@pingagent/sdk 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -488,6 +488,25 @@ interface WsSubscriptionOptions {
     onError?: (err: Error) => void;
     /** Called when a WebSocket opens or reopens; e.g. Skill can run catchUp to fill gaps. */
     onOpen?: (conversationId: string) => void;
+    /**
+     * Keepalive heartbeat for idle connections to reduce "WS silently dropped" periods.
+     * This is client-side only (WS ping/pong control frames) and does not add inbox HTTP fetch cost.
+     */
+    heartbeat?: {
+        enable?: boolean;
+        /** If idle time >= this value, start pinging. */
+        idleThresholdMs?: number;
+        /** Minimum interval between pings while connection is idle. */
+        pingIntervalMs?: number;
+        /** How long to wait for pong after sending ping. If timeout, close the socket. */
+        pongTimeoutMs?: number;
+        /** Max consecutive missed pongs before closing. */
+        maxMissedPongs?: number;
+        /** Heartbeat scheduler tick frequency. */
+        tickMs?: number;
+        /** Jitter for ping interval to avoid synchronized bursts across many connections. */
+        jitter?: number;
+    };
 }
 declare class WsSubscription {
     private opts;
@@ -498,6 +517,8 @@ declare class WsSubscription {
     private stopped;
     /** Conversation IDs that were explicitly stopped (e.g. revoke); do not reconnect. */
     private stoppedConversations;
+    private heartbeatTimer;
+    private heartbeatStates;
     constructor(opts: WsSubscriptionOptions);
     start(): void;
     stop(): void;
@@ -508,6 +529,7 @@ declare class WsSubscription {
     stopConversation(conversationId: string): void;
     private wsUrl;
     private connectAsync;
+    private heartbeatTick;
     private scheduleReconnect;
     private connectAll;
     private syncConnections;

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   loadIdentity,
   saveIdentity,
   updateStoredToken
-} from "./chunk-YS54ADYV.js";
+} from "./chunk-V4IHFEJC.js";
 export {
   A2AAdapter,
   ContactManager,

package/dist/web-server.js

@@ -5,7 +5,7 @@ import {
   ensureTokenValid,
   loadIdentity,
   updateStoredToken
-} from "./chunk-YS54ADYV.js";
+} from "./chunk-V4IHFEJC.js";
 
 // src/web-server.ts
 import * as fs from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingagent/sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -26,9 +26,9 @@
     "commander": "^13.0.0",
     "uuid": "^11.0.0",
     "ws": "^8.0.0",
+    "@pingagent/protocol": "0.1.1",
     "@pingagent/schemas": "0.1.1",
-    "@pingagent/a2a": "0.1.1",
-    "@pingagent/protocol": "0.1.1"
+    "@pingagent/a2a": "0.1.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",

package/src/ws-subscription.ts

@@ -21,6 +21,26 @@ export interface WsSubscriptionOptions {
   onError?: (err: Error) => void;
   /** Called when a WebSocket opens or reopens; e.g. Skill can run catchUp to fill gaps. */
   onOpen?: (conversationId: string) => void;
+
+  /**
+   * Keepalive heartbeat for idle connections to reduce "WS silently dropped" periods.
+   * This is client-side only (WS ping/pong control frames) and does not add inbox HTTP fetch cost.
+   */
+  heartbeat?: {
+    enable?: boolean;
+    /** If idle time >= this value, start pinging. */
+    idleThresholdMs?: number;
+    /** Minimum interval between pings while connection is idle. */
+    pingIntervalMs?: number;
+    /** How long to wait for pong after sending ping. If timeout, close the socket. */
+    pongTimeoutMs?: number;
+    /** Max consecutive missed pongs before closing. */
+    maxMissedPongs?: number;
+    /** Heartbeat scheduler tick frequency. */
+    tickMs?: number;
+    /** Jitter for ping interval to avoid synchronized bursts across many connections. */
+    jitter?: number;
+  };
 }
 
 const RECONNECT_BASE_MS = 1000;
@@ -28,6 +48,16 @@ const RECONNECT_MAX_MS = 30_000;
 const RECONNECT_JITTER = 0.2;
 const LIST_CONVERSATIONS_INTERVAL_MS = 60_000;
 
+const DEFAULT_HEARTBEAT = {
+  enable: true,
+  idleThresholdMs: 25_000,
+  pingIntervalMs: 30_000,
+  pongTimeoutMs: 10_000,
+  maxMissedPongs: 2,
+  tickMs: 5_000,
+  jitter: 0.2,
+};
+
 export class WsSubscription {
   private opts: WsSubscriptionOptions;
   private connections = new Map<string, WebSocket>();
@@ -38,6 +68,18 @@ export class WsSubscription {
   /** Conversation IDs that were explicitly stopped (e.g. revoke); do not reconnect. */
   private stoppedConversations = new Set<string>();
 
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private heartbeatStates = new Map<
+    string,
+    {
+      lastRxAt: number;
+      lastPingAt: number;
+      nextPingAt: number;
+      missedPongs: number;
+      pongTimeout: ReturnType<typeof setTimeout> | null;
+    }
+  >();
+
   constructor(opts: WsSubscriptionOptions) {
     this.opts = opts;
   }
@@ -46,6 +88,12 @@ export class WsSubscription {
     this.stopped = false;
     this.connectAll();
     this.listInterval = setInterval(() => this.syncConnections(), LIST_CONVERSATIONS_INTERVAL_MS);
+
+    // Start heartbeat scheduler (idle-triggered) once per process.
+    const hb = this.opts.heartbeat ?? {};
+    if (hb.enable ?? DEFAULT_HEARTBEAT.enable) {
+      this.heartbeatTimer = setInterval(() => this.heartbeatTick(), hb.tickMs ?? DEFAULT_HEARTBEAT.tickMs);
+    }
   }
 
   stop(): void {
@@ -54,6 +102,10 @@ export class WsSubscription {
       clearInterval(this.listInterval);
       this.listInterval = null;
     }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
     for (const timer of this.reconnectTimers.values()) {
       clearTimeout(timer);
     }
@@ -67,6 +119,11 @@ export class WsSubscription {
     }
     this.reconnectAttempts.clear();
     this.stoppedConversations.clear();
+
+    for (const state of this.heartbeatStates.values()) {
+      if (state.pongTimeout) clearTimeout(state.pongTimeout);
+    }
+    this.heartbeatStates.clear();
   }
 
   /**
@@ -80,6 +137,11 @@ export class WsSubscription {
       clearTimeout(timer);
       this.reconnectTimers.delete(conversationId);
     }
+
+    const hbState = this.heartbeatStates.get(conversationId);
+    if (hbState?.pongTimeout) clearTimeout(hbState.pongTimeout);
+    this.heartbeatStates.delete(conversationId);
+
     const ws = this.connections.get(conversationId);
     if (ws) {
       ws.removeAllListeners();
@@ -106,6 +168,19 @@ export class WsSubscription {
 
     this.connections.set(conversationId, ws);
 
+    const hb = this.opts.heartbeat ?? {};
+    const hbEnabled = hb.enable ?? DEFAULT_HEARTBEAT.enable;
+    if (hbEnabled) {
+      const now = Date.now();
+      this.heartbeatStates.set(conversationId, {
+        lastRxAt: now,
+        lastPingAt: 0,
+        nextPingAt: now + (hb.idleThresholdMs ?? DEFAULT_HEARTBEAT.idleThresholdMs),
+        missedPongs: 0,
+        pongTimeout: null,
+      });
+    }
+
     ws.on('open', () => {
       this.reconnectAttempts.set(conversationId, 0);
       this.opts.onOpen?.(conversationId);
@@ -115,6 +190,18 @@ export class WsSubscription {
     ws.on('message', (data: Buffer | string) => {
       try {
         const msg = JSON.parse(data.toString());
+
+        // Any server frame counts as activity; keep connection stable and avoid unnecessary pings.
+        const state = this.heartbeatStates.get(conversationId);
+        if (state) {
+          state.lastRxAt = Date.now();
+          state.missedPongs = 0;
+          if (state.pongTimeout) {
+            clearTimeout(state.pongTimeout);
+            state.pongTimeout = null;
+          }
+        }
+
         if (msg.type === 'ws_message' && msg.envelope) {
           const env = msg.envelope;
           if (env.sender_did !== this.opts.myDid) {
@@ -128,8 +215,22 @@ export class WsSubscription {
       }
     });
 
+    ws.on('pong', () => {
+      const state = this.heartbeatStates.get(conversationId);
+      if (!state) return;
+      state.lastRxAt = Date.now();
+      state.missedPongs = 0;
+      if (state.pongTimeout) {
+        clearTimeout(state.pongTimeout);
+        state.pongTimeout = null;
+      }
+    });
+
     ws.on('close', () => {
       this.connections.delete(conversationId);
+      const state = this.heartbeatStates.get(conversationId);
+      if (state?.pongTimeout) clearTimeout(state.pongTimeout);
+      this.heartbeatStates.delete(conversationId);
       if (!this.stopped && !this.stoppedConversations.has(conversationId)) {
         this.scheduleReconnect(conversationId);
       }
@@ -140,6 +241,57 @@ export class WsSubscription {
     });
   }
 
+  private heartbeatTick(): void {
+    const hb = this.opts.heartbeat ?? {};
+    const hbEnabled = hb.enable ?? DEFAULT_HEARTBEAT.enable;
+    if (!hbEnabled) return;
+
+    const idleThresholdMs = hb.idleThresholdMs ?? DEFAULT_HEARTBEAT.idleThresholdMs;
+    const pingIntervalMs = hb.pingIntervalMs ?? DEFAULT_HEARTBEAT.pingIntervalMs;
+    const pongTimeoutMs = hb.pongTimeoutMs ?? DEFAULT_HEARTBEAT.pongTimeoutMs;
+    const maxMissedPongs = hb.maxMissedPongs ?? DEFAULT_HEARTBEAT.maxMissedPongs;
+    const jitter = hb.jitter ?? DEFAULT_HEARTBEAT.jitter;
+
+    const now = Date.now();
+
+    for (const [conversationId, ws] of this.connections) {
+      if (ws.readyState !== WebSocket.OPEN) continue;
+      const state = this.heartbeatStates.get(conversationId);
+      if (!state) continue;
+
+      // If we are waiting for a pong, do not send another ping.
+      if (state.pongTimeout) continue;
+
+      const idleFor = now - state.lastRxAt;
+      if (idleFor < idleThresholdMs) continue;
+
+      if (now < state.nextPingAt) continue;
+      if (state.lastPingAt !== 0 && now - state.lastPingAt < pingIntervalMs * 0.5) {
+        // Extra guard against edge cases (should be rare).
+        continue;
+      }
+
+      ws.ping();
+      state.lastPingAt = now;
+      const jitterFactor = 1 + (Math.random() - 0.5) * 2 * jitter;
+      state.nextPingAt = now + Math.max(1000, pingIntervalMs * jitterFactor);
+
+      state.pongTimeout = setTimeout(() => {
+        state.missedPongs += 1;
+        state.pongTimeout = null;
+
+        if (state.missedPongs > maxMissedPongs) {
+          try {
+            // Trigger close handler -> scheduleReconnect
+            ws.close(1001, 'pong timeout');
+          } catch {
+            // ignore
+          }
+        }
+      }, pongTimeoutMs);
+    }
+  }
+
   private scheduleReconnect(conversationId: string): void {
     if (this.reconnectTimers.has(conversationId)) return;