@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/shared-kernel/flutter-h5-port.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const { executionSleep } = require('./execution-scope');
+const { validateValue } = require('./argument-schema');
+const h5 = require('./flutter-h5-target');
+const reject = error => ({ ok: false, error, dispatched: false, ambiguous: false });
+
+// The same managed Flutter action port owns admission, receipts and cancellation.
+// No arbitrary JavaScript or active-adapter lookup is used by typed commands.
+function createFlutterH5Port(invoke, { actionId } = {}) {
+  const mutate = payload => invoke(payload, { actionId });
+  async function snapshot(adapterId) {
+    const result = await invoke({ action: 'h5Dom', ...(adapterId === undefined ? {} : { adapterId }) }, { actionId: randomUUID() });
+    if (result.ok !== true) return result;
+    if (result.h5TargetSchema !== h5.schema) return reject('flutter_h5_target_schema_required');
+    try { validateValue(result.pageRef, h5.pageSchema, 'pageRef'); }
+    catch { return reject('invalid_flutter_h5_page_ref'); }
+    if (!Array.isArray(result.dom?.controls) || typeof result.dom.truncated !== 'boolean'
+        || result.dom.documentId !== result.pageRef.documentId || result.dom.url !== result.pageRef.url) return reject('invalid_flutter_h5_snapshot');
+    if (adapterId !== undefined && result.pageRef.adapterId !== adapterId) return reject('reobserve_required');
+    return result;
+  }
+  async function control(operation, options) {
+    const expected = options.expectedTarget?.pageRef ?? options.expectedPage;
+    if (options.adapterId !== undefined && expected && options.adapterId !== expected.adapterId) return reject('flutter_h5_adapter_conflict');
+    const tree = await snapshot(options.adapterId ?? expected?.adapterId);
+    if (tree.ok !== true) return tree;
+    if (operation === 'scrollBy') {
+      if (expected !== undefined && !isDeepStrictEqual(expected, tree.pageRef)) return reject('reobserve_required');
+      return mutate({ action: 'h5Control', operation, expectedPage: tree.pageRef,
+        deltaX: options.deltaX, deltaY: options.deltaY });
+    }
+    const selected = h5.selectH5Node(tree, options.selector, options.expectedTarget);
+    if (!selected.ok) return selected;
+    return mutate({ action: 'h5Control', operation, expectedTarget: selected.targetRef,
+      ...(operation === 'input' ? { text: options.text } : {}) });
+  }
+  async function wait(options) {
+    const timeoutMs = options.timeoutMs ?? 5000, intervalMs = options.intervalMs ?? 250;
+    const deadline = Date.now() + timeoutMs;
+    let page, selected;
+    do {
+      const tree = await snapshot(page?.adapterId ?? options.adapterId);
+      if (tree.ok !== true) return tree;
+      if (page && !isDeepStrictEqual(page, tree.pageRef)) return reject('reobserve_required');
+      page = tree.pageRef;
+      selected = h5.selectH5Node(tree, options.selector);
+      if (selected.ok || selected.error !== 'flutter_h5_selector_not_found') return selected;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await executionSleep(Math.min(intervalMs, remaining));
+    } while (Date.now() < deadline);
+    return { ...reject('flutter_h5_wait_timeout'), timeoutMs, lastResult: selected };
+  }
+  return { snapshot, control, wait,
+    evaluate: options => mutate({ action: 'h5Eval', script: options.script, expectedPage: options.expectedPage }) };
+}
+module.exports = { createFlutterH5Port };

package/bin/shared-kernel/flutter-h5-target.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const { object, text } = require('./argument-schema');
+const { h5TargetContract } = require('./h5-target');
+const schema = 'aab.flutter-h5-target/v1';
+const fields = ['runtimeEpoch', 'adapterId', 'adapterGeneration', 'documentId', 'url'];
+const pageSchema = object({ schemaVersion: { const: schema },
+  ...Object.fromEntries(fields.map(key => [key, text])) }, ['schemaVersion', ...fields]);
+module.exports = h5TargetContract({ schema, pageSchema, errorPrefix: 'flutter_h5' });

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

@@ -0,0 +1,75 @@
+'use strict';
+
+const { validBounds } = require('./native-target');
+
+function selectFlutterNode(rawTree, spec) {
+  const reject = error => ({ ok: false, error, dispatched: false });
+  if (!Array.isArray(rawTree?.nodes) || rawTree.ok === false) return reject('observed_flutter_tree_required');
+  if (rawTree.truncated === true) return reject('flutter_observation_incomplete');
+  const selector = spec.selector || (typeof spec.text === 'string' ? { text: spec.text } : null);
+  const keys = Object.keys(selector || {});
+  if (keys.length !== 1 || !['text', 'nodeId'].includes(keys[0])
+    || typeof selector[keys[0]] !== 'string' || !selector[keys[0]]
+    || spec.exact === false || (spec.selector && spec.text != null)) return reject('explicit_exact_flutter_selector_required');
+  const action = spec.action === 'inputText' ? 'input' : ['scrollBy', 'scrollUntilText'].includes(spec.action) ? 'scroll' : 'tap';
+  const operable = node => node.enabled !== false && node.visible !== false && node.offstage !== true && validBounds(node[action]?.bounds);
+  const matches = rawTree.nodes.filter(node => keys[0] === 'nodeId'
+    ? node.id != null && String(node.id) === selector.nodeId
+    : (node.text === selector.text || node.value === selector.text) && operable(node));
+  if (matches.length !== 1) return reject(matches.length ? 'flutter_selector_not_unique' : 'flutter_selector_not_found');
+  const node = matches[0];
+  if (!operable(node)) return reject('flutter_node_not_operable');
+  const bounds = node[action].bounds;
+  const x = (bounds.left + bounds.right) / 2, y = (bounds.top + bounds.bottom) / 2;
+  const viewport = rawTree.viewport;
+  if (x < 0 || y < 0 || (Number.isFinite(viewport?.logicalWidth) && x >= viewport.logicalWidth)
+    || (Number.isFinite(viewport?.logicalHeight) && y >= viewport.logicalHeight)) return reject('flutter_node_not_operable');
+  return { ok: true, node, x, y };
+}
+
+function flutterNodeIdentity(node) {
+  return Object.fromEntries(['id', 'text', 'value', 'label', 'hint', 'widgetType', 'role', 'targetRef'].map(key => [key, node?.[key] ?? null]));
+}
+
+function flutterTargetRequest(node, selector) {
+  const ref = node?.targetRef;
+  if (!ref || ref.schemaVersion !== 'aab.flutter-target/v1'
+    || !['runtimeEpoch', 'elementId', 'guard'].every(key => typeof ref[key] === 'string' && ref[key])) {
+    return { ok: false, error: 'flutter_atomic_target_unavailable', dispatched: false, ambiguous: false,
+      message: 'Update the Flutter SDK and observe again. This action requires a live Element reference.' };
+  }
+  return { ok: true, request: { selector, targetRef: ref } };
+}
+
+function bindFlutterAction(rawTree, payload) {
+  const reject = error => ({ ok: false, error, dispatched: false, ambiguous: false });
+  if (rawTree?.ok === false || !Array.isArray(rawTree?.nodes) || rawTree.truncated === true) return reject('flutter_observation_incomplete');
+  let selector = payload.selector;
+  if (payload.action === 'tapText') selector = { text: payload.text };
+  if (!selector) {
+    const action = payload.action === 'inputText' ? 'input' : 'scroll';
+    let nodes = rawTree.nodes.filter(node => validBounds(node[action]?.bounds) && node.enabled !== false && node.visible !== false);
+    if (action === 'input') {
+      if (payload.x !== undefined || payload.y !== undefined) {
+        if (!Number.isFinite(payload.x) || !Number.isFinite(payload.y)) return reject('invalid_flutter_coordinates');
+        nodes = nodes.filter(node => { const b = node.input.bounds; return payload.x >= b.left && payload.x < b.right && payload.y >= b.top && payload.y < b.bottom; });
+      } else {
+        const focused = nodes.filter(node => node.input.focused === true);
+        if (focused.length) nodes = focused;
+      }
+    } else nodes = nodes.filter(node => node.role === 'scrollable');
+    if (nodes.length !== 1) return reject(nodes.length ? 'flutter_selector_not_unique' : 'flutter_selector_not_found');
+    selector = { nodeId: String(nodes[0].id) };
+  }
+  const selected = selectFlutterNode(rawTree, { action: payload.action, selector });
+  if (!selected.ok) return selected;
+  const guarded = flutterTargetRequest(selected.node, selector);
+  if (!guarded.ok) return guarded;
+  const { x, y, ...action } = payload;
+  if (payload.action === 'tapText') delete action.text;
+  return { ok: true, payload: {
+    ...action, ...(payload.action === 'tapText' ? { action: 'tapTarget' } : {}), ...guarded.request,
+  } };
+}
+
+module.exports = { selectFlutterNode, flutterNodeIdentity, flutterTargetRequest, bindFlutterAction };

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

@@ -0,0 +1,11 @@
+'use strict';
+
+const managed = require('./managed-sdk-execution');
+const schema = 'aab.h5-execution/v1';
+
+module.exports = {
+  schema,
+  executeH5Action: options => managed.executeManagedAction({ ...options, kind: 'h5', schema }),
+  terminalReceipt: (result, identity) => managed.terminalReceipt(schema, result, identity),
+  settlementProof: (result, identity) => managed.settlementProof('h5', schema, result, identity),
+};

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

@@ -0,0 +1,31 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('node:util');
+const { object, text } = require('./argument-schema');
+const string = { type: 'string' };
+const elementKeys = ['elementId', 'tag', 'id', 'name', 'type', 'text', 'ariaLabel', 'href'];
+const elementSchema = object(Object.fromEntries(elementKeys.map(key => [key,
+  key === 'elementId' ? text : string])), elementKeys);
+const selectorSchema = { ...object({ elementId: text, text, ariaLabel: text, tag: text }),
+  oneOf: ['elementId', 'text', 'ariaLabel'].map(key => ({ required: [key] })) };
+
+function h5TargetContract({ schema, pageSchema, errorPrefix }) {
+  const expectedTargetSchema = object({ pageRef: pageSchema, element: elementSchema }, ['pageRef', 'element']);
+  const reject = error => ({ ok: false, error, dispatched: false, ambiguous: false });
+  function selectH5Node(tree, selector, expectedTarget) {
+    if (tree?.h5TargetSchema !== schema) return reject(errorPrefix + '_target_schema_required');
+    if (tree.dom.truncated && selector.elementId === undefined) return reject(errorPrefix + '_snapshot_truncated');
+    const nodes = tree.dom.controls.filter(node => node.visible === true
+      && ['elementId', 'text', 'ariaLabel', 'tag'].every(key => selector[key] === undefined || selector[key] === node[key]));
+    if (nodes.length !== 1) return { ...reject(errorPrefix + (nodes.length ? '_selector_ambiguous' : '_selector_not_found')),
+      matched: nodes.length };
+    const node = nodes[0];
+    if (node.disabled) return reject(errorPrefix + '_target_disabled');
+    const targetRef = { pageRef: tree.pageRef, element: Object.fromEntries(elementKeys.map(key => [key, node[key]])) };
+    if (expectedTarget !== undefined && !isDeepStrictEqual(expectedTarget, targetRef)) return reject('reobserve_required');
+    return { ok: true, node, targetRef };
+  }
+  return { schema, selectorSchema, pageSchema, expectedTargetSchema, selectH5Node };
+}
+
+module.exports = { h5TargetContract };

package/bin/shared-kernel/host-fact-store.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const path = require('node:path');
+const { createFactStore } = require('../fact-store');
+const { defaultSegmentedFactStorePath } = require('../segmented-fact-store');
+const { CommandError } = require('../command-errors');
+const { canonicalPath } = require('./canonical-path');
+
+let shared;
+let exitInstalled = false;
+
+function hostFactStoreTarget() {
+  const explicit = process.env.AI_APP_BRIDGE_FACT_STORE_DIR, legacy = process.env.AI_APP_BRIDGE_FACT_CACHE_PATH;
+  const profile = process.env.AI_APP_BRIDGE_FACT_CACHE_PROFILE || 'auto';
+  if (!['auto', '64mb', '256mb', '512mb', '1gb'].includes(profile))
+    throw new CommandError('invalid_fact_store_profile', 'FactStore profile must be auto, 64mb, 256mb, 512mb or 1gb.');
+  return { directory: canonicalPath(explicit || (legacy ? path.join(path.dirname(path.resolve(legacy)), 'fact-store-v1') : defaultSegmentedFactStorePath())),
+    profile };
+}
+
+function open(target) {
+  try { return createFactStore(target); }
+  catch (error) {
+    if (error.code === 'sfs_busy') throw new CommandError('fact_store_writer_busy',
+      'Another Host owns this FactStore. Reconcile from that Host, or close it before retrying. Original device acknowledgement remains pending.');
+    throw error;
+  }
+}
+
+function getHostFactStore() {
+  if (!shared || shared.closed) shared = open(hostFactStoreTarget());
+  if (!exitInstalled) {
+    exitInstalled = true;
+    process.once('exit', () => { try { shared?.close(); } catch { /* Process exit retains committed facts. */ } });
+  }
+  return shared;
+}
+
+function closeHostFactStore() { shared?.close(); shared = null; }
+
+function withHostFactStore(target, action) {
+  if (canonicalPath(target.directory) === hostFactStoreTarget().directory) return action(getHostFactStore());
+  // Recovery follows the original journal's store destination, even when this
+  // Host was opened with a different recording directory. Close this bounded handle.
+  const store = open(target);
+  try { return action(store); } finally { store.close(); }
+}
+
+module.exports = { hostFactStoreTarget, getHostFactStore, closeHostFactStore, withHostFactStore };

package/bin/shared-kernel/ios-h5-target.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const { object, text, integer } = require('./argument-schema');
+const { h5TargetContract } = require('./h5-target');
+const schema = 'aab.ios-h5-target/v1';
+const pageSchema = object({ schemaVersion: { const: schema }, runtimeEpoch: text, bundleId: text,
+  processId: integer(1), webViewId: text, documentId: text, url: text },
+['schemaVersion', 'runtimeEpoch', 'bundleId', 'processId', 'webViewId', 'documentId', 'url']);
+module.exports = h5TargetContract({ schema, pageSchema, errorPrefix: 'ios_h5' });

package/bin/shared-kernel/ios-native-target.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('node:util');
+const { object, text, integer } = require('./argument-schema');
+
+const schema = 'aab.ios-native-target/v1';
+const sessionSchema = 'aab.ios-native-session/v1';
+const orientationSchema = { enum: ['portrait', 'landscapeLeft', 'landscapeRight', 'portraitUpsideDown'],
+  description: 'Requested App interface orientation. Landscape directions are UIInterfaceOrientation, not the opposite UIDeviceOrientation.' };
+const expectedSessionSchema = object({ schemaVersion: { const: sessionSchema }, runnerEpoch: text,
+  bundleId: text, processId: integer(1), sessionId: text },
+['schemaVersion', 'runnerEpoch', 'bundleId', 'processId', 'sessionId']);
+const nullableLabel = { anyOf: [{ type: 'string', maxLength: 16384 }, { type: 'null' }] };
+const selectorSchema = { ...object({ accessibilityId: text, label: text, elementId: text, type: text }),
+  oneOf: ['accessibilityId', 'label', 'elementId'].map(key => ({ required: [key] })) };
+const elementSchema = object({ elementId: text, type: text, identifier: nullableLabel, label: nullableLabel },
+  ['elementId', 'type', 'identifier', 'label']);
+const expectedTargetSchema = object({ schemaVersion: { const: schema }, runnerEpoch: text,
+  bundleId: text, processId: integer(1), sessionId: text, element: elementSchema },
+['schemaVersion', 'runnerEpoch', 'bundleId', 'processId', 'sessionId', 'element']);
+const reject = error => ({ ok: false, error, dispatched: false, ambiguous: false });
+
+function nodesOf(tree) {
+  const nodes = [];
+  function walk(node) {
+    if (!node || typeof node !== 'object') return;
+    nodes.push(node);
+    for (const child of node.children || []) walk(child);
+  }
+  walk(tree.source);
+  return nodes;
+}
+
+function elementRef(node) {
+  return { elementId: node.elementId, type: node.type, identifier: node.rawIdentifier, label: node.label };
+}
+
+function targetRef(tree, node) {
+  return { schemaVersion: schema, runnerEpoch: tree.runtimeBinding.runtimeEpoch,
+    bundleId: tree.session.bundleId, processId: tree.session.processId,
+    sessionId: tree.session.sessionId, element: elementRef(node) };
+}
+
+function sessionRef(tree) {
+  return { schemaVersion: sessionSchema, runnerEpoch: tree.runtimeBinding.runtimeEpoch,
+    bundleId: tree.session.bundleId, processId: tree.session.processId, sessionId: tree.session.sessionId };
+}
+
+function selectNativeNode(tree, selector) {
+  if (tree?.nativeTargetSchema !== schema) return reject('ios_native_target_schema_required');
+  const nodes = nodesOf(tree).filter(node => node.isVisible === '1'
+    && (selector.type === undefined || node.type === selector.type)
+    && (selector.accessibilityId === undefined || node.rawIdentifier === selector.accessibilityId)
+    && (selector.label === undefined || node.label === selector.label)
+    && (selector.elementId === undefined || node.elementId === selector.elementId));
+  if (nodes.length !== 1) return { ...reject(nodes.length ? 'ios_native_selector_ambiguous' : 'ios_native_selector_not_found'), matched: nodes.length };
+  const node = nodes[0];
+  if (typeof node.elementId !== 'string' || !node.elementId) return reject('ios_native_element_identity_required');
+  if (node.isEnabled !== '1') return reject('ios_native_target_disabled');
+  return { ok: true, node, targetRef: targetRef(tree, node), matched: 1 };
+}
+
+function bindNativeTarget(tree, selector, expectedTarget) {
+  const selected = selectNativeNode(tree, selector);
+  if (!selected.ok) return selected;
+  if (expectedTarget !== undefined && !isDeepStrictEqual(selected.targetRef, expectedTarget)) return reject('reobserve_required');
+  return selected;
+}
+
+module.exports = { schema, selectorSchema, expectedTargetSchema, nodesOf, selectNativeNode, bindNativeTarget, targetRef,
+  orientationSchema, expectedSessionSchema, sessionRef };

package/bin/shared-kernel/live-capture-query.js

@@ -0,0 +1,115 @@
+'use strict';
+
+function createLiveCaptureQuery({ runner } = {}) {
+  if (typeof runner !== 'function') {
+    throw new TypeError('runner');
+  }
+
+  async function query(request = {}) {
+    const command = commandFor(request);
+    if (!command) return unavailablePage('unsupported_capture_stream');
+    const { command: _command, stream: _stream, platform: _platform, ...args } = request;
+    // CaptureRequest uses null for an absent window boundary. Public command
+    // arguments represent absence by omission; no payload or error is replaced.
+    for (const key of ['serial', 'packageName', 'afterActionId', 'runtimeEpoch', 'sinceMs', 'timeoutMs']) {
+      if (args[key] == null) delete args[key];
+    }
+    let result;
+    try {
+      result = await runner(command, {
+        ...args,
+        limit: request.limit == null ? (command.startsWith('web-') ? 16 : 200) : request.limit,
+      });
+    } catch (error) {
+      return unavailablePage(error.code || error.message || 'capture_query_failed', error);
+    }
+    if (request.view === 'decision-window' && request.runtimeEpoch != null
+      && result?.runtimeEpoch !== request.runtimeEpoch && result?.coverage?.status === 'complete') {
+      return unavailablePage('runtime_epoch_changed');
+    }
+    const expectedTarget = request.targetKey ?? (command.startsWith('ios-') ? request.bundleId : request.packageName);
+    if (expectedTarget != null && result?.targetKey !== expectedTarget
+      && result?.coverage?.status === 'complete') return unavailablePage('capture_target_mismatch');
+    return capturePage(result);
+  }
+
+  return query;
+}
+
+// Keep mobile-issued window, epoch, refs and pagination intact through each port.
+// Legacy payloads and explicit failures never acquire invented strong coverage.
+function capturePage(result) {
+  const coverage = coverageOf(result);
+  if (!result || result.ok === false || result.error || !coverage || coverage.status === 'unavailable') {
+    return unavailablePage(result?.error || result?.reason || 'capture_contract_unavailable', result || {});
+  }
+  if (!Array.isArray(result.refs) || !Array.isArray(result.items)) {
+    return unavailablePage('capture_contract_invalid');
+  }
+  return {
+    ...result,
+    coverage,
+    gap: coverage.gap === true || result.gap === true,
+    committed: coverage.committed === true,
+  };
+}
+
+function coverageOf(result) {
+  const coverage = result && result.coverage;
+  if (
+    !coverage
+    || (coverage.status !== 'complete'
+      && coverage.status !== 'partial'
+      && coverage.status !== 'unavailable')
+  ) {
+    return null;
+  }
+  return coverage;
+}
+
+// The durable observation and the portable payload verifier share this exact
+// metadata projection. Optional diagnostics remain absent when not supplied.
+function capturePageMetadata(page) {
+  return {
+    stream: page.stream, coverage: page.coverage, window: page.window,
+    runtimeEpoch: page.runtimeEpoch, targetKey: page.targetKey, storeGeneration: page.storeGeneration,
+    watermarkCursor: page.watermarkCursor, nextCursor: page.nextCursor,
+    hasMore: page.hasMore, throughWatermark: page.throughWatermark,
+    ...(page.barrier === undefined ? {} : { barrier: page.barrier }),
+    error: page.error || page.reason || null,
+    ...(page.field === undefined ? {} : { field: page.field }),
+    ...(page.message === undefined ? {} : { message: page.message }),
+  };
+}
+
+function commandFor(request) {
+  const stream = request.stream;
+  if (stream !== 'logs' && stream !== 'network' && stream !== 'state' && stream !== 'events') {
+    return null;
+  }
+  if (request.command) {
+    const commands = [stream, `ios-${stream}`, `web-${stream}`];
+    if (stream === 'logs') commands.push('webview-console');
+    if (stream === 'network') commands.push('webview-network');
+    return commands.includes(request.command) ? request.command : null;
+  }
+  if (request.platform === 'ios') return `ios-${stream}`;
+  if (request.platform === 'web') return `web-${stream}`;
+  return stream;
+}
+
+function unavailablePage(error = 'capture_unavailable', { field, message } = {}) {
+  return {
+    ok: false,
+    error,
+    ...(field === undefined ? {} : { field }),
+    ...(message === undefined ? {} : { message }),
+    coverage: { status: 'unavailable', gap: true, committed: false },
+    gap: true,
+    committed: false,
+    refs: [],
+    items: [],
+  };
+}
+
+module.exports = { createLiveCaptureQuery, capturePage, capturePageMetadata, unavailablePage };

package/bin/shared-kernel/managed-sdk-execution.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const { randomUUID, createHash } = require('node:crypto');
+const { currentExecution, checkExecution, withoutExecution } = require('./execution-scope');
+
+function terminalReceipt(schema, result, identity) {
+  const execution = result?.execution;
+  return execution?.schemaVersion === schema && execution.actionId === identity.actionId
+    && execution.runtimeEpoch === identity.runtimeEpoch && execution.settled === true
+    && result.actionId === identity.actionId && result.runtimeEpoch === identity.runtimeEpoch && result.settled === true
+    && typeof result.ok === 'boolean' && typeof result.dispatched === 'boolean' && typeof result.ambiguous === 'boolean'
+    && (result.ok === false ? typeof result.error === 'string' && result.error.length > 0 : result.ambiguous === false);
+}
+
+// Managed SDK execution validates one original action identity. Closing HTTP
+// is never a completion receipt. Cleanup addresses the exact dispatched peer.
+async function executeManagedAction({ kind, schema, runtime, payload, actionId, timeoutMs, send, cancel }) {
+  if (runtime?.executionSchema !== schema || typeof runtime.runtimeEpoch !== 'string' || !runtime.runtimeEpoch) return {
+    ok: false, error: `${kind}_execution_unavailable`, dispatched: false, ambiguous: false,
+    message: `The app SDK does not advertise managed ${kind} execution. Update the SDK and observe again.`,
+  };
+  checkExecution();
+  const identity = { actionId: actionId ?? randomUUID(), runtimeEpoch: runtime.runtimeEpoch };
+  const scope = currentExecution();
+  const remaining = Math.min(scope ? scope.deadlineMs - Date.now() : Infinity, timeoutMs, 2147483647);
+  if (!(remaining >= 1)) return { ok: false, error: 'deadline_exceeded', dispatched: false, ambiguous: false };
+  const request = { ...payload, actionId: identity.actionId,
+    execution: { schemaVersion: schema, ...identity, timeoutMs: Math.floor(remaining) } };
+  let failure;
+  try {
+    const result = await send(request);
+    if (terminalReceipt(schema, result, identity)) return { ...result, request, executionReceipt: settlementProof(kind, schema, result, identity) };
+    if (result?.ok === false && typeof result.error === 'string' && result.error
+        && result.dispatched === false && result.ambiguous === false && !result.execution) return { ...result, request, executionReceipt: settlementProof(kind, schema, result, identity) };
+    const pending = result?.schemaVersion === schema && result.actionId === identity.actionId
+      && result.runtimeEpoch === identity.runtimeEpoch && result.ok === false && result.settled === false
+      && result.dispatched === null && result.ambiguous === true && typeof result.error === 'string' && result.error;
+    failure = { code: pending ? result.error : `invalid_${kind}_execution_receipt`, response: result };
+  } catch (error) {
+    if (error.aiAppBridgeRequestNotStarted === true || error.dispatched === false) return {
+      ok: false, error: error.code || `${kind}_request_not_started`, message: error.message,
+      dispatched: false, ambiguous: false, request,
+    };
+    failure = error;
+  }
+  let cancellation;
+  try { cancellation = await withoutExecution(() => cancel(identity)); }
+  catch (error) { cancellation = { ok: false, error: error.code || error.message }; }
+  let receipt;
+  if (cancellation?.ok === true && cancellation.actionId === identity.actionId && cancellation.runtimeEpoch === identity.runtimeEpoch
+      && terminalReceipt(schema, cancellation.executionResult, identity)) receipt = cancellation.executionResult;
+  else if (cancellation?.ok !== false || typeof cancellation.error !== 'string' || !cancellation.error) {
+    cancellation = { ok: false, error: `invalid_${kind}_cancel_receipt`, response: cancellation };
+  }
+  return { ok: false, error: failure.code || `${kind}_action_response_lost`,
+    actionId: identity.actionId, runtimeEpoch: identity.runtimeEpoch, request,
+    dispatched: receipt?.dispatched ?? null, ambiguous: receipt?.ambiguous ?? true, settled: Boolean(receipt),
+    cancellation, executionReceipt: receipt ? settlementProof(kind, schema, receipt, identity) : null, ...(failure.response === undefined ? {} : { response: failure.response }) };
+}
+
+function settlementProof(kind, schema, result, identity) {
+  const receipt = terminalReceipt(schema, result, identity) ? result
+    : result?.cancellation?.ok === true && terminalReceipt(schema, result.cancellation.executionResult, identity)
+      ? result.cancellation.executionResult : null;
+  if (receipt) {
+    const { request, executionReceipt, transport, ...wireReceipt } = receipt;
+    return { kind, settled: true, actionId: identity.actionId, runtimeEpoch: identity.runtimeEpoch,
+    execution: receipt.execution, dispatched: receipt.dispatched, ambiguous: receipt.ambiguous, error: receipt.error ?? null,
+    responseSha256: createHash('sha256').update(JSON.stringify(wireReceipt)).digest('hex') };
+  }
+  if (result?.dispatched === false && result.ambiguous === false && result.settled !== false && !result.execution) return {
+    kind, settled: true, actionId: identity.actionId, runtimeEpoch: identity.runtimeEpoch,
+    dispatched: false, ambiguous: false, error: result.error ?? null,
+  };
+  return null;
+}
+
+module.exports = { executeManagedAction, terminalReceipt, settlementProof };

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

@@ -0,0 +1,13 @@
+'use strict';
+
+const managed = require('./managed-sdk-execution');
+const schema = 'aab.native-execution/v1';
+
+function executeNativeAction({ runtime, ...options }) {
+  return managed.executeManagedAction({ ...options, kind: 'native', schema, runtime: runtime });
+}
+
+module.exports = { schema, executeNativeAction,
+  terminalReceipt: (result, identity) => managed.terminalReceipt(schema, result, identity),
+  settlementProof: (result, identity) => managed.settlementProof('native', schema, result, identity),
+};