@harness-fe/runtime 3.1.0 → 3.3.0

package/dist/fetchPatch.js

@@ -1,314 +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 { captureInitiator } from './initiator.js';
-const DEFAULT_BODY_CAP = 256 * 1024;
-const INTERNAL_FLAG = '__hfeInternal';
-const PATCHED_FLAG = '__hfePatched';
-const DEFAULT_DENYLIST = [/\/__hfe\//, /sockjs-node/, /\.hot-update\./];
-const SENSITIVE_HEADER = /^(authorization|cookie|x-api-key|x-auth-.+)$/i;
-/**
- * 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 function installFetchPatch(opts) {
-    if (typeof window === 'undefined' || typeof window.fetch !== 'function') {
-        return () => { };
-    }
-    const original = window.fetch;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    if (original[PATCHED_FLAG])
-        return () => { };
-    const bodyCap = opts.bodyCap ?? DEFAULT_BODY_CAP;
-    const denylist = opts.denylist ?? DEFAULT_DENYLIST;
-    const emit = (entry) => safeEmit(opts.onEntry, entry);
-    // Named function so .name === 'fetch'.
-    const patched = function fetch(input, init) {
-        // Self-traffic short-circuit — internal requests bypass capture.
-        if (init && init[INTERNAL_FLAG]) {
-            return original.call(this, input, init);
-        }
-        const meta = extractRequestMeta(input, init);
-        if (denylist.some((re) => re.test(meta.url))) {
-            return original.call(this, input, init);
-        }
-        const id = generateId();
-        const startedAt = performance.now();
-        const startedTs = Date.now();
-        const initiator = captureInitiator();
-        // Emit request record eagerly (req body is read async — second emit
-        // updates the record once body is serialized; consumers join by id).
-        const reqRecord = {
-            ts: startedTs,
-            id,
-            phase: 'req',
-            method: meta.method,
-            url: meta.url,
-            requestHeaders: meta.headers,
-            initiator,
-        };
-        emit(reqRecord);
-        cloneRequestBody(input, init, bodyCap).then(({ body, truncated }) => {
-            if (body === undefined && !truncated)
-                return;
-            emit({
-                ...reqRecord,
-                requestBody: body,
-                requestBodyTruncated: truncated || undefined,
-            });
-        }, () => {
-            /* serialization error — ignore, req already emitted */
-        });
-        const promise = original.call(this, input, init);
-        promise.then((response) => {
-            let cloned;
-            try {
-                cloned = response.clone();
-            }
-            catch {
-                emit({
-                    ts: Date.now(),
-                    id,
-                    phase: 'res',
-                    method: meta.method,
-                    url: meta.url,
-                    status: response.status,
-                    responseHeaders: headersToObject(response.headers),
-                    durationMs: performance.now() - startedAt,
-                });
-                return;
-            }
-            const finalize = (body, truncated) => {
-                emit({
-                    ts: Date.now(),
-                    id,
-                    phase: 'res',
-                    method: meta.method,
-                    url: meta.url,
-                    status: response.status,
-                    responseHeaders: headersToObject(response.headers),
-                    responseBody: body,
-                    responseBodyTruncated: truncated || undefined,
-                    durationMs: performance.now() - startedAt,
-                });
-            };
-            const ct = response.headers.get('content-type') ?? '';
-            if (isSSE(ct)) {
-                pumpSSE(cloned, bodyCap, finalize);
-            }
-            else if (isTextLike(ct)) {
-                readTextWithCap(cloned, bodyCap).then(({ body, truncated }) => finalize(maybeParseJson(body, ct), truncated), () => finalize(undefined, false));
-            }
-            else {
-                // Binary or unknown: only record size, do not pull bytes.
-                cloned.arrayBuffer().then((buf) => finalize(`[binary ${buf.byteLength}B]`, false), () => finalize(undefined, false));
-            }
-        }, (err) => {
-            emit({
-                ts: Date.now(),
-                id,
-                phase: 'res',
-                method: meta.method,
-                url: meta.url,
-                durationMs: performance.now() - startedAt,
-                error: err instanceof Error ? err.message : String(err),
-            });
-        });
-        return promise;
-    };
-    // Preserve fingerprint — library detection commonly inspects these.
-    try {
-        Object.defineProperty(patched, 'name', { value: 'fetch' });
-        Object.defineProperty(patched, 'length', { value: original.length });
-        Object.defineProperty(patched, 'toString', {
-            value: () => original.toString(),
-        });
-    }
-    catch {
-        /* sealed property — safe to skip */
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    patched[PATCHED_FLAG] = true;
-    window.fetch = patched;
-    return () => {
-        if (window.fetch === patched) {
-            window.fetch = original;
-        }
-    };
-}
-// ─── helpers ────────────────────────────────────────────────────────────────
-function generateId() {
-    try {
-        return crypto.randomUUID();
-    }
-    catch {
-        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-    }
-}
-function extractRequestMeta(input, init) {
-    let url;
-    let method = 'GET';
-    let headers;
-    if (typeof input === 'string') {
-        url = input;
-    }
-    else if (input instanceof URL) {
-        url = input.toString();
-    }
-    else {
-        url = input.url;
-        method = input.method;
-        headers = headersToObject(input.headers);
-    }
-    if (init?.method)
-        method = init.method;
-    if (init?.headers) {
-        headers = { ...(headers ?? {}), ...(headersToObject(init.headers) ?? {}) };
-    }
-    return { url, method, headers };
-}
-function headersToObject(h) {
-    if (!h)
-        return undefined;
-    const out = {};
-    if (h instanceof Headers) {
-        h.forEach((v, k) => {
-            out[k] = v;
-        });
-    }
-    else if (Array.isArray(h)) {
-        for (const [k, v] of h)
-            out[k] = v;
-    }
-    else {
-        Object.assign(out, h);
-    }
-    return redactHeaders(out);
-}
-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;
-}
-async function cloneRequestBody(input, init, cap) {
-    if (init?.body !== undefined && init.body !== null) {
-        return serializeBodyInit(init.body, cap);
-    }
-    if (input instanceof Request && input.body) {
-        try {
-            const text = await input.clone().text();
-            return capText(text, cap);
-        }
-        catch {
-            return { truncated: false };
-        }
-    }
-    return { truncated: false };
-}
-function serializeBodyInit(body, cap) {
-    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 };
-    }
-    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 };
-}
-async function readTextWithCap(res, cap) {
-    const text = await res.text();
-    return capText(text, cap);
-}
-function maybeParseJson(text, contentType) {
-    if (!/json/i.test(contentType))
-        return text;
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-}
-function isSSE(ct) {
-    return /text\/event-stream/i.test(ct);
-}
-function isTextLike(ct) {
-    return /json|text|xml|javascript|x-www-form-urlencoded/i.test(ct);
-}
-function pumpSSE(res, cap, done) {
-    if (!res.body || typeof res.body.getReader !== 'function') {
-        return done('', false);
-    }
-    const reader = res.body.getReader();
-    const dec = new TextDecoder();
-    let total = '';
-    let truncated = false;
-    const step = () => {
-        reader.read().then(({ done: end, value }) => {
-            if (end)
-                return done(total, truncated);
-            total += dec.decode(value, { stream: true });
-            if (total.length > cap) {
-                total = total.slice(0, cap);
-                truncated = true;
-                reader.cancel().catch(() => { });
-                return done(total, truncated);
-            }
-            step();
-        }, () => done(total, truncated));
-    };
-    step();
-}
-function safeEmit(fn, entry) {
-    try {
-        fn(entry);
-    }
-    catch {
-        /* swallow — capture must not break business */
-    }
-}

package/dist/initiator.d.ts

@@ -1,20 +0,0 @@
-/**
- * Initiator stack capture — answers "who issued this network/storage call?".
- *
- * Called synchronously from inside a patched API (fetch / xhr / ws / storage).
- * `new Error().stack` walks the JS call stack from the V8 perspective:
- *   - frame 0: this helper
- *   - frame 1: the patched wrapper
- *   - frame 2+: caller code
- *
- * We trim the first 2 frames so the returned `stack` starts at the business
- * code that triggered the call. Best-effort: shapes vary across engines, so
- * if the format is unexpected we return the raw stack.
- *
- * Cost: ~0.2–0.5 ms per call on a modern V8. Safe to leave on in development;
- * gated behind NODE_ENV elsewhere so production is unaffected.
- */
-export interface Initiator {
-    stack?: string;
-}
-export declare function captureInitiator(): Initiator;

package/dist/initiator.js

@@ -1,34 +0,0 @@
-/**
- * Initiator stack capture — answers "who issued this network/storage call?".
- *
- * Called synchronously from inside a patched API (fetch / xhr / ws / storage).
- * `new Error().stack` walks the JS call stack from the V8 perspective:
- *   - frame 0: this helper
- *   - frame 1: the patched wrapper
- *   - frame 2+: caller code
- *
- * We trim the first 2 frames so the returned `stack` starts at the business
- * code that triggered the call. Best-effort: shapes vary across engines, so
- * if the format is unexpected we return the raw stack.
- *
- * Cost: ~0.2–0.5 ms per call on a modern V8. Safe to leave on in development;
- * gated behind NODE_ENV elsewhere so production is unaffected.
- */
-const FRAMES_TO_TRIM = 2;
-export function captureInitiator() {
-    const err = new Error();
-    const raw = err.stack;
-    if (!raw)
-        return {};
-    const lines = raw.split('\n');
-    if (lines.length <= FRAMES_TO_TRIM + 1)
-        return { stack: raw };
-    // Preserve the "Error" header line + caller frames. Drop the frames
-    // representing the helper and the patched wrapper.
-    const header = lines[0].startsWith('Error') ? lines[0] : '';
-    const callerFrames = lines.slice(FRAMES_TO_TRIM + 1);
-    const trimmed = header
-        ? [header, ...callerFrames].join('\n')
-        : callerFrames.join('\n');
-    return { stack: trimmed };
-}

package/dist/storagePatch.d.ts

@@ -1,23 +0,0 @@
-/**
- * Storage monkey-patch — captures localStorage / sessionStorage / cookie
- * mutations so agents can answer "who deleted my token?".
- *
- * Safety contract (mirrors fetchPatch / wsPatch):
- *  1. Identity-preserving: replacements use Object.defineProperty so
- *     `localStorage.setItem` keeps its prototype membership. Cookie wrapping
- *     uses a `document` getter/setter pair on the prototype.
- *  2. Error-isolated: capture failures swallowed; never propagate to callers.
- *  3. No timing or value change: every wrapper calls the original synchronously
- *     and returns its result.
- *  4. crossTab events captured via the native `storage` event (no initiator —
- *     the mutation happened in another tab so the stack is meaningless here).
- *
- * Idempotent. Returns a dispose function.
- */
-import type { StorageEntry } from '@harness-fe/protocol';
-export interface StoragePatchOptions {
-    onEntry: (entry: StorageEntry) => void;
-    /** Per-value byte cap. Default 4 KB — captures small tokens, drops giant blobs. */
-    valueCap?: number;
-}
-export declare function installStoragePatch(opts: StoragePatchOptions): () => void;

package/dist/storagePatch.js

@@ -1,190 +0,0 @@
-/**
- * Storage monkey-patch — captures localStorage / sessionStorage / cookie
- * mutations so agents can answer "who deleted my token?".
- *
- * Safety contract (mirrors fetchPatch / wsPatch):
- *  1. Identity-preserving: replacements use Object.defineProperty so
- *     `localStorage.setItem` keeps its prototype membership. Cookie wrapping
- *     uses a `document` getter/setter pair on the prototype.
- *  2. Error-isolated: capture failures swallowed; never propagate to callers.
- *  3. No timing or value change: every wrapper calls the original synchronously
- *     and returns its result.
- *  4. crossTab events captured via the native `storage` event (no initiator —
- *     the mutation happened in another tab so the stack is meaningless here).
- *
- * Idempotent. Returns a dispose function.
- */
-import { captureInitiator } from './initiator.js';
-const PATCHED_FLAG = '__hfeStoragePatched';
-const DEFAULT_VALUE_CAP = 4 * 1024;
-export function installStoragePatch(opts) {
-    if (typeof window === 'undefined')
-        return () => { };
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    if (window[PATCHED_FLAG])
-        return () => { };
-    const valueCap = opts.valueCap ?? DEFAULT_VALUE_CAP;
-    const emit = (entry) => {
-        try {
-            opts.onEntry(entry);
-        }
-        catch {
-            /* swallow */
-        }
-    };
-    const disposers = [];
-    // Patch each storage instance directly — own properties shadow the
-    // prototype regardless of how the engine implements them. This works
-    // uniformly across real browsers, happy-dom, jsdom, and Electron.
-    try {
-        disposers.push(patchStorageInstance(window.localStorage, 'local', valueCap, emit));
-    }
-    catch { /* localStorage may be inaccessible (private mode, etc.) */ }
-    try {
-        disposers.push(patchStorageInstance(window.sessionStorage, 'session', valueCap, emit));
-    }
-    catch { /* ignore */ }
-    if (typeof document !== 'undefined') {
-        const cookieDispose = patchCookie(valueCap, emit);
-        if (cookieDispose)
-            disposers.push(cookieDispose);
-    }
-    // Cross-tab storage events.
-    const onStorageEvent = (ev) => {
-        const which = ev.storageArea === window.sessionStorage ? 'session' : 'local';
-        const op = ev.key === null ? 'clear' : ev.newValue === null ? 'remove' : 'set';
-        emit({
-            ts: Date.now(),
-            op,
-            which,
-            key: ev.key ?? undefined,
-            value: ev.newValue !== null ? clip(ev.newValue, valueCap) : undefined,
-            crossTab: true,
-        });
-    };
-    window.addEventListener('storage', onStorageEvent);
-    disposers.push(() => window.removeEventListener('storage', onStorageEvent));
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    window[PATCHED_FLAG] = true;
-    return () => {
-        for (const d of disposers) {
-            try {
-                d();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        delete window[PATCHED_FLAG];
-    };
-}
-/**
- * Patch Storage.prototype.setItem / removeItem / clear. Both localStorage and
- * sessionStorage share the same prototype, so one patch covers both — we
- * disambiguate at call time via `this === window.sessionStorage`.
- */
-function patchStorageInstance(storage, kind, valueCap, emit) {
-    const origSet = storage.setItem.bind(storage);
-    const origRemove = storage.removeItem.bind(storage);
-    const origClear = storage.clear.bind(storage);
-    Object.defineProperty(storage, 'setItem', {
-        configurable: true, writable: true,
-        value: (key, value) => {
-            emit({ ts: Date.now(), op: 'set', which: kind, key, value: clip(value, valueCap), initiator: captureInitiator() });
-            origSet(key, value);
-        },
-    });
-    Object.defineProperty(storage, 'removeItem', {
-        configurable: true, writable: true,
-        value: (key) => {
-            emit({ ts: Date.now(), op: 'remove', which: kind, key, initiator: captureInitiator() });
-            origRemove(key);
-        },
-    });
-    Object.defineProperty(storage, 'clear', {
-        configurable: true, writable: true,
-        value: () => {
-            emit({ ts: Date.now(), op: 'clear', which: kind, initiator: captureInitiator() });
-            origClear();
-        },
-    });
-    return () => {
-        // Restore by replacing the own properties with thin shims that
-        // forward to the captured originals. `delete` doesn't reliably
-        // expose the prototype method in every engine (happy-dom in
-        // particular), so this is the safer reset.
-        try {
-            Object.defineProperty(storage, 'setItem', {
-                configurable: true, writable: true,
-                value: (k, v) => origSet(k, v),
-            });
-            Object.defineProperty(storage, 'removeItem', {
-                configurable: true, writable: true,
-                value: (k) => origRemove(k),
-            });
-            Object.defineProperty(storage, 'clear', {
-                configurable: true, writable: true,
-                value: () => origClear(),
-            });
-        }
-        catch { /* ignore */ }
-    };
-}
-function patchCookie(valueCap, emit) {
-    const descriptor = Object.getOwnPropertyDescriptor(Document.prototype, 'cookie');
-    if (!descriptor || !descriptor.set || !descriptor.get)
-        return undefined;
-    const origSet = descriptor.set;
-    const origGet = descriptor.get;
-    Object.defineProperty(Document.prototype, 'cookie', {
-        configurable: true,
-        get() {
-            return origGet.call(this);
-        },
-        set(val) {
-            const initiator = captureInitiator();
-            const { key, value, removed } = parseCookieAssignment(val);
-            emit({
-                ts: Date.now(),
-                op: removed ? 'remove' : 'set',
-                which: 'cookie',
-                key,
-                value: removed ? undefined : value !== undefined ? clip(value, valueCap) : undefined,
-                initiator,
-            });
-            return origSet.call(this, val);
-        },
-    });
-    return () => {
-        Object.defineProperty(Document.prototype, 'cookie', descriptor);
-    };
-}
-/**
- * Cookie writes look like "key=value; Path=/; Expires=...; Max-Age=0".
- * Treat Max-Age=0 or any past Expires as removal. Anything else is set.
- */
-function parseCookieAssignment(raw) {
-    const parts = raw.split(';');
-    const head = (parts[0] ?? '').trim();
-    const eq = head.indexOf('=');
-    const key = eq >= 0 ? head.slice(0, eq) : head;
-    const value = eq >= 0 ? head.slice(eq + 1) : undefined;
-    let removed = false;
-    for (let i = 1; i < parts.length; i++) {
-        const seg = parts[i].trim();
-        const lower = seg.toLowerCase();
-        if (lower === 'max-age=0' || lower === 'max-age=-1')
-            removed = true;
-        if (lower.startsWith('expires=')) {
-            const date = new Date(seg.slice('expires='.length).trim());
-            if (!Number.isNaN(date.getTime()) && date.getTime() <= Date.now()) {
-                removed = true;
-            }
-        }
-    }
-    return { key: key || undefined, value, removed };
-}
-function clip(s, cap) {
-    return s.length <= cap ? s : `${s.slice(0, cap)}…[+${s.length - cap}B]`;
-}

package/dist/wsPatch.d.ts

@@ -1,26 +0,0 @@
-/**
- * WebSocket monkey-patch — captures open / send / recv / close frames so
- * agents can see long-lived push channels (IM, presence, sync, kick-out).
- *
- * Safety contract (mirrors fetchPatch):
- *  1. Identity-preserving: replacement is a constructor with the same name,
- *     prototype, and CONNECTING/OPEN/CLOSING/CLOSED static fields. Existing
- *     `instanceof WebSocket` checks still pass because we extend the original.
- *  2. Error-isolated: capture failures swallowed via safeEmit.
- *  3. No timing or value change: pass-through to native WebSocket; we only
- *     observe events and call sites. The original Promise / data flow is
- *     untouched.
- *  4. Bounded memory: frame payloads capped at BODY_CAP per send/recv. Binary
- *     frames record a `[binary Nb]` marker rather than the bytes.
- *
- * The patch is idempotent. Returns a dispose function that restores
- * `window.WebSocket`.
- */
-import type { WsEntry } from '@harness-fe/protocol';
-export interface WsPatchOptions {
-    onEntry: (entry: WsEntry) => void;
-    bodyCap?: number;
-    /** URL patterns to skip entirely. Default skips daemon traffic. */
-    denylist?: RegExp[];
-}
-export declare function installWsPatch(opts: WsPatchOptions): () => void;