@mobileaidev/ai-app-bridge 0.3.7 → 0.4.0

package/README.md

@@ -7,10 +7,11 @@ 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 source version is `0.3.7`; registry publication is a separate release step.
+This source version is `0.4.0`; registry publication is a separate release step.
 The default installation includes the Script/Intent and capture contracts below.
 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 simplest MCP setup and Host requirements](docs/INSTALLATION.md).
 See [the release guide](docs/RELEASE.md) for local packaging and coordinated publication.
 
 Optional Android Instrumentation/UI Automator/Espresso/Compose/H5, Flutter integration_test,
@@ -27,13 +28,17 @@ CLI and MCP connect to one independent local execution runtime. Every registered
 command is available from either entrypoint, including Intent, Script, Web,
 installation and permission flows. A CLI command can start a task and a later MCP
 connection can observe or decide the same operation ID. Disconnecting either
-client leaves tasks running. Use `runtime --operation status` to inspect its
-owner, `runtime --operation stop` to drain it, and task `cancel` to stop one task.
-
-CLI output is `{kind: "json"|"text"|"bytes", value, history?}`. Read the command
-payload from `value`; binary values are base64. Failure uses `value.ok:false` and
-exit code 1. MCP wraps the same payload/history in its content format. See the
-[shared lifecycle and configuration contract](docs/COMMAND_CONTRACT.md#shared-runtime-lifecycle).
+client leaves tasks running. Use `runtime --operation status --extract null` to inspect its
+owner, `runtime --operation stop --extract null` to drain it, and task `cancel` to stop one task.
+
+Each run explicitly supplies `extract`: `null` for the original result, or
+regex/JavaScript/Python for a smaller result. CLI: `--extract null`.
+The compact body is `{command, execution, control, extraction, delivery, kind,
+value?, failureStage?}`. Original execution facts and continuation controls stay
+separate from the extracted value. Default body budget: 96 KiB UTF-8; overflow
+can return a saved response ref. Retry with `response read`, not the original
+action. CLI exits 0 / 1 / 2 for delivery success / execution failure or unknown /
+post-success extraction or delivery failure. See [extraction and recovery](docs/RESPONSE_EXTRACTION.md).
 
 Execution operations and nested controls use strict schemas. Supply an explicit
 `operation`, use `script.target` and canonical `javascript`/`python` languages,
@@ -60,31 +65,31 @@ 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.7
-
-ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge clear-app-data --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge launch-app --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge launch-activity --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample --activity .MainActivity --extra route=/home
-ai-app-bridge screenshot --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge input-text --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample --text "中文输入" --hide-keyboard
-ai-app-bridge network --package-name io.github.mobileaidev.aiappbridge.sample --compact --url-filter /api/
-ai-app-bridge webview-network --package-name io.github.mobileaidev.aiappbridge.sample --duration-ms 3000
-ai-app-bridge ios-devices
-ai-app-bridge ios-doctor --device-id <device-or-udid> --bundle-id <ios.bundle.id> --wda-runner-bundle-id <runner-from-setup>
-ai-app-bridge ios-setup --device-id <device-or-udid> --bundle-id <ios.bundle.id> --team-id <APPLE_TEAM_ID> --start-wda
-ai-app-bridge ios-status --device-id <device-or-udid> --bundle-id <ios.bundle.id>
-ai-app-bridge ios-execution --operation status --device-id <device-or-udid> --bundle-id <ios.bundle.id>
-ai-app-bridge ios-execution --operation reconcile --device-id <device-or-udid> --bundle-id <original.ios.bundle.id>
-ai-app-bridge ios-execution --operation reconcile --kind wda --device-id <device-or-udid> --wda-runner-bundle-id <runner.bundle.id>
-ai-app-bridge ios-wda-session --operation create --device-id <device-or-udid> --wda-runner-bundle-id <runner-from-setup> --bundle-id <ios.bundle.id>
-ai-app-bridge ios-tap --device-id <device-or-udid> --wda-runner-bundle-id <runner-from-setup> --bundle-id <ios.bundle.id> --wda-session-id <created-session> --tap-x 120 --tap-y 360
-ai-app-bridge ios-input --device-id <device-or-udid> --wda-runner-bundle-id <runner-from-setup> --bundle-id <ios.bundle.id> --wda-session-id <created-session> --accessibility-id sample_text_field --clear-first --text "hello"
-ai-app-bridge web-session-start --web-port 18180
-ai-app-bridge runtime --operation status
-ai-app-bridge thaw-app --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
-ai-app-bridge freeze-app --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
+npm install -g @mobileaidev/ai-app-bridge@0.4.0
+
+ai-app-bridge status --extract null --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge tree --extract null --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge clear-app-data --extract null --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge launch-app --extract null --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge launch-activity --extract null --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample --activity .MainActivity --extra route=/home
+ai-app-bridge screenshot --extract null --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge input-text --extract null --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample --text "中文输入" --hide-keyboard
+ai-app-bridge network --extract null --package-name io.github.mobileaidev.aiappbridge.sample --compact --url-filter /api/
+ai-app-bridge webview-network --extract null --package-name io.github.mobileaidev.aiappbridge.sample --duration-ms 3000
+ai-app-bridge ios-devices --extract null
+ai-app-bridge ios-doctor --extract null --device-id <device-or-udid> --bundle-id <ios.bundle.id> --wda-runner-bundle-id <runner-from-setup>
+ai-app-bridge ios-setup --extract null --device-id <device-or-udid> --bundle-id <ios.bundle.id> --team-id <APPLE_TEAM_ID> --start-wda
+ai-app-bridge ios-status --extract null --device-id <device-or-udid> --bundle-id <ios.bundle.id>
+ai-app-bridge ios-execution --extract null --operation status --device-id <device-or-udid> --bundle-id <ios.bundle.id>
+ai-app-bridge ios-execution --extract null --operation reconcile --device-id <device-or-udid> --bundle-id <original.ios.bundle.id>
+ai-app-bridge ios-execution --extract null --operation reconcile --kind wda --device-id <device-or-udid> --wda-runner-bundle-id <runner.bundle.id>
+ai-app-bridge ios-wda-session --extract null --operation create --device-id <device-or-udid> --wda-runner-bundle-id <runner-from-setup> --bundle-id <ios.bundle.id>
+ai-app-bridge ios-tap --extract null --device-id <device-or-udid> --wda-runner-bundle-id <runner-from-setup> --bundle-id <ios.bundle.id> --wda-session-id <created-session> --tap-x 120 --tap-y 360
+ai-app-bridge ios-input --extract null --device-id <device-or-udid> --wda-runner-bundle-id <runner-from-setup> --bundle-id <ios.bundle.id> --wda-session-id <created-session> --accessibility-id sample_text_field --clear-first --text "hello"
+ai-app-bridge web-session-start --extract null --web-port 18180
+ai-app-bridge runtime --extract null --operation status
+ai-app-bridge thaw-app --extract null --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge freeze-app --extract null --serial DEVICE --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge-mcp --help
 ```
 
@@ -203,7 +208,13 @@ Script/Intent history to inspect execution records separately:
 ```json
 {
   "command": "events",
-  "arguments": { "serial": "DEVICE", "packageName": "com.example.app", "history": true, "limit": 100 }
+  "extract": null,
+  "arguments": {
+    "serial": "DEVICE",
+    "packageName": "com.example.app",
+    "history": true,
+    "limit": 100
+  }
 }
 ```
 
@@ -396,10 +407,12 @@ entry point explicitly.
 
 `ai-app-bridge --version` (also `-V`) reads the installed entrypoint's package
 version without requiring a device. Upgrading npm replaces files; it does not
-replace an MCP process already connected to Cursor or another client. Stop the
-shared Runtime with `ai-app-bridge runtime --operation stop` when existing work
-has finished, then reconnect the client's MCP server. The MCP initialize
+replace an MCP process already connected to Cursor or another client. Reconnect
+the client's MCP server after upgrading. Follow the mismatch diagnostic: upgrade
+an older client first; only stop an older Runtime after its existing work finishes,
+using `ai-app-bridge runtime --operation stop --extract null`. The MCP initialize
 response reports `serverInfo.version`; refresh cached tool descriptions in the
 client when they still show removed commands such as `batch` or `smoke`.
-A running Runtime from different source code reports `runtime_code_mismatch`
-until explicitly stopped, so in-flight work is not silently moved to new code.
+A same-version fingerprint mismatch requires aligning the source and Node
+environment; the hash alone does not identify which side is newer. In-flight
+work is not silently moved to new code.

package/bin/ai-app-bridge.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 
-const { CommandError, commandFailure } = require('./command-errors');
+const { CommandError } = require('./command-errors');
 const { commandDefinitions, isolatedCommandDefinitions, parseCliOptions } = require('./command-registry');
-const { commandInputSchema } = require('./command-discovery');
-const { encodeReply } = require('./runtime-protocol');
+const { commandHelpSchema } = require('./command-discovery');
+const { publicFailure, exitCodeFor } = require('./public-reply');
+const { publicOutputLimit } = require('./command-request');
 const runtime = require('./runtime-client');
 
 const helpText = `Usage: ai-app-bridge <command> [options]
@@ -25,14 +26,18 @@ Intent decide also accepts --platform, --provider and --action schema filters.
 CLI flags use kebab-case, for example --package-name, --tap-x, --timeout-ms.
 Objects, arrays, nullable objects and Script decisions use JSON flag values.
 Only --category and --extra repeat as individual strings.
-Results are JSON: {kind: "json"|"text"|"bytes", value, history?}.
-Bytes are base64; value.ok:false exits with code 1. Help is plain text.
+Every command requires --extract: null delivers the command's own result.
+Results are one line of compact JSON: {command, execution, control, extraction,
+delivery, kind: "json"|"text"|"bytes", value, failureStage?}. Bytes are base64.
+Exit 0: delivered as requested. 1: rejected, failed or unknown execution.
+2: the command succeeded but extraction or delivery failed. Help is plain text.
 Relative file paths use the calling directory. Script cwd defaults to it.
-Example: ai-app-bridge script --operation start --script '{"schemaVersion":"aab.code-script/v1","language":"javascript","sourcePath":"./regression.js"}'
+Example: ai-app-bridge script --extract null --operation start --script '{"schemaVersion":"aab.code-script/v1","language":"javascript","sourcePath":"./regression.js","target":{"platform":"android","serial":"<serial>","packageName":"<package>"}}'
 `;
 
 async function main() {
   let command;
+  let maxBytes;
   const connection = new AbortController();
   const disconnect = () => connection.abort();
   process.once('SIGINT', disconnect);
@@ -46,29 +51,61 @@ async function main() {
     if (!argv.length) { process.stdout.write(`${helpText}\n`); return; }
     const parsed = parseArgs(argv);
     command = parsed.command;
+    const envelopeOutput = publicFields({ output: parsed.options.output });
+    maxBytes = publicOutputLimit(envelopeOutput);
+    if (parsed.error) throw parsed.error;
     if (parsed.options.help || command === 'help') {
       const name = command === 'help' ? '' : command;
       const { help, ...filters } = parsed.options;
       if (!name && Object.keys(filters).length) throw new CommandError('invalid_argument', 'Schema filters require a command after --help.', { field: Object.keys(filters)[0] });
-      process.stdout.write(name ? `${JSON.stringify(commandInputSchema(name, filters), null, 2)}\n` : `${helpText}\n`);
+      const schema = name ? commandHelpSchema(name, filters) : null;
+      process.stdout.write(name ? `${JSON.stringify(schema)}\n` : `${helpText}\n`);
+      if (schema?.ok === false) process.exitCode = 1;
       return;
     }
     command ||= 'status';
-    const reply = await runtime.run({ command, arguments: parseCliOptions(command, parsed.options) }, { signal: connection.signal });
-    process.stdout.write(`${JSON.stringify(encodeReply(reply), null, 2)}\n`);
-    if (reply.value?.ok === false) process.exitCode = 1;
+    // The public fields leave the CLI options before the command's own parser
+    // sees them; each is one JSON value and never reaches the device action.
+    const { extract, output, ...options } = parsed.options;
+    const request = { command, ...envelopeOutput };
+    Object.assign(request, publicFields({ extract }));
+    request.arguments = parseCliOptions(command, options);
+    const { value: reply } = await runtime.run(request, { signal: connection.signal });
+    process.stdout.write(`${JSON.stringify(reply)}\n`);
+    process.exitCode = exitCodeFor(reply);
   } catch (error) {
-    process.stdout.write(`${JSON.stringify(encodeReply({ value: commandFailure(error, command) }), null, 2)}\n`);
-    process.exitCode = 1;
+    const reply = publicFailure({ command, stage: 'validation', error, maxBytes });
+    process.stdout.write(`${JSON.stringify(reply)}\n`);
+    process.exitCode = exitCodeFor(reply);
   } finally {
     process.removeListener('SIGINT', disconnect);
     process.removeListener('SIGTERM', disconnect);
   }
 }
 
+// --extract and --output carry JSON. A flag without a value is a missing value,
+// not `true`; the JSON string "null" is not null.
+function publicFields(fields) {
+  const parsed = {};
+  for (const [name, raw] of Object.entries(fields)) {
+    if (raw === undefined) continue;
+    if (raw === true) throw new CommandError('missing_argument', `--${name} requires one JSON value${name === 'extract' ? '; use --extract null for this command\'s own result' : ''}.`, { field: name });
+    try { parsed[name] = JSON.parse(raw); }
+    catch { throw new CommandError('invalid_argument', `--${name} must be one JSON value${name === 'extract' ? ', for example null' : ''}: ${raw}`, { field: name }); }
+  }
+  return parsed;
+}
+
 function parseArgs(argv) {
   const options = {};
   let command = '';
+  let error;
+  // Finish reading named tokens after a lexical error so its reply can still
+  // honor a valid output budget. The first error rejects the entire request.
+  const append = (name, value) => {
+    try { appendOption(options, name, value); }
+    catch (cause) { error ||= cause; }
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (!arg.startsWith('--') && !command) {
@@ -76,22 +113,24 @@ function parseArgs(argv) {
       continue;
     }
     if (!arg.startsWith('--')) {
-      throw new CommandError('unexpected_argument', `Unexpected positional argument: ${arg}. Supply values through named flags.`, { field: `argv[${index}]` });
+      error ||= new CommandError('unexpected_argument', `Unexpected positional argument: ${arg}. Supply values through named flags.`, { field: `argv[${index}]` });
+      continue;
     }
     const rawName = arg.slice(2);
     if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(rawName)) {
-      throw new CommandError('invalid_argument', `Invalid CLI flag: ${arg}. Use --kebab-case flags followed by separate value tokens.`, { field: `argv[${index}]` });
+      error ||= new CommandError('invalid_argument', `Invalid CLI flag: ${arg}. Use --kebab-case flags followed by separate value tokens.`, { field: `argv[${index}]` });
+      continue;
     }
     const name = rawName.replace(/-([a-z])/g, (_, value) => value.toUpperCase());
     const next = argv[index + 1];
     if (name === 'help' || next === undefined || next.startsWith('--')) {
-      appendOption(options, name, true);
+      append(name, true);
       continue;
     }
-    appendOption(options, name, next);
+    append(name, next);
     index += 1;
   }
-  return { command, options };
+  return { command, options, ...(error ? { error } : {}) };
 }
 
 function appendOption(options, name, value) {

package/bin/command-discovery.js

@@ -27,7 +27,19 @@ const commandDomains = {
 };
 const supportedTargetsText = `AI App Bridge supports ${supportedTargets.join('; ')}.`;
 const commandDomainsText = `Command domains: ${Object.entries(commandDomains).map(([domain, summary]) => `${domain}(${summary})`).join('; ')}.`;
-const discoveryText = 'Use capabilities with a domain for a command directory, then request one command and operation when applicable. For intent decide, narrow by the actual platform, provider and action. Omit filters for the complete command contract; includeOptions:true explicitly expands a directory. Execute with run and command-specific arguments.';
+const discoveryText = 'Use capabilities with a domain for a command directory, then request one command and operation when applicable. For intent decide, narrow by the actual platform, provider and action. Discovery output is limited to 96 KiB; narrow the query if a full schema or includeOptions:true exceeds this budget. Execute with run, command-specific arguments and explicit extract.';
+
+function discoveryBudget(value) {
+  const limitBytes = require('./public-reply').DEFAULT_OUTPUT_BYTES;
+  const attemptedBytes = Buffer.byteLength(JSON.stringify(value));
+  if (attemptedBytes <= limitBytes) return value;
+  return { ok: false, error: 'discovery_output_too_large', attemptedBytes, limitBytes,
+    message: 'Request a command directory without includeOptions, then one command and operation. For intent decide, add platform/provider/action. No schema was truncated.',
+    filters: ['domain', 'command', ...schemaFilterNames], example: { command: 'intent', operation: 'start' } };
+}
+
+function capabilities(args) { return discoveryBudget(capabilityPayload(args)); }
+function commandHelpSchema(command, filters) { return discoveryBudget(commandInputSchema(command, filters)); }
 function capabilityPayload(args = {}) {
   if (!args || typeof args !== 'object' || Array.isArray(args)) return { ok: false, error: 'invalid_argument', field: 'arguments', dispatched: false, ambiguous: false };
   const invalidKey = Object.keys(args).find(key => !['command', 'domain', 'includeOptions', ...schemaFilterNames].includes(key));
@@ -46,7 +58,7 @@ function capabilityPayload(args = {}) {
       return {
         ok: Boolean(definition),
         command: requestedCommand,
-        ...(definition ? shapeCommandDefinition(definition, true, filters) : { error: 'unknown_command' }),
+        ...(definition ? shapeCommandDefinition(definition, true, filters) : { error: 'unknown_command', message: `Unknown command: ${requestedCommand}. Omit command, or pass a domain, to list the command directory.` }),
       };
     } catch (error) {
       if (!(error instanceof CommandError)) throw error;
@@ -56,7 +68,10 @@ function capabilityPayload(args = {}) {
 
   const requestedDomain = args.domain ? String(args.domain) : '';
   const domains = {};
-  if (requestedDomain && !Object.hasOwn(commandDomains, requestedDomain)) return { ok: false, error: 'unknown_domain', field: 'domain', dispatched: false, ambiguous: false };
+  if (requestedDomain && !Object.hasOwn(commandDomains, requestedDomain)) {
+    return { ok: false, error: 'unknown_domain', field: 'domain', dispatched: false, ambiguous: false,
+      message: `Unknown domain: ${requestedDomain}. Domains: ${Object.keys(commandDomains).join(', ')}. android is a platform, not a domain: platform, provider and action narrow intent decide schemas, e.g. {"command":"intent","operation":"decide","platform":"android","provider":"native","action":"tap"}.` };
+  }
   for (const definition of [...isolatedCommandDefinitions, ...commandDefinitions]) {
     if (requestedDomain && definition.domain !== requestedDomain) continue;
     if (!domains[definition.domain]) domains[definition.domain] = [];
@@ -139,4 +154,4 @@ function shapeCommandDefinition(definition, includeOptions, filters = {}) {
 
 
 function normalizeCommandName(value) { return typeof value === 'string' ? value : ''; }
-module.exports = { capabilities: capabilityPayload, commandInputSchema, commandDomains, supportedTargets, supportedTargetsText, commandDomainsText, discoveryText };
+module.exports = { capabilities, commandInputSchema, commandHelpSchema, commandDomains, supportedTargets, supportedTargetsText, commandDomainsText, discoveryText };

package/bin/command-registry.js

@@ -8,6 +8,8 @@ const { executionCommandSchema, nativeGestureSchema, nativeSelector, flutterSele
 const { flutterActionSchema, webCommandSchema } = require('./shared-kernel/provider-command-contracts');
 
 const commandDefinitions = [
+  { command: 'response', domain: 'evidence', summary: 'Read and re-extract one saved response using its unchanged control.source.ref. This never repeats the original action or refreshes an observation.', targetKind: 'host', options: ['operation', 'ref'] },
+  { command: 'executor-prepare', domain: 'advanced', summary: 'Prepare optional test executors from the existing project: generate Android androidTest entry/dependencies and matching APKs, add Flutter dev dependency and build the generated entrypoint, prepare managed iOS WDA, or install pinned Playwright/browser. Host preparation does not install or launch a mobile application. No application ID is changed. Requires app.test in Script.', targetKind: 'host', options: ['platform'] },
   { 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'] },
@@ -151,6 +153,7 @@ const isolatedCommandDefinitions = [
 ];
 
 const mutationCommands = new Set([
+  'executor-prepare',
   'install-apk', 'clear-app-data', 'freeze-app', 'thaw-app', 'launch-app',
   'launch-activity', 'permission-grant',
   'permission-revoke', 'permission-dialog', 'appops-set',
@@ -254,12 +257,13 @@ function isMutationCommand(command, args = {}) {
 }
 
 function isAndroidMutation(command, args = {}) {
-  return isMutationCommand(command, args) && !['runtime', 'device-ownership'].includes(command)
+  return isMutationCommand(command, args) && !['runtime', 'device-ownership', 'executor-prepare'].includes(command)
     && !command.startsWith('ios-') && !command.startsWith('web-');
 }
 
 function executionTimeoutMs(command, args = {}) {
   if (args.timeoutMs !== undefined) return args.timeoutMs;
+  if (command === 'executor-prepare') return 600000;
   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;
@@ -273,7 +277,7 @@ 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.test': ['web-executor', 'android-executor', 'flutter-executor', 'executor-prepare'],
   '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': ['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'],
@@ -287,14 +291,23 @@ const workflowCommands = new Set(['install-apk', 'permission-dialog']);
 const permissionCommands = new Set(['permission-state', 'permission-grant', 'permission-revoke']);
 const expertCommands = new Set(['uia-runtime', 'freeze-app', 'thaw-app', 'flutter-action', 'h5-eval', 'flutter-h5-eval', 'ios-h5-eval', 'ios-flutter-action', 'ios-setup', 'web-command', 'forward', 'remove-forward', 'webview-pages', 'appops-set', 'permission-grant', 'permission-revoke']);
 const deviceCommands = new Set(['uia-tree', 'screenshot', 'tap', 'tap-uia-text', 'keyboard-state', 'hide-keyboard', 'swipe', 'keyevent', 'logcat', 'permission-dialog', 'install-apk', 'remove-forward']);
+// Discovery is a recorded misuse of run: point at the discovery entry instead of
+// only rejecting the name.
+function unknownCommand(command) {
+  const message = command === 'capabilities'
+    ? 'capabilities is the discovery tool, not a run command. Call the capabilities tool (CLI: --help <command>) with an optional domain or command filter, then run one of the listed command names.'
+    : `Unknown command: ${command}. List command names with the capabilities tool (CLI: ai-app-bridge help).`;
+  return new CommandError('unknown_command', message, { field: 'command' });
+}
+
 function commandContract(command) {
   const definition = commandByName.get(command) || isolatedByName.get(command);
-  if (!definition) throw new CommandError('unknown_command', `Unknown command: ${command}`, { field: 'command' });
+  if (!definition) throw unknownCommand(command);
   const isolated = isolatedByName.has(command);
-  const platform = command === 'runtime' ? 'host' : isolated ? (command === 'evidence' ? 'host' : 'multi')
+  const platform = ['runtime', 'executor-prepare', 'response'].includes(command) ? 'host' : isolated ? (command === 'evidence' ? 'host' : 'multi')
     : definition.domain === 'ios' ? 'ios' : definition.domain === 'web' ? 'web' : 'android';
   const role = command === 'runtime' || command === 'intent' || command === 'script' || workflowCommands.has(command) ? 'execution'
-    : command === 'evidence' ? 'evidence' : expertCommands.has(command) ? 'expert' : 'capability';
+    : ['evidence', 'response'].includes(command) ? 'evidence' : expertCommands.has(command) ? 'expert' : 'capability';
   const permission = scriptPermissionByCommand.get(command) || null;
   return {
     role, platform,
@@ -316,7 +329,9 @@ 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 (!definition) throw unknownCommand(command);
+  if (command === 'response') return require('./response-store').responseSchema();
+  if (command === 'executor-prepare') return require('./executors/preparation').preparationSchema();
   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();

package/bin/command-request.js

@@ -2,13 +2,77 @@
 
 const { CommandError } = require('./command-errors');
 const { validateCommandArguments } = require('./command-registry');
+const { validateValue } = require('./shared-kernel/argument-schema');
+
+// The public run request shared by MCP and the CLI. Business arguments stay
+// under `arguments`; `extract` and `output` never reach a device action.
+const extractSchema = {
+  description: 'Required. Use null for this command\'s result within the output budget, or regex/script to extract a smaller result on the Host. Execution and control facts remain separate. On overflow or extraction failure, use a returned response ref to retry extraction; do not repeat the action.',
+  oneOf: [
+    { type: 'null' },
+    {
+      type: 'object', additionalProperties: false,
+      required: ['mode', 'pattern', 'inputPath'],
+      properties: {
+        mode: { const: 'regex' },
+        pattern: { type: 'string', minLength: 1, maxLength: 2048 },
+        flags: { type: 'string', pattern: '^[imsu]*$', description: 'Unique JavaScript RegExp flags. The Host returns all matches; g/y are not accepted.' },
+        inputPath: { type: 'string', description: 'JSON Pointer to a string in the response. Empty string selects a text response.' },
+        timeoutMs: { type: 'integer', minimum: 1, maximum: 10000 },
+      },
+    },
+    {
+      type: 'object', additionalProperties: false,
+      required: ['mode', 'language'],
+      properties: {
+        mode: { const: 'script' },
+        language: { enum: ['javascript', 'python'] },
+        source: { type: 'string', minLength: 1, maxLength: 65536, description: 'main(ctx). ctx.inputs contains kind, response, execution, control. Return a JSON value.' },
+        sourcePath: { type: 'string', minLength: 1, description: 'Resolve from the caller cwd and freeze source before dispatch. Exactly one of source/sourcePath.' },
+        timeoutMs: { type: 'integer', minimum: 1, maximum: 10000 },
+      },
+      oneOf: [{ required: ['source'] }, { required: ['sourcePath'] }],
+    },
+  ],
+};
+const outputSchema = {
+  type: 'object', additionalProperties: false, required: ['maxBytes'],
+  properties: { maxBytes: { type: 'integer', minimum: 16384, maximum: 262144 } },
+};
+
+function publicRequestSchema() {
+  return {
+    type: 'object', additionalProperties: false, required: ['command', 'extract'],
+    properties: {
+      command: { type: 'string', minLength: 1 },
+      arguments: { type: 'object', additionalProperties: true },
+      extract: extractSchema,
+      output: outputSchema,
+    },
+  };
+}
+
+// Preserve a valid caller budget even when another part of the request fails
+// validation. Invalid output is still reported by validateRunRequest.
+function publicOutputLimit(args) {
+  if (!args || !Object.hasOwn(args, 'output')) return undefined;
+  try { validateValue(args.output, outputSchema, 'output'); }
+  catch { return undefined; }
+  return args.output.maxBytes;
+}
 
 function validateRunRequest(args) {
   if (!args || typeof args !== 'object' || Array.isArray(args)) throw new CommandError('invalid_argument', 'run requires an object.', { field: 'arguments' });
-  const extra = Object.keys(args).find(key => key !== 'command' && key !== 'arguments');
-  if (extra) throw new CommandError('unsupported_argument', 'Put all command parameters in run.arguments.', { field: extra });
+  const extra = Object.keys(args).find(key => !['command', 'arguments', 'extract', 'output'].includes(key));
+  if (extra) throw new CommandError('unsupported_argument', 'Put all command parameters in run.arguments; only command, arguments, extract and output are top-level fields.', { field: extra });
+  if (!Object.hasOwn(args, 'extract')) {
+    throw new CommandError('missing_argument', 'extract is required. Pass null (CLI: --extract null) to deliver this command\'s own result, or a regex/script extraction. Nothing was dispatched.', { field: 'extract' });
+  }
+  validateValue(args.extract, extractSchema, 'extract');
+  if (Object.hasOwn(args, 'output')) validateValue(args.output, outputSchema, 'output');
   const command = typeof args.command === 'string' ? args.command : '';
-  return { command, arguments: validateCommandArguments(command, args.arguments === undefined ? {} : args.arguments) };
+  return { command, arguments: validateCommandArguments(command, args.arguments === undefined ? {} : args.arguments), extract: args.extract,
+    ...(args.output ? { output: args.output } : {}) };
 }
 
-module.exports = { validateRunRequest };
+module.exports = { validateRunRequest, publicRequestSchema, publicOutputLimit, extractSchema, outputSchema };

package/bin/execution-host.js

@@ -1,9 +1,11 @@
 'use strict';
 
 const { executeProviderCommand } = require('./device-provider');
-const { validateRunRequest } = require('./command-request');
+const { validateRunRequest, publicOutputLimit } = require('./command-request');
 const { resolveCommandPaths } = require('./shared-kernel/request-context');
 const { commandFailure, normalizeCommandResult } = require('./command-errors');
+const { publicReply, publicFailure, responseReply, finishReply, boundedReply } = require('./public-reply');
+const { prepareExtraction } = require('./extraction/prepare');
 const { runExecution, withoutExecution } = require('./shared-kernel/execution-scope');
 const { getHostFactStore } = require('./shared-kernel/host-fact-store');
 const { FactRecorder, historyDescriptor, isMobileCaptureCommand } = require('./fact-recorder');
@@ -35,8 +37,9 @@ let closing = false;
 const activeRuns = new Set();
 
 // Callers share one execution host. The owning process controls its lifecycle.
+// Every reply is the public reply of the request, assembled exactly once here.
 function run(args, dependencies) {
-  if (closing) return Promise.resolve(valueReply({ ok: false, error: 'runtime_stopping', dispatched: false, ambiguous: false }));
+  if (closing) return Promise.resolve({ value: boundedReply(publicReply({ command: requestedCommand(args), reply: valueReply({ ok: false, error: 'runtime_stopping', dispatched: false, ambiguous: false }) })) });
   const task = runGeneric(args, dependencies);
   activeRuns.add(task);
   task.then(() => activeRuns.delete(task), () => activeRuns.delete(task));
@@ -147,11 +150,30 @@ function wrapIsolatedEntry(entry, namespace) {
   };
 }
 
+function requestedCommand(args) {
+  return typeof args?.command === 'string' ? args.command : undefined;
+}
+
 async function runGeneric(args = {}, dependencies = {}) {
+  const command = requestedCommand(args);
+  const maxBytes = publicOutputLimit(args);
+  let request;
+  let commandArguments;
+  let extract;
+  try {
+    request = validateRunRequest(args);
+    commandArguments = resolveCommandPaths(request.command, request.arguments);
+    extract = prepareExtraction(request.extract);
+  } catch (error) { return { value: publicFailure({ command, stage: 'validation', error, maxBytes }) }; }
   try {
-    const request = validateRunRequest(args);
-    return commandRouter.route(request.command, resolveCommandPaths(request.command, request.arguments), dependencies);
-  } catch (error) { return valueReply(commandFailure(error, typeof args?.command === 'string' ? args.command : undefined)); }
+    const getStore = () => dependencies.responseStore || getResponseStore();
+    if (command === 'response') {
+      const frozen = getStore().read(commandArguments.ref);
+      return { value: await finishReply({ body: responseReply(frozen), extract, output: request.output, frozen }) };
+    }
+    const reply = await commandRouter.route(request.command, commandArguments, dependencies);
+    return { value: await finishReply({ body: publicReply({ command: request.command, reply, completed: true }), extract, output: request.output, getStore }) };
+  } catch (error) { return { value: publicFailure({ command: request.command, stage: 'execution', error, maxBytes: request.output?.maxBytes }) }; }
 }
 
 async function runCommand(command, args = {}, dependencies = {}) {
@@ -538,6 +560,10 @@ function getSharedFactStore() {
   return sharedFactStore;
 }
 
+function getResponseStore() {
+  return require('./response-store').createResponseStore({ adapter: createSegmentedEvidenceAdapter(getSharedFactStore()) });
+}
+
 function getSharedFactRecorder() {
   if (String(process.env.AI_APP_BRIDGE_FACT_CACHE || '').toLowerCase() === 'off') return null;
   if (sharedFactRecorder) return sharedFactRecorder;
@@ -585,6 +611,7 @@ function getSharedObservationCollector(factRecorder) {
 }
 
 async function runRawCommand(command, args = {}) {
+  if (command === 'executor-prepare') return require('./executors/preparation').prepareExecutor(args);
   if (command === 'android-executor') {
     androidExecutor ||= new (require('./executors/android-host').AndroidExecutorHost)();
     return androidExecutor.run(args);

package/bin/execution-runtime.js

@@ -6,6 +6,7 @@ const path = require('node:path');
 const http = require('node:http');
 const { randomBytes, randomUUID } = require('node:crypto');
 const { CommandError, commandFailure } = require('./command-errors');
+const { publicFailure } = require('./public-reply');
 const { protocol, maxMessageBytes, encodeReply, readJson } = require('./runtime-protocol');
 const { runtimeLocation, runtimeIdentity, acquireRuntimeLock, publishEndpoint } = require('./runtime-directory');
 const { inRequestDirectory } = require('./shared-kernel/request-context');
@@ -24,21 +25,28 @@ async function start() {
   const status = () => ({ ok: true, command: 'runtime', status: phase, runtimeId, pid: process.pid, identity,
     startedAtMs, facts: location.facts, profile: location.profile, node: { executable: process.execPath, version: process.version } });
   const server = http.createServer(async (request, response) => {
+    // Execute replies are public replies; a failure of the execute path itself
+    // is wrapped the same way. Status and stop keep their internal shape.
+    let message = null;
+    const executing = () => message?.method === 'execute';
+    const commandOf = () => (typeof message?.arguments?.command === 'string' ? message.arguments.command : undefined);
     const send = reply => {
       if (response.destroyed) return;
-      let message;
-      try { message = JSON.stringify({ protocol, runtimeId, reply: encodeReply(reply) }); }
-      catch (error) { message = JSON.stringify({ protocol, runtimeId, reply: encodeReply({ value: commandFailure(error) }) }); }
-      if (Buffer.byteLength(message) > maxMessageBytes) message = JSON.stringify({ protocol, runtimeId,
-        reply: encodeReply({ value: { ok: false, error: 'runtime_message_too_large', dispatched: null, ambiguous: true } }) });
+      let body;
+      try { body = JSON.stringify({ protocol, runtimeId, reply: encodeReply(reply) }); }
+      catch (error) { body = JSON.stringify({ protocol, runtimeId, reply: encodeReply(failure(error)) }); }
+      if (Buffer.byteLength(body) > maxMessageBytes) {
+        body = JSON.stringify({ protocol, runtimeId, reply: encodeReply(failure(new CommandError('runtime_message_too_large', 'Runtime messages are limited to 128 MiB.', { dispatched: null, ambiguous: true }))) });
+      }
       response.writeHead(200, { 'Content-Type': 'application/json', Connection: 'close' });
-      response.end(message);
+      response.end(body);
     };
+    const failure = error => (executing() ? { value: publicFailure({ command: commandOf(), stage: 'execution', error }) } : { value: commandFailure(error) });
     try {
       if (request.headers.authorization !== `Bearer ${token}` || request.method !== 'POST' || request.url !== '/rpc') {
         request.resume(); throw new CommandError('runtime_access_denied', 'The local runtime connection is not authenticated.');
       }
-      const message = await readJson(request);
+      message = await readJson(request);
       if (!message || typeof message !== 'object' || Array.isArray(message)
         || Object.keys(message).some(key => !['protocol', 'runtimeId', 'method', 'identity', 'arguments', 'cwd'].includes(key))
         || message.protocol !== protocol || message.runtimeId !== runtimeId) throw new CommandError('runtime_protocol_error', 'Runtime request identity or fields are invalid.');
@@ -46,8 +54,7 @@ async function start() {
       if (message.method === 'stop') { await stop(); send({ value: status() }); return; }
       if (message.method !== 'execute') throw new CommandError('runtime_protocol_error', 'Unknown runtime method.');
       if (phase !== 'running') throw new CommandError('runtime_stopping', 'The runtime is stopping.');
-      if (message.identity?.code !== identity.code) throw new CommandError('runtime_code_mismatch', 'The runtime and client use different code.');
-      if (message.identity?.config !== identity.config) throw new CommandError('runtime_configuration_mismatch', 'The runtime and client use different configuration.');
+      require('./runtime-directory').requireCompatible({ identity, runtimeId, pid: process.pid }, message.identity);
       let validDirectory = false;
       if (typeof message.cwd === 'string' && path.isAbsolute(message.cwd)) {
         try { validDirectory = fs.statSync(message.cwd).isDirectory(); }
@@ -57,7 +64,7 @@ async function start() {
       // Closing this HTTP connection never cancels the admitted work. Its
       // original runtime, deadline and explicit cancel operation own settlement.
       send(await inRequestDirectory(message.cwd, () => host.run(message.arguments)));
-    } catch (error) { send({ value: commandFailure(error) }); }
+    } catch (error) { send(failure(error)); }
   });
   server.requestTimeout = 30000;
   server.headersTimeout = 10000;