@llui/agent 0.0.30 → 0.0.31

package/dist/server/web/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Web-runtime adapters. Use this sub-path from Cloudflare Workers,
+ * Deno, Bun, or any other runtime that speaks WHATWG `Request` /
+ * `Response` and exposes native WebSocket upgrade primitives.
+ *
+ * Pair with `@llui/agent/server/core`'s `createLluiAgentCore` — that
+ * builds the runtime-neutral router and registry; the handlers
+ * exported here handle the WebSocket upgrade half.
+ */
+export { createWHATWGPairingConnection } from './adapter.js';
+export { handleCloudflareUpgrade, handleDenoUpgrade, extractToken } from './upgrade.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/web/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA"}

package/dist/server/web/index.js

@@ -0,0 +1,12 @@
+/**
+ * Web-runtime adapters. Use this sub-path from Cloudflare Workers,
+ * Deno, Bun, or any other runtime that speaks WHATWG `Request` /
+ * `Response` and exposes native WebSocket upgrade primitives.
+ *
+ * Pair with `@llui/agent/server/core`'s `createLluiAgentCore` — that
+ * builds the runtime-neutral router and registry; the handlers
+ * exported here handle the WebSocket upgrade half.
+ */
+export { createWHATWGPairingConnection } from './adapter.js';
+export { handleCloudflareUpgrade, handleDenoUpgrade, extractToken } from './upgrade.js';
+//# sourceMappingURL=index.js.map

package/dist/server/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/web/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA","sourcesContent":["/**\n * Web-runtime adapters. Use this sub-path from Cloudflare Workers,\n * Deno, Bun, or any other runtime that speaks WHATWG `Request` /\n * `Response` and exposes native WebSocket upgrade primitives.\n *\n * Pair with `@llui/agent/server/core`'s `createLluiAgentCore` — that\n * builds the runtime-neutral router and registry; the handlers\n * exported here handle the WebSocket upgrade half.\n */\nexport { createWHATWGPairingConnection } from './adapter.js'\nexport { handleCloudflareUpgrade, handleDenoUpgrade, extractToken } from './upgrade.js'\n"]}

package/dist/server/web/upgrade.d.ts

@@ -0,0 +1,41 @@
+import type { AgentCoreHandle } from '../core.js';
+/**
+ * Extract the bearer token from a LAP WebSocket upgrade request.
+ * Accepts the token on either `?token=` or `Authorization: Bearer` —
+ * query-string is the common pattern because browsers can't set
+ * arbitrary headers on WebSocket construction.
+ */
+export declare function extractToken(req: Request): string | null;
+/**
+ * Cloudflare Workers handler. Accepts a WebSocket upgrade using
+ * `WebSocketPair`, validates the token via
+ * `agent.acceptConnection`, and returns the 101 upgrade Response.
+ *
+ * Usage:
+ * ```ts
+ * const agent = createLluiAgentCore({ signingKey: env.AGENT_KEY })
+ * export default {
+ *   async fetch(req, env) {
+ *     const url = new URL(req.url)
+ *     if (url.pathname === '/agent/ws') return handleCloudflareUpgrade(req, agent)
+ *     return (await agent.router(req)) ?? new Response('Not Found', { status: 404 })
+ *   },
+ * }
+ * ```
+ */
+export declare function handleCloudflareUpgrade(req: Request, agent: AgentCoreHandle): Promise<Response>;
+/**
+ * Deno handler. Uses `Deno.upgradeWebSocket(req)` to produce the
+ * response + socket pair, then plugs the socket into the registry.
+ *
+ * Usage:
+ * ```ts
+ * Deno.serve(async (req) => {
+ *   const url = new URL(req.url)
+ *   if (url.pathname === '/agent/ws') return handleDenoUpgrade(req, agent)
+ *   return (await agent.router(req)) ?? new Response('Not Found', { status: 404 })
+ * })
+ * ```
+ */
+export declare function handleDenoUpgrade(req: Request, agent: AgentCoreHandle): Promise<Response>;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/server/web/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../../src/server/web/upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOxD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,QAAQ,CAAC,CAmCnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CA+B/F"}

package/dist/server/web/upgrade.js

@@ -0,0 +1,96 @@
+import { createWHATWGPairingConnection } from './adapter.js';
+/**
+ * Extract the bearer token from a LAP WebSocket upgrade request.
+ * Accepts the token on either `?token=` or `Authorization: Bearer` —
+ * query-string is the common pattern because browsers can't set
+ * arbitrary headers on WebSocket construction.
+ */
+export function extractToken(req) {
+    const url = new URL(req.url);
+    const q = url.searchParams.get('token');
+    if (q)
+        return q;
+    const auth = req.headers.get('authorization');
+    if (auth?.startsWith('Bearer '))
+        return auth.slice('Bearer '.length);
+    return null;
+}
+/**
+ * Cloudflare Workers handler. Accepts a WebSocket upgrade using
+ * `WebSocketPair`, validates the token via
+ * `agent.acceptConnection`, and returns the 101 upgrade Response.
+ *
+ * Usage:
+ * ```ts
+ * const agent = createLluiAgentCore({ signingKey: env.AGENT_KEY })
+ * export default {
+ *   async fetch(req, env) {
+ *     const url = new URL(req.url)
+ *     if (url.pathname === '/agent/ws') return handleCloudflareUpgrade(req, agent)
+ *     return (await agent.router(req)) ?? new Response('Not Found', { status: 404 })
+ *   },
+ * }
+ * ```
+ */
+export async function handleCloudflareUpgrade(req, agent) {
+    if (req.headers.get('upgrade') !== 'websocket') {
+        return new Response('Expected upgrade: websocket', { status: 426 });
+    }
+    const token = extractToken(req);
+    if (!token)
+        return new Response('Unauthorized', { status: 401 });
+    // `WebSocketPair` is a Cloudflare Workers global. We reference it
+    // through `globalThis` so importing this module in non-CF runtimes
+    // (e.g. during type-checking on Node) doesn't crash.
+    const Pair = globalThis.WebSocketPair;
+    if (!Pair) {
+        return new Response('WebSocketPair unavailable in this runtime', { status: 501 });
+    }
+    const pair = new Pair();
+    const client = pair[0];
+    const server = pair[1];
+    server.accept();
+    const conn = createWHATWGPairingConnection(server);
+    const result = await agent.acceptConnection(token, conn);
+    if (!result.ok) {
+        conn.close();
+        return new Response(result.code, { status: result.status });
+    }
+    // `webSocket` on ResponseInit is Cloudflare-specific; cast to satisfy
+    // the standard lib types.
+    return new Response(null, { status: 101, webSocket: client });
+}
+/**
+ * Deno handler. Uses `Deno.upgradeWebSocket(req)` to produce the
+ * response + socket pair, then plugs the socket into the registry.
+ *
+ * Usage:
+ * ```ts
+ * Deno.serve(async (req) => {
+ *   const url = new URL(req.url)
+ *   if (url.pathname === '/agent/ws') return handleDenoUpgrade(req, agent)
+ *   return (await agent.router(req)) ?? new Response('Not Found', { status: 404 })
+ * })
+ * ```
+ */
+export async function handleDenoUpgrade(req, agent) {
+    const token = extractToken(req);
+    if (!token)
+        return new Response('Unauthorized', { status: 401 });
+    const Deno_ = globalThis.Deno;
+    if (!Deno_) {
+        return new Response('Deno.upgradeWebSocket unavailable in this runtime', { status: 501 });
+    }
+    const { socket, response } = Deno_.upgradeWebSocket(req);
+    const conn = createWHATWGPairingConnection(socket);
+    // Deno opens the socket asynchronously; validate the token first,
+    // then register on `open` so frames aren't missed.
+    socket.addEventListener('open', () => {
+        void agent.acceptConnection(token, conn).then((result) => {
+            if (!result.ok)
+                conn.close();
+        });
+    }, { once: true });
+    return response;
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/server/web/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../../src/server/web/upgrade.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentCoreHandle } from '../core.js'\nimport { createWHATWGPairingConnection } from './adapter.js'\n\n/**\n * Extract the bearer token from a LAP WebSocket upgrade request.\n * Accepts the token on either `?token=` or `Authorization: Bearer` —\n * query-string is the common pattern because browsers can't set\n * arbitrary headers on WebSocket construction.\n */\nexport function extractToken(req: Request): string | null {\n  const url = new URL(req.url)\n  const q = url.searchParams.get('token')\n  if (q) return q\n  const auth = req.headers.get('authorization')\n  if (auth?.startsWith('Bearer ')) return auth.slice('Bearer '.length)\n  return null\n}\n\n/**\n * Cloudflare Workers handler. Accepts a WebSocket upgrade using\n * `WebSocketPair`, validates the token via\n * `agent.acceptConnection`, and returns the 101 upgrade Response.\n *\n * Usage:\n * ```ts\n * const agent = createLluiAgentCore({ signingKey: env.AGENT_KEY })\n * export default {\n *   async fetch(req, env) {\n *     const url = new URL(req.url)\n *     if (url.pathname === '/agent/ws') return handleCloudflareUpgrade(req, agent)\n *     return (await agent.router(req)) ?? new Response('Not Found', { status: 404 })\n *   },\n * }\n * ```\n */\nexport async function handleCloudflareUpgrade(\n  req: Request,\n  agent: AgentCoreHandle,\n): Promise<Response> {\n  if (req.headers.get('upgrade') !== 'websocket') {\n    return new Response('Expected upgrade: websocket', { status: 426 })\n  }\n  const token = extractToken(req)\n  if (!token) return new Response('Unauthorized', { status: 401 })\n\n  // `WebSocketPair` is a Cloudflare Workers global. We reference it\n  // through `globalThis` so importing this module in non-CF runtimes\n  // (e.g. during type-checking on Node) doesn't crash.\n  const Pair = (\n    globalThis as unknown as { WebSocketPair?: new () => { 0: WebSocket; 1: WebSocket } }\n  ).WebSocketPair\n  if (!Pair) {\n    return new Response('WebSocketPair unavailable in this runtime', { status: 501 })\n  }\n  const pair = new Pair()\n  const client = pair[0]\n  const server = pair[1]!\n  // `accept()` on the server half is Cloudflare-specific — it tells\n  // the runtime the Worker will handle the WebSocket itself.\n  ;(server as unknown as { accept: () => void }).accept()\n\n  const conn = createWHATWGPairingConnection(server)\n  const result = await agent.acceptConnection(token, conn)\n  if (!result.ok) {\n    conn.close()\n    return new Response(result.code, { status: result.status })\n  }\n\n  // `webSocket` on ResponseInit is Cloudflare-specific; cast to satisfy\n  // the standard lib types.\n  return new Response(null, { status: 101, webSocket: client } as ResponseInit & {\n    webSocket: WebSocket\n  })\n}\n\n/**\n * Deno handler. Uses `Deno.upgradeWebSocket(req)` to produce the\n * response + socket pair, then plugs the socket into the registry.\n *\n * Usage:\n * ```ts\n * Deno.serve(async (req) => {\n *   const url = new URL(req.url)\n *   if (url.pathname === '/agent/ws') return handleDenoUpgrade(req, agent)\n *   return (await agent.router(req)) ?? new Response('Not Found', { status: 404 })\n * })\n * ```\n */\nexport async function handleDenoUpgrade(req: Request, agent: AgentCoreHandle): Promise<Response> {\n  const token = extractToken(req)\n  if (!token) return new Response('Unauthorized', { status: 401 })\n\n  const Deno_ = (\n    globalThis as unknown as {\n      Deno?: {\n        upgradeWebSocket: (req: Request) => { socket: WebSocket; response: Response }\n      }\n    }\n  ).Deno\n  if (!Deno_) {\n    return new Response('Deno.upgradeWebSocket unavailable in this runtime', { status: 501 })\n  }\n\n  const { socket, response } = Deno_.upgradeWebSocket(req)\n  const conn = createWHATWGPairingConnection(socket)\n\n  // Deno opens the socket asynchronously; validate the token first,\n  // then register on `open` so frames aren't missed.\n  socket.addEventListener(\n    'open',\n    () => {\n      void agent.acceptConnection(token, conn).then((result) => {\n        if (!result.ok) conn.close()\n      })\n    },\n    { once: true },\n  )\n\n  return response\n}\n"]}

package/dist/server/ws/pairing-registry.d.ts

@@ -1,7 +1,11 @@
 import type { ClientFrame, ServerFrame, HelloFrame, LogEntry } from '../../protocol.js';
+import { type RpcOptions, type RpcError } from './rpc.js';
+export type { RpcOptions, RpcError };
 /**
- * Thin abstraction over a WebSocket so the registry is testable with
- * a fake EventEmitter-style mock.
+ * Thin abstraction over a single paired WebSocket. Consumed by the
+ * registry implementations; runtime-specific adapters (`ws`-lib,
+ * `WebSocketPair`, `Deno.upgradeWebSocket`, `Bun.serve` upgrade) build
+ * one of these and pass it to `registry.register()`.
  */
 export interface PairingConnection {
     send(frame: ServerFrame): void;
@@ -9,35 +13,85 @@ export interface PairingConnection {
     onClose(handler: () => void): void;
     close(): void;
 }
-export type RpcError = {
-    code: 'paused' | 'invalid' | 'timeout' | 'schema-error' | 'internal' | string;
-    detail?: string;
-};
-export type RpcOptions = {
-    timeoutMs?: number;
-};
 /**
- * Tracks live browser pairings and correlates rpc requests with replies.
- * One instance per server; shared by all LAP handlers + the upgrade
- * handler. Spec §10.4–§10.5.
+ * A per-call frame subscriber. Return `true` to remove this
+ * subscriber (one-shot), or `false` to keep receiving. The registry
+ * dispatches every inbound `ClientFrame` to every active subscriber
+ * for the given `tid`; subscribers filter by `frame.t` + identifiers
+ * (correlation id, confirm id, state path) to find the one that
+ * belongs to their request.
  */
-export declare class WsPairingRegistry {
+export type FrameSubscriber = (frame: ClientFrame) => boolean;
+/**
+ * Registry of live browser pairings. Pure routing + hello cache —
+ * request-lifecycle state (in-flight RPC promises, confirm waits,
+ * long-polls) lives in the LAP handlers that need it, not here.
+ *
+ * Two implementations ship today:
+ *   - `InMemoryPairingRegistry` for long-lived server processes
+ *     (Node, Bun, Deno, Deno Deploy).
+ *   - A Cloudflare Durable Object implementation (see
+ *     `server/cloudflare`) for stateless Worker runtimes.
+ *
+ * Other runtimes can implement this interface the same way; the
+ * contract is intentionally small.
+ */
+export interface PairingRegistry {
+    register(tid: string, conn: PairingConnection): void;
+    unregister(tid: string): void;
+    isPaired(tid: string): boolean;
+    getHello(tid: string): HelloFrame | null;
+    /** Send a frame. No-op when the pairing is absent or closed. */
+    send(tid: string, frame: ServerFrame): void;
+    /**
+     * Subscribe to frames from the paired browser. Returns an
+     * unsubscribe function. A subscriber can remove itself mid-dispatch
+     * by returning `true` from its callback — useful for one-shot
+     * request/response correlation.
+     */
+    subscribe(tid: string, handler: FrameSubscriber): () => void;
+    /**
+     * Observe the pairing closing (WebSocket drop, `unregister`, etc.).
+     * Handlers registered before close fire; handlers registered after
+     * close fire synchronously. Returns an unsubscribe function.
+     */
+    onClose(tid: string, handler: () => void): () => void;
+    /**
+     * Send a typed rpc frame and await its matching reply. See
+     * `./rpc.ts::rpc` for the full contract.
+     */
+    rpc(tid: string, tool: string, args: unknown, opts?: RpcOptions): Promise<unknown>;
+    /** See `./rpc.ts::waitForConfirm`. */
+    waitForConfirm(tid: string, confirmId: string, timeoutMs: number): Promise<{
+        outcome: 'confirmed' | 'user-cancelled';
+        stateAfter?: unknown;
+    }>;
+    /** See `./rpc.ts::waitForChange`. */
+    waitForChange(tid: string, path: string | undefined, timeoutMs: number): Promise<{
+        status: 'changed' | 'timeout';
+        stateAfter: unknown;
+    }>;
+}
+/**
+ * Single-process in-memory registry. Correct for Node/Bun/Deno/Deno
+ * Deploy — anywhere the server process can hold a long-lived
+ * WebSocket. Not suitable for stateless Worker isolates; use the
+ * Durable Object registry for Cloudflare.
+ */
+export declare class InMemoryPairingRegistry implements PairingRegistry {
     private pairings;
-    private now;
     private onLogAppend;
     constructor(opts?: {
-        now?: () => number;
         onLogAppend?: (tid: string, entry: LogEntry) => void;
     });
     register(tid: string, conn: PairingConnection): void;
     unregister(tid: string): void;
     isPaired(tid: string): boolean;
-    /**
-     * Send a ServerFrame to the paired browser connection, if one is live.
-     * No-op when unpaired or closed.
-     */
-    notify(tid: string, frame: ServerFrame): void;
     getHello(tid: string): HelloFrame | null;
+    send(tid: string, frame: ServerFrame): void;
+    subscribe(tid: string, handler: FrameSubscriber): () => void;
+    onClose(tid: string, handler: () => void): () => void;
+    private dispatch;
     rpc(tid: string, tool: string, args: unknown, opts?: RpcOptions): Promise<unknown>;
     waitForConfirm(tid: string, confirmId: string, timeoutMs: number): Promise<{
         outcome: 'confirmed' | 'user-cancelled';
@@ -47,7 +101,16 @@ export declare class WsPairingRegistry {
         status: 'changed' | 'timeout';
         stateAfter: unknown;
     }>;
-    private handleClientFrame;
+    /** @deprecated Use `send(tid, frame)` directly; semantics are identical. */
+    notify(tid: string, frame: ServerFrame): void;
     private handleClose;
 }
+/**
+ * Back-compat alias for the prior class name. New code should use
+ * `InMemoryPairingRegistry`. Removed in a future major.
+ *
+ * @deprecated Use `InMemoryPairingRegistry` directly.
+ */
+export declare const WsPairingRegistry: typeof InMemoryPairingRegistry;
+export type WsPairingRegistry = InMemoryPairingRegistry;
 //# sourceMappingURL=pairing-registry.d.ts.map

package/dist/server/ws/pairing-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing-registry.d.ts","sourceRoot":"","sources":["../../../src/server/ws/pairing-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEvF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IAC9B,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAA;IAChD,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAClC,KAAK,IAAI,IAAI,CAAA;CACd;AA4BD,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,GAAG,MAAM,CAAA;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/C;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,WAAW,CAAiD;gBAGlE,IAAI,GAAE;QACJ,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;QAClB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAA;KAChD;IAMR,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAcpD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK9B;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAU7C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IA6BtF,cAAc,CAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,OAAO,EAAE,WAAW,GAAG,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAiBvE,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;IAiBlE,OAAO,CAAC,iBAAiB;IAmDzB,OAAO,CAAC,WAAW;CAqBpB"}
+{"version":3,"file":"pairing-registry.d.ts","sourceRoot":"","sources":["../../../src/server/ws/pairing-registry.ts"],"names":[],"mappings":"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"}

package/dist/server/ws/pairing-registry.js

@@ -1,45 +1,39 @@
-import { randomUUID } from 'node:crypto';
+import { rpc as rpcHelper, waitForConfirm as waitForConfirmHelper, waitForChange as waitForChangeHelper, } from './rpc.js';
 /**
- * Tracks live browser pairings and correlates rpc requests with replies.
- * One instance per server; shared by all LAP handlers + the upgrade
- * handler. Spec §10.4–§10.5.
+ * Single-process in-memory registry. Correct for Node/Bun/Deno/Deno
+ * Deploy — anywhere the server process can hold a long-lived
+ * WebSocket. Not suitable for stateless Worker isolates; use the
+ * Durable Object registry for Cloudflare.
  */
-export class WsPairingRegistry {
+export class InMemoryPairingRegistry {
     pairings = new Map();
-    now;
     onLogAppend;
     constructor(opts = {}) {
-        this.now = opts.now ?? (() => Date.now());
         this.onLogAppend = opts.onLogAppend ?? null;
     }
     register(tid, conn) {
         const p = {
             conn,
             hello: null,
-            pendingRpc: new Map(),
-            pendingConfirm: new Map(),
-            pendingWait: [],
+            subscribers: new Set(),
+            closeHandlers: new Set(),
             closed: false,
         };
         this.pairings.set(tid, p);
-        conn.onFrame((frame) => this.handleClientFrame(tid, frame));
+        conn.onFrame((frame) => this.dispatch(tid, frame));
         conn.onClose(() => this.handleClose(tid));
     }
     unregister(tid) {
-        const p = this.pairings.get(tid);
-        if (!p)
-            return;
         this.handleClose(tid);
     }
     isPaired(tid) {
         const p = this.pairings.get(tid);
         return !!p && !p.closed;
     }
-    /**
-     * Send a ServerFrame to the paired browser connection, if one is live.
-     * No-op when unpaired or closed.
-     */
-    notify(tid, frame) {
+    getHello(tid) {
+        return this.pairings.get(tid)?.hello ?? null;
+    }
+    send(tid, frame) {
         const p = this.pairings.get(tid);
         if (!p || p.closed)
             return;
@@ -47,159 +41,103 @@ export class WsPairingRegistry {
             p.conn.send(frame);
         }
         catch {
-            // connection may have dropped between isPaired and notify; ignore
+            // Connection may have dropped between isPaired() and send(); no-op.
         }
     }
-    getHello(tid) {
-        return this.pairings.get(tid)?.hello ?? null;
-    }
-    async rpc(tid, tool, args, opts = {}) {
+    subscribe(tid, handler) {
         const p = this.pairings.get(tid);
-        if (!p || p.closed) {
-            const err = { code: 'paused' };
-            throw err;
-        }
-        const id = randomUUID();
-        const timeoutMs = opts.timeoutMs ?? 15_000;
-        return new Promise((resolve, reject) => {
-            const entry = {
-                resolve,
-                reject,
-                timer: setTimeout(() => {
-                    p.pendingRpc.delete(id);
-                    reject({ code: 'timeout' });
-                }, timeoutMs),
-            };
-            p.pendingRpc.set(id, entry);
-            const frame = { t: 'rpc', id, tool, args };
-            try {
-                p.conn.send(frame);
-            }
-            catch (e) {
-                p.pendingRpc.delete(id);
-                if (entry.timer)
-                    clearTimeout(entry.timer);
-                reject({ code: 'internal', detail: String(e) });
-            }
-        });
+        if (!p || p.closed)
+            return () => { };
+        p.subscribers.add(handler);
+        return () => {
+            p.subscribers.delete(handler);
+        };
     }
-    async waitForConfirm(tid, confirmId, timeoutMs) {
+    onClose(tid, handler) {
         const p = this.pairings.get(tid);
         if (!p || p.closed) {
-            return { outcome: 'user-cancelled' };
+            // Already closed — fire synchronously so callers don't hang
+            // waiting for a close that already happened.
+            queueMicrotask(handler);
+            return () => { };
         }
-        return new Promise((resolve) => {
-            const entry = {
-                resolve,
-                timer: setTimeout(() => {
-                    p.pendingConfirm.delete(confirmId);
-                    resolve({ outcome: 'user-cancelled' });
-                }, timeoutMs),
-            };
-            p.pendingConfirm.set(confirmId, entry);
-        });
-    }
-    async waitForChange(tid, path, timeoutMs) {
-        const p = this.pairings.get(tid);
-        if (!p || p.closed)
-            return { status: 'timeout', stateAfter: null };
-        return new Promise((resolve) => {
-            const entry = {
-                path,
-                resolve,
-                timer: setTimeout(() => {
-                    const idx = p.pendingWait.indexOf(entry);
-                    if (idx >= 0)
-                        p.pendingWait.splice(idx, 1);
-                    resolve({ status: 'timeout', stateAfter: null });
-                }, timeoutMs),
-            };
-            p.pendingWait.push(entry);
-        });
+        p.closeHandlers.add(handler);
+        return () => {
+            p.closeHandlers.delete(handler);
+        };
     }
-    handleClientFrame(tid, frame) {
+    dispatch(tid, frame) {
         const p = this.pairings.get(tid);
         if (!p || p.closed)
             return;
-        switch (frame.t) {
-            case 'hello': {
-                p.hello = frame;
-                break;
-            }
-            case 'rpc-reply': {
-                const e = p.pendingRpc.get(frame.id);
-                if (!e)
-                    break;
-                p.pendingRpc.delete(frame.id);
-                if (e.timer)
-                    clearTimeout(e.timer);
-                e.resolve(frame.result);
-                break;
-            }
-            case 'rpc-error': {
-                const e = p.pendingRpc.get(frame.id);
-                if (!e)
-                    break;
-                p.pendingRpc.delete(frame.id);
-                if (e.timer)
-                    clearTimeout(e.timer);
-                e.reject({ code: frame.code, detail: frame.detail });
-                break;
-            }
-            case 'confirm-resolved': {
-                const e = p.pendingConfirm.get(frame.confirmId);
-                if (!e)
-                    break;
-                p.pendingConfirm.delete(frame.confirmId);
-                if (e.timer)
-                    clearTimeout(e.timer);
-                e.resolve({ outcome: frame.outcome, stateAfter: frame.stateAfter });
-                break;
-            }
-            case 'state-update': {
-                for (let i = p.pendingWait.length - 1; i >= 0; i--) {
-                    const w = p.pendingWait[i];
-                    if (w === undefined)
-                        continue;
-                    if (w.path === undefined || w.path === frame.path || frame.path.startsWith(w.path)) {
-                        p.pendingWait.splice(i, 1);
-                        if (w.timer)
-                            clearTimeout(w.timer);
-                        w.resolve({ status: 'changed', stateAfter: frame.stateAfter });
-                    }
-                }
-                break;
+        // hello and log-append are registry-owned side effects — handled
+        // here so no per-call subscriber has to pick them up.
+        if (frame.t === 'hello') {
+            p.hello = frame;
+            return;
+        }
+        if (frame.t === 'log-append') {
+            this.onLogAppend?.(tid, frame.entry);
+            return;
+        }
+        // Iterate over a snapshot because subscribers may self-remove
+        // mid-iteration by returning true.
+        const snapshot = Array.from(p.subscribers);
+        for (const sub of snapshot) {
+            try {
+                if (sub(frame))
+                    p.subscribers.delete(sub);
             }
-            case 'log-append': {
-                this.onLogAppend?.(tid, frame.entry);
-                break;
+            catch {
+                // One bad subscriber shouldn't break the others.
+                p.subscribers.delete(sub);
             }
         }
     }
+    // ── Convenience wrappers ───────────────────────────────────────
+    // The following methods delegate to the free-function helpers in
+    // `./rpc.ts`. They're here so the in-memory registry remains a
+    // one-stop testing surface (spy on `registry.rpc`, etc.) without
+    // couping the `PairingRegistry` interface to request-lifecycle
+    // details. External implementations (e.g. the Cloudflare Durable
+    // Object registry) are NOT required to provide these; the LAP
+    // handlers always go through the free helpers.
+    rpc(tid, tool, args, opts = {}) {
+        return rpcHelper(this, tid, tool, args, opts);
+    }
+    waitForConfirm(tid, confirmId, timeoutMs) {
+        return waitForConfirmHelper(this, tid, confirmId, timeoutMs);
+    }
+    waitForChange(tid, path, timeoutMs) {
+        return waitForChangeHelper(this, tid, path, timeoutMs);
+    }
+    /** @deprecated Use `send(tid, frame)` directly; semantics are identical. */
+    notify(tid, frame) {
+        this.send(tid, frame);
+    }
     handleClose(tid) {
         const p = this.pairings.get(tid);
-        if (!p)
+        if (!p || p.closed)
             return;
         p.closed = true;
-        for (const [, e] of p.pendingRpc) {
-            if (e.timer)
-                clearTimeout(e.timer);
-            e.reject({ code: 'paused' });
-        }
-        p.pendingRpc.clear();
-        for (const [, e] of p.pendingConfirm) {
-            if (e.timer)
-                clearTimeout(e.timer);
-            e.resolve({ outcome: 'user-cancelled' });
-        }
-        p.pendingConfirm.clear();
-        for (const w of p.pendingWait) {
-            if (w.timer)
-                clearTimeout(w.timer);
-            w.resolve({ status: 'timeout', stateAfter: null });
+        for (const h of Array.from(p.closeHandlers)) {
+            try {
+                h();
+            }
+            catch {
+                // Swallow — handlers run best-effort.
+            }
         }
-        p.pendingWait.length = 0;
+        p.closeHandlers.clear();
+        p.subscribers.clear();
         this.pairings.delete(tid);
     }
 }
+/**
+ * Back-compat alias for the prior class name. New code should use
+ * `InMemoryPairingRegistry`. Removed in a future major.
+ *
+ * @deprecated Use `InMemoryPairingRegistry` directly.
+ */
+export const WsPairingRegistry = InMemoryPairingRegistry;
 //# sourceMappingURL=pairing-registry.js.map