@butlerbot/sdk 0.0.33 → 0.0.34

package/dist/config.d.ts

@@ -1,5 +1,12 @@
 export declare const CONFIG: {
     server: string;
+    /**
+     * Where links connect.
+     *
+     * Not the core server: links are carried by their own service, so the SDK holds two
+     * addresses rather than one.
+     */
+    link: string;
     healthcheckPath: string;
     paths: {
         conversation: {
@@ -55,3 +62,15 @@ export declare const CONFIG: {
     };
 };
 export type APIPath = keyof typeof CONFIG.paths.conversation;
+/**
+ * Which server a link should connect to.
+ *
+ * `linkUrl` names it outright and always wins. Failing that, a `serverUrl` pointing anywhere
+ * other than the hosted core is taken at its word: a self-hosted stack is usually one address,
+ * and sending an API key to a host nobody named would be a worse surprise than a wrong path.
+ * Otherwise it is the hosted link service, which is what the core server used to be and is not.
+ */
+export declare function resolveLinkUrl(config: {
+    linkUrl?: string;
+    serverUrl?: string;
+}): string;

package/dist/config.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CONFIG = void 0;
+exports.resolveLinkUrl = resolveLinkUrl;
 exports.CONFIG = {
     server: "https://core.butler.now",
+    /**
+     * Where links connect.
+     *
+     * Not the core server: links are carried by their own service, so the SDK holds two
+     * addresses rather than one.
+     */
+    link: "https://link.butler.now",
     healthcheckPath: "/api/healthcheck",
     paths: {
         conversation: {
@@ -45,3 +53,19 @@ exports.CONFIG = {
         }
     }
 };
+const withoutTrailingSlash = (url) => url.replace(/\/+$/, "");
+/**
+ * Which server a link should connect to.
+ *
+ * `linkUrl` names it outright and always wins. Failing that, a `serverUrl` pointing anywhere
+ * other than the hosted core is taken at its word: a self-hosted stack is usually one address,
+ * and sending an API key to a host nobody named would be a worse surprise than a wrong path.
+ * Otherwise it is the hosted link service, which is what the core server used to be and is not.
+ */
+function resolveLinkUrl(config) {
+    if (config.linkUrl)
+        return config.linkUrl;
+    if (config.serverUrl && withoutTrailingSlash(config.serverUrl) !== withoutTrailingSlash(exports.CONFIG.server))
+        return config.serverUrl;
+    return exports.CONFIG.link;
+}

package/dist/index.d.ts

@@ -9,6 +9,14 @@ type OptionalApiKey<T> = Omit<T, "apiKey"> & {
 export type ButlerBotClientOptions = {
     /** The server endpoint, API calls are sent here */
     serverUrl?: string;
+    /**
+     * Where links connect. Defaults to the hosted link service.
+     *
+     * Links are no longer carried by the core server, so this is a second address rather than
+     * a path on the first. A `serverUrl` pointing at your own stack is used for links too,
+     * unless this names somewhere else.
+     */
+    linkUrl?: string;
     /** The API key to use with ButlerBot */
     apiKey: string;
     /** Whether to enable debug logs */
@@ -17,6 +25,7 @@ export type ButlerBotClientOptions = {
 export declare class ButlerBotClient {
     private apiKey;
     private serverUrl;
+    private linkUrl;
     private debug;
     constructor(config: ButlerBotClientOptions);
     /** Checks the health of the server returning true if server is alive */
@@ -25,7 +34,10 @@ export declare class ButlerBotClient {
     createConversation<V extends APIPath = "v4">(config?: OptionalApiKey<ConversationOptions<V>>): Conversation<V>;
     /**
      * Creates a Link: a live connection that can register tools and hooks, and carry
-     * conversations. Inherits the client's API key and server URL.
+     * conversations. Inherits the client's API key and link URL.
+     *
+     * The link URL, not the server URL: links are served by their own service. Pass
+     * `serverUrl` here, or `linkUrl` to the client, to point somewhere else.
      */
     createLink(config: OptionalApiKey<LinkOptions>): Link;
     /** Get current usage policy data */
@@ -33,7 +45,8 @@ export declare class ButlerBotClient {
 }
 export * from "./types/type_registry";
 export * from "./link";
-export { Conversation, ConversationOptions };
+export { Conversation };
+export type { ConversationOptions };
 export type { APIPath };
 export type { ConversationStream, ConversationTransport, TransportTurnRequest, TransportHandlers, } from "./modules/transport";
 export { LinkConversationTransport } from "./modules/transport_link";

package/dist/index.js

@@ -20,10 +20,23 @@ const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
 Object.defineProperty(exports, "Conversation", { enumerable: true, get: function () { return conversation_1.Conversation; } });
 const usage_1 = require("./modules/usage");
+/**
+ * The options a caller actually gave, with the keys they left out removed.
+ *
+ * A client's own API key and URLs are the fallback for whatever a factory call omits, and the
+ * usual way to omit something is to forward an optional setting that happens to be unset —
+ * `createLink({ serverUrl: process.env.LINK_URL })`. Spread as it stands, that `undefined`
+ * lands on top of the client's resolved value and erases it, so the link ends up at the hosted
+ * service rather than the self-hosted stack the client was pointed at. Absent means "not given".
+ */
+function given(config) {
+    return Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
+}
 class ButlerBotClient {
     constructor(config) {
         this.apiKey = config.apiKey;
         this.serverUrl = config.serverUrl || config_1.CONFIG.server;
+        this.linkUrl = (0, config_1.resolveLinkUrl)(config);
         this.debug = config.debug || false;
     }
     /** Checks the health of the server returning true if server is alive */
@@ -41,14 +54,17 @@ class ButlerBotClient {
     }
     /** Spawns a new Conversation, inherits api key and server URL */
     createConversation(config = {}) {
-        return new conversation_1.Conversation({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
+        return new conversation_1.Conversation({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...given(config) });
     }
     /**
      * Creates a Link: a live connection that can register tools and hooks, and carry
-     * conversations. Inherits the client's API key and server URL.
+     * conversations. Inherits the client's API key and link URL.
+     *
+     * The link URL, not the server URL: links are served by their own service. Pass
+     * `serverUrl` here, or `linkUrl` to the client, to point somewhere else.
      */
     createLink(config) {
-        return new link_1.Link({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
+        return new link_1.Link({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.linkUrl, ...given(config) });
     }
     /** Get current usage policy data */
     getUsagePolicyData(config) {

package/dist/link/link.d.ts

@@ -49,6 +49,7 @@ export type LinkOptions = {
      * one takes over and the older one's registrations are released.
      */
     linkId: string;
+    /** The link service. Defaults to the hosted one, which is not the core server. */
     serverUrl?: string;
     /** Informational, shown in server logs. Defaults to the SDK name. */
     client?: string;

package/dist/link/link.js

@@ -66,7 +66,7 @@ class Link {
             reconnect: true,
             debug: false,
             client: "@butlerbot/sdk",
-            serverUrl: config_1.CONFIG.server,
+            serverUrl: config_1.CONFIG.link,
             socketFactory: socket_1.defaultSocketFactory,
             ...stripUndefined(options),
         };

package/dist/link/protocol.d.ts

@@ -236,12 +236,19 @@ export type LinkServerPayloads = {
         chatId?: string;
         message: string;
     };
+    /**
+     * A turn ended, one way or another.
+     *
+     * `lastEventId` comes with `turn_suspended`: the turn is still being answered somewhere
+     * and this is where a `conversation.attach` should pick it back up.
+     */
     "conversation.done": {
         chatId?: string;
         ok: boolean;
         code?: string;
         error?: string;
         message?: string;
+        lastEventId?: string;
     };
     /** A turn was stopped. `mode` is what was applied, `requestedMode` what was asked for. */
     "conversation.stopped": {

package/dist/modules/transport_link.d.ts

@@ -50,6 +50,35 @@ export declare class LinkConversationTransport implements ConversationTransport
      */
     attach(request: TransportAttachRequest, handlers: TransportHandlers): ConversationStream;
     private runTurn;
+    /**
+     * One `conversation.attach`: streams a turn's events to the caller and resolves with how
+     * that watch ended.
+     *
+     * Shared by watching somebody else's turn and by rejoining one of our own, because from
+     * here the two are the same act. `progress` is carried rather than returned: a watch that
+     * dies halfway still has to leave behind where it got to, or a resume would replay from
+     * the beginning and the caller would read the answer twice.
+     */
+    private watch;
+    /**
+     * Picks a turn back up after losing sight of it.
+     *
+     * Two ways to lose one, one way to get it back. The socket can go — a deploy of the link
+     * service, a proxy timing out — which rejects the exchange carrying the turn. Or core can
+     * suspend the turn at its own deploy and hand it to another instance, which the link
+     * service follows for two minutes before giving up and saying `turn_suspended`. Either way
+     * the turn is still being answered and the conversation still holds it, so this re-attaches
+     * from the last event the caller was actually given and the stream reads as one answer.
+     *
+     * `no_active_turn` is the ambiguous reply and it is deliberately not treated as an ending:
+     * during a handover it means "not picked up yet" far more often than it means "gone", and
+     * the window is what decides between them.
+     *
+     * Nothing here throws. It runs behind a stream the caller already holds, so the outcomes
+     * that matter are the ones delivered into it: a completion, or a failure that says plainly
+     * that the answer was lost track of rather than that it failed.
+     */
+    private resume;
     /** Opens a session, or reuses the open one when it is for the same conversation. */
     private session;
 }

package/dist/modules/transport_link.js

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LinkConversationTransport = void 0;
 const protocol_1 = require("../link/protocol");
 const transport_1 = require("./transport");
+/**
+ * How long to keep trying to pick a lost turn back up before giving up on it.
+ *
+ * A turn belongs to its conversation, not to the socket that asked for one, so neither losing
+ * the connection nor losing the instance answering it — which is what a deploy does — ends it.
+ * Long enough to outlast a deploy of either service, short enough that a caller awaiting a
+ * reply is not left there forever when the turn really is gone.
+ */
+const RESUME_WINDOW_MS = 60000;
+/** Waits between attempts to pick a turn back up. The last value repeats. */
+const RESUME_BACKOFF_MS = [250, 500, 1000, 2000, 4000, 5000];
 /**
  * Carries a turn over an existing Link connection.
  *
@@ -18,20 +29,20 @@ class LinkConversationTransport {
         link.on("disconnect", () => { this.sessionId = undefined; });
     }
     send(request, handlers) {
-        let closed = false;
+        const listening = { closed: false };
         const deliver = {
-            payload: (payload) => { if (!closed)
+            payload: (payload) => { if (!listening.closed)
                 handlers.payload(payload); },
-            convoId: (convoId) => { if (!closed)
+            convoId: (convoId) => { if (!listening.closed)
                 handlers.convoId(convoId); },
         };
-        void this.runTurn(request, deliver, true).catch((error) => {
+        void this.runTurn(request, deliver, true, listening).catch((error) => {
             const failure = 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);
             deliver.payload(failure);
         });
-        return { close: () => { closed = true; } };
+        return { close: () => { listening.closed = true; } };
     }
     /**
      * Stops a running turn.
@@ -96,57 +107,46 @@ class LinkConversationTransport {
      * ordinary answer for one that is simply idle.
      */
     attach(request, handlers) {
-        let closed = false;
-        const deliver = (payload) => { if (!closed)
+        const listening = { closed: false };
+        const deliver = (payload) => { if (!listening.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;
+        const progress = { chatId: request.chatId, lastEventId: request.afterEventId, sawCompletion: false };
+        // Watching is allowed to end in silence, which is why `quietWhenGone` is true here and
+        // false for a turn of our own: nobody is waiting on an answer to a question they asked.
+        const resume = () => this.resume(request.chatId, progress, deliver, listening, { quietWhenGone: true });
+        void this.watch(request.chatId, progress, deliver).then(async (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;
+            // The turn is alive, somewhere this connection can no longer see. Following it is
+            // the entire point of being here.
+            if (payload.code === "turn_suspended") {
+                if (payload.lastEventId)
+                    progress.lastEventId = payload.lastEventId;
+                await resume();
+                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) => {
+        }, async (error) => {
             if (error instanceof protocol_1.LinkError && error.code === "no_active_turn")
                 return;
+            // The socket went while we were watching. The turn did not go with it.
+            if (error instanceof protocol_1.LinkError && error.code === "disconnected") {
+                await resume();
+                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)
+                if (listening.closed)
                     return;
-                closed = true;
+                listening.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 });
@@ -157,15 +157,14 @@ class LinkConversationTransport {
             },
         };
     }
-    async runTurn(request, handlers, mayRetry) {
+    async runTurn(request, handlers, mayRetry, listening) {
         const sessionId = await this.session(request);
-        let chatId = request.chatId ?? this.sessionChatId;
+        const progress = { chatId: request.chatId ?? this.sessionChatId, sawCompletion: false };
         let announcedChatId = false;
-        let sawCompletion = false;
         const learnChatId = (candidate) => {
             if (!candidate)
                 return;
-            chatId = candidate;
+            progress.chatId = candidate;
             this.sessionChatId = candidate;
             handlers.convoId(candidate);
             // Mirrors the HTTP transport's first byte, which tells a client which
@@ -176,13 +175,99 @@ class LinkConversationTransport {
                 handlers.payload((0, transport_1.convoStartedPayload)(candidate));
             }
         };
-        learnChatId(chatId);
-        const done = await this.link.exchange("conversation.chat", {
-            sessionId,
-            message: request.message,
-            ...(request.model ? { model: request.model } : {}),
-            ...(request.instructions ? { instructions: request.instructions } : {}),
-            ...(request.personality ? { personality: request.personality } : {}),
+        learnChatId(progress.chatId);
+        let done;
+        try {
+            done = await this.link.exchange("conversation.chat", {
+                sessionId,
+                message: request.message,
+                ...(request.model ? { model: request.model } : {}),
+                ...(request.instructions ? { instructions: request.instructions } : {}),
+                ...(request.personality ? { personality: request.personality } : {}),
+            }, {
+                // 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;
+                        learnChatId(payload.chatId);
+                        if (payload.eventId)
+                            progress.lastEventId = payload.eventId;
+                        const event = payload.event;
+                        const final = event.type === "response_status" && Boolean(event.payload?.completed);
+                        if (final)
+                            progress.sawCompletion = true;
+                        handlers.payload({
+                            success: true,
+                            data: {
+                                response: event,
+                                ...(payload.chatId ?? progress.chatId ? { convoId: payload.chatId ?? progress.chatId } : {}),
+                                ...(final ? { quitStream: true } : {}),
+                            },
+                        });
+                        return;
+                    }
+                    if (frame.type === "conversation.notice") {
+                        const payload = frame.payload;
+                        learnChatId(payload.chatId);
+                        handlers.payload((0, transport_1.noticePayload)(payload.message, payload.chatId ?? progress.chatId));
+                    }
+                },
+            });
+        }
+        catch (error) {
+            // The socket went while the turn was running. The turn did not go with it: it
+            // belongs to the conversation, and the conversation outlives this connection.
+            if (progress.chatId && error instanceof protocol_1.LinkError && error.code === "disconnected") {
+                await this.resume(progress.chatId, progress, handlers.payload, listening, { quietWhenGone: false });
+                return;
+            }
+            throw error;
+        }
+        const payload = done.payload;
+        learnChatId(payload.chatId);
+        if (payload.ok) {
+            // Nearly always the pipeline's own completion event has already closed the
+            // stream; this is for the turn that ended without one.
+            if (!progress.sawCompletion)
+                handlers.payload((0, transport_1.completedPayload)(payload.chatId ?? progress.chatId));
+            return;
+        }
+        // The session died with a connection we have since replaced. Reopening it is
+        // invisible to the caller, and the message has not been delivered yet.
+        if (payload.code === "unknown_session" && mayRetry) {
+            this.sessionId = undefined;
+            await this.runTurn(request, handlers, false, listening);
+            return;
+        }
+        // Core suspended the turn at a deploy and handed it to another instance, and the link
+        // service followed it as far as it could. The answer is still being written; rejoining
+        // it is the difference between a deploy costing a reply and costing nothing.
+        if (payload.code === "turn_suspended" && progress.chatId) {
+            if (payload.lastEventId)
+                progress.lastEventId = payload.lastEventId;
+            await this.resume(progress.chatId, progress, handlers.payload, listening, { quietWhenGone: false });
+            return;
+        }
+        handlers.payload((0, transport_1.failurePayload)(
+        // `turn_failed` means the dialogue itself failed, and then `error` holds the
+        // code the HTTP transport would have reported.
+        payload.code === "turn_failed" ? payload.error ?? payload.code : payload.code ?? "link_error", payload.error ?? "The turn failed.", payload.message ?? payload.error ?? "I'm afraid that turn could not be completed.", payload.chatId ?? progress.chatId));
+    }
+    /**
+     * One `conversation.attach`: streams a turn's events to the caller and resolves with how
+     * that watch ended.
+     *
+     * Shared by watching somebody else's turn and by rejoining one of our own, because from
+     * here the two are the same act. `progress` is carried rather than returned: a watch that
+     * dies halfway still has to leave behind where it got to, or a resume would replay from
+     * the beginning and the caller would read the answer twice.
+     */
+    async watch(chatId, progress, deliver) {
+        const done = await this.link.exchange("conversation.attach", {
+            chatId,
+            ...(progress.lastEventId ? { afterEventId: progress.lastEventId } : {}),
         }, {
             // A turn takes as long as it takes; only the transport dying ends it early.
             timeoutMs: 0,
@@ -190,48 +275,112 @@ class LinkConversationTransport {
             onFrame: (frame) => {
                 if (frame.type === "conversation.event") {
                     const payload = frame.payload;
-                    learnChatId(payload.chatId);
+                    if (payload.eventId)
+                        progress.lastEventId = payload.eventId;
                     const event = payload.event;
                     const final = event.type === "response_status" && Boolean(event.payload?.completed);
                     if (final)
-                        sawCompletion = true;
-                    handlers.payload({
+                        progress.sawCompletion = true;
+                    deliver({
                         success: true,
                         data: {
                             response: event,
-                            ...(payload.chatId ?? chatId ? { convoId: payload.chatId ?? chatId } : {}),
+                            convoId: payload.chatId ?? chatId,
                             ...(final ? { quitStream: true } : {}),
                         },
                     });
                     return;
                 }
                 if (frame.type === "conversation.notice") {
-                    const payload = frame.payload;
-                    learnChatId(payload.chatId);
-                    handlers.payload((0, transport_1.noticePayload)(payload.message, payload.chatId ?? chatId));
+                    deliver((0, transport_1.noticePayload)(frame.payload.message, frame.payload.chatId ?? chatId));
                 }
             },
         });
-        const payload = done.payload;
-        learnChatId(payload.chatId);
-        if (payload.ok) {
-            // Nearly always the pipeline's own completion event has already closed the
-            // stream; this is for the turn that ended without one.
-            if (!sawCompletion)
-                handlers.payload((0, transport_1.completedPayload)(payload.chatId ?? chatId));
+        return done.payload;
+    }
+    /**
+     * Picks a turn back up after losing sight of it.
+     *
+     * Two ways to lose one, one way to get it back. The socket can go — a deploy of the link
+     * service, a proxy timing out — which rejects the exchange carrying the turn. Or core can
+     * suspend the turn at its own deploy and hand it to another instance, which the link
+     * service follows for two minutes before giving up and saying `turn_suspended`. Either way
+     * the turn is still being answered and the conversation still holds it, so this re-attaches
+     * from the last event the caller was actually given and the stream reads as one answer.
+     *
+     * `no_active_turn` is the ambiguous reply and it is deliberately not treated as an ending:
+     * during a handover it means "not picked up yet" far more often than it means "gone", and
+     * the window is what decides between them.
+     *
+     * Nothing here throws. It runs behind a stream the caller already holds, so the outcomes
+     * that matter are the ones delivered into it: a completion, or a failure that says plainly
+     * that the answer was lost track of rather than that it failed.
+     */
+    async resume(chatId, progress, deliver, listening, options) {
+        const deadline = Date.now() + RESUME_WINDOW_MS;
+        for (let attempt = 0; !listening.closed && Date.now() < deadline; attempt++) {
+            if (attempt > 0)
+                await pause(RESUME_BACKOFF_MS[Math.min(attempt - 1, RESUME_BACKOFF_MS.length - 1)]);
+            if (listening.closed)
+                return;
+            try {
+                // The link reconnects on its own; this waits for it rather than racing it.
+                await this.link.ready();
+            }
+            catch (error) {
+                // Closed for good means nobody is coming back. Anything else is the link still
+                // being down, which is exactly what the window is for.
+                if (error instanceof protocol_1.LinkError && error.code === "closed")
+                    break;
+                continue;
+            }
+            // An attachment from before may still be registered against a connection that is
+            // itself still alive, and the server allows only one per conversation. Dropping it
+            // first costs nothing when there is none to drop.
+            try {
+                this.link.send("conversation.detach", { chatId });
+            }
+            catch {
+                // Not connected. The server dropped the attachment with the socket.
+            }
+            let payload;
+            try {
+                payload = await this.watch(chatId, progress, deliver);
+            }
+            catch (error) {
+                if (error instanceof protocol_1.LinkError && error.code === "closed")
+                    break;
+                if (error instanceof protocol_1.LinkError && error.code === "no_active_turn" && options.quietWhenGone)
+                    return;
+                continue;
+            }
+            if (payload.ok) {
+                if (!progress.sawCompletion)
+                    deliver((0, transport_1.completedPayload)(payload.chatId ?? chatId));
+                return;
+            }
+            // Not picked up yet, or suspended again mid-hop. Both mean it is still moving.
+            if (payload.code === "no_active_turn") {
+                if (options.quietWhenGone)
+                    return;
+                continue;
+            }
+            if (payload.code === "turn_suspended") {
+                if (payload.lastEventId)
+                    progress.lastEventId = payload.lastEventId;
+                continue;
+            }
+            deliver((0, transport_1.failurePayload)(payload.code ?? "link_error", payload.error ?? "The turn could not be picked back up.", payload.message ?? payload.error ?? "I'm afraid I couldn't follow that response.", payload.chatId ?? chatId));
             return;
         }
-        // The session died with a connection we have since replaced. Reopening it is
-        // invisible to the caller, and the message has not been delivered yet.
-        if (payload.code === "unknown_session" && mayRetry) {
-            this.sessionId = undefined;
-            await this.runTurn(request, handlers, false);
+        if (listening.closed)
             return;
-        }
-        handlers.payload((0, transport_1.failurePayload)(
-        // `turn_failed` means the dialogue itself failed, and then `error` holds the
-        // code the HTTP transport would have reported.
-        payload.code === "turn_failed" ? payload.error ?? payload.code : payload.code ?? "link_error", payload.error ?? "The turn failed.", payload.message ?? payload.error ?? "I'm afraid that turn could not be completed.", payload.chatId ?? chatId));
+        // The completion already reached the caller; there is nothing left to say.
+        if (progress.sawCompletion)
+            return;
+        if (options.quietWhenGone)
+            return;
+        deliver((0, transport_1.failurePayload)("turn_suspended", "The turn could not be picked back up.", "I'm afraid I lost track of that answer. It may well have finished — reopen the conversation to see where it got to.", chatId));
     }
     /** Opens a session, or reuses the open one when it is for the same conversation. */
     async session(request) {
@@ -257,3 +406,10 @@ class LinkConversationTransport {
     }
 }
 exports.LinkConversationTransport = LinkConversationTransport;
+/** Waits, without keeping a Node process alive on its own. */
+function pause(ms) {
+    return new Promise(resolve => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}

package/package.json

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

package/readme.md

@@ -78,7 +78,12 @@ between you and the socket.
 
 ## Link
 
-A Link is a live connection to Alfred. It does three things:
+A Link is a live connection to Alfred, served by its own endpoint — `link.butler.now`,
+not the core API server. `createLink` goes there by default; pass `linkUrl` to the client
+(or `serverUrl` to `createLink`) to point somewhere else. A client given a `serverUrl` of
+its own — a self-hosted stack — uses that for links too.
+
+It does three things:
 
 - **Tools** — Alfred calls code that runs on your machine
 - **Hooks** — your code wakes the user's background agents when something happens
@@ -286,9 +291,15 @@ 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.
 
-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.
+A turn survives losing the connection it was asked for on. Sessions are ephemeral — the
+server drops one with its socket — but the turn belongs to the conversation, so when the
+socket goes mid-answer the SDK reconnects, rejoins the turn from the last event it gave
+you, and carries on into the same stream. The same holds when the platform deploys
+mid-turn and the answer is handed to another instance. A message that had not been
+delivered yet is simply sent again on a fresh session; one that had is never sent twice.
+
+If the turn cannot be picked back up within a minute, the stream ends with a failure that
+says so — the reply may still have finished, and reopening the conversation will show it.
 
 ### Rejoining a turn already in progress