fix: preserve agent-cdp passthrough flags

Author: thymikee

src/utils/__tests__/args.test.ts

@@ -308,8 +308,8 @@ test('parseArgs preserves agent-cdp arguments as passthrough positionals', () =>
     { strictFlags: true },
   );
   assert.equal(parsed.command, 'agent-cdp');
-  assert.equal(parsed.flags.json, true);
-  assert.equal(parsed.flags.session, 'rn');
+  assert.equal(parsed.flags.json, false);
+  assert.equal(parsed.flags.session, undefined);
   assert.deepEqual(parsed.positionals, [
     'memory',
     'snapshot',
@@ -319,6 +319,46 @@ test('parseArgs preserves agent-cdp arguments as passthrough positionals', () =>
     '--compare',
     'ms_2',
     '--limit=10',
+    '--json',
+    '--session',
+    'rn',
+  ]);
+});
+
+test('parseArgs preserves agent-cdp help as a downstream flag', () => {
+  const parsed = parseArgs(['agent-cdp', '--help'], { strictFlags: true });
+  assert.equal(parsed.command, 'agent-cdp');
+  assert.equal(parsed.flags.help, false);
+  assert.deepEqual(parsed.positionals, ['--help']);
+});
+
+test('parseArgs accepts agent-device globals before agent-cdp passthrough args', () => {
+  const parsed = parseArgs(
+    [
+      '--session',
+      'outer-session',
+      'agent-cdp',
+      'target',
+      'list',
+      '--target',
+      'Hermes',
+      '--device',
+      'rn-app',
+      '--json',
+    ],
+    { strictFlags: true },
+  );
+  assert.equal(parsed.command, 'agent-cdp');
+  assert.equal(parsed.flags.session, 'outer-session');
+  assert.equal(parsed.flags.json, false);
+  assert.deepEqual(parsed.positionals, [
+    'target',
+    'list',
+    '--target',
+    'Hermes',
+    '--device',
+    'rn-app',
+    '--json',
   ]);
 });
 

src/utils/args.ts

@@ -59,6 +59,10 @@ export function parseRawArgs(argv: string[]): RawParsedArgs {
       else positionals.push(arg);
       continue;
     }
+    if (shouldPreservePostCommandArgs(command)) {
+      positionals.push(arg);
+      continue;
+    }
     const isLongFlag = arg.startsWith('--');
     const isShortFlag = arg.startsWith('-') && arg.length > 1;
     if (!isLongFlag && !isShortFlag) {
@@ -112,11 +116,15 @@ function shouldPassThroughLocalToolFlag(
   command: string | null,
   definition: FlagDefinition | undefined,
 ): boolean {
-  if (command !== 'react-devtools' && command !== 'agent-cdp') return false;
+  if (command !== 'react-devtools') return false;
   if (!definition) return true;
   return !isFlagSupportedForCommand(definition.key, command);
 }
 
+function shouldPreservePostCommandArgs(command: string | null): boolean {
+  return command === 'agent-cdp';
+}
+
 function resolveFlagDefinition(token: string, command: string | null): FlagDefinition | undefined {
   const definitions = getFlagDefinitions().filter((definition) => definition.names.includes(token));
   if (definitions.length <= 1) return definitions[0] ?? getFlagDefinition(token);

src/utils/cli-help.ts

@@ -501,6 +501,8 @@ Allocation pressure:
     agent-device agent-cdp memory allocation source-maps
 
 Recommended subset:
+  agent-cdp dynamically runs pinned agent-cdp@1.6.0 through npm; the first run may download the pinned package, and later runs can reuse the npm cache.
+  Every argument after agent-cdp is passed to agent-cdp. Put agent-device global flags before agent-cdp when you need the outer CLI to consume them.
   Use agent-cdp memory usage, memory snapshot, memory allocation, and targeted runtime eval.
   Avoid agent-cdp profile cpu, trace, network, and console by default because agent-device already has perf cpu, trace, network, logs, and react-devtools guidance for those areas.
 

website/docs/docs/commands.md

@@ -692,7 +692,8 @@ agent-device agent-cdp memory snapshot leak-triplet --baseline ms_1 --action ms_
 agent-device agent-cdp memory snapshot retainers --snapshot ms_3 --id <node-id> --depth 8 --limit 10
 ```
 
-- `agent-cdp` dynamically runs pinned `agent-cdp@1.6.0` through npm and passes arguments through 1:1.
+- `agent-cdp` dynamically runs pinned `agent-cdp@1.6.0` through npm; the first run may download the pinned package, and later runs can reuse the npm cache.
+- Every argument after `agent-cdp` is passed to `agent-cdp`. Put `agent-device` global flags before `agent-cdp` when you need the outer CLI to consume them.
 - Use it when a React Native or Expo app exposes a Metro CDP target and the task needs JavaScript heap usage, heap snapshots, allocation hotspots, retained-object diffs, retaining paths, or a small runtime eval to confirm JS state.
 - Start with `memory usage sample --gc` for a quick JS heap growth signal. Use snapshot diff and `leak-triplet` for proof that objects stayed retained after cleanup.
 - Until `agent-cdp` has a compact leak report command, synthesize one from `memory usage diff`, `memory snapshot diff`, `memory snapshot leak-triplet`, and `memory snapshot retainers`.