diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index afa783dfa..5a1bbd6a2 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -240,6 +240,12 @@ "section": "PRDs", "body": "# Embedded NATS execution -- decision\n\n**Status:** Finalised\n\n**Date:** 2026-08-24\n\n**Beads epic:** `archie-core-q15y`\n\nThis decision supersedes the position that embedded NATS was only a\ndistribution mechanism and could not be an agent-execution topology. That was\ntrue only because the embedded listener was unauthenticated loopback. It left a\nsecond production architecture in which `archied` ran autonomous workflows in\nits own process, weakening the isolation boundary that managed task containers\nexist to provide.\n\n## One execution architecture, two broker deployments\n\nEvery autonomous repository workflow is handed over as one complete task via\nNATS and runs in a task-scoped `archie-agent` container. `archied` remains a\nnative, long-lived orchestration and interactive-chat process; its operator\nconfigured host filesystem access is unchanged. It owns task admission,\nstate, forge and worktree operations, container lifecycle, and the broker when\nthe embedded deployment is selected. It does not run an autonomous model loop.\n\nNATS has two supported deployment shapes:\n\n| mode | meaning |\n| --- | --- |\n| `embedded` | `archied` owns an in-process JetStream server (default). |\n| `external` | `archied` and workers connect to the configured NATS URL. |\n\nBoth shapes have identical task semantics: one container and one full-task\nrequest per workflow. Broker placement must not select a different executor.\nThe legacy `agent` section and `containers.enabled` key remain decode-only\nmigration inputs. `nats.mode = \"off\"`, per-stage NATS, in-process execution,\nand subprocess execution are not production choices.\n\nSQLite remains authoritative for task state. NATS is the sole autonomous work\nhandoff. SQLite recovery may identify work that needs republishing, but it must\nnot cause `archied` to call `workflow.Run` locally.\n\n## Embedded reachability and authentication\n\nAn embedded listener uses a cryptographically random bearer token generated for\neach daemon start. The token exists only in process memory and the environment\nof managed worker containers; it is never written to config or logs.\n\nFor a native daemon with managed containers, startup resolves the Docker bridge\nthe workers will join. The listener binds only to that bridge's host gateway\naddress on a random port. Both the native daemon and workers use that same\nreachable endpoint, and every client supplies the generated token. Binding a\nDocker bridge address keeps the listener off ordinary LAN interfaces without\npublishing a host port. A configured user bridge is respected; otherwise the\nDocker default bridge is used. A network without a usable local IPv4 gateway is\na startup error for autonomous execution.\n\nIf Docker is unavailable, interactive chat may still start and embedded NATS\nmay remain loopback-only, but autonomous tasks park with an explicit container\ncapability failure. They never fall back to host execution.\n\n## Ownership and lifecycle\n\n- `internal/infrastructure/eventbus/nats` owns the authenticated embedded\n server and exposes its runtime endpoint, not the server implementation.\n- `internal/container` resolves the worker bridge and gateway and owns task\n container lifecycle.\n- `internal/app` composition selects embedded or external broker deployment,\n freezes the connected runtime endpoint for worker environments, and wires the\n full-task handoff.\n- `cmd/archied` remains process input only as the domain migration reaches this\n composition path.\n\nThe daemon starts the embedded server before its client, closes clients before\nthe server, and keeps JetStream data beneath the daemon data directory. NATS URL\nand token are startup-built values: a reload cannot send new workers to a broker\ndifferent from the one the daemon is using.\n" }, + { + "url": "/dev/prds/event-automation/", + "title": "Event automation: identified events, typed parameters, purpose-built agents", + "section": "PRDs", + "body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools,\n repo) profile) secrets, access)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required` gives the agent a worktree of the task's repository.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another workflow. The call passes the callee's\ninputs, and the callee runs as its own run with its own agent profile, so one\nevent can start an investigator that then calls a containment workflow:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n inputs: { src_ip: inputs.src_ip }\n wait: true # false starts the callee and continues\n```\n\n- With `wait: true` the caller receives the callee's outputs and fails if the\n callee fails. With `wait: false` the caller continues and the callee's\n outcome is reported on its own run.\n- A call's inputs are checked against the callee's declared inputs when the\n calling workflow is saved.\n- A workflow that calls itself, directly or through other workflows, is\n refused when it is saved. Calls are limited to a fixed depth at run time.\n- A callee must be enabled for the caller's org.\n\n### Bindings\n\nA binding connects an event type to one workflow:\n\n- an optional filter on mapped parameters (`severity in [\"high\", \"critical\"]`),\n written in the CEL the playbook engine already uses;\n- an assignment of workflow inputs from mapped parameters or constants,\n checked against the workflow's declared inputs when the binding is saved;\n- a repository, when the workflow's `repository` is not `none`: either fixed\n (`acme/api`) or taken from a parameter (the GitHub webhook's\n `repository.full_name`).\n\nAny number of bindings may use one event type. Approval and re-approval after\nan edit are unchanged. A binding whose workflow input types no longer match is\nrefused at dispatch and reported on the binding.\n\n### Agent profiles\n\nA profile is a named execution environment that a workflow selects:\n\n- the container image;\n- the tools the agent may call;\n- the secrets injected into it, by reference to the secret store, never\n inline;\n- its network access and forge access.\n\nThe global `[containers].image` becomes the default profile, so existing\nworkflows are unchanged. A secret or permission is granted to a profile, not\nto a binding, so an event can never widen what an agent can do.\n\n### Workflows belong to orgs\n\nArchie ships a default workflow catalogue that every org can use. An org can\nadd its own workflows, and can enable or disable any workflow, default or its\nown, for itself. A binding can target only a workflow enabled for its org, and\ndisabling a workflow stops its bindings dispatching and marks them on the\nbinding list.\n\n## Delivery order\n\n1. Event types: structural signatures, grouping, naming, match rules, and the\n inspector view of proposed and unidentified events.\n2. Mappings per event type, and multiple bindings per source.\n3. Workflow inputs, structured parameters in the task brief, and\n `repository: none | optional | required`.\n4. Agent profiles with image, tools, secret references and access.\n5. Signing as a source setting, with the unsigned option; UUIDv7 source paths\n with a custom-path override.\n6. Workflows calling workflows, with declared outputs.\n7. Org-scoped workflow catalogue, once orgs exist.\n\nEach step ships usable on its own. Step 3 is the first where an event that has\nnothing to do with a repository can run a workflow.\n\n## Out of scope\n\n- How forge-issue playbook triggers (`internal/domain/eda/playbook`) relate to\n event types. They stay as they are until event types exist.\n- Built-in catalogues of event types for known senders.\n- Orgs themselves: membership, access, and how sources and bindings belong to\n one. This design needs only an org to own workflows and their enabled state.\n- Running an agent outside a container.\n\n## Verification\n\n- Two GitHub webhooks with different `X-GitHub-Event` headers posted to one\n source are grouped into two proposed event types, and a firewall payload\n with a different shape is grouped separately.\n- A capture matching no named type is shown as unidentified and starts\n nothing.\n- A firewall event runs a `repository: none` workflow with its mapped inputs\n readable by the agent as structured data, and no clone is made.\n- A GitHub `pull_request.opened` event runs a PR review workflow against the\n repository named in the payload.\n- An event type created from a pasted payload has that payload's schema, and a\n later matching event is identified as it.\n- A new source gets a UUIDv7 path; a custom path that is already taken is\n refused.\n- A workflow that calls another with `wait: true` receives its outputs; one\n that calls itself through another workflow is refused when saved.\n- A mapping's matched-event count rises by one for each event it resolves.\n- A workflow disabled for an org cannot be targeted, and its existing bindings\n stop dispatching.\n- A binding whose filter excludes an event does not dispatch it.\n- An agent receives only the secrets its profile references.\n- An unsigned event on a signed source is captured and not dispatched. An\n event on an unsigned source is dispatched and marked unsigned.\n" + }, { "url": "/dev/prds/event-capture-storage/", "title": "Event capture storage -- decision", @@ -611,6 +617,10 @@ "title": "Embedded NATS execution -- decision", "url": "/dev/prds/embedded-nats/" }, + { + "title": "Event automation: identified events, typed parameters, purpose-built agents", + "url": "/dev/prds/event-automation/" + }, { "title": "Event capture storage -- decision", "url": "/dev/prds/event-capture-storage/"