@ai-sdk/harness 1.0.123 → 1.0.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.123",
+  "version": "1.0.126",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -45,8 +45,8 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.18",
-    "@ai-sdk/provider-utils": "5.0.47",
-    "ai": "7.0.113"
+    "@ai-sdk/provider-utils": "5.0.49",
+    "ai": "7.0.116"
   },
   "peerDependencies": {
     "ws": "^8.21.0",
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/otel": "1.0.113",
+    "@ai-sdk/otel": "1.0.116",
     "@opentelemetry/sdk-trace-base": "2.7.1",
     "@types/node": "22.19.19",
     "@types/ws": "^8.5.13",

package/src/agent/create-harness-sandbox-template.ts

@@ -0,0 +1,80 @@
+import type {
+  HarnessAgentAdapter,
+  HarnessSandboxTemplate,
+} from './harness-agent-types';
+import type { HarnessAgentSandboxConfig } from './harness-agent-settings';
+import { hashHarnessBootstrap } from './internal/bootstrap-recipe';
+import { resolvePreparedSandboxIdentity } from './internal/prepared-sandbox-identity';
+import {
+  normalizeSandboxWorkDir,
+  runSandboxBootstrap,
+  validateSandboxBootstrapSettings,
+} from './internal/sandbox-bootstrap';
+
+export async function createHarnessSandboxTemplate(options: {
+  readonly harnesses: ReadonlyArray<HarnessAgentAdapter>;
+  readonly sandboxConfig?: Omit<HarnessAgentSandboxConfig, 'onSession'>;
+}): Promise<HarnessSandboxTemplate | undefined> {
+  if (options.harnesses.length === 0) {
+    throw new Error(
+      'createHarnessSandboxTemplate: at least one harness must be provided.',
+    );
+  }
+  const settings = options.sandboxConfig ?? {};
+  validateSandboxBootstrapSettings(settings);
+  const workDir =
+    settings.workDir == null
+      ? undefined
+      : normalizeSandboxWorkDir(settings.workDir);
+  const harnesses = [
+    ...new Map(
+      options.harnesses.map(harness => [harness.harnessId, harness]),
+    ).values(),
+  ].sort((a, b) => a.harnessId.localeCompare(b.harnessId));
+  const recipes = await Promise.all(
+    harnesses.map(async harness => {
+      const recipe = await harness.getBootstrap?.({});
+      return recipe == null
+        ? undefined
+        : {
+            recipe,
+            identity: await hashHarnessBootstrap(recipe),
+          };
+    }),
+  );
+  const recipeIdentities: Record<string, string> = {};
+  for (let index = 0; index < harnesses.length; index++) {
+    const entry = recipes[index];
+    if (entry != null)
+      recipeIdentities[harnesses[index].harnessId] = entry.identity;
+  }
+  const identity = await resolvePreparedSandboxIdentity({
+    recipeIdentities,
+    bootstrapHash: settings.bootstrapHash,
+    workDir,
+  });
+  if (identity == null) return undefined;
+  return {
+    identity,
+    prepare: async ({ session, abortSignal }) => {
+      for (const entry of recipes) {
+        if (entry != null) {
+          await runSandboxBootstrap({
+            session,
+            recipe: entry.recipe,
+            recipeIdentity: entry.identity,
+            abortSignal,
+          });
+        }
+      }
+      await runSandboxBootstrap({
+        session,
+        workDir,
+        onBootstrap: settings.onBootstrap,
+        bootstrapHash: settings.bootstrapHash,
+        skipOnBootstrapIfMarked: true,
+        abortSignal,
+      });
+    },
+  };
+}

package/src/agent/harness-agent-settings.ts

@@ -356,6 +356,7 @@ export type HarnessAgentSettings<
    * sessions. When omitted, every `createSession()` call must provide an
    * existing network sandbox session.
    */
+  /** @deprecated Supply `sandboxSession` to `HarnessAgent.createSession()` instead. */
   readonly sandbox?: HarnessV1SandboxProvider;
 
   /**

package/src/agent/harness-agent-types.ts

@@ -15,6 +15,7 @@ import type {
   HarnessV1PromptControl,
   HarnessV1PromptTurnOptions,
   HarnessV1ResumeSessionState,
+  HarnessV1SandboxTemplate,
   HarnessV1Session,
   HarnessV1Skill,
   HarnessV1StartOptions,
@@ -24,6 +25,7 @@ import type {
 
 export type HarnessAgentAdapter<TBuiltinTools extends ToolSet = ToolSet> =
   HarnessV1<TBuiltinTools>;
+export type HarnessSandboxTemplate = HarnessV1SandboxTemplate;
 
 export type HarnessAgentBuiltinTool<
   INPUT = unknown,

package/src/agent/harness-agent.ts

@@ -48,6 +48,7 @@ import type {
   HarnessAgentResumeSessionState,
   HarnessAgentSkill,
   HarnessAgentToolSpec,
+  HarnessSandboxTemplate,
 } from './harness-agent-types';
 import { collectHarnessAgentToolApprovalContinuations } from './harness-agent-tool-approval-continuation';
 import { collectHarnessAgentToolResultContinuations } from './harness-agent-tool-result-continuation';
@@ -59,6 +60,7 @@ import {
   createSandboxBootstrapPlan,
   ensureSandboxDirectory,
   resolveSessionWorkDir,
+  runSandboxBootstrap,
   validateSandboxBootstrapSettings,
 } from './internal/sandbox-bootstrap';
 import { buildObservability } from './internal/resolve-observability';
@@ -72,6 +74,7 @@ import { resolveSandboxDefaultWorkingDirectory } from '../utils/resolve-sandbox-
 import { resolveSandboxHomeDir } from '../utils/sandbox-home-dir';
 import { getRestrictedSandboxSession } from '../utils/get-restricted-sandbox-session';
 import type { HarnessAgentLifecycleCallbacks } from './internal/turn-telemetry';
+import { createHarnessSandboxTemplate } from './create-harness-sandbox-template';
 
 export type { HarnessAllTools } from './harness-agent-tool-types';
 
@@ -222,6 +225,11 @@ export class HarnessAgent<
       CALL_OPTIONS
     >,
   ) {
+    if (settings.sandbox != null) {
+      console.warn(
+        'HarnessAgent: `sandbox` is deprecated. Supply `sandboxSession` to createSession() instead.',
+      );
+    }
     const sandboxConfig = resolveSandboxConfig(settings);
     validateSandboxBootstrapSettings(sandboxConfig);
     this.settings = settings;
@@ -290,6 +298,13 @@ export class HarnessAgent<
     return this.settings.output != null;
   }
 
+  getSandboxTemplate(): Promise<HarnessSandboxTemplate | undefined> {
+    return createHarnessSandboxTemplate({
+      harnesses: [this.settings.harness],
+      sandboxConfig: this.sandboxConfig,
+    });
+  }
+
   /**
    * Start a fresh session, or resume from state previously returned by
    * `session.detach()` or `session.stop()`. The returned
@@ -540,6 +555,14 @@ export class HarnessAgent<
     }
 
     try {
+      await runSandboxBootstrap({
+        session: getRestrictedSandboxSession(sandboxSession),
+        workDir: this.sandboxConfig.workDir,
+        onBootstrap: this.sandboxConfig.onBootstrap,
+        bootstrapHash: this.sandboxConfig.bootstrapHash,
+        skipOnBootstrapIfMarked: true,
+        abortSignal,
+      });
       await ensureSandboxDirectory({
         session: sandboxSession,
         workDir: sessionWorkDir,

package/src/agent/internal/on-bootstrap-marker.ts

@@ -0,0 +1,70 @@
+import { posix } from 'node:path';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import { harnessStateDirectoryPath } from '../../v1';
+import { resolveSandboxHomeDir } from '../../utils/sandbox-home-dir';
+
+export async function onBootstrapMarkerPath({
+  session,
+  bootstrapHash,
+  abortSignal,
+}: {
+  session: SandboxSession;
+  bootstrapHash: string;
+  abortSignal?: AbortSignal;
+}): Promise<string> {
+  const digest = new Uint8Array(
+    await crypto.subtle.digest(
+      'SHA-256',
+      new TextEncoder().encode(bootstrapHash),
+    ),
+  );
+  const filename = Array.from(digest, byte =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+  return posix.join(
+    harnessStateDirectoryPath({
+      sandboxHomeDir: await resolveSandboxHomeDir({
+        sandbox: session,
+        abortSignal,
+      }),
+    }),
+    '.on-bootstrap',
+    `${filename}.ok`,
+  );
+}
+
+export async function hasOnBootstrapMarker(options: {
+  session: SandboxSession;
+  bootstrapHash: string;
+  abortSignal?: AbortSignal;
+}): Promise<boolean> {
+  return (
+    (await options.session.readTextFile({
+      path: await onBootstrapMarkerPath(options),
+      abortSignal: options.abortSignal,
+    })) !== null
+  );
+}
+
+export async function writeOnBootstrapMarker(options: {
+  session: SandboxSession;
+  bootstrapHash: string;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  const path = await onBootstrapMarkerPath(options);
+  const result = await options.session.run({
+    command: 'mkdir -p "$MARKER_DIR"',
+    env: { MARKER_DIR: posix.dirname(path) },
+    abortSignal: options.abortSignal,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to create onBootstrap marker directory: ${result.stderr || result.stdout}`,
+    );
+  }
+  await options.session.writeTextFile({
+    path,
+    content: '',
+    abortSignal: options.abortSignal,
+  });
+}

package/src/agent/internal/prepared-sandbox-identity.ts

@@ -0,0 +1,42 @@
+const PREPARED_SANDBOX_IDENTITY_VERSION = 1;
+
+export async function resolvePreparedSandboxIdentity({
+  recipeIdentities,
+  bootstrapHash,
+  workDir,
+}: {
+  readonly recipeIdentities: Record<string, string>;
+  readonly bootstrapHash?: string;
+  readonly workDir?: string;
+}): Promise<string | undefined> {
+  const entries = Object.entries(recipeIdentities).sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+  if (entries.length === 0 && bootstrapHash == null) return undefined;
+
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  const pushString = (value: string) => {
+    chunks.push(encoder.encode(value));
+    chunks.push(encoder.encode('\0'));
+  };
+  pushString(String(PREPARED_SANDBOX_IDENTITY_VERSION));
+  pushString(workDir ?? '');
+  pushString(bootstrapHash ?? '');
+  for (const [harnessId, identity] of entries) {
+    pushString(harnessId);
+    pushString(identity);
+  }
+  const buffer = new Uint8Array(
+    chunks.reduce((sum, chunk) => sum + chunk.length, 0),
+  );
+  let offset = 0;
+  for (const chunk of chunks) {
+    buffer.set(chunk, offset);
+    offset += chunk.length;
+  }
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', buffer));
+  return Array.from(digest.slice(0, 8), byte =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+}

package/src/agent/internal/run-prompt.ts

@@ -53,7 +53,11 @@ import type { HarnessAgentToolApprovalConfiguration } from '../harness-agent-set
 import { HarnessStreamTextResult } from './harness-stream-text-result';
 import { getOwn } from './get-own';
 import { translateStreamPart } from './translate-stream-part';
-import { createToolInputWorkDirStripper, stripWorkDir } from './strip-work-dir';
+import {
+  createToolInputWorkDirStripper,
+  stripParsedToolInputWorkDir,
+  stripWorkDir,
+} from './strip-work-dir';
 import {
   createTurnLifecycle,
   type HarnessAgentLifecycleCallbacks,
@@ -63,6 +67,8 @@ import { resolveCustomToolApproval } from './permission-mode';
 import { logBridgeError } from '../../utils/bridge-diagnostics';
 import { pinSandboxChannelEventCheckpoint } from '../../utils/sandbox-channel';
 
+const invalidToolInputMessage = 'Tool input validation failed.';
+
 function unwrapToolResultOutput(toolResult: ToolResultPart): {
   output: unknown;
   isError?: boolean;
@@ -647,7 +653,9 @@ export function runPrompt<
       continuation: ToolApprovalResponse,
     ): Promise<'continued' | 'awaiting-tool-result'> => {
       const rawToolCall =
-        rawToolCallsByToolCallId.get(approval.toolCallId) ??
+        (approval.kind === 'builtin'
+          ? rawToolCallsByToolCallId.get(approval.toolCallId)
+          : undefined) ??
         ({
           type: 'tool-call',
           toolCallId: approval.toolCallId,
@@ -656,16 +664,31 @@ export function runPrompt<
           providerExecuted: approval.providerExecuted,
           nativeName: approval.nativeName,
         } satisfies Extract<HarnessV1StreamPart, { type: 'tool-call' }>);
-      const parsedInput = await safeParseJSON({ text: rawToolCall.input });
-      const toolCall: ToolCallTextStreamPart = {
-        type: 'tool-call',
-        toolCallId: rawToolCall.toolCallId,
-        toolName: rawToolCall.toolName,
-        input: parsedInput.success ? parsedInput.value : rawToolCall.input,
-        ...(rawToolCall.providerExecuted !== undefined
-          ? { providerExecuted: rawToolCall.providerExecuted }
-          : {}),
-      };
+      let validatedToolCall: ToolCallTextStreamPart | undefined;
+      let toolCall: ToolCallTextStreamPart;
+      if (approval.kind === 'custom' && continuation.approved) {
+        validatedToolCall = asToolCallTextStreamPart({
+          part: await validateToolCall({
+            event: rawToolCall,
+            tools: input.tools,
+          }),
+        });
+        toolCall = displayHostToolCall({
+          toolCall: validatedToolCall,
+          sessionWorkDir: input.sessionWorkDir,
+        });
+      } else {
+        const parsedInput = await safeParseJSON({ text: rawToolCall.input });
+        toolCall = {
+          type: 'tool-call',
+          toolCallId: rawToolCall.toolCallId,
+          toolName: rawToolCall.toolName,
+          input: parsedInput.success ? parsedInput.value : rawToolCall.input,
+          ...(rawToolCall.providerExecuted !== undefined
+            ? { providerExecuted: rawToolCall.providerExecuted }
+            : {}),
+        };
+      }
 
       enqueueApprovalResponse(approval, continuation, toolCall);
       onToolApprovalSettled(approval.approvalId);
@@ -699,6 +722,29 @@ export function runPrompt<
         return 'continued';
       }
 
+      if (validatedToolCall == null) {
+        throw new Error(
+          `Harness '${input.harness.harnessId}' could not validate approved host tool '${approval.toolName}'.`,
+        );
+      }
+
+      if (validatedToolCall.invalid) {
+        const error = new Error(invalidToolInputMessage);
+        await submitToolResult({
+          toolCallId: approval.toolCallId,
+          output: { error: invalidToolInputMessage },
+          isError: true,
+        });
+        bufferedToolOutcomes.push(() => {
+          enqueueHostToolOutcome({
+            toolCall,
+            outcome: { ok: false, error },
+          });
+        });
+        await publishToolExecutions();
+        return 'continued';
+      }
+
       await lifecycle.start(input.model);
       toolExecutions.set(rawToolCall.toolCallId, {
         toolCall: toolCall as TypedToolCall<TOOLS>,
@@ -706,6 +752,7 @@ export function runPrompt<
       const executionStartedAt = Date.now();
       const execution = await maybeExecuteHostTool({
         event: rawToolCall,
+        parsedToolCall: validatedToolCall,
         tools: activeTools,
         toolsContext,
         wrappedExecuteTool: lifecycle.executeTool,
@@ -886,7 +933,6 @@ export function runPrompt<
         if (settledHostInputReplay || settledBuiltinApprovalReplay) {
           continue;
         }
-
         if (displayValue.type === 'finish-step' && closingResumedStep) {
           closingResumedStep = false;
           await publishToolExecutions();
@@ -971,15 +1017,34 @@ export function runPrompt<
 
         // Tool-call validation lives here (not in translateStreamPart) because
         // schema parsing is async and needs the merged tool set in scope.
+        let validatedHostToolCall: ToolCallTextStreamPart | undefined;
         if (displayValue.type === 'tool-call') {
+          const isHostTool =
+            value.type === 'tool-call' &&
+            !value.providerExecuted &&
+            hasTool({ tools: activeTools, toolName: value.toolName }) &&
+            !(
+              value.toolName === 'askUserQuestions' &&
+              hasTool({
+                tools: input.harness.builtinTools,
+                toolName: value.toolName,
+              })
+            );
           const parsed = await validateToolCall<TOOLS>({
-            event: displayValue,
+            event: isHostTool ? value : displayValue,
             tools: input.tools,
           });
           const parsedToolCall = asToolCallTextStreamPart({ part: parsed });
+          validatedHostToolCall = isHostTool ? parsedToolCall : undefined;
+          const displayToolCall = isHostTool
+            ? displayHostToolCall({
+                toolCall: parsedToolCall,
+                sessionWorkDir: input.sessionWorkDir,
+              })
+            : parsedToolCall;
           rawToolCallsByToolCallId.set(displayValue.toolCallId, displayValue);
-          toolCallsByToolCallId.set(displayValue.toolCallId, parsedToolCall);
-          result.enqueue(parsed);
+          toolCallsByToolCallId.set(displayValue.toolCallId, displayToolCall);
+          result.enqueue(displayToolCall as TextStreamPart<TOOLS>);
         }
 
         if (value.type === 'text-delta') {
@@ -1155,6 +1220,31 @@ export function runPrompt<
             await finishForHostInputPause({ completeCurrentStep: true });
             return;
           }
+          if (validatedHostToolCall == null) {
+            throw new Error(
+              `Harness '${input.harness.harnessId}' could not validate host tool '${toolCall.toolName}'.`,
+            );
+          }
+          if (validatedHostToolCall.invalid) {
+            settledHostToolCallIds.add(toolCall.toolCallId);
+            toolExecutions.delete(toolCall.toolCallId);
+            bufferedToolOutcomes.push(() => {
+              result.enqueue({
+                type: 'tool-error',
+                toolCallId: toolCall.toolCallId,
+                toolName: toolCall.toolName,
+                input: parsedToolCall.input,
+                error: new Error(invalidToolInputMessage),
+                dynamic: true,
+              } as TextStreamPart<TOOLS>);
+            });
+            await submitToolResult({
+              toolCallId: toolCall.toolCallId,
+              output: { error: invalidToolInputMessage },
+              isError: true,
+            });
+            continue;
+          }
           const customToolApprovalDecision = resolveCustomToolApproval({
             toolName: toolCall.toolName,
             toolApproval: input.toolApproval,
@@ -1266,6 +1356,7 @@ export function runPrompt<
               const executionStartedAt = Date.now();
               const execution = await maybeExecuteHostTool({
                 event: toolCall,
+                parsedToolCall: validatedHostToolCall,
                 tools: activeTools,
                 toolsContext,
                 wrappedExecuteTool: lifecycle.executeTool,
@@ -1414,6 +1505,22 @@ function asToolCallTextStreamPart<TOOLS extends ToolSet>(input: {
   return input.part as ToolCallTextStreamPart;
 }
 
+function displayHostToolCall(input: {
+  toolCall: ToolCallTextStreamPart;
+  sessionWorkDir: string;
+}): ToolCallTextStreamPart {
+  return {
+    ...input.toolCall,
+    input: stripParsedToolInputWorkDir({
+      value: input.toolCall.input,
+      sessionWorkDir: input.sessionWorkDir,
+    }),
+    ...(input.toolCall.invalid
+      ? { error: new Error(invalidToolInputMessage) }
+      : {}),
+  };
+}
+
 type ToolCallTextStreamPart = {
   readonly type: 'tool-call';
   readonly toolCallId: string;
@@ -1433,6 +1540,7 @@ function hasTool(input: { tools: ToolSet; toolName: string }): boolean {
 
 async function maybeExecuteHostTool<TOOLS extends ToolSet>(input: {
   event: { toolCallId: string; toolName: string; input: string };
+  parsedToolCall: ToolCallTextStreamPart;
   tools: TOOLS;
   toolsContext: InferToolSetContext<TOOLS>;
   wrappedExecuteTool: TurnLifecycle<ToolSet, Context>['executeTool'];
@@ -1450,8 +1558,15 @@ async function maybeExecuteHostTool<TOOLS extends ToolSet>(input: {
 
   if (!isExecutableTool(tool)) return { executed: false };
 
-  const parsed = await safeParseJSON({ text: input.event.input });
-  const args = parsed.success ? parsed.value : input.event.input;
+  if (input.parsedToolCall.invalid) {
+    const error = new Error(invalidToolInputMessage);
+    await input.submitToolResult({
+      toolCallId: input.event.toolCallId,
+      output: { error: invalidToolInputMessage },
+      isError: true,
+    });
+    return { executed: true, outcome: { ok: false, error } };
+  }
 
   let context: unknown;
   try {
@@ -1489,7 +1604,7 @@ async function maybeExecuteHostTool<TOOLS extends ToolSet>(input: {
         let output: unknown;
         const stream = executeTool({
           tool,
-          input: args as never,
+          input: input.parsedToolCall.input as never,
           options: {
             toolCallId: input.event.toolCallId,
             messages: [],

package/src/agent/internal/sandbox-bootstrap.ts

@@ -6,6 +6,10 @@ import { resolveSandboxDefaultWorkingDirectory } from '../../utils/resolve-sandb
 import { resolveSandboxHomeDir } from '../../utils/sandbox-home-dir';
 import type { HarnessAgentSandboxConfig } from '../harness-agent-settings';
 import { applyBootstrapRecipe, hashHarnessBootstrap } from './bootstrap-recipe';
+import {
+  hasOnBootstrapMarker,
+  writeOnBootstrapMarker,
+} from './on-bootstrap-marker';
 
 const SANDBOX_BOOTSTRAP_IDENTITY_VERSION = 1;
 
@@ -125,6 +129,7 @@ export async function createSandboxBootstrapPlan({
               recipeIdentity,
               workDir,
               onBootstrap: settings.onBootstrap,
+              bootstrapHash: settings.bootstrapHash,
               abortSignal: opts.abortSignal,
             }),
         }
@@ -138,6 +143,8 @@ export async function runSandboxBootstrap({
   recipeIdentity,
   workDir,
   onBootstrap,
+  bootstrapHash,
+  skipOnBootstrapIfMarked = false,
   defaultWorkingDirectory,
   abortSignal,
 }: {
@@ -146,6 +153,8 @@ export async function runSandboxBootstrap({
   readonly recipeIdentity?: string;
   readonly workDir?: string;
   readonly onBootstrap?: SandboxBootstrapSettings['onBootstrap'];
+  readonly bootstrapHash?: string;
+  readonly skipOnBootstrapIfMarked?: boolean;
   readonly defaultWorkingDirectory?: string;
   readonly abortSignal?: AbortSignal;
 }): Promise<void> {
@@ -173,6 +182,13 @@ export async function runSandboxBootstrap({
 
   if (onBootstrap == null) return;
 
+  if (
+    skipOnBootstrapIfMarked &&
+    bootstrapHash != null &&
+    (await hasOnBootstrapMarker({ session, bootstrapHash, abortSignal }))
+  )
+    return;
+
   const resolvedDefaultWorkingDirectory =
     defaultWorkingDirectory ??
     (await resolveSandboxDefaultWorkingDirectory({
@@ -194,6 +210,9 @@ export async function runSandboxBootstrap({
     abortSignal,
   });
   await onBootstrap({ session, workDir: bootstrapWorkDir, abortSignal });
+  if (bootstrapHash != null) {
+    await writeOnBootstrapMarker({ session, bootstrapHash, abortSignal });
+  }
 }
 
 export async function ensureSandboxDirectory({

package/src/agent/internal/strip-work-dir.ts

@@ -120,6 +120,63 @@ export function stripWorkDir(
   }
 }
 
+export function stripParsedToolInputWorkDir({
+  value,
+  sessionWorkDir,
+}: {
+  value: unknown;
+  sessionWorkDir: string;
+}): unknown {
+  if (sessionWorkDir.length === 0) return value;
+
+  const projected = new WeakMap<object, unknown>();
+  const pending: Array<{
+    source: object;
+    target: Record<string, unknown> | unknown[];
+  }> = [];
+
+  const project = (item: unknown): unknown => {
+    if (typeof item === 'string') return stripString(item, sessionWorkDir);
+    if (item === null || typeof item !== 'object') return item;
+    if (
+      !Array.isArray(item) &&
+      Object.getPrototypeOf(item) !== Object.prototype &&
+      Object.getPrototypeOf(item) !== null
+    ) {
+      return item;
+    }
+    if (projected.has(item)) return projected.get(item);
+
+    const target: Record<string, unknown> | unknown[] = Array.isArray(item)
+      ? new Array(item.length)
+      : {};
+    projected.set(item, target);
+    pending.push({ source: item, target });
+    return target;
+  };
+
+  const result = project(value);
+  while (pending.length > 0) {
+    const { source, target } = pending.pop()!;
+    if (Array.isArray(source) && Array.isArray(target)) {
+      for (let index = 0; index < source.length; index++) {
+        if (index in source) target[index] = project(source[index]);
+      }
+    } else {
+      for (const [key, item] of Object.entries(source)) {
+        Object.defineProperty(target, key, {
+          value: project(item),
+          enumerable: true,
+          writable: true,
+          configurable: true,
+        });
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * Replace occurrences of the working directory in a string. A reference to the
  * directory followed by a separator becomes workspace-relative