@mobileaidev/ai-app-bridge 0.3.4 → 0.3.6

package/bin/executors/playwright-worker.js

@@ -0,0 +1,307 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID, createHash } = require('node:crypto');
+const { createRequire } = require('node:module');
+const { ReceiptJournal } = require('./receipt-journal');
+const { atomicJson } = require('./managed-runtime');
+
+const protocol = 'aab.playwright-worker/v1';
+const packageDirectory = process.argv[2];
+const sessionDirectory = process.argv[3];
+const identity = { sessionId: process.argv[4], runtimeEpoch: process.argv[5] };
+const playwright = createRequire(path.join(packageDirectory, 'package.json'))('playwright');
+const pages = new Map();
+const frames = new Map();
+const journals = new Map();
+const events = [];
+let eventSequence = 0;
+let eventBytes = 0;
+let browser;
+let browserContext;
+let closing = false;
+let active;
+let tail = Promise.resolve();
+const requests = new Map();
+
+function failure(code, message, details) { return Object.assign(new Error(message), { code, details }); }
+function emitEvent(type, data) {
+  const event = { sequence: ++eventSequence, observedAtMs: Date.now(), type, ...data };
+  const bytes = Buffer.byteLength(JSON.stringify(event));
+  events.push({ event, bytes }); eventBytes += bytes;
+  while (events.length > 1000 || eventBytes > 1024 * 1024) eventBytes -= events.shift().bytes;
+}
+function bindFrame(frame, targetId) {
+  let entry = frames.get(frame);
+  if (!entry) { entry = { frameId: randomUUID(), documentId: randomUUID(), targetId, frame }; frames.set(frame, entry); }
+  return entry;
+}
+function bindPage(page) {
+  if (pages.size >= 64) {
+    emitEvent('page-capacity', { maximum: 64 });
+    void page.close().catch(error => emitEvent('page-close-error', { message: error.message }));
+    return null;
+  }
+  const targetId = randomUUID();
+  pages.set(targetId, page);
+  for (const frame of page.frames()) bindFrame(frame, targetId);
+  page.on('frameattached', frame => bindFrame(frame, targetId));
+  page.on('framenavigated', frame => { bindFrame(frame, targetId).documentId = randomUUID(); });
+  page.on('framedetached', frame => frames.delete(frame));
+  page.on('close', () => { pages.delete(targetId); emitEvent('page-closed', { targetId }); for (const [frame, entry] of frames) if (entry.targetId === targetId) frames.delete(frame); });
+  page.on('console', message => emitEvent('console', { targetId, level: message.type(), text: message.text().slice(0, 8192) }));
+  page.on('pageerror', error => emitEvent('page-error', { targetId, message: error.message.slice(0, 8192) }));
+  page.on('requestfailed', request => emitEvent('request-failed', { targetId, url: request.url().slice(0, 8192), method: request.method(), failure: request.failure()?.errorText }));
+  page.on('response', response => emitEvent('response', { targetId, url: response.url().slice(0, 8192), status: response.status() }));
+  page.on('dialog', async dialog => {
+    const policy = active?.args.targetId === targetId ? active.args.dialog : null;
+    emitEvent('dialog', { targetId, dialogType: dialog.type(), message: dialog.message().slice(0, 8192), disposition: policy?.action || 'dismiss' });
+    try { if (policy?.action === 'accept') await dialog.accept(policy.promptText); else await dialog.dismiss(); }
+    catch (error) { emitEvent('dialog-error', { targetId, message: error.message.slice(0, 8192) }); }
+  });
+  emitEvent('page-opened', { targetId });
+  return targetId;
+}
+function pageFor(args) {
+  if (args.sessionId !== identity.sessionId || args.runtimeEpoch !== identity.runtimeEpoch) throw failure('executor_session_mismatch', 'Executor session identity changed.');
+  const page = pages.get(args.targetId);
+  if (!page || page.isClosed()) throw failure('executor_target_closed', 'The selected browser page is not open.');
+  return page;
+}
+function documentFor(args) {
+  pageFor(args);
+  const entry = [...frames.values()].find(value => value.frameId === args.frameId && value.targetId === args.targetId);
+  if (!entry || entry.frame.isDetached() || entry.documentId !== args.documentId) throw failure('reobserve_required', 'The selected frame/document changed; observe again.');
+  return entry;
+}
+async function locate(frame, selector, documentId) {
+  // The isolated selector world remembers the document bound by observe().
+  // Locator retries stay inside it; a new document can never acquire an old ID.
+  const root = frame.locator(`aabdocument=match:${documentId}`);
+  switch (selector.by) {
+    case 'role': return root.getByRole(selector.value, { name: selector.name, exact: true });
+    case 'testId': return root.getByTestId(selector.value);
+    case 'text': return root.getByText(selector.value, { exact: true });
+    case 'label': return root.getByLabel(selector.value, { exact: true });
+    case 'placeholder': return root.getByPlaceholder(selector.value, { exact: true });
+    case 'css': {
+      // Accept CSS syntax only. Playwright's selector chains could otherwise
+      // escape the observed document through an internal selector engine.
+      const valid = await frame.evaluate(value => {
+        try { document.querySelectorAll(value); return true; } catch { return false; }
+      }, selector.value);
+      if (!valid) throw failure('executor_selector_invalid', 'The css selector must use standard CSS syntax.');
+      return root.locator(`css=${selector.value}`);
+    }
+    default: throw failure('executor_selector_unsupported', 'Unknown selector kind.');
+  }
+}
+async function unique(frame, selector, documentId) {
+  const locator = await locate(frame, selector, documentId);
+  const count = await locator.count();
+  if (count !== 1) throw failure(count === 0 ? 'target_not_found' : 'ambiguous_target', 'Executor selectors must match exactly one element.', { matches: count });
+  return locator;
+}
+function assertDocument(entry, documentId) {
+  if (entry.documentId !== documentId || entry.frame.isDetached()) throw failure('reobserve_required', 'The selected document changed during preparation.');
+}
+function journalFor(targetId) {
+  let journal = journals.get(targetId);
+  if (!journal) { journal = new ReceiptJournal(path.join(sessionDirectory, 'receipts'), { ...identity, targetId }); journals.set(targetId, journal); }
+  return journal;
+}
+
+async function observe(args, options) {
+  const page = pageFor(args);
+  const documents = [];
+  const pageFrames = page.frames();
+  if (pageFrames.length > 64) throw failure('executor_frame_limit', 'This document exceeds the 64-frame observation limit.');
+  for (const frame of pageFrames) {
+    const entry = bindFrame(frame, args.targetId);
+    const documentId = entry.documentId;
+    await frame.locator(`aabdocument=bind:${documentId}`).count();
+    const snapshot = await frame.locator('body').ariaSnapshotJSON({ ...options, depth: 30 });
+    const controls = await frame.locator('input,textarea,select,button,a[href],[contenteditable="true"],[role],[data-testid]').evaluateAll((elements, limit) => elements.slice(0, limit).map(element => ({
+      tag: element.tagName.toLowerCase(), role: element.getAttribute('role'), testId: element.getAttribute('data-testid'),
+      id: element.id || null, text: typeof element.innerText === 'string' ? element.innerText.slice(0, 512) : null,
+      label: element.getAttribute('aria-label'), placeholder: element.getAttribute('placeholder'),
+      value: element.matches('input[type="password"]') ? null : ('value' in element ? String(element.value).slice(0, 4096) : null),
+      disabled: 'disabled' in element ? element.disabled : element.getAttribute('aria-disabled') === 'true',
+      visible: element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }),
+    })), args.maxControls ?? 200);
+    assertDocument(entry, documentId);
+    documents.push({ frameId: entry.frameId, documentId, parentFrameId: frame.parentFrame() ? bindFrame(frame.parentFrame(), args.targetId).frameId : null,
+      url: frame.url(), name: frame.name(), snapshot, controls });
+  }
+  const result = { ok: true, ...identity, targetId: args.targetId, url: page.url(), title: await page.title(),
+    documents, pages: [...pages].filter(([, item]) => !item.isClosed()).map(([targetId, item]) => ({ targetId, url: item.url() })),
+    scope: 'browser-dom', engine: 'playwright', observedAtMs: Date.now() };
+  if (Buffer.byteLength(JSON.stringify(result)) > 4 * 1024 * 1024) throw failure('executor_observation_too_large', 'Browser observation exceeds 4 MiB.');
+  return result;
+}
+
+async function mutate(args, options) {
+  const actionId = args.actionId;
+  const journal = journalFor(args.targetId);
+  const begun = journal.begin(actionId, { operation: args.operation, targetId: args.targetId, frameId: args.frameId, documentId: args.documentId,
+    ...(args.action ? { action: args.action } : {}), ...(args.url ? { url: args.url } : {}), ...(args.dialog ? { dialog: args.dialog } : {}) });
+  if (!begun.fresh) {
+    if (begun.receipt.phase === 'completed') return { ...begun.receipt.result, replayed: true, executionReceipt: begun.receipt };
+    throw failure('executor_action_unresolved', 'This action was already started. Query its original receipt; do not replay it.');
+  }
+  let dispatched = false;
+  let result;
+  const startedAtMs = Date.now();
+  try {
+    const entry = documentFor(args);
+    if (args.operation === 'navigate') {
+      const page = pageFor(args);
+      if (entry.frame !== page.mainFrame()) throw failure('executor_navigation_scope', 'Navigation requires the observed main document.');
+      dispatched = true;
+      await page.goto(args.url, { ...options, waitUntil: 'domcontentloaded' });
+    } else {
+      const action = args.action;
+      const locator = await unique(entry.frame, action.selector, args.documentId);
+      const destination = action.type === 'drag' ? await unique(entry.frame, action.destination, args.documentId) : null;
+      assertDocument(entry, args.documentId);
+      if (options.signal.aborted) throw failure('executor_cancelled', 'Executor action was cancelled before dispatch.');
+      dispatched = true;
+      switch (action.type) {
+        case 'click': await locator.click(options); break;
+        case 'doubleClick': await locator.dblclick(options); break;
+        case 'hover': await locator.hover(options); break;
+        case 'fill': await locator.fill(action.text, options); break;
+        case 'type': await locator.pressSequentially(action.text, options); break;
+        case 'press': await locator.press(action.text, options); break;
+        case 'check': await locator.setChecked(action.checked, options); break;
+        case 'select': await locator.selectOption(action.values, options); break;
+        case 'scrollIntoView': await locator.scrollIntoViewIfNeeded(options); break;
+        case 'drag': await locator.dragTo(destination, options); break;
+        case 'upload': await locator.setInputFiles(action.files, options); break;
+        default: throw failure('executor_action_unsupported', 'Unknown browser action.');
+      }
+      if (action.type === 'fill') {
+        const value = await locator.evaluate(element => element.isContentEditable ? element.innerText : element.value);
+        if (value !== action.text) throw failure('executor_postcondition_failed', 'The editor did not retain the requested value.', { observedValue: value });
+      }
+    }
+    result = { ok: true, ...identity, targetId: args.targetId, actionId, dispatched: true, ambiguous: false,
+      mechanism: args.operation === 'navigate' ? 'browser-navigation' : `playwright-${args.action.type}` };
+  } catch (error) {
+    result = { ok: false, ...identity, targetId: args.targetId, actionId, error: error.code || 'executor_action_failed',
+      message: error.message, details: error.details, dispatched, ambiguous: dispatched };
+  }
+  result.timings = { executionMs: Date.now() - startedAtMs };
+  let receipt;
+  try { receipt = journal.finish(begun.receipt, result); }
+  catch (error) { error.dispatched = dispatched; error.ambiguous = dispatched; throw error; }
+  return { ...result, executionReceipt: receipt };
+}
+
+async function handle(args, controller) {
+  const options = { timeout: args.timeoutMs ?? 30000, signal: controller.signal };
+  if (args.operation === 'open') {
+    if (browser) throw failure('executor_already_open', 'Worker already owns a browser.');
+    await playwright.selectors.register('aabdocument', () => {
+      const identities = new WeakMap();
+      const query = (root, selector) => {
+        const document = root.nodeType === 9 ? root : root.ownerDocument;
+        const separator = selector.indexOf(':');
+        const operation = selector.slice(0, separator), id = selector.slice(separator + 1);
+        if (operation === 'bind') identities.set(document, id);
+        return identities.get(document) === id ? document.documentElement : null;
+      };
+      return { query, queryAll: (root, selector) => { const element = query(root, selector); return element ? [element] : []; } };
+    }, { contentScript: true });
+    browser = await playwright[args.browser || 'chromium'].launch({ headless: args.headless ?? true, timeout: options.timeout });
+    if (controller.signal.aborted) { await browser.close(); throw failure('executor_cancelled', 'Browser preparation was cancelled.'); }
+    browserContext = await browser.newContext({ viewport: args.viewport || { width: 1280, height: 900 } });
+    browserContext.on('page', bindPage);
+    const page = await browserContext.newPage();
+    const targetId = [...pages].find(([, item]) => item === page)[0];
+    await page.goto(args.url, { ...options, waitUntil: 'domcontentloaded' });
+    const descriptor = { schemaVersion: protocol, ...identity, targetId, engine: 'playwright', version: browser.version(),
+      browser: args.browser || 'chromium', openedAtMs: Date.now(), state: 'open' };
+    atomicJson(path.join(sessionDirectory, 'session.json'), descriptor);
+    return { ok: true, ...descriptor, capabilities: ['observe', 'act', 'navigate', 'wait', 'screenshot', 'events', 'receipt', 'close'],
+      limitations: ['closed-shadow-root', 'native-operating-system-ui'], dialogDefault: 'dismiss' };
+  }
+  if (args.operation === 'observe') return observe(args, options);
+  if (args.operation === 'act' || args.operation === 'navigate') return mutate(args, options);
+  if (args.operation === 'wait') {
+    const entry = documentFor(args), locator = await locate(entry.frame, args.selector, args.documentId);
+    await locator.waitFor({ ...options, state: args.state || 'visible' });
+    if (args.text !== undefined) {
+      const deadline = Date.now() + options.timeout;
+      while (await locator.textContent(options) !== args.text) {
+        assertDocument(entry, args.documentId);
+        if (controller.signal.aborted || Date.now() >= deadline) throw failure('executor_wait_timeout', 'Expected text was not observed.');
+        await new Promise(resolve => setTimeout(resolve, 25));
+      }
+    }
+    assertDocument(entry, args.documentId);
+    return { ok: true, ...identity, targetId: args.targetId, condition: 'matched', observedAtMs: Date.now() };
+  }
+  if (args.operation === 'screenshot') {
+    const page = pageFor(args);
+    const bytes = await page.screenshot({ ...options, fullPage: args.fullPage ?? false, type: 'png' });
+    fs.mkdirSync(path.dirname(args.outFile), { recursive: true });
+    fs.writeFileSync(args.outFile, bytes, { flag: 'wx', mode: 0o600 });
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    return { ok: true, ...identity, targetId: args.targetId, outFile: args.outFile, artifact: { sha256, bytes: bytes.length },
+      refs: [{ stream: 'screenshot', screenshotId: args.outFile, sha256 }] };
+  }
+  if (args.operation === 'events') {
+    pageFor(args);
+    const after = args.afterSequence ?? 0;
+    const selected = events.filter(({ event }) => event.sequence > after).slice(0, args.limit ?? 100);
+    return { ok: true, ...identity, items: selected.map(({ event }) => event),
+      nextSequence: selected.at(-1)?.event.sequence ?? after, throughSequence: eventSequence,
+      gap: events.length > 0 && after < events[0].event.sequence - 1 };
+  }
+  if (args.operation === 'close') { pageFor(args); await shutdown(); return { ok: true, ...identity, closed: true }; }
+  throw failure('executor_operation_unsupported', 'Unknown worker operation.');
+}
+
+let shutdownPromise;
+function shutdown() {
+  if (shutdownPromise) return shutdownPromise;
+  closing = true;
+  active?.controller.abort();
+  shutdownPromise = (async () => {
+    await browser?.close();
+    atomicJson(path.join(sessionDirectory, 'closed.json'), { ...identity, closedAtMs: Date.now() });
+  })();
+  return shutdownPromise;
+}
+
+process.on('message', message => {
+  if (message?.protocol !== protocol) return;
+  if (message.type === 'cancel') { requests.get(message.id)?.controller.abort(); return; }
+  if (message.type !== 'request') return;
+  const controller = new AbortController();
+  const request = { id: message.id, controller, args: message.args };
+  requests.set(message.id, request);
+  const deadline = Date.now() + (message.args.timeoutMs ?? 30000);
+  const timer = setTimeout(() => controller.abort(), message.args.timeoutMs ?? 30000);
+  tail = tail.then(async () => {
+    active = request;
+    try {
+      if (closing) throw failure('executor_closed', 'Executor worker is closing.');
+      if (controller.signal.aborted || Date.now() >= deadline) throw failure('executor_cancelled', 'Executor request was cancelled while queued.');
+      const result = await handle({ ...message.args, timeoutMs: Math.max(1, deadline - Date.now()) }, controller);
+      if (process.connected) process.send({ protocol, id: message.id, result });
+      if (message.args.operation === 'close') process.disconnect();
+    } catch (error) {
+      const dispatched = error.dispatched ?? (message.args.operation === 'open' && Boolean(browser));
+      if (process.connected) process.send({ protocol, id: message.id, result: { ok: false, error: error.code || 'executor_failed', message: error.message,
+        details: error.details, dispatched, ambiguous: error.ambiguous ?? dispatched } });
+    } finally { clearTimeout(timer); requests.delete(message.id); active = null; }
+  }).catch(async error => {
+    if (process.connected) process.send({ protocol, id: message.id, result: { ok: false, error: error.code || 'executor_failed', message: error.message } });
+  });
+});
+process.on('disconnect', () => { shutdown().finally(() => process.exit(0)); });
+process.on('SIGTERM', () => { shutdown().finally(() => process.exit(0)); });
+process.send({ protocol, type: 'ready', ...identity });

package/bin/executors/receipt-journal.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { atomicJson, readJson } = require('./managed-runtime');
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  return value;
+}
+
+class ReceiptJournal {
+  constructor(directory, identity, { maxActions = 4096 } = {}) {
+    this.directory = directory;
+    this.identity = identity;
+    this.maxActions = maxActions;
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  }
+
+  receipt(actionId) {
+    const value = readJson(path.join(this.directory, `${hash(actionId)}.json`));
+    if (value && (value.actionId !== actionId || JSON.stringify(value.identity) !== JSON.stringify(this.identity))) {
+      throw new CommandError('executor_receipt_identity_mismatch', 'Receipt does not belong to this executor session.');
+    }
+    return value;
+  }
+
+  begin(actionId, request) {
+    const digest = hash(JSON.stringify(canonical(request)));
+    const existing = this.receipt(actionId);
+    if (existing) {
+      if (existing.requestDigest !== digest) throw new CommandError('idempotency_conflict', 'actionId was already used with different executor arguments.');
+      return { fresh: false, receipt: existing };
+    }
+    if (fs.readdirSync(this.directory).filter(name => name.endsWith('.json')).length >= this.maxActions) {
+      throw new CommandError('executor_receipt_capacity', 'Close this session and open a new one; retained action receipts are full.');
+    }
+    const receipt = { schemaVersion: 'aab.executor-receipt/v1', identity: this.identity, actionId, requestDigest: digest,
+      phase: 'started', preparedAtMs: Date.now(), settled: false, dispatched: null };
+    atomicJson(path.join(this.directory, `${hash(actionId)}.json`), receipt);
+    return { fresh: true, receipt };
+  }
+
+  finish(receipt, result) {
+    const completed = { ...receipt, phase: 'completed', completedAtMs: Date.now(), settled: true,
+      dispatched: result.dispatched === true, result };
+    atomicJson(path.join(this.directory, `${hash(receipt.actionId)}.json`), completed);
+    return completed;
+  }
+}
+
+module.exports = { ReceiptJournal, canonical };

package/bin/feedback-probe.js

@@ -1,6 +1,31 @@
 'use strict';
 
-async function runWithFeedbackProbe({
+async function runWithFeedbackProbe(options = {}) {
+  const { command, args = {}, runner } = options;
+  if (!isFullFeedback(args.feedback) || !isMutationCommand(command)
+      || command === 'launch-app' || command === 'launch-activity') return runFeedback(options);
+  const observationCommand = String(command).startsWith('ios-') ? 'ios-ui-observation'
+    : String(command).startsWith('web-') ? 'web-ui-observation' : 'ui-observation';
+  const targetArgs = pick(args, ['serial', 'adb', 'packageName', 'port', 'deviceId', 'bundleId', 'runtimeUrl', 'iosHost', 'iosPort', 'sessionId', 'runtimeEpoch', 'targetId']);
+  if (observationCommand !== 'web-ui-observation') targetArgs.provider = String(command).includes('flutter') ? 'flutter' : 'native';
+  const started = await runner(observationCommand, { ...targetArgs, operation: 'start', durationMs: 5000 });
+  if (started?.ok !== true || started.active !== true || typeof started.leaseId !== 'string') {
+    return { result: { ok: false, error: 'ui_observation_unavailable', dispatched: false, ambiguous: false, details: started ?? null },
+      observation: { mode: 'full', inconclusive: true }, evidence: [] };
+  }
+  let output;
+  try {
+    output = await runFeedback(options);
+    return output;
+  } finally {
+    let cleanup;
+    try { cleanup = await runner(observationCommand, { ...targetArgs, operation: 'stop', leaseId: started.leaseId }); }
+    catch (error) { cleanup = { ok: false, error: error.code || 'ui_observation_cleanup_failed' }; }
+    if (output?.observation) output.observation.window = { leaseId: started.leaseId, maxDurationMs: 5000, cleanup };
+  }
+}
+
+async function runFeedback({
   command,
   args = {},
   runner,
@@ -130,6 +155,7 @@ function isFullFeedback(value) {
 function isMutationCommand(command) {
   const normalized = String(command || '').toLowerCase();
   const readOnly = new Set([
+    'ui-observation', 'ios-ui-observation', 'web-ui-observation',
     'status', 'tree', 'uia-tree', 'screenshot', 'logs', 'network', 'state', 'events',
     'logcat', 'keyboard-state', 'wait-text', 'flutter-tree', 'flutter-nodes', 'h5-dom',
     'flutter-h5-dom', 'webview-pages', 'webview-network', 'webview-console',

package/bin/ios-device-outcome.js

@@ -23,6 +23,23 @@ function deviceCommandRejection(reply, args, error) {
 function originalDeviceRejection(reply, args) {
   const command = args.slice(0, 3).join(' ');
   if (!matchesInvocation(reply, args) || reply.info.outcome !== 'failed') return null;
+  // CoreDevice rejects this launch while acquiring its prerequisites, before
+  // contacting the application service. Match the original structured failure,
+  // not stderr text or a general tunnel/timeout error.
+  const usage = reply.error;
+  const requested = usage?.userInfo?.RequestedDeviceStates?.array;
+  const available = usage?.userInfo?.CurrentlyAssertableStates?.array;
+  const prerequisites = ['com.apple.coredevice.remoteServiceDiscoveryTrustedConnectivityAvailable',
+    'com.apple.coredevice.coreDeviceServicesLoaded', 'com.apple.coredevice.powerAssertionTaken'];
+  if (command === 'device process launch' && !reply.result
+      && usage?.domain === 'com.apple.dt.CoreDeviceError' && usage.code === 4016
+      && Array.isArray(available) && available.length === 0
+      && Array.isArray(requested) && requested.length === prerequisites.length
+      && prerequisites.every(state => requested.some(value => value?.string === state))) {
+    return { ok: false, error: 'ios_device_unavailable',
+      message: 'CoreDevice rejected the launch before dispatch because the device connection and services were unavailable. Restore the device connection before launching again.',
+      settled: true, dispatched: false, ambiguous: false, deviceOutcome: reply };
+  }
   const errors = [];
   function visit(value, depth) {
     if (!value || typeof value !== 'object' || depth > 16 || errors.length > 32) return;

package/bin/ios-execution.js

@@ -4,6 +4,7 @@ const { randomUUID } = require('node:crypto');
 const { CommandError } = require('./command-errors');
 const fs = require('node:fs');
 const { originalDeviceOutcome, deviceCommandProof } = require('./ios-device-outcome');
+const { initializationProof, recoverLegacySetup } = require('./ios-wda-startup');
 const managed = require('./shared-kernel/managed-sdk-execution');
 const { runDeviceEffect } = require('./shared-kernel/device-mutation-lease');
 const { checkExecution, runExecution } = require('./shared-kernel/execution-scope');
@@ -75,12 +76,23 @@ async function executeIOSAction({ port, kind, payload, status, target, timeoutMs
   }, result => result.executionReceipt);
 }
 
-async function reconcileIOS({ lease, device, args, createPort }) {
+async function reconcileIOS({ lease, device, args, createPort, readWdaTestSummary }) {
+  const original = args.setupResultPath ? lease.status(iosDeviceKey(device)).ownership : null;
   const result = await lease.reconcile(iosDeviceKey(device), async pending => {
     if (pending.target?.deviceId !== device.udid
         || args.bundleId && pending.target?.bundleId && pending.target.bundleId !== args.bundleId) {
       return { settled: false, error: 'ios_original_completion_identity_required' };
     }
+    if (pending.kind === 'ios-wda-start' || pending.kind === 'ios-command' && pending.command === 'ios-setup') {
+      try {
+        const proof = pending.kind === 'ios-wda-start'
+          ? initializationProof(await readWdaTestSummary(pending.invocation.resultBundlePath), pending.invocation, device.udid)
+          : original?.pending?.id === pending.id && await recoverLegacySetup({ pending, owner: original.owner,
+            resultPath: args.setupResultPath, device, readSummary: readWdaTestSummary });
+        return proof || { settled: false, error: 'ios_original_wda_startup_outcome_unresolved' };
+      } catch (error) { return { settled: false, error: 'ios_wda_startup_completion_unavailable', cause: error.code || 'invalid_result' }; }
+    }
+    if (args.setupResultPath) return { settled: false, error: 'ios_original_completion_identity_required' };
     if (pending.kind === 'ios-command') {
       const invocation = pending.invocation;
       const index = Array.isArray(invocation?.arguments) ? invocation.arguments.indexOf('--json-output') : -1;

package/bin/ios-provider.js

@@ -17,6 +17,7 @@ const { openWdaPort, target: wdaTarget } = require('./ios-wda-port');
 const { prepareWdaProject, wdaBuildEnvironment } = require('./ios-wda-project');
 const { executeWDAAction, reconcileWDA, completionPort } = require('./ios-wda-execution');
 const { deviceCommandRejection, deviceCommandProof } = require('./ios-device-outcome');
+const { initializationProof } = require('./ios-wda-startup');
 const { bindFlutterAction } = require('./shared-kernel/flutter-target');
 const nativeTarget = require('./shared-kernel/ios-native-target');
 const h5Target = require('./shared-kernel/ios-h5-target');
@@ -94,6 +95,11 @@ class IOSBridgeProvider {
           return await this.launchApp(args, context);
         case 'ios-status':
           return await this.runtimeGet(args, '/v1/status');
+        case 'ios-ui-observation': {
+          const port = await this.runtimePort(args, context);
+          const result = await port.post(require('./ui-observation').path(args), require('./ui-observation').request(args));
+          return { ...result, endpoint: port.endpoint.baseUrl, device: port.endpoint.device, runtimeBinding: port.endpoint.runtimeBinding };
+        }
         case 'ios-tree':
           return await this.runtimeGet(args, '/v1/view/tree');
         case 'ios-logs':
@@ -152,6 +158,22 @@ class IOSBridgeProvider {
     const ctx = this.context(args);
     const raw = await this.devicectlJson(ctx, ['list', 'devices']);
     const devices = parseDevicectlDevices(raw).map(shapeDevice);
+    const selected = selectDeviceFromList(devices, args).device;
+    if (selected && (selected.tunnelState !== 'connected' || selected.ddiServicesAvailable !== true)) {
+      // list devices can describe a sleeping tunnel. A targeted, read-only
+      // details request asks CoreDevice to establish its lazy connection.
+      try {
+        const reply = await this.devicectlJson(ctx, ['device', 'info', 'details', '--device', selected.identifier]);
+        const current = shapeDevice(reply?.result);
+        if (current.identifier !== selected.identifier || !current.udid || current.udid !== selected.udid) {
+          throw bindingFailure('ios_device_identity_mismatch', 'Device details did not match the selected device identifier and UDID.');
+        }
+        devices[devices.indexOf(selected)] = { ...current, connectionProbe: { ok: true, source: 'devicectl.device.info.details' } };
+      } catch (error) {
+        selected.connectionProbe = { ok: false, source: 'devicectl.device.info.details',
+          error: error.code || 'ios_device_probe_failed', message: error.message };
+      }
+    }
     return {
       ok: true,
       devices,
@@ -273,7 +295,9 @@ class IOSBridgeProvider {
       if (start.ok === true) {
         wda = start.status || await this.wdaStatus(args);
       } else {
-        return { ok: false, error: start.error, message: start.message, device, steps };
+        return { ok: false, error: start.error, message: start.message, device, steps,
+          ...(start.executionReceipt ? { settled: start.settled, dispatched: start.dispatched,
+            ambiguous: start.ambiguous, executionReceipt: start.executionReceipt } : {}) };
       }
     }
     steps.push({ name: 'wda', ok: wda.ok === true, url: wda.url || null, error: wda.error || null });
@@ -449,7 +473,7 @@ class IOSBridgeProvider {
       const endpoint = port.endpoint;
       let response;
       if (method === 'POST') {
-        const status = await port.get('/v1/status');
+        const status = await port.get(endpointPath === '/v1/flutter/action' ? '/v1/flutter/snapshot' : '/v1/status');
         if (status.ok === false) return { ...status, dispatched: false, ambiguous: false };
         const kind = endpointPath === '/v1/h5/action' ? 'h5' : 'flutter';
         const target = { platform: 'ios', deviceId: endpoint.device.udid, bundleId: args.bundleId,
@@ -477,7 +501,7 @@ class IOSBridgeProvider {
       return lookupCompletion(completionPort(port), 'wda', identity, cancelled);
     }
     if (args.operation === 'reconcile') return reconcileIOS({ lease, device, args,
-      createPort: target => this.runtimePort(target, { device }) });
+      createPort: target => this.runtimePort(target, { device }), readWdaTestSummary: file => this.readWdaTestSummary(file) });
     if (args.operation === 'status') return {
       ok: true, device, ownership: lease.status(key),
       runtime: args.bundleId ? await this.runtimeGet(args, '/v1/execution/status', { device, allowUnavailable: true }) : null,
@@ -502,7 +526,7 @@ class IOSBridgeProvider {
   }
 
   async flutterTree(args = {}) {
-    const status = await this.runtimeGet(args, '/v1/status');
+    const status = await this.runtimeGet(args, '/v1/flutter/snapshot');
     if (status.ok === false) return status;
     return {
       ok: true,
@@ -533,7 +557,7 @@ class IOSBridgeProvider {
 
   async flutterControl(command, args, context = {}) {
     const port = await this.runtimePort(args, context);
-    const status = await port.get('/v1/status');
+    const status = await port.get('/v1/flutter/snapshot');
     if (status.ok !== true) return { ...status, dispatched: false, ambiguous: false };
     const action = flutterControls.get(command);
     let payload = { action };
@@ -562,7 +586,9 @@ class IOSBridgeProvider {
       throw bindingFailure('ios_device_not_found', 'deviceId must match the selected devicectl identifier or UDID.');
     }
     if (device.developerModeStatus !== 'enabled' || device.ddiServicesAvailable !== true || device.tunnelState !== 'connected') {
-      throw bindingFailure('ios_tunnel_unavailable', 'The selected iPhone must expose a connected developer tunnel. Unlock/trust the device and let Xcode prepare it.');
+      throw bindingFailure('ios_tunnel_unavailable', device.connectionProbe?.ok === false
+        ? `The selected iPhone did not become ready after a targeted device details request: ${device.connectionProbe.message}`
+        : 'The selected iPhone does not expose ready developer services after the device details request. Inspect ios-doctor for the observed device state.');
     }
     const runtimeBinding = await this.readRuntimePortFile(args, device);
     const host = target.iosHost ?? device.tunnelIPAddress;
@@ -768,25 +794,47 @@ class IOSBridgeProvider {
       };
     } finally { await build.stop(); }
     const logFile = path.join(directory, 'xcodebuild.log');
-    const runtime = spawnWdaProcess(ctx.xcodebuild, [...xcodeArgs, 'test-without-building'], logFile, true);
-    const child = runtime.child;
-    let ready = false;
-    try {
-      while (!runtime.terminal) {
-        checkExecution();
-        const status = await this.wdaStatus({ ...args, deviceId: device.udid, wdaRunnerBundleId });
-        if (status.ok) {
-          ready = true; child.unref();
-          return { ok: true, device, wdaTestBundleId, wdaRunnerBundleId, pid: child.pid, logFile, buildLogFile, prepared, status };
+    const resultBundlePath = path.join(directory, 'result.xcresult');
+    const invocation = { arguments: [...xcodeArgs, '-resultBundlePath', resultBundlePath, 'test-without-building'],
+      resultBundlePath, startedAtMs: Date.now() };
+    return runDeviceEffect({ kind: 'ios-wda-start', command: 'ios-setup', invocation,
+      target: { deviceId: device.udid, bundleId: args.bundleId ?? null } }, async () => {
+      const runtime = spawnWdaProcess(ctx.xcodebuild, invocation.arguments, logFile, true);
+      const child = runtime.child;
+      let ready = false;
+      try {
+        while (!runtime.terminal) {
+          checkExecution();
+          const status = await this.wdaStatus({ ...args, deviceId: device.udid, wdaRunnerBundleId });
+          if (status.ok) {
+            ready = true; child.unref();
+            return { ok: true, device, wdaTestBundleId, wdaRunnerBundleId, pid: child.pid, logFile, buildLogFile, prepared, status,
+              executionReceipt: { kind: 'ios-wda-start', settled: true, dispatched: true, ambiguous: false, invocation,
+                runtimeBinding: status.runtimeBinding } };
+          }
+          await executionSleep(1000);
+        }
+        let proof;
+        if (!runtime.spawnError && runtime.exitCode === 65) {
+          try { proof = initializationProof(await this.readWdaTestSummary(resultBundlePath), invocation, device.udid); }
+          catch { /* An absent or unreadable original XCTest result remains unresolved. */ }
         }
-        await executionSleep(1000);
+        return { ok: false, error: runtime.spawnError ? 'ios_wda_xcodebuild_spawn_failed' : 'ios_wda_xcodebuild_exited',
+          message: runtime.spawnError?.message ?? 'xcodebuild closed before the selected Runner published a bound endpoint.',
+          phase: 'device-test', exitCode: runtime.exitCode, logFile, buildLogFile, prepared, resultBundlePath,
+          ...(runtime.spawnError ? { dispatched: false, ambiguous: false,
+            executionReceipt: { kind: 'ios-wda-start', settled: true, dispatched: false, ambiguous: false, invocation } } : {}),
+          ...(proof ? { ...proof.outcome, executionReceipt: proof } : {}) };
+      } finally {
+        if (!ready) await runtime.stop();
       }
-      return { ok: false, error: runtime.spawnError ? 'ios_wda_xcodebuild_spawn_failed' : 'ios_wda_xcodebuild_exited',
-        message: runtime.spawnError?.message ?? 'xcodebuild closed before the selected Runner published a bound endpoint.',
-        phase: 'device-test', exitCode: runtime.exitCode, logFile, buildLogFile, prepared };
-    } finally {
-      if (!ready) await runtime.stop();
-    }
+    }, result => result.executionReceipt);
+  }
+
+  async readWdaTestSummary(resultBundlePath) {
+    const reply = await execFileText(this.execFile, 'xcrun', ['xcresulttool', 'get', 'test-results', 'summary',
+      '--path', resultBundlePath, '--format', 'json'], { timeoutMs: 10000 });
+    return JSON.parse(reply.stdout);
   }
 
   async requireDevice(args = {}) {
@@ -987,7 +1035,9 @@ function withQuery(endpointPath, query) {
 function iosSetupSuggestion(device, runtime, wda) {
   if (!device) return 'Connect one iPhone, trust this Mac on the device, then rerun ios-doctor.';
   if (device.developerModeStatus !== 'enabled') return 'Enable Developer Mode on the iPhone and rerun ios-setup.';
-  if (device.ddiServicesAvailable !== true || device.tunnelState !== 'connected') return 'Unlock/trust the iPhone and let Xcode finish preparing a connected developer tunnel.';
+  if (device.ddiServicesAvailable !== true || device.tunnelState !== 'connected') return device.connectionProbe?.ok === false
+    ? `The device details probe failed: ${device.connectionProbe.message}`
+    : 'The device details probe did not establish ready developer services. Check the selected device connection and Xcode preparation state.';
   if (wda?.ok !== true) return 'Start the prepared Runner with ios-setup --start-wda --team-id, or supply its exact wdaRunnerBundleId. An optional wdaUrl still requires container binding.';
   if (runtime?.ok !== true) return 'Launch a debug App with AiAppBridgeIOS and supply its exact deviceId and bundleId.';
   return 'Rerun ios-setup after resolving the failing check.';