agentschat-mcp 0.33.5 → 0.34.0

package/connector/identities.ts

@@ -63,6 +63,29 @@ export class IdentityTable {
   all(): Identity[] {
     return [...this.byBot.values()];
   }
+
+  /**
+   * Hot-replace the identity set (RELAY_IDENTITIES reload). Fails closed on
+   * duplicate botIds the same way the constructor does.
+   */
+  replace(identities: Identity[]): void {
+    const next = new Map<string, Identity>();
+    for (const id of identities) {
+      if (next.has(id.botId)) {
+        throw new Error(`duplicate identity botId "${id.botId}" — ambiguous routing`);
+      }
+      next.set(id.botId, id);
+    }
+    this.byBot.clear();
+    for (const [k, v] of next) this.byBot.set(k, v);
+  }
+}
+
+/** Platform hooks must never substitute another identity's credentials. */
+export function requireIdentity(identities: readonly Identity[], botId: string): Identity {
+  const id = identities.find(id => id.botId === botId);
+  if (!id) throw new Error(`unknown identity: ${botId}`);
+  return id;
 }
 
 export interface InboundContext {
@@ -90,6 +113,23 @@ export interface InboundContext {
  * the agent's session and burn its tokens on chatter not addressed to it.
  * `mentioned_ids` is still honored when a host provides it (explicit signal wins).
  */
+function matchesExactMention(content: string, id: string): boolean {
+  if (!id) return false;
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|[^\\p{L}\\p{N}_@-])@(?:${escaped}(?![\\p{L}\\p{N}_(-])|[^\\s@()]+\\(${escaped}\\))`, "u").test(content);
+}
+
+/** All exact addressed targets, once each, in identity-table order. */
+export function routeInboundTargets(table: IdentityTable, ctx: InboundContext): Identity[] {
+  if (ctx.channel_id?.startsWith("dm-")) {
+    const owner = ctx.dmOwnerBotId ? table.forBot(ctx.dmOwnerBotId) : null;
+    return owner ? [owner] : [];
+  }
+  const mentioned = Array.isArray(ctx.mentioned_ids) ? ctx.mentioned_ids : [];
+  return table.all().filter(id => mentioned.includes(id.botId) ||
+    matchesExactMention(ctx.content ?? "", id.agentId) || matchesExactMention(ctx.content ?? "", id.botId));
+}
+
 export function routeInbound(table: IdentityTable, ctx: InboundContext): Identity | null {
   // DM: route to the identity that owns the DM channel.
   if (ctx.channel_id?.startsWith("dm-")) {

package/connector/ingest.ts

@@ -0,0 +1,42 @@
+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 });
+  const isDm = frame.channel_id?.startsWith("dm-");
+  const scopedKey = key && (isDm ? JSON.stringify([id.botId, frame.channel_id, frame.id]) : key);
+  if (scopedKey && deps.dedup.recordOrSkip(scopedKey)) return false;
+  // Group fanout must filter self per TARGET, not per arrival socket: A can
+  // mention B, and A's self echo may be the first copy of the shared message.
+  return (!frame.channel_id?.startsWith("dm-") || frame.sender_id !== id.agentId) && frame.content !== "__typing__";
+}

package/connector/run.ts

@@ -10,28 +10,39 @@
  * Multiplex (N identities, one per Hermes profile/agent):
  *   RELAY_IDENTITIES = JSON array, one entry per identity:
  *     [{"botId":"<agentschat agent_id>","token":"ac_...","gatewayId":"...","secret":"...","profile":"<hermes profile>"}, ...]
+ *   OR RELAY_IDENTITIES_FILE = path to that JSON array (preferred for hot-reload).
  *   Each botId is an agentschat agent_id. Optional `profile` is the Hermes profile
  *   name (for gateway.multiplex_profiles). Do NOT put the AgentsChat agent_id in
  *   profile — that splits Hermes session keys and breaks clarify. The connector
  *   holds all identities, opens one agentschat WS per identity, and routes by
- *   identity — identity A's messages never cross to identity B.
+ *   identity. Each gateway must hello its own authorized botId. Prefer distinct
+ *   gatewayId/secret pairs per bot with separate single-identity gateways.
+ *   Shared multi-hello connections require explicit, correct outbound botIds.
+ *
+ * Hot-reload (no process rewrite):
+ *   SIGHUP re-reads RELAY_IDENTITIES_FILE (or RELAY_IDENTITIES env), opens WS for
+ *   new botIds, disconnects removed ones. New identities need a gateway hello.
  *
  * Common:
  *   AGENTCHAT_API_URL      REST base (default https://agents-chat.com)
  *   AGENTCHAT_WS_URL       WebSocket (default wss://agents-chat.com/ws)
  *   RELAY_PORT             port to listen on (default 8765)
  *   RELAY_HOST             bind host (default 127.0.0.1)
+ *   RELAY_IDENTITIES_FILE  path to JSON identities array (SIGHUP reloads it)
  */
 
 import WS from "ws";
-import { startConnector } from "./server.ts";
-import type { Identity } from "./identities.ts";
+import { readFileSync } from "node:fs";
+import { startConnector, PlatformHttpError, PlatformNetworkError } from "./server.ts";
+import { requireIdentity, 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 { 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`);
 
@@ -49,36 +60,50 @@ const WS_URL = process.env.AGENTCHAT_WS_URL || API.replace(/^http/, "ws") + "/ws
 const PORT = Number(process.env.RELAY_PORT || 8765);
 const HOST = process.env.RELAY_HOST || "127.0.0.1";
 
-// ── Resolve identities: multiplex (RELAY_IDENTITIES) or single-tenant (legacy env) ──
+// ── Resolve identities: multiplex (RELAY_IDENTITIES[_FILE]) or single-tenant (legacy env) ──
 
-function resolveIdentities(): Identity[] {
+function parseIdentitiesJson(raw: string, source: string): Identity[] {
+  let parsed: any;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${source} is not valid JSON`);
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(`${source} must be a non-empty JSON array`);
+  }
+  const seen = new Set<string>();
+  for (const [index, it] of parsed.entries()) {
+    const invalid = ["botId", "token", "gatewayId", "secret"].filter(k => typeof it?.[k] !== "string" || !it[k].trim());
+    for (const k of ["agentId", "profile"]) {
+      if (it?.[k] !== undefined && (typeof it[k] !== "string" || !it[k].trim())) invalid.push(k);
+    }
+    if (invalid.length) throw new Error(`${source} entry ${index}: missing or invalid string fields: ${invalid.join(", ")}`);
+    if (seen.has(it.botId)) throw new Error(`${source} entry ${index}: duplicate botId`);
+    seen.add(it.botId);
+  }
+  return parsed.map((it: any) => ({
+    botId: String(it.botId),
+    agentId: String(it.agentId ?? it.botId),
+    token: String(it.token),
+    gatewayId: String(it.gatewayId),
+    secret: String(it.secret),
+    ...(it.profile ? { profile: String(it.profile) } : {}),
+  }));
+}
+
+/** Load identities; throws on bad JSON/shape (SIGHUP keeps prior set). */
+function loadIdentities(): Identity[] {
+  const file = (process.env.RELAY_IDENTITIES_FILE || "").trim();
+  if (file) {
+    let raw: string;
+    try { raw = readFileSync(file, "utf8"); }
+    catch { throw new Error("RELAY_IDENTITIES_FILE could not be read"); }
+    return parseIdentitiesJson(raw, "RELAY_IDENTITIES_FILE");
+  }
   const raw = (process.env.RELAY_IDENTITIES || "").trim();
   if (raw) {
-    let parsed: any;
-    try {
-      parsed = JSON.parse(raw);
-    } catch (e) {
-      log(`ERROR: RELAY_IDENTITIES is not valid JSON: ${e}`);
-      process.exit(1);
-    }
-    if (!Array.isArray(parsed) || parsed.length === 0) {
-      log(`ERROR: RELAY_IDENTITIES must be a non-empty JSON array`);
-      process.exit(1);
-    }
-    for (const it of parsed) {
-      if (!it?.botId || !it?.token || !it?.gatewayId || !it?.secret) {
-        log(`ERROR: each RELAY_IDENTITIES entry needs botId, token, gatewayId, secret — got: ${JSON.stringify(it).slice(0, 80)}`);
-        process.exit(1);
-      }
-    }
-    return parsed.map((it: any) => ({
-      botId: String(it.botId),
-      agentId: String(it.agentId ?? it.botId),
-      token: String(it.token),
-      gatewayId: String(it.gatewayId),
-      secret: String(it.secret),
-      ...(it.profile ? { profile: String(it.profile) } : {}),
-    }));
+    return parseIdentitiesJson(raw, "RELAY_IDENTITIES");
   }
   // Single-tenant legacy env.
   const agentId = need("AGENTCHAT_AGENT_ID");
@@ -88,10 +113,20 @@ function resolveIdentities(): Identity[] {
   return [{ botId: agentId, agentId, token, gatewayId, secret }];
 }
 
-const identities = resolveIdentities();
-const single = identities.length === 1;
+function resolveIdentitiesAtStartup(): Identity[] {
+  try {
+    return loadIdentities();
+  } catch (e: any) {
+    log(`ERROR: ${e?.message ?? e}`);
+    process.exit(1);
+  }
+}
+
+/** Mutable identity list — hooks and reload close over this binding. */
+let identities = resolveIdentitiesAtStartup();
 
 // The per-gateway secret table for the relay upgrade auth (gatewayId → secrets).
+// Mutated in place on hot-reload so startConnector's closed-over object stays valid.
 const secrets: Record<string, string[]> = {};
 for (const id of identities) {
   (secrets[id.gatewayId] ??= []).push(id.secret);
@@ -101,10 +136,41 @@ for (const id of identities) {
 
 let broadcast: ((msg: any) => void) | null = null;
 const socketsByBot = new Map<string, WS>();
+const reconnectTimerByBot = new Map<string, ReturnType<typeof setTimeout>>();
+// Identity object is the generation token; unchanged reload rows retain it.
+const currentIdentity = (id: Identity) => !(process as any).__shutdown && identities.includes(id);
+function cancelReconnect(botId: string) {
+  const timer = reconnectTimerByBot.get(botId);
+  if (timer) clearTimeout(timer);
+  reconnectTimerByBot.delete(botId);
+}
+function scheduleReconnect(id: Identity, delay: number) {
+  if (!currentIdentity(id)) return;
+  cancelReconnect(id.botId);
+  const timer = setTimeout(() => {
+    if (reconnectTimerByBot.get(id.botId) !== timer) return;
+    reconnectTimerByBot.delete(id.botId);
+    if (currentIdentity(id)) connectIdentity(id);
+  }, delay);
+  reconnectTimerByBot.set(id.botId, timer);
+}
 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.
@@ -172,6 +238,7 @@ async function joinMemberships(ws: WS, id: Identity) {
       return;
     }
     const body = await r.json() as any;
+    if (!currentIdentity(id) || socketsByBot.get(id.botId) !== ws) return;
     const channels = Array.isArray(body) ? body : (body.channels || []);
     const joined: string[] = [];
     for (const ch of channels) {
@@ -186,7 +253,7 @@ async function joinMemberships(ws: WS, id: Identity) {
     if (prev) clearTimeout(prev);
     const t = setTimeout(() => {
       backfillTimerByBot.delete(id.botId);
-      if ((process as any).__shutdown) return;
+      if (!currentIdentity(id) || socketsByBot.get(id.botId) !== ws) return;
       void backfillIdentity(id, joined);
     }, 2000);
     (t as any).unref?.();
@@ -199,6 +266,7 @@ async function joinMemberships(ws: WS, id: Identity) {
 async function backfillIdentity(id: Identity, channelIds: string[]) {
   const s = cursorFor(id);
   for (const channelId of channelIds) {
+    if (!currentIdentity(id)) return;
     try {
       const after = s.map.get(channelId);
       const params = after ? `?after=${encodeURIComponent(after)}&limit=50` : `?limit=1`;
@@ -207,6 +275,7 @@ async function backfillIdentity(id: Identity, channelIds: string[]) {
       });
       if (!r.ok) continue;
       const msgs = (((await r.json()) as any)?.messages ?? []) as any[];
+      if (!currentIdentity(id)) return;
       const plan = planBackfill(after, msgs, id.agentId);
       if (plan.seed) {
         s.map.set(channelId, plan.seed);
@@ -217,10 +286,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,43 +297,98 @@ async function backfillIdentity(id: Identity, channelIds: string[]) {
 }
 
 function connectIdentity(id: Identity) {
+  if (!currentIdentity(id)) return;
+  cancelReconnect(id.botId);
+  // 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 (!currentIdentity(id) || socketsByBot.get(id.botId) !== ws || 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);
+        scheduleReconnect(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", () => {
+    if (!currentIdentity(id) || socketsByBot.get(id.botId) !== ws) { ws.close(); return; }
     backoffByBot.set(id.botId, 1000);
     try {
       ws.send(JSON.stringify({ type: "auth", agent_id: id.agentId, token: id.token, capabilities: ["chat"] }));
     } catch {}
   });
   ws.on("message", (raw: any) => {
+    if (!currentIdentity(id) || socketsByBot.get(id.botId) !== ws) return;
     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", () => {
+    if (!currentIdentity(id) || socketsByBot.get(id.botId) !== ws) return;
+    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);
+    scheduleReconnect(id, delay);
     backoffByBot.set(id.botId, Math.min(delay * 2, 30000));
   });
   ws.on("error", (e: any) => log(`agentschat WS error (${id.botId}): ${e?.message ?? e}`));
@@ -280,18 +403,18 @@ const connector = startConnector({
   identities,
   agentschat: {
     async sendMessage(botId, chatId, content, replyTo) {
-      const id = identities.find((i) => i.botId === botId) ?? identities[0];
+      const id = requireIdentity(identities, botId);
       const res = await fetch(`${API}/api/channels/${encodeURIComponent(chatId)}/messages`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${id.token}` },
         body: JSON.stringify({ sender_id: id.agentId, content_type: "text", content, ...(replyTo ? { parent_id: replyTo } : {}) }),
-      });
-      if (!res.ok) throw new Error(`agentschat send failed: ${res.status}`);
+      }).catch(() => { throw new PlatformNetworkError(); });
+      if (!res.ok) throw new PlatformHttpError(res.status);
       const data = (await res.json()) as any;
       return { id: data?.id };
     },
     async getChatInfo(botId, chatId) {
-      const id = identities.find((i) => i.botId === botId) ?? identities[0];
+      const id = requireIdentity(identities, botId);
       const res = await fetch(`${API}/api/channels/${encodeURIComponent(chatId)}`, {
         headers: { Authorization: `Bearer ${id.token}` },
       });
@@ -300,7 +423,7 @@ const connector = startConnector({
       return { name: data?.name ?? chatId, type: chatId.startsWith("dm-") ? "dm" : "group" };
     },
     async sendTyping(botId, chatId) {
-      const id = identities.find((i) => i.botId === botId) ?? identities[0];
+      const id = requireIdentity(identities, botId);
       const ws = socketsByBot.get(id.botId);
       if (ws && ws.readyState === WS.OPEN) {
         try { ws.send(JSON.stringify({ type: "typing", channel_id: chatId, sender_id: id.agentId })); } catch {}
@@ -310,9 +433,10 @@ const connector = startConnector({
     // oldest→newest, trigger message excluded, secrets redacted (a group channel is
     // untrusted content — never forward a leaked key downstream). Best-effort: any
     // failure returns null and the addressed message still delivers without it.
-    async getChannelContext(botId, chatId, sinceTs, excludeId) {
-      const id = identities.find((i) => i.botId === botId) ?? identities[0];
+    async getChannelContext(botId, chatId, sinceTs, excludeId, signal) {
+      const id = requireIdentity(identities, botId);
       const res = await fetch(`${API}/api/channels/${encodeURIComponent(chatId)}/messages?limit=50`, {
+        signal,
         headers: { Authorization: `Bearer ${id.token}` },
       });
       if (!res.ok) return null;
@@ -333,13 +457,82 @@ const connector = startConnector({
 });
 
 broadcast = (msg) => connector.injectAgentsChatMessage(msg);
+await connector.ready;
 log(`listening on ${HOST}:${connector.port} (contract v1, ${identities.length} identit${identities.length === 1 ? "y" : "ies"})`);
 
 for (const id of identities) connectIdentity(id);
 
+/**
+ * Hot-reload RELAY_IDENTITIES without rewriting the connector process.
+ * Prefer RELAY_IDENTITIES_FILE so SIGHUP re-reads disk; env-only deployments
+ * re-parse RELAY_IDENTITIES (unchanged unless the supervisor rewrote the env).
+ * Opens AgentsChat WS for new botIds, disconnects removed ones. Gateway hello
+ * must include each new identity before it receives any inbound traffic.
+ */
+function reloadIdentitiesFromConfig() {
+  const next = loadIdentities().map(id => identities.find(prev =>
+    prev.botId === id.botId && prev.agentId === id.agentId && prev.token === id.token &&
+    prev.gatewayId === id.gatewayId && prev.secret === id.secret && prev.profile === id.profile) ?? id);
+  const prevByBot = new Map(identities.map((i) => [i.botId, i]));
+  const nextByBot = new Map(next.map((i) => [i.botId, i]));
+  const added = next.filter((i) => !prevByBot.has(i.botId));
+  const removed = identities.filter((i) => !nextByBot.has(i.botId));
+  const kept = next.filter((i) => prevByBot.has(i.botId));
+
+  // Table first — if replace throws, leave AgentsChat sockets / `identities` untouched.
+  connector.reloadIdentities(next);
+  identities = next;
+
+  for (const id of removed) {
+    cancelReconnect(id.botId);
+    log(`hot-reload: disconnecting removed identity ${id.botId}`);
+    stopHeartbeat(id.botId);
+    const t = backfillTimerByBot.get(id.botId);
+    if (t) { clearTimeout(t); backfillTimerByBot.delete(id.botId); }
+    const ws = socketsByBot.get(id.botId);
+    if (ws) {
+      try {
+        ws.removeAllListeners("close");
+        ws.close();
+      } catch {}
+      socketsByBot.delete(id.botId);
+    }
+    backoffByBot.delete(id.botId);
+    // Keep cursor files on disk (reconnect watermark survives a temporary remove).
+  }
+  for (const id of kept) {
+    // Token/gateway rotation: update in-memory row already done via `identities = next`.
+    // If the agentschat token changed, force reconnect so auth uses the new key.
+    const prev = prevByBot.get(id.botId)!;
+    if (prev !== id) {
+      cancelReconnect(id.botId);
+      const timer = backfillTimerByBot.get(id.botId);
+      if (timer) clearTimeout(timer);
+      backfillTimerByBot.delete(id.botId);
+      log(`hot-reload: reconnecting ${id.botId} (credentials changed)`);
+      connectIdentity(id);
+    }
+  }
+  for (const id of added) {
+    log(`hot-reload: connecting new identity ${id.botId}`);
+    connectIdentity(id);
+  }
+  log(`hot-reload complete: ${identities.length} identit${identities.length === 1 ? "y" : "ies"} (${added.length} added, ${removed.length} removed)`);
+}
+
+process.on("SIGHUP", () => {
+  try {
+    reloadIdentitiesFromConfig();
+  } catch (e: any) {
+    log(`hot-reload FAILED (keeping previous identities): ${e?.message ?? e}`);
+  }
+});
+
 for (const sig of ["SIGINT", "SIGTERM"] as const) {
   process.on(sig, () => {
     (process as any).__shutdown = true;
+    for (const botId of reconnectTimerByBot.keys()) cancelReconnect(botId);
+    for (const botId of [...heartbeatsByBot.keys()]) stopHeartbeat(botId);
     for (const ws of socketsByBot.values()) {
       try { ws.close(); } catch {}
     }