@ai-sdk/harness 1.0.51 → 1.0.53

package/dist/index.d.ts

@@ -6,7 +6,9 @@ import { JSONValue, LanguageModelV4ToolCall, LanguageModelV4ToolApprovalRequest,
 
 /**
  * One file to write into the sandbox as part of an adapter's bootstrap recipe.
- * Paths should live under {@link HarnessV1Bootstrap.bootstrapDir}.
+ * Absolute paths are used as-is. Relative paths are resolved against the
+ * sandbox's default working directory. Paths should live under
+ * {@link HarnessV1Bootstrap.bootstrapDir}.
  */
 interface HarnessV1BootstrapFile {
     readonly path: string;
@@ -19,6 +21,11 @@ interface HarnessV1BootstrapFile {
  */
 interface HarnessV1BootstrapCommand {
     readonly command: string;
+    /**
+     * Absolute working directories are used as-is. Relative working directories
+     * are resolved against the sandbox's default working directory. When
+     * omitted, the command runs from the recipe's bootstrap directory.
+     */
     readonly workingDirectory?: string;
 }
 /**
@@ -34,15 +41,16 @@ interface HarnessV1Bootstrap {
      */
     readonly harnessId: string;
     /**
-     * Absolute path inside the sandbox where this recipe writes its state.
-     * The marker file lives directly under it. Files declared in {@link files}
-     * should also use this prefix so an adapter upgrade can sweep stale state
-     * by clearing the directory.
+     * Path inside the sandbox where this recipe writes its state. Absolute paths
+     * are used as-is. Relative paths are resolved against the sandbox's default
+     * working directory. The marker file lives directly under it. Files
+     * declared in {@link files} should also use this prefix so an adapter upgrade
+     * can sweep stale state by clearing the directory.
      */
     readonly bootstrapDir: string;
     /** Files to write into the sandbox before any command runs. */
     readonly files: ReadonlyArray<HarnessV1BootstrapFile>;
-    /** Commands to run after files are written, in order. */
+    /** Commands to run from the bootstrap directory after files are written. */
     readonly commands: ReadonlyArray<HarnessV1BootstrapCommand>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.51",
+  "version": "1.0.53",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -45,8 +45,8 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.4",
-    "@ai-sdk/provider-utils": "5.0.17",
-    "ai": "7.0.45"
+    "@ai-sdk/provider-utils": "5.0.18",
+    "ai": "7.0.47"
   },
   "peerDependencies": {
     "ws": "^8.21.0",
@@ -65,7 +65,7 @@
     "typescript": "5.8.3",
     "ws": "^8.21.0",
     "zod": "3.25.76",
-    "@ai-sdk/otel": "1.0.45",
+    "@ai-sdk/otel": "1.0.47",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "engines": {

package/src/agent/harness-agent.ts

@@ -310,12 +310,13 @@ export class HarnessAgent<
         sandboxBootstrapPlan.recipe != null &&
         sandboxBootstrapPlan.recipeIdentity != null
       ) {
-        await applyBootstrapRecipe(
-          sandboxSession.restricted(),
-          sandboxBootstrapPlan.recipe,
-          sandboxBootstrapPlan.recipeIdentity,
-          { abortSignal },
-        );
+        await applyBootstrapRecipe({
+          session: sandboxSession.restricted(),
+          recipe: sandboxBootstrapPlan.recipe,
+          identity: sandboxBootstrapPlan.recipeIdentity,
+          defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+          abortSignal,
+        });
       }
       await ensureSandboxDirectory({
         session: sandboxSession,

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

@@ -1,3 +1,4 @@
+import { posix } from 'node:path';
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 import type { HarnessV1Bootstrap } from '../../v1';
 
@@ -59,55 +60,102 @@ export async function hashHarnessBootstrap(
 
 /**
  * Absolute path of the marker file the framework writes after a recipe runs
- * successfully. Presence of this path inside the sandbox indicates the
- * recipe with the matching `identity` has already been applied.
+ * successfully. Presence of this path inside the sandbox indicates the recipe
+ * with the matching `identity` has already been applied.
  */
-export function bootstrapMarkerPath(
-  recipe: HarnessV1Bootstrap,
-  identity: string,
-): string {
-  return `${recipe.bootstrapDir}/.bootstrap-${identity}.ok`;
+export function bootstrapMarkerPath({
+  recipe,
+  identity,
+  defaultWorkingDirectory,
+}: {
+  recipe: HarnessV1Bootstrap;
+  identity: string;
+  defaultWorkingDirectory: string;
+}): string {
+  return posix.join(
+    resolveBootstrapPath({
+      path: recipe.bootstrapDir,
+      defaultWorkingDirectory,
+    }),
+    `.bootstrap-${identity}.ok`,
+  );
 }
 
 /**
  * Apply a bootstrap recipe to a sandbox session idempotently. Reads the
- * marker file; if it exists, returns immediately. Otherwise writes the
- * recipe's files, runs its commands sequentially, and writes the marker
- * on success.
+ * marker file; if it exists, returns immediately. Otherwise creates the
+ * bootstrap directory, writes the recipe's files, runs its commands
+ * sequentially, and writes the marker on success.
  *
  * Safe to call multiple times. For sandboxes that already contain the
  * recipe (resumed from snapshot, reused across sessions, or applied by
  * an earlier process) this is a single fast read.
  */
-export async function applyBootstrapRecipe(
-  session: SandboxSession,
-  recipe: HarnessV1Bootstrap,
-  identity: string,
-  options?: { abortSignal?: AbortSignal },
-): Promise<void> {
-  const markerPath = bootstrapMarkerPath(recipe, identity);
+export async function applyBootstrapRecipe({
+  session,
+  recipe,
+  identity,
+  defaultWorkingDirectory,
+  abortSignal,
+}: {
+  session: SandboxSession;
+  recipe: HarnessV1Bootstrap;
+  identity: string;
+  defaultWorkingDirectory: string;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  const markerPath = bootstrapMarkerPath({
+    recipe,
+    identity,
+    defaultWorkingDirectory,
+  });
 
   const existingMarker = await session.readTextFile({
     path: markerPath,
-    abortSignal: options?.abortSignal,
+    abortSignal,
   });
   if (existingMarker !== null) {
     return;
   }
 
+  const bootstrapDir = resolveBootstrapPath({
+    path: recipe.bootstrapDir,
+    defaultWorkingDirectory,
+  });
+  const mkdirResult = await session.run({
+    command: 'mkdir -p "$BOOTSTRAP_DIR"',
+    workingDirectory: defaultWorkingDirectory,
+    env: { BOOTSTRAP_DIR: bootstrapDir },
+    abortSignal,
+  });
+  if (mkdirResult.exitCode !== 0) {
+    throw new Error(
+      `Failed to create bootstrap directory for harness '${recipe.harnessId}' (exit ${mkdirResult.exitCode}): ${bootstrapDir}\n${mkdirResult.stderr || mkdirResult.stdout}`,
+    );
+  }
+
   for (const file of recipe.files) {
     await session.writeTextFile({
-      path: file.path,
+      path: resolveBootstrapPath({
+        path: file.path,
+        defaultWorkingDirectory,
+      }),
       content: file.content,
-      abortSignal: options?.abortSignal,
+      abortSignal,
     });
   }
 
   for (const cmd of recipe.commands) {
     const result = await session.run({
       command: cmd.command,
-      workingDirectory: cmd.workingDirectory,
-      abortSignal: options?.abortSignal,
+      workingDirectory:
+        cmd.workingDirectory == null
+          ? bootstrapDir
+          : resolveBootstrapPath({
+              path: cmd.workingDirectory,
+              defaultWorkingDirectory,
+            }),
+      abortSignal,
     });
     if (result.exitCode !== 0) {
       throw new Error(
@@ -119,6 +167,18 @@ export async function applyBootstrapRecipe(
   await session.writeTextFile({
     path: markerPath,
     content: '',
-    abortSignal: options?.abortSignal,
+    abortSignal,
   });
 }
+
+function resolveBootstrapPath({
+  path,
+  defaultWorkingDirectory,
+}: {
+  path: string;
+  defaultWorkingDirectory: string;
+}): string {
+  return posix.isAbsolute(path)
+    ? path
+    : posix.resolve(defaultWorkingDirectory, path);
+}

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

@@ -133,6 +133,7 @@ export async function runSandboxBootstrap({
   recipeIdentity,
   workDir,
   onBootstrap,
+  defaultWorkingDirectory,
   abortSignal,
 }: {
   readonly session: SandboxSession;
@@ -140,25 +141,35 @@ export async function runSandboxBootstrap({
   readonly recipeIdentity?: string;
   readonly workDir?: string;
   readonly onBootstrap?: SandboxBootstrapSettings['onBootstrap'];
+  readonly defaultWorkingDirectory?: string;
   readonly abortSignal?: AbortSignal;
 }): Promise<void> {
+  if (recipe == null && onBootstrap == null) return;
+
+  const resolvedDefaultWorkingDirectory =
+    defaultWorkingDirectory ??
+    (await resolveDefaultWorkingDirectory({
+      session,
+      abortSignal,
+    }));
+
   if (recipe != null && recipeIdentity != null) {
-    await applyBootstrapRecipe(session, recipe, recipeIdentity, {
+    await applyBootstrapRecipe({
+      session,
+      recipe,
+      identity: recipeIdentity,
+      defaultWorkingDirectory: resolvedDefaultWorkingDirectory,
       abortSignal,
     });
   }
 
   if (onBootstrap == null) return;
 
-  const defaultWorkingDirectory = await resolveDefaultWorkingDirectory({
-    session,
-    abortSignal,
-  });
   const bootstrapWorkDir =
     workDir == null
-      ? defaultWorkingDirectory
+      ? resolvedDefaultWorkingDirectory
       : joinSandboxPath({
-          base: defaultWorkingDirectory,
+          base: resolvedDefaultWorkingDirectory,
           path: workDir,
         });
 

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

@@ -50,14 +50,13 @@ export async function prepareHarnessSandboxTemplate(options: {
 
   try {
     if (bootstrapPlan.recipe != null && bootstrapPlan.recipeIdentity != null) {
-      await applyBootstrapRecipe(
-        sandboxSession.restricted(),
-        bootstrapPlan.recipe,
-        bootstrapPlan.recipeIdentity,
-        {
-          abortSignal: options.abortSignal,
-        },
-      );
+      await applyBootstrapRecipe({
+        session: sandboxSession.restricted(),
+        recipe: bootstrapPlan.recipe,
+        identity: bootstrapPlan.recipeIdentity,
+        defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+        abortSignal: options.abortSignal,
+      });
     }
   } finally {
     await Promise.resolve(sandboxSession.stop()).catch(() => {});

package/src/agent/prepare-sandbox-for-harness.ts

@@ -7,6 +7,7 @@ import {
 } from './internal/bootstrap-recipe';
 import {
   normalizeSandboxWorkDir,
+  resolveDefaultWorkingDirectory,
   runSandboxBootstrap,
   validateSandboxBootstrapSettings,
 } from './internal/sandbox-bootstrap';
@@ -62,6 +63,7 @@ export async function prepareSandboxForHarness(options: {
       : normalizeSandboxWorkDir(sandboxConfig.workDir);
   const recipeIdentities: Record<string, string> = {};
   const skippedHarnessIds: string[] = [];
+  let defaultWorkingDirectory: string | undefined;
 
   for (const harness of harnesses) {
     const recipe = await harness.getBootstrap?.({
@@ -74,7 +76,15 @@ export async function prepareSandboxForHarness(options: {
 
     const recipeIdentity = await hashHarnessBootstrap(recipe);
     recipeIdentities[harness.harnessId] = recipeIdentity;
-    await applyBootstrapRecipe(options.session, recipe, recipeIdentity, {
+    defaultWorkingDirectory ??= await resolveDefaultWorkingDirectory({
+      session: options.session,
+      abortSignal: options.abortSignal,
+    });
+    await applyBootstrapRecipe({
+      session: options.session,
+      recipe,
+      identity: recipeIdentity,
+      defaultWorkingDirectory,
       abortSignal: options.abortSignal,
     });
   }
@@ -84,6 +94,7 @@ export async function prepareSandboxForHarness(options: {
       session: options.session,
       workDir,
       onBootstrap: sandboxConfig.onBootstrap,
+      defaultWorkingDirectory,
       abortSignal: options.abortSignal,
     });
   }

package/src/v1/harness-v1-bootstrap.ts

@@ -1,6 +1,8 @@
 /**
  * One file to write into the sandbox as part of an adapter's bootstrap recipe.
- * Paths should live under {@link HarnessV1Bootstrap.bootstrapDir}.
+ * Absolute paths are used as-is. Relative paths are resolved against the
+ * sandbox's default working directory. Paths should live under
+ * {@link HarnessV1Bootstrap.bootstrapDir}.
  */
 export interface HarnessV1BootstrapFile {
   readonly path: string;
@@ -14,6 +16,11 @@ export interface HarnessV1BootstrapFile {
  */
 export interface HarnessV1BootstrapCommand {
   readonly command: string;
+  /**
+   * Absolute working directories are used as-is. Relative working directories
+   * are resolved against the sandbox's default working directory. When
+   * omitted, the command runs from the recipe's bootstrap directory.
+   */
   readonly workingDirectory?: string;
 }
 
@@ -31,16 +38,17 @@ export interface HarnessV1Bootstrap {
   readonly harnessId: string;
 
   /**
-   * Absolute path inside the sandbox where this recipe writes its state.
-   * The marker file lives directly under it. Files declared in {@link files}
-   * should also use this prefix so an adapter upgrade can sweep stale state
-   * by clearing the directory.
+   * Path inside the sandbox where this recipe writes its state. Absolute paths
+   * are used as-is. Relative paths are resolved against the sandbox's default
+   * working directory. The marker file lives directly under it. Files
+   * declared in {@link files} should also use this prefix so an adapter upgrade
+   * can sweep stale state by clearing the directory.
    */
   readonly bootstrapDir: string;
 
   /** Files to write into the sandbox before any command runs. */
   readonly files: ReadonlyArray<HarnessV1BootstrapFile>;
 
-  /** Commands to run after files are written, in order. */
+  /** Commands to run from the bootstrap directory after files are written. */
   readonly commands: ReadonlyArray<HarnessV1BootstrapCommand>;
 }