gobby 0.2.5__py3-none-any.whl

gobby/agents/spawners/__init__.py

@@ -0,0 +1,77 @@
+"""Terminal spawner implementations for agent execution.
+
+This package provides Strategy pattern implementations for spawning
+agents in various terminal types across different platforms.
+
+Usage:
+    from gobby.agents.spawners import (
+        TerminalSpawnerBase,
+        SpawnResult,
+        TerminalType,
+        SpawnMode,
+        # Platform-specific spawners
+        GhosttySpawner,
+        ITermSpawner,
+        # etc.
+    )
+"""
+
+from gobby.agents.spawners.base import (
+    EmbeddedPTYResult,
+    HeadlessResult,
+    SpawnMode,
+    SpawnResult,
+    TerminalSpawnerBase,
+    TerminalType,
+)
+from gobby.agents.spawners.cross_platform import (
+    AlacrittySpawner,
+    KittySpawner,
+    TmuxSpawner,
+)
+from gobby.agents.spawners.embedded import EmbeddedSpawner
+from gobby.agents.spawners.headless import HeadlessSpawner
+from gobby.agents.spawners.linux import (
+    GnomeTerminalSpawner,
+    KonsoleSpawner,
+)
+from gobby.agents.spawners.macos import (
+    GhosttySpawner,
+    ITermSpawner,
+    TerminalAppSpawner,
+)
+from gobby.agents.spawners.windows import (
+    CmdSpawner,
+    PowerShellSpawner,
+    WindowsTerminalSpawner,
+    WSLSpawner,
+)
+
+__all__ = [
+    # Base types
+    "SpawnMode",
+    "TerminalType",
+    "SpawnResult",
+    "EmbeddedPTYResult",
+    "HeadlessResult",
+    "TerminalSpawnerBase",
+    # macOS spawners
+    "GhosttySpawner",
+    "ITermSpawner",
+    "TerminalAppSpawner",
+    # Linux spawners
+    "GnomeTerminalSpawner",
+    "KonsoleSpawner",
+    # Windows spawners
+    "WindowsTerminalSpawner",
+    "CmdSpawner",
+    "PowerShellSpawner",
+    "WSLSpawner",
+    # Cross-platform spawners
+    "KittySpawner",
+    "AlacrittySpawner",
+    "TmuxSpawner",
+    # Embedded/Headless spawners
+    "EmbeddedSpawner",
+    "HeadlessSpawner",
+]

gobby/agents/spawners/base.py

@@ -0,0 +1,142 @@
+"""Base classes and types for terminal spawners."""
+
+from __future__ import annotations
+
+import os
+import subprocess  # nosec B404 - subprocess needed for terminal spawning
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+class SpawnMode(str, Enum):
+    """Agent execution mode."""
+
+    TERMINAL = "terminal"  # Spawn in external terminal window
+    EMBEDDED = "embedded"  # Return PTY handle for UI attachment
+    HEADLESS = "headless"  # Daemon captures output, no terminal visible
+    IN_PROCESS = "in_process"  # Run via SDK in daemon process
+
+
+class TerminalType(str, Enum):
+    """Supported terminal types."""
+
+    # macOS
+    GHOSTTY = "ghostty"
+    ITERM = "iterm"
+    TERMINAL_APP = "terminal.app"
+    KITTY = "kitty"
+    ALACRITTY = "alacritty"
+
+    # Linux
+    GNOME_TERMINAL = "gnome-terminal"
+    KONSOLE = "konsole"
+
+    # Windows
+    WINDOWS_TERMINAL = "windows-terminal"
+    CMD = "cmd"
+    POWERSHELL = "powershell"
+    WSL = "wsl"
+
+    # Cross-platform multiplexer
+    TMUX = "tmux"
+
+    # Auto-detect
+    AUTO = "auto"
+
+
+@dataclass
+class SpawnResult:
+    """Result of spawning a terminal process."""
+
+    success: bool
+    message: str
+    pid: int | None = None
+    terminal_type: str | None = None
+    error: str | None = None
+
+
+@dataclass
+class EmbeddedPTYResult:
+    """Result of spawning an embedded PTY process."""
+
+    success: bool
+    message: str
+    master_fd: int | None = None
+    """Master file descriptor for reading/writing to PTY."""
+    slave_fd: int | None = None
+    """Slave file descriptor (used by child process)."""
+    pid: int | None = None
+    """Child process PID."""
+    error: str | None = None
+
+    def close(self) -> None:
+        """Close the PTY file descriptors."""
+        if self.master_fd is not None:
+            try:
+                os.close(self.master_fd)
+            except OSError:
+                pass
+        if self.slave_fd is not None:
+            try:
+                os.close(self.slave_fd)
+            except OSError:
+                pass
+
+
+@dataclass
+class HeadlessResult:
+    """Result of spawning a headless process."""
+
+    success: bool
+    message: str
+    pid: int | None = None
+    """Child process PID."""
+    process: subprocess.Popen[Any] | None = None
+    """Subprocess handle for output capture."""
+    output_buffer: list[str] = field(default_factory=list)
+    """Captured output lines."""
+    error: str | None = None
+
+    def get_output(self) -> str:
+        """Get all captured output as a string."""
+        return "\n".join(self.output_buffer)
+
+
+class TerminalSpawnerBase(ABC):
+    """Base class for terminal spawners."""
+
+    @property
+    @abstractmethod
+    def terminal_type(self) -> TerminalType:
+        """The terminal type this spawner handles."""
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if this terminal is available on the system."""
+        pass
+
+    @abstractmethod
+    def spawn(
+        self,
+        command: list[str],
+        cwd: str | Path,
+        env: dict[str, str] | None = None,
+        title: str | None = None,
+    ) -> SpawnResult:
+        """
+        Spawn a new terminal window with the given command.
+
+        Args:
+            command: Command to run in the terminal
+            cwd: Working directory
+            env: Environment variables to set
+            title: Optional window title
+
+        Returns:
+            SpawnResult with success status and process info
+        """
+        pass

gobby/agents/spawners/cross_platform.py

@@ -0,0 +1,266 @@
+"""Cross-platform terminal spawners: Kitty, Alacritty, and tmux."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shlex
+import shutil
+import subprocess  # nosec B404 - subprocess needed for terminal spawning
+import time
+from pathlib import Path
+
+from gobby.agents.spawners.base import SpawnResult, TerminalSpawnerBase, TerminalType
+from gobby.agents.tty_config import get_tty_config
+
+__all__ = ["KittySpawner", "AlacrittySpawner", "TmuxSpawner"]
+
+
+class KittySpawner(TerminalSpawnerBase):
+    """Spawner for Kitty terminal."""
+
+    @property
+    def terminal_type(self) -> TerminalType:
+        return TerminalType.KITTY
+
+    def is_available(self) -> bool:
+        config = get_tty_config().get_terminal_config("kitty")
+        if not config.enabled:
+            return False
+        # On macOS, check app bundle; on other platforms check CLI
+        if platform.system() == "Darwin":
+            app_path = config.app_path or "/Applications/kitty.app"
+            return Path(app_path).exists()
+        command = config.command or "kitty"
+        return shutil.which(command) is not None
+
+    def spawn(
+        self,
+        command: list[str],
+        cwd: str | Path,
+        env: dict[str, str] | None = None,
+        title: str | None = None,
+    ) -> SpawnResult:
+        try:
+            tty_config = get_tty_config().get_terminal_config("kitty")
+            if platform.system() == "Darwin":
+                # On macOS, --detach doesn't work properly - command doesn't execute
+                # Use direct path without --detach, subprocess handles backgrounding
+                app_path = tty_config.app_path or "/Applications/kitty.app"
+                kitty_path = f"{app_path}/Contents/MacOS/kitty"
+                args = [kitty_path, "--directory", str(cwd)]
+            else:
+                # On Linux, --detach works correctly
+                cli_command = tty_config.command or "kitty"
+                args = [cli_command, "--detach", "--directory", str(cwd)]
+
+            # Add extra options from config (includes confirm_os_window_close=0 by default)
+            args.extend(tty_config.options)
+
+            if title:
+                args.extend(["--title", title])
+            # Add end-of-options separator before the user command
+            # This ensures command arguments starting with '-' are not interpreted as Kitty options
+            args.append("--")
+            args.extend(command)
+
+            spawn_env = os.environ.copy()
+            if env:
+                spawn_env.update(env)
+
+            process = subprocess.Popen(  # nosec B603 - args built from config
+                args,
+                env=spawn_env,
+                start_new_session=True,
+            )
+
+            return SpawnResult(
+                success=True,
+                message=f"Spawned Kitty with PID {process.pid}",
+                pid=process.pid,
+                terminal_type=self.terminal_type.value,
+            )
+
+        except Exception as e:
+            return SpawnResult(
+                success=False,
+                message=f"Failed to spawn Kitty: {e}",
+                error=str(e),
+            )
+
+
+class AlacrittySpawner(TerminalSpawnerBase):
+    """Spawner for Alacritty terminal."""
+
+    @property
+    def terminal_type(self) -> TerminalType:
+        return TerminalType.ALACRITTY
+
+    def is_available(self) -> bool:
+        config = get_tty_config().get_terminal_config("alacritty")
+        if not config.enabled:
+            return False
+        command = config.command or "alacritty"
+        return shutil.which(command) is not None
+
+    def spawn(
+        self,
+        command: list[str],
+        cwd: str | Path,
+        env: dict[str, str] | None = None,
+        title: str | None = None,
+    ) -> SpawnResult:
+        try:
+            tty_config = get_tty_config().get_terminal_config("alacritty")
+            cli_command = tty_config.command or "alacritty"
+            args = [cli_command, "--working-directory", str(cwd)]
+            # Add extra options from config
+            args.extend(tty_config.options)
+            if title:
+                args.extend(["--title", title])
+            args.extend(["-e"] + command)
+
+            spawn_env = os.environ.copy()
+            if env:
+                spawn_env.update(env)
+
+            process = subprocess.Popen(  # nosec B603 - args built from config
+                args,
+                env=spawn_env,
+                start_new_session=True,
+            )
+
+            return SpawnResult(
+                success=True,
+                message=f"Spawned Alacritty with PID {process.pid}",
+                pid=process.pid,
+                terminal_type=self.terminal_type.value,
+            )
+
+        except Exception as e:
+            return SpawnResult(
+                success=False,
+                message=f"Failed to spawn Alacritty: {e}",
+                error=str(e),
+            )
+
+
+class TmuxSpawner(TerminalSpawnerBase):
+    """
+    Spawner for tmux terminal multiplexer.
+
+    Creates a new detached tmux session that runs the command.
+    The session can be attached to later with `tmux attach -t <session>`.
+    """
+
+    @property
+    def terminal_type(self) -> TerminalType:
+        return TerminalType.TMUX
+
+    def is_available(self) -> bool:
+        # tmux is available on macOS and Linux (not Windows natively)
+        if platform.system() == "Windows":
+            return False
+        config = get_tty_config().get_terminal_config("tmux")
+        if not config.enabled:
+            return False
+        command = config.command or "tmux"
+        return shutil.which(command) is not None
+
+    def spawn(
+        self,
+        command: list[str],
+        cwd: str | Path,
+        env: dict[str, str] | None = None,
+        title: str | None = None,
+    ) -> SpawnResult:
+        try:
+            tty_config = get_tty_config().get_terminal_config("tmux")
+            cli_command = tty_config.command or "tmux"
+
+            # Generate a unique session name based on title or timestamp
+            session_name = title or f"gobby-{int(time.time())}"
+            # Sanitize session name (tmux doesn't like dots or colons)
+            session_name = session_name.replace(".", "-").replace(":", "-")
+
+            # Build tmux command:
+            # tmux new-session -d -s <name> -n <name> -c <cwd> <command> \
+            #   \; set-option destroy-unattached off \
+            #   \; set-environment VAR value ...
+            # -d: detached (runs in background)
+            # -s: session name
+            # -n: window name (title)
+            # -c: starting directory
+            # The chained set-option prevents session destruction when user has
+            # global destroy-unattached on (must be atomic with session creation)
+            args = [
+                cli_command,
+                "new-session",
+                "-d",  # Detached
+                "-s",
+                session_name,
+                "-n",
+                session_name,  # Window title
+                "-c",
+                str(cwd),
+            ]
+
+            # Add extra options from config
+            args.extend(tty_config.options)
+
+            # Build the command to run, injecting env vars if provided
+            # We export env vars in the shell command so they're available to the process
+            # (tmux set-environment only affects new processes, not the initial command)
+            if env:
+                # Build export statements for each env var
+                exports = " ".join(
+                    f"export {shlex.quote(k)}={shlex.quote(v)};" for k, v in env.items()
+                )
+                # Wrap command with exports
+                shell_cmd = f"{exports} exec {shlex.join(command)}"
+                args.extend(["sh", "-c", shell_cmd])
+            elif len(command) == 1:
+                args.append(command[0])
+            else:
+                # Use shell to handle complex commands with arguments
+                args.extend(["sh", "-c", shlex.join(command)])
+
+            # Chain set-option to disable destroy-unattached atomically
+            # This prevents the session from being destroyed before we can configure it
+            args.extend([";", "set-option", "-t", session_name, "destroy-unattached", "off"])
+
+            spawn_env = os.environ.copy()
+            if env:
+                spawn_env.update(env)
+
+            process = subprocess.Popen(  # nosec B603 - args built from config
+                args,
+                cwd=cwd,
+                env=spawn_env,
+                start_new_session=True,
+            )
+
+            # Wait for tmux to start (it exits quickly after creating the session)
+            process.wait()
+
+            if process.returncode != 0:
+                return SpawnResult(
+                    success=False,
+                    message=f"tmux exited with code {process.returncode}",
+                    error=f"tmux failed to create session '{session_name}'",
+                )
+
+            # pid=None since tmux process has exited; session_name is the identifier
+            return SpawnResult(
+                success=True,
+                message=f"Spawned tmux session '{session_name}' (attach with: tmux attach -t {session_name})",
+                pid=None,
+                terminal_type=self.terminal_type.value,
+            )
+
+        except Exception as e:
+            return SpawnResult(
+                success=False,
+                message=f"Failed to spawn tmux: {e}",
+                error=str(e),
+            )

gobby/agents/spawners/embedded.py

@@ -0,0 +1,225 @@
+"""Embedded PTY spawner for agent execution with UI attachment."""
+
+from __future__ import annotations
+
+import os
+import platform
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from gobby.agents.constants import get_terminal_env_vars
+from gobby.agents.spawners.base import EmbeddedPTYResult
+
+# pty is only available on Unix-like systems
+try:
+    import pty
+except ImportError:
+    pty = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["EmbeddedSpawner"]
+
+# Maximum prompt length to pass via environment variable
+# Longer prompts will be written to a temp file
+MAX_ENV_PROMPT_LENGTH = 4096
+
+
+# Import these from spawn.py to avoid duplication
+def _get_spawn_utils() -> tuple[
+    Callable[..., list[str]],
+    Callable[[str, str], str],
+    int,
+]:
+    """Lazy import to avoid circular dependencies."""
+    from gobby.agents.spawn import (
+        MAX_ENV_PROMPT_LENGTH as _MAX_ENV_PROMPT_LENGTH,
+    )
+    from gobby.agents.spawn import (
+        _create_prompt_file,
+        build_cli_command,
+    )
+
+    return build_cli_command, _create_prompt_file, _MAX_ENV_PROMPT_LENGTH
+
+
+class EmbeddedSpawner:
+    """
+    Spawner for embedded mode with PTY.
+
+    Creates a pseudo-terminal that can be attached to a UI component.
+    The master file descriptor can be used to read/write to the process.
+    """
+
+    def spawn(
+        self,
+        command: list[str],
+        cwd: str | Path,
+        env: dict[str, str] | None = None,
+    ) -> EmbeddedPTYResult:
+        """
+        Spawn a process with a PTY for embedded mode.
+
+        Args:
+            command: Command to run
+            cwd: Working directory
+            env: Environment variables to set
+
+        Returns:
+            EmbeddedPTYResult with PTY file descriptors and process info
+        """
+        if not command or len(command) == 0:
+            return EmbeddedPTYResult(
+                success=False,
+                message="Cannot spawn process with empty command",
+                error="Empty command list provided",
+            )
+
+        if platform.system() == "Windows" or pty is None:
+            return EmbeddedPTYResult(
+                success=False,
+                message="Embedded PTY mode not supported on Windows",
+                error="Windows does not support Unix PTY",
+            )
+
+        master_fd: int | None = None
+        slave_fd: int | None = None
+
+        try:
+            # Create pseudo-terminal
+            master_fd, slave_fd = pty.openpty()
+
+            # Merge environment
+            spawn_env = os.environ.copy()
+            if env:
+                spawn_env.update(env)
+
+            # Fork and exec
+            pid = os.fork()
+
+            if pid == 0:
+                # Child process
+                try:
+                    # Close master fd in child - not needed
+                    os.close(master_fd)
+
+                    # Create new session
+                    os.setsid()
+
+                    # Set slave as controlling terminal
+                    os.dup2(slave_fd, 0)  # stdin
+                    os.dup2(slave_fd, 1)  # stdout
+                    os.dup2(slave_fd, 2)  # stderr
+
+                    # Close original slave fd after duplication
+                    os.close(slave_fd)
+
+                    # Change to working directory
+                    os.chdir(cwd)
+
+                    # Execute command
+                    os.execvpe(command[0], command, spawn_env)  # nosec B606 - config
+                except Exception:
+                    # Ensure we exit on any failure
+                    os._exit(1)
+
+                # Should never reach here, but just in case
+                os._exit(1)
+            else:
+                # Parent process - close slave fd (child has its own copy)
+                os.close(slave_fd)
+                slave_fd = None  # Mark as closed
+
+                return EmbeddedPTYResult(
+                    success=True,
+                    message=f"Spawned embedded PTY with PID {pid}",
+                    master_fd=master_fd,
+                    slave_fd=None,  # Closed in parent
+                    pid=pid,
+                )
+
+        except Exception as e:
+            # Clean up file descriptors on any error
+            if master_fd is not None:
+                try:
+                    os.close(master_fd)
+                except OSError:
+                    pass
+            if slave_fd is not None:
+                try:
+                    os.close(slave_fd)
+                except OSError:
+                    pass
+            return EmbeddedPTYResult(
+                success=False,
+                message=f"Failed to spawn embedded PTY: {e}",
+                error=str(e),
+            )
+
+    def spawn_agent(
+        self,
+        cli: str,
+        cwd: str | Path,
+        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,
+    ) -> EmbeddedPTYResult:
+        """
+        Spawn a CLI agent with embedded PTY.
+
+        Args:
+            cli: CLI to run
+            cwd: Working directory
+            session_id: Pre-created child session ID
+            parent_session_id: Parent session ID
+            agent_run_id: Agent run record ID
+            project_id: Project ID
+            workflow_name: Optional workflow to activate
+            agent_depth: Current nesting depth
+            max_agent_depth: Maximum allowed depth
+            prompt: Optional initial prompt
+
+        Returns:
+            EmbeddedPTYResult with PTY info
+        """
+        build_cli_command, _create_prompt_file, max_env_prompt_length = _get_spawn_utils()
+
+        # Build command with prompt as CLI argument and auto-approve for autonomous work
+        command = build_cli_command(
+            cli,
+            prompt=prompt,
+            session_id=session_id,
+            auto_approve=True,  # Subagents need to work autonomously
+            working_directory=str(cwd) if cli == "codex" else None,
+        )
+
+        # Handle prompt for environment variables (backup for hooks/context)
+        prompt_env: str | None = None
+        prompt_file: str | None = None
+
+        if prompt:
+            if len(prompt) <= max_env_prompt_length:
+                prompt_env = prompt
+            else:
+                # Write to temp file with secure permissions
+                prompt_file = _create_prompt_file(prompt, session_id)
+
+        env = get_terminal_env_vars(
+            session_id=session_id,
+            parent_session_id=parent_session_id,
+            agent_run_id=agent_run_id,
+            project_id=project_id,
+            workflow_name=workflow_name,
+            agent_depth=agent_depth,
+            max_agent_depth=max_agent_depth,
+            prompt=prompt_env,
+            prompt_file=prompt_file,
+        )
+
+        return self.spawn(command, cwd, env)