@ai-sdk/harness 1.0.0-beta.24 → 1.0.0-beta.26

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ai-sdk/harness
 
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- a83a367: feat(harness): allow pre-snapshot `sandboxConfig.onBootstrap` callback in `HarnessAgent`
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- ai@7.0.0-beta.186
+
 ## 1.0.0-beta.24
 
 ### Patch Changes

package/README.md

@@ -27,12 +27,25 @@ const agent = new HarnessAgent({
     runtime: 'node24',
     ports: [4000],
   }),
-  onSandboxSession: async ({ session, sessionWorkDir, abortSignal }) => {
-    await session.writeTextFile({
-      path: `${sessionWorkDir}/README.md`,
-      content: 'Workspace notes for this session.',
-      abortSignal,
-    });
+  sandboxConfig: {
+    bootstrapHash: 'ripgrep-v1',
+    onBootstrap: async ({ session, abortSignal }) => {
+      const result = await session.run({
+        command:
+          'command -v rg >/dev/null || (apt-get update && apt-get install -y ripgrep)',
+        abortSignal,
+      });
+      if (result.exitCode !== 0) {
+        throw new Error(`Failed to install ripgrep: ${result.stderr}`);
+      }
+    },
+    onSession: async ({ session, sessionWorkDir, abortSignal }) => {
+      await session.writeTextFile({
+        path: `${sessionWorkDir}/README.md`,
+        content: 'Workspace notes for this session.',
+        abortSignal,
+      });
+    },
   },
   tools: {
     deploy: tool({
@@ -70,18 +83,17 @@ try {
 }
 ```
 
-`sandbox` is a required `HarnessV1SandboxProvider` — the agent calls `provider.createSession()` when a session starts. Use `onSandboxSession` to prepare the acquired sandbox before the harness adapter starts. The hook runs for fresh and resumed sessions, so keep it idempotent. Use `session.detach()` to park a bridge-backed session for later attach, `session.stop()` to save state and stop the sandbox, or `session.destroy()` to clean up without keeping resume state. Bridge-backed adapters (claude-code, codex) require a provider that exposes ports — `@ai-sdk/sandbox-vercel` is the supported choice today. `@ai-sdk/sandbox-just-bash` is suitable only for non-bridge flows.
+Use `session.detach()` to park a bridge-backed session for later attach, `session.stop()` to save state and stop the sandbox, or `session.destroy()` to clean up without keeping resume state. Bridge-backed adapters (claude-code, codex) require a sandbox provider that exposes ports — `@ai-sdk/sandbox-vercel` is the supported choice today. `@ai-sdk/sandbox-just-bash` is suitable only for non-bridge flows.
+
+`sandbox` is a required `HarnessV1SandboxProvider` — the agent calls `provider.createSession()` when a session starts. Use `sandboxConfig` for agent specific sandbox configuration that works independently from the sandbox provider that is used:
+
+- Use `sandboxConfig.onSession` to prepare the acquired sandbox before the harness adapter starts. The hook runs for fresh and resumed sessions, so keep it idempotent.
+- Use `sandboxConfig.onBootstrap` for expensive sandbox setup that should be baked into a reusable snapshot, such as installing tools or cloning a large repository. Provide `sandboxConfig.bootstrapHash` with it and change that value whenever the bootstrap output should invalidate the cached snapshot.
+- Use `sandboxConfig.workDir` to set a stable working directory for the agent, relative to the sandbox's default working directory; otherwise regular sessions use the existing `<harnessId>-<sessionId>` directory. In that case, the `onBootstrap` callback receives the sandbox's default working directory.
 
 ### Available harnesses
 
-- `@ai-sdk/harness-claude-code`
-- `@ai-sdk/harness-codex`
-- `@ai-sdk/harness-opencode` (WIP)
-- `@ai-sdk/harness-goose` (WIP)
-- `@ai-sdk/harness-mastra` (WIP)
-- `@ai-sdk/harness-deepagents` (WIP)
-- `@ai-sdk/harness-openai-agents` (WIP)
-- `@ai-sdk/harness-pi` (WIP)
+See the [harness adapters documentation](https://ai-sdk.dev/v7/docs/ai-sdk-harnesses/harness-adapters).
 
 ## Implementing a harness
 

package/dist/agent/index.d.ts

@@ -1039,6 +1039,44 @@ type HarnessAgentSkill = HarnessV1Skill;
 type HarnessAgentPermissionMode = HarnessV1PermissionMode;
 
 type HarnessAgentToolApprovalConfiguration = Readonly<Record<string, ToolApprovalStatus>>;
+type HarnessAgentSandboxConfig = {
+    /**
+     * Optional fixed working directory for all sessions, relative to the
+     * sandbox's default working directory. When omitted, sessions keep the
+     * existing `<harnessId>-<sessionId>` work directory.
+     */
+    readonly workDir?: string;
+    /**
+     * Caller-controlled identity for `onBootstrap`. Change this whenever the
+     * bootstrap side effects should invalidate the reusable sandbox snapshot.
+     */
+    readonly bootstrapHash?: string;
+    /**
+     * Called during sandbox template creation after the harness adapter's own
+     * bootstrap has run and before snapshot-capable providers publish a snapshot.
+     *
+     * `bootstrapHash` must be provided with this callback.
+     */
+    readonly onBootstrap?: (opts: {
+        readonly session: Experimental_SandboxSession;
+        readonly workDir: string;
+        readonly abortSignal?: AbortSignal;
+    }) => Promise<void>;
+    /**
+     * Called after each sandbox session is acquired and the session work
+     * directory exists, before the harness adapter starts. Runs for fresh and
+     * resumed sessions.
+     *
+     * Use this to write per-session config, install lightweight tools, activate
+     * licenses, or prepare files in `sessionWorkDir`. Keep it idempotent if the
+     * agent may resume sessions.
+     */
+    readonly onSession?: (opts: {
+        readonly session: Experimental_SandboxSession;
+        readonly sessionWorkDir: string;
+        readonly abortSignal?: AbortSignal;
+    }) => Promise<void>;
+};
 /**
  * Construction-time settings for a `HarnessAgent`.
  *
@@ -1102,19 +1140,11 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
      */
     readonly sandbox: HarnessV1SandboxProvider;
     /**
-     * Called after each sandbox session is acquired and the session work
-     * directory exists, before the harness adapter starts. Runs for fresh and
-     * resumed sessions.
-     *
-     * Use this to write per-session config, install lightweight tools, activate
-     * licenses, or prepare files in `sessionWorkDir`. Keep it idempotent if the
-     * agent may resume sessions.
+     * Sandbox working-directory and lifecycle hook configuration.
      */
-    readonly onSandboxSession?: (opts: {
-        readonly session: Experimental_SandboxSession;
-        readonly sessionWorkDir: string;
-        readonly abortSignal?: AbortSignal;
-    }) => Promise<void>;
+    readonly sandboxConfig?: HarnessAgentSandboxConfig;
+    /** @deprecated Use `sandboxConfig.onSession` instead. */
+    readonly onSandboxSession?: HarnessAgentSandboxConfig['onSession'];
     /**
      * Telemetry configuration. The harness drives AI SDK's pluggable
      * `Telemetry` integration contract from the turn lifecycle, so a harness turn
@@ -1356,6 +1386,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
      */
     readonly tools: HarnessAllTools<THarness, TUserTools>;
     private readonly settings;
+    private readonly sandboxConfig;
     private readonly userTools;
     private readonly permissionMode;
     constructor(settings: HarnessAgentSettings<THarness, TUserTools>);
@@ -1423,6 +1454,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
     private _toGenerateResult;
 }
 
+type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
 /**
  * Pre-build a harness's sandbox template without running an agent. Idempotent:
  * if the template already exists (snapshot present, or marker on a non-snapshot
@@ -1440,6 +1472,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
 declare function prewarmHarness(options: {
     readonly harness: HarnessAgentAdapter;
     readonly sandboxProvider: HarnessV1SandboxProvider;
+    readonly sandboxConfig?: SandboxBootstrapSettings;
     readonly abortSignal?: AbortSignal;
 }): Promise<void>;
 

package/dist/agent/index.js

@@ -2132,7 +2132,7 @@ function collectHarnessAgentToolApprovalContinuations(input) {
 
 // src/agent/internal/bootstrap-recipe.ts
 var BOOTSTRAP_SCHEMA_VERSION = 1;
-async function hashBootstrap(recipe) {
+async function hashHarnessBootstrap(recipe) {
   const encoder = new TextEncoder();
   const chunks = [];
   const pushString = (value) => {
@@ -2204,6 +2204,188 @@ ${result.stderr || result.stdout}`
   });
 }
 
+// src/agent/internal/sandbox-bootstrap.ts
+import { posix } from "path";
+var SANDBOX_BOOTSTRAP_IDENTITY_VERSION = 1;
+function validateSandboxBootstrapSettings(settings) {
+  if (settings.onBootstrap == null !== (settings.bootstrapHash == null)) {
+    throw new Error(
+      "HarnessAgent: `sandboxConfig.onBootstrap` and `sandboxConfig.bootstrapHash` must be provided together."
+    );
+  }
+  if (settings.workDir != null) {
+    normalizeSandboxWorkDir(settings.workDir);
+  }
+}
+function normalizeSandboxWorkDir(workDir) {
+  if (workDir.length === 0) {
+    throw new Error("HarnessAgent: `sandboxConfig.workDir` must not be empty.");
+  }
+  if (workDir.includes("\0")) {
+    throw new Error(
+      "HarnessAgent: `sandboxConfig.workDir` must not contain NUL."
+    );
+  }
+  if (workDir.includes("\\")) {
+    throw new Error(
+      "HarnessAgent: `sandboxConfig.workDir` must use POSIX path separators."
+    );
+  }
+  if (posix.isAbsolute(workDir)) {
+    throw new Error("HarnessAgent: `sandboxConfig.workDir` must be relative.");
+  }
+  const normalized = posix.normalize(workDir);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new Error(
+      "HarnessAgent: `sandboxConfig.workDir` must stay inside the sandbox default working directory."
+    );
+  }
+  return normalized;
+}
+function resolveSessionWorkDir({
+  defaultWorkingDirectory,
+  harnessId,
+  sessionId,
+  workDir
+}) {
+  return joinSandboxPath({
+    base: defaultWorkingDirectory,
+    path: workDir != null ? workDir : `${harnessId}-${sessionId}`
+  });
+}
+async function createSandboxBootstrapPlan({
+  recipe,
+  settings
+}) {
+  const workDir = settings.workDir == null ? void 0 : normalizeSandboxWorkDir(settings.workDir);
+  const recipeIdentity = recipe == null ? void 0 : await hashHarnessBootstrap(recipe);
+  const hasCallerBootstrap = settings.onBootstrap != null;
+  const needsCombinedIdentity = hasCallerBootstrap || recipeIdentity != null && workDir != null;
+  const identity = needsCombinedIdentity && (recipeIdentity != null || hasCallerBootstrap) ? await hashSandboxBootstrapIdentity({
+    recipeIdentity,
+    bootstrapHash: settings.bootstrapHash,
+    workDir
+  }) : recipeIdentity;
+  return {
+    ...recipe != null ? { recipe } : {},
+    ...recipeIdentity != null ? { recipeIdentity } : {},
+    ...identity != null ? { identity } : {},
+    ...workDir != null ? { workDir } : {},
+    ...recipe != null || settings.onBootstrap != null ? {
+      onFirstCreate: (session, opts) => runSandboxBootstrap({
+        session,
+        recipe,
+        recipeIdentity,
+        workDir,
+        onBootstrap: settings.onBootstrap,
+        abortSignal: opts.abortSignal
+      })
+    } : {}
+  };
+}
+async function runSandboxBootstrap({
+  session,
+  recipe,
+  recipeIdentity,
+  workDir,
+  onBootstrap,
+  abortSignal
+}) {
+  if (recipe != null && recipeIdentity != null) {
+    await applyBootstrapRecipe(session, recipe, recipeIdentity, {
+      abortSignal
+    });
+  }
+  if (onBootstrap == null) return;
+  const defaultWorkingDirectory = await resolveDefaultWorkingDirectory({
+    session,
+    abortSignal
+  });
+  const bootstrapWorkDir = workDir == null ? defaultWorkingDirectory : joinSandboxPath({
+    base: defaultWorkingDirectory,
+    path: workDir
+  });
+  await ensureSandboxDirectory({
+    session,
+    workDir: bootstrapWorkDir,
+    abortSignal
+  });
+  await onBootstrap({ session, workDir: bootstrapWorkDir, abortSignal });
+}
+async function resolveDefaultWorkingDirectory({
+  session,
+  abortSignal
+}) {
+  const result = await session.run({
+    command: "pwd",
+    abortSignal
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to resolve sandbox default working directory (exit ${result.exitCode}): ${result.stderr || result.stdout}`
+    );
+  }
+  const cwd = result.stdout.trim();
+  if (!posix.isAbsolute(cwd)) {
+    throw new Error(
+      `Failed to resolve sandbox default working directory: expected an absolute path, got ${JSON.stringify(cwd)}.`
+    );
+  }
+  return cwd === "/" ? cwd : cwd.replace(/\/+$/, "");
+}
+async function ensureSandboxDirectory({
+  session,
+  workDir,
+  abortSignal
+}) {
+  const result = await session.run({
+    command: 'mkdir -p "$WORK_DIR"',
+    env: { WORK_DIR: workDir },
+    abortSignal
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to create sandbox work directory ${workDir} (exit ${result.exitCode}): ${result.stderr || result.stdout}`
+    );
+  }
+}
+async function hashSandboxBootstrapIdentity({
+  recipeIdentity,
+  bootstrapHash,
+  workDir
+}) {
+  const encoder = new TextEncoder();
+  const chunks = [];
+  const pushString = (value) => {
+    chunks.push(encoder.encode(value));
+    chunks.push(encoder.encode("\0"));
+  };
+  pushString(String(SANDBOX_BOOTSTRAP_IDENTITY_VERSION));
+  pushString(recipeIdentity != null ? recipeIdentity : "");
+  pushString(bootstrapHash != null ? bootstrapHash : "");
+  pushString(workDir != null ? workDir : "");
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const buffer = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    buffer.set(chunk, offset);
+    offset += chunk.length;
+  }
+  const digest = await crypto.subtle.digest("SHA-256", buffer);
+  const bytes = new Uint8Array(digest);
+  let hex = "";
+  for (let i = 0; i < 8; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function joinSandboxPath({
+  base,
+  path
+}) {
+  return posix.join(base, path);
+}
+
 // src/agent/internal/resolve-observability.ts
 import { asArray } from "@ai-sdk/provider-utils";
 var ENV_TRUTHY = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
@@ -2281,7 +2463,10 @@ var HarnessAgent = class {
   constructor(settings) {
     this.version = "agent-v1";
     var _a3;
+    const sandboxConfig = resolveSandboxConfig(settings);
+    validateSandboxBootstrapSettings(sandboxConfig);
     this.settings = settings;
+    this.sandboxConfig = sandboxConfig;
     this.id = settings.id;
     this.userTools = (_a3 = settings.tools) != null ? _a3 : {};
     this.permissionMode = resolvePermissionMode({
@@ -2343,17 +2528,18 @@ var HarnessAgent = class {
     const effectiveContinueFrom = validatedContinueFrom != null ? validatedContinueFrom : validatedResumeFrom == null ? void 0 : validatedResumeFrom.continueFrom;
     const isResumedSession = validatedResumeFrom != null || effectiveContinueFrom != null;
     let recipe;
-    let identity;
     if (harness.getBootstrap != null) {
       recipe = await harness.getBootstrap({ abortSignal });
-      identity = await hashBootstrap(recipe);
     }
+    const sandboxBootstrapPlan = await createSandboxBootstrapPlan({
+      recipe,
+      settings: this.sandboxConfig
+    });
     const acquiredSandboxSession = await this._acquireSandbox({
       sandboxProvider,
       sessionId,
       isResume: isResumedSession,
-      recipe,
-      identity,
+      bootstrapPlan: sandboxBootstrapPlan,
       abortSignal
     });
     const leased = applyPortLease({
@@ -2363,22 +2549,28 @@ var HarnessAgent = class {
     });
     const sandboxSession = leased.sandboxSession;
     const leasedBridgePort = leased.port;
-    const sessionWorkDir = `${sandboxSession.defaultWorkingDirectory}/${harness.harnessId}-${sessionId}`;
+    const sessionWorkDir = resolveSessionWorkDir({
+      defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+      harnessId: harness.harnessId,
+      sessionId,
+      workDir: sandboxBootstrapPlan.workDir
+    });
     try {
-      if (!isResumedSession && recipe != null && identity != null) {
+      if (!isResumedSession && sandboxBootstrapPlan.recipe != null && sandboxBootstrapPlan.recipeIdentity != null) {
         await applyBootstrapRecipe(
           sandboxSession.restricted(),
-          recipe,
-          identity,
+          sandboxBootstrapPlan.recipe,
+          sandboxBootstrapPlan.recipeIdentity,
           { abortSignal }
         );
       }
-      await sandboxSession.run({
-        command: `mkdir -p ${sessionWorkDir}`,
+      await ensureSandboxDirectory({
+        session: sandboxSession,
+        workDir: sessionWorkDir,
         abortSignal
       });
-      if (this.settings.onSandboxSession != null) {
-        await this.settings.onSandboxSession({
+      if (this.sandboxConfig.onSession != null) {
+        await this.sandboxConfig.onSession({
           session: sandboxSession.restricted(),
           sessionWorkDir,
           abortSignal
@@ -2535,13 +2727,8 @@ var HarnessAgent = class {
     return sandboxProvider.createSession({
       sessionId: input.sessionId,
       abortSignal: input.abortSignal,
-      identity: input.identity,
-      onFirstCreate: input.recipe != null && input.identity != null ? (session, opts) => applyBootstrapRecipe(
-        session,
-        input.recipe,
-        input.identity,
-        opts
-      ) : void 0
+      identity: input.bootstrapPlan.identity,
+      onFirstCreate: input.bootstrapPlan.onFirstCreate
     });
   }
   /*
@@ -2682,6 +2869,18 @@ var HarnessGenerateTextResult = class {
     return this.finalStep.providerMetadata;
   }
 };
+function resolveSandboxConfig(settings) {
+  var _a3;
+  if (settings.onSandboxSession != null) {
+    console.warn(
+      "HarnessAgent: `onSandboxSession` is deprecated. Use `sandboxConfig.onSession` instead."
+    );
+  }
+  return {
+    ...settings.sandboxConfig,
+    ...((_a3 = settings.sandboxConfig) == null ? void 0 : _a3.onSession) == null && settings.onSandboxSession != null ? { onSession: settings.onSandboxSession } : {}
+  };
+}
 function applyPortLease(input) {
   const pool = input.provider.bridgePorts;
   if (pool == null || pool.length === 0) {
@@ -2718,21 +2917,35 @@ async function cleanupAfterStartFailure(input) {
 
 // src/agent/prewarm.ts
 async function prewarmHarness(options) {
-  var _a3, _b3;
-  const recipe = await ((_b3 = (_a3 = options.harness).getBootstrap) == null ? void 0 : _b3.call(_a3, {
+  var _a3, _b3, _c;
+  const sandboxConfig = (_a3 = options.sandboxConfig) != null ? _a3 : {};
+  validateSandboxBootstrapSettings(sandboxConfig);
+  const recipe = await ((_c = (_b3 = options.harness).getBootstrap) == null ? void 0 : _c.call(_b3, {
     abortSignal: options.abortSignal
   }));
-  if (recipe == null) return;
-  const identity = await hashBootstrap(recipe);
+  const bootstrapPlan = await createSandboxBootstrapPlan({
+    recipe,
+    settings: sandboxConfig
+  });
+  if (bootstrapPlan.identity == null || bootstrapPlan.onFirstCreate == null) {
+    return;
+  }
   const sandboxSession = await options.sandboxProvider.createSession({
     abortSignal: options.abortSignal,
-    identity,
-    onFirstCreate: (session, opts) => applyBootstrapRecipe(session, recipe, identity, opts)
+    identity: bootstrapPlan.identity,
+    onFirstCreate: bootstrapPlan.onFirstCreate
   });
   try {
-    await applyBootstrapRecipe(sandboxSession.restricted(), recipe, identity, {
-      abortSignal: options.abortSignal
-    });
+    if (bootstrapPlan.recipe != null && bootstrapPlan.recipeIdentity != null) {
+      await applyBootstrapRecipe(
+        sandboxSession.restricted(),
+        bootstrapPlan.recipe,
+        bootstrapPlan.recipeIdentity,
+        {
+          abortSignal: options.abortSignal
+        }
+      );
+    }
   } finally {
     await Promise.resolve(sandboxSession.stop()).catch(() => {
     });