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

package/bin/script/progress-projector.js

@@ -0,0 +1,63 @@
+'use strict';
+
+function createProgressProjector({ maxEvents = 256 } = {}) {
+  const executions = new Map();
+
+  function accept(fact) {
+    if (!fact || typeof fact.executionId !== 'string' || fact.executionId.length === 0) {
+      throw new TypeError('executionId');
+    }
+    let record = executions.get(fact.executionId);
+    if (!record) {
+      record = { sequence: 0, events: [], business: null };
+      executions.set(fact.executionId, record);
+    }
+    record.sequence += 1;
+    const stored = {
+      schemaVersion: 'aab.execution-fact/v1',
+      executionId: fact.executionId,
+      sequence: record.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,
+    };
+    record.events.push(stored);
+    while (record.events.length > maxEvents) {
+      record.events.shift();
+    }
+    if (fact.kind === 'progress') {
+      record.business = stored;
+    }
+    return {
+      lastSequence: record.sequence,
+      lastKind: stored.kind,
+      business: record.business,
+    };
+  }
+
+  function read(executionId, afterSequence, limit) {
+    const record = executions.get(executionId);
+    if (!record) {
+      return { items: [], lastSequence: 0, hasMore: false };
+    }
+    const start = afterSequence;
+    const cap = limit;
+    const items = record.events.filter((event) => event.sequence > start);
+    const limited = items.length > cap ? items.slice(0, cap) : items;
+    return {
+      items: limited,
+      lastSequence: record.sequence,
+      hasMore: items.length > limited.length,
+    };
+  }
+
+  return { accept, read };
+}
+
+module.exports = { createProgressProjector };

package/bin/script/python-runtime-adapter.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { createChildRuntimeAdapter } = require('./node-runtime-adapter');
+
+let cached = undefined;
+let spawnFailureReprobed = false;
+
+function inspectPython(opts = {}) {
+  if (opts.resolvePython) return detectPython(opts.resolvePython, opts);
+  if (opts.pythonPath || opts.env) return detectPython(undefined, opts);
+  if (cached !== undefined) return cached;
+  cached = detectPython(undefined, opts);
+  return cached;
+}
+
+function resetPythonDetection() {
+  cached = undefined;
+  spawnFailureReprobed = false;
+}
+
+function pythonCandidates({ pythonPath, env = process.env } = {}) {
+  const seen = new Set();
+  const list = [];
+  function add(value) {
+    if (!value || seen.has(value)) return;
+    seen.add(value);
+    list.push(value);
+  }
+  add(pythonPath);
+  add(env.AI_APP_BRIDGE_PYTHON);
+  add('python3');
+  add('python');
+  return list;
+}
+
+function probePython(executable, env) {
+  const options = { encoding: 'utf8', shell: false };
+  if (env) options.env = env;
+  const probe = spawnSync(executable, ['-c', 'import sys; print("%d.%d" % sys.version_info[:2])'], options);
+  if (probe.status !== 0 || !probe.stdout) {
+    return { available: false, executable, error: 'runtime_unavailable' };
+  }
+  const parsed = parsePythonVersion(probe.stdout);
+  if (!parsed) {
+    return { available: false, executable, error: 'runtime_unavailable' };
+  }
+  if (parsed.major < 3 || (parsed.major === 3 && parsed.minor < 9)) {
+    return { available: false, executable, version: parsed.version, error: 'python_too_old' };
+  }
+  return { available: true, executable, version: parsed.version };
+}
+
+function parsePythonVersion(stdout) {
+  const version = String(stdout || '').trim();
+  const match = /^(\d+)\.(\d+)\b/.exec(version);
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]), version };
+}
+
+function detectPython(resolvePython, opts = {}) {
+  if (typeof resolvePython === 'function') {
+    const executable = resolvePython();
+    if (!executable) return { available: false, executable: null };
+    return probePython(executable, opts.env);
+  }
+  let tooOld = null;
+  for (const candidate of pythonCandidates(opts)) {
+    const result = probePython(candidate, opts.env);
+    if (result.available) return result;
+    if (result.error === 'python_too_old' && !tooOld) tooOld = result;
+  }
+  return tooOld || { available: false, executable: null };
+}
+
+function resolvePythonExecutable(opts = {}) {
+  return detectPython(undefined, opts).executable;
+}
+
+function createPythonRuntimeAdapter(opts = {}) {
+  const resolved = inspectPython(opts);
+  if (!resolved.available) {
+    return {
+      kind: 'python',
+      unavailable: true,
+      error: resolved.error || 'runtime_unavailable',
+      async start() {
+        return { ok: false, error: 'runtime_unavailable' };
+      },
+    };
+  }
+  return createChildRuntimeAdapter({
+    kind: 'python',
+    executable: resolved.executable,
+    sdkFile: 'script-sdk.py',
+    extension: '.py',
+    onSpawnFailure() {
+      if (spawnFailureReprobed) return;
+      spawnFailureReprobed = true;
+      cached = undefined;
+    },
+  });
+}
+
+module.exports = {
+  createPythonRuntimeAdapter,
+  inspectPython,
+  resetPythonDetection,
+  resolvePythonExecutable,
+  detectPython,
+};

package/bin/script/rolling-summary.js

@@ -0,0 +1,134 @@
+'use strict';
+
+function createRollingSummary({ operationId, startedAtMs }) {
+  const assertions = { passed: 0, failed: 0, inconclusive: 0 };
+  const assertionScopes = {
+    code: { passed: 0, failed: 0, inconclusive: 0 },
+    device: { passed: 0, failed: 0, inconclusive: 0 },
+  };
+  let status = 'running';
+  let stage = null;
+  let message = null;
+  let currentCall = null;
+  let completedCalls = 0;
+  let lastCheckpoint = null;
+  let lastEventAtMs = startedAtMs;
+  let lastKind = null;
+  let latestEvidenceRefs = [];
+  let agentRequest = null;
+  let pausedAtMs = null;
+  let pausedMs = 0;
+  let terminalAtMs = null;
+
+  function apply(event) {
+    if (event.kind === 'heartbeat') {
+      return snapshot(event.timestampMs);
+    }
+    lastEventAtMs = event.timestampMs;
+    lastKind = event.kind;
+    if (event.evidenceRefs !== undefined) {
+      latestEvidenceRefs = event.evidenceRefs;
+    }
+    if (event.kind === 'call_started') {
+      currentCall = event.command;
+    }
+    if (event.kind === 'call_completed' || event.kind === 'call_failed') {
+      completedCalls += 1;
+      currentCall = null;
+    }
+    if (event.kind === 'assertion_passed') {
+      assertions.passed += 1;
+    }
+    if (event.kind === 'assertion_failed') {
+      assertions.failed += 1;
+    }
+    if (event.kind === 'assertion_inconclusive') {
+      assertions.inconclusive += 1;
+    }
+    if (event.kind.startsWith('assertion_')) {
+      const verdict = event.kind.slice('assertion_'.length);
+      const scope = event.scope || 'device';
+      if (assertionScopes[scope] && Object.hasOwn(assertionScopes[scope], verdict)) assertionScopes[scope][verdict] += 1;
+    }
+    if (event.kind === 'checkpoint_committed') {
+      lastCheckpoint = event.name;
+    }
+    if (event.kind === 'progress') {
+      stage = event.stage;
+      message = event.message;
+    }
+    if (event.kind === 'agent_question_created') {
+      agentRequest = event.request;
+    }
+    if (event.kind === 'agent_decision') {
+      agentRequest = null;
+    }
+    if (event.kind === 'paused') {
+      status = 'paused';
+      pausedAtMs = event.timestampMs;
+    }
+    if (event.kind === 'resumed') {
+      status = 'running';
+      if (pausedAtMs !== null) {
+        pausedMs += event.timestampMs - pausedAtMs;
+        pausedAtMs = null;
+      }
+      agentRequest = null;
+    }
+    if (event.kind === 'script_completed') {
+      status = 'completed';
+    }
+    if (event.kind === 'script_failed') {
+      status = 'failed';
+    }
+    if (event.kind === 'script_cancelled') {
+      status = 'cancelled';
+    }
+    if (event.kind === 'script_ambiguous') {
+      status = 'ambiguous';
+    }
+    if (['script_completed', 'script_failed', 'script_cancelled', 'script_ambiguous'].includes(event.kind)
+      && terminalAtMs === null) terminalAtMs = event.timestampMs;
+    return snapshot(event.timestampMs);
+  }
+
+  function snapshot(nowMs) {
+    const endAtMs = terminalAtMs ?? nowMs;
+    const holdMs = pausedAtMs === null ? 0 : endAtMs - pausedAtMs;
+    return {
+      operationId,
+      status,
+      stage,
+      message,
+      currentCall,
+      completedCalls,
+      assertions: {
+        passed: assertions.passed,
+        failed: assertions.failed,
+        inconclusive: assertions.inconclusive,
+      },
+      assertionScopes: { code: { ...assertionScopes.code }, device: { ...assertionScopes.device } },
+      lastCheckpoint,
+      elapsedMs: endAtMs - startedAtMs,
+      activeMs: endAtMs - startedAtMs - pausedMs - holdMs,
+      decisionWaitMs: agentRequest === null ? 0 : endAtMs - lastEventAtMs,
+      latestEvidenceRefs,
+      agentRequest,
+    };
+  }
+
+  function heartbeat(nowMs, childHealth) {
+    return {
+      kind: 'heartbeat',
+      timestampMs: nowMs,
+      elapsedMs: (terminalAtMs ?? nowMs) - startedAtMs,
+      lastEventAtMs,
+      lastKind,
+      childHealth,
+    };
+  }
+
+  return { apply, snapshot, heartbeat };
+}
+
+module.exports = { createRollingSummary };

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

@@ -0,0 +1,40 @@
+'use strict';
+
+function createScriptAgentPort() {
+  const pending = [];
+
+  function askAgent(request) {
+    const queued = {
+      requestId: (request && request.requestId) || `ask-${pending.length + 1}`,
+      request,
+      answered: false,
+    };
+    pending.push(queued);
+    return new Promise((resolve) => {
+      queued.resolve = resolve;
+    });
+  }
+
+  function decide(requestId, decision) {
+    const open = pending.find((entry) => entry.requestId === requestId && entry.answered === false);
+    if (open) {
+      open.answered = true;
+      open.decision = decision;
+      if (open.resolve) open.resolve(decision);
+      return { ok: true, requestId, decision };
+    }
+    const answered = pending.find((entry) => entry.requestId === requestId && entry.answered === true);
+    if (answered) {
+      return { ok: true, requestId, decision: answered.decision };
+    }
+    return { ok: false, error: 'unknown_or_duplicate_decide', requestId };
+  }
+
+  return {
+    askAgent,
+    decide,
+    pending: () => pending.filter((item) => item.answered === false),
+  };
+}
+
+module.exports = { createScriptAgentPort };

package/bin/script/script-assert.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { randomUUID, createHash } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+
+// The registry is an execution-local verifier, never a second mobile payload store.
+function createObservationRegistry({ maxCount = 128, maxBytes = 256 * 1024 } = {}) {
+  const entries = new Map();
+  let retainedBytes = 0;
+  return {
+    set(id, record) {
+      const bytes = Buffer.byteLength(JSON.stringify(record));
+      const previous = entries.get(id);
+      if (previous) { retainedBytes -= previous.bytes; entries.delete(id); }
+      if (bytes > maxBytes) return;
+      while (entries.size >= maxCount || retainedBytes + bytes > maxBytes) {
+        const oldest = entries.keys().next().value;
+        retainedBytes -= entries.get(oldest).bytes;
+        entries.delete(oldest);
+      }
+      entries.set(id, { record, bytes });
+      retainedBytes += bytes;
+    },
+    get(id) { return entries.get(id)?.record; },
+    entries() { return [...entries].map(([id, item]) => [id, item.record]); },
+    get retainedCount() { return entries.size; },
+    get retainedBytes() { return retainedBytes; },
+  };
+}
+
+// Stored metadata belongs to the Host. The child only receives a JSON copy.
+function issueObservation(observations, evidence, { afterActionId, mutationRevision, pendingMutation, captureValid }, { command, payload, tree = false }) {
+  evidence.observationId = randomUUID();
+  evidence.window.closedAtMs = Date.now();
+  evidence.source = {
+    scope: 'execution',
+    command,
+    payloadSha256: createHash('sha256').update(JSON.stringify(payload ?? null)).digest('hex'),
+  };
+  if (tree && evidence.refs.length === 0) {
+    evidence.refs = [{ stream: 'tree', hostObservationId: evidence.observationId, ...evidence.source }];
+  }
+  observations.set(evidence.observationId, {
+    evidence: structuredClone(evidence),
+    afterActionId,
+    mutationRevision,
+    pendingMutation,
+    captureValid,
+  });
+  return evidence;
+}
+
+function judgeAssertion(assertion, observations, { afterActionId = null, mutationRevision = 0, pendingMutation = false } = {}) {
+  const scope = assertion.scope || 'device';
+  const result = (verdict, reason) => ({
+    verdict,
+    name: assertion.name || null,
+    scope,
+    ...(reason ? { reason } : {}),
+  });
+  if (scope !== 'device' && scope !== 'code') return result('inconclusive', 'assertion_scope_invalid');
+  if (typeof assertion.condition !== 'boolean') return result('inconclusive', 'assertion_condition_not_boolean');
+  if (scope === 'code') {
+    if (assertion.evidence != null || (assertion.requiredEvidence || []).length > 0) {
+      return result('inconclusive', 'code_assertion_cannot_claim_device_evidence');
+    }
+    return result(assertion.condition ? 'passed' : 'failed');
+  }
+  const evidence = assertion.evidence;
+  const issued = observations.get(evidence?.observationId);
+  if (!issued || !isDeepStrictEqual(evidence, issued.evidence)) {
+    return result('inconclusive', 'evidence_not_host_issued');
+  }
+  const coverage = issued.evidence.coverage;
+  if (coverage.status !== 'complete' || coverage.gap !== false || coverage.committed !== true) {
+    return result('inconclusive', 'evidence_coverage_incomplete');
+  }
+  if (
+    pendingMutation || issued.pendingMutation
+    || issued.mutationRevision !== mutationRevision
+    || issued.afterActionId !== afterActionId
+  ) {
+    return result('inconclusive', 'evidence_action_window_stale');
+  }
+  if (issued.captureValid === false) return result('inconclusive', 'capture_boundary_not_host_observed');
+  const refs = issued.evidence.refs;
+  if (!Array.isArray(refs) || refs.length === 0) return result('inconclusive', 'device_evidence_refs_empty');
+  const streams = new Set(refs.map((ref) => ref.stream));
+  if ((assertion.requiredEvidence || []).some((stream) => !streams.has(stream))) {
+    return result('inconclusive', 'required_evidence_missing');
+  }
+  return result(assertion.condition ? 'passed' : 'failed');
+}
+
+module.exports = { createObservationRegistry, issueObservation, judgeAssertion };

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

@@ -0,0 +1,76 @@
+'use strict';
+
+const { capturePage, unavailablePage } = require('../shared-kernel/live-capture-query');
+
+function createScriptCapturePort({ query } = {}) {
+  if (typeof query !== 'function') {
+    throw new TypeError('query');
+  }
+
+  async function queryWindow(commandName, args = {}, executionContext = {}) {
+    const stream = streamFor(commandName);
+    if (!stream) {
+      return unavailablePage('unsupported_capture_stream');
+    }
+    if (executionContext.runtimeEpochChanged === true || executionContext.disconnected === true) {
+      return unavailablePage(executionContext.disconnected ? 'target_disconnected' : 'runtime_epoch_changed');
+    }
+    const page = await query({
+      ...args,
+      command: commandName,
+      view: args.view ?? (args.history === true ? 'connected-history' : 'decision-window'),
+      stream,
+      afterActionId: afterActionIdOf(args, executionContext),
+      timeoutMs: timeoutMsOf(args, executionContext),
+      runtimeEpoch: executionContext.runtimeEpoch ?? args.runtimeEpoch ?? null,
+      sinceMs: args.sinceMs ?? null,
+      limit: args.limit ?? (commandName.startsWith('web-') ? 16 : 200),
+      serial: args.serial,
+      packageName: args.packageName,
+    });
+    return capturePage(page);
+  }
+
+  return { query: queryWindow };
+}
+
+function afterActionIdOf(args, executionContext) {
+  if (executionContext.evidenceWindow && executionContext.evidenceWindow.afterActionId != null) {
+    return executionContext.evidenceWindow.afterActionId;
+  }
+  if (executionContext.actionId != null) return executionContext.actionId;
+  if (args.afterActionId != null) return args.afterActionId;
+  return null;
+}
+
+function timeoutMsOf(args, executionContext) {
+  if (executionContext.evidenceWindow && executionContext.evidenceWindow.timeoutMs != null) {
+    return executionContext.evidenceWindow.timeoutMs;
+  }
+  if (executionContext.timeoutMs != null) return executionContext.timeoutMs;
+  return args.timeoutMs ?? null;
+}
+
+function streamFor(commandName) {
+  if (
+    commandName === 'logs'
+    || commandName === 'ios-logs'
+    || commandName === 'web-logs'
+    || commandName === 'webview-console'
+  ) return 'logs';
+  if (
+    commandName === 'network'
+    || commandName === 'ios-network'
+    || commandName === 'web-network'
+    || commandName === 'webview-network'
+  ) return 'network';
+  if (commandName === 'state' || commandName === 'ios-state' || commandName === 'web-state') return 'state';
+  if (commandName === 'events' || commandName === 'ios-events' || commandName === 'web-events') return 'events';
+  return null;
+}
+
+function isCaptureReadCommand(commandName) {
+  return streamFor(commandName) !== null;
+}
+
+module.exports = { createScriptCapturePort, isCaptureReadCommand };

package/bin/script/script-catalog.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { scriptPermissions } = require('../command-registry');
+const PERMISSIONS = Object.freeze(Object.fromEntries(Object.entries(scriptPermissions).map(([name, commands]) =>
+  [name, Object.freeze(name === 'app.read' ? [...commands, 'page-summary'] : [...commands])])));
+
+const DENY_DEFAULT = Object.freeze([
+  'clear-app-data',
+  'install-apk',
+  'ios-install-app',
+  'ios-setup',
+  'permission-grant',
+  'permission-revoke',
+  'appops-set',
+]);
+
+const DENY_PERMANENT = Object.freeze([
+  'h5-eval',
+  'flutter-h5-eval',
+  'ios-h5-eval',
+  'web-command',
+  'forward',
+  'remove-forward',
+]);
+
+const DEFAULT_PERMISSIONS = Object.freeze(['app.read', 'app.interact', 'capture.read']);
+
+function allowedCommands(permissions = DEFAULT_PERMISSIONS) {
+  const names = new Set();
+  for (const permission of permissions) {
+    for (const command of PERMISSIONS[permission] || []) names.add(command);
+  }
+  return [...names];
+}
+
+function commandPermission(command) {
+  for (const [permission, commands] of Object.entries(PERMISSIONS)) {
+    if (commands.includes(command)) return permission;
+  }
+  return null;
+}
+
+function authorizeCommand(command, permissions = DEFAULT_PERMISSIONS) {
+  if (DENY_PERMANENT.includes(command)) {
+    return { ok: false, error: 'command_permanently_denied', command };
+  }
+  if (DENY_DEFAULT.includes(command) && !permissions.includes(commandPermission(command))) {
+    return { ok: false, error: 'command_not_in_default_allowlist', command };
+  }
+  const permission = commandPermission(command);
+  if (!permission) {
+    return { ok: false, error: 'command_not_in_catalog', command };
+  }
+  if (!permissions.includes(permission)) {
+    return { ok: false, error: 'permission_not_granted', command, permission };
+  }
+  return { ok: true, command, permission };
+}
+
+function catalogPayload() {
+  return {
+    runtime: 'trusted-local-code',
+    warning: 'Script source is trusted-local-code, not an OS sandbox. permissions gate Bridge SDK calls only.',
+    schemaVersion: 'aab.code-script/v1',
+    languages: ['javascript', 'python'],
+    executablePlatforms: ['android', 'ios', 'web'],
+    unavailablePlatforms: {},
+    entrypoint: 'main',
+    permissions: PERMISSIONS,
+    defaultPermissions: DEFAULT_PERMISSIONS,
+    denyDefault: DENY_DEFAULT,
+    denyPermanent: DENY_PERMANENT,
+    internalOnly: ['page-summary'],
+  };
+}
+
+module.exports = {
+  PERMISSIONS,
+  DENY_DEFAULT,
+  DENY_PERMANENT,
+  DEFAULT_PERMISSIONS,
+  allowedCommands,
+  authorizeCommand,
+  catalogPayload,
+};