@ai-sdk/harness 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -46,7 +46,7 @@
   "dependencies": {
     "@ai-sdk/provider": "4.0.0",
     "@ai-sdk/provider-utils": "5.0.0",
-    "ai": "7.0.1"
+    "ai": "7.0.2"
   },
   "peerDependencies": {
     "ws": "^8.21.0"

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

@@ -0,0 +1,148 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessAgentSandboxConfig } from './harness-agent-settings';
+import type { HarnessAgentAdapter } from './harness-agent-types';
+import {
+  applyBootstrapRecipe,
+  hashHarnessBootstrap,
+} from './internal/bootstrap-recipe';
+import {
+  normalizeSandboxWorkDir,
+  runSandboxBootstrap,
+  validateSandboxBootstrapSettings,
+} from './internal/sandbox-bootstrap';
+
+const PREPARED_SANDBOX_IDENTITY_VERSION = 1;
+
+export type PrepareSandboxForHarnessResult = {
+  readonly identity?: string;
+  readonly recipeIdentities: Record<string, string>;
+  readonly skippedHarnessIds: ReadonlyArray<string>;
+};
+
+export async function prepareSandboxForHarness(options: {
+  readonly session: SandboxSession;
+  readonly harnesses: ReadonlyArray<HarnessAgentAdapter>;
+  readonly sandboxConfig?: HarnessAgentSandboxConfig;
+  readonly abortSignal?: AbortSignal;
+}): Promise<PrepareSandboxForHarnessResult> {
+  const sandboxConfig = options.sandboxConfig ?? {};
+  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
+      ? undefined
+      : normalizeSandboxWorkDir(sandboxConfig.workDir);
+  const recipeIdentities: Record<string, string> = {};
+  const skippedHarnessIds: string[] = [];
+
+  for (const harness of harnesses) {
+    const recipe = await harness.getBootstrap?.({
+      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: ReadonlyArray<HarnessAgentAdapter>,
+): void {
+  const seen = new Set<string>();
+  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,
+}: {
+  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 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;
+}

package/src/agent/prewarm.ts

@@ -10,20 +10,20 @@ import {
 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).
  */
-export async function prewarmHarness(options: {
+export async function prepareHarnessSandboxTemplate(options: {
   readonly harness: HarnessAgentAdapter;
   readonly sandboxProvider: HarnessV1SandboxProvider;
   readonly sandboxConfig?: SandboxBootstrapSettings;
@@ -63,3 +63,6 @@ export async function prewarmHarness(options: {
     await Promise.resolve(sandboxSession.stop()).catch(() => {});
   }
 }
+
+/** @deprecated Use `prepareHarnessSandboxTemplate` instead. */
+export const prewarmHarness = prepareHarnessSandboxTemplate;