agent-device 0.17.10 → 0.18.0

package/dist/src/batch.d.ts

@@ -12,6 +12,20 @@ export declare type BatchRequest = Omit<DaemonRequest, 'flags'> & {
     flags?: BatchFlags | Record<string, unknown>;
 };
 
+export declare type BatchRunResponse = {
+    ok: true;
+    data: BatchRunResult;
+} | Extract<DaemonResponse, {
+    ok: false;
+}>;
+
+export declare type BatchRunResult = Record<string, unknown> & {
+    total: number;
+    executed: number;
+    totalDurationMs: number;
+    results: BatchStepResult[];
+};
+
 export declare type BatchStepResult = {
     step: number;
     command: string;
@@ -36,7 +50,7 @@ export declare type DaemonBatchStep = {
     command: string;
     positionals?: string[];
     flags?: Record<string, unknown>;
-    runtime?: unknown;
+    runtime?: DaemonRequest['runtime'];
 };
 
 declare type DaemonError = {
@@ -90,6 +104,9 @@ declare type DaemonRequestMeta = {
     leaseId?: string;
     leaseTtlMs?: number;
     leaseBackend?: LeaseBackend;
+    leaseProvider?: string;
+    deviceKey?: string;
+    clientId?: string;
     sessionIsolation?: SessionIsolationMode;
     uploadedArtifactId?: string;
     clientArtifactPaths?: Record<string, string>;
@@ -126,14 +143,14 @@ export declare type NormalizedBatchStep = {
     command: string;
     positionals: string[];
     flags: Record<string, unknown>;
-    runtime?: unknown;
+    runtime?: DaemonRequest['runtime'];
 };
 
 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>;
+export declare function runBatch(req: BatchRequest, sessionName: string, invoke: BatchInvoke): Promise<BatchRunResponse>;
 
 declare const SESSION_ISOLATION_MODES: readonly ['none', 'tenant'];
 

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};
+var _=100;export{BATCH_BLOCKED_COMMANDS,INHERITED_PARENT_FLAG_KEYS}from"./5341.js";export{buildBatchStepFlags,runBatch,validateAndNormalizeBatchSteps}from"./6918.js";export{_ as DEFAULT_BATCH_MAX_STEPS};

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"./5341.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, 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.
 
@@ -140,8 +140,9 @@ 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.
+  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+.
     agent-device web setup
     agent-device web doctor
@@ -153,12 +154,14 @@ 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 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, 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.
   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
@@ -353,6 +356,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>
 
@@ -410,7 +414,7 @@ React Native dev loop:
     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 +498,25 @@ 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 discovers the 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.
 
 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
@@ -528,11 +538,14 @@ 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.
+  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.
@@ -592,14 +605,16 @@ 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 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, 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 +679,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 u(){let a,o,p,h,u,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:",m(s)),h=v("Agent Starting Point:",r),u=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}
+${u}
 
 ${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 m(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=m(new Set(i.allowedFlags??[])),l=[];d.length>0&&l.push(f("Command flags:",d));let u=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}${u}
+`}export{b as buildCommandUsageText,u as buildUsageText};