agent-relay 1.6.0 → 2.0.4

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

package/packages/sdk/dist/discovery.js

@@ -0,0 +1,126 @@
+/**
+ * Socket Discovery for Agent Relay SDK
+ *
+ * Discovers the daemon socket path for local development and cloud environments.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+/**
+ * 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 markers = ['.git', 'package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', '.agent-relay'];
+    // Limit iterations to prevent infinite loops
+    for (let i = 0; i < 100; i++) {
+        for (const marker of markers) {
+            if (existsSync(join(current, marker))) {
+                return current;
+            }
+        }
+        const parent = join(current, '..');
+        if (parent === current)
+            break; // Reached root
+        current = parent;
+    }
+    return null;
+}
+/**
+ * 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 function discoverSocket(cwd) {
+    const startDir = cwd || process.cwd();
+    // 1. Explicit socket path from environment
+    const socketEnv = process.env.RELAY_SOCKET;
+    if (socketEnv && existsSync(socketEnv)) {
+        return {
+            socketPath: socketEnv,
+            projectId: process.env.RELAY_PROJECT || 'env',
+            source: 'env',
+        };
+    }
+    // 2. Cloud workspace socket (if WORKSPACE_ID is set)
+    const workspaceId = process.env.WORKSPACE_ID;
+    if (workspaceId) {
+        const cloudSocket = `/tmp/relay/${workspaceId}/sockets/daemon.sock`;
+        if (existsSync(cloudSocket)) {
+            return {
+                socketPath: cloudSocket,
+                projectId: workspaceId,
+                source: 'cloud',
+            };
+        }
+    }
+    // 3. Project-local socket
+    // First try cwd, then scan up to find project root
+    const projectRoot = findProjectRoot(startDir);
+    const searchDirs = [startDir];
+    if (projectRoot && projectRoot !== startDir) {
+        searchDirs.push(projectRoot);
+    }
+    for (const dir of searchDirs) {
+        const projectLocalSocket = join(dir, '.agent-relay', 'relay.sock');
+        if (existsSync(projectLocalSocket)) {
+            // Read project ID from marker file if available
+            let projectId = 'local';
+            const markerPath = join(dir, '.agent-relay', '.project');
+            if (existsSync(markerPath)) {
+                try {
+                    const marker = JSON.parse(readFileSync(markerPath, 'utf-8'));
+                    projectId = marker.projectId || 'local';
+                }
+                catch {
+                    // Ignore marker read errors
+                }
+            }
+            return {
+                socketPath: projectLocalSocket,
+                projectId,
+                source: 'project',
+            };
+        }
+    }
+    // 4. Legacy fallback
+    const legacySocket = '/tmp/agent-relay.sock';
+    if (existsSync(legacySocket)) {
+        return {
+            socketPath: legacySocket,
+            projectId: 'legacy',
+            source: 'legacy',
+        };
+    }
+    // Also check ~/.agent-relay for legacy global installations
+    const homeSocket = join(homedir(), '.agent-relay', 'relay.sock');
+    if (existsSync(homeSocket)) {
+        return {
+            socketPath: homeSocket,
+            projectId: 'home',
+            source: 'legacy',
+        };
+    }
+    // Return legacy path even if it doesn't exist (will fail on connect)
+    return {
+        socketPath: legacySocket,
+        projectId: 'unknown',
+        source: 'legacy',
+    };
+}
+/**
+ * Get the default socket path using discovery.
+ * Convenience function that returns just the path.
+ */
+export function getDefaultSocketPath(cwd) {
+    return discoverSocket(cwd).socketPath;
+}
+//# sourceMappingURL=discovery.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * @agent-relay/sdk
+ *
+ * Lightweight SDK for agent-to-agent communication via Agent Relay.
+ *
+ * ## Quick Start (Standalone - No Setup Required)
+ *
+ * ```typescript
+ * import { createRelay } from '@agent-relay/sdk';
+ *
+ * const relay = await createRelay();
+ * const alice = await relay.client('Alice');
+ * const bob = await relay.client('Bob');
+ *
+ * bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
+ * alice.sendMessage('Bob', 'Hello!');
+ * ```
+ *
+ * ## With External Daemon
+ *
+ * ```typescript
+ * import { RelayClient } from '@agent-relay/sdk';
+ *
+ * const client = new RelayClient({ agentName: 'MyAgent' });
+ * await client.connect();
+ * ```
+ */
+export { RelayClient, type ClientState, type ClientConfig, type SyncOptions, } from './client.js';
+export { createRelay, createPair, type Relay, type RelayConfig, } from './standalone.js';
+export { PROTOCOL_VERSION, type MessageType, type PayloadKind, type Envelope, type EntityType, type SendPayload, type SendMeta, type SyncMeta, type DeliveryInfo, type AckPayload, type ErrorCode, type ErrorPayload, type SpeakOnTrigger, type ShadowConfig, type SpawnPayload, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type ChannelMessagePayload, type ChannelJoinPayload, type ChannelLeavePayload, } from './protocol/index.js';
+export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
+export { discoverSocket, getDefaultSocketPath, type DiscoveryResult, } from './discovery.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * @agent-relay/sdk
+ *
+ * Lightweight SDK for agent-to-agent communication via Agent Relay.
+ *
+ * ## Quick Start (Standalone - No Setup Required)
+ *
+ * ```typescript
+ * import { createRelay } from '@agent-relay/sdk';
+ *
+ * const relay = await createRelay();
+ * const alice = await relay.client('Alice');
+ * const bob = await relay.client('Bob');
+ *
+ * bob.onMessage = (from, { body }) => console.log(`${from}: ${body}`);
+ * alice.sendMessage('Bob', 'Hello!');
+ * ```
+ *
+ * ## With External Daemon
+ *
+ * ```typescript
+ * import { RelayClient } from '@agent-relay/sdk';
+ *
+ * const client = new RelayClient({ agentName: 'MyAgent' });
+ * await client.connect();
+ * ```
+ */
+// Main client
+export { RelayClient, } from './client.js';
+// Standalone relay (in-process daemon for simple use cases)
+export { createRelay, createPair, } from './standalone.js';
+// Protocol types (re-export for convenience)
+export { PROTOCOL_VERSION, } from './protocol/index.js';
+// Framing utilities
+export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
+// Socket discovery utilities
+export { discoverSocket, getDefaultSocketPath, } from './discovery.js';
+//# sourceMappingURL=index.js.map

package/packages/sdk/dist/protocol/framing.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Frame encoding/decoding for the Agent Relay protocol.
+ * @agent-relay/sdk
+ *
+ * Wire format:
+ * - 1 byte: format indicator (0 = JSON, 1 = MessagePack)
+ * - 4 bytes: big-endian payload length
+ * - N bytes: payload (JSON or MessagePack encoded)
+ *
+ * Legacy format (for backwards compatibility):
+ * - 4 bytes: big-endian payload length
+ * - N bytes: JSON payload
+ */
+import type { Envelope } from './types.js';
+export declare const MAX_FRAME_BYTES: number;
+export declare const HEADER_SIZE = 5;
+export declare const LEGACY_HEADER_SIZE = 4;
+export type WireFormat = 'json' | 'msgpack';
+/**
+ * Initialize MessagePack support.
+ * Install @msgpack/msgpack to enable: npm install @msgpack/msgpack
+ */
+export declare function initMessagePack(): Promise<boolean>;
+/**
+ * Check if MessagePack is available.
+ */
+export declare function hasMessagePack(): boolean;
+/**
+ * Encode a message envelope into a framed buffer.
+ *
+ * @param envelope - The envelope to encode
+ * @param format - Wire format to use (default: 'json')
+ * @returns Framed buffer ready for socket write
+ */
+export declare function encodeFrame(envelope: Envelope, format?: WireFormat): Buffer;
+/**
+ * Encode a frame in legacy format (no format byte, JSON only).
+ * Used for backwards compatibility with older clients.
+ */
+export declare function encodeFrameLegacy(envelope: Envelope): Buffer;
+/**
+ * Ring buffer-based frame parser for streaming data.
+ */
+export declare class FrameParser {
+    private ring;
+    private head;
+    private tail;
+    private readonly capacity;
+    private readonly maxFrameBytes;
+    private format;
+    private legacyMode;
+    constructor(maxFrameBytes?: number);
+    /**
+     * Set the expected wire format for parsing.
+     */
+    setFormat(format: WireFormat): void;
+    /**
+     * Enable legacy mode (4-byte header, JSON only).
+     */
+    setLegacyMode(legacy: boolean): void;
+    /**
+     * Get current unread bytes in buffer.
+     */
+    get pendingBytes(): number;
+    /**
+     * Push data into the parser and extract complete frames.
+     *
+     * @param data - Incoming data buffer
+     * @returns Array of parsed envelope frames
+     */
+    push(data: Buffer): Envelope[];
+    private extractFrames;
+    private decodePayload;
+    private compact;
+    /**
+     * Reset parser state.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=framing.d.ts.map

package/packages/sdk/dist/protocol/framing.js

@@ -0,0 +1,206 @@
+/**
+ * Frame encoding/decoding for the Agent Relay protocol.
+ * @agent-relay/sdk
+ *
+ * Wire format:
+ * - 1 byte: format indicator (0 = JSON, 1 = MessagePack)
+ * - 4 bytes: big-endian payload length
+ * - N bytes: payload (JSON or MessagePack encoded)
+ *
+ * Legacy format (for backwards compatibility):
+ * - 4 bytes: big-endian payload length
+ * - N bytes: JSON payload
+ */
+export const MAX_FRAME_BYTES = 1024 * 1024; // 1 MiB
+export const HEADER_SIZE = 5; // 1 byte format + 4 bytes length
+export const LEGACY_HEADER_SIZE = 4; // For backwards compatibility
+// Format indicator bytes
+const FORMAT_JSON = 0;
+const FORMAT_MSGPACK = 1;
+// Optional MessagePack - loaded dynamically if available
+let msgpack = null;
+/**
+ * Initialize MessagePack support.
+ * Install @msgpack/msgpack to enable: npm install @msgpack/msgpack
+ */
+export async function initMessagePack() {
+    if (msgpack)
+        return true;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = await import('@msgpack/msgpack');
+        const encode = mod.encode || mod.default?.encode;
+        const decode = mod.decode || mod.default?.decode;
+        if (encode && decode) {
+            msgpack = { encode, decode };
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if MessagePack is available.
+ */
+export function hasMessagePack() {
+    return msgpack !== null;
+}
+/**
+ * Encode a message envelope into a framed buffer.
+ *
+ * @param envelope - The envelope to encode
+ * @param format - Wire format to use (default: 'json')
+ * @returns Framed buffer ready for socket write
+ */
+export function encodeFrame(envelope, format = 'json') {
+    let data;
+    let formatByte;
+    if (format === 'msgpack' && msgpack) {
+        const encoded = msgpack.encode(envelope);
+        data = Buffer.from(encoded.buffer, encoded.byteOffset, encoded.byteLength);
+        formatByte = FORMAT_MSGPACK;
+    }
+    else {
+        data = Buffer.from(JSON.stringify(envelope), 'utf-8');
+        formatByte = FORMAT_JSON;
+    }
+    if (data.length > MAX_FRAME_BYTES) {
+        throw new Error(`Frame too large: ${data.length} > ${MAX_FRAME_BYTES}`);
+    }
+    const header = Buffer.alloc(HEADER_SIZE);
+    header.writeUInt8(formatByte, 0);
+    header.writeUInt32BE(data.length, 1);
+    return Buffer.concat([header, data]);
+}
+/**
+ * Encode a frame in legacy format (no format byte, JSON only).
+ * Used for backwards compatibility with older clients.
+ */
+export function encodeFrameLegacy(envelope) {
+    const json = JSON.stringify(envelope);
+    const data = Buffer.from(json, 'utf-8');
+    if (data.length > MAX_FRAME_BYTES) {
+        throw new Error(`Frame too large: ${data.length} > ${MAX_FRAME_BYTES}`);
+    }
+    const header = Buffer.alloc(LEGACY_HEADER_SIZE);
+    header.writeUInt32BE(data.length, 0);
+    return Buffer.concat([header, data]);
+}
+/**
+ * Ring buffer-based frame parser for streaming data.
+ */
+export class FrameParser {
+    ring;
+    head = 0;
+    tail = 0;
+    capacity;
+    maxFrameBytes;
+    format = 'json';
+    legacyMode = false;
+    constructor(maxFrameBytes = MAX_FRAME_BYTES) {
+        this.maxFrameBytes = maxFrameBytes;
+        this.capacity = maxFrameBytes * 2 + HEADER_SIZE;
+        this.ring = Buffer.allocUnsafe(this.capacity);
+    }
+    /**
+     * Set the expected wire format for parsing.
+     */
+    setFormat(format) {
+        this.format = format;
+    }
+    /**
+     * Enable legacy mode (4-byte header, JSON only).
+     */
+    setLegacyMode(legacy) {
+        this.legacyMode = legacy;
+    }
+    /**
+     * Get current unread bytes in buffer.
+     */
+    get pendingBytes() {
+        return this.tail - this.head;
+    }
+    /**
+     * Push data into the parser and extract complete frames.
+     *
+     * @param data - Incoming data buffer
+     * @returns Array of parsed envelope frames
+     */
+    push(data) {
+        const spaceAtEnd = this.capacity - this.tail;
+        if (data.length > spaceAtEnd) {
+            this.compact();
+            if (data.length > this.capacity - this.tail) {
+                throw new Error(`Buffer overflow: data ${data.length} exceeds capacity`);
+            }
+        }
+        data.copy(this.ring, this.tail);
+        this.tail += data.length;
+        return this.extractFrames();
+    }
+    extractFrames() {
+        const frames = [];
+        const headerSize = this.legacyMode ? LEGACY_HEADER_SIZE : HEADER_SIZE;
+        while (this.pendingBytes >= headerSize) {
+            let formatByte = FORMAT_JSON;
+            let frameLength;
+            if (this.legacyMode) {
+                frameLength = this.ring.readUInt32BE(this.head);
+            }
+            else {
+                formatByte = this.ring.readUInt8(this.head);
+                frameLength = this.ring.readUInt32BE(this.head + 1);
+            }
+            if (frameLength > this.maxFrameBytes) {
+                throw new Error(`Frame too large: ${frameLength} > ${this.maxFrameBytes}`);
+            }
+            const totalLength = headerSize + frameLength;
+            if (this.pendingBytes < totalLength) {
+                break;
+            }
+            const payloadStart = this.head + headerSize;
+            const payloadEnd = this.head + totalLength;
+            let envelope;
+            try {
+                envelope = this.decodePayload(formatByte, payloadStart, payloadEnd);
+            }
+            catch (err) {
+                throw new Error(`Invalid frame payload: ${err}`);
+            }
+            this.head += totalLength;
+            frames.push(envelope);
+        }
+        if (this.head > this.capacity / 2 && this.pendingBytes < this.capacity / 4) {
+            this.compact();
+        }
+        return frames;
+    }
+    decodePayload(formatByte, start, end) {
+        if (formatByte === FORMAT_MSGPACK && msgpack) {
+            return msgpack.decode(this.ring.subarray(start, end));
+        }
+        else {
+            return JSON.parse(this.ring.toString('utf-8', start, end));
+        }
+    }
+    compact() {
+        if (this.head === 0)
+            return;
+        const unread = this.pendingBytes;
+        if (unread > 0) {
+            this.ring.copy(this.ring, 0, this.head, this.tail);
+        }
+        this.head = 0;
+        this.tail = unread;
+    }
+    /**
+     * Reset parser state.
+     */
+    reset() {
+        this.head = 0;
+        this.tail = 0;
+    }
+}
+//# sourceMappingURL=framing.js.map

package/packages/sdk/dist/protocol/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Protocol exports for @agent-relay/sdk
+ */
+export { PROTOCOL_VERSION, type MessageType, type PayloadKind, type Envelope, type EntityType, type HelloPayload, type WelcomePayload, type SendPayload, type SendMeta, type SyncMeta, type DeliveryInfo, type AckPayload, type NackPayload, type BusyPayload, type PingPayload, type PongPayload, type ErrorCode, type ErrorPayload, type LogPayload, type SyncStream, type SyncPayload, type SpeakOnTrigger, type ShadowConfig, type ShadowBindPayload, type ShadowUnbindPayload, type SpawnPayload, type SpawnPolicyDecision, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type MessageAttachment, type ChannelJoinPayload, type ChannelLeavePayload, type ChannelMessagePayload, type HelloEnvelope, type WelcomeEnvelope, type SendEnvelope, type DeliverEnvelope, type AckEnvelope, type NackEnvelope, type PingEnvelope, type PongEnvelope, type ErrorEnvelope, type BusyEnvelope, type LogEnvelope, type SyncEnvelope, type ShadowBindEnvelope, type ShadowUnbindEnvelope, type SpawnEnvelope, type SpawnResultEnvelope, type ReleaseEnvelope, type ReleaseResultEnvelope, type ChannelJoinEnvelope, type ChannelLeaveEnvelope, type ChannelMessageEnvelope, } from './types.js';
+export { MAX_FRAME_BYTES, HEADER_SIZE, LEGACY_HEADER_SIZE, type WireFormat, initMessagePack, hasMessagePack, encodeFrame, encodeFrameLegacy, FrameParser, } from './framing.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/protocol/index.js

@@ -0,0 +1,6 @@
+/**
+ * Protocol exports for @agent-relay/sdk
+ */
+export { PROTOCOL_VERSION, } from './types.js';
+export { MAX_FRAME_BYTES, HEADER_SIZE, LEGACY_HEADER_SIZE, initMessagePack, hasMessagePack, encodeFrame, encodeFrameLegacy, FrameParser, } from './framing.js';
+//# sourceMappingURL=index.js.map