agent-relay 2.0.0 → 2.0.4

package/packages/sdk/README.md

@@ -1,15 +1,17 @@
 # @agent-relay/sdk
 
-Dead simple agent-to-agent communication.
+Dead simple agent-to-agent communication for AI agent systems.
 
 ## Install
 
 ```bash
-npm install @agent-relay/sdk @agent-relay/daemon
+npm install @agent-relay/sdk
 ```
 
 ## Quick Start
 
+### Standalone (In-Process Daemon)
+
 ```typescript
 import { createRelay } from '@agent-relay/sdk';
 
@@ -32,9 +34,7 @@ alice.sendMessage('Bob', 'Hello!');
 await relay.stop();
 ```
 
-That's it. No daemon to start, no config files, no setup.
-
-## Even Simpler: Two Agents
+### Two-Agent Shortcut
 
 ```typescript
 import { createPair } from '@agent-relay/sdk';
@@ -47,56 +47,163 @@ alice.sendMessage('bob', 'Hey!');
 await stop();
 ```
 
-## Features
+### With External Daemon
 
-| 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` |
+If you're running `agent-relay up` separately:
 
-## API Reference
+```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' });
 
-### createRelay(config?)
+await client.connect();
+client.sendMessage('OtherAgent', 'Hello!');
+```
 
-Creates a standalone relay with an in-process daemon.
+## 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
-const relay = await createRelay({
-  socketPath: '/tmp/my-relay.sock',  // Optional custom socket
-  quiet: true,                        // Suppress logs (default: true)
-});
+import { discoverSocket, getDefaultSocketPath } from '@agent-relay/sdk';
 
-// Create clients
-const agent = await relay.client('MyAgent');
+// Get detailed discovery info
+const { socketPath, projectId, source } = discoverSocket();
+console.log(`Using socket: ${socketPath} (source: ${source})`);
 
-// Stop everything
-await relay.stop();
+// Or just get the path
+const socketPath = getDefaultSocketPath();
 ```
 
-### createPair(name1, name2, config?)
+## Integration Guide (for Libraries like AgentSwarm)
 
-Shortcut to create two connected agents.
+If you're building a library that integrates with Agent Relay:
+
+### Option 1: Use the SDK Client (Recommended)
 
 ```typescript
-const { alice, bob, stop } = await createPair('alice', 'bob');
+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);
+  }
+
+  async waitForResponse(to: string, message: string, timeoutMs = 30000) {
+    return this.client.sendAndWait(to, message, { timeoutMs });
+  }
+
+  onMessage(handler: (from: string, body: string) => void) {
+    this.client.onMessage = (from, payload) => {
+      handler(from, payload.body);
+    };
+  }
+}
 ```
 
-### RelayClient
+### Option 2: Use MCP Simple API (If Using MCP)
 
-The client for agent communication.
+If your agents use MCP, the `@agent-relay/mcp` package has an even simpler API:
 
 ```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',
+});
+
+// Check messages
+const messages = await tools.inbox();
+
+// List online agents
+const agents = await tools.who();
+
+// Release workers
+await tools.release('Worker1');
+```
+
+### Option 3: HTTP API (For Non-Node Environments)
+
+If the daemon is running with dashboard, use the HTTP API:
+
+```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
+```
+
+## 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();
+
 // 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');
+const ack = await client.sendAndWait('OtherAgent', 'Important message', {
+  timeoutMs: 30000,
+});
 
 // Receive messages
 client.onMessage = (from, payload, messageId, meta, originalTo) => {
@@ -117,23 +224,20 @@ client.onStateChange = (state) => {
 client.disconnect();
 ```
 
-## Using with External Daemon
-
-If you're running `agent-relay up` separately (e.g., for the dashboard), use the client directly:
+### Socket Discovery
 
 ```typescript
-import { RelayClient } from '@agent-relay/sdk';
+import { discoverSocket, getDefaultSocketPath } from '@agent-relay/sdk';
 
-const client = new RelayClient({
-  agentName: 'MyAgent',
-  socketPath: '/tmp/agent-relay.sock',
-});
+// Get full discovery result
+const result = discoverSocket();
+// { socketPath: string, projectId: string, source: 'env' | 'cloud' | 'project' | 'legacy' }
 
-await client.connect();
-client.sendMessage('OtherAgent', 'Hello!');
+// Get just the path
+const socketPath = getDefaultSocketPath();
 ```
 
-## Advanced: Channels
+### Channels
 
 ```typescript
 // Join a channel
@@ -151,7 +255,7 @@ client.onChannelMessage = (from, channel, body, envelope) => {
 client.leaveChannel('#general');
 ```
 
-## Advanced: Shadow Agents
+### Shadow Agents
 
 Monitor another agent's communication:
 
@@ -166,6 +270,19 @@ 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,7 +45,39 @@ export interface ClientConfig {
     reconnectMaxDelayMs: number;
 }
 /**
- * RelayClient for agent-to-agent communication.
+ * 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}`);
+ * ```
  */
 export declare class RelayClient {
     private config;
@@ -62,12 +94,32 @@ 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;
@@ -86,7 +138,30 @@ export declare class RelayClient {
      */
     destroy(): void;
     /**
-     * Send a message to another agent.
+     * 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' });
+     * ```
      */
     sendMessage(to: string, body: string, kind?: PayloadKind, data?: Record<string, unknown>, thread?: string, meta?: SendMeta): boolean;
     /**
@@ -94,7 +169,28 @@ export declare class RelayClient {
      */
     sendAck(payload: AckPayload): boolean;
     /**
-     * Send a message and wait for ACK response.
+     * 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');
+     * }
+     * ```
      */
     sendAndWait(to: string, body: string, options?: SyncOptions): Promise<AckPayload>;
     /**

package/packages/sdk/dist/client.js

@@ -6,11 +6,19 @@
  */
 import net from 'node:net';
 import { randomUUID } from 'node:crypto';
+import { getDefaultSocketPath } from './discovery.js';
 import { PROTOCOL_VERSION, } from './protocol/types.js';
 import { encodeFrameLegacy, FrameParser } from './protocol/framing.js';
-const DEFAULT_SOCKET_PATH = '/tmp/agent-relay.sock';
+// Socket path is discovered lazily to allow environment to be set up first
+let _discoveredSocketPath = null;
+function getDiscoveredSocketPath() {
+    if (_discoveredSocketPath === null) {
+        _discoveredSocketPath = getDefaultSocketPath();
+    }
+    return _discoveredSocketPath;
+}
 const DEFAULT_CLIENT_CONFIG = {
-    socketPath: DEFAULT_SOCKET_PATH,
+    socketPath: '', // Will be set in constructor if not provided
     agentName: 'agent',
     cli: undefined,
     quiet: false,
@@ -56,7 +64,39 @@ class CircularDedupeCache {
     }
 }
 /**
- * RelayClient for agent-to-agent communication.
+ * 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}`);
+ * ```
  */
 export class RelayClient {
     config;
@@ -73,16 +113,39 @@ export class RelayClient {
     writeQueue = [];
     writeScheduled = false;
     pendingSyncAcks = new Map();
-    // Event handlers
+    /**
+     * 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;
     /**
      * 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;
+    /**
+     * Callback for connection state changes.
+     * @param state - New connection state: 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF'
+     */
     onStateChange;
+    /**
+     * Callback for errors.
+     * @param error - The error that occurred
+     */
     onError;
     constructor(config = {}) {
         this.config = { ...DEFAULT_CLIENT_CONFIG, ...config };
+        // Use discovered socket path if not explicitly provided
+        if (!this.config.socketPath) {
+            this.config.socketPath = getDiscoveredSocketPath();
+        }
         this.parser = new FrameParser();
         this.parser.setLegacyMode(true);
         this.reconnectDelay = this.config.reconnectDelayMs;
@@ -177,7 +240,30 @@ export class RelayClient {
         this.disconnect();
     }
     /**
-     * Send a message to another agent.
+     * 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' });
+     * ```
      */
     sendMessage(to, body, kind = 'message', data, thread, meta) {
         if (this._state !== 'READY') {
@@ -216,7 +302,28 @@ export class RelayClient {
         return this.send(envelope);
     }
     /**
-     * Send a message and wait for ACK response.
+     * 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');
+     * }
+     * ```
      */
     async sendAndWait(to, body, options = {}) {
         if (this._state !== 'READY') {

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

@@ -0,0 +1,29 @@
+/**
+ * Socket Discovery for Agent Relay SDK
+ *
+ * Discovers the daemon socket path for local development and cloud environments.
+ */
+export interface DiscoveryResult {
+    socketPath: string;
+    projectId: string;
+    source: 'env' | 'cloud' | 'project' | 'legacy';
+}
+/**
+ * Discover the relay daemon socket path.
+ *
+ * Discovery order:
+ * 1. RELAY_SOCKET environment variable (explicit override)
+ * 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)
+ *
+ * @param cwd - Working directory to start search from (default: process.cwd())
+ * @returns Discovery result with socket path and metadata
+ */
+export declare function discoverSocket(cwd?: string): DiscoveryResult;
+/**
+ * Get the default socket path using discovery.
+ * Convenience function that returns just the path.
+ */
+export declare function getDefaultSocketPath(cwd?: string): string;
+//# sourceMappingURL=discovery.d.ts.map