@mastra/platform-workspace 1.5.0 → 1.6.0-alpha.1

package/README.md

@@ -8,6 +8,23 @@ Mastra Platform workspace provider. It gives agents environment-scoped sandbox e
 npm install @mastra/platform-workspace
 ```
 
+## Configuration
+
+All options can be passed to the constructor or read from environment variables:
+
+| Option            | Env var                        | Required                        |
+| ----------------- | ------------------------------ | ------------------------------- |
+| `accessToken`     | `MASTRA_PLATFORM_ACCESS_TOKEN` | Yes                             |
+| `projectId`       | `MASTRA_PROJECT_ID`            | Yes                             |
+| `environmentId`   | `MASTRA_ENVIRONMENT_ID`        | Yes (sandbox)                   |
+| `actingUserId`    | —                              | No (sandbox)                    |
+| `sandboxProvider` | `SANDBOX_PROVIDER`             | No (sandbox, defaults to `e2b`) |
+| `bucketName`      | `MASTRA_PLATFORM_BUCKET_NAME`  | Yes (filesystem)                |
+
+The proxy URL defaults to `https://workspaces.mastra.ai`. Set `MASTRA_PLATFORM_REGION` to `us` or `eu` (case-insensitive) to route to the regional replica at `https://workspaces.us.mastra.ai` or `https://workspaces.eu.mastra.ai`. An explicit `MASTRA_WORKSPACE_PROXY_URL` (useful for staging) overrides both.
+
+Requests to the proxy are authenticated with `Authorization: Bearer <accessToken>`. For sandbox requests authenticated with a project access token, set `actingUserId` to the stable opaque user subject from your authentication system. It is sent as `x-acting-user-id` for token partitioning and attribution; it is not an authorization claim.
+
 ## Usage
 
 ```typescript

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAC/D;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,KAAK,CAAC;AAWhD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAUD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB;IAKjE,WAAW;IACX,SAAS;IACT,YAAY;IACZ,QAAQ;IACR,eAAe;IACf,SAAS;IACT,QAAQ;IACR,KAAK;EAER;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2HAA2H;IAC3H,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,yGAAyG;IACzG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C,YAAY,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EASvC;CACF;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAE7B,YAAY,OAAO,EAAE,qBAAqB,EAUzC;IAEK,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEnF;IAEK,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE3F;YAEa,aAAa;CA2B5B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CAC/D;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,KAAK,CAAC;AA6BhD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAUD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB;IAKjE,WAAW;IACX,SAAS;IACT,YAAY;IACZ,QAAQ;IACR,eAAe;IACf,SAAS;IACT,QAAQ;IACR,KAAK;EAER;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2HAA2H;IAC3H,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,yGAAyG;IACzG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAE1C,YAAY,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EASvC;CACF;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAE7B,YAAY,OAAO,EAAE,qBAAqB,EAUzC;IAEK,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEnF;IAEK,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAE3F;YAEa,aAAa;CA2B5B"}

package/dist/index.cjs

@@ -31,6 +31,23 @@ let util = require("util");
 let crypto = require("crypto");
 //#region src/client.ts
 const DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
+const REGIONAL_PROXY_URLS = {
+	us: "https://workspaces.us.mastra.ai",
+	eu: "https://workspaces.eu.mastra.ai"
+};
+/**
+* Resolves the workspace proxy URL, preferring an explicit
+* `MASTRA_WORKSPACE_PROXY_URL` override, then a regional replica selected by
+* `MASTRA_PLATFORM_REGION` (case-insensitive `us` or `eu`), then the global
+* default. Unknown region values fall through to the global default.
+*/
+function resolveProxyUrl() {
+	const override = process.env.MASTRA_WORKSPACE_PROXY_URL?.trim();
+	if (override) return override;
+	const region = process.env.MASTRA_PLATFORM_REGION?.trim().toLowerCase();
+	if (region === "us" || region === "eu") return REGIONAL_PROXY_URLS[region];
+	return DEFAULT_PROXY_URL;
+}
 /**
 * Default per-request timeout for calls to the workspace proxy. Applied only
 * when the caller doesn't already pass an `AbortSignal`. Long-running routes
@@ -53,7 +70,7 @@ function resolvePlatformOptions(options) {
 		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
 		projectId: requireOption(options.projectId ?? process.env.MASTRA_PROJECT_ID, "projectId"),
 		actingUserId: options.actingUserId?.trim() || void 0,
-		proxyUrl: (process.env.MASTRA_WORKSPACE_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/$/, ""),
+		proxyUrl: resolveProxyUrl().replace(/\/$/, ""),
 		sandboxProvider: resolveSandboxProvider(configuredSandboxProvider),
 		sessionId: options.sessionId,
 		threadId: options.threadId,
@@ -2015,6 +2032,14 @@ const BUILD_TOKEN_ENV = "MASTRA_REPOSITORY_ACCESS_TOKEN";
 const CLONE_URL_ALLOWED_CHARS = /^[a-z0-9:/._-]+$/i;
 const CLONE_URL_HOST_PATTERN = /^[a-z0-9.-]+$/i;
 const CLONE_URL_SEGMENT_PATTERN = /^[\w.-]+$/;
+/** Last default-branch head resolved per clone URL, shared across resolvers in this process. */
+const lastKnownHeads = /* @__PURE__ */ new Map();
+const MAX_LAST_KNOWN_HEADS = 1e3;
+function rememberHead(cloneUrl, sha) {
+	lastKnownHeads.delete(cloneUrl);
+	lastKnownHeads.set(cloneUrl, sha);
+	if (lastKnownHeads.size > MAX_LAST_KNOWN_HEADS) lastKnownHeads.delete(lastKnownHeads.keys().next().value);
+}
 /**
 * Create a lazy repository template definition for PlatformSandbox, mirroring
 * `@mastra/e2b`'s `createRepoTemplate`: pass the sandbox context through and a
@@ -2025,8 +2050,10 @@ const CLONE_URL_SEGMENT_PATTERN = /^[\w.-]+$/;
 * what gets cloned and what the template is identified by can't drift — and
 * pins repositories to their current default-branch commit. Private repository
 * credentials are used for head resolution and sent to the provider as
-* transient build envs; they never enter the serialized definition. If the
-* repository or its head cannot be resolved, the resolver keeps `cpuCount` and
+* transient build envs; they never enter the serialized definition. A failed
+* head lookup reuses the last head resolved for the same clone URL in this
+* process. If the repository cannot be resolved, or no head has been resolved
+* yet, the resolver keeps `cpuCount` and
 * `memoryMB` in a resources-only template so the sandbox still boots at the
 * requested size, and the caller's runtime setup materializes the checkout.
 */
@@ -2057,16 +2084,30 @@ function createRepoTemplate(options) {
 		}
 		const token = access.authorization?.token;
 		let headError;
-		const sha = await (token ? resolveHead(cloneUrl, token) : resolveHead(cloneUrl)).catch((error) => {
+		const resolved = await (token ? resolveHead(cloneUrl, token) : resolveHead(cloneUrl)).catch((error) => {
 			headError = error;
 		});
-		if (!sha || !SHA_PATTERN.test(sha)) {
-			console.warn("[platform-workspace] repo template skipped: could not resolve default-branch head", {
+		let sha;
+		if (resolved && SHA_PATTERN.test(resolved)) {
+			sha = resolved;
+			rememberHead(cloneUrl, sha);
+		} else {
+			const lastKnown = lastKnownHeads.get(cloneUrl);
+			if (!lastKnown) {
+				console.warn("[platform-workspace] repo template skipped: could not resolve default-branch head", {
+					cloneUrl,
+					sha: resolved,
+					error: redactSecrets(headError)
+				});
+				return resourcesOnly();
+			}
+			console.warn("[platform-workspace] repo template pinned to the last known default-branch head", {
 				cloneUrl,
-				sha,
+				sha: lastKnown,
+				resolved,
 				error: redactSecrets(headError)
 			});
-			return resourcesOnly();
+			sha = lastKnown;
 		}
 		const workingDirectory = options.workingDirectory === void 0 ? void 0 : trimTrailingSlashes(assertWorkingDirectory(options.workingDirectory));
 		const repoDir = repoDirName(cloneUrl);