verikun 0.7.0 → 0.8.0

package/README.md

@@ -232,6 +232,11 @@ a hard iteration cap and stop early if the screen stops changing.
 - 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
 
@@ -424,6 +429,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/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/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.8.0';

package/package.json

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