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