feat: add runtime diagnostics commands

Author: thymikee

COMMAND_OWNERSHIP.md

@@ -110,6 +110,11 @@ Their semantics should live in `agent-device/commands` as they migrate.
   start/stop result unions.
 - `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.
+- `network`: runtime `diagnostics.network` implemented with bounded,
+  structured, 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
@@ -169,12 +174,9 @@ the portable command runtime.
 
 ## Later Capability-Gated Runtime Commands
 
-These commands should migrate only after the runtime, backend capability, and IO
-contracts are established for their behavior.
-
-- `logs`
-- `network`
-- `perf`
+All currently identified capability-gated diagnostics have runtime command
+contracts. New diagnostics should follow the `diagnostics.*` namespace with
+bounded result windows and backend-specific support.
 
 ## Compatibility Helper Subpaths
 

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

@@ -60,12 +60,18 @@ test('admin runtime commands call typed backend primitives', async () => {
   });
   assert.equal(reinstalled.kind, 'appReinstalled');
 
+  const installedFromSource = await device.admin.installFromSource({
+    source: { kind: 'url', url: 'https://example.test/Other.app.zip' },
+  });
+  assert.equal(installedFromSource.kind, 'appInstalledFromSource');
+
   assert.deepEqual(calls, [
     'listDevices',
     'bootDevice',
     'ensureSimulator',
     'installApp',
     'reinstallApp',
+    'installApp',
   ]);
 });
 
@@ -141,6 +147,46 @@ test('router batch preserves per-step failures and enforces per-command policy',
   assert.equal(nested.ok ? undefined : nested.error.code, 'INVALID_ARGS');
 });
 
+test('router batch can continue after failure and inherits command context', async () => {
+  const sessionsSeen: unknown[] = [];
+  const appsOpened: string[] = [];
+  const router = createCommandRouter({
+    createRuntime: (request) => {
+      sessionsSeen.push(request.options?.session);
+      return createAgentDevice({
+        backend: {
+          platform: 'ios',
+          openApp: async (_context, target) => {
+            if (target.app === 'bad') throw new Error('open failed');
+            if (target.app) appsOpened.push(target.app);
+          },
+        },
+        artifacts,
+        policy: restrictedCommandPolicy(),
+      });
+    },
+  });
+
+  const response = await router.dispatch({
+    command: 'batch',
+    options: {
+      session: 'parent-session',
+      stopOnError: false,
+      maxSteps: 2,
+      steps: [
+        { command: 'apps.open', options: { app: 'bad' } },
+        { command: 'apps.open', options: { app: 'good' } },
+      ],
+    },
+  });
+
+  assert.equal(response.ok, true);
+  assert.equal(response.ok && isResultKind(response.data, 'batch') ? response.data.executed : 0, 2);
+  assert.equal(response.ok && isResultKind(response.data, 'batch') ? response.data.failed : 0, 1);
+  assert.deepEqual(appsOpened, ['good']);
+  assert.deepEqual(sessionsSeen, ['parent-session', 'parent-session']);
+});
+
 test('record and trace runtime commands call typed backend lifecycle primitives', async () => {
   const calls: unknown[] = [];
   const device = createAgentDevice({

src/__tests__/runtime-conformance.test.ts

@@ -57,6 +57,9 @@ test('command conformance suites run against a fixture backend', async () => {
   assert.equal(calls.includes('reinstallApp'), true);
   assert.equal(calls.includes('startRecording'), true);
   assert.equal(calls.includes('stopTrace'), true);
+  assert.equal(calls.includes('readLogs'), true);
+  assert.equal(calls.includes('dumpNetwork'), true);
+  assert.equal(calls.includes('measurePerf'), true);
 });
 
 test('assertCommandConformance throws when a suite fails', async () => {
@@ -193,6 +196,24 @@ function createFixtureBackend(calls: string[]): AgentDeviceBackend {
       calls.push('stopTrace');
       return { outPath: '/tmp/trace.log' };
     },
+    readLogs: async () => {
+      calls.push('readLogs');
+      return {
+        entries: [{ timestamp: '2026-04-16T00:00:00.000Z', level: 'info', message: 'ready' }],
+      };
+    },
+    dumpNetwork: async () => {
+      calls.push('dumpNetwork');
+      return {
+        entries: [{ method: 'GET', url: 'https://example.test/health', status: 200 }],
+      };
+    },
+    measurePerf: async () => {
+      calls.push('measurePerf');
+      return {
+        metrics: [{ name: 'cpu', value: 3.5, unit: '%' }],
+      };
+    },
   };
 }
 

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

@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import type { AgentDeviceBackend, BackendCommandContext } from '../backend.ts';
+import type { ArtifactAdapter } from '../io.ts';
+import {
+  createAgentDevice,
+  createMemorySessionStore,
+  restrictedCommandPolicy,
+} from '../runtime.ts';
+import { createCommandRouter } from '../commands/index.ts';
+
+const artifacts = {
+  resolveInput: async () => ({ path: '/tmp/input' }),
+  reserveOutput: async (_ref, options) => ({
+    path: `/tmp/${options.field}${options.ext}`,
+    visibility: options.visibility ?? 'client-visible',
+    publish: async () => undefined,
+  }),
+  createTempFile: async (options) => ({
+    path: `/tmp/${options.prefix}${options.ext}`,
+    visibility: 'internal',
+    cleanup: async () => {},
+  }),
+} satisfies ArtifactAdapter;
+
+test('diagnostics runtime commands call typed backend primitives and redact sensitive data', async () => {
+  const contexts: BackendCommandContext[] = [];
+  const device = createAgentDevice({
+    backend: createDiagnosticsBackend(contexts),
+    artifacts,
+    sessions: createMemorySessionStore([
+      { name: 'default', appId: 'app-1', appBundleId: 'com.example.app' },
+    ]),
+    policy: restrictedCommandPolicy(),
+  });
+
+  const logs = await device.observability.logs({
+    session: 'default',
+    limit: 10,
+    levels: ['info'],
+    search: 'ready',
+  });
+  assert.equal(logs.kind, 'diagnosticsLogs');
+  assert.equal(logs.redacted, true);
+  assert.match(logs.entries[0]?.message ?? '', /token=\[REDACTED\]/);
+  assert.equal(logs.entries[0]?.metadata?.authorization, '[REDACTED]');
+
+  const network = await device.observability.network({
+    session: 'default',
+    include: 'all',
+    limit: 5,
+  });
+  assert.equal(network.kind, 'diagnosticsNetwork');
+  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\]/);
+
+  const perf = await device.observability.perf({ session: 'default', sampleMs: 100 });
+  assert.equal(perf.kind, 'diagnosticsPerf');
+  assert.equal(perf.redacted, false);
+  assert.equal(perf.metrics[0]?.name, 'cpu');
+
+  assert.deepEqual(
+    contexts.map((context) => ({ appId: context.appId, appBundleId: context.appBundleId })),
+    [
+      { appId: 'app-1', appBundleId: 'com.example.app' },
+      { appId: 'app-1', appBundleId: 'com.example.app' },
+      { appId: 'app-1', appBundleId: 'com.example.app' },
+    ],
+  );
+});
+
+test('diagnostics commands validate bounded windows and router dispatches diagnostics namespace', async () => {
+  const router = createCommandRouter({
+    createRuntime: () =>
+      createAgentDevice({
+        backend: createDiagnosticsBackend([]),
+        artifacts,
+        policy: restrictedCommandPolicy(),
+      }),
+  });
+
+  const ok = await router.dispatch({
+    command: 'diagnostics.network',
+    options: { limit: 1, include: 'summary' },
+  });
+  assert.equal(ok.ok, true);
+  assert.equal(ok.ok && 'kind' in ok.data ? ok.data.kind : undefined, 'diagnosticsNetwork');
+  const data =
+    ok.ok && 'kind' in ok.data && ok.data.kind === 'diagnosticsNetwork' ? ok.data : undefined;
+  assert.equal(data?.entries[0]?.requestHeaders, undefined);
+
+  const invalid = await router.dispatch({
+    command: 'diagnostics.logs',
+    options: { limit: 501 },
+  });
+  assert.equal(invalid.ok, false);
+  assert.equal(invalid.ok ? undefined : invalid.error.code, 'INVALID_ARGS');
+});
+
+function createDiagnosticsBackend(contexts: BackendCommandContext[]): AgentDeviceBackend {
+  return {
+    platform: 'ios',
+    readLogs: async (context) => {
+      contexts.push(context);
+      return {
+        backend: 'fixture',
+        redacted: false,
+        entries: [
+          {
+            timestamp: '2026-04-16T00:00:00.000Z',
+            level: 'info',
+            message: 'ready token=secret',
+            metadata: { authorization: 'Bearer secret' },
+          },
+        ],
+      };
+    },
+    dumpNetwork: async (context) => {
+      contexts.push(context);
+      return {
+        backend: 'fixture',
+        entries: [
+          {
+            method: 'POST',
+            url: 'https://example.test/path?token=secret',
+            status: 200,
+            requestHeaders: { Authorization: 'Bearer secret' },
+            responseHeaders: { 'content-type': 'application/json' },
+            requestBody: 'password=secret',
+            responseBody: '{"ok":true}',
+          },
+        ],
+      };
+    },
+    measurePerf: async (context) => {
+      contexts.push(context);
+      return {
+        backend: 'fixture',
+        metrics: [{ name: 'cpu', value: 12.5, unit: '%' }],
+      };
+    },
+  };
+}

src/__tests__/runtime-public.test.ts

@@ -44,6 +44,9 @@ const backend = {
   pushFile: async () => {},
   triggerAppEvent: async () => {},
   pressHome: async () => {},
+  readLogs: async () => ({ entries: [{ message: 'ready' }] }),
+  dumpNetwork: async () => ({ entries: [{ method: 'GET', url: 'https://example.test' }] }),
+  measurePerf: async () => ({ metrics: [{ name: 'cpu', value: 1, unit: '%' }] }),
 } satisfies AgentDeviceBackend;
 
 const artifacts = {
@@ -81,6 +84,7 @@ test('package root exposes command runtime skeleton', async () => {
   assert.equal(typeof device.apps.open, 'function');
   assert.equal(typeof device.admin.install, 'function');
   assert.equal(typeof device.recording.record, 'function');
+  assert.equal(typeof device.observability.logs, 'function');
   const result = await device.capture.screenshot({});
   assert.equal(result.path, '/tmp/path.png');
 });
@@ -386,11 +390,14 @@ test('public backend, commands, io, and conformance subpaths are importable', ()
   assert.equal(typeof commands.admin.install, 'function');
   assert.equal(typeof commands.recording.record, 'function');
   assert.equal(typeof commands.recording.trace, 'function');
+  assert.equal(typeof commands.diagnostics.logs, 'function');
+  assert.equal(typeof commands.diagnostics.network, 'function');
+  assert.equal(typeof commands.diagnostics.perf, 'function');
   assert.equal(
     commandCatalog.some((entry) => entry.command === 'click' && entry.status === 'implemented'),
     true,
   );
-  assert.equal(commandConformanceSuites.length, 7);
+  assert.equal(commandConformanceSuites.length, 8);
   assert.equal(typeof runCommandConformance, 'function');
   assert.equal(target.name, 'fake');
 });
@@ -485,8 +492,15 @@ test('command router dispatches implemented runtime commands and normalizes erro
   assert.equal(batch.ok, true);
   assert.equal(batch.ok && 'kind' in batch.data ? batch.data.kind : undefined, 'batch');
 
+  const logs = await router.dispatch({
+    command: 'diagnostics.logs',
+    options: { limit: 10 },
+  });
+  assert.equal(logs.ok, true);
+  assert.equal(logs.ok && 'kind' in logs.data ? logs.data.kind : undefined, 'diagnosticsLogs');
+
   const planned = await router.dispatch({
-    command: 'logs',
+    command: 'session',
     options: {},
   } as never);
   assert.equal(planned.ok, false);