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

package/bin/intent/permission-intent.js

@@ -0,0 +1,239 @@
+'use strict';
+
+const { normalizeExecutionTarget } = require('../shared-kernel/execution-target');
+
+const { CommandError, executionFields } = require('../command-errors');
+const { readPermissionState, readPermissionRequest } = require('../android-permissions');
+const { getProcessDeviceMutationLease } = require('../shared-kernel/device-mutation-lease');
+const { checksumOf } = require('../shared-kernel/evidence-schema');
+const { createIntentWorker } = require('./intent-worker');
+const { createProductionIntentDeviceAdapter } = require('./intent-production-adapter');
+
+const sameState = (a, b) => a.uid === b.uid && a.userId === b.userId && a.granted === b.granted && JSON.stringify(a.flags) === JSON.stringify(b.flags);
+const sameRequest = (a, b) => a && b && ['token', 'component', 'userId', 'requesterPackage', 'requesterUid'].every(key => a[key] === b[key]);
+const rejection = error => ({ ok: false, error, dispatched: false, ambiguous: false });
+
+function permissionDeviceAdapter({ args, origin, expectedState, canDispatch, onDispatch, onFailure, readState, readRequest, ports }) {
+  const bridge = ports || require('../device-provider');
+  let selectedRequest = null;
+  function providerResult(result, stage) {
+    if (result.ok || !result.error || /^[a-z][a-z0-9_]+$/.test(result.error)) return result;
+    const error = `permission_ui_${stage}_failed`;
+    onFailure({ stage, error, message: String(result.error).slice(0, 2048) });
+    return { ...result, error };
+  }
+  async function input(action) {
+    let state; let request;
+    try {
+      state = await readState(args);
+      if (!sameState(expectedState(), state)) return rejection('permission_state_changed');
+      request = await readRequest(args);
+      if (!sameRequest(origin(), request.request) || !sameRequest(selectedRequest, request.request)) return rejection('permission_request_changed');
+    } catch (error) { return rejection(error.code || 'permission_query_failed'); }
+    if (!canDispatch()) return rejection('cancelled');
+    onDispatch();
+    try {
+      return { ...await action(), precondition: { request, state } };
+    } catch (error) {
+      return { ok: false, error: 'permission_input_failed', dispatched: error.code === 'ENOENT' ? false : true,
+        ambiguous: error.code !== 'ENOENT', cause: error.code || null, precondition: { request, state }, ...executionFields(error) };
+    }
+  }
+  const base = createProductionIntentDeviceAdapter({ adb: args.adb, ports: {
+    ...bridge,
+    uiaTap: (ctx, binding, options) => input(() => bridge.uiaTap(ctx, binding, options)),
+    keyevent: ctx => input(() => bridge.keyevent(ctx, 4)),
+  } });
+  return {
+    async observe(request) {
+      try {
+        const before = await readRequest(args);
+        if (!sameRequest(origin(), before.request)) return rejection('permission_request_changed');
+        const observed = await base.observe({ ...request, provider: 'uia', packageName: before.request.packageName, foregroundPackages: [] });
+        if (!observed.ok) return providerResult(observed, 'observation');
+        const after = await readRequest(args);
+        if (!sameRequest(before.request, after.request) || after.request.component !== `${observed.route.packageName}/${observed.route.activity}`) return rejection('permission_request_changed');
+        return { ...observed, route: { ...observed.route, permissionRequest: after.request } };
+      } catch (error) { return rejection(error.code || 'permission_request_query_failed'); }
+    },
+    async action(request) {
+      selectedRequest = request.route?.permissionRequest;
+      if (!sameRequest(origin(), selectedRequest)) return rejection('permission_request_changed');
+      return providerResult(await base.action({ ...request, primaryProvider: 'uia', foregroundPackages: [origin().packageName],
+        spec: { ...request.spec, provider: 'uia', exact: true, requireClickable: true } }), 'action');
+    },
+  };
+}
+
+async function createPermissionIntent({ args, operationId, store, recording, dependencies = {} }) {
+  const ownership = (dependencies.lease || getProcessDeviceMutationLease()).acquire(args.serial);
+  if (!ownership.ok) throw new CommandError(ownership.error, 'The device is owned by another operation.', { details: { serial: args.serial } });
+  const readState = dependencies.readState || readPermissionState;
+  const readRequest = dependencies.readRequest || readPermissionRequest;
+  const bound = { ...args };
+  const target = normalizeExecutionTarget({ platform: 'android', serial: args.serial, packageName: args.packageName, foregroundPackages: [],
+    ...(args.adb === undefined ? {} : { adb: args.adb }) }, { intent: true });
+  let worker; let active = null; let finalizing = null; let final = false; let stopping = null; let timer; let deadline = Infinity;
+  let expected; let origin; let dispatched = false; let ownedReceipt = null;
+  const permissionDialog = { kind: 'permission-dialog', permission: args.permission, outcome: args.outcome,
+    phase: 'preparing', before: null, after: null, requestBefore: null, requestAfter: null, verified: false, actionCount: 0 };
+  try {
+    const adapter = permissionDeviceAdapter({ args: bound, origin: () => origin, expectedState: () => expected,
+      canDispatch: () => Date.now() < deadline && !stopping && !finalizing && !final && worker.context.canDispatch(),
+      onDispatch: () => { dispatched = true; permissionDialog.actionCount++; }, readState, readRequest,
+      onFailure: failure => { permissionDialog.providerFailure = failure; },
+      ports: dependencies.ports });
+    worker = createIntentWorker({ operationId, target, ownsOutcome: false, timeoutMs: null, provider: 'uia', store, recording, adapter,
+      goal: `Resolve the observed runtime permission request from ${args.packageName}: ${args.outcome} ${args.permission}. Read the actual UI and select exactly one visible control. Completion requires PackageManager state and closure of this Activity instance. No recording or other App action is part of this workflow.` });
+  } catch (error) { ownership.release(); throw error; }
+  function snapshot() {
+    return { ...worker.status(), permissionDialog: { ...permissionDialog } };
+  }
+  async function persist(kind, record) {
+    const result = await store.persist(kind, { operationId, target, revision: worker.runtime.state.revision, timestampMs: Date.now(), ...record });
+    if (!result.ok) throw new CommandError(result.error || 'permission_evidence_failed', 'Permission evidence could not be committed.');
+    return result;
+  }
+  async function inspect() {
+    permissionDialog.after = await readState(bound);
+    permissionDialog.requestAfter = await readRequest(bound);
+    permissionDialog.dialogClosed = !permissionDialog.requestAfter.activeRequestTokens.includes(origin.token);
+    permissionDialog.pending = !permissionDialog.dialogClosed && !permissionDialog.requestAfter.request ? 'activity_closure' : null;
+  }
+  async function verify() {
+    await inspect();
+    if (permissionDialog.after.uid !== permissionDialog.before.uid) return { status: 'intervention_required', error: 'permission_target_changed' };
+    const request = permissionDialog.requestAfter.request;
+    if (request && !sameRequest(origin, request)) return { status: 'intervention_required', error: 'permission_request_changed' };
+    if (!ownedReceipt) {
+      if (permissionDialog.dialogClosed || !sameState(expected, permissionDialog.after)) return { status: 'intervention_required', error: 'permission_changed_without_owned_action' };
+      return null;
+    }
+    expected = permissionDialog.after;
+    if (!permissionDialog.dialogClosed) {
+      if (permissionDialog.pending) {
+        worker.runtime.state.status = 'waiting_for_observation'; worker.runtime.state.error = null;
+      }
+      return null;
+    }
+    const after = permissionDialog.after;
+    const matches = args.outcome === 'allow' ? after.granted && !after.flags.includes('ONE_TIME')
+      : args.outcome === 'allow-once' ? after.granted && after.flags.includes('ONE_TIME')
+      : args.outcome === 'deny' ? !after.granted && after.flags.includes('USER_SET')
+      : sameState(permissionDialog.before, after);
+    permissionDialog.verified = matches;
+    return matches ? { status: 'completed', error: null } : { status: 'failed', error: 'permission_outcome_mismatch' };
+  }
+  function finish(verdict) {
+    if (finalizing) return finalizing;
+    clearTimeout(timer);
+    worker.runtime.state.status = 'finishing';
+    finalizing = (async () => {
+      try {
+        await worker.quiesce();
+        worker.runtime.state.status = 'finishing';
+        if (verdict.status !== 'completed') {
+          permissionDialog.verified = false;
+          // Cancel stops this operation, never presses Back and never rolls back
+          // an Android grant. Report the final observed state after in-flight I/O.
+          try { if (origin) await inspect(); }
+          catch (error) { permissionDialog.verificationError = error.code || 'permission_query_failed'; }
+        }
+        permissionDialog.phase = verdict.status;
+        const proof = await persist('checkpoint', { stepId: 'permission-outcome', payloadSummary: { ...verdict, permissionDialog: { ...permissionDialog } } });
+        permissionDialog.verificationEvidenceId = proof.evidenceId;
+        worker.runtime.state.status = verdict.status; worker.runtime.state.error = verdict.error;
+        worker.runtime.emit('permission_verified', { status: verdict.status, verified: permissionDialog.verified, evidenceId: proof.evidenceId });
+      } catch (error) {
+        permissionDialog.phase = 'blocked_evidence_store'; permissionDialog.verified = false;
+        worker.runtime.state.status = 'blocked_evidence_store'; worker.runtime.state.error = error.code || 'permission_evidence_failed';
+      } finally { final = true; ownership.release(); }
+      return snapshot();
+    })();
+    return finalizing;
+  }
+  async function stop(status, error) {
+    if (final || finalizing) { await finalizing; return snapshot(); }
+    stopping ||= { status, error };
+    const uiStopped = worker.cancel();
+    await uiStopped;
+    await active;
+    return finish(stopping);
+  }
+  async function run(fn) {
+    if (final || finalizing || stopping) return { ...snapshot(), ok: false, error: 'operation_stopped' };
+    if (active) return { ...snapshot(), ok: false, error: 'operation_busy' };
+    let result; let verdict;
+    active = ownership.run(async () => {
+      try { ({ result, verdict } = await fn()); }
+      catch (error) { verdict = { status: dispatched ? 'inconclusive' : 'failed', error: error.code || 'permission_verification_failed' }; }
+    });
+    await active;
+    active = null;
+    if (Date.now() >= deadline) stopping ||= { status: 'timeout', error: 'permission_dialog_timeout' };
+    if (stopping) return finish(stopping);
+    if (verdict) return finish(verdict);
+    permissionDialog.phase = worker.runtime.state.status;
+    return { ...snapshot(), ...(result ? { ok: result.ok, error: result.error } : {}) };
+  }
+  function workerFailure(result) {
+    return ['failed', 'ambiguous', 'blocked_evidence_store'].includes(result.status) ? { status: result.status, error: result.error } : null;
+  }
+  return {
+    ...worker, isManagedWorkflow: true, isFinished: () => final, status: snapshot,
+    start: () => run(async () => {
+      deadline = Date.now() + (args.timeoutMs || 60000);
+      timer = setTimeout(() => { stop('timeout', 'permission_dialog_timeout'); }, args.timeoutMs || 60000); timer.unref?.();
+      permissionDialog.before = expected = await readState(bound);
+      bound.userId = expected.userId;
+      permissionDialog.requestBefore = await readRequest(bound);
+      origin = permissionDialog.requestBefore.request;
+      if (!origin) throw new CommandError('permission_dialog_not_found', 'Trigger a runtime permission request through the App before starting permission-dialog.');
+      if (origin.requesterPackage !== args.packageName || origin.requesterUid !== expected.uid || origin.userId !== expected.userId) {
+        throw new CommandError('permission_requester_mismatch', 'The visible runtime permission request belongs to a different App or Android user.');
+      }
+      const plan = await persist('plan', { planStepId: 'permission-request', actionSpecHash: checksumOf({ target, outcome: args.outcome, permission: args.permission }),
+        payloadSummary: { permissionDialog: { ...permissionDialog } } });
+      permissionDialog.planEvidenceId = plan.evidenceId;
+      if (stopping) return {};
+      const result = await worker.start();
+      return { result, verdict: result.ok ? null : { status: 'inconclusive', error: result.error } };
+    }),
+    observe: options => run(async () => {
+      const verdict = await verify();
+      if (verdict || stopping) return { verdict };
+      if (permissionDialog.pending) return { result: { ok: true, error: null } };
+      const result = await worker.observe(options);
+      return { result, verdict: workerFailure(result) };
+    }),
+    decide: decision => run(async () => {
+      const action = decision?.action;
+      const allowed = action?.action === 'tap' && action.selector && Object.keys(action).every(key => ['action', 'selector', 'provider', 'exact', 'requireClickable'].includes(key))
+        || args.outcome === 'dismiss' && action?.action === 'back' && Object.keys(action).every(key => ['action', 'provider'].includes(key));
+      if (decision?.agentDecision !== 'act' || !allowed || action?.exact === false || action?.provider && action.provider !== 'uia') {
+        return { result: { ok: false, error: 'permission_requires_observed_decision', message: 'Use an exact observed tap; dismiss also accepts back. Completion is verified independently. Use intent cancel to stop the operation.' } };
+      }
+      const previous = worker.context.latestEvidenceIds.receipt;
+      const result = await worker.decide(decision);
+      const failure = workerFailure(result);
+      if (failure || stopping) return { result, verdict: failure };
+      const receiptId = worker.context.latestEvidenceIds.receipt;
+      if (receiptId && receiptId !== previous) {
+        const receipt = store.read(receiptId);
+        if (!receipt.ok || receipt.record.mechanicalStatus !== 'ok' || receipt.record.ambiguous || !receipt.record.dispatched) {
+          return { verdict: { status: 'inconclusive', error: 'permission_action_not_verified' } };
+        }
+        permissionDialog.actionEvidenceId = ownedReceipt = receiptId;
+        const verdict = await verify();
+        return { result: permissionDialog.pending ? { ok: true, error: null } : result, verdict };
+      }
+      return { result };
+    }),
+    cancel: () => stop('cancelled', 'permission_dialog_cancelled'),
+    intervene: reason => stop('intervention_required', reason || 'permission_dialog_intervened'),
+    pause() { if (!active && !finalizing && !stopping && !final) worker.pause(); return snapshot(); },
+    resume() { if (!active && !finalizing && !stopping && !final) worker.resume(); return snapshot(); },
+  };
+}
+
+module.exports = { createPermissionIntent, permissionDeviceAdapter, sameState, sameRequest };

package/bin/intent/web-intent-adapter.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const { selectWebNode, schema } = require('../shared-kernel/web-dom-target');
+
+function createWebIntentDeviceAdapter({ provider } = {}) {
+  if (!provider || typeof provider.run !== 'function') throw new TypeError('Web Intent requires the serving Web provider.');
+  const bound = target => ({ sessionId: target.sessionId, runtimeEpoch: target.runtimeEpoch, targetId: target.targetId ?? 'main' });
+  return {
+    async observe(target) {
+      const rawTree = await provider.run('web-dom', bound(target));
+      if (rawTree.ok !== true) return rawTree;
+      if (rawTree.webTargetSchema !== schema) return { ok: false, error: 'web_dom_target_schema_required' };
+      return { ok: true, provider: 'h5', rawTreeId: target.rawTreeId, rawTree, foregroundTarget: rawTree.pageRef.url };
+    },
+    async action(target) {
+      const { spec, rawTree } = target;
+      const selected = selectWebNode(rawTree, spec.selector);
+      if (!selected.ok) return selected;
+      const commands = { tap: 'web-click', inputText: 'web-input', pressKey: 'web-key', scroll: 'web-scroll', scrollBy: 'web-scroll' };
+      const result = await provider.run(commands[spec.action], { ...bound(target), runtimeActionId: target.actionId,
+        selector: { elementId: selected.node.elementId }, expectedTarget: selected.targetRef,
+        ...(spec.action === 'inputText' ? { value: spec.value } : {}),
+        ...(spec.action === 'pressKey' ? { key: spec.key } : {}),
+        ...(spec.action === 'scroll' ? { mode: 'into-view' } : {}),
+        ...(spec.action === 'scrollBy' ? { mode: 'by', deltaX: spec.deltaX, deltaY: spec.deltaY } : {}) });
+      return { ...result, mechanicalStatus: result.ok === true ? 'ok' : 'failed' };
+    },
+  };
+}
+
+module.exports = { createWebIntentDeviceAdapter };

package/bin/ios-device-outcome.js

@@ -0,0 +1,47 @@
+'use strict';
+const { isDeepStrictEqual } = require('node:util');
+
+// A normal process exit alone cannot settle a remote action. Only the original
+// devicectl JSON response, with its exact arguments and explicit OS rejection,
+// can identify a known device rejection. Timeout/transport loss stays unknown.
+function deviceCommandRejection(reply, args, error) {
+  if (!Number.isInteger(error?.code) || error.code === 0 || error.signal || error.killed) return null;
+  return originalDeviceRejection(reply, args);
+}
+
+// For recovery, the caller must independently associate the retained original
+// response and exact invocation with the pending operation before using it.
+function originalDeviceRejection(reply, args) {
+  const command = args.slice(0, 3).join(' ');
+  const type = command === 'device process launch' ? 'devicectl.device.process.launch'
+    : command === 'device install app' ? 'devicectl.device.install.app' : null;
+  if (!type
+      || reply?.info?.jsonVersion !== 4 || reply.info.outcome !== 'failed'
+      || reply.info.commandType !== type
+      || !isDeepStrictEqual(reply.info.arguments, ['devicectl', ...args])) return null;
+  const errors = [];
+  function visit(value, depth) {
+    if (!value || typeof value !== 'object' || depth > 16 || errors.length > 32) return;
+    if (typeof value.domain === 'string' && Number.isInteger(value.code)) errors.push(value);
+    for (const item of Object.values(value)) visit(item, depth + 1);
+  }
+  visit(reply.error, 0);
+  if (command === 'device install app') {
+    const installer = errors.find(value => value.domain === 'MIInstallerErrorDomain' && value.code === 13);
+    if (!errors.some(value => value.domain === 'com.apple.dt.CoreDeviceError' && value.code === 3002)
+        || !errors.some(value => value.domain === 'IXUserPresentableErrorDomain' && value.code === 14)
+        || installer?.userInfo?.LegacyErrorString?.string !== 'ApplicationVerificationFailed'
+        || !installer.userInfo.NSLocalizedDescription?.string?.startsWith('This device has reached the maximum number of installed apps using a free developer profile:')) return null;
+    return { ok: false, error: 'ios_free_profile_app_limit',
+      message: 'The selected iPhone has reached the free developer profile App limit. Remove an explicitly selected test App before installing another.',
+      settled: true, dispatched: true, ambiguous: false, deviceOutcome: reply };
+  }
+  const reason = errors.find(value => value.domain === 'FBSOpenApplicationErrorDomain' && [3, 7].includes(value.code));
+  if (!errors.some(value => value.domain === 'FBSOpenApplicationServiceErrorDomain' && value.code === 1) || !reason) return null;
+  return { ok: false, error: reason.code === 7 ? 'ios_device_locked' : 'ios_app_launch_rejected',
+    message: reason.code === 7 ? 'Unlock the selected iPhone before launching the App.'
+      : 'iOS rejected the App launch. Check its code signature, entitlements and developer trust on the selected device.',
+    settled: true, dispatched: true, ambiguous: false, deviceOutcome: reply };
+}
+
+module.exports = { deviceCommandRejection, originalDeviceRejection };

package/bin/ios-execution.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+const { CommandError } = require('./command-errors');
+const managed = require('./shared-kernel/managed-sdk-execution');
+const { runDeviceEffect } = require('./shared-kernel/device-mutation-lease');
+const { checkExecution, runExecution } = require('./shared-kernel/execution-scope');
+
+const schemas = { h5: 'aab.h5-execution/v1', flutter: 'aab.flutter-execution/v1', wda: 'aab.wda-execution/v1' };
+
+function iosDeviceKey(device) {
+  if (typeof device?.udid !== 'string' || !device.udid) {
+    throw new CommandError('ios_device_identity_unavailable', 'devicectl must supply the physical iOS UDID before mutation or recovery.');
+  }
+  return `ios:${device.udid}`;
+}
+
+async function lookupCompletion(port, kind, identity, first) {
+  let page = first;
+  let after = 0;
+  let through;
+  let cursor;
+  while (true) {
+    checkExecution();
+    if (!page) {
+      const query = new URLSearchParams({ ...(kind === 'wda' ? {} : { kind }), ...identity, ...(cursor === undefined ? {} : { cursor }) });
+      page = await port.get(`${kind === 'wda' ? '/aab/execution/result' : '/v1/execution/result'}?${query}`);
+    }
+    if (page.ok !== true) return page;
+    if (page.executionResult) {
+      if (page.actionId !== identity.actionId || page.runtimeEpoch !== identity.runtimeEpoch
+        || !managed.terminalReceipt(schemas[kind], page.executionResult, identity)) {
+        return { ok: false, error: 'invalid_ios_completion_receipt', settled: false };
+      }
+      return page;
+    }
+    if (page.found !== false || typeof page.hasMore !== 'boolean') return { ok: false, error: 'invalid_ios_completion_page', settled: false };
+    if (!page.hasMore) return { ok: false, error: 'ios_original_completion_unavailable', settled: false, ...identity };
+    if (!Number.isSafeInteger(page.nextSequence) || page.nextSequence <= after
+      || !Number.isSafeInteger(page.throughSequence) || page.nextSequence >= page.throughSequence
+      || typeof page.nextCursor !== 'string' || !page.nextCursor || page.nextCursor.length > 2048
+      || (through !== undefined && page.throughSequence !== through)) {
+      return { ok: false, error: 'invalid_ios_completion_cursor', settled: false };
+    }
+    after = page.nextSequence; through = page.throughSequence; cursor = page.nextCursor; page = null;
+  }
+}
+
+async function executeIOSAction({ port, kind, payload, status, target, timeoutMs, actionId }) {
+  if (kind === 'h5' && status.debugBridge?.h5TargetSchema !== require('./shared-kernel/ios-h5-target').schema) {
+    return { ok: false, error: 'ios_h5_target_schema_required', dispatched: false, ambiguous: false,
+      message: 'Update the selected App SDK to one that binds H5 actions to observed WebViews and documents.' };
+  }
+  const runtime = kind === 'h5'
+    ? { runtimeEpoch: status.debugBridge?.runtimeEpoch, executionSchema: status.debugBridge?.h5ExecutionSchema }
+    : { runtimeEpoch: status.flutter?.layout?.operable?.runtimeEpoch, executionSchema: status.debugBridge?.flutterExecutionSchema };
+  if (runtime.executionSchema !== schemas[kind] || typeof runtime.runtimeEpoch !== 'string' || !runtime.runtimeEpoch) {
+    return { ok: false, error: 'ios_managed_execution_unavailable', dispatched: false, ambiguous: false,
+      message: 'The selected iOS SDK/Flutter engine must advertise managed execution before an action can run.' };
+  }
+  const identity = { actionId: actionId ?? randomUUID(), runtimeEpoch: runtime.runtimeEpoch };
+  return runDeviceEffect({ kind: `ios-${kind}`, ...identity, target }, async () => {
+    const result = await managed.executeManagedAction({ kind, schema: schemas[kind], runtime, payload,
+      actionId: identity.actionId, timeoutMs,
+      send: request => port.post(kind === 'h5' ? '/v1/h5/action' : '/v1/flutter/action', request),
+      cancel: original => runExecution({ timeoutMs: 4000 }, async () => {
+        const cancelled = await port.post(`/v1/${kind}/cancel`, original);
+        if (cancelled.ok !== true) return cancelled;
+        return lookupCompletion(port, kind, original, cancelled);
+      }),
+    });
+    return { ...result, executionReceipt: managed.settlementProof(`ios-${kind}`, schemas[kind], result, identity) };
+  }, result => result.executionReceipt);
+}
+
+async function reconcileIOS({ lease, device, args, createPort }) {
+  return lease.reconcile(iosDeviceKey(device), async pending => {
+    const kind = pending.kind === 'ios-h5' ? 'h5' : pending.kind === 'ios-flutter' ? 'flutter' : null;
+    if (!kind || pending.target?.deviceId !== device.udid || pending.target?.bundleId !== args.bundleId
+      || typeof pending.actionId !== 'string' || typeof pending.runtimeEpoch !== 'string') {
+      return { settled: false, error: 'ios_original_completion_identity_required' };
+    }
+    const identity = { actionId: pending.actionId, runtimeEpoch: pending.runtimeEpoch };
+    try {
+      // Reconnect to the original device/App. The process serving durable
+      // history may be new; the queried action/epoch can never be replaced.
+      const target = { ...pending.target, timeoutMs: args.timeoutMs ?? 30000 };
+      if (args.runtimeUrl !== undefined) {
+        delete target.iosHost; delete target.iosPort; target.runtimeUrl = args.runtimeUrl;
+      } else if (args.iosHost !== undefined || args.iosPort !== undefined) {
+        delete target.runtimeUrl;
+        for (const key of ['iosHost', 'iosPort']) if (args[key] !== undefined) target[key] = args[key];
+      }
+      if (args.devicectl !== undefined) target.devicectl = args.devicectl;
+      const port = await createPort(target);
+      const reply = await lookupCompletion(port, kind, identity);
+      if (reply.ok !== true || reply.receipt?.committed !== true
+        || !Number.isSafeInteger(reply.receipt?.sequence) || reply.receipt.sequence < 1
+        || !/^[a-f0-9]{64}$/.test(reply.receipt?.sha256)) {
+        return { settled: false, error: reply.error || 'ios_durable_completion_required' };
+      }
+      return managed.settlementProof(`ios-${kind}`, schemas[kind], reply.executionResult, identity)
+        || { settled: false, error: 'invalid_ios_completion_receipt' };
+    } catch (error) { return { settled: false, error: error.code || 'ios_completion_query_failed', message: error.message }; }
+  });
+}
+
+module.exports = { iosDeviceKey, executeIOSAction, lookupCompletion, reconcileIOS };