fix: use bridge metro runtime descriptors (#425)

Author: thymikee

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

@@ -103,28 +103,31 @@ Example `remote-config.json` shape:
   "tenant": "acme",
   "runId": "run-123",
   "sessionIsolation": "tenant",
-  "platform": "android",
-  "metroPublicBaseUrl": "http://127.0.0.1:8081"
+  "platform": "ios",
+  "metroProxyBaseUrl": "https://bridge.example.com"
 }
 ```
 
 Optional overrides stay available for advanced cases:
 
 ```json
 {
-  "session": "adc-android",
-  "leaseBackend": "android-instance",
+  "session": "adc-ios",
+  "leaseBackend": "ios-instance",
   "metroProjectRoot": ".",
   "metroKind": "expo",
-  "metroProxyBaseUrl": "https://bridge.example.com/metro/acme/run-123"
+  "metroPublicBaseUrl": "http://127.0.0.1:8081"
 }
 ```
 
 - Keep secrets in env/config managed by the operator boundary. Do not persist auth tokens in connection state.
 - Omit Metro fields for non-React Native flows.
 - Put `tenant`, `runId`, and `sessionIsolation` in the remote profile so agents can run `agent-device connect --remote-config ./remote-config.json` without extra scope flags. Add `platform`, `leaseBackend`, `session`, or Metro overrides only when the default inference is not enough for that flow.
 - Explicit command-line flags override connected defaults. Use them intentionally when switching session, platform, target, tenant, run, or lease scope.
-- For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally.
+- For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally. `metroProxyBaseUrl` is the bridge origin, not a prebuilt `/api/metro/...` route.
+- For cloud stock React Native iOS, use the bridge descriptor's wildcard HTTPS Metro hints directly; do not install or launch the XCTest runner just to make Metro reachable.
+- Android keeps using bridge-provided `/api/metro/runtimes/<runtimeId>/...` Metro routes.
+- `metroPublicBaseUrl` is only needed for direct/non-bridge bundle hints. Bridged profiles can omit it.
 - Use a lease backend that matches the bridge target platform, for example `android-instance`, `ios-instance`, or an explicit `--lease-backend` override.
 
 ## Transport prerequisites

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

@@ -166,6 +166,35 @@ test('metro prepare forwards normalized options to client.metro.prepare', async
   assert.equal(payload.runtimeFilePath, null);
 });
 
+test('metro prepare rejects when no public or proxy base URL is provided', async () => {
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+    prepareMetro: async () => {
+      throw new Error('unexpected metro prepare call');
+    },
+  });
+
+  await assert.rejects(
+    () =>
+      tryRunClientBackedCommand({
+        command: 'metro',
+        positionals: ['prepare'],
+        flags: {
+          json: false,
+          help: false,
+          version: false,
+        },
+        client,
+      }),
+    (error) =>
+      error instanceof AppError &&
+      error.code === 'INVALID_ARGS' &&
+      error.message.includes('--public-base-url <url> or --proxy-base-url <url>'),
+  );
+});
+
 test('screenshot forwards --overlay-refs to the client capture API', async () => {
   let observed:
     | {
@@ -426,7 +455,6 @@ test('metro prepare with --remote-config loads profile defaults', async () => {
     remoteConfigPath,
     JSON.stringify({
       metroProjectRoot: './apps/demo',
-      metroPublicBaseUrl: 'https://sandbox.example.test',
       metroProxyBaseUrl: 'https://proxy.example.test',
       tenant: 'tenant-1',
       runId: 'run-1',
@@ -483,7 +511,7 @@ test('metro prepare with --remote-config loads profile defaults', async () => {
   assert.deepEqual(observedPrepare, {
     projectRoot: path.join(configDir, 'apps/demo'),
     kind: undefined,
-    publicBaseUrl: 'https://sandbox.example.test',
+    publicBaseUrl: undefined,
     proxyBaseUrl: 'https://proxy.example.test',
     bearerToken: undefined,
     bridgeScope: {

src/__tests__/client-metro-auto-companion.test.ts

@@ -67,16 +67,17 @@ test('prepareMetroRuntime starts the local companion only after bridge setup nee
           enabled: true,
           base_url: 'https://proxy.example.test',
           status_url: 'https://proxy.example.test/status',
-          bundle_url: 'https://proxy.example.test/index.bundle?platform=ios',
+          bundle_url: 'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios',
           ios_runtime: {
-            metro_host: '127.0.0.1',
-            metro_port: 8081,
-            metro_bundle_url: 'https://proxy.example.test/index.bundle?platform=ios',
+            metro_host: 'runtime-1.metro.agent-device.dev',
+            metro_port: 443,
+            metro_bundle_url: 'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios',
           },
           android_runtime: {
-            metro_host: '10.0.2.2',
-            metro_port: 8081,
-            metro_bundle_url: 'https://proxy.example.test/index.bundle?platform=android',
+            metro_host: 'proxy.example.test',
+            metro_port: 443,
+            metro_bundle_url:
+              'https://proxy.example.test/api/metro/runtimes/runtime-1/index.bundle?platform=android',
           },
           upstream: {
             bundle_url:
@@ -99,7 +100,6 @@ test('prepareMetroRuntime starts the local companion only after bridge setup nee
   try {
     const result = await prepareMetroRuntime({
       projectRoot,
-      publicBaseUrl: 'https://public.example.test',
       proxyBaseUrl: 'https://proxy.example.test',
       proxyBearerToken: 'shared-token',
       bridgeScope: TEST_BRIDGE_SCOPE,
@@ -113,11 +113,13 @@ test('prepareMetroRuntime starts the local companion only after bridge setup nee
     assert.equal(result.bridge?.enabled, true);
     assert.equal(
       result.iosRuntime.bundleUrl,
-      'https://proxy.example.test/index.bundle?platform=ios',
+      'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios',
     );
+    assert.equal(result.iosRuntime.metroHost, 'runtime-1.metro.agent-device.dev');
+    assert.equal(result.iosRuntime.metroPort, 443);
     assert.equal(
       result.androidRuntime.bundleUrl,
-      'https://proxy.example.test/index.bundle?platform=android',
+      'https://proxy.example.test/api/metro/runtimes/runtime-1/index.bundle?platform=android',
     );
     assert.equal(vi.mocked(ensureMetroCompanion).mock.calls.length, 1);
     assert.deepEqual(vi.mocked(ensureMetroCompanion).mock.calls[0]?.[0], {
@@ -138,27 +140,91 @@ test('prepareMetroRuntime starts the local companion only after bridge setup nee
       tenantId: 'tenant-1',
       runId: 'run-1',
       leaseId: 'lease-1',
-      ios_runtime: {
-        metro_bundle_url:
-          'https://public.example.test/index.bundle?platform=ios&dev=true&minify=false',
-      },
       timeout_ms: 10000,
     });
     assert.deepEqual(JSON.parse(String(fetchMock.mock.calls[2]?.[1]?.body)), {
       tenantId: 'tenant-1',
       runId: 'run-1',
       leaseId: 'lease-1',
-      ios_runtime: {
-        metro_bundle_url:
-          'https://public.example.test/index.bundle?platform=ios&dev=true&minify=false',
-      },
       timeout_ms: 10000,
     });
   } finally {
     fs.rmSync(tempRoot, { recursive: true, force: true });
   }
 });
 
+test('prepareMetroRuntime rejects bridged descriptors without iOS bundle URLs', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-metro-descriptor-'));
+  const projectRoot = path.join(tempRoot, 'project');
+  fs.mkdirSync(path.join(projectRoot, 'node_modules'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({
+      name: 'metro-descriptor-test',
+      private: true,
+      dependencies: {
+        'react-native': '0.0.0-test',
+      },
+    }),
+  );
+
+  const fetchMock = vi.fn();
+  fetchMock.mockResolvedValueOnce({
+    ok: true,
+    status: 200,
+    text: async () => 'packager-status:running',
+  });
+  fetchMock.mockResolvedValueOnce({
+    ok: true,
+    status: 200,
+    text: async () =>
+      JSON.stringify({
+        ok: true,
+        data: {
+          enabled: true,
+          base_url: 'https://proxy.example.test',
+          status_url: 'https://proxy.example.test/status',
+          bundle_url: 'https://proxy.example.test/index.bundle?platform=ios',
+          ios_runtime: {},
+          android_runtime: {
+            metro_bundle_url:
+              'https://proxy.example.test/api/metro/runtimes/runtime-1/index.bundle?platform=android',
+          },
+          upstream: {
+            bundle_url:
+              'https://public.example.test/index.bundle?platform=ios&dev=true&minify=false',
+          },
+          probe: {
+            reachable: true,
+            status_code: 200,
+            latency_ms: 5,
+            detail: 'ok',
+          },
+        },
+      }),
+  });
+  vi.stubGlobal('fetch', fetchMock);
+
+  try {
+    await assert.rejects(
+      () =>
+        prepareMetroRuntime({
+          projectRoot,
+          proxyBaseUrl: 'https://proxy.example.test',
+          proxyBearerToken: 'shared-token',
+          bridgeScope: TEST_BRIDGE_SCOPE,
+          metroPort: 8081,
+          reuseExisting: true,
+          installDependenciesIfNeeded: false,
+        }),
+      /bridge descriptor is missing ios_runtime\.metro_bundle_url/,
+    );
+    assert.equal(vi.mocked(ensureMetroCompanion).mock.calls.length, 0);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test('prepareMetroRuntime preserves the initial bridge error if companion startup fails', async () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-metro-companion-error-'));
   const projectRoot = path.join(tempRoot, 'project');
@@ -387,12 +453,17 @@ test('prepareMetroRuntime retries malformed retryable bridge responses after com
           enabled: true,
           base_url: 'https://proxy.example.test',
           status_url: 'https://proxy.example.test/status',
-          bundle_url: 'https://proxy.example.test/index.bundle?platform=ios',
+          bundle_url: 'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios',
           ios_runtime: {
-            metro_bundle_url: 'https://proxy.example.test/index.bundle?platform=ios',
+            metro_host: 'runtime-1.metro.agent-device.dev',
+            metro_port: 443,
+            metro_bundle_url: 'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios',
           },
           android_runtime: {
-            metro_bundle_url: 'https://proxy.example.test/index.bundle?platform=android',
+            metro_host: 'proxy.example.test',
+            metro_port: 443,
+            metro_bundle_url:
+              'https://proxy.example.test/api/metro/runtimes/runtime-1/index.bundle?platform=android',
           },
           upstream: {
             bundle_url:
@@ -429,8 +500,10 @@ test('prepareMetroRuntime retries malformed retryable bridge responses after com
     assert.equal(result.bridge?.enabled, true);
     assert.equal(
       result.iosRuntime.bundleUrl,
-      'https://proxy.example.test/index.bundle?platform=ios',
+      'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios',
     );
+    assert.equal(result.iosRuntime.metroHost, 'runtime-1.metro.agent-device.dev');
+    assert.equal(result.iosRuntime.metroPort, 443);
     assert.equal(fetchMock.mock.calls.length, 4);
   } finally {
     fs.rmSync(tempRoot, { recursive: true, force: true });

src/__tests__/client-metro.test.ts

@@ -58,7 +58,7 @@ test('prepareMetroRuntime starts Metro, bridges through proxy, and writes runtim
     assert.equal(body.tenantId, 'tenant-1');
     assert.equal(body.runId, 'run-1');
     assert.equal(body.leaseId, 'lease-1');
-    assert.match(body.ios_runtime?.metro_bundle_url ?? '', /index\.bundle\?platform=ios/);
+    assert.equal(body.ios_runtime, undefined);
 
     res.statusCode = 200;
     res.setHeader('content-type', 'application/json');
@@ -72,16 +72,16 @@ test('prepareMetroRuntime starts Metro, bridges through proxy, and writes runtim
             status_url: 'http://127.0.0.1:8081/status',
             bundle_url: 'http://127.0.0.1:8081/index.bundle?platform=ios&dev=true&minify=false',
             ios_runtime: {
-              metro_host: '127.0.0.1',
-              metro_port: 8081,
+              metro_host: 'runtime-1.metro.agent-device.dev',
+              metro_port: 443,
               metro_bundle_url:
-                'http://127.0.0.1:8081/index.bundle?platform=ios&dev=true&minify=false',
+                'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios&dev=true&minify=false',
             },
             android_runtime: {
-              metro_host: '10.0.2.2',
-              metro_port: 8081,
+              metro_host: 'bridge.example.test',
+              metro_port: 443,
               metro_bundle_url:
-                'http://10.0.2.2:8081/index.bundle?platform=android&dev=true&minify=false',
+                'https://bridge.example.test/api/metro/runtimes/runtime-1/index.bundle?platform=android&dev=true&minify=false',
             },
             upstream: {
               bundle_url: `http://127.0.0.1:${metroPort}/index.bundle?platform=ios&dev=true&minify=false`,
@@ -140,9 +140,10 @@ test('prepareMetroRuntime starts Metro, bridges through proxy, and writes runtim
     assert.equal(result.started, true);
     assert.equal(result.reused, false);
     assert.equal(result.bridge?.enabled, true);
-    assert.equal(result.iosRuntime.metroHost, '127.0.0.1');
+    assert.equal(result.iosRuntime.metroHost, 'runtime-1.metro.agent-device.dev');
+    assert.equal(result.iosRuntime.metroPort, 443);
     assert.equal(result.iosRuntime.platform, 'ios');
-    assert.equal(result.androidRuntime.metroHost, '10.0.2.2');
+    assert.equal(result.androidRuntime.metroHost, 'bridge.example.test');
     assert.equal(result.androidRuntime.platform, 'android');
     assert.deepEqual(requests, ['/api/metro/bridge']);
 
@@ -151,10 +152,10 @@ test('prepareMetroRuntime starts Metro, bridges through proxy, and writes runtim
       androidRuntime: { metroHost?: string; metroPort?: number; platform?: string };
       runtimeFilePath?: string;
     };
-    assert.equal(written.iosRuntime.metroHost, '127.0.0.1');
-    assert.equal(written.iosRuntime.metroPort, 8081);
+    assert.equal(written.iosRuntime.metroHost, 'runtime-1.metro.agent-device.dev');
+    assert.equal(written.iosRuntime.metroPort, 443);
     assert.equal(written.iosRuntime.platform, 'ios');
-    assert.equal(written.androidRuntime.metroHost, '10.0.2.2');
+    assert.equal(written.androidRuntime.metroHost, 'bridge.example.test');
     assert.equal(written.androidRuntime.platform, 'android');
     assert.equal(written.runtimeFilePath, runtimeFilePath);
   } finally {

src/__tests__/metro-protocol-public.test.ts

@@ -15,14 +15,15 @@ import {
   enabled: true,
   base_url: 'https://bridge.example.test',
   ios_runtime: {
-    metro_host: '127.0.0.1',
-    metro_port: 8081,
-    metro_bundle_url: 'https://bridge.example.test/index.bundle?platform=ios',
+    metro_host: 'runtime-1.metro.agent-device.dev',
+    metro_port: 443,
+    metro_bundle_url: 'https://runtime-1.metro.agent-device.dev/index.bundle?platform=ios',
   },
   android_runtime: {
-    metro_host: '10.0.2.2',
-    metro_port: 8081,
-    metro_bundle_url: 'https://bridge.example.test/index.bundle?platform=android',
+    metro_host: 'bridge.example.test',
+    metro_port: 443,
+    metro_bundle_url:
+      'https://bridge.example.test/api/metro/runtimes/runtime-1/index.bundle?platform=android',
   },
   upstream: { bundle_url: 'http://127.0.0.1:8081/index.bundle?platform=ios' },
   probe: { reachable: true, status_code: 200, latency_ms: 4, detail: 'ok' },

src/cli/commands/connection-runtime.ts

@@ -188,10 +188,10 @@ export async function prepareConnectedMetro(
       'Deferred Metro preparation requires platform "ios" or "android".',
     );
   }
-  if (!flags.metroPublicBaseUrl) {
+  if (!flags.metroPublicBaseUrl && !flags.metroProxyBaseUrl) {
     throw new AppError(
       'INVALID_ARGS',
-      'Deferred Metro preparation requires metroPublicBaseUrl when Metro settings are provided.',
+      'Deferred Metro preparation requires metroPublicBaseUrl or metroProxyBaseUrl when Metro settings are provided.',
     );
   }
   const prepared = await client.metro.prepare({

src/cli/commands/metro.ts

@@ -7,8 +7,11 @@ export const metroCommand: ClientCommandHandler = async ({ positionals, flags, c
   if (action !== 'prepare') {
     throw new AppError('INVALID_ARGS', 'metro only supports prepare');
   }
-  if (!flags.metroPublicBaseUrl) {
-    throw new AppError('INVALID_ARGS', 'metro prepare requires --public-base-url <url>.');
+  if (!flags.metroPublicBaseUrl && !flags.metroProxyBaseUrl) {
+    throw new AppError(
+      'INVALID_ARGS',
+      'metro prepare requires --public-base-url <url> or --proxy-base-url <url>.',
+    );
   }
 
   const result = await client.metro.prepare({