@mastra/deployer-sandbox 0.0.0 → 0.1.0-alpha.0

package/LICENSE.md

@@ -0,0 +1,30 @@
+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:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `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/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/chunk-CSXC6CZL.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+// src/shared.ts
+var REMOTE_DIR_NAME = "mastra-app";
+var DEFAULT_PORT = 4111;
+var SERVER_SCRIPT = ".mastra-server.sh";
+var SERVER_PIDFILE = ".mastra-server.pid";
+var SERVER_LOGFILE = ".mastra-server.log";
+var INSTALL_MARKER = ".mastra-install-hash";
+async function getInfoSafe(sandbox) {
+  try {
+    return await sandbox.getInfo?.();
+  } catch {
+    return void 0;
+  }
+}
+async function resolveRemoteDir(sandbox, remoteDir) {
+  if (remoteDir) return remoteDir;
+  const result = await runInSandbox(sandbox, `printf %s "\${HOME:-$(pwd)}"`, { allowFailure: true });
+  const base = result.stdout.trim();
+  if (!base) {
+    throw new Error("Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.");
+  }
+  return `${base}/${REMOTE_DIR_NAME}`;
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function runInSandbox(sandbox, script, opts) {
+  if (!sandbox.executeCommand) {
+    throw new Error(
+      `Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.`
+    );
+  }
+  const result = await sandbox.executeCommand(
+    "sh",
+    ["-c", script],
+    opts?.timeout ? { timeout: opts.timeout } : void 0
+  );
+  if (!result.success && !opts?.allowFailure) {
+    const what = opts?.label ?? truncate(script, 120);
+    throw new Error(
+      `Command failed inside sandbox (exit ${result.exitCode}): ${what}
+${truncate(result.stderr || result.stdout, 4e3)}`
+    );
+  }
+  return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
+}
+function truncate(value, max) {
+  return value.length > max ? `${value.slice(0, max)}\u2026 (truncated)` : value;
+}
+async function killPreviousServer(sandbox, remoteDir) {
+  const pidfile = shellQuote(`${remoteDir}/${SERVER_PIDFILE}`);
+  const script = [
+    `if [ -f ${pidfile} ]; then`,
+    `  pid="$(cat ${pidfile})"`,
+    `  kill "$pid" 2>/dev/null || true`,
+    // Wait up to ~5s for the old server to release the port, then force-kill.
+    `  i=0`,
+    `  while kill -0 "$pid" 2>/dev/null && [ "$i" -lt 50 ]; do sleep 0.1; i=$((i + 1)); done`,
+    `  kill -9 "$pid" 2>/dev/null || true`,
+    `  rm -f ${pidfile}`,
+    `fi`
+  ].join("\n");
+  await runInSandbox(sandbox, script, { allowFailure: true, timeout: 15e3 });
+}
+async function launchServer(sandbox, remoteDir) {
+  const script = `${remoteDir}/${SERVER_SCRIPT}`;
+  await runInSandbox(sandbox, `nohup sh ${shellQuote(script)} >/dev/null 2>&1 & echo launched`);
+}
+async function tailServerLog(sandbox, remoteDir, lines = 50) {
+  const logfile = `${remoteDir}/${SERVER_LOGFILE}`;
+  const result = await runInSandbox(
+    sandbox,
+    `tail -n ${Math.floor(lines)} ${shellQuote(logfile)} 2>/dev/null || true`,
+    {
+      allowFailure: true
+    }
+  );
+  return result.stdout;
+}
+async function waitForHealthy(url, opts = {}) {
+  const path = opts.path ?? "/api";
+  const timeoutMs = opts.timeoutMs ?? 6e4;
+  const intervalMs = opts.intervalMs ?? 1e3;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(new URL(path, url), { signal: AbortSignal.timeout(intervalMs * 5) });
+      const providerError = res.status === 410 || res.headers.has("x-vercel-error");
+      if (res.status < 500 && !providerError) {
+        return true;
+      }
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return false;
+}
+
+exports.DEFAULT_PORT = DEFAULT_PORT;
+exports.INSTALL_MARKER = INSTALL_MARKER;
+exports.SERVER_LOGFILE = SERVER_LOGFILE;
+exports.SERVER_PIDFILE = SERVER_PIDFILE;
+exports.SERVER_SCRIPT = SERVER_SCRIPT;
+exports.getInfoSafe = getInfoSafe;
+exports.killPreviousServer = killPreviousServer;
+exports.launchServer = launchServer;
+exports.resolveRemoteDir = resolveRemoteDir;
+exports.runInSandbox = runInSandbox;
+exports.shellQuote = shellQuote;
+exports.tailServerLog = tailServerLog;
+exports.waitForHealthy = waitForHealthy;
+//# sourceMappingURL=chunk-CSXC6CZL.cjs.map
+//# sourceMappingURL=chunk-CSXC6CZL.cjs.map

package/dist/chunk-CSXC6CZL.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared.ts"],"names":[],"mappings":"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","file":"chunk-CSXC6CZL.cjs","sourcesContent":["import type { SandboxInfo, WorkspaceSandbox } from '@mastra/core/workspace';\n\n/** Directory name (under the sandbox user's home) that the app is deployed into by default. */\nexport const REMOTE_DIR_NAME = 'mastra-app';\n/** Default port the Mastra server listens on. */\nexport const DEFAULT_PORT = 4111;\n/** Launch script written into the remote dir. Re-running it restarts the server (e.g. after a wake). */\nexport const SERVER_SCRIPT = '.mastra-server.sh';\n/** Pidfile written by the launch script. */\nexport const SERVER_PIDFILE = '.mastra-server.pid';\n/** Server log file inside the remote dir. */\nexport const SERVER_LOGFILE = '.mastra-server.log';\n/** Marker recording the package.json hash of the last completed dependency install. */\nexport const INSTALL_MARKER = '.mastra-install-hash';\n\n/** getInfo may be sync or async, and may throw — normalize to `undefined` on failure. */\nexport async function getInfoSafe(sandbox: WorkspaceSandbox): Promise<SandboxInfo | undefined> {\n  try {\n    return await sandbox.getInfo?.();\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Resolve the directory the app is (or will be) deployed into. Defaults to\n * `$HOME/mastra-app` resolved inside the sandbox — home directories persist\n * across snapshot stop/resume on providers that support it, unlike `/tmp`.\n * The sandbox must be running.\n */\nexport async function resolveRemoteDir(sandbox: WorkspaceSandbox, remoteDir?: string): Promise<string> {\n  if (remoteDir) return remoteDir;\n  const result = await runInSandbox(sandbox, `printf %s \"\\${HOME:-$(pwd)}\"`, { allowFailure: true });\n  const base = result.stdout.trim();\n  if (!base) {\n    throw new Error('Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.');\n  }\n  return `${base}/${REMOTE_DIR_NAME}`;\n}\n\n/** Single-quote a value for POSIX shells. */\nexport function shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n\n/** Run a shell script string inside the sandbox and throw on failure. */\nexport async function runInSandbox(\n  sandbox: WorkspaceSandbox,\n  script: string,\n  opts?: {\n    allowFailure?: boolean;\n    timeout?: number;\n    /** Safe description used in error messages instead of the script itself. */\n    label?: string;\n  },\n): Promise<{ stdout: string; stderr: string; exitCode: number }> {\n  if (!sandbox.executeCommand) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" does not support executeCommand, which is required for sandbox deploys.`,\n    );\n  }\n  // Run via `sh -c` (argv style): providers pass `command` straight to their\n  // exec API as an executable, so a raw script string with spaces would fail.\n  const result = await sandbox.executeCommand(\n    'sh',\n    ['-c', script],\n    opts?.timeout ? { timeout: opts.timeout } : undefined,\n  );\n  if (!result.success && !opts?.allowFailure) {\n    // Never echo the full script back: it can contain secrets (env values)\n    // or entire base64 upload chunks. Use the label or a bounded excerpt.\n    const what = opts?.label ?? truncate(script, 120);\n    throw new Error(\n      `Command failed inside sandbox (exit ${result.exitCode}): ${what}\\n${truncate(result.stderr || result.stdout, 4_000)}`,\n    );\n  }\n  return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };\n}\n\nfunction truncate(value: string, max: number): string {\n  return value.length > max ? `${value.slice(0, max)}… (truncated)` : value;\n}\n\n/**\n * Kill the previously launched server (if any) using its pidfile, waiting for\n * the process to exit (bounded, then SIGKILL) so the replacement never races\n * the old server for the port. Safe when nothing is running.\n */\nexport async function killPreviousServer(sandbox: WorkspaceSandbox, remoteDir: string): Promise<void> {\n  const pidfile = shellQuote(`${remoteDir}/${SERVER_PIDFILE}`);\n  const script = [\n    `if [ -f ${pidfile} ]; then`,\n    `  pid=\"$(cat ${pidfile})\"`,\n    `  kill \"$pid\" 2>/dev/null || true`,\n    // Wait up to ~5s for the old server to release the port, then force-kill.\n    `  i=0`,\n    `  while kill -0 \"$pid\" 2>/dev/null && [ \"$i\" -lt 50 ]; do sleep 0.1; i=$((i + 1)); done`,\n    `  kill -9 \"$pid\" 2>/dev/null || true`,\n    `  rm -f ${pidfile}`,\n    `fi`,\n  ].join('\\n');\n  await runInSandbox(sandbox, script, { allowFailure: true, timeout: 15_000 });\n}\n\n/**\n * Launch (or relaunch) the server by running the recorded launch script,\n * detached via nohup. Deliberately NOT `processes.spawn()`: provider process\n * handles follow the command's log stream, which would keep the calling\n * process's event loop alive for as long as the server runs. The server's\n * lifecycle is managed through its pidfile instead.\n */\nexport async function launchServer(sandbox: WorkspaceSandbox, remoteDir: string): Promise<void> {\n  const script = `${remoteDir}/${SERVER_SCRIPT}`;\n  await runInSandbox(sandbox, `nohup sh ${shellQuote(script)} >/dev/null 2>&1 & echo launched`);\n}\n\n/** Tail the server log from inside the sandbox. */\nexport async function tailServerLog(sandbox: WorkspaceSandbox, remoteDir: string, lines = 50): Promise<string> {\n  const logfile = `${remoteDir}/${SERVER_LOGFILE}`;\n  const result = await runInSandbox(\n    sandbox,\n    `tail -n ${Math.floor(lines)} ${shellQuote(logfile)} 2>/dev/null || true`,\n    {\n      allowFailure: true,\n    },\n  );\n  return result.stdout;\n}\n\n/**\n * Poll `${url}${path}` until the server responds. Any HTTP status below 500\n * counts as \"the server is up\" — gateway errors (502/503) mean nothing is\n * listening on the port, and 410 is what some providers (e.g. Vercel) return\n * from their edge when the sandbox itself is stopped.\n */\nexport async function waitForHealthy(\n  url: string,\n  opts: { path?: string; timeoutMs?: number; intervalMs?: number } = {},\n): Promise<boolean> {\n  const path = opts.path ?? '/api';\n  const timeoutMs = opts.timeoutMs ?? 60_000;\n  const intervalMs = opts.intervalMs ?? 1_000;\n  const deadline = Date.now() + timeoutMs;\n\n  while (Date.now() < deadline) {\n    try {\n      const res = await fetch(new URL(path, url), { signal: AbortSignal.timeout(intervalMs * 5) });\n      // A provider-edge error header means the response came from the sandbox\n      // infrastructure (stopped/unreachable VM), not from the Mastra server.\n      const providerError = res.status === 410 || res.headers.has('x-vercel-error');\n      if (res.status < 500 && !providerError) {\n        return true;\n      }\n    } catch {\n      // Not reachable yet.\n    }\n    await new Promise(resolve => setTimeout(resolve, intervalMs));\n  }\n  return false;\n}\n"]}

package/dist/chunk-Z636GNUQ.js

@@ -0,0 +1,101 @@
+// src/shared.ts
+var REMOTE_DIR_NAME = "mastra-app";
+var DEFAULT_PORT = 4111;
+var SERVER_SCRIPT = ".mastra-server.sh";
+var SERVER_PIDFILE = ".mastra-server.pid";
+var SERVER_LOGFILE = ".mastra-server.log";
+var INSTALL_MARKER = ".mastra-install-hash";
+async function getInfoSafe(sandbox) {
+  try {
+    return await sandbox.getInfo?.();
+  } catch {
+    return void 0;
+  }
+}
+async function resolveRemoteDir(sandbox, remoteDir) {
+  if (remoteDir) return remoteDir;
+  const result = await runInSandbox(sandbox, `printf %s "\${HOME:-$(pwd)}"`, { allowFailure: true });
+  const base = result.stdout.trim();
+  if (!base) {
+    throw new Error("Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.");
+  }
+  return `${base}/${REMOTE_DIR_NAME}`;
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function runInSandbox(sandbox, script, opts) {
+  if (!sandbox.executeCommand) {
+    throw new Error(
+      `Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.`
+    );
+  }
+  const result = await sandbox.executeCommand(
+    "sh",
+    ["-c", script],
+    opts?.timeout ? { timeout: opts.timeout } : void 0
+  );
+  if (!result.success && !opts?.allowFailure) {
+    const what = opts?.label ?? truncate(script, 120);
+    throw new Error(
+      `Command failed inside sandbox (exit ${result.exitCode}): ${what}
+${truncate(result.stderr || result.stdout, 4e3)}`
+    );
+  }
+  return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };
+}
+function truncate(value, max) {
+  return value.length > max ? `${value.slice(0, max)}\u2026 (truncated)` : value;
+}
+async function killPreviousServer(sandbox, remoteDir) {
+  const pidfile = shellQuote(`${remoteDir}/${SERVER_PIDFILE}`);
+  const script = [
+    `if [ -f ${pidfile} ]; then`,
+    `  pid="$(cat ${pidfile})"`,
+    `  kill "$pid" 2>/dev/null || true`,
+    // Wait up to ~5s for the old server to release the port, then force-kill.
+    `  i=0`,
+    `  while kill -0 "$pid" 2>/dev/null && [ "$i" -lt 50 ]; do sleep 0.1; i=$((i + 1)); done`,
+    `  kill -9 "$pid" 2>/dev/null || true`,
+    `  rm -f ${pidfile}`,
+    `fi`
+  ].join("\n");
+  await runInSandbox(sandbox, script, { allowFailure: true, timeout: 15e3 });
+}
+async function launchServer(sandbox, remoteDir) {
+  const script = `${remoteDir}/${SERVER_SCRIPT}`;
+  await runInSandbox(sandbox, `nohup sh ${shellQuote(script)} >/dev/null 2>&1 & echo launched`);
+}
+async function tailServerLog(sandbox, remoteDir, lines = 50) {
+  const logfile = `${remoteDir}/${SERVER_LOGFILE}`;
+  const result = await runInSandbox(
+    sandbox,
+    `tail -n ${Math.floor(lines)} ${shellQuote(logfile)} 2>/dev/null || true`,
+    {
+      allowFailure: true
+    }
+  );
+  return result.stdout;
+}
+async function waitForHealthy(url, opts = {}) {
+  const path = opts.path ?? "/api";
+  const timeoutMs = opts.timeoutMs ?? 6e4;
+  const intervalMs = opts.intervalMs ?? 1e3;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(new URL(path, url), { signal: AbortSignal.timeout(intervalMs * 5) });
+      const providerError = res.status === 410 || res.headers.has("x-vercel-error");
+      if (res.status < 500 && !providerError) {
+        return true;
+      }
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return false;
+}
+
+export { DEFAULT_PORT, INSTALL_MARKER, SERVER_LOGFILE, SERVER_PIDFILE, SERVER_SCRIPT, getInfoSafe, killPreviousServer, launchServer, resolveRemoteDir, runInSandbox, shellQuote, tailServerLog, waitForHealthy };
+//# sourceMappingURL=chunk-Z636GNUQ.js.map
+//# sourceMappingURL=chunk-Z636GNUQ.js.map

package/dist/chunk-Z636GNUQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shared.ts"],"names":[],"mappings":";AAGO,IAAM,eAAA,GAAkB,YAAA;AAExB,IAAM,YAAA,GAAe;AAErB,IAAM,aAAA,GAAgB;AAEtB,IAAM,cAAA,GAAiB;AAEvB,IAAM,cAAA,GAAiB;AAEvB,IAAM,cAAA,GAAiB;AAG9B,eAAsB,YAAY,OAAA,EAA6D;AAC7F,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,QAAQ,OAAA,IAAU;AAAA,EACjC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,MAAA;AAAA,EACT;AACF;AAQA,eAAsB,gBAAA,CAAiB,SAA2B,SAAA,EAAqC;AACrG,EAAA,IAAI,WAAW,OAAO,SAAA;AACtB,EAAA,MAAM,MAAA,GAAS,MAAM,YAAA,CAAa,OAAA,EAAS,gCAAgC,EAAE,YAAA,EAAc,MAAM,CAAA;AACjG,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,MAAA,CAAO,IAAA,EAAK;AAChC,EAAA,IAAI,CAAC,IAAA,EAAM;AACT,IAAA,MAAM,IAAI,MAAM,4EAA4E,CAAA;AAAA,EAC9F;AACA,EAAA,OAAO,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,eAAe,CAAA,CAAA;AACnC;AAGO,SAAS,WAAW,KAAA,EAAuB;AAChD,EAAA,OAAO,CAAA,CAAA,EAAI,KAAA,CAAM,OAAA,CAAQ,IAAA,EAAM,OAAO,CAAC,CAAA,CAAA,CAAA;AACzC;AAGA,eAAsB,YAAA,CACpB,OAAA,EACA,MAAA,EACA,IAAA,EAM+D;AAC/D,EAAA,IAAI,CAAC,QAAQ,cAAA,EAAgB;AAC3B,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,kBAAA,EAAqB,QAAQ,QAAQ,CAAA,yEAAA;AAAA,KACvC;AAAA,EACF;AAGA,EAAA,MAAM,MAAA,GAAS,MAAM,OAAA,CAAQ,cAAA;AAAA,IAC3B,IAAA;AAAA,IACA,CAAC,MAAM,MAAM,CAAA;AAAA,IACb,MAAM,OAAA,GAAU,EAAE,OAAA,EAAS,IAAA,CAAK,SAAQ,GAAI;AAAA,GAC9C;AACA,EAAA,IAAI,CAAC,MAAA,CAAO,OAAA,IAAW,CAAC,MAAM,YAAA,EAAc;AAG1C,IAAA,MAAM,IAAA,GAAO,IAAA,EAAM,KAAA,IAAS,QAAA,CAAS,QAAQ,GAAG,CAAA;AAChD,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,oCAAA,EAAuC,MAAA,CAAO,QAAQ,CAAA,GAAA,EAAM,IAAI;AAAA,EAAK,SAAS,MAAA,CAAO,MAAA,IAAU,MAAA,CAAO,MAAA,EAAQ,GAAK,CAAC,CAAA;AAAA,KACtH;AAAA,EACF;AACA,EAAA,OAAO,EAAE,QAAQ,MAAA,CAAO,MAAA,EAAQ,QAAQ,MAAA,CAAO,MAAA,EAAQ,QAAA,EAAU,MAAA,CAAO,QAAA,EAAS;AACnF;AAEA,SAAS,QAAA,CAAS,OAAe,GAAA,EAAqB;AACpD,EAAA,OAAO,KAAA,CAAM,SAAS,GAAA,GAAM,CAAA,EAAG,MAAM,KAAA,CAAM,CAAA,EAAG,GAAG,CAAC,CAAA,kBAAA,CAAA,GAAkB,KAAA;AACtE;AAOA,eAAsB,kBAAA,CAAmB,SAA2B,SAAA,EAAkC;AACpG,EAAA,MAAM,UAAU,UAAA,CAAW,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,cAAc,CAAA,CAAE,CAAA;AAC3D,EAAA,MAAM,MAAA,GAAS;AAAA,IACb,WAAW,OAAO,CAAA,QAAA,CAAA;AAAA,IAClB,gBAAgB,OAAO,CAAA,EAAA,CAAA;AAAA,IACvB,CAAA,iCAAA,CAAA;AAAA;AAAA,IAEA,CAAA,KAAA,CAAA;AAAA,IACA,CAAA,uFAAA,CAAA;AAAA,IACA,CAAA,oCAAA,CAAA;AAAA,IACA,WAAW,OAAO,CAAA,CAAA;AAAA,IAClB,CAAA,EAAA;AAAA,GACF,CAAE,KAAK,IAAI,CAAA;AACX,EAAA,MAAM,YAAA,CAAa,SAAS,MAAA,EAAQ,EAAE,cAAc,IAAA,EAAM,OAAA,EAAS,MAAQ,CAAA;AAC7E;AASA,eAAsB,YAAA,CAAa,SAA2B,SAAA,EAAkC;AAC9F,EAAA,MAAM,MAAA,GAAS,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,aAAa,CAAA,CAAA;AAC5C,EAAA,MAAM,aAAa,OAAA,EAAS,CAAA,SAAA,EAAY,UAAA,CAAW,MAAM,CAAC,CAAA,gCAAA,CAAkC,CAAA;AAC9F;AAGA,eAAsB,aAAA,CAAc,OAAA,EAA2B,SAAA,EAAmB,KAAA,GAAQ,EAAA,EAAqB;AAC7G,EAAA,MAAM,OAAA,GAAU,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,cAAc,CAAA,CAAA;AAC9C,EAAA,MAAM,SAAS,MAAM,YAAA;AAAA,IACnB,OAAA;AAAA,IACA,CAAA,QAAA,EAAW,KAAK,KAAA,CAAM,KAAK,CAAC,CAAA,CAAA,EAAI,UAAA,CAAW,OAAO,CAAC,CAAA,oBAAA,CAAA;AAAA,IACnD;AAAA,MACE,YAAA,EAAc;AAAA;AAChB,GACF;AACA,EAAA,OAAO,MAAA,CAAO,MAAA;AAChB;AAQA,eAAsB,cAAA,CACpB,GAAA,EACA,IAAA,GAAmE,EAAC,EAClD;AAClB,EAAA,MAAM,IAAA,GAAO,KAAK,IAAA,IAAQ,MAAA;AAC1B,EAAA,MAAM,SAAA,GAAY,KAAK,SAAA,IAAa,GAAA;AACpC,EAAA,MAAM,UAAA,GAAa,KAAK,UAAA,IAAc,GAAA;AACtC,EAAA,MAAM,QAAA,GAAW,IAAA,CAAK,GAAA,EAAI,GAAI,SAAA;AAE9B,EAAA,OAAO,IAAA,CAAK,GAAA,EAAI,GAAI,QAAA,EAAU;AAC5B,IAAA,IAAI;AACF,MAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,IAAI,IAAI,IAAA,EAAM,GAAG,CAAA,EAAG,EAAE,QAAQ,WAAA,CAAY,OAAA,CAAQ,UAAA,GAAa,CAAC,GAAG,CAAA;AAG3F,MAAA,MAAM,gBAAgB,GAAA,CAAI,MAAA,KAAW,OAAO,GAAA,CAAI,OAAA,CAAQ,IAAI,gBAAgB,CAAA;AAC5E,MAAA,IAAI,GAAA,CAAI,MAAA,GAAS,GAAA,IAAO,CAAC,aAAA,EAAe;AACtC,QAAA,OAAO,IAAA;AAAA,MACT;AAAA,IACF,CAAA,CAAA,MAAQ;AAAA,IAER;AACA,IAAA,MAAM,IAAI,OAAA,CAAQ,CAAA,OAAA,KAAW,UAAA,CAAW,OAAA,EAAS,UAAU,CAAC,CAAA;AAAA,EAC9D;AACA,EAAA,OAAO,KAAA;AACT","file":"chunk-Z636GNUQ.js","sourcesContent":["import type { SandboxInfo, WorkspaceSandbox } from '@mastra/core/workspace';\n\n/** Directory name (under the sandbox user's home) that the app is deployed into by default. */\nexport const REMOTE_DIR_NAME = 'mastra-app';\n/** Default port the Mastra server listens on. */\nexport const DEFAULT_PORT = 4111;\n/** Launch script written into the remote dir. Re-running it restarts the server (e.g. after a wake). */\nexport const SERVER_SCRIPT = '.mastra-server.sh';\n/** Pidfile written by the launch script. */\nexport const SERVER_PIDFILE = '.mastra-server.pid';\n/** Server log file inside the remote dir. */\nexport const SERVER_LOGFILE = '.mastra-server.log';\n/** Marker recording the package.json hash of the last completed dependency install. */\nexport const INSTALL_MARKER = '.mastra-install-hash';\n\n/** getInfo may be sync or async, and may throw — normalize to `undefined` on failure. */\nexport async function getInfoSafe(sandbox: WorkspaceSandbox): Promise<SandboxInfo | undefined> {\n  try {\n    return await sandbox.getInfo?.();\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Resolve the directory the app is (or will be) deployed into. Defaults to\n * `$HOME/mastra-app` resolved inside the sandbox — home directories persist\n * across snapshot stop/resume on providers that support it, unlike `/tmp`.\n * The sandbox must be running.\n */\nexport async function resolveRemoteDir(sandbox: WorkspaceSandbox, remoteDir?: string): Promise<string> {\n  if (remoteDir) return remoteDir;\n  const result = await runInSandbox(sandbox, `printf %s \"\\${HOME:-$(pwd)}\"`, { allowFailure: true });\n  const base = result.stdout.trim();\n  if (!base) {\n    throw new Error('Could not resolve the sandbox home directory. Pass `remoteDir` explicitly.');\n  }\n  return `${base}/${REMOTE_DIR_NAME}`;\n}\n\n/** Single-quote a value for POSIX shells. */\nexport function shellQuote(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`;\n}\n\n/** Run a shell script string inside the sandbox and throw on failure. */\nexport async function runInSandbox(\n  sandbox: WorkspaceSandbox,\n  script: string,\n  opts?: {\n    allowFailure?: boolean;\n    timeout?: number;\n    /** Safe description used in error messages instead of the script itself. */\n    label?: string;\n  },\n): Promise<{ stdout: string; stderr: string; exitCode: number }> {\n  if (!sandbox.executeCommand) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" does not support executeCommand, which is required for sandbox deploys.`,\n    );\n  }\n  // Run via `sh -c` (argv style): providers pass `command` straight to their\n  // exec API as an executable, so a raw script string with spaces would fail.\n  const result = await sandbox.executeCommand(\n    'sh',\n    ['-c', script],\n    opts?.timeout ? { timeout: opts.timeout } : undefined,\n  );\n  if (!result.success && !opts?.allowFailure) {\n    // Never echo the full script back: it can contain secrets (env values)\n    // or entire base64 upload chunks. Use the label or a bounded excerpt.\n    const what = opts?.label ?? truncate(script, 120);\n    throw new Error(\n      `Command failed inside sandbox (exit ${result.exitCode}): ${what}\\n${truncate(result.stderr || result.stdout, 4_000)}`,\n    );\n  }\n  return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode };\n}\n\nfunction truncate(value: string, max: number): string {\n  return value.length > max ? `${value.slice(0, max)}… (truncated)` : value;\n}\n\n/**\n * Kill the previously launched server (if any) using its pidfile, waiting for\n * the process to exit (bounded, then SIGKILL) so the replacement never races\n * the old server for the port. Safe when nothing is running.\n */\nexport async function killPreviousServer(sandbox: WorkspaceSandbox, remoteDir: string): Promise<void> {\n  const pidfile = shellQuote(`${remoteDir}/${SERVER_PIDFILE}`);\n  const script = [\n    `if [ -f ${pidfile} ]; then`,\n    `  pid=\"$(cat ${pidfile})\"`,\n    `  kill \"$pid\" 2>/dev/null || true`,\n    // Wait up to ~5s for the old server to release the port, then force-kill.\n    `  i=0`,\n    `  while kill -0 \"$pid\" 2>/dev/null && [ \"$i\" -lt 50 ]; do sleep 0.1; i=$((i + 1)); done`,\n    `  kill -9 \"$pid\" 2>/dev/null || true`,\n    `  rm -f ${pidfile}`,\n    `fi`,\n  ].join('\\n');\n  await runInSandbox(sandbox, script, { allowFailure: true, timeout: 15_000 });\n}\n\n/**\n * Launch (or relaunch) the server by running the recorded launch script,\n * detached via nohup. Deliberately NOT `processes.spawn()`: provider process\n * handles follow the command's log stream, which would keep the calling\n * process's event loop alive for as long as the server runs. The server's\n * lifecycle is managed through its pidfile instead.\n */\nexport async function launchServer(sandbox: WorkspaceSandbox, remoteDir: string): Promise<void> {\n  const script = `${remoteDir}/${SERVER_SCRIPT}`;\n  await runInSandbox(sandbox, `nohup sh ${shellQuote(script)} >/dev/null 2>&1 & echo launched`);\n}\n\n/** Tail the server log from inside the sandbox. */\nexport async function tailServerLog(sandbox: WorkspaceSandbox, remoteDir: string, lines = 50): Promise<string> {\n  const logfile = `${remoteDir}/${SERVER_LOGFILE}`;\n  const result = await runInSandbox(\n    sandbox,\n    `tail -n ${Math.floor(lines)} ${shellQuote(logfile)} 2>/dev/null || true`,\n    {\n      allowFailure: true,\n    },\n  );\n  return result.stdout;\n}\n\n/**\n * Poll `${url}${path}` until the server responds. Any HTTP status below 500\n * counts as \"the server is up\" — gateway errors (502/503) mean nothing is\n * listening on the port, and 410 is what some providers (e.g. Vercel) return\n * from their edge when the sandbox itself is stopped.\n */\nexport async function waitForHealthy(\n  url: string,\n  opts: { path?: string; timeoutMs?: number; intervalMs?: number } = {},\n): Promise<boolean> {\n  const path = opts.path ?? '/api';\n  const timeoutMs = opts.timeoutMs ?? 60_000;\n  const intervalMs = opts.intervalMs ?? 1_000;\n  const deadline = Date.now() + timeoutMs;\n\n  while (Date.now() < deadline) {\n    try {\n      const res = await fetch(new URL(path, url), { signal: AbortSignal.timeout(intervalMs * 5) });\n      // A provider-edge error header means the response came from the sandbox\n      // infrastructure (stopped/unreachable VM), not from the Mastra server.\n      const providerError = res.status === 410 || res.headers.has('x-vercel-error');\n      if (res.status < 500 && !providerError) {\n        return true;\n      }\n    } catch {\n      // Not reachable yet.\n    }\n    await new Promise(resolve => setTimeout(resolve, intervalMs));\n  }\n  return false;\n}\n"]}

package/dist/client/index.cjs

@@ -0,0 +1,159 @@
+'use strict';
+
+var chunkCSXC6CZL_cjs = require('../chunk-CSXC6CZL.cjs');
+var workspace = require('@mastra/core/workspace');
+
+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)."
+    );
+  }
+}
+async function getDeployment(options) {
+  assertServerOnly();
+  const {
+    sandbox,
+    port = chunkCSXC6CZL_cjs.DEFAULT_PORT,
+    wake = false,
+    healthCheckPath = "/api",
+    healthCheckTimeoutMs = 6e4
+  } = options;
+  const handle = (url2, status, expiresAt) => ({
+    url: url2,
+    status,
+    expiresAt,
+    stop: async () => {
+      await sandbox.stop?.();
+    },
+    destroy: async () => {
+      await sandbox.destroy?.();
+    },
+    // Resolved lazily — reading logs requires a running sandbox anyway.
+    logs: async (lines) => chunkCSXC6CZL_cjs.tailServerLog(sandbox, await chunkCSXC6CZL_cjs.resolveRemoteDir(sandbox, options.remoteDir), lines)
+  });
+  if (!wake) {
+    const url2 = workspace.supportsNetworking(sandbox) ? await sandbox.networking.getPortUrl(port) : null;
+    if (!url2) {
+      return handle(null, "stopped");
+    }
+    const healthy2 = await chunkCSXC6CZL_cjs.waitForHealthy(url2, { path: healthCheckPath, timeoutMs: 3e3, intervalMs: 1e3 });
+    return handle(url2, healthy2 ? "running" : "stopped");
+  }
+  await sandbox.start?.();
+  if (!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 chunkCSXC6CZL_cjs.waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3e3, intervalMs: 1e3 });
+  if (!healthy) {
+    const remoteDir = await chunkCSXC6CZL_cjs.resolveRemoteDir(sandbox, options.remoteDir);
+    await chunkCSXC6CZL_cjs.killPreviousServer(sandbox, remoteDir);
+    await chunkCSXC6CZL_cjs.launchServer(sandbox, remoteDir);
+    healthy = await chunkCSXC6CZL_cjs.waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1e3 });
+  }
+  if (!healthy) {
+    const log = await chunkCSXC6CZL_cjs.resolveRemoteDir(sandbox, options.remoteDir).then((dir) => chunkCSXC6CZL_cjs.tailServerLog(sandbox, dir)).catch(() => "");
+    throw new Error(
+      `Woke sandbox but the Mastra server did not become healthy at ${url}${healthCheckPath}.` + (log ? `
+
+Server log:
+${log}` : "")
+    );
+  }
+  const info = await chunkCSXC6CZL_cjs.getInfoSafe(sandbox);
+  return handle(url, "running", info?.timeoutAt);
+}
+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 is required by Node's fetch for streamed request bodies
+      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;
+      }
+    }
+  };
+}
+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 void 0;
+    }
+    const sandboxUrl = await res.json();
+    if (typeof sandboxUrl !== "string" || !sandboxUrl) {
+      return void 0;
+    }
+    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 });
+  };
+}
+
+exports.createSandboxHandler = createSandboxHandler;
+exports.createSandboxProxy = createSandboxProxy;
+exports.getDeployment = getDeployment;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts"],"names":["DEFAULT_PORT","url","tailServerLog","resolveRemoteDir","supportsNetworking","healthy","waitForHealthy","killPreviousServer","launchServer","getInfoSafe"],"mappings":"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","file":"index.cjs","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"]}

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"}