agent-relay 2.3.13 → 3.0.1

package/README.md

@@ -9,186 +9,267 @@
 
 ## Install
 
-**Quick install (recommended - no Node.js required!):**
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash
 ```
 
-This downloads a standalone binary that works without any dependencies.
+Or via npm (requires Node.js 18+):
 
-**Or via npm:**
 ```bash
 npm install -g agent-relay
 ```
 
-*The npm method requires Node.js 18+*
-
-## Getting Started
+## Quick Start
 
 ```bash
 agent-relay up --dashboard
 ```
 
-Navigate to **http://localhost:3888** to:
-- 🤖 Spawn and chat with agents using your locally installed CLI tools
-- 👀 View real-time agent presence and status
-- 💬 Message history and threading
-- 📜 Log streaming from all agents
+Open **http://localhost:3888** to spawn agents, view real-time status, and stream logs.
 
 ---
 
 ## CLI Reference
 
-| Command | Description |
-|---------|-------------|
-| `agent-relay <cli>` | Start daemon + coordinator (claude, codex, gemini, etc.) |
-| `agent-relay up` | Start daemon + dashboard |
-| `agent-relay down` | Stop daemon |
-| `agent-relay status` | Check daemon status |
-| `agent-relay spawn <name> <cli> "task"` | Spawn a worker agent |
-| `agent-relay bridge <projects...>` | Bridge multiple projects |
-| `agent-relay doctor` | Diagnose issues |
+| Command                                 | Description              |
+| --------------------------------------- | ------------------------ |
+| `agent-relay up`                        | Start broker + dashboard |
+| `agent-relay down`                      | Stop broker              |
+| `agent-relay spawn <name> <cli> "task"` | Spawn a worker agent     |
+| `agent-relay status`                    | Check broker status      |
+| `agent-relay run workflow.yaml`         | Run a YAML workflow      |
+| `agent-relay run --template feature-dev`| Run a built-in template  |
 
 ---
 
-## Agent Roles
+## Workflows
+
+Define multi-agent workflows in YAML, TypeScript, or Python. Run locally or queue to the cloud for 24/7 execution:
 
-Define roles by adding markdown files to your project:
+```bash
+# Run locally
+agent-relay run workflow.yaml --task "Add OAuth2 support"
 
+# Queue to cloud — durable, scalable, runs in sandboxes
+agent-relay run workflow.yaml --cloud --task "Add OAuth2 support"
+
+# Use built-in templates
+agent-relay run --template feature-dev --task "Add user dashboard"
 ```
-.claude/agents/
-├── lead.md          # Coordinator
-├── implementer.md   # Developer
-├── reviewer.md      # Code review
-└── designer.md      # UI/UX
+
+### relay.yaml
+
+Blueprint-style workflows combine **agent steps** (LLM-powered) with **deterministic steps** (shell commands) for faster, cheaper, more reliable execution:
+
+```yaml
+version: "1.0"
+name: ship-feature
+
+agents:
+  - name: planner
+    cli: claude
+    model: opus
+  - name: developer
+    cli: codex
+
+workflows:
+  - name: default
+    preflight:
+      - command: git status --porcelain
+        failIf: non-empty
+    steps:
+      - name: plan
+        agent: planner
+        task: "Create implementation plan for: {{task}}"
+      - name: create-branch
+        type: deterministic
+        command: git checkout -b feature/{{branch-name}}
+        dependsOn: [plan]
+      - name: implement
+        agent: developer
+        task: "Implement: {{steps.plan.output}}"
+        dependsOn: [create-branch]
+      - name: test
+        type: deterministic
+        command: npm test
+        dependsOn: [implement]
+      - name: commit
+        type: deterministic
+        command: git add -A && git commit -m "feat: {{task}}"
+        dependsOn: [test]
 ```
 
-Names automatically match roles (case-insensitive). Create agents using either method:
+**Benefits:** Deterministic steps run instantly ($0 LLM cost), catch issues early with preflight checks, and git commands can't hallucinate.
 
-**Option A: Dashboard (recommended for interactive use)**
-1. Open http://localhost:3888
-2. Click "Spawn Agent"
-3. Enter name "Lead" and select CLI "claude"
+Also available as fluent builders in [TypeScript SDK](https://www.npmjs.com/package/@agent-relay/sdk) and [Python SDK](https://pypi.org/project/agent-relay/).
 
-**Option B: CLI (for scripting/automation)**
-```bash
-agent-relay spawn Lead claude "Your task instructions"
-```
+### Built-in Templates
 
-Agents with matching names automatically assume the corresponding role from your `.claude/agents/` directory.
+All templates use blueprint-style hybrid workflows with deterministic quality gates.
 
-## MCP Server
+| Template         | Pattern      | Description                                      |
+| ---------------- | ------------ | ------------------------------------------------ |
+| `feature-dev`    | hub-spoke    | Plan, implement, review, and finalize a feature  |
+| `bug-fix`        | hub-spoke    | Investigate, patch, validate, and document       |
+| `code-review`    | fan-out      | Parallel multi-reviewer assessment               |
+| `security-audit` | pipeline     | Scan, triage, remediate, and verify              |
+| `refactor`       | hierarchical | Analyze, plan, execute, and validate             |
+| `documentation`  | handoff      | Research, draft, review, and publish             |
+
+---
 
-Give AI agents native relay tools via [Model Context Protocol](https://modelcontextprotocol.io):
+## SDK Usage
 
 ```bash
-npx @agent-relay/mcp install
+npm install @agent-relay/sdk
 ```
 
-Supports Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, OpenCode, Gemini CLI, and Droid.
+### Agent-to-Agent Messaging
 
-Once configured, agents get access to: `relay_send`, `relay_inbox`, `relay_who`, `relay_spawn`, `relay_release`, and `relay_status`.
+```typescript
+import { AgentRelay, Models } from '@agent-relay/sdk';
 
-## Multi-Project Bridge
+const relay = new AgentRelay();
 
-Orchestrate agents across repositories:
+// Spawn agents with different CLIs and models
+const planner = await relay.claude.spawn({
+  name: 'Planner',
+  model: Models.Claude.OPUS
+});
 
-```bash
-# Start daemons in each project
-cd ~/auth && agent-relay up
-cd ~/frontend && agent-relay up
+const coder = await relay.codex.spawn({
+  name: 'Coder',
+  model: Models.Codex.CODEX_5_3
+});
 
-# Bridge from anywhere
-agent-relay bridge ~/auth ~/frontend ~/api
-```
+// Send messages between agents
+await planner.sendMessage({ to: 'Coder', text: 'Implement the auth module' });
 
-Cross-project messaging uses `project:agent` format:
-```bash
-cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
-TO: auth:Lead
+// Listen for messages
+relay.onMessageReceived = (msg) => {
+  console.log(`${msg.from} → ${msg.to}: ${msg.text}`);
+};
 
-Please review the token refresh logic
-EOF
+await relay.shutdown();
 ```
-Then output: `->relay-file:msg`
 
-## Cloud
+### Multi-Agent Workflows
 
-For team collaboration and cross-machine messaging, use [agent-relay cloud](https://agent-relay.com):
+Build workflows with different swarm patterns:
 
-```bash
-agent-relay cloud link      # Link your machine
-agent-relay cloud status    # Check cloud status
-agent-relay cloud agents    # List agents across machines
-agent-relay cloud send AgentName "Your message"
+```typescript
+import { workflow, Models, SwarmPatterns } from '@agent-relay/sdk/workflows';
+
+// Hub-spoke: Lead coordinates workers
+const result = await workflow('feature-build')
+  .pattern(SwarmPatterns.HUB_SPOKE)
+  .agent('lead', { cli: 'claude', model: Models.Claude.OPUS, role: 'Coordinator' })
+  .agent('dev1', { cli: 'codex', model: Models.Codex.CODEX_5_3, role: 'Developer' })
+  .agent('dev2', { cli: 'cursor', model: Models.Cursor.CLAUDE_SONNET, role: 'Developer' })
+  .step('plan', { agent: 'lead', task: 'Break down the feature into tasks' })
+  .step('impl1', { agent: 'dev1', task: 'Implement backend', dependsOn: ['plan'] })
+  .step('impl2', { agent: 'dev2', task: 'Implement frontend', dependsOn: ['plan'] })
+  .step('review', { agent: 'lead', task: 'Review and merge', dependsOn: ['impl1', 'impl2'] })
+  .run();
 ```
 
-Connect your CLI tool to your own private workspace and unlock agents working 24/7 against your GitHub repository in their own private sandbox.
+**Swarm Patterns:**
 
-## Teaching Agents
+| Category        | Patterns                                                    |
+| --------------- | ----------------------------------------------------------- |
+| **Core**        | `dag`, `fan-out`, `pipeline`, `hub-spoke`, `consensus`, `mesh` |
+| **Data**        | `map-reduce`, `scatter-gather`                              |
+| **Quality**     | `supervisor`, `reflection`, `verifier`                      |
+| **Adversarial** | `red-team`, `auction`                                       |
+| **Resilience**  | `escalation`, `saga`, `circuit-breaker`                     |
 
-> **Note:** On `agent-relay up` initialization this step happens automatically. If there is already an existing `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`, it will append the protocol instructions to that file.
+Auto-pattern selection: define agents with roles like `mapper`, `reducer`, `tier-1`, `attacker`, `defender` and the pattern is auto-selected.
 
-Install the messaging protocol snippet for your agents via [prpm](https://prpm.dev):
+---
 
-```bash
-npx prpm install @agent-relay/agent-relay-snippet
+## Cloud
 
-# for Claude
-npx prpm install @agent-relay/agent-relay-snippet --location CLAUDE.md
-```
+Scale to teams and automate with [Agent Relay Cloud](https://agent-relay.com):
 
-Prefer skills?
 ```bash
-npx prpm install @agent-relay/using-agent-relay
+agent-relay cloud link      # Link your machine
+agent-relay cloud agents    # List agents across machines
+agent-relay cloud send AgentName "Your message"
 ```
 
-View all packages on our [prpm organization page](https://prpm.dev/orgs?name=Agent%20Relay).
+### Multi-Agent Orchestration
 
----
+Spawn agent teams in the cloud — each agent runs in its own isolated sandbox but can communicate with teammates:
 
-## For Agents
+- **Isolated Sandboxes**: Each agent gets a secure container with full dev environment
+- **Cross-Sandbox Messaging**: Agents collaborate via relay channels despite isolation
+- **24/7 Durable Workflows**: Queue workflows to run continuously, survive restarts
+- **Auto-Scaling**: Workspaces scale up/down based on agent load
 
-Paste this into your LLM agent session:
 ```bash
-curl -s https://raw.githubusercontent.com/AgentWorkforce/relay/main/docs/guide/agent-setup.md
+# Queue a workflow to run in the cloud
+agent-relay run workflow.yaml --cloud --task "Refactor auth module"
+
+# Workflows persist, scale, and run even when you're offline
 ```
 
-Or read the full [Agent Setup Guide](./docs/guide/agent-setup.md).
+### Integrations
 
-## Using the Agent Relay SDK
+| Integration | Capabilities |
+| ----------- | ------------ |
+| **GitHub** | CI auto-fix, @mentions in PRs, issue assignment triggers |
+| **Linear** | Issue assignment spawns agents, status sync |
+| **Slack** | Chat with agents, trigger workflows from Slack commands |
 
-The easiest way to develop against relay:
+### CI Auto-Fix
 
-```bash
-# Install globally and start daemon
-npm install -g agent-relay
-agent-relay up
+Install the [Agent Relay GitHub App](https://github.com/apps/agent-relay):
 
-# In your project
-npm install agent-relay
+```
+1. CI fails on PR #123
+2. Agent Relay: "🔴 CI Failure Detected, spawning @ci-fix agent..."
+3. Agent analyzes logs, fixes issue, pushes commit
+4. Agent Relay: "✅ CI Fix Applied — please re-run checks"
 ```
 
-```typescript
-import { RelayClient } from 'agent-relay';
+---
 
-const client = new RelayClient({ name: 'MyApp' });
-await client.connect();
+## Architecture
 
-// Spawn a worker agent
-await client.spawn({ name: 'Worker', cli: 'claude', task: 'Wait for instructions' });
+Agent Relay is built from modular components that work together:
 
-// Send it a message
-await client.send('Worker', 'Hello from my app');
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Your Application                         │
+├─────────────────────────────────────────────────────────────────┤
+│  agent-relay CLI    │    @agent-relay/sdk    │    relay.yaml   │
+├─────────────────────────────────────────────────────────────────┤
+│                         Relay Broker                            │
+│  • Agent lifecycle  • Message routing  • PTY management        │
+├─────────────────────────────────────────────────────────────────┤
+│                         Relaycast                               │
+│  • REST API  • WebSocket events  • Channels & threads          │
+├─────────────────────────────────────────────────────────────────┤
+│  Claude  │  Codex  │  Gemini  │  Cursor  │  Aider  │  Goose   │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
----
+### Components
 
-## Philosophy
+| Component | Description |
+| --------- | ----------- |
+| **Relay Broker** | Core message router with sub-5ms latency. Manages agent lifecycle, PTY sessions, and message delivery. |
+| **Relaycast** | Communication layer with REST API and WebSocket. Provides channels, threads, reactions, and file attachments. Framework-agnostic — works with CrewAI, LangGraph, AutoGen, or raw API calls. |
+| **Relay Dashboard** | Real-time monitoring UI. View agent status, stream logs, and manage workflows from the browser. |
+| **Relay Cloud** | Multi-tenant cloud platform with auto-scaling, billing, and webhook integrations for GitHub/Linear/Slack. |
+| **Trajectories** | Decision capture system. Records the "why" behind code changes — decisions, challenges, and confidence scores — as searchable institutional memory. |
 
-> **Do one thing well:** Real-time agent messaging with sub-5ms latency.
+### How It Works
 
-agent-relay is a messaging layer, not a framework. It works with any CLI tool, any orchestration system, and any memory layer.
+1. **Zero modification**: Agents run unmodified CLI tools (Claude Code, Codex, etc.) in PTY sessions
+2. **MCP protocol**: Agents communicate via standard MCP tools — no custom SDK required inside agents
+3. **Mix AI providers**: Combine Claude, GPT, and Gemini agents in a single workflow — each using their strengths
+4. **Workflow engine**: YAML workflows parsed and executed with dependency resolution, retries, and verification
 
 ---