agentschat-mcp 0.30.0 → 0.32.0

package/connector/run.ts

@@ -0,0 +1,180 @@
+/**
+ * Connector entrypoint: wire the relay connector to one or more agentschat accounts.
+ *
+ * Single-tenant (one identity):
+ *   AGENTCHAT_TOKEN        agentschat agent key (ac_…)
+ *   AGENTCHAT_AGENT_ID     agentschat agent id
+ *   RELAY_GATEWAY_ID       the gateway id hermes uses in its upgrade token
+ *   RELAY_GATEWAY_SECRET   the per-gateway secret that token is HMAC'd with
+ *
+ * Multiplex (N identities, one per Hermes profile/agent):
+ *   RELAY_IDENTITIES = JSON array, one entry per identity:
+ *     [{"botId":"<agentschat agent_id>","token":"ac_...","gatewayId":"...","secret":"..."}, ...]
+ *   Each botId is an agentschat agent_id. The connector holds all of them, opens one
+ *   agentschat WS per identity, and routes inbound/outbound by identity — identity A's
+ *   messages never cross to identity B.
+ *
+ * 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)
+ */
+
+import WS from "ws";
+import { startConnector } from "./server.ts";
+import type { Identity } from "./identities.ts";
+
+const log = (m: string) => process.stderr.write(`[agentschat-connector] ${m}\n`);
+
+function need(name: string): string {
+  const v = process.env[name];
+  if (!v) {
+    log(`ERROR: ${name} is required`);
+    process.exit(1);
+  }
+  return v;
+}
+
+const API = (process.env.AGENTCHAT_API_URL || "https://agents-chat.com").replace(/\/$/, "");
+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) ──
+
+function resolveIdentities(): Identity[] {
+  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),
+    }));
+  }
+  // Single-tenant legacy env.
+  const agentId = need("AGENTCHAT_AGENT_ID");
+  const token = need("AGENTCHAT_TOKEN");
+  const gatewayId = need("RELAY_GATEWAY_ID");
+  const secret = need("RELAY_GATEWAY_SECRET");
+  return [{ botId: agentId, agentId, token, gatewayId, secret }];
+}
+
+const identities = resolveIdentities();
+const single = identities.length === 1;
+
+// The per-gateway secret table for the relay upgrade auth (gatewayId → secrets).
+const secrets: Record<string, string[]> = {};
+for (const id of identities) {
+  (secrets[id.gatewayId] ??= []).push(id.secret);
+}
+
+// ── agentschat connections: one WS per identity ──
+
+let broadcast: ((msg: any) => void) | null = null;
+const socketsByBot = new Map<string, WS>();
+const backoffByBot = new Map<string, number>();
+
+function connectIdentity(id: Identity) {
+  const ws = new WS(WS_URL);
+  socketsByBot.set(id.botId, ws);
+  ws.on("open", () => {
+    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) => {
+    let data: any;
+    try { data = JSON.parse(String(raw)); } catch { return; }
+    if (data.type === "auth_ok") {
+      log(`connected to agentschat as ${id.agentId}`);
+      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 });
+    }
+  });
+  ws.on("close", () => {
+    if ((process as any).__shutdown) return;
+    const delay = backoffByBot.get(id.botId) ?? 1000;
+    log(`agentschat WS closed for ${id.botId}; reconnecting in ${delay}ms`);
+    setTimeout(() => connectIdentity(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}`));
+}
+
+const connector = startConnector({
+  port: PORT,
+  host: HOST,
+  secrets,
+  identities: single ? undefined : identities, // single-tenant → derived default identity
+  agentschat: {
+    async sendMessage(botId, chatId, content, replyTo) {
+      const id = identities.find((i) => i.botId === botId) ?? identities[0];
+      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}`);
+      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 res = await fetch(`${API}/api/channels/${encodeURIComponent(chatId)}`, {
+        headers: { Authorization: `Bearer ${id.token}` },
+      });
+      if (!res.ok) return { name: chatId, type: chatId.startsWith("dm-") ? "dm" : "group" };
+      const data = (await res.json()) as any;
+      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 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 {}
+      }
+    },
+  },
+  logger: log,
+});
+
+broadcast = (msg) => connector.injectAgentsChatMessage(msg);
+log(`listening on ${HOST}:${connector.port} (contract v1, ${identities.length} identit${identities.length === 1 ? "y" : "ies"})`);
+
+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 ws of socketsByBot.values()) {
+      try { ws.close(); } catch {}
+    }
+    connector.stop();
+    process.exit(0);
+  });
+}

package/connector/server.ts

@@ -0,0 +1,281 @@
+/**
+ * agentschat connector — the connector side of the Hermes relay contract.
+ *
+ * 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:{...}}   (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 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";
+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, 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>;
+}
+
+export interface ConnectorConfig {
+  port: number;
+  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 | LegacyHooks;
+  logger?: (msg: string) => void;
+}
+
+export interface ConnectorHandle {
+  port: number;
+  stop(): void;
+  /** 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 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, identities: table.size }));
+  });
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  http.on("upgrade", (req: IncomingMessage, socket, head) => {
+    const { pathname } = new URL(req.url ?? "/", "http://localhost");
+    if (pathname !== "/relay") {
+      socket.destroy();
+      return;
+    }
+    const auth = req.headers.authorization ?? "";
+    const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
+    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})`);
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        ws.close(CLOSE_UNAUTHORIZED, "unauthorized");
+      });
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      onConnection(ws, gatewayId);
+    });
+  });
+
+  function onConnection(ws: WebSocket, gatewayId: string) {
+    const conn: GatewayConn = { ws, gatewayId, fronted: new Set() };
+    sockets.add(conn);
+    log(`[connector] gateway connected: ${gatewayId} (${sockets.size} total)`);
+
+    ws.on("message", async (data) => {
+      // 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}`));
+      }
+    });
+    ws.on("close", () => {
+      sockets.delete(conn);
+      log(`[connector] gateway disconnected: ${gatewayId} (${sockets.size} left)`);
+    });
+    ws.on("error", () => sockets.delete(conn));
+  }
+
+  async function handleFrame(conn: GatewayConn, frame: any) {
+    const t = frame?.type;
+    if (t === "hello") {
+      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(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(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 hooks.sendMessage(identity.botId, chatId, action.content ?? "", action.reply_to);
+        return { success: true, message_id: r?.id };
+      }
+      case "typing": {
+        await hooks.sendTyping?.(identity.botId, chatId);
+        return { success: true };
+      }
+      case "get_chat_info": {
+        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) {
+    // 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");
+  }
+
+  http.listen(config.port, config.host ?? "127.0.0.1");
+  const address = http.address();
+  const port = typeof address === "object" && address ? address.port : config.port;
+
+  return {
+    port,
+    stop() {
+      for (const c of sockets) {
+        try { c.ws.close(1001, "connector shutdown"); } catch {}
+      }
+      wss.close();
+      http.close();
+    },
+    injectAgentsChatMessage(msg: AgentsChatMessage) {
+      // 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;
+      // 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;
+    },
+  };
+}
+
+/** Peek the payload head of an upgrade token without verifying (to index secrets). */
+function peekPayload(token: string): string | null {
+  try {
+    const decoded = Buffer.from(token, "base64url").toString("utf8");
+    const parts = decoded.split(":");
+    if (parts.length < 3) return null;
+    return parts.slice(0, -2).join(":");
+  } catch {
+    return null;
+  }
+}