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

htmlgraph/hooks/orchestrator_reflector.py

@@ -0,0 +1,223 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
+"""
+Orchestrator Reflection Module
+
+Detects when Claude executes Python code directly via Bash and provides
+a gentle reflection prompt to encourage delegation to subagents.
+
+This helps reinforce orchestrator patterns:
+- Delegation over direct execution
+- Parallel Task() calls for efficiency
+- Work item tracking for all efforts
+
+Usage:
+    from htmlgraph.hooks.orchestrator_reflector import orchestrator_reflect
+
+    # In a posttooluse hook
+    hook_input = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "uv run pytest"}
+    }
+    result = orchestrator_reflect(hook_input)
+    # Returns: {"continue": True, "hookSpecificOutput": {...}}
+"""
+
+import re
+from typing import Any, TypedDict
+
+
+class HookSpecificOutput(TypedDict):
+    """Hook-specific output structure."""
+
+    hookEventName: str
+    additionalContext: str
+
+
+class HookResponse(TypedDict):
+    """Hook response structure."""
+
+    continue_: bool
+    hookSpecificOutput: HookSpecificOutput | None
+
+
+# Python execution patterns to detect
+PYTHON_EXECUTION_PATTERNS = [
+    r"\buv\s+run\b",  # uv run <anything>
+    r"\bpython\s+-c\b",  # python -c "code"
+    r"\bpython\s+[\w/.-]+\.py\b",  # python script.py
+    r"\bpython\s+-m\s+\w+",  # python -m module
+    r"\bpytest\b",  # pytest
+    r"\bpython3\s+",  # python3 command
+]
+
+# Commands to exclude from detection
+EXCLUDED_COMMAND_PREFIXES = ("git ", " git ", "ls ", "cat ", "grep ", "find ")
+
+
+def is_python_execution(command: str) -> bool:
+    """
+    Detect if a bash command is executing Python code.
+
+    Patterns to detect:
+    - uv run <script>
+    - python -c <code>
+    - python <script>
+    - pytest
+    - python -m <module>
+
+    Excludes:
+    - git commands (even if they mention python)
+    - simple tool calls that happen to have "python" in path
+
+    Args:
+        command: The bash command to analyze
+
+    Returns:
+        True if the command executes Python code
+    """
+    # Normalize command
+    cmd = command.strip().lower()
+
+    # Exclude git commands entirely
+    if cmd.startswith("git ") or " git " in cmd:
+        return False
+
+    # Exclude simple file operations
+    if cmd.startswith(EXCLUDED_COMMAND_PREFIXES):
+        return False
+
+    # Check for Python execution patterns
+    for pattern in PYTHON_EXECUTION_PATTERNS:
+        if re.search(pattern, cmd):
+            return True
+
+    return False
+
+
+def should_reflect(hook_input: dict[str, Any]) -> tuple[bool, str]:
+    """
+    Check if we should show reflection prompt.
+
+    Args:
+        hook_input: The hook input data containing tool name and tool input
+
+    Returns:
+        (should_show, command_preview) tuple where:
+        - should_show: True if reflection should be shown
+        - command_preview: Preview of the command (first 60 chars)
+    """
+    tool_name = hook_input.get("tool_name", "")
+
+    # Only check Bash tool usage
+    if tool_name != "Bash":
+        return False, ""
+
+    # Get the command
+    tool_input = hook_input.get("tool_input", {})
+    command = tool_input.get("command", "")
+
+    if not command:
+        return False, ""
+
+    # Check if it's Python execution
+    if is_python_execution(command):
+        # Create a preview of the command (first 60 chars)
+        preview = command[:60].replace("\n", " ")
+        if len(command) > 60:
+            preview += "..."
+        return True, preview
+
+    return False, ""
+
+
+def build_reflection_message(command_preview: str) -> str:
+    """
+    Build the reflection message for orchestrator.
+
+    This should be:
+    - Gentle and non-blocking
+    - Encourage reflection without being preachy
+    - Point to specific alternatives
+
+    Args:
+        command_preview: Preview of the executed command
+
+    Returns:
+        The formatted reflection message
+    """
+    return f"""ORCHESTRATOR REFLECTION: You executed code directly.
+
+Command: {command_preview}
+
+Ask yourself:
+- Could this have been delegated to a subagent?
+- Would parallel Task() calls have been faster?
+- Is a work item tracking this effort?
+
+Continue, but consider delegation for similar future tasks."""
+
+
+def orchestrator_reflect(tool_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Main API function for orchestrator reflection.
+
+    Analyzes tool usage and provides reflection feedback when direct
+    Python execution is detected.
+
+    Args:
+        tool_input: Hook input containing tool_name and tool_input fields
+
+    Returns:
+        Hook response dict with continue=True and optional hookSpecificOutput
+
+    Example:
+        >>> hook_input = {
+        ...     "tool_name": "Bash",
+        ...     "tool_input": {"command": "uv run pytest"}
+        ... }
+        >>> result = orchestrator_reflect(hook_input)
+        >>> result["continue"]
+        True
+        >>> "hookSpecificOutput" in result
+        True
+    """
+    # Check if we should reflect
+    should_show, command_preview = should_reflect(tool_input)
+
+    # Build response
+    response: dict[str, Any] = {"continue": True}
+
+    if should_show:
+        reflection = build_reflection_message(command_preview)
+        response["hookSpecificOutput"] = {
+            "hookEventName": "PostToolUse",
+            "additionalContext": reflection,
+        }
+
+    return response
+
+
+def main() -> None:
+    """Hook entry point for script wrapper."""
+    import json
+    import os
+    import sys
+
+    # Check if tracking is disabled
+    if os.environ.get("HTMLGRAPH_DISABLE_TRACKING") == "1":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Run reflection logic
+    response = orchestrator_reflect(hook_input)
+
+    # Output JSON response
+    print(json.dumps(response))

htmlgraph/hooks/post-checkout.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+#
+# HtmlGraph Post-Checkout Hook
+# Logs branch switches / checkouts for continuity tracking
+#
+
+set +e
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$PROJECT_ROOT" || exit 0
+
+if [ ! -d ".htmlgraph" ]; then
+  exit 0
+fi
+
+OLD_HEAD="$1"
+NEW_HEAD="$2"
+FLAG="$3"
+
+if ! command -v htmlgraph &> /dev/null; then
+  if command -v python3 &> /dev/null; then
+    python3 -m htmlgraph.git_events checkout "$OLD_HEAD" "$NEW_HEAD" "$FLAG" &> /dev/null &
+  fi
+  exit 0
+fi
+
+htmlgraph git-event checkout "$OLD_HEAD" "$NEW_HEAD" "$FLAG" &> /dev/null &
+exit 0

htmlgraph/hooks/post-commit.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+#
+# HtmlGraph Post-Commit Hook
+# Logs Git commit events for agent-agnostic continuity tracking
+#
+
+set +e
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$PROJECT_ROOT" || exit 0
+
+if [ ! -d ".htmlgraph" ]; then
+  exit 0
+fi
+
+if ! command -v htmlgraph &> /dev/null; then
+  if command -v python3 &> /dev/null; then
+    python3 -m htmlgraph.git_events commit &> /dev/null &
+  fi
+  exit 0
+fi
+
+htmlgraph git-event commit &> /dev/null &
+exit 0

htmlgraph/hooks/post-merge.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+#
+# HtmlGraph Post-Merge Hook
+# Logs successful merges for continuity tracking
+#
+
+set +e
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$PROJECT_ROOT" || exit 0
+
+if [ ! -d ".htmlgraph" ]; then
+  exit 0
+fi
+
+SQUASH_FLAG="$1"
+
+if ! command -v htmlgraph &> /dev/null; then
+  if command -v python3 &> /dev/null; then
+    python3 -m htmlgraph.git_events merge "$SQUASH_FLAG" &> /dev/null &
+  fi
+  exit 0
+fi
+
+htmlgraph git-event merge "$SQUASH_FLAG" &> /dev/null &
+exit 0

htmlgraph/hooks/post_tool_use_failure.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+import logging
+
+logger = logging.getLogger(__name__)
+
+"""
+PostToolUseFailure Hook - Automatic Error Tracking and Debug Spike Creation
+
+This hook is triggered when tool executions fail, enabling:
+- Error logging to .htmlgraph/errors.jsonl
+- Pattern detection for recurring errors (3+ occurrences)
+- Automatic debug spike creation for investigation
+- Error context preservation for debugging
+
+CRITICAL REQUIREMENTS:
+- MUST exit with code 0 (exit 1 blocks Claude)
+- MUST execute quickly (< 1 second)
+- MUST use file-based output (not stdout)
+- MUST handle all exceptions gracefully
+"""
+
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+def run(hook_input: dict[str, Any]) -> dict[str, Any]:
+    """
+    Handle tool execution failures.
+
+    Args:
+        hook_input: Hook input containing:
+            - name: Tool name that failed
+            - result: Tool result (may contain error field)
+            - session_id: Current session ID
+
+    Returns:
+        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
+        # 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 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" and result:
+            result_str = str(result).lower()
+            if any(
+                indicator in result_str
+                for indicator in ["error", "failed", "exception"]
+            ):
+                error_msg = str(result)[:500]  # Truncate to 500 chars
+
+        # Track error in file-based storage
+        error_log = Path(".htmlgraph/errors.jsonl")
+        error_log.parent.mkdir(parents=True, exist_ok=True)
+
+        error_entry = {
+            "timestamp": datetime.now().isoformat(),
+            "tool": tool_name,
+            "error": error_msg,
+            "session_id": session_id,
+        }
+
+        with open(error_log, "a") as f:
+            f.write(json.dumps(error_entry) + "\n")
+
+        # Check for error patterns (same error 3+ times)
+        if should_create_debug_spike(tool_name, error_msg, error_log):
+            create_debug_spike(tool_name, error_msg, error_log)
+
+        # Return success (don't block Claude)
+        return {"continue": True}
+
+    except Exception as e:
+        # Never raise - log and continue
+        logger.warning(f"PostToolUseFailure hook error: {e}")
+        return {"continue": True}
+
+
+def should_create_debug_spike(tool: str, error: str, log_path: Path) -> bool:
+    """
+    Check if this error has occurred 3+ times.
+
+    Args:
+        tool: Tool name that failed
+        error: Error message
+        log_path: Path to errors.jsonl
+
+    Returns:
+        True if error occurred 3+ times, False otherwise
+    """
+    if not log_path.exists():
+        return False
+
+    count = 0
+    # Use first 100 chars of error for pattern matching
+    error_signature = error[:100]
+
+    with open(log_path) as f:
+        for line in f:
+            try:
+                entry = json.loads(line)
+                if entry.get("tool") == tool and error_signature in entry.get(
+                    "error", ""
+                ):
+                    count += 1
+                    if count >= 3:
+                        return True
+            except Exception:
+                continue
+    return False
+
+
+def create_debug_spike(tool: str, error: str, log_path: Path) -> None:
+    """
+    Auto-create debug spike for recurring error.
+
+    Args:
+        tool: Tool name that failed
+        error: Error message
+        log_path: Path to errors.jsonl
+    """
+    try:
+        from htmlgraph import SDK
+
+        sdk = SDK(agent="error-tracker")
+
+        # Get recent occurrences
+        occurrences = []
+        error_signature = error[:100]
+        with open(log_path) as f:
+            for line in f:
+                try:
+                    entry = json.loads(line)
+                    if entry.get("tool") == tool and error_signature in entry.get(
+                        "error", ""
+                    ):
+                        occurrences.append(entry)
+                except Exception:
+                    continue
+
+        # Check if spike already exists for this error
+        spike_marker = Path(".htmlgraph/.error-spikes.json")
+        existing_spikes = {}
+        if spike_marker.exists():
+            try:
+                with open(spike_marker) as f:
+                    existing_spikes = json.load(f)
+            except Exception:
+                pass
+
+        # Create unique key for this error
+        error_key = f"{tool}:{error_signature}"
+        if error_key in existing_spikes:
+            # Already created spike for this error
+            return
+
+        # Create debug spike
+        spike = (
+            sdk.spikes.create(f"Recurring Error: {tool}")
+            .set_spike_type("technical")
+            .set_findings(
+                f"""
+## Recurring Tool Failure Detected
+
+**Tool**: {tool}
+**Occurrences**: {len(occurrences)}
+**First Seen**: {occurrences[0]["timestamp"] if occurrences else "unknown"}
+**Last Seen**: {occurrences[-1]["timestamp"] if occurrences else "unknown"}
+
+### Error Message
+```
+{error}
+```
+
+### Recent Occurrences
+{chr(10).join(f"- {o['timestamp']}: {o.get('session_id', 'unknown')}" for o in occurrences[-5:])}
+
+### Recommended Actions
+1. Review error message for root cause
+2. Check if this is a known issue in the codebase
+3. Search GitHub issues if Claude Code related
+4. Fix underlying issue or add error handling
+5. Test fix to ensure error doesn't recur
+
+### Debugging Resources
+- `.htmlgraph/errors.jsonl` - Full error log
+- `DEBUGGING.md` - Systematic debugging guide
+- `/doctor` - System diagnostics
+- `claude --debug` - Verbose output
+            """
+            )
+            .save()
+        )
+
+        # Record that we created a spike for this error
+        existing_spikes[error_key] = {
+            "spike_id": spike.id,
+            "created": datetime.now().isoformat(),
+            "occurrences": len(occurrences),
+        }
+        with open(spike_marker, "w") as f:
+            json.dump(existing_spikes, f, indent=2)
+
+        logger.warning(f"Created debug spike: {spike.id}")
+
+    except Exception as e:
+        logger.warning(f"Failed to create debug spike: {e}")
+
+
+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)
+
+    # Read tool input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Run hook
+    result = run(hook_input)
+
+    # Output response
+    print(json.dumps(result))
+    sys.exit(0)  # Always exit 0
+
+
+if __name__ == "__main__":
+    main()