@harness-fe/runtime 3.0.1

package/dist/xhrPatch.js

@@ -0,0 +1,269 @@
+/**
+ * XMLHttpRequest monkey-patch — captures URL/method/headers/body for
+ * request and response WITHOUT replacing the XMLHttpRequest constructor.
+ *
+ * The previous implementation wrapped `window.XMLHttpRequest` with a new
+ * constructor, which broke `xhr instanceof XMLHttpRequest` checks in
+ * business code. This patch attaches per-instance metadata via a
+ * non-enumerable Symbol key and overrides only prototype methods, leaving
+ * the constructor and prototype chain native.
+ *
+ * Capture rules mirror fetchPatch.ts:
+ *  - 256 KB body cap with content-type routing (json / text / binary)
+ *  - Sensitive header redaction (Authorization / Cookie / x-api-key / x-auth-*)
+ *  - Two events per request keyed by a shared `id` (`phase: 'req' | 'res'`)
+ *  - Errors inside capture are swallowed via `safeEmit`
+ *  - `__hfeInternal` opt-out via a magic header `x-hfe-internal: 1`
+ *    (XHR has no init-style options bag like fetch)
+ *  - Idempotent install + dispose() restores original prototype methods
+ */
+const DEFAULT_BODY_CAP = 256 * 1024;
+const PATCHED_FLAG = '__hfeXhrPatched';
+const META_KEY = Symbol.for('@harness-fe/xhr-meta');
+const INTERNAL_HEADER = 'x-hfe-internal';
+const SENSITIVE_HEADER = /^(authorization|cookie|x-api-key|x-auth-.+)$/i;
+export function installXhrPatch(opts) {
+    if (typeof XMLHttpRequest === 'undefined')
+        return () => { };
+    const proto = XMLHttpRequest.prototype;
+    if (proto[PATCHED_FLAG])
+        return () => { };
+    const bodyCap = opts.bodyCap ?? DEFAULT_BODY_CAP;
+    const denylist = opts.denylist ?? [];
+    const emit = (entry) => safeEmit(opts.onEntry, entry);
+    const origOpen = proto.open;
+    const origSetHeader = proto.setRequestHeader;
+    const origSend = proto.send;
+    const patchedOpen = function open(method, url, ...rest) {
+        const meta = {
+            id: generateId(),
+            method,
+            url: typeof url === 'string' ? url : url.toString(),
+            headers: {},
+            startedAt: 0,
+            startedTs: 0,
+            bodyCap,
+            internal: false,
+            skipped: denylist.some((re) => re.test(typeof url === 'string' ? url : url.toString())),
+            reqEmitted: false,
+        };
+        this[META_KEY] = meta;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return origOpen.call(this, method, url, ...rest);
+    };
+    const patchedSetHeader = function setRequestHeader(name, value) {
+        const meta = this[META_KEY];
+        if (meta) {
+            if (name.toLowerCase() === INTERNAL_HEADER) {
+                meta.internal = true;
+            }
+            else {
+                meta.headers[name] = value;
+            }
+        }
+        // Do NOT forward the internal sentinel to the server.
+        if (name.toLowerCase() === INTERNAL_HEADER)
+            return;
+        return origSetHeader.call(this, name, value);
+    };
+    const patchedSend = function send(body) {
+        const meta = this[META_KEY];
+        if (!meta || meta.internal || meta.skipped) {
+            return origSend.call(this, body ?? null);
+        }
+        meta.startedAt = performance.now();
+        meta.startedTs = Date.now();
+        // Emit req eagerly with headers; body added on second emit after
+        // serialization (mirrors fetchPatch behavior).
+        const reqRecord = {
+            ts: meta.startedTs,
+            id: meta.id,
+            phase: 'req',
+            method: meta.method,
+            url: meta.url,
+            requestHeaders: redactHeaders(meta.headers),
+        };
+        emit(reqRecord);
+        meta.reqEmitted = true;
+        const serialized = serializeBody(body, meta.bodyCap);
+        if (serialized.body !== undefined || serialized.truncated) {
+            emit({
+                ...reqRecord,
+                requestBody: serialized.body,
+                requestBodyTruncated: serialized.truncated || undefined,
+            });
+        }
+        this.addEventListener('loadend', () => {
+            const status = this.status;
+            const ct = safeGetResponseHeader(this, 'content-type') ?? '';
+            const respHeaders = parseAllResponseHeaders(this);
+            const isErr = status === 0;
+            const baseRes = {
+                ts: Date.now(),
+                id: meta.id,
+                phase: 'res',
+                method: meta.method,
+                url: meta.url,
+                status: isErr ? undefined : status,
+                responseHeaders: respHeaders,
+                durationMs: performance.now() - meta.startedAt,
+            };
+            if (isErr) {
+                emit({ ...baseRes, error: 'xhr error or aborted' });
+                return;
+            }
+            if (isTextLike(ct)) {
+                const text = safeReadResponseText(this);
+                if (text === undefined) {
+                    emit(baseRes);
+                    return;
+                }
+                const capped = capText(text, meta.bodyCap);
+                emit({
+                    ...baseRes,
+                    responseBody: /json/i.test(ct) ? safeParseJson(capped.body) : capped.body,
+                    responseBodyTruncated: capped.truncated || undefined,
+                });
+            }
+            else {
+                // Binary or unknown → don't pull bytes, just record size when available.
+                const len = Number(safeGetResponseHeader(this, 'content-length') ?? '0') || 0;
+                emit({
+                    ...baseRes,
+                    responseBody: len ? `[binary ${len}B]` : '[binary]',
+                });
+            }
+        });
+        return origSend.call(this, body ?? null);
+    };
+    proto.open = patchedOpen;
+    proto.setRequestHeader = patchedSetHeader;
+    proto.send = patchedSend;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    proto[PATCHED_FLAG] = true;
+    return () => {
+        // Only restore if we still own the patch — don't clobber a later patch.
+        if (proto.open !== patchedOpen)
+            return;
+        proto.open = origOpen;
+        proto.setRequestHeader = origSetHeader;
+        proto.send = origSend;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        delete proto[PATCHED_FLAG];
+    };
+}
+// ─── helpers ────────────────────────────────────────────────────────────────
+function generateId() {
+    try {
+        return crypto.randomUUID();
+    }
+    catch {
+        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+}
+function redactHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h)) {
+        out[k] = SENSITIVE_HEADER.test(k) ? `[redacted ${String(v).length}]` : v;
+    }
+    return out;
+}
+function serializeBody(body, cap) {
+    if (body === undefined || body === null)
+        return { truncated: false };
+    if (typeof body === 'string')
+        return capText(body, cap);
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const obj = {};
+        body.forEach((v, k) => {
+            obj[k] = typeof v === 'string'
+                ? v
+                : `[File ${v.name} ${v.size}B]`;
+        });
+        return { body: obj, truncated: false };
+    }
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+        return { body: body.toString(), truncated: false };
+    }
+    if (typeof Blob !== 'undefined' && body instanceof Blob) {
+        return { body: `[Blob ${body.size}B]`, truncated: false };
+    }
+    if (body instanceof ArrayBuffer) {
+        return { body: `[ArrayBuffer ${body.byteLength}B]`, truncated: false };
+    }
+    if (ArrayBuffer.isView(body)) {
+        return {
+            body: `[${body.constructor.name} ${body.byteLength}B]`,
+            truncated: false,
+        };
+    }
+    if (typeof Document !== 'undefined' && body instanceof Document) {
+        return { body: '[Document]', truncated: false };
+    }
+    return { body: '[unknown body]', truncated: false };
+}
+function capText(text, cap) {
+    if (text.length > cap)
+        return { body: text.slice(0, cap), truncated: true };
+    return { body: text, truncated: false };
+}
+function safeGetResponseHeader(xhr, name) {
+    try {
+        return xhr.getResponseHeader(name);
+    }
+    catch {
+        return null;
+    }
+}
+function parseAllResponseHeaders(xhr) {
+    let raw;
+    try {
+        raw = xhr.getAllResponseHeaders();
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw)
+        return undefined;
+    const out = {};
+    for (const line of raw.split('\r\n')) {
+        const idx = line.indexOf(':');
+        if (idx < 0)
+            continue;
+        const k = line.slice(0, idx).trim();
+        const v = line.slice(idx + 1).trim();
+        if (k)
+            out[k] = v;
+    }
+    return Object.keys(out).length ? redactHeaders(out) : undefined;
+}
+function safeReadResponseText(xhr) {
+    try {
+        // responseType must be '' or 'text' to access responseText.
+        if (xhr.responseType !== '' && xhr.responseType !== 'text')
+            return undefined;
+        return xhr.responseText;
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isTextLike(ct) {
+    return /json|text|xml|javascript|x-www-form-urlencoded/i.test(ct);
+}
+function safeEmit(fn, entry) {
+    try {
+        fn(entry);
+    }
+    catch {
+        /* swallow */
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@harness-fe/runtime",
+  "version": "3.0.1",
+  "description": "Browser-side SDK injected into the dev page. Connects to the MCP server via WebSocket and executes commands.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Morphicai/harness-fe.git",
+    "directory": "packages/runtime-client"
+  },
+  "homepage": "https://github.com/Morphicai/harness-fe#readme",
+  "bugs": {
+    "url": "https://github.com/Morphicai/harness-fe/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@zumer/snapdom": "^2.12.0",
+    "rrweb": "2.0.0-alpha.4",
+    "@harness-fe/protocol": "3.0.0"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.9.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "watch": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/buffer.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { RingBuffer } from './buffer.js';
+
+describe('RingBuffer', () => {
+    it('respects capacity', () => {
+        const buf = new RingBuffer<number>(3);
+        for (let i = 1; i <= 5; i++) buf.push(i);
+        expect(buf.size()).toBe(3);
+        expect(buf.tail(3)).toEqual([3, 4, 5]);
+    });
+
+    it('tail(n) returns last n items', () => {
+        const buf = new RingBuffer<string>(10);
+        ['a', 'b', 'c', 'd'].forEach((v) => buf.push(v));
+        expect(buf.tail(2)).toEqual(['c', 'd']);
+        expect(buf.tail(99)).toEqual(['a', 'b', 'c', 'd']);
+    });
+
+    it('clear empties the buffer', () => {
+        const buf = new RingBuffer<number>(3);
+        buf.push(1);
+        buf.clear();
+        expect(buf.size()).toBe(0);
+        expect(buf.tail(5)).toEqual([]);
+    });
+});

package/src/buffer.ts

@@ -0,0 +1,29 @@
+/**
+ * Bounded ring buffer for console / network / error tails.
+ * O(1) push, O(n) drain. Fixed capacity to keep page memory bounded.
+ */
+
+export class RingBuffer<T> {
+    private items: T[] = [];
+
+    constructor(private readonly capacity: number) {}
+
+    push(item: T): void {
+        this.items.push(item);
+        if (this.items.length > this.capacity) {
+            this.items.splice(0, this.items.length - this.capacity);
+        }
+    }
+
+    tail(n: number): T[] {
+        return this.items.slice(Math.max(0, this.items.length - n));
+    }
+
+    size(): number {
+        return this.items.length;
+    }
+
+    clear(): void {
+        this.items = [];
+    }
+}

package/src/capture.ts

@@ -0,0 +1,126 @@
+/**
+ * Console + network + error capture. Monkey-patches in place once on init.
+ *
+ * Network capture covers fetch + XMLHttpRequest. Body capture is opt-in
+ * per-request to keep memory bounded.
+ */
+
+import type {
+    ConsoleEntry,
+    ErrorEntry,
+    NetworkEntry,
+} from '@harness-fe/protocol';
+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;
+
+export class CaptureStore {
+    readonly console = new RingBuffer<ConsoleEntry>(CONSOLE_CAP);
+    readonly network = new RingBuffer<NetworkEntry>(NETWORK_CAP);
+    readonly errors = new RingBuffer<ErrorEntry>(ERROR_CAP);
+
+    private installed = false;
+    private fetchDispose?: () => void;
+    private xhrDispose?: () => void;
+
+    install(onEvent: (name: string, payload: unknown) => void): void {
+        if (this.installed) return;
+        this.installed = true;
+        this.installConsole(onEvent);
+        this.installFetch(onEvent);
+        this.installXhr(onEvent);
+        this.installErrors(onEvent);
+    }
+
+    dispose(): void {
+        this.fetchDispose?.();
+        this.fetchDispose = undefined;
+        this.xhrDispose?.();
+        this.xhrDispose = 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);
+            },
+        });
+    }
+
+    private installXhr(onEvent: (name: string, payload: unknown) => void): void {
+        this.xhrDispose = installXhrPatch({
+            onEntry: (entry) => {
+                this.network.push(entry);
+                onEvent('network', 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);
+        });
+    }
+}
+
+let captureStoreSingleton: CaptureStore | undefined;
+export function getCaptureStore(): CaptureStore {
+    captureStoreSingleton ??= new 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);
+        }
+    }
+    return value;
+}

package/src/client.test.ts

@@ -0,0 +1,89 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, afterEach } from 'vitest';
+import { tryInheritFromParent } from './parent-inherit.js';
+
+/**
+ * tryInheritFromParent has three branches:
+ *   1. `window.parent === window` → top-level page, return {}
+ *   2. same-origin parent with harness-fe runtime → read tabId/sessionId/projectId
+ *   3. cross-origin parent → SecurityError when accessing parent props → catch → {}
+ *
+ * happy-dom doesn't enforce cross-origin security boundaries, so branch 3 is
+ * simulated by replacing `window.parent` with a Proxy that throws.
+ */
+describe('tryInheritFromParent', () => {
+    const origParentDescriptor = Object.getOwnPropertyDescriptor(window, 'parent');
+
+    afterEach(() => {
+        if (origParentDescriptor) {
+            Object.defineProperty(window, 'parent', origParentDescriptor);
+        }
+        delete (window as any).__hfe_session_id__;
+        delete (window as any).__harness_fe_client__;
+        delete (window as any).__HARNESS_FE__;
+        try {
+            sessionStorage.removeItem('__hfe_tab_id__');
+        } catch {
+            /* noop */
+        }
+    });
+
+    it('returns empty object when running at top level (parent === window)', () => {
+        // happy-dom default: window.parent === window
+        expect(window.parent).toBe(window);
+        expect(tryInheritFromParent()).toEqual({});
+    });
+
+    it('reads parent tabId / sessionId / projectId when same-origin parent has harness-fe', () => {
+        const fakeParent = {
+            __hfe_session_id__: 'parent-session-xyz',
+            __harness_fe_client__: {
+                tabId: 'parent-tab-abc',
+                sessionId: 'parent-session-xyz',
+            },
+            __HARNESS_FE__: { projectId: 'iframe-parent' },
+            // sessionStorage isn't read because __harness_fe_client__.tabId
+            // already returns a value. Keeping it minimal here.
+            sessionStorage: undefined as unknown as Storage,
+        };
+        Object.defineProperty(window, 'parent', { value: fakeParent, configurable: true });
+
+        expect(tryInheritFromParent()).toEqual({
+            tabId: 'parent-tab-abc',
+            sessionId: 'parent-session-xyz',
+            parentProjectId: 'iframe-parent',
+        });
+    });
+
+    it('falls back to parent.sessionStorage for tabId when no client global is exposed yet', () => {
+        // Simulates: parent runtime hasn't finished booting; sessionStorage
+        // is already populated from a previous tab session.
+        const fakeStorage = {
+            getItem: (key: string) => (key === '__hfe_tab_id__' ? 'storage-tab' : null),
+        } as unknown as Storage;
+        const fakeParent = {
+            __HARNESS_FE__: { projectId: 'iframe-parent' },
+            sessionStorage: fakeStorage,
+        };
+        Object.defineProperty(window, 'parent', { value: fakeParent, configurable: true });
+
+        const out = tryInheritFromParent();
+        expect(out.tabId).toBe('storage-tab');
+        expect(out.parentProjectId).toBe('iframe-parent');
+        expect(out.sessionId).toBeUndefined(); // parent hasn't booted yet
+    });
+
+    it('returns empty object on cross-origin SecurityError', () => {
+        // Cross-origin: any property read on window.parent throws.
+        const evilParent = new Proxy(
+            {},
+            {
+                get(): never {
+                    throw new DOMException('Blocked a frame...', 'SecurityError');
+                },
+            },
+        );
+        Object.defineProperty(window, 'parent', { value: evilParent, configurable: true });
+        expect(tryInheritFromParent()).toEqual({});
+    });
+});