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

htmlgraph/orchestration/plugin_manager.py

@@ -0,0 +1,136 @@
+"""Plugin management for HtmlGraph Claude Code integration.
+
+Centralizes plugin installation, directory management, and validation.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+
+class PluginManager:
+    """Manage HtmlGraph Claude plugin installation and directories."""
+
+    @staticmethod
+    def get_plugin_dir() -> Path:
+        """Get the plugin directory path.
+
+        Returns:
+            Path to packages/claude-plugin/.claude-plugin
+        """
+        # Path(__file__) = .../src/python/htmlgraph/orchestration/plugin_manager.py
+        # Need to go up 5 levels to reach project root
+        return (
+            Path(__file__).parent.parent.parent.parent.parent
+            / "packages"
+            / "claude-plugin"
+            / ".claude-plugin"
+        )
+
+    @staticmethod
+    def install_or_update(verbose: bool = True) -> None:
+        """Install or update HtmlGraph plugin.
+
+        Args:
+            verbose: Whether to show progress messages
+        """
+        if verbose:
+            print("\n📦 Installing/upgrading HtmlGraph plugin...\n")
+
+        # Step 1: Update marketplace
+        try:
+            if verbose:
+                print("  Updating marketplace...")
+            result = subprocess.run(
+                ["claude", "plugin", "marketplace", "update", "htmlgraph"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode == 0:
+                if verbose:
+                    print("    ✓ Marketplace updated")
+            else:
+                # Non-blocking errors
+                if (
+                    "not found" in result.stderr.lower()
+                    or "no marketplace" in result.stderr.lower()
+                ):
+                    if verbose:
+                        print("    ℹ Marketplace not configured (OK, continuing)")
+                elif verbose:
+                    print(f"    ⚠ Marketplace update: {result.stderr.strip()}")
+        except FileNotFoundError:
+            if verbose:
+                print("    ⚠ 'claude' command not found")
+        except Exception as e:
+            if verbose:
+                print(f"    ⚠ Error updating marketplace: {e}")
+
+        # Step 2: Try update, fallback to install
+        try:
+            if verbose:
+                print("  Updating plugin to latest version...")
+            result = subprocess.run(
+                ["claude", "plugin", "update", "htmlgraph"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode == 0:
+                if verbose:
+                    print("    ✓ Plugin updated successfully")
+            else:
+                # Fallback to install
+                if (
+                    "not installed" in result.stderr.lower()
+                    or "not found" in result.stderr.lower()
+                ):
+                    if verbose:
+                        print("    ℹ Plugin not yet installed, installing...")
+                    install_result = subprocess.run(
+                        ["claude", "plugin", "install", "htmlgraph"],
+                        capture_output=True,
+                        text=True,
+                        check=False,
+                    )
+                    if install_result.returncode == 0:
+                        if verbose:
+                            print("    ✓ Plugin installed successfully")
+                    elif verbose:
+                        print(f"    ⚠ Plugin install: {install_result.stderr.strip()}")
+                elif verbose:
+                    print(f"    ⚠ Plugin update: {result.stderr.strip()}")
+        except FileNotFoundError:
+            if verbose:
+                print("    ⚠ 'claude' command not found")
+        except Exception as e:
+            if verbose:
+                print(f"    ⚠ Error updating plugin: {e}")
+
+        if verbose:
+            print("\n✓ Plugin installation complete\n")
+
+    @staticmethod
+    def validate_plugin_dir(plugin_dir: Path) -> None:
+        """Validate that plugin directory exists, exit if not.
+
+        Args:
+            plugin_dir: Path to plugin directory
+
+        Raises:
+            SystemExit: If plugin directory doesn't exist
+        """
+        if not plugin_dir.exists():
+            print(f"Error: Plugin directory not found: {plugin_dir}", file=sys.stderr)
+            print(
+                "Expected location: packages/claude-plugin/.claude-plugin",
+                file=sys.stderr,
+            )
+            sys.exit(1)

htmlgraph/orchestration/prompts.py

@@ -0,0 +1,137 @@
+"""
+Orchestrator system prompt loading and management.
+
+Centralizes logic for loading and combining orchestrator system prompts,
+keeping CLI code clean and focused on invocation.
+"""
+
+import textwrap
+from pathlib import Path
+
+
+def get_orchestrator_prompt(include_dev_mode: bool = False) -> str:
+    """
+    Load and combine orchestrator system prompts.
+
+    Args:
+        include_dev_mode: If True, append development mode guidance
+
+    Returns:
+        Combined system prompt text ready for --append-system-prompt
+    """
+    package_dir = Path(__file__).parent.parent
+
+    # Load base orchestrator prompt
+    prompt_file = package_dir / "orchestrator-system-prompt-optimized.txt"
+    if prompt_file.exists():
+        base_prompt = prompt_file.read_text(encoding="utf-8")
+    else:
+        # Fallback: minimal orchestrator guidance
+        base_prompt = textwrap.dedent(
+            """
+            You are an AI orchestrator for HtmlGraph project development.
+
+            CRITICAL DIRECTIVES:
+            1. DELEGATE to spawner skills - do not implement directly
+            2. CREATE work items before delegating (features, bugs, spikes)
+            3. USE SDK for tracking - all work must be tracked in .htmlgraph/
+            4. RESPECT dependencies - check blockers before starting
+
+            Key Rules:
+            - Exploration/Research → Skill(skill=".claude-plugin:gemini")
+            - Code implementation → Skill(skill=".claude-plugin:codex")
+            - Git/GitHub ops → Skill(skill=".claude-plugin:copilot")
+            - Strategic planning → Task() with Claude subagent
+
+            Always use:
+                from htmlgraph import SDK
+                sdk = SDK(agent='orchestrator')
+
+            See CLAUDE.md for complete orchestrator directives.
+            """
+        )
+
+    # Load orchestration rules
+    rules_file = package_dir / "orchestration.md"
+    orchestration_rules = ""
+    if rules_file.exists():
+        orchestration_rules = rules_file.read_text(encoding="utf-8")
+
+    # Combine prompts
+    combined_prompt = base_prompt
+    if orchestration_rules:
+        combined_prompt = f"{base_prompt}\n\n---\n\n{orchestration_rules}"
+
+    # Add dev mode guidance if requested
+    if include_dev_mode:
+        dev_addendum = textwrap.dedent(
+            """
+
+            ═══════════════════════════════════════════════════════════
+            🔧 DEVELOPMENT MODE - HtmlGraph Project
+            ═══════════════════════════════════════════════════════════
+
+            CRITICAL: Hooks load htmlgraph from PyPI, NOT local source!
+
+            Development Workflow:
+            1. Make changes to src/python/htmlgraph/
+            2. Run tests: uv run pytest
+            3. Deploy to PyPI: ./scripts/deploy-all.sh X.Y.Z --no-confirm
+            4. Restart Claude Code (hooks auto-load new version from PyPI)
+            5. Verify changes work correctly
+
+            Why PyPI in Dev Mode?
+            - Hooks use: #!/usr/bin/env -S uv run --with htmlgraph
+            - Always pulls latest version from PyPI
+            - Tests in production-like environment
+            - No surprises when distributed to users
+            - Single source of truth (PyPI package)
+
+            Incremental Versioning:
+            - Use patch versions: 0.26.2 → 0.26.3 → 0.26.4
+            - No need to edit hook shebangs (always get latest)
+            - Deploy frequently for rapid iteration
+
+            Session ID Tracking (v0.26.3+):
+            - PostToolUse hooks query for most recent UserQuery session
+            - All events should share same session_id
+            - Verify: See "Development Mode" section in CLAUDE.md
+
+            Key References:
+            - Development workflow: CLAUDE.md "Development Mode" section
+            - Orchestrator patterns: /orchestrator-directives skill
+            - Code quality: /code-quality skill
+            - Deployment: /deployment-automation skill
+
+            Remember: You're dogfooding HtmlGraph!
+            - Use SDK to track your own work
+            - Delegate to spawner agents (Gemini, Codex, Copilot)
+            - Follow orchestration patterns
+            - Test in production-like environment
+
+            ═══════════════════════════════════════════════════════════
+            """
+        )
+        combined_prompt += dev_addendum
+
+    return combined_prompt
+
+
+def get_prompt_summary() -> dict[str, str]:
+    """
+    Get summary of available prompt components.
+
+    Returns:
+        Dictionary with component names and their status
+    """
+    package_dir = Path(__file__).parent.parent
+
+    prompt_file = package_dir / "orchestrator-system-prompt-optimized.txt"
+    rules_file = package_dir / "orchestration.md"
+
+    return {
+        "base_prompt": "✓ Found" if prompt_file.exists() else "✗ Missing",
+        "orchestration_rules": "✓ Found" if rules_file.exists() else "✗ Missing",
+        "base_prompt_path": str(prompt_file),
+        "rules_path": str(rules_file),
+    }

htmlgraph/orchestration/spawners/__init__.py

@@ -0,0 +1,16 @@
+"""AI spawner implementations for multi-AI orchestration."""
+
+from .base import AIResult, BaseSpawner
+from .claude import ClaudeSpawner
+from .codex import CodexSpawner
+from .copilot import CopilotSpawner
+from .gemini import GeminiSpawner
+
+__all__ = [
+    "AIResult",
+    "BaseSpawner",
+    "ClaudeSpawner",
+    "CodexSpawner",
+    "CopilotSpawner",
+    "GeminiSpawner",
+]

htmlgraph/orchestration/spawners/base.py

@@ -0,0 +1,194 @@
+"""Base spawner class with common functionality for all AI spawners."""
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.orchestration.live_events import LiveEventPublisher
+    from htmlgraph.sdk import SDK
+
+
+@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
+
+
+class BaseSpawner:
+    """
+    Base class for AI spawners with common functionality.
+
+    Provides:
+    - Live event publishing for WebSocket streaming
+    - SDK initialization with parent session support
+    - Common error handling patterns
+    """
+
+    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 _get_parent_context(self) -> tuple[str | None, int]:
+        """
+        Get parent activity context for event tracking.
+
+        Returns:
+            Tuple of (parent_activity_id, nesting_depth)
+        """
+        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
+        return parent_activity, nesting_depth
+
+    def _track_activity(
+        self,
+        sdk: "SDK",
+        tool: str,
+        summary: str,
+        payload: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Track activity in HtmlGraph with parent context.
+
+        Args:
+            sdk: SDK instance
+            tool: Tool name
+            summary: Activity summary
+            payload: Activity payload (will be enriched with parent context)
+            **kwargs: Additional arguments for track_activity
+        """
+        if payload is None:
+            payload = {}
+
+        # Enrich with parent context
+        parent_activity, nesting_depth = self._get_parent_context()
+        if parent_activity:
+            payload["parent_activity"] = parent_activity
+        if nesting_depth > 0:
+            payload["nesting_depth"] = nesting_depth
+
+        try:
+            sdk.track_activity(tool=tool, summary=summary, payload=payload, **kwargs)
+        except Exception:
+            # Tracking failure should not break execution
+            pass

htmlgraph/orchestration/spawners/claude.py

@@ -0,0 +1,170 @@
+"""Claude spawner implementation."""
+
+import json
+import subprocess
+from typing import TYPE_CHECKING
+
+from .base import AIResult, BaseSpawner
+
+if TYPE_CHECKING:
+    pass
+
+
+class ClaudeSpawner(BaseSpawner):
+    """
+    Spawner for Claude Code CLI.
+
+    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).
+    """
+
+    def spawn(
+        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 = ClaudeSpawner()
+            >>> result = spawner.spawn("What is 2+2?")
+            >>> if result.success:
+            ...     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,
+            )