Implement durable dynamic workflow runs for multi-agent orchestration

[senamakel]

Summary

Create a first-class OpenHuman workflow-run model for repeatable multi-agent orchestration where a saved plan/graph coordinates many subagents, tracks intermediate results outside the main chat context, and can be inspected, stopped, and resumed.

Parent: #3370

Problem

Claude Code's dynamic workflows move orchestration out of the main conversation and into a script/runtime with phases, agent caps, intermediate variables, progress views, and saved commands. OpenHuman currently has spawn_parallel_agents and AgentOrchestrationSession, but not a durable workflow run entity with phases, reusable definitions, approval, progress, and bounded concurrency.

Without this, large audits or cross-checked research either overload the main agent context or collapse too much detail into one tool result.

Implementation plan

1. Define workflow definitions and runs.

   • WorkflowDefinition: id, name, description, input schema, phases, default concurrency, allowed agents/tools, safety tier.
   • WorkflowRun: id, definition id, parent thread, input, status, phase states, child agent refs, token/cost totals, result summary, created/updated timestamps.
   • Start with declarative Rust/JSON phase graphs, not arbitrary JS. Arbitrary script execution is a larger security surface and should wait.

2. Implement one read-only prototype workflow.

   • Suggested first workflow: parallel research with cross-checking.
   • Phases: decompose angles -> spawn researcher agents -> cross-check claims with critic -> synthesize cited report.
   • Keep tools read-only unless the user explicitly chooses an edit-capable workflow.

3. Add controller APIs.

   • workflow.list_definitions, workflow.start, workflow.list_runs, workflow.get_run, workflow.stop, workflow.resume, workflow.save_definition if definitions are user-authored later.

4. Add UI.

   • A Workflows section under the new/background agent command center.
   • Show phase list, agent count, elapsed time, token/cost estimates, stop/resume actions, and drill-down to child agents.
   • Approval card before starting high-cost/high-concurrency runs.

5. Add bounded execution semantics.

   • Concurrency cap defaults should reuse max_parallel_tools or a workflow-specific lower cap.
   • Hard cap total children per run.
   • Workflow itself coordinates only; child agents perform tool/file operations.

6. Add tests.

   • Rust tests for phase transitions, concurrency caps, stop/resume behavior, and failed child handling.
   • Vitest for workflow progress rendering and approval card behavior.

Reference code

spawn_parallel_agents is the existing fanout primitive:

// src/openhuman/agent_orchestration/tools/spawn_parallel_agents.rs
let max_parallel = parent.agent_config.max_parallel_tools.max(2);
if tasks.len() > max_parallel {
    return Ok(ToolResult::error(format!(
        "spawn_parallel_agents received {} tasks but max_parallel_tools is {}",
        tasks.len(),
        max_parallel
    )));
}

let futures = prepared.into_iter().map(|(definition, prompt, task, task_id)| async move {
    run_one_parallel_task(definition, prompt, task, task_id).await
});

OpenHuman already emits lifecycle progress that a workflow view can aggregate:

• src/openhuman/agent_orchestration/tools/spawn_parallel_agents.rs
• src/core/event_bus/events.rs (SubagentSpawned, SubagentCompleted, SubagentFailed, SubagentAwaitingUser)
• src/openhuman/agent_orchestration/ops.rs
• app/src/store/chatRuntimeSlice.ts

Claude reference: https://code.claude.com/docs/en/workflows

Relevant Claude ideas to adapt:

• The workflow plan lives outside the main chat context.
• Intermediate results stay in runtime state until synthesized.
• Users approve large runs and can inspect phase/agent progress.
• Concurrency and total-agent caps are explicit cost/safety controls.
• Saved workflows become repeatable commands/templates.

Acceptance criteria

• Workflow definition/run types exist and are persisted durably.
• A read-only parallel research/cross-check workflow can be started from the app.
• Runs expose phase progress, child agent refs, stop/resume state, and final synthesis.
• Concurrency and total child limits are enforced in Rust.
• High-cost/high-concurrency runs require explicit approval.
• Focused Rust and frontend tests are added.
• Diff coverage >= 80% for changed lines.

Related

• Parent: Design subagent workflows and parallel agent surfaces #3370
• Claude dynamic workflows: https://code.claude.com/docs/en/workflows