@agent-relay/sdk 2.3.4 → 2.3.5

package/dist/browser-client.js

@@ -1,750 +0,0 @@
-/**
- * BrowserRelayClient - Browser-compatible Agent Relay SDK Client
- * @agent-relay/sdk
- *
- * A client designed for browser environments using WebSocket transport.
- * Can also be used in Node.js with the WebSocket transport.
- *
- * Key differences from RelayClient:
- * - Uses transport abstraction instead of direct socket access
- * - No Node.js-specific dependencies (node:net, node:crypto)
- * - Uses browser-compatible APIs (crypto.randomUUID, etc.)
- */
-import { createAutoTransport, } from './transports/index.js';
-import { PROTOCOL_VERSION, } from '@agent-relay/protocol';
-import { encodeFrameLegacyBrowser, BrowserFrameParser } from './browser-framing.js';
-const DEFAULT_CONFIG = {
-    agentName: 'agent',
-    quiet: false,
-    reconnect: true,
-    maxReconnectAttempts: 10,
-    reconnectDelayMs: 1000,
-    reconnectMaxDelayMs: 30000,
-};
-// Simple ID generator (browser-compatible)
-let idCounter = 0;
-function generateId() {
-    return `${Date.now().toString(36)}-${(++idCounter).toString(36)}`;
-}
-// Browser-compatible UUID generator
-function generateUUID() {
-    // Use crypto.randomUUID if available (modern browsers)
-    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-        return crypto.randomUUID();
-    }
-    // Fallback: simple UUID v4 implementation
-    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === 'x' ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });
-}
-/**
- * Circular buffer for O(1) deduplication with bounded memory.
- */
-class CircularDedupeCache {
-    ids = new Set();
-    ring;
-    head = 0;
-    capacity;
-    constructor(capacity = 2000) {
-        this.capacity = capacity;
-        this.ring = new Array(capacity);
-    }
-    check(id) {
-        if (this.ids.has(id))
-            return true;
-        if (this.ids.size >= this.capacity) {
-            const oldest = this.ring[this.head];
-            if (oldest)
-                this.ids.delete(oldest);
-        }
-        this.ring[this.head] = id;
-        this.ids.add(id);
-        this.head = (this.head + 1) % this.capacity;
-        return false;
-    }
-    clear() {
-        this.ids.clear();
-        this.ring = new Array(this.capacity);
-        this.head = 0;
-    }
-}
-/**
- * BrowserRelayClient - A browser-compatible relay client.
- *
- * Uses WebSocket transport by default, making it compatible with browsers.
- * Can also be used in Node.js for WebSocket-based connections.
- *
- * @example Browser usage
- * ```typescript
- * import { BrowserRelayClient } from '@agent-relay/sdk/browser';
- *
- * const client = new BrowserRelayClient({
- *   agentName: 'MyAgent',
- *   transport: {
- *     wsUrl: 'wss://relay.example.com/ws',
- *   },
- * });
- *
- * await client.connect();
- *
- * client.onMessage = (from, payload) => {
- *   console.log(`Message from ${from}: ${payload.body}`);
- * };
- *
- * client.sendMessage('OtherAgent', 'Hello!');
- * ```
- */
-export class BrowserRelayClient {
-    config;
-    transport;
-    parser;
-    _state = 'DISCONNECTED';
-    sessionId;
-    resumeToken;
-    reconnectAttempts = 0;
-    reconnectDelay;
-    reconnectTimer;
-    _destroyed = false;
-    dedupeCache = new CircularDedupeCache(2000);
-    writeQueue = [];
-    writeScheduled = false;
-    pendingSyncAcks = new Map();
-    pendingRequests = new Map();
-    // Event handlers
-    onMessage;
-    onChannelMessage;
-    onStateChange;
-    onError;
-    constructor(config) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
-        this.parser = new BrowserFrameParser(); // Always uses legacy mode (4-byte header, JSON only)
-        this.reconnectDelay = this.config.reconnectDelayMs ?? DEFAULT_CONFIG.reconnectDelayMs;
-    }
-    get state() {
-        return this._state;
-    }
-    get agentName() {
-        return this.config.agentName;
-    }
-    get currentSessionId() {
-        return this.sessionId;
-    }
-    /**
-     * Connect to the relay daemon.
-     */
-    async connect() {
-        if (this._state !== 'DISCONNECTED' && this._state !== 'BACKOFF') {
-            return;
-        }
-        this.setState('CONNECTING');
-        // Create transport if not provided
-        if (!this.transport) {
-            if (this.config.transportInstance) {
-                this.transport = this.config.transportInstance;
-            }
-            else if (this.config.transport) {
-                this.transport = createAutoTransport(this.config.transport);
-            }
-            else {
-                throw new Error('Transport configuration required. Provide either transport options or transportInstance.');
-            }
-        }
-        // Set up transport events
-        this.transport.setEvents({
-            onConnect: () => {
-                this.setState('HANDSHAKING');
-                this.sendHello();
-            },
-            onData: (data) => this.handleData(data),
-            onClose: () => this.handleDisconnect(),
-            onError: (err) => this.handleError(err),
-        });
-        try {
-            await this.transport.connect();
-            // Wait for READY state
-            await new Promise((resolve, reject) => {
-                let checkReady;
-                const cleanup = () => {
-                    clearInterval(checkReady);
-                    clearTimeout(timeout);
-                };
-                const timeout = setTimeout(() => {
-                    cleanup();
-                    reject(new Error('Connection handshake timeout'));
-                }, 5000);
-                checkReady = setInterval(() => {
-                    if (this._state === 'READY') {
-                        cleanup();
-                        resolve();
-                    }
-                    else if (this._state === 'DISCONNECTED') {
-                        cleanup();
-                        reject(new Error('Connection failed'));
-                    }
-                }, 10);
-            });
-        }
-        catch (err) {
-            this.setState('DISCONNECTED');
-            throw err;
-        }
-    }
-    /**
-     * Disconnect from the relay daemon.
-     */
-    disconnect() {
-        if (this.reconnectTimer) {
-            clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = undefined;
-        }
-        if (this.transport) {
-            // Send BYE message
-            this.send({
-                v: PROTOCOL_VERSION,
-                type: 'BYE',
-                id: generateId(),
-                ts: Date.now(),
-                payload: {},
-            });
-            this.transport.disconnect();
-            this.transport = undefined;
-        }
-        this.setState('DISCONNECTED');
-    }
-    /**
-     * Permanently destroy the client.
-     */
-    destroy() {
-        this._destroyed = true;
-        this.disconnect();
-    }
-    /**
-     * Send a message to another agent.
-     */
-    sendMessage(to, body, kind = 'message', data, thread, meta) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'SEND',
-            id: generateId(),
-            ts: Date.now(),
-            to,
-            payload: {
-                kind,
-                body,
-                data,
-                thread,
-            },
-            payload_meta: meta,
-        };
-        return this.send(envelope);
-    }
-    /**
-     * Send an ACK for a delivered message.
-     */
-    sendAck(payload) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'ACK',
-            id: generateId(),
-            ts: Date.now(),
-            payload,
-        };
-        return this.send(envelope);
-    }
-    /**
-     * Send a request to another agent and wait for their response.
-     */
-    async request(to, body, options = {}) {
-        if (this._state !== 'READY') {
-            throw new Error('Client not ready');
-        }
-        const correlationId = generateUUID();
-        const timeoutMs = options.timeout ?? 30000;
-        const kind = options.kind ?? 'message';
-        return new Promise((resolve, reject) => {
-            const timeoutHandle = setTimeout(() => {
-                this.pendingRequests.delete(correlationId);
-                reject(new Error(`Request timeout after ${timeoutMs}ms waiting for response from ${to}`));
-            }, timeoutMs);
-            this.pendingRequests.set(correlationId, {
-                resolve,
-                reject,
-                timeoutHandle,
-                targetAgent: to,
-            });
-            const envelope = {
-                v: PROTOCOL_VERSION,
-                type: 'SEND',
-                id: generateId(),
-                ts: Date.now(),
-                to,
-                payload: {
-                    kind,
-                    body,
-                    data: {
-                        ...options.data,
-                        _correlationId: correlationId,
-                    },
-                    thread: options.thread,
-                },
-                payload_meta: {
-                    replyTo: correlationId,
-                },
-            };
-            const sent = this.send(envelope);
-            if (!sent) {
-                clearTimeout(timeoutHandle);
-                this.pendingRequests.delete(correlationId);
-                reject(new Error('Failed to send request'));
-            }
-        });
-    }
-    /**
-     * Respond to a request from another agent.
-     */
-    respond(correlationId, to, body, data) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'SEND',
-            id: generateId(),
-            ts: Date.now(),
-            to,
-            payload: {
-                kind: 'message',
-                body,
-                data: {
-                    ...data,
-                    _correlationId: correlationId,
-                    _isResponse: true,
-                },
-            },
-            payload_meta: {
-                replyTo: correlationId,
-            },
-        };
-        return this.send(envelope);
-    }
-    /**
-     * Broadcast a message to all agents.
-     */
-    broadcast(body, kind = 'message', data) {
-        return this.sendMessage('*', body, kind, data);
-    }
-    /**
-     * Bind as a shadow to a primary agent.
-     */
-    bindAsShadow(primaryAgent, options = {}) {
-        if (this._state !== 'READY')
-            return false;
-        return this.send({
-            v: PROTOCOL_VERSION,
-            type: 'SHADOW_BIND',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                primaryAgent,
-                speakOn: options.speakOn,
-                receiveIncoming: options.receiveIncoming,
-                receiveOutgoing: options.receiveOutgoing,
-            },
-        });
-    }
-    /**
-     * Unbind from a primary agent.
-     */
-    unbindAsShadow(primaryAgent) {
-        if (this._state !== 'READY')
-            return false;
-        return this.send({
-            v: PROTOCOL_VERSION,
-            type: 'SHADOW_UNBIND',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                primaryAgent,
-            },
-        });
-    }
-    /**
-     * Send log output to the daemon.
-     */
-    sendLog(data) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'LOG',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                data,
-                timestamp: Date.now(),
-            },
-        };
-        return this.send(envelope);
-    }
-    // =============================================================================
-    // Channel Operations
-    // =============================================================================
-    /**
-     * Join a channel.
-     */
-    joinChannel(channel, displayName) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'CHANNEL_JOIN',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                channel,
-                displayName,
-            },
-        };
-        return this.send(envelope);
-    }
-    /**
-     * Leave a channel.
-     */
-    leaveChannel(channel, reason) {
-        if (this._state !== 'READY')
-            return false;
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'CHANNEL_LEAVE',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                channel,
-                reason,
-            },
-        };
-        return this.send(envelope);
-    }
-    /**
-     * Send a message to a channel.
-     */
-    sendChannelMessage(channel, body, options) {
-        if (this._state !== 'READY') {
-            return false;
-        }
-        const envelope = {
-            v: PROTOCOL_VERSION,
-            type: 'CHANNEL_MESSAGE',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                channel,
-                body,
-                thread: options?.thread,
-                mentions: options?.mentions,
-                attachments: options?.attachments,
-                data: options?.data,
-            },
-        };
-        return this.send(envelope);
-    }
-    // =============================================================================
-    // Private Methods
-    // =============================================================================
-    setState(state) {
-        this._state = state;
-        if (this.onStateChange) {
-            this.onStateChange(state);
-        }
-    }
-    sendHello() {
-        const hello = {
-            v: PROTOCOL_VERSION,
-            type: 'HELLO',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                agent: this.config.agentName,
-                entityType: this.config.entityType,
-                cli: this.config.cli,
-                displayName: this.config.displayName,
-                avatarUrl: this.config.avatarUrl,
-                capabilities: {
-                    ack: true,
-                    resume: true,
-                    max_inflight: 256,
-                    supports_topics: true,
-                },
-                session: this.resumeToken ? { resume_token: this.resumeToken } : undefined,
-            },
-        };
-        this.send(hello);
-    }
-    send(envelope) {
-        if (!this.transport || this.transport.state !== 'connected') {
-            return false;
-        }
-        try {
-            const frame = encodeFrameLegacyBrowser(envelope);
-            this.writeQueue.push(frame);
-            if (!this.writeScheduled) {
-                this.writeScheduled = true;
-                // Use setTimeout(0) for browser compatibility (instead of setImmediate)
-                setTimeout(() => this.flushWrites(), 0);
-            }
-            return true;
-        }
-        catch (err) {
-            this.handleError(err);
-            return false;
-        }
-    }
-    flushWrites() {
-        this.writeScheduled = false;
-        if (this.writeQueue.length === 0 || !this.transport)
-            return;
-        // Concatenate all buffers
-        const totalLength = this.writeQueue.reduce((sum, buf) => sum + buf.length, 0);
-        const combined = new Uint8Array(totalLength);
-        let offset = 0;
-        for (const buf of this.writeQueue) {
-            combined.set(buf, offset);
-            offset += buf.length;
-        }
-        this.transport.send(combined);
-        this.writeQueue = [];
-    }
-    handleData(data) {
-        try {
-            const frames = this.parser.push(data);
-            for (const frame of frames) {
-                this.processFrame(frame);
-            }
-        }
-        catch (err) {
-            this.handleError(err);
-        }
-    }
-    processFrame(envelope) {
-        switch (envelope.type) {
-            case 'WELCOME':
-                this.handleWelcome(envelope);
-                break;
-            case 'DELIVER':
-                this.handleDeliver(envelope);
-                break;
-            case 'CHANNEL_MESSAGE':
-                this.handleChannelMessage(envelope);
-                break;
-            case 'PING':
-                this.handlePing(envelope);
-                break;
-            case 'ACK':
-                this.handleAck(envelope);
-                break;
-            case 'ERROR':
-                this.handleErrorFrame(envelope);
-                break;
-            case 'BUSY':
-                if (!this.config.quiet) {
-                    console.warn('[sdk] Server busy, backing off');
-                }
-                break;
-        }
-    }
-    handleWelcome(envelope) {
-        this.sessionId = envelope.payload.session_id;
-        this.resumeToken = envelope.payload.resume_token;
-        this.reconnectAttempts = 0;
-        this.reconnectDelay = this.config.reconnectDelayMs ?? DEFAULT_CONFIG.reconnectDelayMs;
-        this.setState('READY');
-        if (!this.config.quiet) {
-            console.log(`[sdk] Connected as ${this.config.agentName} (session: ${this.sessionId})`);
-        }
-    }
-    handleDeliver(envelope) {
-        // Send ACK
-        this.send({
-            v: PROTOCOL_VERSION,
-            type: 'ACK',
-            id: generateId(),
-            ts: Date.now(),
-            payload: {
-                ack_id: envelope.id,
-                seq: envelope.delivery.seq,
-            },
-        });
-        const duplicate = this.dedupeCache.check(envelope.id);
-        if (duplicate) {
-            return;
-        }
-        // Check if this is a response to a pending request
-        const correlationId = this.extractCorrelationId(envelope);
-        if (correlationId && envelope.from) {
-            const pending = this.pendingRequests.get(correlationId);
-            if (pending) {
-                clearTimeout(pending.timeoutHandle);
-                this.pendingRequests.delete(correlationId);
-                pending.resolve({
-                    from: envelope.from,
-                    body: envelope.payload.body,
-                    data: envelope.payload.data,
-                    correlationId,
-                    thread: envelope.payload.thread,
-                    payload: envelope.payload,
-                });
-            }
-        }
-        if (this.onMessage && envelope.from) {
-            this.onMessage(envelope.from, envelope.payload, envelope.id, envelope.payload_meta, envelope.delivery.originalTo);
-        }
-    }
-    extractCorrelationId(envelope) {
-        if (envelope.payload_meta?.replyTo) {
-            return envelope.payload_meta.replyTo;
-        }
-        if (envelope.payload.data && typeof envelope.payload.data._correlationId === 'string') {
-            return envelope.payload.data._correlationId;
-        }
-        return undefined;
-    }
-    handleChannelMessage(envelope) {
-        const duplicate = this.dedupeCache.check(envelope.id);
-        if (duplicate) {
-            return;
-        }
-        if (this.onChannelMessage && envelope.from) {
-            this.onChannelMessage(envelope.from, envelope.payload.channel, envelope.payload.body, envelope);
-        }
-        // Also call onMessage for backwards compatibility
-        if (this.onMessage && envelope.from) {
-            const sendPayload = {
-                kind: 'message',
-                body: envelope.payload.body,
-                data: {
-                    _isChannelMessage: true,
-                    _channel: envelope.payload.channel,
-                    _mentions: envelope.payload.mentions,
-                },
-                thread: envelope.payload.thread,
-            };
-            this.onMessage(envelope.from, sendPayload, envelope.id, undefined, envelope.payload.channel);
-        }
-    }
-    handleAck(envelope) {
-        const correlationId = envelope.payload.correlationId;
-        if (!correlationId)
-            return;
-        const pending = this.pendingSyncAcks.get(correlationId);
-        if (!pending)
-            return;
-        clearTimeout(pending.timeoutHandle);
-        this.pendingSyncAcks.delete(correlationId);
-        pending.resolve(envelope.payload);
-    }
-    handlePing(envelope) {
-        this.send({
-            v: PROTOCOL_VERSION,
-            type: 'PONG',
-            id: generateId(),
-            ts: Date.now(),
-            payload: envelope.payload ?? {},
-        });
-    }
-    handleErrorFrame(envelope) {
-        if (!this.config.quiet) {
-            console.error('[sdk] Server error:', envelope.payload);
-        }
-        if (envelope.payload.code === 'RESUME_TOO_OLD') {
-            this.resumeToken = undefined;
-            this.sessionId = undefined;
-        }
-        if (envelope.payload.fatal) {
-            if (!this.config.quiet) {
-                console.error('[sdk] Fatal error received, will not reconnect:', envelope.payload.message);
-            }
-            this._destroyed = true;
-        }
-    }
-    handleDisconnect() {
-        this.parser.reset();
-        this.transport = undefined;
-        this.rejectPendingSyncAcks(new Error('Disconnected while awaiting ACK'));
-        this.rejectPendingRequests(new Error('Disconnected while awaiting request response'));
-        if (this._destroyed) {
-            this.setState('DISCONNECTED');
-            return;
-        }
-        if (this.config.reconnect && this.reconnectAttempts < (this.config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts)) {
-            this.scheduleReconnect();
-        }
-        else {
-            this.setState('DISCONNECTED');
-            if (this.reconnectAttempts >= (this.config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts) && !this.config.quiet) {
-                console.error(`[sdk] Max reconnect attempts reached (${this.config.maxReconnectAttempts}), giving up`);
-            }
-        }
-    }
-    handleError(error) {
-        if (!this.config.quiet) {
-            console.error('[sdk] Error:', error.message);
-        }
-        if (this.onError) {
-            this.onError(error);
-        }
-    }
-    rejectPendingSyncAcks(error) {
-        for (const [correlationId, pending] of this.pendingSyncAcks.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingSyncAcks.delete(correlationId);
-        }
-    }
-    rejectPendingRequests(error) {
-        for (const [correlationId, pending] of this.pendingRequests.entries()) {
-            clearTimeout(pending.timeoutHandle);
-            pending.reject(error);
-            this.pendingRequests.delete(correlationId);
-        }
-    }
-    scheduleReconnect() {
-        // Cannot reconnect when using transportInstance - we can't recreate an
-        // externally-provided transport. Users must handle reconnection themselves
-        // or use transport options instead.
-        if (!this.config.transport && this.config.transportInstance) {
-            if (!this.config.quiet) {
-                console.warn('[sdk] Cannot auto-reconnect with transportInstance. ' +
-                    'Use transport options instead, or handle reconnection manually.');
-            }
-            this.setState('DISCONNECTED');
-            return;
-        }
-        this.setState('BACKOFF');
-        this.reconnectAttempts++;
-        const jitter = Math.random() * 0.3 + 0.85;
-        const maxDelay = this.config.reconnectMaxDelayMs ?? DEFAULT_CONFIG.reconnectMaxDelayMs;
-        const delay = Math.min(this.reconnectDelay * jitter, maxDelay);
-        this.reconnectDelay *= 2;
-        if (!this.config.quiet) {
-            console.log(`[sdk] Reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempts})`);
-        }
-        this.reconnectTimer = setTimeout(() => {
-            // Re-create transport for reconnection
-            if (this.config.transport) {
-                this.transport = createAutoTransport(this.config.transport);
-            }
-            this.connect().catch(() => { });
-        }, delay);
-    }
-}
-//# sourceMappingURL=browser-client.js.map