Replace per-handler mcp_manager plumbing with a single PolicyBus

[shaun0927]

Context

Depends on #471 (control-plane RFC), the Directive vocabulary issue, and the control_directive event-category issue.

PRs #279 and #280 wire mcp_manager through ExecuteSeedHandler via explicit constructor injection. Each additional handler that needs MCP capability — evolve_step, unstuck, ralph, and any future workflow — must repeat the same injection.

Evidence from #280:

• src/ouroboros/cli/commands/mcp.py: bridge is constructed and passed into create_ouroboros_server(..., mcp_bridge=mcp_bridge)
• src/ouroboros/mcp/tools/definitions.py::execute_seed_handler added mcp_manager and mcp_tool_prefix parameters
• docs/guides/mcp-bridge.md records as a Known Limitation that evolve_step does not yet receive the manager

Problem

Per-handler injection is O(handlers). It has three failure modes:

1. A new handler silently omits the injection → runtime failure only.
2. Future plumbing (event store, LLM backend, directive emitter) compounds the parameter list.
3. Dynamic capability addition (also a stated limitation: "No dynamic server addition after initial connection") has no seam to plug into — each handler holds a static reference.

Proposal

Introduce a single PolicyBus object (name open — ControlBus / DirectiveBus are alternatives) that owns the dependencies currently passed à la carte:

@dataclass
class PolicyBus:
    event_store: EventStore
    mcp_manager: MCPClientManager | None   # from MCPBridge, optional
    directive_emitter: DirectiveEmitter    # emits ControlDirectiveEmitted
    llm_backend: str | None
    runtime_backend: str | None
    # ... single source of shared dependencies

Construction: once per server lifecycle, at _run_mcp_server time. Handlers receive PolicyBus by reference.

Handler contract change

Before:

ExecuteSeedHandler(
    event_store=event_store,
    mcp_manager=mcp_manager,
    mcp_tool_prefix=prefix,
    runtime_backend=rb,
    llm_backend=lb,
)

After:

ExecuteSeedHandler(bus=bus)

Dynamic capability support

Because PolicyBus holds a live reference to the manager, future dynamic add_server calls on the manager propagate to all handlers without re-injection — unlocking the second half of #280's Known Limitations.

Migration strategy

1. Introduce PolicyBus as an additive type; existing constructors unchanged.
2. Add a from_bus classmethod to each handler: ExecuteSeedHandler.from_bus(bus) constructs with the legacy arguments derived from the bus.
3. Migrate call sites one at a time. Deprecate the legacy constructors.
4. Remove legacy constructors in a subsequent release.

Acceptance Criteria

• PolicyBus lives under src/ouroboros/orchestrator/ (or core/ — final location decided in review)
• _run_mcp_server constructs a single bus and passes it to create_ouroboros_server
• ExecuteSeedHandler accepts the bus and its unit tests pass unchanged
• Deprecation warnings on legacy constructors
• A worked example PR (separate, linked here) demonstrates adding a new handler with a 1-file change, proving O(1) plumbing

Out of Scope

• Migrating evolve_step, unstuck, ralph — that is the next sibling issue
• Adding new directives to the vocabulary — that is the Directive vocabulary issue
• Reshaping the Double-Diamond execution pipeline

Risks

• Large blast radius: handler signatures change broadly. Mitigation: classmethod bridge (from_bus) plus staged migration.
• Hidden coupling: a "god object" bus can accumulate unrelated fields. Mitigation: keep the struct flat and reviewed on every addition; document membership criteria.

[shaun0927]

Design proposal (for needs-design removal)

Grounded in the post-#280 plumbing shape (src/ouroboros/cli/commands/mcp.py, src/ouroboros/mcp/tools/definitions.py::execute_seed_handler).

Type

# src/ouroboros/orchestrator/policy_bus.py
@dataclass(frozen=True, slots=True)
class PolicyBus:
    event_store: EventStore
    runtime_backend: str | None
    llm_backend: str | None
    mcp_manager: MCPClientManager | None = None
    mcp_tool_prefix: str = ""
    # future: directive_emitter (after #473-a lands)

Frozen + slots to match the rest of core/ (Result, ACNode, etc.). Optional mcp_manager preserves the current optional-bridge behavior from #280.

Handler contract change

Legacy constructor preserved through the migration:

# Today (unchanged in the first PR of this series):
ExecuteSeedHandler(
    event_store=event_store,
    mcp_manager=mcp_manager,
    mcp_tool_prefix=prefix,
    runtime_backend=rb,
    llm_backend=lb,
)

# New path, added side-by-side:
ExecuteSeedHandler.from_bus(bus)

from_bus is a thin @classmethod that unpacks bus fields into the existing constructor. No behavior change; tests that use the legacy constructor stay green.

Migration strategy — 3 PRs

Following the surgical-PR pattern (e.g., #470, #461, #467) rather than one large refactor:

1. 474-a feat(orchestrator): introduce PolicyBus + handler.from_bus classmethod

   • Add the type + the single classmethod on ExecuteSeedHandler. No call-site changes.
   • All existing tests remain untouched.
   • ~100 LOC + tests.

2. 474-b refactor(mcp): construct PolicyBus in _run_mcp_server

   • src/ouroboros/cli/commands/mcp.py builds a single bus.
   • create_ouroboros_server(..., bus=bus) starts accepting the bus; legacy kwargs kept.
   • Proves the O(1) plumbing claim inside the codebase.

3. 474-c refactor(mcp): deprecate per-handler mcp_manager kwargs

   • DeprecationWarning on legacy handler constructors.
   • Follow-up issue Wire evolve_step / unstuck / ralph through PolicyBus (closes #280 known limitations) #475 consumes the bus in evolve_step / unstuck / ralph (3 PRs), at which point the legacy constructors can be removed in a separate release.

Alternatives considered

• Inject into a module-level singleton — rejected. The repo deliberately avoids globals (see core/ lazy-loader rationale; runtime backends are constructed per-session via factories). A bus tied to _run_mcp_server lifetime preserves that discipline.
• Subclass-per-handler — rejected. Would explode the orchestrator surface and duplicate constructor plumbing instead of eliminating it.
• Call it ControlBus / DirectiveBus — reasonable. I lean PolicyBus because it is intended to carry directive sources, not the directive values themselves (which live on Directive in Introduce unified Directive vocabulary for the control plane #472). Happy to rename if maintainers prefer.

What this issue is not

• Not a change to the Double-Diamond execution pipeline.
• Not a change to the 3-stage evaluation semantics.
• Not a general-purpose DI container. The struct stays flat; additions require review justification.

Ask

If the structure + migration split look acceptable, I'd like to remove the needs-design label and open 474-a as a small additive PR (no call-site changes). Any objections to the name, the optional-mcp_manager default, or the three-step migration — please flag before the code PR lands.

[shaun0927]

Design update — adopting AgentRuntimeContext + ControlBus (per #476)

Superseding the earlier PolicyBus proposal on this issue. The rename is endorsed in my reply at #476#issuecomment-4294892689 (Q1); this comment records the concrete shape we'll use.

Type (revised)

# src/ouroboros/orchestrator/runtime_context.py
@dataclass(frozen=True, slots=True)
class AgentRuntimeContext:
    event_store: EventStore
    runtime_backend: str | None
    llm_backend: str | None
    mcp_bridge: MCPBridge | None = None     # capability source
    # Added in follow-ups, not in the first PR:
    # directive_emitter: DirectiveEmitter
    # policy_decisions: PolicyDecisionView

class ControlBus:
    """Emission + subscription surface for Directive values.

    Handlers emit via context.control.emit(directive, reason=...).
    Subscribers receive live projections of control.directive.emitted events.
    """

Both types honor the #476 guardrails:

• Not a service locator. Membership stays frozen; additions require a PR-body justification.
• Control vs capability stay distinct. ControlBus handles directives; capability resolution flows through context.capabilities (landed in a later phase).
• Replayability. Every emission produces a control.directive.emitted event (Add control_directive event category to EventStore #473/feat(events): add control.directive.emitted event factory #478) before reaching subscribers; persistence is primary.

Handler contract change (unchanged in spirit)

Legacy constructor preserved through the migration:

# Unchanged in the first PR:
ExecuteSeedHandler(
    event_store=event_store,
    mcp_manager=mcp_manager,
    mcp_tool_prefix=prefix,
    runtime_backend=rb,
    llm_backend=lb,
)

# New path, added side-by-side:
ExecuteSeedHandler.from_context(ctx)

from_context is a thin @classmethod that unpacks context fields into the existing constructor. Behavior-neutral; existing tests remain untouched.

Migration strategy — 3 PRs (names revised)

Following the surgical-PR pattern (#470, #461, #467), not a single large refactor:

1. 474-a feat(orchestrator): introduce AgentRuntimeContext + handler.from_context classmethod
   • Add the type + the single classmethod on ExecuteSeedHandler. No call-site changes.
   • ~100 LOC + tests.
2. 474-b refactor(mcp): construct AgentRuntimeContext in _run_mcp_server
   • cli/commands/mcp.py builds one context.
   • create_ouroboros_server(..., context=ctx) accepts it; legacy kwargs preserved.
   • Proves the O(1) plumbing claim inside the codebase.
3. 474-c refactor(mcp): deprecate per-handler mcp_manager kwargs
   • DeprecationWarning on legacy constructors. Removal in a later release.

Issue #475 then consumes the context in evolve_step / unstuck / ralph (3 PRs). The StepAction → Directive mapping established by the first migration (per Q5 in #476) becomes the reference pattern.

Alternatives considered (updated)

• Keeping PolicyBus — rejected per [RFC] Agent OS runtime contract: capabilities, policy, directives, and replayable agent processes #476 Q1. PolicyBus overloads policy decisions (capability eligibility) with directive flow (workflow control). The Agent OS framing separates these; so should the type names.
• Making AgentRuntimeContext mutable — rejected. frozen=True forces additions to go through code review rather than runtime mutation. Re-creation on capability change is a separate story ([RFC] Agent OS runtime contract: capabilities, policy, directives, and replayable agent processes #476 Q4).
• One fat AgentRuntimeContext with many optional fields — rejected. Starting narrow, with a documented "membership is expensive to add" rule, keeps the type honest.

What this issue is still not

• Not a change to the Double-Diamond execution pipeline.
• Not a change to the 3-stage evaluation semantics.
• Not a general-purpose DI container.
• Not the Phase 3 AgentProcess layer ([RFC] Agent OS runtime contract: capabilities, policy, directives, and replayable agent processes #476) — that stays out of scope here.

Ask

If the revised shape is acceptable, I'll open 474-a with the narrow struct + from_context classmethod. Objections to the membership list, the frozen-slots stance, or the three-step migration — please flag before the code PR lands.