htmlgraph 0.20.1__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/orchestration/claude_launcher.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+"""Claude Code launcher with multiple integration modes.
+
+Coordinates launching Claude Code with various HtmlGraph integration options.
+"""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from htmlgraph.orchestration.command_builder import ClaudeCommandBuilder
+from htmlgraph.orchestration.plugin_manager import PluginManager
+from htmlgraph.orchestration.prompts import get_orchestrator_prompt
+from htmlgraph.orchestration.subprocess_runner import SubprocessRunner
+
+logger = logging.getLogger(__name__)
+
+
+class ClaudeLauncher:
+    """Launch Claude Code with various HtmlGraph integration modes.
+
+    Supports four launch scenarios:
+    1. --init: Orchestrator mode with plugin installation
+    2. --continue: Resume last session with orchestrator rules
+    3. --dev: Development mode with local plugin
+    4. default: Minimal orchestrator rules
+    """
+
+    def __init__(self, args: argparse.Namespace) -> None:
+        """Initialize launcher with parsed arguments.
+
+        Args:
+            args: Parsed command-line arguments
+        """
+        self.args = args
+        self.interactive = not (args.quiet or args.format == "json")
+
+    def launch(self) -> None:
+        """Main entry point - routes to appropriate scenario.
+
+        Raises:
+            SystemExit: On error during launch
+        """
+        try:
+            if self.args.init:
+                self._launch_orchestrator_mode()
+            elif self.args.continue_session:
+                self._launch_resume_mode()
+            elif self.args.dev:
+                self._launch_dev_mode()
+            else:
+                self._launch_default_mode()
+        except Exception as e:
+            logger.warning(f"Error: Failed to start Claude Code: {e}")
+            sys.exit(1)
+
+    def _launch_orchestrator_mode(self) -> None:
+        """Launch with orchestrator prompt (--init).
+
+        Installs plugin, loads orchestrator system prompt, and starts Claude Code
+        in orchestrator mode with multi-AI delegation rules.
+        """
+        # Install plugin
+        PluginManager.install_or_update(verbose=self.interactive)
+
+        # Load prompt
+        prompt = get_orchestrator_prompt(include_dev_mode=False)
+
+        # Show banner
+        if self.interactive:
+            self._print_orchestrator_banner()
+
+        # Build command
+        cmd = ClaudeCommandBuilder().with_system_prompt(prompt).build()
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _launch_resume_mode(self) -> None:
+        """Resume last session with orchestrator rules (--continue).
+
+        Installs/updates marketplace plugin and resumes the last Claude Code
+        session with orchestrator system prompt. Uses marketplace plugin, NOT
+        local source (only --dev uses local source).
+        """
+        # Install/update marketplace plugin
+        PluginManager.install_or_update(verbose=self.interactive)
+
+        # Load prompt
+        prompt = get_orchestrator_prompt(include_dev_mode=False)
+
+        # Show status
+        if self.interactive:
+            logger.info("Resuming last Claude Code session...")
+            logger.info("  ✓ Multi-AI delegation rules injected")
+            logger.info("  ✓ Using marketplace plugin")
+
+        # Build command (no --plugin-dir, uses marketplace)
+        cmd = ClaudeCommandBuilder().with_resume().with_system_prompt(prompt).build()
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _launch_dev_mode(self) -> None:
+        """Launch with local plugin for development (--dev).
+
+        Loads plugin from local source directory for development/testing.
+        Changes to plugin files take effect after restart.
+        """
+        # Get and validate plugin directory
+        plugin_dir = PluginManager.get_plugin_dir()
+        PluginManager.validate_plugin_dir(plugin_dir)
+
+        # Load prompt with dev mode
+        prompt = get_orchestrator_prompt(include_dev_mode=True)
+
+        # Show banner
+        if self.interactive:
+            self._print_dev_mode_banner(plugin_dir)
+
+        # Build command
+        cmd = (
+            ClaudeCommandBuilder()
+            .with_plugin_dir(str(plugin_dir))
+            .with_system_prompt(prompt)
+            .build()
+        )
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _launch_default_mode(self) -> None:
+        """Launch with minimal orchestrator rules (default).
+
+        Starts Claude Code with basic multi-AI delegation rules but no plugin.
+        """
+        # Load prompt
+        prompt = get_orchestrator_prompt(include_dev_mode=False)
+
+        # Show status
+        if self.interactive:
+            logger.info("Starting Claude Code with multi-AI delegation rules...")
+
+        # Build command
+        cmd = ClaudeCommandBuilder().with_system_prompt(prompt).build()
+
+        # Execute
+        SubprocessRunner.run_claude_command(cmd)
+
+    def _print_orchestrator_banner(self) -> None:
+        """Print orchestrator mode banner."""
+        print("=" * 60)
+        logger.info("🤖 HtmlGraph Orchestrator Mode")
+        print("=" * 60)
+        logger.info("\nStarting Claude Code with orchestrator system prompt...")
+        logger.info("Key directives:")
+        logger.info("  ✓ Delegate to Gemini (FREE), Codex, Copilot first")
+        logger.info("  ✓ Use Task() only as fallback")
+        logger.info("  ✓ Create work items before delegating")
+        logger.info("  ✓ Track all work in .htmlgraph/")
+        print()
+
+    def _print_dev_mode_banner(self, plugin_dir: Path) -> None:
+        """Print development mode banner.
+
+        Args:
+            plugin_dir: Path to local plugin directory
+        """
+        print("=" * 60)
+        logger.info("🔧 HtmlGraph Development Mode")
+        print("=" * 60)
+        logger.info(f"\nLoading plugin from: {plugin_dir}")
+        logger.info("  ✓ Skills, agents, and hooks will be loaded from local files")
+        logger.info("  ✓ Orchestrator system prompt will be appended")
+        logger.info("  ✓ Multi-AI delegation rules will be injected")
+        logger.info("  ✓ Changes to plugin files will take effect after restart")
+        print()

htmlgraph/orchestration/command_builder.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+"""Command builder for Claude Code CLI invocations.
+
+Provides fluent interface for constructing Claude CLI commands.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ClaudeCommandBuilder:
+    """Fluent builder for Claude Code CLI commands.
+
+    Example:
+        >>> builder = ClaudeCommandBuilder()
+        >>> cmd = builder.with_resume() \\
+        ...     .with_plugin_dir("/path/to/plugin") \\
+        ...     .with_system_prompt("System prompt text") \\
+        ...     .build()
+        >>> # Result: ["claude", "--resume", "--plugin-dir", "/path/to/plugin",
+        ...  #          "--append-system-prompt", "System prompt text"]
+    """
+
+    def __init__(self) -> None:
+        """Initialize with base command."""
+        self._cmd: list[str] = ["claude"]
+
+    def with_resume(self) -> ClaudeCommandBuilder:
+        """Add --resume flag to resume last session.
+
+        Returns:
+            Self for method chaining
+        """
+        self._cmd.append("--resume")
+        return self
+
+    def with_plugin_dir(self, plugin_dir: str | Path) -> ClaudeCommandBuilder:
+        """Add --plugin-dir flag.
+
+        Args:
+            plugin_dir: Path to plugin directory
+
+        Returns:
+            Self for method chaining
+        """
+        self._cmd.extend(["--plugin-dir", str(plugin_dir)])
+        return self
+
+    def with_system_prompt(self, prompt: str) -> ClaudeCommandBuilder:
+        """Add --append-system-prompt flag.
+
+        Args:
+            prompt: System prompt text to append
+
+        Returns:
+            Self for method chaining
+        """
+        if prompt:  # Only add if prompt is not empty
+            self._cmd.extend(["--append-system-prompt", prompt])
+        return self
+
+    def build(self) -> list[str]:
+        """Build the final command list.
+
+        Returns:
+            List of command arguments ready for subprocess.run()
+        """
+        return self._cmd

htmlgraph/orchestration/headless_spawner.py

@@ -0,0 +1,281 @@
+"""Headless AI spawner for multi-AI orchestration.
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+This module provides backward compatibility by delegating to modular spawner implementations.
+"""
+
+from typing import Any
+
+from .spawners import (
+    AIResult,
+    ClaudeSpawner,
+    CodexSpawner,
+    CopilotSpawner,
+    GeminiSpawner,
+)
+
+# Re-export AIResult for backward compatibility
+__all__ = ["HeadlessSpawner", "AIResult"]
+
+
+class HeadlessSpawner:
+    """
+    Spawn AI agents in headless CLI mode.
+
+    Supports multiple AI CLIs:
+    - spawn_gemini(): Google Gemini (free tier)
+    - spawn_codex(): OpenAI Codex (ChatGPT Plus+)
+    - spawn_copilot(): GitHub Copilot (GitHub subscription)
+    - spawn_claude(): Claude Code (same login as Task tool)
+
+    spawn_claude() vs Task() Tool:
+    --------------------------------
+    Both use the same Claude Code authentication and billing, but:
+
+    spawn_claude():
+    - Isolated execution (no context sharing)
+    - Fresh session each call
+    - Best for: independent tasks, external scripts, parallel processing
+    - Cache miss on each call (higher token usage)
+
+    Task():
+    - Shared conversation context
+    - Builds on previous work
+    - Best for: orchestration, related sequential work
+    - Cache hits in session (5x cheaper for related work)
+
+    Example - When to use spawn_claude():
+        # Independent tasks in external script
+        spawner = HeadlessSpawner()
+        for file in files:
+            result = spawner.spawn_claude(f"Analyze {file} independently")
+            save_result(file, result)
+
+    Example - When to use Task() instead:
+        # Related tasks in orchestration workflow
+        Task(prompt="Analyze all files and compare them")
+        # Better: shares context, uses caching
+    """
+
+    def __init__(self) -> None:
+        """Initialize spawner with modular implementations."""
+        self._gemini_spawner = GeminiSpawner()
+        self._codex_spawner = CodexSpawner()
+        self._copilot_spawner = CopilotSpawner()
+        self._claude_spawner = ClaudeSpawner()
+
+    # 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)
+
+    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: Any
+    ) -> list[dict]:
+        """Parse and track Copilot events (delegates to CopilotSpawner)."""
+        return self._copilot_spawner._parse_and_track_events(prompt, response, sdk)
+
+    def _get_sdk(self) -> Any:
+        """Get SDK instance (delegates to base spawner implementation)."""
+        return self._gemini_spawner._get_sdk()
+
+    def spawn_gemini(
+        self,
+        prompt: str,
+        output_format: str = "stream-json",
+        model: str | None = None,
+        include_directories: list[str] | None = None,
+        track_in_htmlgraph: bool = True,
+        timeout: int = 120,
+        tracker: Any = None,
+        parent_event_id: str | None = None,
+    ) -> AIResult:
+        """
+        Spawn Gemini in headless mode.
+
+        Args:
+            prompt: Task description for Gemini
+            output_format: "json" or "stream-json" (enables real-time tracking)
+            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
+            tracker: Optional SpawnerEventTracker for recording subprocess invocation
+            parent_event_id: Optional parent event ID for event hierarchy
+
+        Returns:
+            AIResult with response, error, and tracked events if tracking enabled
+        """
+        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,
+        )
+
+    def spawn_codex(
+        self,
+        prompt: str,
+        output_json: bool = True,
+        model: str | None = None,
+        sandbox: str | None = None,
+        full_auto: bool = True,
+        images: list[str] | None = None,
+        output_last_message: str | None = None,
+        output_schema: str | None = None,
+        skip_git_check: bool = False,
+        working_directory: str | None = None,
+        use_oss: bool = False,
+        bypass_approvals: bool = False,
+        track_in_htmlgraph: bool = True,
+        timeout: int = 120,
+        tracker: Any = None,
+        parent_event_id: str | None = None,
+    ) -> AIResult:
+        """
+        Spawn Codex in headless mode.
+
+        Args:
+            prompt: Task description for Codex
+            output_json: JSONL output flag (enables real-time tracking)
+            model: Model selection (e.g., "gpt-4-turbo"). Default: None
+            sandbox: Sandbox mode ("read-only", "workspace-write", or full)
+            full_auto: Enable full auto mode. Default: True (required headless)
+            images: List of image paths (--image). Default: None
+            output_last_message: Write last message to file. Default: None
+            output_schema: JSON schema for validation. Default: None
+            skip_git_check: Skip git repo check. Default: False
+            working_directory: Workspace directory (--cd). Default: None
+            use_oss: Use local Ollama provider (--oss). Default: False
+            bypass_approvals: Bypass approval checks. Default: False
+            track_in_htmlgraph: Enable HtmlGraph activity tracking. Default: True
+            timeout: Max seconds to wait
+            tracker: Optional SpawnerEventTracker for recording subprocess invocation
+            parent_event_id: Optional parent event ID for event hierarchy
+
+        Returns:
+            AIResult with response, error, and tracked events if tracking enabled
+        """
+        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,
+        )
+
+    def spawn_copilot(
+        self,
+        prompt: str,
+        allow_tools: list[str] | None = None,
+        allow_all_tools: bool = False,
+        deny_tools: list[str] | None = None,
+        track_in_htmlgraph: bool = True,
+        timeout: int = 120,
+        tracker: Any = None,
+        parent_event_id: str | None = None,
+    ) -> AIResult:
+        """
+        Spawn GitHub Copilot in headless mode.
+
+        Args:
+            prompt: Task description for Copilot
+            allow_tools: Tools to auto-approve (e.g., ["shell(git)"])
+            allow_all_tools: Auto-approve all tools. Default: False
+            deny_tools: Tools to deny (--deny-tool). Default: None
+            track_in_htmlgraph: Enable HtmlGraph activity tracking. Default: True
+            timeout: Max seconds to wait
+            tracker: Optional SpawnerEventTracker for recording subprocess invocation
+            parent_event_id: Optional parent event ID for event hierarchy
+
+        Returns:
+            AIResult with response, error, and tracked events if tracking enabled
+        """
+        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,
+        )
+
+    def spawn_claude(
+        self,
+        prompt: str,
+        output_format: str = "json",
+        permission_mode: str = "bypassPermissions",
+        resume: str | None = None,
+        verbose: bool = False,
+        timeout: int = 300,
+        extra_args: list[str] | None = None,
+    ) -> AIResult:
+        """
+        Spawn Claude in headless mode.
+
+        NOTE: Uses same Claude Code authentication as Task() tool, but provides
+        isolated execution context. Each call creates a new session without shared
+        context. Best for independent tasks or external scripts.
+
+        For orchestration workflows with shared context, prefer Task() tool which
+        leverages prompt caching (5x cheaper for related work).
+
+        Args:
+            prompt: Task description for Claude
+            output_format: "text" or "json" (stream-json requires --verbose)
+            permission_mode: Permission handling mode:
+                - "bypassPermissions": Auto-approve all (default)
+                - "acceptEdits": Auto-approve edits only
+                - "dontAsk": Fail on permission prompts
+                - "default": Normal interactive prompts
+                - "plan": Plan mode (no execution)
+                - "delegate": Delegation mode
+            resume: Resume from previous session (--resume). Default: None
+            verbose: Enable verbose output (--verbose). Default: False
+            timeout: Max seconds (default: 300, Claude can be slow with initialization)
+            extra_args: Additional arguments to pass to Claude CLI
+
+        Returns:
+            AIResult with response or error
+
+        Example:
+            >>> spawner = HeadlessSpawner()
+            >>> result = spawner.spawn_claude("What is 2+2?")
+            >>> if result.success:
+            ...     logger.info("%s", result.response)  # "4"
+            ...     logger.info(f"Cost: ${result.raw_output['total_cost_usd']}")
+        """
+        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,
+        )