@deeeed/metamask-harness 0.42.0 → 0.44.0

package/adapters/mobile/bridge-runtime/console-forwarder.cjs

@@ -35,10 +35,12 @@ const {
   deviceIdFromUrl,
 } = require('./lib/cdp-broker.cjs');
 const { createDevtoolsProxy } = require('./lib/devtools-proxy.cjs');
+const { resolvePort } = require('./lib/config.cjs');
 
 // Hermes uses Node's built-in WebSocket client. The local DevTools proxy uses
 // the package's pinned `ws` server implementation.
 const HANDSHAKE_TIMEOUT_MS = 3000;
+const RUNTIME_ENABLE_TIMEOUT_MS = 60_000;
 
 const DISCOVER_ACTIVE_MS = 1000; // a device is unattached — look for it quickly
 const DISCOVER_STEADY_MS = 10000; // all known targets attached — cheap liveness tick
@@ -46,7 +48,7 @@ const FLUSH_MS = 100;
 const MAX_LINE_CHARS = 4000;
 
 function parseArgs(argv) {
-  const args = { port: process.env.WATCHER_PORT || '8081', out: null };
+  const args = { port: resolvePort(), out: null };
   for (let i = 2; i < argv.length; i += 1) {
     if (argv[i] === '--port') args.port = argv[++i];
     else if (argv[i] === '--out') args.out = argv[++i];
@@ -208,7 +210,7 @@ function sendCommand(session, method, params = {}, timeoutMs = 10_000) {
 }
 
 broker = createCdpBroker({
-  socketPath: brokerSocketPath(path.dirname(out)),
+  socketPath: brokerSocketPath(path.dirname(out), port),
   sessions,
   sendCommand,
   requestDiscovery(deviceId) {
@@ -310,25 +312,36 @@ function connect(target) {
   ws.addEventListener('open', async () => {
     clearTimeout(handshakeTimer);
     session.opened = true;
+    // A live inspector socket is enough for broker commands. Do not keep the
+    // broker unavailable while Runtime.enable replays a large console buffer or
+    // while __AGENTIC__ is being installed after a Hermes context handoff.
+    // Commands such as status already report agenticPresent=false and their
+    // callers retry against the same bounded action deadline.
+    session.brokerReady = true;
+    broker.onSessionOpen(deviceId);
+    devtoolsProxy.onSessionOpen(deviceId, session);
+    process.stderr.write(`console-forwarder: attached ${name}\n`);
     try {
-      await sendCommand(session, 'Runtime.enable');
+      await sendCommand(
+        session,
+        'Runtime.enable',
+        {},
+        RUNTIME_ENABLE_TIMEOUT_MS,
+      );
       const evaluation = await sendCommand(session, 'Runtime.evaluate', {
         expression: "typeof globalThis.__AGENTIC__ === 'object'",
         returnByValue: true,
         awaitPromise: false,
       });
       if (evaluation?.result?.value !== true) {
-        throw new Error('CDP target does not expose __AGENTIC__');
+        process.stderr.write(
+          `console-forwarder: ${name} is waiting for __AGENTIC__\n`,
+        );
       }
-      session.brokerReady = true;
-      broker.onSessionOpen(deviceId);
-      devtoolsProxy.onSessionOpen(deviceId, session);
-      process.stderr.write(`console-forwarder: attached ${name}\n`);
     } catch (error) {
       process.stderr.write(
-        `console-forwarder: rejected ${name}: ${String(error?.message || error).slice(0, 256)}\n`,
+        `console-forwarder: console bootstrap pending for ${name}: ${String(error?.message || error).slice(0, 256)}\n`,
       );
-      ws.close();
     }
   });
   ws.addEventListener('message', (event) => {

package/adapters/mobile/bridge-runtime/lib/bridge-errors.cjs

@@ -63,6 +63,8 @@ const NEEDLE_CODES = [
   ['websocket error', BRIDGE_ERROR_CODES.WS_CLOSED],
   ['cdp connection timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
   ['cdp message timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+  ['cdp broker connection timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
+  ['cdp broker request timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
   ['evaluation timed out', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
   ['timed out', BRIDGE_ERROR_CODES.CDP_TIMEOUT],
 ];

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

@@ -12,22 +12,40 @@ const MAX_ACTIVE_CAPTURES = 16;
 const MAX_COMPLETED_CAPTURES = 16;
 const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 const MAX_POST_DATA_BYTES = 64 * 1024;
-const MAX_RPC_FRAME_BYTES = 8 * 1024 * 1024;
+const MAX_REQUEST_FRAME_BYTES = 8 * 1024 * 1024;
+const MAX_RESPONSE_FRAME_BYTES = 16 * 1024 * 1024;
+const MAX_HUD_STEP_BYTES = 16 * 1024;
+const MAX_HUD_UPDATES = 64;
 const MAX_RETAINED_STRING_LENGTH = 256;
 const MAX_BROKER_TIMEOUT_MS = 60_000;
 const SENSITIVE_FIELD =
   /(?:address|authorization|cookie|key|password|secret|token|user|account)/iu;
 const SENSITIVE_VALUE =
   /(?:0x[a-f0-9]{40,}|[a-f0-9]{64,}|eyJ[a-z0-9_-]{20,}\.[a-z0-9_-]{20,})/iu;
+const APPLY_HUD_UPDATE_FUNCTION = `function(step) {
+  const bridge = this.__AGENTIC__;
+  if (step === null) {
+    if (typeof bridge?.hideStep !== 'function') return false;
+    setTimeout(() => bridge.hideStep(), 0);
+    return true;
+  }
+  if (typeof bridge?.showStep !== 'function') return false;
+  setTimeout(() => bridge.showStep(step), 0);
+  return true;
+}`;
 
-function brokerSocketPath(runtimeDir) {
+function brokerSocketPath(runtimeDir, endpointIdentity) {
   const runtimePath = path.resolve(
     runtimeDir ||
       process.env.RECIPE_RUNTIME_DIR ||
       path.join('temp', 'recipe', 'runtime'),
   );
+  const socketIdentity =
+    endpointIdentity === undefined || endpointIdentity === null
+      ? runtimePath
+      : `${runtimePath}\u0000${String(endpointIdentity)}`;
   const identity = createHash('sha256')
-    .update(runtimePath)
+    .update(socketIdentity)
     .digest('hex')
     .slice(0, 20);
   return path.join('/tmp', `mmh-cdp-${identity}.sock`);
@@ -77,6 +95,23 @@ function boundedTimeout(value, fallback = 10_000) {
     : fallback;
 }
 
+// State recovery is event-driven. Pick a fixed bound below the caller's RPC
+// deadline so the broker always answers before the client gives up. Returning
+// literals also keeps the timer independent from untrusted request values.
+function stateWaitTimeout(value) {
+  const timeout = boundedTimeout(value);
+  if (timeout <= 500) return 1;
+  if (timeout <= 1_000) return 400;
+  if (timeout <= 2_000) return 900;
+  if (timeout <= 5_000) return 1_900;
+  if (timeout <= 10_000) return 4_500;
+  if (timeout <= 15_000) return 9_500;
+  if (timeout <= 30_000) return 14_500;
+  if (timeout <= 45_000) return 29_500;
+  if (timeout <= 55_000) return 44_500;
+  return 54_500;
+}
+
 function readField(value, field) {
   let current = value;
   for (const segment of String(field).split('.')) {
@@ -331,8 +366,30 @@ function createCdpBroker({
 }) {
   const captures = new Map();
   const completedCaptures = new Map();
+  const hudUpdates = new Map();
+  const appliedHudVersions = new Map();
+  const hudApplyChains = new Map();
   const clients = new Set();
   const subscriptions = new Map();
+  const knownTargets = new Map(
+    [...sessions.entries()].flatMap(([deviceId, session]) =>
+      session?.brokerReady
+        ? [[deviceId, {
+            deviceId,
+            generation: 1,
+            name: String(session.name || ''),
+            ready: true,
+          }]]
+        : [],
+    ),
+  );
+  const sessionWaiters = new Map();
+  const targetWaiters = new Set();
+  const observedSessions = new Map(
+    [...sessions.entries()].flatMap(([deviceId, session]) =>
+      session?.brokerReady ? [[deviceId, session]] : [],
+    ),
+  );
 
   const capturesFor = (deviceId) => {
     if (!captures.has(deviceId)) captures.set(deviceId, new Map());
@@ -346,23 +403,83 @@ function createCdpBroker({
     return completedCaptures.get(deviceId);
   };
 
-  async function waitForSession(deviceId, timeoutMs) {
+  function targetList({ nameIncludes = '', readyOnly = false } = {}) {
+    const pin = String(nameIncludes).trim().toLowerCase();
+    return [...knownTargets.values()]
+      .filter((target) => !readyOnly || target.ready)
+      .filter((target) => !pin || target.name.toLowerCase().includes(pin))
+      .map((target) => ({ ...target }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  function settleTargetWaiters() {
+    for (const waiter of [...targetWaiters]) {
+      const targets = targetList({ nameIncludes: waiter.nameIncludes });
+      if (targets.length === 0) continue;
+      targetWaiters.delete(waiter);
+      clearTimeout(waiter.timer);
+      waiter.resolve(targets);
+    }
+  }
+
+  function resolveTargets(params, timeoutMs, socket) {
+    const existing = targetList({ nameIncludes: params.nameIncludes });
+    if (existing.length > 0) return Promise.resolve(existing);
+    requestDiscovery?.('');
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        nameIncludes: String(params.nameIncludes || ''),
+        resolve,
+        reject,
+        socket,
+        timer: null,
+      };
+      waiter.timer = setTimeout(() => {
+        targetWaiters.delete(waiter);
+        reject(new Error('CDP broker never observed the requested target'));
+      }, stateWaitTimeout(timeoutMs));
+      targetWaiters.add(waiter);
+      settleTargetWaiters();
+    });
+  }
+
+  function waitForSession(deviceId, timeoutMs, socket) {
     if (sessions.get(deviceId)?.brokerReady) return sessions.get(deviceId);
     requestDiscovery?.(deviceId);
-    const deadline = Date.now() + boundedTimeout(timeoutMs);
-    while (Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, 100));
+    return new Promise((resolve, reject) => {
+      const waiters = sessionWaiters.get(deviceId) || new Set();
+      const waiter = {
+        resolve,
+        reject,
+        socket,
+        timer: setTimeout(() => {
+          waiters.delete(waiter);
+          if (waiters.size === 0) sessionWaiters.delete(deviceId);
+          reject(new Error(`CDP broker target unavailable: ${deviceId}`));
+        }, stateWaitTimeout(timeoutMs)),
+      };
+      waiters.add(waiter);
+      sessionWaiters.set(deviceId, waiters);
       const session = sessions.get(deviceId);
-      if (session?.brokerReady) return session;
-    }
-    throw new Error('CDP broker target unavailable');
+      if (session?.brokerReady) {
+        waiters.delete(waiter);
+        if (waiters.size === 0) sessionWaiters.delete(deviceId);
+        clearTimeout(waiter.timer);
+        resolve(session);
+      }
+    });
   }
 
-  async function enableNetwork(deviceId, capture, timeoutMs = 10_000) {
+  async function enableNetwork(
+    deviceId,
+    capture,
+    timeoutMs = 10_000,
+    socket,
+  ) {
     try {
       const budgetMs = boundedTimeout(timeoutMs);
       const deadline = Date.now() + budgetMs;
-      const session = await waitForSession(deviceId, budgetMs);
+      const session = await waitForSession(deviceId, budgetMs, socket);
       const remainingMs = Math.max(1, deadline - Date.now());
       await sendCommand(session, 'Network.enable', {}, remainingMs);
       if (capture.enableErrors.length > 0) capture.partial = true;
@@ -381,6 +498,67 @@ function createCdpBroker({
     capturesFor(deviceId).delete(capture.id);
   }
 
+  async function applyHudUpdate(deviceId, timeoutMs, socket) {
+    if (!hudUpdates.has(deviceId)) return { status: 'none' };
+    const budgetMs = boundedTimeout(timeoutMs);
+    const deadline = Date.now() + budgetMs;
+    const session = await waitForSession(deviceId, budgetMs, socket);
+    const update = hudUpdates.get(deviceId);
+    if (!update) return { status: 'none' };
+    if (appliedHudVersions.get(deviceId) === update.version) {
+      return { status: 'applied', version: update.version };
+    }
+    let applied = false;
+    while (Date.now() < deadline) {
+      const globalObject = await sendCommand(
+        session,
+        'Runtime.evaluate',
+        { expression: 'globalThis', returnByValue: false, awaitPromise: false },
+        Math.max(1, deadline - Date.now()),
+      );
+      const objectId = globalObject?.result?.objectId;
+      if (!objectId) {
+        throw new Error('Mobile HUD runtime did not expose globalThis');
+      }
+      const evaluation = await sendCommand(
+        session,
+        'Runtime.callFunctionOn',
+        {
+          objectId,
+          functionDeclaration: APPLY_HUD_UPDATE_FUNCTION,
+          arguments: [{ value: update.step }],
+          returnByValue: true,
+          awaitPromise: false,
+        },
+        Math.max(1, deadline - Date.now()),
+      );
+      if (evaluation?.result?.value === true) {
+        applied = true;
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (!applied) {
+      throw new Error('Mobile HUD bridge was not installed before the update deadline');
+    }
+    if (hudUpdates.get(deviceId)?.version === update.version) {
+      appliedHudVersions.set(deviceId, update.version);
+    }
+    return { status: 'applied', version: update.version };
+  }
+
+  function scheduleHudUpdate(deviceId, timeoutMs, socket) {
+    const previous = hudApplyChains.get(deviceId) || Promise.resolve();
+    const next = previous
+      .catch(() => undefined)
+      .then(() => applyHudUpdate(deviceId, timeoutMs, socket));
+    hudApplyChains.set(deviceId, next);
+    void next.finally(() => {
+      if (hudApplyChains.get(deviceId) === next) hudApplyChains.delete(deviceId);
+    }).catch(() => undefined);
+    return next;
+  }
+
   function expireCapture(deviceId, capture) {
     if (capturesFor(deviceId).get(capture.id) !== capture) return;
     finishCapture(deviceId, capture, true);
@@ -422,15 +600,44 @@ function createCdpBroker({
     };
   }
 
-  async function control(deviceId, action, params, timeoutMs = 10_000) {
+  async function control(
+    deviceId,
+    action,
+    params,
+    timeoutMs = 10_000,
+    socket,
+  ) {
     if (action === 'list-targets') {
-      return [...sessions.entries()]
-        .filter(([, session]) => session.brokerReady)
-        .map(([activeDeviceId, session]) => ({
-          deviceId: activeDeviceId,
-          name: String(session.name || ''),
-        }))
-        .sort((a, b) => a.name.localeCompare(b.name));
+      return targetList({ readyOnly: true }).map(({ deviceId, name }) => ({
+        deviceId,
+        name,
+      }));
+    }
+    if (action === 'resolve-targets') {
+      return resolveTargets(params, timeoutMs, socket);
+    }
+    if (action === 'hud-update') {
+      const step = params.step ?? null;
+      if (step !== null && (typeof step !== 'object' || Array.isArray(step))) {
+        throw new Error('HUD update requires an object step or null');
+      }
+      if (Buffer.byteLength(JSON.stringify(step)) > MAX_HUD_STEP_BYTES) {
+        throw new Error('HUD update exceeds its bound');
+      }
+      const previousVersion = hudUpdates.get(deviceId)?.version || 0;
+      if (hudUpdates.has(deviceId)) {
+        hudUpdates.delete(deviceId);
+      }
+      while (hudUpdates.size >= MAX_HUD_UPDATES) {
+        const oldestDeviceId = hudUpdates.keys().next().value;
+        hudUpdates.delete(oldestDeviceId);
+        appliedHudVersions.delete(oldestDeviceId);
+      }
+      const version = previousVersion + 1;
+      hudUpdates.set(deviceId, { step, version });
+      requestDiscovery?.(deviceId);
+      void scheduleHudUpdate(deviceId, 10_000).catch(() => undefined);
+      return { status: 'queued', version };
     }
     if (action === 'capture-start') {
       const capture = normalizeCapture(params);
@@ -443,7 +650,12 @@ function createCdpBroker({
       }
       completedCapturesFor(deviceId).delete(capture.id);
       deviceCaptures.set(capture.id, capture);
-      await enableNetwork(deviceId, capture, Math.max(1, timeoutMs - 500));
+      await enableNetwork(
+        deviceId,
+        capture,
+        Math.max(1, timeoutMs - 500),
+        socket,
+      );
       return { id: capture.id, status: 'started' };
     }
     if (action === 'capture-end') {
@@ -467,15 +679,18 @@ function createCdpBroker({
     try {
       onClientActivity?.();
       if (request.type === 'command') {
+        const budgetMs = boundedTimeout(request.timeoutMs);
+        const deadline = Date.now() + budgetMs;
         const session = await waitForSession(
           request.deviceId,
-          boundedTimeout(request.timeoutMs),
+          budgetMs,
+          socket,
         );
         const result = await sendCommand(
           session,
           request.method,
           request.params || {},
-          boundedTimeout(request.timeoutMs),
+          Math.max(1, deadline - Date.now()),
         );
         writeMessage(socket, { id: request.id, result });
         return;
@@ -486,6 +701,7 @@ function createCdpBroker({
           request.action,
           request.params || {},
           boundedTimeout(request.timeoutMs),
+          socket,
         );
         writeMessage(socket, { id: request.id, result });
         return;
@@ -532,7 +748,7 @@ function createCdpBroker({
     socket.setEncoding('utf8');
     socket.on('data', (chunk) => {
       buffer += chunk;
-      if (Buffer.byteLength(buffer) > MAX_RPC_FRAME_BYTES) {
+      if (Buffer.byteLength(buffer) > MAX_REQUEST_FRAME_BYTES) {
         writeMessage(socket, { error: 'CDP broker request exceeds its bound' });
         socket.destroy();
         return;
@@ -556,6 +772,21 @@ function createCdpBroker({
     const drop = () => {
       clients.delete(socket);
       subscriptions.delete(socket);
+      for (const waiter of [...targetWaiters]) {
+        if (waiter.socket !== socket) continue;
+        targetWaiters.delete(waiter);
+        clearTimeout(waiter.timer);
+        waiter.reject(new Error('CDP broker client closed'));
+      }
+      for (const [deviceId, waiters] of sessionWaiters) {
+        for (const waiter of [...waiters]) {
+          if (waiter.socket !== socket) continue;
+          waiters.delete(waiter);
+          clearTimeout(waiter.timer);
+          waiter.reject(new Error('CDP broker client closed'));
+        }
+        if (waiters.size === 0) sessionWaiters.delete(deviceId);
+      }
     };
     socket.on('close', drop);
     socket.on('error', drop);
@@ -568,12 +799,40 @@ function createCdpBroker({
 
   return {
     onSessionOpen(deviceId) {
+      const session = sessions.get(deviceId);
+      if (!session?.brokerReady) return;
+      const previous = knownTargets.get(deviceId);
+      const sessionChanged = observedSessions.get(deviceId) !== session;
+      knownTargets.set(deviceId, {
+        deviceId,
+        generation:
+          previous?.generation === undefined
+            ? 1
+            : previous.generation + (!previous.ready || sessionChanged ? 1 : 0),
+        name: String(session.name || previous?.name || ''),
+        ready: true,
+      });
+      observedSessions.set(deviceId, session);
+      const waiters = sessionWaiters.get(deviceId);
+      if (waiters) {
+        sessionWaiters.delete(deviceId);
+        for (const waiter of waiters) {
+          clearTimeout(waiter.timer);
+          waiter.resolve(session);
+        }
+      }
+      settleTargetWaiters();
       for (const capture of capturesFor(deviceId).values()) {
         if (capture.reconnects > 0) capture.partial = true;
         void enableNetwork(deviceId, capture);
       }
+      void scheduleHudUpdate(deviceId, 10_000).catch(() => undefined);
     },
     onSessionClose(deviceId) {
+      const previous = knownTargets.get(deviceId);
+      if (previous) knownTargets.set(deviceId, { ...previous, ready: false });
+      observedSessions.delete(deviceId);
+      appliedHudVersions.delete(deviceId);
       for (const capture of capturesFor(deviceId).values()) {
         capture.reconnects += 1;
         capture.partial = true;
@@ -621,6 +880,18 @@ function createCdpBroker({
     },
     close() {
       clearInterval(expirySweep);
+      for (const waiters of sessionWaiters.values()) {
+        for (const waiter of waiters) {
+          clearTimeout(waiter.timer);
+          waiter.reject(new Error('CDP broker closed'));
+        }
+      }
+      sessionWaiters.clear();
+      for (const waiter of targetWaiters) {
+        clearTimeout(waiter.timer);
+        waiter.reject(new Error('CDP broker closed'));
+      }
+      targetWaiters.clear();
       for (const socket of clients) socket.destroy();
       try {
         server.close();
@@ -696,7 +967,7 @@ function createBrokerClient(socketPath, deviceId, timeout) {
     });
     socket.on('data', (chunk) => {
       buffer += chunk;
-      if (Buffer.byteLength(buffer) > MAX_RPC_FRAME_BYTES) {
+      if (Buffer.byteLength(buffer) > MAX_RESPONSE_FRAME_BYTES) {
         socket.destroy();
         for (const entry of pending.values()) {
           entry.reject(new Error('CDP broker response exceeds its bound'));

package/adapters/mobile/bridge-runtime/lib/config.cjs

@@ -4,9 +4,9 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 /** Read a value from .js.env */
-function loadEnvValue(key) {
+function loadEnvValue(key, appRoot = process.env.APP_ROOT || process.cwd()) {
   try {
-    const envPath = path.resolve(process.env.APP_ROOT || process.cwd(), '.js.env');
+    const envPath = path.resolve(appRoot, '.js.env');
     const content = fs.readFileSync(envPath, 'utf8');
     // .js.env uses `export KEY="value"` (shell-sourceable format),
     // so we handle the optional `export` prefix and strip surrounding quotes.
@@ -18,9 +18,19 @@ function loadEnvValue(key) {
   return undefined;
 }
 
+function resolvePort(env = process.env, appRoot = env.APP_ROOT || process.cwd()) {
+  return (
+    env.WATCHER_PORT ||
+    env.METRO_PORT ||
+    loadEnvValue('WATCHER_PORT', appRoot) ||
+    loadEnvValue('METRO_PORT', appRoot) ||
+    '8081'
+  );
+}
+
 /** Read WATCHER_PORT from .js.env or env (default: 8081) */
 function loadPort() {
-  return Number.parseInt(process.env.WATCHER_PORT || loadEnvValue('WATCHER_PORT') || '8081', 10);
+  return Number.parseInt(resolvePort(), 10);
 }
 
 /** Read IOS_SIMULATOR name from .js.env or env (default: none — accept any device) */
@@ -48,4 +58,4 @@ function loadAndroidTargetDeviceName() {
   return process.env.ANDROID_TARGET_DEVICE_NAME || '';
 }
 
-module.exports = { loadEnvValue, loadPort, loadSimulatorName, loadAndroidDevice, loadAndroidTargetDeviceName };
+module.exports = { loadEnvValue, loadPort, resolvePort, loadSimulatorName, loadAndroidDevice, loadAndroidTargetDeviceName };

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

@@ -300,6 +300,7 @@ async function discoverTarget(port, { probe = true } = {}) {
     for (const candidate of candidates) {
       if (candidate.webSocketDebuggerUrl === acceptedPinnedCandidate.webSocketDebuggerUrl) {
         return {
+          id: acceptedPinnedCandidate.id || '',
           wsUrl: acceptedPinnedCandidate.webSocketDebuggerUrl,
           deviceName: acceptedPinnedCandidate.deviceName || '',
         };
@@ -312,6 +313,7 @@ async function discoverTarget(port, { probe = true } = {}) {
   // platform/device filtering and select the highest-ranked runtime instead.
   if (!probe) {
     return {
+      id: candidates[0].id || '',
       wsUrl: candidates[0].webSocketDebuggerUrl,
       deviceName: candidates[0].deviceName || '',
     };
@@ -331,7 +333,7 @@ async function discoverTarget(port, { probe = true } = {}) {
   for (const candidate of candidates) {
     const hasAgentic = await probeTarget(candidate.webSocketDebuggerUrl);
     if (hasAgentic) {
-      return { wsUrl: candidate.webSocketDebuggerUrl, deviceName: candidate.deviceName || '' };
+      return { id: candidate.id || '', wsUrl: candidate.webSocketDebuggerUrl, deviceName: candidate.deviceName || '' };
     }
   }
 
@@ -348,7 +350,7 @@ async function discoverTarget(port, { probe = true } = {}) {
   }
 
   // Fallback: return highest page number (most likely the JS runtime)
-  return { wsUrl: candidates[0].webSocketDebuggerUrl, deviceName: candidates[0].deviceName || '' };
+  return { id: candidates[0].id || '', wsUrl: candidates[0].webSocketDebuggerUrl, deviceName: candidates[0].deviceName || '' };
 }
 
 /**