cairn-engine 2.1.0 → 2.2.0

package/README.md

@@ -2,72 +2,179 @@
 
 ![cairn banner](https://raw.githubusercontent.com/team-poem/cairn/main/banner.svg)
 
-The engine behind [cairn](https://github.com/team-poem/cairn) — an AI walks an unfamiliar
-app **once** to discover a browser test and **freezes it into a marker**; from then on it
-replays that path **deterministically, with no LLM in the loop**. When a step breaks or lands
-in the wrong state, the LLM returns to **heal** just that step, then re-freezes. **Discovery is
-paid once; every replay is free.** Model- and browser-agnostic — embed it, or drive it from the `cairn` CLI.
+[![npm](https://img.shields.io/npm/v/cairn-engine.svg)](https://www.npmjs.com/package/cairn-engine)
+[![CI](https://github.com/team-poem/cairn/actions/workflows/ci.yml/badge.svg)](https://github.com/team-poem/cairn/actions/workflows/ci.yml)
+[![types](https://img.shields.io/npm/types/cairn-engine.svg)](https://www.npmjs.com/package/cairn-engine)
+[![license](https://img.shields.io/npm/l/cairn-engine.svg)](https://github.com/team-poem/cairn/blob/main/LICENSE)
+
+**Browser tests you write in plain language — that then run with zero AI in the loop.**
+
+An AI walks your app **once** to discover the flow and **freezes** it. From then on it replays
+**deterministically — no LLM, no hand-written selectors.** When the UI changes and a step breaks,
+the AI returns to **heal just that step**, then re-freezes. A third thing, between two tools you
+already reach for:
+
+- **Scripted (Playwright/Cypress)** — deterministic, but you hand-write selectors that break every redesign.
+- **LLM agents** — plain language, but a slow, costly, flaky model in _every_ run.
+- **cairn** — plain-language authoring **and** deterministic, free, self-healing replay.
+
+## Use it
 
 ```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
+**Author once** — an AI discovers the flow; you freeze it to a file:
+
+```ts
+import { discover, ChromeDevToolsDriver, createLlmClient } from "cairn-engine";
+import { writeFileSync } from "node:fs";
+
+const scenario = await discover(
+  "log in, add the first product, open the cart",
+  {
+    driver: new ChromeDevToolsDriver(),
+    llm: createLlmClient(), // Claude Code if installed, else ANTHROPIC_API_KEY
+    baseUrl: "https://shop.example",
+  },
+);
+writeFileSync("cart.skill.json", JSON.stringify(scenario, null, 2));
 ```
 
-Embed it — every stage is an injected port:
+**Replay forever** — deterministic, no LLM. When the UI drifts, `heal` repairs the step and you
+re-freeze the fixed path:
 
 ```ts
-import { runScenario } from "cairn-engine";
+import { runScenario, loadSkillFile } from "cairn-engine";
+import { writeFileSync } from "node:fs";
+
+const { result, healedScenario } = await runScenario(
+  loadSkillFile("cart.skill.json"),
+  {
+    heal: true, // repair a broken step with the LLM instead of going red
+  },
+);
+
+if (healedScenario) {
+  // the UI changed and cairn adapted — write the repaired path back
+  writeFileSync("cart.skill.json", JSON.stringify(healedScenario, null, 2));
+}
+if (!result.verdict.passed) process.exit(1); // a deterministic gate for CI
+```
+
+Prefer a one-off from the terminal? The same steps are CLI commands —
+`cairn discover … --freeze cart.skill.json` · `cairn replay cart.skill.json` · `… --heal`.
+
+**Models** — set a key and cairn picks the backend: **Anthropic** (`ANTHROPIC_API_KEY`, or a local
+**Claude Code** install with no key), **OpenAI** (`OPENAI_API_KEY`), or **Gemini**
+(`GEMINI_API_KEY`). Force one with `createLlmClient({ backend: "openai" })`, or implement the
+`LlmClient` port for any other model.
+
+## How the loop works
+
+```
+intent ─► discover (LLM, once) ─► cart.skill.json ─► replay (no LLM, forever)
+                                                          │ a step breaks
+                                                          ▼
+                                                  self-heal (LLM, just that step)
+```
 
-const { result } = await runScenario(scenario, { heal: true });
-if (!result.verdict.passed) process.exit(1);
+- **discover** _(LLM · once)_ — observes the live page, picks one action, acts, and repeats until your intent is met. Out comes a `Scenario`.
+- **freeze** — that scenario is plain JSON (`*.skill.json`): a flat list of steps + assertions, each target carrying several locators. No model, no LLM — just data.
+- **replay** _(no LLM)_ — runs the steps through a `Driver`, auto-waiting for the page to settle; a `Critic` rules on three layers of evidence — _did it act_ · _what it looked like_ · _the requests & console_. Same input, same verdict.
+- **heal** _(LLM · only on a break)_ — when a target stops resolving or the outcome diverges, the LLM maps your original step `intent` onto the new page, repairs that one step, retries, and returns a scenario to re-freeze. A green replay never calls it.
+
+Discovery is paid once; regression is free. A frozen scenario is data you can read, diff, and edit
+by hand:
+
+```json
+{
+  "name": "cart",
+  "steps": [
+    { "kind": "goto", "url": "https://shop.example" },
+    {
+      "kind": "type",
+      "target": { "text": "Email" },
+      "text": "you@shop.example"
+    },
+    {
+      "kind": "click",
+      "target": { "text": "Log in" },
+      "intent": "submit the login form",
+      "expect": { "requestStatus": { "urlIncludes": "/auth", "status": 200 } }
+    },
+    { "kind": "click", "target": { "text": "Add to cart" } },
+    { "kind": "click", "target": { "text": "Cart", "role": "link" } },
+    { "kind": "waitFor", "until": { "url": "/cart" } }
+  ],
+  "assertions": [
+    { "kind": "navigated", "to": "/cart" },
+    { "kind": "no-failed-requests" }
+  ]
+}
 ```
 
-Building a UI on top? The engine exposes the seams; you bring the UI:
+Each `target` keeps several locators — `text` (accessible name) first, `role` + `index` as a
+rename-resilient fallback, `selector` as a CSS escape hatch — which is what lets replay survive a
+redesign without falling back to the LLM. The `expect` on a step is its post-condition: replay
+checks it deterministically and only heals if it diverges.
+
+**Measured, not claimed** — a real multi-step checkout, via cairn's `bench/` harness:
+
+- **4/4 deterministic** replays · **0 LLM calls** on replay
+- discovery **~$0.50 once** → every replay after is **$0** (a full LLM agent runs **~$15–30 _per run_**)
+- a renamed button broke hand-written selectors; cairn **healed it and stayed green**
+
+## Build on it
+
+cairn is the machinery — discover · freeze · replay · heal — behind a handful of ports, **general
+in mechanism, specific in meaning.** It's made to be **built on**, not scattered across your
+service as test code. A few things it powers:
+
+- **A QA tool** — non-developers write flows in plain language, then watch them replay & self-heal
+- **A CI regression gate** — frozen flows run on every PR; drift heals instead of going red
+- **A synthetic monitor** — replay critical paths against production, alert only when one truly breaks
+- **A visual-replay app** — the engine streams per-step progress + screenshots; you draw the UI
+
+You _can_ call `runScenario` straight from a test file — nothing stops you. But that isn't the
+point: cairn is **not a Jest or Playwright you write service tests in** — it's the engine those
+kinds of tools are built _from_. Reach for it to **build** testing tooling, not to author a test
+suite by hand.
+
+## Extend it
+
+The core knows no app — **you** supply what "success" means and how to drive the browser. Every
+stage is a replaceable port — your own `Driver` (e.g. Playwright), `Critic`, `Reporter`,
+`ContextProvider` (auth/fixtures), `LlmClient` (any model). Too much for a full port? `custom`
+assertions/actions define success inline:
 
 ```ts
-const controller = new AbortController();
 await runScenario(scenario, {
-  signal: controller.signal,                 // a Stop button
-  screenshots: true,                         // capture a PNG per step
-  onStep: (e) => render(e.index, e.step, e.ok, e.screenshot), // live timeline
+  custom: {
+    "cart-has": (p, ev) =>
+      ev.logic.requests.some((r) => r.url.includes(p.path) && r.status === 200),
+  },
 });
 ```
 
-Make it yours — the engine ships defaults, your product defines the specifics:
+Building a UI on top? The engine streams exactly what a screen needs — wire it up and draw:
 
 ```ts
+const controller = new AbortController();
 await runScenario(scenario, {
-  // success is whatever your product says it is
-  custom: { "cart-has": (p, ev) => ev.logic.requests.some((r) => r.url.includes(p.path) && r.status === 200) },
-  // product-specific interactions, beyond click/type/hover/select/scroll
-  actions: { "drag-slider": async (driver, p) => { /* … */ } },
+  signal: controller.signal, // a Stop button
+  screenshots: true, // a PNG per step
+  onStep: (s) => render(s.index, s.step, s.ok, s.screenshot), // a live timeline
 });
 ```
 
-Every layer is replaceable: bring your own `Driver` (e.g. Playwright), `Critic`, `Reporter`,
-`ContextProvider` (auth / fixtures), or `LlmClient` (any model) — and use `custom`
-assertions / `actions` for what doesn't fit the built-ins. Nothing forces your product
-through only what we decided.
-
-**Browser or extension (no Node)?** `runScenario` and the default Chrome DevTools MCP driver
-need Node. Import the browser-safe core from `cairn-engine/browser` and compose `runHarness`
-with your own `Driver` (e.g. one over `chrome.debugger`) plus a fetch-based `LlmClient`:
-
-```ts
-import { runHarness, StaticPlanner, AssertionCritic, AnthropicLlmClient } from "cairn-engine/browser";
-```
+**Browser / extension (no Node)?** Import the browser-safe core from `cairn-engine/browser` and
+compose `runHarness` with your own `Driver` (e.g. one over `chrome.debugger`) plus a fetch-based
+`LlmClient`.
 
-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.
+## Conventions
 
-**Full docs, design, and the loop diagram:** https://github.com/team-poem/cairn
+Name embedded files `*.agentic.ts` + frozen `*.skill.json` — distinct from `*.test.ts` /
+`*.spec.ts`, stable glob `**/*.agentic.ts`.
 
-MIT
+**Full docs · design · the loop:** https://github.com/team-poem/cairn · MIT

package/dist/adapters/llm/anthropic.js

@@ -1,4 +1,4 @@
-const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+import { postJsonWithRetry } from "./http.js";
 export class AnthropicLlmClient {
     id;
     apiKey;
@@ -18,58 +18,39 @@ export class AnthropicLlmClient {
         this.id = `anthropic:${this.model}`;
     }
     async complete(prompt, opts = {}) {
-        const body = JSON.stringify({
-            model: this.model,
-            max_tokens: opts.maxTokens ?? 1024,
-            // #15 — cache the (constant) system prompt so repeated discover steps don't re-bill it.
-            ...(opts.system
-                ? { system: [{ type: "text", text: opts.system, cache_control: { type: "ephemeral" } }] }
-                : {}),
-            messages: [{ role: "user", content: prompt }],
+        const data = await postJsonWithRetry(`${this.baseUrl}/v1/messages`, {
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": this.apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify({
+                model: this.model,
+                max_tokens: opts.maxTokens ?? 1024,
+                // #15 — cache the (constant) system prompt so repeated discover steps don't re-bill it.
+                ...(opts.system
+                    ? {
+                        system: [
+                            {
+                                type: "text",
+                                text: opts.system,
+                                cache_control: { type: "ephemeral" },
+                            },
+                        ],
+                    }
+                    : {}),
+                messages: [{ role: "user", content: prompt }],
+            }),
+        }, {
+            timeoutMs: this.timeoutMs,
+            maxRetries: this.maxRetries,
+            label: "Anthropic",
         });
-        for (let attempt = 0;; attempt++) {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-            try {
-                const res = await fetch(`${this.baseUrl}/v1/messages`, {
-                    method: "POST",
-                    headers: {
-                        "content-type": "application/json",
-                        "x-api-key": this.apiKey,
-                        "anthropic-version": "2023-06-01",
-                    },
-                    body,
-                    signal: controller.signal,
-                });
-                if (res.ok) {
-                    const data = (await res.json());
-                    return (data.content ?? [])
-                        .filter((c) => c.type === "text" && typeof c.text === "string")
-                        .map((c) => c.text)
-                        .join("")
-                        .trim();
-                }
-                // Back off on transient errors (rate limit / overloaded / server), else fail.
-                if ((res.status === 429 || res.status >= 500) && attempt < this.maxRetries) {
-                    await delay(500 * 2 ** attempt);
-                    continue;
-                }
-                throw new Error(`Anthropic API ${res.status}: ${await res.text()}`);
-            }
-            catch (err) {
-                const aborted = err instanceof Error && err.name === "AbortError";
-                if (aborted && attempt >= this.maxRetries)
-                    throw new Error(`Anthropic request timed out after ${this.timeoutMs}ms`);
-                if (aborted) {
-                    await delay(500 * 2 ** attempt);
-                    continue;
-                }
-                throw err;
-            }
-            finally {
-                clearTimeout(timer);
-            }
-        }
+        return (data.content ?? [])
+            .filter((c) => c.type === "text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("")
+            .trim();
     }
 }
 //# sourceMappingURL=anthropic.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../../src/adapters/llm/anthropic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../../src/adapters/llm/anthropic.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAgB9C,MAAM,OAAO,kBAAkB;IACpB,EAAE,CAAS;IACH,MAAM,CAAS;IACf,KAAK,CAAS;IACd,OAAO,CAAS;IAChB,SAAS,CAAS;IAClB,UAAU,CAAS;IAEpC,YAAY,OAAyB,EAAE;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC5D,IAAI,CAAC,MAAM;YACT,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,mBAAmB,CAAC;QAC/C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,2BAA2B,CAAC;QAC3D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,EAAE,GAAG,aAAa,IAAI,CAAC,KAAK,EAAE,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,OAAwB,EAAE;QACvD,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAClC,GAAG,IAAI,CAAC,OAAO,cAAc,EAC7B;YACE,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,MAAM;gBACxB,mBAAmB,EAAE,YAAY;aAClC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,UAAU,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;gBAClC,wFAAwF;gBACxF,GAAG,CAAC,IAAI,CAAC,MAAM;oBACb,CAAC,CAAC;wBACE,MAAM,EAAE;4BACN;gCACE,IAAI,EAAE,MAAM;gCACZ,IAAI,EAAE,IAAI,CAAC,MAAM;gCACjB,aAAa,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;6BACrC;yBACF;qBACF;oBACH,CAAC,CAAC,EAAE,CAAC;gBACP,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;aAC9C,CAAC;SACH,EACD;YACE,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,WAAW;SACnB,CACF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;aACxB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;aAC9D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aAClB,IAAI,CAAC,EAAE,CAAC;aACR,IAAI,EAAE,CAAC;IACZ,CAAC;CACF"}

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

@@ -1,8 +1,12 @@
-/** Picks the LLM backend (invariant #5): the API if ANTHROPIC_API_KEY is set, else local Claude Code. */
+/**
+ * Picks the LLM backend (invariant #5). An explicit `backend` wins; otherwise the first provider
+ * whose API key is present, in order Anthropic → OpenAI → Gemini, falling back to local Claude Code.
+ */
 import type { LlmClient } from "../../core/ports.js";
+export type LlmBackend = "anthropic" | "openai" | "gemini" | "claude-code";
 export interface LlmFactoryOptions {
     /** Force a backend regardless of environment. */
-    backend?: "anthropic" | "claude-code";
+    backend?: LlmBackend;
     model?: string;
 }
 export declare function createLlmClient(opts?: LlmFactoryOptions): LlmClient;

package/dist/adapters/llm/factory.js

@@ -1,9 +1,27 @@
 import { AnthropicLlmClient } from "./anthropic.js";
 import { ClaudeCodeLlmClient } from "./claude-code.js";
+import { GeminiLlmClient } from "./gemini.js";
+import { OpenAILlmClient } from "./openai.js";
+function detectBackend() {
+    if (process.env.ANTHROPIC_API_KEY)
+        return "anthropic";
+    if (process.env.OPENAI_API_KEY)
+        return "openai";
+    if (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY)
+        return "gemini";
+    return "claude-code";
+}
 export function createLlmClient(opts = {}) {
-    const backend = opts.backend ?? (process.env.ANTHROPIC_API_KEY ? "anthropic" : "claude-code");
-    return backend === "anthropic"
-        ? new AnthropicLlmClient({ model: opts.model })
-        : new ClaudeCodeLlmClient({ model: opts.model });
+    const backend = opts.backend ?? detectBackend();
+    switch (backend) {
+        case "openai":
+            return new OpenAILlmClient({ model: opts.model });
+        case "gemini":
+            return new GeminiLlmClient({ model: opts.model });
+        case "claude-code":
+            return new ClaudeCodeLlmClient({ model: opts.model });
+        default:
+            return new AnthropicLlmClient({ model: opts.model });
+    }
 }
 //# sourceMappingURL=factory.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/adapters/llm/factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAQvD,MAAM,UAAU,eAAe,CAAC,OAA0B,EAAE;IAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC9F,OAAO,OAAO,KAAK,WAAW;QAC5B,CAAC,CAAC,IAAI,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/C,CAAC,CAAC,IAAI,mBAAmB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/adapters/llm/factory.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAU9C,SAAS,aAAa;IACpB,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB;QAAE,OAAO,WAAW,CAAC;IACtD,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO,QAAQ,CAAC;IAChD,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO,QAAQ,CAAC;IAC9E,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAA0B,EAAE;IAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,aAAa,EAAE,CAAC;IAChD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,QAAQ;YACX,OAAO,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACpD,KAAK,QAAQ;YACX,OAAO,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACpD,KAAK,aAAa;YAChB,OAAO,IAAI,mBAAmB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACxD;YACE,OAAO,IAAI,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,21 @@
+/**
+ * LlmClient backed by the Google Gemini API (GEMINI_API_KEY / GOOGLE_API_KEY). Uses fetch — no SDK.
+ */
+import type { CompleteOptions, LlmClient } from "../../core/ports.js";
+export interface GeminiOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+export declare class GeminiLlmClient implements LlmClient {
+    readonly id: string;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly timeoutMs?;
+    private readonly maxRetries?;
+    constructor(opts?: GeminiOptions);
+    complete(prompt: string, opts?: CompleteOptions): Promise<string>;
+}

package/dist/adapters/llm/gemini.js

@@ -0,0 +1,44 @@
+import { postJsonWithRetry } from "./http.js";
+export class GeminiLlmClient {
+    id;
+    apiKey;
+    model;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY;
+        if (!apiKey)
+            throw new Error("GeminiLlmClient requires GEMINI_API_KEY");
+        this.apiKey = apiKey;
+        this.model = opts.model ?? "gemini-2.0-flash";
+        this.baseUrl = opts.baseUrl ?? "https://generativelanguage.googleapis.com";
+        this.timeoutMs = opts.timeoutMs;
+        this.maxRetries = opts.maxRetries;
+        this.id = `gemini:${this.model}`;
+    }
+    async complete(prompt, opts = {}) {
+        const data = await postJsonWithRetry(`${this.baseUrl}/v1beta/models/${this.model}:generateContent`, {
+            headers: {
+                "content-type": "application/json",
+                "x-goog-api-key": this.apiKey,
+            },
+            body: JSON.stringify({
+                ...(opts.system
+                    ? { systemInstruction: { parts: [{ text: opts.system }] } }
+                    : {}),
+                contents: [{ role: "user", parts: [{ text: prompt }] }],
+                generationConfig: { maxOutputTokens: opts.maxTokens ?? 1024 },
+            }),
+        }, {
+            timeoutMs: this.timeoutMs,
+            maxRetries: this.maxRetries,
+            label: "Gemini",
+        });
+        return (data.candidates?.[0]?.content?.parts ?? [])
+            .map((p) => p.text ?? "")
+            .join("")
+            .trim();
+    }
+}
+//# sourceMappingURL=gemini.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../../src/adapters/llm/gemini.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAc9C,MAAM,OAAO,eAAe;IACjB,EAAE,CAAS;IACH,MAAM,CAAS;IACf,KAAK,CAAS;IACd,OAAO,CAAS;IAChB,SAAS,CAAU;IACnB,UAAU,CAAU;IAErC,YAAY,OAAsB,EAAE;QAClC,MAAM,MAAM,GACV,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;QAC1E,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC;QAC9C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,2CAA2C,CAAC;QAC3E,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,EAAE,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,OAAwB,EAAE;QACvD,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAClC,GAAG,IAAI,CAAC,OAAO,kBAAkB,IAAI,CAAC,KAAK,kBAAkB,EAC7D;YACE,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,gBAAgB,EAAE,IAAI,CAAC,MAAM;aAC9B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,GAAG,CAAC,IAAI,CAAC,MAAM;oBACb,CAAC,CAAC,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;oBAC3D,CAAC,CAAC,EAAE,CAAC;gBACP,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;gBACvD,gBAAgB,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,EAAE;aAC9D,CAAC;SACH,EACD;YACE,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,QAAQ;SAChB,CACF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;aACxB,IAAI,CAAC,EAAE,CAAC;aACR,IAAI,EAAE,CAAC;IACZ,CAAC;CACF"}

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

@@ -0,0 +1,12 @@
+export interface HttpRetryOptions {
+    /** Per-request timeout (ms). Default 60s — a stalled connection rejects instead of hanging. */
+    timeoutMs?: number;
+    /** Retries on transient errors (429 / 5xx / timeout). Default 2. */
+    maxRetries?: number;
+    /** Provider name for error messages, e.g. "Anthropic". */
+    label?: string;
+}
+export declare function postJsonWithRetry<T>(url: string, init: {
+    headers: Record<string, string>;
+    body: string;
+}, opts?: HttpRetryOptions): Promise<T>;

package/dist/adapters/llm/http.js

@@ -0,0 +1,45 @@
+/**
+ * Shared POST-JSON transport for the HTTP-based LlmClient adapters (Anthropic, OpenAI, Gemini):
+ * a per-request timeout plus exponential back-off on transient failures (429 / 5xx / timeout).
+ * Each adapter builds its own request body and parses its own response shape.
+ */
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function postJsonWithRetry(url, init, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const maxRetries = opts.maxRetries ?? 2;
+    const label = opts.label ?? "LLM";
+    for (let attempt = 0;; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: init.headers,
+                body: init.body,
+                signal: controller.signal,
+            });
+            if (res.ok)
+                return (await res.json());
+            // Back off on transient errors (rate limit / overloaded / server), else fail.
+            if ((res.status === 429 || res.status >= 500) && attempt < maxRetries) {
+                await delay(500 * 2 ** attempt);
+                continue;
+            }
+            throw new Error(`${label} API ${res.status}: ${await res.text()}`);
+        }
+        catch (err) {
+            const aborted = err instanceof Error && err.name === "AbortError";
+            if (aborted && attempt >= maxRetries)
+                throw new Error(`${label} request timed out after ${timeoutMs}ms`);
+            if (aborted) {
+                await delay(500 * 2 ** attempt);
+                continue;
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=http.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/adapters/llm/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAC1C,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAWxC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,IAAuD,EACvD,OAAyB,EAAE;IAE3B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;IAElC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,IAAI,GAAG,CAAC,EAAE;gBAAE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;YAC3C,8EAA8E;YAC9E,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;gBACtE,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,GAAG,CAAC,MAAM,KAAK,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;YAClE,IAAI,OAAO,IAAI,OAAO,IAAI,UAAU;gBAClC,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,4BAA4B,SAAS,IAAI,CAAC,CAAC;YACrE,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,21 @@
+/**
+ * LlmClient backed by the OpenAI Chat Completions API (OPENAI_API_KEY). Uses fetch — no SDK.
+ */
+import type { CompleteOptions, LlmClient } from "../../core/ports.js";
+export interface OpenAIOptions {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+export declare class OpenAILlmClient implements LlmClient {
+    readonly id: string;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly timeoutMs?;
+    private readonly maxRetries?;
+    constructor(opts?: OpenAIOptions);
+    complete(prompt: string, opts?: CompleteOptions): Promise<string>;
+}

package/dist/adapters/llm/openai.js

@@ -0,0 +1,43 @@
+import { postJsonWithRetry } from "./http.js";
+export class OpenAILlmClient {
+    id;
+    apiKey;
+    model;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? process.env.OPENAI_API_KEY;
+        if (!apiKey)
+            throw new Error("OpenAILlmClient requires OPENAI_API_KEY");
+        this.apiKey = apiKey;
+        this.model = opts.model ?? "gpt-4o";
+        this.baseUrl = opts.baseUrl ?? "https://api.openai.com";
+        this.timeoutMs = opts.timeoutMs;
+        this.maxRetries = opts.maxRetries;
+        this.id = `openai:${this.model}`;
+    }
+    async complete(prompt, opts = {}) {
+        const messages = [];
+        if (opts.system)
+            messages.push({ role: "system", content: opts.system });
+        messages.push({ role: "user", content: prompt });
+        const data = await postJsonWithRetry(`${this.baseUrl}/v1/chat/completions`, {
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: this.model,
+                max_tokens: opts.maxTokens ?? 1024,
+                messages,
+            }),
+        }, {
+            timeoutMs: this.timeoutMs,
+            maxRetries: this.maxRetries,
+            label: "OpenAI",
+        });
+        return (data.choices?.[0]?.message?.content ?? "").trim();
+    }
+}
+//# sourceMappingURL=openai.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../../src/adapters/llm/openai.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAc9C,MAAM,OAAO,eAAe;IACjB,EAAE,CAAS;IACH,MAAM,CAAS;IACf,KAAK,CAAS;IACd,OAAO,CAAS;IAChB,SAAS,CAAU;IACnB,UAAU,CAAU;IAErC,YAAY,OAAsB,EAAE;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;QACzD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,wBAAwB,CAAC;QACxD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,EAAE,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,OAAwB,EAAE;QACvD,MAAM,QAAQ,GAA6C,EAAE,CAAC;QAC9D,IAAI,IAAI,CAAC,MAAM;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAEjD,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAClC,GAAG,IAAI,CAAC,OAAO,sBAAsB,EACrC;YACE,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,UAAU,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;gBAClC,QAAQ;aACT,CAAC;SACH,EACD;YACE,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,QAAQ;SAChB,CACF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,CAAC;CACF"}

package/dist/browser.d.ts

@@ -22,6 +22,8 @@ export { FakeDriver } from "./adapters/drivers/fake.js";
 export { SelfHealingDriver, parseHealChoice } from "./adapters/drivers/self-heal.js";
 export type { Heal, SelfHealOptions } from "./adapters/drivers/self-heal.js";
 export { AnthropicLlmClient } from "./adapters/llm/anthropic.js";
+export { OpenAILlmClient } from "./adapters/llm/openai.js";
+export { GeminiLlmClient } from "./adapters/llm/gemini.js";
 export { discover, parseDecision } from "./core/discover.js";
 export type { DiscoverOptions, Decision } from "./core/discover.js";
 export { LlmStepHealer } from "./core/step-heal.js";

package/dist/browser.js

@@ -19,6 +19,8 @@ export { ConsoleReporter } from "./adapters/reporters/console.js";
 export { FakeDriver } from "./adapters/drivers/fake.js";
 export { SelfHealingDriver, parseHealChoice } from "./adapters/drivers/self-heal.js";
 export { AnthropicLlmClient } from "./adapters/llm/anthropic.js";
+export { OpenAILlmClient } from "./adapters/llm/openai.js";
+export { GeminiLlmClient } from "./adapters/llm/gemini.js";
 export { discover, parseDecision } from "./core/discover.js";
 export { LlmStepHealer } from "./core/step-heal.js";
 export { scoreTarget, scoreScenario, weakTargets } from "./core/freeze.js";

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE7F,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE7F,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.d.ts

@@ -20,7 +20,10 @@ export { SelfHealingDriver, parseHealChoice } from "./adapters/drivers/self-heal
 export type { Heal, SelfHealOptions } from "./adapters/drivers/self-heal.js";
 export { ClaudeCodeLlmClient } from "./adapters/llm/claude-code.js";
 export { AnthropicLlmClient } from "./adapters/llm/anthropic.js";
+export { OpenAILlmClient } from "./adapters/llm/openai.js";
+export { GeminiLlmClient } from "./adapters/llm/gemini.js";
 export { createLlmClient } from "./adapters/llm/factory.js";
+export type { LlmBackend, LlmFactoryOptions } from "./adapters/llm/factory.js";
 export { FileSkillStore, loadSkillFile } from "./adapters/skills/file-store.js";
 export { discover, parseDecision } from "./core/discover.js";
 export type { DiscoverOptions, Decision } from "./core/discover.js";

package/dist/index.js

@@ -16,6 +16,8 @@ export { ChromeDevToolsDriver } from "./adapters/drivers/chrome.js";
 export { SelfHealingDriver, parseHealChoice } from "./adapters/drivers/self-heal.js";
 export { ClaudeCodeLlmClient } from "./adapters/llm/claude-code.js";
 export { AnthropicLlmClient } from "./adapters/llm/anthropic.js";
+export { OpenAILlmClient } from "./adapters/llm/openai.js";
+export { GeminiLlmClient } from "./adapters/llm/gemini.js";
 export { createLlmClient } from "./adapters/llm/factory.js";
 export { FileSkillStore, loadSkillFile } from "./adapters/skills/file-store.js";
 export { discover, parseDecision } from "./core/discover.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-engine",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "An engine for self-healing E2E browser tests — discovered once by an AI, replayed deterministically.",
   "keywords": [
     "e2e",