@phone-use/sdk 0.1.0

package/src/config.ts

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// Device configuration: a discriminated union, never a stringly-typed
+// capability blob (docs/19 §Backend contract, learning from Appium's leaks).
+// Field names verified against agent-device 0.19.3's AgentDeviceSelectionOptions
+// and AgentDeviceClientConfig. Plain types — no zod in the SDK public API
+// (docs/20 risk 6).
+// ---------------------------------------------------------------------------
+
+/** Fields shared by every platform's device config (session/daemon pinning). */
+export type CommonDeviceConfig = {
+  /** agent-device session name pinning. */
+  session?: string | undefined;
+  /** Remote daemon endpoint (API surface reserved; local-only this cycle). */
+  daemonBaseUrl?: string | undefined;
+  daemonAuthToken?: string | undefined;
+};
+
+/** iOS device selection: pin by udid, name match, or custom device set. */
+export type IosDeviceConfig = CommonDeviceConfig & {
+  platform: 'ios';
+  /** Pin a specific simulator/device by udid. */
+  udid?: string | undefined;
+  /** Name match, e.g. "iPhone 16". */
+  device?: string | undefined;
+  /** Custom simulator device set directory. */
+  simulatorDeviceSet?: string | undefined;
+};
+
+/** Android device selection: pin by adb serial or name match. */
+export type AndroidDeviceConfig = CommonDeviceConfig & {
+  platform: 'android';
+  /** Pin a specific device/emulator by adb serial. */
+  serial?: string | undefined;
+  /** Name match. */
+  device?: string | undefined;
+};
+
+/**
+ * Device configuration: a discriminated union on `platform`, never a
+ * stringly-typed capability blob (docs/19 §Backend contract, learning from
+ * Appium's leaks). Plain types — no zod in the SDK public API.
+ */
+export type DeviceConfig = IosDeviceConfig | AndroidDeviceConfig;

package/src/device.ts

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// Shared device types — the SDK's own vocabulary, structurally compatible with
+// agent-device's snapshot nodes but never importing its types (docs/20 item 2:
+// no backend type in the public API). Every optional is `| undefined` so
+// narrower backend types assign structurally under exactOptionalPropertyTypes.
+// ---------------------------------------------------------------------------
+
+/** Element geometry in screen points (same space as screenshot pixels at @1x). */
+export type Rect = { x: number; y: number; width: number; height: number };
+
+/**
+ * One accessibility-tree node as reported by a backend snapshot. The SDK's own
+ * vocabulary — structurally compatible with agent-device's nodes but never
+ * importing its types (docs/20 item 2: no backend type in the public API).
+ */
+export type SnapshotNode = {
+  ref?: string | undefined;
+  type?: string | undefined;
+  role?: string | undefined;
+  label?: string | undefined;
+  value?: string | undefined;
+  identifier?: string | undefined;
+  enabled?: boolean | undefined;
+  selected?: boolean | undefined;
+  focused?: boolean | undefined;
+  interactionBlocked?: string | undefined;
+  rect?: Rect | undefined;
+};
+
+/** One backend snapshot: the node list plus the frontmost app when known. */
+export type Snapshot = {
+  nodes: SnapshotNode[];
+  appName?: string | undefined;
+  appBundleId?: string | undefined;
+};
+
+/** Scroll gesture direction. */
+export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+
+/** A press target: an element ref from a snapshot, or raw screen coordinates. */
+export type PressTarget = { ref: string } | { x: number; y: number };
+
+/** What to do with a system alert: read it, accept it, or dismiss it. */
+export type AlertAction = 'get' | 'accept' | 'dismiss';
+
+/** Raw result of a backend's system-alert command. */
+export type BackendAlertResult = {
+  alert?:
+    | { title?: string | undefined; message?: string | undefined; buttons?: string[] | undefined }
+    | null
+    | undefined;
+  handled?: boolean | undefined;
+  button?: string | undefined;
+};
+
+/** What a backend reports after opening an app or URL. */
+export type OpenAppResult = { appName?: string | undefined; appBundleId?: string | undefined };
+
+/** A backend feature a caller can query via `backend.capabilities`. */
+export type Capability =
+  | 'snapshot'
+  | 'screenshot'
+  | 'press'
+  | 'longPress'
+  | 'fill'
+  | 'type'
+  | 'key'
+  | 'scroll'
+  | 'pan'
+  | 'waitForText'
+  | 'alert'
+  | 'home'
+  | 'back'
+  | 'openApp'
+  | 'openUrl'
+  | 'listApps'
+  | 'closeSession';
+
+/** Every capability — what a full backend (agent-device iOS) declares. */
+export const ALL_CAPABILITIES: readonly Capability[] = [
+  'snapshot',
+  'screenshot',
+  'press',
+  'longPress',
+  'fill',
+  'type',
+  'key',
+  'scroll',
+  'pan',
+  'waitForText',
+  'alert',
+  'home',
+  'back',
+  'openApp',
+  'openUrl',
+  'listApps',
+  'closeSession',
+];

package/src/errors.ts

@@ -0,0 +1,177 @@
+import { isAgentDeviceError } from 'agent-device';
+
+/**
+ * Stable machine-readable error codes carried by every {@link PhoneUseError}.
+ *
+ * Codes are deliberately string-identical to agent-device's where a concept
+ * maps 1:1 (DEVICE_NOT_FOUND, SESSION_NOT_FOUND, ...) so existing harness
+ * checks like `(e as {code?: string}).code === 'SESSION_NOT_FOUND'` keep
+ * working unchanged across the normalization boundary.
+ */
+export type PhoneUseErrorCode =
+  | 'DEVICE_NOT_FOUND'
+  | 'DEVICE_IN_USE'
+  | 'SESSION_NOT_FOUND'
+  | 'TIMEOUT'
+  | 'ACTION_FAILED'
+  | 'UNSUPPORTED_CAPABILITY'
+  | 'BACKEND_NOT_FOUND'
+  | 'ABORTED'
+  | 'UNKNOWN';
+
+/** Structured, code-specific context attached to a {@link PhoneUseError}. */
+export type PhoneUseErrorDetails = Record<string, unknown> & {
+  /** Preserved from agent-device details.hint — describeError renders it. */
+  hint?: string | undefined;
+  /** The raw backend code when we collapse to ACTION_FAILED. */
+  backendCode?: string | undefined;
+};
+
+/**
+ * Root of the typed error tree (docs/19 §Artifacts, errors; docs/20 item 2).
+ * Every backend method rejects only with PhoneUseError subclasses; agent-device
+ * (or any transport) errors are normalized at the boundary by
+ * {@link toPhoneUseError} so no backend type ever reaches the public API. Each
+ * error carries a stable `code` and an explicit `retryable` flag — the field
+ * agent loops need to decide retry-vs-replan.
+ */
+export class PhoneUseError extends Error {
+  /** Stable machine-readable code — the field to branch on. */
+  readonly code: PhoneUseErrorCode;
+  /** Whether retrying the same call can plausibly succeed. */
+  readonly retryable: boolean;
+  /** Optional structured context (hint, raw backend code, ...). */
+  readonly details?: PhoneUseErrorDetails | undefined;
+
+  constructor(
+    message: string,
+    opts: {
+      code: PhoneUseErrorCode;
+      retryable: boolean;
+      details?: PhoneUseErrorDetails | undefined;
+      cause?: unknown;
+    },
+  ) {
+    super(message, opts.cause === undefined ? undefined : { cause: opts.cause });
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.retryable = opts.retryable;
+    this.details = opts.details;
+  }
+}
+
+/** No device matched the selection (`DEVICE_NOT_FOUND`, not retryable). */
+export class DeviceNotFoundError extends PhoneUseError {
+  constructor(message: string, opts: { details?: PhoneUseErrorDetails | undefined; cause?: unknown } = {}) {
+    super(message, { code: 'DEVICE_NOT_FOUND', retryable: false, ...opts });
+  }
+}
+
+/** The device is held by another session (`DEVICE_IN_USE`, retryable). */
+export class DeviceInUseError extends PhoneUseError {
+  constructor(message: string, opts: { details?: PhoneUseErrorDetails | undefined; cause?: unknown } = {}) {
+    super(message, { code: 'DEVICE_IN_USE', retryable: true, ...opts });
+  }
+}
+
+/** No live session — the device/session was closed (`SESSION_NOT_FOUND`, not retryable). */
+export class SessionNotFoundError extends PhoneUseError {
+  constructor(message: string, opts: { details?: PhoneUseErrorDetails | undefined; cause?: unknown } = {}) {
+    super(message, { code: 'SESSION_NOT_FOUND', retryable: false, ...opts });
+  }
+}
+
+/** A deadline elapsed before the operation completed (`TIMEOUT`, retryable). */
+export class TimeoutError extends PhoneUseError {
+  constructor(message: string, opts: { details?: PhoneUseErrorDetails | undefined; cause?: unknown } = {}) {
+    super(message, { code: 'TIMEOUT', retryable: true, ...opts });
+  }
+}
+
+/** A device action failed to execute (`ACTION_FAILED`, retryable). */
+export class ActionFailedError extends PhoneUseError {
+  constructor(message: string, opts: { details?: PhoneUseErrorDetails | undefined; cause?: unknown } = {}) {
+    super(message, { code: 'ACTION_FAILED', retryable: true, ...opts });
+  }
+}
+
+/** The backend does not implement the capability (`UNSUPPORTED_CAPABILITY`, not retryable). */
+export class UnsupportedCapabilityError extends PhoneUseError {
+  /** The backend that rejected the call. */
+  readonly backend: string;
+  /** The missing capability. */
+  readonly capability: string;
+
+  constructor(opts: { backend: string; capability: string; cause?: unknown }) {
+    super(`backend "${opts.backend}" does not support "${opts.capability}"`, {
+      code: 'UNSUPPORTED_CAPABILITY',
+      retryable: false,
+      details: { backend: opts.backend, capability: opts.capability },
+      ...(opts.cause === undefined ? {} : { cause: opts.cause }),
+    });
+    this.backend = opts.backend;
+    this.capability = opts.capability;
+  }
+}
+
+/**
+ * The caller's AbortSignal fired (`ABORTED`, not retryable). Abort is caller
+ * control flow, not a device outcome — never retried.
+ */
+export class AbortedError extends PhoneUseError {
+  constructor(message = 'aborted by caller', opts: { cause?: unknown } = {}) {
+    super(message, { code: 'ABORTED', retryable: false, ...opts });
+  }
+}
+
+const TIMEOUT_RE = /\btime[d ]?\s?out\b|\btimeout\b/i;
+
+/**
+ * Boundary normalizer: ANY thrown value → PhoneUseError. agent-device AppError
+ * codes map per the table below; an existing PhoneUseError passes through
+ * untouched; unknown values wrap as UNKNOWN (not retryable). The original
+ * error always rides on `cause`; details (including hint) are preserved.
+ */
+export function toPhoneUseError(
+  err: unknown,
+  ctx: { backend?: string; capability?: string } = {},
+): PhoneUseError {
+  if (err instanceof PhoneUseError) return err;
+
+  if (isAgentDeviceError(err)) {
+    const e = err as Error & { code?: string; details?: Record<string, unknown> };
+    const message = e.message || String(e.code ?? 'agent-device error');
+    const details: PhoneUseErrorDetails = { ...(e.details ?? {}) };
+    const opts = { details, cause: err };
+    // Timeout is a shape, not a code, in agent-device — heuristic on message.
+    // Flagged in docs/20: Mac verification is the arbiter for this mapping.
+    if (TIMEOUT_RE.test(message)) return new TimeoutError(message, opts);
+    switch (e.code) {
+      case 'DEVICE_NOT_FOUND':
+        return new DeviceNotFoundError(message, opts);
+      case 'DEVICE_IN_USE':
+        return new DeviceInUseError(message, opts);
+      case 'SESSION_NOT_FOUND':
+        return new SessionNotFoundError(message, opts);
+      case 'UNSUPPORTED_PLATFORM':
+      case 'UNSUPPORTED_OPERATION':
+      case 'NOT_IMPLEMENTED':
+        return new UnsupportedCapabilityError({
+          backend: ctx.backend ?? 'unknown',
+          capability: ctx.capability ?? String(e.code),
+          cause: err,
+        });
+      default:
+        return new ActionFailedError(message, {
+          details: { ...details, backendCode: e.code === undefined ? undefined : String(e.code) },
+          cause: err,
+        });
+    }
+  }
+
+  if (err instanceof Error) {
+    if (TIMEOUT_RE.test(err.message)) return new TimeoutError(err.message, { cause: err });
+    return new PhoneUseError(err.message, { code: 'UNKNOWN', retryable: false, cause: err });
+  }
+  return new PhoneUseError(String(err), { code: 'UNKNOWN', retryable: false, cause: err });
+}

package/src/exec.ts

@@ -0,0 +1,48 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+/** Per-call options an {@link ExecRunner} accepts. */
+export type ExecOptions = {
+  /** Kill the process after this many ms (rejects in the killed shape). */
+  timeoutMs?: number | undefined;
+  /** Replacement environment for the child process. */
+  env?: Record<string, string> | undefined;
+};
+
+/** What an {@link ExecRunner} resolves with on exit 0. */
+export type ExecResult = { stdout: string; stderr: string };
+
+/**
+ * The process-execution seam (docs/19: dependency-inject the spawn/exec runner
+ * so unit tests run without the real binaries). Runners are dumb: resolve on
+ * exit 0, reject with the execFile error shape otherwise — error normalization
+ * to PhoneUseError happens at the call site, once.
+ */
+export type ExecRunner = (file: string, args: string[], opts?: ExecOptions) => Promise<ExecResult>;
+
+const pExecFile = promisify(execFile);
+
+export const defaultExecRunner: ExecRunner = async (file, args, opts) => {
+  const { stdout, stderr } = await pExecFile(file, args, {
+    encoding: 'utf8',
+    // simctl `list devices -j` on a runtime-rich Mac can exceed the 1 MiB
+    // default and fail spuriously — a failure the VPS test tier can never see.
+    maxBuffer: 16 * 1024 * 1024,
+    ...(opts?.timeoutMs === undefined ? {} : { timeout: opts.timeoutMs }),
+    ...(opts?.env === undefined ? {} : { env: opts.env }),
+  });
+  return { stdout, stderr };
+};
+
+/** The execFile rejection shape runners produce (structural, for call sites). */
+export type ExecError = Error & {
+  code?: number | string | undefined;
+  stdout?: string | undefined;
+  stderr?: string | undefined;
+  killed?: boolean | undefined;
+  signal?: string | undefined;
+};
+
+export function isExecError(err: unknown): err is ExecError {
+  return err instanceof Error && ('code' in err || 'killed' in err || 'stderr' in err);
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * @phone-use/sdk — the device runtime SDK: engine-as-object lifecycle
+ * (ios.launch/connect → Device), Device backends, config, errors, capabilities
+ * (docs/20-runtime-sdk-v1-plan.md items 2-3; action verbs land in item 4).
+ *
+ * The test double (FakeBackend) lives on the "@phone-use/sdk/testing" subpath,
+ * deliberately not re-exported here.
+ */
+/** The published package version (kept in sync with package.json by the release flow). */
+export const VERSION = '0.1.0';
+
+export {
+  type Action,
+  type ActionResult,
+  type ActionVerb,
+  type ActOptions,
+  buildObserveResult,
+  type CompiledSkill,
+  type ElementQuery,
+  executeAction,
+  type ObservedElement,
+  type ObserveResult,
+  toActions,
+} from './actions.ts';
+export {
+  type BackendFactory,
+  BaseDeviceBackend,
+  type DeviceBackend,
+  getBackendFactory,
+  listBackends,
+  registerBackend,
+} from './backend.ts';
+export { createAgentDeviceBackend } from './backends/agent-device.ts';
+export { type IosConnectOptions, type IosLaunchOptions, ios } from './backends/ios.ts';
+export type { AndroidDeviceConfig, CommonDeviceConfig, DeviceConfig, IosDeviceConfig } from './config.ts';
+export type {
+  AlertAction,
+  BackendAlertResult,
+  Capability,
+  OpenAppResult,
+  PressTarget,
+  Rect,
+  ScrollDirection,
+  Snapshot,
+  SnapshotNode,
+} from './device.ts';
+export { ALL_CAPABILITIES } from './device.ts';
+export {
+  AbortedError,
+  ActionFailedError,
+  DeviceInUseError,
+  DeviceNotFoundError,
+  PhoneUseError,
+  type PhoneUseErrorCode,
+  type PhoneUseErrorDetails,
+  SessionNotFoundError,
+  TimeoutError,
+  toPhoneUseError,
+  UnsupportedCapabilityError,
+} from './errors.ts';
+export {
+  type CreateDeviceHandleOptions,
+  createDeviceHandle,
+  type Device,
+  type DevicePlatform,
+  type DeviceStatus,
+} from './lifecycle.ts';
+export type {
+  ActionEvidence,
+  AlertOutcome,
+  Observation,
+  RenderState,
+  Resolution,
+  ResolveOpts,
+  UiElement,
+} from './observe.ts';
+export { DeviceCore, describeError, labelMatches, matchInElements } from './observe.ts';
+export { SecretStore } from './secrets.ts';
+
+// Built-in backend registration — explicit, here, so importing the barrel
+// registers it (documented; sideEffects:false refers to bundler tree-shaking
+// of the *published* dist, where the barrel is the entry).
+import { registerBackend as _register } from './backend.ts';
+import { createAgentDeviceBackend as _createAd } from './backends/agent-device.ts';
+
+_register('agent-device', _createAd);