From 2aa3e874c0662b4d479e4c38d0bda1e71b3360ac Mon Sep 17 00:00:00 2001 From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:39:42 -0800 Subject: [PATCH 1/2] chore(devices): bump agent-device to 0.21.41 and expo-device-hub to 0.26.1 Co-authored-by: Cursor --- .../workflows/mobile-showcase-screenshots.yml | 2 +- apps/server/src/device/AgentDeviceShim.ts | 9 ++++++++- apps/server/src/device/deviceToolVersions.json | 4 ++-- pnpm-lock.yaml | 16 ++++++++++++++-- scripts/package.json | 2 +- 5 files changed, 26 insertions(+), 7 deletions(-) diff --git a/.github/workflows/mobile-showcase-screenshots.yml b/.github/workflows/mobile-showcase-screenshots.yml index 402ff86445378..16a70a58aac0a 100644 --- a/.github/workflows/mobile-showcase-screenshots.yml +++ b/.github/workflows/mobile-showcase-screenshots.yml @@ -88,7 +88,7 @@ jobs: axe --version - name: Install foldable simulator controls - run: npm install --global agent-device@0.21.36 + run: npm install --global agent-device@0.21.41 - name: Capture iOS showcase run: pnpm screenshots:mobile --platform ios --appearance "${{ inputs.appearance }}" --theme "${{ inputs.theme }}" diff --git a/apps/server/src/device/AgentDeviceShim.ts b/apps/server/src/device/AgentDeviceShim.ts index e5b42557a1e10..60c26b0137d6f 100644 --- a/apps/server/src/device/AgentDeviceShim.ts +++ b/apps/server/src/device/AgentDeviceShim.ts @@ -12,7 +12,7 @@ const STALE_RUNTIME = const quoteShell = (value: string) => "'" + value.replaceAll("'", "'\"'\"'") + "'"; -/** agent-device 0.21.36's flags that take a value, so the launcher can find the command past them. */ +/** agent-device 0.21.41's flags that take a value, so the launcher can find the command past them. */ const VALUE_FLAGS: ReadonlyArray = [ "--activity", "--all", @@ -43,9 +43,13 @@ const VALUE_FLAGS: ReadonlyArray = [ "--delay-ms", "--depth", "--device", + "--device-baseline", + "--device-mode", "--device-orientation", "--dsym", "--duration-ms", + "-e", + "--env", "--fps", "--from", "--geo-location", @@ -85,6 +89,7 @@ const VALUE_FLAGS: ReadonlyArray = [ "--out", "--pattern", "--pause-ms", + "--pick", "--pixel-density", "--pixels", "--plan-digest", @@ -112,6 +117,7 @@ const VALUE_FLAGS: ReadonlyArray = [ "--provider-timezone", "--proxy-base-url", "--public-base-url", + "--public-origin", "--quality", "--record-as", "--remote-config", @@ -122,6 +128,7 @@ const VALUE_FLAGS: ReadonlyArray = [ "--run-id", "--runtime-file", "-s", + "--save-script", "--scale", "--scope", "--search-path", diff --git a/apps/server/src/device/deviceToolVersions.json b/apps/server/src/device/deviceToolVersions.json index ce61669b26573..4145899e9e762 100644 --- a/apps/server/src/device/deviceToolVersions.json +++ b/apps/server/src/device/deviceToolVersions.json @@ -1,4 +1,4 @@ { - "agent-device": "0.21.36", - "expo-device-hub": "0.22.1" + "agent-device": "0.21.41", + "expo-device-hub": "0.26.1" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 74ee6e28d7433..dbace4a52737f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2598,8 +2598,8 @@ importers: specifier: workspace:* version: link:../packages/tailscale agent-device: - specifier: 0.21.36 - version: 0.21.36 + specifier: 0.21.41 + version: 0.21.41 e2e: specifier: 0.23.0 version: 0.23.0 @@ -7919,6 +7919,16 @@ packages: ai: optional: true + agent-device@0.21.41: + resolution: {integrity: sha512-VQMYEXzcNBwCPLrWHDM0ic1pWD+GroWukj0jHCzS9zob9eeHSVYJTVSgydLaDn2c2aMH3NuCHr1vLvZ2Bgl7Uw==} + engines: {node: '>=22.12'} + hasBin: true + peerDependencies: + ai: ^6.0.0 || ^7.0.0 + peerDependenciesMeta: + ai: + optional: true + agent-install@0.0.5: resolution: {integrity: sha512-nHlms9BkP8ZiY79HrwCGiA2DcNaXrAaJrCM/BEqQ7MEsSKyCk+2A76xPGylIfASZSZE0SaU3T0bNSg4rBPIJAQ==} hasBin: true @@ -17949,6 +17959,8 @@ snapshots: agent-device@0.21.36: {} + agent-device@0.21.41: {} + agent-install@0.0.5: dependencies: '@iarna/toml': 2.2.5 diff --git a/scripts/package.json b/scripts/package.json index 9eb10db4c227e..223c91da44780 100644 --- a/scripts/package.json +++ b/scripts/package.json @@ -16,7 +16,7 @@ "@t3tools/contracts": "workspace:*", "@t3tools/shared": "workspace:*", "@t3tools/tailscale": "workspace:*", - "agent-device": "0.21.36", + "agent-device": "0.21.41", "e2e": "0.23.0", "effect": "catalog:", "playwright-core": "1.64.1", From d555147810ae90961240108a93e94979408b28c2 Mon Sep 17 00:00:00 2001 From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com> Date: Fri, 20 Nov 2026 19:55:00 -0800 Subject: [PATCH 2/2] chore(evals): regenerate agent-device-help.txt for 0.21.41 and drop optional-value --save-script from VALUE_FLAGS Co-authored-by: Cursor --- apps/server/src/device/AgentDeviceShim.ts | 1 - evals/mcp-tool-use/agent-device-help.txt | 43 +++++++++++++---------- 2 files changed, 25 insertions(+), 19 deletions(-) diff --git a/apps/server/src/device/AgentDeviceShim.ts b/apps/server/src/device/AgentDeviceShim.ts index 60c26b0137d6f..885775279b2ad 100644 --- a/apps/server/src/device/AgentDeviceShim.ts +++ b/apps/server/src/device/AgentDeviceShim.ts @@ -128,7 +128,6 @@ const VALUE_FLAGS: ReadonlyArray = [ "--run-id", "--runtime-file", "-s", - "--save-script", "--scale", "--scope", "--search-path", diff --git a/evals/mcp-tool-use/agent-device-help.txt b/evals/mcp-tool-use/agent-device-help.txt index 058f29b5bf6a1..17b4088d0594f 100644 --- a/evals/mcp-tool-use/agent-device-help.txt +++ b/evals/mcp-tool-use/agent-device-help.txt @@ -1,11 +1,11 @@ -agent-device 0.21.36 prints this help; apps/server/src/device/deviceToolVersions.json pins that version. Regenerate from +agent-device 0.21.41 prints this help; apps/server/src/device/deviceToolVersions.json pins that version. Regenerate from the repo root with: node scripts/node_modules/agent-device/bin/agent-device.mjs help [commands|record|screenshot|open|settings|fill] $ agent-device help agent-device [args] [--json] Automates iOS, Android, macOS, TV, and web apps for AI agents. -All 75 commands: agent-device help commands +All 76 commands: agent-device help commands Start: When starting a task with a known app, first run: @@ -22,13 +22,14 @@ Loop: acts, waits for quiet, and prints the UI diff. Continue from that diff. Run snapshot -i only when the diff lacks the next target or did not settle. Verify a named expectation with the diff, wait text "...", wait , wait absent , - is, get, or find. A bare screenshot is not verification. + is, or get. A bare screenshot is not verification. + find acts: it clicks by default. To check only, use find text "..." exists. End with: agent-device close Targets: Copy refs exactly: @e12, @e12~s4. Keep @ and any ~sN pin; refs go stale after mutations. A literal @handle is label="@handle", not a bare ref. - Prefer refs, then id/label/role selectors. Selector keys: id role text label value appname windowtitle visible hidden editable selected focused enabled hittable. + Prefer refs, then id/label/role selectors. Selector keys: id role text label value appname windowtitle visible hidden editable selected checked focused enabled hittable. Coordinates are last resort: after snapshot -i shows no semantic target, or a sparse/AX-unavailable warning says its refs and selectors are invalid. Then screenshot, press , and re-snapshot on the changed screen. @@ -49,24 +50,24 @@ More commands (exact shapes: agent-device help ): Guides (agent-device help ): workflow full refs, selectors, waits, recovery, and platform limits - manual-qa / dogfood / validate / debugging / scripting / gestures + manual-qa / dogfood / accessibility / validate / debugging / scripting / gestures react-native / react-devtools / cdp / tv / web / macos / remote physical-device / ios-system-ui / maestro foldable iPhone Duo panels, the fold command, and why refs die on a pose change - $ agent-device help commands -agent-device 0.21.36 — commands +agent-device 0.21.41 — commands Full command catalog. Use agent-device help for exact flags and behavior. Commands: - action-button Press the iPhone or iPad Action Button + action-button Press the iPhone, iPad, or Apple Watch Ultra Action Button alert [action] [timeout] Inspect, accept, or dismiss a platform alert app-switcher Open the device app switcher apps List installed apps or deferred provider app assets appstate Show the foreground app and activity artifacts [provider-session-id] List daemon or cloud provider session artifacts audio Probe audio levels + audit Report advisory accessibility findings auth Manage cloud login state back Navigate back in the app or system batch --steps | --steps-file Run multiple commands @@ -155,6 +156,7 @@ Global Flags: Configuration: Default config files: ~/.agent-device/config.json (or /config.json), ./agent-device.json (project-safe defaults only). Use --config or AGENT_DEVICE_CONFIG for explicit connection/provider defaults; project config cannot select endpoints or credentials. + Pin device selection with { "devicePin": { "platform": "ios", "device": "iPad Pro" } } in config. Conflicts name the config file. Edit or remove the pin there to target another device. Environment: AGENT_DEVICE_SESSION Explicit session name @@ -184,7 +186,7 @@ $ agent-device help record Usage: agent-device record start [path] [--scope ] [--fps ] [--quality ] [--hide-touches] | record stop | record contact-sheet [--out ] -Start or stop a screen recording for the active app session or, where supported, the selected device, or build a contact-sheet PNG from a recording already exported. Long Android recordings can return multiple video artifacts; HarmonyOS supports whole-screen recording on physical devices. The default --scope app requires an active app session from open ; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Android screenrecord encodes a frame only when the screen changes, so a clip can end at the last frame the recorder encoded instead of at record stop; durationMs is host wall clock from record start until the export finished, and capturedDurationMs reports the video timeline when it can be measured, with a warning naming how much of the window that video covers. An Android manifest left by an unreachable recording is retired on the next start once its recorders are proven gone; one still owned refuses with non-retriable DEVICE_IN_USE and reason native_recovery_evidence_open naming the session to run record stop for, and a recorder that is still writing an artifact refuses with DEVICE_IN_USE and reason native_recording_artifact_claimed, which clears itself once that recorder ends at the 180s limit. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends. The touch overlay renders at most 30 frames a second, or at --fps when lower; a lower --fps makes record stop faster on a long recording, and an overlay export that runs past its budget returns the raw video with an overlayWarning. An iOS simulator host recording lock returns non-retriable DEVICE_IN_USE with reason apple_simulator_recording_busy. Stop the recording in its owning session; if a dead recorder left the host locked, ask the host operator to restart the CoreSimulator stream service. A record stop that cannot produce its export keeps what a retry reads back — on Android the device-side artifact and the native manifest — leaves the recording manifest of that session open, and returns its own error, so retry record stop in that session; only closing the session disposes them. Every stopped recording also reports what became of its recorder and of the file that recorder writes to: recorder is confirmed, or lost when the session holding it died, and nativePathDisposition is retirable while that file still owes a removal or retired once its removal was verified. Both are optional disclosures, not failures; ADR 0024 declares further states (unconfirmed, pending) for the steps that gain those probes, and no stop reports them yet. record contact-sheet [--out ] is a local report over a file you already exported: it decodes frames out of that MP4 and writes one PNG holding the cells where the screen visibly changed, each labeled with its elapsed time on the clip timeline. It needs no session and no device, rebuilds any past recording, and works for every backend that exports MP4; a WebM recording is refused with reason contact_sheet_container_unsupported. The sample grid is bounded and spread across the whole clip, so it reports coverage rather than a review: a flash that opens and closes entirely between two sample times is not in the sheet, which is why the result also reports how many times it sampled and how many frames came back. Frame decoding is Apple AVFoundation tooling, so the command runs only on macOS hosts and refuses elsewhere with reason contact_sheet_unsupported_host. +Start or stop a screen recording for the active app session or, where supported, the selected device, or build a contact-sheet PNG from a recording already exported. Long Android recordings can return multiple video artifacts; HarmonyOS supports whole-screen recording on physical devices. MP4 verification setup starts in the background before recording output preparation, without delaying capture. If setup exceeds the stop budget, details.reason is video_validator_compile_timeout (retriable); run record stop again while setup continues. Hosts without xcrun keep container-only MP4 completion. Other compilation failures, or an unavailable validator executable or AVFoundation during verification, return video_validator_unavailable. A Swift helper cache that is not private to this user returns swift_cache_untrusted. When details.ancestor is the configured cache root or a directory above it that the group or other users can write, remove that write access (chmod g-w,o-w) from that directory. When it is v3 or a directory inside it (bin, home or module-cache), do not chmod it: that clears the refusal but keeps whatever was written while it was open. Set AGENT_DEVICE_SWIFT_CACHE_DIR to a new directory only you can write, or remove that directory yourself; agent-device never deletes it. When details.exposure is untrusted_developer_dir, the DEVELOPER_DIR selection is refused; it is checked only when a Swift helper compiles, and a cached helper is reused without checking it: restart the daemon with DEVELOPER_DIR unset, or set DEVELOPER_DIR to an empty value for one local command to select the system default, or point it at an Xcode Contents/Developer directory, given as an absolute path, that root or you own along with every directory above it. Repair the reported failure and retry record stop; a failed compile is retried on the next start or stop. The default --scope app requires an active app session from open ; use --scope device/system to explicitly request whole-screen recording where the selected backend supports it. Android record start publishes a durable device manifest, recordings longer than the 180s adb screenrecord limit are returned as multiple MP4 chunks while the daemon stays alive, and daemon-restart recovery uses only manifest-owned chunks. Android screenrecord encodes a frame only when the screen changes, so a clip can end at the last frame the recorder encoded instead of at record stop; durationMs is host wall clock from record start until the export finished, and capturedDurationMs reports the video timeline when it can be measured, with a warning naming how much of the window that video covers. An Android manifest left by an unreachable recording is retired on the next start once its recorders are proven gone; one still owned refuses with non-retriable DEVICE_IN_USE and reason native_recovery_evidence_open naming the session to run record stop for, and a recorder that is still writing an artifact refuses with DEVICE_IN_USE and reason native_recording_artifact_claimed, which clears itself once that recorder ends at the 180s limit. HarmonyOS supports whole-screen recording on physical devices only: use --scope device/system; --fps, --quality, and --hide-touches are unsupported. Use --quality to choose medium or high export quality on supported backends. The touch overlay renders at most 30 frames a second, or at --fps when lower; a lower --fps makes record stop faster on a long recording, and an overlay export that runs past its budget returns the raw video with an overlayWarning. An iOS simulator host recording lock returns non-retriable DEVICE_IN_USE with reason apple_simulator_recording_busy. Stop the recording in its owning session; if a dead recorder left the host locked, ask the host operator to restart the CoreSimulator stream service. On any backend, record start first settles the open recording records on its device that it would refuse on and whose session this daemon no longer holds: it finishes each one as its own record stop would, so the export lands at the output path of that recording and a later record stop in that session returns it, and runs the exact-owner recovery a daemon restart runs, which discards what that recording left, only for a record that cannot finish. A record it cannot confirm cleaned, or one whose session is still held, refuses the start with reason cleanup-unconfirmed and names that session: stop or close it, then retry. A record that another device left under the same session name is never settled from this device: the start refuses and names that device, so stop it in that session or record under another session name. A record stop that cannot produce its export keeps what a retry reads back — on Android the device-side artifact and the native manifest — leaves the recording manifest of that session open, and returns its own error, so retry record stop in that session; while this daemon holds that session, only closing it disposes them, and once it does not, the next record start on that device settles them as described above. Every stopped recording also reports what became of its recorder and of the file that recorder writes to: recorder is confirmed, or lost when the session holding it died, and nativePathDisposition is retirable while that file still owes a removal or retired once its removal was verified. Both are optional disclosures, not failures; ADR 0024 declares further states (unconfirmed, pending) for the steps that gain those probes, and no stop reports them yet. record contact-sheet [--out ] is a local report over a file you already exported: it decodes frames out of that MP4 and writes one PNG holding the cells where the screen visibly changed, each labeled with its elapsed time on the clip timeline. It needs no session and no device, rebuilds any past recording, and works for every backend that exports MP4; a WebM recording is refused with reason contact_sheet_container_unsupported. The sample grid is bounded and spread across the whole clip, so it reports coverage rather than a review: a flash that opens and closes entirely between two sample times is not in the sheet, which is why the result also reports how many times it sampled and how many frames came back. Frame decoding is Apple AVFoundation tooling, so the command runs only on macOS hosts and refuses elsewhere with reason contact_sheet_unsupported_host. Command flags: --fps Record: target frames per second (iOS physical device runner); also lowers the touch-overlay rate, which never exceeds 30 @@ -194,29 +196,33 @@ Command flags: --out Output path $ agent-device help screenshot Usage: - agent-device screenshot [path] [--out ] [--overlay-refs] [--crop-on ] [--pixel-density ] [--fullscreen, --full, -f] [--scale <0.01-1>] [--no-stabilize] [--normalize-status-bar] + agent-device screenshot [path] [--out ] [--overlay-refs] [--crop-on ] [--pixel-density ] [--screen-mask ] [--fullscreen, --full, -f] [--scale <0.01-1>] [--no-stabilize] [--normalize-status-bar] [--capture-backend runner] -Capture a screenshot of the active app or web session. Choose the capture scope, density, size, or annotations through the corresponding input fields when needed. Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, and CoreDevice physical iPhones), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing. +Capture a screenshot of the active app or web session. Input fields control capture scope, density, size, and annotations. Use it for visual evidence, or when a snapshot warns that the accessibility tree is sparse: read the image, then press by coordinates. A screenshot alone does not verify a result. Web defaults to the viewport; use --fullscreen, --full, or -f for the entire page. iOS simulators default to 1x logical-point output; use --pixel-density to request a different screenshot density. Use --screen-mask black to fill the iOS simulator screen outline, including rounded corners, with black for this capture. It requires simctl: physical devices, tvOS and visionOS simulators, other platforms, provider captures and XCTest runner captures are refused. A masked capture fails if simctl fails instead of falling back to an unmasked runner capture. macOS app sessions default to the app window; use --fullscreen for full desktop, --scale to downscale, --crop-on to crop the capture to the frame the selector resolves on the same screen (currently iOS simulators, Android emulators, CoreDevice physical iPhones, and Samsung Tizen and LG webOS TV apps), --overlay-refs to annotate current refs, --normalize-status-bar for deterministic iOS simulator or Android chrome. Physical iPhone crop verification covers portrait CoreDevice/devicectl captures only. XCTest, runner fallback, and physical iPad crops are refused; landscape iPhone crop is unverified. Android captures immediately by default; --normalize-status-bar also waits for transient UI to fade, and --no-stabilize keeps capture immediate. With the native macOS backend, the front window is the app's frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, as is the small indicator window macOS adds in front of a window that a screen-sharing stream captures, and a sheet is captured as its own window. On macOS, any --surface other than app (desktop, menubar, frontmost-app) always captures the main display and refuses an explicit --fullscreen. On single-display iOS simulators and Android devices, the result reports displayRotation, the rotation the display rendered the capture in, when the device returns a reading in time; otherwise the field is absent. On iOS simulators a screenshot waits for that simulator's status bar to be free, and a request its caller cancelled while it waits reports the cancellation instead of capturing. Command flags: --out Output path --overlay-refs Screenshot: draw current snapshot refs and target rectangles onto the saved PNG; diff screenshot: also write a separate current-screen overlay guide --crop-on Screenshot: crop the capture to the frame of the selector resolved on the same screen --pixel-density Screenshot: output PNG pixel density in pixels per logical point (currently supported on iOS simulators) + --screen-mask Screenshot or live screenshot diff: fill the iOS simulator screen outline with black; requires simctl capture --fullscreen, --full, -f Screenshot: on web capture the full page; on macOS app sessions capture the full desktop instead of the app window --scale <0.01-1> Screenshot: resize both dimensions by this factor (or use AGENT_DEVICE_SCREENSHOT_SCALE) --no-stabilize Screenshot: capture immediately without Android status-bar stabilization (the default) --normalize-status-bar Screenshot: temporarily normalize iOS simulator or ADB-backed Android status-bar chrome for deterministic screenshot diffs; ADB-backed Android waits for transient UI to fade + --capture-backend runner Screenshot: on Apple targets capture through the XCTest runner (XCUIScreen), which leaves out the simulator-drawn Dynamic Island, instead of simctl; refused on other platforms, provider sessions and macOS surfaces the helper captures, and with --pixel-density, --screen-mask and --normalize-status-bar $ agent-device help open Usage: - agent-device open [appOrUrl] [url] [--activity ] [--launch-console ] [--launch-args ] [--test-ime] [--no-test-ime] [--save-script [path]] [--force, --overwrite] [--no-record] [--relaunch] [--foreground] [--timeout ] [--wait ] [--surface app|frontmost-app|desktop|menubar] [--metro-host ] [--metro-port ] [--bundle-url ] [--launch-url ] [--os ] [--image-tag ] [--physical] + agent-device open [appOrUrl] [url] [--activity ] [--launch-console ] [--launch-args ] [--test-ime] [--no-test-ime] [--save-script [path]] [--force, --overwrite] [--no-record] [--relaunch] [--foreground] [--timeout ] [--wait ] [--surface app|frontmost-app|desktop|menubar] [--metro-host ] [--metro-port ] [--bundle-url ] [--launch-url ] [--os ] [--image-tag ] [--device-mode ] [--device-baseline ] [--physical] -Boot the selected device when needed, then open an app, deep link, or URL in a session. Use the app or URL inputs to choose what becomes the foreground automation target. Use --platform to bind URL/deep-link opens to the target platform. For local iOS simulator initial stdout/stderr, put --launch-console on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url choose the app's Metro server and save that address for later metro reload calls in the same session. A fresh open without Metro hints clears an older same-name binding; close also clears it. --launch-url supplies the app's launch URL; it does not select the reload server. On an iOS simulator without --launch-url, open connects a detected Expo development client through its expo-development-client URL. The app must declare a single exp+ scheme that no other installed app owns. If detection is inconclusive, the app opens normally. Bare React Native apps receive their server settings before launch. On an iOS simulator, when --launch-url raises an "Open in ?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if the scheme owner cannot be resolved because no single installed app owns it or the lookup failed, the prompt stays on screen and open returns with data.launchConfirmation: "unanswered", launchConfirmationReason url-owner-unresolved, and a warning; a prompt that is seen but not recognized is reported the same way with launchConfirmationReason alert-unrecognized and its own warning; for url-owner-unresolved, answer the prompt with alert accept; for alert-unrecognized, read the alert with alert get first, because it can be the app's own alert (such as a permission prompt) rather than the launch confirmation, and answer with alert accept only when it is the launch confirmation; when agent-device cannot read whether a prompt is up at all (the alert read, the accept, or the runner itself failed, including after a re-hand of the URL), open stays green, reports no launchConfirmation plus data.launchConfirmationProbeFailure naming the failed step (alert-read, alert-accept, or runner), and appends a warning that says to check with alert get. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app's target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. When the runner reports its main-thread timeout for the accept and the prompt is still up, open presses Open again, but only when the time the open request has left covers a whole press and the read that checks it. A recognized prompt still visible after a failed accept, or once that time is gone, also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. The prompt is recognized by the OS's own wording of its title and buttons in the Simulator's preferred languages; when the runner cannot read that wording, the prompt stays on screen as alert-unrecognized. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session. +Boot the selected device when needed, then open an app, deep link, or URL in a session. With a known app, start with open and foreground: a fresh open returns the initial interactive snapshot with refs (or initialSnapshotError: then run snapshot). Do not probe with devices or apps first; list them only for an unknown app id, and never guess one. The app or URL inputs select the foreground automation target. Remote daemons refuse file: URLs in open targets and launch URLs with reason REMOTE_HOST_INPUT_DENIED. Local web content is supported over HTTP(S). Use --platform to bind URL/deep-link opens to the target platform. For local or Limrun iOS simulator initial stdout/stderr, put --launch-console on this open command, for example agent-device open "Agent Device Tester" --platform ios --launch-console artifacts/launch-console.log. Expo Go/dev-client shells accept host + URL, for example agent-device open "Expo Go" exp://127.0.0.1:8081 --platform ios. macOS also supports --surface app|frontmost-app|desktop|menubar. --metro-host/--metro-port/--bundle-url choose the app's Metro server and save that address for later metro reload calls in the same session. A fresh open without Metro hints clears an older same-name binding; close also clears it. --launch-url supplies the app's launch URL; it does not select the reload server. On an iOS simulator without --launch-url, open connects a detected Expo development client through its expo-development-client URL. The app must declare a single exp+ scheme that no other installed app owns. If detection is inconclusive, the app opens normally. Bare React Native apps receive their server settings before launch. On an iOS simulator, when --launch-url raises an "Open in ?" prompt that keeps open from seeing the app, open accepts it if the URL scheme belongs to the session app (data.launchConfirmation: "accepted"); if the scheme belongs to another installed app, the prompt stays on screen and open fails with details.reason launch_confirmation_foreign_app; if the scheme owner cannot be resolved because no single installed app owns it or the lookup failed, the prompt stays on screen and open returns with data.launchConfirmation: "unanswered", launchConfirmationReason url-owner-unresolved, and a warning; a prompt that is seen but not recognized is reported the same way with launchConfirmationReason alert-unrecognized and its own warning; for url-owner-unresolved, answer the prompt with alert accept; for alert-unrecognized, read the alert with alert get first, because it can be the app's own alert (such as a permission prompt) rather than the launch confirmation, and answer with alert accept only when it is the launch confirmation; when agent-device cannot read whether a prompt is up at all (the alert read, the accept, or the runner itself failed, including after a re-hand of the URL), open stays green, reports no launchConfirmation plus data.launchConfirmationProbeFailure naming the failed step (alert-read, alert-accept, or runner), and appends a warning that says to check with alert get. The prompt is read whenever open cannot see the app afterwards, including on a slow host where the app's target discovery fails on its own deadline. When an accept leaves the app provably not running, open hands the same URL over once more and reads again; still not running, it fails with details.reason launch_confirmation_unanswered. When the runner reports its main-thread timeout for the accept and the prompt is still up, open presses Open again, but only when the time the open request has left covers a whole press and the read that checks it. A recognized prompt still visible after a failed accept, or once that time is gone, also fails with this reason, even if the app is running behind it; answer it with alert accept or alert dismiss. A simulator openurl that CoreSimulator never answers fails within 20s with details.reason ios-simulator-openurl-timeout. The prompt is recognized by the OS's own wording of its title and buttons in the Simulator's preferred languages; when the runner cannot read that wording, the prompt stays on screen as alert-unrecognized. A prompt that appears after open has already seen the app is not answered; use alert accept. A device another session is holding refuses at once; add --wait to block up to that budget for it and only then fail with DEVICE_IN_USE naming the owning session. Command flags: --force, --overwrite Force replacement of existing state (connect: replace an active connection; --save-script: overwrite an existing target instead of refusing) --os Proxy lease: OS version or range the backend picks the device by (Android: API level); refused without such a backend --image-tag Proxy lease: Android system image tag the backend picks the device by; refused without such a backend + --device-mode Proxy lease: iOS simulator mode (slim or full) the backend leases; refused without such a backend + --device-baseline Proxy lease: saved device state (baseline) the backend restores on the leased device; refused without such a backend --physical Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend --surface app|frontmost-app|desktop|menubar macOS session surface for open (defaults to app) --metro-host Session-scoped Metro/debug host hint @@ -226,11 +232,12 @@ Command flags: --test-ime open/test/replay: activate the headless Android test IME for deterministic Unicode text entry (default on for emulators; opt-in on real devices; on test/replay it applies to the sessions the flow opens) --no-test-ime open/test/replay: keep the real Android keyboard even on emulators (opt out of the headless test IME; on test/replay it applies to the sessions the flow opens) --activity Android launch activity (package/Class, .Class, or Class) or HarmonyOS ability name; not for URL opens - --launch-console open: capture the initial local iOS simulator launch console window to a file + --launch-console open: capture the initial local or Limrun iOS simulator launch console window to a file --launch-args open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args). Linux and macOS reject the flag. - --save-script [path] Arm evidence capture on open, publish the armed recording on close; close --save-script alone (without an armed open) is rejected — start with open --save-script, or use session save-script mid-session. Optional custom output path. + --no-post-gesture-stabilization Scroll, swipe, gesture swipe, open: skip the movement check and the stabilization wait that follow a gesture, and on a local iOS simulator the first-screen wait after an app launch; use it only when your own polling verifies the screen + --save-script [path] Arm evidence capture on open, publish the armed recording on close; close --save-script alone (without an armed open) is rejected — start with open --save-script, or use session save-script mid-session. Optional custom output path. On Windows, absolute paths need a drive letter or ordinary UNC share. --relaunch open: terminate app process before launching it - --foreground open: keep normal app/device selection and return an initial snapshot; without an app, resolve the sole running app on the sole booted iOS simulator + --foreground open: keep normal app/device selection and return an initial snapshot of the first screen (a local iOS simulator waits up to 10s for it); without an app, resolve the sole running app on the sole booted iOS simulator --no-record Do not record this action --timeout Boot/Open/Prepare: startup budget covering the device boot (and runner preparation for prepare). Replay/Snapshot/Test: maximum wall-clock time for the command or attempt. With --settle: the settle-wait deadline (default 10s) --wait Open: wait up to n ms for a device another session is holding before failing with DEVICE_IN_USE @@ -256,7 +263,7 @@ Settings: fingerprint: Simulates a fingerprint touch on Android emulators, and on devices that expose cmd fingerprint. clear-app-state: Clears the data of the positional app, the --app app, or the session app, and refuses two different apps. It leaves the keychain alone. An app with no data container, such as a simulator system app, refuses with app-no-data-container. reset-keychain: Resets the whole iOS simulator keychain, for every app on it: simctl has no per-app reset. A fresh-install reset needs this and clear-app-state; relaunch the app afterwards to see it signed out. - permission: Changes a permission of the --app app or the session app. An iOS simulator resolves --app to an installed bundle id or display name, Android to an installed package, and a Limrun iOS session only through the settings alias. On Android, deny|reset of a held permission kills a running app; the response reports priorGrantState and warns, and open --relaunch restores it. Android needs a resolvable foreground user and changes nothing without one. On the macOS host, grant|reset change the host TCC grants for the three desktop targets and take no --app. + permission: Changes a permission of the --app app or the session app. An iOS simulator, local or Limrun, resolves --app to an installed bundle id or display name, and Android to an installed package. On Android, deny|reset of a held permission kills a running app; the response reports priorGrantState and warns, and open --relaunch restores it. Android needs a resolvable foreground user and changes nothing without one. On the macOS host, grant|reset change the host TCC grants for the three desktop targets and take no --app. Command flags: --app Target an app without opening it: doctor verifies an installed app by id or name; settings applies an app-scoped change (permission, iOS location) to a bundle id or package @@ -264,7 +271,7 @@ $ agent-device help fill Usage: agent-device fill | fill <@ref|selector> | fill --text-stdin -Replace text in a UI input selected by snapshot ref, selector, or coordinates. Pass an empty text to clear the field. Inspect unconfirmed evidence and assert the expected value or resulting screen before continuing. Prefer refs or selectors after snapshot; use recordAs to keep sensitive text out of a recorded replay while sending it to the live app. Every positional after an @ref is the replacement text, so fill @e57 good morning enters "good morning"; quote the text when the shell must preserve exact whitespace. Clear a field with an empty text argument: fill @e57 "" (the argument must be present — fill @e57 alone is a missing argument, not a clear). When visible label text also matches a non-input element, constrain the target with editable=true, for example fill 'label="Email" editable=true' "qa@example.com". To keep a secret out of argv, omit the text and pipe it in: printf %s "$PASSWORD" | fill @e57 --text-stdin (max 64 KiB, one trailing newline removed). On web, a coordinate fill selects the clicked field in the page and refuses with COMMAND_FAILED and details.reason text_entry_focus_not_observed, before it sends any text or key, when the click did not reach an editable text field it can reach: a read-only, disabled, date, checkbox, or select control, a field in a cross-origin frame, a sandboxed frame without allow-same-origin, or a closed shadow root, or a click that missed. The click has already landed, so run snapshot -i again and fill the field it reports by ref (fill @e2 text); a selector fill reaches the same coordinate path and hits the same limits. +Replace text in a UI input selected by snapshot ref, selector, or coordinates. An empty text clears the field. Unconfirmed evidence does not establish the resulting value or screen. The recordAs option keeps sensitive text out of a recorded replay while sending it to the live app. To append instead of replacing, use type. Every positional after an @ref is the replacement text, so fill @e57 good morning enters "good morning"; quote the text when the shell must preserve exact whitespace. Clear a field with an empty text argument: fill @e57 "" (the argument must be present — fill @e57 alone is a missing argument, not a clear). When visible label text also matches a non-input element, constrain the target with editable=true, for example fill 'label="Email" editable=true' "qa@example.com". To keep a secret out of argv, omit the text and pipe it in: printf %s "$PASSWORD" | fill @e57 --text-stdin (max 64 KiB, one trailing newline removed). On web, a coordinate fill selects the clicked field in the page and refuses with COMMAND_FAILED and details.reason text_entry_focus_not_observed, before it sends any text or key, when the click did not reach an editable text field it can reach: a read-only, disabled, date, checkbox, or select control, a field in a cross-origin frame, a sandboxed frame without allow-same-origin, or a closed shadow root, or a click that missed. The click has already landed, so run snapshot -i again and fill the field it reports by ref (fill @e2 text); a selector fill reaches the same coordinate path and hits the same limits. Command flags: --delay-ms Delay between typed characters