ouroboros-ai 0.29.3.dev5__tar.gz → 0.29.3.dev6__tar.gz

{ouroboros_ai-0.29.3.dev5 → ouroboros_ai-0.29.3.dev6}/CLAUDE.md

@@ -32,6 +32,7 @@ When the user types any of these commands, read the corresponding SKILL.md file
 | `ooo pm` or `ooo pm ...` | Read `skills/pm/SKILL.md` and follow it |
 | `ooo brownfield` or `ooo brownfield ...` | Read `skills/brownfield/SKILL.md` and follow it |
 | `ooo publish` or `ooo publish ...` | Read `skills/publish/SKILL.md` and follow it |
+| `ooo resume` | Read `skills/resume/SKILL.md` and follow it |
 
 **Important**: Do NOT use the Skill tool. Read the file with the Read tool and execute its instructions directly.
 

{ouroboros_ai-0.29.3.dev5 → ouroboros_ai-0.29.3.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.29.3.dev5
+Version: 0.29.3.dev6
 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.29.3.dev6/skills/resume/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: resume
+description: "List in-flight sessions and show the commands needed to re-attach after MCP disconnect"
+---
+
+# /ouroboros:resume
+
+Recover in-flight sessions after an unexpected MCP server disconnect.
+
+## Usage
+
+```
+ooo resume
+ooo resume --all
+```
+
+**Trigger keywords:** "resume session", "re-attach", "mcp disconnected", "lost session", "in-flight"
+
+## How It Works
+
+`ooo resume` reads the EventStore directly (no MCP server required) and lists
+every session that is still in a `running` or `paused` state. The command is
+strictly read-only — it never creates the data directory, never writes
+schema, and never appends events. Its job is to surface the identifiers you
+need to re-attach.
+
+- `ooo resume` shows the 20 most recent active sessions.
+- `ooo resume --all` shows every active session.
+
+## Instructions
+
+When the user invokes this skill:
+
+1. Run the CLI command:
+
+   ```
+   ouroboros resume
+   ```
+
+   This reads `~/.ouroboros/ouroboros.db` directly — the MCP server does **not**
+   need to be running.
+
+2. If sessions are listed, enter the number of the session you want to work
+   with. The command prints both the `session_id` and the `exec_id`, along
+   with the two re-attach paths.
+
+3. Pick the right re-attach path:
+
+   - **Inspect only** (read-only interactive monitor):
+
+     ```
+     ouroboros tui monitor
+     ```
+
+     Launches the TUI and lets you pick the session to inspect. The
+     `ouroboros status execution <exec_id>` command is *registered* but its
+     handler is still a placeholder in `src/ouroboros/cli/commands/status.py`
+     (it only prints "Would show details for execution: …"), so it is
+     intentionally not surfaced here. Follow-up tracked as a separate issue.
+
+   - **Resume execution** (requires the original seed file):
+
+     ```
+     ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>
+     ```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success — sessions listed, or no sessions found |
+| `1`  | Invalid user selection (non-numeric or out-of-range) |
+| `2`  | EventStore exists but could not be opened or read |
+
+## Fallback (No sessions found)
+
+If the command reports "No in-flight sessions found", the execution either
+completed, failed, was cancelled, or the EventStore has never been created.
+To browse historical sessions interactively, use the TUI monitor:
+
+```
+ouroboros tui monitor
+```
+
+## Example
+
+```
+User: ooo resume
+
+┌─────────────────────── In-Flight Sessions ───────────────────────┐
+│  #  Session ID          Execution ID        Status    Started    │
+│  1  sess-abc123         exec-xyz789         running   2026-04-15 │
+└───────────────────────────────────────────────────────────────────┘
+
+Enter number to re-attach (1-1), or 'q' to quit: 1
+
+╭─ Re-attach ────────────────────────────────────────────────────────────────╮
+│ Session ID:   sess-abc123                                                  │
+│ Execution ID: exec-xyz789                                                  │
+│                                                                            │
+│ Inspect (read-only interactive monitor):                                   │
+│     ouroboros tui monitor                                                  │
+│                                                                            │
+│ Resume execution (requires the original seed file):                        │
+│     ouroboros run workflow --orchestrator --resume sess-abc123 seed-001    │
+╰────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Next Steps
+
+After you have the identifiers:
+
+- `ouroboros tui monitor` — launch the TUI and pick the session to inspect
+- `ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>` — resume execution
+- `ooo evaluate` — evaluate results once the execution completes
+- `ooo cancel execution <exec_id>` — cancel if the session is stuck

{ouroboros_ai-0.29.3.dev5 → ouroboros_ai-0.29.3.dev6}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.29.3.dev5'
-__version_tuple__ = version_tuple = (0, 29, 3, 'dev5')
+__version__ = version = '0.29.3.dev6'
+__version_tuple__ = version_tuple = (0, 29, 3, 'dev6')
 
 __commit_id__ = commit_id = None

ouroboros_ai-0.29.3.dev6/src/ouroboros/cli/commands/resume.py

@@ -0,0 +1,333 @@
+"""Resume command for Ouroboros.
+
+List in-flight sessions directly from the EventStore (no MCP dependency).
+The command is intentionally read-only: it never creates the data directory,
+never writes schema, and never appends events. Read-only is enforced at the
+SQLite connection layer via ``EventStore(..., read_only=True)`` so even
+unexpected write paths fail fast with ``attempt to write a readonly
+database``. Its only job is to surface the identifiers a user needs to
+re-attach (inspect with ``ouroboros tui monitor`` or resume execution with
+``ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from ouroboros.cli.formatters import console
+from ouroboros.cli.formatters.panels import print_error, print_info, print_success
+from ouroboros.cli.formatters.tables import create_table, print_table
+
+app = typer.Typer(
+    name="resume",
+    help="List in-flight sessions and re-attach after MCP disconnect.",
+    invoke_without_command=True,
+)
+
+
+# Default cap on rows shown when many stale sessions accumulate. The user can
+# opt into the full list with ``--all``.
+DEFAULT_DISPLAY_LIMIT = 20
+
+# Exit code surfaced when the EventStore exists but is unreadable. Pinned so
+# users/scripts can branch on it (distinct from the happy "no sessions" path
+# which exits 0).
+EXIT_CORRUPTED_DB = 2
+
+
+def _default_db_path() -> str:
+    """Return the canonical SQLite path used by the running CLI."""
+    return os.path.expanduser("~/.ouroboros/ouroboros.db")
+
+
+async def _get_event_store(db_path: str | None = None):
+    """Open the EventStore read-only.
+
+    Returns ``None`` if the database file does not exist. Intentionally does
+    not create ``~/.ouroboros/`` or run ``metadata.create_all`` — this command
+    is a recovery tool and must not mutate user state. Read-only is enforced
+    at the SQLite connection layer via ``EventStore(..., read_only=True)``
+    so any accidental write path raises
+    ``sqlite3.OperationalError: attempt to write a readonly database``.
+    """
+    from ouroboros.persistence.event_store import EventStore
+
+    resolved = db_path or _default_db_path()
+    if not Path(resolved).exists():
+        return None
+
+    event_store = EventStore(
+        f"sqlite+aiosqlite:///{resolved}",
+        read_only=True,
+    )
+    try:
+        await event_store.initialize()
+    except Exception:
+        # Ensure the partially constructed engine is disposed before we bail
+        # out — otherwise the outer ``finally`` cannot close it (the variable
+        # was never bound in the caller).
+        try:
+            await event_store.close()
+        finally:
+            raise
+    return event_store
+
+
+def _is_active_snapshot(snapshot) -> bool:
+    """Return True when a snapshot is plausibly running or paused.
+
+    Terminal ``status_event_type`` values short-circuit the expensive replay.
+    Non-terminal or progress-only snapshots fall through to reconstruction.
+    """
+    terminal = {
+        "orchestrator.session.completed",
+        "orchestrator.session.failed",
+        "orchestrator.session.cancelled",
+    }
+    return snapshot.status_event_type not in terminal
+
+
+async def _get_in_flight_sessions(event_store, limit: int | None = DEFAULT_DISPLAY_LIMIT) -> list:
+    """Return running or paused session trackers, most-recent-first.
+
+    Uses ``get_session_activity_snapshots`` to narrow candidates without
+    replaying every event for every session, then reconstructs only the
+    snapshots whose latest status is non-terminal.
+    """
+    from ouroboros.orchestrator.session import SessionRepository, SessionStatus
+
+    repo = SessionRepository(event_store)
+
+    try:
+        snapshots = await event_store.get_session_activity_snapshots()
+    except AttributeError:
+        # Older EventStore builds may lack the snapshot helper. Fall back to
+        # the full replay path so the command still works.
+        return await _get_in_flight_sessions_fallback(event_store)
+
+    candidates = [s for s in snapshots if _is_active_snapshot(s)]
+
+    def _activity_key(snapshot) -> str:
+        return str(snapshot.last_activity or snapshot.start_time or "")
+
+    candidates.sort(key=_activity_key, reverse=True)
+
+    in_flight: list = []
+    for snapshot in candidates:
+        result = await repo.reconstruct_session(snapshot.session_id)
+        if result.is_err:
+            continue
+        tracker = result.value
+        if tracker.status in (SessionStatus.RUNNING, SessionStatus.PAUSED):
+            in_flight.append(tracker)
+            if limit is not None and len(in_flight) >= limit:
+                break
+
+    return in_flight
+
+
+async def _get_in_flight_sessions_fallback(event_store) -> list:
+    """Legacy path: replay every session. Retained only for API compatibility."""
+    from ouroboros.orchestrator.session import SessionRepository, SessionStatus
+
+    repo = SessionRepository(event_store)
+    session_events = await event_store.get_all_sessions()
+    if not session_events:
+        return []
+
+    seen: set[str] = set()
+    in_flight: list = []
+    for event in session_events:
+        session_id = event.aggregate_id
+        if session_id in seen:
+            continue
+        seen.add(session_id)
+        result = await repo.reconstruct_session(session_id)
+        if result.is_err:
+            continue
+        tracker = result.value
+        if tracker.status in (SessionStatus.RUNNING, SessionStatus.PAUSED):
+            in_flight.append(tracker)
+    return in_flight
+
+
+def _display_sessions(sessions: list) -> None:
+    """Render in-flight sessions in a numbered table."""
+    table = create_table("In-Flight Sessions")
+    table.add_column("#", style="bold", no_wrap=True, justify="right")
+    table.add_column("Session ID", style="cyan", no_wrap=True)
+    table.add_column("Execution ID", style="dim")
+    table.add_column("Seed ID", style="dim")
+    table.add_column("Status", justify="center")
+    table.add_column("Started", style="dim")
+
+    for idx, tracker in enumerate(sessions, 1):
+        status = tracker.status.value
+        status_style = "success" if status == "running" else "warning"
+        table.add_row(
+            str(idx),
+            tracker.session_id,
+            tracker.execution_id or "-",
+            tracker.seed_id or "-",
+            f"[{status_style}]{status}[/]",
+            tracker.start_time.isoformat(),
+        )
+
+    print_table(table)
+
+
+def _format_reattach_guidance(tracker) -> str:
+    """Build the post-selection guidance block.
+
+    Prints two commands, matching the real CLI contracts:
+
+    - Inspect:   ``ouroboros tui monitor`` (functional TUI; select the session)
+    - Resume:    ``ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>``
+
+    ``run workflow --resume`` takes a *session_id* (not an execution_id) and
+    also requires the seed file, so both identifiers are surfaced explicitly.
+
+    Note: ``ouroboros status execution <exec_id>`` is *registered* but its
+    implementation is still a placeholder (see src/ouroboros/cli/commands/status.py),
+    so we deliberately do not surface it as an inspection path — it would
+    print misleading "Would show details" output.
+    """
+    exec_id = tracker.execution_id or "<unknown>"
+    seed_hint = tracker.seed_id or "<seed.yaml>"
+
+    inspect_line = "ouroboros tui monitor"
+    resume_line = f"ouroboros run workflow --orchestrator --resume {tracker.session_id} {seed_hint}"
+
+    lines = [
+        f"Session ID:   [bold cyan]{tracker.session_id}[/]",
+        f"Execution ID: [bold cyan]{exec_id}[/]",
+        "",
+        "[bold]Inspect[/] (read-only interactive monitor):",
+        f"    {inspect_line}",
+        "",
+        "[bold]Resume execution[/] (requires the original seed file):",
+        f"    {resume_line}",
+    ]
+    if not tracker.seed_id:
+        lines.append(
+            "[dim]Seed ID was not recorded for this session — replace "
+            "<seed.yaml> with the original seed path.[/]"
+        )
+    return "\n".join(lines)
+
+
+async def _interactive_resume(show_all: bool = False) -> int:
+    """List in-flight sessions and prompt the user to pick one to re-attach.
+
+    Returns the integer exit code the CLI should emit so callers can pin
+    distinct codes for missing DB vs. corrupted DB vs. happy path.
+    """
+    limit = None if show_all else DEFAULT_DISPLAY_LIMIT
+
+    try:
+        event_store = await _get_event_store()
+    except Exception as exc:  # noqa: BLE001 — surface any open error verbatim
+        print_error(f"Failed to open EventStore: {exc}")
+        return EXIT_CORRUPTED_DB
+
+    if event_store is None:
+        print_info("No in-flight sessions found.", "Resume")
+        console.print(
+            "[dim]EventStore does not exist yet. "
+            "Sessions appear here after the MCP server has started at least one run.[/]"
+        )
+        return 0
+
+    try:
+        try:
+            sessions = await _get_in_flight_sessions(event_store, limit=limit)
+        except Exception as exc:  # noqa: BLE001
+            print_error(f"Failed to read EventStore: {exc}")
+            return EXIT_CORRUPTED_DB
+    finally:
+        await event_store.close()
+
+    if not sessions:
+        print_info("No in-flight sessions found.", "Resume")
+        console.print(
+            "[dim]Sessions appear here when the MCP server was disconnected mid-execution.[/]"
+        )
+        return 0
+
+    _display_sessions(sessions)
+    console.print()
+
+    choice = typer.prompt(
+        f"Enter number to re-attach (1-{len(sessions)}), or 'q' to quit",
+        default="q",
+    )
+
+    if choice.strip().lower() == "q":
+        print_info("No session selected.", "Resume")
+        return 0
+
+    try:
+        index = int(choice) - 1
+    except ValueError:
+        print_error(f"Invalid selection: {choice!r}")
+        return 1
+
+    if index < 0 or index >= len(sessions):
+        print_error(f"Selection out of range: {choice}. Expected 1-{len(sessions)}.")
+        return 1
+
+    selected = sessions[index]
+    print_success(_format_reattach_guidance(selected), "Re-attach")
+    return 0
+
+
+@app.callback(invoke_without_command=True)
+def resume(
+    ctx: typer.Context,
+    show_all: Annotated[
+        bool,
+        typer.Option(
+            "--all",
+            "-a",
+            help=(
+                f"Show every in-flight session instead of the most recent {DEFAULT_DISPLAY_LIMIT}."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """List in-flight sessions and get re-attach instructions.
+
+    Reads the EventStore directly — no MCP server required. Use this command
+    after an unexpected MCP disconnect to recover the session/execution IDs
+    and re-attach.
+
+    Re-attach paths surfaced after selection:
+
+        # Inspect (interactive monitor — the `status execution` placeholder is
+        # not wired up yet)
+        ouroboros tui monitor
+
+        # Resume execution (requires the original seed file)
+        ouroboros run workflow --orchestrator --resume <session_id> <seed.yaml>
+
+    Examples:
+
+        # Interactive: list in-flight sessions and pick one
+        ouroboros resume
+
+        # Show every stale active session, not just the 20 most recent
+        ouroboros resume --all
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    exit_code = asyncio.run(_interactive_resume(show_all=show_all))
+    if exit_code != 0:
+        raise typer.Exit(exit_code)
+
+
+__all__ = ["app"]

{ouroboros_ai-0.29.3.dev5 → ouroboros_ai-0.29.3.dev6}/src/ouroboros/cli/main.py

@@ -21,6 +21,7 @@ from ouroboros.cli.commands import (
     init,
     mcp,
     pm,
+    resume,
     run,
     setup,
     status,
@@ -48,6 +49,7 @@ app.add_typer(setup.app, name="setup")
 app.add_typer(detect.app, name="detect")
 app.add_typer(tui.app, name="tui")
 app.add_typer(pm.app, name="pm")
+app.add_typer(resume.app, name="resume")
 app.add_typer(uninstall.app, name="uninstall")
 
 

{ouroboros_ai-0.29.3.dev5 → ouroboros_ai-0.29.3.dev6}/src/ouroboros/persistence/event_store.py

@@ -90,21 +90,64 @@ class EventStore:
         await store.close()
     """
 
-    def __init__(self, database_url: str | None = None) -> None:
+    def __init__(
+        self,
+        database_url: str | None = None,
+        *,
+        read_only: bool = False,
+    ) -> None:
         """Initialize EventStore with database URL.
 
         Args:
             database_url: SQLAlchemy database URL.
                          For async SQLite: "sqlite+aiosqlite:///path/to/db.sqlite"
                          If not provided, defaults to ~/.ouroboros/ouroboros.db
+            read_only: When True, open the underlying SQLite database in true
+                read-only mode by rewriting the URL into the ``file:<path>?mode=ro&uri=true``
+                form and passing ``connect_args={"uri": True}`` to aiosqlite.
+                This enforces the read-only contract at the connection layer
+                so *any* accidental write path (including library/future code
+                paths we don't control) fails fast with
+                ``sqlite3.OperationalError: attempt to write a readonly database``.
+                Callers that opt in should also skip schema creation by calling
+                ``initialize(create_schema=False)`` — this is the default when
+                ``read_only=True``. ``read_only`` is a no-op for non-SQLite URLs.
         """
         if database_url is None:
             db_path = Path.home() / ".ouroboros" / "ouroboros.db"
-            db_path.parent.mkdir(parents=True, exist_ok=True)
+            if not read_only:
+                db_path.parent.mkdir(parents=True, exist_ok=True)
             database_url = f"sqlite+aiosqlite:///{db_path}"
+
+        self._read_only = read_only
+        if read_only:
+            database_url = self._coerce_to_readonly_url(database_url)
         self._database_url = database_url
         self._engine: AsyncEngine | None = None
 
+    @staticmethod
+    def _coerce_to_readonly_url(database_url: str) -> str:
+        """Rewrite a plain aiosqlite URL into a ``mode=ro`` URI form.
+
+        Leaves non-SQLite URLs untouched. Already-URI forms (starting with
+        ``file:``) are returned as-is so explicit callers keep full control.
+        """
+        prefix = "sqlite+aiosqlite:///"
+        if not database_url.startswith(prefix):
+            return database_url
+
+        path_part = database_url[len(prefix) :]
+        if path_part.startswith("file:"):
+            # Caller already provided a URI form — respect it verbatim.
+            return database_url
+
+        # ``:memory:`` has no filesystem and cannot be opened read-only
+        # meaningfully; leave it alone.
+        if path_part in (":memory:", ""):
+            return database_url
+
+        return f"{prefix}file:{path_part}?mode=ro&uri=true"
+
     def _raise_invalid_append_input(
         self,
         event: object,
@@ -133,34 +176,65 @@ class EventStore:
             details=details,
         )
 
-    async def initialize(self) -> None:
+    async def initialize(self, *, create_schema: bool | None = None) -> None:
         """Initialize the database connection and create tables if needed.
 
         This method is idempotent - calling it multiple times is safe.
 
+        Args:
+            create_schema: When True run ``metadata.create_all`` so missing
+                tables are created. Read-only consumers (for example diagnostic
+                CLI commands that must not mutate the store) can pass ``False``
+                to skip schema creation entirely. When ``None`` (default), the
+                value follows ``read_only``: stores constructed with
+                ``read_only=True`` skip schema creation and all others create
+                it, preserving the prior default behaviour.
+
         For aiosqlite, uses StaticPool (default) which maintains a single
         connection. This avoids connection accumulation while supporting
         :memory: databases in tests.
         """
+        if create_schema is None:
+            create_schema = not self._read_only
+
+        if self._read_only and create_schema:
+            raise PersistenceError(
+                "Cannot create schema on a read-only EventStore.",
+                operation="initialize",
+                details={"read_only": True},
+            )
+
         if self._engine is None:
+            connect_args: dict[str, object] = {"timeout": 30}
+            if self._read_only:
+                # aiosqlite forwards unknown kwargs to sqlite3.connect — the
+                # ``uri=True`` flag is what turns the ``file:...?mode=ro`` form
+                # into a real read-only connection.
+                connect_args["uri"] = True
+
             self._engine = create_async_engine(
                 self._database_url,
                 echo=False,
-                connect_args={"timeout": 30},
+                connect_args=connect_args,
             )
 
-            # Enable WAL mode and set busy timeout on every new connection
-            @event.listens_for(self._engine.sync_engine, "connect")
-            def _set_sqlite_pragmas(dbapi_conn, _connection_record):
-                cursor = dbapi_conn.cursor()
-                cursor.execute("PRAGMA journal_mode=WAL")
-                cursor.execute("PRAGMA synchronous=NORMAL")
-                cursor.execute("PRAGMA busy_timeout=30000")
-                cursor.close()
-
-        # Create all tables defined in metadata
-        async with self._engine.begin() as conn:
-            await conn.run_sync(metadata.create_all)
+            # Enable WAL mode and set busy timeout on every new connection.
+            # Skipped for read-only consumers: ``PRAGMA journal_mode=WAL`` is
+            # itself a write and would trip SQLite's read-only guard.
+            if not self._read_only:
+
+                @event.listens_for(self._engine.sync_engine, "connect")
+                def _set_sqlite_pragmas(dbapi_conn, _connection_record):
+                    cursor = dbapi_conn.cursor()
+                    cursor.execute("PRAGMA journal_mode=WAL")
+                    cursor.execute("PRAGMA synchronous=NORMAL")
+                    cursor.execute("PRAGMA busy_timeout=30000")
+                    cursor.close()
+
+        # Create all tables defined in metadata (skipped for read-only consumers)
+        if create_schema:
+            async with self._engine.begin() as conn:
+                await conn.run_sync(metadata.create_all)
 
     async def append(self, event: BaseEvent) -> None:
         """Append an event to the store.