@deeeed/metamask-harness 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.0 - 2026-07-07
+
+### Added
+- **`status` auto-probes live app state per device** — the `yarn a:status` successor. Static info prints instantly; within a strict 2s window each device line is enriched with `screen=` (active route via the `__AGENTIC__` bridge, Route objects normalised), `wallet=locked|unlocked|onboarding`, `account=<label> (0x1234…abcd)` and `fixture=READY|missing`. `--fast` skips all probes (guaranteed-instant for scripts); `--json` carries the enriched `devices[]` in one envelope. All RN targets attached to the checkout's Metro are probed and matched per device (exact id → exact name → platform-uniqueness → leftover 1:1), so android + ios side by side on one Metro both report. Honest degradation: `no-bridge` (nothing matched/answering) vs `bridge-absent` (target attached but the installed build predates `__AGENTIC__`, rendered with a rebuild hint) — surfacing pre-bridge builds required the target discovery probe to become three-state (agentic/responsive/unreachable) instead of silently dropping them.
+- **Every action now carries self-discovery metadata.** `action_metadata` (description + example recipe node, derived from the real handler implementations) covers all official and custom actions across the mobile, extension and core manifests — previously `app.status`, `cdp.target` and all 16 `metamask.wallet.*`/`metamask.perps.*` actions were bare names to agents. A new contract guard enforces coverage (including example structure: `node.action` must match), and locks mobile ↔ extension action-set parity with an explicit platform-only allowlist.
+
 ## 0.8.0 - 2026-07-07
 
 ### Added

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -173,10 +173,11 @@ const COMMANDS = {
 
   async status(client, _args, { deviceName, platform } = {}) {
     const expr = `(function() {
+      var agenticPresent = typeof globalThis.__AGENTIC__ !== 'undefined';
       var route = globalThis.__AGENTIC__?.getRoute() || null;
       var account = null;
       try { account = globalThis.__AGENTIC__?.getSelectedAccount() || null; } catch(e) {}
-      return { route: route, account: account };
+      return { route: route, account: account, agenticPresent: agenticPresent };
     })()`;
     const snapshot = await cdpEval(client, expr);
     return { ...snapshot, deviceName: deviceName || '', platform: platform || '' };
@@ -658,7 +659,9 @@ Environment:
         const result = await handler(client, args.slice(1), { deviceName: target.deviceName, platform });
         results.push(result);
       } catch {
-        // Target not responsive — skip
+        // Recovery is correct: status probes every target advisory; an
+        // unresponsive one degrades to absent-from-the-listing rather than
+        // failing the whole multi-target command.
       } finally {
         if (client) client.close();
       }

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -48,6 +48,18 @@ async function fetchJSON(url) {
  * Returns true if __AGENTIC__ is installed, false otherwise.
  */
 async function probeTarget(wsUrl) {
+  return (await probeTargetDetailed(wsUrl)) === 'agentic';
+}
+
+/**
+ * Three-state probe so callers can tell a pre-__AGENTIC__ build apart from a
+ * dead target:
+ *   'agentic'     — JS runtime answered and __AGENTIC__ is installed.
+ *   'responsive'  — the target evaluated JS but has no __AGENTIC__ (an app build
+ *                   that predates the bridge, or a non-runtime page).
+ *   'unreachable' — connect/eval failed.
+ */
+async function probeTargetDetailed(wsUrl) {
   try {
     const client = await createWSClient(wsUrl, 3000);
     try {
@@ -56,13 +68,13 @@ async function probeTarget(wsUrl) {
         returnByValue: true,
         awaitPromise: false,
       });
-      return result?.result?.value === 'object';
+      return result?.result?.value === 'object' ? 'agentic' : 'responsive';
     } finally {
       client.close();
     }
   } catch {
-    // Connection failed — target is not the right one
-    return false;
+    // Connection failed — target is not usable at all
+    return 'unreachable';
   }
 }
 
@@ -186,18 +198,32 @@ async function discoverAllTargets(port) {
     return bPage - aPage;
   });
 
-  // Group by deviceName, probe each to find the JS runtime target
-  const seen = new Set();
-  const results = [];
+  // Group by deviceName, probe each to find the JS runtime target. Prefer the
+  // device's __AGENTIC__-bearing target; when a device has none, keep its first
+  // RESPONSIVE candidate (candidates are sorted JS-runtime-first) so a build
+  // that predates the bridge still surfaces — the status consumer reports it as
+  // bridge-absent instead of the device silently vanishing from discovery.
+  // Known ambiguity: when a device's JS runtime is attached-but-busy while its
+  // native C++ Hermes page answers, that page is also 'responsive' (no
+  // __AGENTIC__ in the native context), so the device reports bridge-absent even
+  // though the app build may carry the bridge. Low probability, and the degraded
+  // report is informative rather than harmful.
+  const agenticByDevice = new Map();
+  const responsiveByDevice = new Map();
   for (const candidate of candidates) {
     const device = candidate.deviceName || candidate.id || candidate.webSocketDebuggerUrl;
-    if (seen.has(device)) continue;
-    const hasAgentic = await probeTarget(candidate.webSocketDebuggerUrl);
-    if (hasAgentic) {
-      seen.add(device);
-      results.push({ wsUrl: candidate.webSocketDebuggerUrl, deviceName: device });
+    if (agenticByDevice.has(device)) continue;
+    const state = await probeTargetDetailed(candidate.webSocketDebuggerUrl);
+    if (state === 'agentic') {
+      agenticByDevice.set(device, { wsUrl: candidate.webSocketDebuggerUrl, deviceName: device });
+    } else if (state === 'responsive' && !responsiveByDevice.has(device)) {
+      responsiveByDevice.set(device, { wsUrl: candidate.webSocketDebuggerUrl, deviceName: device });
     }
   }
+  const results = [...agenticByDevice.values()];
+  for (const [device, entry] of responsiveByDevice) {
+    if (!agenticByDevice.has(device)) results.push(entry);
+  }
   return results;
 }
 

package/dist/cli-commands.js

@@ -7,7 +7,7 @@ const SPEC = {
     { name: "help", aliases: ["-h", "--help"], desc: "Show usage" }
   ],
   shared: [
-    { name: "status", aliases: ["health", "home"], desc: "Home status + next commands", flags: ["--json"] },
+    { name: "status", aliases: ["health", "home"], desc: "Home status + next commands", flags: ["--json", "--fast"] },
     { name: "ports", desc: "Slot ports and runtime paths", flags: ["--json"] },
     { name: "up", desc: "Decide + run minimum work to reach ready", flags: ["--json", "--dry-run"] },
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", flags: ["--json"] },

package/dist/commands/parse-args.js

@@ -29,6 +29,7 @@ function parseArgs(argv, command) {
     "force",
     "resolveOnly",
     "expectLive",
+    "fast",
     "help"
   ]);
   for (let i = 0; i < argv.length; i += 1) {

package/dist/commands/status-probe.js

@@ -0,0 +1,167 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fixtureSummary } from "../doctor.js";
+import { runnerDir } from "../paths.js";
+const PROBE_TIMEOUT_MS = 2e3;
+function bridgeScriptPath() {
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT ?? path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+}
+function truncateAddress(address) {
+  if (!address || address.length <= 10) return address;
+  return `${address.slice(0, 6)}\u2026${address.slice(-4)}`;
+}
+function routeToString(route) {
+  if (typeof route === "string") return route;
+  if (route && typeof route === "object" && "name" in route) {
+    const n = route.name;
+    if (typeof n === "string") return n;
+  }
+  return void 0;
+}
+function deriveWalletState(account, route) {
+  const routeStr = (routeToString(route) ?? "").toLowerCase();
+  if (routeStr.includes("onboard")) return "onboarding";
+  if (account !== null && account !== void 0 && typeof account === "object") return "unlocked";
+  return "locked";
+}
+function parseBridgeEntries(raw) {
+  if (!raw || typeof raw !== "object") return [];
+  const items = Array.isArray(raw) ? raw : [raw];
+  return items.filter((e) => Boolean(e && typeof e === "object" && !Array.isArray(e))).map((e) => ({
+    route: e.route,
+    account: e.account,
+    deviceName: typeof e.deviceName === "string" ? e.deviceName : "",
+    platform: typeof e.platform === "string" ? e.platform : "",
+    // agenticPresent is only set when the bridge explicitly sends it (false = absent).
+    // Omitted by older bridge versions → leave undefined so caller treats as present.
+    ...typeof e.agenticPresent === "boolean" ? { agenticPresent: e.agenticPresent } : {}
+  }));
+}
+function matchBridgeEntry(device, entries) {
+  const byId = entries.find((e) => e.deviceName === device.id);
+  if (byId) return byId;
+  if (device.name) {
+    const byName = entries.find((e) => e.deviceName === device.name);
+    if (byName) return byName;
+  }
+  const platformEntries = entries.filter((e) => e.platform === device.platform);
+  if (platformEntries.length === 1) return platformEntries[0];
+  return null;
+}
+function probeMobileBridge(target) {
+  const script = bridgeScriptPath();
+  if (!fs.existsSync(script)) {
+    return Promise.resolve({ ok: false, liveState: "no-bridge" });
+  }
+  return new Promise((resolve) => {
+    const env = {
+      ...process.env,
+      APP_ROOT: target,
+      CDP_TIMEOUT: String(PROBE_TIMEOUT_MS)
+    };
+    let settled = false;
+    let stdout = "";
+    const child = spawn(process.execPath, [script, "status"], {
+      cwd: target,
+      env,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      const killTimer = setTimeout(() => child.kill("SIGKILL"), 500);
+      child.once("close", () => clearTimeout(killTimer));
+      resolve({ ok: false, liveState: "no-bridge" });
+    }, PROBE_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolve({ ok: false, liveState: "no-bridge" });
+        return;
+      }
+      try {
+        const raw = JSON.parse(stdout);
+        const entries = parseBridgeEntries(raw);
+        if (entries.length === 0) {
+          resolve({ ok: false, liveState: "no-bridge" });
+          return;
+        }
+        resolve({ ok: true, entries });
+      } catch {
+        resolve({ ok: false, liveState: "no-bridge" });
+      }
+    });
+    child.on("error", () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, liveState: "no-bridge" });
+    });
+  });
+}
+function resolveFixtureStatus(target) {
+  const summary = fixtureSummary(target);
+  return summary.status === "ready" ? "READY" : "missing";
+}
+async function probeMobileLiveState(target, devices) {
+  const result = /* @__PURE__ */ new Map();
+  if (devices.length === 0) return result;
+  const fixtureStatus = resolveFixtureStatus(target);
+  const probeResult = await probeMobileBridge(target);
+  if (!probeResult.ok) {
+    for (const device of devices) result.set(device.id, { fixtureStatus, liveState: "no-bridge" });
+    return result;
+  }
+  const { entries } = probeResult;
+  const matched = /* @__PURE__ */ new Map();
+  const usedEntries = /* @__PURE__ */ new Set();
+  for (const device of devices) {
+    const entry = matchBridgeEntry(device, entries.filter((e) => !usedEntries.has(e)));
+    if (entry) {
+      matched.set(device.id, entry);
+      usedEntries.add(entry);
+    }
+  }
+  const leftoverEntries = entries.filter(
+    (e) => !usedEntries.has(e) && e.platform === "" && e.agenticPresent === false
+  );
+  const unmatchedDevices = devices.filter((d) => !matched.has(d.id));
+  if (leftoverEntries.length === 1 && unmatchedDevices.length === 1) {
+    matched.set(unmatchedDevices[0].id, leftoverEntries[0]);
+  }
+  for (const device of devices) {
+    const entry = matched.get(device.id);
+    if (!entry) {
+      result.set(device.id, { fixtureStatus, liveState: "no-bridge" });
+      continue;
+    }
+    if (entry.agenticPresent === false) {
+      result.set(device.id, { fixtureStatus, liveState: "bridge-absent" });
+      continue;
+    }
+    const account = entry.account;
+    const walletState = deriveWalletState(account, entry.route);
+    const currentScreen = routeToString(entry.route);
+    const addrRaw = typeof account?.address === "string" ? account.address : void 0;
+    const labelRaw = typeof account?.name === "string" ? account.name : void 0;
+    const liveEntry = {
+      fixtureStatus,
+      walletState,
+      ...currentScreen !== void 0 ? { currentScreen } : {},
+      ...labelRaw !== void 0 && addrRaw !== void 0 ? { selectedAccount: { label: labelRaw, address: truncateAddress(addrRaw) } } : {}
+    };
+    result.set(device.id, liveEntry);
+  }
+  return result;
+}
+export {
+  probeMobileLiveState,
+  resolveFixtureStatus
+};

package/dist/commands/status.js

@@ -4,11 +4,13 @@ import { assertAdapter } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { listConnectedDevices } from "../devices.js";
 import { deviceSelected, renderDeviceList } from "./device-target.js";
+import { probeMobileLiveState } from "./status-probe.js";
 import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import { optionFlag, targetPath } from "./parse-args.js";
 async function handleStatus({ options }) {
   const target = targetPath(options);
   const json = optionFlag(options, "json");
+  const fast = optionFlag(options, "fast");
   const adapter = detectAdapter(target);
   if (!adapter) {
     return usageOut(json, "status", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
@@ -17,15 +19,70 @@ async function handleStatus({ options }) {
   const devices = adapter === "mobile" ? listConnectedDevices().map((device) => ({ ...device, selected: deviceSelected(device) })) : [];
   const next = getAdapterSurface(adapter).hints.relaunch;
   if (json) {
-    console.log(JSON.stringify({ schemaVersion: 1, command: "status", adapter, target, devices, next }, null, 2));
+    const doProbe = !fast && adapter === "mobile" && devices.length > 0;
+    if (doProbe) {
+      const liveMap = await probeMobileLiveState(target, devices);
+      const devicesWithLive = devices.map((d) => mergeDeviceLive(d, liveMap.get(d.id)));
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, command: "status", adapter, target, devices: devicesWithLive, next },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(
+        JSON.stringify({ schemaVersion: 1, command: "status", adapter, target, devices, next }, null, 2)
+      );
+    }
     return EXIT.ok;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });
   console.log(`${out("label", "status")} ${out("bold", adapter)} ${out("dim", target)}`);
   if (adapter === "mobile") renderDeviceList(devices, out);
   console.log(`${out("label", "Next:")} ${out("cmd", next)}`);
+  if (!fast && adapter === "mobile" && devices.length > 0) {
+    const liveMap = await probeMobileLiveState(target, devices);
+    renderLiveBlock(devices, liveMap, out);
+  }
   return EXIT.ok;
 }
+function mergeDeviceLive(device, live) {
+  if (!live) return device;
+  return {
+    ...device,
+    fixtureStatus: live.fixtureStatus,
+    ...live.liveState !== void 0 ? { liveState: live.liveState } : {},
+    ...live.currentScreen !== void 0 ? { currentScreen: live.currentScreen } : {},
+    ...live.walletState !== void 0 ? { walletState: live.walletState } : {},
+    ...live.selectedAccount !== void 0 ? { selectedAccount: live.selectedAccount } : {}
+  };
+}
+function renderLiveBlock(devices, liveMap, out) {
+  console.log(`${out("label", "live:")}`);
+  for (const device of devices) {
+    const live = liveMap.get(device.id);
+    const prefix = `  ${device.platform} ${out("dim", device.id)}${device.name ? ` (${device.name})` : ""}`;
+    if (!live || live.liveState === "no-bridge") {
+      console.log(`${prefix}: ${out("dim", "(no-bridge)")}`);
+      continue;
+    }
+    if (live.liveState === "bridge-absent") {
+      console.log(`${prefix}: ${out("warn", "(bridge-absent \u2014 app attached, build lacks __AGENTIC__; rebuild/reinstall a dev build)")}`);
+      continue;
+    }
+    const parts = [];
+    if (live.currentScreen !== void 0) parts.push(`screen=${out("cmd", live.currentScreen)}`);
+    if (live.walletState !== void 0) parts.push(`wallet=${out(live.walletState === "unlocked" ? "ok" : "warn", live.walletState)}`);
+    if (live.selectedAccount !== void 0) {
+      parts.push(`account=${live.selectedAccount.label} ${out("dim", `(${live.selectedAccount.address})`)}`);
+    }
+    if (live.fixtureStatus !== void 0) {
+      parts.push(`fixture=${out(live.fixtureStatus === "READY" ? "ok" : "warn", live.fixtureStatus)}`);
+    }
+    console.log(`${prefix}: ${parts.join("  ")}`);
+  }
+}
 export {
   handleStatus
 };

package/dist/mm-harness-cli.js

@@ -18,18 +18,31 @@ const REAL = [
     helpText: `mm-harness status [flags]
 
   Home dashboard for the current checkout \u2014 the detected adapter, the next command
-  to run, and (mobile only) the connected devices with which one is the selected
-  target (matches ADB_SERIAL / IOS_SIMULATOR). Aliases: health, home.
+  to run, and (mobile only) the connected devices with live app state. Aliases: health, home.
 
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable envelope { adapter, target, devices[], next }
+  --fast                             Skip all live-state probes (instant output, safe for scripts)
 
-  The devices[] section carries { platform, id, name, state, selected } per device;
-  extension/core checkouts report an empty list (no device surface).
+  Human output: static device list prints immediately; live-state lines append
+  after the ~2s probe window (screen, wallet, account, fixture per device).
+
+  The devices[] section carries per device:
+    { platform, id, name, state, selected }   always present
+    { currentScreen, walletState, selectedAccount, fixtureStatus }  when bridge reachable
+    { liveState: 'no-bridge' }   when bridge unreachable or --fast
+
+  All RN targets attached to the checkout's Metro are probed and matched to their
+  devices; a device whose target cannot be confidently matched (Metro's device
+  description matches neither the serial nor the model name) degrades to
+  liveState:'no-bridge'. An attached target whose build predates __AGENTIC__
+  reports liveState:'bridge-absent'.
+  Extension/core live-state probing is V1-pending (use doctor for runtime status).
 
 Example:
   mm-harness status
-  mm-harness status --json`
+  mm-harness status --json
+  mm-harness status --fast`
   },
   {
     name: "actions",

package/docs/CLI-SPEC.md

@@ -450,7 +450,7 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ## `status` (aliases `health`, `home`) — home dashboard + devices[] (REAL)
 
-`status` is the compact home dashboard for a checkout: the detected adapter, the next command to run (`next`), and — for **mobile** checkouts — a `devices[]` section. Extension/core checkouts report an empty `devices[]` (CDP tab detail is out of scope). Additive envelope:
+`status` is the compact home dashboard for a checkout: the detected adapter, the next command to run (`next`), and — for **mobile** checkouts — a `devices[]` section with live app state. Extension/core checkouts report an empty `devices[]`. Additive envelope:
 
 ```json
 {
@@ -459,14 +459,49 @@ Readiness check for a checkout without launching the app. Doctor is the single p
   "adapter": "mobile",
   "target": "/path/to/checkout",
   "devices": [
-    { "platform": "android", "id": "emulator-5554", "name": "Pixel_6", "state": "device", "selected": true },
-    { "platform": "ios", "id": "AAAA-BBBB", "name": "iPhone 15", "state": "Booted", "selected": false }
+    {
+      "platform": "android", "id": "emulator-5554", "name": "Pixel_6",
+      "state": "device", "selected": true,
+      "currentScreen": "Wallet", "walletState": "unlocked",
+      "selectedAccount": { "label": "Account 1", "address": "0xabcd…ef12" },
+      "fixtureStatus": "READY"
+    },
+    {
+      "platform": "ios", "id": "AAAA-BBBB", "name": "iPhone 15",
+      "state": "Booted", "selected": false,
+      "fixtureStatus": "READY", "liveState": "no-bridge"
+    }
   ],
   "next": "mm-harness launch ios"
 }
 ```
 
-`selected` is `true` when the device id matches the current `ADB_SERIAL`/`ANDROID_SERIAL` (android) or `IOS_SIMULATOR` (ios) env. `doctor --json` carries the same `devices[]` shape (with `selected`) for mobile checkouts.
+**Per-device live fields** (additive — absent or null when unreachable):
+
+| Field | Type | Description |
+|---|---|---|
+| `currentScreen` | string | Active route/screen in the running app (mobile bridge `status` route field) |
+| `walletState` | `'locked'\|'unlocked'\|'onboarding'` | Derived from bridge status: account present → unlocked; onboarding route → onboarding; else locked |
+| `selectedAccount` | `{ label, address }` | Active account name + address truncated to `0x1234…abcd` form |
+| `fixtureStatus` | `'READY'\|'missing'` | Checkout-level: whether `wallet-fixture.json` is present and well-formed |
+| `liveState` | `'no-bridge'\|'bridge-absent'` | Set when the bridge is unreachable/times out (`no-bridge`) or the target answers but `__AGENTIC__` is absent (`bridge-absent`); live fields omitted in both cases |
+
+**`--fast` flag:** skips all live-state probes. Output is instant (same envelope shape, live fields absent). Safe for scripts and CI where probe latency is unacceptable.
+
+**Human output** is progressive: static info (adapter, device list, next) prints immediately; a `live:` block appends after the ~2s probe window closes. `--fast` suppresses the live block entirely.
+
+`selected` is `true` when the device id matches `ADB_SERIAL`/`ANDROID_SERIAL` (android) or `IOS_SIMULATOR` (ios) env. `doctor --json` carries the same `devices[]` shape (with `selected`) for mobile checkouts.
+
+The mobile bridge probes all connected RN targets in one call and returns an array; each device is matched to its entry by name or platform-uniqueness, so multi-device checkouts (e.g. Android + iOS simulator) receive per-device live state.
+
+`liveState` in the JSON envelope (absent = fully enriched):
+
+| Value | Meaning |
+|---|---|
+| `'no-bridge'` | No matching/responding target on Metro — bridge genuinely unreachable or app not running. |
+| `'bridge-absent'` | Target IS reachable and answered Runtime.evaluate, but `typeof globalThis.__AGENTIC__ === 'undefined'` — the installed build predates the bridge. Reinstall a dev build to get live state. |
+
+Extension/core live-state probing (CDP home-tab route) is V1-pending — use `doctor` for runtime status.
 
 **Exit:** 0 (2 when the repo type cannot be detected).