feat: streamline remote metro open flow (#240)

* feat: streamline remote metro open flow

* fix: honor remote config defaults and cli precedence

Author: thymikee

README.md

@@ -349,8 +349,8 @@ Navigation helpers:
 - `install`/`reinstall` accept package/bundle id style app names and support `~` in paths.
 - `install-from-source` supports `--retain-paths` and `--retention-ms <ms>` when callers need retained materialized artifact paths after the install.
 - When `AGENT_DEVICE_DAEMON_BASE_URL` targets a remote daemon, local `.apk`/`.aab`/`.ipa` files and `.app` bundles are uploaded automatically before `install`/`reinstall`.
-- `metro prepare --public-base-url <url>` starts or reuses a local Metro server for sandbox/client flows and prints runtime JSON to stdout. `--json` wraps the same payload in the standard `{ success, data }` envelope. Pass `--proxy-base-url <url>` plus `AGENT_DEVICE_PROXY_TOKEN` (preferred) or `--bearer-token <token>` when the runtime must be bridged through `agent-device-proxy`, and `--runtime-file <path>` only when a persisted artifact is needed.
-- Remote daemon clients can persist session-scoped runtime hints with `runtime set` before `open`; Android launches write React Native dev prefs, and iOS simulator launches write React Native bundle defaults before app start. Example: `agent-device runtime set --session my-session --platform android --metro-host 10.0.0.10 --metro-port 8081 --launch-url "myapp://dev"`.
+- `open <app> --remote-config <path> --relaunch` is the canonical remote Metro-backed launch flow for sandbox agents. The remote profile supplies host + Metro settings, `open` prepares Metro locally when needed, derives platform runtime hints, and forwards them inline to the remote daemon before launch.
+- `metro prepare --remote-config <path>` remains available for inspection and debugging. It prints JSON runtime hints to stdout, `--json` wraps them in the standard `{ success, data }` envelope, and `--runtime-file <path>` persists the same payload when callers need an artifact.
 - Remote daemon screenshots and recordings are materialized back to the caller path instead of returning host-local daemon paths.
 - To force a daemon-side path instead of uploading a local file, prefix it with `remote:`, for example `remote:/srv/builds/MyApp.app`.
 - Supported binary formats for `install`/`reinstall`: Android `.apk` and `.aab`, iOS `.app` and `.ipa`.
@@ -568,7 +568,7 @@ Environment selectors:
 - `AGENT_DEVICE_DAEMON_BASE_URL=http(s)://host:port[/base-path]` connect directly to a remote HTTP daemon and skip local daemon metadata/startup.
 - Remote daemon installs upload local artifacts through `POST /upload`; use a `remote:` path prefix when you need the daemon to read an existing server-side artifact path as-is.
 - `AGENT_DEVICE_DAEMON_AUTH_TOKEN=<token>` auth token for remote HTTP daemon mode; sent in both the JSON-RPC request token and HTTP auth headers (`Authorization: Bearer` and `x-agent-device-token`).
-- `AGENT_DEVICE_PROXY_TOKEN=<token>` preferred bearer token for `metro prepare --proxy-base-url <url>` so the proxy secret does not need to be passed on the command line. `AGENT_DEVICE_METRO_BEARER_TOKEN` is also supported.
+- `AGENT_DEVICE_PROXY_TOKEN=<token>` preferred bearer token for `metro prepare --proxy-base-url <url>` so the host-bridge secret does not need to be passed on the command line. `AGENT_DEVICE_METRO_BEARER_TOKEN` is also supported.
 - `AGENT_DEVICE_DAEMON_SERVER_MODE=socket|http|dual` daemon server mode. `http` and `dual` expose JSON-RPC 2.0 at `POST /rpc` (`GET /health` available for liveness).
 - `AGENT_DEVICE_DAEMON_TRANSPORT=auto|socket|http` client preference when connecting to daemon metadata.
 - `AGENT_DEVICE_HTTP_AUTH_HOOK=<module-path>` optional HTTP auth hook module path for JSON-RPC server mode.

skills/agent-device/SKILL.md

@@ -33,7 +33,7 @@ Use this skill as a router, not a full manual.
 - iOS local QA: use simulators unless the task explicitly requires a physical device.
 - iOS local QA in mixed simulator/device environments: run `ensure-simulator` first and pass `--device`, `--udid`, or `--ios-simulator-device-set` on later commands.
 - Android local QA: use `install` or `reinstall` for `.apk`/`.aab` files, then relaunch by installed package name.
-- Android React Native + Metro flows: set runtime hints with `runtime set` before `open <package> --relaunch`.
+- Android React Native + Metro flows: prefer `open <package> --remote-config <path> --relaunch`.
 - In mixed-device environments, always pin the exact target with `--serial`, `--device`, `--udid`, or an isolation scope.
 - For session-bound automation runs, prefer a pre-bound session/platform instead of repeating selectors on every command: set `AGENT_DEVICE_SESSION`, set `AGENT_DEVICE_PLATFORM`, and the daemon will enforce the shared lock policy across CLI, typed client, and RPC entry points.
 - Use `--session-lock reject|strip` (or `AGENT_DEVICE_SESSION_LOCK`) only when you need to override the default reject behavior. Lock mode applies to nested `batch` steps too.
@@ -67,8 +67,7 @@ Use this when a physical iPhone is also connected and you want deterministic sim
 
 ```bash
 agent-device reinstall MyApp /path/to/app-debug.apk --platform android --serial emulator-5554
-agent-device runtime set --session qa-android --platform android --metro-host 10.0.2.2 --metro-port 8081
-agent-device open com.example.myapp --platform android --serial emulator-5554 --session qa-android --relaunch
+agent-device open com.example.myapp --remote-config ./agent-device.remote.json --relaunch
 agent-device snapshot -i
 agent-device close
 ```
@@ -186,7 +185,7 @@ That includes bound-session defaults such as `sessionLock` / `AGENT_DEVICE_SESSI
 For Android emulators by AVD name, use `boot --platform android --device <avd-name>`.
 For Android emulators without GUI, add `--headless`.
 Use `--target mobile|tv` with `--platform` (required) to pick phone/tablet vs TV targets (AndroidTV/tvOS).
-For Android React Native + Metro flows, install or reinstall the APK first, set runtime hints with `runtime set`, then use `open <package> --relaunch`; do not use `open <apk|aab> --relaunch`.
+For Android React Native + Metro flows, install or reinstall the APK first, then use `open <package> --remote-config <path> --relaunch`; do not use `open <apk|aab> --relaunch`.
 For local iOS QA in mixed simulator/device environments, use `ensure-simulator` and pass `--device` or `--udid` so automation does not attach to a physical device by accident.
 For session-bound automation, prefer `AGENT_DEVICE_SESSION` + `AGENT_DEVICE_PLATFORM`; that bound-session default now enables lock mode automatically.
 

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

@@ -1,12 +1,17 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { tryRunClientBackedCommand } from '../cli-client-commands.ts';
 import type {
   AgentDeviceClient,
   AppInstallFromSourceOptions,
+  AppOpenOptions,
   MetroPrepareOptions,
 } from '../client.ts';
 import { AppError } from '../utils/errors.ts';
+import { resolveCliOptions } from '../utils/cli-options.ts';
 
 test('install-from-source forwards URL and repeated headers to client.apps.installFromSource', async () => {
   let observed: AppInstallFromSourceOptions | undefined;
@@ -180,6 +185,223 @@ test('metro prepare wraps output in the standard success envelope for --json', a
   assert.equal(payload.data.iosRuntime.platform, 'ios');
 });
 
+test('metro prepare with --remote-config loads profile defaults', async () => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-remote-metro-'));
+  const configDir = path.join(tmpRoot, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  const remoteConfigPath = path.join(configDir, 'remote.json');
+  fs.writeFileSync(
+    remoteConfigPath,
+    JSON.stringify({
+      metroProjectRoot: './apps/demo',
+      metroPublicBaseUrl: 'https://sandbox.example.test',
+      metroProxyBaseUrl: 'https://proxy.example.test',
+      metroPreparePort: 9090,
+    }),
+  );
+  const parsed = resolveCliOptions(['metro', 'prepare', '--remote-config', remoteConfigPath], {
+    cwd: tmpRoot,
+    env: process.env,
+  });
+
+  let observedPrepare: MetroPrepareOptions | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+    prepareMetro: async (options) => {
+      observedPrepare = options;
+      return {
+        projectRoot: '/tmp/project',
+        kind: 'react-native',
+        dependenciesInstalled: false,
+        packageManager: null,
+        started: false,
+        reused: true,
+        pid: 0,
+        logPath: '/tmp/project/.agent-device/metro.log',
+        statusUrl: 'http://127.0.0.1:8081/status',
+        runtimeFilePath: null,
+        iosRuntime: {
+          platform: 'ios',
+          bundleUrl: 'https://sandbox.example.test/index.bundle?platform=ios',
+        },
+        androidRuntime: {
+          platform: 'android',
+          bundleUrl: 'https://sandbox.example.test/index.bundle?platform=android',
+        },
+        bridge: null,
+      };
+    },
+  });
+
+  const stdout = await captureStdout(async () => {
+    const handled = await tryRunClientBackedCommand({
+      command: 'metro',
+      positionals: ['prepare'],
+      flags: parsed.flags,
+      client,
+    });
+    assert.equal(handled, true);
+  });
+  const payload = JSON.parse(stdout);
+  assert.deepEqual(observedPrepare, {
+    projectRoot: path.join(configDir, 'apps/demo'),
+    kind: undefined,
+    publicBaseUrl: 'https://sandbox.example.test',
+    proxyBaseUrl: 'https://proxy.example.test',
+    bearerToken: undefined,
+    port: 9090,
+    listenHost: undefined,
+    statusHost: undefined,
+    startupTimeoutMs: undefined,
+    probeTimeoutMs: undefined,
+    reuseExisting: undefined,
+    installDependenciesIfNeeded: undefined,
+    runtimeFilePath: undefined,
+  });
+  assert.equal(payload.kind, 'react-native');
+});
+
+test('open with --remote-config prepares Metro and forwards inline runtime hints', async () => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-remote-open-'));
+  const configDir = path.join(tmpRoot, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  const remoteConfigPath = path.join(configDir, 'remote.json');
+  fs.writeFileSync(
+    remoteConfigPath,
+    JSON.stringify({
+      platform: 'android',
+      metroProjectRoot: './apps/demo',
+      metroRuntimeFile: './.agent-device-cloud/metro-runtime.json',
+      metroPublicBaseUrl: 'https://sandbox.example.test',
+      metroProxyBaseUrl: 'https://proxy.example.test',
+      metroPreparePort: 9090,
+    }),
+  );
+  const parsed = resolveCliOptions(
+    ['open', 'com.example.app', '--remote-config', remoteConfigPath],
+    {
+      cwd: tmpRoot,
+      env: process.env,
+    },
+  );
+
+  let observedPrepare: MetroPrepareOptions | undefined;
+  let observedOpen: AppOpenOptions | undefined;
+  const client = createStubClient({
+    installFromSource: async () => {
+      throw new Error('unexpected install call');
+    },
+    prepareMetro: async (options) => {
+      observedPrepare = options;
+      return {
+        projectRoot: '/tmp/project',
+        kind: 'react-native',
+        dependenciesInstalled: false,
+        packageManager: null,
+        started: false,
+        reused: true,
+        pid: 0,
+        logPath: '/tmp/project/.agent-device/metro.log',
+        statusUrl: 'http://127.0.0.1:8081/status',
+        runtimeFilePath: null,
+        iosRuntime: {
+          platform: 'ios',
+          bundleUrl: 'https://sandbox.example.test/index.bundle?platform=ios',
+        },
+        androidRuntime: {
+          platform: 'android',
+          metroHost: '10.0.2.2',
+          metroPort: 9090,
+          bundleUrl: 'https://sandbox.example.test/index.bundle?platform=android',
+          launchUrl: 'myapp://dev',
+        },
+        bridge: null,
+      };
+    },
+    open: async (options) => {
+      observedOpen = options;
+      return {
+        session: options.session ?? 'default',
+        runtime: options.runtime,
+        identifiers: { session: options.session ?? 'default' },
+      };
+    },
+  });
+
+  const handled = await tryRunClientBackedCommand({
+    command: 'open',
+    positionals: ['com.example.app'],
+    flags: { ...parsed.flags, relaunch: true },
+    client,
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(observedPrepare, {
+    projectRoot: path.join(configDir, 'apps/demo'),
+    kind: undefined,
+    publicBaseUrl: 'https://sandbox.example.test',
+    proxyBaseUrl: 'https://proxy.example.test',
+    bearerToken: undefined,
+    port: 9090,
+    listenHost: undefined,
+    statusHost: undefined,
+    startupTimeoutMs: undefined,
+    probeTimeoutMs: undefined,
+    reuseExisting: undefined,
+    installDependenciesIfNeeded: undefined,
+    runtimeFilePath: path.join(configDir, '.agent-device-cloud/metro-runtime.json'),
+  });
+  assert.deepEqual(observedOpen?.runtime, {
+    platform: 'android',
+    metroHost: '10.0.2.2',
+    metroPort: 9090,
+    bundleUrl: 'https://sandbox.example.test/index.bundle?platform=android',
+    launchUrl: 'myapp://dev',
+  });
+});
+
+test('open with --remote-config preserves CLI overrides over profile defaults', () => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-remote-open-override-'));
+  const configDir = path.join(tmpRoot, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  const remoteConfigPath = path.join(configDir, 'remote.json');
+  fs.writeFileSync(
+    remoteConfigPath,
+    JSON.stringify({
+      session: 'remote-session',
+      platform: 'android',
+      daemonBaseUrl: 'http://remote-mac.example.test:9124/agent-device',
+      metroPublicBaseUrl: 'https://sandbox.example.test',
+    }),
+  );
+
+  const parsed = resolveCliOptions(
+    [
+      'open',
+      'com.example.app',
+      '--remote-config',
+      remoteConfigPath,
+      '--session',
+      'cli-session',
+      '--platform',
+      'ios',
+      '--daemon-base-url',
+      'http://cli-mac.example.test:9124/agent-device',
+    ],
+    {
+      cwd: tmpRoot,
+      env: process.env,
+    },
+  );
+
+  assert.equal(parsed.flags.session, 'cli-session');
+  assert.equal(parsed.flags.platform, 'ios');
+  assert.equal(parsed.flags.daemonBaseUrl, 'http://cli-mac.example.test:9124/agent-device');
+  assert.equal(parsed.flags.metroPublicBaseUrl, 'https://sandbox.example.test');
+});
+
 async function captureStdout(run: () => Promise<void>): Promise<string> {
   let stdout = '';
   const originalWrite = process.stdout.write.bind(process.stdout);
@@ -200,6 +422,7 @@ async function captureStdout(run: () => Promise<void>): Promise<string> {
 function createStubClient(params: {
   installFromSource: AgentDeviceClient['apps']['installFromSource'];
   prepareMetro?: AgentDeviceClient['metro']['prepare'];
+  open?: AgentDeviceClient['apps']['open'];
 }): AgentDeviceClient {
   return {
     devices: {
@@ -237,10 +460,12 @@ function createStubClient(params: {
         identifiers: { appId: 'com.example.demo' },
       }),
       installFromSource: params.installFromSource,
-      open: async () => ({
-        session: 'default',
-        identifiers: { session: 'default' },
-      }),
+      open:
+        params.open ??
+        (async () => ({
+          session: 'default',
+          identifiers: { session: 'default' },
+        })),
       close: async () => ({
         session: 'default',
         identifiers: { session: 'default' },
@@ -253,18 +478,6 @@ function createStubClient(params: {
         identifiers: { session: options.session ?? 'default' },
       }),
     },
-    runtime: {
-      set: async () => ({
-        session: 'default',
-        configured: true,
-        identifiers: { session: 'default' },
-      }),
-      show: async () => ({
-        session: 'default',
-        configured: false,
-        identifiers: { session: 'default' },
-      }),
-    },
     metro: {
       prepare:
         params.prepareMetro ??

src/__tests__/cli-config.test.ts

@@ -225,6 +225,61 @@ test('AGENT_DEVICE_CONFIG loads an explicit config path', async () => {
   fs.rmSync(root, { recursive: true, force: true });
 });
 
+test('remote config defaults override generic config and env for remote workflow bindings', async () => {
+  const { root, home, project } = makeTempWorkspace();
+  fs.mkdirSync(path.join(home, '.agent-device'), { recursive: true });
+  fs.writeFileSync(
+    path.join(project, 'agent-device.json'),
+    JSON.stringify({ session: 'project-session', platform: 'ios' }),
+    'utf8',
+  );
+  const remoteConfig = path.join(project, 'agent-device.remote.json');
+  fs.writeFileSync(
+    remoteConfig,
+    JSON.stringify({
+      session: 'remote-session',
+      platform: 'android',
+      daemonBaseUrl: 'http://remote-mac.example.test:9124/agent-device',
+    }),
+    'utf8',
+  );
+
+  const result = await runCliCapture(['snapshot', '--remote-config', remoteConfig, '--json'], {
+    cwd: project,
+    env: {
+      HOME: home,
+      AGENT_DEVICE_SESSION: 'env-session',
+      AGENT_DEVICE_PLATFORM: 'ios',
+    },
+  });
+
+  assert.equal(result.code, null);
+  assert.equal(result.calls.length, 1);
+  assert.equal(result.calls[0]?.session, 'remote-session');
+  assert.equal(result.calls[0]?.flags?.platform, 'android');
+  assert.equal(
+    result.calls[0]?.flags?.daemonBaseUrl,
+    'http://remote-mac.example.test:9124/agent-device',
+  );
+
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('missing explicit remote config path returns parse error before daemon dispatch', async () => {
+  const { root, home, project } = makeTempWorkspace();
+
+  const result = await runCliCapture(['snapshot', '--remote-config', './missing.remote.json'], {
+    cwd: project,
+    env: { HOME: home },
+  });
+
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /Remote config file not found/);
+  assert.equal(result.calls.length, 0);
+
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
 test('config and env defaults include session lock policy flags', async () => {
   const { root, home, project } = makeTempWorkspace();
   fs.mkdirSync(path.join(home, '.agent-device'), { recursive: true });