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

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

@@ -0,0 +1,171 @@
+'use strict';
+
+const { object, integer, text, milliseconds } = require('./argument-schema');
+const { executionTargetSchema } = require('./execution-target');
+const { observationTargetSchema, intentTargetSchema } = require('../intent/intent-observation-target');
+const { selectorSchema: iosNativeSelector } = require('./ios-native-target');
+
+const boolean = { type: 'boolean' };
+const number = { type: 'number', minimum: -2147483647, maximum: 2147483647 };
+const revision = integer(1);
+const afterSequence = { ...integer(0), default: 0 };
+const pageLimit = integer(1, 1000);
+const provider = { enum: ['native', 'uia', 'flutter', 'h5'] };
+const packageName = { ...text, pattern: '^[A-Za-z][A-Za-z0-9_]*(?:\\.[A-Za-z][A-Za-z0-9_]*)+$' };
+const jsonObject = { type: 'object', additionalProperties: true, description: 'Application data; nested values must be JSON.' };
+const array = (items, minItems = 0, maxItems = 1000) => ({ type: 'array', items, minItems, maxItems });
+
+function variants(tag, branches) {
+  const properties = {};
+  for (const branch of branches) {
+    for (const [name, rule] of Object.entries(branch.properties)) {
+      const prior = properties[name];
+      if (!prior) properties[name] = rule;
+      else if (JSON.stringify(prior) !== JSON.stringify(rule)) properties[name] = { anyOf: [prior, rule] };
+    }
+  }
+  properties[tag] = { type: 'string', enum: [...new Set(branches.flatMap(branch => branch.properties[tag].enum || [branch.properties[tag].const]))] };
+  return { ...object(properties, [tag]), anyOf: branches };
+}
+
+function exactlyOne(properties, keys, required = []) {
+  return { ...object(properties, required), oneOf: keys.map(key => ({ required: [key] })) };
+}
+
+const nodeLabels = { text, resourceName: text, contentDescription: text };
+const nodeIdentity = exactlyOne({ className: text, resourceName: text }, ['className', 'resourceName']);
+const ancestor = exactlyOne({ ...nodeIdentity.properties, parent: nodeIdentity }, ['className', 'resourceName']);
+const within = exactlyOne({ ...nodeLabels, ancestor }, Object.keys(nodeLabels), ['ancestor']);
+const nativeSelector = exactlyOne({ ...nodeLabels, within }, Object.keys(nodeLabels));
+const uiaSelector = require('./uia-target').intentSelectorSchema;
+const flutterSelector = exactlyOne({ text, nodeId: text }, ['text', 'nodeId']);
+
+function nativeGestureBranches(make) {
+  const selector = nativeSelector;
+  return [
+    make('longPress', { selector, durationMs: integer(500, 10000) }, ['selector', 'durationMs']),
+    make('swipe', { selector, deltaX: number, deltaY: number, durationMs: integer(1, 10000) }, ['selector', 'deltaX', 'deltaY', 'durationMs']),
+    make('scroll', { selector, direction: { enum: ['up', 'down'] }, durationMs: { ...integer(1, 10000), default: 400 } }, ['selector', 'direction']),
+  ];
+}
+
+function nativeGestureSchema() {
+  return variants('action', nativeGestureBranches((action, properties, required) => object({ action: { const: action }, ...properties }, ['action', ...required])));
+}
+
+function intentActionSchema(activeProvider, platform) {
+  const branches = [];
+  for (const name of activeProvider ? [activeProvider] : provider.enum) {
+    const make = (action, properties = {}, required = []) => object({ action: { const: action }, provider: { const: name }, ...properties }, ['action', ...required]);
+    if (name === 'h5') {
+      const webSelector = require('./web-dom-target').intentSelectorSchema;
+      if (platform === 'web' || platform === undefined) {
+        branches.push(make('tap', { selector: webSelector }, ['selector']), make('scroll', { selector: webSelector }, ['selector']),
+          make('inputText', { selector: webSelector, value: { type: 'string', maxLength: 16384 } }, ['selector', 'value']),
+          make('pressKey', { selector: webSelector, key: { enum: ['Enter', 'Escape'] } }, ['selector', 'key']),
+          make('scrollBy', { selector: webSelector, deltaX: number, deltaY: number }, ['selector', 'deltaX', 'deltaY']));
+        if (platform === 'web') continue;
+      }
+      const selector = require('./ios-h5-target').selectorSchema;
+      branches.push(make('tap', { selector }, ['selector']), make('scroll', { selector }, ['selector']),
+        make('inputText', { selector, value: { type: 'string', maxLength: 16384 } }, ['selector', 'value']));
+      continue;
+    }
+    const native = platform === 'ios' ? iosNativeSelector : platform === 'android' ? nativeSelector
+      : { allOf: [object({ ...nativeSelector.properties, ...iosNativeSelector.properties }), { anyOf: [nativeSelector, iosNativeSelector] }] };
+    const selector = name === 'native' ? native : name === 'uia' ? uiaSelector : flutterSelector;
+    if (name === 'native' && (platform === 'ios' || platform === undefined)) {
+      branches.push(make('setOrientation', { orientation: require('./ios-native-target').orientationSchema }, ['orientation']));
+    }
+    branches.push(make('tap', { selector }, ['selector']));
+    if (name === 'native' && platform === 'ios') {
+      branches.push(make('inputText', { selector, value: { type: 'string', maxLength: 16384 } }, ['selector', 'value']));
+      continue;
+    }
+    branches.push(make('back'));
+    if (platform !== 'ios') branches.push(make('keyevent', { keyCode: integer(0, 2147483647) }, ['keyCode']));
+    if (name === 'native') {
+      branches.push(make('inputText', { selector, value: { type: 'string' } }, ['selector', 'value']));
+      branches.push(...nativeGestureBranches(make));
+    }
+    if (name === 'flutter') {
+      branches.push(make('inputText', { selector, value: { type: 'string' } }, ['selector', 'value']));
+      branches.push(make('scrollBy', { selector, delta: number }, ['selector', 'delta']));
+      branches.push(make('hideKeyboard'));
+    }
+    else if (name === 'uia') branches.push(make('scroll', { direction: { enum: ['up', 'down'] }, durationMs: { ...integer(1, 10000), default: 400 } }, ['direction']));
+  }
+  return variants('action', branches);
+}
+
+function intentDecisionSchema(activeProvider, platform) {
+  const common = { decisionId: text, basedOnRevision: revision, reason: text };
+  return variants('agentDecision', [
+    object({ ...common, agentDecision: { const: 'act' }, action: intentActionSchema(activeProvider, platform) }, ['decisionId', 'basedOnRevision', 'agentDecision', 'action']),
+    ...['complete', 'fail', 'inconclusive'].map(value => object({ ...common, agentDecision: { const: value } }, ['decisionId', 'basedOnRevision', 'agentDecision'])),
+  ]);
+}
+
+const intentTarget = intentTargetSchema();
+const scriptTarget = executionTargetSchema({ nullable: true });
+const intentActionNames = intentActionSchema().properties.action.enum;
+const intentBudget = object({ maxSteps: { ...integer(1, 10000), default: 30 }, maxAgentCalls: { ...integer(1, 10000), default: 30 },
+  maxDurationMs: { ...milliseconds, default: 120000 }, allowlist: { ...array({ enum: intentActionNames }, 0, intentActionNames.length), uniqueItems: true, default: ['tap'] } });
+const captureRequirements = object({ streams: { ...array({ enum: ['logs', 'network', 'state', 'events'] }, 1, 4), uniqueItems: true },
+  view: { enum: ['decision-window', 'connected-history'], default: 'decision-window' }, sinceMs: integer(0), limit: pageLimit,
+  timeoutMs: milliseconds, runtimeEpoch: text,
+  afterActionId: { anyOf: [text, { type: 'null' }], description: 'Omitted selects the current action. Explicit null retains all records in the observed window without claiming causal attribution.' },
+  factCursor: text }, ['streams']);
+
+function scriptSpecSchema(permissionNames) {
+  return { ...object({ schemaVersion: { const: 'aab.code-script/v1' }, name: { ...text, default: 'script' },
+    language: { enum: ['javascript', 'python'] }, source: text, sourcePath: text, cwd: text,
+    entrypoint: { ...text, default: 'main' }, target: scriptTarget, inputs: { ...jsonObject, default: {} },
+    permissions: { ...array({ enum: permissionNames }, 0, permissionNames.length), uniqueItems: true,
+      default: ['app.read', 'app.interact', 'capture.read'] },
+    policy: object({ timeoutMs: { ...milliseconds, default: 600000 },
+      restartPolicy: { enum: ['none', 'checkpoint'], default: 'none' },
+      maxOutputBytes: { ...integer(1, 64 * 1024 * 1024), default: 1048576 }, maxProgressBytes: { ...integer(1, 64 * 1024 * 1024), default: 1048576 } }),
+  }, ['schemaVersion', 'language']), oneOf: [{ required: ['source'] }, { required: ['sourcePath'] }] };
+}
+
+function executionCommandSchema(command, permissionNames) {
+  const read = { afterSequence, limit: pageLimit };
+  const scriptRead = { ...read, 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', [
+    { ...operation('start', { script: scriptSpecSchema(permissionNames), operationId: text, recordingDir: text, pythonPath: text }, ['script']),
+      allOf: [
+        { if: { required: ['pythonPath'] }, then: { properties: { script: { properties: { language: { const: 'python' } } } } } },
+        { 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 } }),
+    ...['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', {}),
+  ]);
+  if (command === 'intent') {
+    const start = { goal: text, target: intentTarget, provider: { ...provider, default: 'native' }, observationTarget: observationTargetSchema, operationId: text,
+      timeoutMs: { ...milliseconds, default: 300000, description: 'Total lifetime including observations, decision waits, paused time and actions; terminal persistence drains afterwards.' },
+      require: captureRequirements, recordingDir: text };
+    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,
+        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)),
+      operation('intervene', { operationId: text, reason: text }, ['operationId', 'reason']),
+    ]);
+  }
+  if (command === 'evidence') return variants('operation', [
+    operation('export', { namespace: { enum: ['intent', 'script'] }, 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}`);
+}
+
+module.exports = { variants, exactlyOne, jsonObject, flutterSelector, nativeSelector, scriptSpecSchema, intentDecisionSchema, intentActionSchema, nativeGestureSchema,
+  intentBudget, captureRequirements, executionCommandSchema };

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

@@ -0,0 +1,106 @@
+'use strict';
+
+const { execFile } = require('node:child_process');
+const http = require('node:http');
+const https = require('node:https');
+const { CommandError } = require('../command-errors');
+const { requestDirectory } = require('./request-context');
+const { runExecution, currentExecution, checkExecution, executionFailure, markExecutionDispatched } = require('./execution-scope');
+
+function ioFailure(code, message, scope) {
+  return new CommandError(code, message, { dispatched: scope?.dispatched === true, ambiguous: scope?.dispatched === true });
+}
+
+// Cancellation requests termination but resolves only after the subprocess has
+// closed. Releasing a device lease on a Promise.race would leave a live writer.
+function execFileBounded(file, args, { timeoutMs = 15000, mutation = false, execFileImpl = execFile, ...options } = {}) {
+  if (!currentExecution()) return runExecution({ mutation }, () => execFileBounded(file, args, { ...options, timeoutMs, mutation, execFileImpl }));
+  checkExecution();
+  const scope = currentExecution();
+  return new Promise((resolve, reject) => {
+    let stopped;
+    let killTimer;
+    let timer;
+    let completed = false;
+    const abort = () => stop(executionFailure(scope));
+    const child = execFileImpl(file, args, { cwd: requestDirectory(), ...options, timeout: 0, killSignal: 'SIGKILL' }, (error, stdout, stderr) => {
+      completed = true;
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      scope?.signal.removeEventListener('abort', abort);
+      if (stopped) error = stopped;
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        error.dispatched ??= scope?.dispatched === true;
+        error.ambiguous ??= error.dispatched;
+        reject(error);
+      } else resolve({ stdout, stderr });
+    });
+    if (completed) return;
+    if (mutation && child.pid) markExecutionDispatched();
+    const stop = error => {
+      if (stopped) return;
+      stopped = error;
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 250);
+    };
+    timer = setTimeout(() => stop(ioFailure('provider_timeout', `Subprocess timed out after ${timeoutMs} ms.`, scope)), timeoutMs);
+    scope?.signal.addEventListener('abort', abort, { once: true });
+    if (scope?.signal.aborted) abort();
+  });
+}
+
+function httpRequestBounded(url, { method = 'GET', payload, headers = {}, timeoutMs = 10000, maxBytes = 64 * 1024 * 1024 } = {}) {
+  if (!currentExecution()) return runExecution({ mutation: method !== 'GET' }, () => httpRequestBounded(url, { method, payload, headers, timeoutMs, maxBytes }));
+  checkExecution();
+  const scope = currentExecution();
+  const body = payload === undefined ? undefined : JSON.stringify(payload);
+  const protocol = new URL(url).protocol;
+  if (!['http:', 'https:'].includes(protocol)) throw ioFailure('invalid_argument', 'HTTP transport requires an http or https URL.', scope);
+  checkExecution();
+  return new Promise((resolve, reject) => {
+    let failure;
+    let data = '';
+    let bytes = 0;
+    let ended = false;
+    const request = (protocol === 'https:' ? https : http).request(url, {
+      method,
+      headers: { ...headers, ...(body === undefined ? {} : { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(body) }) },
+    }, response => {
+      response.setEncoding('utf8');
+      response.on('data', chunk => {
+        bytes += Buffer.byteLength(chunk);
+        if (bytes > maxBytes) stop(ioFailure('provider_response_too_large', `HTTP response exceeds ${maxBytes} bytes.`, scope));
+        else data += chunk;
+      });
+      response.on('error', error => stop(error));
+      response.on('end', () => {
+        ended = true;
+        if (response.statusCode < 200 || response.statusCode >= 300) failure = Object.assign(new Error(`HTTP ${response.statusCode}: ${data}`),
+          { statusCode: response.statusCode, responseBody: data });
+      });
+    });
+    const stop = error => { failure ||= error; request.destroy(); };
+    const abort = () => stop(executionFailure(scope));
+    const timer = setTimeout(() => stop(ioFailure('provider_timeout', `HTTP request timed out after ${timeoutMs} ms.`, scope)), timeoutMs);
+    scope?.signal.addEventListener('abort', abort, { once: true });
+    request.on('error', error => { failure ||= error; });
+    request.on('close', () => {
+      clearTimeout(timer);
+      scope?.signal.removeEventListener('abort', abort);
+      if (!ended) failure ||= ioFailure('provider_disconnected', 'HTTP response closed before completion.', scope);
+      if (failure) {
+        failure.url = url;
+        failure.dispatched ??= scope?.dispatched === true;
+        failure.ambiguous ??= failure.dispatched;
+        reject(failure);
+      } else resolve(data);
+    });
+    try { checkExecution(); } catch (error) { stop(error); return; }
+    if (method !== 'GET' && scope?.mutation) markExecutionDispatched();
+    request.end(body);
+  });
+}
+
+module.exports = { execFileBounded, httpRequestBounded };

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

@@ -0,0 +1,125 @@
+'use strict';
+
+function createExecutionLedger({ maxEvents = 256, maxExecutions = 256 } = {}) {
+  const executions = new Map();
+  const tombstones = new Map();
+
+  function evictOldest() {
+    const oldest = executions.keys().next().value;
+    if (oldest === undefined) return;
+    const bucket = executions.get(oldest);
+    tombstones.set(oldest, {
+      lastSequence: bucket.sequence,
+      lastFact: bucket.events[bucket.events.length - 1] || null,
+      gap: true,
+    });
+    executions.delete(oldest);
+    while (tombstones.size > maxExecutions) {
+      tombstones.delete(tombstones.keys().next().value);
+    }
+  }
+
+  function record(fact) {
+    if (!fact || typeof fact.executionId !== 'string' || fact.executionId.length === 0) {
+      throw new TypeError('executionId');
+    }
+    let bucket = executions.get(fact.executionId);
+    if (!bucket) {
+      const prior = tombstones.get(fact.executionId);
+      while (executions.size >= maxExecutions) {
+        evictOldest();
+      }
+      tombstones.delete(fact.executionId);
+      bucket = {
+        sequence: prior ? prior.lastSequence : 0,
+        events: [],
+        latestByKind: new Map(),
+        gap: prior ? true : false,
+      };
+      executions.set(fact.executionId, bucket);
+    }
+    bucket.sequence = Number.isInteger(fact.sequence) ? fact.sequence : bucket.sequence + 1;
+    const stored = {
+      schemaVersion: 'aab.execution-fact/v1',
+      executionId: fact.executionId,
+      sequence: bucket.sequence,
+      revision: fact.revision,
+      kind: fact.kind,
+      target: fact.target,
+      timestampMs: fact.timestampMs,
+      actionId: fact.actionId,
+      parentFactId: fact.parentFactId,
+      payloadSummary: fact.payloadSummary,
+      evidenceRefs: fact.evidenceRefs,
+      timings: fact.timings,
+    };
+    bucket.events.push(stored);
+    while (bucket.events.length > maxEvents) {
+      bucket.events.shift();
+      bucket.gap = true;
+    }
+    bucket.latestByKind.set(fact.kind, stored);
+    return {
+      ok: true,
+      executionId: fact.executionId,
+      sequence: bucket.sequence,
+      kind: fact.kind,
+    };
+  }
+
+  function snapshot(executionId) {
+    const bucket = executions.get(executionId);
+    if (bucket) {
+      return {
+        executionId,
+        lastSequence: bucket.sequence,
+        lastFact: bucket.events[bucket.events.length - 1],
+        gap: bucket.gap === true,
+      };
+    }
+    const tomb = tombstones.get(executionId);
+    if (tomb) {
+      return {
+        executionId,
+        lastSequence: tomb.lastSequence,
+        lastFact: tomb.lastFact,
+        gap: true,
+      };
+    }
+    return { executionId, lastSequence: 0, lastFact: null };
+  }
+
+  function query(executionId, afterSequence, limit) {
+    const bucket = executions.get(executionId);
+    if (!bucket) {
+      const tomb = tombstones.get(executionId);
+      if (tomb) {
+        return { items: [], lastSequence: tomb.lastSequence, hasMore: false, gap: true };
+      }
+      return { items: [], lastSequence: 0, hasMore: false, gap: false };
+    }
+    const items = bucket.events.filter((event) => event.sequence > afterSequence);
+    const limited = items.length > limit ? items.slice(0, limit) : items;
+    return {
+      items: limited,
+      lastSequence: limited.length > 0
+        ? limited[limited.length - 1].sequence
+        : (items.length > 0 ? afterSequence : bucket.sequence),
+      hasMore: items.length > limited.length,
+      gap: bucket.gap === true,
+    };
+  }
+
+  function latest(executionId, kind) {
+    const bucket = executions.get(executionId);
+    if (!bucket) {
+      return null;
+    }
+    const found = bucket.latestByKind.get(kind);
+    return found === undefined ? null : found;
+  }
+
+  return { record, snapshot, query, latest };
+}
+
+module.exports = { createExecutionLedger };

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

@@ -0,0 +1,87 @@
+'use strict';
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+const { CommandError } = require('../command-errors');
+
+const context = new AsyncLocalStorage();
+
+// One budget covers queueing, observation, dispatch and provider I/O. Nested
+// calls may shorten it, never restart or extend it. Signals stay inside Host.
+async function runExecution({ timeoutMs, deadlineMs = Infinity, signal, mutation } = {}, action) {
+  if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)) {
+    throw new CommandError('invalid_argument', 'timeoutMs must be a positive integer in milliseconds.', { field: 'timeoutMs' });
+  }
+  const parent = context.getStore();
+  if (parent?.closed) throw new CommandError('runtime_stopped', 'The owning execution has already settled.');
+  const controller = new AbortController();
+  const scope = {
+    parent, controller, signal: controller.signal, closed: false, dispatched: false,
+    mutation: mutation ?? parent?.mutation ?? false,
+    deadlineMs: Math.min(parent?.deadlineMs ?? Infinity, deadlineMs, timeoutMs === undefined ? Infinity : Date.now() + timeoutMs),
+  };
+  const subscriptions = [];
+  for (const upstream of new Set([parent?.signal, signal].filter(Boolean))) {
+    const abort = () => controller.abort(upstream.reason);
+    if (upstream.aborted) abort();
+    else {
+      upstream.addEventListener('abort', abort, { once: true });
+      subscriptions.push(() => upstream.removeEventListener('abort', abort));
+    }
+  }
+  const remaining = scope.deadlineMs - Date.now();
+  let timer;
+  if (remaining <= 0) controller.abort({ code: 'deadline_exceeded' });
+  else if (Number.isFinite(remaining)) timer = setTimeout(() => controller.abort({ code: 'deadline_exceeded' }), remaining);
+  try {
+    return await context.run(scope, () => { checkExecution(); return action(); });
+  } finally {
+    scope.closed = true;
+    clearTimeout(timer);
+    for (const unsubscribe of subscriptions) unsubscribe();
+  }
+}
+
+function currentExecution() { return context.getStore(); }
+
+// Long-lived collectors own their own lifecycle; starting one from a command
+// must not attach all of its later observations to that command's deadline.
+function withoutExecution(action) { return context.exit(action); }
+
+function executionFailure(scope = currentExecution()) {
+  const code = scope?.signal.reason?.code || 'runtime_stopped';
+  return new CommandError(code, code === 'deadline_exceeded'
+    ? 'The execution deadline expired.' : 'The execution was stopped.', {
+    dispatched: scope?.dispatched === true,
+    ambiguous: scope?.dispatched === true,
+  });
+}
+
+function checkExecution() {
+  const scope = currentExecution();
+  if (!scope) return;
+  // A busy event loop may not have delivered the timer yet.
+  if (Date.now() >= scope.deadlineMs) scope.controller.abort({ code: 'deadline_exceeded' });
+  if (scope.closed || scope.signal.aborted) throw executionFailure(scope);
+}
+
+function markExecutionDispatched() {
+  for (let scope = currentExecution(); scope; scope = scope.parent) scope.dispatched = true;
+}
+
+async function executionSleep(ms) {
+  checkExecution();
+  const scope = currentExecution();
+  await new Promise((resolve, reject) => {
+    const finish = (error) => {
+      clearTimeout(timer);
+      scope?.signal.removeEventListener('abort', abort);
+      error ? reject(error) : resolve();
+    };
+    const abort = () => finish(executionFailure(scope));
+    const timer = setTimeout(() => finish(), ms);
+    scope?.signal.addEventListener('abort', abort, { once: true });
+  });
+  checkExecution();
+}
+
+module.exports = { runExecution, currentExecution, withoutExecution, checkExecution, markExecutionDispatched, executionFailure, executionSleep };

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

@@ -0,0 +1,115 @@
+'use strict';
+
+const { object, integer, text, validateValue } = require('./argument-schema');
+const { CommandError } = require('../command-errors');
+const { checksumOf } = require('./evidence-schema');
+const { resolveExecutablePaths } = require('./request-context');
+
+const definitions = Object.freeze({
+  android: { identity: ['serial', 'packageName'], connection: ['adb', 'port'] },
+  ios: { identity: ['deviceId', 'bundleId'], connection: ['runtimeUrl', 'iosHost', 'iosPort', 'wdaUrl', 'wdaRunnerBundleId', 'wdaSessionId', 'webViewId', 'devicectl', 'xcodebuild'] },
+  web: { identity: ['sessionId', 'runtimeEpoch'], connection: ['targetId'] },
+});
+const identityText = { ...text, maxLength: 1024, pattern: '^\\S+$' };
+const identifier = { ...text, maxLength: 255, pattern: '^[A-Za-z][A-Za-z0-9_]*(?:\\.[A-Za-z0-9_]+)*$' };
+const allFields = new Set(Object.values(definitions).flatMap(value => [...value.identity, ...value.connection]));
+
+function executionTargetSchema({ intent = false, nullable = false } = {}) {
+  const branches = Object.entries(definitions).map(([platform, definition]) => {
+    const properties = { platform: { const: platform } };
+    for (const key of definition.identity) properties[key] = identityText;
+    for (const key of definition.connection) properties[key] = text;
+    if (platform === 'android') {
+      properties.packageName = identifier;
+      properties.port = integer(1, 65535);
+      if (intent) properties.foregroundPackages = { type: 'array', items: identifier, maxItems: 32, uniqueItems: true };
+    }
+    if (platform === 'ios') properties.iosPort = integer(1, 65535);
+    return object(properties, ['platform', ...definition.identity]);
+  });
+  return { anyOf: nullable ? [...branches, { type: 'null' }] : branches,
+    description: 'Explicit platform and target identity. Connection options belong only to that platform.' };
+}
+
+function normalizeExecutionTarget(value, { intent = false, nullable = false } = {}) {
+  validateValue(value, executionTargetSchema({ intent, nullable }), 'target');
+  if (value === null) return null;
+  if (value.platform === 'ios') {
+    if (value.runtimeUrl !== undefined && (value.iosHost !== undefined || value.iosPort !== undefined)) {
+      throw new CommandError('target_connection_conflict', 'runtimeUrl and iosHost/iosPort describe alternative runtime connections.', { field: 'target.runtimeUrl' });
+    }
+    for (const key of ['runtimeUrl', 'wdaUrl']) {
+      if (value[key] === undefined) continue;
+      let url;
+      try { url = new URL(value[key]); } catch { /* rejected below */ }
+      if (!url || !['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash || url.search) {
+        throw new CommandError('invalid_target_url', `${key} must be an HTTP(S) base URL without credentials, a query or fragment.`, { field: `target.${key}` });
+      }
+    }
+  }
+  const target = resolveExecutablePaths(structuredClone(value));
+  if (target.foregroundPackages) Object.freeze(target.foregroundPackages);
+  return Object.freeze(target);
+}
+
+function targetIdentity(target) {
+  if (!target) return null;
+  const definition = definitions[target.platform];
+  if (!definition) throw new CommandError('invalid_target_platform', 'Target has no supported platform discriminator.', { field: 'target.platform' });
+  // Web DOM targets share an SDK session but have distinct observation identity.
+  const fields = target.platform === 'web' ? ['sessionId', 'runtimeEpoch', 'targetId'] : definition.identity;
+  return `${target.platform}:${JSON.stringify(fields.map(key => target[key] ?? null))}`;
+}
+
+function targetFingerprint(target) {
+  return target === null ? null : checksumOf(target);
+}
+
+function commandPlatform(command) {
+  return command.startsWith('ios-') ? 'ios' : command.startsWith('web-') ? 'web' : 'android';
+}
+
+// A Script target supplies explicit defaults. A complete per-call identity can
+// 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) {
+  const platform = commandPlatform(command);
+  const definition = definitions[platform];
+  const selected = explicitTarget === undefined ? defaultTarget : normalizeExecutionTarget(explicitTarget);
+  const fullIdentity = definition.identity.every(key => args[key] !== undefined);
+  if (selected && selected.platform !== platform && !fullIdentity) {
+    throw new CommandError('target_platform_mismatch', `${command} requires a complete ${platform} target.`, { field: 'target.platform' });
+  }
+  if (explicitTarget !== undefined && selected.platform !== platform) {
+    throw new CommandError('target_platform_mismatch', `${command} does not execute on ${selected.platform}.`, { field: 'options.target.platform' });
+  }
+  const target = { ...(selected?.platform === platform ? selected : {}), platform };
+  delete target.foregroundPackages;
+  const schema = require('../command-registry').commandSchema(command);
+  for (const key of allFields) {
+    if (args[key] === undefined) continue;
+    if (!definition.identity.includes(key) && !definition.connection.includes(key)) {
+      // For example, Android CDP's targetId selects a WebView page. It is a
+      // command argument, not the identity of a desktop Web execution target.
+      if (schema.properties?.[key] !== undefined) continue;
+      throw new CommandError('target_platform_mismatch', `${key} does not belong to a ${platform} target.`, { field: key });
+    }
+    if (explicitTarget !== undefined && target[key] !== undefined && target[key] !== args[key]) {
+      throw new CommandError('target_argument_conflict', `Argument ${key} conflicts with options.target.`, { field: key });
+    }
+    target[key] = args[key];
+  }
+  const normalized = normalizeExecutionTarget(target);
+  const bound = { ...args };
+  const operationBranches = [...(schema.oneOf || []), ...(schema.anyOf || [])]
+    .filter(branch => branch.properties?.operation?.const === args.operation && args.operation !== undefined);
+  // Transport options may describe both SDK HTTP and WDA on the same iPhone;
+  // each command receives only fields its public contract accepts.
+  for (const [key, value] of Object.entries(normalized)) {
+    if (key !== 'platform' && schema.properties?.[key] !== undefined
+        && !operationBranches.some(branch => branch.properties?.[key] === false)) bound[key] = value;
+  }
+  return { target: normalized, args: bound };
+}
+
+module.exports = { executionTargetSchema, normalizeExecutionTarget, targetIdentity, targetFingerprint, commandPlatform, bindCommandTarget };

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

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