ouroboros-ai 0.31.2.dev29__tar.gz → 0.31.2.dev36__tar.gz

{ouroboros_ai-0.31.2.dev29 → ouroboros_ai-0.31.2.dev36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev29
+Version: 0.31.2.dev36
 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.dev29 → ouroboros_ai-0.31.2.dev36}/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.dev29'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev29')
+__version__ = version = '0.31.2.dev36'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev36')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.31.2.dev29 → ouroboros_ai-0.31.2.dev36}/src/ouroboros/events/io.py

@@ -36,6 +36,7 @@ from __future__ import annotations
 
 from enum import StrEnum
 import hashlib
+import logging
 import os
 import re
 import secrets
@@ -44,6 +45,9 @@ from typing import Any, Final
 
 from ouroboros.events.base import BaseEvent
 
+logger = logging.getLogger(__name__)
+_WARNED_INVALID_PRIVACY_VALUES: set[str] = set()
+
 # ---------------------------------------------------------------------------
 # Constants
 # ---------------------------------------------------------------------------
@@ -94,15 +98,29 @@ class PrivacyMode(StrEnum):
 def get_privacy_mode() -> PrivacyMode:
     """Resolve the active privacy mode from the environment.
 
-    Unknown values fall back to :attr:`PrivacyMode.ON`. The env var is
-    read on every call so tests can flip it without restarting the
-    process; this is fine because the read is `os.environ.get`-cheap.
+    Unset values preserve the cooperative-trust default
+    (:attr:`PrivacyMode.ON`). Explicit but unknown values fail closed to
+    :attr:`PrivacyMode.OFF` so a typo never preserves raw previews. The
+    env var is read on every call so tests can flip it without
+    restarting the process; this is fine because the read is
+    `os.environ.get`-cheap.
     """
-    raw = os.environ.get(PRIVACY_ENV_VAR, PrivacyMode.ON.value).lower()
+    configured = os.environ.get(PRIVACY_ENV_VAR)
+    if configured is None:
+        return PrivacyMode.ON
+    raw = configured.strip().lower()
     try:
         return PrivacyMode(raw)
     except ValueError:
-        return PrivacyMode.ON
+        if raw not in _WARNED_INVALID_PRIVACY_VALUES:
+            _WARNED_INVALID_PRIVACY_VALUES.add(raw)
+            logger.warning(
+                "Invalid %s=%r; falling back to %s to avoid preserving I/O previews",
+                PRIVACY_ENV_VAR,
+                configured,
+                PrivacyMode.OFF.value,
+            )
+        return PrivacyMode.OFF
 
 
 # ---------------------------------------------------------------------------

{ouroboros_ai-0.31.2.dev29 → ouroboros_ai-0.31.2.dev36}/src/ouroboros/mcp/server/adapter.py

@@ -36,7 +36,7 @@ from ouroboros.mcp.types import (
     ToolInputType,
 )
 from ouroboros.orchestrator.agent_runtime_context import AgentRuntimeContext
-from ouroboros.orchestrator.control_bus import ControlBus
+from ouroboros.orchestrator.control_bus import ControlBus, ControlBusDrainError
 
 log = structlog.get_logger(__name__)
 
@@ -721,6 +721,12 @@ class MCPServerAdapter:
             if callable(close_fn):
                 try:
                     await close_fn()
+                except ControlBusDrainError:
+                    log.error(
+                        "mcp.server.control_bus_close_failed",
+                        resource=type(resource).__name__,
+                    )
+                    raise
                 except Exception as exc:
                     log.warning(
                         "mcp.server.resource_close_failed",
@@ -1467,25 +1473,28 @@ def create_ouroboros_server(
         rate_limit_config=rate_limit_config,
     )
 
-    # The server owns the shared event store lifecycle
-    server.register_owned_resource(event_store)
-    if brownfield_store is not None:
-        server.register_owned_resource(brownfield_store)
-
     # Build the AgentRuntimeContext that #474 funnels through every
     # handler. For now the context only exposes the EventStore, the
     # backend labels, the optional MCP bridge, and a fresh ControlBus
     # for #515. Subsequent migration slices move handler internals to
     # consume context.mcp_bridge directly instead of self.mcp_manager.
+    control_bus = ControlBus()
     agent_runtime_context = AgentRuntimeContext(
         event_store=event_store,
         runtime_backend=resolved_runtime_backend,
         llm_backend=llm_backend,
         mcp_bridge=mcp_bridge,
-        control=ControlBus(),
+        control=control_bus,
     )
     server.set_runtime_context(agent_runtime_context)
 
+    # Close the reactive control surface before stores/bridges it may
+    # reference from subscriber tasks.
+    server.register_owned_resource(control_bus)
+    server.register_owned_resource(event_store)
+    if brownfield_store is not None:
+        server.register_owned_resource(brownfield_store)
+
     # Inject the bridge from the runtime context into every
     # BridgeAwareMixin handler. ``inject_runtime_context`` is byte-
     # equivalent to the legacy ``inject_bridge`` for the same bridge —

{ouroboros_ai-0.31.2.dev29 → ouroboros_ai-0.31.2.dev36}/src/ouroboros/orchestrator/control_bus.py

@@ -45,11 +45,18 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_CLOSE_TIMEOUT_S = 1.0
+DEFAULT_CANCEL_TIMEOUT_S = 0.1
+
 
 Predicate = Callable[["BaseEvent"], bool]
 Handler = Callable[["BaseEvent"], Awaitable[None]]
 
 
+class ControlBusDrainError(RuntimeError):
+    """Raised when subscriber tasks refuse to quiesce during shutdown."""
+
+
 @dataclass(frozen=True, slots=True)
 class SubscriptionHandle:
     """Opaque token returned by :meth:`ControlBus.subscribe`.
@@ -86,6 +93,9 @@ class ControlBus:
     _owner: object = field(default_factory=object)
     _tasks: set[asyncio.Task[None]] = field(default_factory=set)
     _spawn: Callable[[Awaitable[None]], asyncio.Task[None]] | None = None
+    _closed: bool = False
+    _close_timeout_s: float | None = DEFAULT_CLOSE_TIMEOUT_S
+    _cancel_timeout_s: float | None = DEFAULT_CANCEL_TIMEOUT_S
 
     def subscribe(self, predicate: Predicate, handler: Handler) -> SubscriptionHandle:
         """Register *handler* to be invoked when *predicate* returns ``True``.
@@ -102,6 +112,9 @@ class ControlBus:
             A :class:`SubscriptionHandle` accepted by
             :meth:`unsubscribe`.
         """
+        if self._closed:
+            msg = "Cannot subscribe to a closed ControlBus"
+            raise RuntimeError(msg)
         handle = SubscriptionHandle(_id=self._next_id, _owner=self._owner)
         self._next_id += 1
         self._subscriptions.append(
@@ -129,6 +142,12 @@ class ControlBus:
         A subscription whose predicate raises an exception is treated as
         non-matching for that event; the predicate is not unsubscribed.
         """
+        if self._closed:
+            logger.debug(
+                "control_bus.publish_after_close",
+                extra={"event_type": event.type},
+            )
+            return ()
         spawned: list[asyncio.Task[None]] = []
         for sub in tuple(self._subscriptions):
             try:
@@ -161,3 +180,82 @@ class ControlBus:
                 "control_bus.handler_raised",
                 extra={"event_type": event.type, "error": repr(exc)},
             )
+
+    async def close(self) -> None:
+        """Close the bus and drain in-flight subscriber tasks.
+
+        Shutdown is idempotent. Once closed, the bus rejects new
+        subscriptions and turns publishes into no-ops so server teardown
+        cannot fan out new work while owned resources are closing.
+        """
+        if self._closed and not self._tasks:
+            return
+        self._closed = True
+        self._subscriptions.clear()
+        await self.drain(
+            timeout=self._close_timeout_s,
+            cancel_timeout=self._cancel_timeout_s,
+        )
+
+    async def drain(
+        self,
+        *,
+        timeout: float | None = DEFAULT_CLOSE_TIMEOUT_S,
+        cancel_timeout: float | None = DEFAULT_CANCEL_TIMEOUT_S,
+    ) -> None:
+        """Await pending subscriber tasks, cancelling stragglers after *timeout*.
+
+        ``timeout=None`` waits indefinitely before cancellation.
+        ``cancel_timeout=None`` waits indefinitely after cancellation.
+        Any task exceptions are collected so drain itself remains a
+        lifecycle cleanup primitive, not a second error channel.
+        """
+        pending = tuple(task for task in self._tasks if not task.done())
+        if not pending:
+            self._tasks.difference_update(task for task in self._tasks if task.done())
+            return
+
+        if timeout is None:
+            await asyncio.gather(*pending, return_exceptions=True)
+            self._tasks.difference_update(task for task in self._tasks if task.done())
+            return
+
+        done, still_pending = await asyncio.wait(pending, timeout=max(timeout, 0.0))
+        if done:
+            await asyncio.gather(*done, return_exceptions=True)
+        if still_pending:
+            logger.warning(
+                "control_bus.drain_timeout",
+                extra={"pending_tasks": len(still_pending), "timeout_s": timeout},
+            )
+            for task in still_pending:
+                task.cancel()
+            if cancel_timeout is None:
+                await asyncio.gather(*still_pending, return_exceptions=True)
+            else:
+                cancelled_done, still_running = await asyncio.wait(
+                    still_pending,
+                    timeout=max(cancel_timeout, 0.0),
+                )
+                if cancelled_done:
+                    await asyncio.gather(*cancelled_done, return_exceptions=True)
+                if still_running:
+                    finished_after_wait = tuple(task for task in still_running if task.done())
+                    if finished_after_wait:
+                        await asyncio.gather(*finished_after_wait, return_exceptions=True)
+                    still_running = {task for task in still_running if not task.done()}
+                if still_running:
+                    logger.error(
+                        "control_bus.cancel_timeout",
+                        extra={
+                            "pending_tasks": len(still_running),
+                            "timeout_s": cancel_timeout,
+                        },
+                    )
+                    self._tasks.difference_update(task for task in self._tasks if task.done())
+                    msg = (
+                        f"{len(still_running)} ControlBus subscriber task(s) "
+                        "ignored cancellation during shutdown"
+                    )
+                    raise ControlBusDrainError(msg)
+        self._tasks.difference_update(task for task in self._tasks if task.done())

{ouroboros_ai-0.31.2.dev29 → ouroboros_ai-0.31.2.dev36}/tests/unit/events/test_io_events.py

@@ -108,10 +108,41 @@ class TestPrivacyMode:
             assert get_privacy_mode() is mode
         monkeypatch.setenv(PRIVACY_ENV_VAR, "OFF")
         assert get_privacy_mode() is PrivacyMode.OFF
-
-    def test_unknown_value_falls_back_to_on(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv(PRIVACY_ENV_VAR, " redacted ")
+        assert get_privacy_mode() is PrivacyMode.REDACTED
+
+    def test_unknown_value_fails_closed_to_off(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
         monkeypatch.setenv(PRIVACY_ENV_VAR, "loud")
-        assert get_privacy_mode() is PrivacyMode.ON
+        assert get_privacy_mode() is PrivacyMode.OFF
+        assert PRIVACY_ENV_VAR in caplog.text
+
+    def test_invalid_env_value_does_not_preserve_preview(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv(PRIVACY_ENV_VAR, "of")
+        assert shape_preview("SECRET prompt") is None
+
+    def test_invalid_value_warns_once_per_normalised_value(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        monkeypatch.setenv(PRIVACY_ENV_VAR, " noisy ")
+        assert get_privacy_mode() is PrivacyMode.OFF
+        assert get_privacy_mode() is PrivacyMode.OFF
+        monkeypatch.setenv(PRIVACY_ENV_VAR, "NOISY")
+        assert get_privacy_mode() is PrivacyMode.OFF
+
+        warnings = [
+            record
+            for record in caplog.records
+            if "Invalid OUROBOROS_IO_JOURNAL_PREVIEWS" in record.message
+        ]
+        assert len(warnings) == 1
 
 
 class TestTruncatePreview:

{ouroboros_ai-0.31.2.dev29 → ouroboros_ai-0.31.2.dev36}/tests/unit/mcp/server/test_adapter.py

@@ -1,5 +1,6 @@
 """Tests for MCP server adapter."""
 
+import asyncio
 from types import SimpleNamespace
 from typing import Any
 from unittest.mock import AsyncMock
@@ -7,6 +8,7 @@ from unittest.mock import AsyncMock
 import pytest
 
 from ouroboros.core.types import Result
+from ouroboros.events.base import BaseEvent
 from ouroboros.mcp.errors import MCPResourceNotFoundError, MCPServerError
 from ouroboros.mcp.server.adapter import (
     VALID_TRANSPORTS,
@@ -28,6 +30,7 @@ from ouroboros.mcp.types import (
     MCPToolResult,
     ToolInputType,
 )
+from ouroboros.orchestrator.control_bus import ControlBus, ControlBusDrainError
 
 
 class MockToolHandler:
@@ -1031,7 +1034,8 @@ class TestCreateOuroborosServerBrownfieldStore:
             )
 
         assert captured_handler_kwargs["_store"] is mock_brownfield_store
-        assert server._owned_resources == [mock_event_store, mock_brownfield_store]
+        assert isinstance(server._owned_resources[0], ControlBus)
+        assert server._owned_resources[1:] == [mock_event_store, mock_brownfield_store]
 
 
 def test_create_ouroboros_server_retains_runtime_context() -> None:
@@ -1044,3 +1048,83 @@ def test_create_ouroboros_server_retains_runtime_context() -> None:
     assert server.runtime_context.runtime_backend == "codex"
     assert server.runtime_context.llm_backend == "claude_code"
     assert server.runtime_context.control is not None
+
+
+@pytest.mark.asyncio
+async def test_server_shutdown_drains_runtime_control_bus() -> None:
+    """Server-owned ControlBus must not leave subscriber tasks behind."""
+    from ouroboros.mcp.server.adapter import create_ouroboros_server
+
+    server = create_ouroboros_server(runtime_backend="codex", llm_backend="claude_code")
+    assert server.runtime_context is not None
+    bus = server.runtime_context.control
+    assert bus is not None
+    bus._close_timeout_s = 0.01
+
+    started = asyncio.Event()
+
+    async def blocked(_event: BaseEvent) -> None:
+        started.set()
+        await asyncio.sleep(60)
+
+    bus.subscribe(lambda _event: True, blocked)
+    tasks = bus.publish(
+        BaseEvent(
+            type="control.directive.emitted",
+            aggregate_type="lineage",
+            aggregate_id="lin_shutdown_probe",
+            data={"directive": "cancel"},
+        )
+    )
+    await asyncio.wait_for(started.wait(), timeout=0.5)
+
+    await server.shutdown()
+
+    assert tasks[0].cancelled()
+    assert bus._tasks == set()
+    assert server._owned_resources == []
+
+
+@pytest.mark.asyncio
+async def test_server_shutdown_stops_before_dependents_when_control_bus_refuses_drain() -> None:
+    """Do not close dependent resources while control subscribers are still live."""
+    server = MCPServerAdapter()
+    bus = ControlBus(_close_timeout_s=0.01, _cancel_timeout_s=0.01)
+    started = asyncio.Event()
+    release = asyncio.Event()
+
+    class _DependentResource:
+        closed = False
+
+        async def close(self) -> None:
+            self.closed = True
+
+    resource = _DependentResource()
+
+    async def stubborn(_event: BaseEvent) -> None:
+        started.set()
+        try:
+            await asyncio.sleep(60)
+        except asyncio.CancelledError:
+            await release.wait()
+
+    server.register_owned_resource(bus)
+    server.register_owned_resource(resource)
+    bus.subscribe(lambda _event: True, stubborn)
+    tasks = bus.publish(
+        BaseEvent(
+            type="control.directive.emitted",
+            aggregate_type="lineage",
+            aggregate_id="lin_shutdown_probe",
+            data={"directive": "cancel"},
+        )
+    )
+    await asyncio.wait_for(started.wait(), timeout=0.5)
+
+    with pytest.raises(ControlBusDrainError):
+        await asyncio.wait_for(server.shutdown(), timeout=0.5)
+
+    assert resource.closed is False
+
+    release.set()
+    await asyncio.wait_for(tasks[0], timeout=0.5)

{ouroboros_ai-0.31.2.dev29 → ouroboros_ai-0.31.2.dev36}/tests/unit/orchestrator/test_control_bus.py

@@ -25,7 +25,11 @@ import asyncio
 import pytest
 
 from ouroboros.events.base import BaseEvent
-from ouroboros.orchestrator.control_bus import ControlBus, SubscriptionHandle
+from ouroboros.orchestrator.control_bus import (
+    ControlBus,
+    ControlBusDrainError,
+    SubscriptionHandle,
+)
 
 
 def _directive_event(directive: str = "retry") -> BaseEvent:
@@ -269,3 +273,125 @@ async def test_publish_retains_fire_and_forget_tasks_until_done() -> None:
     await asyncio.gather(*tasks)
     await asyncio.sleep(0)
     assert bus._tasks == set()
+
+
+@pytest.mark.asyncio
+async def test_close_drains_pending_tasks_and_stops_delivery() -> None:
+    bus = ControlBus()
+    release = asyncio.Event()
+    seen: list[str] = []
+
+    async def slow(event: BaseEvent) -> None:
+        await release.wait()
+        seen.append(event.type)
+
+    bus.subscribe(_is_directive, slow)
+    tasks = bus.publish(_directive_event())
+
+    assert len(tasks) == 1
+    assert len(bus._tasks) == 1
+
+    release.set()
+    await bus.close()
+
+    assert seen == ["control.directive.emitted"]
+    assert bus._tasks == set()
+    assert bus.publish(_directive_event()) == ()
+    with pytest.raises(RuntimeError, match="closed ControlBus"):
+        bus.subscribe(_is_directive, slow)
+
+
+@pytest.mark.asyncio
+async def test_close_cancels_stragglers_after_timeout() -> None:
+    bus = ControlBus(_close_timeout_s=0.01)
+    started = asyncio.Event()
+
+    async def blocked(event: BaseEvent) -> None:
+        started.set()
+        await asyncio.sleep(60)
+
+    bus.subscribe(_is_directive, blocked)
+    tasks = bus.publish(_directive_event())
+    await asyncio.wait_for(started.wait(), timeout=0.5)
+
+    await bus.close()
+
+    assert tasks[0].cancelled()
+    assert bus._tasks == set()
+
+
+@pytest.mark.asyncio
+async def test_close_does_not_hang_when_cancel_is_ignored() -> None:
+    bus = ControlBus(_close_timeout_s=0.01, _cancel_timeout_s=0.01)
+    started = asyncio.Event()
+    cancelled = asyncio.Event()
+    release = asyncio.Event()
+
+    async def stubborn(event: BaseEvent) -> None:
+        started.set()
+        try:
+            await asyncio.sleep(60)
+        except asyncio.CancelledError:
+            cancelled.set()
+            await release.wait()
+
+    bus.subscribe(_is_directive, stubborn)
+    tasks = bus.publish(_directive_event())
+    await asyncio.wait_for(started.wait(), timeout=0.5)
+
+    with pytest.raises(ControlBusDrainError, match="ignored cancellation"):
+        await asyncio.wait_for(bus.close(), timeout=0.5)
+
+    assert cancelled.is_set()
+    assert not tasks[0].done()
+
+    release.set()
+    await asyncio.wait_for(tasks[0], timeout=0.5)
+    await asyncio.sleep(0)
+    assert bus._tasks == set()
+
+
+@pytest.mark.asyncio
+async def test_close_does_not_raise_when_cancelled_task_finishes_after_wait(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A stale ``asyncio.wait`` pending set must not cause a false drain failure."""
+    bus = ControlBus(_close_timeout_s=0.01, _cancel_timeout_s=0.01)
+    started = asyncio.Event()
+    real_wait = asyncio.wait
+    wait_calls = 0
+
+    async def stale_second_wait(
+        awaitables: set[asyncio.Task[None]] | tuple[asyncio.Task[None], ...],
+        *,
+        timeout: float | None = None,
+    ) -> tuple[set[asyncio.Task[None]], set[asyncio.Task[None]]]:
+        nonlocal wait_calls
+        wait_calls += 1
+        done, pending = await real_wait(awaitables, timeout=timeout)
+        if wait_calls == 2 and pending:
+            stale_pending = set(pending)
+            await asyncio.wait_for(
+                asyncio.gather(*stale_pending, return_exceptions=True),
+                timeout=0.5,
+            )
+            return done, stale_pending
+        return done, pending
+
+    async def exits_after_cancel(event: BaseEvent) -> None:
+        started.set()
+        try:
+            await asyncio.sleep(60)
+        except asyncio.CancelledError:
+            await asyncio.sleep(0)
+
+    monkeypatch.setattr(asyncio, "wait", stale_second_wait)
+    bus.subscribe(_is_directive, exits_after_cancel)
+    tasks = bus.publish(_directive_event())
+    await asyncio.wait_for(started.wait(), timeout=0.5)
+
+    await bus.close()
+
+    assert tasks[0].done()
+    assert not tasks[0].cancelled()
+    assert bus._tasks == set()