@deeeed/metamask-harness 0.41.1 → 0.43.0

package/library/actions/mobile/app/network_capture.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  bridgeCommand,
+  runAdapter,
+} from '../platform/bridge.mjs';
+import { resolveNetworkArtifact } from '../../shared/app/network-artifact.mjs';
+
+export async function captureNetwork(input) {
+  const node = input.node ?? {};
+  const phase = String(node.phase ?? '').toLowerCase();
+  const id = String(node.id ?? '').trim();
+  if (!['start', 'end'].includes(phase) || !id) {
+    throw new Error(
+      'app.network_capture requires phase=start|end and a non-empty id.',
+    );
+  }
+
+  if (phase === 'start') {
+    const result = await bridgeCommand(input, [
+      'network-capture-start',
+      JSON.stringify({
+        id,
+        urlIncludes: node.url_includes ?? [],
+        methods: node.methods ?? [],
+        bodyJsonFields: node.body_json_fields ?? [],
+        maxRequests: node.max_requests,
+        maxDurationMs: node.max_duration_ms,
+      }),
+    ]);
+    return { action: input.action, phase, ...result };
+  }
+
+  const artifactsDir = input.context?.artifactsDir;
+  if (!artifactsDir) {
+    throw new Error('app.network_capture requires artifactsDir.');
+  }
+  const artifactPath = String(
+    node.artifact_path ?? `network/${id}-summary.json`,
+  );
+  const artifactFile = resolveNetworkArtifact(artifactsDir, artifactPath);
+
+  const summary = await bridgeCommand(input, [
+    'network-capture-end',
+    JSON.stringify({ id }),
+  ]);
+  await mkdir(path.dirname(artifactFile), { recursive: true });
+  await writeFile(artifactFile, `${JSON.stringify(summary, null, 2)}\n`);
+
+  return {
+    action: input.action,
+    phase,
+    ...summary,
+    artifacts: [
+      {
+        path: artifactPath,
+        type: 'report',
+        nodeId: String(input.context?.nodeId ?? 'network-capture'),
+      },
+    ],
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runAdapter(captureNetwork);
+}

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

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { constants as fsConstants } from 'node:fs';
+import { constants as fsConstants, existsSync } from 'node:fs';
 import { mkdir, mkdtemp, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -7,6 +7,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import bridgeErrors from '../../../../adapters/mobile/bridge-runtime/lib/bridge-errors.cjs';
+import brokerModule from '../../../../adapters/mobile/bridge-runtime/lib/cdp-broker.cjs';
+import configModule from '../../../../adapters/mobile/bridge-runtime/lib/config.cjs';
 import { resolveMobileToolPath } from './tool-paths.mjs';
 
 const {
@@ -16,6 +18,8 @@ const {
   coded,
   parseErrorMarker,
 } = bridgeErrors;
+const { brokerSocketPath } = brokerModule;
+const { resolvePort } = configModule;
 
 // Re-exported so the TS adapter classifies on the same code constants without a
 // second import path into the cjs bridge-runtime.
@@ -430,7 +434,11 @@ export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
   // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
   const env = await bridgeEnv(input);
-  if (adapterActionActive) {
+  const brokerSocket = brokerSocketPath(
+    path.dirname(resolveBridgeLockPath(input, env)),
+    resolvePort(env, input.context.projectRoot),
+  );
+  if (adapterActionActive && !existsSync(brokerSocket)) {
     env.CDP_BRIDGE_LOCK_OWNER_PID = await acquireActionBridgeLock(input, env);
   }
   const result = await new Promise((resolve, reject) => {

package/library/actions/shared/app/network-artifact.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path';
+
+export function resolveNetworkArtifact(artifactsDir, relativePath) {
+  const root = path.resolve(artifactsDir);
+  const resolved = path.resolve(root, relativePath);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    throw new Error('Network artifact_path escapes artifactsDir.');
+  }
+  return resolved;
+}

package/library/actions/shared/app/network-assert.mjs

@@ -0,0 +1,154 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+
+import { resolveNetworkArtifact } from './network-artifact.mjs';
+
+export async function assertNetwork(input) {
+  const node = input.node ?? {};
+  const id = String(node.id ?? '').trim();
+  const artifactsDir = input.context?.artifactsDir;
+  if (!id || !artifactsDir) {
+    throw new Error('app.network_assert requires id and artifactsDir.');
+  }
+  const artifactPath = String(
+    node.artifact_path ?? `network/${id}-summary.json`,
+  );
+  const artifactFile = resolveNetworkArtifact(artifactsDir, artifactPath);
+  const handle = await open(
+    artifactFile,
+    constants.O_RDONLY | constants.O_NOFOLLOW,
+  );
+  let summary;
+  try {
+    const artifactStat = await handle.stat();
+    if (!artifactStat.isFile() || artifactStat.size > 5 * 1024 * 1024) {
+      throw new Error(
+        'app.network_assert summary is not a bounded regular file.',
+      );
+    }
+    summary = JSON.parse(await handle.readFile('utf8'));
+  } finally {
+    await handle.close();
+  }
+  validateSummary(summary, id);
+
+  const requiredStatus = node.required_status;
+  if (requiredStatus && summary.status !== requiredStatus) {
+    throw new Error(
+      `app.network_assert expected ${requiredStatus}, got ${summary.status}.`,
+    );
+  }
+  const requiredMinRequests = node.required_min_requests;
+  const requiredMaxRequests = node.required_max_requests;
+  const requiredTypes = node.required_types ?? [];
+  const forbiddenTypes = node.forbidden_types ?? [];
+  if (
+    (requiredTypes.length > 0 || forbiddenTypes.length > 0) &&
+    !summary.projectedBodyFields.includes('type')
+  ) {
+    throw new Error(
+      'app.network_assert type assertions require body_json_fields to include type.',
+    );
+  }
+  if (
+    (requiredMaxRequests !== undefined || forbiddenTypes.length > 0) &&
+    requiredStatus !== 'complete'
+  ) {
+    throw new Error(
+      'app.network_assert negative assertions require required_status=complete.',
+    );
+  }
+  for (const [name, value] of [
+    ['required_min_requests', requiredMinRequests],
+    ['required_max_requests', requiredMaxRequests],
+  ]) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
+      throw new Error(`app.network_assert ${name} is invalid.`);
+    }
+  }
+  if (
+    Number.isInteger(requiredMinRequests) &&
+    Number.isInteger(requiredMaxRequests) &&
+    requiredMinRequests > requiredMaxRequests
+  ) {
+    throw new Error('app.network_assert request assertion range is invalid.');
+  }
+  if (
+    Number.isInteger(requiredMinRequests) &&
+    summary.totalRequests < requiredMinRequests
+  ) {
+    throw new Error(
+      `app.network_assert expected at least ${requiredMinRequests} request(s), got ${summary.totalRequests}.`,
+    );
+  }
+  if (
+    Number.isInteger(requiredMaxRequests) &&
+    summary.totalRequests > requiredMaxRequests
+  ) {
+    throw new Error(
+      `app.network_assert expected at most ${requiredMaxRequests} request(s), got ${summary.totalRequests}.`,
+    );
+  }
+  for (const type of requiredTypes) {
+    if (!hasPositiveOwnCount(summary.requestsByType, type)) {
+      throw new Error(`app.network_assert did not observe required type ${type}.`);
+    }
+  }
+  for (const type of forbiddenTypes) {
+    if (hasPositiveOwnCount(summary.requestsByType, type)) {
+      throw new Error(`app.network_assert observed forbidden type ${type}.`);
+    }
+  }
+
+  return {
+    action: input.action,
+    id,
+    artifactPath,
+    status: summary.status,
+    totalRequests: summary.totalRequests,
+  };
+}
+
+function hasPositiveOwnCount(counts, key) {
+  return (
+    Object.hasOwn(counts, key) &&
+    Number.isInteger(counts[key]) &&
+    counts[key] > 0
+  );
+}
+
+function validateSummary(summary, expectedId) {
+  if (
+    !summary ||
+    typeof summary !== 'object' ||
+    Array.isArray(summary) ||
+    summary.schemaVersion !== 1 ||
+    summary.id !== expectedId ||
+    !['complete', 'partial', 'unavailable'].includes(summary.status) ||
+    !Number.isInteger(summary.totalRequests) ||
+    summary.totalRequests < 0 ||
+    !Array.isArray(summary.requests) ||
+    summary.requests.length !== summary.totalRequests ||
+    !Number.isInteger(summary.uninspectableBodyRequests) ||
+    summary.uninspectableBodyRequests < 0 ||
+    !Array.isArray(summary.projectedBodyFields) ||
+    summary.projectedBodyFields.some((field) => typeof field !== 'string') ||
+    !summary.requestsByType ||
+    typeof summary.requestsByType !== 'object' ||
+    Array.isArray(summary.requestsByType)
+  ) {
+    throw new Error('app.network_assert summary contract is invalid.');
+  }
+  const typeCounts = Object.values(summary.requestsByType);
+  for (const count of typeCounts) {
+    if (!Number.isInteger(count) || count < 1) {
+      throw new Error('app.network_assert summary type counts are invalid.');
+    }
+  }
+  if (
+    typeCounts.reduce((total, count) => total + count, 0) !==
+    summary.totalRequests
+  ) {
+    throw new Error('app.network_assert summary type counts are inconsistent.');
+  }
+}

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

@@ -1119,6 +1119,179 @@
         }
       ]
     },
+    "app.network_capture": {
+      "description": "Capture redacted HTTP requests between named Recipe Protocol v1 nodes through the adapter's persistent Network observer.",
+      "examples": [
+        {
+          "action": "app.network_capture",
+          "phase": "start",
+          "id": "perps-home",
+          "url_includes": ["api.hyperliquid.xyz/info"],
+          "methods": ["POST"],
+          "body_json_fields": ["type", "req.coin", "dex"],
+          "intent": "Start the redacted request window",
+          "next": "exercise-flow"
+        },
+        {
+          "action": "app.network_capture",
+          "phase": "end",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "intent": "End and index the redacted request window",
+          "next": "assert-network"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": { "type": "string", "enum": ["start", "end"] },
+          "id": { "type": "string" },
+          "url_includes": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "methods": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "body_json_fields": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "max_requests": { "type": "integer" },
+          "max_duration_ms": { "type": "integer" },
+          "artifact_path": { "type": "string" }
+        },
+        "required": ["phase", "id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
+    "app.network_assert": {
+      "description": "Assert a previously indexed app.network_capture summary without hiding its diagnostics on failure.",
+      "examples": [
+        {
+          "action": "app.network_assert",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "required_status": "complete",
+          "required_min_requests": 1,
+          "required_types": ["allMids"],
+          "forbidden_types": ["candleSnapshot"],
+          "intent": "Assert the indexed request summary",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "artifact_path": { "type": "string" },
+          "required_status": {
+            "type": "string",
+            "enum": ["complete", "partial", "unavailable"]
+          },
+          "required_min_requests": { "type": "integer" },
+          "required_max_requests": { "type": "integer" },
+          "required_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "forbidden_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
+    "app.performance_capture": {
+      "description": "Capture bounded CDP renderer frame metrics and separately labelled JavaScript work across Recipe Protocol v1 node boundaries.",
+      "examples": [
+        {
+          "action": "app.performance_capture",
+          "phase": "start",
+          "id": "homepage-scroll",
+          "max_duration_ms": 300000,
+          "intent": "Start the bounded UI smoothness window",
+          "next": "exercise-flow"
+        },
+        {
+          "action": "app.performance_capture",
+          "phase": "end",
+          "id": "homepage-scroll",
+          "artifact_path": "performance/homepage-scroll.json",
+          "html_path": "performance/homepage-scroll.html",
+          "intent": "End and index the UI smoothness window",
+          "next": "assert-performance"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": {
+            "type": "string",
+            "enum": ["start", "end"]
+          },
+          "id": { "type": "string" },
+          "max_duration_ms": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Maximum accepted at runtime: 3600000 ms."
+          },
+          "artifact_path": { "type": "string" },
+          "html_path": { "type": "string" }
+        },
+        "required": ["phase", "id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": ["host-read-export"]
+    },
+    "app.performance_assert": {
+      "description": "Assert a previously indexed app.performance_capture summary without hiding unavailable or partial source coverage.",
+      "examples": [
+        {
+          "action": "app.performance_assert",
+          "id": "homepage-scroll",
+          "artifact_path": "performance/homepage-scroll.json",
+          "required_status": ["complete", "partial"],
+          "minimum_frame_count": 1,
+          "require_native_ui_when_supported": true,
+          "required_node_ids": ["scroll-homepage"],
+          "intent": "Assert the indexed UI smoothness summary",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "artifact_path": { "type": "string" },
+          "required_status": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["complete", "partial", "unavailable"]
+            }
+          },
+          "minimum_frame_count": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Minimum MetaMask renderer frame count. JavaScript task count cannot satisfy this assertion."
+          },
+          "require_native_ui_when_supported": { "type": "boolean" },
+          "required_node_ids": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": ["host-read-export"]
+    },
     "app.status": {
       "description": "Report the adapter's static status — platform, project root, resolved checkout shape, and headless compatibility mode (no live route or account).",
       "examples": [

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

@@ -1112,6 +1112,210 @@
       },
       "execution_capabilities": ["app-mutation"]
     },
+    "app.network_capture": {
+      "description": "Capture redacted HTTP requests between named Recipe Protocol v1 nodes through the adapter's persistent Network observer.",
+      "examples": [
+        {
+          "action": "app.network_capture",
+          "phase": "start",
+          "id": "perps-home",
+          "url_includes": ["api.hyperliquid.xyz/info"],
+          "methods": ["POST"],
+          "body_json_fields": ["type", "req.coin", "dex"],
+          "intent": "Start the redacted request window",
+          "next": "exercise-flow"
+        },
+        {
+          "action": "app.network_capture",
+          "phase": "end",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "intent": "End and index the redacted request window",
+          "next": "assert-network"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": {
+            "type": "string",
+            "enum": ["start", "end"]
+          },
+          "id": {
+            "type": "string"
+          },
+          "url_includes": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "methods": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "body_json_fields": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "max_requests": {
+            "type": "integer"
+          },
+          "max_duration_ms": {
+            "type": "integer"
+          },
+          "artifact_path": {
+            "type": "string"
+          }
+        },
+        "required": ["phase", "id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
+    "app.network_assert": {
+      "description": "Assert a previously indexed app.network_capture summary without hiding its diagnostics on failure.",
+      "examples": [
+        {
+          "action": "app.network_assert",
+          "id": "perps-home",
+          "artifact_path": "network/perps-home.json",
+          "required_status": "complete",
+          "required_min_requests": 1,
+          "required_types": ["allMids"],
+          "forbidden_types": ["candleSnapshot"],
+          "intent": "Assert the indexed request summary",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "artifact_path": {
+            "type": "string"
+          },
+          "required_status": {
+            "type": "string",
+            "enum": ["complete", "partial", "unavailable"]
+          },
+          "required_min_requests": {
+            "type": "integer"
+          },
+          "required_max_requests": {
+            "type": "integer"
+          },
+          "required_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "forbidden_types": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": []
+    },
+    "app.performance_capture": {
+      "description": "Capture bounded CDP native UI frame metrics and separately labelled JavaScript work across Recipe Protocol v1 node boundaries.",
+      "examples": [
+        {
+          "action": "app.performance_capture",
+          "phase": "start",
+          "id": "homepage-scroll",
+          "max_duration_ms": 300000,
+          "intent": "Start the bounded UI smoothness window",
+          "next": "exercise-flow"
+        },
+        {
+          "action": "app.performance_capture",
+          "phase": "end",
+          "id": "homepage-scroll",
+          "artifact_path": "performance/homepage-scroll.json",
+          "html_path": "performance/homepage-scroll.html",
+          "intent": "End and index the UI smoothness window",
+          "next": "assert-performance"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "phase": {
+            "type": "string",
+            "enum": ["start", "end"]
+          },
+          "id": {
+            "type": "string"
+          },
+          "max_duration_ms": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Maximum accepted at runtime: 3600000 ms."
+          },
+          "artifact_path": {
+            "type": "string"
+          },
+          "html_path": {
+            "type": "string"
+          }
+        },
+        "required": ["phase", "id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": ["host-read-export"]
+    },
+    "app.performance_assert": {
+      "description": "Assert a previously indexed app.performance_capture summary without hiding unavailable or partial source coverage.",
+      "examples": [
+        {
+          "action": "app.performance_assert",
+          "id": "homepage-scroll",
+          "artifact_path": "performance/homepage-scroll.json",
+          "required_status": ["complete", "partial"],
+          "minimum_frame_count": 1,
+          "require_native_ui_when_supported": true,
+          "required_node_ids": ["scroll-homepage"],
+          "intent": "Assert the indexed UI smoothness summary",
+          "next": "done"
+        }
+      ],
+      "schema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "artifact_path": {
+            "type": "string"
+          },
+          "required_status": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["complete", "partial", "unavailable"]
+            }
+          },
+          "minimum_frame_count": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Minimum native UI frame count. JavaScript task count cannot satisfy this assertion."
+          },
+          "require_native_ui_when_supported": {
+            "type": "boolean"
+          },
+          "required_node_ids": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id"],
+        "additionalProperties": false
+      },
+      "execution_capabilities": ["host-read-export"]
+    },
     "app.status": {
       "description": "Report the adapter's static status — platform, project root, resolved checkout shape, and headless compatibility mode (no live route or account).",
       "examples": [