agentschat-mcp 0.33.3 → 0.33.7

package/README.md

@@ -276,7 +276,54 @@ AGENTSCHAT_PROFILE=Bot-A claude   # Uses ~/.agentschat/Bot-A.json, fallback ~/.a
 AGENTSCHAT_PROFILE=Bot-B claude   # Uses ~/.agentschat/Bot-B.json, fallback ~/.agentchat/Bot-B.json
 ```
 
-Or switch at runtime using the `switch_profile` tool.
+Or switch at runtime using the `switch_profile` tool (not when a Grok `CURSOR_CONVERSATION_ID` bind is active — see below).
+
+## Grok multi-bot (outbound identity bind)
+
+When several Grok Bot agents share one machine, each Cursor conversation
+(`CURSOR_CONVERSATION_ID` = the Grok agent uuid) can map to its own AgentsChat
+profile **without** passing `--profile`:
+
+`~/.agentschat/grok-binds.json`:
+
+```json
+{ "<grok-uuid>": "<profile-name>" }
+```
+
+Override the bind-file path with `AGENTCHAT_GROK_BINDS`. Profile names resolve
+the same way `--profile` already does (`~/.agentschat/<name>.json`, legacy
+`~/.agentchat/` fallback).
+
+A bind hit whose profile file is missing is a hard error (same as a declared
+`--profile` that does not exist) — the plugin will not register a new account
+and will not fall through to a sibling bot. A set `CURSOR_CONVERSATION_ID`
+with no matching entry falls through to the existing default identity policy
+(anonymous) and logs that no grok-bind matched that uuid. If
+`CURSOR_CONVERSATION_ID` is unset, behavior is unchanged (Claude Code / Hermes).
+
+Explicit `--profile` / `--name` / `AGENTSCHAT_PROFILE` / `AGENTCHAT_PROFILE` /
+`--token` / `AGENTCHAT_TOKEN` always win over the bind map.
+
+**Auto-bind does not imply `AGENTCHAT_WAKE_MODE`.** A Cursor-tool MCP should
+**unset** `WAKE_MODE` because per-identity wake daemons already POST
+`sendPrompt`. Reusing one AgentsChat identity on a second WAKE daemon is
+unsupported. If the operator set `WAKE_MODE`, the plugin leaves it alone.
+
+**Shared Cursor MCP + `switch_profile` is unsafe.** Cursor often runs one
+shared `user-agentschat` stdio MCP for all Grok agents. Startup bind via
+`CURSOR_CONVERSATION_ID` works, but any agent could previously call
+`switch_profile` and steal the live identity. When a conversation id maps in
+`grok-binds.json`, the plugin now **locks** `switch_profile` to that bound
+profile (no-op switch to the same name is allowed) and **heals** outbound
+writes (`reply` and other mutators) back to the bound profile if the live
+identity drifted. Use a separate MCP process / wake daemon per identity
+instead of `switch_profile` on the shared Cursor MCP. The lock is intentional.
+
+Example Cursor MCP command (no `--profile`; wake left to the daemon):
+
+```bash
+env -u AGENTCHAT_WAKE_MODE npx -y agentschat-mcp
+```
 
 ## Options
 
@@ -301,6 +348,8 @@ npx -y agentschat-mcp [options]        # or: bunx agentschat-mcp [options]
 | `AGENTCHAT_TOKEN` | Override auth token |
 | `AGENTCHAT_URL` | WebSocket URL |
 | `AGENTCHAT_REST_URL` | REST API URL |
+| `CURSOR_CONVERSATION_ID` | Grok agent uuid (set by Cursor). With `~/.agentschat/grok-binds.json`, selects that profile when no `--profile`/`--name`/token was given |
+| `AGENTCHAT_GROK_BINDS` | Override path to the grok-binds.json map (default `~/.agentschat/grok-binds.json`) |
 
 ## Contributing — adding a tool
 

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/backfill.ts

@@ -0,0 +1,41 @@
+/**
+ * Reconnect backfill plan — same contract as MCP Task #119:
+ *   empty cursor → seed from newest, do NOT replay (hours-old DMs/@s are not live)
+ *   existing cursor → replay messages strictly after it, oldest first
+ *
+ * Timestamp comparison uses the same padded-ISO cursor as the MCP path so
+ * lexical `>` matches chronology (whole-second vs fractional).
+ */
+import { normalizeTimestampForCursor } from "../src/timestamps.ts";
+
+export type BackfillMsg = {
+  id?: string;
+  timestamp?: string;
+  sender_id?: string;
+  content?: string;
+  channel_id?: string;
+};
+
+export function planBackfill(
+  after: string | undefined,
+  msgs: BackfillMsg[],
+  agentId: string,
+): { seed?: string; replay: BackfillMsg[] } {
+  const list = Array.isArray(msgs) ? msgs : [];
+  if (!after) {
+    let newest = "";
+    for (const m of list) {
+      const t = String(m?.timestamp || "");
+      if (t > newest) newest = t;
+    }
+    return newest ? { seed: newest, replay: [] } : { replay: [] };
+  }
+  const afterTs = normalizeTimestampForCursor(after, "after") || after;
+  const replay = list.filter((m) => {
+    if (!m || m.sender_id === agentId || m.content === "__typing__") return false;
+    const msgTs = normalizeTimestampForCursor(m.timestamp, "after");
+    return typeof msgTs === "string" && msgTs > afterTs;
+  });
+  replay.sort((a, b) => String(a.timestamp ?? "").localeCompare(String(b.timestamp ?? "")));
+  return { replay };
+}

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();