agent-relay 1.1.0 → 1.2.0

package/docs/agent-relay-snippet.md

@@ -16,7 +16,20 @@ Your message here.>>>
 Broadcast to all agents.>>>
 ```
 
-**CRITICAL:** Always close multi-line messages with `>>>` on its own line!
+**CRITICAL:** Always close multi-line messages with `>>>` after the very last character.
+
+**WARNING:** Do NOT put blank lines before `>>>` - it must immediately follow your content:
+
+```
+# CORRECT - >>> immediately after content
+->relay:Agent <<<Your message here.>>>
+
+# WRONG - blank line before >>> breaks parsing
+->relay:Agent <<<
+Your message here.
+
+>>>
+```
 
 ## Communication Protocol
 
@@ -27,8 +40,6 @@ Broadcast to all agents.>>>
 ACK: Brief description of task received>>>
 ```
 
-Then proceed with your work. This confirms message delivery and lets the sender know you're on it.
-
 **Report completion** - When done, send a completion message:
 
 ```
@@ -62,8 +73,6 @@ Response to the group message.>>>
 Response to the group message.>>>
 ```
 
-This ensures your response appears in the same channel as the original message.
-
 If truncated, read full message:
 ```bash
 agent-relay read abc123
@@ -74,13 +83,26 @@ agent-relay read abc123
 Spawn workers to delegate tasks:
 
 ```
-->relay:spawn WorkerName claude "task description"
+# Short tasks - single line with quotes
+->relay:spawn WorkerName claude "short task description"
+
+# Long tasks - use fenced format (recommended)
+->relay:spawn WorkerName claude <<<
+Implement the authentication module.
+Requirements:
+- JWT tokens with refresh
+- Password hashing with bcrypt
+- Rate limiting on login endpoint>>>
+
+# Release when done
 ->relay:release WorkerName
 ```
 
+**Use fenced format for tasks longer than ~50 characters** to avoid truncation from terminal line wrapping.
+
 ## Threads
 
-Use threads to group related messages together. Thread syntax:
+Use threads to group related messages together:
 
 ```
 ->relay:AgentName [thread:topic-name] <<<
@@ -91,25 +113,20 @@ Your message here.>>>
 - Working on a specific issue (e.g., `[thread:agent-relay-299]`)
 - Back-and-forth discussions with another agent
 - Code review conversations
-- Any multi-message topic you want grouped
-
-**Examples:**
-
-```
-->relay:Protocol [thread:auth-feature] <<<
-How should we handle token refresh?>>>
 
-->relay:Frontend [thread:auth-feature] <<<
-Use a 401 interceptor that auto-refreshes.>>>
+## Status Updates
 
-->relay:Reviewer [thread:pr-123] <<<
-Please review src/auth/*.ts>>>
+**Send status updates to your lead, NOT broadcast:**
 
-->relay:Developer [thread:pr-123] <<<
-LGTM, approved!>>>
 ```
+# Correct - status to lead only
+->relay:Lead <<<
+STATUS: Working on auth module>>>
 
-Thread messages appear grouped in the dashboard with reply counts.
+# Wrong - don't broadcast status to everyone
+->relay:* <<<
+STATUS: Working on auth module>>>
+```
 
 ## Common Patterns
 
@@ -117,7 +134,7 @@ Thread messages appear grouped in the dashboard with reply counts.
 ->relay:Lead <<<
 ACK: Starting /api/register implementation>>>
 
-->relay:* <<<
+->relay:Lead <<<
 STATUS: Working on auth module>>>
 
 ->relay:Lead <<<
@@ -133,36 +150,25 @@ REVIEW: Please check src/auth/*.ts>>>
 QUESTION: JWT or sessions?>>>
 ```
 
-## Cross-Project Messaging
-
-When running in bridge mode (multiple projects connected), use `project:agent` format:
-
-```
-->relay:frontend:Designer <<<
-Please update the login UI for the new auth flow>>>
-
-->relay:backend:lead <<<
-API question - should we use REST or GraphQL?>>>
+## Rules
 
-->relay:shared-lib:* <<<
-New utility functions available, please pull latest>>>
-```
+- Pattern must be at line start (whitespace OK)
+- Escape with `\->relay:` to output literally
+- Check daemon status: `agent-relay status`
 
-**Format:** `->relay:project-id:agent-name`
+## Writing Examples (For Documentation)
 
-**Special targets:**
-- `->relay:project:lead` - Message the lead agent of that project
-- `->relay:project:*` - Broadcast to all agents in that project
-- `->relay:*:*` - Broadcast to ALL agents in ALL projects
+When showing examples of relay syntax in documentation or explanations, **escape the markers** so they don't get interpreted as actual messages:
 
-**Cross-project threads:**
 ```
-->relay:frontend:Designer [thread:auth-feature] <<<
-UI mockups ready for review>>>
+# Escape the opening marker
+\->relay:AgentName \<<<
+Example content here.\>>>
 ```
 
-## Rules
+**What to escape:**
+- `\->relay:` - Prevents the pattern from being detected as a real message
+- `\<<<` - Prevents the fenced block from being parsed
+- `\>>>` - Prevents the block from being closed
 
-- Pattern must be at line start (whitespace OK)
-- Escape with `\->relay:` to output literally
-- Check daemon status: `agent-relay status`
+This ensures your examples are displayed literally rather than sent as messages.

package/docs/archive/EXECUTIVE_SUMMARY.md

@@ -0,0 +1,358 @@
+# Agent Relay: Executive Summary
+
+> Real-time autonomous agent-to-agent communication without modifying the agents themselves.
+
+---
+
+## What Is Agent Relay?
+
+Agent Relay enables AI coding assistants (Claude, Codex, Gemini) running in separate terminals to **discover each other and communicate autonomously** - without any code changes to the AI systems.
+
+**Key differentiator:** agent-relay is a **composable messaging layer**, not a monolithic solution. It does one thing exceptionally well (<5ms real-time messaging) and integrates with best-of-breed tools for memory, UI, and workflows.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                                                                         │
+│    Terminal 1              Terminal 2              Terminal 3           │
+│   ┌─────────┐             ┌─────────┐             ┌─────────┐          │
+│   │  Alice  │────────────▶│   Bob   │◀────────────│  Carol  │          │
+│   │ (Claude)│◀────────────│ (Codex) │────────────▶│(Gemini) │          │
+│   └─────────┘             └─────────┘             └─────────┘          │
+│        │                       │                       │                │
+│        └───────────────────────┼───────────────────────┘                │
+│                                │                                        │
+│                    ┌───────────▼───────────┐                           │
+│                    │    Relay Daemon       │                           │
+│                    │  (Message Routing)    │                           │
+│                    └───────────────────────┘                           │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## The Core Insight
+
+**Agents already produce text.** By watching for a simple pattern in their output, we can extract communication intent:
+
+```
+Agent Output:  "I'll ask Bob for help. ->relay:Bob Can you review auth.ts?"
+                                        ▲
+                                        │
+                            Relay captures this, routes to Bob
+```
+
+No API integration. No agent modification. Just pattern matching on stdout.
+
+---
+
+## How It Works (30-Second Version)
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                                                                          │
+│  1. WRAP                    2. CAPTURE                 3. ROUTE          │
+│  ════════                   ═════════                  ═══════           │
+│                                                                          │
+│  agent-relay               Background                  Daemon            │
+│  -n Alice claude    ───▶   polling     ───▶   finds   routes    ───▶    │
+│                            captures          ->relay:   message          │
+│  Agent runs in             output            Bob...    to Bob           │
+│  tmux session                                                            │
+│                                                                          │
+│                                                                          │
+│  4. DELIVER                 5. INJECT                  6. RESPOND        │
+│  ═════════                  ════════                   ═════════         │
+│                                                                          │
+│  Bob's wrapper             Types into                  Bob's agent       │
+│  receives       ───▶       Bob's        ───▶          processes  ───▶   │
+│  message                   terminal                    as input          │
+│                                                                          │
+│                            "Relay message              Can reply with    │
+│                             from Alice:                ->relay:Alice      │
+│                             Can you..."                                  │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+```bash
+# Terminal 1: Start the daemon
+agent-relay up
+
+# Terminal 2: Start first agent
+agent-relay -n Alice claude
+
+# Terminal 3: Start second agent
+agent-relay -n Bob claude
+```
+
+Alice can now send: `->relay:Bob Can you help with the auth module?`
+
+Bob receives: `Relay message from Alice [abc123]: Can you help with the auth module?`
+
+---
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          AGENT RELAY SYSTEM                             │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                    CLI Layer (Entry Point)                       │   │
+│  │                                                                  │   │
+│  │   agent-relay up      Start daemon + dashboard                   │   │
+│  │   agent-relay down    Stop daemon                                │   │
+│  │   agent-relay -n X    Wrap agent with name X                     │   │
+│  │   agent-relay status  Check daemon status                        │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                    │                                    │
+│                                    ▼                                    │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                    Wrapper Layer (Per Agent)                     │   │
+│  │                                                                  │   │
+│  │   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │   │
+│  │   │TmuxWrapper  │  │OutputParser │  │RelayClient  │            │   │
+│  │   │             │  │             │  │             │            │   │
+│  │   │• Runs agent │  │• ->relay:    │  │• Socket I/O │            │   │
+│  │   │  in tmux    │  │  patterns   │  │• Reconnect  │            │   │
+│  │   │• Captures   │  │• ANSI strip │  │• Handshake  │            │   │
+│  │   │  output     │  │• Dedup      │  │             │            │   │
+│  │   │• Injects    │  │             │  │             │            │   │
+│  │   │  messages   │  │             │  │             │            │   │
+│  │   └─────────────┘  └─────────────┘  └─────────────┘            │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                    │                                    │
+│                          Unix Domain Socket                             │
+│                                    │                                    │
+│                                    ▼                                    │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                    Daemon Layer (Central)                        │   │
+│  │                                                                  │   │
+│  │   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │   │
+│  │   │Server       │  │Connection   │  │Router       │            │   │
+│  │   │             │  │             │  │             │            │   │
+│  │   │• Lifecycle  │  │• State M/C  │  │• Agent map  │            │   │
+│  │   │• Socket     │  │• Handshake  │  │• Routing    │            │   │
+│  │   │• PID file   │  │• Heartbeat  │  │• Broadcast  │            │   │
+│  │   └─────────────┘  └─────────────┘  └─────────────┘            │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                    │                                    │
+│                                    ▼                                    │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                    Storage Layer (SQLite)                        │   │
+│  │                                                                  │   │
+│  │   • Message persistence        • Query by sender/recipient       │   │
+│  │   • WAL mode for concurrency   • Full message history            │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Message Flow Diagram
+
+```
+  Alice (Claude)                    Daemon                      Bob (Codex)
+       │                              │                              │
+       │  Agent outputs:              │                              │
+       │  "->relay:Bob review auth"    │                              │
+       │                              │                              │
+       ├──────────────────────────────┤                              │
+       │     TmuxWrapper captures     │                              │
+       │     OutputParser extracts    │                              │
+       │     RelayClient sends SEND   │                              │
+       ├─────────────────────────────▶│                              │
+       │                              │                              │
+       │                              │  Router looks up "Bob"       │
+       │                              │  Creates DELIVER envelope    │
+       │                              │  Persists to SQLite          │
+       │                              │                              │
+       │                              ├─────────────────────────────▶│
+       │                              │                              │
+       │                              │     RelayClient receives     │
+       │                              │     TmuxWrapper waits idle   │
+       │                              │     Injects via send-keys    │
+       │                              │                              │
+       │                              │              ┌───────────────┤
+       │                              │              │ Bob sees:     │
+       │                              │              │ "Relay msg    │
+       │                              │              │  from Alice:  │
+       │                              │              │  review auth" │
+       │                              │              └───────────────┤
+       │                              │                              │
+       │                              │     Bob can respond:         │
+       │                              │     "->relay:Alice Done!"     │
+       │                              │                              │
+       │                              │◀─────────────────────────────┤
+       │◀─────────────────────────────┤                              │
+       │                              │                              │
+```
+
+---
+
+## Protocol Overview
+
+### Wire Format
+
+```
+┌────────────────┬──────────────────────────────────────────────────────┐
+│  Length (4B)   │              JSON Payload (UTF-8)                    │
+│  Big-endian    │              Up to 1 MiB                             │
+└────────────────┴──────────────────────────────────────────────────────┘
+```
+
+### Message Types
+
+| Type | Direction | Purpose |
+|------|-----------|---------|
+| `HELLO` | Client → Daemon | Identify agent |
+| `WELCOME` | Daemon → Client | Confirm session |
+| `SEND` | Client → Daemon | Send message |
+| `DELIVER` | Daemon → Client | Receive message |
+| `PING/PONG` | Both | Heartbeat |
+| `BYE` | Both | Disconnect |
+
+### Envelope Structure
+
+```json
+{
+  "v": 1,
+  "type": "SEND",
+  "id": "uuid-here",
+  "ts": 1703001234567,
+  "to": "Bob",
+  "payload": {
+    "kind": "message",
+    "body": "Can you review auth.ts?"
+  }
+}
+```
+
+---
+
+## State Machines
+
+### Connection States (Daemon-side)
+
+```
+ CONNECTING ──▶ HANDSHAKING ──▶ ACTIVE ──▶ CLOSING ──▶ CLOSED
+                     │             │
+                     └─── ERROR ───┘
+```
+
+### Client States (Wrapper-side)
+
+```
+ DISCONNECTED ──▶ CONNECTING ──▶ HANDSHAKING ──▶ READY
+       ▲                                           │
+       │                                           │
+       └──────────── BACKOFF ◀─────────────────────┘
+                   (auto-reconnect)
+```
+
+---
+
+## Communication Patterns
+
+### Direct Message
+```
+->relay:Bob Please review the authentication module
+```
+
+### Broadcast
+```
+->relay:* I've completed the database migration - all tests passing
+```
+
+### Structured (Block Format)
+```
+[[RELAY]]{"to":"Bob","type":"action","body":"Run integration tests","data":{"priority":"high"}}[[/RELAY]]
+```
+
+### Common Conventions
+```
+->relay:* STATUS: Starting work on auth module
+->relay:* DONE: Auth module complete
+->relay:Reviewer REVIEW: Please check src/auth/*.ts
+->relay:Architect QUESTION: Should we use JWT or sessions?
+```
+
+---
+
+## Key Design Decisions
+
+| Decision | Why |
+|----------|-----|
+| **Output parsing** | Works with any CLI agent, no modifications needed |
+| **Tmux wrapper** | Mature terminal emulation, users can detach/reattach |
+| **Unix sockets** | No network exposure, filesystem permissions for security |
+| **Message injection** | Agents treat messages as natural user input |
+| **SQLite storage** | Zero config, single file, good enough for local use |
+
+---
+
+## Limitations (Transparency)
+
+| Area | Limitation |
+|------|------------|
+| **Security** | No authentication between agents (local trust assumed) |
+| **Reliability** | Messages can be lost if agent is busy outputting |
+| **Timing** | 200ms polling latency, 1.5s idle wait before injection |
+| **Platform** | Windows requires WSL (tmux dependency) |
+| **Scale** | ~50 concurrent agents, ~100 msg/sec |
+
+---
+
+## File Structure
+
+```
+agent-relay/
+├── src/
+│   ├── cli/index.ts           # CLI entry point
+│   ├── daemon/
+│   │   ├── server.ts          # Daemon server
+│   │   ├── connection.ts      # Connection state machine
+│   │   └── router.ts          # Message routing
+│   ├── wrapper/
+│   │   ├── tmux-wrapper.ts    # Tmux session management
+│   │   ├── client.ts          # Daemon client
+│   │   └── parser.ts          # ->relay: pattern matching
+│   ├── protocol/
+│   │   ├── types.ts           # Message types
+│   │   └── framing.ts         # Wire format
+│   └── storage/
+│       └── sqlite-adapter.ts  # Message persistence
+├── ARCHITECTURE.md            # Detailed technical docs
+└── EXECUTIVE_SUMMARY.md       # This document
+```
+
+---
+
+## Storage Locations
+
+```
+/tmp/agent-relay/{project-hash}/
+├── relay.sock              # Unix domain socket
+├── relay.sock.pid          # Daemon PID
+├── messages.sqlite         # Message history
+└── agents.json             # Connected agents
+```
+
+---
+
+## See Also
+
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Complete technical deep-dive
+- **[README.md](./README.md)** - Quick start guide
+- **[docs/COMPETITIVE_ANALYSIS.md](./docs/COMPETITIVE_ANALYSIS.md)** - Comparison with 16 multi-agent tools
+
+---
+
+*Agent Relay v1.0.7*