diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 9376dcf69..105d32ce6 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:** 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" + "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`, `agent` or `call`. A new kind needs a named consumer\n before it is added.\n- A `workflow.call` step (`docs/prds/event-automation.md`) is a `call`\n StepExecution in the caller's tree. The callee is its own\n WorkflowExecution, with its own tree, acting as its own identity, and the\n `call` step records the callee's execution ID. Trees never nest across\n executions, so each run's tree stays inside that run's authority.\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\nCancelling a caller cancels each callee it is waiting on (`wait: true`),\nthrough `CancelExecution` on the callee under the callee's own lifecycle. A\ncallee started with `wait: false` runs on.\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\nThe run credential of `docs/prds/orgs-and-access.md` authorises `StartStep`\nand `FinishStep` on its own execution only, and the container records its own\nagent calls with it. `CancelExecution` and `ListSteps` are dashboard, API and\ndispatch actions, decided by the Authorizer: `update` and `read` on the run.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary. A StepExecution belongs to its\nWorkflowExecution's org and workspace and carries their `org_id` and\n`workspace_id`, like every owned record. The State Store stamps both from the\ncredential on `StartStep` and ignores them in the request. `ListSteps` for an\nexecution in another org returns the store's ordinary not-found error.\n\n## Storage\n\nOne new table, `step_executions`: `id`, `org_id`, `workspace_id`,\n`execution_id`, `attempt`, `parent_id`, `depth`, `kind`, `name`,\n`called_execution_id`, `status`, `detail`, `tokens_used`, `started_at`,\n`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 run credential cannot `StartStep` on another execution, and a member of\n org A listing steps of an org B execution gets not-found.\n- Cancelling a caller cancels its `wait: true` callee and leaves a\n `wait: false` callee running.\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:** 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" + "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\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames a Kit composition (the workload Kit pinned by digest, and zero or more\nmixin Kits) in place of a container image. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nProfiles are org resources in the State Store, so a Kit profile belongs to\none org, is granted to its workspaces like any profile, and applies without\na restart.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary; a harness adds nothing that\ncrosses it.\n\n- A Kit profile, its credential bindings and its OAuth tokens belong to one\n org. No record is shared between orgs.\n- A harness run is a run like any other: it acts as the workflow's identity,\n under the run credential issued at dispatch.\n- The egress proxy injects a credential only when the run credential carries\n the secret the binding names. A Kit that declares a service the identity is\n not granted gets no credential: a required one refuses the launch, an\n optional one is skipped.\n- A Kit's network policy is what the Kit asks for; the identity's network\n grants are what the org allows. The proxy enforces the intersection.\n- Concurrency slots are counted per binding within its org.\n\n## Credentials\n\nA credential binding maps a Kit's `credential@1` `service` name to an org\nsecret, which the org grants to identities like any secret. The secret holds\none of:\n\n- **API key:** a value in the org's secret store.\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 against the run\ncredential. The container gets the Kit's sentinel in the named variable or\ncredential file. OAuth refresh happens at the proxy, which intercepts the\nKit's `tokenEndpoint`, so a refreshed token is written to the State Store and\nnever returned to the container.\n\nRuns sharing an OAuth binding share its subscription's rate limit.\n`max_concurrent` on the binding (default 1) caps its simultaneous runs. A\nstage waiting for a slot is `pending`, not `running`.\n\n## Setup terminal\n\nThe dashboard opens a terminal (xterm.js over a WebSocket to a PTY) into an\nephemeral container built from a Kit profile, on the same egress path. The\nmember runs the CLI's own login. The proxy captures the tokens at the token\nendpoint into the org secret the binding names. The container is removed when\nthe terminal closes. No worktree is mounted into it.\n\nOpening the terminal is the `update` action on the secret, decided by the\nAuthorizer like any other; the shipped roles give it to org owners and\nadmins. It is the only interactive path into a harness container.\n\n## Egress\n\nOnly Kit profiles run on the egress path. An image profile keeps the network\naccess its identity is granted, because workflows such as a network\ninvestigator need raw DNS, ICMP and arbitrary TCP that no HTTP proxy\ncarries.\n\n- **Sandbox network.** Each Kit run gets its own internal Docker bridge on\n which the host holds no address. Host services, including those listening\n on every interface, are unreachable from it by any address.\n- **Relay.** One relay container, `archie-agent relay`, sits on the sandbox\n networks under a fixed alias and on the host-reachable network. It\n forwards every connection to the proxy and can reach nothing else. It\n holds no secrets.\n- **Proxy.** The proxy runs inside `archied`, listening on the host gateway\n of the host-reachable network. It terminates TLS with a per-daemon CA\n installed into the container at create, identifies the container by a\n per-run proxy token, and applies that run's network policy and credential\n inject rules. Upstream dials refuse loopback, and refuse internal addresses\n unless the policy names the exact IP, so an allowed name cannot resolve\n back into the host.\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. Kit profiles, runner selection from the stage's profile, and definition\n validation.\n7. OAuth bindings as org secrets: token-endpoint interception, encrypted\n storage, per-binding 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- A Kit profile in org A cannot be selected, and its binding cannot be\n resolved, by a workflow in org B.\n- A harness run whose identity is not granted a Kit's required credential is\n refused at launch; the proxy never injects a secret outside the run\n credential.\n- The firewall investigation example runs unchanged on an image profile with\n direct network access.\n" }, { "url": "/dev/prds/identity-decision/", @@ -412,7 +412,7 @@ "url": "/dev/prds/pr-review-agent/", "title": "PR review agent", "section": "PRDs", - "body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake,\n anatomy and diff, each able to read the repository:\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags.\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n near-duplicates through a small classification call that keeps both\n when unsure;\n - map lines to the diff's coordinates, sort by score, cap at 25 inline\n comments.\n8. **Merge gate.** One classification call per finding decides blocking or\n advisory: blocking only for broken builds, security, data loss, contract\n breaks and regressions. A failed call means advisory.\n9. **Output.** One call per comment tightens its wording, keeping the\n original on failure. The review is posted as one forge review with inline\n comments. Any blocking finding requests changes; otherwise the review is a\n comment. Archie never posts an approval.\n\n## Precision dial\n\nWith `review.precision_gate = true`, a post-worthiness pass runs after phase 4\nand before the verification layer. It keeps every concrete, evidenced defect\nand drops nitpicks, style and unverifiable claims, keeping a finding when\nunsure. It trades recall for precision and cuts verification cost by\nfiltering early.\n\n## Operator approval\n\nWith `review.approve_before_post = true`, synthesis ends in\n`waiting_human`. The operator chooses which findings to post, rejects the\nreview, or asks for a re-review with instructions. A re-review reruns phases\n3 to 8 with the instructions added to the lens and reviewer prompts, at most\n2 times. A review with no findings posts nothing and does not wait.\n\n## Isolation\n\nEvery agent in the pipeline reads a `.git`-free snapshot of the PR head, with\nread-only tools rooted at it, and never the implementer's worktree or\ntranscript. No pipeline agent holds a forge credential; posting is code.\n\n## Budget\n\nA run has a cost cap and a wall-clock cap, split into per-phase shares. A\nphase whose share is spent is skipped and recorded on its StepExecution. The\nposted review names every skipped phase, so an exhausted run never reads as a\nclean one. A run whose review stage fails posts nothing and\nfails.\n\n## Triggers\n\n- **Watched repositories:** a PR opened or updated on a repository with\n `review.enabled` starts a run. An update cancels the in-flight run for the\n same PR.\n- **Operator:** a PR URL from the dashboard or chat starts a run on any\n repository the identity can read.\n- **Archie's own PRs:** the implement workflow runs the pipeline before\n opening its PR. A blocking finding the adversary did not challenge parks\n the task with the findings. A pipeline that fails parks the task. Advisory\n findings are posted after the PR opens.\n\n## Models\n\nEach agent phase names a model role. Lens, reviewer, verification,\nadversary, compound and consistency agents use the review role. Intake,\ncoverage, dedup, merge gate and polish calls use the classification role.\nEither role may run on the built-in runner or a harness.\n\n## Out of scope\n\n- SARIF and standalone report formats. The findings are StepExecution outputs\n and the forge review.\n- Reviewing a diff without a forge PR.\n- Self-consistency reruns.\n\n## Plan\n\n1. Deterministic core: diff parsing, clustering, blast radius, evidence\n extraction, scoring, dedup, line mapping, review event. Table-driven tests.\n2. The benchmark harness (Verification), run against the deterministic core\n with fixture findings.\n3. `pr-review` workflow: intake, anatomy, lenses, reviewers, synthesis,\n output, with the execution tree recording each call.\n4. Verification layer, coverage loop and consistency verification.\n5. Merge gate, polish, budget shares and skipped-phase reporting.\n6. Benchmark acceptance run.\n7. Triggers: operator, watched repositories, archie's own PRs replacing the\n single-reviewer stage.\n8. Precision dial and operator approval.\n\n## Verification\n\n- **Benchmark acceptance.** On the 38 runnable PRs of the Martian\n Code-Review-Bench offline set, one blind run per PR at `deep` with the\n review and classification roles on GLM-5.2, and an independent judge\n (`anthropic/claude-sonnet-4.6`) matching posted comments to golden\n comments: golden micro-recall is at least 0.70. Golden-only precision is\n reported alongside it. The run is reproducible from a script in the\n repository.\n- Scoring, thresholds, dedup and line mapping give identical output for\n identical findings.\n- A run whose phase share is exhausted posts a review naming the skipped\n phase.\n- An update to a PR under review cancels the running review and its child\n steps.\n- No pipeline agent can write to the snapshot, and none can reach a forge\n credential.\n- Archie's own PR with an unchallenged blocking finding is parked, not\n opened.\n- Archie never submits an approving review.\n" + "body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake,\n anatomy and diff, each able to read the repository:\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags.\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n near-duplicates through a small classification call that keeps both\n when unsure;\n - map lines to the diff's coordinates, sort by score, cap at 25 inline\n comments.\n8. **Merge gate.** One classification call per finding decides blocking or\n advisory: blocking only for broken builds, security, data loss, contract\n breaks and regressions. A failed call means advisory.\n9. **Output.** One call per comment tightens its wording, keeping the\n original on failure. The review is posted as one forge review with inline\n comments. Any blocking finding requests changes; otherwise the review is a\n comment. Archie never posts an approval.\n\n## Precision dial\n\nWith `review.precision_gate = true`, a post-worthiness pass runs after phase 4\nand before the verification layer. It keeps every concrete, evidenced defect\nand drops nitpicks, style and unverifiable claims, keeping a finding when\nunsure. It trades recall for precision and cuts verification cost by\nfiltering early.\n\n## Operator approval\n\nWith `review.approve_before_post = true`, synthesis ends in\n`waiting_human`. The operator chooses which findings to post, rejects the\nreview, or asks for a re-review with instructions. A re-review reruns phases\n3 to 8 with the instructions added to the lens and reviewer prompts, at most\n2 times. A review with no findings posts nothing and does not wait.\n\n## Isolation\n\nEvery agent in the pipeline reads a `.git`-free snapshot of the PR head, with\nread-only tools rooted at it, and never the implementer's worktree or\ntranscript. No pipeline agent holds a forge credential; posting is code.\n\n## Budget\n\nA run has a cost cap and a wall-clock cap, split into per-phase shares. A\nphase whose share is spent is skipped and recorded on its StepExecution. The\nposted review names every skipped phase, so an exhausted run never reads as a\nclean one. A run whose review stage fails posts nothing and\nfails.\n\n## Triggers\n\n- **Watched repositories:** a PR opened or updated on a repository with\n `review.enabled` starts a run. An update cancels the in-flight run for the\n same PR.\n- **Operator:** a PR URL from the dashboard or chat starts a run on any\n repository the identity can read.\n- **Archie's own PRs:** the implement workflow runs the pipeline before\n opening its PR. A blocking finding the adversary did not challenge parks\n the task with the findings. A pipeline that fails parks the task. Advisory\n findings are posted after the PR opens.\n\n## Organisations\n\nThe reviewer is a workflow, so `docs/prds/orgs-and-access.md` applies to it\nunchanged: it runs as the workflow's identity under the run credential, reads\nonly repositories that identity may read, and posts through the forge RPC\nunder that credential. A watched repository belongs to a workspace, and its\nPR events start reviews through that workspace's bindings. Findings,\nStepExecutions and the posted review carry the run's org and workspace.\n\n## Models\n\nEach agent phase names a model role. Lens, reviewer, verification,\nadversary, compound and consistency agents use the review role. Intake,\ncoverage, dedup, merge gate and polish calls use the classification role.\nEither role may run on the built-in runner or a harness.\n\n## Out of scope\n\n- SARIF and standalone report formats. The findings are StepExecution outputs\n and the forge review.\n- Reviewing a diff without a forge PR.\n- Self-consistency reruns.\n\n## Plan\n\n1. Deterministic core: diff parsing, clustering, blast radius, evidence\n extraction, scoring, dedup, line mapping, review event. Table-driven tests.\n2. The benchmark harness (Verification), run against the deterministic core\n with fixture findings.\n3. `pr-review` workflow: intake, anatomy, lenses, reviewers, synthesis,\n output, with the execution tree recording each call.\n4. Verification layer, coverage loop and consistency verification.\n5. Merge gate, polish, budget shares and skipped-phase reporting.\n6. Benchmark acceptance run.\n7. Triggers: operator, watched repositories, archie's own PRs replacing the\n single-reviewer stage.\n8. Precision dial and operator approval.\n\n## Verification\n\n- **Benchmark acceptance.** On the 38 runnable PRs of the Martian\n Code-Review-Bench offline set, one blind run per PR at `deep` with the\n review and classification roles on GLM-5.2, and an independent judge\n (`anthropic/claude-sonnet-4.6`) matching posted comments to golden\n comments: golden micro-recall is at least 0.70. Golden-only precision is\n reported alongside it. The run is reproducible from a script in the\n repository.\n- Scoring, thresholds, dedup and line mapping give identical output for\n identical findings.\n- A run whose phase share is exhausted posts a review naming the skipped\n phase.\n- An update to a PR under review cancels the running review and its child\n steps.\n- No pipeline agent can write to the snapshot, and none can reach a forge\n credential.\n- Archie's own PR with an unchallenged blocking finding is parked, not\n opened.\n- Archie never submits an approving review.\n" }, { "url": "/dev/prds/pr-review-remediation/", @@ -496,7 +496,7 @@ "url": "/dev/prds/store/", "title": "Store", "section": "PRDs", - "body": "# Store\n\n**Status:** Approved\n**Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes\n`docs/prds/extensions-center.md`, whose installed-inventory states are\nadopted below.\n**Compounds with:** `docs/prds/external-agent-harness.md` (harness Kits),\n`docs/prds/pr-review-agent.md` (the first package).\n\n## Decision\n\nOperators get capabilities from a store: browse, install, update and remove\npackages from the dashboard, with no config file editing. A package is an\nOCI image in a registry. A store catalogue is a list of package references.\nInstalling pins a digest. Every package declares the authority it needs, and\nan update that asks for more stops for the operator's approval.\n\n## Packages\n\nTwo kinds, both ordinary OCI images:\n\n- **Harness Kits.** Kit v3 images, resolved as\n `docs/prds/external-agent-harness.md` decides. Their authority is their\n Kit permission surface.\n- **Archie packages.** An image whose manifest annotation\n `dev.archie.package.v1` carries the descriptor and whose single layer\n carries files. A package contributes any of: workflow definitions,\n prompts, skills, MCP server definitions, and default settings for them.\n\nArchie packages are declarative. They carry no Go, Yaegi or script code that\narchie executes on the host. Anything that runs code ships as a Kit and runs\nin a sandbox. An archie package that references a Kit names it by digest,\nand installing the package installs the Kit.\n\nThe descriptor declares: display name, description, version, the families\nit contributes, the packages it requires, and its authority.\n\n## Authority\n\nA package's authority is the set of grants it needs to work:\n\n- credential services (from its Kits and MCP servers);\n- egress hosts (from its Kits);\n- forge permissions its workflows use: read, comment, review, push, open\n pull request;\n- triggers it registers: watched-repository events, schedules;\n- tools it enables for agents.\n\nInstall shows this list and records the operator's acceptance against the\ndigest. An update whose authority is equal or narrower applies under the\npackage's update policy. An update whose authority is wider waits for\napproval, showing only what widened. Nothing a package does at runtime can\nexceed its accepted authority: archie checks forge actions, triggers and\ntool grants against it, and the egress proxy enforces the Kit's grants.\n\n## Catalogues\n\nA catalogue is an OCI artifact listing package references with digests,\nsigned by the catalogue's key. Archie ships with the default catalogue and\nits public key configured. An operator can add catalogues, for example a\nprivate registry, by reference and public key. A catalogue without a key is\nrefused unless the operator marks it unsigned, which the dashboard shows on\nevery package it supplies.\n\nInstall and update verify the catalogue signature and the package digest.\nArchie never installs a tag it has not resolved to a digest through a\nverified catalogue.\n\n## Install, update, remove\n\n- Installed packages, their pinned digests, accepted authority and update\n policy are State Store resources. They apply without a restart.\n- **Update policy** per package: `manual` (default) or `auto`. `auto` applies\n non-widening updates when the catalogue lists them; widening updates always\n wait.\n- **Setup.** A package whose authority includes a credential with no binding\n installs as `needs_setup`, and links to the binding form or the harness\n setup terminal. Its triggers do not fire until setup completes.\n- **Remove** stops its triggers, removes its contributions, and leaves any\n credential bindings for the operator to delete. A package another\n installed package requires cannot be removed first.\n- Rolling back reinstalls the previously accepted digest.\n\n## Inventory\n\nThe installed view lists every package and every bundled capability with\none state, computed on read and never persisted:\n\n| State | Meaning |\n| ------------- | -------------------------------------------------------- |\n| `available` | in a catalogue or bundled, not installed |\n| `needs_setup` | installed, waiting for a credential binding |\n| `active` | installed and running |\n| `degraded` | active, and its family's health check reports a fault |\n| `pending` | an update waiting for approval of widened authority |\n\nCore capabilities (identity, workflow engine, State Store) are listed and\ncannot be removed.\n\n## Out of scope\n\n- Payment, licensing and paid packages.\n- Publishing from the dashboard. Packages are built and pushed with standard\n image tooling.\n- Ratings and reviews.\n\n## Plan\n\n1. Archie package descriptor and its validation, including declarative-only\n content.\n2. Installed-package resources, digest pinning, install and remove for\n archie packages from a local registry.\n3. Authority model: extraction from packages and Kits, acceptance records,\n runtime checks for forge actions, triggers and tools.\n4. Signed catalogues and verification; the default catalogue.\n5. Updates: widening detection, approval, `auto` policy, rollback.\n6. Kit packages through the same flow; `needs_setup`.\n7. Inventory states across packages and bundled capabilities.\n8. The PR review agent published as the first package.\n\n## Verification\n\n- Installing the PR review package from the default catalogue on a fresh\n instance, then binding a credential, reviews a PR without editing\n configuration.\n- An update adding a forge permission or egress host waits as `pending`,\n showing only the added grant, and does not apply under `auto`.\n- A workflow from a package that tries a forge action outside its accepted\n authority fails the step.\n- A tampered package digest or an unsigned catalogue refuses to install.\n- A package containing executable host code is rejected at validation.\n- Rolling back restores the prior digest and its accepted authority.\n" + "body": "# Store\n\n**Status:** Approved\n**Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes\n`docs/prds/extensions-center.md`, whose installed-inventory states are\nadopted below.\n**Compounds with:** `docs/prds/external-agent-harness.md` (harness Kits),\n`docs/prds/pr-review-agent.md` (the first package).\n\n## Decision\n\nOperators get capabilities from a store: browse, install, update and remove\npackages from the dashboard, with no config file editing. A package is an\nOCI image in a registry. A store catalogue is a list of package references.\nInstalling pins a digest. Every package declares the authority it needs, and\nan update that asks for more stops for the operator's approval.\n\n## Packages\n\nTwo kinds, both ordinary OCI images:\n\n- **Harness Kits.** Kit v3 images, resolved as\n `docs/prds/external-agent-harness.md` decides. Their authority is their\n Kit permission surface.\n- **Archie packages.** An image whose manifest annotation\n `dev.archie.package.v1` carries the descriptor and whose single layer\n carries files. A package contributes any of: workflow definitions,\n prompts, skills, MCP server definitions, and default settings for them.\n\nArchie packages are declarative. They carry no Go, Yaegi or script code that\narchie executes on the host. Anything that runs code ships as a Kit and runs\nin a sandbox. An archie package that references a Kit names it by digest,\nand installing the package installs the Kit.\n\nThe descriptor declares: display name, description, version, the families\nit contributes, the packages it requires, and its authority.\n\n## Authority\n\nA package's authority is the set of grants it needs to work:\n\n- credential services (from its Kits and MCP servers);\n- egress hosts (from its Kits);\n- forge permissions its workflows use: read, comment, review, push, open\n pull request;\n- triggers it registers: watched-repository events, schedules;\n- tools it enables for agents.\n\nInstall shows this list and records the operator's acceptance against the\ndigest. An update whose authority is equal or narrower applies under the\npackage's update policy. An update whose authority is wider waits for\napproval, showing only what widened. Nothing a package does at runtime can\nexceed its accepted authority: archie checks forge actions, triggers and\ntool grants against it, and the egress proxy enforces the Kit's grants.\n\n## Catalogues\n\nA catalogue is an OCI artifact listing package references with digests,\nsigned by the catalogue's key. Archie ships with the default catalogue and\nits public key configured. An operator can add catalogues, for example a\nprivate registry, by reference and public key. A catalogue without a key is\nrefused unless the operator marks it unsigned, which the dashboard shows on\nevery package it supplies.\n\nInstall and update verify the catalogue signature and the package digest.\nArchie never installs a tag it has not resolved to a digest through a\nverified catalogue.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary, and the store follows its\nsplit between the instance and each org.\n\n- **Instance.** Catalogues and their keys are instance configuration, set by\n instance admins. Every org browses the same catalogues.\n- **Org.** Installing, updating, removing, accepting authority and setting the\n update policy are org actions. An installed package, its pinned digest and\n its accepted authority belong to one org. Two orgs can run different\n versions of one package.\n- **Contributions** become org resources: workflows are org workflows,\n profiles are org profiles, and credential bindings name org secrets. A\n workspace uses them only once the org grants them to it.\n- **Authority is an upper bound, not a grant.** Accepting a package's\n authority permits the package to ask; the workflow's identity must still\n hold each grant. A package never creates, grants to or widens an identity.\n- Install and authority acceptance are the `create` and `approve` actions on\n the package, decided by the Authorizer. Org approval policy decides who may\n accept, and no member accepts authority they asked for.\n\n## Install, update, remove\n\n- Installed packages, their pinned digests, accepted authority and update\n policy are org resources in the State Store. They apply without a restart.\n- **Update policy** per package: `manual` (default) or `auto`. `auto` applies\n non-widening updates when the catalogue lists them; widening updates always\n wait.\n- **Setup.** A package whose authority includes a credential with no binding\n installs as `needs_setup`, and links to the binding form or the harness\n setup terminal. Its triggers do not fire until setup completes.\n- **Remove** stops its triggers, removes its contributions, and leaves any\n credential bindings for the operator to delete. A package another\n installed package requires cannot be removed first.\n- Rolling back reinstalls the previously accepted digest.\n\n## Inventory\n\nThe installed view lists every package and every bundled capability with\none state, computed on read and never persisted:\n\n| State | Meaning |\n| ------------- | -------------------------------------------------------- |\n| `available` | in a catalogue or bundled, not installed |\n| `needs_setup` | installed, waiting for a credential binding |\n| `active` | installed and running |\n| `degraded` | active, and its family's health check reports a fault |\n| `pending` | an update waiting for approval of widened authority |\n\nCore capabilities (identity, workflow engine, State Store) are listed and\ncannot be removed.\n\n## Out of scope\n\n- Payment, licensing and paid packages.\n- Publishing from the dashboard. Packages are built and pushed with standard\n image tooling.\n- Ratings and reviews.\n\n## Plan\n\n1. Archie package descriptor and its validation, including declarative-only\n content.\n2. Installed-package resources, digest pinning, install and remove for\n archie packages from a local registry.\n3. Authority model: extraction from packages and Kits, acceptance records,\n runtime checks for forge actions, triggers and tools.\n4. Signed catalogues and verification; the default catalogue.\n5. Updates: widening detection, approval, `auto` policy, rollback.\n6. Kit packages through the same flow; `needs_setup`.\n7. Inventory states across packages and bundled capabilities.\n8. The PR review agent published as the first package.\n\n## Verification\n\n- Installing the PR review package from the default catalogue on a fresh\n instance, then binding a credential, reviews a PR without editing\n configuration.\n- An update adding a forge permission or egress host waits as `pending`,\n showing only the added grant, and does not apply under `auto`.\n- A workflow from a package that tries a forge action outside its accepted\n authority fails the step.\n- A tampered package digest or an unsigned catalogue refuses to install.\n- A package containing executable host code is rejected at validation.\n- Rolling back restores the prior digest and its accepted authority.\n- A package installed in org A is invisible to org B, and org B's workflows\n cannot select its profiles.\n- A package whose workflow needs a forge permission the running identity was\n never granted fails that step, even though the org accepted the package's\n authority.\n- A member cannot accept widened authority on an update they requested.\n" }, { "url": "/dev/prds/task-logs-pagination/", diff --git a/docs/prds/execution-tree-state-machine.md b/docs/prds/execution-tree-state-machine.md index d5f90d601..e411e5f54 100644 --- a/docs/prds/execution-tree-state-machine.md +++ b/docs/prds/execution-tree-state-machine.md @@ -45,8 +45,13 @@ WorkflowExecution (tasks row, id E) - A StepExecution belongs to exactly one WorkflowExecution and one attempt. `parent_id` is null for a stage and names the enclosing StepExecution otherwise. Depth is derived from the parent, never supplied by the caller. -- `kind` is `stage` or `agent`. A new kind needs a named consumer before it is - added. +- `kind` is `stage`, `agent` or `call`. A new kind needs a named consumer + before it is added. +- A `workflow.call` step (`docs/prds/event-automation.md`) is a `call` + StepExecution in the caller's tree. The callee is its own + WorkflowExecution, with its own tree, acting as its own identity, and the + `call` step records the callee's execution ID. Trees never nest across + executions, so each run's tree stays inside that run's authority. - A retry starts a new attempt. Earlier attempts' StepExecutions are never rewritten. @@ -106,6 +111,10 @@ whichever the operator action names. The daemon then cancels the in-memory context. A worker whose step write returns `ErrStaleTransition` because its step is already `cancelled` stops without writing further. +Cancelling a caller cancels each callee it is waiting on (`wait: true`), +through `CancelExecution` on the callee under the callee's own lifecycle. A +callee started with `wait: false` runs on. + The store is the record of cancellation. The context cancel is the delivery mechanism, so a lost cancel still leaves the store correct and the worker's next write fails. @@ -126,16 +135,25 @@ facade: - `CancelExecution(execution, reason, to)` - `ListSteps(execution, attempt)` -`TaskGrants.UnaryInterceptor` authorises a task-scoped token for `StartStep` -and `FinishStep` on its own execution only. The container records its own -agent calls. `CancelExecution` and `ListSteps` require the administrative -token. +The run credential of `docs/prds/orgs-and-access.md` authorises `StartStep` +and `FinishStep` on its own execution only, and the container records its own +agent calls with it. `CancelExecution` and `ListSteps` are dashboard, API and +dispatch actions, decided by the Authorizer: `update` and `read` on the run. + +## Organisations + +`docs/prds/orgs-and-access.md` is the boundary. A StepExecution belongs to its +WorkflowExecution's org and workspace and carries their `org_id` and +`workspace_id`, like every owned record. The State Store stamps both from the +credential on `StartStep` and ignores them in the request. `ListSteps` for an +execution in another org returns the store's ordinary not-found error. ## Storage -One new table, `step_executions`: `id`, `execution_id`, `attempt`, -`parent_id`, `depth`, `kind`, `name`, `status`, `detail`, `tokens_used`, -`started_at`, `finished_at`. Indexed on `(execution_id, attempt, id)`. +One new table, `step_executions`: `id`, `org_id`, `workspace_id`, +`execution_id`, `attempt`, `parent_id`, `depth`, `kind`, `name`, +`called_execution_id`, `status`, `detail`, `tokens_used`, `started_at`, +`finished_at`. Indexed on `(execution_id, attempt, id)`. Deleting an execution (archive, clearing terminal tasks) deletes its steps. Existing rows gain no backfilled steps. Their history stays in `transitions` and `events`. @@ -174,6 +192,9 @@ it, then dropped once the dashboard reads `ListSteps`. `interrupted` and the execution `queued` with a new attempt. - Stopping a run during review leaves every review child `cancelled`, and a late `FinishStep` from the container returns `ErrStaleTransition`. -- A task-scoped token cannot `StartStep` on another execution. +- A run credential cannot `StartStep` on another execution, and a member of + org A listing steps of an org B execution gets not-found. +- Cancelling a caller cancels its `wait: true` callee and leaves a + `wait: false` callee running. - For every step transition there is exactly one event row, written in the same transaction. diff --git a/docs/prds/external-agent-harness.md b/docs/prds/external-agent-harness.md index 3f941e8e8..4102ec525 100644 --- a/docs/prds/external-agent-harness.md +++ b/docs/prds/external-agent-harness.md @@ -73,62 +73,93 @@ retry without a `resume` verb. ## Selection -Order of precedence, first match wins: +A harness is an agent profile. `docs/prds/event-automation.md` defines a +profile as the execution environment a workflow selects; a harness profile +names a Kit composition (the workload Kit pinned by digest, and zero or more +mixin Kits) in place of a container image. Everything else about profiles +holds: a workflow names its profile, a stage may name a different one, and a +profile holds no secrets. -1. the stage's `runner` in the workflow definition; -2. the agent profile's `runner`; -3. `builtin`, the ai-sdk agent loop. +`archie-agent` builds the stage's runner from the stage's profile: the +ai-sdk agent loop for an image profile, the harness runner for a Kit +profile. Image profiles, and every workflow already written against them, +are unchanged. A Kit profile named by no workflow is a validation error. -`runner` names a harness resource. `archie-agent` reads it when it builds the -stage's runner; that is its only consumer. An unknown name, and a harness -named by no stage and no profile, are validation errors. +Profiles are org resources in the State Store, so a Kit profile belongs to +one org, is granted to its workspaces like any profile, and applies without +a restart. -A harness resource holds the workload Kit reference pinned by digest, zero or -more mixin Kit references, the credential bindings it uses, and -`max_concurrent` (default 1). Harness resources and credential bindings are -State Store resources managed from the dashboard, so they apply without a -restart. +## Organisations + +`docs/prds/orgs-and-access.md` is the boundary; a harness adds nothing that +crosses it. + +- A Kit profile, its credential bindings and its OAuth tokens belong to one + org. No record is shared between orgs. +- A harness run is a run like any other: it acts as the workflow's identity, + under the run credential issued at dispatch. +- The egress proxy injects a credential only when the run credential carries + the secret the binding names. A Kit that declares a service the identity is + not granted gets no credential: a required one refuses the launch, an + optional one is skipped. +- A Kit's network policy is what the Kit asks for; the identity's network + grants are what the org allows. The proxy enforces the intersection. +- Concurrency slots are counted per binding within its org. ## Credentials -A credential binding is keyed by the Kit's `credential@1` `service` name and -holds one of: +A credential binding maps a Kit's `credential@1` `service` name to an org +secret, which the org grants to identities like any secret. The secret holds +one of: -- **API key:** a `{ engine, key }` secret reference resolved through - `internal/secret`. +- **API key:** a value in the org's secret store. - **OAuth:** tokens captured by the setup terminal, stored in the State Store under the at-rest envelope of `binding-secret-encryption.md` with its own domain separator. -The egress proxy resolves the binding for each request. The container gets -the Kit's sentinel in the named variable or credential file. OAuth refresh -happens at the proxy, which intercepts the Kit's `tokenEndpoint`, so a -refreshed token is written to the State Store and never returned to the -container. +The egress proxy resolves the binding for each request against the run +credential. The container gets the Kit's sentinel in the named variable or +credential file. OAuth refresh happens at the proxy, which intercepts the +Kit's `tokenEndpoint`, so a refreshed token is written to the State Store and +never returned to the container. Runs sharing an OAuth binding share its subscription's rate limit. -`max_concurrent` is enforced per binding, summed across harnesses that use -it. A stage waiting for a slot is `pending`, not `running`. +`max_concurrent` on the binding (default 1) caps its simultaneous runs. A +stage waiting for a slot is `pending`, not `running`. ## Setup terminal -The dashboard opens an operator-only terminal (xterm.js over a WebSocket to a -PTY) into an ephemeral container built from the harness's Kits, on the same -egress proxy. The operator runs the CLI's own login. The proxy captures the -tokens at the token endpoint into the credential binding. The container is -removed when the terminal closes. No worktree is mounted into it. +The dashboard opens a terminal (xterm.js over a WebSocket to a PTY) into an +ephemeral container built from a Kit profile, on the same egress path. The +member runs the CLI's own login. The proxy captures the tokens at the token +endpoint into the org secret the binding names. The container is removed when +the terminal closes. No worktree is mounted into it. -The terminal requires the administrative role. It is the only interactive -path into a harness container. +Opening the terminal is the `update` action on the secret, decided by the +Authorizer like any other; the shipped roles give it to org owners and +admins. It is the only interactive path into a harness container. -## Egress proxy +## Egress -The egress proxy runs inside `archied`. Task and setup containers attach to -an internal Docker network whose only reachable endpoint is the proxy, so -egress outside the policy fails at the network, not by convention. The proxy -terminates TLS with a per-daemon CA installed into the container at create, -identifies the container by a per-container proxy token, and applies that -container's resolved `network-policy@1` and `credential@1` inject rules. +Only Kit profiles run on the egress path. An image profile keeps the network +access its identity is granted, because workflows such as a network +investigator need raw DNS, ICMP and arbitrary TCP that no HTTP proxy +carries. + +- **Sandbox network.** Each Kit run gets its own internal Docker bridge on + which the host holds no address. Host services, including those listening + on every interface, are unreachable from it by any address. +- **Relay.** One relay container, `archie-agent relay`, sits on the sandbox + networks under a fixed alias and on the host-reachable network. It + forwards every connection to the proxy and can reach nothing else. It + holds no secrets. +- **Proxy.** The proxy runs inside `archied`, listening on the host gateway + of the host-reachable network. It terminates TLS with a per-daemon CA + installed into the container at create, identifies the container by a + per-run proxy token, and applies that run's network policy and credential + inject rules. Upstream dials refuse loopback, and refuse internal addresses + unless the policy names the exact IP, so an allowed name cannot resolve + back into the host. ## Container layout @@ -201,9 +232,10 @@ of them. worktree checks for git, protected paths and read-only; budget and cancellation. 5. Claude Code output adapter; `archie-agent mcp`; gate-and-resume loop. -6. Harness resources, selection precedence and definition validation. -7. OAuth bindings: token-endpoint interception, encrypted storage, per-binding - concurrency; dashboard setup terminal. +6. Kit profiles, runner selection from the stage's profile, and definition + validation. +7. OAuth bindings as org secrets: token-endpoint interception, encrypted + storage, per-binding concurrency; dashboard setup terminal. 8. Output adapters for Codex, Pi, OMP and GitHub Copilot CLI. ## Verification @@ -230,3 +262,10 @@ of them. - Two tasks sharing an OAuth binding with `max_concurrent = 1` run one at a time; the second waits as `pending`. - Stopping a run kills the harness process and removes the container. +- A Kit profile in org A cannot be selected, and its binding cannot be + resolved, by a workflow in org B. +- A harness run whose identity is not granted a Kit's required credential is + refused at launch; the proxy never injects a secret outside the run + credential. +- The firewall investigation example runs unchanged on an image profile with + direct network access. diff --git a/docs/prds/pr-review-agent.md b/docs/prds/pr-review-agent.md index b2914834e..c250a1c7f 100644 --- a/docs/prds/pr-review-agent.md +++ b/docs/prds/pr-review-agent.md @@ -141,6 +141,15 @@ fails. the task with the findings. A pipeline that fails parks the task. Advisory findings are posted after the PR opens. +## Organisations + +The reviewer is a workflow, so `docs/prds/orgs-and-access.md` applies to it +unchanged: it runs as the workflow's identity under the run credential, reads +only repositories that identity may read, and posts through the forge RPC +under that credential. A watched repository belongs to a workspace, and its +PR events start reviews through that workspace's bindings. Findings, +StepExecutions and the posted review carry the run's org and workspace. + ## Models Each agent phase names a model role. Lens, reviewer, verification, diff --git a/docs/prds/store.md b/docs/prds/store.md index ec8899c92..511bde52d 100644 --- a/docs/prds/store.md +++ b/docs/prds/store.md @@ -66,10 +66,31 @@ Install and update verify the catalogue signature and the package digest. Archie never installs a tag it has not resolved to a digest through a verified catalogue. +## Organisations + +`docs/prds/orgs-and-access.md` is the boundary, and the store follows its +split between the instance and each org. + +- **Instance.** Catalogues and their keys are instance configuration, set by + instance admins. Every org browses the same catalogues. +- **Org.** Installing, updating, removing, accepting authority and setting the + update policy are org actions. An installed package, its pinned digest and + its accepted authority belong to one org. Two orgs can run different + versions of one package. +- **Contributions** become org resources: workflows are org workflows, + profiles are org profiles, and credential bindings name org secrets. A + workspace uses them only once the org grants them to it. +- **Authority is an upper bound, not a grant.** Accepting a package's + authority permits the package to ask; the workflow's identity must still + hold each grant. A package never creates, grants to or widens an identity. +- Install and authority acceptance are the `create` and `approve` actions on + the package, decided by the Authorizer. Org approval policy decides who may + accept, and no member accepts authority they asked for. + ## Install, update, remove - Installed packages, their pinned digests, accepted authority and update - policy are State Store resources. They apply without a restart. + policy are org resources in the State Store. They apply without a restart. - **Update policy** per package: `manual` (default) or `auto`. `auto` applies non-widening updates when the catalogue lists them; widening updates always wait. @@ -130,3 +151,9 @@ cannot be removed. - A tampered package digest or an unsigned catalogue refuses to install. - A package containing executable host code is rejected at validation. - Rolling back restores the prior digest and its accepted authority. +- A package installed in org A is invisible to org B, and org B's workflows + cannot select its profiles. +- A package whose workflow needs a forge permission the running identity was + never granted fails that step, even though the org accepted the package's + authority. +- A member cannot accept widened authority on an update they requested.