Commit Graph
3 Commits
Author SHA1 Message Date
sam 2cb2275eb6 docs(prds): settle identity for users, agents and external agents
One identity record covers users, agents, external agents, service accounts and the
system. Authentication is delegated to the estate's OIDC provider and attribution
stays archie's. Nothing that verifies a credential, issues a session, stores a
password or checks a permission is built here, per Sam's hard requirement that
authentication and authorisation are OSS archie integrates.

Authelia is the only provider, because the estate already runs it in front of the
dashboard and it issues credentials for both kinds of caller: authorization code
for humans and client_credentials for machines, whose subject is the client's own
identifier. Each agent is its own client, so two agents are distinguishable in the
audit trail and revocable separately. SPIFFE/SPIRE is rejected on operational fit
rather than quality: it is adopted and its attestation is strictly stronger, but it
adds a control plane archie does not have and answers a threat archie does not face
while its agents run in containers the operator launches.

internal/domain/identity survives and is not replaced by the provider's directory,
because it carries what the directory does not: lifecycle, bindings and
attribution. archie owns the subject binding that ties an identity to the provider
subject asserting it -- the same bridge identity_aliases already provides from a
legacy name -- plus the lifecycle, the attribution and the identity audit trail. It
owns no credential, password, session, token, signing key or permission rule.

How an agent proves who it is: it presents a token the provider issued to its own
client, archie validates it against the provider's published keys and takes the
subject as the acting identity, so an agent holds the secret and archie holds only
public keys. A WebMCP tool call cannot be a proof of agent identity and cannot be
made one -- a page can invoke its own tools, so an agent's call and a page script's
call arrive identically and the difference does not exist on the wire. It is
attributed to the identity the request presented with its source as a hint, and it
never records that an agent acted or that a human approved. Agent-initiated action
therefore arrives on a surface that carries a credential.

Task actions gain both attributions: the acting identity, derived from the
credential and never from a supplied string, and the authorising principal whose
authority the action used. The event kind describes the actor, so
KindHumanApproved is recorded only when a human acted; an agent acting under a
standing approval records itself as actor and the human as authorising principal.
An action with no authorising principal is unattributed rather than attributed to
the actor's own authority, and the review gate's approver is the approval's
authorising principal, not the surface they used.

External agents are first-class: the same record, kind service_account, bound to
its own provider client, at the cost of a client registration and a secret to
rotate per peer. Authorisation is deferred: no engine, no policy language, no
decision point, with the credential's scopes as the only input; the decision point
goes behind a single archie interface when per-skill limits are needed.

The PRD is a development-audience page, so it regenerates dev-docs.json to 69
pages. Verified: task check exit 0, including docs:prds.
2026-09-22 14:10:55 +10:00
sam 85e27e3778 docs(prds): cement A2A as the agent-to-agent protocol
Sam's decision, recorded as requirements rather than options. A2A carries
agent-to-agent work: discovery of what a remote agent offers, delegation of a unit
of work, progress on it, and the artifacts it produces. MCP stays the tool layer --
the two are complementary, and internal/tools/provider already registers MCP
providers as optional capabilities. A2A rides archie's existing transports, which
the protocol permits: its canonical data model is Protocol Buffer messages and it
defines a gRPC binding, so archie speaks it over the gRPC and NATS it already runs.

The boundaries are requirements. internal/domain/messaging stays the human and
channel layer, because a Conversation is a ChannelID and a ThreadID and its
participants are people. internal/agentexec stays the daemon-to-worker execution
protocol, whose Request, Result, gate and budget policy A2A never carries. A2A is
an edge protocol that composes with both.

The load-bearing decision, and the one that constrains everything downstream:
archie's work lifecycle is MAPPED to A2A's, not expressed in it. An A2A task is a
view over archie's own task, and archie's status stays the record of truth. Three
gaps make the mapping partial, and each is a fact A2A's states cannot hold: A2A's
terminal states describe what the agent did, while archie's merged and rejected
describe what a forge did afterwards; pr_open hands work to a human reviewer, while
A2A's input-required means the CLIENT must send more input; and declined, parked
and dead are outcomes of archie's own policy. Adopting A2A's state names as the
persisted task status is rejected outright -- it would migrate the task store and
drop the forge outcomes that tell a caller whether the work was accepted.

An A2A agent is an Identity: the actor archie persists, versions and scopes
credentials to. A persona is prompt text with no endpoint; an agent container is
task-scoped and ephemeral; the daemon is the process that serves the identity. The
Gateway serves the card for the identity it is configured as, over the gRPC
binding's Get Agent Card operation, and the card is derived -- skills from the
catalog, identity from configuration, capabilities from what the process already
advertises -- never hand-written, and carries no secret.

archie is a server first, because the work a peer would delegate exists only inside
archie. An inbound call is authenticated at the transport by the bearer-token
interceptor the Gateway already applies: A2A carries no identity in its payload, so
the transport credential is the identity. Authorization is per skill, which is
A2A's own model. Task-scoped grants are not A2A credentials -- reusing one would let
a peer act with a worker's authority -- and the dashboard's authentication gates an
operator interface, not an agent endpoint.

The new PRD is a development-audience page, so it regenerates the development
artifact rather than the public one: dev-docs.json goes to 68 pages and
docs.json is unchanged.

Verified: task check exit 0, including docs:prds, and both docsite checks.
2026-09-22 13:45:06 +10:00
sam a75df5eb0c feat(docs): split the published set by audience, public and development
The site's sidebar held the landing page and one guide next to seventeen
architecture records, the migration register, the review procedure and five
PRDs. Nothing there is secret -- every development page may be read by anyone --
but a reader who wants to know what Archie is and how to point an event at it
was meeting contributor material with no signal that it was not for them.

One source tree now yields two sets: public (index, guides/) under /docs/, and
development (architecture/, prds/) under /dev/, each with its own artifact and
its own derived sidebar. archive/, inspiration/, news/ and the credential notes
stay out of both, unchanged.

Selective PRD publication is gone rather than carried over. It existed only
because settled architecture cites PRDs and a link to a held-back target fails
the generator, so five PRDs published to keep those citations alive; with both
halves of every such citation in the development set, the exception has no work
left to do. Both sets are generated in one pass over one url map, so a citation
that crosses between them resolves to the base its target is served under, and
the refusal now fires only for a target genuinely in neither set.

Widening the set exposed a scanner bug worth its own note: the link regex
matched `Resolve[T](i, src, exportPath)` inside a code span and refused the page
for a link to `i,`. Code spans and fenced blocks are now skipped, because what a
renderer draws as a link is the only thing this tool may rewrite or refuse a
page for.

docs/prds/public-and-dev-docs.md records the decision. Draft: the three choices
in it are the maintainer's, the write-up is not yet reviewed.
2026-09-22 13:41:13 +10:00