@ai-sdk/sandbox-vercel 1.0.124 → 1.0.126

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ai-sdk/sandbox-vercel
 
+## 1.0.126
+
+### Patch Changes
+
+- 31742b9: feat(harness): refactor sandbox APIs for cleaner separation of concerns from harness layer, more intuitive DX regardless of how your sandbox is configured, and streamlined handling of sandbox templates/snapshots
+- Updated dependencies [af9597b]
+- Updated dependencies [31742b9]
+- Updated dependencies [bc49f78]
+  - @ai-sdk/harness@1.0.126
+  - @ai-sdk/provider-utils@5.0.49
+
+## 1.0.125
+
+### Patch Changes
+
+- Updated dependencies [be877ff]
+  - @ai-sdk/provider-utils@5.0.48
+  - @ai-sdk/harness@1.0.125
+
 ## 1.0.124
 
 ### Patch Changes

package/README.md

@@ -2,7 +2,7 @@
 
 _This package is **experimental**._
 
-`HarnessV1SandboxProvider` implementation for [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox).
+Sandbox session implementation for [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox).
 
 ## Setup
 
@@ -12,21 +12,13 @@ npm i @ai-sdk/sandbox-vercel
 
 ## Usage
 
-The factory is synchronous. The returned provider is stable; the actual `@vercel/sandbox` `Sandbox` is created on demand inside `provider.createSession()`.
-
-When neither `runtime` nor `image` is provided, the adapter uses the legacy
-`node24` runtime on both Vercel Sandbox v2 and v3. Pass `image` explicitly to
-opt into a v3 managed image such as `vercel/sandbox/universal`.
-
 ```ts
-import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
+import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';
 
-const vercelSandbox = createVercelSandbox({
+const networkSandboxSession = await createVercelNetworkSandboxSession({
   runtime: 'node24',
   ports: [3000],
 });
-
-const networkSandboxSession = await vercelSandbox.createSession();
 const sandboxSession = networkSandboxSession.restricted();
 
 await sandboxSession.writeTextFile({ path: 'hello.txt', content: 'hi' });
@@ -35,67 +27,20 @@ const { stdout } = await sandboxSession.run({
   command: 'cat hello.txt',
 });
 console.log(stdout); // "hi"
-await networkSandboxSession.stop();
+await networkSandboxSession.destroy();
 ```
 
-## Authentication
-
-Vercel Sandbox accepts `VERCEL_OIDC_TOKEN`, or explicit `token`, `teamId`, and
-`projectId` settings. For local OIDC authentication, link the application with
-`vercel link`, run `vercel env pull`, and load the generated `.env.local` before
-starting it.
-
-Credential resolution failures throw
-`HarnessSandboxAuthenticationError` from `@ai-sdk/harness` and preserve the
-underlying Vercel SDK error as `cause`.
-
-`networkSandboxSession.restricted()` is typed as `Experimental_SandboxSession`, so it's safe to pass to AI SDK tools that accept `experimental_sandbox`. The network sandbox session itself carries the infra surface (`ports`, `getPortEndpoint`, `setNetworkPolicy`, `setRequestTransformations`, `addRequestTransformations`, `stop`) that only the harness should reach for. `getPortUrl` remains available as a deprecated compatibility wrapper.
+### Use cases
 
-The flat-field settings are aliased directly from `@vercel/sandbox`'s `Sandbox.create` parameters, so every option Vercel supports — including its native `NetworkPolicy` — is available without re-declaration:
-
-```ts
-const sandbox = createVercelSandbox({
-  runtime: 'node24',
-  ports: [3000],
-  timeout: 10 * 60 * 1000,
-  networkPolicy: {
-    allow: ['api.example.com'],
-    subnets: { deny: ['169.254.169.254/32'] },
-  },
-});
-```
+- Create a network sandbox session with `createVercelNetworkSandboxSession()` and pass it to `HarnessAgent.createSession({ sandboxSession })`. For reusable snapshots, pass `template: await agent.getSandboxTemplate()` to the creator function.
+- Set `sandboxId` to name a new sandbox, or persist the returned session's `id`. Creation never resumes an existing sandbox and a conflicting name fails; use `resumeVercelNetworkSandboxSession({ sandboxId })` to reattach.
+- Take a network sandbox session's process-restricted subset with `networkSandboxSession.restricted()` and use it with AI SDK tools that accept `experimental_sandbox`.
+- Adapt an existing native `Sandbox` with `createVercelSandboxSessionFromNativeSandbox(nativeSandbox)` and use it with AI SDK tools that accept `experimental_sandbox`.
 
-To wrap an already-created `@vercel/sandbox` `Sandbox` instead — e.g. when you need credentials or options outside the factory's settings, or you want to share one sandbox across multiple harness sessions — pass it via `sandbox`. Install `@vercel/sandbox` directly if your application imports `Sandbox`. The network sandbox session's `stop()` is a no-op in this case; the caller owns the lifecycle.
-
-```ts
-import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
-import { Sandbox } from '@vercel/sandbox';
-
-const sandbox = createVercelSandbox({
-  sandbox: await Sandbox.create({ runtime: 'node24', ports: [3000] }),
-});
-```
-
-### Mid-session network policy
-
-Once the network sandbox session is alive, the host can update outbound network policy on the running sandbox:
-
-```ts
-await networkSandboxSession.setNetworkPolicy?.({
-  mode: 'custom',
-  allowedHosts: ['api.example.com'],
-  deniedCIDRs: ['169.254.169.254/32'],
-});
-```
+## Authentication
 
-`HarnessV1NetworkPolicy` is the harness-level abstraction used here. The provider translates it to `@vercel/sandbox`'s native `NetworkPolicy` for enforcement.
+Vercel Sandbox accepts `VERCEL_OIDC_TOKEN`, or explicit `token`, `teamId`, and `projectId` settings. For local OIDC authentication, link the application with `vercel link`, run `vercel env pull`, and load the generated `.env.local` before starting it.
 
-### Request transformations and credential brokering
+## Request transformations and credential brokering
 
-Vercel Sandbox supports outbound request transformations for use cases such as
-credential brokering. `setRequestTransformations()` replaces the managed rules,
-while `addRequestTransformations()` adds rules without replacing unrelated
-rules. Re-adding a managed rule with the same request matcher and transformed
-header names refreshes that rule in place, which keeps resumed credential
-brokering idempotent. Network access policies remain authoritative over which
-hosts can be reached.
+Vercel Sandbox supports outbound request transformations for use cases such as credential brokering. `setRequestTransformations()` replaces the managed rules, while `addRequestTransformations()` adds rules without replacing unrelated rules.

package/dist/index.d.ts

@@ -1,34 +1,15 @@
-import { HarnessV1SandboxProvider, HarnessV1NetworkSandboxSession } from '@ai-sdk/harness';
+import { HarnessV1SandboxProvider, HarnessV1NetworkSandboxSession, HarnessV1SandboxSessionCreateOptions, HarnessV1SandboxSessionResumeOptions } from '@ai-sdk/harness';
 import { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
 import { Sandbox } from '@vercel/sandbox';
 
+type VercelSandboxCreateParams$1 = NonNullable<Parameters<typeof Sandbox.create>[0]>;
+type DistributiveOmit$1<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never;
+type VercelSandboxCreationSettings$1 = DistributiveOmit$1<VercelSandboxCreateParams$1, 'onResume'> & {
+    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'>;
-/**
- * Settings for {@link createVercelSandbox}. Two mutually-exclusive shapes:
+ * 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
@@ -38,13 +19,13 @@ type VercelSandboxCreateParams = DistributiveOmit<NonNullable<Parameters<typeof
  *   `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.
  */
 type VercelSandboxSettings = {
     sandbox: Sandbox;
-} | (VercelSandboxCreateParams & {
-    sandbox?: never;
-    name?: string;
-});
+} | VercelSandboxCreationSettings$1;
+/** @deprecated Use `createVercelNetworkSandboxSession` instead. */
 declare function createVercelSandbox(settings?: VercelSandboxSettings): HarnessV1SandboxProvider;
 /**
  * `HarnessV1SandboxProvider` implementation backed by `@vercel/sandbox`.
@@ -52,6 +33,7 @@ declare function createVercelSandbox(settings?: VercelSandboxSettings): HarnessV
  * to a `HarnessAgent` (or call `createSession()` directly if you want raw
  * access to a network sandbox session).
  */
+/** @deprecated Use `createVercelNetworkSandboxSession` instead. */
 declare class VercelSandboxProvider implements HarnessV1SandboxProvider {
     private readonly settings;
     readonly specificationVersion: "harness-sandbox-v1";
@@ -71,4 +53,50 @@ declare class VercelSandboxProvider implements HarnessV1SandboxProvider {
     }) => Promise<HarnessV1NetworkSandboxSession>;
 }
 
-export { VercelSandboxProvider, type VercelSandboxSettings, createVercelSandbox };
+/**
+ * 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 VercelNativeSandboxSession = Sandbox;
+type VercelSandboxCreationSettings = VercelSandboxCreateParams & {
+    sandbox?: never;
+    name?: string;
+};
+type VercelCreationSettings = DistributiveOmit<VercelSandboxCreationSettings, 'sandbox'>;
+type VercelNetworkSandboxSessionCreateOptions = Prettify<HarnessV1SandboxSessionCreateOptions<VercelCreationSettings> & {
+    sandbox?: never;
+}>;
+type VercelLookupSettings = DistributiveOmit<NonNullable<Parameters<typeof Sandbox.get>[0]>, 'name' | 'resume'> & {
+    name?: never;
+    resume?: never;
+};
+type VercelNetworkSandboxSessionResumeOptions = Prettify<HarnessV1SandboxSessionResumeOptions<VercelLookupSettings>>;
+
+declare function createVercelNetworkSandboxSession(options?: VercelNetworkSandboxSessionCreateOptions): Promise<HarnessV1NetworkSandboxSession>;
+declare function resumeVercelNetworkSandboxSession(options: VercelNetworkSandboxSessionResumeOptions): Promise<HarnessV1NetworkSandboxSession>;
+declare function createVercelSandboxSessionFromNativeSandbox(nativeSandbox: VercelNativeSandboxSession): Experimental_SandboxSession;
+declare function createVercelNetworkSandboxSessionFromNativeSandbox(nativeSandbox: VercelNativeSandboxSession): HarnessV1NetworkSandboxSession;
+
+export { type VercelNativeSandboxSession, type VercelNetworkSandboxSessionCreateOptions, type VercelNetworkSandboxSessionResumeOptions, VercelSandboxProvider, type VercelSandboxSettings, createVercelNetworkSandboxSession, createVercelNetworkSandboxSessionFromNativeSandbox, createVercelSandbox, createVercelSandboxSessionFromNativeSandbox, resumeVercelNetworkSandboxSession };