@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/sandbox/session-sandbox.js

@@ -0,0 +1,248 @@
+import { timedPhase } from "../timing.js";
+import { SETUP_FAILED_MARKER_PATH, SETUP_MARKER_PATH, WORKSPACE_SETUP_MARKER_PATH, repoSetupMarkerPath, setupMarkerContent } from "../packages/_internals/workspace/dist/index.js";
+import { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder, repositoryDirectoryName } from "./workdir.js";
+import path from "path";
+//#region src/sandbox/session-sandbox.ts
+const sessionSandboxes = /* @__PURE__ */ new Map();
+/** The layout of a memoized session, `undefined` until its workdir resolved. */
+function sessionLayout(entry) {
+	if (!entry?.workdir) return void 0;
+	const slugs = entry.repos?.length ? entry.repos : [entry.ownRepo];
+	if (slugs.length === 1) return {
+		root: entry.workdir,
+		repos: [{
+			slug: slugs[0],
+			dir: entry.workdir,
+			prefix: ""
+		}]
+	};
+	const root = path.posix.dirname(entry.workdir);
+	return {
+		root,
+		repos: slugs.map((slug) => {
+			const dir = slug.toLowerCase() === entry.ownRepo.toLowerCase() ? entry.workdir : repoDirUnder(root, slug);
+			return {
+				slug,
+				dir,
+				prefix: `${path.posix.basename(dir)}/`
+			};
+		})
+	};
+}
+/**
+* Get the session's memoized sandbox entry, constructing (and memoizing) it on
+* first access. Construction is cheap and side-effect-free by contract; VMs
+* are provisioned on `start()` only. Local sandboxes get their workdir here;
+* remote workdirs are a runtime fact of the VM, resolved on first start.
+*/
+function getSessionSandbox(sessionId, repoFullName, construct, repos) {
+	const existing = sessionSandboxes.get(sessionId);
+	if (existing) {
+		if (repos) existing.repos = repos;
+		return existing;
+	}
+	const sandbox = construct();
+	const local = deriveLocalWorkdir(sandbox, repoFullName);
+	const entry = {
+		sandbox,
+		ownRepo: repoFullName,
+		...local ? { workdir: local } : {},
+		...repos ? { repos } : {}
+	};
+	sessionSandboxes.set(sessionId, entry);
+	return entry;
+}
+/**
+* Resolve (and memoize on the session entry) the session's repo checkout
+* root. Local sandboxes answer synchronously from their configured
+* `workingDirectory`; remote sandboxes clone into the VM's own default cwd,
+* so the first resolution probes it with one `pwd` — the VM tells us where
+* home is, we never invent a path. Calling this against a stopped sandbox
+* lazily starts it (the probe is a command), so passive readers must peek
+* `entry.workdir` instead. The memo is the session's own checkout; another
+* environment repository lives beside it under the same root, so it is
+* answered from the memo's parent without a second probe.
+*/
+async function resolveSessionWorkdir(sessionId, sandbox, repoFullName) {
+	const entry = sessionSandboxes.get(sessionId);
+	const memo = entry && entry.sandbox === sandbox ? entry : void 0;
+	if (memo && memo.ownRepo !== repoFullName) {
+		const own = await resolveSessionWorkdir(sessionId, sandbox, memo.ownRepo);
+		return repoDirUnder(path.posix.dirname(own), repoFullName);
+	}
+	if (memo?.workdir) return memo.workdir;
+	const workdir = deriveLocalWorkdir(sandbox, repoFullName) ?? deriveRemoteRepoDir(sandbox, repoFullName) ?? repoDirUnder(await probeHome(sandbox), repoFullName);
+	if (memo) memo.workdir = workdir;
+	return workdir;
+}
+/** One `pwd` in the VM's default shell cwd — its home dir, by provider convention. */
+async function probeHome(sandbox) {
+	if (!sandbox.executeCommand) throw new Error(`Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation`);
+	const probe = await sandbox.executeCommand("pwd");
+	const home = probe.stdout.trim().split("\n").pop()?.trim() ?? "";
+	if (probe.exitCode !== 0 || !home.startsWith("/")) throw new Error(`Sandbox '${sandbox.id}' default cwd probe failed (exit ${probe.exitCode}): ${probe.stderr.trim() || probe.stdout.trim() || "empty output"}`);
+	return home;
+}
+/**
+* The session's memoized sandbox (and its workdir) when one was already
+* constructed in this process, else undefined. Never constructs — passive
+* read paths use this so browsing files cannot provision a VM.
+*/
+function peekSessionSandbox(sessionId) {
+	return sessionSandboxes.get(sessionId);
+}
+/** Drop the memoized instance (on stop/destroy/retirement or construction failure). */
+function evictSessionSandbox(sessionId) {
+	sessionSandboxes.delete(sessionId);
+	failedSetupCommands.delete(sessionId);
+}
+/** Test-only: reset the process-wide memo between tests. */
+function __clearSessionSandboxesForTests() {
+	sessionSandboxes.clear();
+	failedSetupCommands.clear();
+}
+/**
+* Setup commands that already failed once for a session. The first failure
+* fails the start loudly — the agent sees the real error in the tool result
+* that triggered it. Recording it lets the next start skip the known-bad
+* command instead of wedging the session behind a permanently failing
+* onStart: clone and checkout still run, and the agent can fix or re-run
+* the setup itself. Keyed by the exact command, one entry per failed command, so an
+* edited setup command runs fresh. In-memory only — a server restart re-runs the (idempotent)
+* setup.
+*/
+const failedSetupCommands = /* @__PURE__ */ new Map();
+function recordFailedSetupCommand(sessionId, command) {
+	const failed = failedSetupCommands.get(sessionId) ?? /* @__PURE__ */ new Set();
+	failed.add(command);
+	failedSetupCommands.set(sessionId, failed);
+}
+function hasFailedSetupCommand(sessionId, command) {
+	return failedSetupCommands.get(sessionId)?.has(command) ?? false;
+}
+/**
+* The setup completion marker is a convention shared with the repo templates
+* (`@internal/workspace`): `.mastra-sandbox/setup` beside the checkout,
+* containing a digest of the setup commands. Templates write it as their last
+* build step, so a sandbox booted from a warm image already carries it; the
+* start hook writes it after a successful runtime setup. It is a skip cache,
+* not a correctness mechanism: the setup command is assumed idempotent, and a
+* missing or mismatched marker only re-runs it.
+*
+* The working directory is the parent of the repo dir, which is also the
+* template's build cwd, so this is the file the template's marker step wrote.
+*/
+function markerShellPath(workdir) {
+	return `${path.posix.dirname(workdir)}/${SETUP_MARKER_PATH}`;
+}
+async function markerMatches(sandbox, workdir, content) {
+	const marker = markerShellPath(workdir);
+	return (await sandbox.executeCommand(`test -d "${workdir}/.git" && test -f "${marker}" && [ "$(cat "${marker}")" = "${content}" ]`)).exitCode === 0;
+}
+async function writeMarker(sandbox, workdir, content) {
+	const marker = markerShellPath(workdir);
+	await sandbox.executeCommand(`mkdir -p "$(dirname "${marker}")" && printf '%s' '${content}' > "${marker}"`).catch(() => {});
+}
+/**
+* Build the session setup hook, which factory attaches to the constructed
+* sandbox with `setOnStart`. Runs inside the sandbox start lifecycle on
+* every start, fresh VM or reconnect: materialize and checkout always run,
+* and the setup command runs unless the sandbox already carries the marker
+* for it (a warm template image, or an earlier successful start). Throwing
+* fails `start()` loudly; core treats onStart errors as fatal.
+*/
+function createSessionSetupHook(run, sessionId, repoFullName, setupCommand) {
+	const marker = setupCommand?.trim() ? setupMarkerContent(setupCommand) : void 0;
+	return async ({ sandbox }) => {
+		if (!sandbox.executeCommand) throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);
+		const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);
+		const setupDone = marker ? await timedPhase("workspace.setup-marker", () => markerMatches(sandbox, workdir, marker)) : true;
+		if (marker) process.stderr.write(`[factory:setup] ${setupDone ? "marker matches, skipping setup command" : "no matching marker, setup command will run"} (${markerShellPath(workdir)})\n`);
+		await run(sandbox, workdir, {
+			setupDone,
+			markSetupDone: () => marker ? writeMarker(sandbox, workdir, marker) : Promise.resolve()
+		});
+	};
+}
+/**
+* Shell-quote one marker file's content. Marker contents are digests, but
+* the quoting keeps an edited command's digest from ever reaching the shell
+* unquoted.
+*/
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+* The list-form marker probe: trust a repository's marker only when its
+* checkout exists, the marker names this command, and the template did not
+* record the repository in `setup-failed` (a failed per-repo setup still
+* writes the marker because every step ran; the failure list says it failed).
+*/
+async function repoMarkerMatches(sandbox, root, repoDir, content) {
+	const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;
+	const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;
+	return (await sandbox.executeCommand(`test -d "${root}/${repoDir}/.git" && test -f "${marker}" && [ "$(cat "${marker}")" = ${shellQuote(content)} ] && ! grep -qxF -- ${shellQuote(repoDir)} "${failed}" 2>/dev/null`)).exitCode === 0;
+}
+/** Write a repository's marker and drop it from `setup-failed`. Best-effort, like `writeMarker`. */
+async function writeRepoMarker(sandbox, root, repoDir, content) {
+	const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;
+	const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;
+	await sandbox.executeCommand(`mkdir -p "$(dirname "${marker}")" && printf '%s' ${shellQuote(content)} > "${marker}" && { test -f "${failed}" && { grep -vxF -- ${shellQuote(repoDir)} "${failed}" > "${failed}.tmp" || true; } && mv "${failed}.tmp" "${failed}" || true; }`).catch(() => {});
+}
+async function workspaceMarkerMatches(sandbox, root, content) {
+	const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;
+	return (await sandbox.executeCommand(`test -f "${marker}" && [ "$(cat "${marker}")" = ${shellQuote(content)} ]`)).exitCode === 0;
+}
+async function writeWorkspaceMarker(sandbox, root, content) {
+	const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;
+	await sandbox.executeCommand(`mkdir -p "$(dirname "${marker}")" && printf '%s' ${shellQuote(content)} > "${marker}"`).catch(() => {});
+}
+/**
+* The list-form start hook for a session whose factory has an environment:
+* the same lifecycle as `createSessionSetupHook`, with one gate per
+* repository plus one for the workspace setup command. The markers are the
+* ones the multi-repo templates write (`.mastra-sandbox/repos/<repoDir>`,
+* `.mastra-sandbox/workspace-setup`, `.mastra-sandbox/setup-failed`), all
+* under the workspace root, which is the parent of the primary repository's
+* directory: `resolveSessionWorkdir` keeps answering that directory so the
+* PR tools and passive readers see the primary checkout, and the root is
+* derived from it rather than probed twice.
+*
+* `repos` is in position order and must include the primary (`repoFullName`).
+*/
+function createEnvironmentSetupHook(run, sessionId, repoFullName, environment) {
+	const workspaceCommand = environment.workspaceSetupCommand?.trim() ? environment.workspaceSetupCommand : void 0;
+	const workspaceMarker = workspaceCommand ? setupMarkerContent(workspaceCommand) : void 0;
+	return async ({ sandbox }) => {
+		if (!sandbox.executeCommand) throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);
+		const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);
+		const root = path.posix.dirname(workdir);
+		const repos = [];
+		for (const repo of environment.repos) {
+			const repoDir = repositoryDirectoryName(repo.slug);
+			const marker = repo.setupCommand?.trim() ? setupMarkerContent(repo.setupCommand) : void 0;
+			const setupDone = marker ? await timedPhase(`workspace.setup-marker(${repoDir})`, () => repoMarkerMatches(sandbox, root, repoDir, marker)) : true;
+			if (marker) process.stderr.write(`[factory:setup] ${repo.slug}: ${setupDone ? "marker matches, skipping setup command" : "no matching marker, setup command will run"} (${root}/${repoSetupMarkerPath(repoDir)})\n`);
+			repos.push({
+				...repo,
+				dir: `${root}/${repoDir}`,
+				gate: {
+					setupDone,
+					markSetupDone: () => marker ? writeRepoMarker(sandbox, root, repoDir, marker) : Promise.resolve()
+				}
+			});
+		}
+		await run(sandbox, {
+			root,
+			repos,
+			workspace: {
+				setupDone: workspaceMarker ? await timedPhase("workspace.setup-marker(workspace)", () => workspaceMarkerMatches(sandbox, root, workspaceMarker)) : true,
+				markSetupDone: () => workspaceMarker ? writeWorkspaceMarker(sandbox, root, workspaceMarker) : Promise.resolve()
+			}
+		});
+	};
+}
+//#endregion
+export { __clearSessionSandboxesForTests, createEnvironmentSetupHook, createSessionSetupHook, evictSessionSandbox, getSessionSandbox, hasFailedSetupCommand, peekSessionSandbox, recordFailedSetupCommand, resolveSessionWorkdir, sessionLayout };
+
+//# sourceMappingURL=session-sandbox.js.map

package/dist/sandbox/session-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-sandbox.js","names":[],"sources":["../../src/sandbox/session-sandbox.ts"],"sourcesContent":["import path from 'node:path';\nimport {\n  SETUP_FAILED_MARKER_PATH,\n  SETUP_MARKER_PATH,\n  WORKSPACE_SETUP_MARKER_PATH,\n  repoSetupMarkerPath,\n  setupMarkerContent,\n} from '@internal/workspace';\n\nimport type {\n  FactorySandbox,\n  FactorySandboxContext as CoreFactorySandboxContext,\n  MastraSandbox,\n  SandboxStartHook,\n  WorkspaceSandbox,\n} from '@mastra/core/workspace';\nimport { timedPhase } from '../timing.js';\nimport { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder, repositoryDirectoryName } from './workdir.js';\n\n/**\n * Everything factory knows about a session's sandbox needs: the whole contract\n * between factory and the host's FactorySandbox. Factory owns intent; the\n * provider owns resolving `sessionId` to a runnable VM. Defined in\n * `@mastra/core/workspace` so provider packages can implement it without\n * depending on factory.\n */\nexport type FactorySandboxContext = CoreFactorySandboxContext;\n\n/**\n * The deploy's sandbox configuration: construct a session's sandbox from\n * intent. The sandbox identity is the session id; the provider must honor\n * id-keyed getOrCreate on `start()` (reconnect/resume an existing VM for the\n * id, create otherwise). Construction must be cheap and side-effect-free —\n * VMs are provisioned on `start()` only. Local sandboxes should root their\n * `workingDirectory` at a per-session directory (e.g.\n * `join(root, ctx.sessionId)`); the repo checks out as a subdirectory of it.\n *\n * Forward `ctx.sandboxId` to providers that reattach by physical id so resume\n * reattaches the original VM instead of provisioning a replacement.\n *\n * Returns a `MastraSandbox`, not the bare `WorkspaceSandbox` interface:\n * factory relies on the base class for the start lifecycle and the runtime\n * env, so providers extend it rather than reimplementing the contract.\n *\n * Factory attaches its own session setup to the returned sandbox, so the\n * callback never has to wire it up. A callback may still pass its own\n * `onStart`; it runs after factory's setup, against a prepared workspace.\n *\n * @example\n * ```typescript\n * sandbox: ({ sessionId, sandboxId }) => new E2BSandbox({ id: sessionId, sandboxId })\n * ```\n *\n * A FactorySandbox instance (for example `new E2BFactorySandbox({ apiKey })`)\n * additionally exposes settings and template builds to the environment.\n */\nexport type MastraFactorySandboxConfig = (ctx: FactorySandboxContext) => MastraSandbox;\n\n/**\n * The `sandbox` option of `MastraFactoryConfig`: a FactorySandbox instance\n * (it owns the session sandbox constructor, the repo template and the\n * environment settings schema) or a bare callback, which the factory wraps as a `provider: 'custom'` sandbox with no settings.\n */\nexport type MastraFactorySandboxOption = FactorySandbox | MastraFactorySandboxConfig;\n\n/**\n * What the start hook learned about the setup command before running the\n * session setup, and how to record its completion afterwards.\n */\nexport interface SessionSetupGate {\n  /** True when the sandbox already carries a marker for the current setup command. */\n  setupDone: boolean;\n  /** Write the marker once the setup command succeeded. Best-effort. */\n  markSetupDone: () => Promise<void>;\n}\n\n/**\n * The session's setup work, run against a started sandbox on EVERY start.\n * Materialize and checkout are idempotent and must always run (a warm boot\n * still needs its pull); only the setup command consults `gate`.\n */\nexport type SessionSetupRun = (sandbox: WorkspaceSandbox, workdir: string, gate: SessionSetupGate) => Promise<void>;\n\n/** One environment repository as the boot hook needs it: its slug and setup command. */\nexport interface SessionEnvironmentRepository {\n  slug: string;\n  setupCommand?: string;\n}\n\n/** What the environment hook learned about one repository before the boot runs. */\nexport interface SessionEnvironmentRepositoryGate extends SessionEnvironmentRepository {\n  /** `<root>/<repoDir>`, the directory the template cloned this repository into. */\n  dir: string;\n  gate: SessionSetupGate;\n}\n\n/** The environment hook's view of the workspace: the root, every repository in position order, the workspace gate. */\nexport interface SessionEnvironmentGate {\n  /** The workspace root, parent of every repository directory. */\n  root: string;\n  repos: SessionEnvironmentRepositoryGate[];\n  /** Gate for `workspaceSetupCommand`; `setupDone` when there is no command or its marker matches. */\n  workspace: SessionSetupGate;\n}\n\n/** The list-form session boot: run on every start, like `SessionSetupRun`. */\nexport type SessionEnvironmentSetupRun = (\n  sandbox: WorkspaceSandbox,\n  environment: SessionEnvironmentGate,\n) => Promise<void>;\n\n/**\n * Per-process session-id → sandbox instance memo.\n *\n * The provider contract is id-keyed getOrCreate, but provider find-then-create\n * has a real double-create race across independent instances. Memoizing the\n * instance per session makes the base class's per-instance start coalescing\n * apply process-wide per session — the same single-flight scope the fleet's\n * per-binding coalescing provided. Cross-replica races are accepted (the\n * fleet was also per-replica).\n */\ninterface SessionSandboxEntry {\n  sandbox: WorkspaceSandbox;\n  /**\n   * The session's repo checkout root, recorded for passive readers (fs\n   * routes, capture, authz). Local sandboxes derive it at construction;\n   * remote sandboxes clone into the VM's own home, so it is undefined until\n   * `resolveSessionWorkdir` probes the first started VM — passive readers\n   * treat an unresolved workdir as \"nothing materialized\".\n   */\n  workdir?: string;\n  /** The session's own repository, the only one `workdir` is ever recorded for. */\n  ownRepo: string;\n  /** Environment repositories in position order; the session's own repository is among them. */\n  repos?: string[];\n}\n\nconst sessionSandboxes = new Map<string, SessionSandboxEntry>();\n\n/** One environment repository as the file readers see it. */\nexport interface SessionLayoutRepository {\n  slug: string;\n  /** Absolute checkout directory. */\n  dir: string;\n  /** Path prefix of this checkout under the layout root: empty for a single-repository session, `<dir>/` otherwise. */\n  prefix: string;\n}\n\n/**\n * Where a session's files are read from. A session with one repository is\n * rooted at that checkout, as before environments existed; a session with\n * several is rooted at the workspace root with each checkout as a directory\n * beneath it.\n */\nexport interface SessionLayout {\n  root: string;\n  repos: SessionLayoutRepository[];\n}\n\n/** The layout of a memoized session, `undefined` until its workdir resolved. */\nexport function sessionLayout(entry: SessionSandboxEntry | undefined): SessionLayout | undefined {\n  if (!entry?.workdir) return undefined;\n  const slugs = entry.repos?.length ? entry.repos : [entry.ownRepo];\n  if (slugs.length === 1) {\n    return { root: entry.workdir, repos: [{ slug: slugs[0]!, dir: entry.workdir, prefix: '' }] };\n  }\n  const root = path.posix.dirname(entry.workdir);\n  return {\n    root,\n    repos: slugs.map(slug => {\n      const dir = slug.toLowerCase() === entry.ownRepo.toLowerCase() ? entry.workdir! : repoDirUnder(root, slug);\n      return { slug, dir, prefix: `${path.posix.basename(dir)}/` };\n    }),\n  };\n}\n\n/**\n * Get the session's memoized sandbox entry, constructing (and memoizing) it on\n * first access. Construction is cheap and side-effect-free by contract; VMs\n * are provisioned on `start()` only. Local sandboxes get their workdir here;\n * remote workdirs are a runtime fact of the VM, resolved on first start.\n */\nexport function getSessionSandbox(\n  sessionId: string,\n  repoFullName: string,\n  construct: () => WorkspaceSandbox,\n  repos?: string[],\n): SessionSandboxEntry {\n  const existing = sessionSandboxes.get(sessionId);\n  if (existing) {\n    // The environment can change between boots; the layout follows the latest.\n    if (repos) existing.repos = repos;\n    return existing;\n  }\n  const sandbox = construct();\n  const local = deriveLocalWorkdir(sandbox, repoFullName);\n  const entry: SessionSandboxEntry = {\n    sandbox,\n    ownRepo: repoFullName,\n    ...(local ? { workdir: local } : {}),\n    ...(repos ? { repos } : {}),\n  };\n  sessionSandboxes.set(sessionId, entry);\n  return entry;\n}\n\n/**\n * Resolve (and memoize on the session entry) the session's repo checkout\n * root. Local sandboxes answer synchronously from their configured\n * `workingDirectory`; remote sandboxes clone into the VM's own default cwd,\n * so the first resolution probes it with one `pwd` — the VM tells us where\n * home is, we never invent a path. Calling this against a stopped sandbox\n * lazily starts it (the probe is a command), so passive readers must peek\n * `entry.workdir` instead. The memo is the session's own checkout; another\n * environment repository lives beside it under the same root, so it is\n * answered from the memo's parent without a second probe.\n */\nexport async function resolveSessionWorkdir(\n  sessionId: string,\n  sandbox: WorkspaceSandbox,\n  repoFullName: string,\n): Promise<string> {\n  const entry = sessionSandboxes.get(sessionId);\n  const memo = entry && entry.sandbox === sandbox ? entry : undefined;\n  if (memo && memo.ownRepo !== repoFullName) {\n    // Passive readers take `workdir` as the session's own checkout, so a\n    // sibling never lands in the memo: resolve the own checkout (cold memo\n    // included) and answer the sibling beside it.\n    const own = await resolveSessionWorkdir(sessionId, sandbox, memo.ownRepo);\n    return repoDirUnder(path.posix.dirname(own), repoFullName);\n  }\n  if (memo?.workdir) return memo.workdir;\n  const workdir =\n    deriveLocalWorkdir(sandbox, repoFullName) ??\n    deriveRemoteRepoDir(sandbox, repoFullName) ??\n    repoDirUnder(await probeHome(sandbox), repoFullName);\n  if (memo) memo.workdir = workdir;\n  return workdir;\n}\n\n/** One `pwd` in the VM's default shell cwd — its home dir, by provider convention. */\nasync function probeHome(sandbox: WorkspaceSandbox): Promise<string> {\n  if (!sandbox.executeCommand) {\n    throw new Error(`Sandbox '${sandbox.id}' cannot resolve its workdir: no executeCommand implementation`);\n  }\n  const probe = await sandbox.executeCommand('pwd');\n  const home = probe.stdout.trim().split('\\n').pop()?.trim() ?? '';\n  if (probe.exitCode !== 0 || !home.startsWith('/')) {\n    throw new Error(\n      `Sandbox '${sandbox.id}' default cwd probe failed (exit ${probe.exitCode}): ${\n        probe.stderr.trim() || probe.stdout.trim() || 'empty output'\n      }`,\n    );\n  }\n  return home;\n}\n\n/**\n * The session's memoized sandbox (and its workdir) when one was already\n * constructed in this process, else undefined. Never constructs — passive\n * read paths use this so browsing files cannot provision a VM.\n */\nexport function peekSessionSandbox(sessionId: string): SessionSandboxEntry | undefined {\n  return sessionSandboxes.get(sessionId);\n}\n\n/** Drop the memoized instance (on stop/destroy/retirement or construction failure). */\nexport function evictSessionSandbox(sessionId: string): void {\n  sessionSandboxes.delete(sessionId);\n  failedSetupCommands.delete(sessionId);\n}\n\n/** Test-only: reset the process-wide memo between tests. */\nexport function __clearSessionSandboxesForTests(): void {\n  sessionSandboxes.clear();\n  failedSetupCommands.clear();\n}\n\n/**\n * Setup commands that already failed once for a session. The first failure\n * fails the start loudly — the agent sees the real error in the tool result\n * that triggered it. Recording it lets the next start skip the known-bad\n * command instead of wedging the session behind a permanently failing\n * onStart: clone and checkout still run, and the agent can fix or re-run\n * the setup itself. Keyed by the exact command, one entry per failed command, so an\n * edited setup command runs fresh. In-memory only — a server restart re-runs the (idempotent)\n * setup.\n */\nconst failedSetupCommands = new Map<string, Set<string>>();\n\nexport function recordFailedSetupCommand(sessionId: string, command: string): void {\n  const failed = failedSetupCommands.get(sessionId) ?? new Set<string>();\n  failed.add(command);\n  failedSetupCommands.set(sessionId, failed);\n}\n\nexport function hasFailedSetupCommand(sessionId: string, command: string): boolean {\n  return failedSetupCommands.get(sessionId)?.has(command) ?? false;\n}\n\n/**\n * The setup completion marker is a convention shared with the repo templates\n * (`@internal/workspace`): `.mastra-sandbox/setup` beside the checkout,\n * containing a digest of the setup commands. Templates write it as their last\n * build step, so a sandbox booted from a warm image already carries it; the\n * start hook writes it after a successful runtime setup. It is a skip cache,\n * not a correctness mechanism: the setup command is assumed idempotent, and a\n * missing or mismatched marker only re-runs it.\n *\n * The working directory is the parent of the repo dir, which is also the\n * template's build cwd, so this is the file the template's marker step wrote.\n */\nfunction markerShellPath(workdir: string): string {\n  return `${path.posix.dirname(workdir)}/${SETUP_MARKER_PATH}`;\n}\n\nasync function markerMatches(sandbox: WorkspaceSandbox, workdir: string, content: string): Promise<boolean> {\n  // The marker sits beside the checkout, not inside it, so it can outlive a\n  // removed checkout (a wiped local session dir, a recovered VM). Trust it\n  // only when the checkout it describes exists and it names this command.\n  const marker = markerShellPath(workdir);\n  const probe = await sandbox.executeCommand!(\n    `test -d \"${workdir}/.git\" && test -f \"${marker}\" && [ \"$(cat \"${marker}\")\" = \"${content}\" ]`,\n  );\n  return probe.exitCode === 0;\n}\n\nasync function writeMarker(sandbox: WorkspaceSandbox, workdir: string, content: string): Promise<void> {\n  // Best-effort: a missing marker only re-runs the idempotent setup later.\n  const marker = markerShellPath(workdir);\n  await sandbox.executeCommand!(`mkdir -p \"$(dirname \"${marker}\")\" && printf '%s' '${content}' > \"${marker}\"`).catch(\n    () => {},\n  );\n}\n\n/**\n * Build the session setup hook, which factory attaches to the constructed\n * sandbox with `setOnStart`. Runs inside the sandbox start lifecycle on\n * every start, fresh VM or reconnect: materialize and checkout always run,\n * and the setup command runs unless the sandbox already carries the marker\n * for it (a warm template image, or an earlier successful start). Throwing\n * fails `start()` loudly; core treats onStart errors as fatal.\n */\nexport function createSessionSetupHook(\n  run: SessionSetupRun,\n  sessionId: string,\n  repoFullName: string,\n  setupCommand: string | undefined,\n): SandboxStartHook {\n  // No command, no marker: nothing to gate.\n  const marker = setupCommand?.trim() ? setupMarkerContent(setupCommand) : undefined;\n  return async ({ sandbox }) => {\n    if (!sandbox.executeCommand) {\n      throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);\n    }\n    // Resolved from the live instance (the hook runs inside `start()`, so the\n    // VM is up) and memoized on the session entry for passive readers.\n    const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);\n    // Probed before materialize so a wiped checkout reads as \"not done\" even\n    // though materialize is about to restore it.\n    const setupDone = marker\n      ? await timedPhase('workspace.setup-marker', () => markerMatches(sandbox, workdir, marker))\n      : true;\n    if (marker) {\n      process.stderr.write(\n        `[factory:setup] ${setupDone ? 'marker matches, skipping setup command' : 'no matching marker, setup command will run'} (${markerShellPath(workdir)})\\n`,\n      );\n    }\n    await run(sandbox, workdir, {\n      setupDone,\n      markSetupDone: () => (marker ? writeMarker(sandbox, workdir, marker) : Promise.resolve()),\n    });\n  };\n}\n\n/**\n * Shell-quote one marker file's content. Marker contents are digests, but\n * the quoting keeps an edited command's digest from ever reaching the shell\n * unquoted.\n */\nfunction shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n\n/**\n * The list-form marker probe: trust a repository's marker only when its\n * checkout exists, the marker names this command, and the template did not\n * record the repository in `setup-failed` (a failed per-repo setup still\n * writes the marker because every step ran; the failure list says it failed).\n */\nasync function repoMarkerMatches(\n  sandbox: WorkspaceSandbox,\n  root: string,\n  repoDir: string,\n  content: string,\n): Promise<boolean> {\n  const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;\n  const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;\n  const probe = await sandbox.executeCommand!(\n    `test -d \"${root}/${repoDir}/.git\" && test -f \"${marker}\" && [ \"$(cat \"${marker}\")\" = ${shellQuote(content)} ] && ! grep -qxF -- ${shellQuote(repoDir)} \"${failed}\" 2>/dev/null`,\n  );\n  return probe.exitCode === 0;\n}\n\n/** Write a repository's marker and drop it from `setup-failed`. Best-effort, like `writeMarker`. */\nasync function writeRepoMarker(\n  sandbox: WorkspaceSandbox,\n  root: string,\n  repoDir: string,\n  content: string,\n): Promise<void> {\n  const marker = `${root}/${repoSetupMarkerPath(repoDir)}`;\n  const failed = `${root}/${SETUP_FAILED_MARKER_PATH}`;\n  await sandbox.executeCommand!(\n    `mkdir -p \"$(dirname \"${marker}\")\" && printf '%s' ${shellQuote(content)} > \"${marker}\" && { test -f \"${failed}\" && { grep -vxF -- ${shellQuote(repoDir)} \"${failed}\" > \"${failed}.tmp\" || true; } && mv \"${failed}.tmp\" \"${failed}\" || true; }`,\n  ).catch(() => {});\n}\n\nasync function workspaceMarkerMatches(sandbox: WorkspaceSandbox, root: string, content: string): Promise<boolean> {\n  const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;\n  const probe = await sandbox.executeCommand!(\n    `test -f \"${marker}\" && [ \"$(cat \"${marker}\")\" = ${shellQuote(content)} ]`,\n  );\n  return probe.exitCode === 0;\n}\n\nasync function writeWorkspaceMarker(sandbox: WorkspaceSandbox, root: string, content: string): Promise<void> {\n  const marker = `${root}/${WORKSPACE_SETUP_MARKER_PATH}`;\n  await sandbox.executeCommand!(\n    `mkdir -p \"$(dirname \"${marker}\")\" && printf '%s' ${shellQuote(content)} > \"${marker}\"`,\n  ).catch(() => {});\n}\n\n/**\n * The list-form start hook for a session whose factory has an environment:\n * the same lifecycle as `createSessionSetupHook`, with one gate per\n * repository plus one for the workspace setup command. The markers are the\n * ones the multi-repo templates write (`.mastra-sandbox/repos/<repoDir>`,\n * `.mastra-sandbox/workspace-setup`, `.mastra-sandbox/setup-failed`), all\n * under the workspace root, which is the parent of the primary repository's\n * directory: `resolveSessionWorkdir` keeps answering that directory so the\n * PR tools and passive readers see the primary checkout, and the root is\n * derived from it rather than probed twice.\n *\n * `repos` is in position order and must include the primary (`repoFullName`).\n */\nexport function createEnvironmentSetupHook(\n  run: SessionEnvironmentSetupRun,\n  sessionId: string,\n  repoFullName: string,\n  environment: { repos: SessionEnvironmentRepository[]; workspaceSetupCommand?: string },\n): SandboxStartHook {\n  const workspaceCommand = environment.workspaceSetupCommand?.trim() ? environment.workspaceSetupCommand : undefined;\n  const workspaceMarker = workspaceCommand ? setupMarkerContent(workspaceCommand) : undefined;\n  return async ({ sandbox }) => {\n    if (!sandbox.executeCommand) {\n      throw new Error(`Sandbox '${sandbox.id}' cannot run the session setup: no executeCommand implementation`);\n    }\n    const workdir = await resolveSessionWorkdir(sessionId, sandbox, repoFullName);\n    const root = path.posix.dirname(workdir);\n    const repos: SessionEnvironmentRepositoryGate[] = [];\n    for (const repo of environment.repos) {\n      const repoDir = repositoryDirectoryName(repo.slug);\n      const marker = repo.setupCommand?.trim() ? setupMarkerContent(repo.setupCommand) : undefined;\n      const setupDone = marker\n        ? await timedPhase(`workspace.setup-marker(${repoDir})`, () =>\n            repoMarkerMatches(sandbox, root, repoDir, marker),\n          )\n        : true;\n      if (marker) {\n        process.stderr.write(\n          `[factory:setup] ${repo.slug}: ${setupDone ? 'marker matches, skipping setup command' : 'no matching marker, setup command will run'} (${root}/${repoSetupMarkerPath(repoDir)})\\n`,\n        );\n      }\n      repos.push({\n        ...repo,\n        dir: `${root}/${repoDir}`,\n        gate: {\n          setupDone,\n          markSetupDone: () => (marker ? writeRepoMarker(sandbox, root, repoDir, marker) : Promise.resolve()),\n        },\n      });\n    }\n    const workspaceDone = workspaceMarker\n      ? await timedPhase('workspace.setup-marker(workspace)', () =>\n          workspaceMarkerMatches(sandbox, root, workspaceMarker),\n        )\n      : true;\n    await run(sandbox, {\n      root,\n      repos,\n      workspace: {\n        setupDone: workspaceDone,\n        markSetupDone: () =>\n          workspaceMarker ? writeWorkspaceMarker(sandbox, root, workspaceMarker) : Promise.resolve(),\n      },\n    });\n  };\n}\n"],"mappings":"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"}

package/dist/sandbox/workdir.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Session workdir derivation. Workdirs are never persisted or trusted from
+ * storage or client input — the stale-workdir class of production bugs came
+ * from reading `session.sandboxWorkdir` written under a different provider.
+ *
+ * Local sandboxes derive their workdir synchronously from the sandbox's own
+ * `workingDirectory` (the per-session directory the deploy's callback chose).
+ * Remote sandboxes have no invented path: the repo clones into the VM's own
+ * default cwd (its home dir), so the workdir is only knowable once a VM is
+ * running — resolved lazily by `resolveSessionWorkdir` via a one-time `pwd`
+ * probe and memoized on the session entry.
+ */
+/** Keep each path piece a single safe segment (no separators or traversal). */
+export declare function sanitizeSegment(segment: string): string;
+/**
+ * Synchronously derivable workdir: local sandboxes expose their host
+ * `workingDirectory`; the repo checks out as a contained subdirectory so the
+ * setup marker sits beside the clone instead of polluting `git status`
+ * inside it. Returns undefined for remote providers, whose workdir is a
+ * runtime fact of the VM (`<home>/<repo>`).
+ */
+export declare function deriveLocalWorkdir(sandbox: {
+    provider: string;
+    workingDirectory?: unknown;
+}, repoFullName: string): string | undefined;
+/** Derive `<workingDirectory>/<repo>` when a remote sandbox declares an absolute root. */
+export declare function deriveRemoteRepoDir(sandbox: {
+    provider: string;
+    workingDirectory?: unknown;
+}, repoFullName: string): string | undefined;
+/** Join a parent directory and sanitized repository name. */
+export declare function repoDirUnder(parent: string, repoFullName: string): string;
+/**
+ * The directory a repository checks out into, under the workspace root. Must
+ * agree with the repo templates' private `repoDirName`
+ * (`workspaces/platform-workspace/src/repo-template.ts`): the last segment
+ * of the clone URL, `[^A-Za-z0-9._-]` replaced by `-`, leading dots dropped,
+ * `repo` when nothing is left. A repository slug never ends in `.git`, so
+ * both derive the same name for every slug; `workdir.test.ts` pins the
+ * template's own fixtures.
+ */
+export declare function repositoryDirectoryName(repoFullName: string): string;
+/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */
+export declare function resolveContainedLocalWorkdir(root: string, ...segments: string[]): string;
+//# sourceMappingURL=workdir.d.ts.map

package/dist/sandbox/workdir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workdir.d.ts","sourceRoot":"","sources":["../../src/sandbox/workdir.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,EACzD,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,EACzD,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED,0FAA0F;AAC1F,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAKxF"}

package/dist/sandbox/workdir.js

@@ -0,0 +1,64 @@
+import * as path$1 from "path";
+//#region src/sandbox/workdir.ts
+/**
+* Session workdir derivation. Workdirs are never persisted or trusted from
+* storage or client input — the stale-workdir class of production bugs came
+* from reading `session.sandboxWorkdir` written under a different provider.
+*
+* Local sandboxes derive their workdir synchronously from the sandbox's own
+* `workingDirectory` (the per-session directory the deploy's callback chose).
+* Remote sandboxes have no invented path: the repo clones into the VM's own
+* default cwd (its home dir), so the workdir is only knowable once a VM is
+* running — resolved lazily by `resolveSessionWorkdir` via a one-time `pwd`
+* probe and memoized on the session entry.
+*/
+/** Keep each path piece a single safe segment (no separators or traversal). */
+function sanitizeSegment(segment) {
+	return segment.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "") || "repo";
+}
+/**
+* Synchronously derivable workdir: local sandboxes expose their host
+* `workingDirectory`; the repo checks out as a contained subdirectory so the
+* setup marker sits beside the clone instead of polluting `git status`
+* inside it. Returns undefined for remote providers, whose workdir is a
+* runtime fact of the VM (`<home>/<repo>`).
+*/
+function deriveLocalWorkdir(sandbox, repoFullName) {
+	const wd = sandbox.workingDirectory;
+	if (sandbox.provider === "local" && typeof wd === "string" && wd.length > 0) return resolveContainedLocalWorkdir(wd, repositoryDirectoryName(repoFullName));
+}
+/** Derive `<workingDirectory>/<repo>` when a remote sandbox declares an absolute root. */
+function deriveRemoteRepoDir(sandbox, repoFullName) {
+	const wd = sandbox.workingDirectory;
+	if (sandbox.provider !== "local" && typeof wd === "string" && wd.startsWith("/")) return repoDirUnder(wd, repoFullName);
+}
+/** Join a parent directory and sanitized repository name. */
+function repoDirUnder(parent, repoFullName) {
+	let end = parent.length;
+	while (end > 0 && parent[end - 1] === "/") end--;
+	return `${parent.slice(0, end)}/${repositoryDirectoryName(repoFullName)}`;
+}
+/**
+* The directory a repository checks out into, under the workspace root. Must
+* agree with the repo templates' private `repoDirName`
+* (`workspaces/platform-workspace/src/repo-template.ts`): the last segment
+* of the clone URL, `[^A-Za-z0-9._-]` replaced by `-`, leading dots dropped,
+* `repo` when nothing is left. A repository slug never ends in `.git`, so
+* both derive the same name for every slug; `workdir.test.ts` pins the
+* template's own fixtures.
+*/
+function repositoryDirectoryName(repoFullName) {
+	const segments = repoFullName.split("/");
+	return sanitizeSegment(segments.length > 1 ? segments.at(-1) || "repo" : "repo");
+}
+/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */
+function resolveContainedLocalWorkdir(root, ...segments) {
+	const resolvedRoot = path$1.resolve(root);
+	const resolved = path$1.resolve(resolvedRoot, ...segments);
+	if (resolved !== resolvedRoot && resolved.startsWith(`${resolvedRoot}${path$1.sep}`)) return resolved;
+	throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);
+}
+//#endregion
+export { deriveLocalWorkdir, deriveRemoteRepoDir, repoDirUnder, repositoryDirectoryName, resolveContainedLocalWorkdir, sanitizeSegment };
+
+//# sourceMappingURL=workdir.js.map

package/dist/sandbox/workdir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workdir.js","names":["path"],"sources":["../../src/sandbox/workdir.ts"],"sourcesContent":["import * as path from 'node:path';\n\n/**\n * Session workdir derivation. Workdirs are never persisted or trusted from\n * storage or client input — the stale-workdir class of production bugs came\n * from reading `session.sandboxWorkdir` written under a different provider.\n *\n * Local sandboxes derive their workdir synchronously from the sandbox's own\n * `workingDirectory` (the per-session directory the deploy's callback chose).\n * Remote sandboxes have no invented path: the repo clones into the VM's own\n * default cwd (its home dir), so the workdir is only knowable once a VM is\n * running — resolved lazily by `resolveSessionWorkdir` via a one-time `pwd`\n * probe and memoized on the session entry.\n */\n\n/** Keep each path piece a single safe segment (no separators or traversal). */\nexport function sanitizeSegment(segment: string): string {\n  const cleaned = segment.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^\\.+/, '');\n  return cleaned || 'repo';\n}\n\n/**\n * Synchronously derivable workdir: local sandboxes expose their host\n * `workingDirectory`; the repo checks out as a contained subdirectory so the\n * setup marker sits beside the clone instead of polluting `git status`\n * inside it. Returns undefined for remote providers, whose workdir is a\n * runtime fact of the VM (`<home>/<repo>`).\n */\nexport function deriveLocalWorkdir(\n  sandbox: { provider: string; workingDirectory?: unknown },\n  repoFullName: string,\n): string | undefined {\n  const wd = sandbox.workingDirectory;\n  if (sandbox.provider === 'local' && typeof wd === 'string' && wd.length > 0) {\n    return resolveContainedLocalWorkdir(wd, repositoryDirectoryName(repoFullName));\n  }\n  return undefined;\n}\n\n/** Derive `<workingDirectory>/<repo>` when a remote sandbox declares an absolute root. */\nexport function deriveRemoteRepoDir(\n  sandbox: { provider: string; workingDirectory?: unknown },\n  repoFullName: string,\n): string | undefined {\n  const wd = sandbox.workingDirectory;\n  if (sandbox.provider !== 'local' && typeof wd === 'string' && wd.startsWith('/')) {\n    return repoDirUnder(wd, repoFullName);\n  }\n  return undefined;\n}\n\n/** Join a parent directory and sanitized repository name. */\nexport function repoDirUnder(parent: string, repoFullName: string): string {\n  let end = parent.length;\n  while (end > 0 && parent[end - 1] === '/') end--;\n  return `${parent.slice(0, end)}/${repositoryDirectoryName(repoFullName)}`;\n}\n\n/**\n * The directory a repository checks out into, under the workspace root. Must\n * agree with the repo templates' private `repoDirName`\n * (`workspaces/platform-workspace/src/repo-template.ts`): the last segment\n * of the clone URL, `[^A-Za-z0-9._-]` replaced by `-`, leading dots dropped,\n * `repo` when nothing is left. A repository slug never ends in `.git`, so\n * both derive the same name for every slug; `workdir.test.ts` pins the\n * template's own fixtures.\n */\nexport function repositoryDirectoryName(repoFullName: string): string {\n  const segments = repoFullName.split('/');\n  return sanitizeSegment(segments.length > 1 ? segments.at(-1) || 'repo' : 'repo');\n}\n\n/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */\nexport function resolveContainedLocalWorkdir(root: string, ...segments: string[]): string {\n  const resolvedRoot = path.resolve(root);\n  const resolved = path.resolve(resolvedRoot, ...segments);\n  if (resolved !== resolvedRoot && resolved.startsWith(`${resolvedRoot}${path.sep}`)) return resolved;\n  throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgBA,SAAgB,gBAAgB,SAAyB;CAEvD,OADgB,QAAQ,QAAQ,oBAAoB,GAAG,CAAC,CAAC,QAAQ,QAAQ,EAC5D,KAAK;AACpB;;;;;;;;AASA,SAAgB,mBACd,SACA,cACoB;CACpB,MAAM,KAAK,QAAQ;CACnB,IAAI,QAAQ,aAAa,WAAW,OAAO,OAAO,YAAY,GAAG,SAAS,GACxE,OAAO,6BAA6B,IAAI,wBAAwB,YAAY,CAAC;AAGjF;;AAGA,SAAgB,oBACd,SACA,cACoB;CACpB,MAAM,KAAK,QAAQ;CACnB,IAAI,QAAQ,aAAa,WAAW,OAAO,OAAO,YAAY,GAAG,WAAW,GAAG,GAC7E,OAAO,aAAa,IAAI,YAAY;AAGxC;;AAGA,SAAgB,aAAa,QAAgB,cAA8B;CACzE,IAAI,MAAM,OAAO;CACjB,OAAO,MAAM,KAAK,OAAO,MAAM,OAAO,KAAK;CAC3C,OAAO,GAAG,OAAO,MAAM,GAAG,GAAG,EAAE,GAAG,wBAAwB,YAAY;AACxE;;;;;;;;;;AAWA,SAAgB,wBAAwB,cAA8B;CACpE,MAAM,WAAW,aAAa,MAAM,GAAG;CACvC,OAAO,gBAAgB,SAAS,SAAS,IAAI,SAAS,GAAG,EAAE,KAAK,SAAS,MAAM;AACjF;;AAGA,SAAgB,6BAA6B,MAAc,GAAG,UAA4B;CACxF,MAAM,eAAeA,OAAK,QAAQ,IAAI;CACtC,MAAM,WAAWA,OAAK,QAAQ,cAAc,GAAG,QAAQ;CACvD,IAAI,aAAa,gBAAgB,SAAS,WAAW,GAAG,eAAeA,OAAK,KAAK,GAAG,OAAO;CAC3F,MAAM,IAAI,MAAM,+DAA+D,UAAU;AAC3F"}

package/dist/secret-encryption.d.ts

@@ -0,0 +1,25 @@
+export interface DecryptedFactorySecret<T> {
+    value: T;
+    needsReencryption: boolean;
+}
+/** Encrypts opaque JSON values before they cross the Factory storage boundary. */
+export interface FactorySecretEncryption {
+    encrypt<T>(value: T): Promise<string>;
+    decrypt<T>(value: unknown): Promise<DecryptedFactorySecret<T>>;
+}
+export interface FactorySecretEncryptionKey {
+    id: string;
+    key: Uint8Array;
+}
+export interface FactorySecretEncryptionConfig {
+    primary: FactorySecretEncryptionKey;
+    previous?: FactorySecretEncryptionKey[];
+}
+/**
+ * Creates a versioned AES-256-GCM encryptor. The primary key is used for new
+ * writes; previous keys remain decrypt-only until stored values are rotated.
+ */
+export declare function createFactorySecretEncryption(config: FactorySecretEncryptionConfig): FactorySecretEncryption;
+/** Explicit plaintext compatibility for local, no-auth Factory development. */
+export declare function createPlaintextFactorySecretEncryption(): FactorySecretEncryption;
+//# sourceMappingURL=secret-encryption.d.ts.map

package/dist/secret-encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-encryption.d.ts","sourceRoot":"","sources":["../src/secret-encryption.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC;IACT,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,0BAA0B,CAAC;IACpC,QAAQ,CAAC,EAAE,0BAA0B,EAAE,CAAC;CACzC;AAgCD;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,6BAA6B,GAAG,uBAAuB,CAyD5G;AAED,+EAA+E;AAC/E,wBAAgB,sCAAsC,IAAI,uBAAuB,CAiBhF"}

package/dist/secret-encryption.js

@@ -0,0 +1,107 @@
+import { createCipheriv, createDecipheriv } from "crypto";
+//#region src/secret-encryption.ts
+const ENVELOPE_PREFIX = "mastra:factory-secret:v1:";
+const ALGORITHM = "aes-256-gcm";
+const IV_BYTES = 12;
+function validateKey({ id, key }) {
+	if (!id) throw new Error("[FactorySecretEncryption] Key id is required.");
+	const buffer = Buffer.from(key);
+	if (buffer.byteLength !== 32) throw new Error(`[FactorySecretEncryption] Key "${id}" must be exactly 32 bytes.`);
+	return buffer;
+}
+function parseEnvelope(value) {
+	let parsed;
+	try {
+		parsed = JSON.parse(Buffer.from(value.slice(25), "base64url").toString("utf8"));
+	} catch {
+		throw new Error("[FactorySecretEncryption] Invalid encrypted value.");
+	}
+	if (!parsed || typeof parsed !== "object" || typeof parsed.keyId !== "string" || typeof parsed.iv !== "string" || typeof parsed.ciphertext !== "string" || typeof parsed.tag !== "string") throw new Error("[FactorySecretEncryption] Invalid encrypted value.");
+	return parsed;
+}
+/**
+* Creates a versioned AES-256-GCM encryptor. The primary key is used for new
+* writes; previous keys remain decrypt-only until stored values are rotated.
+*/
+function createFactorySecretEncryption(config) {
+	const primaryKey = validateKey(config.primary);
+	const keys = /* @__PURE__ */ new Map([[config.primary.id, primaryKey]]);
+	for (const previous of config.previous ?? []) {
+		if (keys.has(previous.id)) throw new Error(`[FactorySecretEncryption] Duplicate key id "${previous.id}".`);
+		keys.set(previous.id, validateKey(previous));
+	}
+	return {
+		async encrypt(value) {
+			const iv = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES)));
+			const cipher = createCipheriv(ALGORITHM, primaryKey, iv);
+			const ciphertext = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+			const envelope = {
+				keyId: config.primary.id,
+				iv: iv.toString("base64url"),
+				ciphertext: ciphertext.toString("base64url"),
+				tag: cipher.getAuthTag().toString("base64url")
+			};
+			return `${ENVELOPE_PREFIX}${Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url")}`;
+		},
+		async decrypt(value) {
+			if (typeof value !== "string") return {
+				value: structuredClone(value),
+				needsReencryption: true
+			};
+			if (!value.startsWith(ENVELOPE_PREFIX)) try {
+				return {
+					value: JSON.parse(value),
+					needsReencryption: true
+				};
+			} catch {
+				return {
+					value,
+					needsReencryption: true
+				};
+			}
+			const envelope = parseEnvelope(value);
+			const key = keys.get(envelope.keyId);
+			if (!key) throw new Error(`[FactorySecretEncryption] Unknown key id "${envelope.keyId}".`);
+			try {
+				const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(envelope.iv, "base64url"));
+				decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
+				const plaintext = Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, "base64url")), decipher.final()]).toString("utf8");
+				return {
+					value: JSON.parse(plaintext),
+					needsReencryption: envelope.keyId !== config.primary.id
+				};
+			} catch {
+				throw new Error("[FactorySecretEncryption] Unable to decrypt encrypted value.");
+			}
+		}
+	};
+}
+/** Explicit plaintext compatibility for local, no-auth Factory development. */
+function createPlaintextFactorySecretEncryption() {
+	return {
+		async encrypt(value) {
+			return JSON.stringify(value);
+		},
+		async decrypt(value) {
+			if (typeof value !== "string") return {
+				value: structuredClone(value),
+				needsReencryption: false
+			};
+			try {
+				return {
+					value: JSON.parse(value),
+					needsReencryption: false
+				};
+			} catch {
+				return {
+					value,
+					needsReencryption: true
+				};
+			}
+		}
+	};
+}
+//#endregion
+export { createFactorySecretEncryption, createPlaintextFactorySecretEncryption };
+
+//# sourceMappingURL=secret-encryption.js.map

package/dist/secret-encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-encryption.js","names":[],"sources":["../src/secret-encryption.ts"],"sourcesContent":["import { createCipheriv, createDecipheriv } from 'node:crypto';\n\nconst ENVELOPE_PREFIX = 'mastra:factory-secret:v1:';\nconst ALGORITHM = 'aes-256-gcm';\nconst IV_BYTES = 12;\n\ninterface SecretEnvelopeV1 {\n  keyId: string;\n  iv: string;\n  ciphertext: string;\n  tag: string;\n}\n\nexport interface DecryptedFactorySecret<T> {\n  value: T;\n  needsReencryption: boolean;\n}\n\n/** Encrypts opaque JSON values before they cross the Factory storage boundary. */\nexport interface FactorySecretEncryption {\n  encrypt<T>(value: T): Promise<string>;\n  decrypt<T>(value: unknown): Promise<DecryptedFactorySecret<T>>;\n}\n\nexport interface FactorySecretEncryptionKey {\n  id: string;\n  key: Uint8Array;\n}\n\nexport interface FactorySecretEncryptionConfig {\n  primary: FactorySecretEncryptionKey;\n  previous?: FactorySecretEncryptionKey[];\n}\n\nfunction validateKey({ id, key }: FactorySecretEncryptionKey): Buffer {\n  if (!id) throw new Error('[FactorySecretEncryption] Key id is required.');\n  const buffer = Buffer.from(key);\n  if (buffer.byteLength !== 32) {\n    throw new Error(`[FactorySecretEncryption] Key \"${id}\" must be exactly 32 bytes.`);\n  }\n  return buffer;\n}\n\nfunction parseEnvelope(value: string): SecretEnvelopeV1 {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(Buffer.from(value.slice(ENVELOPE_PREFIX.length), 'base64url').toString('utf8'));\n  } catch {\n    throw new Error('[FactorySecretEncryption] Invalid encrypted value.');\n  }\n\n  if (\n    !parsed ||\n    typeof parsed !== 'object' ||\n    typeof (parsed as SecretEnvelopeV1).keyId !== 'string' ||\n    typeof (parsed as SecretEnvelopeV1).iv !== 'string' ||\n    typeof (parsed as SecretEnvelopeV1).ciphertext !== 'string' ||\n    typeof (parsed as SecretEnvelopeV1).tag !== 'string'\n  ) {\n    throw new Error('[FactorySecretEncryption] Invalid encrypted value.');\n  }\n  return parsed as SecretEnvelopeV1;\n}\n\n/**\n * Creates a versioned AES-256-GCM encryptor. The primary key is used for new\n * writes; previous keys remain decrypt-only until stored values are rotated.\n */\nexport function createFactorySecretEncryption(config: FactorySecretEncryptionConfig): FactorySecretEncryption {\n  const primaryKey = validateKey(config.primary);\n  const keys = new Map<string, Buffer>([[config.primary.id, primaryKey]]);\n  for (const previous of config.previous ?? []) {\n    if (keys.has(previous.id)) throw new Error(`[FactorySecretEncryption] Duplicate key id \"${previous.id}\".`);\n    keys.set(previous.id, validateKey(previous));\n  }\n\n  return {\n    async encrypt<T>(value: T): Promise<string> {\n      const iv = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(IV_BYTES)));\n      const cipher = createCipheriv(ALGORITHM, primaryKey, iv);\n      const ciphertext = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()]);\n      const envelope: SecretEnvelopeV1 = {\n        keyId: config.primary.id,\n        iv: iv.toString('base64url'),\n        ciphertext: ciphertext.toString('base64url'),\n        tag: cipher.getAuthTag().toString('base64url'),\n      };\n      return `${ENVELOPE_PREFIX}${Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64url')}`;\n    },\n\n    async decrypt<T>(value: unknown): Promise<DecryptedFactorySecret<T>> {\n      if (typeof value !== 'string') {\n        return { value: structuredClone(value) as T, needsReencryption: true };\n      }\n      if (!value.startsWith(ENVELOPE_PREFIX)) {\n        // JSON text written by the plaintext encryptor, or a raw pre-encryption\n        // secret string. Decode it the same way the plaintext encryptor does so\n        // migration encrypts the original value, not its JSON text.\n        try {\n          return { value: JSON.parse(value) as T, needsReencryption: true };\n        } catch {\n          return { value: value as T, needsReencryption: true };\n        }\n      }\n\n      const envelope = parseEnvelope(value);\n      const key = keys.get(envelope.keyId);\n      if (!key) throw new Error(`[FactorySecretEncryption] Unknown key id \"${envelope.keyId}\".`);\n\n      try {\n        const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(envelope.iv, 'base64url'));\n        decipher.setAuthTag(Buffer.from(envelope.tag, 'base64url'));\n        const plaintext = Buffer.concat([\n          decipher.update(Buffer.from(envelope.ciphertext, 'base64url')),\n          decipher.final(),\n        ]).toString('utf8');\n        return {\n          value: JSON.parse(plaintext) as T,\n          needsReencryption: envelope.keyId !== config.primary.id,\n        };\n      } catch {\n        throw new Error('[FactorySecretEncryption] Unable to decrypt encrypted value.');\n      }\n    },\n  };\n}\n\n/** Explicit plaintext compatibility for local, no-auth Factory development. */\nexport function createPlaintextFactorySecretEncryption(): FactorySecretEncryption {\n  return {\n    async encrypt<T>(value: T): Promise<string> {\n      return JSON.stringify(value);\n    },\n    async decrypt<T>(value: unknown): Promise<DecryptedFactorySecret<T>> {\n      if (typeof value !== 'string') return { value: structuredClone(value) as T, needsReencryption: false };\n      try {\n        return { value: JSON.parse(value) as T, needsReencryption: false };\n      } catch {\n        // Pre-encryption rows stored raw secret strings (e.g. a bare\n        // `custom_providers.api_key`), not JSON. Treat the raw string as the\n        // value and flag it so migration rewrites it in the current format.\n        return { value: value as T, needsReencryption: true };\n      }\n    },\n  };\n}\n"],"mappings":";;AAEA,MAAM,kBAAkB;AACxB,MAAM,YAAY;AAClB,MAAM,WAAW;AA8BjB,SAAS,YAAY,EAAE,IAAI,OAA2C;CACpE,IAAI,CAAC,IAAI,MAAM,IAAI,MAAM,+CAA+C;CACxE,MAAM,SAAS,OAAO,KAAK,GAAG;CAC9B,IAAI,OAAO,eAAe,IACxB,MAAM,IAAI,MAAM,kCAAkC,GAAG,4BAA4B;CAEnF,OAAO;AACT;AAEA,SAAS,cAAc,OAAiC;CACtD,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,OAAO,KAAK,MAAM,MAAM,EAAsB,GAAG,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC;CACpG,QAAQ;EACN,MAAM,IAAI,MAAM,oDAAoD;CACtE;CAEA,IACE,CAAC,UACD,OAAO,WAAW,YAClB,OAAQ,OAA4B,UAAU,YAC9C,OAAQ,OAA4B,OAAO,YAC3C,OAAQ,OAA4B,eAAe,YACnD,OAAQ,OAA4B,QAAQ,UAE5C,MAAM,IAAI,MAAM,oDAAoD;CAEtE,OAAO;AACT;;;;;AAMA,SAAgB,8BAA8B,QAAgE;CAC5G,MAAM,aAAa,YAAY,OAAO,OAAO;CAC7C,MAAM,uBAAO,IAAI,IAAoB,CAAC,CAAC,OAAO,QAAQ,IAAI,UAAU,CAAC,CAAC;CACtE,KAAK,MAAM,YAAY,OAAO,YAAY,CAAC,GAAG;EAC5C,IAAI,KAAK,IAAI,SAAS,EAAE,GAAG,MAAM,IAAI,MAAM,+CAA+C,SAAS,GAAG,GAAG;EACzG,KAAK,IAAI,SAAS,IAAI,YAAY,QAAQ,CAAC;CAC7C;CAEA,OAAO;EACL,MAAM,QAAW,OAA2B;GAC1C,MAAM,KAAK,OAAO,KAAK,WAAW,OAAO,gBAAgB,IAAI,WAAW,QAAQ,CAAC,CAAC;GAClF,MAAM,SAAS,eAAe,WAAW,YAAY,EAAE;GACvD,MAAM,aAAa,OAAO,OAAO,CAAC,OAAO,OAAO,KAAK,UAAU,KAAK,GAAG,MAAM,GAAG,OAAO,MAAM,CAAC,CAAC;GAC/F,MAAM,WAA6B;IACjC,OAAO,OAAO,QAAQ;IACtB,IAAI,GAAG,SAAS,WAAW;IAC3B,YAAY,WAAW,SAAS,WAAW;IAC3C,KAAK,OAAO,WAAW,CAAC,CAAC,SAAS,WAAW;GAC/C;GACA,OAAO,GAAG,kBAAkB,OAAO,KAAK,KAAK,UAAU,QAAQ,GAAG,MAAM,CAAC,CAAC,SAAS,WAAW;EAChG;EAEA,MAAM,QAAW,OAAoD;GACnE,IAAI,OAAO,UAAU,UACnB,OAAO;IAAE,OAAO,gBAAgB,KAAK;IAAQ,mBAAmB;GAAK;GAEvE,IAAI,CAAC,MAAM,WAAW,eAAe,GAInC,IAAI;IACF,OAAO;KAAE,OAAO,KAAK,MAAM,KAAK;KAAQ,mBAAmB;IAAK;GAClE,QAAQ;IACN,OAAO;KAAS;KAAY,mBAAmB;IAAK;GACtD;GAGF,MAAM,WAAW,cAAc,KAAK;GACpC,MAAM,MAAM,KAAK,IAAI,SAAS,KAAK;GACnC,IAAI,CAAC,KAAK,MAAM,IAAI,MAAM,6CAA6C,SAAS,MAAM,GAAG;GAEzF,IAAI;IACF,MAAM,WAAW,iBAAiB,WAAW,KAAK,OAAO,KAAK,SAAS,IAAI,WAAW,CAAC;IACvF,SAAS,WAAW,OAAO,KAAK,SAAS,KAAK,WAAW,CAAC;IAC1D,MAAM,YAAY,OAAO,OAAO,CAC9B,SAAS,OAAO,OAAO,KAAK,SAAS,YAAY,WAAW,CAAC,GAC7D,SAAS,MAAM,CACjB,CAAC,CAAC,CAAC,SAAS,MAAM;IAClB,OAAO;KACL,OAAO,KAAK,MAAM,SAAS;KAC3B,mBAAmB,SAAS,UAAU,OAAO,QAAQ;IACvD;GACF,QAAQ;IACN,MAAM,IAAI,MAAM,8DAA8D;GAChF;EACF;CACF;AACF;;AAGA,SAAgB,yCAAkE;CAChF,OAAO;EACL,MAAM,QAAW,OAA2B;GAC1C,OAAO,KAAK,UAAU,KAAK;EAC7B;EACA,MAAM,QAAW,OAAoD;GACnE,IAAI,OAAO,UAAU,UAAU,OAAO;IAAE,OAAO,gBAAgB,KAAK;IAAQ,mBAAmB;GAAM;GACrG,IAAI;IACF,OAAO;KAAE,OAAO,KAAK,MAAM,KAAK;KAAQ,mBAAmB;IAAM;GACnE,QAAQ;IAIN,OAAO;KAAS;KAAY,mBAAmB;IAAK;GACtD;EACF;CACF;AACF"}

package/dist/server-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Server-wide error handler for the MastraCode web surface.
+ *
+ * Installed as `server.onError`, which the deployer applies to the top-level
+ * Hono app AND the custom-route sub-app (`/web/*`, `/auth/*`) — without it,
+ * unexpected route errors surface as an opaque `Internal Server Error` with no
+ * server-side trace.
+ */
+import type { Context } from 'hono';
+/** Handle a route error: log full detail server-side, return structured JSON. */
+export declare function handleServerError(err: Error, c: Context): Response;
+//# sourceMappingURL=server-error.d.ts.map

package/dist/server-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-error.d.ts","sourceRoot":"","sources":["../src/server-error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAG,QAAQ,CAiBlE"}

package/dist/server-error.js

@@ -0,0 +1,16 @@
+import { HTTPException } from "hono/http-exception";
+//#region src/server-error.ts
+/** Handle a route error: log full detail server-side, return structured JSON. */
+function handleServerError(err, c) {
+	if (err instanceof HTTPException) return c.json({ error: err.message }, err.status);
+	const detail = err instanceof Error ? err.stack ?? err.message : String(err);
+	console.error(`[Mastra Factory] ${c.req.method} ${c.req.path} failed: ${detail}`);
+	return c.json({
+		error: "internal_error",
+		message: err instanceof Error ? err.message : String(err)
+	}, 500);
+}
+//#endregion
+export { handleServerError };
+
+//# sourceMappingURL=server-error.js.map

package/dist/server-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-error.js","names":[],"sources":["../src/server-error.ts"],"sourcesContent":["/**\n * Server-wide error handler for the MastraCode web surface.\n *\n * Installed as `server.onError`, which the deployer applies to the top-level\n * Hono app AND the custom-route sub-app (`/web/*`, `/auth/*`) — without it,\n * unexpected route errors surface as an opaque `Internal Server Error` with no\n * server-side trace.\n */\n\nimport type { Context } from 'hono';\nimport { HTTPException } from 'hono/http-exception';\n\n/** Handle a route error: log full detail server-side, return structured JSON. */\nexport function handleServerError(err: Error, c: Context): Response {\n  // Deliberate HTTP errors (auth middleware, body limits, handlers) keep their\n  // status + message; they are expected flows, not server faults.\n  if (err instanceof HTTPException) {\n    return c.json({ error: err.message }, err.status);\n  }\n\n  const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);\n  console.error(`[Mastra Factory] ${c.req.method} ${c.req.path} failed: ${detail}`);\n\n  return c.json(\n    {\n      error: 'internal_error',\n      message: err instanceof Error ? err.message : String(err),\n    },\n    500,\n  );\n}\n"],"mappings":";;;AAaA,SAAgB,kBAAkB,KAAY,GAAsB;CAGlE,IAAI,eAAe,eACjB,OAAO,EAAE,KAAK,EAAE,OAAO,IAAI,QAAQ,GAAG,IAAI,MAAM;CAGlD,MAAM,SAAS,eAAe,QAAS,IAAI,SAAS,IAAI,UAAW,OAAO,GAAG;CAC7E,QAAQ,MAAM,oBAAoB,EAAE,IAAI,OAAO,GAAG,EAAE,IAAI,KAAK,WAAW,QAAQ;CAEhF,OAAO,EAAE,KACP;EACE,OAAO;EACP,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;CAC1D,GACA,GACF;AACF"}