anvil-dev-framework 0.1.7 → 0.1.9

package/project/hooks/session_start.py

@@ -0,0 +1,656 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "python-dotenv",
+# ]
+# ///
+
+import argparse
+import json
+import os
+import sys
+import subprocess
+import platform
+import hashlib
+import random
+import re
+from pathlib import Path
+from datetime import datetime, timezone
+
+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 register_agent as hud_register_agent
+    AGENT_REGISTRY_AVAILABLE = True
+except ImportError:
+    AGENT_REGISTRY_AVAILABLE = False
+
+# Doc coverage service for gap detection (ANV-218)
+try:
+    from doc_coverage_service import DocCoverageService
+    DOC_COVERAGE_AVAILABLE = True
+except ImportError:
+    DOC_COVERAGE_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 ""
+
+
+# Agent ID word lists for human-readable identifiers
+ADJECTIVES = [
+    "swift", "calm", "bold", "keen", "wise",
+    "warm", "cool", "fair", "bright", "quick",
+    "steady", "agile", "clever", "noble", "eager"
+]
+
+NOUNS = [
+    "falcon", "raven", "wolf", "bear", "hawk",
+    "fox", "owl", "lion", "tiger", "eagle",
+    "otter", "heron", "lynx", "stag", "crane"
+]
+
+
+def generate_agent_id():
+    """Generate a unique, human-readable agent ID.
+
+    Format: {adjective}-{noun}-{4char-hash}
+    Example: swift-falcon-a3f2
+    """
+    adjective = random.choice(ADJECTIVES)
+    noun = random.choice(NOUNS)
+
+    # Generate 4-char hash from timestamp + random for uniqueness
+    unique_str = f"{datetime.now().isoformat()}-{random.randint(0, 999999)}"
+    hash_suffix = hashlib.md5(unique_str.encode()).hexdigest()[:4]
+
+    return f"{adjective}-{noun}-{hash_suffix}"
+
+
+def update_coordination_file(agent_id, working_on="(starting up)"):
+    """Register agent in coordination.md Active Sessions table.
+
+    Args:
+        agent_id: The unique agent identifier
+        working_on: What the agent is working on (default: starting up)
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    coord_file = Path(".claude/coordination.md")
+
+    if not coord_file.exists():
+        return False
+
+    try:
+        content = coord_file.read_text()
+
+        # Find the Active Sessions table
+        # Pattern: table header followed by separator, then rows until empty line or ---
+        table_pattern = r'(\| Session ID \| Started \| Working On \| Status \|\n\|[-|]+\|)\n'
+        match = re.search(table_pattern, content)
+
+        if not match:
+            return False
+
+        # Create new row
+        started_time = datetime.now().strftime("%H:%M")
+        new_row = f"| {agent_id} | {started_time} | {working_on} | active |\n"
+
+        # Insert after table header
+        insert_pos = match.end()
+        updated_content = content[:insert_pos] + new_row + content[insert_pos:]
+
+        # Also add to Session Log
+        log_entry = f"[{datetime.now().strftime('%Y-%m-%d %H:%M')}] [{agent_id}]: started - session begin\n"
+
+        # Find "### Today" section and add entry after it
+        today_pattern = r'(### Today\n+)'
+        today_match = re.search(today_pattern, updated_content)
+        if today_match:
+            log_insert_pos = today_match.end()
+            updated_content = updated_content[:log_insert_pos] + log_entry + updated_content[log_insert_pos:]
+
+        coord_file.write_text(updated_content)
+        return True
+
+    except Exception:
+        return False
+
+
+def update_anvil_state(agent_id):
+    """Store agent ID in anvil-state.json.
+
+    Args:
+        agent_id: The unique agent identifier
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    state_file = Path(".claude/anvil-state.json")
+
+    try:
+        # Read existing state or create new
+        if state_file.exists():
+            state = json.loads(state_file.read_text())
+        else:
+            state = {
+                "version": "1.0",
+                "session": {},
+                "cache": {"git": {}},
+                "meta": {"createdAt": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")}
+            }
+
+        # Add agent info to session
+        state["session"]["agentId"] = agent_id
+        state["session"]["agentStartedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+        state["meta"]["updatedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+        # Write back
+        state_file.parent.mkdir(parents=True, exist_ok=True)
+        state_file.write_text(json.dumps(state, indent=2) + "\n")
+        return True
+
+    except Exception:
+        return False
+
+
+def register_agent():
+    """Register this session as an active agent.
+
+    Returns:
+        str: The generated agent ID, or None if registration failed
+    """
+    agent_id = generate_agent_id()
+
+    # Get current branch to include in "working on"
+    branch, _ = get_git_status()
+    working_on = f"branch: {branch}" if branch else "(starting up)"
+
+    # Update coordination file
+    coord_success = update_coordination_file(agent_id, working_on)
+
+    # Update anvil state
+    state_success = update_anvil_state(agent_id)
+
+    if coord_success or state_success:
+        return agent_id
+
+    return None
+
+
+def get_agent_id_from_state():
+    """Read agent ID from anvil-state.json.
+
+    Returns:
+        str: The agent ID, or None if not found
+    """
+    state_file = Path(".claude/anvil-state.json")
+
+    try:
+        if state_file.exists():
+            state = json.loads(state_file.read_text())
+            return state.get("session", {}).get("agentId")
+    except Exception:
+        pass
+
+    return None
+
+
+def remove_agent_from_coordination(agent_id):
+    """Remove agent from coordination.md Active Sessions table.
+
+    Args:
+        agent_id: The agent ID to remove
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    coord_file = Path(".claude/coordination.md")
+
+    if not coord_file.exists():
+        return False
+
+    try:
+        content = coord_file.read_text()
+
+        # Find and remove the agent's row from Active Sessions
+        # Pattern: | agent_id | ... | ... | ... |\n
+        row_pattern = rf'\| {re.escape(agent_id)} \|[^\n]+\|\n'
+        updated_content = re.sub(row_pattern, '', content)
+
+        if updated_content != content:
+            coord_file.write_text(updated_content)
+            return True
+
+        return False
+
+    except Exception:
+        return False
+
+
+def add_completion_log(agent_id, summary="session end"):
+    """Add completion entry to coordination.md Session Log.
+
+    Args:
+        agent_id: The agent ID
+        summary: Brief summary of what was done (default: "session end")
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    coord_file = Path(".claude/coordination.md")
+
+    if not coord_file.exists():
+        return False
+
+    try:
+        content = coord_file.read_text()
+
+        # Add completion log entry after "### Today"
+        log_entry = f"[{datetime.now().strftime('%Y-%m-%d %H:%M')}] [{agent_id}]: completed - {summary}\n"
+
+        today_pattern = r'(### Today\n+)'
+        match = re.search(today_pattern, content)
+
+        if match:
+            insert_pos = match.end()
+            updated_content = content[:insert_pos] + log_entry + content[insert_pos:]
+            coord_file.write_text(updated_content)
+            return True
+
+        return False
+
+    except Exception:
+        return False
+
+
+def clear_agent_from_state():
+    """Clear agent info from anvil-state.json.
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    state_file = Path(".claude/anvil-state.json")
+
+    try:
+        if state_file.exists():
+            state = json.loads(state_file.read_text())
+
+            # Remove agent-specific fields
+            session = state.get("session", {})
+            session.pop("agentId", None)
+            session.pop("agentStartedAt", None)
+
+            state["meta"]["updatedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+            state_file.write_text(json.dumps(state, indent=2) + "\n")
+            return True
+
+    except Exception:
+        pass
+
+    return False
+
+
+def deregister_agent(summary="session end"):
+    """Deregister this session's agent.
+
+    Args:
+        summary: Brief summary of what was accomplished (default: "session end")
+
+    Returns:
+        str: The agent ID that was deregistered, or None if no agent was registered
+    """
+    agent_id = get_agent_id_from_state()
+
+    if not agent_id:
+        return None
+
+    # Add completion log first (before removing from active)
+    add_completion_log(agent_id, summary)
+
+    # Remove from Active Sessions table
+    remove_agent_from_coordination(agent_id)
+
+    # Clear from anvil state
+    clear_agent_from_state()
+
+    return agent_id
+
+
+def log_session_start(input_data):
+    """Log session start event to logs directory."""
+    # Ensure logs directory exists
+    log_dir = Path("logs")
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / 'session_start.json'
+
+    # Read existing log data or initialize empty list
+    if log_file.exists():
+        with open(log_file, 'r') as f:
+            try:
+                log_data = json.load(f)
+            except (json.JSONDecodeError, ValueError):
+                log_data = []
+    else:
+        log_data = []
+
+    # Append the entire input data
+    log_data.append(input_data)
+
+    # Write back to file with formatting
+    with open(log_file, 'w') as f:
+        json.dump(log_data, f, indent=2)
+
+
+def get_git_status():
+    """Get current git status information."""
+    try:
+        # Get current branch
+        branch_result = subprocess.run(
+            ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        current_branch = branch_result.stdout.strip() if branch_result.returncode == 0 else "unknown"
+
+        # Get uncommitted changes count
+        status_result = subprocess.run(
+            ['git', 'status', '--porcelain'],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if status_result.returncode == 0:
+            changes = status_result.stdout.strip().split('\n') if status_result.stdout.strip() else []
+            uncommitted_count = len(changes)
+        else:
+            uncommitted_count = 0
+
+        return current_branch, uncommitted_count
+    except Exception:
+        return None, None
+
+
+def get_recent_issues():
+    """Get recent GitHub issues if gh CLI is available."""
+    try:
+        # Check if gh is available
+        gh_check = subprocess.run(['which', 'gh'], capture_output=True)
+        if gh_check.returncode != 0:
+            return None
+
+        # Get recent open issues
+        result = subprocess.run(
+            ['gh', 'issue', 'list', '--limit', '5', '--state', 'open'],
+            capture_output=True,
+            text=True,
+            timeout=10
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return None
+
+
+def load_development_context(source):
+    """Load relevant development context based on session source."""
+    context_parts = []
+
+    # Add timestamp
+    context_parts.append(f"Session started at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    context_parts.append(f"Session source: {source}")
+
+    # Add git information
+    branch, changes = get_git_status()
+    if branch:
+        context_parts.append(f"Git branch: {branch}")
+        if changes > 0:
+            context_parts.append(f"Uncommitted changes: {changes} files")
+
+    # Add doc coverage warnings if service is available (ANV-218)
+    if DOC_COVERAGE_AVAILABLE:
+        try:
+            service = DocCoverageService()
+            warnings = service.get_session_warnings(sensitivity="balanced")
+            if warnings:
+                context_parts.append(warnings)
+        except Exception:
+            pass  # Don't fail session start on doc coverage errors
+
+    # Load project-specific context files if they exist
+    context_files = [
+        ".claude/CONTEXT.md",
+        ".claude/TODO.md",
+        "TODO.md",
+        ".github/ISSUE_TEMPLATE.md"
+    ]
+
+    for file_path in context_files:
+        if Path(file_path).exists():
+            try:
+                with open(file_path, 'r') as f:
+                    content = f.read().strip()
+                    if content:
+                        context_parts.append(f"\n--- Content from {file_path} ---")
+                        context_parts.append(content[:1000])  # Limit to first 1000 chars
+            except Exception:
+                pass
+
+    # Add recent issues if available
+    issues = get_recent_issues()
+    if issues:
+        context_parts.append("\n--- Recent GitHub Issues ---")
+        context_parts.append(issues)
+
+    return "\n".join(context_parts)
+
+
+def main():
+    try:
+        # Parse command line arguments
+        parser = argparse.ArgumentParser()
+        parser.add_argument('--load-context', action='store_true',
+                          help='Load development context at session start')
+        parser.add_argument('--register-agent', action='store_true',
+                          help='Register agent in coordination.md and HUD registry')
+        parser.add_argument('--deregister-agent', action='store_true',
+                          help='Deregister agent from coordination.md (call on session end)')
+        parser.add_argument('--summary', type=str, default='session end',
+                          help='Summary for deregistration log (used with --deregister-agent)')
+        parser.add_argument('--announce', action='store_true',
+                          help='Announce session start via TTS')
+        args = parser.parse_args()
+
+        # Handle deregistration (doesn't require stdin input)
+        if args.deregister_agent:
+            agent_id = deregister_agent(args.summary)
+            if agent_id:
+                print(json.dumps({"success": True, "agentId": agent_id, "action": "deregistered"}))
+            else:
+                print(json.dumps({"success": False, "error": "No agent registered"}))
+            sys.exit(0)
+
+        # Read JSON input from stdin (for session start operations)
+        input_data = json.loads(sys.stdin.read())
+
+        # Extract fields
+        session_id = input_data.get('session_id', 'unknown')
+        source = input_data.get('source', 'unknown')  # "startup", "resume", or "clear"
+
+        # Log the session start event
+        log_session_start(input_data)
+
+        # Register agent in global HUD registry for multi-agent visibility
+        if args.register_agent and AGENT_REGISTRY_AVAILABLE:
+            try:
+                # Generate human-readable agent ID (swift-falcon-a3f2 style)
+                hud_agent_id = os.getenv("ANVIL_AGENT_ID", generate_agent_id())
+
+                # Extract model name from input data
+                model_info = input_data.get("model", {})
+                model_name = model_info.get("display_name", "Claude")
+                # Shorten model name
+                if "Opus" in model_name:
+                    model_name = "Opus"
+                elif "Sonnet" in model_name:
+                    model_name = "Sonnet"
+                elif "Haiku" in model_name:
+                    model_name = "Haiku"
+
+                # Get current project path
+                project_path = os.getcwd()
+
+                # Register in HUD registry (~/.anvil/agents.json)
+                hud_register_agent(
+                    agent_id=hud_agent_id,
+                    project=project_path,
+                    session_id=session_id,
+                    model=model_name
+                )
+
+                # Store HUD agent ID in anvil-state.json for sync script
+                state_file = Path(".claude/anvil-state.json")
+                try:
+                    if state_file.exists():
+                        state = json.loads(state_file.read_text())
+                    else:
+                        state = {"version": "1.0", "session": {}, "cache": {"git": {}}, "meta": {}}
+                    state["session"]["agentId"] = hud_agent_id
+                    state["meta"]["updatedAt"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+                    state_file.write_text(json.dumps(state, indent=2) + "\n")
+                except Exception:
+                    pass
+            except Exception:
+                pass  # HUD registration is optional, don't fail session start
+
+        # Announce session start if requested (do this first, before potential exit)
+        if args.announce:
+            try:
+                script_dir = Path(__file__).parent
+                tts_dir = script_dir / "utils" / "tts"
+
+                # TTS priority: MLX Audio > ElevenLabs > OpenAI > pyttsx3 > macOS say
+                tts_script = None
+
+                # Check for Apple Silicon and MLX Audio
+                if platform.system() == "Darwin" and platform.machine() == "arm64":
+                    mlx_script = tts_dir / "mlx_audio_tts.py"
+                    if mlx_script.exists():
+                        tts_script = mlx_script
+
+                # ElevenLabs if API key set
+                if not tts_script and os.getenv('ELEVENLABS_API_KEY'):
+                    el_script = tts_dir / "elevenlabs_tts.py"
+                    if el_script.exists():
+                        tts_script = el_script
+
+                # OpenAI TTS if API key set
+                if not tts_script and os.getenv('OPENAI_API_KEY'):
+                    oai_script = tts_dir / "openai_tts.py"
+                    if oai_script.exists():
+                        tts_script = oai_script
+
+                # pyttsx3 fallback
+                if not tts_script:
+                    py_script = tts_dir / "pyttsx3_tts.py"
+                    if py_script.exists():
+                        tts_script = py_script
+
+                # Get agent codename for identification (ANV-135)
+                codename = get_my_codename()
+                agent_prefix = f"Agent {codename[1:]}" if codename.startswith("A") else "Claude Code"
+
+                messages = {
+                    "startup": f"{agent_prefix} session started.",
+                    "resume": f"{agent_prefix} resuming session.",
+                    "clear": f"{agent_prefix} starting fresh."
+                }
+                message = messages.get(source, f"{agent_prefix} ready.")
+
+                if tts_script:
+                    result = subprocess.run(
+                        ["uv", "run", str(tts_script), message],
+                        capture_output=True,
+                        timeout=15
+                    )
+                    # Fallback to say if script failed
+                    if result.returncode != 0 and platform.system() == "Darwin":
+                        subprocess.run(['say', message], capture_output=True, timeout=10)
+                elif platform.system() == "Darwin":
+                    subprocess.run(['say', message], capture_output=True, timeout=10)
+            except Exception:
+                pass
+
+        # Register agent if requested (for multi-terminal coordination)
+        agent_id = None
+        if args.register_agent:
+            agent_id = register_agent()
+
+        # Load development context if requested
+        if args.load_context:
+            context = load_development_context(source)
+            if context:
+                # Using JSON output to add context
+                output = {
+                    "hookSpecificOutput": {
+                        "hookEventName": "SessionStart",
+                        "additionalContext": context
+                    }
+                }
+                # Include agent ID in context if registered
+                if agent_id:
+                    output["hookSpecificOutput"]["additionalContext"] += f"\nAgent ID: {agent_id}"
+                print(json.dumps(output))
+
+        # Success
+        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()