agent-relay 2.0.4 → 2.0.6

package/packages/mcp/dist/prompts/protocol.js

@@ -91,21 +91,13 @@ Channel messages include the channel:
 Relay message from Alice [msg-id-456] [#general]: Hello team!
 \`\`\`
 
-### ACK/DONE Protocol
-When assigned a task:
-1. Send ACK immediately: "ACK: Starting work on X"
+### Optional: ACK/DONE Convention
+Some applications use ACK/DONE conventions for task tracking. If your application uses this pattern:
+1. Send ACK when starting: "ACK: Starting work on X"
 2. Send progress updates as needed
 3. Send DONE when complete: "DONE: Completed X with result Y"
 
-Example:
-\`\`\`
-# When receiving a task
-relay_send(to="Lead", message="ACK: Starting test suite run")
-
-# ... do work ...
-
-relay_send(to="Lead", message="DONE: All 42 tests passed")
-\`\`\`
+Note: This is an application-level convention, not a protocol requirement. Check your application's documentation for expected message formats.
 
 ## Best Practices
 
@@ -116,9 +108,9 @@ relay_send(to="Lead", message="DONE: All 42 tests passed")
 - Use channels for team announcements
 
 ### For Worker Agents
-- ACK immediately when receiving tasks
+- Respond promptly when receiving tasks
 - Send progress updates for long tasks
-- Send DONE with results when complete
+- Report results when complete
 - Ask clarifying questions if needed
 
 ### Message Etiquette

package/packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/mcp",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "MCP server for Agent Relay - native messaging tools for AI agents in Claude, Cursor, and VS Code",
   "author": "Agent Workforce Inc.",
   "license": "Apache-2.0",
@@ -47,6 +47,7 @@
     "prepublishOnly": "npm run clean && npm run build && npm test"
   },
   "dependencies": {
+    "@agent-relay/config": "2.0.6",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.8"
   },

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/memory",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Semantic memory storage and retrieval system for agent-relay with multiple backend support",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/hooks": "2.0.4"
+    "@agent-relay/hooks": "2.0.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/policy",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Agent policy management with multi-level fallback (repo, local PRPM, cloud workspace)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "2.0.4"
+    "@agent-relay/config": "2.0.6"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/protocol/dist/types.d.ts

@@ -278,6 +278,8 @@ export interface SpawnPayload {
     shadowSpeakOn?: SpeakOnTrigger[];
     /** User ID for cloud persistence */
     userId?: string;
+    /** Include ACK/DONE workflow conventions in agent instructions (default: false) */
+    includeWorkflowConventions?: boolean;
 }
 export interface SpawnPolicyDecision {
     allowed: boolean;

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/protocol",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Wire protocol types and framing for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/resiliency/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/resiliency",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Health monitoring, logging, metrics, and crash resilience utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/sdk/README.md

@@ -1,17 +1,15 @@
 # @agent-relay/sdk
 
-Dead simple agent-to-agent communication for AI agent systems.
+Dead simple agent-to-agent communication.
 
 ## Install
 
 ```bash
-npm install @agent-relay/sdk
+npm install @agent-relay/sdk @agent-relay/daemon
 ```
 
 ## Quick Start
 
-### Standalone (In-Process Daemon)
-
 ```typescript
 import { createRelay } from '@agent-relay/sdk';
 
@@ -34,7 +32,9 @@ alice.sendMessage('Bob', 'Hello!');
 await relay.stop();
 ```
 
-### Two-Agent Shortcut
+That's it. No daemon to start, no config files, no setup.
+
+## Even Simpler: Two Agents
 
 ```typescript
 import { createPair } from '@agent-relay/sdk';
@@ -47,163 +47,56 @@ alice.sendMessage('bob', 'Hey!');
 await stop();
 ```
 
-### With External Daemon
-
-If you're running `agent-relay up` separately:
-
-```typescript
-import { RelayClient } from '@agent-relay/sdk';
-
-// Socket path is auto-discovered from your project's .agent-relay/relay.sock
-const client = new RelayClient({ agentName: 'MyAgent' });
-
-await client.connect();
-client.sendMessage('OtherAgent', 'Hello!');
-```
-
-## Socket Discovery
-
-The SDK automatically discovers the daemon socket in this order:
-
-1. `RELAY_SOCKET` environment variable
-2. Cloud workspace socket (if `WORKSPACE_ID` is set)
-3. **Project-local socket** (`{projectRoot}/.agent-relay/relay.sock`)
-4. Legacy fallback (`/tmp/agent-relay.sock`)
-
-You can also use the discovery API directly:
-
-```typescript
-import { discoverSocket, getDefaultSocketPath } from '@agent-relay/sdk';
-
-// Get detailed discovery info
-const { socketPath, projectId, source } = discoverSocket();
-console.log(`Using socket: ${socketPath} (source: ${source})`);
-
-// Or just get the path
-const socketPath = getDefaultSocketPath();
-```
-
-## Integration Guide (for Libraries like AgentSwarm)
-
-If you're building a library that integrates with Agent Relay:
-
-### Option 1: Use the SDK Client (Recommended)
-
-```typescript
-import { RelayClient, discoverSocket } from '@agent-relay/sdk';
-
-class MyAgentOrchestrator {
-  private client: RelayClient;
-
-  async connect(agentName: string) {
-    // Auto-discovers socket path
-    this.client = new RelayClient({
-      agentName,
-      reconnect: true, // Auto-reconnect on disconnect
-    });
-
-    await this.client.connect();
-  }
-
-  async sendTask(to: string, task: string) {
-    return this.client.sendMessage(to, task);
-  }
+## Features
 
-  async waitForResponse(to: string, message: string, timeoutMs = 30000) {
-    return this.client.sendAndWait(to, message, { timeoutMs });
-  }
+| Feature | Description |
+|---------|-------------|
+| **Zero config** | Just import and go |
+| **Auto-reconnect** | Handles disconnections automatically |
+| **Message deduplication** | No duplicate deliveries |
+| **Sync messaging** | Wait for acknowledgment |
+| **Broadcast** | Send to all agents with `*` |
+| **Channels** | Group messaging with `#channel` |
 
-  onMessage(handler: (from: string, body: string) => void) {
-    this.client.onMessage = (from, payload) => {
-      handler(from, payload.body);
-    };
-  }
-}
-```
+## API Reference
 
-### Option 2: Use MCP Simple API (If Using MCP)
+### createRelay(config?)
 
-If your agents use MCP, the `@agent-relay/mcp` package has an even simpler API:
+Creates a standalone relay with an in-process daemon.
 
 ```typescript
-import { createTools } from '@agent-relay/mcp';
-
-const tools = createTools('Orchestrator');
-
-// Send messages
-await tools.send('Worker1', 'Run the test suite');
-
-// Spawn workers
-await tools.spawn({
-  name: 'Worker1',
-  cli: 'claude',
-  task: 'Run tests and report results',
+const relay = await createRelay({
+  socketPath: '/tmp/my-relay.sock',  // Optional custom socket
+  quiet: true,                        // Suppress logs (default: true)
 });
 
-// Check messages
-const messages = await tools.inbox();
-
-// List online agents
-const agents = await tools.who();
+// Create clients
+const agent = await relay.client('MyAgent');
 
-// Release workers
-await tools.release('Worker1');
+// Stop everything
+await relay.stop();
 ```
 
-### Option 3: HTTP API (For Non-Node Environments)
+### createPair(name1, name2, config?)
 
-If the daemon is running with dashboard, use the HTTP API:
+Shortcut to create two connected agents.
 
-```bash
-# Spawn an agent
-curl -X POST http://localhost:3888/api/spawn \
-  -H 'Content-Type: application/json' \
-  -d '{"name": "Worker1", "cli": "claude", "task": "Run tests"}'
-
-# List agents
-curl http://localhost:3888/api/spawned
-
-# Release an agent
-curl -X DELETE http://localhost:3888/api/spawned/Worker1
+```typescript
+const { alice, bob, stop } = await createPair('alice', 'bob');
 ```
 
-## Features
-
-| Feature | Description |
-|---------|-------------|
-| **Auto-discovery** | Finds daemon socket automatically |
-| **Auto-reconnect** | Handles disconnections automatically |
-| **Message deduplication** | No duplicate deliveries |
-| **Sync messaging** | Wait for acknowledgment |
-| **Broadcast** | Send to all agents with `*` |
-| **Channels** | Group messaging with `#channel` |
-
-## API Reference
-
 ### RelayClient
 
-```typescript
-import { RelayClient } from '@agent-relay/sdk';
-
-const client = new RelayClient({
-  agentName: 'MyAgent',      // Required: your agent's name
-  socketPath: '/custom/path', // Optional: override auto-discovery
-  reconnect: true,            // Optional: auto-reconnect (default: true)
-  quiet: false,               // Optional: suppress logs (default: false)
-});
-
-// Connect to daemon
-await client.connect();
+The client for agent communication.
 
+```typescript
 // Send messages
 client.sendMessage('OtherAgent', 'Hello!');
 client.sendMessage('#general', 'Channel message');
 client.sendMessage('*', 'Broadcast to everyone');
 
 // Wait for acknowledgment
-const ack = await client.sendAndWait('OtherAgent', 'Important message', {
-  timeoutMs: 30000,
-});
+const ack = await client.sendAndWait('OtherAgent', 'Important message');
 
 // Receive messages
 client.onMessage = (from, payload, messageId, meta, originalTo) => {
@@ -224,20 +117,23 @@ client.onStateChange = (state) => {
 client.disconnect();
 ```
 
-### Socket Discovery
+## Using with External Daemon
+
+If you're running `agent-relay up` separately (e.g., for the dashboard), use the client directly:
 
 ```typescript
-import { discoverSocket, getDefaultSocketPath } from '@agent-relay/sdk';
+import { RelayClient } from '@agent-relay/sdk';
 
-// Get full discovery result
-const result = discoverSocket();
-// { socketPath: string, projectId: string, source: 'env' | 'cloud' | 'project' | 'legacy' }
+const client = new RelayClient({
+  agentName: 'MyAgent',
+  socketPath: '/tmp/agent-relay.sock',
+});
 
-// Get just the path
-const socketPath = getDefaultSocketPath();
+await client.connect();
+client.sendMessage('OtherAgent', 'Hello!');
 ```
 
-### Channels
+## Advanced: Channels
 
 ```typescript
 // Join a channel
@@ -255,7 +151,7 @@ client.onChannelMessage = (from, channel, body, envelope) => {
 client.leaveChannel('#general');
 ```
 
-### Shadow Agents
+## Advanced: Shadow Agents
 
 Monitor another agent's communication:
 
@@ -270,19 +166,6 @@ client.bindAsShadow('PrimaryAgent', {
 client.unbindAsShadow('PrimaryAgent');
 ```
 
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `RELAY_SOCKET` | Override daemon socket path |
-| `RELAY_PROJECT` | Override project name |
-| `WORKSPACE_ID` | Cloud workspace ID (auto-detects cloud socket) |
-
-## Requirements
-
-- Node.js 18+
-- Agent Relay daemon running (`agent-relay up`)
-
 ## License
 
 MIT

package/packages/sdk/dist/client.d.ts

@@ -45,39 +45,7 @@ export interface ClientConfig {
     reconnectMaxDelayMs: number;
 }
 /**
- * RelayClient - Agent-to-agent communication client for Agent Relay.
- *
- * The client automatically discovers the daemon socket path. You only need to provide
- * your agent name. Use `connect()` to establish a connection, then send/receive messages.
- *
- * @example Basic Usage
- * ```typescript
- * import { RelayClient } from '@agent-relay/sdk';
- *
- * const client = new RelayClient({ agentName: 'MyAgent' });
- * await client.connect();
- *
- * // Send messages
- * client.sendMessage('OtherAgent', 'Hello!');
- * client.sendMessage('#general', 'Channel message');
- * client.sendMessage('*', 'Broadcast');
- *
- * // Receive messages
- * client.onMessage = (from, payload) => {
- *   console.log(`${from}: ${payload.body}`);
- * };
- *
- * // Disconnect when done
- * client.disconnect();
- * ```
- *
- * @example Wait for Response
- * ```typescript
- * const response = await client.sendAndWait('Worker', 'Do this task', {
- *   timeoutMs: 30000,
- * });
- * console.log(`Worker replied: ${response.content}`);
- * ```
+ * RelayClient for agent-to-agent communication.
  */
 export declare class RelayClient {
     private config;
@@ -94,32 +62,12 @@ export declare class RelayClient {
     private writeQueue;
     private writeScheduled;
     private pendingSyncAcks;
-    /**
-     * Callback for receiving direct messages.
-     * @param from - Name of the sending agent
-     * @param payload - Message payload containing body, kind, and optional data
-     * @param messageId - Unique message identifier
-     * @param meta - Optional metadata (sync info, etc.)
-     * @param originalTo - Original recipient (useful for detecting broadcasts when originalTo='*')
-     */
     onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
     /**
      * Callback for channel messages.
-     * @param from - Name of the sending agent
-     * @param channel - Channel name (e.g., '#general')
-     * @param body - Message body text
-     * @param envelope - Full message envelope with metadata
      */
     onChannelMessage?: (from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>) => void;
-    /**
-     * Callback for connection state changes.
-     * @param state - New connection state: 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF'
-     */
     onStateChange?: (state: ClientState) => void;
-    /**
-     * Callback for errors.
-     * @param error - The error that occurred
-     */
     onError?: (error: Error) => void;
     constructor(config?: Partial<ClientConfig>);
     get state(): ClientState;
@@ -138,30 +86,7 @@ export declare class RelayClient {
      */
     destroy(): void;
     /**
-     * Send a message to another agent, channel, or broadcast.
-     *
-     * @param to - Recipient: agent name, '#channel', or '*' for broadcast
-     * @param body - Message content
-     * @param kind - Message type (default: 'message')
-     * @param data - Optional structured data to include
-     * @param thread - Optional thread ID for conversation threading
-     * @param meta - Optional metadata (sync info, etc.)
-     * @returns true if message was queued, false if not connected
-     *
-     * @example
-     * ```typescript
-     * // Direct message
-     * client.sendMessage('Worker1', 'Start the task');
-     *
-     * // Channel message
-     * client.sendMessage('#general', 'Team update');
-     *
-     * // Broadcast to all agents
-     * client.sendMessage('*', 'System announcement');
-     *
-     * // With structured data
-     * client.sendMessage('Worker1', 'Process this', 'task', { priority: 'high' });
-     * ```
+     * Send a message to another agent.
      */
     sendMessage(to: string, body: string, kind?: PayloadKind, data?: Record<string, unknown>, thread?: string, meta?: SendMeta): boolean;
     /**
@@ -169,28 +94,7 @@ export declare class RelayClient {
      */
     sendAck(payload: AckPayload): boolean;
     /**
-     * Send a message and wait for acknowledgment response.
-     *
-     * This is useful for request-response patterns where you need to wait for
-     * the recipient to process your message and reply.
-     *
-     * @param to - Recipient agent name
-     * @param body - Message content
-     * @param options - Options including timeout, thread, etc.
-     * @returns Promise that resolves with the ACK payload when recipient responds
-     * @throws Error if client not ready or timeout exceeded
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const response = await client.sendAndWait('Worker', 'Process this task', {
-     *     timeoutMs: 30000,  // 30 second timeout
-     *   });
-     *   console.log('Worker responded:', response);
-     * } catch (err) {
-     *   console.error('Worker did not respond in time');
-     * }
-     * ```
+     * Send a message and wait for ACK response.
      */
     sendAndWait(to: string, body: string, options?: SyncOptions): Promise<AckPayload>;
     /**