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

htmlgraph/orchestration/plugin_manager.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+"""Plugin management for HtmlGraph Claude Code integration.
+
+Centralizes plugin installation, directory management, and validation.
+"""
+
+import logging
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+logger = logging.getLogger(__name__)
+
+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 (the plugin root, not .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"
+        )
+
+    @staticmethod
+    def install_or_update(verbose: bool = True) -> None:
+        """Install or update HtmlGraph plugin.
+
+        Args:
+            verbose: Whether to show progress messages
+        """
+        if verbose:
+            logger.info("\n📦 Installing/upgrading HtmlGraph plugin...\n")
+
+        # Step 1: Update marketplace
+        try:
+            if verbose:
+                logger.info("  Updating marketplace...")
+            result = subprocess.run(
+                ["claude", "plugin", "marketplace", "update", "htmlgraph"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode == 0:
+                if verbose:
+                    logger.info("    ✓ Marketplace updated")
+            else:
+                # Non-blocking errors
+                if (
+                    "not found" in result.stderr.lower()
+                    or "no marketplace" in result.stderr.lower()
+                ):
+                    if verbose:
+                        logger.info("    ℹ Marketplace not configured (OK, continuing)")
+                elif verbose:
+                    logger.info(f"    ⚠ Marketplace update: {result.stderr.strip()}")
+        except FileNotFoundError:
+            if verbose:
+                logger.info("    ⚠ 'claude' command not found")
+        except Exception as e:
+            if verbose:
+                logger.info(f"    ⚠ Error updating marketplace: {e}")
+
+        # Step 2: Try update, fallback to install
+        try:
+            if verbose:
+                logger.info("  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:
+                    logger.info("    ✓ Plugin updated successfully")
+            else:
+                # Fallback to install
+                if (
+                    "not installed" in result.stderr.lower()
+                    or "not found" in result.stderr.lower()
+                ):
+                    if verbose:
+                        logger.info("    ℹ 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:
+                            logger.info("    ✓ Plugin installed successfully")
+                    elif verbose:
+                        logger.info(
+                            f"    ⚠ Plugin install: {install_result.stderr.strip()}"
+                        )
+                elif verbose:
+                    logger.info(f"    ⚠ Plugin update: {result.stderr.strip()}")
+        except FileNotFoundError:
+            if verbose:
+                logger.info("    ⚠ 'claude' command not found")
+        except Exception as e:
+            if verbose:
+                logger.info(f"    ⚠ Error updating plugin: {e}")
+
+        if verbose:
+            logger.info("\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():
+            logger.warning(f"Error: Plugin directory not found: {plugin_dir}")
+            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/spawner_event_tracker.py

@@ -0,0 +1,383 @@
+"""Spawner event tracking helper for internal activity tracking in spawned sessions.
+
+This module provides utilities for tracking internal activities within spawner agents
+and linking them to parent delegation events for observability in HtmlGraph.
+
+Usage:
+    from htmlgraph.orchestration.spawner_event_tracker import SpawnerEventTracker
+
+    tracker = SpawnerEventTracker(
+        delegation_event_id="event-abc123",
+        parent_agent="orchestrator",
+        spawner_type="gemini"
+    )
+
+    # Track initialization phase
+    init_event = tracker.record_phase("Initializing Spawner", spawned_agent="gemini-2.0-flash")
+
+    # Track execution phase
+    exec_event = tracker.record_phase("Executing Gemini", tool_name="gemini-cli")
+    tracker.complete_phase(exec_event["event_id"], output_summary="Generated output...")
+
+    # Track completion
+    tracker.record_completion(success=True, response="Result here")
+"""
+
+import os
+import time
+import uuid
+from typing import Any
+
+
+class SpawnerEventTracker:
+    """Track internal activities in spawner agents with parent-child linking."""
+
+    def __init__(
+        self,
+        delegation_event_id: str | None = None,
+        parent_agent: str = "orchestrator",
+        spawner_type: str = "generic",
+        session_id: str | None = None,
+    ):
+        """
+        Initialize spawner event tracker.
+
+        Args:
+            delegation_event_id: Parent delegation event ID to link to
+            parent_agent: Agent that initiated the spawning
+            spawner_type: Type of spawner (gemini, codex, copilot)
+            session_id: Session ID for events
+        """
+        self.delegation_event_id = delegation_event_id
+        self.parent_agent = parent_agent
+        self.spawner_type = spawner_type
+        self.session_id = session_id or f"session-{uuid.uuid4().hex[:8]}"
+        self.db = None
+        self.phase_events: dict[str, dict[str, Any]] = {}
+        self.start_time = time.time()
+
+        # Try to initialize database for event tracking
+        try:
+            from htmlgraph.config import get_database_path
+            from htmlgraph.db.schema import HtmlGraphDB
+
+            # Get correct database path from environment or project root
+            db_path = get_database_path()
+
+            if db_path.exists():
+                self.db = HtmlGraphDB(str(db_path))
+        except Exception:
+            # Tracking is optional, continue without it
+            pass
+
+    def record_phase(
+        self,
+        phase_name: str,
+        spawned_agent: str | None = None,
+        tool_name: str | None = None,
+        input_summary: str | None = None,
+        status: str = "running",
+        parent_phase_event_id: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record the start of a phase in spawner execution.
+
+        Args:
+            phase_name: Human-readable phase name (e.g., "Initializing Spawner")
+            spawned_agent: Agent being spawned (optional)
+            tool_name: Tool being executed (optional)
+            input_summary: Summary of input (optional)
+            status: Current status (running, completed, failed)
+            parent_phase_event_id: Parent phase event ID for proper nesting (optional)
+
+        Returns:
+            Event dictionary with event_id and metadata
+        """
+        if not self.db:
+            return {}
+
+        event_id = f"event-{uuid.uuid4().hex[:8]}"
+        event_type = "tool_call"
+
+        try:
+            context = {
+                "phase_name": phase_name,
+                "spawner_type": self.spawner_type,
+                "parent_delegation_event": self.delegation_event_id,
+            }
+            if spawned_agent:
+                context["spawned_agent"] = spawned_agent
+            if tool_name:
+                context["tool"] = tool_name
+
+            # Use parent_phase_event_id if provided, otherwise use delegation_event_id
+            actual_parent_event_id = parent_phase_event_id or self.delegation_event_id
+
+            self.db.insert_event(
+                event_id=event_id,
+                agent_id=spawned_agent or self.parent_agent,
+                event_type=event_type,
+                session_id=self.session_id,
+                tool_name=tool_name
+                or f"HeadlessSpawner.{phase_name.replace(' ', '_').lower()}",
+                input_summary=input_summary or phase_name,
+                context=context,
+                parent_event_id=actual_parent_event_id,
+                subagent_type=self.spawner_type,
+            )
+
+            event = {
+                "event_id": event_id,
+                "phase_name": phase_name,
+                "spawned_agent": spawned_agent,
+                "tool_name": tool_name,
+                "status": status,
+                "start_time": time.time(),
+            }
+            self.phase_events[event_id] = event
+            return event
+
+        except Exception:
+            # Non-fatal - tracking is best-effort
+            return {}
+
+    def complete_phase(
+        self,
+        event_id: str,
+        output_summary: str | None = None,
+        status: str = "completed",
+        execution_duration: float | None = None,
+    ) -> bool:
+        """
+        Mark a phase as completed with results.
+
+        Args:
+            event_id: Event ID from record_phase
+            output_summary: Summary of output/result
+            status: Final status (completed, failed)
+            execution_duration: Execution time in seconds (auto-calculated if not provided)
+
+        Returns:
+            True if update successful, False otherwise
+        """
+        if not self.db or not event_id:
+            return False
+
+        try:
+            if execution_duration is None and event_id in self.phase_events:
+                execution_duration = (
+                    time.time() - self.phase_events[event_id]["start_time"]
+                )
+
+            if self.db.connection is None:
+                return False
+
+            cursor = self.db.connection.cursor()
+            cursor.execute(
+                """
+                UPDATE agent_events
+                SET output_summary = ?, status = ?, execution_duration_seconds = ?,
+                    updated_at = CURRENT_TIMESTAMP
+                WHERE event_id = ?
+            """,
+                (output_summary, status, execution_duration or 0.0, event_id),
+            )
+            self.db.connection.commit()
+
+            if event_id in self.phase_events:
+                self.phase_events[event_id]["status"] = status
+                self.phase_events[event_id]["output_summary"] = output_summary
+
+            return True
+        except Exception:
+            # Non-fatal
+            return False
+
+    def record_completion(
+        self,
+        success: bool,
+        response: str | None = None,
+        error: str | None = None,
+        tokens_used: int = 0,
+        cost: float = 0.0,
+    ) -> dict[str, Any]:
+        """
+        Record final completion with overall results.
+
+        Args:
+            success: Whether execution succeeded
+            response: Successful response/output
+            error: Error message if failed
+            tokens_used: Tokens consumed
+            cost: Execution cost
+
+        Returns:
+            Completion event dictionary
+        """
+        total_duration = time.time() - self.start_time
+
+        completion_event: dict[str, Any] = {
+            "success": success,
+            "duration": total_duration,
+            "tokens": tokens_used,
+            "cost": cost,
+            "phase_count": len(self.phase_events),
+        }
+
+        if success:
+            completion_event["response"] = response
+        else:
+            completion_event["error"] = error
+
+        return completion_event
+
+    def get_phase_events(self) -> dict[str, dict[str, Any]]:
+        """Get all recorded phase events."""
+        return self.phase_events
+
+    def record_tool_call(
+        self,
+        tool_name: str,
+        tool_input: dict | None,
+        phase_event_id: str,
+        spawned_agent: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record a tool call within a spawned execution phase.
+
+        Args:
+            tool_name: Name of the tool (bash, read_file, write_file, etc.)
+            tool_input: Input parameters to the tool
+            phase_event_id: Parent phase event ID to link to
+            spawned_agent: Agent making the tool call (optional)
+
+        Returns:
+            Event dictionary with event_id and metadata
+        """
+        if not self.db:
+            return {}
+
+        event_id = f"event-{uuid.uuid4().hex[:8]}"
+
+        try:
+            context = {
+                "tool_name": tool_name,
+                "spawner_type": self.spawner_type,
+                "parent_phase_event": phase_event_id,
+            }
+            if spawned_agent:
+                context["spawned_agent"] = spawned_agent
+
+            self.db.insert_event(
+                event_id=event_id,
+                agent_id=spawned_agent or self.parent_agent,
+                event_type="tool_call",
+                session_id=self.session_id,
+                tool_name=tool_name,
+                input_summary=(
+                    str(tool_input)[:200] if tool_input else f"Call to {tool_name}"
+                ),
+                context=context,
+                parent_event_id=phase_event_id,
+                subagent_type=self.spawner_type,
+            )
+
+            tool_event = {
+                "event_id": event_id,
+                "tool_name": tool_name,
+                "tool_input": tool_input,
+                "phase_event_id": phase_event_id,
+                "spawned_agent": spawned_agent,
+                "status": "running",
+                "start_time": time.time(),
+            }
+            return tool_event
+
+        except Exception:
+            # Non-fatal - tracking is best-effort
+            return {}
+
+    def complete_tool_call(
+        self,
+        event_id: str,
+        output_summary: str | None = None,
+        success: bool = True,
+    ) -> bool:
+        """
+        Mark a tool call as complete with results.
+
+        Args:
+            event_id: Event ID from record_tool_call
+            output_summary: Summary of tool output/result
+            success: Whether the tool call succeeded
+
+        Returns:
+            True if update successful, False otherwise
+        """
+        if not self.db or not event_id:
+            return False
+
+        try:
+            if self.db.connection is None:
+                return False
+
+            cursor = self.db.connection.cursor()
+            cursor.execute(
+                """
+                UPDATE agent_events
+                SET output_summary = ?, status = ?, updated_at = CURRENT_TIMESTAMP
+                WHERE event_id = ?
+            """,
+                (
+                    output_summary,
+                    "completed" if success else "failed",
+                    event_id,
+                ),
+            )
+            self.db.connection.commit()
+            return True
+        except Exception:
+            # Non-fatal
+            return False
+
+    def get_event_hierarchy(self) -> dict[str, Any]:
+        """
+        Get the event hierarchy for this spawner execution.
+
+        Returns:
+            Dictionary with delegation event as root and phases as children
+        """
+        return {
+            "delegation_event_id": self.delegation_event_id,
+            "spawner_type": self.spawner_type,
+            "session_id": self.session_id,
+            "total_duration": time.time() - self.start_time,
+            "phase_events": self.phase_events,
+        }
+
+
+def create_tracker_from_env(
+    spawner_type: str = "generic",
+) -> SpawnerEventTracker:
+    """
+    Create a SpawnerEventTracker from environment variables.
+
+    Reads HTMLGRAPH_PARENT_EVENT, HTMLGRAPH_PARENT_AGENT, HTMLGRAPH_PARENT_SESSION
+    from environment to link to parent context.
+
+    Args:
+        spawner_type: Type of spawner (gemini, codex, copilot)
+
+    Returns:
+        Initialized SpawnerEventTracker
+    """
+    delegation_event_id = os.getenv("HTMLGRAPH_PARENT_EVENT")
+    parent_agent = os.getenv("HTMLGRAPH_PARENT_AGENT", "orchestrator")
+    session_id = os.getenv("HTMLGRAPH_PARENT_SESSION")
+
+    return SpawnerEventTracker(
+        delegation_event_id=delegation_event_id,
+        parent_agent=parent_agent,
+        spawner_type=spawner_type,
+        session_id=session_id,
+    )

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",
+]