diff --git a/docs/architecture/configuration.md b/docs/architecture/configuration.md index 2bf507c31..a2accd77a 100644 --- a/docs/architecture/configuration.md +++ b/docs/architecture/configuration.md @@ -335,14 +335,19 @@ Two properties matter to anyone changing this area: query, so boot records the last published settings and the reload re-applies them from there. - **Live kinds arrive on a watch.** Provider settings, model role assignments, - repository policies, scheduling policy, plugin settings, review settings, - channel settings and container runtime policies are `ApplyMode: live`: the - daemon keeps a watch per kind (`boot.startRuntimeResourceWatches`, - `runtimeResourceKinds`) and, on a new version, re-runs `boot.runtimeConfig` - over the published snapshot and + repository policies, scheduling policy, tool settings, plugin settings, + review settings, channel settings and container runtime policies are + `ApplyMode: live`: the daemon keeps a watch per kind + (`boot.startRuntimeResourceWatches`, `runtimeResourceKinds`) and, on a new + version, re-runs `boot.runtimeConfig` over the published snapshot and republishes through `config.Holder`. A candidate the layered document cannot run is refused before it is published — last-known-good keeps running and - the refusal is reported through apply status. Container runtime policies + the refusal is reported through apply status. Tool settings reconcile in this + process: the daemon diffs the stored MCP server set against the running + providers — connecting added servers, disconnecting removed ones and + reconnecting changed ones while an unchanged server keeps running — and + rebuilds the `web_fetch` and `minimax` entries, whose config was captured at + construction (`boot.reconcileToolSettings`). Container runtime policies join the live set because their consumers re-read the published config: the container pool reads image, pull policy, network, max uptime and concurrency cap on every acquire and the daemon resizes its running task dispatcher from diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 5aae1a858..0344d42a0 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- **Live kinds arrive on a watch.** Provider settings, model role assignments,\n repository policies, scheduling policy, plugin settings, review settings,\n channel settings and container runtime policies are `ApplyMode: live`: the\n daemon keeps a watch per kind (`boot.startRuntimeResourceWatches`,\n `runtimeResourceKinds`) and, on a new version, re-runs `boot.runtimeConfig`\n 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. Container runtime policies\n join the live set because their consumers re-read the published config: the\n container pool reads image, pull policy, network, max uptime and concurrency\n cap on every acquire and the daemon resizes its running task dispatcher from\n the same publish; the fields the document cannot carry, `registry_auth`\n above all, stay boot-resolved and remain requires-restart. A kind whose\n consumer lives in another process reconciles there too: `archie-messaging`\n re-reads the stored channel settings on the apply-status restamp interval\n and restarts only the channel whose transport settings changed, while the\n listen addresses it has bound and the set of channels it composed stay\n process bindings that take effect on restart. A kind joins the live list\n only with a consumer that re-reads it; one whose startup-built consumer\n never does stays restart-required, and the model/provider half of the live\n set 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" + "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, scheduling policy, tool settings, plugin settings,\n review settings, channel settings and container runtime policies are\n `ApplyMode: live`: the daemon keeps a watch per kind\n (`boot.startRuntimeResourceWatches`, `runtimeResourceKinds`) 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. Tool settings reconcile in this\n process: the daemon diffs the stored MCP server set against the running\n providers — connecting added servers, disconnecting removed ones and\n reconnecting changed ones while an unchanged server keeps running — and\n rebuilds the `web_fetch` and `minimax` entries, whose config was captured at\n construction (`boot.reconcileToolSettings`). Container runtime policies\n join the live set because their consumers re-read the published config: the\n container pool reads image, pull policy, network, max uptime and concurrency\n cap on every acquire and the daemon resizes its running task dispatcher from\n the same publish; the fields the document cannot carry, `registry_auth`\n above all, stay boot-resolved and remain requires-restart. A kind whose\n consumer lives in another process reconciles there too: `archie-messaging`\n re-reads the stored channel settings on the apply-status restamp interval\n and restarts only the channel whose transport settings changed, while the\n listen addresses it has bound and the set of channels it composed stay\n process bindings that take effect on restart. A kind joins the live list\n only with a consumer that re-reads it; one whose startup-built consumer\n never does stays restart-required, and the model/provider half of the live\n set 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/", @@ -424,7 +424,7 @@ "url": "/dev/prds/pr-review-operator-response/", "title": "PR review: the operator's answer to the approval gate", "section": "PRDs", - "body": "# PR review: the operator's answer to the approval gate\n\n**Status:** Draft\n**Authority:** `docs/prds/pr-review-agent.md` (\"Operator approval\") for the gate, and `docs/prds/state-store-contract.md` (rev. 2e) for every task field that crosses the State Store.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a run cannot resume partway through its stage list).\n\n## Decision 1 — where the operator answers\n\nThe dashboard's `POST /api/tasks/{id}/action` (`internal/webui/api_tasks.go`, `handleTaskAction`) is the authoritative surface: the only one that resolves the actor from a credential and can carry a payload. Chat is a shortcut, not a second authority — `/approve` (`internal/gateway/gateway.go`, `Router.handleApprove`) answers the post decision with every offered finding selected, and gains no instruction or selection syntax.\n\n`taskstate.Action` gains `rereview`, and `taskstate.Actions` returns `approve`, `reject` and `rereview` for `WaitingHuman`. `approve` posts the review, `reject` discards it through the existing terminal decline, `rereview` reruns the review phases with instructions. The action body carries `instructions`, required by `rereview`, and `findings`, the finding keys `approve` posts; an absent selection means all of them.\n\nThe path is `handleTaskAction` → `applyOperatorTaskAction` → `Chat.Contract.ApplyOperatorTaskAction` → the daemon's `LocalChatAdapter` → `taskactions.Client` (NATS `archie.gateway.task-action`) → `taskactions.Service.Apply` → one guarded store write that records the decision and requeues. Chat's `/approve` path (`StoreTaskController.Approve` → `chatTaskControllerAdapter.ApproveChatTask`) must reach that same write through the same function, so the two surfaces cannot record different decisions for one operator intent.\n\nA requeue resumes the workflow the waiting state names, never a name the handler hardcodes. `taskactions.Service.apply` and `chatTaskControllerAdapter.ApproveChatTask` requeue every approval under `implement`, which is the feasibility handoff: an approval whose wait recorded `pr-review` would run the implement workflow. Feasibility must keep that handoff by naming `implement` on the task before it enters the wait, which is the invariant the handler needs — the workflow a task carries is the workflow it runs next. `Requeue` treats an empty workflow as \"keep the task's\".\n\n### The review the operator answers\n\nThe gate writes the review it is holding onto the task before it ends the run: one JSON column, `review_gate`, a sibling of `review_payload`, holding the scored findings, the head SHA, the pull request's identity and the workflow the wait resumes. The run's existing `Store.Update` persists it. The same column carries the answer back: the response path's guarded write fills in the outcome, the selection and the instructions, and clears the offer for a re-review.\n\nThe operator reads the offer through the existing task read — `taskView.Task` on `GET /api/tasks` and `GET /api/tasks/{id}/debug` — so no new read endpoint is needed.\n\nThis record is load-bearing because the run that computed the findings ends at the gate and the engine cannot resume it partway. Without it, \"post the selected findings\" cannot mean the findings the operator saw: the resumed run recomputes them with agent calls. An `approve` resume therefore posts the recorded review filtered by the selection, and the review the resumed phases recompute never reaches the output.\n\n## Decision 2 — the cap\n\nThe cap is a column: `rereview_rounds` on `tasks`, `bigint NOT NULL DEFAULT 0`, read by the response path and incremented in the same guarded write that requeues a re-review. A re-review at the cap is refused with the conflict sentinel the dashboard answers 409 with, and nothing is requeued. Two is a constant in the domain, not a config knob: the PRD fixes it.\n\n`Task.Attempt` cannot carry the count, because it counts every requeue. The two alternatives are worse.\n\n- The execution tree measures passes through the gate, not operator requests. A crash recovery (`RecoverStale`) or an operator retry re-runs the pipeline to the gate and would consume the cap; and a stage has no step read (`task.Store` carries none), so this route needs a new interface method anyway.\n- `Task.Notes` is the agent memory ledger, not scratch. `AgentStage.buildRequest` passes it into every generic agent request, `agentexec` renders it as a prompt section, and `persistAppendedNotes` appends to it. A counter parsed out of a field agents write to is the encoded-state defect this repository rejects, and instructions parked there would reach every unrelated workflow's agents.\n\n`RemediationRounds` is the precedent: one writer, one reader, one meaning, kept separate from `RetryCount` so unrelated retries cannot draw a budget down.\n\nThe write crosses the State Store. A goose migration adds the column; `internal/infrastructure/postgres/queries/tasks.sql` and its sqlc output carry it; `internal/infrastructure/postgres/store.go` maps it; `proto/state/v1/state.proto` carries it as a new `Task` field with its regenerated contracts and `staterpc/values.go` mapping both ways; `internal/domain/workflow/task/task.go` declares it; `internal/infrastructure/taskactions/store.go` adds it to the `taskactions.Task` projection the response path reads. The write itself is a guarded requeue method beside `RetryTask`, which increments a counter, and `BeginRemediation`, which records a payload in the same transaction: one transition-table guard, one increment and one requeue in one write. It must join every column-listing query, which `docs/development/state-store.md` names.\n\nTests that prove it: the guarded write increments for a re-review and for no other requeue; a re-review at the cap is refused and leaves the task waiting; and the field survives the wire, which `TestTaskProtoCarriesEveryDomainField` asserts for every field of the domain task.\n\n## Decision 3 — how the instructions reach the stages\n\nThe recorded instructions enter the pipeline at phase 3 and phase 4 only, which is what the PRD asks for: a labelled operator-instructions block appended to `runLens`'s mission in `stagePRLenses` and to `runReviewer`'s mission.\n\nThey cannot ride `AgentStage.buildRequest`. Every pr-review stage builds its `agentexec.Request` in `runPRReviewAgentRecorded`, which sets no `Request.Notes`, so nothing the generic path threads reaches these calls. The pipeline restores the instructions from the task record at the same point it restores the review, and the two mission builders read them there.\n\n## The gate is not reachable from archie's own PRs\n\n`StagePRReviewAndOpenPR` splices `prReviewDecisionStages()`, the list `PRReview()` uses, so the gate is reachable from the implement workflow too. It must not be. The change is one entry moving: `stagePROperatorApproval()` leaves the shared list for `PRReview()`'s own stage list, immediately before the merge gate, and the own-PR splice keeps taking the shared list unchanged. This is a prerequisite for the response channel and a change of its own.\n\nThree reasons, the second deciding it alone.\n\n- The gate's question is which findings to post, and on archie's own PRs there is no pull request to post to at the point the splice reaches the gate. That trigger's human decision point is its park on an unchallenged blocking finding.\n- Approving a wait inside the implement workflow re-enters that workflow at its first stage against a worktree that already carries the change. A builder that then reports no changes sets `BuildNoChanges`, `StageCommitPush` calls `closeNoChangesIssue`, and the issue is closed with no pull request ever opened. Nothing the gate decides is worth a route to silently closing an issue.\n- Short-circuiting instead would put a conditional no-op in every stage whose work a wait had completed, which changes the resume semantics of the whole pipeline rather than this gate.\n\n## What a full restart gives, and what it costs\n\nA requeue re-runs the workflow's stage list from its first stage; the engine has no partway resume. That satisfies the PRD's \"reruns phases 3 to 8\" for free, and it is acceptable for the standalone pipeline precisely because that pipeline has no stage that writes and then closes. The costs:\n\n- Phases 1 and 2 recompute. Both are code except two agent calls — the machine-written score and the anatomy narrative — so those re-run, and a changed score can change whether the hallucination-check dimension is added.\n- The pull request's snapshot is checked out again.\n- The run's cost and wall-clock budgets are per attempt, so a re-review starts with a fresh allowance, which the cap bounds.\n\n## Verification\n\n- A gate wait on the standalone `pr-review` workflow answered `approve` posts exactly the findings the operator selected, and no finding the resumed phases produced.\n- A re-review at the cap is refused, the task stays waiting, and the count survives a store round trip.\n- A re-review's instructions reach the lens and reviewer missions; a first run's do not.\n- The gate is unreachable from the implement workflow's stage list.\n" + "body": "# PR review: the operator's answer to the approval gate\n\n**Status:** Draft\n**Authority:** `docs/prds/pr-review-agent.md` (\"Operator approval\") for the gate, and `docs/prds/state-store-contract.md` (rev. 2e) for every task field that crosses the State Store.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a run cannot resume partway through its stage list).\n\n## Decision 1 — where the operator answers\n\nThe dashboard's `POST /api/tasks/{id}/action` (`internal/webui/api_tasks.go`, `handleTaskAction`) is the authoritative surface: the only one that resolves the actor from a credential and can carry a payload. Chat is a shortcut, not a second authority — `/approve` (`internal/gateway/gateway.go`, `Router.handleApprove`) answers the post decision with every offered finding selected, and gains no instruction or selection syntax.\n\n`taskstate.Action` gains `rereview`, and `taskstate.Actions` returns `approve`, `reject` and `rereview` for `WaitingHuman`. `approve` posts the review, `reject` discards it through the existing terminal decline, `rereview` reruns the review phases with instructions. The action body carries `instructions`, required by `rereview`, and `findings`, the finding keys `approve` posts; an absent selection means all of them.\n\nThe path is `handleTaskAction` → `applyOperatorTaskAction` → `Chat.Contract.ApplyOperatorTaskAction` → the daemon's `LocalChatAdapter` → `taskactions.Client` (NATS `archie.gateway.task-action`) → `taskactions.Service.Apply` → one guarded store write that records the decision and requeues. Chat's `/approve` path (`StoreTaskController.Approve` → `chatTaskControllerAdapter.ApproveChatTask`) must reach that same write through the same function, so the two surfaces cannot record different decisions for one operator intent.\n\nA requeue resumes the workflow the waiting state names, never a name the handler hardcodes. `taskactions.Service.apply` and `chatTaskControllerAdapter.ApproveChatTask` requeue with an empty workflow, which `Requeue` reads as \"keep the task's\", so neither surface hardcodes a workflow name: an approval whose wait recorded `pr-review` resumes `pr-review`. The feasibility handoff therefore has to name `implement` on the task before it enters the wait, which is the invariant the handler relies on — the workflow a task carries is the workflow it runs next. `Requeue` treats an empty workflow as \"keep the task's\".\n\n### The review the operator answers\n\nThe gate writes the review it is holding onto the task before it ends the run: one JSON column, `review_gate`, a sibling of `review_payload`, holding the scored findings, the head SHA, the pull request's identity and the workflow the wait resumes. The run's existing `Store.Update` persists it. The same column carries the answer back: the response path's guarded write fills in the outcome, the selection and the instructions, and clears the offer for a re-review.\n\nThe operator reads the offer through the existing task read — `taskView.Task` on `GET /api/tasks` and `GET /api/tasks/{id}/debug` — so no new read endpoint is needed.\n\nThis record is load-bearing because the run that computed the findings ends at the gate and the engine cannot resume it partway. Without it, \"post the selected findings\" cannot mean the findings the operator saw: the resumed run recomputes them with agent calls. An `approve` resume therefore posts the recorded review filtered by the selection, and the review the resumed phases recompute never reaches the output.\n\n## Decision 2 — the cap\n\nThe cap is a column: `rereview_rounds` on `tasks`, `bigint NOT NULL DEFAULT 0`, read by the response path and incremented in the same guarded write that requeues a re-review. A re-review at the cap is refused with the conflict sentinel the dashboard answers 409 with, and nothing is requeued. Two is a constant in the domain, not a config knob: the PRD fixes it.\n\n`Task.Attempt` cannot carry the count, because it counts every requeue. The two alternatives are worse.\n\n- The execution tree measures passes through the gate, not operator requests. A crash recovery (`RecoverStale`) or an operator retry re-runs the pipeline to the gate and would consume the cap; and a stage has no step read (`task.Store` carries none), so this route needs a new interface method anyway.\n- `Task.Notes` is the agent memory ledger, not scratch. `AgentStage.buildRequest` passes it into every generic agent request, `agentexec` renders it as a prompt section, and `persistAppendedNotes` appends to it. A counter parsed out of a field agents write to is the encoded-state defect this repository rejects, and instructions parked there would reach every unrelated workflow's agents.\n\n`RemediationRounds` is the precedent: one writer, one reader, one meaning, kept separate from `RetryCount` so unrelated retries cannot draw a budget down.\n\nThe write crosses the State Store. A goose migration adds the column; `internal/infrastructure/postgres/queries/tasks.sql` and its sqlc output carry it; `internal/infrastructure/postgres/store.go` maps it; `proto/state/v1/state.proto` carries it as a new `Task` field with its regenerated contracts and `staterpc/values.go` mapping both ways; `internal/domain/workflow/task/task.go` declares it; `internal/infrastructure/taskactions/store.go` adds it to the `taskactions.Task` projection the response path reads. The write itself is a guarded requeue method beside `RetryTask`, which increments a counter, and `BeginRemediation`, which records a payload in the same transaction: one transition-table guard, one increment and one requeue in one write. It must join every column-listing query, which `docs/development/state-store.md` names.\n\nTests that prove it: the guarded write increments for a re-review and for no other requeue; a re-review at the cap is refused and leaves the task waiting; and the field survives the wire, which `TestTaskProtoCarriesEveryDomainField` asserts for every field of the domain task.\n\n## Decision 3 — how the instructions reach the stages\n\nThe recorded instructions enter the pipeline at phase 3 and phase 4 only, which is what the PRD asks for: a labelled operator-instructions block appended to `runLens`'s mission in `stagePRLenses` and to `runReviewer`'s mission.\n\nThey cannot ride `AgentStage.buildRequest`. Every pr-review stage builds its `agentexec.Request` in `runPRReviewAgentRecorded`, which sets no `Request.Notes`, so nothing the generic path threads reaches these calls. The pipeline restores the instructions from the task record at the same point it restores the review, and the two mission builders read them there.\n\n## The gate is not reachable from archie's own PRs\n\n`StagePRReviewAndOpenPR` splices `prReviewDecisionStages()`, the list `PRReview()` uses, so the gate is reachable from the implement workflow too. It must not be. The change is one entry moving: `stagePROperatorApproval()` leaves the shared list for `PRReview()`'s own stage list, immediately before the merge gate, and the own-PR splice keeps taking the shared list unchanged. This is a prerequisite for the response channel and a change of its own.\n\nThree reasons, the second deciding it alone.\n\n- The gate's question is which findings to post, and on archie's own PRs there is no pull request to post to at the point the splice reaches the gate. That trigger's human decision point is its park on an unchallenged blocking finding.\n- Approving a wait inside the implement workflow re-enters that workflow at its first stage against a worktree that already carries the change. A builder that then reports no changes sets `BuildNoChanges`, `StageCommitPush` calls `closeNoChangesIssue`, and the issue is closed with no pull request ever opened. Nothing the gate decides is worth a route to silently closing an issue.\n- Short-circuiting instead would put a conditional no-op in every stage whose work a wait had completed, which changes the resume semantics of the whole pipeline rather than this gate.\n\n## What a full restart gives, and what it costs\n\nA requeue re-runs the workflow's stage list from its first stage; the engine has no partway resume. That satisfies the PRD's \"reruns phases 3 to 8\" for free, and it is acceptable for the standalone pipeline precisely because that pipeline has no stage that writes and then closes. The costs:\n\n- Phases 1 and 2 recompute. Both are code except two agent calls — the machine-written score and the anatomy narrative — so those re-run, and a changed score can change whether the hallucination-check dimension is added.\n- The pull request's snapshot is checked out again.\n- The run's cost and wall-clock budgets are per attempt, so a re-review starts with a fresh allowance, which the cap bounds.\n\n## Verification\n\n- A gate wait on the standalone `pr-review` workflow answered `approve` posts exactly the findings the operator selected, and no finding the resumed phases produced.\n- A re-review at the cap is refused, the task stays waiting, and the count survives a store round trip.\n- A re-review's instructions reach the lens and reviewer missions; a first run's do not.\n- The gate is unreachable from the implement workflow's stage list.\n" }, { "url": "/dev/prds/pr-review-remediation/", diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index fde701270..c469b8cf2 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -289,7 +289,19 @@ type boot struct { curatorRuntime *curator.Runtime guardrails *tools.GuardrailEngine providerRegistry *toolprovider.Registry - d *daemon.Daemon + // mcpMu guards mcpApplied, which records the MCP servers the provider + // registry was last built from, keyed by configured name. A live + // tool-settings change diffs the stored server set against it so an + // unchanged server is left running and untouched (mcp_reconcile.go); the + // mutex is held because registerTools runs at boot while the + // control-plane watch may already be applying an update. + mcpMu sync.Mutex + mcpApplied map[string]appliedMCPServer + // mcpProvider builds the engine for one configured MCP server. Nil uses + // configuredMCPProvider; a test injects a fake so the live reconciliation + // can run without spawning a server process. + mcpProvider func(config.MCPServer) (toolprovider.Engine, error) + d *daemon.Daemon // schedulingEngine is the cron/scheduling ticker engine (setupScheduling). // Nil when no chat task creator is configured, in which case startServices // leaves it unstarted rather than running with no reachable job kind. @@ -1408,8 +1420,14 @@ func (b *boot) setupGuardrails() { // built per turn onto the resolved Subject's scopes // (internal/gateway/turn_memory_tool.go), not once at boot. func (b *boot) registerTools(ctx context.Context) error { - cfg, log := b.cfg, b.log + // The running config, not b.cfg: boot is where the first stored version of + // every kind was already layered in, and a watch that applied a later one + // before this point published through the holder. + cfg, log := b.cfgHolder.Get(), b.log b.providerRegistry = toolprovider.NewRegistry(b.toolReg) + b.mcpMu.Lock() + b.mcpApplied = make(map[string]appliedMCPServer, len(cfg.Tools.MCPServers)) + b.mcpMu.Unlock() // Workspace file and shell tools. Registered only when a workspace is // configured: these read, write and execute, so the directory is a // deliberate choice rather than a default. @@ -1428,7 +1446,7 @@ func (b *boot) registerTools(ctx context.Context) error { log.Info("workspace tools disabled (chat.workspace is unset)") } for _, srv := range cfg.Tools.MCPServers { - provider, err := configuredMCPProvider(srv, cfg.WorkDir, b.mcpSamplingHandler()) + provider, err := b.buildMCPProvider(srv) if err != nil { log.Warn("mcp tool provider skipped", "name", srv.Name, "err", err) continue @@ -1443,6 +1461,9 @@ func (b *boot) registerTools(ctx context.Context) error { log.Warn("mcp tool provider skipped", "name", srv.Name, "err", err) continue } + b.mcpMu.Lock() + b.mcpApplied[strings.TrimSpace(srv.Name)] = appliedMCPServer{server: srv, id: provider.Manifest().ID} + b.mcpMu.Unlock() } if err := b.capabilityHost.Register(b.providerRegistry); err != nil { log.Error("tool-provider capability registration failed", "err", err) @@ -1492,21 +1513,7 @@ func (b *boot) registerStandaloneTools() { // web_fetch. Registered directly rather than as a tool provider: it has // no process to start or stop, so the provider lifecycle would buy // nothing. Disabled by configuration returns nil and advertises nothing. - if entry := webfetch.Tool(webfetch.Config{ - Enabled: cfg.Tools.WebFetch.IsEnabled(), - Timeout: cfg.Tools.WebFetch.Timeout.Std(), - MaxBytes: cfg.Tools.WebFetch.MaxBytes, - AllowPrivateNetworks: cfg.Tools.WebFetch.AllowPrivateNetworks, - }); entry != nil { - if err := b.toolReg.Register(*entry); err != nil { - log.Warn("web_fetch registration failed", "err", err) - } else { - log.Info("web fetch enabled", - "allow_private_networks", cfg.Tools.WebFetch.AllowPrivateNetworks) - } - } else { - log.Info("web fetch disabled") - } + b.registerWebFetchTool(cfg) // send_file. Rooted at the same workspace as the file tools and gated // by the same confinement, because it hands a host file to an outbound @@ -1525,6 +1532,30 @@ func (b *boot) registerStandaloneTools() { b.registerMinimaxTool(cfg, log) } +// registerWebFetchTool registers web_fetch from cfg. Split out of +// registerStandaloneTools because a live tool-settings change rebuilds the +// entry: the one a boot built captured its config at construction, so it +// cannot read a changed value per call. +func (b *boot) registerWebFetchTool(cfg config.Config) { + log := b.log + entry := webfetch.Tool(webfetch.Config{ + Enabled: cfg.Tools.WebFetch.IsEnabled(), + Timeout: cfg.Tools.WebFetch.Timeout.Std(), + MaxBytes: cfg.Tools.WebFetch.MaxBytes, + AllowPrivateNetworks: cfg.Tools.WebFetch.AllowPrivateNetworks, + }) + if entry == nil { + log.Info("web fetch disabled") + return + } + if err := b.toolReg.Register(*entry); err != nil { + log.Warn("web_fetch registration failed", "err", err) + return + } + log.Info("web fetch enabled", + "allow_private_networks", cfg.Tools.WebFetch.AllowPrivateNetworks) +} + // registerMinimaxTool registers generate_video. Off by default -- see // MinimaxConfig's doc comment, it spends real API credits per call -- and, // unlike web_fetch, needs a resolved credential before it can be diff --git a/internal/app/archied/chat_setup.go b/internal/app/archied/chat_setup.go index a8410eaa3..6036246fd 100644 --- a/internal/app/archied/chat_setup.go +++ b/internal/app/archied/chat_setup.go @@ -12,6 +12,7 @@ import ( "github.com/samcharles93/ai-sdk/core" "github.com/samcharles93/ai-sdk/runtime" + "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/daemon" "github.com/samcharles93/archie-core/internal/domain/messaging" @@ -30,6 +31,10 @@ type chatSetup struct { // running yet at this point, so the reload-safe Holder is mostly a // formality, but matching the daemon's API keeps callers honest. Cfg *config.Holder + // ToolLimits resolves the tool-output policy at each turn, so a live + // tool-settings update reaches the next chat turn's tool options rather + // than the value captured when the runner was built. + ToolLimits func() agentexec.ToolLimits // LLM resolves the provider runtime at each use: a live provider-settings // or model-role-assignments update swaps the runtime wholesale (ai-sdk's // Runtime caches the provider instances it built), so the pointer cannot @@ -182,7 +187,7 @@ func newChatTurnRunner( Sessions: sessionStore, Models: s.ChatModels, Personas: s.Personas, - Model: newChatTurnModel(s.LLM, s.ToolReg, cfg.Chat.MaxSteps, toolLimits(cfg), s.ProviderOutcomes), + Model: newChatTurnModel(s.LLM, s.ToolReg, cfg.Chat.MaxSteps, s.ToolLimits, s.ProviderOutcomes), TaskLister: s.ChatTaskLister, Tasks: s.ChatTasks, TaskLogs: s.ChatTaskLogs, diff --git a/internal/app/archied/chat_turn_model.go b/internal/app/archied/chat_turn_model.go index f0f9dfb3b..754a61dc6 100644 --- a/internal/app/archied/chat_turn_model.go +++ b/internal/app/archied/chat_turn_model.go @@ -23,7 +23,10 @@ type chatTurnModel struct { llm func() *runtime.Runtime registry *tools.Registry maxSteps int - limits agentexec.ToolLimits + // limits resolves the tool-output policy at each turn, so a live + // tool-settings update is the policy the next turn builds its tool options + // with; a snapshot taken at construction would keep the boot limits. + limits func() agentexec.ToolLimits // outcomes records each call's result for /status (see sendChatTurn). outcomes *providerOutcomeRecorder } @@ -32,7 +35,7 @@ func newChatTurnModel( llm func() *runtime.Runtime, registry *tools.Registry, maxSteps int, - limits agentexec.ToolLimits, + limits func() agentexec.ToolLimits, outcomes *providerOutcomeRecorder, ) gateway.TurnModel { return &chatTurnModel{ @@ -48,7 +51,11 @@ func (m *chatTurnModel) Prepare( ctx context.Context, req gateway.TurnPrepareContext, ) (gateway.PreparedTurnModel, error) { - options, err := chatGenerateOptions(ctx, nil, m.registry, m.maxSteps, m.limits, req.Extra, req.ContextWindow) + limits := agentexec.ToolLimits{} + if m.limits != nil { + limits = m.limits() + } + options, err := chatGenerateOptions(ctx, nil, m.registry, m.maxSteps, limits, req.Extra, req.ContextWindow) if err != nil { return nil, err } diff --git a/internal/app/archied/control_plane.go b/internal/app/archied/control_plane.go index ac235f54b..f55a2e02a 100644 --- a/internal/app/archied/control_plane.go +++ b/internal/app/archied/control_plane.go @@ -264,26 +264,30 @@ func (b *boot) startLiveSettings(ctx context.Context) error { // (b.runtimeConfig, which applies the execution budgets the settings watch // published) and republishes through config.Holder, so the change takes // effect without a restart. Kinds stay out of this list while a -// startup-built component still holds their value -- tool -// 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. ContainerRuntimePoliciesKind is on the list because both consumers +// startup-built component still holds their value; none does today, so the +// list is every control-plane kind. A kind joins it only with a consumer that +// re-reads it. ToolSettingsKind is on it because applyRuntimeResourceUpdate +// reconciles the MCP provider set and rebuilds the two config-derived tool +// entries (boot.reconcileToolSettings, its consumer); a removed MCP server +// really disconnects, because it is a child process with a Stop, not a Yaegi +// interpreter. ContainerRuntimePoliciesKind is on it because both consumers // re-read the published config: the container pool takes its image, pull -// policy, network, max-uptime and concurrency cap per acquire, and the -// daemon's dispatcher is resized after the publish (applyRuntimeResourceUpdate -// below). PluginSettingsKind is on the list because its only consumer is the -// directory reconciliation, which reads the running config each tick; a -// removed plugin or engine still cannot unload, so that kind reports the -// removal rather than requiring a restart. ChannelSettingsKind is on the list -// for this process's own re-layer; the Messaging Service, which owns the -// channel transports, reconciles them separately and restarts only the -// channel whose settings changed. Each kind is watched in its own goroutine, -// exactly the shape the workflow-execution-settings watch established. +// policy, network, max-uptime and concurrency cap per acquire, and the daemon's +// dispatcher is resized after the publish (applyRuntimeResourceUpdate below). +// PluginSettingsKind is on the list because its only consumer is the directory +// reconciliation, which reads the running config each tick; a removed plugin +// or engine still cannot unload, so that kind reports the removal rather than +// requiring a restart. ChannelSettingsKind is on the list for this process's +// own re-layer; the Messaging Service, which owns the channel transports, +// reconciles them separately and restarts only the channel whose settings +// changed. Each kind is watched in its own goroutine, exactly the shape the +// workflow-execution-settings watch established. var runtimeResourceKinds = []string{ controlplane.ProviderSettingsKind, controlplane.ModelRoleAssignmentsKind, controlplane.RepositoryPoliciesKind, controlplane.SchedulingPolicyKind, + controlplane.ToolSettingsKind, controlplane.PluginSettingsKind, controlplane.ReviewSettingsKind, controlplane.ChannelSettingsKind, @@ -366,6 +370,14 @@ func (b *boot) applyRuntimeResourceUpdate(ctx context.Context, kind string, upda switch kind { case controlplane.ProviderSettingsKind, controlplane.ModelRoleAssignmentsKind: b.rebuildChatModelRuntime(cfg) + case controlplane.ToolSettingsKind: + // The document's server set and tool entries are live now; reconcile + // them and report the reconciliation's own outcome, which is the one + // that knows whether a server failed to connect. + if err := b.reconcileToolSettings(ctx, cfg); err != nil { + b.applyStatus.Report(ctx, kind, update.Version, err) + b.log.Error("tool settings reconciled with errors; the running servers stay", "version", update.Version, "err", err) + } case controlplane.PluginSettingsKind: // The document's directories are live now; load what they hold and // report the reconciliation's own outcome, which is the one that knows diff --git a/internal/app/archied/gateway_runtime.go b/internal/app/archied/gateway_runtime.go index 54d902740..ff186c492 100644 --- a/internal/app/archied/gateway_runtime.go +++ b/internal/app/archied/gateway_runtime.go @@ -137,8 +137,13 @@ func (b *boot) setupGatewayChat(ctx context.Context, actor gateway.ChatTaskActor router.InitSessions(b.chatSessionStore) configureTaskCommands(router, b.chatTasks, b.chatController, chatTaskListerAdapter{tasks: b.stateStore.Tasks}, b.defaultChatIdentity) router.Health = b.statusHealth + // ToolLimits reads the live holder, not cfg: the daemon's runtime-resource + // watch republishes a tool-settings change through it, so a policy edit + // applies to the next turn in the process that serves this runner. setup := chatSetup{ - Cfg: config.NewHolder(cfg), LLM: b.chatLLM, ChatModels: b.chatModels, ToolReg: b.toolReg, + Cfg: config.NewHolder(cfg), + ToolLimits: func() agentexec.ToolLimits { return toolLimits(b.cfgHolder.Get()) }, + LLM: b.chatLLM, ChatModels: b.chatModels, ToolReg: b.toolReg, Personas: b.personas, ChatTasks: b.chatTasks, ChatTaskLister: chatTaskListerAdapter{tasks: b.stateStore.Tasks}, ChatTaskLogs: chatTaskLogReaderAdapter{tasks: b.stateStore.TaskByID, taskLogs: b.taskLogs}, diff --git a/internal/app/archied/mcp_reconcile.go b/internal/app/archied/mcp_reconcile.go new file mode 100644 index 000000000..26d4f8d49 --- /dev/null +++ b/internal/app/archied/mcp_reconcile.go @@ -0,0 +1,192 @@ +package archied + +import ( + "context" + "errors" + "fmt" + "reflect" + "slices" + "strings" + + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/tools/minimax" + toolprovider "github.com/samcharles93/archie-core/internal/tools/provider" + "github.com/samcharles93/archie-core/internal/tools/webfetch" +) + +// appliedMCPServer is one MCP server the running provider registry was built +// from: the configuration it was built with and the manifest id it registered +// under. A live tool-settings change diffs the stored server set against this +// record, so a server that did not change is left running and untouched +// (archie-core-zfb0.3). +type appliedMCPServer struct { + server config.MCPServer + id string +} + +// buildMCPProvider builds the tool-provider engine for one configured MCP +// server. boot.mcpProvider overrides it in tests; production uses +// configuredMCPProvider with the running config's work directory and the +// daemon's sampling handler. Boot registration and the live reconciliation +// both reach the engine through here, so the two cannot build one differently. +func (b *boot) buildMCPProvider(srv config.MCPServer) (toolprovider.Engine, error) { + if b.mcpProvider != nil { + return b.mcpProvider(srv) + } + return configuredMCPProvider(srv, b.cfgHolder.Get().WorkDir, b.mcpSamplingHandler()) +} + +// reconcileToolSettings applies a live tool-settings change to the components +// built once from that kind: the MCP provider set (diffed, so an unchanged +// server keeps running), the web_fetch and minimax tool entries (rebuilt, +// because the entry captured the config at construction) and the tool-output +// policy (whose spill directory is ensured here; the task snapshot reads the +// policy fresh per dispatch and boot.toolLimits is read per call). A nil tool +// registry means this process built no tools, so only the config was layered. +func (b *boot) reconcileToolSettings(ctx context.Context, cfg config.Config) error { + if err := toolLimits(cfg).EnsureSpillDir(); err != nil { + b.log.Warn("tool spill directory unavailable; large results will be truncated instead", "err", err) + } + var problems []error + if err := b.reconcileMCPServers(ctx, cfg.Tools.MCPServers); err != nil { + problems = append(problems, err) + } + if b.toolReg != nil { + // Unregister first: the boot entry is being replaced, and a second + // registration would collide on the tool name. Minimax resolves its + // API key again as part of the rebuild, so a rotated credential + // applies too. + b.toolReg.Unregister(webfetch.ToolName, minimax.ToolName) + b.registerWebFetchTool(cfg) + b.registerMinimaxTool(cfg, b.log) + } + return errors.Join(problems...) +} + +// reconcileMCPServers brings the running provider set in line with the MCP +// servers the layered configuration now names: a server that appeared +// connects, one that disappeared disconnects, one whose configuration changed +// reconnects, and an unchanged one is left running and untouched. It is +// idempotent, so it can run on every stored tool-settings version without +// disturbing the servers that did not change. +// +// A server whose engine cannot be built or started is reported and left out; +// the servers already running keep running, the degrade-and-skip rule the boot +// registration applies. A changed server whose new engine fails to start is +// rolled back to the old one by the registry, so a refused change does not +// leave the server down. +func (b *boot) reconcileMCPServers(ctx context.Context, servers []config.MCPServer) error { + if b.providerRegistry == nil { + return nil + } + b.mcpMu.Lock() + defer b.mcpMu.Unlock() + + desired := make(map[string]config.MCPServer, len(servers)) + for _, srv := range servers { + if name := strings.TrimSpace(srv.Name); name != "" { + desired[name] = srv + } + } + state := b.mcpRegistryState() + var problems []error + problems = append(problems, b.disconnectAbsentMCPServers(ctx, desired)...) + problems = append(problems, b.applyDesiredMCPServers(ctx, desired, state)...) + return errors.Join(problems...) +} + +// mcpRegistryState is the read side of the provider registry a diff needs: is +// the family running at all, which ids are registered, and which are live. +type mcpRegistryState struct { + familyRunning bool + registered map[string]bool + live map[string]bool +} + +func (b *boot) mcpRegistryState() mcpRegistryState { + registered := make(map[string]bool) + for _, id := range b.providerRegistry.RegisteredIDs() { + registered[id] = true + } + live := make(map[string]bool) + for _, id := range b.providerRegistry.RunningIDs() { + live[id] = true + } + return mcpRegistryState{ + familyRunning: b.providerRegistry.Running(), + registered: registered, + live: live, + } +} + +// disconnectAbsentMCPServers removes every applied server the stored document +// no longer names. +func (b *boot) disconnectAbsentMCPServers(ctx context.Context, desired map[string]config.MCPServer) []error { + var problems []error + for name := range b.mcpApplied { + if _, ok := desired[name]; ok { + continue + } + applied := b.mcpApplied[name] + if err := b.providerRegistry.Remove(ctx, applied.id); err != nil { + problems = append(problems, fmt.Errorf("disconnect MCP server %q: %w", name, err)) + continue + } + delete(b.mcpApplied, name) + } + return problems +} + +// applyDesiredMCPServers connects, reconnects or restarts the servers the +// stored document names, skipping the ones already running unchanged. +func (b *boot) applyDesiredMCPServers(ctx context.Context, desired map[string]config.MCPServer, state mcpRegistryState) []error { + names := make([]string, 0, len(desired)) + for name := range desired { + names = append(names, name) + } + slices.Sort(names) + + var problems []error + for _, name := range names { + srv := desired[name] + if b.mcpServerCurrent(name, srv, state) { + continue + } + engine, err := b.buildMCPProvider(srv) + if err != nil { + problems = append(problems, fmt.Errorf("MCP server %q: %w", name, err)) + continue + } + if err := b.applyMCPProvider(ctx, engine, state); err != nil { + problems = append(problems, fmt.Errorf("connect MCP server %q: %w", name, err)) + continue + } + b.mcpApplied[name] = appliedMCPServer{server: srv, id: engine.Manifest().ID} + } + return problems +} + +// mcpServerCurrent reports whether the server is already running unchanged, so +// a reconciliation can leave it untouched. Present means running while the +// family runs, or still registered while it has not started; a +// registered-but-not-running server on a running family is a refused earlier +// start and is worth another attempt. +func (b *boot) mcpServerCurrent(name string, srv config.MCPServer, state mcpRegistryState) bool { + applied, ok := b.mcpApplied[name] + if !ok || !reflect.DeepEqual(applied.server, srv) { + return false + } + if !state.registered[applied.id] { + return false + } + return !state.familyRunning || state.live[applied.id] +} + +// applyMCPProvider replaces a registered provider and adds an absent one, +// whichever the registry needs for that id. +func (b *boot) applyMCPProvider(ctx context.Context, engine toolprovider.Engine, state mcpRegistryState) error { + if state.registered[engine.Manifest().ID] { + return b.providerRegistry.Replace(ctx, engine) + } + return b.providerRegistry.Add(ctx, engine) +} diff --git a/internal/app/archied/model_output_bound_test.go b/internal/app/archied/model_output_bound_test.go index c51bc4a76..5cc49e040 100644 --- a/internal/app/archied/model_output_bound_test.go +++ b/internal/app/archied/model_output_bound_test.go @@ -89,7 +89,7 @@ func TestChatTurnParameterNameFollowsModelClass(t *testing.T) { llm := agentexec.NewRuntime(map[string]agentexec.Provider{ "openai": {Class: "openai", BaseURL: api.URL}, }) - model := newChatTurnModel(func() *runtime.Runtime { return llm }, tools.NewRegistry(), 1, agentexec.ToolLimits{}, nil) + model := newChatTurnModel(func() *runtime.Runtime { return llm }, tools.NewRegistry(), 1, func() agentexec.ToolLimits { return agentexec.ToolLimits{} }, nil) prepared, err := model.Prepare(t.Context(), gateway.TurnPrepareContext{ Model: tc.modelRef, Reasoning: tc.reasoning, diff --git a/internal/app/archied/tool_settings_live_test.go b/internal/app/archied/tool_settings_live_test.go new file mode 100644 index 000000000..2ff5bc168 --- /dev/null +++ b/internal/app/archied/tool_settings_live_test.go @@ -0,0 +1,337 @@ +package archied + +import ( + "context" + "errors" + "strings" + "sync" + "testing" + + "github.com/samcharles93/archie-core/internal/app/controlplane" + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/plugin" + "github.com/samcharles93/archie-core/internal/secret" + "github.com/samcharles93/archie-core/internal/tools" + toolprovider "github.com/samcharles93/archie-core/internal/tools/provider" + "github.com/samcharles93/archie-core/internal/tools/webfetch" +) + +// fakeMCPEngine stands in for a configured MCP server so the live reconciliation +// can be driven without spawning a process. It records each lifecycle call on +// the shared recorder, keyed by configured server name. +type fakeMCPEngine struct { + name string + tools []tools.ToolEntry + rec *mcpEngineRecorder + startErr error +} + +func (e *fakeMCPEngine) Manifest() plugin.Manifest { + return plugin.Manifest{ + ID: "mcp." + e.name, + Name: e.name, + Version: "1.0.0", + APIVersion: plugin.HostAPIVersion, + Capabilities: []plugin.CapabilityKind{"tools"}, + } +} + +func (e *fakeMCPEngine) Start(context.Context) error { + e.rec.recordStart(e.name) + return e.startErr +} + +func (e *fakeMCPEngine) Stop(context.Context) error { + e.rec.recordStop(e.name) + return nil +} + +func (e *fakeMCPEngine) Discover(context.Context) ([]tools.ToolEntry, error) { + return append([]tools.ToolEntry(nil), e.tools...), nil +} + +// mcpEngineRecorder records what the live reconciliation did to each server and +// hands the test a factory boot.mcpProvider can use. +type mcpEngineRecorder struct { + mu sync.Mutex + builds map[string]int + starts map[string]int + stops map[string]int + failNext map[string]error + seen map[string]config.MCPServer +} + +func newMCPEngineRecorder() *mcpEngineRecorder { + return &mcpEngineRecorder{ + builds: map[string]int{}, + starts: map[string]int{}, + stops: map[string]int{}, + failNext: map[string]error{}, + seen: map[string]config.MCPServer{}, + } +} + +func (r *mcpEngineRecorder) factory() func(config.MCPServer) (toolprovider.Engine, error) { + return func(srv config.MCPServer) (toolprovider.Engine, error) { + name := strings.TrimSpace(srv.Name) + r.mu.Lock() + r.builds[name]++ + r.seen[name] = srv + err := r.failNext[name] + delete(r.failNext, name) + r.mu.Unlock() + return &fakeMCPEngine{ + name: name, + rec: r, + startErr: err, + tools: []tools.ToolEntry{{ + Name: "mcp." + name + ".tool", + Toolset: "mcp", + Handler: func(context.Context, map[string]any) (any, error) { return "ok", nil }, + }}, + }, nil + } +} + +func (r *mcpEngineRecorder) recordStart(name string) { + r.mu.Lock() + defer r.mu.Unlock() + r.starts[name]++ +} + +func (r *mcpEngineRecorder) recordStop(name string) { + r.mu.Lock() + defer r.mu.Unlock() + r.stops[name]++ +} + +func (r *mcpEngineRecorder) failOnNextStart(name string, err error) { + r.mu.Lock() + defer r.mu.Unlock() + r.failNext[name] = err +} + +func (r *mcpEngineRecorder) count(counts map[string]int, name string) int { + r.mu.Lock() + defer r.mu.Unlock() + return counts[name] +} + +// toolSettingsDocument renders a stored tool-settings document carrying the +// given MCP servers and an enabled web_fetch. +func toolSettingsDocument(servers ...map[string]any) map[string]any { + return map[string]any{ + "mcp_servers": servers, + "policy": map[string]any{}, + "web_fetch": map[string]any{}, + "minimax": map[string]any{}, + } +} + +func mcpServerDoc(name string, parallel bool) map[string]any { + return map[string]any{ + "name": name, + "transport": "stdio", + "command": "run-server", + "parallel_tool_calls": parallel, + } +} + +// newMCPReconcileBoot builds a boot whose provider registry is running, so the +// live reconciliation acts on a real registry and a real tool index. +func newMCPReconcileBoot(t *testing.T, base config.Config, stub *resourceWatchStub) (*boot, *applyStatusRecorder, *mcpEngineRecorder) { + t.Helper() + b, status := newLiveApplyBoot(t, base) + b.controlPlane = controlplane.NewRPCClient(stub) + b.secrets = secret.NewRegistry() + b.toolReg = tools.NewRegistry() + b.providerRegistry = toolprovider.NewRegistry(b.toolReg) + if err := b.providerRegistry.Start(t.Context()); err != nil { + t.Fatalf("start provider registry: %v", err) + } + b.mcpApplied = map[string]appliedMCPServer{} + rec := newMCPEngineRecorder() + b.mcpProvider = rec.factory() + return b, status, rec +} + +// applyToolSettings stores the document and runs the live apply the watch +// would run, the seam the daemon meets a stored tool-settings change through. +func applyToolSettings(t *testing.T, b *boot, stub *resourceWatchStub, version int64, document map[string]any) { + t.Helper() + if stub.values == nil { + stub.values = map[string]any{} + } + stub.values[controlplane.ToolSettingsKind] = document + if stub.storedVersion == nil { + stub.storedVersion = map[string]int64{} + } + stub.storedVersion[controlplane.ToolSettingsKind] = version + b.applyRuntimeResourceUpdate(t.Context(), controlplane.ToolSettingsKind, controlplane.AppliedResource{Version: version}) +} + +func TestLiveToolSettingsConnectsAnAddedServer(t *testing.T) { + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}} + b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub) + + applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false))) + + if got := rec.count(rec.starts, "alpha"); got != 1 { + t.Errorf("alpha start count = %d, want 1", got) + } + if _, ok := b.toolReg.Get("mcp.alpha.tool"); !ok { + t.Error("the added server's tool was not indexed") + } + if !b.providerRegistry.Has("mcp.alpha") { + t.Error("the added server is not registered") + } + servers := b.cfgHolder.Get().Tools.MCPServers + if len(servers) != 1 || servers[0].Name != "alpha" { + t.Errorf("running config servers = %+v, want the added alpha", servers) + } +} + +func TestLiveToolSettingsLeavesAnUnchangedServerUntouched(t *testing.T) { + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}} + b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub) + + applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false))) + applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("alpha", false), mcpServerDoc("beta", false))) + + if got := rec.count(rec.builds, "alpha"); got != 1 { + t.Errorf("alpha was rebuilt on an unchanged update: builds = %d, want 1", got) + } + if got := rec.count(rec.starts, "alpha"); got != 1 { + t.Errorf("alpha was reconnected on an unchanged update: starts = %d, want 1", got) + } + if got := rec.count(rec.stops, "alpha"); got != 0 { + t.Errorf("alpha was stopped on an unchanged update: stops = %d, want 0", got) + } + if got := rec.count(rec.starts, "beta"); got != 1 { + t.Errorf("beta start count = %d, want 1", got) + } +} + +func TestLiveToolSettingsReconnectsAChangedServer(t *testing.T) { + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}} + b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub) + + applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false))) + applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("alpha", true))) + + if got := rec.count(rec.stops, "alpha"); got != 1 { + t.Errorf("the changed server was not disconnected: stops = %d, want 1", got) + } + if got := rec.count(rec.starts, "alpha"); got != 2 { + t.Errorf("the changed server was not reconnected: starts = %d, want 2", got) + } + if _, ok := b.toolReg.Get("mcp.alpha.tool"); !ok { + t.Error("the reconnected server's tool left the index") + } +} + +func TestLiveToolSettingsDisconnectsARemovedServer(t *testing.T) { + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}} + b, _, rec := newMCPReconcileBoot(t, fileConfig(), stub) + + applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false), mcpServerDoc("beta", false))) + applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("beta", false))) + + if got := rec.count(rec.stops, "alpha"); got != 1 { + t.Errorf("the removed server was not disconnected: stops = %d, want 1", got) + } + if b.providerRegistry.Has("mcp.alpha") { + t.Error("the removed server stayed registered") + } + if _, ok := b.toolReg.Get("mcp.alpha.tool"); ok { + t.Error("the removed server's tool stayed indexed") + } + if got := rec.count(rec.stops, "beta"); got != 0 { + t.Errorf("the surviving server was disturbed: stops = %d, want 0", got) + } +} + +// TestLiveToolSettingsKeepsTheRunningServerWhenAChangeCannotStart is the path +// where the change must NOT apply: a changed server whose replacement fails to +// start is rolled back to the one that was running, and the refusal reaches +// apply status rather than the kind silently reporting success. +func TestLiveToolSettingsKeepsTheRunningServerWhenAChangeCannotStart(t *testing.T) { + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}} + b, status, rec := newMCPReconcileBoot(t, fileConfig(), stub) + + applyToolSettings(t, b, stub, 11, toolSettingsDocument(mcpServerDoc("alpha", false))) + rec.failOnNextStart("alpha", errors.New("handshake refused")) + applyToolSettings(t, b, stub, 12, toolSettingsDocument(mcpServerDoc("alpha", true))) + + // Two stops: the running server is disconnected for the replacement, and + // the replacement's own half-start is cleaned up when its handshake fails. + if got := rec.count(rec.stops, "alpha"); got != 2 { + t.Errorf("stops = %d, want 2 (the replaced server and the failed replacement's cleanup)", got) + } + if got := rec.count(rec.starts, "alpha"); got != 3 { + t.Errorf("starts = %d, want 3 (initial, refused replacement, rollback restart)", got) + } + if _, ok := b.toolReg.Get("mcp.alpha.tool"); !ok { + t.Error("the refused change left the running server's tool out of the index") + } + if !b.providerRegistry.Has("mcp.alpha") { + t.Error("the refused change left the server unregistered") + } + last, ok := status.last(controlplane.ToolSettingsKind) + if !ok { + t.Fatal("the refused change reported no apply status") + } + if !strings.Contains(last.Error, "alpha") { + t.Errorf("apply status error = %q, want it to name the refused server", last.Error) + } +} + +// TestLiveToolSettingsRebuildsTheWebFetchEntry: web_fetch captured its config +// at construction, so a live change rebuilds the entry rather than leaving the +// boot value in the model's tool list. +func TestLiveToolSettingsRebuildsTheWebFetchEntry(t *testing.T) { + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}} + b, _, _ := newMCPReconcileBoot(t, fileConfig(), stub) + + disabled := toolSettingsDocument() + disabled["web_fetch"] = map[string]any{"enabled": false} + applyToolSettings(t, b, stub, 11, disabled) + if _, ok := b.toolReg.Get(webfetch.ToolName); ok { + t.Error("web_fetch stayed registered after the stored document disabled it") + } + + applyToolSettings(t, b, stub, 12, toolSettingsDocument()) + if _, ok := b.toolReg.Get(webfetch.ToolName); !ok { + t.Error("web_fetch was not registered after the stored document re-enabled it") + } +} + +// TestLiveToolSettingsKeepsAnUnprojectedMCPHeader: the stored document cannot +// carry secret-bearing headers, so the layering restores them from the running +// base (controlplane.runtimeToolConfigFrom). The reconciliation must build the +// reconnected engine from that layered server, not from the document alone, or +// an authentication header disappears on the first live edit. +func TestLiveToolSettingsKeepsAnUnprojectedMCPHeader(t *testing.T) { + base := fileConfig() + base.Tools.MCPServers = []config.MCPServer{{ + Name: "alpha", + Transport: "http", + URL: "https://alpha.example/mcp", + Headers: map[string]string{"Authorization": "Bearer secret"}, + }} + stub := &resourceWatchStub{values: databaseOwnedResources(), version: 10, storedVersion: map[string]int64{}, opens: map[string]int{}} + b, _, rec := newMCPReconcileBoot(t, base, stub) + + changed := mcpServerDoc("alpha", true) + changed["transport"] = "http" + changed["url"] = "https://alpha.example/mcp" + delete(changed, "command") + applyToolSettings(t, b, stub, 11, toolSettingsDocument(changed)) + + rec.mu.Lock() + seen := rec.seen["alpha"] + rec.mu.Unlock() + if got := seen.Headers["Authorization"]; got != "Bearer secret" { + t.Errorf("reconnected server headers = %v, want the unprojected Authorization header restored", seen.Headers) + } +} diff --git a/internal/app/controlplane/operational_settings.go b/internal/app/controlplane/operational_settings.go index 3f0af7f3d..eaa306021 100644 --- a/internal/app/controlplane/operational_settings.go +++ b/internal/app/controlplane/operational_settings.go @@ -45,7 +45,14 @@ func operationalDefinitions() []Definition { {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}, + // ApplyMode is live: the daemon diffs the stored MCP server set against + // the running providers -- connecting added servers, disconnecting + // removed ones and reconnecting changed ones while leaving unchanged + // servers untouched -- and rebuilds the web_fetch and minimax entries + // (archie-core-zfb0.3). A changed server whose new engine fails to start + // is rolled back to the old one, so the refusal is reported rather than + // leaving the server down. + {Kind: ToolSettingsKind, Title: "Tool and MCP settings", ApplyMode: "live", Document: toolSettings{}, Seed: seedTools, Validate: validateTools}, // ApplyMode is live for additions: a stored directory change re-layers live // and the daemon's reconciliation loads new and changed files without a // restart. A removal cannot unload Yaegi's interpreter, so it stays an diff --git a/internal/app/controlplane/runtime_config_test.go b/internal/app/controlplane/runtime_config_test.go index 22b4b9b73..6f79aa623 100644 --- a/internal/app/controlplane/runtime_config_test.go +++ b/internal/app/controlplane/runtime_config_test.go @@ -553,17 +553,17 @@ func TestRuntimeResourceKindsApplyLive(t *testing.T) { modes[definition.Kind] = definition.ApplyMode } for _, kind := range []string{ - ProviderSettingsKind, ModelRoleAssignmentsKind, RepositoryPoliciesKind, SchedulingPolicyKind, AgentProfileKind, CredentialBindingsKind, PluginSettingsKind, ReviewSettingsKind, ChannelSettingsKind, ContainerRuntimePoliciesKind, + ProviderSettingsKind, ModelRoleAssignmentsKind, RepositoryPoliciesKind, SchedulingPolicyKind, AgentProfileKind, CredentialBindingsKind, ToolSettingsKind, PluginSettingsKind, ReviewSettingsKind, ChannelSettingsKind, ContainerRuntimePoliciesKind, } { 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} { - if modes[kind] != "restart-required" { - t.Errorf("%s applies %q, want restart-required: a startup-built component still holds it", kind, modes[kind]) - } - } + // No control-plane kind is restart-required any more: every kind's consumer + // either re-reads the published config or reconciles on its own process's + // watch. The process bindings that would be restart-required (listen + // addresses, the NATS and database URLs, the state and work directories) + // are not control-plane resource kinds at all. } func TestSchedulingPolicySeedCarriesTheLabel(t *testing.T) { diff --git a/internal/tools/provider/contract_test.go b/internal/tools/provider/contract_test.go index e797e641e..46cbc3454 100644 --- a/internal/tools/provider/contract_test.go +++ b/internal/tools/provider/contract_test.go @@ -42,7 +42,7 @@ func TestArchiedWiresTypedProvidersAndExecutableConsumers(t *testing.T) { // Also check the chat composition files, which hold the chat-turn wiring // extracted from main.go during the structural refactor. - for _, name := range []string{"telegram_setup.go", "chat_turn_model.go", "bootstrap.go"} { + for _, name := range []string{"telegram_setup.go", "chat_turn_model.go", "bootstrap.go", "mcp_reconcile.go"} { path := filepath.Join("..", "..", "..", "internal", "app", "archied", name) source, readErr := os.ReadFile(path) if readErr == nil { @@ -56,7 +56,12 @@ func TestArchiedWiresTypedProvidersAndExecutableConsumers(t *testing.T) { // root was decomposed; the receiver makes the arg expressions // carry the b. prefix there. "toolprovider.NewRegistry(b.toolReg)", - "configuredMCPProvider(srv, cfg.WorkDir, b.mcpSamplingHandler())", + // buildMCPProvider is the single construction seam: boot registration + // and the live reconciliation both reach configuredMCPProvider through + // it, so an MCP server is always built with the daemon's sampling + // handler. + "configuredMCPProvider(srv, b.cfgHolder.Get().WorkDir, b.mcpSamplingHandler())", + "b.buildMCPProvider(srv)", "capabilityHost.Register(b.providerRegistry)", // The chat turn builds its toolset from the registry before the // system prompt is rendered, so the prompt can advertise exactly diff --git a/internal/tools/provider/provider.go b/internal/tools/provider/provider.go index 127123b06..d2ab2851b 100644 --- a/internal/tools/provider/provider.go +++ b/internal/tools/provider/provider.go @@ -97,6 +97,25 @@ func (r *Registry) Register(engine Engine) error { return r.register(engine, false) } +// prepareRegistration validates an engine and builds its registration, the +// validation Register, Add and Replace all share. +func prepareRegistration(engine Engine, optional bool) (registration, error) { + if isNilEngine(engine) { + return registration{}, errors.New("tool provider is nil") + } + manifest, err := safeManifest(engine) + if err != nil { + return registration{}, err + } + if err := manifest.Validate(); err != nil { + return registration{}, fmt.Errorf("tool provider manifest: %w", err) + } + if !slices.Contains(manifest.Capabilities, toolCapability) { + return registration{}, fmt.Errorf("tool provider %q does not declare %q capability", manifest.ID, toolCapability) + } + return registration{engine: engine, manifest: cloneManifest(manifest), optional: optional}, nil +} + // RegisterOptional adds an engine the daemon can run without. // // An optional provider that fails to start or discover is logged, excluded @@ -109,30 +128,20 @@ func (r *Registry) RegisterOptional(engine Engine) error { } func (r *Registry) register(engine Engine, optional bool) error { - if isNilEngine(engine) { - return errors.New("tool provider is nil") - } - manifest, err := safeManifest(engine) + reg, err := prepareRegistration(engine, optional) if err != nil { return err } - if err := manifest.Validate(); err != nil { - return fmt.Errorf("tool provider manifest: %w", err) - } - if !slices.Contains(manifest.Capabilities, toolCapability) { - return fmt.Errorf("tool provider %q does not declare %q capability", manifest.ID, toolCapability) - } - manifest = cloneManifest(manifest) r.mu.Lock() defer r.mu.Unlock() if r.state != stateIdle { return ErrRegistryStarted } - if _, exists := r.providers[manifest.ID]; exists { - return fmt.Errorf("%w: %q", ErrDuplicateProvider, manifest.ID) + if _, exists := r.providers[reg.manifest.ID]; exists { + return fmt.Errorf("%w: %q", ErrDuplicateProvider, reg.manifest.ID) } - r.providers[manifest.ID] = registration{engine: engine, manifest: manifest, optional: optional} + r.providers[reg.manifest.ID] = reg return nil } diff --git a/internal/tools/provider/running.go b/internal/tools/provider/running.go new file mode 100644 index 000000000..30120337b --- /dev/null +++ b/internal/tools/provider/running.go @@ -0,0 +1,315 @@ +package provider + +import ( + "context" + "errors" + "fmt" + "slices" +) + +// ErrRegistryNotRunning is returned by the running-state operations when the +// family has been stopped or failed and can no longer change shape. +var ErrRegistryNotRunning = errors.New("tool provider registry is not running") + +// Running reports whether the family has started and its providers are live. +func (r *Registry) Running() bool { + r.mu.RLock() + defer r.mu.RUnlock() + return r.state == stateRunning +} + +// Has reports whether a provider with id is registered, running or not. +func (r *Registry) Has(id string) bool { + r.mu.RLock() + defer r.mu.RUnlock() + _, ok := r.providers[id] + return ok +} + +// RegisteredIDs returns the manifest IDs of every registered provider, sorted. +func (r *Registry) RegisteredIDs() []string { + r.mu.RLock() + defer r.mu.RUnlock() + ids := make([]string, 0, len(r.providers)) + for id := range r.providers { + ids = append(ids, id) + } + slices.Sort(ids) + return ids +} + +// RunningIDs returns the manifest IDs of the running providers, in start +// order. An unchanged provider's presence here is what a live reconciliation +// reads to leave it untouched. +func (r *Registry) RunningIDs() []string { + r.mu.RLock() + defer r.mu.RUnlock() + ids := make([]string, 0, len(r.running)) + for _, rp := range r.running { + ids = append(ids, rp.registration.manifest.ID) + } + return ids +} + +// Add starts one provider while the family is running, indexing its tools as +// one batch. The provider is isolated: a failed start unregisters it again and +// leaves every other provider running, the plugin engine rule for a provider +// pulled in at runtime. On a registry that has not started, Add registers the +// provider and Start picks it up with the rest. +func (r *Registry) Add(ctx context.Context, engine Engine) error { + r.opMu.Lock() + defer r.opMu.Unlock() + + reg, err := prepareRegistration(engine, true) + if err != nil { + return err + } + id := reg.manifest.ID + + r.mu.Lock() + if _, exists := r.providers[id]; exists { + r.mu.Unlock() + return fmt.Errorf("%w: %q", ErrDuplicateProvider, id) + } + switch r.state { + case stateIdle: + r.providers[id] = reg + r.mu.Unlock() + return nil + case stateRunning: + default: + state := r.state + r.mu.Unlock() + return fmt.Errorf("%w: cannot add from state %d", ErrRegistryNotRunning, state) + } + if missing, blocked := r.missingDependencyLocked(reg); blocked { + r.mu.Unlock() + return fmt.Errorf("tool provider %q depends on %q, which is not running", id, missing) + } + r.providers[id] = reg + r.mu.Unlock() + + rp, err := r.startProvider(ctx, reg, nil) + if err != nil { + r.mu.Lock() + delete(r.providers, id) + r.mu.Unlock() + return err + } + r.mu.Lock() + r.running = append(r.running, rp) + r.mu.Unlock() + return nil +} + +// Remove stops one running provider and unregisters it, removing the tools it +// indexed. Unlike a Yaegi plugin, an MCP server is a child process with a +// Stop, so a removal really unloads. On a registry that has not started, +// Remove only unregisters. +func (r *Registry) Remove(ctx context.Context, id string) error { + r.opMu.Lock() + defer r.opMu.Unlock() + + r.mu.Lock() + if _, exists := r.providers[id]; !exists { + r.mu.Unlock() + return fmt.Errorf("tool provider %q is not registered", id) + } + switch r.state { + case stateIdle, stateRunning: + default: + state := r.state + r.mu.Unlock() + return fmt.Errorf("%w: cannot remove from state %d", ErrRegistryNotRunning, state) + } + index := -1 + for i, rp := range r.running { + if rp.registration.manifest.ID == id { + index = i + break + } + } + if index >= 0 { + if dependent, ok := r.runningDependentLocked(id); ok { + r.mu.Unlock() + return fmt.Errorf("tool provider %q is required by running provider %q and cannot be removed", id, dependent) + } + } + var rp runningProvider + if index >= 0 { + rp = r.running[index] + r.running = slices.Delete(r.running, index, index+1) + } + delete(r.providers, id) + r.mu.Unlock() + + if index < 0 { + return nil + } + r.index.Unregister(rp.toolNames...) + if err := safeStop(ctx, rp.registration.engine); err != nil { + return fmt.Errorf("stop tool provider %q: %w", id, err) + } + return nil +} + +// Replace swaps the provider whose manifest id matches for a new engine while +// the family is running. The old provider is stopped and the new one started; +// when the new start fails the old one is restarted, so a refused replacement +// leaves the running set as it was. A provider registered but not yet running +// is started. On a registry that has not started, Replace swaps the +// registration only and Start picks the replacement up with the rest. +func (r *Registry) Replace(ctx context.Context, engine Engine) error { + r.opMu.Lock() + defer r.opMu.Unlock() + + reg, err := prepareRegistration(engine, true) + if err != nil { + return err + } + id := reg.manifest.ID + + r.mu.Lock() + if _, exists := r.providers[id]; !exists { + r.mu.Unlock() + return fmt.Errorf("tool provider %q is not registered", id) + } + switch r.state { + case stateIdle: + r.providers[id] = reg + r.mu.Unlock() + return nil + case stateRunning: + default: + state := r.state + r.mu.Unlock() + return fmt.Errorf("%w: cannot replace from state %d", ErrRegistryNotRunning, state) + } + index := -1 + for i, rp := range r.running { + if rp.registration.manifest.ID == id { + index = i + break + } + } + if missing, blocked := r.missingDependencyLocked(reg); blocked { + r.mu.Unlock() + return fmt.Errorf("tool provider %q depends on %q, which is not running", id, missing) + } + if index < 0 { + // Registered but not running -- a refused earlier start. Register the + // replacement and start it alone; nothing is running to stop first. + r.providers[id] = reg + r.mu.Unlock() + return r.startRegistered(ctx, reg) + } + if dependent, ok := r.runningDependentLocked(id); ok { + r.mu.Unlock() + return fmt.Errorf("tool provider %q is required by running provider %q and cannot be replaced", id, dependent) + } + previous := r.running[index] + r.mu.Unlock() + + // The old provider's tools leave the index before the new provider + // discovers, or a replacement advertising the same tool names would + // collide with its own predecessor. + r.index.Unregister(previous.toolNames...) + if err := safeStop(ctx, previous.registration.engine); err != nil { + r.dropProvider(id) + return fmt.Errorf("stop tool provider %q: %w", id, err) + } + rp, err := r.startProvider(ctx, reg, nil) + if err != nil { + restartErr := r.restartProvider(ctx, previous) + return errors.Join(fmt.Errorf("replace tool provider %q: %w", id, err), restartErr) + } + r.mu.Lock() + r.providers[id] = reg + r.running[index] = rp + r.mu.Unlock() + return nil +} + +// startRegistered starts one already-registered provider alone and moves it +// into the running set, rolling the registration back when it cannot run. +func (r *Registry) startRegistered(ctx context.Context, reg registration) error { + id := reg.manifest.ID + rp, err := r.startProvider(ctx, reg, nil) + if err != nil { + r.mu.Lock() + delete(r.providers, id) + r.mu.Unlock() + return err + } + r.mu.Lock() + r.running = append(r.running, rp) + r.mu.Unlock() + return nil +} + +// restartProvider puts a stopped provider back the way it was, the rollback of +// a refused replacement. It restarts the engine and re-indexes the tools it +// advertised; when even that fails, the provider is dropped rather than left +// half-registered, because nothing can put it back. +func (r *Registry) restartProvider(ctx context.Context, previous runningProvider) error { + cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), cleanupTimeout) + defer cancel() + id := previous.registration.manifest.ID + if err := safeStart(cleanupCtx, previous.registration.engine); err != nil { + r.dropProvider(id) + return fmt.Errorf("restart tool provider %q: %w", id, err) + } + entries, err := safeDiscover(cleanupCtx, previous.registration.engine) + if err == nil { + err = r.index.RegisterBatch(entries) + } + if err != nil { + r.dropProvider(id) + return fmt.Errorf("restore tool provider %q: %w", id, err) + } + return nil +} + +// dropProvider removes a provider from both the registration and the running +// set, the disposition of a provider that could not be started or restored. +func (r *Registry) dropProvider(id string) { + r.mu.Lock() + defer r.mu.Unlock() + delete(r.providers, id) + r.running = slices.DeleteFunc(r.running, func(rp runningProvider) bool { + return rp.registration.manifest.ID == id + }) +} + +// missingDependencyLocked reports the first dependency of reg that is not in +// the running set. The caller holds r.mu. +func (r *Registry) missingDependencyLocked(reg registration) (string, bool) { + for _, dependency := range reg.manifest.Dependencies { + found := false + for _, rp := range r.running { + if rp.registration.manifest.ID == dependency { + found = true + break + } + } + if !found { + return dependency, true + } + } + return "", false +} + +// runningDependentLocked returns a running provider other than id that depends +// on id, which is what makes replacing or removing id unsafe. The caller holds +// r.mu. +func (r *Registry) runningDependentLocked(id string) (string, bool) { + for _, rp := range r.running { + if rp.registration.manifest.ID == id { + continue + } + if slices.Contains(rp.registration.manifest.Dependencies, id) { + return rp.registration.manifest.ID, true + } + } + return "", false +} diff --git a/internal/tools/provider/running_test.go b/internal/tools/provider/running_test.go new file mode 100644 index 000000000..2d3de53ba --- /dev/null +++ b/internal/tools/provider/running_test.go @@ -0,0 +1,231 @@ +package provider + +import ( + "context" + "errors" + "slices" + "testing" + + "github.com/samcharles93/archie-core/internal/tools" +) + +// startRunningRegistry builds a registry over a fresh tool index with the +// named engines registered and started as one family, the state a live +// reconciliation runs against. It returns both so a test can read the index. +func startRunningRegistry(t *testing.T, engines ...Engine) (*Registry, *tools.Registry) { + t.Helper() + index := tools.NewRegistry() + registry := NewRegistry(index) + for _, engine := range engines { + if err := registry.RegisterOptional(engine); err != nil { + t.Fatalf("RegisterOptional: %v", err) + } + } + if err := registry.Start(t.Context()); err != nil { + t.Fatalf("Start: %v", err) + } + return registry, index +} + +func TestRegistryAddStartsOneProviderAlone(t *testing.T) { + first := newFakeEngine("first") + first.tools = []tools.ToolEntry{testTool("first.tool")} + registry, index := startRunningRegistry(t, first) + + second := newFakeEngine("second") + second.tools = []tools.ToolEntry{testTool("second.tool")} + if err := registry.Add(t.Context(), second); err != nil { + t.Fatalf("Add: %v", err) + } + + if first.startCount != 1 || first.stopCount != 0 { + t.Errorf("the running provider was disturbed: start=%d stop=%d", first.startCount, first.stopCount) + } + if second.startCount != 1 || second.discoverCount != 1 { + t.Errorf("the added provider was not started: start=%d discover=%d", second.startCount, second.discoverCount) + } + if got := registry.RunningIDs(); !slices.Equal(got, []string{"first", "second"}) { + t.Errorf("RunningIDs() = %v, want [first second]", got) + } + if _, ok := index.Get("second.tool"); !ok { + t.Error("the added provider's tool was not indexed") + } +} + +func TestRegistryAddIsIsolatedWhenTheProviderFails(t *testing.T) { + first := newFakeEngine("first") + first.tools = []tools.ToolEntry{testTool("first.tool")} + registry, _ := startRunningRegistry(t, first) + + failing := newFakeEngine("second") + failing.startErr = errors.New("boom") + if err := registry.Add(t.Context(), failing); err == nil { + t.Fatal("Add of a provider that cannot start: expected an error") + } + + if first.startCount != 1 || first.stopCount != 0 { + t.Errorf("a failed addition rolled the family back: start=%d stop=%d", first.startCount, first.stopCount) + } + if _, ok := registry.Get("second"); ok { + t.Error("the failed provider stayed registered") + } + if got := registry.RunningIDs(); !slices.Equal(got, []string{"first"}) { + t.Errorf("RunningIDs() = %v, want the family unchanged", got) + } + if failing.stopCount == 0 { + t.Error("the half-started provider was not cleaned up") + } +} + +func TestRegistryAddBeforeStartRegistersForTheFamily(t *testing.T) { + registry := NewRegistry(tools.NewRegistry()) + engine := newFakeEngine("late") + if err := registry.Add(t.Context(), engine); err != nil { + t.Fatalf("Add before Start: %v", err) + } + if registry.Running() { + t.Error("Add before Start started the family") + } + if engine.startCount != 0 { + t.Errorf("Add before Start started the engine %d times, want 0", engine.startCount) + } + if err := registry.Start(t.Context()); err != nil { + t.Fatalf("Start: %v", err) + } + if engine.startCount != 1 { + t.Errorf("Start did not pick up the added provider: start=%d", engine.startCount) + } +} + +func TestRegistryRemoveStopsOneProviderAlone(t *testing.T) { + first := newFakeEngine("first") + first.tools = []tools.ToolEntry{testTool("first.tool")} + second := newFakeEngine("second") + second.tools = []tools.ToolEntry{testTool("second.tool")} + registry, index := startRunningRegistry(t, first, second) + + if err := registry.Remove(t.Context(), "first"); err != nil { + t.Fatalf("Remove: %v", err) + } + + if first.stopCount != 1 { + t.Errorf("the removed provider was not stopped: stop=%d", first.stopCount) + } + if second.stopCount != 0 || second.startCount != 1 { + t.Errorf("the surviving provider was disturbed: start=%d stop=%d", second.startCount, second.stopCount) + } + if _, ok := registry.Get("first"); ok { + t.Error("the removed provider stayed registered") + } + if _, ok := index.Get("first.tool"); ok { + t.Error("the removed provider's tool stayed indexed") + } + if _, ok := index.Get("second.tool"); !ok { + t.Error("the surviving provider's tool left the index") + } +} + +func TestRegistryRemoveRejectsUnknownProvider(t *testing.T) { + registry, _ := startRunningRegistry(t) + if err := registry.Remove(t.Context(), "missing"); err == nil { + t.Fatal("Remove of an unregistered provider: expected an error") + } +} + +func TestRegistryReplaceSwapsTheRunningProvider(t *testing.T) { + previous := newFakeEngine("mcp.alpha") + previous.tools = []tools.ToolEntry{testTool("alpha.old")} + registry, index := startRunningRegistry(t, previous) + + replacement := newFakeEngine("mcp.alpha") + replacement.tools = []tools.ToolEntry{testTool("alpha.new")} + if err := registry.Replace(t.Context(), replacement); err != nil { + t.Fatalf("Replace: %v", err) + } + + if previous.stopCount != 1 { + t.Errorf("the replaced provider was not stopped: stop=%d", previous.stopCount) + } + if replacement.startCount != 1 { + t.Errorf("the replacement was not started: start=%d", replacement.startCount) + } + if _, ok := index.Get("alpha.old"); ok { + t.Error("the replaced provider's tool stayed indexed") + } + if _, ok := index.Get("alpha.new"); !ok { + t.Error("the replacement's tool was not indexed") + } +} + +func TestRegistryReplaceRestoresThePreviousProviderOnFailure(t *testing.T) { + previous := newFakeEngine("mcp.alpha") + previous.tools = []tools.ToolEntry{testTool("alpha.old")} + registry, index := startRunningRegistry(t, previous) + + replacement := newFakeEngine("mcp.alpha") + replacement.startErr = errors.New("boom") + err := registry.Replace(t.Context(), replacement) + if err == nil { + t.Fatal("Replace with a provider that cannot start: expected an error") + } + + if previous.stopCount != 1 { + t.Errorf("the previous provider was not stopped for the replacement: stop=%d", previous.stopCount) + } + if previous.startCount != 2 { + t.Errorf("the previous provider was not restarted: start=%d, want 2", previous.startCount) + } + if _, ok := index.Get("alpha.old"); !ok { + t.Error("the refused replacement left the previous provider's tool out of the index") + } + if got := registry.RunningIDs(); !slices.Equal(got, []string{"mcp.alpha"}) { + t.Errorf("RunningIDs() = %v, want the previous provider still running", got) + } +} + +func TestRegistryReplaceBeforeStartSwapsTheRegistration(t *testing.T) { + registry := NewRegistry(tools.NewRegistry()) + previous := newFakeEngine("mcp.alpha") + if err := registry.RegisterOptional(previous); err != nil { + t.Fatalf("RegisterOptional: %v", err) + } + replacement := newFakeEngine("mcp.alpha") + if err := registry.Replace(t.Context(), replacement); err != nil { + t.Fatalf("Replace before Start: %v", err) + } + if err := registry.Start(t.Context()); err != nil { + t.Fatalf("Start: %v", err) + } + if replacement.startCount != 1 || previous.startCount != 0 { + t.Errorf("Start ran the wrong registration: replacement=%d previous=%d", replacement.startCount, previous.startCount) + } +} + +func TestRegistryRunningStateReads(t *testing.T) { + registry := NewRegistry(tools.NewRegistry()) + engine := newFakeEngine("alpha") + if err := registry.RegisterOptional(engine); err != nil { + t.Fatalf("RegisterOptional: %v", err) + } + if registry.Running() { + t.Error("Running() = true before Start") + } + if !registry.Has("alpha") { + t.Error("Has(alpha) = false after registration") + } + if got := registry.RegisteredIDs(); !slices.Equal(got, []string{"alpha"}) { + t.Errorf("RegisteredIDs() = %v, want [alpha]", got) + } + if got := registry.RunningIDs(); len(got) != 0 { + t.Errorf("RunningIDs() = %v before Start, want none", got) + } + if err := registry.Start(context.Background()); err != nil { + t.Fatalf("Start: %v", err) + } + if !registry.Running() { + t.Error("Running() = false after Start") + } + if got := registry.RunningIDs(); !slices.Equal(got, []string{"alpha"}) { + t.Errorf("RunningIDs() = %v, want [alpha]", got) + } +} diff --git a/ui/test/settings-apply-status.test.ts b/ui/test/settings-apply-status.test.ts index 3046e560e..d13298a2c 100644 --- a/ui/test/settings-apply-status.test.ts +++ b/ui/test/settings-apply-status.test.ts @@ -23,18 +23,18 @@ const current: ApplyStatusRow[] = [ test("the restart banner names a process-binding change but never a live one", () => { const rowsFor = (kind: string) => - kind === "plugin-settings" ? behind : kind === "tool-settings" ? behind : current; + kind === "plugin-settings" ? behind : kind === "channel-settings" ? behind : current; // Both resources are behind; only the restart-required one is a restart. assert.deepEqual( restartPendingTitles( [ resource("plugin-settings", "Plugin settings", "live"), - resource("tool-settings", "Tool and MCP settings", "restart-required"), + resource("channel-settings", "Channel settings", "restart-required"), ], rowsFor, ), - ["Tool and MCP settings"], + ["Channel settings"], ); // A live-apply kind behind on a process never earns the banner at all.