Files

T

220df14314 feat: add structured foreach back-edge execution

foreach back-edge execution and control-region validation

2026-09-04 19:59:37 +07:00

66 KiB

Raw Blame History

Current Roadmap

This is the live, short roadmap. Completed implementation plans and long slice history live under historical/. Current architecture references:

wf_api_architecture.md: workflow API, server, transport, and source package boundaries.
project_map.md: package map and entrypoints.
wf_cli.md: current CLI usage.

Current Product Shape

wf_cli
  -> local WorkflowApi or wf_transport_rpc_http.RpcWorkflowApiClient
  -> wf_server.WorkflowServer
  -> wf_api.WorkflowApi / admin surfaces
  -> wf_core / wf_artifacts / wf_sources_mcp

The durable product path is now wf-rpc-server plus neutral wf_config / wf_server composition. The old wf-mcp script remains a legacy/special-purpose MCP entrypoint and compatibility surface.

Completed: the async wf_client Python slice is verified against the real JSON-RPC ASGI application and the full repository suite. It covers capability discovery, local graph authoring, remote validation, immutable artifact save, deployment selection, and durable run execution. Rich client objects have bounded, secret-safe repr() and _repr_html_() views that never perform remote I/O. Draft workspaces remain a separate server/admin surface and are not part of the client; server registration is explicit so the artifact -> deployment -> run path does not require draft storage.

Active Initiative: Workflow Console And Defense Demo

The next product-facing push is a local-first web console and defense demo that shows the lifecycle without forcing viewers to read raw JSON. It connects to a loopback wf-rpc-server through JSON-RPC, displays lifecycle records and traces, and runs a prepared lda.chat report workflow with a typed human approval interrupt.

Design contracts:

Implementation order:

Completed: self-describing interrupt request/resume schemas are carried through core execution, persisted run inspection, and resume validation.
Completed: deterministic examples/lda_report_workflow/ case study with local document, report, issue-board sources, and typed issue-review interrupt.
Completed: add a top-level web/ pnpm workspace with a React/Vite console, Hono local server, Effect JSON-RPC boundary, loopback connection flow, source inventory, protocol evidence, and production static serving. Design: workflow console foundation. Implementation: workflow console foundation plan.
Completed: add the generic console lifecycle explorer, exercised first through the artifact -> deployment -> run -> trace path, with interactive graph and raw RPC evidence. Design: workflow console lifecycle explorer. Implementation: workflow console lifecycle explorer plan. Draft workspace inspection reuses the same shell after the first vertical path. Slice 1 is complete: the routed console now provides real-server capability discovery and read-only draft workspace inspection with desktop and mobile acceptance coverage. Implementation: workflow console workspace foundation plan. Slice 2 is complete: the console now provides draft graph authoring through real mutation RPCs, schema-backed capability forms, route editing, validation diagnostics, operation evidence, and responsive graph-first mobile sheets. Design: draft authoring workbench. Implementation: draft authoring workbench plan. Slice 3 is complete: selected capability steps now expose Setup, Inputs, and Outputs editing with canonical whole-list replacement, malformed-row repair gating, truthful graph binding summaries, and mobile mounted-inspector state preservation. Design: selected-step dataflow. Implementation: selected-step dataflow plan. Planned authoring slices, in order:
- Slice 4 is complete: the Discover capability playground resolves self-contained local JSON Schema $ref / $defs references and exposes the existing workflow.capabilities.call operation through a generated input form with typed output, diagnostics, bounded/redacted evidence, and durable inline failure receipts. Direct capability calls are isolated smoke tests, not persisted workflow runs: they create no workflow state, routes, run records, or trace frames. Implementation: capability playground plan.
- The console review remediation gate is complete. The final verified dispositions are recorded in workflow console review remediation.
- Slice 5 is complete: composite input values extend canonical step-input bindings with a deliberate recursive literal/path expression model for arrays and objects. Start by exposing per-item Literal/Path controls in existing array editors, preserving order and schema-validating every element. Do not encode array assembly as synthetic targets such as items.0; retain the current simple path/literal bindings for ordinary fields. Design: composite input expressions. Implementation: composite input expressions plan.
- Slice 6 is complete: workflow contract graph adds selectable Input, State, Output, and Outcomes projections with focused forms for workflow contracts, explicit outcomes, entry point, and final workflow output bindings. One backend-owned, node-scoped authoring contract inventory supplies discoverable input, state, selected-step, and applicable runtime-context choices without high-level hardcoding or raw JSON hunting. The standalone capability playground remains literal-only until it has a real workflow scope. Design: workflow contract graph. Implementation: workflow contract graph plan.
- Slice 7: explicit End authoring and a typed Add step palette. End nodes are real stored steps; Input, State, Output, and Outcomes remain graph projections of workflow-level contracts rather than fake runtime steps.
- Slice 8: typed forms for interrupt, condition/choose/match, subgraph, and foreach/join steps, built on the focused draft operations already exposed by the workflow API.
- Slice 9: direct graph gestures. Typed handles and drag-to-connect lower through the same canonical route and binding mutations used by inspector forms; the graph never owns an independent editable document.
Completed: the web console can operate the prepared examples/lda_report_workflow/ deployment through run start, typed issue_review interrupt, resume, trace, and final output inspection.
Completed: lifecycle autoplay, typed approval, issue-board output, and replay. Design: demo autoplay and replay. Implementation: demo autoplay and replay plan.
Completed: React presentation mode foundation for the prepared workflow demo. Make the report workflow story primary, demote lifecycle evidence to supporting panels, and keep the layout usable on a 720p display. Decision: React presentation mode before Astro. Design: React presentation mode. Implementation: React presentation mode plan.
Completed: constrained demo agent that invokes one prepared recipe macro. This agent driver remains replay-only. A separate presentation runtime added live prepared-run activation in a later slice. Design: constrained demo agent. Implementation: constrained demo agent plan.
Completed: implement the original 12-scene defense storyboard as a no-scroll 720p compositor. Later slices expanded and then consolidated the current deck to 13 scenes. Content and evidence freeze before chat replacement, visual polish, or motion tuning. Design: defense presentation storyboard. Implementation: defense storyboard compositor plan.
Completed: make the workflow execution handoff the visual center of Scenes 9 and 10. The canonical replay now drives an interpreted operation surface, persistent execution graph, typed interrupt contract, and raw evidence drawer. Design: workflow takes the stage. Implementation: workflow takes the stage plan.
Completed: replace whole-stage theme switching with one scalable Editorial Canvas and prove the reusable recursive Interactive Figure through Scene 6. Design: defense presentation storyboard. Implementation: editorial canvas and Interactive Figure plan.
Completed: adapt the logical presentation canvas continuously from 4:3 to 16:9 and replace the resizing evidence drawer with a progress-row receipt and centered inspector. Design: adaptive presentation canvas and evidence inspector. Implementation: adaptive presentation canvas plan.
Completed: address the presentation CodeRabbit review pass covering reducer state semantics, agent approval cleanup, discussion modal accessibility, figure validation, keyboard roving focus, and stale demo agent spec wording. Implementation: presentation CodeRabbit fixes.
Completed: presentation chat uses source-owned AI Elements-style conversation, message, tool, and prompt-action primitives against existing AgentMessagePart / TimelineAgent contracts. Live AI SDK driver remains deferred; the current chat runs the deterministic timeline agent. Implementation: presentation AI chat surface.
Completed: schema approval surface for typed interrupt/resume decisions. Scene 10 and prepared-agent approval requests now render schema/payload approval UI instead of raw { "type": "object" } as the primary product proof. Implementation: schema approval surface.
Completed: presentation chat now drives the prepared workflow timeline. The chat run action, schema approval submit/revision, graph, evidence, and live/replay execution all share useDemoTimeline; AI SDK remains a later driver for the same seam. Implementation: presentation chat timeline bridge.
Completed: guided run beat gates connect Scene 10 schema approval, chat approval, graph focus, and evidence transitions into one deterministic presenter sequence. Implementation: guided run beat gates.
Completed: Scene 10 guided product moment primes replay state for direct hashes and stages approval, resume, output, and trace as one readable product flow. Design: Scene 10 guided product moment. Implementation: Scene 10 guided product moment plan.
Completed: presentation live/replay truth surface distinguishes reviewed replay evidence, live target readiness, live active run state, and replay fallback. Design: presentation live/replay truth. Implementation: presentation live/replay truth plan.
Completed: Scene 10 now presents factual run state: workflow input, interrupt payload, operator resume decision, output, and trace frame facts. The live workflow contract supports a same-run negative outcome; the current prepared revision recording uses a separate run identity and is documented as a factual follow-up. Implementation: Scene 10 factual run state.
Completed: presentation lifecycle story expansion splits the demo climax into prepared lifecycle, run start, typed human boundary, and resume/output/evidence scenes so Draft -> Artifact -> Deployment -> Run is visible before the run inspector details. Design: presentation lifecycle story expansion. Implementation: presentation lifecycle story expansion plan.
Completed: presentation demo proof composition makes scenes 9-12 factual and readable: the workflow graph reflects the prepared plan, approval shows input/interruption/decision only, and resume/output/trace expose scroll-contained proof panes. Implementation: presentation demo proof composition.
Future: presenter companion and defense evidence assets.
Add a static slide/appendix shell only after presentation mode is clear. Astro remains an option, not the default next surface.
Completed: presentation agent authoring story creates a canonical prepared authoring recording, Scene 7 as an authentic single-beat full-screen conversation, and Scene 8 as a 6-beat lifecycle with route-level coverage that never calls workflow authoring RPC operations during Scene 8 navigation. Implementation: presentation agent authoring story.
Completed: compress Scene 10 typed approval and Scene 11 resume/output/trace evidence into a decision-led, continuation-led presentation, and restore live prepared-run activation against the configured JSON-RPC target. Implementation plan: Scene 11-12 evidence and live activation.

Presentation visual audit, July 11:

Baseline-good: Scenes 3, 4, and 5 are good enough for now. Do not churn them unless a later rehearsal exposes a concrete problem.
Completed: Scene 1 introduces the agent-shaped product goal through Planner -> Tool surface -> Runner / platform, then identifies the last role as the implemented contribution. Scene 2 remains responsible for the automation problem. Scenes 2, 6, and 7 retain their concrete focal artifacts, and Scenes 7-9 share a prepared authoring/run spine. Implementation: presentation opening title.
Completed: Scenes 10-11 now use decision-led approval, continuation-led resume/output, and compact factual trace rows so approval, resume, output, and trace remain factual without competing panels or repeated low-signal values. A healthy prepared target remains live; failed health probes switch the presentation back to the offline recording.
Completed: Scenes 12 and 13 now close with a bounded evaluation board, contribution boundary/future-work map, and canonical defense-question index.

Completed: Presentation Recomposition And Authoring Story

Scenes 7 and 8 now present an external-agent request through a scripted presentation surface and factual prepared-authoring proof. Scene 7 is one local request-to-first-turn beat; its obsolete /handoff route fails closed. Scene 8 keeps a persistent prepared assistant pane beside six factual phase visuals in an adaptive approximately 26/74 split. The obsolete receipt/trace modal and lower chat dock were removed. Plans: presentation agent authoring story and Scene 9 assistant pane. The staged message-box completion is recorded in Scene 9 staged message box.

Recommended next visual slices:

Completed: Opening visuals rebuilt Scenes 1 and 2 around concrete diagrams for "AI-agent pursuit -> workflow substrate" and "direct actions are not reusable automation". Design: presentation opening visuals. Implementation: presentation opening visuals plan.
Completed: Presentation coherence pass added a 13-scene visual matrix, corrected Scene 2's direct-action metaphor into a chat/tool transcript, and marked demo beats with primary/support surface metadata so Scenes 7-11 can keep one dominant product proof at a time. Implementation: presentation coherence pass.
Completed: Scene 2 visual craft pass made the one-off side read as a chat/tool transcript and the reusable side read as a durable workflow blueprint, while preserving simple vocabulary and 720p readability. Implementation: Scene 2 tool-loop visual craft.
Completed: guided proof scene composition cleanup made approval, resume, output, and trace beats read as product evidence without chat competing for space. Implementation: guided proof scene composition cleanup.
Completed: Evidence and closing visuals make Scenes 12 and 13 readable as a defense artifact: bounded evaluation board, claim boundaries, future-work map, and canonical examiner-question index. Design: presentation evaluation and closing. Implementation: presentation evaluation and closing plan.
Completed: Presentation agent authoring story rebuilds Scenes 7 and 8 as a scripted surface representing an external-agent handoff and factual prepared-authoring proof. Implementation: presentation agent authoring story plan.
Completed: Scene 1 now introduces the agent-shaped product goal through Planner -> Tool surface -> Runner / platform, then identifies the last role as the implemented contribution. Scene 2 remains responsible for the automation problem. Implementation: presentation opening title.
Completed: harden the live/replay defense rehearsal path with visible live start readiness, submitted and revision-requested outcome evidence, deterministic replay fallback, current deep links, and reset instructions. The live contract is same-run; the prepared revision branch uses a separate recording and is disclosed in the rehearsal log. Implementation: defense presentation rehearsal.
Completed: Scenes 7-9 now use one dominant factual artifact per beat on the Editorial Canvas: authoring/repair evidence, a scripted light agent chat, and a light prepared lifecycle canvas with synchronized secondary chat. Implementation: Scenes 7-9 editorial focal proof.
Completed: revise the remaining visual outliers only when a screenshot identifies a concrete hierarchy, overflow, or factual-readability problem. Implementation: presentation follow-up visual/story pass.

Next: Scene 7–13 Defense Recomposition

The next presentation work is intentionally split into six implementation slices followed by a rehearsal gate. The broader story-flow review remains a separate activity after these surfaces are stable.

Completed: Scene 8 chat entry: replaced the standalone run button with a full-screen assistant-style chat entry. The local composer/send action reveals the first prepared authoring conversation without starting a workflow run. Implementation: Scene 8 chat entry.
Completed: Scene 9 staged message box: kept one message box visible across Discover, Draft, Validate, Artifact, and Deployment; Draft and Artifact Send advance the prepared lifecycle while preserving edited user turns, and Deployment Send records a truthful local run request without execution or RPC. Implementation: Scene 9 staged message box. The boundary is explicit: the compact demo footer may start the prepared run from Scenes 7–11, while Scenes 9–11 own run, decision, resume, output, and trace evidence.
Completed: Live/replay truth and run activation: the compact footer rail across Scenes 7–11 exposes the prepared-run action, retries the existing health probe, starts live execution explicitly, and keeps direct links and failed services on truthful replay evidence. Scene 9 remains the semantic start of execution evidence. Implementation: presentation live/replay activation.
Completed: Scene 11 compression: reduce the typed-human-boundary scene to two beats: interrupt context and approval decision. Cancellation remains a decision outcome rather than a near-duplicate presentation beat. Implementation plan: Scene 11 decision beat compression.
Completed: Scene 10 factual proof and graph composition: the factual graph, selected input files, and proof layout are now implemented. The completed plan is Scene 10 factual graph and proof layout. File-preview rendering remains explicitly deferred as a separate follow-up.
Completed: presentation demo-chrome ownership: Scenes 7–11 share one route-projected footer rail for run, replay fallback, retry, paused, and terminal states. Design: presentation demo-chrome ownership. Implementation: presentation demo-chrome ownership plan.
Completed: visual scale and color pass: removed unwanted blue from Scenes 2 and 13, shorten Scene 2's two-column composition, enlarge the focal diagrams in Scenes 7, 8, 12, and 13, separate Diagnose from Repair visuals, and improve Scene 1 title-box padding and contrast. Design: presentation visual scale and color pass. Implementation: presentation visual scale and color pass plan.
Completed: defense rehearsal gate: all 13 scenes have paired 1280x720 and 1024x768 replay captures, and the rehearsal matrix, log, and story audit are recorded. The live end-to-end path remains blocked, the prepared revision branch has a separate recorded run identity, and the full web test gate passes after route-contract stabilization. Historical implementation plan: defense rehearsal gate. Route matrix: presentation rehearsal matrix; Story-flow audit: presentation story audit; dated evidence: presentation rehearsal log.
Completed: factual input file browser: Scene 9 presents the run-selected documents as a read-only browser with selectable prepared-fixture Markdown excerpts and a separately labelled output destination. The preview states that it is not execution evidence; the UI does not claim per-file reads because the current trace recording does not expose them.
Completed: presentation follow-up visual/story pass: clarified Scene 1 and the lifecycle-to-authoring narrative, gave Scenes 7 and 8 a stronger dominant artifact, made the Scene 9 graph easier to present, and densified Evaluation and Conclusion beats without inventing evidence. The dated review records the remaining factual input-browser, live-E2E, and full screenshot-inspection follow-ups: presentation follow-up visual review. Implementation plan: presentation follow-up visual/story pass.
Completed: presenter speech and live documentation reconciliation. The typed catalog, live runbooks, README, and active contracts use the consolidated 13-scene story. The audience route passed the 1280x720, 1024x768, and 1920x1080 browser gate, including the six-step lifecycle, right-column discussion rail, and optional NodeUse deep link. Implementation: consolidated authoring story.

Presentation wishlist / defense readiness:

Completed: Simpler Speech

Completed: gave every beat one audience goal and one to three anchor terms, then simplified the timed presenter path through Scenes 1-8 to one suggested sentence per beat. Keep essential vocabulary such as Workflow API and lifecycle record names, while moving detailed qualification into optional notes or Q&A. The current catalog contains a 9:27 must-say path with a 500-700 word budget and a 10:42 complete-deck target. Implementation: defense speech simplification.

Completed: Factual Scene 8 Evidence

Scene 8 now presents six factual reviewed evidence variants. Diagnose records missing_outcome_edge at nodes[analyze] in revision 3; Repair records the exact wf draft set-route lda_report_workflow --revision 3 --step analyze --outcome ok --to __end__ command and a valid revision 4 result with zero diagnostics. Direct-hash route assertions cover the Diagnose and Repair beats. Implementation: Scene 8 product evidence.

Design: defense speech and Scene 8 product evidence.

Completed: Distance-Readable Scene 8 Diagrams

Each prepared lifecycle beat now gives its primary meaning to a large diagram: source discovery, one continuous Draft/Diagnose/Repair workflow graph, artifact freezing, and deployment binding. Exact reviewed commands, diagnostics, IDs, and counts remain available as compact secondary receipts. Dagre reserves graph ranks for route-state labels, while React Flow refits after scene-column resize. Implementation: authoring lifecycle diagram pass.

Completed: visual pass for Scenes 6, 7, and 10 fixed architecture figure scale, authoring-loop clarity, interrupt/evidence emphasis, and presenter-note treatment. Implementation: defense presentation visual pass.
Next presentation visual slices:
1. Completed: contrast and readability fix pass repaired dark-on-dark text in the Scene 7 authoring loop and the Scene 10 chat rail, and ignored local .visual-smoke/ screenshots. Implementation: presentation contrast readability.
2. Completed: surface theme normalization pass made light chat, discussion modals, and Q&A branches use the same editorial presentation surface. Implementation: presentation surface theme normalization.
3. Completed: scene composition pass expanded the positioning map, planner/runtime boundary, lifecycle rail, and Scene 10 demo graph/contract readability. Implementation: presentation scene composition.
4. Completed: alignment/layout polish fixed Scene 6 figure dimensions, settled React Flow fitting, Scene 3 chip/evidence collision, narrow chat rail behavior, and Scene 10 smoke route. Implementation: presentation alignment and layout polish.
5. Completed: demo climax craft pass made Scenes 9 and 10 read as one continuous product demonstration from agent handoff, to persisted run, to typed interrupt, to resume/output/evidence. Implementation: demo climax craft pass.
6. Completed: demo product proof layout pass hid chat during graph-heavy beats, kept workflow graph nodes in frame, added run-proof labels inside the graph, and cleared outcome panels below the receipt row. Implementation: demo product proof layout.
7. Completed: demo interrupt layout focus pass made approval/interrupt beats contract-first, reduced the graph to compact context where appropriate, and removed the remaining three-column crowding. Implementation: demo interrupt layout focus.
8. Completed: discussion craft pass replaced detached branch chips with a presenter question rail and rebuilt Q&A modals around answer, provenance, and presenter-note hierarchy. Implementation: presentation discussion craft.
9. Completed: discussion modal composition pass made Q&A and context-only routes stage-aware, with body/support/action regions instead of plain document cards. Implementation: presentation discussion modal composition.
10. Completed: Scene 10 guided product moment primes replay state for direct hashes and stages approval, resume, output, and trace as one readable product flow. Design: Scene 10 guided product moment. Implementation: Scene 10 guided product moment plan.

Completed: presentation demo proof composition makes scenes 9-12 factual and readable: the workflow graph reflects the prepared plan, approval shows input/interruption/decision only, and resume/output/trace expose scroll-contained proof panes. Implementation: presentation demo proof composition. 12. Completed: hardened the replay/live evidence handoff so the trace beat consistently renders canonical frames without stale or empty state. Implementation: presentation evidence handoff.
Completed: deck hierarchy pass gave Scenes 1, 2, 6, 7, 8-12, and 13-14 one focal artifact per beat, reused factual authoring/demo projections, kept one editorial canvas, and froze Scenes 3-5. Implementation: defense deck hierarchy pass.

Presenter runbook: defense presentation runbook covers exact URLs, keyboard controls, live RPC/demo fallback steps, story spine, timing, and short speaker notes for what to say if the live demo fails. defense speech and claim audit provides the current 9:27 speech plus navigation buffer, evidence qualifications, and prioritized 12-minute Q&A. Completed: defense story reweighting now provides a typed 39-beat presenter-note catalog, a 500-700-word must-say path, evidence warnings, and a 10:42 complete-deck timing contract. Completed: interactive graphs and Scenes 3-6 choreography adds restrained Scene 3-5 choreography, a semantic-zoom architecture map, the readable wf_core and NodeUse figures, and a factual prepared-run graph inspector. Completed: read-only presenter route provides a static speech, evidence, timing, fallback, and Q&A reader without RPC, replay, or audience-window synchronization.
Defense Q&A branch set: defense Q&A runbook collects answers for "Where is the AI agent?", evaluation validity, security boundaries, demo reliability, and other likely examiner questions. Completed projection into /present discussion branches: defense Q&A branch projection.
Chat surface replacement: make the prepared demo agent feel operable from a real chat surface, not from custom slide chrome. The chat should own the "run prepared agent" affordance, render tool calls/results with a standard modern AI-app vocabulary, and expose approval requests as normal chat events that can also drive presentation actions.
Completed: guided run beat gates connect Scene 10 schema approval, chat approval, graph focus, and evidence transitions into one deterministic presenter sequence. Implementation: guided run beat gates.
Completed: Scene 10 guided product moment removes delayed direct-link readiness and gives approval, resume, output, and trace one dominant proof surface each. Design: Scene 10 guided product moment. Implementation: Scene 10 guided product moment plan.
Completed: presentation lifecycle story expansion makes the demo climax less run-only by adding explicit prepared lifecycle scenes before the run, interrupt, output, and trace proof. Design: presentation lifecycle story expansion. Implementation: presentation lifecycle story expansion plan.
Evidence assets and rehearsal timing: prepare fallback screenshots/recordings, expected run states, and a timed walkthrough checklist for a 15-minute defense.
Completed: LAN presentation synchronization pairs /present and /presenter through an ephemeral bidirectional room with uniform code/QR/URL pairing, revision-ordered location updates, reconnect behavior, and explicit presenter termination. Public-internet TLS is not part of the first slice: LAN presentation synchronization design. Implementation: LAN presentation synchronization plan.

Boundaries: this is not a production admin panel, generic visual workflow editor, scheduler, external Google Drive/mail integration, or benchmark evidence for free-form autonomous planning.

Priority 1: Product Smoke And Status UX

The platform is usable enough to test as a product. Next work should focus on clear operator feedback before adding more architecture.

Completed: wf status is a compact read-only target/server status command, including durable run counts and the latest run summary when available.
Completed: a real CLI smoke pass against wf-rpc-server --config wf.config.json is captured in 2026-06-09 product smoke RPC CLI.
Completed: wf artifact inspect now accepts --version as an alias for the positional version argument.
Completed: wf artifact delete <artifact_id> <version> --confirm deletes unreferenced artifact versions and rejects versions still referenced by deployments. Implementation: wf artifact delete.
Completed: wf draft delete <workspace_id> --confirm exposes existing draft workspace deletion as a safe CLI command. Implementation: wf draft delete CLI/RPC.
Completed: bounded RPC CLI smoke runbook with cleanup commands: RPC CLI smoke runbook.
Completed: automated RPC CLI smoke example: RPC CLI smoke example.
Completed: cap call output is safer for humans through compact/text modes without changing default JSON semantics. Implementation: cap call output safety.
Completed: raw JSON/YAML workflow plans can be turned into artifacts through JSON-RPC and wf artifact create-from-plan, allowing agent/evidence harnesses to use the product-facing CLI path.
Completed: the opencode browser-click challenge harness is local-first via wf --config examples/browser_click_workflow/wf.config.json --local, with optional --start-server / --server-url modes for JSON-RPC-path trials.
Completed: focused draft edit helpers are exposed through RPC/CLI, and wf deploy create is accepted as an alias for wf deploy save. Docs now distinguish draft shape from raw plan shape for agent authoring.
Completed: capability-free draft lifecycle authoring now spans the Python API, JSON-RPC, remote client, and wf CLI. Callers can create an empty revisioned workspace, set its entry point, and replace whole workflow schemas or outcomes without RFC 6902 patches. Implementation: draft workspace lifecycle authoring.
Completed: semantic draft edits now gate workspace and capability preflight on the expected revision, so stale callers consistently receive revision_conflict while the patch path retains its mutation-time race guard. Implementation: draft semantic revision precedence.
Completed: focused draft bind and capability-step insertion now preserve nested node-local paths and project nested capability schemas through one shared bounded JSON Schema path module. CLI and agent guidance distinguish rooted bind endpoints from implied rootless map targets. Implementation: nested local draft bindings.
Completed: wf draft set-input and wf draft set-output now accept --merge, preserving existing bindings when agents split map edits across multiple revisions.
Completed: wf schema now lists workflow document/component models, emits compact JSON outlines for agent discovery, and emits valid self-contained JSON Schema with --verbose.
Completed: wf draft bind --from ... --to ... composes input/state/output schema projection with step binding merge, replacing the prior narrower output-to-state helper and reducing manual draft patch repairs in agent challenge runs.
Completed: draft CLI vocabulary now uses wf draft create --capability and the typed wf draft add <kind> command tree. All nine draft step kinds have dedicated commands; capability insertion retains schema projection, while interrupt and subgraph commands preserve their explicit boundary contracts. Generic insertion is exposed through Python and JSON-RPC with atomic incoming and outgoing route wiring. Implementation: generic draft step authoring.
Completed: wf draft branch and wf draft handle provide atomic route editing for existing draft steps without rewriting the full routes object.
Completed: wf draft compile returns the compiled raw plan plus required capabilities without mutating or saving the draft workspace.
Completed: draft validation now preserves structured core validation issues and adds exact wf draft bind repair hints for missing state fields.
Completed: wf explain now covers draft/workflow validation codes such as unknown_edge_destination, invalid_source_path, and patch_invalid. Implementation plan: draft explain diagnostics.
Completed: draft workspaces can persist invalid intermediate route states, allowing agents to add missing target steps before final validation/save. Implementation: invalid intermediate draft authoring.
Completed: draft workspaces expose focused remove commands for routes, steps, and step bindings so agents can recover from bad edits without raw JSON Patch. Implementation: draft remove commands.
Completed: wf draft set-workflow-output and full-stack API/RPC/CLI support for editing top-level workflow output bindings. The compatibility map adapter remains available for existing callers. Implementation: set-workflow-output API/RPC/CLI.
Completed: canonical workflow-output replacement now preserves ordered path/value bindings across Python, JSON-RPC, MCP, and CLI; nested input/state sources can project missing output schemas, while literals and context.* require declared targets. Empty replacement restores implicit same-name state fallback; compatibility --merge --map remains intentionally lossy. Implementation: atomic workflow output bindings.
Completed: compatibility map merges now reject canonical input/output bindings they cannot preserve, and local or remote CLI users can export an exact draft document and revision-check its import into an existing workspace. Structurally valid imports receive fresh semantic diagnostics and remain repairable when invalid. Implementation: safe compatibility merges and draft document transfer.
Completed: challenge-driven output UX polish makes set-workflow-output project missing top-level output schema fields from declared input.* and state.* sources, and challenge prompt templates now always include ux_issues_found: [] so debug-profile reports do not fail by omission.
Completed: wf draft bind now reuses existing workflow input/state schema fields when binding to step-local inputs, avoiding redundant-schema failures found by debug challenge runs. Implementation: idempotent draft bind inputs.
Keep status read-only; do not mutate registry, auth, config, or stores.

Priority 2: Durable Run/Resume Hardening

The v1 durable run and resume path exists, including persisted interrupted runs, bounded trace reads, dependency revalidation, and process-rebuild resume tests. Remaining hardening should focus on correctness under real server use.

Completed: same-process resume_run calls are serialized per run id. Implementation: resume run concurrency guard.
Completed: store-level locking/transaction expectations are documented for current file stores and future transactional stores: store transaction boundary.
Completed: paged wf run list exposes compact persisted stopped-run summaries without trace or checkpoint state. Implementation: run list API/RPC/CLI.
Preserve existing semantics: broken pinned dependencies return blocked readiness and diagnostics; ordinary live tool/source failures are failed runs, not implicit pauses.
Active specs:
- persisted run/resume contract
- durable workflow runs and resume

Priority 3: Source/Auth/Config Polish

Source registry, neutral MCP source config, role-specific stores, and local/dev auth admin are implemented. The next work is polish, not new broad surfaces.

Keep config bootstrap separate from mutable store-backed source registry state.
Keep auth payload values write-only; display summaries must show metadata and payload keys only.
Keep role-specific stores filesystem-only until a real SQL/secret-manager slice is planned.
New source families should follow the generic runtime source lifecycle rather than being forced through MCP ConnectionConfig: runtime source lifecycle.
Completed: static config kind: "python" sources can load trusted local NodeSpec registries and expose them through WorkflowServer. Implementation: static Python sources.
Completed: wf config validate preflights neutral workflow config files, including config-relative path resolution and trusted static Python source imports. MCP sources are shape-validated only; live upstream checks remain a server/status concern.
Completed: Python source operator docs and RPC integration coverage now prove ops.py source config, capability call, draft artifact creation, deployment, and workflow run. Runbook: Python source.
Completed: static source inventory providers now have an explicit WorkflowSourceProvider.load_sources() seam in wf_server, and Python source loading is behind PythonSourceProvider.
Completed: wf --local --config <workflow-config> now composes configured neutral server sources in-process instead of falling back to built-in static sources only. --local is process-local server composition, not local-only source transports or shared in-memory source sessions.
Completed: server startup policy moved to wf_server.cli; JSON-RPC HTTP remains in wf_transport_rpc_http: server CLI and transport boundary.
Next auth work: typed/discriminated auth records and source-owned auth binders (McpAuthBinder first) are now completed. Remaining: Google Drive MCP smoke through https://drivemcp.googleapis.com/mcp/v1 (manual/local-only, requires Google OAuth client credentials). OAuth refresh-token support and provider profiles are now implemented. Production secret manager integration and encrypted-at-rest file format remain deferred.
Completed source auth diagnostics: wf source diagnose <source_id> now reports transport/auth/catalog state without exposing secret payloads.
Completed source provider docs: docs/source_provider_guide.md now covers MCP HTTP, MCP stdio, Python sources, auth refs, OAuth refresh-token setup, diagnostics, and the Google Drive MCP caveat.
Completed platform source policy: documented fixed-id sources such as wf.std and wf.source are platform sources. They resolve by fixed source id, do not require self-bindings, and legacy explicit self-bindings such as wf.std=wf.std are accepted as no-op compatibility. Deployment validation still rejects non-self platform-source bindings as stale configuration. Other wf.* namespaces are described by their own source docs/policies.
Completed wf.source.read_resource: resource refs are inert pass-by-value data using logical_source; explicit platform helper nodes dereference them through runtime/platform context with bounded output.
Completed source inventory CLI polish: wf source resources and wf source prompts list source-owned resource/prompt names without fetching content.
Active specs:

Priority 4: MCP Package Split Finish Line

wf_sources_mcp now owns upstream MCP source implementation pieces: ids, registry DTOs, auth/catalog stores, discovery/catalog DTOs, SDK adapter/facade, runtime pool, schema helpers, tool events, wrappers, and adapter lookup.

Next split work should be selective:

Avoid new dependencies on the combined wf_mcp facade from durable server or transport packages.
Keep wf_mcp compatibility shims until callers are retired deliberately.
Move only pieces with clear package ownership. Do not move proxy/UI/App metadata support into workflow transports by accident.
MCP UI/App metadata remains source/proxy metadata only; do not advertise MCP Apps/widget support through durable workflow transports yet.

Priority 5: Runtime/Core Polish Later

Core runtime foundations for native subgraphs, concurrent foreach, lineage state, and durable stopped-run resume exist. Return here after product/server UX is stable.

Native subgraph polish: optional per-use-site child deployment overrides and clearer child trace inspection.
Proposed follow-up: replace innermost-only foreach values with same-scope structured runtime context, including typed Python lookup, graph paths, schema analysis, authoring refs, and explicit subgraph input boundaries.
Proposed runtime guard: add a persisted, run-wide step budget for valid graph cycles that cannot be proven terminating during validation.
Next, reuse the foreach barrier/lineage machinery for fork/gather. The proposed control semantics are recorded in ADR-0006.
Protocol-native progress: investigate MCP tasks/progress or WebSocket/SSE only after polling wf run watch proves insufficient.
OpenAPI sources: continue from openapi capability sources when a real non-MCP source is needed.

Recently Completed Platform Milestones

Completed: the composed Python OpenRPC contract now has a checked, transport-neutral manifest with a deterministic drift gate. Design: workflow contract manifest design. Artifact: workflow-api.manifest.json.
Completed: @lda/workflow-rpc generates all 70 wire operation names plus raw parameter/result types from the checked manifest. The generated artifact has its own deterministic drift check and proves the 16 authored Effect RPCs are a subset without broadening browser authorization.
Completed: a fail-closed representative JSON Schema-to-Effect translator handles constrained primitives, objects, arrays, anyOf, local references, and structurally guarded recursive synthetic schemas, with representative checked-manifest coverage. Unsupported union and conditional semantics remain typed translation failures. No runtime RPC or browser authorization behavior changed; runtime TypeScript parity is not complete.
Completed: a test-only parity harness translates all 32 payload/result sides of the 16 authored Effect RPCs. Health, sources, artifacts, deployments, and run-list fixtures agree; eight bidirectional result mismatches are pinned for the current representative run inspect/start/resume interrupt fixtures and the compact run-trace envelope/frame shape. No runtime decoder or browser authorization behavior changed.
Completed: all 16 current Effect RPCs now use generated runtime decoders from the checked manifest. Run inspect/start/resume use the complete persisted interrupt contract; run trace uses the full run envelope and canonical frame identifiers. The checked generator embeds only those operation schemas and reachable components, and a 64-container guard rejects adversarial request or response nesting before recursive JSON decoding. The authored browser allowlist remains unchanged.
Completed: duplicated Effect-client operation-name unions and guards now come from the authored operation metadata registry, with every name checked against the generated 70-operation inventory. The Hono browser proxy retains an independently authored, typed 16-operation allowlist so future client expansion does not broaden browser authorization implicitly.
WorkflowApiSurface is the protocol-neutral workflow operation contract.
wf_transport_rpc_http exposes local/static and MCP-backed WorkflowServer over JSON-RPC HTTP.
wf can target local or remote workflow APIs for capability discovery, draft authoring, artifact/deployment operations, run, inspect, bounded trace, resume, and cap call.
Desired source registry reads, mutations, and explicit apply/reload are exposed through JSON-RPC and CLI.
Neutral wf_config can express MCP sources, role-specific filesystem stores, and client/server target separation.
wf config migrate-mcp converts legacy broker configs to neutral workflow config without mutating the original.
McpRuntimePool is shared for stateful upstream MCP operations and has JSON-RPC E2E coverage proving session reuse across workflow runs.
wf run watch provides polling-based progress UX.
CLI expected errors are compact by default; wf --verbose ... preserves raw tracebacks for debugging.
Completed thesis case-study evidence bundle: examples/report_workflow/ provides a deterministic report workflow with Python source, fixture input, config, runbook, and tests.
Completed thesis system-design draft: docs/thesis/system-design-implementation.md now frames the platform as a formal system design/implementation report backed by docs/thesis/evidence-index.md and the report-workflow case study.
Completed supplemental browser-click workflow example with serial multi-node lifecycle evidence.
Completed: an opencode browser-click challenge harness captures external agent trials against the deterministic browser-click workflow example without changing product runtime code. The old staged-server modes were replaced by per-trial local configs in the generic V2 harness.
Completed: skills/, runbooks, and challenge prompt templates are treated as the agent instruction layer. Challenge reports now track when trials rely on product code, prior stores, adjacent attempts, or existing example solutions.
Completed: workflow/CLI agent instructions now form an explicit copyable bundle for controlled challenge profiles, use wf schema for public shape discovery, and avoid implementation/test-file guidance.
Completed: the generic agent challenge harness now supports data-driven manifests, layered prompts, explicit none|skills|all|debug profiles, one-hour hard ceilings, normalized OpenCode tool/token evidence, policy findings, and manual-audited reports. Two data-driven challenges exist: browser-click and report-workflow. The central run_trials.py runner accepts any challenge manifest. The debug profile is opt-in and captures evidence-backed UX issue reports separately from normal benchmark scoring.
Completed: report projections generate bounded Markdown and JSON reports for every V2 trial and regenerate both after audit without mutating raw evidence. Implementation: report projections.
Completed: challenge trial collection now supports bounded concurrency through run_trials.py --concurrency and a Python matrix runner, examples/agent_challenges/run_matrix.py. The PowerShell matrix helper now delegates to the Python runner.
Completed: shared agent challenge evaluation runbook documents trial execution, instruction profiles, manual audit, and the distinction between evaluation validity and policy coverage: agent challenge evaluation.
Completed: challenge matrix operations now have compact OpenCode thread titles, policy handling for canonical skill-document reads, and a central summarize_trials.py command for audited result tables.
Completed: agent challenge results now record OpenCode session metadata and resume commands, so incomplete provider runs can be continued without mutating original raw evidence.
Completed: canonical TOML path strings are the emitted workflow path form. Paths now serialize as "input.text", "state.echoed", and "message" (local). Structural {"root": "input", "parts": ["text"]} path objects remain accepted and are now advertised in generated schemas as an input form.
Completed: challenge-driven CLI UX fixes now provide exact available deployment binding suggestions, reject bare --bind-output state targets before RPC with compact guidance, and accept wf schema --full as an alias for --verbose.
Completed: wf draft bind with --from local.x --to output.y now lowers through state atomically (projecting into both state_schema and output_schema), and validation repair hints cover undeclared workflow input source paths. Implementation plan: bind repair hints.
Completed: capability-backed draft creation now auto-binds required inputs only; optional inputs are surfaced in wrapper-hint notes for explicit binding. Implementation plan: required-only wrapper inputs.
Completed: wf draft set-input rejects local.x targets before RPC and shows the equivalent bare-target mapping.
Completed: wf draft add capability --route errors include declared outcomes and direct add/remove repair guidance.
Completed: repeated idempotent wf draft bind input/state -> local behavior is covered by regression tests.
Completed: capability-aware canonical step-input replacement now supports structured assembly, literals, explicit null, fan-out, whole-payload projection, local/remote CLI modes, JSON-RPC, and MCP. Compatibility map merge remains available but intentionally lossy. Implementation plan: atomic step input bindings.
Completed: capability-aware canonical step-output replacement now preserves ordered repeated-source fan-out, projects missing state schemas atomically, and is available through Python, JSON-RPC, MCP, and local/remote CLI modes. Compatibility map merges remain available but inherently lossy. Implementation plan: atomic step output bindings.
Completed: capability-step creation now accepts metadata and ordered path/literal inputs, while focused presence-aware updates can clear selected metadata or atomically replace canonical inputs without changing use, routes, or outputs. Python, JSON-RPC, MCP, and local/remote CLI surfaces are aligned. Implementation plan: capability step updates.
Completed: foreach bodies now return through validated back-edges to their immediate owner, with unique static control regions and fresh persisted activation identities for every dynamic visit. Design: foreach back-edge design. Fork/gather remains explicitly deferred.

Agent evaluation cohort status and policy:

Treat trials collected while product code, prompts, fixtures, harness logic, or workspace isolation were changing as formative evaluation. Preserve them as qualitative evidence linking observed agent failures to product/harness fixes, but do not pool their timing, token, or success metrics with a frozen cohort.
Completed: the primary longitudinal campaign now has N=3 per cell / 36 manually audited trials across two challenges, two models, and none|skills|all profiles. The explicit cohort manifest, aggregate Markdown, and SVG/PDF figures live in docs/thesis/.
The 36 trials span repository snapshots and a base-prompt change before the third wave. Treat the aggregate as longitudinal product/prompt engineering evidence, not as a frozen model comparison or causal profile experiment.
Keep product code, challenge prompts, supplied skill bundle, model variants, timeout, concurrency, fixtures, and enabled tool set fixed if a future controlled cohort is collected. Record the product baseline and rendered prompt hashes with every result.
Keep manual audit authoritative for final pass/fail/invalid interpretation. Automatic policy findings remain review inputs, not bespoke exceptions or final benchmark outcomes.

Planned challenge-driven UX follow-ups:

Composite binding and data shaping is now tracked as console authoring Slice 5 above. It covers mixed literal/path arrays as well as the underlying model needed later to map state fields into structured objects such as report.

66 KiB Raw Blame History Unescape Escape