docs/prds/external-agent-harness.md (Credentials) and orgs-and-access.md:
egress.Resolver had no production implementation, and no run carried a
credential naming the org secrets its identity is granted, so a Kit's
required credential@1 was refused at the proxy and no harness run
authenticated (archie-core-egkf.11).
Two things, as scoped (this does not attempt #1026's full run-credential
consolidation replacing WorktreeGrantIssuer/StateStoreGrantIssuer -- that
PRD item is real, separate, and still open; this is deliberately narrower):
1. A run credential naming granted secrets: config.CredentialBinding maps a
Kit credential@1 service to a secret; config.Config/IdentityConfig gain
Org and GrantedCredentials (a per-identity allowlist of service names,
reusing the existing per-identity config-override pattern DiffCapLines
already uses, not a new Cedar/Authorizer integration -- KindSecret policy
objects exist in internal/domain/access but assembling a full Principal
is #1026's job, not a two-line addition here). config.ContainerConfig.
BoundCredentials computes the declared (Kit) ∩ granted (identity) ∩
org-matched intersection Sam's own rule requires: neither side widens
the other, proven by a mutation-checked test flipping each of the three
independently.
2. egress.GrantResolver: the production Resolver, holding only what a
caller explicitly Grant-ed one run, replaced wholesale (not merged) on
a repeated Grant, gone entirely on RevokeGrant. kitrun.Launcher.Launch
computes the intersection per launch and resolves real values through
the existing secret registry (SecretResolver), Grants it before the
proxy session opens, and Release/error-path rollback (a new shared
Launcher.release) always revokes it.
Course-corrected mid-implementation (flagged by Sam): credential bindings
first landed as a boot-time config.ContainerConfig.Credentials field
captured once into Launcher.Bindings -- exactly the "parses but is not a
resource" trap CLAUDE.md warns about, and inconsistent with agent-profiles
(#1207) making a Kit profile apply without a restart. Rebuilt as its own
live control-plane resource, CredentialBindingsKind ("credential-bindings"),
following the agent-profiles/container-runtime-policies split precisely:
config.ContainerConfig.Credentials is json:"-", [containers].credentials
is only its seed, and kitrun.Launcher now holds *config.Holder (not a
captured slice) and reads Containers.Credentials fresh on every Launch.
Org/GrantedCredentials were already read fresh per dispatch (d.configFor
inside runKitTask, never cached), so no equivalent fix was needed there.
Deliberately not built: identities and grants as their own State Store
resource (orgs-and-access.md's "Org owns ... identities and their grants").
Identities are entirely config.toml-defined today with no control-plane
resource at all; moving GrantedCredentials alone into one would put half
an identity in two places. That migration is identities' own scope, not
credential bindings'.
Plan item 3 of docs/prds/execution-tree-state-machine.md (archie-core-1220), on
top of the transition tables and ErrIllegalTransition enforcement (1214/1215,
archie-core-qdbo.5):
- Migration 0017 adds step_executions -- id, org_id, workspace_id, execution_id,
attempt, parent_id, depth, kind, name, called_execution_id, status, detail,
tokens_used, started_at, finished_at, indexed on (execution_id, attempt, id).
Ownership fields are stamped from the execution's row; depth is derived from
the parent, never supplied by a caller. Existing rows gain no backfilled
steps.
- task.Store (the workflow engine's mid-run facade) gains StartStep/FinishStep
(5 methods, within the 8 cap), with storecontract.StepRecorder fronting them
on the server; deadlineStore wraps both with its per-call timeout.
- The store enforces each write as one transaction: the guarded row write
under the shared step transition table plus the transition's own
stage_start/stage_finish event row. Staleness is decided before legality,
the way guardTransition decides it, and the store returns the persisted
event for the caller's post-commit publish -- the EmitDurable convention
(the daemon's event sink skips already-persisted rows by assigned ID), which
is why workflow.Run stops emitting stage events beside the store and no
longer discards step-write errors: a failed start or finish parks the
execution, and the stage does not run unrecorded. An interrupted stage
records interrupted rather than failed; a recording failure on that
shutdown path is logged and left to RecoverStale, which owns the
interrupted-execution sweep in plan item 6.
- The run credential of docs/prds/orgs-and-access.md authorises StartStep and
FinishStep on its own execution only: both requests carry the execution ID
the grant check verifies (FinishStep carries it because the interceptor
never reads the database), and FinishStep verifies handler-side that the
step really is that execution's. authorizesTaskScopedCall's sanctioned
widenings are now held as a lookup table so the next one stops growing a
switch.
- The PRD's wire contract is StartStep(execution, attempt, parent, kind, name)
-> step id; the responses also carry the persisted event (needed for the
post-commit publish) and FinishStep's request carries execution_id (needed
for the grant check) -- both noted here as deliberate additions to the PRD's
shorthand. called_execution_id exists in the table but not yet on the wire:
its named consumer is the workflow-call recording of plan item 4 (#1216).
Conformance drives both adapters; grant tests pin the own-execution scoping;
the wire sentinel set gains ErrInvalidStep (InvalidArgument, "step execution
invalid") for a step kind no consumer names.
docs/prds/external-agent-harness.md ("Contract"): workflow definition
validation must reject a stage whose needs the selected harness cannot
meet -- capture tools without an adapter, or a gate retry without a
resume verb. The step vocabulary had no static way to declare either.
Added task.WorkflowInterface.Needs{Captures, GateRetries}, parsed and
validated (GateRetries >= 0) the same way Inputs/Repository already are.
Only a Kit profile is checked against it: an image profile's built-in
agent loop always supports both, so Needs constrains only the harness path.
Two enforcement points, chosen for where each fact is actually known
without a network fetch at save time:
- Captures vs adapter is knowable from config alone (profile.Adapter, the
agentexec.harnessAdapters table), so daemon.pinTaskProfile checks it
right where it already resolves the profile (validateProfileMeetsNeeds),
parking the task the same way an unconfigured profile already does.
- GateRetries vs the Kit's actual agent-sessions resume verb is only known
once the Kit composition is fetched, which kitrun.Launcher.Launch
already does -- so kit.ValidateNeeds runs there (new kitrun.Request.
GateRetries field, threaded from the workflow's parsed Needs in
daemon.runKitTask) rather than inventing an image-fetching workflow-save
validator.
Deliberately NOT built: "a Kit profile named by no workflow is a
validation error" (external-agent-harness.md "Selection"). Read literally
("a Kit profile [that is] named by no workflow"), this is a
cross-resource check -- an agent-profiles entry unreferenced by anything
in workflow-definitions -- and no control-plane Definition validator can
see another resource today (Definition.Validate is a pure []byte->error
function by design, matching every existing resource kind). Building
that crossing is a real, separate piece of infrastructure with its own
ordering questions (does defining a Kit profile before its workflow now
fail?), not a two-line addition, so it is left for a follow-on rather
than bolted on here.
Also fixes a test bug caught by rerunning with a short -timeout per
instruction: TestRunKitTaskThreadsGateRetriesToTheLauncher's fake NATS
subscriber never responded, so runKitTask's call into runViaAgent blocked
forever waiting for a reply bounded by a zero (unconfigured) wall-clock
budget. Fixed by responding, matching the sibling test's pattern.
docs/prds/external-agent-harness.md's "Selection" says a stage may name a
different profile than its workflow's. Investigated before writing new
runtime code, per instruction not to build container-switching machinery:
a Kit task runs in one container provisioned for one profile (Container
layout), so a stage needing a different profile cannot be a mid-container
runner swap without inventing per-stage re-provisioning the PRD does not
ask for and Container layout argues against ("cost scales with the run,
not with how many agents it fans out to").
The requirement is already met by workflow.call plus per-task profile
resolution, both pre-existing: postgres.Store.StartCall stores the
callee's OWN Workflow name (not the caller's), and daemon.pinTaskProfile
resolves a task's profile purely from its own WorkflowDefinitionYAML.
Chaining these means a stage wanting a different profile is its own
callee workflow, started via workflow.call, exactly the way
event-automation.md already describes ("the callee runs as its own run
with its own agent profile").
No new production code, only a PRD clarification (dev-docs regenerated)
plus TestWorkflowCallGivesACalleeItsOwnProfile (daemon_test.go), which
closes the gap between two already-tested facts that nothing previously
stated together: TestWorkflowCallerConformance (staterpc) proves a
callee's Workflow field is independent of its caller's; this proves that
independence is what makes Kit-vs-image runner selection independent too,
composing a caller pinned to an image profile with a real StartCall-
created callee pinned to a Kit profile.
docs/prds/external-agent-harness.md ("Selection"): a Kit profile is an org
resource that applies without a restart. Profiles were bundled inside
container-runtime-policies (ApplyMode: restart-required), which is correct
for Image/MaxConcurrency/Network but not for Profiles, which nothing
startup-builds: daemon.configFor reads config.Holder fresh per dispatch
(pinTaskProfile -> Containers.Profile).
Split Profiles into its own resource, AgentProfileKind ("agent-profiles"),
ApplyMode: live, seeded from [containers.profiles] and validated with the
same rules the file document uses (config.ValidateAgentProfiles, factored
out of ContainerConfig.ValidateProfiles so the two cannot disagree).
config.ContainerConfig.Profiles is now json:"-" so container-runtime-policies
never carries it (one authoritative resource per field, not two), and
runtime_config.go layers the new resource in by wholesale map replacement
(matching ModelRoleAssignmentsKind's precedent) rather than merging into the
file's map. Added Profiles to reload.go's Containers reloadable-subfield set
to match this.
Deliberately NOT built here: true per-org multi-tenant storage for this
resource (docs/prds/orgs-and-access.md places agent profiles under org
ownership, granted to workspaces). No existing control-plane resource kind
in this registry does real per-org storage yet either -- schedules,
workflow settings, etc. are all single instance-wide documents -- so
agent-profiles follows that same established, tested pattern rather than
inventing org-scoped storage unilaterally for this one resource. Org/
workspace grants over agent-profiles are a follow-on, not a redo: nothing
about this resource's shape needs to change to add that scoping later.
Router.Route returned the chat-facing rate-limit prose with a nil error, so
the webhook handler had no way to tell a genuine dispatch outcome from a
rejection: DeliverTo "origin" echoed the prose as a 200 reply, and any
other route got a 202 for an event that was actually dropped before
reaching the LLM, so the source never retries it.
ChatReply now carries RateLimited, set by a new Router.RouteResult (Route
is now a thin wrapper over it) so chat channels that render Text to a
human are unaffected. The webhook handler checks it and answers 429,
matching the precedent internal/webhookguard.RateLimiter's other callers
already set.
applyWorkflowExecutionSettings swapped the running config with cfgHolder.Set,
so the dashboard's published projection kept the previous budgets until the
next reload. Route it through publishConfig like every other config change.
Fixes#1148
The bypass mux mounted captureintake's route from a local literal that
duplicated captureintake.Path, with a comment acknowledging the drift risk:
the kind of duplication that silently stops matching after a rename
(archie-core-1175). Reference the constant instead, so the receiver owns the
one spelling of the route and a rename there cannot unmount here.
The existing routing tests are the drift coverage: TestCaptureIntakeMountedOnBypassMux
drives Handler() with a POST to the real path, so a rename on either side that
stopped matching would fail it; no new test is needed. This gives internal/webui
its first infrastructure import -- the deleted literal existed so webui could
mount an http.Handler without depending on the receiver's concrete package, but
mounting by the owner's constant is exactly the boundary the intake cutover
drew: webui mounts and reads, captureintake owns the write path.
2fcc32d8 gave archied sd_notify: one READY=1 when the run loop starts serving.
RunGateway and RunStateStore serve contracts and health surfaces of their own --
the State Store even takes -ready-addr for a readiness HTTP listener -- but told
systemd nothing, so run as Type=notify either would hang until TimeoutStartSec
and be killed in a restart loop while perfectly healthy (archie-core-1174).
Both now announce at the moment each declares itself serving, the same notion
archied's runLoop announces beside healthSurface.markServing -- no second
definition of started. The Gateway announces from its serving tail
(serveGatewayListener, extracted from RunGateway), after the listener is bound;
the State Store announces after its optional surfaces have started, because a
readiness surface that fails to bind fails the boot and READY must not precede
it, and before serveStateStore, which begins accepting the moment it is called.
No unit file changes Type=notify for them; the helper already lives in package
archied beside both entry points, so no move was needed.
Tests follow the notify pattern the daemon's announcement already has: the
Gateway test drives its serving tail over a bound loopback listener with a
stub contract and judges READY against a real Snapshot RPC on the same socket;
the State Store test drives the real RunStateStore boot over a pgtest database
and waits for the datagram. Both failed red before the announcement existed --
no datagram within the window -- and pass after.
The per-kind request-ID dedup was fixed in e8f86622 for the SQLite store and
carried into the PostgreSQL rewrite (05ee5eff) from day one: ResourceByRequest
filters WHERE kind = $1 AND request_id = $2 and resource_history carries
UNIQUE(kind, request_id). What neither rewrite kept is the test that pins the
cross-kind half of the contract -- the deleted internal/store suite had one, and
the Postgres suite only covers same-kind replay.
Pin it, and prove the failure mode it guards against: with the kind filter
dropped from the query, a request ID reused across two kinds silently returns
the first kind's history row under the second kind's write -- wrong kind, wrong
value, no error (archie-core-1179's latent hazard). Restore the filter and both
kinds write their own revisions, with per-kind replay still idempotent.
archie-core-1000's failure mode was silent persistence: provider-settings seeded
from an already-resolved snapshot stored the process-local ARCHIE_PROVIDER_<hash>
env name with no api_key_ref, and once the resource outranked the file no later
boot had a reference left to resolve. The producer was fixed in b0ff54f6 and the
stored shape is refused in b5e4ee53, but nothing pinned the seed path's own
refusal: ImportConfig over a resolved snapshot must skip the kind, store nothing,
and report why -- the State Store still starts and the file document stays in
force -- rather than wedging on it or storing it.
Pin that contract, and prove the refusal comes from the guard: with
rejectBootDerivedProviderEnv removed the test fails with 'provider-settings was
stored from a resolved snapshot'.
scheduling.Duration landed in f29169c2 (archie-core-1169) with no test over the
JSON contract the schedules document and the jobs table both depend on: the
interval marshals the human string time.ParseDuration reads, unmarshals both
that string and the nanosecond count every schedule stored before the shape
existed carries, and refuses a non-duration string with ErrInvalidSpec. Pin it,
because a regression here fails silently in the worst direction -- the document
writes a count and an operator is back to typing 1800000000000 for one hour.
container-runtime-policies seeded and validated config.ContainerConfig directly,
the last resource in the registry whose document was the internal config struct
(archie-core-1171). encoding/json fell back to that struct's Go field names --
Image, MaxConcurrency, LegacyEnabled, Profiles -- the only Go-cased keys the Web
UI still rendered, and case-insensitive matching let a lowercase misspelling
("maxconcurrency") decode as the field while "max_concurrency" was read back
half-applied.
Define the document here instead: containerRuntimePolicies with explicit
snake_case tags and agentProfile at the profile nesting level, the same shape
a45aebcf gave the channel document. The two durations stay config.Duration,
which already writes the string the file accepts; this leak was the keys only.
The mapping to config.ContainerConfig is one function the validator and the
runtime layering share.
Reading a legacy document is deliberate, so it stays strict about everything
else: DecodeRenamingLegacyKeys renames the seven Go-cased keys an existing store
holds (and the four at the profile level), drops LegacyEnabled -- the removed
containers.enabled switch, which had no runtime consumer and no current
counterpart -- and keeps DisallowUnknownFields, because swallowing an unknown
key decodes as unset and an unset image is a broken worker. A misspelling is
refused.
normalizeContainerPolicies, through the Definition.Normalize hook the channel
document already uses, rewrites a legacy document into the current shape on
write, so a stored document converges the next time it is saved. The layering
keeps its profile semantics -- a document that omits profiles (one stored before
they existed) inherits the file's, one that carries them replaces the file's --
and now checks both spellings of the key.
docs/development/control-plane.md's 'adding a database-owned field' still
instructed the untagged practice this class of issue removes; it now names the
wire-shape rule, the legacy-key tolerance and the Normalize hook instead.
The equivalent fix was made in the crew/qc8p worktree but never committed there before the merge, so the merge silently carried the pre-fix version through despite a clean, no-conflict merge. Re-applied directly on main; task check clean.
Readiness probe test asserts each subsystem registers exactly once instead of
an ordered five-item list. Config descriptor test drops the exact-count check
and its stale settings.js rationale. Container defaults test references the
production constant.
Refs #1229#1231#1232
refuseCallCycles iterated calls (a map) in range order to pick its DFS root, so the same a<->b cycle reported as 'a -> b -> a' on one run and 'b -> a -> b' on the next -- flaky in CI (TestValidateCollectionWorkflowCalls/indirect_cycle failed ~40% of local runs) and a genuinely unstable error message for an operator reading it twice. Sort the roots.
TestExecuteTaskRequestStartsWorkflowCallCallee built its transport with no URL, so it silently fell through to nats.DefaultURL (127.0.0.1:4222). It passed locally against a developer's own NATS server and failed in CI with no servers available for connection. Start an ephemeral server per the sibling test's pattern and dial it explicitly.
Flip provider-settings, model-role-assignments, repository-policies and
scheduling-policy to ApplyMode live, and give the daemon a watch per kind
(keepWatch's reconnection and backoff rules): on a new stored version the
watch re-runs boot.runtimeConfig over the published snapshot and republishes
through config.Holder, keeping last-known-good when the layered document
fails to validate and reporting through apply status.
The stored model-role assignments now own cfg.Models entirely (the map
merge would resurrect a role the store deleted on every re-layering), and a
provider or role update rebuilds the gateway chat runtime's provider set
(swapped runtime, read per turn) and the chat model manager's offered list.
Every caller-supplied status write (Transition, ParkTask, Requeue,
RetryTask, BeginRemediation) now checks the shared taskstate transition
table inside the write's transaction, after the from guard decides
staleness. An off-table pair returns the new storecontract.ErrIllegalTransition,
carried over gRPC through mapError/unmapError on (FailedPrecondition,
"illegal transition"). Claim, BeginRemediation and RecoverStale pin
their pairs in SQL; a test pins those pairs to the table so a query
edit cannot move a write off it. Requeue/RetryTask share one guarded
requeue body. (archie-core-qdbo.5)