@butlerbot/sdk 0.0.24 → 0.0.26

package/dist/link/link.d.ts

@@ -56,7 +56,11 @@ export type LinkOptions = {
     reconnect?: boolean;
     minReconnectDelayMs?: number;
     maxReconnectDelayMs?: number;
-    /** Keeps idle connections alive through proxies. 0 disables. Default 30s. */
+    /**
+     * How long the connection may be silent before it is pinged, which both proves it is
+     * alive and keeps proxies from dropping it. A connection that is receiving frames is
+     * never pinged. 0 disables. Default 30s.
+     */
     heartbeatMs?: number;
     /** How long to wait for an acknowledgement. Turns are never timed out here. */
     requestTimeoutMs?: number;
@@ -88,6 +92,8 @@ export declare class Link {
     private readonly pending;
     private readonly calls;
     private socket;
+    /** Every socket this link has opened and not yet closed, by generation. */
+    private readonly sockets;
     private frameCounter;
     private currentState;
     private identity?;
@@ -110,6 +116,13 @@ export declare class Link {
     private reconnectAttempt;
     private reconnectAfterMs;
     private heartbeat?;
+    /**
+     * When the server last said anything at all.
+     *
+     * Any frame is proof the connection is alive, so a link that is busy carrying a turn
+     * never needs to ask.
+     */
+    private lastInboundAt;
     private closedByUs;
     constructor(options: LinkOptions);
     /** Adds a tool Alfred can call. Registered on connect, or immediately if already open. */
@@ -162,6 +175,15 @@ export declare class Link {
      * means the real event, whenever it turns up, is ignored.
      */
     private dropSocket;
+    /**
+     * Closes a socket this end has stopped using, whatever generation it belongs to.
+     *
+     * Every path that walks away from a socket goes through here. Forgetting one is not harmless:
+     * the server has no way to tell an abandoned connection from a live one — it has said hello,
+     * registered its tools and claimed its link id — so it keeps it, keeps serving from it, and
+     * hands the link id back and forth between it and its replacements.
+     */
+    private abandon;
     private onClose;
     /** Retries when it is allowed to, and tells everyone waiting when it is not. */
     private retryOrGiveUp;
@@ -174,21 +196,31 @@ export declare class Link {
     private scheduleReconnect;
     private clearReconnect;
     /**
-     * Pings on an interval and, the important half, notices when a ping goes unanswered.
+     * Pings a SILENT connection and, the important half, notices when a ping goes unanswered.
      *
      * A websocket can die without a close frame — a dropped route, a proxy that forgets
      * the connection, a suspended machine — leaving both ends convinced they are
      * connected while every frame sent into it vanishes. An unanswered ping is the only
      * evidence this end will ever get, so it is treated as a dead connection and
      * reconnected rather than swallowed.
-     */
-    private startHeartbeat;
-    /**
-     * Never longer than the interval itself: a second ping in flight tells us nothing new.
      *
-     * Floored so that a very short interval cannot declare a merely busy connection dead.
+     * It only asks when nothing has arrived for a whole interval, because a connection
+     * that is delivering frames has already answered the question. Pinging regardless
+     * meant a busy link had to complete a round trip while the socket was carrying a
+     * streaming turn: the reply queues behind everything already in flight, and a turn
+     * big enough to take longer than the timeout to drain got its own connection torn
+     * down with `4000 heartbeat timeout` — always mid-response, always on the longest
+     * answers, which are the ones a user least wants to lose.
      */
+    private startHeartbeat;
+    /** Wakes when the connection will have been silent for a full interval, not before. */
+    private scheduleHeartbeat;
+    /** One liveness round trip. Only ever sent to a connection that has gone quiet. */
+    private ping;
+    /** Never longer than the interval itself: a second ping in flight tells us nothing new. */
     private heartbeatTimeoutMs;
+    /** Any frame from the server, of any kind, is proof the connection still works. */
+    private markInbound;
     private stopHeartbeat;
     /** Parks a caller until someone settles the list it was parked in. 0 waits forever. */
     private wait;

package/dist/link/link.js

@@ -28,6 +28,8 @@ class Link {
         this.pending = new Map();
         this.calls = new Map();
         this.socket = null;
+        /** Every socket this link has opened and not yet closed, by generation. */
+        this.sockets = new Map();
         this.frameCounter = 0;
         this.currentState = "idle";
         /**
@@ -47,6 +49,13 @@ class Link {
         this.openWaiters = [];
         this.reconnectAttempt = 0;
         this.reconnectAfterMs = 0;
+        /**
+         * When the server last said anything at all.
+         *
+         * Any frame is proof the connection is alive, so a link that is busy carrying a turn
+         * never needs to ask.
+         */
+        this.lastInboundAt = 0;
         this.closedByUs = false;
         this.options = {
             ...DEFAULTS,
@@ -171,7 +180,10 @@ class Link {
         this.failPending(closed);
         this.settleWaiters(this.attemptWaiters, closed);
         this.settleWaiters(this.openWaiters, closed);
-        this.socket?.close(1000, reason);
+        // Every socket, not just the current one: a link that is being closed for good must not
+        // leave anything of itself attached to the server.
+        for (const generation of [...this.sockets.keys()])
+            this.abandon(generation, reason);
         this.socket = null;
     }
     /**
@@ -194,14 +206,23 @@ class Link {
         const { url, protocols } = (0, socket_1.buildHandshake)(this.options.serverUrl, "link", this.options.apiKey);
         this.debug(`connecting to ${url.replace(/api_key=[^&]+/, "api_key=***")}`);
         try {
-            this.socket = this.options.socketFactory(url, protocols, {
+            const socket = this.options.socketFactory(url, protocols, {
                 onOpen: () => this.onOpen(generation),
                 onMessage: (data) => { if (generation === this.generation)
                     this.onMessage(data); },
-                onClose: (code, reason) => this.onClose(generation, code, reason),
+                onClose: (code, reason) => {
+                    this.sockets.delete(generation);
+                    this.onClose(generation, code, reason);
+                },
                 onError: (error) => { if (generation === this.generation)
                     this.emitter.emit("error", asError(error)); },
             });
+            // Held by generation, not only as `this.socket`, so a socket that stops being the
+            // current one can still be closed. One that is merely forgotten stays open at the far
+            // end: it has already said hello and registered its tools, so the server goes on serving
+            // it, and it answers websocket pings forever because the network stack does that for it.
+            this.sockets.set(generation, socket);
+            this.socket = socket;
         }
         catch (error) {
             // A factory that throws never produces a close event, so this failure is
@@ -230,9 +251,11 @@ class Link {
             const identity = { connectionId: welcome.connectionId, scope: welcome.scope };
             this.identity = identity;
             await this.registerAll();
-            // Registration is several round trips; the socket may have gone during them.
+            // Registration is several round trips; the socket may have gone during them. It is fully
+            // registered at the server by now, so abandoning it quietly would leave it serving tools
+            // nothing here will ever answer.
             if (generation !== this.generation)
-                return;
+                return this.abandon(generation, "superseded during handshake");
             this.attempting = false;
             this.currentState = "open";
             this.reconnectAttempt = 0;
@@ -243,7 +266,7 @@ class Link {
             this.emitter.emit("connect", identity);
         }).catch((error) => {
             if (generation !== this.generation)
-                return;
+                return this.abandon(generation, "superseded during handshake");
             this.emitter.emit("error", error);
             this.settleWaiters(this.attemptWaiters, error);
             // Only the server saying "do not come back" stops us: a rejected claim or an
@@ -266,12 +289,28 @@ class Link {
     dropSocket(generation, code, reason) {
         if (generation !== this.generation)
             return;
-        const socket = this.socket;
         this.onClose(generation, code, reason);
+        // 1006 is reserved and rejected by browsers; anything else we raise is a valid
+        // application code.
+        this.abandon(generation, reason, code === 1006 ? 1000 : code);
+    }
+    /**
+     * Closes a socket this end has stopped using, whatever generation it belongs to.
+     *
+     * Every path that walks away from a socket goes through here. Forgetting one is not harmless:
+     * the server has no way to tell an abandoned connection from a live one — it has said hello,
+     * registered its tools and claimed its link id — so it keeps it, keeps serving from it, and
+     * hands the link id back and forth between it and its replacements.
+     */
+    abandon(generation, reason, code = 1000) {
+        const socket = this.sockets.get(generation);
+        if (!socket)
+            return;
+        this.sockets.delete(generation);
+        if (this.socket === socket)
+            this.socket = null;
         try {
-            // 1006 is reserved and rejected by browsers; anything else we raise is a valid
-            // application code.
-            socket?.close(code === 1006 ? 1000 : code, reason);
+            socket.close(code, reason);
         }
         catch {
             // Already gone, which is the outcome we wanted anyway.
@@ -336,46 +375,82 @@ class Link {
         this.reconnectTimer = undefined;
     }
     /**
-     * Pings on an interval and, the important half, notices when a ping goes unanswered.
+     * Pings a SILENT connection and, the important half, notices when a ping goes unanswered.
      *
      * A websocket can die without a close frame — a dropped route, a proxy that forgets
      * the connection, a suspended machine — leaving both ends convinced they are
      * connected while every frame sent into it vanishes. An unanswered ping is the only
      * evidence this end will ever get, so it is treated as a dead connection and
      * reconnected rather than swallowed.
+     *
+     * It only asks when nothing has arrived for a whole interval, because a connection
+     * that is delivering frames has already answered the question. Pinging regardless
+     * meant a busy link had to complete a round trip while the socket was carrying a
+     * streaming turn: the reply queues behind everything already in flight, and a turn
+     * big enough to take longer than the timeout to drain got its own connection torn
+     * down with `4000 heartbeat timeout` — always mid-response, always on the longest
+     * answers, which are the ones a user least wants to lose.
      */
     startHeartbeat(generation) {
         if (!this.options.heartbeatMs)
             return;
         this.stopHeartbeat();
-        this.heartbeat = setInterval(() => {
+        this.markInbound();
+        this.scheduleHeartbeat(generation);
+    }
+    /** Wakes when the connection will have been silent for a full interval, not before. */
+    scheduleHeartbeat(generation) {
+        if (generation !== this.generation || !this.options.heartbeatMs)
+            return;
+        const silentFor = Date.now() - this.lastInboundAt;
+        const due = Math.max(this.options.heartbeatMs - silentFor, 0);
+        this.heartbeat = setTimeout(() => {
             if (generation !== this.generation)
                 return;
-            // The reply is consumed by the exchange, so it never reaches log listeners.
-            this.exchange("ping", {}, {
-                awaitReady: false,
-                isDone: (frame) => frame.type === "log",
-                timeoutMs: this.heartbeatTimeoutMs(),
-            }).catch(() => {
-                if (generation !== this.generation)
-                    return;
-                this.debug("heartbeat went unanswered, treating the connection as dead");
-                this.dropSocket(generation, 4000, "heartbeat timeout");
-            });
-        }, this.options.heartbeatMs);
+            // Something arrived while this was pending: the connection is demonstrably
+            // alive and there is nothing to ask. Wait out the rest of its silence instead.
+            if (Date.now() - this.lastInboundAt < this.options.heartbeatMs) {
+                return this.scheduleHeartbeat(generation);
+            }
+            this.ping(generation);
+        }, due);
         unref(this.heartbeat);
     }
-    /**
-     * Never longer than the interval itself: a second ping in flight tells us nothing new.
-     *
-     * Floored so that a very short interval cannot declare a merely busy connection dead.
-     */
+    /** One liveness round trip. Only ever sent to a connection that has gone quiet. */
+    ping(generation) {
+        const sentAt = Date.now();
+        // The reply is consumed by the exchange, so it never reaches log listeners.
+        this.exchange("ping", {}, {
+            awaitReady: false,
+            isDone: (frame) => frame.type === "log",
+            timeoutMs: this.heartbeatTimeoutMs(),
+        }).then(() => {
+            this.scheduleHeartbeat(generation);
+        }, () => {
+            if (generation !== this.generation)
+                return;
+            // The pong is late but other frames are flowing, so the socket is fine and only
+            // this reply is stuck behind them. Killing it here would throw away a working
+            // connection — and whatever it was busy delivering.
+            if (this.lastInboundAt > sentAt) {
+                this.debug("heartbeat was slow but the connection is delivering frames, keeping it");
+                return this.scheduleHeartbeat(generation);
+            }
+            this.debug("heartbeat went unanswered, treating the connection as dead");
+            this.dropSocket(generation, 4000, "heartbeat timeout");
+        });
+    }
+    /** Never longer than the interval itself: a second ping in flight tells us nothing new. */
     heartbeatTimeoutMs() {
         return Math.max(250, Math.min(this.options.requestTimeoutMs, this.options.heartbeatMs));
     }
+    /** Any frame from the server, of any kind, is proof the connection still works. */
+    markInbound() {
+        this.lastInboundAt = Date.now();
+    }
     stopHeartbeat() {
         if (this.heartbeat)
-            clearInterval(this.heartbeat);
+            clearTimeout(this.heartbeat);
         this.heartbeat = undefined;
     }
     // =============================================
@@ -553,6 +628,7 @@ class Link {
         this.calls.clear();
     }
     onMessage(raw) {
+        this.markInbound();
         let frame;
         try {
             frame = JSON.parse(raw);

package/dist/link/protocol.d.ts

@@ -105,6 +105,21 @@ export type LinkClientPayloads = {
     "conversation.end": {
         sessionId: string;
     };
+    /**
+     * Watches a turn that is already running, without starting one.
+     *
+     * A turn belongs to the conversation, not to the socket that asked for it, so a
+     * client that reloads or opens the conversation elsewhere can pick the answer back
+     * up as it is written. `afterEventId` resumes from what the client already has.
+     */
+    "conversation.attach": {
+        chatId: string;
+        afterEventId?: string;
+    };
+    /** Stops watching. The turn itself keeps running. */
+    "conversation.detach": {
+        chatId: string;
+    };
 };
 export type LinkClientFrameType = keyof LinkClientPayloads;
 /**
@@ -167,6 +182,7 @@ export type LinkServerPayloads = {
     };
     "conversation.event": {
         chatId?: string;
+        eventId?: string;
         event: ConversationEvent;
     };
     "conversation.notice": {

package/dist/modules/conversation.d.ts

@@ -137,8 +137,20 @@ export declare class Conversation<V extends APIPath = "v4"> {
     onceConvoId(cb: (convoId: string) => any): string | undefined;
     /** Fetches the conversation state from the server, including message history and metadata */
     fetchState(): Promise<ConversationStateResponse>;
-    /** Fetches the conversation progress stream from the server */
-    fetchProgressStream(cb: (chunk: RequestResponseByVersion[V]) => any): EventSource;
+    /**
+     * Follows the turn currently running in this conversation.
+     *
+     * Reopening a conversation mid-answer is watching a turn, not starting one, and a
+     * turn belongs to the conversation rather than to whoever started it. When the
+     * conversation is carried over a websocket Link this rides that same connection;
+     * otherwise it opens the HTTP progress stream. Either way the payloads are the same.
+     *
+     * `afterEventId` resumes from what the caller already has, so a client that reloads
+     * is sent what it missed rather than the turn from the beginning.
+     */
+    fetchProgressStream(cb: (chunk: RequestResponseByVersion[V]) => any, options?: {
+        afterEventId?: string;
+    }): ConversationStream | EventSource;
     /**
      * Fetches the conversation progress from the server
      * Returns undefined if no active turn progress

package/dist/modules/conversation.js

@@ -176,10 +176,29 @@ class Conversation {
         const data = await response.json();
         return data;
     }
-    /** Fetches the conversation progress stream from the server */
-    fetchProgressStream(cb) {
+    /**
+     * Follows the turn currently running in this conversation.
+     *
+     * Reopening a conversation mid-answer is watching a turn, not starting one, and a
+     * turn belongs to the conversation rather than to whoever started it. When the
+     * conversation is carried over a websocket Link this rides that same connection;
+     * otherwise it opens the HTTP progress stream. Either way the payloads are the same.
+     *
+     * `afterEventId` resumes from what the caller already has, so a client that reloads
+     * is sent what it missed rather than the turn from the beginning.
+     */
+    fetchProgressStream(cb, options) {
         if (!this.convoId)
             throw new Error("Conversation ID is not set");
+        if (this.transport.attach) {
+            return this.transport.attach({
+                chatId: this.convoId,
+                ...(options?.afterEventId ? { afterEventId: options.afterEventId } : {}),
+            }, {
+                payload: (payload) => cb(payload),
+                convoId: () => { },
+            });
+        }
         const url = (0, url_formatter_1.formatURL)(this.endpoints.progressStream, { chatId: this.convoId }, { apiKey: this.apiKey, debug: this.debug });
         return (0, transport_sse_1.streamSSE)(url, { debug: this.debug, onPayload: (payload) => cb(payload) });
     }

package/dist/modules/transport.d.ts

@@ -30,8 +30,21 @@ export type TransportHandlers = {
     /** The conversation this turn belongs to, as soon as it is known. */
     convoId(convoId: string): void;
 };
+/** A request to watch a turn that is already running in a conversation. */
+export type TransportAttachRequest = {
+    chatId: string;
+    /** Resume point: only what came after this event is replayed. */
+    afterEventId?: string;
+};
 export interface ConversationTransport {
     send(request: TransportTurnRequest, handlers: TransportHandlers): ConversationStream;
+    /**
+     * Watches a turn that is already running, without starting one.
+     *
+     * Optional: a transport that cannot follow someone else's turn simply does not
+     * implement it, and the conversation falls back to the HTTP progress stream.
+     */
+    attach?(request: TransportAttachRequest, handlers: TransportHandlers): ConversationStream;
 }
 /**
  * The system message form the HTTP transport uses for a notice.

package/dist/modules/transport_link.d.ts

@@ -1,5 +1,5 @@
 import type { Link } from "../link/link";
-import { ConversationStream, ConversationTransport, TransportHandlers, TransportTurnRequest } from "./transport";
+import { ConversationStream, ConversationTransport, TransportAttachRequest, TransportHandlers, TransportTurnRequest } from "./transport";
 export type LinkSessionConfig = {
     model?: string;
     personality?: string;
@@ -22,6 +22,18 @@ export declare class LinkConversationTransport implements ConversationTransport
     send(request: TransportTurnRequest, handlers: TransportHandlers): ConversationStream;
     /** Ends the session, if one is open. The conversation can still be resumed later. */
     end(): Promise<void>;
+    /**
+     * Follows a turn that is already running, over the link this conversation already holds.
+     *
+     * A turn belongs to the conversation rather than to the socket that started it, so
+     * reopening a conversation mid-answer — a reload, a second tab, a turn started from
+     * another device or over HTTP — streams here instead of dropping to an SSE connection
+     * just to watch. Needs no session: watching is not speaking.
+     *
+     * A conversation with nothing running ends the stream immediately, which is the
+     * ordinary answer for one that is simply idle.
+     */
+    attach(request: TransportAttachRequest, handlers: TransportHandlers): ConversationStream;
     private runTurn;
     /** Opens a session, or reuses the open one when it is for the same conversation. */
     private session;

package/dist/modules/transport_link.js

@@ -41,6 +41,79 @@ class LinkConversationTransport {
         this.sessionId = undefined;
         await this.link.exchange("conversation.end", { sessionId });
     }
+    /**
+     * Follows a turn that is already running, over the link this conversation already holds.
+     *
+     * A turn belongs to the conversation rather than to the socket that started it, so
+     * reopening a conversation mid-answer — a reload, a second tab, a turn started from
+     * another device or over HTTP — streams here instead of dropping to an SSE connection
+     * just to watch. Needs no session: watching is not speaking.
+     *
+     * A conversation with nothing running ends the stream immediately, which is the
+     * ordinary answer for one that is simply idle.
+     */
+    attach(request, handlers) {
+        let closed = false;
+        const deliver = (payload) => { if (!closed)
+            handlers.payload(payload); };
+        const watching = this.link.exchange("conversation.attach", {
+            chatId: request.chatId,
+            ...(request.afterEventId ? { afterEventId: request.afterEventId } : {}),
+        }, {
+            // A turn takes as long as it takes; only the transport dying ends it early.
+            timeoutMs: 0,
+            isDone: (frame) => frame.type === "conversation.done",
+            onFrame: (frame) => {
+                if (frame.type === "conversation.event") {
+                    const payload = frame.payload;
+                    const event = payload.event;
+                    const final = event.type === "response_status" && Boolean(event.payload?.completed);
+                    deliver({
+                        success: true,
+                        data: {
+                            response: event,
+                            convoId: payload.chatId ?? request.chatId,
+                            ...(final ? { quitStream: true } : {}),
+                        },
+                    });
+                    return;
+                }
+                if (frame.type === "conversation.notice") {
+                    deliver((0, transport_1.noticePayload)(frame.payload.message, frame.payload.chatId ?? request.chatId));
+                }
+            },
+        });
+        void watching.then((done) => {
+            const payload = done.payload;
+            if (payload.ok)
+                return;
+            // Nothing running is not a failure: the caller asked to watch a conversation
+            // that has nothing to watch, and the stream simply ends.
+            if (payload.code === "no_active_turn")
+                return;
+            deliver((0, transport_1.failurePayload)(payload.code ?? "link_error", payload.error ?? "The turn could not be watched.", payload.message ?? payload.error ?? "I'm afraid I couldn't follow that response.", payload.chatId ?? request.chatId));
+        }, (error) => {
+            if (error instanceof protocol_1.LinkError && error.code === "no_active_turn")
+                return;
+            deliver(error instanceof protocol_1.LinkError
+                ? (0, transport_1.failurePayload)(error.code, error.message, error.message, request.chatId)
+                : (0, transport_1.failurePayload)("link_error", String(error), "I'm afraid the connection to Alfred failed.", request.chatId));
+        });
+        return {
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                // Best-effort: a socket that has gone has already ended the watch for us.
+                try {
+                    this.link.send("conversation.detach", { chatId: request.chatId });
+                }
+                catch {
+                    // Disconnected. The server drops the attachment with the connection.
+                }
+            },
+        };
+    }
     async runTurn(request, handlers, mayRetry) {
         const sessionId = await this.session(request);
         let chatId = request.chatId ?? this.sessionChatId;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.24",
+	"version": "0.0.26",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -1,20 +1,18 @@
 # ButlerBot SDK
 
-ButlerBot SDK is a JavaScript library that provides a simple way to interact with the [ButlerBot](https://butler.now/) API.
+ButlerBot SDK is a JavaScript library that provides a simple way to interact with the [Butler](https://butler.now/) API.
 
 ## Quickstart
 
-Grab an API key at [ButlerBot](https://butler.now/) and install the package:
+Grab an API key at [Butler](https://butler.now/) (Dashboard -> Account Dropdown -> API Keys) and install the package:
 
 ```bash
 npm i @butlerbot/sdk
 ```
 
-> NOTE: API key is currently not available on the ButlerBot UI
-
 ## Prerequisites
 
-- ButlerBot API key
+- Butler API key
 
 ## Talking to Alfred
 
@@ -212,13 +210,27 @@ Which to use:
   Best when you are already running a link for tools or hooks, or holding many
   conversations at once — one socket carries them all.
 
-Two differences to know about:
+One difference to know about: sessions are ephemeral. If the connection drops mid-turn
+the SDK reopens the session and resends transparently; the conversation itself is
+persisted server-side, so nothing is lost.
+
+### Rejoining a turn already in progress
+
+A turn belongs to the conversation, not to whoever started it, so reopening a
+conversation mid-answer picks the reply back up as it is written:
+
+```typescript
+const convo = client.createConversation({ convoId, transport: link });
+const watching = convo.fetchProgressStream(chunk => render(chunk));
+// ...later
+watching.close();       // stop watching; the turn keeps running
+```
 
-- Sessions are ephemeral. If the connection drops mid-turn the SDK reopens the session
-  and resends transparently; the conversation itself is persisted server-side, so
-  nothing is lost.
-- The HTTP transport replays your own message back to you (it exists so a browser
-  reconnecting mid-turn sees it). A Link does not, since it has nothing to replay.
+Over a Link this rides the connection you already hold; over SSE it opens the HTTP
+progress stream. The payloads are identical either way, including your own message and
+the conversation's start — everything a client that arrived late needs to draw the turn
+from the beginning. Pass `{ afterEventId }` to be sent only what you have not already
+seen. A conversation with nothing running simply ends the stream.
 
 Neither transport can cancel a turn: `close()` stops delivery locally, and the reply is
 still generated and stored.