lda-wf/docs/historical/thesis/thesis-outline.md

Thesis Outline

Note: All sections below have been transferred to the formal Big Doc at system-design-implementation.md. This outline is now historical scaffolding; maintain the Big Doc directly.

This is a writing scaffold for a thesis/report about the workflow platform. It should guide the argument; it is not a changelog.

The final document should read like a formal system design and implementation report. Keep detailed command transcripts and long CLI outputs in appendices or linked runbooks; inline chapters should show only the commands/results needed to support the argument.

Core Argument

External LLM agents are useful workflow authors and operators, but durable workspace automation needs a typed execution substrate. Artifacts, deployments, source bindings, validation, runs, traces, and resumability should be owned by the platform, not improvised through raw tool-call loops.

The short version:

The LLM plans. The runtime executes. Source providers expose capabilities. Stores preserve durable workflow state.

Research Question

Primary research question:

How can an AI-agent-facing workflow platform represent, validate, execute, and persist reusable workspace automations while keeping planning separate from deterministic execution?

Product motivation:

How can external AI agents help workspace operators create reusable automations without requiring them to write scripts, while preserving validation, inspection, and durable execution?

Main Contribution

The thesis contribution is a platform architecture, not a new foundation model:

1. typed workflow artifact/deployment/run lifecycle
2. source-provider boundary for MCP, Python, and future OpenAPI sources
3. durable server/API/CLI surface that external agents can drive
4. validation and inspection mechanisms that reduce planner trial-and-error
5. next-action guidance that points an agent toward useful lifecycle operations without replacing validation

Evidence Strategy

Use one representative workspace case study as the narrative spine: a document/report preparation workflow backed by local fixtures and trusted Python sources. The case study should read or receive a small document-like input, extract structured information such as action items or sections, normalize the result, and produce report-shaped JSON or Markdown. MCP-backed sources can be secondary evidence, but the thesis-critical demo should not depend on remote MCP auth, quota, or provider availability.

The case study should exist as a runnable example, not only prose. Target shape: examples/report_workflow/ops.py, input.md, wf.config.json, a short README.md, and commands for config validation, server startup, capability calls, draft/artifact/deployment creation, run, inspect, and trace. The runnable evidence bundle for this case study lives at examples/report_workflow/.

Keep the thesis-critical path deterministic. Do not require an LLM call inside the case-study workflow. LLM nodes can be discussed as future work or an optional variant, but the evidence path should be reproducible without model credentials, cost, or output variance.

Prefer typed report JSON as the primary output, with Markdown rendering optional later. A useful output contract is:

{
  "title": "Weekly Project Update",
  "summary": "...",
  "action_items": [
    {"owner": "Alice", "task": "Prepare demo config", "due": "Friday"}
  ],
  "risks": ["..."],
  "followups": ["..."]
}

This makes schemas and validation visible in the case study.

Use CLI lifecycle commands for the thesis narrative because they demonstrate the agent-operable surface. Tests may seed RawWorkflowPlan objects directly when that makes assertions tighter, but the case-study runbook should show config validation, server startup, capability inspection/call, draft or artifact creation, deployment save/validate, run start, run inspect, run trace, and run list.

Support that case study with platform evidence: automated tests, CLI/server smoke runs, source-provider examples, run persistence/resume checks, source drift producing unrunnable deployments, stateful MCP session reuse, and a small failed-attempt case study showing how validation/diagnostics reduced blind retries.

Do not frame the evaluation as a broad user study unless that study actually exists. The evidence claim is that the prototype demonstrates the architecture and workflow lifecycle under controlled examples.

Do not make runtime throughput a central claim. The project targets planner efficiency and operational clarity: fewer blind retries through typed contracts, validation, diagnostics, compact outputs, and traces. Performance optimization is future work unless backed by explicit measurements.

Working Title

Safer current title:

Design and Implementation of lda.chat: Infrastructure for AI Agents to Author and Execute Workspace Workflows

Aspirational product title:

Design and Implementation of lda.chat: An AI Agent Platform for Authoring and Executing Workspace Workflows

Use the safer title if the thesis must describe exactly what exists today: external agents such as Claude Desktop and OpenCode can drive the platform, but lda.chat does not yet bundle its own autonomous agent brain. Use the aspirational title only if the thesis explicitly frames lda.chat as the platform intended to host or serve AI agents, not as a completed built-in agent.

1. Problem Statement

Current agent/tool systems often let the LLM directly orchestrate side effects through ad hoc tool calls. This creates practical problems:

• weak validation before execution
• poor resumability after interruption or process restart
• hard-to-audit tool-call traces
• limited reuse of successful procedures
• unclear boundaries between planning, execution, and provider-specific state

The thesis should frame the platform as a response to those pressures.

The automation target is reusable workspace procedures, not arbitrary office work end-to-end. Examples include document transformation, data collection, tool/API calls, report preparation, monitoring checks, and scheduled workspace operations.

2. Thesis

The proposed model is a prototype platform for AI-assisted work:

• workflows are typed graphs
• source capabilities are exposed through explicit contracts
• deployments bind logical source requirements to concrete sources
• runs are durable stopped records
• clients interact through stable APIs/transports rather than direct runtime internals

Natural language belongs in the authoring loop: a workspace operator can express intent to an external LLM agent, but the reusable output should be a typed workflow artifact and deployment rather than an opaque prompt transcript.

Be explicit about actors:

• the workflow owner wants to see useful workflow runs and outputs
• the external LLM agent may be the one driving CLI/API operations
• the developer/operator configures sources, secrets, server processes, and trusted Python code

The CLI should be described as agent-operable first and human-usable second. Its structured output, status/inspect/list commands, validation commands, compact summaries, and guarded destructive actions make it a practical surface for external agents.

This is not a claim that LLMs cannot operate tools. It is a claim that durable, inspectable, reusable work benefits from a separate execution substrate.

Use “prototype platform” deliberately. The implementation proves the core lifecycle and architecture, but it is not yet a finished product with scheduling, visual workflow editing, production secrets, general fork/gather, and broad real-world evaluation.

Next actions and repairable validation failures should be framed as machine-client UX. Human interfaces use buttons and affordances; an agent-facing API needs compact structured hints, stable diagnostic fields, and suggested next operations so an LLM agent can recover without blind probing.

3. Design Goals

The design goals should be stated early and then revisited in evaluation:

• deterministic execution
• validation-centered lifecycle for LLM-authored workflows
• typed inputs, state, outputs, and node payloads
• explicit source binding
• platform sources with fixed process-provided identities, separate from configured workspace/account sources
• scoped workflow portability through artifact requirements and deployment binding contracts
• durable artifacts, deployments, and stopped runs
• inspectable trace slices
• reviewable lifecycle points for drafts, deployments, runs, diagnostics, and guarded destructive actions
• resumability after interruption
• transport neutrality for CLI, server, and future UI/MCP clients
• source-provider extensibility for MCP, Python, OpenAPI, and future families
• source-provider correctness, especially for external systems whose tools, resources, prompts, or authentication depend on initialized stateful sessions

Auth should be described as prototype source-readiness plumbing, not a completed production secret system. The implementation includes typed auth records, OAuth refresh-token support, source auth diagnostics, and MCP auth binding. This is enough to show how credentials participate in source readiness and diagnostics, but encrypted-at-rest storage, production secret-manager integration, and broad provider verification remain future work.

4. Positioning And Related Systems

Keep this section short and category-oriented. The goal is to position the system, not to claim full feature parity with mature platforms.

Compare against:

• direct LLM tool orchestration: flexible but weak durability and validation
• generated scripts: simple and maintainable for some tasks, but lifecycle affordances are manual
• Zapier/RPA/workflow automation platforms: mature integrations and scheduling, but less agent-native typed authoring/repair flow in this prototype's terms
• LangGraph-style agent graphs/durable agents: adjacent durability ideas, but a different emphasis from source-provider-backed reusable workspace workflows
• MCP: useful protocol for tools/resources/prompts, but not itself the workflow artifact/deployment/run lifecycle

5. Architecture

Explain the active package boundaries:

wf_cli
  -> wf_transport_rpc_http
  -> wf_server
  -> wf_api
  -> wf_core / wf_artifacts / wf_sources_*

Important layers:

• wf_core: deterministic workflow kernel
• wf_authoring: authoring support for NodeSpec, drafts, wrappers, API surfaces, source providers, and MCP/admin tools
• wf_api: application surface for capabilities, drafts, artifacts, deployments, runs, and admin/source operations
• wf_server: durable server composition boundary
• wf_transport_rpc_http: JSON-RPC-over-HTTP transport
• wf_sources_mcp: MCP upstream source implementation and persistent runtime
• wf_sources_python: trusted in-process Python source loading
• wf_mcp: legacy/special-purpose MCP compatibility package

Use package names as implementation evidence, not as the main argument. The conceptual architecture should lead: workflow core, platform domain, workflow API surface, server/transport composition, and source providers. Package names then show how those concepts were implemented in this codebase.

The thesis should explain why the old “everything in MCP” shape was split: transport, source provider, workflow API, and runtime concerns are different.

Architecture spine:

• workflow core: deterministic execution semantics for graph, state, outcomes, trace, and resume rules
• platform domain: artifacts, deployments, runs, stores, sources, binding contracts, validation, and admin concepts
• workflow API surface: lifecycle operations exposed to clients
• server/transport composition: concrete stores, sources, runtimes, and communication mechanisms

JSON-RPC is an implementation of the Workflow API Surface. It should not be presented as the product boundary or as the place where workflow semantics live. wf_server is composition: it assembles concrete stores, sources, runtimes, and admin surfaces into a long-lived service. It should not own workflow semantics. wf_authoring is support infrastructure used by drafts, API surfaces, source providers, and MCP tools; it is not a fifth runtime/product layer. If MCP is discussed, distinguish upstream MCP sources from a future client-facing MCP frontend. The former exists as a source family; the latter should not be claimed as a completed clean platform surface.

MCP is an important source-provider case study, not the product identity. It demonstrates why source-provider correctness matters: a source may require persistent sessions, auth context, catalog refresh, resources, and prompt inventory. The platform treats MCP as one source family behind the workflow boundary, not as the whole architecture.

6. Workflow Model

Describe workflows as typed graphs:

• input_schema: validates run input
• state_schema: defines workflow memory and reducer behavior
• output_schema: defines final result shape
• NodeUse: invokes named NodeSpec
• edges: route by declared outcomes
• reducers: merge concurrent or repeated writes safely
• interrupts: represent typed external input points
• subgraphs: compose workflows as nodes

Separate lifecycle objects:

• draft workspace: mutable authoring state for agent/user iteration
• workflow artifact: immutable versioned workflow definition
• deployment: binding contract from artifact version to concrete source/runtime context
• run: execution record with status, diagnostics, output, trace, and resumable stopped/interrupted state where applicable

Key distinction:

• outcome controls routing
• output carries business data

The graph model improves the safety posture by making automation structure explicit. Node contracts, source requirements, state writes, outcomes, validation gates, and trace records are visible before and after execution. It does not guarantee safe behavior from provider code, credentials, or external side effects.

Use generated scripts as a serious baseline, not a strawman. Scripts can be simpler and maintainable for many tasks. The platform argument is that reusable workspace automation benefits from lifecycle affordances that scripts do not automatically provide: typed validation, source binding, artifact/deployment separation, run records, resumability, trace inspection, and repairable diagnostics.

Code ends at the source-provider boundary. A workflow can call trusted Python, Playwright, API, MCP, or future LLM capabilities, but those should appear as typed source capabilities. The workflow itself remains an orchestration artifact, not an embedded code blob.

Durability is a contract over time, not just storage. Artifacts, deployments, bindings, run records, and traces preserve workflow intent. Validation against the current source catalog determines whether that intent is still runnable. If a source changes incompatibly and a deployment becomes unrunnable, the system has preserved the contract instead of silently drifting.

Trace claims should be grounded in the current code: run summaries expose trace_count, and clients can request caller-bounded trace slices for debugging. Do not overstate this as production observability, distributed tracing, metrics, or OpenTelemetry support.

7. Source Model

The common boundary is CapabilitySource.

Source families today:

Source	Kind	Role
wf.std	system	built-in workflow nodes and reducers
wf.recipes	system	first-party workflow recipes
MCP sources	connection	upstream MCP tools/resources/prompts
Python sources	python	trusted project-local NodeSpec registries

The thesis should stress that the runtime does not care where a NodeSpec came from. Source-specific behavior belongs in provider packages and server composition.

Use precise vocabulary:

• tools are provider-native operations, such as MCP tools
• workflow capabilities are NodeSpec contracts callable from graphs
• resources are source-owned addressable content; a URI is meaningful only with its owning source
• prompts are source-owned prompt/template inventory; rendering may be stateful

Platform sources such as wf.std and wf.source are process-provided and do not require deployment self-bindings. Configured sources such as MCP, Python, and future OpenAPI sources remain explicit server/operator choices.

wf.source.read_resource is the current explicit dereference helper: workflows pass inert resource refs by value, then the helper resolves the logical source through runtime/platform context and returns bounded text. Prompt rendering is deliberately not a workflow helper yet; keep it in future work unless the thesis adds a concrete graph use case, argument schema, and bounded output policy.

MCP should be presented as one source family and a useful stress test for source-provider correctness, not as the platform identity.

Current provider seam:

class WorkflowSourceProvider(Protocol):
    def load_sources(self) -> Mapping[str, CapabilitySource]: ...

This seam is intentionally narrow: it covers static inventory, not runtime pools, admin/apply, auth, or live health checks.

For MCP, source-provider correctness includes stateful runtime behavior. A workflow capability call should not silently turn a stateful external provider into a fresh one-off client call when provider state is part of correctness.

8. Implementation Vertical Slice

Use the working product path as evidence:

wf config validate
  -> wf-rpc-server --config
  -> wf status
  -> wf source list
  -> wf source resources / prompts
  -> wf cap list / inspect / call
  -> wf draft create --capability
  -> wf draft save
  -> wf deploy save / validate
  -> wf run start
  -> wf run inspect / trace / list

A strong demonstration is the Python source flow:

1. write ops.py with @node
2. configure kind: "python" source
3. validate config
4. start server
5. call local.ops.echo
6. create draft/artifact/deployment
7. run deployment successfully

This shows the source abstraction is not MCP-only.

Use diagrams as first-class explanation, especially Mermaid diagrams that can be rendered by the existing document generation flow. Each major part should have at least one diagram that explains its role and boundaries before code excerpts or package names appear. Prefer diagrams for:

• main architecture spine:

  flowchart LR
    Owner[Workflow Owner] --> Agent[External LLM Agent]
    Agent --> CLI[wf CLI]
    CLI --> Transport[JSON-RPC Transport]
    Transport --> Server[WorkflowServer]
    Server --> API[Workflow API Surface]
    API --> Core[Workflow Core]
    API --> Platform[Artifacts / Deployments / Runs]
    Server --> Sources[Source Providers]
    Sources --> Builtins[Platform Sources]
    Sources --> MCP[MCP Sources]
    Sources --> Python[Python Sources]
  

• layer architecture: CLI/transport/server/API/core/source providers

• workflow core: schemas, nodes, outcomes, reducers, trace, interrupts/resume

• platform domain: draft workspaces, artifacts, deployments, source inventory, validation diagnostics, run records

• lifecycle: draft -> artifact -> deployment -> run -> trace/list/resume

• source resolution: logical source -> deployment binding/platform context -> concrete source/runtime

• source-provider comparison: built-in, MCP, Python, future OpenAPI

• runtime call path: cap call/run -> Workflow API -> source runtime/client

Use source excerpts sparingly. Include small snippets for key seams such as the artifact/deployment/run lifecycle shape, CapabilitySource, the WorkflowSourceProvider protocol, a compact Python source @node example, and selected CLI/JSON responses. Avoid long file listings; the implementation chapter should explain the architecture, not reproduce the repository.

Frame Python sources as trusted developer extensibility. They are useful because project-local code can become typed workflow capabilities quickly, but they are not sandboxed non-programmer plugins yet.

9. Evaluation

Evaluation should use concrete evidence:

• automated tests for workflow core, API, transports, source providers, and CLI
• live smoke test against wf-rpc-server
• durable run/resume tests
• stateful MCP session reuse tests
• MCP source-provider correctness tests covering tools, resources, prompts, and session reuse through the same server path
• Python source workflow-run integration test
• bounded source inventory and resource-read tests, especially to avoid raw provider payload spam
• OAuth refresh-token/auth-binding tests for HTTP MCP sources, with Google Drive MCP treated as manual smoke coverage rather than a regression fixture
• config validation catching import/path errors before server startup
• planner-efficiency checks: validation, source catalogs, compact output, and inspectable errors should reduce repeated blind LLM attempts
• next-action guidance should reduce planner uncertainty before and after validation calls
• attempt-count comparison on representative tasks, for example old interaction traces with many failed attempts versus the current structured lifecycle
• draft-validation and run-failure analysis, especially cases where old session or source assumptions caused repeated failed runs
• source-drift cases where old deployments become unrunnable with diagnostics instead of silently executing against incompatible capabilities
• current agent/tool evaluation with a small repeat count. A practical prototype target is five end-to-end attempts where free or commodity LLM agents try to use the CLI/API surface to complete the deterministic case study. Report pass/fail counts, failure categories, and whether diagnostics were actionable; do not present this as a statistical reliability benchmark.

For the agent/tool evaluation, success means end-to-end completion: the agent creates or selects a valid workflow artifact/deployment and completes a run whose output matches the expected typed report schema and key content. Merely calling a capability, producing a draft, or returning freeform text outside the schema is not success.

Count failures explicitly. Useful categories include:

• config/setup failure
• source discovery or source binding failure
• draft validation failure
• deployment validation failure
• run failure
• output schema/content mismatch
• excessive manual intervention
• agent gave up or looped without progress

Track autonomous and assisted success separately. Autonomous success means the agent completes the task with only the initial prompt/runbook. Assisted success means completion after limited documented help such as confirming that the server is running or pointing at the intended config path. Manual artifact edits, code fixes, or changing the expected output should count as failures for autonomous evaluation.

Avoid vague claims such as “robust” or “production-ready” unless backed by specific checks.

Evidence package:

• architecture/code walkthrough tied to the four-layer model
• automated tests for lifecycle, validation, source providers, persistence, resume, stateful MCP reuse, and Python source integration
• live CLI/server smoke run
• before/after failed-attempt case study from old ad-hoc interaction to structured workflow lifecycle
• explicit limitations and future work

Recommended case study:

• document/report preparation, not an echo demo
• deterministic current sources first, such as Python source text transforms
• optional/future LLM summarization as a typed source capability, not required
• output should be a structured report or Markdown/JSON artifact that a workflow owner would plausibly want
• package the example with fixture input, Python source code, workflow config, store/environment setup, and CLI/server commands

Possible evaluation questions:

• Can a source capability be discovered, called, saved into a workflow, deployed, and run?
• Can an interrupted run survive process restart and resume?
• Can the same server be used through CLI and JSON-RPC transport?
• Can a new source family be added without changing wf_core?
• Are large/raw provider payloads bounded in CLI output?
• Can platform sources such as wf.std be used without self-bindings while configured sources still require explicit bindings?
• Can source resources be referenced by logical source and dereferenced only through an explicit bounded helper?
• Can an external LLM agent converge on a valid workflow without spending most of the interaction on tool-output spam and trial-and-error?
• Does the structured surface reduce failed attempts before success compared to earlier ad-hoc agent/tool interaction traces?
• Do wf draft validate, deployment validation, and run inspection catch or explain the kinds of issues that previously caused repeated failed runs?
• Does deployment validation surface source drift as runnable/unrunnable state with diagnostics rather than silent behavior changes?

9.1 Positioning Against Existing Automation Platforms

The thesis should discuss the space it fits into through multiple baselines: direct LLM tool use, manual scripts, Zapier-style automation platforms, RPA tools, and workflow engines. The goal is not to claim feature parity with mature products. The goal is to explain the trade-off this prototype explores.

Zapier and similar platforms are stronger today at:

• polished non-programmer UI
• large integration catalogs
• hosted scheduling and triggers
• operational maturity

Manual scripts are powerful and often faster for technical users, so the thesis should not dismiss them. The fair comparison is accessibility and adaptability: how much skill and maintenance effort is required before a workspace operator or external agent can turn a repeated task into a reusable workflow?

This prototype explores a different center of gravity:

• external AI agents can drive the authoring/execution lifecycle directly
• workflows are typed graphs with explicit schemas and source bindings
• local Python, MCP, and future OpenAPI sources can share one workflow surface
• runs, traces, artifacts, and deployments are first-class inspectable records

Use the comparison to position the work, not as a claim that the prototype outperforms existing automation products.

10. Limitations

State limitations explicitly:

• Python sources are trusted in-process code; no sandbox yet.
• Python sources are static at server startup; no hot reload yet.
• Source provider lifecycle is early, especially for non-MCP mutable sources.
• Workflow portability is scoped; local Python code, MCP catalogs, auth records, and source stores can differ between environments.
• The prototype has not been evaluated against a broad external provider catalog or a large user study.
• File-backed stores are the current implementation proof for durable lifecycle; durability itself should not be framed as filesystem-specific.
• Auth records/admin surfaces exist as prototype plumbing, but end-to-end production credential handling is not verified as a core thesis claim.
• Run deletion is not implemented.
• MCP widget/resource proxying is not supported; upstream interactive widgets are not carried through the durable workflow path.
• Crash recovery is at stopped boundaries, not arbitrary mid-node checkpoints.
• Offline scheduling is not implemented yet.
• There is no visual workflow editor yet.
• There is no bundled autonomous agent brain.
• General fork/gather workflow control is future work.
• There is no full approval, roles, policy, or multi-user review system.

Limitations make the thesis more credible. They also motivate future work.

11. Future Work

Likely future-work sections:

• provider lifecycle: add/update/remove/apply/reload for multiple source families
• OpenAPI or fetch-style source provider for broader HTTP integration
• Python development reload
• LLM nodes as typed source capabilities
• production auth/secret stores
• SQL/transactional stores
• scheduler/server daemon operations
• offline scheduling for deployments
• fork/gather workflow control
• richer run rewind/time-travel debugging beyond stopped/interrupted resume
• UI/admin dashboard
• first-party workflow UI for listing, inspecting, and editing workflows
• richer evaluation with real workflows and larger source catalogs

12. Conclusion

Restate the core argument: external LLM agents can author and operate workflows, but the durable workflow lifecycle should live in a typed platform substrate. Summarize what the implementation proves: artifacts, deployments, runs, validation, source providers, server/API/CLI surfaces, and reproducible evidence across built-in, MCP, and Python sources.

Appendices

Keep long operational material out of the main argument:

• reproducible command transcript for the case study
• smoke-test commands and abbreviated outputs
• selected config files
• generated workflow/artifact/deployment examples
• test/evidence index

What Not To Do

Do not make the thesis a commit history. The reader does not need every refactor.

Do not over-center MCP. MCP is one source family and one compatibility/frontend area, not the whole platform.

Do not claim unimplemented production properties:

• no Python sandbox
• no general provider hot reload
• no production secret manager
• no full MCP widget passthrough
• no unmeasured performance or production-readiness claims

The strongest version is an honest systems argument:

1. Direct LLM tool orchestration has durability and validation problems.
2. Typed workflows address those problems.
3. The implementation proves the model across local, MCP, and Python sources.
4. Remaining work is clear and bounded.