@mobileaidev/ai-app-bridge 0.3.7 → 0.4.0

package/bin/executors/command-schema.js

@@ -56,7 +56,7 @@ function androidExecutorSchema() {
   const bound = (properties = {}, required = []) => ({ properties: { ...target, ...session, ...properties }, required: ['serial', 'packageName', 'sessionId', 'runtimeEpoch', ...required] });
   const action = { anyOf: [
     object({ type: { enum: ['click', 'longClick', 'scrollTo', 'swipeUp', 'swipeDown', 'swipeLeft', 'swipeRight', 'webClick', 'webClear', 'webScrollIntoView', 'semanticLongClick', 'composeClearText'] }, nodeId: identifier }, ['type', 'nodeId']),
-    object({ type: { enum: ['setText', 'typeText', 'replaceText', 'webKeys', 'composeInput', 'composeReplaceText'] }, nodeId: identifier, text: { type: 'string', maxLength: 65536 } }, ['type', 'nodeId', 'text']),
+    object({ type: { enum: ['setText', 'typeText', 'replaceText', 'replaceTextViaInputConnection', 'webKeys', 'composeInput', 'composeReplaceText'] }, nodeId: identifier, text: { type: 'string', maxLength: 65536 } }, ['type', 'nodeId', 'text']),
     object({ type: { const: 'composeScrollToIndex' }, nodeId: identifier, index: integer(0, 1000000) }, ['type', 'nodeId', 'index']),
     object({ type: { const: 'scroll' }, nodeId: identifier, direction: { enum: ['up', 'down', 'left', 'right'] }, percent: { type: 'number', exclusiveMinimum: 0, maximum: 10 } }, ['type', 'nodeId', 'direction', 'percent']),
     object({ type: { enum: ['back', 'home', 'closeKeyboard'] } }, ['type']),

package/bin/executors/preparation.js

@@ -0,0 +1,262 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL, fileURLToPath } = require('node:url');
+const { createHash, randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { object, text, integer } = require('../shared-kernel/argument-schema');
+const { resolveRequestPath } = require('../shared-kernel/request-context');
+const { execFileBounded } = require('../shared-kernel/execution-io');
+const { executorHome, atomicJson, readJson, preparePackage } = require('./managed-runtime');
+const bridgeVersion = require('../../package.json').version;
+const testClass = 'io.github.mobileaidev.aiappbridge.generated.BridgeSessionTest';
+const identifier = { ...text, maxLength: 4096 };
+const common = { timeoutMs: integer(1, 1800000), requestId: identifier, feedback: { enum: ['auto', 'off', 'full'] } };
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function preparationSchema() {
+  const definitions = {
+    android: { properties: { projectDir: identifier, module: { ...text, pattern: '^(:[A-Za-z0-9_-]+)+$' },
+      variant: { ...text, pattern: '^[A-Za-z][A-Za-z0-9]*$' },
+      adapters: { type: 'array', uniqueItems: true, maxItems: 2, items: { enum: ['espresso-web', 'compose'] } },
+      repositoryUrl: identifier, gradlePath: identifier }, required: ['projectDir', 'module', 'variant'] },
+    flutter: { properties: { projectDir: identifier, entrypoint: identifier, flutterPath: identifier,
+      flavor: { ...text, pattern: '^[A-Za-z][A-Za-z0-9_]*$' }, testPackagePath: identifier,
+      mainArguments: { type: 'array', items: { type: 'string', maxLength: 4096 }, maxItems: 100 },
+      dartDefines: { type: 'array', items: identifier, maxItems: 100 } }, required: ['projectDir'] },
+    ios: { properties: { xcodebuild: identifier }, required: [] },
+    web: { properties: { browser: { enum: ['chromium', 'firefox', 'webkit'] } }, required: [] },
+  };
+  const branches = Object.entries(definitions).map(([platform, definition]) =>
+    object({ platform: { const: platform }, ...common, ...definition.properties }, ['platform', ...definition.required]));
+  return { type: 'object', additionalProperties: false, required: ['platform'],
+    properties: { ...Object.assign({}, ...branches.map(branch => branch.properties)), platform: { enum: Object.keys(definitions) } }, anyOf: branches };
+}
+
+function requireFile(file) {
+  if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile())
+    throw new CommandError('executor_prepare_file_missing', `Required project file is missing: ${file}`);
+  return file;
+}
+
+function repository(value = 'https://jitpack.io') {
+  const url = new URL(value);
+  if (!['https:', 'file:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+    throw new CommandError('invalid_argument', 'repositoryUrl must be an HTTPS or local file Maven repository without credentials, query or fragment.');
+  return url.href;
+}
+
+async function withProject(projectDir, action, { home = executorHome() } = {}) {
+  const project = fs.realpathSync(resolveRequestPath(projectDir));
+  const locks = path.join(home, 'preparation-locks');
+  fs.mkdirSync(locks, { recursive: true, mode: 0o700 });
+  const { DatabaseSync } = require('node:sqlite');
+  const lock = new DatabaseSync(path.join(locks, `${digest(project)}.sqlite`));
+  let locked = false;
+  try {
+    try { lock.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE'); locked = true; }
+    catch (error) { if (error.errcode === 5) throw new CommandError('executor_preparing', 'This project is already being prepared.'); throw error; }
+    const directory = path.join(project, 'build', 'ai-app-bridge', 'prepare', randomUUID());
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const startedAtMs = Date.now();
+    try {
+      const result = { ok: true, bridgeVersion, directory, ...await action(project, directory), elapsedMs: Date.now() - startedAtMs };
+      atomicJson(path.join(directory, 'result.json'), result);
+      return result;
+    } catch (error) {
+      const result = { ok: false, bridgeVersion, directory, error: error.code || 'executor_prepare_failed',
+        message: error.message, ...(error.details ? { details: error.details } : {}), elapsedMs: Date.now() - startedAtMs };
+      atomicJson(path.join(directory, 'result.json'), result);
+      throw new CommandError(result.error, result.message, { details: { ...error.details, directory, resultFile: path.join(directory, 'result.json') } });
+    }
+  } finally { if (locked) lock.exec('ROLLBACK'); lock.close(); }
+}
+
+async function loggedRun(run, file, args, directory, name, options) {
+  const logFile = path.join(directory, `${name}.log`);
+  try {
+    const result = await run(file, args, { ...options, maxBuffer: 16 * 1024 * 1024 });
+    fs.writeFileSync(logFile, result.stdout + result.stderr, { mode: 0o600 });
+    return result;
+  } catch (error) {
+    fs.writeFileSync(logFile, String(error.stdout || '') + String(error.stderr || '') + '\n' + error.message, { mode: 0o600 });
+    throw new CommandError('executor_prepare_build_failed', `${name} failed. Read ${logFile}`, { details: { logFile, exitCode: error.code } });
+  }
+}
+
+function androidEntry(adapters) {
+  const compose = adapters.includes('compose');
+  return `package io.github.mobileaidev.aiappbridge.generated;
+public final class BridgeSessionTest extends io.github.mobileaidev.aiappbridge.executor.instrumentation.AndroidExecutorTest {
+${compose ? '  @org.junit.Rule public final androidx.compose.ui.test.junit4.ComposeTestRule compose = androidx.compose.ui.test.junit4.AndroidComposeTestRule_androidKt.createEmptyComposeRule();' : ''}
+  @Override protected java.util.Map<String, io.github.mobileaidev.aiappbridge.executor.ExecutorAdapter> adapters() {
+    java.util.Map<String, io.github.mobileaidev.aiappbridge.executor.ExecutorAdapter> adapters = super.adapters();
+${adapters.includes('espresso-web') ? '    adapters.put("espresso-web", new io.github.mobileaidev.aiappbridge.executor.web.EspressoWebExecutor());' : ''}
+${compose ? '    adapters.put("compose", new io.github.mobileaidev.aiappbridge.executor.compose.ComposeExecutor(compose));' : ''}
+    return adapters;
+  }
+}
+`;
+}
+
+async function prepareAndroid(args, { run = execFileBounded, home } = {}) {
+  if (process.platform === 'win32') throw new CommandError('executor_host_unsupported', 'Android preparation currently supports macOS/Linux Gradle wrappers.');
+  const repositoryUrl = repository(args.repositoryUrl);
+  return withProject(args.projectDir, async (project, directory) => {
+    const wrapper = requireFile(args.gradlePath ? resolveRequestPath(args.gradlePath) : path.join(project, 'gradlew'));
+    const adapters = args.adapters ?? [];
+    const javaFile = path.join(directory, 'java', ...testClass.split('.')) + '.java';
+    fs.mkdirSync(path.dirname(javaFile), { recursive: true });
+    fs.writeFileSync(javaFile, androidEntry(adapters));
+    const coordinate = module => `com.github.mobileAiDev.ai-app-bridge:${module}:${bridgeVersion}`;
+    const config = { directory, module: args.module, variant: args.variant, repositoryUrl,
+      requirements: { minCompileSdk: adapters.includes('compose') ? 35 : 34, minAgp: '8.1.1',
+        dependencies: ['androidx.test.uiautomator:uiautomator:2.4.0', ...(adapters.includes('compose') ? ['androidx.compose.ui:ui-test-junit4-android:1.8.3'] : [])] },
+      pluginCoordinate: coordinate('ai-app-bridge-gradle-plugin'),
+      dependencies: [coordinate('ai-app-bridge-test-instrumentation'), ...adapters.map(adapter => coordinate(`ai-app-bridge-test-${adapter}`)),
+        ...(adapters.includes('compose') ? ['androidx.compose.ui:ui-test-junit4:1.8.3'] : [])] };
+    const configFile = path.join(directory, 'config.json');
+    atomicJson(configFile, config);
+    const template = path.resolve(__dirname, '../../runtime/executors/android/prepare.init.gradle');
+    const preflightFile = path.join(directory, 'android-preflight.json');
+    try { await loggedRun(run, 'sh', [wrapper, '--init-script', template, `-Daab.prepare.config=${configFile}`,
+      `${args.module}:aiAppBridgePrepareExecutor`, '--console=plain', '--no-configuration-cache', '--max-workers=2'],
+    directory, 'gradle-build', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 }); }
+    catch (error) {
+      const preflight = readJson(preflightFile);
+      if (preflight && preflight.status !== 'compatible') throw new CommandError(
+        preflight.status === 'incompatible' ? 'executor_prepare_incompatible' : 'executor_prepare_configuration_unresolved',
+        `Android executor requirements were not met before compilation: ${preflight.issues.join('; ')}. No project configuration was upgraded.`,
+        { details: { ...error.details, preflight, preflightFile } });
+      throw error;
+    }
+    const preflight = readJson(preflightFile);
+    if (preflight?.status !== 'compatible' || preflight.module !== args.module || preflight.variant !== args.variant)
+      throw new CommandError('executor_prepare_configuration_unresolved', 'The build did not report the selected module and variant preflight.', { details: { preflightFile } });
+    const build = readJson(path.join(directory, 'android-build.json'));
+    if (build?.schemaVersion !== 'aab.android-prepared-build/v1' || build.variant !== args.variant || build.module !== args.module
+      || !build.packageName || !build.testPackageName || !build.runner || !build.applicationApks?.length || !build.testApks?.length)
+      throw new CommandError('executor_prepare_artifact_missing', 'The requested application/test variant did not produce complete build metadata.');
+    const artifacts = files => files.map(file => ({ path: requireFile(file), sha256: digest(fs.readFileSync(file)) }));
+    return { platform: 'android', engine: 'android-instrumentation', ...build, testClass, preflight,
+      instrumentation: `${build.testPackageName}/${build.runner}`, repositoryUrl,
+      adapters: ['uiautomator', 'espresso', ...adapters], applicationApks: artifacts(build.applicationApks), testApks: artifacts(build.testApks),
+      lifecycle: 'built-not-installed', projectFilesEdited: [],
+      next: 'Install the matching application and test APKs, then android-executor open with the returned component and class plus the actual launcher Activity.' };
+  }, { home });
+}
+
+async function prepareFlutter(args, { run = execFileBounded, home } = {}) {
+  return withProject(args.projectDir, async (project, directory) => {
+    const flutter = args.flutterPath ?? 'flutter';
+    const entrypoint = requireFile(path.resolve(project, args.entrypoint ?? 'lib/main.dart'));
+    const pubspec = requireFile(path.join(project, 'pubspec.yaml'));
+    const original = fs.readFileSync(pubspec);
+    const defines = args.dartDefines ?? [];
+    if (defines.some(value => value.split('=')[0] === 'INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE'))
+      throw new CommandError('invalid_argument', 'The Bridge test entrypoint owns INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE.');
+    const probe = await loggedRun(run, flutter, ['--version', '--machine'], directory, 'flutter-version', { cwd: project, timeoutMs: 30000 });
+    const sdk = JSON.parse(probe.stdout);
+    const version = /^(\d+)\.(\d+)\.(\d+)$/.exec(sdk.frameworkVersion);
+    if (!version || Number(version[1]) !== 3 || Number(version[2]) < 41)
+      throw new CommandError('executor_flutter_sdk_unsupported', `Flutter ${sdk.frameworkVersion} is outside the supported stable Flutter 3.41+ profile.`);
+    // Establish the baseline from the existing lock, even on a clean computer.
+    // A normal pub get could silently change versions before our comparison.
+    await loggedRun(run, flutter, ['pub', 'get', '--enforce-lockfile'], directory, 'flutter-pub-get', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 });
+    const beforeGraph = JSON.parse((await loggedRun(run, flutter, ['pub', 'deps', '--json'], directory, 'flutter-deps-before', { cwd: project, timeoutMs: 30000 })).stdout);
+    if (productionVersions(beforeGraph).has('ai_app_bridge_test'))
+      throw new CommandError('executor_flutter_dependency_scope', 'ai_app_bridge_test must be a dev_dependency; move the existing production dependency before preparing.');
+    let packageRoot = project;
+    while (!fs.existsSync(path.join(packageRoot, '.dart_tool/package_config.json'))) {
+      const parent = path.dirname(packageRoot);
+      if (parent === packageRoot) throw new CommandError('executor_flutter_dependency_missing', 'Pub did not create a package configuration.');
+      packageRoot = parent;
+    }
+    const lockFile = requireFile(path.join(packageRoot, 'pubspec.lock'));
+    const originalLock = fs.readFileSync(lockFile);
+    const packageConfig = path.join(packageRoot, '.dart_tool/package_config.json');
+    const beforeHelper = JSON.parse(fs.readFileSync(packageConfig)).packages.find(item => item.name === 'ai_app_bridge_test');
+    const beforeDependency = beforeGraph.packages.find(item => item.name === 'ai_app_bridge_test');
+    const matchingSource = beforeHelper && (args.testPackagePath
+      ? fs.realpathSync(fileURLToPath(new URL(beforeHelper.rootUri, pathToFileURL(packageConfig)))) === fs.realpathSync(resolveRequestPath(args.testPackagePath))
+      : beforeDependency?.source === 'hosted');
+    const dependency = args.testPackagePath
+      ? `dev:ai_app_bridge_test:${JSON.stringify({ path: fs.realpathSync(resolveRequestPath(args.testPackagePath)) })}`
+      : `dev:ai_app_bridge_test:${bridgeVersion}`;
+    const reusedDependency = matchingSource && beforeDependency.version === bridgeVersion;
+    try {
+      if (!reusedDependency) await loggedRun(run, flutter, ['pub', 'add', dependency], directory, 'flutter-dependencies', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 });
+      const afterGraph = JSON.parse((await loggedRun(run, flutter, ['pub', 'deps', '--json'], directory, 'flutter-deps-after', { cwd: project, timeoutMs: 30000 })).stdout);
+      const afterVersions = new Map(afterGraph.packages.map(item => [item.name, item.version]));
+      const changes = [...productionVersions(beforeGraph)].filter(([name, version]) => afterVersions.get(name) !== version)
+        .map(([name, before]) => ({ name, before, after: afterVersions.get(name) ?? null }));
+      if (changes.length) {
+        atomicJson(path.join(directory, 'dependency-conflicts.json'), changes);
+        throw new CommandError('executor_flutter_dependency_conflict', 'The test helper would change existing application dependencies; its pubspec/lock changes were reverted. See dependency-conflicts.json.');
+      }
+      const packages = JSON.parse(fs.readFileSync(path.join(packageRoot, '.dart_tool/package_config.json')));
+      const helper = packages.packages.find(item => item.name === 'ai_app_bridge_test');
+      if (!helper || afterVersions.get('ai_app_bridge_test') !== bridgeVersion)
+        throw new CommandError('executor_flutter_dependency_mismatch', `Pub must resolve ai_app_bridge_test ${bridgeVersion}; received ${afterVersions.get('ai_app_bridge_test')}.`);
+    } catch (error) {
+      if (!original.equals(fs.readFileSync(pubspec)) || !originalLock.equals(fs.readFileSync(lockFile))) {
+        fs.writeFileSync(pubspec, original);
+        fs.writeFileSync(lockFile, originalLock);
+        try {
+          await loggedRun(run, flutter, ['pub', 'get', '--offline', '--enforce-lockfile'], directory, 'flutter-restore-dependencies', { cwd: project, timeoutMs: 60000 });
+        } catch (restoreError) {
+          throw new CommandError('executor_flutter_dependency_restore_failed', `Pubspec and lock were restored, but Pub metadata restoration failed after ${error.code || error.message}. ${restoreError.message}`);
+        }
+      }
+      throw error;
+    }
+    const generated = path.join(directory, 'bridge_test.dart');
+    const launch = args.mainArguments === undefined ? 'app.main' : `() => app.main(<String>${JSON.stringify(args.mainArguments).replaceAll('$', '\\$')})`;
+    const importUri = pathToFileURL(entrypoint).href.replaceAll("'", '%27').replaceAll('$', '%24');
+    fs.writeFileSync(generated, `import 'package:ai_app_bridge_test/ai_app_bridge_test.dart';\nimport '${importUri}' as app;\nvoid main() => aiAppBridgeTest(${launch});\n`);
+    await loggedRun(run, flutter, ['build', 'apk', '--debug', '--no-pub', '--target', generated,
+      '--dart-define=INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE=false',
+      ...(args.flavor ? ['--flavor', args.flavor] : []), ...defines.map(value => `--dart-define=${value}`)],
+    directory, 'flutter-build', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 });
+    const apk = requireFile(path.join(project, 'build/app/outputs/flutter-apk', `app-${args.flavor ? `${args.flavor}-` : ''}debug.apk`));
+    return { platform: 'flutter', devicePlatform: 'android', engine: 'flutter-integration-test', flutter: sdk,
+      projectDir: project, entrypoint, generatedEntrypoint: generated,
+      reusedDependency: Boolean(reusedDependency),
+      applicationApks: [{ path: apk, sha256: digest(fs.readFileSync(apk)) }], lifecycle: 'built-not-installed',
+      dependencySource: args.testPackagePath ? { path: fs.realpathSync(resolveRequestPath(args.testPackagePath)) } : { hosted: 'pub.dev', version: bridgeVersion },
+      projectFilesEdited: original.equals(fs.readFileSync(pubspec)) ? [] : ['pubspec.yaml'],
+      applicationDependencyVersionsChanged: [],
+      dependencyMetadata: ['pubspec.lock', '.dart_tool/package_config.json', '.flutter-plugins-dependencies'],
+      next: 'Install this debug APK into the original application package, then flutter-executor open. Ordinary lib/main.dart builds do not start WidgetTester.' };
+  }, { home });
+}
+
+function productionVersions(graph) {
+  const packages = new Map(graph.packages.map(item => [item.name, item]));
+  const versions = new Map();
+  function visit(name) {
+    if (versions.has(name)) return;
+    const item = packages.get(name);
+    if (!item) throw new CommandError('executor_flutter_dependency_graph_invalid', `Pub dependency is absent: ${name}`);
+    versions.set(name, item.version);
+    for (const child of item.directDependencies) visit(child);
+  }
+  for (const item of graph.packages.filter(item => item.kind === 'root')) for (const name of item.directDependencies) visit(name);
+  return versions;
+}
+
+async function prepareExecutor(args, dependencies = {}) {
+  if (args.platform === 'android') return prepareAndroid(args, dependencies);
+  if (args.platform === 'flutter') return prepareFlutter(args, dependencies);
+  if (args.platform === 'web') return { platform: 'web', bridgeVersion, ...await preparePackage(args.browser ?? 'chromium', dependencies) };
+  if (args.platform === 'ios') {
+    const { prepareManagedWda, wdaBuildEnvironment } = require('../ios-wda-project');
+    const xcode = await (dependencies.run ?? execFileBounded)(args.xcodebuild ?? 'xcodebuild', ['-version'],
+      { timeoutMs: 30000, env: wdaBuildEnvironment() });
+    return { ...await prepareManagedWda(dependencies), xcode: xcode.stdout.trim() };
+  }
+  throw new CommandError('invalid_argument', 'Select android, flutter, ios or web.');
+}
+
+module.exports = { preparationSchema, prepareExecutor, prepareAndroid, prepareFlutter, androidEntry, withProject, loggedRun, testClass, bridgeVersion, productionVersions };

package/bin/extraction/json-value.js

@@ -0,0 +1,26 @@
+'use strict';
+
+function validateJsonValue(value, location = '', parents = new Set()) {
+  function invalid(reason) { throw Object.assign(new TypeError(`${location || '/'}: ${reason}`),
+    { code: 'extraction_type_error', valuePath: location }); }
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))) invalid('expected a finite number in the safe integer range');
+    return;
+  }
+  if (typeof value !== 'object') invalid(`unsupported JSON type: ${typeof value}`);
+  if (parents.has(value)) invalid('cyclic value');
+  if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) invalid('expected a plain JSON object');
+  if (Object.getOwnPropertySymbols(value).length) invalid('symbol keys are unsupported');
+  parents.add(value);
+  const keyPath = key => `${location}/${String(key).replace(/~/g, '~0').replace(/\//g, '~1')}`;
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length) invalid('sparse arrays or extra array properties are unsupported');
+    for (let i = 0; i < value.length; i++) validateJsonValue(value[i], keyPath(i), parents);
+  } else {
+    for (const key of Object.keys(value)) validateJsonValue(value[key], keyPath(key), parents);
+  }
+  parents.delete(value);
+}
+
+module.exports = { validateJsonValue };

package/bin/extraction/prepare.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const Module = require('node:module');
+const { spawnSync } = require('node:child_process');
+const { CommandError } = require('../command-errors');
+const { requestDirectory } = require('../shared-kernel/request-context');
+const { inspectPython } = require('../script/python-runtime-adapter');
+const { executablePath } = require('../shared-kernel/executable-path');
+
+function prepareExtraction(extract) {
+  if (extract === null) return null;
+  const timeoutMs = extract.timeoutMs ?? 2000;
+  const reject = (message, field, code = 'invalid_argument') => { throw new CommandError(code, message, { field }); };
+  if (extract.mode === 'regex') {
+    const flags = extract.flags ?? '';
+    if (new Set(flags).size !== flags.length) reject('Regex flags must be unique.', 'extract.flags');
+    if (extract.inputPath !== '' && (!extract.inputPath.startsWith('/') || /~(?![01])/u.test(extract.inputPath))) {
+      reject('inputPath must be a JSON Pointer (for example /text; escape ~ as ~0 and / as ~1).', 'extract.inputPath');
+    }
+    try { new RegExp(extract.pattern, flags); }
+    catch (error) { reject(error.message, 'extract.pattern'); }
+    return { ...extract, flags, timeoutMs };
+  }
+  const cwd = requestDirectory();
+  const filename = extract.sourcePath ? path.resolve(cwd, extract.sourcePath) : `extract.${extract.language === 'python' ? 'py' : 'js'}`;
+  let source = extract.source;
+  if (extract.sourcePath) {
+    try {
+      if (fs.statSync(filename).size > 65536) reject('Extraction source exceeds 64 KiB UTF-8.', 'extract.sourcePath');
+      source = fs.readFileSync(filename, 'utf8');
+    } catch (error) {
+      if (error instanceof CommandError) throw error;
+      reject(`Cannot read extraction source: ${error.message}`, 'extract.sourcePath', 'extraction_source_unavailable');
+    }
+  }
+  if (!source.length || Buffer.byteLength(source) > 65536) reject('Extraction source must contain 1–65536 UTF-8 bytes.', extract.sourcePath ? 'extract.sourcePath' : 'extract.source');
+  let executable = process.execPath;
+  if (extract.language === 'javascript') {
+    try { new vm.Script(Module.wrap(source), { filename }); }
+    catch (error) { reject(`${filename}: ${error.message}`, 'extract.source', 'extraction_syntax_error'); }
+  } else {
+    const python = inspectPython();
+    if (!python.available) reject('Python 3.9+ is required only for Python extraction. Set AI_APP_BRIDGE_PYTHON to an available interpreter.', 'extract.language', 'extraction_runtime_unavailable');
+    executable = executablePath(python.executable);
+    if (!executable) reject('The selected Python interpreter is unavailable.', 'extract.language', 'extraction_runtime_unavailable');
+    const checked = spawnSync(executable, ['-c', 'import sys; compile(sys.stdin.read(), sys.argv[1], "exec")', filename],
+      { input: source, encoding: 'utf8', timeout: 5000, killSignal: 'SIGKILL', maxBuffer: 16384, cwd });
+    if (checked.error) reject(checked.error.message, 'extract.language', 'extraction_runtime_unavailable');
+    if (checked.status !== 0) reject(checked.stderr.trim(), 'extract.source', 'extraction_syntax_error');
+  }
+  return { mode: 'script', language: extract.language, source, filename, cwd, executable, timeoutMs };
+}
+
+module.exports = { prepareExtraction };

package/bin/extraction/regex.js

@@ -0,0 +1,30 @@
+'use strict';
+
+function extractRegex(response, { inputPath, pattern, flags = '' }) {
+  let input = response;
+  if (inputPath !== '') {
+    for (const part of inputPath.slice(1).split('/')) {
+      const key = part.replace(/~1/g, '/').replace(/~0/g, '~');
+      if (input === null || typeof input !== 'object' || !Object.hasOwn(input, key)) {
+        throw Object.assign(new Error(`JSON Pointer does not exist: ${inputPath}`), { code: 'extraction_path_not_found' });
+      }
+      input = input[key];
+    }
+  }
+  if (typeof input !== 'string') throw Object.assign(new Error('Regex inputPath must select a string.'), { code: 'extraction_input_type' });
+  const expression = new RegExp(pattern, `${flags}g`);
+  const matches = [];
+  let match;
+  while ((match = expression.exec(input)) !== null) {
+    if (matches.length === 1000) throw Object.assign(new Error('Regex exceeded 1000 matches; no partial result was returned.'), { code: 'extraction_match_limit' });
+    matches.push({ match: match[0], groups: Array.from(match).slice(1).map(value => value === undefined ? null : value),
+      namedGroups: Object.fromEntries(Object.entries(match.groups || {}).map(([key, value]) => [key, value === undefined ? null : value])) });
+    if (match[0] === '') {
+      const code = input.codePointAt(expression.lastIndex);
+      expression.lastIndex += flags.includes('u') && code > 0xffff ? 2 : 1;
+    }
+  }
+  return matches;
+}
+
+module.exports = { extractRegex };

package/bin/extraction/runner.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { createScriptSessionChannel } = require('../script/script-session-channel');
+
+const MAX_INPUT_FRAME_BYTES = 8 * 1024 * 1024 + 64 * 1024;
+const MAX_OUTPUT_FRAME_BYTES = 256 * 1024 + 64 * 1024;
+let active = 0;
+
+async function runExtraction(prepared, inputs) {
+  if (active >= 2) return { ok: false, error: 'extraction_busy', message: 'Two extraction workers are active. Retry extraction using the response ref; do not repeat the action.' };
+  active++;
+  let directory, child, channel, timer, exited;
+  let result;
+  let timings = {};
+  let started = performance.now();
+  try {
+    directory = fs.mkdtempSync(path.join(os.tmpdir(), 'aab-extract-'));
+    const python = prepared.language === 'python';
+    const artifact = path.join(directory, python ? 'main.py' : 'main.js');
+    fs.writeFileSync(artifact, prepared.source ?? '');
+    const sdk = path.resolve(__dirname, '../script', python ? 'script-sdk.py' : 'script-sdk.js');
+    started = performance.now();
+    child = spawn(prepared.executable ?? process.execPath, [sdk, artifact], {
+      shell: false, cwd: prepared.cwd, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    channel = createScriptSessionChannel(child, { maxInputFrameBytes: MAX_INPUT_FRAME_BYTES, maxOutputFrameBytes: MAX_OUTPUT_FRAME_BYTES });
+    exited = new Promise(resolve => {
+      child.once('exit', resolve);
+      child.once('error', () => { if (child.pid == null) resolve(); });
+    });
+    const timeout = new Promise(resolve => { timer = setTimeout(() => resolve({ type: 'fail', error: 'extraction_timeout' }), prepared.timeoutMs); });
+    const next = () => Promise.race([channel.nextMessage(), timeout]);
+    let message = await next();
+    if (message.type === 'ready') {
+      timings.coldStartMs = performance.now() - started;
+      channel.send({ type: 'start', inputs, extraction: prepared.mode === 'regex'
+        ? { mode: 'regex', inputPath: prepared.inputPath, pattern: prepared.pattern, flags: prepared.flags }
+        : { mode: 'script' }, sourceName: prepared.filename, entrypoint: 'main' });
+      message = await next();
+    }
+    timings.responseMs = performance.now() - started;
+    if (message.timings) Object.assign(timings, message.timings);
+    if (message.type === 'return' && Object.hasOwn(message, 'result')) {
+      require('./json-value').validateJsonValue(message.result);
+      if (Buffer.byteLength(JSON.stringify(message.result)) > 256 * 1024) result = { ok: false, error: 'extraction_output_too_large' };
+      else result = { ok: true, result: message.result };
+    } else {
+      const code = ['channel_closed', 'stopped'].includes(message.error) ? 'extraction_worker_exited'
+        : message.error === 'frame_too_large' ? 'extraction_frame_too_large'
+        : message.error === 'malformed_frame' ? 'extraction_malformed_frame' : message.error;
+      result = { ok: false, error: typeof code === 'string' && /^extraction_[a-z0-9_]{1,110}$/.test(code) ? code : 'extraction_failed',
+        ...(message.message ? { message: message.message } : {}), ...(message.diagnostic ? { diagnostic: message.diagnostic } : {}) };
+    }
+  } catch (error) {
+    result = { ok: false, error: error.code === 'extraction_type_error' ? error.code : 'extraction_worker_failed', message: error.message };
+  } finally {
+    clearTimeout(timer);
+    channel?.stop();
+    if (exited) await exited;
+    // Descendants may inherit pipes, but are outside the worker lifecycle.
+    // Close our pipe handles after the worker exits instead of waiting for
+    // every descendant to close its copies of stdout/stderr.
+    child?.stdin?.destroy(); child?.stdout?.destroy(); child?.stderr?.destroy();
+    try { if (directory) fs.rmSync(directory, { recursive: true, force: true }); }
+    catch (error) { result = { ok: false, error: 'extraction_cleanup_failed', message: error.message }; }
+    finally { active--; }
+  }
+  const diagnostics = channel?.diagnostics();
+  return { ...result, durationMs: Math.round((performance.now() - started) * 100) / 100, timings,
+    ...(!result.ok && diagnostics && Object.keys(diagnostics).length ? { diagnostics } : {}) };
+}
+
+module.exports = { runExtraction, MAX_INPUT_FRAME_BYTES, MAX_OUTPUT_FRAME_BYTES };

package/bin/intent/install-intent.js

@@ -48,7 +48,9 @@ async function inspectApk(args, run = execute) {
     if (error instanceof CommandError) throw error;
     throw new CommandError('invalid_apk', 'APK manifest or signature verification failed.', { field: 'apkPath', details: { cause: error.code || null } });
   }
-  const pkg = /^package: name='([^']+)' versionCode='([^']+)' versionName='([^']*)'/m.exec(badging.stdout);
+  // AGP-generated instrumentation APKs can omit both version attributes.
+  // Identity still comes from the manifest package, verified signer and bytes.
+  const pkg = /^package: name='([^']+)' versionCode='([0-9]*)' versionName='([^']*)'/m.exec(badging.stdout);
   const certificates = [...new Set([...signatures.stdout.matchAll(/^(?:Signer #\d+|V(?:[124]|3(?:\.[01])?) Signer:) certificate SHA-256 digest: ([a-fA-F0-9]{64})\r?$/gm)].map(match => match[1].toLowerCase()))];
   if (!pkg || !certificates.length) throw new CommandError('invalid_apk', 'The APK has no verified package identity.', { field: 'apkPath' });
   if (args.packageName !== undefined && args.packageName !== pkg[1]) throw new CommandError('apk_package_mismatch', 'packageName differs from the APK manifest.', { field: 'packageName', details: { requested: args.packageName, apk: pkg[1] } });

package/bin/ios-provider.js

@@ -14,7 +14,7 @@ const { isMutationCommand, executionTimeoutMs } = require('./command-registry');
 const { normalizeExecutionTarget } = require('./shared-kernel/execution-target');
 const { descriptorBinding, bindingHeaders, assertRuntimeResponse, bindingFailure } = require('./ios-runtime-binding');
 const { openWdaPort, target: wdaTarget } = require('./ios-wda-port');
-const { prepareWdaProject, wdaBuildEnvironment } = require('./ios-wda-project');
+const { prepareManagedWda, wdaBuildEnvironment } = require('./ios-wda-project');
 const { executeWDAAction, reconcileWDA, completionPort } = require('./ios-wda-execution');
 const { deviceCommandRejection, deviceCommandProof } = require('./ios-device-outcome');
 const { initializationProof } = require('./ios-wda-startup');
@@ -776,8 +776,8 @@ class IOSBridgeProvider {
     if (!teamId) return { ok: false, error: 'ios_team_id_required', message: 'Signing WDA requires an explicit teamId or configured DEVELOPMENT_TEAM.' };
     checkExecution();
     const directory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'aab-wda-runtime-'));
-    const prepared = prepareWdaProject({ destination: path.join(directory, 'source') });
     const ctx = this.context(args);
+    const prepared = await prepareManagedWda();
     const xcodeArgs = ['-project', prepared.projectPath, '-scheme', 'WebDriverAgentRunner', '-sdk', 'iphoneos', '-destination', `id=${device.udid}`,
       '-derivedDataPath', path.join(directory, 'build'), `DEVELOPMENT_TEAM=${teamId}`, `PRODUCT_BUNDLE_IDENTIFIER=${wdaTestBundleId}`,
       'ENABLE_DEFAULT_HEADER_SEARCH_PATHS=NO', '-allowProvisioningUpdates'];

package/bin/ios-wda-project.js

@@ -76,4 +76,51 @@ function prepareWdaProject({ destination, packageDirectory = path.dirname(requir
   return result;
 }
 
-module.exports = { supportedVersion, prepareWdaProject, wdaBuildEnvironment };
+async function prepareManagedWda({ home = require('./executors/managed-runtime').executorHome() } = {}) {
+  const { atomicJson, readJson } = require('./executors/managed-runtime');
+  const bridgeVersion = require('../package.json').version;
+  const hash = createHash('sha256').update(fs.readFileSync(__filename)).update(bridgeVersion).update(supportedVersion);
+  const sourceRoot = path.join(__dirname, '..', 'runtime', 'ios-wda');
+  for (const name of fs.readdirSync(sourceRoot).sort()) hash.update(name).update(fs.readFileSync(path.join(sourceRoot, name)));
+  const nativeRoot = path.dirname(require.resolve('@mobileaidev/segmented-fact-store-native/package.json'));
+  for (const name of ['package.json', 'include/sfs.h', 'src/sfs.c']) hash.update(fs.readFileSync(path.join(nativeRoot, name)));
+  const dependencyDigest = hash.digest('hex');
+  const directory = path.join(home, 'packages', 'ios-wda', dependencyDigest);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const { DatabaseSync } = require('node:sqlite');
+  const lock = new DatabaseSync(path.join(directory, 'prepare.sqlite'));
+  let locked = false;
+  try {
+    try { lock.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE'); locked = true; }
+    catch (error) { if (error.errcode === 5) throw new CommandError('executor_preparing', 'This WDA project is already being prepared.'); throw error; }
+    const readyFile = path.join(directory, 'prepared.json');
+    const existing = readJson(readyFile);
+    const sha256 = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    if (existing) {
+      for (const item of existing.files) {
+        const file = path.join(directory, 'source', item.path);
+        if (!fs.existsSync(file) || sha256(file) !== item.sha256)
+          throw new CommandError('ios_wda_prepared_source_changed', 'The managed WDA source changed after preparation. Select a new executor home to prepare clean source.');
+      }
+      return { ...existing.result, reused: true };
+    }
+    const destination = path.join(directory, 'source');
+    const prepared = prepareWdaProject({ destination });
+    const files = [];
+    function visit(relative) {
+      for (const entry of fs.readdirSync(path.join(destination, relative), { withFileTypes: true })) {
+        const name = path.join(relative, entry.name);
+        if (entry.isDirectory()) visit(name);
+        else if (entry.isFile()) files.push({ path: name, sha256: sha256(path.join(destination, name)) });
+      }
+    }
+    visit('');
+    const result = { ok: true, platform: 'ios', engine: 'wda-xcuitest', bridgeVersion, dependencyDigest, directory,
+      ...prepared, reused: false, lifecycle: 'source-prepared',
+      next: 'Run ios-setup with startWda, deviceId, bundleId and teamId to sign, build and start this managed Runner. Device trust and Enable UI Automation still require the device owner.' };
+    atomicJson(readyFile, { result, files });
+    return result;
+  } finally { if (locked) lock.exec('ROLLBACK'); lock.close(); }
+}
+
+module.exports = { supportedVersion, prepareWdaProject, prepareManagedWda, wdaBuildEnvironment };