@mastra/platform-workspace 1.2.0-alpha.1 → 1.2.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @mastra/platform
 
+## 1.2.0-alpha.2
+
+### Minor Changes
+
+- Added startup observability to `PlatformSandbox`. New optional `sessionId` and `threadId` options let you correlate all sandbox startup activity with the session that triggered it, and the sandbox now logs how long startup took and whether it became reachable. ([#21189](https://github.com/mastra-ai/mastra/pull/21189))
+
+  ```ts
+  import { PlatformSandbox } from '@mastra/platform-workspace';
+
+  const sandbox = new PlatformSandbox({
+    projectId: 'proj_123',
+    environmentId: 'env_123',
+    sessionId: 'session_abc', // correlate startup logs with your session
+    threadId: 'thread_xyz', // optional finer-grained correlation
+  });
+  ```
+
+- Added `PlatformSandbox.snapshot()` to capture the configured recovery checkpoint. ([#21221](https://github.com/mastra-ai/mastra/pull/21221))
+
+  ```ts
+  await sandbox.snapshot();
+  ```
+
+### Patch Changes
+
+- Fixed Platform Sandbox startup so commands use a reliable connection while a new sandbox is starting. ([#21028](https://github.com/mastra-ai/mastra/pull/21028))
+
+- Updated dependencies [[`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`d6c56f9`](https://github.com/mastra-ai/mastra/commit/d6c56f951db3213330b98b0abafa9778c8770e58), [`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`acc3513`](https://github.com/mastra-ai/mastra/commit/acc3513b19f79bf0a7ec2998694580edca54086c), [`94e7ae9`](https://github.com/mastra-ai/mastra/commit/94e7ae970b37c888cd1244ef013292639a2fe6d1), [`6a667b4`](https://github.com/mastra-ai/mastra/commit/6a667b4b7cd6a93fe41fcdd357b08c5a8c09b9ab), [`2440e09`](https://github.com/mastra-ai/mastra/commit/2440e096ea6c2def1ccc1eb2d0f3f5b88c4af940), [`a59049b`](https://github.com/mastra-ai/mastra/commit/a59049b1652a13efff66ac826326b5ed9a550342)]:
+  - @mastra/core@1.58.0-alpha.13
+
 ## 1.2.0-alpha.1
 
 ### Minor Changes

package/dist/client.d.ts

@@ -1,6 +1,19 @@
 export interface PlatformClientOptions {
     accessToken?: string;
     projectId?: string;
+    /**
+     * Advisory correlation id for the factory session driving this client.
+     * Sent as `x-mastra-session-id` on every proxy request so proxy-side logs
+     * can be joined back to the calling session without a multi-store hand-join
+     * (`threadId → sessionId → sandboxId → providerResourceId`). Never used for
+     * authorization — the Bearer token remains the only credential.
+     */
+    sessionId?: string;
+    /**
+     * Advisory correlation id for the factory thread, sent as
+     * `x-mastra-thread-id` when present. See {@link PlatformClientOptions.sessionId}.
+     */
+    threadId?: string;
     fetch?: typeof fetch;
 }
 export interface PlatformRequestOptions extends RequestInit {
@@ -11,6 +24,8 @@ export declare function resolvePlatformOptions(options: PlatformClientOptions):
     accessToken: string;
     projectId: string;
     proxyUrl: string;
+    sessionId: string | undefined;
+    threadId: string | undefined;
     fetch: typeof fetch;
 };
 /**
@@ -37,6 +52,10 @@ export declare class PlatformClient {
     readonly accessToken: string;
     readonly projectId: string;
     readonly proxyUrl: string;
+    /** Advisory session correlation id — see {@link PlatformClientOptions.sessionId}. */
+    readonly sessionId: string | undefined;
+    /** Advisory thread correlation id — see {@link PlatformClientOptions.threadId}. */
+    readonly threadId: string | undefined;
     readonly fetch: typeof fetch;
     constructor(options: PlatformClientOptions);
     request(path: string, options?: PlatformRequestOptions): Promise<Response>;

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,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;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB;;;;;EAOpE;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;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAUzC;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;gBAEjB,OAAO,EAAE,qBAAqB;IAQpC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC;CAoBrF"}
+{"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;;;;;;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;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,qBAAqB;;;;;;;EASpE;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;gBAE9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAUzC;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,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;gBAEjB,OAAO,EAAE,qBAAqB;IAUpC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,QAAQ,CAAC;CA0BrF"}

package/dist/index.cjs

@@ -42,6 +42,8 @@ function resolvePlatformOptions(options) {
 		accessToken: requireOption(options.accessToken ?? process.env.MASTRA_PLATFORM_ACCESS_TOKEN, "accessToken"),
 		projectId: requireOption(options.projectId ?? process.env.MASTRA_PROJECT_ID, "projectId"),
 		proxyUrl: (process.env.MASTRA_WORKSPACE_PROXY_URL ?? DEFAULT_PROXY_URL).replace(/\/$/, ""),
+		sessionId: options.sessionId,
+		threadId: options.threadId,
 		fetch: options.fetch ?? fetch
 	};
 }
@@ -85,12 +87,18 @@ var PlatformClient = class {
 	accessToken;
 	projectId;
 	proxyUrl;
+	/** Advisory session correlation id — see {@link PlatformClientOptions.sessionId}. */
+	sessionId;
+	/** Advisory thread correlation id — see {@link PlatformClientOptions.threadId}. */
+	threadId;
 	fetch;
 	constructor(options) {
 		const resolved = resolvePlatformOptions(options);
 		this.accessToken = resolved.accessToken;
 		this.projectId = resolved.projectId;
 		this.proxyUrl = resolved.proxyUrl;
+		this.sessionId = resolved.sessionId;
+		this.threadId = resolved.threadId;
 		this.fetch = resolved.fetch;
 	}
 	async request(path, options = {}) {
@@ -98,6 +106,8 @@ var PlatformClient = class {
 		for (const [key, value] of Object.entries(options.query ?? {})) if (value !== void 0) url.searchParams.set(key, String(value));
 		const headers = new Headers(options.headers);
 		headers.set("authorization", `Bearer ${this.accessToken}`);
+		if (this.sessionId) headers.set("x-mastra-session-id", this.sessionId);
+		if (this.threadId) headers.set("x-mastra-thread-id", this.threadId);
 		const { query: _query, ...fetchOptions } = options;
 		const signal = fetchOptions.signal ?? AbortSignal.timeout(DEFAULT_REQUEST_TIMEOUT_MS);
 		const response = await this.fetch(url, {
@@ -693,6 +703,24 @@ const CREATE_MAX_ATTEMPTS = 3;
 /** Base delay between create retries; multiplied by the attempt number. */
 const CREATE_RETRY_BASE_DELAY_MS = 2e3;
 /**
+* How long to wait for the in-sandbox sidecar's `/health` endpoint to respond
+* before giving up and leaving the address registry unpopulated (execs fall
+* back to the lease path). This bounds the fire-and-forget probe that runs
+* after `start()` resolves; the sandbox is usable immediately — the probe
+* only controls whether early execs go via private-net or lease.
+*/
+const SIDECAR_PROBE_TIMEOUT_MS = 3e4;
+/** Delay between sidecar probe attempts. */
+const SIDECAR_PROBE_INTERVAL_MS = 250;
+/**
+* How long `executeCommand` waits for the transport to become ready before
+* falling back to the lease path. This is much shorter than
+* `SIDECAR_PROBE_TIMEOUT_MS` because we want execs to proceed quickly if
+* the sidecar is slow to boot — the probe continues in the background and
+* later execs will use private-net once it succeeds.
+*/
+const TRANSPORT_READY_WAIT_MS = 5e3;
+/**
 * 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"
@@ -887,6 +915,22 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* Mirrors OSS `@mastra/railway` `RailwaySandbox._startInFlight`.
 	*/
 	_startInFlight = null;
+	/**
+	* Generation token for the sidecar probe. Incremented on every `start()`
+	* and on teardown. The probe captures this value when it begins; if the
+	* generation has changed by the time the probe succeeds, the probe skips
+	* the `set()` to avoid re-populating a deleted or superseded sandbox entry.
+	*/
+	_probeGeneration = 0;
+	/**
+	* In-flight sidecar probe promise. Concurrent `executeCommand` callers that
+	* arrive before the registry is populated all await this single promise so
+	* we don't fire N independent lease requests during the sidecar boot window.
+	* Once the probe resolves (success or timeout), callers check the registry
+	* and proceed — either via private-net (probe succeeded) or via lease (probe
+	* failed/timed out, but now coalesced via `_leaseInFlight`).
+	*/
+	_transportReadyPromise = null;
 	constructor(options = {}) {
 		super({
 			...options,
@@ -929,6 +973,8 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			...id !== void 0 && { id },
 			accessToken: this._client.accessToken,
 			projectId: this._client.projectId,
+			...this._client.sessionId !== void 0 && { sessionId: this._client.sessionId },
+			...this._client.threadId !== void 0 && { threadId: this._client.threadId },
 			fetch: this._client.fetch,
 			environmentId: this._environmentId,
 			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
@@ -958,11 +1004,16 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	* awaiter.
 	*/
 	async _doStart() {
+		const startedAt = Date.now();
 		if (this._sandboxId) try {
-			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
+			const requestStartedAt = Date.now();
+			const response = await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`);
+			const requestMs = Date.now() - requestStartedAt;
+			const json = await response.json();
 			if (!json.destroyedAt) {
 				this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
 				this._populateAddressFromResponse(json);
+				this._logStartComplete(json.id, startedAt, requestMs, "reattach");
 				return;
 			}
 			this._sandboxId = void 0;
@@ -979,6 +1030,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			env: this._env
 		});
 		let response;
+		const requestStartedAt = Date.now();
 		for (let attempt = 1;; attempt++) try {
 			response = await this._client.request("/sandbox", {
 				method: "POST",
@@ -990,10 +1042,32 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 			if (!(error instanceof PlatformApiError && error.status >= 500) || attempt >= CREATE_MAX_ATTEMPTS) throw error;
 			await new Promise((resolve) => setTimeout(resolve, CREATE_RETRY_BASE_DELAY_MS * attempt));
 		}
+		const requestMs = Date.now() - requestStartedAt;
 		const json = await response.json();
 		this._sandboxId = json.id;
 		this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
 		this._populateAddressFromResponse(json);
+		this._logStartComplete(json.id, startedAt, requestMs, "provision");
+	}
+	/**
+	* One timing summary per completed `start()` — the whole
+	* `PlatformSandbox`-visible boot in a single greppable line.
+	*
+	* `requestMs` is the proxy round-trip (`GET /sandbox/:id` on reattach,
+	* `POST /sandbox` including transient-5xx retries on provision) — a black
+	* box from this side that rolls up Railway RPC, sidecar launch, and the
+	* proxy's discovery exec. Sidecar probe cost is intentionally NOT here: the
+	* probe is fire-and-forget and outlives `start()` by design, so its
+	* duration lands on the `platform-workspace probe ok` line instead.
+	*/
+	_logStartComplete(sandboxId, startedAt, requestMs, mode) {
+		this.logger.info("platform-workspace start complete", {
+			sandboxId,
+			sessionId: this._client.sessionId,
+			mode,
+			totalMs: Date.now() - startedAt,
+			requestMs
+		});
 	}
 	/**
 	* Copy `response.instanceUrl` into the injected {@link SandboxAddressRegistry}
@@ -1014,7 +1088,74 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	_populateAddressFromResponse(json) {
 		if (!this._addressRegistry) return;
 		if (!json.instanceUrl) return;
-		this._addressRegistry.set(json.id, json.instanceUrl);
+		this._addressRegistry.delete(json.id);
+		const generation = ++this._probeGeneration;
+		this._transportReadyPromise = this._probeSidecarThenRegister(json.id, json.instanceUrl, generation);
+	}
+	/**
+	* Fire-and-forget probe that polls the sidecar's `/health` endpoint until
+	* it responds, then populates the address registry. Runs detached from
+	* `start()` so sandbox provision latency is unchanged; early execs simply
+	* fall back to the lease path until the probe succeeds.
+	*
+	* If the sidecar never comes up within {@link SIDECAR_PROBE_TIMEOUT_MS},
+	* the registry stays unpopulated and all execs go via lease for this
+	* sandbox's lifetime (or until a future `start()` re-runs the probe).
+	*
+	* @param generation - The probe generation captured at call time. If this
+	*   no longer matches `_probeGeneration` when the probe succeeds, the probe
+	*   was superseded by a teardown or a new `start()`, so we skip the `set()`.
+	*/
+	async _probeSidecarThenRegister(sandboxId, instanceUrl, generation) {
+		const probeStartedAt = Date.now();
+		const deadline = probeStartedAt + SIDECAR_PROBE_TIMEOUT_MS;
+		const fetchFn = this._privateNetFetch ?? fetch;
+		let attempts = 0;
+		while (Date.now() < deadline) {
+			if (generation !== this._probeGeneration) return;
+			attempts++;
+			try {
+				const res = await fetchFn(`${instanceUrl}/health`, {
+					method: "GET",
+					signal: AbortSignal.timeout(1e3)
+				});
+				const ok = res.ok;
+				await res.body?.cancel().catch(() => {});
+				if (ok) {
+					this.logger.info("platform-workspace probe ok", {
+						sandboxId,
+						sessionId: this._client.sessionId,
+						probeDurationMs: Date.now() - probeStartedAt,
+						attempts
+					});
+					if (generation === this._probeGeneration && this._sandboxId === sandboxId) this._addressRegistry?.set(sandboxId, instanceUrl);
+					return;
+				}
+			} catch {}
+			await new Promise((r) => setTimeout(r, SIDECAR_PROBE_INTERVAL_MS));
+		}
+		this.logger.warn("platform-workspace probe timed out", {
+			sandboxId,
+			sessionId: this._client.sessionId,
+			timeoutMs: SIDECAR_PROBE_TIMEOUT_MS,
+			attempts
+		});
+	}
+	/**
+	* Wait for the transport to become ready (sidecar probe succeeds) or time
+	* out. Concurrent callers all await the same probe promise, coalescing the
+	* cold-start storm into a single warmup attempt.
+	*
+	* If no probe is in flight (no registry, or registry already populated),
+	* this returns immediately. After the wait (success or timeout), callers
+	* check the registry and proceed — either via private-net or lease. The
+	* lease path is still coalesced via `_leaseInFlight`, so even if the probe
+	* times out, we only mint one lease for all concurrent execs.
+	*/
+	async _awaitTransportReady() {
+		if (this._sandboxId && this._addressRegistry?.get(this._sandboxId)) return;
+		if (!this._transportReadyPromise) return;
+		await Promise.race([this._transportReadyPromise, new Promise((r) => setTimeout(r, TRANSPORT_READY_WAIT_MS))]);
 	}
 	/**
 	* Stop the sandbox while **preserving its recovery checkpoint**.
@@ -1079,12 +1220,17 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 	async _teardownSandbox() {
 		if (!this._sandboxId) return;
 		const destroyedSandboxId = this._sandboxId;
+		this._probeGeneration++;
 		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
 		this._lease = null;
 		this._addressRegistry?.delete(destroyedSandboxId);
 	}
+	/** Persist the configured recovery checkpoint when available. */
+	async snapshot() {
+		await this.captureCheckpoint();
+	}
 	/**
 	* Capture the sandbox's checkpoint on demand, outside any refresh timer the
 	* workspace-proxy owns internally.
@@ -1233,6 +1379,7 @@ var PlatformSandbox = class PlatformSandbox extends _mastra_core_workspace.Mastr
 		const started = Date.now();
 		const fullCommand = buildCommand(command, args);
 		const effectiveTimeout = options?.timeout ?? this._timeout;
+		await this._awaitTransportReady();
 		const instanceUrl = this._addressRegistry?.get(this._sandboxId);
 		if (instanceUrl) {
 			const privateNet = await this._tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options);