feat(agentexec): run a Kit task's stages on its harness through a named output adapter

This commit is contained in:
sam committed 2026-09-26 09:20:30 +10:00
1 parent 5507ded2d5
commit 0d042b72d9
7 files changed
+145 -21

No files matched your search

+4
View File
@@ -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"
+40
View File
@@ -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)
}
+15 -6
View File
@@ -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)
}
+55 -3
View File
@@ -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) {
+4 -1
View File
@@ -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"`
+24 -11
View File
@@ -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,
}
+3
View File
@@ -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