@mastra/platform-workspace 1.1.1-alpha.0 → 1.2.0-alpha.2

package/dist/index.js

@@ -18,6 +18,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
 	};
 }
@@ -61,12 +63,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 = {}) {
@@ -74,6 +82,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, {
@@ -669,6 +679,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"
@@ -834,12 +862,58 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	* Cleared (regardless of success or failure) when the request settles.
 	*/
 	_leaseInFlight = null;
+	/**
+	* True when this sandbox was constructed with a caller-supplied `id` (the
+	* recovery key the proxy hashes into an on-provider checkpoint name).
+	* `captureCheckpoint()` needs this to distinguish "no checkpoint intent"
+	* (auto-generated random id — capture would land under a name no future
+	* boot would look for) from "capture on demand". Cloned sandboxes route
+	* `checkpointName` through `id`, so both entry points set this the same
+	* way.
+	*/
+	_hasRecoveryKey;
+	/**
+	* In-flight `captureCheckpoint()` request. Concurrent callers on the same
+	* instance coalesce onto this single promise so we don't burn N `POST
+	* /checkpoint` round-trips when the fleet fires several turn-end captures
+	* before the first one resolves. Cleared when the request settles.
+	*/
+	_captureInFlight = null;
+	/**
+	* In-flight `start()` attempt. Concurrent callers on a fresh instance
+	* coalesce onto this single promise so a `POST /sandbox` is not fired
+	* N times when N fleet callers race to bring the same logical sandbox
+	* up. Published **synchronously** with `??=` before the first `await`
+	* so a later caller cannot slip through the null check while the
+	* originator is mid-round-trip. Cleared when the shared attempt
+	* settles (success or failure) so the next call sees a clean slot.
+	*
+	* 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,
 			name: "PlatformSandbox",
 			processes: new PlatformProcessManager()
 		});
+		this._hasRecoveryKey = options.id !== void 0;
 		this.id = options.id ?? this.generateId();
 		this._client = new PlatformClient(options);
 		this._environmentId = options.environmentId ?? process.env.MASTRA_ENVIRONMENT_ID ?? "";
@@ -875,6 +949,8 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			...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 },
@@ -889,11 +965,31 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		});
 	}
 	async start() {
+		this._startInFlight ??= this._doStart().finally(() => {
+			this._startInFlight = null;
+		});
+		return this._startInFlight;
+	}
+	/**
+	* The single `start` attempt behind {@link start}'s coalescing wrapper.
+	*
+	* Split out so the wrapper can install a shared in-flight promise
+	* synchronously (before the first `await`) without inlining the reattach
+	* / retry logic. Joined callers observe whatever outcome this method
+	* produces — success returns normally, failures propagate to every
+	* 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;
@@ -910,6 +1006,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			env: this._env
 		});
 		let response;
+		const requestStartedAt = Date.now();
 		for (let attempt = 1;; attempt++) try {
 			response = await this._client.request("/sandbox", {
 				method: "POST",
@@ -921,10 +1018,32 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			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}
@@ -945,20 +1064,274 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	_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**.
+	*
+	* Semantic parity with `@mastra/railway` `RailwaySandbox.stop()`: the VM
+	* is released but the on-provider checkpoint survives, so a subsequent
+	* `start()` on a sandbox constructed with the same `id` can restore from
+	* it. Any in-flight capture is awaited first so the preserved checkpoint
+	* reflects the latest disk state we asked for.
+	*
+	* Corresponds to `DELETE /v1/projects/:pid/sandbox/:sandboxId` on
+	* workspace-proxy, which by contract does not touch the checkpoint. Use
+	* {@link destroy} when you want the checkpoint released too.
+	*/
 	async stop() {
-		await this.destroy();
+		if (this._captureInFlight) await this._captureInFlight.catch((error) => {
+			this.logger.warn(`stop(): failed to flush in-flight capture before teardown:`, error);
+		});
+		await this._teardownSandbox();
 	}
+	/**
+	* Destroy the sandbox **and release its recovery checkpoint**.
+	*
+	* Semantic parity with `@mastra/railway` `RailwaySandbox.destroy()`:
+	* cancels any in-flight capture (the checkpoint is about to be deleted
+	* — no reason to burn a capture on state we're releasing), asks the
+	* proxy to delete the checkpoint, then releases the VM. Both remote
+	* operations are best-effort logged failures — a stray checkpoint or a
+	* transient proxy error must not leave the caller with a half-torn-down
+	* sandbox they can't safely retry.
+	*
+	* Requires the caller to have constructed with a recovery `id` (there is
+	* no checkpoint to delete otherwise); callers without one skip the
+	* checkpoint DELETE and behave identically to {@link stop}.
+	*/
 	async destroy() {
 		if (!this._sandboxId) return;
 		const destroyedSandboxId = this._sandboxId;
+		this._captureInFlight = null;
+		if (this._hasRecoveryKey) try {
+			await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}/checkpoint`, {
+				method: "DELETE",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ id: this.id })
+			});
+		} catch (error) {
+			if (error instanceof PlatformApiError && (error.status === 404 || error.status === 410)) this.logger.debug(`destroy(): checkpoint already absent upstream (status=${error.status})`);
+			else this.logger.warn(`destroy(): failed to delete checkpoint upstream:`, error);
+		}
+		await this._teardownSandbox();
+	}
+	/**
+	* Release the remote sandbox VM and clear the local state pointing at it.
+	*
+	* Shared body of {@link stop} and {@link destroy} — both funnel through
+	* here after they've dealt with the checkpoint (preserve vs release).
+	* The VM DELETE is safe to issue in either mode: the proxy's DELETE
+	* route does not touch the checkpoint on its own, so `stop()` correctly
+	* leaves the checkpoint intact and `destroy()` has already removed it
+	* before this call.
+	*/
+	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.
+	*
+	* Intended for callers (e.g. a factory-side scheduler) that want to refresh
+	* the recovery checkpoint at semantic moments — turn end, session-idle,
+	* pre-teardown — rather than only just before the upstream's idle destroy.
+	*
+	* Mirrors the OSS `@mastra/railway` `RailwaySandbox.captureCheckpoint()`
+	* shape so factory can call `sandbox.captureCheckpoint()` uniformly and
+	* branch on `status`/`reason` without knowing which provider is underneath.
+	* Both `captured` and `coalesced` carry the checkpoint name inline so the
+	* caller can persist a session→checkpoint binding atomically with the
+	* awaited capture.
+	*
+	* Skip semantics:
+	*  - No caller-supplied `id`: returns `{ status: 'skipped', reason:
+	*    'no-checkpoint-name-configured' }`. An auto-generated random id is
+	*    never a meaningful recovery key (no future boot would look for a
+	*    checkpoint under it), so capturing would silently produce dead data.
+	*  - Not started (no `_sandboxId`): returns `{ status: 'skipped', reason:
+	*    'sandbox-not-running' }` without a round-trip.
+	*  - Upstream 410 (workspace-proxy or Railway reports the sandbox is
+	*    already destroyed): returns the same `sandbox-not-running` skip so
+	*    the discriminant matches the pre-flight case. Local state
+	*    (`_sandboxId`, `_lease`, sidecar address) is cleared as a side
+	*    effect so the next `start()` provisions fresh instead of reattaching
+	*    to a dead id. The diagnostic distinction (pre-flight vs post-hoc)
+	*    is preserved in log level: debug for the expected pre-flight skip,
+	*    warn for the surprise upstream destroy.
+	*
+	* Concurrent callers on the same instance coalesce onto a single in-flight
+	* `POST /checkpoint` so N simultaneous turn-end fires (e.g. several tabs)
+	* do not each round-trip the proxy. Both the originator and joiners
+	* receive `{ status: 'coalesced', ... }` for the joined result — the
+	* outer contract does not distinguish who started the request, only that
+	* one upstream capture was made.
+	*
+	* Never throws for expected outcomes. Transport failures (5xx, 4xx other
+	* than 410) propagate as {@link PlatformApiError}; a 410 is normalized
+	* to a skip as described above.
+	*/
+	async captureCheckpoint() {
+		if (!this._hasRecoveryKey) {
+			this.logger.debug(`captureCheckpoint skipped: no recovery key configured for sandbox ${this._sandboxId ?? "(unstarted)"}`);
+			return {
+				status: "skipped",
+				reason: "no-checkpoint-name-configured"
+			};
+		}
+		if (!this._sandboxId) {
+			this.logger.debug(`captureCheckpoint skipped: sandbox not running (local pre-flight, id=${this.id})`);
+			return {
+				status: "skipped",
+				reason: "sandbox-not-running"
+			};
+		}
+		if (this._captureInFlight) return this._captureInFlight;
+		const sandboxId = this._sandboxId;
+		const capture = this._doCaptureCheckpoint(sandboxId).finally(() => {
+			if (this._captureInFlight === capture) this._captureInFlight = null;
+		});
+		this._captureInFlight = capture;
+		return capture;
+	}
+	/**
+	* The single `POST /checkpoint` attempt behind {@link captureCheckpoint}.
+	*
+	* Split out so the coalescing wrapper can install a shared in-flight
+	* promise without inlining the transport + response-mapping logic.
+	* Joined callers observe `{ status: 'coalesced', ... }` — the initiator
+	* sees the underlying `captured` / `coalesced` / `skipped` result the
+	* proxy returned. Both are legitimate: the OSS mirror uses the same
+	* "initiator sees the truth, joiners see coalesced" split.
+	*/
+	async _doCaptureCheckpoint(sandboxId) {
+		let response;
+		try {
+			response = await this._client.request(`/sandbox/${encodeURIComponent(sandboxId)}/checkpoint`, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ id: this.id })
+			});
+		} catch (error) {
+			if (error instanceof PlatformApiError && error.status === 410) {
+				this.logger.warn(`captureCheckpoint skipped: sandbox destroyed upstream (proxy 410, sandboxId=${sandboxId})`);
+				this._clearDestroyedState(sandboxId);
+				return {
+					status: "skipped",
+					reason: "sandbox-not-running"
+				};
+			}
+			throw error;
+		}
+		const json = await response.json();
+		if (json.status === "skipped") {
+			this.logger.warn(`captureCheckpoint skipped: sandbox destroyed upstream (proxy reported skipped, sandboxId=${sandboxId})`);
+			this._clearDestroyedState(sandboxId);
+			return {
+				status: "skipped",
+				reason: "sandbox-not-running"
+			};
+		}
+		return {
+			status: json.status,
+			checkpointName: json.checkpointName
+		};
+	}
+	/**
+	* Clear local state that would otherwise let the caller keep exec'ing
+	* against a sandbox the upstream has already destroyed. Mirrors what
+	* `destroy()` does minus the outbound DELETE — the sandbox is already
+	* gone, so all that remains is to stop pointing at it.
+	*
+	* Also resets `status` to `'pending'` so a subsequent `_start()` on this
+	* reused instance re-runs provisioning instead of short-circuiting on
+	* the cached `'running'` state (see `MastraSandbox._start`).
+	*/
+	_clearDestroyedState(destroyedSandboxId) {
+		this._sandboxId = void 0;
+		this._createdAt = null;
+		this._lease = null;
+		this._addressRegistry?.delete(destroyedSandboxId);
+		this.status = "pending";
+	}
 	/**
 	* Execute a command on the remote sandbox.
 	*
@@ -982,6 +1355,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		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);