refactor: clean up runtime router surface

Author: thymikee

COMMAND_OWNERSHIP.md

@@ -111,14 +111,14 @@ Their semantics should live in `agent-device/commands` as they migrate.
 - `trace`: runtime `trace` router/API command implemented with typed trace
   start/stop result unions.
 - `logs`: runtime `diagnostics.logs` implemented with bounded, paginated,
-  redacted log entries.
+  best-effort redacted log entries.
 - `network`: runtime `diagnostics.network` implemented with bounded,
-  structured, redacted network entries.
+  structured, best-effort redacted network entries.
 - `perf`: runtime `diagnostics.perf` implemented with typed metric entries.
-- `replay`: runtime router command implemented for replay scripts or router
-  steps, executing each step through `createCommandRouter()`.
-- `test`: runtime router command implemented for replay test cases with retries
-  and fail-fast handling.
+- `replay`: still daemon/CLI owned; runtime router migration is deferred until
+  it can reuse the real `.ad` parser and healing semantics.
+- `test`: still daemon/CLI owned; runtime router migration is deferred until it
+  can share daemon replay-suite semantics end to end.
 
 ## Boundary Requirements
 

src/__tests__/runtime-admin-router.test.ts

@@ -140,7 +140,7 @@ test('router batch preserves per-step failures and enforces per-command policy',
   const nested = await router.dispatch({
     command: 'batch',
     options: {
-      steps: [{ command: 'replay', options: { steps: [] } }],
+      steps: [{ command: 'batch', options: { steps: [] } }],
     },
   });
   assert.equal(nested.ok, false);
@@ -284,68 +284,31 @@ test('record keeps successful reserved outputs available after publish', async (
   assert.equal(cleanupCalled, false);
 });
 
-test('router replay and test execute parsed router scripts through nested dispatch', async () => {
-  const opened: string[] = [];
+test('router replay and test stay planned until phase 7 migration is complete', async () => {
   const router = createCommandRouter({
     createRuntime: () =>
       createAgentDevice({
-        backend: {
-          platform: 'ios',
-          openApp: async (_context, target) => {
-            if (target.app) opened.push(target.app);
-          },
-        },
+        backend: { platform: 'ios' },
         artifacts,
         policy: restrictedCommandPolicy(),
       }),
   });
 
   const replay = await router.dispatch({
     command: 'replay',
-    options: {
-      script: 'apps.open {"app":"com.example.app"}\napps.open {"app":"com.example.other"}',
-    },
-  });
-
-  assert.equal(replay.ok, true);
-  assert.equal(replay.ok && isResultKind(replay.data, 'replay') ? replay.data.failed : 1, 0);
+    options: { steps: [{ command: 'apps.open', options: { app: 'com.example.app' } }] },
+  } as never);
+  assert.equal(replay.ok, false);
+  assert.equal(replay.ok ? undefined : replay.error.code, 'NOT_IMPLEMENTED');
 
   const suite = await router.dispatch({
     command: 'test',
     options: {
       tests: [{ name: 'opens app', steps: [{ command: 'apps.open', options: { app: 'suite' } }] }],
     },
-  });
-
-  assert.equal(suite.ok, true);
-  assert.equal(suite.ok && isResultKind(suite.data, 'replayTest') ? suite.data.passed : 0, 1);
-  assert.equal(
-    suite.ok && isResultKind(suite.data, 'replayTest') ? suite.data.tests[0]?.attempts : 0,
-    1,
-  );
-  assert.deepEqual(opened, ['com.example.app', 'com.example.other', 'suite']);
-});
-
-test('router replay update fails explicitly until healing is implemented', async () => {
-  const router = createCommandRouter({
-    createRuntime: () =>
-      createAgentDevice({
-        backend: { platform: 'ios' },
-        artifacts,
-        policy: restrictedCommandPolicy(),
-      }),
-  });
-
-  const response = await router.dispatch({
-    command: 'replay',
-    options: {
-      update: true,
-      steps: [{ command: 'apps.open', options: { app: 'com.example.app' } }],
-    },
-  });
-
-  assert.equal(response.ok, false);
-  assert.equal(response.ok ? undefined : response.error.code, 'NOT_IMPLEMENTED');
+  } as never);
+  assert.equal(suite.ok, false);
+  assert.equal(suite.ok ? undefined : suite.error.code, 'NOT_IMPLEMENTED');
 });
 
 function isResultKind<TKind extends string>(

src/__tests__/runtime-diagnostics-router.test.ts

@@ -54,7 +54,20 @@ test('diagnostics runtime commands call typed backend primitives and redact sens
   assert.equal(network.redacted, true);
   assert.match(network.entries[0]?.url ?? '', /token=%5BREDACTED%5D/);
   assert.equal(network.entries[0]?.requestHeaders?.Authorization, '[REDACTED]');
-  assert.match(network.entries[0]?.requestBody ?? '', /password=\[REDACTED\]/);
+  assert.deepEqual(JSON.parse(network.entries[0]?.requestBody ?? '{}'), {
+    token: '[REDACTED]',
+    nested: {
+      apiKey: '[REDACTED]',
+      items: [{ password: '[REDACTED]' }],
+    },
+  });
+  assert.deepEqual(JSON.parse(network.entries[0]?.responseBody ?? '{}'), {
+    ok: true,
+    session: {
+      authorization: '[REDACTED]',
+    },
+    items: [{ secret: '[REDACTED]' }],
+  });
 
   const perf = await device.observability.perf({ session: 'default', sampleMs: 100 });
   assert.equal(perf.kind, 'diagnosticsPerf');
@@ -128,8 +141,10 @@ function createDiagnosticsBackend(contexts: BackendCommandContext[]): AgentDevic
             status: 200,
             requestHeaders: { Authorization: 'Bearer secret' },
             responseHeaders: { 'content-type': 'application/json' },
-            requestBody: 'password=secret',
-            responseBody: '{"ok":true}',
+            requestBody:
+              '{"token":"secret","nested":{"apiKey":"top-secret","items":[{"password":"hidden"}]}}',
+            responseBody:
+              '{"ok":true,"session":{"authorization":"Bearer secret"},"items":[{"secret":"classified"}]}',
           },
         ],
       };

src/__tests__/runtime-public.test.ts

@@ -26,6 +26,7 @@ import {
   createCommandRouter,
   type ScreenshotCommandOptions,
 } from '../commands/index.ts';
+import { runtimeRouterCommandNames } from '../commands/router.ts';
 import type { ArtifactAdapter, FileInputRef, FileOutputRef } from '../io.ts';
 import {
   commandConformanceSuites,
@@ -174,6 +175,31 @@ test('public runtime policy helpers expose local and restricted defaults', async
   assert.equal((await store.get('default'))?.name, 'default');
 });
 
+test('runtime router command map stays aligned with implemented catalog entries', () => {
+  const catalogRuntimeCommands = commandCatalog
+    .filter(
+      (entry) =>
+        entry.status === 'implemented' &&
+        (entry.command.includes('.') || entry.command === 'record' || entry.command === 'trace'),
+    )
+    .map((entry) => entry.command)
+    .sort();
+
+  assert.deepEqual([...runtimeRouterCommandNames].sort(), catalogRuntimeCommands);
+  assert.equal(
+    commandCatalog.some((entry) => entry.command === 'batch' && entry.status === 'implemented'),
+    true,
+  );
+  assert.equal(
+    commandCatalog.some((entry) => entry.command === 'replay' && entry.status === 'planned'),
+    true,
+  );
+  assert.equal(
+    commandCatalog.some((entry) => entry.command === 'test' && entry.status === 'planned'),
+    true,
+  );
+});
+
 test('local artifact adapter marks command outputs and temp files by visibility', async () => {
   const adapter = createLocalArtifactAdapter();
   const output = await adapter.reserveOutput(undefined, {

src/commands/catalog.ts

@@ -18,14 +18,26 @@ export const commandCatalog: readonly CommandCatalogEntry[] = [
   { command: 'diff screenshot', category: 'portable-runtime', status: 'implemented' },
   { command: 'snapshot', category: 'portable-runtime', status: 'implemented' },
   { command: 'diff snapshot', category: 'portable-runtime', status: 'implemented' },
+  { command: 'capture.screenshot', category: 'portable-runtime', status: 'implemented' },
+  { command: 'capture.diffScreenshot', category: 'portable-runtime', status: 'implemented' },
+  { command: 'capture.snapshot', category: 'portable-runtime', status: 'implemented' },
+  { command: 'capture.diffSnapshot', category: 'portable-runtime', status: 'implemented' },
   { command: 'find read-only', category: 'portable-runtime', status: 'implemented' },
   { command: 'get', category: 'portable-runtime', status: 'implemented' },
   { command: 'is', category: 'portable-runtime', status: 'implemented' },
   { command: 'wait', category: 'portable-runtime', status: 'implemented' },
+  { command: 'selectors.find', category: 'portable-runtime', status: 'implemented' },
+  { command: 'selectors.get', category: 'portable-runtime', status: 'implemented' },
+  { command: 'selectors.is', category: 'portable-runtime', status: 'implemented' },
+  { command: 'selectors.wait', category: 'portable-runtime', status: 'implemented' },
   { command: 'alert', category: 'portable-runtime', status: 'planned' },
   { command: 'click', category: 'portable-runtime', status: 'implemented' },
   { command: 'press', category: 'portable-runtime', status: 'implemented' },
   { command: 'fill', category: 'portable-runtime', status: 'implemented' },
+  { command: 'interactions.click', category: 'portable-runtime', status: 'implemented' },
+  { command: 'interactions.press', category: 'portable-runtime', status: 'implemented' },
+  { command: 'interactions.fill', category: 'portable-runtime', status: 'implemented' },
+  { command: 'interactions.typeText', category: 'portable-runtime', status: 'implemented' },
   { command: 'longpress', category: 'portable-runtime', status: 'planned' },
   { command: 'swipe', category: 'portable-runtime', status: 'planned' },
   { command: 'focus', category: 'portable-runtime', status: 'planned' },
@@ -83,8 +95,8 @@ export const commandCatalog: readonly CommandCatalogEntry[] = [
   { command: 'metro', category: 'environment', status: 'planned' },
   { command: 'record', category: 'capability-gated', status: 'implemented' },
   { command: 'trace', category: 'capability-gated', status: 'implemented' },
-  { command: 'replay', category: 'capability-gated', status: 'implemented' },
-  { command: 'test', category: 'capability-gated', status: 'implemented' },
+  { command: 'replay', category: 'capability-gated', status: 'planned' },
+  { command: 'test', category: 'capability-gated', status: 'planned' },
   { command: 'batch', category: 'capability-gated', status: 'implemented' },
   { command: 'logs', category: 'capability-gated', status: 'implemented' },
   { command: 'network', category: 'capability-gated', status: 'implemented' },

src/commands/diagnostics-format.ts

@@ -51,13 +51,9 @@ export function formatNetworkResult(
     const responseHeaders =
       include === 'headers' || include === 'all' ? redactHeaders(entry.responseHeaders) : undefined;
     const requestBody =
-      include === 'body' || include === 'all'
-        ? redactAndTruncate(entry.requestBody, PAYLOAD_MAX_CHARS)
-        : undefined;
+      include === 'body' || include === 'all' ? redactPayload(entry.requestBody) : undefined;
     const responseBody =
-      include === 'body' || include === 'all'
-        ? redactAndTruncate(entry.responseBody, PAYLOAD_MAX_CHARS)
-        : undefined;
+      include === 'body' || include === 'all' ? redactPayload(entry.responseBody) : undefined;
     const metadata = redactUnknown(entry.metadata);
     redacted ||=
       (url?.redacted ?? false) ||
@@ -151,6 +147,22 @@ function redactUrl(url: string): { value: string; redacted: boolean } {
   }
 }
 
+function redactPayload(value: string | undefined): { value?: string; redacted: boolean } {
+  if (value === undefined) return { redacted: false };
+  const structured = redactJsonPayload(value);
+  return structured ?? redactAndTruncate(value, PAYLOAD_MAX_CHARS);
+}
+
+function redactJsonPayload(value: string): { value?: string; redacted: boolean } | undefined {
+  try {
+    const parsed = JSON.parse(value);
+    const result = redactStructured(parsed);
+    return truncateRedacted(JSON.stringify(result.value), PAYLOAD_MAX_CHARS, result.redacted);
+  } catch {
+    return undefined;
+  }
+}
+
 function redactUnknown(value: unknown): { value?: unknown; redacted: boolean } {
   if (value === undefined) return { redacted: false };
   if (typeof value === 'string') return redactAndTruncate(value, PAYLOAD_MAX_CHARS);
@@ -179,11 +191,44 @@ function redactUnknown(value: unknown): { value?: unknown; redacted: boolean } {
   return { value: next, redacted };
 }
 
+function redactStructured(value: unknown): { value?: unknown; redacted: boolean } {
+  if (value === undefined) return { redacted: false };
+  if (typeof value === 'string') return redactText(value);
+  if (!value || typeof value !== 'object') return { value, redacted: false };
+  if (Array.isArray(value)) {
+    let redacted = false;
+    const next = value.map((entry) => {
+      const result = redactStructured(entry);
+      redacted ||= result.redacted;
+      return result.value;
+    });
+    return { value: next, redacted };
+  }
+  let redacted = false;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (SECRET_KEY_PATTERN.test(key)) {
+      next[key] = '[REDACTED]';
+      redacted = true;
+      continue;
+    }
+    const result = redactStructured(entry);
+    next[key] = result.value;
+    redacted ||= result.redacted;
+  }
+  return { value: next, redacted };
+}
+
 function redactAndTruncate(
   value: string | undefined,
   maxChars: number,
 ): { value?: string; redacted: boolean } {
   if (value === undefined) return { redacted: false };
+  const result = redactText(value);
+  return truncateRedacted(result.value, maxChars, result.redacted);
+}
+
+function redactText(value: string): { value: string; redacted: boolean } {
   let redacted = false;
   let next = value.replaceAll(
     /(authorization|token|secret|password|passwd|api[-_]?key)=([^&\s]+)/gi,
@@ -192,6 +237,34 @@ function redactAndTruncate(
       return `${String(key)}=[REDACTED]`;
     },
   );
+  next = next.replaceAll(
+    /("(?:authorization|cookie|token|secret|password|passwd|api[-_]?key)"\s*:\s*")([^"]*)(")/gi,
+    (_match, prefix, _value, suffix) => {
+      redacted = true;
+      return `${String(prefix)}[REDACTED]${String(suffix)}`;
+    },
+  );
+  next = next.replaceAll(/\b(Bearer\s+)([^\s",;]+)/gi, (_match, prefix) => {
+    redacted = true;
+    return `${String(prefix)}[REDACTED]`;
+  });
+  next = next.replaceAll(
+    /((?:authorization|cookie|token|secret|password|passwd|api[-_]?key)\s*[:=]\s*)([^\s,;]+)/gi,
+    (_match, prefix) => {
+      redacted = true;
+      return `${String(prefix)}[REDACTED]`;
+    },
+  );
+  return { value: next, redacted };
+}
+
+function truncateRedacted(
+  value: string | undefined,
+  maxChars: number,
+  redacted: boolean,
+): { value?: string; redacted: boolean } {
+  if (value === undefined) return { redacted };
+  let next = value;
   if (next.length > maxChars) {
     next = `${next.slice(0, maxChars)}...[truncated]`;
     redacted = true;

src/commands/index.ts

@@ -277,12 +277,6 @@ export type {
   CommandRouterRequest,
   CommandRouterResponse,
   CommandRouterResult,
-  ReplayCommandOptions,
-  ReplayCommandResult,
-  ReplayTestCase,
-  ReplayTestCaseResult,
-  ReplayTestCommandOptions,
-  ReplayTestCommandResult,
 } from './router.ts';
 
 export type CommandResult = Record<string, unknown>;