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

gobby/agents/spawn_executor.py

@@ -0,0 +1,385 @@
+"""
+Unified Spawn Executor for Agent Spawning.
+
+This module consolidates the spawn dispatch logic from agents.py, worktrees.py,
+and clones.py into a single unified executor that handles terminal, embedded,
+and headless modes.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from gobby.agents.sandbox import SandboxConfig
+
+if TYPE_CHECKING:
+    from gobby.agents.session import ChildSessionManager
+from gobby.agents.spawn import (
+    TerminalSpawner,
+    build_codex_command_with_resume,
+    build_gemini_command_with_resume,
+    prepare_codex_spawn_with_preflight,
+    prepare_gemini_spawn_with_preflight,
+)
+from gobby.agents.spawners.embedded import EmbeddedSpawner
+from gobby.agents.spawners.headless import HeadlessSpawner
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SpawnRequest:
+    """Request for spawning an agent."""
+
+    # Required fields
+    prompt: str
+    cwd: str
+    mode: Literal["terminal", "embedded", "headless"]
+    provider: str
+    terminal: str
+    session_id: str
+    run_id: str
+    parent_session_id: str
+    project_id: str
+
+    # Optional fields
+    workflow: str | None = None
+    worktree_id: str | None = None
+    clone_id: str | None = None
+    agent_depth: int = 0
+    max_agent_depth: int = 3
+    session_manager: Any | None = None  # Required for Gemini/Codex preflight
+    machine_id: str | None = None
+
+    # Sandbox configuration
+    sandbox_config: SandboxConfig | None = None
+    sandbox_args: list[str] | None = None
+    sandbox_env: dict[str, str] | None = field(default=None)
+
+
+@dataclass
+class SpawnResult:
+    """Result of a spawn operation."""
+
+    success: bool
+    run_id: str
+    child_session_id: str
+    status: str
+
+    # Optional result fields
+    pid: int | None = None
+    terminal_type: str | None = None
+    master_fd: int | None = None
+    error: str | None = None
+    message: str | None = None
+    process: Any | None = None  # subprocess.Popen for headless
+    gemini_session_id: str | None = None  # Gemini external session ID
+    codex_session_id: str | None = None  # Codex external session ID
+
+
+async def execute_spawn(request: SpawnRequest) -> SpawnResult:
+    """
+    Unified spawn dispatch for terminal/embedded/headless modes.
+
+    Consolidates duplicated logic from agents.py, worktrees.py, clones.py
+    into a single dispatch function.
+
+    Args:
+        request: SpawnRequest with all spawn parameters
+
+    Returns:
+        SpawnResult with spawn outcome and metadata
+    """
+    if request.mode == "terminal":
+        # Special handling for Gemini/Codex: requires preflight session capture
+        if request.provider == "gemini":
+            return await _spawn_gemini_terminal(request)
+        elif request.provider == "codex":
+            return await _spawn_codex_terminal(request)
+        return await _spawn_terminal(request)
+    elif request.mode == "embedded":
+        return await _spawn_embedded(request)
+    else:  # headless
+        return await _spawn_headless(request)
+
+
+async def _spawn_terminal(request: SpawnRequest) -> SpawnResult:
+    """Spawn agent in external terminal."""
+    spawner = TerminalSpawner()
+    result = spawner.spawn_agent(
+        cli=request.provider,
+        cwd=request.cwd,
+        session_id=request.session_id,
+        parent_session_id=request.parent_session_id,
+        agent_run_id=request.run_id,
+        project_id=request.project_id,
+        workflow_name=request.workflow,
+        agent_depth=request.agent_depth,
+        max_agent_depth=request.max_agent_depth,
+        terminal=request.terminal,
+        prompt=request.prompt,
+        sandbox_config=request.sandbox_config,
+    )
+
+    if not result.success:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error=result.error or result.message,
+        )
+
+    return SpawnResult(
+        success=True,
+        run_id=request.run_id,
+        child_session_id=request.session_id,
+        status="pending",
+        pid=result.pid,
+        terminal_type=result.terminal_type,
+        message=f"Agent spawned in {result.terminal_type} (PID: {result.pid})",
+    )
+
+
+async def _spawn_embedded(request: SpawnRequest) -> SpawnResult:
+    """Spawn agent with PTY for UI attachment."""
+    spawner = EmbeddedSpawner()
+    result = spawner.spawn_agent(
+        cli=request.provider,
+        cwd=request.cwd,
+        session_id=request.session_id,
+        parent_session_id=request.parent_session_id,
+        agent_run_id=request.run_id,
+        project_id=request.project_id,
+        workflow_name=request.workflow,
+        agent_depth=request.agent_depth,
+        max_agent_depth=request.max_agent_depth,
+        prompt=request.prompt,
+        sandbox_config=request.sandbox_config,
+    )
+
+    if not result.success:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error=result.error or result.message,
+        )
+
+    return SpawnResult(
+        success=True,
+        run_id=request.run_id,
+        child_session_id=request.session_id,
+        status="pending",
+        pid=result.pid,
+        master_fd=result.master_fd,
+        message=f"Agent spawned with PTY (PID: {result.pid})",
+    )
+
+
+async def _spawn_headless(request: SpawnRequest) -> SpawnResult:
+    """Spawn headless agent with output capture."""
+    spawner = HeadlessSpawner()
+    result = spawner.spawn_agent(
+        cli=request.provider,
+        cwd=request.cwd,
+        session_id=request.session_id,
+        parent_session_id=request.parent_session_id,
+        agent_run_id=request.run_id,
+        project_id=request.project_id,
+        workflow_name=request.workflow,
+        agent_depth=request.agent_depth,
+        max_agent_depth=request.max_agent_depth,
+        prompt=request.prompt,
+        sandbox_config=request.sandbox_config,
+    )
+
+    if not result.success:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error=result.error or result.message,
+        )
+
+    return SpawnResult(
+        success=True,
+        run_id=request.run_id,
+        child_session_id=request.session_id,
+        status="running",  # Headless is immediately running
+        pid=result.pid,
+        process=result.process,
+        message=f"Agent spawned headless (PID: {result.pid})",
+    )
+
+
+async def _spawn_gemini_terminal(request: SpawnRequest) -> SpawnResult:
+    """
+    Spawn Gemini agent in terminal with preflight session capture.
+
+    Gemini CLI in interactive mode can't introspect its session_id, so we:
+    1. Launch preflight to capture session_id from stream-json output
+    2. Create Gobby session with external_id = gemini's session_id
+    3. Launch interactive with -r {session_id} to resume
+    """
+    if request.session_manager is None:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error="session_manager is required for Gemini preflight",
+        )
+
+    try:
+        # Preflight capture: gets Gemini's session_id and creates linked Gobby session
+        spawn_context = await prepare_gemini_spawn_with_preflight(
+            session_manager=cast("ChildSessionManager", request.session_manager),
+            parent_session_id=request.parent_session_id,
+            project_id=request.project_id,
+            machine_id=request.machine_id or "unknown",
+            workflow_name=request.workflow,
+            git_branch=None,  # Will be detected by hook
+        )
+    except FileNotFoundError as e:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error=str(e),
+        )
+    except Exception as e:
+        logger.error(f"Gemini preflight capture failed: {e}", exc_info=True)
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error=f"Gemini preflight capture failed: {e}",
+        )
+
+    # Extract IDs from prepared spawn context
+    gobby_session_id = spawn_context.session_id
+    gemini_session_id = spawn_context.env_vars["GOBBY_GEMINI_EXTERNAL_ID"]
+
+    # Build command with session context injected into prompt
+    cmd = build_gemini_command_with_resume(
+        gemini_external_id=gemini_session_id,
+        prompt=request.prompt,
+        auto_approve=True,  # Subagents need to work autonomously
+        gobby_session_id=gobby_session_id,
+    )
+
+    # Spawn in terminal
+    terminal_spawner = TerminalSpawner()
+    terminal_result = terminal_spawner.spawn(
+        command=cmd,
+        cwd=request.cwd,
+        terminal=request.terminal,
+    )
+
+    if not terminal_result.success:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=gobby_session_id,
+            status="failed",
+            error=terminal_result.error or terminal_result.message,
+        )
+
+    return SpawnResult(
+        success=True,
+        run_id=f"gemini-{gemini_session_id[:8]}",
+        child_session_id=gobby_session_id,
+        status="pending",
+        pid=terminal_result.pid,
+        gemini_session_id=gemini_session_id,
+        message=f"Gemini agent spawned in terminal with session {gobby_session_id}",
+    )
+
+
+async def _spawn_codex_terminal(request: SpawnRequest) -> SpawnResult:
+    """
+    Spawn Codex agent in terminal with preflight session capture.
+
+    Codex outputs session_id in startup banner, which we parse from `codex exec "exit"`.
+    """
+    if request.session_manager is None:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error="session_manager is required for Codex preflight",
+        )
+
+    try:
+        # Preflight capture: gets Codex's session_id and creates linked Gobby session
+        spawn_context = await prepare_codex_spawn_with_preflight(
+            session_manager=cast("ChildSessionManager", request.session_manager),
+            parent_session_id=request.parent_session_id,
+            project_id=request.project_id,
+            machine_id=request.machine_id or "unknown",
+            workflow_name=request.workflow,
+            git_branch=None,  # Will be detected by hook
+        )
+    except FileNotFoundError as e:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error=str(e),
+        )
+    except Exception as e:
+        logger.error(f"Codex preflight capture failed: {e}", exc_info=True)
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=request.session_id,
+            status="failed",
+            error=f"Codex preflight capture failed: {e}",
+        )
+
+    # Extract IDs from prepared spawn context
+    gobby_session_id = spawn_context.session_id
+    codex_session_id = spawn_context.env_vars["GOBBY_CODEX_EXTERNAL_ID"]
+
+    # Build command with session context injected into prompt
+    cmd = build_codex_command_with_resume(
+        codex_external_id=codex_session_id,
+        prompt=request.prompt,
+        auto_approve=True,  # --full-auto for sandboxed autonomy
+        gobby_session_id=gobby_session_id,
+        working_directory=request.cwd,
+    )
+
+    # Spawn in terminal
+    terminal_spawner = TerminalSpawner()
+    terminal_result = terminal_spawner.spawn(
+        command=cmd,
+        cwd=request.cwd,
+        terminal=request.terminal,
+    )
+
+    if not terminal_result.success:
+        return SpawnResult(
+            success=False,
+            run_id=request.run_id,
+            child_session_id=gobby_session_id,
+            status="failed",
+            error=terminal_result.error or terminal_result.message,
+        )
+
+    return SpawnResult(
+        success=True,
+        run_id=f"codex-{codex_session_id[:8]}",
+        child_session_id=gobby_session_id,
+        status="pending",
+        pid=terminal_result.pid,
+        codex_session_id=codex_session_id,
+        message=f"Codex agent spawned in terminal with session {gobby_session_id}",
+    )

gobby/agents/spawners/__init__.py

@@ -14,6 +14,12 @@ Usage:
         ITermSpawner,
         # etc.
     )
+
+    # Command building
+    from gobby.agents.spawners import build_cli_command
+
+    # Prompt file management
+    from gobby.agents.spawners import create_prompt_file, read_prompt_from_env
 """
 
 from gobby.agents.spawners.base import (
@@ -24,6 +30,11 @@ from gobby.agents.spawners.base import (
     TerminalSpawnerBase,
     TerminalType,
 )
+from gobby.agents.spawners.command_builder import (
+    build_cli_command,
+    build_codex_command_with_resume,
+    build_gemini_command_with_resume,
+)
 from gobby.agents.spawners.cross_platform import (
     AlacrittySpawner,
     KittySpawner,
@@ -40,6 +51,11 @@ from gobby.agents.spawners.macos import (
     ITermSpawner,
     TerminalAppSpawner,
 )
+from gobby.agents.spawners.prompt_manager import (
+    MAX_ENV_PROMPT_LENGTH,
+    create_prompt_file,
+    read_prompt_from_env,
+)
 from gobby.agents.spawners.windows import (
     CmdSpawner,
     PowerShellSpawner,
@@ -74,4 +90,12 @@ __all__ = [
     # Embedded/Headless spawners
     "EmbeddedSpawner",
     "HeadlessSpawner",
+    # Command building
+    "build_cli_command",
+    "build_gemini_command_with_resume",
+    "build_codex_command_with_resume",
+    # Prompt management
+    "MAX_ENV_PROMPT_LENGTH",
+    "create_prompt_file",
+    "read_prompt_from_env",
 ]

gobby/agents/spawners/command_builder.py

@@ -0,0 +1,189 @@
+"""CLI command building for agent spawning.
+
+Provides functions to construct CLI commands for Claude, Gemini, and Codex
+with proper flags for prompts, permissions, and session management.
+"""
+
+from __future__ import annotations
+
+
+def build_cli_command(
+    cli: str,
+    prompt: str | None = None,
+    session_id: str | None = None,
+    auto_approve: bool = False,
+    working_directory: str | None = None,
+    mode: str = "terminal",
+    sandbox_args: list[str] | None = None,
+) -> list[str]:
+    """
+    Build the CLI command with proper prompt passing and permission flags.
+
+    Each CLI has different syntax for passing prompts and handling permissions:
+
+    Claude Code:
+    - claude --session-id <uuid> --dangerously-skip-permissions [prompt]
+    - Use --dangerously-skip-permissions for autonomous subagent operation
+
+    Gemini CLI:
+    - gemini -i "prompt" (interactive mode with initial prompt)
+    - gemini --approval-mode yolo -i "prompt" (YOLO + interactive)
+    - gemini "prompt" (one-shot non-interactive for headless)
+
+    Codex CLI:
+    - codex --full-auto -C <dir> [PROMPT]
+    - Or: codex -c 'sandbox_permissions=["disk-full-read-access"]' -a never [PROMPT]
+
+    Args:
+        cli: CLI name (claude, gemini, codex)
+        prompt: Optional prompt to pass
+        session_id: Optional session ID (used by Claude CLI)
+        auto_approve: If True, add flags to auto-approve actions/permissions
+        working_directory: Optional working directory (used by Codex -C flag)
+        mode: Execution mode - "terminal" (interactive) or "headless" (non-interactive)
+        sandbox_args: Optional list of CLI args for sandbox configuration
+
+    Returns:
+        Command list for subprocess execution
+    """
+    command = [cli]
+
+    if cli == "claude":
+        # Claude CLI flags
+        if session_id:
+            command.extend(["--session-id", session_id])
+        if auto_approve:
+            # Skip all permission prompts for autonomous subagent operation
+            command.append("--dangerously-skip-permissions")
+        # For headless mode, use -p (print mode) for single-turn execution
+        # For terminal mode, don't use -p to allow multi-turn interaction
+        if prompt and mode != "terminal":
+            command.append("-p")
+
+    elif cli == "gemini":
+        # Gemini CLI flags
+        if auto_approve:
+            command.extend(["--approval-mode", "yolo"])
+        # For terminal mode, use -i (prompt-interactive) to execute prompt and stay interactive
+        # For headless mode, use positional prompt for one-shot execution
+        if prompt:
+            if mode == "terminal":
+                command.extend(["-i", prompt])
+                # Add sandbox args before returning (prompt already added via -i flag)
+                if sandbox_args:
+                    command.extend(sandbox_args)
+                return command  # Don't add prompt again as positional
+            # else: fall through to add as positional for headless
+
+    elif cli == "codex":
+        # Codex CLI flags
+        if auto_approve:
+            # --full-auto: low-friction sandboxed automatic execution
+            command.append("--full-auto")
+        if working_directory:
+            command.extend(["-C", working_directory])
+
+    # Add sandbox args before prompt (prompt must be last)
+    if sandbox_args:
+        command.extend(sandbox_args)
+
+    # All three CLIs accept prompt as positional argument (must come last)
+    # For Gemini terminal mode, this is skipped (handled above with -i flag)
+    if prompt:
+        command.append(prompt)
+
+    return command
+
+
+def build_gemini_command_with_resume(
+    gemini_external_id: str,
+    prompt: str | None = None,
+    auto_approve: bool = False,
+    gobby_session_id: str | None = None,
+) -> list[str]:
+    """
+    Build Gemini CLI command with session resume.
+
+    Uses -r flag to resume a preflight-captured session, with session context
+    injected into the initial prompt.
+
+    Args:
+        gemini_external_id: Gemini's session_id from preflight capture
+        prompt: Optional user prompt
+        auto_approve: If True, add --approval-mode yolo
+        gobby_session_id: Gobby session ID to inject into context
+
+    Returns:
+        Command list for subprocess execution
+    """
+    command = ["gemini"]
+
+    # Resume the preflight session
+    command.extend(["-r", gemini_external_id])
+
+    if auto_approve:
+        command.extend(["--approval-mode", "yolo"])
+
+    # Build prompt with session context
+    if gobby_session_id:
+        context_prefix = (
+            f"Your Gobby session_id is: {gobby_session_id}\n"
+            f"Use this when calling Gobby MCP tools.\n\n"
+        )
+        full_prompt = context_prefix + (prompt or "")
+    else:
+        full_prompt = prompt or ""
+
+    # Use -i for interactive mode with initial prompt
+    if full_prompt:
+        command.extend(["-i", full_prompt])
+
+    return command
+
+
+def build_codex_command_with_resume(
+    codex_external_id: str,
+    prompt: str | None = None,
+    auto_approve: bool = False,
+    gobby_session_id: str | None = None,
+    working_directory: str | None = None,
+) -> list[str]:
+    """
+    Build Codex CLI command with session resume.
+
+    Uses `codex resume {session_id}` to resume a preflight-captured session,
+    with session context injected into the prompt.
+
+    Args:
+        codex_external_id: Codex's session_id from preflight capture
+        prompt: Optional user prompt
+        auto_approve: If True, add --full-auto flag
+        gobby_session_id: Gobby session ID to inject into context
+        working_directory: Optional working directory override
+
+    Returns:
+        Command list for subprocess execution
+    """
+    command = ["codex", "resume", codex_external_id]
+
+    if auto_approve:
+        command.append("--full-auto")
+
+    if working_directory:
+        command.extend(["-C", working_directory])
+
+    # Build prompt with session context
+    if gobby_session_id:
+        context_prefix = (
+            f"Your Gobby session_id is: {gobby_session_id}\n"
+            f"Use this when calling Gobby MCP tools.\n\n"
+        )
+        full_prompt = context_prefix + (prompt or "")
+    else:
+        full_prompt = prompt or ""
+
+    # Prompt is a positional argument after session_id
+    if full_prompt:
+        command.append(full_prompt)
+
+    return command

gobby/agents/spawners/embedded.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from gobby.agents.constants import get_terminal_env_vars
+from gobby.agents.sandbox import SandboxConfig, compute_sandbox_paths, get_sandbox_resolver
 from gobby.agents.spawners.base import EmbeddedPTYResult
 
 # pty is only available on Unix-like systems
@@ -37,11 +38,11 @@ def _get_spawn_utils() -> tuple[
         MAX_ENV_PROMPT_LENGTH as _MAX_ENV_PROMPT_LENGTH,
     )
     from gobby.agents.spawn import (
-        _create_prompt_file,
         build_cli_command,
+        create_prompt_file,
     )
 
-    return build_cli_command, _create_prompt_file, _MAX_ENV_PROMPT_LENGTH
+    return build_cli_command, create_prompt_file, _MAX_ENV_PROMPT_LENGTH
 
 
 class EmbeddedSpawner:
@@ -169,6 +170,7 @@ class EmbeddedSpawner:
         agent_depth: int = 1,
         max_agent_depth: int = 3,
         prompt: str | None = None,
+        sandbox_config: SandboxConfig | None = None,
     ) -> EmbeddedPTYResult:
         """
         Spawn a CLI agent with embedded PTY.
@@ -184,12 +186,24 @@ class EmbeddedSpawner:
             agent_depth: Current nesting depth
             max_agent_depth: Maximum allowed depth
             prompt: Optional initial prompt
+            sandbox_config: Optional sandbox configuration
 
         Returns:
             EmbeddedPTYResult with PTY info
         """
         build_cli_command, _create_prompt_file, max_env_prompt_length = _get_spawn_utils()
 
+        # Resolve sandbox configuration if enabled
+        sandbox_args: list[str] | None = None
+        sandbox_env: dict[str, str] = {}
+
+        if sandbox_config and sandbox_config.enabled:
+            # Compute sandbox paths based on cwd (workspace)
+            resolved_paths = compute_sandbox_paths(sandbox_config, str(cwd))
+            # Get CLI-specific resolver and generate args/env
+            resolver = get_sandbox_resolver(cli)
+            sandbox_args, sandbox_env = resolver.resolve(sandbox_config, resolved_paths)
+
         # Build command with prompt as CLI argument and auto-approve for autonomous work
         command = build_cli_command(
             cli,
@@ -197,6 +211,7 @@ class EmbeddedSpawner:
             session_id=session_id,
             auto_approve=True,  # Subagents need to work autonomously
             working_directory=str(cwd) if cli == "codex" else None,
+            sandbox_args=sandbox_args,
         )
 
         # Handle prompt for environment variables (backup for hooks/context)
@@ -222,4 +237,8 @@ class EmbeddedSpawner:
             prompt_file=prompt_file,
         )
 
+        # Merge sandbox environment variables if present
+        if sandbox_env:
+            env.update(sandbox_env)
+
         return self.spawn(command, cwd, env)