@deeeed/metamask-harness 0.29.3 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.31.0 - 2026-08-02
+
+### Added
+
+- Add one cross-platform `metamask.deeplink.open` capability that exercises real Chrome or device URL ingress for external deeplink proofs.
+
+## 0.30.0 - 2026-08-02
+
+### Changed
+
+- Upgrade the Farmslot protocol, recipe runtime, and agent runtime to their continuous-gesture-compatible releases and converge published installs on protocol 0.16.0.
+
 ## 0.29.3 - 2026-08-01
 
 ### Fixed

package/dist/recipe-security.js

@@ -20,6 +20,7 @@ const APP_MUTATION_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
   "metamask.wallet.ensure_unlocked",
   "metamask.wallet.select_account",
+  "metamask.deeplink.open",
   "metamask.perps.close_positions",
   "metamask.perps.close_orders",
   "metamask.perps.place_order",

package/library/actions/extension/deeplink/open.mjs

@@ -0,0 +1,26 @@
+import { pathToFileURL } from 'node:url';
+
+import {
+  externalDeeplinkTimeout,
+  externalDeeplinkUrl,
+} from '../../shared/deeplink/url.mjs';
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+export async function openExtensionDeeplink(input) {
+  return withExtensionPage(input, (page) => navigateExtensionDeeplink(page, input));
+}
+
+export async function navigateExtensionDeeplink(page, input) {
+  const url = externalDeeplinkUrl(input.node);
+  const timeoutMs = externalDeeplinkTimeout(input.node);
+  return {
+    action: input.action,
+    url,
+    navigation: await page.navigate(url, timeoutMs),
+    proofPath: 'external-deeplink',
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runAdapter(openExtensionDeeplink);
+}

package/library/actions/mobile/deeplink/open.mjs

@@ -0,0 +1,16 @@
+import {
+  externalDeeplinkTimeout,
+  externalDeeplinkUrl,
+} from '../../shared/deeplink/url.mjs';
+import { openExternalDeeplink, runAdapter } from '../platform/bridge.mjs';
+
+runAdapter(async (input) => {
+  const url = externalDeeplinkUrl(input.node);
+  const timeoutMs = externalDeeplinkTimeout(input.node);
+  return {
+    action: input.action,
+    url,
+    ...(await openExternalDeeplink(input, url, timeoutMs)),
+    proofPath: 'external-deeplink',
+  };
+});

package/library/actions/mobile/platform/bridge.mjs

@@ -160,6 +160,86 @@ function resolveMobileTarget(input) {
   return { watcherPort, iosSimulator, androidDevice, androidTargetDeviceName, adbSerial };
 }
 
+export async function openExternalDeeplink(input, url, timeout = 15000) {
+  const target = resolveMobileTarget(input);
+  const requestedPlatform = String(
+    input.context?.env?.PLATFORM ?? process.env.PLATFORM ?? '',
+  ).toLowerCase();
+  const serial = String(
+    input.context?.env?.ADB_SERIAL ??
+      input.context?.env?.ANDROID_SERIAL ??
+      process.env.ADB_SERIAL ??
+      process.env.ANDROID_SERIAL ??
+      '',
+  ).trim();
+  const android =
+    requestedPlatform === 'android' || (requestedPlatform !== 'ios' && Boolean(serial));
+  if (android) {
+    if (!serial) {
+      throw new Error(
+        'Android deeplink ingress requires an adb serial.\n' +
+          '  Next: mm-harness devices --adapter mobile --json',
+      );
+    }
+    const adb = resolveMobileToolPath('adb', { required: true });
+    const { stdout } = await runDeeplinkCommand(
+      adb,
+      [
+        '-s',
+        serial,
+        'shell',
+        'am',
+        'start',
+        '-W',
+        '-a',
+        'android.intent.action.VIEW',
+        '-d',
+        quoteRemoteShellArgument(url),
+      ],
+      timeout,
+      `Android device ${serial}`,
+    );
+    if (!/^Status:\s*ok\s*$/imu.test(stdout)) {
+      throw new Error(
+        `Android device ${serial} did not report a successful deeplink launch.\n` +
+          '  Next: mm-harness doctor --adapter mobile --json',
+      );
+    }
+    return { platform: 'android', selectedDevice: serial, method: 'adb-am-start-view' };
+  }
+
+  const simulator = String(target.iosSimulator ?? '').trim();
+  if (!simulator) {
+    throw new Error(
+      'iOS deeplink ingress requires an iOS simulator.\n' +
+        '  Next: mm-harness devices --adapter mobile --json',
+    );
+  }
+  await runDeeplinkCommand(
+    'xcrun',
+    ['simctl', 'openurl', simulator, url],
+    timeout,
+    `iOS simulator ${simulator}`,
+  );
+  return { platform: 'ios', selectedDevice: simulator, method: 'simctl-openurl' };
+}
+
+function quoteRemoteShellArgument(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+async function runDeeplinkCommand(command, args, timeout, target) {
+  try {
+    return await execFileAsync(command, args, { timeout, encoding: 'utf8' });
+  } catch (error) {
+    const detail = String(error?.stderr ?? error?.message ?? error).trim();
+    throw new Error(
+      `Could not open the deeplink on ${target}${detail ? `: ${detail}` : '.'}\n` +
+        '  Next: mm-harness doctor --adapter mobile --json',
+    );
+  }
+}
+
 function androidDeviceNameMatches(deviceName, targetName) {
   if (!targetName) return false;
   return deviceName === targetName || deviceName.startsWith(`${targetName} -`);

package/library/actions/shared/deeplink/url.mjs

@@ -0,0 +1,37 @@
+export function externalDeeplinkUrl(node) {
+  const raw = node?.url;
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new Error(
+      'metamask.deeplink.open requires url.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home',
+    );
+  }
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(
+      'metamask.deeplink.open requires an absolute HTTPS url.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home',
+    );
+  }
+  if (url.protocol !== 'https:') {
+    throw new Error(
+      'metamask.deeplink.open accepts only HTTPS urls.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home',
+    );
+  }
+  return url.toString();
+}
+
+export function externalDeeplinkTimeout(node) {
+  const timeout = Number(node?.timeout_ms ?? 15000);
+  if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 120000) {
+    throw new Error(
+      'metamask.deeplink.open timeout_ms must be between 1 and 120000.\n' +
+        '  Next: mm-harness call metamask.deeplink.open url=https://link.metamask.io/home timeout_ms=15000',
+    );
+  }
+  return timeout;
+}

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

@@ -2779,6 +2779,37 @@
         "external-mutation"
       ]
     },
+    "metamask.deeplink.open": {
+      "description": "Open an HTTPS deeplink through real browser ingress so the Extension owns parsing, verification, and destination navigation.",
+      "execution_capabilities": [
+        "app-mutation"
+      ],
+      "examples": [
+        {
+          "action": "metamask.deeplink.open",
+          "url": "https://link.metamask.io/home",
+          "intent": "Open the deeplink through external browser navigation",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Absolute HTTPS deeplink URL."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "description": "Maximum time for the external navigation. Default 15000."
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "additionalProperties": false
+      }
+    },
     "metamask.analytics.start_capture": {
       "description": "extension Start capturing MetaMetrics events at the Segment transport and return a cursor to bracket later reads.",
       "execution_capabilities": [
@@ -2945,6 +2976,7 @@
     {
       "ref": "ui.screen",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.key_press",
@@ -2957,6 +2989,7 @@
     {
       "ref": "ui.visible",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.key_press",

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

@@ -2901,6 +2901,37 @@
         "external-mutation"
       ]
     },
+    "metamask.deeplink.open": {
+      "description": "Open an HTTPS deeplink through the selected Android device or iOS simulator so Mobile owns parsing and destination navigation.",
+      "execution_capabilities": [
+        "app-mutation"
+      ],
+      "examples": [
+        {
+          "action": "metamask.deeplink.open",
+          "url": "https://link.metamask.io/home",
+          "intent": "Open the deeplink through external device navigation",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Absolute HTTPS deeplink URL."
+          },
+          "timeout_ms": {
+            "type": "number",
+            "description": "Maximum time for the external navigation. Default 15000."
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "additionalProperties": false
+      }
+    },
     "metamask.analytics.start_capture": {
       "description": "mobile Start capturing MetaMetrics events at the Segment transport and return a cursor to bracket later reads.",
       "execution_capabilities": [
@@ -3067,6 +3098,7 @@
     {
       "ref": "ui.screen",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.screenshot",
@@ -3078,6 +3110,7 @@
     {
       "ref": "ui.visible",
       "default_for": [
+        "metamask.deeplink.open",
         "ui.navigate",
         "ui.press",
         "ui.screenshot",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.29.3",
+  "version": "0.31.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -20,10 +20,10 @@
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "^0.5.0",
+    "@farmslot/agent-runtime": "0.5.1",
     "@farmslot/handoff": "^0.3.1",
-    "@farmslot/protocol": "^0.15.0",
-    "@farmslot/recipe-harness": "^0.11.1",
+    "@farmslot/protocol": "0.16.0",
+    "@farmslot/recipe-harness": "0.12.1",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",
     "esbuild": "0.28.1",