@butlerbot/sdk 0.0.28 → 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/package.json

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