verikun 0.4.1 → 0.7.0

package/dist/cli.js

@@ -1,5 +1,40 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.platformFromFlags = platformFromFlags;
+exports.deviceFromFlags = deviceFromFlags;
 exports.parsePoint = parsePoint;
 exports.healNote = healNote;
 exports.parseDuration = parseDuration;
@@ -11,6 +46,7 @@ exports.chooseLogOpts = chooseLogOpts;
 exports.evalAssert = evalAssert;
 exports.tokenizeLine = tokenizeLine;
 exports.withBatchGlobals = withBatchGlobals;
+exports.executeForServer = executeForServer;
 exports.run = run;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -25,10 +61,14 @@ const run_1 = require("./run");
 const image_1 = require("./image");
 const engine_1 = require("./agent/engine");
 const claude_1 = require("./agent/claude");
+const openai_1 = require("./agent/openai");
 const cache_1 = require("./agent/cache");
 const cost_1 = require("./agent/cost");
+const remote_1 = require("./agent/remote");
+const suite_1 = require("./suite");
 const version_1 = require("./version");
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Exported for src/server.ts (which resolves its own platform/device at startup).
 function platformFromFlags(flags) {
     if ((0, args_1.flagBool)(flags, 'ios'))
         return 'ios';
@@ -149,10 +189,10 @@ function cmdDevices(ctx) {
     }
     try {
         // Only include booted simulators; always include physical devices (they carry a note)
-        allDevices.push(...new drivers_1.SimctlDriver().listDevices().filter((d) => d.state === 'booted' || d.note));
+        allDevices.push(...new drivers_1.IdbDriver().listDevices().filter((d) => d.state === 'booted' || d.note));
     }
     catch (e) {
-        (0, output_1.err)(`devices: simctl backend unavailable (${e.message})`);
+        (0, output_1.err)(`devices: iOS backend unavailable (${e.message})`);
     }
     if ((0, args_1.flagBool)(ctx.flags, 'json')) {
         (0, output_1.json)(allDevices);
@@ -171,18 +211,50 @@ function cmdDevices(ctx) {
 }
 function cmdDoctor(ctx) {
     if (ctx.platform === 'ios') {
-        const r = (0, exec_1.runText)('xcrun', ['simctl', 'list', 'devices', 'booted']);
-        (0, output_1.out)('xcrun: present');
-        (0, output_1.out)(r.stdout.trim() || '(no booted simulators)');
-        (0, output_1.out)('note: iOS screenshots + launch/stop work via simctl; tap/text/swipe/hierarchy need idb.');
-        return 0;
+        try {
+            const r = (0, exec_1.runText)('xcrun', ['simctl', 'list', 'devices', 'booted']);
+            (0, output_1.out)('xcrun: present');
+            (0, output_1.out)(r.stdout.trim() || '(no booted simulators)');
+        }
+        catch (e) {
+            // Not necessarily missing: runText also throws on a spawn timeout or other exec
+            // failure, so surface the real reason rather than always claiming "NOT FOUND".
+            (0, output_1.err)(`xcrun: ${e.message}`);
+            (0, output_1.err)('  (if the Xcode command-line tools are not installed: `xcode-select --install`)');
+            return 3;
+        }
+        // idb (+ its companion) powers everything interactive: ui/tap/text/swipe/key/logs.
+        const idb = process.env.IDB || 'idb';
+        let idbOk = true;
+        try {
+            (0, exec_1.runText)(idb, ['--help']); // idb has no --version; --help confirms the binary runs
+            (0, output_1.out)('idb: present');
+        }
+        catch (e) {
+            (0, output_1.err)(`idb: ${e.message}`);
+            (0, output_1.err)('  needed for ui/tap/text/swipe/key/logs — install: `brew install idb-companion` then `pip install fb-idb`');
+            idbOk = false;
+        }
+        try {
+            (0, exec_1.runText)('idb_companion', ['--help']);
+            (0, output_1.out)('idb_companion: present');
+        }
+        catch (e) {
+            (0, output_1.err)(`idb_companion: ${e.message}`);
+            (0, output_1.err)('  install: `brew install idb-companion`');
+            idbOk = false;
+        }
+        (0, output_1.out)('note: simulator screenshots + launch/stop work via simctl; ui/tap/text/swipe/key/logs use idb.');
+        return idbOk ? 0 : 3;
     }
     const adb = process.env.ADB || 'adb';
     try {
         (0, output_1.out)('adb: ' + (0, exec_1.runText)(adb, ['version']).stdout.split('\n')[0]);
     }
-    catch {
-        (0, output_1.err)('adb: NOT FOUND on PATH');
+    catch (e) {
+        // Not necessarily missing: runText also throws on a spawn timeout or other exec
+        // failure — surface the real reason rather than always claiming "NOT FOUND".
+        (0, output_1.err)(`adb: ${e.message}`);
         return 3;
     }
     const devices = ctx.driver.listDevices();
@@ -856,99 +928,157 @@ async function cmdBatch(positionals, batchFlags) {
         (0, output_1.err)(`[verikun] batch: ${commands.length} command(s) ok`);
     return 0;
 }
-// ---------------------------------------------------------------------------
-// ai — compile a natural-language test to a plan IR, then run it (self-healing)
-// ---------------------------------------------------------------------------
-//
-// `vk ai <file>` reads a plain-English test, compiles it ONCE into a deterministic
-// plan IR via the model (cached by NL + app build), then replays it with NO model
-// calls on the happy path. The model is woken only to repair a step that fails to
-// resolve its selector; a green run persists the (possibly repaired) plan so the
-// next run is free again. Cost is bounded by --max-cost-usd. Progress streams to
-// stderr (CI liveness — it never goes quiet); stdout carries the final result.
-async function cmdAi(positionals, flags) {
-    const file = positionals[0];
-    if (!file) {
-        throw new errors_1.CliError('Usage: verikun ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--show-plan] [--recompile]', 2);
-    }
-    let nl;
-    try {
-        nl = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), 'utf8');
-    }
-    catch (e) {
-        throw new errors_1.CliError(`ai: cannot read '${file}' (${e.message})`, 2);
-    }
-    if (!nl.trim())
-        throw new errors_1.CliError(`ai: '${file}' is empty`, 2);
-    const platform = platformFromFlags(flags);
-    const device = deviceFromFlags(flags, platform);
+function parseAiOptions(flags) {
     const model = (0, cost_1.resolveModel)((0, args_1.flagStr)(flags, 'model'));
     const overrideRaw = (0, args_1.flagStr)(flags, 'cost-override');
     const override = overrideRaw ? (0, cost_1.parseCostOverride)(overrideRaw) : undefined;
     const maxCostUsd = (0, args_1.flagNum)(flags, 'max-cost-usd') ?? cost_1.DEFAULT_MAX_COST_USD;
     if (maxCostUsd <= 0)
         throw new errors_1.CliError(`--max-cost-usd must be greater than 0 (got ${maxCostUsd}).`, 2);
-    const cost = new cost_1.CostTracker((0, cost_1.priceFor)(model, override), maxCostUsd);
     // Whole-run wall-clock ceiling (default 15m) so a runaway loop/repair can't hang the run.
     const timeoutFlag = (0, args_1.flagStr)(flags, 'timeout');
     const timeoutMs = timeoutFlag ? parseDuration(timeoutFlag, 'timeout') : engine_1.DEFAULT_RUN_TIMEOUT_MS;
-    const deadline = Date.now() + timeoutMs;
-    const effort = (0, args_1.flagStr)(flags, 'effort');
-    const pkg = (0, args_1.flagStr)(flags, 'package');
-    const build = (0, args_1.flagStr)(flags, 'app-build');
-    const key = { nl, pkg, build, platform };
-    const recompile = (0, args_1.flagBool)(flags, 'recompile') || (0, args_1.flagBool)(flags, 'no-cache');
-    const showPlan = (0, args_1.flagBool)(flags, 'show-plan');
-    const apiKey = process.env.ANTHROPIC_API_KEY;
-    const provider = apiKey ? new claude_1.ClaudeProvider({ model, apiKey, effort }) : null;
-    // 1. 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).
-    const cached = recompile ? null : (0, cache_1.readPlan)(key);
-    let plan;
+    return {
+        model,
+        price: (0, cost_1.priceFor)(model, override),
+        maxCostUsd,
+        timeoutMs,
+        effort: (0, args_1.flagStr)(flags, 'effort'),
+        pkg: (0, args_1.flagStr)(flags, 'package'),
+        build: (0, args_1.flagStr)(flags, 'app-build'),
+        recompile: (0, args_1.flagBool)(flags, 'recompile') || (0, args_1.flagBool)(flags, 'no-cache'),
+    };
+}
+function readAiTest(file) {
+    let nl;
+    try {
+        nl = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), 'utf8');
+    }
+    catch (e) {
+        throw new errors_1.CliError(`ai: cannot read '${file}' (${e.message})`, 2);
+    }
+    if (!nl.trim())
+        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';
+}
+/** 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. */
+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 });
+}
+/** 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
+ *  away, so an unchanged test is never recompiled — even via --show-plan or after a
+ *  failed run. A green run later re-persists the healed plan (never a half-healed one). */
+async function obtainPlan(key, file, opts, cost, provider) {
+    const cached = opts.recompile ? null : (0, cache_1.readPlan)(key);
     if (cached) {
-        plan = cached.plan;
-        (0, output_1.err)(`[ai] plan cache hit — ${model} not called to compile`);
+        (0, output_1.err)(`[ai] plan cache hit — ${opts.model} not called to compile`);
+        return { plan: cached.plan, cached: true };
     }
-    else {
-        if (!provider) {
-            throw new errors_1.CliError('ANTHROPIC_API_KEY is not set — `vk ai` needs it to compile the test. Set it and retry.', 3);
-        }
-        const seed = (0, cache_1.findSeed)(key);
-        if (seed)
-            (0, output_1.err)(`[ai] no exact cache; seeding from a prior plan (build ${seed.build ?? 'unknown'})`);
-        (0, output_1.err)(`[ai] compiling '${file}' with ${model} (effort ${effort ?? 'default'})…`);
-        const compiled = await provider.compile({ nl, pkg, platform, seed: seed?.plan });
-        cost.add(compiled.usage, 'compile');
-        plan = compiled.plan;
-        (0, output_1.err)(`[ai] compiled ${plan.steps.length} top-level step(s) · ${cost.summaryLine()}`);
-        // Cache the freshly-compiled plan right away, keyed by the test-text hash, so an
-        // unchanged test is never recompiled — even via --show-plan or after a failed run.
-        // A green run below re-persists the healed plan; a failed run leaves this clean
-        // compile cached (never a half-healed one).
-        try {
-            (0, cache_1.writePlan)(key, plan);
-        }
-        catch (e) {
-            (0, output_1.err)(`[ai] could not cache compiled plan: ${e.message}`);
-        }
+    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);
+    }
+    const seed = (0, cache_1.findSeed)(key);
+    if (seed)
+        (0, output_1.err)(`[ai] no exact cache; seeding from a prior plan (build ${seed.build ?? 'unknown'})`);
+    (0, output_1.err)(`[ai] compiling '${file}' with ${opts.model} (effort ${opts.effort ?? 'default'})…`);
+    const compiled = await provider.compile({ nl: key.nl, pkg: key.pkg, platform: key.platform, seed: seed?.plan });
+    cost.add(compiled.usage, 'compile');
+    (0, output_1.err)(`[ai] compiled ${compiled.plan.steps.length} top-level step(s) · ${cost.summaryLine()}`);
+    try {
+        (0, cache_1.writePlan)(key, compiled.plan);
     }
-    // 2. --show-plan: print the compiled IR and stop (no device run).
-    if (showPlan) {
-        (0, output_1.json)(plan);
-        return 0;
+    catch (e) {
+        (0, output_1.err)(`[ai] could not cache compiled plan: ${e.message}`);
     }
+    return { plan: compiled.plan, cached: false };
+}
+async function resolveBackend(platform, device, flags) {
+    const server = (0, args_1.flagStr)(flags, 'server') || process.env.VERIKUN_SERVER || undefined;
+    if (!server) {
+        const driver = (0, drivers_1.getDriver)(platform, device);
+        return {
+            backend: {
+                exec: (command, positionals, f) => executeOutcome(command, positionals, f, driver),
+                getElements: () => driver.getElements(),
+                install: (appPath) => driver.install(appPath),
+                reset: (appId) => {
+                    assertSafeAppId(appId);
+                    // iOS has no per-app data reset — degrade honestly to a force-stop.
+                    if (platform === 'ios')
+                        driver.stop(appId);
+                    else
+                        driver.clearApp(appId);
+                },
+            },
+            platform,
+            device,
+        };
+    }
+    let runCtx = { platform, device };
+    const opts = {
+        url: server,
+        authKey: (0, args_1.flagStr)(flags, 'auth-key') || process.env.VERIKUN_SERVER_AUTH_KEY || undefined,
+        // Each remote step is spliced into the local active run so the archived report
+        // is identical to a local run's.
+        onStep: (step, artifacts) => run_1.Recorder.appendForeignStep(step, artifacts, runCtx),
+    };
+    const health = await (0, remote_1.pingServer)(opts); // fails fast (exit 3) on a bad URL or key
+    runCtx = { platform: health.platform, device: health.serial };
+    (0, output_1.err)(`[verikun] server ${server}: ${health.platform} · device ${health.serial} · verikun ${health.version}`);
+    return {
+        backend: (0, remote_1.createRemoteBackend)(opts, health),
+        platform: health.platform,
+        device: health.serial,
+        remote: { url: server, version: health.version },
+    };
+}
+/**
+ * Run one natural-language test through a backend and return DATA — no stdout
+ * writes (stdout stays the caller's one result; progress streams to stderr).
+ * `vk ai` wraps it with its --json/report output; `vk suite` calls it per test.
+ */
+async function runAiTest(file, opts, backend, platform, device) {
+    const nl = readAiTest(file);
+    const key = { nl, pkg: opts.pkg, build: opts.build, platform };
+    const cost = new cost_1.CostTracker(opts.price, opts.maxCostUsd);
+    const deadline = Date.now() + opts.timeoutMs;
+    const provider = makeProvider(opts);
+    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('ANTHROPIC_API_KEY is not set — `vk ai` needs it to repair a failing step at runtime.', 3);
+        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);
     }
     // 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.
     if (!cached && cost.exceeded()) {
-        (0, output_1.err)(`[ai] cost ceiling $${maxCostUsd} reached during compile (${cost.summaryLine()}) — not running`);
-        return 1;
-    }
-    // 3. One explicit run + one shared driver for the whole flow (so rollover can't
-    //    split the test, and we don't rebuild a driver per step).
+        (0, output_1.err)(`[ai] cost ceiling $${opts.maxCostUsd} reached during compile (${cost.summaryLine()}) — not running`);
+        return {
+            ok: false,
+            costUsd: Number(cost.usd().toFixed(4)),
+            costLine: cost.summaryLine(),
+            modelRepairs: 0,
+            improvements: [],
+            runDir: '',
+            reportHtml: '',
+            junitXml: '',
+            state: null,
+            abortedForBudget: true,
+            failure: { where: 'compile', reason: `cost ceiling $${opts.maxCostUsd} reached during compile` },
+        };
+    }
+    // One explicit run for the whole flow (so rollover can't split the test).
     const existing = run_1.Recorder.status();
     if (existing && existing.steps.length > 0) {
         // Seal the pre-existing run into the archive instead of letting start(force=true)
@@ -957,14 +1087,13 @@ async function cmdAi(positionals, flags) {
         (0, output_1.err)(`[ai] archived the active run ('${existing.name}', ${existing.steps.length} step(s)) → ${sealed.dir}`);
     }
     run_1.Recorder.start(`ai: ${(0, node_path_1.basename)(file)}`, platform, device, true);
-    const driver = (0, drivers_1.getDriver)(platform, device);
     // Suppress per-step `out()` so stdout stays the one final result; progress -> stderr.
     const prevQuiet = (0, output_1.setOutputQuiet)(true);
     let result;
     try {
         result = await (0, engine_1.runPlan)(plan, {
-            exec: (command, pos, f) => executeOutcome(command, pos, f, driver),
-            getElements: () => driver.getElements(),
+            exec: (command, pos, f) => backend.exec(command, pos, f),
+            getElements: () => backend.getElements(),
             provider,
             cost,
             log: (m) => (0, output_1.err)(m),
@@ -991,8 +1120,8 @@ async function cmdAi(positionals, flags) {
     finally {
         (0, output_1.setOutputQuiet)(prevQuiet);
     }
-    // 4. Persist the (possibly repaired) plan only on a fully-green run; attach the
-    //    cost + improvements summary to the run; archive into the report.
+    // Persist the (possibly repaired) plan only on a fully-green run; attach the
+    // cost + improvements summary to the run; archive into the report.
     const costLine = cost.summaryLine();
     if (result.ok) {
         try {
@@ -1006,13 +1135,13 @@ async function cmdAi(positionals, flags) {
     run_1.Recorder.annotateRun({
         ai: { ok: result.ok, cost: costLine, modelRepairs: result.modelRepairs, improvements: result.improvements },
     });
-    const { dir, xmlPath, htmlPath } = run_1.Recorder.archive();
+    const { dir, xmlPath, htmlPath, state } = run_1.Recorder.archive();
     const status = result.ok
         ? 'PASS'
         : result.abortedForBudget
-            ? `ABORTED — cost ceiling $${maxCostUsd} reached`
+            ? `ABORTED — cost ceiling $${opts.maxCostUsd} reached`
             : result.abortedForTimeout
-                ? `ABORTED — run timeout (${Math.round(timeoutMs / 1000)}s) reached`
+                ? `ABORTED — run timeout (${Math.round(opts.timeoutMs / 1000)}s) reached`
                 : `FAIL at ${result.failure?.where}: ${result.failure?.reason}`;
     (0, output_1.err)(`[ai] ${status} · ${costLine}`);
     (0, output_1.err)(`[ai] report: ${htmlPath}`);
@@ -1022,28 +1151,124 @@ async function cmdAi(positionals, flags) {
             (0, output_1.err)('  - ' + imp);
     }
     (0, output_1.err)(`[ai] estimated total cost: $${cost.usd().toFixed(4)}`);
+    return {
+        ok: result.ok,
+        costUsd: Number(cost.usd().toFixed(4)),
+        costLine,
+        modelRepairs: result.modelRepairs,
+        improvements: result.improvements,
+        runDir: dir,
+        reportHtml: htmlPath,
+        junitXml: xmlPath,
+        state,
+        ...(result.failure ? { failure: result.failure } : {}),
+        ...(result.abortedForBudget ? { abortedForBudget: true } : {}),
+        ...(result.abortedForTimeout ? { abortedForTimeout: true } : {}),
+    };
+}
+async function cmdAi(positionals, flags) {
+    const file = positionals[0];
+    if (!file) {
+        throw new errors_1.CliError('Usage: verikun ai <file> [--model m] [--max-cost-usd n] [--timeout dur] [--server url] [--show-plan] [--recompile]', 2);
+    }
+    const opts = parseAiOptions(flags);
+    // --show-plan: compile (or cache-hit) and print the IR — no device, no backend.
+    if ((0, args_1.flagBool)(flags, 'show-plan')) {
+        const nl = readAiTest(file);
+        const key = { nl, pkg: opts.pkg, build: opts.build, platform: platformFromFlags(flags) };
+        const cost = new cost_1.CostTracker(opts.price, opts.maxCostUsd);
+        const { plan } = await obtainPlan(key, file, opts, cost, makeProvider(opts));
+        (0, output_1.json)(plan);
+        return 0;
+    }
+    const reqPlatform = platformFromFlags(flags);
+    const { backend, platform, device } = await resolveBackend(reqPlatform, deviceFromFlags(flags, reqPlatform), flags);
+    let result;
+    try {
+        result = await runAiTest(file, opts, backend, platform, device);
+    }
+    finally {
+        await backend.close?.(); // frees a remote server's device lock for the next command
+    }
     if ((0, args_1.flagBool)(flags, 'json')) {
         (0, output_1.json)({
             ok: result.ok,
-            model,
-            cost: costLine,
-            costUsd: Number(cost.usd().toFixed(4)),
+            model: opts.model,
+            cost: result.costLine,
+            costUsd: result.costUsd,
             modelRepairs: result.modelRepairs,
             improvements: result.improvements,
-            report: htmlPath,
-            junit: xmlPath,
-            runDir: dir,
+            report: result.reportHtml,
+            junit: result.junitXml,
+            runDir: result.runDir,
             ...(result.failure ? { failure: result.failure } : {}),
             ...(result.abortedForBudget ? { abortedForBudget: true } : {}),
             ...(result.abortedForTimeout ? { abortedForTimeout: true } : {}),
         });
     }
-    else {
-        (0, output_1.out)(htmlPath); // primary machine result: the report path
+    else if (result.reportHtml) {
+        (0, output_1.out)(result.reportHtml); // primary machine result: the report path
     }
     return result.ok ? 0 : 1;
 }
 // ---------------------------------------------------------------------------
+// install — put an app build on the device (local driver or remote vk server)
+// ---------------------------------------------------------------------------
+async function cmdInstall(positionals, flags) {
+    const appPath = positionals[0];
+    if (!appPath)
+        throw new errors_1.CliError('Usage: verikun install <app.apk|app.ipa> [--server url]', 2);
+    const path = (0, node_path_1.resolve)(process.cwd(), appPath);
+    if (!(0, node_fs_1.existsSync)(path))
+        throw new errors_1.CliError(`install: '${appPath}' does not exist`, 2);
+    const platform = platformFromFlags(flags);
+    const { backend, remote } = await resolveBackend(platform, deviceFromFlags(flags, platform), flags);
+    (0, output_1.err)(`[verikun] installing ${appPath}${remote ? ` via ${remote.url}` : ''}…`);
+    try {
+        await backend.install(path);
+    }
+    finally {
+        await backend.close?.();
+    }
+    if ((0, args_1.flagBool)(flags, 'json'))
+        (0, output_1.json)({ installed: appPath, ...(remote ? { server: remote.url } : {}) });
+    else
+        (0, output_1.out)(`installed ${appPath}`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// suite — run a directory of natural-language tests as one gated suite
+// ---------------------------------------------------------------------------
+async function cmdSuiteEntry(positionals, flags) {
+    const dirArg = positionals[0];
+    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
+    // 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);
+    }
+    const reqPlatform = platformFromFlags(flags);
+    const { backend, platform, device } = await resolveBackend(reqPlatform, deviceFromFlags(flags, reqPlatform), flags);
+    const app = (0, args_1.flagStr)(flags, 'app');
+    if (app)
+        assertSafeAppId(app);
+    try {
+        return await (0, suite_1.cmdSuite)(dirArg, flags, {
+            platform,
+            device,
+            runTest: (file) => runAiTest(file, opts, backend, platform, device),
+            // Reset app state between tests only when the app id is known; without --app,
+            // each test is responsible for its own isolation (e.g. `launch --clear`).
+            reset: app ? () => backend.reset(app) : undefined,
+        });
+    }
+    finally {
+        await backend.close?.();
+    }
+}
+// ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
 async function executeCommand(command, ctx) {
@@ -1149,7 +1374,19 @@ async function executeOutcome(command, positionals, flags, sharedDriver) {
             }
             recorder = run_1.Recorder.beginStep(command, positionals, flags, platform, device, serial, driver);
         }
-        const ctx = { driver, platform, device, positionals, flags, record: recorder ?? undefined };
+    }
+    catch (e) {
+        return { code: e instanceof errors_1.CliError ? e.exitCode : 3, error: e };
+    }
+    const d = driver; // assigned in the try above, or we already returned
+    const ctx = { driver: d, platform, device, positionals, flags, record: recorder ?? undefined };
+    return runRecorded(command, ctx, recorder, d);
+}
+/** The shared middle of executeOutcome / executeForServer: run the handler, close
+ *  the step (with failure evidence) whether it returned or threw, map to a raw
+ *  outcome (the error NOT printed — callers decide). */
+async function runRecorded(command, ctx, recorder, driver) {
+    try {
         const code = await executeCommand(command, ctx);
         recorder?.finish(code, driver);
         return { code };
@@ -1159,6 +1396,28 @@ async function executeOutcome(command, positionals, flags, sharedDriver) {
         return { code: e instanceof errors_1.CliError ? e.exitCode : 3, error: e };
     }
 }
+/**
+ * `vk server`'s per-request executor: run one already-validated leaf against the
+ * server's fixed driver/platform (a client can never repoint the device via flags),
+ * recording into an EPHEMERAL single-step recorder instead of the local run store.
+ * Returns the raw outcome plus the finished step + artifact buffers, which travel
+ * back over the wire and are spliced into the CALLER's run — so `resolved`/`tier`/
+ * failure evidence survive remoting with zero handler changes.
+ */
+async function executeForServer(command, positionals, flags, driver, platform) {
+    let serial;
+    try {
+        serial = driver.resolvedSerial();
+    }
+    catch {
+        /* surfaced by the command handler below */
+    }
+    const recorder = run_1.Recorder.beginEphemeralStep(command, positionals, flags, platform, serial);
+    const ctx = { driver, platform, device: serial, positionals, flags, record: recorder };
+    const outcome = await runRecorded(command, ctx, recorder, driver);
+    const { step, artifacts } = recorder.takeEphemeral();
+    return { ...outcome, step, artifacts };
+}
 /**
  * Run one already-parsed command for the CLI / `batch`: dispatch meta-commands,
  * else execute it and map any failure to a printed exit code. This is the shared
@@ -1174,9 +1433,9 @@ async function executeParsed(command, positionals, flags) {
         return cmdRun(positionals, flags, platform, device);
     if (command === 'batch')
         return cmdBatch(positionals, flags);
-    // `ai` orchestrates its own steps; map its thrown CliErrors to exit codes here
-    // (usage 2 / env 3 / …) so they honor the exit-code contract instead of escaping
-    // to the top-level "Fatal" handler (which would force exit 3).
+    // `ai`/`suite`/`install`/`server` orchestrate their own steps; map their thrown
+    // CliErrors to exit codes here (usage 2 / env 3 / …) so they honor the exit-code
+    // contract instead of escaping to the top-level "Fatal" handler (exit 3).
     if (command === 'ai') {
         try {
             return await cmdAi(positionals, flags);
@@ -1185,6 +1444,33 @@ async function executeParsed(command, positionals, flags) {
             return mapError(e, flags);
         }
     }
+    if (command === 'suite') {
+        try {
+            return await cmdSuiteEntry(positionals, flags);
+        }
+        catch (e) {
+            return mapError(e, flags);
+        }
+    }
+    if (command === 'install') {
+        try {
+            return await cmdInstall(positionals, flags);
+        }
+        catch (e) {
+            return mapError(e, flags);
+        }
+    }
+    if (command === 'server') {
+        // Dynamic import: keeps node:http off the default load path and avoids a
+        // static cli↔server cycle (server.ts imports executeForServer from here).
+        try {
+            const { cmdServer } = await Promise.resolve().then(() => __importStar(require('./server')));
+            return await cmdServer(positionals, flags);
+        }
+        catch (e) {
+            return mapError(e, flags);
+        }
+    }
     const { code, error } = await executeOutcome(command, positionals, flags);
     return error ? mapError(error, flags) : code;
 }
@@ -1232,6 +1518,9 @@ ACT
   launch <app> [--clear] [--no-restart]   stop <app>   App lifecycle (launch restarts by
                                         default — force-stops first; --clear also wipes app data)
   clear <app>                         Wipe app data — login/session, caches (fresh-install state)
+  install <app.apk|.ipa> [--server url]   Install a build on the device (adb install -r /
+                                      idb install). With --server, uploads the file to a
+                                      remote vk server (which must run --allow-install)
 
 BATCH (script many commands in one process)
   batch [--file path] [--quiet]       Run newline-separated commands — from --file,
@@ -1249,11 +1538,37 @@ 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. Progress -> stderr; the report
-                                      path -> stdout. --show-plan prints the compiled
-                                      IR without running; --recompile ignores the cache.
+                                      ANTHROPIC_API_KEY (Claude) or OPENAI_API_KEY
+                                      (gpt-5.x). 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.
+                                      (default) | claude-opus-4-8 | claude-fable-5 |
+                                      gpt-5.4-mini | gpt-5.4 | gpt-5.5.
+
+SUITE (run a directory of natural-language tests as one gated suite)
+  suite <dir> [--app <id>] [--name n] [--json]  (+ all \`ai\` flags, incl. --server)
+                                      Run every *.md in <dir> (lexicographic order —
+                                      prefix 01-, 02- to sequence; README.md skipped)
+                                      through \`vk ai\`. With --app, app data is reset
+                                      between tests (iOS: force-stop). Writes a suite
+                                      overview to ./.verikun/suites/<id>/{index.json,
+                                      index.html} linking each test's report. Exits 1
+                                      if any test failed — the CI gate.
+
+SERVER (expose a locally-connected device to remote verikun clients)
+  server [--bind addr] [--port n] [--auth-key k] [--allow-install]
+         [--allow-unsafe-anonymous]  Serve THIS machine's device over HTTP+JSON for
+                                      \`vk ai/suite/install --server <url>\`. Only
+                                      verikun's validated action grammar is runnable
+                                      (never a shell); auth is required (a key is
+                                      generated if none given; --allow-unsafe-anonymous
+                                      opts out for trusted networks e.g. Tailscale);
+                                      binds 127.0.0.1 by default (--bind to expose);
+                                      one run at a time holds the device lock.
+                                      Env: VERIKUN_SERVER_AUTH_KEY (keeps it off argv).
+  Clients: pass --server <url> (or VERIKUN_SERVER) + --auth-key (or
+  VERIKUN_SERVER_AUTH_KEY) to ai/suite/install. The server's device+platform apply.
 
 ENVIRONMENT
   devices [--json]                    List attached devices/simulators
@@ -1294,5 +1609,7 @@ GLOBAL FLAGS
 EXIT CODES
   0 success · 1 not found / assertion failed / timeout · 2 usage or ambiguous selector · 3 environment error
 
-iOS: screenshots + launch/stop work today via simctl; tap/text/swipe/hierarchy need idb (planned).`;
+iOS (--ios): full parity via idb — ui/tap/text/swipe/key + screenshot/launch/stop.
+  Needs idb (\`brew install idb-companion\` + \`pip install fb-idb\`); see \`vk doctor --ios\`.
+  Caveats: no \`clear\` (no per-app reset), \`current\` is (unknown), device logs are simulator-only.`;
 }