@mobileaidev/ai-app-bridge 0.3.7 → 0.4.0

package/bin/script/script-session-channel.js

@@ -2,7 +2,8 @@
 
 const MAX_FRAME_BYTES = 1024 * 1024;
 
-function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } = {}) {
+function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES,
+  maxInputFrameBytes = maxFrameBytes, maxOutputFrameBytes = maxFrameBytes, maxDiagnosticBytes = 8192 } = {}) {
   let buffer = '';
   let closed = false;
   let failure = null;
@@ -12,10 +13,18 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
   const pending = [];
   const replies = new Map();
   const maxPending = 32;
+  let stderr = Buffer.alloc(0);
+  let stderrTotalBytes = 0;
 
   if (child.stderr) {
-    child.stderr.on('data', () => {});
+    child.stderr.on('data', chunk => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      stderrTotalBytes += bytes.length;
+      stderr = bytes.length >= maxDiagnosticBytes ? Buffer.from(bytes.subarray(-maxDiagnosticBytes))
+        : Buffer.concat([stderr.subarray(Math.max(0, stderr.length + bytes.length - maxDiagnosticBytes)), bytes]);
+    });
   }
+  child.stdin.on('error', error => fail(error));
   child.stdout.setEncoding('utf8');
   child.stdout.on('data', (chunk) => {
     if (closed) return;
@@ -25,7 +34,7 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
       const line = buffer.slice(0, index);
       buffer = buffer.slice(index + 1);
       index = buffer.indexOf('\n');
-      if (Buffer.byteLength(line, 'utf8') > maxFrameBytes) {
+      if (Buffer.byteLength(line, 'utf8') + 1 > maxOutputFrameBytes) {
         fail(new Error('frame_too_large'));
         return;
       }
@@ -57,7 +66,7 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
       }
       pending.push(message);
     }
-    if (Buffer.byteLength(buffer, 'utf8') > maxFrameBytes) {
+    if (Buffer.byteLength(buffer, 'utf8') > maxOutputFrameBytes) {
       fail(new Error('frame_too_large'));
     }
   });
@@ -67,7 +76,7 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
   function send(message) {
     if (closed || !child.stdin.writable) return;
     const line = `${JSON.stringify(message)}\n`;
-    if (Buffer.byteLength(line, 'utf8') > maxFrameBytes) {
+    if (Buffer.byteLength(line, 'utf8') > maxInputFrameBytes) {
       fail(new Error('frame_too_large'));
       return;
     }
@@ -76,14 +85,11 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
 
   function nextMessage() {
     return new Promise((resolve) => {
-      if (closed) {
-        resolve(failure);
-        return;
-      }
       if (pending.length > 0) {
         resolve(pending.shift());
         return;
       }
+      if (closed) { resolve(failure); return; }
       waiters.push(resolve);
     });
   }
@@ -108,7 +114,9 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
     closed = true;
     const frame = { type: 'fail', error: error.message || String(error) };
     failure = frame;
+    const terminal = error.message === 'channel_closed' ? pending.find(message => ['return', 'fail'].includes(message.type)) : null;
     pending.length = 0;
+    if (terminal) pending.push(terminal);
     buffer = '';
     while (waiters.length > 0) waiters.shift()(frame);
     for (const resolve of replies.values()) resolve(frame);
@@ -121,7 +129,16 @@ function createScriptSessionChannel(child, { maxFrameBytes = MAX_FRAME_BYTES } =
     if (child.kill('SIGTERM') && !killTimer) killTimer = setTimeout(() => child.kill('SIGKILL'), 250);
   }
 
-  return { send, nextMessage, waitReply, stop };
+  function diagnostics() {
+    if (!stderrTotalBytes) return {};
+    // Invalid bytes expand to replacement characters. Bound delivered UTF-8
+    // text too, starting at a complete character in the retained tail.
+    const text = Buffer.from(stderr.toString('utf8'));
+    let start = Math.max(0, text.length - maxDiagnosticBytes);
+    while (start < text.length && (text[start] & 0xc0) === 0x80) start++;
+    return { stderr: text.subarray(start).toString('utf8'), stderrTruncated: stderrTotalBytes > stderr.length || start > 0 };
+  }
+  return { send, nextMessage, waitReply, stop, diagnostics };
 }
 
 module.exports = { createScriptSessionChannel };

package/bin/script/script-supervisor.js

@@ -174,6 +174,7 @@ function createScriptSupervisor({
       mutationUnknown: false,
       decisionRevision: 0,
       currentRequestId: null,
+      pendingQuestion: null,
       questionRevisions: new Map(),
       decisions: new Map(),
       ledger: scriptLedger,
@@ -431,8 +432,10 @@ function createScriptSupervisor({
       operationId: record.operationId,
       status: record.status,
       pauseReason: record.pauseReason,
+      pendingQuestion: record.status === 'waiting_for_agent' ? record.pendingQuestion : null,
       error: record.error,
       hash: record.hash,
+      ...(record.diagnostics ? { diagnostics: record.diagnostics } : {}),
       resultRef: record.resultRef ?? null,
       eventSequence: record.events.sequence,
       events: record.events.after(args.afterSequence, args.eventLimit ?? args.limit),
@@ -517,6 +520,7 @@ function persistRecord(record, kind, body) {
 }
 
 async function commitTerminal(record, status, error, now, result) {
+  record.diagnostics = status === 'failed' ? result?.diagnostics : undefined;
   let revision = record.checkpointRevision + 1;
   let resultRef = null;
   if (status === 'completed' && record.store) {
@@ -539,6 +543,7 @@ async function commitTerminal(record, status, error, now, result) {
     status,
     error,
     resultRef,
+    ...(record.diagnostics ? { diagnostics: record.diagnostics } : {}),
     ...(record.recording ? { recording: record.recording.info() } : {}),
   };
   let persisted = await persistRecord(record, 'checkpoint', checkpoint);
@@ -777,6 +782,9 @@ function trackAgent(agent, record, now) {
       const requestId = `ask-${record.decisionRevision}`;
       record.questionRevisions.set(requestId, record.decisionRevision);
       record.currentRequestId = requestId;
+      // The unanswered question stays on the record so a filtered event page
+      // cannot hide it from status/wait.
+      record.pendingQuestion = { requestId, revision: record.decisionRevision, request };
       record.status = 'waiting_for_agent';
       emitRecord(record, 'agent_question_created', {
         request,

package/bin/shared-kernel/argument-schema.js

@@ -14,19 +14,16 @@ function validateValue(value, schema, field = '') {
   if (Object.hasOwn(schema, 'const') && value !== schema.const) throw invalid(field, `${label} must be ${JSON.stringify(schema.const)}.`);
   if (schema.enum && !schema.enum.includes(value)) throw invalid(field, `${label} must be one of: ${schema.enum.join(', ')}.`);
   const type = schema.type;
-  const matches = type === undefined || (type === 'array' ? Array.isArray(value)
-    : type === 'null' ? value === null
-    : type === 'object' ? value !== null && typeof value === 'object' && !Array.isArray(value)
-    : type === 'integer' ? Number.isSafeInteger(value)
-    : type === 'number' ? typeof value === 'number' && Number.isFinite(value)
-    : typeof value === type);
-  if (!matches) throw invalid(field, `${label} must be ${type}; no implicit type conversion is performed.`);
+  if (!matchesType(value, type)) throw invalid(field, `${label} must be ${type}; no implicit type conversion is performed.`);
   if (schema.minLength !== undefined && value.length < schema.minLength) throw invalid(field, `${label} must not be empty.`);
   if (schema.maxLength !== undefined && value.length > schema.maxLength) throw invalid(field, `${label} must contain at most ${schema.maxLength} characters.`);
   if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) throw invalid(field, `${label} must match ${schema.pattern}.`);
-  if (schema.minimum !== undefined && value < schema.minimum) throw invalid(field, `${label} must be >= ${schema.minimum}.`);
-  if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) throw invalid(field, `${label} must be > ${schema.exclusiveMinimum}.`);
-  if (schema.maximum !== undefined && value > schema.maximum) throw invalid(field, `${label} must be <= ${schema.maximum}.`);
+  // A range violation quotes the field's documented meaning, so the caller can
+  // correct the call without reading the nested schema.
+  const explained = message => schema.description ? `${message} ${schema.description}` : message;
+  if (schema.minimum !== undefined && value < schema.minimum) throw invalid(field, explained(`${label} must be >= ${schema.minimum}.`));
+  if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) throw invalid(field, explained(`${label} must be > ${schema.exclusiveMinimum}.`));
+  if (schema.maximum !== undefined && value > schema.maximum) throw invalid(field, explained(`${label} must be <= ${schema.maximum}.`));
   if (type === 'array') {
     if (schema.minItems !== undefined && value.length < schema.minItems) throw invalid(field, `${label} requires at least ${schema.minItems} item(s).`);
     if (schema.maxItems !== undefined && value.length > schema.maxItems) throw invalid(field, `${label} accepts at most ${schema.maxItems} item(s).`);
@@ -68,6 +65,15 @@ function validateValue(value, schema, field = '') {
   if (Object.keys(schema).every(key => ['description', 'default'].includes(key))) validateJson(value, field);
 }
 
+function matchesType(value, type) {
+  return type === undefined || (type === 'array' ? Array.isArray(value)
+    : type === 'null' ? value === null
+    : type === 'object' ? value !== null && typeof value === 'object' && !Array.isArray(value)
+    : type === 'integer' ? Number.isSafeInteger(value)
+    : type === 'number' ? typeof value === 'number' && Number.isFinite(value)
+    : typeof value === type);
+}
+
 function accepts(value, schema, field) {
   try { validateValue(value, schema, field); return true; }
   catch (error) { if (!(error instanceof CommandError)) throw error; return false; }
@@ -82,22 +88,48 @@ function validateUnion(value, branches, field, exactlyOne) {
   }
   if (matched && (!exactlyOne || matched === 1)) return;
   if (!matched) {
+    // A branch for another JSON type cannot explain this value, e.g. the null
+    // branch of a nullable target never explains an object missing platform.
+    const explained = failures.filter(({ branch }) => matchesType(value, branch.type));
+    if (!explained.length) {
+      throw invalid(field, `${field || 'arguments'} must be ${[...new Set(failures.map(({ branch }) => branch.type))].join(' or ')}; no implicit type conversion is performed.`);
+    }
     // A tagged branch gives a useful precise error instead of a generic union
     // failure, e.g. decision.action.durationMs for an observed long press.
-    const tagged = failures.filter(({ branch }) => {
+    const tagged = explained.filter(({ branch }) => {
       const tags = Object.entries(branch.properties || {}).filter(([, rule]) => Object.hasOwn(rule, 'const'));
       return tags.some(([key, rule]) => value?.[key] === rule.const)
         && tags.every(([key, rule]) => Object.hasOwn(value || {}, key) ? value[key] === rule.const : !branch.required?.includes(key));
     });
     if (tagged.length === 1) throw tagged[0].error;
-    const candidates = tagged.length ? tagged : failures;
+    const candidates = tagged.length ? tagged : explained;
     if (candidates.every(({ error }) => error.code === candidates[0].error.code && error.field === candidates[0].error.field && error.message === candidates[0].error.message)) throw candidates[0].error;
+    // No branch accepts every supplied tag: name the tag the intended variants
+    // reject and its accepted values instead of listing every variant.
+    const rejected = tagged.length ? null : rejectedDiscriminator(value || {}, explained.map(({ branch }) => branch));
+    if (rejected) {
+      const child = fieldAt(field, rejected.key);
+      throw invalid(child, `${child} must be one of: ${rejected.values.map(item => JSON.stringify(item)).join(', ')}.`);
+    }
     if (branches.length === 1) throw failures[0].error;
   }
   throw new CommandError('invalid_argument', `${field || 'arguments'} must match ${exactlyOne ? 'exactly one' : 'one'} of the documented variants.`,
     { field: field || 'arguments', details: { variants: failures.map(({ error }) => ({ field: error.field, error: error.code, message: error.message })) } });
 }
 
+// The branches agreeing with the most supplied tags are the intended variants,
+// e.g. the two start variants for {operation:"start", mode:"wrong"}. A supplied
+// tag they all reject is the field to correct; its accepted values are theirs.
+function rejectedDiscriminator(value, branches) {
+  const suppliedTags = branch => Object.entries(branch.properties || {}).filter(([key, rule]) => Object.hasOwn(rule, 'const') && Object.hasOwn(value, key));
+  const agreement = branch => suppliedTags(branch).filter(([key, rule]) => value[key] === rule.const).length;
+  const best = Math.max(...branches.map(agreement));
+  const closest = branches.filter(branch => agreement(branch) === best);
+  const key = suppliedTags(closest[0]).map(([name]) => name)
+    .find(name => closest.every(branch => Object.hasOwn(branch.properties[name] || {}, 'const') && value[name] !== branch.properties[name].const));
+  return key === undefined ? null : { key, values: [...new Set(closest.map(branch => branch.properties[key].const))] };
+}
+
 function validateJson(value, field = '', ancestors = new Set(), depth = 0) {
   if (depth > 64) throw invalid(field, 'JSON nesting must not exceed 64 levels.');
   if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number' && Number.isFinite(value)) return;

package/bin/shared-kernel/evidence-archive.js

@@ -3,7 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { checksumOf, canonicalJson, validateArchivedRecord, verifyChecksum } = require('./evidence-schema');
+const { checksumOf, canonicalJson, validateArchivedRecord, verifyChecksum, NAMESPACES } = require('./evidence-schema');
 const { analyzeRecordedPayloads } = require('./recorded-payload-archive');
 const { readRegularFile: readRecordedFile } = require('./evidence-recording');
 
@@ -23,7 +23,7 @@ function textArgument(value, field) {
 }
 
 function namespaceArgument(namespace) {
-  requireValue(namespace === 'intent' || namespace === 'script', 'invalid_argument', 'namespace');
+  requireValue(NAMESPACES.includes(namespace), 'invalid_argument', 'namespace');
 }
 
 async function handle(args = {}, { getFactStore } = {}) {

package/bin/shared-kernel/evidence-schema.js

@@ -3,7 +3,7 @@
 const crypto = require('node:crypto');
 const { sanitizePersistentValue } = require('../fact-codec');
 
-const NAMESPACES = Object.freeze(['script', 'intent']);
+const NAMESPACES = Object.freeze(['script', 'intent', 'response']);
 const PROVIDERS = Object.freeze(['native', 'uia', 'flutter', 'h5']);
 const RECORD_SCHEMA = 'aab.execution-evidence/v1';
 const AGENT_DECISIONS = Object.freeze(['act', 'complete', 'fail', 'inconclusive']);
@@ -17,6 +17,7 @@ const KINDS = Object.freeze([
   'checkpoint',
   'result',
   'attachment',
+  'response',
 ]);
 
 function checksumOf(value) {
@@ -57,6 +58,7 @@ function verifyChecksum(record) {
 }
 
 function requiredFields(kind) {
+  if (kind === 'response') return ['operationId', 'revision', 'snapshotBase64'];
   if (kind === 'observation') {
     return ['operationId', 'revision', 'target', 'provider', 'capturedAtMs'];
   }
@@ -97,6 +99,7 @@ function validateRecord(namespace, kind, record, { archivedUnversioned = false }
   if (!record || typeof record !== 'object') {
     return { ok: false, error: 'invalid_record' };
   }
+  if ((namespace === 'response') !== (kind === 'response')) return { ok: false, error: 'invalid_kind' };
   if (!archivedUnversioned && record.schemaVersion !== undefined && record.schemaVersion !== RECORD_SCHEMA) {
     return { ok: false, error: 'unsupported_record_schema', field: 'schemaVersion' };
   }
@@ -107,6 +110,18 @@ function validateRecord(namespace, kind, record, { archivedUnversioned = false }
       return { ok: false, error: 'invalid_record', field };
     }
   }
+  if (kind === 'response') {
+    const encoded = record.snapshotBase64;
+    if (typeof encoded !== 'string' || Buffer.from(encoded, 'base64').toString('base64') !== encoded
+      || record.revision !== 1) return { ok: false, error: 'invalid_record', field: 'snapshotBase64' };
+    try {
+      const snapshot = JSON.parse(Buffer.from(encoded, 'base64').toString('utf8'));
+      if (!['json', 'text'].includes(snapshot.kind) || !Object.hasOwn(snapshot, 'value')
+        || !snapshot.execution || !snapshot.control || snapshot.control.source !== undefined
+        || snapshot.identity?.responseId !== record.operationId || typeof snapshot.identity.command !== 'string'
+        || !Number.isSafeInteger(snapshot.identity.capturedAtMs)) throw new Error('invalid_snapshot');
+    } catch { return { ok: false, error: 'invalid_record', field: 'snapshotBase64' }; }
+  }
   if (kind === 'result' && (namespace !== 'script' || !Object.hasOwn(record, 'result')
     || !Number.isSafeInteger(record.bytes) || record.bytes < 1
     || !/^[a-f0-9]{64}$/.test(record.sha256) || !/^[a-f0-9]{64}$/.test(record.originalSha256)

package/bin/shared-kernel/evidence-store.js

@@ -1,10 +1,10 @@
 'use strict';
 
-const { buildEnvelope, verifyChecksum } = require('./evidence-schema');
+const { buildEnvelope, verifyChecksum, NAMESPACES } = require('./evidence-schema');
 
 function createEvidenceStore({ namespace, adapter, now = Date.now, maxBytes = 8 * 1024 * 1024 } = {}) {
-  if (namespace !== 'script' && namespace !== 'intent') {
-    throw new TypeError('namespace must be script or intent');
+  if (!NAMESPACES.includes(namespace)) {
+    throw new TypeError('namespace must be script, intent or response');
   }
   if (!adapter || typeof adapter.record !== 'function' || typeof adapter.readById !== 'function') {
     throw new TypeError('adapter with record/readById is required');

package/bin/shared-kernel/execution-contracts.js

@@ -133,8 +133,15 @@ function scriptSpecSchema(permissionNames) {
 }
 
 function executionCommandSchema(command, permissionNames) {
-  const read = { afterSequence, limit: pageLimit };
-  const scriptRead = { ...read, eventLimit: pageLimit, includeCatalog: boolean };
+  // Script and Intent page with different cursors; the schema states which one.
+  const historyRead = {
+    afterSequence: { ...afterSequence, description: 'History page cursor: the previous response\'s history.lastSequence. Not an eventSequence.' },
+    limit: { ...pageLimit, description: 'History entries per page; it bounds entries, not response bytes.' },
+  };
+  const scriptRead = {
+    afterSequence: { ...afterSequence, description: 'Continuation cursor: the previous status/wait response\'s eventSequence; events and history after it are returned. Not history.lastSequence.' },
+    limit: pageLimit, eventLimit: pageLimit, includeCatalog: boolean,
+  };
   const operation = (name, properties, required = []) => object({ operation: { const: name }, ...properties }, ['operation', ...required]);
   const control = (name, properties = {}) => operation(name, { operationId: text, ...properties }, ['operationId']);
   if (command === 'script') return variants('operation', [
@@ -144,7 +151,8 @@ function executionCommandSchema(command, permissionNames) {
         { if: { required: ['recordingDir'] }, then: { properties: { script: { properties: { policy: { properties: { restartPolicy: { const: 'none' } } } } } } } },
       ] },
     control('result'),
-    control('status', scriptRead), control('wait', { ...scriptRead, waitMs: { ...integer(0, 60000), default: 30000 } }),
+    control('status', scriptRead), control('wait', { ...scriptRead, waitMs: { ...integer(0, 60000), default: 30000,
+      description: 'Upper bound of one wait call in milliseconds. To keep waiting, call wait again with the same operationId and afterSequence set to the last eventSequence.' } }),
     ...['pause', 'resume', 'cancel'].map(name => control(name, scriptRead)),
     operation('decide', { operationId: text, requestId: text, revision, decision: { contentMediaType: 'application/json', description: 'JSON answer to the current ctx.askAgent request; business data is preserved.' }, ...scriptRead }, ['operationId', 'requestId', 'revision', 'decision']),
     operation('runtime-status', {}),
@@ -156,7 +164,7 @@ function executionCommandSchema(command, permissionNames) {
     return variants('operation', [
       operation('start', { ...start, mode: { const: 'supervised', default: 'supervised' } }, ['goal', 'target']),
       operation('start', { ...start, mode: { const: 'autonomous' }, agentModule: text, budget: intentBudget }, ['goal', 'target', 'mode', 'agentModule']),
-      control('status', read), control('observe', { basedOnRevision: revision, observationTarget: observationTargetSchema,
+      control('status', historyRead), control('observe', { basedOnRevision: revision, observationTarget: observationTargetSchema,
         provider: { ...provider, description: 'Observe through this provider on the frozen target. Becomes selected only after the new observation and summary are committed; omitted retains the last committed selection.' } }),
       operation('decide', { operationId: text, decision: intentDecisionSchema() }, ['operationId', 'decision']),
       ...['pause', 'resume', 'cancel'].map(name => control(name)),
@@ -164,7 +172,7 @@ function executionCommandSchema(command, permissionNames) {
     ]);
   }
   if (command === 'evidence') return variants('operation', [
-    operation('export', { namespace: { enum: ['intent', 'script'] }, operationId: text, outputDir: text, includeRecordedPayloads: boolean }, ['namespace', 'operationId', 'outputDir']),
+    operation('export', { namespace: { enum: ['intent', 'script', 'response'] }, operationId: text, outputDir: text, includeRecordedPayloads: boolean }, ['namespace', 'operationId', 'outputDir']),
     operation('verify', { archiveDir: text, manifestSha256: { type: 'string', pattern: '^[a-f0-9]{64}$' } }, ['archiveDir', 'manifestSha256']),
   ]);
   throw new Error(`No execution contract for ${command}`);

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

@@ -73,6 +73,10 @@ function commandPlatform(command) {
 // select another platform; a partial identity can override defaults only on the
 // same platform. Never mix an Android serial with an iOS/Web connection.
 function bindCommandTarget(command, args, defaultTarget = null, explicitTarget) {
+  if (command === 'executor-prepare') {
+    if (explicitTarget !== undefined) throw new CommandError('target_platform_mismatch', 'Executor preparation runs on the Host and accepts no device target.');
+    return { target: null, args: { ...args } };
+  }
   const platform = commandPlatform(command);
   const definition = definitions[platform];
   const selected = explicitTarget === undefined ? defaultTarget : normalizeExecutionTarget(explicitTarget);

package/bin/shared-kernel/request-context.js

@@ -7,8 +7,8 @@ const context = new AsyncLocalStorage();
 const requestDirectory = () => context.getStore()?.cwd ?? process.cwd();
 const resolveRequestPath = value => path.resolve(requestDirectory(), value);
 const inRequestDirectory = (cwd, action) => context.run({ cwd }, action);
-const localPaths = ['outFile', 'artifactDir', 'apkPath', 'appPath', 'recordingDir', 'outputDir', 'archiveDir', 'wdaProjectPath', 'agentModule'];
-const executables = ['adb', 'aaptPath', 'apksignerPath', 'devicectl', 'xcodebuild', 'pythonPath'];
+const localPaths = ['outFile', 'artifactDir', 'apkPath', 'appPath', 'recordingDir', 'outputDir', 'archiveDir', 'wdaProjectPath', 'agentModule', 'projectDir', 'testPackagePath'];
+const executables = ['adb', 'aaptPath', 'apksignerPath', 'devicectl', 'xcodebuild', 'pythonPath', 'flutterPath', 'gradlePath'];
 
 // Only contract-defined filesystem fields are resolved. Web URL paths, source
 // text and arbitrary Script inputs keep their original values.

package/bin/target-execution.js

@@ -165,6 +165,8 @@ function requestDigest(command, args) {
 }
 
 function targetFor(command, args) {
+  if (command === 'executor-prepare') return { kind: 'host', platform: 'host',
+    key: `executor-prepare:${JSON.stringify([args.platform, args.projectDir ?? null])}` };
   if (command === 'logcat' && String(args.deviceLogScope || '').toLowerCase() === 'device') {
     const serial = targetPart(args.serial);
     return {

package/docs/COMMAND_CONTRACT.md

@@ -13,7 +13,7 @@ a light command directory. Use `capabilities {"command":"tap-text"}`
 for its current `inputSchema`, platform, role and supported entrypoints. Domain
 `execution` contains Intent, Script, runtime lifecycle and device ownership;
 `evidence` contains archive operations.
-`capabilities {"includeOptions":true}` returns every current command schema.
+Discovery has a fixed 96 KiB budget. Broad `includeOptions:true` queries may return `discovery_output_too_large`; use the returned narrower query. Schemas are never silently pruned.
 
 Load only the operation needed for Intent, Script or evidence, for example
 `capabilities {"command":"intent","operation":"start"}`. To inspect an Intent
@@ -24,10 +24,19 @@ runtime contract. Intent terminal decisions remain available in the selected
 decision schema. Unsupported operations or scope combinations return an error
 with the offending field. Omit filters to read the complete command contract.
 
-All parameters are under `run.arguments`:
+Business parameters are under `run.arguments`. The required top-level `extract` chooses delivery; explicit `null` requests the original result within budget:
 
 ```json
-{"command":"tap-text","arguments":{"serial":"DEVICE","packageName":"com.example.app","targetText":"设置","provider":"auto"}}
+{
+  "command": "tap-text",
+  "extract": null,
+  "arguments": {
+    "serial": "DEVICE",
+    "packageName": "com.example.app",
+    "targetText": "设置",
+    "provider": "auto"
+  }
+}
 ```
 
 Names are canonical and case-sensitive. Unknown arguments, aliases, invalid
@@ -55,8 +64,8 @@ provider access and device ownership through their execution-specific contracts.
 ### Shared runtime lifecycle
 
 The first executing command starts a local runtime. `runtime --operation start`
-starts it explicitly; `runtime --operation status` inspects it without starting
-one; `runtime --operation stop` cancels and drains active work before releasing
+starts it explicitly; `runtime --operation status --extract null` inspects it without starting
+one; `runtime --operation stop --extract null` cancels and drains active work before releasing
 its ownership. CLI exit, MCP EOF and client SIGINT/SIGTERM close only that client.
 Use `intent`/`script --operation cancel --operation-id ID` to cancel one task.
 The same operation ID can be queried and controlled from either entrypoint.
@@ -93,12 +102,26 @@ there; Script freezes its `cwd`, source and target before starting. Subsequent
 clients cannot change those paths. `evidence verify` is offline in both adapters
 and requires neither a running runtime nor an available FactStore.
 
-CLI results are one JSON envelope: `{kind: "json"|"text"|"bytes", value, history?}`.
-JSON false, zero and null remain values; text is a string and bytes are base64.
-`history` contains the same recording outcome that MCP exposes as `_history`.
-Command failures have `value.ok:false` and exit code 1. MCP uses its normal
-content and `isError` representation. These are wire-format differences;
-validation, dispatch, task control and evidence semantics are shared.
+CLI results are one compact JSON envelope:
+`{command, execution, control, extraction, delivery, kind, value?, failureStage?}`.
+MCP returns this same body in tool text; no second `_meta`, `_history` or
+`structuredContent` copy is attached. `execution` records the command outcome;
+`control` retains continuation, current pending questions, receipts and capture
+coverage. With `extract:null`, `value` is the command's original value including
+`_feedback`; otherwise it is the extracted JSON value when delivered.
+
+The default final-body budget is 96 KiB UTF-8. `output.maxBytes` can select
+16–256 KiB. Overflow never returns a truncated JSON document or a large original
+fallback. Inspect `control.source`: only `persisted:true` provides a readable
+ref. Retry extraction with `response read` and this ref; repeating the original
+action with the same requestId is not a recovery guarantee. Original response
+snapshots and their exports preserve the original JSON representation.
+
+Exit 0 means requested delivery succeeded; 1 means validation/execution failed
+or remained unknown; 2 means the command succeeded but extraction/delivery
+failed. `failureStage` prioritizes validation, execution, extraction, delivery.
+MCP sets `isError` consistently. See [response extraction](RESPONSE_EXTRACTION.md)
+for exact examples, budgets, ref recovery and the distinction from Script.
 
 `batch`, `smoke`, `launch-native-test` and `launch-flutter` were removed. Use a
 code Script for sequences, `launch-app` for a Flutter app's actual launcher, and
@@ -503,6 +526,30 @@ or call budget prevents another Agent call. Malformed replies remain
 `waiting_for_decision` with a field error and require explicit correction; they
 neither dispatch nor trigger another Agent request automatically.
 
+A supervised Intent is driven by the caller: observe, decide against the
+observed revision, observe again, judge independently. One complete lifecycle,
+as sent to `run` (the repository test suite runs this sequence against the
+current contract with an injected device):
+
+```json lifecycle-example
+{"command":"intent","extract":null,"arguments":{"operation":"start","goal":"Open the Labels screen","target":{"platform":"android","serial":"<serial>","packageName":"<package>"}}}
+{"command":"intent","extract":null,"arguments":{"operation":"decide","operationId":"<operationId>","decision":{"decisionId":"d-1","agentDecision":"act","basedOnRevision":1,"action":{"action":"tap","selector":{"text":"Labels"}}}}}
+{"command":"intent","extract":null,"arguments":{"operation":"status","operationId":"<operationId>","limit":20}}
+{"command":"intent","extract":null,"arguments":{"operation":"status","operationId":"<operationId>","limit":20,"afterSequence":"<history.lastSequence of the previous page>"}}
+{"command":"intent","extract":null,"arguments":{"operation":"decide","operationId":"<operationId>","decision":{"decisionId":"d-2","agentDecision":"complete","basedOnRevision":2}}}
+```
+
+`start` and each `decide` return the committed observation with its `revision`
+and `summary`; the next decision must carry that `revision` as
+`basedOnRevision`. `status` returns the current state plus one history page.
+`limit` bounds entries, not bytes: a page of `summary` entries can still be
+large, so read the current state with a small `limit` and page history
+deliberately. The next page's `afterSequence` is the previous page's
+`history.lastSequence`; it is not an `eventSequence`, which belongs to Script.
+Supervised mode never acts on its own: without a decision the Intent stays
+`waiting_for_decision` until `timeoutMs`, and `complete` records the caller's
+judgment rather than evidence of the business outcome.
+
 Every decision requires `decisionId`, positive integer `basedOnRevision`, and
 `agentDecision`. `act` requires a provider-specific `action`; terminal decisions
 `complete/fail/inconclusive` forbid one. Tap uses an exact `selector` object, with
@@ -1186,7 +1233,23 @@ exact and come from one fresh visible provider tree; metadata, hidden windows
 and text from another provider cannot complete a condition. For example:
 
 ```json
-{"command":"wait-text","arguments":{"serial":"DEVICE","packageName":"com.example.app","provider":"native","targetText":"Save, draft","requireText":["Editor"],"absentText":["Loading"],"timeoutMs":5000}}
+{
+  "command": "wait-text",
+  "extract": null,
+  "arguments": {
+    "serial": "DEVICE",
+    "packageName": "com.example.app",
+    "provider": "native",
+    "targetText": "Save, draft",
+    "requireText": [
+      "Editor"
+    ],
+    "absentText": [
+      "Loading"
+    ],
+    "timeoutMs": 5000
+  }
+}
 ```
 
 At least one condition is required. Pure absence or Activity-only waits require
@@ -1491,7 +1554,7 @@ The operation holds the phone's mutation lease through package verification.
 For example, after receiving a fresh observation:
 
 ```json
-{"command":"intent","arguments":{"operation":"decide","operationId":"FROM_START","decision":{"decisionId":"choice-1","basedOnRevision":2,"agentDecision":"act","action":{"action":"tap","selector":{"resourceName":"ID_FROM_ACTUAL_OBSERVATION"}}}}}
+{"command":"intent","extract":null,"arguments":{"operation":"decide","operationId":"FROM_START","decision":{"decisionId":"choice-1","basedOnRevision":2,"agentDecision":"act","action":{"action":"tap","selector":{"resourceName":"ID_FROM_ACTUAL_OBSERVATION"}}}}}
 ```
 
 Completion requires the matching original shell-job receipt, a successful
@@ -1535,11 +1598,11 @@ provider operation. A history failure never retries or rewrites that operation.
 Intent/Script required evidence commits retain their existing strict admission
 and terminal-evidence contracts.
 
-Object results carry `_history` with schema `aab.command-history/v1`, including
-when `feedback:"off"`. Every ordinary CLI/MCP result also carries the same value in
-`_meta["ai-app-bridge/history"]`, so raw text/image-result consumers can inspect
-history without rewriting the original content. This is MCP history metadata;
-CLI and MCP use the same history store; direct internal provider calls do not acquire an auxiliary one.
+Public replies carry command recording status in `control.history` with schema
+`aab.command-history/v1`, where applicable. Full Intent history and original
+business values remain in value; only page/continuation fields are protected.
+CLI and MCP share the same compact body. There is no duplicate `_history` or
+MCP `_meta["ai-app-bridge/history"]` attachment.
 
 - `stored`: this invocation's action and returned Host evidence references were
   committed. It is not a claim of complete mobile history or business correctness.
@@ -1562,7 +1625,16 @@ Background observer health remains separate from this foreground write report.
 Trigger the runtime permission request through the App's existing flow, then call:
 
 ```json
-{"command":"permission-dialog","arguments":{"serial":"DEVICE","packageName":"com.example.app","permission":"android.permission.RECORD_AUDIO","outcome":"allow-once"}}
+{
+  "command": "permission-dialog",
+  "extract": null,
+  "arguments": {
+    "serial": "DEVICE",
+    "packageName": "com.example.app",
+    "permission": "android.permission.RECORD_AUDIO",
+    "outcome": "allow-once"
+  }
+}
 ```
 
 This MCP entry returns an ordinary Intent ID, the actual UI summary, and

package/docs/EVIDENCE_ARCHIVE.md

@@ -1,7 +1,7 @@
 # Record, export and verify execution evidence
 
 Discover the public MCP command with `capabilities {"command":"evidence"}`.
-It works for both Intent operation IDs and Script execution IDs, including
+It works for Intent operation IDs, Script execution IDs and saved response IDs, including
 records retained after the execution runtime has restarted. CLI and MCP use the
 same operation IDs and export command. Export does not require a
 connected phone or a live worker.
@@ -9,6 +9,7 @@ connected phone or a live worker.
 ```json
 {
   "command": "evidence",
+  "extract": null,
   "arguments": {
     "operation": "export",
     "namespace": "intent",
@@ -24,6 +25,16 @@ queued writes, and freezes the retained records for exactly that namespace
 and operation. The parent directory must exist; the output directory must
 not exist. No existing directory is replaced.
 
+For a saved public response, use `namespace: "response"` and the unchanged
+`control.source.ref.operationId`. A response record stores the final command
+result and execution/control facts in `snapshotBase64`, using canonical UTF-8
+JSON bytes after feedback has been added. The decoded bytes are exactly the
+input used for extraction. They can differ from a UI history record captured
+earlier. Export and verification preserve these bytes and use the existing
+evidence checksum; no second snapshot checksum or archive format is added.
+Only `control.source.persisted: true` supplies a readable ref. Missing, expired
+or evicted responses fail reads; they never cause a device query or action.
+
 The response includes `archiveDir`, `manifestPath`, `manifestSha256`,
 `recordCount`, `targets`, and `coverage`. Save the returned manifest SHA256
 separately when handing the archive to an author or reviewer.
@@ -52,6 +63,7 @@ Move or copy the directory as a unit, then call:
 ```json
 {
   "command": "evidence",
+  "extract": null,
   "arguments": {
     "operation": "verify",
     "archiveDir": "/absolute/moved-archive",
@@ -181,6 +193,7 @@ Use the same public export call with `includeRecordedPayloads: true`:
 ```json
 {
   "command": "evidence",
+  "extract": null,
   "arguments": {
     "operation": "export",
     "namespace": "script",