refactor(daemon): bind only the command families the daemon dispatches through

The daemon built its in-process AgentDevice with src/runtime.ts, which value-imports
the all-family command barrel. Five daemon files therefore evaluated the management,
recording, observability and system families they never call, and every change under
src/commands became a daemon-restart-cost event.

Split the runtime assembly (backend, artifacts, sessions, policy, cancellation) into
src/runtime-factory.ts, which carries no command surface, and add
src/runtime-command-surface.ts for the three families an in-process executor
dispatches through: capture, selectors, interactions. src/runtime.ts keeps its public
shape and now composes both, so createAgentDevice stays the one full-surface path and
bindCaptureCommands is the single capture-family binding definition.

Daemon value closure: 717 -> 705 files, 121 -> 108 src/commands files, 19,659 ->
17,434 commands LOC. The residue is the dispatch surface plus the two
cli-schema/command-schema.ts edges owned by #2543, which take it to 34.

Closes #2540

Author: thymikee

.fallowrc.json

@@ -504,6 +504,11 @@
         "summarizeAgentBrowserProcesses",
         "summarizeManagedAgentBrowserProcesses"
       ]
+    },
+    {
+      "comment": "src/runtime.ts keeps its published type surface while its implementation moves to src/runtime-factory.ts (#2540). These two re-exports have no in-repo consumer; they stay so the module's exported shape is unchanged.",
+      "file": "src/runtime.ts",
+      "exports": ["CommandPolicy", "CommandSessionRecord"]
     }
   ],
   "usedClassMembers": [

src/commands/capture/runtime/index.ts

@@ -1,11 +1,13 @@
 import type { DiffSnapshotCommandResult } from '@agent-device/contracts/capture';
+import { bindRuntimeCommands } from '../../runtime-types.ts';
 import type {
   BoundOf,
   DiffSnapshotCommandOptions,
   RuntimeCommand,
   ScreenshotCommandOptions,
   SnapshotCommandOptions,
 } from '../../runtime-types.ts';
+import type { AgentDeviceRuntime } from '../../../runtime-contract.ts';
 import {
   diffScreenshotCommand,
   type DiffScreenshotCommandOptions,
@@ -29,3 +31,7 @@ export const captureCommands: CaptureCommands = {
   snapshot: snapshotCommand,
   diffSnapshot: diffSnapshotCommand,
 };
+
+export function bindCaptureCommands(runtime: AgentDeviceRuntime): BoundCaptureCommands {
+  return bindRuntimeCommands(captureCommands, runtime);
+}

src/commands/index.ts

@@ -1,6 +1,7 @@
 import type { AgentDeviceRuntime } from '../runtime-contract.ts';
 import { bindRuntimeCommands } from './runtime-types.ts';
 import {
+  bindCaptureCommands,
   captureCommands,
   type BoundCaptureCommands,
   type CaptureCommands,
@@ -80,7 +81,7 @@ export const commands: AgentDeviceCommands = {
 
 export function bindCommands(runtime: AgentDeviceRuntime): BoundAgentDeviceCommands {
   return {
-    capture: bindRuntimeCommands(captureCommands, runtime),
+    capture: bindCaptureCommands(runtime),
     selectors: bindSelectorCommands(runtime),
     interactions: bindInteractionCommands(runtime),
     system: bindRuntimeCommands(systemCommands, runtime),

src/daemon/interaction/internal/interaction-runtime.ts

@@ -5,7 +5,7 @@ import type {
   BackendActionResult,
   BackendSnapshotResult,
 } from '../../../backend.ts';
-import { createAgentDevice } from '../../../runtime.ts';
+import { createCommandSurfaceAgentDevice } from '../../../runtime-command-surface.ts';
 import { getRequestSignal } from '@agent-device/host-kit/request';
 import type { Rect } from '@agent-device/kernel/snapshot';
 import type { DaemonCommandContext } from '../../context.ts';
@@ -112,7 +112,7 @@ export function finalizeTouchInteraction(params: FinalizeTouchInteractionInput):
 }
 
 function createInteractionAgentDevice(params: InteractionRuntimeInput) {
-  return createAgentDevice({
+  return createCommandSurfaceAgentDevice({
     backend: createInteractionBackend(params),
     ...createDaemonRuntimePolicy('interaction commands', { plural: true }),
     sessions: params.runtimeSessions,

src/daemon/runtime-policy.ts

@@ -1,5 +1,5 @@
 import type { AgentDeviceRuntimeConfig } from '../runtime-contract.ts';
-import { localCommandPolicy } from '../runtime.ts';
+import { localCommandPolicy } from '../runtime-factory.ts';
 import { createUnsupportedArtifactAdapter } from './runtime-artifacts.ts';
 
 export function createDaemonRuntimePolicy(

src/daemon/screenshot-runtime.ts

@@ -13,7 +13,8 @@ import os from 'node:os';
 import path from 'node:path';
 import type { AgentDeviceBackend } from '../backend.ts';
 import type { ArtifactAdapter } from '../io.ts';
-import { createAgentDevice, localCommandPolicy } from '../runtime.ts';
+import { localCommandPolicy } from '../runtime-factory.ts';
+import { createCommandSurfaceAgentDevice } from '../runtime-command-surface.ts';
 import {
   assertSupportedScreenshotPixelDensity,
   readScreenshotResultMetadata,
@@ -116,7 +117,7 @@ export async function captureScreenshotArtifact(
   }>,
 ): Promise<CapturedScreenshot> {
   const { session, sessionName, outPath, dispatchContext } = params;
-  const runtime = createAgentDevice({
+  const runtime = createCommandSurfaceAgentDevice({
     backend: createBoundScreenshotBackend(params),
     artifacts: createDaemonScreenshotArtifactAdapter(),
     sessions: createDaemonRuntimeSessionStore({

src/daemon/selector-runtime-backend.ts

@@ -4,7 +4,7 @@ import type {
   BackendSnapshotResult,
 } from '../backend.ts';
 import { resolveTargetDevice } from '@agent-device/device-selection/dispatch-resolve';
-import { createAgentDevice } from '../runtime.ts';
+import { createCommandSurfaceAgentDevice } from '../runtime-command-surface.ts';
 import { publicPlatformString } from '@agent-device/kernel/device';
 import { noActiveSessionError } from './response.ts';
 import type { SnapshotState, SnapshotNode } from '@agent-device/kernel/snapshot';
@@ -67,7 +67,7 @@ type ResolvedSelectorDevice =
   | { ok: false; response: DaemonResponse };
 
 export function createSelectorRuntimeForDevice(params: SelectorRuntimeDeviceParams) {
-  return createAgentDevice({
+  return createCommandSurfaceAgentDevice({
     backend: createSelectorBackend(params),
     ...createDaemonRuntimePolicy('selector commands', { plural: true }),
     sessions: createDaemonRuntimeSessionStore({

src/daemon/snapshot-command-runtime.ts

@@ -8,7 +8,8 @@ import type { SnapshotResult } from '@agent-device/contracts/snapshot-runtime';
 import { publicPlatformString } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import type { AgentDeviceBackend, BackendSnapshotResult } from '../backend.ts';
-import { type CommandSessionRecord, createAgentDevice } from '../runtime.ts';
+import type { CommandSessionRecord } from '../runtime-contract.ts';
+import { createCommandSurfaceAgentDevice } from '../runtime-command-surface.ts';
 import { getRequestSignal } from '@agent-device/host-kit/request';
 import type { RuntimeAdmissionBindings } from './request-runtime-binding.ts';
 import { maybeBuildAndroidSnapshotTimeoutFailure } from './android-snapshot-timeout-evidence.ts';
@@ -128,7 +129,7 @@ function createSnapshotRuntime(
   } & RuntimeAdmissionBindings,
 ) {
   const { req, sessionName, logPath, sessionStore, session, device, snapshotScope } = params;
-  return createAgentDevice({
+  return createCommandSurfaceAgentDevice({
     backend: createDaemonSnapshotBackend({
       req,
       logPath,

src/runtime-command-surface.ts

@@ -0,0 +1,37 @@
+import {
+  bindInteractionCommands,
+  bindSelectorCommands,
+  type BoundInteractionCommands,
+  type BoundSelectorCommands,
+} from './commands/interaction/runtime/index.ts';
+import {
+  bindCaptureCommands,
+  type BoundCaptureCommands,
+} from './commands/capture/runtime/index.ts';
+import { createAgentDeviceRuntime } from './runtime-factory.ts';
+import type { AgentDeviceRuntime, AgentDeviceRuntimeConfig } from './runtime-contract.ts';
+
+/**
+ * The command surface an in-process executor dispatches through: capture, selector reads and
+ * interactions. `src/runtime.ts` binds every family for the public SDK and CLI surface; a host
+ * that only executes these three should not evaluate the management, recording, observability and
+ * system families to get them. The runtime assembly is shared with `createAgentDevice`, so there
+ * is one construction path and this differs only in the families it binds.
+ */
+export type CommandSurfaceAgentDevice = AgentDeviceRuntime & {
+  capture: BoundCaptureCommands;
+  selectors: BoundSelectorCommands;
+  interactions: BoundInteractionCommands;
+};
+
+export function createCommandSurfaceAgentDevice(
+  config: AgentDeviceRuntimeConfig,
+): CommandSurfaceAgentDevice {
+  const runtime = createAgentDeviceRuntime(config);
+  return {
+    ...runtime,
+    capture: bindCaptureCommands(runtime),
+    selectors: bindSelectorCommands(runtime),
+    interactions: bindInteractionCommands(runtime),
+  };
+}

src/runtime-factory.ts

@@ -0,0 +1,83 @@
+import type {
+  AgentDeviceRuntime,
+  AgentDeviceRuntimeConfig,
+  CommandPolicy,
+  CommandSessionRecord,
+  CommandSessionStore,
+} from './runtime-contract.ts';
+
+/**
+ * Assembles an in-process runtime from its backend, artifact adapter, session store, policy and
+ * cancellation inputs. Carries no command surface: whoever needs bound commands composes them on
+ * the result, so a consumer that only reads `backend`/`sessions`/`policy` does not evaluate the
+ * command families it never dispatches.
+ */
+export function createAgentDeviceRuntime(config: AgentDeviceRuntimeConfig): AgentDeviceRuntime {
+  return {
+    backend: config.backend,
+    artifacts: config.artifacts,
+    sessions: config.sessions ?? createMemorySessionStore(),
+    policy: config.policy ?? restrictedCommandPolicy(),
+    diagnostics: config.diagnostics,
+    clock: config.clock,
+    signal: config.signal,
+  };
+}
+
+export function createMemorySessionStore(
+  records: readonly CommandSessionRecord[] = [],
+): CommandSessionStore {
+  const sessions = new Map(records.map((record) => [record.name, cloneSessionRecord(record)]));
+  return {
+    get: (name) => cloneSessionRecord(sessions.get(name)),
+    set: (record) => {
+      sessions.set(record.name, cloneSessionRecord(record));
+    },
+    delete: (name) => {
+      sessions.delete(name);
+    },
+    list: () => Array.from(sessions.values(), (record) => cloneSessionRecord(record)),
+  };
+}
+
+function cloneSessionRecord(record: CommandSessionRecord): CommandSessionRecord;
+function cloneSessionRecord(record: undefined): undefined;
+function cloneSessionRecord(
+  record: CommandSessionRecord | undefined,
+): CommandSessionRecord | undefined;
+function cloneSessionRecord(
+  record: CommandSessionRecord | undefined,
+): CommandSessionRecord | undefined {
+  if (!record) return undefined;
+  return {
+    ...record,
+    ...(record.snapshot ? { snapshot: structuredClone(record.snapshot) } : {}),
+    ...(record.metadata ? { metadata: cloneMetadata(record.metadata) } : {}),
+  };
+}
+
+function cloneMetadata(metadata: Record<string, unknown>): Record<string, unknown> {
+  try {
+    return structuredClone(metadata) as Record<string, unknown>;
+  } catch {
+    return { ...metadata };
+  }
+}
+
+export function localCommandPolicy(overrides: Partial<CommandPolicy> = {}): CommandPolicy {
+  return {
+    allowLocalInputPaths: true,
+    allowLocalOutputPaths: true,
+    maxImagePixels: 20_000_000,
+    ...overrides,
+  };
+}
+
+export function restrictedCommandPolicy(overrides: Partial<CommandPolicy> = {}): CommandPolicy {
+  return {
+    allowLocalInputPaths: false,
+    allowLocalOutputPaths: false,
+    maxImagePixels: 20_000_000,
+    ...overrides,
+  };
+}