docs(prds): agents reach a harness only through a workflow stage

This commit is contained in:
sam committed 2026-09-26 01:41:12 +10:00
1 parent 20152f2da3
commit 92a457e36b
2 files changed
+18

No files matched your search

+10
View File
@@ -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 rathLine truncated
},
{
"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 changLine truncated
},
{
"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/"
+8
View File
@@ -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