@mobileaidev/ai-app-bridge 0.3.4 → 0.3.6

package/bin/ios-runtime-binding.js

@@ -4,7 +4,7 @@ const { CommandError } = require('./command-errors');
 const { currentExecution } = require('./shared-kernel/execution-scope');
 
 const schemaVersion = 'aab.ios-runtime/v1';
-const sdkCommands = new Set(['ios-status', 'ios-tree', 'ios-logs', 'ios-network', 'ios-state', 'ios-events',
+const sdkCommands = new Set(['ios-ui-observation', 'ios-status', 'ios-tree', 'ios-logs', 'ios-network', 'ios-state', 'ios-events',
   'ios-h5-dom', 'ios-h5-eval', 'ios-h5-click', 'ios-h5-input', 'ios-h5-scroll', 'ios-flutter-tree', 'ios-flutter-nodes', 'ios-flutter-action',
   'ios-tap-flutter', 'ios-input-flutter-text', 'ios-scroll-flutter', 'ios-flutter-back', 'ios-flutter-hide-keyboard']);
 const fields = ['schemaVersion', 'bundleId', 'runtimeEpoch', 'processId', 'port'];

package/bin/ios-wda-startup.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { getHostFactStore } = require('./shared-kernel/host-fact-store');
+
+const initializationFailure = 'The test runner failed to initialize for UI testing. (Underlying Error: Timed out while enabling automation mode.)';
+const digest = value => createHash('sha256').update(value).digest('hex');
+
+function initializationProof(summary, invocation, deviceId, completedAtMs = Date.now()) {
+  const args = invocation?.arguments;
+  if (!Array.isArray(args) || args[args.indexOf('-destination') + 1] !== `id=${deviceId}`
+      || args[args.indexOf('-scheme') + 1] !== 'WebDriverAgentRunner' || !args.includes('test-without-building')
+      || summary?.result !== 'Failed' || summary.totalTestCount !== 1 || summary.failedTests !== 1
+      || summary.passedTests !== 0 || summary.skippedTests !== 0 || summary.expectedFailures !== 0
+      || summary.devicesAndConfigurations?.length !== 1 || summary.devicesAndConfigurations[0].device?.deviceId !== deviceId
+      || summary.testFailures?.length !== 1 || summary.testFailures[0].targetName !== 'WebDriverAgentRunner'
+      || summary.testFailures[0].failureText !== initializationFailure
+      || !Number.isFinite(summary.startTime) || !Number.isFinite(summary.finishTime)
+      || summary.startTime * 1000 < invocation.startedAtMs || summary.finishTime < summary.startTime
+      || summary.finishTime * 1000 > completedAtMs) return null;
+  return { kind: 'ios-wda-start', settled: true, dispatched: true, ambiguous: false, invocation,
+    outcome: { ok: false, error: 'ios_wda_automation_confirmation_required', settled: true, dispatched: true, ambiguous: false,
+      message: 'XCTest ended before UI test initialization completed. Confirm Enable UI Automation on the iPhone, then explicitly run ios-setup again.' },
+    summary, summarySha256: digest(JSON.stringify(summary)) };
+}
+
+// Old setup markers lack a test invocation. Recovery requires the original
+// public response AND its retained Host action, not a newly supplied exit code.
+async function recoverLegacySetup({ pending, owner, resultPath, device, readSummary, readAction }) {
+  if (pending.command !== 'ios-setup' || pending.invocation || !resultPath) return null;
+  const bytes = await fs.promises.readFile(resultPath);
+  if (bytes.length > 4 * 1024 * 1024) return null;
+  const envelope = JSON.parse(bytes.toString('utf8'));
+  const result = envelope.kind === 'json' ? envelope.value : envelope;
+  const feedback = result?._feedback, times = feedback?.timings;
+  const evidence = feedback?.evidence?.filter(item => item.partition === 'action' && item.stored === true);
+  const steps = result?.steps?.filter(item => item.name === 'start-wda');
+  if (result?.error !== 'ios_wda_xcodebuild_exited' || result.device?.udid !== device.udid
+      || feedback?.dispatch?.command !== 'ios-setup' || feedback.target?.bundleId !== pending.target.bundleId
+      || evidence?.length !== 1 || !evidence[0].actionId?.startsWith(`host-action-${owner?.pid}-`)
+      || !Number.isSafeInteger(times?.startedAtMs) || !Number.isSafeInteger(times?.completedAtMs)
+      || times.startedAtMs > owner.acquiredAtMs || owner.acquiredAtMs > pending.preparedAtMs
+      || pending.preparedAtMs > times.completedAtMs || steps?.length !== 1
+      || steps[0].phase !== 'device-test' || steps[0].exitCode !== 65) return null;
+  const page = (readAction || (actionId => getHostFactStore().read({ partitions: ['action'], actionId, limit: 2 })))(evidence[0].actionId);
+  const fact = page.items?.[0];
+  if (page.ok !== true || page.items?.length !== 1 || fact.globalSeq !== evidence[0].globalSeq
+      || fact.payload?.command !== 'ios-setup' || fact.payload.status !== 'failed' || fact.payload.args?.startWda !== true
+      || fact.payload.args.deviceId !== result.device.identifier || fact.payload.args.bundleId !== pending.target.bundleId
+      || fact.payload.result?.error !== result.error || fact.timestamps?.occurredAtMs !== times.startedAtMs
+      || fact.timestamps.observedAtMs !== times.completedAtMs) return null;
+  const project = steps[0].prepared?.projectPath;
+  if (typeof project !== 'string' || path.basename(project) !== 'WebDriverAgent.xcodeproj') return null;
+  const directory = path.dirname(path.dirname(project));
+  if (steps[0].logFile !== path.join(directory, 'xcodebuild.log')) return null;
+  const resultsDirectory = path.join(directory, 'build', 'Logs', 'Test');
+  const bundles = (await fs.promises.readdir(resultsDirectory)).filter(name => name.endsWith('.xcresult'));
+  if (bundles.length !== 1) return null;
+  const invocation = { arguments: ['-project', project, '-scheme', 'WebDriverAgentRunner', '-destination', `id=${device.udid}`, 'test-without-building'],
+    resultBundlePath: path.join(resultsDirectory, bundles[0]), startedAtMs: pending.preparedAtMs };
+  const proof = initializationProof(await readSummary(invocation.resultBundlePath), invocation, device.udid, times.completedAtMs);
+  return proof && { ...proof, originalSetup: { pendingId: pending.id, actionId: fact.actionId,
+    globalSeq: fact.globalSeq, resultPath: path.resolve(resultPath), responseSha256: digest(bytes) } };
+}
+
+module.exports = { initializationProof, recoverLegacySetup };

package/bin/runtime-directory.js

@@ -51,7 +51,7 @@ function runtimeLocation() {
 
 function runtimeIdentity(location = runtimeLocation()) {
   const names = ['AI_APP_BRIDGE_ADB_TIMEOUT_MS', 'AI_APP_BRIDGE_DEVICECTL', 'AI_APP_BRIDGE_FACT_CACHE',
-    'AI_APP_BRIDGE_IOS_TEAM_ID', 'AI_APP_BRIDGE_PYTHON', 'ANDROID_HOME', 'ANDROID_SDK_ROOT', 'DEVELOPMENT_TEAM', 'DEVELOPER_DIR', 'XCODEBUILD'];
+    'AI_APP_BRIDGE_IOS_TEAM_ID', 'AI_APP_BRIDGE_PYTHON', 'AI_APP_BRIDGE_EXECUTOR_HOME', 'ANDROID_HOME', 'ANDROID_SDK_ROOT', 'DEVELOPMENT_TEAM', 'DEVELOPER_DIR', 'XCODEBUILD'];
   const config = { facts: location.facts, profile: location.profile, ownership: canonicalPath(ownershipDirectory()),
     adb: executablePath(process.env.ADB || 'adb') ?? { unavailable: process.env.ADB || 'adb' },
     environment: Object.fromEntries(names.map(name => [name, process.env[name] ?? null])) };

package/bin/shared-kernel/device-ownership-recovery.js

@@ -19,6 +19,14 @@ async function deviceOwnership(args, { lease = getProcessDeviceMutationLease(),
   const recovered = await lease.reconcile(args.serial, async pending => {
     if (args.operation === 'cancel-install' && (pending.kind !== 'android-install' || pending.actionId !== args.actionId))
       return { settled: false, error: 'install_action_mismatch', actionId: pending.actionId };
+    if (pending.kind === 'android-test-executor') {
+      try { return await require('../executors/android-host').recoverAndroidExecutor(pending); }
+      catch (error) { return { settled: false, error: error.code || 'executor_completion_query_failed', message: error.message }; }
+    }
+    if (pending.kind === 'flutter-test-executor') {
+      try { return await require('../executors/flutter-host').recoverFlutterExecutor(pending); }
+      catch (error) { return { settled: false, error: error.code || 'executor_completion_query_failed', message: error.message }; }
+    }
     if (pending.kind === 'uia-node') {
       if (!uiaProtocol.validIdentity(pending) || pending.target.serial !== args.serial) return { settled: false, error: 'invalid_uia_execution_identity' };
       try {
@@ -100,6 +108,11 @@ async function deviceOwnership(args, { lease = getProcessDeviceMutationLease(),
       if (cleanup.errors.length) (recovered.cleanupErrors ||= []).push(...cleanup.errors);
     }
   }
+  if (args.operation === 'cancel-install' && recovered.ok && recovered.recovered === false) {
+    return { ...recovered, ok: false, error: 'install_action_not_pending', actionId: args.actionId,
+      message: 'No pending installation matches this action. Nothing was cancelled; read the original installation result to determine its outcome.',
+      dispatched: false, ambiguous: false };
+  }
   return recovered;
 }
 

package/bin/shared-kernel/native-target.js

@@ -2,9 +2,8 @@
 
 const { checkExecution } = require('./execution-scope');
 
-// WindowInspector retains other Activities during transitions, and focus can
-// lag the current Activity. Select its window group, including dialogs/popups
-// sharing its focus owner. Older trees keep their window-order semantics.
+// The SDK owns Android window topology and publishes its foreground decision.
+// Focus ownership is an input permission, not an Activity/window relationship.
 
 function visible(node) {
   return node && (node.effectiveVisible === true || node.visible === true)
@@ -21,12 +20,13 @@ function foregroundNativeWindow(rawTree) {
   if (!rawTree || typeof rawTree !== 'object') return null;
   const windows = Array.isArray(rawTree.windows) ? rawTree.windows : [];
   if (windows.length) {
-    const activity = windows.findLast(item => item?.activityDecor === true && Object.hasOwn(item, 'focusOwnerWindowId'));
-    const index = windows.findLastIndex(item => !explicitlyHidden(item?.root)
-      && (!activity || item === activity || !Object.hasOwn(item || {}, 'focusOwnerWindowId')
-        || item.focusOwnerWindowId !== null && item.focusOwnerWindowId === activity.focusOwnerWindowId));
-    if (index < 0) return null;
+    const id = rawTree.foregroundWindowId;
+    if (typeof id !== 'string' || !id.trim()) return null;
+    const matches = windows.map((window, index) => window?.windowId === id ? index : -1).filter(index => index >= 0);
+    if (matches.length !== 1) return null;
+    const [index] = matches;
     const window = windows[index];
+    if (explicitlyHidden(window?.root)) return null;
     return { index, root: window?.root, type: window?.type, windowId: window?.windowId,
       bounds: window && Object.hasOwn(window, 'bounds') ? window.bounds : window?.root?.bounds };
   }
@@ -45,6 +45,9 @@ function explicitlyHidden(node) {
 
 function selectNativeNode(rawTree, spec, editable) {
   const reject = (error) => ({ ok: false, error, dispatched: false });
+  if (rawTree?.windows?.length && (typeof rawTree.foregroundWindowId !== 'string' || !rawTree.foregroundWindowId.trim())) {
+    return reject('native_window_metadata_unavailable');
+  }
   const window = nativeWindow(rawTree);
   if (!window) return reject('visible_observed_window_required');
   const selector = spec.selector || (typeof spec.text === 'string' ? { text: spec.text } : null);

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

@@ -90,7 +90,7 @@ function actionRequest(binding, { timeoutMs, actionId = randomUUID(), clickPolic
 function validDescriptor(value, root) {
   return record(value) && validRoot(root) && value.schemaVersion === runtimeSchema
     && isUuid(value.bootId) && isUuid(value.runtimeEpoch) && isHash(value.dexSha256)
-    && Number.isSafeInteger(value.pid) && value.pid > 0 && Number.isSafeInteger(value.apiLevel) && value.apiLevel >= 33
+    && Number.isSafeInteger(value.pid) && value.pid > 0 && Number.isSafeInteger(value.apiLevel) && value.apiLevel >= 25
     && value.socketName === `aab-uia-${value.runtimeEpoch}` && isHash(value.token)
     && value.sessionPath === `${root}/sessions/${value.runtimeEpoch}` && typeof value.running === 'boolean';
 }

package/bin/shared-kernel/uia-runtime-port.js

@@ -37,7 +37,7 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
       manifest = JSON.parse(fs.readFileSync(path.join(bundleDirectory, 'manifest.json'), 'utf8'));
       bytes = fs.readFileSync(path.join(bundleDirectory, 'ai-app-bridge-uia.jar'));
     } catch (error) { throw failure('uia_runtime_bundle_unavailable', 'The installed CLI has no complete UIA runtime bundle.', { cause: error.code }); }
-    if (manifest?.schemaVersion !== 'aab.uia.bundle.v1' || manifest.mainClass !== mainClass || manifest.minApi !== 33
+    if (manifest?.schemaVersion !== 'aab.uia.bundle.v1' || manifest.mainClass !== mainClass || manifest.minApi !== 25
       || manifest.artifact !== 'ai-app-bridge-uia.jar' || bytes.length > 2 * 1024 * 1024 || protocol.digest(bytes) !== manifest.sha256) {
       throw failure('uia_runtime_bundle_invalid', 'The UIA runtime artifact does not match its bundle manifest.');
     }
@@ -133,7 +133,7 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
 
   async function installAsset(asset) {
     const level = await shell('getprop ro.build.version.sdk');
-    if (!/^[0-9]+$/.test(level) || Number(level) < 33) throw failure('uia_android_api_33_required', 'UIA node execution requires Android API 33 or newer.', { apiLevel: level });
+    if (!/^[0-9]+$/.test(level) || Number(level) < 25) throw failure('uia_android_api_25_required', 'UIA node execution requires Android API 25 or newer.', { apiLevel: level });
     const destination = `${root}/runtime-${asset.manifest.sha256}.jar`;
     await shell(`umask 077\nmkdir -p ${quote(root)} && chmod 700 ${quote(root)}`);
     const existingHash = await shell(`if [ -f ${quote(destination)} ]; then ${sha256FileScript(destination)}; else printf '%s' null; fi`);
@@ -205,6 +205,7 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
   }
 
   async function ensureLocked(rotate) {
+    await require('../executors/automation-owner').assertAvailable(serial);
     const asset = bundle();
     const previous = await readJson(`${root}/runtime.json`);
     let peer = previous === null ? null : descriptor(previous);
@@ -293,6 +294,40 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
   }
 
   return {
+    async withInstrumentation(descriptorFile, start) {
+      return withConnectionLock(async () => {
+        const automation = require('../executors/automation-owner');
+        await automation.assertAvailable(serial);
+        const value = await readJson(`${root}/runtime.json`);
+        if (value !== null) {
+          const peer = descriptor(value);
+          if (peer.running) {
+            const connection = await connect(peer);
+            const status = await statusOf(connection);
+            if (status.pending !== 0 || status.acknowledged !== status.count || status.activeActionId !== null)
+              throw failure('uia_runtime_pending_actions', 'Settle and acknowledge the original UIA actions before opening instrumentation.');
+            await stopRuntime(connection);
+          }
+        }
+        const claim = automation.claim(serial, descriptorFile);
+        try {
+          const result = await start();
+          if (result?.ok === false && result.dispatched === false && result.ambiguous === false) automation.release(serial, claim.sessionId);
+          return result;
+        } catch (error) {
+          if (error.dispatched === false && error.ambiguous === false) automation.release(serial, claim.sessionId);
+          throw error;
+        }
+      });
+    },
+    async releaseInstrumentation(sessionId) {
+      return withConnectionLock(async () => {
+        const automation = require('../executors/automation-owner');
+        const owner = automation.owner(serial);
+        if (owner && owner.sessionId !== sessionId) throw failure('executor_automation_owner_changed', 'Another test session owns UiAutomation.');
+        await automation.assertAvailable(serial);
+      });
+    },
     ensure, post,
     async observe() {
       const connection = await withConnectionLock(() => ensureLocked(true));
@@ -342,6 +377,7 @@ function createUiaRuntimePort({ adb, serial, timeoutMs = 10000, root = protocol.
       return withConnectionLock(async () => {
         const value = await readJson(`${root}/runtime.json`);
         if (operation === 'start') {
+          await require('../executors/automation-owner').assertAvailable(serial);
           const asset = bundle(), destination = await installAsset(asset);
           const ownerRaw = await shell(`CLASSPATH=${quote(destination)} app_process /system/bin ${mainClass} ${quote(root)} ${asset.manifest.sha256} owner-status`);
           let owner;

package/bin/ui-observation.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const commands = new Set(['ui-observation', 'ios-ui-observation', 'web-ui-observation']);
+
+function schema(command, optionTypes) {
+  const target = command === 'web-ui-observation' ? ['sessionId', 'runtimeEpoch', 'targetId', 'timeoutMs']
+    : command === 'ios-ui-observation' ? ['deviceId', 'bundleId', 'runtimeUrl', 'iosHost', 'iosPort', 'timeoutMs', 'devicectl']
+      : ['serial', 'packageName', 'port', 'adb', 'timeoutMs'];
+  const properties = Object.fromEntries(target.map(name => [name, optionTypes[name]]));
+  Object.assign(properties, { operation: { enum: ['start', 'status', 'stop'] },
+    durationMs: { type: 'integer', minimum: 100, maximum: 5000 }, leaseId: { type: 'string', minLength: 1, maxLength: 256 } });
+  if (command !== 'web-ui-observation') properties.provider = { enum: ['native', 'flutter'], default: 'native' };
+  return { type: 'object', additionalProperties: false, properties,
+    required: ['operation', ...(command === 'web-ui-observation' ? ['sessionId', 'runtimeEpoch'] : command === 'ios-ui-observation' ? ['deviceId', 'bundleId'] : ['packageName'])],
+    oneOf: [
+      { properties: { operation: { const: 'start' }, leaseId: false }, required: ['durationMs'] },
+      { properties: { operation: { const: 'stop' }, durationMs: false }, required: ['leaseId'] },
+      { properties: { operation: { const: 'status' }, durationMs: false, leaseId: false } },
+    ] };
+}
+
+function request(args) {
+  return { operation: args.operation,
+    ...(args.operation === 'start' ? { durationMs: args.durationMs } : {}),
+    ...(args.operation === 'stop' ? { leaseId: args.leaseId } : {}) };
+}
+function path(args) { return args.provider === 'flutter' ? '/v1/flutter/observation' : '/v1/ui/observation'; }
+
+module.exports = { commands, schema, request, path };

package/bin/web-provider.js

@@ -43,6 +43,9 @@ class WebBridgeProvider {
           return { ok: true, session: this.sessionSummary(session), ownership: this.owner().status(sessionKey(args.sessionId)) };
         }
         case 'web-execution': return await this.executionControl(args);
+        case 'web-ui-observation': return await this.request(this.connected(args), 'read', {
+          name: 'uiObservation', args: require('./ui-observation').request(args),
+        }, args.timeoutMs ?? 5000);
         case 'web-dom': return args.history === true ? await this.captureResponse(args, 'dom') : await this.dom(args);
         case 'web-logs': return await this.captureResponse(args, 'logs');
         case 'web-network': return await this.captureResponse(args, 'network');
@@ -256,7 +259,9 @@ class WebBridgeProvider {
       this.pendingCommands.set(requestId, { socket, binding, type, payload, fail, resolve: result => end(null, result) });
       scope?.signal.addEventListener('abort', abort, { once: true });
       if (scope?.signal.aborted) { abort(); return; }
-      sent = true; markExecutionDispatched();
+      sent = true;
+      // Acquiring evidence must not mark the enclosing UI action as dispatched.
+      if (!(type === 'read' && payload.name === 'uiObservation')) markExecutionDispatched();
       try { socket.send(wire, error => { if (error && this.pendingCommands.has(requestId)) fail('web_command_transport_lost'); }); }
       catch { fail('web_command_transport_lost'); }
     });

package/docs/COMMAND_CONTRACT.md

@@ -930,7 +930,7 @@ a mutation already running at timeout returns an ambiguous outcome. These checks
 do not make app touch handlers or business outcomes transactional.
 Explicit coordinate commands retain their primitive role.
 
-UIA observation and semantic clicks require Android API 33 or newer and the
+UIA observation and semantic clicks require Android API 25 or newer and the
 bundled, hash-verified `runtime/uia` module. `uia-tree` opens or reuses one
 UiAutomation connection on the explicit device. XML snapshots carry boot,
 runtime and snapshot IDs; each node has an opaque reference. Ordinary UIA text
@@ -938,6 +938,12 @@ commands, Intent (including installer and permission choices), and JavaScript /
 Python Script calls send that reference and their original action ID to the
 same runtime. They do not convert text matches into physical coordinates.
 
+API 25–32 use the process accessibility cache; API 33+ uses its connection
+cache. Before API 30, Android exposes only the default-display window inventory.
+All versions retain durable file and directory synchronization and original
+Binder callbacks. Device validation covers API 25, 30 and 36; this is not a
+claim that every vendor framework implementation has been tested.
+
 The runtime checks the focused default-display window, unique selector match,
 node attributes and clickable ancestor before one node action. Its guarantee
 is `same_connection_node_and_reobserved_attributes`, not a transaction across
@@ -966,6 +972,10 @@ ownership with actions. Stop requires committed terminal actions. Explicit start
 checks the phone's OS-managed process lock. A dead process can be reopened only
 after the new process acquires that lock and audits all original action records;
 any nonterminal or corrupt record blocks reopening, including after a reboot.
+The 0.3.5 audit compares a nodeRef selector with the receipt's `binding.ref`;
+the target attributes do not contain a `nodeRef` field. A successful audit may
+retire acknowledged sessions and publish a new epoch. It does not resurrect
+the old process or authorize replay of old actions.
 An HTTP timeout or a stale `running` descriptor does not authorize replacement.
 Authentication tokens
 stay in private phone descriptors and are absent from public status and Host
@@ -1104,7 +1114,18 @@ metadata, not the raw transport bytes. Settlement proves the recorded execution
 it does not turn an ambiguous action or unverified business assertion into a pass.
 
 Native Intent `longPress`, `swipe` and `scroll` use `/v1/action/gesture-target`.
-The top visible SDK window owns pointer selection. A touchable, non-focusable
+The SDK selects the top visible window belonging to the current Activity on its
+display. Application windows use `WindowManager.LayoutParams.token` for Activity
+ownership; subwindows resolve that token through their parent window. Focus is
+not evidence of Activity ownership. A missing token, unresolved parent or unknown
+window type blocks selection with `native_window_metadata_unavailable`.
+Native tree snapshots publish this decision as `foregroundWindowId`, referring to
+exactly one entry in `windows`. Host summaries and semantic selection consume
+that identity, and SDK semantic, coordinate, gesture and H5 execution use the same
+window policy. Native window snapshots without this field require an updated SDK;
+Host does not reconstruct the decision from focus or array order.
+
+A touchable, non-focusable
 popup can use its focused owner with the same application window token; the SDK
 does not select a background window when the popup blocks an action. Native/H5
 window selection shares this rule. Native window observation carries
@@ -1600,9 +1621,59 @@ explicit state assertions, or request Agent help through `ctx.askAgent`.
 
 ### Android 安装超时后的显式取消
 
+`freeze-app` 使用 SIGSTOP 暂停整个 App 进程，包括 SDK HTTP 服务；冻结期间的
+`tree`、`status` 超时是预期行为。它不是只暂停业务 UI。先完成需要的读取，再冻结；
+后续 SDK 验证前必须 `thaw-app`，并重新确认可读。
+
 `device-ownership status` 返回原安装的 `actionId`。若原 commit 回执因 OEM 确认页丢失，
 可用 `device-ownership --operation cancel-install --serial SERIAL --action-id ORIGINAL_ACTION_ID`。
 该命令只对保留的原 PM session 执行 abandon，先持久保存取消任务身份，再派发；
 重连后 `reconcile` 可读取同一任务的原回执。明确成功才解除该安装的设备占用。
 `phase: session-abandoned` 的 `requestSucceeded: null` 表示原安装结果未被推断，
 已经安装的 APK 不会回滚。取消按钮、等待超时或 Host 进程退出本身仍不是完成证据。
+没有待处理安装时返回 `install_action_not_pending`、`recovered:false` 和
+`dispatched:false`。这同时适用于未知 actionId 和已经结算的安装；是否安装成功应读取
+原操作结果。未抓住安装中途的取消不能当作 PM abandon 验证。
+
+### iOS 设备连接与原始失败对账
+
+`devicectl list devices` 可以返回休眠隧道快照。`ios-devices` 对唯一或显式选择的未就绪
+设备执行只读 `device info details`，核对 identifier/UDID 后使用当前隧道和 DDI 状态；
+`connectionProbe` 保留结果。多设备未选择时不会唤醒任意一台。`ios-doctor` 的
+`deviceConnected` 指开发者隧道可用，USB 配对与传输方式另见 selectedDevice。
+
+`ios-execution reconcile` 可以识别原 launch 的 CoreDevice 4016 回执：要求精确调用、
+失败 outcome、完整请求状态以及空的可用状态，且没有启动 result。它是已结算的启动前
+拒绝；一般超时、丢连接和不匹配的 JSON 仍不能解除所有权。
+
+### WDA startup outcome recovery
+
+`ios-setup --start-wda true` records the exact XCTest invocation and result bundle before starting the device test. A completed XCTest failure that explicitly says UI test initialization timed out while enabling automation is a settled failed startup (`ios_wda_automation_confirmation_required`). The Runner launch was dispatched; this does not undo its installation. Confirm Enable UI Automation on the device, then explicitly run setup again.
+
+`ios-execution --operation reconcile --device-id DEVICE` reads the original result bundle after an interrupted Host. For a legacy generic `ios-setup` marker, supply `--setup-result-path ORIGINAL_RESPONSE.json`: recovery requires the original CLI JSON response (or its unwrapped value), its matching retained Host action in the current FactStore, the same device and startup interval, and the original XCTest bundle identified by that response. Missing, mismatched, or generic test failures remain unresolved. This option is accepted only for SDK/command reconciliation, never action cancellation or WDA session recovery. Lock files and original evidence are retained.
+
+### Bounded SDK UI observation
+
+`ui-observation`, `ios-ui-observation` and `web-ui-observation` expose
+`start`, `status` and `stop`. Start requires `durationMs` in 100–5000; stop
+requires the returned `leaseId`. Android/iOS accept `provider: native|flutter`.
+The capability is available to JS and Python Script under `capture.read`.
+There is no unbounded lease, automatic renewal or activation at SDK startup.
+Closing/reopening a window establishes a new baseline; an idle interval is not
+evidence of an unchanged UI. Lifecycle and explicit business captures remain
+independent of heavy UI observation.
+
+Native and Flutter controls use `/v1/ui/observation` and
+`/v1/flutter/observation`. The response schema is `aab.ui-observation/v1`.
+`GET /v1/flutter/snapshot` explicitly pulls fresh Dart UI state. Flutter tree,
+node and selection commands use it. `GET /v1/status` does not pull a Flutter
+tree or publish cached layout as current UI. Query a provider's observation
+command for its live lease state. These endpoints require rebuilt SDKs;
+installing a new CLI cannot patch an installed application's old SDK.
+
+Ordinary CLI/MCP `feedback=full` opens a window before the action and releases
+it in finally. If observation is unavailable, the action is rejected before
+dispatch; acquiring evidence does not mark the enclosing UI action dispatched.
+Launch retains its independent system feedback path. Script/Intent bypass this
+feedback wrapper and explicitly request windows only when their evidence needs
+them. SDK/page expiry handles a Host that disappears without sending stop.

package/docs/INTENT_FOREGROUND.md

@@ -29,7 +29,7 @@ choosing any action. The Host does not retry the read or substitute a provider.
 
 The summary contains `provider` and `foreground` (`packageName`, `activity`, `component`, probe source and timestamps). Observation, decision, dispatch marker and receipt records preserve that route. The original `target` continues to identify the business operation and its app capture streams. System UIA observations do not imply that system-app network/state/event capture is available.
 
-Actions inherit the provider of their committed observation. An explicit conflicting provider is rejected. Before dispatch, the adapter checks the foreground component again; a changed component returns `reobserve_required` without dispatching a tap. Exact UIA taps use the API 33+ phone node runtime. Its `uia-node` execution receipt binds the Intent action ID, original request hash, runtime epoch, node/window attributes and original callback. The selected node is revalidated on the same automation connection before dispatch. A callback still requires a fresh observation and business checks; it does not create system-app SDK events.
+Actions inherit the provider of their committed observation. An explicit conflicting provider is rejected. Before dispatch, the adapter checks the foreground component again; a changed component returns `reobserve_required` without dispatching a tap. Exact UIA taps use the API 25+ phone node runtime. Its `uia-node` execution receipt binds the Intent action ID, original request hash, runtime epoch, node/window attributes and original callback. The selected node is revalidated on the same automation connection before dispatch. A callback still requires a fresh observation and business checks; it does not create system-app SDK events.
 
 Device-scoped physical taps remain managed Android shell input. Cancellation
 and recovery follow the selected executor's admission and completion contract.

package/docs/OPTIONAL_EXECUTORS.md

@@ -0,0 +1,182 @@
+# Optional UI executors (0.3.6)
+
+Bridge keeps its existing SDK paths and exposes optional executors through `capabilities`, `run`, and JavaScript/Python Script. Select an executor explicitly. No command silently changes a touch into a setter, switches framework after failure, or repeats an uncertain action.
+
+## What is installed
+
+| Capability | Dependency location | Integration requirement |
+| --- | --- | --- |
+| Android UI Automator / Espresso | Application **androidTest** dependencies and its generated test APK | Small precompiled test entry; matching installed application and test packages |
+| Android WebView H5 | Optional `ai-app-bridge-test-espresso-web` in androidTest | JavaScript already enabled by the application; explicit WebView and frame selection |
+| Android Compose | Optional `ai-app-bridge-test-compose` in androidTest | Application-matched Compose test runtime and a JUnit rule surrounding the session |
+| Flutter WidgetTester | `ai_app_bridge_test` in **dev_dependencies**, using Flutter SDK test packages | Debug APK built from `integration_test/bridge_test.dart` |
+| Web Playwright | CLI-managed directory outside the page SDK | Explicitly prepare the pinned Playwright package and matching browser |
+| iOS | Existing WDA / XCUITest integration | Existing signing, device and WDA prerequisites; no new iOS executor in this version |
+
+These dependencies are isolated from ordinary production source sets. They are visible in build metadata and diagnostics. They do not disappear from the installation or compatibility requirements. Android does **not** need a separate business App, repository, or Gradle project. The standard test APK is an Android test artifact.
+
+## Android: one entry in the existing application
+
+Add the selected artifacts to the application's `androidTestImplementation` configuration. All Bridge artifacts use the same version:
+
+```kotlin
+android {
+    defaultConfig {
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+}
+dependencies {
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.3.6")
+    // Optional H5 adapter:
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.3.6")
+}
+```
+
+Place this tiny entry in the existing `app/src/androidTest/java/...` directory:
+
+```java
+package example.app;
+import io.github.mobileaidev.aiappbridge.executor.instrumentation.AndroidExecutorTest;
+public final class BridgeSessionTest extends AndroidExecutorTest {}
+```
+
+This is a precompiled, long-running JUnit test. Host passes the session identity, token, Activity and lease as Instrumentation arguments. The test thread executes incoming commands serially. Python/JS scripts do not become Kotlin/Java source and do not require rebuilding for each workflow. You may extend the test's `adapters()` and add ordinary JUnit rules or idling resources. Arbitrary business field reflection and arbitrary existing `@Test` method invocation are not exposed as remote commands.
+
+Opening a session **restarts and instruments the target application**. Install the matching main and test APKs built from this application first:
+
+```sh
+./gradlew :app:assembleDebug :app:assembleDebugAndroidTest
+adb -s DEVICE install -r -t app/build/outputs/apk/debug/app-debug.apk
+adb -s DEVICE install -r -t app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk
+ai-app-bridge android-executor --operation status --serial DEVICE
+ai-app-bridge android-executor --operation open --serial DEVICE \
+  --package-name example.app \
+  --instrumentation example.app.test/androidx.test.runner.AndroidJUnitRunner \
+  --test-class example.app.BridgeSessionTest --activity example.app.MainActivity
+```
+
+Use the actual installed component names returned by `status`. Supply the returned `sessionId` and `runtimeEpoch` to subsequent operations. `observe` requires an `engine` listed in `open.capabilities.adapters`. `act` requires the current `snapshotId` and a `nodeId` from that observation. Changing adapters invalidates the previous snapshot.
+
+The instrumentation artifact includes `uiautomator` and `espresso`. Add H5 in `adapters()` with `adapters.put("espresso-web", new EspressoWebExecutor())`, after obtaining `super.adapters()`. H5 observation accepts `webView: {by:"description",value:"..."}` or `resourceId`, and `framePath: [{name:"..."}]` or `{index:0}` entries. An unspecified WebView must match exactly one WebView. JavaScript is not automatically enabled. `webClick`, `webKeys`, `webClear` and `webScrollIntoView` use WebDriver JavaScript atoms, not Android IME or physical touch. Open Shadow DOM and cross-origin frame support must be checked for the concrete WebView; closed Shadow DOM is not advertised.
+
+## Dependency checks and Compose
+
+Apply `io.github.mobileaidev.aiappbridge.test` from the same Gradle plugin artifact. It only validates resolved dependencies; it adds no UI bytecode instrumentation and does not rewrite versions. With JitPack, map this plugin ID in `pluginManagement.resolutionStrategy.eachPlugin` to `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-gradle-plugin:<requested version>`, as for the existing `io.github.mobileaidev.aiappbridge.android` plugin. Include JitPack, Google Maven and Maven Central in the appropriate repositories.
+
+The initial Android adapter profile is runner **1.7.0**, Espresso / Espresso-Web **3.7.0**, UI Automator **2.4.0**, Java **11**, minSdk **23**, compileSdk **35**. The source build uses AGP **8.9.1** and JDK **17**. This is a supported profile, not a promise that every old Gradle/AGP combination can consume the artifacts.
+
+Compose is optional and its runtime is supplied by the consumer. The initial Compose adapter profile is **1.8.3**. Apply the application's **same Compose BOM** to its main/debug and androidTest dependencies, then add `ui-test-junit4` without an independent version. The plugin rejects a different main/test Compose runtime or an unvalidated adapter profile. It does not upgrade an application's Kotlin, Compose, AGP or compileSdk to make the check pass. An application outside this profile can keep the existing SDK/UI Automator route or provide a separately validated adapter build.
+
+```java
+@Rule public final ComposeTestRule compose =
+    AndroidComposeTestRule_androidKt.createEmptyComposeRule();
+@Override protected Map<String, ExecutorAdapter> adapters() {
+    Map<String, ExecutorAdapter> adapters = super.adapters();
+    adapters.put("compose", new ComposeExecutor(compose));
+    return adapters;
+}
+```
+
+The rule must start **before** Activity/composition creation. The adapter uses automatic test clock advancement and idle frame ticks; animation timing is not wall-clock fidelity. `click` uses Compose touch input; `composeInput`, `composeReplaceText`, `composeClearText`, scroll semantics and `semanticLongClick` are explicit semantics operations. WebView/platform Views and system dialogs require their corresponding adapters. No private Compose field reflection is used by Bridge.
+
+## Flutter
+
+Add `ai_app_bridge_test: 0.3.6` to the application's `dev_dependencies`. The helper takes `flutter_test` and `integration_test` from the **same Flutter SDK** as the application. It is a Dart test helper, not an additional Android plugin with its own AGP/Kotlin versions.
+
+The helper declares Flutter **>=3.41.0** and Dart **>=3.11.0 <4.0.0**. This release was built and exercised with Flutter **3.41.9 on Android API 25** and **3.44.8 on Android API 36**. These are the verified combinations; newer SDK versions still need validation with the application's plugin graph.
+
+```dart
+// integration_test/bridge_test.dart
+import 'package:ai_app_bridge_test/ai_app_bridge_test.dart';
+import 'package:your_app/main.dart' as app;
+void main() => aiAppBridgeTest(app.main);
+```
+
+```sh
+flutter build apk --debug --target integration_test/bridge_test.dart \
+  --dart-define=INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE=false
+adb -s DEVICE install -r -t build/app/outputs/flutter-apk/app-debug.apk
+ai-app-bridge flutter-executor --operation open --serial DEVICE \
+  --package-name example.app --activity example.app.MainActivity
+```
+
+This version supports the standard **Android Flutter embedder**, with its normal application private cache directory. Launch configuration and original receipts use `no_backup/ai-app-bridge-integration`, outside evictable caches. Opening restarts the test-entrypoint app. Closing drains the tester queue and terminates only the original process, identified by boot ID, PID and process start time. The helper uses a fully live frame policy. `tap`, `longPress`, drag/fling, `ensureVisible`, `pageBack`, `pump` and `enterText` are exposed. `enterText` changes Flutter editing state and reads it back; it does not prove native IME input. Flutter platform views, WebView DOM and system dialogs require another applicable provider. Flutter iOS/desktop/web test-host launch is not implemented by this helper.
+
+## Web
+
+```sh
+ai-app-bridge web-executor --operation status --browser chromium
+ai-app-bridge web-executor --operation prepare --browser chromium --timeout-ms 300000
+ai-app-bridge web-executor --operation open --url http://localhost:3000 --browser chromium
+```
+
+The CLI manages exact Playwright **1.63.0**, an included npm lock file and matching browser downloads. `prepare` is explicit; normal SDK usage does not download browsers. Cache keys include the dependency lock digest, OS and CPU architecture. Node **26.3.x** is the verified Host baseline (`>=26.3.0 <27` contract). Browser preparation is serialized and reports failures. `status` separates the static version from actual executable availability.
+
+`observe` returns pages and documents. Pass the observed `targetId`, `frameId` and `documentId` to actions/waits. A navigation during automatic waiting cannot move an old command into the replacement document. Selectors must be unique; role names and text matching are exact. `css` accepts standard CSS syntax, not Playwright selector chains. Actions include click, doubleClick, hover, fill, type, press, check, select, drag, scrollIntoView and upload. Physical `wheel` is not exposed: Playwright's page mouse API cannot bind the event atomically to the observed document. It is never replaced with a synthetic DOM event. Dialogs default to dismiss; an action may explicitly request accept/dismiss. Browser dialogs, popup pages, open Shadow DOM and iframe observations are supported; native OS dialogs and closed Shadow DOM are outside this executor.
+
+Control `text` contains the element's `innerText`, preserving an empty string. It is `null` for elements without `innerText`; hidden `textContent` is not substituted. Each action ID occupies one slot across all pages in the session. Reusing it on another page is rejected with `executor_receipt_identity_mismatch`; changing other action arguments is rejected with `idempotency_conflict`.
+
+## Agent, Python and JS contract
+
+Discover only the operation needed:
+
+```json
+{"command":"android-executor","operation":"act"}
+```
+
+This is a `capabilities` selection, not an action. Execute through the existing `run` tool, or `ctx.call` in Script with **`app.test`** permission. Script targets remain `platform:"android"` for Android/Flutter Android, and `platform:"web"` for browser sessions. Device/package targeting is inherited from the Script target; session identities are explicit inputs.
+
+```javascript
+// Within module.exports.main = async ctx => { ... }
+const reply = await ctx.call('android-executor', {
+  ...ctx.inputs.identity, operation: 'observe', engine: 'espresso'
+});
+if (!reply.ok || !reply.result.ok) throw new Error(JSON.stringify(reply));
+const observation = reply.result.observation;
+const buttons = observation.nodes.filter(n => n.text === 'Submit');
+if (buttons.length !== 1) throw new Error('Expected exactly one Submit button');
+const result = await ctx.call('android-executor', {
+  ...ctx.inputs.identity, operation: 'act', snapshotId: observation.snapshotId,
+  actionId: 'submit-once', action: {type: 'click', nodeId: buttons[0].nodeId}
+});
+if (!result.ok || !result.result.ok) throw new Error(JSON.stringify(result));
+```
+
+```python
+reply = ctx.call('flutter-executor', {**ctx.inputs['identity'], 'operation': 'observe'})
+assert reply['ok'] and reply['result']['ok'], str(reply)
+observation = reply['result']['observation']
+nodes = [n for n in observation['nodes'] if n.get('key') == 'submit']
+assert len(nodes) == 1
+result = ctx.call('flutter-executor', {
+    **ctx.inputs['identity'], 'operation': 'act',
+    'snapshotId': observation['snapshotId'], 'actionId': 'submit-once',
+    'action': {'type': 'tap', 'nodeId': nodes[0]['nodeId']}
+})
+assert result['ok'] and result['result']['ok'], str(result)
+```
+
+An action receipt means the framework call ended, not that a payment/order/business transaction succeeded. Observe again and assert the independent business result. Do not reuse stale snapshots or change an action's mechanism after a failure without a new decision.
+
+## Cancellation, recovery and lifecycle
+
+- One test thread / browser worker serializes UI effects. Native device effects use the shared device ownership contract. UI Automator and the legacy UIA runtime cannot own Android UiAutomation simultaneously; the Host drains and hands over the connection explicitly.
+- `timeoutMs` requests cancellation; it does not prove rollback. Already executing framework work must return its original receipt or the original process must be confirmed ended. An unsettled WebView atom ends the test session. No replacement action starts against an unresolved device effect.
+- The same `actionId` with identical arguments returns its original receipt. A changed request is rejected. An unresolved receipt is never redispatched. Deduplication is session-scoped; it is not universal exactly-once business execution across process loss or new sessions.
+- `receipt` remains readable after normal close. Host restart can recover Android/Flutter descriptors and read retained device records; a lost browser worker's original receipts remain readable, but its live browser session cannot be resumed.
+- Use explicit `close` for normal teardown. Android/Flutter tests also have an idle lease (default 10 minutes, selectable 10 seconds–1 hour). Host loss preserves original state for recovery; it does not erase unresolved ownership. Run `device-ownership --operation reconcile --serial DEVICE` when required by the error. A closed Flutter test may require reconciliation/close to end its original app process.
+- Each session permits at most 4096 action receipts, with bounded request/response and observation sizes. Receipts are retained for audit; storage is not automatically deleted across sessions. Operators must archive/remove closed session artifacts according to their retention policy. Never remove an unresolved session's records to bypass a device lock.
+
+## Performance evidence
+
+On the same API-36 device, sample APK, Activity, counter button and Instrumentation lifetime, 20 effective samples per path (two warmup rounds excluded) alternated Espresso touch and the existing SDK touch. Both included Host persistence and the same Espresso observations before/after every action. Every counter increment was verified.
+
+| Metric (ms) | Espresso | Existing SDK touch |
+| --- | ---: | ---: |
+| Median action | 362 | 314 |
+| Action p95 | 397 | 345 |
+| Median action + before/after observation | 413 | 359 |
+
+This does not establish a general speedup. Startup, dependency preparation, screenshots, model time and CLI process startup are excluded and must be reported separately. Semantics/setter input is a different operation from physical keyboard/IME input; its shorter duration cannot establish an equivalent-interaction speedup.
+
+The version's local verification and publication status are recorded in the repository delivery report. Local artifact checks are separate from public registry publication and real customer workflow acceptance.