zwarm 0.1.0__tar.gz → 1.0.0__tar.gz

{zwarm-0.1.0 → zwarm-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zwarm
-Version: 0.1.0
+Version: 1.0.0
 Summary: Multi-Agent CLI Orchestration Research Platform
 Requires-Python: <3.14,>=3.13
 Requires-Dist: python-dotenv>=1.0.0
@@ -12,7 +12,17 @@ Description-Content-Type: text/markdown
 
 # zwarm
 
-Multi-agent CLI orchestration research platform. Coordinate multiple coding agents (Codex, Claude Code) with delegation, conversation, and trajectory alignment.
+Multi-agent CLI orchestration research platform. Coordinate multiple coding agents (Codex, Claude Code) with delegation, conversation, trajectory alignment, and automatic context management.
+
+## Key Features
+
+- **Multi-adapter support**: Codex MCP, Claude Code adapters with unified interface
+- **Sync & async modes**: Conversational (iterative refinement) or fire-and-forget
+- **Token tracking**: Per-session token usage tracked and persisted for cost analysis
+- **Context compaction**: Automatic LRU-style pruning when approaching context limits
+- **Trajectory watchers**: Composable guardrails (progress, budget, scope, pattern, delegation)
+- **State persistence**: Resume sessions, track history, replay events
+- **Weave integration**: Full tracing and observability
 
 ## Installation
 
@@ -33,16 +43,19 @@ uv pip install -e ./zwarm
 ## Quick Start
 
 ```bash
-# 1. Test an executor directly
+# 1. Initialize zwarm in your project
+zwarm init
+
+# 2. Test an executor directly
 zwarm exec --task "What is 2+2?"
 
-# 2. Run the orchestrator with a task
+# 3. Run the orchestrator with a task
 zwarm orchestrate --task "Create a hello world Python function"
 
-# 3. Check state after running
+# 4. Check state after running
 zwarm status
 
-# 4. View event history
+# 5. View event history
 zwarm history
 ```
 
@@ -80,24 +93,38 @@ adapter = "codex_mcp"  # or "claude_code"
 ### Environment Variables
 
 ```bash
-# Enable Weave tracing (alternative to config.toml)
+# Weave tracing (optional but recommended)
 export WEAVE_PROJECT="your-entity/zwarm"
 
-# Required for adapters
-export OPENAI_API_KEY="..."      # for Codex
-export ANTHROPIC_API_KEY="..."   # for Claude Code
+# Executor authentication (required - set based on which adapter you use)
+export OPENAI_API_KEY="sk-..."        # Required for codex_mcp adapter
+export ANTHROPIC_API_KEY="sk-ant-..." # Required for claude_code adapter
 ```
 
+**Important:** The orchestrator agent runs with your credentials, but the executor adapters (Codex, Claude Code) need their own authentication. If executors fail with auth errors, check that the appropriate API key is set in your environment.
+
+You can also put these in a `.env` file in your project root - zwarm will load it automatically.
+
 ### Full Configuration Reference
 
 ```yaml
 # config.yaml
 orchestrator:
+  lm: gpt-5-mini              # Model for the orchestrator itself
   max_steps: 100              # Maximum orchestrator steps
+  compaction:                 # Context window management
+    enabled: true
+    max_tokens: 100000        # Trigger compaction above this
+    threshold_pct: 0.85       # Compact at 85% of max
+    target_pct: 0.7           # Target 70% after compaction
+    keep_first_n: 2           # Always keep system + task
+    keep_last_n: 10           # Always keep recent context
 
 executor:
   adapter: codex_mcp          # Default adapter: codex_mcp | claude_code
-  model: null                 # Model override (adapter-specific)
+  model: null                 # Model override (null = use adapter default)
+                              # codex_mcp default: gpt-5.1-codex-mini
+                              # claude_code default: claude-sonnet-4-5-20250514
   sandbox: workspace-write    # Codex sandbox mode
 
 weave:
@@ -107,24 +134,25 @@ weave:
 state_dir: .zwarm             # State directory for sessions/events
 
 watchers:
-  enabled: []                 # List of enabled watchers
-  config:
-    progress:
-      stuck_threshold: 5
-    budget:
-      max_steps: 50
-      max_sessions: 10
-    scope:
-      keywords: []
+  enabled: true
+  watchers:
+    - name: progress
+    - name: budget
+      config:
+        max_steps: 50
+        max_sessions: 10
+    - name: scope
+      config:
+        keywords: []
 ```
 
 ## Adapters
 
-zwarm supports multiple CLI coding agents through adapters.
+zwarm supports multiple CLI coding agents through adapters. Each adapter wraps a different coding CLI and handles the mechanics of starting sessions, sending messages, and capturing responses.
 
 ### Codex MCP (default)
 
-Uses Codex via MCP server for true conversational sessions.
+Uses Codex via MCP server for true conversational sessions. This is the recommended adapter for iterative work where you need back-and-forth refinement.
 
 ```bash
 # Sync mode (conversational)
@@ -134,17 +162,45 @@ zwarm exec --adapter codex_mcp --task "Add a login function"
 # using delegate() and converse() tools
 ```
 
-**Requires:** `codex` CLI installed, `OPENAI_API_KEY` set
+| Setting | Value |
+|---------|-------|
+| Default model | `gpt-5.1-codex-mini` |
+| Requires | `codex` CLI installed |
+| Auth | `OPENAI_API_KEY` environment variable |
 
 ### Claude Code
 
-Uses Claude Code CLI for execution.
+Uses Claude Code CLI for execution. Good alternative when you want Claude's capabilities.
 
 ```bash
 zwarm exec --adapter claude_code --task "Fix the type errors"
 ```
 
-**Requires:** `claude` CLI installed, authenticated
+| Setting | Value |
+|---------|-------|
+| Default model | `claude-sonnet-4-5-20250514` |
+| Requires | `claude` CLI installed and authenticated |
+| Auth | `ANTHROPIC_API_KEY` or `claude` CLI auth |
+
+### Model Selection
+
+Models are selected with this precedence (highest to lowest):
+
+1. **Per-delegation override**: `delegate(task="...", model="o3")`
+2. **Config file**: `executor.model` in config.toml or zwarm.yaml
+3. **Adapter default**: Each adapter has a sensible default
+
+```yaml
+# config.toml - override the default model
+[executor]
+adapter = "codex_mcp"
+model = "gpt-5.1-codex-max"  # Use the more capable model
+```
+
+```bash
+# Or override per-execution
+zwarm exec --model gpt-5.1-codex-max --task "Complex refactoring"
+```
 
 ## Watchers (Trajectory Alignment)
 
@@ -155,10 +211,11 @@ Watchers are composable guardrails that monitor agent behavior and can intervene
 | Watcher | Description |
 |---------|-------------|
 | `progress` | Detects stuck/spinning agents |
-| `budget` | Monitors step/session limits |
+| `budget` | Monitors step/session limits (counts only active sessions) |
 | `scope` | Detects scope creep from original task |
 | `pattern` | Custom regex pattern matching |
 | `quality` | Code quality checks |
+| `delegation` | Ensures orchestrator delegates instead of writing code directly |
 
 ### Enabling Watchers
 
@@ -216,6 +273,41 @@ View traces at: `https://wandb.ai/your-entity/zwarm/weave`
 
 ## CLI Reference
 
+### init
+
+Initialize zwarm in a project directory.
+
+```bash
+zwarm init [OPTIONS]
+
+Options:
+  -w, --working-dir PATH    Working directory [default: .]
+  -y, --yes                 Accept defaults, no prompts
+  --with-project            Also create zwarm.yaml project config
+```
+
+**What it creates:**
+
+1. `config.toml` - User settings (Weave project, adapter preferences, watchers)
+2. `.zwarm/` - State directory for sessions and events
+3. `zwarm.yaml` (optional) - Project-specific task configuration
+
+**Examples:**
+
+```bash
+# Interactive setup with prompts
+zwarm init
+
+# Non-interactive with defaults
+zwarm init --yes
+
+# Create project config too
+zwarm init --with-project
+
+# Initialize in a different directory
+zwarm init --working-dir /path/to/project
+```
+
 ### orchestrate
 
 Start an orchestrator session to delegate tasks.
@@ -234,19 +326,20 @@ Options:
 
 ### exec
 
-Run a single executor directly (for testing).
+Run a single executor directly (for testing). This bypasses the orchestrator entirely and hits the adapter (Codex/Claude) immediately with your task - useful for verifying adapters work before running full orchestration.
 
 ```bash
 zwarm exec [OPTIONS]
 
 Options:
   -t, --task TEXT           Task to execute
-  -f, --task-file PATH      Read task from file
   --adapter TEXT            Adapter to use [default: codex_mcp]
   --model TEXT              Model override
   --mode [sync|async]       Execution mode [default: sync]
 ```
 
+**Note:** Unlike `orchestrate`, this does NOT use watchers, compaction, state persistence, or multi-step planning. It's a single direct call to the executor.
+
 ### status
 
 Show current orchestrator state.
@@ -282,6 +375,30 @@ zwarm configs list          # List available configs
 zwarm configs show NAME     # Show config contents
 ```
 
+### clean
+
+Clean up zwarm state (useful for starting fresh).
+
+```bash
+zwarm clean [OPTIONS]
+
+Options:
+  --all                     Remove everything (events, sessions, state)
+  --events                  Remove only events
+  --sessions                Remove only sessions
+  -y, --yes                 Skip confirmation prompt
+```
+
+**Examples:**
+
+```bash
+# Clean everything and start fresh
+zwarm clean --all --yes
+
+# Clean only events log
+zwarm clean --events
+```
+
 ## Architecture
 
 ```
@@ -332,10 +449,16 @@ All state is stored in flat files under `.zwarm/`:
 ### Running Tests
 
 ```bash
-# From workspace root
-uv run pytest wbal/tests/ -v
+# Run all zwarm tests (68 tests)
+uv run pytest src/zwarm/ -v
+
+# Run specific test modules
+uv run pytest src/zwarm/core/test_compact.py -v      # Context compaction
+uv run pytest src/zwarm/watchers/test_watchers.py -v # Watchers
+uv run pytest src/zwarm/adapters/test_codex_mcp.py -v # Codex adapter
 
-# zwarm doesn't have its own tests yet
+# Run integration tests (requires codex CLI)
+uv run pytest -m integration
 ```
 
 ### Project Structure
@@ -345,19 +468,22 @@ zwarm/
 ├── src/zwarm/
 │   ├── adapters/           # Executor adapters
 │   │   ├── base.py         # ExecutorAdapter protocol
-│   │   ├── codex_mcp.py    # Codex MCP adapter
-│   │   └── claude_code.py  # Claude Code adapter
+│   │   ├── codex_mcp.py    # Codex MCP adapter (with token tracking)
+│   │   └── claude_code.py  # Claude Code adapter (with token tracking)
 │   ├── cli/
 │   │   └── main.py         # Typer CLI
 │   ├── core/
+│   │   ├── compact.py      # Context window compaction (LRU pruning)
 │   │   ├── config.py       # Configuration loading
-│   │   ├── models.py       # ConversationSession, Message, etc.
+│   │   ├── environment.py  # OrchestratorEnv (progress display)
+│   │   ├── models.py       # ConversationSession, Message, Event, etc.
 │   │   └── state.py        # Flat-file state management
 │   ├── tools/
-│   │   └── delegation.py   # delegate, converse, etc.
+│   │   └── delegation.py   # delegate, converse, check_session, etc.
 │   ├── watchers/
 │   │   ├── base.py         # Watcher protocol
-│   │   ├── builtin.py      # Built-in watchers
+│   │   ├── builtin.py      # Built-in watchers (progress, budget, scope, etc.)
+│   │   ├── registry.py     # Watcher registration
 │   │   └── manager.py      # WatcherManager
 │   ├── prompts/
 │   │   └── orchestrator.py # Orchestrator system prompt

{zwarm-0.1.0 → zwarm-1.0.0}/README.md

@@ -1,6 +1,16 @@
 # zwarm
 
-Multi-agent CLI orchestration research platform. Coordinate multiple coding agents (Codex, Claude Code) with delegation, conversation, and trajectory alignment.
+Multi-agent CLI orchestration research platform. Coordinate multiple coding agents (Codex, Claude Code) with delegation, conversation, trajectory alignment, and automatic context management.
+
+## Key Features
+
+- **Multi-adapter support**: Codex MCP, Claude Code adapters with unified interface
+- **Sync & async modes**: Conversational (iterative refinement) or fire-and-forget
+- **Token tracking**: Per-session token usage tracked and persisted for cost analysis
+- **Context compaction**: Automatic LRU-style pruning when approaching context limits
+- **Trajectory watchers**: Composable guardrails (progress, budget, scope, pattern, delegation)
+- **State persistence**: Resume sessions, track history, replay events
+- **Weave integration**: Full tracing and observability
 
 ## Installation
 
@@ -21,16 +31,19 @@ uv pip install -e ./zwarm
 ## Quick Start
 
 ```bash
-# 1. Test an executor directly
+# 1. Initialize zwarm in your project
+zwarm init
+
+# 2. Test an executor directly
 zwarm exec --task "What is 2+2?"
 
-# 2. Run the orchestrator with a task
+# 3. Run the orchestrator with a task
 zwarm orchestrate --task "Create a hello world Python function"
 
-# 3. Check state after running
+# 4. Check state after running
 zwarm status
 
-# 4. View event history
+# 5. View event history
 zwarm history
 ```
 
@@ -68,24 +81,38 @@ adapter = "codex_mcp"  # or "claude_code"
 ### Environment Variables
 
 ```bash
-# Enable Weave tracing (alternative to config.toml)
+# Weave tracing (optional but recommended)
 export WEAVE_PROJECT="your-entity/zwarm"
 
-# Required for adapters
-export OPENAI_API_KEY="..."      # for Codex
-export ANTHROPIC_API_KEY="..."   # for Claude Code
+# Executor authentication (required - set based on which adapter you use)
+export OPENAI_API_KEY="sk-..."        # Required for codex_mcp adapter
+export ANTHROPIC_API_KEY="sk-ant-..." # Required for claude_code adapter
 ```
 
+**Important:** The orchestrator agent runs with your credentials, but the executor adapters (Codex, Claude Code) need their own authentication. If executors fail with auth errors, check that the appropriate API key is set in your environment.
+
+You can also put these in a `.env` file in your project root - zwarm will load it automatically.
+
 ### Full Configuration Reference
 
 ```yaml
 # config.yaml
 orchestrator:
+  lm: gpt-5-mini              # Model for the orchestrator itself
   max_steps: 100              # Maximum orchestrator steps
+  compaction:                 # Context window management
+    enabled: true
+    max_tokens: 100000        # Trigger compaction above this
+    threshold_pct: 0.85       # Compact at 85% of max
+    target_pct: 0.7           # Target 70% after compaction
+    keep_first_n: 2           # Always keep system + task
+    keep_last_n: 10           # Always keep recent context
 
 executor:
   adapter: codex_mcp          # Default adapter: codex_mcp | claude_code
-  model: null                 # Model override (adapter-specific)
+  model: null                 # Model override (null = use adapter default)
+                              # codex_mcp default: gpt-5.1-codex-mini
+                              # claude_code default: claude-sonnet-4-5-20250514
   sandbox: workspace-write    # Codex sandbox mode
 
 weave:
@@ -95,24 +122,25 @@ weave:
 state_dir: .zwarm             # State directory for sessions/events
 
 watchers:
-  enabled: []                 # List of enabled watchers
-  config:
-    progress:
-      stuck_threshold: 5
-    budget:
-      max_steps: 50
-      max_sessions: 10
-    scope:
-      keywords: []
+  enabled: true
+  watchers:
+    - name: progress
+    - name: budget
+      config:
+        max_steps: 50
+        max_sessions: 10
+    - name: scope
+      config:
+        keywords: []
 ```
 
 ## Adapters
 
-zwarm supports multiple CLI coding agents through adapters.
+zwarm supports multiple CLI coding agents through adapters. Each adapter wraps a different coding CLI and handles the mechanics of starting sessions, sending messages, and capturing responses.
 
 ### Codex MCP (default)
 
-Uses Codex via MCP server for true conversational sessions.
+Uses Codex via MCP server for true conversational sessions. This is the recommended adapter for iterative work where you need back-and-forth refinement.
 
 ```bash
 # Sync mode (conversational)
@@ -122,17 +150,45 @@ zwarm exec --adapter codex_mcp --task "Add a login function"
 # using delegate() and converse() tools
 ```
 
-**Requires:** `codex` CLI installed, `OPENAI_API_KEY` set
+| Setting | Value |
+|---------|-------|
+| Default model | `gpt-5.1-codex-mini` |
+| Requires | `codex` CLI installed |
+| Auth | `OPENAI_API_KEY` environment variable |
 
 ### Claude Code
 
-Uses Claude Code CLI for execution.
+Uses Claude Code CLI for execution. Good alternative when you want Claude's capabilities.
 
 ```bash
 zwarm exec --adapter claude_code --task "Fix the type errors"
 ```
 
-**Requires:** `claude` CLI installed, authenticated
+| Setting | Value |
+|---------|-------|
+| Default model | `claude-sonnet-4-5-20250514` |
+| Requires | `claude` CLI installed and authenticated |
+| Auth | `ANTHROPIC_API_KEY` or `claude` CLI auth |
+
+### Model Selection
+
+Models are selected with this precedence (highest to lowest):
+
+1. **Per-delegation override**: `delegate(task="...", model="o3")`
+2. **Config file**: `executor.model` in config.toml or zwarm.yaml
+3. **Adapter default**: Each adapter has a sensible default
+
+```yaml
+# config.toml - override the default model
+[executor]
+adapter = "codex_mcp"
+model = "gpt-5.1-codex-max"  # Use the more capable model
+```
+
+```bash
+# Or override per-execution
+zwarm exec --model gpt-5.1-codex-max --task "Complex refactoring"
+```
 
 ## Watchers (Trajectory Alignment)
 
@@ -143,10 +199,11 @@ Watchers are composable guardrails that monitor agent behavior and can intervene
 | Watcher | Description |
 |---------|-------------|
 | `progress` | Detects stuck/spinning agents |
-| `budget` | Monitors step/session limits |
+| `budget` | Monitors step/session limits (counts only active sessions) |
 | `scope` | Detects scope creep from original task |
 | `pattern` | Custom regex pattern matching |
 | `quality` | Code quality checks |
+| `delegation` | Ensures orchestrator delegates instead of writing code directly |
 
 ### Enabling Watchers
 
@@ -204,6 +261,41 @@ View traces at: `https://wandb.ai/your-entity/zwarm/weave`
 
 ## CLI Reference
 
+### init
+
+Initialize zwarm in a project directory.
+
+```bash
+zwarm init [OPTIONS]
+
+Options:
+  -w, --working-dir PATH    Working directory [default: .]
+  -y, --yes                 Accept defaults, no prompts
+  --with-project            Also create zwarm.yaml project config
+```
+
+**What it creates:**
+
+1. `config.toml` - User settings (Weave project, adapter preferences, watchers)
+2. `.zwarm/` - State directory for sessions and events
+3. `zwarm.yaml` (optional) - Project-specific task configuration
+
+**Examples:**
+
+```bash
+# Interactive setup with prompts
+zwarm init
+
+# Non-interactive with defaults
+zwarm init --yes
+
+# Create project config too
+zwarm init --with-project
+
+# Initialize in a different directory
+zwarm init --working-dir /path/to/project
+```
+
 ### orchestrate
 
 Start an orchestrator session to delegate tasks.
@@ -222,19 +314,20 @@ Options:
 
 ### exec
 
-Run a single executor directly (for testing).
+Run a single executor directly (for testing). This bypasses the orchestrator entirely and hits the adapter (Codex/Claude) immediately with your task - useful for verifying adapters work before running full orchestration.
 
 ```bash
 zwarm exec [OPTIONS]
 
 Options:
   -t, --task TEXT           Task to execute
-  -f, --task-file PATH      Read task from file
   --adapter TEXT            Adapter to use [default: codex_mcp]
   --model TEXT              Model override
   --mode [sync|async]       Execution mode [default: sync]
 ```
 
+**Note:** Unlike `orchestrate`, this does NOT use watchers, compaction, state persistence, or multi-step planning. It's a single direct call to the executor.
+
 ### status
 
 Show current orchestrator state.
@@ -270,6 +363,30 @@ zwarm configs list          # List available configs
 zwarm configs show NAME     # Show config contents
 ```
 
+### clean
+
+Clean up zwarm state (useful for starting fresh).
+
+```bash
+zwarm clean [OPTIONS]
+
+Options:
+  --all                     Remove everything (events, sessions, state)
+  --events                  Remove only events
+  --sessions                Remove only sessions
+  -y, --yes                 Skip confirmation prompt
+```
+
+**Examples:**
+
+```bash
+# Clean everything and start fresh
+zwarm clean --all --yes
+
+# Clean only events log
+zwarm clean --events
+```
+
 ## Architecture
 
 ```
@@ -320,10 +437,16 @@ All state is stored in flat files under `.zwarm/`:
 ### Running Tests
 
 ```bash
-# From workspace root
-uv run pytest wbal/tests/ -v
+# Run all zwarm tests (68 tests)
+uv run pytest src/zwarm/ -v
+
+# Run specific test modules
+uv run pytest src/zwarm/core/test_compact.py -v      # Context compaction
+uv run pytest src/zwarm/watchers/test_watchers.py -v # Watchers
+uv run pytest src/zwarm/adapters/test_codex_mcp.py -v # Codex adapter
 
-# zwarm doesn't have its own tests yet
+# Run integration tests (requires codex CLI)
+uv run pytest -m integration
 ```
 
 ### Project Structure
@@ -333,19 +456,22 @@ zwarm/
 ├── src/zwarm/
 │   ├── adapters/           # Executor adapters
 │   │   ├── base.py         # ExecutorAdapter protocol
-│   │   ├── codex_mcp.py    # Codex MCP adapter
-│   │   └── claude_code.py  # Claude Code adapter
+│   │   ├── codex_mcp.py    # Codex MCP adapter (with token tracking)
+│   │   └── claude_code.py  # Claude Code adapter (with token tracking)
 │   ├── cli/
 │   │   └── main.py         # Typer CLI
 │   ├── core/
+│   │   ├── compact.py      # Context window compaction (LRU pruning)
 │   │   ├── config.py       # Configuration loading
-│   │   ├── models.py       # ConversationSession, Message, etc.
+│   │   ├── environment.py  # OrchestratorEnv (progress display)
+│   │   ├── models.py       # ConversationSession, Message, Event, etc.
 │   │   └── state.py        # Flat-file state management
 │   ├── tools/
-│   │   └── delegation.py   # delegate, converse, etc.
+│   │   └── delegation.py   # delegate, converse, check_session, etc.
 │   ├── watchers/
 │   │   ├── base.py         # Watcher protocol
-│   │   ├── builtin.py      # Built-in watchers
+│   │   ├── builtin.py      # Built-in watchers (progress, budget, scope, etc.)
+│   │   ├── registry.py     # Watcher registration
 │   │   └── manager.py      # WatcherManager
 │   ├── prompts/
 │   │   └── orchestrator.py # Orchestrator system prompt

{zwarm-0.1.0 → zwarm-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zwarm"
-version = "0.1.0"
+version = "1.0.0"
 description = "Multi-Agent CLI Orchestration Research Platform"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"