fix(workflow): derive a declared output's captures need for profile selection

A declared output is written through a capture tool, but the dispatch-time
harness check read only the workflow's needs.captures. A workflow that
declared outputs without also writing needs: {captures: true} could name a
Kit profile whose adapter serves no capture tools; a required output then
parked with "output %q is required" instead of the profile being refused.

WorkflowInterface.Needs now reports captures for a non-empty Outputs beside
the declared needs, and the profile check and Kit launcher read it. The
needs: block keeps its meaning for a workflow that captures without
declaring outputs.

- internal/domain/workflow/task: Needs() derives captures; DeclaredNeeds
  carries only the declared block.
- internal/daemon: pinTaskProfile and runKitTask read Needs().
- tests: parse-time derivation, and pinTaskProfile refusing an
  outputs-declaring workflow against a Kit adapter with no capture MCP.
This commit is contained in:
sam committed 2026-10-02 03:19:07 +10:00
1 parent 446d94681b
commit 721968eeff
8 files changed
+59 -21

No files matched your search

+2 -2
View File
@@ -154,7 +154,7 @@
"url": "/dev/development/workflows/",
"title": "Workflows",
"section": "Development",
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n\n## Enabling and disabling\n\nThe `workflow-enablement` control-plane resource lists, per org, the workflows\nthat org has disabled; anything unlisted is enabled. Its readers are the\ndaemon's binding dispatch (a disabled workflow's binding is skipped like an\nunarmed one), the dashboard's binding save (refused) and binding list\n(`workflow_disabled`), and work requests. A new reader of \"may this org run\nthis workflow\" goes through `task.WorkflowEnablement.Enabled`, never a second\nlist. The dashboard acts in the default org until access resolves a caller's\nown.\n\n## Starting a workflow from chat\n\n`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards\ninputs through the task creation contract; it does not interpret individual\nworkflows. The daemon checks inputs against the pinned `WorkflowInterface`\nbefore acquiring a container and parks invalid requests with the reason.\n"
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- A declared `outputs:` entry is written through a capture tool, so it forces\n the captures need: `task.WorkflowInterface.Needs` resolves that from the\n declaration rather than the author also writing `needs.captures`. A Kit\n profile whose harness serves no capture tools is refused before dispatch.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n\n## Enabling and disabling\n\nThe `workflow-enablement` control-plane resource lists, per org, the workflows\nthat org has disabled; anything unlisted is enabled. Its readers are the\ndaemon's binding dispatch (a disabled workflow's binding is skipped like an\nunarmed one), the dashboard's binding save (refused) and binding list\n(`workflow_disabled`), and work requests. A new reader of \"may this org run\nthis workflow\" goes through `task.WorkflowEnablement.Enabled`, never a second\nlist. The dashboard acts in the default org until access resolves a caller's\nown.\n\n## Starting a workflow from chat\n\n`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards\ninputs through the task creation contract; it does not interpret individual\nworkflows. The daemon checks inputs against the pinned `WorkflowInterface`\nbefore acquiring a container and parks invalid requests with the reason.\n"
},
{
"url": "/dev/prds/01-project-management/",
@@ -562,7 +562,7 @@
"url": "/dev/prds/workflow-call-outputs/",
"title": "Declared outputs of a workflow run",
"section": "PRDs",
"body": "# Declared outputs of a workflow run\n\n**Status:** Draft\n**Date:** 2026-09-30\n**Bead:** `archie-core-t2db.43`\n**Authority:** `docs/prds/event-automation.md` for what a declared output is,\n`docs/prds/workflow-calls.md` for the call and its grants,\n`docs/prds/state-store-contract.md` for the State Store contract the wire\nchange must satisfy.\n**Supersedes:** `docs/prds/workflow-calls.md`, \"Waiting on the callee\": the\ncallee's transition detail is the human summary, not the stand-in for\nstructured outputs.\n\nA workflow declares named, typed outputs. A run writes each one once. A\n`wait: true` caller receives them, and may publish one as its own.\n\n## Where outputs are declared\n\n`outputs:` on the workflow definition, beside `inputs:`, decoded into\n`task.WorkflowInterface.Outputs map[string]OutputSpec` where\n`OutputSpec{Type, Required}`:\n\n```yaml\nid: firewall-contain\noutputs:\n contained: { type: bool, required: true }\n summary: { type: string }\n```\n\nNames and types are the input grammar: the same identifier shape, the same\ntype set, and the same check in `WorkflowInterface.Validate`, which both\n`ParseDefinition` and `ParseWorkflowInterface` call.\n\n**Forced by:** `ParseDefinition` decodes with `KnownFields(true)`, so a key no\ndecoded struct declares is refused — the declaration must live on\n`WorkflowInterface` for an author to write it at all, and that is where\n`docs/development/workflows.md` puts every field a process without the engine\nmust read. The type set is the shared value vocabulary: `TypeAccepts` and\n`ValueType` already check a mapped parameter and an input with it. `required`\ndefaults to false, and the generated YAML for a builtin that declares no\noutputs is unchanged, because a definition's digest pins a run.\n\n**Rejected:** outputs per step, or per call step, because a workflow returns a\nresult as itself rather than as one of its stages. Also `task.Definition`\ngaining outputs: no reader needs them — a binding offers inputs, and a call's\noutputs assignment is checked against the callee's YAML in the same\ncollection — and a declared field with no reader parses and does nothing.\n\n## How a run writes one\n\nEach declared output is offered to the run's agent stages as a capture tool\nnamed after the output, whose arguments are `{\"value\": ...}`; the accepted\ncall's `value` member is the output's value. The engine holds the accepted\nvalues on the task context and writes them into its own task row in the\n`Store.Update` call the run already makes. A deterministic stage may set the\nsame values in Go, and the run's finish check validates them identically.\n\n**Forced by:** a run's only structured results are capture calls\n(`agentexec.CaptureTool`, `Result.Captures`), and the workflow interface\nalready declares when a stage needs them (`task.WorkflowNeeds.Captures`).\nDeriving the tools from the declaration means an output cannot be written\nunder a name nobody declared, and it keeps one route to structured agent\noutput rather than adding a second beside the capture path. The row write is\nthe run's existing write: the task row is where a run's own state lives, and\nthe container already holds `Update` on its own row.\n\nThe tool is offered with `MaxCalls: 1`, and a stage is not offered an output\nthe run has written, so a run writes each output once: a repeat within a stage\nis answered with the tool's rejection and the agent carries on, and a later\nstage cannot overwrite a value. A stage's own capture tool may not share a\nname with a declared output, because the value would otherwise be ambiguous.\n\n**Rejected:** a `workflow.output` step type, because assigning the run's\nresult from a step needs a grammar for \"the previous stage's result\" that does\nnot exist, and a step that reaches the agent would be the second path\n`docs/development/workflows.md` forbids. Also a write RPC of its own: the\ncontainer's `Update` already reaches its own row, and a second write verb for\none column is a second thing to keep in step.\n\n## How a caller receives one\n\nOn a successful `wait: true` call the caller's stage holds the callee's\noutputs as a `map[string]any`. A call step's `outputs:` setting publishes one\nas one of the caller's own outputs:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n wait: true\n inputs: { src_ip: inputs.src_ip }\n outputs: { contained: outputs.contained }\n```\n\nThe key names the callee's declared name; the value names one of the caller's\nown with the prefix the call's `inputs:` already uses. A published value joins\nthe caller's output set for its run, so a caller returns its callee's result to\nits own caller, and a run may publish a callee's output and write its own\nothers.\n\nLifetime is the attempt. The run starts with an empty output set, every later\nstage of that attempt sees the values, and the finish write replaces the row's\nset wholesale — so nothing an attemLine truncated
"body": "# Declared outputs of a workflow run\n\n**Status:** Draft\n**Date:** 2026-09-30\n**Bead:** `archie-core-t2db.43`\n**Authority:** `docs/prds/event-automation.md` for what a declared output is,\n`docs/prds/workflow-calls.md` for the call and its grants,\n`docs/prds/state-store-contract.md` for the State Store contract the wire\nchange must satisfy.\n**Supersedes:** `docs/prds/workflow-calls.md`, \"Waiting on the callee\": the\ncallee's transition detail is the human summary, not the stand-in for\nstructured outputs.\n\nA workflow declares named, typed outputs. A run writes each one once. A\n`wait: true` caller receives them, and may publish one as its own.\n\n## Where outputs are declared\n\n`outputs:` on the workflow definition, beside `inputs:`, decoded into\n`task.WorkflowInterface.Outputs map[string]OutputSpec` where\n`OutputSpec{Type, Required}`:\n\n```yaml\nid: firewall-contain\noutputs:\n contained: { type: bool, required: true }\n summary: { type: string }\n```\n\nNames and types are the input grammar: the same identifier shape, the same\ntype set, and the same check in `WorkflowInterface.Validate`, which both\n`ParseDefinition` and `ParseWorkflowInterface` call.\n\n**Forced by:** `ParseDefinition` decodes with `KnownFields(true)`, so a key no\ndecoded struct declares is refused — the declaration must live on\n`WorkflowInterface` for an author to write it at all, and that is where\n`docs/development/workflows.md` puts every field a process without the engine\nmust read. The type set is the shared value vocabulary: `TypeAccepts` and\n`ValueType` already check a mapped parameter and an input with it. `required`\ndefaults to false, and the generated YAML for a builtin that declares no\noutputs is unchanged, because a definition's digest pins a run.\n\n**Rejected:** outputs per step, or per call step, because a workflow returns a\nresult as itself rather than as one of its stages. Also `task.Definition`\ngaining outputs: no reader needs them — a binding offers inputs, and a call's\noutputs assignment is checked against the callee's YAML in the same\ncollection — and a declared field with no reader parses and does nothing.\n\n## How a run writes one\n\nEach declared output is offered to the run's agent stages as a capture tool\nnamed after the output, whose arguments are `{\"value\": ...}`; the accepted\ncall's `value` member is the output's value. The engine holds the accepted\nvalues on the task context and writes them into its own task row in the\n`Store.Update` call the run already makes. A deterministic stage may set the\nsame values in Go, and the run's finish check validates them identically.\n\n**Forced by:** a run's only structured results are capture calls\n(`agentexec.CaptureTool`, `Result.Captures`), and the workflow interface\nalready declares when a stage needs them (`task.WorkflowNeeds.Captures`).\n`WorkflowInterface.Needs` reports `captures` for a non-empty `Outputs`, so\ndeclaring an output alone requires the capability and a Kit profile that\nserves no capture tools is refused before dispatch.\nDeriving the tools from the declaration means an output cannot be written\nunder a name nobody declared, and it keeps one route to structured agent\noutput rather than adding a second beside the capture path. The row write is\nthe run's existing write: the task row is where a run's own state lives, and\nthe container already holds `Update` on its own row.\n\nThe tool is offered with `MaxCalls: 1`, and a stage is not offered an output\nthe run has written, so a run writes each output once: a repeat within a stage\nis answered with the tool's rejection and the agent carries on, and a later\nstage cannot overwrite a value. A stage's own capture tool may not share a\nname with a declared output, because the value would otherwise be ambiguous.\n\n**Rejected:** a `workflow.output` step type, because assigning the run's\nresult from a step needs a grammar for \"the previous stage's result\" that does\nnot exist, and a step that reaches the agent would be the second path\n`docs/development/workflows.md` forbids. Also a write RPC of its own: the\ncontainer's `Update` already reaches its own row, and a second write verb for\none column is a second thing to keep in step.\n\n## How a caller receives one\n\nOn a successful `wait: true` call the caller's stage holds the callee's\noutputs as a `map[string]any`. A call step's `outputs:` setting publishes one\nas one of the caller's own outputs:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n wait: true\n inputs: { src_ip: inputs.src_ip }\n outputs: { contained: outputs.contained }\n```\n\nThe key names the callee's declared name; the value names one of the caller's\nown with the prefix the call's `inputs:` already uses. A published value joins\nthe caller's output set for its run, so a caller returns its callee's result to\nits own caller, and a run may publish a callee's output and write its own\notheLine truncated
},
{
"url": "/dev/prds/workflow-calls/",
+4
View File
@@ -37,6 +37,10 @@ vocabulary it registers, so both must see the same step types.
- The YAML decoder rejects unknown keys. Existing stored definitions must keep
parsing, so a new key is optional with a default that preserves today's
behaviour.
- A declared `outputs:` entry is written through a capture tool, so it forces
the captures need: `task.WorkflowInterface.Needs` resolves that from the
declaration rather than the author also writing `needs.captures`. A Kit
profile whose harness serves no capture tools is refused before dispatch.
- Examples in `examples/workflows/` are parsed against the registered
vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.
+3
View File
@@ -58,6 +58,9 @@ same values in Go, and the run's finish check validates them identically.
**Forced by:** a run's only structured results are capture calls
(`agentexec.CaptureTool`, `Result.Captures`), and the workflow interface
already declares when a stage needs them (`task.WorkflowNeeds.Captures`).
`WorkflowInterface.Needs` reports `captures` for a non-empty `Outputs`, so
declaring an output alone requires the capability and a Kit profile that
serves no capture tools is refused before dispatch.
Deriving the tools from the declaration means an output cannot be written
under a name nobody declared, and it keeps one route to structured agent
output rather than adding a second beside the capture path. The row write is
+1 -1
View File
@@ -1921,7 +1921,7 @@ 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 {
if err = validateProfileMeetsNeeds(profile, iface.Needs); err == nil {
if err = validateProfileMeetsNeeds(profile, iface.Needs()); err == nil {
return profile, true
}
}
+13 -5
View File
@@ -2373,6 +2373,11 @@ func TestPinTaskProfileRefusesCapturesTheHarnessCannotServe(t *testing.T) {
{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"},
// A declared output is written through a capture tool, so it forces
// the captures need whether or not the author also wrote
// needs.captures (docs/prds/workflow-call-outputs.md).
{ID: "outputs-served", YAML: "id: outputs-served\nrepository: none\nprofile: serves-captures\noutputs: { summary: {type: string} }\nsteps:\n - type: agent.run\n settings: {mission: go}\n"},
{ID: "outputs-codex", YAML: "id: outputs-codex\nrepository: none\nprofile: no-captures\noutputs: { summary: {type: string, required: true} }\nsteps:\n - type: agent.run\n settings: {mission: go}\n"},
}}, version: 1}
ctx := context.Background()
@@ -2389,17 +2394,20 @@ func TestPinTaskProfileRefusesCapturesTheHarnessCannotServe(t *testing.T) {
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 i, servedWorkflow := range []string{"needs-captures-served", "outputs-served"} {
served := claim(51+i, servedWorkflow)
if _, ok := d.pinTaskProfile(ctx, served); !ok {
t.Fatalf("a Kit profile whose adapter serves captures was refused for %s", servedWorkflow)
}
}
for _, tt := range []struct {
number int
workflow string
}{
{52, "needs-captures-codex"},
{53, "needs-captures-bare"},
{53, "needs-captures-codex"},
{54, "needs-captures-bare"},
{55, "outputs-codex"},
} {
task := claim(tt.number, tt.workflow)
if _, ok := d.pinTaskProfile(ctx, task); ok {
+1 -1
View File
@@ -72,7 +72,7 @@ func (d *Daemon) runKitTask(ctx context.Context, task *workflow.Task, repo confi
Adapter: profile.Adapter,
WorkDir: workDir,
WorkerEnv: env,
GateRetries: iface.Needs.GateRetries,
GateRetries: iface.Needs().GateRetries,
Org: taskCfg.Org,
GrantedServices: taskCfg.GrantedCredentials,
})
+19 -10
View File
@@ -56,15 +56,24 @@ 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"`
// DeclaredNeeds is what the definition's needs: block declares. Read
// Needs, not this, when deciding a harness requirement: a declared output
// forces the captures capability and Needs resolves it.
DeclaredNeeds WorkflowNeeds `yaml:"needs" json:"needs"`
}
// Needs reports the harness requirements the interface carries: the declared
// needs, plus the captures a declared output forces, because an output is
// written through a capture tool (docs/prds/workflow-call-outputs.md, "How a
// run writes one"). Profile selection reads this rather than DeclaredNeeds,
// so a workflow that declares outputs cannot name a Kit profile whose harness
// serves no capture tools (docs/prds/external-agent-harness.md, "Contract").
func (w WorkflowInterface) Needs() WorkflowNeeds {
needs := w.DeclaredNeeds
if len(w.Outputs) > 0 {
needs.Captures = true
}
return needs
}
// WorkflowNeeds is WorkflowInterface's declared harness requirements.
@@ -116,7 +125,7 @@ func (w WorkflowInterface) Validate() error {
return fmt.Errorf("workflow output %q type %q must be one of %s", name, spec.Type, strings.Join(inputTypes, ", "))
}
}
if w.Needs.GateRetries < 0 {
if w.DeclaredNeeds.GateRetries < 0 {
return fmt.Errorf("workflow needs.gate_retries must not be negative")
}
return nil
@@ -47,8 +47,22 @@ func TestParseWorkflowInterfaceNeeds(t *testing.T) {
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)
if needs := w.Needs(); !needs.Captures || needs.GateRetries != 3 {
t.Fatalf("Needs() = %+v, want {Captures:true GateRetries:3}", needs)
}
}
// TestParseWorkflowInterfaceOutputsForceCaptures: an output is written
// through a capture tool, so declaring one forces the captures need whether
// or not the author also wrote needs.captures
// (docs/prds/workflow-call-outputs.md, "How a run writes one").
func TestParseWorkflowInterfaceOutputsForceCaptures(t *testing.T) {
w, err := ParseWorkflowInterface("id: a\noutputs:\n summary: {type: string}\n")
if err != nil {
t.Fatal(err)
}
if needs := w.Needs(); !needs.Captures {
t.Fatalf("Needs() = %+v, want Captures for a workflow that declares an output", needs)
}
}