@mobileaidev/ai-app-bridge 0.3.7 → 0.4.0

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 };

package/bin/runtime-client.js

@@ -4,10 +4,11 @@ const fs = require('node:fs');
 const path = require('node:path');
 const http = require('node:http');
 const { fork } = require('node:child_process');
-const { CommandError, commandFailure } = require('./command-errors');
-const { validateRunRequest } = require('./command-request');
+const { CommandError } = require('./command-errors');
+const { validateRunRequest, publicOutputLimit } = require('./command-request');
+const { publicReply, publicFailure, isPublicReply, finishReply } = require('./public-reply');
 const { protocol, maxMessageBytes, readJson, decodeReply } = require('./runtime-protocol');
-const { runtimeLocation, runtimeIdentity, acquireRuntimeLock, readEndpoint, prepareDirectory } = require('./runtime-directory');
+const { runtimeLocation, runtimeIdentity, requireCompatible, acquireRuntimeLock, readEndpoint, prepareDirectory } = require('./runtime-directory');
 const { executablePath } = require('./shared-kernel/executable-path');
 const starting = new Map();
 
@@ -66,11 +67,6 @@ async function probe(location, signal) {
   return { state: endpoint ? 'unresponsive' : 'starting', cause };
 }
 
-function requireCompatible(status, expected) {
-  if (status.identity.code !== expected.code) throw new CommandError('runtime_code_mismatch', 'The running runtime uses different code. Inspect runtime status and explicitly stop it before starting this build.', { details: { runtimeId: status.runtimeId, pid: status.pid } });
-  if (status.identity.config !== expected.config) throw new CommandError('runtime_configuration_mismatch', 'The running runtime uses different persistent/provider configuration. Use the same configuration or explicitly stop it first.', { details: { runtimeId: status.runtimeId, pid: status.pid } });
-}
-
 function launch(location) {
   prepareDirectory(location);
   const log = fs.openSync(location.logFile, 'a', 0o600);
@@ -132,27 +128,48 @@ async function ensureRuntime(location, identity, signal) {
   return starting.get(location.directory);
 }
 
+// The reply is always the public reply of the request. Executed commands
+// arrive assembled by the Runtime; local paths and client failures are
+// assembled here with the same module.
 async function run(request, { signal } = {}) {
+  const command = typeof request?.command === 'string' ? request.command : undefined;
+  const maxBytes = publicOutputLimit(request);
+  let extract;
   try {
     request = validateRunRequest(request);
+    if (request.command === 'runtime' || (request.command === 'evidence' && request.arguments.operation === 'verify')) {
+      extract = require('./extraction/prepare').prepareExtraction(request.extract);
+    }
+  }
+  catch (error) { return { value: publicFailure({ command, stage: 'validation', error, maxBytes }) }; }
+  const local = async reply => ({ value: await finishReply({ body: publicReply({ command: request.command, reply, completed: true }),
+    extract, output: request.output }) });
+  try {
     // Verification is an offline command in both transports; it neither
     // opens FactStore nor depends on a running owner or valid store profile.
     if (request.command === 'evidence' && request.arguments.operation === 'verify') {
-      return { value: await require('./shared-kernel/evidence-archive').handle(request.arguments) };
+      return local({ value: await require('./shared-kernel/evidence-archive').handle(request.arguments) });
     }
     const location = runtimeLocation();
     const identity = runtimeIdentity(location);
     if (request.command === 'runtime' && request.arguments.operation !== 'start') {
       const state = await probe(location, signal);
-      if (state.state === 'stopped') return { value: { ok: true, command: 'runtime', status: 'stopped', facts: location.facts } };
+      if (state.state === 'stopped') return local({ value: { ok: true, command: 'runtime', status: 'stopped', facts: location.facts } });
       if (state.state !== 'running') throw new CommandError('runtime_unresponsive', 'A runtime owns the OS lock but has not answered. It was not restarted.');
-      if (request.arguments.operation === 'stop') return await exchange(state.endpoint, 'stop', {}, { signal });
-      return { value: { ...state.status, compatible: state.status.identity.code === identity.code && state.status.identity.config === identity.config } };
+      if (request.arguments.operation === 'stop') return local(await exchange(state.endpoint, 'stop', {}, { signal }));
+      return local({ value: { ...state.status, compatible: state.status.identity.code === identity.code && state.status.identity.config === identity.config } });
     }
     const endpoint = await ensureRuntime(location, identity, signal);
-    if (request.command === 'runtime') return await exchange(endpoint, 'status', {}, { signal });
-    return await exchange(endpoint, 'execute', request, { identity, signal });
-  } catch (error) { return { value: commandFailure(error, request?.command) }; }
+    if (request.command === 'runtime') return local(await exchange(endpoint, 'status', {}, { signal }));
+    const reply = await exchange(endpoint, 'execute', request, { identity, signal });
+    if (isPublicReply(reply.value)) return reply;
+    // Authentication and request-decoding failures precede execute dispatch,
+    // so the internal RPC cannot yet identify the requested public command.
+    if (reply.value?.ok === false && reply.value.dispatched === false
+      && ['runtime_access_denied', 'runtime_protocol_error', 'runtime_message_too_large'].includes(reply.value.error)) return { value: publicFailure({
+        command: request.command, stage: 'execution', error: new CommandError(reply.value.error, reply.value.message), maxBytes: request.output?.maxBytes }) };
+    throw new CommandError('runtime_protocol_error', 'Execute returned no public reply.', { dispatched: null, ambiguous: true });
+  } catch (error) { return { value: publicFailure({ command: request.command, stage: 'execution', error, maxBytes: request.output?.maxBytes }) }; }
 }
 
 module.exports = { run, exchange };

package/bin/runtime-directory.js

@@ -11,9 +11,7 @@ const { protocol } = require('./runtime-protocol');
 const { canonicalPath } = require('./shared-kernel/canonical-path');
 const { executablePath } = require('./shared-kernel/executable-path');
 
-let fingerprint;
-function codeFingerprint() {
-  if (fingerprint) return fingerprint;
+function calculateCodeFingerprint() {
   const hash = createHash('sha256');
   function visit(directory) {
     for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
@@ -33,12 +31,19 @@ function codeFingerprint() {
   }
   const nativeDirectory = path.dirname(require.resolve('@mobileaidev/segmented-fact-store-native'));
   hash.update(fs.readFileSync(path.join(nativeDirectory, 'index.js')));
-  hash.update(fs.readFileSync(path.join(nativeDirectory, 'build/Release/segmented_fact_store.node')));
+  hash.update(fs.readFileSync(path.join(nativeDirectory, 'binding-path.js')));
+  hash.update(fs.readFileSync(path.join(nativeDirectory, 'prebuilds/manifest.json')));
+  const nativeBinding = require('@mobileaidev/segmented-fact-store-native/binding-path').resolveBinding();
+  hash.update(fs.readFileSync(nativeBinding.path));
   hash.update(JSON.stringify({ node: process.versions.node, modules: process.versions.modules }));
-  fingerprint = hash.digest('hex');
-  return fingerprint;
+  return hash.digest('hex');
 }
 
+// Pin the running client's code when this entrypoint loads, before the first
+// request. Replacing installed files cannot make this process claim new code.
+const fingerprint = calculateCodeFingerprint();
+const packageVersion = require('../package.json').version;
+
 function runtimeLocation() {
   const target = hostFactStoreTarget();
   const facts = canonicalPath(target.directory);
@@ -55,7 +60,31 @@ function runtimeIdentity(location = runtimeLocation()) {
   const config = { facts: location.facts, profile: location.profile, ownership: canonicalPath(ownershipDirectory()),
     adb: executablePath(process.env.ADB || 'adb') ?? { unavailable: process.env.ADB || 'adb' },
     environment: Object.fromEntries(names.map(name => [name, process.env[name] ?? null])) };
-  return { protocol, code: codeFingerprint(), config: createHash('sha256').update(JSON.stringify(config)).digest('hex') };
+  return { protocol, code: fingerprint, config: createHash('sha256').update(JSON.stringify(config)).digest('hex'),
+    version: packageVersion, node: { version: process.versions.node, modules: process.versions.modules, napi: process.versions.napi } };
+}
+
+function requireCompatible(status, client) {
+  const runtime = status.identity;
+  const codeMismatch = runtime?.code !== client?.code;
+  const configMismatch = runtime?.config !== client?.config;
+  if (!codeMismatch && !configMismatch) return;
+  const parse = version => typeof version === 'string' && /^\d+\.\d+\.\d+$/.test(version) ? version.split('.').map(Number) : null;
+  const runtimeVersion = parse(runtime?.version), clientVersion = parse(client?.version);
+  let outdatedSide = 'undetermined';
+  if (runtimeVersion && clientVersion) {
+    const index = runtimeVersion.findIndex((part, i) => part !== clientVersion[i]);
+    if (index >= 0) outdatedSide = runtimeVersion[index] < clientVersion[index] ? 'runtime' : 'client';
+  }
+  const describe = identity => `package ${identity?.version ?? 'unknown'}, Node ${identity?.node?.version ?? 'unknown'}, ABI ${identity?.node?.modules ?? 'unknown'}, code ${identity?.code ?? 'unknown'}, config ${identity?.config ?? 'unknown'}`;
+  let next;
+  if (!codeMismatch) next = 'Use matching persistent/provider configuration; the running Runtime was not restarted.';
+  else if (outdatedSide === 'client') next = 'The client package is older. Update and reconnect the client; do not stop the newer Runtime to fix this client.';
+  else if (outdatedSide === 'runtime') next = 'The Runtime package is older. Finish its active tasks, then explicitly run runtime --operation stop --extract null and reconnect with the updated installation.';
+  else next = 'Builds or Node environments differ. Align the installations and reconnect; fingerprints alone cannot identify an older side.';
+  throw new CommandError(codeMismatch ? 'runtime_code_mismatch' : 'runtime_configuration_mismatch',
+    `Client: ${describe(client)}. Runtime: ${describe(runtime)}. ${next}`,
+    { details: { runtimeId: status.runtimeId, pid: status.pid, client, runtime, outdatedSide } });
 }
 
 function prepareDirectory(location) {
@@ -106,4 +135,4 @@ function publishEndpoint(location, endpoint) {
   fs.renameSync(temporary, location.endpointFile);
 }
 
-module.exports = { runtimeLocation, runtimeIdentity, prepareDirectory, acquireRuntimeLock, readEndpoint, publishEndpoint };
+module.exports = { runtimeLocation, runtimeIdentity, requireCompatible, prepareDirectory, acquireRuntimeLock, readEndpoint, publishEndpoint };