@ai-sdk/sandbox-vercel 1.0.123 → 1.0.126

package/src/vercel-sandbox.ts

@@ -1,455 +1,181 @@
 import {
-  HarnessSandboxAuthenticationError,
   type HarnessV1NetworkSandboxSession,
-  type HarnessV1SandboxProvider,
+  type HarnessV1SandboxSessionCreateOptions,
+  type HarnessV1SandboxSessionResumeOptions,
 } from '@ai-sdk/harness';
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 import { Sandbox } from '@vercel/sandbox';
 import { VercelNetworkSandboxSession } from './vercel-network-sandbox-session';
 import { VercelSandboxSession } from './vercel-sandbox-session';
+import {
+  createLiveSandboxFromSnapshot,
+  ensureTemplateSnapshot,
+  getSandboxLookupParams,
+  withVercelSandboxAuthenticationError,
+  withDefaultSandboxSettings,
+  type BaseCreateSandboxParams,
+  type DistributiveOmit,
+  type Prettify,
+  type VercelSandboxCreateParams,
+} from './utils';
+
+export type VercelNativeSandboxSession = Sandbox;
+
+type VercelSandboxCreationSettings = VercelSandboxCreateParams & {
+  sandbox?: never;
+  name?: string;
+};
 
-/**
- * Flattens an intersection of object types into a single object type so the
- * resolved shape displays as its named properties rather than a chain of
- * `A & B & C`.
- */
-type Prettify<T> = { [K in keyof T]: T[K] } & {};
-
-/**
- * Distributes `Omit` across each member of a union instead of collapsing the
- * union to its common keys. `Sandbox.create`'s parameter is a union (a
- * git/tarball/no-source create variant and a snapshot-source create variant),
- * so a plain `Omit` would discard keys absent from any one member (e.g.
- * `runtime`, which the snapshot variant lacks) and merge the `source` shapes.
- * Applying `Omit` per-member preserves every variant intact; the `Prettify`
- * wrapper collapses each member's intersections into a readable object shape.
- */
-type DistributiveOmit<T, K extends keyof any> = T extends unknown
-  ? Prettify<Omit<T, K>>
-  : never;
-
-/**
- * Parameters forwarded to `@vercel/sandbox`'s `Sandbox.create` when creating
- * a sandbox from scratch. Aliased directly from the underlying SDK so the
- * full surface — every option Vercel supports, including its native
- * `NetworkPolicy` — is available without us re-declaring it.
- */
-type VercelSandboxCreateParams = DistributiveOmit<
-  NonNullable<Parameters<typeof Sandbox.create>[0]>,
-  'onResume'
+type VercelCreationSettings = DistributiveOmit<
+  VercelSandboxCreationSettings,
+  'sandbox'
+>;
+export type VercelNetworkSandboxSessionCreateOptions = Prettify<
+  HarnessV1SandboxSessionCreateOptions<VercelCreationSettings> & {
+    sandbox?: never;
+  }
 >;
 
-/**
- * Settings for {@link createVercelSandbox}. Two mutually-exclusive shapes:
- *
- * - `{ sandbox }` — wrap an already-created `@vercel/sandbox` `Sandbox`. The
- *   caller owns its lifecycle; the provider's `stop()` and `destroy()` are
- *   no-ops.
- * - {@link VercelSandboxCreateParams} fields — provider creates the underlying
- *   sandbox. When the adapter declares a bootstrap recipe the provider uses
- *   `Sandbox.getOrCreate` to maintain a persistent named template snapshot
- *   keyed by the recipe identity, and forks an ephemeral sandbox per session
- *   from the snapshot. Use `name` to override the auto-derived template name.
- */
-export type VercelSandboxSettings =
-  | { sandbox: Sandbox }
-  | (VercelSandboxCreateParams & {
-      sandbox?: never;
-      name?: string;
-    });
-
-/**
- * 30 minutes. The `@vercel/sandbox` SDK defaults to 5 minutes which is
- * too short for multi-step workflows — the VM expires between steps.
- */
-const DEFAULT_SANDBOX_TIMEOUT_MS = 30 * 60 * 1_000;
-const DEFAULT_SANDBOX_RUNTIME = 'node24';
-
-const VERCEL_PROVIDER_ID = 'vercel-sandbox';
-const TEMPLATE_NAME_PREFIX = 'ai-sdk-harness';
-const SESSION_NAME_PREFIX = 'ai-sdk-harness-session';
-const SNAPSHOT_POLL_INTERVAL_MS = 500;
-const SNAPSHOT_POLL_TIMEOUT_MS = 30_000;
-
-function sessionSandboxName(sessionId: string): string {
-  return `${SESSION_NAME_PREFIX}-${sessionId}`;
-}
-
-function hasExplicitSandboxEnvironment(params: object): boolean {
-  return (
-    ('runtime' in params && params.runtime != null) ||
-    ('image' in params && params.image != null) ||
-    ('source' in params &&
-      typeof params.source === 'object' &&
-      params.source != null &&
-      'type' in params.source &&
-      params.source.type === 'snapshot')
-  );
-}
-
-export function createVercelSandbox(
-  settings: VercelSandboxSettings = {} as VercelSandboxSettings,
-): HarnessV1SandboxProvider {
-  return new VercelSandboxProvider(settings);
-}
-
-/**
- * `HarnessV1SandboxProvider` implementation backed by `@vercel/sandbox`.
- * Construct one via {@link createVercelSandbox} at module scope and pass it
- * to a `HarnessAgent` (or call `createSession()` directly if you want raw
- * access to a network sandbox session).
- */
-export class VercelSandboxProvider implements HarnessV1SandboxProvider {
-  readonly specificationVersion = 'harness-sandbox-v1' as const;
-  readonly providerId = VERCEL_PROVIDER_ID;
-
-  constructor(private readonly settings: VercelSandboxSettings) {}
-
-  createSession = async (options?: {
-    sessionId?: string;
-    abortSignal?: AbortSignal;
-    identity?: string;
-    onFirstCreate?: (
-      session: SandboxSession,
-      opts: { abortSignal?: AbortSignal },
-    ) => Promise<void>;
-  }): Promise<HarnessV1NetworkSandboxSession> => {
-    options?.abortSignal?.throwIfAborted();
-
-    if ('sandbox' in this.settings && this.settings.sandbox != null) {
-      return new VercelNetworkSandboxSession({
-        sandbox: this.settings.sandbox,
-        ownsLifecycle: false,
-      });
-    }
-
-    type CreateNewBranch = BaseCreateSandboxParams & {
-      sandbox?: never;
-      name?: string;
-    };
-    const settings = this.settings as CreateNewBranch;
-    const {
-      sandbox: _ignoredSandbox,
-      name: explicitName,
-      ...createParams
-    } = settings;
-    // Sandbox v3 changed its implicit default from the Node 24 runtime to the
-    // Universal managed image. Keep this adapter's existing default stable while
-    // allowing callers to opt into managed images explicitly.
-    const baseParams = {
-      ...(hasExplicitSandboxEnvironment(createParams)
-        ? {}
-        : { runtime: DEFAULT_SANDBOX_RUNTIME }),
-      ...createParams,
-      timeout: createParams.timeout ?? DEFAULT_SANDBOX_TIMEOUT_MS,
-    } as BaseCreateSandboxParams;
-
-    const identity = options?.identity;
-    const onFirstCreate = options?.onFirstCreate;
-
-    // When sessionId is supplied, name the per-session sandbox deterministically
-    // so a future `resumeSession({ sessionId })` can locate it via
-    // `Sandbox.get({ name })`. Absent sessionId (e.g. prewarm), fall back to
-    // Vercel's auto-naming.
-    const sessionNameOverride = options?.sessionId
-      ? { name: sessionSandboxName(options.sessionId) }
-      : {};
-
-    if (identity == null || onFirstCreate == null) {
-      const sandbox = await withVercelSandboxAuthenticationError({
-        settings: this.settings,
-        operation: () =>
-          Sandbox.create({
-            ...baseParams,
-            ...sessionNameOverride,
-            ...(options?.abortSignal ? { signal: options.abortSignal } : {}),
-          }),
-      });
-      return new VercelNetworkSandboxSession({ sandbox, ownsLifecycle: true });
-    }
-
-    const templateName = explicitName ?? `${TEMPLATE_NAME_PREFIX}-${identity}`;
-    const cache = getSnapshotCache();
-    let snapshotId = cache.get(templateName);
-
-    if (snapshotId == null) {
-      const template = await withVercelSandboxAuthenticationError({
-        settings: this.settings,
-        operation: () =>
-          Sandbox.getOrCreate({
-            ...baseParams,
-            name: templateName,
-            persistent: true,
-            snapshotExpiration: baseParams.snapshotExpiration ?? 0,
-            onCreate: async sbx => {
-              await onFirstCreate(new VercelSandboxSession(sbx), {
-                abortSignal: options?.abortSignal,
-              });
-            },
-            ...(options?.abortSignal ? { signal: options.abortSignal } : {}),
-          }),
-      });
-
-      let resolvedId: string | undefined = template.currentSnapshotId;
-      if (resolvedId == null) {
-        const stopResult = await withVercelSandboxAuthenticationError({
-          settings: this.settings,
-          operation: () =>
-            template.stop(
-              options?.abortSignal
-                ? { signal: options.abortSignal }
-                : undefined,
-            ),
-        });
-        resolvedId = stopResult.snapshot?.id;
-        if (resolvedId == null) {
-          resolvedId = await withVercelSandboxAuthenticationError({
-            settings: this.settings,
-            operation: () =>
-              pollForTemplateSnapshot({
-                name: templateName,
-                lookupParams: getSandboxLookupParams(baseParams),
-                abortSignal: options?.abortSignal,
-              }),
-          });
-        }
-      }
-
-      cache.set(templateName, resolvedId);
-      snapshotId = resolvedId;
-    }
-
-    const {
-      runtime: _ignoredRuntime,
-      image: _ignoredImage,
-      source: _ignoredSource,
-      persistent: _ignoredPersistent,
-      ...forkParams
-    } = baseParams;
-
-    const fork = await withVercelSandboxAuthenticationError({
-      settings: this.settings,
-      operation: () =>
-        Sandbox.create({
-          ...forkParams,
-          source: { type: 'snapshot', snapshotId },
-          ...sessionNameOverride,
-          ...(options?.abortSignal ? { signal: options.abortSignal } : {}),
-        }),
-    });
-    return new VercelNetworkSandboxSession({
-      sandbox: fork,
-      ownsLifecycle: true,
-    });
-  };
-
-  resumeSession = async (options: {
-    sessionId: string;
-    abortSignal?: AbortSignal;
-  }): Promise<HarnessV1NetworkSandboxSession> => {
-    options.abortSignal?.throwIfAborted();
+type VercelLookupSettings = DistributiveOmit<
+  NonNullable<Parameters<typeof Sandbox.get>[0]>,
+  'name' | 'resume'
+> & {
+  name?: never;
+  resume?: never;
+};
 
-    // Wrap-existing case: caller owns the sandbox. Same session as createSession.
-    if ('sandbox' in this.settings && this.settings.sandbox != null) {
-      return new VercelNetworkSandboxSession({
-        sandbox: this.settings.sandbox,
-        ownsLifecycle: false,
-      });
-    }
+export type VercelNetworkSandboxSessionResumeOptions = Prettify<
+  HarnessV1SandboxSessionResumeOptions<VercelLookupSettings>
+>;
 
+export {
+  DEFAULT_SANDBOX_TIMEOUT_MS,
+  DEFAULT_SANDBOX_RUNTIME,
+  VERCEL_PROVIDER_ID,
+  getSandboxLookupParams,
+  hasExplicitSandboxEnvironment,
+  pollForTemplateSnapshot,
+  withVercelSandboxAuthenticationError,
+} from './utils';
+export type { BaseCreateSandboxParams } from './utils';
+
+export async function createVercelNetworkSandboxSession(
+  options: VercelNetworkSandboxSessionCreateOptions = {},
+): Promise<HarnessV1NetworkSandboxSession> {
+  if ('sandbox' in options) {
+    throw new Error(
+      'createVercelNetworkSandboxSession: use createVercelNetworkSandboxSessionFromNativeSandbox for an existing sandbox.',
+    );
+  }
+  const {
+    template,
+    abortSignal,
+    sandboxId,
+    sandbox: _sandbox,
+    ...nativeOptions
+  } = options;
+  const effectiveSignal = abortSignal ?? nativeOptions.signal;
+  effectiveSignal?.throwIfAborted();
+  const { name, ...creationOptions } = nativeOptions;
+  if (sandboxId != null && name != null && sandboxId !== name) {
+    throw new Error(
+      'createVercelNetworkSandboxSession: sandboxId and name must match when both are provided.',
+    );
+  }
+  const liveName = sandboxId ?? name;
+  const baseParams = withDefaultSandboxSettings({
+    ...creationOptions,
+    ...(effectiveSignal ? { signal: effectiveSignal } : {}),
+  } as BaseCreateSandboxParams);
+  const settings = options;
+  if (template == null) {
     const sandbox = await withVercelSandboxAuthenticationError({
-      settings: this.settings,
+      settings,
       operation: () =>
-        Sandbox.get({
-          ...getSandboxLookupParams(this.settings),
-          name: sessionSandboxName(options.sessionId),
-          ...(options.abortSignal ? { signal: options.abortSignal } : {}),
+        Sandbox.create({
+          ...baseParams,
+          ...(liveName != null ? { name: liveName } : {}),
         }),
     });
-    return new VercelNetworkSandboxSession({ sandbox, ownsLifecycle: true });
-  };
-}
-
-/**
- * Base shape of `Sandbox.create` params extracted from the union (excludes
- * the `source: { type: 'snapshot' }` variant) so all create-time fields
- * are typed as present.
- */
-type BaseCreateSandboxParams = Exclude<
-  VercelSandboxCreateParams,
-  { source: { type: 'snapshot'; snapshotId: string } }
->;
-
-const SNAPSHOT_CACHE_KEY = Symbol.for(
-  'ai-sdk.harness.vercel-template-snapshots',
-);
-
-type SnapshotCache = Map<string, string>;
-type SandboxLookupParams = {
-  fetch?: typeof fetch;
-  projectId?: string;
-  teamId?: string;
-  token?: string;
-};
-
-function getSandboxLookupParams(
-  settings: VercelSandboxSettings,
-): SandboxLookupParams {
-  if ('sandbox' in settings && settings.sandbox != null) {
-    return {};
+    return createVercelNetworkSandboxSessionFromNativeSandbox(sandbox);
   }
 
-  const { fetch, projectId, teamId, token } = settings as SandboxLookupParams;
-  return {
-    ...(fetch ? { fetch } : {}),
-    ...(projectId ? { projectId } : {}),
-    ...(teamId ? { teamId } : {}),
-    ...(token ? { token } : {}),
-  };
-}
-
-function getSnapshotCache(): SnapshotCache {
-  const globals = globalThis as {
-    [SNAPSHOT_CACHE_KEY]?: SnapshotCache;
-  };
-  let cache = globals[SNAPSHOT_CACHE_KEY];
-  if (cache == null) {
-    cache = new Map();
-    globals[SNAPSHOT_CACHE_KEY] = cache;
-  }
-  return cache;
-}
-
-const VERCEL_SANDBOX_AUTHENTICATION_MESSAGE =
-  'Vercel Sandbox authentication failed. Set VERCEL_OIDC_TOKEN, or pass token, teamId, and projectId to createVercelSandbox(), then verify that they can access Vercel Sandbox.';
-
-async function withVercelSandboxAuthenticationError<T>({
-  settings,
-  operation,
-}: {
-  settings: VercelSandboxSettings;
-  operation: () => Promise<T>;
-}): Promise<T> {
-  try {
-    return await operation();
-  } catch (error) {
-    if (
-      !isVercelSandboxAuthenticationFailure({
-        error,
-        hasConfiguredCredentials: hasConfiguredCredentials(settings),
-      })
-    ) {
-      throw error;
-    }
-    throw new HarnessSandboxAuthenticationError({
-      message: VERCEL_SANDBOX_AUTHENTICATION_MESSAGE,
-      sandboxProviderId: VERCEL_PROVIDER_ID,
-      cause: error,
-    });
-  }
+  const selection =
+    'source' in baseParams && baseParams.source != null
+      ? baseParams.source
+      : 'image' in baseParams && baseParams.image != null
+        ? { image: baseParams.image }
+        : { runtime: baseParams.runtime };
+  const material = JSON.stringify([2, template.identity, selection]);
+  const digest = new Uint8Array(
+    await crypto.subtle.digest('SHA-256', new TextEncoder().encode(material)),
+  );
+  const templateName = `ai-sdk-harness-v2-${Array.from(digest.slice(0, 12), byte => byte.toString(16).padStart(2, '0')).join('')}`;
+  const snapshotId = await withVercelSandboxAuthenticationError({
+    settings,
+    operation: () =>
+      ensureTemplateSnapshot({
+        baseParams,
+        templateName,
+        lookupParams: getSandboxLookupParams(baseParams),
+        abortSignal: effectiveSignal,
+        onCreate: async sandbox => {
+          await template.prepare({
+            session: createVercelSandboxSessionFromNativeSandbox(sandbox),
+            abortSignal: effectiveSignal,
+          });
+        },
+      }),
+  });
+  const liveSandbox = await withVercelSandboxAuthenticationError({
+    settings,
+    operation: () =>
+      createLiveSandboxFromSnapshot({
+        baseParams,
+        snapshotId,
+        liveName,
+      }),
+  });
+  return createVercelNetworkSandboxSessionFromNativeSandbox(liveSandbox);
 }
 
-function hasConfiguredCredentials(settings: VercelSandboxSettings): boolean {
-  if (process.env.VERCEL_OIDC_TOKEN) return true;
-  if ('sandbox' in settings && settings.sandbox != null) return true;
-  const { token, teamId, projectId } = getSandboxLookupParams(settings);
-  return Boolean(token && teamId && projectId);
+export async function resumeVercelNetworkSandboxSession(
+  options: VercelNetworkSandboxSessionResumeOptions,
+): Promise<HarnessV1NetworkSandboxSession> {
+  const {
+    sandboxId,
+    abortSignal,
+    signal,
+    name: _name,
+    resume: _resume,
+    ...lookupOptions
+  } = options;
+  const effectiveSignal = abortSignal ?? signal;
+  effectiveSignal?.throwIfAborted();
+  const sandbox = await withVercelSandboxAuthenticationError({
+    settings: options,
+    operation: () =>
+      Sandbox.get({
+        ...lookupOptions,
+        name: sandboxId,
+        resume: true,
+        ...(effectiveSignal ? { signal: effectiveSignal } : {}),
+      }),
+  });
+  return createVercelNetworkSandboxSessionFromNativeSandbox(sandbox);
 }
 
-function isVercelSandboxAuthenticationFailure({
-  error,
-  hasConfiguredCredentials,
-}: {
-  error: unknown;
-  hasConfiguredCredentials: boolean;
-}): boolean {
-  const seen = new Set<unknown>();
-  let current = error;
-  while (current != null && !seen.has(current)) {
-    seen.add(current);
-    if (typeof current === 'object') {
-      const candidate = current as {
-        name?: unknown;
-        message?: unknown;
-        code?: unknown;
-        cause?: unknown;
-        response?: { status?: unknown; statusCode?: unknown };
-      };
-      if (
-        candidate.response?.status === 401 ||
-        candidate.response?.status === 403 ||
-        candidate.response?.statusCode === 401 ||
-        candidate.response?.statusCode === 403
-      ) {
-        return true;
-      }
-      if (
-        typeof candidate.name === 'string' &&
-        VERCEL_AUTHENTICATION_ERROR_NAMES.has(candidate.name)
-      ) {
-        return true;
-      }
-      if (
-        typeof candidate.message === 'string' &&
-        VERCEL_AUTHENTICATION_ERROR_MESSAGE.test(candidate.message)
-      ) {
-        return true;
-      }
-      if (
-        !hasConfiguredCredentials &&
-        candidate.code === 'ERR_INVALID_ARG_TYPE' &&
-        typeof candidate.message === 'string' &&
-        candidate.message.includes('"path" argument') &&
-        candidate.message.includes('Received undefined')
-      ) {
-        return true;
-      }
-      current = candidate.cause;
-      continue;
-    }
-    break;
-  }
-  return false;
+export function createVercelSandboxSessionFromNativeSandbox(
+  nativeSandbox: VercelNativeSandboxSession,
+): SandboxSession {
+  return new VercelSandboxSession(nativeSandbox);
 }
 
-const VERCEL_AUTHENTICATION_ERROR_NAMES = new Set([
-  'AccessTokenMissingError',
-  'LocalOidcContextError',
-  'OAuthError',
-  'RefreshAccessTokenFailedError',
-  'VercelOidcContextError',
-  'VercelOidcTokenError',
-]);
-
-const VERCEL_AUTHENTICATION_ERROR_MESSAGE =
-  /Could not get credentials from OIDC context|No authentication found|Failed to (?:retrieve|refresh) authentication token|Missing credentials parameters to access the Vercel API|Authentication failed/i;
-
-async function pollForTemplateSnapshot({
-  name,
-  lookupParams,
-  abortSignal,
-}: {
-  name: string;
-  lookupParams: ReturnType<typeof getSandboxLookupParams>;
-  abortSignal: AbortSignal | undefined;
-}): Promise<string> {
-  const deadline = Date.now() + SNAPSHOT_POLL_TIMEOUT_MS;
-  while (Date.now() < deadline) {
-    abortSignal?.throwIfAborted();
-    const refreshed = await Sandbox.get({
-      ...lookupParams,
-      name,
-      resume: false,
-      ...(abortSignal ? { signal: abortSignal } : {}),
-    });
-    if (refreshed.currentSnapshotId) {
-      return refreshed.currentSnapshotId;
-    }
-    await new Promise<void>(resolve =>
-      setTimeout(resolve, SNAPSHOT_POLL_INTERVAL_MS),
-    );
-  }
-  throw new Error(
-    `Timed out waiting for snapshot of template "${name}" to publish.`,
-  );
+export function createVercelNetworkSandboxSessionFromNativeSandbox(
+  nativeSandbox: VercelNativeSandboxSession,
+): HarnessV1NetworkSandboxSession {
+  return new VercelNetworkSandboxSession({
+    sandbox: nativeSandbox,
+    ownsLifecycle: true,
+  });
 }