feat: expose typed client command escape hatch

Author: thymikee

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

@@ -635,6 +635,9 @@ function createStubClient(params: {
   screenshot?: AgentDeviceClient['capture']['screenshot'];
 }): AgentDeviceClient {
   return {
+    command: async () => {
+      throw new Error('unexpected command call');
+    },
     devices: {
       list: async () => [],
     },

src/__tests__/client.test.ts

@@ -1,5 +1,8 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { createAgentDeviceClient, type AgentDeviceClientConfig } from '../client.ts';
 import type { DaemonRequest, DaemonResponse } from '../daemon/types.ts';
 import { AppError } from '../utils/errors.ts';
@@ -347,6 +350,169 @@ test('client throws AppError for daemon failures', async () => {
   );
 });
 
+test('client.command forwards typed back options through shared request metadata', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      action: 'back',
+      mode: 'system',
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const result = await client.command('back', {
+    mode: 'system',
+    platform: 'android',
+  });
+
+  assert.equal(setup.calls.length, 1);
+  assert.equal(setup.calls[0]?.session, 'qa');
+  assert.equal(setup.calls[0]?.command, 'back');
+  assert.deepEqual(setup.calls[0]?.positionals, []);
+  assert.equal(setup.calls[0]?.flags?.backMode, 'system');
+  assert.equal(setup.calls[0]?.flags?.platform, 'android');
+  assert.equal(setup.calls[0]?.flags?.daemonBaseUrl, 'http://daemon.example.test');
+  assert.equal(setup.calls[0]?.meta?.tenantId, 'acme');
+  assert.equal(setup.calls[0]?.meta?.runId, 'run-123');
+  assert.equal(setup.calls[0]?.meta?.leaseId, 'lease-123');
+  assert.deepEqual(result, {
+    action: 'back',
+    mode: 'system',
+  });
+});
+
+test('client.command prepares wait selector options without raw daemon requests', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      selector: 'role=button[name="Continue"]',
+      waitedMs: 120,
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const result = await client.command('wait', {
+    selector: 'role=button[name="Continue"]',
+    timeoutMs: 1_500,
+    depth: 3,
+    raw: true,
+  });
+
+  assert.equal(setup.calls.length, 1);
+  assert.equal(setup.calls[0]?.command, 'wait');
+  assert.deepEqual(setup.calls[0]?.positionals, ['role=button[name="Continue"]', '1500']);
+  assert.equal(setup.calls[0]?.flags?.snapshotDepth, 3);
+  assert.equal(setup.calls[0]?.flags?.snapshotRaw, true);
+  assert.deepEqual(result, {
+    selector: 'role=button[name="Continue"]',
+    waitedMs: 120,
+  });
+});
+
+test('client.command maps appSwitcher alias to daemon app-switcher command', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      action: 'app-switcher',
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  await client.command('appSwitcher', {});
+
+  assert.equal(setup.calls.length, 1);
+  assert.equal(setup.calls[0]?.command, 'app-switcher');
+  assert.deepEqual(setup.calls[0]?.positionals, []);
+});
+
+test('remote-config defaults are scoped to the command escape hatch', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-client-remote-scope-'));
+  try {
+    const remoteConfig = path.join(tempRoot, 'remote.json');
+    fs.writeFileSync(
+      remoteConfig,
+      JSON.stringify({
+        session: 'remote-session',
+        platform: 'android',
+        daemonBaseUrl: 'http://127.0.0.1:9124/agent-device',
+      }),
+    );
+    const setup = createTransport(async () => ({
+      ok: true,
+      data: {
+        devices: [],
+      },
+    }));
+    const client = createAgentDeviceClient(
+      {
+        session: 'local-session',
+        remoteConfig,
+        cwd: tempRoot,
+      },
+      { transport: setup.transport },
+    );
+
+    await client.devices.list();
+
+    assert.equal(setup.calls.length, 1);
+    assert.equal(setup.calls[0]?.session, 'local-session');
+    assert.equal(setup.calls[0]?.command, 'devices');
+    assert.equal(setup.calls[0]?.flags?.platform, undefined);
+    assert.equal(setup.calls[0]?.flags?.daemonBaseUrl, undefined);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('client.command applies remote-config defaults before daemon transport', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-client-remote-config-'));
+  try {
+    const remoteConfig = path.join(tempRoot, 'remote.json');
+    fs.writeFileSync(
+      remoteConfig,
+      JSON.stringify({
+        session: 'remote-session',
+        platform: 'android',
+        daemonBaseUrl: 'http://127.0.0.1:9124/agent-device',
+        tenant: 'remote-tenant',
+        sessionIsolation: 'tenant',
+        runId: 'remote-run',
+        leaseId: 'remote-lease',
+      }),
+    );
+    const setup = createTransport(async () => ({
+      ok: true,
+      data: {
+        action: 'home',
+      },
+    }));
+    const client = createAgentDeviceClient(
+      {
+        remoteConfig,
+        cwd: tempRoot,
+      },
+      { transport: setup.transport },
+    );
+
+    await client.command('home', {});
+
+    assert.equal(setup.calls.length, 1);
+    assert.equal(setup.calls[0]?.session, 'remote-session');
+    assert.equal(setup.calls[0]?.command, 'home');
+    assert.equal(setup.calls[0]?.flags?.platform, 'android');
+    assert.equal(setup.calls[0]?.flags?.daemonBaseUrl, 'http://127.0.0.1:9124/agent-device');
+    assert.equal(setup.calls[0]?.flags?.tenant, 'remote-tenant');
+    assert.equal(setup.calls[0]?.flags?.sessionIsolation, 'tenant');
+    assert.equal(setup.calls[0]?.flags?.runId, 'remote-run');
+    assert.equal(setup.calls[0]?.flags?.leaseId, 'remote-lease');
+    assert.equal(setup.calls[0]?.meta?.tenantId, 'remote-tenant');
+    assert.equal(setup.calls[0]?.meta?.runId, 'remote-run');
+    assert.equal(setup.calls[0]?.meta?.leaseId, 'remote-lease');
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test('client capture.snapshot preserves visibility metadata from daemon responses', async () => {
   const setup = createTransport(async () => ({
     ok: true,

src/__tests__/close-remote-metro.test.ts

@@ -38,6 +38,9 @@ test('close with remote-config stops the managed Metro companion for that projec
     });
 
     const client: AgentDeviceClient = {
+      command: async () => {
+        throw new Error('unexpected call');
+      },
       devices: { list: async () => [] },
       sessions: {
         list: async () => [],
@@ -131,6 +134,9 @@ test('close with remote-config still stops the managed Metro companion when clos
     });
 
     const client: AgentDeviceClient = {
+      command: async () => {
+        throw new Error('unexpected call');
+      },
       devices: { list: async () => [] },
       sessions: {
         list: async () => [],
@@ -229,6 +235,9 @@ test('close app with remote-config stops the managed Metro companion for that se
     );
 
     const client: AgentDeviceClient = {
+      command: async () => {
+        throw new Error('unexpected call');
+      },
       devices: { list: async () => [] },
       sessions: {
         list: async () => [],
@@ -325,6 +334,9 @@ test('close with remote-config still succeeds when the config file is gone befor
     fs.rmSync(remoteConfigPath);
 
     const client: AgentDeviceClient = {
+      command: async () => {
+        throw new Error('unexpected call');
+      },
       devices: { list: async () => [] },
       sessions: {
         list: async () => [],

src/client-normalizers.ts

@@ -257,6 +257,7 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     shutdown: options.shutdown,
     saveScript: options.saveScript,
     noRecord: options.noRecord,
+    backMode: options.backMode,
     metroHost: options.metroHost,
     metroPort: options.metroPort,
     bundleUrl: options.bundleUrl,