diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 27d7868d9..46bc1d5cb 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -324,6 +324,12 @@ "section": "PRDs", "body": "# Extensions centre\n\n**Status:** Draft\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions centre\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disableable\" property\nenforced structurally rather than by a runtime check that could be\nbypassed.\n\n**Call site.** `internal/config/config.go` — add the field per family\nstruct, not one generic `map[string]bool` (typed fields keep\n`docsgen`/`contracts.json` generation working, per `tools/docsgen`'s\n\"treat flags as executable truth\" rule — a generic map has no type to\ngenerate from). `config.example.toml` documents each new field with its\ndefault.\n\n**Reuse check.** The config `Holder` overlay system\n(`internal/infrastructure/configuration`) already handles safe saves; this\nadds fields to existing structs, it does not add a second config-write path.\n\n### Pending-restart and reconciliation\n\n**Decision.** No new \"pending restart\" flag is persisted. `Inventory.List`\ncomputes `StatePendingRestart` by comparing the config's `Enabled` value\nagainst whether the family's registry reports that entry as\nlive — if they disagree, the entry is pending restart. This is simpler than\ntracking a flag through a save-then-restart cycle and can never go stale,\nbecause it's recomputed on every read.\n\n**Call site.** `internal/domain/extensions/inventory.go`'s comparison logic.\n\n### API and UI surface\n\n**Decision.** New `api_extensions.go` alongside the existing `api_skills.go`\n/`api_workflows.go` pattern, exposing `Inventory.List` and a save endpoint\nthat writes through the existing `UpdateConfig` seam (`api_config.go`) —\nthis document does not add a second config-write endpoint. New\n`ui/src/extensions/` (colocated `.js`/`.css` per CLAUDE.md's frontend rule)\nas an index/dashboard that **links to**, not replaces, the existing\n`ui/src/skills/` and `ui/src/workflows/` detail views — Extensions centre is\nwhere an operator sees everything and toggles enablement; the family-specific\npages remain where they inspect a family's own detail.\n\n**Call site.** `internal/webui/api_extensions.go` (new, follows\n`api_skills.go`'s shape), `ui/src/extensions/` (new).\n\n## Call site inventory\n\n| concern | file | change |\n| ------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------- |\n| Plugin metadata type | `internal/plugin/plugin.go` | none — already handles this |\n| Family controllers (curator/health/image/workflow registries) | `internal/domain/curator/registry.go`, `internal/domain/health/health.go`, etc. | none — pattern already proven, reused not rewritten |\n| Unified inventory | `internal/domain/extensions/inventory.go` | new |\n| Composition wiring | `internal/app/archied/server.go` (near existing optional fields) | new |\n| Config enablement fields | `internal/config/config.go` | new fields per family |\n| Config docs | `config.example.toml` | new field documentation |\n| API surface | `internal/webui/api_extensions.go` | new |\n| Existing skills/workflows APIs | `internal/webui/api_skills.go`, `api_workflows.go` | none — linked from, not replaced |\n| Config save path | `internal/webui/api_config.go` (`UpdateConfig`) | reused, not duplicated |\n| UI | `ui/src/extensions/` | new |\n| Existing UI detail views | `ui/src/skills/`, `ui/src/workflows/` | none — linked from Extensions centre |\n\n## Execution: multi-agent team breakdown\n\n| sub-feature | issue | implementer scope | suggested council lenses | why |\n| ------------------------------------ | ---------------------- | ---------------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| Unified inventory type + composition | file as child of `#56` | `internal/domain/extensions/inventory.go`, wiring in `server.go` | `lens-boundary`, `lens-deletionist` | boundary: aggregator must not duplicate family-owned state; deletionist: must not become a new domain that shadows existing registries |\n| Config enablement fields | file as child of `#56` | `config.go` per-family `Enabled` fields, `config.example.toml` | `lens-contract` | config field is a wire contract other tooling (`docsgen`) generates from |\n| API + UI surface | file as child of `#56` | `api_extensions.go`, `ui/src/extensions/` | `lens-maintainer` | new user-facing state machine (available/enabled/active/degraded/skipped/pending-restart) must be legible to an operator with no prior context |\n\n## File and link the beads\n\n- `#56` itself has no filed children yet — file the three rows above as\n child issues linking to this doc's matching `##` heading.\n- Each issue's acceptance criteria should restate this doc's per-family\n `Enabled` default (`true` for existing config, no field at all for core\n capabilities) so \"non-disableable core\" isn't re-litigated per bead.\n- Add the suggested lenses to each issue.\n" }, + { + "url": "/dev/prds/external-agent-harness/", + "title": "External agent harnesses", + "section": "PRDs", + "body": "# External agent harnesses\n\n**Status:** Draft\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop. Supported harnesses are Claude Code, Codex, Pi, OMP and\nGitHub Copilot CLI. Each authenticates with either an API key or the\noperator's own subscription login, and can run with the operator's own\nskills, plugins, subagents and instructions.\n\nArchie's guarantees do not move into the harness. Git, protected paths,\nread-only stages, gates and budgets are enforced by archie around the\nharness process and checked against the worktree afterwards. They never\ndepend on the harness obeying its instructions.\n\n## Contract\n\nA harness is a second implementation of `agentexec.Runner`. It takes the same\n`Request` and returns the same `Result`, so workflows, the daemon and the\nState Store do not know which runner ran a stage.\n\nEach adapter owns, for one CLI:\n\n- the non-interactive invocation and its streamed JSON output;\n- translating stream events into `ToolCallReporter` calls and `Usage`;\n- resuming the same session with follow-up input;\n- the capabilities it declares: `mcp`, `resume`, `usage`.\n\nAn adapter that cannot report usage reports zero and says so in\n`StopReason`; token budgets for that stage are enforced by wall clock only.\nWorkflow definition validation rejects a stage whose requirements the chosen\nharness does not declare, at load time, not mid-run.\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 `[harnesses.\u003cname\u003e]` entry. An entry with no consumer\n(named by no stage and no profile) is a validation warning, and an unknown\nname is a validation error.\n\n```toml\n[harnesses.claude-sub]\nadapter = \"claude-code\"\nimage = \"registry.local/archie-agent-claude:latest\"\nhome = \"claude-sam\" # a harness home, below\nmax_concurrent = 1\n\n[harnesses.codex-api]\nadapter = \"codex\"\nimage = \"registry.local/archie-agent-codex:latest\"\napi_key = { engine = \"env\", key = \"OPENAI_API_KEY\" }\nmax_concurrent = 4\n```\n\n## Credentials and customisation\n\nAn entry authenticates one of two ways. Setting both is a validation error.\n\n- **API key:** `api_key` is a secret reference, injected into the container\n as the environment variable the adapter names. The key is never written\n into the worktree or a harness home.\n- **Subscription:** `home` names a **harness home**, a directory under\n archie's state directory that the operator logs into once with\n `archied harness login \u003chome\u003e`. That command runs the CLI's own login flow\n with its config directory pointed at the home.\n\nA harness home is also where the operator's own setup lives: skills,\nplugins, subagent definitions, global instructions, and the CLI's settings\nfile. Archie mounts it read-write as the CLI's config directory, because\nsubscription tokens refresh in place. Archie never edits it. Archie's own\nmission and tools reach the harness through the prompt and the invocation,\nso they do not touch the operator's files.\n\n`max_concurrent` caps simultaneous runs per entry, default 1. Runs sharing a\nhome share its refresh state and its subscription's rate limit; the cap is\nper home, summed across entries that name it. A stage waiting for a slot is\n`pending`, not `running`.\n\n## Archie tools inside the harness\n\nCapture tools, which are how a stage returns structured results, are served\nto the harness by `archie-agent mcp`, a stdio MCP server started inside the\ncontainer and registered through the adapter's invocation flags. It serves\nthe stage's `CaptureTools` and the central tools the agent profile allows.\nIt does not serve the `workspace` toolset, for the same reason the built-in\nrunner withholds it.\n\nA harness that does not declare `mcp` can only run stages with no capture\ntools.\n\n## Enforcement around the harness\n\nThe harness runs as a subprocess of `archie-agent` in the task-scoped\ncontainer, in the task worktree. Archie holds these properties by\nconstruction and by checking the worktree after the process exits:\n\n| Property | Enforcement |\n| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| Model never runs git | The container has no forge credential. 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 same session with the gate output, up to the stage's iteration budget. A harness without `resume` gets one iteration. |\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. |\n\nHarness settings that deny git or protected paths are added where an\nadapter supports them, to save wasted turns. They are never the\nenforcement.\n\n## Images\n\nThe default `archie-agent` image bundles no third-party CLI. A harness entry\nnames an image that contains both the CLI and the `archie-agent` binary.\nThe repository ships one Dockerfile build target per supported adapter,\nbuilt on the `agent` image. Pull policy follows `containers.pull_policy`.\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 home or its\ncredential. The stage boundary is what carries the container, the git and\npath checks, the gate and the budget; a harness outside a stage has none of\nthem.\n\n## Out of scope\n\n- Chat through a harness. The gateway chat loop stays on the built-in\n runtime.\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. Harness `Runner` with the Claude Code adapter; worktree checks for git,\n protected paths and read-only; budget and cancellation.\n2. `archie-agent mcp` serving capture tools; gate-and-resume loop.\n3. `[harnesses.*]` config, selection precedence and definition validation.\n4. API key credentials; harness homes and `archied harness login`;\n per-home concurrency.\n5. Codex adapter, then Pi, OMP and GitHub Copilot CLI.\n6. Dockerfile targets per adapter.\n\n## Verification\n\n- The same workflow definition completes on `builtin` and on each adapter\n with the same `Result` shape and captures.\n- A harness instructed to `git commit` fails its step, and the task branch\n is 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 stage with a failing gate resumes the same session with the gate output,\n then succeeds or exhausts its iterations.\n- Two tasks naming the same home with `max_concurrent = 1` run one at a\n time; the second waits as `pending`.\n- An API key never appears in the worktree, the harness home, the task log,\n or the event stream.\n- Stopping a run kills the harness process within the step's cancel path.\n" + }, { "url": "/dev/prds/identity-decision/", "title": "Identity for users, agents and external agents — decision", @@ -741,6 +747,10 @@ "title": "Extensions centre", "url": "/dev/prds/extensions-center/" }, + { + "title": "External agent harnesses", + "url": "/dev/prds/external-agent-harness/" + }, { "title": "Identity for users, agents and external agents — decision", "url": "/dev/prds/identity-decision/" diff --git a/docs/prds/external-agent-harness.md b/docs/prds/external-agent-harness.md index ec6ce3c2d..b9799ca3f 100644 --- a/docs/prds/external-agent-harness.md +++ b/docs/prds/external-agent-harness.md @@ -132,6 +132,14 @@ A harness run is one `agent` StepExecution. Subagents the harness spawns internally are not recorded as children. Their usage is included in the step's `tokens_used` when the adapter reports it. +## Agents never hold a harness + +An Agent reaches a harness only by invoking a Workflow whose stage names it. +No Agent tool, chat tool or capability exposes a harness, its home or its +credential. The stage boundary is what carries the container, the git and +path checks, the gate and the budget; a harness outside a stage has none of +them. + ## Out of scope - Chat through a harness. The gateway chat loop stays on the built-in