@harness-fe/runtime 3.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MorphixAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Morphicai/harness-fe/main/branding/logo.svg" alt="Harness-FE" width="96" />
+</p>
+
+# @harness-fe/runtime
+
+> Browser runtime client for [Harness-FE](https://github.com/Morphicai/harness-fe). Captures DOM/console/network events and executes commands from the MCP server in the user's real browser tab.
+
+Auto-injected by the [Vite plugin](https://www.npmjs.com/package/@harness-fe/vite) / [Webpack plugin](https://www.npmjs.com/package/@harness-fe/webpack) — you typically install it as a peer of the plugin.
+
+## Install
+
+```bash
+pnpm add -D @harness-fe/runtime
+```
+
+## What it does
+
+- Connects to the MCP server via WebSocket on dev page load
+- Streams `console.*`, `fetch`/`XHR`, `window.error`, `unhandledrejection` events
+- Captures rrweb session recordings for replay
+- Executes commands (`page.click`, `page.type`, `page.dom_query`, etc.)
+- Renders the annotation overlay (point-and-task)
+
+Disabled automatically in production builds.
+
+## Manual usage (advanced)
+
+For non-Vite/Webpack setups:
+
+```ts
+import { RuntimeClient } from '@harness-fe/runtime';
+
+const client = new RuntimeClient({
+    projectId: 'my-app',
+    wsUrl: 'ws://localhost:47729',
+});
+client.start();
+```
+
+## Docs
+
+- [Root README](https://github.com/Morphicai/harness-fe#readme)
+- [Architecture](https://github.com/Morphicai/harness-fe/blob/main/ARCHITECTURE.md)
+
+## License
+
+MIT

package/dist/buffer.d.ts

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

package/dist/buffer.js

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

package/dist/capture.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 { RingBuffer } from './buffer.js';
+export declare class CaptureStore {
+    readonly console: RingBuffer<{
+        ts: number;
+        level: "error" | "log" | "info" | "warn" | "debug";
+        args: unknown[];
+        source?: string | undefined;
+    }>;
+    readonly network: RingBuffer<{
+        ts: number;
+        method: string;
+        url: string;
+        id?: string | undefined;
+        phase?: "req" | "res" | undefined;
+        status?: number | undefined;
+        durationMs?: number | undefined;
+        requestHeaders?: Record<string, string> | undefined;
+        responseHeaders?: Record<string, string> | undefined;
+        requestBody?: unknown;
+        responseBody?: unknown;
+        requestBodyTruncated?: boolean | undefined;
+        responseBodyTruncated?: boolean | undefined;
+        error?: string | undefined;
+    }>;
+    readonly errors: RingBuffer<{
+        ts: number;
+        message: string;
+        stack?: string | undefined;
+        source?: string | undefined;
+    }>;
+    private installed;
+    private fetchDispose?;
+    private xhrDispose?;
+    install(onEvent: (name: string, payload: unknown) => void): void;
+    dispose(): void;
+    private installConsole;
+    private installFetch;
+    private installXhr;
+    private installErrors;
+}
+export declare function getCaptureStore(): CaptureStore;

package/dist/capture.js

@@ -0,0 +1,112 @@
+/**
+ * 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 { 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 {
+    console = new RingBuffer(CONSOLE_CAP);
+    network = new RingBuffer(NETWORK_CAP);
+    errors = new RingBuffer(ERROR_CAP);
+    installed = false;
+    fetchDispose;
+    xhrDispose;
+    install(onEvent) {
+        if (this.installed)
+            return;
+        this.installed = true;
+        this.installConsole(onEvent);
+        this.installFetch(onEvent);
+        this.installXhr(onEvent);
+        this.installErrors(onEvent);
+    }
+    dispose() {
+        this.fetchDispose?.();
+        this.fetchDispose = undefined;
+        this.xhrDispose?.();
+        this.xhrDispose = undefined;
+        this.installed = false;
+    }
+    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),
+                };
+                this.console.push(entry);
+                onEvent('console', entry);
+                original(...args);
+            };
+        }
+    }
+    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);
+        }
+    }
+    return value;
+}

package/dist/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Runtime client core. Connects to the MCP server over WS, executes
+ * commands dispatched by the server, and forwards page events back.
+ *
+ * Started lazily by `auto-start.ts` when the script is imported.
+ */
+import { COMMAND } from '@harness-fe/protocol';
+import type { QueryMethod } from '@harness-fe/protocol';
+export interface ClientOptions {
+    projectId: string;
+    mcpUrl?: string;
+    /**
+     * Build artifact id, threaded through `window.__HARNESS_FE__.buildId`.
+     * Stamped on every event so agents can trace "what code was running".
+     */
+    buildId?: string;
+    /**
+     * Parent project's id. Set by the plugin when the host app declares it,
+     * or auto-inferred at runtime via `tryInheritFromParent()` when this
+     * runtime is loaded inside a same-origin iframe.
+     */
+    parentProjectId?: string;
+    /** Optional human-readable name; mostly used by the project tree. */
+    displayName?: string;
+    /**
+     * App-supplied user identifier (e.g. supabase.user.id, auth0 sub, …).
+     * Optional. When absent, traffic is treated as anonymous (only stitched
+     * by visitorId). Propagated by HarnessScript via window.__HARNESS_FE__.userId.
+     */
+    userId?: string;
+}
+export { tryInheritFromParent } from './parent-inherit.js';
+export type { ParentInheritance } from './parent-inherit.js';
+export declare class RuntimeClient {
+    private readonly opts;
+    private ws?;
+    readonly tabId: string;
+    readonly sessionId: string;
+    readonly visitorId: string;
+    readonly parentProjectId?: string;
+    /** Read-only accessors exposed for the in-page info panel. */
+    get projectId(): string;
+    get buildId(): string | undefined;
+    get displayName(): string | undefined;
+    get userId(): string | undefined;
+    get mcpUrl(): string | undefined;
+    /** WebSocket state: 'connecting' | 'open' | 'closed'. */
+    getConnectionState(): 'connecting' | 'open' | 'closed';
+    private pageLoadSent;
+    private readonly ctx;
+    private readonly recorder;
+    private reconnectAttempts;
+    private closed;
+    private static readonly MAX_OUTBOX_FRAMES;
+    private static readonly MAX_OUTBOX_BYTES;
+    private readonly outbox;
+    constructor(opts: ClientOptions);
+    start(): void;
+    stop(): void;
+    private connect;
+    private onOpen;
+    private onClose;
+    private onMessage;
+    private onQueryResponse;
+    private onHelloAck;
+    private handleCommand;
+    sendEvent(name: string, payload: unknown): void;
+    /**
+     * Request/reply RPC to the daemon. Currently used by the in-page
+     * overlay to fetch / mutate the visitor's own tasks. Resolves with the
+     * remote `result`, rejects with the remote `error.message` (or a
+     * timeout after 10 s).
+     */
+    query<TResult = unknown>(method: QueryMethod, args?: unknown, timeoutMs?: number): Promise<TResult>;
+    private pendingQueries;
+    private send;
+    private drainOutbox;
+}
+/** Pull the well-known config object planted by the Vite plugin on window. */
+export declare function readInjectedConfig(): ClientOptions;
+/** Re-export command names for outside callers. */
+export { COMMAND };