@mastra/platform-workspace 1.4.1 → 1.5.0-alpha.0

package/dist/index.cjs

@@ -26,6 +26,8 @@ let path = require("path");
 path = __toESM(path, 1);
 let _mastra_core_workspace = require("@mastra/core/workspace");
 let e2b = require("e2b");
+let child_process = require("child_process");
+let util = require("util");
 //#region src/client.ts
 const DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
 /**
@@ -39,19 +41,19 @@ function requireOption(value, name) {
 	return value;
 }
 function resolveSandboxProvider(value) {
-	const provider = value?.trim() || "railway";
+	const provider = value?.trim() || "e2b";
 	if (provider !== "railway" && provider !== "e2b") throw new Error("SANDBOX_PROVIDER must be either \"railway\" or \"e2b\"");
 	return provider;
 }
 function resolvePlatformOptions(options) {
-	const configuredSandboxProvider = process.env.SANDBOX_PROVIDER?.trim();
+	const environmentSandboxProvider = process.env.SANDBOX_PROVIDER?.trim();
+	const configuredSandboxProvider = options.sandboxProvider ?? environmentSandboxProvider;
 	return {
 		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
 		projectId: requireOption(options.projectId ?? process.env.MASTRA_PROJECT_ID, "projectId"),
 		actingUserId: options.actingUserId?.trim() || void 0,
 		proxyUrl: (process.env.MASTRA_WORKSPACE_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/$/, ""),
 		sandboxProvider: resolveSandboxProvider(configuredSandboxProvider),
-		useLegacyRoutes: !configuredSandboxProvider,
 		sessionId: options.sessionId,
 		threadId: options.threadId,
 		fetch: options.fetch ?? fetch
@@ -99,7 +101,6 @@ var PlatformClient = class {
 	actingUserId;
 	proxyUrl;
 	sandboxProvider;
-	useLegacyRoutes;
 	/** Advisory session correlation id — see {@link PlatformClientOptions.sessionId}. */
 	sessionId;
 	/** Advisory thread correlation id — see {@link PlatformClientOptions.threadId}. */
@@ -112,13 +113,17 @@ var PlatformClient = class {
 		this.actingUserId = resolved.actingUserId;
 		this.proxyUrl = resolved.proxyUrl;
 		this.sandboxProvider = resolved.sandboxProvider;
-		this.useLegacyRoutes = resolved.useLegacyRoutes;
 		this.sessionId = resolved.sessionId;
 		this.threadId = resolved.threadId;
 		this.fetch = resolved.fetch;
 	}
 	async request(path, options = {}) {
-		const providerPath = this.useLegacyRoutes ? "" : `/${this.sandboxProvider}`;
+		return this.requestAtPath(`/${this.sandboxProvider}`, path, options);
+	}
+	async requestProvider(path, options = {}) {
+		return this.requestAtPath(`/${this.sandboxProvider}`, path, options);
+	}
+	async requestAtPath(providerPath, path, options) {
 		const url = new URL(`${this.proxyUrl}/v1${providerPath}/projects/${encodeURIComponent(this.projectId)}${path}`);
 		for (const [key, value] of Object.entries(options.query ?? {})) if (value !== void 0) url.searchParams.set(key, String(value));
 		const headers = new Headers(options.headers);
@@ -386,6 +391,185 @@ function matchesExtension(name, extension) {
 	return (Array.isArray(extension) ? extension : [extension]).some((ext) => name.endsWith(ext));
 }
 //#endregion
+//#region src/template.ts
+const SERIALIZE_TEMPLATE = Symbol("serializeTemplate");
+const GET_TEMPLATE_BUILD_ENVS = Symbol("getTemplateBuildEnvs");
+const MAX_OPERATIONS = 256;
+const MAX_SERIALIZED_BYTES = 256 * 1024;
+const MAX_STRING_LENGTH = 32 * 1024;
+const MAX_COLLECTION_ITEMS = 512;
+const MAX_FAMILY_LENGTH = 200;
+var SerializableSandboxTemplateBuilder = class SerializableSandboxTemplateBuilder {
+	#operations;
+	#family;
+	#buildEnvs;
+	constructor(operations = [], family, buildEnvs = {}) {
+		this.#operations = operations;
+		this.#family = family;
+		this.#buildEnvs = buildEnvs;
+	}
+	cpuCount(count) {
+		return this.#append("cpuCount", [validateResourceValue(count, "count")]);
+	}
+	memoryMB(memoryMB) {
+		return this.#append("memoryMB", [validateResourceValue(memoryMB, "memoryMB")]);
+	}
+	async build(options = {}) {
+		return buildSandboxTemplate(this, options);
+	}
+	runCmd(command) {
+		return this.#append("runCmd", [validateStringOrStrings(command, "command")]);
+	}
+	setWorkdir(path) {
+		return this.#append("setWorkdir", [validateString(path, "path")]);
+	}
+	setEnvs(envs, options) {
+		const copy = validateStringRecord(envs, "envs", "environment variable");
+		if ((options === void 0 ? void 0 : validateBooleanOptions(options, ["ephemeral"]))?.ephemeral === true) return new SerializableSandboxTemplateBuilder(this.#operations, this.#family, {
+			...this.#buildEnvs,
+			...copy
+		});
+		return this.#append("setEnvs", [copy]);
+	}
+	aptInstall(packages, options) {
+		const args = [validateStringOrStrings(packages, "packages")];
+		if (options !== void 0) args.push(validateBooleanOptions(options, ["noInstallRecommends", "fixMissing"]));
+		return this.#append("aptInstall", args);
+	}
+	pipInstall(packages, options) {
+		return this.#appendOptionalInstall("pipInstall", packages, options, ["g"]);
+	}
+	npmInstall(packages, options) {
+		return this.#appendOptionalInstall("npmInstall", packages, options, ["g", "dev"]);
+	}
+	withFamily(family) {
+		if (typeof family !== "string" || family.length === 0) throw new TypeError("family must be a non-empty string");
+		if (family.length > MAX_FAMILY_LENGTH) throw new RangeError(`family cannot exceed ${MAX_FAMILY_LENGTH} characters`);
+		assertSerializedSize(this.#operations, family);
+		return new SerializableSandboxTemplateBuilder(this.#operations, family, this.#buildEnvs);
+	}
+	[GET_TEMPLATE_BUILD_ENVS]() {
+		return Object.keys(this.#buildEnvs).length > 0 ? { ...this.#buildEnvs } : void 0;
+	}
+	[SERIALIZE_TEMPLATE]() {
+		return {
+			schemaVersion: 1,
+			operations: this.#operations.map((operation) => ({
+				method: operation.method,
+				args: cloneJson(operation.args)
+			})),
+			...this.#family !== void 0 && { family: this.#family }
+		};
+	}
+	#appendOptionalInstall(method, packages, options, optionKeys) {
+		const args = [];
+		if (packages !== void 0) args.push(validateStringOrStrings(packages, "packages"));
+		if (options !== void 0) {
+			if (packages === void 0) args.push(null);
+			args.push(validateBooleanOptions(options, optionKeys));
+		}
+		return this.#append(method, args);
+	}
+	#append(method, args) {
+		if (this.#operations.length >= MAX_OPERATIONS) throw new RangeError(`Sandbox template cannot contain more than ${MAX_OPERATIONS} operations`);
+		const operation = {
+			method,
+			args: cloneJson(args)
+		};
+		const operations = [...this.#operations, operation];
+		assertSerializedSize(operations, this.#family);
+		return new SerializableSandboxTemplateBuilder(operations, this.#family, this.#buildEnvs);
+	}
+};
+function assertSerializedSize(operations, family) {
+	const serialized = JSON.stringify({
+		schemaVersion: 1,
+		operations,
+		...family !== void 0 && { family }
+	});
+	if (new TextEncoder().encode(serialized).byteLength > MAX_SERIALIZED_BYTES) throw new RangeError(`Serialized sandbox template cannot exceed ${MAX_SERIALIZED_BYTES} bytes`);
+}
+function Template() {
+	return new SerializableSandboxTemplateBuilder();
+}
+function isSandboxTemplateBuilder(value) {
+	return value instanceof SerializableSandboxTemplateBuilder;
+}
+function serializeSandboxTemplate(template) {
+	if (!isSandboxTemplateBuilder(template)) throw new TypeError("template must be created with Template()");
+	return template[SERIALIZE_TEMPLATE]();
+}
+function getSandboxTemplateBuildEnvs(template) {
+	if (!isSandboxTemplateBuilder(template)) throw new TypeError("template must be created with Template()");
+	return template[GET_TEMPLATE_BUILD_ENVS]();
+}
+async function buildSandboxTemplate(template, options) {
+	const environmentId = options.environmentId ?? process.env.MASTRA_ENVIRONMENT_ID;
+	if (!environmentId) throw new Error("environmentId is required. Pass it or set MASTRA_ENVIRONMENT_ID.");
+	const client = new PlatformClient(options);
+	const templateBuildEnvs = getSandboxTemplateBuildEnvs(template);
+	return await (await client.requestProvider("/sandbox/templates/builds", {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			environmentId,
+			templateDefinition: serializeSandboxTemplate(template),
+			...templateBuildEnvs !== void 0 && { templateBuildEnvs }
+		})
+	})).json();
+}
+function validateResourceValue(value, name) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+	return value;
+}
+function validateString(value, name, allowEmpty = false) {
+	if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+	if (!allowEmpty && value.length === 0) throw new TypeError(`${name} must not be empty`);
+	if (value.length > MAX_STRING_LENGTH) throw new RangeError(`${name} cannot exceed ${MAX_STRING_LENGTH} characters`);
+	return value;
+}
+function validateStringOrStrings(value, name) {
+	if (typeof value === "string") return validateString(value, name);
+	if (!Array.isArray(value)) throw new TypeError(`${name} must be a string or an array of strings`);
+	assertCollectionSize(value.length, name);
+	if (value.length === 0) throw new TypeError(`${name} must not be empty`);
+	return Array.from(value, (item, index) => validateString(item, `${name}[${index}]`));
+}
+function validateStringRecord(value, name, entryName) {
+	assertPlainObject(value, name);
+	const entries = Object.entries(value);
+	assertCollectionSize(entries.length, name);
+	return Object.fromEntries(entries.map(([key, item]) => [validateString(key, `${entryName} name`), validateString(item, `${entryName} ${key}`, true)]));
+}
+function validateBooleanOptions(value, keys) {
+	assertPlainObject(value, "options");
+	const options = value;
+	const unknownKey = Object.keys(options).find((key) => !keys.includes(key));
+	if (unknownKey) throw new TypeError(`Unsupported option: ${unknownKey}`);
+	const copy = {};
+	for (const key of keys) {
+		const option = options[key];
+		if (option === void 0) continue;
+		if (typeof option !== "boolean") throw new TypeError(`${key} must be a boolean`);
+		copy[key] = option;
+	}
+	return copy;
+}
+function assertPlainObject(value, name) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(`${name} must be a plain object`);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new TypeError(`${name} must be a plain object`);
+}
+function assertCollectionSize(size, name) {
+	if (size > MAX_COLLECTION_ITEMS) throw new RangeError(`${name} cannot contain more than ${MAX_COLLECTION_ITEMS} items`);
+}
+function cloneJson(value) {
+	if (Array.isArray(value)) return value.map((item) => cloneJson(item));
+	if (typeof value === "object" && value !== null) return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneJson(item)]));
+	if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError("Sandbox template values must contain only finite numbers");
+	return value;
+}
+//#endregion
 //#region src/direct-exec.ts
 /**
 * Direct exec client — opens Railway's tcp-proxy exec WebSocket directly using
@@ -926,10 +1110,26 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	name = "PlatformSandbox";
 	provider = "platform";
 	status = "pending";
+	/**
+	* Populated from the platform's create/reattach response when the sandbox
+	* booted from a prior member of the same template family or the provider
+	* base template while the requested exact template continues to build in
+	* the background.
+	* `undefined` when the sandbox booted on the exact template (or when no
+	* template was requested). Observability-only; consumers reconcile freshness
+	* in their own runtime setup and reprovision to pick up the ready template
+	* on a later start.
+	*/
+	templatePending;
 	_client;
+	_usesProviderRoutes;
 	_environmentId;
 	_sandboxId;
 	_seedCheckpointName;
+	_templateDefinition;
+	_templateBuildEnvs;
+	_template;
+	_templateResolutionInFlight;
 	_idleTimeoutMinutes;
 	_networkIsolation;
 	_env;
@@ -1017,6 +1217,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		if (!this._environmentId && !options.sandboxId) throw new Error("environmentId is required");
 		this._sandboxId = options.sandboxId;
 		this._seedCheckpointName = options.seedCheckpointName;
+		this._usesProviderRoutes = options.template !== void 0;
+		this._template = options.template;
 		this._idleTimeoutMinutes = options.idleTimeoutMinutes;
 		this._networkIsolation = options.networkIsolation;
 		this._env = options.env ?? {};
@@ -1030,6 +1232,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	generateId() {
 		return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
 	}
+	_request(path, options = {}) {
+		return this._usesProviderRoutes ? this._client.requestProvider(path, options) : this._client.request(path, options);
+	}
 	/**
 	* Construct a sibling {@link PlatformSandbox} that inherits this sandbox's
 	* credentials and defaults (access token, project, environment, network
@@ -1045,10 +1250,11 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	clone(options = {}) {
 		const id = options.id ?? options.checkpointName;
 		const seedCheckpointName = options.seedCheckpointName ?? (this._client.sandboxProvider === "e2b" ? options.checkpointName : void 0) ?? this._seedCheckpointName;
-		return new PlatformSandbox({
+		const clone = new PlatformSandbox({
 			...id !== void 0 && { id },
 			accessToken: this._client.accessToken,
 			projectId: this._client.projectId,
+			...this._usesProviderRoutes || this._client.sandboxProvider !== "railway" ? { sandboxProvider: this._client.sandboxProvider } : {},
 			actingUserId: options.actingUserId ?? this._client.actingUserId,
 			...this._client.sessionId !== void 0 && { sessionId: this._client.sessionId },
 			...this._client.threadId !== void 0 && { threadId: this._client.threadId },
@@ -1056,6 +1262,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			environmentId: this._environmentId,
 			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
 			...seedCheckpointName !== void 0 && { seedCheckpointName },
+			...this._template !== void 0 && { template: this._template },
 			idleTimeoutMinutes: options.idleTimeoutMinutes ?? this._idleTimeoutMinutes,
 			...this._networkIsolation !== void 0 && { networkIsolation: this._networkIsolation },
 			env: options.env ?? this._env,
@@ -1066,6 +1273,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			...this._privateNetFetch !== void 0 && { privateNetFetch: this._privateNetFetch },
 			...this._addressRegistry !== void 0 && { addressRegistry: this._addressRegistry }
 		});
+		clone._templateDefinition = this._templateDefinition ? structuredClone(this._templateDefinition) : void 0;
+		clone._templateBuildEnvs = this._templateBuildEnvs ? { ...this._templateBuildEnvs } : void 0;
+		return clone;
 	}
 	/**
 	* Start the sandbox: reattach to a known provider `sandboxId` when one is
@@ -1084,7 +1294,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const startedAt = Date.now();
 		if (this._sandboxId) try {
 			const requestStartedAt = Date.now();
-			const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
+			const response = await this._request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
 			const requestMs = Date.now() - requestStartedAt;
 			const json = await response.json();
 			if (!json.destroyedAt) {
@@ -1099,9 +1309,12 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			this._sandboxId = void 0;
 		}
 		if (!this._environmentId) throw new Error("environmentId is required");
-		const body = JSON.stringify({
+		await this._prepareLazyTemplate();
+		const createBody = () => JSON.stringify({
 			id: this.id,
 			seedCheckpointName: this._seedCheckpointName,
+			templateDefinition: this._templateDefinition,
+			templateBuildEnvs: this._templateBuildEnvs,
 			environmentId: this._environmentId,
 			idleTimeoutMinutes: this._idleTimeoutMinutes,
 			networkIsolation: this._networkIsolation,
@@ -1110,10 +1323,10 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		let response;
 		const requestStartedAt = Date.now();
 		for (let attempt = 1;; attempt++) try {
-			response = await this._client.request("/sandbox", {
+			response = await this._request("/sandbox", {
 				method: "POST",
 				headers: { "content-type": "application/json" },
-				body
+				body: createBody()
 			});
 			break;
 		} catch (error) {
@@ -1124,10 +1337,31 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const json = await response.json();
 		this._sandboxId = json.id;
 		this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+		this.templatePending = json.templatePending;
 		this._populateAddressFromResponse(json);
 		this._logStartComplete(json.id, startedAt, requestMs, "provision");
 		return { outcome: "created" };
 	}
+	async _prepareLazyTemplate() {
+		if (this._templateDefinition !== void 0 || this._template === void 0) return;
+		if (!this._templateResolutionInFlight) {
+			const attempt = this._resolveTemplate();
+			this._templateResolutionInFlight = attempt.finally(() => {
+				this._templateResolutionInFlight = void 0;
+			});
+		}
+		await this._templateResolutionInFlight;
+	}
+	async _resolveTemplate() {
+		try {
+			const resolved = typeof this._template === "function" ? await this._template() : this._template;
+			if (!resolved) return;
+			this._templateDefinition = serializeSandboxTemplate(resolved);
+			this._templateBuildEnvs = getSandboxTemplateBuildEnvs(resolved);
+		} catch (error) {
+			this.logger.warn(`Platform sandbox template resolution failed; using provider default template: ${String(error)}`);
+		}
+	}
 	/**
 	* One timing summary per completed `start()` — the whole
 	* `PlatformSandbox`-visible boot in a single greppable line.
@@ -1292,7 +1526,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const destroyedSandboxId = this._sandboxId;
 		this._captureInFlight = null;
 		if (this._hasRecoveryKey || this._client.sandboxProvider === "e2b") try {
-			await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
+			await this._request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
 				method: "DELETE",
 				headers: { "content-type": "application/json" },
 				body: JSON.stringify({ id: this.id })
@@ -1319,7 +1553,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		this._probeGeneration++;
 		this._probeTarget = null;
 		this._transportReadyPromise = null;
-		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
+		await this._request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
 		this._lease = null;
@@ -1409,7 +1643,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	async _doCaptureCheckpoint(sandboxId) {
 		let response;
 		try {
-			response = await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/checkpoint`, {
+			response = await this._request(`/sandbox/${encodeURIComponent(sandboxId)}/checkpoint`, {
 				method: "POST",
 				headers: { "content-type": "application/json" },
 				body: JSON.stringify({ id: this.id })
@@ -1540,8 +1774,20 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* Returns a result with a real `exitCode` OR `timedOut: true`. Never
 	* returns `{ exitCode: null, timedOut: false }` — that case throws.
 	*/
+	/**
+	* Drop undefined values so the result matches the Record<string, string>
+	* shape the exec transports expect (`ExecuteCommandOptions.env` is
+	* NodeJS.ProcessEnv). The sandbox's own env is already merged in by
+	* `executeCommand` before a transport sees these options. Returns undefined
+	* when there is nothing to send.
+	*/
+	_execEnv(options) {
+		if (!options?.env) return void 0;
+		const filtered = Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0));
+		return Object.keys(filtered).length > 0 ? filtered : void 0;
+	}
 	async _runDirectExec(fullCommand, effectiveTimeout, options) {
-		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		const filteredEnv = this._execEnv(options);
 		let lastResult;
 		let lastLease;
 		let attemptsMade = 0;
@@ -1604,7 +1850,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	*   sidecar bug). Only this specific exec falls back.
 	*/
 	async _tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options) {
-		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		const filteredEnv = this._execEnv(options);
 		const execOptions = {
 			command: fullCommand,
 			...options?.cwd !== void 0 && { cwd: options.cwd },
@@ -1653,7 +1899,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		if (!this._sandboxId) throw new _mastra_core_workspace.SandboxNotReadyError(this.id);
 		const sandboxId = this._sandboxId;
 		const inFlight = (async () => {
-			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/exec-lease`, { method: "POST" })).json();
+			const json = await (await this._request(`/sandbox/${encodeURIComponent(sandboxId)}/exec-lease`, { method: "POST" })).json();
 			const expiresAtMs = json.expiresAt ? Date.parse(json.expiresAt) : null;
 			const lease = {
 				provider: json.provider,
@@ -1691,7 +1937,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			createdAt: this._createdAt ?? /* @__PURE__ */ new Date(),
 			metadata: { sandboxId: this._sandboxId }
 		};
-		const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
+		const json = await (await this._request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
 		return {
 			id: json.id,
 			name: this.name,
@@ -1716,6 +1962,122 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	}
 };
 //#endregion
+//#region src/repo-template.ts
+const execFileAsync = (0, util.promisify)(child_process.execFile);
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+const BUILD_TOKEN_ENV = "MASTRA_REPOSITORY_ACCESS_TOKEN";
+/**
+* Clone URLs interpolate into the template's build commands, so constrain
+* them to https plus plain host/path characters. Every regex here is a
+* single anchored character class, so matching stays linear on adversarial
+* input; the structural checks 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.-]+$/;
+/**
+* Create a lazy repository template definition for PlatformSandbox, mirroring
+* `@mastra/e2b`'s `createRepoTemplate`: pass the sandbox context through and a
+* repo-less session boots the provider default.
+*
+* The resolver performs no work until a fresh sandbox starts. It clones the
+* URL `getRepositoryAccess` resolves — the only source of the clone URL, so
+* what gets cloned and what the template is identified by can't drift — and
+* pins repositories to their current default-branch commit. Private repository
+* credentials are used for head resolution and sent to the provider as
+* transient build envs; they never enter the serialized definition. If the
+* head cannot be resolved, the resolver returns undefined so PlatformSandbox
+* boots from the provider default and the caller's runtime setup materializes
+* the checkout instead.
+*/
+function createRepoTemplate(options) {
+	const getRepositoryAccess = options.getRepositoryAccess;
+	if (!getRepositoryAccess) return void 0;
+	const resolveHead = options.resolveHead ?? resolveDefaultBranchHead;
+	return async () => {
+		const access = await getRepositoryAccess().catch(() => void 0);
+		if (!access?.cloneUrl) return void 0;
+		const cloneUrl = normalizeCloneUrl(access.cloneUrl);
+		if (!isValidCloneUrl(cloneUrl)) return void 0;
+		const token = access.authorization?.token;
+		const sha = await (token ? resolveHead(cloneUrl, token) : resolveHead(cloneUrl)).catch(() => void 0);
+		if (!sha || !SHA_PATTERN.test(sha)) return void 0;
+		const workdir = defaultWorkdir(cloneUrl);
+		const auth = token ? `${gitAuthFlag()} ` : "";
+		const steps = [
+			`git ${auth}clone ${cloneUrl} "${workdir}"`,
+			`git -C "${workdir}" ${auth}fetch origin ${sha}`,
+			`git -C "${workdir}" checkout ${sha}`,
+			...options.setupCommand ? [`cd "${workdir}" && ${options.setupCommand}`] : []
+		];
+		const family = `repo:${cloneUrl}:${workdir}`;
+		let template = Template();
+		if (token) template = template.setEnvs({ [BUILD_TOKEN_ENV]: token }, { ephemeral: true });
+		if (options.cpuCount !== void 0) template = template.cpuCount(options.cpuCount);
+		if (options.memoryMB !== void 0) template = template.memoryMB(options.memoryMB);
+		return template.runCmd(steps).withFamily(family);
+	};
+}
+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));
+}
+/**
+* Canonical form used for identity, the family key, and 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()}`;
+	});
+}
+function defaultWorkdir(cloneUrl) {
+	return `$HOME/${(normalizeCloneUrl(cloneUrl).split("/").at(-1) ?? "").replace(/[^\w.-]/g, "-").replace(/^\.+/, "") || "repo"}`;
+}
+function gitAuthFlag() {
+	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${BUILD_TOKEN_ENV}" | base64 -w0)"`;
+}
+async function resolveDefaultBranchHead(cloneUrl, token, execute = execFileAsync) {
+	try {
+		const env = {
+			...process.env,
+			GIT_TERMINAL_PROMPT: "0"
+		};
+		if (token) {
+			env.GIT_CONFIG_COUNT = "1";
+			env.GIT_CONFIG_KEY_0 = "http.extraheader";
+			env.GIT_CONFIG_VALUE_0 = `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`;
+		}
+		const { stdout } = await execute("git", [
+			"ls-remote",
+			"--",
+			cloneUrl,
+			"HEAD"
+		], {
+			timeout: 1e4,
+			maxBuffer: 1024 * 1024,
+			env
+		});
+		const sha = stdout.trim().split(/\s+/, 1)[0];
+		return sha && SHA_PATTERN.test(sha) ? sha : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/provider.ts
 const platformSandboxProvider = {
 	id: "platform",
@@ -1736,6 +2098,12 @@ const platformSandboxProvider = {
 				type: "string",
 				description: "Opaque user subject attributed to sandbox requests"
 			},
+			sandboxProvider: {
+				type: "string",
+				description: "Sandbox provider (falls back to SANDBOX_PROVIDER, then e2b)",
+				enum: ["railway", "e2b"],
+				default: "e2b"
+			},
 			environmentId: {
 				type: "string",
 				description: "Platform environment ID (falls back to MASTRA_ENVIRONMENT_ID)"
@@ -1837,6 +2205,8 @@ exports.PlatformSandbox = PlatformSandbox;
 exports.PrivateNetExecHttpError = PrivateNetExecHttpError;
 exports.SandboxDestroyedError = SandboxDestroyedError;
 exports.SandboxExecTransportError = SandboxExecTransportError;
+exports.Template = Template;
+exports.createRepoTemplate = createRepoTemplate;
 exports.execViaPrivateNetwork = execViaPrivateNetwork;
 exports.platformFilesystemProvider = platformFilesystemProvider;
 exports.platformSandboxProvider = platformSandboxProvider;