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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.0-beta.24",
+  "version": "1.0.0-beta.26",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -46,7 +46,7 @@
   "dependencies": {
     "@ai-sdk/provider": "4.0.0-beta.20",
     "@ai-sdk/provider-utils": "5.0.0-beta.50",
-    "ai": "7.0.0-beta.185"
+    "ai": "7.0.0-beta.186"
   },
   "peerDependencies": {
     "ws": "^8.21.0"

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

@@ -18,6 +18,48 @@ export type HarnessAgentToolApprovalConfiguration = Readonly<
   Record<string, ToolApprovalStatus>
 >;
 
+export 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: 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: SandboxSession;
+    readonly sessionWorkDir: string;
+    readonly abortSignal?: AbortSignal;
+  }) => Promise<void>;
+};
+
 /**
  * Construction-time settings for a `HarnessAgent`.
  *
@@ -92,19 +134,12 @@ export type HarnessAgentSettings<
   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: 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

package/src/agent/harness-agent.ts

@@ -20,7 +20,10 @@ import type {
   ReasoningOutput,
   StreamTextResult,
 } from 'ai';
-import type { HarnessAgentSettings } from './harness-agent-settings';
+import type {
+  HarnessAgentSandboxConfig,
+  HarnessAgentSettings,
+} from './harness-agent-settings';
 import { HarnessAgentSession } from './harness-agent-session';
 import type {
   HarnessAgentAdapter,
@@ -34,14 +37,18 @@ import {
   collectHarnessAgentToolApprovalContinuations,
   type HarnessAgentToolApprovalContinuation,
 } from './harness-agent-tool-approval-continuation';
-import {
-  applyBootstrapRecipe,
-  hashBootstrap,
-} from './internal/bootstrap-recipe';
+import { applyBootstrapRecipe } from './internal/bootstrap-recipe';
 import {
   acquireBridgePort,
   releaseBridgePort,
 } from './internal/bridge-port-registry';
+import {
+  createSandboxBootstrapPlan,
+  ensureSandboxDirectory,
+  resolveSessionWorkDir,
+  validateSandboxBootstrapSettings,
+  type SandboxBootstrapPlan,
+} from './internal/sandbox-bootstrap';
 import { buildObservability } from './internal/resolve-observability';
 import { validateLifecycleStateData } from './internal/lifecycle-state-validation';
 import {
@@ -130,11 +137,15 @@ export class HarnessAgent<
   readonly tools: HarnessAllTools<THarness, TUserTools>;
 
   private readonly settings: HarnessAgentSettings<THarness, TUserTools>;
+  private readonly sandboxConfig: HarnessAgentSandboxConfig;
   private readonly userTools: TUserTools;
   private readonly permissionMode: HarnessAgentPermissionMode;
 
   constructor(settings: HarnessAgentSettings<THarness, TUserTools>) {
+    const sandboxConfig = resolveSandboxConfig(settings);
+    validateSandboxBootstrapSettings(sandboxConfig);
     this.settings = settings;
+    this.sandboxConfig = sandboxConfig;
     this.id = settings.id;
     this.userTools = settings.tools ?? ({} as TUserTools);
     this.permissionMode = resolvePermissionMode({
@@ -230,19 +241,25 @@ export class HarnessAgent<
       validatedResumeFrom != null || effectiveContinueFrom != null;
 
     let recipe: HarnessV1Bootstrap | undefined;
-    let identity: string | undefined;
-
     if (harness.getBootstrap != null) {
       recipe = await harness.getBootstrap({ abortSignal });
-      identity = await hashBootstrap(recipe);
     }
 
+    // Defines the hashes based on both harness bootstrap recipe and
+    // consumer-defined onBootstrap callback.
+    const sandboxBootstrapPlan = await createSandboxBootstrapPlan({
+      recipe,
+      settings: this.sandboxConfig,
+    });
+
+    // Acquires the concrete sandbox session, either by starting fresh and then
+    // creating a post-bootstrap snapshot, or by reusing a previously created
+    // snapshot based on the bootstrap-based hashes.
     const acquiredSandboxSession = await this._acquireSandbox({
       sandboxProvider,
       sessionId,
       isResume: isResumedSession,
-      recipe,
-      identity,
+      bootstrapPlan: sandboxBootstrapPlan,
       abortSignal,
     });
 
@@ -253,27 +270,37 @@ export class HarnessAgent<
     });
     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 {
-      /*
-       * Adapter bootstrap is one-time work for fresh sessions. The consumer
-       * hook runs for every acquired sandbox session after the work dir exists.
-       */
-      if (!isResumedSession && recipe != null && identity != null) {
+      // In case the sandbox session was created with a custom sandbox, or in
+      // case the sandbox provider doesn't respect `onFirstCreate`, we still
+      // have to ensure the harness bootstrap recipe has run. In the common
+      // scenario, this will be a cheap no-op based on just a marker check.
+      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,
@@ -501,8 +528,7 @@ export class HarnessAgent<
     sandboxProvider: HarnessV1SandboxProvider;
     sessionId: string;
     isResume: boolean;
-    recipe: HarnessV1Bootstrap | undefined;
-    identity: string | undefined;
+    bootstrapPlan: SandboxBootstrapPlan;
     abortSignal: AbortSignal | undefined;
   }): Promise<HarnessV1NetworkSandboxSession> {
     const { sandboxProvider } = input;
@@ -521,17 +547,8 @@ export class HarnessAgent<
     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,
-              )
-          : undefined,
+      identity: input.bootstrapPlan.identity,
+      onFirstCreate: input.bootstrapPlan.onFirstCreate,
     });
   }
 
@@ -756,6 +773,24 @@ class HarnessGenerateTextResult<
   }
 }
 
+function resolveSandboxConfig(
+  settings: Pick<HarnessAgentSettings, 'sandboxConfig' | 'onSandboxSession'>,
+): HarnessAgentSandboxConfig {
+  if (settings.onSandboxSession != null) {
+    console.warn(
+      'HarnessAgent: `onSandboxSession` is deprecated. Use `sandboxConfig.onSession` instead.',
+    );
+  }
+
+  return {
+    ...settings.sandboxConfig,
+    ...(settings.sandboxConfig?.onSession == null &&
+    settings.onSandboxSession != null
+      ? { onSession: settings.onSandboxSession }
+      : {}),
+  };
+}
+
 /*
  * Bridge-port leasing helper. Returns the port-narrowed network sandbox session
  * plus the leased port (or `undefined` when the provider has no port pool). Kept here

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

@@ -16,7 +16,7 @@ export const BOOTSTRAP_SCHEMA_VERSION = 1;
  * Used by sandbox providers as part of the persistent sandbox name so
  * recipe changes automatically invalidate snapshots.
  */
-export async function hashBootstrap(
+export async function hashHarnessBootstrap(
   recipe: HarnessV1Bootstrap,
 ): Promise<string> {
   const encoder = new TextEncoder();

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

@@ -0,0 +1,266 @@
+import { posix } from 'node:path';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1Bootstrap } from '../../v1';
+import type { HarnessAgentSandboxConfig } from '../harness-agent-settings';
+import { applyBootstrapRecipe, hashHarnessBootstrap } from './bootstrap-recipe';
+
+const SANDBOX_BOOTSTRAP_IDENTITY_VERSION = 1;
+
+type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
+
+export type SandboxBootstrapPlan = {
+  readonly recipe?: HarnessV1Bootstrap;
+  readonly recipeIdentity?: string;
+  readonly identity?: string;
+  readonly workDir?: string;
+  readonly onFirstCreate?: (
+    session: SandboxSession,
+    opts: { abortSignal?: AbortSignal },
+  ) => Promise<void>;
+};
+
+export function validateSandboxBootstrapSettings(
+  settings: SandboxBootstrapSettings,
+): void {
+  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);
+  }
+}
+
+export function normalizeSandboxWorkDir(workDir: string): string {
+  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;
+}
+
+export function resolveSessionWorkDir({
+  defaultWorkingDirectory,
+  harnessId,
+  sessionId,
+  workDir,
+}: {
+  readonly defaultWorkingDirectory: string;
+  readonly harnessId: string;
+  readonly sessionId: string;
+  readonly workDir?: string;
+}): string {
+  return joinSandboxPath({
+    base: defaultWorkingDirectory,
+    path: workDir ?? `${harnessId}-${sessionId}`,
+  });
+}
+
+export async function createSandboxBootstrapPlan({
+  recipe,
+  settings,
+}: {
+  readonly recipe?: HarnessV1Bootstrap;
+  readonly settings: SandboxBootstrapSettings;
+}): Promise<SandboxBootstrapPlan> {
+  const workDir =
+    settings.workDir == null
+      ? undefined
+      : normalizeSandboxWorkDir(settings.workDir);
+  const recipeIdentity =
+    recipe == null ? undefined : 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,
+            }),
+        }
+      : {}),
+  };
+}
+
+export async function runSandboxBootstrap({
+  session,
+  recipe,
+  recipeIdentity,
+  workDir,
+  onBootstrap,
+  abortSignal,
+}: {
+  readonly session: SandboxSession;
+  readonly recipe?: HarnessV1Bootstrap;
+  readonly recipeIdentity?: string;
+  readonly workDir?: string;
+  readonly onBootstrap?: SandboxBootstrapSettings['onBootstrap'];
+  readonly abortSignal?: AbortSignal;
+}): Promise<void> {
+  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 });
+}
+
+export async function resolveDefaultWorkingDirectory({
+  session,
+  abortSignal,
+}: {
+  readonly session: SandboxSession;
+  readonly abortSignal?: AbortSignal;
+}): Promise<string> {
+  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(/\/+$/, '');
+}
+
+export async function ensureSandboxDirectory({
+  session,
+  workDir,
+  abortSignal,
+}: {
+  readonly session: SandboxSession;
+  readonly workDir: string;
+  readonly abortSignal?: AbortSignal;
+}): Promise<void> {
+  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,
+}: {
+  readonly recipeIdentity?: string;
+  readonly bootstrapHash?: string;
+  readonly workDir?: string;
+}): Promise<string> {
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  const pushString = (value: string) => {
+    chunks.push(encoder.encode(value));
+    chunks.push(encoder.encode('\0'));
+  };
+
+  pushString(String(SANDBOX_BOOTSTRAP_IDENTITY_VERSION));
+  pushString(recipeIdentity ?? '');
+  pushString(bootstrapHash ?? '');
+  pushString(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,
+}: {
+  readonly base: string;
+  readonly path: string;
+}): string {
+  return posix.join(base, path);
+}

package/src/agent/prewarm.ts

@@ -1,9 +1,13 @@
 import type { HarnessV1SandboxProvider } from '../v1';
 import type { HarnessAgentAdapter } from './harness-agent-types';
+import type { HarnessAgentSandboxConfig } from './harness-agent-settings';
+import { applyBootstrapRecipe } from './internal/bootstrap-recipe';
 import {
-  applyBootstrapRecipe,
-  hashBootstrap,
-} from './internal/bootstrap-recipe';
+  createSandboxBootstrapPlan,
+  validateSandboxBootstrapSettings,
+} from './internal/sandbox-bootstrap';
+
+type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
 
 /**
  * Pre-build a harness's sandbox template without running an agent. Idempotent:
@@ -22,25 +26,39 @@ import {
 export async function prewarmHarness(options: {
   readonly harness: HarnessAgentAdapter;
   readonly sandboxProvider: HarnessV1SandboxProvider;
+  readonly sandboxConfig?: SandboxBootstrapSettings;
   readonly abortSignal?: AbortSignal;
 }): Promise<void> {
+  const sandboxConfig = options.sandboxConfig ?? {};
+  validateSandboxBootstrapSettings(sandboxConfig);
   const recipe = await options.harness.getBootstrap?.({
     abortSignal: options.abortSignal,
   });
-  if (recipe == null) return;
+  const bootstrapPlan = await createSandboxBootstrapPlan({
+    recipe,
+    settings: sandboxConfig,
+  });
+  if (bootstrapPlan.identity == null || bootstrapPlan.onFirstCreate == null) {
+    return;
+  }
 
-  const identity = await hashBootstrap(recipe);
   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(() => {});
   }