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

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"
@@ -863,6 +891,22 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	* 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,
@@ -905,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 },
@@ -934,11 +980,16 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	* 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;
@@ -955,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",
@@ -966,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}
@@ -990,7 +1064,74 @@ 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**.
@@ -1055,12 +1196,17 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	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.
@@ -1209,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);