@agent-relay/sdk 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# @agent-relay/sdk
+
+Dead simple agent-to-agent communication.
+
+## Install
+
+```bash
+npm install @agent-relay/sdk @agent-relay/daemon
+```
+
+## Quick Start
+
+```typescript
+import { createRelay } from '@agent-relay/sdk';
+
+// Start a relay (in-process daemon - no setup required)
+const relay = await createRelay();
+
+// Create agents
+const alice = await relay.client('Alice');
+const bob = await relay.client('Bob');
+
+// Bob listens for messages
+bob.onMessage = (from, { body }) => {
+  console.log(`${from}: ${body}`);
+};
+
+// Alice sends a message
+alice.sendMessage('Bob', 'Hello!');
+
+// When done
+await relay.stop();
+```
+
+That's it. No daemon to start, no config files, no setup.
+
+## Even Simpler: Two Agents
+
+```typescript
+import { createPair } from '@agent-relay/sdk';
+
+const { alice, bob, stop } = await createPair('alice', 'bob');
+
+bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
+alice.sendMessage('bob', 'Hey!');
+
+await stop();
+```
+
+## Features
+
+| 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` |
+
+## API Reference
+
+### createRelay(config?)
+
+Creates a standalone relay with an in-process daemon.
+
+```typescript
+const relay = await createRelay({
+  socketPath: '/tmp/my-relay.sock',  // Optional custom socket
+  quiet: true,                        // Suppress logs (default: true)
+});
+
+// Create clients
+const agent = await relay.client('MyAgent');
+
+// Stop everything
+await relay.stop();
+```
+
+### createPair(name1, name2, config?)
+
+Shortcut to create two connected agents.
+
+```typescript
+const { alice, bob, stop } = await createPair('alice', 'bob');
+```
+
+### RelayClient
+
+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');
+
+// Receive messages
+client.onMessage = (from, payload, messageId, meta, originalTo) => {
+  console.log(`${from}: ${payload.body}`);
+
+  // Check if broadcast
+  if (originalTo === '*') {
+    console.log('This was a broadcast');
+  }
+};
+
+// Connection state changes
+client.onStateChange = (state) => {
+  // 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF'
+};
+
+// Disconnect
+client.disconnect();
+```
+
+## Using with External Daemon
+
+If you're running `agent-relay up` separately (e.g., for the dashboard), use the client directly:
+
+```typescript
+import { RelayClient } from '@agent-relay/sdk';
+
+const client = new RelayClient({
+  agentName: 'MyAgent',
+  socketPath: '/tmp/agent-relay.sock',
+});
+
+await client.connect();
+client.sendMessage('OtherAgent', 'Hello!');
+```
+
+## Advanced: Channels
+
+```typescript
+// Join a channel
+client.joinChannel('#general');
+
+// Send to channel
+client.sendChannelMessage('#general', 'Hello team!');
+
+// Receive channel messages
+client.onChannelMessage = (from, channel, body, envelope) => {
+  console.log(`[${channel}] ${from}: ${body}`);
+};
+
+// Leave channel
+client.leaveChannel('#general');
+```
+
+## Advanced: Shadow Agents
+
+Monitor another agent's communication:
+
+```typescript
+// Bind as shadow to see all messages to/from PrimaryAgent
+client.bindAsShadow('PrimaryAgent', {
+  receiveIncoming: true,
+  receiveOutgoing: true,
+});
+
+// Unbind
+client.unbindAsShadow('PrimaryAgent');
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,181 @@
+/**
+ * RelayClient - Agent Relay SDK Client
+ * @agent-relay/sdk
+ *
+ * Lightweight client for agent-to-agent communication via Agent Relay daemon.
+ */
+import { type Envelope, type SendPayload, type SendMeta, type AckPayload, type PayloadKind, type SpeakOnTrigger, type EntityType, type ChannelMessagePayload, type MessageAttachment } from './protocol/types.js';
+export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
+export interface SyncOptions {
+    timeoutMs?: number;
+    kind?: PayloadKind;
+    data?: Record<string, unknown>;
+    thread?: string;
+}
+export interface ClientConfig {
+    /** Daemon socket path (default: /tmp/agent-relay.sock) */
+    socketPath: string;
+    /** Agent name */
+    agentName: string;
+    /** Entity type: 'agent' (default) or 'user' */
+    entityType?: EntityType;
+    /** CLI identifier (claude, codex, gemini, etc.) */
+    cli?: string;
+    /** Program identifier */
+    program?: string;
+    /** Model identifier */
+    model?: string;
+    /** Task description */
+    task?: string;
+    /** Working directory */
+    workingDirectory?: string;
+    /** Display name for human users */
+    displayName?: string;
+    /** Avatar URL for human users */
+    avatarUrl?: string;
+    /** Suppress console logging */
+    quiet?: boolean;
+    /** Auto-reconnect on disconnect */
+    reconnect: boolean;
+    /** Max reconnect attempts */
+    maxReconnectAttempts: number;
+    /** Initial reconnect delay (ms) */
+    reconnectDelayMs: number;
+    /** Max reconnect delay (ms) */
+    reconnectMaxDelayMs: number;
+}
+/**
+ * RelayClient for agent-to-agent communication.
+ */
+export declare class RelayClient {
+    private config;
+    private socket?;
+    private parser;
+    private _state;
+    private sessionId?;
+    private resumeToken?;
+    private reconnectAttempts;
+    private reconnectDelay;
+    private reconnectTimer?;
+    private _destroyed;
+    private dedupeCache;
+    private writeQueue;
+    private writeScheduled;
+    private pendingSyncAcks;
+    onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
+    /**
+     * Callback for channel messages.
+     */
+    onChannelMessage?: (from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>) => void;
+    onStateChange?: (state: ClientState) => void;
+    onError?: (error: Error) => void;
+    constructor(config?: Partial<ClientConfig>);
+    get state(): ClientState;
+    get agentName(): string;
+    get currentSessionId(): string | undefined;
+    /**
+     * Connect to the relay daemon.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the relay daemon.
+     */
+    disconnect(): void;
+    /**
+     * Permanently destroy the client.
+     */
+    destroy(): void;
+    /**
+     * Send a message to another agent.
+     */
+    sendMessage(to: string, body: string, kind?: PayloadKind, data?: Record<string, unknown>, thread?: string, meta?: SendMeta): boolean;
+    /**
+     * Send an ACK for a delivered message.
+     */
+    sendAck(payload: AckPayload): boolean;
+    /**
+     * Send a message and wait for ACK response.
+     */
+    sendAndWait(to: string, body: string, options?: SyncOptions): Promise<AckPayload>;
+    /**
+     * Broadcast a message to all agents.
+     */
+    broadcast(body: string, kind?: PayloadKind, data?: Record<string, unknown>): boolean;
+    /**
+     * Subscribe to a topic.
+     */
+    subscribe(topic: string): boolean;
+    /**
+     * Unsubscribe from a topic.
+     */
+    unsubscribe(topic: string): boolean;
+    /**
+     * Bind as a shadow to a primary agent.
+     */
+    bindAsShadow(primaryAgent: string, options?: {
+        speakOn?: SpeakOnTrigger[];
+        receiveIncoming?: boolean;
+        receiveOutgoing?: boolean;
+    }): boolean;
+    /**
+     * Unbind from a primary agent.
+     */
+    unbindAsShadow(primaryAgent: string): boolean;
+    /**
+     * Send log output to the daemon for dashboard streaming.
+     */
+    sendLog(data: string): boolean;
+    /**
+     * Join a channel.
+     * @param channel - Channel name (e.g., '#general', 'dm:alice:bob')
+     * @param displayName - Optional display name for this member
+     */
+    joinChannel(channel: string, displayName?: string): boolean;
+    /**
+     * Admin join: Add any member to a channel (does not require member to be connected).
+     * @param channel - Channel name
+     * @param member - Name of the member to add
+     */
+    adminJoinChannel(channel: string, member: string): boolean;
+    /**
+     * Leave a channel.
+     * @param channel - Channel name to leave
+     * @param reason - Optional reason for leaving
+     */
+    leaveChannel(channel: string, reason?: string): boolean;
+    /**
+     * Admin remove: Remove any member from a channel.
+     * @param channel - Channel name
+     * @param member - Name of the member to remove
+     */
+    adminRemoveMember(channel: string, member: string): boolean;
+    /**
+     * Send a message to a channel.
+     * @param channel - Channel name
+     * @param body - Message content
+     * @param options - Optional thread, mentions, attachments
+     */
+    sendChannelMessage(channel: string, body: string, options?: {
+        thread?: string;
+        mentions?: string[];
+        attachments?: MessageAttachment[];
+        data?: Record<string, unknown>;
+    }): boolean;
+    private setState;
+    private sendHello;
+    private send;
+    private flushWrites;
+    private handleData;
+    private processFrame;
+    private handleWelcome;
+    private handleDeliver;
+    private handleChannelMessage;
+    private handleAck;
+    private handlePing;
+    private handleErrorFrame;
+    private handleDisconnect;
+    private handleError;
+    private rejectPendingSyncAcks;
+    private scheduleReconnect;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}