@mobileaidev/ai-app-bridge 0.3.4 → 0.3.6

package/README.md

@@ -7,12 +7,16 @@ discovery. Every request checks the mapping before dispatch. Mutating requests
 are never replayed after a missing route or uncertain result. For manual cleanup,
 pass the exact serial and returned Host port to `remove-forward`.
 
-This release is `0.3.4`, distributed through the npm `latest` dist-tag.
+This source version is `0.3.6`; registry publication is a separate release step.
 The default installation includes the Script/Intent and capture contracts below.
-The `next` dist-tag also points to this release until a newer candidate is published.
+Local package verification does not change npm dist-tags.
 The supported Node range is `>=26.3.0 <27`; this release was checked on 26.3.0.
 See [the release guide](docs/RELEASE.md) for local packaging and coordinated publication.
 
+Optional Android Instrumentation/UI Automator/Espresso/Compose/H5, Flutter integration_test,
+and Playwright executors use the existing `capabilities + run` and Python/JS Script contracts.
+See [integration, dependency profiles and lifecycle](docs/OPTIONAL_EXECUTORS.md).
+
 AI App Bridge CLI/MCP supports Android native apps, Android WebView/H5/CDP,
 Flutter apps on Android and iOS, iOS native apps via `AiAppBridgeIOS` plus
 WebDriverAgent/XCUITest, WKWebView, and desktop Web Bridge sessions.
@@ -56,7 +60,7 @@ domains, commands, and options, then call `run` with the selected command.
 
 ```bash
 # Install the current stable release; see docs/RELEASE.md for packaging.
-npm install -g @mobileaidev/ai-app-bridge@0.3.4
+npm install -g @mobileaidev/ai-app-bridge@0.3.6
 
 ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample

package/bin/android-permissions.js

@@ -42,7 +42,7 @@ function uniqueBlock(lines, predicate, error) {
   return { header: lines[indexes[0]].trim(), lines: block(lines, indexes[0]) };
 }
 
-function parsePermissionState(text, { packageName, permission, userId }) {
+function parsePermissionState(text, { packageName, permission, userId }, definitions) {
   const pkg = uniqueBlock(text.split(/\r?\n/), line => line.startsWith(`Package [${packageName}] (`), 'permission_package_not_found');
   const appId = pkg.lines.map(line => /^\s+(?:appId|userId)=(\d+)\s*$/.exec(line)).filter(Boolean);
   if (appId.length !== 1 || Number(appId[0][1]) >= 100000) throw new CommandError('permission_state_unsupported', 'Android package appId is unavailable or ambiguous.');
@@ -50,10 +50,27 @@ function parsePermissionState(text, { packageName, permission, userId }) {
   if (!/\binstalled=true\b/.test(user.header)) throw new CommandError('permission_package_not_installed', 'The package is not installed for the requested Android user.');
   const runtime = uniqueBlock(user.lines, line => line === 'runtime permissions:', 'runtime_permission_not_found');
   const matches = runtime.lines.filter(line => line.trim().startsWith(`${permission}:`));
-  const match = matches.length === 1 && /^\s*[^:]+:\s+granted=(true|false),\s*flags=\[([^\]]*)\]\s*$/.exec(matches[0]);
+  if (!matches.length && definitions !== undefined) {
+    // Android 7 omits untouched runtime permissions. Establish that the app
+    // requests a runtime permission and has no install grant before interpreting
+    // the absent PackageManager state as denied with no flags.
+    const requested = uniqueBlock(pkg.lines, line => line === 'requested permissions:', 'runtime_permission_not_found');
+    const targetSdk = pkg.lines.flatMap(line => [...line.matchAll(/\btargetSdk=(\d+)\b/g)]);
+    const definition = uniqueBlock(definitions.split(/\r?\n/), line => line.startsWith(`Permission [${permission}] (`), 'runtime_permission_not_found');
+    const protection = definition.lines.flatMap(line => [...line.matchAll(/\bprot=([^\s]+)/g)]);
+    if (targetSdk.length === 1 && Number(targetSdk[0][1]) >= 23
+        && requested.lines.some(line => line.trim() === permission)
+        && protection.length === 1 && protection[0][1].split('|')[0] === 'dangerous'
+        && !pkg.lines.some(line => line.trim().startsWith(`${permission}:`))) {
+      return { packageName, permission, userId, uid: userId * 100000 + Number(appId[0][1]), granted: false, flags: [] };
+    }
+  }
+  // Android 7's Settings.permissionFlagsToString omits the entire suffix when flags == 0.
+  const match = matches.length === 1 && /^\s*[^:]+:\s+granted=(true|false)(?:,\s*flags=\[([^\]]*)\])?\s*$/.exec(matches[0]);
   if (!matches.length) throw new CommandError('runtime_permission_not_found', 'The requested permission has no runtime permission record for this package and user.');
   if (!match) throw new CommandError('permission_state_unsupported', 'Android returned an unrecognized runtime permission record.');
-  const flags = match[2].trim() ? match[2].split('|').map(value => value.trim()) : [];
+  // Nougat separates flags with spaces; newer dumps use pipes.
+  const flags = match[2] !== undefined && match[2].trim() ? match[2].trim().split(/\s*\|\s*|\s+/) : [];
   if (flags.some(value => !/^[A-Z][A-Z0-9_]*$/.test(value)) || new Set(flags).size !== flags.length) {
     throw new CommandError('permission_state_unsupported', 'Android returned unrecognized permission flags.');
   }
@@ -70,8 +87,15 @@ async function readPermissionState(args, run = execute) {
       userId = Number(current);
     }
     const dump = await androidCommand(args, ['shell', 'dumpsys', 'package', args.packageName], run);
+    let state;
+    try { state = parsePermissionState(dump.stdout, { ...args, userId }); }
+    catch (error) {
+      if (error.code !== 'runtime_permission_not_found') throw error;
+      const definitions = await androidCommand(args, ['shell', 'dumpsys', 'package', 'permissions'], run);
+      state = parsePermissionState(dump.stdout, { ...args, userId }, definitions.stdout);
+    }
     return { ok: true, source: 'android-package-manager', serial: args.serial,
-      ...parsePermissionState(dump.stdout, { ...args, userId }), capturedAtMs: Date.now() };
+      ...state, capturedAtMs: Date.now() };
   } catch (error) {
     if (error instanceof CommandError) throw error;
     throw new CommandError('permission_query_failed', 'Android permission state could not be read.', { details: { cause: error.code || null } });
@@ -125,7 +149,17 @@ function activityIdentity(value) {
 // the actual dialog, and PackageManager independently verifies the named permission.
 function parsePermissionRequest(text) {
   const lines = text.split(/\r?\n/);
-  const tops = lines.filter(line => /^\s*topResumedActivity=/.test(line)).map(activityIdentity);
+  let tops = lines.filter(line => /^\s*topResumedActivity=/.test(line)).map(activityIdentity);
+  if (!tops.length) {
+    // Before multi-resume, ActivityManager records one focused Activity and
+    // each stack's resumed Activity. Both identities must agree.
+    tops = lines.filter(line => /^\s*mFocusedActivity:/.test(line)).map(activityIdentity);
+    const resumed = lines.filter(line => /^\s*mResumedActivity:/.test(line)).map(activityIdentity);
+    if (tops.length !== 1 || !tops[0] || !resumed.some(value => value && value.token === tops[0].token
+        && value.component === tops[0].component && value.userId === tops[0].userId)) {
+      throw new CommandError('permission_request_unsupported', 'The focused and resumed Android Activity identities did not agree.');
+    }
+  }
   if (tops.length !== 1 || !tops[0]) throw new CommandError('permission_request_unsupported', 'One top-resumed Android Activity could not be identified.');
   const records = lines.flatMap((line, i) => /^\s*\* Hist\s+#\d+: ActivityRecord\{/.test(line) ? [{ ...activityIdentity(line), lines: block(lines, i) }] : []);
   const requests = records.filter(record => record.lines.some(line => line.trim().startsWith('Intent {') && line.includes(`act=${REQUEST_PERMISSIONS} `)));

package/bin/command-discovery.js

@@ -80,12 +80,18 @@ function commandInputSchema(command, filters = {}) {
   }
   const schema = commandSchema(command);
   if (!Object.keys(filters).length) return schema;
+  if (require('./ui-observation').commands.has(command) && Object.keys(filters).every(key => key === 'operation')) {
+    const branch = schema.oneOf.find(entry => entry.properties.operation.const === filters.operation);
+    if (!branch) throw new CommandError('invalid_argument', 'Unknown UI observation operation.', { field: 'operation' });
+    const { oneOf, ...base } = schema;
+    return { ...base, properties: { ...base.properties, ...branch.properties }, required: [...base.required, ...(branch.required || [])] };
+  }
   const scope = ['platform', 'provider', 'action'].find(key => Object.hasOwn(filters, key));
   if (scope && (command !== 'intent' || filters.operation !== 'decide')) {
     throw new CommandError('invalid_argument', `${scope} is available only with command=intent and operation=decide.`, { field: scope });
   }
-  if (!['intent', 'script', 'evidence'].includes(command)) {
-    throw new CommandError('invalid_argument', 'Operation schema selection supports intent, script and evidence.', { field: 'operation' });
+  if (!['intent', 'script', 'evidence', 'web-executor', 'android-executor', 'flutter-executor'].includes(command)) {
+    throw new CommandError('invalid_argument', 'Operation schema selection supports intent, script, evidence and executor commands.', { field: 'operation' });
   }
   const selected = schema.anyOf.filter(branch => branch.properties.operation.const === filters.operation);
   if (!selected.length) throw new CommandError('invalid_argument', `Unknown ${command} operation: ${filters.operation}.`, { field: 'operation' });

package/bin/command-registry.js

@@ -8,9 +8,15 @@ const { executionCommandSchema, nativeGestureSchema, nativeSelector, flutterSele
 const { flutterActionSchema, webCommandSchema } = require('./shared-kernel/provider-command-contracts');
 
 const commandDefinitions = [
+  { command: 'ui-observation', domain: 'core', summary: 'Start a bounded UI observation window (100–5000 ms), inspect it, or stop its lease. Off by default; provider selects native or Flutter. New windows establish a fresh baseline.', targetApp: true, options: ['operation', 'provider', 'durationMs', 'leaseId', 'packageName', 'serial'] },
+  { command: 'ios-ui-observation', domain: 'ios', summary: 'Control bounded iOS native or Flutter UI observation. Off by default; expires locally even if the Host exits.', targetKind: 'ios-app', options: ['operation', 'provider', 'durationMs', 'leaseId', 'deviceId', 'bundleId'] },
+  { command: 'web-ui-observation', domain: 'web', summary: 'Control bounded Web DOM change observation. Off by default; expires locally even if the Host exits.', targetKind: 'web-target', options: ['operation', 'durationMs', 'leaseId', 'sessionId', 'runtimeEpoch', 'targetId'] },
+  { command: 'android-executor', domain: 'advanced', summary: 'Optional AndroidX UI Automator, Espresso and registered WebView/Compose test adapters. Open an installed androidTest build, observe, act on observed nodes, query original receipts and close. Opening instrumentation restarts the target application. Requires app.test in Script.', targetKind: 'android-app', options: ['operation'] },
+  { command: 'flutter-executor', domain: 'advanced', summary: 'Optional Flutter integration_test executor on Android. Open the installed application test entrypoint, observe widgets, run WidgetTester actions, query receipts and close the test process. Requires app.test in Script.', targetKind: 'android-app', options: ['operation'] },
+  { command: 'web-executor', domain: 'web', summary: 'Optional Playwright executor: inspect readiness, prepare pinned browser dependencies, open a browser, observe bound frames, act, wait, query original receipts, or close. Browser input and test operations retain their actual mechanisms. Script requires app.test.', targetKind: 'web-target', options: ['operation'] },
   { command: 'runtime', domain: 'execution', summary: 'Inspect, start or orderly stop the shared local execution runtime. CLI exit and MCP disconnect leave operations running; stop cancels and drains them.', targetKind: 'host-runtime', options: ['operation'] },
   { command: 'device-ownership', domain: 'execution', summary: 'Read ownership, reconcile original completion, explicitly cancel a retained install by actionId, or read a retained UIA receipt by serial/runtimeEpoch/actionId. Installation cancellation abandons its original PM session; it does not roll back an installed APK.', targetKind: 'android-device', options: ['operation', 'serial', 'timeoutMs', 'runtimeEpoch', 'actionId'] },
-  { command: 'uia-runtime', domain: 'advanced', summary: 'Read, start or orderly stop the Android API 33+ UIA node runtime. Start checks the phone process lock; unacknowledged original receipts are retained.', targetKind: 'android-device', options: ['operation', 'serial', 'adb', 'timeoutMs'] },
+  { command: 'uia-runtime', domain: 'advanced', summary: 'Read, start or orderly stop the Android API 25+ UIA node runtime. Start checks the phone process lock; unacknowledged original receipts are retained.', targetKind: 'android-device', options: ['operation', 'serial', 'adb', 'timeoutMs'] },
   { command: 'status', domain: 'core', summary: 'Read bridge status, app/device metadata, capture counts, and Flutter summary.', targetApp: true, options: ['packageName', 'port', 'serial', 'full'] },
   { command: 'tree', domain: 'core', summary: 'Read Android View tree from the in-app bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes', 'maxDepth'] },
   { command: 'uia-tree', domain: 'core', summary: 'Read UIAutomator XML for the current foreground window.', options: ['serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes', 'maxDepth'] },
@@ -70,7 +76,7 @@ const commandDefinitions = [
   { command: 'ios-devices', domain: 'ios', summary: 'List iOS devices known to xcrun devicectl.', targetKind: 'ios-device', options: ['deviceId'] },
   { command: 'ios-install-app', domain: 'ios', summary: 'Install an iOS .app bundle through devicectl.', targetKind: 'ios-app', options: ['deviceId', 'appPath'] },
   { command: 'ios-launch-app', domain: 'ios', summary: 'Launch an iOS app by bundle identifier through devicectl.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'terminateExisting'] },
-  { command: 'ios-execution', domain: 'ios', summary: 'Read SDK or WDA execution/physical ownership, cancel an original action, read its durable completion, or reconcile unknown ownership without replay.', targetKind: 'ios-app', options: ['operation', 'deviceId', 'bundleId', 'kind', 'actionId', 'runtimeEpoch', 'runtimeUrl', 'iosHost', 'iosPort', 'wdaRunnerBundleId', 'wdaUrl', 'devicectl', 'timeoutMs'] },
+  { command: 'ios-execution', domain: 'ios', summary: 'Read SDK or WDA execution/physical ownership, cancel an original action, read its durable completion, or reconcile unknown ownership without replay.', targetKind: 'ios-app', options: ['operation', 'deviceId', 'bundleId', 'kind', 'actionId', 'runtimeEpoch', 'runtimeUrl', 'iosHost', 'iosPort', 'wdaRunnerBundleId', 'wdaUrl', 'devicectl', 'timeoutMs', 'setupResultPath'] },
   { command: 'ios-status', domain: 'ios', summary: 'Read AiAppBridgeIOS runtime status.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
   { command: 'ios-tree', domain: 'ios', summary: 'Read UIKit tree from the AiAppBridgeIOS runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
   { command: 'ios-logs', domain: 'ios', summary: 'Read in-app iOS log records.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'sinceId', 'sinceMs', 'limit'] },
@@ -202,7 +208,7 @@ define('orientation', require('./shared-kernel/ios-native-target').orientationSc
 define('selector', { type: 'string', minLength: 1 });
 define('spec', { type: 'object', additionalProperties: true });
 define('targetRef', require('./shared-kernel/uia-protocol').targetRefSchema);
-define('adb serial packageName artifactDir deviceId bundleId iosHost runtimeUrl wdaUrl wdaSessionId devicectl xcodebuild host path token appPath apkPath activity component action data initialRoute outFile permission op mode targetText requireText absentText requireActivity resourceId textFilter resourceIdFilter classFilter urlFilter method pageUrlFilter socketName targetId sessionId accessibilityId elementId wdaProjectPath wdaBundleId teamId displayUniqueId tag level grep since factCursor cursor runtimeEpoch afterActionId mobileFactId targetKey requestId deviceLogScope logcatFormat format agentModule pythonPath goal intent operationId recordingDir namespace outputDir archiveDir manifestSha256 name reason provider adapter', { type: 'string', minLength: 1 });
+define('adb serial packageName artifactDir deviceId bundleId iosHost runtimeUrl wdaUrl wdaSessionId devicectl xcodebuild host path token setupResultPath appPath apkPath activity component action data initialRoute outFile permission op mode targetText requireText absentText requireActivity resourceId textFilter resourceIdFilter classFilter urlFilter method pageUrlFilter socketName targetId sessionId accessibilityId elementId wdaProjectPath wdaBundleId teamId displayUniqueId tag level grep since factCursor cursor runtimeEpoch afterActionId mobileFactId targetKey requestId deviceLogScope logcatFormat format agentModule pythonPath goal intent operationId recordingDir namespace outputDir archiveDir manifestSha256 name reason provider adapter', { type: 'string', minLength: 1 });
 define('text value script payload', { type: 'string' });
 define('aaptPath apksignerPath', { type: 'string', minLength: 1 });
 define('full compact visibleOnly clear follow appPid force hideKeyboard noAutoHideKeyboard allowDowngrade clearTask exact skipFlutterLaunch includeResponseBody keepForward noBodies startWda terminateExisting clearFirst refresh includeActions history includeRecordedPayloads grepCaseSensitive includeCatalog', { type: 'boolean' });
@@ -236,6 +242,9 @@ const commandByName = new Map(commandDefinitions.map(d => [d.command, d]));
 const isolatedByName = new Map(isolatedCommandDefinitions.map(d => [d.command, d]));
 
 function isMutationCommand(command, args = {}) {
+  if (require('./ui-observation').commands.has(command)) return args.operation !== 'status';
+  if (['android-executor', 'flutter-executor'].includes(command)) return ['open', 'act', 'close'].includes(args.operation);
+  if (command === 'web-executor') return ['prepare', 'open', 'act', 'navigate', 'close'].includes(args.operation);
   if (command === 'web-command' && args.name === 'domSnapshot') return false;
   return mutationCommands.has(command) || (command === 'logcat' && args.clear === true)
     || (command === 'device-ownership' && args.operation === 'cancel-install')
@@ -251,6 +260,8 @@ function isAndroidMutation(command, args = {}) {
 
 function executionTimeoutMs(command, args = {}) {
   if (args.timeoutMs !== undefined) return args.timeoutMs;
+  if (['android-executor', 'flutter-executor'].includes(command)) return args.operation === 'open' ? 60000 : 30000;
+  if (command === 'web-executor') return args.operation === 'prepare' ? 300000 : 30000;
   if (iosSdkCommands.has(command) || command === 'ios-execution' || require('./ios-wda-port').commands.has(command)) return 30000;
   if (command === 'ios-setup') return 300000;
   if (command === 'ios-install-app') return 120000;
@@ -262,9 +273,10 @@ function executionTimeoutMs(command, args = {}) {
 // These are execution capabilities, independent of MCP/CLI transport. Script
 // permissions gate Bridge calls; trusted local code is not a process sandbox.
 const scriptPermissions = Object.freeze({
+  'app.test': ['web-executor', 'android-executor', 'flutter-executor'],
   'app.read': ['status', 'tree', 'uia-tree', 'screenshot', 'flutter-tree', 'flutter-nodes', 'h5-dom', 'flutter-h5-dom', 'keyboard-state', 'permission-state',
     'ios-status', 'ios-tree', 'ios-uia-tree', 'ios-screenshot', 'ios-flutter-tree', 'ios-flutter-nodes', 'ios-h5-dom', 'ios-wda-status', 'web-status', 'web-dom'],
-  'capture.read': ['logs', 'network', 'state', 'events', 'logcat', 'webview-console', 'webview-network', 'ios-logs', 'ios-network', 'ios-state', 'ios-events', 'web-logs', 'web-network', 'web-state', 'web-events'],
+  'capture.read': ['ui-observation', 'ios-ui-observation', 'web-ui-observation', 'logs', 'network', 'state', 'events', 'logcat', 'webview-console', 'webview-network', 'ios-logs', 'ios-network', 'ios-state', 'ios-events', 'web-logs', 'web-network', 'web-state', 'web-events'],
   'app.interact': ['launch-app', 'launch-activity', 'tap', 'tap-text', 'tap-uia-text', 'tap-uia', 'tap-native', 'input-text', 'swipe', 'native-gesture', 'keyevent', 'wait-text', 'hide-keyboard', 'tap-flutter', 'tap-flutter-text', 'input-flutter-text', 'scroll-flutter', 'h5-click', 'h5-input', 'h5-wait', 'h5-scroll', 'flutter-h5-click', 'flutter-h5-input', 'flutter-h5-wait', 'flutter-h5-scroll',
     'ios-h5-click', 'ios-h5-input', 'ios-h5-scroll', 'ios-launch-app', 'ios-wda-session', 'ios-tap', 'ios-input', 'ios-swipe', 'ios-set-orientation', 'ios-tap-native', 'ios-input-native-text', 'ios-tap-flutter', 'ios-input-flutter-text', 'ios-scroll-flutter', 'ios-flutter-back', 'ios-flutter-hide-keyboard', 'web-click', 'web-input', 'web-key', 'web-scroll', 'web-wait'],
   'app.lifecycle': ['clear-app-data'],
@@ -294,7 +306,7 @@ function commandContract(command) {
       providersByPlatform: { android: ['native', 'uia', 'flutter', 'h5'], ios: ['native', 'h5', 'flutter'], web: ['h5'] } } : {}),
     execution: { kind: role === 'execution' ? 'operation' : isMutationCommand(command) ? 'mutation' : 'query',
       mutation: isMutationCommand(command),
-      conditionalMutation: command === 'uia-runtime' ? 'operation != status' : command === 'logcat' ? 'clear=true' : ['webview-network', 'webview-console'].includes(command) ? 'script is supplied' : null,
+      conditionalMutation: command === 'web-executor' ? 'operation in prepare,open,act,navigate,close' : ['android-executor', 'flutter-executor'].includes(command) ? 'operation in open,act,close' : command === 'uia-runtime' ? 'operation != status' : command === 'logcat' ? 'clear=true' : ['webview-network', 'webview-console'].includes(command) ? 'script is supplied' : null,
       arbitration: command === 'script' || command === 'intent' ? 'target-platform-physical-device'
         : isAndroidMutation(command) ? 'cross-process-physical-android-device'
         : platform === 'ios' && isMutationCommand(command) ? 'cross-process-physical-ios-device'
@@ -305,6 +317,10 @@ function commandContract(command) {
 function commandSchema(command) {
   const definition = commandByName.get(command) || isolatedByName.get(command);
   if (!definition) throw new CommandError('unknown_command', `Unknown command: ${command}`, { field: 'command' });
+  if (require('./ui-observation').commands.has(command)) return require('./ui-observation').schema(command, optionTypes);
+  if (command === 'web-executor') return require('./executors/command-schema').webExecutorSchema();
+  if (command === 'android-executor') return require('./executors/command-schema').androidExecutorSchema();
+  if (command === 'flutter-executor') return require('./executors/command-schema').flutterExecutorSchema();
   if (command === 'runtime') return { type: 'object', additionalProperties: false, required: ['operation'],
     properties: { operation: { enum: ['start', 'status', 'stop'] } } };
   if (definition.domain === 'web') return require('./web/command-schema').webSchema(command);
@@ -355,14 +371,15 @@ function commandSchema(command) {
       actionId: { type: 'string', minLength: 1, maxLength: 256 }, runtimeEpoch: optionTypes.runtimeEpoch,
       wdaRunnerBundleId: optionTypes.wdaRunnerBundleId, wdaUrl: optionTypes.wdaUrl,
       runtimeUrl: optionTypes.runtimeUrl, iosHost: optionTypes.iosHost, iosPort: optionTypes.iosPort,
-      devicectl: optionTypes.devicectl, timeoutMs: optionTypes.timeoutMs },
+      devicectl: optionTypes.devicectl, timeoutMs: optionTypes.timeoutMs, setupResultPath: optionTypes.setupResultPath },
     required: ['operation', 'deviceId'], oneOf: [
       { properties: { kind: { enum: ['h5', 'flutter'] }, wdaRunnerBundleId: false, wdaUrl: false },
         anyOf: [
-          { properties: { operation: { enum: ['status', 'reconcile'] }, kind: false, actionId: false, runtimeEpoch: false } },
-          { properties: { operation: { enum: ['result', 'cancel'] } }, required: ['bundleId', 'kind', 'actionId', 'runtimeEpoch'] },
+          { properties: { operation: { const: 'status' }, kind: false, actionId: false, runtimeEpoch: false, setupResultPath: false } },
+          { properties: { operation: { const: 'reconcile' }, kind: false, actionId: false, runtimeEpoch: false } },
+          { properties: { operation: { enum: ['result', 'cancel'] }, setupResultPath: false }, required: ['bundleId', 'kind', 'actionId', 'runtimeEpoch'] },
         ] },
-      { properties: { kind: { const: 'wda' }, bundleId: false, runtimeUrl: false, iosHost: false, iosPort: false },
+      { properties: { kind: { const: 'wda' }, bundleId: false, runtimeUrl: false, iosHost: false, iosPort: false, setupResultPath: false },
         required: ['kind', 'wdaRunnerBundleId'], anyOf: [
           { properties: { operation: { enum: ['status', 'reconcile'] }, actionId: false, runtimeEpoch: false } },
           { properties: { operation: { enum: ['result', 'cancel'] } }, required: ['actionId', 'runtimeEpoch'] },

package/bin/device-provider.js

@@ -79,10 +79,18 @@ async function runCommand(command, options, ctx) {
       return removeBridgeForward(ctx, adb);
     case 'status':
       return bridgeStatus(ctx, options);
+    case 'ui-observation':
+      return bridgeRequest(ctx, async () => {
+        const path = require('./ui-observation').path(options);
+        const result = JSON.parse(await httpPost(bridgeUrl(ctx, path), require('./ui-observation').request(options), ctx.httpTimeoutMs));
+        verifyBridgeTargetPackage(ctx, result, path);
+        return result;
+      });
     case 'tree':
       return bridgeTree(ctx, options);
     case 'flutter-tree': {
-      const status = await bridgeGet(ctx, '/v1/status');
+      const status = await bridgeGet(ctx, '/v1/flutter/snapshot');
+      if (status.ok === false) return status;
       return status.flutter?.layout || null;
     }
     case 'flutter-nodes':
@@ -2173,7 +2181,8 @@ async function waitText(ctx, targetText, options = {}, dependencies = {}) {
 }
 
 async function flutterNodes(ctx) {
-  const status = await bridgeGet(ctx, '/v1/status');
+  const status = await bridgeGet(ctx, '/v1/flutter/snapshot');
+  if (status.ok === false) return status;
   return status.flutter?.layout?.operable || { ok: false, error: 'no_flutter_operable_tree' };
 }
 

package/bin/execution-host.js

@@ -20,6 +20,9 @@ const {
 const iosProvider = new IOSBridgeProvider();
 const webProvider = new WebBridgeProvider();
 const targetExecution = new TargetExecution();
+let browserExecutor = null;
+let androidExecutor = null;
+let flutterExecutor = null;
 
 let sharedFactStore = null;
 let sharedFactRecorder = null;
@@ -47,6 +50,9 @@ function close() {
     await require('./script/script-entry').cancelActiveScripts();
     await require('./intent/intent-entry').cancelActiveIntents();
     await webProvider.close();
+    await browserExecutor?.close();
+    await androidExecutor?.close();
+    await flutterExecutor?.close();
     await Promise.allSettled([...activeRuns]);
     try { await sharedObservationCollector?.stop(); }
     finally {
@@ -579,6 +585,18 @@ function getSharedObservationCollector(factRecorder) {
 }
 
 async function runRawCommand(command, args = {}) {
+  if (command === 'android-executor') {
+    androidExecutor ||= new (require('./executors/android-host').AndroidExecutorHost)();
+    return androidExecutor.run(args);
+  }
+  if (command === 'flutter-executor') {
+    flutterExecutor ||= new (require('./executors/flutter-host').FlutterExecutorHost)();
+    return flutterExecutor.run(args);
+  }
+  if (command === 'web-executor') {
+    browserExecutor ||= new (require('./executors/playwright-host').PlaywrightHost)();
+    return browserExecutor.run(args);
+  }
   const definition = commandByName.get(command);
   if (definition?.domain === 'ios') return iosProvider.run(command, args);
   if (definition?.domain === 'web') return webProvider.run(command, args);

package/bin/executors/android-host.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { randomUUID, randomBytes, createHash } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { currentExecution, checkExecution, markExecutionDispatched, withoutExecution, runExecution, executionSleep } = require('../shared-kernel/execution-scope');
+const { runDeviceEffect } = require('../shared-kernel/device-mutation-lease');
+const { executorHome, atomicJson, readJson } = require('./managed-runtime');
+const { AndroidExecutorPort, protocol, quote } = require('./android-port');
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+function settlement(result, pending) {
+  if (result?.executionReceipt?.settled === true && result.executionReceipt.sessionId === pending.sessionId
+    && result.executionReceipt.runtimeEpoch === pending.runtimeEpoch && result.executionReceipt.actionId === pending.actionId) {
+    return { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: pending.runtimeEpoch, actionId: pending.actionId,
+      settled: true, dispatched: result.executionReceipt.result?.dispatched === true, receipt: result.executionReceipt };
+  }
+  if (result?.ok === false && result.dispatched === false && result.ambiguous === false)
+    return { kind: pending.kind, sessionId: pending.sessionId, actionId: pending.actionId, settled: true, dispatched: false };
+  if (pending.operation === 'open' && result?.ok && result.protocol === pending.protocol && result.sessionId === pending.sessionId)
+    return { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: result.runtimeEpoch, settled: true, dispatched: true, state: 'ready' };
+  if (['open', 'close'].includes(pending.operation) && result?.closed?.settled === true && result.closed.sessionId === pending.sessionId
+    && (pending.runtimeEpoch === null || result.closed.runtimeEpoch === pending.runtimeEpoch))
+    return { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: pending.runtimeEpoch, settled: true, dispatched: true, state: 'closed' };
+  return null;
+}
+
+class AndroidExecutorHost {
+  constructor({ home = executorHome() } = {}) { this.home = home; this.sessions = new Map(); this.children = new Map(); }
+  get kind() { return 'android-test-executor'; }
+  createPort(descriptor) { return new AndroidExecutorPort(descriptor); }
+  async finishClose(port) {
+    if (!await port.processEnded()) return false;
+    await require('../shared-kernel/uia-runtime-port').createUiaRuntimePort({ adb: port.descriptor.adb, serial: port.descriptor.serial }).releaseInstrumentation(port.descriptor.sessionId);
+    return true;
+  }
+  directory(sessionId) {
+    if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(sessionId)) throw new CommandError('executor_session_mismatch', 'Invalid executor session ID.');
+    return path.join(this.home, 'sessions', 'android', sessionId);
+  }
+  load(args) {
+    const descriptor = readJson(path.join(this.directory(args.sessionId), 'session.json'));
+    if (!descriptor || descriptor.serial !== args.serial || descriptor.packageName !== args.packageName
+      || args.runtimeEpoch !== descriptor.runtimeEpoch) throw new CommandError('executor_session_mismatch', 'Executor target/session/generation does not match.');
+    let port = this.sessions.get(descriptor.sessionId);
+    if (!port) { port = this.createPort(descriptor); this.sessions.set(descriptor.sessionId, port); }
+    return port;
+  }
+  async run(args) {
+    const adb = args.adb || process.env.ADB || 'adb';
+    if (args.operation === 'status') {
+      const port = new AndroidExecutorPort({ adb, serial: args.serial });
+      const listing = await port.invoke(['shell', 'pm', 'list', 'instrumentation']);
+      const instruments = listing.stdout.trim().split(/\r?\n/).filter(Boolean).map(line => {
+        const match = /^instrumentation:(\S+) \(target=(\S+)\)$/.exec(line);
+        if (!match) throw new CommandError('executor_instrumentation_inventory_invalid', 'Android returned an unexpected instrumentation entry.');
+        return { component: match[1], targetPackage: match[2] };
+      });
+      return { ok: true, serial: args.serial, instruments,
+        prerequisite: 'Use the existing application androidTest source set and install its matching test APK. Opening instrumentation restarts the target application; no separate business app is required.' };
+    }
+    if (args.operation === 'open') return this.open({ ...args, adb });
+    const port = this.load(args), descriptor = port.descriptor;
+    const request = { ...args, requestId: randomUUID() };
+    delete request.adb; delete request.serial; delete request.packageName; delete request.feedback;
+    if (args.operation === 'receipt') {
+      const receipt = await port.readRecord(`receipts/${hash(args.actionId)}.json`);
+      return { ok: Boolean(receipt), sessionId: descriptor.sessionId, runtimeEpoch: descriptor.runtimeEpoch, receipt };
+    }
+    if (args.operation === 'observe') return port.request(request);
+    const actionId = args.actionId || args.runtimeActionId || randomUUID();
+    const pending = { kind: this.kind, protocol: descriptor.protocol, operation: args.operation, sessionId: descriptor.sessionId,
+      runtimeEpoch: descriptor.runtimeEpoch, actionId, target: { serial: descriptor.serial, packageName: descriptor.packageName, adb: descriptor.adb },
+      descriptorFile: path.join(this.directory(descriptor.sessionId), 'session.json') };
+    return runDeviceEffect(pending, async () => {
+      if (args.operation === 'close') {
+        const response = await port.request(request);
+        if (!response.ok) return response;
+        while (true) {
+          const closed = await port.readRecord('closed.json');
+          if (closed?.settled === true && await this.finishClose(port)) {
+            await port.disconnect(); this.sessions.delete(descriptor.sessionId); return { ok: true, closed };
+          }
+          await executionSleep(50);
+        }
+      }
+      try { return await port.request({ ...request, actionId }); }
+      catch (error) {
+        if (error.dispatched === false) throw error;
+        const recovered = await withoutExecution(() => runExecution({ timeoutMs: 5000, mutation: false }, async () => {
+          await port.request({ operation: 'cancel', requestId: request.requestId, timeoutMs: 1000 });
+          while (true) {
+            const response = await port.request({ operation: 'receipt', actionId, timeoutMs: 1000 });
+            if (response.receipt?.settled === true) return { ...response.receipt.result, executionReceipt: response.receipt, recovered: true };
+            await executionSleep(50);
+          }
+        })).catch(recoveryError => ({ ok: false, error: 'executor_completion_unknown', message: error.message,
+          recoveryError: recoveryError.code, dispatched: true, ambiguous: true, sessionId: descriptor.sessionId, runtimeEpoch: descriptor.runtimeEpoch, actionId }));
+        return recovered;
+      }
+    }, result => settlement(result, pending));
+  }
+  async open(args) {
+    const inventory = await this.run({ operation: 'status', adb: args.adb, serial: args.serial });
+    const installed = inventory.instruments.find(item => item.component === args.instrumentation);
+    if (!installed) throw new CommandError('executor_not_installed', 'The selected instrumentation component is not installed.', { dispatched: false, ambiguous: false });
+    if (installed.targetPackage !== args.packageName) throw new CommandError('executor_target_mismatch', 'The test APK must target this exact application package.', { dispatched: false, ambiguous: false });
+    if (!args.activity) throw new CommandError('missing_argument', 'The test executor requires the application Activity to launch.', { field: 'activity', dispatched: false, ambiguous: false });
+    const sessionId = randomUUID(), directory = this.directory(sessionId);
+    const descriptor = { protocol, sessionId, serial: args.serial, packageName: args.packageName, targetPackage: installed.targetPackage,
+      adb: args.adb, token: randomBytes(32).toString('hex'), instrumentation: args.instrumentation, testClass: args.testClass };
+    const file = path.join(directory, 'session.json');
+    const port = new AndroidExecutorPort(descriptor);
+    descriptor.bootId = await port.bootId();
+    atomicJson(file, descriptor);
+    await port.connect();
+    const pending = { kind: this.kind, protocol, operation: 'open', sessionId, runtimeEpoch: null,
+      target: { serial: args.serial, packageName: args.packageName, adb: args.adb }, descriptorFile: file };
+    const uia = require('../shared-kernel/uia-runtime-port').createUiaRuntimePort({ adb: args.adb, serial: args.serial, timeoutMs: args.timeoutMs ?? 60000 });
+    return uia.withInstrumentation(file, () => runDeviceEffect(pending, async () => {
+      checkExecution();
+      const command = ['am', 'instrument', '-w', '-r', '-e', 'class', args.testClass, '-e', 'bridgeSessionId', sessionId,
+        '-e', 'bridgeToken', descriptor.token, '-e', 'bridgeLeaseMs', String(args.leaseMs ?? 600000),
+        ...(args.activity ? ['-e', 'bridgeActivity', args.activity] : []), args.instrumentation];
+      const child = spawn(args.adb, ['-s', args.serial, 'shell', command.map(quote).join(' ')], { stdio: ['ignore', 'pipe', 'pipe'] });
+      let output = '', exited = false, spawnError;
+      child.on('error', error => { spawnError = error; });
+      child.stdout.on('data', chunk => { output = (output + chunk).slice(-65536); });
+      child.stderr.on('data', chunk => { output = (output + chunk).slice(-65536); });
+      child.once('close', code => {
+        exited = true; this.children.delete(sessionId);
+        atomicJson(path.join(directory, 'runner-result.json'), { sessionId, code, output: output.replaceAll(descriptor.token, '[REDACTED_SECRET]'), instrumentFinished: /INSTRUMENTATION_CODE: -?\d+/.test(output) });
+      });
+      this.children.set(sessionId, child);
+      if (child.pid) markExecutionDispatched();
+      this.sessions.set(sessionId, port);
+      try {
+      while (true) {
+        checkExecution();
+        if (spawnError) throw Object.assign(spawnError, { dispatched: false, ambiguous: false });
+        if (exited) throw new CommandError('executor_runner_ended', 'Instrumentation ended before the executor was ready.', { dispatched: true, ambiguous: true, details: { sessionId, output: output.replaceAll(descriptor.token, '[REDACTED_SECRET]') } });
+        let status;
+        try { status = await port.request({ operation: 'status', timeoutMs: 1000 }); }
+        catch (error) { if (!['ECONNRESET', 'ECONNREFUSED', 'executor_disconnected', 'executor_transport_timeout'].includes(error.code)) throw error; }
+        if (status?.ok) {
+          if (status.targetPackage !== installed.targetPackage || status.bootId !== descriptor.bootId || status.capabilities?.engine !== 'android-instrumentation')
+            throw new CommandError('executor_engine_mismatch', 'The running test does not expose the requested executor.', { dispatched: true, ambiguous: true });
+          Object.assign(descriptor, { runtimeEpoch: status.runtimeEpoch, pid: status.pid, processStartTicks: status.processStartTicks, openedAtMs: Date.now() });
+          atomicJson(file, descriptor);
+          return { ...status, serial: args.serial, packageName: args.packageName, targetPackage: installed.targetPackage,
+            lifecycle: 'target-application-instrumented-and-restarted', leaseMs: args.leaseMs ?? 600000 };
+        }
+        await executionSleep(100);
+      }
+      } catch (error) {
+        error.dispatched = Boolean(child.pid); error.ambiguous = error.dispatched;
+        throw error;
+      }
+    }, result => settlement(result, pending)));
+  }
+  async close() {
+    // Runtime teardown only disconnects its ADB clients. Device receipts survive;
+    // the executor lease closes the test, and ownership remains unresolved until proof.
+    for (const child of this.children.values()) child.kill('SIGTERM');
+    this.children.clear();
+  }
+}
+
+async function recoverAndroidExecutor(pending, createPort = descriptor => new AndroidExecutorPort(descriptor)) {
+  const descriptor = readJson(pending.descriptorFile);
+  if (!descriptor || descriptor.serial !== pending.target?.serial || descriptor.sessionId !== pending.sessionId)
+    return { settled: false, error: 'executor_descriptor_mismatch' };
+  const port = createPort(descriptor);
+  if (await port.bootChanged()) return { kind: pending.kind, sessionId: pending.sessionId,
+    runtimeEpoch: pending.runtimeEpoch, actionId: pending.actionId, settled: true, dispatched: null, state: 'device-rebooted-outcome-unknown' };
+  if (pending.operation === 'open') {
+    const session = await port.readRecord('session.json');
+    if (session) {
+      Object.assign(descriptor, { runtimeEpoch: session.runtimeEpoch, pid: session.pid, processStartTicks: session.processStartTicks });
+      if (pending.kind === 'flutter-test-executor') descriptor.port = session.port;
+      atomicJson(pending.descriptorFile, descriptor);
+      return settlement({ ...session, ok: true }, pending);
+    }
+    const runner = readJson(path.join(path.dirname(pending.descriptorFile), 'runner-result.json'));
+    if (runner?.sessionId === pending.sessionId && runner.instrumentFinished) return { kind: pending.kind, sessionId: pending.sessionId, settled: true, dispatched: true, state: 'runner-finished' };
+  }
+  if (pending.operation === 'act') {
+    const receipt = await port.readRecord(`receipts/${hash(pending.actionId)}.json`);
+    if (receipt?.settled) return settlement({ executionReceipt: receipt }, pending);
+  }
+  if (descriptor.pid && await port.processEnded()) return { kind: pending.kind, sessionId: pending.sessionId,
+    runtimeEpoch: pending.runtimeEpoch, actionId: pending.actionId, settled: true, dispatched: null, state: 'executor-process-ended-outcome-unknown' };
+  const closed = await port.readRecord('closed.json');
+  return closed?.settled === true && await port.processEnded() ? { kind: pending.kind, sessionId: pending.sessionId, runtimeEpoch: closed.runtimeEpoch,
+    actionId: pending.actionId, settled: true, dispatched: null, state: 'session-closed-outcome-unknown', closed }
+    : { settled: false, error: 'executor_original_completion_unavailable', actionId: pending.actionId };
+}
+
+module.exports = { AndroidExecutorHost, recoverAndroidExecutor, settlement };