agentschat-mcp 0.33.2 → 0.33.5

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

@@ -54,6 +54,13 @@ After `auth_ok` the connector GETs `/api/channels/mine` and sends `join_channel`
 for each membership, and again on `channel_created`. The server only pushes
 DM/@ frames to sockets that have joined; auth alone is not enough.
 
+**Read cursor (same as stdio MCP):** each identity persists
+`last-seen-msg-ts-<botId>.json` (channel → last seen timestamp) under
+`AGENTCHAT_CURSOR_DIR` or the process cwd. On every `auth_ok` it REST-backfills
+messages strictly after that watermark through the same inject path as live WS
+(empty cursor seeds from newest and does not replay). Live frames and backfill
+share a message-id dedup so a reconnect race does not double-inject.
+
 **Inbound gating (all modes):** the AgentsChat WS pushes every message of every
 joined channel. The connector injects into the gateway only what is ADDRESSED to
 an identity — DMs always, group messages only when the body @mentions it (same

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

@@ -26,7 +26,12 @@
 import WS from "ws";
 import { startConnector } from "./server.ts";
 import type { Identity } from "./identities.ts";
+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 { planBackfill } from "./backfill.ts";
 
 const log = (m: string) => process.stderr.write(`[agentschat-connector] ${m}\n`);
 
@@ -97,6 +102,55 @@ for (const id of identities) {
 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 dedup = new MessageDedup();
+
+// 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.
+const CURSOR_DIR = process.env.AGENTCHAT_CURSOR_DIR || process.cwd();
+const cursorFlushMs = Math.max(500, Number(process.env.AGENTSCHAT_MCP_CURSOR_FLUSH_MS || 5000));
+
+type CursorStore = {
+  file: string;
+  map: Map<string, string>;
+  state: { dirty: boolean };
+  timer: ReturnType<typeof setTimeout> | null;
+};
+const cursors = new Map<string, CursorStore>();
+
+function cursorFor(id: Identity): CursorStore {
+  let s = cursors.get(id.botId);
+  if (s) return s;
+  const file = join(CURSOR_DIR, `last-seen-msg-ts-${id.botId}.json`);
+  s = { file, map: loadCursor(file, (m) => log(m.trimEnd())), state: { dirty: false }, timer: null };
+  cursors.set(id.botId, s);
+  return s;
+}
+
+function flushOne(s: CursorStore) {
+  if (s.timer) { clearTimeout(s.timer); s.timer = null; }
+  flushCursor(s.state, () => persistCursor(s.file, s.map, (m) => log(m.trimEnd())));
+}
+
+function scheduleSave(s: CursorStore) {
+  s.state.dirty = true;
+  if (s.timer) return;
+  s.timer = setTimeout(() => { s.timer = null; flushOne(s); }, cursorFlushMs);
+  (s.timer as any).unref?.();
+}
+
+function advanceCursor(id: Identity, channelId: string | undefined, timestamp: string | undefined) {
+  if (typeof channelId !== "string" || typeof timestamp !== "string" || !timestamp) return;
+  const s = cursorFor(id);
+  const prev = s.map.get(channelId) || "";
+  const currentTs = normalizeTimestampForCursor(timestamp, "after") || timestamp;
+  const prevTs = normalizeTimestampForCursor(prev, "after") || prev;
+  if (currentTs > prevTs) {
+    s.map.set(channelId, timestamp);
+    scheduleSave(s);
+  }
+}
 
 function joinChannel(ws: WS, id: Identity, channelId: string, name?: string) {
   try {
@@ -119,16 +173,61 @@ async function joinMemberships(ws: WS, id: Identity) {
     }
     const body = await r.json() as any;
     const channels = Array.isArray(body) ? body : (body.channels || []);
+    const joined: string[] = [];
     for (const ch of channels) {
       const channelId = ch?.id || ch?.channel_id;
       if (!channelId) continue;
       joinChannel(ws, id, channelId, ch?.name);
+      joined.push(channelId);
     }
+    // Same delay as MCP Task #119: let channel_created + gateway hello settle,
+    // then REST-replay anything after the persisted last-seen cursor.
+    const prev = backfillTimerByBot.get(id.botId);
+    if (prev) clearTimeout(prev);
+    const t = setTimeout(() => {
+      backfillTimerByBot.delete(id.botId);
+      if ((process as any).__shutdown) return;
+      void backfillIdentity(id, joined);
+    }, 2000);
+    (t as any).unref?.();
+    backfillTimerByBot.set(id.botId, t);
   } catch (e: any) {
     log(`join-on-auth failed: ${e?.message ?? e}`);
   }
 }
 
+async function backfillIdentity(id: Identity, channelIds: string[]) {
+  const s = cursorFor(id);
+  for (const channelId of channelIds) {
+    try {
+      const after = s.map.get(channelId);
+      const params = after ? `?after=${encodeURIComponent(after)}&limit=50` : `?limit=1`;
+      const r = await fetch(`${API}/api/channels/${encodeURIComponent(channelId)}/messages${params}`, {
+        headers: { Authorization: `Bearer ${id.token}` },
+      });
+      if (!r.ok) continue;
+      const msgs = (((await r.json()) as any)?.messages ?? []) as any[];
+      const plan = planBackfill(after, msgs, id.agentId);
+      if (plan.seed) {
+        s.map.set(channelId, plan.seed);
+        scheduleSave(s);
+        continue;
+      }
+      if (!plan.replay.length) continue;
+      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);
+      }
+    } catch (e: any) {
+      log(`backfill failed for ${id.botId} ${channelId}: ${e?.message ?? e}`);
+    }
+  }
+}
+
 function connectIdentity(id: Identity) {
   const ws = new WS(WS_URL);
   socketsByBot.set(id.botId, ws);
@@ -150,10 +249,16 @@ function connectIdentity(id: Identity) {
       joinChannel(ws, id, data.channel_id, data.name);
       return;
     }
-    if (data.type === "message" && data.sender_id !== id.agentId) {
-      // Tag which identity's socket this arrived on, so the connector routes it to
-      // the gateway fronting that identity (and only that one).
-      broadcast?.({ ...data, __botId: id.botId });
+    if (data.type === "message") {
+      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__") {
+        broadcast?.({ ...data, __botId: id.botId });
+      }
     }
   });
   ws.on("close", () => {
@@ -238,6 +343,7 @@ for (const sig of ["SIGINT", "SIGTERM"] as const) {
     for (const ws of socketsByBot.values()) {
       try { ws.close(); } catch {}
     }
+    for (const s of cursors.values()) flushOne(s);
     connector.stop();
     process.exit(0);
   });

package/dist/connector.js

@@ -365,11 +365,120 @@ function peekPayload(token) {
   }
 }
 
+// connector/run.ts
+import { join } from "node:path";
+
 // src/redact.ts
 function redactSecrets(text) {
   return text.replace(/ac_[A-Za-z0-9_-]{16,}/g, "ac_***REDACTED***").replace(/eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "***JWT_REDACTED***");
 }
 
+// src/read-cursor.ts
+import { readFileSync, writeFileSync } from "fs";
+function loadCursor(file, warn) {
+  try {
+    return new Map(Object.entries(JSON.parse(readFileSync(file, "utf-8"))));
+  } catch (e) {
+    if (e?.code !== "ENOENT") {
+      warn(`[agentchat] WARNING: could not read ${file} — resetting that state: ${e}
+`);
+    }
+    return new Map;
+  }
+}
+function persistCursor(file, cursor, warn) {
+  try {
+    writeFileSync(file, JSON.stringify(Object.fromEntries(cursor)));
+    return true;
+  } catch (e) {
+    warn(`[agentchat] WARNING: failed to persist read cursor to ${file}: ${e}
+`);
+    return false;
+  }
+}
+function flushCursor(state, persist) {
+  if (!state.dirty)
+    return false;
+  const ok = persist();
+  if (ok)
+    state.dirty = false;
+  return ok;
+}
+
+// src/timestamps.ts
+function normalizeTimestampForCursor(ts, mode) {
+  if (!ts || typeof ts !== "string")
+    return ts;
+  const padChar = mode === "before" ? "9" : "0";
+  const withFrac = ts.match(/^(.*\.)(\d+)(Z)$/);
+  if (withFrac) {
+    const frac = withFrac[2];
+    if (frac.length >= 9)
+      return ts;
+    return withFrac[1] + frac + padChar.repeat(9 - frac.length) + withFrac[3];
+  }
+  const noFrac = ts.match(/^(.*\d)(Z)$/);
+  if (noFrac) {
+    return noFrac[1] + "." + padChar.repeat(9) + noFrac[2];
+  }
+  return ts;
+}
+
+// src/dedup.ts
+function messageDedupKey(data) {
+  if (!data || typeof data.id !== "string" || typeof data.channel_id !== "string")
+    return null;
+  return `${data.channel_id}:${data.id}`;
+}
+
+class MessageDedup {
+  max;
+  dropOnEvict;
+  seen = new Set;
+  constructor(max = 5000, dropOnEvict = 1000) {
+    this.max = max;
+    this.dropOnEvict = dropOnEvict;
+  }
+  recordOrSkip(key) {
+    if (this.seen.has(key))
+      return true;
+    this.seen.add(key);
+    if (this.seen.size > this.max) {
+      const arr = [...this.seen];
+      this.seen.clear();
+      for (const item of arr.slice(this.dropOnEvict))
+        this.seen.add(item);
+    }
+    return false;
+  }
+  get size() {
+    return this.seen.size;
+  }
+}
+
+// connector/backfill.ts
+function planBackfill(after, msgs, agentId) {
+  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 };
+}
+
 // connector/run.ts
 var log = (m) => process.stderr.write(`[agentschat-connector] ${m}
 `);
@@ -429,6 +538,49 @@ for (const id of identities) {
 var broadcast = null;
 var socketsByBot = new Map;
 var backoffByBot = new Map;
+var backfillTimerByBot = new Map;
+var dedup = new MessageDedup;
+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;
+function cursorFor(id) {
+  let s = cursors.get(id.botId);
+  if (s)
+    return s;
+  const file = join(CURSOR_DIR, `last-seen-msg-ts-${id.botId}.json`);
+  s = { file, map: loadCursor(file, (m) => log(m.trimEnd())), state: { dirty: false }, timer: null };
+  cursors.set(id.botId, s);
+  return s;
+}
+function flushOne(s) {
+  if (s.timer) {
+    clearTimeout(s.timer);
+    s.timer = null;
+  }
+  flushCursor(s.state, () => persistCursor(s.file, s.map, (m) => log(m.trimEnd())));
+}
+function scheduleSave(s) {
+  s.state.dirty = true;
+  if (s.timer)
+    return;
+  s.timer = setTimeout(() => {
+    s.timer = null;
+    flushOne(s);
+  }, cursorFlushMs);
+  s.timer.unref?.();
+}
+function advanceCursor(id, channelId, timestamp) {
+  if (typeof channelId !== "string" || typeof timestamp !== "string" || !timestamp)
+    return;
+  const s = cursorFor(id);
+  const prev = s.map.get(channelId) || "";
+  const currentTs = normalizeTimestampForCursor(timestamp, "after") || timestamp;
+  const prevTs = normalizeTimestampForCursor(prev, "after") || prev;
+  if (currentTs > prevTs) {
+    s.map.set(channelId, timestamp);
+    scheduleSave(s);
+  }
+}
 function joinChannel(ws, id, channelId, name) {
   try {
     ws.send(JSON.stringify({ type: "join_channel", channel_id: channelId, agent_id: id.agentId }));
@@ -446,16 +598,63 @@ async function joinMemberships(ws, id) {
     }
     const body = await r.json();
     const channels = Array.isArray(body) ? body : body.channels || [];
+    const joined = [];
     for (const ch of channels) {
       const channelId = ch?.id || ch?.channel_id;
       if (!channelId)
         continue;
       joinChannel(ws, id, channelId, ch?.name);
+      joined.push(channelId);
     }
+    const prev = backfillTimerByBot.get(id.botId);
+    if (prev)
+      clearTimeout(prev);
+    const t = setTimeout(() => {
+      backfillTimerByBot.delete(id.botId);
+      if (process.__shutdown)
+        return;
+      backfillIdentity(id, joined);
+    }, 2000);
+    t.unref?.();
+    backfillTimerByBot.set(id.botId, t);
   } catch (e) {
     log(`join-on-auth failed: ${e?.message ?? e}`);
   }
 }
+async function backfillIdentity(id, channelIds) {
+  const s = cursorFor(id);
+  for (const channelId of channelIds) {
+    try {
+      const after = s.map.get(channelId);
+      const params = after ? `?after=${encodeURIComponent(after)}&limit=50` : `?limit=1`;
+      const r = await fetch(`${API}/api/channels/${encodeURIComponent(channelId)}/messages${params}`, {
+        headers: { Authorization: `Bearer ${id.token}` }
+      });
+      if (!r.ok)
+        continue;
+      const msgs = (await r.json())?.messages ?? [];
+      const plan = planBackfill(after, msgs, id.agentId);
+      if (plan.seed) {
+        s.map.set(channelId, plan.seed);
+        scheduleSave(s);
+        continue;
+      }
+      if (!plan.replay.length)
+        continue;
+      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);
+      }
+    } catch (e) {
+      log(`backfill failed for ${id.botId} ${channelId}: ${e?.message ?? e}`);
+    }
+  }
+}
 function connectIdentity(id) {
   const ws = new WS(WS_URL);
   socketsByBot.set(id.botId, ws);
@@ -481,8 +680,17 @@ function connectIdentity(id) {
       joinChannel(ws, id, data.channel_id, data.name);
       return;
     }
-    if (data.type === "message" && data.sender_id !== id.agentId) {
-      broadcast?.({ ...data, __botId: id.botId });
+    if (data.type === "message") {
+      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__") {
+        broadcast?.({ ...data, __botId: id.botId });
+      }
     }
   });
   ws.on("close", () => {
@@ -565,6 +773,8 @@ for (const sig of ["SIGINT", "SIGTERM"]) {
         ws.close();
       } catch {}
     }
+    for (const s of cursors.values())
+      flushOne(s);
     connector.stop();
     process.exit(0);
   });