@ai-sdk/sandbox-vercel 0.0.0 → 1.0.0-beta.15
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.
- package/CHANGELOG.md +115 -0
- package/LICENSE +13 -0
- package/README.md +76 -0
- package/dist/index.d.ts +77 -0
- package/dist/index.js +474 -0
- package/dist/index.js.map +1 -0
- package/package.json +69 -1
- package/src/index.ts +5 -0
- package/src/vercel-network-sandbox-session.ts +132 -0
- package/src/vercel-sandbox-session.ts +299 -0
- package/src/vercel-sandbox.ts +288 -0
|
@@ -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
|
+
}
|