@limrun/api 0.48.3 → 0.49.0

package/src/exec-client.ts

@@ -96,6 +96,7 @@ export type XcodeBuildExecRequest = {
     apiKeyId: string;
     apiIssuerId: string;
     apiPrivateKeyBase64: string;
+    entitlements?: Record<string, string>;
   };
   /** Wire name retained for compatibility with the limbuild exec API. */
   testflight?: AppStoreUploadConfig;

package/src/index.ts

@@ -8,6 +8,50 @@ export { Limrun, type ClientOptions } from './client';
 export { PagePromise } from './core/pagination';
 export * from './instance-client';
 export * as Ios from './ios-client';
+export {
+  isTerminalDestinationTunnelError,
+  type DestinationTcpTunnel,
+  type DestinationTcpTunnelOptions,
+} from './destination-tunnel-dialer';
+export {
+  decodeDestinationTunnelInspectionSSEEvent,
+  deriveDestinationTunnelInspectionURL,
+  startDestinationTunnelInspectionStream,
+  type DestinationTunnelInspectionBodyEvent,
+  type DestinationTunnelInspectionComplete,
+  type DestinationTunnelInspectionErrorCallback,
+  type DestinationTunnelInspectionEvent,
+  type DestinationTunnelInspectionEventCallback,
+  type DestinationTunnelInspectionExtension,
+  type DestinationTunnelInspectionGap,
+  type DestinationTunnelInspectionMetadataEvent,
+  type DestinationTunnelInspectionStream,
+  type DestinationTunnelInspectionStreamOptions,
+} from './destination-tunnel-inspection';
+export {
+  DestinationTunnelHARAssembler,
+  type DestinationTunnelHAREntry,
+  type DestinationTunnelHARExtension,
+} from './destination-tunnel-har';
+export {
+  validateDestinationTunnelSelectors,
+  normalizeDestinationTunnelInspection,
+  disabledDestinationTunnelInspection,
+  destinationTunnelConfigHash,
+  DestinationTunnelSelectorError,
+  DESTINATION_TUNNEL_DEFAULT_MAX_BODY_BYTES,
+  DESTINATION_TUNNEL_DEFAULT_TTL_SECONDS,
+  DESTINATION_TUNNEL_DEFAULT_WINDOW,
+  DESTINATION_TUNNEL_MAX_BODY_BYTES,
+  DESTINATION_TUNNEL_MAX_TTL_SECONDS,
+  type DestinationTunnelInspectionConfig,
+  type DestinationTunnelTransportRequest,
+  type DestinationTunnelTransportResult,
+  type DestinationTunnelSelectors,
+  type DestinationTunnelSelectorReport,
+  type DestinationTunnelSelectorErrorCode,
+  type DestinationTunnelBindReport,
+} from './destination-tunnel';
 export {
   startHttpProxy,
   startForwardHttpProxy,
@@ -87,6 +131,14 @@ export {
   type GradleBuildLog,
 } from './resources/gradle-instances-helpers';
 export { type AssetUploadOptions } from './resources/daemon-client-shared';
+export {
+  type SessionArtifact,
+  type SessionArtifactKind,
+  type SessionLogLine,
+  type SessionEvent,
+  type SessionEventType,
+} from './resources/session-artifacts';
+export { SessionStreamLostError } from './internal/session-stream';
 export {
   LIMRUN_DIR,
   TRY_IMPORT_LINE,

package/src/instance-client.ts

@@ -11,10 +11,45 @@ import { nodeProxyTransport } from './internal/proxy-transport';
 import { startTcpTunnel, isNonRetryableError } from './tunnel';
 import type { Tunnel } from './tunnel';
 import { syncFolder, type FolderSyncOptions, type SyncFolderResult } from './folder-sync';
+import { startDestinationTcpTunnel, type DestinationTcpTunnel } from './destination-tunnel-dialer';
+import type { DestinationTunnelInspectionConfig, DestinationTunnelSelectors } from './destination-tunnel';
+import type {
+  DestinationTunnelInspectionErrorCallback,
+  DestinationTunnelInspectionEventCallback,
+} from './destination-tunnel-inspection';
+import {
+  getDestinationTunnelStatus,
+  stopDestinationTunnel,
+  type DestinationTunnelStatus,
+} from './internal/destination-tunnel-management';
+import { deriveDestinationTunnelURL } from './internal/destination-tunnel-url';
+import { persistFields, type PersistOption } from './internal/persist-option';
+import { streamSessionEntries } from './internal/session-stream';
+import type { SessionLogLine, SessionEvent } from './resources/session-artifacts';
+
+export { type PersistOption } from './internal/persist-option';
 
 const ANDROID_RECORDING_PATH = '/data/local/tmp/recordings/video_recording.mp4';
 const ANDROID_SIGNALING_PATH = '/ws';
 
+/** Transparent destination tunnel from the Android instance to this machine. */
+export type DestinationTunnel = DestinationTcpTunnel;
+export type DestinationTunnelOptions = {
+  /** Exact endpoint and domain selector values interpreted by the Android tunnel server. */
+  selectors: DestinationTunnelSelectors;
+  /** Inspection settings negotiated with the Android tunnel server. */
+  inspection?: Partial<DestinationTunnelInspectionConfig>;
+  /** Called for each validated inspection metadata or body event. */
+  onInspectionEvent?: DestinationTunnelInspectionEventCallback;
+  /** Called when the independent inspection stream fails or reconnects. */
+  onInspectionError?: DestinationTunnelInspectionErrorCallback;
+  /** Per-flow receive window in bytes. Defaults to 1 MiB. */
+  window?: number;
+  /** Controls tunnel logging verbosity. Defaults to the instance client's log level. */
+  logLevel?: LogLevel;
+};
+export type { DestinationTunnelStatus } from './internal/destination-tunnel-management';
+
 /**
  * Connection state of the instance client
  */
@@ -134,6 +169,12 @@ export type InstanceClient = {
    * @param packageName Package name of the app to terminate
    */
   terminateApp: (packageName: string) => Promise<void>;
+  /**
+   * List the launchable apps installed on the instance, each with its package
+   * name (as `bundleId`), display name, install type (`user` or `system`),
+   * and, when available, a small base64 PNG icon.
+   */
+  listApps: () => Promise<InstalledApp[]>;
   /**
    * Watch an app's exit/crash without launching it through {@link launchApp},
    * e.g. for apps that are already running or will be opened via a deeplink
@@ -246,8 +287,11 @@ export type InstanceClient = {
    * Start recording device video. Use stopRecording() to finish the recording.
    * When provided, `quality` must be one of `5`, `6`, `7`, `8`, `9`, or `10`.
    * The server default is `5`.
+   * With `persist`, the completed recording is uploaded to Limrun's bucket
+   * when the recording stops or the instance terminates; list it with
+   * `androidInstances.listRecordings`.
    */
-  startRecording: (options?: { quality?: RecordingQuality }) => Promise<void>;
+  startRecording: (options?: { quality?: RecordingQuality; persist?: PersistOption }) => Promise<void>;
   /**
    * Stop the active server-side recording.
    * If `saveTo.presignedUrl` is provided, the server uploads the completed file there before resolving.
@@ -255,6 +299,48 @@ export type InstanceClient = {
    * Returns a download URL for the completed recording.
    */
   stopRecording: (saveTo: { presignedUrl?: string; localPath?: string }) => Promise<string>;
+  /**
+   * Start capturing an app's logcat output (one JSONL object per line) for
+   * the given package name. One app log capture runs at a time; the server
+   * rejects a second start. With `persist`, the capture is uploaded to
+   * Limrun's bucket when it stops or the instance terminates; list it with
+   * `androidInstances.listAppLogs`.
+   */
+  startAppLogCapture: (options: { bundleId: string; persist?: PersistOption }) => Promise<void>;
+  /** Stop the active app log capture. */
+  stopAppLogCapture: () => Promise<void>;
+  /**
+   * Start capturing the coalesced event log of user and agent actions (one
+   * JSONL object per line). One event capture runs at a time; the server
+   * rejects a second start. With `persist`, the capture is uploaded to
+   * Limrun's bucket when it stops or the instance terminates; list it with
+   * `androidInstances.listEvents`.
+   */
+  startEventCapture: (options?: { persist?: PersistOption }) => Promise<void>;
+  /** Stop the active event capture. */
+  stopEventCapture: () => Promise<void>;
+  /**
+   * Tail the live app log stream fed by {@link startAppLogCapture}. On
+   * connect the instance replays its recent buffer (up to 1000 lines), then
+   * delivers lines as they are captured; a dropped connection reconnects
+   * and resumes exactly where it left off, so every line is delivered once.
+   * The stream is independent of this client's websocket and survives
+   * {@link disconnect}; `onError` fires at most once, after the stream has
+   * kept failing for several minutes (e.g. the instance was deleted), and
+   * the stream is closed. Returns a function that closes the stream.
+   */
+  streamAppLogCapture: (handlers: {
+    onLine: (line: SessionLogLine) => void;
+    onError?: (error: Error) => void;
+  }) => () => void;
+  /**
+   * Tail the live coalesced event log fed by {@link startEventCapture}.
+   * Same delivery and lifecycle semantics as {@link streamAppLogCapture}.
+   */
+  streamEventCapture: (handlers: {
+    onEvent: (event: SessionEvent) => void;
+    onError?: (error: Error) => void;
+  }) => () => void;
   /** Send an application-level keepAlive message on the control websocket. */
   keepAlive: () => void;
   /**
@@ -267,6 +353,22 @@ export type InstanceClient = {
    * Returns the local TCP port and a cleanup function.
    */
   startAdbTunnel: () => Promise<Tunnel>;
+
+  /**
+   * Transparently route declared Android TCP destinations through this
+   * machine. Exact `localhost` routes are also reachable on-device as
+   * `10.0.2.2:<port>`, following the emulator convention.
+   *
+   * The caller owns the returned tunnel and must close it. Disconnecting this
+   * instance client does not close the tunnel.
+   */
+  startTunnel: (options: DestinationTunnelOptions) => Promise<DestinationTunnel>;
+
+  /** Get the active destination tunnel and most recent terminal failure. */
+  getTunnelStatus: () => Promise<DestinationTunnelStatus>;
+
+  /** Stop the active destination tunnel only when its ID matches `tunnelId`. */
+  stopTunnel: (tunnelId: string) => Promise<void>;
   /**
    * Send an asset URL to the instance. The instance will download the asset
    * and process it (currently APK install is supported). Resolves on success,
@@ -517,6 +619,18 @@ export type LaunchAppResult = {
   packageName: string;
 };
 
+/**
+ * One entry of {@link InstanceClient.listApps}. The package name is carried
+ * as `bundleId` so the shape matches iOS's listApps.
+ */
+export type InstalledApp = {
+  bundleId: string;
+  name: string;
+  installType: string;
+  /** App icon as a base64-encoded 64px PNG; absent when the runtime could not extract one. */
+  icon?: string;
+};
+
 /** Handle for an app watch registered via {@link InstanceClient.watchApp}. */
 export type AppWatch = {
   /** Identifier of this watch on the server. */
@@ -703,6 +817,13 @@ type WatchAppResultMessage = {
   error?: CommandError;
 };
 
+type ListAppsResultMessage = {
+  type: 'listAppsResult';
+  id: string;
+  payload?: { apps?: InstalledApp[] };
+  error?: CommandError;
+};
+
 type UnwatchAppResultMessage = {
   type: 'unwatchAppResult';
   id: string;
@@ -770,6 +891,34 @@ type StopVideoRecordingResultMessage = {
   error?: CommandError;
 };
 
+type StartAppLogCaptureResultMessage = {
+  type: 'startAppLogCaptureResult';
+  id: string;
+  payload?: EmptyCommandResult;
+  error?: CommandError;
+};
+
+type StopAppLogCaptureResultMessage = {
+  type: 'stopAppLogCaptureResult';
+  id: string;
+  payload?: EmptyCommandResult;
+  error?: CommandError;
+};
+
+type StartEventCaptureResultMessage = {
+  type: 'startEventCaptureResult';
+  id: string;
+  payload?: EmptyCommandResult;
+  error?: CommandError;
+};
+
+type StopEventCaptureResultMessage = {
+  type: 'stopEventCaptureResult';
+  id: string;
+  payload?: EmptyCommandResult;
+  error?: CommandError;
+};
+
 type KnownCommandResultMessage =
   | ScreenshotResultMessage
   | GetElementTreeResultMessage
@@ -784,12 +933,17 @@ type KnownCommandResultMessage =
   | TerminateAppResultMessage
   | WatchAppResultMessage
   | UnwatchAppResultMessage
+  | ListAppsResultMessage
   | PlayOnMicrophoneResultMessage
   | CameraControlResultMessage
   | AdbShellResultMessage
   | SetWifiBandwidthResultMessage
   | StartVideoRecordingResultMessage
-  | StopVideoRecordingResultMessage;
+  | StopVideoRecordingResultMessage
+  | StartAppLogCaptureResultMessage
+  | StopAppLogCaptureResultMessage
+  | StartEventCaptureResultMessage
+  | StopEventCaptureResultMessage;
 
 type ServerMessage =
   | ScreenshotResponse
@@ -812,12 +966,17 @@ type CommandRequestMap = {
   terminateApp: { packageName: string };
   watchApp: { packageName: string; execId: string };
   unwatchApp: { execId: string };
+  listApps: {};
   playOnMicrophone: { path: string; once?: boolean };
   cameraControl: { action: 'setSource'; source: 'video'; arg: string; loop?: boolean } | { action: 'reset' };
   adbShell: { command: string; timeoutMs?: number };
   setWifiBandwidth: WifiBandwidthOptions;
-  startRecording: { quality?: RecordingQuality };
+  startRecording: { quality?: RecordingQuality; persist?: boolean; ttlSeconds?: number };
   stopRecording: { upload?: { presignedUrl: string } };
+  startAppLogCapture: { bundleId: string; persist?: boolean; ttlSeconds?: number };
+  stopAppLogCapture: {};
+  startEventCapture: { persist?: boolean; ttlSeconds?: number };
+  stopEventCapture: {};
 };
 
 type CommandResultMap = {
@@ -834,12 +993,17 @@ type CommandResultMap = {
   terminateApp: { packageName?: string };
   watchApp: { packageName?: string };
   unwatchApp: EmptyCommandResult;
+  listApps: { apps?: InstalledApp[] };
   playOnMicrophone: PlayOnMicrophoneResult;
   cameraControl: EmptyCommandResult;
   adbShell: AdbShellResultMessage;
   setWifiBandwidth: EmptyCommandResult;
   startRecording: EmptyCommandResult;
   stopRecording: EmptyCommandResult;
+  startAppLogCapture: EmptyCommandResult;
+  stopAppLogCapture: EmptyCommandResult;
+  startEventCapture: EmptyCommandResult;
+  stopEventCapture: EmptyCommandResult;
 };
 
 type PendingRequest<T> = {
@@ -1015,12 +1179,17 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         case 'terminateAppResult':
         case 'watchAppResult':
         case 'unwatchAppResult':
+        case 'listAppsResult':
         case 'playOnMicrophoneResult':
         case 'cameraControlResult':
         case 'adbShellResult':
         case 'setWifiBandwidthResult':
         case 'startRecordingResult':
         case 'stopRecordingResult':
+        case 'startAppLogCaptureResult':
+        case 'stopAppLogCaptureResult':
+        case 'startEventCaptureResult':
+        case 'stopEventCaptureResult':
           return 'id' in message && typeof message.id === 'string';
         default:
           return false;
@@ -1287,6 +1456,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             openUrl,
             launchApp,
             terminateApp,
+            listApps,
             watchApp,
             playOnMicrophone,
             pushFile,
@@ -1297,9 +1467,18 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             setWifiBandwidth,
             startRecording,
             stopRecording,
+            startAppLogCapture,
+            stopAppLogCapture,
+            startEventCapture,
+            stopEventCapture,
+            streamAppLogCapture,
+            streamEventCapture,
             keepAlive,
             disconnect,
             startAdbTunnel,
+            startTunnel,
+            getTunnelStatus,
+            stopTunnel,
             sendAsset,
             syncApp,
             getConnectionState,
@@ -1435,6 +1614,11 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       await sendRequest('terminateApp', { packageName });
     };
 
+    const listApps = async (): Promise<InstalledApp[]> => {
+      const result = await sendRequest('listApps', {});
+      return result.apps ?? [];
+    };
+
     const watchApp = async (packageName: string, onExit: LaunchAppExitCallback): Promise<AppWatch> => {
       const { execId } = await withExitCallback('watch', onExit, (execId) =>
         sendRequest('watchApp', { packageName, execId }),
@@ -1551,8 +1735,13 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       await sendRequest('setWifiBandwidth', request);
     };
 
-    const startRecording = async (recordingOptions?: { quality?: RecordingQuality }): Promise<void> => {
-      const request: CommandRequestMap['startRecording'] = {};
+    const startRecording = async (recordingOptions?: {
+      quality?: RecordingQuality;
+      persist?: PersistOption;
+    }): Promise<void> => {
+      const request: CommandRequestMap['startRecording'] = {
+        ...persistFields(recordingOptions?.persist),
+      };
       if (recordingOptions?.quality !== undefined) {
         if (
           !Number.isInteger(recordingOptions.quality) ||
@@ -1579,6 +1768,53 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return downloadUrl;
     };
 
+    const startAppLogCapture = async (captureOptions: {
+      bundleId: string;
+      persist?: PersistOption;
+    }): Promise<void> => {
+      if (!captureOptions.bundleId) {
+        throw new Error('bundleId must be a non-empty string');
+      }
+      await sendRequest('startAppLogCapture', {
+        bundleId: captureOptions.bundleId,
+        ...persistFields(captureOptions.persist),
+      });
+    };
+
+    const stopAppLogCapture = async (): Promise<void> => {
+      await sendRequest('stopAppLogCapture', {});
+    };
+
+    const startEventCapture = async (captureOptions?: { persist?: PersistOption }): Promise<void> => {
+      await sendRequest('startEventCapture', { ...persistFields(captureOptions?.persist) });
+    };
+
+    const stopEventCapture = async (): Promise<void> => {
+      await sendRequest('stopEventCapture', {});
+    };
+
+    const streamAppLogCapture = (handlers: {
+      onLine: (line: SessionLogLine) => void;
+      onError?: (error: Error) => void;
+    }): (() => void) =>
+      streamSessionEntries<SessionLogLine>({
+        url: `${options.apiUrl}/session/applogs/events`,
+        token: options.token,
+        onEntry: handlers.onLine,
+        onError: handlers.onError,
+      });
+
+    const streamEventCapture = (handlers: {
+      onEvent: (event: SessionEvent) => void;
+      onError?: (error: Error) => void;
+    }): (() => void) =>
+      streamSessionEntries<SessionEvent>({
+        url: `${options.apiUrl}/session/events/events`,
+        token: options.token,
+        onEntry: handlers.onEvent,
+        onError: handlers.onError,
+      });
+
     const keepAlive = (): void => {
       if (!ws || ws.readyState !== WebSocket.OPEN) {
         return;
@@ -1643,6 +1879,36 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return tunnel;
     };
 
+    const requireAdbUrl = (): string => {
+      if (!options.adbUrl) {
+        throw new Error('adbUrl is required to manage a destination tunnel.');
+      }
+      return options.adbUrl;
+    };
+
+    const startTunnel = async (tunnelOptions: DestinationTunnelOptions): Promise<DestinationTunnel> => {
+      return startDestinationTcpTunnel(deriveDestinationTunnelURL(requireAdbUrl()), options.token, {
+        selectors: tunnelOptions.selectors,
+        inspection: {
+          enabled: true,
+          captureBodies: false,
+          ...(tunnelOptions.inspection ?? {}),
+        },
+        ...(tunnelOptions.onInspectionEvent ? { onInspectionEvent: tunnelOptions.onInspectionEvent } : {}),
+        ...(tunnelOptions.onInspectionError ? { onInspectionError: tunnelOptions.onInspectionError } : {}),
+        ...(tunnelOptions.window === undefined ? {} : { window: tunnelOptions.window }),
+        logLevel: tunnelOptions.logLevel ?? logLevel,
+      });
+    };
+
+    const getTunnelStatus = async (): Promise<DestinationTunnelStatus> => {
+      return getDestinationTunnelStatus(requireAdbUrl(), options.token);
+    };
+
+    const stopTunnel = async (tunnelId: string): Promise<void> => {
+      await stopDestinationTunnel(requireAdbUrl(), options.token, tunnelId);
+    };
+
     const sendAsset = async (url: string, timeoutMs?: number): Promise<void> => {
       if (!ws || ws.readyState !== WebSocket.OPEN) {
         return Promise.reject(new Error('WebSocket is not connected or connection is not open.'));

package/src/internal/destination-tunnel-management.ts

@@ -1,12 +1,19 @@
 import { nodeProxyTransport } from './proxy-transport';
 import { deriveDestinationTunnelStatusURL, deriveDestinationTunnelStopURL } from './destination-tunnel-url';
-import { validateDestinationTunnelRoutes, type DestinationTunnelRoute } from '../destination-tunnel';
+import { readArray, readNonEmptyString, readRecord, readString } from './destination-tunnel-wire-reader';
+import {
+  normalizeDestinationTunnelInspection,
+  type DestinationTunnelBindReport,
+  type DestinationTunnelInspectionConfig,
+  type DestinationTunnelSelectorReport,
+} from '../destination-tunnel';
 
 export interface DestinationTunnelStatus {
   active?: {
     tunnelId: string;
     state: 'starting' | 'ready' | 'stopping';
-    routes: DestinationTunnelRoute[];
+    selectors: DestinationTunnelSelectorReport[];
+    inspection: DestinationTunnelInspectionConfig;
   };
   lastFailure?: {
     tunnelId: string;
@@ -15,7 +22,7 @@ export interface DestinationTunnelStatus {
   lastDialFailure?: {
     tunnelId: string;
     connectionId: number;
-    routeId: string;
+    selectorId: string;
     reason: string;
     osCode?: string;
   };
@@ -74,19 +81,67 @@ function readActiveTunnel(value: unknown): NonNullable<DestinationTunnelStatus['
   return {
     tunnelId: readNonEmptyString(active, 'tunnelId'),
     state,
-    routes: validateDestinationTunnelRoutes(readArray(active, 'routes').map(readTunnelRoute)),
+    selectors: readArray(active, 'selectors').map((selector, index) =>
+      readSelectorReport(selector, `selector-${index + 1}`),
+    ),
+    inspection: readInspection(active),
   };
 }
 
-function readTunnelRoute(value: unknown): DestinationTunnelRoute {
-  const route = readRecord(value, 'tunnel route');
-  const port = route['port'];
-  if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535) {
-    throw new Error('tunnel route port must be an integer from 1 to 65535');
+function readInspection(active: Record<string, unknown>): DestinationTunnelInspectionConfig {
+  const inspection = readRecord(active['inspection'], 'inspection');
+  const enabled = inspection['enabled'];
+  const captureBodies = inspection['captureBodies'];
+  const persist = inspection['persist'];
+  if (typeof enabled !== 'boolean' || typeof captureBodies !== 'boolean' || typeof persist !== 'boolean') {
+    throw new Error('inspection enabled, captureBodies, and persist must be booleans');
+  }
+  const maxBodyBytes = inspection['maxBodyBytes'];
+  const ttlSeconds = inspection['ttlSeconds'];
+  if (typeof maxBodyBytes !== 'number' || typeof ttlSeconds !== 'number') {
+    throw new Error('inspection maxBodyBytes and ttlSeconds must be numbers');
+  }
+  return normalizeDestinationTunnelInspection({
+    enabled,
+    captureBodies,
+    maxBodyBytes,
+    persist,
+    ttlSeconds,
+  });
+}
+
+function readSelectorReport(value: unknown, expectedId: string): DestinationTunnelSelectorReport {
+  const report = readRecord(value, 'tunnel selector');
+  const id = readNonEmptyString(report, 'id');
+  if (id !== expectedId) {
+    throw new Error(`invalid tunnel selector id ${id}`);
+  }
+  const kind = readString(report, 'kind');
+  if (kind !== 'route' && kind !== 'domain') {
+    throw new Error(`invalid tunnel selector kind ${kind}`);
+  }
+  return {
+    id,
+    kind,
+    value: readNonEmptyString(report, 'value'),
+    ...(report['binds'] === undefined ? {} : { binds: readArray(report, 'binds').map(readBindReport) }),
+  };
+}
+
+function readBindReport(value: unknown): DestinationTunnelBindReport {
+  const bind = readRecord(value, 'tunnel bind report');
+  const status = readString(bind, 'status');
+  if (status !== 'ok' && status !== 'conflict' && status !== 'error') {
+    throw new Error(`invalid tunnel bind status ${status}`);
+  }
+  const osCode = bind['osCode'];
+  if (osCode !== undefined && typeof osCode !== 'string') {
+    throw new Error('tunnel bind osCode must be a string');
   }
   return {
-    host: readNonEmptyString(route, 'host'),
-    port,
+    address: readNonEmptyString(bind, 'address'),
+    status,
+    ...(osCode === undefined ? {} : { osCode }),
   };
 }
 
@@ -116,39 +171,8 @@ function readTunnelDialFailure(value: unknown): NonNullable<DestinationTunnelSta
   return {
     tunnelId: readNonEmptyString(failure, 'tunnelId'),
     connectionId,
-    routeId: readNonEmptyString(failure, 'routeId'),
+    selectorId: readNonEmptyString(failure, 'selectorId'),
     reason: readNonEmptyString(failure, 'reason'),
     ...(osCode === undefined ? {} : { osCode }),
   };
 }
-
-function readRecord(value: unknown, name: string): Record<string, unknown> {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-    throw new Error(`${name} must be an object`);
-  }
-  return value as Record<string, unknown>;
-}
-
-function readArray(record: Record<string, unknown>, key: string): unknown[] {
-  const value = record[key];
-  if (!Array.isArray(value)) {
-    throw new Error(`${key} must be an array`);
-  }
-  return value;
-}
-
-function readString(record: Record<string, unknown>, key: string): string {
-  const value = record[key];
-  if (typeof value !== 'string') {
-    throw new Error(`${key} must be a string`);
-  }
-  return value;
-}
-
-function readNonEmptyString(record: Record<string, unknown>, key: string): string {
-  const value = readString(record, key);
-  if (value.length === 0) {
-    throw new Error(`${key} must not be empty`);
-  }
-  return value;
-}