agentschat-mcp 0.31.0 → 0.32.0

package/connector/server.ts

@@ -1,20 +1,25 @@
 /**
  * agentschat connector — the connector side of the Hermes relay contract.
  *
- * Single-tenant: one agentschat identity, one tenant. The gateway dials OUT to
- * this server's `/relay` WebSocket with an `Authorization: Bearer <upgrade token>`
- * header; on a valid token the connection is admitted and the contract's frame
- * exchange proceeds (see ws_transport.py on the gateway side):
+ * Single-tenant AND multiplex: one relay WS server fronts one OR MORE agentschat
+ * identities (one per Hermes profile/agent). Hermes fronts multiple identities on
+ * one WS by sending one `hello` per (platform, botId); here platform is always
+ * "agentschat" and botId is the agentschat agent_id.
  *
+ * Frame exchange (see gateway ws_transport.py):
  *   gateway  → hello           {type:"hello", platform, botId}
- *   connector→ descriptor      {type:"descriptor", descriptor:{...}}
- *   connector→ inbound         {type:"inbound", event:{...}}          (agentschat → gateway)
- *   gateway  → outbound        {type:"outbound", requestId, action}
+ *   connector→ descriptor      {type:"descriptor", descriptor:{...}}   (one per hello)
+ *   connector→ inbound         {type:"inbound", event:{...}}           (agentschat → gateway)
+ *   gateway  → outbound        {type:"outbound", requestId, platform?, action}
  *   connector→ outbound_result {type:"outbound_result", requestId, result}
  *
- * Auth is fail-closed: anything wrong with the upgrade token closes 4401 before
- * the socket is admitted (the gateway treats a 4401 before first successful
- * handshake as retryable, but we never let an unauthenticated socket through).
+ * Auth is fail-closed: anything wrong with the upgrade token closes 4401 before the
+ * socket is admitted.
+ *
+ * The single highest-correctness invariant (multiplex): identity A's messages are
+ * NEVER routed to or sent as identity B. Inbound routes to the socket(s) fronting the
+ * addressed identity; outbound uses the sending identity's own token; an identity the
+ * connector has no credentials for is rejected at hello (fail closed).
  */
 
 import { createServer, type Server as HttpServer, type IncomingMessage } from "node:http";
@@ -22,9 +27,17 @@ import { WebSocketServer, WebSocket } from "ws";
 import { verifyUpgradeToken, CLOSE_UNAUTHORIZED } from "./auth.ts";
 import { buildDescriptor, type CapabilityDescriptor } from "./descriptor.ts";
 import { toWireEvent, type AgentsChatMessage } from "./normalize.ts";
+import { IdentityTable, routeInbound, type Identity } from "./identities.ts";
 
-/** What the connector needs from agentschat to fulfil outbound ops. */
+/** What the connector needs from agentschat to fulfil outbound ops, per identity. */
 export interface AgentsChatHooks {
+  sendMessage(botId: string, chatId: string, content: string, replyTo?: string): Promise<{ id?: string }>;
+  getChatInfo(botId: string, chatId: string): Promise<{ name?: string; type?: string }>;
+  sendTyping?(botId: string, chatId: string): Promise<void>;
+}
+
+/** Legacy single-tenant hook shape (no botId first arg) — adapted to the per-identity one. */
+interface LegacyHooks {
   sendMessage(chatId: string, content: string, replyTo?: string): Promise<{ id?: string }>;
   getChatInfo(chatId: string): Promise<{ name?: string; type?: string }>;
   sendTyping?(chatId: string): Promise<void>;
@@ -35,29 +48,55 @@ export interface ConnectorConfig {
   host?: string;
   /** gatewayId → acceptable secrets (rotation window). */
   secrets: Record<string, string[]>;
+  /**
+   * The identities this connector fronts. Multiplex: one per agentschat identity.
+   * Single-tenant (legacy): omit and provide `agentschat` — a single implicit
+   * identity is derived (botId "default").
+   */
+  identities?: Identity[];
   /** Override the descriptor (tests/customization); defaults to the agentschat descriptor. */
   descriptor?: Partial<CapabilityDescriptor>;
-  agentschat: AgentsChatHooks;
-  /** Called for each agentschat message to broadcast to connected gateways. */
+  agentschat: AgentsChatHooks | LegacyHooks;
   logger?: (msg: string) => void;
 }
 
 export interface ConnectorHandle {
   port: number;
   stop(): void;
-  /** Push an agentschat message to every connected gateway as an inbound frame. */
+  /** Push an agentschat message to the gateway socket(s) fronting its addressed identity. */
   injectAgentsChatMessage(msg: AgentsChatMessage): void;
   connections(): number;
 }
 
+/** A connected gateway socket and the set of identities it has hello'd (fronts). */
+interface GatewayConn {
+  ws: WebSocket;
+  gatewayId: string;
+  /** botIds this socket has declared via hello. */
+  fronted: Set<string>;
+}
+
 export function startConnector(config: ConnectorConfig): ConnectorHandle {
   const log = config.logger ?? (() => {});
   const descriptor = buildDescriptor(config.descriptor);
-  const sockets = new Set<WebSocket>();
+  const single = !config.identities || config.identities.length === 0;
+  const table = new IdentityTable(
+    single ? [{ botId: "default", agentId: "default", token: "", gatewayId: "", secret: "" }] : config.identities!,
+  );
+  // Normalize hooks to the per-identity shape. Legacy single-tenant hooks take
+  // (chatId, ...); wrap them to ignore the botId. Per-identity hooks take botId first.
+  const hooks: AgentsChatHooks = single
+    ? {
+        sendMessage: (_b, chatId, content, replyTo) => (config.agentschat as LegacyHooks).sendMessage(chatId, content, replyTo),
+        getChatInfo: (_b, chatId) => (config.agentschat as LegacyHooks).getChatInfo(chatId),
+        sendTyping: (_b, chatId) => (config.agentschat as LegacyHooks).sendTyping?.(chatId) ?? Promise.resolve(),
+      }
+    : (config.agentschat as AgentsChatHooks);
+  const sockets = new Set<GatewayConn>();
 
   const http: HttpServer = createServer((_req, res) => {
     res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ ok: true, service: "agentschat-connector", contract_version: 1 }));
+    res.end(JSON.stringify({ ok: true, service: "agentschat-connector", contract_version: 1, identities: table.size }));
   });
 
   const wss = new WebSocketServer({ noServer: true });
@@ -70,16 +109,11 @@ export function startConnector(config: ConnectorConfig): ConnectorHandle {
     }
     const auth = req.headers.authorization ?? "";
     const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
-    // Peek the gateway id (payload head) to select that gateway's verify list.
     const payload = peekPayload(token);
     const secrets = payload ? config.secrets[payload] : undefined;
     const gatewayId = secrets ? verifyUpgradeToken(token, secrets) : null;
     if (!gatewayId) {
       log(`[connector] rejecting upgrade: bad/absent token (path=${pathname})`);
-      // Write a 4401-flavored close: send an HTTP 401 then destroy, and — once the
-      // WS is established for a valid path — close with the app code. For the
-      // upgrade itself we must reject the handshake; the client observes a failed
-      // upgrade. We additionally complete a minimal WS so we can send close 4401.
       wss.handleUpgrade(req, socket, head, (ws) => {
         ws.close(CLOSE_UNAUTHORIZED, "unauthorized");
       });
@@ -91,65 +125,103 @@ export function startConnector(config: ConnectorConfig): ConnectorHandle {
   });
 
   function onConnection(ws: WebSocket, gatewayId: string) {
-    sockets.add(ws);
+    const conn: GatewayConn = { ws, gatewayId, fronted: new Set() };
+    sockets.add(conn);
     log(`[connector] gateway connected: ${gatewayId} (${sockets.size} total)`);
 
     ws.on("message", async (data) => {
-      let frame: any;
-      try {
-        frame = JSON.parse(data.toString());
-      } catch {
-        return;
+      // Newline-delimited: the gateway may batch frames; split and handle each.
+      const text = data.toString();
+      for (const line of text.split("\n")) {
+        if (!line.trim()) continue;
+        let frame: any;
+        try {
+          frame = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        await handleFrame(conn, frame).catch((e) => log(`[connector] frame error: ${e}`));
       }
-      await handleFrame(ws, frame).catch((e) => log(`[connector] frame error: ${e}`));
     });
     ws.on("close", () => {
-      sockets.delete(ws);
+      sockets.delete(conn);
       log(`[connector] gateway disconnected: ${gatewayId} (${sockets.size} left)`);
     });
-    ws.on("error", () => sockets.delete(ws));
+    ws.on("error", () => sockets.delete(conn));
   }
 
-  async function handleFrame(ws: WebSocket, frame: any) {
+  async function handleFrame(conn: GatewayConn, frame: any) {
     const t = frame?.type;
     if (t === "hello") {
-      send(ws, { type: "descriptor", descriptor });
+      const botId = String(frame.botId ?? "");
+      // Single-tenant (no identity table configured): front whatever identity the
+      // gateway declares — there's exactly one. Multiplex: the botId MUST be a
+      // registered identity (fail closed — never front an identity we can't send as).
+      const identity = single
+        ? table.all()[0]
+        : botId
+          ? table.forBot(botId)
+          : null;
+      if (!identity) {
+        send(conn.ws, { type: "error", error: `unknown identity botId: ${botId || "(none)"}` });
+        return;
+      }
+      conn.fronted.add(identity.botId);
+      send(conn.ws, { type: "descriptor", descriptor: { ...descriptor, platform: "agentschat" } });
       return;
     }
     if (t === "outbound") {
-      const result = await handleOutbound(frame.action ?? {});
-      send(ws, { type: "outbound_result", requestId: frame.requestId, result });
+      const result = await handleOutbound(conn, frame);
+      send(conn.ws, { type: "outbound_result", requestId: frame.requestId, result });
       return;
     }
     // Unknown / ignored frame types (interrupt, etc.) — additive contract, ignore.
   }
 
-  async function handleOutbound(action: any): Promise<any> {
+  async function handleOutbound(conn: GatewayConn, frame: any): Promise<any> {
+    const action = frame?.action ?? {};
     const op = action?.op;
     const chatId = action?.chat_id ?? "";
+    // Which identity sends? The frame's botId picks the egress identity for a
+    // multi-identity gateway (contract D-Q1.5b.1: the connector validates the
+    // per-frame egress target against the SET of identities THIS socket
+    // advertised via hello). Untagged outbound falls back to the FIRST hello'd
+    // identity (the session default). Fail closed when the named identity isn't
+    // registered or wasn't fronted by this socket — never send with another
+    // identity's credentials.
+    const firstFronted = [...conn.fronted][0];
+    const requested = typeof frame?.botId === "string" && frame.botId ? frame.botId : firstFronted ?? null;
+    const identity = single
+      ? table.all()[0]
+      : requested && conn.fronted.has(requested)
+        ? table.forBot(requested)
+        : null;
+    if (!identity) {
+      log(`[connector] outbound failed: no fronted identity for botId=${requested ?? "?"}`);
+      return { success: false, error: `no fronted identity for outbound (botId=${requested ?? "?"})` };
+    }
     switch (op) {
       case "send": {
-        const r = await config.agentschat.sendMessage(chatId, action.content ?? "", action.reply_to);
+        const r = await hooks.sendMessage(identity.botId, chatId, action.content ?? "", action.reply_to);
         return { success: true, message_id: r?.id };
       }
       case "typing": {
-        await config.agentschat.sendTyping?.(chatId);
+        await hooks.sendTyping?.(identity.botId, chatId);
         return { success: true };
       }
       case "get_chat_info": {
-        const info = await config.agentschat.getChatInfo(chatId);
+        const info = await hooks.getChatInfo(identity.botId, chatId);
         return info ?? {};
       }
       default:
+        log(`[connector] outbound failed: unsupported op ${String(op)}`);
         return { success: false, error: `unsupported op: ${String(op)}` };
     }
   }
 
   function send(ws: WebSocket, obj: any) {
-    // The relay transport is newline-delimited (gateway ws_transport.py's read loop
-    // splits on "\n"). A frame without a trailing newline never reaches the
-    // gateway's frame handler — it sits in the reader's buffer waiting for the
-    // terminator. This is why the descriptor must end with \n.
+    // Newline-delimited (gateway ws_transport.py splits on "\n"): a frame without the
+    // terminator never reaches the gateway's frame handler.
     if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(obj) + "\n");
   }
 
@@ -160,16 +232,35 @@ export function startConnector(config: ConnectorConfig): ConnectorHandle {
   return {
     port,
     stop() {
-      for (const ws of sockets) {
-        try { ws.close(1001, "connector shutdown"); } catch {}
+      for (const c of sockets) {
+        try { c.ws.close(1001, "connector shutdown"); } catch {}
       }
       wss.close();
       http.close();
     },
     injectAgentsChatMessage(msg: AgentsChatMessage) {
-      const event = toWireEvent(msg, descriptor.platform);
+      // Route to the identity this message is addressed to, then only to gateway
+      // socket(s) fronting THAT identity — never broadcast across identities.
+      // The strongest signal is __botId: which identity's agentschat socket the
+      // message ARRIVED on (agentschat only pushes @mentions/DMs to that agent).
+      // Fall back to mention/DM-owner routing for hosts that don't tag.
+      const bySocket = (msg as any).__botId ? table.forBot(String((msg as any).__botId)) : null;
+      const target = bySocket ?? routeInbound(table, {
+        channel_id: msg.channel_id,
+        mentioned_ids: (msg as any).mentioned_ids,
+        dmOwnerBotId: (msg as any).dm_owner,
+      }) ?? (table.isSingle() ? table.all()[0] : null);
+      if (!target) {
+        log(`[connector] inbound unaddressed (channel=${(msg as any).channel_id ?? "?"} mentions=${JSON.stringify((msg as any).mentioned_ids ?? [])}) — dropped`);
+        return;
+      }
+      const event = toWireEvent(msg, "agentschat");
       if (!event) return;
-      for (const ws of sockets) send(ws, { type: "inbound", event });
+      // Tag the fronting identity so the gateway keys the right session/profile.
+      (event.source as any).profile = target.botId;
+      for (const conn of sockets) {
+        if (conn.fronted.has(target.botId)) send(conn.ws, { type: "inbound", event });
+      }
     },
     connections() {
       return sockets.size;