htmlgraph 0.26.24__py3-none-any.whl → 0.27.0__py3-none-any.whl

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/claude.py

@@ -1,11 +1,14 @@
 """Claude spawner implementation."""
 
 import json
+import logging
 import subprocess
 from typing import TYPE_CHECKING
 
 from .base import AIResult, BaseSpawner
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     pass
 
@@ -64,8 +67,8 @@ class ClaudeSpawner(BaseSpawner):
             >>> 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']}")
+            ...     logger.info("%s", result.response)  # "4"
+            ...     logger.info(f"Cost: ${result.raw_output['total_cost_usd']}")
         """
         cmd = ["claude", "-p"]
 

htmlgraph/orchestration/spawners/codex.py

@@ -1,13 +1,15 @@
 """Codex spawner implementation."""
 
 import json
+import logging
 import subprocess
-import sys
 import time
 from typing import TYPE_CHECKING, Any
 
 from .base import AIResult, BaseSpawner
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from htmlgraph.sdk import SDK
 
@@ -232,15 +234,11 @@ class CodexSpawner(BaseSpawner):
 
             # 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,
+            logger.warning(
+                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}"
             )
             if tracker and parent_event_id:
-                print(
-                    "DEBUG: Recording subprocess invocation for Codex...",
-                    file=sys.stderr,
-                )
+                logger.debug("Recording subprocess invocation for Codex...")
                 try:
                     subprocess_event = tracker.record_tool_call(
                         tool_name="subprocess.codex",
@@ -250,23 +248,18 @@ class CodexSpawner(BaseSpawner):
                     )
                     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,
+                        logger.warning(
+                            f"DEBUG: Subprocess event created for Codex: {subprocess_event_id}"
                         )
                     else:
-                        print("DEBUG: subprocess_event was None", file=sys.stderr)
+                        logger.debug("subprocess_event was None")
                 except Exception as e:
                     # Tracking failure should not break execution
-                    print(
-                        f"DEBUG: Exception recording Codex subprocess: {e}",
-                        file=sys.stderr,
-                    )
+                    logger.warning(f"DEBUG: Exception recording Codex subprocess: {e}")
                     pass
             else:
-                print(
-                    f"DEBUG: Skipping Codex subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
+                logger.warning(
+                    f"DEBUG: Skipping Codex subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}"
                 )
 
             result = subprocess.run(

htmlgraph/orchestration/spawners/copilot.py

@@ -1,12 +1,14 @@
 """Copilot spawner implementation."""
 
+import logging
 import subprocess
-import sys
 import time
 from typing import TYPE_CHECKING, Any
 
 from .base import AIResult, BaseSpawner
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from htmlgraph.sdk import SDK
 
@@ -129,15 +131,11 @@ class CopilotSpawner(BaseSpawner):
 
             # 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,
+            logger.warning(
+                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}"
             )
             if tracker and parent_event_id:
-                print(
-                    "DEBUG: Recording subprocess invocation for Copilot...",
-                    file=sys.stderr,
-                )
+                logger.debug("Recording subprocess invocation for Copilot...")
                 try:
                     subprocess_event = tracker.record_tool_call(
                         tool_name="subprocess.copilot",
@@ -147,23 +145,20 @@ class CopilotSpawner(BaseSpawner):
                     )
                     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,
+                        logger.warning(
+                            f"DEBUG: Subprocess event created for Copilot: {subprocess_event_id}"
                         )
                     else:
-                        print("DEBUG: subprocess_event was None", file=sys.stderr)
+                        logger.debug("subprocess_event was None")
                 except Exception as e:
                     # Tracking failure should not break execution
-                    print(
-                        f"DEBUG: Exception recording Copilot subprocess: {e}",
-                        file=sys.stderr,
+                    logger.warning(
+                        f"DEBUG: Exception recording Copilot subprocess: {e}"
                     )
                     pass
             else:
-                print(
-                    f"DEBUG: Skipping Copilot subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
+                logger.warning(
+                    f"DEBUG: Skipping Copilot subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}"
                 )
 
             result = subprocess.run(

htmlgraph/orchestration/spawners/gemini.py

@@ -1,13 +1,15 @@
 """Gemini spawner implementation."""
 
 import json
+import logging
 import subprocess
-import sys
 import time
 from typing import TYPE_CHECKING, Any
 
 from .base import AIResult, BaseSpawner
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from htmlgraph.sdk import SDK
 
@@ -220,15 +222,11 @@ class GeminiSpawner(BaseSpawner):
 
             # 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,
+            logger.warning(
+                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}"
             )
             if tracker and parent_event_id:
-                print(
-                    "DEBUG: Recording subprocess invocation for Gemini...",
-                    file=sys.stderr,
-                )
+                logger.debug("Recording subprocess invocation for Gemini...")
                 try:
                     subprocess_event = tracker.record_tool_call(
                         tool_name="subprocess.gemini",
@@ -238,23 +236,18 @@ class GeminiSpawner(BaseSpawner):
                     )
                     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,
+                        logger.warning(
+                            f"DEBUG: Subprocess event created for Gemini: {subprocess_event_id}"
                         )
                     else:
-                        print("DEBUG: subprocess_event was None", file=sys.stderr)
+                        logger.debug("subprocess_event was None")
                 except Exception as e:
                     # Tracking failure should not break execution
-                    print(
-                        f"DEBUG: Exception recording Gemini subprocess: {e}",
-                        file=sys.stderr,
-                    )
+                    logger.warning(f"DEBUG: Exception recording Gemini subprocess: {e}")
                     pass
             else:
-                print(
-                    f"DEBUG: Skipping Gemini subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
+                logger.warning(
+                    f"DEBUG: Skipping Gemini subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}"
                 )
 
             # Execute with timeout and stderr redirection

htmlgraph/orchestration/subprocess_runner.py

@@ -1,13 +1,16 @@
+from __future__ import annotations
+
 """Subprocess execution with standardized error handling.
 
 Provides consistent error handling for Claude Code CLI invocations.
 """
 
-from __future__ import annotations
-
+import logging
 import subprocess
 import sys
 
+logger = logging.getLogger(__name__)
+
 
 class SubprocessRunner:
     """Execute subprocess commands with error handling."""
@@ -25,7 +28,7 @@ class SubprocessRunner:
         try:
             subprocess.run(cmd, check=False)
         except FileNotFoundError:
-            print("Error: 'claude' command not found.", file=sys.stderr)
+            logger.warning("Error: 'claude' command not found.")
             print(
                 "Please install Claude Code CLI: https://code.claude.com",
                 file=sys.stderr,