* 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.
432 lines
23 KiB
Markdown
432 lines
23 KiB
Markdown
# archie-core Architecture
|
|
|
|
**archied** is a resident daemon that discovers forge work — GitHub and Gitea
|
|
issues assigned to its bot user, carrying its label, or either (`dispatch`
|
|
mode, per identity) — by polling (the default) or, single-identity
|
|
deployments only, reacting to forge webhook events the instant they arrive
|
|
(`Forge.Intake` = `webhook`/`both`, see `docs/prds/event-sources-and-
|
|
reactions.md`), works each matched issue in an isolated worktree through a
|
|
routed workflow, and opens pull requests for human review. A single daemon can
|
|
serve several identities across several forges, each with its own `bot_user`,
|
|
label, and repository set.
|
|
|
|
## Package Map
|
|
|
|
This lists the load-bearing packages, not all of them — `internal/` holds ~36.
|
|
The domain migration is in progress (`internal/domain/`,
|
|
`internal/infrastructure/`), so **the tree is authoritative over this table**.
|
|
See `docs/architecture/organisation.md` for the target structure and
|
|
`docs/architecture/migration-decisions.md` for the current position.
|
|
|
|
| Package | Role |
|
|
| ---------------------------- | ------------------------------------------------------------------------- |
|
|
| `cmd/archied/` | Binary entry: config→forge→store→runtime→workflows→daemon |
|
|
| `cmd/archie-agent/` | Binary entry: flags, environment, signals, and agentworker invocation |
|
|
| `internal/app/agentworker/` | Agent worker composition, lifecycle, routing, and workflow execution |
|
|
| `internal/infrastructure/agentboot/` | Worker boot-brief filesystem decoding |
|
|
| `internal/infrastructure/agentgit/` | Worker git safe-directory setup |
|
|
| `internal/infrastructure/agenttransport/nats/` | Worker core-NATS full-task handoff and RPC client construction |
|
|
| `internal/config/` | Config types only — loading lives in `infrastructure/configuration` |
|
|
| `internal/daemon/` | Resident loop: poll, enqueue, claim, route, process, reconcile |
|
|
| `internal/domain/workflow/` | Engine: stage lists, routing, shared steps, workflow definitions |
|
|
| `internal/domain/workflow/task/` | Task-execution vocabulary (`Task`, statuses, mid-run `Store`, `Definition`) importable without the engine |
|
|
| `internal/domain/messaging/` | Canonical messages plus the chat wire contracts (`ChatContract`, sessions, turns, streaming) shared by gateway, channels, webui, and archie-ui |
|
|
| `internal/channels/status/` | Operator-facing channel lifecycle ledger (`State`/`Descriptor`/`Status`/`Manager`); the plugin contract stays in `internal/channels` |
|
|
| `internal/app/archiemessaging/` | Messaging Service composition: Telegram/email/webhook channels, dialling the Gateway's `ChatContract` over gRPC. The daemon runs no channel and builds no `gateway.Router` |
|
|
| `internal/domain/workintake/`| `TaskEnvelope`, routing `Kind`, label vocabulary, task subjects |
|
|
| `internal/agentexec/` | Worker-local stage protocol and ai-sdk loop runner |
|
|
| `internal/forge/` | Forge interface: GitHub and Gitea implementations |
|
|
| `internal/forge/webhook/` | Optional forge webhook receiver: GitHub issue events → `workintake.TaskEnvelope`, same publish path as polling |
|
|
| `internal/webhookguard/` | Cross-cutting inbound-webhook mechanics: HMAC verification, per-source rate limiting |
|
|
| `internal/worktree/` | Git operations: clone, branch, commit, push, diff, cleanup |
|
|
| `internal/store/` | Task/capture/mapping/binding SQLite implementation; producer-owned contract interfaces live in `internal/domain/storecontract` (aliases kept here) |
|
|
| `internal/domain/storecontract/` | Producer-owned State Store read contracts consumed by webui, intake, and the gRPC adapters (state-store-contract rev. 2d) |
|
|
| `internal/events/` | In-process event bus: publish/subscribe for observability |
|
|
| `internal/infrastructure/` | Config loading, eventbus transport, model catalog |
|
|
| `internal/webui/` | Shared dashboard HTTP layer served by the archie-ui process |
|
|
| `internal/gateway/` (18.7k LOC) | Persistent-connection layer between archie and its users (Telegram, web UI, etc.); shared CommandRouter for dispatch |
|
|
| `internal/tools/` (20.9k LOC) | Central tool subsystem: built-in tool implementations, approval, execution contract |
|
|
| `internal/domain/memory/` | Memory engine contract: four typed scopes, CRUD + revisions, content scanner |
|
|
| `internal/infrastructure/memory/` | Builtin memory engine + its `builtin/` markdown store |
|
|
| `internal/secret/` | Secret reference resolution across named engines (env, vault, etc.) |
|
|
| `internal/plugin/` | Core plugin interface: Yaegi-interpreted `.go` plugins loaded from `~/.config/archie/plugins/` and registered with the daemon's extension registry |
|
|
| `internal/skill/` | Parses and discovers agentskills.io `SKILL.md` files |
|
|
| `ai-sdk/runtime` | External: provider-agnostic LLM runtime |
|
|
| `ai-sdk/agentloop` | External: gated agent loop with budgets and tool jails |
|
|
| `ai-sdk/core` | External: tool definitions, generate options |
|
|
|
|
## Task Lifecycle
|
|
|
|
```
|
|
queued → running(workflow:stage) → pr_open → merged | rejected
|
|
↓
|
|
waiting_human → (human approves) → queued(implement)
|
|
↓
|
|
parked
|
|
```
|
|
|
|
**Crash recovery:** tasks left in `running` are re-queued on startup. Parks are
|
|
never silent, but they no longer comment on the forge issue: the reason is
|
|
recorded on the task as `park_reason` (cleared on requeue) and surfaced by the
|
|
dashboard and `/api/tasks`. Retries are an explicit operator action capped by
|
|
`max_retries`, not a label a human removes.
|
|
|
|
**Adversarial review:** the implement workflow runs a fresh adversarial review
|
|
after the deterministic gates and before `pr_open` (see
|
|
`docs/architecture/adversarial-review.md`). A surviving blocking finding — or a
|
|
review that failed to run — parks the task with the findings as its
|
|
`park_reason`; otherwise the PR opens with a findings section on its body.
|
|
Opt-in per repo via `repo.review_enabled`.
|
|
|
|
**PR reconciliation:** the daemon polls open PRs, checks GitHub state
|
|
(`merged`/`closed`), transitions the task, and cleans up worktrees.
|
|
|
|
**Provenance by origin:** a task's origin determines which enqueue path
|
|
created it, though every origin converges on the same `tasks` table and the
|
|
same `Route`/`Run` lifecycle above once queued. Forge-sourced tasks — whether
|
|
discovered by polling or, single-identity only, delivered by the forge
|
|
webhook receiver (`internal/forge/webhook`) — enqueue via the same
|
|
`workintake.TaskEnvelope` and `PublishTask` path (see `docs/prds/event-sources-
|
|
and-reactions.md`'s decided contract); `TaskEnvelope.IdempotencyKey` is keyed
|
|
on `owner/repo/number`, not delivery source, so a webhook-delivered issue and
|
|
a later poll of the same issue dedup for free instead of double-enqueuing.
|
|
Playbook-binding-dispatched tasks enqueue
|
|
via `EnqueueChatTask`/`EnqueueBindingTask` (`internal/store`), the same direct
|
|
path chat-spawned tasks use, stamped with `binding_id`/`binding_version` for
|
|
provenance. See `docs/architecture/bindings.md` for the binding model and its
|
|
threat model in full.
|
|
|
|
## Workflow Engine
|
|
|
|
### Core types (`workflow.go`)
|
|
|
|
- `Workflow` = named list of `Stage`s
|
|
- `Stage` = `Name` + `Run(ctx, *TaskContext) error`
|
|
- `TaskContext` = mutable bag: Task, Repo, Config, Forge, Store, Agent runner,
|
|
worktree dir/branch, scratch fields
|
|
- `Outcome` = terminal decision (status + detail) -- ends the workflow
|
|
immediately
|
|
- `Registry` = `map[string]Workflow`
|
|
|
|
### Routing (`Route`)
|
|
|
|
Label-driven, no LLM involved. Pre-assigned workflow wins; then labels decide.
|
|
The built-in bindings are:
|
|
|
|
- `bug` → `tdd`
|
|
- `feature` → `feasibility`
|
|
- `bootstrap` → `bootstrap` (diagnostics, no LLM spend)
|
|
- Default → `implement`
|
|
|
|
Both the closed `bug`/`feature`/`bootstrap` set's target workflow and
|
|
arbitrary additional labels are YAML-overridable at daemon startup
|
|
(`internal/domain/workflow/routing.go`'s `LoadKindWorkflowsYAML`/
|
|
`LoadLabelWorkflowsYAML`, `WorkflowRoutingFile`/`WorkflowLabelsFile`/
|
|
`PlaybookDirs` config) -- see `docs/prds/eda-playbook-engine.md`. A label
|
|
already owned by the closed kind set, or a binding declared twice across
|
|
sources, is a reported load failure, not a silent override.
|
|
|
|
### Execution (`Run`)
|
|
|
|
Stages execute sequentially. After each stage:
|
|
|
|
- Task is persisted to SQLite
|
|
- Error → park the task (comment on issue, keep worktree)
|
|
- Outcome set → finish (transition task, update labels)
|
|
- Neither → continue to next stage
|
|
|
|
A workflow that ends without an outcome parks -- definition bugs must not vanish
|
|
silently.
|
|
|
|
## Workflows
|
|
|
|
### Bootstrap (diagnostics, no LLM)
|
|
|
|
```
|
|
prepare → apply(marker file) → commit-push → diff-cap → open-pr
|
|
```
|
|
|
|
Proves the plumbing: clone, push, PR. Label any test issue `bootstrap` to verify
|
|
end-to-end.
|
|
|
|
### Implement (default)
|
|
|
|
```
|
|
prepare → baseline-gate → plan(planner, read-only) → build(builder, gated) → commit-push → diff-cap → open-pr
|
|
```
|
|
|
|
- **baseline-gate:** runs the repo's gate at the base commit before anything is
|
|
touched
|
|
- **plan:** read-only agent explores codebase, produces implementation plan,
|
|
posts it as a comment
|
|
- **build:** full toolset agent implements against the plan behind the repo's
|
|
quality gate
|
|
- **diff-cap:** parks oversized changes (>400 lines default)
|
|
- **open-pr:** builder's summary becomes the PR body
|
|
|
|
### TDD (bug label)
|
|
|
|
```
|
|
prepare → baseline-gate → analyse(planner) → repro-tests(builder, inverted gate) → capture-proof → commit-repro → fix(builder, normal gate, test files protected) → commit-push → diff-cap → open-pr + repro-evidence
|
|
```
|
|
|
|
- **repro-tests:** the quality gate is **inverted** -- the test command must
|
|
FAIL. Proven failure is required.
|
|
- **capture-proof:** runs the test command deterministically, captures the
|
|
failing output
|
|
- **commit-repro:** commits the failing tests as the first commit
|
|
- **fix:** test files are **environmentally write-protected** (not
|
|
prompt-ruled). The agent fixes code, not tests.
|
|
- **open-pr + evidence:** posts both the PR and the captured failure proof
|
|
|
|
### Feasibility (feature label)
|
|
|
|
```
|
|
prepare → assess(planner, with decide tool) → [close_if_bad_fit | prd(planner)] → deliver → waiting_human
|
|
```
|
|
|
|
- **assess:** reads AGENT.md, ROADMAP.md, README. Calls a `decide` tool
|
|
(structured output, not parsed prose). Bad fit → close with reasons.
|
|
- **prd:** read-only agent writes a PRD: problem, solution, files affected,
|
|
acceptance criteria, non-goals, diff estimate
|
|
- **deliver:** posts PRD as issue comment + webhook notification (n8n → email).
|
|
Sets state to `waiting_human`.
|
|
- The daemon watches for human replies, judges them with a triage LLM
|
|
(APPROVE/REJECT/UNCLEAR), requeues or closes.
|
|
|
|
## Forge Interface
|
|
|
|
A thin abstraction over the forge. GitHub (`github.go`) and Gitea (`gitea.go`)
|
|
both implement it, plus a no-op (`noop.go`) used when no credential resolves —
|
|
see the degradation rule in `docs/architecture/configuration.md`. A multi-forge
|
|
deployment is configured per identity; see
|
|
`deployments/multi-forge-github-gitea.toml`.
|
|
|
|
| Method | Purpose |
|
|
| ------------------- | --------------------------------------- |
|
|
| `AcceptInvitations` | Auto-accept repo invites |
|
|
| `AssignedIssues` | Poll assigned issues (excluding PRs) |
|
|
| `IssuesWithLabel` | Poll labelled issues |
|
|
| `Comment` | Post issue/PR comment, return ID |
|
|
| `RepliesAfter` | Find human replies after a comment ID |
|
|
| `CreatePR` | Open pull request |
|
|
| `PRState` | Check merged/open/closed |
|
|
| `CloseIssue` | Close with final comment |
|
|
| `React` | Emoji reaction (pickup acknowledgement) |
|
|
| `SetStateLabel` | Replace old state label with new one |
|
|
| `VerifyPush` | Confirm push permission at startup |
|
|
|
|
State labels (`archie:queued`, `archie:working`, etc.) are created on demand,
|
|
removed when transitioning. They report state; they do not drive it. Removing
|
|
a label no longer retries a parked task -- retries are an explicit operator
|
|
action from the dashboard or chat, capped by `max_retries`.
|
|
|
|
### Webhook intake (alternative to polling)
|
|
|
|
`internal/forge/webhook` is a separate HTTP receiver, not a `Forge` method: it
|
|
verifies a GitHub webhook's HMAC signature (`internal/webhookguard.VerifyHMAC`),
|
|
decodes an `issues` event, applies the same dispatch predicate the poller
|
|
uses, and calls the same `PublishTask` the poller calls. It is opt-in via
|
|
`Forge.Intake` (`poll` default, `webhook`, `both`) and single-identity only --
|
|
a deployment with `[[identities]]` configured keeps polling per identity
|
|
instead. See `docs/prds/event-sources-and-reactions.md` for why this stayed a
|
|
thin decode-and-reuse layer rather than a second intake mechanism.
|
|
|
|
## Worktree Manager
|
|
|
|
Every task gets a fresh clone -- no persistent state between runs. The model
|
|
never runs git.
|
|
|
|
```
|
|
~/.local/share/archie/work/<owner>-<repo>/issue-<N>/
|
|
```
|
|
|
|
Token auth via a generated `GIT_ASKPASS` helper script -- the token never
|
|
appears in `.git/config` or process argv.
|
|
|
|
## Config
|
|
|
|
Daemon-level TOML (`~/.config/archie/config.toml`):
|
|
|
|
- `[forge]` -- type (github/gitea), host, token secret reference; `intake`
|
|
(`poll` default, `webhook`, or `both`) with `webhook_secret`/`webhook_addr`
|
|
when reacting to forge events instead of, or alongside, polling
|
|
(single-identity deployments only)
|
|
- `[dispatch]` -- trigger (assignee/label/either), labels, ack reaction
|
|
- `[[repos]]` -- owner, name, base branch, gate commands, protected paths,
|
|
ecosystem
|
|
- `[models]` -- planner, builder, triage (provider/model refs)
|
|
- `[providers]` -- LLM provider configs
|
|
- `[nats]` -- embedded or external broker deployment
|
|
- `[containers]` -- managed `archie-agent` image, limits, storage, and network
|
|
- `[budgets]` -- max steps, max tokens, wall clock, gate max failures
|
|
- `[web]` -- dashboard listen address, bound by the standalone archie-ui
|
|
process (the daemon runs no dashboard listener after the UI cutover)
|
|
- `[notify]` -- webhook URL for notifications
|
|
|
|
Secrets (forge token, provider API keys, channel tokens) are not embedded in
|
|
config files. `internal/secret` defines a pluggable `Engine` interface (`Name`,
|
|
`Version`, `Resolve(key) (string, error)`) resolved through a `Registry`; the
|
|
built-in `env` engine reads an environment variable by name and the built-in
|
|
`bws` engine caches the accessible Bitwarden project at startup. Custom engines
|
|
(sops, Vault/OpenBao) are Yaegi-interpreted `.go` plugins loaded from a
|
|
directory, following the same convention as `internal/plugin`'s daemon plugins.
|
|
Config fields reference a secret as
|
|
`{engine, key}` (`secret.SecretRef`), e.g.
|
|
`token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }`. As of this writing
|
|
`Forge.Token` and `Provider.APIKey` use `SecretRef`; resolved provider values
|
|
are exported under private, identity-scoped environment names because the SDK
|
|
and container boundary consume credential names rather than
|
|
plaintext wire fields. The older `Provider.APIKeyEnv`, `NATSConfig.TokenEnv`, and
|
|
`TelegramConfig.TokenEnv` field names remain supported.
|
|
|
|
Per-repo gates are command lists: `[[repos.gate]] = ["go", "vet", "./..."]`. The
|
|
last command is the test runner (by convention -- TDD inverts it).
|
|
|
|
## Observability
|
|
|
|
Every lifecycle event flows through an internal event bus:
|
|
|
|
- SQLite event log (every event stamped with a row ID)
|
|
- Live dashboard via SSE (server-sent events)
|
|
- Bounded subscriber buffers -- slow consumers drop events, never block the
|
|
daemon
|
|
|
|
## Plugin engine rule (strict)
|
|
|
|
“Engine” is reserved for a typed, lifecycle-managed capability family. It is not
|
|
a synonym for a generic plugin hook. Every new plugin engine must satisfy all of
|
|
these invariants:
|
|
|
|
1. **Typed domain contract.** The engine interface exposes real
|
|
capability-specific operations in addition to identity metadata. Examples are
|
|
resolving a secret, delivering a message, or running an agent. A plugin that
|
|
only exposes `Name` and `Version` is metadata, not an engine.
|
|
2. **Owning family manager.** The capability package owns a `Registry` or
|
|
`Manager` that controls provider registration and discovery, initialization,
|
|
or access. Providers do not register arbitrary callbacks directly on the
|
|
daemon.
|
|
3. **Lifecycle and health.** When an implementation owns resources or background
|
|
work, its typed family contract must expose start, health, and stop
|
|
semantics. The owning manager invokes them and defines failure isolation and
|
|
shutdown ordering. Stateless providers may make these operations explicit
|
|
no-ops.
|
|
4. **Narrow host access.** Plugins receive the typed family registrar and only
|
|
the host services their declared capability requires. They never receive
|
|
`*daemon.Daemon`, a service locator, or an untyped hook map.
|
|
5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to
|
|
`Name()` and `Version()`. Domain hooks belong on typed engine interfaces;
|
|
adding capability methods to the generic interface is forbidden.
|
|
6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed
|
|
plugins—including third-party secret-engine plugins the operator chooses to
|
|
trust—may run in-process and have daemon privileges. Repository-supplied code
|
|
runs in the task container. Integrations that are not trusted as daemon code
|
|
run out of process through MCP or a versioned protocol and, when a
|
|
confidentiality or integrity boundary is required, inside a real container
|
|
sandbox. A subprocess boundary alone is not a security sandbox, and calling
|
|
Yaegi-loaded code a plugin does not isolate it.
|
|
|
|
`internal/plugin/architecture_test.go` enforces the mechanically testable parts
|
|
of this rule: the generic plugin method set, the shared agent-instruction
|
|
source, and the requirement that engine interfaces have domain behavior plus an
|
|
owning registry or manager.
|
|
|
|
### Memory engine family
|
|
|
|
One engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,
|
|
`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).
|
|
A caller names exactly the scopes it may read or write; the engine applies no
|
|
access policy of its own, so isolation falls out mechanically because
|
|
`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See
|
|
`docs/prds/memory-engine-unification.md` for the decision this contract
|
|
implements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),
|
|
deleted in that PRD's slice 5.
|
|
|
|
`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family
|
|
contract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --
|
|
CRUD with revisions retained, not just create/read/delete. `Update` supersedes
|
|
rather than overwrites: the superseded state is appended to the scope's
|
|
`HISTORY.md` before the live block is replaced, and `Update` carries no
|
|
`Scope` field, so a record can never change scope. The family's content
|
|
scanner (prompt-injection / sensitive-data patterns) is applied inside
|
|
`Create` and `Update`, the single choke point every producer crosses.
|
|
|
|
`internal/domain/memory.Registry` is the owning family registry: registration,
|
|
start/health/stop, shutdown ordering, and failure isolation, following the
|
|
plugin engine rule (`ARCHITECTURE.md#plugin-engine-rule-strict`).
|
|
`internal/infrastructure/memory.NewBuiltinEngine` is the only registered
|
|
engine today; it persists through `internal/infrastructure/memory/builtin`,
|
|
a markdown store (`MEMORY.md`-shaped per-scope files) that owns its on-disk
|
|
format end-to-end.
|
|
|
|
Two per-turn seams in `internal/gateway` connect a chat turn to the engine,
|
|
each narrowed to exactly the operations it needs:
|
|
|
|
- **Read** (`turn_memory.go`, `MemoryStore`): `prepareTurn` runs a
|
|
scope-only `Query` over the resolved `Subject`'s readable scopes,
|
|
synchronously and before the prompt is built. It never returns an error --
|
|
a panicking or failing engine degrades to an empty `<memory>` block rather
|
|
than failing the turn -- and is bounded by a per-scope record limit and a
|
|
byte cap on the rendered block.
|
|
- **Write** (`turn_memory_tool.go`, `MemoryWriteStore`): four tools --
|
|
`memory_create`, `memory_update`, `memory_delete`, `memory_list` -- built
|
|
per turn onto the resolved `Subject`'s writable scopes, not registered once
|
|
at boot. The model chooses the scope kind; it never chooses the agent or
|
|
user id, which come from the turn's resolved `Subject` and have no schema
|
|
field to override. `ScopeGlobal` is never model-writable.
|
|
|
|
`boot.setupMemoryEngine` (`internal/app/archied/bootstrap.go`) registers and
|
|
starts the engine and must run before `setupGatewayChat`, which constructs the
|
|
only chat turn runner in production and captures the engine at construction
|
|
time (`internal/app/archied/composition_order_test.go` pins the ordering), and
|
|
before `setupCurators`, whose `Registrar` captures the engine registry. The session curator (`internal/infrastructure/sessioncurator`)
|
|
writes derived records onto `ScopeAgentUser`, making it the engine's other
|
|
live producer besides the chat write path.
|
|
|
|
## Key Design Decisions
|
|
|
|
1. **Environmental constraints over prompt rules.** The gate, test-file
|
|
protection, and diff cap are code enforcement -- not "please don't do that"
|
|
in the system prompt.
|
|
2. **The model never runs git.** Worktree operations are deterministic steps,
|
|
not agent tools.
|
|
3. **Tokens as cost, not features.** Token usage is tracked per task and emitted
|
|
in observability events but never budgeted beyond the agent loop's own
|
|
limits.
|
|
4. **Label-driven routing.** Workflow selection is a switch statement, not an
|
|
LLM call. A triage LLM is used only for the human reply judgment in
|
|
waiting_human.
|
|
5. **Shared code.** `ai-sdk/agentloop` and `ai-sdk/toolkit` provide the common
|
|
agent loop and tool set.
|
|
6. **No daemon-internal cron.** Polling is a ticker loop, not cron. The
|
|
feasibility PRD notification uses an external webhook (n8n).
|
|
7. **Fresh worktree per task.** No persistent state between runs. Crash recovery
|
|
just re-queues.
|
|
8. **Agent execution is a data boundary.** Autonomous stages receive a versioned
|
|
request and return a fenced result; SQLite, forge operations, git, workflow
|
|
sequencing, and outcome handling stay daemon-owned.
|
|
|
|
## What's Implemented vs Planned
|
|
|
|
**Implemented:**
|
|
|
|
- Daemon poll loop, enqueue, claim, process
|
|
- Forge webhook intake as a feature-flagged alternative/backstop pairing to
|
|
polling (single-identity deployments; see `internal/forge/webhook`)
|
|
- Bootstrap, implement, TDD, feasibility workflows
|
|
- GitHub and Gitea forges (issues, PRs, labels, comments, reactions)
|
|
- Worktree isolation (clone, branch, commit, push, diff, cleanup)
|
|
- SQLite store with transition audit
|
|
- Config with ecosystem support (go, python, node, rust)
|
|
- Agent stages with gates, budgets, preflight, protected paths
|
|
- Observability (event bus, SQLite log, SSE dashboard)
|
|
- Crash recovery (re-queue stale running tasks)
|
|
- Human reply judgment (triage LLM for waiting_human)
|
|
|
|
**Planned:**
|
|
|
|
- Multi-identity webhook intake (currently single-identity only)
|
|
- More ecosystems
|
|
- Notification integrations beyond n8n webhook
|
|
- Skills (SKILL.md support -- see `.archie/skills/`)
|