agent-device 0.12.9 → 0.13.1

package/dist/src/index.d.ts

@@ -145,6 +145,7 @@ export declare type AgentDeviceClient = {
     };
     metro: {
         prepare: (options: MetroPrepareOptions) => Promise<MetroPrepareResult>;
+        reload: (options?: MetroReloadOptions) => Promise<MetroReloadResult>;
     };
     capture: {
         snapshot: (options?: CaptureSnapshotOptions) => Promise<CaptureSnapshotResult>;
@@ -1412,7 +1413,18 @@ declare type DaemonInstallSource = {
 } | {
     kind: 'path';
     path: string;
-};
+} | ({
+    kind: 'github-actions-artifact';
+    owner: string;
+    repo: string;
+} & ({
+    artifactId: number;
+} | {
+    runId: number;
+    artifactName: string;
+} | {
+    artifactName: string;
+}));
 
 declare type DaemonLockPolicy = 'reject' | 'strip';
 
@@ -1933,6 +1945,15 @@ export declare type MetroPrepareOptions = {
 
 export declare type MetroPrepareResult = PrepareMetroRuntimeResult;
 
+export declare type MetroReloadOptions = {
+    metroHost?: string;
+    metroPort?: number;
+    bundleUrl?: string;
+    timeoutMs?: number;
+};
+
+export declare type MetroReloadResult = ReloadMetroResult;
+
 /** Re-export of {@link SessionRuntimeHints} under the Metro-specific alias used by public API consumers. */
 declare type MetroRuntimeHints = SessionRuntimeHints;
 
@@ -2153,6 +2174,13 @@ declare type RefTarget_2 = {
     selector?: never;
 };
 
+declare type ReloadMetroResult = {
+    reloaded: true;
+    reloadUrl: string;
+    status: number;
+    body: string;
+};
+
 declare type RepeatedPressOptions = {
     count?: number;
     intervalMs?: number;
@@ -2164,11 +2192,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 +2482,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/dist/src/metro-companion.js

@@ -1 +1 @@
-import e from"node:fs";import{setTimeout as r}from"node:timers/promises";import{normalizeBaseUrl as t,METRO_COMPANION_RUN_ARG as a,ENV_SERVER_BASE_URL as s,ENV_LOCAL_BASE_URL as o,ENV_STATE_PATH as n,ENV_LAUNCH_URL as i,ENV_SCOPE_TENANT_ID as c,ENV_SCOPE_RUN_ID as f,ENV_BEARER_TOKEN as d,ENV_SCOPE_LEASE_ID as m}from"./320.js";async function l(e){var r,a;let s=await fetch(`${t(e.serverBaseUrl)}/api/metro/companion/register`,{method:"POST",headers:(r=e.serverBaseUrl,a=e.bearerToken,{authorization:`Bearer ${a}`,"content-type":"application/json",...r.includes("ngrok")?{"ngrok-skip-browser-warning":"1"}:{}}),body:JSON.stringify({...e.bridgeScope,local_base_url:t(e.localBaseUrl),...e.launchUrl?{launch_url:e.launchUrl}:{}})}),o=await s.json();if(!s.ok||!0!==o.ok||"string"!=typeof o.data?.ws_url)throw Error(`Failed to register Metro companion: ${JSON.stringify(o)}`);return{wsUrl:o.data.ws_url}}async function u(e){return"string"==typeof e?Buffer.from(e,"utf8"):e instanceof ArrayBuffer?Buffer.from(e):ArrayBuffer.isView(e)?Buffer.from(e.buffer,e.byteOffset,e.byteLength):"u">typeof Blob&&e instanceof Blob?Buffer.from(await e.arrayBuffer()):Buffer.from(String(e),"utf8")}async function p(e){return JSON.parse((await u(e.data)).toString("utf8"))}function y(e,r){1===e.readyState&&e.send(JSON.stringify(r))}async function g(e,r){1!==e.readyState&&await new Promise((t,a)=>{let s=()=>{i(),t()},o=()=>{i(),a(Error(`${r} WebSocket failed before opening.`))},n=()=>{i(),a(Error(`${r} WebSocket closed before opening.`))},i=()=>{e.removeEventListener("open",s),e.removeEventListener("error",o),e.removeEventListener("close",n)};e.addEventListener("open",s,{once:!0}),e.addEventListener("error",o,{once:!0}),e.addEventListener("close",n,{once:!0})})}async function w(e){e.readyState>=WebSocket.CLOSING||await new Promise(r=>{let t=()=>{a(),r()},a=()=>{e.removeEventListener("close",t),e.removeEventListener("error",t)};e.addEventListener("close",t,{once:!0}),e.addEventListener("error",t,{once:!0}),e.readyState>=WebSocket.CLOSING&&t()})}function b(e,r,t){try{e.close(1e3===r||r>=3e3&&r<=4999?r:3001,t)}catch{}}function h(r){return!r.statePath||e.existsSync(r.statePath)}async function S(e,r,a,s){var o,n;switch(r.type){case"ping":return void y(e,{type:"pong",timestamp:r.timestamp});case"http-request":try{let s=await fetch(new URL(r.path,`${t(a.localBaseUrl)}/`),{method:r.method,headers:r.headers,...r.bodyBase64?{body:Buffer.from(r.bodyBase64,"base64")}:{}}),o=Buffer.from(await s.arrayBuffer());y(e,{type:"http-response",requestId:r.requestId,status:s.status,headers:Object.fromEntries(s.headers.entries()),...o.length>0?{bodyBase64:o.toString("base64")}:{}})}catch(t){y(e,{type:"http-error",requestId:r.requestId,message:t instanceof Error?t.message:String(t)})}return;case"ws-open":{let n,i=new WebSocket((o=a.localBaseUrl,(n=new URL(r.path,`${t(o)}/`)).protocol="https:"===n.protocol?"wss:":"ws:",n.toString()));i.binaryType="arraybuffer";let c=!1;i.addEventListener("message",t=>{(async()=>{if(!c)return;let a=await u(t.data);y(e,{type:"ws-frame",streamId:r.streamId,dataBase64:a.toString("base64"),binary:"string"!=typeof t.data})})().catch(e=>{console.error(e instanceof Error?e.message:String(e))})}),i.addEventListener("close",t=>{s.delete(r.streamId),c&&y(e,{type:"ws-close",streamId:r.streamId,code:t.code,reason:t.reason})}),i.addEventListener("error",()=>{c&&y(e,{type:"ws-close",streamId:r.streamId,code:1011,reason:"Upstream WebSocket error."})}),s.set(r.streamId,i);try{await g(i,"Upstream"),c=!0,y(e,{type:"ws-open-result",streamId:r.streamId,success:!0,headers:{}})}catch(t){s.delete(r.streamId),b(i,1011,"open failed"),y(e,{type:"ws-open-result",streamId:r.streamId,success:!1,error:t instanceof Error?t.message:String(t)})}return}case"ws-frame":{let e=s.get(r.streamId);if(!e||1!==e.readyState)return;let t=Buffer.from(r.dataBase64,"base64");e.send(r.binary?t:t.toString("utf8"));return}case"ws-close":{let e=s.get(r.streamId);if(!e)return;s.delete(r.streamId),b(e,"number"==typeof(n=r.code)&&Number.isInteger(n)&&(1e3===n||n>=3e3&&n<=4999||n>=1001&&n<=1015&&1004!==n&&1005!==n&&1006!==n)?n:1011,r.reason??"bridge requested close");return}}}async function v(e){let t=new Map,a=setInterval(()=>{h(e)||process.exit(0)},250);for(a.unref();h(e);){try{let r=await l(e),a=new WebSocket(r.wsUrl);a.binaryType="arraybuffer",await g(a,"Bridge"),a.addEventListener("message",r=>{(async()=>{let s=await p(r);await S(a,s,e,t)})().catch(e=>{console.error(e instanceof Error?e.message:String(e))})}),await w(a),t.forEach(e=>b(e,1012,"bridge disconnected")),t.clear()}catch(r){if(!h(e))break;console.error(r instanceof Error?r.message:String(r))}if(!h(e))break;await r(1e3)}clearInterval(a)}(async function(e,r){let t=function(e,r){if(e[0]!==a)return null;let t=r[s]?.trim(),l=r[d]?.trim(),u=r[o]?.trim();if(!t||!l||!u)throw Error("Metro companion worker is missing required environment configuration.");let p=r[c]?.trim(),y=r[f]?.trim(),g=r[m]?.trim();if(!p||!y||!g)throw Error("Metro companion worker is missing required bridge scope configuration.");return{serverBaseUrl:t,bearerToken:l,localBaseUrl:u,bridgeScope:{tenantId:p,runId:y,leaseId:g},launchUrl:r[i]?.trim()||void 0,statePath:r[n]?.trim()||void 0}}(e,r);return!!t&&(await v(t),!0)})(process.argv.slice(2),process.env).catch(e=>{if(e instanceof Error&&e.message.includes("missing required environment")){console.error(e.message),process.exitCode=1;return}console.error(e instanceof Error?e.stack??e.message:String(e)),process.exitCode=1});
+import e from"node:fs";import{setTimeout as r}from"node:timers/promises";import{normalizeBaseUrl as t,ENV_REGISTER_PATH as s,ENV_STATE_PATH as o,ENV_LOCAL_BASE_URL as a,ENV_SESSION as n,ENV_UNREGISTER_PATH as i,ENV_BEARER_TOKEN as c,METRO_COMPANION_RUN_ARG as f,ENV_SERVER_BASE_URL as l,ENV_LAUNCH_URL as d,ENV_SCOPE_TENANT_ID as u,ENV_SCOPE_RUN_ID as m,ENV_SCOPE_LEASE_ID as p,REACT_DEVTOOLS_COMPANION_RUN_ARG as g,ENV_DEVICE_PORT as y}from"./320.js";function w(e,r){return{authorization:`Bearer ${r}`,"content-type":"application/json",...e.includes("ngrok")?{"ngrok-skip-browser-warning":"1"}:{}}}function h(e){return{...e.bridgeScope,...e.session?{session:e.session}:{},local_base_url:t(e.localBaseUrl),...e.devicePort?{device_port:e.devicePort}:{},...e.launchUrl?{launch_url:e.launchUrl}:{}}}async function b(e){let r,s,o=e.registerPath??"/api/metro/companion/register";try{r=await fetch(`${t(e.serverBaseUrl)}${o}`,{method:"POST",headers:w(e.serverBaseUrl,e.bearerToken),body:JSON.stringify(h(e)),signal:AbortSignal.timeout(5e3)})}catch(r){if(r instanceof Error&&"TimeoutError"===r.name)throw Error(`${o} timed out after 5000ms calling ${t(e.serverBaseUrl)}${o}`);throw r}let a=await r.text();try{s=a?JSON.parse(a):{}}catch{let e;throw Error(`Failed to register companion (${r.status}): invalid JSON response: ${(e=a.replaceAll(/\s+/g," ").trim()).length>300?`${e.slice(0,300)}...`:e}`)}if(!r.ok||!0!==s.ok||"string"!=typeof s.data?.ws_url)throw Error(`Failed to register companion (${r.status}): ${JSON.stringify(s)}`);return{wsUrl:s.data.ws_url}}async function v(e){let r=e.unregisterPath??null;if(r)try{await fetch(`${t(e.serverBaseUrl)}${r}`,{method:"POST",headers:w(e.serverBaseUrl,e.bearerToken),body:JSON.stringify(h(e)),signal:AbortSignal.timeout(2e3)})}catch(e){console.error(e instanceof Error?e.message:String(e))}}async function S(e){return"string"==typeof e?Buffer.from(e,"utf8"):e instanceof ArrayBuffer?Buffer.from(e):ArrayBuffer.isView(e)?Buffer.from(e.buffer,e.byteOffset,e.byteLength):"u">typeof Blob&&e instanceof Blob?Buffer.from(await e.arrayBuffer()):Buffer.from(String(e),"utf8")}async function E(e){return JSON.parse((await S(e.data)).toString("utf8"))}function I(e,r){1===e.readyState&&e.send(JSON.stringify(r))}async function B(e,r){1!==e.readyState&&await new Promise((t,s)=>{let o=()=>{i(),t()},a=()=>{i(),s(Error(`${r} WebSocket failed before opening.`))},n=()=>{i(),s(Error(`${r} WebSocket closed before opening.`))},i=()=>{e.removeEventListener("open",o),e.removeEventListener("error",a),e.removeEventListener("close",n)};e.addEventListener("open",o,{once:!0}),e.addEventListener("error",a,{once:!0}),e.addEventListener("close",n,{once:!0})})}async function k(e){e.readyState>=WebSocket.CLOSING||await new Promise(r=>{let t=()=>{s(),r()},s=()=>{e.removeEventListener("close",t),e.removeEventListener("error",t)};e.addEventListener("close",t,{once:!0}),e.addEventListener("error",t,{once:!0}),e.readyState>=WebSocket.CLOSING&&t()})}function L(e,r,t){try{e.close(1e3===r||r>=3e3&&r<=4999?r:3001,t)}catch{}}function U(r){return!r.statePath||e.existsSync(r.statePath)}async function $(e,r,s,o){var a,n;switch(r.type){case"ping":return void I(e,{type:"pong",timestamp:r.timestamp});case"http-request":try{let o=await fetch(new URL(r.path,`${t(s.localBaseUrl)}/`),{method:r.method,headers:r.headers,...r.bodyBase64?{body:Buffer.from(r.bodyBase64,"base64")}:{}}),a=Buffer.from(await o.arrayBuffer());I(e,{type:"http-response",requestId:r.requestId,status:o.status,headers:Object.fromEntries(o.headers.entries()),...a.length>0?{bodyBase64:a.toString("base64")}:{}})}catch(t){I(e,{type:"http-error",requestId:r.requestId,message:t instanceof Error?t.message:String(t)})}return;case"ws-open":{let n,i=new WebSocket((a=s.localBaseUrl,(n=new URL(r.path,`${t(a)}/`)).protocol="https:"===n.protocol?"wss:":"ws:",n.toString()));i.binaryType="arraybuffer";let c=!1;i.addEventListener("message",t=>{(async()=>{if(!c)return;let s=await S(t.data);I(e,{type:"ws-frame",streamId:r.streamId,dataBase64:s.toString("base64"),binary:"string"!=typeof t.data})})().catch(e=>{console.error(e instanceof Error?e.message:String(e))})}),i.addEventListener("close",t=>{o.delete(r.streamId),c&&I(e,{type:"ws-close",streamId:r.streamId,code:t.code,reason:t.reason})}),i.addEventListener("error",()=>{c&&I(e,{type:"ws-close",streamId:r.streamId,code:1011,reason:"Upstream WebSocket error."})}),o.set(r.streamId,i);try{await B(i,"Upstream"),c=!0,I(e,{type:"ws-open-result",streamId:r.streamId,success:!0,headers:{}})}catch(t){o.delete(r.streamId),L(i,1011,"open failed"),I(e,{type:"ws-open-result",streamId:r.streamId,success:!1,error:t instanceof Error?t.message:String(t)})}return}case"ws-frame":{let e=o.get(r.streamId);if(!e||1!==e.readyState)return;let t=Buffer.from(r.dataBase64,"base64");e.send(r.binary?t:t.toString("utf8"));return}case"ws-close":{let e=o.get(r.streamId);if(!e)return;o.delete(r.streamId),L(e,"number"==typeof(n=r.code)&&Number.isInteger(n)&&(1e3===n||n>=3e3&&n<=4999||n>=1001&&n<=1015&&1004!==n&&1005!==n&&1006!==n)?n:1011,r.reason??"bridge requested close");return}}}async function P(e){let t=new Map,s=!1,o=null,a=!1,n=()=>{s||(s=!0,a&&v(e).finally(()=>process.exit(0)),o&&L(o,1e3,"companion stopping"),setTimeout(()=>process.exit(0),900).unref())};process.once("SIGTERM",n),process.once("SIGINT",n);let i=setInterval(()=>{U(e)||process.exit(0)},250);for(i.unref();!s&&U(e);){let n=!1;try{a=!1;let r=await b(e);if(n=!0,a=!0,s||!U(e)){await v(e),n=!1,a=!1;break}let i=new WebSocket(r.wsUrl);o=i,i.binaryType="arraybuffer";try{await B(i,"Bridge"),i.addEventListener("message",r=>{(async()=>{let s=await E(r);await $(i,s,e,t)})().catch(e=>{console.error(e instanceof Error?e.message:String(e))})}),await k(i)}finally{o=null,a=!1,t.forEach(e=>L(e,1012,"bridge disconnected")),t.clear(),n&&(await v(e),n=!1)}}catch(r){if(o=null,a=!1,n&&(await v(e),n=!1),s||!U(e))break;console.error(r instanceof Error?r.message:String(r))}if(s||!U(e))break;await r(1e3)}clearInterval(i)}(async function(e,r){let t=function(e,r){let t=e[0];if(t!==f&&t!==g)return null;let w=r[l]?.trim(),h=r[c]?.trim(),b=r[a]?.trim();if(!w||!h||!b)throw Error("Metro companion worker is missing required environment configuration.");let v=r[u]?.trim(),S=r[m]?.trim(),E=r[p]?.trim();if(!v||!S||!E)throw Error("Metro companion worker is missing required bridge scope configuration.");return{serverBaseUrl:w,bearerToken:h,localBaseUrl:b,bridgeScope:{tenantId:v,runId:S,leaseId:E},launchUrl:r[d]?.trim()||void 0,statePath:r[o]?.trim()||void 0,registerPath:r[s]?.trim()||void 0,unregisterPath:r[i]?.trim()||void 0,devicePort:function(e){if(!e?.trim())return;let r=Number.parseInt(e,10);if(!Number.isInteger(r)||r<1||r>65535)throw Error("Companion worker received invalid device port configuration.");return r}(r[y]),session:r[n]?.trim()||void 0}}(e,r);return!!t&&(await P(t),!0)})(process.argv.slice(2),process.env).catch(e=>{if(e instanceof Error&&e.message.includes("missing required environment")){console.error(e.message),process.exitCode=1;return}console.error(e instanceof Error?e.stack??e.message:String(e)),process.exitCode=1});

package/dist/src/metro.d.ts

@@ -187,6 +187,27 @@ export declare type PrepareRemoteMetroResult = {
     logPath: string;
 };
 
+declare type ReloadMetroOptions = {
+    metroHost?: string;
+    metroPort?: number | string;
+    bundleUrl?: string;
+    runtime?: MetroRuntimeHints;
+    timeoutMs?: number | string;
+};
+
+declare type ReloadMetroResult = {
+    reloaded: true;
+    reloadUrl: string;
+    status: number;
+    body: string;
+};
+
+export declare function reloadRemoteMetro(options?: ReloadRemoteMetroOptions): Promise<ReloadRemoteMetroResult>;
+
+export declare type ReloadRemoteMetroOptions = ReloadMetroOptions;
+
+export declare type ReloadRemoteMetroResult = ReloadMetroResult;
+
 export declare function resolveRuntimeTransport(runtime: SessionRuntimeHints | undefined): {
     host: string;
     port: number;

package/dist/src/metro.js

@@ -1 +1 @@
-import{buildMetroRuntimeHints as e,ensureMetroCompanion as t,stopMetroCompanion as r,prepareMetroRuntime as o}from"./1974.js";import{resolveRuntimeTransportHints as n}from"./9323.js";function i(e){return n(e)}async function s(e){let t=await o({projectRoot:e.projectRoot,kind:e.kind,publicBaseUrl:e.publicBaseUrl,proxyBaseUrl:e.proxyBaseUrl,proxyBearerToken:e.proxyBearerToken,bridgeScope:e.bridgeScope,launchUrl:e.launchUrl,companionProfileKey:e.profileKey,companionConsumerKey:e.consumerKey,metroPort:e.port,listenHost:e.listenHost,statusHost:e.statusHost,startupTimeoutMs:e.startupTimeoutMs,probeTimeoutMs:e.probeTimeoutMs,reuseExisting:e.reuseExisting,installDependenciesIfNeeded:e.installDependenciesIfNeeded,runtimeFilePath:e.runtimeFilePath,logPath:e.logPath,env:e.env});return{iosRuntime:t.iosRuntime,androidRuntime:t.androidRuntime,bridge:t.bridge,started:t.started,reused:t.reused,logPath:t.logPath}}async function u(e){let r=await t(e);return{pid:r.pid,started:r.spawned,logPath:r.logPath}}async function a(e){await r(e)}function l(t){return e(t,"ios")}function d(t){return e(t,"android")}export{buildBundleUrl,normalizeBaseUrl}from"./320.js";export{d as buildAndroidRuntimeHints,l as buildIosRuntimeHints,u as ensureMetroTunnel,s as prepareRemoteMetro,i as resolveRuntimeTransport,a as stopMetroTunnel};
+import{buildMetroRuntimeHints as e,ensureMetroCompanion as t,reloadMetro as r,stopMetroCompanion as o,prepareMetroRuntime as n}from"./1974.js";import{resolveRuntimeTransportHints as i}from"./8656.js";function s(e){return i(e)}async function a(e){let t=await n({projectRoot:e.projectRoot,kind:e.kind,publicBaseUrl:e.publicBaseUrl,proxyBaseUrl:e.proxyBaseUrl,proxyBearerToken:e.proxyBearerToken,bridgeScope:e.bridgeScope,launchUrl:e.launchUrl,companionProfileKey:e.profileKey,companionConsumerKey:e.consumerKey,metroPort:e.port,listenHost:e.listenHost,statusHost:e.statusHost,startupTimeoutMs:e.startupTimeoutMs,probeTimeoutMs:e.probeTimeoutMs,reuseExisting:e.reuseExisting,installDependenciesIfNeeded:e.installDependenciesIfNeeded,runtimeFilePath:e.runtimeFilePath,logPath:e.logPath,env:e.env});return{iosRuntime:t.iosRuntime,androidRuntime:t.androidRuntime,bridge:t.bridge,started:t.started,reused:t.reused,logPath:t.logPath}}async function u(e){let r=await t(e);return{pid:r.pid,started:r.spawned,logPath:r.logPath}}async function l(e){await o(e)}async function d(e={}){return await r(e)}function p(t){return e(t,"ios")}function m(t){return e(t,"android")}export{buildBundleUrl,normalizeBaseUrl}from"./320.js";export{m as buildAndroidRuntimeHints,p as buildIosRuntimeHints,u as ensureMetroTunnel,a as prepareRemoteMetro,d as reloadRemoteMetro,s as resolveRuntimeTransport,l as stopMetroTunnel};

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.1",
+  "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
@@ -16,6 +16,7 @@ Use this skill as a router with mandatory defaults. Read this file first. For no
 - Prefer `diff snapshot` after a nearby mutation when you only need to know what changed.
 - Avoid speculative mutations. You may take the smallest reversible UI action needed to unblock inspection or complete the requested task, such as dismissing a popup, closing an alert, or clearing an unintended surface.
 - In React Native dev or debug builds, check early for visible warning or error overlays, tooltips, and toasts that can steal focus or intercept taps. If they are not part of the requested behavior, dismiss them and continue. If you saw them, report them in the final summary.
+- In Metro-backed React Native dev loops, use `agent-device metro reload` for a JS app reload before falling back to `open <app> --relaunch`. It mirrors pressing `r` in the Metro terminal and preserves the native app process.
 - Do not browse the web or use external sources unless the user explicitly asks.
 - Re-snapshot after meaningful UI changes instead of reusing stale refs.
 - Treat refs in default snapshot output as actionable-now, not durable identities. If a target appears only in an off-screen summary, use `scroll <direction>` and re-snapshot until the target is visible.
@@ -60,6 +61,7 @@ Use this skill as a router with mandatory defaults. Read this file first. For no
 - If there is no simulator, no app install, or no open app session yet, switch to `bootstrap-install.md` instead of improvising setup steps.
 - Use the smallest unblock action first when transient UI blocks inspection, but do not navigate, search, or enter new text just to make the UI reveal data unless the user asked for that interaction.
 - In React Native dev or debug apps, treat visible warning or error overlays as transient blockers unless the user is explicitly asking you to diagnose them. Dismiss them when safe, then continue the requested flow.
+- For React Native code changes where the app is already connected to Metro, prefer `agent-device metro reload`, then wait and re-snapshot. Use `open <app> --relaunch` only when Metro reload does not reconnect or native startup state must reset.
 - Do not use external lookups to compensate for missing on-screen data unless the user asked for them.
 - If the needed information is not exposed on screen, say that plainly instead of compensating with extra navigation, text entry, or web search.
 - Prefer `@ref` or selector targeting over raw coordinates.
@@ -71,3 +73,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/bootstrap-install.md

@@ -18,6 +18,7 @@ Use this exact order when you are not sure about the installed app identifier. O
 
 - `install` or `reinstall`
 - `install-from-source` when the artifact already exists at a URL the daemon can reach
+- `install-from-source --github-actions-artifact` when a compatible remote daemon should resolve a GitHub Actions artifact
 
 ## Most common mistake to avoid
 
@@ -35,8 +36,6 @@ After setup is confirmed or completed, move to `exploration.md` before doing UI
 - If `open <app>` fails, run `agent-device apps` and retry with a discovered app name before considering install steps.
 - Do not install or reinstall on the first attempt unless the user explicitly asks for installation or provides a concrete artifact path or URL.
 - When installation is required from a known location, prefer a checked-in shell script or other deterministic bootstrap command over ad hoc path guessing.
-
-- If `open <app>` fails, or you are not sure which app name is available on the target, run `agent-device apps` first and choose from the discovered app list instead of guessing.
 - Use `apps --platform <platform>` together with `--device`, `--udid`, or `--serial` when target selection matters.
 - Once you have the correct app name, retry `open` with that exact discovered value.
 
@@ -64,8 +63,27 @@ agent-device install com.example.app ./build/MyApp.app --platform ios --device "
 ```bash
 ARTIFACT_URL="<trusted-artifact-url>"
 agent-device install-from-source "$ARTIFACT_URL" --platform android
-GITHUB_ARTIFACT_URL="<trusted-github-actions-artifact-api-url>"
-agent-device install-from-source "$GITHUB_ARTIFACT_URL" --platform ios --header "authorization: Bearer TOKEN"
+```
+
+Daemon-resolved GitHub Actions artifacts:
+
+```bash
+agent-device install-from-source \
+  --github-actions-artifact ORG/REPO:1234567890 \
+  --platform android
+```
+
+Project config can provide an artifact name instead:
+
+```json
+{
+  "platform": "android",
+  "installSource": {
+    "type": "github-actions-artifact",
+    "repo": "ORG/REPO",
+    "artifact": "app-debug"
+  }
+}
 ```
 
 ## Install guidance
@@ -73,6 +91,7 @@ agent-device install-from-source "$GITHUB_ARTIFACT_URL" --platform ios --header
 - Use `install <app> <path>` when the app may already be installed and you do not need a fresh-state reset.
 - Use `reinstall <app> <path>` when you explicitly need uninstall plus install as one deterministic step.
 - Use `install-from-source <url>` only when an existing artifact URL is trusted, operator-approved, and reachable by the daemon.
+- Use `--github-actions-artifact <org>/<repo>:<artifact>` when a compatible remote daemon should resolve a GitHub Actions artifact. Numeric artifacts are IDs; non-numeric artifacts are names.
 - Local `.apk`, `.aab`, `.app`, and `.ipa` paths go through `install` or `reinstall`; existing reachable URLs go through `install-from-source`.
 - Do not download, re-zip, publish temporary GitHub releases, or move CI artifacts elsewhere just to make an install command work.
 - Keep install and open as separate phases. Do not turn them into one default command flow.
@@ -80,10 +99,10 @@ agent-device install-from-source "$GITHUB_ARTIFACT_URL" --platform ios --header
   - Android: `.apk` and `.aab`
   - iOS: `.app` and `.ipa`
 - Android URL sources can be direct `.apk` or `.aab` files.
-- Trusted artifact service URLs, currently GitHub Actions and EAS, may point at archive-backed downloads that contain one installable artifact. This includes GitHub Actions artifact ZIPs whose URL path does not end in `.zip` and ZIPs containing one nested `.apk`, `.aab`, `.ipa`, or iOS `.app` tar archive.
+- Trusted artifact service URLs may point at archive-backed downloads that contain one installable artifact. Prefer `--github-actions-artifact` for GitHub Actions artifacts that a compatible remote daemon can resolve with its own credentials.
 - If a trusted artifact archive contains multiple installables, stop and ask for the intended artifact instead of guessing.
 - `.aab` still requires `bundletool` in `PATH`, or `AGENT_DEVICE_BUNDLETOOL_JAR=<absolute-path-to-bundletool-all.jar>` with `java` in `PATH`, when the daemon installs the materialized artifact.
-- For iOS `.ipa` files, `<app>` is used as the bundle id or bundle name hint when the archive contains multiple app bundles.
+- For `.ipa` archives with multiple app bundles, `<app>` is the bundle id or bundle name selection hint.
 - After install or reinstall, later use `open <app>` with the exact discovered or known package/bundle identifier, not the artifact path.
 
 ## Choose the right starting point
@@ -115,6 +134,7 @@ agent-device --session auth snapshot -i
 - Use semantic session names when you need multiple concurrent runs.
 - Use `--save-script=<path>` on `close` when you want to keep a replay script.
 - For dev loops where state can linger, prefer `open <app> --relaunch`.
+- For Metro-backed React Native JS changes with the app already running, prefer `metro reload` instead of `open <app> --relaunch`; it asks Metro to reload connected apps without restarting the native process.
 - In iOS sessions, use `open <app>` for the app itself. Use `open <url>` for deep links, and `open <app> <url>` when you need to launch the app and deep link in one step.
 - On iOS, `appstate` is session-scoped and requires the matching active session on the target device.
 

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,8 @@ 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
+- User asks to reload a Metro-backed React Native app after JS changes: `agent-device metro reload`, then wait briefly and re-run `snapshot` or `snapshot -i`
 - 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 +51,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.
 
@@ -58,6 +61,16 @@ Open this file when the app or screen is already running and you need to discove
 - Blocking or recurring: switch to [debugging.md](debugging.md) and collect evidence.
 - Seen at any point: mention in the final summary even if dismissed.
 
+**React Native Metro reload.** When a dev app is already running and connected to Metro, prefer a Metro reload over restarting the native app process:
+
+```bash
+agent-device metro reload
+agent-device wait 1000
+agent-device snapshot -i
+```
+
+Use `--metro-host`, `--metro-port`, or `--bundle-url` only when the active connection does not already carry the right runtime hints. Fall back to `open <app> --relaunch` when the app is not connected to Metro, Metro reload fails, or native startup state needs a clean process.
+
 ## Common example loops
 
 These are examples, not required exact sequences. Adapt them to the app, state, and task at hand.
@@ -222,7 +235,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/remote-tenancy.md

@@ -8,7 +8,9 @@ Open this file for remote daemon HTTP flows that let an agent running in a Linux
 
 - `agent-device connect --remote-config <path>`
 - `agent-device install-from-source <url> --remote-config <path> --platform android`
+- `agent-device install-from-source --github-actions-artifact <org>/<repo>:<artifact> --remote-config <path> --platform android`
 - `agent-device open <package> --remote-config <path> --relaunch`
+- `agent-device metro reload --remote-config <path>`
 - `agent-device snapshot --remote-config <path> -i`
 - `agent-device disconnect --remote-config <path>`
 - `agent-device connection status`
@@ -36,6 +38,7 @@ agent-device connect --remote-config ./remote-config.json
 ARTIFACT_URL="<trusted-artifact-url>"
 agent-device install-from-source "$ARTIFACT_URL" --platform android
 agent-device open com.example.app --relaunch
+agent-device metro reload
 agent-device snapshot -i
 agent-device fill @e3 "test@example.com"
 agent-device disconnect
@@ -73,6 +76,7 @@ The first command that needs a lease or Metro runtime prepares and persists it.
 - `connect` stores local non-secret connection state and defers tenant lease allocation plus Metro preparation until a later command needs them.
 - Commands such as `install-from-source`, `open`, `snapshot`, and `apps` allocate or refresh the lease when needed.
 - `open` prepares Metro runtime hints when the remote profile has Metro fields and no compatible runtime is already saved.
+- `metro reload` reuses saved Metro runtime hints and asks Metro to reload connected React Native apps without restarting the native process.
 - `batch` also prepares Metro when any step opens an app and that step does not provide its own runtime.
 - `disconnect` closes the session when possible, stops the Metro companion owned by the connection, releases the lease when one was allocated, and removes local connection state.
 
@@ -82,12 +86,11 @@ Remote install examples:
 agent-device install com.example.app ./app.apk
 ARTIFACT_URL="<trusted-artifact-url>"
 agent-device install-from-source "$ARTIFACT_URL" --platform android
-GITHUB_ARTIFACT_URL="<trusted-github-actions-artifact-api-url>"
-agent-device install-from-source "$GITHUB_ARTIFACT_URL" --platform ios --header "authorization: Bearer TOKEN"
 ```
 
 - Use `install` or `reinstall` for local paths; remote daemons upload local artifacts automatically.
 - Use `install-from-source` only for trusted, operator-approved artifact URLs the remote daemon can reach. Do not fetch arbitrary user-supplied URLs.
+- Use `install-from-source --github-actions-artifact <org>/<repo>:<artifact>` when the remote daemon has repository credentials and supports daemon-resolved GitHub Actions artifacts.
 - For local-path versus URL artifact rules, follow [bootstrap-install.md](bootstrap-install.md).
 
 Use `agent-device connection status --session adc-android` to inspect the active connection without reading JSON state manually. Status output must not include auth tokens.
@@ -135,30 +138,47 @@ Optional overrides stay available for advanced cases:
 - Start the daemon in HTTP mode with `AGENT_DEVICE_DAEMON_SERVER_MODE=http|dual` on the host.
 - Point the profile or env at the remote host with `daemonBaseUrl` or `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]`.
 - For non-loopback remote hosts, set `AGENT_DEVICE_DAEMON_AUTH_TOKEN` or `--daemon-auth-token`. The client rejects non-loopback remote daemon URLs without auth.
-- Direct JSON-RPC callers can authenticate with request params, `Authorization: Bearer <token>`, or `x-agent-device-token`.
 - Prefer an auth hook such as `AGENT_DEVICE_HTTP_AUTH_HOOK` when the host needs caller validation or tenant injection.
 
-## Manual lease debug fallback
+## Lease debug fallback
 
-The main agent flow should use `connect`. Use manual JSON-RPC only for host-side automation or daemon-side auth/scope debugging, and only against trusted daemon hosts.
+The main agent flow should use `connect` and `connection status`. For daemon-side auth, scope, or lease debugging, inspect host-side daemon logs and operator tooling instead of issuing raw daemon RPC from the agent shell.
+
+## GitHub Actions artifact install
+
+Use this when a compatible remote daemon resolves GitHub Actions artifacts server-side. Do not download CI artifacts locally or add a local `GITHUB_TOKEN` just to install CI output.
+
+Artifact ID shape:
+
+```bash
+agent-device install-from-source \
+  --github-actions-artifact OWNER/REPO:1234567890 \
+  --remote-config ./remote-config.json \
+  --platform android
+```
+
+Artifact-name shape:
 
 ```bash
-curl -fsS "$AGENT_DEVICE_DAEMON_BASE_URL/rpc" \
-  -H "Authorization: Bearer $AGENT_DEVICE_DAEMON_AUTH_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": "lease-1",
-    "method": "agent_device.lease.allocate",
-    "params": {
-      "tenantId": "acme",
-      "runId": "run-123",
-      "backend": "android-instance"
-    }
-  }'
+agent-device install-from-source \
+  --github-actions-artifact OWNER/REPO:app-debug \
+  --remote-config ./remote-config.json \
+  --platform ios
+```
+
+Config shape:
+
+```json
+{
+  "installSource": {
+    "type": "github-actions-artifact",
+    "repo": "OWNER/REPO",
+    "artifact": "app-debug"
+  }
+}
 ```
 
-Related daemon methods are `agent_device.lease.allocate`, `agent_device.lease.heartbeat`, `agent_device.lease.release`, and `agent_device.command`.
+Numeric artifacts are passed as artifact IDs. Non-numeric artifacts are passed as artifact names.
 
 ## Failure semantics and trust notes
 

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,55 @@
+---
+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`.
+- For Android sessions connected through `agent-device connect --remote-config`, run `agent-device react-devtools ...` normally. The CLI registers a bridge companion tunnel to the local DevTools daemon on `127.0.0.1:8097` and unregisters it when the command exits.
+- Remote Android React DevTools assumes the React Native-bundled DevTools behavior in React Native 0.83+. Do not assume older browser/Chromium DevTools workflows exist in remote sandboxes. For Expo apps, verify the SDK's bundled React Native version and runtime behavior first; no Expo SDK version is separately verified by this skill.
+
+## 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
+```