@harness-fe/runtime 3.0.1

package/dist/dashboardUrl.js

@@ -0,0 +1,20 @@
+export function deriveDashboardUrl(input) {
+    if (!input.mcpUrl)
+        return undefined;
+    let url;
+    try {
+        url = new URL(input.mcpUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const httpScheme = url.protocol === 'wss:' ? 'https:' : 'http:';
+    const path = input.sessionId
+        ? `/dashboard/sessions/${encodeURIComponent(input.sessionId)}`
+        : '/dashboard/';
+    const token = url.searchParams.get('token');
+    const search = token ? `?token=${encodeURIComponent(token)}` : '';
+    // Build manually so we don't leak any extra query/hash from the WS URL
+    // (rare, but be defensive — the agent only ever sees what we hand it).
+    return `${httpScheme}//${url.host}${path}${search}`;
+}

package/dist/fetchPatch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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;

package/dist/fetchPatch.js

@@ -0,0 +1,311 @@
+/**
+ * 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`.
+ */
+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();
+        // 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,
+        };
+        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/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Auto-start entry. Importing this module (as the Vite plugin does)
+ * boots a RuntimeClient using the config planted on `window.__HARNESS_FE__`.
+ *
+ * Idempotent: importing twice is a no-op.
+ */
+export { RuntimeClient, tryInheritFromParent } from './client.js';
+export type { ClientOptions, ParentInheritance } from './client.js';

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * Auto-start entry. Importing this module (as the Vite plugin does)
+ * boots a RuntimeClient using the config planted on `window.__HARNESS_FE__`.
+ *
+ * Idempotent: importing twice is a no-op.
+ */
+import { installOverlay } from './overlay.js';
+import { RuntimeClient, readInjectedConfig } from './client.js';
+const w = window;
+if (typeof window !== 'undefined' && !w.__harness_fe_started__) {
+    w.__harness_fe_started__ = true;
+    const cfg = readInjectedConfig();
+    const client = new RuntimeClient(cfg);
+    client.start();
+    installOverlay(client);
+    // Expose for debugging + same-origin iframe inheritance.
+    // Same-origin children read `window.parent.__hfe_session_id__` and
+    // `window.parent.__harness_fe_client__.tabId` in tryInheritFromParent()
+    // so all iframes within one pageload share identity.
+    w.__harness_fe_client__ = client;
+    w.__hfe_session_id__ = client.sessionId;
+}
+export { RuntimeClient, tryInheritFromParent } from './client.js';

package/dist/outbox.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pre-handshake / reconnect outbox.
+ *
+ * Buffers frames produced while the WebSocket isn't OPEN and replays them
+ * in FIFO order on `flush(send)`. Capped to defend against OOM if the
+ * bridge is unreachable for an extended period.
+ *
+ * `sticky` marks frames that must survive eviction even when the outbox
+ * is full — currently used for rrweb chunks containing a FullSnapshot
+ * (type:2) baseline. Without this protection, the FullSnapshot — being
+ * the oldest frame in the outbox — was always the first to be FIFO-
+ * evicted under load, leaving the session permanently unreplayable.
+ * Eviction only touches sticky frames as a last resort (all remaining
+ * frames are sticky and we still exceed cap).
+ */
+export declare class Outbox {
+    private readonly maxFrames;
+    private readonly maxBytes;
+    private entries;
+    private bytes;
+    constructor(maxFrames: number, maxBytes: number);
+    /** Current buffered frame count. */
+    get size(): number;
+    /** Current buffered byte size. */
+    get byteSize(): number;
+    /** Inspect entries without exposing the underlying mutable array. */
+    snapshot(): ReadonlyArray<{
+        payload: string;
+        sticky: boolean;
+    }>;
+    enqueue(payload: string, sticky: boolean): void;
+    /**
+     * Drain FIFO into `send`. If `send` throws (or returns false), keep the
+     * frame in the queue and bail — caller will retry on next flush.
+     */
+    flush(send: (payload: string) => boolean | void): void;
+}

package/dist/outbox.js

@@ -0,0 +1,80 @@
+/**
+ * Pre-handshake / reconnect outbox.
+ *
+ * Buffers frames produced while the WebSocket isn't OPEN and replays them
+ * in FIFO order on `flush(send)`. Capped to defend against OOM if the
+ * bridge is unreachable for an extended period.
+ *
+ * `sticky` marks frames that must survive eviction even when the outbox
+ * is full — currently used for rrweb chunks containing a FullSnapshot
+ * (type:2) baseline. Without this protection, the FullSnapshot — being
+ * the oldest frame in the outbox — was always the first to be FIFO-
+ * evicted under load, leaving the session permanently unreplayable.
+ * Eviction only touches sticky frames as a last resort (all remaining
+ * frames are sticky and we still exceed cap).
+ */
+export class Outbox {
+    maxFrames;
+    maxBytes;
+    entries = [];
+    bytes = 0;
+    constructor(maxFrames, maxBytes) {
+        this.maxFrames = maxFrames;
+        this.maxBytes = maxBytes;
+    }
+    /** Current buffered frame count. */
+    get size() {
+        return this.entries.length;
+    }
+    /** Current buffered byte size. */
+    get byteSize() {
+        return this.bytes;
+    }
+    /** Inspect entries without exposing the underlying mutable array. */
+    snapshot() {
+        return this.entries.slice();
+    }
+    enqueue(payload, sticky) {
+        this.entries.push({ payload, sticky });
+        this.bytes += payload.length;
+        // Pass 1: evict only non-sticky frames, oldest first.
+        let i = 0;
+        while ((this.entries.length > this.maxFrames || this.bytes > this.maxBytes) && i < this.entries.length) {
+            const entry = this.entries[i];
+            if (entry.sticky) {
+                i++;
+                continue;
+            }
+            this.entries.splice(i, 1);
+            this.bytes -= entry.payload.length;
+        }
+        // Pass 2 (last resort): drop oldest sticky frames if we still bust
+        // the cap. Replay only needs the *most recent* baseline, so dropping
+        // older sticky frames is acceptable.
+        while ((this.entries.length > this.maxFrames || this.bytes > this.maxBytes) && this.entries.length > 0) {
+            const dropped = this.entries.shift();
+            this.bytes -= dropped.payload.length;
+        }
+    }
+    /**
+     * Drain FIFO into `send`. If `send` throws (or returns false), keep the
+     * frame in the queue and bail — caller will retry on next flush.
+     */
+    flush(send) {
+        while (this.entries.length > 0) {
+            const entry = this.entries[0];
+            let ok = false;
+            try {
+                const result = send(entry.payload);
+                ok = result !== false;
+            }
+            catch {
+                ok = false;
+            }
+            if (!ok)
+                return;
+            this.entries.shift();
+            this.bytes -= entry.payload.length;
+        }
+    }
+}

package/dist/overlay.d.ts

@@ -0,0 +1,68 @@
+/**
+ * In-page overlay — single floating "H" mark in the bottom-right corner.
+ *
+ * Click → expands into an info card that surfaces:
+ *   - project / buildId / connection status
+ *   - sessionId / tabId (click-to-copy)
+ *   - current URL
+ *   - "Copy snapshot" — key fields as markdown for sharing with a teammate
+ *     or pasting into an agent prompt
+ *   - "Report a problem" — enters element-picker mode (the legacy annotation
+ *     flow, now reachable from inside the card so users don't see two FABs)
+ *
+ * Single Shadow DOM root attached to <body>; host page styles never leak in
+ * or out. State machine: idle → info → (picker → question) → flash → idle.
+ */
+import { type TaskAttachment } from '@harness-fe/protocol';
+export interface OverlayClient {
+    readonly projectId: string;
+    readonly buildId?: string;
+    readonly displayName?: string;
+    readonly tabId: string;
+    readonly sessionId: string;
+    readonly visitorId?: string;
+    readonly userId?: string;
+    readonly parentProjectId?: string;
+    /**
+     * WebSocket URL the runtime connects to. Used by the overlay to derive
+     * the daemon's dashboard URL ("Open dashboard" button). Optional — if
+     * absent, the button hides instead of pointing at the wrong host.
+     */
+    readonly mcpUrl?: string;
+    getConnectionState(): 'connecting' | 'open' | 'closed';
+    sendEvent(name: string, payload: unknown): void;
+    /**
+     * RPC channel to the daemon. Used to fetch and mutate the visitor's own
+     * tasks. Resolves with `result`, rejects with the remote error message.
+     */
+    query?<TResult = unknown>(method: string, args?: unknown): Promise<TResult>;
+}
+export declare function installOverlay(client: OverlayClient): void;
+interface ArrowStroke {
+    kind: 'arrow';
+    color: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+interface TextStroke {
+    kind: 'text';
+    color: string;
+    x: number;
+    y: number;
+    text: string;
+}
+type Stroke = ArrowStroke | TextStroke;
+export declare function replayStrokes(ctx: CanvasRenderingContext2D, bgCanvas: HTMLCanvasElement, strokes: Stroke[]): void;
+/**
+ * Flatten strokes onto the background canvas and return as a TaskAttachment.
+ * Exported for testing.
+ */
+export declare function finalizeAnnotation(): Promise<TaskAttachment | null>;
+/**
+ * Best-effort CSS path. Depth cap 12, id anchor short-circuits, ` >>> `
+ * separates shadow-DOM boundaries.
+ */
+export declare function buildCssPath(el: Element): string;
+export {};