@vostride/agent-qa-ios 0.2.2 → 0.2.4

package/README.md

@@ -0,0 +1,78 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/banner-dark.jpg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/banner-light.png">
+  <img src="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/banner-light.png" alt="agent-qa by vostride — a self-improving QA agent for your software factory" width="100%">
+</picture>
+
+<p align="center">
+  <strong>English</strong> · <a href="https://github.com/vostride/agent-qa/blob/main/README.zh-CN.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/agent-qa"><img src="https://img.shields.io/npm/v/agent-qa?color=196872" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/agent-qa"><img src="https://img.shields.io/npm/dm/agent-qa?color=196872" alt="npm downloads per month"></a>
+  <a href="https://github.com/vostride/agent-qa/stargazers"><img src="https://img.shields.io/github/stars/vostride/agent-qa?color=196872" alt="GitHub stars"></a>
+  <a href="https://github.com/vostride/agent-qa/actions/workflows/ci.yml"><img src="https://github.com/vostride/agent-qa/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://vostride.com/docs/agent-qa"><img src="https://img.shields.io/badge/docs-agent--qa-196872" alt="Documentation"></a>
+  <a href="https://github.com/vostride/agent-qa/blob/main/LICENSE.md"><img src="https://img.shields.io/badge/license-FSL--1.1--ALv2-196872" alt="License: FSL-1.1-ALv2"></a>
+</p>
+
+<p align="center">
+  <a href="https://vostride.com/agent-qa">Website</a> · <a href="https://vostride.com/docs/agent-qa">Docs</a> · <a href="https://vostride.com/demo/agent-qa">Demo</a> · <a href="https://vostride.com/blog">Blog</a> · <a href="https://vostride.com/changelog">Changelog</a>
+</p>
+
+**Your AI QA engineer, with memory.** Describe a user journey in plain language. agent-qa tests it on web, Android or iOS and keeps the evidence. Use the CLI, the dashboard, or your coding agent through MCP and skills.
+
+- **memidex:** remembers facts and working procedures as reviewable files in your repository.
+- **Self-improvement:** validates lessons from runs, retires stale knowledge, and uses your feedback to correct mistakes.
+
+| Benchmark | Rank | Published result |
+| --- | --- | --- |
+| [AndroidWorld](https://vostride.com/benchmark/android-world) | **#1** | **100% pass@1** (116/116 tasks) |
+| [AppControlBench](https://vostride.com/benchmark/app-control-bench) | **#1** | **99.6% completion** (114.5/115 points) |
+
+Read the full benchmark reports, with run evidence and methodology, on [our blog](https://vostride.com/blog). Both used gpt-6-sol with memory and self-improvement off; AppControlBench gives half credit for partial completion.
+
+## See it in action
+
+**Inspect a failure.** The demo catches a cart showing $29 instead of $53, with the failed step and its screenshot side by side.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/evidence-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/evidence-light.png">
+  <img src="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/evidence-light.png" alt="The dashboard shows the deliberate cart-total bug, its failed assertion, and recorded browser evidence" width="100%">
+</picture>
+
+**See what memory contributed.** Inspect the knowledge supplied to a run and trace it back to the steps that used it.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/knowledge-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/knowledge-light.png">
+  <img src="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/knowledge-light.png" alt="The Knowledge tab shows stored facts retrieved for the demo run" width="100%">
+</picture>
+
+**Run from your terminal.** Real output from the demo suite: checkout passes; the deliberate cart-total bug fails.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/cli-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/cli-light.png">
+  <img src="https://raw.githubusercontent.com/vostride/agent-qa/main/docs/assets/readme/cli-light.png" alt="CLI output excerpt showing one passed test, one failed test, and eight of nine steps passing" width="100%">
+</picture>
+
+## Get started
+
+Requires Node.js 24+.
+
+```sh
+npm install -D agent-qa
+npx agent-qa init
+```
+
+Follow the [quickstart](https://vostride.com/docs/agent-qa/quickstart) to connect a model and run the demo, or [set up with your coding agent](https://vostride.com/docs/agent-qa/agent-quickstart).
+
+> [!NOTE]
+> Early stage. Expect bugs. [Report an issue](https://github.com/vostride/agent-qa/issues) when something breaks.
+
+## License
+
+[Functional Source License (FSL-1.1-ALv2)](https://github.com/vostride/agent-qa/blob/main/LICENSE.md).

package/dist/index.cjs

@@ -42,10 +42,10 @@ function positiveInteger(value) {
   const parsed = Number(value.trim());
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : void 0;
 }
-function resolveIOSSnapshotDepth(farmCapabilities) {
-  return positiveInteger(farmCapabilities?.[IOS_SNAPSHOT_DEPTH_CAPABILITY]) ?? positiveInteger(process.env[IOS_SNAPSHOT_DEPTH_ENV]) ?? IOS_SNAPSHOT_MAX_DEPTH;
+function resolveIOSSnapshotDepth() {
+  return positiveInteger(process.env[IOS_SNAPSHOT_DEPTH_ENV]) ?? IOS_SNAPSHOT_MAX_DEPTH;
 }
-async function createIOSSession(config, farmSession) {
+async function createIOSSession(config) {
   const match = config.device?.match ?? {};
   const appiumUrl = process.env.AGENT_QA_APPIUM_URL ?? config.appiumUrl ?? "http://localhost:4723";
   const url = new URL(appiumUrl);
@@ -71,17 +71,6 @@ async function createIOSSession(config, farmSession) {
       delete capabilities[key];
     }
   }
-  if (farmSession) {
-    Object.assign(capabilities, farmSession.capabilities);
-    return (0, import_webdriverio.remote)({
-      protocol: "https",
-      hostname: farmSession.hostname,
-      port: farmSession.port,
-      path: farmSession.path,
-      logLevel: config.verbose ? "info" : "silent",
-      capabilities
-    });
-  }
   return (0, import_webdriverio.remote)({
     hostname: url.hostname,
     port: parseInt(url.port || "4723", 10),
@@ -130,15 +119,6 @@ function firstErrorLine(err) {
   return (err instanceof Error ? err.message : String(err)).split("\n")[0];
 }
 var IOS_TAP_HOLD_MS = 100;
-async function safePerform(chain) {
-  try {
-    await chain.perform();
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("actions") && msg.includes("DELETE")) return;
-    throw err;
-  }
-}
 var IOS_SYSLOG_REGEX = /^.*?\s+(\S+)\[(\d+)\].*?:\s+(.*)/;
 var IOS_APPIUM_LOG_REGEX = /^\S+\s+\S+\s+\[(\w+)\]\s+\[(\S+)\]\s+(.*)/;
 var IOS_LEVEL_MAP = {
@@ -284,8 +264,7 @@ var IOSPlatformAdapter = class {
   consoleDrainIndex = 0;
   captureConsole = true;
   bundleId = null;
-  // EXEC-03 session-cached app registry (D-10/D-12): enumerated once per session. null = not yet
-  // enumerated OR enumeration unavailable (iOS simulator — mobile: listApps throws). Reset in cleanup().
+  // `null` means not yet enumerated, or unavailable because simulators throw on `listApps`.
   appRegistry = null;
   sessionSnapshotDepth = IOS_SNAPSHOT_MAX_DEPTH;
   snapshotDepth = IOS_SNAPSHOT_MAX_DEPTH;
@@ -295,11 +274,11 @@ var IOSPlatformAdapter = class {
     this.config = config;
     this.captureConsole = config.logCapture?.console !== false;
     this.bundleId = this.config.bundleId ?? config.device?.match?.bundleId ?? null;
-    this.sessionSnapshotDepth = resolveIOSSnapshotDepth(config.farmSession?.capabilities);
+    this.sessionSnapshotDepth = resolveIOSSnapshotDepth();
     this.snapshotDepth = this.sessionSnapshotDepth;
     this.readsAtLoweredDepth = 0;
     this.snapshotDepthWarned = false;
-    this.driver = await createIOSSession(this.config, config.farmSession);
+    this.driver = await createIOSSession(this.config);
     const bundleId = this.bundleId;
     if (bundleId) {
       try {
@@ -342,18 +321,12 @@ var IOSPlatformAdapter = class {
     this.readsAtLoweredDepth = 0;
     this.snapshotDepthWarned = false;
   }
-  /**
-   * 428 D-11: the labelled 1s snapshot preview, over `captureScreenshot()` — `takeScreenshot()`
-   * and nothing else. Never `screenshot()`: that one switches the Appium context, and a tick
-   * landing between a step's context switch and its command would run the command in the wrong
-   * context. Declared before the driver exists (a capture then answers `undefined`), so the
-   * composition's selection never falls through to `screenshot()`.
-   */
+  // `takeScreenshot()` only: `screenshot()` switches the Appium context mid-step.
   get liveStream() {
     this.liveStreamCapability ??= (0, import_agent_qa_runner.createSnapshotLiveStream)({ capture: () => this.captureScreenshot() });
     return this.liveStreamCapability;
   }
-  async observe(_options) {
+  async observe() {
     if (!this.driver) {
       throw new Error("IOSPlatformAdapter not initialized \u2014 call setup() first");
     }
@@ -517,9 +490,6 @@ var IOSPlatformAdapter = class {
       return void 0;
     }
   }
-  // ---------------------------------------------------------------------------
-  // Compound behaviors (EXEC-01/02/03)
-  // ---------------------------------------------------------------------------
   async readIOSPageSource() {
     const driver = this.driver;
     if (this.snapshotDepth < this.sessionSnapshotDepth && this.readsAtLoweredDepth >= IOS_SNAPSHOT_PROBE_INTERVAL) {
@@ -547,8 +517,9 @@ var IOSPlatformAdapter = class {
         if (!this.snapshotDepthWarned) {
           this.snapshotDepthWarned = true;
           const detail = (readErr instanceof Error ? readErr.message : String(readErr)).split("\n")[0].slice(0, 160);
-          console.warn(
-            `[ios-adapter] page source failed at snapshotMaxDepth ${failedDepth}; later reads stay at ${IOS_SNAPSHOT_FALLBACK_DEPTH} and retry ${this.sessionSnapshotDepth} every ${IOS_SNAPSHOT_PROBE_INTERVAL} reads (${detail})`
+          (0, import_agent_qa_core.printRunText)(
+            `[ios-adapter] page source failed at snapshotMaxDepth ${failedDepth}; later reads stay at ${IOS_SNAPSHOT_FALLBACK_DEPTH} and retry ${this.sessionSnapshotDepth} every ${IOS_SNAPSHOT_PROBE_INTERVAL} reads (${detail})`,
+            (text) => console.warn(text)
           );
         }
       }
@@ -560,9 +531,7 @@ var IOSPlatformAdapter = class {
     return xml;
   }
   async tapAt(point) {
-    await safePerform(
-      this.driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(point.x), y: Math.round(point.y) }).down({ button: 0 }).pause(IOS_TAP_HOLD_MS).up({ button: 0 })
-    );
+    await this.driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(point.x), y: Math.round(point.y) }).down({ button: 0 }).pause(IOS_TAP_HOLD_MS).up({ button: 0 }).perform();
   }
   async readRect(elementId) {
     try {
@@ -694,27 +663,7 @@ var IOSPlatformAdapter = class {
       return void 0;
     }
   }
-  /**
-   * EXEC-01 iOS fill compound (D-05..D-08). From the SAME focused-element handle: (append) capture
-   * the prior value FIRST via getAttribute('value') then addValue, or (replace) setValue; RE-READ
-   * via getAttribute('value') on that same handle; verdict via compareFillReread. Secure fields
-   * (nativeType XCUIElementTypeSecureTextField) take the non-empty-only lane — the comparator yields
-   * length sentinels so no raw value enters the result (T-359-02); bullet masking is tolerated
-   * (A3/Pitfall 7 — never a length compare). On a passing re-read AND submit, a return/newline is
-   * delivered AFTER the re-read (D-07). Single typing attempt; a mismatch is success:false + §7.1.
-   *
-   * Append (437 FA-1, owner 2026-10-08): the XCUITest `value` attribute often lags after addValue,
-   * so a re-read equal to the prior cannot show the appended text. That fill is recorded unverified:
-   * never exact, and never a mismatch. Every fill records the shared verdict as `fillVerdict`.
-   * An empty field reads as its placeholder, so an append prior equal to it counts as empty.
-   *
-   * Return in a multi-line field adds a new line instead of submitting, so a multi-line submit is
-   * never sent and is recorded as such.
-   *
-   * An unreadable re-read is unverified and does not stop a requested Return, as on Android (D-09,
-   * D-10; owner 2026-10-09), but focus is confirmed once first and a Return is held as focus-lost
-   * when the field no longer has it (444.1 D-10).
-   */
+  // XCUITest `value` lags after `addValue`, so an append read back as the prior is unverified.
   async fillIOSCompound(el, action, box, secure, multiline, target) {
     const driver = this.driver;
     const isAppend = action.clearMode === "append";
@@ -752,13 +701,7 @@ var IOSPlatformAdapter = class {
     };
     return verdict.ok ? { success: true, ...box, ...notice, metadata } : { success: false, error: verdict.selfCorrectingError, ...box, ...notice, metadata };
   }
-  /**
-   * EXEC-02 platform primitives injected into the shared runner scroll loops (D-02/D-03). The swipe
-   * is a page-sized directional gesture (inverted to the finger direction) that reports unknown
-   * movement; nativeSearchScroll drives
-   * the XCUITest `mobile: scroll` predicateString rung over an injection-escaped target; readInterimTree
-   * is a light page-source parse — NO refMap mint, NO screenshot, lastRefs untouched.
-   */
+  // iOS swipes report unknown movement; `readInterimTree` mints no refs and takes no screenshot.
   async buildIOSScrollPrimitives(scrollDirection, maxSwipes, factor = 1) {
     const driver = this.driver;
     const viewport = await driver.getWindowSize();
@@ -774,9 +717,7 @@ var IOSPlatformAdapter = class {
           sy = Math.round(center.y);
         }
         const pts = (0, import_agent_qa_core.computeSwipe)(sx, sy, fingerDirectionFor(direction), distance);
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: 300 }).up({ button: 0 })
-        );
+        await driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: 300 }).up({ button: 0 }).perform();
         return "unknown";
       },
       nativeSearchScroll: async (target) => {
@@ -795,14 +736,7 @@ var IOSPlatformAdapter = class {
       }
     };
   }
-  /**
-   * EXEC-03 openApp (D-10/D-12, Pitfall 5). Resolve a human name to a bundle id (or validate an
-   * explicit bundleId) over the session-cached registry, then launch via activateApp. On real devices
-   * `mobile: listApps` enumerates the registry; on simulators it throws, leaving the registry
-   * unavailable — the appName lane then mints a structured §7.1 error directing to an explicit
-   * bundleId, and the bundleId lane validates without the registry (isAppInstalled / activateApp
-   * error conversion, A2). Never a best-guess launch (T-359-04); an invalid bundle never succeeds.
-   */
+  // Simulators throw on `listApps`, so `appName` needs a real device; `bundleId` works without it.
   async openApp(action) {
     const driver = this.driver;
     const registry = await this.ensureAppRegistry();
@@ -841,12 +775,7 @@ var IOSPlatformAdapter = class {
       }
     }
   }
-  /**
-   * Explicit `{bundleId}` launch (D-12, A2). With a registry, validate membership; without one
-   * (simulator) validate via `driver.isAppInstalled` when the driver exposes it, otherwise attempt
-   * `activateApp` and convert a driver rejection into the structured §7.1 error. An invalid bundle
-   * NEVER returns success:true.
-   */
+  // Without a registry, validate via `isAppInstalled` or convert an `activateApp` rejection.
   async openByBundleId(bundleId, registry) {
     const driver = this.driver;
     if (registry !== null) {
@@ -893,12 +822,7 @@ var IOSPlatformAdapter = class {
     if (enumerated !== null) this.appRegistry = enumerated;
     return enumerated;
   }
-  /**
-   * Enumerate installed apps through the driver only (ownership contract — webdriverio only, no
-   * child_process/simctl). `mobile: listApps` maps bundle ids → AppRegistryEntry with CFBundleName
-   * labels when present (D-10 — no per-app round-trips). It throws on simulators (Pitfall 5) ⇒ null,
-   * leaving enumeration unavailable WITHOUT crashing.
-   */
+  // Driver only, no simctl; `listApps` throws on simulators, which leaves enumeration unavailable.
   async enumerateApps() {
     const driver = this.driver;
     try {
@@ -1075,9 +999,7 @@ var IOSPlatformAdapter = class {
         (0, import_agent_qa_core.warnIfOutOfBounds)({ x: pts.startX, y: pts.startY }, { width, height }, "swipe");
         (0, import_agent_qa_core.warnIfOutOfBounds)({ x: pts.endX, y: pts.endY }, { width, height }, "swipe");
         const swipeDuration = action.durationMs;
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: swipeDuration }).up({ button: 0 })
-        );
+        await driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: swipeDuration }).up({ button: 0 }).perform();
         return {
           success: true,
           startCoordinates: { x: pts.startX, y: pts.startY },
@@ -1128,9 +1050,7 @@ var IOSPlatformAdapter = class {
       }
       case "longpress": {
         const { center } = resolver.resolve(action.ref);
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).pause(action.duration ?? 1e3).up({ button: 0 })
-        );
+        await driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).pause(action.duration ?? 1e3).up({ button: 0 }).perform();
         return { success: true };
       }
       case "waitFor": {
@@ -1318,25 +1238,19 @@ var IOSPlatformAdapter = class {
               success: false,
               error: 'assertValue {source:"network"} (HTTP log inspection) is not available on the iOS adapter. Use a web target for network assertions, or assert on visible UI text.'
             };
-          case "expr-result":
-            return { success: true, data: void 0 };
         }
       }
       case "drag": {
         const from = resolver.resolve(action.fromRef);
         const to = resolver.resolve(action.toRef);
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(from.center.x), y: Math.round(from.center.y) }).down({ button: 0 }).pause(300).move({ x: Math.round(to.center.x), y: Math.round(to.center.y), duration: 500 }).up({ button: 0 })
-        );
+        await driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(from.center.x), y: Math.round(from.center.y) }).down({ button: 0 }).pause(300).move({ x: Math.round(to.center.x), y: Math.round(to.center.y), duration: 500 }).up({ button: 0 }).perform();
         return { success: true };
       }
       case "doubleTap": {
         const { center, bounds } = resolver.resolve(action.ref);
         const x = Math.round(center.x);
         const y = Math.round(center.y);
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x, y }).down({ button: 0 }).up({ button: 0 }).pause(50).down({ button: 0 }).up({ button: 0 })
-        );
+        await driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x, y }).down({ button: 0 }).up({ button: 0 }).pause(50).down({ button: 0 }).up({ button: 0 }).perform();
         return { success: true, coordinates: center, boundingBox: bounds };
       }
       case "openApp":
@@ -1429,16 +1343,10 @@ var IOSPlatformAdapter = class {
             end = { x: midX, y: Math.round(height * 0.4) };
             break;
         }
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: start.x, y: start.y }).down({ button: 0 }).move({ x: end.x, y: end.y, duration: 300 }).up({ button: 0 })
-        );
+        await driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: start.x, y: start.y }).down({ button: 0 }).move({ x: end.x, y: end.y, duration: 300 }).up({ button: 0 }).perform();
         return { success: true, startCoordinates: start, endCoordinates: end };
       }
-      // Runner-minted / author-channel verbs (D-01/D-15): reportValue, assertAI, extractAI, and
-      // setVariable are intercepted at the runner dispatch seam and never reach the adapter. A
-      // grouped §7.1 defensive case surfaces a dispatch-routing error if one arrives here;
-      // assertNever remains the backstop for a genuinely unknown schema verb. (uniqueValue is
-      // web-only and is not part of ActionsFor<'ios'>.)
+      // Runner-channel verbs never reach the adapter; one arriving here is a routing error.
       case "reportValue":
       case "assertAI":
       case "extractAI":