@ai-sdk/harness 1.0.123 → 1.0.126

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

@@ -25,8 +25,8 @@ type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
  *
  * 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).
+ * provider's native storage.
+ * @deprecated Use `createHarnessSandboxTemplate` and pass its template to a sandbox session creator instead.
  */
 export async function prepareHarnessSandboxTemplate(options: {
   readonly harness: HarnessAgentAdapter;
@@ -34,6 +34,9 @@ export async function prepareHarnessSandboxTemplate(options: {
   readonly sandboxConfig?: SandboxBootstrapSettings;
   readonly abortSignal?: AbortSignal;
 }): Promise<void> {
+  console.warn(
+    'prepareHarnessSandboxTemplate (prewarmHarness) is deprecated. Use createHarnessSandboxTemplate and a sandbox session creator instead.',
+  );
   const sandboxConfig = options.sandboxConfig ?? {};
   validateSandboxBootstrapSettings(sandboxConfig);
 

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

@@ -13,9 +13,9 @@ import {
   runSandboxBootstrap,
   validateSandboxBootstrapSettings,
 } from './internal/sandbox-bootstrap';
+import { resolvePreparedSandboxIdentity } from './internal/prepared-sandbox-identity';
 
-const PREPARED_SANDBOX_IDENTITY_VERSION = 1;
-
+/** @deprecated Use `createHarnessSandboxTemplate` and `template.prepare` instead. */
 export type PrepareSandboxForHarnessResult = {
   readonly identity?: string;
   readonly recipeIdentities: Record<string, string>;
@@ -41,6 +41,7 @@ export type PrepareSandboxForHarnessResult = {
  *
  * Repeated harness IDs are prepared once. When multiple adapters use the same
  * ID, the last adapter in `harnesses` is used.
+ * @deprecated Use `createHarnessSandboxTemplate` and `template.prepare` instead.
  */
 export async function prepareSandboxForHarness(options: {
   readonly session: SandboxSession;
@@ -48,6 +49,9 @@ export async function prepareSandboxForHarness(options: {
   readonly sandboxConfig?: HarnessAgentSandboxConfig;
   readonly abortSignal?: AbortSignal;
 }): Promise<PrepareSandboxForHarnessResult> {
+  console.warn(
+    'prepareSandboxForHarness is deprecated. Use createHarnessSandboxTemplate and template.prepare instead.',
+  );
   const sandboxConfig = options.sandboxConfig ?? {};
   validateSandboxBootstrapSettings(sandboxConfig);
 
@@ -107,6 +111,7 @@ export async function prepareSandboxForHarness(options: {
       session: options.session,
       workDir,
       onBootstrap: sandboxConfig.onBootstrap,
+      bootstrapHash: sandboxConfig.bootstrapHash,
       defaultWorkingDirectory,
       abortSignal: options.abortSignal,
     });
@@ -124,52 +129,3 @@ export async function prepareSandboxForHarness(options: {
     skippedHarnessIds,
   };
 }
-
-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/v1/harness-v1-network-sandbox-session.ts

@@ -34,8 +34,8 @@ export function harnessStateDirectoryPath({
 }
 
 /**
- * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. The
- * harness keeps this for the lifetime of a session. It is itself a
+ * Network sandbox session returned by sandbox adapter creation and resume
+ * functions. The harness keeps this for the lifetime of a session. It is itself a
  * {@link SandboxSession} (file I/O, exec, spawn) and adds the infra surface on
  * top: port resolution, lifecycle, and network-policy mutation.
  *
@@ -46,22 +46,15 @@ export function harnessStateDirectoryPath({
  */
 export interface HarnessV1NetworkSandboxSession extends SandboxSession {
   /**
-   * Stable identifier for the underlying sandbox resource. Used by the
-   * harness session manager as the durable lookup key for cross-process
-   * resume — the framework persists this on lifecycle state so a future
-   * process can call `HarnessV1SandboxProvider.resume?({ sessionId })` and
-   * reach the same resource. Providers populate it from their native
-   * identifier (Vercel: the sandbox name; just-bash: a UUID minted at
-   * create time).
+   * Identifier for the sandbox session. Persist this separately from the
+   * harness session ID and resume state when reattaching across processes.
    */
   readonly id: string;
 
   /**
    * The sandbox's default working directory — the absolute path that
    * `run`/`spawn` resolve relative commands against when no `workingDirectory`
-   * is given. Read from the live sandbox (it is provider-specific and
-   * configurable at create time: Vercel defaults to `/vercel/sandbox`,
-   * just-bash to `/home/user`), never hardcoded.
+   * is given. Read from the live sandbox, never hardcoded.
    *
    * The framework composes each session's working directory underneath this
    * path (`<defaultWorkingDirectory>/<harnessId>-<sessionId>`) so adapters do
@@ -105,7 +98,7 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
 
   /**
    * Update the sandbox's outbound network policy. Optional — implementations
-   * without a local enforcement primitive (e.g. just-bash) omit this. Callers
+   * without a local enforcement primitive omit this. Callers
    * use optional-call (`sandboxSession.setNetworkPolicy?.(policy)`); a
    * missing implementation is a no-op.
    */
@@ -139,7 +132,7 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
   /**
    * Replace the set of ports exposed by the sandbox. Full-replacement
    * semantics: ports omitted from the array are deregistered. Optional —
-   * implementations that cannot expose ports (e.g. just-bash) omit this.
+   * implementations that cannot expose ports omit this.
    */
   readonly setPorts?: (
     ports: ReadonlyArray<number>,

package/src/v1/harness-v1-sandbox-provider.ts

@@ -7,6 +7,7 @@ import type { HarnessV1NetworkSandboxSession } from './harness-v1-network-sandbo
  * `LanguageModelV4` providers, no I/O performed at construction. The actual
  * sandbox is created (or wrapped) when `HarnessAgent` calls `createSession()`.
  */
+/** @deprecated Supply a sandbox session to `HarnessAgent.createSession()` instead. */
 export interface HarnessV1SandboxProvider {
   readonly specificationVersion: 'harness-sandbox-v1';
   readonly providerId: string;
@@ -54,8 +55,8 @@ export interface HarnessV1SandboxProvider {
 
   /**
    * Reattach to an existing sandbox previously created with the same
-   * `sessionId`. Optional — providers that cannot rehydrate by id (e.g.
-   * just-bash) omit this; the harness throws
+   * `sessionId`. Optional — providers that cannot rehydrate by id omit
+   * this; the harness throws
    * `HarnessCapabilityUnsupportedError` when resume is attempted against
    * them.
    *

package/src/v1/harness-v1-sandbox-session-create-options.ts

@@ -0,0 +1,14 @@
+import type { HarnessV1SandboxTemplate } from './harness-v1-sandbox-template';
+
+export type HarnessV1SandboxSessionCreateOptions<
+  TProviderOptions extends object,
+> = TProviderOptions & {
+  /**
+   * Manually assign the ID of a newly created sandbox session. Creation never
+   * looks up or resumes an existing session. An existing sandbox resource with
+   * the same ID is a creation conflict.
+   */
+  readonly sandboxId?: string;
+  readonly template?: HarnessV1SandboxTemplate;
+  readonly abortSignal?: AbortSignal;
+};

package/src/v1/harness-v1-sandbox-session-resume-options.ts

@@ -0,0 +1,10 @@
+export type HarnessV1SandboxSessionResumeOptions<
+  TProviderOptions extends object,
+> = TProviderOptions & {
+  /**
+   * ID of the existing sandbox session to reattach. Resume never creates a
+   * sandbox when the ID cannot be found.
+   */
+  readonly sandboxId: string;
+  readonly abortSignal?: AbortSignal;
+};

package/src/v1/harness-v1-sandbox-template.ts

@@ -0,0 +1,9 @@
+import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+
+export type HarnessV1SandboxTemplate = {
+  readonly identity: string;
+  readonly prepare: (options: {
+    readonly session: Experimental_SandboxSession;
+    readonly abortSignal?: AbortSignal;
+  }) => Promise<void>;
+};

package/src/v1/index.ts

@@ -48,6 +48,9 @@ export type {
   HarnessV1ResponseFormat,
 } from './harness-v1-response-format';
 export type { HarnessV1SandboxProvider } from './harness-v1-sandbox-provider';
+export type { HarnessV1SandboxTemplate } from './harness-v1-sandbox-template';
+export type { HarnessV1SandboxSessionCreateOptions } from './harness-v1-sandbox-session-create-options';
+export type { HarnessV1SandboxSessionResumeOptions } from './harness-v1-sandbox-session-resume-options';
 export type {
   HarnessV1ContinueTurnState,
   HarnessV1LifecycleState,