@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/plugins/interaction-session.ts

@@ -0,0 +1,252 @@
+import { existsSync, readdirSync, rmSync } from 'fs';
+import { join } from 'path';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+
+export type InteractionProvider = 'browser' | 'ios-simulator' | 'ios-device';
+export type InteractionEngine = 'agent-device' | 'coredevice';
+export type InteractionSessionStatus =
+  | 'starting'
+  | 'waiting_for_user'
+  | 'unknown'
+  | 'closing'
+  | 'completed'
+  | 'closed'
+  | 'failed';
+export type InteractionCommandKind = 'resume' | 'cancel';
+
+export interface InteractionSessionRecord {
+  schemaVersion: 1;
+  interactionId: string;
+  provider: InteractionProvider;
+  /** Execution engine inside the provider-owned resource domain. Optional for schema-v1 compatibility. */
+  engine?: InteractionEngine;
+  sessionId: string;
+  targetId: string;
+  /** Stable identifiers known to refer to the same provider resource. Immutable after creation. */
+  targetAliases?: string[];
+  status: InteractionSessionStatus;
+  reason: string;
+  instructions?: string;
+  owner: {
+    repoId: string;
+    requestId: string;
+    jobId?: string;
+  };
+  host?: {
+    pid?: number;
+    startedAt?: string;
+    heartbeatAt?: string;
+    foregroundPresented?: boolean;
+  };
+  result?: {
+    url?: string;
+    title?: string;
+  };
+  error?: {
+    code: string;
+    message: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+  expiresAt: string;
+}
+
+export interface InteractionCommand {
+  schemaVersion: 1;
+  interactionId: string;
+  kind: InteractionCommandKind;
+  requestedAt: string;
+  requestedBy: string;
+}
+
+function providerRoot(repoRoot: string, provider: InteractionProvider): string {
+  return join(repoRoot, '.forge', 'interactions', sanitizeFileComponent(provider));
+}
+
+export function interactionSessionPath(repoRoot: string, provider: InteractionProvider, interactionId: string): string {
+  return join(providerRoot(repoRoot, provider), 'sessions', `${sanitizeFileComponent(interactionId)}.json`);
+}
+
+export function interactionLaunchSpecPath(repoRoot: string, provider: InteractionProvider, interactionId: string): string {
+  return join(providerRoot(repoRoot, provider), 'launch', `${sanitizeFileComponent(interactionId)}.json`);
+}
+
+export function interactionCommandPath(
+  repoRoot: string,
+  provider: InteractionProvider,
+  interactionId: string,
+  kind: InteractionCommandKind,
+): string {
+  return join(providerRoot(repoRoot, provider), 'commands', `${sanitizeFileComponent(interactionId)}.${kind}.json`);
+}
+
+export function readInteractionSession(
+  repoRoot: string,
+  provider: InteractionProvider,
+  interactionId: string,
+): InteractionSessionRecord | undefined {
+  const path = interactionSessionPath(repoRoot, provider, interactionId);
+  if (!existsSync(path)) return undefined;
+  const value = readJsonFile<InteractionSessionRecord | undefined>(path, undefined);
+  return value?.schemaVersion === 1 && value.interactionId === interactionId ? value : undefined;
+}
+
+export function interactionAutomationEngine(record: InteractionSessionRecord): InteractionEngine | undefined {
+  if (record.engine !== undefined) {
+    return record.engine === 'agent-device' || record.engine === 'coredevice'
+      ? record.engine
+      : undefined;
+  }
+  if ((record.provider === 'ios-device' || record.provider === 'ios-simulator')
+    && record.interactionId.startsWith('ios_agent_device_')
+    && (record.reason === 'ios_simulator_automation' || record.reason === 'ios_physical_device_automation')) {
+    return 'agent-device';
+  }
+  if (record.provider === 'ios-device'
+    && record.interactionId.startsWith('ios_device_')
+    && record.reason === 'ios_physical_device_automation') {
+    return 'coredevice';
+  }
+  return undefined;
+}
+
+export function interactionTargetIdentifiers(record: InteractionSessionRecord): string[] {
+  return Array.from(new Set([
+    record.targetId,
+    ...(Array.isArray(record.targetAliases) ? record.targetAliases : []),
+  ].filter((value): value is string => typeof value === 'string' && Boolean(value.trim()))
+    .map((value) => value.trim())));
+}
+
+export function interactionTargetsOverlap(
+  record: InteractionSessionRecord,
+  candidates: Array<string | undefined>,
+): boolean {
+  const canonical = (value: string) => value.trim().toLocaleLowerCase('en-US');
+  const expected = new Set(candidates
+    .filter((value): value is string => typeof value === 'string' && Boolean(value.trim()))
+    .map(canonical));
+  return interactionTargetIdentifiers(record).some((value) => expected.has(canonical(value)));
+}
+
+/**
+ * Decide whether an active interaction may own one selected target.
+ *
+ * Pre-alias physical-device records cannot prove that their provider-internal
+ * identifier names a different phone from a hardware UDID. During migration,
+ * fail closed inside the shared ios-device domain rather than permitting a
+ * second automation engine to acquire a potentially identical phone.
+ */
+export function interactionMayOwnTarget(
+  record: InteractionSessionRecord,
+  candidates: Array<string | undefined>,
+): boolean {
+  if (interactionTargetsOverlap(record, candidates)) return true;
+  if (record.provider !== 'ios-device') return false;
+  const hasTrustedAliases = Array.isArray(record.targetAliases)
+    && record.targetAliases.some((value) => typeof value === 'string' && Boolean(value.trim()));
+  return !hasTrustedAliases;
+}
+
+export function writeInteractionSession(repoRoot: string, record: InteractionSessionRecord): InteractionSessionRecord {
+  writeJsonAtomic(interactionSessionPath(repoRoot, record.provider, record.interactionId), record);
+  return record;
+}
+
+export function patchInteractionSession(
+  repoRoot: string,
+  provider: InteractionProvider,
+  interactionId: string,
+  patch: Partial<Omit<InteractionSessionRecord,
+    | 'schemaVersion'
+    | 'interactionId'
+    | 'provider'
+    | 'engine'
+    | 'sessionId'
+    | 'targetId'
+    | 'targetAliases'
+    | 'owner'
+    | 'createdAt'
+  >>,
+): InteractionSessionRecord | undefined {
+  const current = readInteractionSession(repoRoot, provider, interactionId);
+  if (!current) return undefined;
+  return writeInteractionSession(repoRoot, {
+    ...current,
+    ...patch,
+    host: patch.host ? { ...current.host, ...patch.host } : current.host,
+    result: patch.result ? { ...current.result, ...patch.result } : current.result,
+    updatedAt: patch.updatedAt ?? new Date().toISOString(),
+  });
+}
+
+export function listInteractionSessions(repoRoot: string, provider: InteractionProvider): InteractionSessionRecord[] {
+  const root = join(providerRoot(repoRoot, provider), 'sessions');
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => readJsonFile<InteractionSessionRecord | undefined>(join(root, name), undefined))
+    .filter((entry): entry is InteractionSessionRecord => Boolean(entry?.schemaVersion === 1 && entry.interactionId))
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+}
+
+export function writeInteractionCommand(
+  repoRoot: string,
+  provider: InteractionProvider,
+  interactionId: string,
+  kind: InteractionCommandKind,
+  requestedBy: string,
+): InteractionCommand {
+  const command: InteractionCommand = {
+    schemaVersion: 1,
+    interactionId,
+    kind,
+    requestedAt: new Date().toISOString(),
+    requestedBy,
+  };
+  writeJsonAtomic(interactionCommandPath(repoRoot, provider, interactionId, kind), command);
+  return command;
+}
+
+export function readInteractionCommand(
+  repoRoot: string,
+  provider: InteractionProvider,
+  interactionId: string,
+  kind: InteractionCommandKind,
+): InteractionCommand | undefined {
+  const path = interactionCommandPath(repoRoot, provider, interactionId, kind);
+  if (!existsSync(path)) return undefined;
+  return readJsonFile<InteractionCommand | undefined>(path, undefined);
+}
+
+export function removeInteractionCommand(
+  repoRoot: string,
+  provider: InteractionProvider,
+  interactionId: string,
+  kind: InteractionCommandKind,
+): void {
+  rmSync(interactionCommandPath(repoRoot, provider, interactionId, kind), { force: true });
+}
+
+export function removeInteractionSession(repoRoot: string, provider: InteractionProvider, interactionId: string): void {
+  rmSync(interactionSessionPath(repoRoot, provider, interactionId), { force: true });
+  rmSync(interactionLaunchSpecPath(repoRoot, provider, interactionId), { force: true });
+  removeInteractionCommand(repoRoot, provider, interactionId, 'resume');
+  removeInteractionCommand(repoRoot, provider, interactionId, 'cancel');
+}
+
+export function pruneInteractionSessions(
+  repoRoot: string,
+  provider: InteractionProvider,
+  maxTerminalSessions = 100,
+): number {
+  const terminal = listInteractionSessions(repoRoot, provider)
+    .filter((record) => !isInteractionSessionActive(record.status));
+  const stale = terminal.slice(Math.max(0, Math.trunc(maxTerminalSessions)));
+  for (const record of stale) removeInteractionSession(repoRoot, provider, record.interactionId);
+  return stale.length;
+}
+
+export function isInteractionSessionActive(status: InteractionSessionStatus): boolean {
+  return status === 'starting' || status === 'waiting_for_user' || status === 'unknown' || status === 'closing';
+}

package/src/runtime/plugins/ios/agent-device-capabilities.ts

@@ -0,0 +1,258 @@
+import { createHash } from 'crypto';
+
+export const PREFERRED_AGENT_DEVICE_VERSION = '0.20.2';
+export const MINIMUM_AGENT_DEVICE_VERSION = '0.19.3';
+const REVIEWED_FALLBACK_VERSIONS = new Set(['0.19.3', '0.20.2', '0.20.3']);
+
+export interface AgentDeviceSemanticVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  raw: string;
+}
+
+export interface AgentDeviceHelpContract {
+  root?: string;
+  snapshot?: string;
+  press?: string;
+  fill?: string;
+  batch?: string;
+  keyboard?: string;
+}
+
+export interface AgentDeviceCapabilityProfile {
+  version: string;
+  versionSupported: boolean;
+  source: 'help' | 'known-version' | 'unsupported';
+  contractFingerprint: string;
+  global: {
+    costFlag?: '--cost';
+  };
+  snapshot: {
+    interactiveFlag?: '-i';
+    depthFlag?: '--depth';
+    scopeFlag?: '--scope';
+    rawFlag?: '--raw';
+    forceFullFlag?: '--force-full';
+  };
+  press: {
+    supported: boolean;
+    settleFlag?: '--settle';
+  };
+  fill: {
+    supported: boolean;
+    settleFlag?: '--settle';
+    delayFlag?: '--delay-ms';
+    verifyFlag?: '--verify';
+  };
+  batch: {
+    supported: boolean;
+    stepsFlag?: '--steps';
+    onErrorFlag?: '--on-error';
+    maxStepsFlag?: '--max-steps';
+  };
+  keyboard: {
+    returnSupported: boolean;
+    dismissSupported: boolean;
+  };
+}
+
+export interface SnapshotCommandOptions {
+  interactiveOnly?: boolean;
+  raw?: boolean;
+  depth?: number;
+  scope?: string;
+  forceFull?: boolean;
+}
+
+export function parseAgentDeviceVersion(value: string | undefined): AgentDeviceSemanticVersion | undefined {
+  const raw = value?.trim();
+  if (!raw) return undefined;
+  const match = raw.match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return undefined;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    raw,
+  };
+}
+
+function compareVersion(left: AgentDeviceSemanticVersion, right: AgentDeviceSemanticVersion): number {
+  return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+}
+
+export function isSupportedAgentDeviceVersion(value: string | undefined): boolean {
+  const parsed = parseAgentDeviceVersion(value);
+  const minimum = parseAgentDeviceVersion(MINIMUM_AGENT_DEVICE_VERSION)!;
+  if (!parsed || compareVersion(parsed, minimum) < 0) return false;
+  // The public Node/CLI contracts are still pre-1.0. Treat the next minor as a
+  // compatibility boundary until its help/typed contract is reviewed.
+  return parsed.major === 0 && parsed.minor <= 20;
+}
+
+function includesFlag(help: string | undefined, flag: string): boolean {
+  return Boolean(help && new RegExp(`(^|[\\s,|\\[])${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=$|[\\s,|\\]<>])`, 'm').test(help));
+}
+
+function includesWord(help: string | undefined, word: string): boolean {
+  return Boolean(help && new RegExp(`(^|[\\s|\\[])${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=$|[\\s|\\]])`, 'm').test(help));
+}
+
+function knownVersionProfile(version: string): Omit<AgentDeviceCapabilityProfile, 'contractFingerprint'> {
+  // When command help cannot be parsed, fall back only for versions whose
+  // concrete CLI contracts were inspected. A broad semver range is not enough
+  // evidence for a pre-1.0 automation provider.
+  const supported = REVIEWED_FALLBACK_VERSIONS.has(version);
+  if (!supported) {
+    return {
+      version,
+      versionSupported: false,
+      source: 'unsupported',
+      global: {},
+      snapshot: {},
+      press: { supported: false },
+      fill: { supported: false },
+      batch: { supported: false },
+      keyboard: { returnSupported: false, dismissSupported: false },
+    };
+  }
+  // Verified against the installed 0.19.3 and 0.20.2 help surfaces. Keep this
+  // conservative: only capabilities used by the deterministic provider path.
+  return {
+    version,
+    versionSupported: true,
+    source: 'known-version',
+    global: { costFlag: '--cost' },
+    snapshot: {
+      interactiveFlag: '-i',
+      depthFlag: '--depth',
+      scopeFlag: '--scope',
+      rawFlag: '--raw',
+      forceFullFlag: '--force-full',
+    },
+    press: {
+      supported: true,
+      settleFlag: '--settle',
+    },
+    fill: {
+      supported: true,
+      settleFlag: '--settle',
+      delayFlag: '--delay-ms',
+      verifyFlag: '--verify',
+    },
+    batch: {
+      supported: true,
+      stepsFlag: '--steps',
+      onErrorFlag: '--on-error',
+      maxStepsFlag: '--max-steps',
+    },
+    keyboard: { returnSupported: true, dismissSupported: true },
+  };
+}
+
+export function detectAgentDeviceCapabilities(
+  version: string,
+  help: AgentDeviceHelpContract = {},
+): AgentDeviceCapabilityProfile {
+  const fallback = knownVersionProfile(version);
+  const combinedHelp = Object.values(help).filter(Boolean).join('\n');
+  const helpLooksUsable = /agent-device\s+(snapshot|press|fill|batch|keyboard)/.test(combinedHelp);
+  const profile: Omit<AgentDeviceCapabilityProfile, 'contractFingerprint'> = !helpLooksUsable
+    ? fallback
+    : {
+      version,
+      versionSupported: isSupportedAgentDeviceVersion(version),
+      source: isSupportedAgentDeviceVersion(version) ? 'help' : 'unsupported',
+      global: {
+        ...(includesFlag(help.root, '--cost') ? { costFlag: '--cost' as const } : {}),
+      },
+      snapshot: {
+        ...(includesFlag(help.snapshot, '-i') ? { interactiveFlag: '-i' as const } : {}),
+        ...(includesFlag(help.snapshot, '--depth') || includesFlag(help.snapshot, '-d') ? { depthFlag: '--depth' as const } : {}),
+        ...(includesFlag(help.snapshot, '--scope') || includesFlag(help.snapshot, '-s') ? { scopeFlag: '--scope' as const } : {}),
+        ...(includesFlag(help.snapshot, '--raw') ? { rawFlag: '--raw' as const } : {}),
+        ...(includesFlag(help.snapshot, '--force-full') ? { forceFullFlag: '--force-full' as const } : {}),
+      },
+      press: {
+        supported: /agent-device\s+press/.test(help.press ?? ''),
+        ...(includesFlag(help.press, '--settle') ? { settleFlag: '--settle' as const } : {}),
+      },
+      fill: {
+        supported: /agent-device\s+fill/.test(help.fill ?? ''),
+        ...(includesFlag(help.fill, '--settle') ? { settleFlag: '--settle' as const } : {}),
+        ...(includesFlag(help.fill, '--delay-ms') ? { delayFlag: '--delay-ms' as const } : {}),
+        ...(includesFlag(help.fill, '--verify') ? { verifyFlag: '--verify' as const } : {}),
+      },
+      batch: {
+        supported: /agent-device\s+batch/.test(help.batch ?? ''),
+        ...(includesFlag(help.batch, '--steps') ? { stepsFlag: '--steps' as const } : {}),
+        ...(includesFlag(help.batch, '--on-error') ? { onErrorFlag: '--on-error' as const } : {}),
+        ...(includesFlag(help.batch, '--max-steps') ? { maxStepsFlag: '--max-steps' as const } : {}),
+      },
+      keyboard: {
+        returnSupported: includesWord(help.keyboard, 'return') || includesWord(help.keyboard, 'enter'),
+        dismissSupported: includesWord(help.keyboard, 'dismiss'),
+      },
+    };
+
+  const fingerprintInput = JSON.stringify({ version, help, profile });
+  return {
+    ...profile,
+    contractFingerprint: createHash('sha256').update(fingerprintInput).digest('hex'),
+  };
+}
+
+export function compileSnapshotCommand(
+  profile: AgentDeviceCapabilityProfile,
+  options: SnapshotCommandOptions = {},
+): string[] {
+  const args = ['snapshot'];
+  if (options.interactiveOnly) {
+    if (!profile.snapshot.interactiveFlag) throw new Error('agent-device snapshot interactive mode is unsupported by the detected contract.');
+    args.push(profile.snapshot.interactiveFlag);
+  }
+  if (options.raw) {
+    if (!profile.snapshot.rawFlag) throw new Error('agent-device raw snapshots are unsupported by the detected contract.');
+    args.push(profile.snapshot.rawFlag);
+  }
+  if (typeof options.depth === 'number') {
+    if (!profile.snapshot.depthFlag) throw new Error('agent-device snapshot depth is unsupported by the detected contract.');
+    args.push(profile.snapshot.depthFlag, String(Math.max(1, Math.min(20, Math.trunc(options.depth)))));
+  }
+  if (options.scope) {
+    if (!profile.snapshot.scopeFlag) throw new Error('agent-device scoped snapshots are unsupported by the detected contract.');
+    args.push(profile.snapshot.scopeFlag, options.scope);
+  }
+  if (options.forceFull) {
+    if (!profile.snapshot.forceFullFlag) throw new Error('agent-device force-full snapshots are unsupported by the detected contract.');
+    args.push(profile.snapshot.forceFullFlag);
+  }
+  return args;
+}
+
+
+export function compileBatchCommand(
+  profile: AgentDeviceCapabilityProfile,
+  steps: Array<{ command: string; input: Record<string, unknown> }>,
+  maxSteps: number,
+  options: { includeCost?: boolean } = {},
+): string[] {
+  if (!profile.batch.supported || !profile.batch.stepsFlag) {
+    throw new Error('agent-device native batch execution is unsupported by the detected contract.');
+  }
+  const args = ['batch', profile.batch.stepsFlag, JSON.stringify(steps)];
+  if (profile.batch.onErrorFlag) args.push(profile.batch.onErrorFlag, 'stop');
+  if (profile.batch.maxStepsFlag) args.push(profile.batch.maxStepsFlag, String(maxSteps));
+  if (options.includeCost && profile.global.costFlag) args.push(profile.global.costFlag);
+  return args;
+}
+
+export function appendSettleFlag(
+  profile: AgentDeviceCapabilityProfile,
+  args: string[],
+  operation: 'fill' | 'press' = 'fill',
+): string[] {
+  const flag = operation === 'press' ? profile.press.settleFlag : profile.fill.settleFlag;
+  return flag ? [...args, flag] : [...args];
+}

package/src/runtime/plugins/ios/agent-device-failures.ts

@@ -0,0 +1,95 @@
+import { AssistantPluginError, toAssistantPluginError } from '../errors';
+
+export type AgentDeviceSessionFailureDisposition = 'preserve_session' | 'terminate_session' | 'fence_unknown';
+
+export interface AgentDeviceFailureClassification {
+  disposition: AgentDeviceSessionFailureDisposition;
+  providerCode?: string;
+  reason: string;
+}
+
+const PRESERVE_CODES = new Set([
+  'ELEMENT_NOT_FOUND',
+  'NO_SUCH_ELEMENT',
+  'STALE_REF',
+  'INVALID_SELECTOR',
+  'INVALID_ARGS',
+  'UNSUPPORTED_OPERATION',
+  'WAIT_TIMEOUT',
+  'ASSERTION_FAILED',
+  'ELEMENT_NOT_EDITABLE',
+  'ELEMENT_NOT_HITTABLE',
+  'TARGET_NOT_INTERACTABLE',
+  'TYPE_FAILED',
+]);
+
+const TERMINATE_CODES = new Set([
+  'SESSION_NOT_FOUND',
+  'RUNNER_DISCONNECTED',
+  'RUNNER_NOT_READY',
+  'TRANSPORT_ERROR',
+  'DAEMON_UNAVAILABLE',
+  'DEVICE_DISCONNECTED',
+  'XCTEST_UNAVAILABLE',
+]);
+
+function detailString(value: unknown): string {
+  try {
+    return JSON.stringify(value ?? {});
+  } catch {
+    return '';
+  }
+}
+
+export function classifyAgentDeviceFailure(error: unknown): AgentDeviceFailureClassification {
+  const normalized = toAssistantPluginError(error, {
+    code: 'AGENT_DEVICE_COMMAND_FAILED',
+    message: 'The agent-device command failed.',
+    retryable: false,
+  });
+  const details = normalized.details && typeof normalized.details === 'object'
+    ? normalized.details as Record<string, unknown>
+    : {};
+  const providerCode = typeof details.providerCode === 'string'
+    ? details.providerCode
+    : typeof details.code === 'string'
+      ? details.code
+      : undefined;
+  if (providerCode && PRESERVE_CODES.has(providerCode)) {
+    return { disposition: 'preserve_session', providerCode, reason: `provider:${providerCode}` };
+  }
+  if (providerCode && TERMINATE_CODES.has(providerCode)) {
+    return { disposition: 'terminate_session', providerCode, reason: `provider:${providerCode}` };
+  }
+
+  const evidence = `${normalized.code}\n${normalized.message}\n${detailString(normalized.details)}`;
+  if (/(?:stale\s+ref|element\s+not\s+found|no\s+such\s+element|invalid\s+selector|unsupported\s+operation|not\s+editable|not\s+hittable|not\s+interactable|cannot\s+type|failed\s+to\s+type|failed\s+to\s+fill|target\s+(?:is\s+)?covered|target\s+(?:is\s+)?disabled)/i.test(evidence)
+    && !/(?:runner|transport|connection|socket|daemon|xctest|dtx|device\s+disconnect)/i.test(evidence)) {
+    return { disposition: 'preserve_session', providerCode, reason: 'recoverable_semantic_failure' };
+  }
+  if (/(?:runner|transport|connection\s+(?:refused|lost|closed)|socket|daemon\s+unavailable|xctest|dtx|device\s+disconnect|broken\s+pipe|session\s+not\s+found)/i.test(evidence)) {
+    return { disposition: 'terminate_session', providerCode, reason: 'provider_or_transport_failure' };
+  }
+  if (normalized.code === 'AGENT_DEVICE_COMMAND_TIMEOUT' || normalized.code === 'AGENT_DEVICE_COMMAND_CANCELLED') {
+    return { disposition: 'fence_unknown', providerCode, reason: 'unknown_mutation_outcome' };
+  }
+  // A provider that returns a concrete failure has supplied a terminal outcome,
+  // even if its error code is not yet normalized. Unknown is reserved for a
+  // dispatched command whose completion evidence was lost.
+  return { disposition: 'terminate_session', providerCode, reason: 'unclassified_provider_failure' };
+}
+
+export function preserveSessionFailure(error: unknown): never {
+  const normalized = toAssistantPluginError(error, {
+    code: 'AGENT_DEVICE_COMMAND_FAILED',
+    message: 'The agent-device command failed.',
+    retryable: false,
+  });
+  throw new AssistantPluginError(normalized.code, normalized.message, {
+    retryable: normalized.retryable,
+    details: {
+      ...(normalized.details && typeof normalized.details === 'object' ? normalized.details as Record<string, unknown> : {}),
+      sessionPreserved: true,
+    },
+  });
+}

package/src/runtime/plugins/ios/agent-device-provider.ts

@@ -0,0 +1,63 @@
+export type AgentDeviceBackendMode = 'auto' | 'typed' | 'cli';
+export type AgentDeviceBackendKind = 'typed' | 'cli';
+
+export interface AgentDeviceProviderIdentity {
+  kind: AgentDeviceBackendKind;
+  available: boolean;
+  version?: string;
+  resolvedModule?: string;
+  runtimeVersion?: string;
+  minimumRuntimeVersion?: string;
+  reason?: string;
+}
+
+export interface AgentDeviceSessionContext {
+  stateDir: string;
+  session: string;
+  device: string;
+  platform: 'ios';
+  requestId: string;
+  cwd: string;
+  timeoutMs: number;
+}
+
+export interface AgentDeviceSnapshotRequest {
+  interactiveOnly?: boolean;
+  depth?: number;
+  scope?: string;
+  raw?: boolean;
+  forceFull?: boolean;
+}
+
+export interface AgentDeviceSnapshotEnvelope {
+  success: true;
+  data: Record<string, unknown>;
+  provider: AgentDeviceBackendKind;
+}
+
+export interface AgentDeviceReadProvider {
+  readonly identity: AgentDeviceProviderIdentity;
+  snapshot(
+    context: AgentDeviceSessionContext,
+    request: AgentDeviceSnapshotRequest,
+  ): Promise<AgentDeviceSnapshotEnvelope>;
+}
+
+export function configuredAgentDeviceBackendMode(
+  value = process.env.FORGE_AGENT_DEVICE_BACKEND,
+): AgentDeviceBackendMode {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized || normalized === 'auto') return 'auto';
+  if (normalized === 'typed' || normalized === 'cli') return normalized;
+  return 'auto';
+}
+
+export function agentDeviceProviderVersionsMatch(
+  typedVersion: string | undefined,
+  cliVersion: string | undefined,
+): boolean {
+  const normalize = (value: string | undefined) => value?.trim().replace(/^v/i, '');
+  const typed = normalize(typedVersion);
+  const cli = normalize(cliVersion);
+  return Boolean(typed && cli && typed === cli);
+}