agent-relay 2.0.4 → 2.0.6

package/packages/dashboard-server/dist/server.js

@@ -4051,6 +4051,7 @@ export async function startDashboard(portOrOptions, dataDirArg, teamDirArg, dbPa
                 shadowTriggers,
                 shadowSpeakOn,
                 userId: typeof userId === 'string' ? userId : undefined,
+                includeWorkflowConventions: true, // Cloud opts into ACK/DONE workflow conventions
             };
             const result = await spawner.spawn(request);
             if (result.success) {
@@ -4172,6 +4173,7 @@ Start by greeting the project leads and asking for status updates.`;
                 name: 'Architect',
                 cli,
                 task: architectPrompt,
+                includeWorkflowConventions: true, // Cloud opts into ACK/DONE workflow conventions
             });
             if (result.success) {
                 broadcastData().catch(() => { });

package/packages/dashboard-server/dist/user-bridge.d.ts

@@ -88,6 +88,11 @@ export declare class UserBridge {
         avatarUrl?: string;
         displayName?: string;
     }): Promise<void>;
+    /**
+     * Remove a specific WebSocket connection from a user's session.
+     * If this was the last connection, unregister the user entirely.
+     */
+    private removeWebSocket;
     /**
      * Unregister a user and disconnect their relay client.
      */
@@ -97,9 +102,8 @@ export declare class UserBridge {
      */
     isUserRegistered(username: string): boolean;
     /**
-     * Update the WebSocket for an existing user session.
-     * This is needed when a user reconnects or opens a new tab,
-     * so messages are forwarded to the active WebSocket.
+     * Add a new WebSocket connection for an existing user session.
+     * This is needed when a user opens a new tab.
      */
     updateWebSocket(username: string, newWebSocket: WebSocket): boolean;
     /**

package/packages/dashboard-server/dist/user-bridge.js

@@ -36,9 +36,11 @@ export class UserBridge {
      * Creates a relay client connection for the user.
      */
     async registerUser(username, webSocket, options) {
-        // If user already registered, unregister first
+        // If user already registered, just update the WebSocket (multi-tab support)
         if (this.users.has(username)) {
-            this.unregisterUser(username);
+            console.log(`[user-bridge] User ${username} already registered, updating WebSocket`);
+            this.updateWebSocket(username, webSocket);
+            return;
         }
         // Create relay client for this user
         const relayClient = await this.createRelayClient({
@@ -61,16 +63,16 @@ export class UserBridge {
         relayClient.onChannelMessage = (from, channel, body, envelope) => {
             this.handleIncomingChannelMessage(username, from, channel, body, envelope);
         };
-        // Create session
+        // Create session with WebSocket set for multi-tab support
         const session = {
             username,
             relayClient,
-            webSocket,
+            webSockets: new Set([webSocket]),
             channels: new Set(),
             avatarUrl: options?.avatarUrl,
         };
         this.users.set(username, session);
-        console.log(`[user-bridge] User registered: ${username} (total: ${this.users.size})`);
+        console.log(`[user-bridge] User registered: ${username} (total users: ${this.users.size}, connections: 1)`);
         // Auto-join user to #general channel
         // Note: The daemon auto-joins on connect, but we need to track locally too
         session.channels.add('#general');
@@ -90,12 +92,27 @@ export class UserBridge {
                 console.error(`[user-bridge] Failed to restore persisted channels for ${username}:`, err);
             }
         }
-        // Set up WebSocket close handler
+        // Set up WebSocket close handler to remove this specific connection
         webSocket.on('close', () => {
-            this.unregisterUser(username);
+            this.removeWebSocket(username, webSocket);
         });
         console.log(`[user-bridge] User ${username} registered with relay daemon`);
     }
+    /**
+     * Remove a specific WebSocket connection from a user's session.
+     * If this was the last connection, unregister the user entirely.
+     */
+    removeWebSocket(username, webSocket) {
+        const session = this.users.get(username);
+        if (!session)
+            return;
+        session.webSockets.delete(webSocket);
+        console.log(`[user-bridge] WebSocket closed for ${username} (${session.webSockets.size} connections remaining)`);
+        // Only unregister if ALL connections are closed
+        if (session.webSockets.size === 0) {
+            this.unregisterUser(username);
+        }
+    }
     /**
      * Unregister a user and disconnect their relay client.
      */
@@ -114,26 +131,22 @@ export class UserBridge {
         return this.users.has(username);
     }
     /**
-     * Update the WebSocket for an existing user session.
-     * This is needed when a user reconnects or opens a new tab,
-     * so messages are forwarded to the active WebSocket.
+     * Add a new WebSocket connection for an existing user session.
+     * This is needed when a user opens a new tab.
      */
     updateWebSocket(username, newWebSocket) {
         const session = this.users.get(username);
         if (!session) {
-            console.log(`[user-bridge] Cannot update WebSocket - user ${username} not registered`);
+            console.log(`[user-bridge] Cannot add WebSocket - user ${username} not registered`);
             return false;
         }
-        // Remove the close handler from old WebSocket to prevent auto-unregister
-        session.webSocket.removeAllListeners('close');
-        // Update to new WebSocket
-        session.webSocket = newWebSocket;
-        // Set up close handler on new WebSocket
+        // Add the new WebSocket to the set
+        session.webSockets.add(newWebSocket);
+        // Set up close handler to remove this specific connection
         newWebSocket.on('close', () => {
-            // Note: The server manages multi-tab connections and will call
-            // unregisterUser when all connections are closed
+            this.removeWebSocket(username, newWebSocket);
         });
-        console.log(`[user-bridge] Updated WebSocket for user ${username}`);
+        console.log(`[user-bridge] Added WebSocket for user ${username} (${session.webSockets.size} connections)`);
         return true;
     }
     /**
@@ -224,23 +237,25 @@ export class UserBridge {
         const session = this.users.get(username);
         if (!session)
             return;
-        const ws = session.webSocket;
-        if (ws.readyState !== 1)
-            return; // Not OPEN
         // Look up sender's avatar if lookup function is available
         const senderInfo = this.lookupUserInfo?.(from);
         const fromAvatarUrl = senderInfo?.avatarUrl;
         // Determine entity type: user if they have info, agent otherwise
         const fromEntityType = senderInfo ? 'user' : 'agent';
-        // Direct message (DELIVER)
-        ws.send(JSON.stringify({
+        const message = JSON.stringify({
             type: 'direct_message',
             from,
             fromAvatarUrl,
             fromEntityType,
             body: payloadObj?.body || body,
             timestamp: new Date().toISOString(),
-        }));
+        });
+        // Send to ALL open WebSocket connections (multi-tab support)
+        for (const ws of session.webSockets) {
+            if (ws.readyState === 1) { // OPEN
+                ws.send(message);
+            }
+        }
     }
     /**
      * Handle incoming channel message from relay daemon.
@@ -249,9 +264,6 @@ export class UserBridge {
         const session = this.users.get(username);
         if (!session)
             return;
-        const ws = session.webSocket;
-        if (ws.readyState !== 1)
-            return; // Not OPEN
         // Look up sender's avatar if lookup function is available
         const senderInfo = this.lookupUserInfo?.(from);
         const fromAvatarUrl = senderInfo?.avatarUrl;
@@ -259,7 +271,7 @@ export class UserBridge {
         const fromEntityType = senderInfo ? 'user' : 'agent';
         // Channel message
         const env = envelope;
-        ws.send(JSON.stringify({
+        const message = JSON.stringify({
             type: 'channel_message',
             channel,
             from,
@@ -269,7 +281,13 @@ export class UserBridge {
             thread: env?.payload?.thread,
             mentions: env?.payload?.mentions,
             timestamp: new Date().toISOString(),
-        }));
+        });
+        // Send to ALL open WebSocket connections (multi-tab support)
+        for (const ws of session.webSockets) {
+            if (ws.readyState === 1) { // OPEN
+                ws.send(message);
+            }
+        }
     }
     /**
      * Admin: Add a member to a channel (does not require member to be connected).

package/packages/dashboard-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/dashboard-server",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Relay dashboard server - HTTP/WebSocket server for agent coordination",
   "type": "module",
   "main": "dist/index.js",
@@ -22,17 +22,17 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.4",
-    "@agent-relay/config": "2.0.4",
-    "@agent-relay/storage": "2.0.4",
-    "@agent-relay/bridge": "2.0.4",
-    "@agent-relay/utils": "2.0.4",
-    "@agent-relay/resiliency": "2.0.4",
-    "@agent-relay/trajectory": "2.0.4",
-    "@agent-relay/cloud": "2.0.4",
-    "@agent-relay/daemon": "2.0.4",
-    "@agent-relay/user-directory": "2.0.4",
-    "@agent-relay/sdk": "2.0.4",
+    "@agent-relay/protocol": "2.0.6",
+    "@agent-relay/config": "2.0.6",
+    "@agent-relay/storage": "2.0.6",
+    "@agent-relay/bridge": "2.0.6",
+    "@agent-relay/utils": "2.0.6",
+    "@agent-relay/resiliency": "2.0.6",
+    "@agent-relay/trajectory": "2.0.6",
+    "@agent-relay/cloud": "2.0.6",
+    "@agent-relay/daemon": "2.0.6",
+    "@agent-relay/user-directory": "2.0.6",
+    "@agent-relay/sdk": "2.0.6",
     "array-flatten": "^1.1.1",
     "express": "^4.21.2",
     "ws": "^8.18.3"

package/packages/hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/hooks",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Hook emitter, registry, and trajectory hooks for Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -37,9 +37,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.4",
-    "@agent-relay/config": "2.0.4",
-    "@agent-relay/trajectory": "2.0.4"
+    "@agent-relay/protocol": "2.0.6",
+    "@agent-relay/config": "2.0.6",
+    "@agent-relay/trajectory": "2.0.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/mcp/README.md

@@ -160,166 +160,50 @@ The MCP server provides:
 
 In cloud environments (with `WORKSPACE_ID` set), MCP is pre-configured and uses workspace-specific sockets automatically.
 
-## Programmatic Usage (For Libraries & Integrations)
+## Programmatic Usage
 
-The MCP package provides a simple programmatic API that's perfect for building agent orchestration libraries like AgentSwarm.
-
-### Simple Tools API (Recommended)
+Use relay tools directly in your code (no MCP protocol needed):
 
 ```typescript
 import { createTools } from '@agent-relay/mcp';
 
-// Create tools for your orchestrator agent
-const tools = createTools('Conductor');
-
-// Send messages to agents
-await tools.send('Worker1', 'Run the test suite');
-await tools.send('#team', 'Starting task coordination');  // Channel
-await tools.send('*', 'System announcement');              // Broadcast
+const tools = createTools('MyAgent');
 
-// Spawn worker agents
-const result = await tools.spawn({
-  name: 'TestRunner',
-  cli: 'claude',           // 'claude' | 'codex' | 'gemini' | 'opencode'
-  task: 'Run all tests and report failures',
-  cwd: '/path/to/project', // Optional working directory
-});
+// Send messages
+await tools.send('OtherAgent', 'Hello!');
+await tools.send('#general', 'Channel message');
+await tools.send('*', 'Broadcast');
 
-if (!result.success) {
-  console.error('Spawn failed:', result.error);
-}
-
-// Check your inbox
+// Check inbox
 const messages = await tools.inbox();
 for (const msg of messages) {
-  console.log(`From ${msg.from}: ${msg.content}`);
-  if (msg.channel) console.log(`  (in ${msg.channel})`);
+  console.log(`${msg.from}: ${msg.content}`);
 }
 
 // List online agents
 const agents = await tools.who();
-console.log('Online agents:', agents.map(a => a.name));
-
-// Release workers when done
-await tools.release('TestRunner', 'Tests complete');
-
-// Get connection status
-const status = await tools.status();
-console.log(`Connected: ${status.connected}, Project: ${status.project}`);
-```
-
-### Full Integration Example
-
-```typescript
-import { createTools, type RelayTools, type Message, type Agent } from '@agent-relay/mcp';
-
-class AgentOrchestrator {
-  private tools: RelayTools;
-  private workers: Map<string, { task: string; status: string }> = new Map();
-
-  constructor(name: string) {
-    this.tools = createTools(name);
-  }
-
-  async spawnWorker(name: string, task: string) {
-    const result = await this.tools.spawn({
-      name,
-      cli: 'claude',
-      task,
-    });
-
-    if (result.success) {
-      this.workers.set(name, { task, status: 'running' });
-    }
-    return result;
-  }
-
-  async sendTask(workerName: string, task: string) {
-    await this.tools.send(workerName, task);
-  }
-
-  async waitForCompletion(workerName: string, timeoutMs = 60000) {
-    // Use sendAndWait for synchronous request-response
-    const response = await this.tools.sendAndWait(
-      workerName,
-      'Report your status',
-      { timeoutMs }
-    );
-    return response;
-  }
-
-  async getMessages(): Promise<Message[]> {
-    return this.tools.inbox();
-  }
-
-  async getOnlineAgents(): Promise<Agent[]> {
-    return this.tools.who();
-  }
-
-  async releaseWorker(name: string) {
-    await this.tools.release(name);
-    this.workers.delete(name);
-  }
-
-  async releaseAll() {
-    for (const name of this.workers.keys()) {
-      await this.releaseWorker(name);
-    }
-  }
-}
-
-// Usage
-const conductor = new AgentOrchestrator('Conductor');
 
-await conductor.spawnWorker('Planner', 'Create implementation plan');
-await conductor.spawnWorker('Coder', 'Implement the plan');
-await conductor.spawnWorker('Tester', 'Write and run tests');
-
-// Coordinate work...
-await conductor.sendTask('Planner', 'Start planning the feature');
-
-// Check for responses
-const messages = await conductor.getMessages();
+// Spawn workers
+await tools.spawn({
+  name: 'Worker1',
+  cli: 'claude',
+  task: 'Run tests',
+});
 
-// Clean up
-await conductor.releaseAll();
+// Release workers
+await tools.release('Worker1');
 ```
 
-### One-liners (For Quick Scripts)
+### One-liners
 
 ```typescript
-import { send, inbox, who } from '@agent-relay/mcp';
+import { send, inbox, who } from '@agent-relay/mcp/simple';
 
-// Send a message
 await send('MyAgent', 'Bob', 'Hello!');
-
-// Check inbox
 const messages = await inbox('MyAgent');
-
-// List agents
 const agents = await who();
 ```
 
-### Socket Discovery
-
-The MCP package auto-discovers the daemon socket:
-
-```typescript
-import { discoverSocket, getConnectionInfo } from '@agent-relay/mcp';
-
-// Get socket path and metadata
-const discovery = discoverSocket();
-if (discovery) {
-  console.log(`Socket: ${discovery.socketPath}`);
-  console.log(`Project: ${discovery.project}`);
-  console.log(`Source: ${discovery.source}`);  // 'env' | 'cloud' | 'cwd' | 'scan'
-  console.log(`Cloud: ${discovery.isCloud}`);
-}
-
-// Or get full connection info
-const info = getConnectionInfo();
-```
-
 ## Requirements
 
 - Node.js 18+

package/packages/mcp/dist/client.js

@@ -2,55 +2,95 @@
  * RelayClient - Client for connecting to the Agent Relay daemon
  */
 import { createConnection } from 'node:net';
-import { randomUUID } from 'node:crypto';
 import { discoverSocket } from './cloud.js';
 import { DaemonNotRunningError } from './errors.js';
+// Protocol version
+const PROTOCOL_VERSION = 1;
+/**
+ * Encode a message envelope into a length-prefixed frame (legacy format).
+ * Format: 4-byte big-endian length + JSON payload
+ */
+function encodeFrame(envelope) {
+    const json = JSON.stringify(envelope);
+    const data = Buffer.from(json, 'utf-8');
+    const header = Buffer.alloc(4);
+    header.writeUInt32BE(data.length, 0);
+    return Buffer.concat([header, data]);
+}
+/**
+ * Frame parser for length-prefixed messages.
+ */
+class FrameParser {
+    buffer = Buffer.alloc(0);
+    push(data) {
+        this.buffer = Buffer.concat([this.buffer, data]);
+        const frames = [];
+        while (this.buffer.length >= 4) {
+            const frameLength = this.buffer.readUInt32BE(0);
+            const totalLength = 4 + frameLength;
+            if (this.buffer.length < totalLength)
+                break;
+            const payload = this.buffer.subarray(4, totalLength);
+            this.buffer = this.buffer.subarray(totalLength);
+            try {
+                frames.push(JSON.parse(payload.toString('utf-8')));
+            }
+            catch {
+                // Skip malformed frames
+            }
+        }
+        return frames;
+    }
+}
 export function createRelayClient(options) {
     const { agentName, project = 'default', timeout = 5000 } = options;
     const discovery = discoverSocket({ socketPath: options.socketPath });
     const socketPath = discovery?.socketPath || options.socketPath || '/tmp/agent-relay.sock';
-    // Use randomUUID for collision-resistant request IDs
-    const generateId = () => `${agentName}-${randomUUID()}`;
+    // Generate unique IDs
+    let idCounter = 0;
+    const generateId = () => `mcp-${Date.now().toString(36)}-${(++idCounter).toString(36)}`;
     async function request(type, payload) {
         return new Promise((resolve, reject) => {
             const id = generateId();
-            const req = { type, id, payload };
+            // Build a proper protocol envelope
+            const envelope = {
+                v: PROTOCOL_VERSION,
+                type,
+                id,
+                ts: Date.now(),
+                payload,
+            };
             let timedOut = false;
-            let buffer = '';
+            const parser = new FrameParser();
             const socket = createConnection(socketPath);
             const timeoutId = setTimeout(() => {
                 timedOut = true;
                 socket.destroy();
                 reject(new Error(`Request timeout after ${timeout}ms`));
             }, timeout);
-            socket.on('connect', () => socket.write(JSON.stringify(req) + '\n'));
+            socket.on('connect', () => socket.write(encodeFrame(envelope)));
             socket.on('data', (data) => {
                 // Ignore data if we've already timed out
                 if (timedOut)
                     return;
-                buffer += data.toString();
-                const lines = buffer.split('\n');
-                buffer = lines.pop() || '';
-                for (const line of lines) {
-                    if (!line.trim())
-                        continue;
-                    try {
-                        const response = JSON.parse(line);
-                        if (response.id === id) {
-                            clearTimeout(timeoutId);
-                            socket.end();
-                            if (response.error)
-                                reject(new Error(response.error));
-                            else
-                                resolve(response.payload);
-                            return;
+                const frames = parser.push(data);
+                for (const response of frames) {
+                    // Check if this is a response to our request
+                    if (response.id === id || response.payload?.replyTo === id) {
+                        clearTimeout(timeoutId);
+                        socket.end();
+                        // Handle error responses
+                        if (response.type === 'ERROR') {
+                            const errorPayload = response.payload;
+                            reject(new Error(errorPayload?.message || errorPayload?.code || 'Unknown error'));
                         }
-                    }
-                    catch (parseError) {
-                        // Log parse errors in debug mode for easier troubleshooting
-                        if (process.env.DEBUG || process.env.RELAY_DEBUG) {
-                            console.error('[RelayClient] Failed to parse daemon response:', line, parseError);
+                        else if (response.payload?.error) {
+                            reject(new Error(response.payload.error));
+                        }
+                        else {
+                            resolve(response.payload);
                         }
+                        return;
                     }
                 }
             });

package/packages/mcp/dist/cloud.js

@@ -7,6 +7,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { findProjectRoot } from '@agent-relay/config';
 // ============================================================================
 // Cloud Workspace Detection
 // ============================================================================
@@ -61,24 +62,6 @@ export function getCloudSocketPath(workspaceId) {
 export function getCloudOutboxPath(workspaceId, agentName) {
     return `/tmp/relay/${workspaceId}/outbox/${agentName}`;
 }
-/**
- * Find project root by looking for common markers.
- * Scans up from startDir until it finds a marker or hits the filesystem root.
- */
-function findProjectRoot(startDir = process.cwd()) {
-    let current = startDir;
-    const root = current.split('/')[0] || '/';
-    const markers = ['.git', 'package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', '.agent-relay'];
-    while (current !== root && current !== '/') {
-        for (const marker of markers) {
-            if (existsSync(join(current, marker))) {
-                return current;
-            }
-        }
-        current = join(current, '..');
-    }
-    return null;
-}
 /**
  * Get platform-specific data directory.
  */

package/packages/mcp/dist/prompts/protocol.d.ts

@@ -6,6 +6,6 @@
  */
 import type { Prompt } from '@modelcontextprotocol/sdk/types.js';
 export declare const protocolPrompt: Prompt;
-export declare const PROTOCOL_DOCUMENTATION = "\n# Agent Relay Protocol\n\nYou are connected to Agent Relay, a real-time messaging system for AI agent coordination.\n\n## Communication Patterns\n\n### Direct Messages\nSend a message to a specific agent by name:\n```\nrelay_send(to=\"Alice\", message=\"Can you review this PR?\")\n```\n\n### Channel Messages\nSend to a channel (prefix with #):\n```\nrelay_send(to=\"#engineering\", message=\"Build complete\")\n```\nChannel messages are visible to all agents subscribed to that channel.\n\n### Broadcast\nSend to all online agents:\n```\nrelay_send(to=\"*\", message=\"System maintenance in 5 minutes\")\n```\nUse sparingly - broadcasts interrupt all agents.\n\n### Threaded Conversations\nFor multi-turn conversations, use thread IDs:\n```\nrelay_send(to=\"Bob\", message=\"Starting task\", thread=\"task-123\")\nrelay_send(to=\"Bob\", message=\"Task update\", thread=\"task-123\")\n```\n\n### Await Response\nBlock and wait for a reply:\n```\nrelay_send(to=\"Worker\", message=\"Process this file\", await_response=true, timeout_ms=60000)\n```\n\n## Spawning Workers\n\nCreate worker agents to parallelize work:\n\n```\nrelay_spawn(\n  name=\"TestRunner\",\n  cli=\"claude\",\n  task=\"Run the test suite in src/tests/ and report any failures\"\n)\n```\n\nWorkers:\n- Run in separate processes\n- Have their own CLI instance\n- Can use relay to communicate back\n- Should be released when done\n\n### Worker Lifecycle\n1. Spawn worker with task\n2. Worker sends ACK when ready\n3. Worker sends progress updates\n4. Worker sends DONE when complete\n5. Lead releases worker\n\n### Release Workers\n```\nrelay_release(name=\"TestRunner\", reason=\"Tests completed\")\n```\n\n## Message Protocol\n\nWhen you receive messages, they follow this format:\n```\nRelay message from Alice [msg-id-123]: Content here\n```\n\nChannel messages include the channel:\n```\nRelay message from Alice [msg-id-456] [#general]: Hello team!\n```\n\n### ACK/DONE Protocol\nWhen assigned a task:\n1. Send ACK immediately: \"ACK: Starting work on X\"\n2. Send progress updates as needed\n3. Send DONE when complete: \"DONE: Completed X with result Y\"\n\nExample:\n```\n# When receiving a task\nrelay_send(to=\"Lead\", message=\"ACK: Starting test suite run\")\n\n# ... do work ...\n\nrelay_send(to=\"Lead\", message=\"DONE: All 42 tests passed\")\n```\n\n## Best Practices\n\n### For Lead Agents\n- Spawn workers for parallelizable tasks\n- Keep track of spawned workers\n- Release workers when done\n- Use channels for team announcements\n\n### For Worker Agents\n- ACK immediately when receiving tasks\n- Send progress updates for long tasks\n- Send DONE with results when complete\n- Ask clarifying questions if needed\n\n### Message Etiquette\n- Keep messages concise\n- Include relevant context\n- Use threads for related messages\n- Don't spam broadcasts\n\n## Checking Messages\n\nProactively check your inbox:\n```\nrelay_inbox()\nrelay_inbox(from=\"Lead\")\nrelay_inbox(channel=\"#urgent\")\n```\n\n## Seeing Who's Online\n\n```\nrelay_who()\n```\n\n## Error Handling\n\nIf relay returns an error:\n- \"Daemon not running\" - The relay daemon needs to be started\n- \"Agent not found\" - Target agent is offline\n- \"Channel not found\" - Channel doesn't exist\n- \"Timeout\" - No response within timeout period\n\n## Multi-Project Communication\n\nIn multi-project setups, specify project:\n```\nrelay_send(to=\"frontend:Designer\", message=\"Need UI mockup\")\n```\n\nSpecial targets:\n- `project:lead` - Lead agent of that project\n- `project:*` - Broadcast to project\n- `*:*` - Broadcast to all projects\n";
+export declare const PROTOCOL_DOCUMENTATION = "\n# Agent Relay Protocol\n\nYou are connected to Agent Relay, a real-time messaging system for AI agent coordination.\n\n## Communication Patterns\n\n### Direct Messages\nSend a message to a specific agent by name:\n```\nrelay_send(to=\"Alice\", message=\"Can you review this PR?\")\n```\n\n### Channel Messages\nSend to a channel (prefix with #):\n```\nrelay_send(to=\"#engineering\", message=\"Build complete\")\n```\nChannel messages are visible to all agents subscribed to that channel.\n\n### Broadcast\nSend to all online agents:\n```\nrelay_send(to=\"*\", message=\"System maintenance in 5 minutes\")\n```\nUse sparingly - broadcasts interrupt all agents.\n\n### Threaded Conversations\nFor multi-turn conversations, use thread IDs:\n```\nrelay_send(to=\"Bob\", message=\"Starting task\", thread=\"task-123\")\nrelay_send(to=\"Bob\", message=\"Task update\", thread=\"task-123\")\n```\n\n### Await Response\nBlock and wait for a reply:\n```\nrelay_send(to=\"Worker\", message=\"Process this file\", await_response=true, timeout_ms=60000)\n```\n\n## Spawning Workers\n\nCreate worker agents to parallelize work:\n\n```\nrelay_spawn(\n  name=\"TestRunner\",\n  cli=\"claude\",\n  task=\"Run the test suite in src/tests/ and report any failures\"\n)\n```\n\nWorkers:\n- Run in separate processes\n- Have their own CLI instance\n- Can use relay to communicate back\n- Should be released when done\n\n### Worker Lifecycle\n1. Spawn worker with task\n2. Worker sends ACK when ready\n3. Worker sends progress updates\n4. Worker sends DONE when complete\n5. Lead releases worker\n\n### Release Workers\n```\nrelay_release(name=\"TestRunner\", reason=\"Tests completed\")\n```\n\n## Message Protocol\n\nWhen you receive messages, they follow this format:\n```\nRelay message from Alice [msg-id-123]: Content here\n```\n\nChannel messages include the channel:\n```\nRelay message from Alice [msg-id-456] [#general]: Hello team!\n```\n\n### Optional: ACK/DONE Convention\nSome applications use ACK/DONE conventions for task tracking. If your application uses this pattern:\n1. Send ACK when starting: \"ACK: Starting work on X\"\n2. Send progress updates as needed\n3. Send DONE when complete: \"DONE: Completed X with result Y\"\n\nNote: This is an application-level convention, not a protocol requirement. Check your application's documentation for expected message formats.\n\n## Best Practices\n\n### For Lead Agents\n- Spawn workers for parallelizable tasks\n- Keep track of spawned workers\n- Release workers when done\n- Use channels for team announcements\n\n### For Worker Agents\n- Respond promptly when receiving tasks\n- Send progress updates for long tasks\n- Report results when complete\n- Ask clarifying questions if needed\n\n### Message Etiquette\n- Keep messages concise\n- Include relevant context\n- Use threads for related messages\n- Don't spam broadcasts\n\n## Checking Messages\n\nProactively check your inbox:\n```\nrelay_inbox()\nrelay_inbox(from=\"Lead\")\nrelay_inbox(channel=\"#urgent\")\n```\n\n## Seeing Who's Online\n\n```\nrelay_who()\n```\n\n## Error Handling\n\nIf relay returns an error:\n- \"Daemon not running\" - The relay daemon needs to be started\n- \"Agent not found\" - Target agent is offline\n- \"Channel not found\" - Channel doesn't exist\n- \"Timeout\" - No response within timeout period\n\n## Multi-Project Communication\n\nIn multi-project setups, specify project:\n```\nrelay_send(to=\"frontend:Designer\", message=\"Need UI mockup\")\n```\n\nSpecial targets:\n- `project:lead` - Lead agent of that project\n- `project:*` - Broadcast to project\n- `*:*` - Broadcast to all projects\n";
 export declare function getProtocolPrompt(): string;
 //# sourceMappingURL=protocol.d.ts.map