agent-device 0.12.9 → 0.13.0

package/dist/src/index.d.ts

@@ -2164,11 +2164,13 @@ declare type RepeatedPressOptions = {
 export declare type ReplayRunOptions = AgentDeviceRequestOverrides & {
     path: string;
     update?: boolean;
+    env?: string[];
 };
 
 export declare type ReplayTestOptions = AgentDeviceRequestOverrides & AgentDeviceSelectionOptions & {
     paths: string[];
     update?: boolean;
+    env?: string[];
     failFast?: boolean;
     timeoutMs?: number;
     retries?: number;
@@ -2452,6 +2454,9 @@ declare type SessionRuntimeHints = {
 export declare type SettingsUpdateOptions = (ClientCommandBaseOptions & {
     setting: 'wifi' | 'airplane' | 'location';
     state: 'on' | 'off';
+}) | (ClientCommandBaseOptions & {
+    setting: 'animations';
+    state: 'on' | 'off';
 }) | (ClientCommandBaseOptions & {
     setting: 'appearance';
     state: 'light' | 'dark' | 'toggle';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-device",
-  "version": "0.12.9",
-  "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
+  "version": "0.13.0",
+  "description": "Agent-driven CLI for mobile UI automation, network inspection, and performance diagnostics across iOS, Android, tvOS, and macOS.",
   "license": "MIT",
   "author": "Callstack",
   "homepage": "https://agent-device.dev/",
@@ -128,11 +128,20 @@
     "agent",
     "device",
     "cli",
+    "automation",
     "adb",
     "simctl",
     "devicectl",
     "ios",
-    "android"
+    "android",
+    "tvos",
+    "macos",
+    "react-native",
+    "observability",
+    "diagnostics",
+    "network",
+    "profiling",
+    "performance"
   ],
   "dependencies": {
     "fast-xml-parser": "^5.5.10",

package/skills/agent-device/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-device
-description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info across mobile, TV, and desktop targets.
+description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, extracting UI info, or collecting logs, network inspection, and perf snapshots across mobile, TV, and desktop targets.
 ---
 
 # agent-device
@@ -71,3 +71,4 @@ Use this skill as a router with mandatory defaults. Read this file first. For no
 - Need desktop surfaces, menu bar behavior, or macOS-specific interaction rules: [references/macos-desktop.md](references/macos-desktop.md)
 - Need remote HTTP transport, `connect --remote-config`, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)
   This includes remote React Native runs where `agent-device` now prepares Metro locally and manages the local Metro companion tunnel automatically.
+- Need the React Native component tree, props, state, hooks, or render profiling: use `agent-device react-devtools ...` and the [react-devtools skill](../react-devtools/SKILL.md).

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

@@ -4,6 +4,8 @@
 
 Open this file when the task turns into failure triage, logs, network inspection, permission prompts, setup trouble, or unstable session behavior.
 
+If the debugging task needs the React Native component tree, props, state, hooks, or render profiling, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow instead of trying to infer those internals from the accessibility tree or app logs alone.
+
 ## Main commands to reach for first
 
 - `logs clear --restart`
@@ -111,7 +113,7 @@ agent-device alert accept
 - `snapshot` returns 0 nodes: the app may no longer be foregrounded or the UI is not stable yet. Re-open the app or retry when state settles.
 - Logs are empty: confirm you opened an app session before `logs clear --restart`.
 - Android logs look stale after relaunch: retry the repro window after the process rebinds.
-- Android accessibility snapshots can lag behind visible screen transitions. The next snapshot now retries briefly after navigation-sensitive actions, but if the tree still looks stale, use `screenshot` as visual truth, wait briefly, then re-run `snapshot -i`.
+- Android accessibility snapshots can lag behind visible screen transitions. The next snapshot retries suspicious trees for a short post-action deadline after navigation-sensitive actions, and `@ref` actions refresh while that window is active. If the tree still looks stale, use `screenshot` as visual truth, wait briefly, then re-run `snapshot -i`. For animation-heavy runs, try `settings animations off` and restore with `settings animations on`.
 - React Native dev warnings or errors keep reappearing: treat them as part of the app state, not as disposable chrome. Capture one clean repro and include them in the summary.
 - Permission prompts block the flow: wait for the alert and handle it explicitly.
 - If snapshots keep returning 0 nodes on an iOS simulator, restart Simulator and re-open the app.

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

@@ -20,6 +20,7 @@ Open this file when the app or screen is already running and you need to discove
 - User asks what is visible on screen: `snapshot`
 - User asks for exact text from a known target: `get text`
 - User asks you to tap, type, or choose an element: `snapshot -i`, then act
+- User asks for the React Native component tree, props/state/hooks, or render profiling: use `agent-device react-devtools ...` and the `skills/react-devtools` workflow
 - React Native dev or debug build shows warning/error UI: capture enough evidence to identify it, dismiss it if it is not the requested behavior, then continue the flow and report it in the summary
 - The on-screen keyboard is blocking the next step: `keyboard dismiss`; on iOS do this only while an app session is active, and use `keyboard status|get` only on Android
 - UI does not expose the answer: say so plainly; do not browse or force the app into a new state unless asked
@@ -49,8 +50,9 @@ Open this file when the app or screen is already running and you need to discove
 **Android AX tree lag.** After submits, route changes, or composer transitions, the accessibility tree can lag behind the visible UI. If `snapshot -i` and `screenshot` disagree:
 
 1. Trust the screenshot as visual truth.
-2. Take one fresh `snapshot -i`. Android retries briefly after navigation-sensitive actions.
+2. Take one fresh `snapshot -i`. Android retries suspicious trees for a short post-action deadline after navigation-sensitive actions.
 3. If the tree still disagrees with the screenshot, wait briefly, then take one more fresh snapshot. Do not loop snapshots immediately.
+4. For animation-heavy Android runs, use `settings animations off` as an opt-in stabilizer and restore with `settings animations on` after the run.
 
 **React Native dev overlays.** In dev or debug builds, warning or error overlays can block taps, change focus, or hide the real UI. Check for them near app open and after major transitions.
 
@@ -222,7 +224,7 @@ Preferred mapping:
 Notes:
 
 - `wait text` is useful for synchronizing on text presence, but it is not the same as `is visible`.
-- After a nearby navigation or submit on Android, prefer `screenshot`, then `wait 500` or `wait 1000`, then one fresh `snapshot -i` if the accessibility tree seems stale.
+- After a nearby navigation or submit on Android, prefer `screenshot`, then one fresh `snapshot -i`; `@ref` interactions refresh while the Android freshness window is active.
 
 Anti-hallucination rules:
 

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

@@ -129,5 +129,6 @@ agent-device perf --json
 - `startup` is command round-trip timing around `open`.
 - It is not true first-frame or first-interactive telemetry.
 - Android app sessions also expose `memory` (`dumpsys meminfo`) and `cpu` (`dumpsys cpuinfo`) snapshots when the session has an app package context.
-- Apple app sessions on macOS and iOS simulators also expose `memory` and `cpu` process snapshots when the session has an app bundle ID.
-- `fps` is still unavailable, and physical iOS devices still leave `memory` and `cpu` unavailable in this release.
+- Apple app sessions on macOS, iOS simulators, and physical iOS devices also expose `memory` and `cpu` process snapshots when the session has an app bundle ID.
+- On physical iOS devices, sampling uses a short `xcrun xctrace` Activity Monitor capture, so keep the device unlocked, connected, and the app active in the foreground while sampling.
+- `fps` is still unavailable in this release.

package/skills/dogfood/SKILL.md

@@ -166,6 +166,7 @@ agent-device --session {SESSION} close
 - Re-snapshot after any mutation (navigation, modal, list update, form submit).
 - Use `fill` for clear-then-type semantics; use `type` for incremental typing behavior checks.
 - Keep logs optional and targeted: enable/read app logs only when useful for diagnosis.
+- If the issue appears rooted in React Native internals rather than device/app runtime behavior, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow for component-tree or render-profiling inspection.
 - Never read source code of the app under test; findings must come from observed runtime behavior.
 - Write each issue immediately to avoid losing evidence.
 - Never delete screenshots/videos/report artifacts during a session.

package/skills/react-devtools/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: react-devtools
+description: Inspect and profile React Native component trees from agent-device. Use when debugging React Native props, state, hooks, render causes, slow components, excessive re-renders, or questions like why a component re-rendered.
+---
+
+# react-devtools
+
+Use this skill when the task needs React Native internals that are not visible in the accessibility tree: component hierarchy, props, state, hooks, render causes, or profiling data.
+
+Run commands through `agent-device react-devtools`. The command dynamically runs pinned `agent-react-devtools@0.4.0` and passes arguments through 1:1.
+
+The first run may download the pinned package from npm. `agent-device` global flags work before or after `react-devtools`; use `--` before downstream flags only when they intentionally share an `agent-device` global flag name.
+
+## Default flow
+
+1. Use `agent-device` to open the React Native app and verify the visible state when needed.
+2. Check `agent-device react-devtools status`.
+3. If no app is connected, start or wait for the devtools daemon, then reload or relaunch the app.
+4. Inspect with `get tree`, `find`, and `get component`.
+5. Profile only around the interaction being investigated.
+6. Verify the fix with the same command sequence and interaction.
+
+For cross-platform validation with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. Named sessions enable bound-session locks during setup. Restart `agent-device react-devtools` between iOS and Android runs so `status`, `get tree`, and profiling clearly refer to the currently launched app.
+
+## Main commands
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools wait --connected
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools find <ComponentName>
+agent-device react-devtools get component @c5
+agent-device react-devtools profile start
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+## Decision rules
+
+- Need current UI text, refs, screenshots, logs, network, or device metrics: use the `agent-device` skill.
+- Need props, state, hooks, component ownership, render causes, or React profiler data: use this skill.
+- Start component-tree reads with `get tree --depth 3` or `find <name>` to keep output bounded.
+- Labels like `@c5` reset when the app reloads or components remount. After reload, run `wait --connected` and inspect again.
+- Profiling only captures renders between `profile start` and `profile stop`.
+- On Android, set `adb reverse tcp:8097 tcp:8097` for React DevTools. If Metro is local, also set `adb reverse tcp:8081 tcp:8081`.
+
+## References
+
+| File                                    | When to read                                  |
+| --------------------------------------- | --------------------------------------------- |
+| [commands.md](references/commands.md)   | Command reference and common inspection flows |
+| [profiling.md](references/profiling.md) | Render profiling workflow and interpretation  |

package/skills/react-devtools/references/commands.md

@@ -0,0 +1,91 @@
+# React DevTools Commands
+
+All commands are run through `agent-device react-devtools`.
+
+## Connection
+
+```bash
+agent-device react-devtools start
+agent-device react-devtools stop
+agent-device react-devtools status
+agent-device react-devtools wait --connected --timeout 30
+agent-device react-devtools wait --component <ComponentName> --timeout 30
+```
+
+- `status` shows the daemon port, connected apps, component count, profiling state, uptime, and last connection event.
+- Most commands auto-start the daemon, but `start` is useful before launching or reloading the app.
+- React Native development builds connect to the daemon on port 8097. For Android emulators or physical devices, use `adb reverse tcp:8097 tcp:8097` if the app cannot reach the host. If the app also uses local Metro, set `adb reverse tcp:8081 tcp:8081`.
+
+## Validation Notes
+
+- When validating the same app across iOS and Android with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. A named `--session` enables bound-session lock behavior, so setup commands with explicit target selectors can be rejected.
+- Restart the React DevTools daemon between platforms so `status`, `get tree`, and profiling output belong to the currently launched app.
+- Verify the app is visibly loaded with `snapshot` before collecting React internals. Use `react-devtools` for component state and profiling, not for proving the device/app surface is open.
+
+## Component Inspection
+
+```bash
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools get component @c5
+agent-device react-devtools find Button
+agent-device react-devtools find Button --exact
+agent-device react-devtools count
+agent-device react-devtools errors
+```
+
+- `get tree` prints a component hierarchy with labels like `@c1`, `@c2`.
+- Use `--depth` on large apps. Start at `--depth 3` or `--depth 4`.
+- `get component` accepts a label or numeric React fiber id and shows props, state, and hooks.
+- `find` searches by display name. Use `--exact` when fuzzy results are noisy.
+- `errors` lists components with React-tracked warnings or errors.
+
+## Profiling
+
+```bash
+agent-device react-devtools profile start "interaction name"
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+agent-device react-devtools profile report @c5
+agent-device react-devtools profile timeline --limit 20
+agent-device react-devtools profile commit 3
+agent-device react-devtools profile export profile.json
+agent-device react-devtools profile diff before.json after.json --limit 10
+```
+
+- `profile slow` ranks components by average render duration.
+- `profile rerenders` ranks components by render count.
+- `profile report @cN` shows render causes and changed props/state/hooks for one component.
+- `profile timeline` lists commits. Use `--limit` and `--offset` for long sessions.
+- `profile export` writes React DevTools Profiler JSON that can be diffed later.
+
+## Common Flows
+
+Inspect a component:
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools get tree --depth 3
+agent-device react-devtools find SearchScreen
+agent-device react-devtools get component @c12
+```
+
+Profile a slow interaction:
+
+```bash
+agent-device react-devtools profile start "slow search"
+# Trigger the interaction with agent-device or ask the user to perform it.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+Verify a render fix:
+
+```bash
+agent-device react-devtools profile start "after fix"
+# Repeat the same interaction.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```

package/skills/react-devtools/references/profiling.md

@@ -0,0 +1,74 @@
+# React Native Profiling
+
+Use this workflow when the user reports slow interactions, excessive re-renders, unstable props, or unclear render causes.
+
+## Baseline
+
+```bash
+agent-device react-devtools status
+agent-device react-devtools count
+agent-device react-devtools get tree --depth 3
+```
+
+If the app is not connected, run:
+
+```bash
+agent-device react-devtools start
+agent-device react-devtools wait --connected
+```
+
+Then reload or relaunch the React Native app if needed.
+
+## Capture One Interaction
+
+```bash
+agent-device react-devtools profile start "short label"
+# Trigger exactly the interaction being investigated.
+agent-device react-devtools profile stop
+```
+
+Keep the profiling window narrow. Extra navigation, warm-up work, or unrelated gestures make the report harder to interpret.
+
+## Identify Suspects
+
+```bash
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+- A component with high average render time is a slow-render suspect.
+- A component with high render count is a re-render suspect.
+- A component can be both.
+
+## Drill In
+
+```bash
+agent-device react-devtools profile report @c12
+agent-device react-devtools get component @c12
+```
+
+Use `profile report` to identify render causes and changed keys. Use `get component` to inspect current props, state, and hooks.
+
+Common interpretations:
+
+| Signal                                     | Meaning                             | Typical follow-up                              |
+| ------------------------------------------ | ----------------------------------- | ---------------------------------------------- |
+| `props-changed` with function props        | Parent may pass unstable callbacks  | Check whether the parent can use `useCallback` |
+| `props-changed` with object or array props | Parent may pass unstable references | Check whether the parent can use `useMemo`     |
+| `parent-rendered` with many child renders  | Child has no bailout                | Check whether `React.memo` is appropriate      |
+| `state-changed`                            | Component state caused the render   | Check whether the state update is necessary    |
+| `hooks-changed`                            | Hook value or dependency changed    | Inspect hook values and dependencies           |
+
+## Verify
+
+After making a change, repeat the same interaction:
+
+```bash
+agent-device react-devtools profile start "after fix"
+# Repeat the same interaction.
+agent-device react-devtools profile stop
+agent-device react-devtools profile slow --limit 5
+agent-device react-devtools profile rerenders --limit 5
+```
+
+Compare render counts, average durations, changed keys, and commit counts against the baseline.

package/dist/src/4993.js

@@ -1 +0,0 @@
-let e=["android.shell","ios.runnerCommand","macos.desktopScreenshot"],n={"android.shell":"androidShell","ios.runnerCommand":"iosRunnerCommand","macos.desktopScreenshot":"macosDesktopScreenshot"};function o(e,n){return e.capabilities?.includes(n)??!1}function a(e,o){let a=n[o];return"function"==typeof e.escapeHatches?.[a]}export{n as BACKEND_CAPABILITY_ESCAPE_HATCH_METHODS,e as BACKEND_CAPABILITY_NAMES,o as hasBackendCapability,a as hasBackendEscapeHatch};