@llui/agent 0.0.31 → 0.0.34

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

@@ -56,6 +56,14 @@ export interface PairingRegistry {
      * close fire synchronously. Returns an unsubscribe function.
      */
     onClose(tid: string, handler: () => void): () => void;
+    /**
+     * Read the most recent `n` log entries for a tid (newest first).
+     * Backed by an in-memory ring buffer populated as the registry
+     * sees `log-append` frames; capped per-tid to bound memory across
+     * long-lived sessions. Drained on close. Returns an empty array
+     * for unknown tids.
+     */
+    getRecentLog(tid: string, n: number): LogEntry[];
     /**
      * Send a typed rpc frame and await its matching reply. See
      * `./rpc.ts::rpc` for the full contract.
@@ -72,18 +80,26 @@ export interface PairingRegistry {
         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 onLogAppend;
+    /**
+     * Per-tid ring buffer of recent log entries. Populated as the
+     * registry sees `log-append` frames; trimmed to RECENT_LOG_CAP.
+     * The agent reads this via `describe_recent_actions` to introspect
+     * its own activity history with stateDiffs intact.
+     */
+    private recentLog;
     constructor(opts?: {
         onLogAppend?: (tid: string, entry: LogEntry) => void;
     });
+    /**
+     * Read the most recent `n` log entries for a tid, newest-first. Returns
+     * an empty array when the tid is unknown or has no recorded activity.
+     * Drained from the in-memory ring buffer; entries older than
+     * RECENT_LOG_CAP have already been trimmed.
+     */
+    getRecentLog(tid: string, n: number): LogEntry[];
     register(tid: string, conn: PairingConnection): void;
     unregister(tid: string): void;
     isPaired(tid: string): boolean;

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":"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"}
+{"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

@@ -5,12 +5,43 @@ import { rpc as rpcHelper, waitForConfirm as waitForConfirmHelper, waitForChange
  * WebSocket. Not suitable for stateless Worker isolates; use the
  * Durable Object registry for Cloudflare.
  */
+/**
+ * Per-tid cap on the recent-log ring buffer. Sized to cover a few
+ * minutes of agent activity at typical dispatch rates without
+ * growing unboundedly for long-lived sessions. Reads via
+ * `getRecentLog` clamp to this; agents asking for more get whatever
+ * the buffer currently holds.
+ */
+const RECENT_LOG_CAP = 100;
 export class InMemoryPairingRegistry {
     pairings = new Map();
     onLogAppend;
+    /**
+     * Per-tid ring buffer of recent log entries. Populated as the
+     * registry sees `log-append` frames; trimmed to RECENT_LOG_CAP.
+     * The agent reads this via `describe_recent_actions` to introspect
+     * its own activity history with stateDiffs intact.
+     */
+    recentLog = new Map();
     constructor(opts = {}) {
         this.onLogAppend = opts.onLogAppend ?? null;
     }
+    /**
+     * Read the most recent `n` log entries for a tid, newest-first. Returns
+     * an empty array when the tid is unknown or has no recorded activity.
+     * Drained from the in-memory ring buffer; entries older than
+     * RECENT_LOG_CAP have already been trimmed.
+     */
+    getRecentLog(tid, n) {
+        const buf = this.recentLog.get(tid);
+        if (!buf || buf.length === 0)
+            return [];
+        const count = Math.min(Math.max(0, Math.floor(n)), buf.length);
+        if (count === 0)
+            return [];
+        // Buffer is append-order; return the tail reversed so newest is first.
+        return buf.slice(-count).reverse();
+    }
     register(tid, conn) {
         const p = {
             conn,
@@ -77,6 +108,19 @@ export class InMemoryPairingRegistry {
             return;
         }
         if (frame.t === 'log-append') {
+            // Push into the ring buffer for `describe_recent_actions`,
+            // capped to RECENT_LOG_CAP. The audit-sink callback runs
+            // alongside; both are independent observers of the same
+            // log-append stream.
+            let buf = this.recentLog.get(tid);
+            if (!buf) {
+                buf = [];
+                this.recentLog.set(tid, buf);
+            }
+            buf.push(frame.entry);
+            if (buf.length > RECENT_LOG_CAP) {
+                buf.splice(0, buf.length - RECENT_LOG_CAP);
+            }
             this.onLogAppend?.(tid, frame.entry);
             return;
         }
@@ -131,6 +175,11 @@ export class InMemoryPairingRegistry {
         p.closeHandlers.clear();
         p.subscribers.clear();
         this.pairings.delete(tid);
+        // Drop the recent-log ring buffer — once the pairing is gone,
+        // `describe_recent_actions` will reject anyway (paused/revoked
+        // gates run before the registry lookup), but holding the entries
+        // would leak memory across reconnects.
+        this.recentLog.delete(tid);
     }
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"pairing-registry.js","sourceRoot":"","sources":["../../../src/server/ws/pairing-registry.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ClientFrame, ServerFrame, HelloFrame, LogEntry } from '../../protocol.js'\nimport {\n  rpc as rpcHelper,\n  waitForConfirm as waitForConfirmHelper,\n  waitForChange as waitForChangeHelper,\n  type RpcOptions,\n  type RpcError,\n} from './rpc.js'\n\nexport type { RpcOptions, RpcError }\n\n/**\n * Thin abstraction over a single paired WebSocket. Consumed by the\n * registry implementations; runtime-specific adapters (`ws`-lib,\n * `WebSocketPair`, `Deno.upgradeWebSocket`, `Bun.serve` upgrade) build\n * one of these and pass it to `registry.register()`.\n */\nexport interface PairingConnection {\n  send(frame: ServerFrame): void\n  onFrame(handler: (f: ClientFrame) => void): void\n  onClose(handler: () => void): void\n  close(): void\n}\n\n/**\n * A per-call frame subscriber. Return `true` to remove this\n * subscriber (one-shot), or `false` to keep receiving. The registry\n * dispatches every inbound `ClientFrame` to every active subscriber\n * for the given `tid`; subscribers filter by `frame.t` + identifiers\n * (correlation id, confirm id, state path) to find the one that\n * belongs to their request.\n */\nexport type FrameSubscriber = (frame: ClientFrame) => boolean\n\n/**\n * Registry of live browser pairings. Pure routing + hello cache —\n * request-lifecycle state (in-flight RPC promises, confirm waits,\n * long-polls) lives in the LAP handlers that need it, not here.\n *\n * Two implementations ship today:\n *   - `InMemoryPairingRegistry` for long-lived server processes\n *     (Node, Bun, Deno, Deno Deploy).\n *   - A Cloudflare Durable Object implementation (see\n *     `server/cloudflare`) for stateless Worker runtimes.\n *\n * Other runtimes can implement this interface the same way; the\n * contract is intentionally small.\n */\nexport interface PairingRegistry {\n  // ── Routing primitives ─────────────────────────────────────────\n  register(tid: string, conn: PairingConnection): void\n  unregister(tid: string): void\n  isPaired(tid: string): boolean\n  getHello(tid: string): HelloFrame | null\n  /** Send a frame. No-op when the pairing is absent or closed. */\n  send(tid: string, frame: ServerFrame): void\n  /**\n   * Subscribe to frames from the paired browser. Returns an\n   * unsubscribe function. A subscriber can remove itself mid-dispatch\n   * by returning `true` from its callback — useful for one-shot\n   * request/response correlation.\n   */\n  subscribe(tid: string, handler: FrameSubscriber): () => void\n  /**\n   * Observe the pairing closing (WebSocket drop, `unregister`, etc.).\n   * Handlers registered before close fire; handlers registered after\n   * close fire synchronously. Returns an unsubscribe function.\n   */\n  onClose(tid: string, handler: () => void): () => void\n\n  // ── Request/response helpers ───────────────────────────────────\n  // These are part of the contract (LAP handlers call them directly)\n  // but implementations almost always delegate to the free helpers in\n  // `./rpc.ts`, which are built on the routing primitives above. The\n  // Cloudflare Durable Object registry uses the same helpers; the\n  // split exists so the routing surface is small enough to implement\n  // across stateful boundaries (DO storage, WebSocket hibernation),\n  // while the correlation logic lives once in a runtime-neutral file.\n\n  /**\n   * Send a typed rpc frame and await its matching reply. See\n   * `./rpc.ts::rpc` for the full contract.\n   */\n  rpc(tid: string, tool: string, args: unknown, opts?: RpcOptions): Promise<unknown>\n  /** See `./rpc.ts::waitForConfirm`. */\n  waitForConfirm(\n    tid: string,\n    confirmId: string,\n    timeoutMs: number,\n  ): Promise<{ outcome: 'confirmed' | 'user-cancelled'; stateAfter?: unknown }>\n  /** See `./rpc.ts::waitForChange`. */\n  waitForChange(\n    tid: string,\n    path: string | undefined,\n    timeoutMs: number,\n  ): Promise<{ status: 'changed' | 'timeout'; stateAfter: unknown }>\n}\n\ntype Pairing = {\n  conn: PairingConnection\n  hello: HelloFrame | null\n  subscribers: Set<FrameSubscriber>\n  closeHandlers: Set<() => void>\n  closed: boolean\n}\n\n/**\n * Single-process in-memory registry. Correct for Node/Bun/Deno/Deno\n * Deploy — anywhere the server process can hold a long-lived\n * WebSocket. Not suitable for stateless Worker isolates; use the\n * Durable Object registry for Cloudflare.\n */\nexport class InMemoryPairingRegistry implements PairingRegistry {\n  private pairings = new Map<string, Pairing>()\n  private onLogAppend: ((tid: string, entry: LogEntry) => void) | null\n\n  constructor(\n    opts: {\n      onLogAppend?: (tid: string, entry: LogEntry) => void\n    } = {},\n  ) {\n    this.onLogAppend = opts.onLogAppend ?? null\n  }\n\n  register(tid: string, conn: PairingConnection): void {\n    const p: Pairing = {\n      conn,\n      hello: null,\n      subscribers: new Set(),\n      closeHandlers: new Set(),\n      closed: false,\n    }\n    this.pairings.set(tid, p)\n    conn.onFrame((frame) => this.dispatch(tid, frame))\n    conn.onClose(() => this.handleClose(tid))\n  }\n\n  unregister(tid: string): void {\n    this.handleClose(tid)\n  }\n\n  isPaired(tid: string): boolean {\n    const p = this.pairings.get(tid)\n    return !!p && !p.closed\n  }\n\n  getHello(tid: string): HelloFrame | null {\n    return this.pairings.get(tid)?.hello ?? null\n  }\n\n  send(tid: string, frame: ServerFrame): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    try {\n      p.conn.send(frame)\n    } catch {\n      // Connection may have dropped between isPaired() and send(); no-op.\n    }\n  }\n\n  subscribe(tid: string, handler: FrameSubscriber): () => void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return () => {}\n    p.subscribers.add(handler)\n    return () => {\n      p.subscribers.delete(handler)\n    }\n  }\n\n  onClose(tid: string, handler: () => void): () => void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) {\n      // Already closed — fire synchronously so callers don't hang\n      // waiting for a close that already happened.\n      queueMicrotask(handler)\n      return () => {}\n    }\n    p.closeHandlers.add(handler)\n    return () => {\n      p.closeHandlers.delete(handler)\n    }\n  }\n\n  private dispatch(tid: string, frame: ClientFrame): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    // hello and log-append are registry-owned side effects — handled\n    // here so no per-call subscriber has to pick them up.\n    if (frame.t === 'hello') {\n      p.hello = frame\n      return\n    }\n    if (frame.t === 'log-append') {\n      this.onLogAppend?.(tid, frame.entry)\n      return\n    }\n    // Iterate over a snapshot because subscribers may self-remove\n    // mid-iteration by returning true.\n    const snapshot = Array.from(p.subscribers)\n    for (const sub of snapshot) {\n      try {\n        if (sub(frame)) p.subscribers.delete(sub)\n      } catch {\n        // One bad subscriber shouldn't break the others.\n        p.subscribers.delete(sub)\n      }\n    }\n  }\n\n  // ── Convenience wrappers ───────────────────────────────────────\n  // The following methods delegate to the free-function helpers in\n  // `./rpc.ts`. They're here so the in-memory registry remains a\n  // one-stop testing surface (spy on `registry.rpc`, etc.) without\n  // couping the `PairingRegistry` interface to request-lifecycle\n  // details. External implementations (e.g. the Cloudflare Durable\n  // Object registry) are NOT required to provide these; the LAP\n  // handlers always go through the free helpers.\n\n  rpc(tid: string, tool: string, args: unknown, opts: RpcOptions = {}): Promise<unknown> {\n    return rpcHelper(this, tid, tool, args, opts)\n  }\n\n  waitForConfirm(\n    tid: string,\n    confirmId: string,\n    timeoutMs: number,\n  ): Promise<{ outcome: 'confirmed' | 'user-cancelled'; stateAfter?: unknown }> {\n    return waitForConfirmHelper(this, tid, confirmId, timeoutMs)\n  }\n\n  waitForChange(\n    tid: string,\n    path: string | undefined,\n    timeoutMs: number,\n  ): Promise<{ status: 'changed' | 'timeout'; stateAfter: unknown }> {\n    return waitForChangeHelper(this, tid, path, timeoutMs)\n  }\n\n  /** @deprecated Use `send(tid, frame)` directly; semantics are identical. */\n  notify(tid: string, frame: ServerFrame): void {\n    this.send(tid, frame)\n  }\n\n  private handleClose(tid: string): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    p.closed = true\n    for (const h of Array.from(p.closeHandlers)) {\n      try {\n        h()\n      } catch {\n        // Swallow — handlers run best-effort.\n      }\n    }\n    p.closeHandlers.clear()\n    p.subscribers.clear()\n    this.pairings.delete(tid)\n  }\n}\n\n/**\n * Back-compat alias for the prior class name. New code should use\n * `InMemoryPairingRegistry`. Removed in a future major.\n *\n * @deprecated Use `InMemoryPairingRegistry` directly.\n */\nexport const WsPairingRegistry = InMemoryPairingRegistry\nexport type WsPairingRegistry = InMemoryPairingRegistry\n"]}
+{"version":3,"file":"pairing-registry.js","sourceRoot":"","sources":["../../../src/server/ws/pairing-registry.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ClientFrame, ServerFrame, HelloFrame, LogEntry } from '../../protocol.js'\nimport {\n  rpc as rpcHelper,\n  waitForConfirm as waitForConfirmHelper,\n  waitForChange as waitForChangeHelper,\n  type RpcOptions,\n  type RpcError,\n} from './rpc.js'\n\nexport type { RpcOptions, RpcError }\n\n/**\n * Thin abstraction over a single paired WebSocket. Consumed by the\n * registry implementations; runtime-specific adapters (`ws`-lib,\n * `WebSocketPair`, `Deno.upgradeWebSocket`, `Bun.serve` upgrade) build\n * one of these and pass it to `registry.register()`.\n */\nexport interface PairingConnection {\n  send(frame: ServerFrame): void\n  onFrame(handler: (f: ClientFrame) => void): void\n  onClose(handler: () => void): void\n  close(): void\n}\n\n/**\n * A per-call frame subscriber. Return `true` to remove this\n * subscriber (one-shot), or `false` to keep receiving. The registry\n * dispatches every inbound `ClientFrame` to every active subscriber\n * for the given `tid`; subscribers filter by `frame.t` + identifiers\n * (correlation id, confirm id, state path) to find the one that\n * belongs to their request.\n */\nexport type FrameSubscriber = (frame: ClientFrame) => boolean\n\n/**\n * Registry of live browser pairings. Pure routing + hello cache —\n * request-lifecycle state (in-flight RPC promises, confirm waits,\n * long-polls) lives in the LAP handlers that need it, not here.\n *\n * Two implementations ship today:\n *   - `InMemoryPairingRegistry` for long-lived server processes\n *     (Node, Bun, Deno, Deno Deploy).\n *   - A Cloudflare Durable Object implementation (see\n *     `server/cloudflare`) for stateless Worker runtimes.\n *\n * Other runtimes can implement this interface the same way; the\n * contract is intentionally small.\n */\nexport interface PairingRegistry {\n  // ── Routing primitives ─────────────────────────────────────────\n  register(tid: string, conn: PairingConnection): void\n  unregister(tid: string): void\n  isPaired(tid: string): boolean\n  getHello(tid: string): HelloFrame | null\n  /** Send a frame. No-op when the pairing is absent or closed. */\n  send(tid: string, frame: ServerFrame): void\n  /**\n   * Subscribe to frames from the paired browser. Returns an\n   * unsubscribe function. A subscriber can remove itself mid-dispatch\n   * by returning `true` from its callback — useful for one-shot\n   * request/response correlation.\n   */\n  subscribe(tid: string, handler: FrameSubscriber): () => void\n  /**\n   * Observe the pairing closing (WebSocket drop, `unregister`, etc.).\n   * Handlers registered before close fire; handlers registered after\n   * close fire synchronously. Returns an unsubscribe function.\n   */\n  onClose(tid: string, handler: () => void): () => void\n\n  /**\n   * Read the most recent `n` log entries for a tid (newest first).\n   * Backed by an in-memory ring buffer populated as the registry\n   * sees `log-append` frames; capped per-tid to bound memory across\n   * long-lived sessions. Drained on close. Returns an empty array\n   * for unknown tids.\n   */\n  getRecentLog(tid: string, n: number): LogEntry[]\n\n  // ── Request/response helpers ───────────────────────────────────\n  // These are part of the contract (LAP handlers call them directly)\n  // but implementations almost always delegate to the free helpers in\n  // `./rpc.ts`, which are built on the routing primitives above. The\n  // Cloudflare Durable Object registry uses the same helpers; the\n  // split exists so the routing surface is small enough to implement\n  // across stateful boundaries (DO storage, WebSocket hibernation),\n  // while the correlation logic lives once in a runtime-neutral file.\n\n  /**\n   * Send a typed rpc frame and await its matching reply. See\n   * `./rpc.ts::rpc` for the full contract.\n   */\n  rpc(tid: string, tool: string, args: unknown, opts?: RpcOptions): Promise<unknown>\n  /** See `./rpc.ts::waitForConfirm`. */\n  waitForConfirm(\n    tid: string,\n    confirmId: string,\n    timeoutMs: number,\n  ): Promise<{ outcome: 'confirmed' | 'user-cancelled'; stateAfter?: unknown }>\n  /** See `./rpc.ts::waitForChange`. */\n  waitForChange(\n    tid: string,\n    path: string | undefined,\n    timeoutMs: number,\n  ): Promise<{ status: 'changed' | 'timeout'; stateAfter: unknown }>\n}\n\ntype Pairing = {\n  conn: PairingConnection\n  hello: HelloFrame | null\n  subscribers: Set<FrameSubscriber>\n  closeHandlers: Set<() => void>\n  closed: boolean\n}\n\n/**\n * Single-process in-memory registry. Correct for Node/Bun/Deno/Deno\n * Deploy — anywhere the server process can hold a long-lived\n * WebSocket. Not suitable for stateless Worker isolates; use the\n * Durable Object registry for Cloudflare.\n */\n/**\n * Per-tid cap on the recent-log ring buffer. Sized to cover a few\n * minutes of agent activity at typical dispatch rates without\n * growing unboundedly for long-lived sessions. Reads via\n * `getRecentLog` clamp to this; agents asking for more get whatever\n * the buffer currently holds.\n */\nconst RECENT_LOG_CAP = 100\n\nexport class InMemoryPairingRegistry implements PairingRegistry {\n  private pairings = new Map<string, Pairing>()\n  private onLogAppend: ((tid: string, entry: LogEntry) => void) | null\n  /**\n   * Per-tid ring buffer of recent log entries. Populated as the\n   * registry sees `log-append` frames; trimmed to RECENT_LOG_CAP.\n   * The agent reads this via `describe_recent_actions` to introspect\n   * its own activity history with stateDiffs intact.\n   */\n  private recentLog = new Map<string, LogEntry[]>()\n\n  constructor(\n    opts: {\n      onLogAppend?: (tid: string, entry: LogEntry) => void\n    } = {},\n  ) {\n    this.onLogAppend = opts.onLogAppend ?? null\n  }\n\n  /**\n   * Read the most recent `n` log entries for a tid, newest-first. Returns\n   * an empty array when the tid is unknown or has no recorded activity.\n   * Drained from the in-memory ring buffer; entries older than\n   * RECENT_LOG_CAP have already been trimmed.\n   */\n  getRecentLog(tid: string, n: number): LogEntry[] {\n    const buf = this.recentLog.get(tid)\n    if (!buf || buf.length === 0) return []\n    const count = Math.min(Math.max(0, Math.floor(n)), buf.length)\n    if (count === 0) return []\n    // Buffer is append-order; return the tail reversed so newest is first.\n    return buf.slice(-count).reverse()\n  }\n\n  register(tid: string, conn: PairingConnection): void {\n    const p: Pairing = {\n      conn,\n      hello: null,\n      subscribers: new Set(),\n      closeHandlers: new Set(),\n      closed: false,\n    }\n    this.pairings.set(tid, p)\n    conn.onFrame((frame) => this.dispatch(tid, frame))\n    conn.onClose(() => this.handleClose(tid))\n  }\n\n  unregister(tid: string): void {\n    this.handleClose(tid)\n  }\n\n  isPaired(tid: string): boolean {\n    const p = this.pairings.get(tid)\n    return !!p && !p.closed\n  }\n\n  getHello(tid: string): HelloFrame | null {\n    return this.pairings.get(tid)?.hello ?? null\n  }\n\n  send(tid: string, frame: ServerFrame): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    try {\n      p.conn.send(frame)\n    } catch {\n      // Connection may have dropped between isPaired() and send(); no-op.\n    }\n  }\n\n  subscribe(tid: string, handler: FrameSubscriber): () => void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return () => {}\n    p.subscribers.add(handler)\n    return () => {\n      p.subscribers.delete(handler)\n    }\n  }\n\n  onClose(tid: string, handler: () => void): () => void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) {\n      // Already closed — fire synchronously so callers don't hang\n      // waiting for a close that already happened.\n      queueMicrotask(handler)\n      return () => {}\n    }\n    p.closeHandlers.add(handler)\n    return () => {\n      p.closeHandlers.delete(handler)\n    }\n  }\n\n  private dispatch(tid: string, frame: ClientFrame): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    // hello and log-append are registry-owned side effects — handled\n    // here so no per-call subscriber has to pick them up.\n    if (frame.t === 'hello') {\n      p.hello = frame\n      return\n    }\n    if (frame.t === 'log-append') {\n      // Push into the ring buffer for `describe_recent_actions`,\n      // capped to RECENT_LOG_CAP. The audit-sink callback runs\n      // alongside; both are independent observers of the same\n      // log-append stream.\n      let buf = this.recentLog.get(tid)\n      if (!buf) {\n        buf = []\n        this.recentLog.set(tid, buf)\n      }\n      buf.push(frame.entry)\n      if (buf.length > RECENT_LOG_CAP) {\n        buf.splice(0, buf.length - RECENT_LOG_CAP)\n      }\n      this.onLogAppend?.(tid, frame.entry)\n      return\n    }\n    // Iterate over a snapshot because subscribers may self-remove\n    // mid-iteration by returning true.\n    const snapshot = Array.from(p.subscribers)\n    for (const sub of snapshot) {\n      try {\n        if (sub(frame)) p.subscribers.delete(sub)\n      } catch {\n        // One bad subscriber shouldn't break the others.\n        p.subscribers.delete(sub)\n      }\n    }\n  }\n\n  // ── Convenience wrappers ───────────────────────────────────────\n  // The following methods delegate to the free-function helpers in\n  // `./rpc.ts`. They're here so the in-memory registry remains a\n  // one-stop testing surface (spy on `registry.rpc`, etc.) without\n  // couping the `PairingRegistry` interface to request-lifecycle\n  // details. External implementations (e.g. the Cloudflare Durable\n  // Object registry) are NOT required to provide these; the LAP\n  // handlers always go through the free helpers.\n\n  rpc(tid: string, tool: string, args: unknown, opts: RpcOptions = {}): Promise<unknown> {\n    return rpcHelper(this, tid, tool, args, opts)\n  }\n\n  waitForConfirm(\n    tid: string,\n    confirmId: string,\n    timeoutMs: number,\n  ): Promise<{ outcome: 'confirmed' | 'user-cancelled'; stateAfter?: unknown }> {\n    return waitForConfirmHelper(this, tid, confirmId, timeoutMs)\n  }\n\n  waitForChange(\n    tid: string,\n    path: string | undefined,\n    timeoutMs: number,\n  ): Promise<{ status: 'changed' | 'timeout'; stateAfter: unknown }> {\n    return waitForChangeHelper(this, tid, path, timeoutMs)\n  }\n\n  /** @deprecated Use `send(tid, frame)` directly; semantics are identical. */\n  notify(tid: string, frame: ServerFrame): void {\n    this.send(tid, frame)\n  }\n\n  private handleClose(tid: string): void {\n    const p = this.pairings.get(tid)\n    if (!p || p.closed) return\n    p.closed = true\n    for (const h of Array.from(p.closeHandlers)) {\n      try {\n        h()\n      } catch {\n        // Swallow — handlers run best-effort.\n      }\n    }\n    p.closeHandlers.clear()\n    p.subscribers.clear()\n    this.pairings.delete(tid)\n    // Drop the recent-log ring buffer — once the pairing is gone,\n    // `describe_recent_actions` will reject anyway (paused/revoked\n    // gates run before the registry lookup), but holding the entries\n    // would leak memory across reconnects.\n    this.recentLog.delete(tid)\n  }\n}\n\n/**\n * Back-compat alias for the prior class name. New code should use\n * `InMemoryPairingRegistry`. Removed in a future major.\n *\n * @deprecated Use `InMemoryPairingRegistry` directly.\n */\nexport const WsPairingRegistry = InMemoryPairingRegistry\nexport type WsPairingRegistry = InMemoryPairingRegistry\n"]}

package/dist/state-diff.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Compute a structural diff between two state snapshots and return it
+ * in JSON-Patch-shaped form (RFC 6902 subset: `add`, `remove`,
+ * `replace`).
+ *
+ * Why JSON Patch shape: LLMs see this exact format in their training
+ * data — it's the standard for describing object mutations on the
+ * wire. The agent learns the schema implicitly and can answer "what
+ * changed?" in a sentence by reading the ops.
+ *
+ * Why not unified-diff or per-binding dirty masks: the dirty mask
+ * tracks what bindings need re-rendering, which is a layout concern.
+ * The agent wants to know what *values* changed, which is a state
+ * concern. Dirty masks miss field-level resolution; per-path JSON
+ * Patch gives it.
+ *
+ * Cost is O(state size) per dispatch. For typical app states (a few
+ * KB) that's microseconds. Apps with very large states (collections
+ * of thousands of items) should subscribe to specific slices via
+ * `query_state` / `wait_for_change` instead of reading full diffs.
+ *
+ * Path escaping follows JSON Pointer (RFC 6901): `/` becomes `~1`,
+ * `~` becomes `~0`. The escape happens per-segment.
+ */
+export type JsonPatchOp = {
+    op: 'add';
+    path: string;
+    value: unknown;
+} | {
+    op: 'remove';
+    path: string;
+} | {
+    op: 'replace';
+    path: string;
+    value: unknown;
+};
+export type StateDiff = JsonPatchOp[];
+/**
+ * Compute the diff. Order of operations: removes first, then adds,
+ * then replaces. This is RFC 6902's recommended order — the receiver
+ * can apply ops sequentially without ambiguity.
+ *
+ * The implementation is a simple recursive walk; collection diffs
+ * are positional (index-based for arrays, key-based for objects)
+ * rather than structural (no LCS). Apps that pass identity-stable
+ * collections (`[...prev, item]`-style appends) get clean diffs;
+ * apps that rebuild arrays from scratch get noisy ones — same
+ * tradeoff a React reconciler makes, and the same fix (stable keys
+ * + push-don't-rebuild updates) applies.
+ */
+export declare function computeStateDiff(prev: unknown, next: unknown): StateDiff;
+//# sourceMappingURL=state-diff.d.ts.map

package/dist/state-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-diff.d.ts","sourceRoot":"","sources":["../src/state-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC3C;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAEnD,MAAM,MAAM,SAAS,GAAG,WAAW,EAAE,CAAA;AAErC;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,CAIxE"}

package/dist/state-diff.js

@@ -0,0 +1,119 @@
+/**
+ * Compute a structural diff between two state snapshots and return it
+ * in JSON-Patch-shaped form (RFC 6902 subset: `add`, `remove`,
+ * `replace`).
+ *
+ * Why JSON Patch shape: LLMs see this exact format in their training
+ * data — it's the standard for describing object mutations on the
+ * wire. The agent learns the schema implicitly and can answer "what
+ * changed?" in a sentence by reading the ops.
+ *
+ * Why not unified-diff or per-binding dirty masks: the dirty mask
+ * tracks what bindings need re-rendering, which is a layout concern.
+ * The agent wants to know what *values* changed, which is a state
+ * concern. Dirty masks miss field-level resolution; per-path JSON
+ * Patch gives it.
+ *
+ * Cost is O(state size) per dispatch. For typical app states (a few
+ * KB) that's microseconds. Apps with very large states (collections
+ * of thousands of items) should subscribe to specific slices via
+ * `query_state` / `wait_for_change` instead of reading full diffs.
+ *
+ * Path escaping follows JSON Pointer (RFC 6901): `/` becomes `~1`,
+ * `~` becomes `~0`. The escape happens per-segment.
+ */
+/**
+ * Compute the diff. Order of operations: removes first, then adds,
+ * then replaces. This is RFC 6902's recommended order — the receiver
+ * can apply ops sequentially without ambiguity.
+ *
+ * The implementation is a simple recursive walk; collection diffs
+ * are positional (index-based for arrays, key-based for objects)
+ * rather than structural (no LCS). Apps that pass identity-stable
+ * collections (`[...prev, item]`-style appends) get clean diffs;
+ * apps that rebuild arrays from scratch get noisy ones — same
+ * tradeoff a React reconciler makes, and the same fix (stable keys
+ * + push-don't-rebuild updates) applies.
+ */
+export function computeStateDiff(prev, next) {
+    const ops = [];
+    diffInto(prev, next, '', ops);
+    return ops;
+}
+function diffInto(prev, next, basePath, ops) {
+    if (Object.is(prev, next))
+        return;
+    // Either side null/undefined or non-object → straight replace at this path.
+    // (`null` is `typeof === 'object'`, so we test it explicitly.)
+    if (prev === null ||
+        next === null ||
+        prev === undefined ||
+        next === undefined ||
+        typeof prev !== 'object' ||
+        typeof next !== 'object') {
+        ops.push({ op: 'replace', path: basePath, value: next });
+        return;
+    }
+    const prevIsArr = Array.isArray(prev);
+    const nextIsArr = Array.isArray(next);
+    // Type change (object↔array) — single replace at the path. Recursing
+    // into mismatched containers would emit a wall of incoherent ops.
+    if (prevIsArr !== nextIsArr) {
+        ops.push({ op: 'replace', path: basePath, value: next });
+        return;
+    }
+    if (prevIsArr && nextIsArr) {
+        diffArray(prev, next, basePath, ops);
+        return;
+    }
+    diffObject(prev, next, basePath, ops);
+}
+function diffArray(prev, next, basePath, ops) {
+    const minLen = Math.min(prev.length, next.length);
+    // Recurse into shared indices.
+    for (let i = 0; i < minLen; i++) {
+        diffInto(prev[i], next[i], `${basePath}/${i}`, ops);
+    }
+    // Excess elements: remove from the end (descending order so each
+    // index is still valid as we apply).
+    if (prev.length > next.length) {
+        for (let i = prev.length - 1; i >= next.length; i--) {
+            ops.push({ op: 'remove', path: `${basePath}/${i}` });
+        }
+    }
+    // New elements: add at the position they end up in. RFC 6902 allows
+    // a `-` index for "append" semantics, but explicit indices are easier
+    // for the LLM to reason about ("alternative at index 8 was added").
+    if (next.length > prev.length) {
+        for (let i = prev.length; i < next.length; i++) {
+            ops.push({ op: 'add', path: `${basePath}/${i}`, value: next[i] });
+        }
+    }
+}
+function diffObject(prev, next, basePath, ops) {
+    // Removes: keys that exist in prev but not next.
+    for (const k in prev) {
+        if (!(k in next)) {
+            ops.push({ op: 'remove', path: `${basePath}/${escapeSegment(k)}` });
+        }
+    }
+    // Adds + replaces: keys in next.
+    for (const k in next) {
+        const path = `${basePath}/${escapeSegment(k)}`;
+        if (!(k in prev)) {
+            ops.push({ op: 'add', path, value: next[k] });
+        }
+        else {
+            diffInto(prev[k], next[k], path, ops);
+        }
+    }
+}
+/**
+ * Escape a single path segment per RFC 6901: `~` → `~0`, then `/` →
+ * `~1`. Order matters; do `~` first so `/` substitution doesn't
+ * double-escape an already-escaped tilde.
+ */
+function escapeSegment(seg) {
+    return seg.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+//# sourceMappingURL=state-diff.js.map

package/dist/state-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-diff.js","sourceRoot":"","sources":["../src/state-diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Compute a structural diff between two state snapshots and return it\n * in JSON-Patch-shaped form (RFC 6902 subset: `add`, `remove`,\n * `replace`).\n *\n * Why JSON Patch shape: LLMs see this exact format in their training\n * data — it's the standard for describing object mutations on the\n * wire. The agent learns the schema implicitly and can answer \"what\n * changed?\" in a sentence by reading the ops.\n *\n * Why not unified-diff or per-binding dirty masks: the dirty mask\n * tracks what bindings need re-rendering, which is a layout concern.\n * The agent wants to know what *values* changed, which is a state\n * concern. Dirty masks miss field-level resolution; per-path JSON\n * Patch gives it.\n *\n * Cost is O(state size) per dispatch. For typical app states (a few\n * KB) that's microseconds. Apps with very large states (collections\n * of thousands of items) should subscribe to specific slices via\n * `query_state` / `wait_for_change` instead of reading full diffs.\n *\n * Path escaping follows JSON Pointer (RFC 6901): `/` becomes `~1`,\n * `~` becomes `~0`. The escape happens per-segment.\n */\n\nexport type JsonPatchOp =\n  | { op: 'add'; path: string; value: unknown }\n  | { op: 'remove'; path: string }\n  | { op: 'replace'; path: string; value: unknown }\n\nexport type StateDiff = JsonPatchOp[]\n\n/**\n * Compute the diff. Order of operations: removes first, then adds,\n * then replaces. This is RFC 6902's recommended order — the receiver\n * can apply ops sequentially without ambiguity.\n *\n * The implementation is a simple recursive walk; collection diffs\n * are positional (index-based for arrays, key-based for objects)\n * rather than structural (no LCS). Apps that pass identity-stable\n * collections (`[...prev, item]`-style appends) get clean diffs;\n * apps that rebuild arrays from scratch get noisy ones — same\n * tradeoff a React reconciler makes, and the same fix (stable keys\n * + push-don't-rebuild updates) applies.\n */\nexport function computeStateDiff(prev: unknown, next: unknown): StateDiff {\n  const ops: JsonPatchOp[] = []\n  diffInto(prev, next, '', ops)\n  return ops\n}\n\nfunction diffInto(prev: unknown, next: unknown, basePath: string, ops: JsonPatchOp[]): void {\n  if (Object.is(prev, next)) return\n\n  // Either side null/undefined or non-object → straight replace at this path.\n  // (`null` is `typeof === 'object'`, so we test it explicitly.)\n  if (\n    prev === null ||\n    next === null ||\n    prev === undefined ||\n    next === undefined ||\n    typeof prev !== 'object' ||\n    typeof next !== 'object'\n  ) {\n    ops.push({ op: 'replace', path: basePath, value: next })\n    return\n  }\n\n  const prevIsArr = Array.isArray(prev)\n  const nextIsArr = Array.isArray(next)\n\n  // Type change (object↔array) — single replace at the path. Recursing\n  // into mismatched containers would emit a wall of incoherent ops.\n  if (prevIsArr !== nextIsArr) {\n    ops.push({ op: 'replace', path: basePath, value: next })\n    return\n  }\n\n  if (prevIsArr && nextIsArr) {\n    diffArray(prev, next, basePath, ops)\n    return\n  }\n\n  diffObject(prev as Record<string, unknown>, next as Record<string, unknown>, basePath, ops)\n}\n\nfunction diffArray(\n  prev: readonly unknown[],\n  next: readonly unknown[],\n  basePath: string,\n  ops: JsonPatchOp[],\n): void {\n  const minLen = Math.min(prev.length, next.length)\n  // Recurse into shared indices.\n  for (let i = 0; i < minLen; i++) {\n    diffInto(prev[i], next[i], `${basePath}/${i}`, ops)\n  }\n  // Excess elements: remove from the end (descending order so each\n  // index is still valid as we apply).\n  if (prev.length > next.length) {\n    for (let i = prev.length - 1; i >= next.length; i--) {\n      ops.push({ op: 'remove', path: `${basePath}/${i}` })\n    }\n  }\n  // New elements: add at the position they end up in. RFC 6902 allows\n  // a `-` index for \"append\" semantics, but explicit indices are easier\n  // for the LLM to reason about (\"alternative at index 8 was added\").\n  if (next.length > prev.length) {\n    for (let i = prev.length; i < next.length; i++) {\n      ops.push({ op: 'add', path: `${basePath}/${i}`, value: next[i] })\n    }\n  }\n}\n\nfunction diffObject(\n  prev: Record<string, unknown>,\n  next: Record<string, unknown>,\n  basePath: string,\n  ops: JsonPatchOp[],\n): void {\n  // Removes: keys that exist in prev but not next.\n  for (const k in prev) {\n    if (!(k in next)) {\n      ops.push({ op: 'remove', path: `${basePath}/${escapeSegment(k)}` })\n    }\n  }\n  // Adds + replaces: keys in next.\n  for (const k in next) {\n    const path = `${basePath}/${escapeSegment(k)}`\n    if (!(k in prev)) {\n      ops.push({ op: 'add', path, value: next[k] })\n    } else {\n      diffInto(prev[k], next[k], path, ops)\n    }\n  }\n}\n\n/**\n * Escape a single path segment per RFC 6901: `~` → `~0`, then `/` →\n * `~1`. Order matters; do `~` first so `/` substitution doesn't\n * double-escape an already-escaped tilde.\n */\nfunction escapeSegment(seg: string): string {\n  return seg.replace(/~/g, '~0').replace(/\\//g, '~1')\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llui/agent",
-  "version": "0.0.31",
+  "version": "0.0.34",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -27,19 +27,25 @@
     "./protocol": {
       "types": "./dist/protocol.d.ts",
       "import": "./dist/protocol.js"
+    },
+    "./codecs": {
+      "types": "./dist/codecs.d.ts",
+      "import": "./dist/codecs.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "ws": "^8.18.0",
-    "@llui/dom": "0.0.30",
-    "@llui/effects": "0.0.9"
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "@llui/dom": "^0.0.32"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@types/ws": "^8.5.13"
+    "@types/ws": "^8.5.13",
+    "@llui/dom": "0.0.32"
   },
   "description": "LLui Agent — LAP server + browser client runtime for driving LLui apps from LLM clients",
   "keywords": [