anvil-dev-framework 0.1.7 → 0.1.9

package/project/hooks/stop.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "python-dotenv",
+# ]
+# ///
+
+import argparse
+import json
+import os
+import sys
+import random
+import subprocess
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # dotenv is optional
+
+# Add global lib to path for agent_registry
+_global_lib = Path(__file__).parent.parent.parent / "global" / "lib"
+if _global_lib.exists():
+    sys.path.insert(0, str(_global_lib))
+
+try:
+    from agent_registry import deregister_agent
+    AGENT_REGISTRY_AVAILABLE = True
+except ImportError:
+    AGENT_REGISTRY_AVAILABLE = False
+
+
+def get_my_codename() -> str:
+    """Get this agent's codename (A1, A2, etc.) from registry.
+
+    Reads agent ID from local anvil-state.json, then looks up
+    the codename from the global agent registry.
+
+    Returns:
+        Codename like "A1" or empty string if not found.
+    """
+    try:
+        state_file = Path(".claude/anvil-state.json")
+        if not state_file.exists():
+            return ""
+
+        state = json.loads(state_file.read_text())
+        agent_id = state.get("session", {}).get("agentId", "")
+        if not agent_id:
+            return ""
+
+        registry_file = Path.home() / ".anvil" / "agents.json"
+        if registry_file.exists():
+            registry = json.loads(registry_file.read_text())
+            agent = registry.get("agents", {}).get(agent_id, {})
+            return agent.get("codename") or ""
+    except Exception:
+        pass
+    return ""
+
+
+def cleanup_agent_registration():
+    """Deregister agent from global registry on session stop (ANV-222).
+
+    This ensures the agent count stays accurate by immediately removing
+    the agent when the session ends, rather than waiting for stale cleanup.
+    """
+    if not AGENT_REGISTRY_AVAILABLE:
+        return
+
+    try:
+        # Read agent ID from anvil-state.json
+        state_file = Path(".claude/anvil-state.json")
+        if not state_file.exists():
+            return
+
+        state = json.loads(state_file.read_text())
+        agent_id = state.get("session", {}).get("agentId")
+        if agent_id:
+            deregister_agent(agent_id)
+    except Exception:
+        pass  # Fail silently
+
+
+def get_completion_messages():
+    """Return list of friendly completion messages."""
+    return [
+        "Work complete!",
+        "All done!",
+        "Task finished!",
+        "Job complete!",
+        "Ready for next task!"
+    ]
+
+
+def read_anvil_config():
+    """
+    Read Anvil framework configuration from .claude/anvil.config.json.
+
+    Returns:
+        dict: Config with autoRetro and autoHealthcheck settings, or defaults if missing.
+    """
+    defaults = {
+        "version": "1.0",
+        "autoRetro": False,
+        "autoHealthcheck": False
+    }
+
+    config_path = Path(os.getcwd()) / ".claude" / "anvil.config.json"
+
+    if not config_path.exists():
+        return defaults
+
+    try:
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+            # Merge with defaults to ensure all keys exist
+            return {**defaults, **config}
+    except (json.JSONDecodeError, IOError):
+        return defaults
+
+
+def get_auto_trigger_commands(config):
+    """
+    Determine which commands should be suggested based on config.
+
+    Args:
+        config: Dict with autoRetro and autoHealthcheck settings
+
+    Returns:
+        list: Commands to suggest running
+    """
+    commands = []
+
+    if config.get("autoHealthcheck", False):
+        commands.append("/healthcheck")
+
+    if config.get("autoRetro", False):
+        commands.append("/retro")
+
+    return commands
+
+
+def get_tts_script_path():
+    """
+    Determine which TTS script to use based on availability and API keys.
+    Priority order: MLX Audio (local) > ElevenLabs > OpenAI > pyttsx3
+    """
+    # Get current script directory and construct utils/tts path
+    script_dir = Path(__file__).parent
+    tts_dir = script_dir / "utils" / "tts"
+
+    # Check for MLX Audio (highest priority - fast, free, local)
+    mlx_script = tts_dir / "mlx_audio_tts.py"
+    if mlx_script.exists():
+        return str(mlx_script)
+
+    # Check for ElevenLabs API key
+    if os.getenv('ELEVENLABS_API_KEY'):
+        elevenlabs_script = tts_dir / "elevenlabs_tts.py"
+        if elevenlabs_script.exists():
+            return str(elevenlabs_script)
+
+    # Check for OpenAI API key
+    if os.getenv('OPENAI_API_KEY'):
+        openai_script = tts_dir / "openai_tts.py"
+        if openai_script.exists():
+            return str(openai_script)
+
+    # Fall back to pyttsx3 (no API key required)
+    pyttsx3_script = tts_dir / "pyttsx3_tts.py"
+    if pyttsx3_script.exists():
+        return str(pyttsx3_script)
+
+    return None
+
+
+def get_llm_completion_message():
+    """
+    Generate completion message using available LLM services.
+    Priority order: OpenAI > Anthropic > fallback to random message
+
+    Returns:
+        str: Generated or fallback completion message
+    """
+    # Get current script directory and construct utils/llm path
+    script_dir = Path(__file__).parent
+    llm_dir = script_dir / "utils" / "llm"
+
+    # Try OpenAI first (highest priority)
+    if os.getenv('OPENAI_API_KEY'):
+        oai_script = llm_dir / "oai.py"
+        if oai_script.exists():
+            try:
+                result = subprocess.run([
+                    "uv", "run", str(oai_script), "--completion"
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    return result.stdout.strip()
+            except (subprocess.TimeoutExpired, subprocess.SubprocessError):
+                pass
+
+    # Try Anthropic second
+    if os.getenv('ANTHROPIC_API_KEY'):
+        anth_script = llm_dir / "anth.py"
+        if anth_script.exists():
+            try:
+                result = subprocess.run([
+                    "uv", "run", str(anth_script), "--completion"
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    return result.stdout.strip()
+            except (subprocess.TimeoutExpired, subprocess.SubprocessError):
+                pass
+
+    # Fallback to random predefined message
+    messages = get_completion_messages()
+    return random.choice(messages)
+
+def announce_completion():
+    """Announce completion using the best available TTS service."""
+    try:
+        tts_script = get_tts_script_path()
+        if not tts_script:
+            return  # No TTS scripts available
+
+        # Get agent codename for identification (ANV-135)
+        codename = get_my_codename()
+        agent_prefix = f"Agent {codename[1:]}" if codename.startswith("A") else ""
+
+        # Get completion message (LLM-generated or fallback)
+        base_message = get_llm_completion_message()
+
+        # Prepend agent identifier if available
+        if agent_prefix:
+            completion_message = f"{agent_prefix}: {base_message}"
+        else:
+            completion_message = base_message
+
+        # Call the TTS script with the completion message
+        subprocess.run([
+            "uv", "run", tts_script, completion_message
+        ],
+        capture_output=True,  # Suppress output
+        timeout=10  # 10-second timeout
+        )
+
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, FileNotFoundError):
+        # Fail silently if TTS encounters issues
+        pass
+    except Exception:
+        # Fail silently for any other errors
+        pass
+
+
+def main():
+    try:
+        # Parse command line arguments
+        parser = argparse.ArgumentParser()
+        parser.add_argument('--chat', action='store_true', help='Copy transcript to chat.json')
+        # Note: --cleanup-agent flag removed in ANV-222; deregistration now always happens
+        args = parser.parse_args()
+
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+
+        # Extract required fields
+        session_id = input_data.get("session_id", "")
+        input_data.get("stop_hook_active", False)
+
+        # Ensure log directory exists
+        log_dir = os.path.join(os.getcwd(), "logs")
+        os.makedirs(log_dir, exist_ok=True)
+        log_path = os.path.join(log_dir, "stop.json")
+
+        # Read existing log data or initialize empty list
+        if os.path.exists(log_path):
+            with open(log_path, 'r') as f:
+                try:
+                    log_data = json.load(f)
+                except (json.JSONDecodeError, ValueError):
+                    log_data = []
+        else:
+            log_data = []
+
+        # Append new data
+        log_data.append(input_data)
+
+        # Write back to file with formatting
+        with open(log_path, 'w') as f:
+            json.dump(log_data, f, indent=2)
+
+        # ANV-222: Always deregister agent from global registry on stop
+        # This ensures accurate agent counts without waiting for stale cleanup
+        cleanup_agent_registration()
+
+        # Handle --chat switch
+        if args.chat and 'transcript_path' in input_data:
+            transcript_path = input_data['transcript_path']
+            if os.path.exists(transcript_path):
+                # Read .jsonl file and convert to JSON array
+                chat_data = []
+                try:
+                    with open(transcript_path, 'r') as f:
+                        for line in f:
+                            line = line.strip()
+                            if line:
+                                try:
+                                    chat_data.append(json.loads(line))
+                                except json.JSONDecodeError:
+                                    pass  # Skip invalid lines
+
+                    # Write to logs/chat.json
+                    chat_file = os.path.join(log_dir, 'chat.json')
+                    with open(chat_file, 'w') as f:
+                        json.dump(chat_data, f, indent=2)
+                except Exception:
+                    pass  # Fail silently
+
+        # Check for auto-trigger commands from anvil.config.json
+        config = read_anvil_config()
+        auto_commands = get_auto_trigger_commands(config)
+
+        if auto_commands:
+            # Output reminder for Claude to see
+            print("\n[Anvil Auto-Trigger]")
+            print("The following commands are configured to run at session end:")
+            for cmd in auto_commands:
+                print(f"  → {cmd}")
+            print("\nConsider running these commands before ending the session.")
+
+        # Announce completion via TTS
+        announce_completion()
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Handle JSON decode errors gracefully
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/project/hooks/subagent_start.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "python-dotenv",
+# ]
+# ///
+"""
+SubagentStart Hook
+
+Fires when a subagent begins execution. Enables:
+- Logging subagent invocations for observability
+- Injecting context specific to the subagent type
+- Tracking active agents for coordination
+
+Input Schema:
+{
+    "session_id": "string",
+    "agent_id": "string",
+    "agent_type": "string",
+    "tool_use_id": "string"
+}
+
+Output Schema (for context injection):
+{
+    "hookSpecificOutput": {
+        "hookEventName": "SubagentStart",
+        "additionalContext": "string"
+    }
+}
+
+Usage:
+    uv run .claude/hooks/subagent_start.py --log --inject-context
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from datetime import datetime
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # dotenv is optional
+
+
+# Context mapping: agent_type -> rules file
+# Add your custom agent types and their corresponding rules here
+CONTEXT_MAP = {
+    "security-code-reviewer": ".claude/rules/security-review.md",
+    "cross-layer-debugger": ".claude/rules/debugging.md",
+    # Add more mappings as needed:
+    # "api-reviewer": ".claude/rules/api-design.md",
+    # "test-writer": ".claude/rules/testing.md",
+}
+
+
+def log_subagent_start(input_data):
+    """
+    Log subagent start event to logs/subagent_start.json.
+
+    Creates a timestamped record of each subagent invocation for:
+    - Debugging and observability
+    - Tracking agent coordination patterns
+    - Auditing agent usage
+    """
+    log_dir = Path("logs")
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / 'subagent_start.json'
+
+    # Read existing log data or initialize empty list
+    if log_file.exists():
+        try:
+            with open(log_file, 'r') as f:
+                log_data = json.load(f)
+        except (json.JSONDecodeError, ValueError):
+            log_data = []
+    else:
+        log_data = []
+
+    # Append new entry with timestamp
+    log_data.append({
+        **input_data,
+        "timestamp": datetime.now().isoformat()
+    })
+
+    # Write back to file
+    with open(log_file, 'w') as f:
+        json.dump(log_data, f, indent=2)
+
+
+def inject_context(agent_type):
+    """
+    Inject context based on subagent type.
+
+    Reads rules files from .claude/rules/ directory and returns
+    their content to be injected into the subagent's context.
+
+    Args:
+        agent_type: The type/name of the subagent being invoked
+
+    Returns:
+        String content of the rules file, or None if not found
+    """
+    context_file = CONTEXT_MAP.get(agent_type)
+
+    if context_file:
+        context_path = Path(context_file)
+        if context_path.exists():
+            try:
+                with open(context_path, 'r') as f:
+                    return f.read()
+            except (IOError, OSError):
+                pass  # Fail silently if file can't be read
+
+    return None
+
+
+def register_agent(input_data):
+    """
+    Register agent in global registry for multi-agent coordination.
+
+    This is optional - used by Anvil HUD for tracking active agents.
+    Registry location: ~/.anvil/agents.json
+    """
+    try:
+        registry_dir = Path.home() / ".anvil"
+        registry_dir.mkdir(parents=True, exist_ok=True)
+        registry_file = registry_dir / "agents.json"
+
+        # Read existing registry
+        if registry_file.exists():
+            try:
+                with open(registry_file, 'r') as f:
+                    registry = json.load(f)
+            except (json.JSONDecodeError, ValueError):
+                registry = {"agents": []}
+        else:
+            registry = {"agents": []}
+
+        # Add new agent entry
+        agent_entry = {
+            "agent_id": input_data.get("agent_id", ""),
+            "agent_type": input_data.get("agent_type", ""),
+            "session_id": input_data.get("session_id", ""),
+            "tool_use_id": input_data.get("tool_use_id", ""),
+            "started_at": datetime.now().isoformat(),
+            "status": "running"
+        }
+
+        registry["agents"].append(agent_entry)
+        registry["last_updated"] = datetime.now().isoformat()
+
+        # Write back
+        with open(registry_file, 'w') as f:
+            json.dump(registry, f, indent=2)
+
+    except Exception:
+        pass  # Fail silently - registry is optional
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='SubagentStart hook - log and inject context for subagents'
+    )
+    parser.add_argument(
+        '--log',
+        action='store_true',
+        help='Log subagent start to logs/subagent_start.json'
+    )
+    parser.add_argument(
+        '--inject-context',
+        action='store_true',
+        help='Inject context from .claude/rules/ based on agent type'
+    )
+    parser.add_argument(
+        '--register',
+        action='store_true',
+        help='Register agent in global registry (~/.anvil/agents.json)'
+    )
+    args = parser.parse_args()
+
+    try:
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+
+        # Log subagent start if requested
+        if args.log:
+            log_subagent_start(input_data)
+
+        # Register in global registry if requested
+        if args.register:
+            register_agent(input_data)
+
+        # Inject context if requested
+        if args.inject_context:
+            agent_type = input_data.get('agent_type', '')
+            context = inject_context(agent_type)
+
+            if context:
+                # Output hook-specific response for context injection
+                output = {
+                    "hookSpecificOutput": {
+                        "hookEventName": "SubagentStart",
+                        "additionalContext": context
+                    }
+                }
+                print(json.dumps(output))
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Handle JSON decode errors gracefully
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()