@particle-academy/agent-integrations 0.5.0 → 0.6.0

package/dist/relay-server/index.d.ts

@@ -0,0 +1,134 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * RelayBroker — pure logic for the SSE+POST tunnel described in
+ * docs/relay-protocol.md, hostable in any Node-compatible runtime
+ * (Node, Bun, Deno-with-Node-compat, Cloudflare Workers via the Web
+ * standards subset). No HTTP framework opinions; this class just
+ * stores sessions, validates tokens, enqueues frames, and produces
+ * SSE event payloads ready to flush.
+ *
+ *   const broker = new RelayBroker();
+ *   const reg     = broker.register("session-id", "token");      // ok / error
+ *   broker.inbox("session-id", "token", '{"jsonrpc":"2.0",…}');  // enqueue inbound
+ *   const sub = broker.subscribe("session-id", "token", "inbound");
+ *   for await (const payload of sub.frames()) yield encodeSse(payload);
+ *
+ * Storage is an in-memory Map by default — fine for a single relay
+ * process. To run multiple instances behind a load balancer, swap
+ * `MemoryStore` for a Redis-backed equivalent (same Store interface).
+ */
+type Direction = "inbound" | "outbound";
+type Session = {
+    id: string;
+    /** SHA-256 hex of the original token. Compared with timing-safe equals. */
+    tokenHash: string;
+    /** Last touched (ms since epoch). Used for TTL cleanup. */
+    lastSeen: number;
+};
+type Subscriber = {
+    id: string;
+    direction: Direction;
+    queue: string[];
+    resolveNext: ((frame: string | null) => void) | null;
+};
+type RelayBrokerOptions = {
+    /** Sessions auto-expire after this many ms of inactivity. Default 4h. */
+    ttlMs?: number;
+    /** Cleanup tick interval in ms. Default 60 000. */
+    reapIntervalMs?: number;
+    /** Bring-your-own storage layer (redis, etc.). Defaults to in-memory. */
+    store?: Store;
+};
+interface Store {
+    putSession(s: Session): void;
+    getSession(id: string): Session | undefined;
+    deleteSession(id: string): void;
+    /** Used by the reap tick — return ids whose lastSeen < cutoff. */
+    expiredSessionIds(cutoff: number): string[];
+}
+declare class RelayBroker {
+    private readonly ttlMs;
+    private readonly store;
+    /** Per-session, per-direction subscriber list. */
+    private subs;
+    private reaper?;
+    constructor(opts?: RelayBrokerOptions);
+    dispose(): void;
+    /** Register a session id + token. Idempotent — same id+token re-registers,
+     *  different token fails. */
+    register(id: string, token: string): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    unregister(id: string, token: string): boolean;
+    /** Validate an authenticated touch and slide the TTL forward. */
+    validate(id: string, token: string): boolean;
+    /** Push a frame onto the inbound queue (external agent → browser). */
+    inbox(id: string, token: string, payload: string): boolean;
+    /** Push a frame onto the outbound queue (browser server → external agents). */
+    outbox(id: string, token: string, payload: string): boolean;
+    /**
+     * Subscribe to a session's queue for one direction. Returns an iterable
+     * the caller (an HTTP handler) pumps as SSE.
+     */
+    subscribe(id: string, token: string, direction: Direction): SubscribeResult;
+    private getDirSubs;
+    private fanOut;
+    private isFrame;
+    private reap;
+}
+type SubscribeResult = {
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    subscriberId: string;
+    frames: AsyncGenerator<string, void, void>;
+    unsubscribe: () => void;
+};
+
+/**
+ * Node HTTP adapter for {@link RelayBroker}. Returns a single request
+ * handler plus per-route handlers, so you can either drop it into
+ * `http.createServer(...)` directly or mount the individual handlers
+ * onto your existing Node HTTP framework (Express, Hono w/ node-adapter,
+ * native http).
+ *
+ *   const relay = createNodeRelay({ pathPrefix: "/mcp-relay" });
+ *   http.createServer(relay.handler).listen(8787);
+ *
+ *   // Or piecemeal:
+ *   app.post("/mcp-relay/register",       relay.register);
+ *   app.post("/mcp-relay/:s/inbox",       relay.inbox);
+ *   app.post("/mcp-relay/:s/outbox",      relay.outbox);
+ *   app.get ("/mcp-relay/:s/events",      relay.events);
+ *   app.post("/mcp-relay/:s/unregister",  relay.unregister);
+ */
+type NodeRelayOptions = RelayBrokerOptions & {
+    /** URL path prefix (without trailing slash). Default `""` — handlers
+     *  expect paths like `/register`, `/{id}/inbox`, etc. directly. */
+    pathPrefix?: string;
+    /** Comma-separated origins (or `*`) for CORS. Default `*` — relays
+     *  are typically called cross-origin from the demo host. */
+    corsAllowOrigin?: string;
+};
+type NodeHandler = (req: IncomingMessage, res: ServerResponse) => unknown | Promise<unknown>;
+type NodeRelay = {
+    broker: RelayBroker;
+    /** Single-handler shape — routes internally based on method + URL. */
+    handler: NodeHandler;
+    /** Per-route handlers. Each handler ignores the URL prefix and
+     *  acts on the path remainder, so you can mount them under any
+     *  prefix in your existing app. */
+    register: NodeHandler;
+    inbox: NodeHandler;
+    outbox: NodeHandler;
+    events: NodeHandler;
+    unregister: NodeHandler;
+};
+declare function createNodeRelay(opts?: NodeRelayOptions): NodeRelay;
+
+export { type Direction, type NodeHandler, type NodeRelay, type NodeRelayOptions, RelayBroker, type RelayBrokerOptions, type Session, type Store, type Subscriber, createNodeRelay };

package/dist/relay-server-cli.cjs

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+'use strict';
+
+var http = require('http');
+var url = require('url');
+var crypto = require('crypto');
+
+var MemoryStore = class {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
+  }
+  putSession(s) {
+    this.sessions.set(s.id, s);
+  }
+  getSession(id) {
+    return this.sessions.get(id);
+  }
+  deleteSession(id) {
+    this.sessions.delete(id);
+  }
+  expiredSessionIds(cutoff) {
+    const out = [];
+    for (const [id, s] of this.sessions) if (s.lastSeen < cutoff) out.push(id);
+    return out;
+  }
+};
+var SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{4,64}$/;
+var RelayBroker = class {
+  constructor(opts = {}) {
+    /** Per-session, per-direction subscriber list. */
+    this.subs = /* @__PURE__ */ new Map();
+    this.ttlMs = opts.ttlMs ?? 4 * 60 * 60 * 1e3;
+    this.store = opts.store ?? new MemoryStore();
+    const tick = opts.reapIntervalMs ?? 6e4;
+    if (tick > 0) {
+      this.reaper = setInterval(() => this.reap(), tick);
+      if (typeof this.reaper.unref === "function") {
+        this.reaper.unref();
+      }
+    }
+  }
+  dispose() {
+    if (this.reaper) clearInterval(this.reaper);
+    this.subs.clear();
+  }
+  /** Register a session id + token. Idempotent — same id+token re-registers,
+   *  different token fails. */
+  register(id, token) {
+    if (!SESSION_ID_PATTERN.test(id)) return { ok: false, reason: "invalid_session_id" };
+    if (typeof token !== "string" || token.length < 16 || token.length > 128) {
+      return { ok: false, reason: "invalid_token" };
+    }
+    const existing = this.store.getSession(id);
+    const hash = sha256Hex(token);
+    if (existing) {
+      if (!timingSafeEqualHex(existing.tokenHash, hash)) return { ok: false, reason: "session_taken" };
+      existing.lastSeen = Date.now();
+      this.store.putSession(existing);
+      return { ok: true };
+    }
+    this.store.putSession({ id, tokenHash: hash, lastSeen: Date.now() });
+    return { ok: true };
+  }
+  unregister(id, token) {
+    if (!this.validate(id, token)) return false;
+    this.store.deleteSession(id);
+    this.subs.delete(id);
+    return true;
+  }
+  /** Validate an authenticated touch and slide the TTL forward. */
+  validate(id, token) {
+    if (!id || !token) return false;
+    const s = this.store.getSession(id);
+    if (!s) return false;
+    if (!timingSafeEqualHex(s.tokenHash, sha256Hex(token))) return false;
+    s.lastSeen = Date.now();
+    this.store.putSession(s);
+    return true;
+  }
+  /** Push a frame onto the inbound queue (external agent → browser). */
+  inbox(id, token, payload) {
+    if (!this.validate(id, token)) return false;
+    if (!this.isFrame(payload)) return false;
+    this.fanOut(id, "inbound", payload);
+    return true;
+  }
+  /** Push a frame onto the outbound queue (browser server → external agents). */
+  outbox(id, token, payload) {
+    if (!this.validate(id, token)) return false;
+    if (!this.isFrame(payload)) return false;
+    this.fanOut(id, "outbound", payload);
+    return true;
+  }
+  /**
+   * Subscribe to a session's queue for one direction. Returns an iterable
+   * the caller (an HTTP handler) pumps as SSE.
+   */
+  subscribe(id, token, direction) {
+    if (!this.validate(id, token)) return { ok: false, reason: "invalid_token" };
+    const subscriberId = crypto.randomBytes(8).toString("hex");
+    const subscriber = { id: subscriberId, direction, queue: [], resolveNext: null };
+    this.getDirSubs(id, direction).set(subscriberId, subscriber);
+    if (direction === "outbound") {
+      this.fanOut(
+        id,
+        "inbound",
+        JSON.stringify({
+          jsonrpc: "2.0",
+          method: "notifications/peer_joined",
+          params: { subscriberId, ts: Date.now() }
+        })
+      );
+    }
+    const unsubscribe = () => {
+      this.getDirSubs(id, direction).delete(subscriberId);
+      if (direction === "outbound") {
+        this.fanOut(
+          id,
+          "inbound",
+          JSON.stringify({
+            jsonrpc: "2.0",
+            method: "notifications/peer_left",
+            params: { subscriberId, ts: Date.now() }
+          })
+        );
+      }
+    };
+    const frames = async function* () {
+      while (true) {
+        if (this.queue.length > 0) {
+          const next2 = this.queue.shift();
+          if (next2 !== void 0) yield next2;
+          continue;
+        }
+        const next = await new Promise((resolve) => {
+          this.resolveNext = resolve;
+        });
+        this.resolveNext = null;
+        if (next === null) return;
+        yield next;
+      }
+    }.bind(subscriber);
+    return {
+      ok: true,
+      subscriberId,
+      frames: frames(),
+      unsubscribe: () => {
+        subscriber.resolveNext?.(null);
+        unsubscribe();
+      }
+    };
+  }
+  // ────────────────────────────────────────────────────────────── internals
+  getDirSubs(sessionId, direction) {
+    let bySession = this.subs.get(sessionId);
+    if (!bySession) {
+      bySession = /* @__PURE__ */ new Map();
+      this.subs.set(sessionId, bySession);
+    }
+    let byDir = bySession.get(direction);
+    if (!byDir) {
+      byDir = /* @__PURE__ */ new Map();
+      bySession.set(direction, byDir);
+    }
+    return byDir;
+  }
+  fanOut(sessionId, direction, payload) {
+    const dir = this.subs.get(sessionId)?.get(direction);
+    if (!dir) return;
+    for (const sub of dir.values()) {
+      sub.queue.push(payload);
+      sub.resolveNext?.(sub.queue.shift() ?? null);
+    }
+  }
+  isFrame(payload) {
+    return payload.length > 0 && payload.includes('"jsonrpc"');
+  }
+  reap() {
+    const cutoff = Date.now() - this.ttlMs;
+    for (const id of this.store.expiredSessionIds(cutoff)) {
+      const dirs = this.subs.get(id);
+      if (dirs) {
+        for (const dir of dirs.values()) {
+          for (const sub of dir.values()) sub.resolveNext?.(null);
+        }
+      }
+      this.subs.delete(id);
+      this.store.deleteSession(id);
+    }
+  }
+};
+function sha256Hex(input) {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+}
+
+// src/relay-server/node.ts
+function createNodeRelay(opts = {}) {
+  const broker = new RelayBroker(opts);
+  const prefix = (opts.pathPrefix ?? "").replace(/\/$/, "");
+  const cors = opts.corsAllowOrigin ?? "*";
+  function setCorsHeaders(res) {
+    res.setHeader("access-control-allow-origin", cors);
+    res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+    res.setHeader("access-control-allow-headers", "content-type, x-csrf-token, accept");
+    res.setHeader("access-control-max-age", "86400");
+  }
+  function readBody(req) {
+    return new Promise((resolve, reject) => {
+      const chunks = [];
+      let bytes = 0;
+      req.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 256 * 1024) {
+          reject(new Error("payload_too_large"));
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      req.on("error", reject);
+    });
+  }
+  function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(body));
+  }
+  function getQuery(req) {
+    const host = req.headers.host || "x";
+    const u = new url.URL(req.url || "/", `http://${host}`);
+    return u.searchParams;
+  }
+  function getPathname(req) {
+    const host = req.headers.host || "x";
+    const u = new url.URL(req.url || "/", `http://${host}`);
+    return u.pathname;
+  }
+  const register = async (req, res) => {
+    setCorsHeaders(res);
+    if (req.method === "OPTIONS") {
+      res.statusCode = 204;
+      return res.end();
+    }
+    if (req.method !== "POST") return json(res, 405, { error: "method_not_allowed" });
+    let body;
+    try {
+      body = await readBody(req);
+    } catch (e) {
+      return json(res, 413, { error: e instanceof Error ? e.message : "payload_error" });
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      return json(res, 400, { error: "invalid_json" });
+    }
+    const { session, token } = parsed ?? {};
+    if (typeof session !== "string" || typeof token !== "string") {
+      return json(res, 400, { error: "missing_fields" });
+    }
+    const result = broker.register(session, token);
+    if (!result.ok) return json(res, 401, { error: result.reason });
+    return json(res, 200, { ok: true });
+  };
+  function makeSessionHandler(direction) {
+    return async (req, res) => {
+      setCorsHeaders(res);
+      if (req.method === "OPTIONS") {
+        res.statusCode = 204;
+        return res.end();
+      }
+      if (req.method !== "POST") return json(res, 405, { error: "method_not_allowed" });
+      const session = extractSession(req, prefix);
+      if (!session) return json(res, 400, { error: "missing_session" });
+      const token = getQuery(req).get("token") ?? "";
+      if (direction === "unregister") {
+        const ok2 = broker.unregister(session, token);
+        return json(res, ok2 ? 200 : 401, ok2 ? { ok: true } : { error: "invalid_token" });
+      }
+      let body;
+      try {
+        body = await readBody(req);
+      } catch (e) {
+        return json(res, 413, { error: e instanceof Error ? e.message : "payload_error" });
+      }
+      const ok = direction === "inbound" ? broker.inbox(session, token, body) : broker.outbox(session, token, body);
+      return json(res, ok ? 200 : 401, ok ? { ok: true } : { error: "invalid_token_or_frame" });
+    };
+  }
+  const inbox = makeSessionHandler("inbound");
+  const outbox = makeSessionHandler("outbound");
+  const unregister = makeSessionHandler("unregister");
+  const events = async (req, res) => {
+    setCorsHeaders(res);
+    if (req.method === "OPTIONS") {
+      res.statusCode = 204;
+      return res.end();
+    }
+    if (req.method !== "GET") return json(res, 405, { error: "method_not_allowed" });
+    const session = extractSession(req, prefix);
+    if (!session) return json(res, 400, { error: "missing_session" });
+    const q = getQuery(req);
+    const token = q.get("token") ?? "";
+    const direction = q.get("direction") === "outbound" ? "outbound" : "inbound";
+    const sub = broker.subscribe(session, token, direction);
+    if (!sub.ok) {
+      res.statusCode = 401;
+      res.setHeader("content-type", "text/event-stream");
+      res.write(`event: error
+data: ${sub.reason}
+
+`);
+      return res.end();
+    }
+    res.statusCode = 200;
+    res.setHeader("content-type", "text/event-stream");
+    res.setHeader("cache-control", "no-cache");
+    res.setHeader("connection", "keep-alive");
+    res.setHeader("x-accel-buffering", "no");
+    res.write("retry: 2000\n\n");
+    flush(res);
+    let heartbeat = setInterval(() => {
+      res.write(": keepalive\n\n");
+      flush(res);
+    }, 15e3);
+    if (heartbeat && typeof heartbeat.unref === "function") {
+      heartbeat.unref();
+    }
+    const cleanup = () => {
+      if (heartbeat) {
+        clearInterval(heartbeat);
+        heartbeat = null;
+      }
+      sub.unsubscribe();
+    };
+    req.on("close", cleanup);
+    req.on("error", cleanup);
+    try {
+      for await (const frame of sub.frames) {
+        res.write(`event: mcp
+data: ${frame}
+
+`);
+        flush(res);
+      }
+    } catch {
+    } finally {
+      cleanup();
+      res.end();
+    }
+  };
+  const handler = async (req, res) => {
+    const pathname = getPathname(req);
+    if (!pathname.startsWith(prefix + "/")) {
+      return json(res, 404, { error: "not_found" });
+    }
+    const rest = pathname.slice(prefix.length);
+    if (rest === "/register") return register(req, res);
+    const m = /^\/([A-Za-z0-9_-]{4,64})\/(inbox|outbox|events|unregister)$/.exec(rest);
+    if (!m) return json(res, 404, { error: "not_found" });
+    const route = m[2];
+    if (route === "inbox") return inbox(req, res);
+    if (route === "outbox") return outbox(req, res);
+    if (route === "events") return events(req, res);
+    if (route === "unregister") return unregister(req, res);
+    return json(res, 404, { error: "not_found" });
+  };
+  return { broker, handler, register, inbox, outbox, events, unregister };
+}
+function extractSession(req, prefix) {
+  const host = req.headers.host || "x";
+  const u = new url.URL(req.url || "/", `http://${host}`);
+  const path = u.pathname;
+  if (prefix && !path.startsWith(prefix + "/")) return null;
+  const rest = prefix ? path.slice(prefix.length) : path;
+  const m = /^\/([A-Za-z0-9_-]{4,64})\//.exec(rest);
+  return m ? m[1] : null;
+}
+function flush(res) {
+  const r = res;
+  r.flush?.();
+}
+
+// src/relay-server/cli.ts
+async function main() {
+  const argv = process.argv.slice(2);
+  let port = Number(process.env.PORT ?? 8787);
+  let host = process.env.HOST ?? "0.0.0.0";
+  let prefix = process.env.PREFIX ?? "";
+  let ttlMs = Number(process.env.TTL_MS ?? 4 * 60 * 60 * 1e3);
+  let cors = process.env.CORS_ALLOW_ORIGIN ?? "*";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--port":
+        port = Number(argv[++i]);
+        break;
+      case "--host":
+        host = argv[++i];
+        break;
+      case "--prefix":
+        prefix = argv[++i];
+        break;
+      case "--ttl-ms":
+        ttlMs = Number(argv[++i]);
+        break;
+      case "--cors":
+        cors = argv[++i];
+        break;
+      case "-h":
+      case "--help":
+        process.stdout.write(HELP);
+        process.exit(0);
+      default:
+        process.stderr.write(`[relay] unknown flag: ${a}
+`);
+        process.exit(2);
+    }
+  }
+  if (!Number.isFinite(port) || port <= 0) {
+    process.stderr.write(`[relay] invalid --port: ${port}
+`);
+    process.exit(2);
+  }
+  const relay = createNodeRelay({ pathPrefix: prefix, ttlMs, corsAllowOrigin: cors });
+  const server = http.createServer((req, res) => {
+    const url = req.url || "/";
+    if ((url === "/" || url === "/healthz" || url === prefix + "/") && req.method === "GET") {
+      res.statusCode = 200;
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify({ ok: true, service: "agent-integrations-relay" }));
+      return;
+    }
+    relay.handler(req, res);
+  });
+  server.listen(port, host, () => {
+    process.stdout.write(
+      `[relay] listening on http://${host}:${port}${prefix || ""} (ttl=${Math.round(ttlMs / 1e3)}s, cors=${cors})
+`
+    );
+  });
+  const shutdown = () => {
+    process.stdout.write("[relay] shutting down\n");
+    relay.broker.dispose();
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 2e3).unref();
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+var HELP = `agent-integrations-relay \u2014 Node HTTP server for the MCP relay broker.
+
+Usage: agent-integrations-relay [options]
+
+Options:
+  --port <n>          Listen port (env: PORT). Default 8787.
+  --host <addr>       Bind address (env: HOST). Default 0.0.0.0.
+  --prefix <path>     URL path prefix (env: PREFIX). Default "".
+  --ttl-ms <n>        Session TTL ms (env: TTL_MS). Default 14_400_000.
+  --cors <origin>     CORS Access-Control-Allow-Origin (env: CORS_ALLOW_ORIGIN). Default "*".
+  -h, --help          Show this help.
+
+Endpoints (under --prefix):
+  POST  /register                          { session, token } \u2192 { ok: true }
+  POST  /<session>/inbox?token=...         body: JSON-RPC frame
+  POST  /<session>/outbox?token=...        body: JSON-RPC frame
+  GET   /<session>/events?token=...&direction=inbound|outbound
+                                           Server-sent events stream
+  POST  /<session>/unregister?token=...    Tear down session
+  GET   /                                  Healthcheck \u2192 200
+`;
+main().catch((e) => {
+  process.stderr.write(`[relay] fatal: ${e instanceof Error ? e.stack ?? e.message : String(e)}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=relay-server-cli.cjs.map
+//# sourceMappingURL=relay-server-cli.cjs.map