@deeeed/metamask-harness 0.36.0 → 0.37.0

package/library/actions/mobile/wallet/native-ui.mjs

@@ -0,0 +1,493 @@
+import { createAgentDeviceUiTransport } from '@farmslot/expo-recipe';
+import { createAgentDeviceClient } from 'agent-device';
+
+const TEST_IDS = {
+  existingWallet: 'wallet-setup-screen-have-an-existing-wallet-button-id',
+  importSeed: 'onboarding-sheet-import-seed-button-id',
+  srp: 'phrase-input-id',
+  continue: 'import-from-seed-screen-continue-button-id',
+  password: 'create-password-first-input-field',
+  confirmPassword: 'create-password-second-input-field',
+  passwordTerms: 'password-understand-box',
+  createPassword: 'submit-button',
+  metricsCheckbox: 'optin-metrics-metrics-checkbox',
+  metricsContinue: 'optin-metrics-continue-button-id',
+  interestSkip: 'onboarding-interest-skip-button',
+  interestContinue: 'onboarding-interest-continue-button',
+  successDone: 'onboarding-success-done-button',
+  notificationYes: 'push-notification-new-user-sheet-button-yes',
+  notificationNotNow: 'push-notification-new-user-sheet-button-not-now',
+  walletTourSkip: 'wallet-home-onboarding-steps-skip',
+  wallet: 'wallet-screen',
+  walletSafeArea: 'wallet-safe-area',
+  walletHomepage: 'homepage-container',
+  walletScroll: 'wallet-scroll-view',
+  walletAddress: 'wallet-account-copy-button',
+  addressListBack: 'address-list-go-back',
+  walletTab: 'tab-bar-item-Wallet',
+  perpsHome: 'perps-home',
+  perpsHomeBack: 'perps-home-back-button',
+  perpsMarket: 'perps-market-details-view',
+  perpsMarketBack: 'perps-market-header-back-button',
+  hamburger: 'navbar-hamburger-menu-button',
+  lock: 'lock-menu-item',
+  confirmLock: 'android:id/button1',
+  login: 'login',
+  loginPassword: 'login-password-input',
+  loginButton: 'log-in-button',
+  forgotPassword: 'reset-wallet-button',
+  resetWallet: 'forgot-password-modal-reset-wallet-button',
+  confirmReset: 'forgot-password-modal-yes-reset-wallet-button',
+};
+
+const WALLET_SCREEN_IDS = [
+  TEST_IDS.wallet,
+  TEST_IDS.walletSafeArea,
+  TEST_IDS.walletHomepage,
+  TEST_IDS.walletScroll,
+];
+
+const POST_PASSWORD_TEST_IDS = [
+  TEST_IDS.metricsContinue,
+  TEST_IDS.interestSkip,
+  TEST_IDS.successDone,
+  TEST_IDS.notificationNotNow,
+  TEST_IDS.walletTourSkip,
+  ...WALLET_SCREEN_IDS,
+];
+
+const BIOMETRIC_PROMPT_ID = 'com.android.systemui:id/biometric_prompt_constraint_layout';
+const PERMISSION_CONTROLLER_PACKAGES = new Set([
+  'com.android.permissioncontroller',
+  'com.google.android.permissioncontroller',
+]);
+
+function isMetaMaskBiometricPrompt(nodes) {
+  const systemUiNodes = nodes.filter((node) => node.bundleId === 'com.android.systemui');
+  return systemUiNodes.some((node) => node.identifier === BIOMETRIC_PROMPT_ID) &&
+    systemUiNodes.some((node) =>
+      /metamask/iu.test(String(node.label ?? node.value ?? ''))
+    );
+}
+
+function isPostPasswordScreen(nodes) {
+  return nodes.some((node) => POST_PASSWORD_TEST_IDS.includes(String(node.identifier ?? '')));
+}
+
+function isMetaMaskNotificationPermissionPrompt(nodes) {
+  const permissionNodes = nodes.filter((node) => PERMISSION_CONTROLLER_PACKAGES.has(node.bundleId));
+  return permissionNodes.some((node) => /metamask/iu.test(String(node.label ?? node.value ?? ''))) &&
+    permissionNodes.some((node) => /notification/iu.test(String(node.label ?? node.value ?? node.identifier ?? '')));
+}
+
+function isWalletScreen(nodes) {
+  return nodes.some((node) => WALLET_SCREEN_IDS.includes(String(node.identifier ?? '')));
+}
+
+function hasBlockingSystemUi(nodes) {
+  return nodes.some((node) =>
+    (node.bundleId === 'com.android.systemui' || PERMISSION_CONTROLLER_PACKAGES.has(node.bundleId)) &&
+    /(?:dialog|prompt|permission)/iu.test(String(node.identifier ?? ''))
+  );
+}
+
+export function isOpaqueMobileRuntime(input) {
+  return input.context?.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === '1' ||
+    process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === '1';
+}
+
+export async function importWalletThroughNativeUi(input, credentials, options) {
+  const native = nativeSession(input);
+  try {
+    const initial = await native.normalizeWalletSurface(options.timeoutMs);
+    if (initial.wallet) {
+      if (options.requireFresh) {
+        throw new Error('metamask.wallet.import method=ui requires a fresh Mobile onboarding state.');
+      }
+      return await native.walletProof(credentials.expectedAddress, true, options.timeoutMs);
+    }
+    if (initial.visible.has(TEST_IDS.login)) {
+      if (options.requireFresh) {
+        throw new Error('metamask.wallet.import method=ui requires a fresh Mobile onboarding state.');
+      }
+      await native.fill(TEST_IDS.loginPassword, credentials.password, options.timeoutMs);
+      await native.press(TEST_IDS.loginButton, options.timeoutMs);
+      await native.waitForWallet(options.timeoutMs);
+      return await native.walletProof(credentials.expectedAddress, true, options.timeoutMs);
+    }
+    const resumedAfterPassword = initial.postPassword;
+    if (!resumedAfterPassword) {
+      await native.press(TEST_IDS.existingWallet, options.timeoutMs);
+      if (!await native.exists(TEST_IDS.srp, 3000)) {
+        await native.press(TEST_IDS.importSeed, options.timeoutMs);
+      }
+      await fillRecoveryPhrase(native, credentials.mnemonic, options.timeoutMs);
+      await native.press(TEST_IDS.continue, options.timeoutMs);
+      await native.fill(TEST_IDS.password, credentials.password, options.timeoutMs);
+      await native.fill(TEST_IDS.confirmPassword, credentials.password, options.timeoutMs);
+      await native.dismissKeyboard();
+      await native.press(TEST_IDS.passwordTerms, options.timeoutMs);
+      await native.press(TEST_IDS.createPassword, options.timeoutMs);
+    }
+    const onboarding = await native.completeOnboarding(options);
+    return {
+      ...await native.walletProof(credentials.expectedAddress, false, options.timeoutMs),
+      ...onboarding,
+    };
+  } finally {
+    await native.close();
+  }
+}
+
+async function fillRecoveryPhrase(native, mnemonic, timeoutMs) {
+  const words = mnemonic.trim().split(/\s+/u);
+  await native.fill(TEST_IDS.srp, words[0], timeoutMs);
+  for (const [index, word] of words.slice(1).entries()) {
+    await native.type(' ');
+    await native.wait(`${TEST_IDS.srp}_${index + 1}`, timeoutMs);
+    await native.type(word);
+  }
+  await native.verifyRecoveryPhrase(words);
+  await native.dismissKeyboard();
+}
+
+export async function readWalletThroughNativeUi(input) {
+  const native = nativeSession(input);
+  try {
+    const timeoutMs = Number(input.node?.timeout_ms ?? 30_000);
+    await native.normalizeWalletSurface(timeoutMs);
+    await native.waitForWallet(timeoutMs);
+    return await native.walletProof(undefined, true, timeoutMs);
+  } finally {
+    await native.close();
+  }
+}
+
+export async function resetWalletThroughNativeUi(input) {
+  const native = nativeSession(input);
+  const timeoutMs = Number(input.node?.timeout_ms ?? 60_000);
+  try {
+    if (await native.exists(TEST_IDS.existingWallet, 1000)) {
+      return { alreadyFresh: true, provider: 'android-native-accessibility' };
+    }
+    if (await native.exists(TEST_IDS.confirmLock, 1000)) {
+      await native.press(TEST_IDS.confirmLock, timeoutMs);
+    } else {
+      const state = await native.normalizeWalletSurface(timeoutMs);
+      if (state.wallet) {
+        await native.press(TEST_IDS.hamburger, timeoutMs);
+        await native.press(TEST_IDS.lock, timeoutMs);
+        if (await native.exists(TEST_IDS.confirmLock, 3000)) {
+          await native.press(TEST_IDS.confirmLock, timeoutMs);
+        }
+      }
+    }
+    await native.wait(TEST_IDS.login, timeoutMs);
+    await native.press(TEST_IDS.forgotPassword, timeoutMs);
+    await native.press(TEST_IDS.resetWallet, timeoutMs);
+    await native.press(TEST_IDS.confirmReset, timeoutMs);
+    await native.wait(TEST_IDS.existingWallet, timeoutMs);
+    return { alreadyFresh: false, provider: 'android-native-accessibility' };
+  } finally {
+    await native.close();
+  }
+}
+
+function nativeSession(input) {
+  const env = { ...process.env, ...(input.context?.env ?? {}) };
+  const device = String(env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? '').trim();
+  if (!device) throw new Error('Opaque Mobile UI execution requires one explicit Android device serial.');
+  const app = String(env.ANDROID_PACKAGE_ID ?? 'io.metamask');
+  const session = `mm-harness-wallet-${process.pid}-${String(input.context?.nodeId ?? 'node')}`
+    .replace(/[^A-Za-z0-9._-]/gu, '-');
+  const client = createAgentDeviceClient({
+    session,
+    lockPolicy: 'reject',
+    lockPlatform: 'android',
+  });
+  const selection = { platform: 'android', target: 'mobile', serial: device, session };
+  const transport = createAgentDeviceUiTransport({
+    platform: 'android',
+    device,
+    app,
+    session,
+    client,
+  });
+  const context = {
+    nodeId: String(input.context?.nodeId ?? 'wallet'),
+    projectRoot: input.context.projectRoot,
+    artifactsDir: input.context.artifactsDir,
+    env,
+  };
+  const execute = (action, node) => transport.execute(action, node, context);
+  return {
+    press: (testId, timeoutMs) => execute('ui.press', { test_id: testId, timeout_ms: timeoutMs }),
+    fill: (testId, value, timeoutMs) => execute('ui.set_input', {
+      test_id: testId,
+      value,
+      timeout_ms: timeoutMs,
+      settle: false,
+    }),
+    type: (value) => client.interactions.type({
+      ...selection,
+      text: value,
+      delayMs: 50,
+      responseLevel: 'digest',
+    }),
+    async verifyRecoveryPhrase(words) {
+      const snapshot = await client.capture.snapshot({
+        ...selection,
+        interactiveOnly: false,
+        forceFull: true,
+      });
+      const actual = new Map(snapshot.nodes
+        .filter((node) => /^phrase-input-id_\d+$/u.test(String(node.identifier ?? '')))
+        .map((node) => [
+          Number(String(node.identifier).split('_').at(-1)),
+          String(node.value ?? node.label ?? ''),
+        ]));
+      const mismatches = words.flatMap((word, index) =>
+        actual.get(index) === word ? [] : [index + 1]
+      );
+      if (actual.size !== words.length || mismatches.length > 0) {
+        throw new Error(
+          `Mobile recovery phrase entry did not match ${words.length} expected fields; mismatched field numbers: ${mismatches.join(', ') || 'unknown'}.`,
+        );
+      }
+    },
+    dismissKeyboard: () => client.command.keyboard({
+      ...selection,
+      action: 'dismiss',
+      responseLevel: 'digest',
+    }),
+    async isPostPasswordScreen() {
+      return (await this.screenState()).postPassword;
+    },
+    async screenState() {
+      const snapshot = await client.capture.snapshot({
+        ...selection,
+        interactiveOnly: false,
+        forceFull: true,
+      });
+      return {
+        nodes: snapshot.nodes,
+        visible: new Set(snapshot.nodes.map((node) => String(node.identifier ?? ''))),
+        wallet: isWalletScreen(snapshot.nodes),
+        postPassword: isPostPasswordScreen(snapshot.nodes) || isMetaMaskBiometricPrompt(snapshot.nodes),
+      };
+    },
+    async normalizeWalletSurface(timeoutMs) {
+      const deadline = Date.now() + timeoutMs;
+      for (let attempt = 0; attempt < 5 && Date.now() <= deadline; attempt += 1) {
+        const state = await this.screenState();
+        if (
+          state.wallet ||
+          state.postPassword ||
+          state.visible.has(TEST_IDS.existingWallet) ||
+          state.visible.has(TEST_IDS.login)
+        ) {
+          return state;
+        }
+        if (state.visible.has(TEST_IDS.perpsMarketBack)) {
+          await this.press(TEST_IDS.perpsMarketBack, timeoutMs);
+        } else if (state.visible.has(TEST_IDS.perpsHomeBack)) {
+          await this.press(TEST_IDS.perpsHomeBack, timeoutMs);
+        } else if (state.visible.has(TEST_IDS.walletTab)) {
+          await this.press(TEST_IDS.walletTab, timeoutMs);
+        } else if (state.visible.has(TEST_IDS.addressListBack)) {
+          await this.press(TEST_IDS.addressListBack, timeoutMs);
+        } else {
+          await client.command.back({
+            ...selection,
+            mode: 'system',
+            responseLevel: 'digest',
+          });
+        }
+      }
+      throw new Error('Mobile wallet action could not reach wallet home, login, or onboarding.');
+    },
+    async completeOnboarding(options) {
+      const deadline = Date.now() + options.timeoutMs;
+      let biometricPromptDismissed = false;
+      let notificationPromptHandled = false;
+      let notificationsEnabled = false;
+      let walletTourSkipped = false;
+      let interestsHandled = false;
+      let awaitingNotificationPermission = false;
+      while (Date.now() <= deadline) {
+        const snapshot = await client.capture.snapshot({
+          ...selection,
+          interactiveOnly: false,
+          forceFull: true,
+        });
+        if (isMetaMaskBiometricPrompt(snapshot.nodes)) {
+          if (options.biometricsEnabled) {
+            throw new Error('Mobile biometrics=true requires manual device authentication and is not supported by an unattended recipe.');
+          }
+          await client.command.back({
+            ...selection,
+            mode: 'system',
+            responseLevel: 'digest',
+          });
+          biometricPromptDismissed = true;
+          continue;
+        }
+        if (isMetaMaskNotificationPermissionPrompt(snapshot.nodes) && awaitingNotificationPermission) {
+          await client.command.alert({
+            ...selection,
+            action: 'accept',
+            timeoutMs: 5000,
+            responseLevel: 'digest',
+          });
+          awaitingNotificationPermission = false;
+          notificationsEnabled = true;
+          continue;
+        }
+        if (hasBlockingSystemUi(snapshot.nodes)) {
+          throw new Error('Unexpected Android system UI blocked Mobile wallet creation; refusing to dismiss it as biometric authentication.');
+        }
+        const visible = new Set(snapshot.nodes.map((node) => String(node.identifier ?? '')));
+        if (visible.has(TEST_IDS.metricsContinue)) {
+          if (!options.metametricsEnabled) {
+            await this.press(TEST_IDS.metricsCheckbox, options.timeoutMs);
+          }
+          await this.press(TEST_IDS.metricsContinue, options.timeoutMs);
+          continue;
+        }
+        if (visible.has(TEST_IDS.interestSkip)) {
+          interestsHandled = true;
+          if (options.interests.length > 0) {
+            for (const interest of options.interests) {
+              await this.press(`onboarding-interest-option-${interest}`, options.timeoutMs);
+            }
+            await this.press(TEST_IDS.interestContinue, options.timeoutMs);
+          } else {
+            await this.press(TEST_IDS.interestSkip, options.timeoutMs);
+          }
+          continue;
+        }
+        if (visible.has(TEST_IDS.successDone)) {
+          if (options.interests.length > 0 && !interestsHandled) {
+            throw new Error('Mobile onboarding interests were requested, but the questionnaire is not enabled for this build.');
+          }
+          await this.press(TEST_IDS.successDone, options.timeoutMs);
+          continue;
+        }
+        if (visible.has(TEST_IDS.notificationNotNow)) {
+          await this.press(
+            options.notificationsEnabled ? TEST_IDS.notificationYes : TEST_IDS.notificationNotNow,
+            options.timeoutMs,
+          );
+          notificationPromptHandled = true;
+          awaitingNotificationPermission = options.notificationsEnabled;
+          continue;
+        }
+        if (visible.has(TEST_IDS.walletTourSkip)) {
+          if (options.skipWalletTour) {
+            await this.press(TEST_IDS.walletTourSkip, options.timeoutMs);
+            walletTourSkipped = true;
+            continue;
+          }
+          throw new Error('Mobile wallet-home tour remains visible because skip_wallet_tour=false; wallet readiness cannot be proven.');
+        }
+        if (WALLET_SCREEN_IDS.some((testId) => visible.has(testId))) {
+          if (options.interests.length > 0 && !interestsHandled) {
+            throw new Error('Mobile onboarding interests were requested, but the questionnaire is not enabled for this build.');
+          }
+          return {
+            biometricsEnabled: options.biometricsEnabled,
+            biometricPromptDismissed,
+            notificationsEnabled,
+            notificationPromptHandled,
+            walletTourSkipped,
+          };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      throw new Error('Mobile onboarding did not reach a usable wallet before the import timeout.');
+    },
+    wait: (testId, timeoutMs) => execute('ui.wait_for', {
+      test_id: testId,
+      expected: 'visible',
+      timeout_ms: timeoutMs,
+      settle: false,
+    }),
+    async waitForWallet(timeoutMs) {
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() <= deadline) {
+        if ((await this.screenState()).wallet) return;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      throw new Error('Mobile wallet home did not become visible before the readiness timeout.');
+    },
+    async exists(testId, timeoutMs) {
+      try {
+        await execute('ui.wait_for', {
+          test_id: testId,
+          expected: 'visible',
+          timeout_ms: timeoutMs,
+          settle: false,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async walletProof(expectedAddress, alreadyReady, timeoutMs) {
+      const observed = await transport.observe?.(['ui.screen', 'ui.visible']);
+      let rawText = JSON.stringify(observed ?? '').toLowerCase();
+      const text = rawText.replace(/[^a-z0-9]/gu, '');
+      const address = expectedAddress?.toLowerCase().replace(/[^a-z0-9]/gu, '');
+      let addressVisible = address
+        ? text.includes(address) || (text.includes(address.slice(0, 7)) && text.includes(address.slice(-5)))
+        : /0x[a-f0-9]{5,40}(?:…|\.\.\.)?[a-f0-9]{0,8}/u.test(rawText);
+      const deadline = Date.now() + Math.min(timeoutMs, 30_000);
+      while (!addressVisible && Date.now() <= deadline) {
+        let openedAddressList = false;
+        try {
+          await this.press(TEST_IDS.walletAddress, 15_000);
+          openedAddressList = true;
+          const addressState = await this.screenState();
+          rawText = JSON.stringify(addressState.nodes.map((node) => [node.label, node.value])).toLowerCase();
+          const normalized = rawText.replace(/[^a-z0-9]/gu, '');
+          addressVisible = address
+            ? normalized.includes(address) ||
+              (normalized.includes(address.slice(0, 7)) && normalized.includes(address.slice(-5)))
+            : /0x[a-f0-9]{5,40}(?:…|\.\.\.)?[a-f0-9]{0,8}/u.test(rawText);
+        } finally {
+          if (openedAddressList) {
+            if (await this.exists(TEST_IDS.addressListBack, 2000)) {
+              await this.press(TEST_IDS.addressListBack, 15_000);
+            } else {
+              await client.command.back({
+                ...selection,
+                mode: 'system',
+                responseLevel: 'digest',
+              });
+            }
+          }
+        }
+        if (!addressVisible) await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      const observedAddress = rawText.match(/0x[a-f0-9]{5,40}(?:…|\.\.\.)?[a-f0-9]{0,8}/u)?.[0] ?? null;
+      return {
+        alreadyReady,
+        selectedAddress: addressVisible && expectedAddress ? expectedAddress : null,
+        selectedAddressObserved: observedAddress,
+        ...(expectedAddress ? { selectedAddressExpected: expectedAddress } : {}),
+        addressVisible,
+        walletVisible: true,
+        provider: 'android-native-accessibility',
+        redacted: true,
+        proofPath: 'mobile-visible-onboarding-import-native',
+      };
+    },
+    async close() {
+      try {
+        await client.sessions.close({ session, shutdown: false });
+      } catch (error) {
+        if (!/No active session|SESSION_NOT_FOUND/iu.test(String(error?.message ?? error))) throw error;
+      }
+    },
+  };
+}

package/library/actions/mobile/wallet/read_state.mjs

@@ -1,9 +1,25 @@
 import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
+import { isOpaqueMobileRuntime, readWalletThroughNativeUi } from './native-ui.mjs';
 
 // selectedStatus: shared pin-aware entry selection (see selectBridgeStatusEntry).
 const selectedStatus = selectBridgeStatusEntry;
 
 runAdapter(async (input) => {
+  if (isOpaqueMobileRuntime(input)) {
+    const proof = await readWalletThroughNativeUi(input);
+    if (!proof.addressVisible) {
+      throw new Error('Mobile wallet home is visible, but the selected account address is not observable through native accessibility.');
+    }
+    return {
+      action: input.action,
+      source: proof.provider,
+      account: { address: proof.selectedAddress, displayAddress: proof.selectedAddressObserved },
+      route: { name: 'WalletView', observedBy: 'wallet-screen' },
+      platform: 'android',
+      redacted: true,
+      proofPath: 'native-wallet-status',
+    };
+  }
   const status = selectedStatus(await bridgeCommand(input, ['status']), input);
   const output = {
     action: input.action,

package/library/actions/mobile/wallet/reset.mjs

@@ -1,7 +1,20 @@
 import { runAdapter } from '../platform/bridge.mjs';
 import { resetMobileWalletThroughUi } from './reset-helper.mjs';
+import { isOpaqueMobileRuntime, resetWalletThroughNativeUi } from './native-ui.mjs';
 
-runAdapter(async (input) => ({
-  action: input.action,
-  ...(await resetMobileWalletThroughUi(input)),
-}));
+runAdapter(async (input) => {
+  if (isOpaqueMobileRuntime(input)) {
+    const result = await resetWalletThroughNativeUi(input);
+    return {
+      action: input.action,
+      ...result,
+      route: 'Onboarding',
+      redacted: true,
+      proofPath: 'mobile-visible-wallet-reset-native',
+    };
+  }
+  return {
+    action: input.action,
+    ...(await resetMobileWalletThroughUi(input)),
+  };
+});

package/library/actions/shared/ui/locators.mjs

@@ -30,6 +30,7 @@ export function locatorsFromObservation(observation) {
       const leftBest = left.suggestions[0];
       const rightBest = right.suggestions[0];
       return (
+        locatorPriority(left) - locatorPriority(right) ||
         confidenceRank(leftBest?.confidence) - confidenceRank(rightBest?.confidence) ||
         strategyRank(leftBest?.strategy) - strategyRank(rightBest?.strategy)
       );
@@ -44,6 +45,12 @@ export function locatorsFromObservation(observation) {
   };
 }
 
+function locatorPriority(locator) {
+  const role = text(locator.role)?.toLowerCase() ?? '';
+  if (INTERACTIVE_ROLE_PARTS.some((part) => role.includes(part))) return 0;
+  return locator.description.includes('label=') ? 1 : 2;
+}
+
 export function requireVisibleObservation(result) {
   const value = record(result);
   const observations = record(value.observations);

package/library/manifests/extension.action-manifest.json

@@ -1180,6 +1180,21 @@
             "default": false,
             "description": "Enable MetaMetrics during visible onboarding."
           },
+          "biometrics": {
+            "type": "boolean",
+            "default": false,
+            "description": "Mobile-only biometric onboarding preference; ignored on Extension."
+          },
+          "notifications": {
+            "type": "boolean",
+            "default": false,
+            "description": "Mobile-only push notification onboarding preference; ignored on Extension."
+          },
+          "skip_wallet_tour": {
+            "type": "boolean",
+            "default": true,
+            "description": "Mobile-only wallet-home tour preference; ignored on Extension."
+          },
           "interests": {
             "type": "array",
             "items": {
@@ -1433,6 +1448,107 @@
       ],
       "execution_capabilities": []
     },
+    "metamask.perps.read_snapshot": {
+      "description": "Read a bounded, redacted snapshot of live Extension Perps state through product background APIs.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "include": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "account",
+                "markets",
+                "positions",
+                "orders",
+                "history",
+                "watchlist"
+              ]
+            },
+            "minItems": 1,
+            "default": [
+              "account",
+              "markets",
+              "positions",
+              "orders",
+              "history",
+              "watchlist"
+            ],
+            "description": "Sections to request. Every requested section must be available or the action fails."
+          },
+          "market": {
+            "type": "string",
+            "description": "Optional single market filter."
+          },
+          "markets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 100,
+            "description": "Optional market filters applied to market-scoped sections."
+          },
+          "history": {
+            "type": "object",
+            "properties": {
+              "start_time_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Inclusive history start time in Unix milliseconds. Defaults to 30 days before end_time_ms."
+              },
+              "end_time_ms": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Inclusive history end time in Unix milliseconds. Defaults to the current time."
+              },
+              "account_id": {
+                "type": "string",
+                "description": "Optional CAIP account ID passed to the product history API; the value is not returned."
+              },
+              "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "default": 100,
+                "description": "Maximum history items returned after product filtering."
+              }
+            },
+            "additionalProperties": false
+          },
+          "max_items_per_section": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 100,
+            "description": "Maximum normalized items returned for each requested list section."
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "minimum": 1000,
+            "default": 20000,
+            "description": "Per-request background API timeout."
+          }
+        },
+        "additionalProperties": false
+      },
+      "examples": [
+        {
+          "action": "metamask.perps.read_snapshot",
+          "include": [
+            "account",
+            "markets",
+            "positions",
+            "orders"
+          ],
+          "markets": [
+            "BTC",
+            "ETH"
+          ],
+          "intent": "Read the bounded Perps state needed for release validation",
+          "next": "done"
+        }
+      ],
+      "execution_capabilities": []
+    },
     "metamask.perps.read_positions": {
       "description": "extension Read live Perps positions; without a selector, return all live positions.",
       "schema": {