zwarm 0.1.0__py3-none-any.whl

zwarm/watchers/builtin.py

@@ -0,0 +1,256 @@
+"""
+Built-in watchers for common trajectory alignment needs.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from zwarm.watchers.base import Watcher, WatcherContext, WatcherResult, WatcherAction
+from zwarm.watchers.registry import register_watcher
+
+
+@register_watcher("progress")
+class ProgressWatcher(Watcher):
+    """
+    Watches for lack of progress.
+
+    Detects when the agent appears stuck:
+    - Repeating same tool calls
+    - Not making session progress
+    - Spinning without completing tasks
+    """
+
+    name = "progress"
+    description = "Detects when agent is stuck or spinning"
+
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        config = self.config
+        max_same_calls = config.get("max_same_calls", 3)
+        min_progress_steps = config.get("min_progress_steps", 5)
+
+        # Check for repeated tool calls
+        if len(ctx.messages) >= max_same_calls * 2:
+            recent_assistant = [
+                m for m in ctx.messages[-max_same_calls * 2 :]
+                if m.get("role") == "assistant"
+            ]
+            if len(recent_assistant) >= max_same_calls:
+                # Check if tool calls are repeating
+                tool_calls = []
+                for msg in recent_assistant:
+                    if "tool_calls" in msg:
+                        for tc in msg["tool_calls"]:
+                            tool_calls.append(
+                                f"{tc.get('function', {}).get('name', '')}:{tc.get('function', {}).get('arguments', '')}"
+                            )
+
+                if len(tool_calls) >= max_same_calls:
+                    # Check for repetition
+                    if len(set(tool_calls[-max_same_calls:])) == 1:
+                        return WatcherResult.nudge(
+                            guidance=(
+                                "You appear to be repeating the same action. "
+                                "Consider a different approach or ask for clarification."
+                            ),
+                            reason=f"Repeated tool call: {tool_calls[-1][:100]}",
+                        )
+
+        # Check for no session completions in a while
+        if ctx.step >= min_progress_steps:
+            completed = [
+                e for e in ctx.events
+                if e.get("kind") == "session_completed"
+            ]
+            started = [
+                e for e in ctx.events
+                if e.get("kind") == "session_started"
+            ]
+            if len(started) > 0 and len(completed) == 0:
+                return WatcherResult.nudge(
+                    guidance=(
+                        "Several sessions have been started but none completed. "
+                        "Focus on completing current sessions before starting new ones."
+                    ),
+                    reason="No session completions",
+                )
+
+        return WatcherResult.ok()
+
+
+@register_watcher("budget")
+class BudgetWatcher(Watcher):
+    """
+    Watches resource budget (steps, sessions).
+
+    Warns when approaching limits.
+    """
+
+    name = "budget"
+    description = "Monitors resource usage against limits"
+
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        config = self.config
+        warn_at_percent = config.get("warn_at_percent", 80)
+        max_sessions = config.get("max_sessions", 10)
+
+        # Check step budget
+        if ctx.max_steps > 0:
+            percent_used = (ctx.step / ctx.max_steps) * 100
+            if percent_used >= warn_at_percent:
+                remaining = ctx.max_steps - ctx.step
+                return WatcherResult.nudge(
+                    guidance=(
+                        f"You have {remaining} steps remaining out of {ctx.max_steps}. "
+                        "Prioritize completing the most important parts of the task."
+                    ),
+                    reason=f"Step budget {percent_used:.0f}% used",
+                )
+
+        # Check session count
+        if len(ctx.sessions) >= max_sessions:
+            return WatcherResult.nudge(
+                guidance=(
+                    f"You have {len(ctx.sessions)} active sessions. "
+                    "Consider completing or closing existing sessions before starting new ones."
+                ),
+                reason=f"Session limit reached ({max_sessions})",
+            )
+
+        return WatcherResult.ok()
+
+
+@register_watcher("scope")
+class ScopeWatcher(Watcher):
+    """
+    Watches for scope creep.
+
+    Ensures the agent stays focused on the original task.
+    """
+
+    name = "scope"
+    description = "Detects scope creep and keeps agent on task"
+
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        config = self.config
+        focus_keywords = config.get("focus_keywords", [])
+        avoid_keywords = config.get("avoid_keywords", [])
+        max_tangent_steps = config.get("max_tangent_steps", 3)
+
+        # Check last few messages for avoid keywords
+        if avoid_keywords:
+            recent_content = " ".join(
+                m.get("content", "") or ""
+                for m in ctx.messages[-max_tangent_steps * 2:]
+            ).lower()
+
+            for keyword in avoid_keywords:
+                if keyword.lower() in recent_content:
+                    return WatcherResult.nudge(
+                        guidance=(
+                            f"The task involves '{keyword}' which may be out of scope. "
+                            f"Remember the original task: {ctx.task[:200]}"
+                        ),
+                        reason=f"Detected avoid keyword: {keyword}",
+                    )
+
+        return WatcherResult.ok()
+
+
+@register_watcher("pattern")
+class PatternWatcher(Watcher):
+    """
+    Watches for specific patterns in output.
+
+    Configurable regex patterns that trigger nudges/alerts.
+    """
+
+    name = "pattern"
+    description = "Watches for configurable patterns in output"
+
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        config = self.config
+        patterns = config.get("patterns", [])
+
+        # Each pattern is: {"regex": "...", "action": "nudge|pause|abort", "message": "..."}
+        for pattern_config in patterns:
+            regex = pattern_config.get("regex")
+            if not regex:
+                continue
+
+            try:
+                compiled = re.compile(regex, re.IGNORECASE)
+            except re.error:
+                continue
+
+            # Check recent messages
+            for msg in ctx.messages[-10:]:
+                content = msg.get("content", "") or ""
+                if compiled.search(content):
+                    action = pattern_config.get("action", "nudge")
+                    message = pattern_config.get("message", f"Pattern matched: {regex}")
+
+                    if action == "abort":
+                        return WatcherResult.abort(message)
+                    elif action == "pause":
+                        return WatcherResult.pause(message)
+                    else:
+                        return WatcherResult.nudge(guidance=message, reason=f"Pattern: {regex}")
+
+        return WatcherResult.ok()
+
+
+@register_watcher("quality")
+class QualityWatcher(Watcher):
+    """
+    Watches for quality issues.
+
+    Detects:
+    - Missing tests when code is written
+    - Large file changes
+    - Missing error handling
+    """
+
+    name = "quality"
+    description = "Watches for quality issues in code changes"
+
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        config = self.config
+        require_tests = config.get("require_tests", True)
+        max_files_changed = config.get("max_files_changed", 10)
+
+        # Check for large changes
+        if len(ctx.files_changed) > max_files_changed:
+            return WatcherResult.nudge(
+                guidance=(
+                    f"You've modified {len(ctx.files_changed)} files. "
+                    "Consider breaking this into smaller, focused changes."
+                ),
+                reason=f"Large change: {len(ctx.files_changed)} files",
+            )
+
+        # Check for tests if code files are changed
+        if require_tests and ctx.files_changed:
+            code_files = [
+                f for f in ctx.files_changed
+                if f.endswith((".py", ".js", ".ts", ".go", ".rs"))
+                and not f.startswith("test_")
+                and not f.endswith("_test.py")
+                and "/test" not in f
+            ]
+            test_files = [
+                f for f in ctx.files_changed
+                if "test" in f.lower()
+            ]
+
+            if code_files and not test_files:
+                return WatcherResult.nudge(
+                    guidance=(
+                        "Code files were modified but no test files were added or updated. "
+                        "Consider adding tests for the changes."
+                    ),
+                    reason="Code without tests",
+                )
+
+        return WatcherResult.ok()

zwarm/watchers/manager.py

@@ -0,0 +1,143 @@
+"""
+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
+
+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)
+
+    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
+        tasks = [watcher.observe(ctx) for watcher in self._watchers]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Collect valid results with their watcher names
+        valid_results: list[tuple[str, WatcherResult]] = []
+        for watcher, result in zip(self._watchers, results):
+            if isinstance(result, Exception):
+                # Log and skip failed watchers
+                continue
+            if isinstance(result, WatcherResult):
+                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,195 @@
+"""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
+
+
+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