Compare commits

...
160 Commits
Author SHA1 Message Date
sam 0fe3caa175 chore(release): v1.46.0
deploy / gate (push) Failing after 6m5s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-02 13:03:00 +10:00
sam 83d57ec6a2 fix(daemon): drop the import and assignment left by the composition cleanup
l45's refactor removed the assigned-but-unread daemon handles and l44 had
already moved the guardrail wiring out of the daemon, so the rebase union
left internal/daemon/daemon.go importing internal/tools with no use and
internal/app/archied/bootstrap.go assigning a Guardrails field that no
longer exists. main did not build.

Caught by building the merged tree rather than trusting the merge; the
merge train merged on a failed gate instead of chaining on it, which is
the mistake this commit repairs.
2026-10-02 13:00:56 +10:00
sam e762f15844 docs(agent-system): failure classification lives on the persisted record
The hazards list still claimed failure classification and retryability are
not represented explicitly. The persisted execution record has carried the
park class the parking code records since the typed-park work landed, so
the hazard now points at that record and the taskstate vocabulary instead
of restating a field list.

Regenerated the committed development-docs artifact for the edited page.
2026-10-02 12:57:53 +10:00
sam 1539fdc560 fix(daemon): classify workflow-pin parks by cause, not a blanket transient
pinTaskProfile parked every pinWorkflowDefinition failure as
taskstate.ParkTransient. That class documents that a requeue can succeed,
but the dominant pin failures are durable: a stored definition whose YAML
does not hash to the digest beside it, a definition that does not parse,
and a workflow or playbook binding resolving to an undefined workflow all
recur on every requeue until an operator repairs the row or the
configuration. A future retry pass reading transient as its input would
loop on them forever.

pinFailure now carries the class its cause needs, decided where the cause
is known, and pinParkClass reads it at the park site. A durable pin defect
parks operator-actionable; only a State Store read or persist failure --
the genuinely environmental case -- stays transient. The safe default for
an unclassified cause is ParkNeedsHuman, never a requeue that will fix it.

Red-first: TestDurablePinDefectIsNotParkedTransient failed at its
assertion before the fix (parked "transient"); TestTransientPinFailureStaysTransient
keeps the environmental case transient so the rule is per-cause, not a
blanket flip.
2026-10-02 12:57:53 +10:00
sam 0e37a0f536 refactor(daemon): drop assigned-but-unread composition handles
Three exported Daemon fields were wired by the composition root and read
nowhere: CapabilityHost (*plugin.Host), Curators (*curator.Registry) and
ToolRegistry (*tools.Registry). No field access exists anywhere in the
repo, and git history shows no read ever existed.

Each handle has a live owner outside the daemon: the curator
registry/runtime is boot-owned (the curator isolation invariant keeps it
off the agent loop), the capability host is lifecycle-owned by the
composition root and consumed by the control plane, and the tool registry
is consumed by chat, curator and MCP wiring. Keeping the daemon copies was
decorative wiring, so the fields, their composition assignments and the
now-unused plugin/curator imports go together.

The daemon architecture test now refuses the three names, and the plugin
host contract test refuses a CapabilityHost: handle on the daemon alongside
the PluginRegistry: one it already refused.
2026-10-02 12:57:53 +10:00
sam de32542c00 fix(agentworker): supply the guardrail engine to every task run
TaskContext.Guardrails was never assigned: the engine was built in
archied's composition root and held on Daemon.Guardrails, which no code
read after workflow execution moved to the full-task worker handoff.
archie-agent is a separate process, so a live engine cannot cross that
handoff. Build the engine at the agentworker composition root (the
process that runs agent stages), thread it through the task dependencies,
and set it on TaskContext; drop the now-dead archied-side construction.

Refs: archie-core-jd5v
2026-10-02 12:37:35 +10:00
sam c1673e43fb fix(config): carry max_retries into the worker TaskConfig snapshot
The remediate round cap runs inside archie-agent and reads
TaskContext.Cfg.MaxRetries, but TaskConfig did not carry the global
Config.MaxRetries: ForTask and ToConfig both dropped it, so a default
configuration reached the cap as 0 and a remediation never parked. Carry
the value (a repo-level override still wins via EffectiveMaxRetries) and
pin it with a red-first cap test traced through ForTask/ToConfig.

Refs: archie-core-ad3p
2026-10-02 12:37:35 +10:00
sam a9233755c3 fix(workflow): bind the remediate worktree before the builder runs
Commit 4e5b91d7 moved the remediate resume into daemon worktree
preparation and deleted StageResumeWorktree together with the Dir/Resume
pair it called, but nothing in the workflow replaced the binding it did:
TaskContext.Dir and Branch stayed empty for a whole run, so
remediate-build ran the builder with no workspace and
remediate-commit-push called CommitAll/Push with an empty dir and branch.

Extend the workflow-side Trees seam with the prepare target, mirroring
the daemon's mode-aware worktree.Manager.Prepare: PrepareFresh lands on
base, a non-empty target is the branch a resume continues. Remediate now
stages StagePrepareWorktreeOnBranch before any agent stage, binding the
same directory the daemon prepared and the task's PR branch, and failing
closed when the task has no branch rather than preparing base. The
container adapter returns the requested resume target verbatim.

Refs archie-core-h4tk
2026-10-02 12:29:57 +10:00
sam 7ca81dc85a feat(agentworker): answer MCP sampling from the task's model
A task hosts the same configured MCP servers as a chat turn, but the
worker's provider builder passed no sampling handler, so a task-scoped
server's sampling/createMessage request got a JSON-RPC method-not-found
while the identical request succeeded on the chat path. The worker runs
its own model runtime, so it can answer.

Thread a sampling handler built from the task's builder model into the
worker's MCP provider builder, beside the chat path's handler. Build the
task's model runtime once and share it with the stage runners instead of
creating a second client for sampling.

Move the sampling message mapping and max-token bound to agentexec, next
to the runtime both paths call models through, so a server gets the same
bound on either path. Carry the catalog's reasoning flag in
ModelLimits: a reasoning-class builder model must omit the max-token
bound its provider rejects, exactly as the chat path does.
2026-10-02 12:20:31 +10:00
sam 457da2e97d refactor(agent): drop the SOUL upgrade branch with no shipped template
ShippedSoul returned an empty SoulDocument.Legacy, so SoulSuperseded,
replaceSoul and SoulUpgraded had no production producer: the only body the
build ships is its current default, which classifies as SoulCurrent, and only
tests constructed a Legacy document. No earlier SOUL ever shipped (the file was
introduced with the starter in cc83c9ae), so the upgrade path has nothing to
consume.

Remove the speculative machinery and keep the behaviour that is real: seed the
starter when no file exists, recognise the shipped default as current, and
preserve every other body, including a template-shaped edit. A build that
supersedes the starter reintroduces the upgrade together with the old body it
consumes.
2026-10-02 11:59:54 +10:00
sam 656d21520f fix(webui): pin the dashboard validators to the control plane's
ui/src/settings/validation.ts hand-mirrors three control-plane validators with
no shared source, and the model-role rule had already diverged: the dashboard
required a stricter regex while the server only asks for a slash, so it refused
values the server accepts.

Add a shared fixture (internal/app/controlplane/testdata/dashboard-validators.json)
that both sides run through their real implementations: a Go test over the
server validators and ui/test/control-plane-validator-parity.test.ts over the
dashboard ones. Either side changing a rule alone now fails the other's test.

Fix the diverged rule to mirror the server's predicate exactly (non-blank role,
model containing a slash), so an empty or whitespace-padded model is judged the
same way the control plane judges it. Regenerate ui/dist and the dev-docs
artifact.
2026-10-02 11:59:17 +10:00
sam 92eabbed17 feat(telegram): carry clarify and picker through the text fallback
Telegram had no generic question or choice widget in the agent-turn path,
so the interactive contract could not be carried by the only channel that
ships. telegramInteractor implements ClarifyRequester and PickerRequester
on the shared TextFallback and reports both capabilities honestly: the
capability is about carrying the interaction, not the widget, and the cost
is a typed answer. A reply typed while a prompt is pending is consumed by
the blocked interaction rather than dispatched as a new turn; a command is
never consumed, so /stop still cancels the turn.

The carrier is set on the turn context in the Messaging process. It does
not cross the gRPC boundary into the Gateway process, so in the extracted
messaging deployment the gateway turn has no interactive adapter and
ask_user is not offered -- the same gap that already makes
WithApprovalRequester unreachable there. That transport is a product
decision recorded on the lane, not silently worked around; the in-process
path, the capability report and the tests land here.

Red-first: TestInteractivePickUsesTextFallback and
TestInteractiveClarifyReturnsTypedAnswer (plus the command guard) failed at
the assertion before the interactor was implemented.
2026-10-02 11:52:07 +10:00
sam 28acf2a8db feat(gateway): offer ask_user when the turn's channel can carry a question
prepareTurn now registers an ask_user tool only when the turn context
carries an interactive adapter (WithInteractive), so a contract with no
caller has a real one and a channel that cannot ask registers no tool
rather than one that always fails. A channel reporting Picker gets the
native single-choice request; one reporting only Clarify still carries a
choice, rendered as numbered text and matched from the typed reply through
the domain's FormatPickerText/ParsePickerReply rather than erroring.

Red-first: InteractiveTools returned nothing and
TestInteractiveToolsRegisteredWithCarrier / TestAskUserUsesPickerWhenChannelCanPick
/ TestAskUserFallsBackToTextWhenChannelCannotPick failed at the assertion
before the tool was implemented. TestTurnRegistersAskUserOnlyWithCarrier
proves reachability from a real TurnRunner turn.
2026-10-02 11:52:07 +10:00
sam c02852d87f feat(messaging): add a per-turn interactive carrier for clarify and picker
The contract could carry a question but nothing carried the ability to ask
one. Add Interactive, resolved from a channel adapter's own capability
report through InteractiveOf, with WithInteractive / InteractiveFromContext
as the per-turn carrier -- the same shape WithApprovalRequester already uses
for consent. The capability still wins over the method set, so a
mis-reporting adapter contributes nothing instead of being called.

Tests: TestInteractiveOfTrustsCapabilityReport and
TestInteractiveCarrierRoundTrip pin the resolution and the round trip.
2026-10-02 11:52:06 +10:00
sam ab86442156 feat(tools): reconcile MCP servers and tool settings live
Flip tool-settings to ApplyMode live (archie-core-zfb0.3): the daemon now
watches the kind, diffs the stored MCP server set against the running
providers -- connecting added servers, disconnecting removed ones and
reconnecting changed ones while an unchanged server keeps running -- and
rebuilds the web_fetch and minimax entries, whose config is captured at
construction. A changed server whose replacement fails to start is rolled
back to the one running, and the refusal is reported through apply status.

toolprovider.Registry grows running-state Add/Remove/Replace beside
Register, Start and Stop, isolating a provider's failure the way the plugin
host's Add/Replace do. The chat turn model resolves its tool-output policy
per turn instead of capturing it at construction, and the boot registration
reads the running holder so a stored update that lands during boot is not
lost.
2026-10-02 11:46:37 +10:00
sam bfb909a93a docs(prreview): the approval path keeps the task's workflow, it does not force implement
The PRD still described both approval surfaces requeueing under a hardcoded
implement workflow. The shipped path passes an empty workflow, which Requeue
reads as keep-the-task's, so the feasibility handoff has to name implement on
the task before the wait rather than relying on the handler.
2026-10-02 11:45:46 +10:00
sam 894fffc63b test(messaging): widen the config-read gate past explicit config.Config types
The gate that keeps a PRD-forbidden [models]/[providers] read out of the
Messaging Service only blamed identifiers whose parameter or var type spelled
config.Config. A value reached through an inferred declaration
("cfg := doc.Config") or held in a struct field therefore left the read
intact while the rule saw no holder -- the same class of miss that let voice
transcription ship behind a green link gate.

Widen the holder detection to track the config type through inferred short
variable declarations and vars, struct fields and receivers, type-preserving
expressions, and range variables over a slice or map of config, then assert
each previously-inert shape red first.
2026-10-02 11:44:51 +10:00
sam c94be59952 feat(container): apply container-runtime-policies live
The container runtime policies kind was restart-required because the pool
captured image, pull policy, network, max uptime and max concurrency at
construction and the dispatcher fixed its slot count at the start of a drain
pass. Both consumers now re-read the published config:

- the pool's settings come from a live source read per acquire, with the
  boot-resolved registry credential and Docker construction values preserved;
  a live default-image change is pulled rather than assumed present;
- the daemon owns one long-lived dispatcher that accepts a new limit: running
  tasks keep their slots, a raise admits queued work immediately, and a lower
  limit is applied as tasks finish;
- the control-plane descriptor is live, the kind joins runtimeResourceKinds,
  and the apply/reload paths resize the dispatcher after publishing. The
  ContainerConfig fields whose consumers now re-read are added to the reload
  allowlist; registry_auth stays restart-required.

Regenerate the docs artifacts. contracts.json also carries the voice
media-type description a prior commit left stale.
2026-10-02 11:39:46 +10:00
sam 04d0495f12 revert(tools): drop the checkpoint writer with no restore caller
The pre-mutation file checkpoint added in e10d862f wrote a full copy of
every write/edit target into .git/archie-checkpoints, but nothing could
restore it: CheckpointStore.RestoreLatest (and its latest/restore
helpers) had no production caller, no rollback surface reaches the
workspace, and the store was never pruned, so it grew without bound in
every workspace.

A writer whose only reader is unreachable is dead weight and an
unbounded disk cost, so the write half goes with the read half: write
and edit no longer snapshot, and CheckpointStore is deleted. The
regression test pins the decision by asserting a write and an edit
leave no .git/archie-checkpoints behind.
2026-10-02 11:36:10 +10:00
sam 9ccb6e2418 feat(messaging): restart only the channel whose settings changed
archie-core-zfb0.4. Channel settings were restart-required as a whole: a
change to one channel needed a process restart that restarted every channel.

The Messaging Service now reconciles the stored channel-settings resource on
the apply-status restamp interval (docs/prds/plugin-settings-live.md), re-layers
it over the file document exactly as boot does, and restarts only the channel
whose transport settings changed. Every other channel keeps serving.

A restart is stop-and-start, not an in-place reload: each channel gets its own
supervisor and a rebuild factory, so email and webhook -- which have no reload
seam -- are restarted too. Telegram's Start still calls dropPendingUpdates
before it long-polls, so the rule holds on the reconcile path as on /restart. A
replacement is built before the running channel is touched, so a configuration
this build cannot run leaves the running channel serving.

The composed set and the bound listen addresses are process bindings: enabling
or disabling a channel, or changing chat.webhook_addr / chat.email.listen_addr,
is refused and reported for a restart rather than applied. A channel rebuild
that fails is not recorded as applied, so it is retried on the next tick. The
applied version reaches apply status, and ChannelSettingsKind flips to live.

Files: internal/app/archiemessaging/{compose,reconcile,supervise,run}.go,
controlplane ApplyMode, archied runtime watch, configuration.md, the config
skill matrix and the regenerated dev-docs artifact.

Verified: go test ./internal/app/archiemessaging/... (race clean); go test
./cmd/archie-messaging/... ./internal/app/controlplane/... ./internal/app/archied/...
./internal/config/...; go vet and golangci-lint run on those packages (0 issues);
go fix ./... and golangci-lint fmt produced no diff; task docs:artifact:check.
2026-10-02 11:31:05 +10:00
sam cd878f3c4d fix(messaging): gate the boundary on config reads, not only package links
The deletion gate checked which packages the messaging binary links, so a
process that reads a decoded [models]/[providers] value passed while
building an LLM client in-process. Go imports are atomic, but a config
read leaves no import to measure.

- add the model-provider capability packages (transcription, embedding)
  to the banned-link table and classify links through a testable
  bannedLink rule.
- scan internal/app/archiemessaging's production sources for a read of a
  top-level config section the PRD forbids, so the projection that built
  the transcriber cannot come back.
- unit-test both rules, including a synthetic copy of the old wiring, so
  the live gate cannot rot into a no-op and still pass.

Red first: TestMessagingReadsNoBannedConfigSection failed on cfg.Models
and cfg.Providers before the capability moved, and the link gate failed on
internal/infrastructure/transcription.
2026-10-02 11:12:59 +10:00
sam b650a8c156 fix(messaging): transcribe voice notes on the model-owning side of the boundary
The Messaging Service built the voice-transcription client in-process
from [models].transcription and [providers.*], which the messaging
boundary PRD reserves to the process that owns the model runtime and its
provider credentials. The deletion gate only measured linked packages,
so the PRD violation shipped green: config reads are not imports.

Move the capability across the boundary:

- archiemessaging no longer reads [models] or [providers], builds no
  transcription client, and drops the ResolvedConfig.Transcriber field.
- telegram classifies a voice note as messaging.MediaTypeVoice and stops
  transcribing; it carries the attachment bytes and its note to the turn,
  which is all a frontend without the credential can do.
- archied builds the transcriber beside the chat runtime from its own
  model-role configuration (setupTranscriber) and gives it to every
  gateway TurnRunner.
- the turn runner transcribes a speech attachment before recording the
  inbound message, so stored history and the model context carry the
  transcript; a nil/failed/empty transcription keeps the frontend note.
- messaging.TranscribedMessageText renders the transcript into the text a
  frontend built from its media note, preserving the sender's caption.

Red first: TestTurnRunnerTranscribesSpeechOnTheModelOwningSide failed at
'Transcribe calls = 0, want 1' with the transcription call disabled.
2026-10-02 11:12:59 +10:00
sam 4241429620 feat(controlplane): add the writable review-settings resource
review.precision_gate and review.approve_before_post were file-only, so the
dashboard had no way to write them: no control-plane resource carried them.
Add the review-settings kind (docs/prds/review-settings-resource.md), seed it
from the file's [review] section, layer it field-by-field into cfg.Review,
watch it live, and publish it through ConfigView.Review. The dashboard gets a
Review settings page bound to the kind through PAGE_RESOURCES, showing each
dial beside the value in force.
2026-10-02 11:08:44 +10:00
sam cc83c9aea2 feat(agent): seed a starter SOUL and upgrade only untouched templates 2026-10-02 11:06:40 +10:00
sam 1f0cb9f318 docs(prds): name the registered step type and hold the vocabulary PRD to the provider set
docs/prds/workflow-step-vocabulary.md named the repository-rules step type
`workflow.diff-rules` while the vocabulary a deployment resolves carries
`gate.diff-rules` (workflow.DiffRulesStepName), so a definition written to
the document's word is refused at save and at run. The same decision's
sibling, docs/prds/runtime-control-plane.md, still claimed "Plugins can add
step types", which this document's closed-set rule contradicts: an
interpreted plugin contributes none, and a step type arrives as a provider
in the compiled-in set.

Correct both documents, and hold the vocabulary PRD to the provider set with
a guard test: every step-type-shaped name the document identifies must
resolve in workflowsteps.Providers(). The test fails on the pre-fix document
("workflow.diff-rules" is contributed by no provider) and passes after.

Refs: archie-core-vwqc, split from archie-core-gcoj (closed as invalidated by
re-verification: the provider set exists and cross-side agreement is already
pinned).
2026-10-02 11:05:08 +10:00
sam 19520a63e5 feat(webui): let the operator choose the retry worktree mode
A retry now carries the operator's worktree choice (refresh onto the base
branch or continue the work already pushed on the task branch) from the
dashboard through the task action to the daemon dispatch, and persists it
on the task row so it survives a reload. The daemon resolves the mode from
the task, never from the workflow; BeginRemediation records continue
explicitly so a remediation still resumes its pull request branch.
2026-10-02 10:53:21 +10:00
sam ef203ce30a fix(control-plane): unify validation for the domain-managed kinds
The control-plane catalog advertises identities, capture-events,
capture-mappings and capture-bindings as domain-managed: the domain API
validates their writes, not the generic resource store. Two of those
paths did not hold.

Identities: the file loader judged an identity name with its own
`name == ""` test, while the store derives the same string through
identity.New, whose rule rejects an empty-after-trim name. A
whitespace-only name passed the file and then failed State Store boot
(or was silently skipped by BootstrapIdentities). The loader now calls
identity.ValidDisplayName, the feature's own rule, and
BootstrapIdentities derives legacy names through
identity.FromLegacyName rather than dropping one it cannot build.

Capture mappings and bindings: mapping.Validate and binding.Validate
ran only in the archie-ui handlers, so any other client of the RPCs the
catalog names could store a mapping or binding the feature refuses.
The staterpc write handlers now apply the feature's rule before the
store, per runtime-control-plane.md ("the server validates the change,
then writes it"). The rule stays in the domain package; the handlers
only translate its refusal.

Capture-events has no file-side copy and no feature rule for a captured
event's content, so there is nothing to unify there.

Tests: identity_agreement_test.go ties the file loader's name rule to
the store constructor; domain_validation_test.go proves the mapping and
binding RPCs refuse an invalid value before it reaches the store.
2026-10-02 10:50:52 +10:00
sam ff3f80e4c1 fix(logging): file a task log record under its own event time
A remotely-shipped task log entry was re-emitted through the sink with
slog.Logger.LogAttrs, which stamps time.Now(): the entry's own event time
was discarded and replaced with the daemon's receipt time. Because a
container's records arrive in bursts, a multi-minute run collapsed onto a
few milliseconds of receipt timestamps and its timing became
unrecoverable -- which stage ran when, how long an iteration took, whether
a stage stalled.

Write now builds the record from entry.Time (falling back to receipt time
only for an entry that carries none) and dispatches it through the same
handler, preserving the sink's level gate. Receipt time stays available
separately in the record's received_at field, so event time and arrival
time cannot be confused. The agent-side producer already carried the
record's own time; a test now pins that half too.
2026-10-02 10:33:24 +10:00
sam 3da407e410 fix(archied): omit the max-token bound on reasoning-class models
The OpenAI chat-completions provider in the pinned ai-sdk serialises a
non-zero output-token bound as `max_tokens`, which reasoning-class models
reject with HTTP 400 ("Use 'max_completion_tokens' instead"). Send no bound
at all for a model the catalog marks reasoning; classic models keep their
bound. Covers the chat turn path and MCP sampling, the two call sites that
set one today.

The reasoning flag rides TurnPrepareContext from the catalog details the
gateway already resolves, so archie-core keeps one notion of "reasoning
model": messaging.ModelDetails.Reasoning. A max_completion_tokens path in
ai-sdk is still needed to ever bound these models; that is filed separately.
2026-10-02 10:25:39 +10:00
sam 4e5b91d791 fix(daemon): resume a retry whose worktree is gone
prepareWorkspace chose between Manager.Prepare (refresh onto base) and a
separate Manager.Resume, and Manager.Resume only opened an
already-prepared clone. A remediation whose local worktree the terminal
cleanup removed, an expired volume dropped, or a different host never had
could therefore never be resumed, and the retry path had no way to select
the mode that continues pushed work.

Unify the two matched methods into Prepare(..., Target): Fresh resets onto
origin/<base>, a non-empty Target resets onto origin/<that branch>, and
either target clones a missing worktree. The daemon's retry path selects
the target from the task row and passes the persisted branch, so a resume
lands on the branch the open PR lives on and fails closed when it is not
on the remote.

Delete the container-mode no-op resume (hybridTrees.Resume and the
resumableTrees capability) now that the daemon owns it. The remediate
workflow no longer stages a resume, and the retired remediate.resume step
word stays resolvable as an inert stage: a stored definition is validated
as a whole collection, so a removed word would fail every workflow to
decode, not just its own.
2026-10-02 10:24:52 +10:00
sam 12b59a046d fix(messaging): carry an inbound attachment's bytes to the gateway turn
A Telegram photo or document was dropped between the process that receives
it and the one that runs the turn. Telegram runs in archie-messaging, which
downloads the attachment; the turn runs in archie-gateway/archied, which
never holds the bot token. gatewayrpc stripped MediaAttachment.Data on the
inbound request, so by the time the Gateway's model seam ran, the
attachment had no bytes and no URL, and mediaParts dropped it -- the model
read only the "[photo]" placeholder.

- proto/gateway/v1: Media gains a `data` field, populated only on the
  inbound request. Stored-history and outbound-event directions keep it
  empty: a persisted record still strips the bytes, and a streamed media
  event still carries metadata only.
- gatewayrpc: the inbound conversion maps Data; the stored and outbound
  conversions deliberately do not.
- archied: the Gateway server raises its gRPC receive limit from the 4 MB
  default to the messaging contract's inbound attachment ceiling plus
  framing headroom, so a maximal (20 MB) attachment is accepted rather than
  failing the RPC.
- messaging: MaxInboundAttachmentBytes is the single ceiling the Telegram
  download gate and the Gateway receive limit both derive from.

Red first: a new TestInboundMediaBytesReachTheTurn asserted the bytes crossed
the wire and failed at that assertion before the mapping changed; it was then
consolidated into TestInboundMediaRoundTrip, which now pins metadata plus bytes.
2026-10-02 10:18:01 +10:00
sam af1b9855ab fix(messaging): report the daemon version this process was built from
The Telegram update-report relay verified every pending report against a
nil running-version map, so a successful update always ended with "I still
can't confirm which version is actually running" and read as a failure.

The 2026-09-19 extraction decision left RunningVersions nil because the
Messaging Service could obtain only another binary's stamp. 70ea9b2a
(archie-core-k94o) then gave every host binary, archie-messaging included,
a buildinfo.Version self-report stamped with the archied release tag, so
the process now has a truthful source for its own running version: report
daemon = buildinfo.Version and leave the agent Unverified, since every
archie-agent process is task-scoped and observed only through
daemon.AgentStatus. A relaying process that the update did not replace
still reports its old build, which Verify reads as drift.
2026-10-02 10:16:22 +10:00
sam 3e878464f9 fix(workflow): deliver the feasibility PRD to the forge issue
The deliver stage's notify() returned early when [notify].webhook was
unset, so a parked feasibility PRD left the process nowhere while both
its doc comments promised an issue comment that was never posted. A
default deployment sets no webhook: the PRD reached only the operator
who went looking.

notify now posts a one-way delivery notice on the task's forge issue
before the webhook, for a forge-backed task. The issue is the channel a
default deployment always has; the webhook remains an additional push.
Neither is a reply channel -- the decision surfaces stay chat and the
Web UI, so the notice carries the PRD and names where to decide rather
than inviting a reply, and no reply cursor is recorded (WatchCommentID
stays 0).

Both stale doc comments now describe what the code does.
2026-10-02 10:10:04 +10:00
sam 216be98652 feat(plugins): load plugin and secret-engine files without a restart
docs/prds/plugin-settings-live.md: a `plugin-settings` change now applies
live for plugin_dir, module_dir and secret_engine_dir, and a file dropped
into any of those directories loads on the reconciliation tick.

- PluginSettingsKind moves to ApplyMode "live" and joins
  runtimeResourceKinds, so a stored directory change re-layers immediately.
- A reconciler re-runs the directory loads and the layering on the
  apply-status restamp interval. Files are content-hashed, so only new and
  changed files load.
- plugin.Host grows Add and Replace for the running state (Register keeps
  its pre-Start rule), and plugin.LoadFile / secret.Registry.LoadFile are
  the single-file load paths the boot loader and the reconciler share.
- Yaegi cannot unload, so a removed file keeps running and the removal is
  reported through apply status against the live version until restart; a
  clean pass clears it.
- A plugin-settings document that changes skills_dir is refused before the
  layering, since skills_dir has no live consumer.
- applystatus.Reporter.AppliedVersion lets the reconciliation report an
  outcome without resetting the version to zero.
2026-10-02 10:01:35 +10:00
sam f77baecb00 feat(gateway): gate admin slash commands by sender policy
Add SlashAccessPolicy, a deny-by-default role policy (admin allowlist plus
per-user delegated commands), and enforce it in Router.route before any
local command dispatches. A refusal executes none of the handler, is
visible to the sender, logged, and recorded through an optional
SlashDenials sink.

No config field yet: the gatewayrpc wire drops Message.SenderID (only the
display Sender crosses), so a per-sender allowlist cannot match a Telegram
sender at the daemon Router until the layered auth mixin carries identity
(archie-core-263). Nil policy preserves today's behaviour.
2026-10-02 10:00:37 +10:00
sam 394c76b4cc feat(messaging): adapter-facing clarify, picker and approval contract
The optional-capability pattern had media and delete but no interactive
UX: a channel could ask a human to approve an action through
ApprovalRequester, but there was no domain contract for posing a
clarifying question or presenting a single-choice picker, and no
capability flag a caller could read before attempting one.

Add ClarifyRequester and PickerRequester to internal/domain/messaging
alongside ApprovalRequester, with Clarify/Picker/Approval flags on
AdapterCapabilities and ClarifierOf/PickerOf/ApproverOf lookups that
treat the capability as the contract rather than the method set, so a
mis-reporting adapter degrades instead of panicking.

TextFallback is the shared text degrade: a channel with no native
question or selection UI still carries the interaction (numbered
prompt, parsed reply) instead of failing or silently dropping it.
FormatClarifyText/FormatPickerText/ParsePickerReply hold the rendering
and matching logic once.

The approval half reuses the existing decision model: Telegram's
telegramApprover already renders a native prompt, so it now reports the
Approval capability and deliberately does not claim Clarify/Picker it
has no native UI for. Gateway re-exports the contract.

Red-first: internal/domain/messaging/interactive_test.go drives the
test double adapters (native, degrade, mis-reporting, over-claiming)
and the text rendering/parsing; telegram/approval_test.go pins the
honest capability report.
2026-10-02 09:57:44 +10:00
sam b6defc5f31 fix(workflow): park environment gate failures without dispatching a builder
The baseline stage treated every red gate as a pre-existing code defect and
dispatched a TDD repair agent. A failure the environment caused -- no Docker
daemon for the test harness, or a gate command that is not installed -- cannot
be fixed from the worktree, so the run spent a full agent budget and then
parked. A provider error during that repair run (observed: HTTP 402) replaced
the gate cause in the park reason entirely.

Classify at the producer: gateEnvironmentCause names a failure whose command
could not start (*exec.Error) or whose output names unavailable host
infrastructure (the Docker shapes from archie-core-71mq). That failure parks
with the cause and the gate output and starts no builder. A real code failure
still dispatches exactly one repair run, and every post-dispatch failure now
carries the gate output alongside the agent/provider error instead of masking
it.

Refs archie-core-rwy6.
2026-10-02 09:57:15 +10:00
sam 5e1623f82f feat(webui): the harness settings page and its setup terminal
A Settings > Runtime page lists every credential binding with the capture
state of its OAuth token set (expiry, scopes, time; never the tokens), and
offers the setup terminal for the Kit profiles the daemon advertises. The
terminal is xterm.js over the WebSocket the harness route upgrades, lazy
loaded so xterm stays out of the shell bundle. The page reports the
terminal as unavailable when the process cannot open one, rather than
offering a control that fails (archie-core-egkf.7).

Wire shapes and URL building live in ui/src/harness/harness.ts and are
covered by ui/test/harness.test.ts; ui/dist is regenerated.
2026-10-02 09:42:26 +10:00
sam 0544fa58fc feat(gateway): list the harness page in the dashboard page registry
internal/gateway/dashboard_tools.go mirrors the dashboard's route table so
the agent can navigate to every page. The new /settings/harness route needs
its entry or page_index would not offer it (archie-core-egkf.7).
2026-10-02 09:38:09 +10:00
sam 057a4a8614 feat(webui): the dashboard reads harness bindings and opens the setup terminal
The harness page lists each credential binding with its captured OAuth
state (expiry, scopes, capture time; never the tokens), and the setup
terminal route upgrades to a WebSocket and bridges it to a harness
session. The session is a narrow webui-owned HarnessTerminal seam: the
container, sandbox network and egress path belong to the daemon, so the
dashboard process cannot implement it and answers 503 until a transport
is wired (archie-core-egkf.7). Opening the terminal authorizes as the
update action on the secret, per the PRD.
2026-10-02 09:38:09 +10:00
sam 2a1ed36a26 feat(webui): a live-apply setting reads as applied, never as a restart
The per-process apply rows labelled every older applied version "Restart
pending", including a live-apply kind that needs no restart at all: the lag is
in reporting. The wording now follows the resource's apply mode. A live kind
reads "Applied" at the stored version and "Behind" on an older one, neutrally
rather than as a warning, while a restart-required kind keeps "Restart
pending".

The restart banner's condition is lifted out of the component into a plain
module so it can be tested: only a restart-required resource with a process on
an older version earns the banner, and a live-apply kind never does. The
per-process rows are wired onto the Plugins page, where a live kind's lag is
meant to show.
2026-10-02 09:37:44 +10:00
sam 605988e0a9 fix(egress): take a run's credential kind from its binding, not the Kit
The sandbox kit spec lets one credential@1 declare apiKey and oauth
together, meaning "whichever the host has bound": the published
docker/claude-code-kit does exactly that for anthropic, and codex for
openai. archie decided the kind from the Kit's declaration instead
(egress.IsOAuthManaged), so a dual-declared service always came out
OAuth-bound however the org had bound it:

  - kitrun.resolveCredentials granted an API-key binding's service the
    empty string, so the proxy had no key to inject and every request to
    a domain the Kit named carried an empty credential. The reference
    Claude Code Kit could not authenticate with an API key at all.
  - an API-key-only service whose binding named no secret resolved to ""
    through the zero SecretRef, presenting an empty credential rather than
    staying unbound.
  - the proxy fired an apiKey inject rule for an OAuth-bound service,
    putting "Bearer " on the wire, and intercepted the token endpoint of
    an API-key-bound one, whose only outcomes were a 502 on the missing
    token set, a capture the org never bound, or -- for a required
    dual-declared credential -- a refused launch when no token store was
    configured.
  - the container's SBX_CRED_*_MODE said "apikey" for an OAuth-bound
    dual-declared service, and kitrun demanded a captured OAuth token for
    an API-key-bound one whose Kit renders a credential file.

One root cause, fixed once: the org's binding decides the kind. It is
now a first-class fact (egress.CredentialKind: apikey or oauth, absent
meaning unbound), computed from the binding in resolveCredentials and
carried to every consumer of it -- the resolver grant, the container's
credential state (mode variable and credential file), and the proxy
session, whose rule sets are built from it so a rule can only fire for a
service the run carries as that same kind. A service the run does not
carry at all keeps both rule sets, so resolving it still refuses a
required credential and skips an optional one.

Declared and bound stay two independent facts, as the reported
declared-and-granted intersection requires: neither widens the other.
No secret value crosses into kit (Bound carries kinds only) and none is
logged or written to a task row.
2026-10-02 09:37:20 +10:00
sam 06e0a87a62 feat(messaging): transcribe Telegram voice notes
A Telegram voice note was stored as the placeholder "[voice message]" and
nothing turned its audio into text, so the agent could not read it. Add a
channel-neutral Transcriber capability to the messaging media layer
(internal/domain/messaging), an ai-sdk Whisper implementation behind it
(internal/infrastructure/transcription), and wire it for Telegram.

The capability is config-driven like the other model roles:
models.transcription names a provider/model, the matching [providers.*]
entry carries the credential (api_key_env or an api_key secret ref), and
a missing role, provider, class or credential degrades to today's
behaviour with a log -- never an error that fails the turn.

A transcribed note replaces its placeholder with "[voice transcription]"
followed by the transcript, preserving any caption, so stored history
shows the agent it is reading a machine transcript.
2026-10-02 09:36:48 +10:00
sam 1d2fcec69e feat(messaging): retract ephemeral replies after their TTL
An EphemeralReply is a status notice a channel delivers and then removes
once its TTL elapses, so a transient placeholder does not linger in the
chat history after it is superseded. The TTL lives on the reply, the
Delete capability joins AdapterCapabilities alongside Media, and
channels.EphemeralSender does the send-then-retract with an injected
clock. A sender that cannot delete still delivers the reply and logs the
missed retraction instead of failing the turn.

Telegram implements MessageDeleter through deleteMessage and honours the
mechanism for the "Archie reloaded." status notice; the pre-restart
"Reloading…" message remains the durable acknowledgement.
2026-10-02 09:36:16 +10:00
sam f5fbec6371 feat(container): send registry auth on image pull
ImagePull was called with empty options, so a private registry answered 401
on every pull regardless of containers.pull_policy. docker login did not help
either: it writes ~/.docker/config.json, which only the CLI reads.

Add containers.registry_auth, a SecretRef reusing the credential shape the
rest of the file uses, whose resolved value is a Docker registry.AuthConfig
JSON document. archied resolves it at boot and the pool base64url-encodes it
into the X-Registry-Auth header ImagePullOptions carries.

A missing or unresolvable credential degrades to the anonymous pull that
existed before the field (with a warning), so a deployment with no private
registry is unaffected; a half-named reference is refused by
configuration.Validate. The field is file-owned and json:"-", so the
container-runtime-policies layering has to preserve it explicitly, the way it
preserves Profiles.
2026-10-02 09:35:28 +10:00
sam a9f441042e style(mcp): apply go fix to the sampling transport 2026-10-02 09:35:21 +10:00
sam a8a04929af feat(mcp): answer server-initiated sampling from the chat model
MCP servers could not ask the client for a completion: the transports
routed only responses by id and dropped every server-initiated request,
so a server calling sampling/createMessage hung waiting for a reply.

Route server->client requests through the transport readers to a handler
on the client. The client answers sampling/createMessage from a
configured SamplingHandler and maps a missing handler, malformed params
and handler failure to JSON-RPC errors for that request alone -- never a
silent drop or a failed session. stdio and SSE implement the routing;
the stateless HTTP transport cannot receive the request at all and says
so in its doc.

The daemon wires the handler to its own chat runtime and active model
role, so a sample is answered by the model a chat turn uses, capped by
the request's maxTokens and the model's output ceiling, and recorded on
/status like every other model call. No model configured is a refused
request with a clear error.
2026-10-02 09:33:32 +10:00
sam 1e1f51af55 feat(archied): refresh the model catalog at runtime
modelcatalog.Load ran once at boot, so a provider whose credential became
resolvable later, or a model models.dev published since, needed a restart.
The daemon now re-reads the catalog on an interval and republishes everything
derived from it, without a restart.

- `refreshModelCatalog` re-reads through the same options boot used, layers
  the result with the process's own runtimeConfig, and publishes. A failed
  read keeps the catalog already running: the model list must not go blank
  because the catalog service had a bad minute.
- Boot now publishes the merged config into `config.Holder`. applyModelCatalog
  only ever wrote into the boot struct, so the catalog's model limits and
  discovered providers never reached the running config -- and therefore never
  reached `config.ForTask`, which is what a workflow stage resolves model
  limits from. The first live update was the first snapshot to carry them.
- The chat model manager's catalog is a contribution that is replaced, not
  merged. A model the catalog no longer publishes stops being offered and
  described instead of lingering from an earlier snapshot.
- The catalog snapshot and the refs it contributes live behind one lock: the
  refresh goroutine replaces them while the config paths read them.

The daemon owns the published configuration, so the loop is the daemon's; the
standalone Gateway reads the catalog once at boot, as it does for the other
live-applied settings it does not watch.

The interval is deliberately not an operator setting: the catalog is derived
state rather than a stored resource, and a knob with no second consumer would
be a setting that parses and does nothing.

A key exported into the shell after the process started stays invisible to
every refresh, and cannot be otherwise: the process environment is fixed at
exec. A credential a secret engine starts resolving is visible, because the
catalog's credential lookup is the secrets registry.

Refs archie-core-zfb0.6
2026-10-02 09:24:32 +10:00
sam 3c2b1f6654 fix(storepkg): validate every declared authority grant at the package descriptor
Descriptor.Validate duplicated only the forge-permission half of
Authority.Validate, so a descriptor could declare a blank credential
service, egress host, trigger or tool and be installed: the acceptance
record refused the same blank, leaving the descriptor the operator is
shown disagreeing with the record the package is bounded by. Delegate to
Authority.Validate, the one validation of a grant list, and cover it with
the blank cases the descriptor now has to refuse.
2026-10-02 09:20:49 +10:00
sam e10d862f6a feat(tools): checkpoint files before mutating write and edit
The built-in workspace write and edit tools replaced file content with
no recoverable pre-state. Each now snapshots its target immediately
before the write and refuses the mutation when the snapshot cannot be
taken, so a checkpoint is never silently skipped.

Checkpoints land in .git/archie-checkpoints inside the workspace, the
same per-task state directory that already holds the task brief and the
prepared sentinel: nothing under .git can be swept onto the task branch
by go-git's Add{All:true}. A checkpoint records either the file's bytes
or its absence, so creating a file restores by removing it;
RestoreLatest returns the most recent pre-state for a path.

Shell, Go-script, MCP and plugin tools are deliberately not covered:
the set of files they can touch is not enumerable from the call.
2026-10-02 09:18:47 +10:00
sam 721968eeff fix(workflow): derive a declared output's captures need for profile selection
A declared output is written through a capture tool, but the dispatch-time
harness check read only the workflow's needs.captures. A workflow that
declared outputs without also writing needs: {captures: true} could name a
Kit profile whose adapter serves no capture tools; a required output then
parked with "output %q is required" instead of the profile being refused.

WorkflowInterface.Needs now reports captures for a non-empty Outputs beside
the declared needs, and the profile check and Kit launcher read it. The
needs: block keeps its meaning for a workflow that captures without
declaring outputs.

- internal/domain/workflow/task: Needs() derives captures; DeclaredNeeds
  carries only the declared block.
- internal/daemon: pinTaskProfile and runKitTask read Needs().
- tests: parse-time derivation, and pinTaskProfile refusing an
  outputs-declaring workflow against a Kit adapter with no capture MCP.
2026-10-02 03:19:07 +10:00
sam 446d94681b feat(webui): block invalid settings and show a field's former value
The Settings save flow tracked dirty fields but did not consult validity:
each page validated in a local computed the save bar could not see, so an
invalid draft could be saved and the server refused it a round-trip later.
The rules now live once in ui/src/settings/validation.ts, the store derives
invalidFields from the same draft diff as dirtyKinds, and the save bar lists
the invalid fields and refuses Save. The route-leave guard still reads the
one dirty model, so the two can never disagree.

Every edited field also shows its former value inline ("was 1m0s") from the
same per-kind diff, via a new DraftHint component.

The per-kind diff is now a cached computed, so the hint, the save bar and
the guard share one computation per change instead of one per consumer.
2026-10-02 03:14:46 +10:00
sam 04dedde52c feat(daemon): resolve the producing identity's org before publishing work
The poller, the forge webhook intake and the review scan built envelopes
without an Org, so every task and reaction keyed on the default org no
matter which org its identity served. Resolve the org through the State
Store's PrincipalSource (the existing org RPC over the staterpc client)
on the single publish paths:

- PublishTask stamps the envelope's identity org before encoding, so the
  idempotency key is org/identity/owner/repo/number; a resolve failure
  stops the publish instead of keying under a guess.
- PublishReaction is the one reaction write path, stamping the root org
  when the webhook producer could not; the poll scan stamps its task's
  already-resolved org, so both deliveries of one review key the same.
- The webhook receiver's inline publish closure moves onto the daemon
  method, removing the second reaction write path.
2026-10-02 03:12:42 +10:00
sam a4abafe0ad docs(prds): decide the plugin live-reload open questions
Review of the plugin-settings reconcile PRD (F1-F8) returned REVISE: the doc
stated outcomes without making the decisions behind them. This revision makes
each one, so the PRD can carry the plugin live-reload work:

- ApplyMode is set to live and the gateway's version lag moves from the
  restart banner to the per-process applied-version rows.
- The skills_dir refusal gets a check site (a pre-layer comparison on the live
  path, not the value-agnostic validator), keeping #1143's validates-nothing
  intact.
- Records the four-directory coupling and why a whole-document refusal is
  acceptable.
- Justifies stop-then-start as a module's only check, and adds the refused
  dependent-replace outcome to the apply-status taxonomy.
- States that a reconcile tick re-runs layering and provider resolution, and
  what archie-gateway actually boots.
- Adds the Verification section.

Cited package paths re-checked against the tree; the control-plane
definitions now cite internal/app/controlplane/.
2026-10-02 03:10:18 +10:00
sam 6bf24d73db test(agentexec): make seeded git repos independent of host signing config
The temp-repo fixtures in agentexec, domain/workflow and agentworker seeded
a repository and committed without disabling gpg signing, so a host with
commit.gpgsign=true and an agent-only SSH signing key failed those tests at
the fixture's own git call ("Couldn't get agent socket?").

Each producer now writes commit.gpgsign=false into the temporary repository's
own config, which also covers commits made inside the seeded repo by a
subprocess (the fake harness). A regression test per package pins the
fixture's hermeticity under a hostile global git config.
2026-10-02 03:06:48 +10:00
sam 20b4595a95 style(postgres): apply the formatter to the rebased review-gate row mapping 2026-10-02 02:30:16 +10:00
sam 2341c6df36 style(taskactions): apply go fix to the gate response test
The modernizer promotes the embedded fakeStore's fields into the literal;
task fmt runs go fix, so the lane gate flags the pre-fix form.
2026-10-02 02:27:59 +10:00
sam eaabc254be feat(webui): the dashboard answers the review gate, including a re-review's instructions
The server offers re-review for a waiting task, and it refuses one
without instructions, so the control needs a dialog of its own rather
than the plain confirm: it collects the operator's focus and posts
api.taskAction(id, "rereview", {instructions}). taskAction now takes the
review-gate payload (instructions and the finding keys approve posts, an
absent selection meaning all), and the freeze-dried catalog gains
Re-review so the first render matches the served catalog. The rereview
event kinds join the live-update topic list.

ui/dist is regenerated and committed; task test:ui and the typecheck pass.
2026-10-02 02:27:59 +10:00
sam 68a17aed91 feat(taskactions): one approval path answers the review gate from every surface
Decision 1 of docs/prds/pr-review-operator-response.md: the dashboard's
POST /api/tasks/{id}/action is the authoritative surface, chat's /approve
is a shortcut that posts every offered finding, and both reach the same
Service.Apply so one operator intent cannot be recorded as two decisions.

The action body now carries instructions (required by rereview) and the
finding keys an approve posts. taskactions.Service answers an offer
through the guarded RespondReviewGate write: approve records the
selection on the offer, rereview records the instructions, increments the
round and clears the offer, and a rereview with no instructions, with no
offer, or at the cap is refused as a conflict with nothing written. Chat
reaches the same service: chatTaskControllerAdapter.ApproveChatTask
delegates to b.taskActions() instead of its own requeue, which is what
removed the handler's hardcoded implement handoff -- feasibility's deliver
stage now names implement on the task before it waits, the invariant the
handler needs.

The payload crosses every hop it must: the NATS action request, the
gateway.v1 gRPC contract (regenerated), the LocalChatAdapter, and the
webui handler, which answers 400 for a rereview without instructions and
409 for the cap. A rereview event kind names its actor the way the
approval and rejection trios do.

taskactions.Task gains review_gate and rereview_rounds, and the two
surfaces' tests assert they agree.
2026-10-02 02:27:59 +10:00
sam 4f01b1604d feat(prreview): the gate records the review it holds and posts the operator's answer
The gate now writes its offer to the task's review_gate document before it
waits -- the scored findings, the head SHA, the pull request's identity
and the resuming workflow -- because the engine cannot resume a run
partway, so a resumed pipeline recomputes its findings and only the
recorded document is the review the operator saw
(docs/prds/pr-review-operator-response.md, "The review the operator
answers").

The document lives with the task column it encodes (internal/domain/
workflow/task), the way EncodeInputs does, and carries each finding as
opaque JSON beside the key an operator's selection names. That is what
lets the dashboard render and answer a gate without linking the workflow
engine -- cmd/archie-ui/architecture_test.go measures the linked binary,
and an operator-domain service importing the finding's own type linked
prreview into archie-ui. prreview owns the key derivation and the
finding's encoding, and the MaxRereviewRounds constant lives in the task
vocabulary beside the action names it answers with.

Intake restores the document into the run: a re-review's instructions
ride one labelled block in runLens's and runReviewer's missions only, and
an approve's recorded review is posted by phase 9 filtered by the
operator's selection, with the recomputed findings kept out of the output.
The gate does not wait again on an answered approve.

taskstate gains the rereview action the vocabulary needs -- offered for
waiting_human beside approve and reject, routed to queued -- whose
surfaces follow in the response channel.
2026-10-02 02:27:59 +10:00
sam bea1c69210 feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
The operator-approval gate needs its conversation with the operator
persisted before it waits and its answer threaded back
(docs/prds/pr-review-operator-response.md, Decision 2). review_gate is a
text column beside review_payload, encoded by the package that owns the
type; rereview_rounds is a bigint counted only by the new guarded write.

RespondReviewGate is the one write beside RetryTask/BeginRemediation: a
transition-table guard, one from-status check, an optional round
increment, and a requeue in one transaction. The re-review cap is
enforced in the row under the guard's lock, and a refusal leaves the
task waiting and the row untouched, surfaced as ErrRereviewCapReached
(added to the wire error table and the conformance battery). The column
joins the column-listing ListTaskSummaries projection and UpdateTask, so
the dashboard reads the offer and the store round-trips the count.
2026-10-02 02:27:59 +10:00
sam 7f51f1c39e feat(prreview): the operator-approval gate is PRReview's own stage-list entry
prReviewDecisionStages loses the withOperatorApproval flag: the shared
list the implement workflow splices (archie-core-afbk.7) never carries
the gate, and the standalone pipeline inserts it itself, immediately
before its merge gate (docs/prds/pr-review-operator-response.md, "The
gate is not reachable from archie's own PRs"). A structural test pins
both directions so a future edit cannot re-share the gate.
2026-10-02 02:27:30 +10:00
sam 3c32b63066 feat(workflow): declared workflow outputs for wait:true callers
A workflow declares named, typed outputs beside its inputs
(task.WorkflowInterface.Outputs). A run writes each one once through a
capture tool named after the output, or from a deterministic Go stage via
TaskContext.WriteOutput; the finish write persists them on tasks.outputs
before the outcome transition. A wait:true caller receives its successful
callee's outputs through WorkflowCallStatus and publishes one as its own
through a call step's outputs assignment.

Build authority: docs/prds/workflow-call-outputs.md.

- save time: WorkflowInterface.Validate checks output names and types;
  checkCallOutputs checks a call's assignment against both declarations
  and refuses outputs over a wait:false call.
- run time: undeclared, mistyped and required-but-missing values park the
  run; published callee values are re-checked against the caller's type.
- storage/wire: tasks.outputs (goose 0024), reset by each claim so the set
  is attempt-scoped; an encoded set past the structured-payload bound is
  refused, not clipped. Task.outputs_json and
  WorkflowCallStatusResponse.outputs_json carry it; task.Caller keeps its
  two methods.
- examples: firewall-contain calls firewall-investigate and publishes its
  summary as its own output.
2026-10-02 02:09:03 +10:00
sam 829fc44cbc chore(release): v1.45.0
deploy / gate (push) Failing after 3m47s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-30 11:44:01 +10:00
sam 6b4049c9f5 Merge branch 'pi-subagents/ht-writer-Repo-work-apps-archie-core.-You-are-the-ONE-writer-for-ui-in-an-isolated-work-fa09caee-88c919c-8f2c-s0-t0' 2026-09-30 11:42:28 +10:00
sam 934ba16c72 Merge branch 'crew/pi-1154' 2026-09-30 11:41:51 +10:00
sam 9f1dc44673 feat(webui): events counts, YAML reading, log rows and dashboard filters
Four findings from the ui-redesign verification pass, each with the module that
owns the rule and the test that pins it.

- events: the three-step strip's and the tab chips' counts move out of the SFC
  into events/counts.ts -- one read per step, an unreadable count stays blank
  rather than reading as zero (events-counts.test.ts).
- workflows: workflows/workflow-yaml.ts reads the editor's YAML with a real
  parser (the yaml package, not a line scanner) to drive the read-only Steps
  preview and a live validity indicator; the editor gains a line-number gutter
  and light syntax colouring behind the textarea. Step types and their settings
  are not served to the dashboard, so those remain the server's to check on
  save, and a save it refuses still reports its own reason.
- tasks: an ERROR log row is a block rather than only red text (lib/log.ts), the
  log pane ends with "End of attempt N - M lines", and the task head offers
  Archive when the server's own action list offers it (task-actions.ts, and
  TaskRowActions' new `only` narrows the list without inventing a control).
- dashboard: the live activity feed gains the All/Tasks/System filter
  (activity-filter.ts) and every quality-gate row gains a pass bar
  (pass-bar.ts) that is red when the gate is failing.

ui/dist regenerated; ui/package.json carries yaml ^2.9.1.
2026-09-30 11:41:33 +10:00
sam 24258e215f docs(prds): plugin settings reconcile live without a restart
Direction for GH #1154 (epic #998): reconcile the plugin, module and
secret-engine directories into the running registries, load new and
changed files, and surface only the removals through apply status.
Draft pending maintainer approval - not settled design, so no diff.
2026-09-30 11:41:11 +10:00
sam 793eec6e51 Merge branch 'pi-subagents/webui-1152-142b744-4aae-s0-t0' 2026-09-30 11:39:42 +10:00
sam 6785750729 Merge branch 'pi-subagents/gate-1160-8a4f132-d61b-s0-t0' 2026-09-30 11:39:42 +10:00
sam 72fa043f47 docs(development): task check writes no module file on a consistent tree
The index page warned that task check adds linter-tool lines to go.sum
(bead 1e37) and told contributors to restore the file before committing.
Measured at HEAD 275d3370 on a copy of go.sum, with the originals restored
after every step, that is not what the gate does: go fix ./..., golangci-lint
fmt, go vet ./..., golangci-lint run ./... (root and tools), go build ./cmd/...,
go test -short ./..., the docsgen and docsite checks and
go -C tools test -mod=readonly ./... left go.mod, go.sum, tools/go.mod and
tools/go.sum byte-identical, with GOFLAGS unset and again with
GOFLAGS=-mod=mod. golangci-lint cannot write its own lines into go.sum either:
it is in no require or tool directive, go mod tidy -diff is empty, and the
committed go.sum carries none of its dependencies.

What the page should say is the rule the measurements show. A stale go.mod or
go.sum fails the gate (missing go.sum entry, updates to go.mod needed) instead
of being repaired, because every Go step runs under the toolchain's readonly
default and the tools steps pass -mod=readonly. Only a global
GOFLAGS=-mod=mod in go env re-enables the repair, which is why the flag is
spelled out on the go -C tools steps; when go.sum does go dirty, go mod tidy
and its own commit are the fix.

The regenerated docs/data/generated/dev-docs.json rides along, as the page
requires: docsite check failed on the edited page first (stale dev-docs.json)
and passes after task docs:artifact.
2026-09-30 11:38:57 +10:00
sam cc7397787b fix(webui): drop the config schema's editability advert
No process writes configuration through the dashboard: the write
handlers, their UpdateConfig/ResetConfig/UpdateRepoField seams and
ConfigView.Editable were deleted with the runtime config overlay
(295f8d69), and database-backed settings are written through the control
plane. That left producer-side residue behind:

- ConfigField.Editable and the descriptor literals setting it, which
  emitted editable=true for fields no process can change, and which
  ui/src/settings/types.ts's ConfigField deliberately omits from the
  reader side of the wire shape
- ErrConfigUpdateUnavailable/ErrConfigUpdateInvalid, with neither a
  producer nor a consumer since handleConfigUpdate was deleted
- comments pointing at handleConfigUpdate/UpdateConfig,
  ConfigView.Editable, the overlay's overridden markers and a deleted
  test name

The two Editable-only descriptor tests go with the field; the deleted
write path is what they pinned.
2026-09-30 11:38:44 +10:00
sam cef476aca3 docs(controlplane): record the plugin-settings dirs as deliberately free-form
Closes the decision #1143 asked for. plugin_dir, module_dir, secret_engine_dir
and skills_dir keep their no-op validator, and the comment at that validator
now says so on purpose, with the two rules considered and refused:

- "must exist": all four consumers read a missing directory as an empty one by
  design (plugin.LoadDir and secret.Registry.LoadDir return no entries and no
  error on os.IsNotExist, loadModules skips an absent kind file, playbook.Load
  returns an empty store, and internal/secret's TestLoadDirNonexistent pins the
  no-error half), so the rule would turn deliberate emptiness into a failed
  startup.
- "must be absolute" / "skills_dir under plugin_dir": no directory setting in
  the repository is validated for shape, so a rule for these four alone is
  arbitrary, and a boot-path validator over a stored document fails closed on
  values the store already holds.

Deliberately no code change to either layer: configuration.validateDatabaseOwned
still has no say over the four, and the resource validator stays the single
no-op function with one obvious home for a rule.

Refs #1143
2026-09-30 11:37:19 +10:00
sam f50444594f fix(config): expand plugin, module and skills dirs like every other operator path
applyGeneralDefaults home-expanded secret_engine_dir, work_dir, state_dir and
chat.workspace but not plugin_dir, module_dir or skills_dir, while
config.example.toml tells operators to write all four as
~/.local/share/archie/<dir>. A literal "~" is not a directory: plugin.LoadDir
returns an empty set for it, loadModules finds no kind file, and skill
discovery falls back to the built-ins, all without an error naming the
mistake. Expand the three in the same place as the rest, so a value the
example advertises resolves to the directory the operator meant.

Test first: TestLoadExpandsConfiguredHomePaths gains the three fields (and
pins HOME to a temp dir instead of the runner's real one); it failed on the
three new assertions before this change.

No validator is added alongside: see the plugin-settings decision record for
why these four directories stay free-form.

Refs #1143
2026-09-30 11:37:00 +10:00
sam 275d337032 refactor(archied): move the sd_notify client to internal/sdnotify
The sd_notify(3) client lived in internal/app/archied, so archie-messaging --
a process that must not import archied's composition -- could never announce
itself to systemd, and could therefore never be a Type=notify unit
(archie-core-g5g8).

The protocol client and the heartbeat sampler move to internal/sdnotify, a
cross-cutting leaf that imports nothing of ours. What stays in archied is
what is the daemon's own: which marker counts as progress (daemon.LastPollAt)
and how long the run loop may go between poll passes. The three entry points
that already announced keep announcing, unchanged.

The Messaging Service announces READY=1 at the point it declares itself
serving, the way the daemon, the Gateway and the State Store already do. No
unit is switched to Type=notify here: that is a separate decision, and
archie-messaging.service is still Type=simple.
2026-09-30 11:23:33 +10:00
sam b314470281 docs(fleet): a docs page change needs the dev-docs artifact regenerated
The skill already told a lane that a wire-type change needs `task docs:generate`;
this names the other trigger for the same generated artifact. Adding or editing a
page under docs/ gains or drops a page in docs/data/generated/dev-docs.json, and
skipping the regeneration fails docs:artifact:check on main rather than in the
lane that caused it.
2026-09-30 09:04:20 +10:00
sam eb3add5b89 chore(docs): regenerate the dev-docs artifact for the SOUL PRD page
fcc6a797 added docs/prds/soul.md but did not regenerate
docs/data/generated/dev-docs.json, which is generated from the docs tree and
gained a 95th page (/dev/prds/soul/). main therefore fails the gate's
docs:artifact:check. Regenerated with the command the check itself names.
2026-09-30 08:59:44 +10:00
sam c126d5a24a refactor(gateway): delete the dead RouteStream entry point 2026-09-30 08:57:32 +10:00
sam 1a3e79502d docs(fleet): carry peer-session, gate-order and codegraph facts in the fleet skill
The fleet skill is normative for archie facts and the fleet can read it, so
three facts earned this session move here from one operator's private memory:

- Peer sessions over intercom: name the reporting channel in the brief, because
  a compaction erases an agent's transport convention while keeping its task
  state, so a peer can revert to addressing its operator. Peer silence is not
  evidence of death; ask for an ack. Also: match task shape to window size, and
  checkpoint at ~70% rather than compacting mid-task.
- Gate the merge candidate before main moves, and have the lane brief demand
  scoped lint beside scoped tests.
- codegraph: read interface_dispatch and inferred tests alongside test_count,
  treat the index as a derived cache, stagger name-based queries, and report
  problems as one JSON object per line.
2026-09-30 08:50:54 +10:00
sam fcc6a7974e docs(prds): draft SOUL, the per-identity chat personality 2026-09-30 08:37:48 +10:00
sam f4ed542b00 refactor(gateway): extract the streamed-turn prelude and pump from stream 2026-09-30 08:34:30 +10:00
sam d06be5ca32 feat(gateway): coalesce rapid-fire text events into one turn 2026-09-30 08:26:27 +10:00
sam 8d48a08b13 merge: project installed package workflow contributions live, both ways (em7s.9) 2026-09-30 08:06:43 +10:00
sam f6ee43bf55 feat(store): project installed package contributions into org resources
An install that stayed in installed_packages left every contribution
unprojected: nothing made a package's workflow a usable org resource, and
nothing stopped it on removal. This lands projection for the workflow family,
the one kind whose org resource, validation and live read path all exist:

- storepkg.Service gains Projections (family -> projector): install resolves
  each projected family's contributed names against the fetched
  layer (FilesFromLayer), applies them, and on failure withdraws and removes
  the half installation; remove withdraws before the record goes, so a failed
  withdrawal keeps the package installed and usable.
- controlplane.WorkflowProjector merges the package's entries into the org's
  workflow-definitions document — the same document the daemon's
  WorkflowDefinitions client reads per dispatch, so a projected workflow is
  usable at the next dispatch and a withdrawn one stops dispatching, without
  restarts. A contributed id displacing an operator's own workflow is refused
  (storepkg.ErrContributionCollision), never silently replaced.
- installed_package_contributions (migration 0023) records the entries a
  package projected, so removal takes exactly its own contributions out.
- stateStoreDeps wires the projector set on the State Store's pool; the
  composition is pinned by the live round-trip test over a real gRPC
  connection.

Prompts, skills, MCP server definitions and default settings remain
unprojected: their contribution formats are not settled by docs/prds/store.md
and are left for their own slices rather than half-wired here.
2026-09-30 08:05:22 +10:00
sam 268f99051a merge: render the OAuth scopes and omit an uncaptured primary key (egkf.14) 2026-09-30 08:00:08 +10:00
sam 60a09e7def feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
{{.Scopes}} now substitutes the captured set as an ARRAY in the target
encoding, so a one-element set stays a one-element array rather than
collapsing to a bare string. An empty set REFUSES by name with an
actionable "re-run the setup terminal" message: the spec declares an
omission case for {{.PrimaryApiKey}} but none for {{.Scopes}}, and an empty
array would silently change the CLI's capability decisions.

{{.PrimaryApiKey}} now implements the spec's omit case: its enclosing key is
dropped from the structure, never emptied. archie resolves a service key
only to fill the egress grant and the container holds egress.Sentinel, so
there is never a key to render.

The renderer's input becomes OAuthFacts{Scopes, ExpiresAt} -- still the only
thing it receives about a stored token set, so a real access or refresh
token cannot reach the file and an unsourceable placeholder still refuses by
name (docs/prds/external-agent-harness.md, Verification).
2026-09-30 07:59:05 +10:00
sam bf1dc2e33e docs(prds): the step-type vocabulary PRD awaits the maintainer's approval 2026-09-30 07:56:52 +10:00
sam f34714ea07 merge: decide the workflow step-type vocabulary (m7oc, ze7y) 2026-09-30 07:56:10 +10:00
sam c2cfba1129 docs(prds): decide how step types are named, agreed, and refused 2026-09-30 07:55:34 +10:00
sam cea8bfee98 merge: state the resource idempotency key and the approval gate's scope (ut6b) 2026-09-30 07:55:25 +10:00
sam 2f8107d5ca style(gateway): adopt the formatter's output for the dedup tests 2026-09-30 07:55:25 +10:00
sam a67a142139 docs(prds): state the resource idempotency key and the approval gate's scope 2026-09-30 07:54:05 +10:00
sam 48416af5bc merge: capture the OAuth scope set and carry it to the harness secret (egkf.15) 2026-09-30 07:53:18 +10:00
sam cca80ac2e8 feat(egress): capture the OAuth scope set and carry it to the harness secret
A Kit's credentialFile cannot render {{.Scopes}} because nothing records the
granted scopes: the token response's `scope` field (RFC 6749 section 5.1,
space-delimited) was never read, and the token set had nowhere to hold it.

capture now parses `scope` into []string and keeps the previous set when the
field is absent or empty -- the same rule the refresh token follows, so a
refresh that does not repeat the scopes preserves what the login captured.

The set is carried end to end: Scopes on harnesssecret.Secret, in
harnessSecretPayload (JSON inside the existing encrypted envelope, so no
migration), on message HarnessSecret as `repeated string scopes = 8`, and
both ways through staterpc values.go. The proto field is load-bearing: the
daemon reads the token set over gRPC, so a local-struct-only field is
silently lost in production -- TestHarnessSecretConformance proves the round
trip in both its local and grpc modes.
2026-09-30 07:52:13 +10:00
sam 52d267683b merge: decide the dashboard test harness (7svn) 2026-09-30 07:51:44 +10:00
sam 0b00682fac merge: a TTL-bounded dedup gate for repeated inbound messages (104) 2026-09-30 07:49:59 +10:00
sam d1b8bff5ce docs(development): decide the dashboard test harness 2026-09-30 07:49:56 +10:00
sam ae8f0d42ef feat(gateway): a TTL-bounded dedup gate for redelivered platform messages 2026-09-30 07:48:56 +10:00
sam 39b61a0340 merge: record the operator's accepted package authority against the digest (em7s.3) 2026-09-30 07:43:23 +10:00
sam 06334ca3f9 merge: the own-PR flow no longer parks on the operator-approval gate (7nst) 2026-09-30 07:41:24 +10:00
sam f9e97b561f fix(workflow): the own-PR flow no longer parks on the operator-approval gate 2026-09-30 07:40:26 +10:00
sam d7f6f502a8 merge: decide the declared-outputs model for workflow.call (t2db.43) 2026-09-30 07:40:17 +10:00
sam 54e36ff8b7 merge: decide the operator-approval response channel and re-review cap (afbk.11) 2026-09-30 07:40:16 +10:00
sam a1c69c5b28 merge: one empty-state treatment from the installed primitive (micl.5) 2026-09-30 07:40:16 +10:00
sam bf68866dca feat(store): record accepted package authority against the pin
An archie package declares its authority; nothing in the tree recorded the
operator's acceptance of it. This lands the acceptance-record slice of
docs/prds/store.md ("Authority"):

- storepkg.Authority gains Covers (the upper-bound predicate: equal or
  narrower applies, wider does not) and Validate (forge-permission
  vocabulary, no blank grants).
- Installed carries AcceptedAuthority (nil until accepted); install leaves it
  unset, so an unaccepted package has no authority.
- AcceptPackageAuthority on the storepkg Manager records the acceptance
  against the pinned digest and refuses grants the package does not declare
  (storepkg.ErrAuthorityNotDeclared), carried over the wire.
- staterpc gains the admin-only AcceptPackageAuthority RPC;
  InstalledPackage carries accepted_authority.
2026-09-30 07:40:06 +10:00
sam 87d52938b5 refactor(webui): one empty-state treatment from the installed empty primitive 2026-09-30 07:39:10 +10:00
sam 90a4189db4 merge: render the Kit OAuth credential file with sentinels (egkf.13) 2026-09-30 07:38:58 +10:00
sam 013fcd0919 docs(prds): decide the declared-outputs model for workflow.call 2026-09-30 07:38:50 +10:00
sam 00209ebe87 docs(prds): decide the operator-approval response channel and re-review cap 2026-09-30 07:38:03 +10:00
sam 96e54e963f merge: cover the duration and byte-size control conversion logic (micl.4) 2026-09-30 07:37:33 +10:00
sam 2f05ed81b1 test(webui): cover the duration and byte-size controls' conversion behaviour 2026-09-30 07:37:05 +10:00
sam 822f8b63d4 feat(kitrun): render the OAuth credential file with sentinels
A Kit's credential@1 oauth.credentialFile was never rendered: Assemble set
SBX_CRED_<SVC>_MODE=oauth but no file was written, so the harness CLI started
logged out and never reached the token endpoint the egress proxy intercepts.

Render it at launch, for each bound OAuth-managed service that declares one:
the Kit's structure with its access/refresh sentinels, and the stored token
set's expiry for {{.ExpiresAt}}. The renderer's only input about a token set
is that expiry -- the tokens never cross into kit, so a real token cannot be
written (docs/prds/external-agent-harness.md, Verification).

Expiry renders as epoch milliseconds, the unit both in-spec OAuth credential
files use (Claude Code's expiresAt, OpenCode's expires). A placeholder archie
does not render, or a token placeholder with no declared sentinel, refuses the
launch rather than leaving a literal or an empty value in the file.

kitrun reads the store only for a service the run credential carries, and
fails closed when a rendered credential file has no captured token set.
2026-09-30 07:36:57 +10:00
sam e0ec9b87e6 merge: the dashboard workflow handlers act in the caller's org (t2db.45) 2026-09-30 07:35:12 +10:00
sam 27bad9f1fa merge: decide where per-workflow review settings live (0ry6) 2026-09-30 07:33:38 +10:00
sam 403ace1cef fix(webui): the workflow handlers act in the caller's org
The definitions query was built by hand, so it carried no org and the server
resolved the default one, while the enablement document read beside it and the
enablement write went to the default org outright. A caller in a non-default
org therefore read one org's definitions beside another org's enablement, and
toggled that other org's workflows.

workflowCollection now builds its query with controlplanerpc.QueryRequest, and
the three enablement reads and the write use org.OrgFromContext, so every one of
them names the org the principal put on the request context.
2026-09-30 07:33:16 +10:00
sam 761a1271a4 docs(prds): decide where per-workflow review settings live 2026-09-30 07:32:25 +10:00
sam c5a8942976 merge: carry the caller org from the request principal (t2db.45) 2026-09-30 07:25:48 +10:00
sam fb0424b729 fix(test): a table case holds the org, not a context
containedctx rejects a struct field of type context.Context, and both new
table tests stored one. Each case now carries what the caller put on the
context -- a builder in the org test, the org id in the client test -- and
builds the context inside the subtest.
2026-09-30 07:24:09 +10:00
sam 52b8b6dcca merge: name a workflow's declared inputs on the work-request form (06nq)
# Conflicts:
#	ui/dist/assets/index.js
2026-09-30 07:23:07 +10:00
sam d7178250ae feat(controlplane): carry the caller org from the request principal
The storage and wire contract already key resources by (org, kind), but no
caller sent an org, so every request acted in the default org. The org now
travels on the request context: webui's authorize middleware attaches the
verified principal's org, and one request-constructor per wire shape
(controlplanerpc's Query/History/Watch/CommandRequest) stamps it back, so a
call site cannot send the wrong org and a new one cannot forget it.

No behaviour change today: the shared token's principal is the default org's
owner, no production path creates another org, and a context with no principal
yields DefaultOrgID (what the server already derived from an empty org_id).
2026-09-30 04:01:52 +10:00
sam 9b282177e0 feat(webui): name a workflow's declared inputs on the work-request form
The dashboard could not name a workflow's declared inputs, so POST
/api/work-requests admitted a pr-review task with no pr_number, which then
failed at the workflow's intake stage (archie-core-06nq). The handler now takes
`inputs`, checks it against the workflow's declared interface before admitting
the task, and carries it through SpawnRequest.Inputs -> EnqueueChatTaskRequest;
the form renders one field per declared input, sends a declared number as a
number, and keeps Start disabled while a required input is empty.

Item 2 of the lane brief -- archie-core-afbk.12, review.precision_gate /
review.approve_before_post in the dashboard Config tab -- is deliberately NOT in
this commit. The surface it describes no longer exists in this tree; the
supervisor's decision was to stop it and re-scope it as its own lane, and the
facts it must start from belong in the branch's record:

* The Config-tab components were deleted by b5c98a0c (2026-09-25, "the legacy
  config catalog stops advertising fields the control plane owns"): ConfigSections.vue,
  ConfigRow.vue, ConfigControl.vue, ConfigList.vue, ConfigNotices.vue,
  ConfigUnavailable.vue, config-field.ts and sections.ts all went, because no
  page used them. Descriptor entries in internal/webui/config_schema.go would
  therefore change nothing a person can see: the only consumer of GET /api/config
  is SystemModelsPage reading `catalog`; the per-field `schema` has no renderer.
* The config write seams went earlier, in 295f8d69 (2026-09-21, "delete the
  runtime config overlay"): UpdateConfig, ResetConfig and UpdateRepoField are
  gone and internal/webui/server.go serves only GET /api/config. Configuration
  is written through the control plane.
* No control-plane resource carries review settings. executionSettingsDocument
  (internal/app/controlplane/workflow_settings.go) and workflow.ExecutionSettings
  carry only the four budget fields, and runtimeConfigFrom never layers
  cfg.Review. That is exactly why the budget descriptors survive in the catalog
  and review.* cannot: budgets are saved through workflow-execution-settings,
  edited on the Task-execution page, so those entries match a real write path.
* The brief's precedent name is wrong: TestToolSettingsProjectionCarriesEveryMCPServerField
  does not exist. The precedent is TestToolSettingsProjectionCarriesEveryMirroredField
  (internal/app/controlplane/runtime_config_test.go:349).

Making review.* genuinely editable needs a carrying control-plane resource
(extend workflow-execution-settings or add a review-settings kind), a layering
step in internal/app/archied/control_plane.go, and the round-trip test that
precedent sets -- an unsettled design decision spanning packages this lane does
not own.
2026-09-30 04:00:31 +10:00
sam 59273c9544 merge: attachment metadata in the session transcript (jaba) 2026-09-30 04:00:16 +10:00
sam 86e706dff7 merge: resume the PR branch before container acquisition (8li9.7) 2026-09-30 04:00:16 +10:00
sam ad5caf88a6 docs: the adversarial self-review record is removed, not shipped
docs/architecture/adversarial-review.md opened by describing the stage as
shipped and documented workflow.Reviewer, ReviewRequest, ReviewReport and
StageReview -- all of which 625ead95 deleted with the adversarial self-review
system. Three PRDs link to the page, so deleting it would break those links.

It gets a banner instead: the removal commit, the authority that supersedes it
(docs/prds/pr-review-agent.md says so in its own header), and the one section
that is stale in an older way -- the synchronous review_pr, which
archie-core-afbk.14 replaced with a queued pr-review task.

Regenerates docs/data/generated/dev-docs.json, which is built from these
sources.
2026-09-30 03:59:54 +10:00
sam a7efb9bb00 feat(webui): show attachment metadata in the session transcript
A message's attachments persist as metadata (messaging.Message.Media) and
cross the gateway wire, but the dashboard transcript rendered text only, so
a photo was invisible to the operator while the model had seen it.

The transcript view now carries the persisted metadata, and the browser
labels each attachment in the placeholder vocabulary the channels already
write into a message's text ('[photo]', '[document: report.pdf]'), with the
surviving metadata (mime, name, size, dimensions, duration) in the chip's
tooltip.

Bytes are never rendered: they are turn-scoped and stripped before a record
is stored, so there is nothing to fetch and no broken image or 404 link. The
platform file id is deliberately not served either -- it is a download
handle, not an address -- so the chip links out only when the attachment
itself carried a URL. A message with no attachments omits the media key, so
transcripts written before this change keep the payload they had.
2026-09-30 03:57:39 +10:00
sam 34f47a4bd0 fix(daemon): resume the task branch before container acquisition
prepareWorkspace always called worktree.Manager.Prepare, whose refresh
resets an existing clone onto origin/<base>. A remediation task -- one
continuing an archie-owned PR branch -- therefore lost that branch's
commits before its container started: StageResumeWorktree runs inside the
container against a tree already reset to base, and hybridTrees.Resume is
a no-op, so nothing restored origin/<branch>.

Route a task whose row names the remediate workflow through
Manager.Resume on the persisted Task.Branch, before Acquire. The branch is
read from the task row, never recomputed from the title or labels, and a
missing branch fails closed with a park rather than falling back to base.

Regression tests use a real bare remote: the prepared worktree's HEAD must
be the PR branch tip, a missing branch must park without touching the
worktree, and a non-remediation task must still start from base.
2026-09-30 03:56:04 +10:00
sam d60fcad18f fix(store): refuse resource keys the audit key cannot disambiguate
An empty org or kind, or either containing the '/' that joins them in the
audit record key, fails on read and write instead of colliding or reading as
an absent resource.
2026-09-30 03:43:23 +10:00
sam 8124c5af54 Merge pull request #1238 from samcharles93/security/prsource-zipslip
fix(prsource): guard archive extraction with a CodeQL-recognised containment check
2026-09-30 03:38:22 +10:00
sam bfc8d4b1b7 feat(store): key control-plane resources by (org, kind)
resources and resource_history are one document per org and kind, with
per-org advisory locks, request-ID idempotency and audit keys. The
control-plane Query/History/Command/Watch requests carry org_id; a request
naming none acts in the default org until the caller's org is derived
server-side.
2026-09-30 03:34:02 +10:00
sam 0b8e9ae7f1 fix(prsource): use a CodeQL-recognised containment guard when extracting archives
The tar.gz extraction already refused ".." escapes, but it did so with
filepath.Rel and checked the resulting relative path. CodeQL's go/zipslip
query models a sanitizer only as strings.HasPrefix applied to the value that
reaches the file-system sink, so the derived relative-path check was invisible
to it and it flagged os.MkdirAll/os.WriteFile on the joined target
(alert 17: internal/infrastructure/prsource/archive.go).

Resolve destDir to an absolute path once, reject an absolute entry name
outright, then test the joined target against the destination root with
strings.HasPrefix -- the PrefixCheck guard the query recognises. Behaviour is
unchanged: a ".." entry is still refused, and a wrapper directory is still
stripped. Adds an absolute-entry rejection test and a test proving an escaping
entry writes nothing outside destDir.
2026-09-30 03:15:21 +10:00
sam 662a5ee336 feat(telegram): carry inbound media through the chat turn
Telegram dropped every incoming photo, document, video and audio
message: the default handler required message text, and nothing on the
turn path knew media existed. The receiving path now closes the gap
end to end.

- telegram: extract the attachment from the update (largest photo, plus
  document, video, video-note, audio and voice kinds), download its
  bytes on the turn lane through getFile + the Bot API file link with a
  20 MB gate, submit the turn with the attachment, and answer
  unsupported content kinds (sticker, location, contact, poll) with a
  clear notice instead of silence
- messaging: Inbound carries turn-scoped transport media and
  MediaAttachment a Data field for in-process bytes; Message gains
  Media attachment metadata which stores persist (Postgres jsonb via
 migration 0020, memory store) with Data stripped at the persist
  boundary, and pb.Message carries the metadata on the gateway wire
- gateway: TurnModelRequest threads the turn's media to the model seam
- archied: the chat turn model merges the attachments into the final
  user message as ai-sdk image/file part entries, so vision-capable
  models see the file for the turn it arrived in; stored history keeps
  the placeholder note plus caption

Session log: messages carry what was sent as data (the attachment
metadata), not just prose. Transcript rendering of attachments and a
re-look capability are tracked as archie-core-jaba.
2026-09-30 03:07:54 +10:00
sam 8cbbdb20b5 feat(eda): per-org workflow enable/disable gating bindings
A workflow-enablement control-plane resource lists, per org, the workflows
that org has disabled. A binding targeting a disabled workflow is skipped at
dispatch like an unarmed one, is refused on save, and is flagged on the
binding list; the workflows page toggles it. Bindings now carry the org_id
column they already had in storage, over the State Store wire too.

Org-owned workflow definitions are deferred to a follow-up bead: they need
the caller's org, which the access chain resolves.
2026-09-30 02:59:23 +10:00
sam cadbc6d1ca Merge origin/main (v1.44.1) into local main 2026-09-30 02:39:21 +10:00
sam 64128645c2 fix(eda): reject a result map missing a field or needing a conversion
DecodeResult accepted any value reflect could convert, so a number for a
string field silently became the rune string (42 became "*"), and a declared
field absent from the map read as its zero value. Both are now reported: a
value is accepted only at the field's declared type, and every declared field
must be present.

That is the boundary the typed CEL environment promises, and it is live now
that the action runner decodes every result into actions.<id>.result before a
later expression reads it. D5 in docs/prds/multi-action-playbooks.md records
the rule.
2026-09-30 02:38:20 +10:00
sam 8155cc915a docs(eda): ratify args evaluation-failure semantics (J6)
An args value that cannot be evaluated aborts its playbook run: the action and
every later action in that playbook do not run, other playbooks matching the
event still run, and the task is unaffected. J3's skip-and-continue rule stays
specific to `when`, because a predicate has a meaningful false and data does
not.

Ratified now that the action runner is the production consumer, and locked by a
call-site test that fails if the rule is weakened to a skip. Drop the stale
"unbuilt decisions" header line, since J1, J2 and the Result schema
declarations have shipped.
2026-09-30 02:31:21 +10:00
sam 150dde5a7d test(state-store): parallelize real-process smoke tests 2026-09-30 02:14:29 +10:00
sam a65f558d35 chore(release): v1.44.1
deploy / gate (push) Failing after 5m44s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-29 15:41:53 +10:00
sam 0dff130682 Merge pull request #1237 from samcharles93/fix/1233-refresh-stale-seeded-workflow-definitions
fix(controlplane): refresh a stale seeded resource and re-seed a removed one
2026-09-29 15:12:45 +10:00
sam 2d1d4ed632 Merge pull request #1236 from samcharles93/fix/1235-repin-workflow-when-requeue-changes-it
fix(daemon): re-pin a task's workflow definition when a requeue names another
2026-09-29 15:12:01 +10:00
sam 67c5447ebc fix(controlplane): refresh a stale seeded resource and re-seed a removed one
A seed was consulted only for a resource kind the store did not hold, so a
document that changed in the build never reached a database an earlier
release had seeded. For workflow-definitions that is not a stale setting but
a total outage: the collection validates as one document, so a stored step
type this build no longer has fails every task's pin, whatever workflow the
task names. The seed's request ID was stable per kind and the store answers a
known request ID from resource_history, which outlives the resource, so the
documented recovery -- remove the resource and restart -- wrote nothing
either.

Seeds now carry one identity the reader can name, and a kind the store holds
is refreshed only when the seed itself wrote the newest revision: a
file-derived value stays the store's, and an operator's replacement is never
undone. The request ID is derived from the value, so an idempotent replay is
still one revision without making a second, changed document impossible. A
replay whose resource is gone re-creates it from the ledger's revision.

The shipped-vs-file-derived distinction is the seed's to make, so it is a
property of the definition (Defaults is set exactly for the kinds that ship a
document) rather than a check at each consumer.
2026-09-29 14:27:57 +10:00
sam db6e8d321e fix(daemon): re-pin a task's workflow definition when a requeue names another
Approving a waiting_human task requeues it under implement, but the requeue
only writes status, workflow and park_reason: the previous run's definition
stays pinned. pinWorkflowDefinition then returned early on any non-empty
stored definition, having checked only that the YAML matched its own recorded
digest -- a property of the write, never of the task -- so the dispatch went
out carrying a definition naming feasibility over a row naming implement.

That is the pair the worker's compile refuses
(agentworker.CompilePinnedWorkflow: "pinned workflow definition does not match
task identity"), so the task parked again immediately, identically on every
further approval, leaving decline the only working operator action.

A pin's identity is part of what makes it valid, not an assumption. The
producer now reads the id the stored definition declares (workflow.DefinitionID
answers that from YAML alone, without the step vocabulary) and re-pins from the
active collection whenever it disagrees with the task's workflow column. A pin
that is present, digest-valid and id-consistent is still a strict no-op, so an
operator's active definition override survives a dispatch unchanged, and a pin
whose YAML does not match its recorded digest is still refused rather than
silently overwritten.

Closes #1235
2026-09-29 13:34:10 +10:00
sam cbeab6afd2 chore(release): v1.44.0
deploy / gate (push) Failing after 3m39s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-29 02:04:40 +10:00
sam ed698fced1 feat(pr-review): benchmark live pipeline through generic workflow spawn 2026-09-29 00:35:34 +10:00
sam 081ee4a8ba docs(daemon): enqueue-time fields belong in the insert; review_pr names the approval gate 2026-09-28 22:42:19 +10:00
sam 5de07fac0e feat(pr-review): operator/chat trigger queues a pr-review task
review_pr self-omitted since 625ead95 deleted the synchronous reviewer it
called. It is rebuilt on the task enqueue path everything else uses: the
tool resolves the identity's configured repo, then queues a pr-review task
naming the pull request through the workflow's declared pr_number input,
which is the same generic input mechanism a watched-repos binding uses.

That input has to reach the store with the task, so
EnqueueChatTaskRequest gains inputs_json and the tasks insert writes the
inputs column directly. StampTaskBinding no longer writes it: the insert is
now the column's only writer, and a chat task must not acquire binding
provenance just to carry an input.

ChatPRReviewer, its result shape and the reviewer wiring are deleted with
the path they served.
2026-09-28 18:24:36 +10:00
sam 03335f49c1 fix(workflow): don't require a PR number for archie's own PRs
stagePRIntake's new missing-PR-number error (d0d759d2) fired even when
this stage runs embedded inside StagePRReviewAndOpenPR (archie's own
PRs, Task.Workflow == "implement"), where no PR exists yet and
localPRSource deliberately ignores the number. Scope the error to the
standalone pr-review workflow, which always needs a real, externally-
fetchable pull request.

Caught before this reached main: the existing StagePRReviewAndOpenPR
tests substitute a fake decision-stage list (by design, so they don't
have to script all nine phases' agent calls), so they never exercised
the real stagePRIntake and would not have caught this. Added a test
that calls stagePRIntake directly with Workflow: "implement" and no
PR number, which does.
2026-09-28 17:02:18 +10:00
sam d0d759d216 feat(workflow): watched-repos triggers pr-review via the generic binding system
Watched-repos needs no bespoke webhook-parsing code: the existing
generic capture+binding system (internal/infrastructure/captureintake,
internal/domain/binding.Binding) already turns any inbound webhook into
a task on any workflow, via a dashboard-editable matcher, CEL filter
and payload-to-input mapping. pr-review just needed to become a
binding-targetable workflow.

- Workflow gains an Interface field (task.WorkflowInterface) so a
  Go-literal builtin can declare inputs the same way a YAML-defined one
  does; ShippedDefinitions emits an inputs: block only when non-empty,
  so every other builtin's generated YAML is byte-identical to before.
- PRReview() declares pr_number as a required number input.
- Task gains EffectivePRNumber(): PRNumber when a producer set it
  directly (archie's own PRs), else the pr_number input a binding
  assigned generically through Task.Inputs. Handles json.Number (the
  store's round-trip encoding), float64 and int.
- The daemon resolves it once in acquireTaskContainer, before the task
  brief is written and before the pr-review prefetch runs, so
  everything downstream agrees. stagePRIntake falls back to the same
  resolution for any dispatch path that bypasses container acquisition,
  and fails loudly if neither PRNumber nor the input is set.

An operator wires up watched-repos entirely through the dashboard: a
Binding matching the webhook's source, a CEL filter for pull_request
events, workflow: pr-review, and an Inputs mapping pr_number from the
payload. No code change needed for a new repo or a new source.

Operator/chat trigger remains open, left as a precise continuation:
EnqueueChatTask is part of the State Store's protobuf-generated gRPC
contract (proto/state/v1/state.proto), not just a Go interface --
extending it for a generic inputs parameter needs a proto field
addition + regen, a new SQL query (StampTaskBinding cannot be reused,
since it unconditionally stamps binding_id/version, which a plain chat
task must never carry), and updates across staterpc's client/server and
~20 call sites. Real plumbing, not a quick tool rewrite -- scoped
correctly as its own pass rather than rushed here.
2026-09-28 16:59:32 +10:00
sam 67ead19dd9 feat(pr-review): daemon prefetches PR data so no forge credential enters the container
Adds the mechanism pr-review's watched-repos and operator triggers need:
before acquiring a pr-review task's container, the daemon fetches the pull
request's metadata, diff and head snapshot over its own credentialed forge
client (prefetchPRReview, using the already-built HTTP-based prsource.Source
from f7c64616) and writes the result under workDir/.archie-pr-review -- the
same host directory Docker bind-mounts into the container. The container-side
pipeline reads it back with prsource.MountSource, a local filesystem read, no
network call and no credential.

This follows the existing convention exactly (docs/development/agent.md,
"Giving the agent something new": "the daemon's own administrative token
never enters a container") and the same pattern WriteTaskJSON already uses
for the task brief -- prepare on the host before the container starts,
because the container binds the directory. No RPC service, no environment
variable, no exception to the stated rule.
2026-09-28 15:19:39 +10:00
sam f7c646163b feat(prsource): rebuild PRSource over the forge's HTTP API, no git checkout
The pipeline's Stage.Run bodies execute inside the sandboxed archie-agent
process, which holds neither a forge credential nor a git-level one --
confirmed the egress/CredentialCapability mechanism (grants.go,
credentials.go) only wires into the Kit/harness launch path
(kitrun.Launcher), not the built-in runner pr-review actually uses, so
routing through it as previously planned isn't viable without a much
bigger structural change. The git-shell Trees dependency needed a local
clone and a git-level credential the sandbox likely doesn't have even with
a bare API token.

Adds two narrow forge capabilities (PullRequestDiffReader,
RepoArchiveReader) implemented on both backends:
- GitHub: PullRequests.GetRaw for the diff, Repositories.GetArchiveLink
  plus a manual unauthenticated fetch of the resolved (pre-signed,
  non-API) blob URL for the archive.
- Gitea: GetPullRequestDiff and GetArchiveReader directly (no separate
  fetch needed).

PRSource.Snapshot fetches the archive and extracts it with a new
extractTarGz, which strips the wrapper directory both forges add (whether
represented as a bare-name path prefix or an explicit tar directory
header), refuses any entry that would escape destDir, and drops .git
entries per the Isolation contract.

Real bug caught before commit: the wrapper-stripping heuristic initially
treated a lone top-level file the same as a top-level directory header,
silently discarding the file entirely when no wrapper existed. Caught by
TestExtractTarGzWithNoWrapperDirectory before it shipped.

Not wired into any trigger yet -- watched-repositories and the operator
trigger still need this Source constructed and handed to the pr-review
task's TaskContext, which is where an execution-model decision (daemon-side
vs sandboxed) has to land first. Left as a precise continuation on
archie-core-afbk.7, not guessed past.
2026-09-28 14:46:09 +10:00
sam 8d05f99526 feat(workflow): wire pr-review into archie's own PRs before opening
StagePRReviewAndOpenPR runs the pr-review pipeline's decision phases
(1-8) against the task's own uncommitted change, using a new
localPRSource that reads Diff/Snapshot straight from Trees instead of
fetching an external PR -- there is no PR number yet to fetch one by,
which is why this trigger needed its own PRSource rather than the
forge-backed one afbk.7 already built for external PRs.

An unchallenged blocking finding parks the task with the findings
instead of opening a PR; a pipeline stage failure parks it the same
way any stage failure does. Once the PR opens, advisory findings post
against it -- best-effort, matching the deleted StagePostReviewComments'
convention: a posting failure is logged, not reverted into the outcome
the PR's existence already earned.

Implement() now uses this in place of the plain StageOpenPR. Bootstrap
and TDD are untouched -- the PRD names "the implement workflow"
specifically; extending to the others is a separate call.

Resolves this bead's first blocker (confirmed via read: CompilePinnedWorkflow
returns the same workflow.Workflow type and runs through the same
workflow.Run either compilation path, so a stage setting Outcome ends
the run identically regardless -- stagePROutput's posting logic had to
move inside StageOpenPR's own Run body, not follow it as a separate
Stage, which OpenPR's own doc comment already anticipated).

Still open on this bead: watched-repositories and operator triggers,
both blocked on the credential path for PRSource's real forge-backed
implementation reaching the sandboxed archie-agent process -- see the
bead comment for the concrete design (egress credential-capability
grant, narrow forge diff/archive HTTP methods) not yet built.
2026-09-28 13:06:42 +10:00
sam 625ead95b3 feat(workflow): remove the superseded adversarial-self-review system
docs/prds/pr-review-agent.md's own header already declared this
superseded (docs/architecture/adversarial-review.md, docs/prds/
operator-pr-review.md, docs/prds/review-calibration.md); this executes
that removal per the maintainer's explicit decision, so no reference
to the old path remains:

- internal/domain/workflow/review.go, review_findings.go,
  review_report_md.go and their tests: Reviewer, ReviewRequest,
  StageReview, StagePostReviewComments, ReviewReport/ReviewFinding and
  friends. ReviewComment relocated into workflow.go (still used by
  Forger.CreateReviewComments and the new pr-review pipeline).
- internal/app/agentworker/review.go: the ai-sdk-backed subagentReviewer.
- internal/app/archied/pr_review.go: the synchronous operator-review
  path (prReviewer, gateway.ChatPRReviewer wiring). The review_pr chat
  tool now self-omits (nil reviewer) until the operator trigger is
  rebuilt to enqueue an async pr-review task instead of reviewing
  synchronously in the chat turn.
- config.Repo.ReviewEnabled and its dashboard exposure.
- Two composition-order tests and one dashboard test that existed only
  to pin the deleted path.

Also splits PRReview()'s Stage list into prReviewDecisionStages()
(phases 1-8) and stagePROutput() (phase 9), so a future caller can
splice the decision phases before a PR exists and defer posting until
after -- needed for the "archie's own PRs" trigger, not wired here: it
needs the same stage-loop-around-StageOpenPR semantics this pass
couldn't fully verify in the time available (does an Outcome-setting
stage like StageOpenPR end the compiled-workflow-definition engine the
same way it ends workflow.Run's literal loop?). Carries ScoredFinding.
Adversary through synthesis so that trigger's blocking-finding check
doesn't need to cross-reference back into the pre-synthesis slice.

Not built in this pass, left as a precise continuation (see the bead
comment): the watched-repositories and operator triggers, both blocked
on the same real question -- how a forge-reading credential reaches
PRSource's real implementation when the pr-review pipeline's Stage.Run
bodies execute inside the sandboxed archie-agent process, which holds
none today.
2026-09-28 12:55:05 +10:00
sam 0acc922d9a feat(prsource): real forge-backed PRSource for the pr-review pipeline
Metadata/Diff/Snapshot implemented against a narrow Forge (GetPullRequest)
and Trees (CheckoutPR/Diff/Snapshot) contract, satisfying
workflow.PRSource -- the counterpart to the task's own Trees, which never
reaches an arbitrary external PR. worktree.Manager already satisfies the
narrow Trees interface structurally; forge.PullRequestReader needs a
small field-mapping adapter at the composition root (not yet wired --
see the afbk.7 continuation note).

Deliberately not wired into production task execution this pass: doing
so surfaced a real credential-boundary problem (see bead comment) that
needs resolving first, not papering over.
2026-09-28 12:32:08 +10:00
sam 595956cc75 feat(workflow): pr-review precision dial and operator-approval gate
Add review.precision_gate and review.approve_before_post to config,
threaded through TaskConfig/ForTask/ToConfig so the pr-review workflow
reads them under archie-agent too, not just in-process.

stagePRPrecisionGate runs between review and verification, filtering
findings down to concrete, evidenced defects when the dial is on;
stagePROperatorApproval ends the run in waiting_human right after
synthesis, before the merge gate, when approval is required and
findings exist. Both are off by default and fail open on a broken
agent call, matching the pipeline's existing recall-first fallbacks.

Filed follow-ups: afbk.11 for the actual operator-response resume
mechanics (post/reject/re-review with instructions, the 2-round cap --
genuinely needs either a small Task schema addition or a documented
Notes-encoding decision, a call for whoever wires afbk.7's triggers)
and afbk.12 for exposing the two flags in the dashboard Config tab.
2026-09-28 12:20:10 +10:00
sam 929784667b feat(workflow): merge gate, budget shares and skipped-phase reporting for pr-review
Phase 8 (merge gate) runs one classification call per finding, deciding
blocking vs advisory per the PRD's narrow criteria; a failed or malformed
call leaves the finding advisory. Added between synthesis and output.

A run-level token/wall-clock budget, split into cumulative per-phase
shares (prreview.Budget.PhaseExhausted), gates the expensive agent-call
work in lenses, review, verification, coverage-consistency, merge-gate,
and the anatomy narrative / output polish sub-calls -- deterministic
bookkeeping (snapshot, blast radius, clustering, scoring) always runs
regardless. A skipped phase is recorded and named in the posted review's
outcome, alongside the REQUEST_CHANGES/COMMENT event ReviewEventFor
already decided.

Known gaps left for a follow-up: workflow.Forger.CreateReviewComments
always posts a COMMENT-state review (GitHub's implementation submits
per-comment calls, not a review object, so REQUEST_CHANGES needs a
Forger/forge change), and there is no PR-body fallback list for
whole-file findings (docs/prds/inline-review.md).
2026-09-28 11:26:20 +10:00
sam d4e254b349 feat(workflow): wire pr-review's verification and coverage/consistency stages
Adds phases 5 and 6 of docs/prds/pr-review-agent.md between the existing
review and synthesis stages: an evidence verifier that drops unsupported
high-priority findings, an adversary that confirms/challenges findings and
may report new ones (more sceptical for a likely machine-written PR), a
per-cluster compound-defect check, a coverage gate that runs gap reviewers
for uncovered clusters and high-exposure blast-radius files (capped at 2
rounds), and consistency verification for cross-location obligations. The
coverage gate and consistency verification run in parallel per the PRD,
guarded by prReviewState.findingsMu.

Phases 5/6 are afbk.4's scope; the merge gate (phase 8) remains afbk.5's.
2026-09-28 11:04:44 +10:00
sam 89c5f8e2ad feat(workflow): add coverage-gap and exposure helpers to pr-review's deterministic core
Extends the afbk.1 deterministic core for afbk.4's coverage gate and
compound-defect check: exposure fan-in counts and high-exposure filtering
(blast.go), cluster/finding coverage matching and grouping (coverage.go),
and a high-priority severity predicate the evidence verifier gates on
(scoring.go).
2026-09-28 11:04:25 +10:00
sam 2ffe924a44 feat(workflow): wire the pr-review pipeline's Stage graph (afbk.3)
Adds PRSource (metadata/diff/snapshot, mirroring Trees for an external PR
rather than the task's own worktree) and the pr-review workflow: intake,
anatomy, lenses, review, synthesis and output as Stages recording
StepExecution children, built on the deterministic core from afbk.1/.2.

Phase 4's reviewer fan-out records a distinct StepFailed for a reviewer
that exhausted its turn cap or deadline before its terminal tool call,
separate from StepSucceeded for one that completed and found nothing
(the just-landed PRD refinement); phases 3, 4 and 9 fan out through a
bounded semaphore since tc.RunAgentChild already supports concurrent
StepExecution recording from inside one stage body.

Phases 5, 6 and 8 (verification, coverage/consistency, merge gate) are
out of scope -- afbk.4 and afbk.5. Output posts every line-anchored
finding as advisory forge review comments; the blocking/advisory split
needs the merge gate first.
2026-09-28 09:40:56 +10:00
sam c9f677f35b feat(workflow): pr-review intake depth and dimension merge
First slice of archie-core-afbk.3's pr-review pipeline (phases 1 and 3's
deterministic logic): depth classification from changed-line count with the
operator-override rule, the depth-to-dimension-cap table, cross-lens
dimension merge/dedup/cap, and the hallucination-check dimension added for a
likely-machine-written PR.

Table-driven tests cover the classification boundaries, the override rule,
duplicate-name merging, priority-ordered capping and the AI-generated
threshold. Stage wiring (agent calls, StepExecution recording, the fan-out
concurrency phases 3/4/9 need, and a PR diff/snapshot source) is still open;
see the bead for what remains.
2026-09-28 03:00:59 +10:00
sam d60f024e74 docs(prds): route intake's AI-score into lenses, split reviewer timeout from zero-findings, bound phase 9
Landing three PRD refinements found while studying prior reviewer art before
starting archie-core-afbk.3: dimension selection now sees intake's
machine-written score directly and adds a hallucination-check dimension for
it; a reviewer that exhausts its turn cap or deadline records a distinct
StepExecution status from one that completed and found nothing; phase 9
polish runs in a bounded pool of 8, matching phase 4.
2026-09-28 03:00:51 +10:00
sam 1fa3acdbe9 fix(security): bound harness IDs to int and drop a summed map size hint
deploy / gate (push) Failing after 3m38s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
Clears the five open CodeQL alerts. harnessCredential parsed uid and gid
as 32-bit and os.Chown converted them to int, which wraps on a 32-bit
build; they are now parsed to 31 bits, so an out-of-range id is refused
where it is read. mergeMapping sized its map by len(base)+len(override);
it now hints len(base) and lets the map grow.
2026-09-28 02:20:25 +10:00
550 changed files with 39800 additions and 7399 deletions

No files matched your search

@@ -66,6 +66,14 @@ packages the moment it merged; formatting and lint drifted the same way, and onl
the repository gate saw it. Both failures are paid for inside the lane when the
gate runs the build and the linter, and at merge when it does not.
Gate the **candidate** before `main` moves. Check the merge candidate out
detached — or gate the lane branch — and advance the ref only on a green result:
gating after a fast-forward lands the failure on the branch of record and leaves
only fix-forward or reset as exits. The lane brief must name the linter as well,
`golangci-lint run ./<package>/...` beside the scoped tests, because a scoped
test run cannot see a complexity or style limit and `task check` is where that
failure otherwise surfaces — once it is already merged.
A copy of the script under `.pi/control-plane-run/` is that run's disposable
state and may lag the skill's version. The skill's copy is the one to trust.
@@ -126,6 +134,36 @@ ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-<lane>/.pi/agents
`.pi/` is gitignored, so the worktree stays clean and the symlink cannot reach a
commit. This costs an hour to rediscover.
## Peer sessions over intercom
A fleet here can also run as **sibling sessions** coordinated over `intercom` —
a peer per lane — rather than pi-subagents children under one orchestrator.
These facts are peer-specific, and each has cost a real run.
- **Name the channel in the brief.** A peer's knowledge of how to report lives in
its context, not its configuration. Write "report to <peer> over intercom" as
an instruction; a convention that is only assumed evaporates.
- **A compaction erases conventions, not just facts.** A peer that compacts
mid-task keeps its task state and loses its transport: it reverts to
addressing its operator, and the coordinator reads that as idleness or death.
**Peer silence is not evidence of either** — ask for a one-line ack over the
channel before concluding anything. Re-priming restores the channel; the
transport itself survives compaction intact.
- **Match the task's shape to the session's window, not its strength.** A sweep
over hundreds of items needs the largest window available; a bounded hard
artifact (a PRD, a conformance review, a design decision) belongs in a smaller,
reasoning-strong session. A wide task in a small window stalls the task — too
wide is not the same as too hard, and it is the coordinator's assignment error,
not the peer's failure.
- **Checkpoint at ~70%, never compact mid-task.** A terse ledger sent to the
coordinator before the window fills survives; one reconstructed afterwards
loses exactly the identifiers — bead IDs, exact counts — that made it worth
having. Instruct every long-running peer to report and stop there.
- **One writer per resource.** Exactly one session writes the tracker. Two
writers produce double-closes, contradictory verdicts, and counts nobody can
reconcile. When a sweep changes hands, the successor re-derives them rather
than inheriting the predecessor's ledger as fact.
## Traps worth carrying
- **`touch` does not invalidate a Task source.** Task hashes file _content_, so a
@@ -143,11 +181,41 @@ build` still reports the binary up to date, shipping the old value. Tracked as
reaches, or changes a wire type, passes its own gate and fails
`task check` on a missing `tools/go.sum` entry or a stale schema. Such a
lane runs `go -C tools mod tidy` and `task docs:generate` and commits both.
Adding or editing a page under `docs/` — a PRD included — changes
`docs/data/generated/dev-docs.json`, which gains or loses a page: regenerate it
and commit it in the same commit, or `docs:artifact:check` fails. That failure
lands on `main`, not in the lane, if the ref moves first.
- **Untracked files in the shared checkout are other sessions'.** prdlint
scratch (`docs/prds/rules.jsonl`), editor state, and gate-written artifacts
appear and vanish under a lane. Never chase, add, stage or commit them: a
merge train's scope is its own lanes' files, and nothing else.
## codegraph answers symbol questions cheaply
The maintainer's `codegraph` MCP server indexes this repository. Prefer it to
grep or whole-file reading for "who calls X", "is this dead", "what does this
change touch": it enumerates call sites that a grep only summarises, and labels
each caller's confidence so interface fan-out is not mistaken for direct calls.
- **`pr_impact <base> <head>`** lists changed symbols with per-symbol caller and
test counts. Read `interface_dispatch` and the inferred tests alongside
`test_count`: a method reached through an interface reports a low direct test
count while many indirect tests reach it, and the compact line alone invites
the wrong conclusion.
- **It is a derived cache.** `scip-go` and tree-sitter rebuild it, and a query
indexes the revisions it names, so a cold query is slow and losing the index
costs a rebuild rather than data. `list_repositories` reports the indexed
revision — compare it with the tree before trusting a default-revision answer.
- **Stagger heavy queries.** Concurrent sessions share one instance, and
**name-based** `symbol_context` is what locks: it returns `database is locked`
or times out, while the same symbol **by id** returns immediately. Query
serially and retry rather than assuming a hang.
- **Report problems one line at a time** in
`/work/apps/codegraph/data/feedback.jsonl` — one JSON object per line, keys
`date`, `repo`, `task`, `tools`, `helped`, `missed`, `wrong`, `slow`. A raw
newline inside a string makes the line invalid and breaks every reader; a
multi-line entry corrupted that file once. Validate, append, never rewrite.
## Tracker conventions
`bd` is the only tracker; no markdown TODO lists, no local trackers.
@@ -120,6 +120,7 @@ Do not expose these helper flags as daemon settings.
| `models.<role>` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired |
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds ai-sdk catalogue. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired |
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired |
| `review.precision_gate`, `review.approve_before_post` | 2026-10-02: one control-plane resource `review-settings` (`internal/app/controlplane/review_settings.go`), seeded from `[review]`; the stored document outranks the file, layers field-by-field into `cfg.Review` (`runtimeConfigFrom`), and is watched live (`archie/control_plane.go`). Reaches a run through `Daemon.configFor` → `ForTask` → `TaskContext.Cfg`; the dashboard writes it on the Review settings page. | production-wired |
| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired |
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired |
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired |
@@ -169,13 +170,14 @@ looking at before reporting one:
| Key | Effective behaviour |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `image` | Required only when enabled. |
| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. |
| `max_uptime` | Default `60m` only when enabled; caps container lifetime. |
| `volume_ttl` | Default `72h` only when enabled; negative rejected. |
| `pull_policy` | Default `missing` when enabled. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. |
| `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. |
| `profiles` | Named agent execution environments (image or Kit); resolved per task dispatch (`ContainerConfig.Profile`). Own control-plane resource `agent-profiles` (`json:"-"` on the field so `container-runtime-policies` never carries it), `ApplyMode: live` -- a profile change applies without a restart, unlike the rest of `[containers]`. |
| `image` | Required at boot. Read by the container pool on every acquire (`containerLiveSettings` -> `Pool.current`, archie-core-zfb0.2), so a stored change applies without a restart. |
| `max_concurrency` | Zero means no limit. Read by the pool per acquire and applied to the daemon's running task dispatcher on publish (`ResizeTaskDispatcher`). |
| `max_uptime` | Default `60m` at boot; caps container lifetime. Read by the pool per acquire, so a stored change reaps the next container under the new cap. |
| `volume_ttl` | Default `72h` only when enabled; negative rejected. Re-read per cleanup cycle. |
| `pull_policy` | Default `missing` at boot. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. Read by the pool per acquire. |
| `registry_auth` | `SecretRef` (file-owned, `json:"-"`). Resolved at boot by `archied`'s `resolveRegistryAuth` and passed to `container.Config.RegistryAuth`; the pool base64url-encodes it into the `X-Registry-Auth` header (`internal/container/pool.go`'s `registryAuthHeader`). Zero ref = anonymous pull. Unresolvable/empty credential or an unencodable one warns and pulls anonymously rather than failing the pool. A half-named ref is refused by `configuration.validateContainers`. `container-runtime-policies` cannot carry a secret ref, so this stays boot-resolved and requires-restart, unlike `image`/`pull_policy`. |
| `network` | Empty uses best-effort self-network detection at boot; the repository overlay pins `archie-core_default`. Read by the pool per acquire, falling back to the boot-resolved network when the live value is empty. |
| `profiles` | Named agent execution environments (image or Kit); resolved per task dispatch (`ContainerConfig.Profile`). Own control-plane resource `agent-profiles` (`json:"-"` on the field so `container-runtime-policies` never carries it), `ApplyMode: live`. |
| `credentials` | Maps a Kit `credential@1` service to a secret (`config.CredentialBinding`). Own control-plane resource `credential-bindings`, `ApplyMode: live`, `json:"-"` on the field. `kitrun.Launcher` reads it fresh from the live `config.Holder` on every `Launch`, never a value captured at boot -- see `internal/infrastructure/kitrun/launcher.go`'s `resolveCredentials`. A binding alone grants nothing; see `org`/`granted_credentials` below. |
| `org` / `granted_credentials` (root and per-identity) | An identity's org and the `credentials` service names it may resolve. `daemon.runKitTask` reads both fresh per dispatch (`d.configFor(task)`) and passes them to `kitrun.Request`; `config.ContainerConfig.BoundCredentials` computes the declared (Kit) ∩ granted (identity) ∩ org-matched intersection -- neither declared nor granted widens the other. |
@@ -193,6 +195,13 @@ looking at before reporting one:
Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway
token and allowed-user list. Every other file setting is startup-only.
A stored `channel-settings` change is reconciled live by `archie-messaging`:
on a new version it re-resolves the file, layers the store over it, and restarts
only the channel whose transport settings changed (Telegram token/allowlist,
email relay, webhook route/secret). `chat.email.listen_addr` and
`chat.webhook_addr` are bound listen addresses, so those changes, and enabling
or disabling a channel, are reported outstanding and take effect on restart.
## Treat multi-identity as partially wired
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
@@ -216,8 +225,9 @@ Classify multi-identity changes field by field. Never label aggregate
## Preserve worker and secret boundaries
`Config.ForTask` creates a detached root snapshot: models, budgets, dispatch,
diff cap, notification, and forge host. `TaskConfig.ToConfig` reconstructs
`Config.ForTask` creates a detached root snapshot: models, budgets, the
retry/remediation cap (`MaxRetries`), dispatch, diff cap, notification, and
forge host. `TaskConfig.ToConfig` reconstructs
only those fields. Forge tokens, provider values, NATS credential references,
repos, and infrastructure settings do not enter `TaskConfig`.
+176
View File
@@ -5,6 +5,182 @@ release's per-component sections are labelled beneath its heading.
## [Unreleased]
## [1.46.0] - 2026-10-02
### archied
- feat(workflow): declared workflow outputs for wait:true callers
- feat(prreview): the operator-approval gate is PRReview's own stage-list entry
- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
- feat(prreview): the gate records the review it holds and posts the operator's answer
- feat(taskactions): one approval path answers the review gate from every surface
- feat(webui): the dashboard answers the review gate, including a re-review's instructions
- feat(daemon): resolve the producing identity's org before publishing work
- feat(webui): block invalid settings and show a field's former value
- fix(workflow): derive a declared output's captures need for profile selection
- fix(storepkg): validate every declared authority grant at the package descriptor
- feat(archied): refresh the model catalog at runtime
- feat(mcp): answer server-initiated sampling from the chat model
- feat(container): send registry auth on image pull
- feat(messaging): retract ephemeral replies after their TTL
- feat(messaging): transcribe Telegram voice notes
- fix(egress): take a run's credential kind from its binding, not the Kit
- feat(webui): a live-apply setting reads as applied, never as a restart
- feat(webui): the dashboard reads harness bindings and opens the setup terminal
- feat(gateway): list the harness page in the dashboard page registry
- feat(webui): the harness settings page and its setup terminal
- fix(workflow): park environment gate failures without dispatching a builder
- feat(messaging): adapter-facing clarify, picker and approval contract
- feat(gateway): gate admin slash commands by sender policy
- feat(plugins): load plugin and secret-engine files without a restart
- fix(workflow): deliver the feasibility PRD to the forge issue
- fix(messaging): report the daemon version this process was built from
- fix(messaging): carry an inbound attachment's bytes to the gateway turn
- fix(daemon): resume a retry whose worktree is gone
- fix(archied): omit the max-token bound on reasoning-class models
- fix(logging): file a task log record under its own event time
- fix(control-plane): unify validation for the domain-managed kinds
- feat(webui): let the operator choose the retry worktree mode
- feat(agent): seed a starter SOUL and upgrade only untouched templates
- feat(controlplane): add the writable review-settings resource
- fix(messaging): transcribe voice notes on the model-owning side of the boundary
- fix(messaging): gate the boundary on config reads, not only package links
- feat(messaging): restart only the channel whose settings changed
- feat(container): apply container-runtime-policies live
- feat(tools): reconcile MCP servers and tool settings live
- feat(messaging): add a per-turn interactive carrier for clarify and picker
- feat(gateway): offer ask_user when the turn's channel can carry a question
- feat(telegram): carry clarify and picker through the text fallback
- fix(webui): pin the dashboard validators to the control plane's
- refactor(agent): drop the SOUL upgrade branch with no shipped template
- feat(agentworker): answer MCP sampling from the task's model
- fix(workflow): bind the remediate worktree before the builder runs
- fix(config): carry max_retries into the worker TaskConfig snapshot
- fix(agentworker): supply the guardrail engine to every task run
### archie-agent
- feat(workflow): declared workflow outputs for wait:true callers
- feat(prreview): the operator-approval gate is PRReview's own stage-list entry
- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
- feat(prreview): the gate records the review it holds and posts the operator's answer
- feat(taskactions): one approval path answers the review gate from every surface
- fix(workflow): derive a declared output's captures need for profile selection
- fix(storepkg): validate every declared authority grant at the package descriptor
- feat(mcp): answer server-initiated sampling from the chat model
- feat(container): send registry auth on image pull
- feat(messaging): retract ephemeral replies after their TTL
- feat(messaging): transcribe Telegram voice notes
- fix(egress): take a run's credential kind from its binding, not the Kit
- fix(workflow): park environment gate failures without dispatching a builder
- feat(messaging): adapter-facing clarify, picker and approval contract
- feat(plugins): load plugin and secret-engine files without a restart
- fix(workflow): deliver the feasibility PRD to the forge issue
- fix(messaging): carry an inbound attachment's bytes to the gateway turn
- fix(daemon): resume a retry whose worktree is gone
- fix(logging): file a task log record under its own event time
- fix(control-plane): unify validation for the domain-managed kinds
- feat(webui): let the operator choose the retry worktree mode
- fix(messaging): transcribe voice notes on the model-owning side of the boundary
- feat(messaging): restart only the channel whose settings changed
- feat(container): apply container-runtime-policies live
- feat(tools): reconcile MCP servers and tool settings live
- feat(messaging): add a per-turn interactive carrier for clarify and picker
- feat(agentworker): answer MCP sampling from the task's model
- fix(workflow): bind the remediate worktree before the builder runs
- fix(config): carry max_retries into the worker TaskConfig snapshot
- fix(agentworker): supply the guardrail engine to every task run
## [1.45.0] - 2026-09-30
### archied
- fix(eda): reject a result map missing a field or needing a conversion
- feat(eda): per-org workflow enable/disable gating bindings
- feat(telegram): carry inbound media through the chat turn
- fix(prsource): use a CodeQL-recognised containment guard when extracting archives
- feat(store): key control-plane resources by (org, kind)
- fix(store): refuse resource keys the audit key cannot disambiguate
- fix(daemon): resume the task branch before container acquisition
- feat(webui): show attachment metadata in the session transcript
- feat(webui): name a workflow's declared inputs on the work-request form
- feat(controlplane): carry the caller org from the request principal
- fix(webui): the workflow handlers act in the caller's org
- feat(kitrun): render the OAuth credential file with sentinels
- feat(store): record accepted package authority against the pin
- fix(workflow): the own-PR flow no longer parks on the operator-approval gate
- feat(gateway): a TTL-bounded dedup gate for redelivered platform messages
- feat(egress): capture the OAuth scope set and carry it to the harness secret
- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
- feat(store): project installed package contributions into org resources
- feat(gateway): coalesce rapid-fire text events into one turn
- fix(config): expand plugin, module and skills dirs like every other operator path
- fix(webui): drop the config schema's editability advert
- feat(webui): events counts, YAML reading, log rows and dashboard filters
### archie-agent
- feat(eda): per-org workflow enable/disable gating bindings
- feat(telegram): carry inbound media through the chat turn
- fix(prsource): use a CodeQL-recognised containment guard when extracting archives
- feat(store): key control-plane resources by (org, kind)
- feat(controlplane): carry the caller org from the request principal
- feat(kitrun): render the OAuth credential file with sentinels
- feat(store): record accepted package authority against the pin
- fix(workflow): the own-PR flow no longer parks on the operator-approval gate
- feat(egress): capture the OAuth scope set and carry it to the harness secret
- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
- feat(store): project installed package contributions into org resources
## [1.44.1] - 2026-09-29
### archied
Two fixes to tasks that could not get past their workflow definition.
- **Approving a task no longer parks it again.** A task requeued under a
different workflow kept the previous run's definition pinned, so the worker
refused to compile the dispatch — it named `feasibility` while the row named
`implement` — and the task parked immediately, identically on every further
approval, which left `decline` as the only working operator action.
The daemon now re-pins whenever the pinned definition's id disagrees with the
task's workflow. A pin that is present, digest-valid and id-consistent is
still a strict no-op, so an operator's own definition override survives a
dispatch unchanged.
- **A shipped workflow definition now reaches an existing install.** A stored
seed was consulted only for a resource the store did not already hold, so a
document that changed in the build never reached a database an earlier
release had seeded. For workflow definitions that is a total outage rather
than a stale setting: the collection validates as one document, so a stored
step type this build no longer has failed every task's pin, whatever workflow
the task named — and the documented recovery, removing the resource and
restarting, wrote nothing either, because the store answered the seed's known
request ID from a history that outlives the resource. A seed now refreshes a
kind it wrote the newest revision of and re-creates a resource that is gone,
while an operator's own replacement is never undone.
### archie-agent
The runtime image is rebuilt with this release and links the shared workflow
package carrying the definition-id helper above. Hosts that run agent
containers need `docker compose pull agent` after updating to pick it up.
## [1.44.0] - 2026-09-29
### archied
Archie can now review pull requests.
- **Reviews on request and by watch.** Ask in chat or on the dashboard work form, add a repository to the watch list, or just let archie review its own PRs before it opens them. Review intensity follows a depth dial (quick/standard/deep) classified from the size of the change, and every finished review passes a verification layer — coverage-gap and cross-finding consistency checks — before it is produced.
- **No forge credential reaches the review sandbox.** The daemon prefetches the pull request's data and rebuilds its source snapshot over the forge's HTTP API, so the agent container works from an isolated copy with no read access to the repository's credentials.
- **Reviews stop at the operator gate before posting.** `review.precision_gate` / `approve_before_post` decide whether a finished review posts itself or parks for operator approval. With this release the parked state is a stop sign, not a checkpoint: the approve/reject/re-review responses behind the gate are not wired yet, and the gate's settings are not yet editable in the dashboard (configure them in `config.toml`). A parked review sits until that follow-up lands.
- The adversarial self-review pass archie previously ran before opening its own PRs is superseded by this pipeline and has been removed.
- Hardened harness input handling: harness identifiers are bounded to integer types.
### archie-agent
The runtime image is rebuilt with this release; it links the shared pr-review workflow packages behind the reviews above. Hosts that run agent containers need `docker compose pull agent` after updating to pick it up.
## [1.43.0] - 2026-09-28
### archied
+10 -6
View File
@@ -89,8 +89,10 @@ domain migration.
reload of `nats.url` logs an error requiring restart to prevent split-brain
delivery.
- **Container pull policy:** `containers.pull_policy` must be `"missing"`
(default) or `"always"`. Private registries return 401 on `"always"` because
no auth is sent. Refresh explicitly via `docker compose pull agent`.
(default) or `"always"`. Private registries need `containers.registry_auth`
(a `SecretRef` resolving to a `registry.AuthConfig` JSON document); without it
the pull is anonymous and a private registry answers 401. Refresh explicitly
via `docker compose pull agent`.
- **Docker Compose:** `docker-compose.yml` carries optional external NATS and
the `agent` build stanza. The agent uses a `build` profile so `up -d nats`
never starts it as a persistent service.
@@ -341,10 +343,12 @@ StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
separate fresh-context reviewer pass on every change as a matter of course.
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
opt-in per request — ask before running one. This is the rule for a human or
agent _contributor_. Separately, archied runs the same adversarial review
automatically on the PRs it opens (gated per repo by `repo.review_enabled`)
— see `docs/architecture/adversarial-review.md`. The two paths are distinct:
you run one when asked; archied runs one before it opens a PR.
agent _contributor_. Separately, archied runs its own PR review pipeline
(`docs/prds/pr-review-agent.md`) before it opens a PR of its own — see that
PRD's Triggers section ("archie's own PRs"). It supersedes the older
single-reviewer stage `docs/architecture/adversarial-review.md` described
(`repo.review_enabled` no longer exists). The two paths are distinct: you
run a manual pass when asked; archied runs its own before it opens a PR.
6. **Linter Guard:**
- When using `errorlint` fixes, ensure boolean predicates (e.g.
+1 -1
View File
@@ -154,7 +154,7 @@ tasks:
- bash tools/webhook-send.sh {{.CLI_ARGS}}
bench:prreview:
desc: Score PR review findings on the Martian benchmark (-- -findings DIR; --help for flags)
desc: Review or rescore the Martian benchmark (-- -review-model PROVIDER/MODEL -classification-model PROVIDER/MODEL; --help for flags)
cmds:
- go run ./cmd/archie-prbench {{.CLI_ARGS}}
+44 -7
View File
@@ -57,6 +57,14 @@ var deletionGate = []bannedCategory{
{"gateway runtime", []string{
modulePath + "internal/gateway",
}},
// The PRD names "Direct LLM providers, model runtimes" among what the
// Messaging Service must not own or link. These are the in-module
// infrastructure packages that construct one; building either here means
// a model-provider credential is in the messaging process.
{"model providers", []string{
modulePath + "internal/infrastructure/transcription",
modulePath + "internal/infrastructure/embedding",
}},
{"dashboard", []string{
modulePath + "internal/webui",
}},
@@ -92,13 +100,8 @@ func TestMessagingProcessLinksNoRuntimeItOnlyDials(t *testing.T) {
if excepted(importPath, linked) {
continue
}
for _, category := range deletionGate {
for _, prefix := range category.prefixes {
if !under(importPath, prefix) {
continue
}
t.Errorf("archie-messaging links %s (%s); the Messaging Service reaches that capability over a contract, never in-process (docs/prds/messaging-service-boundary.md, deletion gate)", importPath, category.name)
}
if category, banned := bannedLink(importPath); banned {
t.Errorf("archie-messaging links %s (%s); the Messaging Service reaches that capability over a contract, never in-process (docs/prds/messaging-service-boundary.md, deletion gate)", importPath, category)
}
}
for _, exception := range gateExceptions {
@@ -113,6 +116,40 @@ func TestMessagingProcessLinksNoRuntimeItOnlyDials(t *testing.T) {
}
}
// bannedLink reports the deletion-gate category importPath falls under, or
// ("", false). Classifying a single package is the rule the unit test below
// pins, so the gate can be exercised without a live `go list`.
func bannedLink(importPath string) (category string, banned bool) {
for _, c := range deletionGate {
for _, prefix := range c.prefixes {
if under(importPath, prefix) {
return c.name, true
}
}
}
return "", false
}
// TestDeletionGateBansModelProviderCapabilities pins the PRD category that the
// voice-transcription violation slipped past: the link gate would not flag
// anything merely because the process built an LLM client, so the capability
// packages are named explicitly. gatewayrpc is checked as the negative, since
// it is the permitted contract and must not be swept up by the internal/
// infrastructure/ prefix.
func TestDeletionGateBansModelProviderCapabilities(t *testing.T) {
for _, pkg := range []string{
modulePath + "internal/infrastructure/transcription",
modulePath + "internal/infrastructure/embedding",
} {
if _, banned := bannedLink(pkg); !banned {
t.Errorf("bannedLink(%q) = not banned; the Messaging Service must not construct a model-provider capability in-process", pkg)
}
}
if category, banned := bannedLink(modulePath + "internal/infrastructure/gatewayrpc"); banned {
t.Errorf("bannedLink(gatewayrpc) = %q; the Gateway contract is permitted", category)
}
}
// excepted reports whether importPath sits under an excepted package, recording
// the ones actually linked so a stale exception fails.
func excepted(importPath string, linked map[string]bool) bool {
+433
View File
@@ -0,0 +1,433 @@
// The link gate in architecture_test.go measures which packages the Messaging
// binary links. It cannot see a process that links nothing new but still reads
// a decoded configuration value it is not allowed to own -- which is exactly
// how voice transcription was wired into the Messaging Service while a green
// link gate watched: internal/app/archiemessaging/config.go built an LLM
// transcriber from [models].transcription and [providers.*], both of which
// docs/prds/messaging-service-boundary.md reserves to the model-owning process.
//
// This file closes that shape of hole: it scans the Messaging Service's own
// production sources for a read of a top-level config section the PRD forbids,
// so re-adding the projection field fails here rather than shipping green.
package main
import (
"go/ast"
"go/parser"
"go/token"
"os"
"path/filepath"
"strings"
"testing"
)
// messagingAppDir is the Messaging Service's application package, relative to
// this package's directory (go test runs with the package dir as cwd).
const messagingAppDir = "../../internal/app/archiemessaging"
// bannedConfigFields are the top-level config.Config fields the Messaging
// Service must never read, by Go field name. The PRD's "Configuration
// Ownership" section permits [chat.*], [services.*], [secrets] and the
// path/identity keys the process needs to locate itself; every entry here is a
// capability another process owns. internal/config's field names are the
// concrete keys, because that is what a Go read names.
var bannedConfigFields = map[string]bool{
"Forge": true, // [forge]
"Repos": true, // [repos]
"Models": true, // [models]
"Providers": true, // [providers]
"Containers": true, // [containers]
"NATS": true, // [nats]
// [runners] has no top-level field in internal/config today; if one is
// added its own name must be listed here with it.
}
// configReadOffenders returns the banned "<holder>.<Field>" config reads in
// src, in source order. A holder is anything the file gives the
// internal/config.Config type: an explicitly typed parameter, var, receiver or
// struct field, a short variable declaration or inferred var whose right-hand
// side resolves to one ("cfg := doc.Config"), or a range variable over a slice
// of them. The type is tracked by name because a name is what a Go read
// selects on. A config value returned by a call this file does not declare is
// outside a syntactic rule and stays untracked.
func configReadOffenders(src []byte) []string {
fset := token.NewFileSet()
file, err := parser.ParseFile(fset, "config.go", src, parser.SkipObjectResolution)
if err != nil {
// A file that does not parse is reported as an offender rather than
// ignored: silently skipping it would make this gate blind exactly
// when the tree is broken.
return []string{"parse error: " + err.Error()}
}
kinds := configKinds(file)
var offenders []string
ast.Inspect(file, func(n ast.Node) bool {
sel, ok := n.(*ast.SelectorExpr)
if !ok || !bannedConfigFields[sel.Sel.Name] {
return true
}
switch base := sel.X.(type) {
case *ast.Ident:
if kinds[base.Name] == configValue {
offenders = append(offenders, base.Name+"."+sel.Sel.Name)
}
case *ast.SelectorExpr:
// doc.Config, or the config-typed struct field h.cfg. Config is
// named by configuration.Document in another package, so it
// cannot come out of the kinds map; treat a selected Config as
// a config holder unconditionally.
if base.Sel.Name == "Config" || kinds[base.Sel.Name] == configValue {
offenders = append(offenders, base.Sel.Name+"."+sel.Sel.Name)
}
}
return true
})
return offenders
}
// configKind is how an identifier or expression reaches a config.Config value.
type configKind int
const (
notConfig configKind = iota // not a config value
configValue // config.Config
configSlice // []config.Config, [N]config.Config or map[K]config.Config
)
// configKinds resolves the identifiers in file that hold a config.Config, in
// two passes because an inferred holder's source must be classified before the
// holder's own name can be.
func configKinds(file *ast.File) map[string]configKind {
kinds := map[string]configKind{}
ast.Inspect(file, func(n ast.Node) bool {
switch node := n.(type) {
case *ast.FuncDecl:
classifyFields(node.Recv, kinds)
classifyFields(node.Type.Params, kinds)
case *ast.ValueSpec:
classifyNames(node.Type, node.Names, kinds)
case *ast.StructType:
for _, field := range node.Fields.List {
classifyNames(field.Type, field.Names, kinds)
}
}
return true
})
// Inferred holders: a single source-order pass suffices because Go
// requires a name to be declared before it is referenced.
ast.Inspect(file, func(n ast.Node) bool {
switch node := n.(type) {
case *ast.AssignStmt:
if node.Tok != token.DEFINE {
return true
}
classifyValues(node.Lhs, node.Rhs, kinds)
case *ast.ValueSpec:
// An explicit type was handled above; here only "var cfg =
// doc.Config", which infers the same way a := does.
if node.Type != nil {
return true
}
names := make([]ast.Expr, len(node.Names))
for i, name := range node.Names {
names[i] = name
}
classifyValues(names, node.Values, kinds)
case *ast.RangeStmt:
if exprKind(node.X, kinds) != configSlice {
return true
}
if id, ok := node.Value.(*ast.Ident); ok {
kinds[id.Name] = configValue
}
}
return true
})
return kinds
}
// classifyValues records each lhs identifier that resolves to a config kind of
// the rhs expression in the same position. A shorter lhs or rhs is fine;
// position is what pairs a name with its value.
func classifyValues(lhs, rhs []ast.Expr, kinds map[string]configKind) {
for i, target := range lhs {
if i >= len(rhs) {
return
}
id, ok := target.(*ast.Ident)
if !ok {
continue
}
if kind := exprKind(rhs[i], kinds); kind != notConfig {
kinds[id.Name] = kind
}
}
}
// classifyFields records every named field in fields whose type holds a
// config.Config.
func classifyFields(fields *ast.FieldList, kinds map[string]configKind) {
if fields == nil {
return
}
for _, field := range fields.List {
classifyNames(field.Type, field.Names, kinds)
}
}
// classifyNames records names as holding the config kind of typ.
func classifyNames(typ ast.Expr, names []*ast.Ident, kinds map[string]configKind) {
kind := typeKind(typ)
if kind == notConfig {
return
}
for _, name := range names {
kinds[name.Name] = kind
}
}
// exprKind resolves the config kind of an expression from the identifiers
// already classified in kinds.
func exprKind(expr ast.Expr, kinds map[string]configKind) configKind {
switch e := expr.(type) {
case *ast.Ident:
return kinds[e.Name]
case *ast.SelectorExpr:
// doc.Config of a configuration.Document, or a struct field the file
// declared as config.Config.
if e.Sel.Name == "Config" {
return configValue
}
return kinds[e.Sel.Name]
case *ast.CompositeLit:
return typeKind(e.Type)
case *ast.StarExpr:
return exprKind(e.X, kinds)
case *ast.UnaryExpr:
return exprKind(e.X, kinds)
case *ast.ParenExpr:
return exprKind(e.X, kinds)
case *ast.IndexExpr:
if exprKind(e.X, kinds) == configSlice {
return configValue
}
}
return notConfig
}
// typeKind reports the config kind a type expression names: config.Config, or
// a slice, array or map whose element is one.
func typeKind(expr ast.Expr) configKind {
switch t := expr.(type) {
case *ast.ArrayType:
if isConfigType(t.Elt) {
return configSlice
}
case *ast.MapType:
// A map's range value is its element; classify the map itself as a
// slice-like source so a range over it yields config values.
if isConfigType(t.Value) {
return configSlice
}
case *ast.StarExpr:
return typeKind(t.X)
case *ast.ParenExpr:
return typeKind(t.X)
}
if isConfigType(expr) {
return configValue
}
return notConfig
}
// isConfigType reports whether expr names internal/config's Config type,
// directly or behind a pointer.
func isConfigType(expr ast.Expr) bool {
switch t := expr.(type) {
case *ast.SelectorExpr:
id, ok := t.X.(*ast.Ident)
return ok && id.Name == "config" && t.Sel.Name == "Config"
case *ast.StarExpr:
return isConfigType(t.X)
}
return false
}
// TestMessagingReadsNoBannedConfigSection is the live gate: every production
// source file in the Messaging Service's application package is scanned, and a
// read of a PRD-forbidden section fails the build.
func TestMessagingReadsNoBannedConfigSection(t *testing.T) {
entries, err := os.ReadDir(messagingAppDir)
if err != nil {
t.Fatalf("read %s: %v", messagingAppDir, err)
}
scanned := 0
for _, entry := range entries {
name := entry.Name()
if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
continue
}
src, err := os.ReadFile(filepath.Join(messagingAppDir, name))
if err != nil {
t.Fatalf("read %s: %v", name, err)
}
scanned++
for _, offender := range configReadOffenders(src) {
t.Errorf("%s reads %s; the Messaging Service must not read or decode that section (docs/prds/messaging-service-boundary.md, Configuration Ownership) -- the capability belongs to the model-owning process, reached over a contract", name, offender)
}
}
// A gate that read no files would pass silently. Pin that it scanned the
// package it names.
if scanned == 0 {
t.Fatalf("no production .go files found in %s: the gate asserted nothing", messagingAppDir)
}
}
// TestConfigReadRuleCatchesTheOldWiring proves the rule fails on a synthetic
// copy of the shape that shipped: a projection built by reading
// [models].transcription and [providers.*]. Without this, the live gate's rule
// could rot into a no-op and still report a pass.
func TestConfigReadRuleCatchesTheOldWiring(t *testing.T) {
const reverted = `package archiemessaging
import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/transcription"
)
func project(cfg config.Config) projection {
return projection{
models: cfg.Models,
providers: cfg.Providers,
}
}
func setupTranscriber(cfg config.Config) {
_, _ = transcription.New(cfg.Models, cfg.Providers, transcription.Options{})
}
`
got := configReadOffenders([]byte(reverted))
want := []string{"cfg.Models", "cfg.Providers", "cfg.Models", "cfg.Providers"}
if strings.Join(got, ",") != strings.Join(want, ",") {
t.Fatalf("configReadOffenders() = %v, want %v", got, want)
}
}
// TestConfigReadRuleCatchesInferredHolders covers the holder shapes the first
// cut of this rule missed. It only saw a config.Config written out as a
// parameter or var type, so a value reached through an inferred short
// variable declaration ("cfg := doc.Config") or held in a struct field
// ("h.cfg.Models") left the forbidden [models]/[providers] read intact while
// the rule saw no holder to blame. Each case here fails red against that rule:
// the live gate would have reported a pass with the violation still shipping.
func TestConfigReadRuleCatchesInferredHolders(t *testing.T) {
cases := []struct {
name string
src string
want []string
}{
{
name: "short var decl from a Document's Config field",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
func f(doc configuration.Document) {
cfg := doc.Config
_ = cfg.Models
}
`,
want: []string{"cfg.Models"},
},
{
name: "inferred var without an explicit type",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
func f(doc configuration.Document) {
var cfg = doc.Config
_ = cfg.Models
}
`,
want: []string{"cfg.Models"},
},
{
name: "short var decl inherits config type from another holder",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
func f(cfg config.Config) {
other := cfg
_ = other.Providers
}
`,
want: []string{"other.Providers"},
},
{
name: "config held in a struct field",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
type holder struct {
cfg config.Config
}
func f(h holder) {
_ = h.cfg.Providers
}
`,
want: []string{"cfg.Providers"},
},
{
name: "range variable over a slice of config",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
func f(cfgs []config.Config) {
for _, cfg := range cfgs {
_ = cfg.Models
}
}
`,
want: []string{"cfg.Models"},
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got := configReadOffenders([]byte(tc.src))
if strings.Join(got, ",") != strings.Join(tc.want, ",") {
t.Fatalf("configReadOffenders() = %v, want %v", got, tc.want)
}
})
}
}
// TestConfigReadRuleAllowsThePermittedKeys proves the rule is not a blanket
// ban on config access: the sections the PRD does permit keep passing, and a
// nested chat field is not mistaken for a top-level one.
func TestConfigReadRuleAllowsThePermittedKeys(t *testing.T) {
const permitted = `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
func project(cfg config.Config) projection {
return projection{
telegram: cfg.Chat.Telegram,
email: cfg.Chat.Email,
gateway: cfg.Services.Get("gateway").Target,
workDir: cfg.WorkDir,
botUser: cfg.BotUser,
healthURL: cfg.Health.URL(),
}
}
`
if got := configReadOffenders([]byte(permitted)); len(got) != 0 {
t.Fatalf("configReadOffenders(permitted) = %v, want none", got)
}
}
+10 -3
View File
@@ -20,13 +20,20 @@ func main() { os.Exit(run()) }
func run() int {
var opts prbench.Options
var problems string
flag.StringVar(&opts.Config, "config", configuration.DefaultConfigPath(), "configuration file whose providers serve the judge model")
flag.StringVar(&opts.Fixtures, "findings", "", "directory of <problem id>.json findings to score")
flag.StringVar(&opts.Config, "config", configuration.DefaultConfigPath(), "configuration file whose providers serve the reviewer and judge")
flag.StringVar(&opts.Fixtures, "findings", "", "directory of <problem id>.json findings to rescore; omit to review live")
flag.StringVar(&opts.ReviewModel, "review-model", "", "provider/model for the review role in live runs")
flag.StringVar(&opts.ClassifyModel, "classification-model", "", "provider/model for the classification role in live runs")
flag.StringVar(&opts.JudgeModel, "judge-model", "anthropic/claude-sonnet-4.6", "provider/model of the independent judge")
flag.StringVar(&opts.Out, "out", "prbench-out", "directory for per-problem results and summary.json")
flag.StringVar(&opts.Out, "out", "bin/prbench-results", "directory for per-problem results and summary.json")
flag.StringVar(&opts.Resume, "resume", "", "reuse complete results from a previous run with the same models")
flag.StringVar(&problems, "problems", "", "comma-separated problem ids (default: all)")
flag.IntVar(&opts.Concurrency, "concurrency", 4, "problems judged at once")
flag.Parse()
opts.GitHubToken = os.Getenv("GH_TOKEN")
if opts.GitHubToken == "" {
opts.GitHubToken = os.Getenv("GITHUB_TOKEN")
}
if problems != "" {
opts.Problems = strings.Split(problems, ",")
}
+7 -2
View File
@@ -338,6 +338,7 @@ func TestStateStoreRealProcessSmoke(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeConfigWithServiceListen(t, dir)
@@ -355,7 +356,7 @@ func TestStateStoreRealProcessSmoke(t *testing.T) {
// Combined task/event/capture view: a task, an event on that task, and an
// unrelated capture written through one consumer, read back across all
// three surfaces in a single pass (the dashboard/observability read path).
task, err := cl.EnqueueChatTask(ctx, "acme", "widget", "verify state store", "body", "implement", "")
task, err := cl.EnqueueChatTask(ctx, "acme", "widget", "verify state store", "body", "implement", "", nil)
if err != nil || task == nil {
t.Fatalf("EnqueueChatTask = %+v, %v", task, err)
}
@@ -453,6 +454,7 @@ func TestStateStoreRealProcessDeadline(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
@@ -479,13 +481,14 @@ func TestStateStoreRealProcessRestartRecovery(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
first := startStateStoreProcess(t, bin, cfg)
s1 := dial(t, first.addr)
task, err := s1.EnqueueChatTask(t.Context(), "acme", "widget", "survive restart", "body", "implement", "")
task, err := s1.EnqueueChatTask(t.Context(), "acme", "widget", "survive restart", "body", "implement", "", nil)
if err != nil || task == nil {
t.Fatalf("first EnqueueChatTask = %+v, %v", task, err)
}
@@ -525,6 +528,7 @@ func TestStateStoreRealProcessTokenProtectedCaptureStream(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
const token = "operator-secret-token"
dir := t.TempDir()
bin := buildBinary(t, dir)
@@ -572,6 +576,7 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
+7 -6
View File
@@ -52,7 +52,7 @@ func recoveryFixture(t *testing.T) (string, *pgstore.TaskDB) {
// seedTask writes one task so the database holds more than its settings.
func seedTask(t *testing.T, st *pgstore.TaskDB, title string) {
t.Helper()
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", ""); err != nil {
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", "", nil); err != nil {
t.Fatalf("seed task %q: %v", title, err)
}
}
@@ -259,7 +259,7 @@ func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
if !strings.Contains(stdout, controlplane.ModelRoleAssignmentsKind) {
t.Errorf("rollback must name the resource it replayed; stdout = %q", stdout)
}
resource, err := st.Resource(t.Context(), controlplane.ModelRoleAssignmentsKind)
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
if err != nil {
t.Fatal(err)
}
@@ -269,7 +269,7 @@ func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
if resource.Version != 3 {
t.Errorf("resource version = %d, want a new revision (3) rather than a rewrite of the old one", resource.Version)
}
history, err := st.ResourceHistory(t.Context(), controlplane.ModelRoleAssignmentsKind, 0)
history, err := st.ResourceHistory(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind, 0)
if err != nil {
t.Fatal(err)
}
@@ -293,7 +293,7 @@ func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) {
if code != 0 {
t.Fatalf("rollback exited %d: %s", code, stderr)
}
resource, err := st.Resource(t.Context(), controlplane.ModelRoleAssignmentsKind)
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
if err != nil {
t.Fatal(err)
}
@@ -463,7 +463,7 @@ func storedResourceCount(t *testing.T, stdout string) int {
// a silent no-op.
func seedResource(t *testing.T, st *pgstore.TaskDB, kind, value, label string) {
t.Helper()
current, err := st.Resource(t.Context(), kind)
current, err := st.Resource(t.Context(), storecontract.DefaultOrgID, kind)
expected := int64(0)
if err == nil {
expected = current.Version
@@ -477,7 +477,8 @@ func seedResource(t *testing.T, st *pgstore.TaskDB, kind, value, label string) {
t.Fatal(err)
}
if _, err := st.PutResource(t.Context(), storecontract.ResourceWrite{
Kind: kind, Value: encoded, Actor: label, Source: "test",
OrgID: storecontract.DefaultOrgID,
Kind: kind, Value: encoded, Actor: label, Source: "test",
RequestID: fmt.Sprintf("%s-%d", label, expected+1), ExpectedVersion: expected,
}); err != nil {
t.Fatalf("seed resource %s: %v", kind, err)
+2 -2
View File
@@ -131,11 +131,11 @@ func (f *fakeGateway) Cancel(context.Context, string) (messaging.ChatCancellatio
func (f *fakeGateway) SetPersona(context.Context, string, string) (bool, error) { return false, nil }
func (f *fakeGateway) ApplyTaskAction(context.Context, string, int64, taskstate.Action) (messaging.TaskActionResult, error) {
func (f *fakeGateway) ApplyTaskAction(context.Context, string, int64, taskstate.Action, taskactions.ActionPayload) (messaging.TaskActionResult, error) {
return messaging.TaskActionResult{}, nil
}
func (f *fakeGateway) ApplyOperatorTaskAction(_ context.Context, actor taskactions.Actor, id int64, action taskstate.Action) (messaging.TaskActionResult, error) {
func (f *fakeGateway) ApplyOperatorTaskAction(_ context.Context, actor taskactions.Actor, id int64, action taskstate.Action, _ taskactions.ActionPayload) (messaging.TaskActionResult, error) {
f.mu.Lock()
defer f.mu.Unlock()
f.actions = append(f.actions, fmt.Sprintf("%d:%s", id, action))
+14 -3
View File
@@ -115,6 +115,11 @@ builder = "openai/gpt-5.4"
# (curators first). Unset, or a credential that fails to resolve, degrades
# to the capability reporting unavailable -- archied still starts.
# embedding = "openai/text-embedding-3-small"
# `transcription` is optional: it turns Telegram voice notes into text before
# the turn is dispatched, behind a "[voice transcription]" marker. Read by
# archie-messaging. Unset, or a provider that does not resolve, leaves the
# voice note as its media placeholder -- the turn still runs.
# transcription = "openai/whisper-1"
[providers.openai]
class = "openai"
@@ -442,6 +447,15 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
# volume_ttl = "72h" # max age for persistent repo volumes and Git clone caches
# pull_policy = "missing" # "missing" or "always"
#
# A private registry needs a credential the daemon sends on pull (an
# anonymous pull always answers 401 there, whatever the policy). The value is
# a Docker registry.AuthConfig JSON document -- {"username":"bot","password":"..."}
# ("identitytoken"/"registrytoken" are alternatives; "serveraddress" is
# optional and defaults to the image's registry). Unset means anonymous pulls,
# exactly as before this key existed; a reference that cannot be resolved
# warns and pulls anonymously rather than failing the daemon.
# registry_auth = { engine = "env", key = "ARCHIE_REGISTRY_AUTH" }
#
# Agent profiles a workflow selects with `profile: <name>`. A workflow that
# names none runs under [containers].image with every tool.
# Once the State Store holds container policies, edit profiles in the
@@ -496,9 +510,6 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
# # [containers].max_concurrency globally.
# # persistent_storage = true # reuse a per-repo Docker volume and Git object cache until volume_ttl
# # max_retries = 5 # per-repo override of the global max_retries above
# # review_enabled = true # run a fresh adversarial reviewer (no path to the implementer's
# # context) after gates pass and before the PR opens. Default false --
# # an uncalibrated reviewer that cries wolf is worse than no review.
# ── Tools ───────────────────────────────────────────────────────────────────
# Limits on what a tool may return. These bound how much of the context window
+24 -1
View File
@@ -1,6 +1,29 @@
# Adversarial self-review
Archie runs a fresh adversarial review of the diff before it opens a pull
> **Removed, not shipped (2026-09-28, `d73e0748`). This page records a system
> that no longer exists in the tree.**
>
> `d73e0748` ("remove the superseded adversarial-self-review system") deleted the
> stage and its contract: `workflow.Reviewer`, `ReviewRequest`, `ReviewReport`
> and `StageReview` are gone from `internal/domain/workflow`, so everything under
> "Contract" below describes types that cannot be found.
>
> The authority is `docs/prds/pr-review-agent.md`, which says so itself: it
> "supersedes the reviewer executor and blocking rule in
> `docs/architecture/adversarial-review.md`". archied now runs its PR review
> pipeline before it opens a pull request; there is no separate adversarial
> self-review pass and no `repo.review_enabled` setting.
>
> The page is kept rather than deleted because PRDs link to it
> (`docs/prds/adversarial-self-review.md`, `docs/prds/inline-review.md`,
> `docs/prds/pr-review-agent.md`). Read it as history.
>
> One section is stale in a second, older way: "Operator-triggered review" below
> describes the synchronous `review_pr` (fetch the head, snapshot it, run the
> reviewer, return findings), which `archie-core-afbk.14` replaced with a queued
> pr-review task.
Archie ran a fresh adversarial review of the diff before it opened a pull
request, so a PR arrives with a findings record rather than an unreviewed
claim. The reviewer provably cannot see the implementer's context: it reviews a
`.git`-free snapshot of the committed tree, not the worktree, the commit
+4 -2
View File
@@ -325,8 +325,10 @@ implemented in different packages:
synthetic issue numbers.
- Repository labels currently select workflows and mirror task state, coupling
domain transitions to forge presentation.
- Failure generally becomes `parked`, but failure classification and
retryability are not represented explicitly.
- Failure generally becomes `parked`, and the failure's classification is no
longer implicit: the persisted execution record carries the class the code
that parks recorded (the vocabulary lives in `internal/taskstate`), and
retryability is read from it rather than inferred from reason text.
- Generic observability events are emitted alongside state changes rather than
being the authoritative domain events.
+23 -7
View File
@@ -335,16 +335,32 @@ Two properties matter to anyone changing this area:
query, so boot records the last published settings and the reload re-applies
them from there.
- **Live kinds arrive on a watch.** Provider settings, model role assignments,
repository policies and scheduling policy are `ApplyMode: live`
(archie-core-zfb0.1): the daemon keeps a watch per kind and, on a new
repository policies, scheduling policy, tool settings, plugin settings,
review settings, channel settings and container runtime policies are
`ApplyMode: live`: the daemon keeps a watch per kind
(`boot.startRuntimeResourceWatches`, `runtimeResourceKinds`) and, on a new
version, re-runs `boot.runtimeConfig` over the published snapshot and
republishes through `config.Holder`. A candidate the layered document cannot
run is refused before it is published — last-known-good keeps running and
the refusal is reported through apply status. The kinds stay
restart-required while a startup-built component still holds their value
(tool, plugin, container and channel settings today); a kind joins the live
list only with a consumer that re-reads it, and the model/provider half of
it also rebuilds the gateway chat runtime's provider set and the chat model
the refusal is reported through apply status. Tool settings reconcile in this
process: the daemon diffs the stored MCP server set against the running
providers — connecting added servers, disconnecting removed ones and
reconnecting changed ones while an unchanged server keeps running — and
rebuilds the `web_fetch` and `minimax` entries, whose config was captured at
construction (`boot.reconcileToolSettings`). Container runtime policies
join the live set because their consumers re-read the published config: the
container pool reads image, pull policy, network, max uptime and concurrency
cap on every acquire and the daemon resizes its running task dispatcher from
the same publish; the fields the document cannot carry, `registry_auth`
above all, stay boot-resolved and remain requires-restart. A kind whose
consumer lives in another process reconciles there too: `archie-messaging`
re-reads the stored channel settings on the apply-status restamp interval
and restarts only the channel whose transport settings changed, while the
listen addresses it has bound and the set of channels it composed stay
process bindings that take effect on restart. A kind joins the live list
only with a consumer that re-reads it; one whose startup-built consumer
never does stays restart-required, and the model/provider half of the live
set also rebuilds the gateway chat runtime's provider set and the chat model
list the chat surfaces offer.
## Completion criteria
+19 -3
View File
@@ -202,13 +202,13 @@ actually owned, not by where it used to be built:
| Seam | Resolution |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |
| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never renders its own build into `/version`; `cmd/archie-messaging` does carry a `buildinfo` release stamp (added by `archie-core-k94o`, see the amendment below) for the updater's skew check and update verification, but `/version` still shows the Gateway's block so a partially upgraded deployment cannot report itself as matched. |
| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |
| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |
| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |
| `ReleaseAnnouncements` | **Still left nil**, but no longer for the `RunningVersions` reason (that seam now self-reports — see the amendment below). `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only version this process can vouch for is its own daemon-release stamp, not the agent's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |
| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |
| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |
| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |
| `RunningVersions` | **Wired from this process's own release stamp** (`archie-core-ot33`; see the amendment below). `archie-messaging` is one of the processes in the archied release set (the installer's `GATEWAY_SERVICES`), built from the same `archied/v*` tag and stamped with `buildinfo.Version` by every build site, so its compiled-in build is evidence that the release the installer claims actually reached this host. It reports `daemon = buildinfo.Version` and reports nothing for `agent` (task-scoped, observed only through `daemon.AgentStatus`), leaving the agent Unverified. The Gateway's rendered block is deliberately not used: that is a different process's stamp. |
| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported "not configured" before the extraction and still do. |
The Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and
@@ -217,6 +217,22 @@ The Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and
polls from outside to confirm an update came back up; the rest of the PRD's
prohibition list is untouched.
**Amended 2026-10-02 (`archie-core-ot33`, Telegram `RunningVersions`).** The
2026-09-19 decision left `RunningVersions` nil because it judged this process
could obtain only another binary's stamp. That was true when written and stopped
being true three days later: `ec0f17a7` (`archie-core-k94o`) gave every host
binary, `archie-messaging` included, a `buildinfo.Version` self-report so the
updater could detect per-binary skew. `cmd/archie-messaging` now registers
`buildinfo`'s `-version`, and every build site (`install.sh`,
`scripts/archie-update-install`, `.github/workflows/deploy.yml`, `Taskfile.yml`)
stamps it with the same `archied/v*` release as the rest of `GATEWAY_SERVICES`.
The messaging process therefore vouches for the `daemon` component from
`buildinfo.Version` — its own compiled-in build, never the Gateway's rendered
block — and reports nothing for the agent. A relayed update report can now
confirm the daemon and still names the agent as unchecked, while a binary the
update did not replace reads as drift. `ReleaseAnnouncements` stays nil: it needs
a version for every component, and this process can vouch only for itself.
**Phase 4 messaging severance: what must move, and the decision the PRD does
not cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot
pass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the
+6 -1
View File
@@ -312,6 +312,11 @@
"additionalProperties": false,
"description": "MediaAttachment describes a file attached to a message.",
"properties": {
"data": {
"contentEncoding": "base64",
"description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It crosses the wire in one direction only:\nthe inbound request from a channel frontend to the Gateway process\nthat runs the turn, because that process never holds the platform\ncredential. It is never persisted, and the stored-history and\noutbound-event directions strip it.",
"type": "string"
},
"duration": {
"description": "Duration is the play time in seconds for audio and video.",
"type": "integer"
@@ -345,7 +350,7 @@
"type": "object"
},
"type": {
"description": "Type is \"image\", \"video\", \"audio\", or \"document\".",
"description": "Type is \"image\", \"video\", \"audio\", \"voice\", or \"document\".",
"type": "string"
},
"url": {
+74 -14
View File
@@ -10,13 +10,13 @@
"url": "/dev/architecture/adversarial-review/",
"title": "Adversarial self-review",
"section": "Architecture",
"body": "# Adversarial self-review\n\nArchie runs a fresh adversarial review of the diff before it opens a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## Operator-triggered review\n\nThe same reviewer runs against an _existing_ PR via the channel-neutral\n`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated\nreviewer, and return the structured findings. Authorisation is identity-scoped\nto the operator's configured repositories; duplicate or concurrent reviews of\nthe same PR are deduplicated.\n"
"body": "# Adversarial self-review\n\n\u003e **Removed, not shipped (2026-09-28, `d73e0748`). This page records a system\n\u003e that no longer exists in the tree.**\n\u003e\n\u003e `d73e0748` (\"remove the superseded adversarial-self-review system\") deleted the\n\u003e stage and its contract: `workflow.Reviewer`, `ReviewRequest`, `ReviewReport`\n\u003e and `StageReview` are gone from `internal/domain/workflow`, so everything under\n\u003e \"Contract\" below describes types that cannot be found.\n\u003e\n\u003e The authority is `docs/prds/pr-review-agent.md`, which says so itself: it\n\u003e \"supersedes the reviewer executor and blocking rule in\n\u003e `docs/architecture/adversarial-review.md`\". archied now runs its PR review\n\u003e pipeline before it opens a pull request; there is no separate adversarial\n\u003e self-review pass and no `repo.review_enabled` setting.\n\u003e\n\u003e The page is kept rather than deleted because PRDs link to it\n\u003e (`docs/prds/adversarial-self-review.md`, `docs/prds/inline-review.md`,\n\u003e `docs/prds/pr-review-agent.md`). Read it as history.\n\u003e\n\u003e One section is stale in a second, older way: \"Operator-triggered review\" below\n\u003e describes the synchronous `review_pr` (fetch the head, snapshot it, run the\n\u003e reviewer, return findings), which `archie-core-afbk.14` replaced with a queued\n\u003e pr-review task.\n\nArchie ran a fresh adversarial review of the diff before it opened a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## OperatorLine truncated
},
{
"url": "/dev/architecture/agent-system/",
"title": "Agent System",
"section": "Architecture",
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
},
{
"url": "/dev/architecture/bindings/",
@@ -28,7 +28,7 @@
"url": "/dev/architecture/configuration/",
"title": "Configuration",
"section": "Architecture",
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognised filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognised filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
},
{
"url": "/dev/architecture/dashboard-agent-tools/",
@@ -64,7 +64,7 @@
"url": "/dev/architecture/migration-decisions/",
"title": "Architecture Migration Decisions",
"section": "Architecture",
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
},
{
"url": "/dev/architecture/observability/",
@@ -106,7 +106,7 @@
"url": "/dev/development/",
"title": "Development guides",
"section": "Development",
"body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| ---------------------------------------------- | -------------------------------------------------------------------------------- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` also adds linter-tool lines to `go.sum`\n (bead 1e37); restore `go.sum` before committing unless you changed a\n dependency.\n- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**\n carries the regenerated `docs/data/generated/dev-docs.json`: run\n `task docs:artifact` (not `task docs:check`, which checks contracts only).\n PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.\n"
"body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| ---------------------------------------------- | -------------------------------------------------------------------------------- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` writes no module file on a consistent tree,\n root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`):\n a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or\n `updates to go.mod needed`, rather than being repaired. Only a global\n `GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the\n `go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run\n `go mod tidy` and commit the result on its own.\n- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**\n carries the regenerated `docs/data/generated/dev-docs.json`: run\n `task docs:artifact` (not `task docs:check`, which checks contracts only).\n PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.\n"
},
{
"url": "/dev/development/agent/",
@@ -118,19 +118,19 @@
"url": "/dev/development/control-plane/",
"title": "Control plane and settings",
"section": "Development",
"body": "# Control plane and settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator.\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the wire-shape type the resource's `Document` names — a dedicated\n struct in `internal/app/controlplane/` with explicit snake_case json tags\n (`channel_settings.go`, `tool_settings.go`, `container_settings.go` are the\n precedents), never the internal config struct itself. A struct fed straight\n into the document falls back to Go field names (`Window`, `MaxRequests`),\n and a bare `time.Duration` marshals as nanoseconds — both render unusable\n in the Web UI. The resource's JSON schema and the dashboard's Advanced\n settings editor are generated from that type, so no UI work is needed for\n the editor itself.\n2. Map to and from the internal config type at the resource boundary (`Seed`,\n the layering in `runtime_config.go`, and the validator all use the same\n mapping). Durations in the document are a string-marshalling type\n (`config.Duration` or a document-local one), never a bare `time.Duration`.\n3. A document stored before the shape existed carries Go-cased keys. Read them\n with `controlplanerpc.DecodeRenamingLegacyKeys` (an `UnmarshalJSON` on the\n wire type) while keeping `DisallowUnknownFields` — dropping unknown keys\n would decode a misspelling as \"unset\" — and register a `Normalize` on the\n `Definition` that re-encodes the document, so a legacy document converges\n the next time it is written. A map or a nested struct needs its layering\n checked: a stored map replaces the file's, not merges into it, and a field\n the stored document omits keeps the file's value. Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n7. A generic catalog resource (`replace` command, not domain-managed, no\n query service) is watched **once per archie-ui process** by `webui.RunLive`,\n then published to every browser through `/api/stream`. Do not add an\n EventSource per resource to a settings store or a gRPC Watch per HTTP client.\n The control-plane server polls `Resource` every 250ms per upstream Watch;\n verify watch count is independent of client count and that late clients get\n the hub's current value (`internal/webui/live_hub_test.go`, real server over\n bufconn). Reopens resume after the last delivered version and charge failed\n attempts; accepting a gRPC stream does not establish its health.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved through the secret registry. Never inspect\n a resolved value, even in a test.\n- Reject a configuration that sets a field with no consumer rather than\n accepting and ignoring it (per-identity `forge.intake` is the precedent).\n"
"body": "# Control plane and settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator. A stored\n value is refreshed from the file only when the store has no value for the kind\n at all; a kind that ships a document of its own (workflow definitions,\n personas) is refreshed whenever the seed itself wrote the stored copy, since\n that copy is a previous release's document rather than an operator's\n (`controlplane.Server.seedKind`).\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the wire-shape type the resource's `Document` names — a dedicated\n struct in `internal/app/controlplane/` with explicit snake_case json tags\n (`channel_settings.go`, `tool_settings.go`, `container_settings.go` are the\n precedents), never the internal config struct itself. A struct fed straight\n into the document falls back to Go field names (`Window`, `MaxRequests`),\n and a bare `time.Duration` marshals as nanoseconds — both render unusable\n in the Web UI. The resource's JSON schema and the dashboard's Advanced\n settings editor are generated from that type, so no UI work is needed for\n the editor itself.\n2. Map to and from the internal config type at the resource boundary (`Seed`,\n the layering in `runtime_config.go`, and the validator all use the same\n mapping). Durations in the document are a string-marshalling type\n (`config.Duration` or a document-local one), never a bare `time.Duration`.\n3. A document stored before the shape existed carries Go-cased keys. Read them\n with `controlplanerpc.DecodeRenamingLegacyKeys` (an `UnmarshalJSON` on the\n wire type) while keeping `DisallowUnknownFields` — dropping unknown keys\n would decode a misspelling as \"unset\" — and register a `Normalize` on the\n `Definition` that re-encodes the document, so a legacy document converges\n the next time it is written. A map or a nested struct needs its layering\n checked: a stored map replaces the file's, not merges into it, and a field\n the stored document omits keeps the file's value. Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n7. A generic catalog resource (`replace` command, not domain-managed, no\n query service) is watched **once per archie-ui process** by `webui.RunLive`,\n then published to every browser through `/api/stream`. Do not add an\n EventSource per resource to a settings store or a gRPC Watch per HTTP client.\n The control-plane server polls `Resource` every 250ms per upstream Watch;\n verify watch count is independent of client count and that late clients get\n the hub's current value (`internal/webui/live_hub_test.go`, real server over\n bufconn). Reopens resume after the last delivered version and charge failed\n attempts; accepting a gRPC stream does not establish its health.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved throLine truncated
},
{
"url": "/dev/development/daemon/",
"title": "Daemon",
"section": "Development",
"body": "# Daemon\n\nThe daemon claims and runs tasks, and turns captured events into tasks through\nbindings. This page covers both.\n\n## Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n### Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server\n catalogue replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n### Adding a task field\n\nFollow [State Store](/dev/development/state-store/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue needs its own statement (as\n`StampTaskBinding` does for binding provenance and inputs).\n\n### Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n\n## Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n### Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n### Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store](/dev/development/state-store/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Frontend UI](/dev/development/frontend-ui/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n### Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
"body": "# Daemon\n\nThe daemon claims and runs tasks, and turns captured events into tasks through\nbindings. This page covers both.\n\n## Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n### Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server\n catalogue replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n### Adding a task field\n\nFollow [State Store](/dev/development/state-store/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue belongs in the insert that creates the\nrow (as `InsertChatTask` does for inputs), or in its own statement when only\nsome producers set it (as `StampTaskBinding` does for binding provenance).\n\n### Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n\n## Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n### Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n### Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store](/dev/development/state-store/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Frontend UI](/dev/development/frontend-ui/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n### Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
},
{
"url": "/dev/development/frontend-ui/",
"title": "Frontend UI",
"section": "Development",
"body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has\n no ignored `ui/node_modules`: run `cd ui \u0026\u0026 npm ci` before these commands.\n6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only\n `new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume\n topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE\n stream. Logs alone opt in while mounted, replacing that same EventSource\n with `?topics=logs\u0026since=\u003clast cursor\u003e`; a browser's `Last-Event-ID` only\n survives its own automatic reconnect, not a newly constructed EventSource.\n Task and log topics resume by cursor; control-plane, identity and apply-status\n topics replay the latest snapshot. Test a fetch and same-origin navigation\n after visiting Settings and Logs: the UI process serves HTTP/1.1 and six\n persistent streams can starve every later browser request.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n6. For a new live topic, add one process-wide producer to `internal/webui`'s\n `RunLive` and fan it through the `/api/stream` hub; `internal/app/archieui/run.go`\n starts the producers with the process context. Never create an upstream\n watch or poller in an HTTP handler. A slow client must reconnect for cursor\n and snapshot repair rather than silently lose an update. Prove the producer\n with several browser clients against the real peer, not just a scripted\n stream; `live_hub_test.go` is the example.\n"
"body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has\n no ignored `ui/node_modules`: run `cd ui \u0026\u0026 npm ci` before these commands.\n6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only\n `new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume\n topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE\n stream. Logs alone opt in while mounted, replacing that same EventSource\n with `?topics=logs\u0026since=\u003clast cursor\u003e`; a browser's `Last-Event-ID` only\n survives its own automatic reconnect, not a newly constructed EventSource.\n Task and log topics resume by cursor; control-plane, identity and apply-status\n topics replay the latest snapshot. Test a fetch and same-origin navigation\n after visiting Settings and Logs: the UI process serves HTTP/1.1 and six\n persistent streams can starve every later browser request.\n\n## Testing the dashboard\n\nAuthority: the runner itself is `ui/package.json`'s `test` script: `node --test\n--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs\npure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM,\nno second dependency beyond what the app already carries. That is the standard,\nand a decision record for when it is deliberately not enough:\n\n- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes,\n draft state, copy conditions, filters and payload building live in plain\n `.ts` files beside the components and are tested in `ui/test/`. Components\n stay thin, so there is normally nothing in an SFC that is archie logic.\n- **A dashboard rule that mirrors a server rule is pinned by a shared\n fixture, not two independent tests.** `ui/src/settings/validation.ts`\n hand-mirrors three control-plane validators, and the model-role rule had\n already drifted because nothing tied the two sides together. Each case now\n lives once in `internal/app/controlplane/testdata/dashboard-validators.json`:\n a Go test in that package runs the real server validators over it, and\n `ui/test/control-plane-validator-parity.test.ts` runs the real dashboard\n validators over the same cases. Changing one rule alone fails the other\n side's test. Add a case to the fixture, never to one side only.\n- **Installed primitives are upstream-tested, not re-tested here.**\n `reka-ui` (2.10.5 here) maintains colocated tests per component in its own\n repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the\n arrow-navigation composables). The npm package ships none of those files, so\n this coverage is inherited through the version bound, not the tarball —\n `grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local\n mount tests would test a dependency.\n- **A `.vue` import cannot run under the module runner.** `node --test` fails\n such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no\n built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is\n therefore a broken test, not a weak one.\n- **If a DOM mount harness is ever needed** (a page-level accessibility\n contract, cross-component interaction, focus behaviour): `happy-dom` +\n `@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the\n module runner for everything else. Measured on the ui tree (vitest 5.0.2,\n happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level\n `node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount\n suite (role=radiogroup vs role=switch, aria-label, click activation against\n the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and\n `vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner\n alternative (absorbing the existing suite into vitest) was measured\n infeasible as-is: all 29 existing files impLine truncated
},
{
"url": "/dev/development/merging-work/",
@@ -154,7 +154,7 @@
"url": "/dev/development/workflows/",
"title": "Workflows",
"section": "Development",
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n"
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Retiring a step type\n\nA step word cannot simply be deleted. A stored or pinned definition is\nvalidated as a whole collection, so one unknown word fails EVERY workflow's\ndefinition to decode and the workflow-definitions resource becomes unreadable.\nRetire a stage by removing it from its workflow's `Stages` and adding it to\n`retiredSteps` in `definition.go`, which keeps the word resolving as an inert\nstage. The retired stage must do nothing: the behaviour it used to perform now\nbelongs to whatever layer took it over (the remediate workflow's in-container\nresume moved to daemon worktree preparation, `archie-core-866m`; the workflow\nstill binds the daemon-prepared directory and the PR branch in a `prepare`\nstage before any agent work).\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- A declared `outputs:` entry is written through a capture tool, so it forces\n the captures need: `task.WorkflowInterface.Needs` resolves that from the\n declaration rather than the author also writing `needs.captures`. A Kit\n profile whose harness serves no capture tools is refused before dispatch.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n\n## Enabling and disabling\n\nThe `workflow-enablement` control-plane resource lists, per org, the workflows\nthat org has disabled; anything unlisted is enabled. Its readers are the\ndaemon's binding dispatch (a disabled workflow's binding is skipped like an\nunarmed one), the dashboard's binding save (refused) and binding list\n(`workflow_disabled`), and work requests. A new reader of \"may this org run\nthis workflow\" goes through `task.WorkflowEnablement.Enabled`, never a second\nlist. The dashboard acts in the default org until access resolves a caller's\nown.\n\n## Starting a workflow from chat\n\n`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards\ninputs through the task creation contract; it does not interpret individual\nworkflows. The daemon checks inputs against the pinned `WorkflowInterface`\nbefore acquiring a container and parks invalid requests with the reason.\n"
},
{
"url": "/dev/prds/01-project-management/",
@@ -352,7 +352,7 @@
"url": "/dev/prds/mcp-tool-completion/",
"title": "MCP client and tool-guardrail completion",
"section": "PRDs",
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a\nparallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n| ------------------------------- | ------------------------------------------------------------------------------------------ |\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the mutex for\nthat server's `Client` instance entirely and let the caller's own\nconcurrency (already proven by the closed concurrent-dispatch bead, `#183`)\nhandle it. This is additive — no server's behaviour changes unless an operator\nopts in.\n\n**Call site.** `internal/config/config.go` (struct field),\n`internal/tools/mcp/client.go` (make the mutex conditional on the\nfield), and wherever `MCPServer` configs are turned into `Client` instances\nat daemon startup (the constructor that reads `internal/config`'s MCP block).\n`config.example.toml`'s commenLine truncated
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client. The agent worker hosts the same configured MCP servers on the\ntask path and runs its own model runtime, so `internal/app/agentworker` wires\nthe same seam from the task's builder model: a server that samples succeeds\ninside a chat turn and inside a task, never one and not the other. The message\nmapping and the token bound are shared (`internal/agentexec`, next to the\nruntime both paths call models through) so both paths bound a sample\nidentically.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`) and the task model path already exists\n(`agentexec.NewRuntime`, the runtime an agent stage runs on); this reuses both\nrather than adding a parallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n| ------------------------------- | ------------------------------------------------------------------------------------------ |\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the muLine truncated
},
{
"url": "/dev/prds/memory-engine-unification/",
@@ -376,7 +376,7 @@
"url": "/dev/prds/multi-action-playbooks/",
"title": "Multi-action playbooks and typed action results",
"section": "PRDs",
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define;\n- an arg value whose checked CEL type cannot fill its `Args` field (`'123'`\n for a string field). A `dyn` value, such as an `event` read, passes: its\n type is known only per event, and the module decode refuses a bad one at\n run.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo or a wrongly typed value a load\nfailure.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.*Line truncated
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define;\n- an arg value whose checked CEL type cannot fill its `Args` field (`'123'`\n for a string field). A `dyn` value, such as an `event` read, passes: its\n type is known only per event, and the module decode refuses a bad one at\n run.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo or a wrongly typed value a load\nfailure.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.*Line truncated
},
{
"url": "/dev/prds/news-and-releases/",
@@ -406,13 +406,25 @@
"url": "/dev/prds/playbook-expression-syntax/",
"title": "Playbook data-flow and condition syntax",
"section": "PRDs",
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\nUnbuilt decisions: `archie-core-t2db.25` (J1 action ids),\n`archie-core-t2db.26` (J2 args as CEL),\n`archie-core-t2db.27` (Result schemas declared to CEL).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a condition\ndeciding whether the action runs; (b) a later action's `args` values referencing\nan earlier action's `Result` and the triggering event's fields. Both are **CEL\nexpressions**, evaluated against one evaluation context. There is no separate\ninterpolation syntax: CEL reads nested maps and fields natively, so `args`\nvalues that need data are written as CEL, and only plain literal args remain\nplain YAML scalars.\n\nBoth halves are read-only: expressions may read context values and compute a\nresult from them, never mutate, never call host functions, never perform I/O.\nCEL enforces this structurally (no side effects, linear evaluation when macros\nare bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged** -- the\nsame tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's\ntrust-boundary section): loaded from a configured directory at startup, never\nfrom a webhook body or task worktree. The schema-by-example flow uses live\nevents to _design against_; the saved playbook is operator-authored file content\nin an operator-configured location.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not attacker\n input; no sandboxing against a hostile expression string is required. If a\n future playbook source is less trusted (auto-generated bindings from\n unauthenticated captures), that is the playbook-file trust tier moving -- the\n loader's acceptance check is the right place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook body, prior\n results through the same pipeline). Robustness against hostile data is\n required: no panic on wrong-typed/missing fields, no unbounded cost on\n deep/cyclic maps, bounded evaluation time. CEL provides this structurally\n (cost limits, linear non-Turing-complete evaluation, error values instead of\n panics -- verified in the vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)\nas the repo's conditional-logic precedent. That is the wrong precedent for\nplaybook conditions because this document's premise is: **YAML is pure\norchestration data; Yaegi is where imperative logic lives** (Problem section;\nmodule-position.md's \"no generic hook\" section). Yaegi snippets in YAML would\nmove imperative logic into the data layer -- the inversion this design exists to\nprevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data, not\nprograms**. CEL is non-Turing-complete and side-effect-free, so it cannot become\na program; a condition that needs real logic gets a Module kind (Yaegi),\nreferenced by the action, not a stronger expression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an `any`\npayload; it exists to keep static implementation contracts typed. Evaluating CEL\nagainst runtime `map[string]any` is **not the same problem**: the rule concerns\n_implementation contracts_ (static operations a capability family exposes), not\n_runtime data values_ (legitimately dynamic -- an event payload's shape is\nunknown until it arrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the playbook\nengine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch time:\n\n| Name | Type | Source Line truncated
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a condition\ndeciding whether the action runs; (b) a later action's `args` values referencing\nan earlier action's `Result` and the triggering event's fields. Both are **CEL\nexpressions**, evaluated against one evaluation context. There is no separate\ninterpolation syntax: CEL reads nested maps and fields natively, so `args`\nvalues that need data are written as CEL, and only plain literal args remain\nplain YAML scalars.\n\nBoth halves are read-only: expressions may read context values and compute a\nresult from them, never mutate, never call host functions, never perform I/O.\nCEL enforces this structurally (no side effects, linear evaluation when macros\nare bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged** -- the\nsame tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's\ntrust-boundary section): loaded from a configured directory at startup, never\nfrom a webhook body or task worktree. The schema-by-example flow uses live\nevents to _design against_; the saved playbook is operator-authored file content\nin an operator-configured location.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not attacker\n input; no sandboxing against a hostile expression string is required. If a\n future playbook source is less trusted (auto-generated bindings from\n unauthenticated captures), that is the playbook-file trust tier moving -- the\n loader's acceptance check is the right place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook body, prior\n results through the same pipeline). Robustness against hostile data is\n required: no panic on wrong-typed/missing fields, no unbounded cost on\n deep/cyclic maps, bounded evaluation time. CEL provides this structurally\n (cost limits, linear non-Turing-complete evaluation, error values instead of\n panics -- verified in the vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)\nas the repo's conditional-logic precedent. That is the wrong precedent for\nplaybook conditions because this document's premise is: **YAML is pure\norchestration data; Yaegi is where imperative logic lives** (Problem section;\nmodule-position.md's \"no generic hook\" section). Yaegi snippets in YAML would\nmove imperative logic into the data layer -- the inversion this design exists to\nprevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data, not\nprograms**. CEL is non-Turing-complete and side-effect-free, so it cannot become\na program; a condition that needs real logic gets a Module kind (Yaegi),\nreferenced by the action, not a stronger expression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an `any`\npayload; it exists to keep static implementation contracts typed. Evaluating CEL\nagainst runtime `map[string]any` is **not the same problem**: the rule concerns\n_implementation contracts_ (static operations a capability family exposes), not\n_runtime data values_ (legitimately dynamic -- an event payload's shape is\nunknown until it arrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the playbook\nengine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch time:\n\n| Name | Type | Source |\n| --------- | ------------------------ | ---------------------------------------------------------------------------------Line truncated
},
{
"url": "/dev/prds/plugin-settings-live/",
"title": "Plugin settings reconcile live",
"section": "PRDs",
"body": "# Plugin settings reconcile live\n\n**Status:** Draft\n**Revision:** 2\n**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)\n**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how\nits changes take effect; `docs/architecture/plugins-and-extensions.md` owns the\nplugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply\nreports go.\n\n## Outcome\n\nAn operator drops a plugin, module or secret-engine file into a configured\ndirectory while archied runs, and the daemon loads it without a restart. An\nedit to an installed file replaces what is running. A delete never stops running\ncode; apply status says so. A stored `plugin-settings` change applies live for\n`plugin_dir`, `module_dir` and `secret_engine_dir`; a change to `skills_dir` is\nrefused.\n\n## Triggers\n\n`PluginSettingsKind` joins `runtimeResourceKinds` in\n`internal/app/archied/control_plane.go`, and its descriptor `ApplyMode` becomes\n`live` in `internal/app/controlplane/operational_settings.go`.\n\nA poller reconciles on the apply-status restamp interval, so a dropped file\nloads without a filesystem watch. Each tick re-runs both halves the boot path\nruns, against the directories in the running config: the directory loads\n(`secret.Registry.LoadDir`, `ModuleRegistry.Register`, `plugin.LoadDir`) and the\nlayering (`boot.runtimeConfig`), which re-resolves provider credentials. A\nprovider disabled at boot for an unresolvable engine is re-resolved on the first\ntick that finds it; a changed directory retargets the next tick without a\nrestart.\n\n## Rules\n\n- Adding and changing load; removing never unloads. Yaegi interpreters are not\n reclaimed while a caller still exists and there is no unload path; the running\n set can only grow. A removal stays outstanding in the apply-status error until\n the process restarts.\n- Each file is loaded through a fresh interpreter (the boot pattern) and\n content-hashed, so only new and changed files load.\n- A file that fails to load is skipped and reported; already-running code keeps\n running, the degrade-and-skip convention `plugin.LoadDir` and\n `Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule\n for the module directory; a broken file at runtime skips without aborting.\n- A directory that does not exist reconciles to an empty set.\n\n## The three registries\n\n- **Secret engines** (`internal/secret`). Reconciliation re-runs\n `Registry.LoadDir` against the live directory. `Register` replaces by name, so\n an edited engine takes effect for the next resolution and a dropped engine\n resolves on the next tick. A deleted engine stays registered: existing\n references keep resolving through it until restart. Engines are stateless\n resolvers, so a swap needs no lifecycle step.\n- **Modules** (`internal/domain/eda/module`). Reconciliation re-runs\n `ModuleRegistry.Register` for the kind's file. Playbook dispatch resolves\n through the registry at invoke time, so the swap reaches a running playbook\n store unchanged; a deleted file leaves the old invoker in place, running.\n- **Plugins** (`internal/plugin`). `Host` grows running-state operations beside\n `Register`, `Start` and `Stop`, and `Register` keeps its rule that\n registration is allowed only before the first `Start`, so these are new host\n methods rather than a relaxed `Register`. One adds a single module while the\n host is running: inserted in dependency order, started alone, and rolled back\n alone on failure, leaving every previously started module running. The other\n replaces a module whose manifest id matches: stop it, start the new one, and\n restart the old one when the new start fails; replacing a module another\n running module depends on is refused. A module's `Start` is its only check\n (`plugin.Module` has no probe, and one manifest id cannot be registered\n twice), so a replacement checks by starting and keeps a rollback rather than\n switching first. These operations obey the plugin engine rule: the host\n invokes start and stop itself and isolates the failure to one module. A\n deleted file makes no host call: the module runs on.\n\n## `skills_dir`\n\n`skills_dir` is not part of this change. The daemon refuses a `plugin-settings`\ndocument whose `skills_dir` differs from the value in force. The check is a\npre-layer comparison on the live path (`boot.applyRuntimeResourceUpdate` in\n`internal/app/archied/control_plane.go`), not an addition to\n`validatePluginSettings` in `internal/app/controlplane/operational_settings.go`,\nwhich stays value-agnostic per the #1143 decision recorded there: a\nchange-immutability rule needs the running config, and #1143's validates-nothing\nstill holds for values. The write lands, the store keeps the version, the daemon\npublishes nothing, the refusal is reported against that stored versLine truncated
},
{
"url": "/dev/prds/pr-review-agent/",
"title": "PR review agent",
"section": "PRDs",
"body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake,\n anatomy and diff, each able to read the repository:\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags.\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n nearLine truncated
"body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake\n (including its machine-written score), anatomy and diff, each able to read\n the repository. A PR that intake scores as likely machine-written adds a\n hallucination-check dimension: claims, citations and behaviour the diff\n does not actually implement.\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags. A reviewer\n that exhausts its turn cap or deadline before its terminal tool call\n records a distinct StepExecution status from a reviewer that completed\n and found nothing; synthesis and the posted review treat the two\n differently (the former is unreviewed, the latter is reviewed-clean).\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both endLine truncated
},
{
"url": "/dev/prds/pr-review-operator-response/",
"title": "PR review: the operator's answer to the approval gate",
"section": "PRDs",
"body": "# PR review: the operator's answer to the approval gate\n\n**Status:** Draft\n**Authority:** `docs/prds/pr-review-agent.md` (\"Operator approval\") for the gate, and `docs/prds/state-store-contract.md` (rev. 2e) for every task field that crosses the State Store.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a run cannot resume partway through its stage list).\n\n## Decision 1 — where the operator answers\n\nThe dashboard's `POST /api/tasks/{id}/action` (`internal/webui/api_tasks.go`, `handleTaskAction`) is the authoritative surface: the only one that resolves the actor from a credential and can carry a payload. Chat is a shortcut, not a second authority — `/approve` (`internal/gateway/gateway.go`, `Router.handleApprove`) answers the post decision with every offered finding selected, and gains no instruction or selection syntax.\n\n`taskstate.Action` gains `rereview`, and `taskstate.Actions` returns `approve`, `reject` and `rereview` for `WaitingHuman`. `approve` posts the review, `reject` discards it through the existing terminal decline, `rereview` reruns the review phases with instructions. The action body carries `instructions`, required by `rereview`, and `findings`, the finding keys `approve` posts; an absent selection means all of them.\n\nThe path is `handleTaskAction` → `applyOperatorTaskAction` → `Chat.Contract.ApplyOperatorTaskAction` → the daemon's `LocalChatAdapter` → `taskactions.Client` (NATS `archie.gateway.task-action`) → `taskactions.Service.Apply` → one guarded store write that records the decision and requeues. Chat's `/approve` path (`StoreTaskController.Approve` → `chatTaskControllerAdapter.ApproveChatTask`) must reach that same write through the same function, so the two surfaces cannot record different decisions for one operator intent.\n\nA requeue resumes the workflow the waiting state names, never a name the handler hardcodes. `taskactions.Service.apply` and `chatTaskControllerAdapter.ApproveChatTask` requeue with an empty workflow, which `Requeue` reads as \"keep the task's\", so neither surface hardcodes a workflow name: an approval whose wait recorded `pr-review` resumes `pr-review`. The feasibility handoff therefore has to name `implement` on the task before it enters the wait, which is the invariant the handler relies on — the workflow a task carries is the workflow it runs next. `Requeue` treats an empty workflow as \"keep the task's\".\n\n### The review the operator answers\n\nThe gate writes the review it is holding onto the task before it ends the run: one JSON column, `review_gate`, a sibling of `review_payload`, holding the scored findings, the head SHA, the pull request's identity and the workflow the wait resumes. The run's existing `Store.Update` persists it. The same column carries the answer back: the response path's guarded write fills in the outcome, the selection and the instructions, and clears the offer for a re-review.\n\nThe operator reads the offer through the existing task read — `taskView.Task` on `GET /api/tasks` and `GET /api/tasks/{id}/debug` — so no new read endpoint is needed.\n\nThis record is load-bearing because the run that computed the findings ends at the gate and the engine cannot resume it partway. Without it, \"post the selected findings\" cannot mean the findings the operator saw: the resumed run recomputes them with agent calls. An `approve` resume therefore posts the recorded review filtered by the selection, and the review the resumed phases recompute never reaches the output.\n\n## Decision 2 — the cap\n\nThe cap is a column: `rereview_rounds` on `tasks`, `bigint NOT NULL DEFAULT 0`, read by the response path and incremented in the same guarded write that requeues a re-review. A re-review at the cap is refused with the conflict sentinel the dashboard answers 409 with, and nothing is requeued. Two is a constant in the domain, not a config knob: the PRD fixes it.\n\n`Task.Attempt` cannot carry the count, because it counts every requeue. The two alternatives are worse.\n\n- The execution tree measures passes through the gate, not operator requests. A crash recovery (`RecoverStale`) or an operator retry re-runs the pipeline to the gate and would consume the cap; and a stage has no step read (`task.Store` carries none), so this route needs a new interface method anyway.\n- `Task.Notes` is the agent memory ledger, not scratch. `AgentStage.buildRequest` passes it into every generic agent request, `agentexec` renders it as a prompt section, and `persistAppendedNotes` appends to it. A counter parsed out of a field agents write to is the encoded-state defect this repository rejects, and instructions parked there would reach every unrelated workflow's agents.\n\n`RemediationRounds` is the precedent: one writer, one reader, one meaning, kept separate from `RetryCount` so unrelated retries cannot draw a budget down.\n\nThe write crosses the State Store. A goose migration adds the column; `Line truncated
},
{
"url": "/dev/prds/pr-review-remediation/",
@@ -444,11 +456,17 @@
"section": "PRDs",
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report _nothing_\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
},
{
"url": "/dev/prds/review-settings-resource/",
"title": "Review settings resource",
"section": "PRDs",
"body": "# Review settings resource\n\n**Status:** Draft\n**Beads issue:** `archie-core-0ry6`\n**Authority:** `docs/prds/runtime-control-plane.md` for the resource model,\n`docs/architecture/configuration.md` for ownership, and\n`docs/prds/pr-review-agent.md` for what the two dials do.\n\n## Decision\n\n`review.precision_gate` and `review.approve_before_post` are one control-plane\nresource, `review-settings`. The file's `[review]` section seeds it, the stored\ndocument outranks the file from then on, and the dashboard writes it through the\nsame settings machinery as every other resource.\n\nThe resource is deployment-wide, like every definition the State Store seeds\n(`storecontract.DefaultOrgID`): not per-repository, per-identity, or per-run.\n\n## Why its own kind\n\nThe two dials are pr-review policy — what a review may post, and whether a human\ndecides — not a limit on a task run. The document that carries task limits\nbelongs to that feature. `runtime-control-plane.md` splits settings by feature\nand refuses documents unrelated features share; `configuration.md` puts a typed\nruntime setting with the domain whose behaviour it describes. One document per\nfeature is the rule, not one document per settings page.\n\nA new kind also has no legacy documents. Its first value is the seed derived\nfrom the file, so \"the store outranks the file\" begins from an explicit copy of\nboth fields rather than from a document that predates them.\n\n## Document\n\nNew file `internal/app/controlplane/review_settings.go`:\n\n```go\nconst ReviewSettingsKind = \"review-settings\"\n\ntype reviewSettings struct {\n PrecisionGate bool `json:\"precision_gate\"`\n ApproveBeforePost bool `json:\"approve_before_post\"`\n}\n```\n\nIts `Definition` sets `ApplyMode: \"live\"`, `Document: reviewSettings{}`, and a\n`Seed` returning `reviewSettings{cfg.Review.PrecisionGate, cfg.Review.ApproveBeforePost}`,\nand a `Validate` wrapping `validateAs`: both fields are free booleans with no cross-field\nrule, so the validator is a named place to put one rather than an inline no-op\n(`validatePluginSettings` is the precedent). No `Normalize`, because the kind\nhas no second wire shape to converge.\n\n## Seeding\n\n`ImportConfig`/`seededValues` write the seed for a kind the store does not hold,\nso a deployment that never edited the dials runs the values in `[review]`. Once\na document is stored, the file key stops mattering, which is the rule for every\ndatabase-owned setting.\n\n## Apply\n\n`runtimeConfigFrom` in `internal/app/controlplane/runtime_config.go` layers the\nstored document over the file's `Review`, assigning `out.Review.PrecisionGate`\nand `out.Review.ApproveBeforePost` field by field. Field-by-field, not\n`out.Review = ...`: a field added to `config.Review` later keeps the file's value\nuntil the document carries it.\n\n`ReviewSettingsKind` joins `runtimeResourceKinds` in\n`internal/app/archied/control_plane.go`, so a new stored version re-runs the\nlayering and republishes through `config.Holder`. Live rather than\nrestart-required, because every consumer re-reads it: `Review` is on\n`reloadableFields` in `internal/app/archied/reload.go`, and the value reaches a\nrun through `Daemon.configFor` → `Config.ForTask` → `TaskConfig.ToConfig` →\n`TaskContext.Cfg`, which `stagePRPrecisionGate` and `stagePROperatorApproval`\nread. The next task run uses the new value; a run in flight keeps the value it\nstarted with.\n\n## Projection and page\n\n`BuildConfigView` gains a plain `Review` field carrying both values out of\n`cfg.Review`, the way `BudgetsView` carries the layered budgets, so the published\nconfig snapshot tells any reader what is in force. The Review page renders the\ntwo toggles from the control-plane store's draft for `review-settings` — the\nshape `SystemTasksPage.vue` uses for `workflow-execution-settings` — and shows\nthe projected value beside them; a Settings route plus a `PAGE_RESOURCES` entry\n(`ui/src/stores/control-plane.ts`) bind the page to the kind.\n\nNothing else re-advertises them. `configFieldDescriptors` and `ConfigView.Schema`\ngain no `review.*` row: the config catalog's generic renderer was deleted, so a\ndescriptor row adds a field nothing can edit, which is the shape `becb0b5e`\nremoved.\n\n## What the test proves\n\n`internal/app/controlplane/runtime_config_test.go` adds the round trip that\nbuilds the effective config the way boot does: seed the kind from a file config\nwith both dials set one way, store a document with both flipped, layer it\nthrough `runtimeConfigFrom`, and assert the effective `cfg.Review` equals the\nstored document. A second case covers the absent kind, where the file's values\nstay in effect. The assertion is on `cfg.Review` — the value `TaskContext.Cfg`\ncarries into the two stages — not on a struct the test set directly.\n`TestRuntimeResourceKindsApplyLive` gains `review-settings` as live. The\nvalidator needs no `validators_agree_test.goLine truncated
},
{
"url": "/dev/prds/runtime-control-plane/",
"title": "Runtime control plane",
"section": "PRDs",
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\n## API\n\nThe API has four operations:\n\n1. **Catalogue** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten. After migration, settings in TOML are\nignored and cannot block State Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nPlugins can add step types. Each run keeps the workflow version it started with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehaviour must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a Pinia-backed editor in the Web UI;\n- a messaging command using the same API;\n- migration of existing `[budgets]` values;\n- an end-to-end restart test.\n\nRunning tasks keep the limits they started with. New tasks use the latest applied\nversion. This replaces the old settings overlay instead of extending it.\n\n## Not included in the first implementation\n\n- Moving bootstrap or secret values into normal settings.\n- A generic JSON editor.\n- Rebuilding every settings screen at once.\n- Changing the limits of a running task.\n"
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\nThe request ID is the write's idempotency key, and it is scoped per org and\nper kind, never global. The key is `(org_id, kind, request_id)` — the unique\nindex `idx_resource_history_org_kind_request` (migration `0021_resources_per_org.sql`)\n— so replaying a request ID is the same org's prior write of the same kind, and\na request ID reused across orgs or across kinds is a separate write. This is the\nsame scoping as the task idempotency key `org/identity/owner/repo/number`\n(`docs/prds/orgs-and-access.md`).\n\n## API\n\nThe API has four operations:\n\n1. **Catalogue** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten, with one exception: a resource whose\ndocument the build ships is refreshed when the seed itself wrote the stored\ncopy, because that copy is a previous release's document rather than an\noperator's. After migration, settings in TOML are ignored and cannot block\nState Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nA step type is part of the build's step vocabulary, contributed as a provider at\nthe composition root; interpreted plugins contribute none\n(`docs/prds/workflow-step-vocabulary.md`). Each run keeps the workflow version it\nstarted with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehaviour must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a PiLine truncated
},
{
"url": "/dev/prds/self-update-transaction/",
@@ -480,6 +498,12 @@
"section": "PRDs",
"body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalisation only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalises trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalisation\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgement. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalisation, and prune is _reporting_\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalogue to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalogue through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval *Line truncated
},
{
"url": "/dev/prds/soul/",
"title": "SOUL: an agent's user-authored personality",
"section": "PRDs",
"body": "# SOUL: an agent's user-authored personality\n\n**Status:** Draft\n**Authority:** `docs/architecture/identity.md`, “Three-layer identity model”;\n`docs/prds/orgs-and-access.md` for identity and org ownership.\n\n## Decision\n\nSOUL supplies an agent's name, register and warmth. It belongs to the agent's\nimmutable `IdentityID`, not its session, model, installation or container\nprofile. Rename preserves it; changing a profile does not change who acts.\nSOUL never changes attribution, credentials, grants or identity lifecycle.\n`config.AgentProfile` remains an execution environment, not another identity.\n\nUse the existing three layers: invariants, user-authored SOUL, and curator-derived\nrepresentation. Curators may propose SOUL changes but never apply them.\n\n## Files and ownership\n\nThe config directory is `${XDG_CONFIG_HOME:-~/.config}/archie`, or the directory\nof an explicitly selected config file. The default/root agent uses `SOUL.md`\ndirectly there; additional agents use `agents/\u003cidentity-id\u003e/SOUL.md`. The root is\nthe identity selected by application composition, never the initiating user or\na session's personality selection. No file creates or selects an identity.\n\nThe common case keeps a human-friendly filename; additional agents get separate\nasset directories, following `.agents/skills/\u003cname\u003e/SKILL.md` without confusing\nthese directories with `[containers.profiles.\u003cname\u003e]`. Reject display-name or\nslug directories: rename and same-name agents across orgs would require another\nname-resolution rule. Immutable IDs avoid both problems without an org directory.\n\nWhen a file-owned agent's file is absent, create the shipped default with\nexclusive creation. Never overwrite an existing file, including an empty one.\nA creation failure still permits the turn using the embedded shipped default.\nShip that document independently of `agent.ShippedPersonas`, so deleting personas\ncannot delete the fallback.\n\nResolve once at the start of every new generation:\n\n1. A stored SOUL entry for the acting identity is authoritative.\n2. Without an entry, read that identity's file again.\n3. An absent, empty, unreadable or invalid selected source uses the shipped default.\n\nThe first explicit dashboard/API save takes ownership permanently. Thereafter\nfile edits are ignored: emit one ownership notice and show the owning stored\nversion in the dashboard. Restoring the shipped default writes a stored value;\nit does not remove ownership. Refuse writes that remove an owned entry.\n\nThis ownership boundary is the design's one stateful rule. Files seed the\neditable value, not an automatic durable import. Reject seed-once import because\nit breaks next-message file editing; reject file-always-wins because it makes\ndashboard saves ineffective. Neither a restart nor an upgrade overwrites an\nowned value, following the precedence of `controlplane.AgentProfileKind` without\ncopying its startup import timing.\n\n## Prompt and failure contract\n\nKeep `archie.md.tpl`'s XML-escaped\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block before\n`\u003cinstruction_precedence\u003e`. SOUL is style reference data; the invariant sections,\ntool inventory and runtime metadata remain authoritative and uneditable.\nPreserve `TestBuildSystemPromptSoulCannotOverrideInvariants`.\n\nAccept UTF-8 plain Markdown with at most 8 KiB in its XML-escaped body. This bounds\npersonality to a small prompt contribution; count the complete rendered prompt\nin the turn's context budget and never truncate invariant sections. Bound file\nreads before decoding; reject oversize input rather than truncating instructions.\nFile and stored writes use the same validator; an invalid save leaves the stored\nversion unchanged. The shipped default must pass that validator.\n\nRead and creation errors never fail a turn. Log once per identity/source failure\nepisode, retry on the next turn, and allow a new warning after recovery. If the\nstore cannot establish whether an owned entry exists, use the shipped default,\nnot a potentially shadowed file. Do not log SOUL text. Each turn keeps its resolved\nsnapshot; edits affect the next generation without restart or SIGHUP.\n\n## Cross-layer delivery\n\n- `internal/domain/agent` owns SOUL content validation and the identity-keyed read\n contract; `internal/domain/identity` remains the actor/lifecycle authority.\n- The configuration infrastructure resolves the config directory and handles\n file discovery, exclusive default creation and bounded per-turn reads.\n Application composition resolves the acting `IdentityID` through the existing\n identity repository/bindings and supplies it to the gateway.\n- Register `SoulKind` (`agent-souls`) in the control plane with a live descriptor\n and an org-scoped document mapping identity IDs to `{text}`. Persist it through\n the State Store's existing resource/history contracts, not a new table,\nLine truncated
},
{
"url": "/dev/prds/state-store-contract/",
"title": "State Store — contract boundary \u0026 transport (ratification)",
@@ -534,11 +558,23 @@
"section": "PRDs",
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per the\nenvironmental-enforcement principle (`docs/architecture/agent-system.md`,\n\"Existing invariants to preserve\"), the boundary is the gate and the sandbox,\nnot a sentence in the system prompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalised JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboarLine truncated
},
{
"url": "/dev/prds/workflow-call-outputs/",
"title": "Declared outputs of a workflow run",
"section": "PRDs",
"body": "# Declared outputs of a workflow run\n\n**Status:** Draft\n**Date:** 2026-09-30\n**Bead:** `archie-core-t2db.43`\n**Authority:** `docs/prds/event-automation.md` for what a declared output is,\n`docs/prds/workflow-calls.md` for the call and its grants,\n`docs/prds/state-store-contract.md` for the State Store contract the wire\nchange must satisfy.\n**Supersedes:** `docs/prds/workflow-calls.md`, \"Waiting on the callee\": the\ncallee's transition detail is the human summary, not the stand-in for\nstructured outputs.\n\nA workflow declares named, typed outputs. A run writes each one once. A\n`wait: true` caller receives them, and may publish one as its own.\n\n## Where outputs are declared\n\n`outputs:` on the workflow definition, beside `inputs:`, decoded into\n`task.WorkflowInterface.Outputs map[string]OutputSpec` where\n`OutputSpec{Type, Required}`:\n\n```yaml\nid: firewall-contain\noutputs:\n contained: { type: bool, required: true }\n summary: { type: string }\n```\n\nNames and types are the input grammar: the same identifier shape, the same\ntype set, and the same check in `WorkflowInterface.Validate`, which both\n`ParseDefinition` and `ParseWorkflowInterface` call.\n\n**Forced by:** `ParseDefinition` decodes with `KnownFields(true)`, so a key no\ndecoded struct declares is refused — the declaration must live on\n`WorkflowInterface` for an author to write it at all, and that is where\n`docs/development/workflows.md` puts every field a process without the engine\nmust read. The type set is the shared value vocabulary: `TypeAccepts` and\n`ValueType` already check a mapped parameter and an input with it. `required`\ndefaults to false, and the generated YAML for a builtin that declares no\noutputs is unchanged, because a definition's digest pins a run.\n\n**Rejected:** outputs per step, or per call step, because a workflow returns a\nresult as itself rather than as one of its stages. Also `task.Definition`\ngaining outputs: no reader needs them — a binding offers inputs, and a call's\noutputs assignment is checked against the callee's YAML in the same\ncollection — and a declared field with no reader parses and does nothing.\n\n## How a run writes one\n\nEach declared output is offered to the run's agent stages as a capture tool\nnamed after the output, whose arguments are `{\"value\": ...}`; the accepted\ncall's `value` member is the output's value. The engine holds the accepted\nvalues on the task context and writes them into its own task row in the\n`Store.Update` call the run already makes. A deterministic stage may set the\nsame values in Go, and the run's finish check validates them identically.\n\n**Forced by:** a run's only structured results are capture calls\n(`agentexec.CaptureTool`, `Result.Captures`), and the workflow interface\nalready declares when a stage needs them (`task.WorkflowNeeds.Captures`).\n`WorkflowInterface.Needs` reports `captures` for a non-empty `Outputs`, so\ndeclaring an output alone requires the capability and a Kit profile that\nserves no capture tools is refused before dispatch.\nDeriving the tools from the declaration means an output cannot be written\nunder a name nobody declared, and it keeps one route to structured agent\noutput rather than adding a second beside the capture path. The row write is\nthe run's existing write: the task row is where a run's own state lives, and\nthe container already holds `Update` on its own row.\n\nThe tool is offered with `MaxCalls: 1`, and a stage is not offered an output\nthe run has written, so a run writes each output once: a repeat within a stage\nis answered with the tool's rejection and the agent carries on, and a later\nstage cannot overwrite a value. A stage's own capture tool may not share a\nname with a declared output, because the value would otherwise be ambiguous.\n\n**Rejected:** a `workflow.output` step type, because assigning the run's\nresult from a step needs a grammar for \"the previous stage's result\" that does\nnot exist, and a step that reaches the agent would be the second path\n`docs/development/workflows.md` forbids. Also a write RPC of its own: the\ncontainer's `Update` already reaches its own row, and a second write verb for\none column is a second thing to keep in step.\n\n## How a caller receives one\n\nOn a successful `wait: true` call the caller's stage holds the callee's\noutputs as a `map[string]any`. A call step's `outputs:` setting publishes one\nas one of the caller's own outputs:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n wait: true\n inputs: { src_ip: inputs.src_ip }\n outputs: { contained: outputs.contained }\n```\n\nThe key names the callee's declared name; the value names one of the caller's\nown with the prefix the call's `inputs:` already uses. A published value joins\nthe caller's output set for its run, so a caller returns its callee's result to\nits own caller, and a run may publish a callee's output and write its own\notheLine truncated
},
{
"url": "/dev/prds/workflow-calls/",
"title": "Workflows calling workflows",
"section": "PRDs",
"body": "# Workflows calling workflows\n\n**Status:** Draft\n**Date:** 2026-09-26\n**Bead:** `archie-core-t2db.41`\n**Extends:** `docs/prds/event-automation.md` (workflow/binding/profile model), `docs/prds/state-store-contract.md` (two new RPCs), `docs/prds/execution-tree-state-machine.md` (call kind)\n\n## The call, end to end\n\n```\ncaller run (in agent container)\n workflow.call step ──StartCall──▶ State Store EnqueueCallTask(caller, workflow, inputs)\n │ callee task row: org/identity/owner/repo\n │ derived from the caller row server-side\n ▼\n callee task (queued, org of the caller)\n │ daemon claims, pins the callee's OWN\n │ definition → its OWN agent profile\n ▼\n callee run (its own container, own tree)\n wait: true ──poll──▶ State Store WorkflowCallStatus(caller, callee)\n wait: false ──continue\n```\n\nA `workflow.call` step starts the callee as a first-class task and, with\n`wait: true`, waits for its terminal state. The callee is never run \"inside\"\nthe caller: it gets its own task row, its own pinned definition, its own\nprofile, its own container, and its own outcome on its own run\n(`execution-tree-state-machine.md`).\n\n## Save-time checks (the collection is the authority)\n\nAll semantic checks run in `workflow.ValidateDefinitionCollection`, the gate\nevery save and load of the `workflow-definitions` resource passes through.\nA single-definition parse cannot see callees, so it validates shape only.\n\n- **Callee exists.** A call to a workflow outside the collection is refused.\n- **Inputs checked.** A call value is a literal or a reference\n (`inputs.\u003cname\u003e`) to the calling workflow's declared input. References must\n name a declared input; the resolved type must satisfy the callee's declared\n type; unknown callee inputs are refused; a required callee input must be\n assigned.\n- **Self-calls refused.** The call graph over the collection is walked from\n every workflow; a workflow that reaches itself, directly or through other\n workflows, is refused with the cycle path. (Cycles can otherwise deadlock:\n `wait: true` callers hold their containers.)\n- **Repository.** `workflow.call` needs no repository, so it is legal in a\n `repository: none` workflow: the callee inherits the caller's task record\n (owner/repo/identity/org), and the callee's own `repository` mode decides\n whether its run clones.\n- **Org enablement** (bead `archie-core-t2db.42`): the single\n instance-wide collection the current model serves is what \"enabled for\n the caller's org\" resolves against — an undefined callee parks. The\n callee's org is derived from the caller's row, so a callee is never\n visible outside its caller's org. The per-org enable/disable catalogue\n lands with `archie-core-t2db.42` and becomes the one source of this\n predicate.\n\n## Runtime\n\n**Depth limit.** `workflow.MaxCallDepth` (5). The calling stage refuses a call\nthat would exceed it; the store re-checks on insert (callee depth = caller\ndepth + 1), so no path can enqueue past the limit.\n\n**Starting the callee.** The caller runs inside a container whose task-scoped\nState Store grant authorizes only `Update`/`Transition`/`InsertEvent` on its\nown task — it can neither enqueue a task nor read another one. One new\ncontract RPC starts the callee:\n\n- `EnqueueCallTask(caller_task_id, workflow, inputs_json) → task`\n — the store reads the caller row, refuses a caller that is not `running`,\n refuses past the depth limit, and inserts the callee row deriving org,\n workspace, identity, owner, repo and a fresh synthetic issue number from\n the caller (the same org COALESCE `EnqueueIssue`/`InsertChatTask` use). The\n callee row carries `call_parent_task_id` and `call_depth`.\n\n**Waiting on the callee.** One new read RPC returns a call's callee:\n\n- `WorkflowCallStatus(caller_task_id, call_task_id) → (status, detail)` — the\n handler verifies `call_parent_task_id` matches, so a caller reads only its\n own callees, and returns the callee's status plus its latest transition\n detail (the callee's summary — the wait:true \"outputs\" until a structured\n outputs model lands).\n\nBoth RPCs are admitted to task-scoped grants on `caller_task_id == granted\ntask ID` (`authorizesTaskScopedCall` gains two request-shape cases). This is\nthe one sanctioned widening of a task grant: the callee is the caller's child,\nand starting it is the mechanism by which one event becomes several runs. The\nwidenings stay request-shape checks; the parent-child authorization is a\nhandler-side row check, so the interceptor never reads the database.\n\n**Schema.** `tasks` gains Line truncated
},
{
"url": "/dev/prds/workflow-step-vocabulary/",
"title": "Workflow step vocabulary: what a step type is and how binaries agree on it",
"section": "PRDs",
"body": "# Workflow step vocabulary: what a step type is and how binaries agree on it\n\n**Status:** Draft\n**Date:** 2026-09-29\n**Beads:** `archie-core-m7oc` (agreement between separately deployed binaries), `archie-core-ze7y` (the deleted `.archie/stages/*.go` equivalent)\n**Extends:** `docs/architecture/plugins-and-extensions.md` (plugin engine rule), `docs/prds/event-automation.md` (the workflow model step types serve)\n\n**Authority:** `docs/architecture/plugins-and-extensions.md` — the workflow step vocabulary is a Workflow capability family, and its extension point follows the plugin engine rule.\n\n## Decision\n\nA workflow step type is a named Go factory: the word a YAML workflow writes in\na step's `type` field, plus the factory that builds its stage. The name is a\nstable identifier; the identity also declares what plugin family claims it,\nso a contribution that shadows a shipped stage is refused instead of\noverriding it.\n\nThe Workflow domain owns the typed family contract — `StepTypeProvider` for a\ncontribution and `Manager` as the owning registry. A provider contributes a\nwhole set of step types under its own stable-identifier name; the manager\nvalidates the entire contribution before applying any of it (named provider,\nwell-formed step-type names, non-nil factories, no step type claimed twice,\nno claim on a name another provider holds) and applies it atomically. The\ngeneric `plugin.Plugin` contract stays metadata-only.\n\nThe vocabulary is a compiled-in, closed set. `internal/infrastructure/workflowsteps`\nis the one place a step type is bundled into any binary that resolves one: the\nshipped workflow stages, the repository-hook replacements (`gate.diff-rules`)\nand the repository-free event steps each arrive as one provider, and adding a\nstep type means adding a provider to that set. Interpreted plugin sources\ncannot contribute step types: the Yaegi plugin host satisfies only the\nmetadata contract, and no bridge to `StepFactory` exists.\n\nEvery binary that resolves a step type builds its manager from that same\nprovider set at its composition root, before its first resolution, and\ninjects the manager everywhere it resolves definitions. Agreement is per\nbuild: the State Store, the daemon's workflow-definitions client and the agent\nworker built from the same source register identical vocabularies by\nconstruction; binaries built from different sources can disagree, and only a\nmatching deploy fixes that.\n\nAn unknown step type is refused twice, and never degraded. The validator\n`ParseDefinition` refuses a definition naming an unregistered type at save\ntime, on the validating side the composition root built (the State Store's\nworkflow-definitions resource validates there before anything is stored). The\ncompiler refuses the same definition at run, so a binary handed a definition\nwritten against a vocabulary it does not have fails that run loudly instead of\nsilently skipping steps. Both checks live in the Workflow domain against the\ninjected manager, which is why no binary can opt out of the check by\nsubstituting its own registry.\n\n## Relationship between the questions\n\n`archie-core-ze7y` is the same question seen from the deleted\nrepository-authored stages: those `.archie/stages/*.go` files held arbitrary\nstages, and their gate half landed as `gate.diff-rules` settings rather\nthan interpreted Go. Their stage half has no replacement and does not get one\nthat approximates it: no interpreted-Go stage type is built, and no command\nstep type is created by this decision to stand in for them. The refusal of\n`.archie/stages/*.go` stays until the maintainer's trust decision\n(`archie-core-ndm8`) says otherwise.\n\nIf that decision ever allows a command step type, it arrives as a provider in\nthe compiled-in set under the rules above — a new contributor of exactly one\nstep type at a named provider. It is not a plugin contribution mechanism, and\nit does not change any answer in this document.\n\n## Rejected alternatives\n\n- **A vocabulary version or hash on the wire.** The executing side already\n refuses an unknown step type at its first compile, which is the mismatch\n detector, and it fails closed. A wire field would only narrow the\n deploy-skew window that a matching deploy closes, at the cost of a new\n contract field.\n- **A Yaegi-plugin-to-`StepFactory` bridge.** It would run repository-supplied\n interpreted code inside the daemon's process with daemon privileges. The\n trust boundary invariant requires repository-authored code to run in the\n task container, not in an interpreter embeddable into any binary.\n- **A package-level process-global registrar.** Global mutable registry state\n is unreadable at the composition root, collides with itself when one\n process builds the vocabulary twice, and is what made the first attempt at\n this question worse instead of better.\n- **Degrading on an unknown step type.** A run that skips steps iLine truncated
}
],
"nav": [
@@ -821,10 +857,18 @@
"title": "Playbook data-flow and condition syntax",
"url": "/dev/prds/playbook-expression-syntax/"
},
{
"title": "Plugin settings reconcile live",
"url": "/dev/prds/plugin-settings-live/"
},
{
"title": "PR review agent",
"url": "/dev/prds/pr-review-agent/"
},
{
"title": "PR review: the operator's answer to the approval gate",
"url": "/dev/prds/pr-review-operator-response/"
},
{
"title": "PR review comment remediation -- decision",
"url": "/dev/prds/pr-review-remediation/"
@@ -845,6 +889,10 @@
"title": "Review calibration -- decision",
"url": "/dev/prds/review-calibration/"
},
{
"title": "Review settings resource",
"url": "/dev/prds/review-settings-resource/"
},
{
"title": "Runtime control plane",
"url": "/dev/prds/runtime-control-plane/"
@@ -869,6 +917,10 @@
"title": "Skill curator (reference implementation) -- decision",
"url": "/dev/prds/skill-curator/"
},
{
"title": "SOUL: an agent's user-authored personality",
"url": "/dev/prds/soul/"
},
{
"title": "State Store — contract boundary \u0026 transport (ratification)",
"url": "/dev/prds/state-store-contract/"
@@ -905,9 +957,17 @@
"title": "Webhook intake security -- decision",
"url": "/dev/prds/webhook-intake-security/"
},
{
"title": "Declared outputs of a workflow run",
"url": "/dev/prds/workflow-call-outputs/"
},
{
"title": "Workflows calling workflows",
"url": "/dev/prds/workflow-calls/"
},
{
"title": "Workflow step vocabulary: what a step type is and how binaries agree on it",
"url": "/dev/prds/workflow-step-vocabulary/"
}
]
}
+10
View File
@@ -11,6 +11,12 @@
"title": "Building your first playbook binding",
"section": "Guides",
"body": "# Building your first playbook binding\n\nThis walks through the whole no-code path the event-capture epic promises:\npoint an external app's webhook at archie, see the real payload it sends,\nmap the fields you care about, bind them to a workflow, and watch the next\nmatching event turn into a task -- no code, no redeploy, no restart. See\n`docs/architecture/bindings.md` for the model and threat model behind each\nstep below.\n\n## 1. Send a test event\n\nPoint whatever external app you want archie to react to at:\n\n```\nPOST http://\u003cyour-archied-host\u003e:8484/webhooks/capture/\u003csource\u003e\n```\n\n`\u003csource\u003e` is a name you choose for this sender (e.g. `sentry`, `github-ci`,\n`stripe`) -- it's just a URL path segment, not a preset list. Send one real\nevent however is easiest for a first test, e.g.:\n\n```bash\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -d '{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\n```\n\nThis event isn't signed yet, so it's captured but marked **unauthenticated**\n-- visible for you to design against, but incapable of triggering anything\n(`docs/architecture/bindings.md`'s threat-model section explains why: an\nunauthenticated event can never match a binding, no matter how it looks).\n\n## 2. Inspect the captured payload\n\nOpen the dashboard's **Event inspector** (`/captures`). Your test event\nappears there with its real body -- this is schema-by-example: you're\nlooking at an actual payload from the actual sender, not guessing at a\nschema in advance.\n\n## 3. Map the fields you care about\n\nOpen **Field mappings** (`/mappings`) → **New mapping**. Pick your captured\nevent from the dropdown, then click through its payload tree on the right --\nevery key and value is clickable. Clicking a value binds it as a field\n(name, JSON path, and an inferred type you can change). Add whichever fields\nyour workflow needs (e.g. the issue title), mark the ones that must be\npresent as **Required**, hit **Preview** to confirm they resolve correctly\nagainst the real payload, then **Save**.\n\n## 4. Create the binding\n\nOpen **Playbook bindings** (`/bindings`) → **New binding**:\n\n- **Name** -- anything descriptive.\n- **Source** -- the same `\u003csource\u003e` segment from step 1 (e.g. `sentry`).\n- **Field mapping** -- the one you just saved.\n- **Workflow** -- which registered workflow should run on a match.\n- **Repo pin** (optional) -- leave both blank to use the single configured\n repo; set owner/repo explicitly if you run a multi-repo deployment.\n- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The\n sender signs every request body with this via HMAC-SHA256 so archie can\n tell a genuine event from anyone who finds the URL.\n\nSave. The binding starts in **draft** -- nothing fires yet.\n\n## 5. Approve it\n\nA **draft** or freshly-**edited** binding needs an explicit human approval\nbefore it can ever match a live event -- this is deliberate, not a missing\nstep: an operator authoring a binding is a considered act, an event arriving\nis not, and nothing should self-arm (`docs/architecture/bindings.md`'s\nthreat-model section, point 2). Click **Approve**. Status becomes **armed**.\n\n## 6. Fire it for real\n\nSend the same kind of event again, this time **signed** with the binding's\nsecret:\n\n```bash\nBODY='{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\nSECRET=\"the-secret-you-set-in-step-4\"\nSIG=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" | sed 's/^.* //')\n\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Hub-Signature-256: sha256=$SIG\" \\\n -d \"$BODY\"\n```\n\nThis event is captured as **authenticated**, matched against your armed\nbinding, and dispatched into a new task through the exact same\ngate/worktree/sandbox pipeline every other task goes through -- see\n`docs/architecture/messaging-and-work-intake.md`'s \"Intake provenance\". Check\nthe **Tasks** page; a new task should appear, its body built from the fields\nyour mapping resolved.\n\n## Editing a live binding\n\nAny edit to an armed binding -- even a typo fix -- drops it back to\n**pending_approval** automatically. This can't be bypassed by editing; it\nhas to be re-approved. When editing, leave the **Shared secret** field blank\nto keep the existing secret; only fill it in if you're deliberately\nrotating it.\n"
},
{
"url": "/docs/guides/pr-review-benchmark/",
"title": "PR review benchmark",
"section": "Guides",
"body": "# PR review benchmark\n\nRun `scripts/pr-review-benchmark.sh` with `PRBENCH_REVIEW_MODEL` and\n`PRBENCH_CLASSIFICATION_MODEL` set to configured `provider/model` references.\nThe judge defaults to `anthropic/claude-sonnet-4.6`; set\n`PRBENCH_JUDGE_MODEL` to another configured model when needed. The script uses\n`~/.config/archie/config.toml` for providers and `GH_TOKEN` or `GITHUB_TOKEN`\nfor read access to the benchmark pull requests. It posts no forge review.\n\nThe default run reviews the 38 runnable Martian pull requests once each at\n`deep`, judges the comments against 102 golden comments, and writes\n`bin/prbench-results/run.json`, `summary.json`, and one JSON result per pull\nrequest. That output directory is ignored by git. A completed full run fails\nwhen any problem fails or golden micro-recall is below 0.70. Golden-only\nprecision is reported alongside recall. Set `PRBENCH_OUT` to keep separate\nruns; `-problems ID` limits a smoke run to one pull request. Completed results\nare saved as each PR finishes. Pass `-resume DIR` to reuse completed results\nfrom a run with the same models; each reused problem must match the current\nbenchmark entry, and failed problems are rerun.\nA smoke run alone is not the acceptance run.\n\nThe benchmark passes only each problem's ID and pull request URL to the\nreviewer. The judge receives the golden comments after the review has ended.\nThe runner uses the production decision phases through the merge gate,\nincluding scoring and the 25-comment cap, then stops before polish and forge\nposting. A reviewer that fails to finish makes that problem fail. The results\nrecord budget-skipped phases and the selected models. Model substitutions do\nnot satisfy the PRD's named-model criterion even if recall clears the threshold.\n"
}
],
"nav": [
@@ -24,6 +30,10 @@
{
"title": "Building your first playbook binding",
"url": "/docs/guides/first-playbook/"
},
{
"title": "PR review benchmark",
"url": "/docs/guides/pr-review-benchmark/"
}
]
}
+6 -1
View File
@@ -17,7 +17,12 @@ that reads it and the path the value takes to get there.
channels, containers). The file only seeds it. Once the State Store holds the
control-plane resource, the stored document is layered over the file
(`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is
checked by `validateDatabaseOwned` and by the resource's validator.
checked by `validateDatabaseOwned` and by the resource's validator. A stored
value is refreshed from the file only when the store has no value for the kind
at all; a kind that ships a document of its own (workflow definitions,
personas) is refreshed whenever the seed itself wrote the stored copy, since
that copy is a previous release's document rather than an operator's
(`controlplane.Server.seedKind`).
- **Worker-carried.** A value the agent container needs travels in
`config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it
as an environment variable the daemon did not already define, and never carry
+3 -2
View File
@@ -28,8 +28,9 @@ Authority: `docs/architecture/agent-system.md`. The status vocabulary lives in
Follow [State Store](state-store.md) for the
column and the wire. Then decide who writes it: `UpdateTask` writes a fixed
column set, so a field set at enqueue needs its own statement (as
`StampTaskBinding` does for binding provenance and inputs).
column set, so a field set at enqueue belongs in the insert that creates the
row (as `InsertChatTask` does for inputs), or in its own statement when only
some producers set it (as `StampTaskBinding` does for binding provenance).
### Changing what the agent receives
+53
View File
@@ -31,6 +31,59 @@ should look.
after visiting Settings and Logs: the UI process serves HTTP/1.1 and six
persistent streams can starve every later browser request.
## Testing the dashboard
Authority: the runner itself is `ui/package.json`'s `test` script: `node --test
--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs
pure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM,
no second dependency beyond what the app already carries. That is the standard,
and a decision record for when it is deliberately not enough:
- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes,
draft state, copy conditions, filters and payload building live in plain
`.ts` files beside the components and are tested in `ui/test/`. Components
stay thin, so there is normally nothing in an SFC that is archie logic.
- **A dashboard rule that mirrors a server rule is pinned by a shared
fixture, not two independent tests.** `ui/src/settings/validation.ts`
hand-mirrors three control-plane validators, and the model-role rule had
already drifted because nothing tied the two sides together. Each case now
lives once in `internal/app/controlplane/testdata/dashboard-validators.json`:
a Go test in that package runs the real server validators over it, and
`ui/test/control-plane-validator-parity.test.ts` runs the real dashboard
validators over the same cases. Changing one rule alone fails the other
side's test. Add a case to the fixture, never to one side only.
- **Installed primitives are upstream-tested, not re-tested here.**
`reka-ui` (2.10.5 here) maintains colocated tests per component in its own
repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the
arrow-navigation composables). The npm package ships none of those files, so
this coverage is inherited through the version bound, not the tarball —
`grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local
mount tests would test a dependency.
- **A `.vue` import cannot run under the module runner.** `node --test` fails
such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no
built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is
therefore a broken test, not a weak one.
- **If a DOM mount harness is ever needed** (a page-level accessibility
contract, cross-component interaction, focus behaviour): `happy-dom` +
`@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the
module runner for everything else. Measured on the ui tree (vitest 5.0.2,
happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level
`node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount
suite (role=radiogroup vs role=switch, aria-label, click activation against
the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and
`vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner
alternative (absorbing the existing suite into vitest) was measured
infeasible as-is: all 29 existing files import `node:test`, which vitest
cannot collect ("No test suite found in file" for every one), so it would be
a rewrite of the whole suite, and its runtime was not measured. Nothing in
`ui/dist` or CI changes either way; happy-dom is pure JS, no browser binary.
- **What the module standard does not verify:** whether a call site passes an
`aria-label` or which `v-if` branch shows. Those live in SFC templates and
are only visible with a mount. If a page's accessible-name wiring is the
risk, say so in the page's task and reach for the harness decision above
rather than quietly growing mount tests. Never suppress a lint rule or a
test to keep SFC behaviour out of the gate.
## Adding an API route
1. The handler goes in the `internal/webui/api_<concern>.go` file for its
+7 -3
View File
@@ -34,9 +34,13 @@ restating them.
index, so stage regenerated contracts before running it.
- Stage by path, or read `git status` before `git add -A`. Tests that start
embedded NATS or write logs must use `t.TempDir()`; anything they leave in the
tree gets committed. `task check` also adds linter-tool lines to `go.sum`
(bead 1e37); restore `go.sum` before committing unless you changed a
dependency.
tree gets committed. `task check` writes no module file on a consistent tree,
root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`):
a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or
`updates to go.mod needed`, rather than being repaired. Only a global
`GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the
`go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run
`go mod tidy` and commit the result on its own.
- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**
carries the regenerated `docs/data/generated/dev-docs.json`: run
`task docs:artifact` (not `task docs:check`, which checks contracts only).
+35
View File
@@ -28,6 +28,19 @@ vocabulary it registers, so both must see the same step types.
6. Add a parse test (settings accepted and refused) and a run test with fake
`Trees` and agent runner.
## Retiring a step type
A step word cannot simply be deleted. A stored or pinned definition is
validated as a whole collection, so one unknown word fails EVERY workflow's
definition to decode and the workflow-definitions resource becomes unreadable.
Retire a stage by removing it from its workflow's `Stages` and adding it to
`retiredSteps` in `definition.go`, which keeps the word resolving as an inert
stage. The retired stage must do nothing: the behaviour it used to perform now
belongs to whatever layer took it over (the remediate workflow's in-container
resume moved to daemon worktree preparation, `archie-core-866m`; the workflow
still binds the daemon-prepared directory and the PR branch in a `prepare`
stage before any agent work).
## Changing the definition format
- The fields a caller needs without the engine (inputs, repository, profile)
@@ -37,5 +50,27 @@ vocabulary it registers, so both must see the same step types.
- The YAML decoder rejects unknown keys. Existing stored definitions must keep
parsing, so a new key is optional with a default that preserves today's
behaviour.
- A declared `outputs:` entry is written through a capture tool, so it forces
the captures need: `task.WorkflowInterface.Needs` resolves that from the
declaration rather than the author also writing `needs.captures`. A Kit
profile whose harness serves no capture tools is refused before dispatch.
- Examples in `examples/workflows/` are parsed against the registered
vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.
## Enabling and disabling
The `workflow-enablement` control-plane resource lists, per org, the workflows
that org has disabled; anything unlisted is enabled. Its readers are the
daemon's binding dispatch (a disabled workflow's binding is skipped like an
unarmed one), the dashboard's binding save (refused) and binding list
(`workflow_disabled`), and work requests. A new reader of "may this org run
this workflow" goes through `task.WorkflowEnablement.Enabled`, never a second
list. The dashboard acts in the default org until access resolves a caller's
own.
## Starting a workflow from chat
`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards
inputs through the task creation contract; it does not interpret individual
workflows. The daemon checks inputs against the pinned `WorkflowInterface`
before acquiring a container and parks invalid requests with the reason.
+28
View File
@@ -0,0 +1,28 @@
# PR review benchmark
Run `scripts/pr-review-benchmark.sh` with `PRBENCH_REVIEW_MODEL` and
`PRBENCH_CLASSIFICATION_MODEL` set to configured `provider/model` references.
The judge defaults to `anthropic/claude-sonnet-4.6`; set
`PRBENCH_JUDGE_MODEL` to another configured model when needed. The script uses
`~/.config/archie/config.toml` for providers and `GH_TOKEN` or `GITHUB_TOKEN`
for read access to the benchmark pull requests. It posts no forge review.
The default run reviews the 38 runnable Martian pull requests once each at
`deep`, judges the comments against 102 golden comments, and writes
`bin/prbench-results/run.json`, `summary.json`, and one JSON result per pull
request. That output directory is ignored by git. A completed full run fails
when any problem fails or golden micro-recall is below 0.70. Golden-only
precision is reported alongside recall. Set `PRBENCH_OUT` to keep separate
runs; `-problems ID` limits a smoke run to one pull request. Completed results
are saved as each PR finishes. Pass `-resume DIR` to reuse completed results
from a run with the same models; each reused problem must match the current
benchmark entry, and failed problems are rerun.
A smoke run alone is not the acceptance run.
The benchmark passes only each problem's ID and pull request URL to the
reviewer. The judge receives the golden comments after the review has ended.
The runner uses the production decision phases through the merge gate,
including scoring and the 25-comment cap, then stops before polish and forge
posting. A reviewer that fails to finish makes that problem fail. The results
record budget-skipped phases and the selected models. Model substitutions do
not satisfy the PRD's named-model criterion even if recall clears the threshold.
+8
View File
@@ -57,6 +57,10 @@
"/news/archie/1.41.2/": "/news/1.41.2/",
"/news/archie/1.42.0/": "/news/1.42.0/",
"/news/archie/1.43.0/": "/news/1.43.0/",
"/news/archie/1.44.0/": "/news/1.44.0/",
"/news/archie/1.44.1/": "/news/1.44.1/",
"/news/archie/1.45.0/": "/news/1.45.0/",
"/news/archie/1.46.0/": "/news/1.46.0/",
"/news/archie/1.5.0/": "/news/1.5.0/",
"/news/archie/1.6.0/": "/news/1.6.0/",
"/news/archie/1.7.0/": "/news/1.7.0/",
@@ -131,6 +135,10 @@
"/news/archied/1.41.2/": "/news/1.41.2/",
"/news/archied/1.42.0/": "/news/1.42.0/",
"/news/archied/1.43.0/": "/news/1.43.0/",
"/news/archied/1.44.0/": "/news/1.44.0/",
"/news/archied/1.44.1/": "/news/1.44.1/",
"/news/archied/1.45.0/": "/news/1.45.0/",
"/news/archied/1.46.0/": "/news/1.46.0/",
"/news/archied/1.5.0/": "/news/1.5.0/",
"/news/archied/1.6.0/": "/news/1.6.0/",
"/news/archied/1.7.0/": "/news/1.7.0/",
+20
View File
@@ -1,4 +1,24 @@
[
{
"version": "1.46.0",
"date": "2026-10-02",
"body": "### archied\n\n- feat(workflow): declared workflow outputs for wait:true callers\n- feat(prreview): the operator-approval gate is PRReview's own stage-list entry\n- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write\n- feat(prreview): the gate records the review it holds and posts the operator's answer\n- feat(taskactions): one approval path answers the review gate from every surface\n- feat(webui): the dashboard answers the review gate, including a re-review's instructions\n- feat(daemon): resolve the producing identity's org before publishing work\n- feat(webui): block invalid settings and show a field's former value\n- fix(workflow): derive a declared output's captures need for profile selection\n- fix(storepkg): validate every declared authority grant at the package descriptor\n- feat(archied): refresh the model catalog at runtime\n- feat(mcp): answer server-initiated sampling from the chat model\n- feat(container): send registry auth on image pull\n- feat(messaging): retract ephemeral replies after their TTL\n- feat(messaging): transcribe Telegram voice notes\n- fix(egress): take a run's credential kind from its binding, not the Kit\n- feat(webui): a live-apply setting reads as applied, never as a restart\n- feat(webui): the dashboard reads harness bindings and opens the setup terminal\n- feat(gateway): list the harness page in the dashboard page registry\n- feat(webui): the harness settings page and its setup terminal\n- fix(workflow): park environment gate failures without dispatching a builder\n- feat(messaging): adapter-facing clarify, picker and approval contract\n- feat(gateway): gate admin slash commands by sender policy\n- feat(plugins): load plugin and secret-engine files without a restart\n- fix(workflow): deliver the feasibility PRD to the forge issue\n- fix(messaging): report the daemon version this process was built from\n- fix(messaging): carry an inbound attachment's bytes to the gateway turn\n- fix(daemon): resume a retry whose worktree is gone\n- fix(archied): omit the max-token bound on reasoning-class models\n- fix(logging): file a task log record under its own event time\n- fix(control-plane): unify validation for the domain-managed kinds\n- feat(webui): let the operator choose the retry worktree mode\n- feat(agent): seed a starter SOUL and upgrade only untouched templates\n- feat(controlplane): add the writable review-settings resource\n- fix(messaging): transcribe voice notes on the model-owning side of the boundary\n- fix(messaging): gate the boundary on config reads, not only package links\n- feat(messaging): restart only the channel whose settings changed\n- feat(container): apply container-runtime-policies live\n- feat(tools): reconcile MCP servers and tool settings live\n- feat(messaging): add a per-turn interactive carrier for clarify and picker\n- feat(gateway): offer ask_user when the turn's channel can carry a question\n- feat(telegram): carry clarify and picker through the text fallback\n- fix(webui): pin the dashboard validators to the control plane's\n- refactor(agent): drop the SOUL upgrade branch with no shipped template\n- feat(agentworker): answer MCP sampling from the task's model\n- fix(workflow): bind the remediate worktree before the builder runs\n- fix(config): carry max_retries into the worker TaskConfig snapshot\n- fix(agentworker): supply the guardrail engine to every task run\n\n### archie-agent\n\n- feat(workflow): declared workflow outputs for wait:true callers\n- feat(prreview): the operator-approval gate is PRReview's own stage-list entry\n- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write\n- feat(prreview): the gate records the review it holds and posts the operator's answer\n- feat(taskactions): one approval path answers the review gate from every surface\n- fix(workflow): derive a declared output's captures need for profile selection\n- fix(storepkg): validate every declared authority grant at the package descriptor\n- feat(mcp): answer server-initiated sampling from the chat model\n- feat(container): send registry auth on image pull\n- feat(messaging): retract ephemeral replies after their TTL\n- feat(messaging): transcribe Telegram voice notes\n- fix(egress): take a run's credential kind from its binding, not the Kit\n- fix(workflow): park environment gate failures without dispatching a builder\n- feat(messaging): adapter-facing clarify, picker and approval contract\n- feat(plugins): load plugin and secret-engine files without a restart\n- fix(workflow): deliver the feasibility PRD to the forge issue\n- fix(messaging): carry an inbound attachment's bytes to the gateway turn\n- fix(daemon): resume a retry whose worktree is gone\n- fix(logging): file a task log record under its own event time\n- fix(control-plane): unify validation for the domain-managed kinds\n- feat(webui): let the operator choose the retry worktree mode\n- fix(messaging): transcribe Line truncated
},
{
"version": "1.45.0",
"date": "2026-09-30",
"body": "### archied\n\n- fix(eda): reject a result map missing a field or needing a conversion\n- feat(eda): per-org workflow enable/disable gating bindings\n- feat(telegram): carry inbound media through the chat turn\n- fix(prsource): use a CodeQL-recognised containment guard when extracting archives\n- feat(store): key control-plane resources by (org, kind)\n- fix(store): refuse resource keys the audit key cannot disambiguate\n- fix(daemon): resume the task branch before container acquisition\n- feat(webui): show attachment metadata in the session transcript\n- feat(webui): name a workflow's declared inputs on the work-request form\n- feat(controlplane): carry the caller org from the request principal\n- fix(webui): the workflow handlers act in the caller's org\n- feat(kitrun): render the OAuth credential file with sentinels\n- feat(store): record accepted package authority against the pin\n- fix(workflow): the own-PR flow no longer parks on the operator-approval gate\n- feat(gateway): a TTL-bounded dedup gate for redelivered platform messages\n- feat(egress): capture the OAuth scope set and carry it to the harness secret\n- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key\n- feat(store): project installed package contributions into org resources\n- feat(gateway): coalesce rapid-fire text events into one turn\n- fix(config): expand plugin, module and skills dirs like every other operator path\n- fix(webui): drop the config schema's editability advert\n- feat(webui): events counts, YAML reading, log rows and dashboard filters\n\n### archie-agent\n\n- feat(eda): per-org workflow enable/disable gating bindings\n- feat(telegram): carry inbound media through the chat turn\n- fix(prsource): use a CodeQL-recognised containment guard when extracting archives\n- feat(store): key control-plane resources by (org, kind)\n- feat(controlplane): carry the caller org from the request principal\n- feat(kitrun): render the OAuth credential file with sentinels\n- feat(store): record accepted package authority against the pin\n- fix(workflow): the own-PR flow no longer parks on the operator-approval gate\n- feat(egress): capture the OAuth scope set and carry it to the harness secret\n- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key\n- feat(store): project installed package contributions into org resources"
},
{
"version": "1.44.1",
"date": "2026-09-29",
"body": "### archied\n\nTwo fixes to tasks that could not get past their workflow definition.\n\n- **Approving a task no longer parks it again.** A task requeued under a\n different workflow kept the previous run's definition pinned, so the worker\n refused to compile the dispatch — it named `feasibility` while the row named\n `implement` — and the task parked immediately, identically on every further\n approval, which left `decline` as the only working operator action.\n The daemon now re-pins whenever the pinned definition's id disagrees with the\n task's workflow. A pin that is present, digest-valid and id-consistent is\n still a strict no-op, so an operator's own definition override survives a\n dispatch unchanged.\n- **A shipped workflow definition now reaches an existing install.** A stored\n seed was consulted only for a resource the store did not already hold, so a\n document that changed in the build never reached a database an earlier\n release had seeded. For workflow definitions that is a total outage rather\n than a stale setting: the collection validates as one document, so a stored\n step type this build no longer has failed every task's pin, whatever workflow\n the task named — and the documented recovery, removing the resource and\n restarting, wrote nothing either, because the store answered the seed's known\n request ID from a history that outlives the resource. A seed now refreshes a\n kind it wrote the newest revision of and re-creates a resource that is gone,\n while an operator's own replacement is never undone.\n\n### archie-agent\n\nThe runtime image is rebuilt with this release and links the shared workflow\npackage carrying the definition-id helper above. Hosts that run agent\ncontainers need `docker compose pull agent` after updating to pick it up."
},
{
"version": "1.44.0",
"date": "2026-09-29",
"body": "### archied\n\nArchie can now review pull requests.\n\n- **Reviews on request and by watch.** Ask in chat or on the dashboard work form, add a repository to the watch list, or just let archie review its own PRs before it opens them. Review intensity follows a depth dial (quick/standard/deep) classified from the size of the change, and every finished review passes a verification layer — coverage-gap and cross-finding consistency checks — before it is produced.\n- **No forge credential reaches the review sandbox.** The daemon prefetches the pull request's data and rebuilds its source snapshot over the forge's HTTP API, so the agent container works from an isolated copy with no read access to the repository's credentials.\n- **Reviews stop at the operator gate before posting.** `review.precision_gate` / `approve_before_post` decide whether a finished review posts itself or parks for operator approval. With this release the parked state is a stop sign, not a checkpoint: the approve/reject/re-review responses behind the gate are not wired yet, and the gate's settings are not yet editable in the dashboard (configure them in `config.toml`). A parked review sits until that follow-up lands.\n- The adversarial self-review pass archie previously ran before opening its own PRs is superseded by this pipeline and has been removed.\n- Hardened harness input handling: harness identifiers are bounded to integer types.\n\n### archie-agent\n\nThe runtime image is rebuilt with this release; it links the shared pr-review workflow packages behind the reviews above. Hosts that run agent containers need `docker compose pull agent` after updating to pick it up."
},
{
"version": "1.43.0",
"date": "2026-09-28",
+13 -5
View File
@@ -56,11 +56,18 @@ messages by method name (the same switch that already routes
`internal/app/archied/main.go` that routes the sampling request through the
same chat-model call path `chatGenerateOptions` already uses, so a
server-initiated sample gets the daemon's configured model, not a second
provider client.
provider client. The agent worker hosts the same configured MCP servers on the
task path and runs its own model runtime, so `internal/app/agentworker` wires
the same seam from the task's builder model: a server that samples succeeds
inside a chat turn and inside a task, never one and not the other. The message
mapping and the token bound are shared (`internal/agentexec`, next to the
runtime both paths call models through) so both paths bound a sample
identically.
**Reuse check.** The chat model invocation path already exists
(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a
parallel model-calling path for MCP sampling.
(`chatGenerateOptions`, `main.go`) and the task model path already exists
(`agentexec.NewRuntime`, the runtime an agent stage runs on); this reuses both
rather than adding a parallel model-calling path for MCP sampling.
**Failure mapping.**
@@ -170,7 +177,8 @@ preview callbacks fire in order before the next call starts. `task check`.
| MCP client call serialisation | `internal/tools/mcp/client.go` | change (`#177`) |
| MCP server config | `internal/config/config.go` | new fields: `ParallelToolCalls`, `Sandboxed` |
| Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) |
| Sampling handler wiring | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |
| Sampling handler wiring (chat path) | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |
| Sampling handler wiring (task path) | `internal/app/agentworker/mcp_sampling.go`, `mcp_providers.go` | new (`#151`), answers from the task's builder model |
| Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) |
| Concurrent tool dispatch | dispatch entry point (closed `#183`) | none — already handles this |
| Sequential tool dispatch + previews | same dispatch entry point | new (`#182`) |
@@ -181,7 +189,7 @@ preview callbacks fire in order before the next call starts. `task check`.
| sub-feature | issue | implementer scope | suggested council lenses | why |
| ------------------------------------ | -------------- | ---------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| Server-initiated sampling | `#151` | `client.go` dispatch branch, `main.go` handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract |
| Server-initiated sampling | `#151` | `client.go` dispatch branch, chat-path and task-path handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract |
| Parallel-tool-calls flag | `#177` | config field, conditional mutex, constructor wiring | `lens-boundary` | per-server behaviour change must not leak into other servers' serialisation |
| Sandboxed MCP + Firecracker deferral | `#178`, `#179` | config field, constructor routing through `ContainerPool`, pool entrypoint variant | `lens-operator`, `lens-deletionist` | operator: sandbox-down failure path; deletionist: keeps `#179` from becoming unused scaffolding |
| Sequential dispatch with previews | `#182` | `DispatchMode` enum, sequential branch, preview reuse of streaming seam | `lens-maintainer` | two coexisting dispatch modes need a reader to tell which applies without re-deriving both |
+9 -1
View File
@@ -118,7 +118,12 @@ typed values are checked at load; `dyn` values are checked by the module decode.
**D5 — where the result map becomes the `Result` struct.** Settled:
`ModuleRegistry` stays schema-agnostic. `ModuleRegistry.DecodeResult`
(`internal/domain/eda/module`) is the conversion site.
(`internal/domain/eda/module`) is the conversion site. It accepts a value only
when it already carries the field's declared type, and a map only when it
carries every declared field. A conversion changes the value's representation --
a number for a string field is the named case -- and an absent field reads as the
zero value, so each is reported rather than becoming a quietly wrong value in a
later expression.
## Verification
@@ -128,5 +133,8 @@ typed values are checked at load; `dyn` values are checked by the module decode.
dynamically indexed `actions` read fails.
- An arg KEY the kind's `Args` schema does not define fails the load, and so
does `message: '123'` for the `log` kind. `message: event.title` loads.
- A result map missing a declared field, and one whose value is not already the
field's type, are both reported by the decode; a value that would only be
convertible (a number for a string field) is not accepted.
- The one-action `workflow` playbook shape, its dispatch, and its existing
load-time checks are unchanged.
+8 -3
View File
@@ -4,9 +4,6 @@
**Date:** 2026-09-03
**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`
**Beads issue:** `archie-core-t2db.14` (expression environment).
Unbuilt decisions: `archie-core-t2db.25` (J1 action ids),
`archie-core-t2db.26` (J2 args as CEL),
`archie-core-t2db.27` (Result schemas declared to CEL).
**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression
mechanism covers both an action's `when` condition and its `args` values.
@@ -222,6 +219,14 @@ cost of CEL is measured and bounded.
applied to every expression; the linter and daemon use the same value so they
agree. Alternative considered: exact number is a constant to tune at first
use.
- **J6 -- `args` failure semantics.** An `args` value that cannot be evaluated
aborts its playbook run: the action and every later action in that playbook do
not run, because data has no false value to fall back on and an action run
without its arguments is a silent one. Other playbooks matching the same event
still run, and the task is unaffected: a playbook run never changes routing.
The daemon log reports the failure, naming the task, the playbook and the
action; no task event is written. Alternative considered: mirroring J3,
rejected because a predicate has a meaningful false and data does not.
## Interaction with the execution-time gaps
+134
View File
@@ -0,0 +1,134 @@
# Plugin settings reconcile live
**Status:** Draft
**Revision:** 2
**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)
**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how
its changes take effect; `docs/architecture/plugins-and-extensions.md` owns the
plugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply
reports go.
## Outcome
An operator drops a plugin, module or secret-engine file into a configured
directory while archied runs, and the daemon loads it without a restart. An
edit to an installed file replaces what is running. A delete never stops running
code; apply status says so. A stored `plugin-settings` change applies live for
`plugin_dir`, `module_dir` and `secret_engine_dir`; a change to `skills_dir` is
refused.
## Triggers
`PluginSettingsKind` joins `runtimeResourceKinds` in
`internal/app/archied/control_plane.go`, and its descriptor `ApplyMode` becomes
`live` in `internal/app/controlplane/operational_settings.go`.
A poller reconciles on the apply-status restamp interval, so a dropped file
loads without a filesystem watch. Each tick re-runs both halves the boot path
runs, against the directories in the running config: the directory loads
(`secret.Registry.LoadDir`, `ModuleRegistry.Register`, `plugin.LoadDir`) and the
layering (`boot.runtimeConfig`), which re-resolves provider credentials. A
provider disabled at boot for an unresolvable engine is re-resolved on the first
tick that finds it; a changed directory retargets the next tick without a
restart.
## Rules
- Adding and changing load; removing never unloads. Yaegi interpreters are not
reclaimed while a caller still exists and there is no unload path; the running
set can only grow. A removal stays outstanding in the apply-status error until
the process restarts.
- Each file is loaded through a fresh interpreter (the boot pattern) and
content-hashed, so only new and changed files load.
- A file that fails to load is skipped and reported; already-running code keeps
running, the degrade-and-skip convention `plugin.LoadDir` and
`Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule
for the module directory; a broken file at runtime skips without aborting.
- A directory that does not exist reconciles to an empty set.
## The three registries
- **Secret engines** (`internal/secret`). Reconciliation re-runs
`Registry.LoadDir` against the live directory. `Register` replaces by name, so
an edited engine takes effect for the next resolution and a dropped engine
resolves on the next tick. A deleted engine stays registered: existing
references keep resolving through it until restart. Engines are stateless
resolvers, so a swap needs no lifecycle step.
- **Modules** (`internal/domain/eda/module`). Reconciliation re-runs
`ModuleRegistry.Register` for the kind's file. Playbook dispatch resolves
through the registry at invoke time, so the swap reaches a running playbook
store unchanged; a deleted file leaves the old invoker in place, running.
- **Plugins** (`internal/plugin`). `Host` grows running-state operations beside
`Register`, `Start` and `Stop`, and `Register` keeps its rule that
registration is allowed only before the first `Start`, so these are new host
methods rather than a relaxed `Register`. One adds a single module while the
host is running: inserted in dependency order, started alone, and rolled back
alone on failure, leaving every previously started module running. The other
replaces a module whose manifest id matches: stop it, start the new one, and
restart the old one when the new start fails; replacing a module another
running module depends on is refused. A module's `Start` is its only check
(`plugin.Module` has no probe, and one manifest id cannot be registered
twice), so a replacement checks by starting and keeps a rollback rather than
switching first. These operations obey the plugin engine rule: the host
invokes start and stop itself and isolates the failure to one module. A
deleted file makes no host call: the module runs on.
## `skills_dir`
`skills_dir` is not part of this change. The daemon refuses a `plugin-settings`
document whose `skills_dir` differs from the value in force. The check is a
pre-layer comparison on the live path (`boot.applyRuntimeResourceUpdate` in
`internal/app/archied/control_plane.go`), not an addition to
`validatePluginSettings` in `internal/app/controlplane/operational_settings.go`,
which stays value-agnostic per the #1143 decision recorded there: a
change-immutability rule needs the running config, and #1143's validates-nothing
still holds for values. The write lands, the store keeps the version, the daemon
publishes nothing, the refusal is reported against that stored version, and
last-known-good keeps running.
The layering assigns all four directories from one document, so a refused
`skills_dir` refuses the whole document and the other kinds still layer. That is
acceptable: `skills_dir` is the one field with no live consumer, a
whole-document refusal is the honest signal that none of it took effect, and an
operator changing `skills_dir` alongside another directory writes the two
changes separately.
## Apply status
One record per process: `archied` on `plugin-settings`, reported against the
version the process is running. The record's error field carries the outstanding
problem: a deleted file still running, a file that failed to load, the directory
failing to read, or a refused replace of a module another running module depends
on. A clean reconciliation clears the error. An add that succeeded is live even
while a removal is outstanding, and the error says so rather than showing the
kind as restart-required.
`ApplyMode` becomes `live`, so `RestartPendingBanner` no longer names
`plugin-settings`. The gateway's lag is shown instead by the per-process
applied-version rows on the Plugins page, which read the state
`applyStatusForKind` derives from `applied_version < storedVersion` in
`ui/src/stores/control-plane.ts`; that derivation is independent of
`ApplyMode`.
`archie-gateway` layers the `plugin-settings` document at boot through
`boot.loadRuntimeConfig` and reports it, but never calls `boot.loadPlugins` or
`boot.loadModules` and never reads the four directories, so it loads no plugin,
module or secret engine. With no live watch its row lags the stored version
until restart; that lag is a reporting lag, not a behaviour gap.
## Verification
- A plugin, module and secret-engine file dropped while the daemon runs loads on
the next tick; an unchanged file is not reloaded.
- An edited file replaces the running interpretation; a deleted file leaves the
running code running, with the process's error naming it until restart.
- A `skills_dir` change refuses the document: the store keeps the version, the
record carries that version and the refusal, and the running `skills_dir` is
unchanged.
- A plugin replacement whose new `Start` fails restarts the old module and
reports the failure; a replacement of a depended-on module is refused and the
dependent keeps running.
- A provider disabled at boot for a missing engine resolves again after the
engine file loads and a tick re-layers.
- The gateway reports the last version it layered at boot, loads no directory,
and its lag appears in its applied-version row rather than the restart banner.
+18 -6
View File
@@ -44,8 +44,11 @@ an `agent` StepExecution; fan-out phases record one child per call.
imported by changed files. One agent writes the PR narrative, risk
surfaces, changes that do not fit the narrative, and gaps between the
description and the diff.
3. **Dimension selection.** Three lens agents run in parallel over the intake,
anatomy and diff, each able to read the repository:
3. **Dimension selection.** Three lens agents run in parallel over the intake
(including its machine-written score), anatomy and diff, each able to read
the repository. A PR that intake scores as likely machine-written adds a
hallucination-check dimension: claims, citations and behaviour the diff
does not actually implement.
- **behaviour:** where the old and new code diverge for any input; API
contracts, concurrency and state, security, error handling, data flow;
- **mechanics:** whether the code runs at the language and framework
@@ -62,7 +65,11 @@ an `agent` StepExecution; fan-out phases record one child per call.
at most 8 at a time. Each reads its target and context files and may
follow references. Each finding carries file, line range, severity
(`critical`, `important`, `suggestion`, `nitpick`), title, body, an
optional suggested fix, quoted evidence, confidence and tags.
optional suggested fix, quoted evidence, confidence and tags. A reviewer
that exhausts its turn cap or deadline before its terminal tool call
records a distinct StepExecution status from a reviewer that completed
and found nothing; synthesis and the posted review treat the two
differently (the former is unreviewed, the latter is reviewed-clean).
5. **Verification layer**, over the review findings:
- code extracts an evidence package per finding: the code at the cited
lines and snippets from its callers;
@@ -94,8 +101,9 @@ an `agent` StepExecution; fan-out phases record one child per call.
8. **Merge gate.** One classification call per finding decides blocking or
advisory: blocking only for broken builds, security, data loss, contract
breaks and regressions. A failed call means advisory.
9. **Output.** One call per comment tightens its wording, keeping the
original on failure. The review is posted as one forge review with inline
9. **Output.** One call per comment tightens its wording, running in a
bounded pool at most 8 at a time (matching phase 4), keeping the original
on failure. The review is posted as one forge review with inline
comments. Any blocking finding requests changes; otherwise the review is a
comment. Archie never posts an approval.
@@ -113,7 +121,11 @@ With `review.approve_before_post = true`, synthesis ends in
`waiting_human`. The operator chooses which findings to post, rejects the
review, or asks for a re-review with instructions. A re-review reruns phases
3 to 8 with the instructions added to the lens and reviewer prompts, at most
2 times. A review with no findings posts nothing and does not wait.
2 times. A review with no findings posts nothing and does not wait. The gate
belongs to the standalone `pr-review` workflow only; archie's own-PR stage list
drops it, because a park there would end an implement run before its PR
exists (`docs/prds/pr-review-operator-response.md`,
"The gate is not reachable from archie's own PRs").
## Isolation
+69
View File
@@ -0,0 +1,69 @@
# PR review: the operator's answer to the approval gate
**Status:** Draft
**Authority:** `docs/prds/pr-review-agent.md` ("Operator approval") for the gate, and `docs/prds/state-store-contract.md` (rev. 2e) for every task field that crosses the State Store.
**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a run cannot resume partway through its stage list).
## Decision 1 — where the operator answers
The dashboard's `POST /api/tasks/{id}/action` (`internal/webui/api_tasks.go`, `handleTaskAction`) is the authoritative surface: the only one that resolves the actor from a credential and can carry a payload. Chat is a shortcut, not a second authority — `/approve` (`internal/gateway/gateway.go`, `Router.handleApprove`) answers the post decision with every offered finding selected, and gains no instruction or selection syntax.
`taskstate.Action` gains `rereview`, and `taskstate.Actions` returns `approve`, `reject` and `rereview` for `WaitingHuman`. `approve` posts the review, `reject` discards it through the existing terminal decline, `rereview` reruns the review phases with instructions. The action body carries `instructions`, required by `rereview`, and `findings`, the finding keys `approve` posts; an absent selection means all of them.
The path is `handleTaskAction` → `applyOperatorTaskAction` → `Chat.Contract.ApplyOperatorTaskAction` → the daemon's `LocalChatAdapter` → `taskactions.Client` (NATS `archie.gateway.task-action`) → `taskactions.Service.Apply` → one guarded store write that records the decision and requeues. Chat's `/approve` path (`StoreTaskController.Approve` → `chatTaskControllerAdapter.ApproveChatTask`) must reach that same write through the same function, so the two surfaces cannot record different decisions for one operator intent.
A requeue resumes the workflow the waiting state names, never a name the handler hardcodes. `taskactions.Service.apply` and `chatTaskControllerAdapter.ApproveChatTask` requeue with an empty workflow, which `Requeue` reads as "keep the task's", so neither surface hardcodes a workflow name: an approval whose wait recorded `pr-review` resumes `pr-review`. The feasibility handoff therefore has to name `implement` on the task before it enters the wait, which is the invariant the handler relies on — the workflow a task carries is the workflow it runs next. `Requeue` treats an empty workflow as "keep the task's".
### The review the operator answers
The gate writes the review it is holding onto the task before it ends the run: one JSON column, `review_gate`, a sibling of `review_payload`, holding the scored findings, the head SHA, the pull request's identity and the workflow the wait resumes. The run's existing `Store.Update` persists it. The same column carries the answer back: the response path's guarded write fills in the outcome, the selection and the instructions, and clears the offer for a re-review.
The operator reads the offer through the existing task read — `taskView.Task` on `GET /api/tasks` and `GET /api/tasks/{id}/debug` — so no new read endpoint is needed.
This record is load-bearing because the run that computed the findings ends at the gate and the engine cannot resume it partway. Without it, "post the selected findings" cannot mean the findings the operator saw: the resumed run recomputes them with agent calls. An `approve` resume therefore posts the recorded review filtered by the selection, and the review the resumed phases recompute never reaches the output.
## Decision 2 — the cap
The cap is a column: `rereview_rounds` on `tasks`, `bigint NOT NULL DEFAULT 0`, read by the response path and incremented in the same guarded write that requeues a re-review. A re-review at the cap is refused with the conflict sentinel the dashboard answers 409 with, and nothing is requeued. Two is a constant in the domain, not a config knob: the PRD fixes it.
`Task.Attempt` cannot carry the count, because it counts every requeue. The two alternatives are worse.
- The execution tree measures passes through the gate, not operator requests. A crash recovery (`RecoverStale`) or an operator retry re-runs the pipeline to the gate and would consume the cap; and a stage has no step read (`task.Store` carries none), so this route needs a new interface method anyway.
- `Task.Notes` is the agent memory ledger, not scratch. `AgentStage.buildRequest` passes it into every generic agent request, `agentexec` renders it as a prompt section, and `persistAppendedNotes` appends to it. A counter parsed out of a field agents write to is the encoded-state defect this repository rejects, and instructions parked there would reach every unrelated workflow's agents.
`RemediationRounds` is the precedent: one writer, one reader, one meaning, kept separate from `RetryCount` so unrelated retries cannot draw a budget down.
The write crosses the State Store. A goose migration adds the column; `internal/infrastructure/postgres/queries/tasks.sql` and its sqlc output carry it; `internal/infrastructure/postgres/store.go` maps it; `proto/state/v1/state.proto` carries it as a new `Task` field with its regenerated contracts and `staterpc/values.go` mapping both ways; `internal/domain/workflow/task/task.go` declares it; `internal/infrastructure/taskactions/store.go` adds it to the `taskactions.Task` projection the response path reads. The write itself is a guarded requeue method beside `RetryTask`, which increments a counter, and `BeginRemediation`, which records a payload in the same transaction: one transition-table guard, one increment and one requeue in one write. It must join every column-listing query, which `docs/development/state-store.md` names.
Tests that prove it: the guarded write increments for a re-review and for no other requeue; a re-review at the cap is refused and leaves the task waiting; and the field survives the wire, which `TestTaskProtoCarriesEveryDomainField` asserts for every field of the domain task.
## Decision 3 — how the instructions reach the stages
The recorded instructions enter the pipeline at phase 3 and phase 4 only, which is what the PRD asks for: a labelled operator-instructions block appended to `runLens`'s mission in `stagePRLenses` and to `runReviewer`'s mission.
They cannot ride `AgentStage.buildRequest`. Every pr-review stage builds its `agentexec.Request` in `runPRReviewAgentRecorded`, which sets no `Request.Notes`, so nothing the generic path threads reaches these calls. The pipeline restores the instructions from the task record at the same point it restores the review, and the two mission builders read them there.
## The gate is not reachable from archie's own PRs
`StagePRReviewAndOpenPR` splices `prReviewDecisionStages()`, the list `PRReview()` uses, so the gate is reachable from the implement workflow too. It must not be. The change is one entry moving: `stagePROperatorApproval()` leaves the shared list for `PRReview()`'s own stage list, immediately before the merge gate, and the own-PR splice keeps taking the shared list unchanged. This is a prerequisite for the response channel and a change of its own.
Three reasons, the second deciding it alone.
- The gate's question is which findings to post, and on archie's own PRs there is no pull request to post to at the point the splice reaches the gate. That trigger's human decision point is its park on an unchallenged blocking finding.
- Approving a wait inside the implement workflow re-enters that workflow at its first stage against a worktree that already carries the change. A builder that then reports no changes sets `BuildNoChanges`, `StageCommitPush` calls `closeNoChangesIssue`, and the issue is closed with no pull request ever opened. Nothing the gate decides is worth a route to silently closing an issue.
- Short-circuiting instead would put a conditional no-op in every stage whose work a wait had completed, which changes the resume semantics of the whole pipeline rather than this gate.
## What a full restart gives, and what it costs
A requeue re-runs the workflow's stage list from its first stage; the engine has no partway resume. That satisfies the PRD's "reruns phases 3 to 8" for free, and it is acceptable for the standalone pipeline precisely because that pipeline has no stage that writes and then closes. The costs:
- Phases 1 and 2 recompute. Both are code except two agent calls — the machine-written score and the anatomy narrative — so those re-run, and a changed score can change whether the hallucination-check dimension is added.
- The pull request's snapshot is checked out again.
- The run's cost and wall-clock budgets are per attempt, so a re-review starts with a fresh allowance, which the cap bounds.
## Verification
- A gate wait on the standalone `pr-review` workflow answered `approve` posts exactly the findings the operator selected, and no finding the resumed phases produced.
- A re-review at the cap is refused, the task stays waiting, and the count survives a store round trip.
- A re-review's instructions reach the lens and reviewer missions; a first run's do not.
- The gate is unreachable from the implement workflow's stage list.
+123
View File
@@ -0,0 +1,123 @@
# Review settings resource
**Status:** Draft
**Beads issue:** `archie-core-0ry6`
**Authority:** `docs/prds/runtime-control-plane.md` for the resource model,
`docs/architecture/configuration.md` for ownership, and
`docs/prds/pr-review-agent.md` for what the two dials do.
## Decision
`review.precision_gate` and `review.approve_before_post` are one control-plane
resource, `review-settings`. The file's `[review]` section seeds it, the stored
document outranks the file from then on, and the dashboard writes it through the
same settings machinery as every other resource.
The resource is deployment-wide, like every definition the State Store seeds
(`storecontract.DefaultOrgID`): not per-repository, per-identity, or per-run.
## Why its own kind
The two dials are pr-review policy — what a review may post, and whether a human
decides — not a limit on a task run. The document that carries task limits
belongs to that feature. `runtime-control-plane.md` splits settings by feature
and refuses documents unrelated features share; `configuration.md` puts a typed
runtime setting with the domain whose behaviour it describes. One document per
feature is the rule, not one document per settings page.
A new kind also has no legacy documents. Its first value is the seed derived
from the file, so "the store outranks the file" begins from an explicit copy of
both fields rather than from a document that predates them.
## Document
New file `internal/app/controlplane/review_settings.go`:
```go
const ReviewSettingsKind = "review-settings"
type reviewSettings struct {
PrecisionGate bool `json:"precision_gate"`
ApproveBeforePost bool `json:"approve_before_post"`
}
```
Its `Definition` sets `ApplyMode: "live"`, `Document: reviewSettings{}`, and a
`Seed` returning `reviewSettings{cfg.Review.PrecisionGate, cfg.Review.ApproveBeforePost}`,
and a `Validate` wrapping `validateAs`: both fields are free booleans with no cross-field
rule, so the validator is a named place to put one rather than an inline no-op
(`validatePluginSettings` is the precedent). No `Normalize`, because the kind
has no second wire shape to converge.
## Seeding
`ImportConfig`/`seededValues` write the seed for a kind the store does not hold,
so a deployment that never edited the dials runs the values in `[review]`. Once
a document is stored, the file key stops mattering, which is the rule for every
database-owned setting.
## Apply
`runtimeConfigFrom` in `internal/app/controlplane/runtime_config.go` layers the
stored document over the file's `Review`, assigning `out.Review.PrecisionGate`
and `out.Review.ApproveBeforePost` field by field. Field-by-field, not
`out.Review = ...`: a field added to `config.Review` later keeps the file's value
until the document carries it.
`ReviewSettingsKind` joins `runtimeResourceKinds` in
`internal/app/archied/control_plane.go`, so a new stored version re-runs the
layering and republishes through `config.Holder`. Live rather than
restart-required, because every consumer re-reads it: `Review` is on
`reloadableFields` in `internal/app/archied/reload.go`, and the value reaches a
run through `Daemon.configFor` → `Config.ForTask` → `TaskConfig.ToConfig` →
`TaskContext.Cfg`, which `stagePRPrecisionGate` and `stagePROperatorApproval`
read. The next task run uses the new value; a run in flight keeps the value it
started with.
## Projection and page
`BuildConfigView` gains a plain `Review` field carrying both values out of
`cfg.Review`, the way `BudgetsView` carries the layered budgets, so the published
config snapshot tells any reader what is in force. The Review page renders the
two toggles from the control-plane store's draft for `review-settings` — the
shape `SystemTasksPage.vue` uses for `workflow-execution-settings` — and shows
the projected value beside them; a Settings route plus a `PAGE_RESOURCES` entry
(`ui/src/stores/control-plane.ts`) bind the page to the kind.
Nothing else re-advertises them. `configFieldDescriptors` and `ConfigView.Schema`
gain no `review.*` row: the config catalog's generic renderer was deleted, so a
descriptor row adds a field nothing can edit, which is the shape `becb0b5e`
removed.
## What the test proves
`internal/app/controlplane/runtime_config_test.go` adds the round trip that
builds the effective config the way boot does: seed the kind from a file config
with both dials set one way, store a document with both flipped, layer it
through `runtimeConfigFrom`, and assert the effective `cfg.Review` equals the
stored document. A second case covers the absent kind, where the file's values
stay in effect. The assertion is on `cfg.Review` — the value `TaskContext.Cfg`
carries into the two stages — not on a struct the test set directly.
`TestRuntimeResourceKindsApplyLive` gains `review-settings` as live. The
validator needs no `validators_agree_test.go` case: it wraps `validateAs` with
no rule, because no combination of the two booleans is invalid, and a case that
cannot fail is a test the project then carries for nothing.
## Rejected: extending workflow-execution-settings
That resource is `workflow.ExecutionSettings`, "the limits captured when a
workflow execution starts". Putting review policy in it makes the review feature
a field of the limits document, gives a boolean edit a ride on a document whose
candidate is validated and swapped as one unit with the budgets, and forces
absence-aware pointer fields onto booleans so a document stored before the fields
existed does not turn a file's `precision_gate = true` into `false`. It buys one
less kind at the cost of the ownership rule the model is built on.
## Out of scope
- Per-repository, per-identity, or per-workflow review settings. A scope key is
a later decision with its own resource shape.
- Any other review knob. A field joins the document only with a consumer, the
rule every config field carries.
- The reviewer pipeline's behaviour. This document places the settings; it does
not change what they do.
+17 -3
View File
@@ -45,6 +45,14 @@ version being edited. The API layer sets the actor; the request body cannot.
The server validates the change, then writes it with its audit record. It rejects
edits to an old version.
The request ID is the write's idempotency key, and it is scoped per org and
per kind, never global. The key is `(org_id, kind, request_id)` — the unique
index `idx_resource_history_org_kind_request` (migration `0021_resources_per_org.sql`)
— so replaying a request ID is the same org's prior write of the same kind, and
a request ID reused across orgs or across kinds is a separate write. This is the
same scoping as the task idempotency key `org/identity/owner/repo/number`
(`docs/prds/orgs-and-access.md`).
## API
The API has four operations:
@@ -76,8 +84,11 @@ and encryption-key references. State Store and control-plane RPCs use the same
endpoint.
When upgraded, existing instances are migrated to the database. Existing
database values are not overwritten. After migration, settings in TOML are
ignored and cannot block State Store startup.
database values are not overwritten, with one exception: a resource whose
document the build ships is refreshed when the seed itself wrote the stored
copy, because that copy is a previous release's document rather than an
operator's. After migration, settings in TOML are ignored and cannot block
State Store startup.
The Web UI remains available when `archied` or Gateway is down. It shows failed
changes and can correct or roll them back.
@@ -92,7 +103,10 @@ Users create and edit workflows in the Web UI. Workflows are stored as versioned
YAML. Built-in workflows can be overridden and restored.
A workflow is a list of steps. Each step has a known type and its own settings.
Plugins can add step types. Each run keeps the workflow version it started with.
A step type is part of the build's step vocabulary, contributed as a provider at
the composition root; interpreted plugins contribute none
(`docs/prds/workflow-step-vocabulary.md`). Each run keeps the workflow version it
started with.
Yaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful
behaviour must first be available as normal workflow steps.
+142
View File
@@ -0,0 +1,142 @@
# SOUL: an agent's user-authored personality
**Status:** Draft
**Authority:** `docs/architecture/identity.md`, “Three-layer identity model”;
`docs/prds/orgs-and-access.md` for identity and org ownership.
## Decision
SOUL supplies an agent's name, register and warmth. It belongs to the agent's
immutable `IdentityID`, not its session, model, installation or container
profile. Rename preserves it; changing a profile does not change who acts.
SOUL never changes attribution, credentials, grants or identity lifecycle.
`config.AgentProfile` remains an execution environment, not another identity.
Use the existing three layers: invariants, user-authored SOUL, and curator-derived
representation. Curators may propose SOUL changes but never apply them.
## Files and ownership
The config directory is `${XDG_CONFIG_HOME:-~/.config}/archie`, or the directory
of an explicitly selected config file. The default/root agent uses `SOUL.md`
directly there; additional agents use `agents/<identity-id>/SOUL.md`. The root is
the identity selected by application composition, never the initiating user or
a session's personality selection. No file creates or selects an identity.
The common case keeps a human-friendly filename; additional agents get separate
asset directories, following `.agents/skills/<name>/SKILL.md` without confusing
these directories with `[containers.profiles.<name>]`. Reject display-name or
slug directories: rename and same-name agents across orgs would require another
name-resolution rule. Immutable IDs avoid both problems without an org directory.
When a file-owned agent's file is absent, create the shipped default with
exclusive creation. Never overwrite an existing file, including an empty one.
A creation failure still permits the turn using the embedded shipped default.
Ship that document independently of `agent.ShippedPersonas`, so deleting personas
cannot delete the fallback.
Resolve once at the start of every new generation:
1. A stored SOUL entry for the acting identity is authoritative.
2. Without an entry, read that identity's file again.
3. An absent, empty, unreadable or invalid selected source uses the shipped default.
The first explicit dashboard/API save takes ownership permanently. Thereafter
file edits are ignored: emit one ownership notice and show the owning stored
version in the dashboard. Restoring the shipped default writes a stored value;
it does not remove ownership. Refuse writes that remove an owned entry.
This ownership boundary is the design's one stateful rule. Files seed the
editable value, not an automatic durable import. Reject seed-once import because
it breaks next-message file editing; reject file-always-wins because it makes
dashboard saves ineffective. Neither a restart nor an upgrade overwrites an
owned value, following the precedence of `controlplane.AgentProfileKind` without
copying its startup import timing.
## Prompt and failure contract
Keep `archie.md.tpl`'s XML-escaped
`<soul purpose="identity_and_style" trust="data">` block before
`<instruction_precedence>`. SOUL is style reference data; the invariant sections,
tool inventory and runtime metadata remain authoritative and uneditable.
Preserve `TestBuildSystemPromptSoulCannotOverrideInvariants`.
Accept UTF-8 plain Markdown with at most 8 KiB in its XML-escaped body. This bounds
personality to a small prompt contribution; count the complete rendered prompt
in the turn's context budget and never truncate invariant sections. Bound file
reads before decoding; reject oversize input rather than truncating instructions.
File and stored writes use the same validator; an invalid save leaves the stored
version unchanged. The shipped default must pass that validator.
Read and creation errors never fail a turn. Log once per identity/source failure
episode, retry on the next turn, and allow a new warning after recovery. If the
store cannot establish whether an owned entry exists, use the shipped default,
not a potentially shadowed file. Do not log SOUL text. Each turn keeps its resolved
snapshot; edits affect the next generation without restart or SIGHUP.
## Cross-layer delivery
- `internal/domain/agent` owns SOUL content validation and the identity-keyed read
contract; `internal/domain/identity` remains the actor/lifecycle authority.
- The configuration infrastructure resolves the config directory and handles
file discovery, exclusive default creation and bounded per-turn reads.
Application composition resolves the acting `IdentityID` through the existing
identity repository/bindings and supplies it to the gateway.
- Register `SoulKind` (`agent-souls`) in the control plane with a live descriptor
and an org-scoped document mapping identity IDs to `{text}`. Persist it through
the State Store's existing resource/history contracts, not a new table,
process or SOUL RPC. An empty map owns no identity; saves preserve other entries
and use expected-version checks. Validate that each key is an agent identity
in the resource's org; begin with the default org without inventing org setup.
Every save records the authenticated editor's identity, source, request ID and
timestamp; file installation records the system identity, not a fictitious user.
- Replace `TurnRunnerConfig.Personas` / `PersonaPromptSource` with the per-identity
source in `prepareTurn`; name the `SystemPromptConfig` input SOUL. Both normal
and streaming turns use this assembly path. Do not add personality to the
worker environment, `AgentProfile` or workflow-stage prompts.
- On an agent identity's dashboard page, expose its effective SOUL, file/default
or stored source, shadowed file path, owning version, and Markdown editing.
Save to the control plane, never the host file; show validation/version
conflicts and offer restoring shipped content or a history revision as a save.
Read effective file/default content and ownership metadata through a gateway
query using the turn resolver; the separate UI process never reads the
gateway host's files. Apply identity-management access rules and the existing
shared live-update hub.
- Update `docs/development/agent.md` and `control-plane.md` with this reach and
precedence, `frontend-ui.md` with the gateway query, and the config wiring
guidance with a copyable file example.
## Persona removal gate
SOUL supersedes `PersonaRegistry` and the persona-reconciliation proposal;
identity-per-action supersedes personas as an identity mechanism.
`PersonaRegistry.GetActive` composes the baseline with one of five styles from
`agent.ShippedPersonas`; SOUL replaces the baseline, not that style catalogue.
Per-session switching disappears: remove `/personality`, Telegram personality
callbacks, the dashboard persona page, and chat wire fields `personas`,
`active_personas` and `personas_available` without reusing their field numbers.
Do not merge session selections into SOUL or retain a separate style axis.
Custom persona text must remain available to copy before deleting its stored
resource; no migration guesses one agent's SOUL from several sessions.
Remove persona loading, selectors and commands only after every chat composition
supplies the identity-aware SOUL source, the fallback renders without personas,
and the dashboard can edit it. SOUL delivery does not wait for org creation or a
new container-profile model.
## Acceptance
- Two agents use distinct files and stored entries; renaming one or sharing a
container profile does not change or mix their SOULs.
- Before ownership, a file edit changes the next normal or streaming prompt;
creating defaults never clobbers an existing file.
- After a save, conflicting file edits and restarts cannot override the stored
value; the ignored file and owning version are visible. Updating one agent
preserves the other; stale saves fail and history restores are audited saves.
- Missing, empty, unreadable, malformed and oversize selected inputs render the
shipped default. Repeated read failures log once, recover on a later turn,
and never abort generation.
- Hostile markup stays escaped before singular, unchanged invariant blocks;
prompt budgeting includes SOUL and cannot drop the rules.
- Dashboard edits reach the next generation without restart; persona removal
leaves every channel with a nonempty identity slot and preserved custom text.
+216
View File
@@ -0,0 +1,216 @@
# Declared outputs of a workflow run
**Status:** Draft
**Date:** 2026-09-30
**Bead:** `archie-core-t2db.43`
**Authority:** `docs/prds/event-automation.md` for what a declared output is,
`docs/prds/workflow-calls.md` for the call and its grants,
`docs/prds/state-store-contract.md` for the State Store contract the wire
change must satisfy.
**Supersedes:** `docs/prds/workflow-calls.md`, "Waiting on the callee": the
callee's transition detail is the human summary, not the stand-in for
structured outputs.
A workflow declares named, typed outputs. A run writes each one once. A
`wait: true` caller receives them, and may publish one as its own.
## Where outputs are declared
`outputs:` on the workflow definition, beside `inputs:`, decoded into
`task.WorkflowInterface.Outputs map[string]OutputSpec` where
`OutputSpec{Type, Required}`:
```yaml
id: firewall-contain
outputs:
contained: { type: bool, required: true }
summary: { type: string }
```
Names and types are the input grammar: the same identifier shape, the same
type set, and the same check in `WorkflowInterface.Validate`, which both
`ParseDefinition` and `ParseWorkflowInterface` call.
**Forced by:** `ParseDefinition` decodes with `KnownFields(true)`, so a key no
decoded struct declares is refused — the declaration must live on
`WorkflowInterface` for an author to write it at all, and that is where
`docs/development/workflows.md` puts every field a process without the engine
must read. The type set is the shared value vocabulary: `TypeAccepts` and
`ValueType` already check a mapped parameter and an input with it. `required`
defaults to false, and the generated YAML for a builtin that declares no
outputs is unchanged, because a definition's digest pins a run.
**Rejected:** outputs per step, or per call step, because a workflow returns a
result as itself rather than as one of its stages. Also `task.Definition`
gaining outputs: no reader needs them — a binding offers inputs, and a call's
outputs assignment is checked against the callee's YAML in the same
collection — and a declared field with no reader parses and does nothing.
## How a run writes one
Each declared output is offered to the run's agent stages as a capture tool
named after the output, whose arguments are `{"value": ...}`; the accepted
call's `value` member is the output's value. The engine holds the accepted
values on the task context and writes them into its own task row in the
`Store.Update` call the run already makes. A deterministic stage may set the
same values in Go, and the run's finish check validates them identically.
**Forced by:** a run's only structured results are capture calls
(`agentexec.CaptureTool`, `Result.Captures`), and the workflow interface
already declares when a stage needs them (`task.WorkflowNeeds.Captures`).
`WorkflowInterface.Needs` reports `captures` for a non-empty `Outputs`, so
declaring an output alone requires the capability and a Kit profile that
serves no capture tools is refused before dispatch.
Deriving the tools from the declaration means an output cannot be written
under a name nobody declared, and it keeps one route to structured agent
output rather than adding a second beside the capture path. The row write is
the run's existing write: the task row is where a run's own state lives, and
the container already holds `Update` on its own row.
The tool is offered with `MaxCalls: 1`, and a stage is not offered an output
the run has written, so a run writes each output once: a repeat within a stage
is answered with the tool's rejection and the agent carries on, and a later
stage cannot overwrite a value. A stage's own capture tool may not share a
name with a declared output, because the value would otherwise be ambiguous.
**Rejected:** a `workflow.output` step type, because assigning the run's
result from a step needs a grammar for "the previous stage's result" that does
not exist, and a step that reaches the agent would be the second path
`docs/development/workflows.md` forbids. Also a write RPC of its own: the
container's `Update` already reaches its own row, and a second write verb for
one column is a second thing to keep in step.
## How a caller receives one
On a successful `wait: true` call the caller's stage holds the callee's
outputs as a `map[string]any`. A call step's `outputs:` setting publishes one
as one of the caller's own outputs:
```yaml
steps:
- type: workflow.call
workflow: firewall-contain
wait: true
inputs: { src_ip: inputs.src_ip }
outputs: { contained: outputs.contained }
```
The key names the callee's declared name; the value names one of the caller's
own with the prefix the call's `inputs:` already uses. A published value joins
the caller's output set for its run, so a caller returns its callee's result to
its own caller, and a run may publish a callee's output and write its own
others.
Lifetime is the attempt. The run starts with an empty output set, every later
stage of that attempt sees the values, and the finish write replaces the row's
set wholesale — so nothing an attempt wrote survives into the next, and a run
that writes nothing stores nothing. Values reach a caller only from a
successful terminal state: the caller assigns them after `callSucceeded`, so a
parked or failed callee delivers nothing whatever its row holds. A call step
with `wait: false` and an `outputs:` block is refused when the definition is
saved, because nothing has finished when the caller moves on.
**Forced by:** caller and callee are separate runs in separate containers, so
the caller's own row is the only durable place to hold a received value. The
prefix rule is not a new grammar: in `inputs.<name>` the prefixed side is the
caller's own value and the map key is the callee's, and `outputs.<name>` reads
the same way in the other direction.
**Rejected:** an implicit same-name copy from callee to caller, because the
caller's contract would then depend on a callee it does not name, and swapping
the callee would silently change what the caller returns. Also letting a later
stage read a callee's output in its mission text: that needs a stage-result
reference namespace this model does not define.
## Failure rules
- **Undeclared value.** The agent path cannot produce one — the tool exists
only for a declared output. A Go stage that sets an undeclared key parks the
run before its outcome transition, and a stage capture tool sharing a
declared output's name is refused when the run starts.
- **Declared but never written.** With `required: true` the run parks naming
the output and reaches no successful terminal state, so no caller observes a
success missing a promised value. Without it the key is absent from the
object rather than null, and a written `null` counts as not written, as
`CheckInputs` treats a null input. A published output the callee never wrote
leaves the caller's output absent, which the caller's own `required` then
judges.
- **Save time.** `WorkflowInterface.Validate` refuses an unknown type and a
malformed name. A call step's `outputs:` assignment is checked by a
`checkCallOutputs` beside `checkCallInputs`: the key must be declared by the
callee, the reference must name an output the caller declares, and the
callee's declared type must satisfy the caller's.
- **Run time.** A captured value is re-validated against the declared type
when the run reads it back, for the reason `readCaptures` re-checks every
record: the captures file is writable by the harness user. A published
callee value is re-checked against the caller's declared type before it
enters the caller's set; a mismatch parks the caller naming the output.
**Rejected:** typing at save time only, because a captured value has no
save-time form; and at run time only, because a definition error would surface
as a failed run instead of a refused save.
## Storage and wire
- `tasks.outputs`, text, `NOT NULL DEFAULT ''`, written by the run's own row
write — the shape `tasks.inputs` already has, with `EncodeOutputs` and
`DecodeOutputs` beside `EncodeInputs`/`DecodeInputs`.
- The `Task` message carries it as `outputs_json`, because the container's
`Update` sends the whole row and a column the message cannot carry is a
column that write drops.
- `WorkflowCallStatusResponse` carries it as `outputs_json` beside `status`
and `detail`, read from the callee's row by the handler that already
verifies `call_parent_task_id`; `detail` keeps carrying the transition
detail. The Go facade stays the two methods of `task.Caller`; no interface
method is added.
**Forced by the grant:** a caller authenticates as its own task and may reach
`WorkflowCallStatus` on its own task ID, `Update`/`Transition`/`InsertEvent`
on its own row, and the step-execution pair on its own execution. It can read
neither the callee's row nor the callee's steps. `WorkflowCallStatus` is
therefore the only channel that exists, and it is already the sanctioned
cross-run read — this model fills the placeholder it carries. The values live
on the callee's row rather than on the caller's call step because the callee
writes them and the caller only receives them.
The write order is part of the contract: a run persists its outputs before its
outcome transition, so the status a caller sees when its wait ends already
carries them. A set whose encoded form passes the bound the store applies to a
structured payload (`clip`, as `ReviewPayload` is stored) is refused rather
than clipped, because clipped JSON does not parse.
No sentinel moves: a missing required output is an engine park reason, and a
caller asking about a task that is not its callee still gets `ErrCallNotYours`,
so nothing new crosses `mapError`/`unmapError` and no canonical message string
changes.
**Rejected:**
- A new read RPC (`WorkflowCallOutputs`) — a second poll of a row the caller
already polls, whose answer could disagree with the status beside it, and a
second grant-widening row for the same parent-child check.
- The step-execution record — `ListSteps` is granted by `read` on a run, so a
caller cannot read the callee's steps at all, and making them readable would
hand it the callee's whole step history, which the parent-child check exists
to prevent. A step's `detail` is text clipped like every other detail.
- The caller's call step as the store — the value originates in another
process and must outlive the container that produced it.
## Out of scope
- A run started by a binding: it has no caller, and its outputs live on its
own row only.
- A stage reference to a previous stage's captured value.
- Assigning outputs in a caller cancelled while it waits.
## Verification
- A definition whose output type is not in the vocabulary, and a call
publishing an output neither side declares, are refused when saved.
- A `wait: true` caller receives a value its callee wrote, returns it as its
own output, and the caller's row carries it.
- A run whose required output is never written parks, and its caller's stage
fails naming the output.
- A call step publishing an output over `wait: false` is refused when saved.
- A retried attempt that writes no outputs leaves an empty set on the row.
- An example under `examples/workflows/` carries an `outputs:` block and a
call that publishes one, which `TestExampleWorkflowsParse` covers.
+85
View File
@@ -0,0 +1,85 @@
# Workflow step vocabulary: what a step type is and how binaries agree on it
**Status:** Draft
**Date:** 2026-09-29
**Beads:** `archie-core-m7oc` (agreement between separately deployed binaries), `archie-core-ze7y` (the deleted `.archie/stages/*.go` equivalent)
**Extends:** `docs/architecture/plugins-and-extensions.md` (plugin engine rule), `docs/prds/event-automation.md` (the workflow model step types serve)
**Authority:** `docs/architecture/plugins-and-extensions.md` — the workflow step vocabulary is a Workflow capability family, and its extension point follows the plugin engine rule.
## Decision
A workflow step type is a named Go factory: the word a YAML workflow writes in
a step's `type` field, plus the factory that builds its stage. The name is a
stable identifier; the identity also declares what plugin family claims it,
so a contribution that shadows a shipped stage is refused instead of
overriding it.
The Workflow domain owns the typed family contract — `StepTypeProvider` for a
contribution and `Manager` as the owning registry. A provider contributes a
whole set of step types under its own stable-identifier name; the manager
validates the entire contribution before applying any of it (named provider,
well-formed step-type names, non-nil factories, no step type claimed twice,
no claim on a name another provider holds) and applies it atomically. The
generic `plugin.Plugin` contract stays metadata-only.
The vocabulary is a compiled-in, closed set. `internal/infrastructure/workflowsteps`
is the one place a step type is bundled into any binary that resolves one: the
shipped workflow stages, the repository-hook replacements (`gate.diff-rules`)
and the repository-free event steps each arrive as one provider, and adding a
step type means adding a provider to that set. Interpreted plugin sources
cannot contribute step types: the Yaegi plugin host satisfies only the
metadata contract, and no bridge to `StepFactory` exists.
Every binary that resolves a step type builds its manager from that same
provider set at its composition root, before its first resolution, and
injects the manager everywhere it resolves definitions. Agreement is per
build: the State Store, the daemon's workflow-definitions client and the agent
worker built from the same source register identical vocabularies by
construction; binaries built from different sources can disagree, and only a
matching deploy fixes that.
An unknown step type is refused twice, and never degraded. The validator
`ParseDefinition` refuses a definition naming an unregistered type at save
time, on the validating side the composition root built (the State Store's
workflow-definitions resource validates there before anything is stored). The
compiler refuses the same definition at run, so a binary handed a definition
written against a vocabulary it does not have fails that run loudly instead of
silently skipping steps. Both checks live in the Workflow domain against the
injected manager, which is why no binary can opt out of the check by
substituting its own registry.
## Relationship between the questions
`archie-core-ze7y` is the same question seen from the deleted
repository-authored stages: those `.archie/stages/*.go` files held arbitrary
stages, and their gate half landed as `gate.diff-rules` settings rather
than interpreted Go. Their stage half has no replacement and does not get one
that approximates it: no interpreted-Go stage type is built, and no command
step type is created by this decision to stand in for them. The refusal of
`.archie/stages/*.go` stays until the maintainer's trust decision
(`archie-core-ndm8`) says otherwise.
If that decision ever allows a command step type, it arrives as a provider in
the compiled-in set under the rules above — a new contributor of exactly one
step type at a named provider. It is not a plugin contribution mechanism, and
it does not change any answer in this document.
## Rejected alternatives
- **A vocabulary version or hash on the wire.** The executing side already
refuses an unknown step type at its first compile, which is the mismatch
detector, and it fails closed. A wire field would only narrow the
deploy-skew window that a matching deploy closes, at the cost of a new
contract field.
- **A Yaegi-plugin-to-`StepFactory` bridge.** It would run repository-supplied
interpreted code inside the daemon's process with daemon privileges. The
trust boundary invariant requires repository-authored code to run in the
task container, not in an interpreter embeddable into any binary.
- **A package-level process-global registrar.** Global mutable registry state
is unreadable at the composition root, collides with itself when one
process builds the vocabulary twice, and is what made the first attempt at
this question worse instead of better.
- **Degrading on an unknown step type.** A run that skips steps it cannot
compile would finish green while silently dropping the behaviour the
definition asked for; refusal at save and at run is the only honest option.
+28
View File
@@ -0,0 +1,28 @@
# The containment workflow a firewall-investigate run calls:
# firewall-investigate (workflow.call, wait: true) hands its findings upward
# from its declared summary, and this workflow's own agent stage decides and
# records the containment as its own declared outputs. Paste it into the
# dashboard's workflow definitions alongside firewall-investigate
# (docs/prds/workflow-call-outputs.md).
id: firewall-contain
repository: none
profile: network-investigator
inputs:
src_ip: { type: string, required: true }
outputs:
contained: { type: bool, required: true }
summary: { type: string }
steps:
- type: workflow.call
settings:
workflow: firewall-investigate
wait: true
inputs: { src_ip: "inputs.src_ip" }
outputs: { summary: "outputs.summary" }
- type: agent.run
settings:
mission: >-
Using the investigation summary the called workflow returned, decide
whether the source address in the inputs should be contained. Write
your decision with the contained tool, and a one-line rationale with
the summary tool.
+8 -1
View File
@@ -2,17 +2,24 @@
# src_ip from a mapped parameter and runs one agent mission in a scratch
# workspace under the network-investigator profile. Paste it into the
# dashboard's workflow definitions.
#
# Its declared output (summary) is offered to the agent stages as a capture
# tool named after it; a wait:true caller publishes it as one of its own
# outputs (docs/prds/workflow-call-outputs.md).
id: firewall-investigate
repository: none
profile: network-investigator
inputs:
src_ip: { type: string, required: true }
severity: { type: string }
outputs:
summary: { type: string }
steps:
- type: agent.run
settings:
mission: >-
Investigate the source address in the inputs: who owns it, what it
resolves to, and whether it is reachable. Report what you found and
how serious it looks given the severity.
how serious it looks given the severity, and write your one-line
conclusion with the summary tool.
read_only: true
+6 -5
View File
@@ -41,10 +41,11 @@ func runAsHarnessUser(cmd *exec.Cmd, name string) error {
}
// harnessCredential resolves a user name or "uid[:gid]" to a credential.
// Root is refused whichever way it is named.
// Root is refused whichever way it is named. IDs are bounded to 31 bits so
// they convert to int for os.Chown on every platform.
func harnessCredential(name string) (*syscall.Credential, error) {
uidText, gidText, hasGid := strings.Cut(name, ":")
uid, uidErr := strconv.ParseUint(uidText, 10, 32)
uid, uidErr := strconv.ParseUint(uidText, 10, 31)
var cred syscall.Credential
if uidErr == nil {
cred.Uid, cred.Gid = uint32(uid), uint32(uid)
@@ -53,18 +54,18 @@ func harnessCredential(name string) (*syscall.Credential, error) {
if err != nil {
return nil, fmt.Errorf("harness user %q: %w", uidText, err)
}
id, err := strconv.ParseUint(u.Uid, 10, 32)
id, err := strconv.ParseUint(u.Uid, 10, 31)
if err != nil {
return nil, fmt.Errorf("harness user %q has non-numeric uid %q", uidText, u.Uid)
}
group, err := strconv.ParseUint(u.Gid, 10, 32)
group, err := strconv.ParseUint(u.Gid, 10, 31)
if err != nil {
return nil, fmt.Errorf("harness user %q has non-numeric gid %q", uidText, u.Gid)
}
cred.Uid, cred.Gid = uint32(id), uint32(group)
}
if hasGid {
gid, err := strconv.ParseUint(gidText, 10, 32)
gid, err := strconv.ParseUint(gidText, 10, 31)
if err != nil {
return nil, fmt.Errorf("harness group %q is not numeric", gidText)
}
+24
View File
@@ -77,6 +77,27 @@ func runGit(t *testing.T, dir string, args ...string) {
}
}
// hostileSigningConfig writes a global git config that makes every commit
// fail unless the fixture disables signing in the repository's own config.
func hostileSigningConfig(t *testing.T) string {
t.Helper()
path := filepath.Join(t.TempDir(), "hostile.gitconfig")
const cfg = "[user]\n\tname = Hostile\n\temail = hostile@example.com\n\tsigningkey = /nonexistent/signing-key\n[gpg]\n\tformat = ssh\n[commit]\n\tgpgsign = true\n"
if err := os.WriteFile(path, []byte(cfg), 0o600); err != nil {
t.Fatal(err)
}
return path
}
// TestFixtureSeedsARepositoryThatIgnoresHostSigningConfig pins the fixture's
// hermeticity: it must not depend on the developer's global git identity or a
// signing agent.
func TestFixtureSeedsARepositoryThatIgnoresHostSigningConfig(t *testing.T) {
t.Setenv("GIT_CONFIG_GLOBAL", hostileSigningConfig(t))
t.Setenv("GIT_CONFIG_NOSYSTEM", "1")
newFixture(t, "edit")
}
type fixture struct {
workspace string
log string
@@ -87,6 +108,7 @@ func newFixture(t *testing.T, scenario string) *fixture {
t.Helper()
ws := t.TempDir()
runGit(t, ws, "init", "-q")
runGit(t, ws, "config", "commit.gpgsign", "false")
if err := os.WriteFile(filepath.Join(ws, "widget_test.go"), []byte("package widget\n"), 0o600); err != nil {
t.Fatal(err)
}
@@ -388,6 +410,8 @@ func TestHarnessUser(t *testing.T) {
{"0", 0, 0, true},
{"root", 0, 0, true},
{"not-a-user-anywhere", 0, 0, true},
{"2147483648", 0, 0, true},
{"1000:2147483648", 0, 0, true},
}
for _, tt := range tests {
cred, err := harnessCredential(tt.user)
+66
View File
@@ -0,0 +1,66 @@
package agentexec
import (
"errors"
"fmt"
"github.com/samcharles93/ai-sdk/chat"
protocol "github.com/samcharles93/archie-core/internal/tools/mcp"
)
// DefaultSamplingMaxTokens bounds a server-requested completion when the
// request does not set maxTokens. A sampling request is a delegated
// sub-completion, not a full turn, so one MCP server cannot spend a
// turn-sized output allowance on a single request.
const DefaultSamplingMaxTokens = 4096
// SamplingMessages maps a server's sampling messages onto chat messages. Both
// MCP sampling host paths use it -- the daemon's chat handler and the agent
// worker's task handler -- so the same server is answered the same way
// wherever the client runs. A non-text content block or an unknown role is
// rejected rather than silently dropped: answering from a partial prompt would
// be a wrong answer, not a degraded one.
func SamplingMessages(req protocol.SamplingRequest) ([]chat.Message, error) {
if len(req.Messages) == 0 {
return nil, errors.New("mcp sampling: the request has no messages")
}
messages := make([]chat.Message, 0, len(req.Messages))
for i, message := range req.Messages {
if message.Content.Type != "" && message.Content.Type != "text" {
return nil, fmt.Errorf("mcp sampling: message %d has unsupported content type %q", i, message.Content.Type)
}
var role chat.Role
switch message.Role {
case "user":
role = chat.RoleUser
case "assistant":
role = chat.RoleAssistant
default:
return nil, fmt.Errorf("mcp sampling: message %d has unsupported role %q", i, message.Role)
}
messages = append(messages, chat.Message{Role: role, Content: message.Content.Text})
}
return messages, nil
}
// SamplingMaxTokens bounds a delegated completion to the request's own
// maxTokens, falling back to DefaultSamplingMaxTokens, and never past the
// model's own output ceiling (zero when the ceiling is unknown). A
// reasoning-class model gets no bound at all: its provider rejects the
// `max_tokens` parameter the chat-completions provider emits for a non-zero
// bound. Both the daemon's chat path and the agent worker answer sampling
// with this, so the same server gets the same bound on either path.
func SamplingMaxTokens(requested, modelCeiling int, reasoning bool) int {
maxTokens := requested
if maxTokens <= 0 {
maxTokens = DefaultSamplingMaxTokens
}
if modelCeiling > 0 && maxTokens > modelCeiling {
maxTokens = modelCeiling
}
if reasoning {
return 0
}
return maxTokens
}
+98
View File
@@ -0,0 +1,98 @@
package agentexec
import (
"strings"
"testing"
"github.com/samcharles93/ai-sdk/chat"
protocol "github.com/samcharles93/archie-core/internal/tools/mcp"
)
func TestSamplingMessagesMapsRolesAndRejectsUnsupportedInput(t *testing.T) {
tests := []struct {
name string
request protocol.SamplingRequest
want []chat.Message
wantErr string
}{
{
name: "user and assistant text map to chat roles",
request: protocol.SamplingRequest{Messages: []protocol.SamplingMessage{
{Role: "user", Content: protocol.SamplingContent{Type: "text", Text: "2+2?"}},
{Role: "assistant", Content: protocol.SamplingContent{Type: "", Text: "4"}},
}},
want: []chat.Message{
{Role: chat.RoleUser, Content: "2+2?"},
{Role: chat.RoleAssistant, Content: "4"},
},
},
{
name: "no messages is a refusal",
request: protocol.SamplingRequest{},
wantErr: "the request has no messages",
},
{
name: "non-text content is a refusal",
request: protocol.SamplingRequest{Messages: []protocol.SamplingMessage{
{Role: "user", Content: protocol.SamplingContent{Type: "image"}},
}},
wantErr: "unsupported content type",
},
{
name: "unknown role is a refusal",
request: protocol.SamplingRequest{Messages: []protocol.SamplingMessage{
{Role: "system", Content: protocol.SamplingContent{Type: "text", Text: "hi"}},
}},
wantErr: "unsupported role",
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
got, err := SamplingMessages(tc.request)
if tc.wantErr != "" {
if err == nil || !strings.Contains(err.Error(), tc.wantErr) {
t.Fatalf("SamplingMessages error = %v, want it to mention %q", err, tc.wantErr)
}
return
}
if err != nil {
t.Fatalf("SamplingMessages error = %v, want nil", err)
}
if len(got) != len(tc.want) {
t.Fatalf("SamplingMessages returned %d messages, want %d", len(got), len(tc.want))
}
for i := range got {
if got[i].Role != tc.want[i].Role || got[i].Content != tc.want[i].Content {
t.Errorf("message %d = %+v, want %+v", i, got[i], tc.want[i])
}
}
})
}
}
func TestSamplingMaxTokens(t *testing.T) {
tests := []struct {
name string
requested int
ceiling int
reasoning bool
wantTokens int
}{
{name: "requested bound is honoured", requested: 64, ceiling: 1024, wantTokens: 64},
{name: "absent request falls back to the default", requested: 0, ceiling: 8192, wantTokens: DefaultSamplingMaxTokens},
{name: "request is capped by the model ceiling", requested: 8192, ceiling: 1024, wantTokens: 1024},
{name: "unknown ceiling keeps the request", requested: 8192, ceiling: 0, wantTokens: 8192},
{name: "reasoning model gets no bound", requested: 64, ceiling: 1024, reasoning: true, wantTokens: 0},
{name: "reasoning model with absent request gets no bound", requested: 0, ceiling: 0, reasoning: true, wantTokens: 0},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
if got := SamplingMaxTokens(tc.requested, tc.ceiling, tc.reasoning); got != tc.wantTokens {
t.Fatalf("SamplingMaxTokens(%d, %d, %v) = %d, want %d", tc.requested, tc.ceiling, tc.reasoning, got, tc.wantTokens)
}
})
}
}
+12
View File
@@ -93,6 +93,18 @@ func TestSystemLogHandlerPublishesToTheTasksSystemSubject(t *testing.T) {
if entry.Fields["component"] != "gate" {
t.Errorf("Fields[component] = %v, want gate", entry.Fields["component"])
}
// The wire entry must carry the record's own event time. The daemon files
// a task's records under the time the event happened (see
// logging.TaskRegistry.Write), so a producer that dropped or re-stamped it
// here would collapse a run's timing before it ever left the container.
next.mu.Lock()
wantTime := next.records[0].Time
next.mu.Unlock()
if entry.Time.IsZero() {
t.Error("Entry.Time is the zero time, want the record's own event time")
} else if !entry.Time.Equal(wantTime) {
t.Errorf("Entry.Time = %s, want the record's event time %s", entry.Time, wantTime)
}
}
func TestSystemLogHandlerAlwaysTeesToNextRegardlessOfPublishOutcome(t *testing.T) {
@@ -0,0 +1,93 @@
package agentworker
import (
"log/slog"
"testing"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/taskrun"
"github.com/samcharles93/archie-core/internal/tools"
)
// guardrailRunYAML is a repository-none workflow with one agent stage: a task
// run reaches AgentStage.handleResult once, and the engine that recorded that
// outcome is observable by its call count and by the decision a low threshold
// earns.
const guardrailRunYAML = "id: guardrail\nrepository: none\nsteps:\n" +
" - type: agent.run\n settings:\n mission: first\n"
// TestProductionWorkerDependenciesBuildGuardrails pins the producer: the
// process that runs agent stages is archie-agent, so its composition root must
// build the guardrail engine every TaskContext records against. A daemon-built
// engine can never reach this process -- it is a separate binary -- so before
// this wiring TaskContext.Guardrails was nil on every production run and no
// decision was ever recorded.
func TestProductionWorkerDependenciesBuildGuardrails(t *testing.T) {
deps, err := productionWorkerDependencies()
if err != nil {
t.Fatalf("productionWorkerDependencies: %v", err)
}
if deps.guardrails == nil {
t.Fatal("worker composition built no guardrail engine: TaskContext.Guardrails stays nil and no agent-stage decision is recorded")
}
}
// TestRunTaskRecordsGuardrailDecision is the end-to-end half: a workflow run
// whose TaskContext carries the engine records its agent stage's outcome. Before
// the wiring the engine was never assigned, so the run recorded zero -- the
// guardrail engine observed nothing for any task.
func TestRunTaskRecordsGuardrailDecision(t *testing.T) {
ctx := t.Context()
st := pgstore.Open(t)
task, err := st.EnqueueChatTask(ctx, "", "", "guardrail recording", "", "guardrail", "", nil)
if err != nil {
t.Fatalf("seed task: %v", err)
}
if err := st.Transition(ctx, task.ID, task.Status, workflow.StatusRunning, "started"); err != nil {
t.Fatalf("claim task: %v", err)
}
task.Status = workflow.StatusRunning
task.WorkflowDefinitionYAML = guardrailRunYAML
task.WorkflowDefinitionDigest = workflow.DigestDefinition(guardrailRunYAML)
if err := st.Update(ctx, task); err != nil {
t.Fatalf("seed task: %v", err)
}
workDir := t.TempDir()
// A threshold a single stage reaches turns the recorded outcome into an
// actual guardrail decision, so the test proves the run consulted the
// engine rather than merely holding a reference.
engine := tools.NewGuardrailEngine(tools.ToolCallGuardrailConfig{
NoProgressWarnAfter: 1,
HardStopAfterWarnRepeat: 1,
})
request := taskrun.Request{
Task: task,
Repo: config.Repo{},
Cfg: config.Config{Models: map[string]string{"builder": "p/m"}}.ForTask(),
WorkflowDefinition: guardrailRunYAML,
}
dependencies := taskDependencies{
store: st,
trees: &fakeScratchTrees{dir: workDir},
steps: testSteps(t),
guardrails: engine,
}
fakeRunner := runnerFactory(func(map[string]agentexec.Provider, *slog.Logger) agentexec.Runner {
return stubRunner{}
})
if _, err := runTask(ctx, request, dependencies, fakeRunner, workDir, slog.New(slog.DiscardHandler)); err != nil {
t.Fatalf("runTask: %v", err)
}
if got := engine.TotalCalls(); got != 1 {
t.Fatalf("guardrail engine recorded %d tool outcomes, want 1 (the agent stage): TaskContext.Guardrails is not wired to the engine the run was given", got)
}
if !engine.HardStopped() {
t.Fatal("guardrail engine issued no decision for the run's agent stage: TaskContext.Guardrails is not wired to the engine the run was given")
}
}
+16 -8
View File
@@ -23,18 +23,26 @@ type mcpProviderSet struct {
registry *tools.Registry
}
type mcpProviderBuilder func(config.MCPServer) (toolprovider.Engine, string, error)
type mcpProviderBuilder func(config.MCPServer, mcp.SamplingHandler) (toolprovider.Engine, string, error)
// startMCPProviders creates MCP transports from config, starts them,
// discovers tools, and registers them into a local registry. Returns
// nil when there are no servers configured.
func startMCPProviders(ctx context.Context, servers []config.MCPServer, log *slog.Logger) (*mcpProviderSet, error) {
return startMCPProvidersWith(ctx, servers, log, buildMCPProvider)
// discovers tools, and registers them into a local registry. A non-nil
// sampling handler answers server-initiated sampling/createMessage requests
// (nil leaves the method refused, the client's own default). Returns nil when
// there are no servers configured.
func startMCPProviders(
ctx context.Context,
servers []config.MCPServer,
sampling mcp.SamplingHandler,
log *slog.Logger,
) (*mcpProviderSet, error) {
return startMCPProvidersWith(ctx, servers, sampling, log, buildMCPProvider)
}
func startMCPProvidersWith(
ctx context.Context,
servers []config.MCPServer,
sampling mcp.SamplingHandler,
log *slog.Logger,
build mcpProviderBuilder,
) (*mcpProviderSet, error) {
@@ -51,7 +59,7 @@ func startMCPProvidersWith(
continue
}
provider, transportType, err := build(server)
provider, transportType, err := build(server, sampling)
if errors.Is(err, errUnknownMCPTransport) {
log.Warn("mcp server skipped: unknown transport", "name", name, "transport", transportType)
continue
@@ -78,7 +86,7 @@ func startMCPProvidersWith(
return set, nil
}
func buildMCPProvider(server config.MCPServer) (toolprovider.Engine, string, error) {
func buildMCPProvider(server config.MCPServer, sampling mcp.SamplingHandler) (toolprovider.Engine, string, error) {
name := strings.TrimSpace(server.Name)
transportType := strings.ToLower(strings.TrimSpace(server.Transport))
if transportType == "" {
@@ -89,7 +97,7 @@ func buildMCPProvider(server config.MCPServer) (toolprovider.Engine, string, err
if err != nil {
return nil, transportType, err
}
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), transportType, nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls, mcptoolprovider.WithSamplingHandler(sampling)), transportType, nil
}
func mcpTransportForServer(
@@ -167,7 +167,7 @@ func TestBuildMCPProviderSelectsTransport(t *testing.T) {
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
provider, transportType, err := buildMCPProvider(tc.server)
provider, transportType, err := buildMCPProvider(tc.server, nil)
if transportType != tc.wantTransport {
t.Fatalf("transport = %q, want %q", transportType, tc.wantTransport)
}
@@ -344,7 +344,7 @@ func TestStartMCPProvidersPreservesOptionalProviderBehavior(t *testing.T) {
"valid-two": {id: "valid-two", entries: []tools.ToolEntry{testTool("shared")}},
}
buildCalls := make(map[string]int)
build := func(server config.MCPServer) (toolprovider.Engine, string, error) {
build := func(server config.MCPServer, _ protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) {
buildCalls[server.Name]++
switch server.Name {
case "unknown":
@@ -365,7 +365,7 @@ func TestStartMCPProvidersPreservesOptionalProviderBehavior(t *testing.T) {
{Name: "valid-one"},
{Name: "valid-two"},
}
set, err := startMCPProvidersWith(t.Context(), servers, slog.New(slog.DiscardHandler), build)
set, err := startMCPProvidersWith(t.Context(), servers, nil, slog.New(slog.DiscardHandler), build)
if err != nil {
t.Fatalf("error = %v, want nil when valid providers remain available", err)
}
@@ -409,14 +409,14 @@ func TestStartMCPProvidersReturnsNilWithoutAvailableProviders(t *testing.T) {
{
name: "unknown transport is skipped without error",
servers: []config.MCPServer{{Name: "unknown"}},
build: func(config.MCPServer) (toolprovider.Engine, string, error) {
build: func(config.MCPServer, protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) {
return nil, "unknown", errUnknownMCPTransport
},
},
{
name: "first provider error is returned",
servers: []config.MCPServer{{Name: "first"}, {Name: "second"}},
build: func(server config.MCPServer) (toolprovider.Engine, string, error) {
build: func(server config.MCPServer, _ protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) {
if server.Name == "first" {
return nil, "stdio", firstErr
}
@@ -430,12 +430,12 @@ func TestStartMCPProvidersReturnsNilWithoutAvailableProviders(t *testing.T) {
t.Run(tc.name, func(t *testing.T) {
build := tc.build
if build == nil {
build = func(config.MCPServer) (toolprovider.Engine, string, error) {
build = func(config.MCPServer, protocolmcp.SamplingHandler) (toolprovider.Engine, string, error) {
t.Fatal("builder called without configured servers")
return nil, "", nil
}
}
set, err := startMCPProvidersWith(t.Context(), tc.servers, slog.New(slog.DiscardHandler), build)
set, err := startMCPProvidersWith(t.Context(), tc.servers, nil, slog.New(slog.DiscardHandler), build)
if set != nil {
t.Fatalf("provider set = %#v, want nil", set)
}
+67
View File
@@ -0,0 +1,67 @@
package agentworker
import (
"context"
"errors"
"fmt"
"strings"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/ai-sdk/runtime"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/tools/mcp"
)
// taskSamplingModel is the model a task-scoped MCP server's sampling request
// is answered with: the task's builder model, the same fallback an agent stage
// whose role is unset uses (workflow.AgentStage.resolveModel) and the same
// role the daemon's chat path falls back to. Empty means the task has no model
// to answer with.
func taskSamplingModel(cfg config.TaskConfig) string {
return strings.TrimSpace(cfg.Models["builder"])
}
// taskSamplingHandler answers an MCP server's sampling/createMessage request
// from the task's own model runtime, the same way the daemon's chat path
// answers it from its chat model. The worker hosts the same configured MCP
// servers as a chat turn, so without this a server's sampling request is
// answered on one path and refused on the other. A missing runtime or model is
// a refused request, never a dropped one: the client maps the returned error
// to a JSON-RPC error for that request alone.
func taskSamplingHandler(llm *runtime.Runtime, cfg config.TaskConfig) mcp.SamplingHandler {
return func(ctx context.Context, req mcp.SamplingRequest) (mcp.SamplingResult, error) {
if llm == nil {
return mcp.SamplingResult{}, errors.New("mcp sampling: no model runtime is configured")
}
model := taskSamplingModel(cfg)
if model == "" {
return mcp.SamplingResult{}, errors.New("mcp sampling: no builder model is configured")
}
messages, err := agentexec.SamplingMessages(req)
if err != nil {
return mcp.SamplingResult{}, err
}
limits := cfg.ModelLimits[model]
options := core.GenerateOptions{
Messages: messages,
System: req.SystemPrompt,
MaxSteps: 1,
MaxTokens: agentexec.SamplingMaxTokens(req.MaxTokens, limits.MaxOutputTokens, limits.Reasoning),
}
if req.Temperature != nil {
options.Temperature = float32(*req.Temperature)
}
result, err := llm.Chat(ctx, model, options)
if err != nil {
return mcp.SamplingResult{}, fmt.Errorf("mcp sampling: %w", err)
}
return mcp.SamplingResult{
Model: model,
Role: "assistant",
Content: mcp.SamplingContent{Type: "text", Text: result.Text},
StopReason: string(result.FinishReason),
}, nil
}
}
@@ -0,0 +1,193 @@
package agentworker
import (
"encoding/json"
"io"
"net/http"
"net/http/httptest"
"reflect"
"strings"
"sync"
"testing"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/tools/mcp"
)
// capturedChatRequest is the JSON body the OpenAI-compatible provider sent for
// the last call, which is where the max-token parameter is chosen.
type capturedChatRequest struct {
mu sync.Mutex
body map[string]any
}
func (c *capturedChatRequest) get() map[string]any {
c.mu.Lock()
defer c.mu.Unlock()
return c.body
}
// newCapturingChatAPI answers every completion and records the wire body, so a
// test can assert the parameter the provider actually emitted rather than an
// option the handler merely set.
func newCapturingChatAPI(t *testing.T, capture *capturedChatRequest) *httptest.Server {
t.Helper()
api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var body map[string]any
_ = json.NewDecoder(r.Body).Decode(&body)
capture.mu.Lock()
capture.body = body
capture.mu.Unlock()
w.Header().Set("Content-Type", "application/json")
_, _ = io.WriteString(w, `{"id":"chatcmpl-1","object":"chat.completion","created":1,"model":"test",`+
`"choices":[{"index":0,"message":{"role":"assistant","content":"ok"},"finish_reason":"stop"}],`+
`"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}`)
}))
t.Cleanup(api.Close)
return api
}
// newSamplingModelServer stands in for an OpenAI-compatible provider so a
// sampling request can be answered without a real backend.
func newSamplingModelServer(t *testing.T) *httptest.Server {
t.Helper()
api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = io.WriteString(w, `{"id":"chatcmpl-1","object":"chat.completion","created":1,"model":"gpt-5.6",`+
`"choices":[{"index":0,"message":{"role":"assistant","content":"four"},"finish_reason":"stop"}],`+
`"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}`)
}))
t.Cleanup(api.Close)
return api
}
func testSamplingRequest() mcp.SamplingRequest {
return mcp.SamplingRequest{
Messages: []mcp.SamplingMessage{{
Role: "user",
Content: mcp.SamplingContent{Type: "text", Text: "2+2?"},
}},
MaxTokens: 16,
}
}
// TestTaskSamplingHandlerAnswersFromWorkerModel proves a task-scoped MCP
// server's sampling request is answered by the worker's own model. A task
// hosts the same configured MCP servers as a chat turn, so without this the
// server is answered on the chat path and refused on the task path.
func TestTaskSamplingHandlerAnswersFromWorkerModel(t *testing.T) {
api := newSamplingModelServer(t)
llm := agentexec.NewRuntime(map[string]agentexec.Provider{
"openai": {Class: "openai", BaseURL: api.URL},
})
handler := taskSamplingHandler(llm, config.TaskConfig{Models: map[string]string{"builder": "openai/gpt-5.6"}})
result, err := handler(t.Context(), testSamplingRequest())
if err != nil {
t.Fatalf("sampling handler = %v, want a completion", err)
}
if result.Model != "openai/gpt-5.6" {
t.Errorf("result.Model = %q, want the task's builder model", result.Model)
}
if result.Role != "assistant" || result.Content.Type != "text" || result.Content.Text != "four" {
t.Errorf("result = %+v, want an assistant text completion", result)
}
}
// TestTaskSamplingHandlerRefusesCleanly proves a worker with no usable model
// answers the request with an error instead of panicking or dropping it: the
// server sees a failed request, not a dead session.
func TestTaskSamplingHandlerRefusesCleanly(t *testing.T) {
tests := []struct {
name string
llm bool
model string
want string
}{
{name: "no model runtime", llm: false, model: "openai/gpt-5.6", want: "no model runtime"},
{name: "no builder model configured", llm: true, want: "no builder model"},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
llm := agentexec.NewRuntime(nil)
if tc.llm {
llm = agentexec.NewRuntime(map[string]agentexec.Provider{"openai": {Class: "openai"}})
}
models := map[string]string{}
if tc.model != "" {
models["builder"] = tc.model
}
_, err := taskSamplingHandler(llm, config.TaskConfig{Models: models})(t.Context(), testSamplingRequest())
if err == nil {
t.Fatal("sampling handler returned no error with no usable model")
}
if !strings.Contains(err.Error(), tc.want) {
t.Errorf("error = %q, want it to mention %q", err, tc.want)
}
})
}
}
// TestTaskSamplingBoundFollowsModelClass proves the worker consumes the
// reasoning flag carried in TaskConfig.ModelLimits: a reasoning-class builder
// model gets no max-token bound (its provider rejects the max_tokens parameter
// the chat-completions provider emits), while a classic model gets the
// request's own bound.
func TestTaskSamplingBoundFollowsModelClass(t *testing.T) {
tests := []struct {
name string
reasoning bool
wantBound bool
wantValue int
}{
{name: "reasoning model", reasoning: true},
{name: "classic model", wantBound: true, wantValue: 16},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
capture := &capturedChatRequest{}
api := newCapturingChatAPI(t, capture)
llm := agentexec.NewRuntime(map[string]agentexec.Provider{
"openai": {Class: "openai", BaseURL: api.URL},
})
cfg := config.TaskConfig{
Models: map[string]string{"builder": "openai/gpt-5.6"},
ModelLimits: map[string]config.ModelLimits{
"openai/gpt-5.6": {MaxOutputTokens: 128000, Reasoning: tc.reasoning},
},
}
if _, err := taskSamplingHandler(llm, cfg)(t.Context(), testSamplingRequest()); err != nil {
t.Fatalf("sampling handler error = %v", err)
}
bound, present := capture.get()["max_tokens"]
if present != tc.wantBound {
t.Fatalf("request body max_tokens present = %v (value %v), want %v; body = %v", present, bound, tc.wantBound, capture.get())
}
if present && bound != float64(tc.wantValue) {
t.Fatalf("request body max_tokens = %v, want %d; body = %v", bound, tc.wantValue, capture.get())
}
})
}
}
// TestBuildMCPProviderWiresTaskSamplingHandler proves the worker's MCP
// provider builder hands the provider the sampling handler, so the seam a task
// run builds providers through is the one that answers sampling -- not only
// the handler in isolation.
func TestBuildMCPProviderWiresTaskSamplingHandler(t *testing.T) {
handler := taskSamplingHandler(agentexec.NewRuntime(map[string]agentexec.Provider{
"openai": {Class: "openai"},
}), config.TaskConfig{Models: map[string]string{"builder": "openai/gpt-5.6"}})
provider, _, err := buildMCPProvider(config.MCPServer{Name: "sampling", Command: "server"}, handler)
if err != nil {
t.Fatalf("buildMCPProvider: %v", err)
}
field := reflect.ValueOf(provider).Elem().FieldByName("samplingHandler")
if field.IsNil() {
t.Fatal("task MCP provider carries no sampling handler: a task-scoped server's sampling/createMessage request is refused")
}
}
-272
View File
@@ -1,272 +0,0 @@
package agentworker
import (
"context"
"fmt"
"strings"
"github.com/samcharles93/ai-sdk/agent"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/ai-sdk/runtime"
"github.com/samcharles93/ai-sdk/toolkit"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/taskrun"
)
// newReviewerFor builds the workflow.Reviewer for one task run, or nil
// when the repo has not opted into review (Repo.ReviewEnabled == false)
// or no providers are configured. Model resolution mirrors AgentStage's
// own role->"builder" fallback (agent.go): Models["reviewer"], falling
// back to Models["builder"].
func newReviewerFor(req taskrun.Request) workflow.Reviewer {
if !req.Repo.ReviewEnabled {
return nil
}
return NewOperatorReviewer(req.Cfg.Models, req.Providers)
}
// NewOperatorReviewer builds the workflow.Reviewer for an operator-triggered
// review, resolved from daemon-level models and providers rather than a task
// run. It shares newReviewerFor's role->"builder" model fallback but drops
// the Repo.ReviewEnabled gate: the operator asked for the review explicitly,
// so "not opted in" is not a reason to refuse. It returns nil when no model
// resolves (no reviewer/builder model configured) or no provider runtime
// builds, so the caller can report a clear "review not configured" result.
func NewOperatorReviewer(models map[string]string, providers map[string]agentexec.Provider) workflow.Reviewer {
modelRef := ReviewerModel(models)
if modelRef == "" {
return nil
}
rt := agentexec.NewRuntime(providers)
if rt == nil {
return nil
}
return newSubagentReviewer(rt, modelRef)
}
// ReviewerModel resolves the reviewer role's model with the builder fallback.
// It is the single source of truth for the role->"builder" rule, shared by
// the workflow stage (via NewOperatorReviewer/newReviewerFor) and the
// operator-triggered review's result reporting so the reported model and the
// model actually run cannot diverge.
func ReviewerModel(models map[string]string) string {
if models["reviewer"] != "" {
return models["reviewer"]
}
return models["builder"]
}
// defaultReviewMaxSteps bounds the reviewer's tool loop when neither
// ReviewRequest.MaxSteps nor the repo's configured budget set one.
const defaultReviewMaxSteps = 10
// subagentReviewer implements workflow.Reviewer using ai-sdk's
// agent.Subagent: a nested, synchronous generation in this same worker
// process, with its own model, system prompt, toolset, and step budget.
//
// Isolation is two-fold. Conversation isolation is structural: Subagent.Run
// only ever sends a prompt string, never the implementer's message
// history. Workspace isolation is built by the caller (StageReview via
// workflow.Trees.Snapshot): reviewerToolSet is rooted at that snapshot
// directory and holds only read-only tools -- never the worker's own
// toolset, which carries the worktreerpc publication grant a reviewer must
// not be able to reach.
type subagentReviewer struct {
runtime *runtime.Runtime
modelRef string
}
// newSubagentReviewer constructs a Reviewer that runs on modelRef, resolved
// through rt (the same provider runtime the worker's own agent runner
// uses). rt must be non-nil.
func newSubagentReviewer(rt *runtime.Runtime, modelRef string) *subagentReviewer {
return &subagentReviewer{runtime: rt, modelRef: modelRef}
}
var _ workflow.Reviewer = (*subagentReviewer)(nil)
// Review runs one adversarial review. It never returns a Go error: every
// failure mode (unresolvable model, a Subagent.Run error, a truncated
// run) folds into the returned ReviewReport, per
// docs/prds/adversarial-self-review.md section 4's fail-closed contract.
func (s *subagentReviewer) Review(ctx context.Context, req workflow.ReviewRequest) workflow.ReviewReport {
if s.runtime == nil {
return workflow.NewNotRunReviewReport("no provider runtime configured for the reviewer")
}
provider, model, err := s.runtime.ChatProvider(ctx, s.modelRef)
if err != nil {
return workflow.NewNotRunReviewReport(fmt.Sprintf("resolve reviewer model %q: %v", s.modelRef, err))
}
var findings []workflow.ReviewFinding
var checks []workflow.ReviewCheck
tools := reviewerToolSet(req.SnapshotDir, &findings, &checks)
maxSteps := req.MaxSteps
if maxSteps <= 0 {
maxSteps = defaultReviewMaxSteps
}
sub := agent.Subagent{
Provider: provider,
Model: model,
System: reviewerSystemPrompt,
Tools: tools,
MaxSteps: maxSteps,
}
summary, runErr := sub.Run(ctx, reviewerPrompt(req))
if runErr != nil {
// A truncated or errored run still yields whatever the reviewer
// captured before it ran out of budget -- those findings are real
// and must not be discarded just because the run's own
// conclusion never arrived (docs/prds/adversarial-self-review.md
// section 1, "findings return through a closure"). Zero captured
// findings on error means the reviewer never got anywhere, which
// fail-closed treats as not having run at all.
if len(findings) == 0 {
return workflow.NewNotRunReviewReport(runErr.Error())
}
return completedReview(findings, checks, "")
}
return completedReview(findings, checks, summary)
}
// completedReview builds a completed report carrying the captured findings
// and the properties the reviewer verified clean.
func completedReview(findings []workflow.ReviewFinding, checks []workflow.ReviewCheck, summary string) workflow.ReviewReport {
report := workflow.NewCompletedReviewReport(findings, summary)
report.Checked = checks
return report
}
// reviewerSystemPrompt instructs the reviewer per CLAUDE.md's own
// adversarial-review discipline: assume every line is wrong until proven
// correct, work the checklist, report only what a fresh reader can verify
// from what it was given.
const reviewerSystemPrompt = `You are a fresh adversarial code reviewer. You did not write this change and have no access to how or why it was written -- only what is given to you below.
Assume every line is wrong until you have verified it is correct. Read whole files with your read tool, not just diff hunks, before concluding a call site or interface is satisfied. Use grep/find to check for other call sites a change affects.
Check for: dead code, unchecked errors, hardcoded values that should be parameters, interface-satisfaction defects, nil-pointer risk, goroutine leaks, races and unsynchronized shared state.
For every defect you find, call record_finding with: the file and line, a one-sentence defect statement, a concrete failure scenario (specific inputs or state that produce the wrong output or a crash -- not a hypothetical), a verdict, a level, and a category.
A finding must describe wrong behaviour or a crash. Style, formatting, naming, and preference nits are out of contract -- do not report them; they are exactly the padding that teaches an operator to skim past a findings list.
As you clear each checklist property, call record_checked with the property and how you verified it (which files or call sites you read). Record every property you actually checked and found correct, even when you also found defects; a review that reports no findings must still record what it checked, because "I checked and it is fine" and "I did not look" must not read the same.
Verdict is "confirmed" only when you have traced the actual failure -- read the code paths involved and can state exactly how it goes wrong. Verdict is "plausible" for a real worry you have not fully traced. Only a "confirmed" finding at level "error" blocks the pull request; do not inflate a plausible worry to confirmed/error to make it count -- an unjustified block is worse than a missed one, because it teaches the operator to stop trusting your reports.
Level is "error" for a defect that blocks; "warn" for something worth knowing but not blocking.
When a confirmed defect's fix is mechanical, and only then, pass suggestion: the exact text that should replace the anchored line, so the author can apply it in one click. It replaces that line exactly, so include the whole line (indentation included) and nothing else, and never guess -- a wrong one-click fix is worse than none. Do not pass a suggestion for a plausible finding, or for a fix you cannot state as a single line.
When you have finished checking, reply with a short summary of what you checked and what you found (or that you found nothing). If you find nothing, say so plainly -- reporting zero findings on properties you actually checked is a valid and expected outcome, not a failure to find something.`
// reviewerPrompt renders the reviewer's mission: the diff and issue text.
// The snapshot itself is not embedded here -- it reaches the reviewer only
// through its read-only toolset, rooted at SnapshotDir, never as prompt
// text the reviewer could mistake for something it already checked.
func reviewerPrompt(req workflow.ReviewRequest) string {
var b strings.Builder
b.WriteString("Review the following change. The full file tree at the reviewed commit is available through your tools; ")
b.WriteString("start by reading the files the diff touches, not just the diff itself.\n\n")
b.WriteString("<issue>\n")
b.WriteString(req.IssueText)
b.WriteString("\n</issue>\n\n<diff>\n")
b.WriteString(req.Diff)
b.WriteString("\n</diff>\n")
return b.String()
}
// reviewerToolSet builds the reviewer's read-only toolset, rooted at
// snapshotDir, plus the structured capture tools that append directly to
// findings and checks. This is a distinct toolset built fresh for each
// review -- never the worker's own registry, which holds write/edit/shell
// tools and the worktreerpc publication grant.
func reviewerToolSet(snapshotDir string, findings *[]workflow.ReviewFinding, checks *[]workflow.ReviewCheck) core.ToolSet {
reg := toolkit.NewRegistry()
readOnly := []toolkit.Tool{
toolkit.NewReadTool(snapshotDir, toolkit.NewReadTracker()),
toolkit.NewGrepTool(snapshotDir),
toolkit.NewFindTool(snapshotDir),
}
for _, tool := range readOnly {
_ = reg.Register(tool) // names are fixed and distinct; Register cannot fail here
}
set := reg.CoreToolSet(toolkit.NonInteractiveBridge{})
set["record_finding"] = recordFindingTool(findings)
set["record_checked"] = recordCheckedTool(checks)
return set
}
// checkInput is the reviewer-facing shape of workflow.ReviewCheck.
type checkInput struct {
Property string `json:"property" jsonschema:"description=The property or code path you verified clean, e.g. 'nil-safety of Foo callers'."`
Evidence string `json:"evidence" jsonschema:"description=How you verified it, e.g. 'read all 4 callers; each nil-checks before use'."`
}
// recordCheckedTool builds the typed capture tool the reviewer calls once per
// property it verified clean. Without it a zero-finding review reads the same
// as a review that never looked; with it, "ran and found nothing" arrives
// backed by what was actually checked.
func recordCheckedTool(checks *[]workflow.ReviewCheck) *core.Tool {
return core.NewTypedTool(
"record_checked",
"Record one property or code path you verified clean. Call this once per property you actually checked and found correct -- a review that reports no findings must still record what it checked.",
func(_ context.Context, in checkInput) (string, error) {
check := workflow.ReviewCheck{Property: in.Property, Evidence: in.Evidence}
if err := check.Validate(); err != nil {
return "record_checked rejected: " + err.Error(), nil //nolint:nilerr // rejection feedback lets the model retry with a valid check
}
*checks = append(*checks, check)
return "check recorded", nil
},
)
}
// findingInput is the reviewer-facing shape of workflow.ReviewFinding: the
// model reports plain strings for Verdict/Level/Category, validated and
// converted before being appended.
type findingInput struct {
File string `json:"file" jsonschema:"description=Repo-relative file path where the defect is located."`
Line int `json:"line" jsonschema:"description=Line number where the defect is located."`
Defect string `json:"defect" jsonschema:"description=One-sentence statement of the defect."`
FailureScenario string `json:"failure_scenario" jsonschema:"description=Concrete inputs or state that produce the wrong output or a crash -- not a hypothetical."`
Suggestion string `json:"suggestion,omitempty" jsonschema:"description=Optional. The exact replacement for the anchored line, when the fix is mechanical and you are certain of it -- it is offered as a one-click apply, so an approximate or partial line is worse than none. Only a confirmed finding may carry one; omit it for a plausible finding. Single line only."`
Verdict string `json:"verdict" jsonschema:"description=Only 'confirmed' may block. Use 'plausible' for a real worry you have not fully traced.,enum=confirmed|plausible"`
Level string `json:"level" jsonschema:"description=error blocks when confirmed; warn is advisory only.,enum=error|warn"`
Category string `json:"category" jsonschema:"enum=dead-code|unchecked-error|hardcoded-value|interface-satisfaction|nil-risk|goroutine-leak|race|other"`
}
// recordFindingTool builds the typed capture tool the reviewer must call
// to report a defect. Rejecting an invalid finding with a plain-text
// message (rather than a Go error) lets the model see what was wrong and
// retry, the same environmental-enforcement pattern the rest of the
// agent-loop tool contract uses.
func recordFindingTool(findings *[]workflow.ReviewFinding) *core.Tool {
return core.NewTypedTool(
"record_finding",
"Report one defect found during review. Call this once per defect; do not summarize multiple defects into one call.",
func(_ context.Context, in findingInput) (string, error) {
finding := workflow.ReviewFinding{
File: in.File,
Line: in.Line,
Defect: in.Defect,
FailureScenario: in.FailureScenario,
Suggestion: in.Suggestion,
Verdict: workflow.ReviewVerdict(in.Verdict),
Level: workflow.ReviewLevel(in.Level),
Category: workflow.ReviewCategory(in.Category),
}
if err := finding.Validate(); err != nil {
return "record_finding rejected: " + err.Error(), nil //nolint:nilerr // rejection feedback lets the model retry with a valid finding
}
*findings = append(*findings, finding)
return "finding recorded", nil
},
)
}
-252
View File
@@ -1,252 +0,0 @@
package agentworker
import (
"context"
"errors"
"os"
"path/filepath"
"slices"
"testing"
"github.com/samcharles93/ai-sdk/agent"
"github.com/samcharles93/ai-sdk/chat"
"github.com/samcharles93/archie-core/internal/domain/workflow"
)
// TestReviewerToolSetIsReadOnlyAndHasNoMutationPath asserts, as a
// construction fact rather than a prompt claim, that the reviewer's
// toolset carries no tool capable of writing, editing, or running a
// shell command -- the class of tool that could reach the worktreerpc
// publication grant or otherwise mutate anything. Read/grep/find plus the
// findings-capture tool are the entire surface.
func TestReviewerToolSetIsReadOnlyAndHasNoMutationPath(t *testing.T) {
var findings []workflow.ReviewFinding
var checks []workflow.ReviewCheck
set := reviewerToolSet(t.TempDir(), &findings, &checks)
names := make([]string, 0, len(set))
for name := range set {
names = append(names, name)
}
slices.Sort(names)
want := []string{"find", "grep", "read", "record_checked", "record_finding"}
slices.Sort(want)
if !slices.Equal(names, want) {
t.Fatalf("reviewer toolset = %v, want exactly %v (no write/edit/shell)", names, want)
}
}
// TestReviewerToolSetIsRootedAtTheGivenSnapshot asserts the read tool
// cannot read outside the snapshot directory it was constructed with --
// it has no path back to the implementer's actual worktree.
func TestReviewerToolSetIsRootedAtTheGivenSnapshot(t *testing.T) {
snapshot := t.TempDir()
if err := os.WriteFile(filepath.Join(snapshot, "in-snapshot.txt"), []byte("ok\n"), 0o644); err != nil {
t.Fatal(err)
}
outside := t.TempDir()
if err := os.WriteFile(filepath.Join(outside, "secret.txt"), []byte("nope\n"), 0o644); err != nil {
t.Fatal(err)
}
var findings []workflow.ReviewFinding
var checks []workflow.ReviewCheck
set := reviewerToolSet(snapshot, &findings, &checks)
readTool := set["read"]
if readTool == nil {
t.Fatal("reviewer toolset has no read tool")
}
out, err := readTool.Execute(t.Context(), `{"path":"in-snapshot.txt"}`)
if err != nil {
t.Fatalf("read in-snapshot file: %v", err)
}
if !containsSubstr(out, "ok") {
t.Errorf("read in-snapshot file = %q, want it to contain the file's content", out)
}
// Tool failures are encoded in-band in the returned content, not as a
// Go error (toolkit.Registry.CoreToolSet's own contract) -- an escape
// attempt must reject there, not succeed.
escapeOut, err := readTool.Execute(t.Context(), `{"path":"`+filepath.Join(outside, "secret.txt")+`"}`)
if err != nil {
t.Fatalf("read outside-snapshot path: %v", err)
}
if containsSubstr(escapeOut, "nope") {
t.Errorf("read tool returned content from outside the snapshot: %q", escapeOut)
}
if !containsSubstr(escapeOut, "escapes") {
t.Errorf("read tool output = %q, want a path-confinement rejection", escapeOut)
}
}
// TestRecordFindingToolAppendsToCapturedSlice asserts the capture-tool
// contract: findings are recorded via the closure over the findings
// slice, not returned from Subagent.Run's text.
func TestRecordFindingToolAppendsToCapturedSlice(t *testing.T) {
var findings []workflow.ReviewFinding
tool := recordFindingTool(&findings)
input := `{"file":"main.go","line":10,"defect":"nil deref","failure_scenario":"calling Foo(nil) panics","verdict":"confirmed","level":"error","category":"nil-risk"}`
if _, err := tool.Execute(t.Context(), input); err != nil {
t.Fatalf("record_finding: %v", err)
}
if len(findings) != 1 {
t.Fatalf("captured %d findings, want 1", len(findings))
}
if !findings[0].Blocking() {
t.Error("captured finding is not blocking, want confirmed+error to block")
}
}
// TestRecordFindingToolRejectsInvalidVerdictWithoutError asserts an
// invalid finding is rejected in-band (so the model can retry) rather
// than surfacing as a hard tool error, and is not captured.
func TestRecordFindingToolRejectsInvalidVerdictWithoutError(t *testing.T) {
var findings []workflow.ReviewFinding
tool := recordFindingTool(&findings)
input := `{"file":"main.go","line":1,"defect":"x","failure_scenario":"y","verdict":"maybe","level":"error","category":"other"}`
out, err := tool.Execute(t.Context(), input)
if err != nil {
t.Fatalf("record_finding returned a Go error for invalid input: %v", err)
}
if !containsSubstr(out, "rejected") {
t.Errorf("record_finding output = %q, want a rejection message", out)
}
if len(findings) != 0 {
t.Errorf("captured %d findings, want 0 for an invalid finding", len(findings))
}
}
// TestRecordCheckedToolAppendsToCapturedSlice asserts the calibration capture
// contract: a cleared property is recorded through the closure, so a
// zero-finding review can report what it actually checked.
func TestRecordCheckedToolAppendsToCapturedSlice(t *testing.T) {
var checks []workflow.ReviewCheck
tool := recordCheckedTool(&checks)
input := `{"property":"nil-safety of Foo callers","evidence":"read all 4 callers; each nil-checks"}`
if _, err := tool.Execute(t.Context(), input); err != nil {
t.Fatalf("record_checked: %v", err)
}
if len(checks) != 1 || checks[0].Property != "nil-safety of Foo callers" {
t.Fatalf("captured checks = %+v, want one check for the recorded property", checks)
}
}
// TestRecordCheckedToolRejectsMissingEvidence asserts a check without evidence
// is rejected in-band and not captured, so "verified clean" cannot be recorded
// as a bare assertion.
func TestRecordCheckedToolRejectsMissingEvidence(t *testing.T) {
var checks []workflow.ReviewCheck
tool := recordCheckedTool(&checks)
out, err := tool.Execute(t.Context(), `{"property":"looks fine","evidence":""}`)
if err != nil {
t.Fatalf("record_checked returned a Go error for invalid input: %v", err)
}
if !containsSubstr(out, "rejected") {
t.Errorf("record_checked output = %q, want a rejection message", out)
}
if len(checks) != 0 {
t.Errorf("captured %d checks, want 0 for a check with no evidence", len(checks))
}
}
// TestCompletedReviewCarriesChecks asserts the report the reviewer returns
// carries the captured checks, not just the findings.
func TestCompletedReviewCarriesChecks(t *testing.T) {
checks := []workflow.ReviewCheck{{Property: "p", Evidence: "e"}}
report := completedReview(nil, checks, "summary")
if !report.Ran() {
t.Fatal("completedReview report did not run")
}
if len(report.Checked) != 1 || report.Checked[0].Property != "p" {
t.Fatalf("report.Checked = %+v, want the captured check", report.Checked)
}
}
// TestReviewSubagentConstructionNeverSendsConversationHistory asserts, at
// the exact agent.Subagent construction Review performs, that only a
// prompt string reaches the model. This exercises the same Subagent{}
// shape subagentReviewer.Review builds (provider, model, system prompt,
// reviewerToolSet, MaxSteps) directly against a fake chat.Provider, so it
// proves the construction fact without needing a full *runtime.Runtime:
// Subagent.Run populates GenerateOptions.Prompt and never Messages, so
// there is no code path for the implementer's transcript to travel
// through.
func TestReviewSubagentConstructionNeverSendsConversationHistory(t *testing.T) {
captured := &capturingChatProvider{}
var findings []workflow.ReviewFinding
var checks []workflow.ReviewCheck
req := workflow.ReviewRequest{
SnapshotDir: t.TempDir(),
Diff: "diff --git a/x.go b/x.go\n",
IssueText: "some issue text",
}
sub := agent.Subagent{
Provider: captured,
Model: "fake-model",
System: reviewerSystemPrompt,
Tools: reviewerToolSet(req.SnapshotDir, &findings, &checks),
MaxSteps: defaultReviewMaxSteps,
}
prompt := reviewerPrompt(req)
if _, err := sub.Run(t.Context(), prompt); err != nil {
t.Fatalf("Subagent.Run() error = %v", err)
}
if captured.lastRequest == nil {
t.Fatal("chat provider was never called")
}
// The only non-system message the model ever sees is the one
// Subagent.Run derives from the prompt string -- there is no code
// path here for a second, implementer-authored message to arrive
// alongside it.
var userMessages int
for _, m := range captured.lastRequest.Messages {
if m.Role == chat.RoleUser {
userMessages++
if m.Content != prompt {
t.Errorf("user message content = %q, want the review prompt %q", m.Content, prompt)
}
}
}
if userMessages != 1 {
t.Errorf("chat.Request carried %d user messages, want exactly 1 (the review prompt, no implementer history)", userMessages)
}
}
func containsSubstr(s, substr string) bool {
return len(substr) == 0 ||
(len(s) >= len(substr) && func() bool {
for i := 0; i+len(substr) <= len(s); i++ {
if s[i:i+len(substr)] == substr {
return true
}
}
return false
}())
}
// capturingChatProvider is a minimal chat.Provider fake that records the
// last chat.Request it received and returns a fixed, valid completion.
type capturingChatProvider struct {
lastRequest *chat.Request
}
func (c *capturingChatProvider) Name() string { return "fake" }
func (c *capturingChatProvider) Chat(_ context.Context, req chat.Request) (chat.Response, error) {
r := req
c.lastRequest = &r
return chat.Response{Content: "no findings", FinishReason: "stop"}, nil
}
func (c *capturingChatProvider) ChatStream(_ context.Context, req chat.Request) (chat.Stream, error) {
return nil, errors.New("not implemented")
}
+57 -39
View File
@@ -10,14 +10,18 @@ import (
"path/filepath"
"strconv"
"github.com/samcharles93/ai-sdk/runtime"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/prsource"
"github.com/samcharles93/archie-core/internal/installtype"
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/taskrun"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/worktree"
)
@@ -47,7 +51,15 @@ type hybridTrees struct {
worktreeUID, worktreeGID int
}
func (h *hybridTrees) Prepare(ctx context.Context, owner, repo, base string, issue int, title, body, labels string) (dir, branch string, err error) {
// Prepare binds the task's already-prepared, bind-mounted worktree. The
// daemon positioned it before the container started, so this resolves the
// directory and branch rather than doing network work. A resume target (the
// PR branch a remediation continues) is returned verbatim; a fresh target uses
// the branch the daemon computed and persisted on the task row.
func (h *hybridTrees) Prepare(ctx context.Context, owner, repo, base string, issue int, title, body, labels string, target workflow.PrepareTarget) (dir, branch string, err error) {
if target != workflow.PrepareFresh {
return h.localDir, string(target), nil
}
return h.localDir, h.branch, nil
}
@@ -106,22 +118,6 @@ func (h *hybridTrees) Snapshot(ctx context.Context, dir, destDir string) error {
return h.local.Snapshot(ctx, dir, destDir)
}
// Resume is a no-op here for the same reason Prepare is: resuming a PR
// branch needs the daemon's forge credential to fetch, so archied must run
// it against the bind-mounted worktree before the container starts, the
// same way it runs Prepare today. The container's worktree is already
// resumed by the time a remediate run reaches this stage.
func (h *hybridTrees) Resume(ctx context.Context, dir, branch string) error {
return nil
}
// Dir returns the bind-mounted worktree path archied already prepared,
// ignoring its arguments -- the sandbox has no way to independently derive
// or verify the path, same as Prepare above.
func (h *hybridTrees) Dir(owner, repo string, issue int) string {
return h.localDir
}
func (h *hybridTrees) ChangedLines(ctx context.Context, dir, base string) (int, error) {
return h.local.ChangedLines(ctx, dir, base)
}
@@ -191,6 +187,11 @@ type taskDependencies struct {
// executing half of the contract whose validating half is the control
// plane's (archie-core-fwmp).
steps *workflow.Manager
// guardrails is the guardrail engine agent stages record tool outcomes
// against. It is built by this process's composition root (the workflow
// runs in archie-agent, so the daemon's engine cannot reach it) and set on
// every TaskContext; nil means guardrails are disabled.
guardrails *tools.GuardrailEngine
}
type runnerFactory func(map[string]agentexec.Provider, *slog.Logger) agentexec.Runner
@@ -217,24 +218,25 @@ func applyToolLimits(agent agentexec.Runner, policy config.ToolPolicy, allow []s
runner.AllowTools = allow
}
// stageRunners builds the runner every agent stage uses, and the reviewer.
func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerFactory, log *slog.Logger) (agentexec.Runner, workflow.Reviewer, error) {
// stageRunners builds the runner every agent stage uses. llm is the task's
// shared model runtime (the one its MCP providers answer sampling from); the
// registry path reuses it rather than building a second one.
func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerFactory, llm *runtime.Runtime, log *slog.Logger) (agentexec.Runner, error) {
if req.Harness != nil {
// The built-in loop has no route to a model from a Kit container, so
// the review stage parks rather than running on it.
return agentexec.HarnessStages{Runner: agentexec.NewHarnessRunner(nil), Spec: *req.Harness}, nil, nil
// The built-in loop has no route to a model from a Kit container.
return agentexec.HarnessStages{Runner: agentexec.NewHarnessRunner(nil), Spec: *req.Harness}, nil
}
var agent agentexec.Runner
if mcpSet != nil && mcpSet.registry != nil {
agent = agentexec.NewLoopRunner(agentexec.NewRuntime(req.Providers), log, mcpSet.registry)
agent = agentexec.NewLoopRunner(llm, log, mcpSet.registry)
} else {
agent = newRunner(req.Providers, log)
}
if agent == nil {
return nil, nil, fmt.Errorf("no agent runner configured for task %d", req.Task.ID)
return nil, fmt.Errorf("no agent runner configured for task %d", req.Task.ID)
}
applyToolLimits(agent, req.Cfg.ToolPolicy, req.Tools)
return agent, newReviewerFor(req), nil
return agent, nil
}
// routeTask remains available for routing-only callers. Production execution
@@ -277,8 +279,14 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen
// start from.
defer restoreWorktreeOwnership(trees, workDir, log)()
// Start MCP providers and build a local tool registry.
mcpSet, mcpErr := startMCPProviders(ctx, req.MCPServers, log)
// The MCP providers a task hosts share the same model runtime its agent
// stages run on, so a server-initiated sampling request is answered from
// the task's own model rather than a second provider client.
var llm *runtime.Runtime
if len(req.MCPServers) > 0 {
llm = agentexec.NewRuntime(req.Providers)
}
mcpSet, mcpErr := startMCPProviders(ctx, req.MCPServers, taskSamplingHandler(llm, req.Cfg), log)
if mcpSet != nil {
defer mcpSet.cleanup(ctx, log)
}
@@ -286,7 +294,7 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen
log.Warn("mcp providers had errors, continuing with available tools", "err", mcpErr)
}
agent, reviewer, err := stageRunners(req, mcpSet, newRunner, log)
agent, err := stageRunners(req, mcpSet, newRunner, llm, log)
if err != nil {
return nil, err
}
@@ -310,18 +318,28 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen
}
tc := &workflow.TaskContext{
Task: req.Task,
Repo: req.Repo,
Cfg: req.Cfg.ToConfig(),
Forge: dependencies.forge,
Store: dependencies.store,
Calls: dependencies.calls,
Trees: trees,
Agent: agent,
Reviewer: reviewer,
Bus: bus,
Log: log,
Task: req.Task,
Repo: req.Repo,
Cfg: req.Cfg.ToConfig(),
Forge: dependencies.forge,
Store: dependencies.store,
Calls: dependencies.calls,
Trees: trees,
Agent: agent,
Bus: bus,
Log: log,
Guardrails: dependencies.guardrails,
}
// pr-review reads an external pull request's data from workDir, which the
// daemon already populated before this task started (daemon's
// prefetchPRReview, writing under workDir/.archie-pr-review -- the same
// host directory Docker bind-mounts at storage.WorktreeMountDir) -- never
// over the network, and never with a forge credential in this process.
// See docs/development/agent.md, "Giving the agent something new".
if req.Task.Workflow == "pr-review" {
tc.PRSource = prsource.NewFromMount(filepath.Join(workDir, prsource.PrefetchDirName))
}
if req.Repo.PersistentStorage {
memory, readErr := readProjectMemory(storage.MemoryPath)
if readErr != nil {
@@ -170,6 +170,31 @@ func TestHybridTreesPushSkipsReconciliationWhenNotConfigured(t *testing.T) {
}
}
// TestHybridTreesPrepareResolvesTheTargetBranch pins the container half of the
// workflow prepare seam: the daemon has already positioned the bind-mounted
// worktree, so the adapter resolves its directory and returns the requested
// resume target verbatim -- the branch a remediation continues -- while a fresh
// prepare returns the branch the daemon persisted on the task row.
func TestHybridTreesPrepareResolvesTheTargetBranch(t *testing.T) {
trees := &hybridTrees{localDir: "/work/issue-1", branch: "archie/fresh"}
dir, branch, err := trees.Prepare(t.Context(), "o", "r", "main", 1, "title", "", "", workflow.PrepareTarget("archie/pr-branch"))
if err != nil {
t.Fatalf("Prepare(resume): %v", err)
}
if dir != "/work/issue-1" || branch != "archie/pr-branch" {
t.Fatalf("Prepare(resume) = %q/%q, want /work/issue-1/archie/pr-branch", dir, branch)
}
dir, branch, err = trees.Prepare(t.Context(), "o", "r", "main", 1, "title", "", "", workflow.PrepareFresh)
if err != nil {
t.Fatalf("Prepare(fresh): %v", err)
}
if dir != "/work/issue-1" || branch != "archie/fresh" {
t.Fatalf("Prepare(fresh) = %q/%q, want /work/issue-1/archie/fresh", dir, branch)
}
}
func TestHybridTreesCommitReconcilesOwnershipEvenWhenCommitFails(t *testing.T) {
missing := filepath.Join(t.TempDir(), "does-not-exist")
trees := &hybridTrees{
@@ -301,8 +326,8 @@ type remoteManager struct {
branch string
}
func (r *remoteManager) Prepare(ctx context.Context, owner, repo, base string, issue int, title, body, labels string) (string, string, error) {
dir, branch, err := r.manager.Prepare(ctx, owner, repo, base, issue, title, body, labels)
func (r *remoteManager) Prepare(ctx context.Context, owner, repo, base string, issue int, title, body, labels string, target workflow.PrepareTarget) (string, string, error) {
dir, branch, err := r.manager.Prepare(ctx, owner, repo, base, issue, title, body, labels, worktree.Target(target))
if err == nil {
r.dir = dir
r.branch = branch
@@ -338,6 +363,7 @@ func newLocalRemote(t *testing.T, owner, repo string) string {
run(seed, "init", "-b", "main")
run(seed, "config", "user.name", "seeder")
run(seed, "config", "user.email", "seed@example.com")
run(seed, "config", "commit.gpgsign", "false")
if err := os.WriteFile(filepath.Join(seed, "README.md"), []byte("seed\n"), 0o644); err != nil {
t.Fatal(err)
}
@@ -347,6 +373,26 @@ func newLocalRemote(t *testing.T, owner, repo string) string {
return host
}
// hostileSigningConfig writes a global git config that makes every commit
// fail unless the fixture disables signing in the repository's own config.
func hostileSigningConfig(t *testing.T) string {
t.Helper()
path := filepath.Join(t.TempDir(), "hostile.gitconfig")
const cfg = "[user]\n\tname = Hostile\n\temail = hostile@example.com\n\tsigningkey = /nonexistent/signing-key\n[gpg]\n\tformat = ssh\n[commit]\n\tgpgsign = true\n"
if err := os.WriteFile(path, []byte(cfg), 0o600); err != nil {
t.Fatal(err)
}
return path
}
// TestNewLocalRemoteIgnoresHostSigningConfig pins the fixture's hermeticity:
// it must not depend on the developer's global git identity or a signing agent.
func TestNewLocalRemoteIgnoresHostSigningConfig(t *testing.T) {
t.Setenv("GIT_CONFIG_GLOBAL", hostileSigningConfig(t))
t.Setenv("GIT_CONFIG_NOSYSTEM", "1")
newLocalRemote(t, "acme", "todo")
}
func startEmbeddedTaskRPCServer(t *testing.T) *server.Server {
t.Helper()
srv := natssrv.RunRandClientPortServer()
@@ -407,7 +453,7 @@ func TestRunTaskExecutesBootstrapWorkflowEndToEnd(t *testing.T) {
fg := &prCapturingForge{}
manager := &worktree.Manager{WorkDir: t.TempDir(), Token: "unused", BotUser: "archie-bot", BotEmail: "archie-bot@example.com", BaseURL: "file://" + host}
remote := &remoteManager{manager: manager}
hostDir, _, err := remote.Prepare(ctx, "acme", "widget", "main", 1, task.Title, "", "bootstrap")
hostDir, _, err := remote.Prepare(ctx, "acme", "widget", "main", 1, task.Title, "", "bootstrap", workflow.PrepareFresh)
if err != nil {
t.Fatalf("prepare: %v", err)
}
@@ -613,7 +659,7 @@ func TestExecuteTaskRequestUsesInfrastructureRPCDependencies(t *testing.T) {
BotEmail: "archie-bot@example.com",
BaseURL: "file://" + host,
}
hostDir, branch, err := daemonTrees.Prepare(ctx, "acme", "rpc-widget", "main", 2, task.Title, "", "bootstrap")
hostDir, branch, err := daemonTrees.Prepare(ctx, "acme", "rpc-widget", "main", 2, task.Title, "", "bootstrap", worktree.Fresh)
if err != nil {
t.Fatal(err)
}
@@ -650,7 +696,7 @@ func TestExecuteTaskRequestUsesInfrastructureRPCDependencies(t *testing.T) {
Cfg: config.Config{}.ForTask(),
WorktreeGrant: grant,
}
response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler), testSteps(t))
response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler), testSteps(t), nil)
if err != nil {
t.Fatal(err)
}
@@ -705,7 +751,7 @@ func TestExecuteTaskRequestForwardsWorkflowEventsOverNATS(t *testing.T) {
BotEmail: "archie-bot@example.com",
BaseURL: "file://" + host,
}
hostDir, branch, err := daemonTrees.Prepare(ctx, "acme", "events-widget", "main", 3, task.Title, "", "bootstrap")
hostDir, branch, err := daemonTrees.Prepare(ctx, "acme", "events-widget", "main", 3, task.Title, "", "bootstrap", worktree.Fresh)
if err != nil {
t.Fatal(err)
}
@@ -768,7 +814,7 @@ func TestExecuteTaskRequestForwardsWorkflowEventsOverNATS(t *testing.T) {
Cfg: config.Config{}.ForTask(),
WorktreeGrant: grant,
}
response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler), testSteps(t))
response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler), testSteps(t), nil)
if err != nil {
t.Fatal(err)
}
@@ -898,7 +944,7 @@ func TestHybridTreesForwardsChangedFileStatsToItsLocalManager(t *testing.T) {
WorkDir: t.TempDir(), Token: "unused",
BotUser: "archie-bot", BotEmail: "archie-bot@example.com", BaseURL: "file://" + host,
}
dir, branch, err := manager.Prepare(ctx, "acme", "diffstat", "main", 4, "feat: widget", "", "")
dir, branch, err := manager.Prepare(ctx, "acme", "diffstat", "main", 4, "feat: widget", "", "", worktree.Fresh)
if err != nil {
t.Fatalf("prepare: %v", err)
}
@@ -34,7 +34,7 @@ type fakeScratchTrees struct {
dir string
}
func (f *fakeScratchTrees) Prepare(context.Context, string, string, string, int, string, string, string) (string, string, error) {
func (f *fakeScratchTrees) Prepare(context.Context, string, string, string, int, string, string, string, workflow.PrepareTarget) (string, string, error) {
return f.dir, "", nil
}
@@ -60,7 +60,7 @@ func TestExecuteTaskRequestStartsWorkflowCallCallee(t *testing.T) {
const callerYAML = "id: caller\nrepository: none\ninputs:\n src_ip: {type: string}\nsteps:\n - type: workflow.call\n settings:\n workflow: callee\n inputs: {src_ip: \"inputs.src_ip\"}\n wait: false\n - type: agent.run\n settings:\n mission: report\n"
// A real caller row, claimed and running, so the store's enqueue reads
// the same row shape production does.
task, err := st.EnqueueChatTask(ctx, "", "", "workflow.call integration", "", "caller", "")
task, err := st.EnqueueChatTask(ctx, "", "", "workflow.call integration", "", "caller", "", nil)
if err != nil {
t.Fatalf("seed caller task: %v", err)
}
+17 -9
View File
@@ -15,6 +15,7 @@ import (
"github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps"
"github.com/samcharles93/archie-core/internal/storage"
"github.com/samcharles93/archie-core/internal/taskrun"
"github.com/samcharles93/archie-core/internal/tools"
)
const rpcTimeout = 60 * time.Second
@@ -64,6 +65,11 @@ type workerDependencies struct {
// definitions against, registered by the composition root before the first
// task is served (infrastructure/workflowsteps is the provider set).
steps *workflow.Manager
// guardrails is the guardrail engine every served task records agent-stage
// outcomes against, built once at this process's composition root.
// archie-agent is the process that runs the stages, so the engine that
// observes them lives here; a live engine cannot cross the task handoff.
guardrails *tools.GuardrailEngine
}
// productionWorkerDependencies builds the worker's process dependencies. The
@@ -87,7 +93,8 @@ func productionWorkerDependencies() (workerDependencies, error) {
<-ctx.Done()
log.Info("archie-agent shutting down")
},
steps: steps,
steps: steps,
guardrails: tools.NewGuardrailEngine(tools.DefaultGuardrailConfig()),
}, nil
}
@@ -134,7 +141,7 @@ func run(ctx context.Context, settings Settings, log *slog.Logger, dependencies
log.Info("system log publisher attached", "task", taskID)
subscription, err := transport.SubscribeTasks(ctx, taskID, func(ctx context.Context, request taskrun.Request) (*taskrun.Response, error) {
return executeTaskRequest(ctx, request, transport, workDir, log, dependencies.steps)
return executeTaskRequest(ctx, request, transport, workDir, log, dependencies.steps, dependencies.guardrails)
}, log)
if err != nil {
log.Error("taskrun subscribe failed", "err", err)
@@ -159,15 +166,16 @@ type taskServiceTransport interface {
EventPublisher() agentexec.EventPublisher
}
func executeTaskRequest(ctx context.Context, request taskrun.Request, transport taskServiceTransport, workDir string, log *slog.Logger, steps *workflow.Manager) (*taskrun.Response, error) {
func executeTaskRequest(ctx context.Context, request taskrun.Request, transport taskServiceTransport, workDir string, log *slog.Logger, steps *workflow.Manager, guardrails *tools.GuardrailEngine) (*taskrun.Response, error) {
log.Info("running task", "task", request.Task.ID, "repo", request.Repo.FullName(), "issue", request.Task.IssueNumber)
dependencies := taskDependencies{
forge: transport.Forger(request.Task.Identity, rpcTimeout),
store: transport.Store(rpcTimeout),
calls: transport.Calls(rpcTimeout),
trees: transport.Trees(request.Task.Identity, request.WorktreeGrant, rpcTimeout),
events: transport.EventPublisher(),
steps: steps,
forge: transport.Forger(request.Task.Identity, rpcTimeout),
store: transport.Store(rpcTimeout),
calls: transport.Calls(rpcTimeout),
trees: transport.Trees(request.Task.Identity, request.WorktreeGrant, rpcTimeout),
events: transport.EventPublisher(),
steps: steps,
guardrails: guardrails,
}
response, err := runTask(ctx, request, dependencies, newTaskRunner, workDir, log)
if err != nil {
+255 -68
View File
@@ -17,6 +17,7 @@ import (
"path/filepath"
"slices"
"strings"
"sync"
"sync/atomic"
"syscall"
"time"
@@ -31,6 +32,7 @@ import (
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/daemon"
"github.com/samcharles93/archie-core/internal/domain/access"
"github.com/samcharles93/archie-core/internal/domain/agent"
"github.com/samcharles93/archie-core/internal/domain/applystatus"
"github.com/samcharles93/archie-core/internal/domain/curator"
"github.com/samcharles93/archie-core/internal/domain/eda/module"
@@ -39,6 +41,7 @@ import (
"github.com/samcharles93/archie-core/internal/domain/health"
"github.com/samcharles93/archie-core/internal/domain/identity"
domainmemory "github.com/samcharles93/archie-core/internal/domain/memory"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/domain/scheduling"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/workflow"
@@ -59,6 +62,7 @@ import (
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/infrastructure/taskactions"
"github.com/samcharles93/archie-core/internal/infrastructure/toolbuilder"
"github.com/samcharles93/archie-core/internal/infrastructure/transcription"
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/plugin/pluginextract"
@@ -165,8 +169,22 @@ type boot struct {
// closes; the Gateway also holds its serve claim on it.
chatPool *pgxpool.Pool
// catalog, catalogModels and catalogMu are the model catalog the process
// last loaded and the model references it contributes. The refresh loop
// replaces both together while the config paths read them, so they are one
// value behind one lock rather than two fields that can disagree.
catalogMu sync.RWMutex
catalog modelcatalog.Snapshot
catalogModels []string
// catalogCachePath is where the catalog's last download is cached, beside
// the config file. Empty when boot had no file path to derive it from.
catalogCachePath string
// catalogURL overrides the catalog endpoint. Zero in production:
// modelcatalog defaults to models.dev. Set only by tests.
catalogURL string
// catalogRefreshInterval is how often the running daemon re-reads the
// catalog. The daemon's refresh loop reads it; zero means the default.
catalogRefreshInterval time.Duration
bus *events.Bus
// taskActionsConn is the standalone Gateway process's own NATS connection:
@@ -238,29 +256,51 @@ type boot struct {
// unrelated call.
embeddings domainembedding.Client
toolReg *tools.Registry
chatModels *chatModelManager
personas *gateway.PersonaRegistry
chatTasks gateway.TaskCreator
chatController *gateway.StoreTaskController
// chatPRReviewer is the operator-triggered PR review capability, built
// once and shared by every channel so a review in flight on one channel
// is deduplicated against the same request on another (single-flight).
chatPRReviewer gateway.ChatPRReviewer
// transcriber is the optional voice-transcription capability. It is built
// beside the chat runtime from this process's own [models]/[providers],
// which is the model-owning side of the Messaging boundary: a channel
// frontend carries a voice note's bytes across the inbound wire, and this
// process turns them into text before the turn is recorded. Nil when no
// role is configured or the provider credential did not resolve; a turn
// then keeps the frontend's media note rather than failing.
transcriber messaging.Transcriber
toolReg *tools.Registry
chatModels *chatModelManager
personas *gateway.PersonaRegistry
chatTasks gateway.TaskCreator
chatController *gateway.StoreTaskController
defaultChatIdentity string
updateService *releaseupdate.Service
startGateways []func()
capabilityHost *plugin.Host
startGateways []func()
capabilityHost *plugin.Host
// pluginReconciler loads plugin, module and secret-engine files dropped into
// the running config's directories without a restart. Nil before boot's
// startPluginReconcile, and in processes that load no directory (the
// Gateway), where a stored plugin-settings change still layers but loads
// nothing.
pluginReconciler *pluginReconciler
trees *worktree.Manager
worktreeGrants *worktreerpc.Grants
identityRunners []*daemon.IdentityRunner
memEngines *domainmemory.Registry
curatorRegistry *curator.Registry
curatorRuntime *curator.Runtime
guardrails *tools.GuardrailEngine
providerRegistry *toolprovider.Registry
d *daemon.Daemon
// mcpMu guards mcpApplied, which records the MCP servers the provider
// registry was last built from, keyed by configured name. A live
// tool-settings change diffs the stored server set against it so an
// unchanged server is left running and untouched (mcp_reconcile.go); the
// mutex is held because registerTools runs at boot while the
// control-plane watch may already be applying an update.
mcpMu sync.Mutex
mcpApplied map[string]appliedMCPServer
// mcpProvider builds the engine for one configured MCP server. Nil uses
// configuredMCPProvider; a test injects a fake so the live reconciliation
// can run without spawning a server process.
mcpProvider func(config.MCPServer) (toolprovider.Engine, error)
d *daemon.Daemon
// schedulingEngine is the cron/scheduling ticker engine (setupScheduling).
// Nil when no chat task creator is configured, in which case startServices
// leaves it unstarted rather than running with no reachable job kind.
@@ -534,19 +574,146 @@ func (b *boot) handleRequeue(ctx context.Context, requeue int64, once bool) (boo
return !once, nil
}
// catalogState returns the model catalog the process is running and the model
// references it contributes. Both together, under one lock: the refresh loop
// replaces them as a pair.
func (b *boot) catalogState() (modelcatalog.Snapshot, []string) {
b.catalogMu.RLock()
defer b.catalogMu.RUnlock()
return b.catalog, b.catalogModels
}
// setCatalogState installs a loaded catalog. Called only after everything it
// has to reach has been built, so a read that fails leaves the previous
// snapshot running.
func (b *boot) setCatalogState(snapshot modelcatalog.Snapshot, models []string) {
b.catalogMu.Lock()
defer b.catalogMu.Unlock()
b.catalog = snapshot
b.catalogModels = models
}
// loadCatalog reads the model catalog once at boot and merges it into the
// running config. A catalog that cannot be read is not fatal -- the configured
// providers and models keep running, and the refresh loop retries the same
// read -- but a catalog that *is* read must reach the config the process runs
// on, not just the boot struct the chat runtime was built from.
func (b *boot) loadCatalog(ctx context.Context, cfgPath string) {
catalog, err := modelcatalog.Load(ctx, modelcatalog.Options{
CachePath: filepath.Join(filepath.Dir(cfgPath), "models.json"),
Getenv: b.secrets.Getenv,
Configured: b.cfg.Providers,
})
b.catalog = catalog
b.catalogCachePath = filepath.Join(filepath.Dir(cfgPath), "models.json")
catalog, err := modelcatalog.Load(ctx, b.catalogOptions(b.catalogCachePath))
if err != nil {
b.log.Warn("model catalog unavailable; using configured providers and models", "err", err)
return
}
b.catalogModels = applyModelCatalog(&b.cfg, catalog)
b.log.Info("model catalog loaded", "providers", len(catalog.Providers), "models", len(b.catalogModels))
models := applyModelCatalog(&b.cfg, catalog)
// applyModelCatalog writes into the boot struct, while every consumer
// reads config.Holder. Publishing the merged copy here is what puts the
// catalog's model limits and discovered providers into the running config;
// without it the first live update would be the first snapshot to carry
// them.
b.cfgHolder.Set(b.cfg.Clone())
b.setCatalogState(catalog, models)
b.log.Info("model catalog loaded", "providers", len(catalog.Providers), "models", len(models))
}
// seedSoul writes the starter SOUL beside the config on first run, so the
// identity a user can edit exists before the SOUL loader (#439) reads it. It
// runs on the full process's boot tail rather than in loadConfig: an offline
// command such as `-requeue` reads the config but must not write the operator's
// files. A failure is logged, not fatal -- the loader falls back to the embedded
// default, so a read-only config directory must not stop the process
// (docs/prds/soul.md, "Prompt and failure contract").
func (b *boot) seedSoul(cfgPath string) {
result, err := configuration.SeedSoul(cfgPath, agent.ShippedSoul())
if err != nil {
b.log.Warn("soul: starter file unavailable", "err", err)
return
}
if result.Action == configuration.SoulCreated {
b.log.Info("soul: starter file written", "path", result.Path, "action", result.Action)
}
}
// refreshModelCatalog re-reads the catalog and republishes everything derived
// from it, so a credential that becomes resolvable after boot or a model added
// upstream reaches the running config, the dashboard and the chat runtime
// without a restart. It is the live half of loadCatalog.
//
// A failed read keeps the snapshot already running: the model list must not go
// blank because the catalog service had a bad minute. The caller decides
// whether the failure is fatal to it -- the refresh loop logs and retries.
func (b *boot) refreshModelCatalog(ctx context.Context) error {
catalog, err := modelcatalog.Load(ctx, b.catalogOptions(b.catalogCachePath))
if err != nil {
return err
}
base := b.cfgHolder.Get().Clone()
models := applyModelCatalog(&base, catalog)
cfg, _, err := b.runtimeConfig(ctx, base)
if err != nil {
return err
}
// Committed only once the layered config passed validation, so a refused
// layering leaves the catalog the process is running alone.
b.setCatalogState(catalog, models)
b.publishConfig(ctx, cfg)
b.rebuildChatModelRuntime(cfg)
b.log.Info("model catalog refreshed", "providers", len(catalog.Providers), "models", len(models))
return nil
}
// catalogOptions is the one place the catalog read options are built: boot and
// every live refresh read the same endpoint, the same cache file and the same
// credential lookup. Getenv is the secrets registry, not the raw process
// environment, so a key a secret engine starts resolving after boot is visible
// to the next refresh. A variable exported into the shell after the process
// started is not, and cannot be: the process environment is fixed at exec.
func (b *boot) catalogOptions(cachePath string) modelcatalog.Options {
opts := modelcatalog.Options{
URL: b.catalogURL,
CachePath: cachePath,
}
if b.secrets != nil {
opts.Getenv = b.secrets.Getenv
}
if b.cfgHolder != nil {
opts.Configured = b.cfgHolder.Get().Providers
}
return opts
}
// modelCatalogRefreshInterval is how often the running daemon re-reads the
// model catalog. The document itself changes on the order of weeks, but a
// credential a secret engine starts resolving can appear at any moment, so the
// interval trades one cheap HTTP read against how long an operator waits for a
// newly usable provider to show up. It is deliberately the daemon's own
// cadence and not an operator setting: the catalog is derived state, not a
// stored resource, and a knob with no second consumer would be a setting that
// parses and does nothing.
const modelCatalogRefreshInterval = time.Hour
// startModelCatalogRefresh re-reads the catalog on an interval for the life of
// the process. It belongs to the daemon, which owns the published
// configuration; the standalone Gateway reads the catalog once at boot.
func (b *boot) startModelCatalogRefresh(ctx context.Context) {
every := b.catalogRefreshInterval
if every <= 0 {
every = modelCatalogRefreshInterval
}
go func() {
ticker := time.NewTicker(every)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
if err := b.refreshModelCatalog(ctx); err != nil {
b.log.Warn("model catalog refresh failed; keeping the loaded catalog", "err", err)
}
}
}
}()
}
// setupObservability builds the event bus and dashboard server. Every event is persisted (stamped with its row id) and
@@ -702,7 +869,7 @@ func (b *boot) startEmbeddedNATS(ctx context.Context) (string, string, error) {
// not require Docker; repository tasks park instead of falling back to a host
// model loop.
func (b *boot) setupContainers(ctx context.Context) func() {
containerPool, storeBackend, closeDocker := startContainers(ctx, b.cfg, b.log)
containerPool, storeBackend, closeDocker := startContainers(ctx, b.cfgHolder, b.secrets, b.log)
b.containerPool = containerPool
b.storeBackend = storeBackend
return closeDocker
@@ -725,6 +892,26 @@ func (b *boot) setupEmbeddings(cfg config.Config, log *slog.Logger) {
}
}
// setupTranscriber builds the optional voice-transcription capability. It is
// the model-owning side of the Messaging Service boundary: the channel
// frontend carries a voice note's audio bytes across the inbound wire but
// holds no provider credential, so this process turns them into text before
// the turn's message is recorded. Like setupEmbeddings, a client is wired only
// when models["transcription"] names a provider/model and that provider's
// credential resolves; a configured-but-unusable role is logged so the
// degradation is visible, while a role never configured is silent.
func (b *boot) setupTranscriber(cfg config.Config, log *slog.Logger) {
client, ok := transcription.New(cfg.Models, cfg.Providers, transcription.Options{
ResolveSecret: b.secrets.Resolve,
})
if ok {
b.transcriber = client
log.Info("voice transcription enabled", "role", transcription.Role)
} else if cfg.Models[transcription.Role] != "" {
log.Warn("voice transcription configured but unavailable; capability disabled", "role", transcription.Role)
}
}
// setupLLMAndChat wires the runtime, tool registry, model management,
// personas and the dashboard's chat service.
func (b *boot) setupLLMAndChat(ctx context.Context) error {
@@ -930,10 +1117,10 @@ func (b *boot) loadPlugins() error {
// buildWorktreeManager composes the process-wide worktree manager from the
// resolved primary forge credential and the loaded config. Both process roots
// own one: the daemon works tasks in it, and the Gateway materialises a pull
// request head in it when an operator asks for a review (boot.prReviewer
// refuses to build a reviewer without one, so a Gateway that skips this step
// advertises no review_pr). It reads only, so it has nothing to report.
// own one: the daemon works tasks in it, and the Gateway used it to
// materialise a pull request head for the now-removed synchronous
// operator-review path (archie-core-afbk.7). It reads only, so it has
// nothing to report.
//
// Identity managers are not built here: buildTreesAndIdentities builds one per
// identity, each in its own WorkDir, because the Gateway must not own daemon
@@ -1212,26 +1399,20 @@ func (b *boot) setupCurators(ctx context.Context) {
b.addCleanup(shutdownCuratorRegistry(reg, log))
}
func (b *boot) setupGuardrails() {
log := b.log
gc := tools.DefaultGuardrailConfig()
b.guardrails = tools.NewGuardrailEngine(gc)
log.Info(
"guardrail engine enabled",
"exact_failure_warn", gc.ExactFailureWarnAfter,
"same_tool_failure_warn", gc.SameToolFailureWarnAfter,
"no_progress_warn", gc.NoProgressWarnAfter,
)
}
// registerTools registers the tool providers with a lifecycle: workspace
// file/shell tools and optional MCP servers. Memory tools
// (memory_create/update/delete/list) are not registered here -- they are
// built per turn onto the resolved Subject's scopes
// (internal/gateway/turn_memory_tool.go), not once at boot.
func (b *boot) registerTools(ctx context.Context) error {
cfg, log := b.cfg, b.log
// The running config, not b.cfg: boot is where the first stored version of
// every kind was already layered in, and a watch that applied a later one
// before this point published through the holder.
cfg, log := b.cfgHolder.Get(), b.log
b.providerRegistry = toolprovider.NewRegistry(b.toolReg)
b.mcpMu.Lock()
b.mcpApplied = make(map[string]appliedMCPServer, len(cfg.Tools.MCPServers))
b.mcpMu.Unlock()
// Workspace file and shell tools. Registered only when a workspace is
// configured: these read, write and execute, so the directory is a
// deliberate choice rather than a default.
@@ -1250,7 +1431,7 @@ func (b *boot) registerTools(ctx context.Context) error {
log.Info("workspace tools disabled (chat.workspace is unset)")
}
for _, srv := range cfg.Tools.MCPServers {
provider, err := configuredMCPProvider(srv, cfg.WorkDir)
provider, err := b.buildMCPProvider(srv)
if err != nil {
log.Warn("mcp tool provider skipped", "name", srv.Name, "err", err)
continue
@@ -1265,6 +1446,9 @@ func (b *boot) registerTools(ctx context.Context) error {
log.Warn("mcp tool provider skipped", "name", srv.Name, "err", err)
continue
}
b.mcpMu.Lock()
b.mcpApplied[strings.TrimSpace(srv.Name)] = appliedMCPServer{server: srv, id: provider.Manifest().ID}
b.mcpMu.Unlock()
}
if err := b.capabilityHost.Register(b.providerRegistry); err != nil {
log.Error("tool-provider capability registration failed", "err", err)
@@ -1314,21 +1498,7 @@ func (b *boot) registerStandaloneTools() {
// web_fetch. Registered directly rather than as a tool provider: it has
// no process to start or stop, so the provider lifecycle would buy
// nothing. Disabled by configuration returns nil and advertises nothing.
if entry := webfetch.Tool(webfetch.Config{
Enabled: cfg.Tools.WebFetch.IsEnabled(),
Timeout: cfg.Tools.WebFetch.Timeout.Std(),
MaxBytes: cfg.Tools.WebFetch.MaxBytes,
AllowPrivateNetworks: cfg.Tools.WebFetch.AllowPrivateNetworks,
}); entry != nil {
if err := b.toolReg.Register(*entry); err != nil {
log.Warn("web_fetch registration failed", "err", err)
} else {
log.Info("web fetch enabled",
"allow_private_networks", cfg.Tools.WebFetch.AllowPrivateNetworks)
}
} else {
log.Info("web fetch disabled")
}
b.registerWebFetchTool(cfg)
// send_file. Rooted at the same workspace as the file tools and gated
// by the same confinement, because it hands a host file to an outbound
@@ -1347,6 +1517,30 @@ func (b *boot) registerStandaloneTools() {
b.registerMinimaxTool(cfg, log)
}
// registerWebFetchTool registers web_fetch from cfg. Split out of
// registerStandaloneTools because a live tool-settings change rebuilds the
// entry: the one a boot built captured its config at construction, so it
// cannot read a changed value per call.
func (b *boot) registerWebFetchTool(cfg config.Config) {
log := b.log
entry := webfetch.Tool(webfetch.Config{
Enabled: cfg.Tools.WebFetch.IsEnabled(),
Timeout: cfg.Tools.WebFetch.Timeout.Std(),
MaxBytes: cfg.Tools.WebFetch.MaxBytes,
AllowPrivateNetworks: cfg.Tools.WebFetch.AllowPrivateNetworks,
})
if entry == nil {
log.Info("web fetch disabled")
return
}
if err := b.toolReg.Register(*entry); err != nil {
log.Warn("web_fetch registration failed", "err", err)
return
}
log.Info("web fetch enabled",
"allow_private_networks", cfg.Tools.WebFetch.AllowPrivateNetworks)
}
// registerMinimaxTool registers generate_video. Off by default -- see
// MinimaxConfig's doc comment, it spends real API credits per call -- and,
// unlike web_fetch, needs a resolved credential before it can be
@@ -1394,7 +1588,6 @@ func (b *boot) buildDaemon() {
Bus: b.bus,
Forge: b.forgeClient,
Trees: b.trees,
CapabilityHost: b.capabilityHost,
Storage: b.storeBackend,
Log: log,
Tasks: b.natsClient,
@@ -1403,8 +1596,6 @@ func (b *boot) buildDaemon() {
StateStoreGrants: b.stateStoreGrants,
ContainerPool: b.containerPool,
KitLauncher: b.kitLauncher,
Guardrails: b.guardrails,
ToolRegistry: b.toolReg,
Identities: b.identityRunners,
RootIdentityID: identity.StableID(configuredIdentityNames(b.cfg)[0]),
TaskLogs: b.taskLogs,
@@ -1412,6 +1603,7 @@ func (b *boot) buildDaemon() {
KindWorkflows: b.kindWorkflows,
LabelWorkflows: b.labelWorkflows,
WorkflowDefinitions: b.workflowDefinitions,
WorkflowEnablement: b.controlPlane,
Playbooks: b.playbooks,
}
if identities, ok := b.stateStore.(identity.Repository); ok {
@@ -1507,15 +1699,9 @@ func (b *boot) setupForgeWebhook() {
// The reaction publisher is the consumer's supply side: the same typed
// reaction the poll produces, keyed source-independently, so webhook and
// poll deliveries of one review dedup (pr-review-remediation.md
// decision 2).
publishReaction := func(ctx context.Context, reaction workintake.ReviewCommentEnvelope) error {
payload, err := reaction.Encode()
if err != nil {
return err
}
return b.d.Tasks.PublishUnique(ctx, reaction.Subject(), reaction.IdempotencyKey(), payload)
}
receiver := forgewebhook.New(secretValue, cfg.Dispatch.Trigger, cfg.Label, cfg.BotUser, b.d.PublishTask, publishReaction, log)
// decision 2). The daemon's PublishReaction is the single reaction write
// path: it stamps the root org a webhook delivery would otherwise lack.
receiver := forgewebhook.New(secretValue, cfg.Dispatch.Trigger, cfg.Label, cfg.BotUser, b.d.PublishTask, b.d.PublishReaction, log)
host, port := parseListenAddr(cfg.Forge.WebhookAddr, "0.0.0.0", 8645)
addr := fmt.Sprintf("%s:%d", host, port)
srv := &http.Server{Addr: addr, Handler: receiver}
@@ -1565,10 +1751,11 @@ func (b *boot) configOrigins() []webui.ConfigOrigin {
// the daemon's own configuration state. The daemon is the configuration
// owner, so it is the process that renders this view (archie-core-ml30).
func (b *boot) configViewInput(ctx context.Context) webui.ConfigViewInput {
catalog, _ := b.catalogState()
in := webui.ConfigViewInput{
Config: b.cfgHolder.Get(),
Provenance: b.configOrigins(),
Catalog: catalogView(b.catalog),
Catalog: catalogView(catalog),
}
if b.lastReload != nil {
status := b.lastReload()
+1 -1
View File
@@ -109,7 +109,7 @@ func TestConnectEmbeddedNATSUsesManagedWorkerBridge(t *testing.T) {
DockerClient: dockerClient,
Network: "workers",
RequireHostGateway: true,
}, slog.New(slog.DiscardHandler))
}, nil, slog.New(slog.DiscardHandler))
if err != nil {
t.Fatalf("container.NewPool = %v", err)
}
+40 -14
View File
@@ -18,10 +18,13 @@ type chatModelManager struct {
mu sync.RWMutex
models []string
active string
// catalogs are the non-role sources the model set is derived from, kept
// so SetConfigured can rebuild it after a live settings update without a
// caller re-passing them.
catalogs [][]string
// configured, explicit and catalog are the sources the offered set is
// derived from: the role assignments (live via SetConfigured), the
// [chat].models catalog (fixed for the process), and the model catalog's
// own refs (replaced wholesale by SetModelCatalog).
configured map[string]string
explicit []string
catalog []string
details map[string]gateway.ModelDetails
providerNames map[string]string
}
@@ -63,13 +66,29 @@ func mergeModelRefs(configured map[string]string, catalogs ...[]string) []string
}
func newChatModelManager(configured map[string]string, catalogs ...[]string) *chatModelManager {
return &chatModelManager{
models: mergeModelRefs(configured, catalogs...),
active: pickChatDefault(configured),
catalogs: append([][]string(nil), catalogs...),
explicit := make([]string, 0, len(catalogs))
for _, catalog := range catalogs {
explicit = append(explicit, catalog...)
}
m := &chatModelManager{
configured: configured,
explicit: explicit,
details: make(map[string]gateway.ModelDetails),
providerNames: make(map[string]string),
}
m.active = pickChatDefault(configured)
m.setModelsLocked()
return m
}
// setModelsLocked re-derives the offered set from the three sources and keeps
// the active selection when the new set still carries it, falling back the way
// construction does when it does not.
func (m *chatModelManager) setModelsLocked() {
m.models = mergeModelRefs(m.configured, m.explicit, m.catalog)
if !slices.Contains(m.models, m.active) {
m.active = pickChatDefault(m.configured)
}
}
// SetConfigured re-derives the model set the manager offers after a live
@@ -81,16 +100,22 @@ func newChatModelManager(configured map[string]string, catalogs ...[]string) *ch
func (m *chatModelManager) SetConfigured(configured map[string]string) {
m.mu.Lock()
defer m.mu.Unlock()
models := mergeModelRefs(configured, m.catalogs...)
if !slices.Contains(models, m.active) {
m.active = pickChatDefault(configured)
}
m.models = models
m.configured = configured
m.setModelsLocked()
}
func (m *chatModelManager) ApplyModelCatalog(snapshot modelcatalog.Snapshot) {
// SetModelCatalog replaces the model catalog's contribution to the manager:
// the references it offers, the provider display names and the per-model
// details. The previous snapshot's entries are dropped rather than merged --
// a model or provider the catalog no longer publishes must stop being offered
// and described, and these maps are the manager's own state rather than a
// second catalogue to fall back on.
func (m *chatModelManager) SetModelCatalog(snapshot modelcatalog.Snapshot, models []string) {
m.mu.Lock()
defer m.mu.Unlock()
m.catalog = slices.Clone(models)
m.details = make(map[string]gateway.ModelDetails)
m.providerNames = make(map[string]string)
for _, provider := range snapshot.Providers {
m.providerNames[provider.ID] = provider.Name
for _, model := range provider.Models {
@@ -104,6 +129,7 @@ func (m *chatModelManager) ApplyModelCatalog(snapshot modelcatalog.Snapshot) {
}
}
}
m.setModelsLocked()
}
func (m *chatModelManager) ProviderDisplayName(provider string) string {
+14 -3
View File
@@ -12,8 +12,10 @@ import (
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/ai-sdk/runtime"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/daemon"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/installtype"
@@ -29,6 +31,10 @@ type chatSetup struct {
// running yet at this point, so the reload-safe Holder is mostly a
// formality, but matching the daemon's API keeps callers honest.
Cfg *config.Holder
// ToolLimits resolves the tool-output policy at each turn, so a live
// tool-settings update reaches the next chat turn's tool options rather
// than the value captured when the runner was built.
ToolLimits func() agentexec.ToolLimits
// LLM resolves the provider runtime at each use: a live provider-settings
// or model-role-assignments update swaps the runtime wholesale (ai-sdk's
// Runtime caches the provider instances it built), so the pointer cannot
@@ -41,7 +47,6 @@ type chatSetup struct {
ChatTaskLister gateway.ChatTaskLister
ChatTaskLogs gateway.ChatTaskLogReader
ChatTaskActor gateway.ChatTaskActor
ChatPRReviewer gateway.ChatPRReviewer
DefaultChatIdentity string
// Bus carries primary-input events (archie-core-035): a completed
// chat turn is published here so input-driven curators can wake. Nil
@@ -64,6 +69,12 @@ type chatSetup struct {
// process makes, which the /status health source reads back. Nil disables
// recording (the recorder's methods tolerate that rather than panicking).
ProviderOutcomes *providerOutcomeRecorder
// Transcriber is the voice-transcription capability built by
// setupChatRuntime from this process's own [models]/[providers]. Every turn
// runner carries it so a speech attachment is transcribed before its
// message is recorded. Nil disables the capability (no role configured, or
// the provider credential did not resolve), leaving the frontend's note.
Transcriber messaging.Transcriber
}
// daemonRunningVersions reports the component versions this process can
@@ -176,13 +187,12 @@ func newChatTurnRunner(
Sessions: sessionStore,
Models: s.ChatModels,
Personas: s.Personas,
Model: newChatTurnModel(s.LLM, s.ToolReg, cfg.Chat.MaxSteps, toolLimits(cfg), s.ProviderOutcomes),
Model: newChatTurnModel(s.LLM, s.ToolReg, cfg.Chat.MaxSteps, s.ToolLimits, s.ProviderOutcomes),
TaskLister: s.ChatTaskLister,
Tasks: s.ChatTasks,
TaskLogs: s.ChatTaskLogs,
TaskActor: s.ChatTaskActor,
TaskIdentity: s.DefaultChatIdentity,
PRReviewer: s.ChatPRReviewer,
Bus: s.Bus,
BotUser: cfg.BotUser,
Channel: channel,
@@ -192,6 +202,7 @@ func newChatTurnRunner(
MemoryEngine: s.MemoryEngine,
MemoryWriter: s.MemoryWriter,
UserIdentity: userIdentityResolver(),
Transcriber: s.Transcriber,
Log: s.Log,
})
if err := runner.Recover(ctx); err != nil && s.Log != nil {
+109 -19
View File
@@ -23,7 +23,10 @@ type chatTurnModel struct {
llm func() *runtime.Runtime
registry *tools.Registry
maxSteps int
limits agentexec.ToolLimits
// limits resolves the tool-output policy at each turn, so a live
// tool-settings update is the policy the next turn builds its tool options
// with; a snapshot taken at construction would keep the boot limits.
limits func() agentexec.ToolLimits
// outcomes records each call's result for /status (see sendChatTurn).
outcomes *providerOutcomeRecorder
}
@@ -32,7 +35,7 @@ func newChatTurnModel(
llm func() *runtime.Runtime,
registry *tools.Registry,
maxSteps int,
limits agentexec.ToolLimits,
limits func() agentexec.ToolLimits,
outcomes *providerOutcomeRecorder,
) gateway.TurnModel {
return &chatTurnModel{
@@ -48,7 +51,11 @@ func (m *chatTurnModel) Prepare(
ctx context.Context,
req gateway.TurnPrepareContext,
) (gateway.PreparedTurnModel, error) {
options, err := chatGenerateOptions(ctx, nil, m.registry, m.maxSteps, m.limits, req.Extra, req.ContextWindow)
limits := agentexec.ToolLimits{}
if m.limits != nil {
limits = m.limits()
}
options, err := chatGenerateOptions(ctx, nil, m.registry, m.maxSteps, limits, req.Extra, req.ContextWindow)
if err != nil {
return nil, err
}
@@ -60,6 +67,7 @@ func (m *chatTurnModel) Prepare(
llm: m.llm(),
model: req.Model,
options: options,
reasoning: req.Reasoning,
toolInfo: toolSummaries(options.Tools),
toolTokens: gateway.EstimateTokens(string(toolSchema)),
outcomes: m.outcomes,
@@ -68,9 +76,13 @@ func (m *chatTurnModel) Prepare(
}
type preparedChatTurnModel struct {
llm *runtime.Runtime
model string
options core.GenerateOptions
llm *runtime.Runtime
model string
options core.GenerateOptions
// reasoning is the catalog's class for this model, carried from the
// prepare context so Generate can choose the output-token parameter the
// provider accepts.
reasoning bool
toolInfo []gateway.ToolSummary
toolTokens int
outcomes *providerOutcomeRecorder
@@ -100,17 +112,13 @@ func (m *preparedChatTurnModel) ToolSummaries() []gateway.ToolSummary {
return append([]gateway.ToolSummary(nil), m.toolInfo...)
}
func (m *preparedChatTurnModel) ToolSchemaTokens() int {
return m.toolTokens
}
func (m *preparedChatTurnModel) Generate(
ctx context.Context,
request gateway.TurnModelRequest,
stream gateway.TurnStream,
) (string, error) {
options := m.options
options.Messages = make([]chat.Message, len(request.Messages))
// buildTurnMessages maps the gateway's compressed history onto ai-sdk chat
// messages. The turn's inbound media is not part of stored history, so it
// is merged here into the final user message as content parts: the model
// sees the caption text plus each attachment's bytes (or URL), exactly for
// the turn it arrived in.
func buildTurnMessages(request gateway.TurnModelRequest) []chat.Message {
messages := make([]chat.Message, len(request.Messages))
for i, message := range request.Messages {
role := chat.RoleUser
switch message.Role {
@@ -119,11 +127,93 @@ func (m *preparedChatTurnModel) Generate(
case "system":
role = chat.RoleSystem
}
options.Messages[i] = chat.Message{Role: role, Content: message.Content}
messages[i] = chat.Message{Role: role, Content: message.Content}
}
parts := mediaParts(request.Media)
if len(parts) == 0 {
return messages
}
last := len(messages) - 1
// The media belongs to the inbound message, which is always the final
// user entry; if the view ever ends differently, content stays intact
// over silently attaching parts to an unrelated message.
if last < 0 || messages[last].Role != chat.RoleUser {
return messages
}
userMessages := messages[last]
userMessages.Parts = append(chat.Parts{chat.TextPart{Text: userMessages.Content}}, parts...)
userMessages.Content = ""
messages[last] = userMessages
return messages
}
// mediaParts converts inbound media attachments into ai-sdk content
// parts: images get ImagePart, everything else FilePart. An attachment
// carrying neither bytes nor a URL names nothing consumable and is
// dropped -- the turn's text still reaches the model.
func mediaParts(media []gateway.MediaAttachment) []chat.Part {
if len(media) == 0 {
return nil
}
parts := make([]chat.Part, 0, len(media))
for _, att := range media {
if att.Type == "image" {
switch {
case len(att.Data) > 0 && att.MIMEType != "":
parts = append(parts, chat.ImagePart{Data: att.Data, MediaType: att.MIMEType})
case att.URL != "":
parts = append(parts, chat.ImagePart{URL: att.URL})
}
continue
}
part := chat.FilePart{Name: att.FileName, MediaType: att.MIMEType}
if len(att.Data) > 0 {
part.Data = att.Data
} else {
part.URL = att.URL
}
if len(part.Data) == 0 && part.URL == "" {
continue
}
if part.MediaType == "" {
part.MediaType = "application/octet-stream"
}
parts = append(parts, part)
}
if len(parts) == 0 {
return nil
}
return parts
}
func (m *preparedChatTurnModel) ToolSchemaTokens() int {
return m.toolTokens
}
// maxTokensForRequest returns the output-token bound to place on an ai-sdk
// generate request for a model. A reasoning-class model gets no bound at all:
// the OpenAI chat-completions provider serialises a non-zero bound as
// `max_tokens`, which reasoning models reject with HTTP 400 ("Use
// 'max_completion_tokens' instead"), and the pinned ai-sdk release has no
// max_completion_tokens path, so no bound is the only usable form. A classic
// model keeps the caller's bound unchanged.
func maxTokensForRequest(reasoning bool, bound int) int {
if reasoning {
return 0
}
return bound
}
func (m *preparedChatTurnModel) Generate(
ctx context.Context,
request gateway.TurnModelRequest,
stream gateway.TurnStream,
) (string, error) {
options := m.options
options.Messages = buildTurnMessages(request)
// This is one provider response's output allowance, not a turn-
// continuation budget. Tool loops remain free to continue.
options.MaxTokens = request.MaxOutputTokens
options.MaxTokens = maxTokensForRequest(m.reasoning, request.MaxOutputTokens)
// A runtime swapped to nil -- a live update that left no usable provider
// configured -- is a refused turn, not a panic.
if m.llm == nil {
@@ -0,0 +1,116 @@
package archied
import (
"testing"
"github.com/samcharles93/ai-sdk/chat"
"github.com/samcharles93/archie-core/internal/gateway"
)
// TestBuildTurnMessagesAttachesMediaPartsToTheFinalUserMessage: inbound
// media only reaches the model when the turn's request is turned into
// message parts; the attachment belongs on the message the user just sent.
func TestBuildTurnMessagesAttachesMediaPartsToTheFinalUserMessage(t *testing.T) {
request := gateway.TurnModelRequest{
Messages: []gateway.CompressedMessage{
{Role: "system", Content: "sys"},
{Role: "user", Content: "what is this?"},
},
Media: []gateway.MediaAttachment{
{Type: "image", MIMEType: "image/png", Data: []byte("png-bytes")},
{Type: "image", URL: "https://example.invalid/pic.jpg"},
{Type: "document", MIMEType: "application/pdf", FileName: "report.pdf", Data: []byte("pdf-bytes")},
},
}
messages := buildTurnMessages(request)
if len(messages) != 2 {
t.Fatalf("messages = %d, want 2", len(messages))
}
if messages[0].Content != "sys" || len(messages[0].Parts) != 0 {
t.Errorf("system message = %#v, want plain content and no parts", messages[0])
}
if messages[1].Content != "" {
t.Errorf("user content = %q, want it moved into a text part", messages[1].Content)
}
parts := messages[1].Parts
if len(parts) != 4 {
t.Fatalf("user parts = %d, want text plus three media parts: %#v", len(parts), parts)
}
if text, ok := parts[0].(chat.TextPart); !ok || text.Text != "what is this?" {
t.Errorf("part 0 = %#v, want the caption text", parts[0])
}
image, ok := parts[1].(chat.ImagePart)
if !ok || string(image.Data) != "png-bytes" || image.MediaType != "image/png" {
t.Errorf("part 1 = %#v, want an image part carrying the png bytes", parts[1])
}
linked, ok := parts[2].(chat.ImagePart)
if !ok || linked.URL != "https://example.invalid/pic.jpg" {
t.Errorf("part 2 = %#v, want an image part pointing at the URL", parts[2])
}
file, ok := parts[3].(chat.FilePart)
if !ok {
t.Fatalf("part 3 = %#v, want a file part", parts[3])
}
if string(file.Data) != "pdf-bytes" || file.MediaType != "application/pdf" || file.Name != "report.pdf" {
t.Errorf("file part = %#v, want the pdf bytes with type and name", file)
}
}
// TestBuildTurnMessagesSkipsUndeliverableMedia: an attachment carrying
// neither bytes nor a URL names nothing the model can consume, so it must
// be dropped rather than sent as an empty part.
func TestBuildTurnMessagesSkipsUndeliverableMedia(t *testing.T) {
request := gateway.TurnModelRequest{
Messages: []gateway.CompressedMessage{
{Role: "user", Content: "look"},
},
Media: []gateway.MediaAttachment{
{Type: "video"},
{Type: "image", MIMEType: "image/png", Data: []byte("png")},
},
}
messages := buildTurnMessages(request)
fileSeen := false
for _, p := range messages[0].Parts {
if _, ok := p.(chat.FilePart); ok {
fileSeen = true
}
}
if fileSeen {
t.Errorf("parts = %#v, want the empty attachment dropped", messages[0].Parts)
}
if len(messages[0].Parts) != 2 {
t.Fatalf("user parts = %d, want text plus the one deliverable image", len(messages[0].Parts))
}
if text, ok := messages[0].Parts[0].(chat.TextPart); !ok || text.Text != "look" {
t.Errorf("part 0 = %#v, want the text part", messages[0].Parts[0])
}
}
// TestBuildTurnMessagesWithoutMediaKeepsPlainContent is the regression
// guard for the overwhelmingly common case: text-only turns stay exactly as
// they were, with Content and no parts.
func TestBuildTurnMessagesWithoutMediaKeepsPlainContent(t *testing.T) {
request := gateway.TurnModelRequest{
Messages: []gateway.CompressedMessage{
{Role: "system", Content: "sys"},
{Role: "user", Content: "plain"},
{Role: "assistant", Content: "reply"},
},
}
messages := buildTurnMessages(request)
for i, want := range []struct {
role chat.Role
content string
}{
{chat.RoleSystem, "sys"},
{chat.RoleUser, "plain"},
{chat.RoleAssistant, "reply"},
} {
if messages[i].Content != want.content || messages[i].Parts != nil {
t.Errorf("message %d = %#v, want content %q and no parts", i, messages[i], want.content)
}
}
}
@@ -32,29 +32,3 @@ func TestStartGatewayRuntimeSetsUpMemoryBeforeGatewayChat(t *testing.T) {
t.Fatal("startGatewayRuntime wires setupGatewayChat before setupMemoryEngine; the turn runner would capture a nil memory engine")
}
}
// TestStartGatewayRuntimeBuildsWorktreeManagerBeforeGatewayChat pins the
// Gateway's own worktree-manager ordering. The Gateway owns PR review, so
// startGatewayRuntime must compose the process-wide worktree manager before
// setupGatewayChat resolves boot.prReviewer: prReviewer returns nil without a
// manager, and a nil reviewer omits review_pr from every channel's tool set
// (internal/gateway/review_tools.go). The Gateway deliberately does not call
// buildTreesAndIdentities -- that also registers daemon identity runners it
// must not own -- so nothing at runtime connects the manager to this
// composition phase except the call this asserts on.
func TestStartGatewayRuntimeBuildsWorktreeManagerBeforeGatewayChat(t *testing.T) {
fileset := token.NewFileSet()
file, err := parser.ParseFile(fileset, "gateway.go", nil, 0)
if err != nil {
t.Fatal(err)
}
run := methodBody(t, file, "startGatewayRuntime")
trees := methodCallPosition(run, "buildWorktreeManager")
chat := methodCallPosition(run, "setupGatewayChat")
if trees == token.NoPos || chat == token.NoPos {
t.Fatalf("startGatewayRuntime call positions: buildWorktreeManager=%v setupGatewayChat=%v, want both present", trees, chat)
}
if chat < trees {
t.Fatal("startGatewayRuntime wires setupGatewayChat before buildWorktreeManager; the Gateway would resolve a nil reviewer and never advertise review_pr")
}
}
+134 -7
View File
@@ -2,12 +2,14 @@ package archied
import (
"context"
"encoding/json"
"fmt"
"time"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/applystatus"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
@@ -75,7 +77,8 @@ func (b *boot) reloadConfig(ctx context.Context, doc *configuration.Document) er
// drop them from the running config even though the file is
// unchanged. Re-apply the same merge (idempotent: a catalog that
// failed to load merges to identity).
applyModelCatalog(&doc.Config, b.catalog)
catalog, _ := b.catalogState()
applyModelCatalog(&doc.Config, catalog)
// Bounded: this runs on the signal loop, which handles nothing else
// while it waits, and a State Store that has stopped answering must
// surface as a failed reload rather than a SIGHUP that never returns.
@@ -89,6 +92,10 @@ func (b *boot) reloadConfig(ctx context.Context, doc *configuration.Document) er
old := b.cfgHolder.Get()
b.currentProvenance.Store(&doc.Provenance)
b.publishConfig(ctx, cfg)
// The container pool reads the published config on every acquire, but the
// dispatcher holds its limit; a reloaded containers.max_concurrency must
// reach it the same way a control-plane update does.
b.resizeTaskDispatcher(cfg.Containers.MaxConcurrency)
if fields := changedNonReloadableFields(old, cfg); len(fields) > 0 {
b.log.Warn("config reloaded; some changes require a restart",
"fields", fields, "paths", doc.Provenance.Paths())
@@ -257,16 +264,34 @@ func (b *boot) startLiveSettings(ctx context.Context) error {
// (b.runtimeConfig, which applies the execution budgets the settings watch
// published) and republishes through config.Holder, so the change takes
// effect without a restart. Kinds stay out of this list while a
// startup-built component still holds their value -- tool, plugin, container
// and channel settings are frozen in components built at boot and remain
// restart-required -- and a kind joins it only with a consumer that re-reads
// it. Each kind is watched in its own goroutine, exactly the shape the
// startup-built component still holds their value; none does today, so the
// list is every control-plane kind. A kind joins it only with a consumer that
// re-reads it. ToolSettingsKind is on it because applyRuntimeResourceUpdate
// reconciles the MCP provider set and rebuilds the two config-derived tool
// entries (boot.reconcileToolSettings, its consumer); a removed MCP server
// really disconnects, because it is a child process with a Stop, not a Yaegi
// interpreter. ContainerRuntimePoliciesKind is on it because both consumers
// re-read the published config: the container pool takes its image, pull
// policy, network, max-uptime and concurrency cap per acquire, and the daemon's
// dispatcher is resized after the publish (applyRuntimeResourceUpdate below).
// PluginSettingsKind is on the list because its only consumer is the directory
// reconciliation, which reads the running config each tick; a removed plugin
// or engine still cannot unload, so that kind reports the removal rather than
// requiring a restart. ChannelSettingsKind is on the list for this process's
// own re-layer; the Messaging Service, which owns the channel transports,
// reconciles them separately and restarts only the channel whose settings
// changed. Each kind is watched in its own goroutine, exactly the shape the
// workflow-execution-settings watch established.
var runtimeResourceKinds = []string{
controlplane.ProviderSettingsKind,
controlplane.ModelRoleAssignmentsKind,
controlplane.RepositoryPoliciesKind,
controlplane.SchedulingPolicyKind,
controlplane.ToolSettingsKind,
controlplane.PluginSettingsKind,
controlplane.ReviewSettingsKind,
controlplane.ChannelSettingsKind,
controlplane.ContainerRuntimePoliciesKind,
}
// startRuntimeResourceWatches keeps a watch per live kind established for the
@@ -319,12 +344,20 @@ func (b *boot) applyRuntimeResourceUpdate(ctx context.Context, kind string, upda
b.log.Error("runtime settings watch failed", "kind", kind, "err", update.Err)
return
}
if kind == controlplane.PluginSettingsKind {
if err := b.refuseSkillsDirChange(ctx); err != nil {
b.applyStatus.Report(ctx, kind, update.Version, err)
b.log.Error("plugin settings refused; the running settings stay", "version", update.Version, "err", err)
return
}
}
base := b.cfgHolder.Get()
// Boot publishes before the model catalog is merged in, so the snapshot
// this read returns can lack the catalog's model limits and discovered
// providers. The merge is idempotent, and reloadConfig re-applies it
// before layering for the same reason.
applyModelCatalog(&base, b.catalog)
catalog, _ := b.catalogState()
applyModelCatalog(&base, catalog)
cfg, _, err := b.runtimeConfig(ctx, base)
if err != nil {
// runtimeConfig reported the refusal through apply status for every
@@ -337,19 +370,113 @@ func (b *boot) applyRuntimeResourceUpdate(ctx context.Context, kind string, upda
switch kind {
case controlplane.ProviderSettingsKind, controlplane.ModelRoleAssignmentsKind:
b.rebuildChatModelRuntime(cfg)
case controlplane.ToolSettingsKind:
// The document's server set and tool entries are live now; reconcile
// them and report the reconciliation's own outcome, which is the one
// that knows whether a server failed to connect.
if err := b.reconcileToolSettings(ctx, cfg); err != nil {
b.applyStatus.Report(ctx, kind, update.Version, err)
b.log.Error("tool settings reconciled with errors; the running servers stay", "version", update.Version, "err", err)
}
case controlplane.PluginSettingsKind:
// The document's directories are live now; load what they hold and
// report the reconciliation's own outcome, which is the one that knows
// whether a removal is outstanding.
b.reconcileRuntimePlugins(ctx)
case controlplane.ContainerRuntimePoliciesKind:
// The pool reads the republished config itself; the dispatcher holds
// its limit, so a raise must be woken to admit queued work now and a
// lower must be honoured as running tasks finish.
b.resizeTaskDispatcher(cfg.Containers.MaxConcurrency)
}
}
// resizeTaskDispatcher applies a new containers.max_concurrency to the
// daemon's running dispatcher. The pool needs no poke because it reads the
// published config on every acquire. b.d is nil in the boot window in which
// the watches are already live but the daemon is not built yet; there the
// dispatcher is created later from the config the next drain reads.
func (b *boot) resizeTaskDispatcher(maxConcurrency int) {
if b.d != nil {
b.d.ResizeTaskDispatcher(maxConcurrency)
}
}
// startPluginReconcile establishes the plugin, module and secret-engine
// directory reconciliation on the apply-status restamp interval. Boot calls it
// after loadPlugins, loadWorkflows and configuredSecretRegistry have loaded
// the directories, so the seed records what is already running and the first
// tick loads only what appears or changes afterwards.
func (b *boot) startPluginReconcile(ctx context.Context) {
r := newPluginReconciler(b.log, pluginReconcileTargets{
host: b.capabilityHost,
secrets: b.secrets,
modules: b.modules,
dirs: func() config.Config { return b.cfgHolder.Get() },
relayer: func(ctx context.Context) error {
cfg, _, err := b.runtimeConfig(ctx, b.cfgHolder.Get())
if err != nil {
return err
}
b.publishConfig(ctx, cfg)
return nil
},
report: func(ctx context.Context, err error) {
b.applyStatus.Report(ctx, controlplane.PluginSettingsKind, b.applyStatus.AppliedVersion(controlplane.PluginSettingsKind), err)
},
})
b.pluginReconciler = r
r.seed()
go r.run(ctx, applystatus.RestampInterval)
}
// reconcileRuntimePlugins runs one directory reconciliation after a stored
// plugin-settings change, so a new directory loads on the tick the document
// lands rather than waiting for the poller.
func (b *boot) reconcileRuntimePlugins(ctx context.Context) {
if b.pluginReconciler == nil {
return
}
_ = b.pluginReconciler.reconcile(ctx)
}
// refuseSkillsDirChange refuses a stored plugin-settings document whose
// skills_dir differs from the value in force. skills_dir is the one directory
// with no live consumer, so a change to it stays a restart-scoped edit rather
// than a value the daemon reports as applied. The check reads the running
// config, so it cannot live in validatePluginSettings, which is value-agnostic
// by the archie-core-1143 decision.
func (b *boot) refuseSkillsDirChange(ctx context.Context) error {
var stored struct {
SkillsDir string `json:"skills_dir"`
}
_, found, err := b.controlPlane.Query(ctx, controlplane.PluginSettingsKind, func(value []byte) error {
return json.Unmarshal(value, &stored)
})
if err != nil {
return fmt.Errorf("read plugin settings: %w", err)
}
if !found {
return nil
}
if running := b.cfgHolder.Get().SkillsDir; stored.SkillsDir != running {
return fmt.Errorf("skills_dir applies on restart: stored %q, running %q", stored.SkillsDir, running)
}
return nil
}
// rebuildChatModelRuntime re-derives the gateway chat runtime's provider set
// after a live change to provider-settings or model-role-assignments. The
// turn runner reads the runtime through boot.chatLLM, so the swap reaches its
// next turn without rebuilding the runner, and the model manager re-derives
// the references it offers from the new role assignments.
// the references it offers from the new role assignments and the catalog.
func (b *boot) rebuildChatModelRuntime(cfg config.Config) {
if b.chatModels == nil {
return // this process serves no chat turns
}
b.setLLM(agentexec.NewRuntime(executionProviders(cfg)))
b.chatModels.SetConfigured(cfg.Models)
catalog, models := b.catalogState()
b.chatModels.SetModelCatalog(catalog, models)
b.log.Info("chat model runtime rebuilt", "providers", len(cfg.Providers), "models", len(cfg.Models))
}
@@ -15,6 +15,7 @@ import (
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/app/controlplane"
pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/daemon"
"github.com/samcharles93/archie-core/internal/secret"
)
@@ -240,3 +241,33 @@ func TestLiveModelRoleUpdateRebuildsTheChatModelRuntime(t *testing.T) {
})
}
}
// TestLiveContainerRuntimePoliciesReLayerAndResizeTheDispatcher pins the
// container kind's live seam (archie-core-zfb0.2) at the apply path: a stored
// container-runtime-policies document re-layers into the running config the
// pool reads per acquire, and the daemon resizes its running dispatcher from
// the same publish rather than requiring a restart.
func TestLiveContainerRuntimePoliciesReLayerAndResizeTheDispatcher(t *testing.T) {
values := databaseOwnedResources()
values[controlplane.ContainerRuntimePoliciesKind] = map[string]any{
"image": "archie:live", "max_concurrency": 5, "pull_policy": "missing",
}
stub := &resourceWatchStub{values: values, version: 3, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, _ := newResourceWatchBoot(t, stub)
if err := b.loadRuntimeConfig(t.Context()); err != nil {
t.Fatalf("loadRuntimeConfig: %v", err)
}
// A running daemon, so the resize arm executes against a real dispatcher
// rather than taking the boot-window nil guard.
b.d = &daemon.Daemon{Cfg: b.cfgHolder, Log: b.log}
b.applyRuntimeResourceUpdate(t.Context(), controlplane.ContainerRuntimePoliciesKind, controlplane.AppliedResource{Version: 4})
got := b.cfgHolder.Get().Containers
if got.MaxConcurrency != 5 {
t.Errorf("running max_concurrency = %d, want the stored 5", got.MaxConcurrency)
}
if got.Image != "archie:live" {
t.Errorf("running image = %q, want the stored archie:live", got.Image)
}
}
@@ -47,7 +47,7 @@ func (s *outageStore) down(stall time.Duration) {
s.failing, s.stall = true, stall
}
func (s *outageStore) Resource(ctx context.Context, kind string) (storecontract.Resource, error) {
func (s *outageStore) Resource(ctx context.Context, orgID, kind string) (storecontract.Resource, error) {
s.mu.Lock()
failing, stall := s.failing, s.stall
s.mu.Unlock()
@@ -55,7 +55,7 @@ func (s *outageStore) Resource(ctx context.Context, kind string) (storecontract.
time.Sleep(stall)
return storecontract.Resource{}, errors.New("state store unreachable")
}
return s.TaskDB.Resource(ctx, kind)
return s.TaskDB.Resource(ctx, orgID, kind)
}
// TestWatchRetryGrowsWhileTheStateStoreIsDown is the outage this reconnect
+24 -8
View File
@@ -12,6 +12,7 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/applystatus"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
@@ -71,6 +72,7 @@ func RunGateway(ctx context.Context, options GatewayOptions) error {
return err
}
b.loadCatalog(ctx, options.Config)
b.seedSoul(options.Config)
url, token := b.cfg.NATS.URL, ""
var nc *natsio.Conn
var err error
@@ -156,13 +158,14 @@ func (b *boot) startGatewayRuntime(ctx context.Context, actor gateway.ChatTaskAc
b.addCleanup(b.bus.Close)
b.capabilityHost = plugin.NewHost()
b.startRateLimiter(ctx, b.cfg.Chat.RateLimit)
// The Gateway owns PR review (docs/prds/operator-pr-review.md §4), so it
// composes the process-wide worktree manager before setupGatewayChat
// resolves boot.prReviewer: prReviewer returns nil without a manager, and
// a nil reviewer omits review_pr from every channel's tool set. The
// manager is the only part of the daemon's tree composition the Gateway
// takes -- it must not own identity runners, so it does not call
// buildTreesAndIdentities.
// The Gateway composes the process-wide worktree manager before
// setupGatewayChat; nothing in this process reads it today (the old
// synchronous operator-review path that did was removed with the
// adversarial self-review system, archie-core-afbk.7 -- see that bead's
// continuation for the operator trigger's replacement). Kept for the
// manager's other consumers; it is the only part of the daemon's tree
// composition the Gateway takes -- it must not own identity runners, so
// it does not call buildTreesAndIdentities.
b.buildWorktreeManager()
// setupMemoryEngine must run before setupGatewayChat: setupGatewayChat
// constructs the turn runner, which captures b.memEngines at
@@ -188,18 +191,30 @@ func (b *boot) startGatewayRuntime(ctx context.Context, actor gateway.ChatTaskAc
return contract, nil
}
// inboundMessageHeadroomBytes leaves room for the protobuf framing and the
// rest of the request around an attachment at the messaging contract's
// ceiling, so the largest attachment a channel frontend may send is accepted
// rather than rejected as an oversized gRPC message.
const inboundMessageHeadroomBytes = 1 << 20
// gatewayServerOpts applies the transport security boundary: a loopback
// listener is served insecure with no token; any non-loopback address
// requires a Bearer [REDACTED], else the process fails closed. It mirrors
// stateStoreServerOpts, minus the State Store's task-scoped grants: the
// Gateway has one administrative token for all callers.
//
// The receive limit is raised above gRPC's 4 MB default because an inbound
// request carries a channel attachment's bytes: the channel frontend
// downloads the file, and this process -- which runs the turn -- holds no
// platform credential to fetch it again.
func gatewayServerOpts(listen, token string) (opts []grpc.ServerOption, loopback bool, err error) {
recv := grpc.MaxRecvMsgSize(messaging.MaxInboundAttachmentBytes + inboundMessageHeadroomBytes)
loopback, err = gatewayrpc.TargetIsLoopback(listen)
if err != nil {
return nil, false, err
}
if loopback {
return nil, true, nil
return []grpc.ServerOption{recv}, true, nil
}
if token == "" {
return nil, false, fmt.Errorf(
@@ -208,6 +223,7 @@ func gatewayServerOpts(listen, token string) (opts []grpc.ServerOption, loopback
)
}
return []grpc.ServerOption{
recv,
grpc.ChainUnaryInterceptor(gatewayrpc.UnaryServerInterceptor(token)),
grpc.ChainStreamInterceptor(gatewayrpc.StreamServerInterceptor(token)),
}, false, nil
+30 -8
View File
@@ -9,7 +9,9 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/agent"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/tools"
)
@@ -23,9 +25,15 @@ func (b *boot) setupChatRuntime(ctx context.Context, cfg config.Config) error {
// non-command message processing.
providers := executionProviders(cfg)
b.setLLM(agentexec.NewRuntime(providers))
// Transcription is a model-role capability, like the chat models it sits
// beside: it is built here, on the model-owning side, from this process's
// own [models]/[providers]. The Messaging Service carries a voice note's
// bytes to the Gateway and never holds the credential.
b.setupTranscriber(cfg, b.log)
b.toolReg = tools.NewRegistry()
chatModels := newChatModelManager(cfg.Models, cfg.Chat.Models, b.catalogModels)
chatModels.ApplyModelCatalog(b.catalog)
chatModels := newChatModelManager(cfg.Models, cfg.Chat.Models)
catalog, catalogModels := b.catalogState()
chatModels.SetModelCatalog(catalog, catalogModels)
b.chatModels = chatModels
// ── Persona registry ─────────────────────────────────────────────
@@ -63,8 +71,14 @@ func (b *boot) setupChatRuntime(ctx context.Context, cfg config.Config) error {
canceller = ec
}
b.chatController = gateway.NewStoreTaskController(chatTaskControllerAdapter{
taskByID: b.stateStore.TaskByID,
requeue: b.stateStore.Requeue,
taskByID: b.stateStore.TaskByID,
// Chat's /approve reaches the daemon's one task-action service rather
// than its own requeue, so a chat approval and a dashboard approval
// cannot record different decisions for one operator intent
// (docs/prds/pr-review-operator-response.md, Decision 1).
approve: func(ctx context.Context, scope *string, actor taskactions.Actor, taskID int64, res taskactions.ActionPayload) error {
return b.taskActions().Apply(ctx, scope, actor, taskID, taskstate.ActionApprove, res)
},
cancelExecution: canceller.CancelExecution,
})
b.updateService = makeUpdateService(chatSetup{Cfg: config.NewHolder(cfg)})
@@ -123,16 +137,24 @@ func (b *boot) setupGatewayChat(ctx context.Context, actor gateway.ChatTaskActor
router.InitSessions(b.chatSessionStore)
configureTaskCommands(router, b.chatTasks, b.chatController, chatTaskListerAdapter{tasks: b.stateStore.Tasks}, b.defaultChatIdentity)
router.Health = b.statusHealth
// ToolLimits reads the live holder, not cfg: the daemon's runtime-resource
// watch republishes a tool-settings change through it, so a policy edit
// applies to the next turn in the process that serves this runner.
setup := chatSetup{
Cfg: config.NewHolder(cfg), LLM: b.chatLLM, ChatModels: b.chatModels, ToolReg: b.toolReg,
Cfg: config.NewHolder(cfg),
ToolLimits: func() agentexec.ToolLimits { return toolLimits(b.cfgHolder.Get()) },
LLM: b.chatLLM, ChatModels: b.chatModels, ToolReg: b.toolReg,
Personas: b.personas, ChatTasks: b.chatTasks,
ChatTaskLister: chatTaskListerAdapter{tasks: b.stateStore.Tasks},
ChatTaskLogs: chatTaskLogReaderAdapter{tasks: b.stateStore.TaskByID, taskLogs: b.taskLogs},
ChatTaskActor: actor, ChatPRReviewer: b.prReviewer(),
ChatTaskLister: chatTaskListerAdapter{tasks: b.stateStore.Tasks},
ChatTaskLogs: chatTaskLogReaderAdapter{tasks: b.stateStore.TaskByID, taskLogs: b.taskLogs},
ChatTaskActor: actor,
DefaultChatIdentity: b.defaultChatIdentity,
Bus: b.bus, Log: b.log,
MemoryEngine: b.memoryStore(),
MemoryWriter: b.memoryWriter(),
// The transcription capability is built beside the chat runtime, from
// the model-role configuration only this process reads.
Transcriber: b.transcriber,
// The Gateway executes the web chat's turns, so it is the process
// that must record their outcomes for /status.
ProviderOutcomes: b.providerOutcomes,
+83 -7
View File
@@ -2,8 +2,11 @@ package archied
import (
"context"
"errors"
"io"
"log/slog"
"net"
"sync"
"testing"
"time"
@@ -13,6 +16,7 @@ import (
pb "github.com/samcharles93/archie-core/internal/contracts/gateway/v1"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/sdnotify"
"github.com/samcharles93/archie-core/internal/taskstate"
)
@@ -24,8 +28,10 @@ func TestGatewayServerOptsLoopbackIsInsecure(t *testing.T) {
if !loopback {
t.Fatal("loopback listener should report loopback")
}
if len(opts) != 0 {
t.Fatalf("loopback listener should have no server opts, got %d", len(opts))
// Only the inbound size limit; a loopback listener installs no auth
// interceptors (the count is the only handle on opaque ServerOptions).
if len(opts) != 1 {
t.Fatalf("loopback listener should install only the inbound size limit, got %d options", len(opts))
}
}
@@ -40,8 +46,8 @@ func TestGatewayServerOptsNonLoopbackRequiresToken(t *testing.T) {
if loopback {
t.Fatal("non-loopback listener should not report loopback")
}
if len(opts) != 2 {
t.Fatalf("non-loopback listener should install two server options (unary and stream auth interceptors), got %d", len(opts))
if len(opts) != 3 {
t.Fatalf("non-loopback listener should install three server options (inbound size limit plus unary and stream auth interceptors), got %d", len(opts))
}
}
@@ -88,11 +94,11 @@ func (stubGatewayContract) SetPersona(context.Context, string, string) (bool, er
return false, nil
}
func (stubGatewayContract) ApplyTaskAction(context.Context, string, int64, taskstate.Action) (messaging.TaskActionResult, error) {
func (stubGatewayContract) ApplyTaskAction(context.Context, string, int64, taskstate.Action, taskactions.ActionPayload) (messaging.TaskActionResult, error) {
return messaging.TaskActionResult{}, nil
}
func (stubGatewayContract) ApplyOperatorTaskAction(context.Context, taskactions.Actor, int64, taskstate.Action) (messaging.TaskActionResult, error) {
func (stubGatewayContract) ApplyOperatorTaskAction(context.Context, taskactions.Actor, int64, taskstate.Action, taskactions.ActionPayload) (messaging.TaskActionResult, error) {
return messaging.TaskActionResult{}, nil
}
@@ -116,7 +122,7 @@ func TestGatewayServingAnnouncesReady(t *testing.T) {
serveCh := make(chan error, 1)
go func() { serveCh <- b.serveGatewayListener(ctx, ln, true, stubGatewayContract{}, nil) }()
if !listener.waitForState(t, 5*time.Second, readyState) {
if !listener.waitForState(t, 5*time.Second, sdnotify.ReadyState) {
t.Fatal("no READY=1 datagram within 5s of the Gateway serving")
}
@@ -134,3 +140,73 @@ func TestGatewayServingAnnouncesReady(t *testing.T) {
t.Fatalf("serveGatewayListener returned: %v", err)
}
}
// recordingGatewayContract captures the inbound a Stream call reached the
// Gateway with, so a test can prove the request's payload survived the wire.
type recordingGatewayContract struct {
stubGatewayContract
mu sync.Mutex
last messaging.Inbound
}
func (c *recordingGatewayContract) Stream(_ context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) {
c.mu.Lock()
c.last = in
c.mu.Unlock()
events := make(chan messaging.ChatEvent)
close(events)
return events, nil
}
// TestGatewayAcceptsAnInboundAttachmentOverTheDefaultGRPCLimit: the inbound
// request now carries a channel attachment's bytes, and gRPC's default receive
// limit is 4 MB -- well under the messaging contract's ceiling. A maximal
// attachment must reach the turn, not fail the RPC with ResourceExhausted.
func TestGatewayAcceptsAnInboundAttachmentOverTheDefaultGRPCLimit(t *testing.T) {
rec := &recordingGatewayContract{}
ln, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("listen: %v", err)
}
opts, _, err := gatewayServerOpts(ln.Addr().String(), "")
if err != nil {
t.Fatalf("gatewayServerOpts: %v", err)
}
ctx, cancel := context.WithCancel(t.Context())
defer cancel()
serveCh := make(chan error, 1)
go func() { serveCh <- serveGateway(ctx, ln, rec, nil, opts) }()
defer func() {
cancel()
if err := <-serveCh; err != nil {
t.Errorf("serveGateway: %v", err)
}
}()
conn, err := grpc.NewClient("passthrough:///"+ln.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
t.Fatalf("dial: %v", err)
}
defer conn.Close()
raw := make([]byte, 5<<20) // larger than gRPC's 4 MB default receive limit
stream, err := pb.NewChatServiceClient(conn).Stream(t.Context(), &pb.StreamRequest{
Message: &pb.Message{Media: []*pb.Media{{Type: "image", MimeType: "image/jpeg", Data: raw}}},
})
if err != nil {
t.Fatalf("Stream with a %d-byte attachment: %v", len(raw), err)
}
if _, err := stream.Recv(); !errors.Is(err, io.EOF) {
t.Fatalf("Recv after an empty stream: %v, want EOF", err)
}
rec.mu.Lock()
got := rec.last
rec.mu.Unlock()
if len(got.Media) != 1 {
t.Fatalf("turn received %d attachments, want 1", len(got.Media))
}
if len(got.Media[0].Data) != len(raw) {
t.Fatalf("turn received %d attachment bytes, want %d", len(got.Media[0].Data), len(raw))
}
}
+1 -1
View File
@@ -81,7 +81,7 @@ func (b *boot) setupKitLauncher(ctx context.Context) {
b.kitLauncher = &kitrun.Launcher{
Pool: pool, Fetch: fetcher, Proxy: proxy, Networks: networks,
AgentBinary: agentBinary, CAFile: egress.CACertPath(caDir),
Config: b.cfgHolder, Secrets: b.secrets, Grants: grants,
Config: b.cfgHolder, Secrets: b.secrets, Grants: grants, OAuth: oauthStore,
}
log.Info("kit harness runs enabled", "proxy", ln.Addr().String())
}
+86 -17
View File
@@ -198,7 +198,7 @@ func npmCacheServerEnv(command, workDir string) []string {
return mcp.NpmCacheEnv(command, filepath.Join(workDir, "mcp-npm-cache"))
}
func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovider.Engine, error) {
func configuredMCPProvider(server config.MCPServer, workDir string, sampling mcp.SamplingHandler) (toolprovider.Engine, error) {
name := strings.TrimSpace(server.Name)
if name == "" {
return nil, fmt.Errorf("MCP server name is required")
@@ -208,6 +208,8 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide
transportType = "stdio"
}
samplingOption := mcptoolprovider.WithSamplingHandler(sampling)
switch transportType {
case "stdio":
command := strings.TrimSpace(server.Command)
@@ -220,7 +222,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide
Dir: server.WorkDir,
Env: npmCacheServerEnv(command, workDir),
})
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls, samplingOption), nil
case "http", "streamablehttp":
url := strings.TrimSpace(server.URL)
@@ -231,7 +233,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide
Endpoint: url,
Headers: server.Headers,
})
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls, samplingOption), nil
case "sse":
sseEndpoint := strings.TrimSpace(server.SSEEndpoint)
@@ -243,7 +245,7 @@ func configuredMCPProvider(server config.MCPServer, workDir string) (toolprovide
MessageEndpoint: strings.TrimSpace(server.MessageEndpoint),
Headers: server.Headers,
})
return mcptoolprovider.New(name, transport, server.ParallelToolCalls), nil
return mcptoolprovider.New(name, transport, server.ParallelToolCalls, samplingOption), nil
default:
return nil, fmt.Errorf("MCP transport %q is not supported", transportType)
@@ -379,6 +381,7 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence
return 0
}
b.loadCatalog(ctx, args.cfgPath)
b.seedSoul(args.cfgPath)
b.setupObservability(ctx)
if err := b.setupBackends(ctx); err != nil {
@@ -388,6 +391,11 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence
if err := b.setupLLMAndChat(ctx); err != nil {
return 1
}
// The catalog's consumers exist from here on, and the daemon is the
// process that owns the published configuration, so this is where the
// live catalog refresh belongs. The standalone Gateway reads the catalog
// once at boot and runs no control-plane watches (RunGateway).
b.startModelCatalogRefresh(ctx)
if err := b.buildTreesAndIdentities(ctx); err != nil {
return 1
}
@@ -404,6 +412,9 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence
if err := b.loadPlugins(); err != nil {
return 1
}
// Every directory loader has run by here, so the reconciliation seeds the
// running set and from its first tick loads only what appears or changes.
b.startPluginReconcile(ctx)
if err := b.registerNATSRPC(); err != nil {
return 1
@@ -414,7 +425,6 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence
return 1
}
b.setupGuardrails()
if err := b.registerTools(ctx); err != nil {
return 1
}
@@ -539,14 +549,16 @@ type chatTaskWriterAdapter struct {
enqueue func(
ctx context.Context,
owner, repo, title, body, workflow, identity string,
inputs map[string]any,
) (*workflow.Task, error)
}
func (a chatTaskWriterAdapter) EnqueueChatTask(
ctx context.Context,
owner, repo, title, body, workflow, identity string,
inputs map[string]any,
) (int64, error) {
task, err := a.enqueue(ctx, owner, repo, title, body, workflow, identity)
task, err := a.enqueue(ctx, owner, repo, title, body, workflow, identity, inputs)
if err != nil {
return 0, err
}
@@ -558,7 +570,7 @@ func (a chatTaskWriterAdapter) EnqueueChatTask(
type chatTaskControllerAdapter struct {
taskByID func(context.Context, int64) (*workflow.Task, error)
requeue func(context.Context, int64, string, string) error
approve func(context.Context, *string, taskactions.Actor, int64, taskactions.ActionPayload) error
cancelExecution func(context.Context, int64, string, string) ([]int64, error)
}
@@ -576,8 +588,16 @@ func (a chatTaskControllerAdapter) ChatTaskStatus(ctx context.Context, taskID in
return gateway.ChatTaskStatus{}, false, fmt.Errorf("task %d is not chat-originated", taskID)
}
func (a chatTaskControllerAdapter) ApproveChatTask(ctx context.Context, taskID int64) error {
return a.requeue(ctx, taskID, workflow.StatusWaitingHuman, "implement")
func (a chatTaskControllerAdapter) ApproveChatTask(ctx context.Context, taskID int64, actor taskactions.Actor) error {
if a.approve == nil {
return fmt.Errorf("task approval is unavailable")
}
// The chat-bound identity is both the scope the task must belong to and
// the actor the record names: a chat command has no cross-identity
// authority, and /approve carries no selection syntax, so the review gate
// answer posts every offered finding.
scope := string(actor.Identity)
return a.approve(ctx, &scope, actor, taskID, taskactions.ActionPayload{})
}
func (a chatTaskControllerAdapter) CancelChatTask(ctx context.Context, taskID int64, reason string) error {
@@ -682,15 +702,15 @@ type chatTaskActorAdapter struct {
}
func (a chatTaskActorAdapter) ApplyChatTaskAction(
ctx context.Context, identity *string, actor taskactions.Actor, taskID int64, action taskstate.Action,
ctx context.Context, identity *string, actor taskactions.Actor, taskID int64, action taskstate.Action, res taskactions.ActionPayload,
) (gateway.TaskActionResult, error) {
if a.contract == nil {
return gateway.TaskActionResult{}, gateway.ErrChatCapabilityUnavailable
}
if identity == nil {
return a.contract.ApplyOperatorTaskAction(ctx, actor, taskID, action)
return a.contract.ApplyOperatorTaskAction(ctx, actor, taskID, action, res)
}
return a.contract.ApplyTaskAction(ctx, *identity, taskID, action)
return a.contract.ApplyTaskAction(ctx, *identity, taskID, action, res)
}
func chatTaskProfiles(cfg config.Config) ([]gateway.TaskProfile, string) {
@@ -953,10 +973,12 @@ func safePluginInfo(p plugin.Plugin) (name, version string) {
// there is deliberately no host execution fallback.
func startContainers(
ctx context.Context,
cfg config.Config,
cfgHolder *config.Holder,
secrets *secret.Registry,
log *slog.Logger,
) (*container.Pool, storage.Backend, func()) {
noop := func() {}
cfg := cfgHolder.Get()
// Single Docker client shared between pool and storage backend.
dockerCli, err := client.New(client.FromEnv)
if err != nil {
@@ -974,16 +996,15 @@ func startContainers(
MaxConcurrency: cfg.Containers.MaxConcurrency,
MaxUptime: cfg.Containers.MaxUptime.Std(),
PullPolicy: cfg.Containers.PullPolicy,
RegistryAuth: resolveRegistryAuth(cfg.Containers.RegistryAuth, secrets, log),
Network: cfg.Containers.Network,
DockerClient: dockerCli,
// Only the embedded broker binds a discovered host gateway. The
// standalone State Store uses its configured, container-reachable target.
RequireHostGateway: cfg.NATS.Mode == config.NATSModeEmbedded,
}, log)
}, containerLiveSettings(cfgHolder), log)
if err != nil {
// A missing image is recoverable by hand. The daemon sends no registry
// credentials on pull (internal/container/pool.go), so a private
// registry always needs the operator's CLI to fetch it first.
// A missing image is recoverable by hand.
log.Error("autonomous workflows unavailable: container pool unavailable", "err", err,
"hint", "run `docker compose pull agent` (or `build agent`) so the image is present locally")
return nil, storage.NewDockerBackend(dockerCli), closeDocker
@@ -999,3 +1020,51 @@ func startContainers(
closeDocker()
}
}
// containerLiveSettings reads the per-acquire container settings from the
// running config. The pool calls it on every acquire, so a stored
// container-runtime-policies change reaches the next container without a
// restart. Only fields the resource document carries are taken live:
// RegistryAuth is file-owned and stays the boot-resolved value, DockerClient
// and RequireHostGateway are construction-time, and GracePeriod is not part
// of the document.
func containerLiveSettings(cfgHolder *config.Holder) func() container.Config {
return func() container.Config {
cfg := cfgHolder.Get()
return container.Config{
Image: cfg.Containers.Image,
MaxConcurrency: cfg.Containers.MaxConcurrency,
MaxUptime: cfg.Containers.MaxUptime.Std(),
PullPolicy: cfg.Containers.PullPolicy,
Network: cfg.Containers.Network,
}
}
}
// resolveRegistryAuth resolves [containers].registry_auth into the credential
// the container pool sends on pull. It returns "" -- an anonymous pull, the
// pool's behaviour before the field existed -- whenever the credential is not
// configured or cannot be resolved, because a missing registry credential must
// not stop autonomous work: the pool only needs it for a private registry. The
// warning is what makes the 401 that a private registry will still answer
// explicable after a typo or an unset secret. A ref that names only one half is
// a config error caught by configuration.Validate, not a missing credential.
func resolveRegistryAuth(ref secret.SecretRef, secrets *secret.Registry, log *slog.Logger) string {
if ref == (secret.SecretRef{}) {
return ""
}
if secrets == nil {
log.Warn("registry credential unavailable; pulling without auth", "reason", "no secret registry", "engine", ref.Engine, "key", ref.Key)
return ""
}
value, err := secrets.Resolve(ref)
if err != nil {
log.Warn("registry credential unavailable; pulling without auth", "err", err, "engine", ref.Engine, "key", ref.Key)
return ""
}
if strings.TrimSpace(value) == "" {
log.Warn("registry credential resolved empty; pulling without auth", "engine", ref.Engine, "key", ref.Key)
return ""
}
return value
}
+105 -11
View File
@@ -22,14 +22,17 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/daemon"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/forgerpc"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
taskactionstore "github.com/samcharles93/archie-core/internal/infrastructure/taskactions"
"github.com/samcharles93/archie-core/internal/logging"
"github.com/samcharles93/archie-core/internal/secret"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/taskstate/taskstatetest"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/worktree"
@@ -199,6 +202,65 @@ func TestResolveForgeBuildsClientWhenTokenResolves(t *testing.T) {
}
}
// resolveRegistryAuth hands the container pool the resolved
// [containers].registry_auth, and degrades to an anonymous pull (with a
// warning) whenever there is nothing resolvable to hand it. A deployment with
// no private registry must be unaffected by the field existing, and a private
// registry whose secret is missing or misnamed must still let every task that
// does not need it run -- the pool simply pulls without auth, as it always did,
// and the warning explains the 401 that follows.
func TestResolveRegistryAuthDegradesRatherThanFailing(t *testing.T) {
t.Run("unconfigured is silent", func(t *testing.T) {
rec := &recordingHandler{}
if got := resolveRegistryAuth(secret.SecretRef{}, secret.NewRegistry(), slog.New(rec)); got != "" {
t.Errorf("resolveRegistryAuth(empty) = %q, want empty", got)
}
if warns := rec.Warnings(); len(warns) != 0 {
t.Errorf("unconfigured registry auth logged %v, want nothing", warns)
}
})
t.Run("resolved credential reaches the pool", func(t *testing.T) {
t.Setenv("ARCHIE_TEST_REGISTRY_AUTH", `{"username":"bot","password":"s3cret"}`)
rec := &recordingHandler{}
got := resolveRegistryAuth(
secret.SecretRef{Engine: "env", Key: "ARCHIE_TEST_REGISTRY_AUTH"},
secret.NewRegistry(), slog.New(rec))
if want := `{"username":"bot","password":"s3cret"}`; got != want {
t.Errorf("resolveRegistryAuth = %q, want the resolved secret %q", got, want)
}
if warns := rec.Warnings(); len(warns) != 0 {
t.Errorf("a resolvable credential logged %v, want nothing", warns)
}
})
t.Run("unresolvable credential degrades with a warning", func(t *testing.T) {
rec := &recordingHandler{}
got := resolveRegistryAuth(
secret.SecretRef{Engine: "env", Key: "ARCHIE_TEST_REGISTRY_AUTH_DEFINITELY_UNSET"},
secret.NewRegistry(), slog.New(rec))
if got != "" {
t.Errorf("resolveRegistryAuth = %q, want empty for an unresolvable credential", got)
}
warns := rec.Warnings()
if len(warns) != 1 || !strings.Contains(warns[0], "registry credential unavailable") {
t.Errorf("warnings = %v, want exactly one saying the credential was unavailable", warns)
}
})
t.Run("no secret registry degrades instead of panicking", func(t *testing.T) {
rec := &recordingHandler{}
got := resolveRegistryAuth(
secret.SecretRef{Engine: "env", Key: "ANYTHING"}, nil, slog.New(rec))
if got != "" {
t.Errorf("resolveRegistryAuth = %q, want empty with no secret registry", got)
}
if warns := rec.Warnings(); len(warns) != 1 {
t.Errorf("warnings = %v, want exactly one", warns)
}
})
}
func TestResolveProviderSecretSetsPrivateRuntimeEnvironment(t *testing.T) {
registry := secret.NewRegistry()
registry.Register(providerSecretEngine{value: "provider-secret"})
@@ -431,7 +493,7 @@ func TestConfiguredMCPProviderSupportsAllTransportTypes(t *testing.T) {
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
provider, err := configuredMCPProvider(tt.server, t.TempDir())
provider, err := configuredMCPProvider(tt.server, t.TempDir(), nil)
if (err != nil) != tt.wantErr {
t.Fatalf("configuredMCPProvider() error = %v, wantErr %t", err, tt.wantErr)
}
@@ -567,7 +629,7 @@ func TestManualRequeueTaskRejectsOtherStatuses(t *testing.T) {
func TestChatTaskListerAdapterReadsSQLiteIdentity(t *testing.T) {
st := pgstore.Open(t)
t.Cleanup(func() { _ = st.Close() })
want, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "identity task", "", "tdd", "reviewer")
want, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "identity task", "", "tdd", "reviewer", nil)
if err != nil {
t.Fatal(err)
}
@@ -610,13 +672,14 @@ func TestChatTaskWriterAdapter(t *testing.T) {
enqueue: func(
context.Context,
string, string, string, string, string, string,
map[string]any,
) (*workflow.Task, error) {
return tt.result, tt.err
},
}
id, err := adapter.EnqueueChatTask(
context.Background(),
"owner", "repo", "title", "body", "workflow", "identity",
"owner", "repo", "title", "body", "workflow", "identity", nil,
)
if (err != nil) != tt.wantErr {
t.Fatalf("EnqueueChatTask() error = %v, wantErr %t", err, tt.wantErr)
@@ -669,11 +732,19 @@ func TestChatTaskControllerAdapterRejectsForgeTask(t *testing.T) {
func TestChatTaskControllerAdapterTransitions(t *testing.T) {
task := &workflow.Task{ID: 42, Source: workflow.SourceChat, Status: workflow.StatusWaitingHuman}
var requeueFrom, requeueWorkflow, cancelReason, cancelTo string
var approveScope string
var approveActor taskactions.Actor
var approveRes taskactions.ActionPayload
var cancelReason, cancelTo string
adapter := chatTaskControllerAdapter{
taskByID: func(context.Context, int64) (*workflow.Task, error) { return task, nil },
requeue: func(_ context.Context, _ int64, from, workflow string) error {
requeueFrom, requeueWorkflow = from, workflow
// Chat's approval reaches the daemon's one task-action service, not
// its own requeue: this records what the adapter hands it.
approve: func(_ context.Context, scope *string, actor taskactions.Actor, _ int64, res taskactions.ActionPayload) error {
if scope != nil {
approveScope = *scope
}
approveActor, approveRes = actor, res
return nil
},
cancelExecution: func(_ context.Context, _ int64, reason, to string) ([]int64, error) {
@@ -682,11 +753,17 @@ func TestChatTaskControllerAdapterTransitions(t *testing.T) {
},
}
if err := adapter.ApproveChatTask(context.Background(), task.ID); err != nil {
if err := adapter.ApproveChatTask(context.Background(), task.ID, taskactions.ActorFromScope("archie")); err != nil {
t.Fatalf("ApproveChatTask(): %v", err)
}
if requeueFrom != workflow.StatusWaitingHuman || requeueWorkflow != "implement" {
t.Errorf("requeue = %q/%q, want waiting_human/implement", requeueFrom, requeueWorkflow)
// The scope is the chat-bound identity, and /approve carries no
// instruction or selection syntax, so the review-gate payload is empty
// (an absent selection means every offered finding).
if approveScope != "archie" || approveActor.Identity != "archie" {
t.Errorf("approve scope/actor = %q/%q, want the chat-bound identity", approveScope, approveActor.Identity)
}
if approveRes.Instructions != "" || len(approveRes.Findings) != 0 {
t.Errorf("approve payload = %+v, want the zero review response for chat", approveRes)
}
if err := adapter.CancelChatTask(context.Background(), task.ID, "cancelled by test"); err != nil {
t.Fatalf("CancelChatTask(): %v", err)
@@ -833,9 +910,15 @@ func TestChatTaskCommandsEndToEnd(t *testing.T) {
chatTaskWriterAdapter{enqueue: st.EnqueueChatTask},
profiles,
)
// Chat's /approve reaches the same task-action service the daemon wires
// (docs/prds/pr-review-operator-response.md, Decision 1), over the real
// store this test uses.
actions := taskactionstore.NewService(taskactionstore.Store{TaskStore: st}, nil, nil, nil, nil, nil, nil, nil)
controller := gateway.NewStoreTaskController(chatTaskControllerAdapter{
taskByID: st.TaskByID,
requeue: st.Requeue,
taskByID: st.TaskByID,
approve: func(ctx context.Context, scope *string, actor taskactions.Actor, taskID int64, res taskactions.ActionPayload) error {
return actions.Apply(ctx, scope, actor, taskID, taskstate.ActionApprove, res)
},
cancelExecution: st.CancelExecution,
})
router := gateway.NewRouter(st, nil, "test")
@@ -861,6 +944,17 @@ func TestChatTaskCommandsEndToEnd(t *testing.T) {
t.Fatalf("spawned task = %+v", task)
}
// Feasibility's deliver stage names implement on the task before it waits
// (docs/prds/pr-review-operator-response.md, Decision 1), so the wait the
// seed models carries that name; the approval resumes it.
waiting, err := st.TaskByID(ctx, taskID)
if err != nil || waiting == nil {
t.Fatalf("task before wait = (%+v, %v)", waiting, err)
}
waiting.Workflow = "implement"
if err := st.Update(ctx, waiting); err != nil {
t.Fatalf("name the resuming workflow: %v", err)
}
taskstatetest.Seed(t.Context(), t, st, taskID, workflow.StatusQueued, workflow.StatusWaitingHuman, "await approval")
task, err = st.TaskByID(ctx, taskID)
if err != nil || task == nil || task.Status != workflow.StatusWaitingHuman {
+192
View File
@@ -0,0 +1,192 @@
package archied
import (
"context"
"errors"
"fmt"
"reflect"
"slices"
"strings"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/tools/minimax"
toolprovider "github.com/samcharles93/archie-core/internal/tools/provider"
"github.com/samcharles93/archie-core/internal/tools/webfetch"
)
// appliedMCPServer is one MCP server the running provider registry was built
// from: the configuration it was built with and the manifest id it registered
// under. A live tool-settings change diffs the stored server set against this
// record, so a server that did not change is left running and untouched
// (archie-core-zfb0.3).
type appliedMCPServer struct {
server config.MCPServer
id string
}
// buildMCPProvider builds the tool-provider engine for one configured MCP
// server. boot.mcpProvider overrides it in tests; production uses
// configuredMCPProvider with the running config's work directory and the
// daemon's sampling handler. Boot registration and the live reconciliation
// both reach the engine through here, so the two cannot build one differently.
func (b *boot) buildMCPProvider(srv config.MCPServer) (toolprovider.Engine, error) {
if b.mcpProvider != nil {
return b.mcpProvider(srv)
}
return configuredMCPProvider(srv, b.cfgHolder.Get().WorkDir, b.mcpSamplingHandler())
}
// reconcileToolSettings applies a live tool-settings change to the components
// built once from that kind: the MCP provider set (diffed, so an unchanged
// server keeps running), the web_fetch and minimax tool entries (rebuilt,
// because the entry captured the config at construction) and the tool-output
// policy (whose spill directory is ensured here; the task snapshot reads the
// policy fresh per dispatch and boot.toolLimits is read per call). A nil tool
// registry means this process built no tools, so only the config was layered.
func (b *boot) reconcileToolSettings(ctx context.Context, cfg config.Config) error {
if err := toolLimits(cfg).EnsureSpillDir(); err != nil {
b.log.Warn("tool spill directory unavailable; large results will be truncated instead", "err", err)
}
var problems []error
if err := b.reconcileMCPServers(ctx, cfg.Tools.MCPServers); err != nil {
problems = append(problems, err)
}
if b.toolReg != nil {
// Unregister first: the boot entry is being replaced, and a second
// registration would collide on the tool name. Minimax resolves its
// API key again as part of the rebuild, so a rotated credential
// applies too.
b.toolReg.Unregister(webfetch.ToolName, minimax.ToolName)
b.registerWebFetchTool(cfg)
b.registerMinimaxTool(cfg, b.log)
}
return errors.Join(problems...)
}
// reconcileMCPServers brings the running provider set in line with the MCP
// servers the layered configuration now names: a server that appeared
// connects, one that disappeared disconnects, one whose configuration changed
// reconnects, and an unchanged one is left running and untouched. It is
// idempotent, so it can run on every stored tool-settings version without
// disturbing the servers that did not change.
//
// A server whose engine cannot be built or started is reported and left out;
// the servers already running keep running, the degrade-and-skip rule the boot
// registration applies. A changed server whose new engine fails to start is
// rolled back to the old one by the registry, so a refused change does not
// leave the server down.
func (b *boot) reconcileMCPServers(ctx context.Context, servers []config.MCPServer) error {
if b.providerRegistry == nil {
return nil
}
b.mcpMu.Lock()
defer b.mcpMu.Unlock()
desired := make(map[string]config.MCPServer, len(servers))
for _, srv := range servers {
if name := strings.TrimSpace(srv.Name); name != "" {
desired[name] = srv
}
}
state := b.mcpRegistryState()
var problems []error
problems = append(problems, b.disconnectAbsentMCPServers(ctx, desired)...)
problems = append(problems, b.applyDesiredMCPServers(ctx, desired, state)...)
return errors.Join(problems...)
}
// mcpRegistryState is the read side of the provider registry a diff needs: is
// the family running at all, which ids are registered, and which are live.
type mcpRegistryState struct {
familyRunning bool
registered map[string]bool
live map[string]bool
}
func (b *boot) mcpRegistryState() mcpRegistryState {
registered := make(map[string]bool)
for _, id := range b.providerRegistry.RegisteredIDs() {
registered[id] = true
}
live := make(map[string]bool)
for _, id := range b.providerRegistry.RunningIDs() {
live[id] = true
}
return mcpRegistryState{
familyRunning: b.providerRegistry.Running(),
registered: registered,
live: live,
}
}
// disconnectAbsentMCPServers removes every applied server the stored document
// no longer names.
func (b *boot) disconnectAbsentMCPServers(ctx context.Context, desired map[string]config.MCPServer) []error {
var problems []error
for name := range b.mcpApplied {
if _, ok := desired[name]; ok {
continue
}
applied := b.mcpApplied[name]
if err := b.providerRegistry.Remove(ctx, applied.id); err != nil {
problems = append(problems, fmt.Errorf("disconnect MCP server %q: %w", name, err))
continue
}
delete(b.mcpApplied, name)
}
return problems
}
// applyDesiredMCPServers connects, reconnects or restarts the servers the
// stored document names, skipping the ones already running unchanged.
func (b *boot) applyDesiredMCPServers(ctx context.Context, desired map[string]config.MCPServer, state mcpRegistryState) []error {
names := make([]string, 0, len(desired))
for name := range desired {
names = append(names, name)
}
slices.Sort(names)
var problems []error
for _, name := range names {
srv := desired[name]
if b.mcpServerCurrent(name, srv, state) {
continue
}
engine, err := b.buildMCPProvider(srv)
if err != nil {
problems = append(problems, fmt.Errorf("MCP server %q: %w", name, err))
continue
}
if err := b.applyMCPProvider(ctx, engine, state); err != nil {
problems = append(problems, fmt.Errorf("connect MCP server %q: %w", name, err))
continue
}
b.mcpApplied[name] = appliedMCPServer{server: srv, id: engine.Manifest().ID}
}
return problems
}
// mcpServerCurrent reports whether the server is already running unchanged, so
// a reconciliation can leave it untouched. Present means running while the
// family runs, or still registered while it has not started; a
// registered-but-not-running server on a running family is a refused earlier
// start and is worth another attempt.
func (b *boot) mcpServerCurrent(name string, srv config.MCPServer, state mcpRegistryState) bool {
applied, ok := b.mcpApplied[name]
if !ok || !reflect.DeepEqual(applied.server, srv) {
return false
}
if !state.registered[applied.id] {
return false
}
return !state.familyRunning || state.live[applied.id]
}
// applyMCPProvider replaces a registered provider and adds an absent one,
// whichever the registry needs for that id.
func (b *boot) applyMCPProvider(ctx context.Context, engine toolprovider.Engine, state mcpRegistryState) error {
if state.registered[engine.Manifest().ID] {
return b.providerRegistry.Replace(ctx, engine)
}
return b.providerRegistry.Add(ctx, engine)
}
+71
View File
@@ -0,0 +1,71 @@
package archied
import (
"context"
"errors"
"fmt"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/tools/mcp"
)
// mcpSamplingHandler answers an MCP server's sampling/createMessage request
// from the daemon's own chat model, so a server can ask for a completion
// without archie opening a second provider path. A missing runtime or model
// is a refused request, never a dropped one: the client maps the returned
// error to a JSON-RPC error response for that request alone, leaving the
// server session intact.
func (b *boot) mcpSamplingHandler() mcp.SamplingHandler {
return func(ctx context.Context, req mcp.SamplingRequest) (mcp.SamplingResult, error) {
llm := b.chatLLM()
if llm == nil {
return mcp.SamplingResult{}, errors.New("mcp sampling: no model runtime is configured")
}
if b.chatModels == nil {
return mcp.SamplingResult{}, errors.New("mcp sampling: no chat model is configured")
}
model := b.chatModels.ActiveModel()
if model == "" {
return mcp.SamplingResult{}, errors.New("mcp sampling: no chat model is configured")
}
messages, err := agentexec.SamplingMessages(req)
if err != nil {
return mcp.SamplingResult{}, err
}
options := core.GenerateOptions{
Messages: messages,
System: req.SystemPrompt,
MaxSteps: 1,
MaxTokens: samplingMaxTokens(req, b.chatModels, model),
}
if req.Temperature != nil {
options.Temperature = float32(*req.Temperature)
}
result, err := llm.Chat(ctx, model, options)
// A sampling call is a model call this process made, so it is
// recorded for /status like every other one; a nil recorder records
// nothing.
b.providerOutcomes.record(model, err)
if err != nil {
return mcp.SamplingResult{}, fmt.Errorf("mcp sampling: %w", err)
}
return mcp.SamplingResult{
Model: model,
Role: "assistant",
Content: mcp.SamplingContent{Type: "text", Text: result.Text},
StopReason: string(result.FinishReason),
}, nil
}
}
// samplingMaxTokens bounds the completion to the request's own maxTokens,
// falling back to a conservative default, and never past the model's own
// output ceiling. The bound itself is shared with the agent worker's sampling
// path (agentexec.SamplingMaxTokens) so the same server sees the same bound on
// either path.
func samplingMaxTokens(req mcp.SamplingRequest, models *chatModelManager, model string) int {
details, ok := models.ModelDetails(model)
return agentexec.SamplingMaxTokens(req.MaxTokens, details.MaxOutputTokens, ok && details.Reasoning)
}
+98
View File
@@ -0,0 +1,98 @@
package archied
import (
"io"
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/tools/mcp"
)
func newSamplingTestRuntime(t *testing.T) *httptest.Server {
t.Helper()
api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/json")
_, _ = io.WriteString(w, `{"id":"chatcmpl-1","object":"chat.completion","created":1,"model":"gpt-5.6",`+
`"choices":[{"index":0,"message":{"role":"assistant","content":"four"},"finish_reason":"stop"}],`+
`"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}`)
}))
t.Cleanup(api.Close)
return api
}
// TestMCPSamplingHandlerAnswersFromConfiguredModel proves a server-initiated
// sampling request is answered by the daemon's own chat model and recorded on
// /status like every other model call this process makes.
func TestMCPSamplingHandlerAnswersFromConfiguredModel(t *testing.T) {
api := newSamplingTestRuntime(t)
b := newBootstrap()
b.setLLM(agentexec.NewRuntime(map[string]agentexec.Provider{
"openai": {Class: "openai", BaseURL: api.URL},
}))
b.chatModels = newChatModelManager(map[string]string{"chat": "openai/gpt-5.6"})
b.providerOutcomes = newProviderOutcomeRecorder()
result, err := b.mcpSamplingHandler()(t.Context(), mcp.SamplingRequest{
Messages: []mcp.SamplingMessage{{
Role: "user",
Content: mcp.SamplingContent{Type: "text", Text: "2+2?"},
}},
MaxTokens: 16,
})
if err != nil {
t.Fatalf("sampling handler = %v, want a completion", err)
}
if result.Model != "openai/gpt-5.6" {
t.Errorf("result.Model = %q, want the configured chat model", result.Model)
}
if result.Role != "assistant" || result.Content.Type != "text" || result.Content.Text != "four" {
t.Errorf("result = %+v, want an assistant text completion", result)
}
outcome, attempted := b.providerOutcomes.LastChatModelOutcome()
if !attempted || outcome.Model != "openai/gpt-5.6" || outcome.Err != "" {
t.Errorf("recorded outcome = %+v (attempted %v), want the sampling call recorded as successful", outcome, attempted)
}
}
// TestMCPSamplingHandlerRefusesCleanlyWithNoModel proves a daemon with no
// usable model answers the request with an error instead of panicking or
// dropping it: the server sees a failed request, not a dead session.
func TestMCPSamplingHandlerRefusesCleanlyWithNoModel(t *testing.T) {
tests := []struct {
name string
wired bool
want string
}{
{name: "no model runtime", wired: false, want: "no model runtime"},
{name: "no chat model configured", wired: true, want: "no chat model"},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
b := newBootstrap()
if tc.wired {
b.setLLM(agentexec.NewRuntime(map[string]agentexec.Provider{
"openai": {Class: "openai"},
}))
}
b.chatModels = newChatModelManager(nil)
_, err := b.mcpSamplingHandler()(t.Context(), mcp.SamplingRequest{
Messages: []mcp.SamplingMessage{{
Role: "user",
Content: mcp.SamplingContent{Type: "text", Text: "hi"},
}},
})
if err == nil {
t.Fatal("sampling handler returned no error with no usable model")
}
if !strings.Contains(err.Error(), tc.want) {
t.Errorf("error = %q, want it to mention %q", err, tc.want)
}
})
}
}
+1 -1
View File
@@ -22,7 +22,7 @@ func applyModelCatalog(cfg *config.Config, snapshot modelcatalog.Snapshot) []str
for _, model := range provider.Models {
ref := provider.ID + "/" + model.ID
models = append(models, ref)
limits[ref] = config.ModelLimits{ContextWindow: model.ContextWindow, MaxOutputTokens: model.MaxOutputTokens}
limits[ref] = config.ModelLimits{ContextWindow: model.ContextWindow, MaxOutputTokens: model.MaxOutputTokens, Reasoning: model.Reasoning}
}
}
cfg.ModelLimits = limits
@@ -0,0 +1,250 @@
package archied
import (
"context"
"encoding/json"
"errors"
"io/fs"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"slices"
"strings"
"sync/atomic"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/infrastructure/modelcatalog"
"github.com/samcharles93/archie-core/internal/secret"
"github.com/samcharles93/archie-core/internal/webui"
)
// catalogServer answers the model catalog read with a models.dev-shaped
// document. It is the outside dependency the refresh loop actually meets:
// modelcatalog.Load fetches this and caches what it read.
func catalogServer(t *testing.T, document func() map[string]any) *httptest.Server {
t.Helper()
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
w.Header().Set("Content-Type", "application/json")
_ = json.NewEncoder(w).Encode(document())
}))
t.Cleanup(srv.Close)
return srv
}
// catalogProvider is one usable provider entry: an environment variable that
// resolves (so modelcatalog keeps it) and the tool-callable models it offers.
func catalogProvider(id, env string, models ...string) map[string]any {
entries := make(map[string]any, len(models))
for _, model := range models {
entries[model] = map[string]any{
"id": model, "name": strings.ToUpper(model), "tool_call": true,
"limit": map[string]any{"context": 128000, "output": 16000},
}
}
return map[string]any{
"id": id, "name": strings.ToUpper(id), "npm": "@ai-sdk/openai-compatible",
"api": "https://" + id + ".test/v1", "env": []string{env}, "models": entries,
}
}
// newCatalogBoot builds the smallest boot the refresh path runs against: the
// control plane reads behind runtimeConfig, the secrets registry the catalog
// resolves keys through, the chat runtime a refresh must reach, and a catalog
// endpoint a test controls.
func newCatalogBoot(t *testing.T, url string) *boot {
t.Helper()
b := newReloadBoot(t, &controlPlaneStub{values: databaseOwnedResources()})
b.secrets = secret.NewRegistry()
b.chatModels = newChatModelManager(fileConfig().Models)
b.setLLM(agentexec.NewRuntime(executionProviders(fileConfig())))
b.catalogURL = url
b.catalogCachePath = filepath.Join(t.TempDir(), "models.json")
if err := b.loadRuntimeConfig(t.Context()); err != nil {
t.Fatalf("loadRuntimeConfig: %v", err)
}
return b
}
func awaitCatalog(t *testing.T, b *boot, ref string) {
t.Helper()
deadline := time.Now().Add(5 * time.Second)
for !slices.Contains(b.chatModels.Models(), ref) {
if time.Now().After(deadline) {
t.Fatalf("chat models = %v, want %s to appear within the refresh interval", b.chatModels.Models(), ref)
}
time.Sleep(2 * time.Millisecond)
}
}
// TestRefreshModelCatalogRepublishesEveryProjectionSite: a catalog read after
// boot must reach everything derived from it -- the running config a workflow
// stage resolves model limits from, the dashboard's published catalog view,
// and the chat runtime's model list and details. A value that reaches the
// boot struct alone parses and does nothing.
func TestRefreshModelCatalogRepublishesEveryProjectionSite(t *testing.T) {
srv := catalogServer(t, func() map[string]any {
return map[string]any{"acme": catalogProvider("acme", "ACME_API_KEY", "acme-tool")}
})
t.Setenv("ACME_API_KEY", "resolved-by-the-secret-registry")
b := newCatalogBoot(t, srv.URL)
if snapshot, _ := b.catalogState(); len(snapshot.Providers) != 0 {
t.Fatalf("boot catalog = %+v, want the empty snapshot this test starts from", snapshot.Providers)
}
if err := b.refreshModelCatalog(t.Context()); err != nil {
t.Fatalf("refreshModelCatalog: %v", err)
}
if got := b.cfgHolder.Get().ModelLimits["acme/acme-tool"]; got.ContextWindow != 128000 || got.MaxOutputTokens != 16000 {
t.Errorf("running model limits = %+v, want the refreshed catalog's capacity", got)
}
if _, models := b.catalogState(); !slices.Contains(models, "acme/acme-tool") {
t.Errorf("catalog models = %v, want the refreshed reference", models)
}
view := webui.BuildConfigView(b.configViewInput(t.Context()))
if len(view.Catalog) != 1 || view.Catalog[0].ID != "acme" {
t.Fatalf("published catalog = %+v, want the refreshed provider", view.Catalog)
}
if !slices.Contains(view.Catalog[0].Models, "acme-tool") {
t.Errorf("published catalog models = %v, want the refreshed model", view.Catalog[0].Models)
}
if !slices.Contains(b.chatModels.Models(), "acme/acme-tool") {
t.Errorf("chat models = %v, want the refreshed reference offered", b.chatModels.Models())
}
if _, ok := b.chatModels.ModelDetails("acme/acme-tool"); !ok {
t.Error("chat model details missing the refreshed model")
}
if got := b.chatModels.ProviderDisplayName("acme"); got != "ACME" {
t.Errorf("provider display name = %q, want the refreshed catalog's name", got)
}
}
// TestModelCatalogRefreshLoopPicksUpANewModelWhileTheDaemonRuns is the
// without-a-restart proof: the process is already running on the catalog it
// booted with, and a model that appears upstream afterwards is offered by the
// next tick.
func TestModelCatalogRefreshLoopPicksUpANewModelWhileTheDaemonRuns(t *testing.T) {
var calls atomic.Int64
srv := catalogServer(t, func() map[string]any {
if calls.Add(1) == 1 {
return map[string]any{"acme": catalogProvider("acme", "ACME_API_KEY", "acme-one")}
}
return map[string]any{"acme": catalogProvider("acme", "ACME_API_KEY", "acme-one", "acme-two")}
})
t.Setenv("ACME_API_KEY", "resolved-by-the-secret-registry")
b := newCatalogBoot(t, srv.URL)
if err := b.refreshModelCatalog(t.Context()); err != nil {
t.Fatalf("initial refresh: %v", err)
}
if slices.Contains(b.chatModels.Models(), "acme/acme-two") {
t.Fatal("the second model was offered before upstream published it")
}
b.catalogRefreshInterval = 5 * time.Millisecond
ctx, cancel := context.WithCancel(t.Context())
defer cancel()
b.startModelCatalogRefresh(ctx)
awaitCatalog(t, b, "acme/acme-two")
if got := b.cfgHolder.Get().ModelLimits["acme/acme-two"]; got.ContextWindow != 128000 {
t.Errorf("running model limits for the new model = %+v, want the refreshed capacity", got)
}
}
// TestRefreshModelCatalogKeepsTheLoadedCatalogWhenTheReadFails: the catalog
// service having a bad minute must not blank the model list the process is
// already running on. The failed read is reported; the snapshot stays.
func TestRefreshModelCatalogKeepsTheLoadedCatalogWhenTheReadFails(t *testing.T) {
srv := catalogServer(t, func() map[string]any {
return map[string]any{"acme": catalogProvider("acme", "ACME_API_KEY", "acme-one")}
})
t.Setenv("ACME_API_KEY", "resolved-by-the-secret-registry")
b := newCatalogBoot(t, srv.URL)
if err := b.refreshModelCatalog(t.Context()); err != nil {
t.Fatalf("refreshModelCatalog: %v", err)
}
// The endpoint stops answering and the cache is gone, so the read has no
// fallback left.
srv.Close()
if err := os.Remove(b.catalogCachePath); err != nil && !errors.Is(err, fs.ErrNotExist) {
t.Fatalf("remove cache: %v", err)
}
if err := b.refreshModelCatalog(t.Context()); err == nil {
t.Fatal("refreshModelCatalog error = nil, want the failed read reported")
}
if _, models := b.catalogState(); !slices.Contains(models, "acme/acme-one") {
t.Errorf("catalog models = %v, want the loaded catalog kept", models)
}
if got := b.cfgHolder.Get().ModelLimits["acme/acme-one"]; got.ContextWindow != 128000 {
t.Errorf("running model limits = %+v, want the last-known-good catalog", got)
}
}
// TestBootCatalogReachesTheRunningConfig is the projection-site check for the
// boot half: the catalog boot read must be in the config the process runs on,
// not only in the boot struct the chat runtime was built from. Otherwise the
// first live update is the first snapshot to carry a catalog model limit.
func TestBootCatalogReachesTheRunningConfig(t *testing.T) {
srv := catalogServer(t, func() map[string]any {
return map[string]any{"acme": catalogProvider("acme", "ACME_API_KEY", "acme-one")}
})
t.Setenv("ACME_API_KEY", "resolved-by-the-secret-registry")
b := newCatalogBoot(t, srv.URL)
b.loadCatalog(t.Context(), filepath.Join(t.TempDir(), "config.toml"))
if got := b.cfgHolder.Get().ModelLimits["acme/acme-one"]; got.ContextWindow != 128000 {
t.Errorf("running model limits = %+v, want the catalog boot loaded", got)
}
if _, models := b.catalogState(); !slices.Contains(models, "acme/acme-one") {
t.Errorf("catalog models = %v, want the boot catalog", models)
}
}
// TestChatModelManagerReplacesItsCatalogRatherThanMerging: a refresh must
// drop what the previous snapshot contributed. A manager that only merged
// would keep offering a model the catalog no longer publishes, and would
// describe a provider that no longer exists.
func TestChatModelManagerReplacesItsCatalogRatherThanMerging(t *testing.T) {
manager := newChatModelManager(map[string]string{"chat": "acme/one"})
manager.SetModelCatalog(
modelcatalog.Snapshot{Providers: []modelcatalog.Provider{
{ID: "acme", Name: "Acme", Models: []modelcatalog.Model{{ID: "one"}, {ID: "two"}}},
}},
[]string{"acme/one", "acme/two"},
)
if !slices.Contains(manager.Models(), "acme/two") {
t.Fatalf("chat models = %v, want the catalog's models offered", manager.Models())
}
if got := manager.ProviderDisplayName("acme"); got != "Acme" {
t.Fatalf("provider display name = %q, want the catalog's name", got)
}
manager.SetModelCatalog(
modelcatalog.Snapshot{Providers: []modelcatalog.Provider{
{ID: "acme", Name: "Acme", Models: []modelcatalog.Model{{ID: "one"}}},
}},
[]string{"acme/one"},
)
if slices.Contains(manager.Models(), "acme/two") {
t.Errorf("chat models = %v, want the withdrawn model dropped", manager.Models())
}
if _, ok := manager.ModelDetails("acme/two"); ok {
t.Error("chat model details still carry the withdrawn model")
}
if got := manager.ProviderDisplayName("gone"); got != "" {
t.Errorf("provider display name for an absent provider = %q, want empty", got)
}
if !slices.Contains(manager.Models(), "acme/one") {
t.Errorf("chat models = %v, want the surviving model kept", manager.Models())
}
}
@@ -0,0 +1,163 @@
package archied
import (
"encoding/json"
"io"
"net/http"
"net/http/httptest"
"sync"
"testing"
"github.com/samcharles93/ai-sdk/runtime"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/modelcatalog"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/tools/mcp"
)
// capturedChatRequest is the JSON body the OpenAI-compatible provider sent for
// the last call, which is where the max-token parameter name is chosen.
type capturedChatRequest struct {
mu sync.Mutex
body map[string]any
}
func (c *capturedChatRequest) get() map[string]any {
c.mu.Lock()
defer c.mu.Unlock()
return c.body
}
// newCapturingChatAPI answers every completion and records the wire body, so a
// test can assert the parameter the provider actually emitted rather than an
// option the composition root merely set.
func newCapturingChatAPI(t *testing.T, capture *capturedChatRequest) *httptest.Server {
t.Helper()
api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var body map[string]any
_ = json.NewDecoder(r.Body).Decode(&body)
capture.mu.Lock()
capture.body = body
capture.mu.Unlock()
w.Header().Set("Content-Type", "application/json")
_, _ = io.WriteString(w, `{"id":"chatcmpl-1","object":"chat.completion","created":1,"model":"test",`+
`"choices":[{"index":0,"message":{"role":"assistant","content":"ok"},"finish_reason":"stop"}],`+
`"usage":{"prompt_tokens":1,"completion_tokens":1,"total_tokens":2}}`)
}))
t.Cleanup(api.Close)
return api
}
// assertWireBound asserts the max-token parameter the provider emitted: absent
// entirely for a reasoning model (its only accepted form with this ai-sdk
// release), present with the caller's bound for a classic one.
func assertWireBound(t *testing.T, capture *capturedChatRequest, wantBound bool, wantValue int) {
t.Helper()
bound, present := capture.get()["max_tokens"]
if present != wantBound {
t.Fatalf("request body max_tokens present = %v (value %v), want %v; body = %v", present, bound, wantBound, capture.get())
}
if present && bound != float64(wantValue) {
t.Fatalf("request body max_tokens = %v, want %d; body = %v", bound, wantValue, capture.get())
}
}
// TestChatTurnParameterNameFollowsModelClass proves the chat turn path reaches
// the provider without a max-token bound for a reasoning-class model, while a
// classic model still carries one. The bound itself is unchanged; only the
// parameter the chat-completions provider would serialise it into differs, and
// reasoning models reject `max_tokens` with HTTP 400.
func TestChatTurnParameterNameFollowsModelClass(t *testing.T) {
tests := []struct {
name string
reasoning bool
wantBound bool
modelRef string
maxOutput int
wantValue int
}{
{name: "reasoning model", reasoning: true, wantBound: false, modelRef: "openai/gpt-5.4", maxOutput: 4096},
{name: "classic model", reasoning: false, wantBound: true, modelRef: "openai/gpt-4o", maxOutput: 4096, wantValue: 4096},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
capture := &capturedChatRequest{}
api := newCapturingChatAPI(t, capture)
llm := agentexec.NewRuntime(map[string]agentexec.Provider{
"openai": {Class: "openai", BaseURL: api.URL},
})
model := newChatTurnModel(func() *runtime.Runtime { return llm }, tools.NewRegistry(), 1, func() agentexec.ToolLimits { return agentexec.ToolLimits{} }, nil)
prepared, err := model.Prepare(t.Context(), gateway.TurnPrepareContext{
Model: tc.modelRef, Reasoning: tc.reasoning,
})
if err != nil {
t.Fatalf("Prepare() error = %v", err)
}
_, err = prepared.Generate(t.Context(), gateway.TurnModelRequest{
Messages: []gateway.CompressedMessage{{Role: "user", Content: "hi"}},
MaxOutputTokens: tc.maxOutput,
}, nil)
if err != nil {
t.Fatalf("Generate() error = %v", err)
}
assertWireBound(t, capture, tc.wantBound, tc.wantValue)
})
}
}
// TestMCPSamplingParameterNameFollowsModelClass proves the second place the
// process sets a max-token bound -- server-requested sampling, which also
// applies a default when the request is silent -- preserves it for a classic
// model and drops it entirely for a reasoning one.
func TestMCPSamplingParameterNameFollowsModelClass(t *testing.T) {
tests := []struct {
name string
modelRef string
model modelcatalog.Model
wantBound bool
wantValue int
}{
{
name: "reasoning model",
modelRef: "openai/gpt-5.4",
model: modelcatalog.Model{ID: "gpt-5.4", Reasoning: true, MaxOutputTokens: 128000},
},
{
name: "classic model",
modelRef: "openai/gpt-4o",
model: modelcatalog.Model{ID: "gpt-4o", MaxOutputTokens: 128000},
wantBound: true,
wantValue: agentexec.DefaultSamplingMaxTokens,
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
capture := &capturedChatRequest{}
api := newCapturingChatAPI(t, capture)
b := newBootstrap()
b.setLLM(agentexec.NewRuntime(map[string]agentexec.Provider{
"openai": {Class: "openai", BaseURL: api.URL},
}))
b.chatModels = newChatModelManager(map[string]string{"chat": tc.modelRef})
b.chatModels.SetModelCatalog(modelcatalog.Snapshot{
Providers: []modelcatalog.Provider{{ID: "openai", Models: []modelcatalog.Model{tc.model}}},
}, []string{tc.modelRef})
b.providerOutcomes = newProviderOutcomeRecorder()
_, err := b.mcpSamplingHandler()(t.Context(), mcp.SamplingRequest{
Messages: []mcp.SamplingMessage{{Role: "user", Content: mcp.SamplingContent{Type: "text", Text: "hi"}}},
})
if err != nil {
t.Fatalf("sampling handler error = %v", err)
}
assertWireBound(t, capture, tc.wantBound, tc.wantValue)
})
}
}
@@ -0,0 +1,155 @@
package archied
import (
"archive/tar"
"bytes"
"context"
"go/ast"
"go/parser"
"go/token"
"net"
"testing"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
"google.golang.org/grpc/test/bufconn"
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/domain/storepkg"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
)
// contributedLayer ships one workflow definition file's portable YAML.
func contributedLayer(t *testing.T, path, yaml string) []byte {
t.Helper()
var raw bytes.Buffer
writer := tar.NewWriter(&raw)
if err := writer.WriteHeader(&tar.Header{Typeflag: tar.TypeReg, Name: path, Size: int64(len(yaml))}); err != nil {
t.Fatal(err)
}
if _, err := writer.Write([]byte(yaml)); err != nil {
t.Fatal(err)
}
if err := writer.Close(); err != nil {
t.Fatal(err)
}
return raw.Bytes()
}
func packageDescriptor() storepkg.Descriptor {
return storepkg.Descriptor{
APIVersion: storepkg.APIVersion, DisplayName: "Review pack", Version: "1",
Contributes: storepkg.Contributions{Workflows: []string{"workflows/review.yaml"}},
Files: []storepkg.File{{Path: "workflows/review.yaml", Mode: 0o644}},
}
}
// TestPackageContributionsLiveRoundTrip drives the State Store's own
// composition — the projections stateStoreDeps wires, the install and remove
// RPCs the dashboard calls, and the workflow-definitions resource the daemon
// reads per dispatch — over one real gRPC connection: installing a package
// makes its workflow a usable org resource, and removing it stops being
// usable, both without restarting anything.
func TestPackageContributionsLiveRoundTrip(t *testing.T) {
db := pgstore.Open(t)
projections, err := newPackageProjections(db.Pool)
if err != nil {
t.Fatal(err)
}
const yaml = "id: review\nsteps:\n - type: bootstrap.apply\n"
service := storepkg.Service{
Registry: packageLayerRegistry{descriptor: packageDescriptor(), layer: contributedLayer(t, "workflows/review.yaml", yaml)},
Store: postgres.NewInstalledPackages(db.Pool),
Projections: projections,
}
listener := bufconn.Listen(1 << 20)
server := grpc.NewServer()
staterpc.RegisterServer(server, staterpc.Deps{Packages: service})
go func() { _ = server.Serve(listener) }()
t.Cleanup(func() { server.Stop(); _ = listener.Close() })
conn, err := grpc.NewClient("passthrough:///state",
grpc.WithTransportCredentials(insecure.NewCredentials()),
grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) { return listener.DialContext(ctx) }))
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = conn.Close() })
client := staterpc.NewClient(conn)
const digest = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
if _, err := client.InstallPackage(t.Context(), "org-a", "review", "localhost:5000/review", digest); err != nil {
t.Fatal(err)
}
// The contribution is usable: the org resource the daemon's
// WorkflowDefinitions client reads carries it now, no restart involved.
resource, err := postgres.NewResources(db.Pool).Resource(t.Context(), "org-a", controlplane.WorkflowDefinitionsKind)
if err != nil {
t.Fatal(err)
}
collection, err := workflow.DecodeDefinitionCollection(resource.Value, workflow.BuiltinStepRegistry())
if err != nil {
t.Fatal(err)
}
if _, ok := collection.DefinitionByID("review"); !ok {
t.Fatal("installed package's workflow is not an org workflow after install")
}
if err := client.RemoveInstalled(t.Context(), "org-a", "review"); err != nil {
t.Fatal(err)
}
resource, err = postgres.NewResources(db.Pool).Resource(t.Context(), "org-a", controlplane.WorkflowDefinitionsKind)
if err != nil {
t.Fatal(err)
}
collection, err = workflow.DecodeDefinitionCollection(resource.Value, workflow.BuiltinStepRegistry())
if err != nil {
t.Fatal(err)
}
if _, ok := collection.DefinitionByID("review"); ok {
t.Fatal("removed package's workflow still dispatches: the org resource kept it")
}
if entries, err := postgres.NewPackageContributions(db.Pool).Entries(t.Context(), "org-a", "review"); err != nil || len(entries) != 0 {
t.Fatalf("contributions ledger after removal = %#v, %v", entries, err)
}
}
type packageLayerRegistry struct {
descriptor storepkg.Descriptor
layer []byte
}
func (r packageLayerRegistry) Fetch(context.Context, string, string) (storepkg.Descriptor, []byte, error) {
return r.descriptor, r.layer, nil
}
// TestStateStoreDepsWiresPackageProjections pins the wiring the live round
// trip drives: stateStoreDeps builds projections on the State Store's pool and
// carries them into the packages service it composes.
func TestStateStoreDepsWiresPackageProjections(t *testing.T) {
file := "state_store.go"
fset := token.NewFileSet()
parsed, err := parser.ParseFile(fset, file, nil, 0)
if err != nil {
t.Fatal(err)
}
var calls []string
ast.Inspect(parsed, func(node ast.Node) bool {
if call, ok := node.(*ast.CallExpr); ok {
if fn, ok := call.Fun.(*ast.Ident); ok {
calls = append(calls, fn.Name)
}
}
return true
})
found := false
for _, call := range calls {
if call == "newPackageProjections" {
found = true
}
}
if !found {
t.Fatalf("stateStoreDeps (%s body) wires no package projections", file)
}
}
+306
View File
@@ -0,0 +1,306 @@
package archied
import (
"context"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"io/fs"
"log/slog"
"os"
"path/filepath"
"slices"
"strings"
"sync"
"time"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/eda/module"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/plugin/pluginextract"
"github.com/samcharles93/archie-core/internal/secret"
)
// The three directory families a plugin-settings document names and a
// reconciliation reads.
const (
reconcilePlugins = "plugin"
reconcileModules = "module"
reconcileSecrets = "secret"
)
// pluginReconciler loads plugin, module and secret-engine files that appear or
// change in the directories the running configuration names, so an operator can
// drop a file beside a running daemon and have it take effect without a
// restart. Yaegi cannot unload an interpreter, so a removed file's code keeps
// running and the reconciler reports it through apply status until the process
// restarts (docs/prds/plugin-settings-live.md).
//
// Files are content-hashed, so a tick loads only what appeared or changed: the
// boot load's files are seeded as already loaded. A file whose load fails is
// forgotten until its content changes, the same degrade-and-skip rule the boot
// loaders apply.
type pluginReconciler struct {
log *slog.Logger
pluginReconcileTargets
// reconcileMu serializes reconciliations: the poller's tick and a stored
// plugin-settings update both run one, and they share the loaded set.
reconcileMu sync.Mutex
loaded map[string]loadedPluginFile
}
type pluginReconcileTargets struct {
host *plugin.Host
secrets *secret.Registry
modules *module.ModuleRegistry
// dirs returns the running configuration, the source of the three
// directories. It is read each tick so a changed directory retargets the
// next reconciliation without a restart.
dirs func() config.Config
// relayer re-runs the configuration layering after a secret engine loads
// or changes, which re-resolves provider credentials against the new
// engine. Nil in tests that do not layer.
relayer func(ctx context.Context) error
// report publishes the reconciliation outcome, including a nil error on a
// clean pass so an outstanding removal clears.
report func(ctx context.Context, err error)
}
type loadedPluginFile struct {
hash string
category string
// failed marks a file whose last load failed. It is not reported as a
// removal while it is still present, and a content change retries it.
failed bool
}
func newPluginReconciler(log *slog.Logger, targets pluginReconcileTargets) *pluginReconciler {
if log == nil {
log = slog.New(slog.DiscardHandler)
}
return &pluginReconciler{
log: log,
pluginReconcileTargets: targets,
loaded: make(map[string]loadedPluginFile),
}
}
// seed records the files the boot load already evaluated, so the first tick
// loads only what appeared or changed since boot. The daemon calls it after
// loadPlugins, loadWorkflows and configuredSecretRegistry have run.
func (r *pluginReconciler) seed() {
next := make(map[string]loadedPluginFile)
for _, spec := range r.categories(r.dirs()) {
paths, err := goFiles(spec.dir)
if err != nil {
r.log.Warn("plugin directory not seeded", "category", spec.category, "dir", spec.dir, "err", err)
continue
}
for _, path := range paths {
hash, err := fileHash(path)
if err != nil {
continue
}
next[path] = loadedPluginFile{hash: hash, category: spec.category}
}
}
r.reconcileMu.Lock()
r.loaded = next
r.reconcileMu.Unlock()
}
// run reconciles on interval until ctx ends. The interval is the apply-status
// restamp constant, so a dropped file needs no filesystem watch and a
// reconciliation report is refreshed at the same cadence as every other apply
// status record.
func (r *pluginReconciler) run(ctx context.Context, interval time.Duration) {
ticker := time.NewTicker(interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
_ = r.reconcile(ctx)
}
}
}
type reconcileCategory struct {
category string
dir string
}
func (r *pluginReconciler) categories(cfg config.Config) []reconcileCategory {
return []reconcileCategory{
{reconcilePlugins, cfg.PluginDir},
{reconcileModules, cfg.ModuleDir},
{reconcileSecrets, cfg.SecretEngineDir},
}
}
// reconcile re-reads the three directories against the running config and
// loads every new or changed file. It returns the outstanding problems -- a
// removal, a failed load, an unreadable directory -- joined, and reports the
// same through apply status. A nil return is a clean pass and clears the
// record's error.
func (r *pluginReconciler) reconcile(ctx context.Context) error {
r.reconcileMu.Lock()
defer r.reconcileMu.Unlock()
var problems []error
next := make(map[string]loadedPluginFile, len(r.loaded))
for _, spec := range r.categories(r.dirs()) {
problems = append(problems, r.reconcileCategory(ctx, spec, next)...)
}
for path, file := range r.loaded {
if _, ok := next[path]; ok || file.failed {
continue
}
problems = append(problems, fmt.Errorf("%s file %s was removed; it keeps running until the process restarts", file.category, path))
}
r.loaded = next
// The layering re-runs every tick, not only when a secret engine changed:
// it re-resolves provider credentials, so a provider disabled at boot for
// an unresolvable engine is re-resolved on the first tick that finds it,
// and a changed directory retargets the next tick without a restart
// (docs/prds/plugin-settings-live.md, "Triggers").
if r.relayer != nil {
if err := r.relayer(ctx); err != nil {
problems = append(problems, fmt.Errorf("re-resolve provider credentials: %w", err))
}
}
err := errors.Join(problems...)
if r.report != nil {
r.report(ctx, err)
}
return err
}
// reconcileCategory loads the new and changed files of one directory into
// next, returning the problems it met. A directory that became unreadable
// keeps the entries this category already had: it is not a removal of the
// files loaded before that.
func (r *pluginReconciler) reconcileCategory(ctx context.Context, spec reconcileCategory, next map[string]loadedPluginFile) []error {
var problems []error
paths, err := goFiles(spec.dir)
if err != nil {
problems = append(problems, fmt.Errorf("%s directory %q: %w", spec.category, spec.dir, err))
for path, file := range r.loaded {
if file.category == spec.category {
next[path] = file
}
}
return problems
}
for _, path := range paths {
hash, err := fileHash(path)
if err != nil {
problems = append(problems, fmt.Errorf("read %s: %w", path, err))
continue
}
if previous, ok := r.loaded[path]; ok && previous.hash == hash {
next[path] = previous
continue
}
if err := r.load(ctx, spec.category, path); err != nil {
problems = append(problems, fmt.Errorf("%s %s: %w", spec.category, path, err))
// Record the failed content so the same broken file is not retried
// every tick; changing it retries the load.
next[path] = loadedPluginFile{hash: hash, category: spec.category, failed: true}
continue
}
next[path] = loadedPluginFile{hash: hash, category: spec.category}
r.log.Info("runtime directory file loaded", "category", spec.category, "path", path)
}
return problems
}
func (r *pluginReconciler) load(ctx context.Context, category, path string) error {
switch category {
case reconcilePlugins:
return r.loadPlugin(ctx, path)
case reconcileModules:
return r.loadModule(path)
case reconcileSecrets:
if r.secrets == nil {
return errors.New("no secret registry to load into")
}
return r.secrets.LoadFile(path, secretEngineSymbols...)
default:
return fmt.Errorf("unknown reconcile category %q", category)
}
}
func (r *pluginReconciler) loadPlugin(ctx context.Context, path string) error {
if r.host == nil {
return errors.New("no plugin host to load into")
}
loaded, err := plugin.LoadFile(path, pluginextract.Symbols)
if err != nil {
return err
}
module, err := plugin.AdaptLegacy(loaded)
if err != nil {
return err
}
// The manifest id is the plugin's name, so an edited file that keeps its
// name replaces the running module and a new name adds one.
if r.host.Has(module.Manifest().ID) {
return r.host.Replace(ctx, module)
}
return r.host.Add(ctx, module)
}
func (r *pluginReconciler) loadModule(path string) error {
if r.modules == nil {
return errors.New("no module registry to load into")
}
kind := strings.TrimSuffix(filepath.Base(path), ".go")
if !slices.Contains(module.Kinds(), kind) {
// A .go file for a kind this build has no contract for; the boot load
// iterates the known kinds and ignores it too.
return nil
}
return r.modules.Register(kind, filepath.Dir(path))
}
// goFiles lists the .go files directly under dir, sorted. A missing directory
// reconciles to an empty set, the convention every boot loader already follows.
func goFiles(dir string) ([]string, error) {
if dir == "" {
return nil, nil
}
entries, err := os.ReadDir(dir)
if errors.Is(err, fs.ErrNotExist) {
return nil, nil
}
if err != nil {
return nil, err
}
paths := make([]string, 0, len(entries))
for _, entry := range entries {
if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".go") {
continue
}
paths = append(paths, filepath.Join(dir, entry.Name()))
}
slices.Sort(paths)
return paths, nil
}
func fileHash(path string) (string, error) {
content, err := os.ReadFile(path)
if err != nil {
return "", err
}
sum := sha256.Sum256(content)
return hex.EncodeToString(sum[:]), nil
}
@@ -0,0 +1,297 @@
package archied
import (
"context"
"log/slog"
"os"
"path/filepath"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/eda/module"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/secret"
)
// docs/prds/plugin-settings-live.md: a plugin or secret-engine file dropped
// into the running configuration's directory loads without a restart, an
// edited file replaces what runs, and a removed file keeps running with the
// removal reported through apply status until the process restarts.
const reconcilerPluginSource = `package main
import "github.com/samcharles93/archie-core/internal/plugin"
var Plugin = plugin._Plugin{
WName: func() string { return "hello" },
WVersion: func() string { return "1.0.0" },
}
`
const reconcilerSecretSource = `package main
import "github.com/samcharles93/archie-core/internal/secret"
var Engine = secret._Engine{
WName: func() string { return "hello" },
WVersion: func() string { return "1.0.0" },
WResolve: func(key string) (string, error) { return "one:" + key, nil },
}
`
const reconcilerEditedSecretSource = `package main
import "github.com/samcharles93/archie-core/internal/secret"
var Engine = secret._Engine{
WName: func() string { return "hello" },
WVersion: func() string { return "2.0.0" },
WResolve: func(key string) (string, error) { return "two:" + key, nil },
}
`
// reconcilerHarness is one running directory set: a started plugin host, a
// fresh secret registry, an empty module registry, and the config that names
// the two directories a test writes into.
type reconcilerHarness struct {
root *plugin.Host
secrets *secret.Registry
cfg config.Config
plugins string
secretsD string
mods *module.ModuleRegistry
}
func newReconcilerHarness(t *testing.T) *reconcilerHarness {
t.Helper()
h := &reconcilerHarness{
root: plugin.NewHost(),
secrets: secret.NewRegistry(),
mods: module.New(),
plugins: t.TempDir(),
secretsD: t.TempDir(),
}
if err := h.root.Start(t.Context()); err != nil {
t.Fatalf("start host: %v", err)
}
h.cfg = config.Config{PluginDir: h.plugins, SecretEngineDir: h.secretsD}
return h
}
func (h *reconcilerHarness) reconciler() *pluginReconciler {
return newPluginReconciler(slog.New(slog.DiscardHandler), pluginReconcileTargets{
host: h.root,
secrets: h.secrets,
modules: h.mods,
dirs: func() config.Config { return h.cfg },
})
}
func writeReconcilerFile(t *testing.T, path, source string) {
t.Helper()
if err := os.WriteFile(path, []byte(source), 0o644); err != nil {
t.Fatal(err)
}
}
func TestPluginReconcilerLoadsADroppedPluginAndSecretEngine(t *testing.T) {
h := newReconcilerHarness(t)
r := h.reconciler()
// Boot loaded the (empty) directories; seed is what the daemon does after
// its own boot load so the first tick does not re-load the boot set.
r.seed()
writeReconcilerFile(t, filepath.Join(h.plugins, "hello.go"), reconcilerPluginSource)
writeReconcilerFile(t, filepath.Join(h.secretsD, "hello.go"), reconcilerSecretSource)
if err := r.reconcile(t.Context()); err != nil {
t.Fatalf("reconcile: %v", err)
}
if !h.root.Has("hello") {
t.Error("dropped plugin was not loaded in place")
}
engine, ok := h.secrets.Get("hello")
if !ok {
t.Fatal("dropped secret engine was not loaded in place")
}
value, err := engine.Resolve("k")
if err != nil {
t.Fatalf("Resolve: %v", err)
}
if value != "one:k" {
t.Errorf("Resolve() = %q, want one:k", value)
}
}
func TestPluginReconcilerReplacesAnEditedSecretEngine(t *testing.T) {
h := newReconcilerHarness(t)
r := h.reconciler()
r.seed()
path := filepath.Join(h.secretsD, "hello.go")
writeReconcilerFile(t, path, reconcilerSecretSource)
if err := r.reconcile(t.Context()); err != nil {
t.Fatalf("first reconcile: %v", err)
}
writeReconcilerFile(t, path, reconcilerEditedSecretSource)
if err := r.reconcile(t.Context()); err != nil {
t.Fatalf("second reconcile: %v", err)
}
engine, ok := h.secrets.Get("hello")
if !ok {
t.Fatal("edited secret engine disappeared")
}
value, err := engine.Resolve("k")
if err != nil {
t.Fatalf("Resolve: %v", err)
}
if value != "two:k" {
t.Errorf("Resolve() after edit = %q, want the replaced two:k", value)
}
}
func TestPluginReconcilerReportsARemovedFileThatKeepsRunning(t *testing.T) {
h := newReconcilerHarness(t)
r := h.reconciler()
r.seed()
pluginPath := filepath.Join(h.plugins, "hello.go")
secretPath := filepath.Join(h.secretsD, "hello.go")
writeReconcilerFile(t, pluginPath, reconcilerPluginSource)
writeReconcilerFile(t, secretPath, reconcilerSecretSource)
if err := r.reconcile(t.Context()); err != nil {
t.Fatalf("first reconcile: %v", err)
}
if err := os.Remove(pluginPath); err != nil {
t.Fatal(err)
}
if err := os.Remove(secretPath); err != nil {
t.Fatal(err)
}
err := r.reconcile(t.Context())
if err == nil {
t.Fatal("a reconcile after two removals reported no problem")
}
for _, want := range []string{"hello.go", "removed", "restart"} {
if !strings.Contains(err.Error(), want) {
t.Errorf("removal report %q does not mention %q", err, want)
}
}
// The running code is not unloaded: Yaegi has no unload path, so both the
// module and the engine keep serving until the process restarts.
if !h.root.Has("hello") {
t.Error("a removed plugin stopped running")
}
if _, ok := h.secrets.Get("hello"); !ok {
t.Error("a removed secret engine was unregistered")
}
// Re-adding the file clears the removal: the replacement takes over and no
// old interpreter is left serving the path.
writeReconcilerFile(t, pluginPath, reconcilerPluginSource)
writeReconcilerFile(t, secretPath, reconcilerSecretSource)
if err := r.reconcile(t.Context()); err != nil {
t.Fatalf("reconcile after re-adding the files: %v", err)
}
}
func TestPluginSettingsLiveUpdateLoadsTheNewDirectory(t *testing.T) {
dir := t.TempDir()
writeReconcilerFile(t, filepath.Join(dir, "hello.go"), reconcilerPluginSource)
running := fileConfig()
b, status := newLiveApplyBoot(t, running)
resources := databaseOwnedResources()
resources[controlplane.PluginSettingsKind] = map[string]any{
"plugin_dir": dir, "module_dir": "/db/modules", "secret_engine_dir": "/db/secrets", "skills_dir": "",
}
b.controlPlane = controlplane.NewRPCClient(&controlPlaneStub{values: resources})
b.secrets = secret.NewRegistry()
host := plugin.NewHost()
if err := host.Start(t.Context()); err != nil {
t.Fatalf("start host: %v", err)
}
b.pluginReconciler = newPluginReconciler(b.log, pluginReconcileTargets{
host: host,
secrets: b.secrets,
modules: module.New(),
dirs: func() config.Config { return b.cfgHolder.Get() },
})
b.pluginReconciler.seed()
b.applyRuntimeResourceUpdate(t.Context(), controlplane.PluginSettingsKind, controlplane.AppliedResource{Version: 2})
if got := b.cfgHolder.Get().PluginDir; got != dir {
t.Fatalf("running plugin dir = %q, want the stored %q", got, dir)
}
if !host.Has("hello") {
t.Fatal("a stored plugin_dir change did not load its plugin without a restart")
}
last, ok := status.last(controlplane.PluginSettingsKind)
if !ok {
t.Fatal("the live plugin-settings update reported no apply status")
}
if last.Error != "" {
t.Errorf("apply status error = %q, want none for a live directory load", last.Error)
}
}
func TestPluginSettingsSkillsDirChangeIsRefusedOnTheLivePath(t *testing.T) {
running := fileConfig()
b, status := newLiveApplyBoot(t, running)
// The stored document's skills_dir (/db/skills) differs from the running
// empty value, and skills_dir has no live consumer.
b.controlPlane = controlplane.NewRPCClient(&controlPlaneStub{values: databaseOwnedResources()})
b.applyRuntimeResourceUpdate(t.Context(), controlplane.PluginSettingsKind, controlplane.AppliedResource{Version: 2})
if got := b.cfgHolder.Get().PluginDir; got != fileConfig().PluginDir {
t.Errorf("a refused plugin-settings document published plugin_dir %q, want the file's %q", got, fileConfig().PluginDir)
}
last, ok := status.last(controlplane.PluginSettingsKind)
if !ok {
t.Fatal("the refused plugin-settings update reported no apply status")
}
if !strings.Contains(last.Error, "skills_dir") {
t.Errorf("apply status error = %q, want it to name skills_dir", last.Error)
}
if last.AppliedVersion != 2 {
t.Errorf("apply status version = %d, want the refused version 2", last.AppliedVersion)
}
}
func TestPluginReconcilerReportsTheApplyStatusTruth(t *testing.T) {
h := newReconcilerHarness(t)
var reported []error
reported = nil
r := newPluginReconciler(slog.New(slog.DiscardHandler), pluginReconcileTargets{
host: h.root,
secrets: h.secrets,
modules: h.mods,
dirs: func() config.Config { return h.cfg },
report: func(_ context.Context, err error) { reported = append(reported, err) },
})
r.seed()
writeReconcilerFile(t, filepath.Join(h.secretsD, "hello.go"), reconcilerSecretSource)
if err := r.reconcile(t.Context()); err != nil {
t.Fatalf("clean reconcile: %v", err)
}
if len(reported) != 1 || reported[0] != nil {
t.Fatalf("clean reconcile reported %v, want one nil (a live add is applied)", reported)
}
if err := os.Remove(filepath.Join(h.secretsD, "hello.go")); err != nil {
t.Fatal(err)
}
if err := r.reconcile(t.Context()); err == nil {
t.Fatal("removal reconcile reported no error")
}
if len(reported) != 2 || reported[1] == nil {
t.Fatalf("removal reconcile reported %v, want the removal as the second record", reported)
}
}
-364
View File
@@ -1,364 +0,0 @@
package archied
import (
"context"
"fmt"
"log/slog"
"os"
"strconv"
"strings"
"sync"
"time"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/app/agentworker"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/artifactsync"
"github.com/samcharles93/archie-core/internal/worktree"
)
// prReviewer implements gateway.ChatPRReviewer for the daemon. It fetches
// an existing PR's metadata, materialises its head in a fresh clone, and runs
// the same adversarial reviewer the workflow stage uses, all synchronously in
// the requesting turn. Authorization is identity-scoped (the task_spawn
// repository allow-list) and one review per PR runs at a time.
type prReviewer struct {
forge forge.PullRequestReader // nil = forge cannot read PRs
trees *worktree.Manager
models map[string]string
providers map[string]agentexec.Provider
maxSteps int
// artifacts publishes the completed review to the collaborative editor.
// nil = publishing is disabled (no [artifacts] base_url configured).
artifacts artifactsync.Sender
// currentMaxSteps lets the composition root apply live control-plane
// versions to reviews that have not started yet. Tests and direct
// constructions retain maxSteps as the fallback.
currentMaxSteps func() int
// allowed maps a chat identity to the "owner/name" repos it may review.
// A nil identity is an authenticated dashboard operator, who may review
// any configured repository.
allowed map[string]map[string]bool
log *slog.Logger
mu sync.Mutex
inflight map[string]struct{}
}
var _ gateway.ChatPRReviewer = (*prReviewer)(nil)
// ReviewPR fetches the PR, runs the isolated reviewer against its head, and
// returns the structured findings. It never half-reviews: a missing forge
// capability, an unresolvable head/base, or an absent reviewer model returns
// an error rather than a fabricated result.
func (r *prReviewer) ReviewPR(ctx context.Context, identity *string, repo string, number int) (gateway.PRReviewResult, error) {
owner, name, err := splitOwnerRepo(repo)
if err != nil {
return gateway.PRReviewResult{}, err
}
if err := r.authorize(identity, owner, name); err != nil {
return gateway.PRReviewResult{}, err
}
key := owner + "/" + name + "#" + strconv.Itoa(number)
if !r.begin(key) {
return gateway.PRReviewResult{}, fmt.Errorf("review already in progress for %s", key)
}
defer r.end(key)
if r.forge == nil {
return gateway.PRReviewResult{}, fmt.Errorf("forge does not support pull request review")
}
pr, err := r.forge.GetPullRequest(ctx, owner, name, number)
if err != nil {
return gateway.PRReviewResult{}, err
}
model := agentworker.ReviewerModel(r.models)
if model == "" {
return gateway.PRReviewResult{}, fmt.Errorf("reviewer model is not configured (set models.reviewer, or models.builder as a fallback)")
}
reviewer := agentworker.NewOperatorReviewer(r.models, r.providers)
if reviewer == nil {
return gateway.PRReviewResult{}, fmt.Errorf("no provider runtime configured for the reviewer model %q", model)
}
if r.trees == nil {
return gateway.PRReviewResult{}, fmt.Errorf("worktree manager is not configured")
}
dir, cleanup, err := r.trees.CheckoutPR(ctx, owner, name, pr.HeadRef, pr.BaseRef)
if err != nil {
return gateway.PRReviewResult{}, err
}
defer cleanup()
diff, err := r.trees.Diff(ctx, dir, pr.BaseRef)
if err != nil {
return gateway.PRReviewResult{}, fmt.Errorf("compute PR diff: %w", err)
}
snapshotDir, err := os.MkdirTemp("", "pr-review-snapshot-*")
if err != nil {
return gateway.PRReviewResult{}, fmt.Errorf("create review snapshot directory: %w", err)
}
defer os.RemoveAll(snapshotDir)
if err := r.trees.Snapshot(ctx, dir, snapshotDir); err != nil {
return gateway.PRReviewResult{}, fmt.Errorf("snapshot PR head: %w", err)
}
maxSteps := r.maxSteps
if r.currentMaxSteps != nil {
maxSteps = r.currentMaxSteps()
}
report := reviewer.Review(ctx, workflow.ReviewRequest{
SnapshotDir: snapshotDir,
Diff: diff,
IssueText: prIssueText(pr),
MaxSteps: maxSteps,
})
r.logReview(key, model, report)
result := mapReviewResult(repo, number, model, report)
return r.attachArtifact(ctx, result, identity, owner, name, number, report), nil
}
// authorize enforces the identity-scoped repository allow-list. A nil
// identity (dashboard operator) may review any configured repository.
func (r *prReviewer) authorize(identity *string, owner, repo string) error {
full := owner + "/" + repo
if identity == nil {
for _, set := range r.allowed {
if set[full] {
return nil
}
}
return fmt.Errorf("repository %q is not configured", full)
}
set, ok := r.allowed[*identity]
if !ok {
return fmt.Errorf("identity %q is not configured for PR review", *identity)
}
if !set[full] {
return fmt.Errorf("repository %q is not configured for this identity", full)
}
return nil
}
func (r *prReviewer) begin(key string) bool {
r.mu.Lock()
defer r.mu.Unlock()
if r.inflight == nil {
r.inflight = make(map[string]struct{})
}
if _, ok := r.inflight[key]; ok {
return false
}
r.inflight[key] = struct{}{}
return true
}
func (r *prReviewer) end(key string) {
r.mu.Lock()
defer r.mu.Unlock()
delete(r.inflight, key)
}
func (r *prReviewer) logReview(key, model string, report workflow.ReviewReport) {
if r.log == nil {
return
}
blocking := 0
for _, f := range report.Findings {
if f.Blocking() {
blocking++
}
}
r.log.Info("operator PR review complete",
"pr", key, "model", model, "status", string(report.Status),
"findings", len(report.Findings), "blocking", blocking)
}
// attachArtifact publishes the report when the sender is configured and
// records the editor deep link on the result. Publishing never fails the
// review: a failure degrades to an empty URL.
func (r *prReviewer) attachArtifact(ctx context.Context, result gateway.PRReviewResult, identity *string, owner, name string, number int, report workflow.ReviewReport) gateway.PRReviewResult {
result.ArtifactURL = r.publishArtifact(ctx, reviewActor(identity), owner, name, number, report)
return result
}
// reviewActor resolves the attribution: the requesting chat identity when one
// exists, else the daemon's operator-reviewer actor.
func reviewActor(identity *string) string {
if identity != nil && *identity != "" {
return *identity
}
return "system:pr-reviewer"
}
// publishArtifact renders the report and hands it to the collaborative
// editor when artifact publishing is configured. It returns the editor deep
// link, or "" when publishing is disabled or failed: a publish failure is a
// logged degradation, never an error that fails the producing review.
func (r *prReviewer) publishArtifact(ctx context.Context, actor, owner, name string, number int, report workflow.ReviewReport) string {
if r.artifacts == nil {
return ""
}
title := fmt.Sprintf("Review of %s/%s#%d", owner, name, number)
artifact := artifactsync.Artifact{
Title: title,
Source: report.RenderMarkdown(title),
Meta: artifactsync.Meta{
Format: "markdown",
Category: "pr-review",
Visibility: "account-only",
Egress: "none",
Actor: actor,
Origin: "pr-review",
RequestID: "artifact:pr-review:" + owner + "/" + name + "#" + strconv.Itoa(number),
Version: "r1",
SentAt: time.Now().UTC(),
Task: &artifactsync.Task{Owner: owner, Repo: name, Number: number},
},
}
url, err := r.artifacts.Publish(ctx, artifact)
if err != nil {
if r.log != nil {
r.log.Warn("artifact publish failed; the review result is unaffected",
"artifact", artifact.RequestID(), "err", err)
}
return ""
}
if r.log != nil {
r.log.Info("artifact published", "artifact", artifact.RequestID(), "url", url)
}
return url
}
// splitOwnerRepo splits "owner/name" with the same validation the gateway's
// task_spawn allow-list uses.
func splitOwnerRepo(s string) (owner, repo string, err error) {
owner, repo, ok := strings.Cut(s, "/")
if !ok || owner == "" || repo == "" {
return "", "", fmt.Errorf("repository %q must be owner/name", s)
}
return owner, repo, nil
}
// prIssueText renders the PR title/body as the review's issue text.
func prIssueText(pr forge.PullRequest) string {
if pr.Body == "" {
return pr.Title
}
return pr.Title + "\n\n" + pr.Body
}
// mapReviewResult adapts a workflow.ReviewReport into the gateway's
// channel-neutral result shape.
func mapReviewResult(repo string, number int, model string, report workflow.ReviewReport) gateway.PRReviewResult {
out := gateway.PRReviewResult{
Repo: repo,
Number: number,
Model: model,
Status: string(report.Status),
Summary: report.Summary,
Reason: report.SkipReason,
Findings: make([]gateway.PRReviewFinding, 0, len(report.Findings)),
}
for _, f := range report.Findings {
out.Findings = append(out.Findings, gateway.PRReviewFinding{
File: f.File,
Line: f.Line,
Defect: f.Defect,
FailureScenario: f.FailureScenario,
Verdict: string(f.Verdict),
Level: string(f.Level),
Category: string(f.Category),
Blocking: f.Blocking(),
})
}
return out
}
// buildReviewAllowlist derives the identity-scoped review allow-list from the
// same profiles task_spawn uses, so a chat identity and the review command
// agree on which repositories the identity may touch.
func buildReviewAllowlist(cfg config.Config) map[string]map[string]bool {
profiles, _ := chatTaskProfiles(cfg)
out := make(map[string]map[string]bool, len(profiles))
for _, p := range profiles {
set := make(map[string]bool, len(p.Repos))
for _, repo := range p.Repos {
set[repo] = true
}
out[p.Identity] = set
}
return out
}
// prReviewer assembles the operator-triggered review capability, or nil when
// the forge cannot read PRs (the noop forge, or a forge with no PR read
// support). A review tool that can never run must not be advertised, matching
// the TaskTools nil-backend rule.
//
// The instance is built once and memoized on the boot struct so every channel
// shares one in-flight set: a review of the same PR requested concurrently
// from the Web UI and Telegram deduplicates instead of running twice.
func (b *boot) prReviewer() gateway.ChatPRReviewer {
if b.chatPRReviewer != nil {
return b.chatPRReviewer
}
if b.trees == nil {
return nil
}
forgeReader, _ := b.forgeClient.(forge.PullRequestReader)
if forgeReader == nil {
return nil
}
maxSteps := b.cfg.Budgets.MaxSteps
if b.cfgHolder != nil {
maxSteps = b.cfgHolder.Get().Budgets.MaxSteps
}
review := &prReviewer{
forge: forgeReader,
trees: b.trees,
models: b.cfg.Models,
providers: executionProviders(b.cfg),
maxSteps: maxSteps,
artifacts: b.artifactSender(),
allowed: buildReviewAllowlist(b.cfg),
log: b.log,
}
if b.cfgHolder != nil {
review.currentMaxSteps = func() int { return b.cfgHolder.Get().Budgets.MaxSteps }
}
b.chatPRReviewer = review
return b.chatPRReviewer
}
// artifactSender builds the collaborative-editor sender when the [artifacts]
// section configures one. An empty base_url disables publishing entirely; a
// base_url with an unresolvable token is a missing credential, which disables
// the capability with a loud warning rather than stopping the daemon
// (docs/architecture/configuration.md, "A missing credential disables a
// capability").
func (b *boot) artifactSender() artifactsync.Sender {
cfg := b.cfg.Artifacts
if cfg.BaseURL == "" {
return nil
}
token, err := b.secrets.Resolve(cfg.Token)
if err != nil {
b.log.Warn("artifact publishing disabled: the service credential could not be resolved",
"base_url", cfg.BaseURL, "token_engine", cfg.Token.Engine, "err", err)
return nil
}
if token == "" {
b.log.Warn("artifact publishing disabled: the service token resolved empty",
"base_url", cfg.BaseURL, "token_engine", cfg.Token.Engine)
return nil
}
return artifactsync.NewClient(cfg.BaseURL, token)
}
-317
View File
@@ -1,317 +0,0 @@
package archied
import (
"context"
"errors"
"log/slog"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/artifactsync"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/worktree"
)
func TestSplitOwnerRepo(t *testing.T) {
tests := []struct {
in string
owner string
repo string
wantErr bool
}{
{"acme/widget", "acme", "widget", false},
{"acme/widget/service", "acme", "widget/service", false},
{"acme", "", "", true},
{"/widget", "", "", true},
{"acme/", "", "", true},
{"", "", "", true},
}
for _, tt := range tests {
owner, repo, err := splitOwnerRepo(tt.in)
if tt.wantErr {
if err == nil {
t.Errorf("splitOwnerRepo(%q) error = nil, want error", tt.in)
}
continue
}
if err != nil {
t.Errorf("splitOwnerRepo(%q) error = %v", tt.in, err)
continue
}
if owner != tt.owner || repo != tt.repo {
t.Errorf("splitOwnerRepo(%q) = (%q, %q), want (%q, %q)", tt.in, owner, repo, tt.owner, tt.repo)
}
}
}
func TestPRIssueText(t *testing.T) {
tests := []struct {
name string
pr forge.PullRequest
want string
}{
{"title only", forge.PullRequest{Title: "Fix login"}, "Fix login"},
{"title and body", forge.PullRequest{Title: "Fix login", Body: "The form 500s."}, "Fix login\n\nThe form 500s."},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := prIssueText(tt.pr); got != tt.want {
t.Errorf("prIssueText = %q, want %q", got, tt.want)
}
})
}
}
func TestMapReviewResult(t *testing.T) {
report := workflow.ReviewReport{
Status: workflow.ReviewStatusCompleted,
Summary: "checked and cleared",
Findings: []workflow.ReviewFinding{
{File: "a.go", Line: 3, Defect: "nil deref", FailureScenario: "x", Verdict: workflow.ReviewVerdictConfirmed, Level: workflow.ReviewLevelError, Category: workflow.ReviewCategoryNilRisk},
{File: "b.go", Line: 0, Defect: "style", FailureScenario: "y", Verdict: workflow.ReviewVerdictPlausible, Level: workflow.ReviewLevelWarn, Category: workflow.ReviewCategoryOther},
},
}
got := mapReviewResult("acme/widget", 7, "openai/gpt-5", report)
if got.Repo != "acme/widget" || got.Number != 7 || got.Model != "openai/gpt-5" || got.Status != "completed" || got.Summary != "checked and cleared" {
t.Fatalf("result meta = %+v", got)
}
if len(got.Findings) != 2 {
t.Fatalf("findings = %d, want 2", len(got.Findings))
}
if !got.Findings[0].Blocking {
t.Error("confirmed error finding should be blocking")
}
if got.Findings[1].Blocking {
t.Error("plausible warn finding must not be blocking")
}
if got.Findings[0].Line != 3 {
t.Errorf("line = %d, want 3", got.Findings[0].Line)
}
}
func TestMapReviewResultNotRunPreservesReason(t *testing.T) {
report := workflow.NewNotRunReviewReport("no reviewer model configured")
got := mapReviewResult("acme/widget", 7, "", report)
if got.Status != "not_run" || got.Reason != "no reviewer model configured" {
t.Fatalf("not_run result = %+v, want status not_run and reason preserved", got)
}
}
func TestPrReviewerAuthorize(t *testing.T) {
r := &prReviewer{allowed: map[string]map[string]bool{
"": {"acme/widget": true, "acme/core": true},
"archie": {"acme/widget": true},
}}
archie := "archie"
other := "other"
tests := []struct {
name string
identity *string
owner string
repo string
wantErr bool
}{
{"identity own repo", &archie, "acme", "widget", false},
{"identity foreign repo", &archie, "acme", "core", true},
{"unknown identity", &other, "acme", "widget", true},
{"operator any configured", nil, "acme", "core", false},
{"operator unconfigured repo", nil, "acme", "other", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := r.authorize(tt.identity, tt.owner, tt.repo)
if tt.wantErr && err == nil {
t.Errorf("authorize(%v, %s/%s) error = nil, want error", tt.identity, tt.owner, tt.repo)
}
if !tt.wantErr && err != nil {
t.Errorf("authorize(%v, %s/%s) error = %v, want nil", tt.identity, tt.owner, tt.repo, err)
}
})
}
}
func TestPrReviewerSingleflight(t *testing.T) {
r := &prReviewer{}
key := "acme/widget#7"
if !r.begin(key) {
t.Fatal("first begin = false, want true")
}
if r.begin(key) {
t.Fatal("concurrent begin = true, want false (deterministic single-flight)")
}
r.end(key)
if !r.begin(key) {
t.Fatal("begin after end = false, want true")
}
}
func TestBuildReviewAllowlist(t *testing.T) {
cfg := config.Config{
Identities: []config.IdentityConfig{
{Name: "archie", Repos: []config.Repo{{Owner: "acme", Name: "widget"}}},
},
}
allowed := buildReviewAllowlist(cfg)
if !allowed["archie"]["acme/widget"] {
t.Errorf("allowlist missing acme/widget for identity archie: %+v", allowed)
}
if allowed["archie"]["acme/core"] {
t.Errorf("allowlist leaked acme/core to identity archie: %+v", allowed)
}
if _, ok := allowed["nobody"]; ok {
t.Errorf("allowlist contains unknown identity nobody: %+v", allowed)
}
}
// reviewCapableForge satisfies both forge.Forge (via embedding) and
// forge.PullRequestReader, so boot.prReviewer can be exercised in isolation.
type reviewCapableForge struct {
forge.Forge
}
func (reviewCapableForge) GetPullRequest(context.Context, string, string, int) (forge.PullRequest, error) {
return forge.PullRequest{}, nil
}
// TestPrReviewerIsMemoized pins the cross-channel single-flight fix: every
// gateway must share one prReviewer so a review of the same PR requested from
// two channels at once deduplicates instead of running twice. The boot must
// own a worktree manager: a reviewer without one can never run and must not be
// produced (see TestPrReviewerNilWithoutTrees).
func TestPrReviewerIsMemoized(t *testing.T) {
b := &boot{
forgeClient: reviewCapableForge{Forge: forge.NewNoop(slog.New(slog.DiscardHandler))},
trees: &worktree.Manager{},
}
first := b.prReviewer()
if first == nil {
t.Fatal("prReviewer() = nil, want a reviewer")
}
if second := b.prReviewer(); first != second {
t.Fatal("prReviewer() returned distinct instances; channels would not share the in-flight set")
}
}
// TestPrReviewerNilWithoutTrees pins the producer-side invariant: a PR-capable
// forge without a worktree manager must yield no reviewer. The standalone
// Gateway never builds trees, and the daemon used to capture b.trees before it
// was assigned, so both advertised a review_pr tool that always failed.
func TestPrReviewerNilWithoutTrees(t *testing.T) {
b := &boot{forgeClient: reviewCapableForge{Forge: forge.NewNoop(slog.New(slog.DiscardHandler))}}
if got := b.prReviewer(); got != nil {
t.Fatalf("prReviewer() with no worktree manager = %T, want nil", got)
}
}
// TestReviewPRToolRegisteredOnlyWithWorkingReviewer composes the real boot
// wiring (boot.prReviewer -> gateway.ReviewTools) and asserts review_pr is
// advertised only when the reviewer can actually run.
func TestReviewPRToolRegisteredOnlyWithWorkingReviewer(t *testing.T) {
logger := slog.New(slog.DiscardHandler)
b := &boot{
forgeClient: reviewCapableForge{Forge: forge.NewNoop(logger)},
log: logger,
}
if hasReviewPRTool(gateway.ReviewTools(b.prReviewer(), "archie")) {
t.Fatal("review_pr advertised with no worktree manager: a tool that cannot run must not be offered")
}
b.trees = &worktree.Manager{}
if !hasReviewPRTool(gateway.ReviewTools(b.prReviewer(), "archie")) {
t.Fatal("review_pr not advertised with a worktree manager")
}
}
// hasReviewPRTool reports whether review_pr is offered. Presence is asserted by
// name rather than by entry count: the contract is that this one capability is
// offered only when it can run, so adding a sibling review tool must not turn
// this red.
func hasReviewPRTool(entries []tools.ToolEntry) bool {
for _, e := range entries {
if e.Name == "review_pr" {
return true
}
}
return false
}
type fakeArtifactSender struct {
calls int
url string
err error
last artifactsync.Artifact
}
func (f *fakeArtifactSender) Publish(_ context.Context, a artifactsync.Artifact) (string, error) {
f.calls++
f.last = a
if f.err != nil {
return "", f.err
}
return f.url, nil
}
func TestPrReviewerPublishesTheCompletedReview(t *testing.T) {
fake := &fakeArtifactSender{url: "https://offloaded.dev/collab?document=a_1"}
r := &prReviewer{artifacts: fake, log: slog.New(slog.DiscardHandler)}
report := workflow.NewCompletedReviewReport([]workflow.ReviewFinding{{
File: "handler.go", Line: 42, Defect: "nil deref",
FailureScenario: "empty payload crashes", Verdict: workflow.ReviewVerdictConfirmed,
Level: workflow.ReviewLevelError,
}}, "one finding")
report.Checked = []workflow.ReviewCheck{{Property: "p", Evidence: "e"}}
url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, report)
if url != fake.url {
t.Fatalf("publishArtifact = %q, want the sender's url %q", url, fake.url)
}
if fake.calls != 1 {
t.Fatalf("Publish called %d times, want 1", fake.calls)
}
got := fake.last
if got.Meta.Format != "markdown" || got.Meta.Category != "pr-review" {
t.Fatalf("format/category = %s/%s, want markdown/pr-review", got.Meta.Format, got.Meta.Category)
}
if got.Meta.Actor != "system:pr-reviewer" || got.Meta.Origin != "pr-review" {
t.Fatalf("attribution = %s/%s", got.Meta.Actor, got.Meta.Origin)
}
if got.Meta.Visibility != "account-only" || got.Meta.Egress != "none" {
t.Fatalf("visibility/egress = %s/%s", got.Meta.Visibility, got.Meta.Egress)
}
if got.Title != "Review of acme/widget#7" {
t.Fatalf("title = %q", got.Title)
}
if got.Meta.RequestID != "artifact:pr-review:acme/widget#7" {
t.Fatalf("requestId = %q, want the deterministic artifact key", got.Meta.RequestID)
}
if got.Meta.Task == nil || got.Meta.Task.Owner != "acme" || got.Meta.Task.Number != 7 {
t.Fatalf("task coordinates = %+v", got.Meta.Task)
}
if !strings.Contains(got.Source, "## Findings") {
t.Fatalf("source is not the rendered report:\n%s", got.Source)
}
}
func TestPrReviewerPublishDegradesOnSenderFailure(t *testing.T) {
r := &prReviewer{artifacts: &fakeArtifactSender{err: errors.New("503 exhausted")}, log: slog.New(slog.DiscardHandler)}
if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" {
t.Fatalf("url = %q, want empty on a failed publish", url)
}
}
func TestPrReviewerPublishIsANoOpWithoutASender(t *testing.T) {
r := &prReviewer{}
if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" {
t.Fatalf("url = %q, want empty when the sender is disabled", url)
}
}
+11 -1
View File
@@ -5,6 +5,7 @@ import (
"fmt"
"log/slog"
"os"
"reflect"
"strings"
"github.com/traefik/yaegi/stdlib/unrestricted"
@@ -15,6 +16,15 @@ import (
"github.com/samcharles93/archie-core/internal/secret/secretextract"
)
// secretEngineSymbols is the Yaegi symbol set every secret-engine load uses:
// the generated interface bridge, the host-side CLI helper, and unrestricted
// symbols for parity with skillscript interpretation. The boot load and a
// live directory reconciliation share it so an engine always loads the same
// way.
var secretEngineSymbols = []map[string]map[string]reflect.Value{
secretextract.Symbols, enginehost.Symbols, unrestricted.Symbols,
}
func configuredSecretRegistry(cfg *config.Config, log *slog.Logger) (*secret.Registry, error) {
registry := secret.NewRegistry()
if cfg.SecretEngineDir != "" {
@@ -24,7 +34,7 @@ func configuredSecretRegistry(cfg *config.Config, log *slog.Logger) (*secret.Reg
// host-side helper) because yaegi's interpreted os/exec cannot
// pass an environment to child processes; unrestricted symbols
// are included for parity with skillscript interpretation.
loaded, err := registry.LoadDir(cfg.SecretEngineDir, secretextract.Symbols, enginehost.Symbols, unrestricted.Symbols)
loaded, err := registry.LoadDir(cfg.SecretEngineDir, secretEngineSymbols...)
if err != nil {
return nil, fmt.Errorf("load secret engines from %q: %w", cfg.SecretEngineDir, err)
}
@@ -13,6 +13,7 @@ import (
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
"github.com/samcharles93/archie-core/internal/secret"
@@ -51,7 +52,7 @@ func TestStateStoreBootSeedsProviderSourceReference(t *testing.T) {
go func() { errCh <- RunStateStore(ctx, StateStoreOptions{Config: path, Listen: "127.0.0.1:0"}) }()
deadline := time.After(10 * time.Second)
for {
resource, err := store.Resource(t.Context(), controlplane.ProviderSettingsKind)
resource, err := store.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ProviderSettingsKind)
if err == nil {
if strings.Contains(string(resource.Value), "ARCHIE_PROVIDER_") || !strings.Contains(string(resource.Value), ref.Key) {
t.Fatalf("stored provider settings = %s, want source reference and no derived env name", resource.Value)
+20 -13
View File
@@ -117,6 +117,7 @@ var reloadableFields = map[string]bool{
"Models": true,
"ModelLimits": true,
"Notify": true,
"Review": true,
// BotUser/BotEmail used to be poll-path only; ForTask now carries both
// into the task snapshot as well, because the sandboxed worker builds
// its own worktree.Manager and signs its own commits (agentworker
@@ -134,11 +135,13 @@ var reloadableFields = map[string]bool{
// TestReloadableFieldsCoverForTaskSnapshot.
"Label": true,
"BotUser": true,
// Worked example of the every-consumer criterion above: the sole
// consumer is the webui maxRetriesFor handler (api_tasks.go:380,383),
// which re-reads per request; the daemon never reads MaxRetries. The
// per-task half of this list is pinned mechanically; this webui-only
// entry is pinned by TestChangedNonReloadableFields.
// MaxRetries has two consumers, both re-reading it: the webui
// maxRetriesFor handler (api_tasks.go:380,383) reads it per request, and
// ForTask carries it into every dispatched TaskConfig, where the
// container's remediation round cap reads it (StageRemediationRoundCap).
// The per-task half of this list is pinned mechanically by
// TestReloadableFieldsCoverForTaskSnapshot; the webui-only entry is pinned
// by TestChangedNonReloadableFields.
"MaxRetries": true,
// Tools.Policy (MaxResultChars/SpillDir) is carried into TaskConfig by
// ForTask (config.go) and applied fresh per dispatch via
@@ -155,17 +158,21 @@ var reloadableFields = map[string]bool{
// "Selection": a Kit profile applies without a restart. Credentials is the
// same shape one layer down: kitrun.Launcher reads Config.Get().Containers.
// Credentials fresh on every Launch (CredentialBindingsKind), never a slice
// captured once when the launcher was built. Everything else in
// Containers (Image, MaxConcurrency, MaxUptime, PullPolicy, Network) is
// frozen in the startup-built container pool -- the dispatchers re-read
// MaxConcurrency but the pool captures it at construction
// (container/pool.go:94,163), so a change only partially applies and must
// warn requires-restart. Forge.Host is carried into TaskContext by ForTask
// captured once when the launcher was built. Image, MaxConcurrency, MaxUptime,
// PullPolicy and Network are re-read per acquire by the container pool and
// MaxConcurrency also resizes the running dispatcher on publish
// (archie-core-zfb0.2), so a reload applies them without a restart.
// RegistryAuth stays frozen in the startup-built pool: it is file-owned and
// never part of the container-runtime-policies document, so a changed value
// must warn requires-restart. Forge.Host is carried into TaskContext by ForTask
// (display/link building only); the forge client itself is startup-built, so
// Type/Token/TokenEnv stay requires-restart.
var reloadableSubFields = map[string]map[string]bool{
"Containers": {"VolumeTTL": true, "Profiles": true, "Credentials": true},
"Forge": {"Host": true},
"Containers": {
"VolumeTTL": true, "Profiles": true, "Credentials": true,
"Image": true, "MaxConcurrency": true, "MaxUptime": true, "PullPolicy": true, "Network": true,
},
"Forge": {"Host": true},
// Policy is carried into TaskConfig by ForTask (config.go); MCPServers,
// WebFetch and Minimax are not and stay requires-restart.
"Tools": {"Policy": true},
+12 -9
View File
@@ -198,28 +198,31 @@ func TestChangedNonReloadableFields(t *testing.T) {
t.Fatalf("reloadable-only: got %v, want []", got)
}
// Containers sub-field granularity: Image change warns, MaxConcurrency
// and VolumeTTL changes do not.
// Containers sub-field granularity: the fields the pool re-reads per
// acquire, and the concurrency cap the dispatcher resizes on, are
// reloadable; RegistryAuth stays frozen in the startup-built pool.
c1 := base
c1.Containers = config.ContainerConfig{Image: "img1", MaxConcurrency: 2, VolumeTTL: config.Duration(24 * time.Hour)}
c2 := c1
c2.Containers.Image = "img2"
if got := changedNonReloadableFields(c1, c2); len(got) != 1 || got[0] != "Containers.Image" {
t.Fatalf("Image change: got %v, want [Containers.Image]", got)
if got := changedNonReloadableFields(c1, c2); len(got) != 0 {
t.Fatalf("Image change: got %v, want [] (the pool reads it per acquire)", got)
}
c3 := c1
c3.Containers.MaxConcurrency = 4
// MaxConcurrency is NOT reloadable: the dispatchers re-read it but the
// startup-built container pool captures it (container/pool.go:94), so
// a change only partially applies and must warn requires-restart.
if got := changedNonReloadableFields(c1, c3); len(got) != 1 || got[0] != "Containers.MaxConcurrency" {
t.Fatalf("MaxConcurrency change: got %v, want [Containers.MaxConcurrency]", got)
if got := changedNonReloadableFields(c1, c3); len(got) != 0 {
t.Fatalf("MaxConcurrency change: got %v, want [] (the pool reads it and the dispatcher resizes)", got)
}
c4 := c1
c4.Containers.VolumeTTL = config.Duration(48 * time.Hour)
if got := changedNonReloadableFields(c1, c4); len(got) != 0 {
t.Fatalf("VolumeTTL change: got %v, want []", got)
}
c5 := c1
c5.Containers.RegistryAuth = config.SecretRef{Engine: "env", Key: "REGISTRY_AUTH"}
if got := changedNonReloadableFields(c1, c5); len(got) != 1 || got[0] != "Containers.RegistryAuth" {
t.Fatalf("RegistryAuth change: got %v, want [Containers.RegistryAuth] (the pool resolves it at boot)", got)
}
// NATS is not reloadable: a URL change warns (the daemon's client is
// startup-built; containers get the frozen ConnectedNATS).
+26 -183
View File
@@ -1,22 +1,18 @@
// sd_notify.go implements systemd's sd_notify(3) protocol for archied: one
// READY=1 when the run loop starts serving, and a WATCHDOG=1 heartbeat while
// the run loop is demonstrably still making progress.
// sd_notify.go wires the daemon into internal/sdnotify's implementation of
// systemd's sd_notify(3) protocol: one READY=1 when the run loop starts
// serving, and a WATCHDOG=1 heartbeat while the run loop is demonstrably still
// making progress.
//
// The protocol is three environment variables and one datagram per state, so
// this file speaks it directly instead of taking a module dependency: the whole
// client is net.DialUnix plus a Write. Nothing here is fatal -- a process with
// no NOTIFY_SOCKET (a plain terminal, Docker, a user unit without WatchdogSec)
// sends nothing and serves exactly as before, and a socket that cannot be
// written to is logged and ignored.
// The protocol client and the heartbeat sampler live in internal/sdnotify
// because archie-messaging, a separate process that cannot import this
// package, is the next process that must be able to announce itself
// (archie-core-g5g8). What stays here is what is the daemon's own: which
// marker counts as progress (daemon.LastPollAt) and how long the loop may go
// without beginning a poll pass.
//
// The heartbeat is deliberately not a bare ticker. A ticker fires whether or
// not the loop it stands for is alive, so it would keep systemd satisfied while
// the event loop was wedged -- the exact failure the watchdog exists to catch.
// The sampler instead reads the daemon's own progress marker
// (daemon.LastPollAt, stamped by the poll loop at the start of every pass) and
// withholds the heartbeat once that marker is older than the loop's own poll
// cadence. While passes keep beginning, beats flow at half of WatchdogSec; a
// loop blocked inside a pass stops being reported as alive.
// Nothing here is fatal -- a process with no NOTIFY_SOCKET (a plain terminal,
// Docker, a user unit without WatchdogSec) sends nothing and serves exactly as
// before, and a socket that cannot be written to is logged and ignored.
//
// Consuming the states is the unit's business: READY=1 needs Type=notify, and
// the heartbeat needs WatchdogSec.
@@ -25,75 +21,12 @@ package archied
import (
"context"
"errors"
"fmt"
"log/slog"
"net"
"os"
"strconv"
"time"
"github.com/samcharles93/archie-core/internal/sdnotify"
)
const (
// notifySocketEnv names the socket a manager passes to a Type=notify unit.
notifySocketEnv = "NOTIFY_SOCKET"
// watchdogUsecEnv carries WatchdogSec in microseconds.
watchdogUsecEnv = "WATCHDOG_USEC"
// watchdogPIDEnv names the process whose beats the watchdog counts.
watchdogPIDEnv = "WATCHDOG_PID"
// readyState and watchdogState are the two sd_notify states archied sends.
readyState = "READY=1"
watchdogState = "WATCHDOG=1"
// watchdogHeartbeatDivisor is sd_notify(3)'s recommendation: beat at half
// of WatchdogSec, so one missed beat is tolerated and two are not.
watchdogHeartbeatDivisor = 2
)
// notifier writes sd_notify states to the socket named in the environment. A
// notifier with no address -- the normal case away from systemd -- sends
// nothing and says nothing.
type notifier struct {
addr string
log *slog.Logger
}
// newNotifier resolves the notify socket. The address is read from the
// environment systemd sets for the process, so systemd replaces the previous
// unit's socket with the new one across a restart.
func newNotifier(getenv func(string) string, log *slog.Logger) notifier {
return notifier{addr: getenv(notifySocketEnv), log: log}
}
// send delivers one state line. A failure is logged, never returned: a
// notification is an observation about the daemon, and no observation is worth
// refusing to serve over.
func (n notifier) send(state string) {
if n.addr == "" {
return
}
if err := sendNotify(n.addr, state); err != nil {
n.log.Warn("systemd notify failed", "state", state, "socket", n.addr, "err", err)
}
}
// sendNotify writes one state datagram to a unixgram socket. sd_notify(3) is
// one datagram per state, so each send dials afresh: a manager restart recreates
// its socket, and a connection cached across one would fail every send after it.
// A leading '@' names the Linux abstract namespace, which user managers use;
// net.UnixAddr takes that syntax verbatim.
func sendNotify(addr, state string) error {
conn, err := net.DialUnix("unixgram", nil, &net.UnixAddr{Name: addr, Net: "unixgram"})
if err != nil {
return err
}
defer func() { _ = conn.Close() }()
if _, err := conn.Write([]byte(state)); err != nil {
return fmt.Errorf("write %q: %w", state, err)
}
return nil
}
// announceReady tells systemd the daemon has finished starting. It is called at
// the moment a process declares itself serving: the daemon's run loop (next to
// healthSurface.markServing), and the serve steps of archie-gateway and
@@ -101,42 +34,35 @@ func sendNotify(addr, state string) error {
// own and would otherwise hang a Type=notify unit until TimeoutStartSec while
// perfectly healthy.
func (b *boot) announceReady() {
notifyReady(b.log)
}
// notifyReady is announceReady without the boot: the Gateway's serving tail
// runs on a boot it owns, but a free helper keeps the announcement one call
// rather than a second notion of "started" on each surface.
func notifyReady(log *slog.Logger) {
newNotifier(os.Getenv, log).send(readyState)
sdnotify.Ready(b.log)
}
// startWatchdog arms the heartbeat sampler for the daemon's run loop. It does
// nothing unless a manager named a notify socket and asked for a watchdog
// (WATCHDOG_USEC), so every deployment without systemd is unaffected.
func (b *boot) startWatchdog(ctx context.Context) {
n := newNotifier(os.Getenv, b.log)
if n.addr == "" {
n := sdnotify.New(os.Getenv, b.log)
if !n.Enabled() {
return
}
interval, ok := watchdogHeartbeat(os.Getenv, os.Getpid(), b.log)
interval, ok := sdnotify.Heartbeat(os.Getenv, os.Getpid(), b.log)
if !ok {
return
}
sampler := loopWatchdog{
interval: interval,
cadence: b.loopCadence,
progress: b.d.LastPollAt,
beat: func() { n.send(watchdogState) },
log: b.log,
sampler := sdnotify.Watchdog{
Interval: interval,
Cadence: b.loopCadence,
Progress: b.d.LastPollAt,
Beat: func() { n.Send(sdnotify.WatchdogState) },
Log: b.log,
}
b.log.Info("systemd watchdog armed",
"heartbeat", interval.String(),
"loop_cadence", b.loopCadence().String())
go func() {
if err := sampler.run(ctx); err != nil && !errors.Is(err, context.Canceled) {
if err := sampler.Run(ctx); err != nil && !errors.Is(err, context.Canceled) {
b.log.Error("systemd watchdog stopped", "err", err)
}
}()
@@ -161,86 +87,3 @@ func (b *boot) loopCadence() time.Duration {
}
return cadence
}
// watchdogHeartbeat reads systemd's watchdog contract and returns the heartbeat
// cadence, which is half of WatchdogSec. ok is false when systemd asked for no
// watchdog, and also when it asked for one from a different process:
// WATCHDOG_PID names the process whose beats count, so a unit watching another
// process must not have this one beating on its behalf.
func watchdogHeartbeat(getenv func(string) string, pid int, log *slog.Logger) (time.Duration, bool) {
raw := getenv(watchdogUsecEnv)
if raw == "" {
return 0, false
}
if rawPID := getenv(watchdogPIDEnv); rawPID != "" {
wantPID, err := strconv.Atoi(rawPID)
if err != nil || wantPID != pid {
log.Warn("systemd watchdog disabled: WATCHDOG_PID is not this process",
"watchdog_pid", rawPID, "pid", pid, "err", err)
return 0, false
}
}
watchdog, err := time.ParseDuration(raw + "us")
if err != nil || watchdog <= 0 {
log.Warn("systemd watchdog disabled: WATCHDOG_USEC unreadable", "value", raw, "err", err)
return 0, false
}
return watchdog / watchdogHeartbeatDivisor, true
}
// loopWatchdog samples the run loop's progress marker and emits the watchdog
// heartbeat only while that marker is fresh. Sampling is periodic; the beat is
// not, because it is licensed by the marker rather than by the clock.
type loopWatchdog struct {
// interval is the sampling cadence: half of systemd's WatchdogSec.
interval time.Duration
// cadence reports how long the loop may go between poll passes.
cadence func() time.Duration
// progress reports the start of the loop's most recent poll pass, or the
// zero time when no pass has begun yet.
progress func() time.Time
// beat emits one WATCHDOG=1.
beat func()
log *slog.Logger
}
// run samples until ctx ends. It returns ctx.Err() on shutdown, which is the
// only way out: this sampler never gives up on its own, because a sampler that
// stopped would leave systemd watching a process nothing reports for.
func (w loopWatchdog) run(ctx context.Context) error {
armedAt := time.Now()
stalled := false
ticker := time.NewTicker(w.interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return ctx.Err()
case <-ticker.C:
}
last := w.progress()
if last.IsZero() {
// No pass has begun at all. Measure staleness from arming, so a
// loop that never starts polling is caught like one that stopped.
last = armedAt
}
cadence := w.cadence()
switch age := time.Since(last); {
case age > cadence:
if !stalled {
w.log.Warn("systemd watchdog: run loop has not begun a poll pass within its interval; withholding the heartbeat until it does",
"stale_for", age.String(), "loop_cadence", cadence.String())
stalled = true
}
default:
if stalled {
w.log.Info("systemd watchdog: run loop resumed; heartbeats resumed",
"last_pass_age", age.String())
stalled = false
}
w.beat()
}
}
}
+24 -96
View File
@@ -18,8 +18,16 @@ import (
"github.com/samcharles93/archie-core/internal/daemon"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
"github.com/samcharles93/archie-core/internal/sdnotify"
)
// The protocol-level properties of the notify client -- the '@' address form,
// the disabled and unusable socket contract, and the half-of-WatchdogSec
// heartbeat -- are pinned in internal/sdnotify, where the client now lives.
// These tests pin what is the daemon's: that its three serving entry points
// announce, that the sampler samples daemon.LastPollAt, and that the whole
// path stays silent and harmless without a NOTIFY_SOCKET.
// notifyRecorder captures every record at every level. The other recording
// handler in this package keeps warnings only; these tests need "this path
// logged nothing at all" as positive evidence that a disabled notifier stayed
@@ -49,6 +57,7 @@ func (h *notifyRecorder) all() []slog.Record {
return append([]slog.Record(nil), h.records...)
}
// at returns the captured records at one level.
func (h *notifyRecorder) at(level slog.Level) []slog.Record {
h.mu.Lock()
defer h.mu.Unlock()
@@ -83,7 +92,7 @@ func listenNotify(t *testing.T, addr string) *notifyListener {
t.Fatalf("listen for notify datagrams at %q: %v", addr, err)
}
t.Cleanup(func() { _ = conn.Close() })
t.Setenv(notifySocketEnv, addr)
t.Setenv(sdnotify.NotifySocketEnv, addr)
return &notifyListener{conn: conn}
}
@@ -174,93 +183,12 @@ func pollPasses(ctx context.Context, d *daemon.Daemon, on *atomic.Bool, every ti
}
}
// TestNotifyReachesAbstractSocket pins the '@' address form. systemd is not
// restricted to filesystem paths, and a client that stripped the prefix would
// connect to a file that does not exist instead of the abstract namespace.
func TestNotifyReachesAbstractSocket(t *testing.T) {
listener := listenNotify(t, fmt.Sprintf("@archie-notify-test-%d", os.Getpid()))
(&boot{log: slog.New(slog.DiscardHandler)}).announceReady()
if states := listener.states(t, 300*time.Millisecond); !slices.Contains(states, readyState) {
t.Errorf("states received = %v, want %q among them", states, readyState)
}
}
// TestNotifierDisabledIsSilentAndUnusableSocketWarns pins the two ends of the
// delivery contract: no socket means nothing is attempted and nothing is said,
// while a socket that cannot be written to is reported once and then ignored.
// Neither may ever be fatal.
func TestNotifierDisabledIsSilentAndUnusableSocketWarns(t *testing.T) {
rec := &notifyRecorder{}
log := slog.New(rec)
newNotifier(func(string) string { return "" }, log).send(readyState)
if got := rec.all(); len(got) != 0 {
t.Errorf("a notifier with no socket logged %d records, want none: %v", len(got), got)
}
missing := filepath.Join(t.TempDir(), "absent", "n.sock")
newNotifier(func(string) string { return missing }, log).send(readyState)
warns := rec.at(slog.LevelWarn)
if len(warns) != 1 {
t.Fatalf("sends to an unusable socket logged %d warnings, want exactly 1", len(warns))
}
if errs := rec.at(slog.LevelError); len(errs) != 0 {
t.Errorf("sends to an unusable socket logged %d errors, want none", len(errs))
}
}
// TestWatchdogHeartbeatInterval pins the interval convention: systemd passes
// WatchdogSec as WATCHDOG_USEC and sd_notify(3) heartbeats at half of it, and
// WATCHDOG_PID names the process whose beats count.
func TestWatchdogHeartbeatInterval(t *testing.T) {
const self = 42
tests := []struct {
name string
usec string
pidEnv string
want time.Duration
wantOK bool
}{
{name: "no watchdog requested", wantOK: false},
{name: "half of a 30s watchdog", usec: "30000000", want: 15 * time.Second, wantOK: true},
{name: "sub-second watchdog", usec: "20000", want: 10 * time.Millisecond, wantOK: true},
{name: "unparseable", usec: "soon", wantOK: false},
{name: "zero", usec: "0", wantOK: false},
{name: "negative", usec: "-1", wantOK: false},
{name: "watchdog pid is this process", usec: "20000", pidEnv: "42", want: 10 * time.Millisecond, wantOK: true},
{name: "watchdog pid is another process", usec: "20000", pidEnv: "7", wantOK: false},
{name: "watchdog pid is unreadable", usec: "20000", pidEnv: "seven", wantOK: false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
getenv := func(key string) string {
switch key {
case watchdogUsecEnv:
return tt.usec
case watchdogPIDEnv:
return tt.pidEnv
default:
return ""
}
}
got, ok := watchdogHeartbeat(getenv, self, slog.New(slog.DiscardHandler))
if ok != tt.wantOK || got != tt.want {
t.Errorf("watchdogHeartbeat(usec=%q, pid=%q) = %v, %v; want %v, %v",
tt.usec, tt.pidEnv, got, ok, tt.want, tt.wantOK)
}
})
}
}
// TestNotifyReadyAndWatchdogHeartbeat is the run-loop path end to end: a real
// NOTIFY_SOCKET, the daemon's own boot path announcing READY, and the run
// loop's own progress marker producing WATCHDOG heartbeats.
func TestNotifyReadyAndWatchdogHeartbeat(t *testing.T) {
listener := newNotifyListener(t)
t.Setenv(watchdogUsecEnv, "20000") // 20ms watchdog: heartbeat every 10ms
t.Setenv(sdnotify.WatchdogUsecEnv, "20000") // 20ms watchdog: heartbeat every 10ms
b, d := newNotifyTestBoot(t, 50*time.Millisecond)
ctx, cancel := context.WithCancel(t.Context())
@@ -274,11 +202,11 @@ func TestNotifyReadyAndWatchdogHeartbeat(t *testing.T) {
b.startWatchdog(ctx)
states := listener.states(t, 300*time.Millisecond)
if !slices.Contains(states, readyState) {
t.Errorf("states received = %v, want %q among them", states, readyState)
if !slices.Contains(states, sdnotify.ReadyState) {
t.Errorf("states received = %v, want %q among them", states, sdnotify.ReadyState)
}
if countState(states, watchdogState) == 0 {
t.Errorf("states received = %v, want at least one %q among them", states, watchdogState)
if countState(states, sdnotify.WatchdogState) == 0 {
t.Errorf("states received = %v, want at least one %q among them", states, sdnotify.WatchdogState)
}
}
@@ -288,7 +216,7 @@ func TestNotifyReadyAndWatchdogHeartbeat(t *testing.T) {
// kept alive by an independent ticker.
func TestWatchdogWithholdsHeartbeatWhenRunLoopStalls(t *testing.T) {
listener := newNotifyListener(t)
t.Setenv(watchdogUsecEnv, "20000") // 20ms watchdog: heartbeat every 10ms
t.Setenv(sdnotify.WatchdogUsecEnv, "20000") // 20ms watchdog: heartbeat every 10ms
const cadence = 50 * time.Millisecond
b, d := newNotifyTestBoot(t, cadence)
@@ -300,7 +228,7 @@ func TestWatchdogWithholdsHeartbeatWhenRunLoopStalls(t *testing.T) {
go pollPasses(ctx, d, &polling, 5*time.Millisecond)
b.startWatchdog(ctx)
if beats := countState(listener.states(t, 200*time.Millisecond), watchdogState); beats == 0 {
if beats := countState(listener.states(t, 200*time.Millisecond), sdnotify.WatchdogState); beats == 0 {
t.Fatal("no WATCHDOG=1 within 200ms while the run loop was polling")
}
@@ -323,12 +251,12 @@ func TestWatchdogWithholdsHeartbeatWhenRunLoopStalls(t *testing.T) {
// terminal, and a systemd unit with no WatchdogSec all take this path, and none
// of them may see a datagram, a warning, or a failed start.
func TestNotifyUnsetIsNoOp(t *testing.T) {
t.Setenv(watchdogUsecEnv, "20000")
t.Setenv(sdnotify.WatchdogUsecEnv, "20000")
// t.Setenv cannot unset a variable: register the restoration first, then
// remove it for real so "unset" means unset.
t.Setenv(notifySocketEnv, "")
if err := os.Unsetenv(notifySocketEnv); err != nil {
t.Fatalf("unset %s: %v", notifySocketEnv, err)
t.Setenv(sdnotify.NotifySocketEnv, "")
if err := os.Unsetenv(sdnotify.NotifySocketEnv); err != nil {
t.Fatalf("unset %s: %v", sdnotify.NotifySocketEnv, err)
}
rec := &notifyRecorder{}
@@ -349,8 +277,8 @@ func TestNotifyUnsetIsNoOp(t *testing.T) {
// would be a regression on every deployment that has no systemd at all.
func TestNotifySocketFailureIsNotFatal(t *testing.T) {
missing := filepath.Join(t.TempDir(), "absent", "n.sock")
t.Setenv(notifySocketEnv, missing)
t.Setenv(watchdogUsecEnv, "20000")
t.Setenv(sdnotify.NotifySocketEnv, missing)
t.Setenv(sdnotify.WatchdogUsecEnv, "20000")
rec := &notifyRecorder{}
b, d := newNotifyTestBoot(t, 50*time.Millisecond)
@@ -405,7 +333,7 @@ func TestStateStoreBootAnnouncesReady(t *testing.T) {
errCh := make(chan error, 1)
go func() { errCh <- RunStateStore(ctx, StateStoreOptions{Config: path, Listen: "127.0.0.1:0"}) }()
if !listener.waitForState(t, 15*time.Second, readyState) {
if !listener.waitForState(t, 15*time.Second, sdnotify.ReadyState) {
select {
case bootErr := <-errCh:
t.Fatalf("RunStateStore exited before announcing ready: %v", bootErr)
+31 -1
View File
@@ -17,6 +17,7 @@ import (
"net/http"
"time"
"github.com/jackc/pgx/v5/pgxpool"
"google.golang.org/grpc"
"github.com/samcharles93/archie-core/internal/app/controlplane"
@@ -289,10 +290,20 @@ func (b *boot) openStateStore(ctx context.Context) error {
func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps {
deps := staterpc.Deps{Tasks: b.st, Log: b.log, Grants: grants}
if b.pg != nil {
deps.Packages = storepkg.Service{
packages := storepkg.Service{
Registry: registry.LocalRegistry{},
Store: postgres.NewInstalledPackages(b.pg),
}
// A projection failure degrades the org resources a package would have
// contributed to, the way a group above degrades: the State Store boots
// and reports, rather than refusing to serve the task tables.
projections, err := newPackageProjections(b.pg)
if err != nil {
b.log.Error("build package projections", "err", err)
} else {
packages.Projections = projections
}
deps.Packages = packages
}
if identities, ok := b.st.(identity.Repository); ok {
deps.Identities = identities
@@ -494,3 +505,22 @@ func stateStoreServerOpts(listen, token string, grants *staterpc.TaskGrants) (op
grpc.ChainStreamInterceptor(grants.StreamInterceptor(token)),
}, false, nil
}
// newPackageProjections builds the family projectors an installed package's
// contributions apply through: workflows become org workflow definitions, the
// one resource kind the runtime reads live today. The step vocabulary
// (stepVocabulary) is the same one this process's control plane validates
// dashboard edits with, so a definition the projector admits is compilable
// where it dispatches (openStateStoreControlPlane for the pairing).
func newPackageProjections(pool *pgxpool.Pool) (map[string]storepkg.FamilyProjector, error) {
steps, err := stepVocabulary()
if err != nil {
return nil, fmt.Errorf("register workflow step vocabulary: %w", err)
}
workflows, err := controlplane.NewWorkflowPackageProjector(
postgres.NewResources(pool), postgres.NewPackageContributions(pool), steps)
if err != nil {
return nil, fmt.Errorf("build workflow package projector: %w", err)
}
return map[string]storepkg.FamilyProjector{storepkg.FamilyWorkflows: workflows}, nil
}
+5 -4
View File
@@ -30,6 +30,7 @@ import (
pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
"github.com/samcharles93/archie-core/internal/infrastructure/controlplanerpc"
)
// The audit identity every offline rollback records. A rollback is one more
@@ -135,7 +136,7 @@ func replayRevision(ctx context.Context, resources controlplane.ResourceStore, o
if !server.Owns(options.Kind) {
return "", fmt.Errorf("unknown resource kind %q", options.Kind)
}
current, err := resources.Resource(ctx, options.Kind)
current, err := resources.Resource(ctx, storecontract.DefaultOrgID, options.Kind)
if errors.Is(err, storecontract.ErrResourceNotFound) {
return "", fmt.Errorf("%s has no stored value to roll back", options.Kind)
}
@@ -146,7 +147,7 @@ func replayRevision(ctx context.Context, resources controlplane.ResourceStore, o
if err != nil {
return "", err
}
replaced, err := server.Command(ctx, &pb.CommandRequest{
replaced, err := server.Command(ctx, controlplanerpc.CommandRequest(ctx, &pb.CommandRequest{
Kind: options.Kind,
Command: "replace",
ValueJson: revision.Value,
@@ -154,7 +155,7 @@ func replayRevision(ctx context.Context, resources controlplane.ResourceStore, o
Actor: OfflineRollbackActor,
Source: OfflineRollbackSource,
RequestId: fmt.Sprintf("recovery-rollback-%s-%d", options.Kind, time.Now().UTC().UnixNano()),
})
}))
if err != nil {
return "", fmt.Errorf("replay %s at revision %d: %w", options.Kind, revision.Version, err)
}
@@ -165,7 +166,7 @@ func replayRevision(ctx context.Context, resources controlplane.ResourceStore, o
// revisionToReplay picks the value to put back: the revision the operator
// named, or the newest one older than the value the resource carries now.
func revisionToReplay(ctx context.Context, st controlplane.ResourceStore, kind string, current, requested int64) (storecontract.Resource, error) {
history, err := st.ResourceHistory(ctx, kind, 0)
history, err := st.ResourceHistory(ctx, storecontract.DefaultOrgID, kind, 0)
if err != nil {
return storecontract.Resource{}, fmt.Errorf("read %s history: %w", kind, err)
}
@@ -54,11 +54,12 @@ func putResource(t *testing.T, pool *pgxpool.Pool, kind, value, label string) {
t.Helper()
resources := postgres.NewResources(pool)
expected := int64(0)
if current, err := resources.Resource(t.Context(), kind); err == nil {
if current, err := resources.Resource(t.Context(), storecontract.DefaultOrgID, kind); err == nil {
expected = current.Version
}
if _, err := resources.PutResource(t.Context(), storecontract.ResourceWrite{
Kind: kind, Value: []byte(value), Actor: label, Source: "test",
OrgID: storecontract.DefaultOrgID,
Kind: kind, Value: []byte(value), Actor: label, Source: "test",
RequestID: fmt.Sprintf("%s-%d", label, expected+1), ExpectedVersion: expected,
}); err != nil {
t.Fatalf("put %s: %v", kind, err)
@@ -125,7 +126,7 @@ func TestPostgresRecoveryBackupAndRestore(t *testing.T) {
if !strings.Contains(summary, "after the snapshot") {
t.Errorf("restore must say writes after the snapshot are lost; summary = %q", summary)
}
current, err := postgres.NewResources(pool).Resource(t.Context(), controlplane.ModelRoleAssignmentsKind)
current, err := postgres.NewResources(pool).Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
if err != nil {
t.Fatal(err)
}
@@ -188,7 +189,7 @@ func TestPostgresRecoveryRollback(t *testing.T) {
if _, err := RunStateStoreRecovery(t.Context(), options); err != nil {
t.Fatalf("rollback: %v", err)
}
current, err := postgres.NewResources(pool).Resource(t.Context(), kind)
current, err := postgres.NewResources(pool).Resource(t.Context(), storecontract.DefaultOrgID, kind)
if err != nil {
t.Fatal(err)
}
@@ -15,6 +15,7 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
"github.com/samcharles93/archie-core/internal/secret"
)
// startupGrace is how long RunStateStore is given to either refuse the config
@@ -46,7 +47,7 @@ func TestExternalServicesDoNotRequireBridgeNetwork(t *testing.T) {
cfg.NATS.Mode = config.NATSModeExternal
cfg.Containers.Network = "host"
cfg.Services = config.Services{config.ServiceNameState: {Target: "state.example.test:9090"}}
pool, _, cleanup := startContainers(t.Context(), cfg, slog.New(slog.DiscardHandler))
pool, _, cleanup := startContainers(t.Context(), config.NewHolder(cfg), secret.NewRegistry(), slog.New(slog.DiscardHandler))
defer cleanup()
if pool == nil {
t.Fatal("external services on host networking must construct a worker pool")
+1 -1
View File
@@ -175,7 +175,7 @@ func TestStateStoreDataSurvivesRestart(t *testing.T) {
if err := first.openStateStore(t.Context()); err != nil {
t.Fatalf("first openStateStore: %v", err)
}
task, err := first.st.EnqueueChatTask(t.Context(), "acme", "widget", "restart check", "body", "implement", "")
task, err := first.st.EnqueueChatTask(t.Context(), "acme", "widget", "restart check", "body", "implement", "", nil)
if err != nil {
t.Fatalf("EnqueueChatTask: %v", err)
}
@@ -24,9 +24,9 @@ import (
type testTaskActor struct{ b *boot }
func (a testTaskActor) ApplyChatTaskAction(
ctx context.Context, identity *string, actor taskactions.Actor, taskID int64, action taskstate.Action,
ctx context.Context, identity *string, actor taskactions.Actor, taskID int64, action taskstate.Action, res taskactions.ActionPayload,
) (gateway.TaskActionResult, error) {
if err := a.b.taskActions().Apply(ctx, identity, actor, taskID, action); err != nil {
if err := a.b.taskActions().Apply(ctx, identity, actor, taskID, action, res); err != nil {
return gateway.TaskActionResult{}, err
}
return gateway.TaskActionResult{
@@ -52,7 +52,7 @@ func TestChatTaskActorAdapterCrossIdentityRefused(t *testing.T) {
st := pgstore.Open(t)
t.Cleanup(func() { _ = st.Close() })
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "parked job", "", "", "identity-owner")
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "parked job", "", "", "identity-owner", nil)
if err != nil {
t.Fatal(err)
}
@@ -84,7 +84,7 @@ func TestChatTaskActorAdapterCrossIdentityRefused(t *testing.T) {
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
_, err := adapter.ApplyChatTaskAction(ctx, &tc.actorIdentity, taskactions.Actor{}, task.ID, tc.action)
_, err := adapter.ApplyChatTaskAction(ctx, &tc.actorIdentity, taskactions.Actor{}, task.ID, tc.action, taskactions.ActionPayload{})
if err == nil {
t.Fatalf("ApplyChatTaskAction() allowed cross-identity action %s by %q on task owned by %q",
tc.action, tc.actorIdentity, task.Identity)
@@ -146,13 +146,13 @@ func TestChatTaskActorAdapterRefusesDisallowedStateAction(t *testing.T) {
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "test task", "", "", "archie")
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "test task", "", "", "archie", nil)
if err != nil {
t.Fatal(err)
}
taskstatetest.Seed(ctx, t, st, task.ID, workflow.StatusQueued, tc.initialStatus, "setup")
_, err = adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, task.ID, tc.attemptAction)
_, err = adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, task.ID, tc.attemptAction, taskactions.ActionPayload{})
if err == nil {
t.Fatalf("expected error attempting %s on %s task, got nil", tc.attemptAction, tc.initialStatus)
}
@@ -182,7 +182,7 @@ func TestChatTaskActorAdapterTaskNotFound(t *testing.T) {
adapter := newChatTaskActorForTest(t, st, config.Config{})
_, err := adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, 999999, taskstate.ActionAbandon)
_, err := adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, 999999, taskstate.ActionAbandon, taskactions.ActionPayload{})
if err == nil {
t.Fatal("expected error for non-existent task, got nil")
}
@@ -251,13 +251,13 @@ func TestChatTaskActorAdapterAppliesActionsToStore(t *testing.T) {
adapter := newChatTaskActorForTest(t, st, config.Config{MaxRetries: 3})
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "actionable task", "", "", "archie")
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "actionable task", "", "", "archie", nil)
if err != nil {
t.Fatal(err)
}
taskstatetest.Seed(ctx, t, st, task.ID, workflow.StatusQueued, tc.initialStatus, "setup")
result, err := adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, task.ID, tc.action)
result, err := adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, task.ID, tc.action, taskactions.ActionPayload{})
if err != nil {
t.Fatalf("ApplyChatTaskAction(%s) error = %v", tc.action, err)
}
@@ -292,7 +292,7 @@ func TestChatTaskActorAdapterNilContract(t *testing.T) {
ctx := context.Background()
adapter := chatTaskActorAdapter{contract: nil}
_, err := adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, 1, taskstate.ActionAbandon)
_, err := adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, 1, taskstate.ActionAbandon, taskactions.ActionPayload{})
if err == nil {
t.Fatal("expected error for nil contract, got nil")
}
+11 -3
View File
@@ -11,9 +11,12 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
taskactionstore "github.com/samcharles93/archie-core/internal/infrastructure/taskactions"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/taskstate/taskstatetest"
"github.com/samcharles93/archie-core/internal/webui"
)
@@ -48,7 +51,7 @@ func TestDashboardAndChatAgreeOnTerminalStates(t *testing.T) {
st := pgstore.Open(t)
t.Cleanup(func() { _ = st.Close() })
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "decide on me", "", "", "reviewer")
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "decide on me", "", "", "reviewer", nil)
if err != nil {
t.Fatal(err)
}
@@ -80,9 +83,14 @@ func runChatAction(t *testing.T, ctx context.Context, st storecontract.TaskStore
if !ok {
t.Fatal("the task store cannot cancel executions")
}
// Chat's /approve reaches the daemon's one task-action service
// (docs/prds/pr-review-operator-response.md, Decision 1).
actions := taskactionstore.NewService(taskactionstore.Store{TaskStore: st}, nil, nil, nil, nil, nil, nil, nil)
controller := gateway.NewStoreTaskController(chatTaskControllerAdapter{
taskByID: st.TaskByID,
requeue: st.Requeue,
taskByID: st.TaskByID,
approve: func(ctx context.Context, scope *string, actor taskactions.Actor, taskID int64, res taskactions.ActionPayload) error {
return actions.Apply(ctx, scope, actor, taskID, taskstate.ActionApprove, res)
},
cancelExecution: canceller.CancelExecution,
})
var err error
@@ -0,0 +1,337 @@
package archied
import (
"context"
"errors"
"strings"
"sync"
"testing"
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/plugin"
"github.com/samcharles93/archie-core/internal/secret"
"github.com/samcharles93/archie-core/internal/tools"
toolprovider "github.com/samcharles93/archie-core/internal/tools/provider"
"github.com/samcharles93/archie-core/internal/tools/webfetch"
)
// fakeMCPEngine stands in for a configured MCP server so the live reconciliation
// can be driven without spawning a process. It records each lifecycle call on
// the shared recorder, keyed by configured server name.
type fakeMCPEngine struct {
name string
tools []tools.ToolEntry
rec *mcpEngineRecorder
startErr error
}
func (e *fakeMCPEngine) Manifest() plugin.Manifest {
return plugin.Manifest{
ID: "mcp." + e.name,
Name: e.name,
Version: "1.0.0",
APIVersion: plugin.HostAPIVersion,
Capabilities: []plugin.CapabilityKind{"tools"},
}
}
func (e *fakeMCPEngine) Start(context.Context) error {
e.rec.recordStart(e.name)
return e.startErr
}
func (e *fakeMCPEngine) Stop(context.Context) error {
e.rec.recordStop(e.name)
return nil
}
func (e *fakeMCPEngine) Discover(context.Context) ([]tools.ToolEntry, error) {
return append([]tools.ToolEntry(nil), e.tools...), nil
}
// mcpEngineRecorder records what the live reconciliation did to each server and
// hands the test a factory boot.mcpProvider can use.
type mcpEngineRecorder struct {
mu sync.Mutex
builds map[string]int
starts map[string]int
stops map[string]int
failNext map[string]error
seen map[string]config.MCPServer
}
func newMCPEngineRecorder() *mcpEngineRecorder {
return &mcpEngineRecorder{
builds: map[string]int{},
starts: map[string]int{},
stops: map[string]int{},
failNext: map[string]error{},
seen: map[string]config.MCPServer{},
}
}
func (r *mcpEngineRecorder) factory() func(config.MCPServer) (toolprovider.Engine, error) {
return func(srv config.MCPServer) (toolprovider.Engine, error) {
name := strings.TrimSpace(srv.Name)
r.mu.Lock()
r.builds[name]++
r.seen[name] = srv
err := r.failNext[name]
delete(r.failNext, name)
r.mu.Unlock()
return &fakeMCPEngine{
name: name,
rec: r,
startErr: err,
tools: []tools.ToolEntry{{
Name: "mcp." + name + ".tool",
Toolset: "mcp",
Handler: func(context.Context, map[string]any) (any, error) { return "ok", nil },
}},
}, nil
}
}
func (r *mcpEngineRecorder) recordStart(name string) {
r.mu.Lock()
defer r.mu.Unlock()
r.starts[name]++
}
func (r *mcpEngineRecorder) recordStop(name string) {
r.mu.Lock()
defer r.mu.Unlock()
r.stops[name]++
}
func (r *mcpEngineRecorder) failOnNextStart(name string, err error) {
r.mu.Lock()
defer r.mu.Unlock()
r.failNext[name] = err
}
func (r *mcpEngineRecorder) count(counts map[string]int, name string) int {
r.mu.Lock()
defer r.mu.Unlock()
return counts[name]
}
// toolSettingsDocument renders a stored tool-settings document carrying the
// given MCP servers and an enabled web_fetch.
func toolSettingsDocument(servers ...map[string]any) map[string]any {
return map[string]any{
"mcp_servers": servers,
"policy": map[string]any{},
"web_fetch": map[string]any{},
"minimax": map[string]any{},
}
}
func mcpServerDoc(name string, parallel bool) map[string]any {
return map[string]any{
"name": name,
"transport": "stdio",
"command": "run-server",
"parallel_tool_calls": parallel,
}
}
// newMCPReconcileBoot builds a boot whose provider registry is running, so the
// live reconciliation acts on a real registry and a real tool index.
func newMCPReconcileBoot(t *testing.T, base config.Config, stub *resourceWatchStub) (*boot, *applyStatusRecorder, *mcpEngineRecorder) {
t.Helper()
b, status := newLiveApplyBoot(t, base)
b.controlPlane = controlplane.NewRPCClient(stub)
b.secrets = secret.NewRegistry()
b.toolReg = tools.NewRegistry()
b.providerRegistry = toolprovider.NewRegistry(b.toolReg)
if err := b.providerRegistry.Start(t.Context()); err != nil {
t.Fatalf("start provider registry: %v", err)
}
b.mcpApplied = map[string]appliedMCPServer{}
rec := newMCPEngineRecorder()
b.mcpProvider = rec.factory()
return b, status, rec
}
// applyToolSettings stores the document and runs the live apply the watch
// would run, the seam the daemon meets a stored tool-settings change through.
func applyToolSettings(t *testing.T, b *boot, stub *resourceWatchStub, version int64, document map[string]any) {
t.Helper()
if stub.values == nil {
stub.values = map[string]any{}
}
stub.values[controlplane.ToolSettingsKind] = document
if stub.storedVersion == nil {
stub.storedVersion = map[string]int64{}
}
stub.storedVersion[controlplane.ToolSettingsKind] = version
b.applyRuntimeResourceUpdate(t.Context(), controlplane.ToolSettingsKind, controlplane.AppliedResource{Version: version})
}
func TestLiveToolSettingsConnectsAnAddedServer(t *testing.T) {
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub)
applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false)))
if got := rec.count(rec.starts, "alpha"); got != 1 {
t.Errorf("alpha start count = %d, want 1", got)
}
if _, ok := b.toolReg.Get("mcp.alpha.tool"); !ok {
t.Error("the added server's tool was not indexed")
}
if !b.providerRegistry.Has("mcp.alpha") {
t.Error("the added server is not registered")
}
servers := b.cfgHolder.Get().Tools.MCPServers
if len(servers) != 1 || servers[0].Name != "alpha" {
t.Errorf("running config servers = %+v, want the added alpha", servers)
}
}
func TestLiveToolSettingsLeavesAnUnchangedServerUntouched(t *testing.T) {
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub)
applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false)))
applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("alpha", false), mcpServerDoc("beta", false)))
if got := rec.count(rec.builds, "alpha"); got != 1 {
t.Errorf("alpha was rebuilt on an unchanged update: builds = %d, want 1", got)
}
if got := rec.count(rec.starts, "alpha"); got != 1 {
t.Errorf("alpha was reconnected on an unchanged update: starts = %d, want 1", got)
}
if got := rec.count(rec.stops, "alpha"); got != 0 {
t.Errorf("alpha was stopped on an unchanged update: stops = %d, want 0", got)
}
if got := rec.count(rec.starts, "beta"); got != 1 {
t.Errorf("beta start count = %d, want 1", got)
}
}
func TestLiveToolSettingsReconnectsAChangedServer(t *testing.T) {
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub)
applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false)))
applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("alpha", true)))
if got := rec.count(rec.stops, "alpha"); got != 1 {
t.Errorf("the changed server was not disconnected: stops = %d, want 1", got)
}
if got := rec.count(rec.starts, "alpha"); got != 2 {
t.Errorf("the changed server was not reconnected: starts = %d, want 2", got)
}
if _, ok := b.toolReg.Get("mcp.alpha.tool"); !ok {
t.Error("the reconnected server's tool left the index")
}
}
func TestLiveToolSettingsDisconnectsARemovedServer(t *testing.T) {
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub)
applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false), mcpServerDoc("beta", false)))
applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("beta", false)))
if got := rec.count(rec.stops, "alpha"); got != 1 {
t.Errorf("the removed server was not disconnected: stops = %d, want 1", got)
}
if b.providerRegistry.Has("mcp.alpha") {
t.Error("the removed server stayed registered")
}
if _, ok := b.toolReg.Get("mcp.alpha.tool"); ok {
t.Error("the removed server's tool stayed indexed")
}
if got := rec.count(rec.stops, "beta"); got != 0 {
t.Errorf("the surviving server was disturbed: stops = %d, want 0", got)
}
}
// TestLiveToolSettingsKeepsTheRunningServerWhenAChangeCannotStart is the path
// where the change must NOT apply: a changed server whose replacement fails to
// start is rolled back to the one that was running, and the refusal reaches
// apply status rather than the kind silently reporting success.
func TestLiveToolSettingsKeepsTheRunningServerWhenAChangeCannotStart(t *testing.T) {
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, status, rec := newMCPReconcileBoot(t, fileConfig(), stub)
applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false)))
rec.failOnNextStart("alpha", errors.New("handshake refused"))
applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("alpha", true)))
// Two stops: the running server is disconnected for the replacement, and
// the replacement's own half-start is cleaned up when its handshake fails.
if got := rec.count(rec.stops, "alpha"); got != 2 {
t.Errorf("stops = %d, want 2 (the replaced server and the failed replacement's cleanup)", got)
}
if got := rec.count(rec.starts, "alpha"); got != 3 {
t.Errorf("starts = %d, want 3 (initial, refused replacement, rollback restart)", got)
}
if _, ok := b.toolReg.Get("mcp.alpha.tool"); !ok {
t.Error("the refused change left the running server's tool out of the index")
}
if !b.providerRegistry.Has("mcp.alpha") {
t.Error("the refused change left the server unregistered")
}
last, ok := status.last(controlplane.ToolSettingsKind)
if !ok {
t.Fatal("the refused change reported no apply status")
}
if !strings.Contains(last.Error, "alpha") {
t.Errorf("apply status error = %q, want it to name the refused server", last.Error)
}
}
// TestLiveToolSettingsRebuildsTheWebFetchEntry: web_fetch captured its config
// at construction, so a live change rebuilds the entry rather than leaving the
// boot value in the model's tool list.
func TestLiveToolSettingsRebuildsTheWebFetchEntry(t *testing.T) {
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, _, _ := newMCPReconcileBoot(t, fileConfig(), stub)
disabled := toolSettingsDocument()
disabled["web_fetch"] = map[string]any{"enabled": false}
applyToolSettings(t, b, stub, 11, disabled)
if _, ok := b.toolReg.Get(webfetch.ToolName); ok {
t.Error("web_fetch stayed registered after the stored document disabled it")
}
applyToolSettings(t, b, stub, 12, toolSettingsDocument())
if _, ok := b.toolReg.Get(webfetch.ToolName); !ok {
t.Error("web_fetch was not registered after the stored document re-enabled it")
}
}
// TestLiveToolSettingsKeepsAnUnprojectedMCPHeader: the stored document cannot
// carry secret-bearing headers, so the layering restores them from the running
// base (controlplane.runtimeToolConfigFrom). The reconciliation must build the
// reconnected engine from that layered server, not from the document alone, or
// an authentication header disappears on the first live edit.
func TestLiveToolSettingsKeepsAnUnprojectedMCPHeader(t *testing.T) {
base := fileConfig()
base.Tools.MCPServers = []config.MCPServer{{
Name: "alpha",
Transport: "http",
URL: "https://alpha.example/mcp",
Headers: map[string]string{"Authorization": "Bearer secret"},
}}
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}}
b, _, rec := newMCPReconcileBoot(t, base, stub)
changed := mcpServerDoc("alpha", true)
changed["transport"] = "http"
changed["url"] = "https://alpha.example/mcp"
delete(changed, "command")
applyToolSettings(t, b, stub, 11, toolSettingsDocument(changed))
rec.mu.Lock()
seen := rec.seen["alpha"]
rec.mu.Unlock()
if got := seen.Headers["Authorization"]; got != "Bearer secret" {
t.Errorf("reconnected server headers = %v, want the unprojected Authorization header restored", seen.Headers)
}
}
+39
View File
@@ -0,0 +1,39 @@
package archied
import (
"log/slog"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/transcription"
"github.com/samcharles93/archie-core/internal/secret"
)
// TestSetupTranscriberBuildsOnTheModelOwningSide pins where the voice
// capability is constructed: beside the chat runtime, from the process's own
// [models].transcription and [providers.*]. The Messaging Service carries the
// audio bytes across the inbound wire but no longer builds this client.
func TestSetupTranscriberBuildsOnTheModelOwningSide(t *testing.T) {
log := slog.New(slog.DiscardHandler)
t.Run("configured role wires a transcriber", func(t *testing.T) {
b := &boot{secrets: secret.NewRegistry()}
b.setupTranscriber(config.Config{
Models: map[string]string{transcription.Role: "local/whisper-large-v3"},
Providers: map[string]config.Provider{
"local": {Class: "openai-compatible", BaseURL: "http://127.0.0.1:8080/v1"},
},
}, log)
if b.transcriber == nil {
t.Fatal("transcriber = nil, want a client built from [models].transcription")
}
})
t.Run("absent role degrades to nil", func(t *testing.T) {
b := &boot{secrets: secret.NewRegistry()}
b.setupTranscriber(config.Config{}, log)
if b.transcriber != nil {
t.Fatalf("transcriber = %v, want nil when no role is configured", b.transcriber)
}
})
}
@@ -6,55 +6,9 @@ import (
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/forge"
"github.com/samcharles93/archie-core/internal/gateway"
"github.com/samcharles93/archie-core/internal/secret"
)
// TestGatewayWorktreeManagerAdvertisesReviewPR composes the Gateway's own
// tree step with the reviewer and the review tool: whatever
// buildWorktreeManager produces must be enough for boot.prReviewer to yield a
// reviewer and for ReviewTools to advertise review_pr. The call-order
// assertion in composition_order_test.go proves the Gateway makes this step;
// this proves the step is sufficient, so a manager built without the forge
// credential or the configured work dir cannot pass as wired.
func TestGatewayWorktreeManagerAdvertisesReviewPR(t *testing.T) {
const token = "gateway-forge-token"
cfg := config.Config{
WorkDir: t.TempDir(),
BotUser: "archie-bot",
BotEmail: "bot@example.test",
Forge: config.Forge{Host: "https://forge.example.test"},
}
b := &boot{
cfg: cfg,
cfgHolder: config.NewHolder(cfg),
token: token,
log: slog.New(slog.DiscardHandler),
forgeClient: reviewCapableForge{Forge: forge.NewNoop(slog.New(slog.DiscardHandler))},
}
b.buildWorktreeManager()
if b.trees.WorkDir != cfg.WorkDir {
t.Errorf("worktree manager WorkDir = %q, want the configured %q", b.trees.WorkDir, cfg.WorkDir)
}
if b.trees.BaseURL != cfg.Forge.Host {
t.Errorf("worktree manager BaseURL = %q, want the configured forge host %q", b.trees.BaseURL, cfg.Forge.Host)
}
if b.trees.Token != token {
t.Errorf("worktree manager Token = %q, want the resolved forge token %q", b.trees.Token, token)
}
reviewer := b.prReviewer()
if reviewer == nil {
t.Fatal("prReviewer() = nil after the Gateway's worktree-manager step; review_pr would never be advertised")
}
if !hasReviewPRTool(gateway.ReviewTools(reviewer, "archie")) {
t.Fatal("review_pr not advertised after the Gateway's worktree-manager step")
}
}
// TestBuildTreesAndIdentitiesBuildsRootManagerAndIdentityRunners pins the
// daemon's tree composition, which the shared buildWorktreeManager must not
// change: the daemon still owns the process-wide manager *and* one runner per
@@ -15,7 +15,7 @@ import (
// channel. Only what an operator may see: no configuration value ever enters a
// descriptor, so the manager cannot become a second source for a token or a
// credential.
func channelDescriptors(instances []channelInstance) []status.Descriptor {
func channelDescriptors(instances []*channelInstance) []status.Descriptor {
descriptors := make([]status.Descriptor, 0, len(instances))
for _, instance := range instances {
descriptors = append(descriptors, status.Descriptor{
@@ -34,8 +34,8 @@ func channelDescriptors(instances []channelInstance) []status.Descriptor {
// the single source for both the capability a descriptor declares and the action
// a reload performs; deriving them separately is how a dashboard ends up offering
// a button that reports success and changes nothing (archie-core-np7l).
func reloadable(instance channelInstance) bool {
gateway, ok := instance.channel.(*telegram.Gateway)
func reloadable(instance *channelInstance) bool {
gateway, ok := instance.current().(*telegram.Gateway)
return ok && gateway.Reload != nil
}
@@ -53,7 +53,7 @@ func (s *Service) ReloadChannel(_ context.Context, id string) error {
if instance.name != id {
continue
}
gateway, ok := instance.channel.(*telegram.Gateway)
gateway, ok := instance.current().(*telegram.Gateway)
if !ok || gateway.Reload == nil {
return fmt.Errorf("messaging: channel %q does not support reload", id)
}
Loaded 100 of 550 files, more files were not shown because too many files have changed in this diff. Show more