feat: add cdp command agent-cdp passthrough

[thymikee]

Summary

Add an agent-device cdp passthrough for React Native CDP diagnostics and JS heap leak workflows.

Details:

• Runs pinned agent-cdp@1.6.0 through npm exec, matching the existing react-devtools wrapper pattern while keeping agent-cdp as an internal implementation detail.
• Adds help cdp with the intended leak workflow: target select, heap usage samples, snapshot diff, leak-triplet, retainers, and allocation hotspots.
• Keeps JS heap evidence separate from native/process memory guidance under perf memory.

Refs #823.

Validation

Verified with focused CLI/parser tests and the repo quick check:

• ./node_modules/.bin/vitest run src/__tests__/cli-agent-cdp.test.ts src/utils/__tests__/args.test.ts
• pnpm check:quick

Manual prototype evidence came from Expo Go 56 on iOS simulator with a patched local agent-cdp: target selection succeeded, JS heap samples captured, heap snapshots diffed, leak-triplet flagged the retained object, and retainers pointed to the global retaining path.

Final-path smoke on the current branch is currently blocked because the pinned agent-cdp@1.6.0 package is not published to npm yet. The GitHub release exists at https://github.com/callstackincubator/agent-cdp/releases/tag/v1.6.0, but npm view agent-cdp version dist-tags --json still reports 1.5.1 as latest and npm view agent-cdp versions --json does not include 1.6.0. As a result, node bin/agent-device.mjs cdp target list --url http://127.0.0.1:8081 fails during npm exec --package agent-cdp@1.6.0 resolution with No matching version found for agent-cdp@1.6.0.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-25 19:44 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.3 MB	1.3 MB	+4.8 kB
JS gzip	433.9 kB	435.6 kB	+1.6 kB
npm tarball	571.6 kB	573.2 kB	+1.6 kB
npm unpacked	1.9 MB	1.9 MB	+4.9 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.1 ms	27.5 ms	+0.4 ms
CLI --help	47.1 ms	47.4 ms	+0.3 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli-help.js	+4.1 kB	+1.5 kB
dist/src/cli.js	+403 B	+56 B

[thymikee]

I found one blocker before this is review-ready.

agent-device agent-cdp is presented as a passthrough, but it only forwards positionals to agent-cdp (src/cli.ts:200). The parser consumes any recognized agent-device flag before that handoff: --json and --session are intentionally removed in the new test (src/utils/__tests__/args.test.ts:292), because shouldPassThroughLocalToolFlag forwards only unknown or unsupported flags (src/utils/args.ts:111).

That means downstream agent-cdp options that collide with agent-device flags, especially common ones like --json, --session, --target, --device, or --help, will not reach the pinned CLI unless the user knows to insert --. The help examples do not document that boundary, and the command no longer behaves like a 1:1 passthrough. Please either preserve all post-agent-cdp args for this local tool, or make the boundary contract explicit and add tests for colliding downstream flags so this behavior is deliberate.

[thymikee]

Review — feat: add agent-cdp passthrough

🤖 Automated review (Claude Code).

Overview
Adds agent-device agent-cdp, a passthrough that runs pinned agent-cdp@1.6.0 via npm exec, mirroring the existing react-devtools wrapper. Wires command-catalog (MCP-unexposed + capability-exempt), parser passthrough, help/docs, skillgym cases, and unit tests.

Strengths

• Faithful reuse of the react-devtools pattern (npm exec --yes --package … -- agent-cdp …, allowFailure, chunk streaming, exit-code passthrough).
• Version pinned to a single constant, and cli-agent-cdp.test.ts asserts the docs mention agent-cdp@1.6.0 — a nice guard against doc/version drift.
• Parser rename shouldPassThroughReactDevtoolsFlag → shouldPassThroughLocalToolFlag is accurate and covered.
• Strong help + skillgym coverage steering JS-heap vs native/process-memory routing (the three skillgym cases including the "native memory uses perf not CDP" negative case are good).

Notes / questions

1. Flag shadowing (sharp edge — consistent with react-devtools). Common flags (--json, --session, --platform, --target, …) are consumed by agent-device's parser and not forwarded to agent-cdp. The args test confirms this: --json/--session rn land in parsed.flags, not positionals. So agent-device agent-cdp memory usage diff --json won't make agent-cdp emit JSON; users must use the -- boundary (agent-cdp -- memory usage diff --json). This matches react-devtools and the -- escape hatch is tested — but agent-cdp's own --session/--json surface is broader, so consider one line in help agent-cdp pointing at the -- boundary for agent-cdp flags that collide with an agent-device global.
2. First-run fetch. npm exec --yes will download agent-cdp@1.6.0 on first use (network + execution). Same trust model as react-devtools, and pinning is the right call — maybe a one-liner in help noting the first run may download.

Risk: low. Isolated new command; the only change to existing behavior is the parser-helper rename, which is covered by args.test.ts.

[thymikee]

Addressed the flag-shadowing review comment in 3896c44.\n\nBefore: recognized agent-device flags after agent-cdp (for example --json, --session, --target, --device, --help) were consumed by the outer parser unless callers inserted --.\n\nAfter: every token after agent-cdp is preserved as downstream agent-cdp input; outer agent-device globals still work when placed before agent-cdp. I also added the first-run npm download note to help/docs.\n\nValidation: pnpm exec vitest run src/utils/__tests__/args.test.ts src/__tests__/cli-agent-cdp.test.ts, pnpm check:quick, pnpm format.

[thymikee]

Renamed the public CDP wrapper from agent-device agent-cdp to agent-device cdp in 4dfcf4d.\n\nPublic docs/help/SkillGym now teach cdp; agent-cdp remains only as the internal pinned npm package/bin used by the wrapper. Post-command passthrough semantics are unchanged: every token after cdp is forwarded to the CDP helper, and outer agent-device globals must go before cdp.\n\nValidation: pnpm exec vitest run src/utils/__tests__/args.test.ts src/__tests__/cli-agent-cdp.test.ts, pnpm check:quick, pnpm format. Focused SkillGym run was attempted but blocked by approval review due external model data export risk.

[thymikee]

Moved the public CDP workflow docs from website/docs/docs/commands.md to website/docs/docs/debugging-profiling.md in 278c0e8. The command reference no longer carries the React Native JS memory workflow, and the test now guards that location.\n\nValidation: pnpm exec vitest run src/__tests__/cli-agent-cdp.test.ts src/utils/__tests__/args.test.ts, pnpm check:quick, pnpm format.

[thymikee]

Adjusted the docs split in 3013047: commands.md now mentions representative agent-device cdp commands alongside the other profiling commands and links to Debugging & Profiling for the bounded leak workflow. The full workflow section remains only in website/docs/docs/debugging-profiling.md.\n\nValidation: pnpm exec vitest run src/__tests__/cli-agent-cdp.test.ts src/utils/__tests__/args.test.ts, pnpm check:quick, pnpm format.

[thymikee]

Follow-up review after the cdp rename/docs split: I do not see a code-path blocker in the diff.

One validation gap remains before I would call this fully merge-ready: the focused tests mock runCmdStreaming, so they prove argument construction but not that the shipped wrapper can run the released agent-cdp@1.6.0 package against a real Metro CDP target. The PR body mentions earlier Expo Go simulator prototype evidence with a patched local agent-cdp; please add one final-path smoke result for the current branch, for example:

• agent-device cdp target list --url http://127.0.0.1:8081
• agent-device cdp target select <target-id>
• one compact memory command such as agent-device cdp memory usage sample --label baseline --gc

If live RN/Metro validation is blocked, please state the exact blocker/device/app needed. After that, the residual risk looks low for this isolated CLI passthrough/docs slice.

[thymikee]

One small housekeeping item while adding the final-path smoke evidence: the PR body still describes the public command as agent-device agent-cdp / help agent-cdp, but the branch now exposes agent-device cdp / help cdp. Please update the summary/validation text so reviewers do not have to reconcile the old command name against the current diff.

[thymikee]

Addressed both follow-ups:

• Updated the PR body to use the current public command name: agent-device cdp / help cdp, with agent-cdp described only as the pinned internal package.
• Re-ran the final-path smoke attempt on the current branch after pnpm build with the Expo test app running on Expo Go 56 / iPhone 17 Pro simulator at Metro 8081.

Current-branch blocker:

node bin/agent-device.mjs cdp target list --url http://127.0.0.1:8081
npm error code ETARGET
npm error No matching version found for agent-cdp@1.6.0.

Registry check still shows the package is not published to npm:

npm view agent-cdp version dist-tags --json
{
  "version": "1.5.1",
  "dist-tags": { "latest": "1.5.1" }
}

npm view agent-cdp versions --json lists 1.0.0 through 1.5.1 only. The GitHub release exists (callstackincubator/agent-cdp@v1.6.0, published 2026-06-25T14:42:20Z), but npm exec --package agent-cdp@1.6.0 cannot resolve it yet, so the shipped agent-device cdp wrapper cannot reach target list until that npm publish is available.

I also sanity-checked the live Metro target with the latest published agent-cdp@1.5.1: target list sees host.exp.Exponent (iPhone 17 Pro), but target select fails with the known RN websocket origin rejection (401 / Expo expecting Origin: http://127.0.0.1:8081). I’m not counting that as PR validation since this branch intentionally pins the unreleased/pending 1.6.0 fix.