@mobileaidev/ai-app-bridge 0.3.8 → 0.4.1

package/bin/executors/preparation.js

@@ -66,9 +66,9 @@ async function withProject(projectDir, action, { home = executorHome() } = {}) {
       return result;
     } catch (error) {
       const result = { ok: false, bridgeVersion, directory, error: error.code || 'executor_prepare_failed',
-        message: error.message, elapsedMs: Date.now() - startedAtMs };
+        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: { directory, resultFile: path.join(directory, 'result.json') } });
+      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(); }
 }
@@ -111,21 +111,35 @@ async function prepareAndroid(args, { run = execFileBounded, home } = {}) {
     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');
-    await loggedRun(run, 'sh', [wrapper, '--init-script', template, `-Daab.prepare.config=${configFile}`,
+    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 });
+    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,
+    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: [],

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.cleanupError = error.code || 'extraction_cleanup_failed'; }
+    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/ios-execution.js

@@ -93,6 +93,12 @@ async function reconcileIOS({ lease, device, args, createPort, readWdaTestSummar
       } catch (error) { return { settled: false, error: 'ios_wda_startup_completion_unavailable', cause: error.code || 'invalid_result' }; }
     }
     if (args.setupResultPath) return { settled: false, error: 'ios_original_completion_identity_required' };
+    if (pending.kind === 'ios-command' && pending.command === 'ios-ui-observation') {
+      // Older Hosts incorrectly journaled bounded capture control as a device
+      // action. Retire only that marker; its observation outcome remains unknown.
+      return { kind: 'ios-ui-observation', settled: true, dispatched: null,
+        reason: 'observation_control_not_device_mutation', observationOutcome: 'unknown' };
+    }
     if (pending.kind === 'ios-command') {
       const invocation = pending.invocation;
       const index = Array.isArray(invocation?.arguments) ? invocation.arguments.indexOf('--json-output') : -1;

package/bin/ios-provider.js

@@ -96,7 +96,7 @@ class IOSBridgeProvider {
         case 'ios-status':
           return await this.runtimeGet(args, '/v1/status');
         case 'ios-ui-observation': {
-          const port = await this.runtimePort(args, context);
+          const port = await this.runtimePort(args, { ...context, mutation: false });
           const result = await port.post(require('./ui-observation').path(args), require('./ui-observation').request(args));
           return { ...result, endpoint: port.endpoint.baseUrl, device: port.endpoint.device, runtimeBinding: port.endpoint.runtimeBinding };
         }
@@ -445,7 +445,8 @@ class IOSBridgeProvider {
 
   async runtimePort(args, options = {}) {
     const endpoint = await this.resolveRuntimeEndpoint(args, options);
-    const httpOptions = { timeoutMs: this.context(args).httpTimeoutMs, headers: bindingHeaders(endpoint.runtimeBinding) };
+    const httpOptions = { timeoutMs: this.context(args).httpTimeoutMs, headers: bindingHeaders(endpoint.runtimeBinding),
+      ...(options.mutation === false ? { mutation: false } : {}) };
     const request = async (method, endpointPath, payload) => {
       let response;
       try {

package/bin/mcp-server.js

@@ -3,6 +3,7 @@
 const packageInfo = require('../package.json');
 const runtimeClient = require('./runtime-client');
 const discovery = require('./command-discovery');
+const { publicRequestSchema } = require('./command-request');
 const clientConnection = new AbortController();
 const { supportedTargets, commandDomains, supportedTargetsText, commandDomainsText, discoveryText } = discovery;
 const supportedProtocolVersions = ['2025-06-18', '2024-11-05'];
@@ -10,6 +11,8 @@ const defaultProtocolVersion = supportedProtocolVersions[0];
 const serverInstructions = [
   'Intent, Script and individual commands share one runtime across CLI and MCP. Disconnecting a client leaves operations running; explicit task cancel or runtime stop owns cancellation. Platform capabilities do not imply full complex-App acceptance.',
   'Use script status/wait for progress and resultRef; read the final output with script operation=result and the same operationId, including after runtime restart. A completed execution is separate from the business verdict.',
+  'run requires extract: null delivers the command\'s own result. Every run reply is {command, execution, control, extraction, delivery, kind, value, failureStage?}: execution holds the command\'s ok/error and dispatch facts, control the fields needed to continue (operationId, status, eventSequence, history cursor), and value the original result including _feedback. Read failureStage first when isError is set.',
+  'For large UI/network/log results, choose a focused regex or JS/Python extraction; scripts receive ctx.inputs={kind,response,execution,control} without ctx.call. Default final-body budget is 96 KiB. On extraction failure or overflow, only a persisted control.source.ref can be read with response operation=read and a new extract. Never repeat the original action to repair extraction. control.pendingQuestion retains a current Script question even when events are filtered.',
   supportedTargetsText,
   discoveryText,
   'Prefer AI App Bridge over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, permissions, or app-level Web evidence.',
@@ -30,7 +33,7 @@ MCP surface:
 Discovery:
   1. Call capabilities with optional domain or command filters.
   2. Call run with a command name from capabilities.
-  3. Put command-specific options in arguments.
+  3. Put command-specific options in arguments; pass extract (null for the command's own result).
 
 Target ids:
   Android app commands require packageName; port selects only the host forwarding port.
@@ -41,8 +44,8 @@ Target ids:
 Examples:
   capabilities { "domain": "webview" }
   capabilities { "command": "intent", "operation": "start" }
-  run { "command": "screenshot", "arguments": { "packageName": "com.example.app" } }
-  run { "command": "web-session-start", "arguments": { "webPort": 18180 } }
+  run { "command": "screenshot", "extract": null, "arguments": { "packageName": "com.example.app" } }
+  run { "command": "web-session-start", "extract": null, "arguments": { "webPort": 18180 } }
 `;
 let buffer = Buffer.alloc(0);
 let responseFormat = null;
@@ -247,10 +250,8 @@ function toolDefinitions() {
         provider: { enum: ['native', 'uia', 'flutter', 'h5'], description: 'Intent decide schema scope only; must be supported by the selected platform.' },
         action: { type: 'string', description: 'Intent decide schema scope only, for example tap or inputText.' },
       } } },
-    { name: 'run', description: 'Execute a command from capabilities. All command parameters, including target identity, belong in arguments.',
-      inputSchema: { type: 'object', additionalProperties: false, required: ['command'], properties: {
-        command: { type: 'string' }, arguments: { type: 'object', additionalProperties: true },
-      } } },
+    { name: 'run', description: 'Execute a command from capabilities. All command parameters, including target identity, belong in arguments. extract is required: null delivers the command\'s own result. The reply is {command, execution, control, extraction, delivery, kind, value, failureStage?}; the original result, including _feedback, is value.',
+      inputSchema: publicRequestSchema() },
   ];
 }
 
@@ -263,23 +264,16 @@ async function callTool(name, args) {
   return toolJson({ ok: false, error: 'unknown_tool', message: `Unknown tool: ${name}. Use capabilities or run.`, dispatched: false, ambiguous: false }, true);
 }
 
-// MCP only adapts the shared execution reply to its tool-result format.
+// MCP only adapts the public reply to its tool-result format: the text is the
+// compact public reply, isError follows failureStage. Nothing is duplicated
+// into structuredContent or _meta.
 const capabilityPayload = discovery.capabilities;
 async function runGeneric(args = {}) {
   return toolResultForReply(await runtimeClient.run(args, { signal: clientConnection.signal }));
 }
 
-function toolResultForReply({ value: result, history }) {
-  let tool;
-  if (typeof result === 'string') tool = toolText(result);
-  else if (Buffer.isBuffer(result)) tool = toolText(result.toString('utf8'));
-  else if (result === undefined) tool = toolJson({ ok: false, error: 'runtime_result_missing', dispatched: null, ambiguous: true }, true);
-  else {
-    if (history && result && typeof result === 'object' && !Array.isArray(result)) result = { ...result, _history: history };
-    tool = toolJson(result, Boolean(result && typeof result === 'object' && result.ok === false));
-  }
-  if (history) tool._meta = { 'ai-app-bridge/history': history };
-  return tool;
+function toolResultForReply({ value: reply }) {
+  return toolJson(reply, Boolean(reply.failureStage));
 }
 
 function toolText(text, isError = false) {
@@ -294,8 +288,9 @@ function toolText(text, isError = false) {
   };
 }
 
+// Compact JSON: indentation is context cost for the calling model, not information.
 function toolJson(value, isError = false) {
-  return toolText(JSON.stringify(value, null, 2), isError);
+  return toolText(JSON.stringify(value), isError);
 }
 
 function sendResult(id, result) {

package/bin/public-reply.js

@@ -0,0 +1,184 @@
+'use strict';
+
+const { commandFailure } = require('./command-errors');
+const { encodeReply } = require('./runtime-protocol');
+const { randomUUID } = require('node:crypto');
+const DEFAULT_OUTPUT_BYTES = 96 * 1024;
+
+// The public reply of one run request, assembled once at the Runtime boundary
+// and by the client for its local paths. The original result stays in `value`
+// (including `_feedback`); execution facts and the fields needed to continue
+// are copied next to it so an extraction cannot hide them.
+
+const executionKeys = ['ok', 'error', 'message', 'field', 'details', 'dispatched', 'ambiguous', 'settled',
+  'executionReceipt', 'executionReceipts', 'exitCode', 'target', 'matched', 'verified', 'inconclusive'];
+// Continuation fields per response family. Only fields the response actually
+// carries are copied; a business field of the same name in `value` is not one.
+const scriptControlKeys = ['operationId', 'status', 'pauseReason', 'eventSequence', 'resultRef', 'persisted', 'timedOut', 'waitMs', 'pendingQuestion'];
+const intentControlKeys = ['operationId', 'status', 'revision', 'lastDecisionId', 'eventSequence', 'eventGap', 'droppedEvents', 'evidenceId',
+  'latestEvidenceIds', 'terminalEvidenceId', 'observationFailure', 'provider', 'observationTarget', 'deadlineMs', 'pendingOperations', 'lastAction'];
+const commonControlKeys = ['cursor', 'nextCursor', 'factCursor', 'hasMore', 'truncated', 'dropped', 'gap', 'updatedAtMs', 'observedAtMs', 'capturedAtMs'];
+const intentCommands = new Set(['intent', 'install-apk', 'permission-dialog']);
+const captureCommands = new Set(['logs', 'network', 'state', 'events', 'ios-logs', 'ios-network', 'ios-state', 'ios-events',
+  'web-logs', 'web-network', 'web-state', 'web-events', 'webview-console', 'webview-network']);
+const captureControlKeys = ['stream', 'coverage', 'window', 'runtimeEpoch', 'targetKey', 'storeGeneration', 'watermarkCursor',
+  'throughWatermark', 'barrier', 'committed'];
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && !Buffer.isBuffer(value);
+}
+
+function pick(source, keys) {
+  return Object.fromEntries(keys.filter(key => source[key] !== undefined).map(key => [key, source[key]]));
+}
+
+// The invoking layer can confirm completion for raw JSON/text/bytes. An object
+// response must carry its own execution outcome; missing ok remains unknown.
+function executionFacts(value, completed) {
+  if (!isRecord(value)) return { ok: completed ? true : null };
+  const facts = pick(value, executionKeys);
+  if (facts.ok === undefined) facts.ok = null;
+  return facts;
+}
+
+function controlFacts(command, value, history) {
+  const control = {};
+  if (isRecord(value)) {
+    if (command === 'script') Object.assign(control, pick(value, scriptControlKeys));
+    else if (intentCommands.has(command)) Object.assign(control, pick(value, intentControlKeys));
+    else Object.assign(control, pick(value, commonControlKeys));
+    if (captureCommands.has(command)) {
+      Object.assign(control, pick(value, captureControlKeys));
+      if (isRecord(value._factCache)) control._factCache = pick(value._factCache,
+        ['history', 'cursor', 'gap', 'cursorExpired', 'hasMore', 'scannedCount', 'targetKey', 'partitions']);
+    }
+    if (control.pendingQuestion === null) delete control.pendingQuestion;
+    // Script/Intent history is source content; only its page cursor is control.
+    if ((command === 'script' || intentCommands.has(command)) && isRecord(value.history)) {
+      control.history = pick(value.history, ['lastSequence', 'hasMore', 'gap']);
+    }
+  }
+  if (history) control.history = history;
+  return control;
+}
+
+// `reply` is the internal {value, history?} of the executed command; `stage`
+// names the public stage that rejected the request, when one did.
+function publicReply({ command, reply, stage, completed = false }) {
+  const { kind, value } = encodeReply(reply);
+  const execution = executionFacts(reply.value, completed);
+  const failureStage = stage || (execution.ok !== true || execution.ambiguous === true ? 'execution' : undefined);
+  const body = {
+    command: typeof command === 'string' && command ? command : null,
+    execution,
+    control: { ...controlFacts(command, reply.value, reply.history), source: { responseId: randomUUID(), capturedAtMs: Date.now(), persisted: false, reason: 'not_requested' } },
+    extraction: { status: 'skipped' },
+    delivery: { status: 'inline' },
+    kind, value,
+    ...(failureStage ? { failureStage } : {}),
+  };
+  try {
+    body.delivery.valueBytes = Buffer.byteLength(JSON.stringify(value));
+    JSON.stringify(body);
+    return body;
+  } catch { return serializationFailure(body); }
+}
+
+function publicFailure({ command, stage, error, maxBytes = DEFAULT_OUTPUT_BYTES }) {
+  return boundedReply(publicReply({ command, reply: { value: commandFailure(error, command) }, stage }), maxBytes);
+}
+
+function minimalExecution(execution) {
+  return { ok: execution.ok === true ? true : execution.ok === false ? false : null,
+    ...pick(execution, ['dispatched', 'ambiguous', 'settled', 'exitCode']),
+    ...(typeof execution.error === 'string' && execution.error.length < 128 ? { error: execution.error } : {}) };
+}
+
+function serializationFailure(body) {
+  return { command: body.command, execution: minimalExecution(body.execution),
+    control: { source: body.control.source, controlComplete: false }, extraction: { status: 'skipped' },
+    delivery: { status: 'unavailable', reason: 'response_serialization_failed', limitBytes: DEFAULT_OUTPUT_BYTES },
+    kind: body.kind, failureStage: body.failureStage || 'delivery' };
+}
+
+function replyBytes(body) { return Buffer.byteLength(JSON.stringify(body)); }
+
+function boundedReply(body, limitBytes = DEFAULT_OUTPUT_BYTES) {
+  body.delivery.limitBytes = limitBytes;
+  const attemptedBytes = replyBytes(body);
+  if (attemptedBytes <= limitBytes) return body;
+  delete body.value;
+  body.delivery = { ...body.delivery, status: body.control.source.persisted ? 'reference' : 'unavailable',
+    reason: 'output_budget_exceeded', attemptedBytes, limitBytes };
+  body.failureStage ||= 'delivery';
+  if (replyBytes(body) <= limitBytes) return body;
+  // A large question, receipt or diagnostic must never become a silently
+  // incomplete continuation. Keep dispatch uncertainty and the real source.
+  const source = pick(body.control.source, ['responseId', 'capturedAtMs', 'persisted', 'ref', 'reason']);
+  if (body.control.source.error) source.error = 'source_unavailable';
+  return { command: typeof body.command === 'string' && body.command.length < 256 ? body.command : null,
+    execution: minimalExecution(body.execution), control: { source, controlComplete: false },
+    extraction: pick(body.extraction, ['status', 'mode', 'language', 'durationMs', 'error']),
+    delivery: { status: source.persisted ? 'reference' : 'unavailable', reason: 'control_over_budget', attemptedBytes, limitBytes },
+    kind: body.kind, failureStage: body.failureStage };
+}
+
+async function finishReply({ body, extract, output, frozen, getStore, sourceReason = 'offline' }) {
+  const limitBytes = output?.maxBytes ?? DEFAULT_OUTPUT_BYTES;
+  body.delivery.limitBytes = limitBytes;
+  if (body.delivery.reason === 'response_serialization_failed') return boundedReply(body, limitBytes);
+  const { freezeResponse, MAX_SNAPSHOT_BYTES } = require('./response-store');
+  const extracting = extract !== null;
+  const needsSource = extracting || replyBytes(body) > limitBytes;
+  if (!needsSource) return body;
+  if (!frozen) {
+    try { frozen = freezeResponse(body); }
+    catch { return boundedReply(serializationFailure(body), limitBytes); }
+    if (getStore && body.kind !== 'bytes') {
+      try { body.control.source = await getStore().save(frozen); }
+      catch (error) { body.control.source = { ...body.control.source, reason: undefined, error: error.code || 'snapshot_save_failed' }; }
+    } else body.control.source = { ...body.control.source, reason: body.kind === 'bytes' ? 'binary_snapshot_unsupported' : sourceReason };
+  }
+  if (extracting) {
+    let result;
+    if (frozen.snapshot.kind === 'bytes') result = { ok: false, error: 'extraction_binary_unsupported' };
+    else if (frozen.bytes.length > MAX_SNAPSHOT_BYTES) result = { ok: false, error: 'extraction_input_too_large', maxBytes: MAX_SNAPSHOT_BYTES };
+    else {
+      const { kind, value: response, execution, control } = frozen.snapshot;
+      result = await require('./extraction/runner').runExtraction(extract, { kind, response, execution, control });
+    }
+    const { ok, result: value, timings, ...details } = result;
+    body.extraction = { status: ok ? 'succeeded' : 'failed', mode: extract.mode,
+      ...(extract.language ? { language: extract.language } : {}), ...details };
+    if (ok) {
+      body.kind = 'json';
+      body.value = value;
+      body.delivery.valueBytes = Buffer.byteLength(JSON.stringify(value));
+    } else {
+      delete body.value;
+      body.delivery = { status: body.control.source.persisted ? 'reference' : 'unavailable', limitBytes, reason: 'extraction_failed' };
+      body.failureStage ||= 'extraction';
+    }
+  }
+  return boundedReply(body, limitBytes);
+}
+
+function responseReply({ snapshot, source }) {
+  return { command: 'response', execution: { ok: true, dispatched: false, ambiguous: false },
+    control: { ...snapshot.control, origin: { ...snapshot.identity, execution: snapshot.execution }, source },
+    extraction: { status: 'skipped' }, delivery: { status: 'inline', valueBytes: Buffer.byteLength(JSON.stringify(snapshot.value)) },
+    kind: snapshot.kind, value: snapshot.value };
+}
+
+function isPublicReply(value) {
+  return isRecord(value) && isRecord(value.execution) && isRecord(value.delivery) && ['json', 'text', 'bytes'].includes(value.kind);
+}
+
+// 0: delivered as requested. 1: rejected, failed or unknown execution.
+// 2: the command succeeded but extraction or delivery failed.
+function exitCodeFor(reply) {
+  if (!reply.failureStage) return 0;
+  return ['validation', 'execution'].includes(reply.failureStage) ? 1 : 2;
+}
+
+module.exports = { publicReply, publicFailure, responseReply, isPublicReply, exitCodeFor, finishReply, boundedReply, DEFAULT_OUTPUT_BYTES };

package/bin/response-store.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const { createEvidenceStore } = require('./shared-kernel/evidence-store');
+const { canonicalJson, validateRecord } = require('./shared-kernel/evidence-schema');
+const { CommandError } = require('./command-errors');
+const MAX_SNAPSHOT_BYTES = 8 * 1024 * 1024;
+
+function responseSchema() {
+  return { type: 'object', additionalProperties: false, required: ['operation', 'ref'], properties: {
+    operation: { const: 'read' },
+    ref: { type: 'object', additionalProperties: false, required: ['namespace', 'evidenceId', 'checksum', 'operationId'], properties: {
+      namespace: { const: 'response' }, evidenceId: { type: 'string', minLength: 1, maxLength: 256 },
+      operationId: { type: 'string', minLength: 1, maxLength: 128 }, checksum: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+    }, description: 'Pass control.source.ref unchanged. Reads the saved response; never repeats the original device action.' },
+  } };
+}
+
+// Detach using the public JSON encoding before sorting keys. These same bytes
+// supply immediate extraction and durable storage, after all feedback is added.
+function freezeResponse(body) {
+  const { source, ...control } = body.control;
+  const snapshot = JSON.parse(JSON.stringify({ kind: body.kind, value: body.value, execution: body.execution, control,
+    identity: { command: body.command, responseId: source.responseId, capturedAtMs: source.capturedAtMs } }));
+  const bytes = Buffer.from(canonicalJson(snapshot));
+  return { snapshot: JSON.parse(bytes), bytes };
+}
+
+function createResponseStore({ adapter, now } = {}) {
+  const evidence = createEvidenceStore({ namespace: 'response', adapter, now,
+    maxBytes: Math.ceil(MAX_SNAPSHOT_BYTES / 3) * 4 + 64 * 1024 });
+  async function save({ snapshot, bytes }) {
+    const identity = snapshot.identity;
+    const source = { responseId: identity.responseId, capturedAtMs: identity.capturedAtMs, persisted: false };
+    if (snapshot.kind === 'bytes') return { ...source, error: 'binary_snapshot_unsupported' };
+    if (bytes.length > MAX_SNAPSHOT_BYTES) return { ...source, error: 'snapshot_too_large', bytes: bytes.length, maxBytes: MAX_SNAPSHOT_BYTES };
+    const stored = await evidence.persist('response', { operationId: identity.responseId, revision: 1, snapshotBase64: bytes.toString('base64') });
+    if (!stored.ok) return { ...source, error: stored.error };
+    const retained = evidence.read(stored.evidenceId);
+    if (!retained.ok || retained.record.checksum !== stored.checksum) return { ...source, error: 'snapshot_not_retained' };
+    return { ...source, persisted: true, ref: { namespace: 'response', evidenceId: stored.evidenceId,
+      checksum: stored.checksum, operationId: identity.responseId } };
+  }
+  function read(ref) {
+    const result = evidence.read(ref.evidenceId);
+    if (!result.ok) throw new CommandError(`response_${result.error}`, result.error === 'not_found'
+      ? 'Saved response is missing, expired or evicted. No device action was repeated.' : 'Saved response integrity verification failed.');
+    const record = result.record;
+    if (record.checksum !== ref.checksum) throw new CommandError('response_checksum_mismatch', 'The supplied ref does not match the saved response checksum.');
+    if (record.operationId !== ref.operationId) throw new CommandError('response_identity_mismatch', 'The supplied ref does not match the saved response identity.');
+    if (!validateRecord('response', 'response', record).ok) throw new CommandError('response_invalid_snapshot', 'The saved response has an invalid snapshot.');
+    const bytes = Buffer.from(record.snapshotBase64, 'base64');
+    if (bytes.length > MAX_SNAPSHOT_BYTES) throw new CommandError('response_snapshot_too_large', 'The saved response exceeds the 8 MiB input limit.');
+    const snapshot = JSON.parse(bytes);
+    return { snapshot, bytes, source: { responseId: snapshot.identity.responseId,
+      capturedAtMs: snapshot.identity.capturedAtMs, persisted: true, ref } };
+  }
+  return { save, read };
+}
+
+module.exports = { createResponseStore, freezeResponse, responseSchema, MAX_SNAPSHOT_BYTES };