@deeeed/metamask-harness 0.73.0 → 0.75.0

package/dist/adapters/mobile/ui.js

@@ -0,0 +1,701 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { bridgeCommand, evalAsync, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../../../library/actions/mobile/platform/bridge.mjs";
+import { observeNativeUi } from "../../../library/actions/mobile/platform/observe-ui.mjs";
+import { nativeAgentDeviceStateDir } from "../../../library/actions/mobile/platform/native-session-name.mjs";
+import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
+import { isRecord, traceText } from "../../action-values.js";
+import { runLiveAdapterScript } from "../../live-adapter-contract.js";
+const execFileAsync = promisify(execFile);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function optionalScalarText(value, label) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  throw new Error(`${label} must be a string, number, or boolean.`);
+}
+function scalarText(value, label, fallback) {
+  return optionalScalarText(value, label) ?? fallback;
+}
+function firstScalarText(record, keys, label, fallback) {
+  for (const key of keys) {
+    const value = optionalScalarText(record[key], `${label}.${key}`);
+    if (value !== void 0) return value;
+  }
+  if (fallback !== void 0) return fallback;
+  throw new Error(`${label} requires one of: ${keys.join(", ")}.`);
+}
+function uiInputFor(context, input) {
+  return {
+    action: input.action,
+    node: input.node,
+    context: {
+      nodeId: context.nodeId,
+      projectRoot: context.projectRoot,
+      artifactsDir: context.artifactsDir,
+      env: context.env
+    }
+  };
+}
+function mobileProbeOutput(status, input, projectRoot) {
+  const entries = Array.isArray(status) ? status : [status];
+  const selected = selectBridgeStatusEntry(status, input) ?? null;
+  const route = isRecord(selected) && isRecord(selected.route) ? selected.route : null;
+  return {
+    reachable: isRecord(selected) && selected.agenticPresent === true && Boolean(route),
+    bridge: mobileBridgePath(projectRoot),
+    targetCount: entries.filter((entry) => isRecord(entry)).length,
+    deviceName: isRecord(selected) && typeof selected.deviceName === "string" ? selected.deviceName : null,
+    routeName: route && typeof route.name === "string" ? route.name : null,
+    accountPresent: isRecord(selected) && isRecord(selected.account)
+  };
+}
+function mobileBridgePath(_projectRoot) {
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || "runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs";
+}
+function resolveMobileWaitTarget(payload) {
+  const testId = optionalScalarText(
+    payload.test_id ?? payload.testID,
+    "Mobile ui.wait_for.test_id"
+  );
+  const expectedText = optionalScalarText(payload.text, "ui.wait_for.text");
+  if (!testId && !expectedText) {
+    throw new Error(
+      "Mobile ui.wait_for requires one of: test_id, testID, text."
+    );
+  }
+  const expected = scalarText(
+    payload.expected,
+    "ui.wait_for.expected",
+    "present"
+  ).toLowerCase();
+  const textMatch = scalarText(
+    payload.text_match ?? payload.textMatch,
+    "ui.wait_for.text_match",
+    "contains"
+  ).toLowerCase();
+  if (!["contains", "exact"].includes(textMatch)) {
+    throw new Error("ui.wait_for.text_match must be contains or exact.");
+  }
+  if (!testId && textMatch === "exact") {
+    throw new Error(
+      "Mobile text-only ui.wait_for supports text_match=contains; exact matching also requires test_id/testID."
+    );
+  }
+  return {
+    testId,
+    expectedText,
+    expected,
+    textMatch,
+    visibility: expected === "visible" || expected === "hidden" ? "viewport" : "tree"
+  };
+}
+const RETRYABLE_MOBILE_WAIT_CODES = /* @__PURE__ */ new Set([
+  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
+  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+  MOBILE_BRIDGE_ERROR_CODES.METRO_UNREACHABLE
+]);
+function isRetryableMobileWaitError(error) {
+  return Boolean(
+    isRecord(error) && typeof error.code === "string" && RETRYABLE_MOBILE_WAIT_CODES.has(error.code)
+  );
+}
+async function waitForMobileTarget(input, payload) {
+  const timeoutMs = Number(payload.timeout_ms ?? payload.timeoutMs ?? 1e4);
+  const deadline = Date.now() + timeoutMs;
+  const { testId, expectedText, expected, textMatch, visibility } = resolveMobileWaitTarget(payload);
+  const query = {
+    ...testId ? { testId } : {},
+    ...expectedText && textMatch === "contains" ? { textContains: expectedText } : {},
+    visibility
+  };
+  const queryExpression = `(function(){
+    const api = globalThis.__AGENTIC__;
+    if (!api || typeof api.queryUiTarget !== 'function') {
+      return Promise.resolve(JSON.stringify({ unsupported: true }));
+    }
+    return api.queryUiTarget(${JSON.stringify(query)}).then(function(result){
+      return JSON.stringify(result);
+    });
+  })()`;
+  const textExpression = testId ? `(function(){
+        const api = globalThis.__AGENTIC__;
+        if (!api?.getTextByTestId) return null;
+        return api.getTextByTestId(${JSON.stringify(testId)});
+      })()` : null;
+  let lastResult = null;
+  let lastText = null;
+  let lastBridgeError = null;
+  const expectsAbsent = expected === "absent" || expected === "hidden" || expected === "not_present";
+  while (Date.now() <= deadline) {
+    const remainingMs = Math.max(1, deadline - Date.now());
+    const probeTimeoutMs = Math.min(5e3, remainingMs);
+    const probeInput = {
+      ...input,
+      node: {
+        ...input.node,
+        bridge_timeout_ms: probeTimeoutMs,
+        cdp_timeout_ms: probeTimeoutMs
+      }
+    };
+    let result;
+    try {
+      result = await evalAsync(probeInput, queryExpression);
+    } catch (error) {
+      if (!isRetryableMobileWaitError(error)) throw error;
+      lastBridgeError = error;
+      await sleep(250);
+      continue;
+    }
+    if (!isRecord(result) || result.unsupported === true) {
+      throw new Error(
+        "Mobile ui.wait_for requires the current __AGENTIC__.queryUiTarget bridge for text-only or viewport-visible assertions."
+      );
+    }
+    lastResult = result;
+    const present = result.present === true;
+    const visible = result.visible === true;
+    let textMatched = !expectedText || textMatch === "contains";
+    if (expectedText && textMatch === "exact" && textExpression) {
+      try {
+        lastText = await evalSync(probeInput, textExpression);
+      } catch (error) {
+        if (!isRetryableMobileWaitError(error)) throw error;
+        lastBridgeError = error;
+        await sleep(250);
+        continue;
+      }
+      textMatched = traceText(lastText) === expectedText;
+    }
+    const matched = expected === "visible" ? visible && textMatched : expected === "hidden" ? !visible : expectsAbsent ? !present : present && textMatched;
+    if (matched) {
+      return {
+        matched: true,
+        ...testId ? { testId } : {},
+        ...expectedText ? { text: expectedText, textMatch } : {},
+        expected,
+        present,
+        visible,
+        visibility,
+        ...isRecord(result.rect) ? { rect: result.rect } : {}
+      };
+    }
+    await sleep(250);
+  }
+  const target = [
+    testId ? `testID ${JSON.stringify(testId)}` : "",
+    expectedText ? `text ${textMatch} ${JSON.stringify(expectedText)}` : ""
+  ].filter(Boolean).join(" with ");
+  const exactReason = textMatch === "exact" ? `; last text=${JSON.stringify(lastText)}` : "";
+  const bridgeReason = lastBridgeError ? `; last bridge error=${traceText(lastBridgeError)}` : "";
+  throw new Error(
+    `Timed out waiting for mobile ${target} to be ${expected}; last result=${JSON.stringify(lastResult)}${exactReason}${bridgeReason}.`
+  );
+}
+const MOBILE_BRIDGE_HANDLERS = {
+  screenshot: handleMobileScreenshot,
+  status: handleMobileStatus,
+  navigate: handleMobileNavigate,
+  press: handleMobilePress,
+  keyPress: handleMobileKeyPress,
+  setInput: handleMobileSetInput,
+  scroll: handleMobileScroll,
+  waitFor: handleMobileWaitFor,
+  hud: handleMobileHud,
+  observeUi: handleMobileObserveUi
+};
+async function sendMobileBridgeCommand(command, context) {
+  const handler = MOBILE_BRIDGE_HANDLERS[command.command];
+  if (!handler) {
+    throw new Error(`React Native bridge command ${command.command} is not implemented by the MetaMask runner transport.`);
+  }
+  return handler(command.payload, context);
+}
+function mobileUiInput(context, command, payload) {
+  return uiInputFor(context, { action: `ui.${command}`, node: payload });
+}
+async function handleMobileScreenshot(payload, context) {
+  const input = mobileUiInput(context, "screenshot", payload);
+  const relPath = scalarText(payload.path, "ui.screenshot.path", `screenshots/${context.nodeId}.png`);
+  const artifact = await simulatorScreenshot(input, relPath);
+  context.registerArtifact(artifact);
+  return { captured: true, path: artifact.path, artifact };
+}
+async function handleMobileStatus(payload, context) {
+  return bridgeCommand(mobileUiInput(context, "status", payload), ["status"]);
+}
+async function handleMobileObserveUi(payload, context) {
+  return observeNativeUi(payload, context);
+}
+async function handleMobileNavigate(payload, context) {
+  const live = await runLiveAdapterScript({
+    platform: "mobile",
+    action: "ui.navigate",
+    node: payload,
+    context
+  });
+  if (!live) throw new Error("ui.navigate requires library/actions/mobile/ui/navigate.mjs.");
+  return isRecord(live.result) ? { ...live.result, liveAdapter: live.script } : live.result;
+}
+async function handleMobilePress(payload, context) {
+  const identifiers = ["test_id", "testID", "selector"].map((field) => optionalScalarText(payload[field], `ui.press.${field}`)).filter((value) => value !== void 0);
+  const text = optionalScalarText(payload.text, "ui.press.text");
+  if (identifiers.length + Number(text !== void 0) !== 1) {
+    throw new Error("ui.press requires exactly one of: test_id, testID, selector, text.");
+  }
+  const target = text ?? identifiers[0];
+  if (target.trim() === "") throw new Error("ui.press target must be non-empty.");
+  const longPress = payload.long_press === true;
+  if (longPress && text !== void 0) {
+    throw new Error("ui.press long_press=true requires test_id, testID, or selector targeting.");
+  }
+  const input = mobileUiInput(context, "press", payload);
+  if (text !== void 0) return bridgeCommand(input, ["press-text", target]);
+  return bridgeCommand(input, [longPress ? "long-press-test-id" : "press-test-id", target]);
+}
+async function handleMobileKeyPress(payload, context) {
+  const key = scalarText(payload.key, "ui.key_press.key", "Enter");
+  const input = mobileUiInput(context, "key_press", payload);
+  return bridgeCommand(input, ["key-press", key]);
+}
+async function handleMobileSetInput(payload, context) {
+  const input = mobileUiInput(context, "set_input", payload);
+  const testId = firstScalarText(payload, ["test_id", "testID"], "ui.set_input");
+  const value = scalarText(payload.value ?? payload.text, "ui.set_input.value", "");
+  const result = await bridgeCommand(input, ["set-input", testId, value]);
+  if (isRecord(result) && result.ok === false) {
+    throw new Error(`ui.set_input failed for mobile testID ${testId}: ${traceText(result.error ?? result)}`);
+  }
+  return isRecord(result) ? result : { result, testId, value };
+}
+async function handleMobileScroll(payload, context) {
+  const input = mobileUiInput(context, "scroll", payload);
+  const testId = optionalScalarText(payload.test_id ?? payload.testID, "ui.scroll.test_id");
+  const offset = scalarText(payload.offset ?? payload.delta_y ?? payload.deltaY, "ui.scroll.offset", "600");
+  const intoView = payload.scroll_into_view === true || payload.into_view === true;
+  const measureFromTestId = optionalScalarText(
+    payload.measure_from_test_id ?? payload.measureFromTestId,
+    "ui.scroll.measure_from_test_id"
+  );
+  const measureTargetTestId = optionalScalarText(
+    payload.measure_target_test_id ?? payload.measureTargetTestId,
+    "ui.scroll.measure_target_test_id"
+  );
+  const measureTargetText = optionalScalarText(
+    payload.measure_target_text ?? payload.measureTargetText,
+    "ui.scroll.measure_target_text"
+  );
+  const measureTargetCount = Number(Boolean(measureTargetTestId)) + Number(Boolean(measureTargetText));
+  const measureRequiredPresentTestId = optionalScalarText(
+    payload.measure_required_present_test_id ?? payload.measureRequiredPresentTestId,
+    "ui.scroll.measure_required_present_test_id"
+  );
+  if (Boolean(measureFromTestId) !== (measureTargetCount === 1)) {
+    throw new Error(
+      "ui.scroll visible-transition measurement requires measure_from_test_id and exactly one of measure_target_test_id or measure_target_text."
+    );
+  }
+  if (measureFromTestId && measureTargetCount === 1) {
+    if (intoView) {
+      throw new Error(
+        "ui.scroll visible-transition measurement uses an explicit offset and does not support scroll_into_view."
+      );
+    }
+    return measureMobileScrollTransition(input, {
+      animated: payload.animated === true,
+      fromTestId: measureFromTestId,
+      offset: Number(offset),
+      ...measureTargetTestId ? { targetTestId: measureTargetTestId } : {},
+      ...measureTargetText ? { targetText: measureTargetText } : {},
+      ...measureRequiredPresentTestId ? { requiredPresentTestId: measureRequiredPresentTestId } : {},
+      timeoutMs: Math.max(
+        1,
+        Number(payload.timeout_ms ?? payload.timeoutMs ?? 3e4)
+      ),
+      ...testId ? { scrollTestId: testId } : {}
+    });
+  }
+  if (testId && intoView) {
+    const before = await queryMobileViewportTarget(input, testId);
+    if (before.visible === true) {
+      return {
+        ok: true,
+        testId,
+        intoView: true,
+        alreadyVisible: true,
+        rect: before.rect
+      };
+    }
+  }
+  const args = testId ? [
+    "scroll-view",
+    "--test-id",
+    testId,
+    "--offset",
+    offset,
+    ...intoView ? ["--into-view"] : [],
+    animatedFlag(payload)
+  ] : ["scroll-view", "--offset", offset, animatedFlag(payload)];
+  const timeoutMs = Math.max(0, Number(payload.timeout_ms ?? payload.timeoutMs ?? 5e3));
+  const deadline = Date.now() + timeoutMs;
+  let result;
+  while (true) {
+    try {
+      result = await bridgeCommand(input, args);
+      break;
+    } catch (error) {
+      if (!testId || Date.now() >= deadline) throw error;
+      await sleep(100);
+    }
+  }
+  if (testId && intoView) {
+    const after = await waitForMobileViewportTarget(
+      input,
+      testId,
+      timeoutMs
+    );
+    if (after.visible !== true) {
+      throw new Error(
+        `ui.scroll did not bring mobile testID ${JSON.stringify(testId)} into the viewport; last result=${JSON.stringify(after)}.`
+      );
+    }
+  }
+  return {
+    ...isRecord(result) ? result : { result },
+    intoView
+  };
+}
+async function measureMobileScrollTransition(input, options) {
+  const result = await bridgeCommand(
+    {
+      ...input,
+      node: {
+        ...input.node,
+        bridge_timeout_ms: options.timeoutMs + 5e3,
+        cdp_timeout_ms: options.timeoutMs + 5e3
+      }
+    },
+    ["measure-scroll-transition", JSON.stringify(options)]
+  );
+  if (!isRecord(result) || result.unsupported === true) {
+    throw new Error(
+      "ui.scroll visible-transition measurement requires queryUiTarget and scrollView on the current mobile bridge."
+    );
+  }
+  if (result.ok !== true) {
+    throw new Error(
+      `ui.scroll visible-transition measurement failed: ${traceText(result.error ?? result)}.`
+    );
+  }
+  return {
+    ...result,
+    measureFromTestId: options.fromTestId,
+    ...options.targetTestId ? { measureTargetTestId: options.targetTestId } : {},
+    ...options.targetText ? { measureTargetText: options.targetText } : {},
+    ...options.requiredPresentTestId ? { measureRequiredPresentTestId: options.requiredPresentTestId } : {}
+  };
+}
+async function queryMobileViewportTarget(input, testId) {
+  const expression = `(function(){
+    const api = globalThis.__AGENTIC__;
+    if (!api || typeof api.queryUiTarget !== 'function') {
+      return Promise.resolve(JSON.stringify({ unsupported: true }));
+    }
+    return api.queryUiTarget(${JSON.stringify({ testId, visibility: "viewport" })}).then(function(result){
+      return JSON.stringify(result);
+    });
+  })()`;
+  const result = await evalAsync(input, expression);
+  if (!isRecord(result) || result.unsupported === true) {
+    throw new Error(
+      "Mobile ui.scroll scroll_into_view requires the current __AGENTIC__.queryUiTarget bridge."
+    );
+  }
+  return result;
+}
+async function waitForMobileViewportTarget(input, testId, timeoutMs) {
+  const deadline = Date.now() + Math.max(0, Math.min(timeoutMs, 5e3));
+  let result = await queryMobileViewportTarget(input, testId);
+  while (result.visible !== true && Date.now() < deadline) {
+    await sleep(100);
+    result = await queryMobileViewportTarget(input, testId);
+  }
+  return result;
+}
+async function handleMobileWaitFor(payload, context) {
+  return waitForMobileTarget(mobileUiInput(context, "waitFor", payload), payload);
+}
+async function handleMobileHud(payload, context) {
+  const automaticProgress = typeof payload.action_name === "string" || context.nodeId === "recipe-complete" && isRecord(payload.progress) && payload.progress.complete === true;
+  const captureProgress = payload.action_name === "ui.screenshot" || payload.action_name === "ui.capture_surface";
+  const input = mobileUiInput(
+    context,
+    "hud",
+    automaticProgress ? {
+      ...payload,
+      bridge_timeout_ms: captureProgress ? 1e4 : 2e3,
+      cdp_timeout_ms: captureProgress ? 1e4 : 2e3
+    } : payload
+  );
+  if (payload.clear === true) {
+    try {
+      return await bridgeCommand(input, ["hide-step"]);
+    } catch (error) {
+      return mobileHudSkippedOrThrow(error);
+    }
+  }
+  const hud = mobileHudPayload(payload, context);
+  try {
+    const result = await bridgeCommand(input, [
+      automaticProgress && !captureProgress ? "show-step-json-deferred" : "show-step-json",
+      JSON.stringify(hud.step)
+    ]);
+    return { hud: true, nodeId: hud.nodeId, status: hud.status, result };
+  } catch (error) {
+    return mobileHudSkippedOrThrow(error, { nodeId: hud.nodeId, status: hud.status });
+  }
+}
+async function hideMobileHudOnTeardown(projectRoot, env = {}) {
+  if (env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") return;
+  if (process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false") return;
+  const input = {
+    node: { bridge_timeout_ms: 8e3, cdp_timeout_ms: 5e3 },
+    context: { nodeId: "teardown", projectRoot, artifactsDir: projectRoot, env }
+  };
+  try {
+    await bridgeCommand(input, ["hide-step-deferred"]);
+  } catch {
+  }
+}
+function mobileHudSkippedOrThrow(error, extra = {}) {
+  const reason = traceText(error);
+  const code = isRecord(error) && typeof error.code === "string" ? error.code : void 0;
+  if (isMobileHudLifecycleSkip(reason, code)) {
+    process.stderr.write(`app.hud skipped (bridge target down or transitioning): ${reason}
+`);
+    return {
+      hud: false,
+      skipped: true,
+      warning: "app.hud skipped because the mobile bridge target is down during lifecycle transition.",
+      ...extra,
+      reason
+    };
+  }
+  throw new Error(`app.hud bridge command failed outside a lifecycle/no-target transition: ${reason}`);
+}
+const HUD_LIFECYCLE_SKIP_CODES = /* @__PURE__ */ new Set([
+  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
+  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+  MOBILE_BRIDGE_ERROR_CODES.METRO_UNREACHABLE
+]);
+function isMobileHudLifecycleSkip(reason, code) {
+  if (code && HUD_LIFECYCLE_SKIP_CODES.has(code)) return true;
+  const haystack = reason.toLowerCase();
+  return [
+    "no responding bridge target",
+    "pinned android device",
+    "bridge probe failed",
+    "econnrefused",
+    "timed out",
+    "no react native bridge target",
+    // Metro down mid-run: HUD cannot paint, so skip rather than abort (the real
+    // action fails on its own). Matches the METRO_UNREACHABLE code branch above.
+    "cannot reach metro",
+    // Dev-client foreground/reload kills the Hermes page mid-flight: pending
+    // CDP calls surface as a message timeout or a closed socket.
+    "cdp message timeout",
+    "websocket closed"
+  ].some((needle) => haystack.includes(needle));
+}
+function animatedFlag(payload) {
+  return payload.animated === true ? "--animated" : "--no-animated";
+}
+function mobileHudPayload(payload, context) {
+  const nodeId = scalarText(payload.node_id ?? payload.nodeId, "app.hud.node_id", context.nodeId);
+  const status = scalarText(payload.status, "app.hud.status", "running");
+  const text = optionalScalarText(payload.intent ?? payload.text ?? payload.detail, "app.hud.intent");
+  if (!text || !text.trim()) {
+    throw new Error("app.hud requires intent/text/detail; automatic recipe progress should provide node intent.");
+  }
+  const detail = scalarText(payload.detail, "app.hud.detail", "");
+  const error = scalarText(payload.error, "app.hud.error", "");
+  const progress = mobileHudProgress(payload.progress);
+  const display = isRecord(payload.display) ? payload.display : {};
+  const showDebug = display.showDebug === true;
+  const showDetail = display.showDetail === true;
+  const proofTarget = payload.proofTarget ?? payload.proof_target;
+  const displayId = [mobileHudStatusLabel(status), progress.text].filter(Boolean).join(" ");
+  return {
+    nodeId,
+    status,
+    step: {
+      id: displayId || nodeId,
+      nodeId,
+      status,
+      intent: text,
+      progress: progress.value,
+      detail: showDetail && detail !== text ? detail : void 0,
+      error: error || void 0,
+      debug: showDebug ? {
+        nodeId,
+        proofTarget
+      } : void 0
+    }
+  };
+}
+function mobileHudProgress(progress) {
+  if (!isRecord(progress)) return { text: "" };
+  if (typeof progress.current !== "number" || typeof progress.total !== "number") return { text: "" };
+  return {
+    text: `${progress.current}/${progress.total}`,
+    value: { current: progress.current, total: progress.total }
+  };
+}
+function mobileHudStatusLabel(status) {
+  if (status === "fail") return "fail";
+  if (status === "pass") return "pass";
+  return "run";
+}
+async function probeMobileBridgeTarget(node, context) {
+  const uiInput = { action: "cdp.target", nodeId: context.nodeId, node };
+  const status = await bridgeCommand(uiInputFor(context, uiInput), ["status"]);
+  const probe = mobileProbeOutput(status, uiInput, context.projectRoot);
+  if (!probe.reachable) {
+    throw new Error("cdp.target required a reachable mobile React Native bridge, but bridge status did not expose a selected app route.");
+  }
+  return probe;
+}
+async function executeNativeProviderAction(action, node, context, createTransport) {
+  if (!createTransport) {
+    throw new Error(
+      `${action} requires the MetaMask native UI provider. Next: npm install -g @deeeed/metamask-harness@latest`
+    );
+  }
+  const platform = mobileNativePlatform(context.env);
+  const device = platform === "android" ? context.env.ADB_SERIAL ?? context.env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL : context.env.SIM_UDID ?? context.env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? process.env.IOS_SIMULATOR;
+  if (!device) {
+    throw new Error(
+      `${action} requires one selected ${platform} device. Next: mm-harness status --adapter mobile --all-devices --json`
+    );
+  }
+  if (platform === "android" && action === "ui.swipe" && isCoordinateTarget(node.target)) {
+    return executeAndroidCoordinateSwipe(node, String(device));
+  }
+  const app = platform === "android" ? context.env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask" : context.env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask";
+  const session = (platform === "ios" ? `mm-harness-${process.pid}-${device}` : `mm-harness-${process.pid}-${context.nodeId}`).replace(/[^a-zA-Z0-9._-]/gu, "-");
+  const stateDir = nativeAgentDeviceStateDir(context.env ?? {}, context.projectRoot, String(device));
+  let transport;
+  try {
+    transport = await createTransport({ platform, device, app, session, stateDir });
+  } catch (error) {
+    throw new Error(
+      `${action} could not start the MetaMask native UI provider. Next: npm install -g @deeeed/metamask-harness@latest`,
+      { cause: error }
+    );
+  }
+  let executionError;
+  let output;
+  try {
+    output = await transport.execute(action, node, context);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    executionError = /^Native recipe actions require the optional agent-device provider:/u.test(message) ? new Error(
+      `${action} could not start the MetaMask native UI provider. Next: npm install -g @deeeed/metamask-harness@latest`,
+      { cause: error }
+    ) : error;
+  }
+  let closeError;
+  try {
+    await transport.close?.();
+  } catch (error) {
+    closeError = error;
+  }
+  if (executionError && closeError) {
+    const message = executionError instanceof Error ? executionError.message : String(executionError);
+    throw new AggregateError([executionError, closeError], message);
+  }
+  if (executionError) throw executionError;
+  if (closeError) throw closeError;
+  return output;
+}
+function isCoordinateTarget(value) {
+  return isRecord(value) && typeof value.x === "number" && Number.isFinite(value.x) && typeof value.y === "number" && Number.isFinite(value.y);
+}
+async function executeAndroidCoordinateSwipe(node, device) {
+  const target = node.target;
+  const direction = String(node.direction ?? "").toLowerCase();
+  if (!["up", "down", "left", "right"].includes(direction)) {
+    throw new Error("ui.swipe.direction must be up, down, left, or right.");
+  }
+  const distance = Number(node.distance ?? 300);
+  const durationMs = Number(node.duration_ms ?? 300);
+  if (!Number.isFinite(distance) || distance <= 0) {
+    throw new Error("ui.swipe.distance must be a positive number.");
+  }
+  if (!Number.isFinite(durationMs) || durationMs <= 0) {
+    throw new Error("ui.swipe.duration_ms must be a positive number.");
+  }
+  const start = { x: Math.round(target.x), y: Math.round(target.y) };
+  const end = {
+    x: Math.round(start.x + (direction === "left" ? -distance : direction === "right" ? distance : 0)),
+    y: Math.round(start.y + (direction === "up" ? -distance : direction === "down" ? distance : 0))
+  };
+  const adbPath = resolveMobileToolPath("adb", { required: true });
+  try {
+    await execFileAsync(
+      adbPath,
+      [
+        "-s",
+        device,
+        "shell",
+        "input",
+        "swipe",
+        String(start.x),
+        String(start.y),
+        String(end.x),
+        String(end.y),
+        String(Math.round(durationMs))
+      ],
+      { encoding: "utf8", timeout: Math.round(durationMs) + 1e4 }
+    );
+  } catch (error) {
+    throw new Error(
+      `Android ui.swipe failed on ${device}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const settleMs = node.settle === false ? 0 : 300;
+  if (settleMs > 0) await sleep(settleMs);
+  return {
+    action: "ui.swipe",
+    resolvedStart: start,
+    resolvedEnd: end,
+    backend: "adb-input-swipe",
+    segments: 1,
+    settlement: {
+      method: "bounded-post-gesture",
+      waitedMs: settleMs,
+      lifecycleNeutral: true
+    }
+  };
+}
+function mobileNativePlatform(env) {
+  if (env.PLATFORM === "android" || env.PLATFORM === "ios") return env.PLATFORM;
+  if (env.ADB_SERIAL || env.ANDROID_SERIAL) return "android";
+  if (env.SIM_UDID || env.IOS_SIMULATOR) return "ios";
+  if (process.env.PLATFORM === "android" || process.env.PLATFORM === "ios") return process.env.PLATFORM;
+  return process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
+}
+export {
+  executeNativeProviderAction,
+  hideMobileHudOnTeardown,
+  isMobileHudLifecycleSkip,
+  isRetryableMobileWaitError,
+  probeMobileBridgeTarget,
+  resolveMobileWaitTarget,
+  sendMobileBridgeCommand
+};