feat: add Metro reload command (#440)

Author: thymikee

skills/agent-device/SKILL.md

@@ -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.

skills/agent-device/references/bootstrap-install.md

@@ -115,6 +115,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.
 

skills/agent-device/references/exploration.md

@@ -21,6 +21,7 @@ Open this file when the app or screen is already running and you need to discove
 - 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
@@ -60,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.

skills/agent-device/references/remote-tenancy.md

@@ -9,6 +9,7 @@ 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 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 +37,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 +75,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.
 

src/__tests__/cli-client-commands.test.ts

@@ -10,6 +10,7 @@ import type {
   AppInstallFromSourceOptions,
   AppOpenOptions,
   MetroPrepareOptions,
+  MetroReloadOptions,
 } from '../client.ts';
 import { AppError } from '../utils/errors.ts';
 import { resolveCliOptions } from '../utils/cli-options.ts';
@@ -195,6 +196,50 @@ test('metro prepare rejects when no public or proxy base URL is provided', async
   );
 });
 
+test('metro reload forwards host, port, bundle URL, and timeout to client.metro.reload', async () => {
+  let observed: MetroReloadOptions | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+    reloadMetro: async (options) => {
+      observed = options;
+      return {
+        reloaded: true,
+        reloadUrl: 'http://127.0.0.1:9090/reload',
+        status: 200,
+        body: 'OK',
+      };
+    },
+  });
+
+  const stdout = await captureStdout(async () => {
+    const handled = await tryRunClientBackedCommand({
+      command: 'metro',
+      positionals: ['reload'],
+      flags: {
+        json: false,
+        help: false,
+        version: false,
+        metroHost: '127.0.0.1',
+        metroPort: 9090,
+        bundleUrl: 'http://127.0.0.1:9090/index.bundle?platform=ios',
+        metroProbeTimeoutMs: 1500,
+      },
+      client,
+    });
+    assert.equal(handled, true);
+  });
+
+  assert.deepEqual(observed, {
+    metroHost: '127.0.0.1',
+    metroPort: 9090,
+    bundleUrl: 'http://127.0.0.1:9090/index.bundle?platform=ios',
+    timeoutMs: 1500,
+  });
+  assert.equal(stdout, 'Reloaded React Native apps via http://127.0.0.1:9090/reload\n');
+});
+
 test('screenshot forwards --overlay-refs to the client capture API', async () => {
   let observed:
     | {
@@ -578,6 +623,7 @@ async function captureStdout(run: () => Promise<void>): Promise<string> {
 function createStubClient(params: {
   installFromSource: AgentDeviceClient['apps']['installFromSource'];
   prepareMetro?: AgentDeviceClient['metro']['prepare'];
+  reloadMetro?: AgentDeviceClient['metro']['reload'];
   open?: AgentDeviceClient['apps']['open'];
   screenshot?: AgentDeviceClient['capture']['screenshot'];
 }): AgentDeviceClient {
@@ -683,6 +729,14 @@ function createStubClient(params: {
           },
           bridge: null,
         })),
+      reload:
+        params.reloadMetro ??
+        (async () => ({
+          reloaded: true,
+          reloadUrl: 'http://127.0.0.1:8081/reload',
+          status: 200,
+          body: 'OK',
+        })),
     },
     capture: {
       snapshot: async () => ({

src/__tests__/client-metro.test.ts

@@ -8,7 +8,7 @@ import type { Socket } from 'node:net';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
-import { prepareMetroRuntime } from '../client-metro.ts';
+import { prepareMetroRuntime, reloadMetro } from '../client-metro.ts';
 import { AppError } from '../utils/errors.ts';
 
 const TEST_TOKEN = 'agent-device-proxy-test-token';
@@ -199,6 +199,65 @@ test('prepareMetroRuntime rejects incomplete proxy configuration', async () => {
   );
 });
 
+test('reloadMetro preserves the bundle URL route prefix', async () => {
+  const requests: string[] = [];
+  const server = createServer((req, res) => {
+    requests.push(req.url ?? '');
+    if (req.url === '/metro/runtime-1/reload') {
+      res.statusCode = 200;
+      res.end('OK');
+      return;
+    }
+    res.statusCode = 404;
+    res.end('not found');
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const address = server.address();
+  assert.ok(address && typeof address !== 'string');
+
+  try {
+    const result = await reloadMetro({
+      bundleUrl: `http://127.0.0.1:${address.port}/metro/runtime-1/index.bundle?platform=ios&dev=true`,
+      timeoutMs: 1_000,
+    });
+
+    assert.deepEqual(requests, ['/metro/runtime-1/reload']);
+    assert.deepEqual(result, {
+      reloaded: true,
+      reloadUrl: `http://127.0.0.1:${address.port}/metro/runtime-1/reload`,
+      status: 200,
+      body: 'OK',
+    });
+  } finally {
+    await closeServer(server);
+  }
+});
+
+test('reloadMetro defaults to local Metro host and port', async () => {
+  const server = createServer((req, res) => {
+    if (req.url === '/reload') {
+      res.statusCode = 200;
+      res.end('OK');
+      return;
+    }
+    res.statusCode = 404;
+    res.end('not found');
+  });
+  server.listen(0);
+  await once(server, 'listening');
+  const address = server.address();
+  assert.ok(address && typeof address !== 'string');
+
+  try {
+    const result = await reloadMetro({ metroPort: address.port, timeoutMs: 1_000 });
+    assert.equal(result.reloadUrl, `http://localhost:${address.port}/reload`);
+    assert.equal(result.body, 'OK');
+  } finally {
+    await closeServer(server);
+  }
+});
+
 function writeFakeNpx(binDir: string): void {
   const filePath = path.join(binDir, 'npx');
   writeFileSync(

src/__tests__/metro-public.test.ts

@@ -6,6 +6,7 @@ vi.mock('../client-metro.ts', async () => {
   return {
     ...actual,
     prepareMetroRuntime: vi.fn(),
+    reloadMetro: vi.fn(),
   };
 });
 
@@ -14,13 +15,14 @@ vi.mock('../client-metro-companion.ts', () => ({
   stopMetroCompanion: vi.fn(),
 }));
 
-import { prepareMetroRuntime } from '../client-metro.ts';
+import { prepareMetroRuntime, reloadMetro } from '../client-metro.ts';
 import { ensureMetroCompanion, stopMetroCompanion } from '../client-metro-companion.ts';
 import {
   buildAndroidRuntimeHints,
   buildIosRuntimeHints,
   ensureMetroTunnel,
   prepareRemoteMetro,
+  reloadRemoteMetro,
   resolveRuntimeTransport,
   stopMetroTunnel,
 } from '../metro.ts';
@@ -65,6 +67,12 @@ test('public metro helpers expose stable Node-facing wrappers', async () => {
     stopped: true,
     statePath: '/tmp/project/.agent-device/metro-companion.json',
   });
+  vi.mocked(reloadMetro).mockResolvedValue({
+    reloaded: true,
+    reloadUrl: 'http://127.0.0.1:8081/reload',
+    status: 200,
+    body: 'OK',
+  });
 
   const prepared = await prepareRemoteMetro({
     projectRoot: '/tmp/project',
@@ -87,11 +95,15 @@ test('public metro helpers expose stable Node-facing wrappers', async () => {
   await stopMetroTunnel({
     projectRoot: '/tmp/project',
   });
+  const reloaded = await reloadRemoteMetro({
+    runtime: { platform: 'ios', bundleUrl: 'http://127.0.0.1:8081/index.bundle?platform=ios' },
+  });
 
   assert.equal(prepared.reused, true);
   assert.equal(prepared.logPath, '/tmp/project/.agent-device/metro.log');
   assert.equal(tunnel.started, true);
   assert.equal(tunnel.logPath, '/tmp/project/.agent-device/metro-companion.log');
+  assert.equal(reloaded.reloaded, true);
   assert.deepEqual(vi.mocked(prepareMetroRuntime).mock.calls[0]?.[0], {
     projectRoot: '/tmp/project',
     kind: 'react-native',
@@ -113,6 +125,9 @@ test('public metro helpers expose stable Node-facing wrappers', async () => {
     logPath: undefined,
     env: undefined,
   });
+  assert.deepEqual(vi.mocked(reloadMetro).mock.calls[0]?.[0], {
+    runtime: { platform: 'ios', bundleUrl: 'http://127.0.0.1:8081/index.bundle?platform=ios' },
+  });
   assert.equal(
     buildIosRuntimeHints('https://public.example.test').bundleUrl,
     'https://public.example.test/index.bundle?platform=ios&dev=true&minify=false',

src/cli/commands/metro.ts

@@ -4,8 +4,18 @@ import type { ClientCommandHandler } from './router-types.ts';
 
 export const metroCommand: ClientCommandHandler = async ({ positionals, flags, client }) => {
   const action = (positionals[0] ?? '').toLowerCase();
+  if (action === 'reload') {
+    const result = await client.metro.reload({
+      metroHost: flags.metroHost,
+      metroPort: flags.metroPort,
+      bundleUrl: flags.bundleUrl,
+      timeoutMs: flags.metroProbeTimeoutMs,
+    });
+    writeCommandOutput(flags, result, () => `Reloaded React Native apps via ${result.reloadUrl}`);
+    return true;
+  }
   if (action !== 'prepare') {
-    throw new AppError('INVALID_ARGS', 'metro only supports prepare');
+    throw new AppError('INVALID_ARGS', 'metro requires a subcommand: prepare or reload');
   }
   if (!flags.metroPublicBaseUrl && !flags.metroProxyBaseUrl) {
     throw new AppError(