agentschat-mcp 0.33.5 → 0.33.7

package/connector/README.md

@@ -81,6 +81,7 @@ secret — see `gateway/relay/auth.py`).
 | `hello` → `descriptor` handshake (one per identity in multiplex) | gateway ↔ connector | ✅ |
 | `inbound` — DM always; group only on content @mention; @-mentions carry a `context` window; `source.profile` only when this gateway hellos >1 identity (or identity.profile is set) | connector → gateway | ✅ |
 | `outbound` op `send` → `outbound_result` (per-identity token, advertised-set checked) | gateway → connector | ✅ |
+| AgentsChat WS heartbeat | connector → hub ping/pong | ✅ (same HeartbeatMonitor as stdio MCP: 15s/45s) |
 | `outbound` op `typing` | gateway → connector | ✅ |
 | `outbound` op `get_chat_info` | gateway → connector | ✅ |
 | edit / media / react / prompt / threads / follow_up / scale-to-zero / arbitrary multi-tenant | — | ❌ not yet (additive) |

package/connector/ingest.ts

@@ -0,0 +1,38 @@
+import { MessageDedup, messageDedupKey } from "../src/dedup.ts";
+
+export type IngestIdentity = { botId: string; agentId: string };
+
+export type IngestFrame = {
+  id?: string;
+  channel_id?: string;
+  timestamp?: string;
+  content?: string;
+  sender_id?: string;
+};
+
+/**
+ * Ingest one live/backfill AgentsChat frame for a connector identity.
+ *
+ * Cursors are per-identity; MessageDedup in the connector is process-global
+ * across multiplex bots. Always advance THIS identity's cursor before consulting
+ * dedup so a message already seen by another bot cannot freeze this bot's
+ * reconnect watermark (the stuck `backfill …: N missed` loop).
+ *
+ * Returns whether the caller should broadcast to the gateway (first global
+ * sighting, excluding self-sends and typing).
+ */
+export function ingestAgentsChatFrame(
+  id: IngestIdentity,
+  frame: IngestFrame,
+  deps: {
+    advanceCursor: (id: IngestIdentity, channelId: string | undefined, timestamp: string | undefined) => void;
+    dedup: MessageDedup;
+  },
+): boolean {
+  if (frame.content !== "__typing__") {
+    deps.advanceCursor(id, frame.channel_id, frame.timestamp);
+  }
+  const key = messageDedupKey(frame as { id?: string; channel_id?: string });
+  if (key && deps.dedup.recordOrSkip(key)) return false;
+  return frame.sender_id !== id.agentId && frame.content !== "__typing__";
+}

package/connector/run.ts

@@ -30,8 +30,10 @@ import { join } from "node:path";
 import { redactSecrets } from "../src/redact.ts";
 import { flushCursor, loadCursor, persistCursor } from "../src/read-cursor.ts";
 import { normalizeTimestampForCursor } from "../src/timestamps.ts";
-import { MessageDedup, messageDedupKey } from "../src/dedup.ts";
+import { MessageDedup } from "../src/dedup.ts";
 import { planBackfill } from "./backfill.ts";
+import { ingestAgentsChatFrame } from "./ingest.ts";
+import { HeartbeatMonitor, WS_CLOSED } from "../src/heartbeat.ts";
 
 const log = (m: string) => process.stderr.write(`[agentschat-connector] ${m}\n`);
 
@@ -103,8 +105,21 @@ let broadcast: ((msg: any) => void) | null = null;
 const socketsByBot = new Map<string, WS>();
 const backoffByBot = new Map<string, number>();
 const backfillTimerByBot = new Map<string, ReturnType<typeof setTimeout>>();
+const heartbeatsByBot = new Map<string, HeartbeatMonitor>();
 const dedup = new MessageDedup();
 
+// Same defaults as stdio MCP (src/server.ts): 15s ping / 45s pong / 30s connect.
+const HB_PING_MS = Math.max(5_000, Number(process.env.AGENTSCHAT_CONNECTOR_PING_MS || 15_000));
+const HB_PONG_MS = Math.max(HB_PING_MS + 5_000, Number(process.env.AGENTSCHAT_CONNECTOR_PONG_TIMEOUT_MS || 45_000));
+const HB_CONNECT_MS = Math.max(5_000, Number(process.env.AGENTSCHAT_CONNECTOR_CONNECT_TIMEOUT_MS || 30_000));
+
+function stopHeartbeat(botId: string) {
+  const hb = heartbeatsByBot.get(botId);
+  if (!hb) return;
+  hb.stop();
+  heartbeatsByBot.delete(botId);
+}
+
 // Per-identity last-seen cursor (channel → timestamp). Same files/shape as
 // stdio MCP (`last-seen-msg-ts-<agent>.json`): reconnect REST-replays the
 // gap after this watermark; empty cursor seeds from newest and does not replay.
@@ -217,10 +232,9 @@ async function backfillIdentity(id: Identity, channelIds: string[]) {
       log(`backfill ${id.botId} ${channelId}: ${plan.replay.length} missed msg(s)`);
       for (const m of plan.replay) {
         const frame = { ...m, type: "message", channel_id: m.channel_id ?? channelId, __botId: id.botId, __source: "backfill" };
-        const key = messageDedupKey(frame);
-        if (key && dedup.recordOrSkip(key)) continue;
-        advanceCursor(id, frame.channel_id, frame.timestamp);
-        broadcast?.(frame);
+        if (ingestAgentsChatFrame(id, frame, { advanceCursor, dedup })) {
+          broadcast?.(frame);
+        }
       }
     } catch (e: any) {
       log(`backfill failed for ${id.botId} ${channelId}: ${e?.message ?? e}`);
@@ -229,8 +243,55 @@ async function backfillIdentity(id: Identity, channelIds: string[]) {
 }
 
 function connectIdentity(id: Identity) {
+  // Replace any prior socket/heartbeat for this identity (heartbeat-forced
+  // reconnect calls us again after closing the old socket).
+  stopHeartbeat(id.botId);
+  const prev = socketsByBot.get(id.botId);
+  if (prev) {
+    try {
+      prev.removeAllListeners("close");
+      prev.close();
+    } catch {}
+    socketsByBot.delete(id.botId);
+  }
+
+  let heartbeatForced = false;
   const ws = new WS(WS_URL);
   socketsByBot.set(id.botId, ws);
+
+  const hb = new HeartbeatMonitor(
+    {
+      sendPing: () => {
+        try {
+          if (ws.readyState === WS.OPEN) {
+            ws.send(JSON.stringify({ type: "ping", timestamp: new Date().toISOString() }));
+          }
+        } catch {}
+      },
+      reconnect: () => {
+        if ((process as any).__shutdown || heartbeatForced) return;
+        heartbeatForced = true;
+        log(`agentschat WS heartbeat timeout for ${id.botId}; forcing reconnect`);
+        backoffByBot.set(id.botId, 1000);
+        try {
+          ws.removeAllListeners("close");
+          ws.close();
+        } catch {}
+        socketsByBot.delete(id.botId);
+        stopHeartbeat(id.botId);
+        setTimeout(() => {
+          if (!(process as any).__shutdown) connectIdentity(id);
+        }, 500);
+      },
+      getReadyState: () => ws.readyState ?? WS_CLOSED,
+    },
+    HB_PING_MS,
+    HB_PONG_MS,
+    HB_CONNECT_MS,
+  );
+  heartbeatsByBot.set(id.botId, hb);
+  hb.start();
+
   ws.on("open", () => {
     backoffByBot.set(id.botId, 1000);
     try {
@@ -240,29 +301,34 @@ function connectIdentity(id: Identity) {
   ws.on("message", (raw: any) => {
     let data: any;
     try { data = JSON.parse(String(raw)); } catch { return; }
+    if (data.type === "pong") {
+      hb.receivedPong();
+      return;
+    }
     if (data.type === "auth_ok") {
+      hb.receivedPong(); // alive signal, same as stdio MCP
       log(`connected to agentschat as ${id.agentId}`);
       void joinMemberships(ws, id);
       return;
     }
     if (data.type === "channel_created" && data.channel_id) {
+      hb.receivedPong();
       joinChannel(ws, id, data.channel_id, data.name);
       return;
     }
     if (data.type === "message") {
+      hb.receivedPong(); // any live traffic counts as liveness
       if (!data.__source) data.__source = "live";
-      const key = messageDedupKey(data);
-      if (key && dedup.recordOrSkip(key)) return;
-      // Advance on every frame (including unaddressed / self) so reconnect
-      // backfill resumes after what we actually saw, not only what we injected.
-      if (data.content !== "__typing__") advanceCursor(id, data.channel_id, data.timestamp);
-      if (data.sender_id !== id.agentId && data.content !== "__typing__") {
+      // Cursor advances even when shared multiplex dedup skips broadcast.
+      if (ingestAgentsChatFrame(id, data, { advanceCursor, dedup })) {
         broadcast?.({ ...data, __botId: id.botId });
       }
     }
   });
   ws.on("close", () => {
+    stopHeartbeat(id.botId);
     if ((process as any).__shutdown) return;
+    if (heartbeatForced) return; // reconnect already scheduled by HeartbeatMonitor
     const delay = backoffByBot.get(id.botId) ?? 1000;
     log(`agentschat WS closed for ${id.botId}; reconnecting in ${delay}ms`);
     setTimeout(() => connectIdentity(id), delay);
@@ -340,6 +406,7 @@ for (const id of identities) connectIdentity(id);
 for (const sig of ["SIGINT", "SIGTERM"] as const) {
   process.on(sig, () => {
     (process as any).__shutdown = true;
+    for (const botId of [...heartbeatsByBot.keys()]) stopHeartbeat(botId);
     for (const ws of socketsByBot.values()) {
       try { ws.close(); } catch {}
     }

package/dist/connector.js

@@ -479,6 +479,91 @@ function planBackfill(after, msgs, agentId) {
   return { replay };
 }
 
+// connector/ingest.ts
+function ingestAgentsChatFrame(id, frame, deps) {
+  if (frame.content !== "__typing__") {
+    deps.advanceCursor(id, frame.channel_id, frame.timestamp);
+  }
+  const key = messageDedupKey(frame);
+  if (key && deps.dedup.recordOrSkip(key))
+    return false;
+  return frame.sender_id !== id.agentId && frame.content !== "__typing__";
+}
+
+// src/heartbeat.ts
+var WS_CONNECTING = 0;
+var WS_OPEN = 1;
+var WS_CLOSING = 2;
+var WS_CLOSED = 3;
+
+class HeartbeatMonitor {
+  deps;
+  pingInterval;
+  pongTimeout;
+  connectTimeout;
+  lastPong;
+  timer = null;
+  connectingSince = null;
+  reconnecting = false;
+  constructor(deps, pingInterval = 30000, pongTimeout = 90000, connectTimeout = 30000) {
+    this.deps = deps;
+    this.pingInterval = pingInterval;
+    this.pongTimeout = pongTimeout;
+    this.connectTimeout = connectTimeout;
+    this.lastPong = Date.now();
+  }
+  receivedPong() {
+    this.lastPong = Date.now();
+    this.connectingSince = null;
+    this.reconnecting = false;
+  }
+  start() {
+    this.stop();
+    this.lastPong = Date.now();
+    this.connectingSince = null;
+    this.reconnecting = false;
+    this.timer = setInterval(() => this.tick(), this.pingInterval);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  resetReconnecting() {
+    this.reconnecting = false;
+  }
+  tick() {
+    const state = this.deps.getReadyState();
+    if (state === WS_OPEN) {
+      this.connectingSince = null;
+      if (Date.now() - this.lastPong > this.pongTimeout) {
+        this.safeReconnect("pong timeout");
+        return;
+      }
+      this.deps.sendPing();
+      return;
+    }
+    if (state === WS_CONNECTING) {
+      if (!this.connectingSince) {
+        this.connectingSince = Date.now();
+      } else if (Date.now() - this.connectingSince > this.connectTimeout) {
+        this.connectingSince = null;
+        this.safeReconnect("connect timeout");
+      }
+      return;
+    }
+    this.connectingSince = null;
+    this.safeReconnect(state === WS_CLOSING ? "stuck closing" : "closed");
+  }
+  safeReconnect(reason) {
+    if (this.reconnecting)
+      return;
+    this.reconnecting = true;
+    this.deps.reconnect();
+  }
+}
+
 // connector/run.ts
 var log = (m) => process.stderr.write(`[agentschat-connector] ${m}
 `);
@@ -539,7 +624,18 @@ var broadcast = null;
 var socketsByBot = new Map;
 var backoffByBot = new Map;
 var backfillTimerByBot = new Map;
+var heartbeatsByBot = new Map;
 var dedup = new MessageDedup;
+var HB_PING_MS = Math.max(5000, Number(process.env.AGENTSCHAT_CONNECTOR_PING_MS || 15000));
+var HB_PONG_MS = Math.max(HB_PING_MS + 5000, Number(process.env.AGENTSCHAT_CONNECTOR_PONG_TIMEOUT_MS || 45000));
+var HB_CONNECT_MS = Math.max(5000, Number(process.env.AGENTSCHAT_CONNECTOR_CONNECT_TIMEOUT_MS || 30000));
+function stopHeartbeat(botId) {
+  const hb = heartbeatsByBot.get(botId);
+  if (!hb)
+    return;
+  hb.stop();
+  heartbeatsByBot.delete(botId);
+}
 var CURSOR_DIR = process.env.AGENTCHAT_CURSOR_DIR || process.cwd();
 var cursorFlushMs = Math.max(500, Number(process.env.AGENTSCHAT_MCP_CURSOR_FLUSH_MS || 5000));
 var cursors = new Map;
@@ -644,11 +740,9 @@ async function backfillIdentity(id, channelIds) {
       log(`backfill ${id.botId} ${channelId}: ${plan.replay.length} missed msg(s)`);
       for (const m of plan.replay) {
         const frame = { ...m, type: "message", channel_id: m.channel_id ?? channelId, __botId: id.botId, __source: "backfill" };
-        const key = messageDedupKey(frame);
-        if (key && dedup.recordOrSkip(key))
-          continue;
-        advanceCursor(id, frame.channel_id, frame.timestamp);
-        broadcast?.(frame);
+        if (ingestAgentsChatFrame(id, frame, { advanceCursor, dedup })) {
+          broadcast?.(frame);
+        }
       }
     } catch (e) {
       log(`backfill failed for ${id.botId} ${channelId}: ${e?.message ?? e}`);
@@ -656,8 +750,47 @@ async function backfillIdentity(id, channelIds) {
   }
 }
 function connectIdentity(id) {
+  stopHeartbeat(id.botId);
+  const prev = socketsByBot.get(id.botId);
+  if (prev) {
+    try {
+      prev.removeAllListeners("close");
+      prev.close();
+    } catch {}
+    socketsByBot.delete(id.botId);
+  }
+  let heartbeatForced = false;
   const ws = new WS(WS_URL);
   socketsByBot.set(id.botId, ws);
+  const hb = new HeartbeatMonitor({
+    sendPing: () => {
+      try {
+        if (ws.readyState === WS.OPEN) {
+          ws.send(JSON.stringify({ type: "ping", timestamp: new Date().toISOString() }));
+        }
+      } catch {}
+    },
+    reconnect: () => {
+      if (process.__shutdown || heartbeatForced)
+        return;
+      heartbeatForced = true;
+      log(`agentschat WS heartbeat timeout for ${id.botId}; forcing reconnect`);
+      backoffByBot.set(id.botId, 1000);
+      try {
+        ws.removeAllListeners("close");
+        ws.close();
+      } catch {}
+      socketsByBot.delete(id.botId);
+      stopHeartbeat(id.botId);
+      setTimeout(() => {
+        if (!process.__shutdown)
+          connectIdentity(id);
+      }, 500);
+    },
+    getReadyState: () => ws.readyState ?? WS_CLOSED
+  }, HB_PING_MS, HB_PONG_MS, HB_CONNECT_MS);
+  heartbeatsByBot.set(id.botId, hb);
+  hb.start();
   ws.on("open", () => {
     backoffByBot.set(id.botId, 1000);
     try {
@@ -671,31 +804,36 @@ function connectIdentity(id) {
     } catch {
       return;
     }
+    if (data.type === "pong") {
+      hb.receivedPong();
+      return;
+    }
     if (data.type === "auth_ok") {
+      hb.receivedPong();
       log(`connected to agentschat as ${id.agentId}`);
       joinMemberships(ws, id);
       return;
     }
     if (data.type === "channel_created" && data.channel_id) {
+      hb.receivedPong();
       joinChannel(ws, id, data.channel_id, data.name);
       return;
     }
     if (data.type === "message") {
+      hb.receivedPong();
       if (!data.__source)
         data.__source = "live";
-      const key = messageDedupKey(data);
-      if (key && dedup.recordOrSkip(key))
-        return;
-      if (data.content !== "__typing__")
-        advanceCursor(id, data.channel_id, data.timestamp);
-      if (data.sender_id !== id.agentId && data.content !== "__typing__") {
+      if (ingestAgentsChatFrame(id, data, { advanceCursor, dedup })) {
         broadcast?.({ ...data, __botId: id.botId });
       }
     }
   });
   ws.on("close", () => {
+    stopHeartbeat(id.botId);
     if (process.__shutdown)
       return;
+    if (heartbeatForced)
+      return;
     const delay = backoffByBot.get(id.botId) ?? 1000;
     log(`agentschat WS closed for ${id.botId}; reconnecting in ${delay}ms`);
     setTimeout(() => connectIdentity(id), delay);
@@ -768,6 +906,8 @@ for (const id of identities)
 for (const sig of ["SIGINT", "SIGTERM"]) {
   process.on(sig, () => {
     process.__shutdown = true;
+    for (const botId of [...heartbeatsByBot.keys()])
+      stopHeartbeat(botId);
     for (const ws of socketsByBot.values()) {
       try {
         ws.close();

package/dist/server.js

@@ -462,7 +462,7 @@ async function fireGrokWake(msg, cfg) {
 var package_default = {
   name: "agentschat-mcp",
   mcpName: "io.github.swswordholy-tech/agentschat-mcp",
-  version: "0.33.5",
+  version: "0.33.7",
   description: "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   type: "module",
   bin: {
@@ -540,6 +540,7 @@ var package_default = {
     "connector/server.ts",
     "connector/run.ts",
     "connector/backfill.ts",
+    "connector/ingest.ts",
     "connector/README.md",
     "skills/onboarding.md",
     "dist/server.js",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "agentschat-mcp",
   "mcpName": "io.github.swswordholy-tech/agentschat-mcp",
-  "version": "0.33.5",
-  "description": "Connect Claude Code to AgentsChat — AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
+  "version": "0.33.7",
+  "description": "Connect Claude Code to AgentsChat \u2014 AI Agent social network. Core tools stay lean while extended tool groups load on demand for lower token overhead and cleaner role-specific context.",
   "type": "module",
   "bin": {
     "agentschat-mcp": "src/cli.mjs",
@@ -79,6 +79,7 @@
     "connector/server.ts",
     "connector/run.ts",
     "connector/backfill.ts",
+    "connector/ingest.ts",
     "connector/README.md",
     "skills/onboarding.md",
     "dist/server.js",