docs(prds): approve execution-tree and external-harness PRDs
This commit is contained in:
1 parent
22d36fef75
commit
a98ca2c8e9
3 files changed
+4
-4
No files matched your search
@@ -316,7 +316,7 @@
|
||||
"url": "/dev/prds/execution-tree-state-machine/",
|
||||
"title": "Execution tree and enforced state machine",
|
||||
"section": "PRDs",
|
||||
"body": "# Execution tree and enforced state machine\n\n**Status:** Draft\n**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);\nsettles the \"enforced WorkflowExecution state machine\" item in\n`docs/architecture/migration-decisions.md` section 4.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),\n`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).\n\n## Decision\n\nA WorkflowExecution becomes the root of a tree of StepExecutions. Every stage\nrun, and every agent call a stage makes, is its own durable record with a\nparent, an attempt, a status and an outcome. Both levels move only through a\ndeclared transition table, enforced by the State Store in the same transaction\nthat writes the audit row and the domain event.\n\n## Problem\n\n- A run is one `tasks` row. The only per-step record is the mutable `stage`\n column, overwritten as `workflow.Run` advances, plus observability events.\n A failed attempt cannot say which step failed or what its children did\n without replaying the event stream.\n- `Store.Transition` guards on the expected `from` status, but any `from` to\n any `to` is accepted. A `queued` to `merged` write succeeds.\n- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says\n which work was in flight, so an agent call that outlives its stage (a\n reviewer, a container) is invisible to the store.\n- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits\n `KindStageStart` separately. State and events can diverge.\n\n## Model\n\n```text\nWorkflowExecution (tasks row, id E)\n└── attempt N\n ├── StepExecution stage \"plan\" depth 0\n ├── StepExecution stage \"implement\" depth 0\n │ └── StepExecution agent \"implement\" depth 1\n └── StepExecution stage \"review\" depth 0\n ├── StepExecution agent \"review:1\" depth 1\n └── StepExecution agent \"review:2\" depth 1\n```\n\n- A StepExecution belongs to exactly one WorkflowExecution and one attempt.\n `parent_id` is null for a stage and names the enclosing StepExecution\n otherwise. Depth is derived from the parent, never supplied by the caller.\n- `kind` is `stage` or `agent`. A new kind needs a named consumer before it is\n added.\n- A retry starts a new attempt. Earlier attempts' StepExecutions are never\n rewritten.\n\n## Transition tables\n\nWorkflowExecution statuses are the existing `taskstate` constants, persisted\nstrings unchanged. `taskstate` gains the one table every writer checks:\n\n| From | To |\n| --------------- | ---------------------------------------------------------- |\n| `queued` | `running`, `closed_wont_do` |\n| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |\n| `waiting_human` | `queued` (approve), `closed_wont_do` |\n| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |\n| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |\n| terminal | none |\n\nStepExecution statuses:\n\n| From | To |\n| --------- | ------------------------------------------------------ |\n| `pending` | `running`, `cancelled` |\n| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |\n| terminal | none |\n\n`interrupted` means the process running the step died or shut down. It is\ndistinct from `cancelled`, which an operator or a parent asked for, and from\n`failed`, which the step reported.\n\nA StepExecution cannot reach `running` while its WorkflowExecution is not\n`running`, and cannot start under a terminal parent.\n\n## Enforcement\n\n- The table lives in `taskstate` (no dependencies), so the store, daemon and\n gateway share one copy.\n- Every store method that changes `tasks.status` checks the table and writes\n the audit and event rows, not only `Transition`. That includes the claim,\n `ParkTask`, `Requeue`, `RetryTask`, `BeginRemediation` and `RecoverStale`\n paths, several of which change status without an audit row.\n- The State Store rejects an illegal transition with a new sentinel,\n `ErrIllegalTransition`, carried across the wire through `mapError` like\n `ErrStaleTransition`. A stale `from` stays `ErrStaleTransition`.\n- Each transition is one transaction: guarded row update, audit row, domain\n event row. The events table is written by the store, not emitted beside it.\n `KindStageStart` and `KindStageFinish` are produced by the step transition\n and published to the bus after commit.\n- `workflow.Run` stops discarding persistenceLine truncated
|
||||
"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 persisteLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/extensions-center/",
|
||||
@@ -328,7 +328,7 @@
|
||||
"url": "/dev/prds/external-agent-harness/",
|
||||
"title": "External agent harnesses",
|
||||
"section": "PRDs",
|
||||
"body": "# External agent harnesses\n\n**Status:** Draft\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit the operator builds `FROM` or alongside the harness Kit. It is\nversioned image content, rewritten on every create, never state a run can\nmodify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nOrder of precedence, first match wins:\n\n1. the stage's `runner` in the workflow definition;\n2. the agent profile's `runner`;\n3. `builtin`, the ai-sdk agent loop.\n\n`runner` names a harness resource. `archie-agent` reads it when it builds the\nstage's runner; that is its only consumer. An unknown name, and a harness\nnamed by no stage and no profile, are validation errors.\n\nA harness resource holds the workload Kit reference pinned by digest, zero or\nmore mixin Kit references, the credential bindings it uses, and\n`max_concurrent` (default 1). Harness resources and credential bindings are\nState Store resources managed from the dashboard, so they apply without a\nrestart.\n\n## Credentials\n\nA credential binding is keyed by the Kit's `credential@1` `service` name and\nholds one of:\n\n- **API key:** a `{ engine, key }` secret reference resolved through\n `internal/secret`.\n- **OAutLine truncated
|
||||
"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- **OLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/identity-decision/",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Execution tree and enforced state machine
|
||||
|
||||
**Status:** Draft
|
||||
**Status:** Approved
|
||||
**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);
|
||||
settles the "enforced WorkflowExecution state machine" item in
|
||||
`docs/architecture/migration-decisions.md` section 4.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# External agent harnesses
|
||||
|
||||
**Status:** Draft
|
||||
**Status:** Approved
|
||||
**Authority:** `docs/architecture/agent-system.md` (agent execution as a data
|
||||
boundary); settles the harness non-goal deferred by
|
||||
`docs/prds/service-decomposition.md`.
|
||||
|
||||
Reference in new issue
Block a user