anvil-dev-framework 0.1.8 → 0.1.9

package/global/lib/token_metrics.py

@@ -356,12 +356,36 @@ class TokenMetrics:
     # Recording Methods
     # =========================================================================
 
+    def _update_session_total(self, tokens: int) -> None:
+        """
+        Add tokens to the session total in the database.
+
+        This ensures the sessions table reflects actual consumption,
+        not just the in-memory cumulative total.
+
+        Args:
+            tokens: Number of tokens to add to the session total
+        """
+        if not self._session_id:
+            return
+
+        with self._get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute("""
+                UPDATE sessions
+                SET total_tokens = total_tokens + ?,
+                    peak_context_tokens = MAX(peak_context_tokens, ?)
+                WHERE session_id = ?
+            """, (tokens, self._peak_tokens, self._session_id))
+            conn.commit()
+
     def record_component_load(
         self,
         component_type: str,
         component_name: str,
         tokens: int,
-        source: Optional[str] = None
+        source: Optional[str] = None,
+        _skip_total_update: bool = False
     ) -> None:
         """
         Record a component being loaded into context.
@@ -371,12 +395,14 @@ class TokenMetrics:
             component_name: Name of the component
             tokens: Estimated token count
             source: Source file path or API endpoint
+            _skip_total_update: Internal flag to skip total updates (for cross-referencing)
         """
         if not self._session_id:
             return
 
-        self._cumulative_tokens += tokens
-        self._peak_tokens = max(self._peak_tokens, self._cumulative_tokens)
+        if not _skip_total_update:
+            self._cumulative_tokens += tokens
+            self._peak_tokens = max(self._peak_tokens, self._cumulative_tokens)
 
         with self._get_connection() as conn:
             cursor = conn.cursor()
@@ -387,6 +413,10 @@ class TokenMetrics:
             """, (self._session_id, component_type, component_name, tokens, source))
             conn.commit()
 
+        # Update session total in database
+        if not _skip_total_update:
+            self._update_session_total(tokens)
+
     def record_tool_call(
         self,
         tool_name: str,
@@ -417,6 +447,22 @@ class TokenMetrics:
             """, (self._session_id, tool_name, input_tokens, output_tokens))
             conn.commit()
 
+        # Update session total in database
+        self._update_session_total(total)
+
+        # Auto-mark tool as used if it produced output (ANV-294)
+        # First record as component load, then mark as used (CR feedback)
+        # Skip total update since tool_call already counted these tokens
+        if output_tokens > 0:
+            self.record_component_load(
+                component_type="tool",
+                component_name=f"tool:{tool_name}",
+                tokens=total,
+                source="tool_call",
+                _skip_total_update=True
+            )
+            self.mark_component_used(f"tool:{tool_name}")
+
     def mark_component_used(self, component_name: str) -> None:
         """
         Mark a loaded component as actually used.

package/global/tests/test_command_tracker.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""
+Unit tests for command_tracker.py (ANV-293)
+
+Run with: python3 -m pytest global/tests/test_command_tracker.py -v
+"""
+
+import sys
+import os
+import tempfile
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
+
+from token_metrics import TokenMetrics
+from command_tracker import (
+    track_command_load,
+    get_command_token_estimate,
+    _find_command_content,
+)
+
+
+class TestCommandTracker:
+    """Tests for command tracking functionality."""
+
+    def setup_method(self):
+        """Create a fresh metrics instance with temp database."""
+        self.temp_dir = tempfile.mkdtemp()
+        self.db_path = Path(self.temp_dir) / "test_metrics.db"
+
+        # Create a temp command file
+        self.cmd_dir = Path(self.temp_dir) / ".claude" / "commands"
+        self.cmd_dir.mkdir(parents=True)
+        self.test_command = self.cmd_dir / "test-cmd.md"
+        self.test_command.write_text("# Test Command\n\nThis is a test command for tracking.")
+
+        # Change to temp dir so command finding works
+        self.original_cwd = os.getcwd()
+        os.chdir(self.temp_dir)
+
+        # Initialize metrics with temp database
+        self.metrics = TokenMetrics(db_path=self.db_path)
+        self.metrics.start_session()
+
+        # Patch get_metrics to return our test instance
+        import command_tracker
+        self._original_get_metrics = command_tracker.get_metrics
+        command_tracker.get_metrics = lambda: self.metrics
+
+    def teardown_method(self):
+        """Clean up temp files and restore state."""
+        self.metrics.end_session()
+        os.chdir(self.original_cwd)
+
+        # Restore get_metrics
+        import command_tracker
+        command_tracker.get_metrics = self._original_get_metrics
+
+        # Clean up temp files
+        if self.db_path.exists():
+            self.db_path.unlink()
+        if self.test_command.exists():
+            self.test_command.unlink()
+        self.cmd_dir.rmdir()
+        (Path(self.temp_dir) / ".claude").rmdir()
+        os.rmdir(self.temp_dir)
+
+    def test_track_command_load_with_source_path(self):
+        """Should track command load when source path is provided."""
+        tokens = track_command_load("test-cmd", source_path=str(self.test_command))
+
+        assert tokens is not None
+        assert tokens > 0
+
+        # Verify it was recorded in the database
+        summary = self.metrics.get_session_summary()
+        assert summary.total_tokens >= tokens
+        assert "command" in summary.component_breakdown
+
+    def test_track_command_load_with_content(self):
+        """Should track command load when content is provided directly."""
+        content = "# Direct Content\n\nThis is test content."
+        tokens = track_command_load("direct-cmd", content=content)
+
+        assert tokens is not None
+        assert tokens > 0
+
+        summary = self.metrics.get_session_summary()
+        assert summary.total_tokens >= tokens
+
+    def test_track_command_load_finds_file_automatically(self):
+        """Should find command file in known locations."""
+        tokens = track_command_load("test-cmd")
+
+        assert tokens is not None
+        assert tokens > 0
+
+    def test_track_command_load_nonexistent_command(self):
+        """Should handle nonexistent commands gracefully."""
+        tokens = track_command_load("nonexistent-cmd")
+
+        # Should return 0 or None when content can't be found
+        assert tokens is None or tokens == 0
+
+    def test_find_command_content(self):
+        """Should find command content from known locations."""
+        content = _find_command_content("test-cmd")
+        assert content is not None
+        assert "Test Command" in content
+
+    def test_find_command_content_not_found(self):
+        """Should return None for commands that don't exist."""
+        content = _find_command_content("nonexistent-cmd")
+        assert content is None
+
+    def test_get_command_token_estimate(self):
+        """Should estimate tokens without recording."""
+        estimate = get_command_token_estimate("test-cmd")
+
+        assert estimate is not None
+        assert estimate > 0
+
+        # Verify nothing was recorded (no change to session)
+        summary = self.metrics.get_session_summary()
+        assert summary.total_tokens == 0
+
+    def test_track_command_multiple_loads(self):
+        """Should track multiple command loads."""
+        tokens1 = track_command_load("test-cmd")
+        tokens2 = track_command_load("test-cmd")
+
+        assert tokens1 is not None
+        assert tokens2 is not None
+
+        summary = self.metrics.get_session_summary()
+        assert summary.total_tokens >= tokens1 + tokens2
+
+
+class TestCommandTrackerNoSession:
+    """Tests for command tracking without active session."""
+
+    def setup_method(self):
+        """Create metrics instance without starting session."""
+        self.temp_dir = tempfile.mkdtemp()
+        self.db_path = Path(self.temp_dir) / "test_metrics.db"
+
+        self.metrics = TokenMetrics(db_path=self.db_path)
+        # Note: NOT starting session
+
+        import command_tracker
+        self._original_get_metrics = command_tracker.get_metrics
+        command_tracker.get_metrics = lambda: self.metrics
+
+    def teardown_method(self):
+        """Clean up."""
+        import command_tracker
+        command_tracker.get_metrics = self._original_get_metrics
+
+        if self.db_path.exists():
+            self.db_path.unlink()
+        os.rmdir(self.temp_dir)
+
+    def test_track_without_session_returns_none(self):
+        """Should return None when no session is active."""
+        tokens = track_command_load("test-cmd", content="Test content")
+        assert tokens is None
+
+
+if __name__ == "__main__":
+    import pytest
+    pytest.main([__file__, "-v"])

package/global/tests/test_token_metrics.py

@@ -244,6 +244,44 @@ class TestToolCallRecording:
         summary = self.metrics.get_session_summary()
         assert summary.total_tokens == 350
 
+    def test_auto_mark_tool_used_on_output(self):
+        """Should auto-mark tool as used when output_tokens > 0 (ANV-294)."""
+        # First, load a component with matching name
+        self.metrics.record_component_load("tool", "tool:Bash", 100)
+
+        # Record tool call with output
+        self.metrics.record_tool_call("Bash", 50, 200)
+
+        # Check that the component was marked as used
+        with self.metrics._get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute("""
+                SELECT was_used FROM component_loads
+                WHERE component_name = 'tool:Bash' AND session_id = ?
+            """, (self.metrics._session_id,))
+            row = cursor.fetchone()
+            assert row is not None
+            assert row['was_used'] == 1
+
+    def test_no_auto_mark_tool_with_zero_output(self):
+        """Should NOT auto-mark tool when output_tokens is 0."""
+        # Load a component
+        self.metrics.record_component_load("tool", "tool:Bash", 100)
+
+        # Record tool call WITHOUT output (0 output tokens)
+        self.metrics.record_tool_call("Bash", 50, 0)
+
+        # Check that the component was NOT marked as used
+        with self.metrics._get_connection() as conn:
+            cursor = conn.cursor()
+            cursor.execute("""
+                SELECT was_used FROM component_loads
+                WHERE component_name = 'tool:Bash' AND session_id = ?
+            """, (self.metrics._session_id,))
+            row = cursor.fetchone()
+            assert row is not None
+            assert row['was_used'] == 0
+
 
 class TestBudgetManagement:
     """Tests for token budget functionality."""

package/global/tools/README.md

@@ -176,3 +176,156 @@ uv run global/tools/anvil-hud.py
 **Context not updating**
 - Verify `post_tool_use.py` has `--update-agent` flag
 - Check that hook is receiving context_window data from Claude Code
+
+---
+
+## ralph-watch
+
+Live terminal monitor for Ralph autonomous execution sessions. Shows real-time progress, event stream, and Linear subtask status.
+
+### Usage
+
+```bash
+# Watch current directory session
+python3 global/tools/ralph-watch
+
+# Compact single-line display
+python3 global/tools/ralph-watch --compact
+
+# Custom state file location
+python3 global/tools/ralph-watch --state /path/to/.claude/ralph-state.json
+
+# Hide event stream
+python3 global/tools/ralph-watch --no-events
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit |
+| `r` | Force refresh |
+| `e` | Toggle event stream |
+| `c` | Toggle compact mode |
+
+### Display Modes
+
+**Full Mode** (default)
+- Progress bar with completion percentage
+- Linear subtask status (if enabled)
+- Recent event stream
+- Warnings for circuit breaker and checkpoints
+
+**Compact Mode** (`--compact` or press `c`)
+- Single-line status display
+- Shows: task name, status, iteration, progress, duration
+- Ideal for embedding in tmux status bar
+
+### Features
+
+- **Real-time Updates**: 1-second polling of Ralph state file
+- **Progress Tracking**: Visual progress bar with subtask counts
+- **Linear Integration**: Shows Linear subtask completion status
+- **Event Stream**: Recent events with timestamps and icons
+- **Warning Indicators**: Circuit breaker and checkpoint alerts
+
+### Example Output
+
+```
+╔═══════════════════════════════════════════════════════════════════╗
+║ 🐺 Ralph Session Monitor                                          ║
+╠═══════════════════════════════════════════════════════════════════╣
+║ Task: Migration Task
+║ Status: RUNNING │ Iteration: 5 │ Duration: 12:34
+║ Progress: [================        ] 67% (4/6)
+╠───────────────────────────────────────────────────────────────────╣
+║ Linear Subtasks:
+║   ✅ ANV-101: Phase 1 Setup
+║   ✅ ANV-102: Core Implementation
+║   ⬜ ANV-103: Testing
+╠───────────────────────────────────────────────────────────────────╣
+║ Recent Events:
+║   ✅ 2026-01-17T17:30:00 subtask_complete
+║   🔄 2026-01-17T17:25:00 iteration_complete
+╠═══════════════════════════════════════════════════════════════════╣
+║ q:quit  r:refresh  e:events  c:compact                            ║
+╚═══════════════════════════════════════════════════════════════════╝
+```
+
+### Integration with Ralph
+
+The watcher reads from:
+- `.claude/ralph-state.json` - Current session state
+- `~/.anvil/events/current-session.jsonl` - Event stream
+
+Start the watcher in a split terminal while running Ralph:
+
+```bash
+# Terminal 1: Run Ralph
+while :; do cat PROMPT.md | npx @anthropic-ai/claude-code --print; done
+
+# Terminal 2: Watch progress
+python3 global/tools/ralph-watch
+```
+
+---
+
+## Ralph Notification System
+
+Additional tools for Ralph visibility:
+
+### ralph_notifier.py
+
+Dispatches notifications for Ralph events.
+
+```bash
+# Show current config
+python3 global/lib/ralph_notifier.py --config
+
+# Toggle notifications
+python3 global/lib/ralph_notifier.py --disable tts
+python3 global/lib/ralph_notifier.py --enable macos
+python3 global/lib/ralph_notifier.py --disable all
+
+# Test notifications
+python3 global/lib/ralph_notifier.py --test-macos "Test message"
+python3 global/lib/ralph_notifier.py --test-tts "Hello from Ralph"
+
+# Dispatch pending events
+python3 global/lib/ralph_notifier.py --dispatch
+```
+
+### ralph_webhooks.py
+
+Sends Ralph events to Slack/Discord webhooks.
+
+```bash
+# Test webhooks
+python3 global/lib/ralph_webhooks.py --test-slack $SLACK_WEBHOOK_URL
+python3 global/lib/ralph_webhooks.py --test-discord $DISCORD_WEBHOOK_URL
+
+# Dispatch to configured webhooks
+python3 global/lib/ralph_webhooks.py --dispatch
+```
+
+### ralph_api.py
+
+HTTP API server with SSE for real-time events.
+
+```bash
+# Start API server
+python3 global/api/ralph_api.py --port 8765
+
+# With API key authentication
+python3 global/api/ralph_api.py --api-key "your-secret-key"
+```
+
+**Endpoints:**
+- `GET /health` - Server health check
+- `GET /status` - Current session status
+- `GET /events` - SSE event stream
+- `GET /history` - Recent event history
+- `GET /sessions` - Past session summaries
+- `POST /control` - Control commands (stop)
+
+See `global/api/openapi.yaml` for full API documentation.

package/global/tools/anvil-hud.py

@@ -82,6 +82,13 @@ try:
 except ImportError:
     CodeRabbitService = None
 
+# ANV-277: CodeRabbit Metrics for weekly stats in HUD
+try:
+    from coderabbit_metrics import CodeRabbitMetrics, WeeklySummary
+except ImportError:
+    CodeRabbitMetrics = None
+    WeeklySummary = None
+
 try:
     from config_service import get_config, get_config_service, HUDConfig
 except ImportError:
@@ -290,12 +297,13 @@ class TaskPanel(Static):
 
 
 class QualityPanel(Static):
-    """Widget displaying quality gate status (ANV-103/104/105, ANV-111-115)."""
+    """Widget displaying quality gate status (ANV-103/104/105, ANV-111-115, ANV-277)."""
 
     agents: reactive[Dict[str, Any]] = reactive({})
     quality_results: reactive[Dict[str, Any]] = reactive({})
     github_status: reactive[Dict[str, Any]] = reactive({})  # ANV-111-113
     coderabbit_status: reactive[Dict[str, Any]] = reactive({})  # ANV-114-115
+    weekly_metrics: reactive[Dict[str, Any]] = reactive({})  # ANV-277: Weekly CR metrics
 
     def compose(self) -> ComposeResult:
         yield Static(id="quality-panel-content")
@@ -316,6 +324,10 @@ class QualityPanel(Static):
         """Update display when CodeRabbit status changes."""
         self._refresh_display()
 
+    def watch_weekly_metrics(self, metrics: Dict[str, Any]) -> None:
+        """Update display when weekly metrics change (ANV-277)."""
+        self._refresh_display()
+
     def _refresh_display(self) -> None:
         """Refresh the quality panel display."""
         content = self.query_one("#quality-panel-content", Static)
@@ -478,6 +490,43 @@ class QualityPanel(Static):
 
             text.append("\n")
 
+        # ANV-277: CodeRabbit Weekly Metrics Summary
+        if self.weekly_metrics:
+            text.append("─" * 36 + "\n", style="dim")
+            text.append("CODERABBIT WEEKLY\n", style="bold cyan")
+
+            total_reviews = self.weekly_metrics.get("total_reviews", 0)
+            total_issues = self.weekly_metrics.get("total_issues_found", 0)
+            total_fixed = self.weekly_metrics.get("total_issues_fixed", 0)
+            avg_issues = self.weekly_metrics.get("avg_issues_per_review", 0)
+            pass_rate = self.weekly_metrics.get("pass_rate", 0)
+            trend = self.weekly_metrics.get("trend", "stable")
+
+            text.append(f"  Reviews: ", style="dim")
+            text.append(f"{total_reviews}\n", style="white")
+
+            text.append(f"  Issues: ", style="dim")
+            text.append(f"{total_issues} found", style="yellow" if total_issues > 0 else "green")
+            text.append(f" / {total_fixed} fixed\n", style="green" if total_fixed > 0 else "dim")
+
+            text.append(f"  Avg/Review: ", style="dim")
+            avg_color = "green" if avg_issues < 2 else "yellow" if avg_issues < 5 else "red"
+            text.append(f"{avg_issues:.1f}\n", style=avg_color)
+
+            text.append(f"  Pass Rate: ", style="dim")
+            pass_color = "green" if pass_rate >= 50 else "yellow" if pass_rate >= 25 else "red"
+            text.append(f"{pass_rate:.0f}%\n", style=pass_color)
+
+            text.append(f"  Trend: ", style="dim")
+            if trend == "improving":
+                text.append("↑ improving\n", style="green")
+            elif trend == "degrading":
+                text.append("↓ degrading\n", style="red")
+            else:
+                text.append("→ stable\n", style="dim")
+
+            text.append("\n")
+
         # Summary
         text.append("─" * 36 + "\n", style="dim")
         ready_count = sum(1 for r in self.quality_results.values() if r.get("ready_to_merge"))
@@ -2377,6 +2426,7 @@ class AnvilHUD(App):
         self.coordination_service: Optional["CoordinationService"] = None
         self.github_service: Optional["GitHubService"] = None  # ANV-111-113
         self.coderabbit_service: Optional["CodeRabbitService"] = None  # ANV-114-115
+        self.coderabbit_metrics: Optional["CodeRabbitMetrics"] = None  # ANV-277: Weekly metrics
         self.issue_provider = None  # ANV-76: Issue provider for Kanban
         self.refresh_timer: Optional[Timer] = None
 
@@ -2393,6 +2443,12 @@ class AnvilHUD(App):
         if not self.demo_mode and CodeRabbitService:
             if not self.config or self.config.integrations.enable_coderabbit:
                 self.coderabbit_service = CodeRabbitService()
+        # ANV-277: Initialize CodeRabbit metrics for weekly stats
+        if not self.demo_mode and CodeRabbitMetrics:
+            try:
+                self.coderabbit_metrics = CodeRabbitMetrics()
+            except Exception:
+                self.coderabbit_metrics = None
         # ANV-76: Initialize issue provider
         if not self.demo_mode and get_provider:
             try:
@@ -2731,6 +2787,24 @@ class AnvilHUD(App):
                 quality_panel.github_status
             )
 
+        # ANV-277: Update CodeRabbit weekly metrics
+        if self.demo_mode:
+            quality_panel.weekly_metrics = self._get_demo_weekly_metrics()
+        elif self.coderabbit_metrics:
+            try:
+                summary = self.coderabbit_metrics.get_weekly_summary()
+                if summary:
+                    quality_panel.weekly_metrics = {
+                        "total_reviews": summary.total_reviews,
+                        "total_issues_found": summary.total_issues_found,
+                        "total_issues_fixed": summary.total_issues_fixed,
+                        "avg_issues_per_review": summary.avg_issues_per_review,
+                        "pass_rate": summary.pass_rate,
+                        "trend": summary.trend,
+                    }
+            except Exception:
+                pass  # Keep previous metrics on error
+
         # Update coordination panel (ANV-106-110)
         coordination_panel = self.query_one("#coordination-panel", CoordinationPanel)
         coordination_panel.agents = agents
@@ -3422,6 +3496,17 @@ class AnvilHUD(App):
             },
         }
 
+    def _get_demo_weekly_metrics(self) -> Dict[str, Any]:
+        """Generate demo CodeRabbit weekly metrics for testing (ANV-277)."""
+        return {
+            "total_reviews": 12,
+            "total_issues_found": 28,
+            "total_issues_fixed": 24,
+            "avg_issues_per_review": 2.3,
+            "pass_rate": 42.0,
+            "trend": "improving",
+        }
+
     def _get_demo_agents(self) -> Dict[str, Any]:
         """Generate demo agent data for testing."""
         now = datetime.now(timezone.utc).isoformat()