@particle-academy/agent-integrations 0.44.0 → 0.46.0

package/dist/relay-server-cli.cjs

@@ -5,6 +5,136 @@ var http = require('http');
 var url = require('url');
 var crypto = require('crypto');
 
+// src/relay-server/cors.ts
+function parseCorsOrigins(value) {
+  const entries = (typeof value === "string" ? value.split(",") : [...value]).map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+  if (entries.length === 0) {
+    throw new Error("CORS origin list is empty: pass `*` or one or more origins, e.g. https://example.com");
+  }
+  if (entries.includes("*")) {
+    if (entries.length === 1) return { kind: "any" };
+    throw new Error(
+      "CORS `*` cannot be combined with named origins \u2014 `*` already allows every origin, so the list would mean nothing. Pass either `*` or the origins."
+    );
+  }
+  const origins = [];
+  for (const entry of entries) {
+    const origin = normalizeOrigin(entry);
+    if (!origins.includes(origin)) origins.push(origin);
+  }
+  return { kind: "list", origins };
+}
+function normalizeOrigin(raw) {
+  if (raw.toLowerCase() === "null") {
+    throw new Error("CORS origin `null` is refused: it is what sandboxed iframes and file:// pages send.");
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`CORS origin "${raw}" is not an origin \u2014 expected scheme://host[:port], e.g. https://example.com`);
+  }
+  if (url.pathname !== "/" && url.pathname !== "" || url.search || url.hash || url.username || url.password) {
+    throw new Error(`CORS origin "${raw}" has a path, query or credentials \u2014 an origin is only scheme://host[:port]`);
+  }
+  if (url.origin !== "null") return url.origin;
+  if (url.host) return `${url.protocol}//${url.host}`;
+  throw new Error(`CORS origin "${raw}" is not an origin \u2014 expected scheme://host[:port], e.g. https://example.com`);
+}
+function allowOriginFor(policy, requestOrigin) {
+  if (policy.kind === "any") return "*";
+  return requestOrigin !== void 0 && policy.origins.includes(requestOrigin) ? requestOrigin : null;
+}
+function describeCorsPolicy(policy) {
+  return policy.kind === "any" ? "*" : policy.origins.join(",");
+}
+
+// src/relay-server/args.ts
+var SETTINGS = {
+  port: { flag: "--port", env: "PORT", fallback: "8787" },
+  // Loopback by default: this relay fronts terminal_run (RCE) and register is
+  // unauthenticated, so it must not listen on all interfaces unless the
+  // operator explicitly opts in with --host 0.0.0.0.
+  host: { flag: "--host", env: "HOST", fallback: "127.0.0.1" },
+  prefix: { flag: "--prefix", env: "PREFIX", fallback: "" },
+  ttlMs: { flag: "--ttl-ms", env: "TTL_MS", fallback: String(4 * 60 * 60 * 1e3) },
+  cors: { flag: "--cors", env: "CORS_ALLOW_ORIGIN", fallback: "*" }
+};
+function parseRelayArgs(argv, env) {
+  const flags = {};
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      help = true;
+      continue;
+    }
+    const key = Object.keys(SETTINGS).find((k) => SETTINGS[k].flag === arg);
+    if (!key) return { ok: false, error: `unknown flag: ${arg}` };
+    const value = argv[i + 1];
+    if (value === void 0 || value.startsWith("--")) return { ok: false, error: `${arg} needs a value` };
+    i++;
+    flags[key] = key === "cors" && flags.cors !== void 0 ? `${flags.cors},${value}` : value;
+  }
+  const warnings = [];
+  const raw = {};
+  const sources = {};
+  for (const key of Object.keys(SETTINGS)) {
+    const { flag, env: envName, fallback } = SETTINGS[key];
+    const fromEnv = env[envName] === "" ? void 0 : env[envName];
+    const fromFlag = flags[key];
+    if (fromFlag !== void 0) {
+      raw[key] = fromFlag;
+      sources[key] = "flag";
+      if (fromEnv !== void 0 && fromEnv !== fromFlag) {
+        warnings.push(`${envName}=${fromEnv} is ignored: ${flag} ${fromFlag} was passed, and a flag wins over its env var.`);
+      }
+    } else if (fromEnv !== void 0) {
+      raw[key] = fromEnv;
+      sources[key] = "env";
+    } else {
+      raw[key] = fallback;
+      sources[key] = "default";
+    }
+  }
+  const named = (key) => sources[key] === "env" ? SETTINGS[key].env : SETTINGS[key].flag;
+  const port = Number(raw.port);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    return { ok: false, error: `invalid ${named("port")}: ${raw.port}` };
+  }
+  const ttlMs = Number(raw.ttlMs);
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    return { ok: false, error: `invalid ${named("ttlMs")}: ${raw.ttlMs}` };
+  }
+  let cors;
+  try {
+    cors = parseCorsOrigins(raw.cors);
+  } catch (e) {
+    return { ok: false, error: `invalid ${named("cors")}: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  if (sources.cors === "flag" && env.CORS_ALLOW_ORIGIN) {
+    try {
+      if (describeCorsPolicy(parseCorsOrigins(env.CORS_ALLOW_ORIGIN)) === describeCorsPolicy(cors)) {
+        const i = warnings.findIndex((w) => w.startsWith("CORS_ALLOW_ORIGIN="));
+        if (i !== -1) warnings.splice(i, 1);
+      }
+    } catch {
+    }
+  }
+  return {
+    ok: true,
+    config: {
+      port,
+      host: raw.host,
+      prefix: raw.prefix,
+      ttlMs,
+      cors,
+      sources,
+      warnings,
+      help
+    }
+  };
+}
 var MemoryStore = class {
   constructor() {
     this.sessions = /* @__PURE__ */ new Map();
@@ -25,6 +155,7 @@ var MemoryStore = class {
   }
 };
 var SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{4,64}$/;
+var SUBSCRIBER_ID_PATTERN = /^[a-f0-9]{16}$/;
 var RelayBroker = class {
   constructor(opts = {}) {
     /** Per-session, per-direction subscriber list. */
@@ -32,6 +163,7 @@ var RelayBroker = class {
     /** Per-session map of JSON-RPC request id -> the client that asked. */
     this.callers = /* @__PURE__ */ new Map();
     this.ttlMs = opts.ttlMs ?? 4 * 60 * 60 * 1e3;
+    this.pollIdleMs = opts.pollIdleMs ?? 6e4;
     this.store = opts.store ?? new MemoryStore();
     const tick = opts.reapIntervalMs ?? 6e4;
     if (tick > 0) {
@@ -43,6 +175,7 @@ var RelayBroker = class {
   }
   dispose() {
     if (this.reaper) clearInterval(this.reaper);
+    for (const id of [...this.subs.keys()]) this.endSubscribers(id);
     this.subs.clear();
     this.callers.clear();
   }
@@ -67,6 +200,7 @@ var RelayBroker = class {
   unregister(id, token) {
     if (!this.validate(id, token)) return false;
     this.store.deleteSession(id);
+    this.endSubscribers(id);
     this.subs.delete(id);
     this.callers.delete(id);
     return true;
@@ -116,6 +250,7 @@ var RelayBroker = class {
   /** Drop a session — the page closed, or a test needs it gone. */
   dropSession(id) {
     this.store.deleteSession(id);
+    this.endSubscribers(id);
     this.subs.delete(id);
     this.callers.delete(id);
   }
@@ -146,7 +281,8 @@ var RelayBroker = class {
    * the caller (an HTTP handler) pumps as SSE.
    */
   subscribe(id, token, direction, opts = {}) {
-    if (!this.validate(id, token)) return { ok: false, reason: "invalid_token" };
+    const auth = this.check(id, token);
+    if (!auth.ok) return auth;
     const subscriberId = crypto.randomBytes(8).toString("hex");
     const subscriber = {
       id: subscriberId,
@@ -156,31 +292,7 @@ var RelayBroker = class {
       client: opts.client
     };
     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() }
-          })
-        );
-      }
-    };
+    if (direction === "outbound") this.announcePeer(id, "notifications/peer_joined", subscriberId);
     const frames = async function* () {
       while (true) {
         if (this.queue.length > 0) {
@@ -188,6 +300,7 @@ var RelayBroker = class {
           if (next2 !== void 0) yield next2;
           continue;
         }
+        if (this.ended) return;
         const next = await new Promise((resolve) => {
           this.resolveNext = resolve;
         });
@@ -201,8 +314,88 @@ var RelayBroker = class {
       subscriberId,
       frames: frames(),
       unsubscribe: () => {
-        subscriber.resolveNext?.(null);
-        unsubscribe();
+        this.endSubscriber(subscriber);
+        this.removeSubscriber(id, subscriber);
+      }
+    };
+  }
+  /**
+   * Attach a LONG-POLL subscriber, or re-attach the one a previous poll created.
+   *
+   * The CDN-safe receive leg: a series of short requests instead of one open
+   * stream, because Cloudflare's HTTP/3 edge resets long-lived SSE. Same
+   * contract as the PHP relay in px-ui-sandbox and the one
+   * `@particle-academy/fancy-cf-relay` and `mcp-relay-client` speak:
+   *
+   * - The first poll gets a fresh 16-hex subscriber id; the client echoes it back
+   *   as `subscriber` on every later poll and reads the same queue.
+   * - An id in that shape that this session does not know (pruned, say) is
+   *   adopted as a NEW subscriber under that id, as the PHP relay does, so a
+   *   client that went quiet and came back keeps its identity.
+   * - An id belonging to a STREAMING subscriber is never adopted: one queue read
+   *   by two consumers splits its frames between them.
+   *
+   * Frames queue on the subscriber between polls, so nothing is lost in the gap
+   * between one request ending and the next arriving. A poller that stops is
+   * pruned after `pollIdleMs`.
+   */
+  poll(id, token, direction, opts = {}) {
+    const auth = this.check(id, token);
+    if (!auth.ok) return auth;
+    const dir = this.getDirSubs(id, direction);
+    const requested = opts.subscriber && SUBSCRIBER_ID_PATTERN.test(opts.subscriber) ? opts.subscriber : void 0;
+    const existing = requested ? dir.get(requested) : void 0;
+    let subscriber;
+    let created;
+    if (existing?.poll) {
+      subscriber = existing;
+      created = false;
+    } else {
+      const subscriberId = requested && !existing ? requested : crypto.randomBytes(8).toString("hex");
+      subscriber = {
+        id: subscriberId,
+        direction,
+        queue: [],
+        resolveNext: null,
+        client: opts.client,
+        poll: { lastSeen: Date.now(), parked: 0, wakers: /* @__PURE__ */ new Set() }
+      };
+      dir.set(subscriberId, subscriber);
+      created = true;
+      if (direction === "outbound") this.announcePeer(id, "notifications/peer_joined", subscriberId);
+    }
+    const state = subscriber.poll;
+    state.lastSeen = Date.now();
+    return {
+      ok: true,
+      subscriberId: subscriber.id,
+      created,
+      wait: async (ms, signal) => {
+        state.parked++;
+        state.lastSeen = Date.now();
+        try {
+          if (subscriber.queue.length === 0 && ms > 0 && !subscriber.ended && !signal?.aborted) {
+            await new Promise((resolve) => {
+              const done = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", done);
+                state.wakers.delete(done);
+                resolve();
+              };
+              const timer = setTimeout(done, ms);
+              state.wakers.add(done);
+              signal?.addEventListener("abort", done, { once: true });
+            });
+          }
+          if (signal?.aborted) return [];
+          return subscriber.queue.splice(0);
+        } finally {
+          state.parked--;
+          state.lastSeen = Date.now();
+        }
+      },
+      requeue: (frames) => {
+        if (frames.length > 0 && !subscriber.ended) subscriber.queue.unshift(...frames);
       }
     };
   }
@@ -295,16 +488,78 @@ var RelayBroker = class {
     if (!dir) return;
     for (const sub of dir.values()) {
       if (sub.client !== client) continue;
-      sub.queue.push(payload);
-      sub.resolveNext?.(sub.queue.shift() ?? null);
+      this.deliver(sub, payload);
     }
   }
   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);
+    for (const sub of dir.values()) this.deliver(sub, payload);
+  }
+  /**
+   * Hand one frame to one subscriber.
+   *
+   * The resolver is CLEARED before it is called. It used to stay set until the
+   * generator resumed on a later microtask, so a second frame in the same tick
+   * called an already-settled resolver — a no-op — after shifting its frame out
+   * of the queue, and that frame was lost. Cleared first, the second frame just
+   * waits in the queue for the generator to come back for it.
+   */
+  deliver(sub, payload) {
+    if (sub.ended) return;
+    sub.queue.push(payload);
+    const resolve = sub.resolveNext;
+    if (resolve) {
+      sub.resolveNext = null;
+      resolve(sub.queue.shift() ?? null);
+      return;
+    }
+    if (sub.poll) for (const wake of [...sub.poll.wakers]) wake();
+  }
+  /** Tell the page (the inbound side) that an agent arrived or left. */
+  announcePeer(sessionId, method, subscriberId) {
+    this.fanOut(sessionId, "inbound", JSON.stringify({ jsonrpc: "2.0", method, params: { subscriberId, ts: Date.now() } }));
+  }
+  /** End one subscriber: close its stream, or release its parked polls. Idempotent. */
+  endSubscriber(sub) {
+    if (sub.ended) return;
+    sub.ended = true;
+    const resolve = sub.resolveNext;
+    sub.resolveNext = null;
+    resolve?.(null);
+    if (sub.poll) for (const wake of [...sub.poll.wakers]) wake();
+  }
+  /**
+   * End every subscriber of a session whose session is going away.
+   *
+   * Streams used to be dropped from the map WITHOUT being woken, so an SSE leg
+   * stayed open, heartbeating, for a session that no longer existed — and its
+   * client could not learn the page had closed. Ended, the stream closes, the
+   * client reconnects, and `events` answers 410.
+   */
+  endSubscribers(sessionId) {
+    const dirs = this.subs.get(sessionId);
+    if (!dirs) return;
+    for (const dir of dirs.values()) for (const sub of dir.values()) this.endSubscriber(sub);
+  }
+  /** Remove a subscriber from its session, announcing an agent's departure once. */
+  removeSubscriber(sessionId, sub) {
+    const dir = this.subs.get(sessionId)?.get(sub.direction);
+    if (!dir || dir.get(sub.id) !== sub) return;
+    dir.delete(sub.id);
+    if (sub.direction === "outbound") this.announcePeer(sessionId, "notifications/peer_left", sub.id);
+  }
+  /** Drop long-poll subscribers that stopped polling. Never one with a poll parked. */
+  prunePollers(now) {
+    for (const [sessionId, dirs] of this.subs) {
+      for (const dir of dirs.values()) {
+        for (const sub of [...dir.values()]) {
+          if (!sub.poll || sub.poll.parked > 0) continue;
+          if (now - sub.poll.lastSeen <= this.pollIdleMs) continue;
+          this.endSubscriber(sub);
+          this.removeSubscriber(sessionId, sub);
+        }
+      }
     }
   }
   /**
@@ -340,18 +595,15 @@ var RelayBroker = class {
     return "id" in o && hasResult !== hasError;
   }
   reap() {
-    const cutoff = Date.now() - this.ttlMs;
+    const now = Date.now();
+    const cutoff = 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.endSubscribers(id);
       this.subs.delete(id);
       this.callers.delete(id);
       this.store.deleteSession(id);
     }
+    this.prunePollers(now);
   }
 };
 function sha256Hex(input) {
@@ -363,19 +615,25 @@ function timingSafeEqualHex(a, b) {
 }
 
 // src/relay-server/node.ts
+var POLL_MAX_WAIT_MS = 25e3;
+var POLL_DEFAULT_WAIT_MS = 2e4;
+function pollWaitMs(raw) {
+  if (raw === null || raw === void 0) return POLL_DEFAULT_WAIT_MS;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) return 0;
+  return Math.min(Math.max(n, 0), POLL_MAX_WAIT_MS);
+}
 function createNodeRelay(opts = {}) {
   const broker = new RelayBroker(opts);
   const prefix = (opts.pathPrefix ?? "").replace(/\/$/, "");
-  const cors = opts.corsAllowOrigin ?? "*";
-  const allowedOrigins = opts.allowedOrigins;
+  const cors = opts.allowedOrigins && opts.allowedOrigins.length > 0 ? parseCorsOrigins(opts.allowedOrigins) : parseCorsOrigins(opts.corsAllowOrigin ?? "*");
   function setCorsHeaders(res, req) {
-    if (allowedOrigins && allowedOrigins.length) {
-      const origin = req?.headers.origin;
-      res.setHeader("access-control-allow-origin", origin && allowedOrigins.includes(origin) ? origin : "null");
-      res.setHeader("vary", "origin");
-    } else {
-      res.setHeader("access-control-allow-origin", cors);
+    if (cors.kind === "list") {
+      res.setHeader("vary", "Origin");
     }
+    const origin = req?.headers.origin;
+    const allow = allowOriginFor(cors, typeof origin === "string" ? origin : void 0);
+    if (allow !== null) res.setHeader("access-control-allow-origin", allow);
     res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
     res.setHeader("access-control-allow-headers", "content-type, x-csrf-token, accept, authorization");
     res.setHeader("access-control-max-age", "86400");
@@ -492,7 +750,7 @@ function createNodeRelay(opts = {}) {
       client: getQuery(req).get("client") ?? void 0
     });
     if (!sub.ok) {
-      res.statusCode = 401;
+      res.statusCode = sub.reason === "session_gone" ? 410 : 401;
       res.setHeader("content-type", "text/event-stream");
       res.write(`event: error
 data: ${sub.reason}
@@ -537,6 +795,38 @@ data: ${frame}
       res.end();
     }
   };
+  const poll = async (req, res) => {
+    setCorsHeaders(res, req);
+    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 direction = q.get("direction") === "outbound" ? "outbound" : "inbound";
+    const attached = broker.poll(session, q.get("token") ?? "", direction, {
+      subscriber: q.get("subscriber") ?? void 0,
+      client: q.get("client") ?? void 0
+    });
+    if (!attached.ok) {
+      return json(res, attached.reason === "session_gone" ? 410 : 401, { error: attached.reason });
+    }
+    const gone = new AbortController();
+    const onClose = () => {
+      if (!res.writableEnded) gone.abort();
+    };
+    res.on("close", onClose);
+    const frames = await attached.wait(pollWaitMs(q.get("wait")), gone.signal);
+    res.off("close", onClose);
+    if (gone.signal.aborted || res.destroyed) {
+      attached.requeue(frames);
+      return;
+    }
+    res.setHeader("cache-control", "no-store");
+    return json(res, 200, { subscriber: attached.subscriberId, frames });
+  };
   const handler = async (req, res) => {
     const pathname = getPathname(req);
     if (!pathname.startsWith(prefix + "/")) {
@@ -544,16 +834,17 @@ data: ${frame}
     }
     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);
+    const m = /^\/([A-Za-z0-9_-]{4,64})\/(inbox|outbox|events|poll|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 === "poll") return poll(req, res);
     if (route === "unregister") return unregister(req, res);
     return json(res, 404, { error: "not_found" });
   };
-  return { broker, handler, register, inbox, outbox, events, unregister };
+  return { broker, handler, register, inbox, outbox, events, poll, unregister };
 }
 function extractSession(req, prefix) {
   const host = req.headers.host || "x";
@@ -571,46 +862,27 @@ function flush(res) {
 
 // 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 ?? "127.0.0.1";
-  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}
+  const parsed = parseRelayArgs(process.argv.slice(2), process.env);
+  if (!parsed.ok) {
+    process.stderr.write(`[relay] ${parsed.error}
 `);
-        process.exit(2);
-    }
+    process.exit(2);
   }
-  if (!Number.isFinite(port) || port <= 0) {
-    process.stderr.write(`[relay] invalid --port: ${port}
+  const { config } = parsed;
+  if (config.help) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+  for (const warning of config.warnings) {
+    process.stderr.write(`[relay] WARNING: ${warning}
 `);
-    process.exit(2);
   }
-  const relay = createNodeRelay({ pathPrefix: prefix, ttlMs, corsAllowOrigin: cors });
+  const { port, host, prefix, ttlMs, cors } = config;
+  const relay = createNodeRelay({
+    pathPrefix: prefix,
+    ttlMs,
+    corsAllowOrigin: cors.kind === "any" ? "*" : cors.origins.join(",")
+  });
   const server = http.createServer((req, res) => {
     const url = req.url || "/";
     if ((url === "/" || url === "/healthz" || url === prefix + "/") && req.method === "GET") {
@@ -628,9 +900,10 @@ async function main() {
 `
     );
   }
+  const corsSource = { flag: "--cors", env: "CORS_ALLOW_ORIGIN", default: "default" }[config.sources.cors];
   server.listen(port, host, () => {
     process.stdout.write(
-      `[relay] listening on http://${host}:${port}${prefix || ""} (ttl=${Math.round(ttlMs / 1e3)}s, cors=${cors})
+      `[relay] listening on http://${host}:${port}${prefix || ""} (ttl=${Math.round(ttlMs / 1e3)}s, cors=${describeCorsPolicy(cors)} from ${corsSource})
 `
     );
   });
@@ -653,17 +926,29 @@ Options:
                       Pass 0.0.0.0 to expose on all interfaces (prints a warning).
   --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 "*".
+  --cors <origins>    Allowed browser origins (env: CORS_ALLOW_ORIGIN). Default "*".
+                      "*", or a comma-separated list such as
+                      "https://example.com,https://www.example.com". May be
+                      repeated. A listed Origin is echoed back with Vary: Origin;
+                      an unlisted one gets no Access-Control-Allow-Origin.
   -h, --help          Show this help.
 
+Precedence: a flag wins over its env var, which wins over the default. An env
+var that a flag overrides is reported at startup. An empty env var is unset.
+
 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
+  GET   /<session>/poll?token=...&direction=inbound|outbound&wait=<ms>&subscriber=<id>
+                                           Long-poll \u2192 { subscriber, frames }
   POST  /<session>/unregister?token=...    Tear down session
   GET   /                                  Healthcheck \u2192 200
+
+A session that has ended answers 410 {"error":"session_gone"} on every session
+route; a wrong or missing token answers 401.
 `;
 main().catch((e) => {
   process.stderr.write(`[relay] fatal: ${e instanceof Error ? e.stack ?? e.message : String(e)}