@swarm-agent/sdk 0.1.47 → 0.1.48

package/dist/browser.js

@@ -0,0 +1,408 @@
+import { confirmPermissionResolution, permissionId as validatePermissionId, permissionResolutionBody, PermissionResolutionError } from './permission-ui.js';
+export * from './permission-ui.js';
+/**
+ * Universal browser-side WebSocket client for Swarm.
+ * Hooks directly into the Swarm WebSocket Bridge with typed callbacks for live
+ * assistant tokens, model reasoning deltas, real-time tool events, and permission approvals.
+ */
+export class SwarmBrowserChat {
+    options;
+    ws = null;
+    currentSessionId = null;
+    isDisposed = false;
+    reconnectAttempts = 0;
+    reconnectTimer;
+    subscribedSessionId = null;
+    permissionsLive = false;
+    cancelSubscription;
+    connectPromise = null;
+    listeners = new Map();
+    pendingPermissions = new Map();
+    decisions = new Map();
+    get permissions() { return [...this.pendingPermissions.values()]; }
+    rejectDecisions(message) {
+        for (const [key, decision] of this.decisions) {
+            clearTimeout(decision.timer);
+            this.decisions.delete(key);
+            const error = new Error(message);
+            decision.reject(error);
+            this.emit('permission_error', decision.permissionId, error);
+        }
+    }
+    removePermission(id) {
+        if (this.pendingPermissions.delete(id)) {
+            this.emit('permission_removed', id);
+            this.emit('permissions', this.permissions);
+        }
+    }
+    constructor(options = {}) {
+        this.options = options;
+        if (options.autoConnect !== false) {
+            void this.connect().catch(() => { });
+        }
+    }
+    get sessionId() { return this.currentSessionId; }
+    get isSubscribed() { return this.isConnected && !!this.currentSessionId && this.subscribedSessionId === this.currentSessionId; }
+    get isConnected() {
+        return this.ws !== null && this.ws.readyState === 1; // 1 = OPEN
+    }
+    resolveUrl() {
+        if (this.options.url)
+            return this.options.url;
+        if (typeof location !== 'undefined') {
+            const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            return `${proto}//${location.host}/ws`;
+        }
+        return 'ws://localhost:3456/ws';
+    }
+    /**
+     * Connects to the Swarm WebSocket Bridge. Returns a Promise that resolves when connected.
+     */
+    async connect() {
+        if (this.isDisposed)
+            throw new Error('Chat client disposed');
+        if (this.isConnected)
+            return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.connectPromise = new Promise((resolve, reject) => {
+            try {
+                const targetUrl = this.resolveUrl();
+                const WsClass = this.options.webSocketClass || (typeof WebSocket !== 'undefined' ? WebSocket : null);
+                if (!WsClass) {
+                    throw new Error('No WebSocket implementation available. In Node.js environments, pass webSocketClass in options.');
+                }
+                const socket = new WsClass(targetUrl);
+                this.ws = socket;
+                let hasOpened = false;
+                socket.onopen = () => {
+                    hasOpened = true;
+                    this.reconnectAttempts = 0;
+                    if (this.currentSessionId) {
+                        this.send({ type: 'subscribe', sessionId: this.currentSessionId });
+                    }
+                    resolve();
+                };
+                socket.onmessage = (event) => {
+                    if (this.ws !== socket)
+                        return;
+                    try {
+                        const raw = typeof event.data === 'string' ? event.data : event.data?.toString('utf8');
+                        const msg = JSON.parse(raw);
+                        this.handleServerMessage(msg);
+                    }
+                    catch (error) {
+                        this.emit('error', error instanceof Error ? error.message : 'Malformed server frame');
+                    }
+                };
+                socket.onclose = () => {
+                    if (this.ws !== socket)
+                        return;
+                    this.ws = null;
+                    this.subscribedSessionId = null;
+                    this.permissionsLive = false;
+                    this.rejectDecisions('Disconnected before permission acknowledgement; outcome unknown. Reconnect and review pending requests before retrying.');
+                    this.emit('disconnected');
+                    if (!hasOpened) {
+                        reject(new Error('WebSocket closed before opening'));
+                    }
+                    this.maybeReconnect();
+                };
+                socket.onerror = (err) => {
+                    this.emit('disconnected');
+                    if (!hasOpened) {
+                        reject(err instanceof Error ? err : new Error('WebSocket connection error'));
+                    }
+                };
+            }
+            catch (err) {
+                this.emit('error', err.message);
+                this.maybeReconnect();
+                reject(err);
+            }
+        }).finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    maybeReconnect() {
+        if (this.isDisposed || this.options.autoReconnect === false || this.reconnectTimer)
+            return;
+        const max = this.options.maxReconnectAttempts ?? 10;
+        if (this.reconnectAttempts >= max)
+            return;
+        const delay = Math.min(500 * Math.pow(1.5, this.reconnectAttempts++), 10_000);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (!this.isDisposed) {
+                void this.connect().catch(() => { });
+            }
+        }, delay);
+    }
+    handleServerMessage(msg) {
+        if (msg.sessionId && msg.sessionId !== this.currentSessionId)
+            return;
+        switch (msg.type) {
+            case 'connected':
+                this.emit('connected');
+                break;
+            case 'state':
+                if (msg.state) {
+                    this.permissionsLive = msg.state.status === 'live';
+                    const rawPending = msg.state.snapshot.session_views_by_id?.[this.currentSessionId]?.pending_permissions;
+                    const pending = rawPending === null ? [] : rawPending;
+                    if (this.permissionsLive && Array.isArray(pending)) {
+                        if (pending.some(p => !p || typeof p.id !== 'string' || !p.id || p.session_id !== this.currentSessionId)) {
+                            this.permissionsLive = false;
+                            throw new Error('Invalid pending permission snapshot; refresh the conversation');
+                        }
+                        const records = pending.filter(p => p && p.session_id === this.currentSessionId && p.status === 'pending');
+                        const ids = new Set(records.map(p => p.id));
+                        for (const id of this.pendingPermissions.keys())
+                            if (!ids.has(id))
+                                this.removePermission(id);
+                        for (const p of records)
+                            this.pendingPermissions.set(p.id, p);
+                        this.emit('permissions', this.permissions);
+                    }
+                    this.emit('state', msg.state);
+                }
+                break;
+            case 'accepted':
+                this.emit('accepted', msg.requestId ?? '');
+                break;
+            case 'subscribed':
+                if (msg.sessionId) {
+                    this.subscribedSessionId = msg.sessionId;
+                    this.emit('subscribed', msg.sessionId);
+                }
+                break;
+            case 'unsubscribed':
+                this.emit('unsubscribed');
+                break;
+            case 'text':
+                this.emit('text', msg.delta || '', msg.fullText || '');
+                break;
+            case 'reasoning':
+                this.emit('reasoning', msg.delta || '', msg.fullText || '');
+                break;
+            case 'tool_start':
+                if (msg.tool)
+                    this.emit('tool_start', msg.tool);
+                break;
+            case 'tool_delta':
+                if (msg.tool)
+                    this.emit('tool_delta', msg.tool, msg.delta || '');
+                break;
+            case 'tool_done':
+                if (msg.tool)
+                    this.emit('tool_done', msg.tool);
+                break;
+            case 'tool_permission':
+                if (msg.permission && msg.permission.session_id === this.currentSessionId && msg.permission.status === 'pending') {
+                    this.pendingPermissions.set(msg.permission.id, msg.permission);
+                    this.emit('tool_permission', msg.permission);
+                    this.emit('permissions', this.permissions);
+                }
+                break;
+            case 'permission_resolved': {
+                const decision = msg.requestId ? this.decisions.get(msg.requestId) : undefined;
+                if (!decision || msg.sessionId !== decision.sessionId || msg.permissionId !== decision.permissionId)
+                    break;
+                clearTimeout(decision.timer);
+                this.decisions.delete(msg.requestId);
+                try {
+                    const result = confirmPermissionResolution(msg.result, decision.sessionId, decision.permissionId, decision.action, decision.options);
+                    this.removePermission(decision.permissionId);
+                    decision.resolve(result);
+                    this.emit('permission_resolved', decision.permissionId, result);
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    decision.reject(err);
+                    this.emit('permission_error', decision.permissionId, err);
+                }
+                break;
+            }
+            case 'permission_removed':
+                if (msg.permissionId)
+                    this.removePermission(msg.permissionId);
+                break;
+            case 'permission_error': {
+                const decision = msg.requestId ? this.decisions.get(msg.requestId) : undefined;
+                const result = msg.result?.session_id === this.currentSessionId && msg.result?.permission?.id === msg.permissionId ? msg.result : undefined;
+                const error = new PermissionResolutionError(msg.error || 'Permission resolution failed; refresh before retrying', result);
+                if (decision && msg.sessionId === decision.sessionId && msg.permissionId === decision.permissionId) {
+                    clearTimeout(decision.timer);
+                    this.decisions.delete(msg.requestId);
+                    decision.reject(error);
+                }
+                this.emit('permission_error', msg.permissionId ?? '', error);
+                break;
+            }
+            case 'done':
+                this.emit('done', msg.messages || []);
+                break;
+            case 'error':
+                this.emit('error', msg.error || 'Unknown error');
+                break;
+        }
+    }
+    send(msg) {
+        if (!this.isConnected)
+            throw new Error('Chat disconnected; reconnect and subscribe before sending');
+        this.ws.send(JSON.stringify(msg));
+    }
+    /**
+     * Subscribes to real-time events for a specific session.
+     * Returns a promise that resolves once the session subscription is acknowledged.
+     */
+    async subscribe(sessionId, autoApprovePermissions) {
+        if (typeof sessionId !== 'string' || !sessionId.trim()) {
+            throw new Error('sessionId must be a non-empty string; create or select a conversation before subscribing');
+        }
+        sessionId = sessionId.trim();
+        this.cancelSubscription?.('Subscription superseded');
+        this.rejectDecisions('Subscription changed before permission acknowledgement; outcome unknown');
+        if (this.currentSessionId !== sessionId) {
+            this.permissionsLive = false;
+            this.pendingPermissions.clear();
+            this.emit('permissions', []);
+        }
+        this.currentSessionId = sessionId;
+        this.subscribedSessionId = null;
+        await this.connect();
+        if (this.currentSessionId !== sessionId)
+            throw new Error('Subscription superseded');
+        return new Promise((resolve, reject) => {
+            const cleanup = () => { clearTimeout(timer); unsub(); offError(); offClose(); this.cancelSubscription = undefined; };
+            const fail = (error) => { cleanup(); reject(new Error(error)); };
+            const unsub = this.on('subscribed', (subId) => {
+                if (subId === sessionId) {
+                    cleanup();
+                    resolve(subId);
+                }
+            });
+            const offError = this.on('error', fail);
+            const offClose = this.on('disconnected', () => fail('Disconnected before subscription acknowledgement'));
+            this.cancelSubscription = fail;
+            const timer = setTimeout(() => fail('Subscription acknowledgement timed out'), this.options.subscribeTimeoutMs ?? 45_000);
+            try {
+                this.send({ type: 'subscribe', sessionId, autoApprovePermissions });
+            }
+            catch (error) {
+                fail(error instanceof Error ? error.message : String(error));
+            }
+        });
+    }
+    /** Unsubscribes from active session streaming */
+    unsubscribe() {
+        this.cancelSubscription?.('Unsubscribed');
+        this.rejectDecisions('Unsubscribed before permission acknowledgement; outcome unknown');
+        this.pendingPermissions.clear();
+        this.emit('permissions', []);
+        this.currentSessionId = null;
+        this.subscribedSessionId = null;
+        if (this.isConnected)
+            this.send({ type: 'unsubscribe' });
+    }
+    /** Sends a chat message over the WebSocket */
+    sendMessage(message, sessionId, autoApprovePermissions, requestId) {
+        const targetSession = sessionId || this.currentSessionId;
+        if (!targetSession) {
+            throw new Error('No active session. Call subscribe(sessionId) or provide sessionId');
+        }
+        if (!this.isSubscribed || targetSession !== this.currentSessionId)
+            throw new Error('Await subscribe(sessionId) before sending');
+        const id = requestId ?? globalThis.crypto.randomUUID();
+        this.send({
+            type: 'chat_message',
+            requestId: id,
+            sessionId: targetSession,
+            message,
+            autoApprovePermissions,
+        });
+        return id;
+    }
+    /** Resolve only after a user gesture. Await confirmation; on failure keep the form recoverable. */
+    async resolvePermission(permissionId, action, options = {}) {
+        permissionId = validatePermissionId(permissionId);
+        permissionResolutionBody(action, options);
+        const targetSession = options.sessionId === undefined ? this.currentSessionId : validatePermissionId(options.sessionId, 'sessionId');
+        if (!this.isSubscribed || !targetSession || targetSession !== this.currentSessionId)
+            throw new Error('Await subscribe(sessionId) before resolving permissions');
+        if (!this.permissionsLive)
+            throw new Error('Permission state is reconnecting; wait for fresh hydration');
+        if (!this.pendingPermissions.has(permissionId))
+            throw new Error('Permission is not pending in this conversation; refresh before replying');
+        if ([...this.decisions.values()].some(d => d.permissionId === permissionId))
+            throw new Error('Permission resolution already in flight');
+        const requestId = globalThis.crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.decisions.delete(requestId);
+                this.permissionsLive = false;
+                const error = new Error('Permission acknowledgement timed out; outcome unknown. Refresh before retrying.');
+                reject(error);
+                this.emit('permission_error', permissionId, error);
+            }, this.options.permissionTimeoutMs ?? 45_000);
+            this.decisions.set(requestId, { permissionId, sessionId: targetSession, action, options, resolve, reject, timer });
+            try {
+                this.send({ type: 'resolve_permission', sessionId: targetSession, permissionId, action, requestId,
+                    reason: options.reason, approvedArguments: options.approvedArguments });
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.decisions.delete(requestId);
+                reject(error);
+            }
+        });
+    }
+    on(event, handler) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(handler);
+        // If already connected and listener is for connected, fire immediately
+        if (event === 'connected' && this.isConnected) {
+            setTimeout(() => handler(), 0);
+        }
+        return () => this.off(event, handler);
+    }
+    off(event, handler) {
+        const handlers = this.listeners.get(event);
+        if (handlers)
+            handlers.delete(handler);
+    }
+    emit(event, ...args) {
+        const handlers = this.listeners.get(event);
+        if (handlers) {
+            for (const h of handlers) {
+                try {
+                    h(...args);
+                }
+                catch { }
+            }
+        }
+    }
+    /** Closes and disposes the WebSocket connection */
+    dispose() {
+        this.isDisposed = true;
+        this.rejectDecisions('Client disposed before permission acknowledgement; outcome unknown');
+        clearTimeout(this.reconnectTimer);
+        this.emit('disconnected');
+        if (this.ws) {
+            try {
+                if (typeof this.ws.terminate === 'function') {
+                    this.ws.terminate();
+                }
+                else {
+                    this.ws.close();
+                }
+            }
+            catch { }
+            this.ws = null;
+        }
+        this.listeners.clear();
+    }
+}

package/dist/chat.d.ts

@@ -0,0 +1,134 @@
+import type { PendingPermissionRecord } from './permissions.js';
+import type { PermissionResolver } from './permissions.js';
+import type { SessionWatch, SessionWatchState, V3Message } from './realtime.js';
+import type { SwarmTransport } from './transport.js';
+import type { SessionDetail, SessionRecord } from './types.js';
+import { SwarmWebSocketBridge, type SwarmWebSocketBridgeOptions } from './websocket.js';
+export interface CreateChatSessionOptions {
+    /** Descriptive title for this conversation */
+    title?: string;
+    /** Agent profile name (defaults to 'swarm') */
+    agent_name?: string;
+    /** Workspace filesystem path */
+    workspace_path?: string;
+    /** Workspace catalog identity */
+    workspace_id?: string;
+    /** Project identity if linked to a project */
+    project_id?: string;
+    /**
+     * Mode:
+     * - 'auto' (default): Autonomous execution with tool capabilities.
+     * - 'plan': Plan-mode requiring explicit checkpoint plan submission.
+     */
+    mode?: 'auto' | 'plan';
+}
+export interface ToolStreamItem {
+    id: string;
+    name: string;
+    identity?: string;
+    display?: string;
+    arguments?: string;
+    output?: string;
+    status: 'running' | 'completed' | 'failed' | 'waiting_approval' | 'cancelled';
+    error?: string;
+    durationMs?: number;
+}
+export interface ChatRunOptions {
+    /** User message to send */
+    message: string;
+    /** Max milliseconds to wait for response (default: 180,000ms / 3min) */
+    timeoutMs?: number;
+    /** Polling interval in ms (default: 1,000ms) */
+    pollIntervalMs?: number;
+    /**
+     * Explicit opt-in policy for ordinary tools only. Ask-user always needs a human answer.
+     * Prefer stream() and an explicit permission UI.
+     */
+    autoApprovePermissions?: boolean;
+    /** Optional callback invoked whenever a tool execution starts or completes */
+    onToolEvent?: (event: ToolStreamItem) => void;
+    /** Optional AbortSignal to cancel waiting */
+    signal?: AbortSignal;
+}
+export interface ChatRunResult {
+    /** The final text response from the assistant */
+    reply: string;
+    /** Target session ID */
+    sessionId: string;
+    /** Active or completed run ID */
+    runId?: string;
+    /** All messages in the session */
+    messages: V3Message[];
+    /** Any permissions that were requested during this run */
+    pendingPermissions?: PendingPermissionRecord[];
+    /** Full session detail */
+    session: SessionDetail;
+}
+export interface ChatStreamOptions {
+    signal?: AbortSignal;
+    surface?: string;
+    socketFactory?: import('./realtime.js').RealtimeSocketFactory;
+    /** Authoritative conversation snapshot on hydrate, live change and reconnect. */
+    onState?: (state: SessionWatchState) => void;
+    /** Invoked with incremental and cumulative assistant response text */
+    onText?: (delta: string, fullText: string) => void;
+    /** Invoked with incremental and cumulative reasoning/thinking text */
+    onReasoning?: (delta: string, fullText: string) => void;
+    /** Invoked when a tool call starts running */
+    onToolStarted?: (tool: ToolStreamItem) => void;
+    /** Invoked with streamed incremental output from a running tool */
+    onToolDelta?: (tool: ToolStreamItem, delta: string) => void;
+    /** Invoked when a tool call finishes or fails */
+    onToolCompleted?: (tool: ToolStreamItem) => void;
+    /** Invoked when a tool requires approval before execution */
+    onPermissionRequested?: (permission: PendingPermissionRecord, resolver: PermissionResolver) => void | Promise<void>;
+    /** Request no longer pending in a durable snapshot; this does not imply approval. */
+    onPermissionRemoved?: (permissionId: string) => void;
+    /** Recoverable UI/resolution failure; the watch stays open. Resolver also rejects. */
+    onPermissionError?: (error: Error, permission: PendingPermissionRecord) => void;
+    /** Invoked when the agent turn completes */
+    onComplete?: (messages: V3Message[]) => void;
+    /** Invoked if an unrecoverable streaming error occurs */
+    onError?: (err: Error) => void;
+}
+/**
+ * Dedicated high-level Chat namespace.
+ * Provides streamlined building blocks for interactive AI chat, streaming responses,
+ * live tool call monitoring, and automatic or custom permission handling.
+ */
+export declare class SwarmChatNamespace {
+    private readonly transport;
+    private readonly sessions;
+    private readonly permissions;
+    private readonly realtime;
+    constructor(transport: SwarmTransport);
+    /**
+     * Attaches a native bidirectional WebSocket bridge to an HTTP or HTTPS server.
+     * Enables browsers to stream tokens, live tool events, and send messages directly over WebSockets.
+     */
+    attachWebSocket(server: import('node:http').Server | import('node:https').Server, options?: SwarmWebSocketBridgeOptions): SwarmWebSocketBridge;
+    /**
+     * Creates an interactive chat session.
+     * Standalone workspace chat uses Swarm. For project orchestration use
+     * projects.createConversation(projectId); project membership is not workspace authority.
+     */
+    createSession(options?: CreateChatSessionOptions): Promise<SessionRecord>;
+    /**
+     * Appends a message to a chat conversation.
+     */
+    sendMessage(sessionId: string, content: string, role?: 'user' | 'assistant' | 'system', clientRequestId?: string): Promise<any>;
+    /**
+     * Lists messages from a session conversation.
+     */
+    listMessages(sessionId: string): Promise<V3Message[]>;
+    /**
+     * High-level chat execution: sends a message, monitors execution, handles or surfaces
+     * pending permissions, and returns the final assistant reply.
+     */
+    run(sessionId: string, options: ChatRunOptions): Promise<ChatRunResult>;
+    /**
+     * Establishes a real-time event stream for a chat session.
+     * Streams text deltas, reasoning deltas, and live tool start/output/completion events like on Swarm.
+     */
+    stream(sessionId: string, options?: ChatStreamOptions): Promise<SessionWatch>;
+}