cairn-engine 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# cairn-engine
+
+![cairn banner](https://raw.githubusercontent.com/team-poem/cairn/main/banner.svg)
+
+The engine behind [cairn](https://github.com/team-poem/cairn) — browser tests an AI
+discovers once, replays deterministically (no LLM in the loop), and self-heals when the UI
+drifts. Model- and browser-agnostic; embed it or drive it from the `cairn` CLI.
+
+```sh
+npm install cairn-engine
+```
+
+```sh
+# discover an LLM walks the app once and writes a scenario
+cairn discover "follow the link to learn more" --url https://example.com --freeze t.json
+# replay deterministic, no LLM; non-zero exit on failure (CI gate)
+cairn replay t.json
+# heal repair a broken step via the LLM and re-freeze
+cairn replay t.json --heal --freeze t.json
+```
+
+Embed it — every stage is an injected port:
+
+```ts
+import { runScenario } from "cairn-engine";
+
+const { result } = await runScenario(scenario, { heal: true });
+if (!result.verdict.passed) process.exit(1);
+```
+
+No API key needed if you have **Claude Code** installed (cairn shells out to it); set
+`ANTHROPIC_API_KEY` to use the Anthropic API instead.
+
+**Full docs, design, and the loop diagram:** https://github.com/team-poem/cairn
+
+MIT

package/dist/adapters/context/inline.d.ts

@@ -0,0 +1,8 @@
+/** Simplest ContextProvider: the task string is the intent. */
+import type { ContextProvider } from "../../core/ports.js";
+import type { Context } from "../../core/types.js";
+export declare class InlineContextProvider implements ContextProvider {
+    private readonly baseUrl?;
+    constructor(baseUrl?: string | undefined);
+    provide(task: string): Promise<Context>;
+}

package/dist/adapters/context/inline.js

@@ -0,0 +1,10 @@
+export class InlineContextProvider {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async provide(task) {
+        return { intent: task, baseUrl: this.baseUrl };
+    }
+}
+//# sourceMappingURL=inline.js.map

package/dist/adapters/context/inline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline.js","sourceRoot":"","sources":["../../../src/adapters/context/inline.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,qBAAqB;IACH;IAA7B,YAA6B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;IAAG,CAAC;IAEjD,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACjD,CAAC;CACF"}

package/dist/adapters/critics/assertion.d.ts

@@ -0,0 +1,8 @@
+/** Deterministic Critic for the replay path — checks assertions against evidence, no LLM (invariant #4). */
+import type { Critic } from "../../core/ports.js";
+import type { Assertion, AssertionResult, Evidence, Verdict } from "../../core/types.js";
+/** Evaluate one mechanical assertion. `expect` is not mechanical — returns unsupported (LlmCritic handles it). */
+export declare function checkAssertion(assertion: Assertion, evidence: Evidence): AssertionResult;
+export declare class AssertionCritic implements Critic {
+    judge(evidence: Evidence, assertions: Assertion[]): Promise<Verdict>;
+}

package/dist/adapters/critics/assertion.js

@@ -0,0 +1,43 @@
+/** Evaluate one mechanical assertion. `expect` is not mechanical — returns unsupported (LlmCritic handles it). */
+export function checkAssertion(assertion, evidence) {
+    switch (assertion.kind) {
+        case "navigated": {
+            const { navigated, finalUrl } = evidence.execution;
+            if (!navigated)
+                return { assertion, passed: false, detail: "no navigation occurred" };
+            if (assertion.to && !(finalUrl ?? "").includes(assertion.to)) {
+                return { assertion, passed: false, detail: `final url ${finalUrl} does not include ${assertion.to}` };
+            }
+            return { assertion, passed: true, detail: finalUrl };
+        }
+        case "no-console-errors": {
+            const errors = evidence.logic.console.filter((m) => m.type === "error");
+            return errors.length === 0
+                ? { assertion, passed: true }
+                : { assertion, passed: false, detail: `${errors.length} console error(s): ${errors[0]?.text}` };
+        }
+        case "no-failed-requests": {
+            const failed = evidence.logic.requests.filter((r) => r.status >= 400);
+            return failed.length === 0
+                ? { assertion, passed: true }
+                : { assertion, passed: false, detail: `${failed.length} failed request(s): ${failed[0]?.status} ${failed[0]?.url}` };
+        }
+        case "request-status": {
+            const match = evidence.logic.requests.find((r) => r.url.includes(assertion.urlIncludes));
+            if (!match)
+                return { assertion, passed: false, detail: `no request matching ${assertion.urlIncludes}` };
+            return match.status === assertion.status
+                ? { assertion, passed: true, detail: `${match.status} ${match.url}` }
+                : { assertion, passed: false, detail: `expected ${assertion.status}, got ${match.status} for ${match.url}` };
+        }
+        case "expect":
+            return { assertion, passed: false, detail: "'expect' is judged by LlmCritic, not the deterministic critic" };
+    }
+}
+export class AssertionCritic {
+    async judge(evidence, assertions) {
+        const results = assertions.map((a) => checkAssertion(a, evidence));
+        return { passed: results.every((r) => r.passed), results };
+    }
+}
+//# sourceMappingURL=assertion.js.map

package/dist/adapters/critics/assertion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion.js","sourceRoot":"","sources":["../../../src/adapters/critics/assertion.ts"],"names":[],"mappings":"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"}

package/dist/adapters/critics/llm.d.ts

@@ -0,0 +1,10 @@
+import type { Critic, LlmClient } from "../../core/ports.js";
+import type { Assertion, Evidence, Verdict } from "../../core/types.js";
+/** Compact, judge-friendly rendering of the three evidence layers. */
+export declare function summarizeEvidence(evidence: Evidence): string;
+export declare class LlmCritic implements Critic {
+    private readonly llm;
+    constructor(llm: LlmClient);
+    private judgeExpect;
+    judge(evidence: Evidence, assertions: Assertion[]): Promise<Verdict>;
+}

package/dist/adapters/critics/llm.js

@@ -0,0 +1,68 @@
+/**
+ * Critic that judges natural-language `expect` criteria with an LLM and delegates mechanical
+ * assertions to the deterministic checker. The LLM runs ONLY for `expect`, so a scenario with
+ * none makes zero LLM calls and stays deterministic (invariant #4). Judgment is grounded in the
+ * three-layer evidence (design §6), behind the LlmClient seam (invariant #5).
+ */
+import { checkAssertion } from "./assertion.js";
+const SYSTEM = "You are a QA critic. Given observed evidence from a browser run and a success " +
+    "criterion, decide whether the criterion is satisfied. Judge only from the evidence; " +
+    'do not assume. Respond with strict JSON, no prose, no code fences: {"passed":true|false,"detail":"<short reason>"}.';
+/** Compact, judge-friendly rendering of the three evidence layers. */
+export function summarizeEvidence(evidence) {
+    const { execution, logic } = evidence;
+    const requests = logic.requests
+        .slice(0, 40)
+        .map((r) => `${r.status} ${r.method} ${r.url}`)
+        .join("\n");
+    const errors = logic.console.filter((m) => m.type === "error").map((m) => m.text);
+    return [
+        `navigated: ${execution.navigated}`,
+        `finalUrl: ${execution.finalUrl ?? "(none)"}`,
+        `blocked: ${execution.blocked}`,
+        `requests (${logic.requests.length}):`,
+        requests || "(none)",
+        `console errors (${errors.length}):`,
+        errors.join("\n") || "(none)",
+    ].join("\n");
+}
+function parseVerdict(text) {
+    let s = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "");
+    const start = s.indexOf("{");
+    const end = s.lastIndexOf("}");
+    if (start === -1 || end === -1)
+        throw new Error(`no JSON in critic reply: ${text.slice(0, 200)}`);
+    const obj = JSON.parse(s.slice(start, end + 1));
+    return { passed: obj.passed === true, detail: typeof obj.detail === "string" ? obj.detail : undefined };
+}
+export class LlmCritic {
+    llm;
+    constructor(llm) {
+        this.llm = llm;
+    }
+    async judgeExpect(criterion, evidence, assertion) {
+        const prompt = [
+            `Success criterion: ${criterion}`,
+            ``,
+            `Evidence:`,
+            summarizeEvidence(evidence),
+            ``,
+            `Is the criterion satisfied? Respond with JSON only.`,
+        ].join("\n");
+        try {
+            const reply = await this.llm.complete(prompt, { system: SYSTEM });
+            const v = parseVerdict(reply);
+            return { assertion, passed: v.passed, detail: v.detail ?? `judged by ${this.llm.id}` };
+        }
+        catch (err) {
+            return { assertion, passed: false, detail: `LLM judgment failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    async judge(evidence, assertions) {
+        const results = await Promise.all(assertions.map((a) => a.kind === "expect"
+            ? this.judgeExpect(a.criterion, evidence, a)
+            : Promise.resolve(checkAssertion(a, evidence))));
+        return { passed: results.every((r) => r.passed), results };
+    }
+}
+//# sourceMappingURL=llm.js.map

package/dist/adapters/critics/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../src/adapters/critics/llm.ts"],"names":[],"mappings":"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"}

package/dist/adapters/drivers/chrome.d.ts

@@ -0,0 +1,37 @@
+import type { Driver } from "../../core/ports.js";
+import type { ConsoleMessage, Evidence, NetworkRequest, PageElement, SettleOptions, Target } from "../../core/types.js";
+export interface ChromeDriverOptions {
+    command?: string;
+    args?: string[];
+}
+export declare class ChromeDevToolsDriver implements Driver {
+    private readonly opts;
+    private client?;
+    private transport?;
+    private initialUrl?;
+    constructor(opts?: ChromeDriverOptions);
+    private ensureConnected;
+    private call;
+    goto(url: string): Promise<void>;
+    click(target: Target): Promise<void>;
+    type(target: Target, text: string): Promise<void>;
+    snapshot(): Promise<PageElement[]>;
+    settle(options?: SettleOptions): Promise<void>;
+    observe(): Promise<Evidence>;
+    close(): Promise<void>;
+    private resolveUid;
+}
+/** `uid=1_3 link "Learn more" …` → {role:"link", name:"Learn more"} for named rows. */
+export declare function parseElements(snapshot: string): PageElement[];
+/** `uid=1_3 link "Learn more" …` → first uid whose quoted name includes `text`. */
+export declare function findUidByName(snapshot: string, text: string): string | undefined;
+/** `reqid=5 GET https://… [200]` → NetworkRequest[]. */
+export declare function parseNetwork(text: string): NetworkRequest[];
+/** Console listing → messages. Conservative: only rows naming a known type. */
+export declare function parseConsole(text: string): ConsoleMessage[];
+/** Canonicalize a url for comparison: drop a trailing slash and the hash. */
+export declare function normalizeUrl(u: string): string;
+/** True only if the page genuinely moved — not just a trailing-slash difference. */
+export declare function isNavigation(initialUrl: string | undefined, finalUrl: string): boolean;
+/** `2: Example Domain (https://example.com/) [selected]` → the selected page's url. */
+export declare function parseSelectedUrl(text: string): string | undefined;

package/dist/adapters/drivers/chrome.js

@@ -0,0 +1,195 @@
+/**
+ * Default Driver — drives a real browser via the Chrome DevTools MCP server, which this
+ * embeds as a client and spawns over stdio (so `cairn run` is self-contained). Everything
+ * Chrome-specific, including parsing the MCP's human-readable text, stays here behind the
+ * Driver port (invariant #5).
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+const MCP_COMMAND = "npx";
+// `--isolated` gives the harness its own ephemeral browser, so a standalone `cairn run`
+// never collides with another chrome-devtools-mcp using the default profile.
+const MCP_ARGS = ["-y", "chrome-devtools-mcp@latest", "--isolated"];
+export class ChromeDevToolsDriver {
+    opts;
+    client;
+    transport;
+    initialUrl;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async ensureConnected() {
+        if (this.client)
+            return this.client;
+        const client = new Client({ name: "cairn-harness", version: "0.0.0" }, { capabilities: {} });
+        const transport = new StdioClientTransport({
+            command: this.opts.command ?? MCP_COMMAND,
+            args: this.opts.args ?? MCP_ARGS,
+        });
+        await client.connect(transport);
+        this.client = client;
+        this.transport = transport;
+        return client;
+    }
+    async call(name, args = {}) {
+        const client = await this.ensureConnected();
+        const res = (await client.callTool({ name, arguments: args }));
+        const text = (res.content ?? [])
+            .filter((c) => c.type === "text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("\n");
+        if (res.isError)
+            throw new Error(`MCP ${name} failed: ${text}`);
+        return text;
+    }
+    async goto(url) {
+        if (this.initialUrl === undefined)
+            this.initialUrl = url;
+        await this.call("navigate_page", { type: "url", url });
+    }
+    async click(target) {
+        const uid = await this.resolveUid(target);
+        await this.call("click", { uid });
+    }
+    async type(target, text) {
+        const uid = await this.resolveUid(target);
+        await this.call("fill", { uid, value: text });
+    }
+    async snapshot() {
+        return parseElements(await this.call("take_snapshot"));
+    }
+    async settle(options = {}) {
+        // Chrome defers low-priority resources (favicon, web fonts) past the usual 500ms
+        // "network-idle" window, so the idle threshold is generous — missing a late request
+        // would mean missing a real failure. Tune via SettleOptions.
+        const idleMs = options.idleMs ?? 1_000;
+        const timeoutMs = options.timeoutMs ?? 10_000;
+        const pollMs = options.pollMs ?? 250;
+        const deadline = Date.now() + timeoutMs;
+        let lastCount = -1;
+        let stableSince = Date.now();
+        try {
+            while (Date.now() < deadline) {
+                const count = parseNetwork(await this.call("list_network_requests")).length;
+                if (count !== lastCount) {
+                    lastCount = count;
+                    stableSince = Date.now();
+                }
+                else if (Date.now() - stableSince >= idleMs) {
+                    return; // count held steady long enough — treat as network-idle
+                }
+                await delay(pollMs);
+            }
+        }
+        catch {
+            // best-effort: settling must never fail a run (port contract).
+        }
+    }
+    async observe() {
+        const [pages, network, console] = await Promise.all([
+            this.call("list_pages"),
+            this.call("list_network_requests"),
+            this.call("list_console_messages"),
+        ]);
+        const finalUrl = parseSelectedUrl(pages);
+        const navigated = finalUrl !== undefined && isNavigation(this.initialUrl, finalUrl);
+        return {
+            execution: { actions: [], navigated, finalUrl, blocked: false },
+            perception: {},
+            logic: { requests: parseNetwork(network), console: parseConsole(console) },
+        };
+    }
+    async close() {
+        await this.client?.close().catch(() => { });
+        this.client = undefined;
+        this.transport = undefined;
+    }
+    async resolveUid(target) {
+        if (target.selector) {
+            throw new Error("ChromeDevToolsDriver resolves targets by text, not CSS selector");
+        }
+        if (!target.text)
+            throw new Error("target needs a `text` to resolve an element");
+        const uid = findUidByName(await this.call("take_snapshot"), target.text);
+        if (!uid)
+            throw new Error(`no element with accessible name matching "${target.text}"`);
+        return uid;
+    }
+}
+// --- parsers for chrome-devtools-mcp's text output -------------------------------
+/** `uid=1_3 link "Learn more" …` → {role:"link", name:"Learn more"} for named rows. */
+export function parseElements(snapshot) {
+    const out = [];
+    for (const line of snapshot.split("\n")) {
+        const m = line.match(/uid=\S+\s+(\w+)\s+"([^"]*)"/);
+        if (m && m[2].trim())
+            out.push({ role: m[1], name: m[2] });
+    }
+    return out;
+}
+/** `uid=1_3 link "Learn more" …` → first uid whose quoted name includes `text`. */
+export function findUidByName(snapshot, text) {
+    const needle = text.toLowerCase();
+    for (const line of snapshot.split("\n")) {
+        const uidMatch = line.match(/uid=(\S+)/);
+        if (!uidMatch)
+            continue;
+        const nameMatch = line.match(/"([^"]*)"/);
+        if (nameMatch && nameMatch[1].toLowerCase().includes(needle)) {
+            return uidMatch[1];
+        }
+    }
+    return undefined;
+}
+/** `reqid=5 GET https://… [200]` → NetworkRequest[]. */
+export function parseNetwork(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const m = line.match(/^reqid=\d+\s+(\w+)\s+(\S+)\s+\[(\d+)\]/);
+        if (m)
+            out.push({ method: m[1], url: m[2], status: Number(m[3]) });
+    }
+    return out;
+}
+/** Console listing → messages. Conservative: only rows naming a known type. */
+export function parseConsole(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const m = line.match(/^\s*(?:msgid=\d+\s+)?(log|debug|info|error|warn|trace|verbose)[:>\s]\s*(.*)$/i);
+        if (m)
+            out.push({ type: m[1].toLowerCase(), text: m[2].trim() });
+    }
+    return out;
+}
+/** Canonicalize a url for comparison: drop a trailing slash and the hash. */
+export function normalizeUrl(u) {
+    try {
+        const url = new URL(u);
+        return `${url.origin}${url.pathname.replace(/\/$/, "")}${url.search}`;
+    }
+    catch {
+        return u.replace(/[/#]+$/, "");
+    }
+}
+/** True only if the page genuinely moved — not just a trailing-slash difference. */
+export function isNavigation(initialUrl, finalUrl) {
+    if (initialUrl === undefined)
+        return true;
+    return normalizeUrl(initialUrl) !== normalizeUrl(finalUrl);
+}
+/** `2: Example Domain (https://example.com/) [selected]` → the selected page's url. */
+export function parseSelectedUrl(text) {
+    for (const line of text.split("\n")) {
+        if (!line.includes("[selected]"))
+            continue;
+        const paren = line.match(/\((https?:\/\/[^)]+)\)/);
+        if (paren)
+            return paren[1];
+        const bare = line.match(/:\s*(\S+)\s*\[selected\]/);
+        if (bare)
+            return bare[1];
+    }
+    return undefined;
+}
+//# sourceMappingURL=chrome.js.map

package/dist/adapters/drivers/chrome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome.js","sourceRoot":"","sources":["../../../src/adapters/drivers/chrome.ts"],"names":[],"mappings":"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"}

package/dist/adapters/drivers/fake.d.ts

@@ -0,0 +1,24 @@
+/** In-memory Driver for tests (no browser); also proves the core is driver-agnostic (invariant #5). */
+import type { Driver } from "../../core/ports.js";
+import type { Evidence, PageElement, Target } from "../../core/types.js";
+export interface FakeScript {
+    evidence: Evidence;
+    elements?: PageElement[];
+    /** Targets (by text) that should throw when acted on, to simulate a broken step. */
+    failOn?: string[];
+}
+export declare class FakeDriver implements Driver {
+    private readonly script;
+    closed: boolean;
+    settled: boolean;
+    readonly visited: string[];
+    readonly clicked: Target[];
+    constructor(script: FakeScript);
+    goto(url: string): Promise<void>;
+    click(target: Target): Promise<void>;
+    type(target: Target, _text: string): Promise<void>;
+    snapshot(): Promise<PageElement[]>;
+    settle(): Promise<void>;
+    observe(): Promise<Evidence>;
+    close(): Promise<void>;
+}

package/dist/adapters/drivers/fake.js

@@ -0,0 +1,37 @@
+export class FakeDriver {
+    script;
+    closed = false;
+    settled = false;
+    visited = [];
+    clicked = [];
+    constructor(script) {
+        this.script = script;
+    }
+    async goto(url) {
+        this.visited.push(url);
+    }
+    async click(target) {
+        if (target.text && this.script.failOn?.includes(target.text)) {
+            throw new Error(`element not found: ${target.text}`);
+        }
+        this.clicked.push(target);
+    }
+    async type(target, _text) {
+        if (target.text && this.script.failOn?.includes(target.text)) {
+            throw new Error(`element not found: ${target.text}`);
+        }
+    }
+    async snapshot() {
+        return this.script.elements ?? [];
+    }
+    async settle() {
+        this.settled = true;
+    }
+    async observe() {
+        return this.script.evidence;
+    }
+    async close() {
+        this.closed = true;
+    }
+}
+//# sourceMappingURL=fake.js.map

package/dist/adapters/drivers/fake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake.js","sourceRoot":"","sources":["../../../src/adapters/drivers/fake.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,UAAU;IAMQ;IAL7B,MAAM,GAAG,KAAK,CAAC;IACf,OAAO,GAAG,KAAK,CAAC;IACP,OAAO,GAAa,EAAE,CAAC;IACvB,OAAO,GAAa,EAAE,CAAC;IAEhC,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,MAAc;QACxB,IAAI,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,KAAa;QACtC,IAAI,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;CACF"}

package/dist/adapters/drivers/self-heal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A Driver decorator (wraps any Driver) that repairs a broken step at replay time — the
+ * sanctioned exception to LLM-free replay (invariant #4). When a frozen target no longer
+ * resolves, the LLM maps the original intent onto a current element, the action is retried,
+ * and the substitution is recorded for re-freezing. No break → no LLM call.
+ */
+import type { Driver, LlmClient } from "../../core/ports.js";
+import type { Evidence, PageElement, SettleOptions, Target } from "../../core/types.js";
+/** A recorded substitution: `original` could not be found, `healedText` was used instead. */
+export interface Heal {
+    original: Target;
+    healedText: string;
+    reason?: string;
+}
+export interface SelfHealOptions {
+    maxHeals?: number;
+}
+/** Parse the heal reply → a chosen element name, or undefined for "none". */
+export declare function parseHealChoice(text: string): string | undefined;
+export declare class SelfHealingDriver implements Driver {
+    private readonly inner;
+    private readonly llm;
+    readonly heals: Heal[];
+    private readonly maxHeals;
+    constructor(inner: Driver, llm: LlmClient, opts?: SelfHealOptions);
+    goto(url: string): Promise<void>;
+    click(target: Target): Promise<void>;
+    type(target: Target, text: string): Promise<void>;
+    snapshot(): Promise<PageElement[]>;
+    settle(options?: SettleOptions): Promise<void>;
+    observe(): Promise<Evidence>;
+    close(): Promise<void>;
+    private heal;
+}

package/dist/adapters/drivers/self-heal.js

@@ -0,0 +1,89 @@
+const HEAL_SYSTEM = "You repair a broken browser test step. A step needs to act on an element described by " +
+    "the original target, but no element with that name exists on the page now. Choose the " +
+    "CURRENT element that best fulfills the original intent, or none if nothing fits. " +
+    'Respond with strict JSON, no prose, no code fences: {"name":"<exact current element name>"} ' +
+    'or {"name":null}.';
+function healPrompt(target, elements) {
+    const want = target.text ?? target.selector ?? "(unknown)";
+    const list = elements
+        .slice(0, 60)
+        .map((e) => `- [${e.role}] ${e.name}`)
+        .join("\n");
+    return [
+        `Original target: ${want}`,
+        ``,
+        `Current interactive elements:`,
+        list || "(none)",
+        ``,
+        `Which current element best matches the original target? JSON only.`,
+    ].join("\n");
+}
+/** Parse the heal reply → a chosen element name, or undefined for "none". */
+export function parseHealChoice(text) {
+    let s = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "");
+    const start = s.indexOf("{");
+    const end = s.lastIndexOf("}");
+    if (start === -1 || end === -1)
+        throw new Error(`no JSON in heal reply: ${text.slice(0, 200)}`);
+    const obj = JSON.parse(s.slice(start, end + 1));
+    return typeof obj.name === "string" && obj.name.trim() ? obj.name : undefined;
+}
+export class SelfHealingDriver {
+    inner;
+    llm;
+    heals = [];
+    maxHeals;
+    constructor(inner, llm, opts = {}) {
+        this.inner = inner;
+        this.llm = llm;
+        this.maxHeals = opts.maxHeals ?? 5;
+    }
+    async goto(url) {
+        return this.inner.goto(url);
+    }
+    async click(target) {
+        try {
+            await this.inner.click(target);
+        }
+        catch (err) {
+            const healed = await this.heal(target, err);
+            await this.inner.click({ text: healed });
+        }
+    }
+    async type(target, text) {
+        try {
+            await this.inner.type(target, text);
+        }
+        catch (err) {
+            const healed = await this.heal(target, err);
+            await this.inner.type({ text: healed }, text);
+        }
+    }
+    snapshot() {
+        return this.inner.snapshot();
+    }
+    settle(options) {
+        return this.inner.settle(options);
+    }
+    observe() {
+        return this.inner.observe();
+    }
+    close() {
+        return this.inner.close();
+    }
+    async heal(target, cause) {
+        if (this.heals.length >= this.maxHeals) {
+            throw new Error(`self-heal budget (${this.maxHeals}) exhausted for ${JSON.stringify(target)}`);
+        }
+        const elements = await this.inner.snapshot();
+        const reply = await this.llm.complete(healPrompt(target, elements), { system: HEAL_SYSTEM });
+        const choice = parseHealChoice(reply);
+        if (!choice) {
+            const why = cause instanceof Error ? cause.message : String(cause);
+            throw new Error(`self-heal found no match for ${JSON.stringify(target)} (${why})`);
+        }
+        this.heals.push({ original: target, healedText: choice });
+        return choice;
+    }
+}
+//# sourceMappingURL=self-heal.js.map