agent-relay 1.0.22 → 1.2.0

package/docs/agent-relay-snippet.md

@@ -16,7 +16,36 @@ Your message here.>>>
 Broadcast to all agents.>>>
 ```
 
-**CRITICAL:** Always end with `>>>` at the end of the last line of content!
+**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
+
+**ACK immediately** - When you receive a task, acknowledge it before starting work:
+
+```
+->relay:Sender <<<
+ACK: Brief description of task received>>>
+```
+
+**Report completion** - When done, send a completion message:
+
+```
+->relay:Sender <<<
+DONE: Brief summary of what was completed>>>
+```
 
 ## Receiving Messages
 
@@ -25,6 +54,25 @@ Messages appear as:
 Relay message from Alice [abc123]: Message content here
 ```
 
+### Channel Routing (Important!)
+
+Messages from #general (broadcast channel) include a `[#general]` indicator:
+```
+Relay message from Alice [abc123] [#general]: Hello everyone!
+```
+
+**When you see `[#general]`**: Reply to `*` (broadcast), NOT to the sender directly.
+
+```
+# Correct - responds to #general channel
+->relay:* <<<
+Response to the group message.>>>
+
+# Wrong - sends as DM to sender instead of to the channel
+->relay:Alice <<<
+Response to the group message.>>>
+```
+
 If truncated, read full message:
 ```bash
 agent-relay read abc123
@@ -35,23 +83,67 @@ 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
 ```
 
-## Common Patterns
+**Use fenced format for tasks longer than ~50 characters** to avoid truncation from terminal line wrapping.
+
+## Threads
+
+Use threads to group related messages together:
 
 ```
-->relay:* <<<
-STATUS: Starting work on auth module>>>
+->relay:AgentName [thread:topic-name] <<<
+Your message here.>>>
+```
+
+**When to use threads:**
+- Working on a specific issue (e.g., `[thread:agent-relay-299]`)
+- Back-and-forth discussions with another agent
+- Code review conversations
 
+## Status Updates
+
+**Send status updates to your lead, NOT broadcast:**
+
+```
+# Correct - status to lead only
+->relay:Lead <<<
+STATUS: Working on auth module>>>
+
+# Wrong - don't broadcast status to everyone
 ->relay:* <<<
+STATUS: Working on auth module>>>
+```
+
+## Common Patterns
+
+```
+->relay:Lead <<<
+ACK: Starting /api/register implementation>>>
+
+->relay:Lead <<<
+STATUS: Working on auth module>>>
+
+->relay:Lead <<<
 DONE: Auth module complete>>>
 
 ->relay:Developer <<<
 TASK: Implement /api/register>>>
 
-->relay:Reviewer <<<
+->relay:Reviewer [thread:code-review-auth] <<<
 REVIEW: Please check src/auth/*.ts>>>
 
 ->relay:Architect <<<
@@ -63,3 +155,20 @@ QUESTION: JWT or sessions?>>>
 - Pattern must be at line start (whitespace OK)
 - Escape with `\->relay:` to output literally
 - Check daemon status: `agent-relay status`
+
+## Writing Examples (For Documentation)
+
+When showing examples of relay syntax in documentation or explanations, **escape the markers** so they don't get interpreted as actual messages:
+
+```
+# Escape the opening marker
+\->relay:AgentName \<<<
+Example content here.\>>>
+```
+
+**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
+
+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*