@butlerbot/sdk 0.0.27 → 0.0.29

package/dist/link/link.d.ts

@@ -123,6 +123,8 @@ export declare class Link {
      * never needs to ask.
      */
     private lastInboundAt;
+    /** Ids of keepalive pulses, so their pongs can be dropped instead of shown as logs. */
+    private pulses;
     private closedByUs;
     constructor(options: LinkOptions);
     /** Adds a tool Alfred can call. Registered on connect, or immediately if already open. */
@@ -211,12 +213,28 @@ export declare class Link {
      * 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.
+     *
+     * Not asking is not the same as saying nothing, though. The server reaps connections
+     * that have sent it no frames for 100s, because a socket the client walked away from
+     * still answers websocket pings at the network layer and only the client's own frames
+     * prove someone is still there. A link busy receiving a long turn used to go completely
+     * silent for as long as the turn ran and got closed as idle — `1001 idle: no frames
+     * received`, mid-response again. So a busy interval still sends a pulse; it just does
+     * not wait for the reply, which is the half that could not survive a full send queue.
      */
     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;
+    /**
+     * A ping sent with no deadline and no interest in the answer.
+     *
+     * Its only job is to land on the server so the connection does not look abandoned. A
+     * failure here is not evidence of anything — inbound frames already proved the socket
+     * works — so it stays quiet and lets the real heartbeat make that call.
+     */
+    private pulse;
     /** 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. */

package/dist/link/link.js

@@ -56,6 +56,8 @@ class Link {
          * never needs to ask.
          */
         this.lastInboundAt = 0;
+        /** Ids of keepalive pulses, so their pongs can be dropped instead of shown as logs. */
+        this.pulses = new Set();
         this.closedByUs = false;
         this.options = {
             ...DEFAULTS,
@@ -390,6 +392,14 @@ class Link {
      * 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.
+     *
+     * Not asking is not the same as saying nothing, though. The server reaps connections
+     * that have sent it no frames for 100s, because a socket the client walked away from
+     * still answers websocket pings at the network layer and only the client's own frames
+     * prove someone is still there. A link busy receiving a long turn used to go completely
+     * silent for as long as the turn ran and got closed as idle — `1001 idle: no frames
+     * received`, mid-response again. So a busy interval still sends a pulse; it just does
+     * not wait for the reply, which is the half that could not survive a full send queue.
      */
     startHeartbeat(generation) {
         if (!this.options.heartbeatMs)
@@ -408,8 +418,10 @@ class Link {
             if (generation !== this.generation)
                 return;
             // 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.
+            // alive and there is nothing to ask. Tell the server we are still here and
+            // wait out the rest of its silence instead.
             if (Date.now() - this.lastInboundAt < this.options.heartbeatMs) {
+                this.pulse();
                 return this.scheduleHeartbeat(generation);
             }
             this.ping(generation);
@@ -440,6 +452,21 @@ class Link {
             this.dropSocket(generation, 4000, "heartbeat timeout");
         });
     }
+    /**
+     * A ping sent with no deadline and no interest in the answer.
+     *
+     * Its only job is to land on the server so the connection does not look abandoned. A
+     * failure here is not evidence of anything — inbound frames already proved the socket
+     * works — so it stays quiet and lets the real heartbeat make that call.
+     */
+    pulse() {
+        try {
+            this.pulses.add(this.send("ping", {}));
+        }
+        catch {
+            this.debug("could not send the keepalive pulse, leaving it to the next heartbeat");
+        }
+    }
     /** 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));
@@ -452,6 +479,8 @@ class Link {
         if (this.heartbeat)
             clearTimeout(this.heartbeat);
         this.heartbeat = undefined;
+        // Pongs owed by a socket that is going away will never arrive.
+        this.pulses.clear();
     }
     // =============================================
     // WAITING
@@ -652,6 +681,10 @@ class Link {
                 waiting.onFrame?.(frame);
             return;
         }
+        // The pong to a keepalive pulse. Nothing is waiting for it, and it is not a log
+        // anyone asked to see.
+        if (frame.replyTo && this.pulses.delete(frame.replyTo))
+            return;
         switch (frame.type) {
             case "tool.call":
                 this.handleToolCall(frame);

package/dist/modules/stream_accumulator.d.ts

@@ -12,9 +12,14 @@
  *     { 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.
+ * 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
@@ -23,7 +28,7 @@
 /**
  * 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.
+ * 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

@@ -13,9 +13,14 @@
  *     { 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.
+ * 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
@@ -31,10 +36,11 @@ const STREAMED_FIELDS = {
 /**
  * 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.
+ * 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;
@@ -52,19 +58,26 @@ function createStreamAccumulator() {
         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;
+        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);
+            values.set(id, { text, metadata });
         return {
             ...response,
             data: {
                 ...response.data,
                 response: {
                     ...event,
+                    ...(metadata !== undefined ? { metadata } : {}),
                     payload: {
                         ...event.payload,
                         [fields.text]: text,

package/package.json

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

package/readme.md

@@ -41,15 +41,19 @@ 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:
+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 to you", "completed": false }  // whole: replace
-{ "messageId": "m1", "delta": " to you", "completed": false }            // added: append
+{ "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": {...} }
 ```
 
-The SDK puts them back together, so `payload.message` is always the whole message:
+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) => {
@@ -68,9 +72,9 @@ stuttering one — append it when it is there, and replace with `message` when i
 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.
+`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