agent-device 0.12.8 → 0.12.9

package/dist/src/index.d.ts

@@ -414,7 +414,7 @@ export declare class AppError extends Error {
     constructor(code: AppErrorCode, message: string, details?: AppErrorDetails, cause?: unknown);
 }
 
-export declare type AppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'NOT_IMPLEMENTED' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'UNKNOWN';
+export declare type AppErrorCode = KnownAppErrorCode | (string & {});
 
 declare type AppErrorDetails = Record<string, unknown> & {
     hint?: string;
@@ -1053,6 +1053,7 @@ export declare type CaptureScreenshotOptions = AgentDeviceRequestOverrides & {
     path?: string;
     overlayRefs?: boolean;
     fullscreen?: boolean;
+    maxSize?: number;
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';
 };
 
@@ -1082,6 +1083,8 @@ export declare type CaptureSnapshotResult = {
 
 export declare function centerOfRect(rect: Rect): Point;
 
+declare type ClickButton = 'primary' | 'secondary' | 'middle';
+
 declare type ClickCommandOptions = PressCommandOptions;
 
 export declare type ClickOptions = ClientCommandBaseOptions & SelectorSnapshotCommandOptions & InteractionTarget & RepeatedPressOptions & {
@@ -1645,8 +1648,6 @@ declare type FindBaseOptions = ClientCommandBaseOptions & FindSnapshotCommandOpt
 
 export declare type FindLocator = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
 
-declare type FindLocator_2 = 'any' | 'text' | 'label' | 'value' | 'role' | 'id';
-
 export declare type FindOptions = (FindBaseOptions & {
     action?: 'click' | 'focus' | 'exists' | 'getText' | 'getAttrs';
 }) | (FindBaseOptions & {
@@ -1658,7 +1659,7 @@ export declare type FindOptions = (FindBaseOptions & {
 });
 
 declare type FindReadCommandOptions = CommandContext & {
-    locator?: FindLocator_2;
+    locator?: FindLocator;
     query: string;
     action: Extract<FindAction['kind'], 'exists' | 'wait' | 'get_text' | 'get_attrs'>;
     timeoutMs?: number;
@@ -1796,6 +1797,8 @@ export declare type KeyboardCommandResult = DaemonResponseData & {
     attempts?: number;
 };
 
+declare type KnownAppErrorCode = 'INVALID_ARGS' | 'DEVICE_NOT_FOUND' | 'DEVICE_IN_USE' | 'TOOL_MISSING' | 'APP_NOT_INSTALLED' | 'UNSUPPORTED_PLATFORM' | 'UNSUPPORTED_OPERATION' | 'NOT_IMPLEMENTED' | 'COMMAND_FAILED' | 'SESSION_NOT_FOUND' | 'UNAUTHORIZED' | 'AMBIGUOUS_MATCH' | 'UNKNOWN';
+
 declare type Lease = {
     leaseId: string;
     tenantId: string;
@@ -1899,19 +1902,21 @@ declare type MetroBridgeResult = {
     };
 };
 
+declare type MetroBridgeScope = {
+    tenantId: string;
+    runId: string;
+    leaseId: string;
+};
+
 declare type MetroPrepareKind = 'auto' | 'react-native' | 'expo';
 
 export declare type MetroPrepareOptions = {
     projectRoot?: string;
     kind?: MetroPrepareKind;
-    publicBaseUrl: string;
+    publicBaseUrl?: string;
     proxyBaseUrl?: string;
     bearerToken?: string;
-    bridgeScope?: {
-        tenantId: string;
-        runId: string;
-        leaseId: string;
-    };
+    bridgeScope?: MetroBridgeScope;
     launchUrl?: string;
     companionProfileKey?: string;
     companionConsumerKey?: string;
@@ -2030,7 +2035,7 @@ declare type PrepareMetroRuntimeResult = {
 
 declare type PressCommandOptions = CommandContext & {
     target: InteractionTarget_2;
-    button?: 'primary' | 'secondary' | 'middle';
+    button?: ClickButton;
     count?: number;
     intervalMs?: number;
     holdMs?: number;
@@ -2244,6 +2249,7 @@ declare type ScreenshotCommandOptions = CommandContext & {
     out?: FileOutputRef;
     fullscreen?: boolean;
     overlayRefs?: boolean;
+    maxSize?: number;
     appId?: string;
     appBundleId?: string;
     surface?: 'app' | 'frontmost-app' | 'desktop' | 'menubar';

package/dist/src/metro.d.ts

@@ -11,11 +11,7 @@ export declare type EnsureMetroTunnelOptions = {
     serverBaseUrl: string;
     bearerToken: string;
     localBaseUrl: string;
-    bridgeScope: {
-        tenantId: string;
-        runId: string;
-        leaseId: string;
-    };
+    bridgeScope: MetroBridgeScope;
     launchUrl?: string;
     profileKey?: string;
     consumerKey?: string;
@@ -79,6 +75,12 @@ export declare type MetroBridgeRuntimePayload = {
     launch_url?: string;
 };
 
+declare type MetroBridgeScope = {
+    tenantId: string;
+    runId: string;
+    leaseId: string;
+};
+
 /** Re-export of {@link SessionRuntimeHints} under the Metro-specific alias used by public API consumers. */
 export declare type MetroRuntimeHints = SessionRuntimeHints;
 
@@ -157,14 +159,10 @@ export declare function prepareRemoteMetro(options: PrepareRemoteMetroOptions):
 export declare type PrepareRemoteMetroOptions = {
     projectRoot: string;
     kind: 'auto' | 'react-native' | 'expo';
-    publicBaseUrl: string;
+    publicBaseUrl?: string;
     proxyBaseUrl?: string;
     proxyBearerToken?: string;
-    bridgeScope?: {
-        tenantId: string;
-        runId: string;
-        leaseId: string;
-    };
+    bridgeScope?: MetroBridgeScope;
     launchUrl?: string;
     profileKey?: string;
     consumerKey?: string;

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "agent-device",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
+  "homepage": "https://agent-device.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/callstackincubator/agent-device.git"
+  },
+  "bugs": {
+    "url": "https://github.com/callstackincubator/agent-device/issues"
+  },
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

package/skills/agent-device/references/exploration.md

@@ -338,6 +338,7 @@ Common batch error categories:
 - `SESSION_NOT_FOUND`: open or select the correct session, then retry.
 - `UNSUPPORTED_OPERATION`: switch to a supported command or surface.
 - `AMBIGUOUS_MATCH`: refine the selector or locator, then retry the failed step.
+- `DEVICE_IN_USE`: the device is held by another session — close or reuse the existing session before retrying.
 - `COMMAND_FAILED`: add sync guards and retry from the failing step.
 
 ## Stop conditions

package/skills/agent-device/references/remote-tenancy.md

@@ -103,8 +103,8 @@ Example `remote-config.json` shape:
   "tenant": "acme",
   "runId": "run-123",
   "sessionIsolation": "tenant",
-  "platform": "android",
-  "metroPublicBaseUrl": "http://127.0.0.1:8081"
+  "platform": "ios",
+  "metroProxyBaseUrl": "https://bridge.example.com"
 }
 ```
 
@@ -112,11 +112,11 @@ Optional overrides stay available for advanced cases:
 
 ```json
 {
-  "session": "adc-android",
-  "leaseBackend": "android-instance",
+  "session": "adc-ios",
+  "leaseBackend": "ios-instance",
   "metroProjectRoot": ".",
   "metroKind": "expo",
-  "metroProxyBaseUrl": "https://bridge.example.com/metro/acme/run-123"
+  "metroPublicBaseUrl": "http://127.0.0.1:8081"
 }
 ```
 
@@ -124,7 +124,10 @@ Optional overrides stay available for advanced cases:
 - Omit Metro fields for non-React Native flows.
 - Put `tenant`, `runId`, and `sessionIsolation` in the remote profile so agents can run `agent-device connect --remote-config ./remote-config.json` without extra scope flags. Add `platform`, `leaseBackend`, `session`, or Metro overrides only when the default inference is not enough for that flow.
 - Explicit command-line flags override connected defaults. Use them intentionally when switching session, platform, target, tenant, run, or lease scope.
-- For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally.
+- For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally. `metroProxyBaseUrl` is the bridge origin, not a prebuilt `/api/metro/...` route.
+- For cloud stock React Native iOS, use the bridge descriptor's wildcard HTTPS Metro hints directly; do not install or launch the XCTest runner just to make Metro reachable.
+- Android keeps using bridge-provided `/api/metro/runtimes/<runtimeId>/...` Metro routes.
+- `metroPublicBaseUrl` is only needed for direct/non-bridge bundle hints. Bridged profiles can omit it.
 - Use a lease backend that matches the bridge target platform, for example `android-instance`, `ios-instance`, or an explicit `--lease-backend` override.
 
 ## Transport prerequisites

package/skills/agent-device/references/verification.md

@@ -46,7 +46,10 @@ agent-device diff snapshot -i
 
 Use `screenshot` when the proof needs a rendered image instead of a structural tree.
 
+- Add `--max-size 1024` when a full-resolution screenshot is too large for an agent, model, or chat attachment.
 - Add `--overlay-refs` when you want the saved PNG to show fresh `@eN` refs burned into the screenshot.
+- Combine them as `screenshot /tmp/proof.png --max-size 1024 --overlay-refs` when you need a smaller visual proof that still includes tappable refs.
+- Avoid very small `--max-size` values when text, icons, or labels need to remain readable.
 
 ## Visual regression with diff screenshot