Config Layer Design: ConfigRegistry, HostConfig/AgentManifest Split & Config Change Paths (RFC-0050 Phase 3)

[Million-mo]

Summary

Track the config layer design for AgentWolf v1 (RFC-0050, Issue #135). Scope: Layer 1 ConfigRegistry, the HostConfig/AgentManifest split, the three-layer model configuration (providers / aliases / agent selection), and — critically — the config change path at runtime, which RFC-0050 currently leaves undefined.

This issue does NOT duplicate #114 (import direction violations) or #83 (capability-level config). It is the config-focused sub-issue of #135.

Current State in Codebase

Component	Status
AgentsManifest (flat root config)	src/agentpool/models/manifest.py — loaded once in AgentPool.__init__, no reload path
model_variants (existing alias mechanism)	Already in manifest, agents reference by name
HostContext (frozen dataclass)	src/agentpool/host/context.py — Wave 1 landed, fields complete
AgentFactory	src/agentpool/host/factory.py — holds AgentPool reference (not standalone per RFC), returns empty registry, agents created lazily per-session
ModelRegistry / ModelCache	src/agentpool/host/stubs.py — stubs only
ConfigRegistry	Not implemented (interface in RFC-0050 only)

Design Decisions Already Made (RFC-0050)

1. Config split deferred to Phase 3 — Phase 1a/1b/1c/Phase 2 depend only on runtime extraction (HostContext + AgentFactory), not the config schema split. Flat AgentsManifest works through Phase 1-2. Oracle-verified.
2. Configs immutable once registered — updates create new versions.
3. Reference, not definition — MCP servers / model providers defined in host:; agents reference by name.
4. Three-layer model config — providers (secrets) / aliases (resolution+fallback) / agent selection (temperature, max_tokens). ModelCache keyed by (provider, model_name).
5. Diff-based recompile — AgentFactory.recompile() recreates only affected agents on config change.

The Gap: Config Change Paths (Runtime)

RFC-0050 describes ConfigRegistry as "store, version, serve YAML configs" but does not design how configs actually change at runtime. The storage schema should be designed with change patterns in mind. Five questions need answers:

1. What triggers a config change? File watching (pull-based, race-prone), explicit API submission (atomic, production-safe), CLI patch commands, or all three?
2. What is the change granularity? Full manifest replacement per config_id, or incremental patches to individual agents/fields?
3. How are partial failures handled? If 3 agents need recompilation and the 2nd fails, does the whole change roll back, or do we end up in a mixed state?
4. What happens to in-flight sessions during a HostConfig change? Graceful drain (wait for current turn to finish) or immediate cutover?
5. How are concurrent changes resolved? Two admins editing the same config_id simultaneously — CAS (compare-and-swap) or last-write-wins?

Constrained Answers (from existing RFC-0050 decisions)

• Trigger: Distributed scenario (ConfigStore = etcd) implies API submission + watch notifications. File watching is local-dev convenience; pull-based polling is race-prone.
• Granularity: Immutable versions make each change naturally version-level replacement; diff-based recompile narrows the runtime blast radius.
• Partial failures: Requires atomicity — validate new version → compile new registry → atomic swap (actor-style single reference swap). Not yet specified.
• In-flight sessions: "One RunLoop = one process = one session" invariant means RunLoop cannot be restarted mid-turn. Correct semantics: graceful drain — current turn finishes on old registry, new turns use new registry.
• Concurrent changes: Versioned immutable configs + CAS (validate base version on submit) is the natural fit; last-write-wins breaks versioning semantics.

Required Work

Phase 3 (deferred, per RFC-0050)

• RFC addition: "Config Change Paths" subsection — capture the five trigger/granularity/failure/drain/concurrency answers in RFC-0050 (even if marked Phase 3), so reviewers don't re-litigate them.
• ConfigStore schema design — (config_id, version, base_version, content, created_at, provenance, source) — write the table shape into the RFC appendix now so etcd/DB schema doesn't need rework at Phase 3.
• HostConfig + AgentManifest split — host: optional section plus auto-migration validator for v0.x flat config.
• ConfigRegistry implementation — register / get / list / watch / unregister over the ConfigStore.
• HostRegistry + RunScope routing — (config_id, tenant_id, user_id, session_id) selects the correct Host.

Phase 1 (pre-requisite — run in parallel)

• ConfigStore schema observability: resolve_model() string-fallback semantics (model: "openai:gpt-4o" treated as provider:model spec when not an alias) must be preserved when model_variants migrates to host.models.aliases — backward compat constraint to hold during P1b/P1d.
• Validate the Factory↔Pool coupling: RFC requires AgentFactory standalone (compile(manifest, host_context)), but agentpool/host/factory.py:83 constructs it with a pool reference. Confirm whether P1b work (HostContext independence) resolves this or whether the factory signature needs an explicit change.

Related

• [RFC-0050] packages/agentpool/docs/rfcs/draft/RFC-0050-agentwolf-v1-foundation-architecture.md (2484 lines) — Layers 1-3 + config split + model config + Phase 3 Gantt
• Issue [RFC] AgentWolf v1 Foundation Architecture — Six-Layer Design & Migration Plan #135 — parent RFC (six-layer foundation architecture)
• Issue Phase 7: Resolve 71 config→core import violations (deferred from #93) #114 — config→core import direction violations (separate concern, related)
• Issue feat: global/pool-level capability configuration for auto-injection into all agents #83 — capability-level config for auto-injection (agent-selection layer subset)