gobby 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

gobby/adapters/codex.py

@@ -1,1332 +0,0 @@
-"""Codex CLI integration for gobby-daemon.
-
-This module provides two integration modes for Codex CLI:
-
-1. App-Server Mode (programmatic control):
-   - CodexAppServerClient: Spawns `codex app-server` subprocess
-   - CodexAdapter: Translates app-server events to HookEvent
-   - Full control over threads, turns, and streaming events
-
-2. Notify Mode (installed hooks via `gobby install --codex`):
-   - CodexNotifyAdapter: Handles HTTP webhooks from Codex notify config
-   - Fire-and-forget events on agent-turn-complete
-
-Architecture:
-    App-Server Mode:
-        gobby-daemon
-        └── CodexAppServerClient
-            ├── Spawns: `codex app-server` (stdio subprocess)
-            ├── Protocol: JSON-RPC 2.0 over stdin/stdout
-            └── CodexAdapter (translates events to HookEvent)
-
-    Notify Mode:
-        Codex CLI
-        └── notify script (installed by `gobby install --codex`)
-            └── HTTP POST to /hooks/execute
-                └── CodexNotifyAdapter (translates to HookEvent)
-
-See: https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md
-"""
-
-from __future__ import annotations
-
-import asyncio
-import glob as glob_module
-import json
-import logging
-import os
-import platform
-import subprocess  # nosec B404 - subprocess needed for Codex app-server process
-import threading
-import uuid
-from collections.abc import AsyncIterator, Callable
-from dataclasses import dataclass, field
-from datetime import UTC, datetime
-from enum import Enum
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
-
-from gobby.adapters.base import BaseAdapter
-from gobby.hooks.events import HookEvent, HookEventType, HookResponse, SessionSource
-
-if TYPE_CHECKING:
-    from gobby.hooks.hook_manager import HookManager
-
-logger = logging.getLogger(__name__)
-
-# Codex session storage location
-CODEX_SESSIONS_DIR = Path.home() / ".codex" / "sessions"
-
-
-# =============================================================================
-# App-Server Data Types
-# =============================================================================
-
-
-class CodexConnectionState(Enum):
-    """Connection state for the Codex app-server."""
-
-    DISCONNECTED = "disconnected"
-    CONNECTING = "connecting"
-    CONNECTED = "connected"
-    ERROR = "error"
-
-
-@dataclass
-class CodexThread:
-    """Represents a Codex conversation thread."""
-
-    id: str
-    preview: str = ""
-    model_provider: str = "openai"
-    created_at: int = 0
-
-
-@dataclass
-class CodexTurn:
-    """Represents a turn in a Codex conversation."""
-
-    id: str
-    thread_id: str
-    status: str = "pending"
-    items: list[dict[str, Any]] = field(default_factory=list)
-    error: str | None = None
-    usage: dict[str, int] | None = None
-
-
-@dataclass
-class CodexItem:
-    """Represents an item (message, tool call, etc.) in a turn."""
-
-    id: str
-    type: str  # "reasoning", "agent_message", "command_execution", "user_message", etc.
-    content: str = ""
-    status: str = "pending"
-    metadata: dict[str, Any] = field(default_factory=dict)
-
-
-# Type alias for notification handlers
-NotificationHandler = Callable[[str, dict[str, Any]], None]
-
-
-# =============================================================================
-# App-Server Client (Programmatic Control)
-# =============================================================================
-
-
-class CodexAppServerClient:
-    """
-    Client for the Codex app-server JSON-RPC protocol.
-
-    Manages the subprocess lifecycle and provides async methods for:
-    - Thread management (conversations)
-    - Turn management (message exchanges)
-    - Event streaming via notifications
-
-    Example:
-        async with CodexAppServerClient() as client:
-            thread = await client.start_thread(cwd="/path/to/project")
-            async for event in client.run_turn(thread.id, "Help me refactor"):
-                print(event)
-    """
-
-    CLIENT_NAME = "gobby-daemon"
-    CLIENT_TITLE = "Gobby Daemon"
-    CLIENT_VERSION = "0.1.0"
-
-    def __init__(
-        self,
-        codex_command: str = "codex",
-        on_notification: NotificationHandler | None = None,
-    ) -> None:
-        """
-        Initialize the Codex app-server client.
-
-        Args:
-            codex_command: Path to the codex binary (default: "codex")
-            on_notification: Optional callback for all notifications
-        """
-        self._codex_command = codex_command
-        self._on_notification = on_notification
-
-        self._process: subprocess.Popen[str] | None = None
-        self._state = CodexConnectionState.DISCONNECTED
-        self._request_id = 0
-        self._request_id_lock = threading.Lock()
-
-        # Pending requests waiting for responses
-        self._pending_requests: dict[int, asyncio.Future[Any]] = {}
-        self._pending_requests_lock = threading.Lock()
-
-        # Notification handlers by method
-        self._notification_handlers: dict[str, list[NotificationHandler]] = {}
-
-        # Reader task
-        self._reader_task: asyncio.Task[None] | None = None
-        self._shutdown_event = asyncio.Event()
-
-        # Thread tracking for session management
-        self._threads: dict[str, CodexThread] = {}
-
-    @property
-    def state(self) -> CodexConnectionState:
-        """Get current connection state."""
-        return self._state
-
-    @property
-    def is_connected(self) -> bool:
-        """Check if connected to app-server."""
-        return self._state == CodexConnectionState.CONNECTED
-
-    async def __aenter__(self) -> CodexAppServerClient:
-        """Async context manager entry - starts the app-server."""
-        await self.start()
-        return self
-
-    async def __aexit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: object,
-    ) -> None:
-        """Async context manager exit - stops the app-server."""
-        await self.stop()
-
-    async def start(self) -> None:
-        """
-        Start the Codex app-server subprocess and initialize connection.
-
-        Raises:
-            RuntimeError: If already connected or failed to start
-        """
-        if self._state == CodexConnectionState.CONNECTED:
-            logger.warning("CodexAppServerClient already connected")
-            return
-
-        self._state = CodexConnectionState.CONNECTING
-        logger.debug("Starting Codex app-server...")
-
-        try:
-            # Start the subprocess
-            self._process = subprocess.Popen(  # nosec B603 - hardcoded argument list
-                [self._codex_command, "app-server"],
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                text=True,
-                bufsize=1,  # Line buffered
-            )
-
-            # Start the reader task
-            self._shutdown_event.clear()
-            self._reader_task = asyncio.create_task(self._read_loop())
-
-            # Send initialize request
-            result = await self._send_request(
-                "initialize",
-                {
-                    "clientInfo": {
-                        "name": self.CLIENT_NAME,
-                        "title": self.CLIENT_TITLE,
-                        "version": self.CLIENT_VERSION,
-                    }
-                },
-            )
-
-            user_agent = result.get("userAgent", "unknown")
-            logger.debug(f"Codex app-server initialized: {user_agent}")
-
-            # Send initialized notification
-            await self._send_notification("initialized", {})
-
-            self._state = CodexConnectionState.CONNECTED
-            logger.debug("Codex app-server connection established")
-
-        except Exception as e:
-            self._state = CodexConnectionState.ERROR
-            logger.error(f"Failed to start Codex app-server: {e}", exc_info=True)
-            await self.stop()
-            raise RuntimeError(f"Failed to start Codex app-server: {e}") from e
-
-    async def stop(self) -> None:
-        """Stop the Codex app-server subprocess."""
-        logger.debug("Stopping Codex app-server...")
-
-        self._shutdown_event.set()
-
-        # Cancel reader task
-        if self._reader_task and not self._reader_task.done():
-            self._reader_task.cancel()
-            try:
-                await self._reader_task
-            except asyncio.CancelledError:
-                pass
-
-        # Terminate process
-        if self._process:
-            try:
-                if self._process.stdin:
-                    self._process.stdin.close()
-                self._process.terminate()
-                loop = asyncio.get_event_loop()
-                await asyncio.wait_for(loop.run_in_executor(None, self._process.wait), timeout=5.0)
-            except Exception as e:
-                logger.warning(f"Error terminating Codex app-server: {e}")
-                self._process.kill()
-            finally:
-                self._process = None
-
-        # Cancel pending requests
-        with self._pending_requests_lock:
-            for future in self._pending_requests.values():
-                if not future.done():
-                    future.cancel()
-            self._pending_requests.clear()
-
-        self._state = CodexConnectionState.DISCONNECTED
-        logger.debug("Codex app-server stopped")
-
-    def add_notification_handler(self, method: str, handler: NotificationHandler) -> None:
-        """
-        Register a handler for a specific notification method.
-
-        Args:
-            method: Notification method name (e.g., "turn/started", "item/completed")
-            handler: Callback function(method, params)
-        """
-        if method not in self._notification_handlers:
-            self._notification_handlers[method] = []
-        self._notification_handlers[method].append(handler)
-
-    def remove_notification_handler(self, method: str, handler: NotificationHandler) -> None:
-        """Remove a notification handler."""
-        if method in self._notification_handlers:
-            self._notification_handlers[method] = [
-                h for h in self._notification_handlers[method] if h != handler
-            ]
-
-    # ===== Thread Management =====
-
-    async def start_thread(
-        self,
-        cwd: str | None = None,
-        model: str | None = None,
-        approval_policy: str | None = None,
-        sandbox: str | None = None,
-    ) -> CodexThread:
-        """
-        Start a new Codex conversation thread.
-
-        Args:
-            cwd: Working directory for the session
-            model: Model override (e.g., "gpt-5.1-codex")
-            approval_policy: Approval policy ("never", "unlessTrusted", etc.)
-            sandbox: Sandbox mode ("workspaceWrite", "readOnly", etc.)
-
-        Returns:
-            CodexThread object with thread ID
-        """
-        params: dict[str, Any] = {}
-        if cwd:
-            params["cwd"] = cwd
-        if model:
-            params["model"] = model
-        if approval_policy:
-            params["approvalPolicy"] = approval_policy
-        if sandbox:
-            params["sandbox"] = sandbox
-
-        result = await self._send_request("thread/start", params)
-
-        thread_data = result.get("thread", {})
-        thread = CodexThread(
-            id=thread_data.get("id", ""),
-            preview=thread_data.get("preview", ""),
-            model_provider=thread_data.get("modelProvider", "openai"),
-            created_at=thread_data.get("createdAt", 0),
-        )
-
-        self._threads[thread.id] = thread
-        logger.debug(f"Started Codex thread: {thread.id}")
-        return thread
-
-    async def resume_thread(self, thread_id: str) -> CodexThread:
-        """
-        Resume an existing Codex conversation thread.
-
-        Args:
-            thread_id: ID of the thread to resume
-
-        Returns:
-            CodexThread object
-        """
-        result = await self._send_request("thread/resume", {"threadId": thread_id})
-
-        thread_data = result.get("thread", {})
-        thread = CodexThread(
-            id=thread_data.get("id", thread_id),
-            preview=thread_data.get("preview", ""),
-            model_provider=thread_data.get("modelProvider", "openai"),
-            created_at=thread_data.get("createdAt", 0),
-        )
-
-        self._threads[thread.id] = thread
-        logger.debug(f"Resumed Codex thread: {thread.id}")
-        return thread
-
-    async def list_threads(
-        self, cursor: str | None = None, limit: int = 25
-    ) -> tuple[list[CodexThread], str | None]:
-        """
-        List stored Codex threads with pagination.
-
-        Args:
-            cursor: Pagination cursor from previous call
-            limit: Maximum threads to return
-
-        Returns:
-            Tuple of (threads list, next_cursor or None)
-        """
-        params: dict[str, Any] = {"limit": limit}
-        if cursor:
-            params["cursor"] = cursor
-
-        result = await self._send_request("thread/list", params)
-
-        threads = []
-        for item in result.get("data", []):
-            threads.append(
-                CodexThread(
-                    id=item.get("id", ""),
-                    preview=item.get("preview", ""),
-                    model_provider=item.get("modelProvider", "openai"),
-                    created_at=item.get("createdAt", 0),
-                )
-            )
-
-        next_cursor = result.get("nextCursor")
-        return threads, next_cursor
-
-    async def archive_thread(self, thread_id: str) -> None:
-        """
-        Archive a Codex thread.
-
-        Args:
-            thread_id: ID of the thread to archive
-        """
-        await self._send_request("thread/archive", {"threadId": thread_id})
-        self._threads.pop(thread_id, None)
-        logger.debug(f"Archived Codex thread: {thread_id}")
-
-    # ===== Turn Management =====
-
-    async def start_turn(
-        self,
-        thread_id: str,
-        prompt: str,
-        images: list[str] | None = None,
-        **config_overrides: Any,
-    ) -> CodexTurn:
-        """
-        Start a new turn (send user input and trigger generation).
-
-        Args:
-            thread_id: Thread ID to add turn to
-            prompt: User's input text
-            images: Optional list of image paths or URLs
-            **config_overrides: Optional config overrides (cwd, model, etc.)
-
-        Returns:
-            CodexTurn object (initial state, updates via notifications)
-        """
-        # Build input array
-        inputs: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
-
-        if images:
-            for img in images:
-                if img.startswith(("http://", "https://")):
-                    inputs.append({"type": "image", "url": img})
-                else:
-                    inputs.append({"type": "localImage", "path": img})
-
-        params: dict[str, Any] = {
-            "threadId": thread_id,
-            "input": inputs,
-        }
-        params.update(config_overrides)
-
-        result = await self._send_request("turn/start", params)
-
-        turn_data = result.get("turn", {})
-        turn = CodexTurn(
-            id=turn_data.get("id", ""),
-            thread_id=thread_id,
-            status=turn_data.get("status", "inProgress"),
-            items=turn_data.get("items", []),
-            error=turn_data.get("error"),
-        )
-
-        logger.debug(f"Started turn {turn.id} in thread {thread_id}")
-        return turn
-
-    async def interrupt_turn(self, thread_id: str, turn_id: str) -> None:
-        """
-        Interrupt an in-progress turn.
-
-        Args:
-            thread_id: Thread ID containing the turn
-            turn_id: Turn ID to interrupt
-        """
-        await self._send_request("turn/interrupt", {"threadId": thread_id, "turnId": turn_id})
-        logger.debug(f"Interrupted turn {turn_id}")
-
-    async def run_turn(
-        self,
-        thread_id: str,
-        prompt: str,
-        images: list[str] | None = None,
-        **config_overrides: Any,
-    ) -> AsyncIterator[dict[str, Any]]:
-        """
-        Run a turn and yield streaming events.
-
-        This is the primary method for interacting with Codex. It starts a turn
-        and yields all events until completion.
-
-        Args:
-            thread_id: Thread ID
-            prompt: User's input text
-            images: Optional image paths/URLs
-            **config_overrides: Config overrides
-
-        Yields:
-            Event dicts with "type" and event-specific data
-
-        Example:
-            async for event in client.run_turn(thread.id, "Help me refactor"):
-                if event["type"] == "item.completed":
-                    print(event["item"]["text"])
-        """
-        # Queue to receive notifications
-        event_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
-        turn_completed = asyncio.Event()
-
-        def on_event(method: str, params: dict[str, Any]) -> None:
-            event_queue.put_nowait({"type": method, **params})
-            if method == "turn/completed":
-                turn_completed.set()
-
-        # Register handlers for all turn-related events
-        event_methods = [
-            "turn/started",
-            "turn/completed",
-            "item/started",
-            "item/completed",
-            "item/agentMessage/delta",
-        ]
-
-        for method in event_methods:
-            self.add_notification_handler(method, on_event)
-
-        try:
-            # Start the turn
-            turn = await self.start_turn(thread_id, prompt, images=images, **config_overrides)
-
-            yield {"type": "turn/created", "turn": turn.__dict__}
-
-            # Yield events until turn completes
-            while not turn_completed.is_set():
-                try:
-                    event = await asyncio.wait_for(event_queue.get(), timeout=0.1)
-                    yield event
-                except TimeoutError:
-                    continue
-
-            # Drain remaining events
-            while not event_queue.empty():
-                yield event_queue.get_nowait()
-
-        finally:
-            # Unregister handlers
-            for method in event_methods:
-                self.remove_notification_handler(method, on_event)
-
-    # ===== Authentication =====
-
-    async def login_with_api_key(self, api_key: str) -> dict[str, Any]:
-        """
-        Authenticate using an OpenAI API key.
-
-        Args:
-            api_key: OpenAI API key (sk-...)
-
-        Returns:
-            Login result dict
-        """
-        result = await self._send_request(
-            "account/login/start", {"type": "apiKey", "apiKey": api_key}
-        )
-        logger.debug("Logged in with API key")
-        return result
-
-    async def get_account_status(self) -> dict[str, Any]:
-        """Get current account/authentication status."""
-        return await self._send_request("account/status", {})
-
-    # ===== Internal Methods =====
-
-    def _next_request_id(self) -> int:
-        """Generate unique request ID."""
-        with self._request_id_lock:
-            self._request_id += 1
-            return self._request_id
-
-    async def _send_request(
-        self, method: str, params: dict[str, Any], timeout: float = 60.0
-    ) -> dict[str, Any]:
-        """
-        Send a JSON-RPC request and wait for response.
-
-        Args:
-            method: RPC method name
-            params: Method parameters
-            timeout: Response timeout in seconds
-
-        Returns:
-            Result dict from response
-
-        Raises:
-            RuntimeError: If not connected or request fails
-            TimeoutError: If response times out
-        """
-        if not self._process or not self._process.stdin:
-            raise RuntimeError("Not connected to Codex app-server")
-
-        request_id = self._next_request_id()
-        request = {
-            "jsonrpc": "2.0",
-            "method": method,
-            "id": request_id,
-            "params": params,
-        }
-
-        # Create future for response
-        loop = asyncio.get_event_loop()
-        future: asyncio.Future[Any] = loop.create_future()
-
-        with self._pending_requests_lock:
-            self._pending_requests[request_id] = future
-
-        try:
-            # Send request
-            request_line = json.dumps(request) + "\n"
-            self._process.stdin.write(request_line)
-            self._process.stdin.flush()
-
-            logger.debug(f"Sent request: {method} (id={request_id})")
-
-            # Wait for response
-            result = await asyncio.wait_for(future, timeout=timeout)
-            return cast(dict[str, Any], result)
-
-        except TimeoutError:
-            logger.error(f"Request {method} (id={request_id}) timed out")
-            raise
-        finally:
-            with self._pending_requests_lock:
-                self._pending_requests.pop(request_id, None)
-
-    async def _send_notification(self, method: str, params: dict[str, Any]) -> None:
-        """Send a JSON-RPC notification (no response expected)."""
-        if not self._process or not self._process.stdin:
-            raise RuntimeError("Not connected to Codex app-server")
-
-        notification = {"jsonrpc": "2.0", "method": method, "params": params}
-
-        notification_line = json.dumps(notification) + "\n"
-        self._process.stdin.write(notification_line)
-        self._process.stdin.flush()
-
-        logger.debug(f"Sent notification: {method}")
-
-    async def _read_loop(self) -> None:
-        """Background task to read responses and notifications."""
-        if not self._process or not self._process.stdout:
-            return
-
-        loop = asyncio.get_event_loop()
-
-        while not self._shutdown_event.is_set():
-            try:
-                # Read line in thread pool to avoid blocking
-                line = await loop.run_in_executor(None, self._process.stdout.readline)
-
-                if not line:
-                    if self._process.poll() is not None:
-                        logger.warning("Codex app-server process terminated")
-                        self._state = CodexConnectionState.ERROR
-                        break
-                    continue
-
-                # Parse JSON-RPC message
-                try:
-                    message = json.loads(line.strip())
-                except json.JSONDecodeError as e:
-                    logger.warning(f"Invalid JSON from app-server: {e}")
-                    continue
-
-                # Handle response (has "id")
-                if "id" in message:
-                    request_id = message["id"]
-                    with self._pending_requests_lock:
-                        future = self._pending_requests.get(request_id)
-
-                    if future and not future.done():
-                        if "error" in message:
-                            error = message["error"]
-                            future.set_exception(
-                                RuntimeError(
-                                    f"RPC error {error.get('code')}: {error.get('message')}"
-                                )
-                            )
-                        else:
-                            future.set_result(message.get("result", {}))
-
-                # Handle notification (no "id")
-                elif "method" in message:
-                    method = message["method"]
-                    params = message.get("params", {})
-
-                    logger.debug(f"Received notification: {method}")
-
-                    # Call global handler
-                    if self._on_notification:
-                        try:
-                            self._on_notification(method, params)
-                        except Exception as e:
-                            logger.error(f"Notification handler error: {e}")
-
-                    # Call method-specific handlers
-                    handlers = self._notification_handlers.get(method, [])
-                    for handler in handlers:
-                        try:
-                            handler(method, params)
-                        except Exception as e:
-                            logger.error(f"Handler error for {method}: {e}")
-
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"Error in read loop: {e}", exc_info=True)
-                if self._shutdown_event.is_set():
-                    break
-
-
-# =============================================================================
-# Shared Utilities
-# =============================================================================
-
-
-def _get_machine_id() -> str:
-    """Get or generate a stable machine identifier based on hostname."""
-    node = platform.node()
-    if node:
-        return str(uuid.uuid5(uuid.NAMESPACE_DNS, node))
-    return str(uuid.uuid4())
-
-
-# =============================================================================
-# App-Server Adapter (for programmatic control)
-# =============================================================================
-
-
-class CodexAdapter(BaseAdapter):
-    """Adapter for Codex CLI session tracking via app-server events.
-
-    This adapter translates Codex app-server events to unified HookEvent
-    for session tracking. It can operate in two modes:
-
-    1. Integrated mode (recommended): Attach to existing CodexAppServerClient
-       - Call attach_to_client(codex_client) with the existing client
-       - Events are forwarded from the client's notification handlers
-
-    2. Standalone mode: Use without CodexAppServerClient
-       - Only provides translation methods for events received externally
-       - No subprocess management (use CodexAppServerClient for that)
-
-    Lifecycle (integrated mode):
-    - attach_to_client(codex_client) registers notification handlers
-    - Events processed through HookManager for session registration
-    - detach_from_client() removes handlers
-    """
-
-    source = SessionSource.CODEX
-
-    # Event type mapping: Codex app-server methods -> unified HookEventType
-    EVENT_MAP: dict[str, HookEventType] = {
-        "thread/started": HookEventType.SESSION_START,
-        "thread/archive": HookEventType.SESSION_END,
-        "turn/started": HookEventType.BEFORE_AGENT,
-        "turn/completed": HookEventType.AFTER_AGENT,
-        # Approval requests map to BEFORE_TOOL
-        "item/commandExecution/requestApproval": HookEventType.BEFORE_TOOL,
-        "item/fileChange/requestApproval": HookEventType.BEFORE_TOOL,
-        # Completed items map to AFTER_TOOL
-        "item/completed": HookEventType.AFTER_TOOL,
-    }
-
-    # Tool name mapping: Codex tool names -> canonical CC-style names
-    # Codex uses different tool names - normalize to Claude Code conventions
-    # so block_tools rules work across CLIs
-    TOOL_MAP: dict[str, str] = {
-        # File operations
-        "read_file": "Read",
-        "ReadFile": "Read",
-        "write_file": "Write",
-        "WriteFile": "Write",
-        "edit_file": "Edit",
-        "EditFile": "Edit",
-        # Shell
-        "run_shell_command": "Bash",
-        "RunShellCommand": "Bash",
-        "commandExecution": "Bash",
-        # Search
-        "glob": "Glob",
-        "grep": "Grep",
-        "GlobTool": "Glob",
-        "GrepTool": "Grep",
-    }
-
-    # Item types that represent tool operations
-    TOOL_ITEM_TYPES = {"commandExecution", "fileChange", "mcpToolCall"}
-
-    # Events we want to listen for session tracking
-    SESSION_TRACKING_EVENTS = [
-        "thread/started",
-        "turn/started",
-        "turn/completed",
-        "item/completed",
-    ]
-
-    def __init__(self, hook_manager: HookManager | None = None):
-        """Initialize the Codex adapter.
-
-        Args:
-            hook_manager: Reference to HookManager for event processing.
-        """
-        self._hook_manager = hook_manager
-        self._codex_client: CodexAppServerClient | None = None
-        self._machine_id: str | None = None
-        self._attached = False
-
-    @staticmethod
-    def is_codex_available() -> bool:
-        """Check if Codex CLI is installed and available.
-
-        Returns:
-            True if `codex` command is found in PATH.
-        """
-        import shutil
-
-        return shutil.which("codex") is not None
-
-    def _get_machine_id(self) -> str:
-        """Get or generate a machine identifier."""
-        if self._machine_id is None:
-            self._machine_id = _get_machine_id()
-        return self._machine_id
-
-    def normalize_tool_name(self, codex_tool_name: str) -> str:
-        """Normalize Codex tool name to canonical CC-style format.
-
-        This ensures block_tools rules work consistently across CLIs.
-
-        Args:
-            codex_tool_name: Tool name from Codex CLI.
-
-        Returns:
-            Normalized tool name (e.g., "Bash", "Read", "Write", "Edit").
-        """
-        return self.TOOL_MAP.get(codex_tool_name, codex_tool_name)
-
-    def attach_to_client(self, codex_client: CodexAppServerClient) -> None:
-        """Attach to an existing CodexAppServerClient for event handling.
-
-        Registers notification handlers on the client to receive session
-        tracking events. This is the preferred integration mode.
-
-        Args:
-            codex_client: The CodexAppServerClient to attach to.
-        """
-        if self._attached:
-            logger.warning("CodexAdapter already attached to a client")
-            return
-
-        self._codex_client = codex_client
-
-        # Register handlers for session tracking events
-        for method in self.SESSION_TRACKING_EVENTS:
-            codex_client.add_notification_handler(method, self._handle_notification)
-
-        self._attached = True
-        logger.debug("CodexAdapter attached to CodexAppServerClient")
-
-    def detach_from_client(self) -> None:
-        """Detach from the CodexAppServerClient.
-
-        Removes notification handlers. Call this before disposing the adapter.
-        """
-        if not self._attached or not self._codex_client:
-            return
-
-        # Remove handlers
-        for method in self.SESSION_TRACKING_EVENTS:
-            self._codex_client.remove_notification_handler(method, self._handle_notification)
-
-        self._codex_client = None
-        self._attached = False
-        logger.debug("CodexAdapter detached from CodexAppServerClient")
-
-    def _handle_notification(self, method: str, params: dict[str, Any]) -> None:
-        """Handle notification from CodexAppServerClient.
-
-        This is the callback registered with the client for session tracking events.
-        """
-        try:
-            hook_event = self.translate_to_hook_event({"method": method, "params": params})
-
-            if hook_event and self._hook_manager:
-                # Process through HookManager (fire-and-forget for notifications)
-                self._hook_manager.handle(hook_event)
-                logger.debug(f"Processed Codex event: {method} -> {hook_event.event_type}")
-        except Exception as e:
-            logger.error(f"Error handling Codex notification {method}: {e}")
-
-    def _translate_approval_event(self, method: str, params: dict[str, Any]) -> HookEvent | None:
-        """Translate approval request to HookEvent."""
-        if method not in self.EVENT_MAP:
-            logger.debug(f"Unknown approval method: {method}")
-            return None
-
-        thread_id = params.get("threadId", "")
-        item_id = params.get("itemId", "")
-
-        # Determine tool name from method and normalize to CC-style
-        if "commandExecution" in method:
-            original_tool = "commandExecution"
-            tool_name = self.normalize_tool_name(original_tool)  # -> "Bash"
-            tool_input = params.get("parsedCmd", params.get("command", ""))
-        elif "fileChange" in method:
-            original_tool = "fileChange"
-            tool_name = "Write"  # File changes are writes
-            tool_input = params.get("changes", [])
-        else:
-            original_tool = "unknown"
-            tool_name = "unknown"
-            tool_input = params
-
-        return HookEvent(
-            event_type=HookEventType.BEFORE_TOOL,
-            session_id=thread_id,
-            source=self.source,
-            timestamp=datetime.now(UTC),
-            machine_id=self._get_machine_id(),
-            data={
-                "tool_name": tool_name,
-                "tool_input": tool_input,
-                "item_id": item_id,
-                "turn_id": params.get("turnId", ""),
-                "reason": params.get("reason"),
-                "risk": params.get("risk"),
-            },
-            metadata={
-                "requires_response": True,
-                "item_id": item_id,
-                "approval_method": method,
-                "original_tool_name": original_tool,
-                "normalized_tool_name": tool_name,
-            },
-        )
-
-    def translate_to_hook_event(self, native_event: dict[str, Any]) -> HookEvent | None:
-        """Convert Codex app-server event to unified HookEvent.
-
-        Codex events come as JSON-RPC notifications:
-        {
-            "method": "thread/started",
-            "params": {
-                "thread": {"id": "thr_123", "preview": "...", ...}
-            }
-        }
-
-        Args:
-            native_event: JSON-RPC notification with method and params.
-
-        Returns:
-            Unified HookEvent, or None for unsupported events.
-        """
-        method = native_event.get("method", "")
-        params = native_event.get("params", {})
-
-        # Handle different event types
-        if method == "thread/started":
-            thread = params.get("thread", {})
-            return HookEvent(
-                event_type=HookEventType.SESSION_START,
-                session_id=thread.get("id", ""),
-                source=self.source,
-                timestamp=self._parse_timestamp(thread.get("createdAt")),
-                machine_id=self._get_machine_id(),
-                data={
-                    "preview": thread.get("preview", ""),
-                    "model_provider": thread.get("modelProvider", ""),
-                },
-            )
-
-        if method == "thread/archive":
-            return HookEvent(
-                event_type=HookEventType.SESSION_END,
-                session_id=params.get("threadId", ""),
-                source=self.source,
-                timestamp=datetime.now(UTC),
-                machine_id=self._get_machine_id(),
-                data=params,
-            )
-
-        if method == "turn/started":
-            turn = params.get("turn", {})
-            return HookEvent(
-                event_type=HookEventType.BEFORE_AGENT,
-                session_id=params.get("threadId", turn.get("id", "")),
-                source=self.source,
-                timestamp=datetime.now(UTC),
-                machine_id=self._get_machine_id(),
-                data={
-                    "turn_id": turn.get("id", ""),
-                    "status": turn.get("status", ""),
-                },
-            )
-
-        if method == "turn/completed":
-            turn = params.get("turn", {})
-            return HookEvent(
-                event_type=HookEventType.AFTER_AGENT,
-                session_id=params.get("threadId", turn.get("id", "")),
-                source=self.source,
-                timestamp=datetime.now(UTC),
-                machine_id=self._get_machine_id(),
-                data={
-                    "turn_id": turn.get("id", ""),
-                    "status": turn.get("status", ""),
-                    "error": turn.get("error"),
-                },
-            )
-
-        if method == "item/completed":
-            item = params.get("item", {})
-            item_type = item.get("type", "")
-
-            # Only translate tool-related items
-            if item_type in self.TOOL_ITEM_TYPES:
-                return HookEvent(
-                    event_type=HookEventType.AFTER_TOOL,
-                    session_id=params.get("threadId", ""),
-                    source=self.source,
-                    timestamp=datetime.now(UTC),
-                    machine_id=self._get_machine_id(),
-                    data={
-                        "item_id": item.get("id", ""),
-                        "item_type": item_type,
-                        "status": item.get("status", ""),
-                    },
-                )
-
-        # Unknown/unsupported event
-        logger.debug(f"Unsupported Codex event: {method}")
-        return None
-
-    def translate_from_hook_response(
-        self, response: HookResponse, hook_type: str | None = None
-    ) -> dict[str, Any]:
-        """Convert HookResponse to Codex approval response format.
-
-        Codex expects approval responses as:
-        {
-            "decision": "accept" | "decline"
-        }
-
-        Args:
-            response: Unified HookResponse.
-            hook_type: Original Codex method (unused, kept for interface).
-
-        Returns:
-            Dict with decision field.
-        """
-        return {
-            "decision": "accept" if response.decision != "deny" else "decline",
-        }
-
-    def _parse_timestamp(self, unix_ts: int | float | None) -> datetime:
-        """Parse Unix timestamp to datetime.
-
-        Args:
-            unix_ts: Unix timestamp (seconds).
-
-        Returns:
-            datetime object, or now() if parsing fails.
-        """
-        if unix_ts:
-            try:
-                return datetime.fromtimestamp(unix_ts)
-            except (ValueError, OSError):
-                pass
-        return datetime.now(UTC)
-
-    async def sync_existing_sessions(self) -> int:
-        """Sync existing Codex threads to platform sessions.
-
-        Uses the attached CodexAppServerClient to list threads and registers
-        them as sessions via HookManager.
-
-        Requires:
-        - CodexAdapter attached to a CodexAppServerClient
-        - CodexAppServerClient is connected
-        - HookManager is set
-
-        Returns:
-            Number of threads synced.
-        """
-        if not self._hook_manager:
-            logger.warning("No hook_manager - cannot sync sessions")
-            return 0
-
-        if not self._codex_client:
-            logger.warning("No CodexAppServerClient attached - cannot sync sessions")
-            return 0
-
-        if not self._codex_client.is_connected:
-            logger.warning("CodexAppServerClient not connected - cannot sync sessions")
-            return 0
-
-        try:
-            # Use CodexAppServerClient to list threads
-            all_threads = []
-            cursor = None
-
-            while True:
-                threads, next_cursor = await self._codex_client.list_threads(
-                    cursor=cursor, limit=100
-                )
-                all_threads.extend(threads)
-
-                if not next_cursor:
-                    break
-                cursor = next_cursor
-
-            synced = 0
-            for thread in all_threads:
-                try:
-                    event = HookEvent(
-                        event_type=HookEventType.SESSION_START,
-                        session_id=thread.id,
-                        source=self.source,
-                        timestamp=self._parse_timestamp(thread.created_at),
-                        machine_id=self._get_machine_id(),
-                        data={
-                            "preview": thread.preview,
-                            "model_provider": thread.model_provider,
-                            "synced_from_existing": True,
-                        },
-                    )
-                    self._hook_manager.handle(event)
-                    synced += 1
-                except Exception as e:
-                    logger.error(f"Failed to sync thread {thread.id}: {e}")
-
-            logger.debug(f"Synced {synced} existing Codex threads")
-            return synced
-
-        except Exception as e:
-            logger.error(f"Failed to sync existing sessions: {e}")
-            return 0
-
-
-# =============================================================================
-# Notify Adapter (for installed hooks via `gobby install --codex`)
-# =============================================================================
-
-
-class CodexNotifyAdapter(BaseAdapter):
-    """Adapter for Codex CLI notify events.
-
-    Translates notify payloads to unified HookEvent format.
-    The notify hook only fires on `agent-turn-complete`, so we:
-    - Treat first event for a thread as session start + prompt submit
-    - Track thread IDs to avoid duplicate session registration
-
-    This adapter handles events from the hook_dispatcher.py script installed
-    by `gobby install --codex`.
-    """
-
-    source = SessionSource.CODEX
-
-    def __init__(self, hook_manager: HookManager | None = None):
-        """Initialize the adapter.
-
-        Args:
-            hook_manager: Optional HookManager reference.
-        """
-        self._hook_manager = hook_manager
-        self._machine_id: str | None = None
-        # Track threads we've seen to avoid re-registering
-        self._seen_threads: set[str] = set()
-
-    def _get_machine_id(self) -> str:
-        """Get or generate a machine identifier."""
-        if self._machine_id is None:
-            self._machine_id = _get_machine_id()
-        return self._machine_id
-
-    def _find_jsonl_path(self, thread_id: str) -> str | None:
-        """Find the Codex session JSONL file for a thread.
-
-        Codex stores sessions at: ~/.codex/sessions/YYYY/MM/DD/rollout-{timestamp}-{thread-id}.jsonl
-
-        Args:
-            thread_id: The Codex thread ID
-
-        Returns:
-            Path to the JSONL file, or None if not found
-        """
-        if not CODEX_SESSIONS_DIR.exists():
-            return None
-
-        # Search for file ending with thread-id.jsonl
-        # Escape special glob characters in thread_id
-        safe_thread_id = glob_module.escape(thread_id)
-        pattern = str(CODEX_SESSIONS_DIR / "**" / f"*{safe_thread_id}.jsonl")
-        matches = glob_module.glob(pattern, recursive=True)
-
-        if matches:
-            # Return the most recent match (in case of duplicates)
-            return max(matches, key=os.path.getmtime)
-        return None
-
-    def _get_first_prompt(self, input_messages: list[Any]) -> str | None:
-        """Extract the first user prompt from input_messages.
-
-        Args:
-            input_messages: List of user messages from Codex
-
-        Returns:
-            First prompt string, or None
-        """
-        if input_messages and isinstance(input_messages, list) and len(input_messages) > 0:
-            first = input_messages[0]
-            if isinstance(first, str):
-                return first
-            elif isinstance(first, dict):
-                return first.get("text") or first.get("content")
-        return None
-
-    def translate_to_hook_event(self, native_event: dict[str, Any]) -> HookEvent | None:
-        """Convert Codex notify payload to HookEvent.
-
-        The native_event structure from /hooks/execute:
-        {
-            "hook_type": "AgentTurnComplete",
-            "input_data": {
-                "session_id": "thread-id",
-                "event_type": "agent-turn-complete",
-                "last_message": "...",
-                "input_messages": [...],
-                "cwd": "/path/to/project",
-                "turn_id": "1"
-            },
-            "source": "codex"
-        }
-
-        Args:
-            native_event: The payload from the HTTP endpoint.
-
-        Returns:
-            HookEvent for processing, or None if unsupported.
-        """
-        input_data = native_event.get("input_data", {})
-        thread_id = input_data.get("session_id", "")
-        event_type = input_data.get("event_type", "unknown")
-        input_messages = input_data.get("input_messages", [])
-        cwd = input_data.get("cwd") or os.getcwd()
-
-        if not thread_id:
-            logger.warning("Codex notify event missing thread_id")
-            return None
-
-        # Find the JSONL transcript file
-        jsonl_path = self._find_jsonl_path(thread_id)
-
-        # Track if this is the first event for this thread (for title synthesis)
-        is_first_event = thread_id not in self._seen_threads
-        if is_first_event:
-            self._seen_threads.add(thread_id)
-
-        # Get first prompt for title synthesis (only on first event)
-        first_prompt = self._get_first_prompt(input_messages) if is_first_event else None
-
-        # All Codex notify events are AFTER_AGENT (turn complete)
-        # The HookManager will auto-register the session if it doesn't exist
-        return HookEvent(
-            event_type=HookEventType.AFTER_AGENT,
-            session_id=thread_id,
-            source=self.source,
-            timestamp=datetime.now(UTC),
-            machine_id=self._get_machine_id(),
-            data={
-                "cwd": cwd,
-                "event_type": event_type,
-                "last_message": input_data.get("last_message", ""),
-                "input_messages": input_messages,
-                "transcript_path": jsonl_path,
-                "is_first_event": is_first_event,
-                "prompt": first_prompt,  # For title synthesis on first event
-            },
-        )
-
-    def translate_from_hook_response(
-        self, response: HookResponse, hook_type: str | None = None
-    ) -> dict[str, Any]:
-        """Convert HookResponse to Codex-expected format.
-
-        Codex notify doesn't expect a response - it's fire-and-forget.
-        This just returns a simple status dict for logging.
-
-        Args:
-            response: The HookResponse from HookManager.
-            hook_type: Ignored (notify doesn't need response routing).
-
-        Returns:
-            Simple status dict.
-        """
-        return {
-            "status": "processed",
-            "decision": response.decision,
-        }
-
-    def handle_native(
-        self, native_event: dict[str, Any], hook_manager: HookManager
-    ) -> dict[str, Any]:
-        """Process native Codex notify event.
-
-        Args:
-            native_event: The payload from HTTP endpoint.
-            hook_manager: HookManager instance for processing.
-
-        Returns:
-            Response dict.
-        """
-        hook_event = self.translate_to_hook_event(native_event)
-        if not hook_event:
-            return {"status": "skipped", "message": "Unsupported event"}
-
-        hook_response = hook_manager.handle(hook_event)
-        return self.translate_from_hook_response(hook_response)