From 80f5f8ccc31f1fb63d0c646a993229fccc03fe8f Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 28 Sep 2026 02:04:04 +1000 Subject: [PATCH] feat(kit)!: a Kit profile names one Kit image, a workload or a published set kitrun ran the first Kit of a profile's list as the container image, so every mixin's layers (its tools, skills and staged context) were dropped without a refusal. A profile's `kit` is now one digest-pinned reference: a workload Kit, or a published Kit set, which the Kit spec's frontend merges from a workload and its mixins into one image. archie composes no Kits itself, and a bare mixin is refused with a pointer to publishing a set. kit.Compose had no production caller left and is removed. BREAKING CHANGE: `[containers.profiles.X] kit` and the agent-profiles document's `kit` are a string, not a list. A stored list fails to decode and must be rewritten as the one workload or set reference. Part of archie-core-egkf.6. --- config.example.toml | 5 +- docs/data/generated/dev-docs.json | 2 +- docs/prds/external-agent-harness.md | 11 +++-- .../app/controlplane/container_settings.go | 2 +- internal/config/config.go | 17 ++++--- internal/config/profile_test.go | 7 ++- internal/daemon/daemon_test.go | 16 +++---- internal/infrastructure/kit/kit.go | 18 ++----- internal/infrastructure/kit/kit_test.go | 48 +++++++++---------- internal/infrastructure/kit/launch_test.go | 4 +- internal/infrastructure/kitrun/launcher.go | 23 ++++----- 11 files changed, 68 insertions(+), 85 deletions(-) diff --git a/config.example.toml b/config.example.toml index af9e2ef1f..224b35a3e 100644 --- a/config.example.toml +++ b/config.example.toml @@ -450,9 +450,10 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch # image = "archie-agent-net:local" # docker compose build agent-net; empty uses [containers].image # tools = [] # allowlist over MCP, script and plugin tools; empty allows all # A Kit profile runs every agent stage on an external CLI packaged as a Kit v3 -# image: the workload Kit, then mixins, each pinned by digest. +# image: one workload Kit or published Kit set (which merges a workload with +# its mixins), pinned by digest. # [containers.profiles.claude] -# kit = ["docker/claude-code-kit@sha256:"] +# kit = "docker/claude-code-kit@sha256:" # adapter = "claude-code" # claude-code, codex, pi, omp or copilot; empty runs without capture tools or usage # # Credential bindings map a Kit's credential@1 service name to a secret. A diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 65decd3b2..05bba1a0b 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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\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\nA stage naming a different profile than its workflow's is a separate run,\nnot a mid-container runner switch: a Kit task runs in one container\nprovisioned for one profile (Container layout), so a stage that needs a\ndifferent one is its own callee, started the way `workflow.call` already\nstarts one (`docs/prds/event-automation.md` \"Workflows call workflows\"),\nwith its own agent profile resolved off its own task row. This needs no\nmechanism beyond `workflow.call` plus per-task profile resolution\n(`daemon.pinTaskProfile`), both of which already treat every task's\nprofile independently of any caller's -- see\n`TestWorkflowCallerConformance` (staterpc) for the callee's independent\n`Workflow` field and `TestWorkflowCallGivesACalleeItsOwnProfile` (daemon)\nfor the Kit-vs-image runner selection that independence produces.\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 three fixed ports, to the proxy, NATS and the State Store, and can\n reach nothing else. It 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\nA Kit task runs in one container, from the Kit composition's image, on the\ntask's sandbox network. The worker and every harness invocation share it;\nthey are separated by user, not by container, so a run's cost scales with\nthe run and not with how many agents it fans out to.\n\n- **Worker.** Archie mounts its own `archie-agent` binary read-only and runs\n it as the container's entrypoint, as root. It holds the task's NATS and\n State Store credentials in its own environment and in root-only files,\n runs the workflow, and serves `archie-agent mcp`. The Kit image's\n entrypoint is not PID 1.\n- **Harness.** Every invocation runs as the Kit's user (the image's `User`,\n default uid 1000) with an explicit environment: the Kit's variables, the\n proxy environment and the credential sentinels, and nothing inherited from\n the worker. That user cannot read the worker's environment or files, or\n trace it. Sibling invocations in one run share the user and the worktree.\n- **Hooks.** `lifecycle@1` install and startup hooks run as the user each\n declares, before the worker accepts work.\n- **Mounts.** The task worktree at the Kit's workspace directory, owned by the\n Kit's user, and the read-only skills store. Nothing else from the host.\n- **Network.** The relay forwards three fixed ports on the sandbox network:\n the egress proxy, NATS and the State Store. The worker reaches NATS and the\n State Store with its credentials; a harness can open those ports but holds\n no credential either accepts.\n- **Volumes.** `volume@1` paths persist for the life of the\n WorkflowExecution, which covers session resume across gate iterations and\n retries. They are not 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 harness invocation cannot read the worker's NATS or State Store\n credential from its environment, its files or `/proc`.\n- A run fanning out to many agent invocations uses one 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" + "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, published with the harness Kit as a Kit set: the set merges their\nlayers into one image. It is versioned image content, rewritten on every\ncreate, never state a run can modify.\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 one Kit pinned by digest, a workload Kit or a published Kit set, in\nplace of a container image. Archie runs that Kit's image and composes no Kits\nitself; a bare mixin is refused. 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\nA stage naming a different profile than its workflow's is a separate run,\nnot a mid-container runner switch: a Kit task runs in one container\nprovisioned for one profile (Container layout), so a stage that needs a\ndifferent one is its own callee, started the way `workflow.call` already\nstarts one (`docs/prds/event-automation.md` \"Workflows call workflows\"),\nwith its own agent profile resolved off its own task row. This needs no\nmechanism beyond `workflow.call` plus per-task profile resolution\n(`daemon.pinTaskProfile`), both of which already treat every task's\nprofile independently of any caller's -- see\n`TestWorkflowCallerConformance` (staterpc) for the callee's independent\n`Workflow` field and `TestWorkflowCallGivesACalleeItsOwnProfile` (daemon)\nfor the Kit-vs-image runner selection that independence produces.\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 three fixed ports, to the proxy, NATS and the State Store, and can\n reach nothing else. It 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\nA Kit task runs in one container, from the Kit composition's image, on the\ntask's sandbox network. The worker and every harness invocation share it;\nthey are separated by user, not by container, so a run's cost scales with\nthe run and not with how many agents it fans out to.\n\n- **Worker.** Archie mounts its own `archie-agent` binary read-only and runs\n it as the container's entrypoint, as root. It holds the task's NATS and\n State Store credentials in its own environment and in root-only files,\n runs the workflow, and serves `archie-agent mcp`. The Kit image's\n entrypoint is not PID 1.\n- **Harness.** Every invocation runs as the Kit's user (the image's `User`,\n default uid 1000) with an explicit environment: the Kit's variables, the\n proxy environment and the credential sentinels, and nothing inherited from\n the worker. That user cannot read the worker's environment or files, or\n trace it. Sibling invocations in one run share the user and the worktree.\n- **Hooks.** `lifecycle@1` install and startup hooks run as the user each\n declares, before the worker accepts work.\n- **Mounts.** The task worktree at the Kit's workspace directory, owned by the\n Kit's user, and the read-only skills store. Nothing else from the host.\n- **Network.** The relay forwards three fixed ports on the sandbox network:\n the egress proxy, NATS and the State Store. The worker reaches NATS and the\n State Store with its credentials; a harness can open those ports but holds\n no credential either accepts.\n- **Volumes.** `volume@1` paths persist for the life of the\n WorkflowExecution, which covers session resume across gate iterations and\n retries. They are not 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 harness invocation cannot read the worker's NATS or State Store\n credential from its environment, its files or `/proc`.\n- A run fanning out to many agent invocations uses one 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/", diff --git a/docs/prds/external-agent-harness.md b/docs/prds/external-agent-harness.md index 1028c5f86..b7ccfc2bd 100644 --- a/docs/prds/external-agent-harness.md +++ b/docs/prds/external-agent-harness.md @@ -51,9 +51,9 @@ optional one is skipped and recorded on the step. `credential@1` with `passthrough: true` and any credential for a forge service are refused. The operator's own setup (plugins, subagents, instructions, settings) is a -mixin Kit the operator builds `FROM` or alongside the harness Kit. It is -versioned image content, rewritten on every create, never state a run can -modify. +mixin Kit, published with the harness Kit as a Kit set: the set merges their +layers into one image. It is versioned image content, rewritten on every +create, never state a run can modify. ## Contract @@ -75,8 +75,9 @@ retry without a `resume` verb. 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 +names one Kit pinned by digest, a workload Kit or a published Kit set, in +place of a container image. Archie runs that Kit's image and composes no Kits +itself; a bare mixin is refused. Everything else about profiles holds: a workflow names its profile, a stage may name a different one, and a profile holds no secrets. diff --git a/internal/app/controlplane/container_settings.go b/internal/app/controlplane/container_settings.go index 2e0074b5b..0d3b9b3f1 100644 --- a/internal/app/controlplane/container_settings.go +++ b/internal/app/controlplane/container_settings.go @@ -34,7 +34,7 @@ type containerRuntimePolicies struct { // agentProfile is one named execution environment as the document writes it. type agentProfile struct { Image string `json:"image,omitempty"` - Kit []string `json:"kit,omitempty"` + Kit string `json:"kit,omitempty"` Adapter string `json:"adapter,omitempty"` Tools []string `json:"tools,omitempty"` } diff --git a/internal/config/config.go b/internal/config/config.go index 9f3207b13..561daefca 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -957,10 +957,11 @@ func (c ContainerConfig) ValidateCredentialBindings() error { type AgentProfile struct { // Image is the container image; empty means [containers].image. Image string `toml:"image" yaml:"image"` - // Kit makes this a harness profile: the workload Kit, then its mixins, - // each pinned by digest. The task container is the workload's image and - // every agent stage runs on its CLI. Exclusive with Image. - Kit []string `toml:"kit" yaml:"kit"` + // Kit makes this a harness profile: one workload Kit or published Kit + // set, pinned by digest. Mixins are composed by publishing a set, which + // merges their layers into one image. The task container runs that + // image and every agent stage runs on its CLI. Exclusive with Image. + Kit string `toml:"kit" yaml:"kit"` // Adapter names the output adapter reading the Kit's CLI; empty runs it // with no capture tools and no usage. Adapter string `toml:"adapter" yaml:"adapter"` @@ -988,7 +989,7 @@ func (c ContainerConfig) Profile(name string) (AgentProfile, error) { } // IsKit reports whether the profile runs a Kit harness. -func (p AgentProfile) IsKit() bool { return len(p.Kit) > 0 } +func (p AgentProfile) IsKit() bool { return p.Kit != "" } // ValidateProfiles rejects a profile with an empty name, an empty tool // name, or a Kit that is not pinned by digest or also names an image. @@ -1012,10 +1013,8 @@ func ValidateAgentProfiles(profiles map[string]AgentProfile) error { case !p.IsKit() && p.Adapter != "": return fmt.Errorf("containers.profiles.%s: adapter needs a kit", name) } - for _, ref := range p.Kit { - if !strings.Contains(ref, "@sha256:") { - return fmt.Errorf("containers.profiles.%s.kit: %q must be pinned by digest", name, ref) - } + if p.IsKit() && !strings.Contains(p.Kit, "@sha256:") { + return fmt.Errorf("containers.profiles.%s.kit: %q must be pinned by digest", name, p.Kit) } for _, tool := range p.Tools { if strings.TrimSpace(tool) == "" { diff --git a/internal/config/profile_test.go b/internal/config/profile_test.go index 517701e06..8e61a982a 100644 --- a/internal/config/profile_test.go +++ b/internal/config/profile_test.go @@ -43,16 +43,15 @@ func TestContainerProfileResolution(t *testing.T) { func TestKitProfiles(t *testing.T) { const pinned = "docker/claude-code-kit@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" c := ContainerConfig{Image: "archie-agent:1", Profiles: map[string]AgentProfile{ - "claude": {Kit: []string{pinned}, Adapter: "claude-code"}, + "claude": {Kit: pinned, Adapter: "claude-code"}, }} p, err := c.Profile("claude") if err != nil || p.Image != "" || !p.IsKit() { t.Fatalf("Profile() = %+v, %v; a Kit profile must not inherit the agent image", p, err) } for name, bad := range map[string]AgentProfile{ - "image and kit": {Image: "archie-agent:1", Kit: []string{pinned}}, - "unpinned kit": {Kit: []string{"docker/claude-code-kit:latest"}}, - "unpinned mixin": {Kit: []string{pinned, "me/setup:1"}}, + "image and kit": {Image: "archie-agent:1", Kit: pinned}, + "unpinned kit": {Kit: "docker/claude-code-kit:latest"}, "adapter without a kit": {Adapter: "claude-code"}, } { c := ContainerConfig{Profiles: map[string]AgentProfile{"p": bad}} diff --git a/internal/daemon/daemon_test.go b/internal/daemon/daemon_test.go index 81f6a88b1..bc5ceb227 100644 --- a/internal/daemon/daemon_test.go +++ b/internal/daemon/daemon_test.go @@ -2364,9 +2364,9 @@ func TestPinTaskProfileRefusesCapturesTheHarnessCannotServe(t *testing.T) { d, s, _ := daemonWithNATS(t) cfg := d.Cfg.Get() cfg.Containers.Profiles = map[string]config.AgentProfile{ - "serves-captures": {Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}, - "no-captures": {Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterCodex}, - "no-adapter": {Kit: []string{"kit@sha256:ab"}}, + "serves-captures": {Kit: "kit@sha256:ab", Adapter: agentexec.AdapterClaudeCode}, + "no-captures": {Kit: "kit@sha256:ab", Adapter: agentexec.AdapterCodex}, + "no-adapter": {Kit: "kit@sha256:ab"}, } d.Cfg.Set(cfg) d.WorkflowDefinitions = &workflowDefinitionsStub{collection: workflow.WorkflowDefinitionCollection{Definitions: []workflow.WorkflowDefinitionEntry{ @@ -2427,7 +2427,7 @@ func TestWorkflowCallGivesACalleeItsOwnProfile(t *testing.T) { cfg := d.Cfg.Get() cfg.Containers.Profiles = map[string]config.AgentProfile{ "net": {Image: "agent-net:1"}, - "contain": {Kit: []string{"contain-kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}, + "contain": {Kit: "contain-kit@sha256:ab", Adapter: agentexec.AdapterClaudeCode}, } d.Cfg.Set(cfg) d.WorkflowDefinitions = &workflowDefinitionsStub{collection: workflow.WorkflowDefinitionCollection{Definitions: []workflow.WorkflowDefinitionEntry{ @@ -2607,7 +2607,7 @@ func TestKitProfileRunsTheTaskOnItsHarness(t *testing.T) { } t.Cleanup(func() { _ = sub.Unsubscribe() }) - profile := config.AgentProfile{Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode} + profile := config.AgentProfile{Kit: "kit@sha256:ab", Adapter: agentexec.AdapterClaudeCode} d.runKitTask(ctx, task, config.Repo{Owner: "acme", Name: "widget", Base: "main"}, t.TempDir(), profile) select { @@ -2618,8 +2618,8 @@ func TestKitProfileRunsTheTaskOnItsHarness(t *testing.T) { case <-time.After(time.Second): t.Fatal("archied did not publish a taskrun request") } - if !slices.Equal(launcher.got.Kit, profile.Kit) || launcher.got.Adapter != profile.Adapter { - t.Fatalf("launch request %+v, want the profile's kits and adapter", launcher.got) + if launcher.got.Kit != profile.Kit || launcher.got.Adapter != profile.Adapter { + t.Fatalf("launch request %+v, want the profile's kit and adapter", launcher.got) } for _, e := range launcher.got.WorkerEnv { if strings.Contains(e, "sk-real") { @@ -2666,7 +2666,7 @@ func TestRunKitTaskThreadsGateRetriesToTheLauncher(t *testing.T) { t.Cleanup(func() { _ = sub.Unsubscribe() }) d.runKitTask(ctx, task, config.Repo{Owner: "acme", Name: "widget", Base: "main"}, t.TempDir(), - config.AgentProfile{Kit: []string{"kit@sha256:ab"}, Adapter: agentexec.AdapterClaudeCode}) + config.AgentProfile{Kit: "kit@sha256:ab", Adapter: agentexec.AdapterClaudeCode}) if launcher.got.GateRetries != 4 { t.Fatalf("launch request GateRetries = %d, want the workflow's declared 4", launcher.got.GateRetries) diff --git a/internal/infrastructure/kit/kit.go b/internal/infrastructure/kit/kit.go index aba1b3b72..9f3cc21ac 100644 --- a/internal/infrastructure/kit/kit.go +++ b/internal/infrastructure/kit/kit.go @@ -125,25 +125,15 @@ func Admit(d *spec.Descriptor) (*Plan, error) { return plan, nil } -// Compose merges one workload Kit and its mixins, in the order given, and -// admits the result. archie drives a harness headlessly, so the composition -// must carry an agent-sessions prompt verb. -func Compose(contributions []spec.Contribution) (*Plan, error) { - merged, err := spec.Merge(contributions, MergeOptions) - if err != nil { - return nil, err - } - return FromMerge(merged) -} - // MergeOptions are the options every composition archie runs is merged with. var MergeOptions = spec.MergeOptions{ContextPath: contextPath} -// FromMerge admits an already-merged composition, such as one the Kit spec's -// fetch package assembled from a registry. +// FromMerge admits the profile's Kit as the Kit spec's fetch package read it: +// a workload Kit or a published Kit set, never a bare mixin. archie drives a +// harness headlessly, so it must carry an agent-sessions prompt verb. func FromMerge(merged *spec.MergeResult) (*Plan, error) { if merged.Descriptor.Kind != spec.KindWorkload { - return nil, errors.New("kit composition has no workload: a harness needs exactly one base kit") + return nil, errors.New("kit is a mixin: publish a Kit set composing it with a workload Kit, and name the set") } plan, err := Admit(merged.Descriptor) if err != nil { diff --git a/internal/infrastructure/kit/kit_test.go b/internal/infrastructure/kit/kit_test.go index 2fa71912b..ab969f7f3 100644 --- a/internal/infrastructure/kit/kit_test.go +++ b/internal/infrastructure/kit/kit_test.go @@ -162,45 +162,41 @@ func TestRefusalNamesTheCapability(t *testing.T) { } } -func TestCompose(t *testing.T) { +// admit reads one Kit the way the launcher does: merged alone, then admitted. +func admit(t *testing.T, c spec.Contribution) (*Plan, error) { + t.Helper() + merged, err := spec.Merge([]spec.Contribution{c}, MergeOptions) + if err != nil { + t.Fatalf("Merge: %v", err) + } + return FromMerge(merged) +} + +func TestFromMerge(t *testing.T) { workload := spec.Contribution{Reference: "workload", Descriptor: descriptor(t, spec.KindWorkload, sessions)} mixin := spec.Contribution{Reference: "mixin", Descriptor: descriptor(t, spec.KindMixin, ` - type: com.docker.sandbox/network-policy@1 - config: {runtime: {allow: [api.example.com]}} - - type: com.docker.sandbox/credential@1 - config: - service: example - phase: runtime - apiKey: {name: EXAMPLE_KEY, proxyManaged: true, inject: [{domain: api.example.com, header: x-api-key, format: "%s"}]}`)} + config: {runtime: {allow: [api.example.com]}}`)} bareWorkload := spec.Contribution{Reference: "bare", Descriptor: descriptor(t, spec.KindWorkload, ` - type: com.docker.sandbox/resources@1 config: {memory: 1g}`)} - t.Run("a workload and its mixins compose into one plan", func(t *testing.T) { - plan, err := Compose([]spec.Contribution{workload, mixin}) - if err != nil { - t.Fatalf("Compose: %v", err) - } - if !spec.HasCapability(plan.Capabilities, typeCredential) { - t.Fatal("the mixin's credential did not reach the plan") - } - if plan.Sessions == nil || len(plan.Sessions.Prompt) == 0 { - t.Fatal("the plan carries no headless prompt verb") - } - }) + plan, err := admit(t, workload) + if err != nil || plan.Sessions == nil || len(plan.Sessions.Prompt) == 0 { + t.Fatalf("admit(workload) = %+v, %v; want a plan with a headless prompt verb", plan, err) + } tests := []struct { - name string - contributions []spec.Contribution - want string + name string + kit spec.Contribution + want string }{ - {"no workload", []spec.Contribution{mixin}, "no workload"}, - {"no headless prompt verb", []spec.Contribution{bareWorkload}, "agent-sessions"}, - {"two workloads", []spec.Contribution{workload, bareWorkload}, "workload"}, + {"a bare mixin", mixin, "publish a Kit set"}, + {"no headless prompt verb", bareWorkload, "agent-sessions"}, } for _, tt := range tests { t.Run(tt.name+" is refused", func(t *testing.T) { - _, err := Compose(tt.contributions) + _, err := admit(t, tt.kit) if err == nil || !strings.Contains(err.Error(), tt.want) { t.Fatalf("error %v, want one mentioning %q", err, tt.want) } diff --git a/internal/infrastructure/kit/launch_test.go b/internal/infrastructure/kit/launch_test.go index afedbd5da..b6fc47ee4 100644 --- a/internal/infrastructure/kit/launch_test.go +++ b/internal/infrastructure/kit/launch_test.go @@ -38,9 +38,9 @@ const launchKit = ` func plan(t *testing.T) *Plan { t.Helper() - p, err := Compose([]spec.Contribution{{Reference: "kit", Descriptor: descriptor(t, spec.KindWorkload, launchKit)}}) + p, err := admit(t, spec.Contribution{Reference: "kit", Descriptor: descriptor(t, spec.KindWorkload, launchKit)}) if err != nil { - t.Fatalf("Compose: %v", err) + t.Fatalf("admit: %v", err) } return p } diff --git a/internal/infrastructure/kitrun/launcher.go b/internal/infrastructure/kitrun/launcher.go index 0faef6f83..c2996f5c8 100644 --- a/internal/infrastructure/kitrun/launcher.go +++ b/internal/infrastructure/kitrun/launcher.go @@ -73,7 +73,8 @@ type Request struct { // Execution keys the task's Kit volumes and names its container and // network. Execution string - Kit []string + // Kit is the digest-pinned workload Kit or published Kit set. + Kit string Adapter string WorkDir string WorkerEnv []string @@ -106,9 +107,9 @@ type Run struct { execution string } -// Launch composes the request's Kits and starts its container. +// Launch reads the request's Kit and starts its container. func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) { - if len(req.Kit) == 0 { + if req.Kit == "" { return nil, errors.New("kit profile names no kit") } adapter, ok := agentexec.LookupHarnessAdapter(req.Adapter) @@ -158,7 +159,7 @@ func (l *Launcher) Launch(ctx context.Context, req Request) (*Run, error) { } run.Container, err = l.Pool.AcquireKit(ctx, container.KitSpec{ Name: "archie-kit-" + req.Execution, - Image: req.Kit[0], + Image: req.Kit, Network: run.network, Worker: []string{agentPath}, WorkerEnv: req.WorkerEnv, @@ -234,22 +235,18 @@ func (l *Launcher) release(run *Run) { l.Proxy.Revoke(run.token) } -// compose assembles the profile's Kits and reads the workload image's -// config, the first Kit being the workload. -func (l *Launcher) compose(ctx context.Context, refs []string) (*kit.Plan, kit.ImageConfig, error) { - reqs := make([]fetch.Request, len(refs)) - for i, ref := range refs { - reqs[i] = fetch.Request{Reference: ref} - } +// compose reads the profile's Kit and the config of the image it runs. +func (l *Launcher) compose(ctx context.Context, ref string) (*kit.Plan, kit.ImageConfig, error) { + reqs := []fetch.Request{{Reference: ref}} merged, err := l.Fetch.Assemble(ctx, reqs, kit.MergeOptions) if err != nil { - return nil, kit.ImageConfig{}, fmt.Errorf("assemble kits: %w", err) + return nil, kit.ImageConfig{}, fmt.Errorf("read kit: %w", err) } plan, err := kit.FromMerge(merged.MergeResult) if err != nil { return nil, kit.ImageConfig{}, err } - img, err := l.imageConfig(ctx, refs[0]) + img, err := l.imageConfig(ctx, ref) if err != nil { return nil, kit.ImageConfig{}, err }