From 664a122669146e948d5c6d87dbb3b332ea0ab6bb Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Wed, 4 Nov 2026 04:52:58 +0000 Subject: [PATCH 1/4] fix(mcp): skip parallel children, per-child outputs, gate-respecting loops, end: steps - Add Workflow.ParallelChildren/NextIndex and use them in both executors. devkit_start/devkit_advance now skip parallel children (they previously ran one by one and then again from the dispatcher). The dispatcher response carries each child's interpolated prompt, and devkit_advance takes an `outputs` object with one result per child so {{child-id}} resolves downstream. - Loops over MCP complete only when the gate passes AND the until sentinel appears; a failing gate is no longer overridden by DONE. Retry responses include the gate output. On max: halt (loop_exhausted) if the gate is still failing, otherwise continue with a LOOP EXHAUSTED warning. advancePastLoop now honours branch rules like the CLI engine. - New `end: true` step field: the workflow completes after that step unless a branch matched. Set on feature.yml final-report and bugfix.yml summary so the full paths no longer fall through into quick-fix. - Validation rejects parallel children that are not plain prompt steps and branch gotos that target a parallel child. - Docs: creating-workflows schema (branch syntax, end, parallel outputs, loop completion), CLAUDE.md rows. --- CLAUDE.md | 8 +- skills/creating-workflows/SKILL.md | 15 +- src/engine/engine.go | 14 +- src/engine/engine_test.go | 106 ++++++++++ src/engine/workflow.go | 45 +++++ src/mcp/flow_test.go | 300 +++++++++++++++++++++++++++++ src/mcp/tools.go | 267 +++++++++++++++++-------- workflows/bugfix.yml | 1 + workflows/feature.yml | 1 + 9 files changed, 660 insertions(+), 97 deletions(-) create mode 100644 src/mcp/flow_test.go diff --git a/CLAUDE.md b/CLAUDE.md index 287da8f..53743dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,12 +8,12 @@ devkit is a Claude Code plugin: deterministic YAML workflow engine, dispatcher a | Path | What | Grep here for | |---|---|---| -| `skills/` | 38 SKILL.md skills (engine dispatchers + capability tools) | Skill descriptions; what each skill triggers (workflow or direct exec) | +| `skills/` | 39 SKILL.md skills (engine dispatchers + capability tools) | Skill descriptions; what each skill triggers (workflow or direct exec) | | `skills/_principles.yml` | Shared cross-cutting principle config | Rules applied to every skill | | `skills/creating-workflows/` | Workflow YAML schema reference | Step types, `parallel:`/`branch:`/`loop:`/`expect:` semantics | | `workflows/` | 22 YAML workflow definitions | What each skill actually runs | -| `src/engine/engine.go` | Go workflow executor | How `parallel: [ids]` skips-then-fans-out (`parallelChildren`), branch eval, loop gates | -| `src/engine/workflow.go` | Workflow struct + YAML parsing | Step field definitions | +| `src/engine/engine.go` | Go workflow executor | How `parallel: [ids]` fans out (`runParallel`), branch eval, loop gates, `end:` | +| `src/engine/workflow.go` | Workflow struct + YAML parsing + validation | Step field definitions; `ParallelChildren`/`NextIndex` (shared sequential walk) | | `src/cmd/guard.go` | Hook gatekeeper | What Bash/Edit/etc. is allowed per step type + enforce level | | `src/cmd/workflow.go` | `devkit workflow` CLI command | Workflow invocation entry point | | `src/cmd/mcp.go` | `devkit mcp` CLI command | MCP server bootstrap | @@ -42,7 +42,7 @@ devkit is a Claude Code plugin: deterministic YAML workflow engine, dispatcher a - **Workflows are deterministic.** The engine controls step sequencing, loops, branches, and gates — not the model. YAML is parsed once, the graph is fixed, steps run with state persistence and hook enforcement. - **Skills come in two flavors.** *Engine-shim skills* (most) are thin dispatchers that call `devkit_start` then loop on `devkit_advance`, delegating to the workflow engine. *Capability skills* (e.g., `skills/scrape/`) are runtime-interpreted prompt templates where the model is the executor — it picks a backend from what's installed, generates shell/script via heredoc, judges output, falls through on failure. Use the capability form when work needs on-the-spot adaptation that pre-compiled YAML can't express (anti-bot arms races, heterogeneous backend outputs, content-judgment branching). -- **Parallel step pattern.** Steps listed in another step's `parallel: [ids]` are skipped during the sequential walk (see `parallelChildren` in `src/engine/engine.go`) and dispatched concurrently via `runParallel`. Never expect a step that appears in a parallel list to also execute in its sequential position. +- **Parallel step pattern.** Steps listed in another step's `parallel: [ids]` are skipped during the sequential walk (`Workflow.NextIndex` in `src/engine/workflow.go`, used by both the CLI engine and the MCP server) and run only inside their dispatcher — `runParallel` in the CLI, per-child `outputs` on `devkit_advance` over MCP. Never expect a step that appears in a parallel list to also execute in its sequential position. - **Enforce levels gate hook permissions.** `enforce: soft` lets gather/setup steps run `git diff` and other shell work during dispatch; `enforce: hard` blocks them. The gatekeeper logic lives in `src/cmd/guard.go`; see `guard_test.go` for the allow/deny matrix. - **Engine binary is separate from the CLI wrapper.** `bin/devkit` is the committed shell wrapper; it execs `devkit-engine` (compiled Go, gitignored). The wrapper handles install/version checks; the engine handles workflow execution. - **Skills are the future; `commands/` is legacy.** PR #77 migrated commands to skills. Both auto-discover, but skills support paths, disable-model-invocation, and supporting files. diff --git a/skills/creating-workflows/SKILL.md b/skills/creating-workflows/SKILL.md index 24656ea..a162e20 100644 --- a/skills/creating-workflows/SKILL.md +++ b/skills/creating-workflows/SKILL.md @@ -25,10 +25,10 @@ steps: max: number # Maximum iterations until: string # Stop condition (string match in output) gate: string # Shell command run after each iteration — exit 0 keeps, non-zero reverts - branch: # Optional: conditional execution - if: string # Condition expression - then: string # Step id to jump to if true - else: string # Step id to jump to if false + branch: # Optional: first matching rule wins + - when: string # Sentinel word to look for in this step's output + goto: string # Step id to jump to + end: bool # Optional: workflow completes after this step (unless a branch matched) ``` ## Step Fields @@ -38,10 +38,11 @@ steps: - **prompt** — The instruction. Use `{{step-id}}` to reference earlier outputs. Use `{{input}}` for workflow input. Mutually exclusive with `command`. - **command** — Shell command run directly (no LLM). Output is captured and available via `{{step-id}}`. Costs $0. Mutually exclusive with `prompt`. - **expect** — Only for `command` steps. Values: `success` (step fails if exit code is non-zero) or `failure` (step fails if exit code is 0). Omit for the default behavior where all exit codes are informational. Enables bugfix reproduction gates: repro with `expect: failure` must fail before fix, verify with `expect: success` must pass after. -- **parallel** — Lists step IDs to run concurrently. Results collected before next sequential step. -- **loop** — Repeats with `max` iterations. Exits early if output contains `until` string. Optional `gate` command enforces quality after each iteration. +- **parallel** — Lists step IDs to run concurrently. Listed steps are skipped in their sequential position and run only inside the dispatcher. Children must be plain prompt steps (no command, loop, branch, or end), and a branch may not `goto` a child. Over MCP, the agent reports results with `devkit_advance` `outputs: {"": "", ...}` — one entry per child — so later steps can use `{{child-id}}`. +- **loop** — Repeats with `max` iterations. Completes when the `gate` (if set) passes **and** the `until` sentinel (if set) appears in the iteration's output — a failing gate is never overridden by the sentinel. Over MCP, if `max` is reached with the gate still failing the workflow halts (`loop_exhausted`); if only the sentinel is missing it continues with a `LOOP EXHAUSTED` warning. - **loop.gate** — Shell command run after each loop iteration. Exit 0 = keep changes and commit. Non-zero = revert changes via `git checkout`. 3 consecutive gate failures trigger stuck detection and stop the loop. -- **branch** — Routes execution conditionally. Both `then` and `else` reference step `id`s. +- **branch** — Routes execution conditionally: a list of `when`/`goto` rules evaluated against the step's output; the first match jumps to `goto`, no match falls through. +- **end** — Marks a terminal step. After it runs (and no branch rule matched) the workflow completes instead of falling through. Use it to stop a main path before an alternative path placed later in the file (e.g. a TINY `quick-fix` reached only by branch). ## Minimal Example diff --git a/src/engine/engine.go b/src/engine/engine.go index 7af21ce..b39dcaa 100644 --- a/src/engine/engine.go +++ b/src/engine/engine.go @@ -108,14 +108,9 @@ func (e *Engine) RunWorkflow(ctx context.Context, wf *Workflow, cfg RunConfig) ( // addCost updates the running total (used by loops to keep overBudget accurate) addCost := func(c float64) { totalUSD += c } - // Build set of step IDs that are dispatched by parallel steps, - // so we skip them during sequential walk (they run inside runParallel). - parallelChildren := make(map[string]bool) - for _, s := range wf.Steps { - for _, pid := range s.Parallel { - parallelChildren[pid] = true - } - } + // Steps dispatched by a parallel step are skipped during the + // sequential walk (they run inside runParallel). + parallelChildren := wf.ParallelChildren() // Walk steps sequentially, with branch jumps failed := false @@ -216,6 +211,9 @@ func (e *Engine) RunWorkflow(ctx context.Context, wf *Workflow, cfg RunConfig) ( i = jump continue } + if step.End { + break + } i++ } diff --git a/src/engine/engine_test.go b/src/engine/engine_test.go index 5b13ce3..e909f6a 100644 --- a/src/engine/engine_test.go +++ b/src/engine/engine_test.go @@ -1713,3 +1713,109 @@ func TestInterpolateDeterministic(t *testing.T) { } } } + +func TestRunWorkflowEndStopsBeforeTrailingSteps(t *testing.T) { + db := tempDB(t) + dir, git := initGitRepo(t) + runner := newMockRunner([]runners.RunResult{ + result("BIG change"), + result("full path done"), + }, nil) + eng := mustEngine(t, db, git, runner, dir) + wf := &Workflow{ + Name: "test", + Steps: []WfStep{ + {ID: "triage", Prompt: "Classify {{input}}", Branch: []Branch{{When: "TINY", Goto: "quick"}}}, + {ID: "full", Prompt: "Full", End: true}, + {ID: "quick", Prompt: "Quick"}, + }, + } + res, err := eng.RunWorkflow(context.Background(), wf, RunConfig{Input: "x"}) + if err != nil { + t.Fatalf("RunWorkflow: %v", err) + } + if runner.callIdx != 2 { + t.Errorf("runner called %d times, want 2 (quick must not run after end)", runner.callIdx) + } + if _, ok := res.Outputs["quick"]; ok { + t.Error("quick ran after an end: true step") + } +} + +func TestValidateRejectsUnsupportedParallelChildren(t *testing.T) { + base := func(child WfStep) *Workflow { + return &Workflow{Name: "w", Steps: []WfStep{ + {ID: "fan", Parallel: []string{"c"}}, + child, + {ID: "after", Prompt: "after"}, + }} + } + cases := map[string]WfStep{ + "command child": {ID: "c", Command: "true"}, + "loop child": {ID: "c", Prompt: "p", Loop: &Loop{Max: 2}}, + "branch child": {ID: "c", Prompt: "p", Branch: []Branch{{When: "X", Goto: "after"}}}, + "end child": {ID: "c", Prompt: "p", End: true}, + } + for name, child := range cases { + if err := base(child).Validate(); err == nil { + t.Errorf("%s: expected validation error", name) + } + } + // goto into a parallel child would be silently skipped by the walk. + wf := &Workflow{Name: "w", Steps: []WfStep{ + {ID: "t", Prompt: "t", Branch: []Branch{{When: "X", Goto: "c"}}}, + {ID: "c", Prompt: "c"}, + {ID: "fan", Parallel: []string{"c"}}, + }} + if err := wf.Validate(); err == nil { + t.Error("branch goto targeting a parallel child should be rejected") + } +} + +func TestNextIndexSkipsParallelChildren(t *testing.T) { + wf := &Workflow{Name: "w", Steps: []WfStep{ + {ID: "a", Prompt: "a"}, + {ID: "b", Prompt: "b"}, + {ID: "fan", Parallel: []string{"a", "b"}}, + {ID: "z", Prompt: "z"}, + }} + if got := wf.NextIndex(0); got != 2 { + t.Errorf("NextIndex(0) = %d, want 2", got) + } + if got := wf.NextIndex(3); got != 3 { + t.Errorf("NextIndex(3) = %d, want 3", got) + } + if got := wf.NextIndex(4); got != 4 { + t.Errorf("NextIndex(4) = %d, want 4 (past end)", got) + } +} + +// The full paths of feature and bugfix must stop at their report step +// instead of falling through into the TINY quick-fix step placed last. +func TestShippedWorkflowsFullPathEndsBeforeQuickFix(t *testing.T) { + for wfFile, terminal := range map[string]string{ + "feature.yml": "final-report", + "bugfix.yml": "summary", + } { + wf, err := ParseFile(filepath.Join("..", "..", "workflows", wfFile)) + if err != nil { + t.Fatalf("%s: %v", wfFile, err) + } + var found bool + for i, s := range wf.Steps { + if s.ID != terminal { + continue + } + found = true + if !s.End { + t.Errorf("%s: step %q must set end: true", wfFile, terminal) + } + if i+1 >= len(wf.Steps) || wf.Steps[i+1].ID != "quick-fix" { + t.Errorf("%s: expected quick-fix right after %q", wfFile, terminal) + } + } + if !found { + t.Errorf("%s: step %q not found", wfFile, terminal) + } + } +} diff --git a/src/engine/workflow.go b/src/engine/workflow.go index b403b5c..cdd3e2a 100644 --- a/src/engine/workflow.go +++ b/src/engine/workflow.go @@ -56,6 +56,11 @@ type WfStep struct { Branch []Branch `yaml:"branch"` Principles []string `yaml:"principles"` // per-step override Require *Require `yaml:"require,omitempty"` + // End marks a terminal step: after it runs (and no branch rule + // matched), the workflow completes instead of falling through to + // the next step in the file. Lets alternative paths (e.g. a TINY + // quick-fix placed after the full path) live in one workflow. + End bool `yaml:"end,omitempty"` // Enforce overrides the workflow-level enforce for this step only. // Empty inherits from Workflow.Enforce. Lets a workflow keep most // prompt steps under hard (mid-step tool block) while allowing @@ -259,6 +264,8 @@ func validate(wf *Workflow) error { } } + children := wf.ParallelChildren() + // Validate branch targets exist for _, s := range wf.Steps { for _, b := range s.Branch { @@ -271,6 +278,9 @@ func validate(wf *Workflow) error { if !ids[b.Goto] { return fmt.Errorf("branch target %q not found (step %q)", b.Goto, s.ID) } + if children[b.Goto] { + return fmt.Errorf("branch target %q (step %q) is a parallel child — it only runs inside its dispatcher; goto the dispatcher instead", b.Goto, s.ID) + } } // Validate parallel references exist for _, pid := range s.Parallel { @@ -278,11 +288,46 @@ func validate(wf *Workflow) error { return fmt.Errorf("parallel step %q not found (step %q)", pid, s.ID) } } + // Parallel children are dispatched as plain prompts by both + // executors; anything else would be silently ignored. + if children[s.ID] { + switch { + case s.Prompt == "": + return fmt.Errorf("parallel child %q must be a prompt step", s.ID) + case s.Loop != nil, len(s.Branch) > 0, s.End: + return fmt.Errorf("parallel child %q must not set loop, branch, or end — they are not honoured inside a parallel dispatch", s.ID) + } + } } return nil } +// ParallelChildren returns the set of step IDs dispatched by some +// step's `parallel:` list. Those steps never run in their sequential +// position — only inside their dispatcher. +func (wf *Workflow) ParallelChildren() map[string]bool { + children := make(map[string]bool) + for _, s := range wf.Steps { + for _, pid := range s.Parallel { + children[pid] = true + } + } + return children +} + +// NextIndex returns the first index >= from that is not a parallel +// child, or len(wf.Steps) if there is none. Both executors use it so +// the sequential walk skips children identically. +func (wf *Workflow) NextIndex(from int) int { + children := wf.ParallelChildren() + i := from + for i < len(wf.Steps) && children[wf.Steps[i].ID] { + i++ + } + return i +} + // Validate re-validates a workflow that may have been constructed directly // (not via Parse). Call this at the engine boundary for safety. func (wf *Workflow) Validate() error { diff --git a/src/mcp/flow_test.go b/src/mcp/flow_test.go new file mode 100644 index 0000000..872a138 --- /dev/null +++ b/src/mcp/flow_test.go @@ -0,0 +1,300 @@ +package mcp + +import ( + "context" + "path/filepath" + "strings" + "testing" + + "github.com/5uck1ess/devkit/lib" + mcpmcp "github.com/mark3labs/mcp-go/mcp" +) + +// flowHarness drives devkit_start / devkit_advance against one workflow file. +type flowHarness struct { + t *testing.T + srv *Server + dataDir string + session string +} + +func newFlow(t *testing.T, yml, input string) (*flowHarness, string) { + t.Helper() + wfDir, dataDir := t.TempDir(), t.TempDir() + writeFile(t, filepath.Join(wfDir, "wf.yml"), yml) + h := &flowHarness{t: t, srv: newTestServer(t, dataDir, wfDir), dataDir: dataDir} + _, start := h.srv.startTool() + req := mcpmcp.CallToolRequest{} + req.Params.Arguments = map[string]interface{}{"workflow": "wf", "input": input} + res, err := start(context.Background(), req) + if err != nil { + t.Fatalf("start: %v", err) + } + text := resultText(t, res) + if res.IsError { + t.Fatalf("start tool error: %s", text) + } + st, err := lib.ReadSessionJSON(dataDir) + if err != nil || st == nil { + t.Fatalf("read session: %v", err) + } + h.session = st.ID + return h, text +} + +// advance calls devkit_advance with extra args; returns text and IsError. +func (h *flowHarness) advance(args map[string]interface{}) (string, bool) { + h.t.Helper() + _, adv := h.srv.advanceTool() + req := mcpmcp.CallToolRequest{} + a := map[string]interface{}{"session": h.session} + for k, v := range args { + a[k] = v + } + req.Params.Arguments = a + res, err := adv(context.Background(), req) + if err != nil { + h.t.Fatalf("advance: %v", err) + } + return resultText(h.t, res), res.IsError +} + +func (h *flowHarness) state() *lib.SessionState { + h.t.Helper() + st, err := lib.ReadSessionJSON(h.dataDir) + if err != nil { + h.t.Fatalf("read session: %v", err) + } + return st +} + +func resultText(t *testing.T, res *mcpmcp.CallToolResult) string { + t.Helper() + if res == nil || len(res.Content) == 0 { + t.Fatal("empty result") + } + tc, ok := res.Content[0].(mcpmcp.TextContent) + if !ok { + t.Fatalf("unexpected content type %T", res.Content[0]) + } + return tc.Text +} + +// tri-review layout: parallel children come BEFORE their dispatcher. +const triLayout = `name: tri +description: children before dispatcher +steps: + - id: gather + prompt: Gather {{input}} + - id: review-a + model: smart + prompt: Review A of {{gather}} + - id: review-b + model: fast + prompt: Review B of {{gather}} + - id: dispatch + parallel: [review-a, review-b] + - id: consolidate + prompt: "Merge: {{review-a}} || {{review-b}}" +` + +func TestAdvanceSkipsParallelChildren(t *testing.T) { + h, _ := newFlow(t, triLayout, "diff") + text, isErr := h.advance(map[string]interface{}{"output": "THE-DIFF"}) + if isErr { + t.Fatalf("advance error: %s", text) + } + if st := h.state(); st.CurrentStep != "dispatch" { + t.Fatalf("after gather, current step = %q, want dispatch (children must be skipped)", st.CurrentStep) + } + // The dispatcher response must carry each child's interpolated prompt. + for _, want := range []string{"review-a", "Review A of THE-DIFF", "review-b", "Review B of THE-DIFF", "outputs"} { + if !strings.Contains(text, want) { + t.Errorf("dispatch response missing %q:\n%s", want, text) + } + } +} + +func TestAdvanceParallelStoresPerChildOutputs(t *testing.T) { + h, _ := newFlow(t, triLayout, "diff") + h.advance(map[string]interface{}{"output": "THE-DIFF"}) + text, isErr := h.advance(map[string]interface{}{ + "outputs": map[string]interface{}{"review-a": "A-VERDICT", "review-b": "B-VERDICT"}, + }) + if isErr { + t.Fatalf("advance error: %s", text) + } + if st := h.state(); st.CurrentStep != "consolidate" { + t.Fatalf("current step = %q, want consolidate", st.CurrentStep) + } + if !strings.Contains(text, "Merge: A-VERDICT || B-VERDICT") { + t.Errorf("consolidate prompt did not receive child outputs:\n%s", text) + } +} + +func TestAdvanceParallelRequiresEveryChildOutput(t *testing.T) { + h, _ := newFlow(t, triLayout, "diff") + h.advance(map[string]interface{}{"output": "THE-DIFF"}) + + text, isErr := h.advance(map[string]interface{}{"output": "one consolidated blob"}) + if !isErr || !strings.Contains(text, "review-a") { + t.Fatalf("expected error naming missing child outputs, got isErr=%v:\n%s", isErr, text) + } + text, isErr = h.advance(map[string]interface{}{"outputs": map[string]interface{}{"review-a": "A"}}) + if !isErr || !strings.Contains(text, "review-b") { + t.Fatalf("expected error naming review-b, got isErr=%v:\n%s", isErr, text) + } + if st := h.state(); st.CurrentStep != "dispatch" || st.Busy { + t.Fatalf("rejected advance must leave session on dispatch and unclaimed, got step=%q busy=%v", st.CurrentStep, st.Busy) + } +} + +func TestStartSkipsLeadingParallelChildren(t *testing.T) { + _, text := newFlow(t, `name: lead +description: children first +steps: + - id: a + prompt: A {{input}} + - id: b + prompt: B {{input}} + - id: fan + parallel: [a, b] + - id: after + prompt: After +`, "x") + if !strings.Contains(text, "STEP 3/4: fan") { + t.Fatalf("start should land on the dispatcher, got:\n%s", text) + } +} + +const gatedLoop = `name: gated +description: gate + until +steps: + - id: fix + prompt: Fix it, then say DONE. + loop: + max: 3 + until: DONE + gate: "%s" + - id: next + prompt: Next step. +` + +func TestLoopFailedGateIgnoresUntilSentinel(t *testing.T) { + h, _ := newFlow(t, strings.Replace(gatedLoop, "%s", "echo GATE-SAYS-RED; exit 1", 1), "x") + text, isErr := h.advance(map[string]interface{}{"output": "DONE"}) + if isErr { + t.Fatalf("unexpected error: %s", text) + } + if st := h.state(); st.CurrentStep != "fix" { + t.Fatalf("failing gate + DONE must stay in loop, now at %q", st.CurrentStep) + } + if !strings.Contains(text, "GATE-SAYS-RED") || !strings.Contains(text, "exit 1") { + t.Errorf("retry response should show gate output and exit code:\n%s", text) + } +} + +func TestLoopPassingGateStillNeedsUntil(t *testing.T) { + h, _ := newFlow(t, strings.Replace(gatedLoop, "%s", "true", 1), "x") + h.advance(map[string]interface{}{"output": "made some progress"}) + if st := h.state(); st.CurrentStep != "fix" { + t.Fatalf("gate pass without DONE must keep looping, now at %q", st.CurrentStep) + } + text, _ := h.advance(map[string]interface{}{"output": "DONE"}) + if st := h.state(); st.CurrentStep != "next" { + t.Fatalf("gate pass + DONE should advance, now at %q:\n%s", st.CurrentStep, text) + } +} + +func TestLoopExhaustedWithFailingGateHalts(t *testing.T) { + h, _ := newFlow(t, strings.Replace(strings.Replace(gatedLoop, "%s", "false", 1), "max: 3", "max: 1", 1), "x") + text, isErr := h.advance(map[string]interface{}{"output": "DONE"}) + if !isErr || !strings.Contains(strings.ToLower(text), "exhausted") { + t.Fatalf("expected halt error mentioning exhausted, got isErr=%v:\n%s", isErr, text) + } + if st := h.state(); st != nil { + t.Fatalf("halted workflow should clear session state, got %+v", st) + } +} + +func TestLoopExhaustedWithoutUntilWarnsAndContinues(t *testing.T) { + h, _ := newFlow(t, `name: soft +description: bounded rounds +steps: + - id: rounds + prompt: Research more; say COMPLETE when done. + loop: + max: 1 + until: COMPLETE + - id: synth + prompt: Synthesize. +`, "x") + text, isErr := h.advance(map[string]interface{}{"output": "found two more sources"}) + if isErr { + t.Fatalf("unexpected error: %s", text) + } + if st := h.state(); st.CurrentStep != "synth" { + t.Fatalf("should continue to synth, at %q", st.CurrentStep) + } + if !strings.Contains(text, "LOOP EXHAUSTED") { + t.Errorf("expected LOOP EXHAUSTED warning:\n%s", text) + } +} + +func TestAdvancePastLoopEvaluatesBranch(t *testing.T) { + h, _ := newFlow(t, `name: lb +description: loop with branch +steps: + - id: work + prompt: Work; say DONE. + loop: + max: 3 + until: DONE + branch: + - when: SKIP + goto: last + - id: middle + prompt: Middle. + - id: last + prompt: Last. +`, "x") + h.advance(map[string]interface{}{"output": "SKIP\nDONE"}) + if st := h.state(); st.CurrentStep != "last" { + t.Fatalf("branch on loop step ignored: at %q, want last", st.CurrentStep) + } +} + +const endLayout = `name: ends +description: explicit end +steps: + - id: triage + prompt: Classify. + branch: + - when: TINY + goto: quick + - id: full + prompt: Full path. + end: true + - id: quick + prompt: Quick path. +` + +func TestEndStepCompletesWorkflow(t *testing.T) { + h, _ := newFlow(t, endLayout, "x") + h.advance(map[string]interface{}{"output": "BIG"}) + if st := h.state(); st.CurrentStep != "full" { + t.Fatalf("at %q, want full", st.CurrentStep) + } + text, isErr := h.advance(map[string]interface{}{"output": "did it"}) + if isErr || !strings.Contains(text, "WORKFLOW COMPLETE") { + t.Fatalf("end: true should complete the workflow, got isErr=%v:\n%s", isErr, text) + } +} + +func TestEndNotReachedOnBranchPath(t *testing.T) { + h, _ := newFlow(t, endLayout, "x") + h.advance(map[string]interface{}{"output": "TINY"}) + if st := h.state(); st.CurrentStep != "quick" { + t.Fatalf("at %q, want quick", st.CurrentStep) + } +} diff --git a/src/mcp/tools.go b/src/mcp/tools.go index e0aa926..aaa29c2 100644 --- a/src/mcp/tools.go +++ b/src/mcp/tools.go @@ -125,7 +125,11 @@ func (s *Server) startTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { // window will also correctly report "no active session" until // we publish the transition to "running" below. sessionID := lib.NewSessionID() - firstStep := wf.Steps[0] + firstIdx := wf.NextIndex(0) + if firstIdx >= len(wf.Steps) { + return mcpmcp.NewToolResultError(fmt.Sprintf("workflow %q has no runnable steps (every step is a parallel child)", wfName)), nil + } + firstStep := wf.Steps[firstIdx] var reclaimedNote string state, err := lib.UpdateSessionJSON(s.dataDir, func(cur *lib.SessionState) (*lib.SessionState, error) { if cur != nil && (cur.Status == "running" || cur.Status == "starting") { @@ -157,7 +161,7 @@ func (s *Server) startTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { Workflow: wfName, // store filename, not wf.Name, to prevent traversal in advance Input: input, CurrentStep: firstStep.ID, - CurrentIndex: 0, + CurrentIndex: firstIdx, TotalSteps: len(wf.Steps), StepType: stepType(firstStep), // StepEnforce is the current step's effective enforce, @@ -290,8 +294,19 @@ func (s *Server) formatStepResponse(wf *engine.Workflow, state *lib.SessionState } else if len(step.Parallel) > 0 { fmt.Fprintf(&b, "TYPE: parallel dispatch\n") fmt.Fprintf(&b, "DISPATCH: %s\n", strings.Join(step.Parallel, ", ")) - fmt.Fprintf(&b, "Run each listed step concurrently through the host subagent facility, then call devkit_advance with a consolidated result.\n") + fmt.Fprintf(&b, "Run each listed step concurrently through the host subagent facility, then call devkit_advance with `outputs`: an object mapping every step id above to that subagent's result (e.g. {\"%s\": \"...\"}). If a subagent failed, report the failure text as its output. An optional `output` may carry a consolidated summary.\n", step.Parallel[0]) fmt.Fprintf(&b, "Use host-native subagents or external runners when available; give each subagent a bounded scope, separate write ownership, and require files changed, verification run, and remaining risks before completion.\n") + for _, cid := range step.Parallel { + child := findStep(wf, cid) + if child == nil { + continue + } + fmt.Fprintf(&b, "\n--- %s", cid) + if child.Model != "" { + fmt.Fprintf(&b, " (model: %s)", child.Model) + } + fmt.Fprintf(&b, " ---\nPROMPT: %s\n", engine.Interpolate(child.Prompt, input, state.Outputs)) + } } else { prompt := engine.Interpolate(step.Prompt, input, state.Outputs) fmt.Fprintf(&b, "PROMPT: %s\n", prompt) @@ -352,6 +367,7 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { mcpmcp.WithDescription("Complete current step and get next"), mcpmcp.WithString("session", mcpmcp.Required(), mcpmcp.Description("Session ID")), mcpmcp.WithString("output", mcpmcp.Description("Summary of step output (for prompt steps)")), + mcpmcp.WithObject("outputs", mcpmcp.Description("Parallel dispatch steps only: object mapping each dispatched step id to its result")), ) return tool, func(ctx context.Context, req mcpmcp.CallToolRequest) (*mcpmcp.CallToolResult, error) { sessionID, err := req.RequireString("session") @@ -458,6 +474,15 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { if err := engine.ValidateRequiredOutput(currentStep, output); err != nil { return mcpmcp.NewToolResultError(err.Error()), nil } + if len(currentStep.Parallel) > 0 { + childOut, err := parallelOutputs(currentStep, args["outputs"]) + if err != nil { + return mcpmcp.NewToolResultError(err.Error()), nil + } + for id, out := range childOut { + state.Outputs[id] = out + } + } if outputProvided || (currentStep.Require != nil && currentStep.Require.HasChecks()) { state.Outputs[currentStep.ID] = output } @@ -473,52 +498,132 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { return s.handleLoopAdvance(ctx, wf, state, ¤tStep, req) } - // Advance to next step - nextIndex := state.CurrentIndex + 1 + return s.transition(wf, state, ¤tStep, "") + } +} - // Check branch conditions - if len(currentStep.Branch) > 0 { - if output, ok := state.Outputs[currentStep.ID]; ok { - target := engine.EvalBranch(output, currentStep.Branch) - if target != "" { - for i, step := range wf.Steps { - if step.ID == target { - nextIndex = i - break - } +// findStep returns the step with the given id, or nil. +func findStep(wf *engine.Workflow, id string) *engine.WfStep { + for i := range wf.Steps { + if wf.Steps[i].ID == id { + return &wf.Steps[i] + } + } + return nil +} + +// parallelOutputs validates the `outputs` argument for a parallel +// dispatch step: it must be an object with a string entry for every +// dispatched child and nothing else. Downstream prompts reference +// children by id ({{review-a}}), so a single consolidated blob is not +// enough. +func parallelOutputs(step engine.WfStep, raw any) (map[string]string, error) { + want := strings.Join(step.Parallel, ", ") + obj, ok := raw.(map[string]any) + if !ok { + return nil, fmt.Errorf("parallel step %s: pass `outputs` as an object mapping each dispatched step id (%s) to its result", step.ID, want) + } + allowed := make(map[string]bool, len(step.Parallel)) + for _, id := range step.Parallel { + allowed[id] = true + } + for k := range obj { + if !allowed[k] { + return nil, fmt.Errorf("parallel step %s: unknown id %q in outputs (expected: %s)", step.ID, k, want) + } + } + out := make(map[string]string, len(step.Parallel)) + var missing []string + for _, id := range step.Parallel { + v, ok := obj[id].(string) + if !ok { + missing = append(missing, id) + continue + } + out[id] = v + } + if len(missing) > 0 { + return nil, fmt.Errorf("parallel step %s: outputs missing a string result for: %s", step.ID, strings.Join(missing, ", ")) + } + return out, nil +} + +// transition moves the session past `step`: a matching branch rule +// wins, otherwise `end: true` completes the workflow, otherwise the +// walk continues at the next step that is not a parallel child. The +// claim is cleared in the same write. notice is prepended to the +// response (used for loop-exhaustion warnings). +func (s *Server) transition(wf *engine.Workflow, state *lib.SessionState, step *engine.WfStep, notice string) (*mcpmcp.CallToolResult, error) { + nextIndex := -1 + if len(step.Branch) > 0 { + if output, ok := state.Outputs[step.ID]; ok { + if target := engine.EvalBranch(output, step.Branch); target != "" { + for i := range wf.Steps { + if wf.Steps[i].ID == target { + nextIndex = i + break } } } } + } + if nextIndex < 0 { + if step.End { + nextIndex = len(wf.Steps) + } else { + nextIndex = wf.NextIndex(state.CurrentIndex + 1) + } + } - if nextIndex >= len(wf.Steps) { - // Do NOT pre-release the claim — if completeWorkflow's - // initial WriteSessionJSON fails the session file still - // has Busy=true on disk and we need the deferred release - // to clean it up. On the success path completeWorkflow - // removes session.json via ClearSessionJSON, so the - // defer's UpdateSessionJSON finds nil and no-ops. - return s.completeWorkflow(state) - } - - // Write next step state. Clear the claim as part of this same - // write so the common case is a single atomic transition; the - // deferred releaseClaim will then observe Busy=false and - // no-op. We do NOT set claimReleased=true here so the defer - // still runs on subsequent panics or added return paths. - nextStep := wf.Steps[nextIndex] - state.CurrentStep = nextStep.ID - state.CurrentIndex = nextIndex - state.StepType = stepType(nextStep) - state.StepEnforce = engine.EffectiveEnforce(*wf, nextStep) - state.Busy = false - if err := lib.WriteSessionJSON(s.dataDir, state); err != nil { - return mcpmcp.NewToolResultError(fmt.Sprintf("write state: %v", err)), nil - } - - response := s.formatStepResponse(wf, state, &nextStep, state.Input) - return mcpmcp.NewToolResultText(response), nil + if nextIndex >= len(wf.Steps) { + // Do NOT pre-release the claim — if completeWorkflow's initial + // write fails, the deferred release in advanceTool cleans up. + res, err := s.completeWorkflow(state) + return withNotice(res, notice), err + } + + nextStep := wf.Steps[nextIndex] + state.CurrentStep = nextStep.ID + state.CurrentIndex = nextIndex + state.StepType = stepType(nextStep) + state.StepEnforce = engine.EffectiveEnforce(*wf, nextStep) + state.Busy = false + if err := lib.WriteSessionJSON(s.dataDir, state); err != nil { + return mcpmcp.NewToolResultError(fmt.Sprintf("write state: %v", err)), nil + } + return mcpmcp.NewToolResultText(notice + s.formatStepResponse(wf, state, &nextStep, state.Input)), nil +} + +// withNotice prepends notice to a text result. +func withNotice(res *mcpmcp.CallToolResult, notice string) *mcpmcp.CallToolResult { + if notice == "" || res == nil || len(res.Content) == 0 { + return res } + if tc, ok := res.Content[0].(mcpmcp.TextContent); ok { + tc.Text = notice + tc.Text + res.Content[0] = tc + } + return res +} + +// haltWorkflow ends a session that cannot continue safely (e.g. a +// gated loop ran out of iterations with its gate still failing). The +// session slot is freed and the DB row records why. +func (s *Server) haltWorkflow(state *lib.SessionState, status, reason string) (*mcpmcp.CallToolResult, error) { + var warnings []string + if s.db != nil { + if err := s.db.UpdateSessionStatus(state.ID, status); err != nil { + warnings = append(warnings, fmt.Sprintf("db session status update failed: %v", err)) + } + } + if err := lib.ClearSessionJSON(s.dataDir); err != nil { + warnings = append(warnings, fmt.Sprintf("clear session state failed: %v", err)) + } + msg := fmt.Sprintf("=== WORKFLOW HALTED (%s) ===\nSession: %s\nStep: %s\n%s", status, state.ID, state.CurrentStep, reason) + for _, w := range warnings { + msg += "\nwarning: " + w + } + return mcpmcp.NewToolResultError(msg), nil } // completeWorkflow marks a session as done, updates DB, and clears hot state. @@ -642,35 +747,48 @@ func (s *Server) handleLoopAdvance(ctx context.Context, wf *engine.Workflow, sta } state.LoopIteration++ - // Check gate command if present. Gate strings are also literal — - // values come via env vars DEVKIT_INPUT / DEVKIT_OUT_. - // Gates get a shorter independent timeout so a wedged gate cannot - // eat the full command budget. + // A loop completes when its gate (if any) passes AND its until + // sentinel (if any) appears in this iteration's output. A failing + // gate is objective evidence the work is broken, so the agent's + // "DONE" never overrides it. Gate strings are literal — values come + // via env vars DEVKIT_INPUT / DEVKIT_OUT_. Gates get a + // shorter independent timeout so a wedged gate cannot eat the full + // command budget. + hasCondition := step.Loop.Gate != "" || step.Loop.Until != "" + gatePassed := true + gateNote := "" if step.Loop.Gate != "" { gateOut, exitCode, err := s.runCommandWithTimeout(ctx, step.Loop.Gate, state, gateTimeout) if err != nil { return mcpmcp.NewToolResultError(fmt.Sprintf("gate command failed: %v\n%s", err, gateOut)), nil } - if exitCode == 0 { - // Gate passed — advance past loop - return s.advancePastLoop(wf, state) + if exitCode != 0 { + gatePassed = false + gateNote = fmt.Sprintf("GATE FAILED (exit %d): %s\n%s\n\n", exitCode, step.Loop.Gate, tailString(gateOut, 4000)) } - // Gate failed — continue loop } - - // Check "until" condition. Line-anchored match (see engine.MatchUntil) - // so sentinels like "DONE" do not match prose mentions. + untilMet := true if step.Loop.Until != "" { - if output, ok := state.Outputs[step.ID]; ok { - if engine.MatchUntil(output, step.Loop.Until) { - return s.advancePastLoop(wf, state) - } - } + // Line-anchored match (see engine.MatchUntil). + output, ok := state.Outputs[step.ID] + untilMet = ok && engine.MatchUntil(output, step.Loop.Until) + } + if hasCondition && gatePassed && untilMet { + return s.advancePastLoop(wf, state, step, "") } - // Check max iterations if state.LoopIteration >= state.LoopMax { - return s.advancePastLoop(wf, state) + if !hasCondition { + return s.advancePastLoop(wf, state, step, "") + } + if !gatePassed { + return s.haltWorkflow(state, "loop_exhausted", fmt.Sprintf( + "Loop %s ran %d/%d iterations and its gate is still failing — stopping instead of continuing on broken work.\n%s", + step.ID, state.LoopIteration, state.LoopMax, gateNote)) + } + notice := fmt.Sprintf("=== LOOP EXHAUSTED: %s ran %d/%d iterations without %q — continuing, but treat its result as unverified. ===\n\n", + step.ID, state.LoopIteration, state.LoopMax, step.Loop.Until) + return s.advancePastLoop(wf, state, step, notice) } // Continue loop — return same step for another iteration. @@ -684,30 +802,23 @@ func (s *Server) handleLoopAdvance(ctx context.Context, wf *engine.Workflow, sta return mcpmcp.NewToolResultError(fmt.Sprintf("write loop state: %v", err)), nil } response := fmt.Sprintf("=== LOOP ITERATION %d/%d: %s ===\n", state.LoopIteration, state.LoopMax, step.ID) + response += gateNote response += s.formatStepResponse(wf, state, step, state.Input) return mcpmcp.NewToolResultText(response), nil } -func (s *Server) advancePastLoop(wf *engine.Workflow, state *lib.SessionState) (*mcpmcp.CallToolResult, error) { - nextIndex := state.CurrentIndex + 1 - // Reset loop state +func (s *Server) advancePastLoop(wf *engine.Workflow, state *lib.SessionState, step *engine.WfStep, notice string) (*mcpmcp.CallToolResult, error) { + // Reset loop state, then transition like any other step so branch + // rules and end: true apply to loop steps too. state.LoopIteration = 0 state.LoopMax = 0 + return s.transition(wf, state, step, notice) +} - if nextIndex >= len(wf.Steps) { - return s.completeWorkflow(state) - } - - nextStep := wf.Steps[nextIndex] - state.CurrentStep = nextStep.ID - state.CurrentIndex = nextIndex - state.StepType = stepType(nextStep) - state.StepEnforce = engine.EffectiveEnforce(*wf, nextStep) - state.Busy = false - if err := lib.WriteSessionJSON(s.dataDir, state); err != nil { - return mcpmcp.NewToolResultError(fmt.Sprintf("write state: %v", err)), nil +// tailString returns the last n bytes of s (prefixed with "…" if cut). +func tailString(s string, n int) string { + if len(s) <= n { + return s } - - response := s.formatStepResponse(wf, state, &nextStep, state.Input) - return mcpmcp.NewToolResultText(response), nil + return "…" + s[len(s)-n:] } diff --git a/workflows/bugfix.yml b/workflows/bugfix.yml index ce495a1..bec7b95 100644 --- a/workflows/bugfix.yml +++ b/workflows/bugfix.yml @@ -111,6 +111,7 @@ steps: - id: summary model: fast enforce: soft # deletes scratchpad file + end: true # full path stops here; quick-fix below is the TINY branch target prompt: | Bug fix complete. Summary: diff --git a/workflows/feature.yml b/workflows/feature.yml index a79dc0d..b0363d4 100644 --- a/workflows/feature.yml +++ b/workflows/feature.yml @@ -169,6 +169,7 @@ steps: - id: final-report model: fast enforce: soft # deletes scratchpad file + end: true # full path stops here; quick-fix below is the TINY branch target prompt: | Feature session complete. Produce a summary: From 8e3a843b2a69f5c0d050c6d264d01deaf0b731c9 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Wed, 4 Nov 2026 04:57:59 +0000 Subject: [PATCH 2/4] fix(mcp): validate parallel child require, honour end on dispatchers, fresh loop sentinels - devkit_advance checks each parallel child's require: contract against its reported output (children are skipped in the walk, so nothing else did). - CLI engine: end: true on a parallel dispatcher now completes the workflow. - MCP loops only accept the until sentinel from output supplied in the same advance; a DONE left over from a gate-failed iteration no longer completes the loop once the gate turns green. --- src/engine/engine.go | 3 +++ src/engine/engine_test.go | 22 ++++++++++++++++++ src/mcp/flow_test.go | 49 +++++++++++++++++++++++++++++++++++++++ src/mcp/tools.go | 26 +++++++++++++++++---- 4 files changed, 95 insertions(+), 5 deletions(-) diff --git a/src/engine/engine.go b/src/engine/engine.go index b39dcaa..d5c00d9 100644 --- a/src/engine/engine.go +++ b/src/engine/engine.go @@ -168,6 +168,9 @@ func (e *Engine) RunWorkflow(ctx context.Context, wf *Workflow, cfg RunConfig) ( break } totalUSD += cost + if step.End { + break + } i++ continue } diff --git a/src/engine/engine_test.go b/src/engine/engine_test.go index e909f6a..89694db 100644 --- a/src/engine/engine_test.go +++ b/src/engine/engine_test.go @@ -1819,3 +1819,25 @@ func TestShippedWorkflowsFullPathEndsBeforeQuickFix(t *testing.T) { } } } + +func TestRunWorkflowEndOnParallelDispatcher(t *testing.T) { + db := tempDB(t) + dir, git := initGitRepo(t) + runner := newMockRunner([]runners.RunResult{ + result("a out"), result("b out"), result("must not run"), + }, nil) + eng := mustEngine(t, db, git, runner, dir) + wf := &Workflow{Name: "test", Steps: []WfStep{ + {ID: "a", Prompt: "A"}, + {ID: "b", Prompt: "B"}, + {ID: "fan", Parallel: []string{"a", "b"}, End: true}, + {ID: "trailing", Prompt: "T"}, + }} + res, err := eng.RunWorkflow(context.Background(), wf, RunConfig{Input: "x"}) + if err != nil { + t.Fatalf("RunWorkflow: %v", err) + } + if _, ok := res.Outputs["trailing"]; ok { + t.Error("trailing step ran after an end: true dispatcher") + } +} diff --git a/src/mcp/flow_test.go b/src/mcp/flow_test.go index 872a138..c62986e 100644 --- a/src/mcp/flow_test.go +++ b/src/mcp/flow_test.go @@ -298,3 +298,52 @@ func TestEndNotReachedOnBranchPath(t *testing.T) { t.Fatalf("at %q, want quick", st.CurrentStep) } } + +func TestAdvanceParallelValidatesChildRequire(t *testing.T) { + h, _ := newFlow(t, `name: req +description: child require +steps: + - id: a + prompt: A + require: + until: APPROVED + - id: b + prompt: B + - id: fan + parallel: [a, b] + - id: after + prompt: "{{a}}" +`, "x") + text, isErr := h.advance(map[string]interface{}{ + "outputs": map[string]interface{}{"a": "", "b": "fine"}, + }) + if !isErr || !strings.Contains(text, "a") { + t.Fatalf("child require must be enforced, got isErr=%v:\n%s", isErr, text) + } + if st := h.state(); st.CurrentStep != "fan" || st.Busy { + t.Fatalf("rejected advance must stay on fan and release claim, got %q busy=%v", st.CurrentStep, st.Busy) + } + _, isErr = h.advance(map[string]interface{}{ + "outputs": map[string]interface{}{"a": "APPROVED", "b": "fine"}, + }) + if isErr { + t.Fatal("valid child outputs rejected") + } +} + +func TestLoopUntilRequiresFreshOutput(t *testing.T) { + marker := filepath.Join(t.TempDir(), "green") + h, _ := newFlow(t, strings.Replace(gatedLoop, "%s", "test -f "+marker, 1), "x") + // Iteration 1: agent says DONE but gate is red → stay. + h.advance(map[string]interface{}{"output": "DONE"}) + if st := h.state(); st.CurrentStep != "fix" { + t.Fatalf("at %q, want fix", st.CurrentStep) + } + // Gate turns green; agent advances WITHOUT a new output. The stale + // DONE from iteration 1 must not complete the loop. + writeFile(t, marker, "ok") + h.advance(map[string]interface{}{}) + if st := h.state(); st.CurrentStep != "fix" { + t.Fatalf("stale DONE completed the loop: at %q", st.CurrentStep) + } +} diff --git a/src/mcp/tools.go b/src/mcp/tools.go index aaa29c2..c2ad087 100644 --- a/src/mcp/tools.go +++ b/src/mcp/tools.go @@ -437,6 +437,12 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { currentStep := wf.Steps[state.CurrentIndex] + // freshOutput records whether this advance supplied the current + // step's output; loop until-sentinels only count when fresh, so + // a DONE from an earlier (gate-failed) iteration can't complete + // the loop later. + freshOutput := false + // Handle command steps — engine executes them. Command strings // are run literally (no {{...}} expansion); values are passed // through env vars DEVKIT_INPUT and DEVKIT_OUT_ to @@ -475,7 +481,7 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { return mcpmcp.NewToolResultError(err.Error()), nil } if len(currentStep.Parallel) > 0 { - childOut, err := parallelOutputs(currentStep, args["outputs"]) + childOut, err := parallelOutputs(wf, currentStep, args["outputs"]) if err != nil { return mcpmcp.NewToolResultError(err.Error()), nil } @@ -486,6 +492,7 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { if outputProvided || (currentStep.Require != nil && currentStep.Require.HasChecks()) { state.Outputs[currentStep.ID] = output } + freshOutput = outputProvided } // Handle loop steps. Do NOT pre-release the claim here — if @@ -495,7 +502,7 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { // writes with Busy=false, and the defer's follow-up write is // a harmless no-op. if currentStep.Loop != nil { - return s.handleLoopAdvance(ctx, wf, state, ¤tStep, req) + return s.handleLoopAdvance(ctx, wf, state, ¤tStep, freshOutput) } return s.transition(wf, state, ¤tStep, "") @@ -517,7 +524,7 @@ func findStep(wf *engine.Workflow, id string) *engine.WfStep { // dispatched child and nothing else. Downstream prompts reference // children by id ({{review-a}}), so a single consolidated blob is not // enough. -func parallelOutputs(step engine.WfStep, raw any) (map[string]string, error) { +func parallelOutputs(wf *engine.Workflow, step engine.WfStep, raw any) (map[string]string, error) { want := strings.Join(step.Parallel, ", ") obj, ok := raw.(map[string]any) if !ok { @@ -545,6 +552,15 @@ func parallelOutputs(step engine.WfStep, raw any) (map[string]string, error) { if len(missing) > 0 { return nil, fmt.Errorf("parallel step %s: outputs missing a string result for: %s", step.ID, strings.Join(missing, ", ")) } + // Children are skipped in the sequential walk, so their own + // require: contracts must be checked here. + for _, id := range step.Parallel { + if child := findStep(wf, id); child != nil { + if err := engine.ValidateRequiredOutput(*child, out[id]); err != nil { + return nil, fmt.Errorf("parallel step %s: %w", step.ID, err) + } + } + } return out, nil } @@ -737,7 +753,7 @@ func commandEnv(state *lib.SessionState) []string { // through the same function the validator uses. func sanitizeEnvKey(id string) string { return engine.EnvKey(id) } -func (s *Server) handleLoopAdvance(ctx context.Context, wf *engine.Workflow, state *lib.SessionState, step *engine.WfStep, req mcpmcp.CallToolRequest) (*mcpmcp.CallToolResult, error) { +func (s *Server) handleLoopAdvance(ctx context.Context, wf *engine.Workflow, state *lib.SessionState, step *engine.WfStep, freshOutput bool) (*mcpmcp.CallToolResult, error) { // Initialize loop tracking on first call if state.LoopMax == 0 { state.LoopMax = step.Loop.Max @@ -771,7 +787,7 @@ func (s *Server) handleLoopAdvance(ctx context.Context, wf *engine.Workflow, sta if step.Loop.Until != "" { // Line-anchored match (see engine.MatchUntil). output, ok := state.Outputs[step.ID] - untilMet = ok && engine.MatchUntil(output, step.Loop.Until) + untilMet = freshOutput && ok && engine.MatchUntil(output, step.Loop.Until) } if hasCondition && gatePassed && untilMet { return s.advancePastLoop(wf, state, step, "") From d4f5188a6a06b2c038c0734dd10dfa0feb541f97 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Wed, 4 Nov 2026 05:17:51 +0000 Subject: [PATCH 3/4] fix(mcp,guard): fence parallel dispatchers; drop stale outputs; harden halt - Guard treats a parallel dispatcher like a prompt step (Agent/Task allowed, Write/Edit/Bash blocked under hard). MCP now parks on the dispatcher, and the old allow-all default turned the tri-* fence off. - A dispatcher without its own enforce is soft if any child is soft, so research/self-audit fan-outs keep their WebSearch/Bash. - devkit_advance without output clears the step's earlier output, so a revisited step can't branch on a stale value. - Dispatch response shows each child's require: contract. - haltWorkflow persists the halted status before clearing state. - Validation rejects branch: on a parallel dispatcher. --- src/cmd/guard.go | 8 +++++-- src/cmd/guard_test.go | 40 +++++++++++++++++++++++----------- src/engine/engine_test.go | 30 ++++++++++++++++++++++++++ src/engine/workflow.go | 16 ++++++++++++++ src/mcp/flow_test.go | 39 +++++++++++++++++++++++++++++++++ src/mcp/tools.go | 45 ++++++++++++++++++++++++++++----------- 6 files changed, 151 insertions(+), 27 deletions(-) diff --git a/src/cmd/guard.go b/src/cmd/guard.go index 70b1012..bacf171 100644 --- a/src/cmd/guard.go +++ b/src/cmd/guard.go @@ -448,7 +448,11 @@ func runPreToolGuard() { guardExit(2) return - case "prompt": + case "prompt", "parallel": + // A parallel dispatcher is a prompt step whose work runs in + // subagents; it carries the same fence (Agent/Task allowed, + // Write/Edit/Bash blocked under hard). MCP parks on the + // dispatcher now that children are skipped in the walk. if enforce == lib.EnforceHard { if isDevkitMCPTool(tool) { guardExit(0) @@ -506,7 +510,7 @@ func runPreToolGuard() { return default: - // parallel or unknown — engine is dispatching, allow through. + // unknown step type — allow through rather than wedge the session. guardExit(0) } } diff --git a/src/cmd/guard_test.go b/src/cmd/guard_test.go index aa6a169..6e68ca2 100644 --- a/src/cmd/guard_test.go +++ b/src/cmd/guard_test.go @@ -375,6 +375,32 @@ func TestGuardPreToolUse(t *testing.T) { wantExit: 2, wantStderrSubstr: "cannot read session state", }, + { + // MCP now parks on the parallel dispatcher (children are + // skipped), so the dispatcher must carry the prompt fence: + // subagents may run, but Write/Edit stay blocked under hard. + name: "parallel+hard+Write → block", + dataDir: true, + hasSession: true, + session: lib.SessionState{ + Status: "running", StepType: "parallel", StepEnforce: lib.EnforceHard, CurrentStep: "dispatch-reviews", + Workflow: "tri-review", TotalSteps: 6, + }, + stdin: `{"tool_name":"Write"}`, + wantExit: 2, + wantStderrSubstr: "gather evidence with Read/Grep/Glob", + }, + { + name: "parallel+hard+Agent → allow (dispatch subagents)", + dataDir: true, + hasSession: true, + session: lib.SessionState{ + Status: "running", StepType: "parallel", StepEnforce: lib.EnforceHard, CurrentStep: "dispatch-reviews", + Workflow: "tri-review", TotalSteps: 6, + }, + stdin: `{"tool_name":"Agent"}`, + wantExit: 0, + }, { // Empty step_type is non-command and non-prompt, so the // default branch (parallel/unknown) allows through. This @@ -444,19 +470,7 @@ func TestGuardPreToolUse(t *testing.T) { wantExit: 2, }, { - name: "parallel+hard+Write → allow", - dataDir: true, - hasSession: true, - session: lib.SessionState{ - Status: "running", StepType: "parallel", StepEnforce: lib.EnforceHard, CurrentStep: "fanout", - }, - stdin: `{"tool_name":"Write"}`, - wantExit: 0, - }, - { - // parallel+soft should allow exactly the same as parallel+hard. - // Explicit row so a future refactor that adds an enforce - // check to the parallel branch cannot sneak through. + // parallel+soft behaves like prompt+soft: allow with a nudge. name: "parallel+soft+Bash → allow", dataDir: true, hasSession: true, diff --git a/src/engine/engine_test.go b/src/engine/engine_test.go index 89694db..fb6e930 100644 --- a/src/engine/engine_test.go +++ b/src/engine/engine_test.go @@ -1841,3 +1841,33 @@ func TestRunWorkflowEndOnParallelDispatcher(t *testing.T) { t.Error("trailing step ran after an end: true dispatcher") } } + +func TestEffectiveEnforceParallelDispatcherInheritsSoftChildren(t *testing.T) { + wf := Workflow{Name: "w", Enforce: EnforceHard, Steps: []WfStep{ + {ID: "a", Prompt: "a", Enforce: EnforceSoft}, + {ID: "b", Prompt: "b"}, + {ID: "fan", Parallel: []string{"a", "b"}}, + {ID: "fan-hard", Parallel: []string{"b"}}, + {ID: "fan-pinned", Parallel: []string{"a"}, Enforce: EnforceHard}, + }} + if got := EffectiveEnforce(wf, wf.Steps[2]); got != EnforceSoft { + t.Errorf("dispatcher with a soft child = %q, want soft (children need their tools)", got) + } + if got := EffectiveEnforce(wf, wf.Steps[3]); got != EnforceHard { + t.Errorf("dispatcher with only hard children = %q, want hard", got) + } + if got := EffectiveEnforce(wf, wf.Steps[4]); got != EnforceHard { + t.Errorf("explicit enforce on dispatcher = %q, want hard", got) + } +} + +func TestValidateRejectsBranchOnParallelDispatcher(t *testing.T) { + wf := &Workflow{Name: "w", Steps: []WfStep{ + {ID: "fan", Parallel: []string{"c"}, Branch: []Branch{{When: "X", Goto: "after"}}}, + {ID: "c", Prompt: "c"}, + {ID: "after", Prompt: "after"}, + }} + if err := wf.Validate(); err == nil { + t.Error("branch on a parallel dispatcher should be rejected (CLI never evaluates it)") + } +} diff --git a/src/engine/workflow.go b/src/engine/workflow.go index cdd3e2a..a147e28 100644 --- a/src/engine/workflow.go +++ b/src/engine/workflow.go @@ -99,6 +99,19 @@ func EffectiveEnforce(wf Workflow, step WfStep) EnforceMode { if step.Enforce != EnforceInherit { return step.Enforce } + // A parallel dispatcher's tool calls are its children's (run in + // subagents under the dispatcher's session state). If any child + // declares soft — e.g. research fan-outs that need WebSearch/Bash — + // the dispatcher must not be harder than that child. + if len(step.Parallel) > 0 { + for _, cid := range step.Parallel { + for _, c := range wf.Steps { + if c.ID == cid && c.Enforce == EnforceSoft { + return EnforceSoft + } + } + } + } if wf.Enforce != EnforceInherit { return wf.Enforce } @@ -233,6 +246,9 @@ func validate(wf *Workflow) error { if len(s.Parallel) > 0 && s.Loop != nil { return fmt.Errorf("step %q has both parallel and loop — these are mutually exclusive", s.ID) } + if len(s.Parallel) > 0 && len(s.Branch) > 0 { + return fmt.Errorf("step %q has both parallel and branch — a dispatcher has no single output to branch on", s.ID) + } // Command strings are never interpolated — values are passed // through env vars ($DEVKIT_INPUT, $DEVKIT_OUT_) to avoid // shell injection. Reject {{...}} in command/gate strings so diff --git a/src/mcp/flow_test.go b/src/mcp/flow_test.go index c62986e..cefa532 100644 --- a/src/mcp/flow_test.go +++ b/src/mcp/flow_test.go @@ -347,3 +347,42 @@ func TestLoopUntilRequiresFreshOutput(t *testing.T) { t.Fatalf("stale DONE completed the loop: at %q", st.CurrentStep) } } + +func TestAdvanceWithoutOutputDoesNotReuseStaleBranchOutput(t *testing.T) { + h, _ := newFlow(t, `name: stale +description: revisit +steps: + - id: decide + prompt: Decide; say AGAIN to repeat. + branch: + - when: AGAIN + goto: decide + - id: done + prompt: Done. +`, "x") + h.advance(map[string]interface{}{"output": "AGAIN"}) + if st := h.state(); st.CurrentStep != "decide" { + t.Fatalf("at %q, want decide", st.CurrentStep) + } + // Second visit, no output: the first visit's AGAIN must not loop us back. + h.advance(map[string]interface{}{}) + if st := h.state(); st.CurrentStep != "done" { + t.Fatalf("stale AGAIN re-used: at %q, want done", st.CurrentStep) + } +} + +func TestParallelDispatchShowsChildRequire(t *testing.T) { + _, text := newFlow(t, `name: req2 +description: child require shown +steps: + - id: fan + parallel: [a] + - id: a + prompt: A + require: + until: APPROVED +`, "x") + if !strings.Contains(text, "APPROVED") { + t.Errorf("dispatch response should show child require contract:\n%s", text) + } +} diff --git a/src/mcp/tools.go b/src/mcp/tools.go index c2ad087..cc5cfda 100644 --- a/src/mcp/tools.go +++ b/src/mcp/tools.go @@ -306,6 +306,10 @@ func (s *Server) formatStepResponse(wf *engine.Workflow, state *lib.SessionState fmt.Fprintf(&b, " (model: %s)", child.Model) } fmt.Fprintf(&b, " ---\nPROMPT: %s\n", engine.Interpolate(child.Prompt, input, state.Outputs)) + if child.Require != nil { + fmt.Fprintf(&b, "REQUIRE (checked on this step's entry in outputs):\n") + writeRequire(&b, child.Require) + } } } else { prompt := engine.Interpolate(step.Prompt, input, state.Outputs) @@ -344,18 +348,7 @@ func (s *Server) formatStepResponse(wf *engine.Workflow, state *lib.SessionState } if step.Require != nil { fmt.Fprintf(&b, "\nREQUIRE:\n") - if step.Require.NonEmpty { - fmt.Fprintf(&b, "- non_empty\n") - } - for _, want := range step.Require.Contains { - fmt.Fprintf(&b, "- contains: %s\n", want) - } - if step.Require.Until != "" { - fmt.Fprintf(&b, "- until: %s\n", step.Require.Until) - } - if step.Require.LastLineRegex != "" { - fmt.Fprintf(&b, "- last_line_regex: %s\n", step.Require.LastLineRegex) - } + writeRequire(&b, step.Require) } fmt.Fprintf(&b, "\nCall devkit_advance when this step is complete.\n") @@ -491,6 +484,10 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { } if outputProvided || (currentStep.Require != nil && currentStep.Require.HasChecks()) { state.Outputs[currentStep.ID] = output + } else { + // No output this visit: drop any value from an earlier + // visit so branch rules and {{id}} can't act on it. + delete(state.Outputs, currentStep.ID) } freshOutput = outputProvided } @@ -509,6 +506,22 @@ func (s *Server) advanceTool() (mcpmcp.Tool, mcpgo.ToolHandlerFunc) { } } +// writeRequire renders a require: contract as "- check" lines. +func writeRequire(b *strings.Builder, r *engine.Require) { + if r.NonEmpty { + fmt.Fprintf(b, "- non_empty\n") + } + for _, want := range r.Contains { + fmt.Fprintf(b, "- contains: %s\n", want) + } + if r.Until != "" { + fmt.Fprintf(b, "- until: %s\n", r.Until) + } + if r.LastLineRegex != "" { + fmt.Fprintf(b, "- last_line_regex: %s\n", r.LastLineRegex) + } +} + // findStep returns the step with the given id, or nil. func findStep(wf *engine.Workflow, id string) *engine.WfStep { for i := range wf.Steps { @@ -627,6 +640,14 @@ func withNotice(res *mcpmcp.CallToolResult, notice string) *mcpmcp.CallToolResul // session slot is freed and the DB row records why. func (s *Server) haltWorkflow(state *lib.SessionState, status, reason string) (*mcpmcp.CallToolResult, error) { var warnings []string + // Persist the terminal status first (like completeWorkflow), so a + // failed clear below leaves a non-running session the guards and + // devkit_advance will not treat as live. + state.Status = status + state.Busy = false + if err := lib.WriteSessionJSON(s.dataDir, state); err != nil { + warnings = append(warnings, fmt.Sprintf("write halted state failed: %v", err)) + } if s.db != nil { if err := s.db.UpdateSessionStatus(state.ID, status); err != nil { warnings = append(warnings, fmt.Sprintf("db session status update failed: %v", err)) From bd73e3b473ea7256d8ddeabf9d1c598ef59eda59 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Wed, 4 Nov 2026 14:45:43 +0000 Subject: [PATCH 4/4] test(mcp): use forward slashes for gate path so YAML parses on Windows --- src/mcp/flow_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mcp/flow_test.go b/src/mcp/flow_test.go index cefa532..c1bb723 100644 --- a/src/mcp/flow_test.go +++ b/src/mcp/flow_test.go @@ -333,7 +333,7 @@ steps: func TestLoopUntilRequiresFreshOutput(t *testing.T) { marker := filepath.Join(t.TempDir(), "green") - h, _ := newFlow(t, strings.Replace(gatedLoop, "%s", "test -f "+marker, 1), "x") + h, _ := newFlow(t, strings.Replace(gatedLoop, "%s", "test -f "+filepath.ToSlash(marker), 1), "x") // Iteration 1: agent says DONE but gate is red → stay. h.advance(map[string]interface{}{"output": "DONE"}) if st := h.state(); st.CurrentStep != "fix" {