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.
This commit is contained in:
1 parent
f12cb2478a
commit
abb9f8a04e
8 files changed
+241
-6
No files matched your search
@@ -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) {
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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},
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user