@ai-sdk/sandbox-vercel 0.0.0 → 1.0.0-canary.10

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# @ai-sdk/sandbox-vercel
+
+## 1.0.0-canary.10
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.10
+
+## 1.0.0-canary.9
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.9
+
+## 1.0.0-canary.8
+
+### Patch Changes
+
+- Updated dependencies [aae0138]
+  - @ai-sdk/harness@1.0.0-canary.8
+
+## 1.0.0-canary.7
+
+### Patch Changes
+
+- e551763: fix(harness): avoid using peer dependencies for underlying harness and sandbox SDKs
+- Updated dependencies [3d87086]
+- Updated dependencies [aeda373]
+- Updated dependencies [1ea15a3]
+- Updated dependencies [375fdd7]
+- Updated dependencies [b4507d5]
+  - @ai-sdk/harness@1.0.0-canary.7
+  - @ai-sdk/provider-utils@5.0.0-canary.48
+
+## 1.0.0-canary.6
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.6
+
+## 1.0.0-canary.5
+
+### Patch Changes
+
+- Updated dependencies [d77bed4]
+- Updated dependencies [bae5e2b]
+  - @ai-sdk/harness@1.0.0-canary.5
+  - @ai-sdk/provider-utils@5.0.0-canary.47
+
+## 1.0.0-canary.4
+
+### Patch Changes
+
+- Updated dependencies [3d9a50c]
+  - @ai-sdk/harness@1.0.0-canary.4
+
+## 1.0.0-canary.3
+
+### Patch Changes
+
+- Updated dependencies [21d3d60]
+  - @ai-sdk/harness@1.0.0-canary.3
+
+## 1.0.0-canary.2
+
+### Patch Changes
+
+- 6c7a3e5: Start the `1.0.0` canary release line for the experimental harness and sandbox packages. They were unintentionally published as `0.0.0-canary.*` because they were scaffolded with a `0.0.0-canary.0` premajor version, which semver could not advance past on a major bump.
+- Updated dependencies [6c7a3e5]
+  - @ai-sdk/harness@1.0.0-canary.2
+
+## 0.0.0-canary.1
+
+### Major Changes
+
+- 9d6dbe0: feat(harness): add sandbox specific expansion for harness abstraction, add `sandbox-just-bash` and `sandbox-vercel`
+
+### Patch Changes
+
+- Updated dependencies [9d6dbe0]
+  - @ai-sdk/harness@0.0.0-canary.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,76 @@
+# AI SDK - Vercel Sandbox
+
+_This package is **experimental**._
+
+`HarnessV1SandboxProvider` implementation for [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox).
+
+## Setup
+
+```bash
+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()`.
+
+```ts
+import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
+
+const vercelSandbox = createVercelSandbox({
+  runtime: 'node24',
+  ports: [3000],
+});
+
+const networkSandboxSession = await vercelSandbox.createSession();
+const sandboxSession = networkSandboxSession.restricted();
+
+await sandboxSession.writeTextFile({ path: 'hello.txt', content: 'hi' });
+
+const { stdout } = await sandboxSession.run({
+  command: 'cat hello.txt',
+});
+console.log(stdout); // "hi"
+await networkSandboxSession.stop();
+```
+
+`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`, `getPortUrl`, `setNetworkPolicy`, `stop`) that only the harness should reach for.
+
+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'] },
+  },
+});
+```
+
+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'],
+});
+```
+
+`HarnessV1NetworkPolicy` is the harness-level abstraction used here. The provider translates it to `@vercel/sandbox`'s native `NetworkPolicy` for enforcement.

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import { HarnessV1SandboxProvider, HarnessV1NetworkSandboxSession } from '@ai-sdk/harness';
+import { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+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`.
+ */
+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:
+ *
+ * - `{ sandbox }` — wrap an already-created `@vercel/sandbox` `Sandbox`. The
+ *   caller owns its lifecycle; the provider's `stop()` and `destroy()` are
+ *   no-ops. Optionally declare `bridgePorts` to give the harness a port pool to
+ *   lease from for concurrent sessions on the same provided sandbox.
+ * - {@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.
+ */
+type VercelSandboxSettings = {
+    sandbox: Sandbox;
+    bridgePorts?: ReadonlyArray<number>;
+} | (VercelSandboxCreateParams & {
+    sandbox?: never;
+    name?: string;
+});
+declare function createVercelSandbox(settings?: VercelSandboxSettings): HarnessV1SandboxProvider;
+/**
+ * `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).
+ */
+declare class VercelSandboxProvider implements HarnessV1SandboxProvider {
+    private readonly settings;
+    readonly specificationVersion: "harness-sandbox-v1";
+    readonly providerId = "vercel-sandbox";
+    readonly bridgePorts?: ReadonlyArray<number>;
+    constructor(settings: VercelSandboxSettings);
+    createSession: (options?: {
+        sessionId?: string;
+        abortSignal?: AbortSignal;
+        identity?: string;
+        onFirstCreate?: (session: Experimental_SandboxSession, opts: {
+            abortSignal?: AbortSignal;
+        }) => Promise<void>;
+    }) => Promise<HarnessV1NetworkSandboxSession>;
+    resumeSession: (options: {
+        sessionId: string;
+        abortSignal?: AbortSignal;
+    }) => Promise<HarnessV1NetworkSandboxSession>;
+}
+
+export { VercelSandboxProvider, type VercelSandboxSettings, createVercelSandbox };