@mastra/deployer-sandbox 0.0.0-fix-thread-subscription-multi-instance-redis-streams-20260730204150

package/dist/index.js

@@ -0,0 +1,824 @@
+import { a as SERVER_SCRIPT, c as launchServer, d as shellQuote, f as tailServerLog, i as SERVER_PIDFILE, l as resolveRemoteDir, n as INSTALL_MARKER$1, o as getInfoSafe, p as waitForHealthy, r as SERVER_LOGFILE, s as killPreviousServer, t as DEFAULT_PORT, u as runInSandbox } from "./shared-C-piQAcU.js";
+import { access, mkdtemp, readFile, rm, writeFile } from "fs/promises";
+import { dirname, join, posix } from "path";
+import { fileURLToPath } from "url";
+import { Deployer } from "@mastra/deployer";
+import { copy } from "fs-extra/esm";
+import { execFile } from "child_process";
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import { tmpdir } from "os";
+import { promisify } from "util";
+import { supportsNetworking } from "@mastra/core/workspace";
+//#region src/alias.ts
+/**
+* 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.
+*/
+async function updateEdgeConfigAlias(options) {
+	const { token, teamId } = options;
+	if (!token) throw new Error("Updating the Edge Config alias requires a Vercel API token. Pass `alias.token`.");
+	const endpoint = new URL(`https://api.vercel.com/v1/edge-config/${options.edgeConfigId}/items`);
+	if (teamId) endpoint.searchParams.set("teamId", teamId);
+	const res = await fetch(endpoint, {
+		method: "PATCH",
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ items: [{
+			operation: "upsert",
+			key: options.key,
+			value: options.url
+		}] }),
+		signal: AbortSignal.timeout(3e4)
+	});
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new Error(`Failed to update Edge Config alias "${options.key}" (${res.status}): ${body}`);
+	}
+}
+//#endregion
+//#region src/engine.ts
+const execFileAsync = promisify(execFile);
+const noopLogger = {
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+};
+/** Max shell-command payload per chunk for the base64 upload fallback. */
+const UPLOAD_CHUNK_SIZE = 96e3;
+/**
+* Deploy a prebuilt Mastra server directory into any workspace sandbox that
+* supports networking. Provider-agnostic: only uses the core WorkspaceSandbox
+* contract (`executeCommand` + `networking`, with `writeFiles` / `processes`
+* as fast paths).
+*/
+async function deployToSandbox(options) {
+	const { sandbox, dir, port = DEFAULT_PORT, env = {}, studio = false, healthCheckPath = "/api", healthCheckTimeoutMs = 6e4, healthCheckIntervalMs = 1e3, installCommand = "npm install --omit=dev", logger = noopLogger } = options;
+	if (!existsSync(join(dir, "index.mjs"))) throw new Error(`No index.mjs found in "${dir}" — did the build succeed?`);
+	logger.info(`Starting ${sandbox.provider} sandbox...`);
+	await sandbox.start?.();
+	if (!supportsNetworking(sandbox)) throw new Error(`Sandbox provider "${sandbox.provider}" does not support networking (public port URLs), which is required for sandbox deploys.`);
+	if (!sandbox.executeCommand) throw new Error(`Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.`);
+	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}]\`).`);
+	const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);
+	const mergedEnv = { ...env };
+	if (studio && mergedEnv.MASTRA_STUDIO_PATH === void 0) mergedEnv.MASTRA_STUDIO_PATH = `${remoteDir}/studio`;
+	logger.info(`Uploading build output from ${dir}...`);
+	const tarball = await createTarball(dir);
+	logger.debug(`Tarball size: ${(tarball.length / 1024 / 1024).toFixed(2)} MB`);
+	const remoteTarball = `${remoteDir}/.deploy.tgz`;
+	await runInSandbox(sandbox, `mkdir -p ${shellQuote(remoteDir)}`);
+	await uploadFile(sandbox, remoteTarball, tarball);
+	await killPreviousServer(sandbox, remoteDir);
+	await runInSandbox(sandbox, `cd ${shellQuote(remoteDir)} && tar -xzf .deploy.tgz && rm -f .deploy.tgz`, { timeout: 12e4 });
+	const installHash = await hashInstallInputs(dir, installCommand);
+	const marker = `${remoteDir}/${INSTALL_MARKER$1}`;
+	const markerCheck = await runInSandbox(sandbox, `cat ${shellQuote(marker)} 2>/dev/null || true`, { allowFailure: true });
+	if (installHash && markerCheck.stdout.trim() === installHash) logger.info("Dependencies unchanged — skipping install.");
+	else {
+		logger.info(`Installing dependencies (${installCommand})...`);
+		await runInSandbox(sandbox, `cd ${shellQuote(remoteDir)} && ${installCommand}`, {
+			timeout: 6e5,
+			label: `install dependencies (${installCommand})`
+		});
+		if (installHash) await runInSandbox(sandbox, `printf '%s' ${shellQuote(installHash)} > ${shellQuote(marker)}`);
+	}
+	const launchScript = buildLaunchScript({
+		remoteDir,
+		port,
+		env: mergedEnv
+	});
+	await uploadFile(sandbox, `${remoteDir}/${SERVER_SCRIPT}`, Buffer.from(launchScript));
+	await runInSandbox(sandbox, `chmod 700 ${shellQuote(`${remoteDir}/${SERVER_SCRIPT}`)}`);
+	logger.info("Starting Mastra server...");
+	await launchServer(sandbox, remoteDir);
+	if (!await waitForHealthy(url, {
+		path: healthCheckPath,
+		timeoutMs: healthCheckTimeoutMs,
+		intervalMs: healthCheckIntervalMs
+	})) {
+		const log = await tailServerLog(sandbox, remoteDir).catch(() => "");
+		throw new Error(`Mastra server did not become healthy at ${url}${healthCheckPath} within ${healthCheckTimeoutMs}ms.` + (log ? `\n\nServer log:\n${log}` : "\n\n(no server log output captured)"));
+	}
+	const info = await getInfoSafe(sandbox);
+	return {
+		url,
+		sandboxId: info?.id ?? sandbox.id,
+		expiresAt: info?.timeoutAt,
+		stop: async () => {
+			await sandbox.stop?.();
+		},
+		destroy: async () => {
+			await sandbox.destroy?.();
+		},
+		logs: (lines) => tailServerLog(sandbox, remoteDir, lines)
+	};
+}
+/**
+* Build the POSIX launch script. Re-running the script restarts the server —
+* the wake path uses this after a snapshot resume (which restores the
+* filesystem but not processes).
+*/
+function buildLaunchScript(opts) {
+	const lines = ["#!/bin/sh", `cd ${shellQuote(opts.remoteDir)}`];
+	const env = {
+		MASTRA_AUTO_DETECT_URL: "true",
+		...opts.env,
+		PORT: String(opts.port),
+		MASTRA_HOST: "0.0.0.0"
+	};
+	for (const [key, value] of Object.entries(env)) {
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`Invalid environment variable name: "${key}"`);
+		lines.push(`export ${key}=${shellQuote(value)}`);
+	}
+	lines.push(`echo $$ > ${shellQuote(SERVER_PIDFILE)}`);
+	lines.push(`exec node index.mjs >> ${shellQuote(SERVER_LOGFILE)} 2>&1`);
+	return lines.join("\n") + "\n";
+}
+/** Create a gzipped tarball of the directory contents (excluding node_modules). */
+async function createTarball(dir) {
+	const tmp = await mkdtemp(join(tmpdir(), "mastra-sandbox-"));
+	const tarPath = join(tmp, "deploy.tgz");
+	try {
+		await execFileAsync("tar", [
+			"-czf",
+			tarPath,
+			"--exclude=node_modules",
+			"-C",
+			dir,
+			"."
+		]);
+		return await readFile(tarPath);
+	} finally {
+		await rm(tmp, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Upload a file into the sandbox. Uses the provider's native `writeFiles` fast
+* path when available, otherwise falls back to base64 chunks over
+* `executeCommand` — so `executeCommand` + `networking` is the minimum contract.
+*/
+async function uploadFile(sandbox, remotePath, content) {
+	if (sandbox.writeFiles) {
+		await sandbox.writeFiles([{
+			path: remotePath,
+			content
+		}]);
+		return;
+	}
+	const b64 = content.toString("base64");
+	const tmpPath = `${remotePath}.b64`;
+	await runInSandbox(sandbox, `rm -f ${shellQuote(tmpPath)}`);
+	for (let i = 0; i < b64.length; i += UPLOAD_CHUNK_SIZE) await runInSandbox(sandbox, `printf '%s' ${shellQuote(b64.slice(i, i + UPLOAD_CHUNK_SIZE))} >> ${shellQuote(tmpPath)}`, { label: `upload chunk to ${remotePath}` });
+	await runInSandbox(sandbox, `base64 -d ${shellQuote(tmpPath)} > ${shellQuote(remotePath)} && rm -f ${shellQuote(tmpPath)}`, { label: `decode upload at ${remotePath}` });
+}
+/** Lockfiles that, when present in the build output, participate in the install-skip hash. */
+const LOCKFILES = [
+	"package-lock.json",
+	"npm-shrinkwrap.json",
+	"pnpm-lock.yaml",
+	"yarn.lock",
+	"bun.lock"
+];
+/**
+* Hash everything that determines the outcome of a dependency install:
+* package.json, any bundled lockfile, and the install command itself. A
+* matching hash means the previous `node_modules` can be reused.
+*/
+async function hashInstallInputs(dir, installCommand) {
+	const hash = createHash("sha256");
+	try {
+		hash.update(await readFile(join(dir, "package.json")));
+	} catch {
+		return null;
+	}
+	for (const lockfile of LOCKFILES) {
+		let content;
+		try {
+			content = await readFile(join(dir, lockfile));
+		} catch {
+			continue;
+		}
+		hash.update(lockfile).update(content);
+	}
+	hash.update(installCommand);
+	return hash.digest("hex");
+}
+//#endregion
+//#region src/manifest.ts
+const MANIFEST_FILENAME = "sandbox-deployment.json";
+/** Write `sandbox-deployment.json` into the build output directory. */
+async function writeDeploymentManifest(outputDir, manifest) {
+	await writeFile(join(outputDir, MANIFEST_FILENAME), JSON.stringify(manifest, null, 2));
+}
+/** Read `sandbox-deployment.json` from the build output directory, or null when absent. */
+async function readDeploymentManifest(outputDir) {
+	let raw;
+	try {
+		raw = await readFile(join(outputDir, MANIFEST_FILENAME), "utf-8");
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	}
+	return JSON.parse(raw);
+}
+//#endregion
+//#region src/deployer.ts
+/**
+* Deploy a full Mastra server into any workspace sandbox that supports
+* networking (Vercel Sandbox, E2B, ...) and get a live public URL.
+*
+* Positioning: ephemeral environments — instant previews, PR/CI smoke deploys,
+* agent-built-app verification. Not production hosting.
+*
+* @example
+* ```typescript
+* import { SandboxDeployer } from '@mastra/deployer-sandbox';
+* import { VercelSandbox } from '@mastra/vercel';
+*
+* export const mastra = new Mastra({
+*   deployer: new SandboxDeployer({
+*     sandbox: new VercelSandbox({ sandboxName: 'my-preview', timeout: 3_600_000, ports: [4111] }),
+*   }),
+* });
+* ```
+*/
+var SandboxDeployer = class extends Deployer {
+	/** Sandbox deploys are push-style: `mastra build` runs `deploy()` after bundling. */
+	deployOnBuild = true;
+	sandbox;
+	port;
+	studio;
+	/** Explicit remote dir, when configured. The engine defaults to `$HOME/mastra-app` inside the sandbox. */
+	remoteDir;
+	env;
+	alias;
+	healthCheckTimeoutMs;
+	constructor(options) {
+		super({ name: "SANDBOX" });
+		this.sandbox = options.sandbox;
+		this.port = options.port ?? 4111;
+		this.studio = options.studio ?? true;
+		this.remoteDir = options.remoteDir;
+		this.env = options.env ?? {};
+		this.alias = options.alias;
+		this.healthCheckTimeoutMs = options.healthCheckTimeoutMs;
+	}
+	/**
+	* Merge all existing env files instead of only the first one (base behavior).
+	* Later files win in `loadEnvVars()`, so order least → most specific: a
+	* `.env.local` written by `vercel env pull` shouldn't shadow the `.env` that
+	* holds the app's own keys.
+	*/
+	async getEnvFiles() {
+		const candidates = [
+			".env",
+			".env.production",
+			".env.local"
+		];
+		const existing = [];
+		for (const file of candidates) try {
+			await access(file);
+			existing.push(file);
+		} catch {}
+		return existing;
+	}
+	async getUserBundlerOptions(mastraEntryFile, outputDirectory) {
+		return {
+			...await super.getUserBundlerOptions(mastraEntryFile, outputDirectory),
+			externals: true
+		};
+	}
+	getEntry() {
+		return `
+    // @ts-expect-error
+    import { scoreTracesWorkflow } from '@mastra/core/evals/scoreTraces';
+    import { mastra } from '#mastra';
+    import { createNodeServer, getToolExports } from '#server';
+    import { tools } from '#tools';
+
+    // @ts-expect-error
+    await createNodeServer(mastra, { tools: getToolExports(tools), studio: ${this.studio} });
+
+    const storage = mastra.getStorage();
+    if (storage) {
+      if (!storage.disableInit) {
+        storage.init();
+      }
+      mastra.__registerInternalWorkflow(scoreTracesWorkflow);
+    }
+    `;
+	}
+	async prepare(outputDirectory) {
+		await super.prepare(outputDirectory);
+		if (this.studio) {
+			const studioSource = join(dirname(dirname(fileURLToPath(import.meta.url))), "dist", "studio");
+			const studioServePath = join(outputDirectory, this.outputDir, "studio");
+			try {
+				await copy(studioSource, studioServePath, { overwrite: true });
+			} catch (err) {
+				throw new Error(`Failed to copy studio assets from "${studioSource}" to "${studioServePath}": ${err instanceof Error ? err.message : err}`);
+			}
+		}
+	}
+	async bundle(entryFile, outputDirectory, { toolsPaths, projectRoot }) {
+		return this._bundle(this.getEntry(), entryFile, {
+			outputDirectory,
+			projectRoot
+		}, toolsPaths);
+	}
+	/**
+	* Deploy the built output into the sandbox and wait for the server to come
+	* up on its public URL. Writes `sandbox-deployment.json` into the output
+	* directory and updates the Edge Config alias when configured.
+	*/
+	async deploy(outputDirectory) {
+		const dir = join(outputDirectory, this.outputDir);
+		const envVars = await this.loadEnvVars();
+		const env = {
+			...Object.fromEntries(envVars),
+			...this.env
+		};
+		if (envVars.size > 0) this.logger.warn("Environment variables from your .env file are injected into the remote sandbox. Anyone with access to the sandbox can read them.");
+		const deployment = await deployToSandbox({
+			sandbox: this.sandbox,
+			dir,
+			port: this.port,
+			env,
+			studio: this.studio,
+			remoteDir: this.remoteDir,
+			healthCheckTimeoutMs: this.healthCheckTimeoutMs,
+			logger: this.logger
+		});
+		await writeDeploymentManifest(dir, {
+			provider: this.sandbox.provider,
+			sandboxId: deployment.sandboxId,
+			url: deployment.url,
+			port: this.port,
+			deployedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			expiresAt: deployment.expiresAt?.toISOString()
+		});
+		if (this.alias) {
+			await updateEdgeConfigAlias({
+				...this.alias,
+				url: deployment.url
+			});
+			this.logger.info(`Edge Config alias "${this.alias.key}" now points at ${deployment.url}`);
+		}
+		this.logger.info(`Mastra server deployed: ${deployment.url}/api`);
+		if (this.studio) this.logger.info(`Studio: ${deployment.url}`);
+		if (deployment.expiresAt) this.logger.warn(`Sandbox expires at ${deployment.expiresAt.toISOString()} (provider runtime cap).`);
+	}
+};
+//#endregion
+//#region src/worker.ts
+const ARCHIVE = ".mastra-worker.tar.gz";
+const RUNTIME_DIR = ".mastra/executions";
+const INSTALL_MARKER = ".mastra-install-hash";
+const INSTALL_LOCK = ".mastra-install-lock";
+const ARTIFACT_LOCK = ".mastra-artifact-lock";
+const EXECUTION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const DEFAULT_INPUT_LIMIT = 16 * 1024 * 1024;
+const DEFAULT_OUTPUT_READ_LIMIT = 1024 * 1024;
+async function deployWorkerToSandbox(options) {
+	validateOptions(options);
+	const { sandbox, dir, executionId, command, mode = "worker", args = [], env = {}, workingDirectory = ".", installCommand = "npm install --omit=dev", startupTimeoutMs = 1e4, executionTimeoutMs, terminationGraceMs = 5e3, inputLimitBytes = DEFAULT_INPUT_LIMIT } = options;
+	const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);
+	const config = {
+		sandbox,
+		remoteDir,
+		command,
+		args,
+		env,
+		workingDirectory,
+		mode,
+		startupTimeoutMs,
+		executionTimeoutMs,
+		terminationGraceMs,
+		inputLimitBytes
+	};
+	const archive = `${remoteDir}/${ARCHIVE}`;
+	const tarball = await createTarball(dir);
+	const installHash = await hashInstallInputs(dir, installCommand);
+	const artifactLock = `${remoteDir}/${ARTIFACT_LOCK}`;
+	let artifactLockAcquired = false;
+	try {
+		await runInSandbox(sandbox, `mkdir -p ${shellQuote(remoteDir)}`);
+		await acquireLock(sandbox, artifactLock, options.installTimeoutMs, "worker artifact");
+		artifactLockAcquired = true;
+		await uploadFile(sandbox, archive, tarball);
+		await runInSandbox(sandbox, `tar -xzf ${shellQuote(archive)} -C ${shellQuote(remoteDir)} && rm -f ${shellQuote(archive)}`, { label: "extract worker artifact" });
+	} catch (error) {
+		throw workerPhaseError("upload", error);
+	} finally {
+		if (artifactLockAcquired) await runInSandbox(sandbox, `rm -rf ${shellQuote(artifactLock)}`, {
+			allowFailure: true,
+			label: "release worker artifact lock"
+		});
+	}
+	try {
+		await installDependencies(sandbox, remoteDir, installHash ?? void 0, installCommand, options.installTimeoutMs);
+	} catch (error) {
+		throw workerPhaseError("install", error);
+	}
+	return createExecution(config, executionId, options.input);
+}
+function validateOptions(options) {
+	if (!options.sandbox.executeCommand) throw new Error(`Sandbox provider "${options.sandbox.provider}" does not support executeCommand, which is required for worker deploys.`);
+	validateExecutionId(options.executionId);
+	if (!options.command || /[\0\r\n]/.test(options.command)) throw new Error("Worker command must be a non-empty executable path.");
+	if (options.args?.some((arg) => arg.includes("\0"))) throw new Error("Worker arguments must not contain NUL bytes.");
+	for (const key of Object.keys(options.env ?? {})) if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`Invalid worker environment variable name: ${key}`);
+	validateRelativePath(options.workingDirectory ?? ".", "workingDirectory");
+	validateInput(options.input);
+	for (const [name, value] of [
+		["inputLimitBytes", options.inputLimitBytes],
+		["startupTimeoutMs", options.startupTimeoutMs],
+		["executionTimeoutMs", options.executionTimeoutMs],
+		["terminationGraceMs", options.terminationGraceMs]
+	]) if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) throw new Error(`${name} must be greater than zero.`);
+}
+function validateRelativePath(value, label) {
+	if (!value || posix.isAbsolute(value) || posix.normalize(value).startsWith("..")) throw new Error(`Worker ${label} must stay within the deployed artifact root.`);
+}
+function validateInput(input) {
+	if (input?.type === "file") validateRelativePath(input.path, "input file path");
+}
+async function acquireLock(sandbox, lock, timeout, label) {
+	const timeoutMs = timeout ?? 6e5;
+	const attempts = Math.max(1, Math.ceil(timeoutMs / 1e3));
+	await runInSandbox(sandbox, [
+		"i=0",
+		`while ! mkdir ${shellQuote(lock)} 2>/dev/null; do`,
+		`  if [ "$i" -ge ${attempts} ]; then echo ${shellQuote(`${label} lock timeout`)} >&2; exit 1; fi`,
+		"  sleep 1; i=$((i + 1))",
+		"done"
+	].join("\n"), {
+		timeout: timeoutMs,
+		label: `acquire ${label} lock`
+	});
+}
+async function installDependencies(sandbox, remoteDir, installHash, installCommand, timeout) {
+	if (!installHash) return;
+	const marker = `${remoteDir}/${INSTALL_MARKER}`;
+	const lock = `${remoteDir}/${INSTALL_LOCK}`;
+	await acquireLock(sandbox, lock, timeout, "dependency install");
+	try {
+		await runInSandbox(sandbox, [
+			`current="$(cat ${shellQuote(marker)} 2>/dev/null || true)"`,
+			`if [ "$current" != ${shellQuote(installHash)} ]; then`,
+			`  cd ${shellQuote(remoteDir)} && ${installCommand}`,
+			`  printf %s ${shellQuote(installHash)} > ${shellQuote(`${marker}.tmp`)}`,
+			`  mv ${shellQuote(`${marker}.tmp`)} ${shellQuote(marker)}`,
+			"fi"
+		].join("\n"), {
+			timeout: timeout ?? 6e5,
+			label: "install worker dependencies"
+		});
+	} finally {
+		await runInSandbox(sandbox, `rm -rf ${shellQuote(lock)}`, {
+			allowFailure: true,
+			label: "release dependency install lock"
+		});
+	}
+}
+async function createExecution(config, executionId, input) {
+	validateExecutionId(executionId);
+	const paths = executionPaths(config.remoteDir, executionId);
+	await runInSandbox(config.sandbox, `mkdir -p ${shellQuote(`${config.remoteDir}/${RUNTIME_DIR}`)} && mkdir -m 700 ${shellQuote(paths.dir)}`, { label: "create worker execution namespace" });
+	const script = buildExecutionScript(config, paths, await stageInput(config, paths, input));
+	await uploadFile(config.sandbox, paths.script, Buffer.from(script));
+	await runInSandbox(config.sandbox, `chmod 700 ${shellQuote(paths.script)}`);
+	try {
+		await launchExecution(config.sandbox, paths);
+	} catch (error) {
+		await writeFailedStatus(config.sandbox, paths, executionId, "launch", error);
+		throw workerPhaseError("launch", error);
+	}
+	const startup = await waitForStartup(config, executionId, paths);
+	if (startup.state === "timed_out") await cancelExecution(config, executionId, paths, "startup");
+	if (startup.state === "failed" || startup.state === "timed_out" || startup.state === "provider_unavailable") throw new Error(`Worker ${startup.state} during startup${"message" in startup && startup.message ? `: ${startup.message}` : ""}.`);
+	const info = await getInfoSafe(config.sandbox);
+	return deployment(config, executionId, paths, info?.id ?? config.sandbox.id ?? "unknown", info?.timeoutAt);
+}
+function deployment(config, executionId, paths, sandboxId, expiresAt) {
+	return {
+		sandboxId,
+		executionId,
+		expiresAt,
+		status: (options) => readWorkerStatus(config.sandbox, executionId, paths, options),
+		readOutput: (stream, options) => readOutput(config.sandbox, executionId, paths, stream, options),
+		cancel: () => cancelExecution(config, executionId, paths),
+		stop: async () => {
+			if (!config.sandbox.stop) throw new Error(`Sandbox provider "${config.sandbox.provider}" does not support stop.`);
+			await config.sandbox.stop();
+		},
+		destroy: (options) => destroyWithRetry(config.sandbox, options),
+		relaunch: async (options) => {
+			if (options.executionId === executionId) throw new Error("Relaunch requires a new executionId.");
+			validateInput(options.input);
+			return createExecution(config, options.executionId, options.input);
+		}
+	};
+}
+async function stageInput(config, paths, input) {
+	if (!input) return void 0;
+	const data = typeof input.data === "string" ? Buffer.from(input.data) : Buffer.from(input.data);
+	if (data.byteLength > config.inputLimitBytes) throw new Error(`Worker input exceeds inputLimitBytes (${data.byteLength} > ${config.inputLimitBytes}).`);
+	const path = input.type === "stdin" ? paths.stdin : posix.resolve(config.remoteDir, input.path);
+	await uploadFile(config.sandbox, path, data);
+	await runInSandbox(config.sandbox, `chmod 600 ${shellQuote(path)}`);
+	return input.type === "stdin" ? path : void 0;
+}
+function buildExecutionScript(config, paths, stdinPath) {
+	const cwd = posix.resolve(config.remoteDir, config.workingDirectory);
+	const envPrefix = Object.entries(config.env).map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ");
+	const executable = [shellQuote(config.command), ...config.args.map(shellQuote)].join(" ");
+	const target = `${envPrefix ? `env ${envPrefix} ` : ""}${executable}`;
+	const graceAttempts = Math.max(1, Math.ceil(config.terminationGraceMs / 1e3));
+	const state = (value) => `tmp=${shellQuote(`${paths.status}.tmp.$$`)}; printf '%s\\n' ${shellQuote(value)} > "$tmp"; mv "$tmp" ${shellQuote(paths.status)};`;
+	return [
+		"#!/bin/sh",
+		`cd ${shellQuote(cwd)}`,
+		`execution_id=${shellQuote(paths.executionId)}`,
+		`stdout=${shellQuote(paths.stdout)}`,
+		`stderr=${shellQuote(paths.stderr)}`,
+		`pidfile=${shellQuote(paths.pid)}`,
+		`tokenfile=${shellQuote(paths.pidToken)}`,
+		`: > "$stdout"; : > "$stderr"`,
+		state(`starting|${paths.executionId}`),
+		`setsid sh -c ${shellQuote(`exec ${target}${stdinPath ? ` < ${shellQuote(stdinPath)}` : ""}`)} > "$stdout" 2> "$stderr" &`,
+		"child=$!",
+		"printf %s \"$child\" > \"$pidfile\"",
+		`if [ -r "/proc/$child/stat" ]; then awk '{print $22}' "/proc/$child/stat" > "$tokenfile"; else : > "$tokenfile"; fi`,
+		state(`running|${paths.executionId}`),
+		"cancelled=0",
+		`trap 'cancelled=1; kill -TERM -"$child" 2>/dev/null || kill -TERM "$child" 2>/dev/null || true' TERM INT`,
+		...config.executionTimeoutMs ? [`(sleep ${Math.max(1, Math.ceil(config.executionTimeoutMs / 1e3))}; if kill -0 "$child" 2>/dev/null; then ${state(`timed_out|${paths.executionId}|execution`)} kill -TERM -"$child" 2>/dev/null || kill -TERM "$child" 2>/dev/null || true; i=0; while kill -0 "$child" 2>/dev/null && [ "$i" -lt ${graceAttempts} ]; do sleep 1; i=$((i + 1)); done; kill -KILL -"$child" 2>/dev/null || kill -KILL "$child" 2>/dev/null || true; fi) &`, "watchdog=$!"] : [],
+		"wait \"$child\"",
+		"code=$?",
+		...config.executionTimeoutMs ? ["kill \"$watchdog\" 2>/dev/null || true"] : [],
+		`current="$(cat ${shellQuote(paths.status)} 2>/dev/null || true)"`,
+		`case "$current" in timed_out*) ;; *) if [ "$cancelled" -eq 1 ]; then ${state(`cancelled|${paths.executionId}|TERM`)} else signal=''; if [ "$code" -gt 128 ]; then signal="SIG$((code - 128))"; fi; tmp=${shellQuote(`${paths.status}.tmp.$$`)}; printf 'exited|%s|%s|%s\\n' "$execution_id" "$code" "$signal" > "$tmp"; mv "$tmp" ${shellQuote(paths.status)}; fi ;; esac`,
+		"rm -f \"$pidfile\" \"$tokenfile\"",
+		"exit \"$code\""
+	].join("\n");
+}
+async function launchExecution(sandbox, paths) {
+	await runInSandbox(sandbox, `setsid nohup sh ${shellQuote(paths.script)} >/dev/null 2>&1 & echo $!`, { label: "launch worker execution" });
+}
+async function waitForStartup(config, executionId, paths) {
+	const deadline = Date.now() + config.startupTimeoutMs;
+	while (Date.now() < deadline) {
+		const status = await readWorkerStatus(config.sandbox, executionId, paths);
+		if (status.state !== "unknown" && status.state !== "starting") return status;
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	return {
+		state: "timed_out",
+		executionId,
+		phase: "startup"
+	};
+}
+async function readWorkerStatus(sandbox, executionId, paths, options) {
+	const providerState = sandbox.status;
+	if (providerState === "destroyed" || providerState === "destroying") return {
+		state: "provider_unavailable",
+		executionId,
+		providerState
+	};
+	if (providerState === "stopped" || providerState === "stopping") {
+		if (!options?.wake || !sandbox.start) return {
+			state: "provider_unavailable",
+			executionId,
+			providerState
+		};
+		try {
+			await sandbox.start();
+		} catch (error) {
+			return {
+				state: "provider_unavailable",
+				executionId,
+				providerState,
+				message: errorMessage(error)
+			};
+		}
+	}
+	try {
+		const result = await runInSandbox(sandbox, [
+			`status="$(cat ${shellQuote(paths.status)} 2>/dev/null || true)"`,
+			`if [ -f ${shellQuote(paths.pid)} ]; then`,
+			`  pid="$(cat ${shellQuote(paths.pid)})"`,
+			`  expected="$(cat ${shellQuote(paths.pidToken)} 2>/dev/null || true)"`,
+			`  actual="$(if [ -r "/proc/$pid/stat" ]; then awk '{print $22}' "/proc/$pid/stat"; fi)"`,
+			`  if kill -0 "$pid" 2>/dev/null && { [ -z "$expected" ] || [ "$expected" = "$actual" ]; }; then echo "running|${executionId}"; exit 0; fi`,
+			`  if kill -0 "$pid" 2>/dev/null; then echo "stale|${executionId}"; exit 0; fi`,
+			"fi",
+			`if [ -n "$status" ]; then printf '%s\\n' "$status"; else echo "unknown|${executionId}"; fi`
+		].join("\n"), {
+			allowFailure: true,
+			label: "read worker status"
+		});
+		if (result.exitCode !== 0) return {
+			state: "provider_unavailable",
+			executionId,
+			providerState: sandbox.status,
+			message: result.stderr || result.stdout || "Sandbox status inspection failed."
+		};
+		return parseStatus(executionId, result.stdout.trim());
+	} catch (error) {
+		return {
+			state: "provider_unavailable",
+			executionId,
+			providerState: sandbox.status,
+			message: errorMessage(error)
+		};
+	}
+}
+function parseStatus(executionId, value) {
+	const [state, recordedId, first, second] = value.split("|");
+	if (recordedId !== executionId || state === "stale") return {
+		state: "unknown",
+		executionId
+	};
+	if (state === "starting") return {
+		state,
+		executionId
+	};
+	if (state === "running") return {
+		state,
+		executionId
+	};
+	if (state === "exited") {
+		const exitCode = Number(first);
+		return Number.isInteger(exitCode) ? {
+			state,
+			executionId,
+			exitCode,
+			...second ? { signal: second } : {}
+		} : {
+			state: "unknown",
+			executionId
+		};
+	}
+	if (state === "cancelled") return {
+		state,
+		executionId,
+		...first ? { signal: first } : {}
+	};
+	if (state === "timed_out" && (first === "startup" || first === "execution")) return {
+		state,
+		executionId,
+		phase: first
+	};
+	if (state === "failed" && (first === "upload" || first === "install" || first === "launch")) return {
+		state,
+		executionId,
+		phase: first,
+		message: second ?? ""
+	};
+	return {
+		state: "unknown",
+		executionId
+	};
+}
+async function cancelExecution(config, executionId, paths, timeoutPhase) {
+	const current = await readWorkerStatus(config.sandbox, executionId, paths);
+	if (current.state !== "running" && current.state !== "starting") return current;
+	const attempts = Math.max(1, Math.ceil(config.terminationGraceMs / 1e3));
+	const terminal = timeoutPhase ? `timed_out|${executionId}|startup` : `cancelled|${executionId}|TERM`;
+	await runInSandbox(config.sandbox, [
+		`pid="$(cat ${shellQuote(paths.pid)} 2>/dev/null || true)"`,
+		"[ -n \"$pid\" ] || exit 0",
+		`expected="$(cat ${shellQuote(paths.pidToken)} 2>/dev/null || true)"`,
+		`actual="$(if [ -r "/proc/$pid/stat" ]; then awk '{print $22}' "/proc/$pid/stat"; fi)"`,
+		"[ -n \"$expected\" ] && [ \"$expected\" != \"$actual\" ] && exit 0",
+		"kill -TERM -\"$pid\" 2>/dev/null || kill -TERM \"$pid\" 2>/dev/null || true",
+		`i=0; while kill -0 "$pid" 2>/dev/null && [ "$i" -lt ${attempts} ]; do sleep 1; i=$((i + 1)); done`,
+		"kill -KILL -\"$pid\" 2>/dev/null || kill -KILL \"$pid\" 2>/dev/null || true",
+		`tmp=${shellQuote(`${paths.status}.tmp.$$`)}; printf '%s\\n' ${shellQuote(terminal)} > "$tmp"; mv "$tmp" ${shellQuote(paths.status)}`,
+		`rm -f ${shellQuote(paths.pid)} ${shellQuote(paths.pidToken)}`
+	].join("\n"), {
+		allowFailure: true,
+		timeout: config.terminationGraceMs + 5e3,
+		label: "cancel worker execution"
+	});
+	return parseStatus(executionId, terminal);
+}
+async function readOutput(sandbox, executionId, paths, stream, options) {
+	const offset = Math.max(0, Math.floor(options?.offset ?? 0));
+	const maxBytes = Math.max(1, Math.floor(options?.maxBytes ?? DEFAULT_OUTPUT_READ_LIMIT));
+	const path = stream === "stdout" ? paths.stdout : paths.stderr;
+	try {
+		const result = await runInSandbox(sandbox, `size=$(wc -c < ${shellQuote(path)} 2>/dev/null || echo 0); printf '%s\\n' "$size"; tail -c +${offset + 1} ${shellQuote(path)} 2>/dev/null | head -c ${maxBytes} | base64`, {
+			allowFailure: true,
+			label: `read worker ${stream}`
+		});
+		if (result.exitCode !== 0) throw new Error(result.stderr || result.stdout || `Unable to read worker ${stream}.`);
+		const newline = result.stdout.indexOf("\n");
+		const totalBytes = Number((newline === -1 ? result.stdout : result.stdout.slice(0, newline)).trim()) || 0;
+		const encoded = newline === -1 ? "" : result.stdout.slice(newline + 1).replace(/\s/g, "");
+		const data = Buffer.from(encoded, "base64");
+		const nextOffset = offset + data.byteLength;
+		const status = await readWorkerStatus(sandbox, executionId, paths);
+		const terminal = [
+			"exited",
+			"cancelled",
+			"timed_out",
+			"failed"
+		].includes(status.state);
+		const interrupted = status.state === "provider_unavailable" || status.state === "unknown";
+		return {
+			stream,
+			data,
+			offset,
+			nextOffset,
+			totalBytes,
+			eof: terminal && nextOffset >= totalBytes,
+			truncated: nextOffset < totalBytes,
+			interrupted
+		};
+	} catch {
+		return {
+			stream,
+			data: /* @__PURE__ */ new Uint8Array(),
+			offset,
+			nextOffset: offset,
+			totalBytes: offset,
+			eof: false,
+			truncated: false,
+			interrupted: true
+		};
+	}
+}
+async function destroyWithRetry(sandbox, options) {
+	if (!sandbox.destroy) return {
+		state: "unsupported",
+		attempts: 0
+	};
+	const attempts = Math.max(1, Math.floor(options?.attempts ?? 3));
+	const delayMs = Math.max(0, Math.floor(options?.delayMs ?? 250));
+	let lastError;
+	for (let attempt = 1; attempt <= attempts; attempt++) try {
+		await sandbox.destroy();
+		return {
+			state: "destroyed",
+			attempts: attempt
+		};
+	} catch (error) {
+		lastError = error;
+		if (attempt < attempts) await new Promise((resolve) => setTimeout(resolve, delayMs));
+	}
+	return {
+		state: "exhausted",
+		attempts,
+		error: lastError
+	};
+}
+async function writeFailedStatus(sandbox, paths, executionId, phase, error) {
+	await writeStatus(sandbox, paths.status, `failed|${executionId}|${phase}|${sanitizeStatusValue(errorMessage(error))}`);
+}
+async function writeStatus(sandbox, path, value) {
+	await runInSandbox(sandbox, `tmp=${shellQuote(`${path}.tmp.$$`)}; printf '%s\\n' ${shellQuote(value)} > "$tmp"; mv "$tmp" ${shellQuote(path)}`, {
+		allowFailure: true,
+		label: "write worker status"
+	});
+}
+function executionPaths(remoteDir, executionId) {
+	const dir = `${remoteDir}/${RUNTIME_DIR}/${executionId}`;
+	return {
+		executionId,
+		dir,
+		script: `${dir}/launch.sh`,
+		pid: `${dir}/pid`,
+		pidToken: `${dir}/pid-start`,
+		status: `${dir}/status`,
+		stdin: `${dir}/stdin`,
+		stdout: `${dir}/stdout`,
+		stderr: `${dir}/stderr`
+	};
+}
+function validateExecutionId(executionId) {
+	if (!executionId || !EXECUTION_ID_PATTERN.test(executionId)) throw new Error("Worker executionId must contain only letters, numbers, dots, underscores, and hyphens.");
+}
+function workerPhaseError(phase, error) {
+	return new Error(`Worker ${phase} failed: ${errorMessage(error)}`, { cause: error });
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function sanitizeStatusValue(value) {
+	return value.replace(/[|\r\n]/g, " ").slice(0, 500);
+}
+//#endregion
+export { MANIFEST_FILENAME, SandboxDeployer, buildLaunchScript, deployToSandbox, deployWorkerToSandbox, readDeploymentManifest, updateEdgeConfigAlias, writeDeploymentManifest };
+
+//# sourceMappingURL=index.js.map