@butlerbot/sdk 0.0.26 → 0.0.28

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;
@@ -159,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, () => ({
@@ -190,17 +192,20 @@ class Conversation {
     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: (payload) => cb(payload),
+                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
@@ -226,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;
@@ -262,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,34 @@
+/**
+ * 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
+ *
+ * Deltas are also sent bare: no metadata block, since it is the same on every frame of a
+ * message and several times the size of the few characters a delta carries. The frame that
+ * opens a message brings it, and the one that finishes it brings it again.
+ *
+ * Callers should not have to care about any of that. This puts the message back together,
+ * so `payload.message` is the whole message so far exactly as it always was, restores the
+ * metadata onto every event, 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 what every message the stream is still writing
+ * has said so far, 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,92 @@
+"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
+ *
+ * Deltas are also sent bare: no metadata block, since it is the same on every frame of a
+ * message and several times the size of the few characters a delta carries. The frame that
+ * opens a message brings it, and the one that finishes it brings it again.
+ *
+ * Callers should not have to care about any of that. This puts the message back together,
+ * so `payload.message` is the whole message so far exactly as it always was, restores the
+ * metadata onto every event, 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 what every message the stream is still writing
+ * has said so far, so a turn and a progress stream never see each other's.
+ */
+function createStreamAccumulator() {
+    /** Text so far and the metadata it was opened with, per streamed id. */
+    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 held = values.get(id);
+        const text = typeof delta === "string" ? (held?.text ?? "") + delta : whole;
+        // Deltas are sent without metadata, because it is identical on every frame of a
+        // message and many times the size of the text. The frame that opened the message
+        // carried it, so it is remembered here and handed back on every event — a caller
+        // sees it throughout, exactly as when the server repeated it a thousand times.
+        const metadata = event.metadata ?? held?.metadata;
+        // 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, metadata });
+        return {
+            ...response,
+            data: {
+                ...response.data,
+                response: {
+                    ...event,
+                    ...(metadata !== undefined ? { metadata } : {}),
+                    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/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.26",
+	"version": "0.0.28",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -39,6 +39,43 @@ Or, when you only want the answer:
 const { text } = await convo.ask("Hey there Alfred!");
 ```
 
+### Streaming
+
+Alfred streams a reply as it writes it. A message opens with a whole value, is extended a
+piece at a time, and finishes whole again. No event carries both:
+
+```jsonc
+{ "messageId": "m1", "message": "Good day", "completed": false, "metadata": {...} }
+{ "messageId": "m1", "delta": " to you", "completed": false }
+{ "messageId": "m1", "message": "Good day to you", "completed": true, "metadata": {...} }
+```
+
+Deltas travel bare — no metadata block, since it is identical on every frame of a message
+and many times the size of the few characters a delta carries. The SDK remembers it from
+the frame that opened the message and puts it back, so **every event you receive has both
+the whole message and its metadata**, exactly as it always did:
+
+```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: deltas with no `message`
+beside them and no metadata. 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: