@mastra/platform-workspace 1.0.0 → 1.1.0

package/dist/index.js

@@ -488,6 +488,175 @@ function execViaLease(lease, options) {
 	});
 }
 //#endregion
+//#region src/private-net-exec.ts
+/**
+* Thrown by {@link execViaPrivateNetwork} when the sidecar returns a non-2xx
+* HTTP response. This is an *application* error, not a transport error — the
+* sidecar is reachable and answered, it just refused the exec. Callers should
+* fall back to the lease path for this one call but MUST NOT invalidate the
+* cached `instanceUrl` (the address is still good).
+*/
+var PrivateNetExecHttpError = class extends Error {
+	status;
+	body;
+	constructor(status, body) {
+		super(`Sidecar /exec returned ${status}${body ? `: ${body.slice(0, 200)}` : ""}`);
+		this.name = "PrivateNetExecHttpError";
+		this.status = status;
+		this.body = body;
+	}
+};
+const DEFAULT_FETCH = (input, init) => {
+	const f = globalThis.fetch;
+	if (!f) throw new Error("Private-network exec requires a fetch implementation. Node 22+ provides one globally; on older runtimes, pass fetch explicitly.");
+	return f(input, init);
+};
+/**
+* Dial `${instanceUrl}/exec` and stream the response, resolving with the
+* accumulated stdout/stderr + exit code.
+*
+* Errors:
+* - Connection failure (DNS, refused, reset) → resolves with
+*   `{opened:false, exitCode:null, transportErrorMessage}`. Never throws for
+*   transport failures — the shape matches the lease-path result so the
+*   caller can treat both transports uniformly.
+* - Non-2xx HTTP response from the sidecar → throws {@link PrivateNetExecHttpError}.
+*   Application-level; caller decides whether to fall back.
+* - Stream ends without an `exit` frame → resolves with
+*   `{opened:true, exitCode:null}`, matching the lease-path semantics for a
+*   mid-stream drop.
+* - `timeoutMs` elapsed → aborts the request, resolves with
+*   `{timedOut:true, exitCode:124}`.
+*/
+async function execViaPrivateNetwork(instanceUrl, options) {
+	const fetchImpl = options.fetch ?? DEFAULT_FETCH;
+	const url = `${instanceUrl.replace(/\/$/, "")}/exec`;
+	const controller = new AbortController();
+	let timedOut = false;
+	let timeoutTimer;
+	if (options.timeoutMs !== void 0 && options.timeoutMs > 0) timeoutTimer = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, options.timeoutMs);
+	const body = { command: options.command };
+	if (options.cwd) body.cwd = options.cwd;
+	if (options.env && Object.keys(options.env).length > 0) body.env = options.env;
+	if (options.timeoutMs !== void 0 && options.timeoutMs > 0) body.timeoutMs = options.timeoutMs;
+	const headers = { "content-type": "application/json" };
+	if (options.bearerToken) headers.authorization = `Bearer ${options.bearerToken}`;
+	let response;
+	try {
+		response = await fetchImpl(url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+			signal: controller.signal
+		});
+	} catch (error) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		if (timedOut) return {
+			exitCode: 124,
+			stdout: "",
+			stderr: "",
+			timedOut: true,
+			opened: false
+		};
+		return {
+			exitCode: null,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			opened: false,
+			transportErrorMessage: error instanceof Error ? error.message : String(error)
+		};
+	}
+	if (!response.ok) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		const text = await response.text().catch(() => "");
+		throw new PrivateNetExecHttpError(response.status, text);
+	}
+	if (!response.body) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		return {
+			exitCode: null,
+			stdout: "",
+			stderr: "",
+			timedOut: false,
+			opened: true,
+			status: response.status
+		};
+	}
+	let stdout = "";
+	let stderr = "";
+	let exitCode = null;
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const handleLine = (line) => {
+		if (!line) return;
+		let frame;
+		try {
+			frame = JSON.parse(line);
+		} catch {
+			return;
+		}
+		if (!frame || typeof frame !== "object") return;
+		if (frame.type === "stdout" && typeof frame.data === "string") {
+			stdout += frame.data;
+			options.onStdout?.(frame.data);
+		} else if (frame.type === "stderr" && typeof frame.data === "string") {
+			stderr += frame.data;
+			options.onStderr?.(frame.data);
+		} else if (frame.type === "exit" && typeof frame.code === "number") exitCode = frame.code;
+	};
+	try {
+		const reader = response.body.getReader();
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let newlineIdx = buffer.indexOf("\n");
+			while (newlineIdx !== -1) {
+				const line = buffer.slice(0, newlineIdx).trim();
+				buffer = buffer.slice(newlineIdx + 1);
+				handleLine(line);
+				newlineIdx = buffer.indexOf("\n");
+			}
+		}
+		buffer += decoder.decode();
+		const trailing = buffer.trim();
+		if (trailing) handleLine(trailing);
+	} catch (error) {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+		if (timedOut) return {
+			exitCode: 124,
+			stdout,
+			stderr,
+			timedOut: true,
+			opened: true,
+			status: response.status
+		};
+		return {
+			exitCode,
+			stdout,
+			stderr,
+			timedOut: false,
+			opened: true,
+			status: response.status,
+			transportErrorMessage: error instanceof Error ? error.message : String(error)
+		};
+	} finally {
+		if (timeoutTimer) clearTimeout(timeoutTimer);
+	}
+	return {
+		exitCode,
+		stdout,
+		stderr,
+		timedOut: false,
+		opened: true,
+		status: response.status
+	};
+}
+//#endregion
 //#region src/sandbox.ts
 /**
 * How long before a lease's stated `expiresAt` we should treat it as
@@ -638,6 +807,19 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 	_instructionsOverride;
 	_createdAt = null;
 	_webSocketFactory;
+	_privateNetFetch;
+	/**
+	* Registry that maps `sandboxId → instanceUrl` for the private-network
+	* exec path. Injected by the composition site via
+	* {@link PlatformSandboxOptions.addressRegistry} and populated by this
+	* class itself in `start()` when the workspace-proxy's create/reattach
+	* response includes an `instanceUrl` field. The registry IS the cache —
+	* there is no per-instance mirror on `PlatformSandbox`, so every exec is
+	* a `Map.get()` (in the default in-process impl) against the live view.
+	* When absent, executes go straight to the lease path with no extra
+	* round-trip.
+	*/
+	_addressRegistry;
 	/**
 	* Cached exec lease for this sandbox. `null` before the first exec and
 	* after {@link destroy}. Refreshed when `expiresAt - LEASE_REFRESH_MARGIN_MS < now`
@@ -669,6 +851,8 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		this._timeout = options.timeout;
 		this._instructionsOverride = options.instructions;
 		this._webSocketFactory = options.webSocketFactory;
+		this._privateNetFetch = options.privateNetFetch;
+		this._addressRegistry = options.addressRegistry;
 	}
 	generateId() {
 		return `platform-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -699,7 +883,9 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			env: options.env ?? this._env,
 			...this._timeout !== void 0 && { timeout: this._timeout },
 			...this._instructionsOverride !== void 0 && { instructions: this._instructionsOverride },
-			...this._webSocketFactory !== void 0 && { webSocketFactory: this._webSocketFactory }
+			...this._webSocketFactory !== void 0 && { webSocketFactory: this._webSocketFactory },
+			...this._privateNetFetch !== void 0 && { privateNetFetch: this._privateNetFetch },
+			...this._addressRegistry !== void 0 && { addressRegistry: this._addressRegistry }
 		});
 	}
 	async start() {
@@ -707,6 +893,7 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 			const json = await (await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`)).json();
 			if (!json.destroyedAt) {
 				this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+				this._populateAddressFromResponse(json);
 				return;
 			}
 			this._sandboxId = void 0;
@@ -737,16 +924,40 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		const json = await response.json();
 		this._sandboxId = json.id;
 		this._createdAt = json.createdAt ? new Date(json.createdAt) : /* @__PURE__ */ new Date();
+		this._populateAddressFromResponse(json);
+	}
+	/**
+	* Copy `response.instanceUrl` into the injected {@link SandboxAddressRegistry}
+	* when both are present. Called from both {@link start} branches (fresh
+	* provision + reattach) with the workspace-proxy response for this sandbox.
+	*
+	* The proxy discovers the IPv6 during `Sandbox.create()` and stores it in
+	* `environment_sandboxes.instance_url`; both the create response and
+	* `GET /sandbox/:id` echo the same field. The runtime does not do any
+	* discovery of its own — it only mirrors the field into an in-process map
+	* so {@link executeCommand} can `Map.get()` before every exec without an
+	* HTTP round-trip.
+	*
+	* `null`/absent `instanceUrl` (proxy discovery failed, or an older proxy
+	* that predates the field) leaves the registry untouched — executes fall
+	* through to the lease path with no branch here.
+	*/
+	_populateAddressFromResponse(json) {
+		if (!this._addressRegistry) return;
+		if (!json.instanceUrl) return;
+		this._addressRegistry.set(json.id, json.instanceUrl);
 	}
 	async stop() {
 		await this.destroy();
 	}
 	async destroy() {
 		if (!this._sandboxId) return;
-		await this._client.request(`/sandbox/${encodeURIComponent(this._sandboxId)}`, { method: "DELETE" });
+		const destroyedSandboxId = this._sandboxId;
+		await this._client.request(`/sandbox/${encodeURIComponent(destroyedSandboxId)}`, { method: "DELETE" });
 		this._sandboxId = void 0;
 		this._createdAt = null;
 		this._lease = null;
+		this._addressRegistry?.delete(destroyedSandboxId);
 	}
 	/**
 	* Execute a command on the remote sandbox.
@@ -771,6 +982,22 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		const started = Date.now();
 		const fullCommand = buildCommand(command, args);
 		const effectiveTimeout = options?.timeout ?? this._timeout;
+		const instanceUrl = this._addressRegistry?.get(this._sandboxId);
+		if (instanceUrl) {
+			const privateNet = await this._tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options);
+			if (privateNet) {
+				const privateExit = privateNet.exitCode ?? 124;
+				return {
+					success: privateExit === 0,
+					exitCode: privateExit,
+					stdout: privateNet.stdout,
+					stderr: privateNet.stderr,
+					timedOut: privateNet.timedOut,
+					command: fullCommand,
+					executionTimeMs: Date.now() - started
+				};
+			}
+		}
 		const result = await this._runDirectExec(fullCommand, effectiveTimeout, options);
 		const exitCode = result.exitCode ?? 124;
 		return {
@@ -853,6 +1080,55 @@ var PlatformSandbox = class PlatformSandbox extends MastraSandbox {
 		});
 	}
 	/**
+	* Try to run the exec against the in-sandbox sidecar over Railway's private
+	* network. Returns the result on success (including non-zero exit codes and
+	* timeouts — those are real command results, not failures). Returns
+	* `undefined` when the caller should fall back to the lease path:
+	*
+	* - Transport failure (connection refused, mid-stream drop, no `exit`
+	*   frame). The registry entry is evicted so subsequent execs skip the
+	*   private-net dial until the sidecar re-registers.
+	* - Sidecar answered with a non-2xx HTTP status. Registry is left intact —
+	*   the address is still valid; something else is wrong (bad request,
+	*   sidecar bug). Only this specific exec falls back.
+	*/
+	async _tryExecViaPrivateNetwork(instanceUrl, fullCommand, effectiveTimeout, options) {
+		const filteredEnv = options?.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		const execOptions = {
+			command: fullCommand,
+			...options?.cwd !== void 0 && { cwd: options.cwd },
+			...filteredEnv !== void 0 && { env: filteredEnv },
+			...effectiveTimeout != null && effectiveTimeout > 0 && { timeoutMs: effectiveTimeout },
+			...this._privateNetFetch && { fetch: this._privateNetFetch }
+		};
+		let result;
+		try {
+			result = await execViaPrivateNetwork(instanceUrl, execOptions);
+		} catch (error) {
+			if (error instanceof PrivateNetExecHttpError) return;
+			this._invalidateAddress();
+			return;
+		}
+		if (result.timedOut) {
+			if (!result.opened) this._invalidateAddress();
+			return result;
+		}
+		if (!result.opened || result.exitCode === null) {
+			this._invalidateAddress();
+			return;
+		}
+		return result;
+	}
+	/**
+	* Evict this sandbox's entry from the address registry after an observed
+	* transport failure. The entry stays gone until the next start() re-reads
+	* `instanceUrl` from a workspace-proxy response — until then, execs skip
+	* the private-net dial and go straight to the lease path.
+	*/
+	_invalidateAddress() {
+		if (this._sandboxId) this._addressRegistry?.delete(this._sandboxId);
+	}
+	/**
 	* 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`.
 	*
@@ -994,6 +1270,39 @@ const platformFilesystemProvider = {
 	createFilesystem: (config) => new PlatformFilesystem(config)
 };
 //#endregion
-export { PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, SandboxDestroyedError, SandboxExecTransportError, platformFilesystemProvider, platformSandboxProvider };
+//#region src/address-registry.ts
+/**
+* Concrete in-process {@link SandboxAddressRegistry}. Backed by a `Map`; no
+* eviction policy, no TTL — entries live until an observed transport failure
+* calls `delete`, until the sandbox is explicitly destroyed, or until the
+* process exits.
+*/
+var InProcessSandboxAddressRegistry = class {
+	#map = /* @__PURE__ */ new Map();
+	get(sandboxId) {
+		return this.#map.get(sandboxId);
+	}
+	/**
+	* Populate or overwrite the address for a sandbox. Called by
+	* {@link PlatformSandbox.start} on every fresh provision and every reattach;
+	* overwriting is intentional so a re-provision with a fresh IPv6 heals the
+	* map without a branch.
+	*/
+	set(sandboxId, instanceUrl) {
+		this.#map.set(sandboxId, instanceUrl);
+	}
+	delete(sandboxId) {
+		this.#map.delete(sandboxId);
+	}
+	/**
+	* Test-only introspection. Not part of {@link SandboxAddressRegistry} —
+	* production callers must not read the registry as a whole.
+	*/
+	get size() {
+		return this.#map.size;
+	}
+};
+//#endregion
+export { InProcessSandboxAddressRegistry, PlatformApiError, PlatformClient, PlatformFilesystem, PlatformSandbox, PrivateNetExecHttpError, SandboxDestroyedError, SandboxExecTransportError, execViaPrivateNetwork, platformFilesystemProvider, platformSandboxProvider };
 
 //# sourceMappingURL=index.js.map