[RFC] AgentWolf v1 Foundation Architecture — Six-Layer Design & Migration Plan

[Leoyzen]

Summary

Proposes a six-layer foundation architecture for AgentPool v1.0 that achieves full orthogonality between config, infrastructure, agent compilation, execution lifecycle, agent core, and protocol serving. Unifies and supersedes RFC-0042's lifecycle dimensions within a broader architectural context.

Architecture Overview

Layer 1: ConfigRegistry    → Store, version, serve YAML configs
Layer 2: AgentHost          → Own mutable runtime infrastructure per (config_id, tenant_id)
Layer 3: AgentFactory       → Compile AgentManifest + HostContext into runnable agents
Layer 4: RunLoop            → Drive idle → running → idle | done cycle (RFC-0042 six dimensions)
Layer 5: Agent Core         → MessageNode, NativeAgent/ACPAgent, pydantic-ai Capability/Toolset
Layer 6: ProtocolServer     → Translate between wire protocols and RunLoop operations

RunScope (config_id, tenant_id, user_id, session_id) is the cross-cutting router that enables multi-tenancy without structural changes — each layer becomes a registry keyed by RunScope.

Key Design Decisions

1. Config Split: HostConfig + AgentManifest

Section	Owner	Change Cost	Example
host: (HostConfig)	AgentHost (L2)	High (restart MCP, reconnect DB)	mcp_servers, storage, models, observability
agents: + teams: + graph: (AgentManifest)	AgentFactory (L3)	Low (recompile agents, diff-based)	agent defs, team topology, response schemas

Reference, not definition: MCP servers and model providers are DEFINED in HostConfig; agents REFERENCE them by name. This separates "what infrastructure IS" from "which agent uses WHICH infrastructure."

Deferred to Phase 3 per Oracle analysis — Phase 1 extracts only runtime structures (HostContext + AgentFactory) without modifying config model. Flat AgentsManifest works throughout Phase 1-2.

2. Model Config Three-Layer

Layer	Concern	Location
Provider config	API keys, base URLs, proxies	host.models.providers
Model aliases	Name resolution, fallback chains	host.models.aliases
Agent selection	Which alias, temperature, max_tokens	agent.model, agent.temperature

ModelCache shares pydantic-ai Model instances across agents in the same host (connection pooling). Alias enables model migration in one place.

3. Delete ResourceProvider, Adopt pydantic-ai Capability/Toolset

ResourceProvider is already deprecated. pydantic-ai's AbstractCapability + AbstractToolset system is richer, native, and eliminates the as_capability() bridge layer. 7 provider migration mappings >90% clear.

Change notification: Extend AbstractCapability.on_change() — delegated to Capability, not centralized. Avoids recreating ResourceProvider signal pattern under a new name.

Knowledge management: Starts as Capability (Layer 5), promoted to Layer 2 KnowledgeProvider when cross-agent sharing is demonstrated (YAGNI).

4. ResourceSource — Orthogonal Data Abstraction

pydantic-ai has tools (behavior) and instructions (directives) but no data concept. ResourceSource fills this gap:

• Orthogonal to Capability — not parallel (which would recreate ResourceProvider)
• MCPCapability implements BOTH AbstractCapability (tools) AND ResourceSource (resources) — two interfaces, two concerns, same object
• AggregatedResourceSource composes multiple sources at compile time
• AgentContext.resources: ResourceSource | None — optional, compile-time scoped

5. AgentContext + DelegationService

@dataclass(frozen=True)
class AgentContext:
    agent_registry: AgentRegistry      # read-only, from AgentFactory (L3)
    delegation: DelegationService      # interface from RunLoop (L4)
    session: SessionState              # from RunLoop (L4)
    scope: RunScope                    # cross-cutting
    resources: ResourceSource | None   # from Factory, compile-time scoped
    host: HostContext | None           # rarely needed, for advanced tools

DelegationService is a limited interface exposed by RunLoop — tools know WHAT they can do (spawn subagent), not HOW RunLoop implements it. Preserves Layer 4→5 boundary.

6. HostContext Replaces agent_pool Backdoor

MessageNode.agent_pool is a direct reference to the full AgentPool on every agent — spans Layers 2-5. HostContext is a frozen dataclass carrying only dependency handles, enforcing layer boundaries and enabling tenant isolation. Single highest-priority refactor in Phase 1.

7. Storage Three-Layer (Complementary, Not Conflicting)

Store	Role	Owner	Retention
StorageProvider	DB tables (analytical history)	AgentHost (L2)	Permanent
Journal	WAL / transaction log (event persistence)	CommChannel (L4)	Compactible
SnapshotStore	Checkpoint file (Turn boundary state)	RunLoop (L4)	Turn-scoped

Tiered consistency: Turn-level events strong (synchronous dual-write), Delta events eventual (async batch journal). Avoids write amplification while preserving crash recovery.

8. Concurrency Model

• asyncio at all layers (single-process)
• Multi-process: AgentHost MCP subprocesses + EventTransport IPC (gRPC)
• Distributed: ConfigStore (etcd) + MessageQueueTransport + HostRegistry routing

Invariant: One RunLoop = one process = one session. Distribution happens AROUND RunLoop, not within it.

EventTransport evolution: InProcess (default) → gRPC (multi-process) → MessageQueue (distributed polyglot). Each step opt-in.

Implementation Plan (Oracle-Revised)

Critical path: Phase 1a (14d) → Phase 2 (30d) = 44 days to RunLoop

Phase	Deliverable	Duration	Dependencies
1a	Runtime extraction: HostContext + AgentFactory from AgentPool	14d	—
1b	Backdoor removal: replace agent_pool with HostContext (25 call sites)	21d	1a (parallel with Phase 2)
1c	Capability bridge: 7 ToolsetFactory equivalents + AdapterToolsetFactory	21d	1a (parallel with Phase 2)
1d	Delete ResourceProvider after all call sites migrated	7d	1c
2	RFC-0041 (Run/Turn separation) + RFC-0042 (six dimensions)	30d+45d	1a
3	Config split + ConfigRegistry versioning + HostRegistry + RunScope routing	14d+21d+21d+14d	Phase 2
4	Multi-tenant: tenant isolation + StorageProvider filtering	21d+14d	Phase 3
5	Polyglot: gRPCTransport + MessageQueueTransport	21d+30d	Phase 2

Config split deferred to Phase 3 — Oracle analysis confirmed Phase 1b/1c/Phase 2 depend on 1a-runtime only (HostContext + AgentFactory extraction), NOT on config schema split.

Related Documents

• 📄 RFC-0050: docs/rfcs/draft/RFC-0050-agentwolf-v1-foundation-architecture.md (2484 lines, revision 5, Oracle-revised)
• 📄 RFC-0042: docs/rfcs/draft/RFC-0042-unified-lifecycle-architecture.md (~3060 lines, revision 4.4, Oracle-reviewed PASS) — Layer 4 detail
• 📄 RFC-0041: docs/rfcs/draft/RFC-0041-run-turn-separation.md — Phase 2 prerequisite
• 📊 Lifecycle Analysis: docs/design/lifecycle-analysis.md (cross-framework survey)
• 🔗 Appendix A: Oracle architecture feasibility assessment (MEDIUM RISK, conditional GO)
• 🔗 Appendix B: Codebase migration cost (9-15 dev-weeks, 151 importers, 85 test files)
• 🔗 Appendix C: DeerFlow architecture reference (~228K LOC)
• 🔗 Appendix D: Zed editor architecture reference (~15 Rust crates)

Review Requested

1. Six-layer separation — are the layer boundaries correct? Should any layers merge or split?
2. Config split deferral — is deferring HostConfig/AgentManifest to Phase 3 safe?
3. ResourceSource orthogonality — is the data-vs-behavior axis distinction clear enough to avoid confusion with deleted ResourceProvider?
4. AgentContext design — is DelegationService the right abstraction for Layer 4→5 bridging?
5. Tiered consistency — is the Turn-level strong / Delta-level eventual split acceptable?
6. Migration sequencing — is the Oracle-revised critical path (44d to RunLoop) realistic?

[Million-mo]

Missing: Config Change Strategy & Paths

The issue describes ConfigRegistry as "Store, version, serve YAML configs" but doesn't detail how configurations actually change at runtime. This is a significant gap even for Phase 3 planning — the storage structure should be designed with the change patterns in mind.

Questions that 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 config 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?

Context from current codebase

The existing agentpool watch command (agentpool_cli/watch.py) and WatchConfig (agentpool_config/loaders.py:326) already support file-watching patterns, but only for triggering agent events on resource changes — not for hot-reloading agent configurations themselves. The current AgentPool.__init__ consumes config once at construction time with no reload path.

Suggestion

Consider adding a brief "Config Change Paths" subsection (even if deferred to Phase 3) so the storage structure can be designed to support these patterns from the start. The distributed scenario (ConfigStore (etcd)) mentioned in the issue already implies API-based submission with watch notifications — clarifying this would help reviewers assess whether the L1 design is sufficient.

[Million-mo]

Before/After Architecture Comparison

A concrete breakdown of how the current AgentPool maps to the proposed six layers, showing what each layer extracts and what changes for agents.

Before: AgentPool as God Object

┌─────────────────────────────────────────────────────────────────────┐
│                        AgentPool (one class does everything)         │
│                                                                     │
│  ┌── L1: Config ────────────────────────────────────────────────┐  │
│  │  self.manifest = AgentsManifest.from_file("config.yml")      │  │
│  │  self._config_file_path                                       │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↓ consumed immediately                  │
│  ┌── L2: Infrastructure ───────────────────────────────────────┐  │
│  │  self.mcp = MCPManager(servers=...)   # MCP subprocesses      │  │
│  │  self.storage = StorageManager(...)    # DB connection        │  │
│  │  self._session_store = ...             # session storage      │  │
│  │  self.process_manager = ProcessManager() # subprocess mgmt    │  │
│  │  self.vfs_registry = VFSRegistry()     # virtual FS           │  │
│  │  self.skills = SkillsManager(...)      # skill management     │  │
│  │  self.prompt_manager = PromptManager(...) # prompt templates  │  │
│  │  registry.configure_observability(...)  # observability       │  │
│  │  # No ModelCache — model instances scattered across agents    │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↓ used directly                         │
│  ┌── L3: Agent Compilation ────────────────────────────────────┐  │
│  │  self.connection_registry = ConnectionRegistry()             │  │
│  │  self._graph = None  # graph topology                        │  │
│  │  # Agents compiled inline in __aenter__, no standalone Factory│  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↓ produces agent instances              │
│  ┌── L4: Execution ────────────────────────────────────────────┐  │
│  │  self._session_pool: SessionPool | None                      │  │
│  │  self._input_provider                                        │  │
│  │  # SessionController + TurnRunner + RunExecutor scattered    │  │
│  │  # Native agents and ACP agents use completely different paths│  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              ↓ agent runtime                         │
│  ┌── L5: Agent Core ───────────────────────────────────────────┐  │
│  │  MessageNode                                                 │  │
│  │    .agent_pool → points back to entire AgentPool (backdoor!) │  │
│  │  ResourceProvider + as_capability() (bridge layer)           │  │
│  │  ToolManager (deprecated)                                    │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ┌── Other ────────────────────────────────────────────────────┐   │
│  │  self.file_ops, self.todos, self._tasks                      │  │
│  │  self.skills_instruction_provider, self._skill_commands      │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                    ↑
                    187 references via .agent_pool backdoor
                    agent can reach ALL of the above, no boundary

Key problems:

• One __init__ does L1-L5 everything
• agent_pool backdoor lets agents access the entire system
• Native agent / ACP agent execution paths are completely different, no unified abstraction
• ResourceProvider + as_capability() is a translation layer, not native types
• Any config change requires rebuilding the entire AgentPool

After: Six Orthogonal Layers

┌─────────────────────────────────────────────────────────────────────┐
│                        L1: ConfigRegistry                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                │
│  │ config_id=  │  │ config_id=  │  │ config_id=  │                │
│  │  default    │  │  tenant_A   │  │  tenant_B   │                │
│  │             │  │             │  │             │                │
│  │ HostConfig  │  │ HostConfig  │  │ HostConfig  │  ← MCP/storage │
│  │ + Manifest  │  │ + Manifest  │  │ + Manifest  │    /models def │
│  │  (v1, v2..) │  │  (v1, v2..) │  │  (v1)       │    + agent def │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                │
│         │  Versioning, diff, hot-reload, rollback                   │
└─────────┼──────────────────┼──────────────────┼─────────────────────┘
          │ HostConfig       │ HostConfig       │ HostConfig
          ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        L2: AgentHost                                │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐          │
│  │ AgentHost    │    │ AgentHost    │    │ AgentHost    │          │
│  │ (default)    │    │ (tenant_A)   │    │ (tenant_B)   │          │
│  │              │    │              │    │              │          │
│  │ HostContext: │    │ HostContext: │    │ HostContext: │          │
│  │  mcp         │    │  mcp (A's) │    │  mcp (B's) │          │
│  │  storage     │    │  storage(A)  │    │  storage(B)  │          │
│  │  models ←NEW │    │  models      │    │  models      │          │
│  │  skills      │    │  skills      │    │  skills      │          │
│  │  process_mgr │    │  process_mgr │    │  process_mgr │          │
│  │  observability│   │  observability│   │  observability│         │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘          │
│         │  Lifecycle independent: changing agent does not restart   │
│         │  MCP/DB connections                                          │
└─────────┼───────────────────┼───────────────────┼───────────────────┘
          │ HostContext       │ HostContext       │ HostContext
          │ (frozen)          │ (frozen)          │ (frozen)
          ▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        L3: AgentFactory                             │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  AgentFactory.build(manifest, host_context, scope)           │  │
│  │  manifest + HostContext → compiled agent instances            │  │
│  │  diff-based: only recompiles affected agents                  │  │
│  │  produces: AgentRegistry (read-only)                          │  │
│  │  agent receives HostContext (frozen), NOT AgentHost           │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
          │ AgentRegistry (read-only)
          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        L4: RunLoop                                  │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  RunLoop: idle → running → idle | done                       │  │
│  │                                                              │  │
│  │  Unifies (previously scattered):                             │  │
│  │    SessionController.receive_request()  → unified entry      │  │
│  │    RunExecutor (native agents)         → unified exec loop   │  │
│  │    TurnRunner (ACP agents)             → unified exec loop   │  │
│  │    PendingMessageDrainCapability       → unified msg queue   │  │
│  │    manual _post_turn_prompts           → unified msg queue   │  │
│  │                                                              │  │
│  │  Exposed to agents:                                          │  │
│  │    DelegationService.spawn("agent_name", prompt)             │  │
│  │    ← limited interface, agent does not know how RunLoop works│  │
│  │    ← replaces agent.agent_pool.get_agent() backdoor          │  │
│  │                                                              │  │
│  │  Storage:                                                    │  │
│  │    Journal (WAL) + SnapshotStore (checkpoint)                │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
          │ AgentContext (frozen)
          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        L5: Agent Core                               │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  MessageNode                                                 │  │
│  │    .host → HostContext (frozen)     ← replaces .agent_pool   │  │
│  │    No more: .agent_pool                                       │  │
│  │                                                              │  │
│  │  AgentContext (frozen):                                      │  │
│  │    agent_registry: AgentRegistry     ← read-only, from L3    │  │
│  │    delegation: DelegationService     ← limited iface, from L4│  │
│  │    session: SessionState             ← from L4               │  │
│  │    scope: RunScope                   ← cross-cutting key     │  │
│  │    resources: ResourceSource | None  ← compile-time scoped   │  │
│  │    host: HostContext | None          ← rarely needed         │  │
│  │                                                              │  │
│  │  Tool system:                                                │  │
│  │    AbstractCapability + AbstractToolset (pydantic-ai native) │  │
│  │    Deleted: ResourceProvider + as_capability() bridge        │  │
│  │    Deleted: ToolManager                                      │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        L6: ProtocolServer                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
│  │ ACP      │ │ OpenCode │ │ AG-UI    │ │ OpenAI   │ │ MCP      ││
│  │ Server   │ │ Server   │ │ Server   │ │ API Srv  │ │ Server   ││
│  │          │ │          │ │          │ │          │ │          ││
│  │  Operates via RunLoop, does not touch agent instances directly ││
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘│
└─────────────────────────────────────────────────────────────────────┘

         RunScope (config_id, tenant_id, user_id, session_id)
         ═══════════════════════════════════════════════════
         Cross-cutting router key across L1-L6, each layer indexed by RunScope

Layer-by-Layer Diff

Layer	Before	After	Core Change
L1 Config	AgentPool.__init__ loads YAML once and consumes it	ConfigRegistry stores, versions, serves by config_id	Config becomes a versioned resource instead of a one-time consumable
L2 Infrastructure	Mixed into AgentPool, agents access via .agent_pool backdoor	AgentHost holds HostContext (frozen), agents get dependency handles only	From "can access everything" to "only get handles"; supports per-tenant isolation
L3 Agent Compilation	Inline in AgentPool.__aenter__, no standalone factory	AgentFactory compiles independently, diff-based recompilation	Changing one agent does not rebuild the entire pool
L4 Execution	SessionController + RunExecutor + TurnRunner scattered	RunLoop unifies idle→running→idle|done state machine	Eliminates native/ACP dual-track execution; DelegationService replaces backdoor
L5 Agent Core	.agent_pool backdoor + ResourceProvider bridge layer	AgentContext (frozen) + pydantic-ai native Capability/Toolset	Deletes parallel abstraction and translation layer; agents access system via limited interface only
L6 Protocol	Servers directly manipulate agent instances and pool	Servers operate via RunLoop, do not touch agents directly	Protocol layer decoupled from execution layer

Concrete Code-Level Evidence

The current AgentPool.__init__ (src/agentpool/delegation/pool.py:61-234) does all six layers in one constructor:

• L1: AgentsManifest.from_file() (:128)
• L2: StorageManager() (:162), MCPManager() (:172), SkillsManager() (:173), ProcessManager() (:215)
• L3: ConnectionRegistry() (:170)
• L4: _session_pool (:230), _input_provider (:159)
• L5: SkillsInstructionProvider() (:179), SkillsTools() (:187)

The .agent_pool backdoor appears in 21 files with 187 references across the codebase, with the most critical path in messagenode.py:134-139 where agents directly share the pool's MCPManager:

if agent_pool is not None and not mcp_servers:
    self.mcp = agent_pool.mcp  # agent takes pool's MCP manager directly

This makes per-tenant MCP isolation impossible without structural changes — which is exactly what HostContext (frozen dataclass with dependency handles only) solves.

[Million-mo]

MCP Architecture Review: Design Assessment & Transition Checklist

Reviewed the MCP design in PR #144 (McpConfigSnapshot + ExtensionRegistry + McpServerCap). The design direction is sound — source tagging, scope-level visibility, native capability wrapping, and change notification cover the right concerns. Below are key design questions and a transition checklist.

Key Design Questions

1. McpConfigSnapshot vs ExtensionRegistry — dual-layer mapping redundancy

McpConfigSnapshot partitions configs into pool_configs / agent_configs / session_configs / skill_configs (4 fields). ExtensionRegistry has POOL / SESSION / AGENT / TURN (4 scope levels). The mapping between them is manual in AgentFactory.compile() — pool_configs → ScopeLevel.POOL, agent_configs → ScopeLevel.AGENT, etc. These two four-part partitions overlap significantly. Should they be unified into a single source-of-truth, or is the separation intentional (snapshot = config origin, registry = runtime visibility)?

2. Skill MCP configs — scope ambiguity

McpConfigSnapshot.skill_configs is a standalone field, but ExtensionRegistry has no SKILL scope level. Skill MCP servers are registered into either POOL or SESSION scope depending on the skill's scope configuration, with the mapping logic scattered across AgentFactory and SkillsManager. Questions:

• What happens when two skills define MCP servers with the same name?
• Should ExtensionRegistry have an explicit SKILL scope level, or should skill MCP configs always resolve to an existing scope at registration time?

3. Connection deduplication across scopes

McpServerCap lazily obtains MCPClient via SessionConnectionPool.get_client(). POOL-scoped and SESSION-scoped MCP servers use different SessionConnectionPool instances. If a POOL-level MCP server and a SESSION-level MCP server point to the same URL/command, two separate connections are created. Is this intentional (isolation by scope) or should there be connection deduplication by server identity?

Transition Checklist (PR #144 → Target Architecture)

These are known transition-state items, not design flaws — tracking them for completion:

• McpServerCap ↔ MCPManager coexistence: MCPManager still manages subprocess lifecycle; McpServerCap wraps it at the capability layer. PR comments reference "Phase 4 task 4.13" for full migration. Verify MCPManager is fully replaced by McpServerCap + SessionConnectionPool after Phase 4.
• McpConfigSnapshot → ExtensionRegistry mapping: Currently manual in AgentFactory.compile(). Consider auto-mapping from source field to ScopeLevel to eliminate dual-write maintenance.
• Change notification granularity: ChangeObservable.on_change() fires server-level events (tools/list_changed). The hot-swap listener triggers a full get_toolset() re-fetch. For MCP servers with many tools, consider delta-level notification to avoid full re-fetch.
• TURN-scoped MCP cleanup: ExtensionRegistry supports ScopeLevel.TURN for runtime-injected MCP servers, but the cleanup path (auto-removal after turn ends) needs verification — especially for error cases where the turn fails mid-execution.

[Million-mo]

agent_pool Backdoor Clearance Status

PR #144 introduces HostContext as the replacement for agent_pool direct access, but the migration is incomplete. Counting references in key files on the refactor/agentwolf_v1 branch:

File	agent_pool refs	host_context refs	Status
delegation/pool.py	0	11	✅ Migrated
acp_server/session.py	0	12	✅ Migrated
acp_server/handler.py	0	12	✅ Migrated
agents/base_agent.py	12	15	⚠️ Dual references
agents/native_agent/agent.py	17	15	⚠️ Dual references
messaging/messagenode.py	20	9	⚠️ Dual references
delegation/base_team.py	11	8	⚠️ Dual references
opencode_server/server.py	4	2	⚠️ Dual references
talk/talk.py	2	2	⚠️ Dual references

Key remaining agent_pool usages

The most critical remaining references are in messagenode.py and native_agent/agent.py:

# messagenode.py:134 — agent shares pool MCP manager directly
if agent_pool is not None and not mcp_servers:
    self.mcp = agent_pool.mcp  # ← backdoor to pool infrastructure

# messagenode.py:266 — storage accessed via pool
return self._agent_pool.storage if self._agent_pool else None

# native_agent/agent.py:290-291 — manifest and storage fetched from pool
manifest = agent_pool.manifest if agent_pool else AgentsManifest()
storage = agent_pool.storage if agent_pool else StorageManager()

# native_agent/agent.py:524 — prompt manager accessed via pool
content = agent_pool.prompt_manager.get.sync(reference)

messagenode.py:141-155 has a deprecation warning property:

@property
def agent_pool(self) -> AgentPool[Any] | None:
    warnings.warn("agent_pool is deprecated, use host_context ...")
    return self._agent_pool

But the property is still used internally — messagenode.py:173-174 routes host_context access through agent_pool:

if self._agent_pool is not None:
    return self._agent_pool.get_context()  # ← HostContext obtained via pool backdoor

This means HostContext is currently just a view through the backdoor, not a replacement of it.

Questions

1. Is there a tracked task for complete agent_pool removal? The current state (dual references + deprecation warning) is a valid transition step, but needs a clear endpoint.
2. Should host_context be injected at construction instead of derived from agent_pool? Currently get_context() delegates to AgentPool, which means HostContext cannot exist without AgentPool — defeating the multi-tenant isolation goal.

[Leoyzen]

Steer() Bug Fix & ACP session/inject RFD Findings

Bug Fix (Completed)

While reviewing PR #144, we identified and fixed a bug in RunHandle.steer() where ProtocolChannel sessions (ACP/OpenCode/AG-UI servers) skipped mid-turn injection:

• Root cause: steer() checked the CommChannel feedback path before enqueue("asap"). ProtocolChannel.deliver_feedback() always returns True, causing early return — enqueue("asap") was unreachable.
• Impact: ProtocolChannel sessions got next-turn-only steer delivery, while DirectChannel sessions (standalone execution) got correct mid-turn injection.
• Fix: Reordered steer() — Priority 1: enqueue("asap") when RUNNING + active_agent_run; Priority 2: CommChannel feedback; Priority 3: DirectChannel fallback. Added _idle_event.set() for race safety.
• TDD: 2 tests failed on old code (red), 3 passed on fixed code (green), 348 tests in lifecycle+orchestrator suites — no regressions.

Details: PR #144 comment

ACP session/inject RFD #1261 — Architecture Analysis

Researched the upstream ACP v2 RFD #1261 (session/inject with queue/steer modes). Key findings:

1. ACP v1 has no steer protocol — only session/cancel + new session/prompt (destructive interrupt-then-reprompt). AgentPool's CommChannel already goes beyond ACP v1.

2. RFD #1261 proposes:

• Single session/inject method with mode: "queue" | "steer"
• Agent-owned messageId returned synchronously (for revoke/replace)
• user_message notification at delivery time (same as v2 prompt lifecycle)
• session/revoke_inject (mandatory), session/replace_inject (opt-in)
• steer_in_stream capability: ["interrupt"] vs ["finish"]
• Pending injects survive session/cancel

3. AgentPool's CommChannel vs RFD:

Capability	AgentPool (after fix)	RFD #1261
Mid-turn steer	✅ enqueue("asap") at model request	✅ at next tool boundary
Queue (next-turn)	✅ followup()	✅ mode: "queue"
messageId handle	❌	✅ mandatory
Revoke pending	❌	✅ mandatory
Replace pending	❌	✅ opt-in
steer_in_stream capability	❌	✅
cancel interaction with pending	undefined	defined (injects survive)

4. Production pressure: Raft team reports steer absence is an ACP adoption blocker. They tested Grok CLI 0.2.93 — no mid-turn injection on public ACP transport. Strong +1 for moving session/inject forward. (comment)

5. AgentPool's steer is finer-grained than RFD: PydanticAI's PendingMessageDrainCapability drains at before_model_request — every model request, not just tool boundaries. For multi-tool-call turns, AgentPool injects sooner than RFD's "complete the tool call, then deliver."

Sub-Issue Created

Created #154 to track the messageId / revoke / replace / steer_in_stream work needed for RFD #1261 compliance. This is Layer 4 (RunLoop) scope — extending Feedback type and adding pending message management.

(Note: GitHub API token lacks permission to formally link #154 as a sub-issue of #135. Manual linking may be needed.)