gobby 0.2.5__py3-none-any.whl

gobby/adapters/gemini.py

@@ -0,0 +1,343 @@
+"""Gemini CLI adapter for hook translation.
+
+This adapter translates between Gemini CLI's native hook format and the unified
+HookEvent/HookResponse models.
+
+Gemini CLI Hook Types (11 total):
+- SessionStart, SessionEnd: Session lifecycle
+- BeforeAgent, AfterAgent: Agent turn lifecycle
+- BeforeTool, AfterTool: Tool execution lifecycle
+- BeforeToolSelection: Before tool selection (Gemini-only)
+- BeforeModel, AfterModel: Model call lifecycle (Gemini-only)
+- PreCompress: Context compression (maps to PRE_COMPACT)
+- Notification: System notifications
+
+Key differences from Claude Code:
+- Uses PascalCase hook names (SessionStart vs session-start)
+- Uses `hook_event_name` field instead of `hook_type`
+- Has BeforeToolSelection, BeforeModel, AfterModel (not in Claude)
+- Missing PermissionRequest, SubagentStart, SubagentStop (Claude-only)
+- Different tool names (RunShellCommand vs Bash)
+"""
+
+import platform
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+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
+
+
+class GeminiAdapter(BaseAdapter):
+    """Adapter for Gemini CLI hook translation.
+
+    This adapter:
+    1. Translates Gemini CLI's PascalCase hook payloads to unified HookEvent
+    2. Translates HookResponse back to Gemini CLI's expected format
+    3. Calls HookManager.handle() with unified HookEvent model
+    """
+
+    source = SessionSource.GEMINI
+
+    # Event type mapping: Gemini CLI hook names -> unified HookEventType
+    # Gemini CLI uses PascalCase hook names in the payload's "hook_event_name" field
+    EVENT_MAP: dict[str, HookEventType] = {
+        "SessionStart": HookEventType.SESSION_START,
+        "SessionEnd": HookEventType.SESSION_END,
+        "BeforeAgent": HookEventType.BEFORE_AGENT,
+        "AfterAgent": HookEventType.AFTER_AGENT,
+        "BeforeTool": HookEventType.BEFORE_TOOL,
+        "AfterTool": HookEventType.AFTER_TOOL,
+        "BeforeToolSelection": HookEventType.BEFORE_TOOL_SELECTION,  # Gemini-only
+        "BeforeModel": HookEventType.BEFORE_MODEL,  # Gemini-only
+        "AfterModel": HookEventType.AFTER_MODEL,  # Gemini-only
+        "PreCompress": HookEventType.PRE_COMPACT,  # Gemini calls it PreCompress
+        "Notification": HookEventType.NOTIFICATION,
+    }
+
+    # Reverse mapping for response translation
+    HOOK_EVENT_NAME_MAP: dict[str, str] = {
+        "session_start": "SessionStart",
+        "session_end": "SessionEnd",
+        "before_agent": "BeforeAgent",
+        "after_agent": "AfterAgent",
+        "before_tool": "BeforeTool",
+        "after_tool": "AfterTool",
+        "before_tool_selection": "BeforeToolSelection",
+        "before_model": "BeforeModel",
+        "after_model": "AfterModel",
+        "pre_compact": "PreCompress",
+        "notification": "Notification",
+    }
+
+    # Tool name mapping: Gemini tool names -> normalized names
+    # Gemini uses different tool names than Claude Code
+    TOOL_MAP: dict[str, str] = {
+        "run_shell_command": "Bash",
+        "RunShellCommand": "Bash",
+        "read_file": "Read",
+        "ReadFile": "Read",
+        "ReadFileTool": "Read",
+        "write_file": "Write",
+        "WriteFile": "Write",
+        "WriteFileTool": "Write",
+        "edit_file": "Edit",
+        "EditFile": "Edit",
+        "EditFileTool": "Edit",
+        "GlobTool": "Glob",
+        "GrepTool": "Grep",
+        "ShellTool": "Bash",
+    }
+
+    def __init__(self, hook_manager: "HookManager | None" = None):
+        """Initialize the Gemini CLI adapter.
+
+        Args:
+            hook_manager: Reference to HookManager for handling events.
+                         If None, the adapter can only translate (not handle events).
+        """
+        self._hook_manager = hook_manager
+        # Cache machine_id since Gemini doesn't always send it
+        self._machine_id: str | None = None
+
+    def _get_machine_id(self) -> str:
+        """Get or generate a machine identifier.
+
+        Gemini CLI doesn't always send machine_id, so we generate one
+        based on the platform node (hostname/MAC address).
+
+        Returns:
+            A stable machine identifier.
+        """
+        if self._machine_id is None:
+            # Use platform.node() which returns hostname or MAC-based ID
+            node = platform.node()
+            if node:
+                # Create a deterministic UUID from the node name
+                self._machine_id = str(uuid.uuid5(uuid.NAMESPACE_DNS, node))
+            else:
+                # Fallback to a random UUID (less ideal but works)
+                self._machine_id = str(uuid.uuid4())
+        return self._machine_id
+
+    def normalize_tool_name(self, gemini_tool_name: str) -> str:
+        """Normalize Gemini tool name to standard format.
+
+        Args:
+            gemini_tool_name: Tool name from Gemini CLI.
+
+        Returns:
+            Normalized tool name (e.g., "Bash", "Read", "Write").
+        """
+        return self.TOOL_MAP.get(gemini_tool_name, gemini_tool_name)
+
+    def translate_to_hook_event(self, native_event: dict[str, Any]) -> HookEvent:
+        """Convert Gemini CLI native event to unified HookEvent.
+
+        Gemini CLI payloads have the structure:
+        {
+            "hook_event_name": "SessionStart",  # PascalCase hook name
+            "session_id": "abc123",             # Session identifier
+            "cwd": "/path/to/project",
+            "timestamp": "2025-01-15T10:30:00Z", # ISO timestamp
+            # ... other hook-specific fields
+        }
+
+        Note: The hook_dispatcher.py wraps this in:
+        {
+            "source": "gemini",
+            "hook_type": "SessionStart",
+            "input_data": {...}  # The actual Gemini payload
+        }
+
+        Args:
+            native_event: Raw payload from Gemini CLI's hook_dispatcher.py
+
+        Returns:
+            Unified HookEvent with normalized fields.
+        """
+        # Extract from dispatcher wrapper format (matches Claude's structure)
+        hook_type = native_event.get("hook_type", "")
+        input_data = native_event.get("input_data", {})
+
+        # If input_data is empty, the native_event might BE the input_data
+        # (for direct Gemini calls without dispatcher wrapper)
+        if not input_data and "hook_event_name" in native_event:
+            input_data = native_event
+            hook_type = native_event.get("hook_event_name", "")
+
+        # Map Gemini hook type to unified event type
+        # Fall back to NOTIFICATION for unknown types (fail-open)
+        event_type = self.EVENT_MAP.get(hook_type, HookEventType.NOTIFICATION)
+
+        # Extract session_id
+        session_id = input_data.get("session_id", "")
+
+        # Parse timestamp if present (Gemini uses ISO format)
+        timestamp_str = input_data.get("timestamp")
+        if timestamp_str:
+            try:
+                timestamp = datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
+            except (ValueError, AttributeError):
+                timestamp = datetime.now(UTC)
+        else:
+            timestamp = datetime.now(UTC)
+
+        # Get machine_id (Gemini might not send it)
+        machine_id = input_data.get("machine_id") or self._get_machine_id()
+
+        # Normalize tool name if present (for tool-related hooks)
+        if "tool_name" in input_data:
+            original_tool = input_data.get("tool_name", "")
+            normalized_tool = self.normalize_tool_name(original_tool)
+            # Store both for logging/debugging
+            metadata = {
+                "original_tool_name": original_tool,
+                "normalized_tool_name": normalized_tool,
+            }
+        else:
+            metadata = {}
+
+        return HookEvent(
+            event_type=event_type,
+            session_id=session_id,
+            source=self.source,
+            timestamp=timestamp,
+            machine_id=machine_id,
+            cwd=input_data.get("cwd"),
+            data=input_data,
+            metadata=metadata,
+        )
+
+    def translate_from_hook_response(
+        self, response: HookResponse, hook_type: str | None = None
+    ) -> dict[str, Any]:
+        """Convert HookResponse to Gemini CLI's expected format.
+
+        Gemini CLI expects responses in this format:
+        {
+            "decision": "allow" | "deny",     # Whether to allow the action
+            "reason": "...",                   # Optional reason for decision
+            "hookSpecificOutput": {            # Hook-specific response data
+                "additionalContext": "...",    # Context to inject
+                "llm_request": {...},          # For BeforeModel hooks
+                "toolConfig": {...}            # For BeforeToolSelection hooks
+            }
+        }
+
+        Exit codes: 0 = allow, 2 = deny (handled by dispatcher)
+
+        Args:
+            response: Unified HookResponse from HookManager.
+            hook_type: Original Gemini CLI hook type (e.g., "SessionStart")
+                      Used to format hookSpecificOutput appropriately.
+
+        Returns:
+            Dict in Gemini CLI's expected format.
+        """
+        result: dict[str, Any] = {
+            "decision": response.decision,
+        }
+
+        # Add reason if present
+        if response.reason:
+            result["reason"] = response.reason
+
+        # Build hookSpecificOutput based on hook type
+        hook_specific: dict[str, Any] = {}
+
+        # Add context injection if present
+        if response.context:
+            hook_specific["additionalContext"] = response.context
+
+        # Add session/terminal context for SessionStart only
+        if hook_type == "SessionStart" and response.metadata:
+            session_id = response.metadata.get("session_id")
+            if session_id:
+                hook_event_name = self.HOOK_EVENT_NAME_MAP.get(hook_type, "Unknown")
+                context_lines = [f"session_id: {session_id}"]
+                if response.metadata.get("parent_session_id"):
+                    context_lines.append(
+                        f"parent_session_id: {response.metadata['parent_session_id']}"
+                    )
+                if response.metadata.get("machine_id"):
+                    context_lines.append(f"machine_id: {response.metadata['machine_id']}")
+                if response.metadata.get("project_id"):
+                    context_lines.append(f"project_id: {response.metadata['project_id']}")
+                # Add terminal context (non-null values only)
+                if response.metadata.get("terminal_term_program"):
+                    context_lines.append(f"terminal: {response.metadata['terminal_term_program']}")
+                if response.metadata.get("terminal_tty"):
+                    context_lines.append(f"tty: {response.metadata['terminal_tty']}")
+                if response.metadata.get("terminal_parent_pid"):
+                    context_lines.append(f"parent_pid: {response.metadata['terminal_parent_pid']}")
+                # Add terminal-specific session IDs
+                for key in [
+                    "terminal_iterm_session_id",
+                    "terminal_term_session_id",
+                    "terminal_kitty_window_id",
+                    "terminal_tmux_pane",
+                    "terminal_vscode_terminal_id",
+                    "terminal_alacritty_socket",
+                ]:
+                    if response.metadata.get(key):
+                        friendly_name = key.replace("terminal_", "").replace("_", " ")
+                        context_lines.append(f"{friendly_name}: {response.metadata[key]}")
+                hook_specific["hookEventName"] = hook_event_name
+                # Append to existing additionalContext if present
+                existing = hook_specific.get("additionalContext", "")
+                new_context = "\n".join(context_lines)
+                hook_specific["additionalContext"] = (
+                    f"{existing}\n{new_context}" if existing else new_context
+                )
+
+        # Handle BeforeModel-specific output (llm_request modification)
+        if hook_type == "BeforeModel" and response.modify_args:
+            hook_specific["llm_request"] = response.modify_args
+
+        # Handle BeforeToolSelection-specific output (toolConfig modification)
+        if hook_type == "BeforeToolSelection" and response.modify_args:
+            hook_specific["toolConfig"] = response.modify_args
+
+        # Only add hookSpecificOutput if there's content
+        if hook_specific:
+            result["hookSpecificOutput"] = hook_specific
+
+        # Add system message if present (user-visible notification)
+        if response.system_message:
+            result["systemMessage"] = response.system_message
+
+        return result
+
+    def handle_native(
+        self, native_event: dict[str, Any], hook_manager: "HookManager"
+    ) -> dict[str, Any]:
+        """Main entry point for HTTP endpoint.
+
+        Translates native Gemini CLI event, processes through HookManager,
+        and returns response in Gemini's expected format.
+
+        Args:
+            native_event: Raw payload from Gemini CLI's hook_dispatcher.py
+            hook_manager: HookManager instance for processing.
+
+        Returns:
+            Response dict in Gemini CLI's expected format.
+        """
+        # Translate to unified HookEvent
+        hook_event = self.translate_to_hook_event(native_event)
+
+        # Get original hook type for response formatting
+        hook_type = native_event.get("hook_type", "")
+        if not hook_type:
+            hook_type = native_event.get("input_data", {}).get("hook_event_name", "")
+
+        # Process through HookManager
+        hook_response = hook_manager.handle(hook_event)
+
+        # Translate response back to Gemini format
+        return self.translate_from_hook_response(hook_response, hook_type=hook_type)

gobby/agents/__init__.py

@@ -0,0 +1,37 @@
+"""
+Gobby Agents Module.
+
+This module provides the subagent spawning system, enabling agents to spawn
+independent subagents that can use any LLM provider and follow workflows.
+
+Components:
+- AgentRunner: Orchestrates agent execution with workflow integration
+- Session management: Creates and links child sessions to parents
+- Terminal spawning: Launches agents in separate terminal windows
+
+Usage:
+    from gobby.agents import AgentRunner, AgentConfig
+
+    runner = AgentRunner(db, session_storage, executors)
+    result = await runner.run(AgentConfig(
+        prompt="Review the auth changes",
+        parent_session_id="sess-123",
+        project_id="proj-abc",
+        machine_id="machine-1",
+        source="claude",
+        provider="claude",
+    ))
+"""
+
+from gobby.agents.registry import RunningAgent
+from gobby.agents.runner import AgentConfig, AgentRunContext, AgentRunner
+from gobby.agents.session import ChildSessionConfig, ChildSessionManager
+
+__all__ = [
+    "AgentConfig",
+    "AgentRunContext",
+    "AgentRunner",
+    "RunningAgent",
+    "ChildSessionConfig",
+    "ChildSessionManager",
+]

gobby/agents/codex_session.py

@@ -0,0 +1,120 @@
+"""Codex session ID capture utility.
+
+Captures Codex's session_id from the startup banner before launching interactive mode.
+This is necessary because we need the session_id to:
+1. Link to Gobby sessions (external_id)
+2. Resume functionality with `codex resume {session_id}`
+3. MCP tool calls that require session context
+"""
+
+import asyncio
+import logging
+import re
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+# Regex to match "session id: {uuid}" in startup banner
+SESSION_ID_PATTERN = re.compile(r"^session id:\s*([0-9a-f-]+)$", re.IGNORECASE)
+
+
+@dataclass
+class CodexSessionInfo:
+    """Captured Codex session information."""
+
+    session_id: str
+    model: str | None = None
+    workdir: str | None = None
+
+
+async def capture_codex_session_id(
+    timeout: float = 30.0,
+) -> CodexSessionInfo:
+    """Capture Codex's session_id via preflight exec call.
+
+    Launches Codex with minimal command (`codex exec "exit"`),
+    parses the startup banner for session_id, then returns.
+
+    The Codex banner format is:
+        OpenAI Codex v0.80.0 (research preview)
+        --------
+        workdir: /path/to/dir
+        model: gpt-5.2-codex
+        ...
+        session id: 019bbaea-3e0f-7d61-afc4-56a9456c2c7d
+        --------
+
+    Args:
+        timeout: Max seconds to wait for exec to complete (default 30s
+                 to account for model loading time)
+
+    Returns:
+        CodexSessionInfo with captured session_id and metadata
+
+    Raises:
+        asyncio.TimeoutError: If exec doesn't complete within timeout
+        ValueError: If session_id not found in output
+        FileNotFoundError: If codex CLI is not installed
+    """
+    logger.debug("Starting Codex preflight to capture session_id")
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "codex",
+            "exec",
+            "exit",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+    except FileNotFoundError as e:
+        raise FileNotFoundError(
+            "Codex CLI not found. Install from: https://github.com/openai/codex"
+        ) from e
+
+    try:
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+    except TimeoutError:
+        proc.kill()
+        await proc.wait()
+        raise
+
+    # Codex outputs the startup banner (including session id) to stderr
+    output = stderr.decode()
+    session_id: str | None = None
+    model: str | None = None
+    workdir: str | None = None
+
+    # Parse the startup banner
+    for line in output.splitlines():
+        line = line.strip()
+
+        # Match session id
+        match = SESSION_ID_PATTERN.match(line)
+        if match:
+            session_id = match.group(1)
+            continue
+
+        # Extract model if present
+        if line.startswith("model:"):
+            model = line.split(":", 1)[1].strip()
+            continue
+
+        # Extract workdir if present
+        if line.startswith("workdir:"):
+            workdir = line.split(":", 1)[1].strip()
+            continue
+
+    if not session_id:
+        # Log the output for debugging
+        logger.error(f"Failed to parse Codex output:\n{output}")
+        if stderr:
+            logger.error(f"Codex stderr:\n{stderr.decode()}")
+        raise ValueError("No session id found in Codex output")
+
+    logger.debug(f"Captured Codex session_id: {session_id}, model: {model}, workdir: {workdir}")
+
+    return CodexSessionInfo(
+        session_id=session_id,
+        model=model,
+        workdir=workdir,
+    )

gobby/agents/constants.py

@@ -0,0 +1,112 @@
+"""
+Constants for agent spawning and terminal mode.
+
+This module defines environment variables used to pass context to
+spawned terminal processes. When an agent spawns a child in terminal
+mode, these environment variables are set in the child process.
+"""
+
+# ============================================================================
+# Terminal Mode Environment Variables
+# ============================================================================
+# These environment variables are set when spawning a terminal-mode agent.
+# The child CLI process reads these to pick up its prepared state.
+# ============================================================================
+
+# Session identifier for the pre-created child session
+# The spawned CLI uses this to connect to its session via hooks
+GOBBY_SESSION_ID = "GOBBY_SESSION_ID"
+
+# Parent session identifier for context resolution
+# Used to look up parent session for context injection
+GOBBY_PARENT_SESSION_ID = "GOBBY_PARENT_SESSION_ID"
+
+# Agent run record identifier
+# Links the terminal process back to its agent_runs record
+GOBBY_AGENT_RUN_ID = "GOBBY_AGENT_RUN_ID"
+
+# Workflow name to activate on session start
+# The hook reads this and activates the workflow for the session
+GOBBY_WORKFLOW_NAME = "GOBBY_WORKFLOW_NAME"
+
+# Project identifier for the session
+# Used for project-scoped operations
+GOBBY_PROJECT_ID = "GOBBY_PROJECT_ID"
+
+# Current agent nesting depth
+# 0 = human-initiated, 1+ = agent-spawned
+GOBBY_AGENT_DEPTH = "GOBBY_AGENT_DEPTH"
+
+# Maximum allowed agent depth
+# Prevents infinite nesting
+GOBBY_MAX_AGENT_DEPTH = "GOBBY_MAX_AGENT_DEPTH"
+
+# Initial prompt for the agent (short prompts only)
+# For longer prompts, use GOBBY_PROMPT_FILE instead
+GOBBY_PROMPT = "GOBBY_PROMPT"
+
+# Path to file containing initial prompt (for long prompts)
+# Takes precedence over GOBBY_PROMPT if both are set
+GOBBY_PROMPT_FILE = "GOBBY_PROMPT_FILE"
+
+
+def get_terminal_env_vars(
+    session_id: str,
+    parent_session_id: str,
+    agent_run_id: str,
+    project_id: str,
+    workflow_name: str | None = None,
+    agent_depth: int = 1,
+    max_agent_depth: int = 3,
+    prompt: str | None = None,
+    prompt_file: str | None = None,
+) -> dict[str, str]:
+    """
+    Build environment variables dict for spawning a terminal-mode agent.
+
+    Args:
+        session_id: The pre-created child session ID.
+        parent_session_id: The parent session ID for context resolution.
+        agent_run_id: The agent run record ID.
+        project_id: The project ID.
+        workflow_name: Optional workflow to activate.
+        agent_depth: Current nesting depth (default: 1).
+        max_agent_depth: Maximum allowed depth (default: 3).
+        prompt: Optional short prompt (for inline passing).
+        prompt_file: Optional path to file containing prompt (for long prompts).
+
+    Returns:
+        Dict of environment variable name to value.
+    """
+    env = {
+        GOBBY_SESSION_ID: session_id,
+        GOBBY_PARENT_SESSION_ID: parent_session_id,
+        GOBBY_AGENT_RUN_ID: agent_run_id,
+        GOBBY_PROJECT_ID: project_id,
+        GOBBY_AGENT_DEPTH: str(agent_depth),
+        GOBBY_MAX_AGENT_DEPTH: str(max_agent_depth),
+    }
+
+    if workflow_name:
+        env[GOBBY_WORKFLOW_NAME] = workflow_name
+
+    if prompt_file:
+        env[GOBBY_PROMPT_FILE] = prompt_file
+    elif prompt:
+        env[GOBBY_PROMPT] = prompt
+
+    return env
+
+
+# List of all environment variable names for documentation
+ALL_TERMINAL_ENV_VARS = [
+    GOBBY_SESSION_ID,
+    GOBBY_PARENT_SESSION_ID,
+    GOBBY_AGENT_RUN_ID,
+    GOBBY_WORKFLOW_NAME,
+    GOBBY_PROJECT_ID,
+    GOBBY_AGENT_DEPTH,
+    GOBBY_MAX_AGENT_DEPTH,
+    GOBBY_PROMPT,
+    GOBBY_PROMPT_FILE,
+]