From 1df6ecef32b48baa13baf01c874f875366ba704c Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 26 Sep 2026 09:20:30 +1000 Subject: [PATCH] feat(agentexec): run a Kit task's stages on its harness through a named output adapter --- docs/data/generated/contracts.json | 4 ++ internal/agentexec/harness_adapters.go | 40 +++++++++++++++ internal/agentexec/harness_runner.go | 21 +++++--- internal/agentexec/harness_runner_test.go | 58 ++++++++++++++++++++-- internal/agentexec/protocol.go | 5 +- internal/app/agentworker/task_execution.go | 35 +++++++++---- internal/taskrun/taskrun.go | 3 ++ 7 files changed, 145 insertions(+), 21 deletions(-) create mode 100644 internal/agentexec/harness_adapters.go diff --git a/docs/data/generated/contracts.json b/docs/data/generated/contracts.json index f832dddd8..7618bfde8 100644 --- a/docs/data/generated/contracts.json +++ b/docs/data/generated/contracts.json @@ -255,6 +255,10 @@ "additionalProperties": false, "description": "HarnessSpec is how to drive a Kit's agent headlessly: its launch argv (image entrypoint and cmd) and the agent-sessions@1 verb tails appended to it.", "properties": { + "adapter": { + "description": "Adapter names the output adapter reading the CLI's stream; empty is\na CLI with none.", + "type": "string" + }, "continue": { "items": { "type": "string" diff --git a/internal/agentexec/harness_adapters.go b/internal/agentexec/harness_adapters.go new file mode 100644 index 000000000..0901c027c --- /dev/null +++ b/internal/agentexec/harness_adapters.go @@ -0,0 +1,40 @@ +package agentexec + +import "context" + +// AdapterClaudeCode names the Claude Code stream-json output adapter. +const AdapterClaudeCode = "claude-code" + +// HarnessAdapter is what archie knows about one CLI: how to read its output +// stream and how to register archie's MCP server with it. +type HarnessAdapter struct { + NewOutput func() HarnessOutput + MCPConfig []string +} + +var harnessAdapters = map[string]HarnessAdapter{ + AdapterClaudeCode: { + NewOutput: func() HarnessOutput { return newClaudeCodeHarnessOutput() }, + MCPConfig: []string{"--mcp-config", mcpConfigPlaceholder}, + }, +} + +// LookupHarnessAdapter returns the named adapter. The empty name is a CLI +// with no adapter: it reports nothing and serves no capture tools. +func LookupHarnessAdapter(name string) (HarnessAdapter, bool) { + a, ok := harnessAdapters[name] + return a, ok +} + +// HarnessStages runs every stage of a task on one harness: a Kit task's +// container is built from its harness, so no stage in it runs anywhere else. +type HarnessStages struct { + Runner Runner + Spec HarnessSpec +} + +func (r HarnessStages) Run(ctx context.Context, workspace string, req Request, report ToolCallReporter) (Result, error) { + spec := r.Spec + req.Harness = &spec + return r.Runner.Run(ctx, workspace, req, report) +} diff --git a/internal/agentexec/harness_runner.go b/internal/agentexec/harness_runner.go index c9f61d43c..1dd480efc 100644 --- a/internal/agentexec/harness_runner.go +++ b/internal/agentexec/harness_runner.go @@ -60,7 +60,7 @@ type HarnessRunner struct { } // NewHarnessRunner returns a runner using newOutput to read each -// invocation. A nil newOutput reads nothing: no tool calls, usage or session. +// invocation. A nil newOutput reads with the adapter the request names. func NewHarnessRunner(newOutput func() HarnessOutput) *HarnessRunner { return &HarnessRunner{newOutput: newOutput} } @@ -107,7 +107,7 @@ func (r *HarnessRunner) run(ctx context.Context, workspace string, req Request, session := "" for { res.Iterations++ - out := r.output() + out := r.output(req.Harness.Adapter) exitErr := invoke(runCtx, workspace, req.Harness, harnessArgv(req.Harness, verb, prompt, session, mcpConfig), out, report) if id := out.SessionID(); id != "" { session = id @@ -160,11 +160,14 @@ func settle(runCtx context.Context, workspace string, before repoState, req Requ return res, false, nil } -func (r *HarnessRunner) output() HarnessOutput { - if r.newOutput == nil { - return silentOutput{} +func (r *HarnessRunner) output(adapter string) HarnessOutput { + if r.newOutput != nil { + return r.newOutput() } - return r.newOutput() + if a, ok := LookupHarnessAdapter(adapter); ok { + return a.NewOutput() + } + return silentOutput{} } func validateHarness(req Request) error { @@ -178,6 +181,12 @@ func validateHarness(req Request) error { if !slices.ContainsFunc(h.Prompt, func(s string) bool { return strings.Contains(s, promptPlaceholder) }) { return fmt.Errorf("harness prompt verb must carry %s, or the mission is never passed", promptPlaceholder) } + if _, ok := LookupHarnessAdapter(h.Adapter); h.Adapter != "" && !ok { + return fmt.Errorf("harness output adapter %q is unknown", h.Adapter) + } + if req.Gate.MaxConsecutiveFailures > 1 && len(h.Resume) == 0 && len(h.Continue) == 0 { + return errors.New("stage retries its gate but the harness declares no resume or continue verb") + } if len(h.Resume) > 0 && !slices.ContainsFunc(h.Resume, func(s string) bool { return strings.Contains(s, sessionPlaceholder) }) { return fmt.Errorf("harness resume verb must carry %s", sessionPlaceholder) } diff --git a/internal/agentexec/harness_runner_test.go b/internal/agentexec/harness_runner_test.go index a36a968de..0d36ff756 100644 --- a/internal/agentexec/harness_runner_test.go +++ b/internal/agentexec/harness_runner_test.go @@ -35,6 +35,7 @@ capture) out=$(sed -n 's/.*"-captures","\([^"]*\)".*/\1/p' "$cfg") echo '{"tool":"record_finding","args":{"title":"found it"}}' >> "$out" echo '{"tool":"record_finding","args":{"severity":"forged, no title"}}' >> "$out" ;; +claude) echo '{"type":"system","subtype":"init","session_id":"C42"}' ;; fix-on-resume) if [ -f .attempted ]; then echo ok > fixed.txt; else touch .attempted; fi ;; esac echo "session=S123" @@ -249,13 +250,21 @@ func TestHarnessGateResumesTheSession(t *testing.T) { t.Fatalf("status %q after %d iterations, want parked after 3", res.Status, res.Iterations) } }) - t.Run("without a resume verb there is one iteration", func(t *testing.T) { + t.Run("a gate retry without a resume verb is refused before any invocation", func(t *testing.T) { f := newFixture(t, "fix-on-resume") f.req.Gate = gate f.req.Harness.Resume = nil + if _, err := NewHarnessRunner(nil).Run(t.Context(), f.workspace, f.req, nil); err == nil || len(f.invocations(t)) != 0 { + t.Fatalf("err %v after %d invocations, want a refusal before the harness ran", err, len(f.invocations(t))) + } + }) + t.Run("a single-attempt gate needs no resume verb", func(t *testing.T) { + f := newFixture(t, "edit") + f.req.Gate = Gate{Commands: gate.Commands, MaxConsecutiveFailures: 1} + f.req.Harness.Resume = nil res, _ := f.run(t, t.Context()) - if res.Status != StatusParked || res.Iterations != 1 || len(f.invocations(t)) != 1 { - t.Fatalf("status %q after %d iterations and %d invocations, want parked after 1", res.Status, res.Iterations, len(f.invocations(t))) + if res.Status != StatusParked || res.Iterations != 1 { + t.Fatalf("status %q after %d iterations, want parked after 1", res.Status, res.Iterations) } }) } @@ -266,12 +275,55 @@ func TestHarnessRequestValidation(t *testing.T) { if _, err := NewHarnessRunner(nil).Run(t.Context(), f.workspace, f.req, nil); err == nil { t.Fatal("a prompt verb with no {{.Prompt}} placeholder ran; the mission would be silently dropped") } + f.req.Harness.Prompt = []string{"-p", "{{.Prompt}}"} + f.req.Harness.Adapter = "no-such-cli" + if _, err := NewHarnessRunner(nil).Run(t.Context(), f.workspace, f.req, nil); err == nil { + t.Fatal("an unknown output adapter ran; its output would be read by nothing") + } f.req.Harness = nil if _, err := NewHarnessRunner(nil).Run(t.Context(), f.workspace, f.req, nil); err == nil { t.Fatal("a request without a harness spec ran on the harness runner") } } +func TestHarnessReadsOutputWithTheNamedAdapter(t *testing.T) { + f := newFixture(t, "claude") + f.req.Harness.Adapter = AdapterClaudeCode + f.req.Gate = Gate{Commands: []Command{{Name: "never", Argv: []string{"false"}}}, MaxConsecutiveFailures: 2} + if _, err := NewHarnessRunner(nil).Run(t.Context(), f.workspace, f.req, nil); err != nil { + t.Fatal(err) + } + inv := f.invocations(t) + if len(inv) != 2 || !strings.HasPrefix(inv[1], "--resume C42 ") { + t.Fatalf("invocations %q, want a resume of the session the Claude Code adapter read", inv) + } +} + +func TestClaudeCodeAdapterRegistersTheMCPServer(t *testing.T) { + a, ok := LookupHarnessAdapter(AdapterClaudeCode) + if !ok || !slices.ContainsFunc(a.MCPConfig, func(s string) bool { return strings.Contains(s, mcpConfigPlaceholder) }) { + t.Fatalf("adapter %+v: capture tools could never reach a Claude Code stage", a) + } +} + +func TestHarnessStagesRunEveryStageOnTheTasksHarness(t *testing.T) { + inner := &namedRunner{} + r := HarnessStages{Runner: inner, Spec: HarnessSpec{Adapter: AdapterClaudeCode}} + if _, err := r.Run(t.Context(), "", Request{Stage: "review"}, nil); err != nil { + t.Fatal(err) + } + if inner.got.Harness == nil || inner.got.Harness.Adapter != AdapterClaudeCode { + t.Fatalf("stage ran with harness %+v, want the task's", inner.got.Harness) + } +} + +type namedRunner struct{ got Request } + +func (r *namedRunner) Run(_ context.Context, _ string, req Request, _ ToolCallReporter) (Result, error) { + r.got = req + return Result{}, nil +} + // assertChildDead checks the harness's own child process did not outlive // it: killing only the CLI would leave its subprocesses running. func assertChildDead(t *testing.T, pidFile string) { diff --git a/internal/agentexec/protocol.go b/internal/agentexec/protocol.go index 783767d7b..3c7fe8fc9 100644 --- a/internal/agentexec/protocol.go +++ b/internal/agentexec/protocol.go @@ -104,7 +104,10 @@ type HarnessSpec struct { User string `json:"user,omitempty"` // Env is the invocation's entire environment. Nothing is inherited from // the worker, whose environment carries its credentials. - Env []string `json:"env,omitempty"` + Env []string `json:"env,omitempty"` + // Adapter names the output adapter reading the CLI's stream; empty is + // a CLI with none. + Adapter string `json:"adapter,omitempty"` Launch []string `json:"launch"` Prompt []string `json:"prompt"` Resume []string `json:"resume,omitempty"` diff --git a/internal/app/agentworker/task_execution.go b/internal/app/agentworker/task_execution.go index e11742efc..2f348d5e9 100644 --- a/internal/app/agentworker/task_execution.go +++ b/internal/app/agentworker/task_execution.go @@ -216,6 +216,26 @@ func applyToolLimits(agent agentexec.Runner, policy config.ToolPolicy, allow []s runner.AllowTools = allow } +// stageRunners builds the runner every agent stage uses, and the reviewer. +func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerFactory, log *slog.Logger) (agentexec.Runner, workflow.Reviewer, error) { + if req.Harness != nil { + // The built-in loop has no route to a model from a Kit container, so + // the review stage parks rather than running on it. + return agentexec.HarnessStages{Runner: agentexec.NewHarnessRunner(nil), Spec: *req.Harness}, nil, nil + } + var agent agentexec.Runner + if mcpSet != nil && mcpSet.registry != nil { + agent = agentexec.NewLoopRunner(agentexec.NewRuntime(req.Providers), log, mcpSet.registry) + } else { + agent = newRunner(req.Providers, log) + } + if agent == nil { + return nil, nil, fmt.Errorf("no agent runner configured for task %d", req.Task.ID) + } + applyToolLimits(agent, req.Cfg.ToolPolicy, req.Tools) + return agent, newReviewerFor(req), nil +} + // routeTask remains available for routing-only callers. Production execution // compiles the request's pinned YAML directly. func routeTask(req taskrun.Request, registry workflow.Registry) workflow.Workflow { @@ -265,17 +285,10 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen log.Warn("mcp providers had errors, continuing with available tools", "err", mcpErr) } - // Build a runner with MCP-discovered tools when available. - var agent agentexec.Runner - if mcpSet != nil && mcpSet.registry != nil { - agent = agentexec.NewLoopRunner(agentexec.NewRuntime(req.Providers), log, mcpSet.registry) - } else { - agent = newRunner(req.Providers, log) + agent, reviewer, err := stageRunners(req, mcpSet, newRunner, log) + if err != nil { + return nil, err } - if agent == nil { - return nil, fmt.Errorf("no agent runner configured for task %d", req.Task.ID) - } - applyToolLimits(agent, req.Cfg.ToolPolicy, req.Tools) agent = persistentRunner{Runner: agent, enabled: req.Repo.PersistentStorage} // A workflow run in this process publishes to an in-process *events.Bus @@ -303,7 +316,7 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen Store: dependencies.store, Trees: trees, Agent: agent, - Reviewer: newReviewerFor(req), + Reviewer: reviewer, Bus: bus, Log: log, } diff --git a/internal/taskrun/taskrun.go b/internal/taskrun/taskrun.go index b0b552b2f..e7e9a5ab9 100644 --- a/internal/taskrun/taskrun.go +++ b/internal/taskrun/taskrun.go @@ -45,6 +45,9 @@ type Request struct { WorkflowDefinition string `json:"workflow_definition"` // Tools is the agent profile's tool allowlist; empty allows every tool. Tools []string `json:"tools,omitempty"` + // Harness, set for a Kit profile, runs every agent stage on the Kit's + // CLI instead of the built-in loop. + Harness *agentexec.HarnessSpec `json:"harness,omitempty"` } // Validate rejects a full-task request that cannot be correlated to a real