@mastra/e2b 0.10.0 → 0.11.0-alpha.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { E2BSandbox, type E2BSandboxOptions } from './sandbox/index.js';
 export { E2BProcessManager } from './sandbox/process-manager.js';
-export { createDefaultMountableTemplate, type TemplateSpec, type MountableTemplateResult } from './utils/template.js';
+export { createDefaultMountableTemplate, isNamedTemplateSpec, isDeferredNamedTemplateSpec, DEFAULT_NODE_VERSION, type TemplateSpec, type NamedTemplateSpec, type DeferredNamedTemplateSpec, type MountableTemplateResult, type MountableTemplateOptions, } from './utils/template.js';
+export { createRepoTemplate, refreshRepoTemplate, repoTemplateRef, type RepoTemplateOptions, type RepoTemplateIdentity, type RepositoryAccess, type RefreshRepoTemplateResult, } from './utils/repo-template.js';
 export { type E2BS3MountConfig, type E2BGCSMountConfig, type E2BAzureBlobMountConfig, type E2BMountConfig, } from './sandbox/mounts/index.js';
 export { e2bSandboxProvider } from './provider.js';
 export { E2BCodeModeTransport } from './code-mode/transport.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AACnH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EACL,8BAA8B,EAC9B,mBAAmB,EACnB,2BAA2B,EAC3B,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,9 +1,25 @@
 import { MastraSandbox, ProcessHandle, SandboxNotReadyError, SandboxProcessManager, UnsupportedStdinCloseError } from "@mastra/core/workspace";
 import { Sandbox, Template } from "e2b";
 import { createHash, randomBytes } from "crypto";
+import { execFile } from "child_process";
+import { promisify } from "util";
 import { FRAME_PREFIX, buildProgramModule, buildRunner, sanitizeToolId } from "@mastra/core/tools";
 import { transformSync } from "esbuild";
 /**
+* Node.js version installed into the default template — the current LTS at
+* pin time. An exact version rather than an `lts` alias so the template's
+* contents can never drift under a stable identity hash; bump deliberately
+* (each bump builds new templates).
+*/
+const DEFAULT_NODE_VERSION = "24.20.0";
+const NODE_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+function isNamedTemplateSpec(spec) {
+	return typeof spec === "object" && spec !== null && "ref" in spec && "template" in spec;
+}
+function isDeferredNamedTemplateSpec(spec) {
+	return typeof spec === "object" && spec !== null && "resolveSpec" in spec && typeof spec.resolveSpec === "function";
+}
+/**
 * Create a base template with FUSE mounting dependencies pre-installed.
 *
 * This template includes s3fs and fuse packages required for mounting
@@ -33,17 +49,28 @@ import { transformSync } from "esbuild";
 *
 * @returns Object with template builder and deterministic ID
 */
-function createDefaultMountableTemplate() {
+function createDefaultMountableTemplate(options) {
 	const aptPackages = ["s3fs", "fuse"];
+	const cpuCount = options?.cpuCount ?? 2;
+	const memoryMB = options?.memoryMB ?? 1024;
+	const nodeVersion = options?.nodeVersion ?? "24.20.0";
+	if (!NODE_VERSION_PATTERN.test(nodeVersion)) throw new Error(`Invalid nodeVersion "${nodeVersion}": expected an exact version like "24.20.0"`);
 	const config = {
-		version: "v1",
-		aptPackages
+		version: "v3",
+		aptPackages,
+		cpuCount,
+		memoryMB,
+		nodeVersion
 	};
 	const hash = createHash("sha256").update(JSON.stringify(config, Object.keys(config).sort())).digest("hex").slice(0, 16);
 	return {
-		template: Template().fromTemplate("base").aptInstall(aptPackages),
+		template: Template().fromTemplate("base").aptInstall(aptPackages).runCmd(`curl -fsSL https://nodejs.org/dist/v${nodeVersion}/node-v${nodeVersion}-linux-x64.tar.gz | sudo tar -xz -C /usr/local --strip-components=1`).runCmd("sudo corepack enable").runCmd(`echo 'COREPACK_ENABLE_DOWNLOAD_PROMPT=0' | sudo tee -a /etc/environment`).setEnvs({ COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" }),
 		id: `mastra-${hash}`,
-		aptPackages
+		aptPackages,
+		resources: {
+			cpuCount,
+			memoryMB
+		}
 	};
 }
 //#endregion
@@ -523,7 +550,7 @@ var E2BProcessManager = class extends SandboxProcessManager {
 			handle = new E2BProcessHandle(await e2b.commands.run(command, {
 				background: true,
 				stdin: true,
-				cwd: options.cwd,
+				cwd: options.cwd ?? this.sandbox.workingDirectory,
 				envs,
 				timeoutMs: options.timeout,
 				onStdout: (data) => handle.emitStdout(data),
@@ -578,6 +605,13 @@ function validateMountPath(mountPath) {
 /** Allowlist for marker filenames from ls output — e.g. "mount-abc123" */
 const SAFE_MARKER_NAME = /^mount-[a-z0-9]+$/;
 /**
+* Per-process dedupe of background template rebuild triggers, keyed by
+* template ref. Retained on successful trigger (the ref only ever needs one
+* build; once it exists the exists-check short-circuits before this path),
+* cleared on trigger failure so a later start can retry.
+*/
+const inFlightBackgroundBuilds = /* @__PURE__ */ new Set();
+/**
 * Simplified E2B sandbox implementation.
 *
 * Features:
@@ -652,10 +686,22 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 	_preferredSandboxId;
 	_instructionsOverride;
 	_constructorOptions;
-	/** Resolved template ID after building (if needed) */
+	/**
+	* Resolved template ID after building (if needed). The single cache for
+	* template resolution: `resolveTemplate()` returns it when set, and the
+	* create-time fallback ladder rewrites it to whichever template actually
+	* produced a sandbox.
+	*
+	* `protected` so a subclass with its own default template (e.g. desktop
+	* sandboxes) shares the same cache when it overrides `resolveTemplate()`.
+	*/
 	_resolvedTemplateId;
-	/** Promise for template preparation (started in constructor) */
-	_templatePreparePromise;
+	/**
+	* The named spec a deferred template spec resolved to — kept so the
+	* 404-on-create fallback ladder can walk the same name/fallback rungs it
+	* would for a plain named spec.
+	*/
+	_resolvedNamedSpec;
 	constructor(options = {}) {
 		super({
 			...options,
@@ -677,10 +723,6 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 		this._preferredSandboxId = options.sandboxId;
 		this._instructionsOverride = options.instructions;
 		this._constructorOptions = { ...options };
-		this._templatePreparePromise = this.resolveTemplate().catch((err) => {
-			this.logger.debug(`${LOG_PREFIX} Template preparation error (will retry on start):`, err);
-			return "";
-		});
 	}
 	/**
 	* Construct a sibling `E2BSandbox` that inherits this sandbox's
@@ -770,11 +812,7 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 		this.logger.debug(`${LOG_PREFIX} Mount reconciliation complete`);
 	}
 	async create() {
-		let resolvedTemplateId = await (this._templatePreparePromise || this.resolveTemplate());
-		if (!resolvedTemplateId) {
-			this.logger.debug(`${LOG_PREFIX} Template preparation failed earlier, retrying...`);
-			resolvedTemplateId = await this.resolveTemplate();
-		}
+		const resolvedTemplateId = await this.resolveTemplate();
 		this.logger.debug(`${LOG_PREFIX} Creating new sandbox for: ${this.id} with template: ${resolvedTemplateId}`);
 		const createOpts = {
 			...this.connectionOpts,
@@ -786,17 +824,51 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 			...this.network && { network: this.network },
 			timeoutMs: this.timeout
 		};
+		const createFromTemplate = (templateId) => this.createSdkSandbox(templateId, createOpts);
+		const isTemplateUnusable = (error) => String(error).includes("404");
 		let sdkSandbox;
 		try {
-			sdkSandbox = await this.createSdkSandbox(resolvedTemplateId, createOpts);
+			sdkSandbox = await createFromTemplate(resolvedTemplateId);
 		} catch (createError) {
-			const errorStr = String(createError);
-			if (errorStr.includes("404") && errorStr.includes("not found") && !this.templateSpec) {
+			if (!isTemplateUnusable(createError)) throw createError;
+			const namedSpec = this.templateSpec && isNamedTemplateSpec(this.templateSpec) ? this.templateSpec : this._resolvedNamedSpec;
+			if (namedSpec) {
+				this.logger.warn(`${LOG_PREFIX} Creating from '${resolvedTemplateId}' failed, retrying on fallback: ${createError}`);
+				this._resolvedTemplateId = void 0;
+				const spec = namedSpec;
+				const fallbackId = resolvedTemplateId === spec.ref ? await this.resolveFallbackTemplate(spec.fallbackTemplate) : await this.buildOrReuseDefaultTemplate();
+				try {
+					sdkSandbox = await createFromTemplate(fallbackId);
+					this._resolvedTemplateId = fallbackId;
+				} catch (fallbackError) {
+					if (!isTemplateUnusable(fallbackError)) throw fallbackError;
+					const rebuildDefaultAndCreate = async () => {
+						this.logger.warn(`${LOG_PREFIX} Default template broken too, rebuilding: ${fallbackError}`);
+						const rebuiltId = await this.buildDefaultTemplate();
+						const rebuilt = await createFromTemplate(rebuiltId);
+						this._resolvedTemplateId = rebuiltId;
+						return rebuilt;
+					};
+					const defaultId = await this.buildOrReuseDefaultTemplate();
+					if (defaultId === fallbackId) sdkSandbox = await rebuildDefaultAndCreate();
+					else {
+						this.logger.warn(`${LOG_PREFIX} Fallback '${fallbackId}' failed too, using default: ${fallbackError}`);
+						try {
+							sdkSandbox = await createFromTemplate(defaultId);
+							this._resolvedTemplateId = defaultId;
+						} catch (defaultError) {
+							if (!isTemplateUnusable(defaultError)) throw defaultError;
+							sdkSandbox = await rebuildDefaultAndCreate();
+						}
+					}
+				}
+				this.logger.debug(`${LOG_PREFIX} Created sandbox ${sdkSandbox.sandboxId} from fallback for: ${this.id}`);
+			} else if (!this.templateSpec) {
 				this.logger.debug(`${LOG_PREFIX} Template not found, rebuilding: ${resolvedTemplateId}`);
 				this._resolvedTemplateId = void 0;
 				const rebuiltTemplateId = await this.buildDefaultTemplate();
 				this.logger.debug(`${LOG_PREFIX} Retrying sandbox creation with rebuilt template: ${rebuiltTemplateId}`);
-				sdkSandbox = await this.createSdkSandbox(rebuiltTemplateId, createOpts);
+				sdkSandbox = await createFromTemplate(rebuiltTemplateId);
 			} else throw createError;
 		}
 		this._sandbox = sdkSandbox;
@@ -1236,31 +1308,57 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 	*/
 	async resolveTemplate() {
 		if (this._resolvedTemplateId) return this._resolvedTemplateId;
-		if (!this.templateSpec) {
-			const { template, id } = createDefaultMountableTemplate();
-			if (await Template.exists(id, this.connectionOpts)) {
-				this.logger.debug(`${LOG_PREFIX} Using cached mountable template: ${id}`);
-				this._resolvedTemplateId = id;
-				return id;
-			}
-			this.logger.debug(`${LOG_PREFIX} Building default mountable template: ${id}...`);
-			const buildResult = await Template.build(template, id, this.connectionOpts);
-			this._resolvedTemplateId = buildResult.templateId;
-			this.logger.debug(`${LOG_PREFIX} Template built and cached: ${buildResult.templateId}`);
-			return buildResult.templateId;
-		}
+		if (!this.templateSpec) return await this.buildOrReuseDefaultTemplate();
 		if (typeof this.templateSpec === "string") {
 			this._resolvedTemplateId = this.templateSpec;
 			return this.templateSpec;
 		}
+		let spec;
+		if (isDeferredNamedTemplateSpec(this.templateSpec)) try {
+			spec = await this.templateSpec.resolveSpec();
+			this._resolvedNamedSpec = spec;
+		} catch (error) {
+			this.logger.warn(`${LOG_PREFIX} Deferred template spec resolution failed, falling back: ${error}`);
+			return await this.resolveFallbackTemplate(void 0);
+		}
+		else spec = this.templateSpec;
+		if (isNamedTemplateSpec(spec)) {
+			const { ref, template: namedTemplate, fallbackTemplate, staleRef, buildTags, buildResources } = spec;
+			const buildOpts = {
+				...this.connectionOpts,
+				...buildTags?.length ? { tags: buildTags } : {},
+				...buildResources
+			};
+			try {
+				if (await Template.exists(ref, this.connectionOpts)) {
+					this.logger.debug(`${LOG_PREFIX} Using cached template: ${ref}`);
+					this._resolvedTemplateId = ref;
+					return ref;
+				}
+				if (staleRef && staleRef !== ref && await Template.exists(staleRef, this.connectionOpts)) {
+					this.logger.debug(`${LOG_PREFIX} Using stale build ${staleRef}; rebuilding ${ref} in background`);
+					this.triggerBackgroundBuild(namedTemplate, ref, buildOpts);
+					this._resolvedTemplateId = staleRef;
+					return staleRef;
+				}
+				this.logger.debug(`${LOG_PREFIX} Building template: ${ref}...`);
+				const buildResult = await Template.build(namedTemplate, ref, buildOpts);
+				this.logger.debug(`${LOG_PREFIX} Template built: ${buildResult.templateId}`);
+				this._resolvedTemplateId = ref;
+				return ref;
+			} catch (error) {
+				this.logger.warn(`${LOG_PREFIX} Template '${ref}' resolution failed, falling back: ${error}`);
+				return await this.resolveFallbackTemplate(fallbackTemplate);
+			}
+		}
 		let template;
 		let templateName;
-		if (typeof this.templateSpec === "function") {
+		if (typeof spec === "function") {
 			const { template: baseTemplate } = createDefaultMountableTemplate();
-			template = this.templateSpec(baseTemplate);
+			template = spec(baseTemplate);
 			templateName = `mastra-custom-${this.id.replace(/[^a-zA-Z0-9-]/g, "-")}`;
 		} else {
-			template = this.templateSpec;
+			template = spec;
 			templateName = `mastra-${this.id.replace(/[^a-zA-Z0-9-]/g, "-")}`;
 		}
 		this.logger.debug(`${LOG_PREFIX} Building custom template: ${templateName}...`);
@@ -1270,15 +1368,102 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 		return buildResult.templateId;
 	}
 	/**
+	* Resolve the default mountable template: reuse when it exists, build once
+	* when it does not.
+	*/
+	/**
+	* Resolve a named spec's fallback template. A named fallback gets its own
+	* exists-then-build resolution; anything failing past that (including
+	* specs without a fallback, e.g. repo templates) lands on the default
+	* mountable template so a broken build never wedges a session.
+	*/
+	/**
+	* Trigger a non-blocking template rebuild via `Template.buildInBackground`
+	* (the build runs on E2B's side, so it outlives this process). Deduped
+	* per-process by ref so concurrent session starts on the same moved head
+	* don't stack duplicate builds; a failed TRIGGER clears the guard so a
+	* later start retries. A build that fails server-side simply never
+	* registers the ref — the next start falls back to the stale build again
+	* and re-triggers.
+	*/
+	triggerBackgroundBuild(template, ref, buildOpts) {
+		if (inFlightBackgroundBuilds.has(ref)) return;
+		inFlightBackgroundBuilds.add(ref);
+		Template.buildInBackground(template, ref, buildOpts).then((result) => {
+			this.logger.debug(`${LOG_PREFIX} Background template build triggered: ${ref} (${result.buildId})`);
+		}).catch((error) => {
+			inFlightBackgroundBuilds.delete(ref);
+			this.logger.warn(`${LOG_PREFIX} Background template build trigger failed for '${ref}': ${error}`);
+		});
+	}
+	async resolveFallbackTemplate(fallbackTemplate) {
+		if (typeof fallbackTemplate === "string") {
+			this._resolvedTemplateId = fallbackTemplate;
+			return fallbackTemplate;
+		}
+		if (fallbackTemplate && isNamedTemplateSpec(fallbackTemplate)) try {
+			if (await Template.exists(fallbackTemplate.ref, this.connectionOpts)) {
+				this._resolvedTemplateId = fallbackTemplate.ref;
+				return fallbackTemplate.ref;
+			}
+			const buildResult = await Template.build(fallbackTemplate.template, fallbackTemplate.ref, {
+				...this.connectionOpts,
+				...fallbackTemplate.buildResources
+			});
+			this._resolvedTemplateId = buildResult.templateId;
+			return buildResult.templateId;
+		} catch (error) {
+			this.logger.warn(`${LOG_PREFIX} Fallback template '${fallbackTemplate.ref}' failed too: ${error}`);
+			return await this.buildOrReuseDefaultTemplate();
+		}
+		if (fallbackTemplate) try {
+			const buildResult = await Template.build(fallbackTemplate, `mastra-fallback-${this.id.replace(/[^a-zA-Z0-9-]/g, "-")}`, this.connectionOpts);
+			this._resolvedTemplateId = buildResult.templateId;
+			return buildResult.templateId;
+		} catch (error) {
+			this.logger.warn(`${LOG_PREFIX} Fallback template build failed, using default: ${error}`);
+			return await this.buildOrReuseDefaultTemplate();
+		}
+		return await this.buildOrReuseDefaultTemplate();
+	}
+	/**
+	* Resources the configured template asked for. The default mountable
+	* template honors them too, so a repo template that falls back never
+	* silently downgrades the machine — a 2 GB session's setup would OOM in
+	* the 1 GB default. Per-size default templates cost one extra build each.
+	*/
+	requestedBuildResources() {
+		return (this.templateSpec && isNamedTemplateSpec(this.templateSpec) ? this.templateSpec : this._resolvedNamedSpec)?.buildResources;
+	}
+	async buildOrReuseDefaultTemplate() {
+		const { template, id, resources } = createDefaultMountableTemplate(this.requestedBuildResources());
+		if (await Template.exists(id, this.connectionOpts)) {
+			this.logger.debug(`${LOG_PREFIX} Using cached mountable template: ${id}`);
+			this._resolvedTemplateId = id;
+			return id;
+		}
+		this.logger.debug(`${LOG_PREFIX} Building default mountable template: ${id}...`);
+		const buildResult = await Template.build(template, id, {
+			...this.connectionOpts,
+			...resources
+		});
+		this._resolvedTemplateId = buildResult.templateId;
+		this.logger.debug(`${LOG_PREFIX} Template built and cached: ${buildResult.templateId}`);
+		return buildResult.templateId;
+	}
+	/**
 	* Build the default mountable template (bypasses exists check).
 	*
 	* Override point: called from the template-not-found retry path in
 	* `start()` when no explicit template was configured.
 	*/
 	async buildDefaultTemplate() {
-		const { template, id } = createDefaultMountableTemplate();
+		const { template, id, resources } = createDefaultMountableTemplate(this.requestedBuildResources());
 		this.logger.debug(`${LOG_PREFIX} Building default mountable template: ${id}...`);
-		const buildResult = await Template.build(template, id, this.connectionOpts);
+		const buildResult = await Template.build(template, id, {
+			...this.connectionOpts,
+			...resources
+		});
 		this._resolvedTemplateId = buildResult.templateId;
 		this.logger.debug(`${LOG_PREFIX} Template built: ${buildResult.templateId}`);
 		return buildResult.templateId;
@@ -1368,6 +1553,292 @@ var E2BSandbox = class E2BSandbox extends MastraSandbox {
 	}
 };
 //#endregion
+//#region src/utils/repo-template.ts
+/**
+* Sha-tagged repo templates.
+*
+* A repo template is an E2B template with the repository already cloned and
+* its dependencies installed at a known commit. Sessions started from it only
+* need `git fetch` + checkout of their actual ref plus setup drift, instead
+* of a cold clone + full install.
+*
+* There is exactly ONE template per (repo, setup command, workdir): the
+* template name is a deterministic `mastra-repo-<hash>` over those inputs,
+* and the commit sha rides as a docker-style TAG on that name
+* (`mastra-repo-<hash>:sha-<sha>`). A moved default branch produces a new
+* tag via a rebuild-in-place of the same template — old sha tags remain as
+* prunable build history instead of accumulating stale template names.
+* Builds are lazy: the first `E2BSandbox.start()` that resolves a missing
+* tag triggers the build; nothing pre-builds templates for idle repos.
+*
+* Credential invariant: a build credential may enter the template
+* DEFINITION (via `setEnvs`, visible to build steps but not persisted into
+* runtime sandbox environments) and the build process — never the image
+* filesystem. Clones authenticate through an in-shell computed
+* `http.extraheader`, so no tokened remote URL or credential file can land
+* in a captured layer. Callers must supply a short-lived credential (a
+* GitHub App installation token, which self-expires); never a long-lived
+* PAT. Without a credential the clone is plain tokenless HTTPS — public
+* repos build fine; a private repo's build fails and the sandbox falls back
+* to the fallback template, with the session's runtime setup performing the
+* full clone using its runtime-injected credential instead.
+*/
+const execFileAsync = promisify(execFile);
+const ALIAS_VERSION = "v5";
+/**
+* Stable tag assigned to every successful repo-template build. Points at the
+* latest build regardless of sha, so a moved head can boot from the previous
+* build (`name:current`) while the fresh sha builds in the background.
+*/
+const CURRENT_TAG = "current";
+/**
+* Env var carrying the repository credential during the build. The same
+* name a session installs before running setup, so a setup command sees the
+* same environment in both places. Set via `setEnvs`; the git auth header is
+* computed from it too.
+*/
+const BUILD_TOKEN_ENV = "GH_TOKEN";
+/**
+* Clone URLs interpolate into build shell commands, so constrain them to
+* https plus plain host/path characters. This rejects shell metacharacters
+* outright rather than escaping them. Every regex here is a single anchored
+* character class, so matching stays linear on adversarial input; the
+* structural checks (scheme, host, path segments) go through WHATWG URL
+* parsing instead of one big backtracking pattern.
+*/
+const CLONE_URL_ALLOWED_CHARS = /^[a-z0-9:/._-]+$/i;
+const CLONE_URL_HOST_PATTERN = /^[a-z0-9.-]+$/i;
+const CLONE_URL_SEGMENT_PATTERN = /^[\w.-]+$/;
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+function isValidCloneUrl(cloneUrl) {
+	if (cloneUrl.length > 2048 || !CLONE_URL_ALLOWED_CHARS.test(cloneUrl)) return false;
+	let url;
+	try {
+		url = new URL(cloneUrl);
+	} catch {
+		return false;
+	}
+	if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) return false;
+	if (!CLONE_URL_HOST_PATTERN.test(url.hostname)) return false;
+	const segments = url.pathname.split("/").slice(1);
+	return segments.length > 0 && segments.every((segment) => CLONE_URL_SEGMENT_PATTERN.test(segment));
+}
+/**
+* Compute the deterministic template ref for a set of repo template inputs
+* without constructing the builder: `mastra-repo-<hash>` named over
+* (clone URL, setup command, build env), tag-qualified with `:sha-<sha>`
+* when the sha is known. Exposed so callers (and proofs) can predict which
+* ref a sandbox will resolve.
+*/
+function repoTemplateRef(identity) {
+	const name = repoTemplateName(identity);
+	return identity.sha ? `${name}:${shaTag(identity.sha)}` : `${name}:${CURRENT_TAG}`;
+}
+function repoTemplateName(identity) {
+	const cloneUrl = normalizeCloneUrl(identity.cloneUrl);
+	const config = [
+		ALIAS_VERSION,
+		cloneUrl,
+		identity.setupCommand ?? null,
+		identity.buildEnv ? Object.entries(identity.buildEnv).sort(([a], [b]) => a.localeCompare(b)) : null,
+		identity.cpuCount ?? 2,
+		identity.memoryMB ?? 1024
+	];
+	const hash = createHash("sha256").update(JSON.stringify(config)).digest("hex").slice(0, 8);
+	const { owner, repo } = parseCloneUrl(cloneUrl);
+	return `mastra-repo-${[owner, repo].map((part) => (part ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-/, "").replace(/-$/, "").slice(0, 24)).filter(Boolean).join("-")}-${hash}`;
+}
+function shaTag(sha) {
+	return `sha-${sha.slice(0, 12).toLowerCase()}`;
+}
+/**
+* Create a sha-tagged repo template spec for `E2BSandbox`.
+*
+* Returns undefined when {@link RepoTemplateOptions.getRepositoryAccess} is
+* absent, which is how a session with no repository asks for no template —
+* so a host can write `template: createRepoTemplate(ctx)` without a
+* conditional.
+*
+* Resolution is deferred: right before the exists-then-build check it
+* resolves the clone URL and credential, resolves the repository's current
+* default-branch head (`git ls-remote`, ~100ms, no clone), and keys the
+* template ref as `mastra-repo-<hash>:sha-<head>` — so a moved default
+* branch produces a fresh tagged build of the SAME template on the next new
+* session (rebuild-in-place), and an unmoved head reuses the existing
+* tagged build. When the head cannot be resolved the ref degrades to the
+* untagged name and the build clones whatever the default branch is at
+* build time.
+*
+* When the build itself fails — inaccessible repo, registry flake — the
+* sandbox falls back to its fallback template and the session's runtime
+* setup performs the full clone, so a broken build never wedges a session.
+*/
+function createRepoTemplate(options) {
+	if (!options.getRepositoryAccess) return void 0;
+	return { resolveSpec: async () => (await resolveSpecAtHead(options)).spec };
+}
+/**
+* Resolve the clone URL and credential, resolve the current default-branch
+* head, and produce the concrete sha-tagged spec. Shared by the deferred
+* spec form and {@link refreshRepoTemplate}.
+*
+* A failed access call leaves no clone URL and throws, which the sandbox
+* turns into its default-template fallback rather than a failed start.
+*/
+async function resolveSpecAtHead(options) {
+	const access = options.getRepositoryAccess ? await options.getRepositoryAccess().catch(() => void 0) : void 0;
+	const cloneUrl = access?.cloneUrl;
+	if (!cloneUrl) throw new Error("Repo template has no clone URL: repository access returned none.");
+	assertCloneUrl(cloneUrl);
+	const token = access?.authorization?.token;
+	const buildEnv = typeof options.buildEnv === "function" ? await options.buildEnv() : options.buildEnv;
+	const resolved = await resolveDefaultBranchHead(cloneUrl, token).catch(() => void 0);
+	const sha = resolved && SHA_PATTERN.test(resolved) ? resolved : void 0;
+	return {
+		spec: buildRepoTemplateSpec({
+			cloneUrl,
+			...sha ? { sha } : {},
+			...options.setupCommand ? { setupCommand: options.setupCommand } : {},
+			...buildEnv ? { buildEnv } : {},
+			...options.cpuCount !== void 0 ? { cpuCount: options.cpuCount } : {},
+			...options.memoryMB !== void 0 ? { memoryMB: options.memoryMB } : {}
+		}, token),
+		...sha ? { sha } : {}
+	};
+}
+/**
+* Ensure the repo template is built at the repository's current
+* default-branch head, building it (and moving the `current` tag) when it
+* is not. This is the same resolution the lazy sandbox-start path performs
+* — exposed standalone so template warming can be driven externally: call
+* it from a scheduled workflow (cron) or a merge-to-main event handler and
+* the next session boots warm instead of paying the build.
+*
+* The build is awaited; a build failure rejects so callers can observe it.
+* An unresolvable head degrades to the sha-less `name:current` form, same
+* as the lazy path.
+*/
+async function refreshRepoTemplate(options, connection) {
+	const { spec, sha } = await resolveSpecAtHead(options);
+	const shaField = sha ? { sha } : {};
+	if (await Template.exists(spec.ref, connection)) return {
+		ref: spec.ref,
+		action: "reused",
+		...shaField
+	};
+	await Template.build(spec.template, spec.ref, {
+		...connection,
+		...spec.buildTags?.length ? { tags: spec.buildTags } : {},
+		...spec.buildResources
+	});
+	return {
+		ref: spec.ref,
+		action: "built",
+		...shaField
+	};
+}
+/**
+* The clone URL is the only untrusted input that reaches a build command,
+* so it is checked before it can be interpolated into one. The workdir is
+* derived from it rather than supplied, so it needs no separate guard.
+*/
+function assertCloneUrl(cloneUrl) {
+	if (!isValidCloneUrl(cloneUrl)) throw new Error(`Invalid cloneUrl '${cloneUrl}': expected an https URL with a plain host and path`);
+	if (parseCloneUrl(cloneUrl).repo === "") throw new Error(`Invalid cloneUrl '${cloneUrl}': expected a repository path such as https://host/owner/repo.git`);
+}
+/**
+* In-shell git auth flag: computes a basic-auth header from the build env
+* var at execution time. The stored command contains only the env-var
+* REFERENCE — the token value never appears in the command string, and no
+* credential is written to the build filesystem.
+*/
+function gitAuthFlag() {
+	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${BUILD_TOKEN_ENV}" | base64 -w0)"`;
+}
+function buildRepoTemplateSpec(identity, token) {
+	const { sha, setupCommand, buildEnv } = identity;
+	const cloneUrl = normalizeCloneUrl(identity.cloneUrl);
+	const workdir = defaultWorkdir(cloneUrl);
+	const auth = token ? `${gitAuthFlag()} ` : "";
+	const steps = [`git ${auth}clone ${cloneUrl} "${workdir}"`];
+	if (sha) steps.push(`git -C "${workdir}" ${auth}fetch origin ${sha}`, `git -C "${workdir}" checkout ${sha}`);
+	if (setupCommand) steps.push(`cd "${workdir}" && ${setupCommand}`);
+	let template = createDefaultMountableTemplate().template;
+	const env = { ...buildEnv };
+	if (token) env[BUILD_TOKEN_ENV] = token;
+	if (Object.keys(env).length > 0) template = template.setEnvs(env);
+	template = template.runCmd(steps);
+	return {
+		ref: repoTemplateRef(identity),
+		template,
+		staleRef: `${repoTemplateName(identity)}:${CURRENT_TAG}`,
+		buildTags: [CURRENT_TAG],
+		buildResources: {
+			cpuCount: identity.cpuCount ?? 2,
+			memoryMB: identity.memoryMB ?? 1024
+		}
+	};
+}
+/**
+* Resolve the repository's current default-branch head over HTTPS
+* (`git ls-remote <url> HEAD` — no clone; authenticated via an in-process
+* `http.extraheader` when a token is provided). Returns undefined when the
+* head cannot be resolved (inaccessible repo, offline, no git binary);
+* callers degrade to the untagged template ref.
+*/
+async function resolveDefaultBranchHead(cloneUrl, token) {
+	try {
+		const authArgs = token ? ["-c", `http.extraheader=AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`] : [];
+		const { stdout } = await execFileAsync("git", [
+			...authArgs,
+			"ls-remote",
+			"--",
+			cloneUrl,
+			"HEAD"
+		], {
+			timeout: 1e4,
+			env: {
+				...process.env,
+				GIT_TERMINAL_PROMPT: "0"
+			}
+		});
+		const sha = stdout.split(/\s/, 1)[0];
+		return sha && SHA_PATTERN.test(sha) ? sha : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Canonical form used for identity and for the build's clone: lowercase
+* host, no trailing `.git` or slash. Two spellings of one repository must
+* not produce two templates.
+*/
+function normalizeCloneUrl(cloneUrl) {
+	let end = cloneUrl.length;
+	while (end > 0 && cloneUrl[end - 1] === "/") end--;
+	return cloneUrl.slice(0, end).replace(/\.git$/i, "").replace(/^(https:\/\/)([^/]+)/i, (_match, scheme, host) => {
+		return `${scheme.toLowerCase()}${host.toLowerCase()}`;
+	});
+}
+/**
+* Split a normalized clone URL into its host and trailing owner/repo pair.
+* Hosts that nest groups (GitLab subgroups) keep only the last two path
+* segments as owner/repo; the full URL still drives identity.
+*/
+function parseCloneUrl(cloneUrl) {
+	const [host = "", ...segments] = normalizeCloneUrl(cloneUrl).replace(/^https:\/\//i, "").split("/");
+	const repo = segments.at(-1) ?? "";
+	return {
+		host,
+		owner: segments.length > 1 ? segments.at(-2) ?? "" : "",
+		repo
+	};
+}
+function defaultWorkdir(cloneUrl) {
+	const { repo } = parseCloneUrl(cloneUrl);
+	return `$HOME/${repo.replace(/[^\w.-]/g, "-").replace(/^\.+/, "") || "repo"}`;
+}
+//#endregion
 //#region src/provider.ts
 const e2bSandboxProvider = {
 	id: "e2b",
@@ -1618,6 +2089,6 @@ var E2BCodeModeTransport = class {
 	}
 };
 //#endregion
-export { E2BCodeModeTransport, E2BProcessManager, E2BSandbox, createDefaultMountableTemplate, e2bSandboxProvider };
+export { DEFAULT_NODE_VERSION, E2BCodeModeTransport, E2BProcessManager, E2BSandbox, createDefaultMountableTemplate, createRepoTemplate, e2bSandboxProvider, isDeferredNamedTemplateSpec, isNamedTemplateSpec, refreshRepoTemplate, repoTemplateRef };
 
 //# sourceMappingURL=index.js.map