@particle-academy/agent-integrations 0.45.0 → 0.46.0

package/README.md

@@ -323,9 +323,16 @@ to you:
   `confirm` argument that would apply it (revoking the last passkey is a lockout).
   `passkey_list` re-projects onto the public summary fields, so handing it your
   ORM model cannot leak a public key, a user handle, or a signature counter.
-- **The relay fans tool results + activity to all peers.** The terminal bridge
-  redacts raw command bytes from broadcast meta, but any `structuredContent` you
-  return is visible to every connected peer — don't return secrets.
+- **Activity reaches every peer; tool results reach the caller only if clients
+  label themselves.** Since 0.44.0 a reply goes only to the client that asked
+  when clients send a `client` query parameter; unlabelled clients still get
+  every frame. Notifications are always broadcast. The terminal bridge redacts
+  raw command bytes from broadcast meta, but treat anything you return as
+  visible to every holder of the token — don't return secrets.
+- **The relay serves SSE and long-poll.** Behind Cloudflare (whose HTTP/3 edge
+  resets long SSE streams) install `@particle-academy/fancy-cf-relay` so the
+  browser polls; see `docs/relay-server.md`. Pass `--cors` a list of your
+  sites' origins rather than leaving `*` on a public relay.
 
 ## Status
 

package/dist/{chunk-OZBUPO4K.js → chunk-5W34X4EY.js}

@@ -1,5 +1,5 @@
 import { randomBytes, createHash, timingSafeEqual } from 'crypto';
-import { URL } from 'url';
+import { URL as URL$1 } from 'url';
 
 // src/relay-server/core.ts
 var MemoryStore = class {
@@ -22,6 +22,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. */
@@ -29,6 +30,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) {
@@ -40,6 +42,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();
   }
@@ -64,6 +67,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;
@@ -113,6 +117,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);
   }
@@ -143,7 +148,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 = randomBytes(8).toString("hex");
     const subscriber = {
       id: subscriberId,
@@ -153,31 +159,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) {
@@ -185,6 +167,7 @@ var RelayBroker = class {
           if (next2 !== void 0) yield next2;
           continue;
         }
+        if (this.ended) return;
         const next = await new Promise((resolve) => {
           this.resolveNext = resolve;
         });
@@ -198,8 +181,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 : 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);
       }
     };
   }
@@ -292,16 +355,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);
+        }
+      }
     }
   }
   /**
@@ -337,18 +462,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) {
@@ -358,19 +480,69 @@ function timingSafeEqualHex(a, b) {
   if (a.length !== b.length) return false;
   return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
 }
+
+// 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(",");
+}
+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");
@@ -399,12 +571,12 @@ function createNodeRelay(opts = {}) {
   }
   function getQuery(req) {
     const host = req.headers.host || "x";
-    const u = new URL(req.url || "/", `http://${host}`);
+    const u = new URL$1(req.url || "/", `http://${host}`);
     return u.searchParams;
   }
   function getPathname(req) {
     const host = req.headers.host || "x";
-    const u = new URL(req.url || "/", `http://${host}`);
+    const u = new URL$1(req.url || "/", `http://${host}`);
     return u.pathname;
   }
   const register = async (req, res) => {
@@ -487,7 +659,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}
@@ -532,6 +704,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 + "/")) {
@@ -539,20 +743,21 @@ 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";
-  const u = new URL(req.url || "/", `http://${host}`);
+  const u = new URL$1(req.url || "/", `http://${host}`);
   const path = u.pathname;
   if (prefix && !path.startsWith(prefix + "/")) return null;
   const rest = prefix ? path.slice(prefix.length) : path;
@@ -564,6 +769,6 @@ function flush(res) {
   r.flush?.();
 }
 
-export { RelayBroker, createNodeRelay };
-//# sourceMappingURL=chunk-OZBUPO4K.js.map
-//# sourceMappingURL=chunk-OZBUPO4K.js.map
+export { RelayBroker, createNodeRelay, describeCorsPolicy, parseCorsOrigins };
+//# sourceMappingURL=chunk-5W34X4EY.js.map
+//# sourceMappingURL=chunk-5W34X4EY.js.map