@mastra/platform-workspace 0.2.3 → 0.3.0-alpha.1

package/dist/sandbox.d.ts

@@ -21,6 +21,55 @@ export interface PlatformSandboxOptions extends Omit<MastraSandboxOptions, 'proc
      */
     webSocketFactory?: DirectExecWebSocketFactory;
 }
+/**
+ * Diagnostic error thrown when the direct-exec WebSocket transport fails
+ * twice in a row (opening handshake refused or socket closed mid-stream
+ * without an `exit` frame). Distinguishes "the sandbox transport is broken"
+ * from "your command failed" so callers can decide whether to retry at a
+ * higher level (e.g. reprovision the sandbox) or surface the error.
+ *
+ * `opened` is `true` when the WebSocket completed its handshake at least
+ * once before closing; `false` when Railway refused the upgrade outright.
+ */
+export declare class SandboxExecTransportError extends Error {
+    readonly sandboxId: string | undefined;
+    readonly command: string;
+    readonly attempts: number;
+    readonly opened: boolean;
+    readonly closeCode: number | undefined;
+    readonly closeReason: string | undefined;
+    readonly wsEndpoint: string;
+    constructor(message: string, diagnostics: {
+        sandboxId?: string;
+        command: string;
+        attempts: number;
+        opened: boolean;
+        closeCode?: number;
+        closeReason?: string;
+        wsEndpoint: string;
+    });
+}
+/**
+ * Thrown when `/exec-lease` returns 410 Gone — the sandbox has been destroyed
+ * (Railway destroy, quota reclamation, etc.). The client cannot recover from
+ * this on its own because it does not own the binding store; only the fleet
+ * layer can clear the stale sandbox id and provision a fresh one. Callers
+ * (typically `SandboxFleet`) must catch this and reprovision-and-replay.
+ *
+ * When this is thrown the cached `_lease` and `_sandboxId` on the sandbox
+ * instance are cleared, so the next `ensureRunning()` on a reused instance
+ * will re-provision cleanly.
+ */
+export declare class SandboxDestroyedError extends Error {
+    readonly sandboxId: string | undefined;
+    readonly command: string;
+    readonly attempts: number;
+    constructor(message: string, diagnostics: {
+        sandboxId?: string;
+        command: string;
+        attempts: number;
+    });
+}
 declare class PlatformProcessManager extends SandboxProcessManager<PlatformSandbox> {
     private spawnCounter;
     /**
@@ -63,16 +112,6 @@ export declare class PlatformSandbox extends MastraSandbox {
      * Cleared (regardless of success or failure) when the request settles.
      */
     private _leaseInFlight;
-    /**
-     * Tri-state feature detection for the platform's exec-lease endpoint:
-     *   undefined — not yet tried (default; try direct on first exec)
-     *   true      — endpoint present, use direct exec
-     *   false     — endpoint absent (404/501) OR the WebSocket transport failed
-     *               once; fall back permanently to /exec for this sandbox
-     * Sticky per instance so we make the fallback decision once per sandbox
-     * lifetime instead of paying an extra round-trip on every exec.
-     */
-    private _directExecAvailable;
     constructor(options?: PlatformSandboxOptions);
     private generateId;
     /**
@@ -109,8 +148,28 @@ export declare class PlatformSandbox extends MastraSandbox {
      * execution on the remote sandbox.
      */
     executeCommand(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<CommandResult>;
-    private _tryDirectExec;
-    private _execViaProxy;
+    /**
+     * Run a single exec against the direct-exec transport, with one in-flight
+     * retry on WebSocket transport failure (socket closed without an `exit`
+     * frame and the exec did not time out). The retry mints a fresh lease
+     * — the failure could be a stale JWT — and reopens a new WebSocket.
+     *
+     * Error taxonomy:
+     * - **410 on `/exec-lease`** (either attempt) → the sandbox is gone.
+     *   Nulls the cached `_lease` and `_sandboxId` and throws
+     *   {@link SandboxDestroyedError}. Callers (typically `SandboxFleet`) must
+     *   catch this, clear the stale binding, and reprovision + replay.
+     * - **Persistent transport failure** (both WS attempts close without an
+     *   `exit` frame against a live sandbox) → {@link SandboxExecTransportError}
+     *   with WebSocket close diagnostics.
+     * - **Other `PlatformApiError`s** (404/500/501) propagate directly.
+     * - **Real command result** (exit code from Railway's exit frame, or
+     *   `timedOut: true`) returns normally.
+     *
+     * Returns a result with a real `exitCode` OR `timedOut: true`. Never
+     * returns `{ exitCode: null, timedOut: false }` — that case throws.
+     */
+    private _runDirectExec;
     /**
      * Return a cached exec lease, minting a fresh one when the cache is empty
      * or the JWT is within {@link LEASE_REFRESH_MARGIN_MS} of `expiresAt`.

package/dist/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/platform-workspace",
-  "version": "0.2.3",
+  "version": "0.3.0-alpha.1",
   "description": "Mastra Platform workspace sandbox and filesystem providers",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "vitest": "4.1.10",
     "@internal/lint": "0.0.119",
     "@internal/types-builder": "0.0.94",
-    "@mastra/core": "1.55.0"
+    "@mastra/core": "1.56.0-alpha.3"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.4.0-0 <2.0.0-0"