agent-worker 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # agent-worker
 
-CLI and SDK for creating and managing AI agent sessions with multiple backends.
+CLI and SDK for running AI agents — from standalone instances to collaborative workflows.
 
 ## Installation
 
@@ -10,244 +10,385 @@ npm install -g agent-worker
 bun add -g agent-worker
 ```
 
-## CLI Usage
+## Two Modes of Operation
 
-### Session Management
+agent-worker supports two distinct usage patterns:
 
-```bash
-# Create a session (SDK backend, default)
-agent-worker session new -m anthropic/claude-sonnet-4-5
-
-# Create with system prompt
-agent-worker session new -s "You are a code reviewer."
+| Mode | Use Case | Entry Point | Coordination |
+|------|----------|-------------|--------------|
+| **Agent** | Single AI assistant | CLI commands | Direct interaction |
+| **Workflow** | Multi-agent collaboration | YAML workflow file | @mention-based |
 
-# Create with system prompt from file
-agent-worker session new -f ./prompts/reviewer.txt
+---
 
-# Create named session
-agent-worker session new -n my-session
+## 🤖 Agent Mode
 
-# Create with Claude CLI backend
-agent-worker session new -b claude
+**Run individual AI agents as standalone instances.**
 
-# List all sessions
-agent-worker session list
+Perfect for: testing, prototyping, interactive Q&A, code assistance.
 
-# Switch default session
-agent-worker session use my-session
+### Quick Start
 
-# Check session status
-agent-worker session status
+```bash
+# Start an agent
+agent-worker new alice -m anthropic/claude-sonnet-4-5
 
-# End session
-agent-worker session end
+# Send a message
+agent-worker send alice "Analyze this codebase"
 
-# End specific session
-agent-worker session end my-session
+# View conversation
+agent-worker peek
 
-# End all sessions
-agent-worker session end --all
+# Check status
+agent-worker status alice
 ```
 
-### Sending Messages
+### Organizing Agents
+
+Agents can be grouped into **workflows** by defining them in YAML:
+
+```yaml
+# review.yaml
+agents:
+  reviewer:
+    backend: claude
+    system_prompt: You are a code reviewer.
+
+  coder:
+    backend: cursor
+    system_prompt: You are a code implementer.
+```
 
 ```bash
-# Send to current session
-agent-worker send "What is 2+2?"
+# 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"
+```
 
-# Send to specific session
-agent-worker send "Explain recursion" --to my-session
+**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).
 
-# View conversation history
-agent-worker history
-agent-worker history --last 5
+### Multiple Instances (workflow:tag)
 
-# View token usage
-agent-worker stats
+Run multiple isolated instances of the same workflow using **tags**:
 
-# Export transcript
-agent-worker export > transcript.json
+```bash
+# Different PRs, isolated contexts
+agent-worker run review.yaml --tag pr-123
+agent-worker run review.yaml --tag pr-456
 
-# Clear history (keep session)
-agent-worker clear
+# 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
 ```
 
-### Tool Management (SDK Backend Only)
+**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
 
 ```bash
-# Add a tool
-agent-worker tool add get_weather \
-  -d "Get weather for a location" \
-  -p "location:string:City name"
+# 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
+
+# Shared documents
+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
+```
 
-# Add tool requiring approval
-agent-worker tool add delete_file \
-  -d "Delete a file" \
-  -p "path:string:File path" \
-  --needs-approval
+### Backend Options
 
-# Import tools from file
-agent-worker tool import ./my-tools.ts
+```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
+```
 
-# Mock tool response (for testing)
-agent-worker tool mock get_weather '{"temp": 72, "condition": "sunny"}'
+### Examples
 
-# List registered tools
-agent-worker tool list
+**Quick testing without API keys:**
+```bash
+agent-worker new -b mock
+agent-worker send a0 "Hello"
 ```
 
-### Approval Workflow
+**Scheduled agent (runs every 30s when idle):**
+```bash
+# Standalone agent with wakeup schedule
+agent-worker new monitor --wakeup 30s --prompt "Check CI status"
 
+# Or schedule existing agent
+agent-worker schedule monitor set 30s --prompt "Check CI status"
+```
+
+**Send to workflow (broadcast or @mention):**
 ```bash
-# Check pending approvals
-agent-worker pending
+# Broadcast to entire workflow
+agent-worker send @review "Status update"
 
-# Approve a tool call
-agent-worker approve <approval-id>
+# @mention specific agents in workflow
+agent-worker send @review "@alice @bob discuss this"
+```
 
-# Deny with reason
-agent-worker deny <approval-id> -r "Path not allowed"
+**Feedback-enabled agent (reports observations):**
+```bash
+agent-worker new -m anthropic/claude-sonnet-4-5 --feedback
 ```
 
-### Agent Skills
+---
 
-Agent skills provide reusable instructions and methodologies that agents can access on demand. Compatible with the [Agent Skills](https://agentskills.io) ecosystem.
+## 📋 Workflow Mode
 
-```bash
-# Load skills from default directories (.agents/skills, .claude/skills, ~/.agents/skills)
-agent-worker session new
+**Define multi-agent collaboration through YAML workflows.**
+
+Perfect for: structured tasks, agent orchestration, reproducible pipelines.
 
-# Add a specific skill directory
-agent-worker session new --skill ./my-skills/custom-skill
+### Quick Start
 
-# Scan additional directories for skills
-agent-worker session new --skill-dir ./team-skills --skill-dir ~/shared-skills
+```yaml
+# review.yaml
+agents:
+  reviewer:
+    backend: claude
+    system_prompt: You are a code reviewer. Provide constructive feedback.
 
-# Combine multiple options
-agent-worker session new \
-  --skill ./my-skills/dive \
-  --skill-dir ~/company-skills
+  coder:
+    backend: cursor
+    model: sonnet-4.5
+    system_prompt: You implement code changes based on feedback.
 
-# Import skills from Git repositories (temporary, session-scoped)
-agent-worker session new --import-skill vercel-labs/agent-skills:dive
-agent-worker session new --import-skill lidessen/skills:{memory,orientation}
-agent-worker session new --import-skill gitlab:myorg/skills@v1.0.0:custom
+kickoff: |
+  @reviewer Review the recent changes and provide feedback.
+  @coder Implement the suggested improvements.
 ```
 
-**Import Skill Spec Format:**
+```bash
+# Run once and exit
+agent-worker run review.yaml
 
-The `--import-skill` option supports temporary skill imports from Git repositories. Skills are cloned to a session-specific temp directory and cleaned up when the session ends.
+# Run and keep agents alive
+agent-worker start review.yaml
 
-```
-[provider:]owner/repo[@ref]:{skill1,skill2,...}
+# Run in background
+agent-worker start review.yaml --background
 ```
 
-Examples:
-- `vercel-labs/agent-skills` - Import all skills from GitHub main branch
-- `vercel-labs/agent-skills:dive` - Import single skill
-- `vercel-labs/agent-skills:{dive,memory}` - Import multiple skills (brace expansion)
-- `vercel-labs/agent-skills@v1.0.0:dive` - Import from specific tag/branch
-- `gitlab:myorg/skills:custom` - Import from GitLab
-- `gitee:org/repo@dev:{a,b}` - Import from Gitee dev branch
+### Workflow Instances (Tags)
 
-Supported providers: `github` (default), `gitlab`, `gitee`
+Run the same workflow definition with different contexts:
 
-**Skills Support by Backend:**
-
-| Backend | Skills Support | How It Works | `--import-skill` |
-|---------|----------------|--------------|------------------|
-| **SDK** (default) | ✅ Full | Skills loaded as a tool that agents can call | ✅ Supported |
-| **Claude CLI** | ✅ Full | Loads from `.claude/skills/` and `~/.claude/skills/` | ⚠️ Manual install required |
-| **Codex CLI** | ✅ Full | Loads from `.agents/skills/`, `~/.codex/skills/`, `~/.agents/skills/` | ⚠️ Manual install required |
-| **Cursor CLI** | ✅ Full | Loads from `.agents/skills/` and `~/.cursor/skills/` | ⚠️ Manual install required |
+```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
+```
 
-**Notes:**
-- **SDK Backend**: Skills work through the Skills tool, allowing dynamic file reading. `--import-skill` is fully supported.
-- **CLI Backends** (claude, codex, cursor): Skills are loaded from filesystem locations by the CLI tool itself. To use `--import-skill` with these backends, install skills manually using `npx skills add <repo> --global`.
-- If you specify `--import-skill` with a CLI backend, agent-worker will show a warning and suggest using SDK backend or manual installation.
+### Workflow Structure
+
+```yaml
+# Full workflow structure
+name: code-review  # 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
+    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)
+
+# 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
+
+# Kickoff message (starts the workflow)
+kickoff: |
+  @alice Review these changes:
+
+  Recent commits:
+  ${{ recent_commits }}
+
+  Diff:
+  ${{ changes }}
+
+  @bob Stand by for implementation tasks.
+```
 
-**Default Skill Directories:**
-- `.agents/skills/` - Project-level skills (all backends)
-- `.claude/skills/` - Claude Code project skills
-- `.cursor/skills/` - Cursor project skills
-- `~/.agents/skills/` - User-level global skills (all backends)
-- `~/.claude/skills/` - User-level Claude skills
-- `~/.codex/skills/` - User-level Codex skills
+### Workflow Commands
 
-**Using Skills in Sessions:**
+```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
+```
 
-Once loaded, agents can interact with skills via the `Skills` tool:
+### Variable Interpolation
 
-```typescript
-// List available skills
-Skills({ operation: 'list' })
+Templates support `${{ variable }}` syntax:
 
-// View a skill's complete instructions
-Skills({ operation: 'view', skillName: 'dive' })
+```yaml
+setup:
+  - shell: echo "pr-${{ env.PR_NUMBER }}"
+    as: branch_name
 
-// Read skill reference files
-Skills({
-  operation: 'readFile',
-  skillName: 'dive',
-  filePath: 'references/search-strategies.md'
-})
+kickoff: |
+  Workflow: ${{ workflow.name }}
+  Tag: ${{ workflow.tag }}
+  Branch: ${{ branch_name }}
 ```
 
-**Installing Skills:**
+Available variables:
+- `${{ workflow.name }}` - Workflow name
+- `${{ workflow.tag }}` - Instance tag
+- `${{ env.VAR }}` - Environment variable
+- `${{ task_output }}` - Setup task output (via `as:` field)
 
-Use the [skills CLI](https://github.com/vercel-labs/skills) to install skills:
+### Coordination Patterns
 
-```bash
-# Install from GitHub
-npx skills add vercel-labs/agent-skills
+**Sequential handoff:**
+```yaml
+kickoff: |
+  @alice Start the task.
+```
+Alice's message: "Done! @bob your turn"
 
-# Or use the official skills tool
-npm install -g @agentskills/cli
-skills add vercel-labs/agent-skills
+**Parallel broadcast:**
+```yaml
+kickoff: |
+  @alice @bob @charlie All review this code.
 ```
 
-### Backends
+**Document-based:**
+```yaml
+agents:
+  writer:
+    system_prompt: Write analysis to the shared document.
 
-```bash
-# Check available backends
-agent-worker backends
+  reviewer:
+    system_prompt: Read the document and provide feedback.
 
-# Check SDK providers
-agent-worker providers
+context:
+  provider: file
+  config:
+    bind: ./results/  # Persistent across runs
 ```
 
-| Backend | Command | Best For |
-|---------|---------|----------|
-| SDK (default) | `session new -m provider/model` | Full control, tool injection, mocking |
-| Claude CLI | `session new -b claude` | Use existing Claude installation |
-| Codex | `session new -b codex` | OpenAI Codex workflows |
-| Cursor | `session new -b cursor` | Cursor Agent integration |
+### Examples
 
-> **⚠️ Important:** Different backends have different capabilities. CLI backends (claude, codex, cursor) don't support:
-> - Dynamic tool management (`tool_add`, `tool_mock`, `tool_import`)
-> - Approval system (`approve`, `deny`)
-> - `--import-skill` (use `npx skills add --global` instead)
->
-> See [BACKEND_COMPATIBILITY.md](./BACKEND_COMPATIBILITY.md) for a complete feature comparison.
+**PR Review Workflow:**
+```yaml
+# review.yaml
+agents:
+  reviewer:
+    backend: claude
+    system_prompt: Review code for bugs, style, performance.
 
-### Model Formats (SDK Backend)
+setup:
+  - shell: gh pr diff ${{ env.PR_NUMBER }}
+    as: diff
 
-```bash
-# Gateway format (recommended)
-agent-worker session new -m anthropic/claude-sonnet-4-5
-agent-worker session new -m openai/gpt-5.2
+kickoff: |
+  @reviewer Review this PR:
+
+  ${{ diff }}
+```
 
-# Provider-only (uses frontier model)
-agent-worker session new -m anthropic
-agent-worker session new -m openai
+```bash
+PR_NUMBER=123 agent-worker run review.yaml --tag pr-123
+```
 
-# Direct provider format
-agent-worker session new -m deepseek:deepseek-chat
+**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
+---
+
+## 🔧 SDK Usage
 
-### Basic Session
+For programmatic control (TypeScript/JavaScript):
 
 ```typescript
 import { AgentSession } from 'agent-worker'
@@ -269,123 +410,77 @@ for await (const chunk of session.sendStream('Tell me a story')) {
   process.stdout.write(chunk)
 }
 
-// Get state for persistence
+// State management
 const state = session.getState()
+// Later: restore from state
 ```
 
 ### With Skills
 
 ```typescript
-import {
-  AgentSession,
-  SkillsProvider,
-  createSkillsTool
-} from 'agent-worker'
+import { AgentSession, SkillsProvider, createSkillsTool } from 'agent-worker'
 
-// Setup skills
 const skillsProvider = new SkillsProvider()
 await skillsProvider.scanDirectory('.agents/skills')
-await skillsProvider.scanDirectory('~/my-skills')
 
-// Or add individual skills
-await skillsProvider.addSkill('./custom-skills/my-skill')
-
-// Create session with Skills tool
 const session = new AgentSession({
   model: 'anthropic/claude-sonnet-4-5',
   system: 'You are a helpful assistant.',
-  tools: [
-    createSkillsTool(skillsProvider),
-    // ... other tools
-  ]
+  tools: [createSkillsTool(skillsProvider)]
 })
-
-// Agent can now access skills
-const response = await session.send(
-  'What skills are available? Use the dive skill to analyze this codebase.'
-)
 ```
 
-### With Imported Skills
-
-```typescript
-import {
-  AgentSession,
-  SkillsProvider,
-  SkillImporter,
-  createSkillsTool
-} from 'agent-worker'
-
-// Setup skills provider
-const skillsProvider = new SkillsProvider()
+---
 
-// Import skills from Git repositories
-const sessionId = 'my-session-123'
-const importer = new SkillImporter(sessionId)
+## 📊 Comparison: Agent vs Workflow
 
-// Import from GitHub
-await importer.import('vercel-labs/agent-skills:dive')
-await importer.import('lidessen/skills:{memory,orientation}')
+| 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 |
 
-// Or import multiple specs at once
-await importer.importMultiple([
-  'vercel-labs/agent-skills:{dive,react}',
-  'gitlab:myorg/skills@v1.0.0:custom'
-])
-
-// Add imported skills to provider
-await skillsProvider.addImportedSkills(importer)
-
-// Create session
-const session = new AgentSession({
-  model: 'anthropic/claude-sonnet-4-5',
-  system: 'You are a helpful assistant.',
-  tools: [createSkillsTool(skillsProvider)]
-})
-
-// Don't forget cleanup when done
-process.on('exit', async () => {
-  await importer.cleanup()
-})
+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
 ```
 
-## Common Patterns
+---
 
-### Prompt Testing
+## 🎯 Model Formats
 
 ```bash
-agent-worker session new -f ./my-prompt.txt -n test
-agent-worker send "Test case 1: ..." --to test
-agent-worker send "Test case 2: ..." --to test
-agent-worker history --to test
-agent-worker session end test
+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
 ```
 
-### Tool Development with Mocks
+---
 
-```bash
-agent-worker session new -n dev
-agent-worker tool add my_api -d "Call my API" -p "endpoint:string"
-agent-worker tool mock my_api '{"status": "ok"}'
-agent-worker send "Call my API at /users"
-# Update mock, test error handling
-agent-worker tool mock my_api '{"status": "error", "code": 500}'
-agent-worker send "Call my API at /users"
-```
+## 📚 Documentation
 
-### Multi-Model Comparison
+| 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 |
 
-```bash
-agent-worker session new -m anthropic/claude-sonnet-4-5 -n claude
-agent-worker session new -m openai/gpt-5.2 -n gpt
-agent-worker send "Explain recursion" --to claude
-agent-worker send "Explain recursion" --to gpt
-```
+---
 
 ## Requirements
 
 - Node.js 18+ or Bun
-- API key for chosen provider (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
+- API key for chosen provider (e.g., `ANTHROPIC_API_KEY`)
+
+---
 
 ## License