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

htmlgraph/hooks/post_tool_use_handler.py

@@ -0,0 +1,257 @@
+"""
+PostToolUse Enhancement - Duration Calculation and Tool Trace Updates
+
+This module handles the PostToolUse hook event and updates tool traces with:
+1. Execution end time (when the tool completed)
+2. Duration in milliseconds (end_time - start_time)
+3. Tool output (result of the tool execution)
+4. Status (Ok or Error)
+5. Error message (if status is Error)
+
+The module correlates with PreToolUse via tool_use_id environment variable
+and gracefully handles missing pre-events (logs warning, continues).
+
+Design:
+- Query tool_traces for matching tool_use_id
+- Get start_time from pre-event
+- Calculate duration_ms (end_time - start_time)
+- Update tool_traces with: end_time, duration_ms, tool_output, status, error_message
+- Handle missing pre-event gracefully (log warning, continue)
+- Non-blocking - errors don't prevent tool execution continuation
+"""
+
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+from htmlgraph.db.schema import HtmlGraphDB
+
+logger = logging.getLogger(__name__)
+
+
+def calculate_duration(start_time_iso: str, end_time_iso: str) -> int:
+    """
+    Calculate duration in milliseconds between two ISO8601 UTC timestamps.
+
+    Args:
+        start_time_iso: ISO8601 UTC timestamp from PreToolUse (e.g., "2025-01-07T12:34:56.789000+00:00")
+        end_time_iso: ISO8601 UTC timestamp (now, e.g., "2025-01-07T12:34:57.123000+00:00")
+
+    Returns:
+        duration_ms: Integer milliseconds between timestamps (accurate within 1ms)
+
+    Raises:
+        ValueError: If timestamps cannot be parsed
+        TypeError: If inputs are not strings
+    """
+    try:
+        # Parse ISO8601 timestamps (handles timezone-aware datetimes)
+        start_dt = datetime.fromisoformat(start_time_iso.replace("Z", "+00:00"))
+        end_dt = datetime.fromisoformat(end_time_iso.replace("Z", "+00:00"))
+
+        # Calculate difference and convert to milliseconds
+        delta = end_dt - start_dt
+        duration_ms = int(delta.total_seconds() * 1000)
+
+        return duration_ms
+    except (ValueError, AttributeError, TypeError) as e:
+        logger.warning(f"Error calculating duration: {e}")
+        raise
+
+
+def update_tool_trace(
+    tool_use_id: str,
+    tool_output: dict[str, Any] | None,
+    status: str,
+    error_message: str | None = None,
+) -> bool:
+    """
+    Update tool_traces table with execution end event.
+
+    Updates an existing tool trace (created by PreToolUse) with:
+    - end_time: Current UTC timestamp
+    - duration_ms: Milliseconds between start and end
+    - tool_output: Result of tool execution (JSON)
+    - status: 'Ok' or 'Error'
+    - error_message: Error details if status='Error'
+
+    Args:
+        tool_use_id: Correlation ID from PreToolUse event (from environment)
+        tool_output: Tool execution result (dict, will be JSON serialized)
+        status: 'Ok' or 'Error'
+        error_message: Error details if status='Error'
+
+    Returns:
+        True if update successful, False otherwise
+
+    Workflow:
+    1. Query tool_traces for matching tool_use_id
+    2. Get start_time from pre-event
+    3. Calculate duration_ms (end_time - start_time)
+    4. Update tool_traces with: end_time, duration_ms, tool_output, status, error_message
+    5. Handle missing pre-event gracefully (log warning, continue)
+    """
+    try:
+        # Connect to database
+        db = HtmlGraphDB()
+
+        if not db.connection:
+            db.connect()
+
+        cursor = db.connection.cursor()  # type: ignore[union-attr]
+
+        # Query tool_traces for matching tool_use_id
+        cursor.execute(
+            """
+            SELECT tool_use_id, start_time FROM tool_traces
+            WHERE tool_use_id = ?
+        """,
+            (tool_use_id,),
+        )
+
+        row = cursor.fetchone()
+
+        if not row:
+            # Missing pre-event - log warning but continue (graceful degradation)
+            logger.warning(
+                f"Could not find start event for tool_use_id={tool_use_id}. "
+                f"PreToolUse event may not have completed. Skipping duration update."
+            )
+            db.disconnect()
+            return False
+
+        # Get start_time from pre-event
+        start_time_iso = row[1]
+
+        # Calculate end_time (now in UTC)
+        end_time_iso = datetime.now(timezone.utc).isoformat()
+
+        # Calculate duration_ms
+        try:
+            duration_ms = calculate_duration(start_time_iso, end_time_iso)
+        except (ValueError, TypeError) as e:
+            logger.warning(
+                f"Could not calculate duration for tool_use_id={tool_use_id}: {e}. "
+                f"Using None for duration."
+            )
+            duration_ms = None
+
+        # Validate status
+        valid_statuses = {"Ok", "Error", "completed", "failed", "timeout"}
+        if status not in valid_statuses:
+            logger.warning(
+                f"Invalid status '{status}' for tool_use_id={tool_use_id}. "
+                f"Using 'Ok' as default."
+            )
+            status = "Ok"
+
+        # JSON serialize tool_output
+        tool_output_json = None
+        if tool_output:
+            try:
+                tool_output_json = json.dumps(tool_output)
+            except (TypeError, ValueError) as e:
+                logger.warning(
+                    f"Could not JSON serialize tool_output for "
+                    f"tool_use_id={tool_use_id}: {e}"
+                )
+                tool_output_json = json.dumps(
+                    {"error": str(e), "output": str(tool_output)}
+                )
+
+        # Update tool_traces with: end_time, duration_ms, tool_output, status, error_message
+        cursor.execute(
+            """
+            UPDATE tool_traces
+            SET end_time = ?, duration_ms = ?, tool_output = ?,
+                status = ?, error_message = ?
+            WHERE tool_use_id = ?
+        """,
+            (
+                end_time_iso,
+                duration_ms,
+                tool_output_json,
+                status,
+                error_message,
+                tool_use_id,
+            ),
+        )
+
+        if not db.connection:
+            db.connect()
+
+        db.connection.commit()  # type: ignore[union-attr]
+
+        logger.debug(
+            f"Updated tool trace: tool_use_id={tool_use_id}, "
+            f"duration_ms={duration_ms}, status={status}"
+        )
+
+        db.disconnect()
+        return True
+
+    except Exception as e:
+        # Log error but don't block
+        logger.error(f"Error updating tool trace for tool_use_id={tool_use_id}: {e}")
+        return False
+
+
+def get_tool_use_id_from_context() -> str | None:
+    """
+    Get tool_use_id from environment (set by PreToolUse hook).
+
+    Returns:
+        tool_use_id string or None if not set
+    """
+    return os.environ.get("HTMLGRAPH_TOOL_USE_ID")
+
+
+def determine_status_from_response(
+    tool_response: dict[str, Any] | None,
+) -> tuple[str, str | None]:
+    """
+    Determine status (Ok/Error) and error message from tool response.
+
+    Analyzes tool response to determine if execution was successful.
+    Returns (status, error_message) tuple.
+
+    Args:
+        tool_response: Tool execution response (dict)
+
+    Returns:
+        (status, error_message) where:
+        - status: 'Ok' or 'Error'
+        - error_message: Error details if Error, else None
+    """
+    if not tool_response:
+        return ("Ok", None)
+
+    if not isinstance(tool_response, dict):
+        return ("Ok", None)
+
+    # Check for explicit error indicators
+    # Bash tool: non-empty stderr
+    stderr = tool_response.get("stderr", "")
+    if stderr and isinstance(stderr, str) and stderr.strip():
+        return ("Error", f"stderr: {stderr[:500]}")
+
+    # Explicit error field
+    error_field = tool_response.get("error")
+    if error_field and str(error_field).strip():
+        return ("Error", str(error_field)[:500])
+
+    # success=false flag
+    if tool_response.get("success") is False:
+        reason = tool_response.get("reason", "Unknown error")
+        return ("Error", str(reason)[:500])
+
+    # status field indicating failure
+    status_field = tool_response.get("status")
+    if status_field and status_field.lower() in {"error", "failed", "failed"}:
+        reason = tool_response.get("message", "Unknown error")
+        return ("Error", str(reason)[:500])
+
+    # Default to success
+    return ("Ok", None)

htmlgraph/hooks/posttooluse.py

@@ -0,0 +1,408 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
+"""
+Unified PostToolUse Hook - Parallel Execution of Multiple Tasks
+
+This module provides a unified PostToolUse hook that runs multiple tasks
+in parallel using asyncio:
+1. Event tracking - logs tool usage to session events
+2. Orchestrator reflection - provides delegation suggestions
+3. Task validation - validates task results
+4. Error tracking - logs errors and auto-creates debug spikes
+5. Debugging suggestions - suggests resources when errors detected
+6. CIGS analysis - cost accounting and reinforcement for delegation
+
+Architecture:
+- All tasks run simultaneously via asyncio.gather()
+- Error tracking logs to .htmlgraph/errors.jsonl
+- Auto-creates debug spikes after 3+ similar errors
+- Returns combined response with all feedback
+
+Performance:
+- ~40-50% faster than sequential execution
+- Single Python process (no subprocess overhead)
+- Parallel execution maximizes throughput
+"""
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from htmlgraph.cigs import CIGSPostToolAnalyzer
+from htmlgraph.hooks.event_tracker import track_event
+from htmlgraph.hooks.orchestrator_reflector import orchestrator_reflect
+from htmlgraph.hooks.post_tool_use_failure import run as track_error
+from htmlgraph.hooks.task_validator import validate_task_results
+
+
+async def run_event_tracking(
+    hook_type: str, hook_input: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Run event tracking (async wrapper).
+
+    Args:
+        hook_type: "PostToolUse" or "Stop"
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        Event tracking response: {"continue": True, "hookSpecificOutput": {...}}
+    """
+    try:
+        loop = asyncio.get_event_loop()
+
+        # Run in thread pool since it involves I/O
+        return await loop.run_in_executor(
+            None,
+            track_event,
+            hook_type,
+            hook_input,
+        )
+    except Exception:
+        # Graceful degradation - allow on error
+        return {"continue": True}
+
+
+async def run_orchestrator_reflection(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Run orchestrator reflection (async wrapper).
+
+    Args:
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        Reflection response: {"continue": True, "hookSpecificOutput": {...}}
+    """
+    try:
+        loop = asyncio.get_event_loop()
+
+        # Run in thread pool
+        return await loop.run_in_executor(
+            None,
+            orchestrator_reflect,
+            hook_input,
+        )
+    except Exception:
+        # Graceful degradation - allow on error
+        return {"continue": True}
+
+
+async def run_task_validation(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Run task result validation (async wrapper).
+
+    Args:
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        Validation response: {"continue": True, "hookSpecificOutput": {...}}
+    """
+    try:
+        loop = asyncio.get_event_loop()
+
+        tool_name = hook_input.get("name", "") or hook_input.get("tool_name", "")
+        tool_response = hook_input.get("result", {}) or hook_input.get(
+            "tool_response", {}
+        )
+
+        # Run task validation
+        return await loop.run_in_executor(
+            None,
+            validate_task_results,
+            tool_name,
+            tool_response,
+        )
+    except Exception:
+        # Graceful degradation - allow on error
+        return {"continue": True}
+
+
+async def run_error_tracking(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Track errors to .htmlgraph/errors.jsonl and auto-create debug spikes.
+
+    Only tracks ACTUAL errors, not responses containing the word "error".
+
+    Args:
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        Error tracking response: {"continue": True}
+    """
+    try:
+        loop = asyncio.get_event_loop()
+
+        # Check if this is an ACTUAL error
+        has_error = False
+        tool_response = hook_input.get("tool_response") or hook_input.get("result", {})
+
+        if isinstance(tool_response, dict):
+            # Bash: non-empty stderr indicates error
+            stderr = tool_response.get("stderr", "")
+            if stderr and isinstance(stderr, str) and stderr.strip():
+                has_error = True
+
+            # Explicit error field with content
+            error_field = tool_response.get("error")
+            if error_field and str(error_field).strip():
+                has_error = True
+
+            # success=false flag
+            if tool_response.get("success") is False:
+                has_error = True
+
+        # Only track if there's an actual error
+        if has_error:
+            return await loop.run_in_executor(
+                None,
+                track_error,
+                hook_input,
+            )
+
+        return {"continue": True}
+    except Exception:
+        # Graceful degradation - allow on error
+        return {"continue": True}
+
+
+async def suggest_debugging_resources(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Suggest debugging resources based on tool results.
+
+    Only triggers on ACTUAL errors, not on responses that happen to contain
+    the word "error" in their content.
+
+    Args:
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        Suggestion response: {"hookSpecificOutput": {"additionalContext": "..."}}
+    """
+    try:
+        tool_name = hook_input.get("name", "") or hook_input.get("tool_name", "")
+        tool_response = hook_input.get("result", {}) or hook_input.get(
+            "tool_response", {}
+        )
+
+        suggestions = []
+
+        # Check for ACTUAL errors (not just text containing "error")
+        has_actual_error = False
+
+        if isinstance(tool_response, dict):
+            # Bash: non-empty stderr indicates error
+            stderr = tool_response.get("stderr", "")
+            if stderr and isinstance(stderr, str) and stderr.strip():
+                has_actual_error = True
+
+            # Explicit error field
+            if tool_response.get("error"):
+                has_actual_error = True
+
+            # success=false flag
+            if tool_response.get("success") is False:
+                has_actual_error = True
+
+        if has_actual_error:
+            suggestions.append("⚠️ Error detected in tool response")
+            suggestions.append("Debugging resources:")
+            suggestions.append("  📚 DEBUGGING.md - Systematic debugging guide")
+            suggestions.append("  🔬 Researcher agent - Research error patterns")
+            suggestions.append("  🐛 Debugger agent - Root cause analysis")
+            suggestions.append("  Built-in: /doctor, /hooks, claude --debug")
+
+        # Check for Task tool without save evidence
+        if tool_name == "Task":
+            result_text = str(tool_response).lower()
+            save_indicators = [".save()", "spike", "htmlgraph", ".create("]
+            if not any(ind in result_text for ind in save_indicators):
+                suggestions.append("💡 Task completed - remember to document findings")
+                suggestions.append(
+                    "  See DEBUGGING.md for research documentation patterns"
+                )
+
+        if suggestions:
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": "\n".join(suggestions),
+                }
+            }
+
+        return {}
+    except Exception:
+        # Graceful degradation - no suggestions on error
+        return {}
+
+
+async def run_cigs_analysis(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Run CIGS cost accounting and reinforcement analysis.
+
+    Args:
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        CIGS analysis response: {"hookSpecificOutput": {...}}
+    """
+    try:
+        loop = asyncio.get_event_loop()
+
+        # Extract tool info
+        tool_name = hook_input.get("name", "") or hook_input.get("tool_name", "")
+        tool_params = hook_input.get("input", {}) or hook_input.get("tool_input", {})
+        tool_response = hook_input.get("result", {}) or hook_input.get(
+            "tool_response", {}
+        )
+
+        # Initialize CIGS analyzer
+        graph_dir = Path.cwd() / ".htmlgraph"
+        analyzer = CIGSPostToolAnalyzer(graph_dir)
+
+        # Run analysis in executor (may involve I/O)
+        return await loop.run_in_executor(
+            None,
+            analyzer.analyze,
+            tool_name,
+            tool_params,
+            tool_response,
+        )
+    except Exception:
+        # Graceful degradation - allow on error
+        return {}
+
+
+async def posttooluse_hook(
+    hook_type: str, hook_input: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Unified PostToolUse hook - runs tracking, reflection, validation, error tracking, debugging suggestions, and CIGS analysis in parallel.
+
+    Args:
+        hook_type: "PostToolUse" or "Stop"
+        hook_input: Hook input with tool execution details
+
+    Returns:
+        Claude Code standard format:
+        {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "Combined feedback",
+                "systemMessage": "Warnings/alerts"
+            }
+        }
+    """
+    # Run all six in parallel using asyncio.gather
+    (
+        event_response,
+        reflection_response,
+        validation_response,
+        error_tracking_response,
+        debug_suggestions,
+        cigs_response,
+    ) = await asyncio.gather(
+        run_event_tracking(hook_type, hook_input),
+        run_orchestrator_reflection(hook_input),
+        run_task_validation(hook_input),
+        run_error_tracking(hook_input),
+        suggest_debugging_resources(hook_input),
+        run_cigs_analysis(hook_input),
+    )
+
+    # Combine responses (all should return continue=True)
+    # Event tracking is async and shouldn't block
+    # Reflection provides optional guidance
+    # Validation provides warnings but doesn't block
+
+    # Collect all guidance and messages
+    guidance_parts = []
+    system_messages = []
+
+    # Event tracking guidance (e.g., drift warnings)
+    if "hookSpecificOutput" in event_response:
+        ctx = event_response["hookSpecificOutput"].get("additionalContext", "")
+        if ctx:
+            guidance_parts.append(ctx)
+
+    # Orchestrator reflection
+    if "hookSpecificOutput" in reflection_response:
+        ctx = reflection_response["hookSpecificOutput"].get("additionalContext", "")
+        if ctx:
+            guidance_parts.append(ctx)
+
+    # Task validation feedback
+    if "hookSpecificOutput" in validation_response:
+        ctx = validation_response["hookSpecificOutput"].get("additionalContext", "")
+        if ctx:
+            guidance_parts.append(ctx)
+
+        # Task validation may provide systemMessage for warnings
+        sys_msg = validation_response["hookSpecificOutput"].get("systemMessage", "")
+        if sys_msg:
+            system_messages.append(sys_msg)
+
+    # Debugging suggestions
+    if "hookSpecificOutput" in debug_suggestions:
+        ctx = debug_suggestions["hookSpecificOutput"].get("additionalContext", "")
+        if ctx:
+            guidance_parts.append(ctx)
+
+    # CIGS analysis (cost accounting and reinforcement)
+    if "hookSpecificOutput" in cigs_response:
+        ctx = cigs_response["hookSpecificOutput"].get("additionalContext", "")
+        if ctx:
+            guidance_parts.append(ctx)
+
+    # Build unified response
+    response: dict[str, Any] = {"continue": True}  # PostToolUse never blocks
+
+    if guidance_parts or system_messages:
+        response["hookSpecificOutput"] = {
+            "hookEventName": "PostToolUse",
+        }
+
+        if guidance_parts:
+            response["hookSpecificOutput"]["additionalContext"] = "\n".join(
+                guidance_parts
+            )
+
+        if system_messages:
+            response["hookSpecificOutput"]["systemMessage"] = "\n\n".join(
+                system_messages
+            )
+
+    return response
+
+
+def main() -> None:
+    """Hook entry point for script wrapper."""
+    # Check environment override
+    if os.environ.get("HTMLGRAPH_DISABLE_TRACKING") == "1":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Determine hook type from environment
+    hook_type = os.environ.get("HTMLGRAPH_HOOK_TYPE", "PostToolUse")
+
+    # Read tool input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Run hook with parallel execution
+    result = asyncio.run(posttooluse_hook(hook_type, hook_input))
+
+    # Output response
+    print(json.dumps(result))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()