@phone-use/sdk 0.4.0 → 0.5.0

package/src/backends/cloud-sandbox.ts

@@ -42,7 +42,18 @@ export type SandboxRpcMethod =
   | 'back'
   | 'openApp'
   | 'listApps'
-  | 'closeSession';
+  | 'closeSession'
+  | 'checkpoint'
+  | 'restoreCheckpoint'
+  | 'listCheckpoints'
+  | 'deleteCheckpoint';
+
+/** One saved device state, as reported by the worker. */
+export type SandboxCheckpointInfo = {
+  id: string;
+  label?: string | undefined;
+  createdAt: string;
+};
 
 /** Body of `POST <endpoint>/rpc`: one verb and its positional arguments. */
 export type SandboxRpcRequest = { method: SandboxRpcMethod; args: unknown[] };
@@ -162,6 +173,36 @@ export class CloudSandboxBackend extends BaseDeviceBackend {
     return this.rpc('closeSession');
   }
 
+  // -------------------------------------------------------------------------
+  // Checkpoints: save/restore the WHOLE device state (apps, logins, photos,
+  // settings). Not a UI snapshot — see `snapshot` for the accessibility tree.
+  // The device is briefly unavailable while a checkpoint saves or restores
+  // (shutdown → clone → boot on the worker); verbs issued meanwhile fail and
+  // should be retried after the checkpoint call resolves.
+  // -------------------------------------------------------------------------
+
+  /** Save the device's current state. Returns the checkpoint's id. */
+  checkpoint(opts?: { label?: string }): Promise<SandboxCheckpointInfo> {
+    return this.rpc('checkpoint', opts);
+  }
+
+  /** Restore a checkpoint by id or label. The checkpoint survives — restore as
+   * often as needed. Device identity may change server-side; the sandbox
+   * endpoint/token stay valid. */
+  restoreCheckpoint(ref: string): Promise<{ checkpointId: string }> {
+    return this.rpc('restoreCheckpoint', ref);
+  }
+
+  /** List this sandbox's checkpoints. */
+  listCheckpoints(): Promise<SandboxCheckpointInfo[]> {
+    return this.rpc('listCheckpoints');
+  }
+
+  /** Delete a checkpoint by id or label. */
+  deleteCheckpoint(ref: string): Promise<{ deleted: boolean }> {
+    return this.rpc('deleteCheckpoint', ref);
+  }
+
   /** Upload a zipped .app bundle (base64) and install it on the sandbox device. */
   /**
    * Upload a zipped .app as a raw stream. Prefer this over {@link installApp}:
@@ -186,9 +227,7 @@ export class CloudSandboxBackend extends BaseDeviceBackend {
       const bytes = await zip.arrayBuffer();
       return this.installApp(Buffer.from(bytes).toString('base64'));
     }
-    const body = (await response.json().catch(() => ({}))) as
-      | SandboxRpcResponse
-      | { error?: string };
+    const body = (await response.json().catch(() => ({}))) as SandboxRpcResponse | { error?: string };
     if (!response.ok || !('ok' in body)) {
       const message =
         ('error' in body && typeof body.error === 'string' ? body.error : undefined) ??

package/src/index.ts

@@ -1,13 +1,13 @@
 /**
  * @phone-use/sdk — the device runtime SDK: engine-as-object lifecycle
- * (ios.launch/connect → Device), Device backends, config, errors, capabilities,
+ * (ios.launch/connect and android.launch/connect → Device), Device backends, config, errors, capabilities,
  * and the action verb surface.
  *
  * 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.4.0';
+export const VERSION = '0.5.0';
 
 export {
   type Action,
@@ -31,10 +31,23 @@ export {
   registerBackend,
 } from './backend.ts';
 export { createAgentDeviceBackend } from './backends/agent-device.ts';
+export {
+  AndroidBackend,
+  type AndroidBackendOptions,
+  type AndroidConnectOptions,
+  type AndroidDeviceInfo,
+  type AndroidLaunchOptions,
+  type AndroidListOptions,
+  android,
+  type BinaryExecRunner,
+  createAndroidBackend,
+  type EmulatorProcess,
+} from './backends/android.ts';
 export {
   CloudSandboxBackend,
   type CloudSandboxBackendOptions,
   createCloudSandboxBackend,
+  type SandboxCheckpointInfo,
   type SandboxRpcFailure,
   type SandboxRpcMethod,
   type SandboxRpcRequest,
@@ -97,5 +110,7 @@ export { SecretStore } from './secrets.ts';
 // 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';
+import { createAndroidBackend as _createAndroid } from './backends/android.ts';
 
 _register('agent-device', _createAd);
+_register('android-adb', _createAndroid);

package/src/lifecycle.ts

@@ -21,8 +21,8 @@ export type DeviceStatus = 'running' | 'closed';
 /**
  * The Device lifecycle handle: id, pinned backend, close/dispose, idle lease +
  * reaper — plus the action verb surface layered onto the same type.
- * `ios.launch()` and `ios.connect()` return it; the future android engine will
- * share `createDeviceHandle`.
+ * `ios.launch()`/`ios.connect()` and `android.launch()`/`android.connect()`
+ * all return it, built over `createDeviceHandle`.
  */
 export interface Device {
   /** udid (iOS) / serial (Android). */
@@ -177,7 +177,7 @@ export type CreateDeviceHandleOptions = {
 
 /**
  * Assemble a Device handle over a backend: lease/reaper, verb surface,
- * close/dispose semantics. Engine authors (ios here, android in item 7b,
+ * close/dispose semantics. Engine authors (ios and android here,
  * phone-backend-* third parties) build on this; tests fabricate devices with
  * it over a FakeBackend.
  */

package/src/observe.ts

@@ -94,6 +94,8 @@ function keptViewportNodes(nodes: SnapshotNode[]): {
   kept: SnapshotNode[];
   above: number;
   below: number;
+  aboveNames: string[];
+  belowNames: string[];
   suppressFocused: boolean;
   vw: number;
 } {
@@ -109,23 +111,47 @@ function keptViewportNodes(nodes: SnapshotNode[]): {
   const kept: SnapshotNode[] = [];
   let above = 0;
   let below = 0;
+  // Name the actionable controls hiding off-screen instead of only counting
+  // them. Measured failure (AndroidWorld MarkorCreateNote): the create-note
+  // FAB sat below the fold, the render said only "[9 elements below]", and the
+  // agent burned its whole budget guessing labels (`tap "+"`) for a button it
+  // was never told existed. Tappable roles only, capped, so a long list view
+  // doesn't flood the render with row labels.
+  const aboveNames: string[] = [];
+  const belowNames: string[] = [];
+  const controlName = (n: SnapshotNode): string | undefined => {
+    const role = n.role ?? n.type ?? '';
+    if (!TAPPABLE.has(role) || role === 'StaticText' || role === 'Cell') return undefined;
+    const label = (n.label ?? n.identifier ?? '').trim();
+    return label || undefined;
+  };
   for (const n of nodes) {
     if (isNoise(n)) continue;
     if (!intersectsViewport(n.rect, vw, vh)) {
-      if (n.rect && n.rect.y >= vh) below += 1;
-      else above += 1;
+      const name = controlName(n);
+      if (n.rect && n.rect.y >= vh) {
+        below += 1;
+        if (name && belowNames.length < 5 && !belowNames.includes(name)) belowNames.push(name);
+      } else {
+        above += 1;
+        if (name && aboveNames.length < 5 && !aboveNames.includes(name)) aboveNames.push(name);
+      }
       continue;
     }
     kept.push(n);
   }
-  return { kept, above, below, suppressFocused, vw };
+  return { kept, above, below, aboveNames, belowNames, suppressFocused, vw };
 }
 
 function compressNodes(nodes: SnapshotNode[]): string {
-  const { kept, above, below, suppressFocused, vw } = keptViewportNodes(nodes);
+  const { kept, above, below, aboveNames, belowNames, suppressFocused, vw } = keptViewportNodes(nodes);
   const lines = kept.map((n) => formatNode(n, { suppressFocused, vw }));
-  if (above > 0) lines.unshift(`[${above} elements above the viewport — scroll up to reach them]`);
-  if (below > 0) lines.push(`[${below} elements below the viewport — scroll down to reach them]`);
+  const controls = (names: string[]) =>
+    names.length ? ` — controls there: ${names.map((n) => `"${n}"`).join(', ')}` : '';
+  if (above > 0)
+    lines.unshift(`[${above} elements above the viewport — scroll up to reach them${controls(aboveNames)}]`);
+  if (below > 0)
+    lines.push(`[${below} elements below the viewport — scroll down to reach them${controls(belowNames)}]`);
   return lines.join('\n');
 }
 
@@ -458,7 +484,9 @@ export class DeviceCore {
    */
   renderObservation(full = false): string {
     const app = this.lastApp.app;
-    const { kept, above, below, suppressFocused, vw } = keptViewportNodes(this.cachedNodes);
+    const { kept, above, below, aboveNames, belowNames, suppressFocused, vw } = keptViewportNodes(
+      this.cachedNodes,
+    );
     const keys = kept.map(elementKey);
     const lineByKey = new Map<string, string>();
     for (const n of kept) lineByKey.set(elementKey(n), formatNode(n, { suppressFocused, vw }));
@@ -489,8 +517,14 @@ export class DeviceCore {
     // Full render + refresh the baseline.
     this.lastRender = { app, keys, lineByKey };
     const lines = kept.map((n) => formatNode(n, { suppressFocused, vw }));
-    if (above > 0) lines.unshift(`[${above} elements above the viewport — scroll up to reach them]`);
-    if (below > 0) lines.push(`[${below} elements below the viewport — scroll down to reach them]`);
+    const controls = (names: string[]) =>
+      names.length ? ` — controls there: ${names.map((n) => `"${n}"`).join(', ')}` : '';
+    if (above > 0)
+      lines.unshift(
+        `[${above} elements above the viewport — scroll up to reach them${controls(aboveNames)}]`,
+      );
+    if (below > 0)
+      lines.push(`[${below} elements below the viewport — scroll down to reach them${controls(belowNames)}]`);
     return lines.join('\n');
   }