verikun 0.4.1

package/dist/agent/claude.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeProvider = void 0;
+const errors_1 = require("../errors");
+const format_1 = require("../ui/format");
+const ir_1 = require("./ir");
+const grammar_1 = require("./grammar");
+// The one v1 provider: Anthropic's Messages API over Node's built-in fetch — no SDK,
+// honoring the repo's zero-runtime-dependency rule. Structured output guarantees a
+// schema-valid plan; the stable grammar prefix is cache_control'd; 429/5xx retry with
+// backoff (no SDK to do it for us). The LLM runs here ONLY on compile + repair.
+const API_URL = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_VERSION = '2023-06-01';
+// Per-request wall-clock cap so a stalled connection can't hang the run past its
+// --timeout deadline (the engine checks the deadline only between calls, not during one).
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+// effort (output_config.effort) is rejected by Haiku 4.5; only send it for models
+// that accept it.
+const EFFORT_MODELS = new Set(['claude-opus-4-8', 'claude-sonnet-4-6', 'claude-fable-5']);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const backoffMs = (attempt) => Math.min(1000 * 2 ** (attempt - 1), 15000);
+class ClaudeProvider {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async compile(input) {
+        const parts = [];
+        if (input.pkg)
+            parts.push(`App package: ${input.pkg}`);
+        parts.push(`Platform: ${input.platform}`);
+        if (input.seed) {
+            parts.push('A plan compiled for a PREVIOUS build of this app follows. Reuse it where the test still holds; ' +
+                'change only what the test now requires. PRIOR PLAN:\n' +
+                JSON.stringify(input.seed, null, 2));
+        }
+        parts.push('NATURAL-LANGUAGE TEST:\n' + input.nl);
+        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 };
+    }
+    async repair(ctx) {
+        const parts = [
+            'FAILED STEP: ' + JSON.stringify(ctx.failedStep),
+            'FAILURE: ' + ctx.reason,
+        ];
+        if (ctx.candidates && ctx.candidates.length) {
+            parts.push(`The selector matched ${ctx.candidates.length} elements (ambiguous) — pick a more specific selector for the SAME intended element, or give_up if none of them is it.`);
+        }
+        parts.push('CURRENT SCREEN:\n' + (0, format_1.formatCompact)(ctx.hierarchy));
+        const { json, usage } = await this.call(grammar_1.REPAIR_GRAMMAR, parts.join('\n\n'), ir_1.REPAIR_DECISION_JSON_SCHEMA, 1024);
+        const decision = (json ?? {});
+        if (decision.decision === 'give_up') {
+            return {
+                replaceStep: null,
+                declineReason: decision.reason?.trim() || 'no element on the current screen matches the step intent',
+                usage,
+            };
+        }
+        // Hand the proposed leaf back UNVALIDATED — engine.ts validates every repair against
+        // the grammar before splicing (it is the execution trust boundary and can't assume a
+        // provider validated). A missing/invalid step is rejected there as a failed repair.
+        return { replaceStep: (decision.step ?? null), usage };
+    }
+    async call(system, user, schema, maxTokens) {
+        const outputConfig = { format: { type: 'json_schema', schema } };
+        if (this.opts.effort && EFFORT_MODELS.has(this.opts.model))
+            outputConfig.effort = this.opts.effort;
+        const res = await this.fetchWithRetry({
+            model: this.opts.model,
+            max_tokens: maxTokens,
+            // The grammar is the large, stable prefix — cache it so repeat calls in a
+            // repair-heavy session read it at ~0.1x instead of full input price.
+            system: [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }],
+            messages: [{ role: 'user', content: user }],
+            output_config: outputConfig,
+        });
+        if (res.stop_reason === 'refusal') {
+            throw new errors_1.CliError('Model refused the request (stop_reason=refusal).', 1);
+        }
+        if (res.stop_reason === 'max_tokens') {
+            throw new errors_1.CliError('Model output was truncated (max_tokens) before a complete result — raise max_tokens or shorten the test.', 1);
+        }
+        const text = (res.content ?? [])
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join('');
+        if (!text.trim())
+            throw new errors_1.CliError('Model returned an empty response.', 1);
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new errors_1.CliError('Model output was not valid JSON.', 1);
+        }
+        return { json, usage: res.usage ?? {} };
+    }
+    async fetchWithRetry(body) {
+        const maxRetries = this.opts.maxRetries ?? 4;
+        const timeoutMs = this.opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        let attempt = 0;
+        for (;;) {
+            // Abort a stalled request after timeoutMs so it can't hang forever; the abort is
+            // caught below and retried like any other network error (bounded by maxRetries).
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let res;
+            try {
+                res = await fetch(API_URL, {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-api-key': this.opts.apiKey,
+                        'anthropic-version': ANTHROPIC_VERSION,
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            catch (e) {
+                if (attempt++ >= maxRetries)
+                    throw new errors_1.CliError(`Anthropic API request failed: ${e.message}`, 3);
+                await sleep(backoffMs(attempt));
+                continue;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (res.ok)
+                return (await res.json());
+            // Retry 429 + 5xx with backoff, honoring Retry-After (no SDK to do it for us).
+            if ((res.status === 429 || res.status >= 500) && attempt++ < maxRetries) {
+                const retryAfter = Number(res.headers.get('retry-after'));
+                await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : backoffMs(attempt));
+                continue;
+            }
+            const errText = await res.text().catch(() => '');
+            // 401/403 = auth/permission (env); 400 = bad request (usage); else env.
+            const code = res.status === 401 || res.status === 403 ? 3 : res.status === 400 ? 2 : 3;
+            throw new errors_1.CliError(`Anthropic API error ${res.status}: ${errText.slice(0, 500)}`, code);
+        }
+    }
+}
+exports.ClaudeProvider = ClaudeProvider;

package/dist/agent/cost.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostTracker = exports.DEFAULT_MAX_COST_USD = exports.DEFAULT_MODEL = exports.ALLOWED_MODELS = exports.MODEL_PRICES = void 0;
+exports.resolveModel = resolveModel;
+exports.parseCostOverride = parseCostOverride;
+exports.priceFor = priceFor;
+exports.estimateCostUsd = estimateCostUsd;
+const errors_1 = require("../errors");
+// Per-1M-token prices (Anthropic, cached 2026-05-26). This table WILL drift as
+// pricing changes between releases — `--cost-override <input/output>` is the escape
+// hatch, and is authoritative when supplied. The --model allowlist is exactly the
+// keys of this table, so the two can never disagree.
+exports.MODEL_PRICES = {
+    'claude-haiku-4-5': { input: 1, output: 5 },
+    'claude-sonnet-4-6': { input: 3, output: 15 },
+    'claude-opus-4-8': { input: 5, output: 25 },
+    'claude-fable-5': { input: 10, output: 50 },
+};
+exports.ALLOWED_MODELS = Object.keys(exports.MODEL_PRICES);
+exports.DEFAULT_MODEL = 'claude-sonnet-4-6';
+/** Default total-run cost ceiling for `vk ai` when --max-cost-usd is not given, so a
+ *  runaway compile/repair loop can't spend unbounded tokens. */
+exports.DEFAULT_MAX_COST_USD = 3;
+/** Validate a --model against the allowlist (unknown -> exit 2, not a raw 404). */
+function resolveModel(model) {
+    if (!model)
+        return exports.DEFAULT_MODEL;
+    if (!exports.MODEL_PRICES[model]) {
+        throw new errors_1.CliError(`Unknown --model '${model}'. Allowed: ${exports.ALLOWED_MODELS.join(', ')}.`, 2);
+    }
+    return model;
+}
+/** Parse `--cost-override <input/output>` (e.g. "3/15" => $3 in / $15 out per 1M). */
+function parseCostOverride(raw) {
+    const m = /^(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)$/.exec(raw.trim());
+    if (!m)
+        throw new errors_1.CliError(`--cost-override must be <input/output> per 1M tokens, e.g. 3/15; got '${raw}'`, 2);
+    return { input: Number(m[1]), output: Number(m[2]) };
+}
+/** Resolve the price to use: an explicit override wins over the bundled table. */
+function priceFor(model, override) {
+    return override ?? exports.MODEL_PRICES[model] ?? exports.MODEL_PRICES[exports.DEFAULT_MODEL];
+}
+// Cache reads bill at ~0.1x input; cache writes (5-min TTL) at ~1.25x input.
+const CACHE_READ_MULT = 0.1;
+const CACHE_WRITE_MULT = 1.25;
+const PER_M = 1_000_000;
+/** Estimate the USD cost of a single API response from its `usage`. */
+function estimateCostUsd(usage, price) {
+    const input = usage.input_tokens ?? 0;
+    const output = usage.output_tokens ?? 0;
+    const cacheWrite = usage.cache_creation_input_tokens ?? 0;
+    const cacheRead = usage.cache_read_input_tokens ?? 0;
+    return ((input * price.input +
+        output * price.output +
+        cacheWrite * price.input * CACHE_WRITE_MULT +
+        cacheRead * price.input * CACHE_READ_MULT) /
+        PER_M);
+}
+/**
+ * Accumulates token usage across a run and exposes the running dollar estimate.
+ * `exceeded()` is the budget gate: when the estimate crosses `maxUsd`, the engine
+ * aborts the run (recording it as aborted) rather than spending unbounded tokens.
+ */
+class CostTracker {
+    price;
+    maxUsd;
+    cacheRead = 0;
+    compileUsd = 0;
+    repairUsd = 0;
+    constructor(price, maxUsd) {
+        this.price = price;
+        this.maxUsd = maxUsd;
+    }
+    /** Record one API response. `phase` splits compile vs repair spend for the report. */
+    add(usage, phase) {
+        this.cacheRead += usage.cache_read_input_tokens ?? 0;
+        const usd = estimateCostUsd(usage, this.price);
+        if (phase === 'compile')
+            this.compileUsd += usd;
+        else
+            this.repairUsd += usd;
+    }
+    usd() {
+        return this.compileUsd + this.repairUsd;
+    }
+    /** True once the running estimate has crossed the configured ceiling. */
+    exceeded() {
+        return this.maxUsd !== undefined && this.usd() >= this.maxUsd;
+    }
+    get budgetUsd() {
+        return this.maxUsd;
+    }
+    /** The `compile=… · repairs=… · replay=0 · cache_read=… · est $…` report line. */
+    summaryLine() {
+        const fmt = (n) => `$${n.toFixed(4)}`;
+        return `compile=${fmt(this.compileUsd)} · repairs=${fmt(this.repairUsd)} · replay=$0 · cache_read=${this.cacheRead} tok · est ${fmt(this.usd())}`;
+    }
+}
+exports.CostTracker = CostTracker;

package/dist/agent/engine.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RUN_TIMEOUT_MS = void 0;
+exports.runPlan = runPlan;
+const selector_1 = require("../ui/selector");
+const errors_1 = require("../errors");
+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 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). */
+function structuralHash(els) {
+    return els
+        .map((e) => `${e.idShort}|${e.text}|${e.type}`)
+        .sort()
+        .join('\n');
+}
+function isHealable(outcome) {
+    return (!!outcome.error &&
+        (outcome.error instanceof errors_1.SelectorNotFoundError || outcome.error instanceof errors_1.AmbiguousSelectorError));
+}
+/** Default wall-clock ceiling for a whole `vk ai` run (overridable via --timeout). */
+exports.DEFAULT_RUN_TIMEOUT_MS = 15 * 60 * 1000;
+async function runPlan(plan, deps) {
+    const maxRepairs = deps.maxRepairs ?? 3;
+    const overDeadline = () => deps.deadline !== undefined && Date.now() >= deps.deadline;
+    const improvements = [];
+    let modelRepairs = 0;
+    // A UI dump can fail transiently on a real device (uiautomator throws). Treat
+    // that as "empty screen" rather than letting it abort the whole run — the rest
+    // of the codebase treats dumps as recoverable (resolveOneWaiting re-polls).
+    const safeElements = () => {
+        try {
+            return deps.getElements();
+        }
+        catch {
+            return [];
+        }
+    };
+    const present = (selector) => {
+        // Re-fetch on a dump FAILURE (uiautomator can throw transiently) so a flaky dump at
+        // a guard check doesn't silently read as "absent" and skip a body that should run.
+        // Once a dump SUCCEEDS (even if empty) we trust it — no slow re-poll, so a genuinely
+        // absent guard still skips fast (the common if-present case).
+        let els;
+        for (let i = 0; i < 2 && els === undefined; i++) {
+            try {
+                els = deps.getElements();
+            }
+            catch {
+                /* transient dump failure — retry once before concluding "absent" */
+            }
+        }
+        if (els === undefined)
+            return false;
+        try {
+            return (0, selector_1.matchElements)(els, (0, selector_1.parseSelector)(selector)).matches.length > 0;
+        }
+        catch (e) {
+            // A guard selector that won't parse is a compiler/plan bug — surface it (then treat
+            // as not present) rather than silently skip the guarded body.
+            deps.log(`[ai] guard selector '${selector}' did not parse (${e.message}) — treating as not present`);
+            return false;
+        }
+    };
+    const runLeaf = (leaf) => deps.exec(leaf.command, leaf.positionals, (0, ir_1.leafToFlags)(leaf));
+    /** Execute one leaf, healing a selector miss/ambiguity via the model up to the cap.
+     *  `replace` writes a repaired leaf back into the plan so it persists on green. */
+    async function execLeaf(leaf, where, replace) {
+        deps.log(`[ai] ${where}: ${describe(leaf)}`);
+        let current = leaf;
+        let outcome = await runLeaf(current);
+        let attempts = 0;
+        while (isHealable(outcome) && attempts < maxRepairs) {
+            if (deps.cost.exceeded()) {
+                deps.log(`[ai] budget ceiling reached ($${deps.cost.budgetUsd}) — aborting before another repair`);
+                return { status: 'budget' };
+            }
+            if (overDeadline()) {
+                deps.log(`[ai] run timeout reached — aborting before another repair`);
+                return { status: 'timeout' };
+            }
+            attempts++;
+            const reason = outcome.error.message.split('\n')[0];
+            const candidates = outcome.error instanceof errors_1.AmbiguousSelectorError ? outcome.error.candidates : undefined;
+            deps.log(`[ai]   ${where} failed (${reason}) — asking model to repair (attempt ${attempts}/${maxRepairs})`);
+            let repaired;
+            try {
+                const { replaceStep, declineReason, usage } = await deps.provider.repair({
+                    failedStep: current,
+                    reason,
+                    candidates,
+                    hierarchy: safeElements(),
+                });
+                deps.cost.add(usage, 'repair');
+                // The model may DECLINE (null) when the current screen has no element serving
+                // this step's intent — i.e. the flow drifted to an unexpected screen. Fail
+                // terminally rather than substitute a loosely-related element, which would let
+                // a real regression pass as a false green (the bug this guards against).
+                if (replaceStep === null) {
+                    return { status: 'fail', where, reason: `drifted, not repaired: ${declineReason ?? 'no element matches the step intent'}` };
+                }
+                // The SOLE validation gate for a repair: the provider hands back the model's
+                // proposed leaf UNVALIDATED (a third-party provider can't be trusted to check),
+                // so the engine validates it against the grammar BEFORE splicing. A hallucinated
+                // command is rejected here, never run (it would otherwise exit 2 + abort).
+                const node = (0, ir_1.validateNode)(replaceStep, 'repair');
+                if (node.type !== 'command')
+                    throw new ir_1.InvalidPlanError('repair must be a single command step');
+                repaired = node;
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return { status: 'fail', where, reason: `repair failed: ${msg}` };
+            }
+            // The just-failed attempt was recorded as a failed step; downgrade it to a
+            // healed pass so a self-healed leaf doesn't surface as a failure in the
+            // report (the retry below records its own step).
+            deps.markHealed?.(`healed: ${reason} → ${describe(repaired)}`);
+            improvements.push(`${where}: "${describe(current)}" needed repair (${reason}); model replaced it with "${describe(repaired)}". ` +
+                `Update the test to "${describe(repaired)}" to skip this repair next run.`);
+            modelRepairs++;
+            current = repaired;
+            replace(current);
+            deps.log(`[ai]   ${where} repaired → ${describe(current)} (retrying)`);
+            outcome = await runLeaf(current);
+        }
+        if (outcome.code === 0)
+            return { status: 'ok' };
+        if (isHealable(outcome)) {
+            return { status: 'fail', where, reason: `unresolved after ${maxRepairs} repair attempt(s): ${outcome.error.message.split('\n')[0]}` };
+        }
+        // Terminal: an assertion failure (exit 1, no throw) or an environment error.
+        const reason = outcome.error ? outcome.error.message.split('\n')[0] : `exited ${outcome.code}`;
+        return { status: 'fail', where, reason };
+    }
+    async function walkBody(body, parentWhere) {
+        for (let j = 0; j < body.length; j++) {
+            const res = await execLeaf(body[j], `${parentWhere}.body[${j}]`, (l) => (body[j] = l));
+            if (res.status !== 'ok')
+                return res;
+        }
+        return { status: 'ok' };
+    }
+    async function walkNode(node, where, replace) {
+        switch (node.type) {
+            case 'command':
+                return execLeaf(node, where, replace);
+            case 'if-present': {
+                if (present(node.selector)) {
+                    deps.log(`[ai] ${where}: if-present '${node.selector}' → present, running ${node.body.length} step(s)`);
+                    return walkBody(node.body, where);
+                }
+                deps.log(`[ai] ${where}: if-present '${node.selector}' → absent, skipping`);
+                return { status: 'ok' };
+            }
+            case 'repeat': {
+                let prevHash = '';
+                for (let i = 0; i < node.cap; i++) {
+                    if (overDeadline()) {
+                        deps.log(`[ai] ${where}: run timeout reached — stopping repeat after ${i} iteration(s)`);
+                        return { status: 'timeout' };
+                    }
+                    if (present(node.selector)) {
+                        deps.log(`[ai] ${where}: repeat reached '${node.selector}' after ${i} iteration(s)`);
+                        return { status: 'ok' };
+                    }
+                    const hash = structuralHash(safeElements());
+                    if (i > 0 && hash === prevHash) {
+                        deps.log(`[ai] ${where}: repeat made no progress (screen unchanged) — stopping after ${i} iteration(s)`);
+                        return { status: 'ok' };
+                    }
+                    prevHash = hash;
+                    deps.log(`[ai] ${where}: repeat iteration ${i + 1}/${node.cap}`);
+                    const res = await walkBody(node.body, `${where}#${i + 1}`);
+                    if (res.status !== 'ok')
+                        return res;
+                }
+                deps.log(`[ai] ${where}: repeat hit cap ${node.cap} without '${node.selector}' (continuing)`);
+                return { status: 'ok' };
+            }
+        }
+    }
+    for (let i = 0; i < plan.steps.length; i++) {
+        if (overDeadline()) {
+            deps.log(`[ai] run timeout reached before steps[${i}] — aborting`);
+            return { ok: false, plan, modelRepairs, improvements, abortedForTimeout: true };
+        }
+        const res = await walkNode(plan.steps[i], `steps[${i}]`, (l) => (plan.steps[i] = l));
+        if (res.status === 'budget') {
+            return { ok: false, plan, modelRepairs, improvements, abortedForBudget: true };
+        }
+        if (res.status === 'timeout') {
+            return { ok: false, plan, modelRepairs, improvements, abortedForTimeout: true };
+        }
+        if (res.status === 'fail') {
+            deps.log(`[ai] FAILED at ${res.where}: ${res.reason}`);
+            return { ok: false, plan, modelRepairs, improvements, failure: { where: res.where, reason: res.reason } };
+        }
+    }
+    deps.log(`[ai] all ${plan.steps.length} step(s) passed${modelRepairs ? ` (${modelRepairs} model repair(s))` : ''}`);
+    return { ok: true, plan, modelRepairs, improvements };
+}

package/dist/agent/grammar.js

@@ -0,0 +1,80 @@
+"use strict";
+// The command grammar handed to the model so it compiles NL into a valid plan IR.
+// This mirrors the agent-facing contract in .claude/skills/verikun/SKILL.md; keep
+// the two in sync (the SKILL.md is the human/source-of-truth, this is the compact
+// runtime copy). It is the large, STABLE prefix of every compile/repair prompt, so
+// the provider marks it cache_control: ephemeral to bill repeat calls at ~0.1x.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPAIR_GRAMMAR = exports.GRAMMAR = void 0;
+exports.GRAMMAR = `You compile a natural-language mobile UI test into a verikun PLAN — a JSON program
+that a deterministic engine replays against a real Android/iOS device with NO further
+model calls on the happy path. Emit ONLY the plan object matching the provided schema.
+
+A plan has { "version": 1, "package"?, "platform"?, "steps": [...] }.
+Each step is one of three node types:
+
+1. COMMAND leaf — { "type":"command", "command":<name>, "positionals":[...], "flags":[{"name","value"}] }
+   A boolean flag is {"name":"clear","value":"true"}. A valued flag is {"name":"wait","value":"5s"}.
+   Available commands (verikun):
+     launch <package> [--clear] [--no-restart]  — start the app; force-stops it first so a
+                                  rerun starts FRESH (--clear also wipes data → fresh-install;
+                                  --no-restart skips the force-stop, just bringing it forward)
+     stop <package>               — force-stop the app
+     tap <selector>               — tap the element a selector resolves to
+     text <selector> <value...>   — focus a field and type value (--clear to clear first, --enter to submit)
+     type <value...>              — type into the already-focused field
+     key <name> | back | home | enter
+     swipe <up|down|left|right> [--on <selector>]  — scroll/swipe (up = scroll down the page)
+     assert <selector> [--text <s>] [--gone]       — assert presence/text/absence (FAILS the test if false)
+     wait <selector> [--gone] [--timeout <ms>]     — block until present/absent
+     screenshot                   — capture the screen into the report
+
+2. IF-PRESENT — { "type":"if-present", "selector":<sel>, "body":[<command leaves>] }
+   Run body ONLY if the selector is on screen now. Use for OPTIONAL interstitials:
+   permission dialogs, "rate us" popups, cookie banners, A/B variants. This is how you
+   keep a flow from breaking when an extra screen sometimes appears.
+
+3. REPEAT — { "type":"repeat", "selector":<sel>, "cap":<n>, "body":[<command leaves>] }
+   Repeat body until the selector appears, up to cap iterations. Use for "scroll until X
+   is visible". Always set a sane cap (e.g. 10). The engine also stops early if the screen
+   stops changing.
+
+NESTING: control-node bodies hold COMMAND leaves only — do NOT nest if-present/repeat
+inside another control node.
+
+SELECTORS (the engine auto-heals case/whitespace/partial, so prefer stable identifiers):
+  @login            resource-id 'login' (shorthand for id:login)
+  id:login          resource-id (full, suffix, or short)
+  text:Sign in      visible text (case-insensitive)
+  desc:Submit       content-desc / accessibility label
+  class:Button      type or class
+  "Sign in"         bare string == text:Sign in
+
+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.`;
+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:
+
+- "repair": the current screen genuinely contains an element that serves the SAME
+  PURPOSE as the failed step (the same control after a UI/build change, a renamed id,
+  a translated label, the same button relocated). Return it as ONE replacement command
+  leaf in "step", reusing the same command unless the screen clearly requires another.
+
+- "give_up": the screen does NOT contain an element matching the step's intent — e.g.
+  the flow has landed on an unexpected screen, a different app, or a dead end. Return
+  "give_up" with a short "reason". The test will then FAIL, which is the CORRECT result.
+
+"Same purpose" means the same user-facing action, NOT merely "a tappable element
+exists". Do NOT substitute a loosely-related or convenient element (a back arrow, a
+prominent unrelated button, a menu item that sounds similar) just to make the step
+pass — a wrong substitution hides a real regression behind a false green. If you are
+not confident the element does what the original step intended, choose give_up.
+
+Emit ONLY an object matching the schema:
+  { "decision":"repair", "step": { "type":"command","command","positionals":[...],"flags":[{"name","value"}] } }
+  { "decision":"give_up", "reason": "<why no element on this screen matches the intent>" }
+Prefer a stable selector (resource-id / accessibility label) visible in the hierarchy.
+Do not invent elements that are not in the hierarchy.`;