stravinsky 0.2.11__tar.gz → 0.2.62__tar.gz

{stravinsky-0.2.11 → stravinsky-0.2.62}/.github/workflows/publish.yml

@@ -10,7 +10,6 @@ jobs:
   build-and-publish:
     runs-on: ubuntu-latest
     permissions:
-      id-token: write # Required for trusted publishing
       contents: read
 
     steps:
@@ -33,6 +32,6 @@ jobs:
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          # Uses trusted publishing - no token needed if configured on PyPI
-          # Fallback to token if trusted publishing not set up:
-          password: ${{ secrets.PYPI_API_TOKEN }}
+          # Disable OIDC trusted publishing - use API token instead
+          attestations: false
+          password: ${{ secrets.PYPY_API_TOKEN }}

stravinsky-0.2.62/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "stravinsky": {
+      "command": "/Users/davidandrews/PycharmProjects/stravinsky/run-mcp.sh",
+      "args": []
+    }
+  }
+}

stravinsky-0.2.62/.stravinsky/agents/agent_0de66569.out

@@ -0,0 +1,117 @@
+I have the complete picture now. Here's the comprehensive summary:
+
+---
+
+## Claude Code Hooks Structure in Stravinsky - Complete Analysis
+
+### 1. Hook Files Location
+
+**Native hooks directory:** `/Users/davidandrews/PycharmProjects/stravinsky/mcp_bridge/native_hooks/`
+- `context.py` - UserPromptSubmit hook (injects README/CLAUDE.md context)
+- `edit_recovery.py` - PostToolUse for Edit error recovery
+- `stravinsky_mode.py` - PreToolUse to block native tools in orchestrator mode
+- `todo_delegation.py` - PostToolUse for TodoWrite parallel enforcement
+- `truncator.py` - PostToolUse for response truncation
+
+### 2. Configuration Format (`.claude/settings.json`)
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read,Search,Grep,Bash,Edit,MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 /absolute/path/to/hook.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 /absolute/path/to/context.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [...]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [...]
+      }
+    ]
+  }
+}
+```
+
+**Key configuration properties:**
+- `matcher`: Tool names (comma-separated) or `"*"` for all
+- `type`: `"command"` for shell commands
+- `command`: Full command to execute
+
+### 3. UserPromptSubmit Hook Pattern (context.py)
+
+```python
+import os
+import sys
+import json
+from pathlib import Path
+
+def main():
+    # 1. Read JSON input from stdin
+    try:
+        data = json.load(sys.stdin)
+        prompt = data.get("prompt", "")
+    except Exception:
+        return
+
+    # 2. Get working directory from env
+    cwd = Path(os.environ.get("CLAUDE_CWD", "."))
+    
+    # 3. Load context or modify prompt
+    new_prompt = f"[CONTEXT]\n{context}\n\n[USER PROMPT]\n{prompt}"
+    
+    # 4. Output modified prompt to stdout
+    print(new_prompt)
+
+if __name__ == "__main__":
+    main()
+```
+
+### 4. Environment Variables Available
+- `CLAUDE_CWD` - Current working directory
+- `CLAUDE_SESSION_ID` - Session ID
+- `CLAUDE_TOOL_NAME` - Tool name (for tool hooks)
+- `CLAUDE_TOOL_INPUT` - JSON of tool input
+
+### 5. Exit Codes
+- `0` - Continue normally
+- `1` - Block/deny operation
+- `2+` - Error (logged, continues)
+
+### 6. Hook Types Summary
+
+| Hook Type | Input (stdin) | Output (stdout) | Purpose |
+|-----------|---------------|-----------------|---------|
+| `UserPromptSubmit` | `{"prompt": "..."}` | Modified prompt string | Augment user prompts |
+| `PreToolUse` | `{"tool_name": "...", "tool_input": {...}}` | Exit code controls execution | Block/allow tools |
+| `PostToolUse` | `{"tool_name": "...", "tool_response": "..."}` | Modified response | Transform tool output |
+| `Stop` | Session context | Continuation prompt | Follow-up actions |
+
+### 7. For Todo Continuation Hook Implementation
+
+To create a new UserPromptSubmit hook for todo continuation:
+
+1. **Create hook file:** `.claude/hooks/todo_reminder.py`
+2. **Pattern:** Read stdin JSON → Check TODO.md or TodoWrite state → Print augmented prompt
+3. **Register in settings.json:** Add to `UserPromptSubmit` array with `"matcher": "*"`

stravinsky-0.2.62/.stravinsky/agents/agent_0de66569.system

@@ -0,0 +1,10 @@
+You are a codebase exploration specialist. Find files, patterns, and answer 'where is X?' questions.
+
+MODEL ROUTING (MANDATORY):
+You MUST use invoke_gemini with model="gemini-3-flash" for ALL analysis and reasoning.
+Use Claude's native tools (Read, Grep, Glob) ONLY for file access, then pass content to invoke_gemini.
+
+WORKFLOW:
+1. Use Read/Grep/Glob to get file contents
+2. Call invoke_gemini(prompt="Analyze this: <content>", model="gemini-3-flash", agent_context={"agent_type": "explore"}) for analysis
+3. Return the Gemini response

stravinsky-0.2.62/.stravinsky/agents/agent_2ef2b305.out

@@ -0,0 +1,142 @@
+## Delphi's Strategic Analysis: Hook Consolidation & Circular Invocation
+
+The strategic advisor (GPT-5.2) has provided comprehensive architectural analysis. Here are the key recommendations:
+
+---
+
+## Question 1: Hook Consolidation Strategy
+
+### **Recommendation: Hybrid + Unified Interface**
+
+**Core Strategy:**
+- **Native Hooks**: Keep for tool access control and "must-block" behavior (security gates)
+- **MCP Hooks**: Keep for MCP tool dispatch, model routing, session lifecycle, budgeting
+- **Unified Interface**: Create shared hook protocol with adapters for both contexts
+
+### Key Insights
+
+**Technical Analysis:**
+- "All Native" or "All MCP" create impedance mismatches because Claude Code's native tools exist outside MCP
+- Current hybrid is technically sound IF boundaries are crisp
+- Performance: MCP hooks are faster (in-process), native hooks add subprocess overhead
+
+**Security Layering:**
+- **Native**: Hard gates (deny/allow) for Claude Code tools + pre-execution redaction
+- **MCP**: Soft/hard gates for MCP tools + model invocation policy, quotas, logging
+- This layered approach provides defense in depth
+
+**Industry Pattern:**
+Matches production agentic CLI designs:
+- Native = enforcement boundary (closest to execution)
+- MCP = orchestration layer (rich lifecycle management)
+
+### Actionable Migration Path
+
+1. **Define canonical event model**: `ToolEvent`, `ModelInvokeEvent`, `SessionEvent`
+2. **Wrap existing native hooks** with compatibility shim
+3. **Port MCP hooks tier-by-tier** into unified form (lowest risk first)
+4. **Single source of truth** for policies (allow/deny lists, budgets) consumed by both contexts
+
+### Success Metrics
+- % of hook logic shared vs duplicated
+- Hook-induced latency (p50/p95)
+- Incident rate for "unexpected block" / "policy mismatch" bugs
+- Trace completeness (native + MCP share `trace_id`)
+
+---
+
+## Question 2: Circular Invocation Pattern
+
+### **Recommendation: Keep Current (Option D) + Add Local Model Proxy**
+
+**Core Strategy:**
+Decouple model transport without losing Claude Code's tool ecosystem:
+
+```
+Claude Code (main)
+  ↓
+Stravinsky MCP Server
+  ↓
+agent_spawn → Claude CLI process (agent)
+  ↓
+Agent invokes tools (Read/Grep/Bash) + invoke_gemini
+  ↓
+MCP invoke_gemini → LOCAL MODEL PROXY (Unix socket/HTTP)
+  ↓
+Model Proxy → Google Antigravity / OpenAI API
+```
+
+### Key Benefits
+
+**Performance:**
+- Breaks tight "agent → MCP stdio → provider" coupling
+- Scales concurrency independent of MCP's stdio constraints
+- Moves heavy provider I/O out of MCP event loop
+
+**Security:**
+- Keeps centralized auth/token management
+- Enables per-provider circuit breakers and rate limits
+- Maintains audit logging with unified trace IDs
+
+**Flexibility:**
+- Hybrid routing: model-only tasks can use proxy directly (no subprocess)
+- Tasks needing tools still use `agent_spawn` with full Claude Code access
+
+### Failure Mode Analysis
+
+**Current Risks:**
+- Head-of-line blocking on single MCP stdio transport
+- Re-entrancy contention with many concurrent agents
+- Cascade failures from provider rate limits
+- Zombie agents outliving orchestrator
+
+**Mitigations:**
+- Circuit breaker per provider
+- Queue + concurrency limits
+- Agent cancellation propagation
+- Persistent task ledger for resumable state
+
+### Migration Path
+
+1. **Implement model proxy** with same request/response schema as current `invoke_*`
+2. **Switch MCP tools** to proxy-backed implementation (transparent change)
+3. **Add trace ID propagation** from Claude → agent → proxy
+4. **Optional: Add hybrid routing** for model-only tasks (Python worker calling proxy directly)
+
+### Success Metrics
+- End-to-end `invoke_*` latency (p50/p95) under N concurrent agents
+- MCP protocol stability (fewer hangs/timeouts)
+- Provider error rate and retry amplification
+- Reduction in spawned Claude processes for model-only work
+
+---
+
+## Long-Term Vision (5 Years)
+
+**Hook System:**
+- Unified interface enables porting to alternative frontends (other IDEs)
+- New hook types added without duplicating semantics
+- Positions Stravinsky as "policy + orchestration layer" vs tightly coupled to one mechanism
+
+**Model Architecture:**
+- Local proxy enables multiple frontends beyond Claude Code
+- Improved caching (prompt/result memoization)
+- Single telemetry point for all model interactions
+- Simpler adoption of new providers/models
+
+**Ecosystem Compatibility:**
+- MCP evolution (multi-client, richer transport) can be absorbed independently
+- Claude Code hook API changes minimized through unified hook spec
+- New use cases: team policy packs, per-project budgets, trace replay, offline simulation
+
+---
+
+## Next Steps
+
+The advisor offers to create an actionable design document with:
+- Module structure aligned with `mcp_bridge/hooks/` and `mcp_bridge/native_hooks/`
+- Event schemas for unified hook interface
+- Ordering rules and tier semantics
+- Minimal incremental milestone plan
+
+Would you like me to proceed with creating this design document?

stravinsky-0.2.62/.stravinsky/agents/agent_2ef2b305.system

@@ -0,0 +1,9 @@
+You are a strategic technical advisor for architecture and hard debugging.
+
+MODEL ROUTING (MANDATORY):
+You MUST use invoke_openai with model="gpt-5.2" for ALL strategic advice and analysis.
+
+WORKFLOW:
+1. Gather context about the problem
+2. Call invoke_openai(prompt="<problem description>", model="gpt-5.2", agent_context={"agent_type": "delphi"})
+3. Return the GPT response

stravinsky-0.2.62/.stravinsky/agents/agent_32fc606b.out

@@ -0,0 +1,123 @@
+Perfect! Based on my exploration of the Stravinsky codebase, here's a comprehensive analysis of how agents invoke Gemini and OpenAI:
+
+## 📋 Summary: Agent Model Invocation in Stravinsky
+
+### 1. **Agent Spawn Implementation**
+
+The `agent_spawn()` function in `mcp_bridge/tools/agent_manager.py` is the core mechanism:
+
+- **Entry Point**: `agent_spawn(prompt, agent_type, description, model, thinking_budget, timeout)`
+- **Returns**: Task ID for tracking
+- **Execution**: Spawns Claude CLI subprocess with `claude -p <prompt> --dangerously-skip-permissions`
+- **Storage**: Tasks stored in `.stravinsky/agents/` directory
+
+### 2. **Model Routing Architecture**
+
+**Key Innovation**: Specialized agents DON'T use Claude directly - they're instructed via system prompts to call `invoke_gemini` or `invoke_openai`:
+
+```python
+AGENT_MODEL_ROUTING = {
+    "explore": None,           # No CLI model - uses invoke_gemini
+    "dewey": None,             # No CLI model - uses invoke_gemini  
+    "document_writer": None,   # No CLI model - uses invoke_gemini
+    "multimodal": None,        # No CLI model - uses invoke_gemini
+    "frontend": None,          # No CLI model - uses invoke_gemini
+    "delphi": None,            # No CLI model - uses invoke_openai
+    "planner": "opus",         # Direct Claude Opus via CLI
+    "_default": "sonnet",      # Direct Claude Sonnet via CLI
+}
+```
+
+### 3. **System Prompt Enforcement**
+
+Each agent type gets a mandatory system prompt that enforces model routing:
+
+**Example - Explore Agent** (lines 656-665):
+```
+You MUST use invoke_gemini with model="gemini-3-flash" for ALL analysis and reasoning.
+Use Claude's native tools (Read, Grep, Glob) ONLY for file access, then pass content to invoke_gemini.
+
+WORKFLOW:
+1. Use Read/Grep/Glob to get file contents
+2. Call invoke_gemini(prompt="Analyze this: <content>", model="gemini-3-flash") for analysis
+3. Return the Gemini response
+```
+
+**Example - Delphi Agent** (lines 692-696):
+```
+You MUST use invoke_openai with model="gpt-5.2" for ALL strategic advice and analysis.
+
+WORKFLOW:
+1. Gather context about the problem
+2. Call invoke_openai(prompt="<problem description>", model="gpt-5.2")
+3. Return the GPT response
+```
+
+### 4. **invoke_gemini Implementation**
+
+Located in `mcp_bridge/tools/model_invoke.py`:
+
+- **OAuth Flow**: Uses TokenStore with automatic refresh
+- **API**: Calls Google Antigravity API (`/v1internal:generateContent`)
+- **Features**: Session persistence for thinking cache, endpoint fallback, retry logic
+- **Thinking Support**: Supports `thinking_budget` parameter for extended reasoning
+
+### 5. **invoke_openai Implementation**
+
+Also in `model_invoke.py`:
+
+- **OAuth Flow**: Uses OpenAI ChatGPT OAuth tokens
+- **API**: Calls `chatgpt.com/backend-api/codex/responses` (SSE streaming)
+- **Features**: JWT account ID extraction, Codex instructions fetching from GitHub
+- **Streaming**: Parses SSE events for `response.output_text.delta`
+
+### 6. **Output and Logging Structure**
+
+For each spawned agent task:
+
+```
+.stravinsky/agents/
+├── agent_abc123.out      # stdout - final response from agent
+├── agent_abc123.log      # stderr - errors/warnings
+└── agent_abc123.system   # system prompt file (if custom)
+```
+
+**Key logging points**:
+- Line 248: "Spawning Claude CLI agent {task_id} ({agent_type})"
+- Line 316: "Agent {task_id} completed successfully"
+- Line 327: "Agent {task_id} failed: {error_msg}"
+
+### 7. **Agent Context & Metadata**
+
+The `AgentTask` dataclass tracks:
+
+```python
+@dataclass
+class AgentTask:
+    id: str                           # Task identifier (e.g., "agent_abc123")
+    prompt: str                       # Full task prompt
+    agent_type: str                   # explore, dewey, delphi, etc.
+    description: str                  # Short display description
+    status: str                       # pending/running/completed/failed/cancelled
+    created_at: str                   # ISO timestamp
+    started_at: Optional[str]         # When execution began
+    completed_at: Optional[str]       # When finished
+    result: Optional[str]             # Final output
+    error: Optional[str]              # Error message if failed
+    pid: Optional[int]                # Process ID for cancellation
+    timeout: int = 300                # Max execution time
+    parent_session_id: Optional[str]  # For notifications
+    progress: Optional[Dict]          # Real-time progress tracking
+```
+
+### 8. **Key Architectural Patterns**
+
+✅ **Separation of Concerns**: Claude CLI handles tool access, external models (Gemini/GPT) handle reasoning
+✅ **Cost Optimization**: Cheap models (gemini-3-flash) for exploration, expensive models (gpt-5.2) for strategy
+✅ **Non-Blocking**: All agents run in background threads, allowing parallel execution
+✅ **Persistence**: Task state survives process restarts via JSON storage
+✅ **Zombie Detection**: Progress tracking checks if PIDs still exist (line 541-555)
+
+---
+
+**Bottom Line**: Stravinsky agents are Claude CLI subprocesses that are **instructed via system prompts** to delegate their actual reasoning to Gemini or OpenAI by calling `invoke_gemini`/`invoke_openai` MCP tools. This creates a multi-model orchestration layer where Claude manages tool usage while specialized models handle domain-specific reasoning.

stravinsky-0.2.62/.stravinsky/agents/agent_32fc606b.system

@@ -0,0 +1,10 @@
+You are a codebase exploration specialist. Find files, patterns, and answer 'where is X?' questions.
+
+MODEL ROUTING (MANDATORY):
+You MUST use invoke_gemini with model="gemini-3-flash" for ALL analysis and reasoning.
+Use Claude's native tools (Read, Grep, Glob) ONLY for file access, then pass content to invoke_gemini.
+
+WORKFLOW:
+1. Use Read/Grep/Glob to get file contents
+2. Call invoke_gemini(prompt="Analyze this: <content>", model="gemini-3-flash") for analysis
+3. Return the Gemini response

stravinsky-0.2.62/.stravinsky/agents/agent_4943202a.out

@@ -0,0 +1,112 @@
+The Gemini calls aren't working. Let me analyze this directly based on the code I've read:
+
+## Analysis: Delegation and Parallel Execution in Stravinsky
+
+Based on my examination of the codebase, here's what I found:
+
+### 1. **`run_in_background` Parameter - Documentation Error**
+
+**Finding**: `run_in_background=true` appears in hook instructions but is **NOT implemented** in either the native Task tool or the MCP agent_spawn tool.
+
+**Evidence**:
+- `.claude/hooks/todo_delegation.py` (line 69-70): Shows example using `run_in_background=true`
+- `.claude/hooks/parallel_execution.py` (line 82, 95-97): Shows example using `run_in_background=true`
+- `mcp_bridge/tools/agent_manager.py` (line 646): agent_spawn has `blocking` parameter (default False), NOT `run_in_background`
+- Native Task tool: No `run_in_background` parameter exists in Claude Code's Task tool
+
+**Conclusion**: This is a **documentation inconsistency**. The hooks are providing incorrect example syntax.
+
+### 2. **Two Parallel Delegation Systems**
+
+The codebase has **TWO separate delegation mechanisms**:
+
+#### A. **Native Claude Code System** (Task tool)
+- **Where**: Used in `.claude/agents/stravinsky.md` orchestrator
+- **Tool**: Native `Task(subagent_type="explore", prompt="...", description="...")`
+- **Behavior**: Blocking by default - returns results directly in function response
+- **No async mode**: Task tool is synchronous, no background execution
+- **Usage**: Stravinsky orchestrator delegates to explore/dewey/code-reviewer/debugger/frontend
+
+#### B. **Stravinsky MCP System** (agent_spawn)
+- **Where**: `mcp_bridge/tools/agent_manager.py`
+- **Tool**: `agent_spawn(prompt="...", agent_type="explore", blocking=False)`
+- **Behavior**: 
+  - `blocking=False` (default): Returns task_id immediately, async execution
+  - `blocking=True`: Waits for completion, returns full result
+- **Collection**: Use `agent_output(task_id, block=True)` to retrieve results
+- **Usage**: MCP tools for when native subagents need to spawn their own background work
+
+### 3. **Stravinsky Mode Flow**
+
+**Activation**:
+1. User invokes `/stravinsky` skill
+2. `parallel_execution.py` (UserPromptSubmit hook) detects invocation
+3. Creates `~/.stravinsky_mode` marker file
+4. Injects parallel execution instructions into prompt
+
+**Enforcement**:
+1. `stravinsky_mode.py` (PreToolUse hook) checks for marker file
+2. Blocks Read/Grep/Bash/Edit/MultiEdit with exit code 2
+3. Forces delegation to Task tool instead
+
+**Post-TodoWrite**:
+1. `todo_delegation.py` (PostToolUse hook) fires after TodoWrite
+2. Counts pending todos
+3. If 2+ pending and stravinsky mode active: exit code 2 (HARD BLOCK)
+4. If 2+ pending and mode inactive: exit code 1 (WARNING)
+
+### 4. **Gaps and Inconsistencies**
+
+**Critical Issues**:
+
+1. **Invalid Parameter**: Hooks instruct `run_in_background=true` but this parameter doesn't exist
+   - Should be removed or corrected to match actual API
+
+2. **Mixed Metaphors**: 
+   - Hooks say "Task tool" but show agent_spawn examples
+   - `.claude/agents/stravinsky.md` uses Task tool (blocking)
+   - `mcp_bridge/hooks/parallel_enforcer.py` uses agent_spawn (async)
+
+3. **No True Parallel Task Execution**: 
+   - Native Task tool is synchronous/blocking
+   - Can call multiple Task tools in one response, but they execute sequentially
+   - True parallelism only available via agent_spawn MCP tool
+
+4. **Marker File Brittleness**:
+   - `~/.stravinsky_mode` file persists across sessions
+   - No automatic cleanup on task completion
+   - Can leak into unrelated Claude sessions
+   - Race conditions if multiple Claude instances run
+
+5. **Documentation Mismatch**:
+   - Stravinsky agent says "Task tool returns results directly - no manual collection needed"
+   - This is correct but contradicts the async/parallel narrative in hooks
+   - Hooks imply background execution but Task tool is synchronous
+
+### 5. **Correct Patterns**
+
+**For Native Subagents (stravinsky orchestrator)**:
+```python
+# Multiple Task calls in ONE response = sequential but batched
+Task(subagent_type="explore", prompt="Find X", description="Find X")
+Task(subagent_type="dewey", prompt="Research Y", description="Research Y")
+# Results returned immediately in function responses
+```
+
+**For MCP-based Async Delegation**:
+```python
+# True parallel execution
+agent_spawn(prompt="Task 1", agent_type="explore", description="Task 1")  # Returns task_id
+agent_spawn(prompt="Task 2", agent_type="dewey", description="Task 2")    # Returns task_id
+# Later collect results:
+agent_output(task_id_1, block=True)
+agent_output(task_id_2, block=True)
+```
+
+### 6. **Recommendations**
+
+1. **Fix hook examples**: Remove `run_in_background=true` or replace with correct syntax
+2. **Clarify delegation**: Document when to use Task vs agent_spawn
+3. **Cleanup marker file**: Add automatic removal of `~/.stravinsky_mode` on session end
+4. **Unify terminology**: Either "blocking/async" or "foreground/background", not both
+5. **Add validation**: Hook should validate that Task tool calls are valid syntax

stravinsky-0.2.62/.stravinsky/agents/agent_4943202a.system

@@ -0,0 +1,10 @@
+You are a codebase exploration specialist. Find files, patterns, and answer 'where is X?' questions.
+
+MODEL ROUTING (MANDATORY):
+You MUST use invoke_gemini with model="gemini-3-flash" for ALL analysis and reasoning.
+Use Claude's native tools (Read, Grep, Glob) ONLY for file access, then pass content to invoke_gemini.
+
+WORKFLOW:
+1. Use Read/Grep/Glob to get file contents
+2. Call invoke_gemini(prompt="Analyze this: <content>", model="gemini-3-flash", agent_context={"agent_type": "explore"}) for analysis
+3. Return the Gemini response