v0.9.2 Workflow: wire the model-facing workflow tool and run driver

[Hmbown]

Problem

This started as the v0.8.68 entrypoint/wiring issue: the workflow runtime
crates compiled and tested, but the TUI exposed no model-facing workflow
tool, no normal user path led from a model turn into a workflow run, and the
JS-authoring -> typed plan -> sub-agent execution -> bounded events -> TUI run
view bridge was missing. Since then most of that bridge has landed on main
(evidence below). What remains of this lynchpin for v0.9.2 is the telemetry
and boundedness half of the original scope: per-worker usage telemetry in the
run event stream (which #4039 needs to render Tokens/Tools columns without
scraping transcripts), and bounding the run-record payloads the tool returns
to the parent transcript. Per the maintainer cutline decision (2026-07-17),
this issue moves to v0.9.2 together with #4175, #4177, #4178, and #4179;
landed groundwork stays (#4297, #4299, #4300, #4306, #4307, #4325).

Current evidence

Shipped (verified on main, workspace version 0.9.1):

• Tool registration: crates/tui/src/tools/registry.rs::with_subagent_tools
  registers WorkflowTool unconditionally alongside AgentTool and the
  agents/* coordination tools — no feature flag needed.
• Tool surface: crates/tui/src/tools/workflow.rs::WorkflowTool with actions
  start/run/status/cancel (parse_workflow_action), sources
  script/source_path/plan (workflow_source), fleet, token_budget,
  wait, verify. read_workflow_source_path confines source_path to the
  workspace unless trust_mode, so workflows/*.workflow.js runs work.
• Run driver: SubAgentWorkflowDriver in the same file bridges each VM
  task(...) to crates/tui/src/tools/subagent/mod.rs::spawn_workflow_task
  — one delegation axis, no revived agent_swarm (the /swarm-style entry
  the 2026-06-12 Kimi audit comment warned about does not exist; entry is
  /workflow -> workflow tool, matching that guidance).
• JS VM: codewhale-workflow-js (WorkflowVm, WorkflowDriver trait,
  WORKFLOW_MAX_CONCURRENT = 16 in crates/workflow-js/src/lib.rs).
• Events: WorkflowUiEventKind (run_started/phase_started/task_started/
  task_completed/gate_updated/handoff_promoted/budget_updated/...) flows as
  Event::WorkflowUi (crates/tui/src/core/events.rs, v0.9.0 2.5: route workflow events to panel and compact history card #4122) into
  crates/tui/src/tui/tool_routing.rs::apply_workflow_ui_event -> WorkflowPanel
  and history cards.
• Approval posture: crates/tui/src/tools/workflow_plan_approval.rs (v0.9.0 2.9: add approval card for elevated Workflow plans #4126)
  with durable plan_approval receipts on the run record;
  codewhale_config::WorkflowConfigToml (crates/config/src/lib.rs).
• Persistence: .codewhale/workflow-runs.jsonl journal
  (crates/tui/src/tools/workflow.rs::journal::WorkflowWorkspaceState),
  hydrated across tool-registry rebuilds.
• Entrypoints: TUI /workflow [objective|status|cancel <run_id>]
  (crates/tui/src/commands/groups/core/workflow.rs); CLI
  codewhale workflow run (crates/cli/src/lib.rs::run_workflow_command,
  v0.9.1 Phase 2: Workflow steps reference Fleet roles (not raw prompts/profiles) #4177/v0.9.1: Stopship workflow as fleet-backed lane (dogfood #4090/#4093/#4094) #4178) and the hidden Lane dispatcher codewhale-tui workflow-tool
  (crates/tui/src/main.rs::run_workflow_tool_command).
• Bare /workflow behavior: the 2026-07-07 comment recorded a 0.8.68-branch
  fix making bare /workflow local-help-only (commit 7ae540204; not in
  main's history). Main supersedes that: bare /workflow is a deliberate
  context-dependent opt-in that authorizes orchestrating the current work
  (test bare_workflow_is_context_dependent_opt_in in
  crates/tui/src/commands/groups/core/workflow.rs).
• Completion gates: crates/tui/src/tools/verifier.rs::run_workflow_completion_gates
  behind the verify flag; lane gates surface as GateStatusLine (v0.9.1 Phase 3: Workflow gates and handoffs between Fleet roles #4179).

Remaining gaps (verified):

• WorkflowUiEventKind::TaskCompleted carries only task_id + status. No
  per-worker token count, tool-call/step count, duration, or artifact handle,
  although the manager already tracks them (SubAgentResult::steps_taken,
  SubAgentResult::duration_ms, AgentRunUsage totals in
  crates/tui/src/tools/subagent/mod.rs).
  crates/tui/src/tools/workflow.rs::completion_from_manager maps the
  terminal snapshot to TaskCompletion status+text and drops usage.
• WorkflowRunRecord.events is an unbounded Vec<WorkflowUiEvent> and
  workflow_result_for serializes the entire record (all events, full
  result, full execution) into the parent transcript on every status
  call and final result — high-fan-out runs bloat the transcript the panel
  exists to protect.

Scope

1. Extend the per-task completion telemetry: add tokens_total (plus
   input/output when available), tool_calls (from steps_taken),
   duration_ms, and an optional result/artifact reference to the
   task_completed UI event, sourced from the manager record in
   completion_from_manager / the driver delivery path
   (crates/tui/src/tools/workflow.rs).
2. Reconcile per-run usage totals into run_completed (aggregate helper
   WorkflowUsage already exists in crates/workflow/src/lib.rs).
3. Bound the model-facing payloads: cap WorkflowRunRecord.events retention
   (summary + bounded tail; the full stream already persists in
   .codewhale/workflow-runs.jsonl) and make workflow_result_for /
   status_workflow return compact summaries with large child output
   retrievable by reference, not pasted inline.
4. Keep WORKFLOW_HANDOFF_MAX_CHARS (4000) handoff compaction and gate
   receipts unchanged; telemetry fields must not alter gate semantics.
5. Update the workflow_panel.rs JSON event parser contract note so v0.9.2 Workflow: background task phase ledger UI #4039
   can consume the new fields (WorkflowPanelEvent::from_json_value must
   tolerate their absence for old journals).
6. Tests: task_completed carries usage for a completed child; run_completed
   totals match the sum; status payload for a simulated 30+ event run stays
   under the cap; journal round-trip with and without the new fields.

Key files

• crates/tui/src/tools/workflow.rs
• crates/tui/src/tools/subagent/mod.rs
• crates/workflow-js/src/driver.rs
• crates/workflow/src/lib.rs
• crates/tui/src/core/events.rs
• crates/tui/src/tui/tool_routing.rs
• crates/tui/src/tui/widgets/workflow_panel.rs

Acceptance criteria

• A model turn can call workflow(...) with source_path pointing at a
  checked-in workflows/*.workflow.js example and the run dispatches
  children through spawn_workflow_task (already true — keep green).
• task_completed events include worker tokens, tool-call/step count,
  and duration; run_completed includes run totals.
• workflow status/final results stay bounded for a high-fan-out run;
  full event history remains available via .codewhale/workflow-runs.jsonl
  and child output via receipts/references, not inline text.
• Existing plan approval, gate, and handoff behavior is unchanged
  (plan_approval receipt still present in result metadata).
• cargo test -p codewhale-workflow and
  cargo test -p codewhale-workflow-js stay green.
• New tests cover telemetry emission, total reconciliation, and payload
  caps.

Verification

cargo fmt
cargo test -p codewhale-workflow
cargo test -p codewhale-workflow-js
cargo test -p codewhale-tui --bin codewhale-tui --locked workflow
cargo test -p codewhale-tui --bin codewhale-tui --locked workflow_panel

Out of scope

• The phase-ledger UI itself (rows, collapse, finished-runs section) — v0.9.2 Workflow: background task phase ledger UI #4039.
• Lane/Fleet runtime residuals (v0.9.1 architecture: Fleet / Workflow / Lane / Runtime product model (canonical tracker) #4175 vocabulary, v0.9.1 Phase 2: Workflow steps reference Fleet roles (not raw prompts/profiles) #4177 role steps, v0.9.1: Stopship workflow as fleet-backed lane (dogfood #4090/#4093/#4094) #4178
  stopship lane, v0.9.1 Phase 3: Workflow gates and handoffs between Fleet roles #4179 gate hardening) — same v0.9.2 cluster, separate issues.
• Checkpoint/resume (v0.9.4 WhaleFlow: agent checkpoint and resume on timeout/interrupt #4011), topology primitives (v0.9.4 WhaleFlow: agent topology primitives (fan-out, pipeline, diamond, speculative) #4012), worktree pools
  (v0.9.4 WhaleFlow: worktree pool management for parallel agent isolation #4016).
• Reviving any standalone agent_swarm tool/card path (v0.8.5 chore(swarm): drop model-callable agent_swarm tool surface #332/v0.8.5: drop /swarm + agent_swarm tools; polish agent_spawn #336 retired it;
  the Kimi audit comment reaffirms: swarm-style entry stays a workflow run
  intent).

Related

• v0.9.0 Workflow: product-readiness tracker #4038 Workflow product-readiness tracker; v0.9.1 Workflow: rename user-facing WhaleFlow surfaces to Workflow #4037 rename (crates are now
  codewhale-workflow/codewhale-workflow-js).
• v0.9.2 Workflow: background task phase ledger UI #4039 phase-ledger UI — consumes the telemetry this issue emits.
• v0.9.4 WhaleFlow: Conductor agent type for orchestrating agent ensembles #4010 v0.9.4 WhaleFlow: agent checkpoint and resume on timeout/interrupt #4011 v0.9.4 WhaleFlow: agent topology primitives (fan-out, pipeline, diamond, speculative) #4012 v0.9.4 WhaleFlow: verification gates (compile, test, lint, review as post-agent hooks) #4013 v0.9.0 Performance: TUI lag and memory pressure from high agent fan-out sessions #4014 v0.9.4 WhaleFlow: context budget management for high-fan-out orchestration #4015 v0.9.4 WhaleFlow: worktree pool management for parallel agent isolation #4016 — architecture follow-ons.
• v0.8.60: Add /swarm as a Whaleflow-backed dynamic multi-agent mode #3178 Kimi-informed swarm-as-workflow slice; v0.8.5 chore(swarm): drop model-callable agent_swarm tool surface #332/v0.8.5: drop /swarm + agent_swarm tools; polish agent_spawn #336 retired agent_swarm.
• v0.9.2 cluster per 2026-07-17 cutline: v0.9.1 architecture: Fleet / Workflow / Lane / Runtime product model (canonical tracker) #4175, v0.9.1 Phase 2: Workflow steps reference Fleet roles (not raw prompts/profiles) #4177, v0.9.1: Stopship workflow as fleet-backed lane (dogfood #4090/#4093/#4094) #4178, v0.9.1 Phase 3: Workflow gates and handoffs between Fleet roles #4179.
• Landed groundwork: feat(workflow): Phase 2 fleet role on steps (#4177) #4297, feat(workflow): Phase 3 gate nodes and lane-scoped handoffs (#4179) #4299, feat(stopship): fleet-backed dogfood path for #4178 #4300, feat(workflow): lane-backed workflow run entrypoint (#4177/#4178) #4306, feat(workflow): enforce role gate handoffs (#4179) #4307, fix(workflow): run documented scripts and harden cancellation #4325.

Triage note: body restructured for agent execution on 2026-07-18; prior
comment refinements folded in. Original wording preserved in edit history.

[Hmbown]

Kimi Code audit note, 2026-06-12:

When wiring Whaleflow into CLI/TUI, the Kimi /swarm lesson is worth folding into the entry-path design: /swarm <task> should become a Whaleflow run intent, not a revived model-visible agent_swarm tool.

Concrete framing:

• CLI/TUI entry creates a workflow_run with BranchSet/Leaf/Reduce shape when swarm-style fanout is useful.
• The run is the visible/control object; child subagents are headless lanes beneath it.
• Manual approval should happen at the workflow/run boundary where possible, while child permissions still flow through the subagent permission policy.
• Do not bring back the old standalone agent_swarm tool/card path that v0.8.5 chore(swarm): drop model-callable agent_swarm tool surface #332/v0.8.5: drop /swarm + agent_swarm tools; polish agent_spawn #336 retired.

Related Kimi-informed slice: #3178.