zwarm 3.2.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

zwarm-3.3.0.dist-info/METADATA

@@ -0,0 +1,396 @@
+Metadata-Version: 2.4
+Name: zwarm
+Version: 3.3.0
+Summary: Multi-Agent CLI Orchestration Research Platform
+Requires-Python: <3.14,>=3.13
+Requires-Dist: prompt-toolkit>=3.0.52
+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
+```
+
+## Three Interfaces
+
+zwarm has three ways to work with coding agents:
+
+| Interface | Who drives | Use case |
+|-----------|------------|----------|
+| `zwarm interactive` | **You** | Direct session control, experimentation |
+| `zwarm pilot` | **You + LLM** | Conversational guidance with checkpoints |
+| `zwarm orchestrate` | **LLM** | Fully autonomous task execution |
+
+All three use the **same session manager** - they're different interfaces to the same underlying system.
+
+```
+                     .zwarm/sessions/ (GROUND TRUTH)
+                              │
+              ┌───────────────┼───────────────┐
+              │               │               │
+              ▼               ▼               ▼
+        Orchestrate        Pilot        Interactive
+          (LLM)         (LLM+REPL)        (REPL)
+```
+
+---
+
+## Quick Start
+
+```bash
+# Initialize zwarm in your project
+zwarm init
+
+# Start the pilot (recommended for most users)
+zwarm pilot --task "Build a REST API with authentication"
+
+# Or go fully autonomous
+zwarm orchestrate --task "Build a REST API with authentication"
+
+# Or manual control
+zwarm interactive
+```
+
+---
+
+## Pilot Mode
+
+**You chat with an LLM that delegates to coding agents.** Best of both worlds - LLM intelligence with human oversight.
+
+```bash
+zwarm pilot
+zwarm pilot --task "Add user authentication"
+```
+
+### Features
+
+- **Conversational**: Chat naturally, the LLM handles delegation
+- **Checkpoints**: Every turn is saved, time-travel with `:goto`
+- **Multiline input**: Use `"""` for pasting large prompts
+- **Status bar**: See token usage, cost estimates, context window
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `:help` | Show all commands |
+| `:status` | Token usage, cost, context window |
+| `:history` | Show turn checkpoints |
+| `:goto T3` | Jump back to turn 3 |
+| `:sessions` | List executor sessions |
+| `:quit` | Exit |
+
+### Example
+
+```
+$ zwarm pilot
+
+> Add a login endpoint to the API
+
+Chooooching...
+
+I'll delegate this to a coding agent.
+
+[delegate] task: "Add login endpoint with JWT..."
+  → Session abc123 started
+
+The agent is working on it. I'll check back shortly.
+
+[sleep] 10s
+[check_session] abc123
+  → completed (45s, 12k tokens)
+
+Done! The agent added a /login endpoint with JWT support...
+
+> Now add rate limiting
+
+I'll have the same agent continue with rate limiting.
+
+[converse] abc123: "Add rate limiting to the login endpoint..."
+```
+
+### Multiline Input
+
+Start with `"""` and end with `"""`:
+
+```
+> """
+Here's a complex task:
+1. Add authentication
+2. Add rate limiting
+3. Add tests
+"""
+```
+
+---
+
+## Interactive Mode
+
+**You are the orchestrator.** Direct control over sessions with autocomplete.
+
+```bash
+zwarm interactive
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `spawn "task" [--search]` | Start a new session (--search enables web) |
+| `ls` | Dashboard of all sessions (with costs) |
+| `? ID` / `peek ID` | Quick status check |
+| `show ID` | Full session details |
+| `traj ID` | Show trajectory (steps taken) |
+| `watch ID` | Live follow session output |
+| `c ID "msg"` | Continue conversation |
+| `kill ID \| all` | Stop session(s) |
+| `rm ID \| all` | Delete session(s) |
+| `help` | Show all commands |
+| `quit` | Exit |
+
+### Example
+
+```
+$ zwarm interactive
+
+> spawn "Add tests for the auth module"
+✓ Started abc123 (running)
+  Use 'watch abc123' to follow
+
+> spawn "Fix type errors in utils.py"
+✓ Started def456 (running)
+
+> ls
+⟳ 2 running
+
+ID       │    │ Task                          │ Tokens  │ Cost
+abc123   │ ⟳  │ Add tests for the auth...     │ 5,234   │ $0.052
+def456   │ ⟳  │ Fix type errors in utils...   │ 2,100   │ $0.021
+
+> watch abc123
+Watching abc123... (Ctrl+C to stop)
+  [step 3] shell: pytest tests/
+  [step 4] write: tests/test_auth.py
+  ...
+
+> c abc123 "Also add edge case tests"
+✓ Injected message, session running
+
+> kill all
+  ✓ Killed abc123
+  ✓ Killed def456
+Killed 2 session(s)
+```
+
+---
+
+## Orchestrate Mode
+
+**An LLM runs autonomously.** Give it a task, it delegates to coding agents and manages them.
+
+```bash
+zwarm orchestrate --task "Build a REST API with authentication"
+zwarm orchestrate --task-file task.md
+echo "Fix the bug" | zwarm orchestrate
+```
+
+### How It Works
+
+The orchestrator LLM has access to:
+
+| Tool | Description |
+|------|-------------|
+| `delegate(task, web_search=False)` | Start a new coding session |
+| `converse(id, msg)` | Continue a session |
+| `check_session(id)` | Get full session details |
+| `peek_session(id)` | Quick status check |
+| `list_sessions()` | List all sessions |
+| `end_session(id)` | Kill/delete a session |
+| `sleep(seconds)` | Wait before checking again |
+
+**Async-first**: All sessions run in the background. The orchestrator uses `sleep()` to wait, then checks on progress.
+
+**Web Search**: Pass `web_search=True` to `delegate()` for tasks needing current info (API docs, latest releases, etc.).
+
+### Watchers
+
+Watchers monitor the orchestrator and intervene when needed:
+
+| Watcher | Purpose |
+|---------|---------|
+| `progress` | Detects stuck/spinning behavior |
+| `budget` | Enforces step/session limits |
+| `delegation` | Tracks delegation patterns |
+| `delegation_reminder` | Nudges to delegate when doing too much directly |
+
+---
+
+## Session Management
+
+### Quick Commands
+
+```bash
+# List all sessions with costs
+zwarm sessions
+
+# Clean up old sessions
+zwarm sessions --clean
+zwarm sessions -c
+
+# Kill all running sessions
+zwarm sessions --kill-all
+zwarm sessions -k
+
+# Target specific session
+zwarm sessions --rm abc123
+zwarm sessions --kill abc123
+```
+
+### Session Lifecycle
+
+```
+spawn → running → completed/failed/killed
+                       ↓
+               converse → running → completed
+                               ↓
+                         converse → ...
+```
+
+### Storage
+
+```
+.zwarm/sessions/<uuid>/
+├── meta.json           # Status, task, model, tokens, cost
+└── turns/
+    ├── turn_1.jsonl    # Raw codex output for turn 1
+    ├── turn_2.jsonl    # Output after continue
+    └── ...
+```
+
+---
+
+## Configuration
+
+### Initialize
+
+```bash
+zwarm init
+```
+
+This creates:
+- `.zwarm/config.toml` - Runtime settings (Weave, watchers)
+- `.zwarm/codex.toml` - Codex CLI settings (model, reasoning)
+- `zwarm.yaml` - Project context (optional, with `--with-project`)
+
+### Config Files
+
+**`.zwarm/config.toml`** - Controls zwarm itself:
+```toml
+[weave]
+project = "your-entity/zwarm"
+
+[orchestrator]
+max_steps = 50
+
+[executor]
+adapter = "codex_mcp"
+web_search = false  # Enable web search for all delegated sessions
+
+[watchers]
+enabled = ["progress", "budget", "delegation", "delegation_reminder"]
+```
+
+**`.zwarm/codex.toml`** - Controls the Codex CLI:
+```toml
+model = "gpt-5.1-codex-mini"
+model_reasoning_effort = "high"  # low | medium | high
+```
+
+**`zwarm.yaml`** - Project-specific context:
+```yaml
+description: "My awesome project"
+
+context: |
+  Tech stack: FastAPI, PostgreSQL, React
+  Key directories: src/api/, src/components/
+
+constraints:
+  - "All new endpoints need tests"
+  - "Use existing patterns from src/api/"
+```
+
+---
+
+## CLI Reference
+
+```bash
+# Setup
+zwarm init              # Initialize .zwarm/ with interactive prompts
+zwarm init --yes        # Quick setup with defaults
+
+# Interfaces
+zwarm pilot             # Conversational LLM guidance (recommended)
+zwarm interactive       # Direct session control REPL
+zwarm orchestrate       # Fully autonomous LLM
+
+# Session management
+zwarm sessions          # List all sessions
+zwarm sessions -c       # Clean old sessions
+zwarm sessions -k       # Kill all running
+
+# Utilities
+zwarm exec              # Run single executor (testing)
+zwarm clean             # Kill orphaned processes
+zwarm reset             # Reset .zwarm/ state
+```
+
+---
+
+## Project Structure
+
+```
+zwarm/
+├── src/zwarm/
+│   ├── sessions/           # Session substrate
+│   │   └── manager.py      # CodexSessionManager (ground truth)
+│   ├── cli/
+│   │   ├── main.py         # CLI commands
+│   │   ├── pilot.py        # Pilot REPL
+│   │   └── interactive.py  # Interactive REPL
+│   ├── tools/
+│   │   └── delegation.py   # Orchestrator tools
+│   ├── core/
+│   │   ├── config.py       # Configuration
+│   │   ├── checkpoints.py  # Time-travel primitives
+│   │   ├── costs.py        # Token cost estimation
+│   │   └── state.py        # State persistence
+│   ├── watchers/           # Trajectory alignment
+│   ├── prompts/            # System prompts
+│   └── orchestrator.py     # Orchestrator agent
+└── STATE.md                # Current project state
+```

{zwarm-3.2.0.dist-info → zwarm-3.3.0.dist-info}/RECORD

@@ -1,35 +1,28 @@
 zwarm/__init__.py,sha256=3i3LMjHwIzE-LFIS2aUrwv3EZmpkvVMe-xj1h97rcSM,837
-zwarm/orchestrator.py,sha256=JGRGuJP05Nf5QibuWytjQAC_NuGGaGUR3G-tLq4SVxY,23624
+zwarm/orchestrator.py,sha256=sUSYJ1_Zr1pDV-tMyS-jovBCnSmA_JVmgv9_PrIqzps,22277
 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/interactive.py,sha256=0-KFo8tCHdlycgzprW2QCJaN5IKAo2CS3t3n6Mhfd4Q,25893
-zwarm/cli/main.py,sha256=bekPGLv6YbWOs8npbcurneC-i6H0GhMsKso2R5Uf3vU,70220
-zwarm/cli/pilot.py,sha256=ev6UfniLJKDR_GMSEA8JjWdTbtfRK0MLGk3VBCXpwTg,38011
+zwarm/cli/interactive.py,sha256=fCjX71tlN5fE2GvTgIbPRnRtmSiGmWiHsUYrQdVnwJE,25916
+zwarm/cli/main.py,sha256=JfYS_PXNqSVU0RknKJZ3legfvr4lG-UZrK4X_TVnuOo,70559
+zwarm/cli/pilot.py,sha256=SIjP5skBYTz0-VEJ94W0XjS07SAWdJ4zNnnHmuwBzio,38156
 zwarm/core/__init__.py,sha256=nEdpEHMFo0gEEKgX-eKHabyOdrOI6UXfWqLu3FfZDao,376
 zwarm/core/checkpoints.py,sha256=D6sXCMB7Sa1kchQ9_lQx_rabwc5-_7jbuynWgA1nkNY,6560
 zwarm/core/compact.py,sha256=Y8C7Gs-5-WOU43WRvQ863Qzd5xtuEqR6Aw3r2p8_-i8,10907
-zwarm/core/config.py,sha256=331i4io9uEnloFwUMjTPJ5_lQFKJR1nhTpA4SPfSpiI,11748
+zwarm/core/config.py,sha256=QtxvbdVg_mU33x9ItfHu-Rov7ewUHfSi0K_4O1iBJJQ,12486
 zwarm/core/costs.py,sha256=pLyixKn9hbDvtzQofOqajeK3XxOpoHPpA8nw8QM7j3g,5403
 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_config.py,sha256=bXXd3OHhK-ndC7wAxePWIdpu73s4O1eScxi3xDzrZwA,4828
 zwarm/core/test_models.py,sha256=sWTIhMZvuLP5AooGR6y8OR2EyWydqVfhmGrE7NPBBnk,8450
 zwarm/prompts/__init__.py,sha256=DI307o712F8qQyDt5vwnFgpVBrxpKwjhr0MaBHLzr9E,334
 zwarm/prompts/orchestrator.py,sha256=AkVbEpT91QbYFjUYOzm0d37wXrpm0esLBD1MG_W-3FI,15367
 zwarm/prompts/pilot.py,sha256=BcaV04-43FZyrtmoqCbA7DqnTlQ330TcDp9wNGhRojo,5586
 zwarm/sessions/__init__.py,sha256=jRibY8IfmNcnkgNmrgK2T81oa1w71wP_KQp9A1hPL7Q,568
-zwarm/sessions/manager.py,sha256=Aq7Wh-WW7ZMP8LgGa3g70wfGg6E2GYjJOBucy6HUfGc,27700
+zwarm/sessions/manager.py,sha256=bLxwFA9D4EBW3wCC6OqolKcBiZtv8igz0Z7ZGA7EcVc,31559
 zwarm/tools/__init__.py,sha256=FpqxwXJA6-fQ7C-oLj30jjK_0qqcE7MbI0dQuaB56kU,290
-zwarm/tools/delegation.py,sha256=lw4jJk1zVpgPhuvkUVfjUWFFMJotpJXXVY1YfqiP_Iw,21468
+zwarm/tools/delegation.py,sha256=wXKIb7eCL23c5NUwWi1G6JNg1PyXnwW-TNn7NrqchaE,21697
 zwarm/watchers/__init__.py,sha256=a96s7X6ruYkF2ItWWOZ3Q5QUOMOoeCW4Vz8XXcYLXPM,956
 zwarm/watchers/base.py,sha256=r1GoPlj06nOT2xp4fghfSjxbRyFFFQUB6HpZbEyO2OY,3834
 zwarm/watchers/builtin.py,sha256=IL5QwwKOIqWEfJ_uQWb321Px4i5OLtI_vnWQMudqKoA,19064
@@ -37,7 +30,7 @@ zwarm/watchers/llm_watcher.py,sha256=yJGpE3BGKNZX3qgPsiNtJ5d3UJpiTT1V-A-Rh4AiMYM
 zwarm/watchers/manager.py,sha256=XZjBVeHjgCUlkTUeHqdvBvHoBC862U1ik0fG6nlRGog,5587
 zwarm/watchers/registry.py,sha256=A9iBIVIFNtO7KPX0kLpUaP8dAK7ozqWLA44ocJGnOw4,1219
 zwarm/watchers/test_watchers.py,sha256=zOsxumBqKfR5ZVGxrNlxz6KcWjkcdp0QhW9WB0_20zM,7855
-zwarm-3.2.0.dist-info/METADATA,sha256=WDnj-d6wRTYslwj_41iYw3TjNHhRyh9HofeGx0pA0H4,7718
-zwarm-3.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-zwarm-3.2.0.dist-info/entry_points.txt,sha256=u0OXq4q8d3yJ3EkUXwZfkS-Y8Lcy0F8cWrcQfoRxM6Q,46
-zwarm-3.2.0.dist-info/RECORD,,
+zwarm-3.3.0.dist-info/METADATA,sha256=XuIf4S9hSl8xtmpqbTdHJiH15_jkLJagQ1Y8p5y5XHI,9670
+zwarm-3.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+zwarm-3.3.0.dist-info/entry_points.txt,sha256=u0OXq4q8d3yJ3EkUXwZfkS-Y8Lcy0F8cWrcQfoRxM6Q,46
+zwarm-3.3.0.dist-info/RECORD,,

zwarm/adapters/__init__.py

@@ -1,21 +0,0 @@
-"""
-Adapters: Executor wrappers for CLI coding agents.
-
-Adapters provide a unified interface to different coding CLIs (Codex, Claude Code).
-Use the registry to discover and instantiate adapters by name.
-"""
-
-from zwarm.adapters.base import ExecutorAdapter
-from zwarm.adapters.registry import register_adapter, get_adapter, list_adapters, adapter_exists
-
-# Import built-in adapters to register them
-from zwarm.adapters import codex_mcp as _codex_mcp  # noqa: F401
-from zwarm.adapters import claude_code as _claude_code  # noqa: F401
-
-__all__ = [
-    "ExecutorAdapter",
-    "register_adapter",
-    "get_adapter",
-    "list_adapters",
-    "adapter_exists",
-]

zwarm/adapters/base.py

@@ -1,109 +0,0 @@
-"""
-Base adapter protocol for executor agents.
-
-All CLI coding agent adapters (codex, claude-code, gemini) implement this protocol.
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from pathlib import Path
-from typing import Literal
-
-from zwarm.core.models import ConversationSession, SessionMode
-
-
-class ExecutorAdapter(ABC):
-    """
-    Abstract base class for CLI coding agent adapters.
-
-    Adapters handle the mechanics of:
-    - Starting sessions (sync or async)
-    - Sending messages in sync mode
-    - Checking status in async mode
-    - Stopping sessions
-    """
-
-    name: str = "base"
-
-    @abstractmethod
-    async def start_session(
-        self,
-        task: str,
-        working_dir: Path,
-        mode: Literal["sync", "async"] = "sync",
-        model: str | None = None,
-        **kwargs,
-    ) -> ConversationSession:
-        """
-        Start a new session with the executor.
-
-        Args:
-            task: The task description/prompt
-            working_dir: Directory to work in
-            mode: "sync" for conversational, "async" for fire-and-forget
-            model: Optional model override
-            **kwargs: Adapter-specific options
-
-        Returns:
-            A ConversationSession with initial response (if sync)
-        """
-        ...
-
-    @abstractmethod
-    async def send_message(
-        self,
-        session: ConversationSession,
-        message: str,
-    ) -> str:
-        """
-        Send a message to a sync session and get response.
-
-        Args:
-            session: The active session
-            message: Message to send
-
-        Returns:
-            The agent's response
-
-        Raises:
-            ValueError: If session is not in sync mode or not active
-        """
-        ...
-
-    @abstractmethod
-    async def check_status(
-        self,
-        session: ConversationSession,
-    ) -> dict:
-        """
-        Check the status of an async session.
-
-        Args:
-            session: The session to check
-
-        Returns:
-            Status dict with at least {"status": "running"|"completed"|"failed"}
-        """
-        ...
-
-    @abstractmethod
-    async def stop(
-        self,
-        session: ConversationSession,
-    ) -> None:
-        """
-        Stop/kill a session.
-
-        Args:
-            session: The session to stop
-        """
-        ...
-
-    async def cleanup(self) -> None:
-        """
-        Clean up adapter resources (e.g., MCP server).
-
-        Called when the orchestrator shuts down.
-        """
-        pass