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

htmlgraph/hooks/subagent_stop.py

@@ -0,0 +1,369 @@
+"""
+SubagentStop Hook - Update parent events when subagents complete.
+
+This module handles the SubagentStop hook event, which fires when a subagent
+(spawned via Task()) completes. It updates the parent event with completion
+status and counts child spikes created during the subagent's execution.
+
+Architecture:
+- Reads HTMLGRAPH_PARENT_EVENT from environment (set by PreToolUse hook)
+- Queries database for spikes created since parent event start
+- Updates parent event: status="completed", child_spike_count=N
+- Handles graceful degradation if parent event not found
+
+Parent-Child Event Nesting:
+- Parent: evt-abc (Task delegation) created by PreToolUse
+- Child events: spikes created by subagent during task execution
+- Result: Full trace of delegation work visible in dashboard
+"""
+
+import json
+import logging
+import os
+import sqlite3
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def get_parent_event_id() -> str | None:
+    """
+    Get the parent event ID from environment.
+
+    Set by PreToolUse hook when Task() is detected.
+
+    Returns:
+        Parent event ID (evt-XXXXX) or None if not found
+    """
+    return os.environ.get("HTMLGRAPH_PARENT_EVENT")
+
+
+def get_session_id() -> str | None:
+    """
+    Get the current session ID from environment.
+
+    Set by SessionStart hook.
+
+    Returns:
+        Session ID or None if not found
+    """
+    return os.environ.get("HTMLGRAPH_SESSION_ID")
+
+
+def count_child_spikes(
+    db_path: str, parent_event_id: str, parent_start_time: str
+) -> int:
+    """
+    Count spikes created after the parent event started.
+
+    Queries the features table for spikes with created_at > parent start time.
+    Uses a narrow time window (5 minutes) to avoid counting unrelated spikes
+    from other sessions.
+
+    Args:
+        db_path: Path to SQLite database
+        parent_event_id: Parent event ID
+        parent_start_time: ISO8601 timestamp when parent event started
+
+    Returns:
+        Count of child spikes (0 if none found)
+    """
+    try:
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        # Validate parent start time format (ISO8601)
+        try:
+            datetime.fromisoformat(parent_start_time)
+        except (ValueError, TypeError):
+            # If parsing fails, return 0 (couldn't validate time window)
+            logger.warning(f"Could not parse parent start time: {parent_start_time}")
+            return 0
+
+        # Query spikes created within 5 minutes after parent event
+        # This avoids counting unrelated spikes from other sessions
+        query = """
+            SELECT COUNT(*) FROM features
+            WHERE type = 'spike'
+            AND created_at >= ?
+            AND created_at <= datetime(?, '+5 minutes')
+        """
+
+        cursor.execute(query, (parent_start_time, parent_start_time))
+        result = cursor.fetchone()
+        count = result[0] if result else 0
+
+        conn.close()
+        logger.debug(f"Found {count} child spikes for parent event {parent_event_id}")
+        return count
+
+    except Exception as e:
+        logger.warning(f"Error counting child spikes: {e}")
+        return 0
+
+
+def update_parent_event(
+    db_path: str,
+    parent_event_id: str,
+    child_spike_count: int,
+    completion_time: str | None = None,
+) -> bool:
+    """
+    Update parent event with completion status and child spike count.
+
+    Updates agent_events table:
+    - status: "started" → "completed"
+    - child_spike_count: Count of spikes created by subagent
+    - output_summary: JSON with completion info
+
+    Args:
+        db_path: Path to SQLite database
+        parent_event_id: Parent event ID to update
+        child_spike_count: Number of child spikes created
+        completion_time: ISO8601 timestamp (optional, defaults to now)
+
+    Returns:
+        True if update successful, False otherwise
+    """
+    try:
+        if completion_time is None:
+            completion_time = datetime.now(timezone.utc).isoformat()
+
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        # Build output summary
+        output_summary = json.dumps(
+            {
+                "status": "completed",
+                "child_spike_count": child_spike_count,
+                "completion_time": completion_time,
+            }
+        )
+
+        # Update parent event
+        query = """
+            UPDATE agent_events
+            SET status = ?, child_spike_count = ?, output_summary = ?, updated_at = CURRENT_TIMESTAMP
+            WHERE event_id = ?
+        """
+
+        cursor.execute(
+            query,
+            ("completed", child_spike_count, output_summary, parent_event_id),
+        )
+
+        if cursor.rowcount == 0:
+            logger.warning(f"Parent event not found: {parent_event_id}")
+            conn.close()
+            return False
+
+        conn.commit()
+        conn.close()
+
+        logger.info(
+            f"Updated parent event {parent_event_id}: "
+            f"status=completed, child_spike_count={child_spike_count}"
+        )
+        return True
+
+    except Exception as e:
+        logger.warning(f"Error updating parent event: {e}")
+        return False
+
+
+def get_parent_event_start_time(db_path: str, parent_event_id: str) -> str | None:
+    """
+    Get the start time of the parent event.
+
+    Used to set the time window for counting child spikes.
+
+    Args:
+        db_path: Path to SQLite database
+        parent_event_id: Parent event ID
+
+    Returns:
+        ISO8601 timestamp or None if not found
+    """
+    try:
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        query = "SELECT timestamp FROM agent_events WHERE event_id = ?"
+        cursor.execute(query, (parent_event_id,))
+        result = cursor.fetchone()
+
+        conn.close()
+        return result[0] if result else None
+
+    except Exception as e:
+        logger.warning(f"Error getting parent event start time: {e}")
+        return None
+
+
+def get_parent_event_from_db(db_path: str) -> str | None:
+    """
+    Query database for the most recent task_delegation event.
+
+    Used when HTMLGRAPH_PARENT_EVENT environment variable is not available
+    (due to inter-process communication limitations).
+
+    Args:
+        db_path: Path to SQLite database
+
+    Returns:
+        Parent event ID (evt-XXXXX) or None if not found
+    """
+    try:
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        # Query for the most recent task_delegation with status='started'
+        # This is the task that spawned the current subagent
+        query = """
+            SELECT event_id FROM agent_events
+            WHERE event_type = 'task_delegation'
+            AND status = 'started'
+            ORDER BY timestamp DESC
+            LIMIT 1
+        """
+
+        cursor.execute(query)
+        result = cursor.fetchone()
+        conn.close()
+
+        if result:
+            parent_event_id: str = result[0]
+            logger.debug(
+                f"Found parent task_delegation from database: {parent_event_id}"
+            )
+            return parent_event_id
+
+        logger.debug("No active task_delegation found in database")
+        return None
+
+    except Exception as e:
+        logger.warning(f"Error querying for parent event: {e}")
+        return None
+
+
+def handle_subagent_stop(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Handle SubagentStop hook event.
+
+    When a subagent completes, updates the parent event with:
+    1. Completion status
+    2. Count of spikes created during subagent execution
+    3. Completion timestamp
+
+    This closes the parent-child event trace and enables dashboard visualization
+    of the complete delegation hierarchy.
+
+    Args:
+        hook_input: Hook input data from Claude Code
+
+    Returns:
+        Response: {"continue": True} with optional context
+    """
+    # Try to get parent event ID from environment (set by PreToolUse hook)
+    parent_event_id = get_parent_event_id()
+
+    # If not available in environment, query database
+    # (environment variables may not be inherited across subagent process boundary)
+    # Get project directory and database path (reuse for both env and db lookup)
+    db_path = None
+    try:
+        from htmlgraph.config import get_database_path
+
+        cwd = hook_input.get("cwd", os.getcwd())
+        db_path = str(get_database_path(cwd))
+
+        if not Path(db_path).exists():
+            logger.warning(f"Database not found: {db_path}")
+            return {"continue": True}
+
+    except Exception as e:
+        logger.warning(f"Error resolving database path: {e}")
+        return {"continue": True}
+
+    # If parent event ID not in environment, query database
+    if not parent_event_id:
+        logger.debug("Parent event ID not in environment, querying database...")
+        try:
+            parent_event_id = get_parent_event_from_db(db_path)
+        except Exception as e:
+            logger.debug(f"Could not query database for parent event: {e}")
+
+    if not parent_event_id:
+        logger.debug(
+            "No parent event ID found (env or db), skipping subagent stop tracking"
+        )
+        return {"continue": True}
+
+    # Get parent event start time
+    parent_start_time = get_parent_event_start_time(db_path, parent_event_id)
+    if not parent_start_time:
+        logger.warning(f"Could not find parent event: {parent_event_id}")
+        return {"continue": True}
+
+    # Count child spikes
+    child_spike_count = count_child_spikes(db_path, parent_event_id, parent_start_time)
+
+    # Update parent event with completion info
+    completion_time = datetime.now(timezone.utc).isoformat()
+    success = update_parent_event(
+        db_path,
+        parent_event_id,
+        child_spike_count,
+        completion_time,
+    )
+
+    if success:
+        # Clear parent event from environment
+        os.environ.pop("HTMLGRAPH_PARENT_EVENT", None)
+        os.environ.pop("HTMLGRAPH_SUBAGENT_TYPE", None)
+
+        logger.info(
+            f"Subagent stop recorded: parent_event={parent_event_id}, "
+            f"child_spikes={child_spike_count}"
+        )
+
+        return {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "SubagentStop",
+                "additionalContext": (
+                    f"Task delegation completed: {child_spike_count} spike(s) created"
+                ),
+            },
+        }
+
+    return {"continue": True}
+
+
+def main() -> None:
+    """Hook entry point for script wrapper."""
+    # Check if tracking is disabled
+    if os.environ.get("HTMLGRAPH_DISABLE_TRACKING") == "1":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Handle subagent stop
+    result = handle_subagent_stop(hook_input)
+
+    # Output response
+    print(json.dumps(result))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

htmlgraph/hooks/task_enforcer.py

@@ -9,6 +9,7 @@ Architecture:
 - Checks if prompt already includes save instructions
 - Auto-injects SDK save template if missing
 - Returns updatedInput with modified prompt
+- Tracks parent session context and nesting depth (Phase 2)
 
 Usage:
     from htmlgraph.hooks.task_enforcer import enforce_task_saving
@@ -17,6 +18,7 @@ Usage:
     # Returns: {"continue": True, "hookSpecificOutput": {"updatedInput": {...}}}
 """
 
+import os
 from typing import Any
 
 
@@ -124,8 +126,95 @@ def enforce_task_saving(tool_name: str, tool_params: dict[str, Any]) -> dict[str
     if not prompt:
         return {"continue": True}
 
+    # Phase 2: Track parent session context and increment nesting depth
+    parent_session = os.environ.get("HTMLGRAPH_PARENT_SESSION")
+    parent_agent = os.environ.get("HTMLGRAPH_PARENT_AGENT", "claude-code")
+    nesting_depth = int(os.environ.get("HTMLGRAPH_NESTING_DEPTH", "0"))
+    current_session = os.environ.get("HTMLGRAPH_SESSION_ID", "")
+
+    # Record delegation event in database
+    try:
+        import uuid
+
+        from htmlgraph.db.schema import HtmlGraphDB
+
+        db = HtmlGraphDB()
+        db.connect()
+
+        # Extract to_agent from subagent_type (e.g., "haiku" -> "haiku", "gemini-spawner" -> "gemini-spawner")
+        to_agent = tool_params.get("subagent_type", "unknown")
+        task_description = tool_params.get("description", "Unnamed task")
+
+        # Determine session ID, using current > parent > auto-generated
+        session_id = (
+            current_session or parent_session or f"session-{uuid.uuid4().hex[:8]}"
+        )
+
+        # Ensure session exists before recording delegation (handles FK constraints)
+        db._ensure_session_exists(session_id, parent_agent)
+
+        # Record the delegation event
+        db.record_delegation_event(
+            from_agent=parent_agent,
+            to_agent=to_agent,
+            task_description=task_description,
+            session_id=session_id,
+            context={
+                "nesting_depth": nesting_depth,
+                "prompt_preview": prompt[:200] if prompt else "",
+            },
+        )
+
+        db.close()
+    except Exception:
+        # Graceful degradation - continue even if delegation tracking fails
+        pass
+
+    # Track Task invocation as activity (if parent session exists)
+    task_activity_id = None
+    if parent_session:
+        try:
+            from htmlgraph import SDK
+
+            sdk = SDK(agent=parent_agent, parent_session=parent_session)
+
+            # Track Task invocation
+            entry = sdk.track_activity(
+                tool="Task",
+                summary=f"Task invoked: {tool_params.get('description', 'Unnamed task')[:100]}",
+                payload={
+                    "subagent_type": tool_params.get("subagent_type"),
+                    "description": tool_params.get("description"),
+                    "prompt_preview": prompt[:200] if prompt else "",
+                    "nesting_depth": nesting_depth,
+                },
+                success=True,
+            )
+
+            if entry:
+                task_activity_id = entry.id
+
+        except Exception:
+            # Graceful degradation - continue even if tracking fails
+            pass
+
+    # Increment nesting depth for child
+    new_depth = nesting_depth + 1
+
+    # Set parent activity and increment depth in environment
+    if task_activity_id:
+        os.environ["HTMLGRAPH_PARENT_ACTIVITY"] = task_activity_id
+
+    os.environ["HTMLGRAPH_NESTING_DEPTH"] = str(new_depth)
+
+    # Warn about runaway recursion
+    warning = ""
+    if new_depth > 3:
+        warning = f"\n⚠️  Warning: Nesting depth exceeds 3 levels (depth={new_depth}). Consider flattening task hierarchy."
+
     # Check if save instructions already present
     if has_save_instructions(prompt):
+        # Even if save instructions exist, we still need to update environment
         return {"continue": True}
 
     # Detect subagent type from prompt context
@@ -146,15 +235,21 @@ def enforce_task_saving(tool_name: str, tool_params: dict[str, Any]) -> dict[str
     updated_params = tool_params.copy()
     updated_params["prompt"] = modified_prompt
 
+    # Build context message
+    context_msg = (
+        f"📝 Auto-injected HtmlGraph save instructions into Task prompt. "
+        f"Subagent will be reminded to save findings using SDK.spikes. "
+        f"(depth={new_depth}, parent={parent_session[:12] if parent_session else 'none'})"
+    )
+    if warning:
+        context_msg += warning
+
     # Return response with updatedInput
     return {
         "continue": True,
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "updatedInput": updated_params,
-            "additionalContext": (
-                "📝 Auto-injected HtmlGraph save instructions into Task prompt. "
-                "Subagent will be reminded to save findings using SDK.spikes."
-            ),
+            "additionalContext": context_msg,
         },
     }