@harness-fe/runtime 3.1.0 → 3.2.0

package/src/capture.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 type {
@@ -11,18 +22,34 @@ import type {
     NetworkEntry,
     WsEntry,
     StorageEntry,
+    NavigationEntry,
+    GlobalsEntry,
+    IndexedDbEntry,
 } from '@harness-fe/protocol';
+import {
+    installSandbox,
+    type SandboxEvent,
+    type SandboxHandle,
+    type FetchReqObservation,
+    type FetchResObservation,
+    type WsObservation,
+    type StorageObservation,
+    type ConsoleObservation,
+    type ErrorObservation,
+    type NavigationObservation,
+    type GlobalsObservation,
+    type IndexedDbObservation,
+} 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 {
     readonly console = new RingBuffer<ConsoleEntry>(CONSOLE_CAP);
@@ -30,126 +57,83 @@ export class CaptureStore {
     readonly errors = new RingBuffer<ErrorEntry>(ERROR_CAP);
     readonly ws = new RingBuffer<WsEntry>(WS_CAP);
     readonly storage = new RingBuffer<StorageEntry>(STORAGE_CAP);
+    readonly navigation = new RingBuffer<NavigationEntry>(NAVIGATION_CAP);
+    readonly globals = new RingBuffer<GlobalsEntry>(GLOBALS_CAP);
+    readonly indexeddb = new RingBuffer<IndexedDbEntry>(INDEXEDDB_CAP);
 
-    private installed = false;
-    private fetchDispose?: () => void;
-    private xhrDispose?: () => void;
-    private wsDispose?: () => void;
-    private storageDispose?: () => void;
+    private handle?: SandboxHandle;
 
     install(
         onEvent: (name: string, payload: unknown) => void,
         opts: { daemonUrl?: string } = {},
     ): void {
-        if (this.installed) return;
-        this.installed = true;
-        this.installConsole(onEvent);
-        this.installFetch(onEvent);
-        this.installXhr(onEvent);
-        this.installWs(onEvent, opts.daemonUrl);
-        this.installStorage(onEvent);
-        this.installErrors(onEvent);
+        if (this.handle) return;
+        const selfUrls = opts.daemonUrl ? [opts.daemonUrl] : undefined;
+        this.handle = installSandbox({
+            selfUrls,
+            onEvent: (e) => this.adapt(e, onEvent),
+        });
     }
 
     dispose(): void {
-        this.fetchDispose?.();
-        this.fetchDispose = undefined;
-        this.xhrDispose?.();
-        this.xhrDispose = undefined;
-        this.wsDispose?.();
-        this.wsDispose = undefined;
-        this.storageDispose?.();
-        this.storageDispose = undefined;
-        this.installed = false;
-    }
-
-    private installConsole(onEvent: (name: string, payload: unknown) => void): void {
-        const methods: Array<ConsoleEntry['level']> = ['log', 'info', 'warn', 'error', 'debug'];
-        for (const level of methods) {
-            const original = console[level].bind(console);
-            console[level] = (...args: unknown[]) => {
-                const entry: ConsoleEntry = {
-                    ts: Date.now(),
-                    level,
-                    args: args.map(safeClone),
-                };
-                this.console.push(entry);
-                onEvent('console', entry);
-                original(...args);
-            };
-        }
-    }
-
-    private installFetch(onEvent: (name: string, payload: unknown) => void): void {
-        this.fetchDispose = installFetchPatch({
-            onEntry: (entry) => {
-                this.network.push(entry);
-                onEvent('network', entry);
-            },
-        });
+        this.handle?.dispose();
+        this.handle = undefined;
     }
 
-    private installXhr(onEvent: (name: string, payload: unknown) => void): void {
-        this.xhrDispose = installXhrPatch({
-            onEntry: (entry) => {
+    private adapt(e: SandboxEvent, onEvent: (name: string, payload: unknown) => void): void {
+        switch (e.source) {
+            case 'fetch':
+            case 'xhr': {
+                const entry = adaptFetchLike(e);
                 this.network.push(entry);
                 onEvent('network', entry);
-            },
-        });
-    }
-
-    private installWs(onEvent: (name: string, payload: unknown) => void, daemonUrl?: string): void {
-        // 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: RegExp[] = [];
-        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);
-            },
-        });
-    }
-
-    private installStorage(onEvent: (name: string, payload: unknown) => void): void {
-        this.storageDispose = installStoragePatch({
-            onEntry: (entry) => {
-                this.storage.push(entry);
-                onEvent('storage', entry);
-            },
-        });
-    }
-
-    private installErrors(onEvent: (name: string, payload: unknown) => void): void {
-        if (typeof window === 'undefined') return;
-        window.addEventListener('error', (e: ErrorEvent) => {
-            const entry: ErrorEntry = {
-                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: PromiseRejectionEvent) => {
-            const reason: unknown = e.reason;
-            const message =
-                reason instanceof Error ? reason.message : String(reason ?? 'unhandled rejection');
-            const stack = reason instanceof Error ? reason.stack : undefined;
-            const entry: ErrorEntry = {
-                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;
+            }
+        }
     }
 }
 
@@ -159,14 +143,130 @@ export function getCaptureStore(): CaptureStore {
     return captureStoreSingleton;
 }
 
-function safeClone(value: unknown): unknown {
-    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: SandboxEvent & { source: 'fetch' | 'xhr' }): NetworkEntry {
+    const d = e.data as FetchReqObservation | FetchResObservation;
+    if (e.kind === 'req') {
+        const r = d as FetchReqObservation;
+        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 as FetchResObservation;
+    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: SandboxEvent & { source: 'ws' }): WsEntry {
+    const d = e.data as WsObservation;
+    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: SandboxEvent & { source: 'storage' }): StorageEntry | null {
+    const d = e.data as StorageObservation;
+    // 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: SandboxEvent & { source: 'console' }): ConsoleEntry {
+    const d = e.data as ConsoleObservation;
+    return {
+        ts: e.ts,
+        level: d.level,
+        args: d.args,
+    };
+}
+
+function adaptError(e: SandboxEvent & { source: 'errors' }): ErrorEntry {
+    const d = e.data as ErrorObservation;
+    return {
+        ts: e.ts,
+        message: d.message,
+        stack: d.stack,
+        source: d.source,
+    };
+}
+
+function adaptNavigation(e: SandboxEvent & { source: 'navigation' }): NavigationEntry {
+    const d = e.data as NavigationObservation;
+    return {
+        ts: e.ts,
+        kind: d.kind,
+        url: d.url,
+        state: d.state,
+        replace: d.replace,
+        initiator: e.initiator,
+    };
+}
+
+function adaptGlobals(e: SandboxEvent & { source: 'globals' }): GlobalsEntry {
+    const d = e.data as GlobalsObservation;
+    return {
+        ts: e.ts,
+        op: d.op,
+        key: d.key,
+        value: d.value,
+        previousValue: d.previousValue,
+        initiator: e.initiator,
+    };
+}
+
+function adaptIndexedDb(e: SandboxEvent & { source: 'indexeddb' }): IndexedDbEntry {
+    const d = e.data as IndexedDbObservation;
+    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/src/commands.ts

@@ -423,6 +423,36 @@ export const commandHandlers: Record<string, CommandHandler> = {
             return JSON.stringify({ op: e.op, which: e.which, key: e.key, value: e.value });
         }) };
     },
+
+    [COMMAND.NAVIGATION_TAIL]: async (raw, ctx) => {
+        const args = raw as TailArgs & { kind?: string };
+        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 as TailArgs & { op?: string; key?: string };
+        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 as TailArgs & { op?: string; store?: string; db?: string };
+        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 });
+        }) };
+    },
 };
 
 interface TailArgs {

package/src/runtimeClient.e2e.test.ts

@@ -42,6 +42,20 @@ interface Env {
 
 let env: Env | undefined;
 
+async function rmDirWithRetry(dir: string, attempts = 5): Promise<void> {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            return;
+        } catch (err) {
+            const code = (err as NodeJS.ErrnoException).code;
+            if (code !== 'ENOTEMPTY' && code !== 'EBUSY' && code !== 'EPERM') throw err;
+            if (i === attempts - 1) throw err;
+            await new Promise((r) => setTimeout(r, 20 * (i + 1)));
+        }
+    }
+}
+
 async function setup(): Promise<Env> {
     const dir = mkdtempSync(join(tmpdir(), 'harness-rt-e2e-'));
     const store = new JsonlStore(dir);
@@ -85,8 +99,12 @@ afterEach(async () => {
     if (!env) return;
     env.client.stop();
     await env.bridge.stop();
-    env.store.close();
-    rmSync(env.dir, { recursive: true, force: true });
+    // close() drains the async write queue — must await, else rmSync races
+    // file writes and the dir-recursive-rm trips ENOTEMPTY on Linux CI.
+    await env.store.close();
+    // Even after drain, Node's directory cache can lag by a tick on Linux —
+    // retry-with-backoff handles the residual race deterministically.
+    await rmDirWithRetry(env.dir);
     // Reset capture singleton so subsequent tests get a clean install.
     const cap = getCaptureStore();
     cap.dispose();

package/dist/fetchPatch.d.ts

@@ -1,39 +0,0 @@
-/**
- * fetch monkey-patch — captures URL/method/headers/body for request and
- * response, including streaming SSE responses, without changing
- * business-observable fetch behavior.
- *
- * Safety contract (do not weaken without updating the spec):
- *  1. Identity-preserving: replacement is a named `fetch`, with
- *     defineProperty'd name/length/toString so library fingerprint checks
- *     still pass. Response / Request instances are NOT wrapped.
- *  2. Error-isolated: capture failures are swallowed via `safeEmit`; they
- *     NEVER propagate to business code.
- *  3. No timing or value change: the original Promise is returned to the
- *     caller unchanged. body capture reads `response.clone()` on a side
- *     branch — the business path retains an untouched stream.
- *  4. Self-traffic guard: requests carrying `init.__hfeInternal === true`
- *     short-circuit to the original fetch. A URL denylist also skips HMR /
- *     dev-server traffic to prevent capture feedback loops.
- *  5. Bounded memory: bodies are capped at BODY_CAP per request. SSE
- *     streams stop accumulating and `cancel()` the cloned reader once
- *     the cap is hit.
- *
- * The patch is idempotent (re-install is a no-op) and returns a dispose
- * function that restores the original `window.fetch`.
- */
-import type { NetworkEntry } from '@harness-fe/protocol';
-export interface FetchPatchOptions {
-    /** Called once for each emitted record (request and response are separate calls). */
-    onEntry: (entry: NetworkEntry) => void;
-    /** Per-body byte cap. Default 256 KB. */
-    bodyCap?: number;
-    /** URL patterns to skip capture entirely. */
-    denylist?: RegExp[];
-}
-/**
- * Install the fetch patch. Returns a dispose function that restores the
- * original window.fetch. Safe to call multiple times (subsequent calls
- * are no-ops while a patch is active).
- */
-export declare function installFetchPatch(opts: FetchPatchOptions): () => void;