@mastra/factory 0.2.2-alpha.1 → 0.2.2-alpha.2

package/dist/sandbox/fleet.js

@@ -1,266 +1,288 @@
-// src/sandbox/fleet.ts
 import path from "path";
+//#region src/sandbox/fleet.ts
+/**
+* Project sandbox fleet: provisioning, reattach, teardown, and budgeting.
+*
+* Server-hosted projects never run on the web host itself. Each project gets
+* its own isolated sandbox (a `WorkspaceSandbox`, e.g. a Railway VM) `clone()`d
+* from the machine the factory was configured with. This module owns everything
+* about that fleet — which provider is active, where checkouts live inside a
+* sandbox, the idle window, the per-replica budget, and the
+* provision/reattach/teardown lifecycle — but knows nothing about what runs
+* inside a sandbox (git materialization lives with its feature, e.g. the
+* GitHub integration's `sandbox.ts`).
+*
+* The fleet is constructed once at boot with the machine config (or none, when
+* sandboxes are disabled) and handed to consumers — no global registry.
+* Persistence of the provider's reattach id is delegated to the caller via
+* {@link SandboxBindingStore}, so the fleet stays storage-agnostic. Tests can
+* swap the low-level construction via {@link SandboxFleet.setFactory}.
+*/
+/** Invoke a progress callback without letting it break the actual work. */
 function reportProgress(onProgress, event) {
-  if (!onProgress) return;
-  try {
-    onProgress(event);
-  } catch {
-  }
+	if (!onProgress) return;
+	try {
+		onProgress(event);
+	} catch {}
 }
+/** Raised when provisioning would exceed the per-replica sandbox budget. */
 var SandboxBudgetError = class extends Error {
-  constructor(max) {
-    super(
-      `Sandbox budget exceeded: this server already has ${max} active sandbox(es), the configured per-replica maximum. Close an existing repository's sandbox and try again.`
-    );
-    this.max = max;
-    this.name = "SandboxBudgetError";
-  }
-  max;
-  code = "sandbox-budget-exceeded";
+	max;
+	code = "sandbox-budget-exceeded";
+	constructor(max) {
+		super(`Sandbox budget exceeded: this server already has ${max} active sandbox(es), the configured per-replica maximum. Close an existing repository's sandbox and try again.`);
+		this.max = max;
+		this.name = "SandboxBudgetError";
+	}
 };
+/**
+* Adapt a cloned `WorkspaceSandbox` to the minimal surface this module needs.
+* Lifecycle goes through the `_`-prefixed wrappers when present (they add
+* status tracking and concurrency safety on `MastraSandbox` subclasses),
+* falling back to the plain methods for interface-only implementations.
+*/
 function toMaterializationSandbox(sandbox, initialEnvironment = {}) {
-  if (typeof sandbox.executeCommand !== "function") {
-    throw new Error(
-      `Sandbox provider '${sandbox.provider}' does not implement executeCommand() \u2014 cannot materialize repos.`
-    );
-  }
-  const lifecycle = sandbox;
-  const environment = { ...initialEnvironment };
-  return {
-    id: sandbox.id,
-    start: async () => {
-      await (lifecycle._start ?? sandbox.start)?.call(sandbox);
-    },
-    getInfo: async () => await sandbox.getInfo?.() ?? {},
-    executeCommand: (command, args, options) => sandbox.executeCommand(command, args, {
-      ...options,
-      env: { ...environment, ...options?.env }
-    }),
-    setEnvironmentVariable: (name, value) => {
-      environment[name] = value;
-    },
-    stop: async () => {
-      await (lifecycle._stop ?? sandbox.stop)?.call(sandbox);
-    }
-  };
+	if (typeof sandbox.executeCommand !== "function") throw new Error(`Sandbox provider '${sandbox.provider}' does not implement executeCommand() — cannot materialize repos.`);
+	const lifecycle = sandbox;
+	const environment = { ...initialEnvironment };
+	return {
+		id: sandbox.id,
+		start: async () => {
+			await (lifecycle._start ?? sandbox.start)?.call(sandbox);
+		},
+		getInfo: async () => await sandbox.getInfo?.() ?? {},
+		executeCommand: (command, args, options) => sandbox.executeCommand(command, args, {
+			...options,
+			env: {
+				...environment,
+				...options?.env
+			}
+		}),
+		setEnvironmentVariable: (name, value) => {
+			environment[name] = value;
+		},
+		stop: async () => {
+			await (lifecycle._stop ?? sandbox.stop)?.call(sandbox);
+		}
+	};
 }
+/**
+* The provider's reattach id for a started sandbox. For Railway this is the
+* underlying `railwaySandboxId` in `getInfo().metadata`. Providers without a
+* provider-native id (e.g. local) reattach by construction id, so fall back
+* to the sandbox's own logical id.
+*/
 async function readProviderSandboxId(sandbox) {
-  const info = await sandbox.getInfo();
-  const id = info.metadata?.railwaySandboxId ?? info.metadata?.sandboxId;
-  return typeof id === "string" ? id : sandbox.id;
+	const info = await sandbox.getInfo();
+	const id = info.metadata?.railwaySandboxId ?? info.metadata?.sandboxId;
+	return typeof id === "string" ? id : sandbox.id;
 }
+/** Keep each path piece a single safe segment (no separators or traversal). */
 function sanitizeSegment(segment) {
-  const cleaned = segment.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "");
-  return cleaned || "repo";
+	return segment.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^\.+/, "") || "repo";
 }
+/** Resolve a workdir under `root`, refusing any path that escapes the configured root. */
 function resolveContainedLocalWorkdir(root, ...segments) {
-  const resolvedRoot = path.resolve(root);
-  const resolved = path.resolve(resolvedRoot, ...segments);
-  if (resolved !== resolvedRoot && resolved.startsWith(`${resolvedRoot}${path.sep}`)) return resolved;
-  throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);
+	const resolvedRoot = path.resolve(root);
+	const resolved = path.resolve(resolvedRoot, ...segments);
+	if (resolved !== resolvedRoot && resolved.startsWith(`${resolvedRoot}${path.sep}`)) return resolved;
+	throw new Error(`Refusing to use local sandbox path outside configured root: ${resolved}`);
 }
+/**
+* The sandbox fleet for one deployment. Constructed once at boot — with a
+* config when a sandbox machine was configured, or without one when sandboxes
+* are disabled (every provisioning entry point then throws and
+* {@link enabled} reports `false` so features stay off).
+*/
 var SandboxFleet = class {
-  #config;
-  #factory;
-  #liveCount = 0;
-  constructor(config) {
-    this.#config = config;
-  }
-  /**
-   * True when a sandbox machine was configured. The factory validates the
-   * machine implements `clone()` at boot, so a configured fleet is usable —
-   * sandbox-backed projects stay off only when the slot was omitted.
-   */
-  get enabled() {
-    return this.#config !== void 0;
-  }
-  /**
-   * Name of the active sandbox provider — the configured machine's `provider`
-   * discriminator (`'railway'`, `'local'`, …), or `'none'` when the fleet was
-   * constructed without a config. Diagnostic only; feature gating goes
-   * through {@link enabled}.
-   */
-  get provider() {
-    return this.#config?.machine.provider ?? "none";
-  }
-  /**
-   * Idle teardown window for provisioned sandboxes, in minutes; defaults to 30.
-   * Read back from the machine's own config when it exposes one
-   * (Railway's `idleTimeoutMinutes`) — the knob lives on the sandbox, the
-   * fleet only needs it to schedule GC and stamp sandbox clones. Advisory:
-   * providers without idle GC ignore it, and a re-open detects a torn-down VM
-   * and re-provisions cleanly.
-   */
-  get idleMinutes() {
-    const machine = this.#config?.machine;
-    const minutes = machine?.idleTimeoutMinutes;
-    return typeof minutes === "number" && Number.isFinite(minutes) && minutes > 0 ? minutes : 30;
-  }
-  /**
-   * Per-replica cap on concurrently *provisioned* sandboxes. 0 means unlimited.
-   * This is a lightweight per-process budget to keep a single replica from
-   * exhausting provider quota — it is not a global, cross-replica scheduler
-   * (that is a deferred follow-up).
-   */
-  get maxSandboxes() {
-    return this.#config?.maxSandboxes ?? 0;
-  }
-  /**
-   * Count of sandboxes this fleet has freshly provisioned and not yet torn
-   * down. Reattaches to existing VMs do not count (they reuse an already-billed
-   * sandbox). Used to enforce {@link maxSandboxes}.
-   */
-  get liveCount() {
-    return this.#liveCount;
-  }
-  /** For tests: reset the live-sandbox counter to a known state. */
-  __resetLiveCount(value = 0) {
-    this.#liveCount = value;
-  }
-  /** Override the sandbox factory (tests). */
-  setFactory(factory) {
-    this.#factory = factory;
-  }
-  /** Reset to the default machine-cloning factory. */
-  resetFactory() {
-    this.#factory = void 0;
-  }
-  /**
-   * Compute the in-sandbox working directory for a repo: a nested
-   * `<base>/<owner>/<name>` layout under the factory-resolved checkout base.
-   * Nesting keeps same-name repos apart (`acme/api` vs `other/api`) — cloud
-   * sandboxes are one-per-project so it's merely tidy there, but local
-   * checkouts share one host root where it prevents collisions. Server-side
-   * only; never derived from client input.
-   */
-  computeWorkdir(repoFullName) {
-    if (!this.#config) throw new Error("No sandbox configured");
-    const [owner, name] = repoFullName.split("/", 2);
-    return `${this.#config.workdirBase}/${sanitizeSegment(owner || "unknown")}/${sanitizeSegment(name || "repo")}`;
-  }
-  /**
-   * Compute the host working directory for a local GitHub session checkout.
-   * This is server-derived only: repo pieces are sanitized and the trusted
-   * session id is kept as a single path segment under the configured local root.
-   */
-  computeLocalSessionWorkdir(repoFullName, sessionId) {
-    if (!this.#config) throw new Error("No sandbox configured");
-    if (this.#config.machine.provider !== "local") {
-      throw new Error("Local session workdirs require the local sandbox provider");
-    }
-    const localRoot = this.#config.machine.workingDirectory;
-    if (typeof localRoot !== "string" || localRoot.length === 0) {
-      throw new Error("Local sandbox working directory is not configured");
-    }
-    const [owner, name] = repoFullName.split("/", 2);
-    return resolveContainedLocalWorkdir(
-      localRoot,
-      "github-sessions",
-      sanitizeSegment(owner || "unknown"),
-      sanitizeSegment(name || "repo"),
-      sanitizeSegment(sessionId)
-    );
-  }
-  /**
-   * Build a (not-yet-started) sandbox: the test-provided factory when set,
-   * otherwise a per-project clone of the configured machine. The stored id is
-   * passed both as the logical `id` (providers that reattach by construction
-   * id, e.g. local) and as the provider-native `sandboxId` hint (Railway) so
-   * reattach works across the provider matrix.
-   */
-  #build(opts) {
-    if (this.#factory) return this.#factory(opts);
-    if (!this.#config) throw new Error("No sandbox configured");
-    const clone = this.#config.machine.clone({
-      ...opts.providerSandboxId ? { id: opts.providerSandboxId, sandboxId: opts.providerSandboxId } : {},
-      ...opts.env ? { env: opts.env } : {},
-      ...opts.workingDirectory ? { workingDirectory: opts.workingDirectory } : {},
-      ...opts.idleTimeoutMinutes !== void 0 ? { idleTimeoutMinutes: opts.idleTimeoutMinutes } : {},
-      ...opts.checkpointName ? { checkpointName: opts.checkpointName } : {}
-    });
-    return toMaterializationSandbox(clone, opts.env);
-  }
-  async ensureSandbox(store, envOrProgress, progressOrOptions, maybeOptions = {}) {
-    const env = typeof envOrProgress === "function" ? void 0 : envOrProgress;
-    const onProgress = typeof envOrProgress === "function" ? envOrProgress : progressOrOptions;
-    const options = typeof envOrProgress === "function" ? progressOrOptions ?? {} : maybeOptions;
-    const idleTimeoutMinutes = this.idleMinutes;
-    const checkpointName = store.checkpointName;
-    if (store.sandboxId) {
-      reportProgress(onProgress, { phase: "reattaching", message: "Reconnecting to your sandbox\u2026" });
-      const reattached = this.#build({
-        providerSandboxId: store.sandboxId,
-        idleTimeoutMinutes,
-        ...checkpointName ? { checkpointName } : {},
-        ...env ? { env } : {},
-        ...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
-      });
-      try {
-        await reattached.start();
-        return reattached;
-      } catch {
-        await store.setSandboxId(null);
-      }
-    }
-    const max = this.maxSandboxes;
-    if (max > 0 && this.#liveCount >= max) {
-      throw new SandboxBudgetError(max);
-    }
-    reportProgress(onProgress, { phase: "provisioning", message: "Provisioning a new sandbox\u2026" });
-    const sandbox = this.#build({
-      idleTimeoutMinutes,
-      ...checkpointName ? { checkpointName } : {},
-      ...env ? { env } : {},
-      ...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
-    });
-    await sandbox.start();
-    this.#liveCount += 1;
-    const providerSandboxId = await readProviderSandboxId(sandbox);
-    if (providerSandboxId) {
-      await store.setSandboxId(providerSandboxId);
-    }
-    return sandbox;
-  }
-  /**
-   * Tear down a sandbox binding: stop the live VM (best-effort) and clear the
-   * persisted state through the binding store so the next open re-provisions
-   * cleanly. Decrements the per-replica live-sandbox counter.
-   *
-   * @param store   the binding to tear down
-   * @param sandbox an already-reattached live sandbox to stop, when available
-   */
-  async teardownSandbox(store, sandbox) {
-    if (sandbox?.stop) {
-      try {
-        await sandbox.stop();
-      } catch {
-      }
-    }
-    if (store.sandboxId) {
-      if (this.#liveCount > 0) this.#liveCount -= 1;
-      await store.clear();
-    }
-  }
-  /**
-   * Reattach to an already-provisioned sandbox by its provider id and start it.
-   * Used by the workspace seam when opening a project that was already
-   * materialized (sandbox id + workdir carried on controller state), so no DB
-   * round-trip is needed.
-   */
-  async reattachSandbox(providerSandboxId, options = {}) {
-    const sandbox = this.#build({
-      providerSandboxId,
-      idleTimeoutMinutes: this.idleMinutes,
-      ...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
-    });
-    await sandbox.start();
-    return sandbox;
-  }
-};
-export {
-  SandboxBudgetError,
-  SandboxFleet,
-  reportProgress,
-  resolveContainedLocalWorkdir
+	#config;
+	#factory;
+	#liveCount = 0;
+	constructor(config) {
+		this.#config = config;
+	}
+	/**
+	* True when a sandbox machine was configured. The factory validates the
+	* machine implements `clone()` at boot, so a configured fleet is usable —
+	* sandbox-backed projects stay off only when the slot was omitted.
+	*/
+	get enabled() {
+		return this.#config !== void 0;
+	}
+	/**
+	* Name of the active sandbox provider — the configured machine's `provider`
+	* discriminator (`'railway'`, `'local'`, …), or `'none'` when the fleet was
+	* constructed without a config. Diagnostic only; feature gating goes
+	* through {@link enabled}.
+	*/
+	get provider() {
+		return this.#config?.machine.provider ?? "none";
+	}
+	/**
+	* Idle teardown window for provisioned sandboxes, in minutes; defaults to 30.
+	* Read back from the machine's own config when it exposes one
+	* (Railway's `idleTimeoutMinutes`) — the knob lives on the sandbox, the
+	* fleet only needs it to schedule GC and stamp sandbox clones. Advisory:
+	* providers without idle GC ignore it, and a re-open detects a torn-down VM
+	* and re-provisions cleanly.
+	*/
+	get idleMinutes() {
+		const minutes = (this.#config?.machine)?.idleTimeoutMinutes;
+		return typeof minutes === "number" && Number.isFinite(minutes) && minutes > 0 ? minutes : 30;
+	}
+	/**
+	* Per-replica cap on concurrently *provisioned* sandboxes. 0 means unlimited.
+	* This is a lightweight per-process budget to keep a single replica from
+	* exhausting provider quota — it is not a global, cross-replica scheduler
+	* (that is a deferred follow-up).
+	*/
+	get maxSandboxes() {
+		return this.#config?.maxSandboxes ?? 0;
+	}
+	/**
+	* Count of sandboxes this fleet has freshly provisioned and not yet torn
+	* down. Reattaches to existing VMs do not count (they reuse an already-billed
+	* sandbox). Used to enforce {@link maxSandboxes}.
+	*/
+	get liveCount() {
+		return this.#liveCount;
+	}
+	/** For tests: reset the live-sandbox counter to a known state. */
+	__resetLiveCount(value = 0) {
+		this.#liveCount = value;
+	}
+	/** Override the sandbox factory (tests). */
+	setFactory(factory) {
+		this.#factory = factory;
+	}
+	/** Reset to the default machine-cloning factory. */
+	resetFactory() {
+		this.#factory = void 0;
+	}
+	/**
+	* Compute the in-sandbox working directory for a repo: a nested
+	* `<base>/<owner>/<name>` layout under the factory-resolved checkout base.
+	* Nesting keeps same-name repos apart (`acme/api` vs `other/api`) — cloud
+	* sandboxes are one-per-project so it's merely tidy there, but local
+	* checkouts share one host root where it prevents collisions. Server-side
+	* only; never derived from client input.
+	*/
+	computeWorkdir(repoFullName) {
+		if (!this.#config) throw new Error("No sandbox configured");
+		const [owner, name] = repoFullName.split("/", 2);
+		return `${this.#config.workdirBase}/${sanitizeSegment(owner || "unknown")}/${sanitizeSegment(name || "repo")}`;
+	}
+	/**
+	* Compute the host working directory for a local GitHub session checkout.
+	* This is server-derived only: repo pieces are sanitized and the trusted
+	* session id is kept as a single path segment under the configured local root.
+	*/
+	computeLocalSessionWorkdir(repoFullName, sessionId) {
+		if (!this.#config) throw new Error("No sandbox configured");
+		if (this.#config.machine.provider !== "local") throw new Error("Local session workdirs require the local sandbox provider");
+		const localRoot = this.#config.machine.workingDirectory;
+		if (typeof localRoot !== "string" || localRoot.length === 0) throw new Error("Local sandbox working directory is not configured");
+		const [owner, name] = repoFullName.split("/", 2);
+		return resolveContainedLocalWorkdir(localRoot, "github-sessions", sanitizeSegment(owner || "unknown"), sanitizeSegment(name || "repo"), sanitizeSegment(sessionId));
+	}
+	/**
+	* Build a (not-yet-started) sandbox: the test-provided factory when set,
+	* otherwise a per-project clone of the configured machine. The stored id is
+	* passed both as the logical `id` (providers that reattach by construction
+	* id, e.g. local) and as the provider-native `sandboxId` hint (Railway) so
+	* reattach works across the provider matrix.
+	*/
+	#build(opts) {
+		if (this.#factory) return this.#factory(opts);
+		if (!this.#config) throw new Error("No sandbox configured");
+		return toMaterializationSandbox(this.#config.machine.clone({
+			...opts.providerSandboxId ? {
+				id: opts.providerSandboxId,
+				sandboxId: opts.providerSandboxId
+			} : {},
+			...opts.env ? { env: opts.env } : {},
+			...opts.workingDirectory ? { workingDirectory: opts.workingDirectory } : {},
+			...opts.idleTimeoutMinutes !== void 0 ? { idleTimeoutMinutes: opts.idleTimeoutMinutes } : {},
+			...opts.checkpointName ? { checkpointName: opts.checkpointName } : {}
+		}), opts.env);
+	}
+	async ensureSandbox(store, envOrProgress, progressOrOptions, maybeOptions = {}) {
+		const env = typeof envOrProgress === "function" ? void 0 : envOrProgress;
+		const onProgress = typeof envOrProgress === "function" ? envOrProgress : progressOrOptions;
+		const options = typeof envOrProgress === "function" ? progressOrOptions ?? {} : maybeOptions;
+		const idleTimeoutMinutes = this.idleMinutes;
+		const checkpointName = store.checkpointName;
+		if (store.sandboxId) {
+			reportProgress(onProgress, {
+				phase: "reattaching",
+				message: "Reconnecting to your sandbox…"
+			});
+			const reattached = this.#build({
+				providerSandboxId: store.sandboxId,
+				idleTimeoutMinutes,
+				...checkpointName ? { checkpointName } : {},
+				...env ? { env } : {},
+				...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
+			});
+			try {
+				await reattached.start();
+				return reattached;
+			} catch {
+				await store.setSandboxId(null);
+			}
+		}
+		const max = this.maxSandboxes;
+		if (max > 0 && this.#liveCount >= max) throw new SandboxBudgetError(max);
+		reportProgress(onProgress, {
+			phase: "provisioning",
+			message: "Provisioning a new sandbox…"
+		});
+		const sandbox = this.#build({
+			idleTimeoutMinutes,
+			...checkpointName ? { checkpointName } : {},
+			...env ? { env } : {},
+			...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
+		});
+		await sandbox.start();
+		this.#liveCount += 1;
+		const providerSandboxId = await readProviderSandboxId(sandbox);
+		if (providerSandboxId) await store.setSandboxId(providerSandboxId);
+		return sandbox;
+	}
+	/**
+	* Tear down a sandbox binding: stop the live VM (best-effort) and clear the
+	* persisted state through the binding store so the next open re-provisions
+	* cleanly. Decrements the per-replica live-sandbox counter.
+	*
+	* @param store   the binding to tear down
+	* @param sandbox an already-reattached live sandbox to stop, when available
+	*/
+	async teardownSandbox(store, sandbox) {
+		if (sandbox?.stop) try {
+			await sandbox.stop();
+		} catch {}
+		if (store.sandboxId) {
+			if (this.#liveCount > 0) this.#liveCount -= 1;
+			await store.clear();
+		}
+	}
+	/**
+	* Reattach to an already-provisioned sandbox by its provider id and start it.
+	* Used by the workspace seam when opening a project that was already
+	* materialized (sandbox id + workdir carried on controller state), so no DB
+	* round-trip is needed.
+	*/
+	async reattachSandbox(providerSandboxId, options = {}) {
+		const sandbox = this.#build({
+			providerSandboxId,
+			idleTimeoutMinutes: this.idleMinutes,
+			...options.workingDirectory ? { workingDirectory: options.workingDirectory } : {}
+		});
+		await sandbox.start();
+		return sandbox;
+	}
 };
+//#endregion
+export { SandboxBudgetError, SandboxFleet, reportProgress, resolveContainedLocalWorkdir };
+
 //# sourceMappingURL=fleet.js.map