@yoqa/cli 0.3.28 → 0.3.29

package/dist/main.js

@@ -2122,7 +2122,7 @@ var require_commander = __commonJS((exports) => {
 });
 
 // src/program.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile2, writeFile as writeFile3 } from "node:fs/promises";
 
 // ../../node_modules/zod/v3/external.js
 var exports_external = {};
@@ -6105,6 +6105,7 @@ var healthResponseSchema = exports_external.object({
   uptimeMs: exports_external.number().nonnegative()
 });
 var devicePlatformSchema = exports_external.union([exports_external.literal("ios"), exports_external.literal("android")]);
+var laneNameSchema = exports_external.union([exports_external.literal("appium"), exports_external.literal("direct")]);
 var deviceKindSchema = exports_external.union([
   exports_external.literal("physical"),
   exports_external.literal("simulator"),
@@ -6632,7 +6633,8 @@ var createRunRequestSchema = exports_external.object({
   buildId: exports_external.string().min(1).optional(),
   buildPath: exports_external.string().min(1).optional(),
   executionMode: runExecutionModeSchema.optional(),
-  screenMode: runScreenModeSchema.optional()
+  screenMode: runScreenModeSchema.optional(),
+  lane: exports_external.union([laneNameSchema, exports_external.literal("auto")]).optional()
 });
 var stepPhasesSchema = exports_external.object({
   captureMs: exports_external.number().nonnegative(),
@@ -6677,6 +6679,8 @@ var runSchema = exports_external.object({
   status: runStatusSchema,
   executionMode: runExecutionModeSchema,
   screenMode: runScreenModeSchema.optional(),
+  lane: laneNameSchema.optional(),
+  laneWarning: exports_external.string().min(1).optional(),
   error: exports_external.string().nullable(),
   createdAt: exports_external.number().int().nonnegative(),
   startedAt: exports_external.number().int().nonnegative().nullable(),
@@ -6694,7 +6698,8 @@ var connectDeviceRequestSchema = exports_external.object({
   deviceId: exports_external.string().min(1),
   platform: devicePlatformSchema,
   bundleId: exports_external.string().min(1).optional(),
-  appPackage: exports_external.string().min(1).optional()
+  appPackage: exports_external.string().min(1).optional(),
+  lane: exports_external.union([laneNameSchema, exports_external.literal("auto")]).optional()
 });
 var activeDeviceResponseSchema = exports_external.object({
   deviceId: exports_external.string().min(1),
@@ -6703,7 +6708,9 @@ var activeDeviceResponseSchema = exports_external.object({
   mjpegPort: exports_external.number().int().positive().optional(),
   streamReady: exports_external.boolean().optional(),
   streamUrl: exports_external.string().min(1).optional(),
-  heldByRun: exports_external.boolean().optional()
+  heldByRun: exports_external.boolean().optional(),
+  lane: laneNameSchema.optional(),
+  laneWarning: exports_external.string().min(1).optional()
 });
 var controlPointerMessageSchema = exports_external.object({
   type: exports_external.literal("pointer"),
@@ -6764,15 +6771,23 @@ var actionRequestSchema = exports_external.object({
   alertAction: exports_external.union([exports_external.literal("accept"), exports_external.literal("dismiss")]).optional(),
   seconds: exports_external.number().optional(),
   screenshot: exports_external.boolean().optional(),
-  settleMs: exports_external.number().int().min(0).max(1e4).optional()
+  settleMs: exports_external.number().int().min(0).max(1e4).optional(),
+  fullImage: exports_external.boolean().optional(),
+  imageScale: exports_external.number().min(0.01).max(1).optional()
 });
 var actionResultScreenshotSchema = exports_external.object({
   path: exports_external.string().min(1),
+  rawPath: exports_external.string().min(1).optional(),
   annotatedPath: exports_external.string().min(1).optional(),
   settled: exports_external.boolean(),
   waitedMs: exports_external.number(),
   changed: exports_external.boolean().nullable()
 });
+var actionPhasesSchema = exports_external.object({
+  captureMs: exports_external.number().nonnegative(),
+  actionMs: exports_external.number().nonnegative(),
+  settleMs: exports_external.number().nonnegative()
+});
 var actionResponseSchema = exports_external.object({
   ok: exports_external.literal(true),
   kind: actionKindSchema,
@@ -6780,7 +6795,23 @@ var actionResponseSchema = exports_external.object({
     x: exports_external.number().optional(),
     y: exports_external.number().optional()
   }).optional(),
-  screenshot: actionResultScreenshotSchema.optional()
+  screenshot: actionResultScreenshotSchema.optional(),
+  phases: actionPhasesSchema.optional()
+});
+var actionBatchRequestSchema = exports_external.object({
+  steps: exports_external.array(actionRequestSchema).min(1),
+  settleMs: exports_external.number().int().min(0).max(1e4).optional(),
+  fullImage: exports_external.boolean().optional(),
+  imageScale: exports_external.number().min(0.01).max(1).optional()
+});
+var actionBatchResponseSchema = exports_external.object({
+  ok: exports_external.boolean(),
+  completed: exports_external.number().int().nonnegative(),
+  total: exports_external.number().int().nonnegative(),
+  failedIndex: exports_external.number().int().nonnegative().optional(),
+  error: exports_external.string().optional(),
+  screenshot: actionResultScreenshotSchema.optional(),
+  steps: exports_external.array(actionResponseSchema)
 });
 var yoqaStatusResponseSchema = exports_external.object({
   runner: exports_external.object({
@@ -7600,6 +7631,8 @@ function buildRunReportFromCatalogRun(run, meta = {}, screenshotsByStepId = {})
     platform: run.platform,
     executionMode: run.executionMode,
     screenMode: run.screenMode ?? null,
+    lane: run.lane ?? null,
+    laneWarning: run.laneWarning ?? null,
     error: run.error,
     createdAt: run.createdAt,
     startedAt: run.startedAt,
@@ -7647,7 +7680,11 @@ function pngDataUri(base64) {
 }
 function formatRunReportHtml(doc) {
   const accent = statusAccent(doc.status);
-  const screenRows = doc.screenMode ? [["Screen", doc.screenMode]] : [];
+  const screenRows = [
+    ...doc.screenMode ? [["Screen", doc.screenMode]] : [],
+    ...doc.lane ? [["Lane", doc.lane]] : [],
+    ...doc.laneWarning ? [["Lane warning", doc.laneWarning]] : []
+  ];
   const metaRows = [
     ["Status", accent.label],
     ["Source", doc.source === "catalog" ? "Catalog run" : "Manual Inspector"],
@@ -7782,6 +7819,8 @@ function formatRunReportMarkdown(doc) {
     `| Platform | ${escapeMd(doc.platform ?? "—")} |`,
     `| Mode | ${escapeMd(doc.executionMode ?? "—")} |`,
     ...doc.screenMode ? [`| Screen | ${escapeMd(doc.screenMode)} |`] : [],
+    ...doc.lane ? [`| Lane | ${escapeMd(doc.lane)} |`] : [],
+    ...doc.laneWarning ? [`| Lane warning | ${escapeMd(doc.laneWarning)} |`] : [],
     `| Started | ${escapeMd(formatWhen(doc.startedAt ?? doc.createdAt))} |`,
     `| Finished | ${escapeMd(formatWhen(doc.finishedAt))} |`,
     `| Duration | ${escapeMd(formatDuration(doc.startedAt ?? doc.createdAt, doc.finishedAt))} |`,
@@ -7849,6 +7888,8 @@ function formatRunReportGithubSummary(doc) {
     `| Platform | ${escapeMd(doc.platform ?? "—")} |`,
     `| Mode | ${escapeMd(doc.executionMode ?? "—")} |`,
     ...doc.screenMode ? [`| Screen | ${escapeMd(doc.screenMode)} |`] : [],
+    ...doc.lane ? [`| Lane | ${escapeMd(doc.lane)} |`] : [],
+    ...doc.laneWarning ? [`| Lane warning | ${escapeMd(doc.laneWarning)} |`] : [],
     `| Duration | ${escapeMd(formatDuration(doc.startedAt ?? doc.createdAt, doc.finishedAt))} |`,
     `| Run ID | \`${doc.id}\` |`,
     ""
@@ -8304,6 +8345,15 @@ class RunnerClient {
     }, "Action failed");
     return actionResponseSchema.parse(json);
   }
+  async performActionBatch(request) {
+    const body = actionBatchRequestSchema.parse(request);
+    const json = await this.requestJson("/action/batch", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    }, "Action batch failed");
+    return actionBatchResponseSchema.parse(json);
+  }
   async getStatus() {
     const json = await this.requestJson("/status", undefined, "Status failed");
     return yoqaStatusResponseSchema.parse(json);
@@ -8352,10 +8402,369 @@ var {
   Option,
   Help
 } = import__.default;
+
+// ../../services/runner/src/domains/benchmark/accuracy.ts
+function pointInElement(element, x, y) {
+  return x >= element.x && x <= element.x + element.width && y >= element.y && y <= element.y + element.height;
+}
+function tapHitsElement(elements, x, y, expect) {
+  const intended = expect?.id ? elements.filter((el) => el.id === expect.id) : expect?.label ? elements.filter((el) => el.label === expect.label) : elements;
+  return intended.some((el) => pointInElement(el, x, y));
+}
+
+// ../../services/runner/src/domains/benchmark/drivers.ts
+function yoqaBenchmarkDriver(client, options) {
+  return {
+    name: "yoqa",
+    connect: async () => {
+      await client.connectDevice({
+        deviceId: options.deviceId,
+        platform: options.platform,
+        lane: options.lane
+      });
+    },
+    screen: async () => {
+      await client.getScreen();
+    },
+    tapToResult: async (x, y, expect) => {
+      const result = await client.performAction({ kind: "tap", x, y, screenshot: true });
+      const tree = await client.getScreen().catch(() => ({ elements: [] }));
+      const hit = tapHitsElement(tree.elements ?? [], x, y, expect);
+      return {
+        hit,
+        phases: {
+          capture: result.phases?.captureMs ?? 0,
+          action: result.phases?.actionMs ?? 0,
+          settle: result.phases?.settleMs ?? result.screenshot?.waitedMs ?? 0
+        }
+      };
+    },
+    runCase: client.createRun && client.waitForRun && options.appId ? async (caseId) => {
+      const created = await client.createRun?.({
+        appId: options.appId ?? "",
+        caseIds: [caseId],
+        deviceId: options.deviceId,
+        platform: options.platform,
+        executionMode: "agent",
+        screenMode: options.screenMode,
+        lane: options.lane
+      });
+      if (!created)
+        return { passed: false };
+      const finished = await client.waitForRun?.(created.id);
+      const steps = finished?.tests?.reduce((n, test) => n + (test.steps?.length ?? 0), 0);
+      return { passed: finished?.status === "passed", steps };
+    } : undefined,
+    disconnect: async () => {
+      await client.disconnectDevice();
+    }
+  };
+}
+
+// ../../services/runner/src/domains/benchmark/scenario.ts
+async function runLatencyScenario(driver, options) {
+  const clock = options.clock ?? { now: () => Date.now() };
+  const taps = options.suite?.taps ?? [{ x: options.x ?? 500, y: options.y ?? 500 }];
+  const tapToResult = [];
+  const screenRead = [];
+  const coldStart = [];
+  const tapHits = [];
+  const casePasses = [];
+  const stepCounts = [];
+  const captures = [];
+  const actions = [];
+  const settles = [];
+  const t0 = clock.now();
+  await driver.connect();
+  options.advance?.(50);
+  coldStart.push(clock.now() - t0);
+  const tScreen = clock.now();
+  await driver.screen();
+  options.advance?.(20);
+  screenRead.push(clock.now() - tScreen);
+  for (let i = 0;i < options.repeats; i++) {
+    const tap = taps[i % taps.length];
+    if (!tap)
+      continue;
+    const tTap = clock.now();
+    const result = await driver.tapToResult(tap.x, tap.y, {
+      id: tap.id,
+      label: tap.label
+    });
+    options.advance?.(30);
+    tapToResult.push(clock.now() - tTap);
+    if (result.hit != null)
+      tapHits.push(result.hit);
+    if (result.phases?.capture != null)
+      captures.push(result.phases.capture);
+    if (result.phases?.action != null)
+      actions.push(result.phases.action);
+    if (result.phases?.settle != null)
+      settles.push(result.phases.settle);
+  }
+  if (driver.runCase && options.suite) {
+    const times = options.suite.passRepeats;
+    for (let i = 0;i < times; i++) {
+      for (const item of options.suite.cases) {
+        const outcome = await driver.runCase(item.caseId);
+        const passed = typeof outcome === "boolean" ? outcome : outcome.passed;
+        casePasses.push(passed);
+        if (typeof outcome !== "boolean" && outcome.steps != null) {
+          stepCounts.push(outcome.steps);
+        }
+      }
+    }
+  }
+  await driver.disconnect();
+  const phases = driver.name === "yoqa" && (captures.length || actions.length || settles.length) ? {
+    ...captures.length ? { capture: captures } : {},
+    ...actions.length ? { action: actions } : {},
+    ...settles.length ? { settle: settles } : {}
+  } : undefined;
+  return {
+    tool: driver.name,
+    platform: options.platform ?? "ios",
+    ...options.screenMode ? { screenMode: options.screenMode } : {},
+    tapToResult,
+    screenRead,
+    coldStart,
+    ...tapHits.length ? { tapHits } : {},
+    ...casePasses.length ? { casePasses } : {},
+    ...stepCounts.length ? { stepCounts } : {},
+    ...phases ? { phases } : {}
+  };
+}
+
+// ../../services/runner/src/domains/benchmark/suite.ts
+var BENCHMARK_SUITE_VERSION = 1;
+var DEFAULT_BENCHMARK_SUITE = {
+  version: BENCHMARK_SUITE_VERSION,
+  repeats: 5,
+  taps: [{ x: 500, y: 500 }],
+  cases: [],
+  passRepeats: 3,
+  arms: ["vision"]
+};
+function parseBenchmarkSuite(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Benchmark suite must be an object");
+  }
+  const value = raw;
+  const version = Number(value.version);
+  const repeats = Number(value.repeats);
+  const passRepeats = Number(value.passRepeats ?? 3);
+  if (!Number.isInteger(version) || version < 1) {
+    throw new Error("Benchmark suite version must be a positive integer");
+  }
+  if (!Number.isInteger(repeats) || repeats < 1) {
+    throw new Error("Benchmark suite repeats must be a positive integer");
+  }
+  if (!Array.isArray(value.taps) || value.taps.length === 0) {
+    throw new Error("Benchmark suite needs at least one tap");
+  }
+  const taps = value.taps.map((tap, i) => {
+    if (!tap || typeof tap !== "object") {
+      throw new Error(`Benchmark suite tap ${i} is invalid`);
+    }
+    const row = tap;
+    const x = Number(row.x);
+    const y = Number(row.y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      throw new Error(`Benchmark suite tap ${i} needs x and y`);
+    }
+    return {
+      x,
+      y,
+      ...typeof row.id === "string" ? { id: row.id } : {},
+      ...typeof row.label === "string" ? { label: row.label } : {}
+    };
+  });
+  const cases = Array.isArray(value.cases) ? value.cases.flatMap((item) => {
+    if (!item || typeof item !== "object")
+      return [];
+    const caseId = item.caseId;
+    return typeof caseId === "string" && caseId.length > 0 ? [{ caseId }] : [];
+  }) : [];
+  return {
+    version,
+    repeats,
+    taps,
+    cases,
+    passRepeats: Number.isInteger(passRepeats) ? passRepeats : 3,
+    arms: parseBenchmarkArms(value.arms)
+  };
+}
+function parseBenchmarkArms(raw) {
+  if (raw == null)
+    return ["vision"];
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new Error("Benchmark suite arms must be a non-empty list of vision | tree");
+  }
+  const arms = [];
+  for (const item of raw) {
+    if (item !== "vision" && item !== "tree") {
+      throw new Error("Benchmark suite arms must be vision or tree");
+    }
+    if (!arms.includes(item))
+      arms.push(item);
+  }
+  return arms;
+}
+
+// ../../services/runner/src/domains/benchmark/summarize.ts
+function percentile(samples, p) {
+  if (samples.length === 0)
+    return 0;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const rank = Math.ceil(p / 100 * sorted.length) - 1;
+  return sorted[Math.max(0, Math.min(sorted.length - 1, rank))] ?? 0;
+}
+function summarizeSamples(samples) {
+  return {
+    p50: percentile(samples, 50),
+    p95: percentile(samples, 95),
+    n: samples.length,
+    samples: [...samples]
+  };
+}
+function mean(samples) {
+  if (!samples || samples.length === 0)
+    return;
+  return samples.reduce((sum, n) => sum + n, 0) / samples.length;
+}
+function summarizeRate(hits) {
+  if (!hits || hits.length === 0)
+    return;
+  const n = hits.length;
+  const count = hits.filter(Boolean).length;
+  return { hits: count, n, rate: count / n };
+}
+function summarizeLatency(input) {
+  return {
+    recordedAt: input.recordedAt,
+    repeats: input.repeats,
+    ...input.suiteVersion != null ? { suiteVersion: input.suiteVersion } : {},
+    results: input.runs.map((run) => {
+      const capture = mean(run.phases?.capture);
+      const action = mean(run.phases?.action);
+      const settle = mean(run.phases?.settle);
+      const phases = capture != null || action != null || settle != null ? {
+        ...capture != null ? { capture } : {},
+        ...action != null ? { action } : {},
+        ...settle != null ? { settle } : {}
+      } : undefined;
+      const accuracy = summarizeRate(run.tapHits);
+      const passRate = summarizeRate(run.casePasses);
+      const steps = run.stepCounts?.length ? summarizeSamples(run.stepCounts) : undefined;
+      return {
+        tool: run.tool,
+        platform: run.platform,
+        ...run.screenMode ? { screenMode: run.screenMode } : {},
+        metrics: {
+          tapToResult: summarizeSamples(run.tapToResult),
+          screenRead: summarizeSamples(run.screenRead),
+          coldStart: summarizeSamples(run.coldStart)
+        },
+        ...accuracy ? { accuracy } : {},
+        ...passRate ? { passRate } : {},
+        ...steps ? { steps } : {},
+        ...phases ? { phases } : {}
+      };
+    })
+  };
+}
+function formatLatencyTable(report) {
+  const header = [
+    "tool".padEnd(12),
+    "platform".padEnd(10),
+    "metric".padEnd(14),
+    "p50".padStart(8),
+    "p95".padStart(8),
+    "n".padStart(4)
+  ].join(" ");
+  const lines = [header];
+  for (const row of report.results) {
+    const tool = row.screenMode ? `${row.tool}/${row.screenMode}` : row.tool;
+    for (const metric of ["tapToResult", "screenRead", "coldStart"]) {
+      const s = row.metrics[metric];
+      lines.push([
+        tool.padEnd(12),
+        row.platform.padEnd(10),
+        metric.padEnd(14),
+        String(Math.round(s.p50)).padStart(8),
+        String(Math.round(s.p95)).padStart(8),
+        String(s.n).padStart(4)
+      ].join(" "));
+    }
+    if (row.accuracy) {
+      lines.push([
+        tool.padEnd(12),
+        row.platform.padEnd(10),
+        "tapAccuracy".padEnd(14),
+        row.accuracy.rate.toFixed(2).padStart(8),
+        "".padStart(8),
+        String(row.accuracy.n).padStart(4)
+      ].join(" "));
+    }
+    if (row.passRate) {
+      lines.push([
+        tool.padEnd(12),
+        row.platform.padEnd(10),
+        "casePassRate".padEnd(14),
+        row.passRate.rate.toFixed(2).padStart(8),
+        "".padStart(8),
+        String(row.passRate.n).padStart(4)
+      ].join(" "));
+    }
+    if (row.steps) {
+      lines.push([
+        tool.padEnd(12),
+        row.platform.padEnd(10),
+        "stepCount".padEnd(14),
+        String(Math.round(row.steps.p50)).padStart(8),
+        String(Math.round(row.steps.p95)).padStart(8),
+        String(row.steps.n).padStart(4)
+      ].join(" "));
+    }
+    if (row.phases) {
+      const parts = Object.entries(row.phases).map(([k, v]) => `${k}=${Math.round(v)}`);
+      lines.push(`         phases ${parts.join(" ")}`);
+    }
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function recommendScreenDefault(vision, tree) {
+  if (!vision || !tree) {
+    return {
+      screenMode: "vision",
+      reason: "Need both vision and tree arms before flipping the default"
+    };
+  }
+  if (!vision.passRate || !tree.passRate) {
+    return {
+      screenMode: "vision",
+      reason: "No Case pass-rate samples; keep vision-first"
+    };
+  }
+  const visionAcc = vision.accuracy?.rate ?? 0;
+  const treeAcc = tree.accuracy?.rate ?? 0;
+  if (tree.passRate.rate > vision.passRate.rate && treeAcc >= visionAcc) {
+    return {
+      screenMode: "tree",
+      reason: "Tree arm won Case pass rate without losing tap accuracy"
+    };
+  }
+  return {
+    screenMode: "vision",
+    reason: "Tree arm did not beat vision on pass rate and accuracy; keep vision-first"
+  };
+}
 // package.json
 var package_default = {
   name: "@yoqa/cli",
-  version: "0.3.28",
+  version: "0.3.29",
   description: "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
   license: "UNLICENSED",
   type: "module",
@@ -8393,7 +8802,7 @@ var package_default = {
     health: "bun run src/main.ts health"
   },
   dependencies: {
-    "@yoqa/runner": "0.3.28"
+    "@yoqa/runner": "0.3.29"
   },
   devDependencies: {
     "@types/node": "^22.15.30",
@@ -9244,23 +9653,30 @@ for (const platform of ["ios", "android"]) {
     }
   });
 }
-devices.command("connect").description("Open an Appium session on a device").argument("<deviceId>", "Device UDID / serial").requiredOption("--platform <platform>", "ios | android").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--bundle-id <id>", "iOS bundle id to launch").option("--app-package <id>", "Android application id to launch").option("--json", "Print raw JSON").action(async (deviceId, options) => {
+devices.command("connect").description("Open a Device Session on a device").argument("<deviceId>", "Device UDID / serial").requiredOption("--platform <platform>", "ios | android").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--bundle-id <id>", "iOS bundle id to launch").option("--app-package <id>", "Android application id to launch").option("--lane <lane>", "appium | direct | auto (Android / iOS sim auto → Direct)").option("--json", "Print raw JSON").action(async (deviceId, options) => {
   try {
     const platform = options.platform;
     if (platform !== "ios" && platform !== "android") {
       throw new Error("--platform must be ios or android");
     }
+    const lane = options.lane;
+    if (lane != null && lane !== "appium" && lane !== "direct" && lane !== "auto") {
+      throw new Error("--lane must be appium, direct, or auto");
+    }
     const body = await client(options.baseUrl).connectDevice({
       deviceId,
       platform,
       bundleId: options.bundleId,
-      appPackage: options.appPackage
+      appPackage: options.appPackage,
+      lane
     });
     if (options.json) {
       console.log(JSON.stringify(body, null, 2));
       return;
     }
-    console.log(`connected ${body.platform} ${body.deviceId}`);
+    console.log(`connected ${body.platform} ${body.deviceId} lane ${body.lane ?? "appium"}`);
+    if (body.laneWarning)
+      console.log(`lane warning: ${body.laneWarning}`);
   } catch (error) {
     fail("devices connect", error);
   }
@@ -9277,7 +9693,9 @@ devices.command("active").description("Show the currently connected device").opt
       console.log(JSON.stringify(body, null, 2));
       return;
     }
-    console.log(`${body.platform} ${body.deviceId}`);
+    console.log(`${body.platform} ${body.deviceId} lane ${body.lane ?? "appium"}`);
+    if (body.laneWarning)
+      console.log(`lane warning: ${body.laneWarning}`);
   } catch (error) {
     fail("devices active", error);
   }
@@ -9322,15 +9740,20 @@ program2.command("screenshot").description("Capture a screenshot from the active
 });
 var action = program2.command("action").description("Perform an action on the active device");
 function addActionOptions(cmd) {
-  return cmd.option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("-d, --description <text>", "Ground target by natural language").option("--label <text>", "Tap/focus by accessibility label (cleaned screen tree)").option("--id <text>", "Tap/focus by resource-id / accessibility id").option("--x <n>", "X in 0–1000", (v) => Number(v)).option("--y <n>", "Y in 0–1000", (v) => Number(v)).option("--x2 <n>", "End X in 0–1000", (v) => Number(v)).option("--y2 <n>", "End Y in 0–1000", (v) => Number(v)).option("--duration <ms>", "Gesture duration ms (long-press for tap)", (v) => Number(v)).option("--double", "Double-tap (tap only)").option("--text <text>", "Text to type").option("--app-id <id>", "Bundle id / application id").option("--url <url>", "URL to open").option("--seconds <n>", "Background seconds", (v) => Number(v)).option("--screenshot", "Wait for the screen to settle, then return the result screenshot (and a copy marking where the tap or swipe landed)").option("--settle <ms>", "With --screenshot: longest wait for the screen to settle (default 1500)", (v) => Number(v));
+  return cmd.option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("-d, --description <text>", "Ground target by natural language").option("--label <text>", "Tap/focus by accessibility label (cleaned screen tree)").option("--id <text>", "Tap/focus by resource-id / accessibility id").option("--x <n>", "X in 0–1000", (v) => Number(v)).option("--y <n>", "Y in 0–1000", (v) => Number(v)).option("--x2 <n>", "End X in 0–1000", (v) => Number(v)).option("--y2 <n>", "End Y in 0–1000", (v) => Number(v)).option("--duration <ms>", "Gesture duration ms (long-press for tap)", (v) => Number(v)).option("--double", "Double-tap (tap only)").option("--text <text>", "Text to type").option("--app-id <id>", "Bundle id / application id").option("--url <url>", "URL to open").option("--seconds <n>", "Background seconds", (v) => Number(v)).option("--screenshot", "Wait for the screen to settle, then return the result screenshot (and a copy marking where the tap or swipe landed)").option("--settle <ms>", "With --screenshot: longest wait for the screen to settle (default 1500)", (v) => Number(v)).option("--full", "With --screenshot: return the raw Result screenshot instead of the Agent image").option("--scale <n>", "With --screenshot: Agent image scale 0.01–1 (default: long edge ~1000 px)", (v) => Number(v));
 }
 function printResultScreenshot(shot) {
   console.log(`screenshot ${shot.path}`);
+  if (shot.rawPath)
+    console.log(`raw ${shot.rawPath}`);
   if (shot.annotatedPath)
     console.log(`marked ${shot.annotatedPath}`);
   console.log(`settled ${shot.settled} (${Math.round(shot.waitedMs)}ms)`);
   console.log(`changed ${shot.changed === null ? "unknown (screen still animating)" : shot.changed}`);
 }
+function printActionPhases(phases) {
+  console.log(`phases capture=${phases.captureMs} action=${phases.actionMs} settle=${phases.settleMs}`);
+}
 for (const kind of [
   "tap",
   "swipe",
@@ -9360,7 +9783,9 @@ for (const kind of [
         url: options.url,
         seconds: options.seconds,
         screenshot: options.screenshot === true ? true : undefined,
-        settleMs: options.settle
+        settleMs: options.settle,
+        fullImage: options.full === true ? true : undefined,
+        imageScale: options.scale
       });
       if (options.json) {
         console.log(JSON.stringify(body, null, 2));
@@ -9372,6 +9797,8 @@ for (const kind of [
       }
       if (body.screenshot)
         printResultScreenshot(body.screenshot);
+      if (body.phases)
+        printActionPhases(body.phases);
     } catch (error) {
       fail(`action ${kind}`, error);
     }
@@ -9383,7 +9810,9 @@ addActionOptions(action.command("alert").description("Accept or dismiss a system
       kind: "alert",
       alertAction: options.dismiss ? "dismiss" : "accept",
       screenshot: options.screenshot === true ? true : undefined,
-      settleMs: options.settle
+      settleMs: options.settle,
+      fullImage: options.full === true ? true : undefined,
+      imageScale: options.scale
     });
     if (options.json) {
       console.log(JSON.stringify(body, null, 2));
@@ -9396,6 +9825,44 @@ addActionOptions(action.command("alert").description("Accept or dismiss a system
     fail("action alert", error);
   }
 });
+addActionOptions(action.command("batch").description("Run known Actions from a JSON file or stdin (one Settle and Result screenshot at the end). Description-grounded steps are rejected.").argument("[file]", "JSON file of { steps: Action[] } or an Action array. Omit to read stdin.")).action(async (file, options) => {
+  try {
+    const raw = file ? await readFile2(file, "utf8") : await new Promise((resolve, reject) => {
+      const chunks = [];
+      process.stdin.on("data", (chunk) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      process.stdin.on("error", reject);
+    });
+    const parsed = JSON.parse(raw);
+    const steps = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && ("steps" in parsed) ? parsed.steps : null;
+    if (!Array.isArray(steps) || steps.length === 0) {
+      throw new Error("Batch JSON must be an Action array or { steps: Action[] }");
+    }
+    const body = await client(String(options.baseUrl)).performActionBatch({
+      steps,
+      settleMs: options.settle,
+      fullImage: options.full === true ? true : undefined,
+      imageScale: options.scale
+    });
+    if (options.json) {
+      console.log(JSON.stringify(body, null, 2));
+      return;
+    }
+    console.log(`batch ${body.ok ? "ok" : "failed"} ${body.completed}/${body.total}`);
+    if (body.failedIndex != null)
+      console.log(`failedIndex ${body.failedIndex}`);
+    if (body.error)
+      console.log(body.error);
+    if (body.screenshot)
+      printResultScreenshot(body.screenshot);
+    if (!body.ok)
+      process.exitCode = 1;
+  } catch (error) {
+    fail("action batch", error);
+  }
+});
 var setup = program2.command("setup").description("Install Appium and the platform driver (xcuitest / uiautomator2)");
 setup.command("ios").description("Ensure Appium + xcuitest; optionally build and install WDA on a physical device").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("--device <udid>", "Physical device UDID to install WebDriverAgent on").option("--kind <kind>", "Device kind: physical | simulator", "physical").option("--xcode <path>", "Xcode Contents/Developer path (DEVELOPER_DIR)").option("--team <teamId>", "Apple Development team ID").option("--identity <name>", 'Codesigning identity name, e.g. "Apple Development: …"').option("--force", "Force a full WebDriverAgent rebuild even when prep is reusable").action(async (options) => {
   try {
@@ -10022,7 +10489,7 @@ runsCmd.command("delete").argument("<runId>", "Run id").option("--base-url <url>
     fail("runs delete", error);
   }
 });
-runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("--cases <numbers>", "Comma-separated case numbers, e.g. 1,2,5").option("--device <id>", "Device id (defaults to active session)").option("--platform <platform>", "ios | android (defaults to active session)").option("--build-id <id>", "Registered build id to install before run").option("--build-path <path>", "Absolute build path to register + install").option("--mode <mode>", "auto | script | agent (default: auto)").option("--screen-mode <mode>", "vision | tree — what the agent sees: screenshot only, or also the accessibility tree (default: vision)").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("--wait", "Wait until the run finishes (passed / errored / cancelled)").option("--timeout <seconds>", "Wait timeout in seconds (default: 1800)", String(DEFAULT_RUN_WAIT_TIMEOUT_SECONDS)).option("--github-output", "Write run_id and status to $GITHUB_OUTPUT").option("--no-github-output", "Do not write GitHub step outputs").action(async (appArg, options) => {
+runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("--cases <numbers>", "Comma-separated case numbers, e.g. 1,2,5").option("--device <id>", "Device id (defaults to active session)").option("--platform <platform>", "ios | android (defaults to active session)").option("--build-id <id>", "Registered build id to install before run").option("--build-path <path>", "Absolute build path to register + install").option("--mode <mode>", "auto | script | agent (default: auto)").option("--screen-mode <mode>", "vision | tree — what the agent sees: screenshot only, or also the accessibility tree (default: vision)").option("--lane <lane>", "appium | direct | auto — Android / iOS sim auto → Direct").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print raw JSON").option("--wait", "Wait until the run finishes (passed / errored / cancelled)").option("--timeout <seconds>", "Wait timeout in seconds (default: 1800)", String(DEFAULT_RUN_WAIT_TIMEOUT_SECONDS)).option("--github-output", "Write run_id and status to $GITHUB_OUTPUT").option("--no-github-output", "Do not write GitHub step outputs").action(async (appArg, options) => {
   try {
     const c = client(options.baseUrl);
     const resolved = await resolveAppId(c, appArg);
@@ -10058,6 +10525,10 @@ runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("
     if (options.screenMode && !screenMode) {
       throw new Error("--screen-mode must be vision or tree");
     }
+    const lane = options.lane === "appium" || options.lane === "direct" || options.lane === "auto" ? options.lane : undefined;
+    if (options.lane && !lane) {
+      throw new Error("--lane must be appium, direct, or auto");
+    }
     let run = await c.createRun({
       appId: resolved.id,
       caseIds,
@@ -10066,7 +10537,8 @@ runsCmd.command("create").argument("<app>", "App prefix or id").requiredOption("
       buildId: options.buildId,
       buildPath: options.buildPath,
       executionMode,
-      screenMode
+      screenMode,
+      lane
     });
     if (options.wait) {
       try {
@@ -10245,6 +10717,58 @@ scriptCmd.command("run").argument("<file>", "Path to a .yoqa.json / CaseScript J
     fail("script run", error);
   }
 });
+program2.command("benchmark").description("Compare Yoqa (and Argent, when installed) tap-to-result latency on one device").requiredOption("--device <id>", "Device UDID / serial").requiredOption("--platform <platform>", "ios | android").option("--repeats <n>", "Tap-to-result repeats (default: suite repeats)", (v) => Number(v)).option("--suite <path>", "Versioned suite JSON (default: built-in v1)").option("--tools <list>", "Comma-separated: yoqa,argent (default: yoqa)", "yoqa").option("--lane <lane>", "Yoqa Lane: appium | direct | auto", "auto").option("--arms <list>", "Yoqa Screen arms: vision,tree (default: suite arms)").option("--app <id>", "Catalog App id for Case arms (required when the suite has cases)").option("--out <path>", "Write the JSON report to this path").option("--base-url <url>", "Runner base URL", runnerBaseUrl()).option("--json", "Print JSON instead of the table").action(async (options) => {
+  try {
+    const platform = options.platform;
+    if (platform !== "ios" && platform !== "android") {
+      throw new Error("--platform must be ios or android");
+    }
+    const lane = options.lane === "appium" || options.lane === "direct" || options.lane === "auto" ? options.lane : undefined;
+    if (options.lane && !lane)
+      throw new Error("--lane must be appium, direct, or auto");
+    const suite = options.suite ? parseBenchmarkSuite(JSON.parse(await readFile2(options.suite, "utf8"))) : DEFAULT_BENCHMARK_SUITE;
+    const arms = options.arms ? parseBenchmarkArms(options.arms.split(",").map((item) => item.trim())) : suite.arms;
+    const repeats = options.repeats && options.repeats > 0 ? options.repeats : suite.repeats;
+    const tools = options.tools.split(",").map((t) => t.trim());
+    const c = client(options.baseUrl);
+    const runs = [];
+    if (tools.includes("yoqa")) {
+      for (const screenMode of arms) {
+        runs.push(await runLatencyScenario(yoqaBenchmarkDriver(c, {
+          deviceId: options.device,
+          platform,
+          lane,
+          screenMode,
+          appId: options.app
+        }), { repeats, platform, suite, screenMode }));
+      }
+    }
+    if (tools.includes("argent")) {
+      console.error("Argent driver: install the argent CLI and re-run; skipping for now.");
+    }
+    const report = summarizeLatency({
+      recordedAt: new Date().toISOString(),
+      repeats,
+      suiteVersion: suite.version,
+      runs
+    });
+    const recommendation = recommendScreenDefault(report.results.find((row) => row.screenMode === "vision"), report.results.find((row) => row.screenMode === "tree"));
+    if (options.out) {
+      await writeFile3(options.out, `${JSON.stringify({ ...report, recommendation }, null, 2)}
+`);
+    }
+    if (options.json)
+      console.log(JSON.stringify({ ...report, recommendation }, null, 2));
+    else {
+      console.log(formatLatencyTable(report));
+      if (arms.includes("tree")) {
+        console.log(`default ${recommendation.screenMode} — ${recommendation.reason}`);
+      }
+    }
+  } catch (error) {
+    fail("benchmark", error);
+  }
+});
 function buildProgram() {
   return program2;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yoqa/cli",
-	"version": "0.3.28",
+	"version": "0.3.29",
 	"description": "Yoqa CLI — drive local mobile QA from the terminal or CI (talks to the Yoqa runner over HTTP)",
 	"license": "UNLICENSED",
 	"type": "module",
@@ -38,7 +38,7 @@
 		"health": "bun run src/main.ts health"
 	},
 	"dependencies": {
-		"@yoqa/runner": "0.3.28"
+		"@yoqa/runner": "0.3.29"
 	},
 	"devDependencies": {
 		"@types/node": "^22.15.30",