refactor: isolate host audio probe backend

Author: thymikee

src/core/command-descriptor/registry.ts

@@ -5,6 +5,7 @@ import {
 } from '../../command-catalog.ts';
 import type { CommandCapability } from '../capabilities.ts';
 import type { DaemonRequest } from '../../daemon/types.ts';
+import { isAudioProbeSupportedDevice } from '../../kernel/audio-probe-support.ts';
 import { isTvOsDevice, type DeviceInfo } from '../../kernel/device.ts';
 import type { CommandDescriptor } from './types.ts';
 
@@ -47,13 +48,6 @@ const supportsSynthesisGesture = (device: DeviceInfo): boolean =>
   device.platform === 'android' || isIosMobileSimulator(device);
 const supportsAndroidOrIosNonTv = (device: DeviceInfo): boolean =>
   device.platform === 'android' || (device.platform === 'ios' && !isTvOsDevice(device));
-const isHostSystemAudioProbeDevice = (device: DeviceInfo): boolean =>
-  device.platform === 'web' ||
-  (process.platform === 'darwin' &&
-    (device.platform === 'macos' ||
-      (device.platform === 'ios' && device.kind === 'simulator') ||
-      (device.platform === 'android' && device.kind === 'emulator')));
-
 const synthesisGestureUnsupportedHint = (device: DeviceInfo): string | undefined => {
   if (device.platform === 'macos')
     return 'macOS automation has no multi-touch input — this gesture is supported on Android and the iOS simulator only.';
@@ -192,7 +186,7 @@ const RAW_COMMAND_DESCRIPTORS = [
       apple: APPLE_SIM_AND_DEVICE,
       android: { emulator: true },
       linux: LINUX_NONE,
-      supports: isHostSystemAudioProbeDevice,
+      supports: isAudioProbeSupportedDevice,
     },
     batchable: true,
   },

src/daemon/audio-probe.ts

@@ -5,18 +5,17 @@ import {
   normalizeAudioProbeRecord,
   type AudioProbeResult,
 } from '../audio-probe-result.ts';
-import { startMacOsAudioProbeProcess } from '../platforms/apple/os/macos/helper.ts';
+import type { HostAudioProbeBackend } from '../platforms/audio-probe-backend.ts';
 import { AppError } from '../kernel/errors.ts';
 import { sleep } from '../utils/timeouts.ts';
 import type { SessionStore } from './session-store.ts';
 import type { SessionState } from './types.ts';
 
-const HOST_AUDIO_BACKEND = 'macos-screencapturekit';
-
 export type HostAudioProbeCommand = {
   session: SessionState;
   sessionName: string;
   sessionStore: SessionStore;
+  backend: HostAudioProbeBackend;
   probeAction: 'start' | 'status' | 'stop';
   durationMs: number;
   bucketMs: number;
@@ -25,20 +24,24 @@ export type HostAudioProbeCommand = {
 export async function runHostSystemAudioProbeCommand(
   request: HostAudioProbeCommand,
 ): Promise<AudioProbeResult> {
-  const { session, probeAction } = request;
+  const { session, probeAction, backend } = request;
   if (probeAction === 'start') {
     await stopSessionAudioProbe(session, 'restarted');
     const statusPath = path.join(
       request.sessionStore.ensureSessionDir(request.sessionName),
       'audio-probe.json',
     );
-    const probe = await startMacOsAudioProbeProcess({
+    const probe = await backend.start({
       durationMs: request.durationMs,
       bucketMs: request.bucketMs,
       statusPath,
     });
     session.audioProbe = {
-      platform: 'host-system-audio',
+      platform: backend.platform,
+      source: backend.source,
+      backend: backend.backend,
+      sourceCount: backend.sourceCount,
+      notes: backend.notes(session.device),
       child: probe.child,
       wait: probe.wait,
       statusPath,
@@ -75,7 +78,7 @@ export async function stopSessionAudioProbe(
   probe.child.kill('SIGTERM');
   await probe.wait.catch(() => {});
   session.audioProbe = undefined;
-  return finalizeHostSystemAudioProbeStatus(beforeStop, probe, session.device, reason);
+  return finalizeHostSystemAudioProbeStatus(beforeStop, probe, reason);
 }
 
 async function waitForHostSystemAudioProbeStatus(session: SessionState): Promise<AudioProbeResult> {
@@ -110,7 +113,7 @@ async function readHostSystemAudioProbeStatus(
   if (!probe) return undefined;
   try {
     const raw = await fs.readFile(probe.statusPath, 'utf8');
-    return normalizeHostSystemAudioProbeData(JSON.parse(raw), probe, session.device);
+    return normalizeHostSystemAudioProbeData(JSON.parse(raw), probe);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
     throw error;
@@ -120,36 +123,34 @@ async function readHostSystemAudioProbeStatus(
 function normalizeHostSystemAudioProbeData(
   value: unknown,
   probe: NonNullable<SessionState['audioProbe']>,
-  device: SessionState['device'],
 ): AudioProbeResult {
   return normalizeAudioProbeRecord(value, {
-    source: 'system-audio',
-    backend: HOST_AUDIO_BACKEND,
+    source: probe.source,
+    backend: probe.backend,
     durationMs: probe.durationMs,
     elapsedMs: Date.now() - probe.startedAt,
     bucketMs: probe.bucketMs,
     activeFallback: true,
-    sourceCount: 1,
-    notes: hostSystemAudioProbeNotes(device),
+    sourceCount: probe.sourceCount,
+    notes: probe.notes,
   });
 }
 
 function finalizeHostSystemAudioProbeStatus(
   status: AudioProbeResult | undefined,
   probe: NonNullable<SessionState['audioProbe']>,
-  device: SessionState['device'],
   reason: string,
 ): AudioProbeResult {
   const elapsedMs = Math.min(probe.durationMs, Math.max(0, Date.now() - probe.startedAt));
   const base =
     status ??
     emptyAudioProbeResult({
-      source: 'system-audio',
-      backend: HOST_AUDIO_BACKEND,
+      source: probe.source,
+      backend: probe.backend,
       durationMs: probe.durationMs,
       bucketMs: probe.bucketMs,
-      sourceCount: 1,
-      notes: hostSystemAudioProbeNotes(device),
+      sourceCount: probe.sourceCount,
+      notes: probe.notes,
     });
   return {
     ...base,
@@ -168,29 +169,15 @@ function buildHostSystemAudioProbeFallback(
 ): AudioProbeResult {
   return emptyAudioProbeResult({
     state,
-    source: 'system-audio',
-    backend: HOST_AUDIO_BACKEND,
+    source: request.backend.source,
+    backend: request.backend.backend,
     durationMs: request.durationMs,
     bucketMs: request.bucketMs,
     sourceCount: 0,
     reason,
     notes: [
-      ...hostSystemAudioProbeNotes(request.session.device),
+      ...request.backend.notes(request.session.device),
       'No active host audio probe is running.',
     ],
   });
 }
-
-function hostSystemAudioProbeNotes(device: SessionState['device']): string[] {
-  const target =
-    device.platform === 'ios'
-      ? 'iOS simulator'
-      : device.platform === 'android'
-        ? 'Android emulator'
-        : 'macOS session';
-  return [
-    `Audio probe samples host system audio through ScreenCaptureKit for this ${target}; it is not app-instrumented audio.`,
-    'Screen Recording permission is required for host system audio capture.',
-    'Other audible host apps can contribute to the measured buckets.',
-  ];
-}

src/daemon/handlers/__tests__/session-close-shutdown.test.ts

@@ -409,6 +409,14 @@ test('close stops active host audio probe before deleting session', async () =>
     }),
     audioProbe: {
       platform: 'host-system-audio',
+      source: 'system-audio',
+      backend: 'macos-screencapturekit',
+      sourceCount: 1,
+      notes: [
+        'Audio probe samples host system audio through ScreenCaptureKit for this macOS session; it is not app-instrumented audio.',
+        'Screen Recording permission is required for host system audio capture.',
+        'Other audible host apps can contribute to the measured buckets.',
+      ],
       child: { kill, pid: 1234 },
       wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
       statusPath: path.join(os.tmpdir(), 'missing-audio-probe.json'),

src/daemon/handlers/__tests__/session-observability.test.ts

@@ -553,6 +553,14 @@ test('audio probe stop kills active macOS helper and returns stopped status', as
   const kill = vi.fn();
   session.audioProbe = {
     platform: 'host-system-audio',
+    source: 'system-audio',
+    backend: 'macos-screencapturekit',
+    sourceCount: 1,
+    notes: [
+      'Audio probe samples host system audio through ScreenCaptureKit for this macOS session; it is not app-instrumented audio.',
+      'Screen Recording permission is required for host system audio capture.',
+      'Other audible host apps can contribute to the measured buckets.',
+    ],
     child: { kill, pid: 1234 },
     wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
     statusPath,

src/daemon/handlers/session-observability.ts

@@ -14,6 +14,10 @@ import {
 } from '../../contracts/perf.ts';
 import { AppError, normalizeError } from '../../kernel/errors.ts';
 import { resolveWebProvider } from '../../platforms/web/provider.ts';
+import {
+  resolveHostAudioProbeBackend,
+  type HostAudioProbeBackend,
+} from '../../platforms/audio-probe-backend.ts';
 import type { AndroidAdbExecutor } from '../../platforms/android/adb-executor.ts';
 import type { DaemonRequest, DaemonResponse, DaemonResponseData, SessionState } from '../types.ts';
 import { SessionStore } from '../session-store.ts';
@@ -619,8 +623,9 @@ function resolveNetworkIncludeMode(
 async function handleAudioCommand(params: ObservabilityParams): Promise<DaemonResponse> {
   const request = resolveAudioCommandRequest(params);
   if (!request.ok) return request;
-  if (usesHostSystemAudioProbe(request.session)) {
-    return await handleHostSystemAudioCommand(params, request);
+  const hostBackend = await resolveHostAudioProbeBackend(request.session.device);
+  if (hostBackend) {
+    return await handleHostSystemAudioCommand(params, request, hostBackend);
   }
   const provider = resolveWebProvider();
   if (!provider.probeAudio) {
@@ -682,13 +687,10 @@ type ResolvedAudioCommandRequest = Extract<
   { ok: true }
 >;
 
-function usesHostSystemAudioProbe(session: SessionState): boolean {
-  return session.device.platform !== 'web';
-}
-
 async function handleHostSystemAudioCommand(
   params: ObservabilityParams,
   request: ResolvedAudioCommandRequest,
+  backend: HostAudioProbeBackend,
 ): Promise<DaemonResponse> {
   try {
     return {
@@ -697,6 +699,7 @@ async function handleHostSystemAudioCommand(
         session: request.session,
         sessionName: params.sessionName,
         sessionStore: params.sessionStore,
+        backend,
         probeAction: request.probeAction,
         durationMs: request.durationMs,
         bucketMs: request.bucketMs,

src/daemon/types.ts

@@ -25,6 +25,7 @@ import type {
   AppleXctracePerfCapture,
   AppleXctracePerfMode,
 } from '../platforms/apple/core/perf-xctrace.ts';
+import type { AudioProbeSource } from '../audio-probe-result.ts';
 import type {
   SnapshotDiagnosticsState,
   SnapshotDiagnosticsSummary,
@@ -271,6 +272,10 @@ export type SessionState = {
   };
   audioProbe?: {
     platform: 'host-system-audio';
+    source: AudioProbeSource;
+    backend: string;
+    sourceCount: number;
+    notes: string[];
     child: SessionRecordingProcessChild;
     wait: Promise<ExecResult>;
     statusPath: string;

src/kernel/audio-probe-support.ts

@@ -0,0 +1,14 @@
+import type { DeviceInfo } from './device.ts';
+
+export function isHostSystemAudioProbeDevice(device: DeviceInfo): boolean {
+  return (
+    process.platform === 'darwin' &&
+    (device.platform === 'macos' ||
+      (device.platform === 'ios' && device.kind === 'simulator') ||
+      (device.platform === 'android' && device.kind === 'emulator'))
+  );
+}
+
+export function isAudioProbeSupportedDevice(device: DeviceInfo): boolean {
+  return device.platform === 'web' || isHostSystemAudioProbeDevice(device);
+}

src/platforms/apple/os/macos/audio-probe.ts

@@ -0,0 +1,26 @@
+import type { DeviceInfo } from '../../../../kernel/device.ts';
+import type { HostAudioProbeBackend } from '../../../audio-probe-backend.ts';
+import { startMacOsAudioProbeProcess } from './helper.ts';
+
+export const macOsScreenCaptureKitAudioProbeBackend = {
+  platform: 'host-system-audio',
+  source: 'system-audio',
+  backend: 'macos-screencapturekit',
+  sourceCount: 1,
+  start: startMacOsAudioProbeProcess,
+  notes: hostSystemAudioProbeNotes,
+} as const satisfies HostAudioProbeBackend;
+
+function hostSystemAudioProbeNotes(device: DeviceInfo): string[] {
+  const target =
+    device.platform === 'ios'
+      ? 'iOS simulator'
+      : device.platform === 'android'
+        ? 'Android emulator'
+        : 'macOS session';
+  return [
+    `Audio probe samples host system audio through ScreenCaptureKit for this ${target}; it is not app-instrumented audio.`,
+    'Screen Recording permission is required for host system audio capture.',
+    'Other audible host apps can contribute to the measured buckets.',
+  ];
+}

src/platforms/audio-probe-backend.ts

@@ -0,0 +1,28 @@
+import type { AudioProbeSource } from '../audio-probe-result.ts';
+import { isHostSystemAudioProbeDevice } from '../kernel/audio-probe-support.ts';
+import type { DeviceInfo } from '../kernel/device.ts';
+import type { ExecBackgroundResult } from '../utils/exec.ts';
+
+export type HostAudioProbeStartOptions = {
+  durationMs: number;
+  bucketMs: number;
+  statusPath: string;
+};
+
+export type HostAudioProbeBackend = {
+  platform: 'host-system-audio';
+  source: AudioProbeSource;
+  backend: string;
+  sourceCount: number;
+  start(options: HostAudioProbeStartOptions): Promise<ExecBackgroundResult>;
+  notes(device: DeviceInfo): string[];
+};
+
+export async function resolveHostAudioProbeBackend(
+  device: DeviceInfo,
+): Promise<HostAudioProbeBackend | undefined> {
+  if (!isHostSystemAudioProbeDevice(device)) return undefined;
+  const { macOsScreenCaptureKitAudioProbeBackend } =
+    await import('./apple/os/macos/audio-probe.ts');
+  return macOsScreenCaptureKitAudioProbeBackend;
+}