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

mcp_bridge/update_manager_pypi.py

@@ -6,13 +6,11 @@ Logs all checks to ~/.stravinsky/update.log for debugging and monitoring.
 Non-blocking background update checks on server startup.
 """
 
-import asyncio
 import logging
 import subprocess
 import sys
 from datetime import datetime, timedelta
 from pathlib import Path
-from typing import Optional
 
 # Get the logger for this module
 logger = logging.getLogger(__name__)
@@ -21,7 +19,7 @@ logger = logging.getLogger(__name__)
 from mcp_bridge import __version__
 
 
-def _get_stravinsky_home() -> Optional[Path]:
+def _get_stravinsky_home() -> Path | None:
     """Get or create ~/.stravinsky directory."""
     home_dir = Path.home() / ".stravinsky"
     try:
@@ -32,7 +30,7 @@ def _get_stravinsky_home() -> Optional[Path]:
         return None
 
 
-def _get_last_check_time() -> Optional[datetime]:
+def _get_last_check_time() -> datetime | None:
     """
     Read the last update check time from ~/.stravinsky/update.log.
 
@@ -49,7 +47,7 @@ def _get_last_check_time() -> Optional[datetime]:
             return None
 
         # Read the last line (most recent check)
-        with open(update_log, "r") as f:
+        with open(update_log) as f:
             lines = f.readlines()
             if not lines:
                 return None
@@ -72,7 +70,7 @@ def _get_last_check_time() -> Optional[datetime]:
         return None
 
 
-def _should_check(last_check_time: Optional[datetime]) -> bool:
+def _should_check(last_check_time: datetime | None) -> bool:
     """
     Determine if enough time has passed since the last check.
 
@@ -92,7 +90,7 @@ def _should_check(last_check_time: Optional[datetime]) -> bool:
     return time_since_last_check >= timedelta(hours=24)
 
 
-def _get_pypi_version() -> Optional[str]:
+def _get_pypi_version() -> str | None:
     """
     Fetch the latest version of stravinsky from PyPI.
 
@@ -173,7 +171,7 @@ def _compare_versions(current: str, latest: str) -> bool:
         return False
 
 
-def _log_check(current: str, latest: Optional[str], status: str) -> None:
+def _log_check(current: str, latest: str | None, status: str) -> None:
     """
     Log the update check to ~/.stravinsky/update.log.
 

mcp_bridge/utils/cache.py

@@ -0,0 +1,82 @@
+import time
+import os
+import threading
+from typing import Any, Dict, Optional, Tuple
+
+class IOCache:
+    """
+    Lightweight, thread-safe in-memory cache for I/O operations.
+    Supports TTL-based expiration and manual invalidation.
+    """
+    _instance = None
+    _lock = threading.Lock()
+
+    def __init__(self, ttl: float = 5.0):
+        self.ttl = ttl
+        self._cache: Dict[str, Tuple[Any, float]] = {}
+        self._cache_lock = threading.Lock()
+
+    @classmethod
+    def get_instance(cls):
+        """Get the singleton instance of IOCache."""
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = cls()
+        return cls._instance
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        """
+        Store a value in the cache.
+        
+        Args:
+            key: Cache key (e.g., file path or command).
+            value: Data to cache.
+            ttl: Optional override for the default TTL.
+        """
+        expiry = time.time() + (ttl if ttl is not None else self.ttl)
+        with self._cache_lock:
+            self._cache[key] = (value, expiry)
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Retrieve a value from the cache if it hasn't expired.
+        
+        Returns:
+            The cached value, or None if missing or expired.
+        """
+        with self._cache_lock:
+            if key not in self._cache:
+                return None
+            
+            value, expiry = self._cache[key]
+            if time.time() > expiry:
+                del self._cache[key]
+                return None
+            
+            return value
+
+    def invalidate(self, key: str) -> None:
+        """Remove a specific key from the cache."""
+        with self._cache_lock:
+            if key in self._cache:
+                del self._cache[key]
+
+    def invalidate_path(self, path: str) -> None:
+        """
+        Invalidate all cache entries related to a specific file path.
+        Matches keys for read_file, list_dir, etc.
+        """
+        # Use realpath to resolve symlinks (crucial for macOS /var -> /private/var)
+        abs_path = os.path.realpath(path)
+        with self._cache_lock:
+            keys_to_del = [
+                k for k in self._cache.keys() 
+                if abs_path in k
+            ]
+            for k in keys_to_del:
+                del self._cache[k]
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        with self._cache_lock:
+            self._cache.clear()

mcp_bridge/utils/process.py

@@ -0,0 +1,71 @@
+import asyncio
+import os
+from dataclasses import dataclass
+from typing import Optional, List, Union
+
+@dataclass
+class ProcessResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+async def async_execute(
+    cmd: Union[str, List[str]], 
+    cwd: Optional[str] = None, 
+    timeout: Optional[float] = None
+) -> ProcessResult:
+    """
+    Execute a subprocess asynchronously.
+    
+    Args:
+        cmd: Command string or list of arguments.
+        cwd: Working directory.
+        timeout: Maximum execution time in seconds.
+        
+    Returns:
+        ProcessResult containing exit code, stdout, and stderr.
+        
+    Raises:
+        asyncio.TimeoutError: If the process exceeds the timeout.
+    """
+    if isinstance(cmd, str):
+        # Use shell wrapper for string commands
+        process = await asyncio.create_subprocess_exec(
+            "bash", "-c", cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd
+        )
+    else:
+        # Use direct execution for list of arguments
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd
+        )
+    
+    try:
+        if timeout:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(process.communicate(), timeout=timeout)
+        else:
+            stdout_bytes, stderr_bytes = await process.communicate()
+            
+    except asyncio.TimeoutError:
+        try:
+            # Kill process group if started with bash
+            if isinstance(cmd, str):
+                process.kill()
+            else:
+                process.kill()
+        except ProcessLookupError:
+            pass # Already gone
+        # Wait for it to actually die to avoid zombies
+        await process.wait()
+        raise
+        
+    return ProcessResult(
+        returncode=process.returncode if process.returncode is not None else 0,
+        stdout=stdout_bytes.decode('utf-8', errors='replace'),
+        stderr=stderr_bytes.decode('utf-8', errors='replace')
+    )

mcp_bridge/utils/session_state.py

@@ -0,0 +1,51 @@
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+STATE_DIR = Path.home() / ".stravinsky" / "state"
+
+
+def ensure_state_dir():
+    """Ensure the state directory exists."""
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_session_state_path(session_id: str) -> Path:
+    """Get the path to the state file for a given session."""
+    ensure_state_dir()
+    # Sanitize session_id to avoid path traversal
+    safe_id = "".join(c for c in session_id if c.isalnum() or c in ("-", "_"))
+    return STATE_DIR / f"session_{safe_id}.json"
+
+
+def get_session_state(session_id: Optional[str] = None) -> dict[str, Any]:
+    """Get the state for a session."""
+    if session_id is None:
+        session_id = get_current_session_id()
+
+    path = get_session_state_path(session_id)
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except Exception:
+        return {}
+
+
+def update_session_state(updates: dict[str, Any], session_id: Optional[str] = None):
+    """Update the state for a session."""
+    if session_id is None:
+        session_id = get_current_session_id()
+
+    state = get_session_state(session_id)
+    state.update(updates)
+    state["updated_at"] = time.time()
+    path = get_session_state_path(session_id)
+    path.write_text(json.dumps(state, indent=2))
+
+
+def get_current_session_id() -> str:
+    """Get the current session ID from environment or default."""
+    return os.environ.get("CLAUDE_SESSION_ID", "default")

mcp_bridge/utils/truncation.py

@@ -0,0 +1,76 @@
+from enum import Enum
+from typing import Optional
+import logging
+
+try:
+    import stravinsky_native
+    from stravinsky_native import truncator
+    NATIVE_AVAILABLE = True
+except ImportError:
+    NATIVE_AVAILABLE = False
+    logging.warning("stravinsky_native not found. Native truncation unavailable.")
+
+class TruncationStrategy(Enum):
+    MIDDLE = "middle"
+    TAIL = "tail"
+    AUTO_TAIL = "auto_tail" # New line-based strategy
+
+def truncate_output(
+    text: str, 
+    limit: int = 20000, 
+    strategy: TruncationStrategy = TruncationStrategy.MIDDLE,
+    custom_guidance: Optional[str] = None
+) -> str:
+    """
+    Truncates text to a specific limit using the chosen strategy. 
+    
+    Args:
+        text: The string to truncate.
+        limit: Max characters allowed.
+        strategy: How to truncate (MIDDLE or TAIL).
+        custom_guidance: Optional extra message for the agent.
+    """
+    if len(text) <= limit:
+        return text
+
+    # Standard guidance messages
+    guidance = "\n\n[Output truncated. "
+    if custom_guidance:
+        guidance += custom_guidance + " "
+    
+    if strategy == TruncationStrategy.TAIL:
+        # Show the END of the file
+        truncated_text = text[-limit:]
+        msg = f"{guidance}Showing last {limit} characters. Use offset/limit parameters to read specific parts of the file.]"
+        return f"... [TRUNCATED] ...\n{truncated_text}{msg}"
+    
+    else:  # MIDDLE strategy
+        # Show start and end, snip the middle
+        half_limit = limit // 2
+        start_part = text[:half_limit]
+        end_part = text[-half_limit:]
+        msg = f"{guidance}Showing first and last {half_limit} characters. Use offset/limit parameters to read specific parts of the file.]"
+        return f"{start_part}\n\n[... content truncated ...]\n\n{end_part}{msg}"
+
+def auto_tail_logs(content: str, head_lines: int = 100, tail_lines: int = 100) -> str:
+    """
+    Smart truncation for logs using native Rust implementation.
+    Keeps the first N lines (setup/config) and last M lines (recent errors).
+    """
+    if NATIVE_AVAILABLE:
+        try:
+            return truncator.auto_tail(content, head_lines, tail_lines)
+        except Exception as e:
+            logging.error(f"Native truncation failed: {e}")
+            # Fallback to python implementation
+            
+    # Python fallback
+    lines = content.splitlines()
+    if len(lines) <= head_lines + tail_lines:
+        return content
+        
+    head = "\n".join(lines[:head_lines])
+    tail = "\n".join(lines[-tail_lines:])
+    hidden = len(lines) - (head_lines + tail_lines)
+    
+    return f"{head}\n\n<... {hidden} lines truncated (fallback) ...>\n\n{tail}"

{stravinsky-0.4.18.dist-info → stravinsky-0.4.66.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: stravinsky
-Version: 0.4.18
-Summary: MCP Bridge for Claude Code with Multi-Model Support. Install globally: claude mcp add --scope user stravinsky -- uvx stravinsky. Add to CLAUDE.md: See https://pypi.org/project/stravinsky/
+Version: 0.4.66
+Summary: A sophisticated MCP bridge for Claude Code orchestration
 Project-URL: Repository, https://github.com/GratefulDave/stravinsky
 Project-URL: Issues, https://github.com/GratefulDave/stravinsky/issues
 Author: Stravinsky Team
@@ -11,8 +11,10 @@ Requires-Python: <3.14,>=3.11
 Requires-Dist: aiofiles>=23.1.0
 Requires-Dist: chromadb>=0.6.0
 Requires-Dist: cryptography>=41.0.0
+Requires-Dist: fastapi>=0.128.0
 Requires-Dist: google-auth-oauthlib>=1.0.0
 Requires-Dist: google-auth>=2.20.0
+Requires-Dist: google-genai>=0.2.0
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: jedi-language-server>=0.41.0
 Requires-Dist: jedi>=0.19.2
@@ -27,9 +29,11 @@ Requires-Dist: psutil>=5.9.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pygls>=1.3.0
 Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rank-bm25==0.2.2
 Requires-Dist: rich>=13.0.0
 Requires-Dist: ruff>=0.14.10
 Requires-Dist: tenacity>=8.5.0
+Requires-Dist: uvicorn>=0.40.0
 Requires-Dist: watchdog~=5.0.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10.0; extra == 'dev'
@@ -62,6 +66,8 @@ Description-Content-Type: text/markdown
 - 🔄 **Hook-Based Delegation** - PreToolUse hooks enforce delegation patterns with hard boundaries (exit code 2)
 - 📝 **LSP Integration** - Full Language Server Protocol support with persistent servers (35x speedup), code refactoring, and advanced navigation
 - 🔍 **AST-Aware Search** - Structural code search and refactoring with ast-grep
+- 🧠 **Tier-Aware Routing** - Multi-provider fallback system (Claude 4.5, GPT 5.2, Gemini 3) with OAuth-first priority
+- 🧠 **Tier-Aware Routing** - Multi-provider fallback system (Claude 4.5, GPT 5.2, Gemini 3) with OAuth-first priority
 - 🧠 **Semantic Code Search** - Natural language queries with local embeddings (ChromaDB + Ollama)
 - ⚡ **Cost-Optimized Routing** - Free/cheap agents (explore, dewey) always async, expensive (delphi) only when needed
 
@@ -110,6 +116,12 @@ claude mcp add --scope user stravinsky -- stravinsky
 
 ### Authentication
 
+Stravinsky supports **two authentication methods** for Gemini (OAuth-first with automatic API fallback):
+
+#### Option 1: OAuth (Recommended - Primary Method)
+
+**Full OAuth flow** with automatic token refresh:
+
 ```bash
 # Login to Google (Gemini)
 stravinsky-auth login gemini
@@ -124,6 +136,40 @@ stravinsky-auth status
 stravinsky-auth logout gemini
 ```
 
+**When to use:** Primary method for all use cases. Provides automatic fallback to API key on rate limits.
+
+**Rate Limit Architecture:**
+- **OAuth**: Lower rate limits, but convenient (no API key management)
+- **API Key**: **Tier 3 high quotas** - automatic fallback for heavy usage
+
+**Auth Priority:**
+1. OAuth is tried FUWT (if configured)
+2. On OAuth 429 rate limit → **Automatically switch to API key** (Tier 3 quotas) for 5 minutes
+3. After 5-minute cooldown → Retry OAuth
+
+#### Option 2: API Key (**Tier 3 High Quotas** - Automatic Fallback)
+
+**CRITICAL**: Use a **Tier 3 API key** for high-volume usage. OAuth has lower limits and automatically falls back to your API key.
+
+**Setup** - add your Gemini API key to `.env`:
+
+```bash
+# Add to your .env file (or export in shell)
+GEMINI_API_KEY=your_tier_3_api_key_here
+
+# Or use GOOGLE_API_KEY (same effect)
+GOOGLE_API_KEY=your_tier_3_api_key_here
+```
+
+**Get your API key:**
+1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
+2. Create an API key (ensure it's Tier 3 for high quotas)
+3. Add to `.env` file in your project root
+
+**When to use:**
+- **Primary**: Automatic fallback when OAuth rate limits are exhausted (recommended for all users)
+- Development/testing without OAuth setup
+
 **Secure Token Storage:**
 
 OAuth tokens are stored securely with automatic fallback:
@@ -154,7 +200,7 @@ cat ~/.config/python_keyring/keyringrc.cfg
 stravinsky-auth login gemini
 ```
 
-This configuration stores tokens in encrypted files at `~/.stravinsky/tokens/` instead of macOS Keychain, eliminating password prompts across terminal sessions. See [docs/KEYRING_AUTH_FIX.md](docs/KEYRING_AUTH_FIX.md) for detailed information.
+This configuration stores tokens in encrypted files at `~/.stravinsky/tokens/` instead of macOS Keychain, eliminating password prompts across terminal sessions. See [docs/reports/KEYRING_AUTH_FIX.md](docs/reports/KEYRING_AUTH_FIX.md) for detailed information.
 
 ### Slash Commands
 
@@ -164,54 +210,57 @@ Slash commands are discovered from:
 
 Commands can be organized in subdirectories (e.g., `.claude/commands/strav/stravinsky.md`).
 
-## Native Subagent Architecture
+## Native Subagent Architecture (PRIMARY)
 
-Stravinsky uses **native Claude Code subagents** (.claude/agents/) with automatic delegation:
+Stravinsky is architected around the **Native Subagent Pattern**. This design delegates specialized tasks to standalone Claude Code agents, enabling massive parallelism and reducing orchestrator cognitive load.
 
-### How It Works
+### Why Native Subagents?
+- **True Parallelism**: Spawn multiple agents (Explore, Dewey, Reviewer) simultaneously using the `Task` tool.
+- **Zero Bridge Latency**: Agents interact directly with the project codebase using native tools.
+- **Specialized Context**: Each agent type has a bespoke system prompt and focused toolset.
 
-1. **Auto-Delegation**: Claude Code automatically delegates complex tasks to the Stravinsky orchestrator
-2. **Hook-Based Control**: PreToolUse hooks intercept direct tool calls and enforce delegation patterns
-3. **Parallel Execution**: Task tool enables true parallel execution of specialist agents
-4. **Multi-Model Routing**: Specialists use invoke_gemini/openai MCP tools for multi-model access
+---
 
-### Agent Types
+## Model Proxy (NEW in v0.4.58)
 
-| Agent | Model | Cost | Use For |
-|-------|-------|------|---------|
-| **stravinsky** | Claude Sonnet 4.5 (32k thinking) | Moderate | Auto-delegating orchestrator (primary) |
-| **explore** | Gemini 3 Flash (via MCP) | Free | Code search, always async |
-| **dewey** | Gemini 3 Flash + WebSearch | Cheap | Documentation research, always async |
-| **code-reviewer** | Claude Sonnet (native) | Cheap | Quality analysis, always async |
-| **debugger** | Claude Sonnet (native) | Medium | Root cause (after 2+ failures) |
-| **frontend** | Gemini 3 Pro High (via MCP) | Medium | ALL visual changes (blocking) |
-| **delphi** | GPT-5.2 Medium (via MCP) | Expensive | Architecture (after 3+ failures) |
+To solve the "Head-of-Line Blocking" problem in MCP stdio, Stravinsky now includes a dedicated **Model Proxy**.
 
-### Delegation Rules (oh-my-opencode Pattern)
+### The Problem:
+When Claude calls `invoke_gemini` directly through MCP, the entire stdio communication channel is blocked until the model finishes generating. This prevents parallel execution and makes the UI feel sluggish.
 
-- **Always Async**: explore, dewey, code-reviewer (free/cheap)
-- **Blocking**: debugger (2+ failures), frontend (ALL visual), delphi (3+ failures or architecture)
-- **Never Work Alone**: Orchestrator blocks Read/Grep/Bash via PreToolUse hooks
+### The Solution:
+The **Stravinsky Model Proxy** runs as a separate FastAPI process. Model requests are offloaded to this process, allowing the MCP bridge to handle other tool calls immediately.
 
-### ULTRATHINK / ULTRAWORK
+### Performance Benefits:
+- **Async Concurrency**: Handle 20+ simultaneous model calls with <10ms overhead.
+- **Zero CLI Blocking**: Keep the main Claude CLI responsive during long generations.
+- **Observability**: Real-time request tracking, Process-Time headers, and trace IDs.
 
-- **ULTRATHINK**: Engage exhaustive deep reasoning with extended thinking budget (32k tokens)
-- **ULTRAWORK**: Maximum parallel execution - spawn all async agents immediately
+### Usage:
+1. **Start the Proxy** in a separate terminal:
+   ```bash
+   stravinsky-proxy
+   ```
+2. **Enable in Claude**: Set the environment variable:
+   ```bash
+   export STRAVINSKY_USE_PROXY=true
+   ```
 
 ---
 
-## Tools (40)
+## Features
 
 | Category         | Tools                                                                              |
 | ---------------- | ---------------------------------------------------------------------------------- |
-| **Model Invoke** | `invoke_gemini`, `invoke_openai`, `get_system_health`                              |
-| **Environment**  | `get_project_context`, `task_spawn`, `task_status`, `task_list`                    |
-| **Agents**       | `agent_spawn`, `agent_output`, `agent_cancel`, `agent_list`, `agent_progress`, `agent_retry` |
-| **Code Search**  | `ast_grep_search`, `ast_grep_replace`, `grep_search`, `glob_files`                 |
-| **Semantic**     | `semantic_search`, `semantic_index`, `semantic_stats`, `cancel_indexing`, `delete_index` |
+| **Model Invoke** | `invoke_gemini`, `invoke_gemini_agentic`, `invoke_openai` (3 tools)                |
+| **Environment**  | `get_project_context`, `get_system_health`, `stravinsky_version`, `system_restart`, `semantic_health`, `lsp_health` (6 tools) |
+| **Background Tasks** | `task_spawn`, `task_status`, `task_list` (3 tools)                             |
+| **Agents**       | `agent_spawn`, `agent_output`, `agent_cancel`, `agent_list`, `agent_progress`, `agent_retry` (6 tools) |
+| **Code Search**  | `ast_grep_search`, `ast_grep_replace`, `grep_search`, `glob_files` (4 tools)       |
+| **Semantic**     | `semantic_search`, `hybrid_search`, `semantic_index`, `semantic_stats`, `start_file_watcher`, `stop_file_watcher`, `cancel_indexing`, `delete_index`, `list_file_watchers`, `multi_query_search`, `decomposed_search`, `enhanced_search` (12 tools) |
 | **LSP**          | `lsp_diagnostics`, `lsp_hover`, `lsp_goto_definition`, `lsp_find_references`, `lsp_document_symbols`, `lsp_workspace_symbols`, `lsp_prepare_rename`, `lsp_rename`, `lsp_code_actions`, `lsp_code_action_resolve`, `lsp_extract_refactor`, `lsp_servers` (12 tools) |
-| **Sessions**     | `session_list`, `session_read`, `session_search`                                   |
-| **Skills**       | `skill_list`, `skill_get`                                                          |
+| **Sessions**     | `session_list`, `session_read`, `session_search` (3 tools)                         |
+| **Skills**       | `skill_list`, `skill_get` (2 tools)                                                |
 
 ### LSP Performance & Refactoring