a7d6f71d5a2c9da170a46bfc4471f9979189de87
12
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
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. |
||
|
|
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. |
||
|
|
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. |
||
|
|
54ee79553f
|
docs(site): describe archie as an event-driven agent platform
The landing page still opened with "archied is a resident daemon that polls a forge", which is wrong twice over. A deployment is a set of contracted services, not one process, and a forge is one event source among several: signed webhooks from any sender and chat-channel messages reach the same playbook routing that a GitHub or Gitea issue does. GitHub/Gitea was the first case, not the shape of the product. The intro now leads with the event path (event -> playbook -> workflow in an isolated worktree) and says outright that sources, their fields, and the workflows they reach are configuration rather than code. "What runs where" names the actual services and which contract each owns. The stray "Work arrives as events." line went with it, since the intro now states that. Claims are held to what ships: module actions load and type-check but are not dispatched yet, so the page promises one outcome per event, not a fan-out. |
||
|
|
457ad8843e
|
docs(site): drop the internal-invariant clause from the landing intro
The intro stated per-task sandbox and credential isolation and daemon-owned git to a reader who has no reason to act on it. Keep the event framing; the enforcement detail stays in What runs where and ARCHITECTURE.md. Regenerate docs/data/generated/docs.json with task docs:artifact. |
||
|
|
1b54a18e43
|
feat(docs): emit the canonical public-docs artifact the app renders
MkDocs retires and the Astro app becomes the only public site, so the artifact is the product and the Markdown stays the source -- the split tools/newsgen already states for releases. tools/docsite walks the published set and writes docs/data/generated/docs.json: every page's directory-style url, title, section and raw Markdown body, plus the sidebar tree derived from the layout. Three things the artifact has to get right, each of which was wrong in a draft: - LINKS. The published pages carry relative .md links that MkDocs rewrote at build time and nothing else will. Each is rewritten to the target page's url using the same function that builds urls, so a link and its target cannot disagree; anchors and scheme-qualified links pass through; assets resolve by the same rule and none are referenced. - FRAGMENTS. A link can resolve to a page and still be broken, because a fragment matching no heading lands the reader at the top of a long document. Each is checked against the target's headings, by the slug rule a table of contents uses. - REFUSAL. A link whose target the set holds back, or whose fragment matches no heading, fails the generator naming the file, the line and the target. This found three citations from settled architecture pointing at two PRDs the blanket prds/* exclusion withheld -- links that were already 404s on the published site, so the exclusion broke citations rather than withholding drafts. Both targets are now published, for a reason distinct from the three ratified PRDs already published. The published set moves out of mkdocs.yml into the generator with its reasons: a renderer reading the artifact cannot see why a page is absent. docs/data/generated is accounted for by docsgen's generatedArtifacts, which now names this file beside contracts.json -- one ownership registry for the directory rather than one per writer, so neither tool reports the other's artifact as unaccounted. docs:artifact regenerates; docs:artifact:check reproduces into memory and fails on drift without touching the tree, wired into task check beside news:check. The existing docs:site target is MkDocs and was left alone -- a first attempt at that name silently ran MkDocs and produced nothing. Verified: task check exit 0, docs:artifact:check reporting 23 pages. The artifact carries 23 pages, no archive/ inspiration/ or news/ entry, and the five PRDs the set declares. Coverage: the published set and its count, url derivation, the nav tree, both refusal paths, and check's no-write guarantee. |
||
|
|
e0b6aa6105 |
feat(workflow): post line-anchored review comments with suggested fixes (#891)
* feat(workflow): post line-anchored review comments with suggested fixes Bead archie-core-q9au (docs/prds/inline-review.md). A review's findings reached the operator only as a flat list in the PR body, so the author had to map every finding back to its line by hand and apply mechanical fixes by hand. Now the line-anchored findings are also posted as inline review comments, carrying a one-click suggestion when the reviewer could state the fix. Domain (internal/domain/workflow): - ReviewFinding gains Suggestion; Validate rejects one on anything but a confirmed finding, so the agent's record_finding call is refused with something it can act on. Validate splits into validateAnchor / validateClassification / validateDisposition, which also brings it back under the cyclop limit the gate enforces. - StagePostReviewComments runs after StageOpenPR in the implement workflow. It posts only line-anchored findings (Line > 0); a whole-file finding has no line to attach to and stays in the body list, which remains the complete record. It is best-effort: the PR is open and the body already lists every finding, so a failed comment is logged, never a park -- the same reasoning as OpenPR's existing best-effort LinkBranch call. - The suggestion fence is gated on Verdict == confirmed where the fence is written, because it is a one-click apply: a wrong suggestion breaks the code and the author has to notice. Forge (internal/forge): ReviewCommentWriter + GitHub/Gitea implementations, type-asserted like PullRequestReader so a forge that cannot is skipped rather than faked (NoopForge is pinned as not satisfying it). GitHub loops one CreateComment per comment and joins the failures, so one refused anchor cannot drop the rest; Gitea carries them on a single COMMENT-state review. Two deliberate departures from the PRD's sketch, both recorded in it: - The interface is batch (CreateReviewComments), not one call per comment: Gitea's only inline shape is one submitted review, and the set then crosses NATS once instead of once per finding. - The head SHA is resolved inside each forge implementation rather than by the caller. The stage runs in archie-agent, which holds no forge credentials and has no PullRequestReader; the daemon-side forgerpc handler is the only place that does. Transport (internal/forgerpc): workflow.Forger gains the method, so the agent reaches the daemon over the new create_review_comments subject; the server type-asserts the writer and answers an incapable forge with an error the stage logs. This is the one proxied method whose absence on an image skew does not park a task. The reviewer prompt and record_finding schema ask for a suggestion on a confirmed, mechanically fixable defect only. Regenerating the wfextract symbol table -- the documented way a new exported workflow symbol reaches interpreted stage plugins -- also picked up symbols that were missing from the committed table (the Status* and Source* constants, ReviewCheck, Store, Task, and the _Store wrapper). Nil-guards were re-applied to every wrapper afterwards, as that file's header requires. Evidence: task check exit 0 (incl. 229 UI tests). Three mutations of the new stage logic each fail a test that names the behaviour -- dropping the confirmed-only gate, dropping the Line > 0 filter, and letting a posting failure escape -- so the tests discriminate rather than passing vacuously. * fix(build): drop the Dockerfile pin assertion The guard fetched golangci-lint's go.mod at image build time to fail the build when GOLANGCI_LINT_VERSION and GOFUMPT_VERSION disagreed. It only ever tripped on self-inflicted pin drift, but it added a network fetch and a new failure mode to the release build, which is not where that belongs. The pins stay correct (golangci-lint 2.13.2, whose vendored gofumpt v0.11.0 equals GOFUMPT_VERSION) and the comment above them still states the invariant, so the reasoning survives without the build-time machinery. The pin change itself reaches the agent image through the normal release path: CI rebuilds and pushes archie-agent on an archie/vX.Y.Z release, and a gateway-only release deliberately does not. * feat(workflow): add the remediate workflow for PR review remediation Implements step 5 of docs/prds/pr-review-remediation.md: a remediate workflow that resumes the task's existing worktree onto its PR branch (worktree.Manager.Resume, not Prepare's refresh), runs a builder agent against the review's actionable comments, commits and pushes to the same branch, and replies via the forge's ReplyToReview. Task.RetryCount doubles as the remediation round counter, capped by the repo's max_retries; the round-cap stage parks the task and posts one comment when it's hit. Task gains a ReviewPayload field (JSON-encoded review unit) with full store/proto/staterpc plumbing. workflow.Forger gains Comment and ReplyToReview, proxied to archie-agent via a new forgerpc RPC. Resume and its Dir lookup are added as an unexported optional Trees capability rather than widening the exported interface, which is already at golangci-lint's interfacebloat cap and is projected into wfextract's Yaegi symbol table for repository-authored stage plugins. The daemon-side reaction consumer that dispatches into this workflow (subscribing ARCHIE_REACTIONS, grouping comments by review, enforcing per-task serialization) is tracked separately in archie-core-8li9.4. * feat(messaging): extract standalone messaging service binary and process composition * feat(messaging): adapt channel frontends to consume Gateway ChatContract * feat(messaging): remove in-process channels and Router from daemon bootstrap Telegram, email and webhook now run only in the Messaging Service, which reaches this process through the Gateway's ChatContract. The daemon builds no channel and no gateway.Router, so the wiring that existed only to serve them goes with it: setupGateways, setupEmailGateway, setupWebhookGateway, setupTelegramGateway, buildTelegramRouter, makeTelegramReload and the release-announcement path helper. The seams those paths owned move to where they can still be honoured: - Channel ValidateConfig runs in archiemessaging.compose, which now returns an error, so a configured-but-invalid front-end fails the service rather than being dropped silently. - The inbound rate limiter moves to the Gateway process, which owns the only Router and therefore the only place a per-sender budget applies to every channel's turns. - The daemon's gateway readiness probe becomes a ContractProbe against the Gateway. It cannot observe a channel lifecycle it no longer runs, and a channel-count probe would have reported every daemon degraded. - telegramSetup is now chatSetup (in chat_setup.go), trimmed to the fields a chat turn runner actually reads. Telegram operator features that were wired only in the daemon (/update, release announcements, version reporting, SIGHUP reload) are not yet wired in the Messaging Service: archie-core-8cda.6.6. Channel lifecycle reporting: archie-core-8cda.6.8. The Gateway process builds no worktree manager, so review_pr is unadvertised on every channel: archie-core-8cda.6.7. * feat(messaging): re-wire the Telegram operator surface in the Messaging Service setupTelegramGateway satisfied eight telegram.Gateway seams from the daemon's own process. Each is resolved by where the fact it needs is owned, not by where it used to be built; the decision table is in docs/architecture/migration-decisions.md. Wired here: /update (built from this service's own [chat.telegram] check and install commands), the update-report relay (same sha256(bot_user)[:8] path the daemon wrote, so a pending report is found rather than written afresh), show_tool_calls, and /restart's config reload, which re-resolves the token and allowlist from this service's own file and refuses a reload that resolves to an empty token. /version is sourced from the Gateway: ChatSnapshot gains a Version field carrying the Gateway's rendered build block, read per call and bounded by the dependency timeout. cmd/archie-messaging deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. RunningVersions and ReleaseAnnouncements stay nil. Both need a component's real running version, and the only versions this process can obtain are a different binary's stamps -- reporting them would manufacture exactly the false success the update check exists to catch, and the announcer without parseable versions is a no-op that reads as configured. archie-core-8cda.6.9 carries the contract that unblocks them. Dangerous stays nil: no composition has ever supplied a command authority. Enrich is dropped from the update service: componentInstallTypeEnricher read [nats], which this service must not decode, so the check command's own reported install type stands. * fix(workflow): guard inline review comments against head drift Two findings from the review of q9au. A comment's line numbers describe exactly one revision of the branch, but the forge resolved the pull request's head at posting time -- after the review had already read the worktree. A push in that window (a collaborator, a retry) meant the findings were anchored to whatever now occupied those lines, mislabelling instead of failing. The revision the review measured now travels with the comment set: OpenPR records it from the same worktree read it already performs (TaskContext.ReviewedHeadSHA), StagePostReviewComments threads it through Forger to forgerpc, and the forge refuses the whole set once the head it reads has moved off it -- which the best-effort stage logs, the PR body remaining the record. An unmeasured revision posts unverified rather than dropping every finding, so a worktree that cannot report one degrades instead of regressing. Suggestion was documented single-line only, because GitHub applies a suggestion fence up to its first line and a multi-line replacement would silently corrupt the file. Only the verdict was validated, so a multi-line suggestion reached the renderer and posted as that truncated fence. Validate now rejects an embedded newline, which makes record_finding refuse it with feedback the model can act on instead of the reviewer discovering the corruption later. |
||
|
|
dba169a250
|
fix(workflow): require a workflow from triage when a code change is needed
The selection criteria alone left workflow optional and defaulted an omitted or unrecognised value to implement, so a decide call could still skip the decision and send an unsettled capability straight to the builder. Omission is now a retryable rejection: CaptureTool gains RequiredWhenTrue, a conditional requirement a flat RequiredFields entry cannot express, because the close-without-change branch has no workflow to name and must not be made to invent one. A rejected call is not recorded, so it does not consume MaxCalls and the model retries with the field. A value outside the enum now fails the stage rather than degrading to implement: reaching OnResult with one means the model ignored its own schema. Splits validateCaptureArgs into per-constraint checks (cyclop) and carries the regenerated contracts.json. |
||
|
|
294b641bb7
|
docs(skills): re-verify every .agents skill against the current tree
All ten `archie-*` skills carried claims that no longer matched the
checkout. Re-verified each against code, git history, and the shipped
configuration, then corrected the drift.
Structural changes the skills had not caught up with:
- Composition root moved: `cmd/archied/main.go` is a ~30-line dispatcher
into `internal/app/archied.Run()` with wiring in `bootstrap.go`. The
skills still described `cmd/archied` as the wiring site, which also
silently zeroed the diagnostics delivery snapshot.
- Config decoding moved out of `internal/config` into
`internal/infrastructure/configuration`. `config.Load` / `config.LoadDir`
no longer exist; the loader is `configuration.New` + `Loader.Resolve`.
- Task contract moved to `internal/domain/storecontract`, with
`internal/store/interface.go` holding aliases only. The task type is
`internal/domain/workflow/task.Task`.
- `internal/workflow` became `internal/domain/workflow`; `internal/storerpc`
became gRPC `internal/infrastructure/staterpc`; `internal/policy` does not
exist.
- `Store.Transition` now guards on `from` and writes status plus history in
one transaction. Three skills still described the old non-atomic behavior
as current and open.
- `internal/domain/{messaging,workflow,workintake}`, `internal/eventbus`,
`internal/app`, and `internal/infrastructure` now exist.
`internal/domain/{agent,identity}` and `internal/policy` remain target-only.
Tooling and environment facts:
- Go 1.27.0 (root and tools modules), golangci-lint 2.13.2, staticcheck
2026.2.1; snapshot dates and HEAD moved to 2026-09-18 /
|
||
|
|
4b340d2b56 |
fix: harden task and chat execution
Task runs now preserve real model context limits, provider usage, baseline-repair spend, commit identity, durable agent-finish telemetry, and useful timeline details without imposing a token cap. Dashboard forge links are canonical per owning GitHub or Gitea identity. Chat turn claims acquire SQLite writer intent before reading, eliminating the concurrent SQLITE_BUSY snapshot race. |
||
|
|
cc53e5258d |
fix(telegram): compact tool output and drop turn caps
Render completed ToolCallEvents as Telegram-safe streaming blocks with compact name/status and a short cleaned preview. Summarize file contents and listings instead of dumping source or quoted JSON. Collapse repeated legacy turn-budget failures. Remove max_tokens turn gating and the 200000 turn_budget_chars default so absent or commented config cannot restore an aggregate cap. Keep per-result max_result_chars and spill. Confine find/grep discovery to the active workspace/worktree. Refs #604 |
||
|
|
69640b5216 |
docs: consolidate into a single docs/ tree
Fold the old docs/ into the VitePress site and rename docs-2 -> docs. The 12 architecture PRDs become first-class pages at docs/architecture/ with sidebar nav, rather than being buried under an archive path. Historical material stays at docs/archive/. Rewrites every docs-2 and docs/prds/architecture reference across the repo. Site builds clean. |