stravinsky 0.1.2__py3-none-any.whl → 0.2.38__py3-none-any.whl

mcp_bridge/hooks/__init__.py

@@ -0,0 +1,49 @@
+"""
+Hooks initialization.
+Registers all Tier 1-4 hooks into the HookManager.
+"""
+
+from .manager import get_hook_manager
+from .truncator import output_truncator_hook
+from .edit_recovery import edit_error_recovery_hook
+from .directory_context import directory_context_hook
+from .compaction import context_compaction_hook
+from .budget_optimizer import budget_optimizer_hook
+from .todo_enforcer import todo_continuation_hook
+from .keyword_detector import keyword_detector_hook
+from .comment_checker import comment_checker_hook
+from .context_monitor import context_monitor_hook
+from .agent_reminder import agent_reminder_hook
+from .preemptive_compaction import preemptive_compaction_hook
+from .auto_slash_command import auto_slash_command_hook
+from .session_recovery import session_recovery_hook
+from .empty_message_sanitizer import empty_message_sanitizer_hook
+
+
+def initialize_hooks():
+    """Register all available hooks."""
+    manager = get_hook_manager()
+
+    # Tier 1: Post-tool-call (immediate response modification)
+    manager.register_post_tool_call(output_truncator_hook)
+    manager.register_post_tool_call(edit_error_recovery_hook)
+    manager.register_post_tool_call(comment_checker_hook)
+    manager.register_post_tool_call(agent_reminder_hook)
+    manager.register_post_tool_call(session_recovery_hook)
+
+    # Tier 2: Pre-model-invoke (context management)
+    manager.register_pre_model_invoke(directory_context_hook)
+    manager.register_pre_model_invoke(context_compaction_hook)
+    manager.register_pre_model_invoke(context_monitor_hook)
+    manager.register_pre_model_invoke(preemptive_compaction_hook)
+    manager.register_pre_model_invoke(empty_message_sanitizer_hook)
+
+    # Tier 3: Pre-model-invoke (performance optimization)
+    manager.register_pre_model_invoke(budget_optimizer_hook)
+
+    # Tier 4: Pre-model-invoke (behavior enforcement)
+    manager.register_pre_model_invoke(keyword_detector_hook)
+    manager.register_pre_model_invoke(todo_continuation_hook)
+    manager.register_pre_model_invoke(auto_slash_command_hook)
+
+    return manager

mcp_bridge/hooks/agent_reminder.py

@@ -0,0 +1,61 @@
+"""
+Agent Usage Reminder Hook.
+
+When direct search tools (grep, glob, find) are used,
+suggests using background agents for more comprehensive results.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+AGENT_SUGGESTION = """
+[AGENT SUGGESTION]
+You used `{tool_name}` directly. For more comprehensive results, consider:
+
+**Background Agents (parallel, more thorough):**
+```
+background_task(agent="explore", prompt="Search for {search_context}...")
+background_task(agent="dewey", prompt="Find documentation for {search_context}...")
+```
+
+Background agents can search multiple patterns simultaneously and provide richer context.
+Use direct tools for quick, targeted lookups. Use agents for exploratory research.
+"""
+
+SEARCH_TOOLS = {"grep", "glob", "rg", "find", "Grep", "Glob", "grep_search", "glob_files"}
+
+
+async def agent_reminder_hook(
+    tool_name: str, arguments: Dict[str, Any], output: str
+) -> Optional[str]:
+    """
+    Post-tool call hook that suggests background agents after direct search tool usage.
+    """
+    if tool_name not in SEARCH_TOOLS:
+        return None
+
+    search_context = _extract_search_context(arguments)
+
+    if not search_context:
+        return None
+
+    if len(output) < 100:
+        logger.info(
+            f"[AgentReminder] Direct search '{tool_name}' returned limited results, suggesting agents"
+        )
+        suggestion = AGENT_SUGGESTION.format(tool_name=tool_name, search_context=search_context)
+        return output + "\n" + suggestion
+
+    return None
+
+
+def _extract_search_context(arguments: Dict[str, Any]) -> str:
+    """Extract search context from tool arguments."""
+    for key in ("pattern", "query", "search", "name", "path"):
+        if key in arguments:
+            value = arguments[key]
+            if isinstance(value, str) and len(value) < 100:
+                return value
+    return "related patterns"

mcp_bridge/hooks/auto_slash_command.py

@@ -0,0 +1,186 @@
+"""
+Auto Slash Command Hook.
+
+Detects and auto-processes slash commands in user input:
+- Parses `/command` patterns in user input
+- Looks up matching skill via skill_loader
+- Injects skill content into prompt
+- Registered as pre_model_invoke hook
+"""
+
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Pattern to match slash commands at the beginning of a line or after whitespace
+SLASH_COMMAND_PATTERN = re.compile(r'(?:^|(?<=\s))\/([a-zA-Z][a-zA-Z0-9_-]*)\b', re.MULTILINE)
+
+
+def extract_slash_commands(text: str) -> List[str]:
+    """
+    Extract all slash command names from text.
+
+    Args:
+        text: Input text to scan for slash commands
+
+    Returns:
+        List of command names (without the slash)
+    """
+    matches = SLASH_COMMAND_PATTERN.findall(text)
+    # Deduplicate while preserving order
+    seen = set()
+    unique = []
+    for match in matches:
+        if match.lower() not in seen:
+            seen.add(match.lower())
+            unique.append(match)
+    return unique
+
+
+def load_skill_content(command_name: str, project_path: Optional[str] = None) -> Optional[Tuple[str, str]]:
+    """
+    Load skill content by command name.
+
+    Args:
+        command_name: The command name to look up
+        project_path: Optional project path for local skills
+
+    Returns:
+        Tuple of (skill_name, skill_content) or None if not found
+    """
+    from ..tools.skill_loader import discover_skills, parse_frontmatter
+
+    skills = discover_skills(project_path)
+
+    # Find matching skill (case-insensitive)
+    skill = next(
+        (s for s in skills if s["name"].lower() == command_name.lower()),
+        None
+    )
+
+    if not skill:
+        return None
+
+    try:
+        content = Path(skill["path"]).read_text()
+        metadata, body = parse_frontmatter(content)
+
+        # Build the skill injection block
+        skill_block = f"""
+---
+## Skill: /{skill['name']}
+**Source**: {skill['path']}
+"""
+        if metadata.get("description"):
+            skill_block += f"**Description**: {metadata['description']}\n"
+
+        if metadata.get("allowed-tools"):
+            skill_block += f"**Allowed Tools**: {metadata['allowed-tools']}\n"
+
+        skill_block += f"""
+### Instructions:
+{body}
+---
+"""
+        return skill["name"], skill_block
+
+    except Exception as e:
+        logger.error(f"[AutoSlashCommand] Error loading skill '{command_name}': {e}")
+        return None
+
+
+def get_project_path_from_prompt(prompt: str) -> Optional[str]:
+    """
+    Try to extract project path from prompt context.
+    Looks for common patterns that indicate the working directory.
+    """
+    # Look for CWD markers
+    cwd_patterns = [
+        r'CWD:\s*([^\n]+)',
+        r'Working directory:\s*([^\n]+)',
+        r'project_path["\']?\s*[:=]\s*["\']?([^"\'}\n]+)',
+    ]
+
+    for pattern in cwd_patterns:
+        match = re.search(pattern, prompt)
+        if match:
+            path = match.group(1).strip()
+            if Path(path).exists():
+                return path
+
+    return None
+
+
+SKILL_INJECTION_HEADER = """
+> **[AUTO-SKILL INJECTION]**
+> The following skill(s) have been automatically loaded based on slash commands detected in your input:
+"""
+
+SKILL_NOT_FOUND_WARNING = """
+> **[SKILL NOT FOUND]**
+> The slash command `/{command}` was detected but no matching skill was found.
+> Available skills can be listed with the `skill_list` tool.
+"""
+
+
+async def auto_slash_command_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Pre-model invoke hook that detects slash commands and injects skill content.
+
+    Scans the prompt for /command patterns and loads corresponding skill files
+    from .claude/commands/ directories.
+    """
+    prompt = params.get("prompt", "")
+
+    # Skip if already processed
+    if "[AUTO-SKILL INJECTION]" in prompt:
+        return None
+
+    # Extract slash commands
+    commands = extract_slash_commands(prompt)
+
+    if not commands:
+        return None
+
+    logger.info(f"[AutoSlashCommand] Detected slash commands: {commands}")
+
+    # Try to get project path from prompt context
+    project_path = get_project_path_from_prompt(prompt)
+
+    # Load skills for each command
+    injections = []
+    warnings = []
+    loaded_skills = []
+
+    for command in commands:
+        result = load_skill_content(command, project_path)
+        if result:
+            skill_name, skill_content = result
+            injections.append(skill_content)
+            loaded_skills.append(skill_name)
+            logger.info(f"[AutoSlashCommand] Loaded skill: {skill_name}")
+        else:
+            warnings.append(SKILL_NOT_FOUND_WARNING.format(command=command))
+            logger.warning(f"[AutoSlashCommand] Skill not found: {command}")
+
+    if not injections and not warnings:
+        return None
+
+    # Build the injection block
+    injection_block = ""
+
+    if injections:
+        injection_block = SKILL_INJECTION_HEADER
+        injection_block += f"> Skills loaded: {', '.join(loaded_skills)}\n"
+        injection_block += "\n".join(injections)
+
+    if warnings:
+        injection_block += "\n".join(warnings)
+
+    # Prepend the injection to the prompt
+    params["prompt"] = injection_block + "\n\n" + prompt
+
+    return params

mcp_bridge/hooks/budget_optimizer.py

@@ -0,0 +1,38 @@
+"""
+Thinking budget optimizer hook.
+Analyzes prompt complexity and adjusts thinking_budget for models that support it.
+"""
+
+from typing import Any, Dict, Optional
+
+REASONING_KEYWORDS = [
+    "architect", "design", "refactor", "debug", "complex", "optimize", 
+    "summarize", "analyze", "explain", "why", "review", "strangler"
+]
+
+async def budget_optimizer_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Adjusts the thinking_budget based on presence of reasoning-heavy keywords.
+    """
+    model = params.get("model", "")
+    # Only applies to models that typically support reasoning budgets (Gemini 2.0 Thinking, GPT-o1, etc.)
+    if not any(m in model for m in ["thinking", "flash-thinking", "o1", "o3"]):
+        return None
+        
+    prompt = params.get("prompt", "").lower()
+    
+    # Simple heuristic
+    is_complex = any(keyword in prompt for keyword in REASONING_KEYWORDS)
+    
+    current_budget = params.get("thinking_budget", 0)
+    
+    if is_complex and current_budget < 4000:
+        # Increase budget for complex tasks
+        params["thinking_budget"] = 16000
+        return params
+    elif not is_complex and current_budget > 2000:
+        # Lower budget for simple tasks to save time/cost
+        params["thinking_budget"] = 2000
+        return params
+        
+    return None

mcp_bridge/hooks/comment_checker.py

@@ -0,0 +1,136 @@
+"""
+Comment Checker Hook.
+
+Warns when generated code contains excessive comments.
+Code should be self-documenting; excessive comments indicate AI slop.
+"""
+
+import logging
+import re
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+COMMENT_WARNING = """
+[WARNING - EXCESSIVE COMMENTS DETECTED]
+
+Your recent code edit contains a high ratio of comments ({ratio:.0%}).
+Code generated by stravinsky should be indistinguishable from human-written code.
+
+**Guidelines:**
+- Comments should explain WHY, not WHAT
+- Self-documenting code > commented code
+- Remove obvious comments like "// Initialize the variable"
+- Keep only: complex algorithms, security notes, performance optimizations, regex explanations
+
+**Action Required:**
+Review and remove unnecessary comments from your recent edit.
+"""
+
+COMMENT_PATTERNS = {
+    "python": [
+        r"^\s*#(?!\!)",
+        r'^\s*"""[\s\S]*?"""',
+        r"^\s*'''[\s\S]*?'''",
+    ],
+    "javascript": [
+        r"^\s*//",
+        r"/\*[\s\S]*?\*/",
+    ],
+    "typescript": [
+        r"^\s*//",
+        r"/\*[\s\S]*?\*/",
+    ],
+}
+
+CODE_EXTENSIONS = {
+    ".py": "python",
+    ".js": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".jsx": "javascript",
+}
+
+
+async def comment_checker_hook(
+    tool_name: str, arguments: Dict[str, Any], output: str
+) -> Optional[str]:
+    """
+    Post-tool call hook that checks for excessive comments in code edits.
+    """
+    if tool_name not in ("Write", "Edit", "write", "edit"):
+        return None
+
+    file_path = arguments.get("filePath", arguments.get("file_path", ""))
+    if not file_path:
+        return None
+
+    ext = None
+    for extension in CODE_EXTENSIONS:
+        if file_path.endswith(extension):
+            ext = extension
+            break
+
+    if not ext:
+        return None
+
+    lang = CODE_EXTENSIONS[ext]
+    content = arguments.get("content", arguments.get("newString", ""))
+
+    if not content or len(content) < 50:
+        return None
+
+    comment_ratio = _calculate_comment_ratio(content, lang)
+
+    if comment_ratio > 0.30:
+        logger.warning(
+            f"[CommentChecker] High comment ratio ({comment_ratio:.0%}) detected in {file_path}"
+        )
+        warning = COMMENT_WARNING.format(ratio=comment_ratio)
+        return output + "\n" + warning
+
+    return None
+
+
+def _calculate_comment_ratio(content: str, lang: str) -> float:
+    """Calculate the ratio of comment lines to total lines."""
+    lines = content.split("\n")
+    total_lines = len([l for l in lines if l.strip()])
+
+    if total_lines == 0:
+        return 0.0
+
+    comment_lines = 0
+    patterns = COMMENT_PATTERNS.get(lang, [])
+
+    in_multiline = False
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        if lang == "python":
+            if stripped.startswith("#") and not stripped.startswith("#!"):
+                comment_lines += 1
+            elif stripped.startswith('"""') or stripped.startswith("'''"):
+                if stripped.count('"""') >= 2 or stripped.count("'''") >= 2:
+                    comment_lines += 1
+                else:
+                    in_multiline = True
+                    comment_lines += 1
+            elif in_multiline:
+                comment_lines += 1
+                if '"""' in stripped or "'''" in stripped:
+                    in_multiline = False
+        else:
+            if stripped.startswith("//"):
+                comment_lines += 1
+            elif stripped.startswith("/*"):
+                in_multiline = True
+                comment_lines += 1
+            elif in_multiline:
+                comment_lines += 1
+                if "*/" in stripped:
+                    in_multiline = False
+
+    return comment_lines / total_lines

mcp_bridge/hooks/compaction.py

@@ -0,0 +1,32 @@
+"""
+Preemptive context compaction hook.
+Monitors context size and injects optimization reminders.
+"""
+
+from typing import Any, Dict, Optional
+
+THRESHOLD_CHARS = 100000 # Roughly 25k-30k tokens for typical LLM text
+
+COMPACTION_REMINDER = """
+> **[SYSTEM ALERT - CONTEXT WINDOW NEAR LIMIT]**
+> The current conversation history is reaching its limits. Performance may degrade.
+> Please **STOP** and perform a **Session Compaction**:
+> 1. Summarize all work completed so far in a `TASK_STATE.md` (if not already done).
+> 2. List all pending todos.
+> 3. Clear unnecessary tool outputs from your reasoning.
+> 4. Keep your next responses concise and focused only on the current sub-task.
+"""
+
+async def context_compaction_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Checks prompt length and injects a compaction reminder if it's too large.
+    """
+    prompt = params.get("prompt", "")
+    
+    if len(prompt) > THRESHOLD_CHARS:
+        # Check if we haven't already injected the reminder recently
+        if "CONTEXT WINDOW NEAR LIMIT" not in prompt:
+            params["prompt"] = COMPACTION_REMINDER + prompt
+            return params
+            
+    return None

mcp_bridge/hooks/context_monitor.py

@@ -0,0 +1,58 @@
+"""
+Context Window Monitor Hook.
+
+Monitors context window usage and provides headroom reminders.
+At 70% usage, reminds the agent there's still capacity.
+At 85%, suggests compaction before hitting hard limits.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+HEADROOM_REMINDER = """
+[CONTEXT AWARENESS]
+Current context usage: ~{usage:.0%}
+You have approximately {remaining:.0%} headroom remaining.
+Continue working - no compaction needed yet.
+"""
+
+COMPACTION_WARNING = """
+[CONTEXT WARNING - PREEMPTIVE COMPACTION RECOMMENDED]
+Current context usage: ~{usage:.0%}
+Approaching context limit. Consider:
+1. Completing current task quickly
+2. Using `background_cancel(all=true)` to clean up agents
+3. Summarizing findings before context overflow
+"""
+
+CONTEXT_THRESHOLD_REMINDER = 0.70
+CONTEXT_THRESHOLD_WARNING = 0.85
+ESTIMATED_MAX_TOKENS = 200000
+
+
+async def context_monitor_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Pre-model invoke hook that monitors context window usage.
+    """
+    prompt = params.get("prompt", "")
+    estimated_tokens = len(prompt) / 4
+
+    usage_ratio = estimated_tokens / ESTIMATED_MAX_TOKENS
+
+    if usage_ratio >= CONTEXT_THRESHOLD_WARNING:
+        remaining = 1.0 - usage_ratio
+        logger.warning(f"[ContextMonitor] High context usage: {usage_ratio:.0%}")
+        warning = COMPACTION_WARNING.format(usage=usage_ratio, remaining=remaining)
+        params["prompt"] = prompt + "\n\n" + warning
+        return params
+
+    elif usage_ratio >= CONTEXT_THRESHOLD_REMINDER:
+        remaining = 1.0 - usage_ratio
+        logger.info(f"[ContextMonitor] Context usage: {usage_ratio:.0%}, reminding of headroom")
+        reminder = HEADROOM_REMINDER.format(usage=usage_ratio, remaining=remaining)
+        params["prompt"] = prompt + "\n\n" + reminder
+        return params
+
+    return None

mcp_bridge/hooks/directory_context.py

@@ -0,0 +1,40 @@
+"""
+Directory context injector hook.
+Automatically finds and injects local AGENTS.md or README.md content based on the current context.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+async def directory_context_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Search for AGENTS.md or README.md in the current working directory and inject them.
+    """
+    cwd = Path.cwd()
+    
+    # Check for AGENTS.md or README.md
+    target_files = ["AGENTS.md", "README.md"]
+    found_file = None
+    for filename in target_files:
+        if (cwd / filename).exists():
+            found_file = cwd / filename
+            break
+            
+    if not found_file:
+        return None
+        
+    try:
+        content = found_file.read_text()
+        # Injects as a special system reminder
+        injection = f"\n\n### Local Directory Context ({found_file.name}):\n{content}\n"
+        
+        # Modify the prompt if it exists in params
+        if "prompt" in params:
+            # Add to the beginning of the prompt as a context block
+            params["prompt"] = injection + params["prompt"]
+            return params
+    except Exception:
+        pass
+        
+    return None

mcp_bridge/hooks/edit_recovery.py

@@ -0,0 +1,41 @@
+"""
+Edit error recovery hook.
+Detects common mistakes in file editing and injects high-priority corrective directives.
+"""
+
+import re
+from typing import Any, Dict, Optional
+
+EDIT_ERROR_PATTERNS = [
+    r"oldString and newString must be different",
+    r"oldString not found",
+    r"oldString found multiple times",
+    r"Target content not found",
+    r"Multiple occurrences of target content found",
+]
+
+EDIT_RECOVERY_PROMPT = """
+> **[EDIT ERROR - IMMEDIATE ACTION REQUIRED]**
+> You made an Edit mistake. STOP and do this NOW:
+> 1. **READ** the file immediately to see its ACTUAL current state.
+> 2. **VERIFY** what the content really looks like (your assumption was wrong).
+> 3. **APOLOGIZE** briefly to the user for the error.
+> 4. **CONTINUE** with corrected action based on the real file content.
+> **DO NOT** attempt another edit until you've read and verified the file state.
+"""
+
+async def edit_error_recovery_hook(tool_name: str, arguments: Dict[str, Any], output: str) -> Optional[str]:
+    """
+    Analyzes tool output for edit errors and appends corrective directives.
+    """
+    # Check if this is an edit-related tool (handling both built-in and common MCP tools)
+    edit_tools = ["replace_file_content", "multi_replace_file_content", "write_to_file", "edit_file", "Edit"]
+    
+    # We also check the output content for common patterns even if the tool name doesn't match perfectly
+    is_edit_error = any(re.search(pattern, output, re.IGNORECASE) for pattern in EDIT_ERROR_PATTERNS)
+    
+    if is_edit_error or any(tool in tool_name for tool in edit_tools):
+        if any(re.search(pattern, output, re.IGNORECASE) for pattern in EDIT_ERROR_PATTERNS):
+            return output + EDIT_RECOVERY_PROMPT
+            
+    return None