@pingagent/sdk 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -486,8 +486,19 @@ interface WsSubscriptionOptions {
     onMessage: (envelope: any, conversationId: string) => void;
     onControl?: (control: WsControlPayload, conversationId: string) => void;
     onError?: (err: Error) => void;
+    /** Optional debug hook for observability (non-fatal events). */
+    onDebug?: (info: {
+        event: string;
+        conversationId?: string;
+        detail?: Record<string, unknown>;
+    }) => void;
     /** Called when a WebSocket opens or reopens; e.g. Skill can run catchUp to fill gaps. */
     onOpen?: (conversationId: string) => void;
+    /**
+     * When true (default), drop ws_message envelopes sent by myself (sender_did === myDid).
+     * Set to false when you intentionally run multiple devices/processes under the same DID and want cross-device delivery.
+     */
+    ignoreSelfMessages?: boolean;
     /**
      * 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.
@@ -517,6 +528,8 @@ declare class WsSubscription {
     private stopped;
     /** Conversation IDs that were explicitly stopped (e.g. revoke); do not reconnect. */
     private stoppedConversations;
+    private lastParseErrorAtByConv;
+    private lastFrameAtByConv;
     private heartbeatTimer;
     private heartbeatStates;
     constructor(opts: WsSubscriptionOptions);
@@ -531,6 +544,7 @@ declare class WsSubscription {
     private connectAsync;
     private heartbeatTick;
     private scheduleReconnect;
+    private isSubscribableConversationType;
     private connectAll;
     private syncConnections;
 }

package/dist/index.js

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

package/dist/web-server.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingagent/sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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/a2a": "0.1.1",
+    "@pingagent/protocol": "0.1.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",

package/src/ws-subscription.ts

@@ -19,8 +19,15 @@ export interface WsSubscriptionOptions {
   onMessage: (envelope: any, conversationId: string) => void;
   onControl?: (control: WsControlPayload, conversationId: string) => void;
   onError?: (err: Error) => void;
+  /** Optional debug hook for observability (non-fatal events). */
+  onDebug?: (info: { event: string; conversationId?: string; detail?: Record<string, unknown> }) => void;
   /** Called when a WebSocket opens or reopens; e.g. Skill can run catchUp to fill gaps. */
   onOpen?: (conversationId: string) => void;
+  /**
+   * When true (default), drop ws_message envelopes sent by myself (sender_did === myDid).
+   * Set to false when you intentionally run multiple devices/processes under the same DID and want cross-device delivery.
+   */
+  ignoreSelfMessages?: boolean;
 
   /**
    * Keepalive heartbeat for idle connections to reduce "WS silently dropped" periods.
@@ -50,8 +57,8 @@ const LIST_CONVERSATIONS_INTERVAL_MS = 60_000;
 
 const DEFAULT_HEARTBEAT = {
   enable: true,
-  idleThresholdMs: 25_000,
-  pingIntervalMs: 30_000,
+  idleThresholdMs: 10_000,
+  pingIntervalMs: 15_000,
   pongTimeoutMs: 10_000,
   maxMissedPongs: 2,
   tickMs: 5_000,
@@ -67,6 +74,8 @@ export class WsSubscription {
   private stopped = false;
   /** Conversation IDs that were explicitly stopped (e.g. revoke); do not reconnect. */
   private stoppedConversations = new Set<string>();
+  private lastParseErrorAtByConv = new Map<string, number>();
+  private lastFrameAtByConv = new Map<string, number>();
 
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   private heartbeatStates = new Map<
@@ -119,6 +128,8 @@ export class WsSubscription {
     }
     this.reconnectAttempts.clear();
     this.stoppedConversations.clear();
+    this.lastParseErrorAtByConv.clear();
+    this.lastFrameAtByConv.clear();
 
     for (const state of this.heartbeatStates.values()) {
       if (state.pongTimeout) clearTimeout(state.pongTimeout);
@@ -150,6 +161,8 @@ export class WsSubscription {
       }
       this.connections.delete(conversationId);
     }
+    this.lastParseErrorAtByConv.delete(conversationId);
+    this.lastFrameAtByConv.delete(conversationId);
   }
 
   private wsUrl(conversationId: string): string {
@@ -187,10 +200,8 @@ export class WsSubscription {
       // ws_connected will arrive as first message
     });
 
-    ws.on('message', (data: Buffer | string) => {
+    ws.on('message', (data: any) => {
       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) {
@@ -202,16 +213,67 @@ export class WsSubscription {
           }
         }
 
-        if (msg.type === 'ws_message' && msg.envelope) {
+        const rawText =
+          typeof data === 'string'
+            ? data
+            : Buffer.isBuffer(data)
+              ? data.toString()
+              : Array.isArray(data)
+                ? Buffer.concat(data).toString()
+                : data instanceof ArrayBuffer
+                  ? Buffer.from(new Uint8Array(data)).toString()
+                  : // Fallback: try best-effort stringification
+                    String(data);
+
+        this.lastFrameAtByConv.set(conversationId, Date.now());
+
+        const msg = JSON.parse(rawText);
+
+        if (msg.type === 'ws_connected') {
+          this.opts.onDebug?.({
+            event: 'ws_connected',
+            conversationId,
+            detail: {
+              your_did: msg.your_did,
+              server_ts_ms: msg.server_ts_ms,
+              conversation_id: msg.conversation_id,
+            },
+          });
+        } else if (msg.type === 'ws_message' && msg.envelope) {
           const env = msg.envelope;
-          if (env.sender_did !== this.opts.myDid) {
+          const ignoreSelf = this.opts.ignoreSelfMessages ?? true;
+          if (!ignoreSelf || env.sender_did !== this.opts.myDid) {
             this.opts.onMessage(env, conversationId);
+          } else {
+            this.opts.onDebug?.({
+              event: 'ws_message_ignored_self',
+              conversationId,
+              detail: { sender_did: env.sender_did, message_id: env.message_id, seq: env.seq },
+            });
           }
         } else if (msg.type === 'ws_control' && msg.control) {
           this.opts.onControl?.(msg.control, conversationId);
+          this.opts.onDebug?.({ event: 'ws_control', conversationId, detail: msg.control });
+        } else if (msg.type === 'ws_receipt' && msg.receipt) {
+          this.opts.onDebug?.({ event: 'ws_receipt', conversationId, detail: msg.receipt });
+        } else if (msg?.type) {
+          this.opts.onDebug?.({ event: 'ws_unknown_type', conversationId, detail: { type: msg.type } });
+        }
+      } catch (e: any) {
+        // Observability: parse failures are otherwise silent and look like "server never pushes".
+        const now = Date.now();
+        const last = this.lastParseErrorAtByConv.get(conversationId) ?? 0;
+        if (now - last > 30_000) {
+          this.lastParseErrorAtByConv.set(conversationId, now);
+          this.opts.onDebug?.({
+            event: 'ws_parse_error',
+            conversationId,
+            detail: {
+              message: e?.message ?? String(e),
+              last_frame_at_ms: this.lastFrameAtByConv.get(conversationId) ?? null,
+            },
+          });
         }
-      } catch {
-        // ignore parse errors
       }
     });
 
@@ -271,6 +333,14 @@ export class WsSubscription {
         continue;
       }
 
+      // Application-level keepalive for CDN/NAT idle timeouts (more reliable than ping/pong alone).
+      // Receiver can ignore this message.
+      try {
+        ws.send(JSON.stringify({ type: 'hb' }));
+      } catch {
+        // ignore; ping/pong + reconnect will handle dead sockets
+      }
+
       ws.ping();
       state.lastPingAt = now;
       const jitterFactor = 1 + (Math.random() - 0.5) * 2 * jitter;
@@ -280,7 +350,7 @@ export class WsSubscription {
         state.missedPongs += 1;
         state.pongTimeout = null;
 
-        if (state.missedPongs > maxMissedPongs) {
+        if (state.missedPongs >= maxMissedPongs) {
           try {
             // Trigger close handler -> scheduleReconnect
             ws.close(1001, 'pong timeout');
@@ -312,10 +382,15 @@ export class WsSubscription {
     this.reconnectTimers.set(conversationId, timer);
   }
 
+  private isSubscribableConversationType(type: string): boolean {
+    // Server may return pending_dm alongside dm listings. WS upgrade is supported for any conversation_id.
+    return type === 'dm' || type === 'pending_dm' || type === 'channel' || type === 'group';
+  }
+
   private async connectAll(): Promise<void> {
     try {
       const convos = await this.opts.listConversations();
-      const subscribable = convos.filter((c) => c.type === 'dm' || c.type === 'channel');
+      const subscribable = convos.filter((c) => this.isSubscribableConversationType(c.type));
       for (const c of subscribable) {
         void this.connectAsync(c.conversation_id);
       }
@@ -329,7 +404,7 @@ export class WsSubscription {
     try {
       const convos = await this.opts.listConversations();
       const subscribableIds = new Set(
-        convos.filter((c) => c.type === 'dm' || c.type === 'channel').map((c) => c.conversation_id),
+        convos.filter((c) => this.isSubscribableConversationType(c.type)).map((c) => c.conversation_id),
       );
       for (const convId of subscribableIds) {
         if (!this.stoppedConversations.has(convId) && !this.connections.has(convId)) {