From 721968eeff5751cfb60e93aa5b5435d24a5dd8dc Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 2 Oct 2026 03:12:29 +1000 Subject: [PATCH] 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. --- docs/data/generated/dev-docs.json | 4 +-- docs/development/workflows.md | 4 +++ docs/prds/workflow-call-outputs.md | 3 ++ internal/daemon/daemon.go | 2 +- internal/daemon/daemon_test.go | 18 ++++++++---- internal/daemon/kit_task.go | 2 +- internal/domain/workflow/task/interface.go | 29 ++++++++++++------- .../domain/workflow/task/interface_test.go | 18 ++++++++++-- 8 files changed, 59 insertions(+), 21 deletions(-) diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 4013e0162..d06638ffd 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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 attempt wrote survives into the next, and a run\nthat writes nothing stores nothing. Values reach a caller only from a\nsuccessful terminal state: the caller assigns them after `callSucceeded`, so a\nparked or failed callee delivers nothing whatever its row holds. A call step\nwith `wait: false` and an `outputs:` block is refused when the definition is\nsaved, because nothing has finished when the caller moves on.\n\n**Forced by:** caller and callee are separate runs in separate containers, so\nthe caller's own row is the only durable place to hold a received value. The\nprefix rule is not a new grammar: in `inputs.\u003cname\u003e` the prefixed side is the\ncaller's own value and the map key is the callee's, and `outputs.\u003cname\u003e` reads\nthe same way in the other direction.\n\n**Rejected:** an implicit same-name copy from callee to caller, because the\ncaller's contract would then depend on a callee it does not name, and swapping\nthe callee would silently change what the caller returns. Also letting a later\nstage read a callee's output in its mission text: that needs a stage-result\nreference namespace this model does not define.\n\n## Failure rules\n\n- **Undeclared value.** The agent path cannot produce one — the tool exists\n only for a declared output. A Go stage that sets an undeclared key parks the\n run before its outcome transition, and a stage capture tool sharing a\n declared output's name is refused when the run starts.\n- **Declared but never written.** With `required: true` the run parks naming\n the output and reaches no successful terminal state, so no caller observes a\n success missing a promised value. Without it the key is absent from the\n object rather than null, and a written `null` counts as not written, as\n `CheckInputs` treats a null input. A published output the callee never wrote\n leaves the caller's output absent, which the caller's own `required` then\n judges.\n- **Save time.** `WorkflowInterface.Validate` refuses an unknown type and a\n malformed name. A call step's `outputs:` assignment is checked by a\n `checkCallOutputs` beside `checkCallInputs`: the key must be declared by the\n callee, the reference must name an output the caller declares, and the\n callee's declared type must satisfy the caller's.\n- **Run time.** A captured value is re-validated against the declared type\n when the run reads it back, for the reason `readCaptures` re-checks every\n record: the captures file is writable by the harness user. A published\n callee value is re-checked against the caller's declared type before it\n enters the caller's set; a mismatch parks the caller naming the output.\n\n**Rejected:** typing at save time only, because a captured value has no\nsave-time form; and at run time only, because a definition error would surface\nas a failed run instead of a refused save.\n\n## Storage and wire\n\n- `tasks.outputs`, text, `NOT NULL DEFAULT ''`, written by the run's own row\n write — the shape `tasks.inputs` already has, with `EncodeOutputs` and\n `DecodeOutputs` beside `EncodeInputs`/`DecodeInputs`.\n- The `Task` message carries it as `outputs_json`, because the container's\n `Update` sends the whole row and a column the message cannot carry is a\n column that write drops.\n- `WorkflowCallStatusResponse` carries it as `outputs_json` beside `status`\n and `detail`, read from the callee's row by the handler that already\n verifies `call_parent_task_id`; `detail` keeps carrying the transition\n detail. The Go facade stays the two methods of `task.Caller`; no interface\n method is added.\n\n**Forced by the grant:** a caller authenticates as its own task and may reach\n`WorkflowCallStatus` on its own task ID, `Update`/`Transition`/`InsertEvent`\non its own row, and the step-execution pair on its own execution. It can read\nneither the callee's row nor the callee's steps. `WorkflowCallStatus` is\ntherefore the only channel that exists, and it is already the sanctioned\ncross-run read — this model fills the placeholder it carries. The values live\non the callee's row rather than on the caller's call step because the callee\nwrites them and the caller only receives them.\n\nThe write order is part of the contract: a run persists its outputs before its\noutcome transition, so the status a caller sees when its wait ends already\ncarries them. A set whose encoded form passes the bound the store applies to a\nstructured payload (`clip`, as `ReviewPayload` is stored) is refused rather\nthan clipped, because clipped JSON does not parse.\n\nNo sentinel moves: a missing required output is an engine park reason, and a\ncaller asking about a task that is not its callee still gets `ErrCallNotYours`,\nso nothing new crosses `mapError`/`unmapError` and no canonical message string\nchanges.\n\n**Rejected:**\n- A new read RPC (`WorkflowCallOutputs`) — a second poll of a row the caller\n already polls, whose answer could disagree with the status beside it, and a\n second grant-widening row for the same parent-child check.\n- The step-execution record — `ListSteps` is granted by `read` on a run, so a\n caller cannot read the callee's steps at all, and making them readable would\n hand it the callee's whole step history, which the parent-child check exists\n to prevent. A step's `detail` is text clipped like every other detail.\n- The caller's call step as the store — the value originates in another\n process and must outlive the container that produced it.\n\n## Out of scope\n\n- A run started by a binding: it has no caller, and its outputs live on its\n own row only.\n- A stage reference to a previous stage's captured value.\n- Assigning outputs in a caller cancelled while it waits.\n\n## Verification\n\n- A definition whose output type is not in the vocabulary, and a call\n publishing an output neither side declares, are refused when saved.\n- A `wait: true` caller receives a value its callee wrote, returns it as its\n own output, and the caller's row carries it.\n- A run whose required output is never written parks, and its caller's stage\n fails naming the output.\n- A call step publishing an output over `wait: false` is refused when saved.\n- A retried attempt that writes no outputs leaves an empty set on the row.\n- An example under `examples/workflows/` carries an `outputs:` block and a\n call that publishes one, which `TestExampleWorkflowsParse` covers.\n" + "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\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 attempt wrote survives into the next, and a run\nthat writes nothing stores nothing. Values reach a caller only from a\nsuccessful terminal state: the caller assigns them after `callSucceeded`, so a\nparked or failed callee delivers nothing whatever its row holds. A call step\nwith `wait: false` and an `outputs:` block is refused when the definition is\nsaved, because nothing has finished when the caller moves on.\n\n**Forced by:** caller and callee are separate runs in separate containers, so\nthe caller's own row is the only durable place to hold a received value. The\nprefix rule is not a new grammar: in `inputs.\u003cname\u003e` the prefixed side is the\ncaller's own value and the map key is the callee's, and `outputs.\u003cname\u003e` reads\nthe same way in the other direction.\n\n**Rejected:** an implicit same-name copy from callee to caller, because the\ncaller's contract would then depend on a callee it does not name, and swapping\nthe callee would silently change what the caller returns. Also letting a later\nstage read a callee's output in its mission text: that needs a stage-result\nreference namespace this model does not define.\n\n## Failure rules\n\n- **Undeclared value.** The agent path cannot produce one — the tool exists\n only for a declared output. A Go stage that sets an undeclared key parks the\n run before its outcome transition, and a stage capture tool sharing a\n declared output's name is refused when the run starts.\n- **Declared but never written.** With `required: true` the run parks naming\n the output and reaches no successful terminal state, so no caller observes a\n success missing a promised value. Without it the key is absent from the\n object rather than null, and a written `null` counts as not written, as\n `CheckInputs` treats a null input. A published output the callee never wrote\n leaves the caller's output absent, which the caller's own `required` then\n judges.\n- **Save time.** `WorkflowInterface.Validate` refuses an unknown type and a\n malformed name. A call step's `outputs:` assignment is checked by a\n `checkCallOutputs` beside `checkCallInputs`: the key must be declared by the\n callee, the reference must name an output the caller declares, and the\n callee's declared type must satisfy the caller's.\n- **Run time.** A captured value is re-validated against the declared type\n when the run reads it back, for the reason `readCaptures` re-checks every\n record: the captures file is writable by the harness user. A published\n callee value is re-checked against the caller's declared type before it\n enters the caller's set; a mismatch parks the caller naming the output.\n\n**Rejected:** typing at save time only, because a captured value has no\nsave-time form; and at run time only, because a definition error would surface\nas a failed run instead of a refused save.\n\n## Storage and wire\n\n- `tasks.outputs`, text, `NOT NULL DEFAULT ''`, written by the run's own row\n write — the shape `tasks.inputs` already has, with `EncodeOutputs` and\n `DecodeOutputs` beside `EncodeInputs`/`DecodeInputs`.\n- The `Task` message carries it as `outputs_json`, because the container's\n `Update` sends the whole row and a column the message cannot carry is a\n column that write drops.\n- `WorkflowCallStatusResponse` carries it as `outputs_json` beside `status`\n and `detail`, read from the callee's row by the handler that already\n verifies `call_parent_task_id`; `detail` keeps carrying the transition\n detail. The Go facade stays the two methods of `task.Caller`; no interface\n method is added.\n\n**Forced by the grant:** a caller authenticates as its own task and may reach\n`WorkflowCallStatus` on its own task ID, `Update`/`Transition`/`InsertEvent`\non its own row, and the step-execution pair on its own execution. It can read\nneither the callee's row nor the callee's steps. `WorkflowCallStatus` is\ntherefore the only channel that exists, and it is already the sanctioned\ncross-run read — this model fills the placeholder it carries. The values live\non the callee's row rather than on the caller's call step because the callee\nwrites them and the caller only receives them.\n\nThe write order is part of the contract: a run persists its outputs before its\noutcome transition, so the status a caller sees when its wait ends already\ncarries them. A set whose encoded form passes the bound the store applies to a\nstructured payload (`clip`, as `ReviewPayload` is stored) is refused rather\nthan clipped, because clipped JSON does not parse.\n\nNo sentinel moves: a missing required output is an engine park reason, and a\ncaller asking about a task that is not its callee still gets `ErrCallNotYours`,\nso nothing new crosses `mapError`/`unmapError` and no canonical message string\nchanges.\n\n**Rejected:**\n- A new read RPC (`WorkflowCallOutputs`) — a second poll of a row the caller\n already polls, whose answer could disagree with the status beside it, and a\n second grant-widening row for the same parent-child check.\n- The step-execution record — `ListSteps` is granted by `read` on a run, so a\n caller cannot read the callee's steps at all, and making them readable would\n hand it the callee's whole step history, which the parent-child check exists\n to prevent. A step's `detail` is text clipped like every other detail.\n- The caller's call step as the store — the value originates in another\n process and must outlive the container that produced it.\n\n## Out of scope\n\n- A run started by a binding: it has no caller, and its outputs live on its\n own row only.\n- A stage reference to a previous stage's captured value.\n- Assigning outputs in a caller cancelled while it waits.\n\n## Verification\n\n- A definition whose output type is not in the vocabulary, and a call\n publishing an output neither side declares, are refused when saved.\n- A `wait: true` caller receives a value its callee wrote, returns it as its\n own output, and the caller's row carries it.\n- A run whose required output is never written parks, and its caller's stage\n fails naming the output.\n- A call step publishing an output over `wait: false` is refused when saved.\n- A retried attempt that writes no outputs leaves an empty set on the row.\n- An example under `examples/workflows/` carries an `outputs:` block and a\n call that publishes one, which `TestExampleWorkflowsParse` covers.\n" }, { "url": "/dev/prds/workflow-calls/", diff --git a/docs/development/workflows.md b/docs/development/workflows.md index e27a43a43..d6ab1f52d 100644 --- a/docs/development/workflows.md +++ b/docs/development/workflows.md @@ -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. diff --git a/docs/prds/workflow-call-outputs.md b/docs/prds/workflow-call-outputs.md index 4630b3885..b042c52fd 100644 --- a/docs/prds/workflow-call-outputs.md +++ b/docs/prds/workflow-call-outputs.md @@ -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 diff --git a/internal/daemon/daemon.go b/internal/daemon/daemon.go index 75e41654a..bc6fcc2f8 100644 --- a/internal/daemon/daemon.go +++ b/internal/daemon/daemon.go @@ -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 } } diff --git a/internal/daemon/daemon_test.go b/internal/daemon/daemon_test.go index 8bade0724..31187b55e 100644 --- a/internal/daemon/daemon_test.go +++ b/internal/daemon/daemon_test.go @@ -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 { diff --git a/internal/daemon/kit_task.go b/internal/daemon/kit_task.go index ebb494e73..201da5508 100644 --- a/internal/daemon/kit_task.go +++ b/internal/daemon/kit_task.go @@ -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, }) diff --git a/internal/domain/workflow/task/interface.go b/internal/domain/workflow/task/interface.go index 12a023caa..faee5893e 100644 --- a/internal/domain/workflow/task/interface.go +++ b/internal/domain/workflow/task/interface.go @@ -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 diff --git a/internal/domain/workflow/task/interface_test.go b/internal/domain/workflow/task/interface_test.go index 677252412..840ccd1df 100644 --- a/internal/domain/workflow/task/interface_test.go +++ b/internal/domain/workflow/task/interface_test.go @@ -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) } }