zwarm 1.3.10__py3-none-any.whl

zwarm/watchers/manager.py

@@ -0,0 +1,181 @@
+"""
+Watcher manager for running multiple watchers.
+
+Handles:
+- Running watchers in parallel
+- Combining results by priority
+- Injecting guidance into orchestrator
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+import weave
+
+from zwarm.watchers.base import Watcher, WatcherContext, WatcherResult, WatcherAction
+from zwarm.watchers.registry import get_watcher
+
+
+@dataclass
+class WatcherConfig:
+    """Configuration for a watcher instance."""
+
+    name: str
+    enabled: bool = True
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+class WatcherManager:
+    """
+    Manages and runs multiple watchers.
+
+    Watchers run in parallel and results are combined by priority.
+    """
+
+    def __init__(self, watcher_configs: list[WatcherConfig | dict] | None = None):
+        """
+        Initialize manager with watcher configurations.
+
+        Args:
+            watcher_configs: List of WatcherConfig or dicts with watcher configs
+        """
+        self._watchers: list[Watcher] = []
+        self._results_history: list[tuple[str, WatcherResult]] = []
+
+        # Load watchers from configs
+        for cfg in watcher_configs or []:
+            if isinstance(cfg, dict):
+                cfg = WatcherConfig(**cfg)
+
+            if cfg.enabled:
+                try:
+                    watcher = get_watcher(cfg.name, cfg.config)
+                    self._watchers.append(watcher)
+                except ValueError:
+                    # Unknown watcher, skip
+                    pass
+
+    def add_watcher(self, watcher: Watcher) -> None:
+        """Add a watcher instance."""
+        self._watchers.append(watcher)
+
+    @weave.op()
+    async def _run_single_watcher(
+        self,
+        watcher_name: str,
+        watcher: Watcher,
+        ctx: WatcherContext,
+    ) -> dict[str, Any]:
+        """Run a single watcher - traced by Weave."""
+        try:
+            result = await watcher.observe(ctx)
+            return {
+                "watcher": watcher_name,
+                "action": result.action.value,
+                "priority": result.priority,
+                "reason": result.reason,
+                "guidance": result.guidance,
+                "metadata": result.metadata,
+                "success": True,
+            }
+        except Exception as e:
+            return {
+                "watcher": watcher_name,
+                "success": False,
+                "error": str(e),
+            }
+
+    @weave.op()
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        """
+        Run all watchers and return combined result.
+
+        Results are combined by priority:
+        - ABORT takes precedence over everything
+        - PAUSE takes precedence over NUDGE
+        - NUDGE takes precedence over CONTINUE
+        - Within same action, higher priority wins
+
+        Args:
+            ctx: Context for watchers
+
+        Returns:
+            Combined WatcherResult
+        """
+        if not self._watchers:
+            return WatcherResult.ok()
+
+        # Run all watchers in parallel - each traced individually
+        tasks = [
+            self._run_single_watcher(watcher.name, watcher, ctx)
+            for watcher in self._watchers
+        ]
+        watcher_outputs = await asyncio.gather(*tasks)
+
+        # Collect valid results with their watcher names
+        valid_results: list[tuple[str, WatcherResult]] = []
+        for watcher, output in zip(self._watchers, watcher_outputs):
+            if not output.get("success"):
+                # Log and skip failed watchers
+                continue
+            result = WatcherResult(
+                action=WatcherAction(output["action"]),
+                priority=output["priority"],
+                reason=output.get("reason"),
+                guidance=output.get("guidance"),
+                metadata=output.get("metadata", {}),
+            )
+            valid_results.append((watcher.name, result))
+            self._results_history.append((watcher.name, result))
+
+        if not valid_results:
+            return WatcherResult.ok()
+
+        # Sort by action severity (abort > pause > nudge > continue) then priority
+        def sort_key(item: tuple[str, WatcherResult]) -> tuple[int, int]:
+            _, result = item
+            action_order = {
+                WatcherAction.ABORT: 0,
+                WatcherAction.PAUSE: 1,
+                WatcherAction.NUDGE: 2,
+                WatcherAction.CONTINUE: 3,
+            }
+            return (action_order[result.action], -result.priority)
+
+        valid_results.sort(key=sort_key)
+
+        # Return highest priority non-continue result
+        for name, result in valid_results:
+            if result.action != WatcherAction.CONTINUE:
+                # Add which watcher triggered this
+                result.metadata["triggered_by"] = name
+                return result
+
+        return WatcherResult.ok()
+
+    def get_history(self) -> list[tuple[str, WatcherResult]]:
+        """Get history of all watcher results."""
+        return list(self._results_history)
+
+    def clear_history(self) -> None:
+        """Clear results history."""
+        self._results_history.clear()
+
+
+def build_watcher_manager(
+    config: dict[str, Any] | None = None
+) -> WatcherManager:
+    """
+    Build a WatcherManager from configuration.
+
+    Args:
+        config: Dict with "watchers" key containing list of watcher configs
+
+    Returns:
+        Configured WatcherManager
+    """
+    watcher_configs = (config or {}).get("watchers", [])
+    return WatcherManager(watcher_configs)

zwarm/watchers/registry.py

@@ -0,0 +1,57 @@
+"""
+Watcher registry for discovering and instantiating watchers.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Type
+
+from zwarm.watchers.base import Watcher
+
+
+# Global watcher registry
+_WATCHERS: dict[str, Type[Watcher]] = {}
+
+
+def register_watcher(name: str):
+    """
+    Decorator to register a watcher class.
+
+    Example:
+        @register_watcher("progress")
+        class ProgressWatcher(Watcher):
+            ...
+    """
+
+    def decorator(cls: Type[Watcher]) -> Type[Watcher]:
+        cls.name = name
+        _WATCHERS[name] = cls
+        return cls
+
+    return decorator
+
+
+def get_watcher(name: str, config: dict[str, Any] | None = None) -> Watcher:
+    """
+    Get a watcher instance by name.
+
+    Args:
+        name: Registered watcher name
+        config: Optional config to pass to watcher
+
+    Returns:
+        Instantiated watcher
+
+    Raises:
+        ValueError: If watcher not found
+    """
+    if name not in _WATCHERS:
+        raise ValueError(
+            f"Unknown watcher: {name}. Available: {list(_WATCHERS.keys())}"
+        )
+    return _WATCHERS[name](config)
+
+
+def list_watchers() -> list[str]:
+    """List all registered watcher names."""
+    return list(_WATCHERS.keys())

zwarm/watchers/test_watchers.py

@@ -0,0 +1,237 @@
+"""Tests for the watcher system."""
+
+import pytest
+
+from zwarm.watchers import (
+    Watcher,
+    WatcherContext,
+    WatcherResult,
+    WatcherAction,
+    WatcherManager,
+    WatcherConfig,
+    get_watcher,
+    list_watchers,
+)
+
+
+class TestWatcherRegistry:
+    def test_list_watchers(self):
+        """Built-in watchers should be registered."""
+        watchers = list_watchers()
+        assert "progress" in watchers
+        assert "budget" in watchers
+        assert "scope" in watchers
+        assert "pattern" in watchers
+        assert "quality" in watchers
+
+    def test_get_watcher(self):
+        """Can get watcher by name."""
+        watcher = get_watcher("progress")
+        assert watcher.name == "progress"
+
+    def test_get_unknown_watcher(self):
+        """Unknown watcher raises error."""
+        with pytest.raises(ValueError, match="Unknown watcher"):
+            get_watcher("nonexistent")
+
+
+class TestProgressWatcher:
+    @pytest.mark.asyncio
+    async def test_continues_on_normal_progress(self):
+        """Normal progress should continue."""
+        watcher = get_watcher("progress")
+        ctx = WatcherContext(
+            task="Test task",
+            step=2,
+            max_steps=10,
+            messages=[
+                {"role": "user", "content": "Start"},
+                {"role": "assistant", "content": "Working on it"},
+            ],
+        )
+        result = await watcher.observe(ctx)
+        assert result.action == WatcherAction.CONTINUE
+
+
+class TestBudgetWatcher:
+    @pytest.mark.asyncio
+    async def test_warns_at_budget_threshold(self):
+        """Should warn when approaching step limit."""
+        watcher = get_watcher("budget", {"warn_at_percent": 80})
+        ctx = WatcherContext(
+            task="Test task",
+            step=9,  # 90% of max
+            max_steps=10,
+            messages=[],
+        )
+        result = await watcher.observe(ctx)
+        assert result.action == WatcherAction.NUDGE
+        assert "remaining" in result.guidance.lower()
+
+    @pytest.mark.asyncio
+    async def test_continues_when_under_budget(self):
+        """Should continue when well under budget."""
+        watcher = get_watcher("budget")
+        ctx = WatcherContext(
+            task="Test task",
+            step=2,
+            max_steps=10,
+            messages=[],
+        )
+        result = await watcher.observe(ctx)
+        assert result.action == WatcherAction.CONTINUE
+
+    @pytest.mark.asyncio
+    async def test_only_counts_active_sessions(self):
+        """Should only count active sessions, not completed/failed ones."""
+        watcher = get_watcher("budget", {"max_sessions": 2})
+        # Create 5 sessions: 1 active, 2 completed, 2 failed
+        ctx = WatcherContext(
+            task="Test task",
+            step=2,
+            max_steps=10,
+            messages=[],
+            sessions=[
+                {"id": "s1", "status": "active"},
+                {"id": "s2", "status": "completed"},
+                {"id": "s3", "status": "completed"},
+                {"id": "s4", "status": "failed"},
+                {"id": "s5", "status": "failed"},
+            ],
+        )
+        # Should continue because only 1 active session (limit is 2)
+        result = await watcher.observe(ctx)
+        assert result.action == WatcherAction.CONTINUE
+
+    @pytest.mark.asyncio
+    async def test_warns_when_active_sessions_at_limit(self):
+        """Should warn when active sessions reach the limit."""
+        watcher = get_watcher("budget", {"max_sessions": 2})
+        ctx = WatcherContext(
+            task="Test task",
+            step=2,
+            max_steps=10,
+            messages=[],
+            sessions=[
+                {"id": "s1", "status": "active"},
+                {"id": "s2", "status": "active"},
+                {"id": "s3", "status": "completed"},
+            ],
+        )
+        # Should nudge because 2 active sessions (at limit)
+        result = await watcher.observe(ctx)
+        assert result.action == WatcherAction.NUDGE
+        assert "2 active sessions" in result.guidance
+
+
+class TestPatternWatcher:
+    @pytest.mark.asyncio
+    async def test_detects_pattern(self):
+        """Should detect configured patterns."""
+        watcher = get_watcher("pattern", {
+            "patterns": [
+                {"regex": r"ERROR", "action": "nudge", "message": "Error detected!"}
+            ]
+        })
+        ctx = WatcherContext(
+            task="Test task",
+            step=1,
+            max_steps=10,
+            messages=[
+                {"role": "assistant", "content": "Got ERROR in the build"}
+            ],
+        )
+        result = await watcher.observe(ctx)
+        assert result.action == WatcherAction.NUDGE
+        assert "Error detected" in result.guidance
+
+    @pytest.mark.asyncio
+    async def test_abort_pattern(self):
+        """Should abort on critical patterns."""
+        watcher = get_watcher("pattern", {
+            "patterns": [
+                {"regex": r"rm -rf /", "action": "abort", "message": "Dangerous command!"}
+            ]
+        })
+        ctx = WatcherContext(
+            task="Test task",
+            step=1,
+            max_steps=10,
+            messages=[
+                {"role": "assistant", "content": "Running rm -rf /"}
+            ],
+        )
+        result = await watcher.observe(ctx)
+        assert result.action == WatcherAction.ABORT
+
+
+class TestWatcherManager:
+    @pytest.mark.asyncio
+    async def test_runs_multiple_watchers(self):
+        """Manager runs all watchers."""
+        manager = WatcherManager([
+            WatcherConfig(name="progress"),
+            WatcherConfig(name="budget"),
+        ])
+        ctx = WatcherContext(
+            task="Test task",
+            step=2,
+            max_steps=10,
+            messages=[],
+        )
+        result = await manager.observe(ctx)
+        assert isinstance(result, WatcherResult)
+
+    @pytest.mark.asyncio
+    async def test_highest_priority_wins(self):
+        """Most severe action should win."""
+        manager = WatcherManager([
+            WatcherConfig(name="budget", config={"warn_at_percent": 50}),  # Will nudge
+            WatcherConfig(name="pattern", config={
+                "patterns": [{"regex": "ABORT", "action": "abort", "message": "Abort!"}]
+            }),
+        ])
+        ctx = WatcherContext(
+            task="Test task",
+            step=6,  # 60% - triggers budget nudge
+            max_steps=10,
+            messages=[
+                {"role": "assistant", "content": "Must ABORT now"}
+            ],
+        )
+        result = await manager.observe(ctx)
+        # Abort should take precedence over nudge
+        assert result.action == WatcherAction.ABORT
+
+    @pytest.mark.asyncio
+    async def test_empty_manager_continues(self):
+        """Manager with no watchers should continue."""
+        manager = WatcherManager([])
+        ctx = WatcherContext(
+            task="Test task",
+            step=1,
+            max_steps=10,
+            messages=[],
+        )
+        result = await manager.observe(ctx)
+        assert result.action == WatcherAction.CONTINUE
+
+    @pytest.mark.asyncio
+    async def test_disabled_watcher_skipped(self):
+        """Disabled watchers should be skipped."""
+        manager = WatcherManager([
+            WatcherConfig(name="pattern", enabled=False, config={
+                "patterns": [{"regex": ".*", "action": "abort", "message": "Always abort"}]
+            }),
+        ])
+        ctx = WatcherContext(
+            task="Test task",
+            step=1,
+            max_steps=10,
+            messages=[
+                {"role": "assistant", "content": "This would normally trigger abort"}
+            ],
+        )
+        result = await manager.observe(ctx)
+        # Since the pattern watcher is disabled, should continue
+        assert result.action == WatcherAction.CONTINUE