43 lines
2.5 KiB
Markdown
43 lines
2.5 KiB
Markdown
# Orchestrator — Advanced Flow Patterns
|
|
|
|
**Status:** Proposed
|
|
**Epic:** orchestrator-flow-advanced
|
|
**Depends on:** v2.7.17-orchestrator (flow-runner already shipped)
|
|
|
|
## Why
|
|
|
|
The orchestrator (shipped v2.7.17) runs sequential research/analysis flows on local Qwen. Each step is a linear dependency chain: A → B → C. This works for analysis flows (code-review, investigate) but limits three high-value scenarios:
|
|
|
|
1. **Parallel research** — "Analyze this from 3 angles" currently requires 3 separate runs. A single flow with parallel branches would halve the wall-clock time.
|
|
2. **Adaptive depth** — "Investigate bug, and if it's a security issue, escalate to security review" requires conditional branching. Currently all steps run unconditionally.
|
|
3. **Human-in-the-loop** — "Review the diff and approve before applying" requires the orchestrator to pause and wait for user input before proceeding.
|
|
|
|
The patterns from the Ion hybrid workflow engine (trigger rules, event sourcing, approval gates, variable substitution) provide a proven vocabulary for these scenarios — we adapt the patterns without adopting the project.
|
|
|
|
## What Changes
|
|
|
|
### Trigger rules on step deps
|
|
Add `trigger_rule?: 'all_success' | 'one_success' | 'all_done'` to the `Step` type. Default `all_success` preserves existing behavior.
|
|
|
|
- `all_success` — step runs when ALL dependencies complete successfully (current behavior)
|
|
- `one_success` — step runs when ANY dependency completes (parallel research: whichever finishes first seeds the synthesis)
|
|
- `all_done` — step runs when all deps finish regardless of status (cleanup/reporting steps)
|
|
|
|
### Variable substitution in step prompts
|
|
Add `$stepId.output` and `$stepId.output.field` syntax in step prompts. The flow-runner resolves these before dispatching.
|
|
|
|
- `$research.output` — the full text output of step with id "research"
|
|
- `$classify.output.severity` — the "severity" field from step output parsed as YAML/JSON frontmatter
|
|
|
|
### Human approval gate
|
|
New `kind: 'approval'` step type that pauses the flow and publishes a permission frame to the user channel. Flow resumes when the user approves or rejects.
|
|
|
|
### Event-sourced step log
|
|
Append-only event log for each step execution (start, complete, fail, skip, pause, resume). Enables deterministic resume after coder restart without polling.
|
|
|
|
## Non-Goals
|
|
- No YAML DAG format (stay with TypeScript flow definitions)
|
|
- No CLI tool (orchestrator stays in-app)
|
|
- No replacement of the existing flow definitions — additive changes only
|
|
- No VM sandbox or WASM
|