@ai-sdk/sandbox-vercel 1.0.124 → 1.0.126

package/src/utils.ts

@@ -0,0 +1,313 @@
+import { HarnessSandboxAuthenticationError } from '@ai-sdk/harness';
+import { Sandbox } from '@vercel/sandbox';
+
+/**
+ * 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`.
+ */
+export 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.
+ */
+export 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.
+ */
+export type VercelSandboxCreateParams = DistributiveOmit<
+  NonNullable<Parameters<typeof Sandbox.create>[0]>,
+  'onResume'
+>;
+
+/**
+ * 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.
+ */
+export type BaseCreateSandboxParams = Exclude<
+  VercelSandboxCreateParams,
+  { source: { type: 'snapshot'; snapshotId: string } }
+>;
+
+export const VERCEL_PROVIDER_ID = 'vercel-sandbox';
+
+/**
+ * 30 minutes. The `@vercel/sandbox` SDK defaults to 5 minutes which is
+ * too short for multi-step workflows — the VM expires between steps.
+ */
+export const DEFAULT_SANDBOX_TIMEOUT_MS = 30 * 60 * 1_000;
+export const DEFAULT_SANDBOX_RUNTIME = 'node24';
+
+const SNAPSHOT_POLL_INTERVAL_MS = 500;
+const SNAPSHOT_POLL_TIMEOUT_MS = 30_000;
+
+type SandboxLookupParams = {
+  fetch?: typeof fetch;
+  projectId?: string;
+  teamId?: string;
+  token?: string;
+};
+
+type VercelSandboxAuthenticationSettings = SandboxLookupParams & {
+  sandbox?: Sandbox;
+};
+
+export function getSandboxLookupParams(
+  settings: VercelSandboxAuthenticationSettings,
+): SandboxLookupParams {
+  if ('sandbox' in settings && settings.sandbox != null) {
+    return {};
+  }
+
+  const { fetch, projectId, teamId, token } = settings as SandboxLookupParams;
+  return {
+    ...(fetch ? { fetch } : {}),
+    ...(projectId ? { projectId } : {}),
+    ...(teamId ? { teamId } : {}),
+    ...(token ? { token } : {}),
+  };
+}
+
+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.';
+
+export async function withVercelSandboxAuthenticationError<T>({
+  settings,
+  operation,
+}: {
+  settings: VercelSandboxAuthenticationSettings;
+  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,
+    });
+  }
+}
+
+function hasConfiguredCredentials(
+  settings: VercelSandboxAuthenticationSettings,
+): 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);
+}
+
+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;
+}
+
+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;
+
+export 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 withDefaultSandboxSettings(
+  createParams: BaseCreateSandboxParams,
+): BaseCreateSandboxParams {
+  return {
+    ...(hasExplicitSandboxEnvironment(createParams)
+      ? {}
+      : { runtime: DEFAULT_SANDBOX_RUNTIME }),
+    ...createParams,
+    timeout: createParams.timeout ?? DEFAULT_SANDBOX_TIMEOUT_MS,
+  } as BaseCreateSandboxParams;
+}
+
+export async function ensureTemplateSnapshot({
+  baseParams,
+  templateName,
+  onCreate,
+  lookupParams,
+  abortSignal,
+  snapshotCache,
+}: {
+  baseParams: BaseCreateSandboxParams;
+  templateName: string;
+  onCreate: (sandbox: Sandbox) => Promise<void>;
+  lookupParams: SandboxLookupParams;
+  abortSignal?: AbortSignal;
+  snapshotCache?: Map<string, string>;
+}): Promise<string> {
+  const cachedSnapshotId = snapshotCache?.get(templateName);
+  if (cachedSnapshotId != null) {
+    return cachedSnapshotId;
+  }
+
+  const prepared = await Sandbox.getOrCreate({
+    ...baseParams,
+    name: templateName,
+    persistent: true,
+    snapshotExpiration: baseParams.snapshotExpiration ?? 0,
+    onCreate,
+    ...(abortSignal ? { signal: abortSignal } : {}),
+  });
+  let snapshotId = prepared.currentSnapshotId;
+  if (snapshotId == null) {
+    const stopped = await prepared.stop(
+      abortSignal ? { signal: abortSignal } : undefined,
+    );
+    snapshotId =
+      stopped.snapshot?.id ??
+      (await pollForTemplateSnapshot({
+        name: templateName,
+        lookupParams,
+        abortSignal,
+      }));
+  }
+  snapshotCache?.set(templateName, snapshotId);
+  return snapshotId;
+}
+
+export function createLiveSandboxFromSnapshot({
+  baseParams,
+  snapshotId,
+  liveName,
+  abortSignal,
+}: {
+  baseParams: BaseCreateSandboxParams;
+  snapshotId: string;
+  liveName?: string;
+  abortSignal?: AbortSignal;
+}): Promise<Sandbox> {
+  const {
+    runtime: _runtime,
+    image: _image,
+    source: _source,
+    persistent: _persistent,
+    ...forkParams
+  } = baseParams;
+  return Sandbox.create({
+    ...forkParams,
+    source: { type: 'snapshot', snapshotId },
+    ...(liveName != null ? { name: liveName } : {}),
+    ...(abortSignal ? { signal: abortSignal } : {}),
+  });
+}
+
+export async function pollForTemplateSnapshot({
+  name,
+  lookupParams,
+  abortSignal,
+}: {
+  name: string;
+  lookupParams: SandboxLookupParams;
+  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.`,
+  );
+}

package/src/vercel-legacy-sandbox-provider.ts

@@ -0,0 +1,221 @@
+import type {
+  HarnessV1NetworkSandboxSession,
+  HarnessV1SandboxProvider,
+} 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 {
+  VERCEL_PROVIDER_ID,
+  createLiveSandboxFromSnapshot,
+  ensureTemplateSnapshot,
+  getSandboxLookupParams,
+  withVercelSandboxAuthenticationError,
+  withDefaultSandboxSettings,
+  type BaseCreateSandboxParams,
+} from './utils';
+
+type VercelSandboxCreateParams = NonNullable<
+  Parameters<typeof Sandbox.create>[0]
+>;
+
+type DistributiveOmit<T, K extends keyof any> = T extends unknown
+  ? Omit<T, K>
+  : never;
+
+type VercelSandboxCreationSettings = DistributiveOmit<
+  VercelSandboxCreateParams,
+  'onResume'
+> & {
+  sandbox?: never;
+  name?: string;
+};
+
+/**
+ * Settings for `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.
+ *
+ * @deprecated Use `VercelNetworkSandboxSessionCreateOptions` for new sessions.
+ */
+export type VercelSandboxSettings =
+  | { sandbox: Sandbox }
+  | VercelSandboxCreationSettings;
+
+const SESSION_NAME_PREFIX = 'ai-sdk-harness-session';
+
+function sessionSandboxName(sessionId: string): string {
+  return `${SESSION_NAME_PREFIX}-${sessionId}`;
+}
+
+/** @deprecated Use `createVercelNetworkSandboxSession` instead. */
+export function createVercelSandbox(
+  settings: VercelSandboxSettings = {} as VercelSandboxSettings,
+): HarnessV1SandboxProvider {
+  console.warn(
+    'createVercelSandbox is deprecated. Use createVercelNetworkSandboxSession and HarnessAgent.createSession({ sandboxSession }) instead.',
+  );
+  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).
+ */
+/** @deprecated Use `createVercelNetworkSandboxSession` instead. */
+export class VercelSandboxProvider implements HarnessV1SandboxProvider {
+  readonly specificationVersion = 'harness-sandbox-v1' as const;
+  readonly providerId = VERCEL_PROVIDER_ID;
+
+  constructor(private readonly settings: VercelSandboxSettings) {
+    console.warn(
+      'VercelSandboxProvider is deprecated. Use createVercelNetworkSandboxSession instead.',
+    );
+  }
+
+  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 = withDefaultSandboxSettings(
+      createParams 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 ?? `ai-sdk-harness-${identity}`;
+    const snapshotId = await withVercelSandboxAuthenticationError({
+      settings: this.settings,
+      operation: () =>
+        ensureTemplateSnapshot({
+          baseParams,
+          templateName,
+          lookupParams: getSandboxLookupParams(baseParams),
+          abortSignal: options?.abortSignal,
+          snapshotCache: getSnapshotCache(),
+          onCreate: async sbx => {
+            await onFirstCreate(new VercelSandboxSession(sbx), {
+              abortSignal: options?.abortSignal,
+            });
+          },
+        }),
+    });
+
+    const fork = await withVercelSandboxAuthenticationError({
+      settings: this.settings,
+      operation: () =>
+        createLiveSandboxFromSnapshot({
+          baseParams,
+          snapshotId,
+          liveName: sessionNameOverride.name,
+          abortSignal: options?.abortSignal,
+        }),
+    });
+    return new VercelNetworkSandboxSession({
+      sandbox: fork,
+      ownsLifecycle: true,
+    });
+  };
+
+  resumeSession = async (options: {
+    sessionId: string;
+    abortSignal?: AbortSignal;
+  }): Promise<HarnessV1NetworkSandboxSession> => {
+    options.abortSignal?.throwIfAborted();
+
+    // 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,
+      });
+    }
+
+    const sandbox = await withVercelSandboxAuthenticationError({
+      settings: this.settings,
+      operation: () =>
+        Sandbox.get({
+          ...getSandboxLookupParams(this.settings),
+          name: sessionSandboxName(options.sessionId),
+          ...(options.abortSignal ? { signal: options.abortSignal } : {}),
+        }),
+    });
+    return new VercelNetworkSandboxSession({ sandbox, ownsLifecycle: true });
+  };
+}
+
+const SNAPSHOT_CACHE_KEY = Symbol.for(
+  'ai-sdk.harness.vercel-template-snapshots',
+);
+
+type SnapshotCache = Map<string, string>;
+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;
+}

package/src/vercel-network-sandbox-session.ts

@@ -14,11 +14,11 @@ const VERCEL_PROVIDER_ID = 'vercel-sandbox';
 
 /**
  * `HarnessV1NetworkSandboxSession` backed by a `@vercel/sandbox` `Sandbox`. The
- * provider's `create()` returns one of these. It extends
- * {@link VercelSandboxSession} with the infra surface (ports, lifecycle,
- * network policy). It owns the sandbox's lifecycle only when the provider
- * created it; when the provider was given an existing sandbox, `stop()` and
- * `destroy()` are no-ops (caller retains ownership).
+ * native adaptation and sandbox creation functions return one of these. It
+ * extends {@link VercelSandboxSession} with ports, lifecycle, and network
+ * policy. Explicit `stop()` and `destroy()` calls delegate to the native
+ * sandbox unless the session was wrapped through the compatibility provider's
+ * existing-sandbox path, where those calls are intentionally no-ops.
  */
 export class VercelNetworkSandboxSession
   extends VercelSandboxSession

package/src/vercel-sandbox-session.ts

@@ -1,8 +1,8 @@
 import { posix } from 'node:path';
 import {
   extractLines,
-  type Experimental_SandboxSession,
-  type Experimental_SandboxProcess,
+  type Experimental_SandboxSession as SandboxSession,
+  type Experimental_SandboxProcess as SandboxProcess,
 } from '@ai-sdk/provider-utils';
 import type { Sandbox, Command } from '@vercel/sandbox';
 
@@ -13,7 +13,7 @@ import type { Sandbox, Command } from '@vercel/sandbox';
  * constructed directly by consumers. The network sandbox session owns the
  * lifetime of the underlying sandbox.
  */
-export class VercelSandboxSession implements Experimental_SandboxSession {
+export class VercelSandboxSession implements SandboxSession {
   constructor(protected readonly sandbox: Sandbox) {}
 
   get description(): string {
@@ -66,7 +66,7 @@ export class VercelSandboxSession implements Experimental_SandboxSession {
     workingDirectory?: string;
     env?: Record<string, string>;
     abortSignal?: AbortSignal;
-  }): Promise<Experimental_SandboxProcess> {
+  }): Promise<SandboxProcess> {
     abortSignal?.throwIfAborted();
 
     const live = await this.sandbox.runCommand({
@@ -201,7 +201,7 @@ export class VercelSandboxSession implements Experimental_SandboxSession {
 function createSandboxProcess(
   command: Command,
   abortSignal: AbortSignal | undefined,
-): Experimental_SandboxProcess {
+): SandboxProcess {
   const encoder = new TextEncoder();
   const controllers: {
     stdout?: ReadableStreamDefaultController<Uint8Array>;