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

htmlgraph/hooks/event_tracker.py

@@ -2,11 +2,15 @@
 HtmlGraph Event Tracker Module
 
 Reusable event tracking logic for hook integrations.
-Provides session management, drift detection, and activity logging.
+Provides session management, drift detection, activity logging, and SQLite persistence.
 
 Public API:
     track_event(hook_type: str, tool_input: dict) -> dict
         Main entry point for tracking hook events (PostToolUse, Stop, UserPromptSubmit)
+
+Events are recorded to both:
+    - HTML files via SessionManager (existing)
+    - SQLite database via HtmlGraphDB (new - for dashboard queries)
 """
 
 import json
@@ -14,16 +18,25 @@ import os
 import re
 import subprocess
 import sys
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, cast
 
+from htmlgraph.db.schema import HtmlGraphDB
+from htmlgraph.ids import generate_id
 from htmlgraph.session_manager import SessionManager
 
 # Drift classification queue (stored in session directory)
 DRIFT_QUEUE_FILE = "drift-queue.json"
 # Active parent activity tracker (for Skill/Task invocations)
 PARENT_ACTIVITY_FILE = "parent-activity.json"
+# UserQuery event tracker (for parent-child linking) - DEPRECATED (use session-scoped files)
+USER_QUERY_EVENT_FILE = "user-query-event.json"
+
+
+def get_user_query_event_file(graph_dir: Path, session_id: str) -> Path:
+    """Get the session-scoped user query event file path."""
+    return graph_dir / f"user-query-event-{session_id}.json"
 
 
 def load_drift_config() -> dict:
@@ -77,7 +90,12 @@ def load_parent_activity(graph_dir: Path) -> dict:
                 # Clean up stale parent activities (older than 5 minutes)
                 if data.get("timestamp"):
                     ts = datetime.fromisoformat(data["timestamp"])
-                    if datetime.now() - ts > timedelta(minutes=5):
+                    # Use timezone-aware datetime for comparison
+                    now = datetime.now(timezone.utc)
+                    # Ensure ts is timezone-aware (handle both formats)
+                    if ts.tzinfo is None:
+                        ts = ts.replace(tzinfo=timezone.utc)
+                    if now - ts > timedelta(minutes=5):
                         return {}
                 return data
         except Exception:
@@ -97,7 +115,7 @@ def save_parent_activity(
                     {
                         "parent_id": parent_id,
                         "tool": tool,
-                        "timestamp": datetime.now().isoformat(),
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
                     },
                     f,
                 )
@@ -108,6 +126,63 @@ def save_parent_activity(
         print(f"Warning: Could not save parent activity: {e}", file=sys.stderr)
 
 
+def load_user_query_event(graph_dir: Path, session_id: str) -> str | None:
+    """
+    Load the active UserQuery event ID for parent-child linking.
+
+    Session-scoped: Each session maintains its own parent context via
+    user-query-event-{SESSION_ID}.json to support multiple concurrent
+    Claude windows in the same project.
+    """
+    path = get_user_query_event_file(graph_dir, session_id)
+    if path.exists():
+        try:
+            with open(path) as f:
+                data = cast(dict[Any, Any], json.load(f))
+                # Clean up stale UserQuery events (older than 10 minutes)
+                if data.get("timestamp"):
+                    ts = datetime.fromisoformat(data["timestamp"])
+                    now = datetime.now(timezone.utc)
+                    if ts.tzinfo is None:
+                        ts = ts.replace(tzinfo=timezone.utc)
+                    # UserQuery events expire after 10 minutes (conversation turn boundary)
+                    # This allows tool calls up to 10 minutes after a user query to be linked as children
+                    if now - ts > timedelta(minutes=10):
+                        return None
+                return data.get("event_id")
+        except Exception:
+            pass
+    return None
+
+
+def save_user_query_event(
+    graph_dir: Path, session_id: str, event_id: str | None
+) -> None:
+    """
+    Save the active UserQuery event ID for parent-child linking.
+
+    Session-scoped: Each session maintains its own parent context via
+    user-query-event-{SESSION_ID}.json to support multiple concurrent
+    Claude windows in the same project.
+    """
+    path = get_user_query_event_file(graph_dir, session_id)
+    try:
+        if event_id:
+            with open(path, "w") as f:
+                json.dump(
+                    {
+                        "event_id": event_id,
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
+                    },
+                    f,
+                )
+        else:
+            # Clear UserQuery event
+            path.unlink(missing_ok=True)
+    except Exception as e:
+        print(f"Warning: Could not save UserQuery event: {e}", file=sys.stderr)
+
+
 def load_drift_queue(graph_dir: Path, max_age_hours: int = 48) -> dict:
     """
     Load the drift queue from file and clean up stale entries.
@@ -199,7 +274,7 @@ def add_to_drift_queue(graph_dir: Path, activity: dict, config: dict) -> dict:
 
     queue["activities"].append(
         {
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "tool": activity.get("tool"),
             "summary": activity.get("summary"),
             "file_paths": activity.get("file_paths", []),
@@ -293,6 +368,40 @@ def resolve_project_path(cwd: str | None = None) -> str:
     return start_dir
 
 
+def detect_agent_from_environment() -> str:
+    """
+    Detect the agent/model name from environment variables.
+
+    Checks multiple environment variables in order of priority:
+    1. HTMLGRAPH_AGENT - Explicit agent name set by user
+    2. HTMLGRAPH_SUBAGENT_TYPE - For subagent sessions
+    3. CLAUDE_MODEL - Model name if exposed by Claude Code
+    4. ANTHROPIC_MODEL - Alternative model env var
+    5. HTMLGRAPH_PARENT_AGENT - Parent agent context
+
+    Falls back to 'claude-code' if no environment variable is set.
+
+    Returns:
+        Agent/model identifier string
+    """
+    # Check environment variables in priority order
+    env_vars = [
+        "HTMLGRAPH_AGENT",
+        "HTMLGRAPH_SUBAGENT_TYPE",
+        "CLAUDE_MODEL",
+        "ANTHROPIC_MODEL",
+        "HTMLGRAPH_PARENT_AGENT",
+    ]
+
+    for var in env_vars:
+        value = os.environ.get(var)
+        if value and value.strip():
+            return value.strip()
+
+    # Default fallback
+    return "claude-code"
+
+
 def extract_file_paths(tool_input: dict, tool_name: str) -> list[str]:
     """Extract file paths from tool input based on tool type."""
     paths = []
@@ -366,13 +475,153 @@ def format_tool_summary(
         url = tool_input.get("url", "")[:40]
         return f"WebFetch: {url}"
 
+    elif tool_name == "UserQuery":
+        # Extract the actual prompt text from the tool_input
+        prompt = str(tool_input.get("prompt", ""))
+        preview = prompt[:100].replace("\n", " ")
+        if len(prompt) > 100:
+            preview += "..."
+        return preview
+
     else:
         return f"{tool_name}: {str(tool_input)[:50]}"
 
 
+def record_event_to_sqlite(
+    db: HtmlGraphDB,
+    session_id: str,
+    tool_name: str,
+    tool_input: dict,
+    tool_response: dict,
+    is_error: bool,
+    file_paths: list[str] | None = None,
+    parent_event_id: str | None = None,
+    agent_id: str | None = None,
+    subagent_type: str | None = None,
+) -> str | None:
+    """
+    Record a tool call event to SQLite database for dashboard queries.
+
+    Args:
+        db: HtmlGraphDB instance
+        session_id: Session ID from HtmlGraph
+        tool_name: Name of the tool called
+        tool_input: Tool input parameters
+        tool_response: Tool response/result
+        is_error: Whether the tool call resulted in an error
+        file_paths: File paths affected by the tool
+        parent_event_id: Parent event ID if this is a child event
+        agent_id: Agent identifier (optional)
+        subagent_type: Subagent type for Task delegations (optional)
+
+    Returns:
+        event_id if successful, None otherwise
+    """
+    try:
+        event_id = generate_id("event")
+        input_summary = format_tool_summary(tool_name, tool_input, tool_response)
+
+        # Build output summary from tool response
+        output_summary = ""
+        if isinstance(tool_response, dict):
+            if is_error:
+                output_summary = tool_response.get("error", "error")[:200]
+            else:
+                # Extract summary from response
+                content = tool_response.get("content", tool_response.get("output", ""))
+                if isinstance(content, str):
+                    output_summary = content[:200]
+                elif isinstance(content, list):
+                    output_summary = f"{len(content)} items"
+                else:
+                    output_summary = "success"
+
+        # Build context metadata
+        context = {
+            "file_paths": file_paths or [],
+            "tool_input_keys": list(tool_input.keys()),
+            "is_error": is_error,
+        }
+
+        # Insert event to SQLite
+        success = db.insert_event(
+            event_id=event_id,
+            agent_id=agent_id or "claude-code",
+            event_type="tool_call",
+            session_id=session_id,
+            tool_name=tool_name,
+            input_summary=input_summary,
+            output_summary=output_summary,
+            context=context,
+            parent_event_id=parent_event_id,
+            cost_tokens=0,
+            subagent_type=subagent_type,
+        )
+
+        if success:
+            return event_id
+        return None
+
+    except Exception as e:
+        print(f"Warning: Could not record event to SQLite: {e}", file=sys.stderr)
+        return None
+
+
+def record_delegation_to_sqlite(
+    db: HtmlGraphDB,
+    session_id: str,
+    from_agent: str,
+    to_agent: str,
+    task_description: str,
+    task_input: dict,
+) -> str | None:
+    """
+    Record a Task() delegation to agent_collaboration table.
+
+    Args:
+        db: HtmlGraphDB instance
+        session_id: Session ID from HtmlGraph
+        from_agent: Agent delegating the task (usually 'orchestrator' or 'claude-code')
+        to_agent: Target subagent type (e.g., 'general-purpose', 'researcher')
+        task_description: Task description/prompt
+        task_input: Full task input parameters
+
+    Returns:
+        handoff_id if successful, None otherwise
+    """
+    try:
+        handoff_id = generate_id("handoff")
+
+        # Build context with task input
+        context = {
+            "task_input_keys": list(task_input.keys()),
+            "model": task_input.get("model"),
+            "temperature": task_input.get("temperature"),
+        }
+
+        # Insert delegation record
+        success = db.insert_collaboration(
+            handoff_id=handoff_id,
+            from_agent=from_agent,
+            to_agent=to_agent,
+            session_id=session_id,
+            handoff_type="delegation",
+            reason=task_description[:200],
+            context=context,
+        )
+
+        if success:
+            return handoff_id
+        return None
+
+    except Exception as e:
+        print(f"Warning: Could not record delegation to SQLite: {e}", file=sys.stderr)
+        return None
+
+
 def track_event(hook_type: str, hook_input: dict) -> dict:
     """
-    Track a hook event and log it to HtmlGraph.
+    Track a hook event and log it to HtmlGraph (both HTML files and SQLite).
 
     Args:
         hook_type: Type of hook event ("PostToolUse", "Stop", "UserPromptSubmit")
@@ -388,13 +637,24 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
     # Load drift configuration
     drift_config = load_drift_config()
 
-    # Initialize SessionManager
+    # Initialize SessionManager and SQLite DB
     try:
         manager = SessionManager(graph_dir)
     except Exception as e:
         print(f"Warning: Could not initialize SessionManager: {e}", file=sys.stderr)
         return {"continue": True}
 
+    # Initialize SQLite database for event recording
+    db = None
+    try:
+        db = HtmlGraphDB(str(graph_dir / "index.sqlite"))
+    except Exception as e:
+        print(f"Warning: Could not initialize SQLite database: {e}", file=sys.stderr)
+        # Continue without SQLite (graceful degradation)
+
+    # Detect agent from environment
+    detected_agent = detect_agent_from_environment()
+
     # Get active session ID
     active_session = manager.get_active_session()
     if not active_session:
@@ -402,7 +662,7 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
         try:
             active_session = manager.start_session(
                 session_id=None,
-                agent="claude-code",
+                agent=detected_agent,
                 title=f"Session {datetime.now().strftime('%Y-%m-%d %H:%M')}",
             )
         except Exception:
@@ -410,6 +670,50 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
 
     active_session_id = active_session.id
 
+    # Ensure session exists in SQLite database (for foreign key constraints)
+    if db:
+        try:
+            # Get attributes safely - MagicMock objects can cause SQLite binding errors
+            # When getattr is called on a MagicMock, it returns another MagicMock, not the default
+            def safe_getattr(obj: Any, attr: str, default: Any) -> Any:
+                """Get attribute safely, returning default for MagicMock/invalid values."""
+                try:
+                    val = getattr(obj, attr, default)
+                    # Check if it's a mock object (has _mock_name attribute)
+                    if hasattr(val, "_mock_name"):
+                        return default
+                    return val
+                except Exception:
+                    return default
+
+            is_subagent_raw = safe_getattr(active_session, "is_subagent", False)
+            is_subagent = (
+                bool(is_subagent_raw) if isinstance(is_subagent_raw, bool) else False
+            )
+
+            transcript_id = safe_getattr(active_session, "transcript_id", None)
+            transcript_path = safe_getattr(active_session, "transcript_path", None)
+            # Ensure strings or None, not mock objects
+            if transcript_id is not None and not isinstance(transcript_id, str):
+                transcript_id = None
+            if transcript_path is not None and not isinstance(transcript_path, str):
+                transcript_path = None
+
+            db.insert_session(
+                session_id=active_session_id,
+                agent_assigned=safe_getattr(active_session, "agent", None)
+                or detected_agent,
+                is_subagent=is_subagent,
+                transcript_id=transcript_id,
+                transcript_path=transcript_path,
+            )
+        except Exception as e:
+            # Session may already exist, that's OK - continue
+            print(
+                f"Debug: Could not insert session to SQLite (may already exist): {e}",
+                file=sys.stderr,
+            )
+
     # Handle different hook types
     if hook_type == "Stop":
         # Session is ending - track stop event
@@ -417,6 +721,18 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
             manager.track_activity(
                 session_id=active_session_id, tool="Stop", summary="Agent stopped"
             )
+
+            # Record to SQLite if available
+            if db:
+                record_event_to_sqlite(
+                    db=db,
+                    session_id=active_session_id,
+                    tool_name="Stop",
+                    tool_input={},
+                    tool_response={"content": "Agent stopped"},
+                    is_error=False,
+                    agent_id=detected_agent,
+                )
         except Exception as e:
             print(f"Warning: Could not track stop: {e}", file=sys.stderr)
         return {"continue": True}
@@ -432,6 +748,26 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
             manager.track_activity(
                 session_id=active_session_id, tool="UserQuery", summary=f'"{preview}"'
             )
+
+            # Record to SQLite if available and capture event_id for parent-child linking
+            user_query_event_id = None
+            if db:
+                user_query_event_id = record_event_to_sqlite(
+                    db=db,
+                    session_id=active_session_id,
+                    tool_name="UserQuery",
+                    tool_input={"prompt": prompt},
+                    tool_response={"content": "Query received"},
+                    is_error=False,
+                    agent_id=detected_agent,
+                )
+
+                # Store the UserQuery event_id for subsequent tool calls to use as parent
+                if user_query_event_id:
+                    save_user_query_event(
+                        graph_dir, active_session_id, user_query_event_id
+                    )
+
         except Exception as e:
             print(f"Warning: Could not track query: {e}", file=sys.stderr)
         return {"continue": True}
@@ -479,8 +815,8 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
 
         # Get drift thresholds from config
         drift_settings = drift_config.get("drift_detection", {})
-        warning_threshold = drift_settings.get("warning_threshold", 0.7)
-        auto_classify_threshold = drift_settings.get("auto_classify_threshold", 0.85)
+        warning_threshold = drift_settings.get("warning_threshold") or 0.7
+        auto_classify_threshold = drift_settings.get("auto_classify_threshold") or 0.85
 
         # Determine parent activity context
         parent_activity_state = load_parent_activity(graph_dir)
@@ -496,9 +832,23 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
             is_parent_tool = True
         else:
             is_parent_tool = False
-            # Check if there's an active parent context
-            if parent_activity_state.get("parent_id"):
-                parent_activity_id = parent_activity_state["parent_id"]
+            # Check environment variable FIRST for cross-process parent linking
+            # This is set by PreToolUse hook when Task() spawns a subagent
+            env_parent = os.environ.get("HTMLGRAPH_PARENT_EVENT")
+            if env_parent:
+                parent_activity_id = env_parent
+            # Next, check for UserQuery event as parent (for prompt-based grouping)
+            # UserQuery takes priority over parent_activity_json to ensure each conversation turn
+            # has its tool calls properly grouped together
+            else:
+                user_query_event_id = load_user_query_event(
+                    graph_dir, active_session_id
+                )
+                if user_query_event_id:
+                    parent_activity_id = user_query_event_id
+                # Fall back to parent-activity.json only if no UserQuery event (backward compatibility)
+                elif parent_activity_state.get("parent_id"):
+                    parent_activity_id = parent_activity_state["parent_id"]
 
         # Track the activity
         nudge = None
@@ -512,6 +862,41 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
                 parent_activity_id=parent_activity_id,
             )
 
+            # Record to SQLite if available
+            if db:
+                # Extract subagent_type for Task delegations
+                task_subagent_type = None
+                if tool_name == "Task":
+                    task_subagent_type = tool_input_data.get(
+                        "subagent_type", "general-purpose"
+                    )
+
+                record_event_to_sqlite(
+                    db=db,
+                    session_id=active_session_id,
+                    tool_name=tool_name,
+                    tool_input=tool_input_data,
+                    tool_response=tool_response,
+                    is_error=is_error,
+                    file_paths=file_paths if file_paths else None,
+                    parent_event_id=parent_activity_id,  # Link to parent event
+                    agent_id=detected_agent,
+                    subagent_type=task_subagent_type,
+                )
+
+            # If this was a Task() delegation, also record to agent_collaboration
+            if tool_name == "Task" and db:
+                subagent = tool_input_data.get("subagent_type", "general-purpose")
+                description = tool_input_data.get("description", "")
+                record_delegation_to_sqlite(
+                    db=db,
+                    session_id=active_session_id,
+                    from_agent=detected_agent,
+                    to_agent=subagent,
+                    task_description=description,
+                    task_input=tool_input_data,
+                )
+
             # If this was a parent tool, save its ID for subsequent activities
             if is_parent_tool and result:
                 save_parent_activity(graph_dir, result.id, tool_name)
@@ -524,7 +909,10 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
                 drift_score = result.drift_score
                 feature_id = getattr(result, "feature_id", "unknown")
 
-                if drift_score and drift_score >= auto_classify_threshold:
+                # Skip drift detection if no score available
+                if drift_score is None:
+                    pass  # No active features - can't calculate drift
+                elif drift_score >= auto_classify_threshold:
                     # High drift - add to classification queue
                     queue = add_to_drift_queue(
                         graph_dir,
@@ -598,7 +986,9 @@ Task tool with subagent_type="general-purpose", model="haiku", prompt:
 Or manually create a work item in .htmlgraph/ (bug, feature, spike, or chore)."""
 
                         # Mark classification as triggered
-                        queue["last_classification"] = datetime.now().isoformat()
+                        queue["last_classification"] = datetime.now(
+                            timezone.utc
+                        ).isoformat()
                         save_drift_queue(graph_dir, queue)
                     else:
                         nudge = f"Drift detected ({drift_score:.2f}): Activity queued for classification ({len(queue['activities'])}/{drift_settings.get('min_activities_before_classify', 3)} needed)."