stravinsky 0.4.18__py3-none-any.whl → 0.4.66__py3-none-any.whl

mcp_bridge/tools/session_manager.py

@@ -6,10 +6,8 @@ Sessions are stored in ~/.claude/projects/ as JSONL files.
 """
 
 import json
-import os
 from datetime import datetime
 from pathlib import Path
-from typing import Any
 
 
 def get_sessions_directory() -> Path:

mcp_bridge/tools/skill_loader.py

@@ -8,7 +8,6 @@ Discovers and lists available skills (slash commands) from:
 Skills are markdown files with frontmatter defining the command behavior.
 """
 
-import os
 import re
 from pathlib import Path
 from typing import Any

mcp_bridge/tools/task_runner.py

@@ -6,12 +6,10 @@ capture output, and update status in tasks.json.
 """
 
 import argparse
+import asyncio
 import json
 import logging
 import os
-import sys
-import asyncio
-import subprocess
 from datetime import datetime
 from pathlib import Path
 
@@ -27,7 +25,7 @@ async def run_task(task_id: str, base_dir: str):
 
     # Load task details
     try:
-        with open(tasks_file, "r") as f:
+        with open(tasks_file) as f:
             tasks = json.load(f)
         task = tasks.get(task_id)
     except Exception as e:
@@ -39,7 +37,7 @@ async def run_task(task_id: str, base_dir: str):
         return
 
     prompt = task.get("prompt")
-    model = task.get("model", "gemini-2.0-flash")
+    model = task.get("model", "gemini-3-flash")
 
     output_file = agents_dir / f"{task_id}.out"
     agents_dir.mkdir(parents=True, exist_ok=True)
@@ -83,7 +81,7 @@ async def run_task(task_id: str, base_dir: str):
             f.write(result)
 
         # Update status
-        with open(tasks_file, "r") as f:
+        with open(tasks_file) as f:
             tasks = json.load(f)
 
         if task_id in tasks:
@@ -104,7 +102,7 @@ async def run_task(task_id: str, base_dir: str):
 
         # Update status with error
         try:
-            with open(tasks_file, "r") as f:
+            with open(tasks_file) as f:
                 tasks = json.load(f)
             if task_id in tasks:
                 tasks[task_id].update(

mcp_bridge/tools/templates.py

@@ -33,7 +33,7 @@ For ANY task with 2+ independent steps:
 3. Monitor with agent_progress, collect with agent_output
 
 ### Trigger Commands
-- **IRONSTAR** / **IRS**: Maximum parallel execution - spawn agents aggressively for every subtask
+- **ULTRAWORK** / **UW**: Maximum parallel execution - spawn agents aggressively for every subtask
 - **ULTRATHINK**: Engage exhaustive deep reasoning, multi-dimensional analysis
 - **SEARCH**: Maximize search effort across codebase and external resources
 - **ANALYZE**: Deep analysis mode with delphi consultation for complex issues
@@ -99,11 +99,11 @@ stravinsky:agent_output(task_id="[id]", block=true)
 - This enables auto-delegation without manual /stravinsky invocation
 
 ### Execution Modes:
-- `ironstar` / `irs` / `ultrawork` - Maximum parallel execution (10+ agents)
+- `ultrawork` / `irs` - Maximum parallel execution (10+ agents)
 - `ultrathink` - Deep reasoning with delphi consultation
 - `search` - Exhaustive multi-agent search
 
-**Your FIRST action must be spawning agents, not using Read/Search tools.**
+**Your FUWT action must be spawning agents, not using Read/Search tools.**
 """
 
 COMMAND_PARALLEL = """---

mcp_bridge/tools/tool_search.py

@@ -0,0 +1,331 @@
+"""
+Tool Search - BM25-based relevance search across MCP tools
+
+Provides intelligent tool discovery using BM25 (Okapi) ranking algorithm.
+Enables queries like "find github tools", "search semantic code", etc.
+
+Features:
+- BM25Okapi relevance scoring across tool names, descriptions, parameters
+- Tag filtering (e.g., "github", "lsp", "semantic")
+- Category filtering (e.g., "search", "code", "git")
+- Top-K result ranking with scores
+- Comprehensive error handling with timeouts
+- Query logging for debugging
+
+Architecture:
+- Uses rank-bm25 for fast text-based relevance ranking
+- Searches across: tool name, description, parameter names, parameter descriptions, tags
+- Returns ranked list of tool names with relevance scores
+- Supports both broad queries ("find code") and specific queries ("github file search")
+"""
+
+import logging
+import signal
+from contextlib import contextmanager
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Lazy import to avoid startup cost
+_bm25 = None
+_import_lock = None
+
+
+def get_bm25():
+    """Lazy import of rank_bm25."""
+    global _bm25, _import_lock
+    if _bm25 is None:
+        if _import_lock is None:
+            import threading
+
+            _import_lock = threading.Lock()
+
+        with _import_lock:
+            if _bm25 is None:
+                try:
+                    from rank_bm25 import BM25Okapi
+
+                    _bm25 = BM25Okapi
+                except ImportError as e:
+                    raise ImportError(
+                        "rank-bm25 is required for tool search. "
+                        "Install with: uv add rank-bm25"
+                    ) from e
+    return _bm25
+
+
+class TimeoutError(Exception):
+    """Raised when tool search times out."""
+
+    pass
+
+
+@contextmanager
+def timeout(seconds: int):
+    """Context manager for operation timeout."""
+
+    def timeout_handler(signum, frame):
+        raise TimeoutError(f"Tool search timed out after {seconds} seconds")
+
+    # Set the signal handler
+    original_handler = signal.signal(signal.SIGALRM, timeout_handler)
+    signal.alarm(seconds)
+
+    try:
+        yield
+    finally:
+        # Restore original handler and cancel alarm
+        signal.alarm(0)
+        signal.signal(signal.SIGALRM, original_handler)
+
+
+def extract_tool_text(tool: Any) -> str:
+    """
+    Extract searchable text from a tool definition.
+
+    Args:
+        tool: Tool object (Pydantic model from mcp.types) with name, description, inputSchema, etc.
+
+    Returns:
+        Combined text for BM25 indexing (lowercased, space-separated).
+    """
+    parts = []
+
+    # Tool name (most important - add multiple times for weight boost)
+    name = getattr(tool, "name", "")
+    if name:
+        parts.extend([name, name, name])  # Triple weight for name
+
+    # Description (second most important - add twice)
+    description = getattr(tool, "description", "")
+    if description:
+        parts.extend([description, description])
+
+    # Parameter names and descriptions
+    input_schema = getattr(tool, "inputSchema", {})
+    properties = input_schema.get("properties", {}) if isinstance(input_schema, dict) else {}
+    for param_name, param_info in properties.items():
+        parts.append(param_name)
+        param_desc = param_info.get("description", "") if isinstance(param_info, dict) else ""
+        if param_desc:
+            parts.append(param_desc)
+
+    # Tags (if present - add twice for importance)
+    # Note: tags may be in tool.meta if present
+    meta = getattr(tool, "meta", None)
+    tags = meta.get("tags", []) if meta and isinstance(meta, dict) else []
+    if tags:
+        parts.extend(tags)
+        parts.extend(tags)  # Double weight for tags
+
+    # Category (if present - add twice)
+    category = meta.get("category", "") if meta and isinstance(meta, dict) else ""
+    if category:
+        parts.extend([category, category])
+
+    # Join and tokenize
+    text = " ".join(str(p) for p in parts if p).lower()
+    return text
+
+
+def tokenize(text: str) -> list[str]:
+    """
+    Simple tokenization for BM25.
+
+    Args:
+        text: Input text to tokenize.
+
+    Returns:
+        List of lowercase tokens (split on whitespace and punctuation).
+    """
+    # Replace common punctuation with spaces
+    for char in ".,;:!?()[]{}\"'`-_/\\|@#$%^&*+=<>":
+        text = text.replace(char, " ")
+
+    # Split on whitespace and filter empty strings
+    tokens = [t.lower() for t in text.split() if t.strip()]
+    return tokens
+
+
+def search_tools(
+    query: str,
+    tools: list[Any],
+    top_k: int = 10,
+    tag_filter: str | None = None,
+    category_filter: str | None = None,
+    timeout_seconds: int = 5,
+) -> list[dict[str, Any]]:
+    """
+    Search tools using BM25 relevance ranking.
+
+    Args:
+        query: Natural language search query (e.g., "find github tools")
+        tools: List of Tool objects (Pydantic models from mcp.types)
+        top_k: Maximum number of results to return (default: 10)
+        tag_filter: Optional tag to filter by (e.g., "github", "lsp")
+        category_filter: Optional category to filter by (e.g., "search", "code")
+        timeout_seconds: Maximum execution time (default: 5 seconds)
+
+    Returns:
+        List of dicts with keys: name, score, tool (original tool object)
+        Sorted by relevance score (highest first).
+
+    Raises:
+        TimeoutError: If search exceeds timeout_seconds
+        ValueError: If query is empty or tools list is invalid
+        ImportError: If rank-bm25 is not installed
+
+    Example:
+        >>> tools = [...]  # List of Tool objects from MCP
+        >>> results = search_tools("find github tools", tools, top_k=5)
+        >>> print(results[0]["name"])  # "github_search"
+    """
+    # Input validation
+    if not query or not query.strip():
+        raise ValueError("Query cannot be empty")
+
+    if not tools or not isinstance(tools, list):
+        raise ValueError("Tools must be a non-empty list")
+
+    if top_k <= 0:
+        raise ValueError("top_k must be positive")
+
+    logger.info(
+        f"Tool search: query='{query}', tools={len(tools)}, "
+        f"tag_filter={tag_filter}, category_filter={category_filter}, top_k={top_k}"
+    )
+
+    try:
+        with timeout(timeout_seconds):
+            # Apply filters first (reduce search space)
+            filtered_tools = tools
+            if tag_filter:
+                tag_lower = tag_filter.lower()
+                filtered_tools = [
+                    t
+                    for t in filtered_tools
+                    if tag_lower in [
+                        tag.lower()
+                        for tag in (getattr(t, "meta", {}).get("tags", []) if isinstance(getattr(t, "meta", None), dict) else [])
+                    ]
+                ]
+                logger.debug(f"Tag filter '{tag_filter}' reduced to {len(filtered_tools)} tools")
+
+            if category_filter:
+                cat_lower = category_filter.lower()
+                filtered_tools = [
+                    t for t in filtered_tools
+                    if (getattr(t, "meta", {}).get("category", "") if isinstance(getattr(t, "meta", None), dict) else "").lower() == cat_lower
+                ]
+                logger.debug(
+                    f"Category filter '{category_filter}' reduced to {len(filtered_tools)} tools"
+                )
+
+            if not filtered_tools:
+                logger.warning("No tools remaining after filtering")
+                return []
+
+            # Extract and tokenize tool text
+            tool_texts = [extract_tool_text(t) for t in filtered_tools]
+            tokenized_corpus = [tokenize(text) for text in tool_texts]
+
+            # Initialize BM25
+            BM25Okapi = get_bm25()
+            bm25 = BM25Okapi(tokenized_corpus)
+
+            # Tokenize query
+            query_tokens = tokenize(query)
+            logger.debug(f"Query tokens: {query_tokens}")
+
+            # Score all documents
+            scores = bm25.get_scores(query_tokens)
+
+            # Create results with scores
+            results = [
+                {"name": getattr(tool, "name", ""), "score": float(score), "tool": tool}
+                for tool, score in zip(filtered_tools, scores)
+            ]
+
+            # Sort by score (descending) and take top K
+            results.sort(key=lambda x: x["score"], reverse=True)
+            top_results = results[:top_k]
+
+            # Log results
+            logger.info(
+                f"Tool search results: {len(top_results)} tools found "
+                f"(top score: {top_results[0]['score']:.2f} if top_results else 0)"
+            )
+            for i, result in enumerate(top_results[:5], 1):  # Log top 5
+                logger.debug(f"  {i}. {result['name']} (score: {result['score']:.2f})")
+
+            return top_results
+
+    except TimeoutError:
+        logger.error(f"Tool search timed out after {timeout_seconds}s: query='{query}'")
+        raise
+    except Exception as e:
+        logger.error(f"Tool search failed: query='{query}', error={e}", exc_info=True)
+        raise
+
+
+def search_tool_names(
+    query: str,
+    tools: list[Any],
+    top_k: int = 10,
+    tag_filter: str | None = None,
+    category_filter: str | None = None,
+) -> list[str]:
+    """
+    Convenience function that returns just tool names (no scores).
+
+    Args:
+        query: Search query
+        tools: List of Tool objects (Pydantic models from mcp.types)
+        top_k: Maximum results
+        tag_filter: Optional tag filter
+        category_filter: Optional tag filter
+
+    Returns:
+        List of tool names ordered by relevance.
+
+    Example:
+        >>> tools = [...]  # List of Tool objects
+        >>> names = search_tool_names("github search", tools, top_k=5)
+        >>> print(names)  # ["github_search", "search_code", ...]
+    """
+    results = search_tools(query, tools, top_k, tag_filter, category_filter)
+    return [r["name"] for r in results]
+
+
+def format_search_results(results: list[dict[str, Any]], include_scores: bool = True) -> str:
+    """
+    Format search results for display.
+
+    Args:
+        results: List of result dicts from search_tools()
+        include_scores: Whether to include relevance scores
+
+    Returns:
+        Formatted string for display.
+
+    Example:
+        >>> results = search_tools("github", tools)
+        >>> print(format_search_results(results))
+        Found 3 tools:
+        1. github_search (score: 8.52)
+        2. github_create_issue (score: 6.31)
+        3. search_code (score: 2.14)
+    """
+    if not results:
+        return "No tools found"
+
+    lines = [f"Found {len(results)} tool(s):"]
+    for i, result in enumerate(results, 1):
+        name = result["name"]
+        if include_scores:
+            score = result["score"]
+            lines.append(f"{i}. {name} (score: {score:.2f})")
+        else:
+            lines.append(f"{i}. {name}")
+
+    return "\n".join(lines)

mcp_bridge/tools/write_file.py

@@ -0,0 +1,29 @@
+import os
+from pathlib import Path
+from mcp_bridge.utils.cache import IOCache
+
+async def write_file(path: str, content: str) -> str:
+    """
+    Write content to a file and invalidate cache.
+    """
+    # USER-VISIBLE NOTIFICATION
+    import sys
+    print(f"📝 WRITE: {path} ({len(content)} bytes)", file=sys.stderr)
+
+    file_path = Path(path)
+    try:
+        # Ensure parent directories exist
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        # Write file
+        file_path.write_text(content, encoding="utf-8")
+        
+        # Invalidate cache for this path and its parent (directory listing)
+        cache = IOCache.get_instance()
+        cache.invalidate_path(str(file_path))
+        cache.invalidate_path(str(file_path.parent))
+        
+        return f"Successfully wrote {len(content)} bytes to {path}"
+
+    except Exception as e:
+        return f"Error writing file {path}: {str(e)}"

mcp_bridge/update_manager.py

@@ -17,19 +17,19 @@ import json
 import logging
 import shutil
 import sys
+from dataclasses import asdict, dataclass
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Any
-from dataclasses import dataclass, asdict
+from typing import Any
 
 
 @dataclass
 class MergeConflict:
     """Represents a merge conflict for a file."""
     file_path: str
-    base_version: Optional[str]
-    user_version: Optional[str]
-    new_version: Optional[str]
+    base_version: str | None
+    user_version: str | None
+    new_version: str | None
     conflict_type: str
 
 
@@ -38,13 +38,13 @@ class UpdateManifest:
     """Manifest tracking file versions and update status."""
     version: str
     timestamp: str
-    files: Dict[str, str]
+    files: dict[str, str]
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         return asdict(self)
 
     @staticmethod
-    def from_dict(data: Dict[str, Any]) -> 'UpdateManifest':
+    def from_dict(data: dict[str, Any]) -> 'UpdateManifest':
         return UpdateManifest(
             version=data.get('version', ''),
             timestamp=data.get('timestamp', ''),
@@ -102,7 +102,7 @@ class UpdateManager:
         except Exception:
             return "unknown"
 
-    def _load_manifest(self, manifest_type: str) -> Optional[UpdateManifest]:
+    def _load_manifest(self, manifest_type: str) -> UpdateManifest | None:
         """Load manifest file (base, user, new)."""
         manifest_path = self.manifest_dir / f"{manifest_type}_manifest.json"
 
@@ -132,7 +132,7 @@ class UpdateManager:
             self.logger.error(f"Failed to save manifest: {e}")
             return False
 
-    def _create_backup(self, source_dir: Path, backup_name: str) -> Optional[Path]:
+    def _create_backup(self, source_dir: Path, backup_name: str) -> Path | None:
         """Create timestamped backup of directory."""
         if self.dry_run:
             return None
@@ -151,7 +151,7 @@ class UpdateManager:
             self.logger.error(f"Failed to create backup: {e}")
             return None
 
-    def _read_file_safely(self, path: Path) -> Optional[str]:
+    def _read_file_safely(self, path: Path) -> str | None:
         """Read file with error handling."""
         try:
             if not path.exists():
@@ -179,11 +179,11 @@ class UpdateManager:
 
     def _detect_conflicts(
         self,
-        base: Optional[str],
-        user: Optional[str],
-        new: Optional[str],
+        base: str | None,
+        user: str | None,
+        new: str | None,
         file_path: str
-    ) -> Optional[MergeConflict]:
+    ) -> MergeConflict | None:
         """Detect merge conflicts using 3-way merge logic."""
         if new == base:
             return None
@@ -210,18 +210,16 @@ class UpdateManager:
 
     def _merge_3way(
         self,
-        base: Optional[str],
-        user: Optional[str],
-        new: Optional[str],
+        base: str | None,
+        user: str | None,
+        new: str | None,
         file_path: str
-    ) -> Tuple[str, bool]:
+    ) -> tuple[str, bool]:
         """Perform 3-way merge on file content."""
         if base is None:
             if user is None:
                 return new or "", False
-            elif new is None:
-                return user, False
-            elif user == new:
+            elif new is None or user == new:
                 return user, False
             else:
                 return self._format_conflict_markers(user, new), True
@@ -247,7 +245,7 @@ class UpdateManager:
 
         return user, False
 
-    def _line_based_merge(self, base: str, user: str, new: str) -> Tuple[str, bool]:
+    def _line_based_merge(self, base: str, user: str, new: str) -> tuple[str, bool]:
         """Perform line-based merge for text conflicts."""
         base_lines = base.splitlines(keepends=True)
         user_lines = user.splitlines(keepends=True)
@@ -262,9 +260,7 @@ class UpdateManager:
                     merged.append(u)
                 elif u == b and n != b:
                     merged.append(n)
-                elif n == b and u != b:
-                    merged.append(u)
-                elif u == n:
+                elif n == b and u != b or u == n:
                     merged.append(u)
                 else:
                     merged.append(f"<<<<<<< {u}======= {n}>>>>>>> ")
@@ -279,7 +275,7 @@ class UpdateManager:
 
         return "".join(merged), has_conflict
 
-    def _format_conflict_markers(self, user: Optional[str], new: Optional[str]) -> str:
+    def _format_conflict_markers(self, user: str | None, new: str | None) -> str:
         """Format conflict markers for display."""
         lines = ["<<<<<<< USER VERSION\n"]
         if user:
@@ -294,7 +290,7 @@ class UpdateManager:
         lines.append(">>>>>>> NEW VERSION\n")
         return "".join(lines)
 
-    def _preserve_statusline(self, settings_file: Path) -> Optional[Dict[str, Any]]:
+    def _preserve_statusline(self, settings_file: Path) -> dict[str, Any] | None:
         """Read and preserve statusline from settings.json."""
         try:
             if not settings_file.exists():
@@ -310,10 +306,10 @@ class UpdateManager:
 
     def _merge_settings_json(
         self,
-        base: Optional[Dict[str, Any]],
-        user: Optional[Dict[str, Any]],
-        new: Optional[Dict[str, Any]]
-    ) -> Tuple[Dict[str, Any], List[MergeConflict]]:
+        base: dict[str, Any] | None,
+        user: dict[str, Any] | None,
+        new: dict[str, Any] | None
+    ) -> tuple[dict[str, Any], list[MergeConflict]]:
         """Merge settings.json with special handling for hooks and statusline."""
         conflicts = []
 
@@ -369,9 +365,9 @@ class UpdateManager:
 
     def update_hooks(
         self,
-        new_hooks: Dict[str, str],
+        new_hooks: dict[str, str],
         stravinsky_version: str
-    ) -> Tuple[bool, List[MergeConflict]]:
+    ) -> tuple[bool, list[MergeConflict]]:
         """Update hooks with 3-way merge and conflict detection."""
         self.logger.info(f"Starting hooks update to version {stravinsky_version}")
 
@@ -430,7 +426,7 @@ class UpdateManager:
         self.logger.info(f"Hooks update completed ({len(updated_files)} files updated)")
         return True, conflicts
 
-    def update_settings_json(self, new_settings: Dict[str, Any]) -> Tuple[bool, List[MergeConflict]]:
+    def update_settings_json(self, new_settings: dict[str, Any]) -> tuple[bool, list[MergeConflict]]:
         """Update settings.json with hook merging and statusline preservation."""
         self.logger.info("Starting settings.json update")
 
@@ -495,7 +491,7 @@ class UpdateManager:
 
         return success
 
-    def verify_integrity(self) -> Tuple[bool, List[str]]:
+    def verify_integrity(self) -> tuple[bool, list[str]]:
         """Verify integrity of installed hooks and settings."""
         issues = []
         hooks_dir = self.global_claude_dir / "hooks"
@@ -524,7 +520,7 @@ class UpdateManager:
 
         return len(issues) == 0, issues
 
-    def list_backups(self) -> List[Dict[str, Any]]:
+    def list_backups(self) -> list[dict[str, Any]]:
         """List all available backups."""
         backups = []