@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/shared-kernel/summary-transformer.js

@@ -0,0 +1,352 @@
+'use strict';
+
+const { foregroundNativeWindow } = require('./native-target');
+
+const { semanticNode } = require('./semantic-node');
+const { parseXmlAttributes } = require('./xml-attributes');
+const iosNative = require('./ios-native-target');
+const uia = require('./uia-protocol');
+
+const DEFAULT_MAX_BYTES = 64 * 1024;
+const HARD_LIMIT_MS = 50;
+
+function summarizeTree({
+  provider,
+  rawTree,
+  rawTreeId,
+  screenshotId = null,
+  now = Date.now,
+  maxBytes = DEFAULT_MAX_BYTES,
+  hardLimitMs = HARD_LIMIT_MS,
+} = {}) {
+  if (!rawTreeId) {
+    return { ok: false, error: 'rawTreeId_required' };
+  }
+  if (!['native', 'uia', 'flutter', 'h5'].includes(provider)) {
+    return { ok: false, error: 'invalid_provider' };
+  }
+  const startedAtMs = now();
+  const collected = [];
+  let visited = 0;
+  let truncated = false;
+  let reason = null;
+  const page = provider === 'h5' && ([require('./ios-h5-target').schema, require('./android-h5-target').schema].includes(rawTree?.h5TargetSchema)
+    || rawTree?.webTargetSchema === require('./web-dom-target').schema)
+    ? { ...rawTree.pageRef, title: rawTree.dom.title.slice(0,500), readyState: rawTree.dom.readyState,
+      ...(rawTree.dom.viewport === undefined ? {} : { viewport: rawTree.dom.viewport }),
+      bodyText: rawTree.dom.bodyText.slice(0, Math.min(12000, Math.floor(maxBytes / 12))),
+      bodyTextTruncated: rawTree.dom.bodyTextTruncated || rawTree.dom.bodyText.length > Math.min(12000, Math.floor(maxBytes / 12)) } : undefined;
+  const activity = provider === 'native' && typeof rawTree?.activity === 'string' ? rawTree.activity : undefined;
+  const uiaSnapshot = provider === 'uia' ? uia.snapshotIdentity(rawTree) : null;
+
+  walkProvider(provider, rawTree, (source, sourceIndex) => {
+    visited += 1;
+    if (now() - startedAtMs > hardLimitMs) {
+      truncated = true;
+      reason = 'hard_limit_ms';
+      return false;
+    }
+    const node = toSemanticNode(provider, source, sourceIndex, rawTreeId, screenshotId, uiaSnapshot);
+    if (node && keepNode(node)) collected.push(node);
+    return true;
+  });
+
+  const nodes = fitNodes(collected, {
+    provider,
+    rawTreeId,
+    screenshotId,
+    visited,
+    truncated,
+    reason,
+    maxBytes,
+    activity,
+    page,
+    prioritizeVisibleControls: provider === 'native' && rawTree?.nativeTargetSchema === iosNative.schema,
+  });
+  truncated = truncated || nodes.truncated;
+  reason = reason || nodes.reason;
+
+  return {
+    ok: true,
+    provider,
+    rawTreeId,
+    screenshotId,
+    visited,
+    truncated,
+    reason,
+    ...(activity === undefined ? {} : { activity }),
+    ...(page === undefined ? {} : { page }),
+    nodes: nodes.nodes,
+  };
+}
+
+function walkProvider(provider, rawTree, visit) {
+  if (provider === 'native') walkNative(rawTree, visit);
+  else if (provider === 'uia') walkUia(rawTree, visit);
+  else if (provider === 'flutter') walkFlutter(rawTree, visit);
+  else walkH5(rawTree, visit);
+}
+
+function walkNative(tree, visit) {
+  if (tree?.nativeTargetSchema === iosNative.schema) {
+    let sourceIndex = 0;
+    for (const node of iosNative.nodesOf(tree)) {
+      const rect = node.rect;
+      const source = { id: node.elementId, elementId: node.elementId, className: node.type, elementType: node.type,
+        text: node.value, label: node.label, accessibilityId: node.rawIdentifier,
+        enabled: node.isEnabled === '1', visible: node.isVisible === '1',
+        editable: ['TextField', 'SecureTextField', 'TextView', 'SearchField'].includes(node.type),
+        bounds: rect ? { left: rect.x, top: rect.y, right: rect.x + rect.width, bottom: rect.y + rect.height } : null };
+      if (visit(source, sourceIndex++) === false) return;
+    }
+    return;
+  }
+  const index = { i: 0 };
+  if (Array.isArray(tree?.windows) && tree.windows.length) {
+    // Match native action selection: the last non-hidden root owns the foreground.
+    // An unknown/disabled root still blocks background controls. Do not spend the
+    // summary budget on a long background page before exposing its modal dialog.
+    const selected = foregroundNativeWindow(tree);
+    if (!selected) return;
+    const foreground = selected.index;
+    // Preserve the sourceIndex ordinal in the original windows' preorder.
+    for (let i = 0; i < foreground; i++) walkChildren(tree.windows[i]?.root, () => true, index);
+    walkChildren(tree.windows[foreground]?.root, visit, index);
+    return;
+  }
+  if (tree?.root) walkChildren(tree.root, visit, index);
+  else if (tree && !tree.windows && !tree.root) walkChildren(tree, visit, index);
+}
+
+function walkUia(tree, visit) {
+  if (typeof tree === 'string' || typeof tree?.xml === 'string' || typeof tree?.hierarchy === 'string') {
+    walkUiaXml(typeof tree === 'string' ? tree : (tree.xml || tree.hierarchy), visit);
+    return;
+  }
+  if (Array.isArray(tree?.nodes)) {
+    const index = { i: 0 };
+    for (const node of tree.nodes) {
+      if (visit(node, index.i++) === false) return;
+    }
+    return;
+  }
+  walkNative(tree, visit);
+}
+
+function walkUiaXml(xml, visit) {
+  const tokenRegex = /<\/node>|<node\b[^>]*\/?>/g;
+  let sourceIndex = 0;
+  let token;
+  while ((token = tokenRegex.exec(String(xml || ''))) !== null) {
+    const tag = token[0];
+    if (tag.startsWith('</node') || !tag.startsWith('<node')) continue;
+    if (visit(parseXmlAttributes(tag), sourceIndex++) === false) return;
+  }
+}
+
+function walkFlutter(tree, visit) {
+  const operable = tree?.operable || tree?.layout?.operable;
+  if (Array.isArray(operable?.nodes)) {
+    let sourceIndex = 0;
+    for (const node of operable.nodes) {
+      if (visit(node, sourceIndex++) === false) return;
+    }
+    return;
+  }
+  if (Array.isArray(tree?.nodes)) {
+    let sourceIndex = 0;
+    for (const node of tree.nodes) {
+      if (visit(node, sourceIndex++) === false) return;
+    }
+    return;
+  }
+  walkChildren(tree?.root || tree, visit, { i: 0 });
+}
+
+function walkH5(tree, visit) {
+  if ([require('./ios-h5-target').schema, require('./android-h5-target').schema].includes(tree?.h5TargetSchema) || tree?.webTargetSchema === require('./web-dom-target').schema) {
+    for (const [index, node] of tree.dom.controls.entries()) {
+      if (visit({ ...node, elementType: node.tag, label: node.ariaLabel, enabled: !node.disabled,
+        clickable: ['a', 'button'].includes(node.tag)
+          || node.tag === 'input' && ['checkbox', 'radio'].includes(node.type)
+          || ['checkbox', 'menuitemcheckbox', 'radio', 'menuitemradio', 'switch'].includes(node.role) }, index) === false) return;
+    }
+    return;
+  }
+  if (Array.isArray(tree?.nodes)) {
+    let sourceIndex = 0;
+    for (const node of tree.nodes) {
+      if (visit(node, sourceIndex++) === false) return;
+    }
+    return;
+  }
+  walkChildren(tree?.documentElement || tree?.root || tree, visit, { i: 0 });
+}
+
+function walkChildren(node, visit, index) {
+  if (!node || typeof node !== 'object') return true;
+  if (visit(node, index.i++) === false) return false;
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (const child of children) {
+    if (walkChildren(child, visit, index) === false) return false;
+  }
+  return true;
+}
+
+function toSemanticNode(provider, source, sourceIndex, rawTreeId, screenshotId, uiaSnapshot) {
+  if (!source || typeof source !== 'object') return null;
+  const className = String(source.className || source.class || source.widgetType || source.tag || source.tagName || '');
+  const text = firstString(source.text, source.value);
+  const label = firstString(
+    source.contentDescription,
+    source['content-desc'],
+    source.label,
+    source.accessibilityLabel,
+    source['aria-label'],
+    source.alt,
+  );
+  const role = classifyRole(source, className);
+  return semanticNode({
+    nodeId: nodeIdOf(provider, source, sourceIndex),
+    sourceIndex,
+    rawTreeId,
+    screenshotId,
+    targetRef: uiaSnapshot ? uia.nodeTargetRef(uiaSnapshot, source) : undefined,
+    role,
+    text,
+    label,
+    ...(provider === 'flutter' ? { hint: source.hint, errorText: source.errorText } : {}),
+    bounds: boundsOf(source),
+    enabled: source.enabled !== false && source.enabled !== 'false',
+    checked: provider === 'uia' && boolOrNull(source.checkable) !== true
+      ? null : source.checked === 'mixed' ? 'mixed' : boolOrNull(source.checked),
+    selected: boolOrNull(source.selected),
+    clickable: Boolean(
+      source.clickable === true
+      || source.clickable === 'true'
+      || (Array.isArray(source.actions) && source.actions.includes('tap')),
+    ),
+    ...(['native', 'h5'].includes(provider) ? {
+      resourceName: source.resourceName,
+      editable: source.editable,
+      interaction: source.interaction,
+      visible: source.visible,
+      effectiveVisible: source.effectiveVisible,
+      accessibilityId: source.accessibilityId,
+      elementId: source.elementId,
+      elementType: source.elementType,
+    } : {}),
+  });
+}
+
+function keepNode(node) {
+  return Boolean(
+    node.text
+    || node.label
+    || node.accessibilityId
+    || node.clickable
+    || node.checked !== null
+    || node.selected === true
+    || node.role === 'button'
+    || node.role === 'input'
+    || node.role === 'image',
+  );
+}
+
+function classifyRole(source, className) {
+  const lower = className.toLowerCase();
+  const role = String(source.role || '').toLowerCase();
+  if (['checkbox', 'menuitemcheckbox', 'radio', 'menuitemradio', 'switch'].includes(role)) return role;
+  if (lower === 'input' && ['checkbox', 'radio'].includes(source.type)) return source.type;
+  if (role === 'textbox' || source.editable === true || /edit|input|textfield|textarea|search/.test(lower)) return 'input';
+  if (role === 'button' || /button|btn/.test(lower)) return 'button';
+  if (role === 'image' || source.src || /image|img|imageview/.test(lower)) return 'image';
+  if (source.clickable === true || source.clickable === 'true' || (Array.isArray(source.actions) && source.actions.includes('tap'))) {
+    return 'clickable';
+  }
+  return 'text';
+}
+
+function nodeIdOf(provider, source, sourceIndex) {
+  if (source.id != null && source.id !== '') return source.id;
+  if (source.nodeId != null && source.nodeId !== '') return source.nodeId;
+  if (source.resourceName) return source.resourceName;
+  if (source['resource-id']) return source['resource-id'];
+  if (source.resourceId) return source.resourceId;
+  return `${provider}:${sourceIndex}`;
+}
+
+function boundsOf(source) {
+  if (source.bounds && typeof source.bounds === 'object') return source.bounds;
+  if (typeof source.bounds === 'string') return parseUiaBounds(source.bounds);
+  return null;
+}
+
+function parseUiaBounds(value) {
+  const match = /\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/.exec(String(value || ''));
+  if (!match) return null;
+  return {
+    left: Number(match[1]),
+    top: Number(match[2]),
+    right: Number(match[3]),
+    bottom: Number(match[4]),
+  };
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (value == null) continue;
+    const text = String(value);
+    if (text !== '') return text;
+  }
+  return null;
+}
+
+function boolOrNull(value) {
+  if (value === true || value === 'true') return true;
+  if (value === false || value === 'false') return false;
+  return null;
+}
+
+function fitNodes(nodes, { provider, rawTreeId, screenshotId, visited, truncated, reason, maxBytes, activity, page, prioritizeVisibleControls }) {
+  const meta = { ok: true, provider, rawTreeId, screenshotId, visited, truncated, reason, ...(activity === undefined ? {} : { activity }), ...(page === undefined ? {} : { page }) };
+  if (byteSize(nodes, meta) <= maxBytes) {
+    return { nodes, truncated, reason };
+  }
+  // WDA places native toolbars and sheets after potentially long WKWebView text.
+  // Reserve their visible controls before spending the budget on article content;
+  // retain the original identities, visibility and preorder in the final result.
+  const candidates = prioritizeVisibleControls
+    ? [...nodes].sort((a, b) => visibleControlPriority(a) - visibleControlPriority(b))
+    : nodes;
+  let low = 0;
+  let high = nodes.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const candidate = {
+      ...meta,
+      truncated: true,
+      reason: reason || 'max_bytes',
+    };
+    if (byteSize(candidates.slice(0, mid), candidate) <= maxBytes) low = mid;
+    else high = mid - 1;
+  }
+  const selected = candidates.slice(0, low);
+  if (prioritizeVisibleControls) selected.sort((a, b) => a.sourceIndex - b.sourceIndex);
+  return { nodes: selected, truncated: true, reason: reason || 'max_bytes' };
+}
+
+function visibleControlPriority(node) {
+  if (node.visible !== true) return 2;
+  return node.role === 'button' || node.role === 'input' || node.clickable ? 0 : 1;
+}
+
+function byteSize(nodes, meta) {
+  return Buffer.byteLength(JSON.stringify({ ...meta, nodes }), 'utf8');
+}
+
+module.exports = {
+  DEFAULT_MAX_BYTES,
+  HARD_LIMIT_MS,
+  summarizeTree,
+};

package/bin/shared-kernel/target-lease-protocol.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { targetIdentity } = require('./execution-target');
+
+function androidAppTargetKey(serial, packageName) {
+  const serialValue = String(serial || '');
+  if (!serialValue) return '';
+  return targetIdentity({ platform: 'android', serial: serialValue, packageName: String(packageName || '') });
+}
+
+function createTargetLease({ maxActive = 1 } = {}) {
+  const held = new Map();
+
+  function acquire(serial) {
+    const key = String(serial || '');
+    if (!key) return { ok: false, error: 'serial_required' };
+    const active = held.get(key) || 0;
+    if (active >= maxActive) {
+      return { ok: false, error: 'target_busy', serial: key, active };
+    }
+    held.set(key, active + 1);
+    return {
+      ok: true,
+      serial: key,
+      release() {
+        const current = held.get(key) || 0;
+        if (current <= 1) held.delete(key);
+        else held.set(key, current - 1);
+      },
+    };
+  }
+
+  function status(serial) {
+    const key = String(serial || '');
+    return { serial: key, active: held.get(key) || 0, maxActive };
+  }
+
+  return { acquire, status };
+}
+
+const processTargetLease = createTargetLease();
+
+function getProcessTargetLease() {
+  return processTargetLease;
+}
+
+module.exports = { androidAppTargetKey, createTargetLease, getProcessTargetLease };

package/bin/shared-kernel/text-wait.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { CommandError } = require('../command-errors');
+const { foregroundNativeWindow, explicitlyHidden } = require('./native-target');
+const { parseXmlAttributes } = require('./xml-attributes');
+const { looksLikeAndroidUiHierarchyXml, visitAndroidUiHierarchyTags } = require('../android-uia-xml');
+const { runExecution, checkExecution, executionSleep } = require('./execution-scope');
+
+function validateTextConditions({ targetText, requireText = [], absentText = [], requireActivity, provider = 'auto' }) {
+  const invalid = message => { throw new CommandError('invalid_argument', message, { field: 'conditions' }); };
+  if (!['auto', 'native', 'flutter', 'uia'].includes(provider)) invalid('provider must be auto, native, flutter, or uia.');
+  if (targetText !== undefined && (typeof targetText !== 'string' || !targetText)) invalid('targetText must be a non-empty exact label.');
+  if (requireActivity !== undefined && (typeof requireActivity !== 'string' || !requireActivity)) invalid('requireActivity must be a full Activity class name.');
+  for (const values of [requireText, absentText]) if (!Array.isArray(values) || values.some(value => typeof value !== 'string' || !value)) invalid('requireText and absentText must be arrays of non-empty exact labels.');
+  const present = [...new Set([...(targetText === undefined ? [] : [targetText]), ...requireText])];
+  if (!present.length && !absentText.length && !requireActivity) invalid('Supply targetText, requireText, absentText, or requireActivity.');
+  if (!present.length && provider === 'auto') invalid('Waiting for absence or Activity alone requires an explicit provider.');
+  if (present.some(value => absentText.includes(value))) invalid('The same label cannot be both required and absent.');
+  return { present, absent: [...new Set(absentText)], requireActivity, provider };
+}
+
+function visibleLabels(provider, rawTree) {
+  const labels = new Set();
+  const add = value => { if (typeof value === 'string' && value) labels.add(value); };
+  const unavailable = () => { throw new CommandError('observation_unavailable', `A valid ${provider} foreground tree is required.`); };
+  if (rawTree?.ok === false) unavailable();
+  if (provider === 'native') {
+    const window = foregroundNativeWindow(rawTree);
+    if (!window?.root || explicitlyHidden(window.root) || (window.root.visible !== true && window.root.effectiveVisible !== true)) unavailable();
+    const visit = node => {
+      if (!node || explicitlyHidden(node) || (node.visible !== true && node.effectiveVisible !== true)) return;
+      add(node.text); add(node.contentDescription);
+      for (const child of node.children || []) visit(child);
+    };
+    visit(window.root);
+  } else if (provider === 'flutter') {
+    if (!Array.isArray(rawTree?.nodes)) unavailable();
+    for (const node of rawTree.nodes) {
+      if (node.visible === false || node.offstage === true) continue;
+      add(node.text); add(node.value); add(node.label);
+    }
+  } else {
+    if (typeof rawTree !== 'string' || !looksLikeAndroidUiHierarchyXml(rawTree)) unavailable();
+    const hidden = [];
+    visitAndroidUiHierarchyTags(rawTree, ({ tag, closing, selfClosing }) => {
+      if (closing) { hidden.pop(); return; }
+      const attrs = parseXmlAttributes(tag);
+      const isHidden = hidden.at(-1) || attrs['visible-to-user'] === 'false' || attrs.displayed === 'false';
+      if (!isHidden) { add(attrs.text); add(attrs['content-desc']); }
+      if (!selfClosing) hidden.push(isHidden);
+    });
+  }
+  return labels;
+}
+
+function checkTextConditions(labels, activity, conditions) {
+  const missing = conditions.present.filter(value => !labels.has(value));
+  const unexpected = conditions.absent.filter(value => labels.has(value));
+  const activityMatches = !conditions.requireActivity || activity === conditions.requireActivity;
+  return { ok: !missing.length && !unexpected.length && activityMatches, missing, unexpected, activity, activityMatches };
+}
+
+async function waitForText({ options, readTree, readForeground }) {
+  const conditions = validateTextConditions(options);
+  const timeoutMs = options.timeoutMs ?? 10000;
+  const intervalMs = options.intervalMs ?? 500;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 1) throw new CommandError('invalid_argument', 'intervalMs must be a positive integer.', { field: 'intervalMs' });
+  const deadline = Date.now() + timeoutMs;
+  let lastCheck = null;
+  try {
+    return await runExecution({ timeoutMs, mutation: false }, async () => {
+      for (;;) {
+        const foreground = await readForeground();
+        checkExecution();
+        if (!foreground?.ok) throw new CommandError('foreground_probe_failed', 'The foreground app could not be verified.');
+        if (options.packageName && foreground.packageName !== options.packageName) throw new CommandError('foreground_package_mismatch', 'The foreground app differs from packageName.');
+        let nativeTree;
+        let successfulReads = 0;
+        const failures = [];
+        for (const provider of conditions.provider === 'auto' ? ['native', 'flutter', 'uia'] : [conditions.provider]) {
+          try {
+            if (provider === 'flutter') {
+              nativeTree ??= await readTree('native');
+              if (foregroundNativeWindow(nativeTree)?.type !== 'activity') throw new CommandError('native_foreground_blocks_flutter', 'A native foreground window covers Flutter.');
+            }
+            const rawTree = provider === 'native' ? (nativeTree = await readTree(provider)) : await readTree(provider);
+            const labels = visibleLabels(provider, rawTree);
+            const after = await readForeground();
+            checkExecution();
+            if (!after?.ok || after.component !== foreground.component || after.packageName !== foreground.packageName) {
+              throw new CommandError('foreground_changed_during_observation', 'The foreground changed while reading text.');
+            }
+            successfulReads++;
+            lastCheck = { ...checkTextConditions(labels, after.activity, conditions), provider, observedAtMs: Date.now() };
+            if (lastCheck.ok) return { ok: true, conditions, matched: lastCheck };
+          } catch (error) {
+            checkExecution();
+            failures.push({ provider, error: error.code || 'observation_unavailable', message: String(error.message).split('\n')[0] });
+          }
+        }
+        if (!successfulReads) return { ok: false, error: 'observation_unavailable', dispatched: false, ambiguous: false, failures };
+        await executionSleep(Math.min(intervalMs, Math.max(1, deadline - Date.now())));
+      }
+    });
+  } catch (error) {
+    if (error.code !== 'deadline_exceeded') throw error;
+    return { ok: false, error: 'deadline_exceeded', dispatched: false, ambiguous: false, timeoutMs, conditions, lastCheck };
+  }
+}
+
+module.exports = { validateTextConditions, visibleLabels, checkTextConditions, waitForText };

package/bin/shared-kernel/uia-execution.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const { CommandError } = require('../command-errors');
+const { createUiaRuntimePort } = require('./uia-runtime-port');
+const { runDeviceEffect, isDeviceSettlementDurable, completeDeviceAcknowledgement } = require('./device-mutation-lease');
+const { currentExecution, runExecution, checkExecution, withoutExecution, executionSleep } = require('./execution-scope');
+const protocol = require('./uia-protocol');
+
+function matchingPending(response, identity) {
+  return response?.schemaVersion === protocol.schema && response.settled === false && response.ok === false
+    && response.dispatched === null && response.ambiguous === true
+    && ['bootId', 'runtimeEpoch', 'actionId', 'requestSha256'].every(key => response[key] === identity[key])
+    && ['prepared', 'queued', 'admitted', 'unknown', 'terminal'].includes(response.phase)
+    && typeof response.error === 'string' && response.error.length > 0;
+}
+
+async function executeUiaAction({ adb, serial, binding, actionId, timeoutMs = 10000, clickPolicy = 'nearest_clickable_ancestor',
+  port = createUiaRuntimePort({ adb, serial, timeoutMs }) } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)
+    throw new CommandError('invalid_argument', 'UIA timeoutMs must be a positive integer in milliseconds.', { dispatched: false, ambiguous: false });
+  if (!currentExecution()) return runExecution({ timeoutMs, mutation: true },
+    () => executeUiaAction({ adb, serial, binding, actionId, timeoutMs, clickPolicy, port }));
+  checkExecution();
+  const candidate = protocol.actionRequest(binding, { actionId, timeoutMs: Math.min(timeoutMs, 60000), clickPolicy });
+  let connection;
+  try {
+    connection = await port.ensure();
+    if (connection.peer.bootId !== binding?.bootId || connection.peer.runtimeEpoch !== binding?.runtimeEpoch) {
+      throw new CommandError('uia_stale_runtime', 'The observed UIA runtime has changed. Observe the target again.');
+    }
+    if (connection.status.count === connection.status.capacity) {
+      throw new CommandError('uia_action_capacity_exhausted', 'The UIA action journal is full. Reconcile pending actions and retain their completion receipts; a new observation rotates only a fully acknowledged session.');
+    }
+  } catch (error) {
+    return { ok: false, error: error.code || 'uia_runtime_unavailable', message: error.message, dispatched: false, ambiguous: false };
+  }
+  checkExecution();
+  const remaining = Math.floor(Math.min(timeoutMs, currentExecution().deadlineMs - Date.now(), 60000));
+  if (remaining < 1) throw new CommandError('deadline_exceeded', 'The UIA execution budget expired before preparation.', { dispatched: false, ambiguous: false });
+  const prepared = protocol.actionRequest(binding, { actionId: candidate.request.actionId, timeoutMs: remaining, clickPolicy });
+  const { request, requestJson, requestSha256 } = prepared;
+  const identity = { kind: 'uia-node', schemaVersion: protocol.schema, actionId: request.actionId,
+    bootId: request.bootId, runtimeEpoch: request.runtimeEpoch, requestJson, requestSha256,
+    target: { adb, serial, root: connection.peer.sessionPath.split('/sessions/')[0],
+      sessionPath: connection.peer.sessionPath, dexSha256: connection.peer.dexSha256 } };
+  if (!protocol.validIdentity(identity)) throw new CommandError('invalid_uia_execution_identity', 'The UIA runtime did not yield a valid original action identity.', { dispatched: false, ambiguous: false });
+
+  let terminal;
+  const result = await runDeviceEffect(identity, async () => {
+    let response, failure;
+    try {
+      response = await port.action(connection, 'prepare', identity);
+      if (!protocol.originalReceipt(response, identity)) {
+        if (!matchingPending(response, identity)) throw new CommandError('invalid_uia_execution_receipt', 'UIA preparation did not return the original action identity.');
+        if (response.error !== 'uia_action_pending') throw new CommandError(response.error, 'UIA could not prepare this action durably.');
+        if (response.phase === 'prepared') {
+          checkExecution();
+          response = await port.action(connection, 'start', identity);
+        }
+      }
+      for (;;) {
+        const receipt = protocol.originalReceipt(response, identity);
+        if (receipt) { terminal = response; return { ...receipt, request, executionReceipt: protocol.settlementProof(response, identity) }; }
+        if (!matchingPending(response, identity)) throw new CommandError('invalid_uia_execution_receipt', 'UIA did not return a matching original action state.');
+        if (response.error !== 'uia_action_pending') throw new CommandError(response.error, 'The original UIA action has not completed.');
+        checkExecution();
+        await executionSleep(25);
+        response = await port.action(connection, 'query', identity);
+      }
+    } catch (error) { failure = error; }
+
+    let recovery;
+    try {
+      recovery = await withoutExecution(() => runExecution({ timeoutMs: 5000, mutation: false }, () => port.recover(identity)));
+    } catch (error) { recovery = { ok: false, error: error.code || 'uia_completion_query_failed' }; }
+    const receipt = protocol.originalReceipt(recovery, identity);
+    if (receipt) terminal = recovery;
+    return { ok: false, error: failure.code || 'uia_action_response_lost', message: failure.message,
+      actionId: identity.actionId, bootId: identity.bootId, runtimeEpoch: identity.runtimeEpoch, request,
+      settled: Boolean(receipt), dispatched: receipt?.dispatched ?? null, ambiguous: receipt ? false : true,
+      recovery, executionReceipt: receipt ? protocol.settlementProof(recovery, identity) : null };
+  }, value => value?.executionReceipt || false);
+
+  // Shared ownership commits the proof before the phone may acknowledge it.
+  // A history/acknowledgement failure never changes the already known effect.
+  if (terminal && isDeviceSettlementDurable(result.executionReceipt)) {
+    try {
+      const acknowledgement = await completeDeviceAcknowledgement(result.executionReceipt, () => withoutExecution(() =>
+        runExecution({ timeoutMs: 5000, mutation: false }, () => port.acknowledge(identity, terminal))));
+      result.completionHistory = acknowledgement.history;
+    } catch (error) { result.cleanupError = error.code || 'uia_acknowledgement_failed'; }
+  }
+  return result;
+}
+
+module.exports = { executeUiaAction, matchingPending, ...protocol };