verikun 0.8.0 → 0.10.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` / `cursor-cli` (a logged-in `codex` / `cursor-agent` 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,10 @@ 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` / `--model cursor-cli`, which drive an already-logged-in
+`codex` or `cursor-agent` CLI off your ChatGPT / Cursor subscription (log in once;
+verikun just needs the binary on PATH).
 
 ```sh
 # onboarding.md (plain English):
@@ -226,9 +242,14 @@ 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 a CLI backend — **`codex-cli`** (the
+  logged-in `codex` binary) or **`cursor-cli`** (`cursor-agent`) — which need no key at
+  all: spend is on your subscription, so their cost line is `$0` and `--max-cost-usd` /
+  `--cost-override` are no-ops. Each CLI picks its own underlying model, and runs
+  read-only in a scratch directory so it never touches your working tree.
+  **`--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).
@@ -265,8 +286,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` /
+  `cursor-agent` CLI for `--model codex-cli` / `cursor-cli`) is checked up front.
 
 ## Remote devices — `vk server`
 

package/dist/agent/cli-provider.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliProvider = exports.CURSOR_SPEC = exports.CODEX_SPEC = void 0;
+exports.cursorResultText = cursorResultText;
+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)',
+};
+/** cursor-agent (Cursor CLI): non-interactive `--print` with a JSON envelope on stdout. Unlike
+ *  codex it has NO schema flag of any kind, so the schema is injected into the prompt and
+ *  extractJson/parsePlan do the rest. Two flags are load-bearing beyond the obvious ones:
+ *  `--trust`, without which a headless call dies at a "Workspace Trust Required" gate and exits 1
+ *  before the model ever runs; and `--mode ask`, cursor's documented read-only Q&A mode, which
+ *  stands in for codex's `--sandbox read-only` (cursor's own `--sandbox` only takes enabled/
+ *  disabled). Plain `--print` "has access to all tools, including write and shell", so `--mode ask`
+ *  plus the neutral `--workspace` are what keep this a pure transform — and we deliberately never
+ *  pass --force/--yolo/--approve-mcps. */
+exports.CURSOR_SPEC = {
+    id: 'cursor',
+    bin: 'cursor-agent',
+    schema: 'prompt', // no native schema flag — schemaInstruction() injects it into the prompt
+    usesOutputFile: false, // stdout is the only channel out; no --output-last-message equivalent
+    buildArgs(prompt, { cwd, model }) {
+        const args = [
+            '--print', // non-interactive one-shot
+            '--output-format', 'json', // a stable envelope instead of TTY-decorated text
+            '--mode', 'ask', // read-only Q&A mode: no edits, no shell
+            '--workspace', cwd, // root the agent in a neutral temp dir, not the verikun working tree
+            '--trust', // required: else headless stops at the workspace-trust prompt
+        ];
+        if (model)
+            args.push('--model', model);
+        args.push(prompt); // prompt is the trailing positional
+        return args;
+    },
+    rawText: cursorResultText,
+    loginHint: 'run `cursor-agent login` to sign in with your Cursor subscription (no API key needed)',
+};
+/** Peel the model's final message out of cursor-agent's `--output-format json` envelope:
+ *  `{type:"result", subtype:"success", is_error:false, result:"<final text>", …}`.
+ *  Two things a plain `JSON.parse(s).result` would get wrong:
+ *  - cursor can exit 0 while reporting failure via `is_error:true` (e.g. it hit a turn limit), which
+ *    CliProvider's exit-code check cannot see. Left alone, the error prose would flow into
+ *    extractJson and surface as a misleading "did not return parseable JSON", so map it to the same
+ *    exit 3 a non-zero exit gets.
+ *  - an envelope shape drift (or a future default of --output-format text) falls back to the raw
+ *    stdout, so extractJson's tolerant scan still gets a chance instead of failing outright. */
+function cursorResultText(stdout) {
+    let envelope;
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            envelope = parsed;
+    }
+    catch {
+        /* not JSON at all (e.g. --output-format text) — fall through to the raw stdout */
+    }
+    if (!envelope)
+        return stdout;
+    if (envelope.is_error === true) {
+        const detail = typeof envelope.result === 'string' ? tail(envelope.result) : '';
+        throw new errors_1.CliError(`\`cursor-agent\` reported an error: ${detail || '(no detail)'}`, 3);
+    }
+    // Only peel when this really IS the envelope. Parsing alone isn't enough: if cursor ever returns
+    // the plan object bare (or renames the field), treating any JSON object as an envelope would
+    // blank it to '' and report "returned an empty response" — so anything without a string
+    // `result` falls through to the raw stdout, where extractJson can still find the object.
+    return typeof envelope.result === 'string' ? envelope.result : stdout;
+}
+// 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,13 @@ 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 backends: billed to the user's ChatGPT/Cursor subscription via an already-logged-in
+    // 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). The `-cli` suffix reads clearly as "the
+    // CLI" and keeps these from colliding with the CLIs' own model aliases — cursor in particular
+    // offers `gpt-5.3-codex`, `gpt-5.4-high`, `claude-opus-4-8-thinking-high` and friends.
+    'codex-cli': { input: 0, output: 0, provider: 'codex' },
+    'cursor-cli': { input: 0, output: 0, provider: 'cursor' },
 };
 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/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,43 @@ 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';
+/** The CLI-agent backends, by ProviderId. Adding a CLI provider is one entry here rather than a
+ *  new arm in each of the three functions below — they all ask the same question of it. */
+const CLI_SPECS = { codex: cli_provider_1.CODEX_SPEC, cursor: cli_provider_1.CURSOR_SPEC };
+/** 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) {
+    const id = (0, cost_1.providerFor)(model);
+    const spec = CLI_SPECS[id];
+    if (spec)
+        return (0, exec_1.commandExists)(spec.bin);
+    return id === 'openai' ? !!process.env.OPENAI_API_KEY : !!process.env.ANTHROPIC_API_KEY;
+}
+/** What's missing when a provider is unavailable — the tail of the preflight error message. */
+function providerRequirement(model) {
+    const id = (0, cost_1.providerFor)(model);
+    const spec = CLI_SPECS[id];
+    // Reuse the spec's own loginHint rather than restating it, so the two can't drift apart.
+    if (spec)
+        return `the \`${spec.bin}\` CLI was not found on PATH — install it and ${spec.loginHint}`;
+    return id === 'openai' ? 'OPENAI_API_KEY is not set' : '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.
+ *  CLI providers get no `model`, so the CLI picks its own default — the "I just have a
+ *  subscription" path; --effort is likewise inapplicable to them. */
 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 });
+    const id = (0, cost_1.providerFor)(opts.model);
+    const spec = CLI_SPECS[id];
+    if (spec)
+        return (0, exec_1.commandExists)(spec.bin) ? new cli_provider_1.CliProvider({ spec }) : null;
+    if (id === 'openai') {
+        const apiKey = process.env.OPENAI_API_KEY;
+        return apiKey ? new openai_1.OpenAiProvider({ model: opts.model, apiKey, effort: opts.effort }) : null;
+    }
+    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 +1033,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 +1104,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 +1290,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 +1584,19 @@ 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 — no API key: --model
+                                      codex-cli uses your 'codex login' ChatGPT
+                                      subscription, cursor-cli your 'cursor-agent login'
+                                      Cursor one (cost is $0 for both, 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 |
+                                      cursor-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.8.0';
+exports.VERSION = '0.10.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.8.0",
+  "version": "0.10.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",

package/dist/drivers/simctl.js

@@ -1,156 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SimctlDriver = void 0;
-const node_os_1 = require("node:os");
-const node_path_1 = require("node:path");
-const node_fs_1 = require("node:fs");
-const errors_1 = require("../errors");
-const exec_1 = require("../exec");
-const XCRUN = 'xcrun';
-function listPhysicalDevices() {
-    const r = (0, exec_1.runText)(XCRUN, ['devicectl', 'list', 'devices']);
-    if (r.code !== 0)
-        return [];
-    const lines = r.stdout.split('\n');
-    const headerIdx = lines.findIndex((l) => l.includes('Identifier'));
-    if (headerIdx < 0)
-        return [];
-    const header = lines[headerIdx];
-    const nameCol = header.indexOf('Name');
-    const hostCol = header.indexOf('Hostname');
-    const idCol = header.indexOf('Identifier');
-    const stateCol = header.indexOf('State');
-    const modelCol = header.indexOf('Model');
-    const devices = [];
-    for (const line of lines.slice(headerIdx + 2)) {
-        if (!line.trim() || line.startsWith('-'))
-            continue;
-        const identifier = line.slice(idCol, stateCol).trim();
-        const state = line.slice(stateCol, modelCol).trim();
-        const name = line.slice(nameCol, hostCol).trim();
-        const model = line.slice(modelCol).trim();
-        if (!identifier)
-            continue;
-        const productMatch = model.match(/\(([^)]+)\)$/);
-        devices.push({
-            serial: identifier,
-            state,
-            model: name,
-            product: productMatch?.[1],
-            platform: 'ios',
-            note: 'physical — screenshot only, tap/ui not supported',
-        });
-    }
-    return devices;
-}
-// iOS support is intentionally partial. `simctl` covers screenshots, launch,
-// and stop. Full interaction (tap, swipe, type) and the accessibility hierarchy
-// require WebDriverAgent (https://github.com/appium/WebDriverAgent) — the
-// planned next step. WDA is an open-source XCTest HTTP server: build it once
-// in Xcode, sign it with your Apple developer certificate, and run it on the
-// target device or simulator. No Python required; works on both simulators and
-// physical devices. The Driver seam is already in place so the command layer
-// won't change when WDA support is added.
-function notSupported(feature) {
-    throw new errors_1.CliError(`iOS ${feature} is not supported yet.\n` +
-        'Screenshots, launch, and stop work today via xcrun simctl.\n' +
-        'Full interaction (tap / swipe / type) and UI hierarchy inspection are planned\n' +
-        'via WebDriverAgent — build it once in Xcode and vk will drive it over HTTP.\n' +
-        'See: https://github.com/appium/WebDriverAgent', 3);
-}
-class SimctlDriver {
-    platform = 'ios';
-    udid;
-    constructor(device) {
-        this.udid = device || 'booted';
-    }
-    listDevices() {
-        const devices = [];
-        // Simulators via simctl
-        const { stdout } = (0, exec_1.runText)(XCRUN, ['simctl', 'list', 'devices', 'available', '--json']);
-        try {
-            const data = JSON.parse(stdout);
-            for (const [runtime, list] of Object.entries(data.devices)) {
-                for (const d of list) {
-                    devices.push({
-                        serial: d.udid,
-                        state: d.state.toLowerCase(),
-                        model: d.name,
-                        product: runtime.split('.').pop(),
-                        platform: 'ios',
-                    });
-                }
-            }
-        }
-        catch {
-            /* tolerate unexpected simctl output */
-        }
-        // Physical devices via devicectl (Xcode 15+)
-        devices.push(...listPhysicalDevices());
-        return devices;
-    }
-    resolvedSerial() {
-        return this.udid;
-    }
-    screenshot() {
-        const tmp = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `verikun-ios-${process.pid}.png`);
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'io', this.udid, 'screenshot', tmp]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl screenshot failed: ${r.stderr.trim()}`, 3);
-        const buf = (0, node_fs_1.readFileSync)(tmp);
-        try {
-            (0, node_fs_1.unlinkSync)(tmp);
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        return buf;
-    }
-    launch(appId) {
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'launch', this.udid, appId]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl launch failed: ${r.stderr.trim()}`, 3);
-    }
-    stop(appId) {
-        const r = (0, exec_1.runText)(XCRUN, ['simctl', 'terminate', this.udid, appId]);
-        if (r.code !== 0)
-            throw new errors_1.CliError(`simctl terminate failed: ${r.stderr.trim()}`, 3);
-    }
-    clearApp(appId) {
-        // simctl has no per-app data reset. The manual equivalent is to uninstall and
-        // reinstall, which also removes the app itself — so we don't do it implicitly.
-        throw new errors_1.CliError(`iOS app-data clearing is not supported yet (requested for '${appId}').\n` +
-            'simctl has no per-app data reset; uninstall + reinstall ' +
-            '(`xcrun simctl uninstall <udid> <bundleId>`) is the manual equivalent, but it removes the app too.', 3);
-    }
-    getElements() {
-        return notSupported('hierarchy inspection');
-    }
-    screenSize() {
-        return notSupported('screen size');
-    }
-    tap() {
-        notSupported('tap');
-    }
-    swipe() {
-        notSupported('swipe');
-    }
-    inputText() {
-        notSupported('text input');
-    }
-    pressKey() {
-        notSupported('key events');
-    }
-    currentApp() {
-        return notSupported('current app');
-    }
-    getLogs() {
-        // Eventually: `xcrun simctl spawn <udid> log show` (simulators) / devicectl
-        // (physical). Heavier (predicate language, large output) — deferred with WDA.
-        return notSupported('log capture');
-    }
-    deviceTime() {
-        return ''; // no log window to anchor while iOS log capture is unsupported
-    }
-}
-exports.SimctlDriver = SimctlDriver;