@butlerbot/sdk 0.0.25 → 0.0.27

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;
@@ -112,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. */
@@ -185,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

@@ -49,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,
@@ -368,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;
     }
     // =============================================
@@ -585,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

@@ -64,6 +64,18 @@ export type ConversationOptions<V extends APIPath = "v4"> = {
      * have — everything else, including the payloads you receive, is identical.
      */
     transport?: "sse" | Link;
+    /**
+     * Whether streamed text is put back together for you. On by default.
+     *
+     * The server streams each message a piece at a time. With this on, `payload.message`
+     * is the whole message so far — what it has always been — and `payload.delta` is what
+     * the event added, for anyone who would rather append than re-render.
+     *
+     * Turn it off to be handed the wire payloads untouched, where a piece arrives as
+     * `delta` with no `message` beside it. Worth it only if you are appending anyway and
+     * want nothing between you and the socket.
+     */
+    accumulateStream?: boolean;
 };
 export declare class Conversation<V extends APIPath = "v4"> {
     convoId?: string;
@@ -73,6 +85,7 @@ export declare class Conversation<V extends APIPath = "v4"> {
     private options?;
     private events;
     private transport;
+    private accumulateStream;
     /** The link carrying this conversation, when it is not on SSE. */
     readonly link?: Link;
     private endpoints;
@@ -137,8 +150,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
@@ -147,6 +172,13 @@ export declare class Conversation<V extends APIPath = "v4"> {
         lastEventId?: string;
         includeCompleted?: boolean;
     }): Promise<TurnProgressEntryForVersion<V>[] | undefined>;
+    /**
+     * One stream's worth of delivery: rebuilds whole values, then hands them to the caller.
+     *
+     * The accumulator is made per stream rather than per conversation because it holds the
+     * text of whatever is still being written, and two streams are two different answers.
+     */
+    private receiver;
     /** Sends a message into the conversation */
     send(message: string, cb: (chunk: RequestResponseByVersion[V]) => any, options?: DialogueRequestOptions): ConversationStream;
     /**

package/dist/modules/conversation.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Conversation = void 0;
 const config_1 = require("../config");
 const emitter_1 = require("../util/emitter");
+const stream_accumulator_1 = require("./stream_accumulator");
 const transport_link_1 = require("./transport_link");
 const transport_sse_1 = require("./transport_sse");
 const url_formatter_1 = require("../util/url_formatter");
@@ -22,6 +23,7 @@ class Conversation {
         };
         this.apiKey = config.apiKey;
         this.debug = config.debug || false;
+        this.accumulateStream = config.accumulateStream ?? true;
         if (config.transport && config.transport !== "sse") {
             this.link = config.transport;
             this.transport = new transport_link_1.LinkConversationTransport(config.transport, () => ({
@@ -176,12 +178,34 @@ 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");
+        // A watcher joins mid-answer: it is caught up with whole values and then follows the
+        // rest a piece at a time, which the accumulator handles either way.
+        const receive = this.receiver(cb);
+        if (this.transport.attach) {
+            return this.transport.attach({
+                chatId: this.convoId,
+                ...(options?.afterEventId ? { afterEventId: options.afterEventId } : {}),
+            }, {
+                payload: receive,
+                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) });
+        return (0, transport_sse_1.streamSSE)(url, { debug: this.debug, onPayload: receive });
     }
     /**
      * Fetches the conversation progress from the server
@@ -207,15 +231,28 @@ class Conversation {
         return data.events;
     }
     // LIFE CYCLE
+    /**
+     * One stream's worth of delivery: rebuilds whole values, then hands them to the caller.
+     *
+     * The accumulator is made per stream rather than per conversation because it holds the
+     * text of whatever is still being written, and two streams are two different answers.
+     */
+    receiver(cb) {
+        if (!this.accumulateStream)
+            return (payload) => cb(payload);
+        const accumulate = (0, stream_accumulator_1.createStreamAccumulator)();
+        return (payload) => cb(accumulate(payload));
+    }
     /** Sends a message into the conversation */
     send(message, cb, options) {
+        const receive = this.receiver(cb);
         return this.transport.send({
             message,
             ...this.options, // options set for convo
             ...options, // overwrite convo's for this call
             ...(this.convoId ? { chatId: this.convoId } : {}),
         }, {
-            payload: (payload) => cb(payload),
+            payload: receive,
             convoId: (convoId) => {
                 if (this.convoId === convoId)
                     return;
@@ -243,10 +280,14 @@ class Conversation {
                 }
                 const response = chunk.data.response;
                 const metadata = chunk.data.response.metadata;
-                // Message chunks arrive cumulative, and Alfred's own notices are not part
-                // of the reply, so they are collected but not concatenated into it.
-                if (response.type === "message" && metadata?.participantId !== "system" && response.payload?.message) {
-                    text = response.payload.message;
+                // Alfred's own notices are not part of the reply, so they are collected but
+                // not concatenated into it. Appending the piece and replacing on a whole
+                // value is right whether or not the caller left accumulation on.
+                if (response.type === "message" && metadata?.participantId !== "system") {
+                    if (typeof response.payload?.delta === "string")
+                        text += response.payload.delta;
+                    else if (response.payload?.message)
+                        text = response.payload.message;
                 }
                 if (chunk.data.quitStream)
                     resolve({ text, convoId: this.convoId, events });

package/dist/modules/stream_accumulator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * STREAM ACCUMULATION
+ * ===================
+ *
+ * The server streams text a piece at a time.
+ *
+ * It used to send the whole message again on every token, which is O(N²) bytes for an
+ * N-token reply — slow everywhere, and fatal on a Link websocket, where the answer queues
+ * ahead of the connection's own heartbeat until this SDK closes it mid-sentence. A
+ * streamed value now arrives as one of two shapes, and never both:
+ *
+ *     { messageId, message: "Good day to you", completed }   // the whole value: replace
+ *     { messageId, delta: " to you", completed: false }      // what was added: append
+ *
+ * Callers should not have to care. This puts the message back together, so
+ * `payload.message` is the whole message so far exactly as it always was, and keeps
+ * `payload.delta` for anyone who would rather append than re-render.
+ *
+ * Whole values arrive for the last event of a message and for anything replaying after a
+ * reconnect, and they replace rather than extend. That is what makes a reconnect cheap and
+ * a dropped delta harmless, and it is handled here so no caller has to know about it.
+ */
+/**
+ * Rebuilds whole values from a stream of pieces.
+ *
+ * Stateful, and one per stream: it holds the text of every message the stream is still
+ * writing, so a turn and a progress stream never see each other's.
+ */
+export declare function createStreamAccumulator(): (payload: unknown) => unknown;

package/dist/modules/stream_accumulator.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * STREAM ACCUMULATION
+ * ===================
+ *
+ * The server streams text a piece at a time.
+ *
+ * It used to send the whole message again on every token, which is O(N²) bytes for an
+ * N-token reply — slow everywhere, and fatal on a Link websocket, where the answer queues
+ * ahead of the connection's own heartbeat until this SDK closes it mid-sentence. A
+ * streamed value now arrives as one of two shapes, and never both:
+ *
+ *     { messageId, message: "Good day to you", completed }   // the whole value: replace
+ *     { messageId, delta: " to you", completed: false }      // what was added: append
+ *
+ * Callers should not have to care. This puts the message back together, so
+ * `payload.message` is the whole message so far exactly as it always was, and keeps
+ * `payload.delta` for anyone who would rather append than re-render.
+ *
+ * Whole values arrive for the last event of a message and for anything replaying after a
+ * reconnect, and they replace rather than extend. That is what makes a reconnect cheap and
+ * a dropped delta harmless, and it is handled here so no caller has to know about it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStreamAccumulator = createStreamAccumulator;
+/** Which field of a payload holds the streamed text, and what identifies it. */
+const STREAMED_FIELDS = {
+    message: { id: "messageId", text: "message" },
+    reasoning: { id: "reasoningId", text: "reasoning" },
+};
+/**
+ * Rebuilds whole values from a stream of pieces.
+ *
+ * Stateful, and one per stream: it holds the text of every message the stream is still
+ * writing, so a turn and a progress stream never see each other's.
+ */
+function createStreamAccumulator() {
+    const values = new Map();
+    return (payload) => {
+        const response = payload;
+        const event = response?.data?.response;
+        const fields = event?.type ? STREAMED_FIELDS[event.type] : undefined;
+        if (!event?.payload || !fields)
+            return payload;
+        const id = event.payload[fields.id];
+        if (typeof id !== "string")
+            return payload;
+        // Which field is there is the whole discriminant — never `completed`, which says
+        // nothing about the shape: a whole value arrives incomplete whenever this client is
+        // being caught up in the middle of a message.
+        const { delta } = event.payload;
+        const whole = event.payload[fields.text];
+        if (typeof delta !== "string" && typeof whole !== "string")
+            return payload;
+        const text = typeof delta === "string" ? (values.get(id) ?? "") + delta : whole;
+        // A finished value is the last anyone will hear of that id. Holding it would only
+        // leak, and ids are reused across the steps of a turn.
+        if (event.payload.completed)
+            values.delete(id);
+        else
+            values.set(id, text);
+        return {
+            ...response,
+            data: {
+                ...response.data,
+                response: {
+                    ...event,
+                    payload: {
+                        ...event.payload,
+                        [fields.text]: text,
+                        // Kept as it came: present means this event appended, absent means it
+                        // replaced. Callers rendering incrementally read exactly this.
+                        ...(typeof delta === "string" ? { delta } : {}),
+                    },
+                },
+            },
+        };
+    };
+}

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/dist/types/conversation/v3/conversation_v3.d.ts

@@ -144,20 +144,36 @@ export type ResponseMetadata = {
     };
 };
 export type MessagePayload = {
-    /** The message content */
+    /**
+     * The message content, whole: everything written so far.
+     *
+     * The server streams a message a piece at a time; this is the SDK putting it back
+     * together, so it reads the same as it always has. With `accumulateStream: false` you
+     * get the wire payloads instead, where a piece arrives as `delta` and this is absent.
+     */
     message: string;
     /** The UUID of this message */
     messageId: string;
     /** Whether this message chunk is the final one */
     completed: boolean;
+    /**
+     * What this event added to the message, when it added anything.
+     *
+     * Append this instead of re-rendering `message` and you never redraw text you already
+     * have. Absent when the whole value arrived at once — the last event of a message, and
+     * whatever catches you up after a reconnect — which replaces rather than extends.
+     */
+    delta?: string;
 };
 export type ReasoningPayload = {
-    /** The reasoning content */
+    /** The reasoning content, whole. See {@link MessagePayload.message}. */
     reasoning: string;
     /** The UUID of this reasoning */
     reasoningId: string;
     /** Whether this reasoning chunk is the final one */
     completed: boolean;
+    /** What this event added. See {@link MessagePayload.delta}. */
+    delta?: string;
 };
 export type FilePayload = {
     /** The file URL */

package/dist/types/response/v5/ai_response_v5.d.ts

@@ -55,20 +55,36 @@ export type BaseResponseMetadata = {
     participantId?: string;
 };
 export type MessagePayload = {
-    /** The message content */
+    /**
+     * The message content, whole: everything written so far.
+     *
+     * The server streams a message a piece at a time; this is the SDK putting it back
+     * together, so it reads the same as it always has. With `accumulateStream: false` you
+     * get the wire payloads instead, where a piece arrives as `delta` and this is absent.
+     */
     message: string;
     /** The UUID of this message */
     messageId: string;
     /** Whether this message chunk is the final one */
     completed: boolean;
+    /**
+     * What this event added to the message, when it added anything.
+     *
+     * Append this instead of re-rendering `message` and you never redraw text you already
+     * have. Absent when the whole value arrived at once — the last event of a message, and
+     * whatever catches you up after a reconnect — which replaces rather than extends.
+     */
+    delta?: string;
 };
 export type ReasoningPayload = {
-    /** The reasoning content */
+    /** The reasoning content, whole. See {@link MessagePayload.message}. */
     reasoning: string;
     /** The UUID of this reasoning */
     reasoningId: string;
     /** Whether this reasoning chunk is the final one */
     completed: boolean;
+    /** What this event added. See {@link MessagePayload.delta}. */
+    delta?: string;
 };
 export type FilePayload = {
     /** The file URL */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.25",
+	"version": "0.0.27",
 	"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
 
@@ -41,6 +39,39 @@ Or, when you only want the answer:
 const { text } = await convo.ask("Hey there Alfred!");
 ```
 
+### Streaming
+
+Alfred streams a reply as it writes it. Each event carries either the whole message so far
+or just the piece it added, never both:
+
+```jsonc
+{ "messageId": "m1", "message": "Good day to you", "completed": false }  // whole: replace
+{ "messageId": "m1", "delta": " to you", "completed": false }            // added: append
+```
+
+The SDK puts them back together, so `payload.message` is always the whole message:
+
+```typescript
+convo.send("Tell me a story", (res) => {
+  if (!res.success || res.data.response.type !== "message") return;
+
+  const { message, delta } = res.data.response.payload;
+  // message — everything written so far
+  // delta   — just what this event added, when it added anything
+});
+```
+
+Render `message` and you need do nothing else. Render `delta` and you never re-draw text
+you already have, which for a long reply is the difference between a smooth stream and a
+stuttering one — append it when it is there, and replace with `message` when it is not.
+`delta` is absent in two cases: the last event of a message, and whatever catches you up
+after a reconnect. Do not read `completed` to tell the two apart — a whole message arrives
+with `completed: false` whenever you are being caught up mid-answer.
+
+`accumulateStream: false` hands you the wire payloads untouched, where a piece arrives as
+`delta` with no `message` beside it. Only worth it if you are appending anyway and want
+nothing between you and the socket.
+
 ## Link
 
 A Link is a live connection to Alfred. It does three things:
@@ -212,13 +243,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.