htmlgraph 0.9.3__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

@@ -0,0 +1,255 @@
+"""
+Task Enforcer - Auto-inject HtmlGraph save instructions into Task prompts.
+
+This module provides PreToolUse enforcement for the Task tool, ensuring that
+subagent prompts include instructions to save their findings to HtmlGraph.
+
+Architecture:
+- Detects Task tool calls in PreToolUse hook
+- 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
+
+    result = enforce_task_saving(tool_name, tool_params)
+    # Returns: {"continue": True, "hookSpecificOutput": {"updatedInput": {...}}}
+"""
+
+import os
+from typing import Any
+
+
+def has_save_instructions(prompt: str) -> bool:
+    """
+    Check if prompt already includes HtmlGraph save instructions.
+
+    Args:
+        prompt: Task prompt to check
+
+    Returns:
+        True if save instructions are present, False otherwise
+    """
+    # Keywords that indicate save instructions are already present
+    save_keywords = [
+        "sdk",
+        "htmlgraph",
+        ".save()",
+        "spike",
+        "report results",
+        "save findings",
+        "track results",
+    ]
+
+    prompt_lower = prompt.lower()
+    return any(keyword in prompt_lower for keyword in save_keywords)
+
+
+def inject_save_instructions(prompt: str, subagent_type: str = "haiku") -> str:
+    """
+    Inject HtmlGraph save instructions into Task prompt.
+
+    Args:
+        prompt: Original task prompt
+        subagent_type: Type of subagent (default: "haiku")
+
+    Returns:
+        Modified prompt with save instructions appended
+    """
+    # Template to inject
+    save_template = f"""
+
+🔴 CRITICAL - Report Results to HtmlGraph:
+After completing your research/analysis, you MUST save your findings using:
+
+```python
+from htmlgraph import SDK
+sdk = SDK(agent='{subagent_type}')
+spike = sdk.spikes.create('Your Task Summary Here')
+spike.set_findings(\'\'\'
+# Your Comprehensive Findings
+
+## Summary
+[Brief overview of what you discovered]
+
+## Key Findings
+- [Finding 1]
+- [Finding 2]
+- [Finding 3]
+
+## Details
+[Detailed analysis, code examples, etc.]
+
+## Recommendations
+[Action items or next steps]
+\'\'\')
+spike.save()
+```
+
+IMPORTANT:
+- Replace 'Your Task Summary Here' with a concise description of your task
+- Include ALL relevant findings in the set_findings() call
+- This creates a permanent record that can be referenced later
+- The spike will be saved to .htmlgraph/spikes/ directory
+"""
+
+    return prompt + save_template
+
+
+def enforce_task_saving(tool_name: str, tool_params: dict[str, Any]) -> dict[str, Any]:
+    """
+    Enforce HtmlGraph result saving for Task tool calls.
+
+    Args:
+        tool_name: Name of the tool being called
+        tool_params: Tool parameters (includes "prompt" for Task)
+
+    Returns:
+        Hook response with updatedInput if modifications needed:
+        {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "updatedInput": {...},  # Modified tool_params
+                "additionalContext": "..."  # Optional guidance
+            }
+        }
+    """
+    # Only process Task tool calls
+    if tool_name != "Task":
+        return {"continue": True}
+
+    # Get prompt from tool params
+    prompt = tool_params.get("prompt", "")
+    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
+    prompt_lower = prompt.lower()
+    if "haiku" in prompt_lower:
+        subagent_type = "haiku"
+    elif "sonnet" in prompt_lower:
+        subagent_type = "sonnet"
+    elif "opus" in prompt_lower:
+        subagent_type = "opus"
+    else:
+        subagent_type = "haiku"  # Default to haiku for most subagents
+
+    # Inject save instructions
+    modified_prompt = inject_save_instructions(prompt, subagent_type)
+
+    # Create updated tool params
+    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": context_msg,
+        },
+    }