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

package/bin/script/script-host-port.js

@@ -0,0 +1,397 @@
+'use strict';
+
+const { createLiveCaptureQuery } = require('../shared-kernel/live-capture-query');
+const { summarizeTree } = require('../shared-kernel/summary-transformer');
+const { createDeviceMutationLease } = require('../shared-kernel/device-mutation-lease');
+const { admitExecutionMutation } = require('../shared-kernel/execution-admission');
+const { authorizeCommand } = require('./script-catalog');
+const { isMutationCommand } = require('../command-registry');
+const { normalizeExecutionTarget, bindCommandTarget, targetFingerprint } = require('../shared-kernel/execution-target');
+const { createScriptCapturePort, isCaptureReadCommand } = require('./script-capture-port');
+const { judgeAssertion, issueObservation, createObservationRegistry } = require('./script-assert');
+
+function createScriptHostPort({
+  runner,
+  actions,
+  query,
+  mutationLease = createDeviceMutationLease(),
+  target = null,
+  permissions,
+  executionId,
+} = {}) {
+  if (typeof actions !== 'function') {
+    throw new TypeError('actions');
+  }
+  const defaultTarget = normalizeExecutionTarget(target, { nullable: true });
+  const liveQuery = query || (typeof runner === 'function' ? createLiveCaptureQuery({ runner }) : null);
+  const capture = liveQuery ? createScriptCapturePort({ query: liveQuery }) : null;
+  const observations = createObservationRegistry();
+  const watermarks = createObservationRegistry();
+  let preActionWatermarks = new Map();
+  let mutationTarget = null;
+  let afterActionId = null;
+  let mutationRevision = 0;
+  let pendingMutations = 0;
+  let calls = 0;
+  let assertions = 0;
+  let actionCalls = 0;
+
+  async function call(command, args = {}, options = {}) {
+    calls += 1;
+    const callId = `call-${calls}`;
+    const gate = authorizeCommand(command, permissions);
+    if (!gate.ok) {
+      return unavailableEnvelope({ command, error: gate.error, executionId, callId });
+    }
+    if ((command === 'logcat' && args.clear === true) || (['webview-network', 'webview-console'].includes(command) && args.script !== undefined)) {
+      return unavailableEnvelope({ command, error: 'capture_mutation_not_allowed', executionId, callId });
+    }
+    if (command === 'page-summary') {
+      return pageSummaryResult(args, { executionId, callId });
+    }
+    let binding;
+    try { binding = bindCommandTarget(command, args, defaultTarget, options.target); }
+    catch (error) {
+      return { ...unavailableEnvelope({ command, error: error.code || 'invalid_target', executionId, callId }),
+        field: error.field, message: error.message, dispatched: false, ambiguous: false };
+    }
+    args = binding.args;
+    const boundTarget = binding.target;
+    const stamp = result => { result.execution.target = structuredClone(boundTarget); return result; };
+    const observed = { afterActionId, mutationRevision, pendingMutation: pendingMutations > 0 };
+    if (isCaptureReadCommand(command)) {
+      const result = await captureResult(command, args, options, { executionId, callId, capture, target: boundTarget });
+      const queryTarget = targetFingerprint(boundTarget);
+      const boundaryKey = `${command}:${queryTarget}`;
+      const metadata = result.evidence.capture;
+      const window = result.evidence.window;
+      const preAction = preActionWatermarks.get(boundaryKey);
+      const matchesQuery = window.filterApplied === true
+        && window.afterActionId === afterActionIdOf(args, options)
+        && (window.factCursor ?? null) === (args.factCursor ?? null)
+        && (window.sinceId ?? null) === (args.sinceId ?? null)
+        && (window.sinceMs ?? null) === (args.sinceMs ?? null)
+        && typeof metadata.runtimeEpoch === 'string' && metadata.runtimeEpoch.length > 0
+        && window.runtimeEpoch === metadata.runtimeEpoch
+        && typeof metadata.targetKey === 'string' && metadata.targetKey.length > 0
+        && window.targetKey === metadata.targetKey
+        && ((boundTarget.packageName ?? boundTarget.bundleId) == null || (boundTarget.packageName ?? boundTarget.bundleId) === metadata.targetKey)
+        && ((options.runtimeEpoch ?? args.runtimeEpoch) == null || (options.runtimeEpoch ?? args.runtimeEpoch) === metadata.runtimeEpoch)
+        && result.evidence.refs.every((ref) => ref.runtimeEpoch === metadata.runtimeEpoch && ref.targetKey === metadata.targetKey);
+      // A continuation page alone cannot prove a whole decision window.
+      observed.captureValid = Boolean(matchesQuery && metadata.hasMore === false && args.cursor === undefined
+        && (afterActionIdOf(args, options) === null || afterActionIdOf(args, options) === observed.afterActionId)
+        && (observed.mutationRevision === 0 || (
+        queryTarget === mutationTarget && preAction
+        && args.factCursor === preAction.cursor
+        && metadata.runtimeEpoch === preAction.runtimeEpoch
+        && metadata.targetKey === preAction.targetKey
+      )));
+      const coverage = result.evidence.coverage;
+      if (matchesQuery && coverage.status === 'complete' && coverage.gap === false && coverage.committed === true
+        && typeof metadata.watermarkCursor === 'string' && metadata.watermarkCursor.length > 0
+        && !observed.pendingMutation && observed.mutationRevision === mutationRevision) {
+        watermarks.set(boundaryKey, {
+          cursor: metadata.watermarkCursor,
+          runtimeEpoch: metadata.runtimeEpoch,
+          targetKey: metadata.targetKey,
+          mutationRevision,
+        });
+      }
+      issueObservation(observations, result.evidence, observed, { command, payload: result.result });
+      return stamp(result);
+    }
+    if (isMutationCommand(command, args)) {
+      return stamp(await mutationResult(command, args, options, {
+        actions,
+        mutationLease,
+        target: boundTarget,
+        executionId,
+        callId,
+        onAction: (id) => {
+          actionCalls += 1;
+          afterActionId = id;
+          mutationTarget = targetFingerprint(boundTarget);
+          preActionWatermarks = new Map(watermarks.entries().filter(([, item]) => item.mutationRevision === mutationRevision));
+          mutationRevision += 1;
+          pendingMutations += 1;
+        },
+        onSettled: () => { pendingMutations -= 1; },
+      }));
+    }
+    const result = await actionOnce(command, args, options, {
+      actions,
+      target: boundTarget,
+      executionId,
+      callId,
+      actionId: null,
+      onAction: () => { actionCalls += 1; },
+    });
+    result.evidence.window.afterActionId = observed.afterActionId;
+    issueObservation(observations, result.evidence, observed, {
+      command,
+      payload: result.result,
+      tree: result.ok && ['tree', 'uia-tree', 'flutter-tree', 'flutter-nodes', 'h5-dom', 'flutter-h5-dom', 'ios-tree', 'ios-uia-tree', 'ios-flutter-tree', 'ios-flutter-nodes', 'ios-h5-dom', 'web-dom'].includes(command),
+    });
+    return stamp(result);
+  }
+
+  async function assert(assertion = {}) {
+    assertions += 1;
+    return judgeAssertion(assertion, observations, { afterActionId, mutationRevision, pendingMutation: pendingMutations > 0 });
+  }
+
+  return {
+    call,
+    assert,
+    get callCount() { return calls; },
+    get assertionCount() { return assertions; },
+    get actionCallCount() { return actionCalls; },
+  };
+}
+
+function pageSummaryResult(args, ids) {
+  const summary = summarizeTree({
+    provider: args.provider,
+    rawTree: args.rawTree,
+    rawTreeId: args.rawTreeId,
+    screenshotId: args.screenshotId,
+  });
+  return envelope({
+    ok: summary.ok !== false,
+    command: 'page-summary',
+    result: summary,
+    error: summary.error || null,
+    executionId: ids.executionId,
+    callId: ids.callId,
+    actionId: null,
+    coverage: { status: 'complete', gap: false, committed: true },
+    refs: Array.isArray(args.refs) ? args.refs : [],
+    timings: {},
+  });
+}
+
+async function captureResult(command, args, options, { executionId, callId, capture, target }) {
+  if (!capture) {
+    const result = envelope({
+      ok: false,
+      error: 'capture_unavailable',
+      command,
+      result: { items: [] },
+      executionId,
+      callId,
+      actionId: null,
+      coverage: { status: 'unavailable', gap: true, committed: false },
+      refs: [],
+      afterActionId: afterActionIdOf(args, options),
+      timings: {},
+    });
+    result.evidence.capture = {};
+    return result;
+  }
+  const afterActionId = afterActionIdOf(args, options);
+  const window = await capture.query(command, dispatchArgs(args), {
+    actionId: afterActionId,
+    timeoutMs: timeoutMsOf(options),
+    evidenceWindow: options.evidenceWindow,
+    runtimeEpoch: options.runtimeEpoch,
+    runtimeEpochChanged: options.runtimeEpochChanged,
+    disconnected: options.disconnected,
+  });
+  const result = envelope({
+    ok: window.ok !== false && !window.error && window.coverage.status !== 'unavailable',
+    error: window.error || window.reason || null,
+    command,
+    result: { items: window.items },
+    executionId,
+    callId,
+    actionId: null,
+    coverage: window.coverage,
+    refs: window.refs,
+    afterActionId,
+    timings: {},
+  });
+  result.evidence.window = window.window ? structuredClone(window.window) : { afterActionId: null };
+  result.evidence.capture = {
+    storeGeneration: window.storeGeneration ?? null,
+    throughWatermark: window.throughWatermark ?? null,
+    runtimeEpoch: window.runtimeEpoch ?? null,
+    targetKey: window.targetKey ?? null,
+    watermarkCursor: window.watermarkCursor ?? null,
+    nextCursor: window.nextCursor ?? null,
+    hasMore: window.hasMore ?? null,
+    ...(window.barrier === undefined ? {} : { barrier: structuredClone(window.barrier) }),
+  };
+  return result;
+}
+
+async function mutationResult(command, args, options, ctx) {
+  const actionId = options.dispatchActionId || mutationActionId(ctx.executionId, ctx.callId);
+  const bound = dispatchArgs(args, actionId);
+  try {
+    return await admitExecutionMutation(ctx.target, ctx.mutationLease, async () => {
+      try { return await actionOnce(command, bound, options, {
+      actions: ctx.actions,
+      target: ctx.target,
+      executionId: ctx.executionId,
+      callId: ctx.callId,
+      actionId,
+      onAction: ctx.onAction,
+      }); } finally { ctx.onSettled(); }
+    });
+  } catch (error) {
+    return unavailableEnvelope({ command, error: error.code || error.message, executionId: ctx.executionId, callId: ctx.callId });
+  }
+}
+
+async function actionOnce(command, args, options, { actions, target, executionId, callId, actionId, onAction }) {
+  onAction(actionId);
+  let raw;
+  try {
+    raw = await actions(command, dispatchArgs(args, actionId), options);
+  } catch (error) {
+    return envelope({
+      ok: false,
+      command,
+      result: null,
+      error: error?.code || error?.message || String(error),
+      dispatched: error?.dispatched,
+      ambiguous: error?.ambiguous ?? actionId !== null,
+      executionId,
+      callId,
+      actionId,
+      coverage: { status: 'unavailable', gap: true, committed: false },
+      refs: [],
+      timings: {},
+    });
+  }
+  if (raw && raw.ambiguous === true) {
+    return envelope({
+      ok: false,
+      command,
+      result: raw,
+      error: raw.error || 'ambiguous',
+      ambiguous: true,
+      dispatched: raw.dispatched,
+      executionReceipt: raw.executionReceipt ?? null,
+      executionReceipts: raw.executionReceipts,
+      executionId,
+      callId,
+      actionId,
+      coverage: { status: 'unavailable', gap: true, committed: false },
+      refs: actionRefs(command, raw),
+      timings: raw.timings || {},
+    });
+  }
+  return envelope({
+    ok: raw != null && raw.ok !== false && !raw.error,
+    command,
+    result: raw && raw.result !== undefined ? raw.result : raw,
+    error: raw && raw.error ? raw.error : null,
+    dispatched: raw?.dispatched,
+    executionReceipt: raw?.executionReceipt ?? null,
+    executionReceipts: raw?.executionReceipts,
+    executionId,
+    callId,
+    actionId,
+    coverage: raw == null || raw.ok === false || raw.error
+      ? { status: 'unavailable', gap: true, committed: false }
+      : { status: 'complete', gap: false, committed: true },
+    refs: actionRefs(command, raw),
+    timings: raw?.timings || {},
+  });
+}
+
+function actionRefs(command, raw) {
+  if (raw?.ok === false) return [];
+  if (Array.isArray(raw?.refs)) return raw.refs;
+  const screenshotPath = command === 'ios-screenshot' ? raw?.outFile : raw?.path;
+  if (
+    (command === 'screenshot' || command === 'ios-screenshot')
+    && typeof screenshotPath === 'string'
+    && screenshotPath.length > 0
+  ) {
+    return [{ stream: 'screenshot', screenshotId: screenshotPath,
+      ...(/^[a-f0-9]{64}$/.test(raw.artifact?.sha256 || '') ? { sha256: raw.artifact.sha256 } : {}) }];
+  }
+  return [];
+}
+
+function envelope({
+  ok,
+  command,
+  result,
+  error,
+  ambiguous,
+  executionId,
+  callId,
+  actionId,
+  dispatched = actionId !== null,
+  executionReceipt = null,
+  executionReceipts,
+  coverage,
+  refs,
+  afterActionId,
+  timings,
+}) {
+  return {
+    ok,
+    command,
+    result,
+    error: error || null,
+    ambiguous: ambiguous === true,
+    dispatched,
+    executionReceipt,
+    ...(executionReceipts === undefined ? {} : { executionReceipts }),
+    execution: { executionId, callId, actionId },
+    evidence: {
+      window: { afterActionId: afterActionId === undefined ? actionId : afterActionId, closedAtMs: 0 },
+      coverage,
+      refs,
+    },
+    timings,
+  };
+}
+
+function unavailableEnvelope({ command, error, executionId, callId }) {
+  return envelope({
+    ok: false,
+    command,
+    result: null,
+    error,
+    executionId,
+    callId,
+    actionId: null,
+    coverage: { status: 'unavailable', gap: true, committed: false },
+    refs: [],
+    timings: {},
+  });
+}
+
+function mutationActionId(executionId, callId) {
+  const suffix = `action-${callId.slice('call-'.length)}`;
+  if (executionId == null || executionId === '') return suffix;
+  return `${executionId}:${suffix}`;
+}
+
+function dispatchArgs(args, actionId) {
+  return { ...args, ...(actionId == null ? {} : { requestId: actionId }) };
+}
+
+function afterActionIdOf(args, options) {
+  if (options.evidenceWindow && options.evidenceWindow.afterActionId != null) {
+    return options.evidenceWindow.afterActionId;
+  }
+  if (options.actionId != null) return options.actionId;
+  if (args.afterActionId != null) return args.afterActionId;
+  return null;
+}
+
+function timeoutMsOf(options) {
+  if (options.evidenceWindow && options.evidenceWindow.timeoutMs != null) {
+    return options.evidenceWindow.timeoutMs;
+  }
+  return null;
+}
+
+module.exports = { createScriptHostPort, unavailableEnvelope };

package/bin/script/script-ledger.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const { createExecutionLedger } = require('../shared-kernel/execution-ledger');
+
+function createScriptLedger({ ledger = createExecutionLedger() } = {}) {
+  function append(record, type, extra = {}, timestampMs) {
+    if (!record || typeof record.operationId !== 'string' || record.operationId.length === 0) {
+      throw new TypeError('operationId');
+    }
+    return ledger.record({
+      executionId: record.operationId,
+      revision: extra.revision,
+      kind: type,
+      target: scriptEventTarget(record, type, extra),
+      timestampMs,
+      actionId: extra.actionId,
+      parentFactId: extra.parentFactId,
+      payloadSummary: extra.payloadSummary == null ? scriptPayload(extra) : extra.payloadSummary,
+      evidenceRefs: extra.evidenceRefs,
+      timings: extra.timings,
+      sequence: extra.sequence,
+    });
+  }
+
+  return { ledger, append };
+}
+
+// Call events carry the target already bound before dispatch. Never reconstruct
+// it from a subset of arguments or borrow the owning Script's connection.
+function scriptEventTarget(record, type, extra = {}) {
+  return ['call_started', 'call_completed', 'call_failed', 'action_receipt'].includes(type)
+    ? extra.target : record.spec?.target;
+}
+
+function scriptPayload(extra) {
+  return {
+    command: extra.command,
+    callId: extra.callId,
+    args: extra.args,
+    error: extra.error,
+    status: extra.status,
+    resultRef: extra.resultRef,
+    name: extra.name,
+    verdict: extra.verdict,
+    scope: extra.scope,
+    reason: extra.reason,
+    predicateSummary: extra.predicateSummary,
+    condition: extra.condition,
+    requiredEvidence: extra.requiredEvidence,
+    requireCoverage: extra.requireCoverage,
+    refs: extra.refs,
+    coverage: extra.coverage,
+    observationId: extra.observationId,
+    window: extra.window,
+    source: extra.source,
+    requestId: extra.requestId,
+    decision: extra.decision,
+    request: extra.request,
+    stage: extra.stage,
+    message: extra.message,
+  };
+}
+
+module.exports = { createScriptLedger, scriptEventTarget };

package/bin/script/script-result.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { canonicalJson, checksumOf } = require('../shared-kernel/evidence-schema');
+const { sanitizePersistentValue } = require('../fact-codec');
+const { scriptError } = require('./script-errors');
+
+// This is an execution output, separate from the bounded progress stream and
+// from live mobile capture queries. It follows the same write-side redaction.
+function prepareScriptResult(value, maxBytes) {
+  const original = JSON.parse(JSON.stringify(value ?? null));
+  const result = sanitizePersistentValue(original);
+  const bytes = Buffer.byteLength(canonicalJson(result));
+  if (Buffer.byteLength(canonicalJson(original)) > maxBytes || bytes > maxBytes) {
+    return { ok: false, error: 'output_too_large' };
+  }
+  const sha256 = checksumOf(result), originalSha256 = checksumOf(original);
+  return { ok: true, result, bytes, sha256, originalSha256,
+    representation: sha256 === originalSha256 ? 'original-json' : 'redacted-json' };
+}
+
+function resultReference(receipt, prepared) {
+  return { evidenceId: receipt.evidenceId, bytes: prepared.bytes, sha256: prepared.sha256,
+    originalSha256: prepared.originalSha256, representation: prepared.representation };
+}
+
+function readScriptResult({ store, operationId }) {
+  if (!store) return scriptError('result_not_persisted', { operationId });
+  try {
+    let checkpoint = store.latest(operationId, 'checkpoint');
+    if (!checkpoint) return scriptError('unknown_operation', { operationId });
+    const checked = store.read(checkpoint.evidenceId);
+    if (!checked.ok) return scriptError(checked.error, { operationId });
+    checkpoint = checked.record;
+    if (checkpoint.status !== 'completed') {
+      return scriptError(['cancelled', 'failed'].includes(checkpoint.status) ? 'result_unavailable' : 'result_not_ready',
+        { operationId, status: checkpoint.status, executionError: checkpoint.error ?? null });
+    }
+    const ref = checkpoint.resultRef;
+    if (!ref) return scriptError('result_not_persisted', { operationId });
+    const loaded = store.read(ref.evidenceId);
+    if (!loaded.ok) return scriptError(loaded.error === 'not_found' ? 'result_not_retained' : loaded.error, { operationId, resultRef: ref });
+    const body = loaded.record;
+    if (body.kind !== 'result' || body.operationId !== operationId || body.revision !== checkpoint.revision
+      || !Object.hasOwn(body, 'result') || checksumOf(body.result) !== ref.sha256
+      || Buffer.byteLength(canonicalJson(body.result)) !== ref.bytes
+      || body.sha256 !== ref.sha256 || body.bytes !== ref.bytes
+      || body.originalSha256 !== ref.originalSha256 || body.representation !== ref.representation) {
+      return scriptError('result_checksum_mismatch', { operationId, resultRef: ref });
+    }
+    return { ok: true, command: 'script', operationId, status: 'completed',
+      result: body.result, resultRef: ref, persisted: true };
+  } catch (error) {
+    return scriptError(error.code || 'result_read_failed', { operationId });
+  }
+}
+
+module.exports = { prepareScriptResult, resultReference, readScriptResult };

package/bin/script/script-sdk.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs = require('node:fs');
+const readline = require('node:readline');
+
+const artifactPath = process.argv[2];
+const replies = new Map();
+const controlWaiters = [];
+let nextId = 0;
+let control = { status: 'running', pauseReason: null };
+
+const rl = readline.createInterface({ input: process.stdin });
+
+function send(message) {
+  fs.writeSync(1, `${JSON.stringify(message)}\n`);
+}
+
+function writeStderr(args) {
+  fs.writeSync(2, `${args.map(String).join(' ')}\n`);
+}
+
+console.log = (...args) => writeStderr(args);
+console.info = (...args) => writeStderr(args);
+console.debug = (...args) => writeStderr(args);
+
+function waitReply(id) {
+  return new Promise((resolve) => {
+    if (replies.size >= 32) {
+      send({ type: 'fail', error: 'channel_backlog' });
+      process.exit(1);
+      return;
+    }
+    replies.set(id, resolve);
+  });
+}
+
+rl.on('line', (line) => {
+  if (!line) return;
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    send({ type: 'fail', error: 'malformed_frame' });
+    process.exit(1);
+    return;
+  }
+  if (message.type === 'start') {
+    applyControl(message.control);
+    run(message).catch((error) => {
+      send({ type: 'fail', error: error.message || String(error) });
+      process.exit(1);
+    });
+    return;
+  }
+  if (message.type === 'control') {
+    applyControl(message.control);
+    return;
+  }
+  if (message.id && replies.has(message.id)) {
+    applyControl(message.control);
+    const resolve = replies.get(message.id);
+    replies.delete(message.id);
+    resolve(message);
+  }
+});
+
+send({ type: 'ready' });
+
+function applyControl(next) {
+  if (!next) return;
+  control = next;
+  while (controlWaiters.length > 0) controlWaiters.shift()();
+}
+
+function isHeld(status) {
+  return status === 'pause_requested'
+    || status === 'paused_manual'
+    || status === 'paused_live'
+    || status === 'paused_ambiguous';
+}
+
+function holdIfPaused() {
+  return new Promise((resolve) => {
+    const tick = () => {
+      if (!isHeld(control.status)) {
+        resolve();
+        return;
+      }
+      controlWaiters.push(tick);
+    };
+    tick();
+  });
+}
+
+async function run(start) {
+  const loaded = require(artifactPath);
+  const entry = start.entrypoint || 'main';
+  const main = typeof loaded === 'function' && entry === 'main' ? loaded : loaded[entry];
+  if (typeof main !== 'function') {
+    send({ type: 'fail', error: 'unsupported_entrypoint' });
+    process.exit(1);
+  }
+  const ctx = {
+    inputs: start.inputs || {},
+    call: async (command, args, options) => {
+      await holdIfPaused();
+      const id = `c${nextId += 1}`;
+      send({ type: 'call', id, command, args: args || {}, options: options || {} });
+      const reply = await waitReply(id);
+      await holdIfPaused();
+      return reply.value;
+    },
+    assert: async (assertion) => {
+      await holdIfPaused();
+      const id = `a${nextId += 1}`;
+      send({ type: 'assert', id, assertion });
+      const reply = await waitReply(id);
+      await holdIfPaused();
+      return reply.value;
+    },
+    progress: async (event) => {
+      await holdIfPaused();
+      send({ type: 'progress', event });
+      await holdIfPaused();
+    },
+    checkpoint: async (name, state) => {
+      await holdIfPaused();
+      const id = `k${nextId += 1}`;
+      send({ type: 'checkpoint', id, name, state });
+      const reply = await waitReply(id);
+      await holdIfPaused();
+      return reply.value;
+    },
+    askAgent: async (request) => {
+      await holdIfPaused();
+      const id = `q${nextId += 1}`;
+      send({ type: 'ask', id, request });
+      const reply = await waitReply(id);
+      await holdIfPaused();
+      return reply.value;
+    },
+    controlPoint: () => control,
+    resume: () => {
+      const state = control || {};
+      if (!state.checkpoint) return null;
+      return state.checkpoint.state;
+    },
+  };
+  const result = await main(ctx);
+  send({ type: 'return', result });
+  process.exit(0);
+}