@ai-sdk/sandbox-vercel 0.0.0 → 1.0.0-beta.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,132 @@
1
+ import {
2
+ HarnessCapabilityUnsupportedError,
3
+ type HarnessV1NetworkPolicy,
4
+ type HarnessV1NetworkSandboxSession,
5
+ } from '@ai-sdk/harness';
6
+ import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
7
+ import type { Sandbox, NetworkPolicy } from '@vercel/sandbox';
8
+ import { VercelSandboxSession } from './vercel-sandbox-session';
9
+
10
+ const VERCEL_PROVIDER_ID = 'vercel-sandbox';
11
+
12
+ /**
13
+ * `HarnessV1NetworkSandboxSession` backed by a `@vercel/sandbox` `Sandbox`. The
14
+ * provider's `create()` returns one of these. It extends
15
+ * {@link VercelSandboxSession} with the infra surface (ports, lifecycle,
16
+ * network policy). It owns the sandbox's lifecycle only when the provider
17
+ * created it; when the provider was given an existing sandbox, `stop()` and
18
+ * `destroy()` are no-ops (caller retains ownership).
19
+ */
20
+ export class VercelNetworkSandboxSession
21
+ extends VercelSandboxSession
22
+ implements HarnessV1NetworkSandboxSession
23
+ {
24
+ readonly id: string;
25
+ readonly defaultWorkingDirectory: string;
26
+ private readonly ownsLifecycle: boolean;
27
+
28
+ constructor(input: { sandbox: Sandbox; ownsLifecycle: boolean }) {
29
+ super(input.sandbox);
30
+ this.ownsLifecycle = input.ownsLifecycle;
31
+ this.id = input.sandbox.name;
32
+ this.defaultWorkingDirectory = input.sandbox.currentSession().cwd;
33
+ }
34
+
35
+ get ports(): ReadonlyArray<number> {
36
+ return this.sandbox.routes.map(route => route.port);
37
+ }
38
+
39
+ restricted(): SandboxSession {
40
+ return new VercelSandboxSession(this.sandbox);
41
+ }
42
+
43
+ getPortUrl = async (options: {
44
+ port: number;
45
+ protocol?: 'http' | 'https' | 'ws';
46
+ }): Promise<string> => {
47
+ const exposedPorts = this.ports;
48
+ if (!exposedPorts.includes(options.port)) {
49
+ throw new HarnessCapabilityUnsupportedError({
50
+ harnessId: VERCEL_PROVIDER_ID,
51
+ message: `Port ${options.port} is not exposed on this sandbox. Exposed ports: [${exposedPorts.join(', ')}].`,
52
+ });
53
+ }
54
+ const protocol = options.protocol ?? 'https';
55
+ const url = new URL(this.sandbox.domain(options.port));
56
+ const isSecure = url.protocol === 'https:';
57
+ switch (protocol) {
58
+ case 'http':
59
+ url.protocol = isSecure ? 'https:' : 'http:';
60
+ break;
61
+ case 'https':
62
+ url.protocol = 'https:';
63
+ break;
64
+ case 'ws':
65
+ url.protocol = isSecure ? 'wss:' : 'ws:';
66
+ break;
67
+ }
68
+ return url.toString();
69
+ };
70
+
71
+ setNetworkPolicy = async (policy: HarnessV1NetworkPolicy): Promise<void> => {
72
+ await this.sandbox.update({ networkPolicy: toVercelPolicy(policy) });
73
+ };
74
+
75
+ setPorts = async (
76
+ ports: ReadonlyArray<number>,
77
+ options?: { abortSignal?: AbortSignal },
78
+ ): Promise<void> => {
79
+ await this.sandbox.update(
80
+ { ports: [...ports] },
81
+ options?.abortSignal ? { signal: options.abortSignal } : undefined,
82
+ );
83
+ };
84
+
85
+ stop = async (): Promise<void> => {
86
+ if (!this.ownsLifecycle) return;
87
+ await this.sandbox.stop();
88
+ };
89
+
90
+ destroy = async (): Promise<void> => {
91
+ if (!this.ownsLifecycle) return;
92
+ await this.sandbox.stop().catch(() => {});
93
+ await this.sandbox.delete();
94
+ };
95
+ }
96
+
97
+ export function toVercelPolicy(policy: HarnessV1NetworkPolicy): NetworkPolicy {
98
+ switch (policy.mode) {
99
+ case 'allow-all':
100
+ return 'allow-all';
101
+ case 'deny-all':
102
+ return 'deny-all';
103
+ case 'custom': {
104
+ const result: Extract<NetworkPolicy, { allow?: unknown }> = {};
105
+ const { allowedHosts, allowedCIDRs, deniedCIDRs } = policy;
106
+ if (allowedHosts != null && allowedHosts.length > 0) {
107
+ result.allow = [...allowedHosts];
108
+ }
109
+ if (
110
+ (allowedCIDRs != null && allowedCIDRs.length > 0) ||
111
+ (deniedCIDRs != null && deniedCIDRs.length > 0)
112
+ ) {
113
+ result.subnets = {
114
+ ...(allowedCIDRs != null && allowedCIDRs.length > 0
115
+ ? { allow: [...allowedCIDRs] }
116
+ : {}),
117
+ ...(deniedCIDRs != null && deniedCIDRs.length > 0
118
+ ? { deny: [...deniedCIDRs] }
119
+ : {}),
120
+ };
121
+ }
122
+ if (result.allow == null && result.subnets == null) {
123
+ throw new HarnessCapabilityUnsupportedError({
124
+ harnessId: VERCEL_PROVIDER_ID,
125
+ message:
126
+ 'Custom network policy requires at least one of allowedHosts or allowedCIDRs to be non-empty.',
127
+ });
128
+ }
129
+ return result;
130
+ }
131
+ }
132
+ }
@@ -0,0 +1,299 @@
1
+ import { posix } from 'node:path';
2
+ import {
3
+ extractLines,
4
+ type Experimental_SandboxSession,
5
+ type Experimental_SandboxProcess,
6
+ } from '@ai-sdk/provider-utils';
7
+ import type { Sandbox, Command } from '@vercel/sandbox';
8
+
9
+ /**
10
+ * `Experimental_SandboxSession` implementation backed by a `@vercel/sandbox`
11
+ * `Sandbox` instance. This is the tool-safe surface (file I/O, exec, spawn);
12
+ * it is what `VercelNetworkSandboxSession.restricted()` returns and is not
13
+ * constructed directly by consumers. The network sandbox session owns the
14
+ * lifetime of the underlying sandbox.
15
+ */
16
+ export class VercelSandboxSession implements Experimental_SandboxSession {
17
+ constructor(protected readonly sandbox: Sandbox) {}
18
+
19
+ get description(): string {
20
+ return [
21
+ `Vercel Sandbox (name: ${this.sandbox.name}).`,
22
+ 'Filesystem changes persist for the lifetime of the sandbox.',
23
+ ].join('\n');
24
+ }
25
+
26
+ async run({
27
+ command,
28
+ workingDirectory,
29
+ env,
30
+ abortSignal,
31
+ }: {
32
+ command: string;
33
+ workingDirectory?: string;
34
+ env?: Record<string, string>;
35
+ abortSignal?: AbortSignal;
36
+ }): Promise<{ exitCode: number; stdout: string; stderr: string }> {
37
+ abortSignal?.throwIfAborted();
38
+
39
+ const finished = await this.sandbox.runCommand({
40
+ cmd: 'bash',
41
+ args: ['-c', command],
42
+ ...(workingDirectory !== undefined ? { cwd: workingDirectory } : {}),
43
+ ...(env !== undefined ? { env } : {}),
44
+ ...(abortSignal !== undefined ? { signal: abortSignal } : {}),
45
+ });
46
+
47
+ const [stdout, stderr] = await Promise.all([
48
+ finished.stdout(),
49
+ finished.stderr(),
50
+ ]);
51
+
52
+ return {
53
+ exitCode: finished.exitCode,
54
+ stdout,
55
+ stderr,
56
+ };
57
+ }
58
+
59
+ async spawn({
60
+ command,
61
+ workingDirectory,
62
+ env,
63
+ abortSignal,
64
+ }: {
65
+ command: string;
66
+ workingDirectory?: string;
67
+ env?: Record<string, string>;
68
+ abortSignal?: AbortSignal;
69
+ }): Promise<Experimental_SandboxProcess> {
70
+ abortSignal?.throwIfAborted();
71
+
72
+ const live = await this.sandbox.runCommand({
73
+ cmd: 'bash',
74
+ args: ['-c', command],
75
+ detached: true,
76
+ ...(workingDirectory !== undefined ? { cwd: workingDirectory } : {}),
77
+ ...(env !== undefined ? { env } : {}),
78
+ ...(abortSignal !== undefined ? { signal: abortSignal } : {}),
79
+ });
80
+
81
+ return createSandboxProcess(live, abortSignal);
82
+ }
83
+
84
+ async readFile({
85
+ path,
86
+ abortSignal,
87
+ }: {
88
+ path: string;
89
+ abortSignal?: AbortSignal;
90
+ }): Promise<ReadableStream<Uint8Array> | null> {
91
+ const bytes = await this.readBinaryFile({ path, abortSignal });
92
+ if (bytes == null) return null;
93
+ return bytesToStream(bytes);
94
+ }
95
+
96
+ async readBinaryFile({
97
+ path,
98
+ abortSignal,
99
+ }: {
100
+ path: string;
101
+ abortSignal?: AbortSignal;
102
+ }): Promise<Uint8Array | null> {
103
+ abortSignal?.throwIfAborted();
104
+ try {
105
+ const buffer = await this.sandbox.readFileToBuffer(
106
+ { path },
107
+ abortSignal ? { signal: abortSignal } : undefined,
108
+ );
109
+ if (buffer == null) return null;
110
+ return new Uint8Array(
111
+ buffer.buffer,
112
+ buffer.byteOffset,
113
+ buffer.byteLength,
114
+ );
115
+ } catch (error) {
116
+ if (isFileNotFoundError(error)) return null;
117
+ throw error;
118
+ }
119
+ }
120
+
121
+ async readTextFile({
122
+ path,
123
+ encoding = 'utf-8',
124
+ startLine,
125
+ endLine,
126
+ abortSignal,
127
+ }: {
128
+ path: string;
129
+ encoding?: string;
130
+ startLine?: number;
131
+ endLine?: number;
132
+ abortSignal?: AbortSignal;
133
+ }): Promise<string | null> {
134
+ const bytes = await this.readBinaryFile({ path, abortSignal });
135
+ if (bytes == null) return null;
136
+ const text = Buffer.from(bytes).toString(encoding as BufferEncoding);
137
+ return extractLines({ text, startLine, endLine });
138
+ }
139
+
140
+ async writeFile({
141
+ path,
142
+ content,
143
+ abortSignal,
144
+ }: {
145
+ path: string;
146
+ content: ReadableStream<Uint8Array>;
147
+ abortSignal?: AbortSignal;
148
+ }): Promise<void> {
149
+ const bytes = await collectStream(content);
150
+ await this.writeBinaryFile({ path, content: bytes, abortSignal });
151
+ }
152
+
153
+ async writeBinaryFile({
154
+ path,
155
+ content,
156
+ abortSignal,
157
+ }: {
158
+ path: string;
159
+ content: Uint8Array;
160
+ abortSignal?: AbortSignal;
161
+ }): Promise<void> {
162
+ abortSignal?.throwIfAborted();
163
+ const parent = posix.dirname(path);
164
+ if (parent && parent !== '.' && parent !== '/') {
165
+ await this.sandbox.runCommand({
166
+ cmd: 'mkdir',
167
+ args: ['-p', parent],
168
+ ...(abortSignal !== undefined ? { signal: abortSignal } : {}),
169
+ });
170
+ }
171
+ await this.sandbox.writeFiles(
172
+ [{ path, content }],
173
+ abortSignal ? { signal: abortSignal } : undefined,
174
+ );
175
+ }
176
+
177
+ async writeTextFile({
178
+ path,
179
+ content,
180
+ encoding = 'utf-8',
181
+ abortSignal,
182
+ }: {
183
+ path: string;
184
+ content: string;
185
+ encoding?: string;
186
+ abortSignal?: AbortSignal;
187
+ }): Promise<void> {
188
+ const buffer = Buffer.from(content, encoding as BufferEncoding);
189
+ await this.writeBinaryFile({
190
+ path,
191
+ content: new Uint8Array(
192
+ buffer.buffer,
193
+ buffer.byteOffset,
194
+ buffer.byteLength,
195
+ ),
196
+ abortSignal,
197
+ });
198
+ }
199
+ }
200
+
201
+ function createSandboxProcess(
202
+ command: Command,
203
+ abortSignal: AbortSignal | undefined,
204
+ ): Experimental_SandboxProcess {
205
+ const encoder = new TextEncoder();
206
+ const controllers: {
207
+ stdout?: ReadableStreamDefaultController<Uint8Array>;
208
+ stderr?: ReadableStreamDefaultController<Uint8Array>;
209
+ } = {};
210
+
211
+ const stdout = new ReadableStream<Uint8Array>({
212
+ start(controller) {
213
+ controllers.stdout = controller;
214
+ },
215
+ });
216
+
217
+ const stderr = new ReadableStream<Uint8Array>({
218
+ start(controller) {
219
+ controllers.stderr = controller;
220
+ },
221
+ });
222
+
223
+ const drained = (async () => {
224
+ try {
225
+ const iterator = abortSignal
226
+ ? command.logs({ signal: abortSignal })
227
+ : command.logs();
228
+ for await (const message of iterator) {
229
+ const target =
230
+ message.stream === 'stdout' ? controllers.stdout : controllers.stderr;
231
+ target?.enqueue(encoder.encode(message.data));
232
+ }
233
+ controllers.stdout?.close();
234
+ controllers.stderr?.close();
235
+ } catch (error) {
236
+ controllers.stdout?.error(error);
237
+ controllers.stderr?.error(error);
238
+ }
239
+ })();
240
+
241
+ return {
242
+ stdout,
243
+ stderr,
244
+ async wait(): Promise<{ exitCode: number }> {
245
+ const finished = await command.wait();
246
+ await drained;
247
+ if (abortSignal?.aborted) {
248
+ throw abortSignal.reason ?? new DOMException('Aborted', 'AbortError');
249
+ }
250
+ return { exitCode: finished.exitCode };
251
+ },
252
+ async kill(): Promise<void> {
253
+ await command.kill();
254
+ },
255
+ };
256
+ }
257
+
258
+ function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
259
+ return new ReadableStream<Uint8Array>({
260
+ start(controller) {
261
+ controller.enqueue(bytes);
262
+ controller.close();
263
+ },
264
+ });
265
+ }
266
+
267
+ async function collectStream(
268
+ stream: ReadableStream<Uint8Array>,
269
+ ): Promise<Uint8Array> {
270
+ const reader = stream.getReader();
271
+ const chunks: Uint8Array[] = [];
272
+ let total = 0;
273
+ while (true) {
274
+ const { value, done } = await reader.read();
275
+ if (done) break;
276
+ if (value) {
277
+ chunks.push(value);
278
+ total += value.byteLength;
279
+ }
280
+ }
281
+ const out = new Uint8Array(total);
282
+ let offset = 0;
283
+ for (const chunk of chunks) {
284
+ out.set(chunk, offset);
285
+ offset += chunk.byteLength;
286
+ }
287
+ return out;
288
+ }
289
+
290
+ function isFileNotFoundError(error: unknown): boolean {
291
+ if (error == null || typeof error !== 'object') return false;
292
+ const code = (error as { code?: unknown }).code;
293
+ if (code === 'ENOENT') return true;
294
+ const message = (error as { message?: unknown }).message;
295
+ return (
296
+ typeof message === 'string' &&
297
+ /no such file|not found|does not exist|ENOENT/i.test(message)
298
+ );
299
+ }
@@ -0,0 +1,288 @@
1
+ import type {
2
+ HarnessV1NetworkSandboxSession,
3
+ HarnessV1SandboxProvider,
4
+ } from '@ai-sdk/harness';
5
+ import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
6
+ import { Sandbox } from '@vercel/sandbox';
7
+ import { VercelNetworkSandboxSession } from './vercel-network-sandbox-session';
8
+ import { VercelSandboxSession } from './vercel-sandbox-session';
9
+
10
+ /**
11
+ * Flattens an intersection of object types into a single object type so the
12
+ * resolved shape displays as its named properties rather than a chain of
13
+ * `A & B & C`.
14
+ */
15
+ type Prettify<T> = { [K in keyof T]: T[K] } & {};
16
+
17
+ /**
18
+ * Distributes `Omit` across each member of a union instead of collapsing the
19
+ * union to its common keys. `Sandbox.create`'s parameter is a union (a
20
+ * git/tarball/no-source create variant and a snapshot-source create variant),
21
+ * so a plain `Omit` would discard keys absent from any one member (e.g.
22
+ * `runtime`, which the snapshot variant lacks) and merge the `source` shapes.
23
+ * Applying `Omit` per-member preserves every variant intact; the `Prettify`
24
+ * wrapper collapses each member's intersections into a readable object shape.
25
+ */
26
+ type DistributiveOmit<T, K extends keyof any> = T extends unknown
27
+ ? Prettify<Omit<T, K>>
28
+ : never;
29
+
30
+ /**
31
+ * Parameters forwarded to `@vercel/sandbox`'s `Sandbox.create` when creating
32
+ * a sandbox from scratch. Aliased directly from the underlying SDK so the
33
+ * full surface — every option Vercel supports, including its native
34
+ * `NetworkPolicy` — is available without us re-declaring it.
35
+ */
36
+ type VercelSandboxCreateParams = DistributiveOmit<
37
+ NonNullable<Parameters<typeof Sandbox.create>[0]>,
38
+ 'onResume'
39
+ >;
40
+
41
+ /**
42
+ * Settings for {@link createVercelSandbox}. Two mutually-exclusive shapes:
43
+ *
44
+ * - `{ sandbox }` — wrap an already-created `@vercel/sandbox` `Sandbox`. The
45
+ * caller owns its lifecycle; the provider's `stop()` and `destroy()` are
46
+ * no-ops. Optionally declare `bridgePorts` to give the harness a port pool to
47
+ * lease from for concurrent sessions on the same provided sandbox.
48
+ * - {@link VercelSandboxCreateParams} fields — provider creates the underlying
49
+ * sandbox. When the adapter declares a bootstrap recipe the provider uses
50
+ * `Sandbox.getOrCreate` to maintain a persistent named template snapshot
51
+ * keyed by the recipe identity, and forks an ephemeral sandbox per session
52
+ * from the snapshot. Use `name` to override the auto-derived template name.
53
+ */
54
+ export type VercelSandboxSettings =
55
+ | {
56
+ sandbox: Sandbox;
57
+ bridgePorts?: ReadonlyArray<number>;
58
+ }
59
+ | (VercelSandboxCreateParams & {
60
+ sandbox?: never;
61
+ name?: string;
62
+ });
63
+
64
+ /**
65
+ * 30 minutes. The `@vercel/sandbox` SDK defaults to 5 minutes which is
66
+ * too short for multi-step workflows — the VM expires between steps.
67
+ */
68
+ const DEFAULT_SANDBOX_TIMEOUT_MS = 30 * 60 * 1_000;
69
+
70
+ const VERCEL_PROVIDER_ID = 'vercel-sandbox';
71
+ const TEMPLATE_NAME_PREFIX = 'ai-sdk-harness';
72
+ const SESSION_NAME_PREFIX = 'ai-sdk-harness-session';
73
+ const SNAPSHOT_POLL_INTERVAL_MS = 500;
74
+ const SNAPSHOT_POLL_TIMEOUT_MS = 30_000;
75
+
76
+ function sessionSandboxName(sessionId: string): string {
77
+ return `${SESSION_NAME_PREFIX}-${sessionId}`;
78
+ }
79
+
80
+ export function createVercelSandbox(
81
+ settings: VercelSandboxSettings = {} as VercelSandboxSettings,
82
+ ): HarnessV1SandboxProvider {
83
+ return new VercelSandboxProvider(settings);
84
+ }
85
+
86
+ /**
87
+ * `HarnessV1SandboxProvider` implementation backed by `@vercel/sandbox`.
88
+ * Construct one via {@link createVercelSandbox} at module scope and pass it
89
+ * to a `HarnessAgent` (or call `createSession()` directly if you want raw
90
+ * access to a network sandbox session).
91
+ */
92
+ export class VercelSandboxProvider implements HarnessV1SandboxProvider {
93
+ readonly specificationVersion = 'harness-sandbox-v1' as const;
94
+ readonly providerId = VERCEL_PROVIDER_ID;
95
+ readonly bridgePorts?: ReadonlyArray<number>;
96
+
97
+ constructor(private readonly settings: VercelSandboxSettings) {
98
+ if (
99
+ 'sandbox' in settings &&
100
+ settings.sandbox != null &&
101
+ settings.bridgePorts != null &&
102
+ settings.bridgePorts.length > 0
103
+ ) {
104
+ this.bridgePorts = [...settings.bridgePorts];
105
+ }
106
+ }
107
+
108
+ createSession = async (options?: {
109
+ sessionId?: string;
110
+ abortSignal?: AbortSignal;
111
+ identity?: string;
112
+ onFirstCreate?: (
113
+ session: SandboxSession,
114
+ opts: { abortSignal?: AbortSignal },
115
+ ) => Promise<void>;
116
+ }): Promise<HarnessV1NetworkSandboxSession> => {
117
+ options?.abortSignal?.throwIfAborted();
118
+
119
+ if ('sandbox' in this.settings && this.settings.sandbox != null) {
120
+ return new VercelNetworkSandboxSession({
121
+ sandbox: this.settings.sandbox,
122
+ ownsLifecycle: false,
123
+ });
124
+ }
125
+
126
+ type CreateNewBranch = BaseCreateSandboxParams & {
127
+ sandbox?: never;
128
+ name?: string;
129
+ };
130
+ const settings = this.settings as CreateNewBranch;
131
+ const {
132
+ sandbox: _ignoredSandbox,
133
+ name: explicitName,
134
+ ...createParams
135
+ } = settings;
136
+ const baseParams: BaseCreateSandboxParams = {
137
+ ...createParams,
138
+ timeout: createParams.timeout ?? DEFAULT_SANDBOX_TIMEOUT_MS,
139
+ };
140
+
141
+ const identity = options?.identity;
142
+ const onFirstCreate = options?.onFirstCreate;
143
+
144
+ // When sessionId is supplied, name the per-session sandbox deterministically
145
+ // so a future `resumeSession({ sessionId })` can locate it via
146
+ // `Sandbox.get({ name })`. Absent sessionId (e.g. prewarm), fall back to
147
+ // Vercel's auto-naming.
148
+ const sessionNameOverride = options?.sessionId
149
+ ? { name: sessionSandboxName(options.sessionId) }
150
+ : {};
151
+
152
+ if (identity == null || onFirstCreate == null) {
153
+ const sandbox = await Sandbox.create({
154
+ ...baseParams,
155
+ ...sessionNameOverride,
156
+ ...(options?.abortSignal ? { signal: options.abortSignal } : {}),
157
+ });
158
+ return new VercelNetworkSandboxSession({ sandbox, ownsLifecycle: true });
159
+ }
160
+
161
+ const templateName = explicitName ?? `${TEMPLATE_NAME_PREFIX}-${identity}`;
162
+ const cache = getSnapshotCache();
163
+ let snapshotId = cache.get(templateName);
164
+
165
+ if (snapshotId == null) {
166
+ const template = await Sandbox.getOrCreate({
167
+ ...baseParams,
168
+ name: templateName,
169
+ persistent: true,
170
+ snapshotExpiration: baseParams.snapshotExpiration ?? 0,
171
+ onCreate: async sbx => {
172
+ await onFirstCreate(new VercelSandboxSession(sbx), {
173
+ abortSignal: options?.abortSignal,
174
+ });
175
+ },
176
+ ...(options?.abortSignal ? { signal: options.abortSignal } : {}),
177
+ });
178
+
179
+ let resolvedId: string | undefined = template.currentSnapshotId;
180
+ if (resolvedId == null) {
181
+ const stopResult = await template.stop(
182
+ options?.abortSignal ? { signal: options.abortSignal } : undefined,
183
+ );
184
+ resolvedId = stopResult.snapshot?.id;
185
+ if (resolvedId == null) {
186
+ resolvedId = await pollForTemplateSnapshot(
187
+ templateName,
188
+ options?.abortSignal,
189
+ );
190
+ }
191
+ }
192
+
193
+ cache.set(templateName, resolvedId);
194
+ snapshotId = resolvedId;
195
+ }
196
+
197
+ const {
198
+ runtime: _ignoredRuntime,
199
+ source: _ignoredSource,
200
+ persistent: _ignoredPersistent,
201
+ ...forkParams
202
+ } = baseParams;
203
+
204
+ const fork = await Sandbox.create({
205
+ ...forkParams,
206
+ source: { type: 'snapshot', snapshotId },
207
+ ...sessionNameOverride,
208
+ ...(options?.abortSignal ? { signal: options.abortSignal } : {}),
209
+ });
210
+ return new VercelNetworkSandboxSession({
211
+ sandbox: fork,
212
+ ownsLifecycle: true,
213
+ });
214
+ };
215
+
216
+ resumeSession = async (options: {
217
+ sessionId: string;
218
+ abortSignal?: AbortSignal;
219
+ }): Promise<HarnessV1NetworkSandboxSession> => {
220
+ options.abortSignal?.throwIfAborted();
221
+
222
+ // Wrap-existing case: caller owns the sandbox. Same session as createSession.
223
+ if ('sandbox' in this.settings && this.settings.sandbox != null) {
224
+ return new VercelNetworkSandboxSession({
225
+ sandbox: this.settings.sandbox,
226
+ ownsLifecycle: false,
227
+ });
228
+ }
229
+
230
+ const sandbox = await Sandbox.get({
231
+ name: sessionSandboxName(options.sessionId),
232
+ ...(options.abortSignal ? { signal: options.abortSignal } : {}),
233
+ });
234
+ return new VercelNetworkSandboxSession({ sandbox, ownsLifecycle: true });
235
+ };
236
+ }
237
+
238
+ /**
239
+ * Base shape of `Sandbox.create` params extracted from the union (excludes
240
+ * the `source: { type: 'snapshot' }` variant) so all create-time fields
241
+ * are typed as present.
242
+ */
243
+ type BaseCreateSandboxParams = Exclude<
244
+ VercelSandboxCreateParams,
245
+ { source: { type: 'snapshot'; snapshotId: string } }
246
+ >;
247
+
248
+ const SNAPSHOT_CACHE_KEY = Symbol.for(
249
+ 'ai-sdk.harness.vercel-template-snapshots',
250
+ );
251
+
252
+ type SnapshotCache = Map<string, string>;
253
+
254
+ function getSnapshotCache(): SnapshotCache {
255
+ const globals = globalThis as {
256
+ [SNAPSHOT_CACHE_KEY]?: SnapshotCache;
257
+ };
258
+ let cache = globals[SNAPSHOT_CACHE_KEY];
259
+ if (cache == null) {
260
+ cache = new Map();
261
+ globals[SNAPSHOT_CACHE_KEY] = cache;
262
+ }
263
+ return cache;
264
+ }
265
+
266
+ async function pollForTemplateSnapshot(
267
+ name: string,
268
+ abortSignal: AbortSignal | undefined,
269
+ ): Promise<string> {
270
+ const deadline = Date.now() + SNAPSHOT_POLL_TIMEOUT_MS;
271
+ while (Date.now() < deadline) {
272
+ abortSignal?.throwIfAborted();
273
+ const refreshed = await Sandbox.get({
274
+ name,
275
+ resume: false,
276
+ ...(abortSignal ? { signal: abortSignal } : {}),
277
+ });
278
+ if (refreshed.currentSnapshotId) {
279
+ return refreshed.currentSnapshotId;
280
+ }
281
+ await new Promise<void>(resolve =>
282
+ setTimeout(resolve, SNAPSHOT_POLL_INTERVAL_MS),
283
+ );
284
+ }
285
+ throw new Error(
286
+ `Timed out waiting for snapshot of template "${name}" to publish.`,
287
+ );
288
+ }