@mastra/platform-workspace 1.6.2 → 1.7.0-alpha.1

package/dist/index.cjs

@@ -27,8 +27,8 @@ 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");
 let crypto = require("crypto");
+let util = require("util");
 //#region src/client.ts
 const DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
 const REGIONAL_PROXY_URLS = {
@@ -1076,9 +1076,9 @@ var SandboxDestroyedError = class extends Error {
 * sandbox.
 */
 function buildCommand(command, args) {
-	return args?.length ? `${command} ${args.map(shellQuote$1).join(" ")}` : command;
+	return args?.length ? `${command} ${args.map(shellQuote$2).join(" ")}` : command;
 }
-function shellQuote$1(arg) {
+function shellQuote$2(arg) {
 	if (/^[a-zA-Z0-9._\-/=:@]+$/.test(arg)) return arg;
 	return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
@@ -1151,6 +1151,16 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* on a later start.
 	*/
 	templatePending;
+	/**
+	* The platform's id for the provisioned sandbox, as returned by the create
+	* or reattach response. Persist this to reattach later via the `sandboxId`
+	* option. Undefined until the sandbox has been started in this process; a
+	* `sandboxId` passed to the constructor is only a hint for `start()` and is
+	* not reported here until the proxy confirms it.
+	*/
+	get sandboxId() {
+		return this.status === "running" ? this._sandboxId : void 0;
+	}
 	_client;
 	_usesProviderRoutes;
 	_environmentId;
@@ -1335,7 +1345,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			}
 			this._sandboxId = void 0;
 		} catch (error) {
-			if (!(error instanceof PlatformApiError) || error.status !== 404) throw error;
+			if (!(error instanceof PlatformApiError) || error.status !== 404 && error.status !== 410) throw error;
 			this._sandboxId = void 0;
 		}
 		if (!this._environmentId) throw new Error("environmentId is required");
@@ -1518,23 +1528,28 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		await Promise.race([this._transportReadyPromise, new Promise((r) => setTimeout(r, TRANSPORT_READY_WAIT_MS))]);
 	}
 	/**
-	* Stop the sandbox while **preserving its recovery checkpoint**.
+	* Stop this process's use of the sandbox without touching the remote one.
 	*
-	* Semantic parity with `@mastra/railway` `RailwaySandbox.stop()`: the VM
-	* is released but the on-provider checkpoint survives, so a subsequent
-	* `start()` on a sandbox constructed with the same `id` can restore from
-	* it. Any in-flight capture is awaited first so the preserved checkpoint
-	* reflects the latest disk state we asked for.
+	* Nothing is sent to workspace-proxy. The VM keeps running and idles out
+	* under the environment's own idle policy, the recovery checkpoint stays,
+	* and `_sandboxId` is kept so a later `start()` on this instance, or on a
+	* new instance constructed with the same `id` or `sandboxId`, reattaches
+	* instead of provisioning. `Mastra.shutdown()` stops every registered
+	* workspace on SIGINT; releasing the VM here would destroy every live
+	* session on a host restart. Use {@link destroy} to release the VM and
+	* its checkpoint.
 	*
-	* Corresponds to `DELETE /v1/:provider/projects/:pid/sandbox/:sandboxId` on
-	* workspace-proxy, which by contract does not touch the checkpoint. Use
-	* {@link destroy} when you want the checkpoint released too.
+	* Any in-flight capture is awaited first so the checkpoint reflects the
+	* latest disk state the caller asked for.
 	*/
 	async stop() {
 		if (this._captureInFlight) await this._captureInFlight.catch((error) => {
-			this.logger.warn(`stop(): failed to flush in-flight capture before teardown:`, error);
+			this.logger.warn(`stop(): failed to flush in-flight capture before stop:`, error);
 		});
-		await this._teardownSandbox();
+		this._probeGeneration++;
+		this._probeTarget = null;
+		this._transportReadyPromise = null;
+		this._lease = null;
 	}
 	/**
 	* Destroy the sandbox **and release its recovery checkpoint**.
@@ -1571,12 +1586,9 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	/**
 	* Release the remote sandbox VM and clear the local state pointing at it.
 	*
-	* Shared body of {@link stop} and {@link destroy} — both funnel through
-	* here after they've dealt with the checkpoint (preserve vs release).
-	* The VM DELETE is safe to issue in either mode: the proxy's DELETE
-	* route does not touch the checkpoint on its own, so `stop()` correctly
-	* leaves the checkpoint intact and `destroy()` has already removed it
-	* before this call.
+	* Body of {@link destroy}, called after the checkpoint has been released.
+	* The proxy's DELETE route releases the VM (on E2B that kills it), so
+	* only destroy() may reach here; stop() never does.
 	*/
 	async _teardownSandbox() {
 		if (!this._sandboxId) return;
@@ -1955,7 +1967,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		}
 	}
 	async getInfo() {
-		if (!this._sandboxId) return {
+		if (!this._sandboxId || this.status !== "running") return {
 			id: this.id,
 			name: this.name,
 			provider: this.provider,
@@ -1996,6 +2008,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 };
 //#endregion
 //#region ../../packages/_internals/workspace/dist/index.js
+/** Directory, relative to the template's build cwd, that holds every marker below. */
+const SETUP_MARKER_DIR = ".mastra-sandbox";
 /**
 * Setup completion marker shared by repo templates and their consumers.
 *
@@ -2005,8 +2019,29 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 * booted from the image tell whether the setup it is about to run already
 * happened. Relative to the template's build cwd, which is also the runtime
 * working directory the repo was cloned into.
+*
+* This is the single-repository marker. Templates built from a repository
+* list write one marker per repository instead ({@link repoSetupMarkerPath}).
 */
 const SETUP_MARKER_PATH = ".mastra-sandbox/setup";
+/**
+* Marker for the workspace-level setup of a multi-repository template: the
+* commands that ran at the working directory after every repository was set
+* up. Written even when there were no such commands, so a consumer can tell
+* "ran nothing" from "never built".
+*/
+const WORKSPACE_SETUP_MARKER_PATH = ".mastra-sandbox/workspace-setup";
+/**
+* One line per repository directory whose setup failed while the build was
+* told to continue. Absent when nothing failed. Consumers check this before
+* trusting a per-repository marker: that marker means every step ran, not
+* that every step succeeded.
+*/
+const SETUP_FAILED_MARKER_PATH = ".mastra-sandbox/setup-failed";
+/** Per-repository marker of a multi-repository template, keyed by the clone directory name. */
+function repoSetupMarkerPath(repoDir) {
+	return `${SETUP_MARKER_DIR}/repos/${repoDir}`;
+}
 /** Blank entries never become build steps, so they never count toward the digest either. */
 function normalizeSetupCommands(setupCommand) {
 	return (setupCommand === void 0 ? [] : Array.isArray(setupCommand) ? setupCommand : [setupCommand]).filter((command) => command.trim() !== "");
@@ -2016,8 +2051,26 @@ function setupMarkerContent(setupCommand) {
 	return `sha256:${(0, crypto.createHash)("sha256").update(normalizeSetupCommands(setupCommand).join("\n")).digest("hex")}`;
 }
 /** Shell step that writes the marker relative to the cwd. `content` is a digest, so it is shell-safe. */
-function setupMarkerCommand(content) {
-	return `mkdir -p "$(dirname "${SETUP_MARKER_PATH}")" && printf '%s' '${content}' > "${SETUP_MARKER_PATH}"`;
+function setupMarkerCommand(content, markerPath = SETUP_MARKER_PATH) {
+	return `mkdir -p "$(dirname "${markerPath}")" && printf '%s' '${content}' > "${markerPath}"`;
+}
+/** A clone directory name is one path segment of word characters, dots and dashes, so it never needs quoting. */
+const REPO_DIR_PATTERN = /^[\w.-]+$/;
+/**
+* Shell step that runs one setup command inside a repository clone.
+*
+* Without the guard this is the plain `cd "<dir>" && <cmd>` step. With it,
+* the `cd` sits inside the parenthesized group so that the failure branch
+* runs back at the build cwd and the failure list lands at the workspace
+* level, never inside the repository.
+*/
+function guardedSetupCommand({ repoDir, command, continueOnFailure }) {
+	if (!REPO_DIR_PATTERN.test(repoDir)) throw new TypeError(`Repository directory "${repoDir}" must match ${REPO_DIR_PATTERN}.`);
+	if (!continueOnFailure) return `cd "${repoDir}" && ${command}`;
+	return `( cd "${repoDir}" && sh -c ${shellQuote$1(command)} ) || { mkdir -p "${SETUP_MARKER_DIR}" && grep -qxF -- '${repoDir}' "${SETUP_FAILED_MARKER_PATH}" 2>/dev/null || printf '%s\\n' '${repoDir}' >> "${SETUP_FAILED_MARKER_PATH}"; }`;
+}
+function shellQuote$1(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function repoCloneCommand({ cloneUrl, destination, branch, tokenEnv }) {
 	return `git ${tokenEnv ? `${gitAuthFlag$1(tokenEnv)} ` : ""}clone --depth=1 --single-branch ${branch ? `--branch ${shellQuote(branch)} ` : ""}${shellQuote(cloneUrl)} ${shellQuote(destination)}`;
@@ -2070,77 +2123,126 @@ function rememberHead(cloneUrl, sha) {
 * requested size, and the caller's runtime setup materializes the checkout.
 */
 function createRepoTemplate(options) {
-	const getRepositoryAccess = options.getRepositoryAccess;
+	if (options.getRepositoryAccess && options.repos) throw new TypeError("createRepoTemplate: pass either getRepositoryAccess or repos, not both");
+	if (!options.repos && (options.workspaceSetupCommand !== void 0 || options.continueOnSetupFailure !== void 0)) throw new TypeError("createRepoTemplate: workspaceSetupCommand and continueOnSetupFailure require repos");
+	const isList = options.repos !== void 0;
+	const entries = options.repos ? options.repos : options.getRepositoryAccess ? [{
+		getRepositoryAccess: options.getRepositoryAccess,
+		setupCommand: options.setupCommand
+	}] : [];
 	const resourcesOnly = () => {
 		if (options.cpuCount === void 0 && options.memoryMB === void 0) return void 0;
 		return withResources(Template(), options);
 	};
-	if (!getRepositoryAccess) {
+	if (entries.length === 0) {
 		const template = resourcesOnly();
 		return template ? async () => template : void 0;
 	}
 	const resolveHead = options.resolveHead ?? resolveDefaultBranchHead;
+	const continueOnFailure = options.continueOnSetupFailure ?? false;
 	return async () => {
-		let accessError;
-		const access = await getRepositoryAccess().catch((error) => {
-			accessError = error;
-		});
-		if (!access?.cloneUrl) {
-			console.warn("[platform-workspace] repo template skipped: repository access unavailable", { error: redactSecrets(accessError) });
-			return resourcesOnly();
-		}
-		const cloneUrl = normalizeCloneUrl(access.cloneUrl);
-		if (!isValidCloneUrl(cloneUrl)) {
-			console.warn("[platform-workspace] repo template skipped: clone URL failed validation", { cloneUrl: redactSecrets(cloneUrl) });
-			return resourcesOnly();
-		}
-		const token = access.authorization?.token;
-		let headError;
-		const resolved = await (token ? resolveHead(cloneUrl, token) : resolveHead(cloneUrl)).catch((error) => {
-			headError = error;
-		});
-		let sha;
-		if (resolved && SHA_PATTERN.test(resolved)) {
-			sha = resolved;
-			rememberHead(cloneUrl, sha);
-		} else {
-			const lastKnown = lastKnownHeads.get(cloneUrl);
-			if (!lastKnown) {
-				console.warn("[platform-workspace] repo template skipped: could not resolve default-branch head", {
+		const repos = [];
+		for (const [index, entry] of entries.entries()) {
+			let accessError;
+			const access = await entry.getRepositoryAccess().catch((error) => {
+				accessError = error;
+			});
+			if (!access?.cloneUrl) {
+				console.warn("[platform-workspace] repo template skipped: repository access unavailable", {
+					...isList ? { index } : {},
+					error: redactSecrets(accessError)
+				});
+				return resourcesOnly();
+			}
+			const cloneUrl = normalizeCloneUrl(access.cloneUrl);
+			if (!isValidCloneUrl(cloneUrl)) {
+				console.warn("[platform-workspace] repo template skipped: clone URL failed validation", {
+					...isList ? { index } : {},
+					cloneUrl: redactSecrets(cloneUrl)
+				});
+				return resourcesOnly();
+			}
+			const token = access.authorization?.token;
+			let headError;
+			const resolved = await (token ? resolveHead(cloneUrl, token) : resolveHead(cloneUrl)).catch((error) => {
+				headError = error;
+			});
+			let sha;
+			if (resolved && SHA_PATTERN.test(resolved)) {
+				sha = resolved;
+				rememberHead(cloneUrl, sha);
+			} else {
+				const lastKnown = lastKnownHeads.get(cloneUrl);
+				if (lastKnown) {
+					console.warn("[platform-workspace] repo template pinned to the last known default-branch head", {
+						cloneUrl,
+						sha: lastKnown,
+						resolved,
+						error: redactSecrets(headError)
+					});
+					sha = lastKnown;
+				} else if (isList) console.warn("[platform-workspace] repo template clones unpinned: could not resolve default-branch head", {
 					cloneUrl,
 					sha: resolved,
 					error: redactSecrets(headError)
 				});
-				return resourcesOnly();
+				else {
+					console.warn("[platform-workspace] repo template skipped: could not resolve default-branch head", {
+						cloneUrl,
+						sha: resolved,
+						error: redactSecrets(headError)
+					});
+					return resourcesOnly();
+				}
 			}
-			console.warn("[platform-workspace] repo template pinned to the last known default-branch head", {
+			const repoDir = repoDirName(cloneUrl);
+			repos.push({
+				index,
 				cloneUrl,
-				sha: lastKnown,
-				resolved,
-				error: redactSecrets(headError)
+				repoDir,
+				token,
+				tokenEnv: token ? isList ? `${BUILD_TOKEN_ENV}_${index}` : BUILD_TOKEN_ENV : void 0,
+				sha,
+				setupCommands: normalizeSetupCommands(entry.setupCommand)
 			});
-			sha = lastKnown;
+		}
+		const seenDirs = /* @__PURE__ */ new Map();
+		for (const repo of repos) {
+			const other = seenDirs.get(repo.repoDir);
+			if (other) throw new Error(`createRepoTemplate: repositories ${other} and ${repo.cloneUrl} would both clone into "${repo.repoDir}"`);
+			seenDirs.set(repo.repoDir, repo.cloneUrl);
 		}
 		const workingDirectory = options.workingDirectory === void 0 ? void 0 : trimTrailingSlashes(assertWorkingDirectory(options.workingDirectory));
-		const repoDir = repoDirName(cloneUrl);
-		const auth = token ? `${gitAuthFlag()} ` : "";
-		const setupCommands = (options.setupCommand === void 0 ? [] : Array.isArray(options.setupCommand) ? options.setupCommand : [options.setupCommand]).filter((command) => command.trim() !== "");
-		const family = `repo:${cloneUrl}:${workingDirectory ?? ""}/${repoDir}`;
+		const family = isList ? `repos:${(0, crypto.createHash)("sha256").update(JSON.stringify([workingDirectory ?? "", repos.map((repo) => [repo.cloneUrl, repo.repoDir])])).digest("hex").slice(0, 32)}` : `repo:${repos[0].cloneUrl}:${workingDirectory ?? ""}/${repos[0].repoDir}`;
 		let template = Template();
-		const buildEnv = {
-			...options.buildEnv,
-			...token ? { [BUILD_TOKEN_ENV]: token } : {}
-		};
+		const buildEnv = { ...options.buildEnv };
+		for (const repo of repos) if (repo.tokenEnv && repo.token) buildEnv[repo.tokenEnv] = repo.token;
 		if (Object.keys(buildEnv).length > 0) template = template.setEnvs(buildEnv, { ephemeral: true });
 		template = withResources(template, options);
 		if (workingDirectory) template = template.runCmd(`mkdir -p "${workingDirectory}"`).setWorkdir(workingDirectory);
-		template = template.runCmd(repoCloneCommand({
-			cloneUrl,
-			destination: repoDir,
-			...token ? { tokenEnv: BUILD_TOKEN_ENV } : {}
-		})).runCmd(`git -C "${repoDir}" ${auth}fetch origin ${sha}`).runCmd(`git -C "${repoDir}" checkout ${sha}`);
-		for (const command of setupCommands) template = template.runCmd(`cd "${repoDir}" && ${command}`);
-		template = template.runCmd(setupMarkerCommand(setupMarkerContent(setupCommands)));
+		const ordered = [...repos.filter((repo) => !repo.token), ...repos.filter((repo) => repo.token)];
+		for (const repo of ordered) {
+			const { repoDir, sha, tokenEnv, setupCommands } = repo;
+			const auth = tokenEnv ? `${gitAuthFlag(tokenEnv)} ` : "";
+			template = template.runCmd(repoCloneCommand({
+				cloneUrl: repo.cloneUrl,
+				destination: repoDir,
+				...tokenEnv ? { tokenEnv } : {}
+			}));
+			if (sha) template = template.runCmd(`git -C "${repoDir}" ${auth}fetch origin ${sha}`).runCmd(`git -C "${repoDir}" checkout ${sha}`);
+			for (const command of setupCommands) template = template.runCmd(guardedSetupCommand({
+				repoDir,
+				command,
+				continueOnFailure
+			}));
+			const content = setupMarkerContent(setupCommands);
+			template = template.runCmd(isList ? setupMarkerCommand(content, repoSetupMarkerPath(repoDir)) : setupMarkerCommand(content));
+		}
+		if (isList) {
+			const workspaceCommands = normalizeSetupCommands(options.workspaceSetupCommand);
+			for (const command of workspaceCommands) template = template.runCmd(command);
+			template = template.runCmd(setupMarkerCommand(setupMarkerContent(workspaceCommands), WORKSPACE_SETUP_MARKER_PATH));
+		}
 		return template.withFamily(family);
 	};
 }
@@ -2195,8 +2297,8 @@ function redactSecrets(value) {
 	if (value === void 0 || value === null) return void 0;
 	return (value instanceof Error ? value.message : typeof value === "string" ? value : String(value)).replace(/\/\/[^/@\s]+@/g, "//***@").replace(/\b(bearer|basic)\s+[^\s"']+/gi, "$1 ***").replace(/\b(gh[pousr]_|github_pat_)[A-Za-z0-9_]+/g, "$1***");
 }
-function gitAuthFlag() {
-	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${BUILD_TOKEN_ENV}" | base64 -w0)"`;
+function gitAuthFlag(tokenEnv) {
+	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${tokenEnv}" | base64 -w0)"`;
 }
 /**
 * `owner/repo` for a github.com clone URL, else undefined. Only the public