diff --git a/docs/architecture/configuration.md b/docs/architecture/configuration.md index 9f3883ef1..f4ac28bd4 100644 --- a/docs/architecture/configuration.md +++ b/docs/architecture/configuration.md @@ -334,6 +334,18 @@ Two properties matter to anyone changing this area: ones. Workflow execution budgets arrive on a watch rather than in a resource 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 + 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 + list the chat surfaces offer. ## Completion criteria diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 3ef46a7ec..b738a2f6e 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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 lifetime of the application. Any value that may legitimately change while\nthe application is running, between application instances, or between\ndeployments is not a constant.\n\nA runtime setting may have a default, but the default is not its only access\npath. The owner exposes a typed settings structure, validation, and a\n`DefaultSettings` constructor or equivalent. Private constants used to implement\ndefaults do not turn those defaults into invariants and MUST NOT be consumed\ndirectly by runtime code.\n\nEach runtime setting and policy value MUST declare:\n\n- its owner;\n- type, units, validation constraints, and safe bounds;\n- default and derivation, if any;\n- whether it is startup-only, live-reloadable, or restart-required;\n- whether it may differ by installation, identity, repository, workflow,\n channel, or plugin instance;\n- whether it is secret, sensitive, or safe to report;\n- its current source, effective value, version, and last-known-good version;\n- the command and identity required to change it.\n\n## Current configuration migration ledger\n\nThis ledger records the current meanings hidden inside `internal/config`. It is\nthe source inventory for dissolving that package; rows are split where the\nexisting structure combines different owners.\n\n| Current values | Current location | Target owner and requirement |\n| ----------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `WorkDir`, `StateDir` | root `Config` | Workspace/storage infrastructure settings, bootstrap-only. `StateDir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. Defaults derive from the platform data directory. |\n| `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. |\n| `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. |\n| `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. |\n| `MaxRetries` | root `Config`, `Repo` | Retry policy owned by the operation being retried. The duplicate global/repository representation must disappear. |\n| `DiffCapLines` | root `Config` | Agent-change policy value. |\n| `MaxSteps`, `WallClock`, `GateMaxFailures` | `Budgets` | Workflow-execution policy, with units and zero/unlimited semantics made explicit. |\n| `Class`, `APIKeyEnv`, `BaseURL` | `Provider` | Provider instance settings. Secret lookup becomes a `SecretRef`, not an environment variable name leaking into the provider domain. |\n| `Mode`, `Command`, `Env` | `LegacyAgent` | Decode-only compatibility input for the removed executor selector. Delete after the config migration window; it has no runtime settings owner. |\n| `Type`, `Host`, `Token` / `TokenEnv` (older form) | `Forge` | Forge adapter settings. The older `TokenEnv` input is accepted only at the loader boundary. |\n| `Trigger`, `AckReaction`, label names | `Dispatch` | Work-intake and forge presentation policy. Label vocabulary is configurable per forge/identity association. |\n| `Engine` | `MemoryConfig` | Memory engine selection. `internal/domain/memory` is the only engine family; per-engine settings remain owned and validated by that engine. |\n| `Name`, `Transport`, `Command`, `Args`, `WorkDir`, `URL` | `MCPServer` | One typed MCP server instance specification. Transport-specific variants must reject fields belonging to other variants. |\n| `MaxResultChars` | `ToolPolicy` | Tool-execution policy values, not generic daemon configuration. |\n| `URL`, `TokenEnv` | `NATSConfig` | NATS transport settings with a secret reference replacing the environment-name field. |\n| `Image`, `MaxConcurrency`, `MaxUptime`, `VolumeTTL`, `PullPolicy`, `Network` | `ContainerConfig` | Mandatory managed-worker infrastructure settings and resource policy. The legacy `enabled` input is decode-only. |\n| model mappings, email, webhook, Telegram | `ChatConfig` | Separate channel instance settings plus channel-routing associations; there is no chat-wide settings owner. |\n| `AllowedUserIDs`, `Token` / `TokenEnv` (older form), update commands | Telegram config | Telegram adapter settings and access policy. `Token` is the preferred `secret.SecretRef`; `TokenEnv` remains a backwards-compatible fallback. |\n| listen/relay addresses | email config | Email adapter instance settings. |\n| webhook target | `Notify` | Notification adapter instance settings. |\n| web listen address | `Web` | Web transport settings. |\n| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |\n| forge, dispatch, models, providers, containers, memory, tools and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |\n| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |\n| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |\n| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |\n\n## Behavioural literals and incorrectly fixed values\n\nThe following current values affect useful behaviour but are not represented as\nowned typed settings or policy. They MUST be classified and migrated before the\nold configuration package is removed. The listed target is the architectural\ndecision; exact setting names are implementation details.\n\n| Capability | Values fixed in current code | Required classification |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Chat agent | maximum steps `8` in `cmd/archied` | Workflow/chat execution policy. |\n| Context compression | enabled, threshold `0.5`, context size `128000`, protect first `3` and last `20`, compression marker, token estimate of four characters per token | Model/context runtime settings. The marker is presentation; the estimate is provider/model strategy, not a universal truth. |\n| Tool guardrails | escalation thresholds `3`, `5`, `10`, `2` | Tool-use policy with named meanings and bounded defaults. |\n| Tool output | per-result cap `50000` characters, no aggregate turn cap, preview `500` characters | Tool-execution resource and presentation settings. Per-result spill/truncation remains; turn continuation is not character- or token-gated. |\n| Pairing/access | code TTL `1h`, maximum pending `3`, rate window `10m`, failures `5`, lockout `1h`, maximum lockout `24h` | Access policy. Code length/alphabet and salt length require an explicit security-constraint decision; they are not automatically valid constants. |\n| NATS daemon consumer | stream `ARCHIE_TASKS`, consumer `archie-daemon`, deduplication `2m`, poll `2s`, deliveries `3`, acknowledgement wait `5m`, inactive threshold `24h`, subjects | NATS topology settings plus delivery policy. Subject grammar or protocol headers may be invariants only if declared as versioned wire contracts. |\n| NATS worker consumer | stream `ARCHIE_TASKS`, consumer `archie-agent`, deduplication `2m`, poll `5s`, acknowledgement wait `30m`, deliveries `3`, inactive threshold `24h`, queue group and retry delay `1s` | Worker transport settings and delivery/retry policy. Shared stream defaults must have one owner rather than two copies. |\n| Worker readiness | readiness timeout `20s`, retry delay `250ms` | Worker lifecycle and retry policy. |\n| Execution/RPC | agent execution `30m`, task-run RPC `60s`, worktree RPC `15m` | Per-operation timeout policy. |\n| Plugin/tool cleanup | plugin rollback `10s`, tool-provider cleanup `10s`, MCP-provider cleanup `10s` | Lifecycle shutdown/rollback policy owned by each engine, with a shared policy vocabulary where appropriate. |\n| Memory read path | per-scope record limit `20`, rendered `\u003cmemory\u003e` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |\n| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |\n| Memory safety scanner | compiled prompt-injection and sensitive-data patterns with fixed warn/block consequences | Versioned memory-domain policy definitions. Patterns and consequences must be inspectable and replaceable without editing scanner code. |\n| MCP stdio | initial backoff `500ms`, maximum backoff `30s`, unlimited default retries, send and shutdown `5s` | MCP transport retry, request, and lifecycle policy. Unlimited retries must be explicit rather than a zero-value accident. |\n| MCP SSE/HTTP | reconnect `1s` to `30s`, POST/request timeout `30s` | MCP transport settings and retry policy. |\n| Message framing | MCP frame `4MiB`, worker protocol frame `8MiB`, diagnostic `64KiB`, media/base64 `64MiB` | Resource/security policy unless a published wire protocol mandates the limit. Limits must be configurable only within safe bounds. |\n| Webhooks and web UI | webhook bind `0.0.0.0:8644`, webhook shutdown `5s`, web read-header `5s`, web shutdown `2s` | Transport instance and lifecycle settings. |\n| Telegram | typing refresh `4s`, draft interval `700ms`, update-action TTL `10m` | Telegram adapter presentation and lifecycle settings. |\n| Telegram limits | message length `4000` and callback/update prefixes | Record the upstream platform constraint and version it as an adapter compatibility limit; prefixes may remain wire constants when changing them would invalidate outstanding callbacks. |\n| Containers | stop and pull timeouts `10s` and `30s` | Container lifecycle policy. |\n| HTTP clients | feasibility notification timeout `10s`; other paths use `http.DefaultClient` | Adapter request policy. Every outbound client requires an explicit timeout profile. |\n| Workflow routing | labels `bug`, `feature`, `bootstrap`; workflows `tdd`, `feasibility`, `bootstrap`; fallback `implement` | Agent-system routing policy. Workflow identifiers are references, not compiled routing decisions. |\n| Filesystem/deployment | `.agents/skills`, `.archie/stages`, `.archie/gate.go`, `/data/worktree`, `/data/repo`, cache names/paths and prepared sentinel | Split into deployment settings, repository conventions, and genuine internal protocol markers. Paths an installation may relocate are settings. |\n| Packaged release data | `/usr/share/archie/CHANGELOG.md` | Packaging/deployment settings or paths derived from an installation prefix. |\n| Forge presentation | default label colour `bfd4f2` and state-label colours | Forge adapter presentation settings. |\n| Fallback system prompt | compiled fallback prompt | Agent-system default content, versioned and replaceable through its owning settings; safety constraints remain policy/code. |\n| Default paths and identities | config path, data paths, listen addresses, model roles and workflow names | Typed defaults belonging to their respective owners, never global constants consumed throughout the application. |\n\nThis inventory is intentionally broader than exported Go `const` declarations. A\nliteral hidden in a constructor, timeout, switch, retry loop, path join, prompt,\nlabel map, or client setup restricts behaviour just as effectively as an\nincorrectly used constant.\n\n## Constants that may remain\n\nA value may remain constant only when its owner documents why runtime variation\nwould be invalid. Typical valid cases are:\n\n- domain enum values and state names;\n- a versioned wire-protocol version or framing token;\n- reserved internal headers and callback prefixes that peers must interpret\n identically;\n- compile-time mathematical relationships;\n- sentinel errors and internal type identifiers.\n\nNames such as a stream, consumer, label, workflow, file, directory, network,\nmodel role, timeout, retry count, capacity, size limit, colour, prompt, command,\nor executable are not invariants merely because the current application has only\none of them.\n\nArchitecture tests SHOULD reject exported behavioural constants outside approved\ninvariant packages and SHOULD detect direct consumption of private default\nconstants outside their owning `DefaultSettings` construction.\n\n## Current mutation and reload ledger\n\nThe application currently changes behavioural values through unrelated paths:\n\n| Current change seam | Current behaviour | Required target |\n| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Telegram `/restart` in `cmd/archied` | Re-reads the global document and directly replaces Telegram token and allowed-user IDs; failure retains old values. | Submit a Telegram-settings candidate through the universal change protocol. Validate the complete candidate, promote atomically, audit the acting identity, and retain last-known-good. |\n| Active model selection | `chatModelManager.SetActiveModel` changes a model reference. | A conversation/session command changing runtime state. Validate against configured model instances and audit it; do not rewrite configuration. |\n| Active provider selection | `chatModelManager.SetActiveProvider` changes provider selection. | A conversation/session command changing runtime state, with the same distinction from provider-instance configuration. |\n| Persona selection | `PersonaRegistry.SetActive` mutates an in-memory per-session choice. | Agent-system session state. Persistence and audit requirements are owned by that domain, not the configuration loader. |\n| File and environment overlays | Applied while loading `internal/config`; defaults are filled by mutation in `finalize`. | Configuration-infrastructure input processing that produces separately typed candidates. Defaults and derivations remain visible in provenance. |\n| SIGHUP config reload (2026-08) | Re-resolves the file config, re-applies the database layer over it, validates, then atomically republishes through `config.Holder`. A failed reload, whether the file or the control plane caused it, keeps the running config and records `last_error`/`last_error_at` in `/api/config`. | Candidate promotion with last-known-good retention: the running snapshot is untouched on failure. A bounded observation period and actor audit are not yet implemented. |\n| Control-plane resource command (2026-09) | `ControlPlaneService.Command` validates a whole resource document against its owning feature, then writes it with an audit record (actor, source, request ID, expected version) under optimistic concurrency. Hosted on the State Store's gRPC server; the Web UI and messaging channels are its only clients. See `docs/prds/runtime-control-plane.md`. | Met for validate-stage-promote, actor audit and versioned history. Per-field health observation and validate-before-switch on live apply are not yet implemented. |\n\nAny further mutation seam discovered during migration MUST be added here before\nit is changed. Direct field assignment on a live settings object is prohibited.\n\n## Universal change protocol\n\nChanging configuration is an application command performed by an identity. It\nMUST:\n\n1. resolve the target owner and current version;\n2. parse into that owner's typed settings;\n3. validate syntax, semantic constraints, policy, references, and safe bounds;\n4. stage a candidate without altering the active value;\n5. run owner-defined readiness and health checks;\n6. atomically promote the candidate and record actor, source, reason, diff,\n prior version, and new version;\n7. observe the affected capability for a bounded period;\n8. retain the new version on success, or automatically restore last-known-good\n on failure;\n9. report the rejected or rolled-back candidate without terminating unaffected\n capabilities.\n\nStartup loading uses the same candidate rules. A bad user value therefore does\nnot partially mutate the application or make a previously healthy capability\nunavailable.\n\nSettings that cannot safely reload in-process are marked restart-required. The\nchange may still be validated and versioned immediately, but promotion occurs\nthrough a controlled restart with the same health and rollback semantics.\n\n## Implemented runtime reload and settings writes (2026-09)\n\nTwo mechanisms change behavioural values at runtime: SIGHUP re-reads the file\nconfig, and the control plane owns every database-backed setting. The dashboard\nruntime overlay that used to sit between them was deleted once the control plane\ncovered its surface; `-config-overlay` names a file overlay and is unrelated.\n\n### Published snapshot: `config.Holder`\n\nThe running configuration is a published snapshot held in `config.Holder`\n(`internal/config/holder.go`). Get returns a value under RLock; Set replaces the\nwhole snapshot. A published Config is immutable: reload constructs a fresh one\nand calls Set. `config.Clone` deep-copies every reference-type field so a failed\ndecode cannot mutate the published snapshot's shared maps. `Holder.Get` panics\non a nil receiver — a forgotten `NewHolder` must fail loudly, not boot a daemon\nthat silently runs on an empty config.\n\n### The reloadable-field criterion\n\nThe diff-and-warn on reload asks whether a changed field takes effect without a\nrestart. The criterion is: **a field is reloadable when every consumer re-reads\nit.** That question read as \"what does the daemon re-read\" while the daemon owned\nthe only Holder; it stopped being sufficient when webui began sharing that\nHolder, because webui handlers re-read on every request. The allowlist lives in\n`cmd/archied/reload.go` and is deliberately a deny-by-default list: a field added\nto Config later defaults to requires-restart, forcing whoever adds it to decide\ndeliberately. A reload that changes any non-allowlisted field logs\n\"requires a restart\" with the field names; a fully-applied reload logs Info.\n\n### SIGHUP reload\n\nSIGHUP re-resolves the file config, re-applies the database layer over it\n(`boot.runtimeConfig`, the same call boot makes), validates, and atomically\nrepublishes through the shared Holder. A failed reload keeps the running config\nand records `last_error`/`last_error_at` in `/api/config` so the stale state is\nvisible where the operator is looking. The three poll tickers re-read\n`PollInterval` per iteration and reset on change, so a reloaded interval\ngenuinely takes effect.\n\n### Settings writes go through the control plane\n\nDatabase-backed settings are read and written through\n`ControlPlaneService` on the State Store's gRPC server: catalogue, query,\ncommand, watch. Each feature owns its resource's validation and commands;\nstorage writes versions and audit records only. `docs/prds/runtime-control-plane.md`\nis the specification.\n\nTwo properties matter to anyone changing this area:\n\n- **Bootstrap stays file-owned.** The daemon reads the file config first and\n layers database resources over it at boot (`boot.loadRuntimeConfig`). Values\n the daemon needs before it can reach the State Store — the database path,\n listen addresses, credentials — stay file-only by design.\n- **Reload re-reads them.** SIGHUP resolves the file document and then runs the\n same `boot.runtimeConfig` layering boot does, so a reload cannot revert a\n database-owned setting to its file value. A control plane that cannot answer\n fails the reload rather than publishing the file's values over the running\n ones. Workflow execution budgets arrive on a watch rather than in a resource\n query, so boot records the last published settings and the reload re-applies\n them from there.\n\n## Completion criteria\n\nThe configuration rearchitecture is complete only when:\n\n- `internal/config` no longer exists;\n- every behavioural value has one classification and owner;\n- every current field and hard-coded value in the ledgers has a recorded\n disposition;\n- domains and plugins receive only their typed settings;\n- all changes use semantic commands and the universal change protocol;\n- active, candidate, rejected, rolled-back, and last-known-good versions are\n queryable with secret-safe provenance;\n- generated documentation lists every external key, default, constraint,\n mutability class, owner, and deprecation;\n- architecture tests prevent a new central runtime configuration model, direct\n live-setting mutation, and incorrectly fixed behavioural values.\n\n## Startup policy: missing credential degrades, invalid config is fatal\n\nDecided 2026-07-30. Recovered 2026-08-09 from the pre-migration issue tracker.\n\nA missing **credential** disables a capability. Only an **invalid config** stops\nthe daemon. \"Forge is a feature, not a requirement.\"\n\nBefore `518a1a0`, an unresolvable forge token did `return 1` in\n`cmd/archied/main.go`, so a chat-only user who never configured GitHub got no\nchat, no gateway, nothing — and under a systemd unit with `Restart=on-failure`\nand no start limit it crash-looped every five seconds with the error scrolling\npast unread. Forge construction now lives in `resolveForge`, shared by the\nprimary forge and every configured identity, and degrades to `forge.NewNoop`\nwith a warning. The identity path had the same defect and was worse: one\nidentity's missing credential killed all the others.\n\nMalformed configuration still fails fast in `configuration.Validate`, well\nbefore this point. That distinction is the whole design.\n\nApply the same reasoning to any future capability credential, LLM keys\nespecially: start, report the capability as unavailable, let the operator see it.\nGuarded by `TestResolveForgeDegradesInsteadOfFailing`.\n\n**Known consequence, tracked separately:** `worktree.Manager` still receives the\nempty token, so pushes fail late rather than at startup.\n\n## Config generation belongs to `archied setup`, not `install.sh`\n\nDecided 2026-07-30 ([#368](https://github.com/samcharles93/archie-core/issues/368)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n`install.sh` must stop generating `config.toml`; `archied setup` owns it. The\ninstaller hand-rolling TOML has already drifted from the schema once: the\ngenerated-config branch hardcoded `key = ARCHIE_GITHUB_TOKEN` and\n`host = ${GITEA_URL}` regardless of the answers given, so choosing Gitea produced\na config naming a token the installer never wrote (archied then exited 1), and\nchoosing GitHub pointed `host` at `gitea.example.com`. `61a5b35` patched this\nwith a `forge_block` shell helper shared by both config paths — that helper is a\n**workaround**, deleted by\n[#72](https://github.com/samcharles93/archie-core/issues/72). The durable fix is\nthat the code writing the config is the code that reads it.\n\nWhy Go and not Python: the installer must run where nothing is installed yet, and\n`python3` with `tomllib` means 3.11+, which is not safe on LTS distros. `archied`\nis already being built two steps earlier.\n\n**Key constraint for the port:** `BurntSushi/toml` does **not** survive a\ndecode/encode round trip with comments intact, and `config.example.toml` carries\ndocumentation users are meant to hand-edit. Decide the write strategy\n([#412](https://github.com/samcharles93/archie-core/issues/412)) before writing\nany prompting code. Do not port a separate `config.yaml`/`auth.yaml` secret\nsplit — Archie already has `secret.SecretRef{engine,key}`, so setup writes the\nreference to TOML and the value to the secret engine.\n" + "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 lifetime of the application. Any value that may legitimately change while\nthe application is running, between application instances, or between\ndeployments is not a constant.\n\nA runtime setting may have a default, but the default is not its only access\npath. The owner exposes a typed settings structure, validation, and a\n`DefaultSettings` constructor or equivalent. Private constants used to implement\ndefaults do not turn those defaults into invariants and MUST NOT be consumed\ndirectly by runtime code.\n\nEach runtime setting and policy value MUST declare:\n\n- its owner;\n- type, units, validation constraints, and safe bounds;\n- default and derivation, if any;\n- whether it is startup-only, live-reloadable, or restart-required;\n- whether it may differ by installation, identity, repository, workflow,\n channel, or plugin instance;\n- whether it is secret, sensitive, or safe to report;\n- its current source, effective value, version, and last-known-good version;\n- the command and identity required to change it.\n\n## Current configuration migration ledger\n\nThis ledger records the current meanings hidden inside `internal/config`. It is\nthe source inventory for dissolving that package; rows are split where the\nexisting structure combines different owners.\n\n| Current values | Current location | Target owner and requirement |\n| ----------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `WorkDir`, `StateDir` | root `Config` | Workspace/storage infrastructure settings, bootstrap-only. `StateDir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. Defaults derive from the platform data directory. |\n| `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. |\n| `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. |\n| `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. |\n| `MaxRetries` | root `Config`, `Repo` | Retry policy owned by the operation being retried. The duplicate global/repository representation must disappear. |\n| `DiffCapLines` | root `Config` | Agent-change policy value. |\n| `MaxSteps`, `WallClock`, `GateMaxFailures` | `Budgets` | Workflow-execution policy, with units and zero/unlimited semantics made explicit. |\n| `Class`, `APIKeyEnv`, `BaseURL` | `Provider` | Provider instance settings. Secret lookup becomes a `SecretRef`, not an environment variable name leaking into the provider domain. |\n| `Mode`, `Command`, `Env` | `LegacyAgent` | Decode-only compatibility input for the removed executor selector. Delete after the config migration window; it has no runtime settings owner. |\n| `Type`, `Host`, `Token` / `TokenEnv` (older form) | `Forge` | Forge adapter settings. The older `TokenEnv` input is accepted only at the loader boundary. |\n| `Trigger`, `AckReaction`, label names | `Dispatch` | Work-intake and forge presentation policy. Label vocabulary is configurable per forge/identity association. |\n| `Engine` | `MemoryConfig` | Memory engine selection. `internal/domain/memory` is the only engine family; per-engine settings remain owned and validated by that engine. |\n| `Name`, `Transport`, `Command`, `Args`, `WorkDir`, `URL` | `MCPServer` | One typed MCP server instance specification. Transport-specific variants must reject fields belonging to other variants. |\n| `MaxResultChars` | `ToolPolicy` | Tool-execution policy values, not generic daemon configuration. |\n| `URL`, `TokenEnv` | `NATSConfig` | NATS transport settings with a secret reference replacing the environment-name field. |\n| `Image`, `MaxConcurrency`, `MaxUptime`, `VolumeTTL`, `PullPolicy`, `Network` | `ContainerConfig` | Mandatory managed-worker infrastructure settings and resource policy. The legacy `enabled` input is decode-only. |\n| model mappings, email, webhook, Telegram | `ChatConfig` | Separate channel instance settings plus channel-routing associations; there is no chat-wide settings owner. |\n| `AllowedUserIDs`, `Token` / `TokenEnv` (older form), update commands | Telegram config | Telegram adapter settings and access policy. `Token` is the preferred `secret.SecretRef`; `TokenEnv` remains a backwards-compatible fallback. |\n| listen/relay addresses | email config | Email adapter instance settings. |\n| webhook target | `Notify` | Notification adapter instance settings. |\n| web listen address | `Web` | Web transport settings. |\n| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |\n| forge, dispatch, models, providers, containers, memory, tools and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |\n| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |\n| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |\n| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |\n\n## Behavioural literals and incorrectly fixed values\n\nThe following current values affect useful behaviour but are not represented as\nowned typed settings or policy. They MUST be classified and migrated before the\nold configuration package is removed. The listed target is the architectural\ndecision; exact setting names are implementation details.\n\n| Capability | Values fixed in current code | Required classification |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Chat agent | maximum steps `8` in `cmd/archied` | Workflow/chat execution policy. |\n| Context compression | enabled, threshold `0.5`, context size `128000`, protect first `3` and last `20`, compression marker, token estimate of four characters per token | Model/context runtime settings. The marker is presentation; the estimate is provider/model strategy, not a universal truth. |\n| Tool guardrails | escalation thresholds `3`, `5`, `10`, `2` | Tool-use policy with named meanings and bounded defaults. |\n| Tool output | per-result cap `50000` characters, no aggregate turn cap, preview `500` characters | Tool-execution resource and presentation settings. Per-result spill/truncation remains; turn continuation is not character- or token-gated. |\n| Pairing/access | code TTL `1h`, maximum pending `3`, rate window `10m`, failures `5`, lockout `1h`, maximum lockout `24h` | Access policy. Code length/alphabet and salt length require an explicit security-constraint decision; they are not automatically valid constants. |\n| NATS daemon consumer | stream `ARCHIE_TASKS`, consumer `archie-daemon`, deduplication `2m`, poll `2s`, deliveries `3`, acknowledgement wait `5m`, inactive threshold `24h`, subjects | NATS topology settings plus delivery policy. Subject grammar or protocol headers may be invariants only if declared as versioned wire contracts. |\n| NATS worker consumer | stream `ARCHIE_TASKS`, consumer `archie-agent`, deduplication `2m`, poll `5s`, acknowledgement wait `30m`, deliveries `3`, inactive threshold `24h`, queue group and retry delay `1s` | Worker transport settings and delivery/retry policy. Shared stream defaults must have one owner rather than two copies. |\n| Worker readiness | readiness timeout `20s`, retry delay `250ms` | Worker lifecycle and retry policy. |\n| Execution/RPC | agent execution `30m`, task-run RPC `60s`, worktree RPC `15m` | Per-operation timeout policy. |\n| Plugin/tool cleanup | plugin rollback `10s`, tool-provider cleanup `10s`, MCP-provider cleanup `10s` | Lifecycle shutdown/rollback policy owned by each engine, with a shared policy vocabulary where appropriate. |\n| Memory read path | per-scope record limit `20`, rendered `\u003cmemory\u003e` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |\n| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |\n| Memory safety scanner | compiled prompt-injection and sensitive-data patterns with fixed warn/block consequences | Versioned memory-domain policy definitions. Patterns and consequences must be inspectable and replaceable without editing scanner code. |\n| MCP stdio | initial backoff `500ms`, maximum backoff `30s`, unlimited default retries, send and shutdown `5s` | MCP transport retry, request, and lifecycle policy. Unlimited retries must be explicit rather than a zero-value accident. |\n| MCP SSE/HTTP | reconnect `1s` to `30s`, POST/request timeout `30s` | MCP transport settings and retry policy. |\n| Message framing | MCP frame `4MiB`, worker protocol frame `8MiB`, diagnostic `64KiB`, media/base64 `64MiB` | Resource/security policy unless a published wire protocol mandates the limit. Limits must be configurable only within safe bounds. |\n| Webhooks and web UI | webhook bind `0.0.0.0:8644`, webhook shutdown `5s`, web read-header `5s`, web shutdown `2s` | Transport instance and lifecycle settings. |\n| Telegram | typing refresh `4s`, draft interval `700ms`, update-action TTL `10m` | Telegram adapter presentation and lifecycle settings. |\n| Telegram limits | message length `4000` and callback/update prefixes | Record the upstream platform constraint and version it as an adapter compatibility limit; prefixes may remain wire constants when changing them would invalidate outstanding callbacks. |\n| Containers | stop and pull timeouts `10s` and `30s` | Container lifecycle policy. |\n| HTTP clients | feasibility notification timeout `10s`; other paths use `http.DefaultClient` | Adapter request policy. Every outbound client requires an explicit timeout profile. |\n| Workflow routing | labels `bug`, `feature`, `bootstrap`; workflows `tdd`, `feasibility`, `bootstrap`; fallback `implement` | Agent-system routing policy. Workflow identifiers are references, not compiled routing decisions. |\n| Filesystem/deployment | `.agents/skills`, `.archie/stages`, `.archie/gate.go`, `/data/worktree`, `/data/repo`, cache names/paths and prepared sentinel | Split into deployment settings, repository conventions, and genuine internal protocol markers. Paths an installation may relocate are settings. |\n| Packaged release data | `/usr/share/archie/CHANGELOG.md` | Packaging/deployment settings or paths derived from an installation prefix. |\n| Forge presentation | default label colour `bfd4f2` and state-label colours | Forge adapter presentation settings. |\n| Fallback system prompt | compiled fallback prompt | Agent-system default content, versioned and replaceable through its owning settings; safety constraints remain policy/code. |\n| Default paths and identities | config path, data paths, listen addresses, model roles and workflow names | Typed defaults belonging to their respective owners, never global constants consumed throughout the application. |\n\nThis inventory is intentionally broader than exported Go `const` declarations. A\nliteral hidden in a constructor, timeout, switch, retry loop, path join, prompt,\nlabel map, or client setup restricts behaviour just as effectively as an\nincorrectly used constant.\n\n## Constants that may remain\n\nA value may remain constant only when its owner documents why runtime variation\nwould be invalid. Typical valid cases are:\n\n- domain enum values and state names;\n- a versioned wire-protocol version or framing token;\n- reserved internal headers and callback prefixes that peers must interpret\n identically;\n- compile-time mathematical relationships;\n- sentinel errors and internal type identifiers.\n\nNames such as a stream, consumer, label, workflow, file, directory, network,\nmodel role, timeout, retry count, capacity, size limit, colour, prompt, command,\nor executable are not invariants merely because the current application has only\none of them.\n\nArchitecture tests SHOULD reject exported behavioural constants outside approved\ninvariant packages and SHOULD detect direct consumption of private default\nconstants outside their owning `DefaultSettings` construction.\n\n## Current mutation and reload ledger\n\nThe application currently changes behavioural values through unrelated paths:\n\n| Current change seam | Current behaviour | Required target |\n| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Telegram `/restart` in `cmd/archied` | Re-reads the global document and directly replaces Telegram token and allowed-user IDs; failure retains old values. | Submit a Telegram-settings candidate through the universal change protocol. Validate the complete candidate, promote atomically, audit the acting identity, and retain last-known-good. |\n| Active model selection | `chatModelManager.SetActiveModel` changes a model reference. | A conversation/session command changing runtime state. Validate against configured model instances and audit it; do not rewrite configuration. |\n| Active provider selection | `chatModelManager.SetActiveProvider` changes provider selection. | A conversation/session command changing runtime state, with the same distinction from provider-instance configuration. |\n| Persona selection | `PersonaRegistry.SetActive` mutates an in-memory per-session choice. | Agent-system session state. Persistence and audit requirements are owned by that domain, not the configuration loader. |\n| File and environment overlays | Applied while loading `internal/config`; defaults are filled by mutation in `finalize`. | Configuration-infrastructure input processing that produces separately typed candidates. Defaults and derivations remain visible in provenance. |\n| SIGHUP config reload (2026-08) | Re-resolves the file config, re-applies the database layer over it, validates, then atomically republishes through `config.Holder`. A failed reload, whether the file or the control plane caused it, keeps the running config and records `last_error`/`last_error_at` in `/api/config`. | Candidate promotion with last-known-good retention: the running snapshot is untouched on failure. A bounded observation period and actor audit are not yet implemented. |\n| Control-plane resource command (2026-09) | `ControlPlaneService.Command` validates a whole resource document against its owning feature, then writes it with an audit record (actor, source, request ID, expected version) under optimistic concurrency. Hosted on the State Store's gRPC server; the Web UI and messaging channels are its only clients. See `docs/prds/runtime-control-plane.md`. | Met for validate-stage-promote, actor audit and versioned history. Per-field health observation and validate-before-switch on live apply are not yet implemented. |\n\nAny further mutation seam discovered during migration MUST be added here before\nit is changed. Direct field assignment on a live settings object is prohibited.\n\n## Universal change protocol\n\nChanging configuration is an application command performed by an identity. It\nMUST:\n\n1. resolve the target owner and current version;\n2. parse into that owner's typed settings;\n3. validate syntax, semantic constraints, policy, references, and safe bounds;\n4. stage a candidate without altering the active value;\n5. run owner-defined readiness and health checks;\n6. atomically promote the candidate and record actor, source, reason, diff,\n prior version, and new version;\n7. observe the affected capability for a bounded period;\n8. retain the new version on success, or automatically restore last-known-good\n on failure;\n9. report the rejected or rolled-back candidate without terminating unaffected\n capabilities.\n\nStartup loading uses the same candidate rules. A bad user value therefore does\nnot partially mutate the application or make a previously healthy capability\nunavailable.\n\nSettings that cannot safely reload in-process are marked restart-required. The\nchange may still be validated and versioned immediately, but promotion occurs\nthrough a controlled restart with the same health and rollback semantics.\n\n## Implemented runtime reload and settings writes (2026-09)\n\nTwo mechanisms change behavioural values at runtime: SIGHUP re-reads the file\nconfig, and the control plane owns every database-backed setting. The dashboard\nruntime overlay that used to sit between them was deleted once the control plane\ncovered its surface; `-config-overlay` names a file overlay and is unrelated.\n\n### Published snapshot: `config.Holder`\n\nThe running configuration is a published snapshot held in `config.Holder`\n(`internal/config/holder.go`). Get returns a value under RLock; Set replaces the\nwhole snapshot. A published Config is immutable: reload constructs a fresh one\nand calls Set. `config.Clone` deep-copies every reference-type field so a failed\ndecode cannot mutate the published snapshot's shared maps. `Holder.Get` panics\non a nil receiver — a forgotten `NewHolder` must fail loudly, not boot a daemon\nthat silently runs on an empty config.\n\n### The reloadable-field criterion\n\nThe diff-and-warn on reload asks whether a changed field takes effect without a\nrestart. The criterion is: **a field is reloadable when every consumer re-reads\nit.** That question read as \"what does the daemon re-read\" while the daemon owned\nthe only Holder; it stopped being sufficient when webui began sharing that\nHolder, because webui handlers re-read on every request. The allowlist lives in\n`cmd/archied/reload.go` and is deliberately a deny-by-default list: a field added\nto Config later defaults to requires-restart, forcing whoever adds it to decide\ndeliberately. A reload that changes any non-allowlisted field logs\n\"requires a restart\" with the field names; a fully-applied reload logs Info.\n\n### SIGHUP reload\n\nSIGHUP re-resolves the file config, re-applies the database layer over it\n(`boot.runtimeConfig`, the same call boot makes), validates, and atomically\nrepublishes through the shared Holder. A failed reload keeps the running config\nand records `last_error`/`last_error_at` in `/api/config` so the stale state is\nvisible where the operator is looking. The three poll tickers re-read\n`PollInterval` per iteration and reset on change, so a reloaded interval\ngenuinely takes effect.\n\n### Settings writes go through the control plane\n\nDatabase-backed settings are read and written through\n`ControlPlaneService` on the State Store's gRPC server: catalogue, query,\ncommand, watch. Each feature owns its resource's validation and commands;\nstorage writes versions and audit records only. `docs/prds/runtime-control-plane.md`\nis the specification.\n\nTwo properties matter to anyone changing this area:\n\n- **Bootstrap stays file-owned.** The daemon reads the file config first and\n layers database resources over it at boot (`boot.loadRuntimeConfig`). Values\n the daemon needs before it can reach the State Store — the database path,\n listen addresses, credentials — stay file-only by design.\n- **Reload re-reads them.** SIGHUP resolves the file document and then runs the\n same `boot.runtimeConfig` layering boot does, so a reload cannot revert a\n database-owned setting to its file value. A control plane that cannot answer\n fails the reload rather than publishing the file's values over the running\n ones. Workflow execution budgets arrive on a watch rather than in a resource\n query, so boot records the last published settings and the reload re-applies\n them from there.\n- **Live kinds arrive on a watch.** Provider settings, model role assignments,\n repository policies and scheduling policy are `ApplyMode: live`\n (archie-core-zfb0.1): the daemon keeps a watch per kind and, on a new\n version, re-runs `boot.runtimeConfig` over the published snapshot and\n republishes through `config.Holder`. A candidate the layered document cannot\n run is refused before it is published — last-known-good keeps running and\n the refusal is reported through apply status. The kinds stay\n restart-required while a startup-built component still holds their value\n (tool, plugin, container and channel settings today); a kind joins the live\n list only with a consumer that re-reads it, and the model/provider half of\n it also rebuilds the gateway chat runtime's provider set and the chat model\n list the chat surfaces offer.\n\n## Completion criteria\n\nThe configuration rearchitecture is complete only when:\n\n- `internal/config` no longer exists;\n- every behavioural value has one classification and owner;\n- every current field and hard-coded value in the ledgers has a recorded\n disposition;\n- domains and plugins receive only their typed settings;\n- all changes use semantic commands and the universal change protocol;\n- active, candidate, rejected, rolled-back, and last-known-good versions are\n queryable with secret-safe provenance;\n- generated documentation lists every external key, default, constraint,\n mutability class, owner, and deprecation;\n- architecture tests prevent a new central runtime configuration model, direct\n live-setting mutation, and incorrectly fixed behavioural values.\n\n## Startup policy: missing credential degrades, invalid config is fatal\n\nDecided 2026-07-30. Recovered 2026-08-09 from the pre-migration issue tracker.\n\nA missing **credential** disables a capability. Only an **invalid config** stops\nthe daemon. \"Forge is a feature, not a requirement.\"\n\nBefore `518a1a0`, an unresolvable forge token did `return 1` in\n`cmd/archied/main.go`, so a chat-only user who never configured GitHub got no\nchat, no gateway, nothing — and under a systemd unit with `Restart=on-failure`\nand no start limit it crash-looped every five seconds with the error scrolling\npast unread. Forge construction now lives in `resolveForge`, shared by the\nprimary forge and every configured identity, and degrades to `forge.NewNoop`\nwith a warning. The identity path had the same defect and was worse: one\nidentity's missing credential killed all the others.\n\nMalformed configuration still fails fast in `configuration.Validate`, well\nbefore this point. That distinction is the whole design.\n\nApply the same reasoning to any future capability credential, LLM keys\nespecially: start, report the capability as unavailable, let the operator see it.\nGuarded by `TestResolveForgeDegradesInsteadOfFailing`.\n\n**Known consequence, tracked separately:** `worktree.Manager` still receives the\nempty token, so pushes fail late rather than at startup.\n\n## Config generation belongs to `archied setup`, not `install.sh`\n\nDecided 2026-07-30 ([#368](https://github.com/samcharles93/archie-core/issues/368)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n`install.sh` must stop generating `config.toml`; `archied setup` owns it. The\ninstaller hand-rolling TOML has already drifted from the schema once: the\ngenerated-config branch hardcoded `key = ARCHIE_GITHUB_TOKEN` and\n`host = ${GITEA_URL}` regardless of the answers given, so choosing Gitea produced\na config naming a token the installer never wrote (archied then exited 1), and\nchoosing GitHub pointed `host` at `gitea.example.com`. `61a5b35` patched this\nwith a `forge_block` shell helper shared by both config paths — that helper is a\n**workaround**, deleted by\n[#72](https://github.com/samcharles93/archie-core/issues/72). The durable fix is\nthat the code writing the config is the code that reads it.\n\nWhy Go and not Python: the installer must run where nothing is installed yet, and\n`python3` with `tomllib` means 3.11+, which is not safe on LTS distros. `archied`\nis already being built two steps earlier.\n\n**Key constraint for the port:** `BurntSushi/toml` does **not** survive a\ndecode/encode round trip with comments intact, and `config.example.toml` carries\ndocumentation users are meant to hand-edit. Decide the write strategy\n([#412](https://github.com/samcharles93/archie-core/issues/412)) before writing\nany prompting code. Do not port a separate `config.yaml`/`auth.yaml` secret\nsplit — Archie already has `secret.SecretRef{engine,key}`, so setup writes the\nreference to TOML and the value to the secret engine.\n" }, { "url": "/dev/architecture/dashboard-agent-tools/", diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index f140074e5..d40e45695 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -213,7 +213,16 @@ type boot struct { kitLauncher daemon.KitLauncher storeBackend storage.Backend - llm *runtime.Runtime + // llm is the chat runtime's provider runtime, held in a pointer the chat + // surfaces read through chatLLM at each use. A live provider-settings or + // model-role-assignments update swaps it wholesale: ai-sdk's Runtime + // caches the provider instances it built, so a changed provider set needs + // a new Runtime rather than a mutated one. + llm atomic.Pointer[runtime.Runtime] + // runtimeVersions records the version of every control-plane kind boot's + // layering applied. Set once at boot before the runtime-resource watches + // start, which read it as their resume points. + runtimeVersions map[string]int64 // embeddings is nil unless models["embedding"] and a working provider // credential are both configured -- see setupLLMAndChat's "Embeddings @@ -223,7 +232,7 @@ type boot struct { embeddings domainembedding.Client toolReg *tools.Registry - chatModels gateway.ModelManager + chatModels *chatModelManager personas *gateway.PersonaRegistry chatTasks gateway.TaskCreator chatController *gateway.StoreTaskController @@ -279,6 +288,16 @@ func newBootstrap() *boot { return &boot{log: slog.New(slog.NewJSONHandler(os.Stderr, nil)), agentStatus: &daemon.AgentStatus{}} } +// chatLLM is the provider runtime the chat surfaces read at each use: a turn +// resolves it when it starts, so a runtime swapped by a live model-settings +// update is the one the turn after it runs on. +func (b *boot) chatLLM() *runtime.Runtime { return b.llm.Load() } + +// setLLM replaces the chat runtime. A nil runtime is a legal state: a +// deployment whose every provider credential was disabled by a live update +// leaves chat turns refused until another update restores one. +func (b *boot) setLLM(rt *runtime.Runtime) { b.llm.Store(rt) } + func (b *boot) addCleanup(fn func()) { b.cleanups = append(b.cleanups, fn) } @@ -1087,7 +1106,7 @@ func (b *boot) setupCurators(ctx context.Context) { // (TurnRunnerConfig.BotUser), so a fact written here is a fact a later // turn reaches. Conversations: sessioncurator.NewAdapter(b.chatSessionStore, b.cfg.BotUser), - LLM: curatorLLMRunner{rt: b.llm, outcomes: b.providerOutcomes}, + LLM: curatorLLMRunner{llm: b.chatLLM, outcomes: b.providerOutcomes}, // b.chatModels.ActiveModel() is the same source sendChatTurn uses // for a real chat turn (telegram_setup.go) -- not // b.defaultChatIdentity, which names a task-routing identity, not diff --git a/internal/app/archied/chat_models.go b/internal/app/archied/chat_models.go index 4d8a4e6e9..e390cdc6f 100644 --- a/internal/app/archied/chat_models.go +++ b/internal/app/archied/chat_models.go @@ -15,14 +15,29 @@ import ( // The configured role-to-model map supplies the available catalog; switching // chat models does not rewrite daemon configuration or affect workflow roles. type chatModelManager struct { - mu sync.RWMutex - models []string - active string + 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 details map[string]gateway.ModelDetails providerNames map[string]string } -func newChatModelManager(configured map[string]string, catalogs ...[]string) *chatModelManager { +// pickChatDefault is the model the manager starts on: the chat role's +// assignment, falling back to the builder role's. +func pickChatDefault(configured map[string]string) string { + if active := strings.TrimSpace(configured["chat"]); active != "" { + return active + } + return strings.TrimSpace(configured["builder"]) +} + +// mergeModelRefs is the model set the manager offers: the configured role +// assignments plus every catalog, unique and sorted. +func mergeModelRefs(configured map[string]string, catalogs ...[]string) []string { unique := make(map[string]struct{}, len(configured)) for _, ref := range configured { ref = strings.TrimSpace(ref) @@ -44,18 +59,35 @@ func newChatModelManager(configured map[string]string, catalogs ...[]string) *ch models = append(models, ref) } slices.Sort(models) + return models +} - active := strings.TrimSpace(configured["chat"]) - if active == "" { - active = strings.TrimSpace(configured["builder"]) - } +func newChatModelManager(configured map[string]string, catalogs ...[]string) *chatModelManager { return &chatModelManager{ - models: models, active: active, + models: mergeModelRefs(configured, catalogs...), + active: pickChatDefault(configured), + catalogs: append([][]string(nil), catalogs...), details: make(map[string]gateway.ModelDetails), providerNames: make(map[string]string), } } +// SetConfigured re-derives the model set the manager offers after a live +// change to model-role-assignments or provider-settings: the list is built +// from the configured roles at construction, so a stored change would leave +// the chat surfaces offering refs the runtime can no longer resolve. The +// operator's active selection survives when the new roles still carry it; a +// removed one falls back the way construction does. +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 +} + func (m *chatModelManager) ApplyModelCatalog(snapshot modelcatalog.Snapshot) { m.mu.Lock() defer m.mu.Unlock() diff --git a/internal/app/archied/chat_setup.go b/internal/app/archied/chat_setup.go index fb1ecea80..f9c5808a6 100644 --- a/internal/app/archied/chat_setup.go +++ b/internal/app/archied/chat_setup.go @@ -28,8 +28,12 @@ type chatSetup struct { // Cfg is read once per setup function via Get(); the process is not // 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 - LLM *runtime.Runtime + Cfg *config.Holder + // 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 + // be captured at construction. nil means no model runtime is configured. + LLM func() *runtime.Runtime ChatModels gateway.ModelManager ToolReg *tools.Registry Personas *gateway.PersonaRegistry @@ -152,7 +156,7 @@ func makeChatLLMResponder( sessionStore gateway.SessionStore, router *gateway.Router, ) (gateway.LLMResponder, gateway.LLMStreamResponder) { - if s.LLM == nil { + if s.LLM == nil || s.LLM() == nil { return nil, nil } runner := newChatTurnRunner(ctx, channel, s, sessionStore, router) @@ -365,7 +369,7 @@ func multimodalMediaRefs(output string) []tools.MediaRef { // untitled and are logged here. type chatTitleGenerator struct { log *slog.Logger - llm *runtime.Runtime + llm func() *runtime.Runtime chatModels gateway.ModelManager } @@ -395,7 +399,11 @@ func (g *chatTitleGenerator) GenerateTitle(ctx context.Context, sessionID, first // broken provider on the strength of a call no user was waiting for. // No tool set and no stream, so no tool call can be reported: this turn // needs no icons. - text, err := sendChatTurn(ctx, g.llm, g.chatModels.ActiveModel(), + llm := g.llm() + if llm == nil { + return "", fmt.Errorf("no model runtime is configured") + } + text, err := sendChatTurn(ctx, llm, g.chatModels.ActiveModel(), core.GenerateOptions{Messages: messages, MaxSteps: 1}, nil, nil, nil) if err != nil { if g.log != nil { diff --git a/internal/app/archied/chat_turn_model.go b/internal/app/archied/chat_turn_model.go index 31676ed98..feccb4e5c 100644 --- a/internal/app/archied/chat_turn_model.go +++ b/internal/app/archied/chat_turn_model.go @@ -3,6 +3,7 @@ package archied import ( "context" "encoding/json" + "fmt" "github.com/samcharles93/ai-sdk/chat" "github.com/samcharles93/ai-sdk/core" @@ -17,7 +18,9 @@ import ( // provider-neutral TurnModel seam. Tool construction remains here because it // depends on runtime registries and configured execution limits. type chatTurnModel struct { - llm *runtime.Runtime + // llm resolves the provider runtime at each turn, so a runtime swapped by + // a live model-settings update is the one the turn after it runs on. + llm func() *runtime.Runtime registry *tools.Registry maxSteps int limits agentexec.ToolLimits @@ -26,7 +29,7 @@ type chatTurnModel struct { } func newChatTurnModel( - llm *runtime.Runtime, + llm func() *runtime.Runtime, registry *tools.Registry, maxSteps int, limits agentexec.ToolLimits, @@ -54,7 +57,7 @@ func (m *chatTurnModel) Prepare( return nil, err } return &preparedChatTurnModel{ - llm: m.llm, + llm: m.llm(), model: req.Model, options: options, toolInfo: toolSummaries(options.Tools), @@ -121,5 +124,10 @@ func (m *preparedChatTurnModel) Generate( // This is one provider response's output allowance, not a turn- // continuation budget. Tool loops remain free to continue. options.MaxTokens = 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 { + return "", fmt.Errorf("llm chat: no model runtime is configured") + } return sendChatTurn(ctx, m.llm, m.model, options, stream, m.outcomes, m.icons) } diff --git a/internal/app/archied/control_plane.go b/internal/app/archied/control_plane.go index d45c51098..624333292 100644 --- a/internal/app/archied/control_plane.go +++ b/internal/app/archied/control_plane.go @@ -5,6 +5,7 @@ import ( "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/workflow" @@ -16,10 +17,10 @@ import ( // reload re-resolves the file document alone, so republishing that document // as it stands reverts each of these layers to its file value until the // process restarts (archie-core-ju85). -func (b *boot) runtimeConfig(ctx context.Context, base config.Config) (config.Config, error) { +func (b *boot) runtimeConfig(ctx context.Context, base config.Config) (config.Config, map[string]int64, error) { cfg, versions, err := b.controlPlane.RuntimeConfig(ctx, base) if err != nil { - return config.Config{}, err + return config.Config{}, nil, err } if settings := b.executionSettings.Load(); settings != nil { applyExecutionBudgets(&cfg, *settings) @@ -27,17 +28,17 @@ func (b *boot) runtimeConfig(ctx context.Context, base config.Config) (config.Co if err := configuration.Validate(&cfg); err != nil { wrapped := fmt.Errorf("validate database settings: %w", err) b.reportApplied(ctx, versions, wrapped) - return config.Config{}, wrapped + return config.Config{}, nil, wrapped } // The State Store persists source references, while openStores resolved // only the file snapshot. Layering provider-settings restores the source // references, so resolve the effective map before any runtime consumes it. if err := resolveProviderSecrets(&cfg, b.secrets, b.log); err != nil { b.reportApplied(ctx, versions, err) - return config.Config{}, err + return config.Config{}, nil, err } b.reportApplied(ctx, versions, nil) - return cfg, nil + return cfg, versions, nil } // reportApplied publishes the version of each kind this process just layered @@ -50,12 +51,17 @@ func (b *boot) reportApplied(ctx context.Context, versions map[string]int64, app } func (b *boot) loadRuntimeConfig(ctx context.Context) error { - cfg, err := b.runtimeConfig(ctx, b.cfg) + cfg, versions, err := b.runtimeConfig(ctx, b.cfg) if err != nil { return err } b.cfg = cfg b.cfgHolder.Set(cfg) + // The versions boot layered in are the resume points the runtime-resource + // watches start from: a watch re-established after a version it already + // applied neither replays a document this process handled nor skips one + // it has not. + b.runtimeVersions = versions return nil } @@ -75,7 +81,7 @@ func (b *boot) reloadConfig(ctx context.Context, doc *configuration.Document) er // surface as a failed reload rather than a SIGHUP that never returns. queryCtx, cancel := context.WithTimeout(ctx, 10*time.Second) defer cancel() - cfg, err := b.runtimeConfig(queryCtx, doc.Config) + cfg, _, err := b.runtimeConfig(queryCtx, doc.Config) if err != nil { return fmt.Errorf("runtime settings unavailable: %w", err) } @@ -224,3 +230,122 @@ func applyExecutionBudgets(cfg *config.Config, settings workflow.ExecutionSettin cfg.Identities[i].Budgets = cfg.Budgets } } + +// startLiveSettings starts everything a live control-plane update needs +// established before Run continues: the workflow-execution-settings watch, +// whose limits the layering applies, and one watch per runtime-resource kind +// (control_plane.go, runtimeResourceKinds). Both first reads are synchronous, +// so a control plane that cannot be watched at all fails the boot that asked +// for it rather than leaving the process running settings it can no longer +// update. +func (b *boot) startLiveSettings(ctx context.Context) error { + if err := b.startWorkflowExecutionSettings(ctx); err != nil { + return fmt.Errorf("workflow execution settings: %w", err) + } + if err := b.startRuntimeResourceWatches(ctx, b.runtimeVersions); err != nil { + return fmt.Errorf("runtime resource watches: %w", err) + } + return nil +} + +// runtimeResourceKinds are the control-plane kinds this process re-layers +// live: on a new stored version the watch re-runs the layering a reload runs +// (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 +// workflow-execution-settings watch established. +var runtimeResourceKinds = []string{ + controlplane.ProviderSettingsKind, + controlplane.ModelRoleAssignmentsKind, + controlplane.RepositoryPoliciesKind, + controlplane.SchedulingPolicyKind, +} + +// startRuntimeResourceWatches keeps a watch per live kind established for the +// life of the process. versions carries the resume point each kind starts +// from, the versions boot's layering recorded. The first stream per kind is +// opened synchronously, so a control plane that cannot be watched at all +// fails the boot that asked for it; after that the watch does not return, it +// reconnects (see keepWatch, whose backoff rules these watches ride). +func (b *boot) startRuntimeResourceWatches(ctx context.Context, versions map[string]int64) error { + for _, kind := range runtimeResourceKinds { + updates, err := b.controlPlane.WatchResource(ctx, kind, versions[kind]) + if err != nil { + return fmt.Errorf("watch %s: %w", kind, err) + } + go keepWatch(ctx, b.log, kind, versions[kind], updates, + func(ctx context.Context, afterVersion int64) (<-chan controlplane.AppliedResource, error) { + return b.controlPlane.WatchResource(ctx, kind, afterVersion) + }, + waitFor, + func(update controlplane.AppliedResource) int64 { return update.Version }, + func(update controlplane.AppliedResource) { b.applyRuntimeResourceUpdate(ctx, kind, update) }) + } + return nil +} + +// applyRuntimeResourceUpdate re-runs the layering a reload runs and +// republishes the result through config.Holder. The base is the published +// snapshot rather than the boot struct: reloadConfig publishes through the +// same holder and does not update the boot config, so the holder is the one +// view that is current in every path. The layering reads every kind from the +// store over it, so a scheduling-policy document written during this +// process's life and every other kind's last stored value land together, and +// the merge is idempotent (every kind it reads replaces its fields). +// +// The published snapshot is replaced only after the same check the reload +// and the boot layering pass: on a validation failure nothing is published, +// the previous settings keep running (last-known-good), and the failure is +// reported through apply status, which keeps the version still live on the +// record. A refused update therefore reaches the settings page the way a +// refused workflow-execution-settings update does +// (docs/prds/control-plane-apply-status.md). +func (b *boot) applyRuntimeResourceUpdate(ctx context.Context, kind string, update controlplane.AppliedResource) { + if update.Err != nil { + // A stream failure carries no version at all (versions start at 1, + // store.PutResource), and a process must never report an unreachable + // store as its own refusal; the reconnect is keepWatch's business. + if update.Version > 0 { + b.applyStatus.Report(ctx, kind, update.Version, update.Err) + } + b.log.Error("runtime settings watch failed", "kind", kind, "err", update.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) + cfg, _, err := b.runtimeConfig(ctx, base) + if err != nil { + // runtimeConfig reported the refusal through apply status for every + // kind it layers, keeping the version each of them last applied. + b.log.Error("runtime settings update rejected; the running settings stay", "kind", kind, "version", update.Version, "err", err) + return + } + b.publishConfig(ctx, cfg) + b.log.Info("runtime settings applied", "kind", kind, "version", update.Version) + switch kind { + case controlplane.ProviderSettingsKind, controlplane.ModelRoleAssignmentsKind: + b.rebuildChatModelRuntime(cfg) + } +} + +// 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. +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) + b.log.Info("chat model runtime rebuilt", "providers", len(cfg.Providers), "models", len(cfg.Models)) +} diff --git a/internal/app/archied/control_plane_live_apply_test.go b/internal/app/archied/control_plane_live_apply_test.go index a4fbe5144..d97f89bbb 100644 --- a/internal/app/archied/control_plane_live_apply_test.go +++ b/internal/app/archied/control_plane_live_apply_test.go @@ -151,6 +151,9 @@ type watchStreamStub struct { grpc.ClientStream responses []*pb.WatchResponse next int + // onDeliver, when set, runs as the stream delivers each response, so a + // stub standing in for the store can store what it just delivered. + onDeliver func() } func (s *watchStreamStub) Recv() (*pb.WatchResponse, error) { @@ -159,6 +162,9 @@ func (s *watchStreamStub) Recv() (*pb.WatchResponse, error) { } response := s.responses[s.next] s.next++ + if s.onDeliver != nil { + s.onDeliver() + } return response, nil } diff --git a/internal/app/archied/control_plane_resources_test.go b/internal/app/archied/control_plane_resources_test.go new file mode 100644 index 000000000..7295d03d6 --- /dev/null +++ b/internal/app/archied/control_plane_resources_test.go @@ -0,0 +1,242 @@ +package archied + +import ( + "context" + "encoding/json" + "slices" + "strings" + "testing" + "time" + + "google.golang.org/grpc" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" + + "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/secret" +) + +// resourceWatchStub answers Query with one stored version per kind and Watch +// with the documents queued for the watched kind. It is the store end of the +// seam the runtime-resource watch meets a live update through, and it is the +// store: delivering a document stores it, so the layering the apply runs +// reads the update back from Query the way production does. A kind the map +// does not carry is answered codes.NotFound, the state a skipped seed leaves +// behind. +type resourceWatchStub struct { + values map[string]any + // version is the stored version until a watch delivers an update, which + // is the version the store then answers Query with -- the apply the + // delivery triggers layers and reports the version the store now holds. + version int64 + // storedVersion, when present, is the version Query answers a kind with. + storedVersion map[string]int64 + // watch queues, per kind, the documents a live write delivers after the + // stored version, one per stream: the first open delivers the first + // document, the second open the second, and so on. + watch map[string][]string + // opens counts how often each kind's stream was opened, so queued + // documents are delivered in order across the reconnects keepWatch runs. + opens map[string]int +} + +func (s *resourceWatchStub) versionOf(kind string) int64 { + if stored, ok := s.storedVersion[kind]; ok { + return stored + } + return s.version +} + +func (*resourceWatchStub) Catalog(context.Context, *pb.CatalogRequest, ...grpc.CallOption) (*pb.CatalogResponse, error) { + return &pb.CatalogResponse{}, nil +} + +func (s *resourceWatchStub) Query(_ context.Context, request *pb.QueryRequest, _ ...grpc.CallOption) (*pb.QueryResponse, error) { + value, ok := s.values[request.Kind] + if !ok { + return nil, status.Error(codes.NotFound, "resource not found") + } + encoded, err := json.Marshal(value) + return &pb.QueryResponse{Resource: &pb.Resource{Kind: request.Kind, Version: s.versionOf(request.Kind), ValueJson: encoded}}, err +} + +func (s *resourceWatchStub) Watch(_ context.Context, request *pb.WatchRequest, _ ...grpc.CallOption) (grpc.ServerStreamingClient[pb.WatchResponse], error) { + // One queued document per stream: a stream ends after the document it + // carries, and the next one arrives on the reconnect -- the shape a store + // whose writes are spaced apart produces, and the shape that keeps the + // apply each delivery triggers reading the document back from Query + // before the store has moved on to the next one. + open := s.opens[request.Kind] + s.opens[request.Kind] = open + 1 + if open >= len(s.watch[request.Kind]) { + return &watchStreamStub{}, nil + } + document := s.watch[request.Kind][open] + version := s.version + int64(open) + 1 + if version <= request.AfterVersion { + return &watchStreamStub{}, nil + } + // The stub is the store: a document is stored when the stream delivers + // it, so the apply that delivery triggers layers the document back from + // Query. + response := &pb.WatchResponse{Resource: &pb.Resource{ + Kind: request.Kind, Version: version, ValueJson: []byte(document), + }} + return &watchStreamStub{responses: []*pb.WatchResponse{response}, onDeliver: func() { + s.values[request.Kind] = json.RawMessage(document) + s.storedVersion[request.Kind] = version + }}, nil +} + +func (*resourceWatchStub) History(context.Context, *pb.HistoryRequest, ...grpc.CallOption) (*pb.HistoryResponse, error) { + panic("unexpected History") +} + +func (*resourceWatchStub) Audit(context.Context, *pb.AuditRequest, ...grpc.CallOption) (*pb.AuditResponse, error) { + return &pb.AuditResponse{}, nil +} + +func (*resourceWatchStub) Command(context.Context, *pb.CommandRequest, ...grpc.CallOption) (*pb.CommandResponse, error) { + panic("unexpected Command") +} + +// newResourceWatchBoot builds a boot whose apply status lands in a recorder, +// with the chat model runtime a provider or role update must rebuild. +func newResourceWatchBoot(t *testing.T, stub *resourceWatchStub) (*boot, *applyStatusRecorder) { + t.Helper() + b, recorder := newLiveApplyBoot(t, fileConfig()) + b.controlPlane = controlplane.NewRPCClient(stub) + b.secrets = secret.NewRegistry() + b.chatModels = newChatModelManager(fileConfig().Models) + b.setLLM(agentexec.NewRuntime(executionProviders(fileConfig()))) + return b, recorder +} + +// schedulingDocument renders a scheduling-policy document the layering reads +// back, so the applied and refused updates in these tests cannot disagree on +// what "the stored scheduling policy" is. +func schedulingDocument(interval string) string { + return `{"poll_interval": "` + interval + `", "max_retries": 7, "dispatch": {"trigger": "assignee"}}` +} + +// TestRuntimeResourceWatchReLayersTheStoredChangeAndRepublishes is the live +// apply for the four kinds the daemon watches (archie-core-zfb0.1): a new +// stored version of scheduling-policy re-runs the layering a reload runs and +// republishes through config.Holder, so the change takes effect without a +// restart, the apply status records the version that was applied, and every +// other database-owned setting the layering read is still in the running +// config. +func TestRuntimeResourceWatchReLayersTheStoredChangeAndRepublishes(t *testing.T) { + values := databaseOwnedResources() + stub := &resourceWatchStub{values: values, version: 3, storedVersion: map[string]int64{}, opens: map[string]int{}, watch: map[string][]string{ + controlplane.SchedulingPolicyKind: {schedulingDocument("5m")}, + }} + b, status := newResourceWatchBoot(t, stub) + if err := b.loadRuntimeConfig(t.Context()); err != nil { + t.Fatalf("loadRuntimeConfig: %v", err) + } + + ctx, cancel := context.WithCancel(t.Context()) + defer cancel() + if err := b.startRuntimeResourceWatches(ctx, b.runtimeVersions); err != nil { + t.Fatalf("startRuntimeResourceWatches: %v", err) + } + // One record for boot's layering, one for the watched update. + records := status.awaitCount(t, controlplane.SchedulingPolicyKind, 2) + + cfg := b.cfgHolder.Get() + if got := time.Duration(cfg.PollInterval); got != 5*time.Minute { + t.Errorf("running PollInterval = %s, want the watched update (5m)", got) + } + if got := cfg.Repos[0].Name; got != "from-database" { + t.Errorf("running Repos[0] = %q, want the other kinds' last values to survive the re-layering", got) + } + last := records[len(records)-1] + if last.AppliedVersion != stub.version+1 { + t.Errorf("apply status version = %d, want the delivered version %d", last.AppliedVersion, stub.version+1) + } + if last.Error != "" { + t.Errorf("apply status error = %q, want none for an applied update", last.Error) + } +} + +// TestRuntimeResourceWatchKeepsLastKnownGoodWhenTheUpdateIsRefused: an update +// the layered document cannot run is refused before it is published, the +// running config keeps the last version that was applied, and the refusal is +// reported through apply status against the version still live. +func TestRuntimeResourceWatchKeepsLastKnownGoodWhenTheUpdateIsRefused(t *testing.T) { + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 3, storedVersion: map[string]int64{}, opens: map[string]int{}, watch: map[string][]string{ + controlplane.SchedulingPolicyKind: {schedulingDocument("5m"), schedulingDocument("0s")}, + }} + b, status := newResourceWatchBoot(t, stub) + if err := b.loadRuntimeConfig(t.Context()); err != nil { + t.Fatalf("loadRuntimeConfig: %v", err) + } + + ctx, cancel := context.WithCancel(t.Context()) + defer cancel() + if err := b.startRuntimeResourceWatches(ctx, b.runtimeVersions); err != nil { + t.Fatalf("startRuntimeResourceWatches: %v", err) + } + // One record for boot's layering, one for the applied update, one for the + // refusal. The recorder keeps the version that is still live on a refusal, + // so the third record carries the second update's version. + records := status.awaitCount(t, controlplane.SchedulingPolicyKind, 3) + + if got := time.Duration(b.cfgHolder.Get().PollInterval); got != 5*time.Minute { + t.Errorf("running PollInterval = %s, want the last update that validated (5m)", got) + } + last := records[len(records)-1] + if last.AppliedVersion != stub.version+1 { + t.Errorf("apply status version = %d, want the version still live (%d)", last.AppliedVersion, stub.version+1) + } + if !strings.Contains(last.Error, "poll_interval must be positive") { + t.Errorf("apply status error = %q, want it to carry the refusal", last.Error) + } +} + +// TestLiveModelRoleUpdateRebuildsTheChatModelRuntime: providers and model +// role assignments also feed the gateway chat runtime, so an update to either +// kind swaps the runtime (ai-sdk's Runtime caches the provider instances it +// built) and re-derives the model list the chat surfaces offer. +func TestLiveModelRoleUpdateRebuildsTheChatModelRuntime(t *testing.T) { + tests := []struct { + name string + kind string + }{ + {"a provider settings update", controlplane.ProviderSettingsKind}, + {"a model role assignments update", controlplane.ModelRoleAssignmentsKind}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + values := databaseOwnedResources() + values[controlplane.ModelRoleAssignmentsKind] = map[string]string{ + "builder": "main/db-model", "chat": "main/db-model", + } + 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) + } + before := b.chatLLM() + + b.applyRuntimeResourceUpdate(t.Context(), tt.kind, controlplane.AppliedResource{Version: 4}) + + if after := b.chatLLM(); after == before { + t.Error("the chat runtime was not rebuilt; the next turn keeps the previous provider set") + } + if !slices.Contains(b.chatModels.Models(), "main/db-model") { + t.Errorf("chat models = %v, want the new role assignment's reference", b.chatModels.Models()) + } + if got := b.chatModels.ActiveModel(); got != "main/db-model" { + t.Errorf("chat active model = %q, want the chat role's model after the update", got) + } + // The running config carries the update, not just the chat runtime. + if got := b.cfgHolder.Get().Models["chat"]; got != "main/db-model" { + t.Errorf("running chat role = %q, want the applied assignment", got) + } + }) + } +} diff --git a/internal/app/archied/gateway_runtime.go b/internal/app/archied/gateway_runtime.go index f674cee6c..3182ce725 100644 --- a/internal/app/archied/gateway_runtime.go +++ b/internal/app/archied/gateway_runtime.go @@ -21,7 +21,7 @@ func (b *boot) setupChatRuntime(ctx context.Context, cfg config.Config) error { // Created before the router so the LLMResponder can be wired in for // non-command message processing. providers := executionProviders(cfg) - b.llm = agentexec.NewRuntime(providers) + b.setLLM(agentexec.NewRuntime(providers)) b.toolReg = tools.NewRegistry() chatModels := newChatModelManager(cfg.Models, cfg.Chat.Models, b.catalogModels) chatModels.ApplyModelCatalog(b.catalog) @@ -119,7 +119,7 @@ func (b *boot) setupGatewayChat(ctx context.Context, actor gateway.ChatTaskActor configureTaskCommands(router, b.chatTasks, b.chatController, chatTaskListerAdapter{tasks: b.stateStore.Tasks}, b.defaultChatIdentity) router.Health = b.statusHealth setup := chatSetup{ - Cfg: config.NewHolder(cfg), LLM: b.llm, ChatModels: b.chatModels, ToolReg: b.toolReg, + Cfg: config.NewHolder(cfg), 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}, diff --git a/internal/app/archied/main.go b/internal/app/archied/main.go index 4201ae755..65ba53618 100644 --- a/internal/app/archied/main.go +++ b/internal/app/archied/main.go @@ -379,8 +379,8 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence b.log.Error("runtime settings unavailable", "err", err) return 1 } - if err := b.startWorkflowExecutionSettings(ctx); err != nil { - b.log.Error("workflow execution settings unavailable", "err", err) + if err := b.startLiveSettings(ctx); err != nil { + b.log.Error("live settings unavailable", "err", err) return 1 } go b.applyStatus.Run(ctx) @@ -494,7 +494,11 @@ func (s curatorEventSink) Emit(kind, detail string, data map[string]any) { // declared set is converted to a runnable core.ToolSet rather than a // parallel catalogue. type curatorLLMRunner struct { - rt *runtime.Runtime + // llm resolves the runtime at each call, so a live model-settings update + // that swaps it wholesale is the one the next curator run reads; a + // snapshot taken at construction would keep curators on the providers + // boot started with. + llm func() *runtime.Runtime // outcomes records this call for /status alongside sendChatTurn's. A // curator call is a model call this process made, and it does not pass // through sendChatTurn, so without this a daemon whose only recent model @@ -509,7 +513,11 @@ func (r curatorLLMRunner) Chat(ctx context.Context, req curator.ChatRequest) (cu // nil *runtime.Runtime panics on the first method call. A curator asking // for a completion on a daemon with no providers is a misconfiguration, // not a reason to take the process down. - if r.rt == nil { + if r.llm == nil { + return curator.ChatResult{}, fmt.Errorf("curator chat: no model runtime is configured") + } + llm := r.llm() + if llm == nil { return curator.ChatResult{}, fmt.Errorf("curator chat: no model runtime is configured") } msgs := make([]chat.Message, 0, len(req.Messages)) @@ -521,7 +529,7 @@ func (r curatorLLMRunner) Chat(ctx context.Context, req curator.ChatRequest) (cu r.outcomes.record(req.Model, err) return curator.ChatResult{}, err } - res, err := r.rt.Chat(ctx, req.Model, core.GenerateOptions{ + res, err := llm.Chat(ctx, req.Model, core.GenerateOptions{ Messages: msgs, Tools: toolSet, MaxSteps: max(req.MaxSteps, 1), diff --git a/internal/app/archied/status_health_test.go b/internal/app/archied/status_health_test.go index 3983d5bff..a3c9d26fe 100644 --- a/internal/app/archied/status_health_test.go +++ b/internal/app/archied/status_health_test.go @@ -16,6 +16,7 @@ import ( natsio "github.com/nats-io/nats.go" "github.com/samcharles93/ai-sdk/chat" "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/container" @@ -441,7 +442,7 @@ func TestCuratorRunnerRecordsItsOutcome(t *testing.T) { if rt == nil { t.Fatal("NewRuntime returned nil for a configured provider") } - runner := curatorLLMRunner{rt: rt, outcomes: recorder} + runner := curatorLLMRunner{llm: func() *runtime.Runtime { return rt }, outcomes: recorder} _, err := runner.Chat(context.Background(), curator.ChatRequest{Model: "openai/gpt-4o"}) if err == nil { @@ -470,7 +471,7 @@ func TestTitleGenerationDoesNotRecordChatModelHealth(t *testing.T) { if rt == nil { t.Fatal("NewRuntime returned nil for a configured provider") } - gen := &chatTitleGenerator{llm: rt, chatModels: newChatModelManager(map[string]string{"chat": "openai/gpt-4o"}, nil, nil)} + gen := &chatTitleGenerator{llm: func() *runtime.Runtime { return rt }, chatModels: newChatModelManager(map[string]string{"chat": "openai/gpt-4o"}, nil, nil)} if _, err := gen.GenerateTitle(context.Background(), "s1", "hello"); err == nil { t.Fatal("GenerateTitle against a closed port returned no error") diff --git a/internal/app/controlplane/client.go b/internal/app/controlplane/client.go index aa411513e..0d650114c 100644 --- a/internal/app/controlplane/client.go +++ b/internal/app/controlplane/client.go @@ -134,6 +134,33 @@ func (c *Client) WatchWorkflowExecutionSettings(ctx context.Context, afterVersio func(err error) AppliedSettings { return AppliedSettings{Err: err} }), nil } +// AppliedResource carries a watched resource's version only, without its +// document. The kinds applied with it are applied by re-running the whole +// layering, which reads every kind back from the store, so the document the +// stream carries would be decoded and then thrown away; a stored value this +// build cannot read is reported by the layering that refuses it (with +// last-known-good kept), not by the watch. +type AppliedResource struct { + Version int64 + Err error +} + +// WatchResource streams version updates for any resource kind without +// decoding the document. It is the shape the runtime-resource watches read +// (archie-core-zfb0.1): keepWatch reconnects on it exactly as it does on a +// typed stream, and the resume point still moves past a document the client +// refused to decode -- the store answered with that version, and resuming +// before it would re-offer it on every reconnect. +func (c *Client) WatchResource(ctx context.Context, kind string, afterVersion int64) (<-chan AppliedResource, error) { + stream, err := c.rpc.Watch(ctx, &pb.WatchRequest{Kind: kind, AfterVersion: afterVersion}) + if err != nil { + return nil, controlplanerpc.ClientError(err) + } + return watchUpdates(ctx, stream, + func(resource *pb.Resource) AppliedResource { return AppliedResource{Version: resource.Version} }, + func(err error) AppliedResource { return AppliedResource{Err: err} }), nil +} + type AppliedSettings struct { Settings workflow.ExecutionSettings Version int64 diff --git a/internal/app/controlplane/model_settings.go b/internal/app/controlplane/model_settings.go index 6cf221a9d..444130ad7 100644 --- a/internal/app/controlplane/model_settings.go +++ b/internal/app/controlplane/model_settings.go @@ -26,8 +26,8 @@ type providerDocument struct { func modelDefinitions() []Definition { return []Definition{ - {Kind: ProviderSettingsKind, Title: "Providers", ApplyMode: "restart-required", Document: map[string]providerDocument{}, Seed: seedProviders, Validate: validateProviders}, - {Kind: ModelRoleAssignmentsKind, Title: "Model role assignments", ApplyMode: "restart-required", Document: map[string]string{}, Seed: func(cfg config.Config) any { return cfg.Models }, Validate: validateModelRoles}, + {Kind: ProviderSettingsKind, Title: "Providers", ApplyMode: "live", Document: map[string]providerDocument{}, Seed: seedProviders, Validate: validateProviders}, + {Kind: ModelRoleAssignmentsKind, Title: "Model role assignments", ApplyMode: "live", Document: map[string]string{}, Seed: func(cfg config.Config) any { return cfg.Models }, Validate: validateModelRoles}, } } diff --git a/internal/app/controlplane/operational_settings.go b/internal/app/controlplane/operational_settings.go index 071abdca6..efd280eb1 100644 --- a/internal/app/controlplane/operational_settings.go +++ b/internal/app/controlplane/operational_settings.go @@ -41,9 +41,9 @@ type pluginSettings struct { func operationalDefinitions() []Definition { return []Definition{ - {Kind: RepositoryPoliciesKind, Title: "Repository policies", ApplyMode: "restart-required", Document: []config.Repo{}, Seed: func(cfg config.Config) any { return cfg.Repos }, Validate: validateRepositories}, + {Kind: RepositoryPoliciesKind, Title: "Repository policies", ApplyMode: "live", Document: []config.Repo{}, Seed: func(cfg config.Config) any { return cfg.Repos }, Validate: validateRepositories}, {Kind: ChannelSettingsKind, Title: "Channel settings", ApplyMode: "restart-required", Document: channelSettings{}, Seed: seedChannels, Validate: validateChannels, Normalize: normalizeChannels}, - {Kind: SchedulingPolicyKind, Title: "Scheduling policy", ApplyMode: "restart-required", Document: schedulingPolicy{}, Seed: func(cfg config.Config) any { + {Kind: SchedulingPolicyKind, Title: "Scheduling policy", ApplyMode: "live", Document: schedulingPolicy{}, Seed: func(cfg config.Config) any { return schedulingPolicy{PollInterval: cfg.PollInterval.Std().String(), MaxRetries: cfg.MaxRetries, Label: &cfg.Label, Dispatch: cfg.Dispatch} }, Validate: validateScheduling}, {Kind: ToolSettingsKind, Title: "Tool and MCP settings", ApplyMode: "restart-required", Document: toolSettings{}, Seed: seedTools, Validate: validateTools}, diff --git a/internal/app/controlplane/runtime_config.go b/internal/app/controlplane/runtime_config.go index 57f1b9012..8857c6850 100644 --- a/internal/app/controlplane/runtime_config.go +++ b/internal/app/controlplane/runtime_config.go @@ -113,7 +113,20 @@ func runtimeConfigFrom(ctx context.Context, reader controlplanerpc.ResourceReade }); err != nil { return config.Config{}, nil, err } - if err := layerResourceJSON(ctx, reader, versions, ModelRoleAssignmentsKind, &out.Models); err != nil { + // The stored role assignments own cfg.Models once the store carries a + // value, the way the provider layer above owns cfg.Providers: a role + // removed from the store is gone from the layered document too. The + // runtime-resource watches re-layer over an already-layered base + // (archie-core-zfb0.1), so json.Unmarshal's map merge here would + // resurrect a role the store deleted every time any watched kind changed. + if err := layerResource(ctx, reader, versions, ModelRoleAssignmentsKind, func(value []byte) error { + var roles map[string]string + if err := json.Unmarshal(value, &roles); err != nil { + return err + } + out.Models = roles + return nil + }); err != nil { return config.Config{}, nil, err } if err := layerResourceJSON(ctx, reader, versions, RepositoryPoliciesKind, &out.Repos); err != nil { diff --git a/internal/app/controlplane/runtime_config_test.go b/internal/app/controlplane/runtime_config_test.go index 9d6e09b08..51ad089b2 100644 --- a/internal/app/controlplane/runtime_config_test.go +++ b/internal/app/controlplane/runtime_config_test.go @@ -86,6 +86,28 @@ func TestRuntimeConfigUsesDatabaseResourcesAndPreservesBootstrapOnlySecrets(t *t } } +// TestRuntimeConfigReplacesStoredModelRolesEntirely: the stored role +// assignments own cfg.Models once the store carries a value, the way the +// provider settings own cfg.Providers, so a role removed from the store is +// gone from the layered document too. The runtime-resource watches re-layer +// over an already-layered base (archie-core-zfb0.1), so a merge here would +// resurrect a role the store deleted every time any watched kind changed. +func TestRuntimeConfigReplacesStoredModelRolesEntirely(t *testing.T) { + base := config.Config{Models: map[string]string{"builder": "old/model", "stale": "old/stale"}} + client := NewRPCClient(&runtimeConfigClient{values: map[string]any{ + ModelRoleAssignmentsKind: map[string]string{"builder": "main/model"}, + SchedulingPolicyKind: map[string]any{"poll_interval": "2m", "max_retries": 7, "dispatch": map[string]any{"trigger": "assignee"}}, + }}) + + got, _, err := client.RuntimeConfig(t.Context(), base) + if err != nil { + t.Fatalf("RuntimeConfig: %v", err) + } + if !reflect.DeepEqual(got.Models, map[string]string{"builder": "main/model"}) { + t.Fatalf("layered roles = %v, want the stored document alone", got.Models) + } +} + func TestRuntimeConfigRejectsStoredBootDerivedProviderName(t *testing.T) { stored := []byte(`{"openai":{"class":"openai","api_key_env":"ARCHIE_PROVIDER_6986D5A05E1DF674_API_KEY"}}`) if err := validateProviders(stored); err == nil { @@ -339,6 +361,35 @@ func populateEveryField(t *testing.T, value reflect.Value, label string) { // TestSchedulingPolicySeedCarriesTheLabel: the seed a fresh store writes must // carry the file document's label, so the pairing a stored trigger requires // is judgeable at write time from the moment the resource exists. +// TestRuntimeResourceKindsApplyLive pins the four kinds the daemon re-layers +// live (archie-core-zfb0.1) and the ones a startup-built consumer still +// freezes, so a flip in either direction is a deliberate edit to the +// definition, not a default that drifts. +func TestRuntimeResourceKindsApplyLive(t *testing.T) { + t.Parallel() + + registry, err := stepRegistry(testSteps(t)) + if err != nil { + t.Fatalf("build step registry: %v", err) + } + modes := make(map[string]string) + for _, definition := range builtinDefinitions(registry) { + modes[definition.Kind] = definition.ApplyMode + } + for _, kind := range []string{ + ProviderSettingsKind, ModelRoleAssignmentsKind, RepositoryPoliciesKind, SchedulingPolicyKind, + } { + if modes[kind] != "live" { + t.Errorf("%s applies %q, want live: the daemon re-layers this kind on a watch", kind, modes[kind]) + } + } + for _, kind := range []string{ToolSettingsKind, PluginSettingsKind, ContainerRuntimePoliciesKind, ChannelSettingsKind} { + if modes[kind] != "restart-required" { + t.Errorf("%s applies %q, want restart-required: a startup-built component still holds it", kind, modes[kind]) + } + } +} + func TestSchedulingPolicySeedCarriesTheLabel(t *testing.T) { server := testServer(t, nil) seed, err := server.definitions[SchedulingPolicyKind].seededValue(config.Config{