feat: support agent-cdp remote bridge sessions

[thymikee]

Summary

Add remote bridge session support for agent-device agent-cdp target discovery.

agent-cdp target list and target select now run after remote connection defaults/materialization, prepare deferred Metro runtime for bridge sessions, and inject the derived Metro CDP --url when the user did not pass one. Local passthrough behavior remains unchanged, and command/help docs now explain the remote bridge workflow.

Validation

Focused agent-cdp and remote-connection tests pass, including session/default wiring, Metro runtime preparation, URL injection, explicit URL preservation, and local passthrough behavior. pnpm check:quick, pnpm build, and git diff --check passed. A live ADC connect probe against the bridge control plane generated and disconnected an Android remote profile; full live agent-cdp target list was not run because the generated profile had no RN project root, so it would not have represented a real app/Metro session.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-878/
Built to branch gh-pages at 2026-06-25 19:49 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.3 MB	1.3 MB	+1.0 kB
JS gzip	436.5 kB	436.9 kB	+446 B
npm tarball	574.4 kB	574.8 kB	+422 B
npm unpacked	1.9 MB	1.9 MB	+1.0 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	24.3 ms	24.6 ms	+0.3 ms
CLI --help	42.5 ms	43.9 ms	+1.5 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli.js	+894 B	+391 B
dist/src/cli-help.js	+151 B	+55 B

[thymikee]

Review — feat: support agent-cdp remote bridge sessions

🤖 Automated review (Claude Code). Stacked on #873.

Overview
Moves the agent-cdp handler below remote materialization so it can derive a Metro CDP --url for target list/target select in remote bridge sessions, adds agent-cdp to runtimeDeferredCommands, and injects the URL via buildAgentCdpPassthroughArgs.

Strengths

• Handler placement is correct: it now runs after materializeRemoteConnectionForCommand (so resolvedRuntime/effectiveFlags are materialized) and before generic client dispatch. The gating is complete and consistent — agent-cdp is absent from REMOTE_MATERIALIZATION_DEFERRED_COMMANDS (so shouldMaterializeRemoteConnection is true) and present in runtimeDeferredCommands, so deferred runtime prep actually fires for real bridge sessions.
• normalizeCdpBaseUrl correctly strips query/hash/trailing-slash and the /index.bundle suffix; precedence (metroPublicBaseUrl → runtime.bundleUrl → metroHost:metroPort) is sensible.
• Good test matrix: public-url injection, runtime fallback, explicit---url preservation, missing-runtime throw, and end-to-end exec args.
• Local passthrough behavior is unchanged and explicit --url is preserved.

Main question — auth reachability of the proxy fallback
When metroPublicBaseUrl is absent and the URL is derived from metroProxyBaseUrl (…/api/metro/runtimes/runtime-1), can agent-cdp actually reach it? That proxy endpoint is the authenticated bridge, but runAgentCdpCommand forwards no bearer token (and agent-cdp 1.6.0 may not accept one). react-devtools handles this by standing up an authenticated companion (ensureReactDevtoolsCompanion with metroBearerToken); agent-cdp connects directly. So the metroPublicBaseUrl branch (tunneled/local, no auth) looks like the real happy path, and the proxy-base fallback may 401.

• Is metroPublicBaseUrl guaranteed to be set in real bridge sessions? If yes, consider dropping the proxy-base fallback (or erroring with a clearer hint) rather than emitting an unreachable URL. If no, agent-cdp likely needs the bearer token plumbed through.

Smaller notes

• isRemoteBridgeBackend only covers android-instance/ios-instance; any other remote backend silently skips injection and would fail downstream without --url. Fine if those are the only two, worth a comment otherwise.
• Side effect to confirm: every agent-cdp invocation in a remote session now goes through runtime materialization (lease heartbeat / Metro prepare), not just target list/select. Presumably intended (keeps the lease warm), but it adds per-command latency to memory … calls that don't need a fresh runtime.

[thymikee]

GitHub now reports this branch as conflicted against its stack base feat/agent-cdp-passthrough. Please rebase after #873 settles, resolve the conflicts, and reply with what changed plus the validation you reran. I am holding re-review until the branch is clean.

[thymikee]

Follow-up review after the rebase/retarget to main: I do not see the earlier proxy-auth code blocker anymore. The branch now refuses remote bridge CDP target discovery unless metroPublicBaseUrl is available (src/cli/commands/agent-cdp.ts:68), and runtime preparation for cdp target list/select is also gated on that public URL (src/cli/commands/connection-runtime.ts:302). That avoids emitting an authenticated /api/metro/... proxy URL that agent-cdp cannot reach.

Two items remain before I would call this merge-ready:

• The PR body still describes the public command as agent-device agent-cdp; the merged wrapper is agent-device cdp, with agent-cdp only as the internal npm package/bin.
• The validation still stops at ADC connect profile generation. This change is routing-sensitive and runtime-facing, so please add a final-path live result through a real remote bridge RN/Metro session, e.g. agent-device cdp target list and agent-device cdp target select after connect using a profile that has an RN project/runtime. If live validation is still blocked, state the exact missing app/profile/device requirement.

CI is green and the focused tests cover the URL-injection/error behavior; the remaining risk is the production bridge path.