htmlgraph 0.26.5__py3-none-any.whl → 0.26.6__py3-none-any.whl

htmlgraph/orchestration/headless_spawner.py

@@ -1,28 +1,20 @@
-"""Headless AI spawner for multi-AI orchestration."""
+"""Headless AI spawner for multi-AI orchestration.
 
-import json
-import os
-import subprocess
-import sys
-import time
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+This module provides backward compatibility by delegating to modular spawner implementations.
+"""
 
-if TYPE_CHECKING:
-    from htmlgraph.orchestration.live_events import LiveEventPublisher
-    from htmlgraph.sdk import SDK
+from typing import Any
 
+from .spawners import (
+    AIResult,
+    ClaudeSpawner,
+    CodexSpawner,
+    CopilotSpawner,
+    GeminiSpawner,
+)
 
-@dataclass
-class AIResult:
-    """Result from AI CLI execution."""
-
-    success: bool
-    response: str
-    tokens_used: int | None
-    error: str | None
-    raw_output: dict | list | str | None
-    tracked_events: list[dict] | None = None  # Events tracked in HtmlGraph
+# Re-export AIResult for backward compatibility
+__all__ = ["HeadlessSpawner", "AIResult"]
 
 
 class HeadlessSpawner:
@@ -65,396 +57,30 @@ class HeadlessSpawner:
     """
 
     def __init__(self) -> None:
-        """Initialize spawner."""
-        self._live_publisher: LiveEventPublisher | None = None
-
-    def _get_live_publisher(self) -> "LiveEventPublisher | None":
-        """
-        Get LiveEventPublisher instance for real-time WebSocket streaming.
-
-        Returns None if publisher unavailable (optional dependency).
-        """
-        if self._live_publisher is None:
-            try:
-                from htmlgraph.orchestration.live_events import LiveEventPublisher
-
-                self._live_publisher = LiveEventPublisher()
-            except Exception:
-                # Live events are optional
-                pass
-        return self._live_publisher
-
-    def _publish_live_event(
-        self,
-        event_type: str,
-        spawner_type: str,
-        **kwargs: str | int | float | bool | None,
-    ) -> None:
-        """
-        Publish a live event for WebSocket streaming.
-
-        Silently fails if publisher unavailable (optional feature).
-        """
-        publisher = self._get_live_publisher()
-        if publisher is None:
-            return
-
-        parent_event_id = os.getenv("HTMLGRAPH_PARENT_EVENT")
-
-        try:
-            if event_type == "spawner_start":
-                publisher.spawner_start(
-                    spawner_type=spawner_type,
-                    prompt=str(kwargs.get("prompt", "")),
-                    parent_event_id=parent_event_id,
-                    model=str(kwargs.get("model", "")) if kwargs.get("model") else None,
-                )
-            elif event_type == "spawner_phase":
-                progress_val = kwargs.get("progress")
-                publisher.spawner_phase(
-                    spawner_type=spawner_type,
-                    phase=str(kwargs.get("phase", "executing")),
-                    progress=int(progress_val) if progress_val is not None else None,
-                    details=str(kwargs.get("details", ""))
-                    if kwargs.get("details")
-                    else None,
-                    parent_event_id=parent_event_id,
-                )
-            elif event_type == "spawner_complete":
-                duration_val = kwargs.get("duration")
-                tokens_val = kwargs.get("tokens")
-                publisher.spawner_complete(
-                    spawner_type=spawner_type,
-                    success=bool(kwargs.get("success", False)),
-                    duration_seconds=float(duration_val)
-                    if duration_val is not None
-                    else None,
-                    response_preview=str(kwargs.get("response", ""))[:200]
-                    if kwargs.get("response")
-                    else None,
-                    tokens_used=int(tokens_val) if tokens_val is not None else None,
-                    error=str(kwargs.get("error", "")) if kwargs.get("error") else None,
-                    parent_event_id=parent_event_id,
-                )
-            elif event_type == "spawner_tool_use":
-                publisher.spawner_tool_use(
-                    spawner_type=spawner_type,
-                    tool_name=str(kwargs.get("tool_name", "unknown")),
-                    parent_event_id=parent_event_id,
-                )
-            elif event_type == "spawner_message":
-                publisher.spawner_message(
-                    spawner_type=spawner_type,
-                    message=str(kwargs.get("message", "")),
-                    role=str(kwargs.get("role", "assistant")),
-                    parent_event_id=parent_event_id,
-                )
-        except Exception:
-            # Live events should never break spawner execution
-            pass
-
-    def _get_sdk(self) -> "SDK | None":
-        """
-        Get SDK instance for HtmlGraph tracking with parent session support.
-
-        Returns None if SDK unavailable.
-        """
-        try:
-            from htmlgraph.sdk import SDK
-
-            # Read parent session context from environment
-            parent_session = os.getenv("HTMLGRAPH_PARENT_SESSION")
-            parent_agent = os.getenv("HTMLGRAPH_PARENT_AGENT")
-
-            # Create SDK with parent session context
-            sdk = SDK(
-                agent=f"spawner-{parent_agent}" if parent_agent else "spawner",
-                parent_session=parent_session,  # Pass parent session
-            )
-
-            return sdk
-
-        except Exception:
-            # SDK unavailable or not properly initialized (optional dependency)
-            # This happens in test contexts without active sessions
-            # Don't log error to avoid noise in tests
-            return None
-
-    def _parse_and_track_gemini_events(
-        self, jsonl_output: str, sdk: "SDK"
-    ) -> list[dict]:
-        """
-        Parse Gemini stream-json events and track in HtmlGraph.
-
-        Args:
-            jsonl_output: JSONL output from Gemini CLI
-            sdk: HtmlGraph SDK instance for tracking
-
-        Returns:
-            Parsed events list
-        """
-        events = []
-
-        # Get parent context for metadata
-        parent_activity = os.getenv("HTMLGRAPH_PARENT_ACTIVITY")
-        nesting_depth_str = os.getenv("HTMLGRAPH_NESTING_DEPTH", "0")
-        nesting_depth = int(nesting_depth_str) if nesting_depth_str.isdigit() else 0
-
-        for line in jsonl_output.splitlines():
-            if not line.strip():
-                continue
-
-            try:
-                event = json.loads(line)
-                events.append(event)
-
-                # Track based on event type
-                event_type = event.get("type")
-
-                try:
-                    if event_type == "tool_use":
-                        tool_name = event.get("tool_name", "unknown_tool")
-                        parameters = event.get("parameters", {})
-                        payload = {
-                            "tool_name": tool_name,
-                            "parameters": parameters,
-                        }
-                        if parent_activity:
-                            payload["parent_activity"] = parent_activity
-                        if nesting_depth > 0:
-                            payload["nesting_depth"] = nesting_depth
-                        sdk.track_activity(
-                            tool="gemini_tool_call",
-                            summary=f"Gemini called {tool_name}",
-                            payload=payload,
-                        )
-
-                    elif event_type == "tool_result":
-                        status = event.get("status", "unknown")
-                        success = status == "success"
-                        tool_id = event.get("tool_id", "unknown")
-                        payload = {"tool_id": tool_id, "status": status}
-                        if parent_activity:
-                            payload["parent_activity"] = parent_activity
-                        if nesting_depth > 0:
-                            payload["nesting_depth"] = nesting_depth
-                        sdk.track_activity(
-                            tool="gemini_tool_result",
-                            summary=f"Gemini tool result: {status}",
-                            success=success,
-                            payload=payload,
-                        )
-
-                    elif event_type == "message":
-                        role = event.get("role")
-                        if role == "assistant":
-                            content = event.get("content", "")
-                            # Truncate for summary
-                            summary = (
-                                content[:100] + "..." if len(content) > 100 else content
-                            )
-                            payload = {"role": role, "content_length": len(content)}
-                            if parent_activity:
-                                payload["parent_activity"] = parent_activity
-                            if nesting_depth > 0:
-                                payload["nesting_depth"] = nesting_depth
-                            sdk.track_activity(
-                                tool="gemini_message",
-                                summary=f"Gemini: {summary}",
-                                payload=payload,
-                            )
-
-                    elif event_type == "result":
-                        stats = event.get("stats", {})
-                        payload = {"stats": stats}
-                        if parent_activity:
-                            payload["parent_activity"] = parent_activity
-                        if nesting_depth > 0:
-                            payload["nesting_depth"] = nesting_depth
-                        sdk.track_activity(
-                            tool="gemini_completion",
-                            summary="Gemini task completed",
-                            payload=payload,
-                        )
-                except Exception:
-                    # Tracking failure should not break parsing
-                    pass
+        """Initialize spawner with modular implementations."""
+        self._gemini_spawner = GeminiSpawner()
+        self._codex_spawner = CodexSpawner()
+        self._copilot_spawner = CopilotSpawner()
+        self._claude_spawner = ClaudeSpawner()
 
-            except json.JSONDecodeError:
-                # Skip malformed lines
-                continue
+    # Expose internal methods for backward compatibility with tests
+    def _parse_and_track_gemini_events(self, jsonl_output: str, sdk: Any) -> list[dict]:
+        """Parse and track Gemini events (delegates to GeminiSpawner)."""
+        return self._gemini_spawner._parse_and_track_events(jsonl_output, sdk)
 
-        return events
-
-    def _parse_and_track_codex_events(
-        self, jsonl_output: str, sdk: "SDK"
-    ) -> list[dict]:
-        """
-        Parse Codex JSONL events and track in HtmlGraph.
-
-        Args:
-            jsonl_output: JSONL output from Codex CLI
-            sdk: HtmlGraph SDK instance for tracking
-
-        Returns:
-            Parsed events list
-        """
-        events = []
-        parse_errors = []
-
-        # Get parent context for metadata
-        parent_activity = os.getenv("HTMLGRAPH_PARENT_ACTIVITY")
-        nesting_depth_str = os.getenv("HTMLGRAPH_NESTING_DEPTH", "0")
-        nesting_depth = int(nesting_depth_str) if nesting_depth_str.isdigit() else 0
-
-        for line_num, line in enumerate(jsonl_output.splitlines(), start=1):
-            if not line.strip():
-                continue
-
-            try:
-                event = json.loads(line)
-                events.append(event)
-
-                event_type = event.get("type")
-
-                try:
-                    # Track item.started events
-                    if event_type == "item.started":
-                        item = event.get("item", {})
-                        item_type = item.get("type")
-
-                        if item_type == "command_execution":
-                            command = item.get("command", "")
-                            payload = {"command": command}
-                            if parent_activity:
-                                payload["parent_activity"] = parent_activity
-                            if nesting_depth > 0:
-                                payload["nesting_depth"] = nesting_depth
-                            sdk.track_activity(
-                                tool="codex_command",
-                                summary=f"Codex executing: {command[:80]}",
-                                payload=payload,
-                            )
-
-                    # Track item.completed events
-                    elif event_type == "item.completed":
-                        item = event.get("item", {})
-                        item_type = item.get("type")
-
-                        if item_type == "file_change":
-                            path = item.get("path", "unknown")
-                            payload = {"path": path}
-                            if parent_activity:
-                                payload["parent_activity"] = parent_activity
-                            if nesting_depth > 0:
-                                payload["nesting_depth"] = nesting_depth
-                            sdk.track_activity(
-                                tool="codex_file_change",
-                                summary=f"Codex modified: {path}",
-                                file_paths=[path],
-                                payload=payload,
-                            )
-
-                        elif item_type == "agent_message":
-                            text = item.get("text", "")
-                            summary = text[:100] + "..." if len(text) > 100 else text
-                            payload = {"text_length": len(text)}
-                            if parent_activity:
-                                payload["parent_activity"] = parent_activity
-                            if nesting_depth > 0:
-                                payload["nesting_depth"] = nesting_depth
-                            sdk.track_activity(
-                                tool="codex_message",
-                                summary=f"Codex: {summary}",
-                                payload=payload,
-                            )
-
-                    # Track turn.completed for token usage
-                    elif event_type == "turn.completed":
-                        usage = event.get("usage", {})
-                        total_tokens = sum(usage.values())
-                        payload = {"usage": usage}
-                        if parent_activity:
-                            payload["parent_activity"] = parent_activity
-                        if nesting_depth > 0:
-                            payload["nesting_depth"] = nesting_depth
-                        sdk.track_activity(
-                            tool="codex_completion",
-                            summary=f"Codex turn completed ({total_tokens} tokens)",
-                            payload=payload,
-                        )
-                except Exception:
-                    # Tracking failure should not break parsing
-                    pass
-
-            except json.JSONDecodeError as e:
-                parse_errors.append(
-                    {
-                        "line_number": line_num,
-                        "error": str(e),
-                        "content": line[:100],
-                    }
-                )
-                continue
-
-        return events
+    def _parse_and_track_codex_events(self, jsonl_output: str, sdk: Any) -> list[dict]:
+        """Parse and track Codex events (delegates to CodexSpawner)."""
+        return self._codex_spawner._parse_and_track_events(jsonl_output, sdk)
 
     def _parse_and_track_copilot_events(
-        self, prompt: str, response: str, sdk: "SDK"
+        self, prompt: str, response: str, sdk: Any
     ) -> list[dict]:
-        """
-        Track Copilot execution (start and result only).
-
-        Args:
-            prompt: Original prompt
-            response: Response from Copilot
-            sdk: HtmlGraph SDK instance for tracking
-
-        Returns:
-            Synthetic events list for consistency
-        """
-        events = []
-
-        # Get parent context for metadata
-        parent_activity = os.getenv("HTMLGRAPH_PARENT_ACTIVITY")
-        nesting_depth_str = os.getenv("HTMLGRAPH_NESTING_DEPTH", "0")
-        nesting_depth = int(nesting_depth_str) if nesting_depth_str.isdigit() else 0
+        """Parse and track Copilot events (delegates to CopilotSpawner)."""
+        return self._copilot_spawner._parse_and_track_events(prompt, response, sdk)
 
-        try:
-            # Track start
-            start_event = {"type": "copilot_start", "prompt": prompt[:100]}
-            events.append(start_event)
-            payload: dict[str, str | int] = {"prompt_length": len(prompt)}
-            if parent_activity:
-                payload["parent_activity"] = parent_activity
-            if nesting_depth > 0:
-                payload["nesting_depth"] = nesting_depth
-            sdk.track_activity(
-                tool="copilot_start",
-                summary=f"Copilot started with prompt: {prompt[:80]}",
-                payload=payload,
-            )
-        except Exception:
-            pass
-
-        try:
-            # Track result
-            result_event = {"type": "copilot_result", "response": response[:100]}
-            events.append(result_event)
-            payload_result: dict[str, str | int] = {"response_length": len(response)}
-            if parent_activity:
-                payload_result["parent_activity"] = parent_activity
-            if nesting_depth > 0:
-                payload_result["nesting_depth"] = nesting_depth
-            sdk.track_activity(
-                tool="copilot_result",
-                summary=f"Copilot completed: {response[:80]}",
-                payload=payload_result,
-            )
-        except Exception:
-            pass
-
-        return events
+    def _get_sdk(self) -> Any:
+        """Get SDK instance (delegates to base spawner implementation)."""
+        return self._gemini_spawner._get_sdk()
 
     def spawn_gemini(
         self,
@@ -473,7 +99,8 @@ class HeadlessSpawner:
         Args:
             prompt: Task description for Gemini
             output_format: "json" or "stream-json" (enables real-time tracking)
-            model: Model selection (e.g., "gemini-2.0-flash"). Default: None
+            model: Model selection. Default: None (recommended - lets CLI choose
+                   thinking-compatible models). Older models may fail.
             include_directories: Directories to include for context. Default: None
             track_in_htmlgraph: Enable HtmlGraph activity tracking. Default: True
             timeout: Max seconds to wait
@@ -483,317 +110,16 @@ class HeadlessSpawner:
         Returns:
             AIResult with response, error, and tracked events if tracking enabled
         """
-        # Initialize tracking if enabled
-        sdk: SDK | None = None
-        tracked_events: list[dict] = []
-        if track_in_htmlgraph:
-            sdk = self._get_sdk()
-
-        # Publish live event: spawner starting
-        self._publish_live_event(
-            "spawner_start",
-            "gemini",
+        return self._gemini_spawner.spawn(
             prompt=prompt,
+            output_format=output_format,
             model=model,
+            include_directories=include_directories,
+            track_in_htmlgraph=track_in_htmlgraph,
+            timeout=timeout,
+            tracker=tracker,
+            parent_event_id=parent_event_id,
         )
-        start_time = time.time()
-
-        try:
-            # Build command based on tested pattern from spike spk-4029eef3
-            cmd = ["gemini", "-p", prompt, "--output-format", output_format]
-
-            # Add model option if specified
-            if model:
-                cmd.extend(["-m", model])
-
-            # Add include directories if specified
-            if include_directories:
-                for directory in include_directories:
-                    cmd.extend(["--include-directories", directory])
-
-            # CRITICAL: Add --yolo for headless mode (auto-approve all tools)
-            cmd.append("--yolo")
-
-            # Track spawner start if SDK available
-            if sdk:
-                try:
-                    sdk.track_activity(
-                        tool="gemini_spawn_start",
-                        summary=f"Spawning Gemini: {prompt[:80]}",
-                        payload={"prompt_length": len(prompt), "model": model},
-                    )
-                except Exception:
-                    # Tracking failure should not break execution
-                    pass
-
-            # Publish live event: executing
-            self._publish_live_event(
-                "spawner_phase",
-                "gemini",
-                phase="executing",
-                details="Running Gemini CLI",
-            )
-
-            # Record subprocess invocation if tracker is available
-            subprocess_event_id = None
-            print(
-                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                file=sys.stderr,
-            )
-            if tracker and parent_event_id:
-                print(
-                    "DEBUG: Recording subprocess invocation for Gemini...",
-                    file=sys.stderr,
-                )
-                try:
-                    subprocess_event = tracker.record_tool_call(
-                        tool_name="subprocess.gemini",
-                        tool_input={"cmd": cmd},
-                        phase_event_id=parent_event_id,
-                        spawned_agent="gemini-2.0-flash",
-                    )
-                    if subprocess_event:
-                        subprocess_event_id = subprocess_event.get("event_id")
-                        print(
-                            f"DEBUG: Subprocess event created for Gemini: {subprocess_event_id}",
-                            file=sys.stderr,
-                        )
-                    else:
-                        print("DEBUG: subprocess_event was None", file=sys.stderr)
-                except Exception as e:
-                    # Tracking failure should not break execution
-                    print(
-                        f"DEBUG: Exception recording Gemini subprocess: {e}",
-                        file=sys.stderr,
-                    )
-                    pass
-            else:
-                print(
-                    f"DEBUG: Skipping Gemini subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
-                )
-
-            # Execute with timeout and stderr redirection
-            # Note: Cannot use capture_output with stderr parameter
-            result = subprocess.run(
-                cmd,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.DEVNULL,  # Redirect stderr to avoid polluting JSON
-                text=True,
-                timeout=timeout,
-            )
-
-            # Complete subprocess invocation tracking
-            if tracker and subprocess_event_id:
-                try:
-                    tracker.complete_tool_call(
-                        event_id=subprocess_event_id,
-                        output_summary=result.stdout[:500] if result.stdout else "",
-                        success=result.returncode == 0,
-                    )
-                except Exception:
-                    # Tracking failure should not break execution
-                    pass
-
-            # Publish live event: processing response
-            self._publish_live_event(
-                "spawner_phase",
-                "gemini",
-                phase="processing",
-                details="Parsing Gemini response",
-            )
-
-            # Check for command execution errors
-            if result.returncode != 0:
-                duration = time.time() - start_time
-                self._publish_live_event(
-                    "spawner_complete",
-                    "gemini",
-                    success=False,
-                    duration=duration,
-                    error=f"CLI failed with exit code {result.returncode}",
-                )
-                return AIResult(
-                    success=False,
-                    response="",
-                    tokens_used=None,
-                    error=f"Gemini CLI failed with exit code {result.returncode}",
-                    raw_output=None,
-                    tracked_events=tracked_events,
-                )
-
-            # Handle stream-json format with real-time tracking
-            if output_format == "stream-json" and sdk:
-                try:
-                    tracked_events = self._parse_and_track_gemini_events(
-                        result.stdout, sdk
-                    )
-                    # Only use stream-json parsing if we got valid events
-                    if tracked_events:
-                        # For stream-json, we need to extract response differently
-                        # Collect all assistant message content, then check result
-                        response_text = ""
-                        for event in tracked_events:
-                            if event.get("type") == "message":
-                                # Only collect assistant messages
-                                if event.get("role") == "assistant":
-                                    content = event.get("content", "")
-                                    if content:
-                                        response_text += content
-                            elif event.get("type") == "result":
-                                # Result event may have response field (override if present)
-                                if "response" in event and event["response"]:
-                                    response_text = event["response"]
-                                # Don't break - we've already collected messages
-
-                        # Token usage from stats in result event
-                        tokens = None
-                        for event in tracked_events:
-                            if event.get("type") == "result":
-                                stats = event.get("stats", {})
-                                if stats and "models" in stats:
-                                    total_tokens = 0
-                                    for model_stats in stats["models"].values():
-                                        model_tokens = model_stats.get(
-                                            "tokens", {}
-                                        ).get("total", 0)
-                                        total_tokens += model_tokens
-                                    tokens = total_tokens if total_tokens > 0 else None
-                                break
-
-                        # Publish live event: complete
-                        duration = time.time() - start_time
-                        self._publish_live_event(
-                            "spawner_complete",
-                            "gemini",
-                            success=True,
-                            duration=duration,
-                            response=response_text,
-                            tokens=tokens,
-                        )
-                        return AIResult(
-                            success=True,
-                            response=response_text,
-                            tokens_used=tokens,
-                            error=None,
-                            raw_output={"events": tracked_events},
-                            tracked_events=tracked_events,
-                        )
-
-                except Exception:
-                    # Fall back to regular JSON parsing if tracking fails
-                    pass
-
-            # Parse JSON response (for json format or fallback)
-            try:
-                output = json.loads(result.stdout)
-            except json.JSONDecodeError as e:
-                duration = time.time() - start_time
-                self._publish_live_event(
-                    "spawner_complete",
-                    "gemini",
-                    success=False,
-                    duration=duration,
-                    error=f"Failed to parse JSON: {e}",
-                )
-                return AIResult(
-                    success=False,
-                    response="",
-                    tokens_used=None,
-                    error=f"Failed to parse JSON output: {e}",
-                    raw_output={"stdout": result.stdout},
-                    tracked_events=tracked_events,
-                )
-
-            # Extract response and token usage from parsed output
-            # Response is at top level in JSON output
-            response_text = output.get("response", "")
-
-            # Token usage is in stats.models (sum across all models)
-            tokens = None
-            stats = output.get("stats", {})
-            if stats and "models" in stats:
-                total_tokens = 0
-                for model_stats in stats["models"].values():
-                    model_tokens = model_stats.get("tokens", {}).get("total", 0)
-                    total_tokens += model_tokens
-                tokens = total_tokens if total_tokens > 0 else None
-
-            # Publish live event: complete
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "gemini",
-                success=True,
-                duration=duration,
-                response=response_text,
-                tokens=tokens,
-            )
-            return AIResult(
-                success=True,
-                response=response_text,
-                tokens_used=tokens,
-                error=None,
-                raw_output=output,
-                tracked_events=tracked_events,
-            )
-
-        except subprocess.TimeoutExpired as e:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "gemini",
-                success=False,
-                duration=duration,
-                error=f"Timed out after {timeout} seconds",
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Gemini CLI timed out after {timeout} seconds",
-                raw_output={
-                    "partial_stdout": e.stdout.decode() if e.stdout else None,
-                    "partial_stderr": e.stderr.decode() if e.stderr else None,
-                }
-                if e.stdout or e.stderr
-                else None,
-                tracked_events=tracked_events,
-            )
-        except FileNotFoundError:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "gemini",
-                success=False,
-                duration=duration,
-                error="CLI not found",
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error="Gemini CLI not found. Ensure 'gemini' is installed and in PATH.",
-                raw_output=None,
-                tracked_events=tracked_events,
-            )
-        except Exception as e:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "gemini",
-                success=False,
-                duration=duration,
-                error=str(e),
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Unexpected error: {type(e).__name__}: {e}",
-                raw_output=None,
-                tracked_events=tracked_events,
-            )
 
     def spawn_codex(
         self,
@@ -838,305 +164,24 @@ class HeadlessSpawner:
         Returns:
             AIResult with response, error, and tracked events if tracking enabled
         """
-        # Initialize tracking if enabled
-        sdk: SDK | None = None
-        tracked_events: list[dict] = []
-        if track_in_htmlgraph and output_json:
-            sdk = self._get_sdk()
-
-        # Publish live event: spawner starting
-        self._publish_live_event(
-            "spawner_start",
-            "codex",
+        return self._codex_spawner.spawn(
             prompt=prompt,
+            output_json=output_json,
             model=model,
+            sandbox=sandbox,
+            full_auto=full_auto,
+            images=images,
+            output_last_message=output_last_message,
+            output_schema=output_schema,
+            skip_git_check=skip_git_check,
+            working_directory=working_directory,
+            use_oss=use_oss,
+            bypass_approvals=bypass_approvals,
+            track_in_htmlgraph=track_in_htmlgraph,
+            timeout=timeout,
+            tracker=tracker,
+            parent_event_id=parent_event_id,
         )
-        start_time = time.time()
-
-        cmd = ["codex", "exec"]
-
-        if output_json:
-            cmd.append("--json")
-
-        # Add model if specified
-        if model:
-            cmd.extend(["--model", model])
-
-        # Add sandbox mode if specified
-        if sandbox:
-            cmd.extend(["--sandbox", sandbox])
-
-        # Add full auto flag
-        if full_auto:
-            cmd.append("--full-auto")
-
-        # Add images
-        if images:
-            for image in images:
-                cmd.extend(["--image", image])
-
-        # Add output last message file if specified
-        if output_last_message:
-            cmd.extend(["--output-last-message", output_last_message])
-
-        # Add output schema if specified
-        if output_schema:
-            cmd.extend(["--output-schema", output_schema])
-
-        # Add skip git check flag
-        if skip_git_check:
-            cmd.append("--skip-git-repo-check")
-
-        # Add working directory if specified
-        if working_directory:
-            cmd.extend(["--cd", working_directory])
-
-        # Add OSS flag
-        if use_oss:
-            cmd.append("--oss")
-
-        # Add bypass approvals flag
-        if bypass_approvals:
-            cmd.append("--dangerously-bypass-approvals-and-sandbox")
-
-        # Add prompt as final argument
-        cmd.append(prompt)
-
-        # Track spawner start if SDK available
-        if sdk:
-            try:
-                sdk.track_activity(
-                    tool="codex_spawn_start",
-                    summary=f"Spawning Codex: {prompt[:80]}",
-                    payload={
-                        "prompt_length": len(prompt),
-                        "model": model,
-                        "sandbox": sandbox,
-                    },
-                )
-            except Exception:
-                # Tracking failure should not break execution
-                pass
-
-        try:
-            # Publish live event: executing
-            self._publish_live_event(
-                "spawner_phase",
-                "codex",
-                phase="executing",
-                details="Running Codex CLI",
-            )
-
-            # Record subprocess invocation if tracker is available
-            subprocess_event_id = None
-            print(
-                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                file=sys.stderr,
-            )
-            if tracker and parent_event_id:
-                print(
-                    "DEBUG: Recording subprocess invocation for Codex...",
-                    file=sys.stderr,
-                )
-                try:
-                    subprocess_event = tracker.record_tool_call(
-                        tool_name="subprocess.codex",
-                        tool_input={"cmd": cmd},
-                        phase_event_id=parent_event_id,
-                        spawned_agent="gpt-4",
-                    )
-                    if subprocess_event:
-                        subprocess_event_id = subprocess_event.get("event_id")
-                        print(
-                            f"DEBUG: Subprocess event created for Codex: {subprocess_event_id}",
-                            file=sys.stderr,
-                        )
-                    else:
-                        print("DEBUG: subprocess_event was None", file=sys.stderr)
-                except Exception as e:
-                    # Tracking failure should not break execution
-                    print(
-                        f"DEBUG: Exception recording Codex subprocess: {e}",
-                        file=sys.stderr,
-                    )
-                    pass
-            else:
-                print(
-                    f"DEBUG: Skipping Codex subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
-                )
-
-            result = subprocess.run(
-                cmd,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.DEVNULL,
-                text=True,
-                timeout=timeout,
-            )
-
-            # Complete subprocess invocation tracking
-            if tracker and subprocess_event_id:
-                try:
-                    tracker.complete_tool_call(
-                        event_id=subprocess_event_id,
-                        output_summary=result.stdout[:500] if result.stdout else "",
-                        success=result.returncode == 0,
-                    )
-                except Exception:
-                    # Tracking failure should not break execution
-                    pass
-
-            # Publish live event: processing
-            self._publish_live_event(
-                "spawner_phase",
-                "codex",
-                phase="processing",
-                details="Parsing Codex response",
-            )
-
-            if not output_json:
-                # Plain text mode - return as-is
-                duration = time.time() - start_time
-                success = result.returncode == 0
-                self._publish_live_event(
-                    "spawner_complete",
-                    "codex",
-                    success=success,
-                    duration=duration,
-                    response=result.stdout.strip()[:200] if success else None,
-                    error="Command failed" if not success else None,
-                )
-                return AIResult(
-                    success=success,
-                    response=result.stdout.strip(),
-                    tokens_used=None,
-                    error=None if success else "Command failed",
-                    raw_output=result.stdout,
-                    tracked_events=tracked_events,
-                )
-
-            # Parse JSONL output
-            events = []
-            parse_errors = []
-
-            # Use tracking parser if SDK is available
-            if sdk:
-                tracked_events = self._parse_and_track_codex_events(result.stdout, sdk)
-                events = tracked_events
-            else:
-                # Fallback to regular parsing without tracking
-                for line_num, line in enumerate(result.stdout.splitlines(), start=1):
-                    if line.strip():
-                        try:
-                            events.append(json.loads(line))
-                        except json.JSONDecodeError as e:
-                            parse_errors.append(
-                                {
-                                    "line_number": line_num,
-                                    "error": str(e),
-                                    "content": line[
-                                        :100
-                                    ],  # First 100 chars for debugging
-                                }
-                            )
-                            continue
-
-            # Extract agent message
-            response = None
-            for event in events:
-                if event.get("type") == "item.completed":
-                    item = event.get("item", {})
-                    if item.get("type") == "agent_message":
-                        response = item.get("text")
-
-            # Extract token usage from turn.completed event
-            tokens = None
-            for event in events:
-                if event.get("type") == "turn.completed":
-                    usage = event.get("usage", {})
-                    # Sum all token types
-                    tokens = sum(usage.values())
-
-            # Publish live event: complete
-            duration = time.time() - start_time
-            success = result.returncode == 0
-            self._publish_live_event(
-                "spawner_complete",
-                "codex",
-                success=success,
-                duration=duration,
-                response=response[:200] if response else None,
-                tokens=tokens,
-                error="Command failed" if not success else None,
-            )
-            return AIResult(
-                success=success,
-                response=response or "",
-                tokens_used=tokens,
-                error=None if success else "Command failed",
-                raw_output={
-                    "events": events,
-                    "parse_errors": parse_errors if parse_errors else None,
-                },
-                tracked_events=tracked_events,
-            )
-
-        except FileNotFoundError:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "codex",
-                success=False,
-                duration=duration,
-                error="CLI not found",
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error="Codex CLI not found. Install from: https://github.com/openai/codex",
-                raw_output=None,
-                tracked_events=tracked_events,
-            )
-        except subprocess.TimeoutExpired as e:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "codex",
-                success=False,
-                duration=duration,
-                error=f"Timed out after {timeout} seconds",
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Timed out after {timeout} seconds",
-                raw_output={
-                    "partial_stdout": e.stdout.decode() if e.stdout else None,
-                    "partial_stderr": e.stderr.decode() if e.stderr else None,
-                }
-                if e.stdout or e.stderr
-                else None,
-                tracked_events=tracked_events,
-            )
-        except Exception as e:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "codex",
-                success=False,
-                duration=duration,
-                error=str(e),
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Unexpected error: {type(e).__name__}: {e}",
-                raw_output=None,
-                tracked_events=tracked_events,
-            )
 
     def spawn_copilot(
         self,
@@ -1165,229 +210,16 @@ class HeadlessSpawner:
         Returns:
             AIResult with response, error, and tracked events if tracking enabled
         """
-        # Initialize tracking if enabled
-        sdk = None
-        tracked_events = []
-        if track_in_htmlgraph:
-            sdk = self._get_sdk()
-
-        # Publish live event: spawner starting
-        self._publish_live_event(
-            "spawner_start",
-            "copilot",
+        return self._copilot_spawner.spawn(
             prompt=prompt,
+            allow_tools=allow_tools,
+            allow_all_tools=allow_all_tools,
+            deny_tools=deny_tools,
+            track_in_htmlgraph=track_in_htmlgraph,
+            timeout=timeout,
+            tracker=tracker,
+            parent_event_id=parent_event_id,
         )
-        start_time = time.time()
-
-        cmd = ["copilot", "-p", prompt]
-
-        # Add allow all tools flag
-        if allow_all_tools:
-            cmd.append("--allow-all-tools")
-
-        # Add tool permissions
-        if allow_tools:
-            for tool in allow_tools:
-                cmd.extend(["--allow-tool", tool])
-
-        # Add denied tools
-        if deny_tools:
-            for tool in deny_tools:
-                cmd.extend(["--deny-tool", tool])
-
-        # Track spawner start if SDK available
-        if sdk:
-            try:
-                sdk.track_activity(
-                    tool="copilot_spawn_start",
-                    summary=f"Spawning Copilot: {prompt[:80]}",
-                    payload={"prompt_length": len(prompt)},
-                )
-            except Exception:
-                # Tracking failure should not break execution
-                pass
-
-        try:
-            # Publish live event: executing
-            self._publish_live_event(
-                "spawner_phase",
-                "copilot",
-                phase="executing",
-                details="Running Copilot CLI",
-            )
-
-            # Record subprocess invocation if tracker is available
-            subprocess_event_id = None
-            print(
-                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                file=sys.stderr,
-            )
-            if tracker and parent_event_id:
-                print(
-                    "DEBUG: Recording subprocess invocation for Copilot...",
-                    file=sys.stderr,
-                )
-                try:
-                    subprocess_event = tracker.record_tool_call(
-                        tool_name="subprocess.copilot",
-                        tool_input={"cmd": cmd},
-                        phase_event_id=parent_event_id,
-                        spawned_agent="github-copilot",
-                    )
-                    if subprocess_event:
-                        subprocess_event_id = subprocess_event.get("event_id")
-                        print(
-                            f"DEBUG: Subprocess event created for Copilot: {subprocess_event_id}",
-                            file=sys.stderr,
-                        )
-                    else:
-                        print("DEBUG: subprocess_event was None", file=sys.stderr)
-                except Exception as e:
-                    # Tracking failure should not break execution
-                    print(
-                        f"DEBUG: Exception recording Copilot subprocess: {e}",
-                        file=sys.stderr,
-                    )
-                    pass
-            else:
-                print(
-                    f"DEBUG: Skipping Copilot subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
-                )
-
-            result = subprocess.run(
-                cmd,
-                capture_output=True,
-                text=True,
-                timeout=timeout,
-            )
-
-            # Complete subprocess invocation tracking
-            if tracker and subprocess_event_id:
-                try:
-                    tracker.complete_tool_call(
-                        event_id=subprocess_event_id,
-                        output_summary=result.stdout[:500] if result.stdout else "",
-                        success=result.returncode == 0,
-                    )
-                except Exception:
-                    # Tracking failure should not break execution
-                    pass
-
-            # Publish live event: processing
-            self._publish_live_event(
-                "spawner_phase",
-                "copilot",
-                phase="processing",
-                details="Parsing Copilot response",
-            )
-
-            # Parse output: response is before stats block
-            lines = result.stdout.split("\n")
-
-            # Find where stats start (look for "Total usage est:" or "Usage by model")
-            stats_start = len(lines)
-            for i, line in enumerate(lines):
-                if "Total usage est" in line or "Usage by model" in line:
-                    stats_start = i
-                    break
-
-            # Response is everything before stats
-            response = "\n".join(lines[:stats_start]).strip()
-
-            # Try to extract token count from stats
-            tokens = None
-            for line in lines[stats_start:]:
-                # Look for token counts like "25.8k input, 5 output"
-                if "input" in line and "output" in line:
-                    # Simple extraction: just note we found stats
-                    # TODO: More sophisticated parsing if needed
-                    tokens = 0  # Placeholder
-                    break
-
-            # Track Copilot execution if SDK available
-            if sdk:
-                tracked_events = self._parse_and_track_copilot_events(
-                    prompt, response, sdk
-                )
-
-            # Publish live event: complete
-            duration = time.time() - start_time
-            success = result.returncode == 0
-            self._publish_live_event(
-                "spawner_complete",
-                "copilot",
-                success=success,
-                duration=duration,
-                response=response[:200] if response else None,
-                tokens=tokens,
-                error=result.stderr if not success else None,
-            )
-            return AIResult(
-                success=success,
-                response=response,
-                tokens_used=tokens,
-                error=None if success else result.stderr,
-                raw_output=result.stdout,
-                tracked_events=tracked_events,
-            )
-
-        except FileNotFoundError:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "copilot",
-                success=False,
-                duration=duration,
-                error="CLI not found",
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error="Copilot CLI not found. Install from: https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line",
-                raw_output=None,
-                tracked_events=tracked_events,
-            )
-        except subprocess.TimeoutExpired as e:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "copilot",
-                success=False,
-                duration=duration,
-                error=f"Timed out after {timeout} seconds",
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Timed out after {timeout} seconds",
-                raw_output={
-                    "partial_stdout": e.stdout.decode() if e.stdout else None,
-                    "partial_stderr": e.stderr.decode() if e.stderr else None,
-                }
-                if e.stdout or e.stderr
-                else None,
-                tracked_events=tracked_events,
-            )
-        except Exception as e:
-            duration = time.time() - start_time
-            self._publish_live_event(
-                "spawner_complete",
-                "copilot",
-                success=False,
-                duration=duration,
-                error=str(e),
-            )
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Unexpected error: {type(e).__name__}: {e}",
-                raw_output=None,
-                tracked_events=tracked_events,
-            )
 
     def spawn_claude(
         self,
@@ -1434,104 +266,12 @@ class HeadlessSpawner:
             ...     print(result.response)  # "4"
             ...     print(f"Cost: ${result.raw_output['total_cost_usd']}")
         """
-        cmd = ["claude", "-p"]
-
-        if output_format != "text":
-            cmd.extend(["--output-format", output_format])
-
-        if permission_mode:
-            cmd.extend(["--permission-mode", permission_mode])
-
-        # Add resume flag if specified
-        if resume:
-            cmd.extend(["--resume", resume])
-
-        # Add verbose flag
-        if verbose:
-            cmd.append("--verbose")
-
-        # Add extra args
-        if extra_args:
-            cmd.extend(extra_args)
-
-        # Use -- separator to ensure prompt isn't consumed by variadic args
-        cmd.append("--")
-        cmd.append(prompt)
-
-        try:
-            result = subprocess.run(
-                cmd,
-                capture_output=True,
-                text=True,
-                timeout=timeout,
-            )
-
-            if output_format == "json":
-                # Parse JSON output
-                try:
-                    output = json.loads(result.stdout)
-                except json.JSONDecodeError as e:
-                    return AIResult(
-                        success=False,
-                        response="",
-                        tokens_used=None,
-                        error=f"Failed to parse JSON output: {e}",
-                        raw_output=result.stdout,
-                    )
-
-                # Extract result and metadata
-                usage = output.get("usage", {})
-                tokens = (
-                    usage.get("input_tokens", 0)
-                    + usage.get("cache_creation_input_tokens", 0)
-                    + usage.get("cache_read_input_tokens", 0)
-                    + usage.get("output_tokens", 0)
-                )
-
-                return AIResult(
-                    success=output.get("type") == "result"
-                    and not output.get("is_error"),
-                    response=output.get("result", ""),
-                    tokens_used=tokens,
-                    error=output.get("error") if output.get("is_error") else None,
-                    raw_output=output,
-                )
-            else:
-                # Plain text output
-                return AIResult(
-                    success=result.returncode == 0,
-                    response=result.stdout.strip(),
-                    tokens_used=None,
-                    error=None if result.returncode == 0 else result.stderr,
-                    raw_output=result.stdout,
-                )
-
-        except FileNotFoundError:
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error="Claude CLI not found. Install Claude Code from: https://claude.com/claude-code",
-                raw_output=None,
-            )
-        except subprocess.TimeoutExpired as e:
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Timed out after {timeout} seconds",
-                raw_output={
-                    "partial_stdout": e.stdout.decode() if e.stdout else None,
-                    "partial_stderr": e.stderr.decode() if e.stderr else None,
-                }
-                if e.stdout or e.stderr
-                else None,
-            )
-        except Exception as e:
-            return AIResult(
-                success=False,
-                response="",
-                tokens_used=None,
-                error=f"Unexpected error: {type(e).__name__}: {e}",
-                raw_output=None,
-            )
+        return self._claude_spawner.spawn(
+            prompt=prompt,
+            output_format=output_format,
+            permission_mode=permission_mode,
+            resume=resume,
+            verbose=verbose,
+            timeout=timeout,
+            extra_args=extra_args,
+        )