refactor(capture-kit): take the host explicitly for Swift cache and recording tooling

capture-kit no longer reads the command host, so its suites need no bound host
and its local test-host copy is gone; the root recording seams supply the host.
test-kit keeps depending on capture-kit again, and capture-kit does not depend on
test-kit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: thymikee

packages/capture-kit/package.json

@@ -356,7 +356,6 @@
     }
   },
   "devDependencies": {
-    "@agent-device/test-kit": "workspace:*",
     "@types/pngjs": "^6.0.5",
     "fast-check": "^4.9.0",
     "jpeg-js": "^0.4.4",

packages/capture-kit/src/host-environment.fixtures.ts

@@ -0,0 +1,11 @@
+import { captureHostEnvironment } from '@agent-device/host-kit/process';
+import type { HostEnvironment } from '@agent-device/kernel/source-value';
+
+/**
+ * The host a capture-kit test hands to code that takes one explicitly: a snapshot of the process
+ * as it is when called, so `vi.stubEnv` made earlier in the test reaches it. Test-kit depends on
+ * capture-kit, so capture-kit keeps this local.
+ */
+export function createTestHost(): HostEnvironment {
+  return captureHostEnvironment(process);
+}

packages/capture-kit/src/index.ts

@@ -7,7 +7,7 @@ export {
   createAppLogStartResult,
   decodeAppLogProcessMarker,
 } from './app-log-runtime.ts';
-export { createAppLogLiveHandleFromFinish } from './app-log-live-handle.ts';
+export { createAppLogLiveHandle, createAppLogLiveHandleFromFinish } from './app-log-live-handle.ts';
 export { createHostAudioProbeCaptureOperations } from './audio-probe-runtime.ts';
 export { decodeDurableDescriptor } from './durable-descriptor-codec.ts';
 export { createScreenRecordingLiveHandle } from './screen-recording-live-handle.ts';

packages/capture-kit/src/recording/__tests__/overlay.test.ts

@@ -1,10 +1,8 @@
 import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import { createTestHost } from '../../host-environment.fixtures.ts';
 import fs from 'node:fs';
 import path from 'node:path';
 import { mkdtempForTestSync } from '../../tmp-dir.fixtures.ts';
-import { bindTestCommandHost } from '@agent-device/test-kit';
-
-bindTestCommandHost();
 
 vi.mock('@agent-device/host-kit/command', async (importOriginal) => {
   const fs = await import('node:fs');
@@ -66,12 +64,14 @@ test('overlay burns touches through a cached helper and same-directory temp outp
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
   });
   fs.writeFileSync(videoPath, 'second original');
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -112,7 +112,12 @@ test('overlay preserves Swift helper compile hints', async () => {
   });
 
   await expect(
-    overlayRecordingTouches({ videoPath, telemetryPath, deadline: startRecordingOverlayBudget() }),
+    overlayRecordingTouches({
+      host: createTestHost(),
+      videoPath,
+      telemetryPath,
+      deadline: startRecordingOverlayBudget(),
+    }),
   ).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     message: 'Failed to add touch overlays to the recording',
@@ -129,6 +134,7 @@ test('overlay defaults to the fast medium export preset', async () => {
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -146,6 +152,7 @@ test('overlay forwards the requested high export preset', async () => {
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -164,6 +171,7 @@ test('overlay caps the helper frame rate at the caller fps only when one was ask
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -172,6 +180,7 @@ test('overlay caps the helper frame rate at the caller fps only when one was ask
 
   mockRunCmd.mockClear();
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -188,6 +197,7 @@ test('overlay hands the helper what is left of its budget, inside the record req
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -215,7 +225,7 @@ test('overlay hands the helper only what the finalization left of the budget', a
   const deadline = startRecordingOverlayBudget();
   vi.setSystemTime(Date.now() + spentMs);
 
-  await overlayRecordingTouches({ videoPath, telemetryPath, deadline });
+  await overlayRecordingTouches({ host: createTestHost(), videoPath, telemetryPath, deadline });
 
   const helperCall = mockRunCmd.mock.calls.find(([cmd]) => cmd !== 'xcrun');
   expect(helperCall?.[2]?.timeoutMs).toBe(OVERLAY_BUDGET_MS - spentMs);
@@ -237,7 +247,12 @@ test('overlay leaves the video as recorded when compiling the helper spent its b
   });
 
   await expect(
-    overlayRecordingTouches({ videoPath, telemetryPath, deadline: startRecordingOverlayBudget() }),
+    overlayRecordingTouches({
+      host: createTestHost(),
+      videoPath,
+      telemetryPath,
+      deadline: startRecordingOverlayBudget(),
+    }),
   ).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     message: 'Failed to add touch overlays to the recording',
@@ -254,6 +269,7 @@ test('overlay names its budget when the export ran out of it', async () => {
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -265,7 +281,12 @@ test('overlay names its budget when the export ran out of it', async () => {
   });
 
   await expect(
-    overlayRecordingTouches({ videoPath, telemetryPath, deadline: startRecordingOverlayBudget() }),
+    overlayRecordingTouches({
+      host: createTestHost(),
+      videoPath,
+      telemetryPath,
+      deadline: startRecordingOverlayBudget(),
+    }),
   ).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     message: `Failed to add touch overlays to the recording: the export did not finish within its ${OVERLAY_BUDGET_MS}ms budget; a lower --fps renders faster`,
@@ -280,6 +301,7 @@ test('overlay keeps the plain failure when the export failed with budget to spar
   fs.writeFileSync(telemetryPath, '{"events":[]}');
 
   await overlayRecordingTouches({
+    host: createTestHost(),
     videoPath,
     telemetryPath,
     deadline: startRecordingOverlayBudget(),
@@ -289,7 +311,12 @@ test('overlay keeps the plain failure when the export failed with budget to spar
   });
 
   await expect(
-    overlayRecordingTouches({ videoPath, telemetryPath, deadline: startRecordingOverlayBudget() }),
+    overlayRecordingTouches({
+      host: createTestHost(),
+      videoPath,
+      telemetryPath,
+      deadline: startRecordingOverlayBudget(),
+    }),
   ).rejects.toMatchObject({
     message: 'Failed to add touch overlays to the recording',
   });
@@ -307,12 +334,15 @@ test('overlay keeps the video as recorded when verifying the export spent its bu
   });
 
   await expect(
-    overlayRecordingTouches({ videoPath, telemetryPath, deadline }),
+    overlayRecordingTouches({ host: createTestHost(), videoPath, telemetryPath, deadline }),
   ).rejects.toMatchObject({
     code: 'COMMAND_FAILED',
     message: `Failed to add touch overlays to the recording: the export did not finish within its ${OVERLAY_BUDGET_MS}ms budget; a lower --fps renders faster`,
   });
-  expect(vi.mocked(waitForPlayableVideo)).toHaveBeenCalledWith(expect.any(String), { deadline });
+  expect(vi.mocked(waitForPlayableVideo)).toHaveBeenCalledWith(expect.any(String), {
+    host: expect.objectContaining({ cwd: process.cwd() }),
+    deadline,
+  });
   expect(fs.readFileSync(videoPath, 'utf8')).toBe('original');
   expect(fs.readdirSync(tmpDir).filter((name) => name.includes('agent-device-'))).toEqual([]);
 });

packages/capture-kit/src/recording/contact-sheet-frames.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { createTestHost } from '../host-environment.fixtures.ts';
 import path from 'node:path';
 import {
   CONTACT_SHEET_EXTRACTION_REASON,
@@ -7,13 +8,10 @@ import {
 } from './contact-sheet-report.ts';
 import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors';
 import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts';
-import { bindTestCommandHost } from '@agent-device/test-kit';
 import { solidPng } from '../png-pixels.fixtures.ts';
 import { writeDecodedFrames, type StubFrame } from './contact-sheet.fixtures.ts';
 import { extractRecordingFrames } from './contact-sheet-frames.ts';
 
-bindTestCommandHost();
-
 vi.mock(import('@agent-device/host-kit/command'), async (importOriginal) => ({
   ...(await importOriginal()),
   runCmd: vi.fn(),
@@ -40,9 +38,9 @@ function reasonOf(action: () => Promise<unknown>): Promise<unknown> | unknown {
 
 /** Decoding is Apple tooling, so every case here states the host it is pretending to be. */
 function extract(
-  input: Omit<Parameters<typeof extractRecordingFrames>[0], 'hostPlatform'>,
+  input: Omit<Parameters<typeof extractRecordingFrames>[0], 'hostPlatform' | 'host'>,
 ): Promise<Awaited<ReturnType<typeof extractRecordingFrames>>> {
-  return extractRecordingFrames({ ...input, hostPlatform: 'darwin' });
+  return extractRecordingFrames({ host: createTestHost(), ...input, hostPlatform: 'darwin' });
 }
 
 function withTimes(args: readonly string[], times: string): string[] {
@@ -66,6 +64,7 @@ describe('extractRecordingFrames', () => {
     expect(
       await reasonOf(() =>
         extractRecordingFrames({
+          host: createTestHost(),
           videoPath: VIDEO,
           scratchDir,
           maxWidth: CELL_WIDTH,

packages/capture-kit/src/recording/contact-sheet-frames.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import type { HostEnvironment } from '@agent-device/kernel/source-value';
 import path from 'node:path';
 import {
   CONTACT_SHEET_EXTRACTION_REASON,
@@ -67,6 +68,7 @@ export type ExtractedRecordingFrames = Readonly<{
  */
 export async function extractRecordingFrames(
   input: Readonly<{
+    host: HostEnvironment;
     videoPath: string;
     scratchDir: string;
     timesMs: readonly number[];
@@ -107,7 +109,7 @@ export async function extractRecordingFrames(
       ],
       {
         timeoutMs: EXTRACTION_TIMEOUT_MS,
-        env: buildSwiftToolEnv(),
+        env: buildSwiftToolEnv(input.host.env),
         allowFailure: true,
         ...(input.signal === undefined ? {} : { signal: input.signal }),
       },
@@ -260,11 +262,17 @@ function lastNonEmptyLine(text: string): string {
  * Compiles the decoder helper, or fails as an extraction failure: a cold Swift cache that cannot
  * build the helper is exactly as unable to produce a sheet as a helper that exits nonzero.
  */
-async function compileDecoder(input: { videoPath: string; signal?: AbortSignal }): Promise<string> {
+async function compileDecoder(input: {
+  host: HostEnvironment;
+  videoPath: string;
+  signal?: AbortSignal;
+}): Promise<string> {
+  const { cwd } = input.host;
   try {
     return await compileSwiftSourceFile({
-      sourcePath: resolveRecordingScriptPath(FRAMES_SCRIPT, findProjectRoot()),
-      extraSourcePaths: [resolveRecordingScriptPath(SHARED_SUPPORT_SCRIPT, findProjectRoot())],
+      host: input.host,
+      sourcePath: resolveRecordingScriptPath(FRAMES_SCRIPT, findProjectRoot(), cwd),
+      extraSourcePaths: [resolveRecordingScriptPath(SHARED_SUPPORT_SCRIPT, findProjectRoot(), cwd)],
       cacheName: 'recording-frames',
       timeoutMs: COMPILATION_TIMEOUT_MS,
     });

packages/capture-kit/src/recording/contact-sheet.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { createTestHost } from '../host-environment.fixtures.ts';
 import fs from 'node:fs';
 import path from 'node:path';
 import {
@@ -12,14 +13,11 @@ import {
 import { AppError } from '@agent-device/kernel/errors';
 import { BLACK, RED, WHITE, paintPng, solidPng } from '../png-pixels.fixtures.ts';
 import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts';
-import { bindTestCommandHost } from '@agent-device/test-kit';
 import { decodePng } from '../png.ts';
 import { mp4Atom, mp4MovieHeader } from './mp4.fixtures.ts';
 import { writeDecodedFrames, type StubFrame } from './contact-sheet.fixtures.ts';
 import { buildRecordingContactSheet, recordingContactSheetPath } from './contact-sheet.ts';
 
-bindTestCommandHost();
-
 vi.mock(import('@agent-device/host-kit/command'), async (importOriginal) => ({
   ...(await importOriginal()),
   runCmd: vi.fn(),
@@ -101,6 +99,7 @@ type BuildInput = Partial<
 
 function build(videoPath: string, input: BuildInput = {}) {
   return buildRecordingContactSheet({
+    host: createTestHost(),
     ...input,
     videoPath,
     maxPixels: input.maxPixels ?? 20_000_000,

packages/capture-kit/src/recording/contact-sheet.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import type { HostEnvironment } from '@agent-device/kernel/source-value';
 import os from 'node:os';
 import path from 'node:path';
 import {
@@ -50,6 +51,7 @@ export type { RecordingContactSheetResult } from './contact-sheet-report.ts';
  */
 export async function buildRecordingContactSheet(
   input: Readonly<{
+    host: HostEnvironment;
     videoPath: string;
     outputPath?: string;
     maxPixels: number;
@@ -83,6 +85,7 @@ export async function buildRecordingContactSheet(
   const scratchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-contact-sheet-'));
   try {
     const extracted = await extractRecordingFrames({
+      host: input.host,
       videoPath,
       scratchDir,
       timesMs: grid.timesMs,