verikun 0.7.0 → 0.9.0

package/README.md

@@ -1,15 +1,12 @@
 # verikun
 
-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.
+> **Agent-driven, natural-language mobile tests — during agent development or in CI.** Self-healing and self-improving, with cost caps and test reports.
 
-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.
+- **Agent CLI** — `vk <command>`: one-shot commands to inspect the screen as a semantic tree (or screenshot) and act on it.
+- **Puppeteer for native mobile** — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
+- **Natural-language tests** — `vk ai <file>`: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step.
+- **Self-improving** — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
+- **CI-ready** — `vk suite` runs a folder of tests as one gated pass/fail run; `vk server` exposes a real device over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive it.
 
 ```
 $ vk ui
@@ -23,6 +20,12 @@ $ vk tap @sign_in_btn
 tapped [3] Button "Sign in" @sign_in_btn (540,1020) tap
 ```
 
+## Skill/plugin instead of MCP
+
+verikun ships as a skill and plugin, not an MCP server, and that is deliberate. A skill lets us **guide the agent on how to use verikun** — when to inspect the hierarchy, what to assert, which command fits the step, and how to read the result back. That domain knowledge travels with the tool, so the agent drives the device *well*, not just correctly.
+
+There is also no need for an MCP here: verikun runs locally with all its dependencies, and the agent calls it through the plain `vk` CLI — no shared session, data, or authentication to broker.
+
 ## Install
 
 Requires Node ≥ 18 and the Android platform-tools (`adb`) on your `PATH`.
@@ -44,6 +47,16 @@ This repo doubles as a Claude Code [plugin marketplace](https://code.claude.com/
 
 The plugin ships the **skill**; the `vk` **CLI** is a separate Node package — install it with `npm install -g verikun` (see [Install](#install) above) so `vk` lands on your `PATH`. The compiled `dist/` is gitignored, so it isn't bundled into the installed plugin.
 
+### Install the skill for other agents (Cursor, Copilot, Windsurf, …)
+
+Not using Claude Code? The skill is a plain [`SKILL.md`](.claude/skills/verikun/SKILL.md) with `name`/`description` frontmatter, so [`vercel-labs/skills`](https://github.com/vercel-labs/skills) can install it into any of the 70+ agents it supports. Install the `vk` CLI (see [Install](#install) above), then pull the skill straight from this repo:
+
+```sh
+npx skills add ddikman/verikun --skill verikun    # pick your agent when prompted
+```
+
+Add `--agent cursor` (or `windsurf`, `github-copilot`, `opencode`, …) to target one directly, and `-g` to install it globally instead of into the current project. As with the plugin, this installs the **skill** only — the `vk` **CLI** still comes from `npm install -g verikun`.
+
 ## Quick start
 
 ```sh
@@ -90,7 +103,7 @@ 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] [--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). |
+| `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), or no key with `--model codex-cli` (a logged-in `codex` CLI). 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
@@ -197,7 +210,9 @@ 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` (Claude models) or `OPENAI_API_KEY` (OpenAI models).
+Needs `ANTHROPIC_API_KEY` (Claude models) or `OPENAI_API_KEY` (OpenAI models) — or **no
+key** with `--model codex-cli`, which drives an already-logged-in `codex` CLI off your
+ChatGPT subscription (`codex login` once; verikun just needs the binary on PATH).
 
 ```sh
 # onboarding.md (plain English):
@@ -226,12 +241,19 @@ a hard iteration cap and stop early if the screen stops changing.
   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 and its provider — Anthropic (`claude-haiku-4-5` ·
-  `claude-sonnet-4-6` (default) · `claude-opus-4-8` · `claude-fable-5`) or OpenAI
+  `claude-sonnet-4-6` (default) · `claude-opus-4-8` · `claude-fable-5`), 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.
+  (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`), or the CLI backend **`codex-cli`** (no key —
+  the logged-in `codex` binary; spend is on your subscription, so its cost line is `$0` and
+  `--max-cost-usd` / `--cost-override` are no-ops); **`--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).
+- **Review screenshots are inserted automatically.** The compiler adds `screenshot` steps
+  around transitions and inside loops, so the report carries a before/after visual trail
+  for post-run review. They are dumped for humans, never read back by the model (no token
+  cost on replay), and never gate the test — a capture that hiccups is logged and skipped,
+  not a failure.
 
 ## Suites — run a directory of tests
 
@@ -260,8 +282,8 @@ vk suite tests/ --app com.example.app --server "$VERIKUN_SERVER"   # remote devi
   - **`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.
+  every test; the provider (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` CLI for
+  `--model codex-cli`) is checked up front.
 
 ## Remote devices — `vk server`
 
@@ -424,6 +446,13 @@ safely resample (palette, 16-bit, interlaced) are written through untouched, so
 screenshot is never corrupted — only sometimes left full-size (noted on stderr).
 Failure-evidence captures in test-run reports stay full-resolution for debugging.
 
+**Read-back vs evidence.** The downscaling above matters when an agent *reads a
+screenshot back into its context* to decide the next action — that is the token cost to
+manage. A screenshot taken purely as **report evidence and never read back** costs nothing
+at runtime, so driving a flow to a report should capture liberally around transitions.
+`vk ai` does this automatically (see [AI](#ai--natural-language-tests)); when driving by
+hand, `vk screenshot` around each screen change and leave the PNG in the report.
+
 ## How it works
 
 ```

package/dist/agent/cli-provider.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliProvider = exports.CODEX_SPEC = void 0;
+exports.schemaInstruction = schemaInstruction;
+exports.extractJson = extractJson;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const errors_1 = require("../errors");
+const format_1 = require("../ui/format");
+const ir_1 = require("./ir");
+const grammar_1 = require("./grammar");
+const openai_1 = require("./openai");
+const exec_1 = require("../exec");
+// The CLI-agent provider: instead of an HTTP API + API key, drive an already-authenticated
+// coding-agent CLI (codex / cursor-agent) as a one-shot text->JSON transformer. This lets a
+// user compile/repair `vk ai` tests off their existing ChatGPT/Cursor SUBSCRIPTION — the CLI
+// carries its own login, so verikun needs no key (just the binary on PATH). A sibling to
+// claude.ts/openai.ts behind the same AgentProvider seam; like openai.ts is one class
+// parameterized by baseUrl, this is one class parameterized by a CliAgentSpec per binary.
+//
+// Structured output: these CLIs are not HTTP endpoints, so there is no output_config /
+// response_format. codex enforces a schema natively (--output-schema); a CLI without one
+// gets the schema injected into the prompt. Either way parsePlan/validateNode (engine.ts)
+// stays the execution trust boundary — ir.ts documents this exact "parse path when
+// structured output is unavailable", so a malformed/hallucinated result is still rejected.
+//
+// These CLIs are AGENTS (tools, a working dir, a coding-oriented system prompt), so a
+// forceful preamble + a read-only sandbox (per spec) coerce them into a pure transform that
+// never touches the repo. The model runs here ONLY on compile + repair, never on replay.
+// An agentic CLI compile is far slower than an HTTP call, and runText's 30s default would
+// kill it mid-think. This is the per-invocation wall-clock cap (a hung spawn is killed and
+// mapped to exit 3 by exec.ts); the engine's --timeout still bounds the whole run BETWEEN calls.
+const DEFAULT_REQUEST_TIMEOUT_MS = 180_000;
+const PREAMBLE = 'You are being used as a pure text-to-JSON transformer, NOT a coding assistant. ' +
+    'Do NOT read, write, or edit any files. Do NOT run shell commands or use any tools. ' +
+    'Do NOT explain, summarize, or add any commentary. Respond with ONLY a single JSON ' +
+    'object as your final message, exactly matching the specification below.';
+/** codex (OpenAI Codex CLI): non-interactive `codex exec` with NATIVE JSON-schema output
+ *  (--output-schema) — the cleanest CLI path. Runs read-only in a neutral dir so it can't touch
+ *  the verikun tree; the final (schema-shaped) message is written to --output-last-message, which
+ *  we read back (deterministic, unlike parsing stdout, whose decoration is version-dependent). */
+exports.CODEX_SPEC = {
+    id: 'codex',
+    bin: 'codex',
+    schema: 'file',
+    // codex's --output-schema is OpenAI strict Structured Outputs — adapt the shared ir.ts schema
+    // the same way openai.ts does (all keys required, optionals made nullable, additionalProperties
+    // false). parsePlan tolerates the resulting nulls (package/platform → undefined).
+    encodeSchema: openai_1.toStrictSchema,
+    usesOutputFile: true,
+    buildArgs(prompt, { schemaFile, outFile, cwd, model }) {
+        const args = [
+            'exec',
+            '--skip-git-repo-check', // don't require (or scan) a git repo
+            '--cd', cwd, // root the agent in a neutral temp dir, not the verikun working tree
+            '--sandbox', 'read-only', // hard backstop: the agent cannot write anything
+            '--ephemeral', // don't persist session files for a stateless transform
+        ];
+        if (schemaFile)
+            args.push('--output-schema', schemaFile); // constrain the final message to the schema
+        if (outFile)
+            args.push('--output-last-message', outFile); // final message -> file we read back
+        if (model)
+            args.push('--model', model);
+        args.push(prompt); // prompt is the trailing positional
+        return args;
+    },
+    rawText: (stdout) => stdout, // fallback only; the message is read from --output-last-message
+    loginHint: 'run `codex login` to sign in with your ChatGPT subscription (no API key needed)',
+};
+// Collision-free temp-file names within a process without needing Math.random() (which the
+// plan-cache/version paths keep deterministic); pid + a counter is enough.
+let tempCounter = 0;
+class CliProvider {
+    opts;
+    run;
+    baseTmp;
+    timeoutMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.run = opts.runImpl ?? exec_1.runText;
+        this.baseTmp = opts.tmpDir ?? (0, node_os_1.tmpdir)();
+        this.timeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    }
+    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);
+        const json = this.call(grammar_1.GRAMMAR, parts.join('\n\n'), ir_1.PLAN_JSON_SCHEMA);
+        // usage:{} — a CLI is billed to the user's subscription, not per token, so cost is $0
+        // (documented no-op for --max-cost-usd). The run is still bounded by maxRepairs + --timeout.
+        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 = this.call(grammar_1.REPAIR_GRAMMAR, parts.join('\n\n'), ir_1.REPAIR_DECISION_JSON_SCHEMA);
+        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), exactly like the API providers.
+        return { replaceStep: (decision.step ?? null), usage: {} };
+    }
+    /** Spawn the CLI once and return the parsed JSON object it produced. Synchronous (spawnSync);
+     *  the async method wrappers satisfy the Promise-returning AgentProvider seam. */
+    call(system, user, schema) {
+        const spec = this.opts.spec;
+        const promptParts = [PREAMBLE, system];
+        if (spec.schema === 'prompt')
+            promptParts.push(schemaInstruction(schema));
+        promptParts.push(user);
+        const prompt = promptParts.join('\n\n');
+        let schemaFile;
+        let outFile;
+        try {
+            if (spec.schema === 'file') {
+                const encoded = spec.encodeSchema ? spec.encodeSchema(schema) : schema;
+                schemaFile = this.writeTemp('schema', '.json', JSON.stringify(encoded));
+            }
+            if (spec.usesOutputFile)
+                outFile = this.tempPath('out', '.txt'); // path only; the CLI writes it
+            const args = spec.buildArgs(prompt, { schemaFile, outFile, cwd: this.baseTmp, model: this.opts.model });
+            // runText throws CliError(exit 3) for ENOENT / timeout / spawn failure — let it propagate.
+            const res = this.run(spec.bin, args, { timeout: this.timeoutMs, cwd: this.baseTmp });
+            if (res.code !== 0) {
+                // Lead with the CLI's own stderr — it carries the real reason (usage limit, auth, a bad
+                // flag). Only fall back to the login hint when stderr said nothing, so we don't
+                // mis-suggest a re-login for e.g. a quota error.
+                const detail = tail(res.stderr);
+                const suffix = detail ? `: ${detail}` : ` — ${spec.loginHint}`;
+                throw new errors_1.CliError(`\`${spec.bin}\` exited ${res.code}${suffix}`, 3);
+            }
+            // Prefer the message file (deterministic); fall back to stdout if the CLI wrote nothing there.
+            const fromFile = outFile ? readIfExists(outFile).trim() : '';
+            const text = fromFile || spec.rawText(res.stdout).trim();
+            if (!text)
+                throw new errors_1.CliError(`\`${spec.bin}\` returned an empty response.`, 1);
+            return extractJson(text);
+        }
+        finally {
+            for (const f of [schemaFile, outFile]) {
+                if (!f)
+                    continue;
+                try {
+                    (0, node_fs_1.unlinkSync)(f);
+                }
+                catch {
+                    /* best-effort cleanup — a leftover temp file is harmless */
+                }
+            }
+        }
+    }
+    tempPath(kind, ext) {
+        return (0, node_path_1.join)(this.baseTmp, `verikun-${this.opts.spec.id}-${kind}-${process.pid}-${tempCounter++}${ext}`);
+    }
+    writeTemp(kind, ext, content) {
+        const file = this.tempPath(kind, ext);
+        (0, node_fs_1.writeFileSync)(file, content, 'utf8');
+        return file;
+    }
+}
+exports.CliProvider = CliProvider;
+/** Read a file, returning '' if it does not exist / can't be read — lets the message-file path
+ *  fall back to stdout when a CLI didn't populate --output-last-message. */
+function readIfExists(path) {
+    try {
+        return (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** For a CLI with no native schema flag (schema:'prompt'): describe the required output shape
+ *  inline. parsePlan/validateNode still re-checks whatever comes back. */
+function schemaInstruction(schema) {
+    return ('Your entire response MUST be a single JSON object matching this JSON Schema exactly, ' +
+        'with no prose and no code fences:\n' + JSON.stringify(schema));
+}
+/** Tolerantly pull a JSON object out of a CLI's stdout. codex's --output-schema output is
+ *  already clean JSON; a schema-in-prompt CLI may wrap it in ```fences``` or a sentence. The
+ *  brace scanner is string/escape aware, so it finds the object even inside a fence or after a
+ *  "Here is the plan:" preamble. Throws CliError(exit 1) on failure — parsePlan is still the gate. */
+function extractJson(text) {
+    const candidate = firstBalancedObject(text) ?? text.trim();
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        throw new errors_1.CliError('the CLI provider did not return parseable JSON.', 1);
+    }
+}
+/** The first balanced `{...}` in `text`, honoring string literals + backslash escapes so a
+ *  brace inside a JSON string value doesn't throw off the depth count. null if there is none. */
+function firstBalancedObject(text) {
+    const start = text.indexOf('{');
+    if (start < 0)
+        return null;
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (c === '\\')
+                esc = true;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === '{')
+            depth++;
+        else if (c === '}' && --depth === 0)
+            return text.slice(start, i + 1);
+    }
+    return null;
+}
+/** A trimmed, size-capped tail of a CLI's stderr for error messages ('' when it wrote nothing). */
+function tail(stderr, n = 500) {
+    const t = stderr.trim();
+    return t.length > n ? '…' + t.slice(-n) : t;
+}

package/dist/agent/cost.js

@@ -21,6 +21,11 @@ const MODELS = {
     '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' },
+    // CLI-agent backend: billed to the user's ChatGPT subscription via the `codex` CLI, not per
+    // token — so price is $0 and --max-cost-usd/--cost-override are inert no-ops (the run is
+    // bounded by maxRepairs + --timeout instead). Named `codex-cli` to read clearly as "the CLI"
+    // and to avoid colliding with cursor's own `gpt-5.x-codex` model aliases.
+    'codex-cli': { input: 0, output: 0, provider: 'codex' },
 };
 exports.MODEL_PRICES = Object.fromEntries(Object.entries(MODELS).map(([m, s]) => [m, { input: s.input, output: s.output }]));
 exports.ALLOWED_MODELS = Object.keys(MODELS);

package/dist/agent/engine.js

@@ -8,6 +8,11 @@ const ir_1 = require("./ir");
 const describe = (leaf) => [leaf.command, ...leaf.positionals, ...leaf.flags.map((f) => (f.value === 'true' ? `--${f.name}` : `--${f.name} ${f.value}`))]
     .join(' ')
     .trim();
+/** A screenshot leaf is best-effort review evidence, not a gate. The `vk ai`
+ *  grammar has the model sprinkle them around transitions, so a capture that
+ *  fails (a device hiccup on screencap) must never turn a green run red — see
+ *  the guard in execLeaf. */
+const isScreenshotLeaf = (leaf) => leaf.command === 'screenshot' || leaf.command === 'shot';
 /** A structural fingerprint of the screen: sorted id+text+type set. Used for the
  *  loop no-progress check — deliberately NOT the raw hierarchy (its node ordering
  *  is nondeterministic between identical states, which would false-trip). */
@@ -129,6 +134,19 @@ async function runPlan(plan, deps) {
         }
         if (outcome.code === 0)
             return { status: 'ok' };
+        // A review screenshot is best-effort evidence, never a gate. The grammar has the
+        // model insert them liberally around transitions, so a capture that fails (a
+        // device hiccup on screencap) must not fail an otherwise-green run. Log it,
+        // downgrade the just-recorded failed step to a clean pass (markLastStepHealed
+        // sets status=passed/exitCode=0 and drops the failure evidence) so the report and
+        // JUnit stay consistent with the green run, then continue. Scoped to screenshot/
+        // shot — every other command's failure stays terminal.
+        if (isScreenshotLeaf(current)) {
+            const why = outcome.error ? outcome.error.message.split('\n')[0] : `exited ${outcome.code}`;
+            deps.log(`[ai] ${where}: screenshot capture failed (${why}) — continuing (best-effort review screenshot)`);
+            deps.markHealed?.(`screenshot capture failed (${why}) — skipped (best-effort)`);
+            return { status: 'ok' };
+        }
         if (isHealable(outcome)) {
             return { status: 'fail', where, reason: `unresolved after ${maxRepairs} repair attempt(s): ${outcome.error.message.split('\n')[0]}` };
         }

package/dist/agent/grammar.js

@@ -54,7 +54,12 @@ RULES:
 - assert is for VERIFICATION only and is terminal — never use it as a step you expect to
   fail. Put genuinely-optional UI behind if-present.
 - Prefer resource-id / accessibility selectors over visible text where possible.
-- Translate the test literally and minimally; do not invent steps the prose does not imply.`;
+- Translate the test literally and minimally: do not invent ACTION steps (tap/text/swipe/key/assert)
+  the prose does not imply. The ONE exception is screenshot — insert screenshot steps liberally as
+  post-run review evidence: after each screen transition (launch, a navigation tap, a submit, a
+  swipe/scroll) AND inside if-present/repeat bodies, so a failing branch or loop iteration is visible
+  in the report. Screenshots never affect the result; err toward too many. They are dumped into the
+  report for humans and never read back, so they are free on replay.`;
 exports.REPAIR_GRAMMAR = `A single step in a verikun plan failed to resolve its selector against the live screen
 (shown below). Decide between two outcomes — and be STRICT:
 

package/dist/cli.js

@@ -40,6 +40,7 @@ exports.healNote = healNote;
 exports.parseDuration = parseDuration;
 exports.waitWindowMs = waitWindowMs;
 exports.waitNote = waitNote;
+exports.formatDeviceTable = formatDeviceTable;
 exports.confineToCwd = confineToCwd;
 exports.assertSafeAppId = assertSafeAppId;
 exports.chooseLogOpts = chooseLogOpts;
@@ -62,6 +63,7 @@ const image_1 = require("./image");
 const engine_1 = require("./agent/engine");
 const claude_1 = require("./agent/claude");
 const openai_1 = require("./agent/openai");
+const cli_provider_1 = require("./agent/cli-provider");
 const cache_1 = require("./agent/cache");
 const cost_1 = require("./agent/cost");
 const remote_1 = require("./agent/remote");
@@ -202,13 +204,34 @@ function cmdDevices(ctx) {
         (0, output_1.err)('No devices found.');
         return 0;
     }
-    for (const d of allDevices) {
-        (0, output_1.out)([d.platform, d.serial, d.state, d.model ?? '', d.product ? `(${d.product})` : '', d.note ? `[${d.note}]` : '']
-            .filter(Boolean)
-            .join('\t'));
-    }
+    for (const line of formatDeviceTable(allDevices))
+        (0, output_1.out)(line);
     return 0;
 }
+/**
+ * Render the device list as an aligned, headed table (header line first, then one
+ * line per device). Optional columns (MODEL/PRODUCT/NOTE) are dropped when no device
+ * populates them; every shown cell is padded to its column width so columns line up
+ * regardless of which cells are empty — the previous `.filter(Boolean).join('\t')`
+ * dropped empty cells, sliding later cells into earlier tab stops. Exported for unit
+ * testing.
+ */
+function formatDeviceTable(devices) {
+    const columns = [
+        { header: 'PLATFORM', get: (d) => d.platform },
+        { header: 'SERIAL', get: (d) => d.serial },
+        { header: 'STATE', get: (d) => d.state },
+        { header: 'MODEL', get: (d) => d.model ?? '', optional: true },
+        { header: 'PRODUCT', get: (d) => d.product ?? '', optional: true },
+        { header: 'NOTE', get: (d) => d.note ?? '', optional: true },
+    ];
+    // Drop optional columns that no device populates (e.g. NOTE for an Android-only list).
+    const shown = columns.filter((c) => !c.optional || devices.some((d) => c.get(d) !== ''));
+    const rows = [shown.map((c) => c.header), ...devices.map((d) => shown.map((c) => c.get(d)))];
+    const widths = shown.map((_, i) => Math.max(...rows.map((r) => r[i].length)));
+    // Pad every cell except the last shown column (no trailing whitespace); join with 2 spaces.
+    return rows.map((r) => r.map((cell, i) => (i === r.length - 1 ? cell : cell.padEnd(widths[i]))).join('  ').trimEnd());
+}
 function cmdDoctor(ctx) {
     if (ctx.platform === 'ios') {
         try {
@@ -961,20 +984,45 @@ function readAiTest(file) {
         throw new errors_1.CliError(`ai: '${file}' is empty`, 2);
     return nl;
 }
-/** The env var carrying the API key for a model's provider (per-provider keys). */
-function keyEnvFor(model) {
-    return (0, cost_1.providerFor)(model) === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+/** Is the backend for `model` usable right now? HTTP providers need their API key in env;
+ *  a CLI provider needs its binary on PATH (auth lives in the CLI's own login, not an env key). */
+function providerAvailable(model) {
+    switch ((0, cost_1.providerFor)(model)) {
+        case 'openai':
+            return !!process.env.OPENAI_API_KEY;
+        case 'codex':
+            return (0, exec_1.commandExists)(cli_provider_1.CODEX_SPEC.bin);
+        default:
+            return !!process.env.ANTHROPIC_API_KEY;
+    }
+}
+/** What's missing when a provider is unavailable — the tail of the preflight error message. */
+function providerRequirement(model) {
+    switch ((0, cost_1.providerFor)(model)) {
+        case 'openai':
+            return 'OPENAI_API_KEY is not set';
+        case 'codex':
+            return `the \`${cli_provider_1.CODEX_SPEC.bin}\` CLI was not found on PATH — install it and run \`codex login\` (ChatGPT subscription, no API key)`;
+        default:
+            return 'ANTHROPIC_API_KEY is not set';
+    }
 }
-/** Route the model to its backend; each provider reads its own key. A missing key
- *  means no provider (compile/repair unavailable) — the same graceful degradation
- *  as before. */
+/** Route the model to its backend. HTTP providers read their own key; a CLI provider shells
+ *  out to its logged-in binary. Unavailable → null (compile/repair off), the same graceful
+ *  degradation as before: a cached plan can still replay for free without any provider. */
 function makeProvider(opts) {
-    const apiKey = process.env[keyEnvFor(opts.model)];
-    if (!apiKey)
-        return null;
-    return (0, cost_1.providerFor)(opts.model) === 'openai'
-        ? new openai_1.OpenAiProvider({ model: opts.model, apiKey, effort: opts.effort })
-        : new claude_1.ClaudeProvider({ model: opts.model, apiKey, effort: opts.effort });
+    switch ((0, cost_1.providerFor)(opts.model)) {
+        case 'openai': {
+            const apiKey = process.env.OPENAI_API_KEY;
+            return apiKey ? new openai_1.OpenAiProvider({ model: opts.model, apiKey, effort: opts.effort }) : null;
+        }
+        case 'codex':
+            return (0, exec_1.commandExists)(cli_provider_1.CODEX_SPEC.bin) ? new cli_provider_1.CliProvider({ spec: cli_provider_1.CODEX_SPEC }) : null;
+        default: {
+            const apiKey = process.env.ANTHROPIC_API_KEY;
+            return apiKey ? new claude_1.ClaudeProvider({ model: opts.model, apiKey, effort: opts.effort }) : null;
+        }
+    }
 }
 /** Obtain the plan: a cache hit (free) or a compile (pays tokens; may seed from a
  *  prior build's plan to avoid a full recompile). The fresh compile is cached right
@@ -987,7 +1035,7 @@ async function obtainPlan(key, file, opts, cost, provider) {
         return { plan: cached.plan, cached: true };
     }
     if (!provider) {
-        throw new errors_1.CliError(`${keyEnvFor(opts.model)} is not set — \`vk ai\` needs it to compile the test (model ${opts.model}). Set it and retry.`, 3);
+        throw new errors_1.CliError(`${providerRequirement(opts.model)} — needed to compile the test (model ${opts.model}).`, 3);
     }
     const seed = (0, cache_1.findSeed)(key);
     if (seed)
@@ -1058,7 +1106,7 @@ async function runAiTest(file, opts, backend, platform, device) {
     const { plan, cached } = await obtainPlan(key, file, opts, cost, provider);
     // Running needs the provider for repair-on-failure; a cache hit with no key can't repair.
     if (!provider) {
-        throw new errors_1.CliError(`${keyEnvFor(opts.model)} is not set — \`vk ai\` needs it to repair a failing step at runtime (model ${opts.model}).`, 3);
+        throw new errors_1.CliError(`${providerRequirement(opts.model)} — needed to repair a failing step at runtime (model ${opts.model}).`, 3);
     }
     // The budget is a TOTAL-run ceiling: if the compile alone already crossed it, abort
     // before running. A cache hit spends nothing, so a free replay is still allowed.
@@ -1244,10 +1292,10 @@ async function cmdSuiteEntry(positionals, flags) {
     if (!dirArg)
         throw new errors_1.CliError('Usage: verikun suite <dir> [--app <id>] [--server url] [--name n] [--json]', 2);
     const opts = parseAiOptions(flags);
-    // Pre-flight the model key BEFORE touching any device/server: every test needs it
+    // Pre-flight the provider BEFORE touching any device/server: every test needs it
     // to compile (on a cache miss) or to repair at runtime.
-    if (!process.env[keyEnvFor(opts.model)]) {
-        throw new errors_1.CliError(`${keyEnvFor(opts.model)} is not set — \`vk suite\` needs it to compile/repair tests (model ${opts.model}).`, 3);
+    if (!providerAvailable(opts.model)) {
+        throw new errors_1.CliError(`${providerRequirement(opts.model)} — needed to compile/repair tests (model ${opts.model}).`, 3);
     }
     const reqPlatform = platformFromFlags(flags);
     const { backend, platform, device } = await resolveBackend(reqPlatform, deviceFromFlags(flags, reqPlatform), flags);
@@ -1538,13 +1586,16 @@ AI (run a natural-language test — compile once, replay model-free, self-heal)
                                       path. The model is woken only to repair a step
                                       that fails to resolve; a green run persists the
                                       (repaired) plan so the next run is free. Needs
-                                      ANTHROPIC_API_KEY (Claude) or OPENAI_API_KEY
-                                      (gpt-5.x). Progress -> stderr; the report path ->
+                                      ANTHROPIC_API_KEY (Claude), OPENAI_API_KEY (gpt-5.x),
+                                      or a logged-in agent CLI (--model codex-cli uses your
+                                      'codex login' ChatGPT subscription — no API key; cost
+                                      is $0 so --max-cost-usd/--cost-override are no-ops).
+                                      Progress -> stderr; the report path ->
                                       stdout. --show-plan prints the compiled IR without
                                       running; --recompile ignores the cache.
                                       Models: claude-haiku-4-5 | claude-sonnet-4-6
                                       (default) | claude-opus-4-8 | claude-fable-5 |
-                                      gpt-5.4-mini | gpt-5.4 | gpt-5.5.
+                                      gpt-5.4-mini | gpt-5.4 | gpt-5.5 | codex-cli.
 
 SUITE (run a directory of natural-language tests as one gated suite)
   suite <dir> [--app <id>] [--name n] [--json]  (+ all \`ai\` flags, incl. --server)

package/dist/exec.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runText = runText;
+exports.commandExists = commandExists;
 exports.runBinary = runBinary;
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const errors_1 = require("./errors");
 const MAX_BUFFER = 64 * 1024 * 1024; // screenshots can be a few MB
 function describeError(cmd, args, err) {
@@ -14,18 +17,49 @@ function describeError(cmd, args, err) {
     }
     return new errors_1.CliError(`Failed to run '${cmd}': ${err.message}`, 3);
 }
-/** Run a command and capture stdout/stderr as UTF-8 text. */
+/** Run a command and capture stdout/stderr as UTF-8 text. `cwd` runs it rooted elsewhere
+ *  (the CLI-agent providers run in a neutral temp dir so they never touch the working tree). */
 function runText(cmd, args, opts = {}) {
     const r = (0, node_child_process_1.spawnSync)(cmd, args, {
         encoding: 'utf8',
         timeout: opts.timeout ?? 30000,
         input: opts.input,
+        cwd: opts.cwd,
         maxBuffer: MAX_BUFFER,
     });
     if (r.error)
         throw describeError(cmd, args, r.error);
     return { code: r.status ?? 0, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
 }
+/** Is `bin` an executable on PATH (or a direct path to one)? Used to decide a CLI provider is
+ *  available without invoking the agent — a cheap, pure PATH scan (no spawn, no runtime dep). */
+function commandExists(bin) {
+    if (bin.includes('/') || bin.includes('\\'))
+        return isExecutableFile(bin);
+    const isWin = process.platform === 'win32';
+    const exts = isWin ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';') : [''];
+    for (const dir of (process.env.PATH ?? '').split(node_path_1.delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts)
+            if (isExecutableFile((0, node_path_1.join)(dir, bin + ext)))
+                return true;
+    }
+    return false;
+}
+function isExecutableFile(p) {
+    try {
+        if (!(0, node_fs_1.statSync)(p).isFile())
+            return false;
+        if (process.platform === 'win32')
+            return true; // Windows has no X bit; a matching file is enough
+        (0, node_fs_1.accessSync)(p, node_fs_1.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Run a command and capture stdout as raw bytes (e.g. PNG screenshots). */
 function runBinary(cmd, args, opts = {}) {
     const r = (0, node_child_process_1.spawnSync)(cmd, args, {

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.7.0';
+exports.VERSION = '0.9.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",