@mastra/platform-workspace 1.5.0-alpha.4 → 1.5.0-alpha.6

package/README.md

@@ -1,6 +1,6 @@
 # @mastra/platform-workspace
 
-Mastra Platform workspace provider. Gives agents environment-scoped sandbox execution and bucket-backed filesystem access through the Mastra Platform workspace proxy.
+Mastra Platform workspace provider. It gives agents environment-scoped sandbox execution and bucket-backed filesystem access through the Mastra Platform workspace proxy.
 
 ## Installation
 
@@ -8,23 +8,6 @@ Mastra Platform workspace provider. Gives agents environment-scoped sandbox exec
 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)     |
-| `bucketName`      | `MASTRA_PLATFORM_BUCKET_NAME`  | Yes (filesystem) |
-
-The sandbox provider resolves from the explicit `sandboxProvider` option, then `SANDBOX_PROVIDER`, then defaults to `e2b`. Set either option to `railway` to use Railway sandboxes. The proxy URL defaults to `https://workspaces.mastra.ai` and can be overridden with the `MASTRA_WORKSPACE_PROXY_URL` env var (useful for staging).
-
-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
@@ -33,11 +16,8 @@ import { Workspace } from '@mastra/core/workspace';
 import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace';
 
 const workspace = new Workspace({
-  filesystem: new PlatformFilesystem({
-    // accessToken, projectId, bucketName all fall back to env
-  }),
+  filesystem: new PlatformFilesystem({}),
   sandbox: new PlatformSandbox({
-    // accessToken, projectId, environmentId all fall back to env
     idleTimeoutMinutes: 30,
     networkIsolation: 'ISOLATED',
   }),
@@ -50,98 +30,24 @@ const agent = new Agent({
 });
 ```
 
-## Filesystem
-
-`PlatformFilesystem` implements the Mastra filesystem interface against a workspace bucket. Object keys are percent-encoded per segment, so filenames with `?`, `#`, `%`, `&`, `+`, or spaces are preserved end-to-end.
-
-```typescript
-const fs = new PlatformFilesystem({ bucketName: 'reports' });
-
-await fs.writeFile('/analyses/repo.md', markdown);
-const content = await fs.readFile('/analyses/repo.md');
-const entries = await fs.readdir('/analyses');
-await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md');
-```
-
-Pass `readOnly: true` to mount the bucket read-only. Mutating calls will throw `WorkspaceReadOnlyError`.
-
-## Sandbox
-
-`PlatformSandbox` executes commands inside a provider-backed sandbox tied to a Platform environment. Sessions boot from the configured provider template or checkpoint.
-
-```typescript
-const sandbox = new PlatformSandbox({ environmentId: 'env_abc' });
-
-const result = await sandbox.executeCommand('python', ['analyze.py'], {
-  timeout: 30_000,
-  env: { INPUT: 'repo' },
-});
-
-console.log(result.stdout);
-```
-
-Pass an existing `sandboxId` to reattach to a live sandbox instead of creating a new one.
+## Documentation
 
-### Reusable templates
+Both providers authenticate through the workspace proxy with `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`. `PlatformSandbox` also requires `MASTRA_ENVIRONMENT_ID`; `PlatformFilesystem` requires `MASTRA_PLATFORM_BUCKET_NAME`. Constructor values override environment variables, and `MASTRA_WORKSPACE_PROXY_URL` can point requests at a non-production proxy.
 
-Use `Template()` to prebuild a public repository at an immutable commit. `PlatformSandbox` sends the serialized definition to Platform, which content-addresses it and starts or reuses the provider build. Sandbox creation doesn't wait for the build. Platform boots from a prior template in the same family with matching resources when available, otherwise from the provider default, while the requested template builds in the background:
+`PlatformFilesystem` implements the Mastra filesystem interface against a Platform bucket. It supports reading, writing, listing, moving, and deleting files, preserves reserved characters in object names, and can be mounted with `readOnly: true` to reject mutations.
 
-```typescript
-import { PlatformSandbox, Template } from '@mastra/platform-workspace';
-
-const commitSha = process.env.REPOSITORY_COMMIT_SHA!;
-const template = Template()
-  .cpuCount(4)
-  .memoryMB(8_192)
-  .setWorkdir('/workspace/repo')
-  .setEnvs({ BUILD_CONFIG_MARKER: 'template-v1' })
-  .aptInstall(['git', 'jq'])
-  .runCmd('git clone https://github.com/mastra-ai/mastra.git /workspace/repo')
-  .runCmd(`git checkout ${commitSha}`)
-  .runCmd('pnpm install --frozen-lockfile');
-
-const sandbox = new PlatformSandbox({
-  environmentId: 'env_abc',
-  sandboxProvider: 'e2b',
-  template,
-});
-await sandbox.start();
-```
-
-Platform serializes the builder and stores build state under a server-derived content hash within the selected environment and provider. Passing the same definition to another sandbox reuses that build. Call `await template.build(options)` to start or reuse the provider build without provisioning a sandbox; it returns `ready`, `pending`, or `failed`. For E2B templates, `cpuCount()` and `memoryMB()` set the resources inherited by sandboxes created from the exact build or a resource-matched stale build. They default to 2 CPUs and 1,024 MB. Effective resource values participate in the template identity, so changing either value creates a distinct template while explicit defaults reuse the omitted-default build. If a pending build falls back to the provider base, that sandbox may use provider-default resources; check `templatePending` to detect this case. Railway currently ignores these two methods because its sandbox template API doesn't expose matching resource settings.
-
-By default, operation arguments are serialized and sent to Platform. Use `setEnvs(values, { ephemeral: true })` for short-lived build credentials: these values are sent separately, excluded from content identity and persistence, unavailable at runtime, and take precedence over serialized values with the same key. Supply them on every build or fresh provision that may need to build. Railway's provider cache includes transient build variables, so rotating a value may trigger another provider build even though the Platform template ID stays stable.
-
-## Errors
+`PlatformSandbox` starts or reconnects to an environment-scoped provider sandbox and implements command execution, lifecycle, and networking operations. The provider defaults to E2B and can be changed to Railway through `sandboxProvider` or `SANDBOX_PROVIDER`. Pass an existing `sandboxId` to reattach to a live sandbox, and `actingUserId` to partition and attribute project-token requests to a stable application user.
 
-Failures from the proxy raise `PlatformApiError`. Structured `{ error: { message, type } }` payloads from the proxy are parsed into `.code` (machine kind) and `.proxyMessage` (human string); the raw response body stays available on `.body`:
-
-```typescript
-import { PlatformApiError } from '@mastra/platform-workspace';
-
-try {
-  await fs.readFile('/missing.txt');
-} catch (err) {
-  if (err instanceof PlatformApiError) {
-    if (err.code === 'not_found') {
-      // handle missing file
-    } else if (err.code === 'authentication_error') {
-      // refresh token
-    }
-    console.error(err.status, err.code, err.proxyMessage, err.body);
-  }
-}
-```
+The exported `Template()` builder creates reusable sandbox images from commands, packages, environment values, repository checkouts, CPU, memory, and working-directory settings. Platform derives a content identity from the serialized template so matching definitions can reuse previous builds. Ephemeral environment values are excluded from that identity and are not persisted into the runtime image.
 
-`code` / `proxyMessage` are `undefined` when the proxy returns a non-JSON body (e.g. an HTML 502 from a load balancer).
+Proxy failures throw `PlatformApiError`, which includes the HTTP status, parsed machine-readable error code, proxy message, and raw response body. Use these fields to distinguish missing resources, authentication failures, and provider errors.
 
-Filesystem-specific errors (`FileNotFoundError`, `FileExistsError`, `WorkspaceReadOnlyError`) are re-exported from `@mastra/core`.
+- [Mastra Platform workspaces](https://mastra.ai/docs/mastra-platform/workspaces)
 
-### Sandbox exec errors
+## Changelog
 
-`PlatformSandbox.executeCommand` runs over the direct-exec data plane (a WebSocket straight to the Railway tcp-proxy) and can throw two typed errors on unrecoverable failure:
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/workspaces/platform-workspace/CHANGELOG.md) for version history and release notes.
 
-- `SandboxDestroyedError` — the platform returned 410 for `/exec-lease`, meaning the sandbox has been destroyed. The cached sandbox id and lease are cleared, so a reused `PlatformSandbox` instance will re-provision on the next call. Fleet-level code that owns a binding store should catch this, clear the stale sandbox id, and reprovision + replay.
-- `SandboxExecTransportError` — both the initial WebSocket attempt and the built-in retry closed without an `exit` frame against a live sandbox. Carries `{ opened, closeCode, closeReason, wsEndpoint }` diagnostics plus `sandboxId`, `command`, and `attempts` so upstream logs / alerts can distinguish "the Railway data plane is broken" from "your command failed".
+## Support
 
-`PlatformApiError` (with status 404 / 500 / 501 on `/exec-lease`) can also bubble up from `executeCommand` — those are configuration or platform errors, not "reprovision me" signals, and are propagated as-is.
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/dist/index.cjs

@@ -1047,9 +1047,9 @@ var SandboxDestroyedError = class extends Error {
 * sandbox.
 */
 function buildCommand(command, args) {
-	return args?.length ? `${command} ${args.map(shellQuote).join(" ")}` : command;
+	return args?.length ? `${command} ${args.map(shellQuote$1).join(" ")}` : command;
 }
-function shellQuote(arg) {
+function shellQuote$1(arg) {
 	if (/^[a-zA-Z0-9._\-/=:@]+$/.test(arg)) return arg;
 	return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
@@ -1519,14 +1519,15 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* sandbox they can't safely retry.
 	*
 	* Railway requires a caller-supplied recovery `id` before it can have a
-	* checkpoint to delete. E2B also permits capture with the automatic id, so
-	* destroy releases that named snapshot even when no recovery id was supplied.
+	* checkpoint to delete. On E2B the sandbox itself is the persistent thing
+	* (idle sandboxes pause and resume in place), so destroy only kills the
+	* VM; any snapshot a caller captured on purpose is the caller's to manage.
 	*/
 	async destroy() {
 		if (!this._sandboxId) return;
 		const destroyedSandboxId = this._sandboxId;
 		this._captureInFlight = null;
-		if (this._hasRecoveryKey || this._client.sandboxProvider === "e2b") try {
+		if (this._hasRecoveryKey && this._client.sandboxProvider !== "e2b") try {
 			await this._request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
 				method: "DELETE",
 				headers: { "content-type": "application/json" },
@@ -1989,6 +1990,16 @@ function setupMarkerContent(setupCommand) {
 function setupMarkerCommand(content) {
 	return `mkdir -p "$(dirname "${SETUP_MARKER_PATH}")" && printf '%s' '${content}' > "${SETUP_MARKER_PATH}"`;
 }
+function repoCloneCommand({ cloneUrl, destination, branch, tokenEnv }) {
+	return `git ${tokenEnv ? `${gitAuthFlag$1(tokenEnv)} ` : ""}clone --depth=1 --single-branch ${branch ? `--branch ${shellQuote(branch)} ` : ""}${shellQuote(cloneUrl)} ${shellQuote(destination)}`;
+}
+/** Per-invocation auth header; `-c` config never reaches `.git/config`. */
+function gitAuthFlag$1(tokenEnv) {
+	return `-c http.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$${tokenEnv}" | base64 -w0)"`;
+}
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 //#endregion
 //#region src/repo-template.ts
 const execFileAsync = (0, util.promisify)(child_process.execFile);
@@ -2070,7 +2081,11 @@ function createRepoTemplate(options) {
 		if (Object.keys(buildEnv).length > 0) template = template.setEnvs(buildEnv, { ephemeral: true });
 		template = withResources(template, options);
 		if (workingDirectory) template = template.runCmd(`mkdir -p "${workingDirectory}"`).setWorkdir(workingDirectory);
-		template = template.runCmd(`git ${auth}clone ${cloneUrl} "${repoDir}"`).runCmd(`git -C "${repoDir}" ${auth}fetch origin ${sha}`).runCmd(`git -C "${repoDir}" checkout ${sha}`);
+		template = template.runCmd(repoCloneCommand({
+			cloneUrl,
+			destination: repoDir,
+			...token ? { tokenEnv: BUILD_TOKEN_ENV } : {}
+		})).runCmd(`git -C "${repoDir}" ${auth}fetch origin ${sha}`).runCmd(`git -C "${repoDir}" checkout ${sha}`);
 		for (const command of setupCommands) template = template.runCmd(`cd "${repoDir}" && ${command}`);
 		template = template.runCmd(setupMarkerCommand(setupMarkerContent(setupCommands)));
 		return template.withFamily(family);