test: cover agent-cdp guidance

Author: thymikee

skills/agent-device/SKILL.md

@@ -27,6 +27,7 @@ Escalate only when relevant:
 agent-device help debugging
 agent-device help react-native
 agent-device help react-devtools
+agent-device help agent-cdp
 agent-device help remote
 agent-device help macos
 agent-device help dogfood

test/skillgym/suites/agent-device-smoke-suite.ts

@@ -430,6 +430,8 @@ const BOUNDED_PROFILE_TIMELINE =
   /react-devtools\s+profile\s+timeline\b[^\n]*--limit\s+(?:10|20)\b/i;
 const BROAD_PROFILE_SLOW_LIMIT =
   /react-devtools\s+profile\s+slow\b[^\n]*--limit\s+(?:[5-9]\d|[1-9]\d{2,})\b/i;
+const AGENT_CDP_MEMORY_USAGE_SAMPLE = /agent-cdp\s+memory\s+usage\s+sample\b/i;
+const AGENT_CDP_MEMORY_SNAPSHOT_CAPTURE = /agent-cdp\s+memory\s+snapshot\s+capture\b/i;
 const IOS_EXPO_GO_OPEN =
   /(?:^|\n)(?:agent-device\s+)?open\s+["']Expo Go["']\s+["']?exp:\/\/127\.0\.0\.1:8081["']?/i;
 
@@ -1646,6 +1648,93 @@ const SKILL_GUIDANCE_CASES: Case[] = [
       plannedCommand('perf frames'),
     ],
   }),
+  makeCase({
+    id: 'react-native-js-heap-leak-cdp-triplet',
+    contract: [
+      'App name: Agent Device Tester',
+      'Platform: iOS simulator',
+      'Metro is running at http://127.0.0.1:8081',
+      'The app exposes a React Native CDP target through Metro',
+      'Symptom: JavaScript heap grows after opening and closing the Cart screen',
+      'Need proof that retained JS objects survive cleanup, plus shortest useful retaining paths',
+      'This is not a native/process memory investigation',
+    ],
+    task: 'Plan a bounded React Native JS heap leak workflow using agent-cdp: select the Metro CDP target, sample heap usage, capture baseline/action/cleanup snapshots, diff them, run leak-triplet, and inspect retainers for a leaked node.',
+    outputs: [
+      plannedCommand('agent-cdp target list'),
+      /--url\s+http:\/\/127\.0\.0\.1:8081/i,
+      plannedCommand('agent-cdp target select'),
+      AGENT_CDP_MEMORY_SNAPSHOT_CAPTURE,
+      /--name\s+baseline/i,
+      /--name\s+(?:after-action|action)/i,
+      /--name\s+cleanup/i,
+      plannedCommand('agent-cdp memory snapshot diff'),
+      plannedCommand('agent-cdp memory snapshot leak-triplet'),
+      plannedCommand('agent-cdp memory snapshot retainers'),
+    ],
+    forbiddenOutputs: [
+      plannedCommand('perf memory sample'),
+      plannedCommand('perf memory snapshot'),
+      plannedCommand('react-devtools'),
+      plannedCommand('agent-cdp profile cpu'),
+      plannedCommand('agent-cdp trace'),
+      plannedCommand('agent-cdp network'),
+      plannedCommand('agent-cdp console'),
+    ],
+  }),
+  makeCase({
+    id: 'react-native-js-heap-quick-signal-cdp',
+    contract: [
+      'App name: Agent Device Tester',
+      'Platform: Android emulator',
+      'Metro is running at http://127.0.0.1:8081',
+      'The app exposes a React Native CDP target through Metro',
+      'Symptom: JavaScript heap may grow after filtering the product list',
+      'Need only a compact first-pass JS heap growth signal before deciding whether to capture heap snapshots',
+      'This is not a native/process memory investigation',
+    ],
+    task: 'Plan the CDP commands to select the Metro target and collect compact before/after JavaScript heap usage samples with GC, then diff the usage samples.',
+    outputs: [
+      plannedCommand('agent-cdp target list'),
+      /--url\s+http:\/\/127\.0\.0\.1:8081/i,
+      plannedCommand('agent-cdp target select'),
+      AGENT_CDP_MEMORY_USAGE_SAMPLE,
+      /--label\s+baseline/i,
+      /--label\s+after-action/i,
+      plannedCommand('agent-cdp memory usage diff'),
+    ],
+    forbiddenOutputs: [
+      plannedCommand('perf memory sample'),
+      plannedCommand('perf memory snapshot'),
+      AGENT_CDP_MEMORY_SNAPSHOT_CAPTURE,
+      plannedCommand('react-devtools'),
+    ],
+  }),
+  makeCase({
+    id: 'react-native-native-memory-uses-perf-not-cdp',
+    contract: [
+      'App name: Agent Device Tester',
+      'Platform: Android emulator',
+      'The app is already open',
+      'Symptom: total process RSS/PSS grows while scrolling a native image gallery',
+      'Need native/process memory evidence and an Android heap artifact if escalation is needed',
+      'This is not a JavaScript heap or retained JS object investigation',
+    ],
+    task: 'Plan the memory diagnostics commands for this native/process memory issue without using CDP heap snapshots.',
+    outputs: [
+      plannedCommand('perf memory sample'),
+      /--json/i,
+      plannedCommand('perf memory snapshot'),
+      /--kind\s+android-hprof/i,
+      /--out\s+\S+\.hprof/i,
+    ],
+    forbiddenOutputs: [
+      /agent-cdp/i,
+      AGENT_CDP_MEMORY_USAGE_SAMPLE,
+      AGENT_CDP_MEMORY_SNAPSHOT_CAPTURE,
+      plannedCommand('react-devtools'),
+    ],
+  }),
   makeCase({
     id: 'perf-apple-xctrace-profile',
     contract: [

website/docs/docs/agent-setup.md

@@ -47,7 +47,7 @@ The bundled [agent-device skill](https://github.com/callstack/agent-device/blob/
 Add this as a project rule, custom instruction, or skill equivalent when your agent client supports it:
 
 ```text
-Use agent-device only for app/device automation tasks. Before planning commands, run `agent-device --version` and read `agent-device help workflow`. For exploratory QA, read `agent-device help dogfood`. For logs, network, traces, or runtime failures, read `agent-device help debugging`. For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`. For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
+Use agent-device only for app/device automation tasks. Before planning commands, run `agent-device --version` and read `agent-device help workflow`. For exploratory QA, read `agent-device help dogfood`. For logs, network, traces, or runtime failures, read `agent-device help debugging`. For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`. For React Native JavaScript heap growth, heap snapshots, or retained-object leaks, read `agent-device help agent-cdp`. For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
 
 Use MCP tools or the CLI in the integrated terminal. If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the command the same way the user would from a normal terminal session and run that absolute path instead. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the agent process `PATH` is the user's `PATH`. Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version. MCP exposes structured tools backed by the agent-device client; it does not expose generic shell execution. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
 ```
@@ -111,6 +111,7 @@ Before planning device work, run `agent-device --version` and read `agent-device
 For exploratory QA, read `agent-device help dogfood`.
 For logs, network, traces, or runtime failures, read `agent-device help debugging`.
 For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
+For React Native JavaScript heap growth, heap snapshots, or retained-object leaks, read `agent-device help agent-cdp`.
 For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
 
 Use the CLI in Cursor's integrated terminal.
@@ -199,6 +200,7 @@ Before planning device work, run `agent-device --version` and read `agent-device
 For exploratory QA, read `agent-device help dogfood`.
 For logs, network, traces, or runtime failures, read `agent-device help debugging`.
 For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
+For React Native JavaScript heap growth, heap snapshots, or retained-object leaks, read `agent-device help agent-cdp`.
 For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.
 
 Use the CLI in the integrated terminal.

website/docs/docs/installation.md

@@ -21,6 +21,7 @@ Use global install for normal agent workflows. It gives agents a stable `agent-d
 agent-device help workflow
 agent-device help debugging
 agent-device help react-devtools
+agent-device help agent-cdp
 ```
 
 Some agent clients run commands in an environment that differs from the user's normal install shell. If `agent-device` is missing in the agent terminal but was installed globally elsewhere, resolve the command the same way the user would from a normal terminal session, then use the absolute binary path for agent commands. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the agent process `PATH` is the user's `PATH`.

website/docs/docs/introduction.md

@@ -45,6 +45,7 @@ Installed CLI help is the version-matched operating guide. Start there before pl
 agent-device help workflow
 agent-device help debugging
 agent-device help react-devtools
+agent-device help agent-cdp
 agent-device help dogfood
 ```