zwarm 1.3.10__py3-none-any.whl → 2.0.0__py3-none-any.whl

zwarm/watchers/builtin.py

@@ -7,10 +7,99 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from wbal.helper import TOOL_CALL_TYPE, TOOL_RESULT_TYPE
 from zwarm.watchers.base import Watcher, WatcherContext, WatcherResult, WatcherAction
 from zwarm.watchers.registry import register_watcher
 
 
+def _get_field(item: Any, name: str, default: Any = None) -> Any:
+    if isinstance(item, dict):
+        return item.get(name, default)
+    return getattr(item, name, default)
+
+
+def _content_to_text(content: Any) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for part in content:
+            text = _content_to_text(part)
+            if text:
+                parts.append(text)
+        return "\n".join(parts)
+    if isinstance(content, dict):
+        text = content.get("text") or content.get("content") or content.get("refusal")
+        return str(text) if text is not None else ""
+    text = getattr(content, "text", None)
+    if text is None:
+        text = getattr(content, "refusal", None)
+    return str(text) if text is not None else ""
+
+
+def _normalize_tool_call(tool_call: Any) -> dict[str, Any]:
+    if isinstance(tool_call, dict):
+        if isinstance(tool_call.get("function"), dict):
+            return tool_call
+        name = tool_call.get("name", "")
+        arguments = tool_call.get("arguments", "")
+        call_id = tool_call.get("call_id")
+    else:
+        name = getattr(tool_call, "name", "")
+        arguments = getattr(tool_call, "arguments", "")
+        call_id = getattr(tool_call, "call_id", None)
+
+    normalized = {
+        "type": "function",
+        "function": {"name": name, "arguments": arguments},
+    }
+    if call_id:
+        normalized["call_id"] = call_id
+    return normalized
+
+
+def _normalize_messages(messages: list[Any]) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    for item in messages:
+        item_type = _get_field(item, "type")
+        role = _get_field(item, "role")
+        content = ""
+        tool_calls: list[dict[str, Any]] = []
+
+        if item_type in (TOOL_CALL_TYPE, "function_call"):
+            tool_calls = [_normalize_tool_call(item)]
+            role = role or "assistant"
+        else:
+            raw_tool_calls = _get_field(item, "tool_calls") or []
+            if raw_tool_calls and not isinstance(raw_tool_calls, list):
+                raw_tool_calls = [raw_tool_calls]
+            if raw_tool_calls:
+                tool_calls = [
+                    _normalize_tool_call(tc) for tc in raw_tool_calls
+                ]
+
+            if role or item_type == "message" or item_type is None:
+                content = _content_to_text(_get_field(item, "content"))
+
+            if item_type == TOOL_RESULT_TYPE and not content:
+                content = _content_to_text(_get_field(item, "output"))
+                role = role or "tool"
+
+        if not role and not content and not tool_calls:
+            continue
+
+        normalized.append(
+            {
+                "role": role,
+                "content": content or "",
+                "tool_calls": tool_calls,
+            }
+        )
+    return normalized
+
+
 @register_watcher("progress")
 class ProgressWatcher(Watcher):
     """
@@ -26,14 +115,15 @@ class ProgressWatcher(Watcher):
     description = "Detects when agent is stuck or spinning"
 
     async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        messages = _normalize_messages(ctx.messages)
         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:
+        if len(messages) >= max_same_calls * 2:
             recent_assistant = [
-                m for m in ctx.messages[-max_same_calls * 2 :]
+                m for m in messages[-max_same_calls * 2 :]
                 if m.get("role") == "assistant"
             ]
             if len(recent_assistant) >= max_same_calls:
@@ -144,9 +234,10 @@ class ScopeWatcher(Watcher):
 
         # Check last few messages for avoid keywords
         if avoid_keywords:
+            messages = _normalize_messages(ctx.messages)
             recent_content = " ".join(
                 m.get("content", "") or ""
-                for m in ctx.messages[-max_tangent_steps * 2:]
+                for m in messages[-max_tangent_steps * 2:]
             ).lower()
 
             for keyword in avoid_keywords:
@@ -174,6 +265,7 @@ class PatternWatcher(Watcher):
     description = "Watches for configurable patterns in output"
 
     async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        messages = _normalize_messages(ctx.messages)
         config = self.config
         patterns = config.get("patterns", [])
 
@@ -189,7 +281,7 @@ class PatternWatcher(Watcher):
                 continue
 
             # Check recent messages
-            for msg in ctx.messages[-10:]:
+            for msg in messages[-10:]:
                 content = msg.get("content", "") or ""
                 if compiled.search(content):
                     action = pattern_config.get("action", "nudge")
@@ -236,11 +328,12 @@ class DelegationWatcher(Watcher):
     ]
 
     async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        messages = _normalize_messages(ctx.messages)
         config = self.config
         strict = config.get("strict", True)  # If True, nudge. If False, just warn.
 
         # Check recent messages for bash tool calls
-        for msg in ctx.messages[-10:]:
+        for msg in messages[-10:]:
             if msg.get("role") != "assistant":
                 continue
 
@@ -370,6 +463,7 @@ class DelegationReminderWatcher(Watcher):
     }
 
     async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        messages = _normalize_messages(ctx.messages)
         config = self.config
         threshold = config.get("threshold", 10)  # Max consecutive non-delegation calls
         lookback = config.get("lookback", 30)  # How many messages to check
@@ -378,7 +472,7 @@ class DelegationReminderWatcher(Watcher):
         consecutive_non_delegation = 0
 
         # Look through recent messages in reverse order
-        for msg in reversed(ctx.messages[-lookback:]):
+        for msg in reversed(messages[-lookback:]):
             if msg.get("role") != "assistant":
                 continue
 

zwarm-2.0.0.dist-info/METADATA

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: zwarm
+Version: 2.0.0
+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.4.0
+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-1.3.10.dist-info → zwarm-2.0.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
 zwarm/__init__.py,sha256=3i3LMjHwIzE-LFIS2aUrwv3EZmpkvVMe-xj1h97rcSM,837
-zwarm/orchestrator.py,sha256=38PKWwT79U0VY9aqZe5atf9C5EAFGgMXE7PXPX5QJ0w,21359
+zwarm/orchestrator.py,sha256=FGr-_MpG_UGUFAa19oenh7MVifE6frK6URS8ii0x0IA,22952
 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=qX6blFC_rZwl3JaS9TLIG1yxIvWhgX42Goq2DdcJjbU,38474
+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=NKTq-PxIu6cy9MaPzNPr3T7T62BL7cZdGWU7lT9FNvg,73512
+zwarm/cli/main.py,sha256=-kxDul3cPv9vqLLS9ePTjSf1TXo8E3TCuS6p-t4u4hQ,87985
 zwarm/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 zwarm/core/compact.py,sha256=Y8C7Gs-5-WOU43WRvQ863Qzd5xtuEqR6Aw3r2p8_-i8,10907
-zwarm/core/config.py,sha256=7mzxrWvHmTjwiUWAoE4NYS_1yWj85-vWkpT6X6kiMIg,11579
+zwarm/core/config.py,sha256=331i4io9uEnloFwUMjTPJ5_lQFKJR1nhTpA4SPfSpiI,11748
 zwarm/core/environment.py,sha256=HVDpDZEpDSfyh9-wHZMzMKVUPKvioBkPVWeiME2JmFo,5435
 zwarm/core/models.py,sha256=PrC3okRBVJxISUa1Fax4KkagqLT6Xub-kTxC9drN0sY,10083
 zwarm/core/state.py,sha256=MzrvODKEiJovI7YI1jajW4uukineZ3ezmW5oQinMgjg,11563
@@ -20,18 +20,18 @@ zwarm/core/test_compact.py,sha256=WSdjCB5t4YMcknsrkmJIUsVOPY28s4y9GnDmu3Z4BFw,11
 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=af5547L2g6HwGz-PxlKCAXJzqXEdjcwSAIdVH7_4LSk,15412
-zwarm/sessions/__init__.py,sha256=NOOkyspJ2lpr5LwlZw2e9wvJPdRgSCQRkULgayrio5U,526
-zwarm/sessions/manager.py,sha256=0CrexNwMKiaKYESlWM_oDePj7xL8BRk-9XY5NS2ONlc,19391
+zwarm/prompts/orchestrator.py,sha256=-VZ3B5t-2ALOTpdZyNZGSjjzaHiTufAuLzrTLgwg70M,15442
+zwarm/sessions/__init__.py,sha256=jRibY8IfmNcnkgNmrgK2T81oa1w71wP_KQp9A1hPL7Q,568
+zwarm/sessions/manager.py,sha256=slCDE0n9-pw6iZ08YZMjxZRwH0aoEi6MAAChLlAsuPw,22212
 zwarm/tools/__init__.py,sha256=FpqxwXJA6-fQ7C-oLj30jjK_0qqcE7MbI0dQuaB56kU,290
-zwarm/tools/delegation.py,sha256=dV-fDoxA01RqjW90SLCLhBFQ2kVn8-68JdL0ssYYg_k,19583
+zwarm/tools/delegation.py,sha256=axGuDROdJM9xYDG8IscfyQpNGrkDQSFPi9_ElfL0Fzw,20661
 zwarm/watchers/__init__.py,sha256=yYGTbhuImQLESUdtfrYbHYBJNvCNX3B-Ei-vY5BizX8,760
 zwarm/watchers/base.py,sha256=r1GoPlj06nOT2xp4fghfSjxbRyFFFQUB6HpZbEyO2OY,3834
-zwarm/watchers/builtin.py,sha256=k1pCnQBEmLHeuCo8t6UXoenJUpfWY7AuGt_aEk8syew,15828
+zwarm/watchers/builtin.py,sha256=IL5QwwKOIqWEfJ_uQWb321Px4i5OLtI_vnWQMudqKoA,19064
 zwarm/watchers/manager.py,sha256=XZjBVeHjgCUlkTUeHqdvBvHoBC862U1ik0fG6nlRGog,5587
 zwarm/watchers/registry.py,sha256=A9iBIVIFNtO7KPX0kLpUaP8dAK7ozqWLA44ocJGnOw4,1219
 zwarm/watchers/test_watchers.py,sha256=zOsxumBqKfR5ZVGxrNlxz6KcWjkcdp0QhW9WB0_20zM,7855
-zwarm-1.3.10.dist-info/METADATA,sha256=58PTp7Hkwt3DeL8h7BkSaCcCaOBxuSkIheimqs861o8,16115
-zwarm-1.3.10.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-zwarm-1.3.10.dist-info/entry_points.txt,sha256=u0OXq4q8d3yJ3EkUXwZfkS-Y8Lcy0F8cWrcQfoRxM6Q,46
-zwarm-1.3.10.dist-info/RECORD,,
+zwarm-2.0.0.dist-info/METADATA,sha256=v94KN8eICvONW3-UvteIdL0suEu6Pu3ur3FMxGd9lS0,7680
+zwarm-2.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+zwarm-2.0.0.dist-info/entry_points.txt,sha256=u0OXq4q8d3yJ3EkUXwZfkS-Y8Lcy0F8cWrcQfoRxM6Q,46
+zwarm-2.0.0.dist-info/RECORD,,