@mastra/deployer-sandbox 0.1.3 → 0.2.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @mastra/deployer-sandbox
 
+## 0.2.0-alpha.1
+
+### Minor Changes
+
+- Run isolated non-HTTP workers with bounded input, separate byte-preserving output streams, cancellation, relaunch, and cleanup controls. ([#19641](https://github.com/mastra-ai/mastra/pull/19641))
+
+  ```ts
+  import { deployWorkerToSandbox } from '@mastra/deployer-sandbox';
+
+  const worker = await deployWorkerToSandbox({
+    sandbox,
+    dir: './dist/worker',
+    executionId: 'job-1',
+    command: 'node',
+    args: ['index.mjs'],
+    input: { type: 'stdin', data: request },
+  });
+
+  const stdout = await worker.readOutput('stdout');
+  await worker.cancel();
+  const retry = await worker.relaunch({ executionId: 'job-2' });
+  await retry.destroy();
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`55c9e24`](https://github.com/mastra-ai/mastra/commit/55c9e248c27c1d72b5bb7e94ea6b8a3999eee49f), [`07f5b4b`](https://github.com/mastra-ai/mastra/commit/07f5b4ba9d608d88865030732e580298296adf99)]:
+  - @mastra/core@1.55.0-alpha.2
+  - @mastra/deployer@1.55.0-alpha.2
+
+## 0.1.4-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`3f472b4`](https://github.com/mastra-ai/mastra/commit/3f472b468892a1ff14ccb43cc0343b86f7d8fd7d), [`35b929b`](https://github.com/mastra-ai/mastra/commit/35b929b7abc3d20d85c7985880960ac2d04a6c86), [`9b3626a`](https://github.com/mastra-ai/mastra/commit/9b3626aeb1d16fcd34b0a8e94c114ddb80a3b240)]:
+  - @mastra/core@1.55.0-alpha.0
+  - @mastra/deployer@1.55.0-alpha.0
+
 ## 0.1.3
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,8 @@
 # @mastra/deployer-sandbox
 
-Deploy a full Mastra server into any workspace sandbox that supports networking — and get a live public URL in seconds.
+Deploy a full Mastra server or a non-HTTP worker into a workspace sandbox.
 
-Works with any `WorkspaceSandbox` provider that implements the core `networking` capability (Vercel Sandbox, E2B, Daytona, ...). Positioning: **ephemeral environments** — instant previews, PR/CI smoke deploys, agent-built-app verification, multi-tenant untrusted instances. Not production hosting.
+Server deployments work with any `WorkspaceSandbox` provider that implements `executeCommand` and `networking`. Worker deployments require only `executeCommand`; they do not allocate ports, ingress, public URLs, or HTTP health checks. Positioning: **ephemeral environments** — instant previews, PR/CI smoke deploys, isolated jobs, agent-built-app verification, and multi-tenant untrusted instances. Not production hosting.
 
 ## Usage
 
@@ -59,7 +59,39 @@ const deployment = await deployToSandbox({ sandbox, dir: '.mastra/output', port:
 console.log(deployment.url);
 ```
 
-Pass `wake: true` to resume a stopped sandbox before returning — useful in a route handler that fronts the sandbox. If the server isn't healthy after the resume (some providers restore the filesystem but not processes), the wake relaunches it:
+## Non-HTTP workers and custom commands
+
+Deploy a prebuilt worker artifact without requiring networking. The command, arguments, working directory, and install command are trusted developer-authored inputs. The deployer preserves the artifact layout rather than assuming a Mastra-specific entrypoint or process protocol.
+
+```typescript
+import { deployWorkerToSandbox } from '@mastra/deployer-sandbox';
+import { VercelSandbox } from '@mastra/vercel';
+
+const worker = await deployWorkerToSandbox({
+  sandbox: new VercelSandbox({ sandboxName: 'experiment-worker' }),
+  dir: '.mastra/experiment-worker',
+  executionId: 'attempt-1',
+  mode: 'job',
+  command: 'node',
+  args: ['index.mjs'],
+  env: { JOB_ID: 'job-123' },
+  input: { type: 'stdin', data: JSON.stringify({ requestId: 'request-123' }) },
+  startupTimeoutMs: 10_000,
+  executionTimeoutMs: 15 * 60_000,
+  terminationGraceMs: 5_000,
+});
+
+const stdout = await worker.readOutput('stdout', { offset: 0, maxBytes: 64 * 1024 });
+const stderr = await worker.readOutput('stderr', { offset: 0, maxBytes: 64 * 1024 });
+console.log(await worker.status(), stdout, stderr);
+await worker.cancel();
+```
+
+Each caller-provided execution ID gets isolated runtime state. Input is bounded and may be delivered through stdin or staged at an artifact-relative file path. Stdout and stderr remain separate and are read as raw bytes with offsets, EOF, truncation, and interruption metadata; the deployer does not interpret their protocol.
+
+Dependency installs are serialized and cached using the artifact's `package.json`, supported lockfiles, and install command. `cancel()` sends TERM and then KILL to the process group when necessary. `stop()` snapshot-stops the provider sandbox without assuming process preservation. `relaunch({ executionId })` starts the recorded command under a new execution identity. `destroy()` retries permanent sandbox deletion and returns a typed result.
+
+Pass `wake: true` to resume a stopped server sandbox before returning — useful in a route handler that fronts the sandbox. If the server isn't healthy after the resume (some providers restore the filesystem but not processes), the wake relaunches it:
 
 ```typescript
 import { getDeployment } from '@mastra/deployer-sandbox/client';

package/dist/engine.d.ts

@@ -1,3 +1,4 @@
+import type { WorkspaceSandbox } from '@mastra/core/workspace';
 import type { DeployToSandboxOptions, SandboxDeployment } from './types.js';
 /**
  * Deploy a prebuilt Mastra server directory into any workspace sandbox that
@@ -16,4 +17,18 @@ export declare function buildLaunchScript(opts: {
     port: number;
     env: Record<string, string>;
 }): string;
+/** Create a gzipped tarball of the directory contents (excluding node_modules). */
+export declare function createTarball(dir: string): Promise<Buffer>;
+/**
+ * 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.
+ */
+export declare function uploadFile(sandbox: WorkspaceSandbox, remotePath: string, content: Buffer): Promise<void>;
+/**
+ * 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.
+ */
+export declare function hashInstallInputs(dir: string, installCommand: string): Promise<string | null>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,sBAAsB,EAAuB,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAc9F;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+HjG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAyBhH"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAgB/D,OAAO,KAAK,EAAE,sBAAsB,EAAuB,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAc9F;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+HjG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAyBhH;AAED,mFAAmF;AACnF,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAShE;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB9G;AAKD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmBnG"}

package/dist/index.cjs

@@ -380,10 +380,451 @@ var SandboxDeployer = class extends _mastra_deployer.Deployer {
 	}
 };
 //#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 require_shared.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 require_shared.runInSandbox(sandbox, `mkdir -p ${require_shared.shellQuote(remoteDir)}`);
+		await acquireLock(sandbox, artifactLock, options.installTimeoutMs, "worker artifact");
+		artifactLockAcquired = true;
+		await uploadFile(sandbox, archive, tarball);
+		await require_shared.runInSandbox(sandbox, `tar -xzf ${require_shared.shellQuote(archive)} -C ${require_shared.shellQuote(remoteDir)} && rm -f ${require_shared.shellQuote(archive)}`, { label: "extract worker artifact" });
+	} catch (error) {
+		throw workerPhaseError("upload", error);
+	} finally {
+		if (artifactLockAcquired) await require_shared.runInSandbox(sandbox, `rm -rf ${require_shared.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 || path.posix.isAbsolute(value) || path.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 require_shared.runInSandbox(sandbox, [
+		"i=0",
+		`while ! mkdir ${require_shared.shellQuote(lock)} 2>/dev/null; do`,
+		`  if [ "$i" -ge ${attempts} ]; then echo ${require_shared.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 require_shared.runInSandbox(sandbox, [
+			`current="$(cat ${require_shared.shellQuote(marker)} 2>/dev/null || true)"`,
+			`if [ "$current" != ${require_shared.shellQuote(installHash)} ]; then`,
+			`  cd ${require_shared.shellQuote(remoteDir)} && ${installCommand}`,
+			`  printf %s ${require_shared.shellQuote(installHash)} > ${require_shared.shellQuote(`${marker}.tmp`)}`,
+			`  mv ${require_shared.shellQuote(`${marker}.tmp`)} ${require_shared.shellQuote(marker)}`,
+			"fi"
+		].join("\n"), {
+			timeout: timeout ?? 6e5,
+			label: "install worker dependencies"
+		});
+	} finally {
+		await require_shared.runInSandbox(sandbox, `rm -rf ${require_shared.shellQuote(lock)}`, {
+			allowFailure: true,
+			label: "release dependency install lock"
+		});
+	}
+}
+async function createExecution(config, executionId, input) {
+	validateExecutionId(executionId);
+	const paths = executionPaths(config.remoteDir, executionId);
+	await require_shared.runInSandbox(config.sandbox, `mkdir -p ${require_shared.shellQuote(`${config.remoteDir}/${RUNTIME_DIR}`)} && mkdir -m 700 ${require_shared.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 require_shared.runInSandbox(config.sandbox, `chmod 700 ${require_shared.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 require_shared.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$1 = input.type === "stdin" ? paths.stdin : path.posix.resolve(config.remoteDir, input.path);
+	await uploadFile(config.sandbox, path$1, data);
+	await require_shared.runInSandbox(config.sandbox, `chmod 600 ${require_shared.shellQuote(path$1)}`);
+	return input.type === "stdin" ? path$1 : void 0;
+}
+function buildExecutionScript(config, paths, stdinPath) {
+	const cwd = path.posix.resolve(config.remoteDir, config.workingDirectory);
+	const envPrefix = Object.entries(config.env).map(([key, value]) => `${key}=${require_shared.shellQuote(value)}`).join(" ");
+	const executable = [require_shared.shellQuote(config.command), ...config.args.map(require_shared.shellQuote)].join(" ");
+	const target = `${envPrefix ? `env ${envPrefix} ` : ""}${executable}`;
+	const graceAttempts = Math.max(1, Math.ceil(config.terminationGraceMs / 1e3));
+	const state = (value) => `tmp=${require_shared.shellQuote(`${paths.status}.tmp.$$`)}; printf '%s\\n' ${require_shared.shellQuote(value)} > "$tmp"; mv "$tmp" ${require_shared.shellQuote(paths.status)};`;
+	return [
+		"#!/bin/sh",
+		`cd ${require_shared.shellQuote(cwd)}`,
+		`execution_id=${require_shared.shellQuote(paths.executionId)}`,
+		`stdout=${require_shared.shellQuote(paths.stdout)}`,
+		`stderr=${require_shared.shellQuote(paths.stderr)}`,
+		`pidfile=${require_shared.shellQuote(paths.pid)}`,
+		`tokenfile=${require_shared.shellQuote(paths.pidToken)}`,
+		`: > "$stdout"; : > "$stderr"`,
+		state(`starting|${paths.executionId}`),
+		`setsid sh -c ${require_shared.shellQuote(`exec ${target}${stdinPath ? ` < ${require_shared.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 ${require_shared.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=${require_shared.shellQuote(`${paths.status}.tmp.$$`)}; printf 'exited|%s|%s|%s\\n' "$execution_id" "$code" "$signal" > "$tmp"; mv "$tmp" ${require_shared.shellQuote(paths.status)}; fi ;; esac`,
+		"rm -f \"$pidfile\" \"$tokenfile\"",
+		"exit \"$code\""
+	].join("\n");
+}
+async function launchExecution(sandbox, paths) {
+	await require_shared.runInSandbox(sandbox, `setsid nohup sh ${require_shared.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 require_shared.runInSandbox(sandbox, [
+			`status="$(cat ${require_shared.shellQuote(paths.status)} 2>/dev/null || true)"`,
+			`if [ -f ${require_shared.shellQuote(paths.pid)} ]; then`,
+			`  pid="$(cat ${require_shared.shellQuote(paths.pid)})"`,
+			`  expected="$(cat ${require_shared.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 require_shared.runInSandbox(config.sandbox, [
+		`pid="$(cat ${require_shared.shellQuote(paths.pid)} 2>/dev/null || true)"`,
+		"[ -n \"$pid\" ] || exit 0",
+		`expected="$(cat ${require_shared.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=${require_shared.shellQuote(`${paths.status}.tmp.$$`)}; printf '%s\\n' ${require_shared.shellQuote(terminal)} > "$tmp"; mv "$tmp" ${require_shared.shellQuote(paths.status)}`,
+		`rm -f ${require_shared.shellQuote(paths.pid)} ${require_shared.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$2 = stream === "stdout" ? paths.stdout : paths.stderr;
+	try {
+		const result = await require_shared.runInSandbox(sandbox, `size=$(wc -c < ${require_shared.shellQuote(path$2)} 2>/dev/null || echo 0); printf '%s\\n' "$size"; tail -c +${offset + 1} ${require_shared.shellQuote(path$2)} 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$3, value) {
+	await require_shared.runInSandbox(sandbox, `tmp=${require_shared.shellQuote(`${path$3}.tmp.$$`)}; printf '%s\\n' ${require_shared.shellQuote(value)} > "$tmp"; mv "$tmp" ${require_shared.shellQuote(path$3)}`, {
+		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
 exports.MANIFEST_FILENAME = MANIFEST_FILENAME;
 exports.SandboxDeployer = SandboxDeployer;
 exports.buildLaunchScript = buildLaunchScript;
 exports.deployToSandbox = deployToSandbox;
+exports.deployWorkerToSandbox = deployWorkerToSandbox;
 exports.readDeploymentManifest = readDeploymentManifest;
 exports.updateEdgeConfigAlias = updateEdgeConfigAlias;
 exports.writeDeploymentManifest = writeDeploymentManifest;