@recursiv/sdk 0.7.50 → 0.7.51

package/dist/realtime.js

@@ -16,11 +16,62 @@ async function loadIo() {
     }
     return cachedIo;
 }
+/**
+ * Wider and more jittered than socket.io's own 1s/5s: when an API restart
+ * drops every client at once they must not all re-fetch `/realtime/ws-token`
+ * in the same second, which rate-limits it and keeps them all offline.
+ */
+const DEFAULT_BACKOFF = {
+    reconnectionDelay: 2_000,
+    reconnectionDelayMax: 30_000,
+    randomizationFactor: 0.5,
+};
+/** The token source refused the credential itself; retrying cannot succeed. */
+function isCredentialRefusal(err) {
+    const status = err?.status;
+    return status === 401 || status === 403;
+}
+/**
+ * WebSocket client for chat and presence.
+ *
+ * One socket at a time, and it survives the ways a socket dies:
+ * - a transport drop (network blip, sleep, backgrounding, API restart) is
+ *   retried by socket.io with jittered backoff;
+ * - the server ending the connection because its token expired, or refusing
+ *   a reconnect handshake (spent or expired token, rate limit), is retried
+ *   here with the same backoff, since socket.io does not retry either;
+ * - every attempt authenticates with its own token (the server accepts each
+ *   token once), and a failed token fetch sends none rather than a spent one;
+ * - listeners registered with `on()`/`onMessage()`… and rooms joined with
+ *   `joinConversation()` are re-applied to every connection, including a
+ *   socket rebuilt by a later `connect()`.
+ *
+ * Reconnecting stops only on `disconnect()` or when the token source refuses
+ * the credential (401/403).
+ */
 export class RealtimeClient {
     socket = null;
     client;
     connectionPromise = null;
     tokenProvider = null;
+    backoff = { ...DEFAULT_BACKOFF };
+    /** Every subscription, attached to each socket this client builds. */
+    listeners = new Map();
+    /** Conversation rooms to join on every connect. */
+    rooms = new Set();
+    /** connect() callers waiting on a socket that is reconnecting. */
+    waiters = [];
+    recoveryTimer = null;
+    recoveryAttempts = 0;
+    credentialRefused = false;
+    /** Bumped by disconnect(), so a connect() still in flight does not revive a socket. */
+    generation = 0;
+    /**
+     * The socket whose first handshake a connect() is awaiting. Closing a socket
+     * that never connected makes socket.io emit nothing, so discardSocket()
+     * settles that connect() through this.
+     */
+    pendingOpen = null;
     constructor(client) {
         this.client = client;
     }
@@ -32,107 +83,324 @@ export class RealtimeClient {
             const response = await this.client.get('/realtime/ws-token');
             return response.data?.token || undefined;
         }
-        catch {
+        catch (err) {
+            if (isCredentialRefusal(err))
+                this.credentialRefused = true;
+            return undefined;
+        }
+    }
+    /** A token for one reconnect attempt. Never throws: no token means the attempt is refused and retried. */
+    async mintToken() {
+        try {
+            const token = this.tokenProvider ? await this.tokenProvider() : await this.fetchTokenWithClientKey();
+            if (token)
+                this.credentialRefused = false;
+            return token || undefined;
+        }
+        catch (err) {
+            if (isCredentialRefusal(err))
+                this.credentialRefused = true;
             return undefined;
         }
     }
     /**
      * Connects to the WebSocket server using a temporary WebSocket token.
+     * Resolves with the connected socket.
      *
-     * Reconnect-safe by design:
-     * - the connection promise is cleared after settling, so a later call
-     *   builds a fresh socket instead of returning a dead one;
-     * - `connect_error` only tears down the INITIAL attempt — after the first
-     *   successful connect, socket.io's auto-reconnection owns recovery and
-     *   transient errors never disable it;
-     * - auth uses socket.io's function form, so every (re)connection attempt
-     *   fetches a fresh token via `options.getToken` or the client's key.
+     * Safe to call as often as you like: a connected socket is returned as is,
+     * a socket that is reconnecting is waited on (the promise rejects if that
+     * attempt fails, while the client keeps retrying), and only a socket that
+     * has stopped for good is replaced.
      */
     async connect(options) {
         if (options?.getToken) {
             this.tokenProvider = options.getToken;
         }
-        if (this.socket?.connected) {
-            return this.socket;
-        }
-        // A socket that is neither connected nor actively reconnecting is dead —
-        // socket.io has given up on it. Drop it so we build a fresh one.
-        if (this.socket && !this.socket.connected && !this.socket.active) {
-            this.socket.disconnect();
-            this.socket = null;
-            this.connectionPromise = null;
+        if (options)
+            this.applyBackoff(options);
+        const current = this.socket;
+        if (current?.connected) {
+            return current;
         }
         if (this.connectionPromise) {
             return this.connectionPromise;
         }
-        this.connectionPromise = (async () => {
-            const io = await loadIo();
-            const provider = this.tokenProvider ?? (() => this.fetchTokenWithClientKey());
-            const token = await provider();
-            if (!token) {
-                throw new Error('Failed to fetch WebSocket token');
-            }
-            const socket = io(this.client.baseOrigin, {
-                path: '/socket.io',
-                transports: ['websocket', 'polling'],
-                // Function-form auth: socket.io invokes this on EVERY connection
-                // attempt, so reconnects always carry a fresh short-lived token.
-                auth: (cb) => {
-                    provider()
-                        .then((fresh) => cb({ token: fresh ?? token }))
-                        .catch(() => cb({ token }));
-                },
-                autoConnect: true,
-                reconnection: true,
-            });
-            this.socket = socket;
-            return await new Promise((resolve, reject) => {
-                const onConnect = () => {
-                    socket.off('connect', onConnect);
-                    socket.off('connect_error', onInitialError);
-                    resolve(socket);
-                };
-                const onInitialError = (err) => {
-                    // Initial handshake failed — tear down and surface the error.
-                    // This handler is removed on first successful connect, so later
-                    // reconnect errors never disable the socket.
-                    socket.off('connect', onConnect);
-                    socket.off('connect_error', onInitialError);
-                    socket.disconnect();
-                    if (this.socket === socket) {
-                        this.socket = null;
-                    }
-                    reject(err);
-                };
-                socket.on('connect', onConnect);
-                socket.on('connect_error', onInitialError);
-            });
-        })();
+        // socket.io is retrying the transport, or a retry of a refused handshake
+        // is scheduled. Building a second socket here would leave the first one
+        // reconnecting in the background with its own listeners: duplicate events
+        // and an extra server connection per call.
+        if (current && (current.active || this.recoveryTimer)) {
+            return this.waitForConnect();
+        }
+        // Neither connected nor reconnecting: socket.io has given up on it.
+        if (current) {
+            this.discardSocket(current, new Error('Realtime connection replaced'));
+        }
+        const opening = this.openSocket();
+        this.connectionPromise = opening;
         try {
-            return await this.connectionPromise;
+            return await opening;
         }
         finally {
             // Clear after settling (success OR failure): the live socket is held in
-            // this.socket; a dead one must not be served from a stale promise.
-            this.connectionPromise = null;
+            // this.socket; a dead one must not be served from a stale promise. Only
+            // clear our own: after disconnect() a later connect() may already own
+            // the slot, and forgetting it would let the next call open a second
+            // socket beside it.
+            if (this.connectionPromise === opening)
+                this.connectionPromise = null;
+        }
+    }
+    applyBackoff(options) {
+        const next = { ...this.backoff };
+        if (typeof options.reconnectionDelay === 'number' && options.reconnectionDelay >= 0) {
+            next.reconnectionDelay = options.reconnectionDelay;
+        }
+        if (typeof options.reconnectionDelayMax === 'number' && options.reconnectionDelayMax >= 0) {
+            next.reconnectionDelayMax = options.reconnectionDelayMax;
         }
+        if (typeof options.randomizationFactor === 'number') {
+            next.randomizationFactor = Math.min(1, Math.max(0, options.randomizationFactor));
+        }
+        this.backoff = next;
     }
+    async openSocket() {
+        const generation = this.generation;
+        const io = await loadIo();
+        const token = this.tokenProvider ? await this.tokenProvider() : await this.fetchTokenWithClientKey();
+        if (!token) {
+            throw new Error('Failed to fetch WebSocket token');
+        }
+        if (generation !== this.generation) {
+            throw new Error('Realtime disconnected before the connection opened');
+        }
+        this.credentialRefused = false;
+        // The server accepts each token once. The first handshake spends the one
+        // fetched above; every later attempt (socket.io's transport reconnects and
+        // the recoveries below) mints its own, and sends none when that fails
+        // rather than replaying a spent token.
+        let unspent = token;
+        const socket = io(this.client.baseOrigin, {
+            path: '/socket.io',
+            transports: ['websocket', 'polling'],
+            // Function-form auth: socket.io invokes this on EVERY connection attempt.
+            auth: (cb) => {
+                const first = unspent;
+                unspent = undefined;
+                if (first) {
+                    cb({ token: first });
+                    return;
+                }
+                void this.mintToken().then((fresh) => cb(fresh ? { token: fresh } : {}));
+            },
+            autoConnect: true,
+            reconnection: true,
+            reconnectionDelay: this.backoff.reconnectionDelay,
+            reconnectionDelayMax: this.backoff.reconnectionDelayMax,
+            randomizationFactor: this.backoff.randomizationFactor,
+        });
+        this.socket = socket;
+        this.watchLifecycle(socket);
+        for (const [event, listeners] of this.listeners) {
+            for (const listener of listeners)
+                socket.on(event, listener);
+        }
+        return await new Promise((resolve, reject) => {
+            const settle = () => {
+                socket.off('connect', onConnect);
+                socket.off('connect_error', onInitialError);
+                if (this.pendingOpen?.socket === socket)
+                    this.pendingOpen = null;
+            };
+            const onConnect = () => {
+                settle();
+                resolve(socket);
+            };
+            const onInitialError = (err) => {
+                // Initial handshake failed — tear down and surface the error. This
+                // handler is removed on first successful connect, so later reconnect
+                // errors never disable the socket.
+                settle();
+                this.discardSocket(socket, err);
+                reject(err);
+            };
+            // disconnect() before the first handshake completes.
+            this.pendingOpen = {
+                socket,
+                fail: (err) => {
+                    settle();
+                    reject(err);
+                },
+            };
+            socket.on('connect', onConnect);
+            socket.on('connect_error', onInitialError);
+        });
+    }
+    /** Room rejoin, waiter settlement and recovery from the disconnects socket.io leaves alone. */
+    watchLifecycle(socket) {
+        let connectedOnce = false;
+        let tokenExpired = false;
+        socket.on('connect', () => {
+            if (this.socket !== socket)
+                return;
+            connectedOnce = true;
+            tokenExpired = false;
+            this.recoveryAttempts = 0;
+            // Room membership lives on the server-side connection, so a reconnect
+            // starts in no rooms. Rejoin every room the app is in.
+            for (const conversationId of this.rooms) {
+                socket.emit('join_conversation', conversationId);
+            }
+            const waiters = this.waiters;
+            this.waiters = [];
+            for (const waiter of waiters)
+                waiter.resolve(socket);
+        });
+        // The server announces an expired token just before it ends the connection.
+        socket.on('token_expired', () => {
+            tokenExpired = true;
+        });
+        socket.on('disconnect', (reason) => {
+            if (this.socket !== socket)
+                return;
+            // socket.io never reconnects a server-side disconnect. One that follows
+            // token_expired is routine (every token TTL, 10 minutes by default), so
+            // reconnect with a fresh token. Any other server disconnect, such as an
+            // eviction for too many open sockets, is left alone; the next connect()
+            // replaces the socket.
+            if (reason === 'io server disconnect' && tokenExpired) {
+                tokenExpired = false;
+                this.scheduleRecovery(socket);
+            }
+        });
+        socket.on('connect_error', (err) => {
+            if (this.socket !== socket || !connectedOnce)
+                return;
+            const waiters = this.waiters;
+            this.waiters = [];
+            for (const waiter of waiters)
+                waiter.reject(err);
+            // `active` stays true while socket.io retries a transport failure. It
+            // turns false when the server refused the handshake (spent or expired
+            // token, rate limit), which socket.io never retries.
+            if (!socket.active) {
+                this.scheduleRecovery(socket);
+            }
+        });
+    }
+    scheduleRecovery(socket) {
+        if (this.socket !== socket || this.recoveryTimer)
+            return;
+        if (this.credentialRefused) {
+            // The token source refused the credential. Stop here; an explicit
+            // connect() tries again from scratch.
+            this.discardSocket(socket, new Error('Realtime stopped: the WebSocket token request was refused (401/403)'));
+            return;
+        }
+        const delay = this.recoveryDelay(this.recoveryAttempts++);
+        this.recoveryTimer = setTimeout(() => {
+            this.recoveryTimer = null;
+            if (this.socket !== socket || socket.connected || socket.active)
+                return;
+            socket.connect();
+        }, delay);
+    }
+    /** Exponential backoff with jitter, bounded by reconnectionDelayMax. */
+    recoveryDelay(attempt) {
+        const { reconnectionDelay, reconnectionDelayMax, randomizationFactor } = this.backoff;
+        const base = Math.min(reconnectionDelayMax, reconnectionDelay * 2 ** Math.min(attempt, 20));
+        const jitter = base * randomizationFactor * (Math.random() * 2 - 1);
+        return Math.round(Math.min(reconnectionDelayMax, Math.max(0, base + jitter)));
+    }
+    waitForConnect() {
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    discardSocket(socket, reason) {
+        if (this.recoveryTimer) {
+            clearTimeout(this.recoveryTimer);
+            this.recoveryTimer = null;
+        }
+        if (this.pendingOpen?.socket === socket) {
+            this.pendingOpen.fail(reason);
+        }
+        socket.disconnect();
+        for (const [event, listeners] of this.listeners) {
+            for (const listener of listeners)
+                socket.off(event, listener);
+        }
+        if (this.socket === socket) {
+            this.socket = null;
+        }
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const waiter of waiters)
+            waiter.reject(reason);
+    }
+    /**
+     * Close the connection and stop reconnecting. Joined rooms are forgotten;
+     * listeners stay registered and attach to the next connection.
+     */
     disconnect() {
+        this.generation += 1;
+        this.rooms.clear();
+        this.recoveryAttempts = 0;
+        this.credentialRefused = false;
         if (this.socket) {
-            this.socket.disconnect();
-            this.socket = null;
+            this.discardSocket(this.socket, new Error('Realtime disconnected'));
+        }
+        else {
+            const waiters = this.waiters;
+            this.waiters = [];
+            for (const waiter of waiters)
+                waiter.reject(new Error('Realtime disconnected'));
         }
         this.connectionPromise = null;
     }
     getSocket() {
         return this.socket;
     }
+    /**
+     * Listen for any server event, including the lifecycle events `connect`
+     * (initial and every reconnect: refetch what you may have missed) and
+     * `disconnect`. The listener stays attached across reconnects and socket
+     * replacement. Returns an unsubscribe function.
+     *
+     * Server events include `notification`, `feed_update`,
+     * `conversation_created`, `chat_message`, `chat_typing` and `agent_thinking`.
+     */
+    on(event, listener) {
+        // Every call is its own subscription, even for a function that is already
+        // subscribed: it fires once per subscription, as socket.io's own `on`
+        // does, and its unsubscribe removes only itself, so one consumer can never
+        // cancel another's.
+        const handler = (...args) => listener(...args);
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(handler);
+        this.socket?.on(event, handler);
+        return () => {
+            const current = this.listeners.get(event);
+            if (!current?.delete(handler))
+                return;
+            if (current.size === 0)
+                this.listeners.delete(event);
+            this.socket?.off(event, handler);
+        };
+    }
+    /** Join a conversation room now, and again after every reconnect, until you leave it. */
     joinConversation(conversationId) {
+        this.rooms.add(conversationId);
         if (this.socket?.connected) {
             this.socket.emit('join_conversation', conversationId);
         }
     }
     leaveConversation(conversationId) {
+        this.rooms.delete(conversationId);
         if (this.socket?.connected) {
             this.socket.emit('leave_conversation', conversationId);
         }
@@ -143,23 +411,18 @@ export class RealtimeClient {
         }
     }
     onMessage(callback) {
-        this.socket?.on('chat_message', callback);
-        return () => this.socket?.off('chat_message', callback);
+        return this.on('chat_message', callback);
     }
     onMessageEdit(callback) {
-        this.socket?.on('chat_message_edit', callback);
-        return () => this.socket?.off('chat_message_edit', callback);
+        return this.on('chat_message_edit', callback);
     }
     onMessageDelete(callback) {
-        this.socket?.on('chat_message_delete', callback);
-        return () => this.socket?.off('chat_message_delete', callback);
+        return this.on('chat_message_delete', callback);
     }
     onTyping(callback) {
-        this.socket?.on('chat_typing', callback);
-        return () => this.socket?.off('chat_typing', callback);
+        return this.on('chat_typing', callback);
     }
     onAgentThinking(callback) {
-        this.socket?.on('agent_thinking', callback);
-        return () => this.socket?.off('agent_thinking', callback);
+        return this.on('agent_thinking', callback);
     }
 }

package/dist/resources/agents.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, DeleteResponse, Agent, AgentDetail, CreateAgentInput, CreatedAgent, UpdateAgentInput, UpdatedAgent, AgentChatInput, AgentChatResult, AgentConversation, AgentConversationMessage, PaginationParams, StreamChunk } from '../types.js';
+import type { PaginatedResponse, SingleResponse, DeleteResponse, Agent, AgentDetail, CreateAgentInput, CreatedAgent, UpdateAgentInput, UpdatedAgent, AgentChatInput, AgentChatRetryInput, AgentChatResult, AgentConversation, AgentConversationMessage, PaginationParams, StreamChunk } from '../types.js';
 export interface AgentMessage {
     id: string;
     networkId: string;
@@ -137,7 +137,14 @@ export declare class AgentsResource {
      * nothing landed, but never why.
      */
     conversationMessages(id: string, conversationId: string, params?: PaginationParams): Promise<PaginatedResponse<AgentConversationMessage>>;
-    /** List discoverable agents (public + same-org) */
+    /**
+     * List the agents a member may discover: an app key gets the agents of its
+     * project and owning org, a personal key gets global and same-org agents.
+     * Only member-facing agents are returned. Agents that run a tenant (a
+     * project's Lead, swarm workers, dispatcher role agents, MCP client agents,
+     * the workspace AI, anyone's personal AI) never appear here; list your own
+     * with `list()`.
+     */
     listDiscoverable(params?: PaginationParams & {
         organization_id?: string;
         global?: boolean;
@@ -264,6 +271,16 @@ export declare class AgentsResource {
      * For React Native, use `chatStreamText()` instead.
      */
     chatStream(id: string, input: AgentChatInput): AsyncGenerator<StreamChunk>;
+    /**
+     * Retry a turn: stream a fresh reply to one of your existing messages
+     * without sending it again. Use it for "Try again" after a reply failed.
+     * The agent's earlier reply to that message, if any, is removed first.
+     *
+     * The message must be yours and the latest one in the conversation
+     * (409 `retry_not_latest` otherwise), and a reply still being written must
+     * finish or be stopped first (409 `run_in_progress`).
+     */
+    retryChatStream(id: string, input: AgentChatRetryInput): AsyncGenerator<StreamChunk>;
     /**
      * Chat with an agent and get the full response text.
      *
@@ -287,4 +304,13 @@ export declare class AgentsResource {
         conversationId: string;
         chunks: StreamChunk[];
     }>;
+    /** `retryChatStream()` for platforms without `ReadableStream` (React Native). */
+    retryChatStreamText(id: string, input: AgentChatRetryInput): Promise<{
+        content: string;
+        conversationId: string;
+        chunks: StreamChunk[];
+    }>;
+    private openStream;
+    private streamChunks;
+    private streamText;
 }

package/dist/resources/agents.js

@@ -92,7 +92,14 @@ export class AgentsResource {
     conversationMessages(id, conversationId, params) {
         return this.client.get(`/agents/${id}/conversations/${conversationId}/messages`, params);
     }
-    /** List discoverable agents (public + same-org) */
+    /**
+     * List the agents a member may discover: an app key gets the agents of its
+     * project and owning org, a personal key gets global and same-org agents.
+     * Only member-facing agents are returned. Agents that run a tenant (a
+     * project's Lead, swarm workers, dispatcher role agents, MCP client agents,
+     * the workspace AI, anyone's personal AI) never appear here; list your own
+     * with `list()`.
+     */
     listDiscoverable(params) {
         return this.client.get('/agents/discoverable', params);
     }
@@ -181,26 +188,19 @@ export class AgentsResource {
      * For React Native, use `chatStreamText()` instead.
      */
     async *chatStream(id, input) {
-        const response = await this.client.fetchRaw(`/agents/${id}/chat/stream`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(input),
-        });
-        if (!response.ok) {
-            let errorBody;
-            try {
-                errorBody = await response.json();
-            }
-            catch {
-                throw new RecursivError(response.status, {
-                    type: 'api_error',
-                    message: `HTTP ${response.status}: ${response.statusText}`,
-                    code: 'stream_error',
-                });
-            }
-            throw new RecursivError(response.status, errorBody.error);
-        }
-        yield* parseSSE(response.body);
+        yield* this.streamChunks(id, input);
+    }
+    /**
+     * Retry a turn: stream a fresh reply to one of your existing messages
+     * without sending it again. Use it for "Try again" after a reply failed.
+     * The agent's earlier reply to that message, if any, is removed first.
+     *
+     * The message must be yours and the latest one in the conversation
+     * (409 `retry_not_latest` otherwise), and a reply still being written must
+     * finish or be stopped first (409 `run_in_progress`).
+     */
+    async *retryChatStream(id, input) {
+        yield* this.streamChunks(id, input);
     }
     /**
      * Chat with an agent and get the full response text.
@@ -220,12 +220,19 @@ export class AgentsResource {
      * });
      * ```
      */
-    async chatStreamText(id, input) {
+    chatStreamText(id, input) {
+        return this.streamText(id, input);
+    }
+    /** `retryChatStream()` for platforms without `ReadableStream` (React Native). */
+    retryChatStreamText(id, input) {
+        return this.streamText(id, input);
+    }
+    async openStream(id, input, accept) {
         const response = await this.client.fetchRaw(`/agents/${id}/chat/stream`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                Accept: 'text/event-stream',
+                ...(accept ? { Accept: accept } : {}),
             },
             body: JSON.stringify(input),
         });
@@ -243,6 +250,14 @@ export class AgentsResource {
             }
             throw new RecursivError(response.status, errorBody.error);
         }
+        return response;
+    }
+    async *streamChunks(id, input) {
+        const response = await this.openStream(id, input);
+        yield* parseSSE(response.body);
+    }
+    async streamText(id, input) {
+        const response = await this.openStream(id, input, 'text/event-stream');
         const text = await response.text();
         const lines = text.split('\n');
         let fullText = '';