@ai-sdk/harness 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ai-sdk/harness
 
+## 1.0.3
+
+### Patch Changes
+
+- 51d10a0: feat(harness): add `prepareSandboxForHarness` utility to prepare a caller-owned sandbox for one or more harnesses
+
+## 1.0.2
+
+### Patch Changes
+
+- ai@7.0.2
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -91,6 +91,18 @@ Use `session.detach()` to park a bridge-backed session for later attach, `sessio
 - 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.
 
+Use `prepareHarnessSandboxTemplate()` to create or refresh the sandbox provider's
+own reusable template for one harness before serving traffic. This is the
+replacement for `prewarmHarness()`, which remains as a deprecated alias.
+
+Use `prepareSandboxForHarness()` when you own an existing sandbox and want to
+prepare it before creating your own snapshot. It applies the selected harness
+bootstrap recipes and `sandboxConfig.onBootstrap`, returns the computed
+preparation identity and per-harness recipe identities, and leaves snapshotting
+or stopping the sandbox to your code. Later, create a sandbox from that snapshot
+and pass the native sandbox object to `createVercelSandbox({ sandbox })` for the
+`HarnessAgent`.
+
 ### Available harnesses
 
 See the [harness adapters documentation](https://ai-sdk.dev/v7/docs/ai-sdk-harnesses/harness-adapters).

package/agent/index.ts

@@ -1,5 +1,6 @@
 export { HarnessAgent } from '../src/agent/harness-agent';
 export type {
+  HarnessAgentSandboxConfig,
   HarnessAgentSettings,
   HarnessAgentToolApprovalConfiguration,
 } from '../src/agent/harness-agent-settings';
@@ -29,7 +30,14 @@ export {
   collectHarnessAgentToolApprovalContinuations,
   type HarnessAgentToolApprovalContinuation,
 } from '../src/agent/harness-agent-tool-approval-continuation';
-export { prewarmHarness } from '../src/agent/prewarm';
+export {
+  prepareHarnessSandboxTemplate,
+  prewarmHarness,
+} from '../src/agent/prewarm';
+export {
+  prepareSandboxForHarness,
+  type PrepareSandboxForHarnessResult,
+} from '../src/agent/prepare-sandbox-for-harness';
 export type {
   HarnessDebugConfig,
   HarnessDebugLevel,

package/dist/agent/index.d.ts

@@ -1456,25 +1456,39 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
 
 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
+ * Prepare a harness's sandbox template without running an agent. Idempotent: if
+ * the template already exists (snapshot present, or marker on a non-snapshot
  * provider), this resolves quickly.
  *
  * Use from a CI/deploy script to amortize the first-session cost so production
  * sessions always resume from snapshot. For adapters without a bootstrap
  * recipe (no `getBootstrap`) this is a no-op.
  *
- * The temporary network sandbox session created during pre-warm is stopped
+ * The temporary network sandbox session created during preparation is stopped
  * before the function resolves; the snapshot/template state persists in the
  * provider's native storage (for Vercel: as the `currentSnapshotId` of the
  * named template sandbox).
  */
-declare function prewarmHarness(options: {
+declare function prepareHarnessSandboxTemplate(options: {
     readonly harness: HarnessAgentAdapter;
     readonly sandboxProvider: HarnessV1SandboxProvider;
     readonly sandboxConfig?: SandboxBootstrapSettings;
     readonly abortSignal?: AbortSignal;
 }): Promise<void>;
+/** @deprecated Use `prepareHarnessSandboxTemplate` instead. */
+declare const prewarmHarness: typeof prepareHarnessSandboxTemplate;
+
+type PrepareSandboxForHarnessResult = {
+    readonly identity?: string;
+    readonly recipeIdentities: Record<string, string>;
+    readonly skippedHarnessIds: ReadonlyArray<string>;
+};
+declare function prepareSandboxForHarness(options: {
+    readonly session: Experimental_SandboxSession;
+    readonly harnesses: ReadonlyArray<HarnessAgentAdapter>;
+    readonly sandboxConfig?: HarnessAgentSandboxConfig;
+    readonly abortSignal?: AbortSignal;
+}): Promise<PrepareSandboxForHarnessResult>;
 
 declare const symbol$1: unique symbol;
 /**
@@ -1551,4 +1565,4 @@ interface TraceTreeReporterOptions {
 }
 declare function createTraceTreeReporter(options?: TraceTreeReporterOptions): Telemetry;
 
-export { type FileReporter, type FileReporterOptions, HarnessAgent, type HarnessAgentAdapter, type HarnessAgentAdapterSession, type HarnessAgentBuiltinTool, type HarnessAgentBuiltinToolName, type HarnessAgentBuiltinToolUseKind, type HarnessAgentBuiltinTools, type HarnessAgentContinueTurnOptions, type HarnessAgentContinueTurnState, type HarnessAgentLifecycleState, type HarnessAgentPendingToolApproval, type HarnessAgentPermissionMode, type HarnessAgentPrompt, type HarnessAgentPromptControl, type HarnessAgentPromptTurnOptions, type HarnessAgentResumeSessionState, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentSkill, type HarnessAgentStartOptions, type HarnessAgentStreamPart, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolApprovalContinuation, type HarnessAgentToolSpec, HarnessCapabilityUnsupportedError, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, HarnessError, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, createFileReporter, createTraceTreeReporter, prewarmHarness };
+export { type FileReporter, type FileReporterOptions, HarnessAgent, type HarnessAgentAdapter, type HarnessAgentAdapterSession, type HarnessAgentBuiltinTool, type HarnessAgentBuiltinToolName, type HarnessAgentBuiltinToolUseKind, type HarnessAgentBuiltinTools, type HarnessAgentContinueTurnOptions, type HarnessAgentContinueTurnState, type HarnessAgentLifecycleState, type HarnessAgentPendingToolApproval, type HarnessAgentPermissionMode, type HarnessAgentPrompt, type HarnessAgentPromptControl, type HarnessAgentPromptTurnOptions, type HarnessAgentResumeSessionState, type HarnessAgentSandboxConfig, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentSkill, type HarnessAgentStartOptions, type HarnessAgentStreamPart, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolApprovalContinuation, type HarnessAgentToolSpec, HarnessCapabilityUnsupportedError, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, HarnessError, type PrepareSandboxForHarnessResult, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, createFileReporter, createTraceTreeReporter, prepareHarnessSandboxTemplate, prepareSandboxForHarness, prewarmHarness };

package/dist/agent/index.js

@@ -2916,7 +2916,7 @@ async function cleanupAfterStartFailure(input) {
 }
 
 // src/agent/prewarm.ts
-async function prewarmHarness(options) {
+async function prepareHarnessSandboxTemplate(options) {
   var _a3, _b3, _c;
   const sandboxConfig = (_a3 = options.sandboxConfig) != null ? _a3 : {};
   validateSandboxBootstrapSettings(sandboxConfig);
@@ -2951,6 +2951,109 @@ async function prewarmHarness(options) {
     });
   }
 }
+var prewarmHarness = prepareHarnessSandboxTemplate;
+
+// src/agent/prepare-sandbox-for-harness.ts
+var PREPARED_SANDBOX_IDENTITY_VERSION = 1;
+async function prepareSandboxForHarness(options) {
+  var _a3, _b3;
+  const sandboxConfig = (_a3 = options.sandboxConfig) != null ? _a3 : {};
+  validateSandboxBootstrapSettings(sandboxConfig);
+  if (options.harnesses.length === 0) {
+    throw new Error(
+      "prepareSandboxForHarness: at least one harness must be provided."
+    );
+  }
+  const harnesses = [...options.harnesses].sort(
+    (a, b) => a.harnessId.localeCompare(b.harnessId)
+  );
+  assertUniqueHarnessIds(harnesses);
+  const workDir = sandboxConfig.workDir == null ? void 0 : normalizeSandboxWorkDir(sandboxConfig.workDir);
+  const recipeIdentities = {};
+  const skippedHarnessIds = [];
+  for (const harness of harnesses) {
+    const recipe = await ((_b3 = harness.getBootstrap) == null ? void 0 : _b3.call(harness, {
+      abortSignal: options.abortSignal
+    }));
+    if (recipe == null) {
+      skippedHarnessIds.push(harness.harnessId);
+      continue;
+    }
+    const recipeIdentity = await hashHarnessBootstrap(recipe);
+    recipeIdentities[harness.harnessId] = recipeIdentity;
+    await applyBootstrapRecipe(options.session, recipe, recipeIdentity, {
+      abortSignal: options.abortSignal
+    });
+  }
+  if (sandboxConfig.onBootstrap != null) {
+    await runSandboxBootstrap({
+      session: options.session,
+      workDir,
+      onBootstrap: sandboxConfig.onBootstrap,
+      abortSignal: options.abortSignal
+    });
+  }
+  const identity = await resolvePreparedSandboxIdentity({
+    recipeIdentities,
+    bootstrapHash: sandboxConfig.bootstrapHash,
+    workDir
+  });
+  return {
+    ...identity != null ? { identity } : {},
+    recipeIdentities,
+    skippedHarnessIds
+  };
+}
+function assertUniqueHarnessIds(harnesses) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const harness of harnesses) {
+    if (seen.has(harness.harnessId)) {
+      throw new Error(
+        `prepareSandboxForHarness: duplicate harness id "${harness.harnessId}".`
+      );
+    }
+    seen.add(harness.harnessId);
+  }
+}
+async function resolvePreparedSandboxIdentity({
+  recipeIdentities,
+  bootstrapHash,
+  workDir
+}) {
+  const entries = Object.entries(recipeIdentities).sort(
+    ([a], [b]) => a.localeCompare(b)
+  );
+  if (entries.length === 0 && bootstrapHash == null) {
+    return void 0;
+  }
+  const encoder = new TextEncoder();
+  const chunks = [];
+  const pushString = (value) => {
+    chunks.push(encoder.encode(value));
+    chunks.push(encoder.encode("\0"));
+  };
+  pushString(String(PREPARED_SANDBOX_IDENTITY_VERSION));
+  pushString(workDir != null ? workDir : "");
+  pushString(bootstrapHash != null ? bootstrapHash : "");
+  for (const [harnessId, identity] of entries) {
+    pushString(harnessId);
+    pushString(identity);
+  }
+  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;
+}
 
 // src/agent/observability/file-reporter.ts
 import { appendFileSync, mkdirSync } from "fs";
@@ -3180,6 +3283,8 @@ export {
   collectHarnessAgentToolApprovalContinuations,
   createFileReporter,
   createTraceTreeReporter,
+  prepareHarnessSandboxTemplate,
+  prepareSandboxForHarness,
   prewarmHarness
 };
 //# sourceMappingURL=index.js.map