@mastra/platform-workspace 1.5.0-alpha.3 → 1.5.0-alpha.5

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

@@ -28,6 +28,7 @@ let _mastra_core_workspace = require("@mastra/core/workspace");
 let e2b = require("e2b");
 let child_process = require("child_process");
 let util = require("util");
+let crypto = require("crypto");
 //#region src/client.ts
 const DEFAULT_PROXY_URL = "https://workspaces.mastra.ai";
 /**
@@ -1964,6 +1965,31 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	}
 };
 //#endregion
+//#region ../../packages/_internals/workspace/dist/index.js
+/**
+* Setup completion marker shared by repo templates and their consumers.
+*
+* A repo template writes this file beside the checkout as its last build
+* step, so it exists only in images where every setup command succeeded. Its
+* content is a digest of the setup commands the image ran, letting a sandbox
+* booted from the image tell whether the setup it is about to run already
+* happened. Relative to the template's build cwd, which is also the runtime
+* working directory the repo was cloned into.
+*/
+const SETUP_MARKER_PATH = ".mastra-sandbox/setup";
+/** Blank entries never become build steps, so they never count toward the digest either. */
+function normalizeSetupCommands(setupCommand) {
+	return (setupCommand === void 0 ? [] : Array.isArray(setupCommand) ? setupCommand : [setupCommand]).filter((command) => command.trim() !== "");
+}
+/** The marker content for a setup command list: `sha256:<hex>` over the commands joined by newlines. */
+function setupMarkerContent(setupCommand) {
+	return `sha256:${(0, crypto.createHash)("sha256").update(normalizeSetupCommands(setupCommand).join("\n")).digest("hex")}`;
+}
+/** Shell step that writes the marker relative to the cwd. `content` is a digest, so it is shell-safe. */
+function setupMarkerCommand(content) {
+	return `mkdir -p "$(dirname "${SETUP_MARKER_PATH}")" && printf '%s' '${content}' > "${SETUP_MARKER_PATH}"`;
+}
+//#endregion
 //#region src/repo-template.ts
 const execFileAsync = (0, util.promisify)(child_process.execFile);
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
@@ -2046,6 +2072,7 @@ function createRepoTemplate(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}`);
 		for (const command of setupCommands) template = template.runCmd(`cd "${repoDir}" && ${command}`);
+		template = template.runCmd(setupMarkerCommand(setupMarkerContent(setupCommands)));
 		return template.withFamily(family);
 	};
 }