@mastra/factory 0.11.1 → 0.12.0-alpha.0

package/dist/workspace.js

@@ -1,60 +1,19 @@
 import { getFactoryAuthUserFromContext, getFactoryAuthUserId } from "./auth.js";
 import { getGithubPat } from "./integrations/github/pat.js";
 import { registerGithubPatKind, registerGithubTokenInjector } from "./integrations/github/token-refresh.js";
-import { DEFAULT_COMMAND_TIMEOUT_MS, MaterializeError, checkoutSessionBranch, hasExistingCheckout, materializeRepo, recycleClaimedWorkdir, runWorktreeSetup, runWorktreeTeardown } from "./integrations/github/sandbox.js";
-import { baseCheckpointIsStale } from "./sandbox/base-checkpoint-triggers.js";
+import { requireExec } from "./sandbox/materialization.js";
+import { createSessionSetupHook, evictSessionSandbox, getSessionSandbox, hasFailedSetupCommand, recordFailedSetupCommand, resolveSessionWorkdir } from "./sandbox/session-sandbox.js";
+import { DEFAULT_COMMAND_TIMEOUT_MS, SetupCommandError, checkoutSessionBranch, materializeRepo, runSetupCommand, runTeardownCommand } from "./integrations/github/sandbox.js";
 import { getFactorySessionAddress } from "./rules/binding-context.js";
 import path, { dirname, join } from "path";
-import { LocalSandbox, LocalSkillSource, Workspace } from "@mastra/core/workspace";
+import { LocalSkillSource, Workspace } from "@mastra/core/workspace";
 import { DEFAULT_CONFIG_DIR } from "@mastra/code-sdk/constants";
 import { SandboxFilesystem } from "@mastra/code-sdk/agents/sandbox-filesystem";
 import { existsSync } from "fs";
 import { fileURLToPath } from "url";
 import { MASTRACODE_WORKSPACE_TOOLS } from "@mastra/code-sdk/agents/tool-availability";
-import { getDynamicWorkspace } from "@mastra/code-sdk/agents/workspace";
 //#region src/workspace.ts
 const WORKSPACE_ID_PREFIX = "mfw";
-const SESSION_CHECKPOINT_PREFIX = "mastracode-session";
-function checkpointNameForSession(sessionId) {
-	return `${SESSION_CHECKPOINT_PREFIX}-${sessionId}`;
-}
-/**
-* Whether a command failure means the sandbox itself is gone (destroyed by
-* idle GC or provider teardown) AND the command provably never started, so
-* reviving the sandbox and replaying the command cannot run a side effect
-* twice. Matched by error name so any provider's equivalent error classes
-* participate without a package dependency.
-*
-* `SandboxExecTransportError` means both WebSocket attempts closed without an
-* exit frame against a live sandbox. It only proves the command never started
-* when the transport never opened (`opened: false` — the upgrade was refused
-* outright). When the transport opened, the command may have run and mutated
-* state before the result was lost, so replaying `git commit`, uploads, or
-* arbitrary shell commands could execute the side effect twice; those errors
-* surface to the caller instead.
-*/
-function isDeadSandboxError(error) {
-	if (!(error instanceof Error)) return false;
-	if (error.name === "SandboxDestroyedError") return true;
-	if (error.name === "SandboxExecTransportError") return error.opened === false;
-	return /sandbox .*(destroyed|no longer exists|not found)/i.test(error.message);
-}
-/**
-* The local-provider equivalent of {@link isDeadSandboxError}: a local sandbox
-* is just a directory, so it "dies" when that directory is removed — which
-* session retirement does while an in-flight run still holds the handle.
-*
-* Node surfaces a missing `cwd` as ENOENT against the binary it tried to spawn
-* (`spawn /bin/sh ENOENT`), which is textually identical to the shell itself
-* being absent, and is also what a genuinely missing command reports. Probing
-* the working directory is what separates "the sandbox is gone" from "that
-* command does not exist", so only the former triggers a rebuild.
-*/
-function isMissingWorkdirError(error, workdir) {
-	if (!workdir) return false;
-	if (error?.code !== "ENOENT") return false;
-	return !existsSync(workdir);
-}
 const bundleDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledFactorySkillsPath = join(bundleDirectory, "factory-skills");
 const FACTORY_SKILLS_SOURCE_PATH = [
@@ -179,31 +138,22 @@ var FactoryWorkspaceRegistry = class {
 	}
 };
 function createWorkspaceFactory(options = {}) {
-	const { sandbox: sandboxConfig, github, fleet, workItems } = options;
+	const { sandbox: sandboxConfig, github, workItems } = options;
 	const workspaceRegistry = options.workspaceRegistry ?? new FactoryWorkspaceRegistry();
-	const isLocalSandbox = sandboxConfig?.machine instanceof LocalSandbox;
 	const githubTokenInjectors = /* @__PURE__ */ new Map();
 	const githubTokenReconciliations = /* @__PURE__ */ new Map();
-	const inflightMaterializations = /* @__PURE__ */ new Map();
-	const materializedSandboxes = /* @__PURE__ */ new Map();
 	const constructedWorkspaces = /* @__PURE__ */ new Map();
 	return async ({ requestContext, mastra, skillExtension }) => {
 		const effectiveSkillExtension = skillExtension ?? factorySkillExtension;
 		const ctx = requestContext.get("controller");
 		const session = ctx?.resourceId && github ? await github.sourceControlStorage.sessions.getBySessionId(ctx.resourceId) : null;
-		if (!session) {
-			if (sandboxConfig && !isLocalSandbox) return;
-			return getDynamicWorkspace({
-				requestContext,
-				mastra,
-				skillExtension: effectiveSkillExtension
-			});
-		}
+		if (!session) return;
 		const user = getFactoryAuthUserFromContext(requestContext);
 		const userId = getFactoryAuthUserId(user);
 		if (!user?.organizationId || !userId) throw new Error(`Factory session ${session.sessionId} was resolved without a caller identity`);
 		if (user.organizationId !== session.orgId || session.visibility === "private" && userId !== session.userId) throw new Error(`Factory session ${session.sessionId} is not available to the current user`);
-		if (!sandboxConfig || !github || !fleet) throw new Error("GitHub and sandbox providers are required to create a Factory session workspace");
+		if (!sandboxConfig || !github) throw new Error("GitHub and a sandbox callback are required to create a Factory session workspace");
+		const createSessionSandboxInstance = sandboxConfig;
 		const storage = github.sourceControlStorage;
 		const projectRepository = await storage.projectRepositories.get({
 			orgId: session.orgId,
@@ -223,43 +173,69 @@ function createWorkspaceFactory(options = {}) {
 			id: connection.installationId
 		})) throw new Error(`GitHub installation ${connection.installationId} was not found`);
 		const repoFullName = repository.slug;
-		let workdir = isLocalSandbox ? fleet.computeLocalSessionWorkdir(repoFullName, session.id) : session.sandboxWorkdir ?? projectRepository.sandboxWorkdir;
-		let stateSeeded = false;
-		if (ctx && workdir && ctx.getState()?.projectPath !== workdir) {
-			await ctx.setState({
-				projectPath: workdir,
-				projectName: repoFullName
-			});
-			stateSeeded = true;
-		}
-		const binding = {
-			get sandboxId() {
-				return session.sandboxId;
-			},
-			checkpointName: checkpointNameForSession(session.id),
-			...!session.materializedAt && projectRepository.baseCheckpoint && !baseCheckpointIsStale(projectRepository) ? { seedCheckpointName: projectRepository.baseCheckpoint.name } : {},
-			setSandboxId: async (id) => {
-				await storage.sessions.setSandbox({
-					id: session.id,
-					sandboxId: id,
-					sandboxWorkdir: workdir
-				});
-				session.sandboxId = id;
-				session.sandboxWorkdir = workdir;
-			},
-			clear: async () => {
-				await storage.sessions.setSandbox({
-					id: session.id,
-					sandboxId: null,
-					sandboxWorkdir: workdir
-				});
-				session.sandboxId = null;
-			}
+		const runSetupOn = (target, workdir) => runSessionSetup(requireExec(target), workdir);
+		const guardedSetup = createSessionSetupHook(runSetupOn, session.id, repoFullName);
+		const setupHook = async (args) => {
+			if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) throw retiredError();
+			await guardedSetup(args);
+			if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) throw retiredError();
+			const target = requireExec(args.sandbox);
+			const patKind = await resolveGithubPatKind("default");
+			const ghCliToken = await getGithubPat(() => github.integrationStorage, session.orgId, patKind) ?? await getRepositoryToken();
+			target.setEnv?.((env) => ({
+				...env,
+				GH_TOKEN: ghCliToken
+			}));
+			storage.sessions.setSandbox({
+				id: session.id,
+				sandboxId: target.id,
+				sandboxWorkdir: sessionEntry.workdir ?? ""
+			}).catch(() => {});
+			const tokenRegistration = {
+				inject: (freshToken) => {
+					if (!target.setEnv) throw new Error("The active sandbox provider does not support runtime GitHub token refresh.");
+					target.setEnv((env) => ({
+						...env,
+						GH_TOKEN: freshToken
+					}));
+					tokenRegistration.ghToken = freshToken;
+				},
+				patKind,
+				ghToken: ghCliToken,
+				generation: 0,
+				tokenReplacementPending: false
+			};
+			githubTokenInjectors.set(workspaceId, tokenRegistration);
+			registerGithubTokenContext(tokenRegistration);
+			constructedWorkspaces.get(workspaceId)?.skills?.refresh().catch(() => {});
 		};
+		const constructSessionEntry = () => getSessionSandbox(session.id, repoFullName, () => {
+			const sandbox = createSessionSandboxInstance({
+				sessionId: session.id,
+				repoFullName,
+				setupCommand: projectRepository.setupCommand ?? void 0,
+				getRepositoryAccess: () => github.versionControl.getRepositoryAccess({
+					orgId: session.orgId,
+					repositoryId: repository.id
+				})
+			});
+			sandbox.setOnStart((previous) => async (args) => {
+				await setupHook(args);
+				await previous?.(args);
+			});
+			return sandbox;
+		});
+		const sessionEntry = constructSessionEntry();
+		const workdir = sessionEntry.workdir;
+		sessionEntry.sandbox.provider;
+		if (ctx && workdir && ctx.getState()?.projectPath !== workdir) await ctx.setState({
+			projectPath: workdir,
+			projectName: repoFullName
+		});
 		const extensionId = effectiveSkillExtension ? `-${effectiveSkillExtension.id}` : "";
 		const workspaceId = `${WORKSPACE_ID_PREFIX}-${projectRepository.id}-${session.id}${extensionId}`;
 		const workspaceGeneration = workspaceRegistry.generation(session.sessionId);
-		const configDir = sandboxConfig.workdir ?? DEFAULT_CONFIG_DIR;
+		const configDir = DEFAULT_CONFIG_DIR;
 		const getRepositoryToken = async () => {
 			const token = (await github.versionControl.getRepositoryAccess({
 				orgId: session.orgId,
@@ -333,7 +309,6 @@ function createWorkspaceFactory(options = {}) {
 					} catch {}
 					if (evicted && githubTokenInjectors.get(workspaceId) === registered) {
 						githubTokenInjectors.delete(workspaceId);
-						materializedSandboxes.delete(workspaceId);
 						constructedWorkspaces.delete(workspaceId);
 					}
 				}
@@ -354,31 +329,15 @@ function createWorkspaceFactory(options = {}) {
 			return reconcileRegisteredWorkspace(existing);
 		}
 		const retiredError = () => /* @__PURE__ */ new Error(`Factory session ${session.sessionId} was retired during workspace materialization`);
-		const materializeSandbox = async () => {
-			if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) throw retiredError();
-			let claimedPooledSandbox = false;
-			if (!isLocalSandbox && !session.sandboxId) {
-				const pooled = await storage.sandboxPool.claim({ projectRepositoryId: session.projectRepositoryId });
-				if (pooled) {
-					await storage.sessions.setSandbox({
-						id: session.id,
-						sandboxId: pooled.sandboxId,
-						sandboxWorkdir: pooled.sandboxWorkdir
-					});
-					session.sandboxId = pooled.sandboxId;
-					session.sandboxWorkdir = pooled.sandboxWorkdir;
-					workdir = pooled.sandboxWorkdir;
-					claimedPooledSandbox = true;
-				}
-			}
+		const runSessionSetup = async (target, workdir) => {
 			const token = await getRepositoryToken();
-			const patKind = await resolveGithubPatKind("default");
-			const ghCliToken = await getGithubPat(() => github.integrationStorage, session.orgId, patKind) ?? token;
-			const ensureSandbox = () => fleet.ensureSandbox(binding, { GH_TOKEN: ghCliToken }, void 0, {
-				...isLocalSandbox ? { workingDirectory: workdir } : {},
-				actingUserId: userId
-			});
-			const runMaterialize = (target, skipPull) => materializeRepo({
+			const setupPatKind = await resolveGithubPatKind("default");
+			const setupGhToken = await getGithubPat(() => github.integrationStorage, session.orgId, setupPatKind) ?? token;
+			target.setEnv?.((env) => ({
+				...env,
+				GH_TOKEN: setupGhToken
+			}));
+			await materializeRepo({
 				row: {
 					id: session.id,
 					sandboxWorkdir: workdir,
@@ -390,154 +349,61 @@ function createWorkspaceFactory(options = {}) {
 				},
 				sandbox: target,
 				token,
-				storage: storage.sessions,
-				skipPullOnExistingCheckout: skipPull
+				storage: storage.sessions
 			});
-			const isGitMissing = (error) => error instanceof MaterializeError && error.code === "git-missing";
-			let sandbox = await ensureSandbox();
-			if (claimedPooledSandbox) await recycleClaimedWorkdir(sandbox, workdir, repository.defaultBranch);
-			const seededFromBaseCheckpoint = !!binding.seedCheckpointName && !session.materializedAt && !claimedPooledSandbox && await hasExistingCheckout(sandbox, workdir, repoFullName);
-			try {
-				await runMaterialize(sandbox, seededFromBaseCheckpoint);
-			} catch (error) {
-				if (!isGitMissing(error)) throw error;
-				await fleet.teardownSandbox(binding, sandbox);
-				sandbox = await ensureSandbox();
-				try {
-					await runMaterialize(sandbox, false);
-				} catch (retryError) {
-					if (isGitMissing(retryError)) await fleet.teardownSandbox(binding, sandbox);
-					throw retryError;
-				}
-			}
-			await checkoutSessionBranch(sandbox, workdir, {
+			await checkoutSessionBranch(target, workdir, {
 				branch: session.branch,
 				baseBranch: session.baseBranch || projectRepository.branch || repository.defaultBranch,
 				token,
 				repoFullName
 			});
-			if (projectRepository.setupCommand && !seededFromBaseCheckpoint) try {
-				await runWorktreeSetup(sandbox, workdir, projectRepository.setupCommand);
-			} catch (setupError) {
-				if (projectRepository.teardownCommand) try {
-					await runWorktreeTeardown(sandbox, workdir, projectRepository.teardownCommand, { timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS });
-				} catch (teardownError) {
-					console.warn("[Mastra Factory] Worktree teardown after setup failure failed", {
-						orgId: session.orgId,
-						sessionId: session.sessionId,
-						projectRepositoryId: session.projectRepositoryId,
-						error: teardownError instanceof Error ? teardownError.message.slice(-2e3) : String(teardownError)
-					});
-				}
-				throw setupError;
-			}
-			const tokenRegistration = {
-				inject: (freshToken) => {
-					if (!sandbox.setEnvironmentVariable) throw new Error("The active sandbox provider does not support runtime GitHub token refresh.");
-					sandbox.setEnvironmentVariable("GH_TOKEN", freshToken);
-					tokenRegistration.ghToken = freshToken;
-				},
-				patKind,
-				ghToken: ghCliToken,
-				generation: 0,
-				tokenReplacementPending: false
-			};
-			if (workspaceRegistry.generation(session.sessionId) !== workspaceGeneration) {
-				try {
-					await fleet.teardownSandbox(binding, sandbox);
-				} catch (teardownError) {
-					console.warn("[Mastra Factory] Sandbox teardown after mid-materialization retirement failed", {
+			if (projectRepository.setupCommand) {
+				if (hasFailedSetupCommand(session.id, projectRepository.setupCommand)) {
+					console.warn("[Mastra Factory] Skipping setup command that already failed this session", {
 						orgId: session.orgId,
 						sessionId: session.sessionId,
-						error: teardownError instanceof Error ? teardownError.message.slice(-2e3) : String(teardownError)
+						projectRepositoryId: session.projectRepositoryId
 					});
+					return;
 				}
-				throw retiredError();
-			}
-			githubTokenInjectors.set(workspaceId, tokenRegistration);
-			registerGithubTokenContext(tokenRegistration);
-			return sandbox;
-		};
-		const ensureMaterialized = async () => {
-			const ready = materializedSandboxes.get(workspaceId);
-			if (ready) return ready;
-			let inflight = inflightMaterializations.get(workspaceId);
-			if (!inflight) {
-				inflight = materializeSandbox();
-				inflightMaterializations.set(workspaceId, inflight);
-				inflight.then((sb) => {
-					materializedSandboxes.set(workspaceId, sb);
-					workspace.skills?.refresh().catch(() => {});
-				}, () => {});
-			}
-			try {
-				return await inflight;
-			} finally {
-				if (inflightMaterializations.get(workspaceId) === inflight) inflightMaterializations.delete(workspaceId);
-			}
-		};
-		const lazySandbox = {
-			get id() {
-				return materializedSandboxes.get(workspaceId)?.id ?? workspaceId;
-			},
-			name: "Factory Lazy Sandbox",
-			get provider() {
-				return fleet.provider;
-			},
-			get status() {
-				return materializedSandboxes.has(workspaceId) ? "ready" : "pending";
-			},
-			get supportsCheckpoints() {
-				return materializedSandboxes.get(workspaceId)?.supportsCheckpoints ?? false;
-			},
-			getInstructions() {
-				return materializedSandboxes.get(workspaceId)?.getInstructions?.() ?? fleet.getInstructions();
-			},
-			clone() {
-				throw new Error("The Factory session sandbox cannot be cloned from a lazy handle.");
-			},
-			async start() {},
-			async getInfo() {
-				return (await ensureMaterialized()).getInfo();
-			},
-			async executeCommand(command, args, options) {
-				const sandbox = await ensureMaterialized();
 				try {
-					return await sandbox.executeCommand(command, args, options);
-				} catch (error) {
-					if (!isDeadSandboxError(error) && !(isLocalSandbox && isMissingWorkdirError(error, workdir))) throw error;
-					if (materializedSandboxes.get(workspaceId) === sandbox) materializedSandboxes.delete(workspaceId);
-					return (await ensureMaterialized()).executeCommand(command, args, options);
+					await runSetupCommand(target, workdir, projectRepository.setupCommand);
+				} catch (setupError) {
+					if (projectRepository.teardownCommand) try {
+						await runTeardownCommand(target, workdir, projectRepository.teardownCommand, { timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS });
+					} catch (teardownError) {
+						console.warn("[Mastra Factory] Worktree teardown after setup failure failed", {
+							orgId: session.orgId,
+							sessionId: session.sessionId,
+							projectRepositoryId: session.projectRepositoryId,
+							error: teardownError instanceof Error ? teardownError.message.slice(-2e3) : String(teardownError)
+						});
+					}
+					if (setupError instanceof SetupCommandError) {
+						recordFailedSetupCommand(session.id, projectRepository.setupCommand);
+						throw new SetupCommandError(`${setupError.message}. The sandbox stays usable: this setup command is skipped for the rest of the session — retry your command, then fix the setup command in the repository settings or run it manually.`, setupError.code);
+					}
+					throw setupError;
 				}
-			},
-			setEnvironmentVariable(name, value) {
-				const sandbox = materializedSandboxes.get(workspaceId);
-				if (!sandbox?.setEnvironmentVariable) throw new Error("The Factory session sandbox is not materialized yet.");
-				sandbox.setEnvironmentVariable(name, value);
-			},
-			async snapshot() {
-				await materializedSandboxes.get(workspaceId)?.snapshot?.();
-			},
-			async stop() {
-				await materializedSandboxes.get(workspaceId)?.stop?.();
 			}
 		};
+		const sessionSandbox = requireExec(sessionEntry.sandbox);
 		const filesystem = new SandboxFilesystem({
-			id: `sandbox-fs:${workspaceId}:${workdir}`,
-			sandbox: lazySandbox,
-			workdir
+			id: `sandbox-fs:${workspaceId}`,
+			sandbox: sessionSandbox,
+			workdir: () => resolveSessionWorkdir(session.id, sessionEntry.sandbox, repoFullName)
 		});
 		const projectSkillPaths = [
 			path.join(configDir, "skills"),
 			".claude/skills",
 			".agents/skills"
 		];
-		const guardedSkillFallback = new UnmaterializedAwareSkillSource(filesystem, () => materializedSandboxes.has(workspaceId));
+		const guardedSkillFallback = new UnmaterializedAwareSkillSource(filesystem, () => sessionEntry.sandbox.status === "running");
 		const workspace = new Workspace({
 			id: workspaceId,
 			name: "Mastra Code Factory Session Workspace",
 			filesystem,
-			sandbox: lazySandbox,
+			sandbox: sessionSandbox,
 			tools: MASTRACODE_WORKSPACE_TOOLS,
 			skills: [...effectiveSkillExtension?.paths ?? [], ...projectSkillPaths],
 			skillSource: effectiveSkillExtension?.createSource(guardedSkillFallback, projectSkillPaths) ?? guardedSkillFallback
@@ -546,18 +412,14 @@ function createWorkspaceFactory(options = {}) {
 		constructedWorkspaces.set(workspaceId, workspace);
 		if (!await workspaceRegistry.register(session.sessionId, workspaceId, workspaceGeneration, async () => {
 			githubTokenInjectors.delete(workspaceId);
-			materializedSandboxes.delete(workspaceId);
 			constructedWorkspaces.delete(workspaceId);
+			evictSessionSandbox(session.id);
 			await mastra?.removeWorkspace?.(workspaceId);
 		})) throw new Error(`Factory session ${session.sessionId} was retired during workspace materialization`);
-		if (stateSeeded) ensureMaterialized().catch((error) => {
-			console.error(`[factory:workspace] background materialization for ${workspaceId} failed`, error);
-		});
 		return workspace;
 	};
 }
-const getFactoryWorkspace = createWorkspaceFactory();
 //#endregion
-export { FACTORY_SKILLS_SOURCE_PATH, FACTORY_SKILL_NAMES, FactoryWorkspaceRegistry, checkpointNameForSession, createWorkspaceFactory, getFactoryWorkspace, isDeadSandboxError, isMissingWorkdirError };
+export { FACTORY_SKILLS_SOURCE_PATH, FACTORY_SKILL_NAMES, FactoryWorkspaceRegistry, createWorkspaceFactory };
 
 //# sourceMappingURL=workspace.js.map