agent-device 0.17.10 → 0.18.1

package/dist/src/batch.d.ts

@@ -1,18 +1,30 @@
-export declare const BATCH_BLOCKED_COMMANDS: ReadonlySet<string>;
-
-export declare type BatchFlags = Record<string, unknown> & {
+declare type BatchFlags = Record<string, unknown> & {
     batchOnError?: 'stop';
     batchMaxSteps?: number;
     batchSteps?: DaemonBatchStep[];
 };
 
-export declare type BatchInvoke = (req: BatchRequest) => Promise<DaemonResponse>;
+declare type BatchInvoke = (req: BatchRequest) => Promise<DaemonResponse>;
 
-export declare type BatchRequest = Omit<DaemonRequest, 'flags'> & {
+declare type BatchRequest = Omit<DaemonRequest, 'flags'> & {
     flags?: BatchFlags | Record<string, unknown>;
 };
 
-export declare type BatchStepResult = {
+declare type BatchRunResponse = {
+    ok: true;
+    data: BatchRunResult;
+} | Extract<DaemonResponse, {
+    ok: false;
+}>;
+
+declare type BatchRunResult = Record<string, unknown> & {
+    total: number;
+    executed: number;
+    totalDurationMs: number;
+    results: BatchStepResult[];
+};
+
+declare type BatchStepResult = {
     step: number;
     command: string;
     ok: true;
@@ -20,8 +32,6 @@ export declare type BatchStepResult = {
     durationMs: number;
 };
 
-export declare function buildBatchStepFlags(parentFlags: BatchFlags | Record<string, unknown> | undefined, stepFlags: DaemonBatchStep['flags'] | Record<string, unknown> | undefined): BatchFlags;
-
 declare const DAEMON_LOCK_POLICIES: readonly ['reject', 'strip'];
 
 declare type DaemonArtifact = {
@@ -32,11 +42,11 @@ declare type DaemonArtifact = {
     path?: string;
 };
 
-export declare type DaemonBatchStep = {
+declare type DaemonBatchStep = {
     command: string;
     positionals?: string[];
     flags?: Record<string, unknown>;
-    runtime?: unknown;
+    runtime?: DaemonRequest['runtime'];
 };
 
 declare type DaemonError = {
@@ -46,6 +56,18 @@ declare type DaemonError = {
     diagnosticId?: string;
     logPath?: string;
     details?: Record<string, unknown>;
+    /**
+     * Machine-readable typed-error signals (Phase 2). Additive: present only when
+     * derivable, so the default error wire shape is unchanged.
+     *
+     * `retriable` flags a transient failure an agent should retry (vs. a
+     * deterministic one where a retry is wasted). `supportedOn` lists the platform
+     * families that DO support the command (derived from the capability matrix),
+     * surfaced on platform-mismatch errors so an agent self-corrects without a
+     * wasted round-trip.
+     */
+    retriable?: boolean;
+    supportedOn?: string;
 };
 
 declare type DaemonInstallSource = {
@@ -83,6 +105,8 @@ declare type DaemonRequest = {
 declare type DaemonRequestMeta = {
     requestId?: string;
     debug?: boolean;
+    includeCost?: boolean;
+    responseLevel?: ResponseLevel;
     cwd?: string;
     sessionExplicit?: boolean;
     tenantId?: string;
@@ -90,6 +114,9 @@ declare type DaemonRequestMeta = {
     leaseId?: string;
     leaseTtlMs?: number;
     leaseBackend?: LeaseBackend;
+    leaseProvider?: string;
+    deviceKey?: string;
+    clientId?: string;
     sessionIsolation?: SessionIsolationMode;
     uploadedArtifactId?: string;
     clientArtifactPaths?: Record<string, string>;
@@ -99,7 +126,7 @@ declare type DaemonRequestMeta = {
     materializationId?: string;
     lockPolicy?: DaemonLockPolicy;
     lockPlatform?: PlatformSelector;
-    requestProgress?: 'replay-test';
+    requestProgress?: 'replay-test' | 'command';
 };
 
 declare type DaemonResponse = {
@@ -112,28 +139,28 @@ declare type DaemonResponse = {
 
 declare type DaemonResponseData = Record<string, unknown> & {
     artifacts?: DaemonArtifact[];
+    cost?: ResponseCost;
 };
 
-export declare const DEFAULT_BATCH_MAX_STEPS = 100;
-
-export declare const INHERITED_PARENT_FLAG_KEYS: readonly ['platform', 'target', 'device', 'udid', 'serial', 'verbose', 'out'];
-
 declare const LEASE_BACKENDS: readonly ['ios-simulator', 'ios-instance', 'android-instance'];
 
 declare type LeaseBackend = (typeof LEASE_BACKENDS)[number];
 
-export declare type NormalizedBatchStep = {
-    command: string;
-    positionals: string[];
-    flags: Record<string, unknown>;
-    runtime?: unknown;
-};
-
 declare const PLATFORM_SELECTORS: readonly ["ios", "macos", "android", "linux", "web", "apple"];
 
 declare type PlatformSelector = (typeof PLATFORM_SELECTORS)[number];
 
-export declare function runBatch(req: BatchRequest, sessionName: string, invoke: BatchInvoke): Promise<DaemonResponse>;
+declare const RESPONSE_LEVELS: readonly ['digest', 'default', 'full'];
+
+declare type ResponseCost = {
+    wallClockMs: number;
+    runnerRoundTrips: number;
+    nodeCount?: number;
+};
+
+declare type ResponseLevel = (typeof RESPONSE_LEVELS)[number];
+
+export declare function runBatch(req: BatchRequest, sessionName: string, invoke: BatchInvoke): Promise<BatchRunResponse>;
 
 declare const SESSION_ISOLATION_MODES: readonly ['none', 'tenant'];
 
@@ -147,6 +174,4 @@ declare type SessionRuntimeHints = {
     launchUrl?: string;
 };
 
-export declare function validateAndNormalizeBatchSteps(steps: unknown, maxSteps: number): NormalizedBatchStep[];
-
 export { }

package/dist/src/batch.js

@@ -1 +1 @@
-var _=100;export{BATCH_BLOCKED_COMMANDS,INHERITED_PARENT_FLAG_KEYS}from"./2133.js";export{buildBatchStepFlags,runBatch,validateAndNormalizeBatchSteps}from"./6918.js";export{_ as DEFAULT_BATCH_MAX_STEPS};
+export{runBatch}from"./6918.js";

package/dist/src/cli-help.js

@@ -1,4 +1,4 @@
-import{listCliCommandNames as e}from"./2133.js";import{getCliCommandSchema as t,getCommandSchema as a}from"./9581.js";import{getFlagDefinitions as o,GLOBAL_FLAG_KEYS as s}from"./2948.js";let n=[{label:"help workflow",description:"Normal bootstrap, exploration, and validation loop"},{label:"help debugging",description:"Logs, network, perf memory, and traces"},{label:"help react-native",description:"React Native app automation hazards, overlays, Metro, and routing"},{label:"help react-devtools",description:"React Native performance, profiling, component tree, and renders"},{label:"help cdp",description:"React Native CDP targets, JS heap snapshots, and leak triage"},{label:"help physical-device",description:"Connected phone/tablet setup and iOS signing prerequisites"},{label:"help remote",description:"Remote/cloud config, tenants, leases, and local service tunnels"},{label:"help web",description:"Minimal browser sessions through agent-browser"},{label:"help macos",description:"Desktop, frontmost-app, and menu bar surfaces"},{label:"help dogfood",description:"Exploratory QA report workflow"}],r=["Planning output contract: when asked to plan commands, output command lines only: no prose, numbering, Markdown fences, pipes, or shell helpers.","Default loop: devices/apps -> open -> snapshot -i -> press/fill/get/is/wait/find -> verify -> close.",'Use selectors or refs as positional targets: id="submit", label="Allow", or @e12 from snapshot -i.',"Plain snapshot reads state; snapshot -i refreshes current interactive refs only.","Default snapshot text is an agent-facing, token-efficient view for planning and targeting actions.","Read-only visible/state question: use snapshot/get/is/find; use snapshot -i only when refs are needed.","Anti-pattern: snapshot -i followed by snapshot -i | grep ...; prior refs stay valid until app state changes, and --force-full is the explicit full re-read.","Truncated text/input preview: expand first with snapshot -s @e12, not get text.","React Native apps: read help react-native for Metro, DevTools routing, and RN-specific blockers; use react-native dismiss-overlay for LogBox/RedBox overlays.","React Native JS memory leaks: read help cdp; use heap usage samples for a quick signal, then snapshot diff/leak-triplet for retained object proof.","Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability.",'Expo Go/dev clients: use the provided URL when given; on iOS use open "Expo Go" <url> --platform ios, then snapshot -i --platform ios to verify project UI. Do not use plain snapshot or snapshot --diff for this recovery check. Android URL opens infer the foreground package for logs/perf when possible.',"Install flows: install/install-from-source first, then open the installed id with --relaunch.",'Text: fill \'id="field-email"\' "qa@example.com" replaces; type appends after press.','Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',"Android IME capture: if fill says input was captured by the keyboard/IME, inspect keyboard state and switch/disable handwriting before retrying; do not loop fill/type.","Implicit default sessions are scoped to the current worktree; if a prompt names a Session, include --session <name> on every command in that flow.","Run mutating commands serially within one session; parallelize only read-only commands or separate sessions/devices.","Clipboard limits: iOS Allow Paste cannot be automated through XCUITest; prefill with clipboard write. Android non-ASCII should use fill/type, not raw adb input.","After mutation: refs are stale. If the next target is known, use its selector directly; otherwise refresh with snapshot -i, scoped with -s when a stable container is known. Do not use tap; use press or click.","Raw coordinates are fallback-only: use snapshot -i --json rects when iOS refs no-op or child refs are missing, then verify the action with diff snapshot -i or snapshot --diff.","Sparse or AX-unavailable snapshot: use screenshot for visual truth, press the visible coordinate to leave the bad screen, then retry AX with snapshot -i.","macOS context menus use click <ref> --button secondary, then snapshot -i. Longpress is for mobile hold gestures, not macOS secondary-click menus.","Direct proxy: Cloud/Linux clients can use iOS simulators through a Mac running agent-device proxy. A proxy URL/token means direct proxy mode: use --daemon-base-url plus --daemon-auth-token, or saved daemonBaseUrl/daemonAuthToken config.","Direct proxy sessions: choose one explicit --session and reuse it for open/snapshot/interactions/close; do not use connect, --remote-config, tenant, run, or lease flags.","Cloud/remote-config profiles are separate from direct proxy: use connect or --remote-config on operational commands. Do not substitute --config; --config only loads CLI defaults.",'Batch JSON steps use "command" and structured "input"; legacy "positionals"/"flags" steps still run in CLI but are deprecated until the next major version.',"Navigation: app-owned back uses back; system back uses back --system.","Web browser sessions: read help web; first slice is web setup if needed -> web doctor -> open <url> --platform web -> snapshot -i -> click/fill/get/is/find/wait/screenshot -> close.","Verification commands must name the expected text/selector; bare screenshots/snapshots are not enough.","Debug evidence: Session state contains request diagnostics and runner.log; use logs clear --restart/mark/path, trace, and network dump --include headers for app evidence.","Use agent-device commands in final plans; raw platform tools, pseudo commands, and helper prose are wrong.","Full operating guide: agent-device help workflow. Exploratory QA: agent-device help dogfood."],i=["Default config files: ~/.agent-device/config.json, ./agent-device.json","Use --config <path> or AGENT_DEVICE_CONFIG to load one explicit config file."],c=[{label:"AGENT_DEVICE_SESSION",description:"Explicit session name"},{label:"AGENT_DEVICE_PLATFORM",description:"Default platform binding"},{label:"AGENT_DEVICE_SESSION_LOCK",description:"Bound-session conflict mode"},{label:"AGENT_DEVICE_DAEMON_BASE_URL",description:"Connect to remote daemon"},{label:"AGENT_DEVICE_DAEMON_AUTH_TOKEN",description:"Remote daemon service/API token"},{label:"AGENT_DEVICE_CLOUD_BASE_URL",description:"Bridge/control-plane API origin for cloud auth and /api-keys"}],l=["agent-device open Settings --platform ios","agent-device open https://example.com --platform web","agent-device open TextEdit --platform macos","agent-device snapshot -i","agent-device react-devtools get tree --depth 3","agent-device cdp memory usage sample --gc --label baseline",'agent-device fill @e3 "test@example.com"',"agent-device replay ./session.ad","agent-device test ./suite --platform android"],d={workflow:{summary:"Normal agent-device bootstrap, exploration, and validation loop",body:`agent-device help workflow
+import{listCliCommandNames as e}from"./1986.js";import{getCliCommandSchema as t,getCommandSchema as a}from"./9581.js";import{getFlagDefinitions as o,GLOBAL_FLAG_KEYS as s}from"./2948.js";let n=[{label:"agent-device help workflow",description:"Start here for the core loop, command shape, refs/selectors, and verification"},{label:"agent-device help debugging",description:"Use when logs, network, audio, perf memory, traces, alerts, or diagnostics matter"},{label:"agent-device help react-native",description:"Use when the target app is React Native, Expo, or a dev client"},{label:"agent-device help react-devtools",description:"Use when inspecting components, props/state/hooks, renders, or profiles"},{label:"agent-device help cdp",description:"Use when investigating JS heap growth, heap snapshots, or retainers"},{label:"agent-device help physical-device",description:"Use when using a connected phone/tablet or iOS signing setup"},{label:"agent-device help remote",description:"Use when working through cloud config, tenants, leases, or local tunnels"},{label:"agent-device help web",description:"Use when automating a browser through agent-device sessions"},{label:"agent-device help macos",description:"Use when targeting desktop, frontmost app, or menu bar surfaces"},{label:"agent-device help dogfood",description:"Use when producing exploratory QA evidence"}],r=["agent-device is the default automation surface for app/device workflows across supported targets.","Default to agent-device for installs, opens, snapshots, interactions, screenshots, logs, network/perf evidence, and verification.","Use raw adb, simctl, xcrun, or platform scripts only when this help calls out a tool gap or platform setup step.","Start with agent-device help workflow to understand the core loop and how to use the tool."],i=["Planning output contract: when asked to plan commands, output command lines only: no prose, numbering, Markdown fences, pipes, or shell helpers.","Default loop: devices/apps -> open -> snapshot -i -> press/fill/get/is/wait/find -> verify -> close.",'Use selectors or refs as positional targets: id="submit", label="Allow", or @e12 from snapshot -i.',"Plain snapshot reads state; snapshot -i refreshes current interactive refs only.","Default snapshot text is an agent-facing, token-efficient view for planning and targeting actions.","Read-only visible/state question: use snapshot/get/is/find; use snapshot -i only when refs are needed.","Anti-pattern: snapshot -i followed by snapshot -i | grep ...; prior refs stay valid until app state changes, and --force-full is the explicit full re-read.","Truncated text/input preview: expand first with snapshot -s @e12, not get text.","React Native apps: read help react-native for Metro, DevTools routing, and RN-specific blockers; use react-native dismiss-overlay for LogBox/RedBox overlays.","React Native JS memory leaks: read help cdp; use heap usage samples for a quick signal, then snapshot diff/leak-triplet for retained object proof.","Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability.",'Expo Go/dev clients: use the provided URL when given; on iOS use open "Expo Go" <url> --platform ios, then snapshot -i --platform ios to verify project UI. Do not use plain snapshot or snapshot --diff for this recovery check. Android URL opens infer the foreground package for logs/perf when possible.',"Install flows: install/install-from-source first, then open the installed id with --relaunch.",'Text: fill \'id="field-email"\' "qa@example.com" replaces; type appends after press.','Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',"Android IME capture: if fill says input was captured by the keyboard/IME, inspect keyboard state and switch/disable handwriting before retrying; do not loop fill/type.","Implicit default sessions are scoped to the current worktree; if a prompt names a Session, include --session <name> on every command in that flow.","Run mutating commands serially within one session; parallelize only read-only commands or separate sessions/devices.","Clipboard limits: iOS Allow Paste cannot be automated through XCUITest; prefill with clipboard write. Android non-ASCII should use fill/type, not raw adb input.","After mutation: refs are stale. If the next target is known, use its selector directly; otherwise refresh with snapshot -i, scoped with -s when a stable container is known. Do not use tap; use press or click.","Raw coordinates are fallback-only: use snapshot -i --json rects when iOS refs no-op or child refs are missing, then verify the action with diff snapshot -i or snapshot --diff.","Sparse or AX-unavailable snapshot: use screenshot for visual truth, press the visible coordinate to leave the bad screen, then retry AX with snapshot -i.","macOS context menus use click <ref> --button secondary, then snapshot -i. Longpress is for mobile hold gestures, not macOS secondary-click menus.","Remote lifecycle: use connect, then open, commands, close, and disconnect. Cloud, remote-config, direct proxy, and limrun use the same flow.","Direct proxy: run agent-device connect proxy --daemon-base-url <proxy-agent-device-url> before using a shared Mac proxy. Device leases are automatic on open and expire after five minutes of inactivity.",'Batch JSON steps use "command" and structured "input"; legacy "positionals"/"flags" steps still run in CLI but are deprecated until the next major version.',"Navigation: app-owned back uses back; system back uses back --system.","Web browser sessions: read help web; first slice is web setup if needed -> web doctor -> open <url> --platform web -> snapshot -i -> click/fill/get/is/find/wait/screenshot -> close.","Verification commands must name the expected text/selector; bare screenshots/snapshots are not enough.","Debug evidence: Session state contains request diagnostics and runner.log; use logs clear --restart/mark/path, trace, and network dump --include headers for app evidence.","Full operating guide: agent-device help workflow. Exploratory QA: agent-device help dogfood."],c=["Default config files: ~/.agent-device/config.json, ./agent-device.json","Use --config <path> or AGENT_DEVICE_CONFIG to load one explicit config file."],d=[{label:"AGENT_DEVICE_SESSION",description:"Explicit session name"},{label:"AGENT_DEVICE_PLATFORM",description:"Default platform binding"},{label:"AGENT_DEVICE_SESSION_LOCK",description:"Bound-session conflict mode"},{label:"AGENT_DEVICE_DAEMON_BASE_URL",description:"Connect to remote daemon"},{label:"AGENT_DEVICE_DAEMON_AUTH_TOKEN",description:"Remote daemon service/API token"},{label:"AGENT_DEVICE_CLOUD_BASE_URL",description:"Bridge/control-plane API origin for cloud auth and /api-keys"}],l=["agent-device open Settings --platform ios","agent-device open https://example.com --platform web","agent-device open TextEdit --platform macos","agent-device snapshot -i","agent-device react-devtools get tree --depth 3","agent-device cdp memory usage sample --gc --label baseline",'agent-device fill @e3 "test@example.com"',"agent-device replay ./session.ad","agent-device test ./suite --platform android"],p={workflow:{summary:"Normal agent-device bootstrap, exploration, and validation loop",body:`agent-device help workflow
 
 Version-matched operating guide for normal agent-device work.
 
@@ -28,8 +28,8 @@ Bootstrap:
   agent-device prepare ios-runner --platform ios --timeout 240000
   If app id is unknown, plan devices, apps, then open <discovered-app-id>. Discovery is not enough when the task asks to open/start the app.
   Install arguments are app/package id then artifact path. If the task says install, use install; use reinstall only when explicitly requested. Fresh runtime state is open --relaunch after install.
-  In Apple CI, run prepare ios-runner after boot/install and before replay/test. prepare ios-runner builds/reuses the XCTest runner, health-checks it with a lightweight command, and retries one stuck/non-connecting runner launch before the first snapshot pays that setup cost. It is not a recovery step for "runner already owned by another agent-device daemon"; stop or clean the owning daemon on the Mac with simulator access instead. If the replay/test step starts a separate daemon, run clean:daemon after prepare so the prepared runner does not keep a live lease owned by the prepare daemon.
-  CI may cache ~/.agent-device/ios-runner/derived with an exact key that includes the agent-device package and Xcode version. Avoid broad restore-key fallbacks; prepare ios-runner already recovers bad restored runner artifacts and one retryable non-connecting runner launch. Runner build/start output is written to the session's runner.log; daemon.log is for daemon lifecycle/startup issues.
+  In Apple CI, run prepare ios-runner after boot/install and before replay/test. prepare ios-runner builds/reuses the XCTest runner, health-checks it with a lightweight command, and retries one stuck/non-connecting runner launch before the first snapshot pays that setup cost. It is not a recovery step for "runner already owned by another agent-device daemon"; stop the owning daemon on the Mac with simulator access instead. If the replay/test step starts a separate daemon, stop the prepare daemon before replay/test so the prepared runner does not keep a live lease owned by that daemon.
+  CI may cache ~/.agent-device/apple-runner/derived with an exact key that includes the agent-device package and Xcode version. Avoid broad restore-key fallbacks; prepare ios-runner already recovers bad restored runner artifacts and one retryable non-connecting runner launch. Runner build/start output is written to the session's runner.log; daemon.log is for daemon lifecycle/startup issues.
   Do not open artifact paths or invent package ids. If apps lookup misses the target and no URL/artifact is provided, ask or stop.
 
 Snapshots and refs:
@@ -67,7 +67,7 @@ Text entry:
     agent-device type "Handle with care" --delay-ms 80
   Empty replacement is not a supported clear-field command: do not plan fill <target> "" or fill <target> ''. Prefer a visible clear/reset control; if the app exposes none, report the tool gap instead of inventing a clear command.
   Debounced field with no result selector: agent-device wait 1000. Keyboard read-only: keyboard status/get. Blocked control: try keyboard dismiss when supported.
-  On iOS, prefer keyboard dismiss before manually pressing visible Done; the runner can use safe native keyboard controls and still reports unsupported layouts explicitly. If it returns UNSUPPORTED_OPERATION, prefer a visible app dismiss control, or use back --system only when system navigation is an acceptable side effect.
+  To hide the keyboard, use keyboard dismiss. It taps safe controls like Done when available and verifies the keyboard closed. If it reports UNSUPPORTED_OPERATION, press a visible app control such as Done only when that is the intended fallback.
   Use plain fill/type first for ordinary login and form fields. If an iOS debounced or search-as-you-type field actually drops characters, or must receive incremental updates, retry with --delay-ms before trying clipboard paste; --delay-ms intentionally paces character entry.
   iOS Allow Paste prompt cannot be exercised under XCUITest. To test paste-driven app behavior, prefill first with agent-device clipboard write "some text"; test the system prompt manually.
   Android Gboard handwriting/stylus UI can capture text in an IME-owned input instead of the app field. If fill reports that input was captured by the keyboard/IME, use the diagnostic targetInput/actualInput details, inspect keyboard status/get if needed, and switch or disable handwriting outside the command plan before retrying. Do not keep retrying fill/type against the same field while the IME owns focus.
@@ -140,9 +140,10 @@ Validation and evidence:
   Android animations: settings animations off/on, not animations disable/restore.
   Debug logs: logs clear --restart, logs mark, reproduce, then logs path; do not split clear/restart into separate stop/start commands.
   Network headers: network dump --include headers; do not write network log headers.
-  Direct proxy to a Mac you control: cloud/Linux clients can still use iOS simulators through the proxied Mac. Use the printed /agent-device daemon base URL and auth token, or store them as daemonBaseUrl and daemonAuthToken in agent-device.json. Use one explicit --session across open, snapshot, interactions, and close. Do not use connect, --remote-config, tenant, run, or lease flags for direct proxy simulators.
-  Cloud/remote-config profiles: use connect to discover a cloud profile, or connect --remote-config ./remote-config.json for a local profile; then open, snapshot, disconnect.
-  Web: agent-device uses a managed, pinned agent-browser backend as an implementation detail. Use --platform web when a browser step belongs inside an agent-device session, replay, batch, MCP, or typed-client flow; use agent-browser directly for standalone web automation. Run agent-device web setup before first use, then agent-device web doctor for backend health checks. Web automation requires Node 24+.
+  Remote lifecycle: cloud, remote-config, direct proxy, and limrun use the same flow: connect, open, commands, close, disconnect.
+  Remote config profile: agent-device connect --remote-config ./remote-config.json; then run normal commands and disconnect.
+  Direct proxy to a Mac you control: cloud/Linux clients can use local/proxy iOS devices through the proxied Mac. Run agent-device connect proxy --daemon-base-url <proxy-agent-device-url> first. Device leases are automatic on open and expire after five minutes of inactivity.
+  Web: agent-device uses a managed, pinned agent-browser backend as an implementation detail. Use --platform web when a browser step belongs inside an agent-device session, replay, batch, MCP, or typed-client flow; use agent-browser directly for standalone web automation. Run agent-device web setup before first use, then agent-device web doctor for backend health checks. Web automation requires Node 24+. For audio probe start, the first timing positional is duration in seconds and the second is bucket size in milliseconds. On web, audio probe samples HTML media elements, and URL-backed media may be routed through the probe AudioContext while observed. On macOS hosts, audio probe samples host system audio through ScreenCaptureKit for macOS sessions, iOS simulators, and Android emulators; Screen Recording permission is required.
     agent-device web setup
     agent-device web doctor
     agent-device open https://example.com --platform web
@@ -153,13 +154,17 @@ Validation and evidence:
     agent-device click @e12 --platform web
     agent-device fill @e13 "qa@example.com" --platform web
     agent-device wait text "Welcome" 3000 --platform web
+    agent-device record start ./artifacts/web-flow.webm --platform web
     agent-device network dump 25 --include headers --platform web
+    agent-device audio probe start 10 1000 --platform web
     agent-device screenshot ./artifacts/web-home.png --platform web
     agent-device screenshot ./artifacts/web-full.png --platform web --fullscreen
     agent-device viewport 1280 900 --platform web
+    agent-device record stop --platform web
     agent-device close --platform web
-  Minimal web support is for browser sessions with open, snapshot, find, get, is, click/press, fill/type, wait, network dump, screenshot, close, and replay over those commands. Use agent-browser directly for browser-specific features that agent-device does not surface, such as tab/devtools management, advanced page scripting, network routing/HAR, or raw browser debugging.
+  Minimal web support is for browser sessions with open, snapshot, find, get, is, click/press, fill/type, wait, network dump, audio probe, screenshot, record start/stop with WebM output, close, and replay over those commands. Use agent-browser directly for browser-specific features that agent-device does not surface, such as tab/devtools management, advanced page scripting, network routing/HAR, or raw browser debugging.
   macOS menu bar: open ... --platform macos --surface menubar; snapshot -i --platform macos --surface menubar.
+  Host audio: audio probe start 10 1000 --platform macos|ios|android samples host system audio through ScreenCaptureKit for macOS sessions, iOS simulators, and Android emulators on macOS hosts; grant Screen Recording permission first.
   Maestro full-suite validation on explicit connected devices uses one test command with a comma-separated --device list and --shard-all. Use --shard-split only when splitting suite entries across devices:
     agent-device test ./e2e/maestro --maestro --device udid1,emulator-5554 --shard-all 2
 
@@ -213,6 +218,18 @@ Network:
   Use this instead of logs path when the question is request/response metadata.
   network log is a supported alias, but network dump --include headers is the clearest plan form. Do not write network log headers.
 
+Audio:
+  Use audio probe when the question is whether a browser page, macOS session, iOS simulator, or Android emulator produced audible output during a short observation window.
+    agent-device audio probe start 10 1000 --platform web
+    agent-device audio probe status --platform web
+    agent-device audio probe stop --platform web
+    agent-device audio probe start 10 1000 --platform macos
+    agent-device audio probe start 10 1000 --platform ios
+    agent-device audio probe start 10 1000 --platform android
+  audio probe start uses duration seconds first, then bucket milliseconds. Results are compact rmsDbfs and peakDbfs arrays so agents can correlate audible moments with screenshots, actions, network entries, or frame samples.
+  On web, audio probe samples HTML media elements and URL-backed media may be routed through the probe AudioContext while observed.
+  On macOS hosts, audio probe samples host system audio through ScreenCaptureKit for macOS sessions, iOS simulators, and Android emulators. It requires Screen Recording permission and is system-audio evidence, not app-instrumented audio. Physical iOS and Android devices are not supported.
+
 Crash symbolication:
   Crash routing:
     Use logs when you need the lead-up timeline before a failure.
@@ -221,7 +238,7 @@ Crash symbolication:
   Use debug symbols when you already have an Apple crash artifact and local dSYMs and need the failing code path, not a full log dump:
     agent-device debug symbols --artifact crash.log --dsym MyApp.dSYM --out crash-symbolicated.log
     agent-device debug symbols --artifact crash.ips --search-path ./build --out crash-symbolicated.ips
-  debug is intentionally narrow. Do not use it for logs, network evidence, performance samples, recordings, traces, or React Native internals.
+  debug is intentionally narrow. Do not use it for logs, network/audio evidence, performance samples, recordings, traces, or React Native internals.
   Apple support matches crash Binary Images / IPS usedImages UUIDs against dwarfdump --uuid output from .dSYM bundles, then writes a symbolicated artifact path and compact crash report: app/thread, exception or termination, top symbolicated frames, and first-frame finding. This is better than pasting crash logs because it keeps agent context small while preserving the artifact on disk for inspection.
   Android Java/R8 mapping.txt and native ndk-stack/addr2line symbolication are not in this first debug symbols workflow; capture crash evidence with logs and use the Android toolchain externally for now.
 
@@ -353,6 +370,7 @@ state. Do not use this as the default React Native profiler.
 
 Setup:
   Start Metro and open the app first. For Android devices/emulators, make sure Metro is reachable from the app, typically with adb reverse tcp:8081 tcp:8081.
+  In remote bridge sessions, omit --url for target list/select after connect; agent-device derives the Metro CDP URL from the prepared remote runtime.
   agent-device cdp target list --url http://127.0.0.1:8081
   agent-device cdp target select <target-id>
 
@@ -405,12 +423,17 @@ Choose the next help topic:
   Remote/cloud config, leases, and local service tunnels: help remote.
 
 React Native dev loop:
+  Before QA/dogfood runs, use doctor to separate environment setup from app failures:
+    agent-device doctor --platform android
+    agent-device doctor --platform ios
+    agent-device doctor --platform android --app com.example.app
+    agent-device doctor --remote --remote-config ./remote.json
   For "start from screen X" flows, prefer open --relaunch before the first snapshot so the app does not reuse a prior in-progress navigation state.
   JS-only change with Metro connected:
     agent-device metro reload
     agent-device find "Home"
   Do not use agent-device reload. Use open --relaunch for native startup reset.
-  Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability. For app/package launches, use help react-native if the app cannot reach local Metro.
+  Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability. For app/package launches, run metro prepare when the app cannot reach local Metro.
   Verify Metro from the same host context that owns Metro. If a sandboxed shell cannot curl localhost:8081/status but an unrestricted host shell can, Metro is running and the sandbox probe is not authoritative.
   adb reverse only affects Android device-to-host traffic. It does not prove host-to-Metro reachability, and it does not fix a redbox caused by a stale or wrong Metro/app state.
   Multiple local worktrees can reuse one native iOS simulator build by running each worktree's Metro on a different port and opening the same installed app on different simulators with explicit runtime hints:
@@ -494,19 +517,32 @@ Android physical-device prerequisites:
   Enable USB debugging and confirm the device appears in agent-device devices --platform android.
   Android does not need the iOS runner signing setup. For React Native/Expo Metro reachability, read help react-native.`},remote:{summary:"Direct proxy, cloud profiles, and remote config",body:`agent-device help remote
 
-There are two different remote modes:
-  1. Direct proxy: agent-device proxy exposes a Mac you control. A cloud/Linux client can use iOS simulators through that proxied Mac. Use --daemon-base-url plus --daemon-auth-token, or store daemonBaseUrl and daemonAuthToken in agent-device.json. Use one explicit --session across open, snapshot, interactions, and close so implicit cwd-scoped default sessions do not diverge. Do not use connect, --remote-config, tenant, run, or lease flags for this mode.
-  2. Cloud/profile: the cloud connection profile or a local --remote-config owns daemon URL, auth, tenant, run, lease, device scope, and Metro hints. Do not restate those as individual flags unless overriding intentionally.
+Remote connection providers use the same lifecycle:
+  connect -> open -> commands -> close -> disconnect
+
+Providers:
+  Cloud: agent-device connect or agent-device connect cloud discovers the agent-device cloud profile.
+  Remote config: agent-device connect --remote-config ./remote-config.json uses a local profile.
+  Direct proxy: agent-device connect proxy --daemon-base-url <proxy-agent-device-url> stores the shared proxy profile and client identity.
+  BrowserStack: agent-device connect browserstack stores a local provider profile and creates the App Automate session on first open.
+  AWS Device Farm: agent-device connect aws-device-farm stores a local provider profile and creates the remote access session on first open.
+
+Device cloud interfaces:
+  CLI is the canonical bootstrap path: connect browserstack/aws-device-farm, then use normal open/snapshot/click/close/artifacts/disconnect commands.
+  JavaScript can skip persisted connect state by passing leaseProvider plus provider fields to createAgentDeviceClient or per-command options.
+  MCP exposes operational tools such as open, snapshot, click, close, and artifacts. It does not expose connect/disconnect; run CLI connect first in the same state dir before relying on MCP tools.
 
 Direct proxy flow for a remote Mac/simulator:
   On the Mac with simulator/device access:
     agent-device proxy --port 4310
     cloudflared tunnel --url http://127.0.0.1:4310
   On the remote client:
-    agent-device devices --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>
-    agent-device open Maps --session maps --platform ios --device "iPhone 17 Pro" --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>
-    agent-device snapshot -i --session maps --platform ios --device "iPhone 17 Pro" --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>
-    agent-device close --session maps --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>
+    agent-device connect proxy --daemon-base-url https://example.trycloudflare.com/agent-device --daemon-auth-token <token>
+    agent-device devices --platform ios
+    agent-device open Maps --platform ios --device "iPhone 17 Pro"
+    agent-device snapshot -i --platform ios --device "iPhone 17 Pro"
+    agent-device close
+    agent-device disconnect
 
 Cloud profile flow:
   agent-device connect
@@ -514,6 +550,24 @@ Cloud profile flow:
   agent-device snapshot
   agent-device disconnect
 
+BrowserStack hosted-device flow:
+  BROWSERSTACK_USERNAME=... BROWSERSTACK_ACCESS_KEY=...
+  agent-device connect browserstack --platform android --device "Google Pixel 8" --provider-os-version 14.0 --provider-app bs://app-id
+  agent-device open com.example.app
+  agent-device snapshot -i
+  agent-device close
+  agent-device artifacts --json
+  agent-device disconnect
+
+AWS Device Farm hosted-device flow:
+  AWS_REGION=us-west-2 AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_SESSION_TOKEN=...
+  agent-device connect aws-device-farm --platform android --aws-project-arn <arn> --aws-device-arn <arn> --aws-app-arn <arn>
+  agent-device open com.example.app
+  agent-device snapshot -i
+  agent-device close
+  agent-device artifacts --json
+  agent-device disconnect
+
 Local profile flow:
   agent-device connect --remote-config ./remote-config.json
   agent-device open com.example.app
@@ -528,11 +582,18 @@ Script flow, per-command config:
 Rules:
   connect and disconnect are top-level commands. Do not write agent-device remote connect or agent-device remote disconnect.
   Use connect without --remote-config when the cloud control plane owns the connection profile.
-  Prefer --remote-config over --daemon-base-url, --tenant, --run-id, and --lease-id when using a local profile.
-  Use agent-device proxy for direct tunnel access to a Mac you control. Copy the printed daemon base URL and daemon auth token; do not use agent-device auth, connect, disconnect, --remote-config, tenant, run, or lease flags for this direct proxy flow.
-  For repeated direct proxy commands, store daemonBaseUrl and daemonAuthToken in normal agent-device.json CLI config. Keep platform selection on each command or workflow, and keep the same explicit --session until close.
+  Prefer connect --remote-config over --daemon-base-url, --tenant, --run-id, and --lease-id when using a local profile.
+  Use agent-device proxy for direct tunnel access to a Mac you control. Expose the printed proxy URL through cloudflared/ngrok, then run agent-device connect proxy with the tunnel URL and printed token before normal commands.
+  Use BrowserStack and AWS Device Farm through local provider profiles; they do not accept a remote agent-device daemon URL.
+  Device cloud credentials must be available before the command starts. BrowserStack uses BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY. AWS Device Farm uses the AWS CLI credential chain, including CI-provided AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN, AWS profiles, or web identity role variables.
+  Prefer short-lived AWS role credentials in CI. Generated connection profiles store app/device selectors and ARNs, not BrowserStack access keys or AWS credentials.
+  After closing a device cloud session, run agent-device artifacts --json to retrieve provider video/log/dashboard URLs when the provider has made them available.
+  connect proxy stores the connection profile and client identity. Device leases are acquired on open and expire after five minutes without commands.
+  Multiple agents can share one proxy when each uses connect proxy, open, commands, close, and disconnect.
+  disconnect releases local connection state; close releases the active session and device lease.
+  A busy direct-proxy device error means another agent owns the device until it closes or its inactivity lease expires.
   Keep the proxy token secret. Anyone with the token can control the proxied daemon.
-  If iOS snapshot/interaction reports that the runner is already owned by another agent-device daemon, do not run prepare ios-runner from the remote client. Retry the original snapshot or interaction; same-proxy-state stale runner leases are reclaimed by the proxy daemon. If the conflict repeats, the Mac operator should close the owning session or clean the conflicting local daemon.
+  If local/proxy iOS reports that the runner is already owned by another agent-device daemon after lease admission, retry after the owning session closes or after lease expiry. If the conflict repeats, clean stale daemon state on the machine with simulator access.
   Do not use --config as a remote profile flag. --config loads CLI defaults; --remote-config selects remote daemon/profile settings.
   For self-contained scripts, pass the same --remote-config to every operational command, including disconnect; a preceding connect is optional but not required.
   For remote artifact installs, use install-from-source <url> or install-from-source --github-actions-artifact org/repo:artifact; do not download CI artifacts locally first.
@@ -582,6 +643,7 @@ Planning rule:
   For web command plans, output only agent-device command lines. Do not add prose, numbering, Markdown fences, shell pipes, or agent-browser commands unless the task is explicitly standalone browser automation outside agent-device.
 
 First-slice loop:
+  Audio probe start uses duration seconds first, then bucket milliseconds.
   agent-device web setup
   agent-device web doctor
   agent-device open https://example.com --platform web
@@ -592,14 +654,17 @@ First-slice loop:
   agent-device click @e12 --platform web
   agent-device fill @e13 "qa@example.com" --platform web
   agent-device wait text "Welcome" 3000 --platform web
+  agent-device record start ./artifacts/web-flow.webm --platform web
   agent-device network dump 25 --include headers --platform web
+  agent-device audio probe start 10 1000 --platform web
   agent-device screenshot ./artifacts/web-home.png --platform web
   agent-device screenshot ./artifacts/web-full.png --platform web --fullscreen
   agent-device viewport 1280 900 --platform web
+  agent-device record stop --platform web
   agent-device close --platform web
 
 Supported in agent-device web sessions:
-  open <url>, snapshot -i, get text/attrs, is visible/exists/text, find text/selector, click/press @ref or selector, fill/type @ref or selector, wait text/selector, network dump, screenshot, close, and replay scripts made from those commands.
+  open <url>, snapshot -i, get text/attrs, is visible/exists/text, find text/selector, click/press @ref or selector, fill/type @ref or selector, wait text/selector, network dump, audio probe, screenshot, record start/stop with WebM output, close, and replay scripts made from those commands.
 
 Out of scope for agent-device web support:
   Browser runtime debugging, tabs/windows/devtools control, network routing/interception/HAR, storage/cookie management, arbitrary page scripting, downloads/uploads, multi-page orchestration, and agent-browser-specific diagnostics. Use agent-browser directly for those browser-specific workflows.
@@ -664,37 +729,39 @@ Rules:
   Prefer refs for exploration and selectors for deterministic replay.
   Use logs, network, screenshot --overlay-refs, trace, perf metrics, perf frames, or react-devtools only when they add evidence to a specific issue.
   Never delete screenshots, videos, traces, or report artifacts during a session.
-  Escalate to help debugging or help react-devtools when runtime symptoms require those tools.`}};function p(e){let t=e.endsWith("?"),a=t?e.slice(0,-1):e;return t?`[${a}]`:`<${a}>`}function h(){let a,o,d,p,h,v,b,w;return a=`agent-device <command> [args] [--json]
+  Escalate to help debugging or help react-devtools when runtime symptoms require those tools.`}};function h(e){let t=e.endsWith("?"),a=t?e.slice(0,-1):e;return t?`[${a}]`:`<${a}>`}function m(){let a,o,p,h,m,b,w,y,k;return a=`agent-device <command> [args] [--json]
 
-CLI to control iOS and Android devices for AI agents.
-`,o=f("Commands:",e().map(e=>{let a=t(e);return{name:e,schema:a,usage:function(e,t){if(t.listUsageOverride)return t.listUsageOverride;let a=(t.positionalArgs??[]).map(a=>{var o,s,n;let r,i,c,l;return o=e,s=t,i=(r=(n=a).endsWith("?"))?n.slice(0,-1):n,l=(c=/^[a-z-]+(?:\|[a-z-]+)+$/i.test(i))||void 0!==s.usageOverride&&s.usageOverride.startsWith(`${o} ${i}`),r?c?`[${i}]`:l?i:`[${i}]`:l?i:`<${i}>`});return[e,...a].join(" ")}(e,a)}}).map(e=>({label:e.usage,description:e.schema.summary??e.schema.helpDescription}))),d=m("Global Flags:",u(s)),p=g("Agent Quickstart:",r),h=f("Agent Workflows:",n),v=g("Configuration:",i),b=f("Environment:",c),w=g("Examples:",l),`${a}
+CLI to automate supported app, device, desktop, and web targets for AI agents.
+`,o=g("Commands:",e().map(e=>{let a=t(e);return{name:e,schema:a,usage:function(e,t){if(t.listUsageOverride)return t.listUsageOverride;let a=(t.positionalArgs??[]).map(a=>{var o,s,n;let r,i,c,d;return o=e,s=t,i=(r=(n=a).endsWith("?"))?n.slice(0,-1):n,d=(c=/^[a-z-]+(?:\|[a-z-]+)+$/i.test(i))||void 0!==s.usageOverride&&s.usageOverride.startsWith(`${o} ${i}`),r?c?`[${i}]`:d?i:`[${i}]`:d?i:`<${i}>`});return[e,...a].join(" ")}(e,a)}}).map(e=>({label:e.usage,description:e.schema.summary??e.schema.helpDescription}))),p=f("Global Flags:",u(s)),h=v("Agent Starting Point:",r),m=v("Agent Quickstart:",i),b=g("Agent Workflows:",n),w=v("Configuration:",c),y=g("Environment:",d),k=v("Examples:",l),`${a}
 ${h}
 
-${o}
+${b}
 
-${d}
+${o}
 
 ${p}
 
-${v}
-
-${b}
+${m}
 
 ${w}
-`}function u(e){return o().filter(t=>e.has(t.key)&&void 0!==t.usageLabel&&void 0!==t.usageDescription)}function m(e,t){return f(e,t.map(e=>({label:e.usageLabel??"",description:e.usageDescription??""})))}function f(e,t){if(0===t.length)return`${e}
-  (none)`;let a=Math.max(...t.map(e=>e.label.length))+2,o=[e];for(let e of t)o.push(`  ${e.label.padEnd(a)}${e.description}`);return o.join("\n")}function g(e,t){return 0===t.length?`${e}
-  (none)`:[e,...t.map(e=>`  ${e}`)].join("\n")}function v(e){var t,s;let n,r=(n=d[e])?`${n.body}
+
+${y}
+
+${k}
+`}function u(e){return o().filter(t=>e.has(t.key)&&void 0!==t.usageLabel&&void 0!==t.usageDescription)}function f(e,t){return g(e,t.map(e=>({label:e.usageLabel??"",description:e.usageDescription??""})))}function g(e,t){if(0===t.length)return`${e}
+  (none)`;let a=Math.max(...t.map(e=>e.label.length))+2,o=[e];for(let e of t)o.push(`  ${e.label.padEnd(a)}${e.description}`);return o.join("\n")}function v(e,t){return 0===t.length?`${e}
+  (none)`:[e,...t.map(e=>`  ${e}`)].join("\n")}function b(e){var t,s;let n,r=(n=p[e])?`${n.body}
 
 Related:
   agent-device help                  command list and global flags
   agent-device help <command>        command-specific flags
   agent-device help workflow         normal app automation loop
-`:null;if(r)return r;let i=a(e);if(!i)return null;let c=(t=e,(s=i).usageOverride?s.usageOverride:[t,...(s.positionalArgs??[]).map(p),...(s.allowedFlags??[]).flatMap(e=>{var t;return(t=e,o().filter(e=>e.key===t)).map(e=>e.usageLabel??e.names[0])}).map(e=>`[${e}]`)].join(" ")),l=u(new Set(i.allowedFlags??[])),h=[];l.length>0&&h.push(m("Command flags:",l));let f=h.length>0?`
+`:null;if(r)return r;let i=a(e);if(!i)return null;let c=(t=e,(s=i).usageOverride?s.usageOverride:[t,...(s.positionalArgs??[]).map(h),...(s.allowedFlags??[]).flatMap(e=>{var t;return(t=e,o().filter(e=>e.key===t)).map(e=>e.usageLabel??e.names[0])}).map(e=>`[${e}]`)].join(" ")),d=u(new Set(i.allowedFlags??[])),l=[];d.length>0&&l.push(f("Command flags:",d));let m=l.length>0?`
 
-${h.join("\n\n")}`:"";return`agent-device ${c}
+${l.join("\n\n")}`:"";return`agent-device ${c}
 
 ${i.helpDescription}
 
 Usage:
-  agent-device ${c}${f}
-`}export{v as buildCommandUsageText,h as buildUsageText};
+  agent-device ${c}${m}
+`}export{b as buildCommandUsageText,m as buildUsageText};