verikun 0.9.0 → 0.11.0

package/README.md

@@ -103,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), or no key with `--model codex-cli` (a logged-in `codex` CLI). 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
@@ -211,8 +211,9 @@ with no model calls on the happy path**. The model is woken only to *repair* a s
 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) — 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).
+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):
@@ -232,6 +233,14 @@ like permission dialogs) and **bounded loops** (`repeat … until`, e.g. scroll
 row appears) — control flow a flat [`batch`](#batch) script can't express. Loops carry
 a hard iteration cap and stop early if the screen stops changing.
 
+An `if-present` guard **waits for its selector to settle** before deciding the optional UI
+isn't there, so a dialog that animates in a beat after the transition is still caught. The
+window guarantees at least two looks at the screen (wall clock alone isn't a usable unit —
+a UI dump ranges from ~200ms on a fast phone to ~2.5s on an emulator), so an absent guard
+costs about one extra dump. `VERIKUN_GUARD_SETTLE_MS` tunes it; `0` restores the old
+single-shot probe. A loop's own exit check never pays this window — it's absent on every
+iteration by construction, which is what makes it a loop.
+
 - **Progress streams to stderr** (so a CI job never goes silent); **stdout is the
   report path** (or a JSON summary with `--json`). The compiled plan is logged to the
   run before it executes, for troubleshooting.
@@ -243,9 +252,12 @@ a hard iteration cap and stop early if the screen stops changing.
 - **`--model`** picks the model and its provider — Anthropic (`claude-haiku-4-5` ·
   `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`), 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.
+  (`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).
@@ -282,8 +294,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 provider (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, or the `codex` CLI for
-  `--model codex-cli`) 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`
 
@@ -363,7 +375,11 @@ class:Button    simplified type ("Button") or full class ("android.widget.Button
 ```
 
 Modifiers: `--contains` makes text/desc matches substring-based; `--index N`
-selects the Nth match (0-based) when a selector intentionally matches several.
+selects the Nth match (0-based) when a selector intentionally matches several;
+`--enabled` matches only a control that is **actionable right now** — use it for a
+Submit/Check button the app disables until a form is valid, since such a button is
+present long before it is usable and tapping presence taps a dead control (with
+auto-wait this reads as "wait until it is pressable").
 If a selector for an action matches more than one element and no `--index` is
 given, the command fails with exit code 2 and lists the candidates — it never
 taps a guess.

package/dist/agent/claude.js

@@ -35,6 +35,12 @@ class ClaudeProvider {
                 JSON.stringify(input.seed, null, 2));
         }
         parts.push('NATURAL-LANGUAGE TEST:\n' + input.nl);
+        if (input.retryFeedback) {
+            // Last, so it is the freshest thing in context: a previous compile of this same
+            // test lost something the prose stated. Naming it beats hoping the retry differs.
+            parts.push('YOUR PREVIOUS ATTEMPT AT THIS TEST WAS REJECTED. Fix this and emit the whole plan again:\n' +
+                input.retryFeedback);
+        }
         const { json, usage } = await this.call(grammar_1.GRAMMAR, parts.join('\n\n'), ir_1.PLAN_JSON_SCHEMA, 8192);
         return { plan: (0, ir_1.parsePlan)(json), usage };
     }

package/dist/agent/cli-provider.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliProvider = exports.CODEX_SPEC = void 0;
+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");
@@ -69,6 +70,67 @@ exports.CODEX_SPEC = {
     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;
@@ -94,6 +156,12 @@ class CliProvider {
                 JSON.stringify(input.seed, null, 2));
         }
         parts.push('NATURAL-LANGUAGE TEST:\n' + input.nl);
+        if (input.retryFeedback) {
+            // Last, so it is the freshest thing in context: a previous compile of this same
+            // test lost something the prose stated. Naming it beats hoping the retry differs.
+            parts.push('YOUR PREVIOUS ATTEMPT AT THIS TEST WAS REJECTED. Fix this and emit the whole plan again:\n' +
+                input.retryFeedback);
+        }
         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.

package/dist/agent/cost.js

@@ -21,11 +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 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.
+    // 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);