@mastra/deployer-sandbox 0.0.0-aggregate-trace-20261015182851

package/LICENSE.md

@@ -0,0 +1,32 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named `ee/` within this
+  repository, including but not limited to:
+  - `@mastra/core/auth/ee`
+  - `@mastra/core/agent-builder/ee`
+  - `@mastra/editor/ee`
+
+  is licensed under the license defined in [`ee/LICENSE`](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE).
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,65 @@
+# @mastra/deployer-sandbox
+
+Deploy a full Mastra server or a non-HTTP worker into a workspace sandbox. It is intended for ephemeral previews, CI smoke deployments, isolated jobs, agent-built application verification, and untrusted tenant environments rather than permanent production hosting.
+
+## Installation
+
+```bash
+npm install @mastra/deployer-sandbox
+```
+
+Install a workspace sandbox provider separately. The examples below use `@mastra/vercel`.
+
+## Usage
+
+```typescript
+// src/mastra/index.ts
+import { Mastra } from '@mastra/core/mastra';
+import { SandboxDeployer } from '@mastra/deployer-sandbox';
+import { VercelSandbox } from '@mastra/vercel';
+
+const deployer = new SandboxDeployer({
+  sandbox: new VercelSandbox({
+    sandboxName: 'my-preview',
+    timeout: 2_400_000,
+    ports: [4111],
+  }),
+});
+
+export const mastra = new Mastra({ deployer });
+```
+
+Running `mastra build` bundles the project and deploys it into the sandbox, then prints the API and Studio URLs.
+
+## Documentation
+
+Server deployments require a `WorkspaceSandbox` implementation with command execution and networking support. The sandbox name is the deployment identity, so subsequent processes can reconnect to the same deployment with the server-only `@mastra/deployer-sandbox/client` export:
+
+```typescript
+import { getDeployment } from '@mastra/deployer-sandbox/client';
+import { VercelSandbox } from '@mastra/vercel';
+
+const deployment = await getDeployment({
+  sandbox: new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] }),
+});
+
+console.log(deployment.status, deployment.url);
+await deployment.stop(); // Resumable snapshot stop
+await deployment.destroy(); // Permanent deletion
+```
+
+Use `deployToSandbox()` for one-shot programmatic deployments of a prebuilt `.mastra/output` directory. Pass `wake: true` to `getDeployment()` when a stopped server should be resumed and health-checked before it is returned.
+
+The package also supports non-HTTP workers through `deployWorkerToSandbox()`. Workers only require command execution and can receive bounded input through stdin or a staged file. Their handles expose status checks, separate offset-based stdout and stderr reads, cancellation, snapshot stop, relaunch, and permanent destruction. `attachWorkerDeployment()` reconstructs a handle from persisted sandbox and execution IDs after a supervisor restart.
+
+Dependency installation is serialized and cached from the artifact's package manifest and lockfile. Worker cancellation sends TERM before KILL when necessary, while server health checks surface startup logs when a deployment fails to become ready.
+
+- [Sandbox deployment documentation](https://mastra.ai/docs/deployment/sandbox)
+
+## Changelog
+
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/deployers/sandbox/CHANGELOG.md) for version history and release notes.
+
+## Support
+
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/dist/alias.d.ts

@@ -0,0 +1,10 @@
+import type { SandboxAliasOptions } from './types.js';
+/**
+ * Upsert a Vercel Edge Config item so a stable key always points at the
+ * current sandbox URL. Used for Tier 3 routing: apps read the key from Edge
+ * Config (e.g. in middleware) instead of hardcoding the rotating sandbox URL.
+ */
+export declare function updateEdgeConfigAlias(options: SandboxAliasOptions & {
+    url: string;
+}): Promise<void>;
+//# sourceMappingURL=alias.d.ts.map

package/dist/alias.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alias.d.ts","sourceRoot":"","sources":["../src/alias.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BzG"}

package/dist/client/index.cjs

@@ -0,0 +1,174 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_shared = require("../shared-DhnF9P1K.cjs");
+let _mastra_core_workspace = require("@mastra/core/workspace");
+//#region src/client/index.ts
+/**
+* Runtime resolver + routing helpers for sandbox deployments.
+*
+* SERVER-ONLY. This module resolves sandbox URLs using provider credentials
+* (e.g. VERCEL_TOKEN) — importing it in the browser would ship those
+* credentials to the client. Use the proxy/handler patterns instead so the
+* browser only ever talks to your own domain.
+*/
+function assertServerOnly() {
+	if (typeof globalThis.window !== "undefined") throw new Error("@mastra/deployer-sandbox/client is server-only: resolving a sandbox requires provider credentials that must never reach the browser. Proxy requests through your own backend instead (see createSandboxHandler / createSandboxProxy).");
+}
+/**
+* Resolve (and optionally wake) a sandbox deployment.
+*
+* With `wake: false` (default) the sandbox is not started: the URL is resolved
+* only if the sandbox is already running in this process, otherwise
+* `{ url: null, status: 'stopped' | 'unknown' }` is returned and the caller
+* decides whether to wake.
+*
+* With `wake: true` the sandbox is started (providers resume by identity,
+* e.g. name), the server is relaunched if it is not answering, and the
+* deployment is returned once healthy.
+*/
+async function getDeployment(options) {
+	assertServerOnly();
+	const { sandbox, port = require_shared.DEFAULT_PORT, wake = false, healthCheckPath = "/api", healthCheckTimeoutMs = 6e4 } = options;
+	const handle = (url, status, expiresAt) => ({
+		url,
+		status,
+		expiresAt,
+		stop: async () => {
+			await sandbox.stop?.();
+		},
+		destroy: async () => {
+			await sandbox.destroy?.();
+		},
+		logs: async (lines) => require_shared.tailServerLog(sandbox, await require_shared.resolveRemoteDir(sandbox, options.remoteDir), lines)
+	});
+	if (!wake) {
+		const url = (0, _mastra_core_workspace.supportsNetworking)(sandbox) ? await sandbox.networking.getPortUrl(port) : null;
+		if (!url) return handle(null, "stopped");
+		return handle(url, await require_shared.waitForHealthy(url, {
+			path: healthCheckPath,
+			timeoutMs: 3e3,
+			intervalMs: 1e3
+		}) ? "running" : "stopped");
+	}
+	await sandbox.start?.();
+	if (!(0, _mastra_core_workspace.supportsNetworking)(sandbox)) throw new Error(`Sandbox provider "${sandbox.provider}" does not support networking (public port URLs).`);
+	const url = await sandbox.networking.getPortUrl(port);
+	if (!url) throw new Error(`Sandbox provider "${sandbox.provider}" did not expose a public URL for port ${port}. Make sure the port is declared when constructing the sandbox (e.g. \`ports: [${port}]\`).`);
+	let healthy = await require_shared.waitForHealthy(url, {
+		path: healthCheckPath,
+		timeoutMs: 3e3,
+		intervalMs: 1e3
+	});
+	if (!healthy) {
+		const remoteDir = await require_shared.resolveRemoteDir(sandbox, options.remoteDir);
+		await require_shared.killPreviousServer(sandbox, remoteDir);
+		await require_shared.launchServer(sandbox, remoteDir);
+		healthy = await require_shared.waitForHealthy(url, {
+			path: healthCheckPath,
+			timeoutMs: healthCheckTimeoutMs,
+			intervalMs: 1e3
+		});
+	}
+	if (!healthy) {
+		const log = await require_shared.resolveRemoteDir(sandbox, options.remoteDir).then((dir) => require_shared.tailServerLog(sandbox, dir)).catch(() => "");
+		throw new Error(`Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` + (log ? `\n\nServer log:\n${log}` : ""));
+	}
+	return handle(url, "running", (await require_shared.getInfoSafe(sandbox))?.timeoutAt);
+}
+/**
+* Framework-free route-handler proxy (fetch `Request` → `Response`). Mount it
+* as a catch-all API route; the browser only ever sees your own domain, and
+* the sandbox URL (which rotates across resumes) stays server-side.
+*/
+function createSandboxHandler(options) {
+	assertServerOnly();
+	let cachedUrl = null;
+	const forward = async (request, baseUrl) => {
+		const incoming = new URL(request.url);
+		const target = new URL(incoming.pathname + incoming.search, baseUrl);
+		const headers = new Headers(request.headers);
+		headers.delete("host");
+		if (options.secret) headers.set("x-mastra-sandbox-secret", options.secret);
+		const response = await fetch(target, {
+			method: request.method,
+			headers,
+			body: request.body,
+			duplex: "half",
+			redirect: "manual"
+		});
+		const location = response.headers.get("location");
+		if (location) {
+			const resolved = new URL(location, target);
+			if (resolved.origin === new URL(baseUrl).origin) {
+				const rewritten = new URL(resolved.pathname + resolved.search + resolved.hash, incoming.origin);
+				const responseHeaders = new Headers(response.headers);
+				responseHeaders.set("location", rewritten.toString());
+				return new Response(response.body, {
+					status: response.status,
+					statusText: response.statusText,
+					headers: responseHeaders
+				});
+			}
+		}
+		return response;
+	};
+	return async (request) => {
+		cachedUrl ??= options.resolve();
+		try {
+			return await forward(request, await cachedUrl);
+		} catch (error) {
+			cachedUrl = null;
+			if (![
+				"GET",
+				"HEAD",
+				"OPTIONS"
+			].includes(request.method)) throw error;
+			cachedUrl = options.resolve();
+			try {
+				return await forward(request, await cachedUrl);
+			} catch (retryError) {
+				cachedUrl = null;
+				throw retryError;
+			}
+		}
+	};
+}
+/**
+* Next.js middleware helper for Tier 3 routing: reads the current sandbox URL
+* from Edge Config (kept fresh by the deployer's `alias` option) and rewrites
+* the request to it. Returns `undefined` when no URL is configured so the
+* request falls through.
+*
+* ```typescript
+* // middleware.ts
+* export const middleware = createSandboxProxy({ key: 'my-preview' });
+* export const config = { matcher: '/api/:path*' };
+* ```
+*/
+function createSandboxProxy(options) {
+	assertServerOnly();
+	return async (request) => {
+		const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;
+		if (!connection) throw new Error("createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).");
+		const conn = new URL(connection);
+		const token = conn.searchParams.get("token");
+		const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);
+		const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });
+		if (!res.ok) return;
+		const sandboxUrl = await res.json();
+		if (typeof sandboxUrl !== "string" || !sandboxUrl) return;
+		const incoming = new URL(request.url);
+		const target = new URL(incoming.pathname + incoming.search, sandboxUrl);
+		const headers = new Headers({ "x-middleware-rewrite": target.toString() });
+		if (options.secret) {
+			headers.set("x-middleware-request-x-mastra-sandbox-secret", options.secret);
+			headers.set("x-middleware-override-headers", "x-mastra-sandbox-secret");
+		}
+		return new Response(null, { headers });
+	};
+}
+//#endregion
+exports.createSandboxHandler = createSandboxHandler;
+exports.createSandboxProxy = createSandboxProxy;
+exports.getDeployment = getDeployment;
+
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["DEFAULT_PORT","tailServerLog","resolveRemoteDir","waitForHealthy","killPreviousServer","launchServer","getInfoSafe"],"sources":["../../src/client/index.ts"],"sourcesContent":["/**\n * Runtime resolver + routing helpers for sandbox deployments.\n *\n * SERVER-ONLY. This module resolves sandbox URLs using provider credentials\n * (e.g. VERCEL_TOKEN) — importing it in the browser would ship those\n * credentials to the client. Use the proxy/handler patterns instead so the\n * browser only ever talks to your own domain.\n */\nimport { supportsNetworking } from '@mastra/core/workspace';\nimport type { WorkspaceSandbox } from '@mastra/core/workspace';\nimport {\n  DEFAULT_PORT,\n  getInfoSafe,\n  killPreviousServer,\n  launchServer,\n  resolveRemoteDir,\n  tailServerLog,\n  waitForHealthy,\n} from '../shared';\n\nfunction assertServerOnly(): void {\n  if (typeof (globalThis as { window?: unknown }).window !== 'undefined') {\n    throw new Error(\n      '@mastra/deployer-sandbox/client is server-only: resolving a sandbox requires provider credentials ' +\n        'that must never reach the browser. Proxy requests through your own backend instead ' +\n        '(see createSandboxHandler / createSandboxProxy).',\n    );\n  }\n}\n\nexport type DeploymentStatus = 'running' | 'stopped' | 'unknown';\n\nexport interface GetDeploymentOptions {\n  /**\n   * The sandbox to resolve. Provider construction is identity — e.g.\n   * `new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] })` resolves\n   * the same sandbox from any process.\n   */\n  sandbox: WorkspaceSandbox;\n  /** Port the Mastra server listens on. Defaults to 4111. */\n  port?: number;\n  /**\n   * Wake the sandbox when it is not running. Waking starts (resumes) the\n   * sandbox and, only if the server is not answering, relaunches it from the\n   * recorded launch script — some providers (e.g. E2B) resume processes on\n   * wake, others (e.g. Vercel) restore just the filesystem. Defaults to false.\n   */\n  wake?: boolean;\n  /** Directory the app was deployed into. Defaults to `$HOME/mastra-app` resolved inside the sandbox. */\n  remoteDir?: string;\n  /** Path polled for health. Defaults to `/api`. */\n  healthCheckPath?: string;\n  /** Max time to wait for health after a wake, in ms. Defaults to 60000. */\n  healthCheckTimeoutMs?: number;\n}\n\nexport interface ResolvedDeployment {\n  /** Public URL of the Mastra server, or null when it could not be resolved without waking. */\n  url: string | null;\n  status: DeploymentStatus;\n  /** When the sandbox will auto-shutdown (when known). */\n  expiresAt?: Date;\n  stop(): Promise<void>;\n  destroy(): Promise<void>;\n  logs(lines?: number): Promise<string>;\n}\n\n/**\n * Resolve (and optionally wake) a sandbox deployment.\n *\n * With `wake: false` (default) the sandbox is not started: the URL is resolved\n * only if the sandbox is already running in this process, otherwise\n * `{ url: null, status: 'stopped' | 'unknown' }` is returned and the caller\n * decides whether to wake.\n *\n * With `wake: true` the sandbox is started (providers resume by identity,\n * e.g. name), the server is relaunched if it is not answering, and the\n * deployment is returned once healthy.\n */\nexport async function getDeployment(options: GetDeploymentOptions): Promise<ResolvedDeployment> {\n  assertServerOnly();\n\n  const {\n    sandbox,\n    port = DEFAULT_PORT,\n    wake = false,\n    healthCheckPath = '/api',\n    healthCheckTimeoutMs = 60_000,\n  } = options;\n\n  const handle = (url: string | null, status: DeploymentStatus, expiresAt?: Date): ResolvedDeployment => ({\n    url,\n    status,\n    expiresAt,\n    stop: async () => {\n      await sandbox.stop?.();\n    },\n    destroy: async () => {\n      await sandbox.destroy?.();\n    },\n    // Resolved lazily — reading logs requires a running sandbox anyway.\n    logs: async (lines?: number) => tailServerLog(sandbox, await resolveRemoteDir(sandbox, options.remoteDir), lines),\n  });\n\n  if (!wake) {\n    // Resolve without starting the sandbox (starting can resume billing).\n    const url = supportsNetworking(sandbox) ? await sandbox.networking.getPortUrl(port) : null;\n    if (!url) {\n      return handle(null, 'stopped');\n    }\n    const healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });\n    return handle(url, healthy ? 'running' : 'stopped');\n  }\n\n  await sandbox.start?.();\n\n  if (!supportsNetworking(sandbox)) {\n    throw new Error(`Sandbox provider \"${sandbox.provider}\" does not support networking (public port URLs).`);\n  }\n  const url = await sandbox.networking.getPortUrl(port);\n  if (!url) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" did not expose a public URL for port ${port}. ` +\n        `Make sure the port is declared when constructing the sandbox (e.g. \\`ports: [${port}]\\`).`,\n    );\n  }\n\n  // Some providers (e.g. Vercel) restore the filesystem but not processes on\n  // resume, while others (e.g. E2B) resume processes too — relaunch the server\n  // from the recorded launch script only when it is not answering.\n  let healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });\n  if (!healthy) {\n    const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);\n    await killPreviousServer(sandbox, remoteDir);\n    await launchServer(sandbox, remoteDir);\n    healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1_000 });\n  }\n  if (!healthy) {\n    const log = await resolveRemoteDir(sandbox, options.remoteDir)\n      .then(dir => tailServerLog(sandbox, dir))\n      .catch(() => '');\n    throw new Error(\n      `Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` +\n        (log ? `\\n\\nServer log:\\n${log}` : ''),\n    );\n  }\n\n  const info = await getInfoSafe(sandbox);\n  return handle(url, 'running', info?.timeoutAt);\n}\n\n// =============================================================================\n// Tier 3 helpers\n// =============================================================================\n\nexport interface CreateSandboxHandlerOptions {\n  /**\n   * Resolve the current sandbox URL. Called once, cached, and re-invoked when\n   * a forwarded request fails at the network level (e.g. the sandbox rotated\n   * its URL or went to sleep). Typically wraps `getDeployment`:\n   *\n   * ```typescript\n   * createSandboxHandler({\n   *   resolve: async () => {\n   *     const dep = await getDeployment({ sandbox, wake: true });\n   *     return dep.url!;\n   *   },\n   * });\n   * ```\n   */\n  resolve: () => Promise<string>;\n  /** Shared secret attached as the `x-mastra-sandbox-secret` header on forwarded requests. */\n  secret?: string;\n}\n\n/**\n * Framework-free route-handler proxy (fetch `Request` → `Response`). Mount it\n * as a catch-all API route; the browser only ever sees your own domain, and\n * the sandbox URL (which rotates across resumes) stays server-side.\n */\nexport function createSandboxHandler(options: CreateSandboxHandlerOptions): (request: Request) => Promise<Response> {\n  assertServerOnly();\n\n  let cachedUrl: Promise<string> | null = null;\n\n  const forward = async (request: Request, baseUrl: string): Promise<Response> => {\n    const incoming = new URL(request.url);\n    const target = new URL(incoming.pathname + incoming.search, baseUrl);\n\n    const headers = new Headers(request.headers);\n    headers.delete('host');\n    if (options.secret) {\n      headers.set('x-mastra-sandbox-secret', options.secret);\n    }\n\n    const response = await fetch(target, {\n      method: request.method,\n      headers,\n      body: request.body,\n      // duplex is required by Node's fetch for streamed request bodies\n      duplex: 'half',\n      redirect: 'manual',\n    } as RequestInit);\n\n    // Redirects are passed through manually — rewrite sandbox-host Locations\n    // onto the incoming origin so the rotating sandbox URL never reaches the\n    // browser (and subsequent requests keep flowing through this handler).\n    const location = response.headers.get('location');\n    if (location) {\n      const resolved = new URL(location, target);\n      if (resolved.origin === new URL(baseUrl).origin) {\n        const rewritten = new URL(resolved.pathname + resolved.search + resolved.hash, incoming.origin);\n        const responseHeaders = new Headers(response.headers);\n        responseHeaders.set('location', rewritten.toString());\n        return new Response(response.body, {\n          status: response.status,\n          statusText: response.statusText,\n          headers: responseHeaders,\n        });\n      }\n    }\n\n    return response;\n  };\n\n  return async (request: Request): Promise<Response> => {\n    cachedUrl ??= options.resolve();\n\n    try {\n      return await forward(request, await cachedUrl);\n    } catch (error) {\n      // Connection-level failure: the sandbox may have rotated its URL or gone\n      // to sleep. Drop the cached URL so the next request re-resolves, and\n      // retry once — but only for idempotent, bodyless methods. A failed\n      // connection doesn't prove a write never landed, and a streamed body is\n      // already consumed.\n      cachedUrl = null;\n      if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method)) {\n        throw error;\n      }\n      cachedUrl = options.resolve();\n      try {\n        return await forward(request, await cachedUrl);\n      } catch (retryError) {\n        cachedUrl = null;\n        throw retryError;\n      }\n    }\n  };\n}\n\nexport interface CreateSandboxProxyOptions {\n  /** Edge Config item key that holds the current sandbox URL. */\n  key: string;\n  /**\n   * Edge Config connection string (`https://edge-config.vercel.com/ecfg_...?token=...`).\n   * Defaults to `process.env.EDGE_CONFIG`.\n   */\n  edgeConfig?: string;\n  /** Shared secret attached as the `x-mastra-sandbox-secret` header on the rewrite. */\n  secret?: string;\n}\n\n/**\n * Next.js middleware helper for Tier 3 routing: reads the current sandbox URL\n * from Edge Config (kept fresh by the deployer's `alias` option) and rewrites\n * the request to it. Returns `undefined` when no URL is configured so the\n * request falls through.\n *\n * ```typescript\n * // middleware.ts\n * export const middleware = createSandboxProxy({ key: 'my-preview' });\n * export const config = { matcher: '/api/:path*' };\n * ```\n */\nexport function createSandboxProxy(\n  options: CreateSandboxProxyOptions,\n): (request: Request) => Promise<Response | undefined> {\n  // Reads (and would transmit) the Edge Config bearer token — same\n  // server-only contract as the rest of this module.\n  assertServerOnly();\n\n  return async (request: Request): Promise<Response | undefined> => {\n    const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;\n    if (!connection) {\n      throw new Error('createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).');\n    }\n\n    const conn = new URL(connection);\n    const token = conn.searchParams.get('token');\n    const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);\n\n    const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });\n    if (!res.ok) {\n      return undefined;\n    }\n    const sandboxUrl: unknown = await res.json();\n    if (typeof sandboxUrl !== 'string' || !sandboxUrl) {\n      return undefined;\n    }\n\n    const incoming = new URL(request.url);\n    const target = new URL(incoming.pathname + incoming.search, sandboxUrl);\n\n    // A Response with the x-middleware-rewrite header is how Next.js\n    // middleware expresses a rewrite (NextResponse.rewrite does the same) —\n    // this keeps the helper free of a next dependency.\n    const headers = new Headers({ 'x-middleware-rewrite': target.toString() });\n    if (options.secret) {\n      headers.set('x-middleware-request-x-mastra-sandbox-secret', options.secret);\n      headers.set('x-middleware-override-headers', 'x-mastra-sandbox-secret');\n    }\n    return new Response(null, { headers });\n  };\n}\n"],"mappings":";;;;;;;;;;;;AAoBA,SAAS,mBAAyB;CAChC,IAAI,OAAQ,WAAoC,WAAW,aACzD,MAAM,IAAI,MACR,uOAGF;AAEJ;;;;;;;;;;;;;AAmDA,eAAsB,cAAc,SAA4D;CAC9F,iBAAiB;CAEjB,MAAM,EACJ,SACA,OAAOA,eAAAA,cACP,OAAO,OACP,kBAAkB,QAClB,uBAAuB,QACrB;CAEJ,MAAM,UAAU,KAAoB,QAA0B,eAA0C;EACtG;EACA;EACA;EACA,MAAM,YAAY;GAChB,MAAM,QAAQ,OAAO;EACvB;EACA,SAAS,YAAY;GACnB,MAAM,QAAQ,UAAU;EAC1B;EAEA,MAAM,OAAO,UAAmBC,eAAAA,cAAc,SAAS,MAAMC,eAAAA,iBAAiB,SAAS,QAAQ,SAAS,GAAG,KAAK;CAClH;CAEA,IAAI,CAAC,MAAM;EAET,MAAM,OAAA,GAAA,uBAAA,mBAAA,CAAyB,OAAO,IAAI,MAAM,QAAQ,WAAW,WAAW,IAAI,IAAI;EACtF,IAAI,CAAC,KACH,OAAO,OAAO,MAAM,SAAS;EAG/B,OAAO,OAAO,KAAK,MADGC,eAAAA,eAAe,KAAK;GAAE,MAAM;GAAiB,WAAW;GAAO,YAAY;EAAM,CAAC,IAC3E,YAAY,SAAS;CACpD;CAEA,MAAM,QAAQ,QAAQ;CAEtB,IAAI,EAAA,GAAA,uBAAA,mBAAA,CAAoB,OAAO,GAC7B,MAAM,IAAI,MAAM,qBAAqB,QAAQ,SAAS,kDAAkD;CAE1G,MAAM,MAAM,MAAM,QAAQ,WAAW,WAAW,IAAI;CACpD,IAAI,CAAC,KACH,MAAM,IAAI,MACR,qBAAqB,QAAQ,SAAS,yCAAyC,KAAK,iFACF,KAAK,MACzF;CAMF,IAAI,UAAU,MAAMA,eAAAA,eAAe,KAAK;EAAE,MAAM;EAAiB,WAAW;EAAO,YAAY;CAAM,CAAC;CACtG,IAAI,CAAC,SAAS;EACZ,MAAM,YAAY,MAAMD,eAAAA,iBAAiB,SAAS,QAAQ,SAAS;EACnE,MAAME,eAAAA,mBAAmB,SAAS,SAAS;EAC3C,MAAMC,eAAAA,aAAa,SAAS,SAAS;EACrC,UAAU,MAAMF,eAAAA,eAAe,KAAK;GAAE,MAAM;GAAiB,WAAW;GAAsB,YAAY;EAAM,CAAC;CACnH;CACA,IAAI,CAAC,SAAS;EACZ,MAAM,MAAM,MAAMD,eAAAA,iBAAiB,SAAS,QAAQ,SAAS,CAAC,CAC3D,MAAK,QAAOD,eAAAA,cAAc,SAAS,GAAG,CAAC,CAAC,CACxC,YAAY,EAAE;EACjB,MAAM,IAAI,MACR,gEAAgE,MAAM,gBAAgB,MACnF,MAAM,oBAAoB,QAAQ,GACvC;CACF;CAGA,OAAO,OAAO,KAAK,YAAW,MADXK,eAAAA,YAAY,OAAO,EAAA,EACF,SAAS;AAC/C;;;;;;AA+BA,SAAgB,qBAAqB,SAA+E;CAClH,iBAAiB;CAEjB,IAAI,YAAoC;CAExC,MAAM,UAAU,OAAO,SAAkB,YAAuC;EAC9E,MAAM,WAAW,IAAI,IAAI,QAAQ,GAAG;EACpC,MAAM,SAAS,IAAI,IAAI,SAAS,WAAW,SAAS,QAAQ,OAAO;EAEnE,MAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;EAC3C,QAAQ,OAAO,MAAM;EACrB,IAAI,QAAQ,QACV,QAAQ,IAAI,2BAA2B,QAAQ,MAAM;EAGvD,MAAM,WAAW,MAAM,MAAM,QAAQ;GACnC,QAAQ,QAAQ;GAChB;GACA,MAAM,QAAQ;GAEd,QAAQ;GACR,UAAU;EACZ,CAAgB;EAKhB,MAAM,WAAW,SAAS,QAAQ,IAAI,UAAU;EAChD,IAAI,UAAU;GACZ,MAAM,WAAW,IAAI,IAAI,UAAU,MAAM;GACzC,IAAI,SAAS,WAAW,IAAI,IAAI,OAAO,CAAC,CAAC,QAAQ;IAC/C,MAAM,YAAY,IAAI,IAAI,SAAS,WAAW,SAAS,SAAS,SAAS,MAAM,SAAS,MAAM;IAC9F,MAAM,kBAAkB,IAAI,QAAQ,SAAS,OAAO;IACpD,gBAAgB,IAAI,YAAY,UAAU,SAAS,CAAC;IACpD,OAAO,IAAI,SAAS,SAAS,MAAM;KACjC,QAAQ,SAAS;KACjB,YAAY,SAAS;KACrB,SAAS;IACX,CAAC;GACH;EACF;EAEA,OAAO;CACT;CAEA,OAAO,OAAO,YAAwC;EACpD,cAAc,QAAQ,QAAQ;EAE9B,IAAI;GACF,OAAO,MAAM,QAAQ,SAAS,MAAM,SAAS;EAC/C,SAAS,OAAO;GAMd,YAAY;GACZ,IAAI,CAAC;IAAC;IAAO;IAAQ;GAAS,CAAC,CAAC,SAAS,QAAQ,MAAM,GACrD,MAAM;GAER,YAAY,QAAQ,QAAQ;GAC5B,IAAI;IACF,OAAO,MAAM,QAAQ,SAAS,MAAM,SAAS;GAC/C,SAAS,YAAY;IACnB,YAAY;IACZ,MAAM;GACR;EACF;CACF;AACF;;;;;;;;;;;;;AA0BA,SAAgB,mBACd,SACqD;CAGrD,iBAAiB;CAEjB,OAAO,OAAO,YAAoD;EAChE,MAAM,aAAa,QAAQ,cAAc,QAAQ,IAAI;EACrD,IAAI,CAAC,YACH,MAAM,IAAI,MAAM,6EAA6E;EAG/F,MAAM,OAAO,IAAI,IAAI,UAAU;EAC/B,MAAM,QAAQ,KAAK,aAAa,IAAI,OAAO;EAC3C,MAAM,UAAU,IAAI,IAAI,GAAG,KAAK,SAAS,KAAK,SAAS,QAAQ,mBAAmB,QAAQ,GAAG,GAAG;EAEhG,MAAM,MAAM,MAAM,MAAM,SAAS,EAAE,SAAS,EAAE,eAAe,UAAU,QAAQ,EAAE,CAAC;EAClF,IAAI,CAAC,IAAI,IACP;EAEF,MAAM,aAAsB,MAAM,IAAI,KAAK;EAC3C,IAAI,OAAO,eAAe,YAAY,CAAC,YACrC;EAGF,MAAM,WAAW,IAAI,IAAI,QAAQ,GAAG;EACpC,MAAM,SAAS,IAAI,IAAI,SAAS,WAAW,SAAS,QAAQ,UAAU;EAKtE,MAAM,UAAU,IAAI,QAAQ,EAAE,wBAAwB,OAAO,SAAS,EAAE,CAAC;EACzE,IAAI,QAAQ,QAAQ;GAClB,QAAQ,IAAI,gDAAgD,QAAQ,MAAM;GAC1E,QAAQ,IAAI,iCAAiC,yBAAyB;EACxE;EACA,OAAO,IAAI,SAAS,MAAM,EAAE,QAAQ,CAAC;CACvC;AACF"}

package/dist/client/index.d.ts

@@ -0,0 +1,98 @@
+import type { WorkspaceSandbox } from '@mastra/core/workspace';
+export type DeploymentStatus = 'running' | 'stopped' | 'unknown';
+export interface GetDeploymentOptions {
+    /**
+     * The sandbox to resolve. Provider construction is identity — e.g.
+     * `new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] })` resolves
+     * the same sandbox from any process.
+     */
+    sandbox: WorkspaceSandbox;
+    /** Port the Mastra server listens on. Defaults to 4111. */
+    port?: number;
+    /**
+     * Wake the sandbox when it is not running. Waking starts (resumes) the
+     * sandbox and, only if the server is not answering, relaunches it from the
+     * recorded launch script — some providers (e.g. E2B) resume processes on
+     * wake, others (e.g. Vercel) restore just the filesystem. Defaults to false.
+     */
+    wake?: boolean;
+    /** Directory the app was deployed into. Defaults to `$HOME/mastra-app` resolved inside the sandbox. */
+    remoteDir?: string;
+    /** Path polled for health. Defaults to `/api`. */
+    healthCheckPath?: string;
+    /** Max time to wait for health after a wake, in ms. Defaults to 60000. */
+    healthCheckTimeoutMs?: number;
+}
+export interface ResolvedDeployment {
+    /** Public URL of the Mastra server, or null when it could not be resolved without waking. */
+    url: string | null;
+    status: DeploymentStatus;
+    /** When the sandbox will auto-shutdown (when known). */
+    expiresAt?: Date;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+    logs(lines?: number): Promise<string>;
+}
+/**
+ * Resolve (and optionally wake) a sandbox deployment.
+ *
+ * With `wake: false` (default) the sandbox is not started: the URL is resolved
+ * only if the sandbox is already running in this process, otherwise
+ * `{ url: null, status: 'stopped' | 'unknown' }` is returned and the caller
+ * decides whether to wake.
+ *
+ * With `wake: true` the sandbox is started (providers resume by identity,
+ * e.g. name), the server is relaunched if it is not answering, and the
+ * deployment is returned once healthy.
+ */
+export declare function getDeployment(options: GetDeploymentOptions): Promise<ResolvedDeployment>;
+export interface CreateSandboxHandlerOptions {
+    /**
+     * Resolve the current sandbox URL. Called once, cached, and re-invoked when
+     * a forwarded request fails at the network level (e.g. the sandbox rotated
+     * its URL or went to sleep). Typically wraps `getDeployment`:
+     *
+     * ```typescript
+     * createSandboxHandler({
+     *   resolve: async () => {
+     *     const dep = await getDeployment({ sandbox, wake: true });
+     *     return dep.url!;
+     *   },
+     * });
+     * ```
+     */
+    resolve: () => Promise<string>;
+    /** Shared secret attached as the `x-mastra-sandbox-secret` header on forwarded requests. */
+    secret?: string;
+}
+/**
+ * Framework-free route-handler proxy (fetch `Request` → `Response`). Mount it
+ * as a catch-all API route; the browser only ever sees your own domain, and
+ * the sandbox URL (which rotates across resumes) stays server-side.
+ */
+export declare function createSandboxHandler(options: CreateSandboxHandlerOptions): (request: Request) => Promise<Response>;
+export interface CreateSandboxProxyOptions {
+    /** Edge Config item key that holds the current sandbox URL. */
+    key: string;
+    /**
+     * Edge Config connection string (`https://edge-config.vercel.com/ecfg_...?token=...`).
+     * Defaults to `process.env.EDGE_CONFIG`.
+     */
+    edgeConfig?: string;
+    /** Shared secret attached as the `x-mastra-sandbox-secret` header on the rewrite. */
+    secret?: string;
+}
+/**
+ * Next.js middleware helper for Tier 3 routing: reads the current sandbox URL
+ * from Edge Config (kept fresh by the deployer's `alias` option) and rewrites
+ * the request to it. Returns `undefined` when no URL is configured so the
+ * request falls through.
+ *
+ * ```typescript
+ * // middleware.ts
+ * export const middleware = createSandboxProxy({ key: 'my-preview' });
+ * export const config = { matcher: '/api/:path*' };
+ * ```
+ */
+export declare function createSandboxProxy(options: CreateSandboxProxyOptions): (request: Request) => Promise<Response | undefined>;
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAqB/D,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,EAAE,gBAAgB,CAAC;IAC1B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,wDAAwD;IACxD,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsE9F;AAMD,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;OAaG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAqElH;AAED,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAqCrD"}

package/dist/client/index.js

@@ -0,0 +1,171 @@
+import { c as launchServer, f as tailServerLog, l as resolveRemoteDir, o as getInfoSafe, p as waitForHealthy, s as killPreviousServer, t as DEFAULT_PORT } from "../shared-MNp_lXYR.js";
+import { supportsNetworking } from "@mastra/core/workspace";
+//#region src/client/index.ts
+/**
+* Runtime resolver + routing helpers for sandbox deployments.
+*
+* SERVER-ONLY. This module resolves sandbox URLs using provider credentials
+* (e.g. VERCEL_TOKEN) — importing it in the browser would ship those
+* credentials to the client. Use the proxy/handler patterns instead so the
+* browser only ever talks to your own domain.
+*/
+function assertServerOnly() {
+	if (typeof globalThis.window !== "undefined") throw new Error("@mastra/deployer-sandbox/client is server-only: resolving a sandbox requires provider credentials that must never reach the browser. Proxy requests through your own backend instead (see createSandboxHandler / createSandboxProxy).");
+}
+/**
+* Resolve (and optionally wake) a sandbox deployment.
+*
+* With `wake: false` (default) the sandbox is not started: the URL is resolved
+* only if the sandbox is already running in this process, otherwise
+* `{ url: null, status: 'stopped' | 'unknown' }` is returned and the caller
+* decides whether to wake.
+*
+* With `wake: true` the sandbox is started (providers resume by identity,
+* e.g. name), the server is relaunched if it is not answering, and the
+* deployment is returned once healthy.
+*/
+async function getDeployment(options) {
+	assertServerOnly();
+	const { sandbox, port = DEFAULT_PORT, wake = false, healthCheckPath = "/api", healthCheckTimeoutMs = 6e4 } = options;
+	const handle = (url, status, expiresAt) => ({
+		url,
+		status,
+		expiresAt,
+		stop: async () => {
+			await sandbox.stop?.();
+		},
+		destroy: async () => {
+			await sandbox.destroy?.();
+		},
+		logs: async (lines) => tailServerLog(sandbox, await resolveRemoteDir(sandbox, options.remoteDir), lines)
+	});
+	if (!wake) {
+		const url = supportsNetworking(sandbox) ? await sandbox.networking.getPortUrl(port) : null;
+		if (!url) return handle(null, "stopped");
+		return handle(url, await waitForHealthy(url, {
+			path: healthCheckPath,
+			timeoutMs: 3e3,
+			intervalMs: 1e3
+		}) ? "running" : "stopped");
+	}
+	await sandbox.start?.();
+	if (!supportsNetworking(sandbox)) throw new Error(`Sandbox provider "${sandbox.provider}" does not support networking (public port URLs).`);
+	const url = await sandbox.networking.getPortUrl(port);
+	if (!url) throw new Error(`Sandbox provider "${sandbox.provider}" did not expose a public URL for port ${port}. Make sure the port is declared when constructing the sandbox (e.g. \`ports: [${port}]\`).`);
+	let healthy = await waitForHealthy(url, {
+		path: healthCheckPath,
+		timeoutMs: 3e3,
+		intervalMs: 1e3
+	});
+	if (!healthy) {
+		const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);
+		await killPreviousServer(sandbox, remoteDir);
+		await launchServer(sandbox, remoteDir);
+		healthy = await waitForHealthy(url, {
+			path: healthCheckPath,
+			timeoutMs: healthCheckTimeoutMs,
+			intervalMs: 1e3
+		});
+	}
+	if (!healthy) {
+		const log = await resolveRemoteDir(sandbox, options.remoteDir).then((dir) => tailServerLog(sandbox, dir)).catch(() => "");
+		throw new Error(`Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` + (log ? `\n\nServer log:\n${log}` : ""));
+	}
+	return handle(url, "running", (await getInfoSafe(sandbox))?.timeoutAt);
+}
+/**
+* Framework-free route-handler proxy (fetch `Request` → `Response`). Mount it
+* as a catch-all API route; the browser only ever sees your own domain, and
+* the sandbox URL (which rotates across resumes) stays server-side.
+*/
+function createSandboxHandler(options) {
+	assertServerOnly();
+	let cachedUrl = null;
+	const forward = async (request, baseUrl) => {
+		const incoming = new URL(request.url);
+		const target = new URL(incoming.pathname + incoming.search, baseUrl);
+		const headers = new Headers(request.headers);
+		headers.delete("host");
+		if (options.secret) headers.set("x-mastra-sandbox-secret", options.secret);
+		const response = await fetch(target, {
+			method: request.method,
+			headers,
+			body: request.body,
+			duplex: "half",
+			redirect: "manual"
+		});
+		const location = response.headers.get("location");
+		if (location) {
+			const resolved = new URL(location, target);
+			if (resolved.origin === new URL(baseUrl).origin) {
+				const rewritten = new URL(resolved.pathname + resolved.search + resolved.hash, incoming.origin);
+				const responseHeaders = new Headers(response.headers);
+				responseHeaders.set("location", rewritten.toString());
+				return new Response(response.body, {
+					status: response.status,
+					statusText: response.statusText,
+					headers: responseHeaders
+				});
+			}
+		}
+		return response;
+	};
+	return async (request) => {
+		cachedUrl ??= options.resolve();
+		try {
+			return await forward(request, await cachedUrl);
+		} catch (error) {
+			cachedUrl = null;
+			if (![
+				"GET",
+				"HEAD",
+				"OPTIONS"
+			].includes(request.method)) throw error;
+			cachedUrl = options.resolve();
+			try {
+				return await forward(request, await cachedUrl);
+			} catch (retryError) {
+				cachedUrl = null;
+				throw retryError;
+			}
+		}
+	};
+}
+/**
+* Next.js middleware helper for Tier 3 routing: reads the current sandbox URL
+* from Edge Config (kept fresh by the deployer's `alias` option) and rewrites
+* the request to it. Returns `undefined` when no URL is configured so the
+* request falls through.
+*
+* ```typescript
+* // middleware.ts
+* export const middleware = createSandboxProxy({ key: 'my-preview' });
+* export const config = { matcher: '/api/:path*' };
+* ```
+*/
+function createSandboxProxy(options) {
+	assertServerOnly();
+	return async (request) => {
+		const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;
+		if (!connection) throw new Error("createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).");
+		const conn = new URL(connection);
+		const token = conn.searchParams.get("token");
+		const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);
+		const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });
+		if (!res.ok) return;
+		const sandboxUrl = await res.json();
+		if (typeof sandboxUrl !== "string" || !sandboxUrl) return;
+		const incoming = new URL(request.url);
+		const target = new URL(incoming.pathname + incoming.search, sandboxUrl);
+		const headers = new Headers({ "x-middleware-rewrite": target.toString() });
+		if (options.secret) {
+			headers.set("x-middleware-request-x-mastra-sandbox-secret", options.secret);
+			headers.set("x-middleware-override-headers", "x-mastra-sandbox-secret");
+		}
+		return new Response(null, { headers });
+	};
+}
+//#endregion
+export { createSandboxHandler, createSandboxProxy, getDeployment };
+
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/client/index.ts"],"sourcesContent":["/**\n * Runtime resolver + routing helpers for sandbox deployments.\n *\n * SERVER-ONLY. This module resolves sandbox URLs using provider credentials\n * (e.g. VERCEL_TOKEN) — importing it in the browser would ship those\n * credentials to the client. Use the proxy/handler patterns instead so the\n * browser only ever talks to your own domain.\n */\nimport { supportsNetworking } from '@mastra/core/workspace';\nimport type { WorkspaceSandbox } from '@mastra/core/workspace';\nimport {\n  DEFAULT_PORT,\n  getInfoSafe,\n  killPreviousServer,\n  launchServer,\n  resolveRemoteDir,\n  tailServerLog,\n  waitForHealthy,\n} from '../shared';\n\nfunction assertServerOnly(): void {\n  if (typeof (globalThis as { window?: unknown }).window !== 'undefined') {\n    throw new Error(\n      '@mastra/deployer-sandbox/client is server-only: resolving a sandbox requires provider credentials ' +\n        'that must never reach the browser. Proxy requests through your own backend instead ' +\n        '(see createSandboxHandler / createSandboxProxy).',\n    );\n  }\n}\n\nexport type DeploymentStatus = 'running' | 'stopped' | 'unknown';\n\nexport interface GetDeploymentOptions {\n  /**\n   * The sandbox to resolve. Provider construction is identity — e.g.\n   * `new VercelSandbox({ sandboxName: 'my-preview', ports: [4111] })` resolves\n   * the same sandbox from any process.\n   */\n  sandbox: WorkspaceSandbox;\n  /** Port the Mastra server listens on. Defaults to 4111. */\n  port?: number;\n  /**\n   * Wake the sandbox when it is not running. Waking starts (resumes) the\n   * sandbox and, only if the server is not answering, relaunches it from the\n   * recorded launch script — some providers (e.g. E2B) resume processes on\n   * wake, others (e.g. Vercel) restore just the filesystem. Defaults to false.\n   */\n  wake?: boolean;\n  /** Directory the app was deployed into. Defaults to `$HOME/mastra-app` resolved inside the sandbox. */\n  remoteDir?: string;\n  /** Path polled for health. Defaults to `/api`. */\n  healthCheckPath?: string;\n  /** Max time to wait for health after a wake, in ms. Defaults to 60000. */\n  healthCheckTimeoutMs?: number;\n}\n\nexport interface ResolvedDeployment {\n  /** Public URL of the Mastra server, or null when it could not be resolved without waking. */\n  url: string | null;\n  status: DeploymentStatus;\n  /** When the sandbox will auto-shutdown (when known). */\n  expiresAt?: Date;\n  stop(): Promise<void>;\n  destroy(): Promise<void>;\n  logs(lines?: number): Promise<string>;\n}\n\n/**\n * Resolve (and optionally wake) a sandbox deployment.\n *\n * With `wake: false` (default) the sandbox is not started: the URL is resolved\n * only if the sandbox is already running in this process, otherwise\n * `{ url: null, status: 'stopped' | 'unknown' }` is returned and the caller\n * decides whether to wake.\n *\n * With `wake: true` the sandbox is started (providers resume by identity,\n * e.g. name), the server is relaunched if it is not answering, and the\n * deployment is returned once healthy.\n */\nexport async function getDeployment(options: GetDeploymentOptions): Promise<ResolvedDeployment> {\n  assertServerOnly();\n\n  const {\n    sandbox,\n    port = DEFAULT_PORT,\n    wake = false,\n    healthCheckPath = '/api',\n    healthCheckTimeoutMs = 60_000,\n  } = options;\n\n  const handle = (url: string | null, status: DeploymentStatus, expiresAt?: Date): ResolvedDeployment => ({\n    url,\n    status,\n    expiresAt,\n    stop: async () => {\n      await sandbox.stop?.();\n    },\n    destroy: async () => {\n      await sandbox.destroy?.();\n    },\n    // Resolved lazily — reading logs requires a running sandbox anyway.\n    logs: async (lines?: number) => tailServerLog(sandbox, await resolveRemoteDir(sandbox, options.remoteDir), lines),\n  });\n\n  if (!wake) {\n    // Resolve without starting the sandbox (starting can resume billing).\n    const url = supportsNetworking(sandbox) ? await sandbox.networking.getPortUrl(port) : null;\n    if (!url) {\n      return handle(null, 'stopped');\n    }\n    const healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });\n    return handle(url, healthy ? 'running' : 'stopped');\n  }\n\n  await sandbox.start?.();\n\n  if (!supportsNetworking(sandbox)) {\n    throw new Error(`Sandbox provider \"${sandbox.provider}\" does not support networking (public port URLs).`);\n  }\n  const url = await sandbox.networking.getPortUrl(port);\n  if (!url) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" did not expose a public URL for port ${port}. ` +\n        `Make sure the port is declared when constructing the sandbox (e.g. \\`ports: [${port}]\\`).`,\n    );\n  }\n\n  // Some providers (e.g. Vercel) restore the filesystem but not processes on\n  // resume, while others (e.g. E2B) resume processes too — relaunch the server\n  // from the recorded launch script only when it is not answering.\n  let healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });\n  if (!healthy) {\n    const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);\n    await killPreviousServer(sandbox, remoteDir);\n    await launchServer(sandbox, remoteDir);\n    healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1_000 });\n  }\n  if (!healthy) {\n    const log = await resolveRemoteDir(sandbox, options.remoteDir)\n      .then(dir => tailServerLog(sandbox, dir))\n      .catch(() => '');\n    throw new Error(\n      `Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` +\n        (log ? `\\n\\nServer log:\\n${log}` : ''),\n    );\n  }\n\n  const info = await getInfoSafe(sandbox);\n  return handle(url, 'running', info?.timeoutAt);\n}\n\n// =============================================================================\n// Tier 3 helpers\n// =============================================================================\n\nexport interface CreateSandboxHandlerOptions {\n  /**\n   * Resolve the current sandbox URL. Called once, cached, and re-invoked when\n   * a forwarded request fails at the network level (e.g. the sandbox rotated\n   * its URL or went to sleep). Typically wraps `getDeployment`:\n   *\n   * ```typescript\n   * createSandboxHandler({\n   *   resolve: async () => {\n   *     const dep = await getDeployment({ sandbox, wake: true });\n   *     return dep.url!;\n   *   },\n   * });\n   * ```\n   */\n  resolve: () => Promise<string>;\n  /** Shared secret attached as the `x-mastra-sandbox-secret` header on forwarded requests. */\n  secret?: string;\n}\n\n/**\n * Framework-free route-handler proxy (fetch `Request` → `Response`). Mount it\n * as a catch-all API route; the browser only ever sees your own domain, and\n * the sandbox URL (which rotates across resumes) stays server-side.\n */\nexport function createSandboxHandler(options: CreateSandboxHandlerOptions): (request: Request) => Promise<Response> {\n  assertServerOnly();\n\n  let cachedUrl: Promise<string> | null = null;\n\n  const forward = async (request: Request, baseUrl: string): Promise<Response> => {\n    const incoming = new URL(request.url);\n    const target = new URL(incoming.pathname + incoming.search, baseUrl);\n\n    const headers = new Headers(request.headers);\n    headers.delete('host');\n    if (options.secret) {\n      headers.set('x-mastra-sandbox-secret', options.secret);\n    }\n\n    const response = await fetch(target, {\n      method: request.method,\n      headers,\n      body: request.body,\n      // duplex is required by Node's fetch for streamed request bodies\n      duplex: 'half',\n      redirect: 'manual',\n    } as RequestInit);\n\n    // Redirects are passed through manually — rewrite sandbox-host Locations\n    // onto the incoming origin so the rotating sandbox URL never reaches the\n    // browser (and subsequent requests keep flowing through this handler).\n    const location = response.headers.get('location');\n    if (location) {\n      const resolved = new URL(location, target);\n      if (resolved.origin === new URL(baseUrl).origin) {\n        const rewritten = new URL(resolved.pathname + resolved.search + resolved.hash, incoming.origin);\n        const responseHeaders = new Headers(response.headers);\n        responseHeaders.set('location', rewritten.toString());\n        return new Response(response.body, {\n          status: response.status,\n          statusText: response.statusText,\n          headers: responseHeaders,\n        });\n      }\n    }\n\n    return response;\n  };\n\n  return async (request: Request): Promise<Response> => {\n    cachedUrl ??= options.resolve();\n\n    try {\n      return await forward(request, await cachedUrl);\n    } catch (error) {\n      // Connection-level failure: the sandbox may have rotated its URL or gone\n      // to sleep. Drop the cached URL so the next request re-resolves, and\n      // retry once — but only for idempotent, bodyless methods. A failed\n      // connection doesn't prove a write never landed, and a streamed body is\n      // already consumed.\n      cachedUrl = null;\n      if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method)) {\n        throw error;\n      }\n      cachedUrl = options.resolve();\n      try {\n        return await forward(request, await cachedUrl);\n      } catch (retryError) {\n        cachedUrl = null;\n        throw retryError;\n      }\n    }\n  };\n}\n\nexport interface CreateSandboxProxyOptions {\n  /** Edge Config item key that holds the current sandbox URL. */\n  key: string;\n  /**\n   * Edge Config connection string (`https://edge-config.vercel.com/ecfg_...?token=...`).\n   * Defaults to `process.env.EDGE_CONFIG`.\n   */\n  edgeConfig?: string;\n  /** Shared secret attached as the `x-mastra-sandbox-secret` header on the rewrite. */\n  secret?: string;\n}\n\n/**\n * Next.js middleware helper for Tier 3 routing: reads the current sandbox URL\n * from Edge Config (kept fresh by the deployer's `alias` option) and rewrites\n * the request to it. Returns `undefined` when no URL is configured so the\n * request falls through.\n *\n * ```typescript\n * // middleware.ts\n * export const middleware = createSandboxProxy({ key: 'my-preview' });\n * export const config = { matcher: '/api/:path*' };\n * ```\n */\nexport function createSandboxProxy(\n  options: CreateSandboxProxyOptions,\n): (request: Request) => Promise<Response | undefined> {\n  // Reads (and would transmit) the Edge Config bearer token — same\n  // server-only contract as the rest of this module.\n  assertServerOnly();\n\n  return async (request: Request): Promise<Response | undefined> => {\n    const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;\n    if (!connection) {\n      throw new Error('createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).');\n    }\n\n    const conn = new URL(connection);\n    const token = conn.searchParams.get('token');\n    const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);\n\n    const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });\n    if (!res.ok) {\n      return undefined;\n    }\n    const sandboxUrl: unknown = await res.json();\n    if (typeof sandboxUrl !== 'string' || !sandboxUrl) {\n      return undefined;\n    }\n\n    const incoming = new URL(request.url);\n    const target = new URL(incoming.pathname + incoming.search, sandboxUrl);\n\n    // A Response with the x-middleware-rewrite header is how Next.js\n    // middleware expresses a rewrite (NextResponse.rewrite does the same) —\n    // this keeps the helper free of a next dependency.\n    const headers = new Headers({ 'x-middleware-rewrite': target.toString() });\n    if (options.secret) {\n      headers.set('x-middleware-request-x-mastra-sandbox-secret', options.secret);\n      headers.set('x-middleware-override-headers', 'x-mastra-sandbox-secret');\n    }\n    return new Response(null, { headers });\n  };\n}\n"],"mappings":"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"}