ouroboros-ai 0.31.2.dev18__tar.gz → 0.31.2.dev20__tar.gz

{ouroboros_ai-0.31.2.dev18 → ouroboros_ai-0.31.2.dev20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev18
+Version: 0.31.2.dev20
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.31.2.dev18 → ouroboros_ai-0.31.2.dev20}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.31.2.dev18'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev18')
+__version__ = version = '0.31.2.dev20'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev20')
 
 __commit_id__ = commit_id = None

ouroboros_ai-0.31.2.dev20/src/ouroboros/mcp/tools/bridge_mixin.py

@@ -0,0 +1,104 @@
+"""BridgeAwareMixin for MCP tool handlers that need external MCP access.
+
+Handlers that inherit from this mixin will automatically receive
+an MCPClientManager reference when an MCPBridge is configured,
+via loop-based injection in the composition root.
+
+This module exposes two equivalent injection helpers:
+
+* :func:`inject_bridge` — original entry point. Accepts a raw
+  ``MCPBridge`` instance and populates the mixin fields.
+* :func:`inject_runtime_context` — context-aware entry point added by
+  #474. Accepts an :class:`AgentRuntimeContext` and pulls the bridge
+  off it. Subsequent ``mcp_manager`` plumbing migrations (#474 PR-3
+  through PR-5) gradually swap call sites at the composition root from
+  the legacy form to this one, then move handler internals to read
+  ``context.mcp_bridge`` directly instead of ``self.mcp_manager``.
+
+Both helpers are additive: the legacy form continues to work for
+callers that have not yet adopted the runtime context, so the
+migration can land in small reviewable slices without a flag day.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ouroboros.orchestrator.agent_runtime_context import AgentRuntimeContext
+
+
+@dataclass
+class BridgeAwareMixin:
+    """Mixin for handlers that need access to external MCP servers.
+
+    Provides ``mcp_manager`` and ``mcp_tool_prefix`` fields that are
+    injected by the composition root when an MCPBridge is configured.
+    Both fields default to None/"" so handlers work without a bridge.
+
+    Usage::
+
+        @dataclass
+        class MyHandler(BridgeAwareMixin):
+            other_field: str = ""
+
+            async def handle(self, arguments):
+                if self.mcp_manager:
+                    tools = await self.mcp_manager.list_all_tools()
+    """
+
+    mcp_manager: Any | None = field(default=None, repr=False)
+    mcp_tool_prefix: str = ""
+
+
+def inject_bridge(handler: object, bridge: object | None) -> bool:
+    """Inject bridge manager into a BridgeAwareMixin handler.
+
+    Args:
+        handler: A tool handler, possibly BridgeAwareMixin.
+        bridge: An MCPBridge instance (must have .manager and .tool_prefix).
+
+    Returns:
+        True if injection was performed, False otherwise.
+    """
+    if bridge is None or not isinstance(handler, BridgeAwareMixin):
+        return False
+
+    handler.mcp_manager = getattr(bridge, "manager", None)
+    handler.mcp_tool_prefix = getattr(bridge, "tool_prefix", "")
+    return True
+
+
+def inject_runtime_context(
+    handler: object,
+    context: AgentRuntimeContext | None,
+) -> bool:
+    """Inject the ``AgentRuntimeContext``'s bridge into a mixin handler.
+
+    Equivalent to calling :func:`inject_bridge` with
+    ``context.mcp_bridge`` but accepts the runtime context directly.
+    This is the entry point subsequent #474 PRs use at the composition
+    root so handlers can reach the bridge through the same context
+    object that already carries the EventStore and the
+    :class:`ControlBus` (per #476 Q1's narrow-membership commitment).
+
+    Args:
+        handler: A tool handler, possibly :class:`BridgeAwareMixin`.
+        context: The :class:`AgentRuntimeContext` carrying the runtime's
+            optional MCP bridge. Passing ``None`` is treated as
+            "no bridge available" and skips injection — that keeps the
+            non-MCP code paths valid.
+
+    Returns:
+        ``True`` if injection was performed; ``False`` otherwise.
+
+    The function is intentionally a thin adapter so the legacy
+    :func:`inject_bridge` code path remains the single source of truth
+    for the actual attribute write. When the migration is complete and
+    every caller flows through this helper, the legacy entry point can
+    be deprecated without behaviour change.
+    """
+    if context is None:
+        return False
+    return inject_bridge(handler, context.mcp_bridge)

ouroboros_ai-0.31.2.dev20/src/ouroboros/orchestrator/agent_runtime_context.py

@@ -0,0 +1,45 @@
+"""``AgentRuntimeContext`` — the runtime-offering side of #476 Q1.
+
+The runtime context describes *what the orchestrator runtime offers* a
+handler — the EventStore it appends into, optional capability sources,
+and the :class:`ControlBus` that lets handlers react to directive events.
+The context is intentionally narrow: per the maintainer commitment in
+#476 Q1, every new field added later must include a one-line PR-body
+justification so the type does not drift into a service locator.
+
+This first step keeps the membership minimal:
+
+* ``event_store`` — the persistence boundary handlers already share.
+* ``runtime_backend`` / ``llm_backend`` — informational labels existing
+  callers (rate-limit, telemetry) already pass alongside the bridge.
+* ``mcp_bridge`` — the existing capability source from #280's bridge
+  work; optional so non-MCP code paths stay valid.
+* ``control`` — the :class:`ControlBus` introduced alongside this
+  context; ``None`` while #474's migration is in progress so existing
+  callers compile unchanged.
+
+Subsequent issues (#474, #475) wire concrete handlers to consume the
+context. This module deliberately does *not* import any handler-side
+type so that adopting the context becomes a one-import change.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ouroboros.mcp.bridge.bridge import MCPBridge
+    from ouroboros.orchestrator.control_bus import ControlBus
+    from ouroboros.persistence.event_store import EventStore
+
+
+@dataclass(frozen=True, slots=True)
+class AgentRuntimeContext:
+    """Minimal, narrow-membership runtime context handed to MCP handlers."""
+
+    event_store: EventStore
+    runtime_backend: str | None = None
+    llm_backend: str | None = None
+    mcp_bridge: MCPBridge | None = None
+    control: ControlBus | None = None

ouroboros_ai-0.31.2.dev20/src/ouroboros/orchestrator/control_bus.py

@@ -0,0 +1,163 @@
+"""In-process ControlBus for ``control.directive.emitted`` events.
+
+The bus is the *reactive* surface paired with the *observational* event
+factory landed in #492. Subscribers register a predicate and a handler;
+when callsites publish a directive event onto the bus, every matching
+handler fires concurrently on its own task. A slow or failing handler
+never blocks other handlers or the publisher.
+
+Per the maintainer alignment in #476 Q1, the bus is exposed as
+``AgentRuntimeContext.control`` (see :mod:`agent_runtime_context`). The
+context describes *what the runtime offers*; the bus describes *where
+directives flow*. Two different concerns, two different names.
+
+Scope choices baked in here:
+
+* The bus does *not* know about persistence. EventStore stays simple;
+  callsites call :meth:`ControlBus.publish` themselves after
+  :meth:`EventStore.append`. This honours the "no service locator"
+  guardrail from #476 Q1 (narrow membership for the runtime context) and
+  keeps the bus a pure in-process primitive that future callers — for
+  example the #474 ``AgentRuntimeContext`` migration and #475
+  ``evolve_step`` / ``unstuck`` / ``ralph`` wiring — can adopt
+  incrementally.
+
+* Cross-runtime delivery is a *separate* concern; that is the Mesh
+  (sub-RFC :doc:`../../docs/rfc/mesh`). The Mesh, when it lands, can
+  reuse this surface or wrap it.
+
+* Forging resistance is *not* a goal. The cooperative-trust model from
+  #476 explicitly accepts that any in-process actor can publish; the bus
+  does not police identity.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ouroboros.events.base import BaseEvent
+
+
+logger = logging.getLogger(__name__)
+
+
+Predicate = Callable[["BaseEvent"], bool]
+Handler = Callable[["BaseEvent"], Awaitable[None]]
+
+
+@dataclass(frozen=True, slots=True)
+class SubscriptionHandle:
+    """Opaque token returned by :meth:`ControlBus.subscribe`.
+
+    Callers pass it back to :meth:`ControlBus.unsubscribe` to detach.
+    Handles are scoped to the bus that created them so identical local
+    integer IDs from different buses cannot detach each other.
+    """
+
+    _id: int
+    _owner: Any
+
+
+@dataclass(slots=True)
+class _Subscription:
+    """One predicate/handler pair tracked by the bus."""
+
+    handle: SubscriptionHandle
+    predicate: Predicate
+    handler: Handler
+
+
+@dataclass(slots=True)
+class ControlBus:
+    """Concurrent in-process publish/subscribe surface for control events.
+
+    The bus is intended to live on :class:`AgentRuntimeContext` for the
+    lifetime of an orchestrator session. It is **not** thread-safe in the
+    classic shared-memory sense; it expects a single asyncio event loop.
+    """
+
+    _subscriptions: list[_Subscription] = field(default_factory=list)
+    _next_id: int = 0
+    _owner: object = field(default_factory=object)
+    _tasks: set[asyncio.Task[None]] = field(default_factory=set)
+    _spawn: Callable[[Awaitable[None]], asyncio.Task[None]] | None = None
+
+    def subscribe(self, predicate: Predicate, handler: Handler) -> SubscriptionHandle:
+        """Register *handler* to be invoked when *predicate* returns ``True``.
+
+        Args:
+            predicate: Pure synchronous filter on the event. Predicate
+                exceptions are treated like ``False`` and logged so a
+                broken predicate cannot starve other subscribers.
+            handler: Async callable invoked once per matching event. The
+                handler is awaited on its own task so a slow handler does
+                not block fast ones.
+
+        Returns:
+            A :class:`SubscriptionHandle` accepted by
+            :meth:`unsubscribe`.
+        """
+        handle = SubscriptionHandle(_id=self._next_id, _owner=self._owner)
+        self._next_id += 1
+        self._subscriptions.append(
+            _Subscription(handle=handle, predicate=predicate, handler=handler)
+        )
+        return handle
+
+    def unsubscribe(self, handle: SubscriptionHandle) -> None:
+        """Remove the subscription identified by *handle*.
+
+        Idempotent: detaching an unknown or already-removed handle is a
+        no-op.
+        """
+        if handle._owner is not self._owner:
+            return
+        self._subscriptions = [sub for sub in self._subscriptions if sub.handle != handle]
+
+    def publish(self, event: BaseEvent) -> tuple[asyncio.Task[None], ...]:
+        """Spawn a delivery task for every matching subscription.
+
+        Returns a tuple of the spawned tasks so tests can ``await`` them.
+        Production callers can ignore the return value: handler errors
+        are logged on the task so they cannot poison the publisher.
+
+        A subscription whose predicate raises an exception is treated as
+        non-matching for that event; the predicate is not unsubscribed.
+        """
+        spawned: list[asyncio.Task[None]] = []
+        for sub in tuple(self._subscriptions):
+            try:
+                if not sub.predicate(event):
+                    continue
+            except Exception as exc:  # noqa: BLE001 — predicate isolation
+                logger.warning(
+                    "control_bus.predicate_raised",
+                    extra={"handle_id": sub.handle._id, "error": repr(exc)},
+                )
+                continue
+
+            spawned.append(self._spawn_handler(sub.handler, event))
+        return tuple(spawned)
+
+    def _spawn_handler(self, handler: Handler, event: BaseEvent) -> asyncio.Task[None]:
+        """Run *handler* on its own task with structured error isolation."""
+        spawn = self._spawn or asyncio.ensure_future
+        task = spawn(self._invoke_handler(handler, event))
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+        return task
+
+    @staticmethod
+    async def _invoke_handler(handler: Handler, event: BaseEvent) -> None:
+        try:
+            await handler(event)
+        except Exception as exc:  # noqa: BLE001 — handler isolation
+            logger.warning(
+                "control_bus.handler_raised",
+                extra={"event_type": event.type, "error": repr(exc)},
+            )

ouroboros_ai-0.31.2.dev20/tests/unit/mcp/tools/test_bridge_mixin_runtime_context.py

@@ -0,0 +1,111 @@
+"""Unit tests for the AgentRuntimeContext-aware bridge injection helper.
+
+Issue: #474 PR-1 of the AgentRuntimeContext + ControlBus migration.
+The new ``inject_runtime_context`` helper is purely additive — the
+legacy ``inject_bridge`` continues to work, and handler internals are
+unchanged. Subsequent migration PRs swap composition-root call sites
+from the legacy form to this one, then move handler internals to read
+``context.mcp_bridge`` directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ouroboros.mcp.tools.bridge_mixin import (
+    BridgeAwareMixin,
+    inject_bridge,
+    inject_runtime_context,
+)
+from ouroboros.orchestrator.agent_runtime_context import AgentRuntimeContext
+from ouroboros.persistence.event_store import EventStore
+
+
+@dataclass
+class _FakeBridge:
+    """Minimal stand-in for ``MCPBridge`` carrying the two attributes the mixin reads."""
+
+    manager: Any = None
+    tool_prefix: str = ""
+
+
+@dataclass
+class _FakeHandler(BridgeAwareMixin):
+    """Subclass that does nothing extra — exercises the mixin in isolation."""
+
+    extra_field: str = field(default="")
+
+
+def _runtime_context(bridge: _FakeBridge | None = None) -> AgentRuntimeContext:
+    """Build a minimal runtime context for tests."""
+    store = EventStore("sqlite+aiosqlite:///:memory:")
+    return AgentRuntimeContext(event_store=store, mcp_bridge=bridge)
+
+
+class TestInjectRuntimeContext:
+    def test_injects_bridge_from_context(self) -> None:
+        """A handler with the mixin receives the bridge from context.mcp_bridge."""
+        manager = object()
+        bridge = _FakeBridge(manager=manager, tool_prefix="ext_")
+        context = _runtime_context(bridge=bridge)
+        handler = _FakeHandler()
+
+        assert inject_runtime_context(handler, context) is True
+        assert handler.mcp_manager is manager
+        assert handler.mcp_tool_prefix == "ext_"
+
+    def test_returns_false_when_context_is_none(self) -> None:
+        """``None`` context is treated as 'no bridge' — non-MCP paths stay valid."""
+        handler = _FakeHandler()
+        assert inject_runtime_context(handler, None) is False
+        assert handler.mcp_manager is None
+        assert handler.mcp_tool_prefix == ""
+
+    def test_returns_false_when_context_has_no_bridge(self) -> None:
+        """A context without an mcp_bridge does not write to the handler."""
+        context = _runtime_context(bridge=None)
+        handler = _FakeHandler()
+
+        assert inject_runtime_context(handler, context) is False
+        assert handler.mcp_manager is None
+
+    def test_returns_false_when_handler_lacks_mixin(self) -> None:
+        """Handlers that do not inherit from BridgeAwareMixin are skipped."""
+
+        class _BareHandler:
+            mcp_manager: Any = None
+            mcp_tool_prefix: str = ""
+
+        bridge = _FakeBridge(manager=object(), tool_prefix="ext_")
+        context = _runtime_context(bridge=bridge)
+        handler = _BareHandler()
+
+        assert inject_runtime_context(handler, context) is False
+        assert handler.mcp_manager is None
+        assert handler.mcp_tool_prefix == ""
+
+    def test_legacy_inject_bridge_still_works(self) -> None:
+        """The original entry point keeps the same contract."""
+        manager = object()
+        bridge = _FakeBridge(manager=manager, tool_prefix="ext_")
+        handler = _FakeHandler()
+
+        assert inject_bridge(handler, bridge) is True
+        assert handler.mcp_manager is manager
+        assert handler.mcp_tool_prefix == "ext_"
+
+    def test_runtime_context_and_legacy_paths_are_equivalent(self) -> None:
+        """Both helpers must produce the same handler state for the same bridge."""
+        manager = object()
+        bridge = _FakeBridge(manager=manager, tool_prefix="ext_")
+        context = _runtime_context(bridge=bridge)
+
+        legacy = _FakeHandler()
+        modern = _FakeHandler()
+
+        inject_bridge(legacy, bridge)
+        inject_runtime_context(modern, context)
+
+        assert legacy.mcp_manager is modern.mcp_manager
+        assert legacy.mcp_tool_prefix == modern.mcp_tool_prefix

ouroboros_ai-0.31.2.dev20/tests/unit/orchestrator/test_agent_runtime_context.py

@@ -0,0 +1,63 @@
+"""Unit tests for :class:`AgentRuntimeContext`.
+
+Issue: #515 / #474 Q1. The context is intentionally narrow: it must
+remain frozen, slot-based, and only carry the minimal fields the
+maintainer alignment in #476 Q1 specified.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from ouroboros.orchestrator.agent_runtime_context import AgentRuntimeContext
+from ouroboros.orchestrator.control_bus import ControlBus
+from ouroboros.persistence.event_store import EventStore
+
+
+def test_context_is_frozen_and_slotted() -> None:
+    """The dataclass must reject attribute mutation post-construction."""
+    store = EventStore("sqlite+aiosqlite:///:memory:")
+    context = AgentRuntimeContext(event_store=store)
+
+    assert dataclasses.is_dataclass(context)
+    assert context.runtime_backend is None
+    assert context.llm_backend is None
+    assert context.mcp_bridge is None
+    assert context.control is None
+
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        context.runtime_backend = "codex_cli"  # type: ignore[misc]
+
+
+def test_context_carries_optional_control_bus() -> None:
+    """The optional ControlBus slot is the reactive surface for #515."""
+    store = EventStore("sqlite+aiosqlite:///:memory:")
+    bus = ControlBus()
+    context = AgentRuntimeContext(event_store=store, control=bus)
+
+    assert context.control is bus
+    # Existing handlers that do not opt into the bus still see the
+    # default ``None`` and remain valid.
+    no_bus = AgentRuntimeContext(event_store=store)
+    assert no_bus.control is None
+
+
+def test_context_membership_is_narrow() -> None:
+    """Adding a field requires a deliberate PR (no service-locator drift).
+
+    This regression test pins the field set so reviewers see explicit
+    diffs when the membership grows. If this assertion fails because a
+    field was added, the PR must include a justification line per the
+    #476 Q1 narrow-membership commitment.
+    """
+    expected = {
+        "event_store",
+        "runtime_backend",
+        "llm_backend",
+        "mcp_bridge",
+        "control",
+    }
+    actual = {f.name for f in dataclasses.fields(AgentRuntimeContext)}
+    assert actual == expected