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

htmlgraph/hooks/post_tool_use_failure.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 PostToolUseFailure Hook - Automatic Error Tracking and Debug Spike Creation
 
@@ -37,27 +41,48 @@ def run(hook_input: dict[str, Any]) -> dict[str, Any]:
         Standard hook response: {"continue": True}
     """
     try:
+        # DEBUG: Log raw hook input to understand structure
+        debug_log = Path(".htmlgraph/hook-debug.jsonl")
+        debug_log.parent.mkdir(parents=True, exist_ok=True)
+        with open(debug_log, "a") as f:
+            f.write(
+                json.dumps(
+                    {
+                        "raw_input": hook_input,
+                        "keys": list(hook_input.keys()),
+                        "ts": datetime.now().isoformat(),
+                    }
+                )
+                + "\n"
+            )
+
         # Extract error information from PostToolUse hook format
-        tool_name = hook_input.get("name", "unknown")
+        # Official PostToolUse uses: tool_name, tool_response
+        # Custom hooks may use: name, result
+        tool_name = hook_input.get("tool_name") or hook_input.get("name", "unknown")
         session_id = hook_input.get("session_id", "unknown")
 
         # Error message can be in different places depending on tool
         error_msg = "No error message"
 
-        # Check result field first (Bash, Read, etc.)
-        result = hook_input.get("result", {})
+        # Check tool_response field first (official PostToolUse format)
+        # Then check result field (custom hook format)
+        result = hook_input.get("tool_response") or hook_input.get("result", {})
         if isinstance(result, dict):
             if "error" in result:
                 error_msg = result["error"]
             elif "message" in result:
                 error_msg = result["message"]
+        elif isinstance(result, str):
+            # Sometimes the error is directly in the result as a string
+            error_msg = result
 
         # Fallback: check top-level error field
         if error_msg == "No error message" and "error" in hook_input:
             error_msg = hook_input["error"]
 
         # Last resort: stringify the result if it contains error indicators
-        if error_msg == "No error message":
+        if error_msg == "No error message" and result:
             result_str = str(result).lower()
             if any(
                 indicator in result_str
@@ -88,7 +113,7 @@ def run(hook_input: dict[str, Any]) -> dict[str, Any]:
 
     except Exception as e:
         # Never raise - log and continue
-        print(f"PostToolUseFailure hook error: {e}", file=sys.stderr)
+        logger.warning(f"PostToolUseFailure hook error: {e}")
         return {"continue": True}
 
 
@@ -217,10 +242,10 @@ def create_debug_spike(tool: str, error: str, log_path: Path) -> None:
         with open(spike_marker, "w") as f:
             json.dump(existing_spikes, f, indent=2)
 
-        print(f"Created debug spike: {spike.id}", file=sys.stderr)
+        logger.warning(f"Created debug spike: {spike.id}")
 
     except Exception as e:
-        print(f"Failed to create debug spike: {e}", file=sys.stderr)
+        logger.warning(f"Failed to create debug spike: {e}")
 
 
 def main() -> None:

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

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Unified PostToolUse Hook - Parallel Execution of Multiple Tasks
 
@@ -8,6 +12,7 @@ in parallel using asyncio:
 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()
@@ -25,8 +30,10 @@ 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
@@ -119,6 +126,8 @@ 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
 
@@ -128,23 +137,26 @@ async def run_error_tracking(hook_input: dict[str, Any]) -> dict[str, Any]:
     try:
         loop = asyncio.get_event_loop()
 
-        # Check if this is an error (check for error field or non-zero exit code)
+        # Check if this is an ACTUAL error
         has_error = False
-        tool_response = hook_input.get("result", {}) or hook_input.get(
-            "tool_response", {}
-        )
+        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
 
-        # Check for explicit error field
-        if "error" in tool_response or hook_input.get("error"):
-            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
 
-        # Check for error indicators in response text
-        response_text = str(tool_response).lower()
-        error_indicators = ["error", "failed", "exception", "traceback", "errno"]
-        if any(indicator in response_text for indicator in error_indicators):
-            has_error = True
+            # success=false flag
+            if tool_response.get("success") is False:
+                has_error = True
 
-        # Only track if there's an error
+        # Only track if there's an actual error
         if has_error:
             return await loop.run_in_executor(
                 None,
@@ -162,6 +174,9 @@ async def suggest_debugging_resources(hook_input: dict[str, Any]) -> dict[str, A
     """
     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
 
@@ -176,11 +191,24 @@ async def suggest_debugging_resources(hook_input: dict[str, Any]) -> dict[str, A
 
         suggestions = []
 
-        # Check for error indicators in response
-        response_text = str(tool_response).lower()
-        error_indicators = ["error", "failed", "exception", "traceback", "errno"]
+        # 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
 
-        if any(indicator in response_text for indicator in error_indicators):
+            # 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")
@@ -212,11 +240,48 @@ async def suggest_debugging_resources(hook_input: dict[str, Any]) -> dict[str, A
         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, and debugging suggestions in parallel.
+    Unified PostToolUse hook - runs tracking, reflection, validation, error tracking, debugging suggestions, and CIGS analysis in parallel.
 
     Args:
         hook_type: "PostToolUse" or "Stop"
@@ -233,19 +298,21 @@ async def posttooluse_hook(
             }
         }
     """
-    # Run all five in parallel using asyncio.gather
+    # 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)
@@ -286,6 +353,12 @@ async def posttooluse_hook(
         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