@mastra/e2b 0.10.0-alpha.3 → 0.10.0-alpha.5
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 +36 -0
- package/dist/index.cjs +132 -43
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +132 -43
- package/dist/index.js.map +1 -1
- package/dist/sandbox/index.d.ts +82 -15
- package/dist/sandbox/index.d.ts.map +1 -1
- package/package.json +3 -3
package/dist/sandbox/index.d.ts
CHANGED
|
@@ -17,7 +17,7 @@ type InstructionsOption = string | ((opts: {
|
|
|
17
17
|
}) => string);
|
|
18
18
|
import { MastraSandbox } from '@mastra/core/workspace';
|
|
19
19
|
import { Sandbox } from 'e2b';
|
|
20
|
-
import type { SandboxLifecycle, SandboxNetworkOpts } from 'e2b';
|
|
20
|
+
import type { SandboxConnectOpts, SandboxLifecycle, SandboxNetworkOpts, SandboxOpts } from 'e2b';
|
|
21
21
|
import type { TemplateSpec } from '../utils/template.js';
|
|
22
22
|
import { E2BProcessManager } from './process-manager.js';
|
|
23
23
|
/**
|
|
@@ -26,6 +26,17 @@ import { E2BProcessManager } from './process-manager.js';
|
|
|
26
26
|
export interface E2BSandboxOptions extends Omit<MastraSandboxOptions, 'processes'> {
|
|
27
27
|
/** Unique identifier for this sandbox instance */
|
|
28
28
|
id?: string;
|
|
29
|
+
/**
|
|
30
|
+
* Persisted E2B provider sandbox ID to reattach to deterministically.
|
|
31
|
+
*
|
|
32
|
+
* When set, `start()` first queries this exact sandbox and connects to it
|
|
33
|
+
* (resuming it if paused) instead of discovering by logical `id` metadata.
|
|
34
|
+
* Only a typed "sandbox gone" error (not found / killed / not running)
|
|
35
|
+
* falls through to the usual logical-id lookup and create ladder;
|
|
36
|
+
* auth, quota, rate-limit, timeout, and network errors propagate without
|
|
37
|
+
* creating a new sandbox.
|
|
38
|
+
*/
|
|
39
|
+
sandboxId?: string;
|
|
29
40
|
/**
|
|
30
41
|
* Sandbox template specification.
|
|
31
42
|
*
|
|
@@ -120,10 +131,10 @@ export interface E2BSandboxOptions extends Omit<MastraSandboxOptions, 'processes
|
|
|
120
131
|
*
|
|
121
132
|
* ```
|
|
122
133
|
*/
|
|
123
|
-
export declare class E2BSandbox extends MastraSandbox {
|
|
134
|
+
export declare class E2BSandbox extends MastraSandbox<Sandbox> {
|
|
124
135
|
readonly id: string;
|
|
125
|
-
readonly name
|
|
126
|
-
readonly provider
|
|
136
|
+
readonly name: string;
|
|
137
|
+
readonly provider: string;
|
|
127
138
|
status: ProviderStatus;
|
|
128
139
|
readonly mounts: MountManager;
|
|
129
140
|
readonly processes: E2BProcessManager;
|
|
@@ -137,19 +148,20 @@ export declare class E2BSandbox extends MastraSandbox {
|
|
|
137
148
|
* deployments without waking a paused sandbox.
|
|
138
149
|
*/
|
|
139
150
|
readonly networking: SandboxNetworking;
|
|
140
|
-
|
|
151
|
+
protected _sandbox: Sandbox | null;
|
|
141
152
|
private _createdAt;
|
|
142
153
|
private _isRetrying;
|
|
143
154
|
private readonly timeout;
|
|
144
|
-
|
|
155
|
+
protected readonly templateSpec?: TemplateSpec;
|
|
145
156
|
private readonly metadata;
|
|
146
157
|
private readonly network?;
|
|
147
158
|
private readonly lifecycle;
|
|
148
|
-
|
|
159
|
+
protected readonly connectionOpts: Record<string, string>;
|
|
160
|
+
private readonly _preferredSandboxId?;
|
|
149
161
|
private readonly _instructionsOverride?;
|
|
150
162
|
private readonly _constructorOptions;
|
|
151
163
|
/** Resolved template ID after building (if needed) */
|
|
152
|
-
|
|
164
|
+
protected _resolvedTemplateId?: string;
|
|
153
165
|
/** Promise for template preparation (started in constructor) */
|
|
154
166
|
private _templatePreparePromise?;
|
|
155
167
|
constructor(options?: E2BSandboxOptions);
|
|
@@ -164,7 +176,9 @@ export declare class E2BSandbox extends MastraSandbox {
|
|
|
164
176
|
* independent sandboxes (e.g. one per project).
|
|
165
177
|
*
|
|
166
178
|
* `options.idleTimeoutMinutes` maps to the E2B sandbox `timeout` (ms);
|
|
167
|
-
* `options.sandboxId`
|
|
179
|
+
* `options.sandboxId` reattaches the clone to that exact E2B sandbox on
|
|
180
|
+
* `start()`. The parent's own preferred provider sandbox ID is never
|
|
181
|
+
* inherited — physical identity is per-instance.
|
|
168
182
|
*/
|
|
169
183
|
clone(options?: SandboxCloneOptions): E2BSandbox;
|
|
170
184
|
/**
|
|
@@ -191,12 +205,28 @@ export declare class E2BSandbox extends MastraSandbox {
|
|
|
191
205
|
*/
|
|
192
206
|
get e2b(): Sandbox;
|
|
193
207
|
/**
|
|
194
|
-
*
|
|
195
|
-
*
|
|
208
|
+
* The E2B provider sandbox ID resolved after connect or create.
|
|
209
|
+
*
|
|
210
|
+
* Persist this to reattach deterministically later via the `sandboxId`
|
|
211
|
+
* option (or `clone({ sandboxId })`). Undefined until the sandbox has been
|
|
212
|
+
* started (attached) in this process.
|
|
213
|
+
*/
|
|
214
|
+
get sandboxId(): string | undefined;
|
|
215
|
+
/**
|
|
216
|
+
* Acquisition primitives (base-orchestrated start): the base derives
|
|
217
|
+
* `outcome: 'created'` only when a brand-new sandbox VM was created;
|
|
218
|
+
* reconnecting (including resuming a paused sandbox) is `outcome: 'connected'`.
|
|
196
219
|
*
|
|
197
|
-
*
|
|
220
|
+
* `find` returns an already-connected E2B handle: `Sandbox.connect`
|
|
221
|
+
* resumes paused sandboxes, and its failures are deliberately swallowed
|
|
222
|
+
* (unusable handle → create fresh) — that forgiveness is this provider's
|
|
223
|
+
* policy, so it lives here rather than in `connect`. The exception is the
|
|
224
|
+
* `sandboxId` reattach inside {@link acquireExistingSandbox}, which is
|
|
225
|
+
* fail-closed: only a "sandbox gone" error falls through to discovery.
|
|
198
226
|
*/
|
|
199
|
-
|
|
227
|
+
protected find(): Promise<Sandbox | undefined>;
|
|
228
|
+
protected connect(existingSandbox: Sandbox): Promise<void>;
|
|
229
|
+
protected create(): Promise<void>;
|
|
200
230
|
/**
|
|
201
231
|
* Stop the E2B sandbox by pausing it (snapshot-stop).
|
|
202
232
|
*
|
|
@@ -254,12 +284,43 @@ export declare class E2BSandbox extends MastraSandbox {
|
|
|
254
284
|
* WITHOUT connecting or resuming it. Returns its list info or null.
|
|
255
285
|
*/
|
|
256
286
|
private lookupExistingSandboxInfo;
|
|
287
|
+
/**
|
|
288
|
+
* Acquire an existing sandbox: try the preferred provider sandbox ID first
|
|
289
|
+
* (deterministic reattach), then fall back to logical-id metadata discovery.
|
|
290
|
+
*/
|
|
291
|
+
private acquireExistingSandbox;
|
|
292
|
+
/**
|
|
293
|
+
* Deterministically reattach to a sandbox by its E2B provider ID.
|
|
294
|
+
*
|
|
295
|
+
* Fail-closed: only a typed "sandbox gone" error (not found / killed /
|
|
296
|
+
* not running) returns null so the caller can fall through to logical-id
|
|
297
|
+
* discovery or creation. Any other error (auth, quota, rate limit,
|
|
298
|
+
* timeout, network) propagates so a duplicate sandbox is never created.
|
|
299
|
+
*
|
|
300
|
+
* Ownership is validated before connecting: a sandbox tagged with a
|
|
301
|
+
* different `mastra-sandbox-id` is refused (without resuming it).
|
|
302
|
+
* Sandboxes without the tag (created outside Mastra) are attachable.
|
|
303
|
+
*/
|
|
304
|
+
private connectToPreferredSandbox;
|
|
257
305
|
/**
|
|
258
306
|
* Find an existing sandbox with matching mastra-sandbox-id metadata.
|
|
259
307
|
* Returns the connected sandbox if found, null otherwise.
|
|
260
308
|
* Connecting to a paused sandbox resumes it.
|
|
261
309
|
*/
|
|
262
310
|
private findExistingSandbox;
|
|
311
|
+
/**
|
|
312
|
+
* Create a new SDK sandbox from a resolved template ID.
|
|
313
|
+
*
|
|
314
|
+
* Override point for providers layered on the E2B SDK whose `Sandbox`
|
|
315
|
+
* class extends `e2b`'s (e.g. `@e2b/desktop`): override to call their
|
|
316
|
+
* `Sandbox.create`. Connection options are already spread into `opts`.
|
|
317
|
+
*/
|
|
318
|
+
protected createSdkSandbox(templateId: string, opts: SandboxOpts): Promise<Sandbox>;
|
|
319
|
+
/**
|
|
320
|
+
* Connect to (and resume) an existing SDK sandbox by its E2B sandbox ID.
|
|
321
|
+
* Override point — see {@link createSdkSandbox}.
|
|
322
|
+
*/
|
|
323
|
+
protected connectSdkSandbox(sandboxId: string, opts: SandboxConnectOpts): Promise<Sandbox>;
|
|
263
324
|
/**
|
|
264
325
|
* Resolve the template specification to a template ID.
|
|
265
326
|
*
|
|
@@ -267,12 +328,18 @@ export declare class E2BSandbox extends MastraSandbox {
|
|
|
267
328
|
* - TemplateBuilder: Build and return the template ID
|
|
268
329
|
* - Function: Apply to base mountable template, then build
|
|
269
330
|
* - undefined: Use default mountable template (cached)
|
|
331
|
+
*
|
|
332
|
+
* Override point: subclasses with a different default template (e.g.
|
|
333
|
+
* desktop sandboxes) override this and {@link buildDefaultTemplate}.
|
|
270
334
|
*/
|
|
271
|
-
|
|
335
|
+
protected resolveTemplate(): Promise<string>;
|
|
272
336
|
/**
|
|
273
337
|
* Build the default mountable template (bypasses exists check).
|
|
338
|
+
*
|
|
339
|
+
* Override point: called from the template-not-found retry path in
|
|
340
|
+
* `start()` when no explicit template was configured.
|
|
274
341
|
*/
|
|
275
|
-
|
|
342
|
+
protected buildDefaultTemplate(): Promise<string>;
|
|
276
343
|
/**
|
|
277
344
|
* Write marker file for detecting config changes on reconnect.
|
|
278
345
|
* Stores both the mount path and config hash in the file.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,WAAW,EAEX,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/e2b",
|
|
3
|
-
"version": "0.10.0-alpha.
|
|
3
|
+
"version": "0.10.0-alpha.5",
|
|
4
4
|
"description": "E2B cloud sandbox provider for Mastra workspaces",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -32,11 +32,11 @@
|
|
|
32
32
|
"tsdown": "0.22.9",
|
|
33
33
|
"typescript": "^6.0.3",
|
|
34
34
|
"vitest": "4.1.10",
|
|
35
|
-
"@internal/lint": "0.0.125",
|
|
36
35
|
"@internal/types-builder": "0.0.100",
|
|
36
|
+
"@internal/lint": "0.0.125",
|
|
37
37
|
"@internal/workspace-test-utils": "0.0.69",
|
|
38
38
|
"@mastra/gcs": "0.3.2",
|
|
39
|
-
"@mastra/core": "1.62.0-alpha.
|
|
39
|
+
"@mastra/core": "1.62.0-alpha.12",
|
|
40
40
|
"@mastra/s3": "0.6.1"
|
|
41
41
|
},
|
|
42
42
|
"peerDependencies": {
|