@mastra/platform-workspace 1.7.0 → 1.8.0

package/dist/factory-sandbox.d.ts

@@ -0,0 +1,39 @@
+import type { PublicSchema } from '@mastra/core/schema';
+import { FactorySandbox } from '@mastra/core/workspace';
+import type { FactorySandboxBuilds, FactorySandboxContext } from '@mastra/core/workspace';
+import type { PlatformRepoTemplateResolver } from './repo-template.js';
+import { PlatformSandbox } from './sandbox.js';
+import type { PlatformSandboxOptions } from './sandbox.js';
+/** User-tunable settings of a platform factory sandbox. Every field is optional; absent means the provider default. */
+export interface PlatformFactorySandboxSettings extends Record<string, unknown> {
+    /** vCPUs for the sandbox template. Part of the template identity. */
+    cpuCount?: number;
+    /** Memory in MB for the sandbox template. Part of the template identity. */
+    memoryMb?: number;
+    /** Minutes idle before the sandbox pauses. Runtime only. */
+    idleTimeoutMinutes?: number;
+}
+export interface PlatformFactorySandboxOptions extends Omit<PlatformSandboxOptions, 'id' | 'sandboxId' | 'sessionId' | 'template'> {
+    /** Options for the environment's repo template. */
+    template?: {
+        /** Build-only environment, excluded from template identity and runtime sandboxes. */
+        buildEnv?: Record<string, string>;
+    };
+    /** Provider-side defaults used when a setting is unset. Never stored by factory. */
+    defaults?: Partial<PlatformFactorySandboxSettings>;
+}
+/**
+ * The platform host contract for factory: every session sandbox is a
+ * {@link PlatformSandbox} whose template is {@link createRepoTemplate} over
+ * the session's repositories, sized by the factory's environment settings.
+ */
+export declare class PlatformFactorySandbox extends FactorySandbox<PlatformFactorySandboxSettings> {
+    #private;
+    readonly provider = "platform";
+    readonly settings: PublicSchema<PlatformFactorySandboxSettings>;
+    readonly builds: FactorySandboxBuilds<PlatformFactorySandboxSettings>;
+    constructor(options?: PlatformFactorySandboxOptions);
+    template(ctx: FactorySandboxContext, settings: PlatformFactorySandboxSettings): PlatformRepoTemplateResolver | undefined;
+    create(ctx: FactorySandboxContext, settings: PlatformFactorySandboxSettings): PlatformSandbox;
+}
+//# sourceMappingURL=factory-sandbox.d.ts.map

package/dist/factory-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory-sandbox.d.ts","sourceRoot":"","sources":["../src/factory-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAIV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAG3D,uHAAuH;AACvH,MAAM,WAAW,8BAA+B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7E,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAwDD,MAAM,WAAW,6BAA8B,SAAQ,IAAI,CACzD,sBAAsB,EACtB,IAAI,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,CAC9C;IACC,mDAAmD;IACnD,QAAQ,CAAC,EAAE;QACT,qFAAqF;QACrF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACnC,CAAC;IACF,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC,8BAA8B,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,8BAA8B,CAAC;;IACxF,QAAQ,CAAC,QAAQ,cAAc;IAC/B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,8BAA8B,CAAC,CAAC;IAehE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,8BAA8B,CAAC,CAGnE;IAEF,YAAY,OAAO,GAAE,6BAAkC,EAOtD;IAED,QAAQ,CACN,GAAG,EAAE,qBAAqB,EAC1B,QAAQ,EAAE,8BAA8B,GACvC,4BAA4B,GAAG,SAAS,CAQ1C;IAED,MAAM,CAAC,GAAG,EAAE,qBAAqB,EAAE,QAAQ,EAAE,8BAA8B,GAAG,eAAe,CAiB5F;CA4CF"}

package/dist/index.cjs

@@ -25,9 +25,9 @@ let buffer = require("buffer");
 let path = require("path");
 path = __toESM(path, 1);
 let _mastra_core_workspace = require("@mastra/core/workspace");
+let crypto = require("crypto");
 let e2b = require("e2b");
 let child_process = require("child_process");
-let crypto = require("crypto");
 let util = require("util");
 //#region src/client.ts
 const DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
@@ -1434,7 +1434,12 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			sessionId: this._client.sessionId,
 			mode,
 			totalMs: Date.now() - startedAt,
-			requestMs
+			requestMs,
+			...mode === "provision" && this._templateDefinition ? {
+				templateHash: templateHash(this._templateDefinition),
+				templateBoot: this.templatePending ? "pending" : "exact",
+				...this.templatePending ? { pendingTemplateId: this.templatePending.templateId } : {}
+			} : {}
 		});
 	}
 	/**
@@ -2021,6 +2026,17 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		return defaultInstructions;
 	}
 };
+/**
+* Diagnostic fingerprint of the serialized template a sandbox was provisioned
+* with: the same definition (repositories, pinned heads, setup commands,
+* resources) hashes the same on warm and cold boots. `family` is excluded, as
+* in the server's exact-content identity. Not the server's cache digest, which
+* also normalizes resources.
+*/
+function templateHash(definition) {
+	const { family: _family, ...content } = definition;
+	return (0, crypto.createHash)("sha256").update(JSON.stringify(content)).digest("hex").slice(0, 16);
+}
 //#endregion
 //#region ../../packages/_internals/workspace/dist/index.js
 /** Directory, relative to the template's build cwd, that holds every marker below. */
@@ -2474,6 +2490,157 @@ const platformFilesystemProvider = {
 	createFilesystem: (config) => new PlatformFilesystem(config)
 };
 //#endregion
+//#region src/factory-sandbox.ts
+/** Applied when neither the environment setting nor a host default is set. */
+const DEFAULT_SETTINGS = {
+	cpuCount: 2,
+	memoryMb: 1024,
+	idleTimeoutMinutes: 5
+};
+const SETTINGS_SCHEMA = {
+	type: "object",
+	properties: {
+		cpuCount: {
+			type: "integer",
+			title: "CPU",
+			description: "vCPUs for the sandbox template",
+			default: DEFAULT_SETTINGS.cpuCount,
+			minimum: 1,
+			maximum: 64
+		},
+		memoryMb: {
+			type: "integer",
+			title: "Memory (MB)",
+			description: "Memory in MB for the sandbox template",
+			default: DEFAULT_SETTINGS.memoryMb,
+			minimum: 512,
+			maximum: 65536
+		},
+		idleTimeoutMinutes: {
+			type: "integer",
+			title: "Idle timeout (minutes)",
+			description: "Minutes idle before the sandbox pauses",
+			default: DEFAULT_SETTINGS.idleTimeoutMinutes,
+			minimum: 1,
+			maximum: 1440
+		}
+	},
+	additionalProperties: false
+};
+/**
+* The settings schema with the provider's effective defaults as `default`:
+* the built-in values, overridden by the host's `idleTimeoutMinutes` option and
+* then its `defaults` option. The schema
+* is what clients show as placeholders, so it must match what the provider
+* applies when a setting is unset.
+*/
+function settingsSchema(defaults) {
+	const effective = {
+		...DEFAULT_SETTINGS,
+		...defaults
+	};
+	const properties = Object.fromEntries(Object.entries(SETTINGS_SCHEMA.properties).map(([key, property]) => [key, {
+		...property,
+		default: effective[key]
+	}]));
+	return {
+		...SETTINGS_SCHEMA,
+		properties
+	};
+}
+/**
+* The platform host contract for factory: every session sandbox is a
+* {@link PlatformSandbox} whose template is {@link createRepoTemplate} over
+* the session's repositories, sized by the factory's environment settings.
+*/
+var PlatformFactorySandbox = class extends _mastra_core_workspace.FactorySandbox {
+	provider = "platform";
+	settings;
+	#options;
+	/**
+	* Builders by template id from this process's `builds.start` calls. Platform
+	* has no build status endpoint; re-calling the same builder's idempotent
+	* `build()` is the status poll. After a restart earlier builds read as
+	* `unknown`.
+	*
+	* TODO: once the platform API exposes build status and build history, read
+	* `get` from the API instead of this in-memory cache and add `builds.list`.
+	*/
+	#builders = /* @__PURE__ */ new Map();
+	builds = {
+		start: (ctx, settings) => this.#startBuild(ctx, settings),
+		get: (ctx, settings, buildId) => this.#getBuild(ctx, settings, buildId)
+	};
+	constructor(options = {}) {
+		super();
+		this.#options = options;
+		this.settings = settingsSchema({
+			...options.idleTimeoutMinutes !== void 0 ? { idleTimeoutMinutes: options.idleTimeoutMinutes } : {},
+			...options.defaults
+		});
+	}
+	template(ctx, settings) {
+		const { defaults, template } = this.#options;
+		return createRepoTemplate({
+			...ctx,
+			...template?.buildEnv ? { buildEnv: template.buildEnv } : {},
+			cpuCount: settings.cpuCount ?? defaults?.cpuCount ?? DEFAULT_SETTINGS.cpuCount,
+			memoryMB: settings.memoryMb ?? defaults?.memoryMb ?? DEFAULT_SETTINGS.memoryMb
+		});
+	}
+	create(ctx, settings) {
+		const { defaults, template: _template, ...options } = this.#options;
+		return new PlatformSandbox({
+			...options,
+			id: ctx.sessionId,
+			sessionId: ctx.sessionId,
+			sandboxId: ctx.sandboxId,
+			template: this.template(ctx, settings),
+			...ctx.workingDirectory ? { workingDirectory: ctx.workingDirectory } : {},
+			idleTimeoutMinutes: settings.idleTimeoutMinutes ?? defaults?.idleTimeoutMinutes ?? options.idleTimeoutMinutes ?? DEFAULT_SETTINGS.idleTimeoutMinutes
+		});
+	}
+	async #startBuild(ctx, settings) {
+		const builder = await this.#resolveBuilder(ctx, settings);
+		const result = await builder.build(this.#buildOptions());
+		this.#builders.set(result.templateId, builder);
+		return {
+			buildId: result.templateId,
+			templateId: result.templateId,
+			status: mapStatus(result.status)
+		};
+	}
+	async #getBuild(_ctx, _settings, buildId) {
+		const builder = this.#builders.get(buildId);
+		if (!builder) return {
+			buildId,
+			status: "unknown",
+			error: `Build ${buildId} was not started by this process; its status cannot be read.`
+		};
+		return toBuild(await builder.build(this.#buildOptions()));
+	}
+	async #resolveBuilder(ctx, settings) {
+		const builder = await this.template(ctx, settings)?.();
+		if (!builder) throw new Error("PlatformFactorySandbox.builds: the session context yields no template to build");
+		return builder;
+	}
+	#buildOptions() {
+		const { defaults: _defaults, template: _template, env: _env, ...options } = this.#options;
+		return options;
+	}
+};
+function mapStatus(status) {
+	return status;
+}
+function toBuild(result) {
+	return {
+		buildId: result.templateId,
+		templateId: result.templateId,
+		status: mapStatus(result.status),
+		...result.error ? { error: result.error } : {}
+	};
+}
+//#endregion
 //#region src/address-registry.ts
 /**
 * Concrete in-process {@link SandboxAddressRegistry}. Backed by a `Map`; no
@@ -2510,6 +2677,7 @@ var InProcessSandboxAddressRegistry = class {
 exports.InProcessSandboxAddressRegistry = InProcessSandboxAddressRegistry;
 exports.PlatformApiError = PlatformApiError;
 exports.PlatformClient = PlatformClient;
+exports.PlatformFactorySandbox = PlatformFactorySandbox;
 exports.PlatformFilesystem = PlatformFilesystem;
 exports.PlatformSandbox = PlatformSandbox;
 exports.PrivateNetExecHttpError = PrivateNetExecHttpError;