zwarm 2.3.5__py3-none-any.whl

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

zwarm-2.3.5.dist-info/METADATA

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: zwarm
+Version: 2.3.5
+Summary: Multi-Agent CLI Orchestration Research Platform
+Requires-Python: <3.14,>=3.13
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: wbal>=0.5.8
+Description-Content-Type: text/markdown
+
+# zwarm
+
+Multi-agent CLI for orchestrating coding agents. Spawn, manage, and converse with multiple Codex sessions in parallel.
+
+## Installation
+
+```bash
+# From the workspace
+cd /path/to/labs
+uv sync
+
+# Or install directly
+uv pip install -e ./zwarm
+```
+
+**Requirements:**
+- Python 3.13+
+- `codex` CLI installed and authenticated
+
+**Environment:**
+```bash
+export OPENAI_API_KEY="sk-..."        # Required for Codex
+export WEAVE_PROJECT="entity/zwarm"   # Optional: Weave tracing
+```
+
+## Two Modes
+
+zwarm has two ways to orchestrate coding agents:
+
+| Mode | Who's in charge | Use case |
+|------|-----------------|----------|
+| `zwarm interactive` | **You** | Manual control, experimentation |
+| `zwarm orchestrate` | **LLM** | Autonomous task execution |
+
+Both use the **same underlying session manager** - the orchestrator LLM has access to the exact same tools you do.
+
+---
+
+## Interactive Mode
+
+**You are the orchestrator.** Spawn sessions, check on them, continue conversations.
+
+```bash
+zwarm interactive
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `spawn "task"` | Start a session (waits for completion) |
+| `spawn --async "task"` | Start async (returns immediately) |
+| `spawn -d /path "task"` | Start in specific directory |
+| `ls` | List all sessions |
+| `? <id>` | Quick peek: status + latest message |
+| `show <id>` | Full details: all messages, tokens, etc. |
+| `c <id> "msg"` | Continue conversation (waits) |
+| `ca <id> "msg"` | Continue async (returns immediately) |
+| `kill <id>` | Stop a running session |
+| `rm <id>` | Delete session entirely |
+| `killall` | Stop all running sessions |
+| `clean` | Remove sessions older than 7 days |
+| `q` | Quit |
+
+### Example Session
+
+```
+$ zwarm interactive
+
+> spawn "Add a login function to auth.py"
+✓ Started session a1b2c3d4, waiting...
+[a1b2c3d4] codex (completed) - 32s
+Response: I've added a login function with JWT support...
+
+> spawn --async "Fix the type errors in utils.py"
+✓ Session: b2c3d4e5 (running in background)
+
+> spawn --async "Add unit tests for auth.py"
+✓ Session: c3d4e5f6 (running in background)
+
+> ls
+1 running | 2 done
+
+ID         │   │ T │ Task                        │ Updated │ Last Message
+a1b2c3d4   │ ✓ │ 1 │ Add a login function...     │ 2m      │ I've added a login function...
+b2c3d4e5   │ ✓ │ 1 │ Fix the type errors...      │ 30s ★   │ Fixed 3 type errors in...
+c3d4e5f6   │ ● │ 1 │ Add unit tests...           │ 5s      │ (working...)
+
+> ? b2c3d4e5
+✓ b2c3d4e5 Fixed 3 type errors: Optional[str] -> str | None, added missing...
+
+> c a1b2c3d4 "Now add password hashing with bcrypt"
+Continuing session a1b2c3d4...
+[a1b2c3d4] codex (completed) - 28s
+Response: Done! I've updated the login function to use bcrypt...
+
+> rm b2c3d4e5
+✓ Deleted session b2c3d4e5
+
+> q
+```
+
+### Session Status Icons
+
+| Icon | Status |
+|------|--------|
+| `●` | Running |
+| `✓` | Completed |
+| `✗` | Failed |
+| `○` | Killed |
+| `★` | Recently completed (< 60s) |
+
+---
+
+## Orchestrate Mode
+
+**An LLM is the orchestrator.** Give it a task and it delegates to coding agents.
+
+```bash
+zwarm orchestrate --task "Build a REST API with authentication"
+```
+
+The orchestrator LLM uses the same tools available in interactive mode:
+
+| Tool | Description |
+|------|-------------|
+| `delegate(task, ...)` | Start a new session |
+| `converse(id, msg)` | Continue a conversation |
+| `peek_session(id)` | Quick status check |
+| `check_session(id)` | Full session details |
+| `list_sessions()` | List all sessions with `needs_attention` flags |
+| `end_session(id, delete=False)` | Kill/delete a session |
+
+### Task Input
+
+```bash
+# Direct
+zwarm orchestrate --task "Build a REST API"
+
+# From file
+zwarm orchestrate --task-file task.md
+
+# From stdin
+echo "Fix the bug in auth.py" | zwarm orchestrate
+```
+
+---
+
+## Configuration
+
+zwarm looks for config in this order:
+1. `--config` flag
+2. `.zwarm/config.toml`
+3. `config.toml` in working directory
+
+### Minimal Config
+
+```toml
+[weave]
+enabled = true
+project = "your-entity/zwarm"
+
+[executor]
+adapter = "codex_mcp"
+model = "gpt-5.1-codex-mini"
+```
+
+### Full Config Reference
+
+```toml
+[orchestrator]
+lm = "gpt-5-mini"
+max_steps = 100
+
+[orchestrator.compaction]
+enabled = true
+max_tokens = 100000
+threshold_pct = 0.85
+target_pct = 0.7
+
+[executor]
+adapter = "codex_mcp"
+model = "gpt-5.1-codex-mini"
+sandbox = "workspace-write"
+timeout = 300
+
+[weave]
+enabled = true
+project = "your-entity/zwarm"
+
+[watchers]
+enabled = true
+watchers = [
+    { name = "progress" },
+    { name = "budget", config = { max_steps = 50, max_sessions = 10 } },
+    { name = "delegation_reminder", config = { threshold = 10 } },
+]
+```
+
+---
+
+## Session Management
+
+Sessions are the core abstraction. Each session is a conversation with a Codex agent.
+
+### Lifecycle
+
+```
+spawn → running → completed/failed
+                      ↓
+              continue → running → completed
+                              ↓
+                        continue → ...
+```
+
+### Storage
+
+```
+.zwarm/sessions/<uuid>/
+├── meta.json           # Status, task, model, messages, tokens
+└── turns/
+    ├── turn_1.jsonl    # Raw codex output for turn 1
+    ├── turn_2.jsonl    # Output after first continue
+    └── ...
+```
+
+### Sync vs Async
+
+| Mode | Spawn | Continue | Use case |
+|------|-------|----------|----------|
+| **Sync** | `spawn "task"` | `c id "msg"` | Sequential work, immediate feedback |
+| **Async** | `spawn --async "task"` | `ca id "msg"` | Parallel work, batch processing |
+
+Async sessions return immediately. Poll with `ls` or `?` to check status.
+
+---
+
+## Watchers
+
+Watchers monitor agent behavior and intervene when needed.
+
+| Watcher | Purpose |
+|---------|---------|
+| `progress` | Detects stuck/spinning agents |
+| `budget` | Enforces step/session limits |
+| `scope` | Detects scope creep |
+| `delegation_reminder` | Nudges orchestrator to delegate |
+
+Configure in `config.toml`:
+
+```toml
+[watchers]
+enabled = true
+watchers = [
+    { name = "progress" },
+    { name = "budget", config = { max_steps = 50 } },
+]
+```
+
+---
+
+## CLI Reference
+
+```bash
+zwarm init              # Initialize .zwarm/ in current directory
+zwarm interactive       # Start interactive REPL
+zwarm orchestrate       # Start LLM orchestrator
+zwarm exec              # Run single executor directly (testing)
+zwarm status            # Show current state
+zwarm history           # Show event history
+zwarm clean             # Remove old sessions
+```
+
+---
+
+## Project Structure
+
+```
+zwarm/
+├── src/zwarm/
+│   ├── sessions/           # Session management (core)
+│   │   ├── manager.py      # CodexSessionManager
+│   │   └── __init__.py
+│   ├── tools/
+│   │   └── delegation.py   # Orchestrator tools (delegate, converse, etc.)
+│   ├── cli/
+│   │   └── main.py         # CLI commands and interactive REPL
+│   ├── core/
+│   │   ├── config.py       # Configuration loading
+│   │   ├── compact.py      # Context window management
+│   │   └── state.py        # State persistence
+│   ├── watchers/           # Trajectory alignment
+│   └── orchestrator.py     # Orchestrator agent
+├── docs/
+│   └── INTERNALS.md        # Technical architecture
+└── README.md
+```

zwarm-2.3.5.dist-info/RECORD

@@ -0,0 +1,38 @@
+zwarm/__init__.py,sha256=3i3LMjHwIzE-LFIS2aUrwv3EZmpkvVMe-xj1h97rcSM,837
+zwarm/orchestrator.py,sha256=JGRGuJP05Nf5QibuWytjQAC_NuGGaGUR3G-tLq4SVxY,23624
+zwarm/test_orchestrator_watchers.py,sha256=QpoaehPU7ekT4XshbTOWnJ2H0wRveV3QOZjxbgyJJLY,807
+zwarm/adapters/__init__.py,sha256=O0b-SfZpb6txeNqFkXZ2aaf34yLFYreznyrAV25jF_Q,656
+zwarm/adapters/base.py,sha256=fZlQviTgVvOcwnxduTla6WuM6FzQJ_yoHMW5SxwVgQg,2527
+zwarm/adapters/claude_code.py,sha256=vAjsjD-_JjARmC4_FBSILQZmQCBrk_oNHo18a9ubuqk,11481
+zwarm/adapters/codex_mcp.py,sha256=EhdkM3gj5hc01AcM1ERhtfZbydK390yN4Pg3dawKIGU,48791
+zwarm/adapters/registry.py,sha256=EdyHECaNA5Kv1od64pYFBJyA_r_6I1r_eJTNP1XYLr4,1781
+zwarm/adapters/test_codex_mcp.py,sha256=0qhVzxn_KF-XUS30gXSJKwMdR3kWGsDY9iPk1Ihqn3w,10698
+zwarm/adapters/test_registry.py,sha256=otxcVDONwFCMisyANToF3iy7Y8dSbCL8bTmZNhxNuF4,2383
+zwarm/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zwarm/cli/main.py,sha256=cSJ--IHJQv5o3Stb4PMKGIsiMNJn8s-xXvvm6DCjdmA,93294
+zwarm/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zwarm/core/compact.py,sha256=Y8C7Gs-5-WOU43WRvQ863Qzd5xtuEqR6Aw3r2p8_-i8,10907
+zwarm/core/config.py,sha256=331i4io9uEnloFwUMjTPJ5_lQFKJR1nhTpA4SPfSpiI,11748
+zwarm/core/environment.py,sha256=zrgh0N3Ng4HI2F1gCYkcQVGzjQPKiIFWuRe1OPRuRn0,6558
+zwarm/core/models.py,sha256=PrC3okRBVJxISUa1Fax4KkagqLT6Xub-kTxC9drN0sY,10083
+zwarm/core/state.py,sha256=MzrvODKEiJovI7YI1jajW4uukineZ3ezmW5oQinMgjg,11563
+zwarm/core/test_compact.py,sha256=WSdjCB5t4YMcknsrkmJIUsVOPY28s4y9GnDmu3Z4BFw,11878
+zwarm/core/test_config.py,sha256=26ozyiFOdjFF2c9Q-HDfFM6GOLfgw_5FZ55nTDMNYA8,4888
+zwarm/core/test_models.py,sha256=sWTIhMZvuLP5AooGR6y8OR2EyWydqVfhmGrE7NPBBnk,8450
+zwarm/prompts/__init__.py,sha256=FiaIOniLrIyfD3_osxT6I7FfyKjtctbf8jNs5QTPs_s,213
+zwarm/prompts/orchestrator.py,sha256=-VZ3B5t-2ALOTpdZyNZGSjjzaHiTufAuLzrTLgwg70M,15442
+zwarm/sessions/__init__.py,sha256=jRibY8IfmNcnkgNmrgK2T81oa1w71wP_KQp9A1hPL7Q,568
+zwarm/sessions/manager.py,sha256=Aq7Wh-WW7ZMP8LgGa3g70wfGg6E2GYjJOBucy6HUfGc,27700
+zwarm/tools/__init__.py,sha256=FpqxwXJA6-fQ7C-oLj30jjK_0qqcE7MbI0dQuaB56kU,290
+zwarm/tools/delegation.py,sha256=kNvc7YISAEUWhlGYCvacxfDVfGA0a4P2kuWgMN9rP0Y,25294
+zwarm/watchers/__init__.py,sha256=a96s7X6ruYkF2ItWWOZ3Q5QUOMOoeCW4Vz8XXcYLXPM,956
+zwarm/watchers/base.py,sha256=r1GoPlj06nOT2xp4fghfSjxbRyFFFQUB6HpZbEyO2OY,3834
+zwarm/watchers/builtin.py,sha256=IL5QwwKOIqWEfJ_uQWb321Px4i5OLtI_vnWQMudqKoA,19064
+zwarm/watchers/llm_watcher.py,sha256=yJGpE3BGKNZX3qgPsiNtJ5d3UJpiTT1V-A-Rh4AiMYM,11029
+zwarm/watchers/manager.py,sha256=XZjBVeHjgCUlkTUeHqdvBvHoBC862U1ik0fG6nlRGog,5587
+zwarm/watchers/registry.py,sha256=A9iBIVIFNtO7KPX0kLpUaP8dAK7ozqWLA44ocJGnOw4,1219
+zwarm/watchers/test_watchers.py,sha256=zOsxumBqKfR5ZVGxrNlxz6KcWjkcdp0QhW9WB0_20zM,7855
+zwarm-2.3.5.dist-info/METADATA,sha256=HAscgpL1b-0D0fBJxqTEJM0APjE-hijsy8G6Lozyr7M,7680
+zwarm-2.3.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+zwarm-2.3.5.dist-info/entry_points.txt,sha256=u0OXq4q8d3yJ3EkUXwZfkS-Y8Lcy0F8cWrcQfoRxM6Q,46
+zwarm-2.3.5.dist-info/RECORD,,

zwarm-2.3.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zwarm-2.3.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zwarm = zwarm.cli.main:main