@harness-fe/runtime 3.1.0 → 3.3.0

package/dist/capture.d.ts

@@ -1,8 +1,19 @@
 /**
- * Console + network + error capture. Monkey-patches in place once on init.
+ * CaptureStore — thin adapter on top of `@harness-fe/sandbox`.
  *
- * Network capture covers fetch + XMLHttpRequest. Body capture is opt-in
- * per-request to keep memory bounded.
+ * Sandbox does the actual browser-API patching (fetch / xhr / ws / storage /
+ * navigation / console / errors / globals / indexeddb) and exposes a unified
+ * observer + interceptor surface. This module only:
+ *   1. Installs sandbox with the runtime's `onEvent` callback wired in.
+ *   2. Adapts each `SandboxEvent` into the harness-fe protocol shape
+ *      (`NetworkEntry` / `WsEntry` / `StorageEntry` / `ConsoleEntry` /
+ *      `ErrorEntry`) so the daemon's existing ingestion + tail tools keep
+ *      working unchanged.
+ *   3. Mirrors events into bounded `RingBuffer`s so the runtime's
+ *      `console.tail` / `network.tail` / `ws.tail` / `storage.tail` MCP tool
+ *      handlers have something to read.
+ *
+ * Identity / interceptor / reentry safety all live in sandbox.
  */
 import { RingBuffer } from './buffer.js';
 export declare class CaptureStore {
@@ -63,20 +74,45 @@ export declare class CaptureStore {
             stack?: string | undefined;
         } | undefined;
     }>;
-    private installed;
-    private fetchDispose?;
-    private xhrDispose?;
-    private wsDispose?;
-    private storageDispose?;
+    readonly navigation: RingBuffer<{
+        ts: number;
+        kind: "replace" | "push" | "pop" | "hash" | "assign";
+        url?: string | undefined;
+        state?: unknown;
+        replace?: boolean | undefined;
+        initiator?: {
+            stack?: string | undefined;
+        } | undefined;
+    }>;
+    readonly globals: RingBuffer<{
+        ts: number;
+        op: "set" | "get" | "delete";
+        key: string;
+        value?: unknown;
+        previousValue?: unknown;
+        initiator?: {
+            stack?: string | undefined;
+        } | undefined;
+    }>;
+    readonly indexeddb: RingBuffer<{
+        ts: number;
+        op: "open" | "clear" | "get" | "delete" | "put" | "add" | "getAll" | "cursor";
+        db?: string | undefined;
+        version?: number | undefined;
+        store?: string | undefined;
+        key?: unknown;
+        value?: unknown;
+        success?: boolean | undefined;
+        error?: string | undefined;
+        initiator?: {
+            stack?: string | undefined;
+        } | undefined;
+    }>;
+    private handle?;
     install(onEvent: (name: string, payload: unknown) => void, opts?: {
         daemonUrl?: string;
     }): void;
     dispose(): void;
-    private installConsole;
-    private installFetch;
-    private installXhr;
-    private installWs;
-    private installStorage;
-    private installErrors;
+    private adapt;
 }
 export declare function getCaptureStore(): CaptureStore;

package/dist/capture.js

@@ -1,134 +1,107 @@
 /**
- * Console + network + error capture. Monkey-patches in place once on init.
+ * CaptureStore — thin adapter on top of `@harness-fe/sandbox`.
  *
- * Network capture covers fetch + XMLHttpRequest. Body capture is opt-in
- * per-request to keep memory bounded.
+ * Sandbox does the actual browser-API patching (fetch / xhr / ws / storage /
+ * navigation / console / errors / globals / indexeddb) and exposes a unified
+ * observer + interceptor surface. This module only:
+ *   1. Installs sandbox with the runtime's `onEvent` callback wired in.
+ *   2. Adapts each `SandboxEvent` into the harness-fe protocol shape
+ *      (`NetworkEntry` / `WsEntry` / `StorageEntry` / `ConsoleEntry` /
+ *      `ErrorEntry`) so the daemon's existing ingestion + tail tools keep
+ *      working unchanged.
+ *   3. Mirrors events into bounded `RingBuffer`s so the runtime's
+ *      `console.tail` / `network.tail` / `ws.tail` / `storage.tail` MCP tool
+ *      handlers have something to read.
+ *
+ * Identity / interceptor / reentry safety all live in sandbox.
  */
+import { installSandbox, } from '@harness-fe/sandbox';
 import { RingBuffer } from './buffer.js';
-import { installFetchPatch } from './fetchPatch.js';
-import { installXhrPatch } from './xhrPatch.js';
-import { installWsPatch } from './wsPatch.js';
-import { installStoragePatch } from './storagePatch.js';
 const CONSOLE_CAP = 500;
 const NETWORK_CAP = 200;
 const ERROR_CAP = 200;
 const WS_CAP = 200;
 const STORAGE_CAP = 200;
+const NAVIGATION_CAP = 100;
+const GLOBALS_CAP = 200;
+const INDEXEDDB_CAP = 200;
 export class CaptureStore {
     console = new RingBuffer(CONSOLE_CAP);
     network = new RingBuffer(NETWORK_CAP);
     errors = new RingBuffer(ERROR_CAP);
     ws = new RingBuffer(WS_CAP);
     storage = new RingBuffer(STORAGE_CAP);
-    installed = false;
-    fetchDispose;
-    xhrDispose;
-    wsDispose;
-    storageDispose;
+    navigation = new RingBuffer(NAVIGATION_CAP);
+    globals = new RingBuffer(GLOBALS_CAP);
+    indexeddb = new RingBuffer(INDEXEDDB_CAP);
+    handle;
     install(onEvent, opts = {}) {
-        if (this.installed)
+        if (this.handle)
             return;
-        this.installed = true;
-        this.installConsole(onEvent);
-        this.installFetch(onEvent);
-        this.installXhr(onEvent);
-        this.installWs(onEvent, opts.daemonUrl);
-        this.installStorage(onEvent);
-        this.installErrors(onEvent);
+        const selfUrls = opts.daemonUrl ? [opts.daemonUrl] : undefined;
+        this.handle = installSandbox({
+            selfUrls,
+            onEvent: (e) => this.adapt(e, onEvent),
+        });
     }
     dispose() {
-        this.fetchDispose?.();
-        this.fetchDispose = undefined;
-        this.xhrDispose?.();
-        this.xhrDispose = undefined;
-        this.wsDispose?.();
-        this.wsDispose = undefined;
-        this.storageDispose?.();
-        this.storageDispose = undefined;
-        this.installed = false;
+        this.handle?.dispose();
+        this.handle = undefined;
     }
-    installConsole(onEvent) {
-        const methods = ['log', 'info', 'warn', 'error', 'debug'];
-        for (const level of methods) {
-            const original = console[level].bind(console);
-            console[level] = (...args) => {
-                const entry = {
-                    ts: Date.now(),
-                    level,
-                    args: args.map(safeClone),
-                };
-                this.console.push(entry);
-                onEvent('console', entry);
-                original(...args);
-            };
-        }
-    }
-    installFetch(onEvent) {
-        this.fetchDispose = installFetchPatch({
-            onEntry: (entry) => {
+    adapt(e, onEvent) {
+        switch (e.source) {
+            case 'fetch':
+            case 'xhr': {
+                const entry = adaptFetchLike(e);
                 this.network.push(entry);
                 onEvent('network', entry);
-            },
-        });
-    }
-    installXhr(onEvent) {
-        this.xhrDispose = installXhrPatch({
-            onEntry: (entry) => {
-                this.network.push(entry);
-                onEvent('network', entry);
-            },
-        });
-    }
-    installWs(onEvent, daemonUrl) {
-        // Add the daemon URL itself to the denylist so our own bridge
-        // connection isn't intercepted (otherwise every event we send
-        // would emit a `ws send` that loops back into the outbox).
-        const extra = [];
-        if (daemonUrl) {
-            const escaped = daemonUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            extra.push(new RegExp(`^${escaped}`));
-        }
-        this.wsDispose = installWsPatch({
-            denylist: extra.length > 0 ? [/\/__hfe\//, /sockjs-node/, ...extra] : undefined,
-            onEntry: (entry) => {
+                return;
+            }
+            case 'ws': {
+                const entry = adaptWs(e);
                 this.ws.push(entry);
                 onEvent('ws', entry);
-            },
-        });
-    }
-    installStorage(onEvent) {
-        this.storageDispose = installStoragePatch({
-            onEntry: (entry) => {
-                this.storage.push(entry);
-                onEvent('storage', entry);
-            },
-        });
-    }
-    installErrors(onEvent) {
-        if (typeof window === 'undefined')
-            return;
-        window.addEventListener('error', (e) => {
-            const entry = {
-                ts: Date.now(),
-                message: e.message,
-                stack: e.error?.stack,
-                source: e.filename ? `${e.filename}:${e.lineno}:${e.colno}` : undefined,
-            };
-            this.errors.push(entry);
-            onEvent('error', entry);
-        });
-        window.addEventListener('unhandledrejection', (e) => {
-            const reason = e.reason;
-            const message = reason instanceof Error ? reason.message : String(reason ?? 'unhandled rejection');
-            const stack = reason instanceof Error ? reason.stack : undefined;
-            const entry = {
-                ts: Date.now(),
-                message: `Unhandled: ${message}`,
-                stack,
-            };
-            this.errors.push(entry);
-            onEvent('error', entry);
-        });
+                return;
+            }
+            case 'storage': {
+                const entry = adaptStorage(e);
+                if (entry) {
+                    this.storage.push(entry);
+                    onEvent('storage', entry);
+                }
+                return;
+            }
+            case 'console': {
+                const entry = adaptConsole(e);
+                this.console.push(entry);
+                onEvent('console', entry);
+                return;
+            }
+            case 'errors': {
+                const entry = adaptError(e);
+                this.errors.push(entry);
+                onEvent('error', entry);
+                return;
+            }
+            case 'navigation': {
+                const entry = adaptNavigation(e);
+                this.navigation.push(entry);
+                onEvent('navigation', entry);
+                return;
+            }
+            case 'globals': {
+                const entry = adaptGlobals(e);
+                this.globals.push(entry);
+                onEvent('globals', entry);
+                return;
+            }
+            case 'indexeddb': {
+                const entry = adaptIndexedDb(e);
+                this.indexeddb.push(entry);
+                onEvent('indexeddb', entry);
+                return;
+            }
+        }
     }
 }
 let captureStoreSingleton;
@@ -136,16 +109,123 @@ export function getCaptureStore() {
     captureStoreSingleton ??= new CaptureStore();
     return captureStoreSingleton;
 }
-function safeClone(value) {
-    if (value === null)
-        return null;
-    if (typeof value === 'object') {
-        try {
-            return JSON.parse(JSON.stringify(value));
-        }
-        catch {
-            return String(value);
-        }
+// ────────────────────────────────────────────────────────────────────
+// SandboxEvent → harness-fe protocol entry adapters
+// ────────────────────────────────────────────────────────────────────
+function adaptFetchLike(e) {
+    const d = e.data;
+    if (e.kind === 'req') {
+        const r = d;
+        return {
+            ts: e.ts,
+            id: r.id,
+            phase: 'req',
+            method: r.method,
+            url: r.url,
+            requestHeaders: r.headers,
+            requestBody: r.body,
+            requestBodyTruncated: r.bodyTruncated || undefined,
+            initiator: e.initiator,
+        };
     }
-    return value;
+    const r = d;
+    return {
+        ts: e.ts,
+        id: r.id,
+        phase: 'res',
+        method: r.method,
+        url: r.url,
+        status: r.status,
+        durationMs: r.durationMs,
+        responseHeaders: r.headers,
+        responseBody: r.body,
+        responseBodyTruncated: r.bodyTruncated || undefined,
+        error: r.error,
+        initiator: e.initiator,
+    };
+}
+function adaptWs(e) {
+    const d = e.data;
+    return {
+        ts: e.ts,
+        id: d.id,
+        phase: d.phase,
+        url: d.url,
+        protocols: d.protocols,
+        payload: d.payload,
+        payloadTruncated: d.payloadTruncated,
+        code: d.code,
+        reason: d.reason,
+        wasClean: d.wasClean,
+        initiator: e.initiator,
+    };
+}
+function adaptStorage(e) {
+    const d = e.data;
+    // Sandbox emits a 'get' op; harness-fe protocol storage only models set/remove/clear.
+    if (d.op === 'get')
+        return null;
+    return {
+        ts: e.ts,
+        op: d.op,
+        which: d.which,
+        key: d.key,
+        value: d.value,
+        crossTab: d.crossTab,
+        initiator: e.initiator,
+    };
+}
+function adaptConsole(e) {
+    const d = e.data;
+    return {
+        ts: e.ts,
+        level: d.level,
+        args: d.args,
+    };
+}
+function adaptError(e) {
+    const d = e.data;
+    return {
+        ts: e.ts,
+        message: d.message,
+        stack: d.stack,
+        source: d.source,
+    };
+}
+function adaptNavigation(e) {
+    const d = e.data;
+    return {
+        ts: e.ts,
+        kind: d.kind,
+        url: d.url,
+        state: d.state,
+        replace: d.replace,
+        initiator: e.initiator,
+    };
+}
+function adaptGlobals(e) {
+    const d = e.data;
+    return {
+        ts: e.ts,
+        op: d.op,
+        key: d.key,
+        value: d.value,
+        previousValue: d.previousValue,
+        initiator: e.initiator,
+    };
+}
+function adaptIndexedDb(e) {
+    const d = e.data;
+    return {
+        ts: e.ts,
+        op: d.op,
+        db: d.db,
+        version: d.version,
+        store: d.store,
+        key: d.key,
+        value: d.value,
+        success: d.success,
+        error: d.error,
+        initiator: e.initiator,
+    };
 }

package/dist/client.d.ts

@@ -28,6 +28,13 @@ export interface ClientOptions {
      * by visitorId). Propagated by HarnessScript via window.__HARNESS_FE__.userId.
      */
     userId?: string;
+    /**
+     * How often (in ms) rrweb should emit a fresh FullSnapshot baseline.
+     * Defaults to 30 minutes. Set to 0 to disable periodic baselines (the
+     * recorder still emits one at start() and one per ws reconnect).
+     * See {@link RrwebRecorderOptions.checkoutEveryNms} for the trade-off.
+     */
+    rrwebCheckoutEveryNms?: number;
 }
 export { tryInheritFromParent } from './parent-inherit.js';
 export type { ParentInheritance } from './parent-inherit.js';

package/dist/client.js

@@ -90,7 +90,10 @@ export class RuntimeClient {
     }
     pageLoadSent = false;
     ctx = { capture: getCaptureStore() };
-    recorder = new RrwebRecorder((chunk) => this.sendEvent(EVENT_NAME.RRWEB, chunk));
+    // Initialized in constructor (parameter property `opts` isn't readable at
+    // class-field-initializer time — field initializers run before parameter
+    // property assignment).
+    recorder;
     reconnectAttempts = 0;
     closed = false;
     static MAX_OUTBOX_FRAMES = 500;
@@ -109,6 +112,7 @@ export class RuntimeClient {
         const inheritedVisitor = tryInheritVisitorFromParent();
         this.visitorId = inheritedVisitor ?? getOrCreateVisitorId();
         publishVisitorIdToWindow(this.visitorId);
+        this.recorder = new RrwebRecorder((chunk) => this.sendEvent(EVENT_NAME.RRWEB, chunk), { checkoutEveryNms: opts.rrwebCheckoutEveryNms });
     }
     start() {
         const daemonUrl = this.opts.mcpUrl ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}`;

package/dist/commands.js

@@ -382,6 +382,39 @@ export const commandHandlers = {
                 return JSON.stringify({ op: e.op, which: e.which, key: e.key, value: e.value });
             }) };
     },
+    [COMMAND.NAVIGATION_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        const all = ctx.capture.navigation.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+                if (args.kind && e.kind !== args.kind)
+                    return undefined;
+                return JSON.stringify({ kind: e.kind, url: e.url, replace: e.replace });
+            }) };
+    },
+    [COMMAND.GLOBALS_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        const all = ctx.capture.globals.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+                if (args.op && e.op !== args.op)
+                    return undefined;
+                if (args.key && e.key !== args.key)
+                    return undefined;
+                return JSON.stringify({ op: e.op, key: e.key, value: e.value });
+            }) };
+    },
+    [COMMAND.INDEXEDDB_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        const all = ctx.capture.indexeddb.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+                if (args.op && e.op !== args.op)
+                    return undefined;
+                if (args.store && e.store !== args.store)
+                    return undefined;
+                if (args.db && e.db !== args.db)
+                    return undefined;
+                return JSON.stringify({ op: e.op, store: e.store, key: e.key });
+            }) };
+    },
 };
 /**
  * Apply caller-supplied filtering to a tail() result. `pickHaystack` returns

package/dist/recording.d.ts

@@ -1,12 +1,27 @@
 import type { RrwebChunkPayload } from '@harness-fe/protocol';
 export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js';
+export interface RrwebRecorderOptions {
+    /**
+     * Force rrweb to emit a fresh FullSnapshot every N milliseconds. Caps how
+     * stale the most recent baseline can be, so window replays mid-session
+     * don't have to roll forward from a baseline that's potentially hours old.
+     *
+     * Set to `0` (or a negative number) to disable periodic baselines and
+     * rely solely on the start() baseline + reconnect baselines. Useful for
+     * extremely bandwidth-constrained deployments.
+     *
+     * @default 30 * 60 * 1000  (30 minutes)
+     */
+    checkoutEveryNms?: number;
+}
 export declare class RrwebRecorder {
     private readonly onChunk;
+    private readonly opts;
     private stopRecording?;
     private flushTimer?;
     private chunkSeq;
     private buffer;
-    constructor(onChunk: (chunk: RrwebChunkPayload) => void);
+    constructor(onChunk: (chunk: RrwebChunkPayload) => void, opts?: RrwebRecorderOptions);
     start(): void;
     stop(): void;
     /**

package/dist/recording.js

@@ -2,24 +2,38 @@ import { record } from 'rrweb';
 export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js';
 const FLUSH_MS = 5_000;
 const MAX_EVENTS = 200;
+// Default periodic-baseline cadence. Long-running sessions otherwise rely on
+// a single FullSnapshot at start() + one per ws reconnect, which makes
+// mid-session window replays expensive (rrweb has to roll forward all
+// incremental events back to the original baseline) and leaves a window of
+// vulnerability if the original baseline is ever evicted from the outbox.
+// 30 min is a deliberate middle ground: ~16 baselines per 8h session at
+// ~500KB each ≈ 8MB extra storage, which is acceptable for a dev tool.
+const DEFAULT_CHECKOUT_EVERY_MS = 30 * 60 * 1000;
 export class RrwebRecorder {
     onChunk;
+    opts;
     stopRecording;
     flushTimer;
     chunkSeq = 0;
     buffer = [];
-    constructor(onChunk) {
+    constructor(onChunk, opts = {}) {
         this.onChunk = onChunk;
+        this.opts = opts;
     }
     start() {
         if (this.stopRecording)
             return;
+        const checkoutEveryNms = this.opts.checkoutEveryNms ?? DEFAULT_CHECKOUT_EVERY_MS;
+        // rrweb interprets `checkoutEveryNms` falsy / undefined as "off".
+        // Pass undefined when disabled so we get the native off-path.
         this.stopRecording = record({
             emit: (event) => this.push(event),
             inlineImages: false,
             recordCanvas: false,
             collectFonts: false,
             maskAllInputs: false,
+            checkoutEveryNms: checkoutEveryNms > 0 ? checkoutEveryNms : undefined,
         });
         this.flushTimer = window.setInterval(() => this.flush(), FLUSH_MS);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/runtime",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Browser-side SDK injected into the dev page. Connects to the MCP server via WebSocket and executes commands.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,8 @@
   "dependencies": {
     "@zumer/snapdom": "^2.12.0",
     "rrweb": "2.0.0-alpha.4",
-    "@harness-fe/protocol": "3.1.0"
+    "@harness-fe/protocol": "3.2.0",
+    "@harness-fe/sandbox": "^3.2.0"
   },
   "devDependencies": {
     "happy-dom": "^20.9.0",