@cloudflare/sandbox 0.13.0-next.681.1 → 0.13.0-next.709.1

package/dist/extensions-CFB2xHqY.js

@@ -0,0 +1,1023 @@
+import { i as ErrorCode, n as getSuggestion, r as getHttpStatus } from "./errors-CXR0xBpw.js";
+import { d as ProcessExitedBeforeLogError, f as ProcessExitedBeforeReadyError, g as ProcessWaitTimeoutError, l as ProcessAbortedError, m as ProcessReadyTimeoutError, t as createErrorFromResponse, tt as SandboxError, u as ProcessError } from "./errors-QYlSkVGz.js";
+import { n as EXTENSION_TARBALL_REQUIRED } from "./dist-Duor5GbS.js";
+import { RpcTarget } from "cloudflare:workers";
+
+//#region src/container-control/rpc-error.ts
+/** Error translation for container control RPC calls. */
+function isLocalSandboxError(error) {
+	if (!("errorResponse" in error)) return false;
+	const response = error.errorResponse;
+	return typeof response?.code === "string" && Object.hasOwn(ErrorCode, response.code) && typeof response.message === "string" && typeof response.httpStatus === "number" && typeof response.timestamp === "string" && typeof response.context === "object" && response.context !== null;
+}
+function translateRPCError(error, context = {}) {
+	if (error instanceof SandboxError) throw error;
+	if (error instanceof Error) {
+		if (isLocalSandboxError(error)) throw error;
+		const propagated = error;
+		if (typeof propagated.code === "string" && Object.hasOwn(ErrorCode, propagated.code)) {
+			const code = propagated.code;
+			const context$1 = propagated.details && typeof propagated.details === "object" ? propagated.details : {};
+			throw createErrorFromResponse({
+				code,
+				message: error.message,
+				context: context$1,
+				httpStatus: getHttpStatus(code),
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		let payload;
+		try {
+			payload = JSON.parse(error.message);
+		} catch {}
+		if (payload && typeof payload.code === "string" && typeof payload.message === "string") throw createErrorFromResponse({
+			code: payload.code,
+			message: payload.message,
+			context: payload.context ?? {},
+			httpStatus: getHttpStatus(payload.code),
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const transportResponse = buildTransportErrorResponse(error);
+		throw createErrorFromResponse((context.translateTransportErrorsAsInterruptions === false ? null : buildInterruptedOperationResponse(transportResponse, context)) ?? transportResponse, { cause: error });
+	}
+	throw createErrorFromResponse(buildTransportErrorResponse(new Error(String(error))), { cause: error });
+}
+function buildTransportErrorResponse(error) {
+	const message = error.message;
+	const errorName = error.name;
+	let kind = "unknown";
+	let closeCode;
+	let closeReason;
+	if (errorName === "TypeError") kind = "invalid_frame";
+	else if (errorName === "SyntaxError") kind = "protocol_error";
+	else {
+		const peerCloseMatch = message.match(/^Peer closed WebSocket: (\d+) ?(.*)$/);
+		if (peerCloseMatch) {
+			kind = "peer_closed";
+			closeCode = Number(peerCloseMatch[1]);
+			closeReason = peerCloseMatch[2] || void 0;
+		} else if (message === "WebSocket connection failed.") kind = "connection_failed";
+		else if (message.startsWith("WebSocket upgrade failed")) kind = "upgrade_failed";
+		else if (message === "No WebSocket in upgrade response") kind = "upgrade_failed";
+		else if (message === "RPC session was shut down by disposing the main stub" || message === "RPC was canceled because the RpcPromise was disposed.") kind = "session_disposed";
+	}
+	const context = {
+		kind,
+		originalMessage: message,
+		errorName,
+		...closeCode !== void 0 ? { closeCode } : {},
+		...closeReason !== void 0 ? { closeReason } : {}
+	};
+	return {
+		code: ErrorCode.RPC_TRANSPORT_ERROR,
+		message,
+		context,
+		httpStatus: getHttpStatus(ErrorCode.RPC_TRANSPORT_ERROR),
+		suggestion: getSuggestion(ErrorCode.RPC_TRANSPORT_ERROR, context),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function buildInterruptedOperationResponse(transportResponse, context) {
+	if (!context.operation) return null;
+	const { kind } = transportResponse.context;
+	if (kind !== "session_disposed" && kind !== "peer_closed" && kind !== "connection_failed") return null;
+	const interruptedContext = {
+		reason: kind === "session_disposed" ? "transport_disposed" : "runtime_replaced",
+		operation: context.operation,
+		admitted: "unknown",
+		retryable: false
+	};
+	const action = kind === "session_disposed" ? "was closing" : "closed unexpectedly";
+	return {
+		code: ErrorCode.OPERATION_INTERRUPTED,
+		message: `Sandbox operation ${context.operation} was interrupted while the runtime connection ${action}`,
+		context: interruptedContext,
+		httpStatus: getHttpStatus(ErrorCode.OPERATION_INTERRUPTED),
+		suggestion: getSuggestion(ErrorCode.OPERATION_INTERRUPTED, interruptedContext),
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+
+//#endregion
+//#region src/processes/remote-subscription.ts
+/** Keeps a stream local to its Durable Object and exposes pull RPC methods. */
+var PullSubscriptionTarget = class extends RpcTarget {
+	#reader;
+	#onRelease;
+	#released = false;
+	constructor(stream, onRelease) {
+		super();
+		this.#reader = stream.getReader();
+		this.#onRelease = onRelease;
+	}
+	async next() {
+		if (this.#released) return {
+			done: true,
+			value: void 0
+		};
+		try {
+			const result = await this.#reader.read();
+			if (result.done) this.#release();
+			return result;
+		} catch (error) {
+			this.#release();
+			throw error;
+		}
+	}
+	async cancel() {
+		if (this.#released) return;
+		try {
+			await this.#reader.cancel();
+		} finally {
+			this.#release();
+		}
+	}
+	[Symbol.dispose]() {
+		if (this.#released) return;
+		this.#reader.cancel().catch(() => void 0);
+		this.#release();
+	}
+	#release() {
+		if (this.#released) return;
+		this.#released = true;
+		this.#onRelease?.();
+	}
+};
+/** Exposes a remote Workers RPC subscription as a caller-owned local stream. */
+async function openRemoteSubscription(subscriptionPromise, options) {
+	let subscription;
+	let releaseRequested = false;
+	let cleanupStarted = false;
+	const release = () => {
+		releaseRequested = true;
+		if (cleanupStarted || subscription === void 0) return;
+		cleanupStarted = true;
+		try {
+			subscription.cancel().catch(() => void 0);
+		} catch {}
+		try {
+			subscription[Symbol.dispose]();
+		} catch {}
+	};
+	const signal = options.signal;
+	const aborted = () => options.abortError?.() ?? (signal?.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("Operation aborted"));
+	const raceSetup = async (setup) => {
+		if (signal === void 0) return setup;
+		if (signal.aborted) {
+			release();
+			throw aborted();
+		}
+		let onAbort$1;
+		const abort = new Promise((_, reject) => {
+			onAbort$1 = () => {
+				release();
+				reject(aborted());
+			};
+			signal.addEventListener("abort", onAbort$1, { once: true });
+		});
+		try {
+			return await Promise.race([setup, abort]);
+		} finally {
+			if (onAbort$1 !== void 0) signal.removeEventListener("abort", onAbort$1);
+		}
+	};
+	try {
+		subscription = await raceSetup(subscriptionPromise.then((value) => {
+			subscription = value;
+			if (releaseRequested) release();
+			return value;
+		}));
+	} catch (error) {
+		if (signal?.aborted) throw error;
+		translateRPCError(error, { operation: options.operation ?? "open process subscription" });
+	}
+	if (subscription === void 0) throw new Error("Process subscription acquisition did not complete");
+	let read;
+	let cancelReader;
+	if (options.protocol === "pull") {
+		const pullSubscription = subscription;
+		read = () => pullSubscription.next();
+		cancelReader = () => void 0;
+	} else {
+		const streamSubscription = subscription;
+		let source;
+		try {
+			source = await raceSetup(streamSubscription.stream());
+		} catch (error) {
+			release();
+			if (signal?.aborted) throw error;
+			translateRPCError(error, { operation: options.operation ?? "open process subscription" });
+		}
+		let reader;
+		try {
+			reader = source.getReader();
+		} catch (error) {
+			release();
+			translateRPCError(error, { operation: options.operation ?? "read process subscription" });
+		}
+		read = () => reader.read();
+		cancelReader = () => {
+			try {
+				reader.cancel().catch(() => void 0);
+			} catch {}
+		};
+	}
+	let stopped = false;
+	let controller;
+	const stop = (error) => {
+		if (stopped) return;
+		stopped = true;
+		signal?.removeEventListener("abort", onAbort);
+		cancelReader();
+		release();
+		if (error !== void 0) controller?.error(error);
+	};
+	const onAbort = () => stop(aborted());
+	return new ReadableStream({
+		start(localController) {
+			controller = localController;
+			if (signal?.aborted) onAbort();
+			else signal?.addEventListener("abort", onAbort, { once: true });
+		},
+		async pull(localController) {
+			if (stopped) return;
+			try {
+				const result = await read();
+				if (stopped) return;
+				if (result.done) {
+					stopped = true;
+					signal?.removeEventListener("abort", onAbort);
+					release();
+					localController.close();
+					return;
+				}
+				localController.enqueue(result.value);
+			} catch (error) {
+				stop();
+				translateRPCError(error, { operation: options.operation ?? "consume process subscription" });
+			}
+		},
+		cancel() {
+			stop();
+		}
+	});
+}
+
+//#endregion
+//#region src/processes/process-waits.ts
+async function withLocalWait(work, options) {
+	const { signal, timeout } = options;
+	const settlement = new AbortController();
+	let timer;
+	let abortListener;
+	const competitors = [work(settlement.signal)];
+	if (timeout !== void 0) competitors.push(new Promise((_, reject) => {
+		timer = setTimeout(() => reject(timeoutError(options, timeout)), timeout);
+	}));
+	if (signal !== void 0) competitors.push(new Promise((_, reject) => {
+		const abort = () => reject(abortError(options.processId, options.operation, signal));
+		if (signal.aborted) abort();
+		else {
+			abortListener = abort;
+			signal.addEventListener("abort", abort, { once: true });
+		}
+	}));
+	try {
+		return await Promise.race(competitors);
+	} finally {
+		settlement.abort();
+		if (timer !== void 0) clearTimeout(timer);
+		if (abortListener !== void 0) signal?.removeEventListener("abort", abortListener);
+	}
+}
+function processFailure(processId, pid, failure) {
+	return new ProcessError({
+		code: ErrorCode.PROCESS_ERROR,
+		message: failure.message,
+		context: {
+			processId,
+			pid
+		},
+		httpStatus: 500,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+function streamClosed(message) {
+	translateRPCError(new Error(message), {
+		operation: "consume process subscription",
+		translateTransportErrorsAsInterruptions: false
+	});
+}
+function timeoutError(options, timeout) {
+	if (options.operation === "waitForPort") {
+		const condition = `port ${options.port ?? "unknown"}`;
+		return new ProcessReadyTimeoutError({
+			code: ErrorCode.PROCESS_READY_TIMEOUT,
+			message: `Process did not become ready within ${timeout}ms. Waiting for: ${condition}`,
+			context: {
+				processId: options.processId,
+				command: options.processId,
+				condition,
+				timeout
+			},
+			httpStatus: 408,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	const operation = options.operation === "logs" ? "waitForLog" : options.operation;
+	return new ProcessWaitTimeoutError({
+		code: ErrorCode.PROCESS_WAIT_TIMEOUT,
+		message: `Process ${operation} did not complete within ${timeout}ms`,
+		context: {
+			processId: options.processId,
+			operation,
+			timeout
+		},
+		httpStatus: 408,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+function abortError(processId, operation, signal) {
+	if (signal.reason instanceof Error && signal.reason.name !== "AbortError") return signal.reason;
+	return new ProcessAbortedError({
+		code: ErrorCode.PROCESS_ABORTED,
+		message: `Process ${operation} was aborted`,
+		context: {
+			processId,
+			operation
+		},
+		httpStatus: 499,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+
+//#endregion
+//#region src/processes/process-output.ts
+async function readProcessOutput(reader, options) {
+	const maxBytes = validateMaxBytes(options.maxBytes);
+	const stdout = [];
+	const stderr = [];
+	let stdoutBytes = 0;
+	let stderrBytes = 0;
+	let retainedBytes = 0;
+	let truncated = false;
+	for (;;) {
+		const result = await reader.read();
+		if (result.done) streamClosed("Process log stream ended before exit");
+		const event = result.value;
+		if ("type" in event && event.type === "truncated") {
+			truncated = true;
+			continue;
+		}
+		if ("state" in event) {
+			if (event.state === "error") throw processFailure(options.processId, options.pid, event.error);
+			return {
+				stdout: concat(stdout, stdoutBytes),
+				stderr: concat(stderr, stderrBytes),
+				exitCode: event.exit.code,
+				signal: event.exit.signal,
+				timedOut: event.exit.timedOut,
+				truncated
+			};
+		}
+		const remaining = maxBytes === void 0 ? event.data.byteLength : Math.max(0, maxBytes - retainedBytes);
+		const retainedLength = Math.min(remaining, event.data.byteLength);
+		if (retainedLength < event.data.byteLength) truncated = true;
+		if (retainedLength === 0) continue;
+		const chunk = retainedLength === event.data.byteLength ? event.data : event.data.slice(0, retainedLength);
+		if (event.type === "stdout") {
+			stdout.push(chunk);
+			stdoutBytes += chunk.byteLength;
+		} else {
+			stderr.push(chunk);
+			stderrBytes += chunk.byteLength;
+		}
+		retainedBytes += chunk.byteLength;
+	}
+}
+function validateMaxBytes(maxBytes) {
+	if (maxBytes === void 0) return void 0;
+	if (!Number.isFinite(maxBytes) || maxBytes < 0) throw new Error("maxBytes must be a non-negative finite number");
+	return maxBytes;
+}
+function concat(chunks, length) {
+	const out = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return out;
+}
+
+//#endregion
+//#region src/processes/process-readiness.ts
+async function waitForReadiness(portReader, logReader, context) {
+	await Promise.race([consumePort(portReader), consumeTerminal(logReader, context)]);
+}
+async function consumePort(reader) {
+	for (;;) {
+		const result = await reader.read();
+		if (result.done) streamClosed("Port watch stream ended unexpectedly");
+		if (result.value.type === "ready") return;
+		if (result.value.type === "error") throw new Error(result.value.error || "Port watch failed");
+	}
+}
+async function consumeTerminal(reader, context) {
+	for (;;) {
+		const result = await reader.read();
+		if (result.done) streamClosed("Process log stream ended before exit");
+		const event = result.value;
+		if (!("state" in event)) continue;
+		if (event.state === "error") throw processFailure(context.processId, context.pid, event.error);
+		throw exitedBeforeReady(context.processId, context.port, event.exit.code);
+	}
+}
+function exitedBeforeReady(processId, port, exitCode) {
+	return new ProcessExitedBeforeReadyError({
+		code: ErrorCode.PROCESS_EXITED_BEFORE_READY,
+		message: `Process exited with code ${exitCode} before becoming ready. Waiting for: port ${port}`,
+		context: {
+			processId,
+			command: processId,
+			condition: `port ${port}`,
+			exitCode
+		},
+		httpStatus: 500,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+
+//#endregion
+//#region src/processes/wait-for-log.ts
+const MATCH_WINDOW = 64 * 1024;
+async function readUntilLogMatch(reader, pattern, wanted, processId, pid) {
+	const decoders = {
+		stdout: new TextDecoder(),
+		stderr: new TextDecoder()
+	};
+	const windows = {
+		stdout: "",
+		stderr: ""
+	};
+	const cursors = {
+		stdout: "",
+		stderr: ""
+	};
+	const append = (stream, decoded, cursor) => {
+		const text = bounded(windows[stream] + decoded);
+		windows[stream] = text;
+		cursors[stream] = cursor;
+		const match = findMatch(text, pattern);
+		return match === void 0 ? void 0 : {
+			stream,
+			text,
+			match,
+			cursor
+		};
+	};
+	const flush = (cursor) => {
+		for (const stream of ["stdout", "stderr"]) {
+			if (wanted !== "both" && wanted !== stream) continue;
+			const result = append(stream, decoders[stream].decode(), cursors[stream] || cursor);
+			if (result !== void 0) return result;
+		}
+	};
+	for (;;) {
+		const result = await reader.read();
+		if (result.done) {
+			const match$1 = flush("");
+			if (match$1 !== void 0) return match$1;
+			streamClosed("Process log stream ended before a match was found");
+		}
+		const event = result.value;
+		if ("state" in event) {
+			const match$1 = flush(event.cursor);
+			if (match$1 !== void 0) return match$1;
+			if (event.state === "error") throw processFailure(processId, pid, event.error);
+			throw new ProcessExitedBeforeLogError({
+				code: ErrorCode.PROCESS_EXITED_BEFORE_LOG,
+				message: "Process exited before a log match was found",
+				context: {
+					processId,
+					pid,
+					exit: { ...event.exit }
+				},
+				httpStatus: 409,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		if (event.type !== "stdout" && event.type !== "stderr") continue;
+		if (wanted !== "both" && wanted !== event.type) continue;
+		const match = append(event.type, decoders[event.type].decode(event.data, { stream: true }), event.cursor);
+		if (match !== void 0) return match;
+	}
+}
+function bounded(text) {
+	return text.length <= MATCH_WINDOW ? text : text.slice(-MATCH_WINDOW);
+}
+function findMatch(text, pattern) {
+	if (typeof pattern === "string") return text.includes(pattern) ? pattern : void 0;
+	pattern.lastIndex = 0;
+	const match = pattern.exec(text)?.[0];
+	pattern.lastIndex = 0;
+	return match;
+}
+
+//#endregion
+//#region src/processes/sandbox-process.ts
+var SandboxProcessImpl = class {
+	#exitCodePromise;
+	constructor(id, pid, capability) {
+		this.id = id;
+		this.pid = pid;
+		this.capability = capability;
+	}
+	get exitCode() {
+		this.#exitCodePromise ??= this.waitForExit().then((exit) => exit.code);
+		return this.#exitCodePromise;
+	}
+	status() {
+		return this.capability.status();
+	}
+	async logs(options = {}) {
+		const { signal, ...rpcOptions } = options;
+		return openRemoteSubscription(this.capability.openLogs(rpcOptions), {
+			protocol: "pull",
+			signal,
+			operation: "read process logs",
+			abortError: signal === void 0 ? void 0 : () => abortError(this.id, "logs", signal)
+		});
+	}
+	async output(options = {}) {
+		const maxBytes = validateMaxBytes(options.maxBytes);
+		const bytes = await withLocalWait((settlementSignal) => this.consumeLogs(settlementSignal, (reader) => readProcessOutput(reader, {
+			maxBytes,
+			processId: this.id,
+			pid: this.pid
+		})), {
+			processId: this.id,
+			operation: "output",
+			timeout: options.timeout,
+			signal: options.signal
+		});
+		if ("encoding" in options && options.encoding === "utf8") return {
+			...bytes,
+			stdout: new TextDecoder().decode(bytes.stdout),
+			stderr: new TextDecoder().decode(bytes.stderr)
+		};
+		return bytes;
+	}
+	async waitForExit(options = {}) {
+		return withLocalWait((settlementSignal) => this.consumeLogs(settlementSignal, (reader) => readTerminal(reader, this.id, this.pid)), {
+			processId: this.id,
+			operation: "waitForExit",
+			timeout: options.timeout,
+			signal: options.signal
+		});
+	}
+	async waitForLog(pattern, options = {}) {
+		return withLocalWait((settlementSignal) => this.consumeLogs(settlementSignal, (reader) => readUntilLogMatch(reader, pattern, options.stream ?? "both", this.id, this.pid)), {
+			processId: this.id,
+			operation: "waitForLog",
+			timeout: options.timeout,
+			signal: options.signal
+		});
+	}
+	async waitForPort(port, options = {}) {
+		const { timeout, signal, ...rpcOptions } = options;
+		return withLocalWait((settlementSignal) => this.waitForPortSubscriptions(port, rpcOptions, settlementSignal), {
+			processId: this.id,
+			operation: "waitForPort",
+			timeout,
+			signal,
+			port
+		});
+	}
+	async waitForPortSubscriptions(port, options, settlementSignal) {
+		const portStream = await openRemoteSubscription(this.capability.openPortWatch(port, options), {
+			operation: `watch port ${port}`,
+			protocol: "pull",
+			signal: settlementSignal
+		});
+		let logStream;
+		let portReader;
+		let logReader;
+		try {
+			portReader = portStream.getReader();
+			logStream = await openRemoteSubscription(this.capability.openLogs({
+				replay: true,
+				follow: true
+			}), {
+				operation: "read process logs",
+				protocol: "pull",
+				signal: settlementSignal
+			});
+			logReader = logStream.getReader();
+			await waitForReadiness(portReader, logReader, {
+				processId: this.id,
+				pid: this.pid,
+				port
+			});
+		} finally {
+			await cancelOwned(portReader, portStream);
+			if (logStream !== void 0) await cancelOwned(logReader, logStream);
+		}
+	}
+	kill(signal = 15) {
+		return this.capability.kill(signal);
+	}
+	async consumeLogs(signal, consume) {
+		const stream = await openRemoteSubscription(this.capability.openLogs({
+			replay: true,
+			follow: true
+		}), {
+			signal,
+			operation: "read process logs",
+			protocol: "pull"
+		});
+		return this.consume(stream, consume);
+	}
+	async consume(stream, consume) {
+		let reader;
+		try {
+			reader = stream.getReader();
+			return await consume(reader);
+		} finally {
+			await cancelOwned(reader, stream);
+		}
+	}
+};
+function createSandboxProcess(descriptor) {
+	return new SandboxProcessImpl(descriptor.id, descriptor.pid, descriptor.capability);
+}
+async function readTerminal(reader, processId, pid) {
+	for (;;) {
+		const result = await reader.read();
+		if (result.done) streamClosed("Process log stream ended before exit");
+		if ("state" in result.value) {
+			if (result.value.state === "exited") return result.value.exit;
+			throw processFailure(processId, pid, result.value.error);
+		}
+	}
+}
+async function cancelOwned(reader, stream) {
+	try {
+		if (reader !== void 0) await reader.cancel();
+		else await stream.cancel();
+	} catch {}
+}
+
+//#endregion
+//#region src/extensions/index.ts
+/**
+* Unified extension surface for the Cloudflare Sandbox SDK.
+*
+* Every extension \u2014 whether it just drives existing control sub-APIs or
+* ships its own container sidecar \u2014 shares one shape: a class extending
+* {@link SandboxExtension}, captured lazily via a `withX(this)` factory.
+*
+* - No sidecar? Extend {@link SandboxExtension} and use `this.exec()` or
+*   `this.withRuntime()` for scoped control APIs. Don't pass a package.
+* - Need a container sidecar? Pass an {@link ExtensionPackage} to `super()`.
+*   Then use {@link SandboxExtension.withSidecar} with the sidecar's typed
+*   capnweb remote main. Calls on that stub stream through capnweb \u2014 callback
+*   parameters round-trip across both the DO\u2192container and container\u2192sidecar
+*   hops.
+*
+* `ExtensionPackage` carries tarball bytes produced by an extension build.
+* The SDK sends those bytes only when the container has not provisioned the
+* package hash yet.
+*/
+const sandboxRuntimeCall = Symbol("sandboxRuntimeCall");
+function isProcessRPCDescriptor(process) {
+	return "capability" in process;
+}
+/** Normalize local RPC descriptors and caller-side handles for extensions. */
+function createExtensionProcessSandbox(sandbox) {
+	return {
+		async exec(command, options) {
+			if (!sandbox.exec) throw new Error("Sandbox extension requires the exec surface from the owning Sandbox");
+			const process = await sandbox.exec.call(sandbox, command, options);
+			return isProcessRPCDescriptor(process) ? createSandboxProcess(process) : process;
+		},
+		async getProcess(processId) {
+			if (!sandbox.getProcess) throw new Error("Sandbox extension requires the getProcess surface from the owning Sandbox");
+			const process = await sandbox.getProcess.call(sandbox, processId);
+			if (!process) return null;
+			return isProcessRPCDescriptor(process) ? createSandboxProcess(process) : process;
+		},
+		listProcesses() {
+			if (!sandbox.listProcesses) throw new Error("Sandbox extension requires the listProcesses surface from the owning Sandbox");
+			return sandbox.listProcesses.call(sandbox);
+		}
+	};
+}
+/**
+* The one base class for *every* extension.
+*
+* - SDK-only: just drives existing sub-APIs.
+* - Sidecar: pass an {@link ExtensionPackage} to `super(sandbox, pkg)` and
+*   call `this.withSidecar<T>(operation, callback)` to use the typed capnweb stub inside one runtime callback.
+*
+* The sidecar helper throws a clear error if no package was supplied, so an
+* extension only "becomes" a sidecar extension when it opts in.
+*
+* ```ts
+* // SDK-only
+* class GitStatus extends SandboxExtension {
+*   constructor(s: SandboxLike) { super(s); }
+*   async status() {
+*     const process = await this.exec(['git', 'status']);
+*     return process.output({ encoding: 'utf8' });
+*   }
+* }
+*
+* // Sidecar
+* import sidecarTarballBytes from './sidecar-package.tgz';
+* import type { MyAPI } from './shared';
+*
+* class MyExt extends SandboxExtension {
+*   constructor(s: SandboxLike) { super(s, { tarball: new Uint8Array(sidecarTarballBytes) }); }
+*   async run(input: string): Promise<string> {
+*     return this.withSidecar<MyAPI, string>('my-ext.run', (api) =>
+*       api.run(input)
+*     );
+*   }
+* }
+* ```
+*
+* RPC-safety: the sandbox lives in `#sandbox` and runtime control is reached
+* only through a symbol-keyed capability, so it is not exposed as a named RPC
+* method. Only the public methods you add form the extension's RPC surface.
+*/
+var SandboxExtension = class extends RpcTarget {
+	#sandbox;
+	#pkg;
+	#hashPromise;
+	constructor(sandbox, pkg) {
+		super();
+		this.#sandbox = sandbox;
+		this.#pkg = pkg;
+	}
+	withRuntime(operation, call) {
+		const guardedCall = async (runtimeControl) => {
+			const { control, revoke } = scopedRuntimeControl(runtimeControl);
+			try {
+				const result = await call(control);
+				assertRuntimeControlDidNotEscape(result, control);
+				return result;
+			} finally {
+				revoke();
+			}
+		};
+		return this.#sandbox[sandboxRuntimeCall](operation, guardedCall);
+	}
+	/** Launch an argv process through the owning Sandbox. */
+	exec(command, options) {
+		return createExtensionProcessSandbox(this.#sandbox).exec(command, options);
+	}
+	/** Sandbox-level environment applied to extension-launched processes. */
+	get envVars() {
+		return this.#sandbox.envVars ?? {};
+	}
+	get httpAuthInterceptor() {
+		const register = this.#sandbox.registerGitAuthInterceptor;
+		return register ? (params) => register.call(this.#sandbox, params) : void 0;
+	}
+	/**
+	* Provision/connect to the sidecar and use its typed capnweb remote inside
+	* one runtime callback. The remote is invalid after `call` resolves or
+	* rejects, so extension code cannot silently reconnect or keep using an old
+	* runtime's sidecar.
+	*/
+	async withSidecar(operation, call) {
+		const pkg = this.#requirePackage();
+		const packageHash = await this.#hashOnce();
+		const scopedCall = async (control) => {
+			const { proxy, revoke } = scopedSidecarRemote(await this.#connect(control.extensions, pkg, packageHash));
+			try {
+				const result = await call(proxy);
+				assertSidecarRemoteDidNotEscape(result);
+				return detachPlainData(result);
+			} finally {
+				revoke();
+			}
+		};
+		return await this.withRuntime(operation, scopedCall);
+	}
+	/** Health snapshot for this extension's sidecar. */
+	async sidecarHealth() {
+		const hash = await this.#hashOnce();
+		return await this.withRuntime("extension.health", (control) => control.extensions.health(hash));
+	}
+	/**
+	* Stop this extension's sidecar. The next `withSidecar()` call will respawn
+	* it on demand.
+	*/
+	async stopSidecar() {
+		const hash = await this.#hashOnce();
+		await this.withRuntime("extension.stop", (control) => control.extensions.stop(hash));
+	}
+	async #connect(api, pkg, packageHash) {
+		try {
+			return await api.connect({
+				packageHash,
+				bin: pkg.bin,
+				readinessTimeoutMs: pkg.readinessTimeoutMs,
+				allowInstallScripts: pkg.allowInstallScripts
+			});
+		} catch (error) {
+			if (!isTarballRequiredError(error)) throw error;
+			try {
+				return await api.connect({
+					packageHash,
+					tarball: pkg.tarball,
+					bin: pkg.bin,
+					readinessTimeoutMs: pkg.readinessTimeoutMs,
+					allowInstallScripts: pkg.allowInstallScripts
+				});
+			} catch (retryError) {
+				throw createSidecarProvisioningError(packageHash, retryError);
+			}
+		}
+	}
+	#hashOnce() {
+		const pkg = this.#requirePackage();
+		this.#hashPromise ??= sha256Hex(pkg.tarball);
+		return this.#hashPromise;
+	}
+	#requirePackage() {
+		if (!this.#pkg) throw new Error("This extension has no sidecar package. Pass one to `super(sandbox, pkg)` to use sidecar/sidecarHealth/stopSidecar.");
+		return this.#pkg;
+	}
+};
+/**
+* Recognise the host's `ExtensionTarballRequired` error across the capnweb
+* boundary. There are two cases:
+*
+* 1. capnweb preserves `Error.name`, so the primary wire-safe contract is the
+*    string constant `EXTENSION_TARBALL_REQUIRED`.
+* 2. capnweb sometimes re-wraps the error as an `RPCTransportError`, discarding
+*    `name` but preserving the message text. We fall back to matching the
+*    message so the tarball retry still fires in that case.
+*/
+function assertRuntimeControlDidNotEscape(result, control) {
+	if (![
+		control,
+		control.files,
+		control.ports,
+		control.backup,
+		control.watch,
+		control.tunnels,
+		control.terminals,
+		control.extensions,
+		control.utils
+	].filter((handle) => handle !== void 0).includes(result)) return;
+	throw new Error("Sandbox extension runtime callbacks must not return runtime control handles");
+}
+function scopedRuntimeControl(target) {
+	let active = true;
+	const inactiveError = () => /* @__PURE__ */ new Error("Sandbox extension runtime control is no longer valid outside its runtime callback");
+	const wrappedDomains = /* @__PURE__ */ new WeakMap();
+	const scopeDomain = (domain) => {
+		const existing = wrappedDomains.get(domain);
+		if (existing) return existing;
+		const proxy = new Proxy(domain, { get(domainTarget, property, receiver) {
+			if (!active) return () => Promise.reject(inactiveError());
+			const value = Reflect.get(domainTarget, property, receiver);
+			if (typeof value === "function") return (...args) => {
+				if (!active) return Promise.reject(inactiveError());
+				return scopeRuntimeResult(Reflect.apply(value, domainTarget, args));
+			};
+			if (typeof value === "object" && value !== null) {
+				if (objectHasCallableMember(value)) return scopeDomain(value);
+				return detachPlainData(value);
+			}
+			return value;
+		} });
+		wrappedDomains.set(domain, proxy);
+		return proxy;
+	};
+	const scopeRuntimeResult = (result) => {
+		if (result instanceof Promise) return result.then(scopeRuntimeResult);
+		if (typeof result === "object" && result !== null) {
+			if (objectHasCallableMember(result)) return scopeDomain(result);
+			return detachPlainData(result);
+		}
+		return result;
+	};
+	return {
+		control: {
+			files: scopeDomain(target.files),
+			ports: scopeDomain(target.ports),
+			backup: scopeDomain(target.backup),
+			watch: scopeDomain(target.watch),
+			tunnels: scopeDomain(target.tunnels),
+			terminals: scopeDomain(target.terminals),
+			extensions: scopeDomain(target.extensions),
+			utils: scopeDomain(target.utils)
+		},
+		revoke: () => {
+			active = false;
+		}
+	};
+}
+const sidecarRemoteProxies = /* @__PURE__ */ new WeakSet();
+function scopedSidecarRemote(target) {
+	let active = true;
+	const wrappedTargets = /* @__PURE__ */ new WeakMap();
+	const createProxy = (currentTarget) => {
+		const existing = wrappedTargets.get(currentTarget);
+		if (existing) return existing;
+		const proxy = new Proxy(currentTarget, { get(targetObject, property, receiver) {
+			if (!active) return () => Promise.reject(/* @__PURE__ */ new Error("Sandbox extension sidecar remote is no longer valid outside its runtime callback"));
+			const value = Reflect.get(targetObject, property, receiver);
+			if (typeof value === "function") return (...args) => {
+				if (!active) return Promise.reject(/* @__PURE__ */ new Error("Sandbox extension sidecar remote is no longer valid outside its runtime callback"));
+				return wrapSidecarResult(Reflect.apply(value, targetObject, args), createProxy);
+			};
+			if (typeof value === "object" && value !== null) {
+				if (objectHasCallableMember(value)) return createProxy(value);
+				return detachPlainData(value);
+			}
+			return value;
+		} });
+		wrappedTargets.set(currentTarget, proxy);
+		sidecarRemoteProxies.add(proxy);
+		return proxy;
+	};
+	return {
+		proxy: createProxy(target),
+		revoke: () => {
+			active = false;
+		}
+	};
+}
+function wrapSidecarResult(result, wrapObject) {
+	if (result instanceof Promise) return result.then((value) => wrapSidecarResult(value, wrapObject));
+	if (typeof result === "object" && result !== null) {
+		if (objectHasCallableMember(result)) return wrapObject(result);
+		return detachPlainData(result);
+	}
+	return result;
+}
+function objectHasCallableMember(value) {
+	if (Array.isArray(value)) return value.some((entry) => typeof entry === "function");
+	let current = value;
+	while (current && current !== Object.prototype) {
+		for (const property of Reflect.ownKeys(current)) {
+			if (property === "constructor") continue;
+			const descriptor = Reflect.getOwnPropertyDescriptor(current, property);
+			if (!descriptor) continue;
+			if (typeof descriptor.value === "function") return true;
+			if (typeof descriptor.get === "function") return true;
+		}
+		current = Reflect.getPrototypeOf(current);
+	}
+	return false;
+}
+function assertSidecarRemoteDidNotEscape(result) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const visit = (value) => {
+		if (typeof value !== "object" || value === null) return false;
+		if (seen.has(value)) return false;
+		seen.add(value);
+		if (sidecarRemoteProxies.has(value)) return true;
+		if (Array.isArray(value)) return value.some(visit);
+		return Object.values(value).some(visit);
+	};
+	if (!visit(result)) return;
+	throw new Error("Sandbox extension sidecar callbacks must not return sidecar remotes");
+}
+function detachPlainData(value) {
+	if (typeof value !== "object" || value === null) return value;
+	return structuredClone(value);
+}
+function isTarballRequiredError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	const candidate = error;
+	if (candidate.name === EXTENSION_TARBALL_REQUIRED) return true;
+	if (typeof candidate.message !== "string") return false;
+	return candidate.message.includes(EXTENSION_TARBALL_REQUIRED) || /Extension package '[0-9a-f]{64}' is not provisioned/.test(candidate.message);
+}
+function createSidecarProvisioningError(packageHash, cause) {
+	const causeMessage = cause instanceof Error ? cause.message : typeof cause === "string" ? cause : String(cause);
+	return new Error(`Failed to provision sandbox sidecar package '${packageHash}'. The sidecar tarball was sent to the container, but the container could not install or start it. Check that the extension build generated a valid npm-style .tgz, that the .tgz is included in the Worker bundle, and that the sidecar package declares a valid package.json bin/sandboxExtension entry. Cause: ${causeMessage}`, { cause });
+}
+/**
+* Hex sha256 of a tarball via Web Crypto, which is available in workerd and
+* every modern runtime. Avoids a Node-only path so this module stays
+* Worker-bundle-safe.
+*/
+async function sha256Hex(bytes) {
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	const view = new Uint8Array(digest);
+	let hex = "";
+	for (const byte of view) hex += byte.toString(16).padStart(2, "0");
+	return hex;
+}
+
+//#endregion
+export { PullSubscriptionTarget as a, createSandboxProcess as i, createExtensionProcessSandbox as n, openRemoteSubscription as o, sandboxRuntimeCall as r, translateRPCError as s, SandboxExtension as t };
+//# sourceMappingURL=extensions-CFB2xHqY.js.map