@harness-fe/runtime 3.0.1 → 3.2.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 {
@@ -27,6 +38,9 @@ export declare class CaptureStore {
         requestBodyTruncated?: boolean | undefined;
         responseBodyTruncated?: boolean | undefined;
         error?: string | undefined;
+        initiator?: {
+            stack?: string | undefined;
+        } | undefined;
     }>;
     readonly errors: RingBuffer<{
         ts: number;
@@ -34,14 +48,71 @@ export declare class CaptureStore {
         stack?: string | undefined;
         source?: string | undefined;
     }>;
-    private installed;
-    private fetchDispose?;
-    private xhrDispose?;
-    install(onEvent: (name: string, payload: unknown) => void): void;
+    readonly ws: RingBuffer<{
+        ts: number;
+        id: string;
+        phase: "open" | "send" | "recv" | "close";
+        url: string;
+        protocols?: string[] | undefined;
+        payload?: unknown;
+        payloadTruncated?: boolean | undefined;
+        code?: number | undefined;
+        reason?: string | undefined;
+        wasClean?: boolean | undefined;
+        initiator?: {
+            stack?: string | undefined;
+        } | undefined;
+    }>;
+    readonly storage: RingBuffer<{
+        op: "set" | "remove" | "clear";
+        which: "local" | "session" | "cookie";
+        ts: number;
+        key?: string | undefined;
+        value?: string | undefined;
+        crossTab?: boolean | undefined;
+        initiator?: {
+            stack?: string | undefined;
+        } | undefined;
+    }>;
+    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 installErrors;
+    private adapt;
 }
 export declare function getCaptureStore(): CaptureStore;

package/dist/capture.js

@@ -1,112 +1,231 @@
 /**
- * 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';
 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);
-    installed = false;
-    fetchDispose;
-    xhrDispose;
-    install(onEvent) {
-        if (this.installed)
+    ws = new RingBuffer(WS_CAP);
+    storage = new RingBuffer(STORAGE_CAP);
+    navigation = new RingBuffer(NAVIGATION_CAP);
+    globals = new RingBuffer(GLOBALS_CAP);
+    indexeddb = new RingBuffer(INDEXEDDB_CAP);
+    handle;
+    install(onEvent, opts = {}) {
+        if (this.handle)
             return;
-        this.installed = true;
-        this.installConsole(onEvent);
-        this.installFetch(onEvent);
-        this.installXhr(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.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),
-                };
+    adapt(e, onEvent) {
+        switch (e.source) {
+            case 'fetch':
+            case 'xhr': {
+                const entry = adaptFetchLike(e);
+                this.network.push(entry);
+                onEvent('network', entry);
+                return;
+            }
+            case 'ws': {
+                const entry = adaptWs(e);
+                this.ws.push(entry);
+                onEvent('ws', 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);
-                original(...args);
-            };
+                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;
+            }
         }
     }
-    installFetch(onEvent) {
-        this.fetchDispose = installFetchPatch({
-            onEntry: (entry) => {
-                this.network.push(entry);
-                onEvent('network', entry);
-            },
-        });
-    }
-    installXhr(onEvent) {
-        this.xhrDispose = installXhrPatch({
-            onEntry: (entry) => {
-                this.network.push(entry);
-                onEvent('network', 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);
-        });
-    }
 }
 let captureStoreSingleton;
 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.js

@@ -111,7 +111,8 @@ export class RuntimeClient {
         publishVisitorIdToWindow(this.visitorId);
     }
     start() {
-        this.ctx.capture.install((name, payload) => this.sendEvent(name, payload));
+        const daemonUrl = this.opts.mcpUrl ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}`;
+        this.ctx.capture.install((name, payload) => this.sendEvent(name, payload), { daemonUrl });
         this.recorder.start();
         this.connect();
     }

package/dist/commands.js

@@ -276,17 +276,192 @@ export const commandHandlers = {
     },
     [COMMAND.CONSOLE_TAIL]: async (raw, ctx) => {
         const args = raw;
-        return { entries: ctx.capture.console.tail(args.n) };
+        const all = ctx.capture.console.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+                if (args.level && e.level !== args.level)
+                    return undefined;
+                return JSON.stringify({ level: e.level, args: e.args });
+            }) };
     },
     [COMMAND.NETWORK_TAIL]: async (raw, ctx) => {
         const args = raw;
-        return { entries: ctx.capture.network.tail(args.n) };
+        const all = ctx.capture.network.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+                if (args.urlContains && !e.url.includes(args.urlContains))
+                    return undefined;
+                if (args.method && e.method.toUpperCase() !== args.method.toUpperCase())
+                    return undefined;
+                if (args.statusCode !== undefined && e.status !== args.statusCode)
+                    return undefined;
+                return JSON.stringify({ url: e.url, method: e.method, requestBody: e.requestBody, responseBody: e.responseBody });
+            }) };
     },
     [COMMAND.ERRORS_TAIL]: async (raw, ctx) => {
         const args = raw;
-        return { entries: ctx.capture.errors.tail(args.n) };
+        const all = ctx.capture.errors.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => JSON.stringify({ message: e.message, stack: e.stack, source: e.source })) };
+    },
+    [COMMAND.WS_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        const all = ctx.capture.ws.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+                if (args.phase && e.phase !== args.phase)
+                    return undefined;
+                return JSON.stringify({ url: e.url, payload: e.payload, reason: e.reason });
+            }) };
+    },
+    [COMMAND.NETWORK_WAIT_FOR]: async (raw, ctx) => {
+        const args = raw;
+        const timeoutMs = args.timeoutMs ?? 10_000;
+        const deadline = Date.now() + timeoutMs;
+        const regex = args.urlRegex ? safeRegex(args.urlRegex) : undefined;
+        // Anchor on the existing buffer head so we only consider new requests
+        // (otherwise an old matching entry would resolve immediately).
+        const baselineLen = ctx.capture.network.size();
+        while (Date.now() < deadline) {
+            const all = ctx.capture.network.tail(500);
+            const newOnes = all.slice(Math.max(0, all.length - (ctx.capture.network.size() - baselineLen)));
+            for (const e of newOnes) {
+                if (args.urlContains && !e.url.includes(args.urlContains))
+                    continue;
+                if (regex && !regex.test(e.url))
+                    continue;
+                if (args.method && e.method.toUpperCase() !== args.method.toUpperCase())
+                    continue;
+                if (args.statusCode !== undefined && e.status !== args.statusCode)
+                    continue;
+                return { ok: true, entry: e, after: Date.now() };
+            }
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        throw new Error(`network.wait_for: no matching request within ${timeoutMs}ms`);
+    },
+    [COMMAND.NETWORK_WAIT_FOR_IDLE]: async (raw, ctx) => {
+        const args = raw;
+        const idleMs = args.idleMs ?? 500;
+        const timeoutMs = args.timeoutMs ?? 10_000;
+        const deadline = Date.now() + timeoutMs;
+        let lastSize = ctx.capture.network.size();
+        let stableSince = Date.now();
+        while (Date.now() < deadline) {
+            const currentSize = ctx.capture.network.size();
+            if (currentSize !== lastSize) {
+                lastSize = currentSize;
+                stableSince = Date.now();
+            }
+            else if (Date.now() - stableSince >= idleMs) {
+                return { ok: true, idleFor: Date.now() - stableSince, after: Date.now() };
+            }
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        throw new Error(`network.wait_for_idle: never quiet for ${idleMs}ms within ${timeoutMs}ms`);
+    },
+    [COMMAND.NETWORK_GET]: async (raw, ctx) => {
+        const args = raw;
+        // Return both req + res entries for this id (one or both may exist).
+        const all = ctx.capture.network.tail(200);
+        const matches = all.filter((e) => e.id === args.reqId);
+        return { entries: matches, found: matches.length > 0 };
+    },
+    [COMMAND.WS_GET]: async (raw, ctx) => {
+        const args = raw;
+        const all = ctx.capture.ws.tail(200);
+        const matches = all.filter((e) => e.id === args.wsId);
+        return { entries: matches, found: matches.length > 0 };
+    },
+    [COMMAND.STORAGE_TAIL]: async (raw, ctx) => {
+        const args = raw;
+        const all = ctx.capture.storage.tail(args.n ?? 20);
+        return { entries: filterTail(all, args, (e) => {
+                if (args.which && e.which !== args.which)
+                    return undefined;
+                if (args.op && e.op !== args.op)
+                    return undefined;
+                if (args.key && e.key !== args.key)
+                    return undefined;
+                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
+ * the string to match against (or `undefined` to drop the entry due to a
+ * type-specific narrow like `level` / `urlContains`). The shared `filter`
+ * string then runs as substring (default) or regex against the haystack.
+ */
+function safeRegex(source) {
+    try {
+        return new RegExp(source, 'i');
+    }
+    catch {
+        return undefined;
+    }
+}
+function filterTail(items, args, pickHaystack) {
+    const filter = args.filter?.trim();
+    const useRegex = args.match === 'regex';
+    let regex;
+    if (filter && useRegex) {
+        try {
+            regex = new RegExp(filter, 'i');
+        }
+        catch {
+            // Invalid regex: fall back to substring match rather than throwing.
+            regex = undefined;
+        }
+    }
+    const out = [];
+    for (const item of items) {
+        const haystack = pickHaystack(item);
+        if (haystack === undefined)
+            continue;
+        if (filter) {
+            if (regex) {
+                if (!regex.test(haystack))
+                    continue;
+            }
+            else {
+                if (!haystack.toLowerCase().includes(filter.toLowerCase()))
+                    continue;
+            }
+        }
+        out.push(item);
+    }
+    return out;
+}
 function truncate(s, n) {
     if (s.length <= n)
         return s;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/runtime",
-  "version": "3.0.1",
+  "version": "3.2.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.0.0"
+    "@harness-fe/protocol": "3.2.0",
+    "@harness-fe/sandbox": "^3.2.0"
   },
   "devDependencies": {
     "happy-dom": "^20.9.0",