@mastra/e2b 0.13.0 → 0.14.0-alpha.0

package/dist/factory-sandbox.d.ts

@@ -0,0 +1,36 @@
+import type { PublicSchema } from '@mastra/core/schema';
+import { FactorySandbox } from '@mastra/core/workspace';
+import type { FactorySandboxBuilds, FactorySandboxContext } from '@mastra/core/workspace';
+import { E2BSandbox } from './sandbox/index.js';
+import type { E2BSandboxOptions } from './sandbox/index.js';
+import type { DeferredNamedTemplateSpec } from './utils/template.js';
+/** User-tunable settings of an E2B factory sandbox. Every field is optional; absent means the provider default. */
+export interface E2BFactorySandboxSettings extends Record<string, unknown> {
+    /** vCPUs for the sandbox template. Part of the template identity. */
+    cpuCount?: number;
+    /** Memory in MB for the sandbox template. Part of the template identity. */
+    memoryMb?: number;
+    /** Minutes a sandbox stays alive before E2B stops it. Not part of the template identity. */
+    idleTimeoutMinutes?: number;
+}
+export interface E2BFactorySandboxOptions extends Omit<E2BSandboxOptions, 'id' | 'sandboxId' | 'template'> {
+    /** Provider-side defaults used when a setting is unset. Never stored by factory. */
+    defaults?: Partial<E2BFactorySandboxSettings>;
+}
+/**
+ * The E2B host contract for factory: every session sandbox is an
+ * {@link E2BSandbox} whose template is {@link createRepoTemplate} over the
+ * session's repositories, sized by the factory's environment settings. The
+ * `builds` capability starts the same sha-tagged template ahead of any
+ * session and reads its status, logs and history back from E2B.
+ */
+export declare class E2BFactorySandbox extends FactorySandbox<E2BFactorySandboxSettings> {
+    #private;
+    readonly provider = "e2b";
+    readonly settings: PublicSchema<E2BFactorySandboxSettings>;
+    readonly builds: FactorySandboxBuilds<E2BFactorySandboxSettings>;
+    constructor(options?: E2BFactorySandboxOptions);
+    template(ctx: FactorySandboxContext, settings: E2BFactorySandboxSettings): DeferredNamedTemplateSpec | undefined;
+    create(ctx: FactorySandboxContext, settings: E2BFactorySandboxSettings): E2BSandbox;
+}
+//# sourceMappingURL=factory-sandbox.d.ts.map

package/dist/factory-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-sandbox.d.ts","sourceRoot":"","sources":["../src/factory-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAIV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGnD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAElE,mHAAmH;AACnH,MAAM,WAAW,yBAA0B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxE,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AA2DD,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,WAAW,GAAG,UAAU,CAAC;IACxG,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAC/C;AAQD;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,cAAc,CAAC,yBAAyB,CAAC;;IAC9E,QAAQ,CAAC,QAAQ,SAAS;IAC1B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,yBAAyB,CAAC,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;IAKjE,YAAY,OAAO,GAAE,wBAA6B,EAejD;IAED,QAAQ,CAAC,GAAG,EAAE,qBAAqB,EAAE,QAAQ,EAAE,yBAAyB,GAAG,yBAAyB,GAAG,SAAS,CAE/G;IAED,MAAM,CAAC,GAAG,EAAE,qBAAqB,EAAE,QAAQ,EAAE,yBAAyB,GAAG,UAAU,CAUlF;CA6FF"}

package/dist/index.cjs

@@ -2146,6 +2146,222 @@ const e2bSandboxProvider = {
 	createSandbox: (config) => new E2BSandbox(config)
 };
 //#endregion
+//#region src/factory-sandbox.ts
+/** Applied when neither the environment setting nor a host default is set. */
+const DEFAULT_SETTINGS = {
+	cpuCount: 2,
+	memoryMb: 1024,
+	idleTimeoutMinutes: 5
+};
+const SETTINGS_SCHEMA = {
+	type: "object",
+	properties: {
+		cpuCount: {
+			type: "integer",
+			title: "CPU",
+			description: "vCPUs for the sandbox template",
+			default: DEFAULT_SETTINGS.cpuCount,
+			minimum: 1,
+			maximum: 8
+		},
+		memoryMb: {
+			type: "integer",
+			title: "Memory (MB)",
+			description: "Memory in MB for the sandbox template",
+			default: DEFAULT_SETTINGS.memoryMb,
+			minimum: 512,
+			maximum: 65536
+		},
+		idleTimeoutMinutes: {
+			type: "integer",
+			title: "Idle timeout (minutes)",
+			description: "Minutes a sandbox stays alive before E2B stops it",
+			default: DEFAULT_SETTINGS.idleTimeoutMinutes,
+			minimum: 1,
+			maximum: 1440
+		}
+	},
+	additionalProperties: false
+};
+/**
+* The settings schema with the provider's effective defaults as `default`:
+* the built-in values, overridden by the host's `defaults` option. The schema
+* is what clients show as placeholders, so it must match what the provider
+* applies when a setting is unset.
+*/
+function settingsSchema(options) {
+	const { defaults, timeout } = options;
+	const effective = {
+		...DEFAULT_SETTINGS,
+		...timeout !== void 0 ? { idleTimeoutMinutes: Math.ceil(timeout / 6e4) } : {},
+		...defaults
+	};
+	const properties = Object.fromEntries(Object.entries(SETTINGS_SCHEMA.properties).map(([key, property]) => [key, {
+		...property,
+		default: effective[key]
+	}]));
+	return {
+		...SETTINGS_SCHEMA,
+		properties
+	};
+}
+/** Log entries E2B returns per build-status call. */
+const BUILD_LOG_PAGE = 100;
+/** The id of a build that needed no build: the sha-tagged template already existed. */
+const EXISTING_BUILD = "existing";
+/**
+* The E2B host contract for factory: every session sandbox is an
+* {@link E2BSandbox} whose template is {@link createRepoTemplate} over the
+* session's repositories, sized by the factory's environment settings. The
+* `builds` capability starts the same sha-tagged template ahead of any
+* session and reads its status, logs and history back from E2B.
+*/
+var E2BFactorySandbox = class extends _mastra_core_workspace.FactorySandbox {
+	provider = "e2b";
+	settings;
+	builds;
+	#options;
+	#connection;
+	constructor(options = {}) {
+		super();
+		this.#options = options;
+		this.settings = settingsSchema(options);
+		this.#connection = {
+			...options.domain && { domain: options.domain },
+			...options.apiUrl && { apiUrl: options.apiUrl },
+			...options.apiKey && { apiKey: options.apiKey },
+			...options.accessToken && { accessToken: options.accessToken }
+		};
+		this.builds = {
+			start: (ctx, settings) => this.#startBuild(ctx, settings),
+			get: (_ctx, _settings, buildId) => this.#getBuild(buildId),
+			list: (ctx, settings) => this.#listBuilds(ctx, settings)
+		};
+	}
+	template(ctx, settings) {
+		return createRepoTemplate(this.#templateOptions(ctx, settings));
+	}
+	create(ctx, settings) {
+		const { defaults, ...options } = this.#options;
+		return new E2BSandbox({
+			...options,
+			id: ctx.sessionId,
+			sandboxId: ctx.sandboxId,
+			template: this.template(ctx, settings),
+			...ctx.workingDirectory ? { workingDirectory: ctx.workingDirectory } : {},
+			timeout: this.#timeout(settings)
+		});
+	}
+	/** The setting, then the host default, then the host's own `timeout` option, then 5 minutes. */
+	#timeout(settings) {
+		const minutes = settings.idleTimeoutMinutes ?? this.#options.defaults?.idleTimeoutMinutes;
+		if (minutes !== void 0) return minutes * 6e4;
+		return this.#options.timeout ?? DEFAULT_SETTINGS.idleTimeoutMinutes * 6e4;
+	}
+	#templateOptions(ctx, settings) {
+		const { defaults } = this.#options;
+		const { resolveHead: _resolveHead, ...rest } = ctx;
+		return {
+			...rest,
+			cpuCount: settings.cpuCount ?? defaults?.cpuCount ?? DEFAULT_SETTINGS.cpuCount,
+			memoryMB: settings.memoryMb ?? defaults?.memoryMb ?? DEFAULT_SETTINGS.memoryMb
+		};
+	}
+	async #startBuild(ctx, settings) {
+		const { spec } = await resolveSpecAtHead(this.#templateOptions(ctx, settings));
+		if (await e2b.Template.exists(spec.ref, this.#connection)) return {
+			buildId: `${spec.ref}:${EXISTING_BUILD}`,
+			templateId: spec.ref,
+			status: "ready"
+		};
+		const info = await e2b.Template.buildInBackground(spec.template, spec.ref, {
+			...this.#connection,
+			...spec.buildTags?.length ? { tags: spec.buildTags } : {},
+			...spec.buildResources
+		});
+		return {
+			buildId: `${info.templateId}:${info.buildId}`,
+			templateId: info.templateId,
+			status: "pending"
+		};
+	}
+	async #getBuild(compositeId) {
+		const { templateId, buildId } = splitBuildId(compositeId);
+		if (buildId === EXISTING_BUILD) return {
+			buildId: compositeId,
+			templateId,
+			status: "ready"
+		};
+		let response = await e2b.Template.getBuildStatus({
+			templateId,
+			buildId
+		}, this.#connection);
+		const entries = [...response.logEntries ?? []];
+		while (response.logEntries && response.logEntries.length >= BUILD_LOG_PAGE) {
+			response = await e2b.Template.getBuildStatus({
+				templateId,
+				buildId
+			}, {
+				...this.#connection,
+				logsOffset: entries.length
+			});
+			entries.push(...response.logEntries ?? []);
+		}
+		const logs = entries.length ? entries.map((entry) => entry.toString()) : response.logs?.length ? response.logs : void 0;
+		return {
+			buildId: compositeId,
+			templateId: response.templateID,
+			status: mapStatus(response.status),
+			...logs ? { logs } : {},
+			...response.reason?.message ? { error: response.reason.message } : {}
+		};
+	}
+	async #listBuilds(ctx, settings) {
+		const { spec } = await resolveSpecAtHead(this.#templateOptions(ctx, settings));
+		const name = templateNameOf(spec.ref);
+		const client = new e2b.ApiClient(new e2b.ConnectionConfig(this.#connection));
+		const templates = await client.api.GET("/templates");
+		if (templates.error || !templates.data) throw new Error(`E2B template listing failed: ${describeApiError(templates.error)}`);
+		const template = templates.data.find((t) => t.names.includes(name) || t.aliases.includes(name));
+		if (!template) return [];
+		const detail = await client.api.GET("/templates/{templateID}", { params: { path: { templateID: template.templateID } } });
+		if (detail.error || !detail.data) throw new Error(`E2B template build listing failed: ${describeApiError(detail.error)}`);
+		return detail.data.builds.slice().sort((a, b) => b.createdAt.localeCompare(a.createdAt)).map((build) => ({
+			buildId: `${template.templateID}:${build.buildID}`,
+			templateId: template.templateID,
+			status: mapStatus(build.status),
+			startedAt: build.createdAt,
+			...build.finishedAt ? { finishedAt: build.finishedAt } : {}
+		}));
+	}
+};
+function describeApiError(error) {
+	return error ? JSON.stringify(error) : "empty response";
+}
+/** `<templateId>:<buildId>`, split on the last colon because a template ref itself carries one (`name:sha-<head>`). */
+function splitBuildId(compositeId) {
+	const at = compositeId.lastIndexOf(":");
+	if (at <= 0 || at === compositeId.length - 1) throw new Error(`Invalid E2B build id "${compositeId}": expected "<templateId>:<buildId>"`);
+	return {
+		templateId: compositeId.slice(0, at),
+		buildId: compositeId.slice(at + 1)
+	};
+}
+/** The template name of a `name:tag` ref. */
+function templateNameOf(ref) {
+	const at = ref.lastIndexOf(":");
+	return at > 0 ? ref.slice(0, at) : ref;
+}
+function mapStatus(status) {
+	switch (status) {
+		case "waiting": return "pending";
+		case "building": return "building";
+		case "ready": return "ready";
+		case "error": return "failed";
+		default: return "unknown";
+	}
+}
+//#endregion
 //#region src/code-mode/transport.ts
 /**
 * Code Mode — E2B transport
@@ -2353,6 +2569,7 @@ var E2BCodeModeTransport = class {
 //#endregion
 exports.DEFAULT_NODE_VERSION = DEFAULT_NODE_VERSION;
 exports.E2BCodeModeTransport = E2BCodeModeTransport;
+exports.E2BFactorySandbox = E2BFactorySandbox;
 exports.E2BProcessManager = E2BProcessManager;
 exports.E2BSandbox = E2BSandbox;
 exports.createDefaultMountableTemplate = createDefaultMountableTemplate;