htmlgraph 0.24.2__py3-none-any.whl → 0.26.1__py3-none-any.whl

htmlgraph/hooks/subagent_stop.py

@@ -0,0 +1,309 @@
+"""
+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 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
+    """
+    # Get parent event ID from environment
+    parent_event_id = get_parent_event_id()
+
+    if not parent_event_id:
+        logger.debug("No parent event ID found, skipping subagent stop tracking")
+        return {"continue": True}
+
+    # Get project directory and database path
+    try:
+        cwd = hook_input.get("cwd", os.getcwd())
+        graph_dir = Path(cwd) / ".htmlgraph"
+        db_path = str(graph_dir / "index.sqlite")
+
+        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}
+
+    # 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

@@ -130,6 +130,45 @@ def enforce_task_saving(tool_name: str, tool_params: dict[str, Any]) -> dict[str
     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

htmlgraph/hooks/validator.py

@@ -79,7 +79,7 @@ def load_tool_history() -> list[dict]:
             data = json.loads(TOOL_HISTORY_FILE.read_text())
 
             # Handle both formats: {"history": [...]} and [...] (legacy)
-            if isinstance(data, dict):
+            if isinstance(data, dict):  # type: ignore[arg-type]
                 data = data.get("history", [])
 
             # Filter to last hour only
@@ -149,7 +149,7 @@ def detect_optimal_pattern(tool: str, history: list[dict]) -> str | None:
     return OPTIMAL_PATTERNS.get(pair)
 
 
-def get_pattern_guidance(tool: str, history: list[dict]) -> dict:
+def get_pattern_guidance(tool: str, history: list[dict]) -> dict[str, Any]:
     """Get guidance based on tool patterns."""
     # Check for anti-patterns first
     anti_pattern = detect_anti_pattern(tool, history)
@@ -192,7 +192,7 @@ def get_session_health_hint(history: list[dict]) -> str | None:
     return None
 
 
-def load_validation_config() -> dict:
+def load_validation_config() -> dict[str, Any]:
     """Load validation config with defaults."""
     config_path = (
         Path(__file__).parent.parent.parent.parent.parent
@@ -218,7 +218,9 @@ def load_validation_config() -> dict:
     }
 
 
-def is_always_allowed(tool: str, params: dict, config: dict) -> bool:
+def is_always_allowed(
+    tool: str, params: dict[str, Any], config: dict[str, Any]
+) -> bool:
     """Check if tool is always allowed (read-only operations)."""
     # Always-allow tools
     if tool in config.get("always_allow", {}).get("tools", []):
@@ -234,7 +236,7 @@ def is_always_allowed(tool: str, params: dict, config: dict) -> bool:
     return False
 
 
-def is_direct_htmlgraph_write(tool: str, params: dict) -> tuple[bool, str]:
+def is_direct_htmlgraph_write(tool: str, params: dict[str, Any]) -> tuple[bool, str]:
     """Check if attempting direct write to .htmlgraph/ (always denied)."""
     if tool not in ["Write", "Edit", "Delete", "NotebookEdit"]:
         return False, ""
@@ -246,7 +248,7 @@ def is_direct_htmlgraph_write(tool: str, params: dict) -> tuple[bool, str]:
     return False, ""
 
 
-def is_sdk_command(tool: str, params: dict, config: dict) -> bool:
+def is_sdk_command(tool: str, params: dict[str, Any], config: dict[str, Any]) -> bool:
     """Check if Bash command is an SDK command."""
     if tool != "Bash":
         return False
@@ -259,7 +261,9 @@ def is_sdk_command(tool: str, params: dict, config: dict) -> bool:
     return False
 
 
-def is_code_operation(tool: str, params: dict, config: dict) -> bool:
+def is_code_operation(
+    tool: str, params: dict[str, Any], config: dict[str, Any]
+) -> bool:
     """Check if operation modifies code."""
     # Direct file operations
     if tool in config.get("code_operations", {}).get("tools", []):
@@ -288,7 +292,7 @@ def get_active_work_item() -> dict | None:
         return None
 
 
-def check_orchestrator_violation(tool: str, params: dict) -> dict | None:
+def check_orchestrator_violation(tool: str, params: dict[str, Any]) -> dict | None:
     """
     Check if operation violates orchestrator mode rules.
 
@@ -363,8 +367,8 @@ def check_orchestrator_violation(tool: str, params: dict) -> dict | None:
 
 
 def validate_tool_call(
-    tool: str, params: dict, config: dict, history: list[dict]
-) -> dict:
+    tool: str, params: dict[str, Any], config: dict[str, Any], history: list[dict]
+) -> dict[str, Any]:
     """
     Validate tool call and return GUIDANCE with active learning.
 
@@ -375,7 +379,7 @@ def validate_tool_call(
         history: Tool usage history (from load_tool_history())
 
     Returns:
-        dict: {"decision": "allow" | "block", "guidance": "...", "suggestion": "...", ...}
+        dict[str, Any]: {"decision": "allow" | "block", "guidance": "...", "suggestion": "...", ...}
               All operations are ALLOWED unless blocked for safety reasons.
 
     Example:

htmlgraph/models.py

@@ -7,7 +7,7 @@ These models provide:
 - Lightweight context generation for AI agents
 """
 
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
 from typing import Any, Literal
@@ -15,6 +15,11 @@ from typing import Any, Literal
 from pydantic import BaseModel, Field
 
 
+def utc_now() -> datetime:
+    """Return current time as UTC-aware datetime."""
+    return datetime.now(timezone.utc)
+
+
 class WorkType(str, Enum):
     """
     Classification of work/activity type for events and sessions.
@@ -264,15 +269,15 @@ class Node(BaseModel):
         if edge.relationship not in self.edges:
             self.edges[edge.relationship] = []
         self.edges[edge.relationship].append(edge)
-        self.updated = datetime.now()
+        self.updated = utc_now()
 
     def complete_step(self, index: int, agent: str | None = None) -> bool:
         """Mark a step as completed."""
         if 0 <= index < len(self.steps):
             self.steps[index].completed = True
             self.steps[index].agent = agent
-            self.steps[index].timestamp = datetime.now()
-            self.updated = datetime.now()
+            self.steps[index].timestamp = utc_now()
+            self.updated = utc_now()
             return True
         return False
 
@@ -300,7 +305,7 @@ class Node(BaseModel):
         self.context_tokens_used += tokens_used
         self.context_peak_tokens = max(self.context_peak_tokens, peak_tokens)
         self.context_cost_usd += cost_usd
-        self.updated = datetime.now()
+        self.updated = utc_now()
 
     def context_stats(self) -> dict:
         """
@@ -831,9 +836,7 @@ class ContextSnapshot(BaseModel):
     def from_dict(cls, data: dict) -> "ContextSnapshot":
         """Create from dictionary."""
         return cls(
-            timestamp=datetime.fromisoformat(data["ts"])
-            if "ts" in data
-            else datetime.now(),
+            timestamp=datetime.fromisoformat(data["ts"]) if "ts" in data else utc_now(),
             input_tokens=data.get("in", 0),
             output_tokens=data.get("out", 0),
             cache_creation_tokens=data.get("cache_create", 0),
@@ -847,6 +850,48 @@ class ContextSnapshot(BaseModel):
         )
 
 
+class ErrorEntry(BaseModel):
+    """
+    An error record for session error tracking and debugging.
+
+    Stored inline within Session nodes for error analysis and debugging.
+    """
+
+    timestamp: datetime = Field(default_factory=datetime.now)
+    error_type: str  # Exception class name (ValueError, FileNotFoundError, etc.)
+    message: str  # Error message
+    traceback: str | None = None  # Full traceback for debugging
+    tool: str | None = None  # Tool that caused the error (Edit, Bash, etc.)
+    context: str | None = None  # Additional context information
+    session_id: str | None = None  # Session ID for cross-referencing
+    locals_dump: str | None = None  # JSON-serialized local variables at error point
+    stack_frames: list[dict[str, Any]] | None = (
+        None  # Structured stack frame information
+    )
+    command_args: dict[str, Any] | None = None  # Command arguments being executed
+    display_level: str = "minimal"  # Display level: minimal, verbose, or debug
+
+    def to_html(self) -> str:
+        """Convert error to HTML details element."""
+        attrs = [
+            f'data-ts="{self.timestamp.isoformat()}"',
+            f'data-error-type="{self.error_type}"',
+        ]
+        if self.tool:
+            attrs.append(f'data-tool="{self.tool}"')
+
+        summary = f"<span class='error-type'>{self.error_type}</span>: {self.message}"
+        details = ""
+        if self.traceback:
+            details = f"<pre class='traceback'>{self.traceback}</pre>"
+
+        return f"<details class='error-item' {' '.join(attrs)}><summary>{summary}</summary>{details}</details>"
+
+    def to_context(self) -> str:
+        """Lightweight context for AI agents."""
+        return f"[{self.timestamp.strftime('%H:%M:%S')}] ERROR {self.error_type}: {self.message}"
+
+
 class ActivityEntry(BaseModel):
     """
     A lightweight activity log entry for high-frequency events.
@@ -975,20 +1020,52 @@ class Session(BaseModel):
     }
     """
 
+    # Error handling (Phase 1B)
+    error_log: list[ErrorEntry] = Field(default_factory=list)
+    """Error records for this session with full tracebacks for debugging."""
+
     def add_activity(self, entry: ActivityEntry) -> None:
         """Add an activity entry to the log."""
         self.activity_log.append(entry)
         self.event_count += 1
-        self.last_activity = datetime.now()
+        self.last_activity = utc_now()
 
         # Track features worked on
         if entry.feature_id and entry.feature_id not in self.worked_on:
             self.worked_on.append(entry.feature_id)
 
+    def add_error(
+        self,
+        error_type: str,
+        message: str,
+        traceback: str | None = None,
+        tool: str | None = None,
+        context: str | None = None,
+    ) -> None:
+        """
+        Add an error entry to the error log.
+
+        Args:
+            error_type: Exception class name (ValueError, FileNotFoundError, etc.)
+            message: Error message
+            traceback: Full traceback for debugging
+            tool: Tool that caused the error (Edit, Bash, etc.)
+            context: Additional context information
+        """
+        error = ErrorEntry(
+            error_type=error_type,
+            message=message,
+            traceback=traceback,
+            tool=tool,
+            context=context,
+            session_id=self.id,
+        )
+        self.error_log.append(error)
+
     def end(self) -> None:
         """Mark session as ended."""
         self.status = "ended"
-        self.ended_at = datetime.now()
+        self.ended_at = utc_now()
 
     def record_context(
         self, snapshot: ContextSnapshot, sample_interval: int = 10
@@ -1461,6 +1538,25 @@ class Session(BaseModel):
             </table>
         </section>"""
 
+        # Build error log section
+        error_html = ""
+        if self.error_log:
+            error_items = "\n                ".join(
+                error.to_html() for error in self.error_log
+            )
+            error_html = f"""
+        <section data-error-log>
+            <h3>Errors ({len(self.error_log)})</h3>
+            <div class="error-log">
+                {error_items}
+            </div>
+            <style>
+                .error-item {{ margin: 10px 0; padding: 10px; border-left: 3px solid #ff6b6b; }}
+                .error-type {{ font-weight: bold; color: #ff6b6b; }}
+                .traceback {{ background: #f5f5f5; padding: 10px; overflow-x: auto; font-size: 0.9em; margin-top: 5px; }}
+            </style>
+        </section>"""
+
         title = self.title or f"Session {self.id}"
 
         return f'''<!DOCTYPE html>
@@ -1489,7 +1585,7 @@ class Session(BaseModel):
                 <span class="badge">{self.event_count} events</span>
             </div>
         </header>
-{edges_html}{handoff_html}{context_html}{patterns_html}{activity_html}
+{edges_html}{handoff_html}{context_html}{error_html}{patterns_html}{activity_html}
     </article>
 </body>
 </html>
@@ -2141,16 +2237,16 @@ class Todo(BaseModel):
     def start(self) -> "Todo":
         """Mark todo as in progress."""
         self.status = "in_progress"
-        self.started_at = datetime.now()
-        self.updated = datetime.now()
+        self.started_at = utc_now()
+        self.updated = utc_now()
         return self
 
     def complete(self, agent: str | None = None) -> "Todo":
         """Mark todo as completed."""
         self.status = "completed"
-        self.completed_at = datetime.now()
+        self.completed_at = utc_now()
         self.completed_by = agent
-        self.updated = datetime.now()
+        self.updated = utc_now()
 
         # Calculate duration if started
         if self.started_at: