verikun 0.4.1 → 0.7.0

package/README.md

@@ -1,13 +1,14 @@
 # verikun
 
-Drive a connected Android device/emulator (and, later, iOS simulators) the way
+Drive a connected Android device/emulator or iOS simulator the way
 Puppeteer drives a browser — **tap, type, swipe, screenshot**, and most
 importantly **inspect the UI hierarchy by semantic identifiers** so an AI agent
 can act and then *verify* what happened.
 
-It is a thin, deterministic, zero-runtime-dependency wrapper over `adb` (and
-`xcrun simctl` for iOS) that turns the raw `uiautomator` dump into a compact,
-token-efficient list of meaningful elements addressable by `resource-id`,
+It is a thin, deterministic, zero-runtime-dependency wrapper over `adb` (Android)
+and `idb` + `xcrun simctl` (iOS) that turns the raw `uiautomator` dump (Android)
+or `idb ui describe-all` accessibility tree (iOS) into a compact, token-efficient
+list of meaningful elements addressable by `resource-id` / accessibility id,
 visible text, accessibility label, or class.
 
 ```
@@ -78,7 +79,8 @@ vk screenshot                   # -> ./.verikun/screen.png
 | `swipe --from x,y --to x,y [--duration ms]` | Explicit swipe between two points. |
 | `screenshot [--out path] [--more] [--max px] [--full] [--json]` | Save a PNG (default `./.verikun/screen.png`); prints the path. [Downscaled](#screenshots) to a 700px longest edge by default to save tokens; `--more` bumps detail, `--max px` sets an exact cap, `--full` keeps the original. |
 | `launch <app> [--clear] [--no-restart]` / `stop <app>` | App lifecycle by package id (Android) / bundle id (iOS). `launch` **restarts by default** — it force-stops the app first (a no-op if it isn't running) so a rerun starts fresh instead of resurfacing a still-running instance's current screen; `--no-restart` skips that. `--clear` also wipes the app's local data (login/session, prefs, cache) for a fresh-install start. |
-| `clear <app>` | Wipe the app's locally stored data — login/session, preferences, caches — resetting it to a just-installed state (Android `pm clear`, which also force-stops the app). iOS not supported yet. |
+| `clear <app>` | Wipe the app's locally stored data — login/session, preferences, caches — resetting it to a just-installed state (Android `pm clear`, which also force-stops the app). iOS unsupported: there is no per-app data reset. |
+| `install <app.apk\|.ipa> [--server url]` | Install a build on the device (`adb install -r` / `idb install`). With `--server`, the file is uploaded to a remote [`vk server`](#remote-devices--vk-server) started with `--allow-install` (single-file `.apk`/`.ipa`, sha256-verified). |
 
 ### Batch
 | Command | Description |
@@ -88,7 +90,13 @@ vk screenshot                   # -> ./.verikun/screen.png
 ### AI
 | Command | Description |
 |---|---|
-| `ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--cost-override in/out] [--effort e] [--package pkg] [--app-build id] [--show-plan] [--recompile] [--json]` | Run a plain-English test: compile it to a deterministic plan once, replay it model-free, and self-heal failures via the model. Needs `ANTHROPIC_API_KEY`. See [AI](#ai--natural-language-tests). |
+| `ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--cost-override in/out] [--effort e] [--package pkg] [--app-build id] [--server url] [--show-plan] [--recompile] [--json]` | Run a plain-English test: compile it to a deterministic plan once, replay it model-free, and self-heal failures via the model. Needs `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (per model). See [AI](#ai--natural-language-tests). |
+| `suite <dir> [--app <id>] [--name n] [--server url] [--json]` (+ all `ai` flags) | Run every `*.md` in `<dir>` as one sequential suite with an overview report and a non-zero exit on failure — the CI gate. See [Suites](#suites--run-a-directory-of-tests). |
+
+### Remote
+| Command | Description |
+|---|---|
+| `server [--bind addr] [--port n] [--auth-key k] [--allow-install] [--allow-unsafe-anonymous]` | Expose this machine's connected device to remote verikun clients (`ai`/`suite`/`install --server`). Auth is mandatory unless explicitly disabled; only verikun's validated command grammar is executable. See [Remote devices](#remote-devices--vk-server). |
 
 ### Environment
 | Command | Description |
@@ -189,7 +197,7 @@ printf 'launch com.example.app\nassert @home_tab\nrun archive smoke\n' | vk batc
 with no model calls on the happy path**. The model is woken only to *repair* a step
 whose selector stops resolving; a green run persists the repaired plan, so the next
 run is free again. That is what keeps a CI suite's steady-state token cost near zero.
-Needs `ANTHROPIC_API_KEY`.
+Needs `ANTHROPIC_API_KEY` (Claude models) or `OPENAI_API_KEY` (OpenAI models).
 
 ```sh
 # onboarding.md (plain English):
@@ -217,12 +225,110 @@ a hard iteration cap and stop early if the screen stops changing.
   $3)** or the wall-clock passes **`--timeout` (default 15m)** — so a runaway loop or
   repair can't spend or hang without limit. `--cost-override <input/output>` overrides
   the bundled per-1M price table if it drifts.
-- **`--model`** picks the model (`claude-haiku-4-5` · `claude-sonnet-4-6` (default) ·
-  `claude-opus-4-8` · `claude-fable-5`); **`--recompile`** ignores the cache.
+- **`--model`** picks the model and its provider — Anthropic (`claude-haiku-4-5` ·
+  `claude-sonnet-4-6` (default) · `claude-opus-4-8` · `claude-fable-5`) or OpenAI
+  (`gpt-5.4-mini` · `gpt-5.4` · `gpt-5.5`), each read from its own key
+  (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`); **`--recompile`** ignores the cache.
 - An `ai` run records like any other flow, so it produces the same JUnit + HTML report —
   with the cost line and any **suggested test improvements** (workarounds the model
   applied, which you can fold back into the prose to stabilize the test and cut tokens).
 
+## Suites — run a directory of tests
+
+`vk suite <dir>` runs every `*.md` in a directory through the [`vk ai`](#ai--natural-language-tests)
+engine, sequentially, against one shared device (local or [remote](#remote-devices--vk-server)):
+
+```sh
+vk suite tests/ --app com.example.app          # local device
+vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"   # remote device
+```
+
+- **Ordering is lexicographic** — prefix files `01-…`, `02-…` to sequence them.
+  `README.md` is skipped (it documents the suite, it isn't a test).
+- **Isolation between tests:** with `--app <id>`, the app's data is cleared before
+  each test (`pm clear`; iOS degrades to a force-stop since it has no per-app
+  reset). Without `--app`, make each test self-isolating (start with
+  `launch <pkg> --clear` in the prose).
+- **Each test is a full `vk ai` run** — plan cache, self-healing, cost budget, and
+  its own archived JUnit + HTML report under `./.verikun/runs/<id>/`. A test that
+  fails (or errors) doesn't stop the suite; the rest still run.
+- **The suite writes an overview** to `./.verikun/suites/<id>/`:
+  - **`index.json`** — a stable, `schemaVersion`ed manifest: per-test pass/fail,
+    steps, model repairs, cost, duration, and the run id, plus suite totals. This
+    is the **output contract for reporting** — upload/publish steps compose over
+    it (see the [CI recipe](#ci-recipe)) instead of verikun growing upload plugins.
+  - **`index.html`** — a summary page linking every test's `report.html`.
+- **Exit code is the CI gate:** `1` if any test failed, `0` all green, `2` bad/empty
+  directory. All `ai` flags (`--model`, `--max-cost-usd`, `--timeout`, …) apply to
+  every test; the model's key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`) is checked
+  up front.
+
+## Remote devices — `vk server`
+
+CI runners don't have your phone plugged into them. `vk server` exposes a
+locally-connected device to remote verikun clients so a **disposable CI runner**
+can drive it — without a self-hosted runner executing arbitrary PR code on the
+machine that owns the device:
+
+```sh
+# On the machine with the device attached:
+export VERIKUN_SERVER_AUTH_KEY=$(openssl rand -base64 32)   # or let vk generate one
+vk server --allow-install                    # 127.0.0.1:8391 by default
+vk server --bind 100.64.0.7 --allow-install  # expose on a tailnet IP
+
+# From anywhere that can reach it:
+export VERIKUN_SERVER=http://100.64.0.7:8391
+export VERIKUN_SERVER_AUTH_KEY=<the same key>
+vk install ./app-debug.apk --server "$VERIKUN_SERVER"
+vk ai onboarding.md --server "$VERIKUN_SERVER"
+vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"
+```
+
+**Split execution.** The client runs the whole `vk ai` engine — compile, plan
+cache, repairs, the Anthropic key, run recording, suite aggregation — and only
+**validated device commands** cross the network, one HTTP round-trip per command
+(selector auto-wait polls on the server, next to the device). Each step's detail
+(selector, heal tier, resolved element, failure screenshot + hierarchy) returns
+with the response and is spliced into the client's run, so the archived report is
+identical to a local run's.
+
+**Security model** (the server is the boundary, not the transport):
+
+- **Auth is mandatory.** Pass a key via `--auth-key` / `VERIKUN_SERVER_AUTH_KEY`
+  (the env var keeps it out of `ps`), or one is generated and printed at startup.
+  Clients send it as a bearer token; comparison is constant-time.
+  `--allow-unsafe-anonymous` disables auth loudly — only for networks that are
+  themselves the boundary (e.g. a private tailnet), and it cannot be combined
+  with a key.
+- **Only the validated grammar runs.** Every `/v1/exec` request passes the same
+  `validateNode` gate that guards `vk ai` model repairs: action verbs only
+  (`tap`/`text`/`assert`/`launch`/…), never `ui`/`log`, never a shell. The
+  device and platform are fixed when the server starts — client flags cannot
+  repoint them.
+- **Installs are opt-in.** `POST /v1/install` requires `--allow-install` (a
+  read-only server refuses builds), accepts only single-file `.apk`/`.ipa`
+  uploads to a server-generated temp path (never a client path), and verifies a
+  sha256 of the body.
+- **One run at a time.** A run-token holds the device lock; a second concurrent
+  caller gets `409`. The lock is released when the command finishes (so
+  `vk install` then `vk suite` chain seamlessly), and an idle lock (5 min
+  silent) is taken over, so a crashed CI job can't wedge the device.
+- **Bind is loopback by default.** `--bind <addr>` opts into exposure. For a
+  NAT'd box, [Tailscale](https://tailscale.com) is the recommended transport; for
+  a public host, terminate TLS in front (the server itself speaks plain HTTP).
+- Failure evidence (screenshots, UI hierarchies) crosses the authenticated
+  channel like the rest — same caveat as `vk log`: device output is not redacted.
+
+### CI recipe
+
+[`.github/workflows/suite.yml`](.github/workflows/suite.yml) is a working
+reference: a plain `ubuntu-latest` job builds verikun, installs the app build on
+the remote device (`vk install --server`), runs `vk suite --server`, uploads
+`.verikun/suites` + `.verikun/runs` as artifacts, and **fails the job when any
+test fails** (the suite's exit code). Publishing anywhere else is a composable
+step over the `index.json` manifest — the workflow includes commented `rclone`
+(Google Drive) and `aws s3 cp` examples.
+
 ## Selectors
 
 ```
@@ -280,6 +386,8 @@ condition as a step in its own right.
 | `-d, --device <serial>` | Target a specific device (or `VERIKUN_DEVICE` / `ANDROID_SERIAL`). |
 | `-p, --platform <android\|ios>` | Platform (default `android`). `--ios` / `--android` are shortcuts. |
 | `-j, --json` | Machine-readable output (also serializes errors). |
+| `--server <url>` | For `ai`/`suite`/`install`: run against a remote [`vk server`](#remote-devices--vk-server) (or `VERIKUN_SERVER`). The server's device/platform apply. |
+| `--auth-key <k>` | Key for `--server` (or `VERIKUN_SERVER_AUTH_KEY`, which keeps it out of `ps`). |
 | `--` | End flag parsing, so text/arguments may start with `-`. |
 
 ## Exit codes
@@ -319,9 +427,10 @@ Failure-evidence captures in test-run reports stay full-resolution for debugging
 ## How it works
 
 ```
-cli.ts ──> drivers/ ──> adb / xcrun        (platform I/O)
+cli.ts ──> drivers/ ──> adb (Android) / idb + simctl (iOS)   (platform I/O)
    │           └─ produces normalized Element[]
    ├─ ui/android-parse.ts   uiautomator XML -> Element[]
+   ├─ ui/ios-parse.ts       idb describe-all JSON -> Element[]
    ├─ ui/selector.ts        @id / text: / desc: / class: matching
    └─ ui/format.ts          compact / tree / json rendering
 ```
@@ -332,30 +441,39 @@ selector, formatting, and command layers operate only on the normalized
 
 - **Android** (`drivers/adb.ts`): `uiautomator dump` for the hierarchy,
   `screencap -p` for screenshots, `input tap/text/swipe/keyevent`, `wm size`.
-- **iOS** (`drivers/simctl.ts`): `screenshot`, `launch`, `stop` work today via
-  `xcrun simctl`. Full interaction and hierarchy inspection are planned via
-  WebDriverAgent — see [iOS roadmap](#ios-roadmap) below.
+- **iOS** (`drivers/ios.ts`): `idb ui describe-all` for the hierarchy,
+  `idb ui tap/text/swipe/key/button` for interaction, `idb describe` for screen
+  size; simulator `screenshot`/`launch`/`stop`/`log` stay on `xcrun simctl` (no
+  idb needed for those). See [iOS setup](#ios-setup) below.
 
 Run artifacts (screenshots, dumps) are written under `./.verikun/` (gitignored).
 
-## iOS roadmap
+## iOS setup
 
-Today `vk --ios` supports **screenshots, launch, and stop** via `xcrun simctl`.
-Tapping, swiping, typing, and `vk ui` hierarchy inspection are not yet wired up.
+`vk --ios` reaches feature parity with Android — `ui`/`find`, `tap`, `text`/`type`,
+`swipe`, `key`, `assert`, `wait`, `screenshot`, `launch`/`stop`, plus `vk batch`,
+`vk ai`, and the JUnit/HTML reports — on both simulators and physical devices.
 
-The planned backend is **[WebDriverAgent](https://github.com/appium/WebDriverAgent)**
-(WDA) — an open-source XCTest HTTP server maintained by the Appium team. It
-requires no Python and works on both simulators and physical devices. Once WDA
-is running, `vk` will drive it over HTTP and the command layer stays unchanged.
+Everything interactive is powered by **[`idb`](https://github.com/facebook/idb)**
+(Facebook's iOS Development Bridge), a CLI shelled one-shot exactly like `adb`, so
+verikun stays zero-runtime-dependency and one-process-per-command. Install it once:
 
-**One-time setup (when this lands):**
-1. Clone WebDriverAgent and open it in Xcode
-2. Set your Apple developer signing team
-3. Build & run on the target device or simulator
-4. `vk --ios tap`, `vk --ios ui`, etc. will work automatically
+```sh
+brew tap facebook/fb && brew install idb-companion   # the companion daemon
+pip install fb-idb                                    # the idb CLI (needs Python 3.6+)
+```
 
-Until then, running any unsupported iOS command prints an explanation and exits
-with code 3.
+Then boot a simulator (Simulator.app, or `xcrun simctl boot <name>`) and check
+your setup with `vk doctor --ios`. `vk --ios tap`, `vk --ios ui`, etc. then work.
+
+**Caveats (documented limitations, not bugs):**
+- `clear` is unsupported — iOS has no per-app data reset (uninstall + reinstall is
+  the manual equivalent, but it removes the app too). Exits 3 with an explanation.
+- `current` returns `(unknown)` — iOS exposes no reliable foreground-app query.
+- `swipe` duration is not honored (idb has no millisecond duration knob).
+- `log` capture is simulator-only (via `log show`); for a physical device use
+  Console.app or `idb log` directly.
+- `--tree` renders flat — idb's accessibility list has no nesting depth.
 
 ## Using it from an AI agent
 

package/dist/agent/cost.js

@@ -1,23 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CostTracker = exports.DEFAULT_MAX_COST_USD = exports.DEFAULT_MODEL = exports.ALLOWED_MODELS = exports.MODEL_PRICES = void 0;
+exports.providerFor = providerFor;
 exports.resolveModel = resolveModel;
 exports.parseCostOverride = parseCostOverride;
 exports.priceFor = priceFor;
 exports.estimateCostUsd = estimateCostUsd;
 const errors_1 = require("../errors");
-// Per-1M-token prices (Anthropic, cached 2026-05-26). This table WILL drift as
-// pricing changes between releases — `--cost-override <input/output>` is the escape
-// hatch, and is authoritative when supplied. The --model allowlist is exactly the
-// keys of this table, so the two can never disagree.
-exports.MODEL_PRICES = {
-    'claude-haiku-4-5': { input: 1, output: 5 },
-    'claude-sonnet-4-6': { input: 3, output: 15 },
-    'claude-opus-4-8': { input: 5, output: 25 },
-    'claude-fable-5': { input: 10, output: 50 },
+// Per-1M-token prices + owning provider — the SINGLE source of truth. MODEL_PRICES,
+// ALLOWED_MODELS and providerFor all derive from this, so the --model allowlist, its
+// price and its backend can never disagree. Prices WILL drift between releases
+// (Anthropic cached 2026-05-26; OpenAI 2026-07-02) — `--cost-override <input/output>`
+// is the escape hatch and is authoritative when supplied. Every model here bills cached
+// input at ~0.1x (Anthropic + OpenAI gpt-5.x alike), matching CACHE_READ_MULT below.
+const MODELS = {
+    'claude-haiku-4-5': { input: 1, output: 5, provider: 'anthropic' },
+    'claude-sonnet-4-6': { input: 3, output: 15, provider: 'anthropic' },
+    'claude-opus-4-8': { input: 5, output: 25, provider: 'anthropic' },
+    'claude-fable-5': { input: 10, output: 50, provider: 'anthropic' },
+    'gpt-5.4-mini': { input: 0.75, output: 4.5, provider: 'openai' },
+    'gpt-5.4': { input: 2.5, output: 15, provider: 'openai' },
+    'gpt-5.5': { input: 5, output: 30, provider: 'openai' },
 };
-exports.ALLOWED_MODELS = Object.keys(exports.MODEL_PRICES);
+exports.MODEL_PRICES = Object.fromEntries(Object.entries(MODELS).map(([m, s]) => [m, { input: s.input, output: s.output }]));
+exports.ALLOWED_MODELS = Object.keys(MODELS);
 exports.DEFAULT_MODEL = 'claude-sonnet-4-6';
+/** Resolve which provider backend serves a model (unknown → anthropic, the default). */
+function providerFor(model) {
+    return MODELS[model]?.provider ?? 'anthropic';
+}
 /** Default total-run cost ceiling for `vk ai` when --max-cost-usd is not given, so a
  *  runaway compile/repair loop can't spend unbounded tokens. */
 exports.DEFAULT_MAX_COST_USD = 3;

package/dist/agent/engine.js

@@ -31,15 +31,15 @@ async function runPlan(plan, deps) {
     // A UI dump can fail transiently on a real device (uiautomator throws). Treat
     // that as "empty screen" rather than letting it abort the whole run — the rest
     // of the codebase treats dumps as recoverable (resolveOneWaiting re-polls).
-    const safeElements = () => {
+    const safeElements = async () => {
         try {
-            return deps.getElements();
+            return await deps.getElements();
         }
         catch {
             return [];
         }
     };
-    const present = (selector) => {
+    const present = async (selector) => {
         // Re-fetch on a dump FAILURE (uiautomator can throw transiently) so a flaky dump at
         // a guard check doesn't silently read as "absent" and skip a body that should run.
         // Once a dump SUCCEEDS (even if empty) we trust it — no slow re-poll, so a genuinely
@@ -47,7 +47,7 @@ async function runPlan(plan, deps) {
         let els;
         for (let i = 0; i < 2 && els === undefined; i++) {
             try {
-                els = deps.getElements();
+                els = await deps.getElements();
             }
             catch {
                 /* transient dump failure — retry once before concluding "absent" */
@@ -92,7 +92,7 @@ async function runPlan(plan, deps) {
                     failedStep: current,
                     reason,
                     candidates,
-                    hierarchy: safeElements(),
+                    hierarchy: await safeElements(),
                 });
                 deps.cost.add(usage, 'repair');
                 // The model may DECLINE (null) when the current screen has no element serving
@@ -149,7 +149,7 @@ async function runPlan(plan, deps) {
             case 'command':
                 return execLeaf(node, where, replace);
             case 'if-present': {
-                if (present(node.selector)) {
+                if (await present(node.selector)) {
                     deps.log(`[ai] ${where}: if-present '${node.selector}' → present, running ${node.body.length} step(s)`);
                     return walkBody(node.body, where);
                 }
@@ -163,11 +163,11 @@ async function runPlan(plan, deps) {
                         deps.log(`[ai] ${where}: run timeout reached — stopping repeat after ${i} iteration(s)`);
                         return { status: 'timeout' };
                     }
-                    if (present(node.selector)) {
+                    if (await present(node.selector)) {
                         deps.log(`[ai] ${where}: repeat reached '${node.selector}' after ${i} iteration(s)`);
                         return { status: 'ok' };
                     }
-                    const hash = structuralHash(safeElements());
+                    const hash = structuralHash(await safeElements());
                     if (i > 0 && hash === prevHash) {
                         deps.log(`[ai] ${where}: repeat made no progress (screen unchanged) — stopping after ${i} iteration(s)`);
                         return { status: 'ok' };

package/dist/agent/openai.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAiProvider = void 0;
+exports.mapUsage = mapUsage;
+exports.toStrictSchema = toStrictSchema;
+const errors_1 = require("../errors");
+const format_1 = require("../ui/format");
+const ir_1 = require("./ir");
+const grammar_1 = require("./grammar");
+// The OpenAI provider: OpenAI's Chat Completions API over Node's built-in fetch — no
+// SDK, honoring the repo's zero-runtime-dependency rule (a sibling to claude.ts). The
+// LLM ecosystem converged on this /chat/completions shape, so this same class drives any
+// OpenAI-compatible endpoint (Groq, xAI, Together, DeepSeek, Gemini-compat) by pointing
+// `baseUrl` at it — that is the whole point of doing it here rather than per vendor.
+//
+// Structured output: response_format json_schema with strict:true, so generation is
+// HARD-CONSTRAINED to the plan/repair schema. json_object mode is not enough — a weaker
+// model (e.g. gpt-5.4-mini) emits flags as a map instead of the {name,value}[] the IR
+// requires, which parsePlan then rejects. The shared ir.ts schemas are adapted to
+// OpenAI's strict dialect at call time by toStrictSchema (no duplication, no ir.ts
+// change); engine.ts's parsePlan/validateNode stays the execution trust boundary
+// regardless. The model runs here ONLY on compile + repair, never on replay.
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+// Per-request wall-clock cap so a stalled connection can't hang the run past its
+// --timeout deadline (the engine checks the deadline only between calls, not during one).
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+// gpt-5.x are reasoning models: they take reasoning_effort, require max_completion_tokens
+// (not max_tokens), and reject a custom temperature. Map verikun's effort scale onto
+// OpenAI's (whose ceiling is 'high'), and only send it when the caller asked for one.
+// INVARIANT: every OpenAI model in cost.ts's registry is a reasoning model that accepts
+// reasoning_effort. If a non-reasoning model is ever added there, gate this send behind an
+// allowlist like claude.ts's EFFORT_MODELS (else it 400s → exit 2 with no retry).
+const EFFORT_MAP = {
+    low: 'low',
+    medium: 'medium',
+    high: 'high',
+    xhigh: 'high',
+    max: 'high',
+};
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const backoffMs = (attempt) => Math.min(1000 * 2 ** (attempt - 1), 15000);
+/** Map OpenAI's usage onto the normalized (Anthropic-shaped) Usage the CostTracker
+ *  prices. OpenAI's prompt_tokens INCLUDES the cached tokens, so subtract them out:
+ *  uncached prompt → input_tokens (full price), cached → cache_read_input_tokens (0.1x).
+ *  OpenAI has no separate cache-write charge, so cache_creation is 0. completion_tokens
+ *  already includes reasoning tokens on gpt-5.x, so output is priced correctly. A response
+ *  with no usage block maps to all-zeros (cost under-counts) — acceptable because the
+ *  repair loop is also bounded by maxRepairs and the --timeout deadline, not cost alone. */
+function mapUsage(u) {
+    const cached = u?.prompt_tokens_details?.cached_tokens ?? 0;
+    const prompt = u?.prompt_tokens ?? 0;
+    return {
+        input_tokens: Math.max(0, prompt - cached),
+        output_tokens: u?.completion_tokens ?? 0,
+        cache_read_input_tokens: cached,
+        cache_creation_input_tokens: 0,
+    };
+}
+/** Adapt a JSON Schema to OpenAI's strict Structured-Outputs dialect: every object must
+ *  set additionalProperties:false and list ALL its properties in `required`, so a
+ *  previously-optional field is kept but made nullable. Non-mutating — lets the shared
+ *  ir.ts schemas stay the single source of truth while OpenAI hard-constrains generation. */
+function toStrictSchema(schema) {
+    if (Array.isArray(schema))
+        return schema.map(toStrictSchema);
+    if (!schema || typeof schema !== 'object')
+        return schema;
+    const src = schema;
+    const out = {};
+    for (const [k, v] of Object.entries(src))
+        out[k] = toStrictSchema(v);
+    const props = out.properties;
+    if (props && typeof props === 'object' && !Array.isArray(props)) {
+        const p = props;
+        const keys = Object.keys(p);
+        const wasRequired = new Set(Array.isArray(out.required) ? out.required : []);
+        out.additionalProperties = false;
+        out.required = keys;
+        for (const k of keys)
+            if (!wasRequired.has(k))
+                p[k] = makeNullable(p[k]);
+    }
+    return out;
+}
+/** Widen a property schema to also admit null (how strict mode expresses "optional"). */
+function makeNullable(prop) {
+    if (!prop || typeof prop !== 'object')
+        return prop;
+    const p = prop;
+    if (Array.isArray(p.anyOf))
+        return { ...p, anyOf: [...p.anyOf, { type: 'null' }] };
+    if (typeof p.type === 'string') {
+        const next = { ...p, type: [p.type, 'null'] };
+        if (Array.isArray(p.enum))
+            next.enum = [...p.enum, null];
+        return next;
+    }
+    if (Array.isArray(p.type)) {
+        return { ...p, type: [...p.type.filter((t) => t !== 'null'), 'null'] };
+    }
+    return { anyOf: [prop, { type: 'null' }] };
+}
+class OpenAiProvider {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async compile(input) {
+        const parts = [];
+        if (input.pkg)
+            parts.push(`App package: ${input.pkg}`);
+        parts.push(`Platform: ${input.platform}`);
+        if (input.seed) {
+            parts.push('A plan compiled for a PREVIOUS build of this app follows. Reuse it where the test still holds; ' +
+                'change only what the test now requires. PRIOR PLAN:\n' +
+                JSON.stringify(input.seed, null, 2));
+        }
+        parts.push('NATURAL-LANGUAGE TEST:\n' + input.nl);
+        // Generous completion budget: on reasoning models the plan JSON shares this ceiling
+        // with reasoning tokens, so leave headroom (a 'length' finish is surfaced as an error).
+        const { json, usage } = await this.call(grammar_1.GRAMMAR, parts.join('\n\n'), ir_1.PLAN_JSON_SCHEMA, 16384);
+        return { plan: (0, ir_1.parsePlan)(json), usage };
+    }
+    async repair(ctx) {
+        const parts = ['FAILED STEP: ' + JSON.stringify(ctx.failedStep), 'FAILURE: ' + ctx.reason];
+        if (ctx.candidates && ctx.candidates.length) {
+            parts.push(`The selector matched ${ctx.candidates.length} elements (ambiguous) — pick a more specific selector for the SAME intended element, or give_up if none of them is it.`);
+        }
+        parts.push('CURRENT SCREEN:\n' + (0, format_1.formatCompact)(ctx.hierarchy));
+        const { json, usage } = await this.call(grammar_1.REPAIR_GRAMMAR, parts.join('\n\n'), ir_1.REPAIR_DECISION_JSON_SCHEMA, 4096);
+        const decision = (json ?? {});
+        if (decision.decision === 'give_up') {
+            return {
+                replaceStep: null,
+                declineReason: decision.reason?.trim() || 'no element on the current screen matches the step intent',
+                usage,
+            };
+        }
+        // Hand the proposed leaf back UNVALIDATED — engine.ts validates every repair against
+        // the grammar before splicing (it is the execution trust boundary and can't assume a
+        // provider validated). A missing/invalid step is rejected there as a failed repair.
+        return { replaceStep: (decision.step ?? null), usage };
+    }
+    async call(system, user, schema, maxTokens) {
+        const body = {
+            model: this.opts.model,
+            max_completion_tokens: maxTokens,
+            // Hard-constrain generation to the schema (strict Structured Outputs), adapting the
+            // shared ir.ts schema to OpenAI's strict dialect. parsePlan/validateNode still gates.
+            response_format: {
+                type: 'json_schema',
+                json_schema: { name: 'verikun_output', strict: true, schema: toStrictSchema(schema) },
+            },
+            messages: [
+                { role: 'system', content: system },
+                { role: 'user', content: user },
+            ],
+        };
+        if (this.opts.effort) {
+            const mapped = EFFORT_MAP[this.opts.effort];
+            if (mapped)
+                body.reasoning_effort = mapped;
+        }
+        const res = await this.fetchWithRetry(body);
+        const choice = res.choices?.[0];
+        if (choice?.message?.refusal) {
+            throw new errors_1.CliError(`Model refused the request: ${choice.message.refusal}`, 1);
+        }
+        if (choice?.finish_reason === 'length') {
+            throw new errors_1.CliError('Model output was truncated (finish_reason=length) before a complete result — raise the budget or shorten the test.', 1);
+        }
+        if (choice?.finish_reason === 'content_filter') {
+            throw new errors_1.CliError('Model output was blocked by the content filter.', 1);
+        }
+        const text = (choice?.message?.content ?? '').trim();
+        if (!text)
+            throw new errors_1.CliError('Model returned an empty response.', 1);
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new errors_1.CliError('Model output was not valid JSON.', 1);
+        }
+        return { json, usage: mapUsage(res.usage) };
+    }
+    async fetchWithRetry(body) {
+        const maxRetries = this.opts.maxRetries ?? 4;
+        const timeoutMs = this.opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        const doFetch = this.opts.fetchImpl ?? ((url, init) => fetch(url, init));
+        const doSleep = this.opts.sleepImpl ?? sleep;
+        const url = (this.opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '') + '/chat/completions';
+        let attempt = 0;
+        for (;;) {
+            // Abort a stalled request after timeoutMs so it can't hang forever; the abort is
+            // caught below and retried like any other network error (bounded by maxRetries).
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let res;
+            try {
+                res = await doFetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${this.opts.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            catch (e) {
+                if (attempt++ >= maxRetries)
+                    throw new errors_1.CliError(`OpenAI API request failed: ${e.message}`, 3);
+                await doSleep(backoffMs(attempt));
+                continue;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (res.ok) {
+                try {
+                    return (await res.json());
+                }
+                catch {
+                    // A 2xx with a non-JSON body (proxy/API corruption) — map to the env exit code
+                    // rather than letting a raw SyntaxError escape as an unhandled throw.
+                    throw new errors_1.CliError('OpenAI returned a non-JSON success body.', 3);
+                }
+            }
+            // Retry 429 + 5xx with backoff, honoring Retry-After (no SDK to do it for us).
+            if ((res.status === 429 || res.status >= 500) && attempt++ < maxRetries) {
+                const retryAfter = Number(res.headers.get('retry-after'));
+                await doSleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : backoffMs(attempt));
+                continue;
+            }
+            const errText = await res.text().catch(() => '');
+            // 401/403 = auth/permission (env); 400 = bad request (usage); else env.
+            const code = res.status === 401 || res.status === 403 ? 3 : res.status === 400 ? 2 : 3;
+            throw new errors_1.CliError(`OpenAI API error ${res.status}: ${errText.slice(0, 500)}`, code);
+        }
+    }
+}
+exports.OpenAiProvider = OpenAiProvider;