agent-worker 0.11.0 → 0.13.0

package/README.md

@@ -1,418 +1,255 @@
 # agent-worker
 
-CLI and SDK for running AI agents — from standalone instances to collaborative workflows.
-
-## Installation
+Run AI agents from the terminal. One agent or many, talking to each other.
 
 ```bash
 npm install -g agent-worker
-# or
-bun add -g agent-worker
 ```
 
-## Two Modes of Operation
+```bash
+# Start an agent, send it a task
+agent-worker new alice -m anthropic/claude-sonnet-4-5
+agent-worker send alice "Refactor the auth module"
+
+# Or define a team in YAML and let them collaborate
+agent-worker run review.yaml
+```
+
+## Why agent-worker?
+
+Most agent frameworks lock you into a single provider and a single execution model.
+agent-worker gives you **one CLI** that works across backends (Claude CLI, Cursor, Codex, or raw SDK)
+and scales from a single assistant to a team of agents coordinating via @mentions.
+
+- **Multi-backend** — Same commands whether your agent runs on Claude CLI, Cursor, Codex, or the Vercel AI SDK
+- **Single & multi-agent** — Start one agent interactively, or define a team workflow in YAML
+- **@mention coordination** — Agents talk to each other naturally: `@reviewer check this`, `@coder fix it`
+- **Shared context** — Channel (messages), documents (workspace), resources (large content) — all agents see the same state
+- **Instance isolation** — Run the same workflow for different PRs/tasks with `--tag`, fully isolated
+- **SDK included** — Use programmatically from TypeScript when the CLI isn't enough
 
-agent-worker supports two distinct usage patterns:
+## Design Philosophy
 
-| Mode | Use Case | Entry Point | Coordination |
-|------|----------|-------------|--------------|
-| **Agent** | Single AI assistant | CLI commands | Direct interaction |
-| **Workflow** | Multi-agent collaboration | YAML workflow file | @mention-based |
+The central question we're exploring: **how do you make a system of short-lived agents accumulate progress over time?**
 
----
+One approach is to give each agent a persistent memory — recall past conversations, learn preferences, build a model of the world. But for engineering work, the value of making an agent more "human-like" is limited. An agent that remembers everything it did last week doesn't necessarily write better code today.
 
-## 🤖 Agent Mode
+So we start from a different assumption: **an agent's lifetime is one tool loop.** It starts, it works, it's gone. No memory, no continuity, no identity.
 
-**Run individual AI agents as standalone instances.**
+The question then becomes: if each agent is ephemeral, where does the continuity live? Our answer is **collective memory** — not stored in any individual agent, but in the shared artifacts they produce. Channels capture the conversation. Documents hold the evolving workspace. Event logs record what happened. The next agent reads these artifacts, picks up where the last one left off, and pushes forward.
 
-Perfect for: testing, prototyping, interactive Q&A, code assistance.
+This has a property we find compelling: **it scales with the context window.** As models can process more context, agents naturally absorb more of the shared history and make better decisions — without changing a line of code. Contrast this with approaches that program around individual agent limitations (elaborate prompts, rule systems, retrieval hacks). Those techniques solve today's constraints but become dead weight as models improve.
 
-### Quick Start
+We're not building smarter agents. We're building a better environment for agents to work in.
+
+## Quick Start
+
+### Single Agent
 
 ```bash
-# Start an agent
+# Create and interact
 agent-worker new alice -m anthropic/claude-sonnet-4-5
-
-# Send a message
 agent-worker send alice "Analyze this codebase"
+agent-worker peek                    # View conversation
 
-# View conversation
-agent-worker peek
-
-# Check status
-agent-worker status alice
+# Try without API keys
+agent-worker new -b mock
+agent-worker send a0 "Hello"
 ```
 
-### Organizing Agents
-
-Agents can be grouped into **workflows** by defining them in YAML:
+### Multi-Agent Workflow
 
 ```yaml
 # review.yaml
 agents:
   reviewer:
-    backend: claude
-    system_prompt: You are a code reviewer.
+    model: anthropic/claude-sonnet-4-5
+    system_prompt: |
+      You are a code reviewer. When you find issues, @coder to fix them.
 
   coder:
-    backend: cursor
-    system_prompt: You are a code implementer.
+    model: anthropic/claude-sonnet-4-5
+    system_prompt: |
+      You are a coder. Fix issues found by the reviewer.
+      After fixing, @reviewer to verify.
+
+setup:
+  - shell: git diff HEAD~1
+    as: diff
+
+kickoff: |
+  PR diff:
+  ${{ diff }}
+
+  @reviewer please review these changes.
 ```
 
 ```bash
-# Run workflow agents (workflow name from YAML)
 agent-worker run review.yaml
-
-# Send to specific agent in workflow
-agent-worker send reviewer@review "Check this code"
 ```
 
-**Note**: Agent Mode (`agent-worker new`) only creates standalone agents in the global workflow. For coordinated agents in named workflows, use Workflow Mode (YAML files).
+That's it. The reviewer reads the diff, finds issues, @mentions the coder. The coder fixes them, @mentions back. They iterate until done.
 
-### Multiple Instances (workflow:tag)
+## CLI Reference
 
-Run multiple isolated instances of the same workflow using **tags**:
+### Agent Lifecycle
 
 ```bash
-# Different PRs, isolated contexts
-agent-worker run review.yaml --tag pr-123
-agent-worker run review.yaml --tag pr-456
-
-# Each has its own conversation history
-agent-worker send reviewer@review:pr-123 "LGTM"
-agent-worker peek @review:pr-123  # Only sees pr-123 messages
+agent-worker new <name> [options]       # Create agent
+agent-worker stop <target>              # Stop agent or workflow
+agent-worker ls [target]                # List agents (--all for everything)
+agent-worker status <target>            # Agent status
 ```
 
-**Target syntax** (used in send/peek/ls/stop commands):
-- `alice` → alice@global:main (standalone agent)
-- `alice@review` → alice@review:main (agent in review workflow)
-- `alice@review:pr-123` → full specification
-- `@review` → review workflow (for broadcast or listing)
-- `@review:pr-123` → specific workflow instance
-
-### Agent Commands
+### Communication
 
 ```bash
-# Lifecycle
-agent-worker new <name> [options]        # Create standalone agent
-agent-worker stop <target>               # Stop agent
-agent-worker ls [target]                 # List agents (default: global)
-agent-worker ls --all                    # List all agents from all workflows
-agent-worker status <target>             # Check agent status
-
-# Interaction
-agent-worker send <target> <message>     # Send to agent or workflow
-agent-worker peek [target] [options]     # View messages (default: @global)
-
-# Scheduling (periodic wakeup when idle)
-agent-worker schedule <target> set <interval> [--prompt "Task"]
-agent-worker schedule <target> get
-agent-worker schedule <target> clear
+agent-worker send <target> <message>    # Send message
+agent-worker send @review "Status?"     # Broadcast to workflow
+agent-worker peek [target]              # View messages
+```
 
-# Shared documents
+### Shared Documents
+
+```bash
 agent-worker doc read <target>
 agent-worker doc write <target> --content "..."
 agent-worker doc append <target> --file notes.txt
-
-# Testing & Debugging
-agent-worker mock tool <name> <response>    # Mock tool response
-agent-worker feedback [target]              # View agent feedback/observations
 ```
 
-### Backend Options
+### Scheduling
 
 ```bash
-agent-worker new alice -m anthropic/claude-sonnet-4-5  # SDK (default)
-agent-worker new alice -b claude                       # Claude CLI
-agent-worker new alice -b cursor                       # Cursor Agent
-agent-worker new alice -b mock                         # Testing (no API)
-
-# Specify tools at creation (SDK backend only)
-agent-worker new alice --tool ./custom-tools.ts
-agent-worker new alice --skill ./skills --tool ./tools.ts
+agent-worker schedule <target> set 30s --prompt "Check CI status"
+agent-worker schedule <target> get
+agent-worker schedule <target> clear
 ```
 
-### Examples
+### Workflows
 
-**Quick testing without API keys:**
 ```bash
-agent-worker new -b mock
-agent-worker send a0 "Hello"
+agent-worker run <file> [--tag tag]           # Run once, exit when done
+agent-worker start <file> [--tag tag]         # Keep alive after kickoff
+agent-worker start <file> --background        # Daemon mode
 ```
 
-**Scheduled agent (runs every 30s when idle):**
-```bash
-# Standalone agent with wakeup schedule
-agent-worker new monitor --wakeup 30s --prompt "Check CI status"
+## Target Syntax
 
-# Or schedule existing agent
-agent-worker schedule monitor set 30s --prompt "Check CI status"
-```
+Agents live in workflows. Standalone agents go into a default `global` workflow.
 
-**Send to workflow (broadcast or @mention):**
-```bash
-# Broadcast to entire workflow
-agent-worker send @review "Status update"
-
-# @mention specific agents in workflow
-agent-worker send @review "@alice @bob discuss this"
 ```
-
-**Feedback-enabled agent (reports observations):**
-```bash
-agent-worker new -m anthropic/claude-sonnet-4-5 --feedback
+alice                → alice@global:main     (standalone agent)
+alice@review         → alice@review:main     (agent in "review" workflow)
+alice@review:pr-123  → alice@review:pr-123   (specific instance)
+@review              → review workflow       (broadcast)
+@review:pr-123       → specific instance
 ```
 
----
-
-## 📋 Workflow Mode
-
-**Define multi-agent collaboration through YAML workflows.**
-
-Perfect for: structured tasks, agent orchestration, reproducible pipelines.
-
-### Quick Start
-
-```yaml
-# review.yaml
-agents:
-  reviewer:
-    backend: claude
-    system_prompt: You are a code reviewer. Provide constructive feedback.
-
-  coder:
-    backend: cursor
-    model: sonnet-4.5
-    system_prompt: You implement code changes based on feedback.
-
-kickoff: |
-  @reviewer Review the recent changes and provide feedback.
-  @coder Implement the suggested improvements.
-```
+Use `--tag` to run isolated instances of the same workflow:
 
 ```bash
-# Run once and exit
-agent-worker run review.yaml
-
-# Run and keep agents alive
-agent-worker start review.yaml
-
-# Run in background
-agent-worker start review.yaml --background
+agent-worker run review.yaml --tag pr-123
+agent-worker run review.yaml --tag pr-456    # Completely independent
 ```
 
-### Workflow Instances (Tags)
-
-Run the same workflow definition with different contexts:
+## Backends
 
 ```bash
-# Each PR gets its own isolated instance (workflow name from YAML)
-agent-worker run review.yaml --tag pr-123
-agent-worker run review.yaml --tag pr-456
-
-# Context isolation
-├── .workflow/
-│   └── review/
-│       ├── pr-123/    # Independent channel + documents
-│       └── pr-456/    # Independent channel + documents
+agent-worker new alice -m anthropic/claude-sonnet-4-5   # Vercel AI SDK (default)
+agent-worker new alice -b claude                         # Claude CLI
+agent-worker new alice -b cursor                         # Cursor Agent
+agent-worker new alice -b codex                          # OpenAI Codex
+agent-worker new alice -b mock                           # No API calls (testing)
 ```
 
-### Workflow Structure
+| Capability | SDK | Claude CLI | Cursor | Codex | Mock |
+|------------|-----|-----------|--------|-------|------|
+| Custom tools | Yes | Via MCP | No | No | Yes |
+| Streaming | Yes | Yes | Yes | Yes | No |
+| Token tracking | Yes | Partial | No | No | Yes |
+| Skills import | Yes | Filesystem | Filesystem | Filesystem | Yes |
+
+## Workflow YAML
+
+### Full Structure
 
 ```yaml
-# Full workflow structure
-name: code-review  # Optional, defaults to filename
+name: my-workflow                           # Optional, defaults to filename
 
 agents:
   alice:
-    backend: sdk | claude | cursor | codex | mock
-    model: anthropic/claude-sonnet-4-5  # Required for SDK
-    system_prompt: |
-      You are Alice, a senior code reviewer.
-    tools: [bash, read, write]  # CLI backend tool names
+    backend: sdk                            # sdk | claude | cursor | codex | mock
+    model: anthropic/claude-sonnet-4-5      # Required for SDK backend
+    system_prompt: You are Alice.
+    system_prompt_file: ./prompts/alice.txt  # Or load from file
+    tools: [bash, read, write]              # CLI backend tool names
     max_tokens: 8000
     max_steps: 20
 
-  bob:
-    backend: claude
-    system_prompt_file: ./prompts/bob.txt  # Load from file
-
-# Context configuration (shared channel + documents)
 context:
   provider: file
   config:
     dir: ./.workflow/${{ workflow.name }}/${{ workflow.tag }}/  # Ephemeral
-    # OR
-    bind: ./data/${{ workflow.tag }}/  # Persistent (survives shutdown)
+    bind: ./data/                                              # Persistent
 
-# Setup commands (run before kickoff)
 setup:
-  - shell: git log --oneline -10
-    as: recent_commits  # Store output as variable
-
   - shell: git diff main...HEAD
-    as: changes
+    as: changes                             # Store output as variable
+  - shell: echo "$PR_NUMBER"
+    as: pr_num
 
-# Kickoff message (starts the workflow)
 kickoff: |
-  @alice Review these changes:
-
-  Recent commits:
-  ${{ recent_commits }}
-
-  Diff:
   ${{ changes }}
-
-  @bob Stand by for implementation tasks.
+  @alice Review this. @bob Stand by.
 ```
 
-### Workflow Commands
-
-```bash
-# Execution (workflow name inferred from YAML)
-agent-worker run <file> [--tag tag] [--json]    # Run once
-agent-worker start <file> [--tag tag]           # Keep alive
-agent-worker start <file> --background          # Daemon mode
-agent-worker stop @<workflow:tag>               # Stop workflow
-
-# Monitoring
-agent-worker ls @<workflow:tag>          # List agents in workflow
-agent-worker peek @<workflow:tag>        # View channel messages
-agent-worker doc read @<workflow:tag>    # Read shared document
-
-# Debug
-agent-worker run <file> --debug          # Show internal logs
-agent-worker run <file> --feedback       # Enable observation tool
-```
-
-### Variable Interpolation
-
-Templates support `${{ variable }}` syntax:
-
-```yaml
-setup:
-  - shell: echo "pr-${{ env.PR_NUMBER }}"
-    as: branch_name
-
-kickoff: |
-  Workflow: ${{ workflow.name }}
-  Tag: ${{ workflow.tag }}
-  Branch: ${{ branch_name }}
-```
+### Variables
 
-Available variables:
-- `${{ workflow.name }}` - Workflow name
-- `${{ workflow.tag }}` - Instance tag
-- `${{ env.VAR }}` - Environment variable
-- `${{ task_output }}` - Setup task output (via `as:` field)
+- `${{ workflow.name }}` — Workflow name
+- `${{ workflow.tag }}` — Instance tag
+- `${{ env.VAR }}` — Environment variable
+- `${{ task_output }}` — Setup task output (via `as:` field)
 
 ### Coordination Patterns
 
-**Sequential handoff:**
+**Sequential** — One agent finishes, @mentions the next:
 ```yaml
-kickoff: |
-  @alice Start the task.
+kickoff: "@alice Start the analysis."
+# Alice: "Done! @bob your turn to implement."
 ```
-Alice's message: "Done! @bob your turn"
 
-**Parallel broadcast:**
+**Parallel** — Multiple agents work simultaneously:
 ```yaml
-kickoff: |
-  @alice @bob @charlie All review this code.
+kickoff: "@alice @bob @charlie All review this code."
 ```
 
-**Document-based:**
+**Document-based** — Agents collaborate through shared documents:
 ```yaml
-agents:
-  writer:
-    system_prompt: Write analysis to the shared document.
-
-  reviewer:
-    system_prompt: Read the document and provide feedback.
-
 context:
   provider: file
   config:
-    bind: ./results/  # Persistent across runs
+    bind: ./results/                        # Persistent across runs
 ```
 
-### Examples
-
-**PR Review Workflow:**
-```yaml
-# review.yaml
-agents:
-  reviewer:
-    backend: claude
-    system_prompt: Review code for bugs, style, performance.
-
-setup:
-  - shell: gh pr diff ${{ env.PR_NUMBER }}
-    as: diff
-
-kickoff: |
-  @reviewer Review this PR:
-
-  ${{ diff }}
-```
-
-```bash
-PR_NUMBER=123 agent-worker run review.yaml --tag pr-123
-```
-
-**Research & Summarize:**
-```yaml
-# research.yaml
-agents:
-  researcher:
-    backend: sdk
-    model: anthropic/claude-sonnet-4-5
-    system_prompt: Research topics and write findings to document.
-
-  summarizer:
-    backend: sdk
-    model: anthropic/claude-haiku-4-5
-    system_prompt: Read document and create concise summary.
-
-context:
-  provider: file
-  config:
-    bind: ./research-output/
-
-kickoff: |
-  @researcher Research "${{ env.TOPIC }}" and document findings.
-  @summarizer Wait for research to complete, then summarize.
-```
-
----
-
-## 🔧 SDK Usage
-
-For programmatic control (TypeScript/JavaScript):
+## SDK Usage
 
 ```typescript
 import { AgentWorker } from 'agent-worker'
 
-const session = new AgentWorker({
+const agent = new AgentWorker({
   model: 'anthropic/claude-sonnet-4-5',
   system: 'You are a helpful assistant.',
-  tools: [/* your tools */]
+  tools: [/* your tools */],
 })
 
-// Send message
-const response = await session.send('Hello')
+// Request-response
+const response = await agent.send('Hello')
 console.log(response.content)
-console.log(response.toolCalls)
-console.log(response.usage)
 
-// Stream response
-for await (const chunk of session.sendStream('Tell me a story')) {
+// Streaming
+for await (const chunk of agent.sendStream('Tell me a story')) {
   process.stdout.write(chunk)
 }
-
-// State management
-const state = session.getState()
-// Later: restore from state
 ```
 
 ### With Skills
@@ -420,67 +257,52 @@ const state = session.getState()
 ```typescript
 import { AgentWorker, SkillsProvider, createSkillsTool } from 'agent-worker'
 
-const skillsProvider = new SkillsProvider()
-await skillsProvider.scanDirectory('.agents/skills')
+const skills = new SkillsProvider()
+await skills.scanDirectory('.agents/skills')
 
-const session = new AgentWorker({
+const agent = new AgentWorker({
   model: 'anthropic/claude-sonnet-4-5',
   system: 'You are a helpful assistant.',
-  tools: [createSkillsTool(skillsProvider)]
+  tools: [createSkillsTool(skills)],
 })
 ```
 
----
+### Programmatic Workflows
 
-## 📊 Comparison: Agent vs Workflow
-
-| Feature | Agent Mode | Workflow Mode |
-|---------|------------|---------------|
-| **Definition** | CLI commands | YAML file |
-| **Agents** | One at a time | Multiple (orchestrated) |
-| **Coordination** | Manual (via commands) | Automatic (@mentions) |
-| **Context** | Shared channel + docs | Shared channel + docs |
-| **Isolation** | workflow:tag namespace | workflow:tag namespace |
-| **Setup** | Start agents manually | Declarative setup tasks |
-| **Best For** | Interactive tasks, testing | Structured workflows, automation |
+```typescript
+import { parseWorkflowFile, runWorkflowWithControllers } from 'agent-worker'
+
+const workflow = await parseWorkflowFile('review.yaml', { tag: 'pr-123' })
+const result = await runWorkflowWithControllers({
+  workflow,
+  workflowName: 'review',
+  tag: 'pr-123',
+  mode: 'run',
+})
 
-Both modes share the same underlying context system:
-```
-.workflow/
-├── global/main/        # Standalone agents (default)
-├── review/main/        # review workflow, main tag
-└── review/pr-123/      # review workflow, pr-123 tag
+console.log(result.success, result.duration)
 ```
 
----
-
-## 🎯 Model Formats
+## Model Formats
 
 ```bash
-agent-worker new -m anthropic/claude-sonnet-4-5   # Gateway (recommended)
-agent-worker new -m anthropic                      # Provider-only (frontier)
-agent-worker new -m deepseek:deepseek-chat         # Direct format
+agent-worker new -m anthropic/claude-sonnet-4-5    # Gateway format (recommended)
+agent-worker new -m anthropic                       # Provider shorthand (uses frontier)
+agent-worker new -m deepseek:deepseek-chat          # Direct provider format
 ```
 
----
-
-## 📚 Documentation
-
-| Doc | Description |
-|-----|-------------|
-| [ARCHITECTURE.md](./ARCHITECTURE.md) | System architecture and modules |
-| [docs/backends.md](./docs/backends.md) | Backend feature matrix |
-| [docs/workflow/](./docs/workflow/) | Workflow system design |
-| [TEST-ARCHITECTURE.md](./TEST-ARCHITECTURE.md) | Testing strategy |
-
----
-
 ## Requirements
 
 - Node.js 18+ or Bun
-- API key for chosen provider (e.g., `ANTHROPIC_API_KEY`)
+- API key for your chosen provider (e.g., `ANTHROPIC_API_KEY`)
+
+## Documentation
 
----
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — System architecture
+- [docs/backends.md](./docs/backends.md) — Backend comparison
+- [docs/workflow/](./docs/workflow/) — Workflow system design
+- [TEST-ARCHITECTURE.md](./TEST-ARCHITECTURE.md) — Testing strategy
+- [examples/](./examples/) — Example workflows
 
 ## License
 

package/dist/backends-BWzhErjT.mjs

@@ -0,0 +1,3 @@
+import { C as CLAUDE_MODEL_MAP, D as SDK_MODEL_ALIASES, E as OPENCODE_MODEL_MAP, O as getModelForBackend, S as BACKEND_DEFAULT_MODELS, T as CURSOR_MODEL_MAP, _ as extractCodexResult, a as createMockBackend, b as execWithIdleTimeout, c as extractOpenCodeResult, d as CodexBackend, f as ClaudeCodeBackend, g as extractClaudeResult, h as createStreamParser, i as MockAIBackend, k as normalizeBackendType, l as opencodeAdapter, m as codexAdapter, n as createBackend, o as SdkBackend, p as claudeAdapter, r as listBackends, s as OpenCodeBackend, t as checkBackends, u as CursorBackend, v as formatEvent, w as CODEX_MODEL_MAP, x as DEFAULT_IDLE_TIMEOUT, y as IdleTimeoutError } from "./backends-CziIqKRg.mjs";
+
+export { listBackends };