From abb9f8a04e07155c1eb83212749b7550f7f45583 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 27 Sep 2026 05:20:24 +1000 Subject: [PATCH] feat(harness): declare and enforce a workflow's harness needs at dispatch docs/prds/external-agent-harness.md ("Contract"): workflow definition validation must reject a stage whose needs the selected harness cannot meet -- capture tools without an adapter, or a gate retry without a resume verb. The step vocabulary had no static way to declare either. Added task.WorkflowInterface.Needs{Captures, GateRetries}, parsed and validated (GateRetries >= 0) the same way Inputs/Repository already are. Only a Kit profile is checked against it: an image profile's built-in agent loop always supports both, so Needs constrains only the harness path. Two enforcement points, chosen for where each fact is actually known without a network fetch at save time: - Captures vs adapter is knowable from config alone (profile.Adapter, the agentexec.harnessAdapters table), so daemon.pinTaskProfile checks it right where it already resolves the profile (validateProfileMeetsNeeds), parking the task the same way an unconfigured profile already does. - GateRetries vs the Kit's actual agent-sessions resume verb is only known once the Kit composition is fetched, which kitrun.Launcher.Launch already does -- so kit.ValidateNeeds runs there (new kitrun.Request. GateRetries field, threaded from the workflow's parsed Needs in daemon.runKitTask) rather than inventing an image-fetching workflow-save validator. Deliberately NOT built: "a Kit profile named by no workflow is a validation error" (external-agent-harness.md "Selection"). Read literally ("a Kit profile [that is] named by no workflow"), this is a cross-resource check -- an agent-profiles entry unreferenced by anything in workflow-definitions -- and no control-plane Definition validator can see another resource today (Definition.Validate is a pure []byte->error function by design, matching every existing resource kind). Building that crossing is a real, separate piece of infrastructure with its own ordering questions (does defining a Kit profile before its workflow now fail?), not a two-line addition, so it is left for a follow-on rather than bolted on here. Also fixes a test bug caught by rerunning with a short -timeout per instruction: TestRunKitTaskThreadsGateRetriesToTheLauncher's fake NATS subscriber never responded, so runKitTask's call into runViaAgent blocked forever waiting for a reply bounded by a zero (unconfigured) wall-clock budget. Fixed by responding, matching the sibling test's pattern. --- internal/daemon/daemon.go | 22 +++- internal/daemon/daemon_test.go | 101 ++++++++++++++++++ internal/daemon/kit_task.go | 21 +++- internal/domain/workflow/task/interface.go | 22 ++++ .../domain/workflow/task/interface_test.go | 14 +++ internal/infrastructure/kit/kit.go | 13 +++ internal/infrastructure/kit/kit_test.go | 45 ++++++++ internal/infrastructure/kitrun/launcher.go | 9 ++ 8 files changed, 241 insertions(+), 6 deletions(-) diff --git a/internal/daemon/daemon.go b/internal/daemon/daemon.go index 94d52505f..0adee72e3 100644 --- a/internal/daemon/daemon.go +++ b/internal/daemon/daemon.go @@ -1757,7 +1757,9 @@ func (d *Daemon) pinTaskProfile(ctx context.Context, task *workflow.Task) (confi if err == nil { var profile config.AgentProfile if profile, err = d.configFor(task).Containers.Profile(iface.Profile); err == nil { - return profile, true + if err = validateProfileMeetsNeeds(profile, iface.Needs); err == nil { + return profile, true + } } } d.Log.Error("agent profile unavailable", "task", task.ID, "err", err) @@ -1765,6 +1767,24 @@ func (d *Daemon) pinTaskProfile(ctx context.Context, task *workflow.Task) (confi return config.AgentProfile{}, false } +// validateProfileMeetsNeeds rejects a Kit profile whose harness cannot meet +// what the workflow declares it needs (docs/prds/external-agent-harness.md, +// "Contract"): a workflow needing captures but naming a profile whose Kit CLI +// serves none (no adapter, or one with no MCP config to register archie-agent +// mcp against -- e.g. Codex, Pi, OMP per agentexec.harnessAdapters). An image +// profile is never checked: the built-in agent loop always supports both +// captures and gate retries, so Needs constrains only the harness path. +func validateProfileMeetsNeeds(profile config.AgentProfile, needs workflowtask.WorkflowNeeds) error { + if !profile.IsKit() || !needs.Captures { + return nil + } + adapter, ok := agentexec.LookupHarnessAdapter(profile.Adapter) + if !ok || len(adapter.MCPConfig) == 0 { + return fmt.Errorf("needs.captures is set, but profile adapter %q serves no capture tools", profile.Adapter) + } + return nil +} + // publicationGrant issues the capability to publish the task's branch. A task // with no repository has nothing to publish and gets none. func (d *Daemon) publicationGrant(ctx context.Context, task *workflow.Task) (string, func(), bool) { diff --git a/internal/daemon/daemon_test.go b/internal/daemon/daemon_test.go index 8700e432b..81f6a88b1 100644 --- a/internal/daemon/daemon_test.go +++ b/internal/daemon/daemon_test.go @@ -2353,6 +2353,65 @@ func TestRunViaAgentCarriesTheWorkflowProfile(t *testing.T) { } } +// TestPinTaskProfileRefusesCapturesTheHarnessCannotServe is the harness PRD's +// (Contract) "workflow definition validation rejects... a stage whose needs +// the selected harness cannot meet: capture tools without an adapter". A Kit +// profile's own adapter -- not the workflow -- decides whether captures are +// servable, so a workflow that needs them but names a profile whose CLI +// serves no capture tools (empty MCPConfig, e.g. Codex/Pi/OMP) must be +// refused rather than silently running with no way to return its result. +func TestPinTaskProfileRefusesCapturesTheHarnessCannotServe(t *testing.T) { + d, s, _ := daemonWithNATS(t) + cfg := d.Cfg.Get() + cfg.Containers.Profiles = map[string]config.AgentProfile{ + "serves-captures": {Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}, + "no-captures": {Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterCodex}, + "no-adapter": {Kit: []string{"kit@sha256:ab"}}, + } + d.Cfg.Set(cfg) + d.WorkflowDefinitions = &workflowDefinitionsStub{collection: workflow.WorkflowDefinitionCollection{Definitions: []workflow.WorkflowDefinitionEntry{ + {ID: "needs-captures-served", YAML: "id: needs-captures-served\nrepository: none\nprofile: serves-captures\nneeds: {captures: true}\nsteps:\n - type: agent.run\n settings: {mission: go}\n"}, + {ID: "needs-captures-codex", YAML: "id: needs-captures-codex\nrepository: none\nprofile: no-captures\nneeds: {captures: true}\nsteps:\n - type: agent.run\n settings: {mission: go}\n"}, + {ID: "needs-captures-bare", YAML: "id: needs-captures-bare\nrepository: none\nprofile: no-adapter\nneeds: {captures: true}\nsteps:\n - type: agent.run\n settings: {mission: go}\n"}, + }}, version: 1} + ctx := context.Background() + + claim := func(number int, wf string) *workflow.Task { + t.Helper() + if _, err := s.EnqueueIssue(ctx, "acme", "widget", number, "t", "b", "", ""); err != nil { + t.Fatal(err) + } + task, err := s.ClaimNext(ctx) + if err != nil || task == nil { + t.Fatalf("claim: (%v, %v)", task, err) + } + task.Workflow = wf + return task + } + + served := claim(51, "needs-captures-served") + if _, ok := d.pinTaskProfile(ctx, served); !ok { + t.Fatal("a Kit profile whose adapter serves captures was refused") + } + + for _, tt := range []struct { + number int + workflow string + }{ + {52, "needs-captures-codex"}, + {53, "needs-captures-bare"}, + } { + task := claim(tt.number, tt.workflow) + if _, ok := d.pinTaskProfile(ctx, task); ok { + t.Fatalf("%s: a workflow needing captures was not refused by a profile that cannot serve them", tt.workflow) + } + got, err := s.TaskByID(ctx, task.ID) + if err != nil || got.Status != workflow.StatusParked || !strings.Contains(got.ParkReason, "captures") { + t.Fatalf("%s: task = %+v, %v; want parked naming the unmet captures need", tt.workflow, got, err) + } + } +} + // TestWorkflowCallGivesACalleeItsOwnProfile is the harness PRD's "a stage may // name a different profile" (docs/prds/external-agent-harness.md, Selection): // there is no mid-container runner switch, and none is built here. A stage @@ -2571,3 +2630,45 @@ func TestKitProfileRunsTheTaskOnItsHarness(t *testing.T) { t.Fatalf("released %v, removed %v; want the run released and its volumes removed", launcher.released, launcher.removed) } } + +// TestRunKitTaskThreadsGateRetriesToTheLauncher: KitLauncher.Launch is where +// the Kit's actual agent-sessions capability is known (it composes the Kit), +// so that is where docs/prds/external-agent-harness.md's "a gate retry +// without a resume verb" refusal has to run (kit.ValidateNeeds, wired in +// kitrun.Launcher.Launch). This proves runKitTask carries the workflow's +// declared retry budget there rather than dropping it. +func TestRunKitTaskThreadsGateRetriesToTheLauncher(t *testing.T) { + d, s, busClient := daemonWithNATS(t) + launcher := &fakeKitLauncher{} + d.KitLauncher = launcher + d.ConnectedNATS.URL = "nats://172.17.0.1:4222" + ctx := context.Background() + if _, err := s.EnqueueIssue(ctx, "acme", "widget", 32, "t", "b", "", ""); err != nil { + t.Fatal(err) + } + task, err := s.ClaimNext(ctx) + if err != nil || task == nil { + t.Fatalf("claim: (%v, %v)", task, err) + } + task.WorkflowDefinitionYAML = "id: contain\nrepository: none\nneeds: {gate_retries: 4}\nsteps:\n - type: agent.run\n settings: {mission: go}\n" + // runKitTask calls through to runViaAgent after Launch, which blocks on a + // NATS reply bounded by the task wall-clock budget (zero here, i.e. no + // bound at all) -- a handler that never responds hangs the daemon + // goroutine forever rather than timing out, so this must answer even + // though the assertion below only cares about what Launch already saw. + sub, err := mustCoreConn(t, busClient).Subscribe(agentnats.SubjectForTask(task.ID), func(msg *natsio.Msg) { + data, _ := json.Marshal(taskrun.Response{Status: workflow.StatusPROpen}) + _ = msg.Respond(data) + }) + if err != nil { + t.Fatalf("subscribe: %v", err) + } + t.Cleanup(func() { _ = sub.Unsubscribe() }) + + d.runKitTask(ctx, task, config.Repo{Owner: "acme", Name: "widget", Base: "main"}, t.TempDir(), + config.AgentProfile{Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}) + + if launcher.got.GateRetries != 4 { + t.Fatalf("launch request GateRetries = %d, want the workflow's declared 4", launcher.got.GateRetries) + } +} diff --git a/internal/daemon/kit_task.go b/internal/daemon/kit_task.go index 53afb1178..9b7bbc922 100644 --- a/internal/daemon/kit_task.go +++ b/internal/daemon/kit_task.go @@ -8,6 +8,7 @@ import ( "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" + workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task" "github.com/samcharles93/archie-core/internal/infrastructure/kit" "github.com/samcharles93/archie-core/internal/infrastructure/kitrun" "github.com/samcharles93/archie-core/internal/taskstate" @@ -51,12 +52,22 @@ func (d *Daemon) runKitTask(ctx context.Context, task *workflow.Task, repo confi park("kit worker environment", err) return } + // The interface is reparsed rather than threaded through pinTaskProfile's + // return: task.WorkflowDefinitionYAML is already pinned by the time this + // runs, parsing it is pure and cheap, and pinTaskProfile's signature stays + // unchanged for its other callers. + iface, err := workflowtask.ParseWorkflowInterface(task.WorkflowDefinitionYAML) + if err != nil { + park("kit workflow interface", err) + return + } run, err := d.KitLauncher.Launch(ctx, kitrun.Request{ - Execution: fmt.Sprintf("task-%d", task.ID), - Kit: profile.Kit, - Adapter: profile.Adapter, - WorkDir: workDir, - WorkerEnv: env, + Execution: fmt.Sprintf("task-%d", task.ID), + Kit: profile.Kit, + Adapter: profile.Adapter, + WorkDir: workDir, + WorkerEnv: env, + GateRetries: iface.Needs.GateRetries, }) if err != nil { park("kit launch failed", err) diff --git a/internal/domain/workflow/task/interface.go b/internal/domain/workflow/task/interface.go index 3de3e16d8..651d67882 100644 --- a/internal/domain/workflow/task/interface.go +++ b/internal/domain/workflow/task/interface.go @@ -42,6 +42,25 @@ type WorkflowInterface struct { // Profile names a [containers.profiles] entry. It is resolved when a task // is dispatched, not when the workflow is saved. Profile string `yaml:"profile,omitempty" json:"profile,omitempty"` + // Needs declares what this workflow's agent stages require of the + // profile they run under -- checked against the profile's actual + // capabilities before dispatch (docs/prds/external-agent-harness.md, + // "Contract"): a stage that returns structured output needs a harness + // with a capture-tools-capable output adapter, and a gated stage that + // may retry needs the Kit's agent-sessions resume verb. Only a Kit + // profile is checked against it -- an image profile's built-in agent + // loop always supports both. + Needs WorkflowNeeds `yaml:"needs" json:"needs"` +} + +// WorkflowNeeds is WorkflowInterface's declared harness requirements. +type WorkflowNeeds struct { + // Captures declares that a stage returns structured output through + // capture tools. + Captures bool `yaml:"captures,omitempty" json:"captures,omitempty"` + // GateRetries is the largest gate-retry budget any stage declares. Zero + // means no stage gates its result, so no resume capability is needed. + GateRetries int `yaml:"gate_retries,omitempty" json:"gate_retries,omitempty"` } var ( @@ -75,6 +94,9 @@ func (w WorkflowInterface) Validate() error { return fmt.Errorf("workflow input %q type %q must be one of %s", name, spec.Type, strings.Join(inputTypes, ", ")) } } + if w.Needs.GateRetries < 0 { + return fmt.Errorf("workflow needs.gate_retries must not be negative") + } return nil } diff --git a/internal/domain/workflow/task/interface_test.go b/internal/domain/workflow/task/interface_test.go index 545720ef7..4a7f3c44f 100644 --- a/internal/domain/workflow/task/interface_test.go +++ b/internal/domain/workflow/task/interface_test.go @@ -18,6 +18,7 @@ func TestParseWorkflowInterface(t *testing.T) { {name: "unknown mode", src: "id: a\nrepository: sometimes\n", wantErr: "must be none, optional or required"}, {name: "unknown input type", src: "id: a\ninputs:\n ip: {type: ipv4}\n", wantErr: `type "ipv4"`}, {name: "malformed input name", src: "id: a\ninputs:\n src-ip: {type: string}\n", wantErr: `input "src-ip"`}, + {name: "negative gate_retries", src: "id: a\nneeds: {gate_retries: -1}\n", wantErr: "gate_retries must not be negative"}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { @@ -38,6 +39,19 @@ func TestParseWorkflowInterface(t *testing.T) { } } +// TestParseWorkflowInterfaceNeeds pins the declared-needs vocabulary +// (docs/prds/external-agent-harness.md, "Contract"): a stage's requirements +// of its harness are static, readable metadata, not derived at run time. +func TestParseWorkflowInterfaceNeeds(t *testing.T) { + w, err := ParseWorkflowInterface("id: a\nprofile: contain\nneeds: {captures: true, gate_retries: 3}\n") + if err != nil { + t.Fatal(err) + } + if !w.Needs.Captures || w.Needs.GateRetries != 3 { + t.Fatalf("Needs = %+v, want {Captures:true GateRetries:3}", w.Needs) + } +} + func TestCheckInputs(t *testing.T) { w := WorkflowInterface{Inputs: map[string]InputSpec{ "src_ip": {Type: "string", Required: true}, diff --git a/internal/infrastructure/kit/kit.go b/internal/infrastructure/kit/kit.go index c9b9604a3..aba1b3b72 100644 --- a/internal/infrastructure/kit/kit.go +++ b/internal/infrastructure/kit/kit.go @@ -161,6 +161,19 @@ func FromMerge(merged *spec.MergeResult) (*Plan, error) { return plan, nil } +// ValidateNeeds rejects a Plan that cannot meet what the workflow's stages +// declared they need (docs/prds/external-agent-harness.md, "Contract"): a +// gate that may retry needs the Kit's agent-sessions resume verb, because +// archie resumes the session with the gate's output rather than starting +// over. gateRetries is zero for a workflow with no gated stage, which no +// Kit composition can fail to meet. +func ValidateNeeds(plan *Plan, gateRetries int) error { + if gateRetries > 0 && (plan.Sessions == nil || len(plan.Sessions.Resume) == 0) { + return fmt.Errorf("needs.gate_retries is %d, but the kit declares no %s resume verb to retry with", gateRetries, typeAgentSessions) + } + return nil +} + func refusalReason(c spec.Capability) (string, error) { if !supported[c.Type] { return "not provided by archie", nil diff --git a/internal/infrastructure/kit/kit_test.go b/internal/infrastructure/kit/kit_test.go index 9623c105a..2fa71912b 100644 --- a/internal/infrastructure/kit/kit_test.go +++ b/internal/infrastructure/kit/kit_test.go @@ -208,6 +208,51 @@ func TestCompose(t *testing.T) { } } +// TestValidateNeeds pins the harness PRD's "a gate retry without a resume +// verb" refusal (Contract): archie resumes the harness's own session with the +// gate's output rather than starting a fresh one, so a gated stage's retry +// budget is unmeetable by a Kit whose agent-sessions capability names no +// resume verb. +func TestValidateNeeds(t *testing.T) { + promptOnly := descriptor(t, spec.KindWorkload, ` + - type: com.docker.sandbox/agent-sessions@1 + config: + prompt: [-p, "{{.Prompt}}"]`) + withResume := descriptor(t, spec.KindWorkload, sessions) + + tests := []struct { + name string + descriptor *spec.Descriptor + gateRetries int + wantErr bool + }{ + {"no gated stage, no resume verb", promptOnly, 0, false}, + {"gated stage, no resume verb", promptOnly, 2, true}, + {"gated stage, a resume verb", withResume, 2, false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + plan, err := Admit(tt.descriptor) + if err != nil { + t.Fatalf("Admit: %v", err) + } + sessions, err := spec.AgentSessionsOf(plan.Capabilities) + if err != nil { + t.Fatalf("AgentSessionsOf: %v", err) + } + plan.Sessions = sessions + + err = ValidateNeeds(plan, tt.gateRetries) + if tt.wantErr && err == nil { + t.Fatal("ValidateNeeds accepted a gate retry budget the kit cannot resume") + } + if !tt.wantErr && err != nil { + t.Fatalf("ValidateNeeds: %v", err) + } + }) + } +} + func TestDecodePublished(t *testing.T) { published := "schemaVersion: \"3\"\nkind: workload\ncapabilities:" + sessions + "\n" tests := []struct { diff --git a/internal/infrastructure/kitrun/launcher.go b/internal/infrastructure/kitrun/launcher.go index f3f9f084a..d3cd0c97a 100644 --- a/internal/infrastructure/kitrun/launcher.go +++ b/internal/infrastructure/kitrun/launcher.go @@ -49,6 +49,12 @@ type Request struct { Adapter string WorkDir string WorkerEnv []string + // GateRetries is the workflow's declared gate-retry budget + // (task.WorkflowNeeds.GateRetries); zero means no stage gates its + // result. A composition with no agent-sessions resume verb cannot meet + // a positive one, and Launch refuses it rather than starting a + // container no gate failure could ever resume. + GateRetries int } // Run is a started Kit task. @@ -78,6 +84,9 @@ func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) { if err != nil { return nil, err } + if err := kit.ValidateNeeds(plan, req.GateRetries); err != nil { + return nil, err + } network, err := spec.NetworkPolicyOf(plan.Capabilities) if err != nil { return nil, err