From a98ca2c8e9adb347e7588bb95794a04db10db47d Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 26 Sep 2026 01:58:29 +1000 Subject: [PATCH] docs(prds): approve execution-tree and external-harness PRDs --- docs/data/generated/dev-docs.json | 4 ++-- docs/prds/execution-tree-state-machine.md | 2 +- docs/prds/external-agent-harness.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index c9a353062..0a72f6688 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -316,7 +316,7 @@ "url": "/dev/prds/execution-tree-state-machine/", "title": "Execution tree and enforced state machine", "section": "PRDs", - "body": "# Execution tree and enforced state machine\n\n**Status:** Draft\n**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);\nsettles the \"enforced WorkflowExecution state machine\" item in\n`docs/architecture/migration-decisions.md` section 4.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),\n`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).\n\n## Decision\n\nA WorkflowExecution becomes the root of a tree of StepExecutions. Every stage\nrun, and every agent call a stage makes, is its own durable record with a\nparent, an attempt, a status and an outcome. Both levels move only through a\ndeclared transition table, enforced by the State Store in the same transaction\nthat writes the audit row and the domain event.\n\n## Problem\n\n- A run is one `tasks` row. The only per-step record is the mutable `stage`\n column, overwritten as `workflow.Run` advances, plus observability events.\n A failed attempt cannot say which step failed or what its children did\n without replaying the event stream.\n- `Store.Transition` guards on the expected `from` status, but any `from` to\n any `to` is accepted. A `queued` to `merged` write succeeds.\n- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says\n which work was in flight, so an agent call that outlives its stage (a\n reviewer, a container) is invisible to the store.\n- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits\n `KindStageStart` separately. State and events can diverge.\n\n## Model\n\n```text\nWorkflowExecution (tasks row, id E)\n└── attempt N\n ├── StepExecution stage \"plan\" depth 0\n ├── StepExecution stage \"implement\" depth 0\n │ └── StepExecution agent \"implement\" depth 1\n └── StepExecution stage \"review\" depth 0\n ├── StepExecution agent \"review:1\" depth 1\n └── StepExecution agent \"review:2\" depth 1\n```\n\n- A StepExecution belongs to exactly one WorkflowExecution and one attempt.\n `parent_id` is null for a stage and names the enclosing StepExecution\n otherwise. Depth is derived from the parent, never supplied by the caller.\n- `kind` is `stage` or `agent`. A new kind needs a named consumer before it is\n added.\n- A retry starts a new attempt. Earlier attempts' StepExecutions are never\n rewritten.\n\n## Transition tables\n\nWorkflowExecution statuses are the existing `taskstate` constants, persisted\nstrings unchanged. `taskstate` gains the one table every writer checks:\n\n| From | To |\n| --------------- | ---------------------------------------------------------- |\n| `queued` | `running`, `closed_wont_do` |\n| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |\n| `waiting_human` | `queued` (approve), `closed_wont_do` |\n| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |\n| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |\n| terminal | none |\n\nStepExecution statuses:\n\n| From | To |\n| --------- | ------------------------------------------------------ |\n| `pending` | `running`, `cancelled` |\n| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |\n| terminal | none |\n\n`interrupted` means the process running the step died or shut down. It is\ndistinct from `cancelled`, which an operator or a parent asked for, and from\n`failed`, which the step reported.\n\nA StepExecution cannot reach `running` while its WorkflowExecution is not\n`running`, and cannot start under a terminal parent.\n\n## Enforcement\n\n- The table lives in `taskstate` (no dependencies), so the store, daemon and\n gateway share one copy.\n- Every store method that changes `tasks.status` checks the table and writes\n the audit and event rows, not only `Transition`. That includes the claim,\n `ParkTask`, `Requeue`, `RetryTask`, `BeginRemediation` and `RecoverStale`\n paths, several of which change status without an audit row.\n- The State Store rejects an illegal transition with a new sentinel,\n `ErrIllegalTransition`, carried across the wire through `mapError` like\n `ErrStaleTransition`. A stale `from` stays `ErrStaleTransition`.\n- Each transition is one transaction: guarded row update, audit row, domain\n event row. The events table is written by the store, not emitted beside it.\n `KindStageStart` and `KindStageFinish` are produced by the step transition\n and published to the bus after commit.\n- `workflow.Run` stops discarding persistence errors. A failed step write\n parks the execution; the step does not run unrecorded.\n\n## Cancellation\n\nStopping a run is one store call, `CancelExecution(E, reason)`. In one\ntransaction it moves every non-terminal StepExecution of the current attempt\nto `cancelled` and the WorkflowExecution to `closed_wont_do` or `parked`,\nwhichever the operator action names. The daemon then cancels the in-memory\ncontext. A worker whose step write returns `ErrStaleTransition` because its\nstep is already `cancelled` stops without writing further.\n\nThe store is the record of cancellation. The context cancel is the delivery\nmechanism, so a lost cancel still leaves the store correct and the worker's\nnext write fails.\n\n## Crash recovery\n\n`RecoverStale` moves every `running` StepExecution of an interrupted\nexecution to `interrupted` in the same transaction that requeues the\nexecution. The next attempt starts with fresh steps.\n\n## Wire contract\n\nNew State Store RPCs, each with a matching Go method on a narrow consumer\nfacade:\n\n- `StartStep(execution, attempt, parent, kind, name) -\u003e step id`\n- `FinishStep(step, from, to, detail, tokens_used)`\n- `CancelExecution(execution, reason, to)`\n- `ListSteps(execution, attempt)`\n\n`TaskGrants.UnaryInterceptor` authorises a task-scoped token for `StartStep`\nand `FinishStep` on its own execution only. The container records its own\nagent calls. `CancelExecution` and `ListSteps` require the administrative\ntoken.\n\n## Storage\n\nOne new table, `step_executions`: `id`, `execution_id`, `attempt`,\n`parent_id`, `depth`, `kind`, `name`, `status`, `detail`, `tokens_used`,\n`started_at`, `finished_at`. Indexed on `(execution_id, attempt, id)`.\nDeleting an execution (archive, clearing terminal tasks) deletes its steps.\nExisting rows gain no backfilled steps. Their history stays in `transitions`\nand `events`.\n\n`tasks.stage` is written from the step transition while any reader still uses\nit, then dropped once the dashboard reads `ListSteps`.\n\n## Out of scope\n\n- Running sibling steps in parallel. The tree records concurrency; changing\n the stage runner is separate work.\n- Cost in currency. `tokens_used` per step is the only usage field.\n- Workflow definition versioning and the `tasks` to `workflow_executions`\n rename.\n- A harness contract for swappable coding agents.\n\n## Plan\n\n1. `taskstate` transition tables with table-driven tests covering every\n legal and a sample of illegal pairs.\n2. `ErrIllegalTransition` enforced in the Postgres store and mapped over the\n wire.\n3. `step_executions` migration, `StartStep`/`FinishStep`, grant rules;\n `workflow.Run` records stages; events written in the transition\n transaction.\n4. Agent-call children recorded from the agent runtime.\n5. `CancelExecution`; daemon stop and chat/dashboard actions route through it.\n6. `RecoverStale` interrupts running steps.\n7. Dashboard run detail reads `ListSteps`; `tasks.stage` dropped.\n\n## Verification\n\n- An illegal WorkflowExecution or StepExecution transition returns\n `ErrIllegalTransition` over gRPC, and `errors.Is` matches on the client.\n- Killing the daemon mid-stage, then restarting, leaves that stage\n `interrupted` and the execution `queued` with a new attempt.\n- Stopping a run during review leaves every review child `cancelled`, and a\n late `FinishStep` from the container returns `ErrStaleTransition`.\n- A task-scoped token cannot `StartStep` on another execution.\n- For every step transition there is exactly one event row, written in the\n same transaction.\n" + "body": "# Execution tree and enforced state machine\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);\nsettles the \"enforced WorkflowExecution state machine\" item in\n`docs/architecture/migration-decisions.md` section 4.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),\n`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).\n\n## Decision\n\nA WorkflowExecution becomes the root of a tree of StepExecutions. Every stage\nrun, and every agent call a stage makes, is its own durable record with a\nparent, an attempt, a status and an outcome. Both levels move only through a\ndeclared transition table, enforced by the State Store in the same transaction\nthat writes the audit row and the domain event.\n\n## Problem\n\n- A run is one `tasks` row. The only per-step record is the mutable `stage`\n column, overwritten as `workflow.Run` advances, plus observability events.\n A failed attempt cannot say which step failed or what its children did\n without replaying the event stream.\n- `Store.Transition` guards on the expected `from` status, but any `from` to\n any `to` is accepted. A `queued` to `merged` write succeeds.\n- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says\n which work was in flight, so an agent call that outlives its stage (a\n reviewer, a container) is invisible to the store.\n- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits\n `KindStageStart` separately. State and events can diverge.\n\n## Model\n\n```text\nWorkflowExecution (tasks row, id E)\n└── attempt N\n ├── StepExecution stage \"plan\" depth 0\n ├── StepExecution stage \"implement\" depth 0\n │ └── StepExecution agent \"implement\" depth 1\n └── StepExecution stage \"review\" depth 0\n ├── StepExecution agent \"review:1\" depth 1\n └── StepExecution agent \"review:2\" depth 1\n```\n\n- A StepExecution belongs to exactly one WorkflowExecution and one attempt.\n `parent_id` is null for a stage and names the enclosing StepExecution\n otherwise. Depth is derived from the parent, never supplied by the caller.\n- `kind` is `stage` or `agent`. A new kind needs a named consumer before it is\n added.\n- A retry starts a new attempt. Earlier attempts' StepExecutions are never\n rewritten.\n\n## Transition tables\n\nWorkflowExecution statuses are the existing `taskstate` constants, persisted\nstrings unchanged. `taskstate` gains the one table every writer checks:\n\n| From | To |\n| --------------- | ---------------------------------------------------------- |\n| `queued` | `running`, `closed_wont_do` |\n| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |\n| `waiting_human` | `queued` (approve), `closed_wont_do` |\n| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |\n| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |\n| terminal | none |\n\nStepExecution statuses:\n\n| From | To |\n| --------- | ------------------------------------------------------ |\n| `pending` | `running`, `cancelled` |\n| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |\n| terminal | none |\n\n`interrupted` means the process running the step died or shut down. It is\ndistinct from `cancelled`, which an operator or a parent asked for, and from\n`failed`, which the step reported.\n\nA StepExecution cannot reach `running` while its WorkflowExecution is not\n`running`, and cannot start under a terminal parent.\n\n## Enforcement\n\n- The table lives in `taskstate` (no dependencies), so the store, daemon and\n gateway share one copy.\n- Every store method that changes `tasks.status` checks the table and writes\n the audit and event rows, not only `Transition`. That includes the claim,\n `ParkTask`, `Requeue`, `RetryTask`, `BeginRemediation` and `RecoverStale`\n paths, several of which change status without an audit row.\n- The State Store rejects an illegal transition with a new sentinel,\n `ErrIllegalTransition`, carried across the wire through `mapError` like\n `ErrStaleTransition`. A stale `from` stays `ErrStaleTransition`.\n- Each transition is one transaction: guarded row update, audit row, domain\n event row. The events table is written by the store, not emitted beside it.\n `KindStageStart` and `KindStageFinish` are produced by the step transition\n and published to the bus after commit.\n- `workflow.Run` stops discarding persistence errors. A failed step write\n parks the execution; the step does not run unrecorded.\n\n## Cancellation\n\nStopping a run is one store call, `CancelExecution(E, reason)`. In one\ntransaction it moves every non-terminal StepExecution of the current attempt\nto `cancelled` and the WorkflowExecution to `closed_wont_do` or `parked`,\nwhichever the operator action names. The daemon then cancels the in-memory\ncontext. A worker whose step write returns `ErrStaleTransition` because its\nstep is already `cancelled` stops without writing further.\n\nThe store is the record of cancellation. The context cancel is the delivery\nmechanism, so a lost cancel still leaves the store correct and the worker's\nnext write fails.\n\n## Crash recovery\n\n`RecoverStale` moves every `running` StepExecution of an interrupted\nexecution to `interrupted` in the same transaction that requeues the\nexecution. The next attempt starts with fresh steps.\n\n## Wire contract\n\nNew State Store RPCs, each with a matching Go method on a narrow consumer\nfacade:\n\n- `StartStep(execution, attempt, parent, kind, name) -\u003e step id`\n- `FinishStep(step, from, to, detail, tokens_used)`\n- `CancelExecution(execution, reason, to)`\n- `ListSteps(execution, attempt)`\n\n`TaskGrants.UnaryInterceptor` authorises a task-scoped token for `StartStep`\nand `FinishStep` on its own execution only. The container records its own\nagent calls. `CancelExecution` and `ListSteps` require the administrative\ntoken.\n\n## Storage\n\nOne new table, `step_executions`: `id`, `execution_id`, `attempt`,\n`parent_id`, `depth`, `kind`, `name`, `status`, `detail`, `tokens_used`,\n`started_at`, `finished_at`. Indexed on `(execution_id, attempt, id)`.\nDeleting an execution (archive, clearing terminal tasks) deletes its steps.\nExisting rows gain no backfilled steps. Their history stays in `transitions`\nand `events`.\n\n`tasks.stage` is written from the step transition while any reader still uses\nit, then dropped once the dashboard reads `ListSteps`.\n\n## Out of scope\n\n- Running sibling steps in parallel. The tree records concurrency; changing\n the stage runner is separate work.\n- Cost in currency. `tokens_used` per step is the only usage field.\n- Workflow definition versioning and the `tasks` to `workflow_executions`\n rename.\n- A harness contract for swappable coding agents.\n\n## Plan\n\n1. `taskstate` transition tables with table-driven tests covering every\n legal and a sample of illegal pairs.\n2. `ErrIllegalTransition` enforced in the Postgres store and mapped over the\n wire.\n3. `step_executions` migration, `StartStep`/`FinishStep`, grant rules;\n `workflow.Run` records stages; events written in the transition\n transaction.\n4. Agent-call children recorded from the agent runtime.\n5. `CancelExecution`; daemon stop and chat/dashboard actions route through it.\n6. `RecoverStale` interrupts running steps.\n7. Dashboard run detail reads `ListSteps`; `tasks.stage` dropped.\n\n## Verification\n\n- An illegal WorkflowExecution or StepExecution transition returns\n `ErrIllegalTransition` over gRPC, and `errors.Is` matches on the client.\n- Killing the daemon mid-stage, then restarting, leaves that stage\n `interrupted` and the execution `queued` with a new attempt.\n- Stopping a run during review leaves every review child `cancelled`, and a\n late `FinishStep` from the container returns `ErrStaleTransition`.\n- A task-scoped token cannot `StartStep` on another execution.\n- For every step transition there is exactly one event row, written in the\n same transaction.\n" }, { "url": "/dev/prds/extensions-center/", @@ -328,7 +328,7 @@ "url": "/dev/prds/external-agent-harness/", "title": "External agent harnesses", "section": "PRDs", - "body": "# External agent harnesses\n\n**Status:** Draft\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit the operator builds `FROM` or alongside the harness Kit. It is\nversioned image content, rewritten on every create, never state a run can\nmodify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nOrder of precedence, first match wins:\n\n1. the stage's `runner` in the workflow definition;\n2. the agent profile's `runner`;\n3. `builtin`, the ai-sdk agent loop.\n\n`runner` names a harness resource. `archie-agent` reads it when it builds the\nstage's runner; that is its only consumer. An unknown name, and a harness\nnamed by no stage and no profile, are validation errors.\n\nA harness resource holds the workload Kit reference pinned by digest, zero or\nmore mixin Kit references, the credential bindings it uses, and\n`max_concurrent` (default 1). Harness resources and credential bindings are\nState Store resources managed from the dashboard, so they apply without a\nrestart.\n\n## Credentials\n\nA credential binding is keyed by the Kit's `credential@1` `service` name and\nholds one of:\n\n- **API key:** a `{ engine, key }` secret reference resolved through\n `internal/secret`.\n- **OAuth:** tokens captured by the setup terminal, stored in the State Store\n under the at-rest envelope of `binding-secret-encryption.md` with its own\n domain separator.\n\nThe egress proxy resolves the binding for each request. The container gets\nthe Kit's sentinel in the named variable or credential file. OAuth refresh\nhappens at the proxy, which intercepts the Kit's `tokenEndpoint`, so a\nrefreshed token is written to the State Store and never returned to the\ncontainer.\n\nRuns sharing an OAuth binding share its subscription's rate limit.\n`max_concurrent` is enforced per binding, summed across harnesses that use\nit. A stage waiting for a slot is `pending`, not `running`.\n\n## Setup terminal\n\nThe dashboard opens an operator-only terminal (xterm.js over a WebSocket to a\nPTY) into an ephemeral container built from the harness's Kits, on the same\negress proxy. The operator runs the CLI's own login. The proxy captures the\ntokens at the token endpoint into the credential binding. The container is\nremoved when the terminal closes. No worktree is mounted into it.\n\nThe terminal requires the administrative role. It is the only interactive\npath into a harness container.\n\n## Egress proxy\n\nThe egress proxy runs inside `archied`. Task and setup containers attach to\nan internal Docker network whose only reachable endpoint is the proxy, so\negress outside the policy fails at the network, not by convention. The proxy\nterminates TLS with a per-daemon CA installed into the container at create,\nidentifies the container by a per-container proxy token, and applies that\ncontainer's resolved `network-policy@1` and `credential@1` inject rules.\n\n## Container layout\n\n- The task worktree is mounted at the Kit's workspace directory. Nothing else\n from the host is mounted, except the read-only skills store.\n- Archie mounts its own `archie-agent` binary read-only, so published Kits\n need not contain it. `archie-agent` drives the harness as a subprocess and\n serves `archie-agent mcp`.\n- `volume@1` paths persist for the life of the WorkflowExecution, which\n covers session resume across gate iterations and retries. They are not\n shared between executions.\n\n## Archie tools inside the harness\n\nCapture tools, which are how a stage returns structured results, are served\nby `archie-agent mcp`, a stdio MCP server registered through the Kit's MCP\nconfiguration or the adapter's flags. It serves the stage's `CaptureTools`\nand the central tools the agent profile's `AllowTools` permits, never the\n`workspace` toolset. The runner's `ToolLimits` bound its results; the\nharness's own built-in tools are outside archie's limits.\n\n## Enforcement around the harness\n\n| Property | Enforcement |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Model never runs git | No forge credential can be bound. Archie records `HEAD` and every ref before the run; any change fails the step (`failed`, policy class). The workflow commits the stage's changes. |\n| Protected paths | A diff touching a `Protection` path fails the step. |\n| Read-only stage | Any worktree diff fails the step. |\n| Gate | Archie runs the stage's gate after the harness exits. On failure it resumes the session with the gate output, up to the stage's iteration budget. |\n| Budget | Archie kills the process on wall-clock timeout, or when streamed usage passes the token budget. |\n| Cancellation | Cancelling the step kills the process group, then the container. |\n| Egress | Only the proxy is reachable; the Kit's network policy decides the rest. |\n\nHarness settings that deny git or protected paths are added where the CLI\nsupports them, to save wasted turns. They are never the enforcement.\n\n## Execution tree\n\nA harness run is one `agent` StepExecution. Subagents the harness spawns\ninternally are not recorded as children. Their usage is included in the\nstep's `tokens_used` when the adapter reports it.\n\n## Agents never hold a harness\n\nAn Agent reaches a harness only by invoking a Workflow whose stage names it.\nNo Agent tool, chat tool or capability exposes a harness, its setup terminal\nor its credential. The stage boundary is what carries the container, the git\nand path checks, the gate and the budget; a harness outside a stage has none\nof them.\n\n## Out of scope\n\n- Chat through a harness. The gateway chat loop stays on the built-in\n runtime.\n- `network-policy@2` HTTP method and path rules; a Kit requiring it is\n refused.\n- Recording the harness's internal subagents as StepExecutions.\n- Cost in currency.\n- Choosing a harness automatically per task.\n\n## Plan\n\n1. Descriptor resolution with the Kit spec package; capability support\n table and fail-closed refusal.\n2. Egress proxy: internal network, per-daemon CA, per-container token,\n `network-policy@1`.\n3. `credential@1`: API-key bindings, sentinel rendering, inject rules.\n4. Harness `Runner`: container create with worktree, volumes, lifecycle\n hooks and the mounted `archie-agent`; `agent-sessions@1` invocation;\n worktree checks for git, protected paths and read-only; budget and\n cancellation.\n5. Claude Code output adapter; `archie-agent mcp`; gate-and-resume loop.\n6. Harness resources, selection precedence and definition validation.\n7. OAuth bindings: token-endpoint interception, encrypted storage, per-binding\n concurrency; dashboard setup terminal.\n8. Output adapters for Codex, Pi, OMP and GitHub Copilot CLI.\n\n## Verification\n\n- The same workflow definition completes on `builtin` and on the Claude Code\n Kit with the same `Result` shape and captures.\n- After `/login` in the setup terminal, the container's credential file holds\n only sentinels, the State Store holds the encrypted token, and a task run\n authenticates.\n- A real API key or OAuth token never appears in the container environment,\n filesystem, worktree, task log or event stream.\n- A request to a host outside the Kit's runtime allow list fails, including a\n direct connection that bypasses the proxy settings.\n- A harness instructed to `git commit` fails its step, and the task branch is\n unchanged.\n- A harness edit to a protected test file fails the step in a TDD fix stage.\n- A read-only feasibility stage that writes a file fails.\n- A file a run writes into a Kit-managed path such as the CLI's settings file\n is gone on the next execution.\n- A Kit requiring an unsupported capability is refused at launch with the\n capability named.\n- A stage with a failing gate resumes the same session with the gate output,\n then succeeds or exhausts its iterations.\n- Two tasks sharing an OAuth binding with `max_concurrent = 1` run one at a\n time; the second waits as `pending`.\n- Stopping a run kills the harness process and removes the container.\n" + "body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit the operator builds `FROM` or alongside the harness Kit. It is\nversioned image content, rewritten on every create, never state a run can\nmodify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nOrder of precedence, first match wins:\n\n1. the stage's `runner` in the workflow definition;\n2. the agent profile's `runner`;\n3. `builtin`, the ai-sdk agent loop.\n\n`runner` names a harness resource. `archie-agent` reads it when it builds the\nstage's runner; that is its only consumer. An unknown name, and a harness\nnamed by no stage and no profile, are validation errors.\n\nA harness resource holds the workload Kit reference pinned by digest, zero or\nmore mixin Kit references, the credential bindings it uses, and\n`max_concurrent` (default 1). Harness resources and credential bindings are\nState Store resources managed from the dashboard, so they apply without a\nrestart.\n\n## Credentials\n\nA credential binding is keyed by the Kit's `credential@1` `service` name and\nholds one of:\n\n- **API key:** a `{ engine, key }` secret reference resolved through\n `internal/secret`.\n- **OAuth:** tokens captured by the setup terminal, stored in the State Store\n under the at-rest envelope of `binding-secret-encryption.md` with its own\n domain separator.\n\nThe egress proxy resolves the binding for each request. The container gets\nthe Kit's sentinel in the named variable or credential file. OAuth refresh\nhappens at the proxy, which intercepts the Kit's `tokenEndpoint`, so a\nrefreshed token is written to the State Store and never returned to the\ncontainer.\n\nRuns sharing an OAuth binding share its subscription's rate limit.\n`max_concurrent` is enforced per binding, summed across harnesses that use\nit. A stage waiting for a slot is `pending`, not `running`.\n\n## Setup terminal\n\nThe dashboard opens an operator-only terminal (xterm.js over a WebSocket to a\nPTY) into an ephemeral container built from the harness's Kits, on the same\negress proxy. The operator runs the CLI's own login. The proxy captures the\ntokens at the token endpoint into the credential binding. The container is\nremoved when the terminal closes. No worktree is mounted into it.\n\nThe terminal requires the administrative role. It is the only interactive\npath into a harness container.\n\n## Egress proxy\n\nThe egress proxy runs inside `archied`. Task and setup containers attach to\nan internal Docker network whose only reachable endpoint is the proxy, so\negress outside the policy fails at the network, not by convention. The proxy\nterminates TLS with a per-daemon CA installed into the container at create,\nidentifies the container by a per-container proxy token, and applies that\ncontainer's resolved `network-policy@1` and `credential@1` inject rules.\n\n## Container layout\n\n- The task worktree is mounted at the Kit's workspace directory. Nothing else\n from the host is mounted, except the read-only skills store.\n- Archie mounts its own `archie-agent` binary read-only, so published Kits\n need not contain it. `archie-agent` drives the harness as a subprocess and\n serves `archie-agent mcp`.\n- `volume@1` paths persist for the life of the WorkflowExecution, which\n covers session resume across gate iterations and retries. They are not\n shared between executions.\n\n## Archie tools inside the harness\n\nCapture tools, which are how a stage returns structured results, are served\nby `archie-agent mcp`, a stdio MCP server registered through the Kit's MCP\nconfiguration or the adapter's flags. It serves the stage's `CaptureTools`\nand the central tools the agent profile's `AllowTools` permits, never the\n`workspace` toolset. The runner's `ToolLimits` bound its results; the\nharness's own built-in tools are outside archie's limits.\n\n## Enforcement around the harness\n\n| Property | Enforcement |\n| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Model never runs git | No forge credential can be bound. Archie records `HEAD` and every ref before the run; any change fails the step (`failed`, policy class). The workflow commits the stage's changes. |\n| Protected paths | A diff touching a `Protection` path fails the step. |\n| Read-only stage | Any worktree diff fails the step. |\n| Gate | Archie runs the stage's gate after the harness exits. On failure it resumes the session with the gate output, up to the stage's iteration budget. |\n| Budget | Archie kills the process on wall-clock timeout, or when streamed usage passes the token budget. |\n| Cancellation | Cancelling the step kills the process group, then the container. |\n| Egress | Only the proxy is reachable; the Kit's network policy decides the rest. |\n\nHarness settings that deny git or protected paths are added where the CLI\nsupports them, to save wasted turns. They are never the enforcement.\n\n## Execution tree\n\nA harness run is one `agent` StepExecution. Subagents the harness spawns\ninternally are not recorded as children. Their usage is included in the\nstep's `tokens_used` when the adapter reports it.\n\n## Agents never hold a harness\n\nAn Agent reaches a harness only by invoking a Workflow whose stage names it.\nNo Agent tool, chat tool or capability exposes a harness, its setup terminal\nor its credential. The stage boundary is what carries the container, the git\nand path checks, the gate and the budget; a harness outside a stage has none\nof them.\n\n## Out of scope\n\n- Chat through a harness. The gateway chat loop stays on the built-in\n runtime.\n- `network-policy@2` HTTP method and path rules; a Kit requiring it is\n refused.\n- Recording the harness's internal subagents as StepExecutions.\n- Cost in currency.\n- Choosing a harness automatically per task.\n\n## Plan\n\n1. Descriptor resolution with the Kit spec package; capability support\n table and fail-closed refusal.\n2. Egress proxy: internal network, per-daemon CA, per-container token,\n `network-policy@1`.\n3. `credential@1`: API-key bindings, sentinel rendering, inject rules.\n4. Harness `Runner`: container create with worktree, volumes, lifecycle\n hooks and the mounted `archie-agent`; `agent-sessions@1` invocation;\n worktree checks for git, protected paths and read-only; budget and\n cancellation.\n5. Claude Code output adapter; `archie-agent mcp`; gate-and-resume loop.\n6. Harness resources, selection precedence and definition validation.\n7. OAuth bindings: token-endpoint interception, encrypted storage, per-binding\n concurrency; dashboard setup terminal.\n8. Output adapters for Codex, Pi, OMP and GitHub Copilot CLI.\n\n## Verification\n\n- The same workflow definition completes on `builtin` and on the Claude Code\n Kit with the same `Result` shape and captures.\n- After `/login` in the setup terminal, the container's credential file holds\n only sentinels, the State Store holds the encrypted token, and a task run\n authenticates.\n- A real API key or OAuth token never appears in the container environment,\n filesystem, worktree, task log or event stream.\n- A request to a host outside the Kit's runtime allow list fails, including a\n direct connection that bypasses the proxy settings.\n- A harness instructed to `git commit` fails its step, and the task branch is\n unchanged.\n- A harness edit to a protected test file fails the step in a TDD fix stage.\n- A read-only feasibility stage that writes a file fails.\n- A file a run writes into a Kit-managed path such as the CLI's settings file\n is gone on the next execution.\n- A Kit requiring an unsupported capability is refused at launch with the\n capability named.\n- A stage with a failing gate resumes the same session with the gate output,\n then succeeds or exhausts its iterations.\n- Two tasks sharing an OAuth binding with `max_concurrent = 1` run one at a\n time; the second waits as `pending`.\n- Stopping a run kills the harness process and removes the container.\n" }, { "url": "/dev/prds/identity-decision/", diff --git a/docs/prds/execution-tree-state-machine.md b/docs/prds/execution-tree-state-machine.md index def7f6c07..d5f90d601 100644 --- a/docs/prds/execution-tree-state-machine.md +++ b/docs/prds/execution-tree-state-machine.md @@ -1,6 +1,6 @@ # Execution tree and enforced state machine -**Status:** Draft +**Status:** Approved **Authority:** `docs/architecture/agent-system.md` (canonical workflow model); settles the "enforced WorkflowExecution state machine" item in `docs/architecture/migration-decisions.md` section 4. diff --git a/docs/prds/external-agent-harness.md b/docs/prds/external-agent-harness.md index 6009e870b..3f941e8e8 100644 --- a/docs/prds/external-agent-harness.md +++ b/docs/prds/external-agent-harness.md @@ -1,6 +1,6 @@ # External agent harnesses -**Status:** Draft +**Status:** Approved **Authority:** `docs/architecture/agent-system.md` (agent execution as a data boundary); settles the harness non-goal deferred by `docs/prds/service-decomposition.md`.