@particle-academy/agent-integrations 0.45.0 → 0.47.0

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

@@ -40,12 +40,34 @@ type Subscriber = {
      * of everyone else's tool calls without making one.
      */
     client?: string;
+    /**
+     * Present only for a LONG-POLL subscriber, which outlives any one request:
+     * it is read by a series of `GET /poll` calls rather than one open stream,
+     * so it needs its own liveness record.
+     */
+    poll?: {
+        /** Last time a poll started or finished (ms since epoch). */
+        lastSeen: number;
+        /** Polls currently parked on this subscriber. Never pruned while > 0. */
+        parked: number;
+        /** Wake every parked poll — a frame landed, or the session ended. */
+        wakers: Set<() => void>;
+    };
+    /** Set once the subscriber has been ended (unsubscribed, pruned, or its session is gone). */
+    ended?: boolean;
 };
 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;
+    /**
+     * A long-poll subscriber that has not polled for this long is dropped (and,
+     * for an outbound one, the page is told the peer left). Checked on the reap
+     * tick. Default 60 000 — the PHP relay's window, and comfortably longer than
+     * the 25 s maximum park, so a healthy poller is never pruned between polls.
+     */
+    pollIdleMs?: number;
     /** Bring-your-own storage layer (redis, etc.). Defaults to in-memory. */
     store?: Store;
 };
@@ -58,6 +80,7 @@ interface Store {
 }
 declare class RelayBroker {
     private readonly ttlMs;
+    private readonly pollIdleMs;
     private readonly store;
     /** Per-session, per-direction subscriber list. */
     private subs;
@@ -125,6 +148,30 @@ declare class RelayBroker {
     subscribe(id: string, token: string, direction: Direction, opts?: {
         client?: string;
     }): SubscribeResult;
+    /**
+     * 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: string, token: string, direction: Direction, opts?: {
+        subscriber?: string;
+        client?: string;
+    }): PollResult;
     private getDirSubs;
     /**
      * Record which client asked, keyed by JSON-RPC id.
@@ -154,6 +201,33 @@ declare class RelayBroker {
     /** Deliver to the subscribers of one client only. */
     private fanOutTo;
     private fanOut;
+    /**
+     * 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.
+     */
+    private deliver;
+    /** Tell the page (the inbound side) that an agent arrived or left. */
+    private announcePeer;
+    /** End one subscriber: close its stream, or release its parked polls. Idempotent. */
+    private endSubscriber;
+    /**
+     * 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.
+     */
+    private endSubscribers;
+    /** Remove a subscriber from its session, announcing an agent's departure once. */
+    private removeSubscriber;
+    /** Drop long-poll subscribers that stopped polling. Never one with a poll parked. */
+    private prunePollers;
     /**
      * Validate that a peer-supplied payload is a well-formed JSON-RPC 2.0 frame
      * (or batch) before it is fanned out. Previously this was a substring match on
@@ -168,6 +242,24 @@ declare class RelayBroker {
     private isValidFrame;
     private reap;
 }
+type PollResult = {
+    ok: false;
+    reason: "invalid_token" | "session_gone";
+} | {
+    ok: true;
+    /** The id the client must echo back as `subscriber` on its next poll. */
+    subscriberId: string;
+    /** Whether this poll created the subscriber (and, outbound, announced it). */
+    created: boolean;
+    /**
+     * Park up to `ms` for frames, then take everything queued. Returns at once
+     * when frames are already waiting, when `ms` is 0, or when the session
+     * ends. An aborted `signal` returns `[]` and takes nothing.
+     */
+    wait: (ms: number, signal?: AbortSignal) => Promise<string[]>;
+    /** Put frames back at the head of the queue — a response that could not be written. */
+    requeue: (frames: string[]) => void;
+};
 type SubscribeResult = {
     ok: false;
     reason: string;
@@ -178,37 +270,27 @@ type SubscribeResult = {
     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. */
+    /**
+     * Browser origins allowed to read relay responses: `*`, or a comma-separated
+     * list of origins (`"https://example.com,https://www.example.com"`).
+     * Default `*` — relays are typically called cross-origin from the demo host.
+     *
+     * A list is enforced per request: a listed `Origin` is echoed back as
+     * `Access-Control-Allow-Origin` with `Vary: Origin`, and an unlisted one
+     * gets no allow-origin header at all. `*` mixed into a list, an empty value,
+     * `null` or an entry with a path throws here, at construction.
+     */
     corsAllowOrigin?: string;
     /**
-     * Strict browser-origin allow-list. When set, only these Origins get a
-     * matching `Access-Control-Allow-Origin` (the request's own Origin is
-     * reflected, never `*`), which blunts DNS-rebinding + hostile cross-origin
-     * pages from reading relay responses. Recommended for any browser-facing
-     * deployment. When unset, `corsAllowOrigin` (default `*`) is used and the
-     * session token is the only auth — pair that with a loopback bind.
+     * The same allow-list as an array. When non-empty it takes precedence over
+     * `corsAllowOrigin`. Recommended for any browser-facing deployment: it blunts
+     * DNS rebinding and hostile cross-origin pages reading relay responses. When
+     * neither names origins, `*` is used and the session token is the only auth
+     * — pair that with a loopback bind.
      */
     allowedOrigins?: string[];
 };
@@ -224,8 +306,10 @@ type NodeRelay = {
     inbox: NodeHandler;
     outbox: NodeHandler;
     events: NodeHandler;
+    /** Long-poll receive leg — the CDN-safe alternative to `events`. */
+    poll: 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 };
+export { type Direction, type NodeHandler, type NodeRelay, type NodeRelayOptions, type PollResult, RelayBroker, type RelayBrokerOptions, type Session, type Store, type SubscribeResult, type Subscriber, createNodeRelay };

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

@@ -40,12 +40,34 @@ type Subscriber = {
      * of everyone else's tool calls without making one.
      */
     client?: string;
+    /**
+     * Present only for a LONG-POLL subscriber, which outlives any one request:
+     * it is read by a series of `GET /poll` calls rather than one open stream,
+     * so it needs its own liveness record.
+     */
+    poll?: {
+        /** Last time a poll started or finished (ms since epoch). */
+        lastSeen: number;
+        /** Polls currently parked on this subscriber. Never pruned while > 0. */
+        parked: number;
+        /** Wake every parked poll — a frame landed, or the session ended. */
+        wakers: Set<() => void>;
+    };
+    /** Set once the subscriber has been ended (unsubscribed, pruned, or its session is gone). */
+    ended?: boolean;
 };
 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;
+    /**
+     * A long-poll subscriber that has not polled for this long is dropped (and,
+     * for an outbound one, the page is told the peer left). Checked on the reap
+     * tick. Default 60 000 — the PHP relay's window, and comfortably longer than
+     * the 25 s maximum park, so a healthy poller is never pruned between polls.
+     */
+    pollIdleMs?: number;
     /** Bring-your-own storage layer (redis, etc.). Defaults to in-memory. */
     store?: Store;
 };
@@ -58,6 +80,7 @@ interface Store {
 }
 declare class RelayBroker {
     private readonly ttlMs;
+    private readonly pollIdleMs;
     private readonly store;
     /** Per-session, per-direction subscriber list. */
     private subs;
@@ -125,6 +148,30 @@ declare class RelayBroker {
     subscribe(id: string, token: string, direction: Direction, opts?: {
         client?: string;
     }): SubscribeResult;
+    /**
+     * 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: string, token: string, direction: Direction, opts?: {
+        subscriber?: string;
+        client?: string;
+    }): PollResult;
     private getDirSubs;
     /**
      * Record which client asked, keyed by JSON-RPC id.
@@ -154,6 +201,33 @@ declare class RelayBroker {
     /** Deliver to the subscribers of one client only. */
     private fanOutTo;
     private fanOut;
+    /**
+     * 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.
+     */
+    private deliver;
+    /** Tell the page (the inbound side) that an agent arrived or left. */
+    private announcePeer;
+    /** End one subscriber: close its stream, or release its parked polls. Idempotent. */
+    private endSubscriber;
+    /**
+     * 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.
+     */
+    private endSubscribers;
+    /** Remove a subscriber from its session, announcing an agent's departure once. */
+    private removeSubscriber;
+    /** Drop long-poll subscribers that stopped polling. Never one with a poll parked. */
+    private prunePollers;
     /**
      * Validate that a peer-supplied payload is a well-formed JSON-RPC 2.0 frame
      * (or batch) before it is fanned out. Previously this was a substring match on
@@ -168,6 +242,24 @@ declare class RelayBroker {
     private isValidFrame;
     private reap;
 }
+type PollResult = {
+    ok: false;
+    reason: "invalid_token" | "session_gone";
+} | {
+    ok: true;
+    /** The id the client must echo back as `subscriber` on its next poll. */
+    subscriberId: string;
+    /** Whether this poll created the subscriber (and, outbound, announced it). */
+    created: boolean;
+    /**
+     * Park up to `ms` for frames, then take everything queued. Returns at once
+     * when frames are already waiting, when `ms` is 0, or when the session
+     * ends. An aborted `signal` returns `[]` and takes nothing.
+     */
+    wait: (ms: number, signal?: AbortSignal) => Promise<string[]>;
+    /** Put frames back at the head of the queue — a response that could not be written. */
+    requeue: (frames: string[]) => void;
+};
 type SubscribeResult = {
     ok: false;
     reason: string;
@@ -178,37 +270,27 @@ type SubscribeResult = {
     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. */
+    /**
+     * Browser origins allowed to read relay responses: `*`, or a comma-separated
+     * list of origins (`"https://example.com,https://www.example.com"`).
+     * Default `*` — relays are typically called cross-origin from the demo host.
+     *
+     * A list is enforced per request: a listed `Origin` is echoed back as
+     * `Access-Control-Allow-Origin` with `Vary: Origin`, and an unlisted one
+     * gets no allow-origin header at all. `*` mixed into a list, an empty value,
+     * `null` or an entry with a path throws here, at construction.
+     */
     corsAllowOrigin?: string;
     /**
-     * Strict browser-origin allow-list. When set, only these Origins get a
-     * matching `Access-Control-Allow-Origin` (the request's own Origin is
-     * reflected, never `*`), which blunts DNS-rebinding + hostile cross-origin
-     * pages from reading relay responses. Recommended for any browser-facing
-     * deployment. When unset, `corsAllowOrigin` (default `*`) is used and the
-     * session token is the only auth — pair that with a loopback bind.
+     * The same allow-list as an array. When non-empty it takes precedence over
+     * `corsAllowOrigin`. Recommended for any browser-facing deployment: it blunts
+     * DNS rebinding and hostile cross-origin pages reading relay responses. When
+     * neither names origins, `*` is used and the session token is the only auth
+     * — pair that with a loopback bind.
      */
     allowedOrigins?: string[];
 };
@@ -224,8 +306,10 @@ type NodeRelay = {
     inbox: NodeHandler;
     outbox: NodeHandler;
     events: NodeHandler;
+    /** Long-poll receive leg — the CDN-safe alternative to `events`. */
+    poll: 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 };
+export { type Direction, type NodeHandler, type NodeRelay, type NodeRelayOptions, type PollResult, RelayBroker, type RelayBrokerOptions, type Session, type Store, type SubscribeResult, type Subscriber, createNodeRelay };