From da2589e2f4fc66c15df1a82de183464131fc2d2e Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 23 Sep 2026 03:16:35 +1000 Subject: [PATCH] chore(docs): regenerate dev-docs.json for the artifact-sender PRD 0e6c6fc6 added docs/prds/artifact-sender.md without regenerating the artifact, so docs:artifact:check failed at that commit. Generated from a clean worktree at 0e6c6fc6. --- docs/data/generated/dev-docs.json | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 2c85a1f3f..f8286d4c4 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -126,6 +126,12 @@ "section": "PRDs", "body": "# Agent2Agent as archie's agent-to-agent protocol — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** the A2A Protocol Specification v1.0.0 (`a2a-protocol.org`) for the\nprotocol, `docs/architecture/organisation.md` for package placement, and\n`docs/architecture/migration-decisions.md` §2 for session and messaging design.\n\n## Decision\n\nA2A is the protocol archie speaks to other agents. It carries agent-to-agent\nwork: discovery of what a remote agent offers, delegation of a unit of work to it,\nprogress on that work, and the artifacts it produces.\n\n## Layers\n\n**MCP stays the tool layer.** MCP connects a model to tools and data; A2A connects\nagents to agents. They are complementary and archie runs both:\n`internal/tools/provider` registers MCP providers as optional capabilities, so an\nA2A call and an MCP tool call are different kinds of traffic with different\nowners.\n\n**A2A rides archie's existing transports.** A2A's canonical data model is\nProtocol Buffer messages and it defines a gRPC binding, so archie speaks A2A over\nthe gRPC and NATS it already runs. A second wire format, a second broker, or a\nbespoke protocol for agent-to-agent traffic is a requirement not to introduce.\n\n## Where A2A stops\n\nA2A is not a general replacement for either of the two protocols archie already\nhas, and each boundary is a requirement rather than a preference.\n\n- **`internal/domain/messaging` stays the human and channel layer.** A\n Conversation is a ChannelID and a ThreadID, its participants are people on\n Telegram, email, webhook and the dashboard, and its records are what a curator\n reads. An A2A peer is not a channel participant and does not address a\n Conversation.\n- **`internal/agentexec` stays the daemon-to-worker execution protocol.** It\n carries a Request, a Result, gate and budget policy, and capture tools between\n the daemon and the agent container it owns. An A2A peer never receives that\n protocol, and A2A never carries gate, budget or protection policy.\n\nA2A is therefore an edge protocol: it exchanges work with peers outside archie's\nown process boundary, and it composes with the two protocols above rather than\nreplacing or abstracting them.\n\n## A2A Task mapping\n\n**Decision: archie's work lifecycle is mapped to A2A's, not expressed in it. An\nA2A Task is a view over archie's own task, and archie's status remains the record\nof truth.**\n\nThis is the load-bearing decision, because A2A's Task carries its own state\nmachine and archie's lifecycle is the on-disk format of its task store, whose\nstatus strings a rename migrates rather than changes.\n\nThe mapping is partial, and each gap is a case where archie knows something A2A's\nstates do not carry:\n\n- **Completion by another system.** A2A's terminal states describe what the agent\n did (`completed`, `failed`, `canceled`, `rejected`). archie's `merged` and\n `rejected` describe what a forge did to a pull request after archie finished\n its work. There is no A2A state for \"an external system accepted this\", so a\n completed A2A task cannot express the outcome that matters most to the caller.\n- **Handing work to a reviewer.** archie's `pr_open` means the work left\n archie's hands for human review. A2A's `input-required` is the nearest state,\n but it means the *client* must send more input, and a reviewer is not the\n client.\n- **Operator decisions.** `declined`, `parked` and `dead` are outcomes of\n archie's own policy and operator actions. A2A has no state for \"the operator\n refused this\" or \"a budget ran out and an operator must decide\".\n\nA WorkflowExecution is the unit an A2A task maps onto, because it is the attempt\nthat runs, streams and produces artifacts, and a follow-up attempt is a new\nexecution. A2A's own model agrees that a task is immutable once terminal and that\na refinement is a new task sharing the `contextId`, which is why archie's\nper-attempt executions and A2A's per-request tasks correspond.\n\n**Requirement:** the A2A state a peer sees is derived from archie's status by one\nmapping, and archie's status is carried on the task so a peer can read what the\nderivation lost. The mapping is total in the direction that matters -- every\narchie status has an A2A state -- and deliberately not injective, because the\ngaps above are facts A2A cannot hold.\n\n**Requirement:** adopting A2A's state names as archie's persisted task status is\nrejected. It would migrate the task store, and it would drop the forge outcomes\nthat tell a caller whether the work was accepted.\n\n## What an A2A agent is\n\n**An A2A agent is an archie Identity.** The Agent Card describes a durable,\naddressable actor with an endpoint, capabilities and authentication requirements,\nand an Identity is the actor archie persists, versions, suspends and scopes\ncredentials to.\n\nAn `agent.Persona` is not an A2A agent: a persona is prompt text selected for a\nturn, and it has no endpoint or credential. An agent container is not an A2A\nagent: it is task-scoped and ephemeral, and it terminates with the work it ran.\nThe daemon is not an A2A agent: it is the process that serves the identity.\n\n## The Agent Card\n\n**The Gateway serves the card, for the identity it is configured as.** A2A's\n\"Get Agent Card\" is an abstract operation with a gRPC binding, so the card is\nserved through the binding archie runs and needs no HTTP listener.\n\n**The card is derived, never hand-written.** Its skills come from the skill\ncatalog, its identity from the configured Identity, and its capabilities from\nwhat the process already advertises about itself. A card that restated\ncapabilities independently would be a second inventory of the same facts, which\nis the class of drift the existing capability reporting exists to prevent.\n\n**The card advertises the authentication archie applies**, and it carries no\nsecret. A card that named a token would be a credential published at a\nwell-known location.\n\n## Server before client\n\n**archie is an A2A server first.** Accepting A2A calls is the smaller direction\nand the more valuable one: the work a peer would delegate -- an issue taken to a\npull request, through archie's gates, worktrees and review -- exists only inside\narchie, and archie already serves its own contracts over gRPC to the Messaging\nService, the dashboard and the State Store. Acting as an A2A client to remote\nagents is a later capability, and one that consumes the same contract.\n\n## Authentication and authorization\n\n**An inbound A2A call is authenticated at the transport, by the same bearer-token\ninterceptor the Gateway applies to its other contracts.** A2A carries no identity\nin its payload by design: identity is established where the connection is, so the\ntransport token is the identity and no field in a Message or Task names a caller.\n\n**Authorization is per skill**, which is A2A's own model: the card advertises\nskills, and a caller may invoke the skills its credential is scoped to.\n\n**Task-scoped grants are not A2A credentials.** They scope a worker's access to\none task's records inside the State Store and are issued by the daemon for its own\ncontainers. Reusing one as an inbound A2A credential would let a peer act with a\nworker's authority, which is the isolation the grants exist to enforce.\n\n**The dashboard's authentication is not an A2A scheme.** It gates an operator\ninterface, not an endpoint that agents call, so it authenticates no A2A request.\n\n## Package placement\n\n- The contract -- A2A's data model, operations and the mapping from archie's\n status -- lives in `internal/domain/\u003carea\u003e/`.\n- The binding that carries it over gRPC lives in `internal/infrastructure/`,\n beside the existing gRPC clients and servers.\n- Wiring of the contract to the Gateway and the task store lives in\n `internal/app/`.\n\n## Verification\n\n- A peer fetches the Agent Card over gRPC and receives the configured identity's\n identity, skills and authentication requirements.\n- A delegated task reaches an archie task, and the A2A state a peer observes\n changes as archie's status changes, through the one mapping.\n- A task that reaches `merged` reports an A2A state derived from it, and the\n archie status is readable on the task.\n- A call with no credential, and a call with a credential scoped to another\n skill, are both refused, with the refusal A2A defines for them.\n- A task-scoped grant presented as an inbound A2A credential is refused.\n- No A2A traffic reaches `internal/domain/messaging` or `internal/agentexec`.\n" }, + { + "url": "/dev/prds/artifact-sender/", + "title": "Artifact sender", + "section": "PRDs", + "body": "# Artifact sender\n\n**Status:** Approved\n**Revision:** 1\n**Authority:** this document\n\n## Purpose\n\narchie-core publishes artifacts — design documents, review reports, research briefs,\nrunnable pages — to the offloaded.dev collaborative editor. A person reads the\nartifact, comments on it, and the artifact page is the shared surface for iteration.\n\nThe receiving contract is owned by the editor: `POST /api/artifacts` with a bearer\nservice token, a closed field set, and server-side idempotency on `requestId` plus\nlast-write-wins on `sentAt`. This document owns only what archie-core sends.\n\n## Scope\n\nVersion one publishes one-way: archie-core sends, the editor receives. The first\nproducer is the pull-request adversarial review: a completed `ReviewReport` is\nrendered to markdown and published after the review completes.\n\nChat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share\ntokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The\nreceiving contract already carries them; version one does not exercise them.\n\n## Configuration\n\n- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with\n `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.\n- An empty `base_url` disables the sender: no client is constructed, nothing is\n registered, and publishing degrades to a log line.\n- The token is runtime configuration. It is never baked at build time.\n\n## Sender\n\n- New package `internal/infrastructure/artifactsync` exposing one method,\n `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL.\n One-method injected seam, concrete client constructed by the boot path when the\n configuration resolves — the `crondelivery.Courier` posture.\n- The client POSTs the frozen contract body. Each publish sends the complete\n source: versions of record are full snapshots, never diffs.\n- A `503` response is retried three times with backoff. `401` and `400` are not\n retried; they are logged with the field reason the response names.\n- `requestId` is `artifact:\u003ctask-id\u003e:\u003cversion\u003e` when the producer is task-backed,\n otherwise `artifact:\u003cidentity\u003e:\u003csentAt-utc\u003e`. Sending the same `requestId` with\n an equal or older `sentAt` must be a server-side no-op, which makes sender-side\n retry safe.\n\n## Report rendering\n\n- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`:\n the summary as the lede, one finding per subsection with file, line, verdict,\n level and the failure scenario, and the verified properties as a \"checked\n clean\" list. Findings carry their disposition when present.\n- The renderer performs no I/O and imports no infrastructure.\n\n## Attribution\n\n- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer`\n when no task identity resolves; otherwise the task's identity name.\n- `source`: the producing subsystem, `pr-review` for version one.\n- `task`: owner, repository and issue number from the task when one exists.\n\n## Failure behaviour\n\n- Publishing never fails the producing work. A failed publish is logged with its\n status and reason; the artifact is republished on the next production of the\n same artifact.\n- A successful publish records the artifact URL in the run report, so the PR\n description or task log links to the readable artifact.\n- The published URL is the editor deep link for the artifact, keyed on its\n immutable id. archie-core never mints share links; sharing is an\n account-holder decision made in the editor.\n\n## Verification\n\n- Client tests against a test server cover 201, 401, 400 with a field reason,\n and 503 retry behaviour.\n- The report renderer test covers a report with findings, checks, dispositions\n and a not-run status.\n- Configuration tests cover the disabled case, the `SecretRef` path and the\n `token_env` fallback." + }, { "url": "/dev/prds/binding-secret-encryption/", "title": "Binding secret at-rest encryption -- decision", @@ -517,6 +523,10 @@ "title": "Agent2Agent as archie's agent-to-agent protocol — decision", "url": "/dev/prds/agent2agent-protocol/" }, + { + "title": "Artifact sender", + "url": "/dev/prds/artifact-sender/" + }, { "title": "Binding secret at-rest encryption -- decision", "url": "/dev/prds/binding-secret-encryption/"