@cloudflare/sandbox 0.8.9 → 0.8.11

package/dist/bridge/index.js

@@ -0,0 +1,2499 @@
+import "../dist-Ilf8VjmX.js";
+import "../errors-Bz21XTBJ.js";
+import { i as getSandbox, n as streamFile } from "../file-stream-Bn2PceyF.js";
+import { DurableObject, env } from "cloudflare:workers";
+import { Hono } from "hono";
+
+//#region src/bridge/pool.ts
+/**
+* Prime the warm pool — pushes current configuration to the WarmPool
+* Durable Object so it starts its alarm loop.
+*
+* Called by the scheduled() handler and by POST /pool/prime.
+*/
+async function primePool(env$1, warmPoolBinding) {
+	const warmTarget = Number.parseInt(env$1.WARM_POOL_TARGET || "0", 10) || 0;
+	const refreshInterval = Number.parseInt(env$1.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
+	const ns = env$1[warmPoolBinding];
+	const poolId = ns.idFromName("global-pool");
+	await ns.get(poolId).configure({
+		warmTarget,
+		refreshInterval
+	});
+}
+
+//#endregion
+//#region src/bridge/helpers.ts
+/**
+* Utility functions used by the bridge routes.
+*/
+/**
+* UTF-8-safe base64 encoding.
+* btoa() only handles latin-1; encode to UTF-8 bytes first via TextEncoder.
+*/
+function toBase64(str) {
+	const bytes = new TextEncoder().encode(str);
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary);
+}
+/** RFC 4648 base32 encoding (lowercase). Returns only [a-z2-7]. */
+function base32Encode(data) {
+	const alphabet = "abcdefghijklmnopqrstuvwxyz234567";
+	let bits = 0;
+	let value = 0;
+	let out = "";
+	for (const byte of data) {
+		value = value << 8 | byte;
+		bits += 8;
+		while (bits >= 5) {
+			out += alphabet[value >>> bits - 5 & 31];
+			bits -= 5;
+		}
+	}
+	if (bits > 0) out += alphabet[value << 5 - bits & 31];
+	return out;
+}
+function errorJson(error, code, status) {
+	const body = {
+		error,
+		code
+	};
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+/**
+* Shell-quote a single argv token so it is safe to embed in a sh command
+* string.  Tokens that contain only safe characters are returned unchanged
+* for readability.  All others are wrapped in ANSI-C $'...' quoting which
+* can represent newlines, tabs, and other control characters as escape
+* sequences — unlike plain single quotes which pass content literally and
+* break when the value contains a real newline.
+*/
+function shellQuote(arg) {
+	if (/^[A-Za-z0-9@%+=:,./-]+$/.test(arg)) return arg;
+	return "$'" + arg.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t") + "'";
+}
+/**
+* POSIX-normalise a path (resolve `.` / `..` segments) and verify it lives
+* under /workspace.  Returns the resolved absolute path on success, or null
+* if the path escapes the workspace.
+*/
+function resolveWorkspacePath(userPath) {
+	const abs = userPath.startsWith("/") ? userPath : `/workspace/${userPath}`;
+	const parts = [];
+	for (const seg of abs.split("/")) {
+		if (seg === "" || seg === ".") continue;
+		if (seg === "..") parts.pop();
+		else parts.push(seg);
+	}
+	const resolved = "/" + parts.join("/");
+	if (resolved === "/workspace" || resolved.startsWith("/workspace/")) return resolved;
+	return null;
+}
+/**
+* Validate a session ID. Rejects path traversal, control chars, and excessive length.
+* Returns the validated ID or null if invalid.
+*/
+function validateSessionId(id) {
+	if (!/^[a-zA-Z0-9._-]{1,128}$/.test(id)) return null;
+	if (id.includes("..")) return null;
+	return id;
+}
+/**
+* Convert an SSE stream from readFileStream() into a raw byte stream.
+* Decodes base64 chunks for binary files and UTF-8-encodes text chunks.
+*/
+function sseToByteStream(sse) {
+	const encoder = new TextEncoder();
+	return new ReadableStream({ async start(controller) {
+		try {
+			for await (const chunk of streamFile(sse)) controller.enqueue(chunk instanceof Uint8Array ? chunk : encoder.encode(chunk));
+			controller.close();
+		} catch (err) {
+			controller.error(err);
+		}
+	} });
+}
+
+//#endregion
+//#region src/bridge/openapi.ts
+/**
+* OpenAPI 3.1 schema for the Cloudflare Sandbox Service API.
+*
+* Served at GET /v1/openapi.json (requires Bearer token auth).
+*/
+const OPENAPI_SCHEMA = {
+	openapi: "3.1.0",
+	info: {
+		title: "Cloudflare Sandbox Service API",
+		version: "1.0.0",
+		description: "HTTP API consumed by the Python `CloudflareSandboxClient`. Forwards each operation to a named Cloudflare Sandbox Durable Object via the `@cloudflare/sandbox` SDK."
+	},
+	components: {
+		securitySchemes: { BearerAuth: {
+			type: "http",
+			scheme: "bearer",
+			description: "API token set via `wrangler secret put SANDBOX_API_KEY`. The /openapi.* routes also accept the token as a `?token=` query parameter."
+		} },
+		schemas: {
+			ExecRequest: {
+				type: "object",
+				required: ["argv"],
+				properties: {
+					argv: {
+						type: "array",
+						items: { type: "string" },
+						minItems: 1,
+						description: "Argv array — already shell-expanded by the Python layer if shell=True.",
+						example: [
+							"sh",
+							"-lc",
+							"echo hello"
+						]
+					},
+					timeout_ms: {
+						type: "integer",
+						description: "Per-call timeout in milliseconds.",
+						example: 3e4
+					},
+					cwd: {
+						type: "string",
+						description: "Working directory for the command (defaults to sandbox cwd).",
+						example: "/workspace"
+					}
+				}
+			},
+			WriteResponse: {
+				type: "object",
+				required: ["ok"],
+				properties: { ok: {
+					type: "boolean",
+					enum: [true],
+					description: "Always `true` on success."
+				} }
+			},
+			RunningResponse: {
+				type: "object",
+				required: ["running"],
+				properties: { running: {
+					type: "boolean",
+					description: "`true` if the sandbox container is alive and responding."
+				} }
+			},
+			OkResponse: {
+				type: "object",
+				required: ["ok"],
+				properties: { ok: {
+					type: "boolean",
+					enum: [true],
+					description: "Always `true` on success."
+				} }
+			},
+			MountBucketCredentials: {
+				type: "object",
+				required: ["accessKeyId", "secretAccessKey"],
+				properties: {
+					accessKeyId: {
+						type: "string",
+						description: "S3-compatible access key ID."
+					},
+					secretAccessKey: {
+						type: "string",
+						description: "S3-compatible secret access key."
+					}
+				}
+			},
+			MountBucketRequestOptions: {
+				type: "object",
+				required: ["endpoint"],
+				properties: {
+					endpoint: {
+						type: "string",
+						description: "S3-compatible endpoint URL.",
+						example: "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com"
+					},
+					readOnly: {
+						type: "boolean",
+						description: "Mount filesystem as read-only (default: false).",
+						default: false
+					},
+					prefix: {
+						type: "string",
+						description: "Optional prefix/subdirectory within the bucket to mount. Must start and end with `/`.",
+						example: "/uploads/images/"
+					},
+					credentials: {
+						$ref: "#/components/schemas/MountBucketCredentials",
+						description: "Explicit credentials. When omitted, the SDK auto-detects from Worker secrets (R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY or AWS equivalents)."
+					}
+				}
+			},
+			MountBucketRequest: {
+				type: "object",
+				required: [
+					"bucket",
+					"mountPath",
+					"options"
+				],
+				properties: {
+					bucket: {
+						type: "string",
+						description: "Bucket name.",
+						example: "my-r2-bucket"
+					},
+					mountPath: {
+						type: "string",
+						description: "Absolute path in the container to mount at.",
+						example: "/mnt/data"
+					},
+					options: { $ref: "#/components/schemas/MountBucketRequestOptions" }
+				}
+			},
+			UnmountBucketRequest: {
+				type: "object",
+				required: ["mountPath"],
+				properties: { mountPath: {
+					type: "string",
+					description: "Absolute path where the bucket is currently mounted.",
+					example: "/mnt/data"
+				} }
+			},
+			ErrorResponse: {
+				type: "object",
+				required: ["error", "code"],
+				properties: {
+					error: {
+						type: "string",
+						description: "Human-readable error description."
+					},
+					code: {
+						type: "string",
+						description: "Stable machine-readable error code.",
+						enum: [
+							"unauthorized",
+							"invalid_request",
+							"exec_error",
+							"exec_transport_error",
+							"workspace_read_not_found",
+							"workspace_archive_read_error",
+							"workspace_archive_write_error",
+							"capacity_exceeded",
+							"pool_error",
+							"mount_error",
+							"unmount_error",
+							"session_error"
+						]
+					}
+				}
+			},
+			PoolStats: {
+				type: "object",
+				required: [
+					"warm",
+					"assigned",
+					"total",
+					"config",
+					"maxInstances"
+				],
+				properties: {
+					warm: {
+						type: "integer",
+						description: "Number of warm (unassigned) containers ready for use."
+					},
+					assigned: {
+						type: "integer",
+						description: "Number of containers assigned to sandbox IDs."
+					},
+					total: {
+						type: "integer",
+						description: "Total containers tracked by the pool."
+					},
+					config: {
+						type: "object",
+						properties: {
+							warmTarget: { type: "integer" },
+							refreshInterval: { type: "integer" }
+						}
+					},
+					maxInstances: {
+						type: ["integer", "null"],
+						description: "Inferred max_instances limit, or null if not yet known."
+					}
+				}
+			}
+		},
+		responses: {
+			Unauthorized: {
+				description: "Missing or invalid Bearer token.",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "Unauthorized",
+						code: "unauthorized"
+					}
+				} }
+			},
+			InvalidRequest: {
+				description: "Malformed request body or missing required fields.",
+				content: { "application/json": {
+					schema: { $ref: "#/components/schemas/ErrorResponse" },
+					example: {
+						error: "argv must be a non-empty array",
+						code: "invalid_request"
+					}
+				} }
+			}
+		}
+	},
+	security: [{ BearerAuth: [] }],
+	paths: {
+		"/v1/sandbox": { post: {
+			operationId: "createSandbox",
+			summary: "Create a new sandbox session",
+			description: "Generates a new unique sandbox ID. Use this ID with all `/v1/sandbox/{id}/*` routes.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X POST https://$HOST/v1/sandbox \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+			}],
+			responses: {
+				"200": {
+					description: "New sandbox session created.",
+					content: { "application/json": { schema: {
+						type: "object",
+						required: ["id"],
+						properties: { id: {
+							type: "string",
+							description: "Unique sandbox ID for use with `/v1/sandbox/{id}/*` routes.",
+							example: "mfrggzdfmy2tqnrzgezdgnbv"
+						} }
+					} } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		} },
+		"/v1/sandbox/{id}/exec": { post: {
+			operationId: "execCommand",
+			summary: "Execute a command in the sandbox",
+			description: "Runs a shell command inside the named sandbox and streams output as Server-Sent Events (SSE). Events: `stdout` (base64 chunk), `stderr` (base64 chunk), `exit` (JSON with exit_code), `error` (JSON with error and code). The stream terminates after an `exit` or `error` event.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -N -X POST https://$HOST/v1/sandbox/my-sandbox/exec \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"argv\":[\"sh\",\"-lc\",\"echo hello\"]}'"
+			}],
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name (maps to a Durable Object key)."
+			}, {
+				name: "Session-Id",
+				in: "header",
+				required: false,
+				schema: {
+					type: "string",
+					pattern: "^[a-zA-Z0-9._-]{1,128}$"
+				},
+				description: "Scope this operation to a specific session. Uses the default session if omitted."
+			}],
+			requestBody: {
+				required: true,
+				content: { "application/json": { schema: { $ref: "#/components/schemas/ExecRequest" } } }
+			},
+			responses: {
+				"200": {
+					description: "SSE stream of command output. Events:\n- `event: stdout` — data is a base64-encoded chunk of stdout\n- `event: stderr` — data is a base64-encoded chunk of stderr\n- `event: exit` — data is JSON `{\"exit_code\": N}` (terminal)\n- `event: error` — data is JSON `{\"error\": \"...\", \"code\": \"...\"}` (terminal)",
+					content: { "text/event-stream": { schema: { type: "string" } } }
+				},
+				"400": { $ref: "#/components/responses/InvalidRequest" },
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"403": {
+					description: "cwd resolves outside /workspace.",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "cwd must resolve to a location within /workspace",
+							code: "invalid_request"
+						}
+					} }
+				},
+				"502": {
+					description: "SDK transport error before the SSE stream could be established. Once the stream is open, errors are delivered as `event: error` SSE events instead.",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "exec failed: connection reset",
+							code: "exec_transport_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/v1/sandbox/{id}/file/{path}": {
+			get: {
+				operationId: "readFile",
+				summary: "Read a file from the sandbox filesystem",
+				"x-codeSamples": [{
+					lang: "curl",
+					label: "cURL",
+					source: "curl -X GET https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -o main.py"
+				}],
+				parameters: [
+					{
+						name: "id",
+						in: "path",
+						required: true,
+						schema: { type: "string" },
+						description: "Sandbox instance name."
+					},
+					{
+						name: "path",
+						in: "path",
+						required: true,
+						schema: { type: "string" },
+						description: "File path inside the sandbox, without leading slash (e.g. workspace/main.py). Must resolve within /workspace."
+					},
+					{
+						name: "Session-Id",
+						in: "header",
+						required: false,
+						schema: {
+							type: "string",
+							pattern: "^[a-zA-Z0-9._-]{1,128}$"
+						},
+						description: "Scope this operation to a specific session. Uses the default session if omitted."
+					}
+				],
+				responses: {
+					"200": {
+						description: "Raw file bytes.",
+						content: { "application/octet-stream": { schema: {
+							type: "string",
+							format: "binary"
+						} } }
+					},
+					"400": { $ref: "#/components/responses/InvalidRequest" },
+					"401": { $ref: "#/components/responses/Unauthorized" },
+					"403": {
+						description: "Path resolves outside /workspace.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "path must resolve to a location within /workspace",
+								code: "invalid_request"
+							}
+						} }
+					},
+					"404": {
+						description: "File not found in the sandbox.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "File not found: /workspace/foo.txt",
+								code: "workspace_read_not_found"
+							}
+						} }
+					},
+					"502": {
+						description: "SDK read call failed.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "read failed: connection reset",
+								code: "exec_transport_error"
+							}
+						} }
+					}
+				}
+			},
+			put: {
+				operationId: "writeFile",
+				summary: "Write a file into the sandbox filesystem",
+				"x-codeSamples": [{
+					lang: "curl",
+					label: "cURL",
+					source: "curl -X PUT https://$HOST/v1/sandbox/my-sandbox/file/workspace/main.py \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/octet-stream\" \\\n  --data-binary @main.py"
+				}],
+				parameters: [
+					{
+						name: "id",
+						in: "path",
+						required: true,
+						schema: { type: "string" },
+						description: "Sandbox instance name."
+					},
+					{
+						name: "path",
+						in: "path",
+						required: true,
+						schema: { type: "string" },
+						description: "File path inside the sandbox, without leading slash (e.g. workspace/main.py). Must resolve within /workspace."
+					},
+					{
+						name: "Session-Id",
+						in: "header",
+						required: false,
+						schema: {
+							type: "string",
+							pattern: "^[a-zA-Z0-9._-]{1,128}$"
+						},
+						description: "Scope this operation to a specific session. Uses the default session if omitted."
+					}
+				],
+				requestBody: {
+					required: true,
+					description: "Raw file content to write.",
+					content: { "application/octet-stream": { schema: {
+						type: "string",
+						format: "binary"
+					} } }
+				},
+				responses: {
+					"200": {
+						description: "File written successfully.",
+						content: { "application/json": { schema: { $ref: "#/components/schemas/WriteResponse" } } }
+					},
+					"400": { $ref: "#/components/responses/InvalidRequest" },
+					"401": { $ref: "#/components/responses/Unauthorized" },
+					"403": {
+						description: "Path resolves outside /workspace.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "path must resolve to a location within /workspace",
+								code: "invalid_request"
+							}
+						} }
+					},
+					"502": {
+						description: "SDK write call failed.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "write failed: connection reset",
+								code: "workspace_archive_write_error"
+							}
+						} }
+					}
+				}
+			}
+		},
+		"/v1/sandbox/{id}/pty": { get: {
+			operationId: "ptyTerminal",
+			summary: "Open a PTY terminal session via WebSocket",
+			description: "Upgrades the HTTP connection to a WebSocket and proxies it to a PTY shell inside the sandbox.\n\n**WebSocket frame protocol:**\n\n| Direction | Frame type | Content |\n|-----------|------------|--------------------------------------------------|\n| Client → Server | Binary | UTF-8 encoded keystrokes / input |\n| Server → Client | Binary | Terminal output (including ANSI escape sequences) |\n| Client → Server | Text (JSON) | Control messages, e.g. `{\"type\":\"resize\",\"cols\":120,\"rows\":30}` |\n| Server → Client | Text (JSON) | Status messages: `ready`, `exit`, `error` |\n\n**Status messages (server → client):**\n- `{\"type\":\"ready\"}` — PTY is accepting input\n- `{\"type\":\"exit\",\"code\":0,\"signal\":\"SIGTERM\"}` — PTY exited\n- `{\"type\":\"error\",\"message\":\"...\"}` — error occurred\n\nIf the client disconnects, the PTY stays alive; reconnecting replays buffered output.",
+			"x-codeSamples": [{
+				lang: "JavaScript",
+				label: "WebSocket",
+				source: "const ws = new WebSocket(\"wss://$HOST/v1/sandbox/my-sandbox/pty?cols=120&rows=30\");\nws.binaryType = \"arraybuffer\";\nws.onmessage = (e) => { /* handle binary output or JSON status */ };"
+			}],
+			parameters: [
+				{
+					name: "id",
+					in: "path",
+					required: true,
+					schema: { type: "string" },
+					description: "Sandbox instance name."
+				},
+				{
+					name: "cols",
+					in: "query",
+					required: false,
+					schema: {
+						type: "integer",
+						default: 80
+					},
+					description: "Terminal width in columns."
+				},
+				{
+					name: "rows",
+					in: "query",
+					required: false,
+					schema: {
+						type: "integer",
+						default: 24
+					},
+					description: "Terminal height in rows."
+				},
+				{
+					name: "shell",
+					in: "query",
+					required: false,
+					schema: { type: "string" },
+					description: "Shell binary to run (e.g. `/bin/bash`). Uses the container default if omitted."
+				},
+				{
+					name: "session",
+					in: "query",
+					required: false,
+					schema: { type: "string" },
+					description: "SDK session ID. If provided, the PTY is scoped to this session."
+				},
+				{
+					name: "Session-Id",
+					in: "header",
+					required: false,
+					schema: {
+						type: "string",
+						pattern: "^[a-zA-Z0-9._-]{1,128}$"
+					},
+					description: "Scope this operation to a specific session. Uses the default session if omitted."
+				}
+			],
+			responses: {
+				"101": { description: "WebSocket upgrade successful. Binary and text frames flow bidirectionally as described above." },
+				"400": {
+					description: "Missing `Upgrade: websocket` header or invalid query parameters.",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "WebSocket upgrade required",
+							code: "invalid_request"
+						}
+					} }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": {
+					description: "SDK terminal() call failed.",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "terminal failed: connection reset",
+							code: "exec_transport_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/v1/sandbox/{id}/running": { get: {
+			operationId: "isSandboxRunning",
+			summary: "Check whether the sandbox container is alive",
+			description: "Executes a no-op command inside the sandbox. Always returns HTTP 200; inspect the `running` field.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X GET https://$HOST/v1/sandbox/my-sandbox/running \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+			}],
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}],
+			responses: {
+				"200": {
+					description: "Liveness status (always returned, even when not running).",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/RunningResponse" } } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		} },
+		"/v1/sandbox/{id}/persist": { post: {
+			operationId: "persistWorkspace",
+			summary: "Serialize the sandbox workspace to a tar archive",
+			description: "Archives the /workspace directory inside the sandbox and streams the resulting tar back as raw bytes.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/persist \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -o workspace.tar"
+			}],
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}, {
+				name: "excludes",
+				in: "query",
+				required: false,
+				schema: { type: "string" },
+				description: "Comma-separated list of relative paths to exclude from the archive.",
+				example: "__pycache__,.venv"
+			}],
+			responses: {
+				"200": {
+					description: "Raw tar archive bytes.",
+					content: { "application/octet-stream": { schema: {
+						type: "string",
+						format: "binary"
+					} } }
+				},
+				"400": {
+					description: "Invalid exclude paths (e.g. path traversal).",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "exclude paths must not contain \"..\"",
+							code: "invalid_request"
+						}
+					} }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": {
+					description: "tar command failed inside the sandbox.",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "tar failed (exit 1): ...",
+							code: "workspace_archive_read_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/v1/sandbox/{id}/hydrate": { post: {
+			operationId: "hydrateWorkspace",
+			summary: "Populate the sandbox workspace from a tar archive",
+			description: "Accepts a raw tar archive as the request body and extracts it into /workspace inside the sandbox.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/hydrate \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/octet-stream\" \\\n  --data-binary @workspace.tar"
+			}],
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}],
+			requestBody: {
+				required: true,
+				description: "Raw tar archive bytes.",
+				content: { "application/octet-stream": { schema: {
+					type: "string",
+					format: "binary"
+				} } }
+			},
+			responses: {
+				"200": {
+					description: "Archive extracted successfully.",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+				},
+				"400": { $ref: "#/components/responses/InvalidRequest" },
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": {
+					description: "tar extract failed inside the sandbox.",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "tar extract failed (exit 1): ...",
+							code: "workspace_archive_write_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/v1/sandbox/{id}/mount": { post: {
+			operationId: "mountBucket",
+			summary: "Mount an S3-compatible bucket into the container",
+			description: "Mounts an S3-compatible bucket (R2, S3, GCS, etc.) as a local directory via s3fs-FUSE. Credentials are optional — the SDK auto-detects from Worker secrets when omitted.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/mount \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"bucket\":\"my-bucket\",\"mountPath\":\"/mnt/data\",\"options\":{\"endpoint\":\"https://ACCT.r2.cloudflarestorage.com\"}}'"
+			}],
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}],
+			requestBody: {
+				required: true,
+				content: { "application/json": { schema: { $ref: "#/components/schemas/MountBucketRequest" } } }
+			},
+			responses: {
+				"200": {
+					description: "Bucket mounted successfully.",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+				},
+				"400": { $ref: "#/components/responses/InvalidRequest" },
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": {
+					description: "SDK mount call failed (invalid config, duplicate mount, or s3fs error).",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "mount failed: Mount path already in use",
+							code: "mount_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/v1/sandbox/{id}/unmount": { post: {
+			operationId: "unmountBucket",
+			summary: "Unmount a previously mounted bucket",
+			description: "Unmounts a bucket filesystem that was previously mounted via `/v1/sandbox/{id}/mount`.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/unmount \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mountPath\":\"/mnt/data\"}'"
+			}],
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}],
+			requestBody: {
+				required: true,
+				content: { "application/json": { schema: { $ref: "#/components/schemas/UnmountBucketRequest" } } }
+			},
+			responses: {
+				"200": {
+					description: "Bucket unmounted successfully.",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+				},
+				"400": { $ref: "#/components/responses/InvalidRequest" },
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": {
+					description: "SDK unmount call failed (no active mount or unmount error).",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "unmount failed: No active mount found",
+							code: "unmount_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/v1/sandbox/{id}": { delete: {
+			operationId: "deleteSandbox",
+			summary: "Destroy a sandbox instance (best-effort)",
+			description: "Calls destroy() on the sandbox Durable Object to release container resources. Best-effort: unknown sandbox IDs return 204 without allocating a container.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X DELETE https://$HOST/v1/sandbox/my-sandbox \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+			}],
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}],
+			responses: {
+				"204": { description: "Sandbox destroyed (best-effort). Container resources are released." },
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		} },
+		"/v1/sandbox/{id}/session": { post: {
+			operationId: "createSession",
+			summary: "Create an execution session",
+			description: "Sessions isolate working directory and environment variables across commands. The returned session ID is used with the `Session-Id` header on exec, file, and PTY endpoints.",
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}],
+			requestBody: {
+				required: false,
+				content: { "application/json": { schema: {
+					type: "object",
+					properties: {
+						id: {
+							type: "string",
+							description: "Custom session ID. Auto-generated if omitted."
+						},
+						cwd: {
+							type: "string",
+							description: "Initial working directory for the session."
+						},
+						env: {
+							type: "object",
+							additionalProperties: { type: "string" },
+							description: "Environment variables scoped to this session."
+						}
+					}
+				} } }
+			},
+			responses: {
+				"200": {
+					description: "Session created.",
+					content: { "application/json": { schema: {
+						type: "object",
+						required: ["id"],
+						properties: { id: {
+							type: "string",
+							description: "Session ID to pass via `Session-Id` header."
+						} }
+					} } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": {
+					description: "Session creation failed.",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "session creation failed",
+							code: "session_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/v1/sandbox/{id}/session/{sid}": { delete: {
+			operationId: "deleteSession",
+			summary: "Delete an execution session",
+			description: "Removes a named session. The default session cannot be deleted.",
+			parameters: [{
+				name: "id",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Sandbox instance name."
+			}, {
+				name: "sid",
+				in: "path",
+				required: true,
+				schema: { type: "string" },
+				description: "Session ID to delete."
+			}],
+			responses: {
+				"200": {
+					description: "Session deleted.",
+					content: { "application/json": { schema: {
+						type: "object",
+						required: ["success", "sessionId"],
+						properties: {
+							success: {
+								type: "boolean",
+								description: "`true` if the session was deleted."
+							},
+							sessionId: {
+								type: "string",
+								description: "ID of the deleted session."
+							}
+						}
+					} } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" },
+				"502": {
+					description: "Session deletion failed (e.g. cannot delete default session).",
+					content: { "application/json": {
+						schema: { $ref: "#/components/schemas/ErrorResponse" },
+						example: {
+							error: "cannot delete the default session",
+							code: "session_error"
+						}
+					} }
+				}
+			}
+		} },
+		"/health": { get: {
+			operationId: "healthCheck",
+			summary: "Worker health check",
+			description: "Simple liveness probe. Not protected by authentication.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl https://$HOST/health"
+			}],
+			security: [],
+			responses: { "200": {
+				description: "Worker is up.",
+				content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+			} }
+		} },
+		"/v1/openapi.json": { get: {
+			operationId: "getOpenApiSchema",
+			summary: "OpenAPI schema",
+			description: "Returns this OpenAPI 3.1 schema document.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl https://$HOST/v1/openapi.json \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+			}],
+			responses: {
+				"200": {
+					description: "OpenAPI schema document.",
+					content: { "application/json": { schema: { type: "object" } } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		} },
+		"/v1/pool/stats": { get: {
+			operationId: "getPoolStats",
+			summary: "Pool statistics",
+			description: "Returns current warm pool statistics including warm/assigned counts and configuration.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl https://$HOST/v1/pool/stats \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+			}],
+			responses: {
+				"200": {
+					description: "Pool statistics.",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/PoolStats" } } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		} },
+		"/v1/pool/shutdown-prewarmed": { post: {
+			operationId: "shutdownPrewarmed",
+			summary: "Shutdown pre-warmed containers",
+			description: "Stops all idle (unassigned) warm containers. Does not affect containers assigned to sandbox sessions.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X POST https://$HOST/v1/pool/shutdown-prewarmed \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+			}],
+			responses: {
+				"200": {
+					description: "All pre-warmed containers stopped.",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		} },
+		"/v1/pool/prime": { post: {
+			operationId: "primePool",
+			summary: "Prime the warm pool",
+			description: "Pushes the current pool configuration and starts the alarm loop. Called automatically by the cron trigger; can also be called manually after deploy.",
+			"x-codeSamples": [{
+				lang: "curl",
+				label: "cURL",
+				source: "curl -X POST https://$HOST/v1/pool/prime \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+			}],
+			responses: {
+				"200": {
+					description: "Pool primed successfully.",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/OkResponse" } } }
+				},
+				"401": { $ref: "#/components/responses/Unauthorized" }
+			}
+		} }
+	}
+};
+
+//#endregion
+//#region src/bridge/openapi-html.ts
+/**
+* Renders an OpenAPI 3.x schema object as a self-contained HTML page.
+*
+* No external dependencies — pure HTML/CSS/JS generated server-side.
+* The schema is embedded as JSON and rendered client-side via a small
+* inline script.
+*/
+function renderOpenApiHtml(schema) {
+	const json = JSON.stringify(schema);
+	return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${esc(schema.info?.title ?? "API Reference")}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --bg:        #0f1117;
+      --surface:   #1a1d27;
+      --border:    #2a2d3a;
+      --text:      #e2e8f0;
+      --muted:     #8892a4;
+      --accent:    #6366f1;
+      --get:       #22c55e;
+      --post:      #3b82f6;
+      --put:       #f59e0b;
+      --delete:    #ef4444;
+      --patch:     #a855f7;
+      --radius:    6px;
+      --font-mono: ui-monospace, "Cascadia Code", "Fira Code", monospace;
+    }
+
+    body {
+      background: var(--bg);
+      color: var(--text);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      font-size: 14px;
+      line-height: 1.6;
+      display: flex;
+      min-height: 100vh;
+    }
+
+    /* ── Sidebar ── */
+    #sidebar {
+      width: 260px;
+      min-width: 260px;
+      background: var(--surface);
+      border-right: 1px solid var(--border);
+      padding: 24px 0;
+      position: sticky;
+      top: 0;
+      height: 100vh;
+      overflow-y: auto;
+    }
+    #sidebar h1 {
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--text);
+      padding: 0 20px 16px;
+      border-bottom: 1px solid var(--border);
+      margin-bottom: 12px;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    #sidebar .version {
+      font-size: 11px;
+      color: var(--muted);
+      font-weight: 400;
+    }
+    .nav-item {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      padding: 6px 20px;
+      cursor: pointer;
+      border-left: 2px solid transparent;
+      transition: background 0.15s, border-color 0.15s;
+      text-decoration: none;
+      color: var(--muted);
+      font-size: 13px;
+    }
+    .nav-item:hover { background: rgba(255,255,255,0.04); color: var(--text); }
+    .nav-item.active { border-left-color: var(--accent); color: var(--text); background: rgba(99,102,241,0.08); }
+
+    /* ── Main ── */
+    #main {
+      flex: 1;
+      padding: 40px 48px;
+      max-width: 900px;
+    }
+
+    /* ── Info block ── */
+    #info { margin-bottom: 48px; }
+    #info h2 { font-size: 28px; font-weight: 700; margin-bottom: 8px; }
+    #info p  { color: var(--muted); max-width: 680px; }
+    #info .meta { display: flex; gap: 16px; margin-top: 12px; flex-wrap: wrap; }
+    #info .badge {
+      font-size: 11px;
+      padding: 2px 8px;
+      border-radius: 99px;
+      border: 1px solid var(--border);
+      color: var(--muted);
+      font-family: var(--font-mono);
+    }
+
+    /* ── Endpoint card ── */
+    .endpoint {
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      margin-bottom: 16px;
+      overflow: hidden;
+    }
+    .endpoint-header {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+      padding: 14px 18px;
+      cursor: pointer;
+      background: var(--surface);
+      user-select: none;
+      transition: background 0.15s;
+    }
+    .endpoint-header:hover { background: #1e2130; }
+    .endpoint-header.open  { background: #1e2130; border-bottom: 1px solid var(--border); }
+
+    .method {
+      font-family: var(--font-mono);
+      font-size: 11px;
+      font-weight: 700;
+      padding: 3px 8px;
+      border-radius: 4px;
+      min-width: 58px;
+      text-align: center;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+    .method-get    { background: rgba(34,197,94,.15);  color: var(--get); }
+    .method-post   { background: rgba(59,130,246,.15); color: var(--post); }
+    .method-put    { background: rgba(245,158,11,.15); color: var(--put); }
+    .method-delete { background: rgba(239,68,68,.15);  color: var(--delete); }
+    .method-patch  { background: rgba(168,85,247,.15); color: var(--patch); }
+
+    .endpoint-path {
+      font-family: var(--font-mono);
+      font-size: 13px;
+      color: var(--text);
+      flex: 1;
+    }
+    .endpoint-summary { font-size: 13px; color: var(--muted); }
+    .chevron { color: var(--muted); font-size: 10px; transition: transform 0.2s; }
+    .endpoint-header.open .chevron { transform: rotate(90deg); }
+
+    /* ── Endpoint body ── */
+    .endpoint-body { padding: 20px 18px; display: none; }
+    .endpoint-body.open { display: block; }
+    .endpoint-desc { color: var(--muted); margin-bottom: 16px; font-size: 13px; }
+
+    /* ── Section labels ── */
+    .section-label {
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: var(--muted);
+      margin: 20px 0 10px;
+    }
+    .section-label:first-child { margin-top: 0; }
+
+    /* ── Params table ── */
+    table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    th {
+      text-align: left;
+      padding: 6px 10px;
+      font-weight: 600;
+      font-size: 11px;
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      color: var(--muted);
+      border-bottom: 1px solid var(--border);
+    }
+    td {
+      padding: 8px 10px;
+      border-bottom: 1px solid var(--border);
+      vertical-align: top;
+    }
+    tr:last-child td { border-bottom: none; }
+    .param-name  { font-family: var(--font-mono); color: var(--text); }
+    .param-in    { font-size: 11px; color: var(--muted); }
+    .param-type  { font-family: var(--font-mono); font-size: 11px; color: var(--accent); }
+    .required    { color: var(--delete); font-size: 10px; font-weight: 700; margin-left: 4px; }
+
+    /* ── Response rows ── */
+    .response-group { margin-bottom: 4px; border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; }
+    .response-header {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+      padding: 10px 14px;
+      cursor: pointer;
+      background: var(--surface);
+      user-select: none;
+      transition: background 0.15s;
+      font-size: 13px;
+    }
+    .response-header:hover { background: #1e2130; }
+    .response-header.open { border-bottom: 1px solid var(--border); }
+    .response-detail { padding: 12px 14px; display: none; font-size: 13px; }
+    .response-detail.open { display: block; }
+    .response-detail .section-label { margin-top: 14px; }
+    .response-detail .section-label:first-child { margin-top: 0; }
+    .status-code {
+      font-family: var(--font-mono);
+      font-size: 12px;
+      font-weight: 700;
+      min-width: 40px;
+    }
+    .s2xx { color: var(--get); }
+    .s4xx { color: var(--put); }
+    .s5xx { color: var(--delete); }
+    .response-desc { color: var(--muted); flex: 1; }
+    .response-content-type { font-size: 11px; color: var(--muted); font-family: var(--font-mono); }
+    .resp-chevron { color: var(--muted); font-size: 10px; transition: transform 0.2s; margin-left: auto; }
+    .response-header.open .resp-chevron { transform: rotate(90deg); }
+
+    /* ── Code block ── */
+    pre {
+      background: #0a0c12;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 14px 16px;
+      font-family: var(--font-mono);
+      font-size: 12px;
+      overflow-x: auto;
+      color: var(--text);
+      margin-top: 8px;
+    }
+    pre.example-block { margin-top: 4px; }
+
+    /* ── Code samples ── */
+    .code-samples { margin-top: 4px; }
+    .code-sample-label {
+      font-size: 11px;
+      font-weight: 600;
+      color: var(--muted);
+      font-family: var(--font-mono);
+      margin-bottom: 2px;
+    }
+  </style>
+</head>
+<body>
+  <nav id="sidebar"><h1 id="nav-title"></h1></nav>
+  <main id="main"><div id="info"></div><div id="endpoints"></div></main>
+
+  <script>
+    const schema = ${json};
+
+    // ── helpers ──────────────────────────────────────────────────────
+    function esc(s) {
+      return String(s ?? '').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+    }
+    function el(tag, attrs, ...children) {
+      const e = document.createElement(tag);
+      for (const [k, v] of Object.entries(attrs ?? {})) {
+        if (k === 'class') e.className = v;
+        else if (k === 'html') e.innerHTML = v;
+        else e.setAttribute(k, v);
+      }
+      for (const c of children) {
+        if (c == null) continue;
+        e.append(typeof c === 'string' ? document.createTextNode(c) : c);
+      }
+      return e;
+    }
+    function statusClass(code) {
+      const n = parseInt(code);
+      if (n >= 500) return 's5xx';
+      if (n >= 400) return 's4xx';
+      return 's2xx';
+    }
+    function schemaType(s) {
+      if (!s) return '';
+      if (s.$ref) return s.$ref.split('/').pop();
+      if (s.type === 'array') return s.items ? schemaType(s.items) + '[]' : 'array';
+      return s.format ? s.type + '<' + s.format + '>' : (s.type ?? '');
+    }
+    function resolveRef(ref) {
+      const parts = ref.replace(/^#\\//, '').split('/');
+      return parts.reduce((o, k) => o?.[k], schema);
+    }
+    function resolveResponse(resp) {
+      return resp?.$ref ? resolveRef(resp.$ref) : resp;
+    }
+
+    // ── info ─────────────────────────────────────────────────────────
+    const info = schema.info ?? {};
+    document.title = info.title ?? 'API Reference';
+    document.getElementById('nav-title').innerHTML =
+      esc(info.title ?? 'API Reference') +
+      (info.version ? \` <span class="version">v\${esc(info.version)}</span>\` : '');
+
+    const infoEl = document.getElementById('info');
+    infoEl.append(
+      el('h2', {}, info.title ?? 'API Reference'),
+      el('div', {class:'meta'},
+        info.version ? el('span', {class:'badge'}, 'v' + info.version) : null,
+        el('span', {class:'badge'}, 'OpenAPI ' + (schema.openapi ?? '3.x')),
+      ),
+      info.description ? el('p', {html: esc(info.description).replace(/\`([^\`]+)\`/g, '<code>$1</code>')}) : null,
+    );
+
+    // ── endpoints ────────────────────────────────────────────────────
+    const container = document.getElementById('endpoints');
+    const nav = document.getElementById('sidebar');
+    const methods = ['get','post','put','patch','delete'];
+
+    for (const [path, pathItem] of Object.entries(schema.paths ?? {})) {
+      for (const method of methods) {
+        const op = pathItem[method];
+        if (!op) continue;
+
+        const id = method + '_' + path.replace(/[^a-z0-9]/gi, '_');
+
+        // nav link
+        const navLink = el('a', {class:'nav-item', href:'#'+id});
+        navLink.append(
+          el('span', {class:'method method-'+method}, method),
+          el('span', {}, path),
+        );
+        nav.append(navLink);
+
+        // card header
+        const header = el('div', {class:'endpoint-header', id});
+        header.append(
+          el('span', {class:'method method-'+method}, method),
+          el('span', {class:'endpoint-path'}, path),
+          op.summary ? el('span', {class:'endpoint-summary'}, op.summary) : null,
+          el('span', {class:'chevron'}, '▶'),
+        );
+
+        // card body
+        const body = el('div', {class:'endpoint-body'});
+
+        if (op.description) {
+          body.append(el('p', {class:'endpoint-desc', html:
+            esc(op.description).replace(/\`([^\`]+)\`/g,'<code>$1</code>')}));
+        }
+
+        // parameters
+        const params = op.parameters ?? [];
+        if (params.length) {
+          body.append(el('div', {class:'section-label'}, 'Parameters'));
+          const tbl = el('table', {});
+          tbl.append(el('thead', {}, el('tr', {},
+            el('th',{},'Name'), el('th',{},'In'), el('th',{},'Type'), el('th',{},'Description')
+          )));
+          const tbody = el('tbody', {});
+          for (const p of params) {
+            const nameCell = el('td', {class:'param-name'}, p.name);
+            if (p.required) nameCell.append(el('span', {class:'required'}, '*'));
+            tbody.append(el('tr', {},
+              nameCell,
+              el('td', {class:'param-in'}, p.in),
+              el('td', {class:'param-type'}, schemaType(p.schema)),
+              el('td', {class:'response-desc'}, p.description ?? ''),
+            ));
+          }
+          tbl.append(tbody);
+          body.append(tbl);
+        }
+
+        // request body
+        if (op.requestBody) {
+          body.append(el('div', {class:'section-label'}, 'Request Body'));
+          const content = op.requestBody.content ?? {};
+          for (const [ct, media] of Object.entries(content)) {
+            body.append(el('div', {class:'param-in'}, ct));
+            if (media.schema) {
+              const resolved = media.schema.$ref ? resolveRef(media.schema.$ref) : media.schema;
+              if (resolved?.properties) {
+                const tbl = el('table', {});
+                tbl.append(el('thead', {}, el('tr', {},
+                  el('th',{},'Field'), el('th',{},'Type'), el('th',{},'Description')
+                )));
+                const tbody = el('tbody', {});
+                const required = new Set(resolved.required ?? []);
+                for (const [name, prop] of Object.entries(resolved.properties)) {
+                  const nameCell = el('td', {class:'param-name'}, name);
+                  if (required.has(name)) nameCell.append(el('span', {class:'required'}, '*'));
+                  tbody.append(el('tr', {},
+                    nameCell,
+                    el('td', {class:'param-type'}, schemaType(prop)),
+                    el('td', {class:'response-desc'}, prop.description ?? ''),
+                  ));
+                }
+                tbl.append(tbody);
+                body.append(tbl);
+              }
+            }
+          }
+        }
+
+        // responses
+        if (op.responses) {
+          body.append(el('div', {class:'section-label'}, 'Responses'));
+          const wrap = el('div', {});
+          for (const [code, resp] of Object.entries(op.responses)) {
+            const resolved = resolveResponse(resp);
+            const hasContent = resolved?.content && Object.keys(resolved.content).length > 0;
+
+            const group = el('div', {class:'response-group'});
+            const respHeader = el('div', {class:'response-header'});
+            respHeader.append(
+              el('span', {class:'status-code ' + statusClass(code)}, code),
+              el('span', {class:'response-desc'}, resolved?.description ?? ''),
+              hasContent ? el('span', {class:'resp-chevron'}, '\u25B6') : null,
+            );
+            group.append(respHeader);
+
+            if (hasContent) {
+              const detail = el('div', {class:'response-detail'});
+              for (const [ct, media] of Object.entries(resolved.content)) {
+                detail.append(el('div', {class:'response-content-type'}, ct));
+
+                // Render response schema fields
+                if (media.schema) {
+                  const resolvedSchema = media.schema.$ref ? resolveRef(media.schema.$ref) : media.schema;
+                  if (resolvedSchema?.properties) {
+                    detail.append(el('div', {class:'section-label'}, 'Schema'));
+                    const tbl = el('table', {});
+                    tbl.append(el('thead', {}, el('tr', {},
+                      el('th',{},'Field'), el('th',{},'Type'), el('th',{},'Description')
+                    )));
+                    const tbody = el('tbody', {});
+                    const required = new Set(resolvedSchema.required ?? []);
+                    for (const [name, prop] of Object.entries(resolvedSchema.properties)) {
+                      const nameCell = el('td', {class:'param-name'}, name);
+                      if (required.has(name)) nameCell.append(el('span', {class:'required'}, '*'));
+                      tbody.append(el('tr', {},
+                        nameCell,
+                        el('td', {class:'param-type'}, schemaType(prop)),
+                        el('td', {class:'response-desc'}, prop.description ?? ''),
+                      ));
+                    }
+                    tbl.append(tbody);
+                    detail.append(tbl);
+                  }
+                }
+
+                // Render response example
+                if (media.example !== undefined) {
+                  detail.append(el('div', {class:'section-label'}, 'Example'));
+                  detail.append(el('pre', {class:'example-block'}, JSON.stringify(media.example, null, 2)));
+                }
+                if (media.examples) {
+                  detail.append(el('div', {class:'section-label'}, 'Examples'));
+                  for (const [exName, exObj] of Object.entries(media.examples)) {
+                    const val = exObj?.value ?? exObj;
+                    detail.append(el('pre', {class:'example-block'}, '// ' + exName + '\\n' + JSON.stringify(val, null, 2)));
+                  }
+                }
+              }
+
+              respHeader.addEventListener('click', () => {
+                const open = respHeader.classList.toggle('open');
+                detail.classList.toggle('open', open);
+              });
+              group.append(detail);
+            }
+
+            wrap.append(group);
+          }
+          body.append(wrap);
+        }
+
+        // x-codeSamples
+        const samples = op['x-codeSamples'];
+        if (samples && samples.length) {
+          body.append(el('div', {class:'section-label'}, 'Example'));
+          const samplesWrap = el('div', {class:'code-samples'});
+          for (const sample of samples) {
+            samplesWrap.append(
+              el('div', {class:'code-sample-label'}, sample.label ?? sample.lang ?? 'Example'),
+              el('pre', {}, sample.source),
+            );
+          }
+          body.append(samplesWrap);
+        }
+
+        // toggle
+        header.addEventListener('click', () => {
+          const open = header.classList.toggle('open');
+          body.classList.toggle('open', open);
+          // sync nav highlight
+          document.querySelectorAll('.nav-item').forEach(n => n.classList.remove('active'));
+          if (open) navLink.classList.add('active');
+        });
+
+        const card = el('div', {class:'endpoint'});
+        card.append(header, body);
+        container.append(card);
+      }
+    }
+
+    // highlight nav on scroll
+    const observer = new IntersectionObserver(entries => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          const id = entry.target.id;
+          document.querySelectorAll('.nav-item').forEach(n => {
+            n.classList.toggle('active', n.getAttribute('href') === '#' + id);
+          });
+        }
+      }
+    }, { threshold: 0.5 });
+    document.querySelectorAll('.endpoint-header[id]').forEach(h => observer.observe(h));
+  <\/script>
+</body>
+</html>`;
+}
+function esc(s) {
+	return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+//#endregion
+//#region src/bridge/routes.ts
+/** Typed wrapper around the SDK's getSandbox() that returns a BridgeSandbox. */
+function getSandbox$1(ns, containerUUID) {
+	return getSandbox(ns, containerUUID);
+}
+function createBridgeApp(config) {
+	const app = new Hono();
+	const { sandboxBinding, warmPoolBinding, apiPrefix } = config;
+	function getSandboxNs(env$1) {
+		return env$1[sandboxBinding];
+	}
+	function getWarmPoolNs(env$1) {
+		return env$1[warmPoolBinding];
+	}
+	app.use(`${apiPrefix}/sandbox/*`, async (c, next) => {
+		const sandboxId = new URL(c.req.url).pathname.split("/")[apiPrefix.split("/").filter(Boolean).length + 2];
+		if (sandboxId && !/^[a-z2-7]{1,128}$/.test(sandboxId)) return errorJson("Invalid sandbox ID format", "invalid_request", 400);
+		const token = c.env.SANDBOX_API_KEY;
+		if (token) {
+			const authHeader = c.req.header("Authorization") ?? "";
+			if ((authHeader.toLowerCase().startsWith("bearer ") ? authHeader.slice(7) : "") !== token) return errorJson("Unauthorized", "unauthorized", 401);
+		}
+		return next();
+	});
+	app.post(`${apiPrefix}/sandbox`, async (c) => {
+		const token = c.env.SANDBOX_API_KEY;
+		if (token) {
+			const authHeader = c.req.header("Authorization") ?? "";
+			if ((authHeader.toLowerCase().startsWith("bearer ") ? authHeader.slice(7) : "") !== token) return errorJson("Unauthorized", "unauthorized", 401);
+		}
+		const bytes = new Uint8Array(16);
+		crypto.getRandomValues(bytes);
+		const id = base32Encode(bytes);
+		return c.json({ id });
+	});
+	app.use(`${apiPrefix}/sandbox/:id/*`, async (c, next) => {
+		const sandboxId = c.req.param("id");
+		const warmTarget = Number.parseInt(c.env.WARM_POOL_TARGET || "0", 10) || 0;
+		const refreshInterval = Number.parseInt(c.env.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
+		const poolNs = getWarmPoolNs(c.env);
+		const poolId = poolNs.idFromName("global-pool");
+		const poolStub = poolNs.get(poolId);
+		try {
+			await poolStub.configure({
+				warmTarget,
+				refreshInterval
+			});
+			const containerUUID = await poolStub.getContainer(sandboxId);
+			c.set("containerUUID", containerUUID);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			if (msg.includes("instance limit reached")) return errorJson(msg, "capacity_exceeded", 503);
+			return errorJson(`pool error: ${msg}`, "pool_error", 502);
+		}
+		return next();
+	});
+	app.use(`${apiPrefix}/sandbox/:id`, async (c, next) => {
+		if (c.req.method !== "DELETE") return next();
+		const sandboxId = c.req.param("id");
+		const poolNs = getWarmPoolNs(c.env);
+		const poolId = poolNs.idFromName("global-pool");
+		const poolStub = poolNs.get(poolId);
+		try {
+			const containerUUID = await poolStub.lookupContainer(sandboxId);
+			if (!containerUUID) return new Response(null, { status: 204 });
+			c.set("containerUUID", containerUUID);
+		} catch (err) {
+			return errorJson(`pool error: ${err instanceof Error ? err.message : String(err)}`, "pool_error", 502);
+		}
+		return next();
+	});
+	app.post(`${apiPrefix}/sandbox/:id/exec`, async (c) => {
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return errorJson("Invalid JSON body", "invalid_request", 400);
+		}
+		if (!Array.isArray(body.argv) || body.argv.length === 0) return errorJson("argv must be a non-empty array", "invalid_request", 400);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const rawSessionId = c.req.header("Session-Id");
+		let executor = sandbox;
+		if (rawSessionId) {
+			const sessionId = validateSessionId(rawSessionId);
+			if (!sessionId) return errorJson("Invalid session ID format", "invalid_request", 400);
+			executor = await sandbox.getSession(sessionId);
+		}
+		const command = body.argv.map(shellQuote).join(" ");
+		const opts = {};
+		if (typeof body.timeout_ms === "number") opts.timeout = body.timeout_ms;
+		if (typeof body.cwd === "string") {
+			const resolvedCwd = resolveWorkspacePath(body.cwd);
+			if (!resolvedCwd) return errorJson("cwd must resolve to a location within /workspace", "invalid_request", 403);
+			opts.cwd = resolvedCwd;
+		}
+		const { readable, writable } = new TransformStream();
+		const writer = writable.getWriter();
+		const encoder = new TextEncoder();
+		let closed = false;
+		let lastWrite = Promise.resolve();
+		/** Write a single SSE event. Chains on the previous write to respect backpressure. */
+		function writeSSE(event, data) {
+			if (closed) return;
+			const payload = data.split("\n").map((line) => `data: ${line}`).join("\n");
+			lastWrite = lastWrite.then(() => writer.write(encoder.encode(`event: ${event}\n${payload}\n\n`)));
+		}
+		function closeStream() {
+			if (closed) return;
+			closed = true;
+			lastWrite.then(() => writer.close()).catch(() => {});
+		}
+		executor.exec(command, {
+			...opts,
+			stream: true,
+			onOutput(stream, data) {
+				writeSSE(stream, toBase64(data));
+			},
+			onComplete(result) {
+				writeSSE("exit", JSON.stringify({ exit_code: result.exitCode }));
+				closeStream();
+			},
+			onError(err) {
+				writeSSE("error", JSON.stringify({
+					error: err.message,
+					code: "exec_error"
+				}));
+				closeStream();
+			}
+		}).catch((err) => {
+			const msg = err instanceof Error ? err.message : String(err);
+			writeSSE("error", JSON.stringify({
+				error: `exec failed: ${msg}`,
+				code: "exec_transport_error"
+			}));
+			closeStream();
+		});
+		return new Response(readable, {
+			status: 200,
+			headers: {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache"
+			}
+		});
+	});
+	app.get(`${apiPrefix}/sandbox/:id/file/*`, async (c) => {
+		const sandboxId = c.req.param("id");
+		const fullPath = c.req.path;
+		const marker = `${apiPrefix}/sandbox/${sandboxId}/file/`;
+		const relativePath = fullPath.slice(marker.length);
+		if (!relativePath) return errorJson("file path must not be empty", "invalid_request", 400);
+		const resolvedPath = resolveWorkspacePath("/" + relativePath);
+		if (!resolvedPath) return errorJson("path must resolve to a location within /workspace", "invalid_request", 403);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const rawSessionId = c.req.header("Session-Id");
+		let executor = sandbox;
+		if (rawSessionId) {
+			const sessionId = validateSessionId(rawSessionId);
+			if (!sessionId) return errorJson("Invalid session ID format", "invalid_request", 400);
+			executor = await sandbox.getSession(sessionId);
+		}
+		try {
+			const stream = await executor.readFileStream(resolvedPath);
+			return new Response(sseToByteStream(stream), {
+				status: 200,
+				headers: { "Content-Type": "application/octet-stream" }
+			});
+		} catch (err) {
+			if (err.code === "FILE_NOT_FOUND") return errorJson(`File not found: ${resolvedPath}`, "workspace_read_not_found", 404);
+			return errorJson(`read failed: ${err instanceof Error ? err.message : String(err)}`, "exec_transport_error", 502);
+		}
+	});
+	app.put(`${apiPrefix}/sandbox/:id/file/*`, async (c) => {
+		const sandboxId = c.req.param("id");
+		const fullPath = c.req.path;
+		const marker = `${apiPrefix}/sandbox/${sandboxId}/file/`;
+		const relativePath = fullPath.slice(marker.length);
+		if (!relativePath) return errorJson("file path must not be empty", "invalid_request", 400);
+		const resolvedPath = resolveWorkspacePath("/" + relativePath);
+		if (!resolvedPath) return errorJson("path must resolve to a location within /workspace", "invalid_request", 403);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const rawSessionId = c.req.header("Session-Id");
+		let executor = sandbox;
+		if (rawSessionId) {
+			const sessionId = validateSessionId(rawSessionId);
+			if (!sessionId) return errorJson("Invalid session ID format", "invalid_request", 400);
+			executor = await sandbox.getSession(sessionId);
+		}
+		try {
+			const buffer = await c.req.arrayBuffer();
+			const MAX_WRITE_BYTES = 32 * 1024 * 1024;
+			if (buffer.byteLength > MAX_WRITE_BYTES) return errorJson(`payload too large: ${buffer.byteLength} bytes exceeds the ${MAX_WRITE_BYTES}-byte limit`, "payload_too_large", 413);
+			const bytes = new Uint8Array(buffer);
+			let b64 = "";
+			const CHUNK = 6144;
+			for (let i = 0; i < bytes.length; i += CHUNK) b64 += btoa(String.fromCharCode(...bytes.subarray(i, i + CHUNK)));
+			await executor.writeFile(resolvedPath, b64, { encoding: "base64" });
+			return c.json({ ok: true });
+		} catch (err) {
+			return errorJson(`write failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_write_error", 502);
+		}
+	});
+	app.get(`${apiPrefix}/sandbox/:id/running`, async (c) => {
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		try {
+			await sandbox.exec("true");
+			return c.json({ running: true });
+		} catch {
+			return c.json({ running: false });
+		}
+	});
+	app.get(`${apiPrefix}/sandbox/:id/pty`, async (c) => {
+		const upgrade = c.req.header("Upgrade");
+		if (!upgrade || upgrade.toLowerCase() !== "websocket") return errorJson("WebSocket upgrade required", "invalid_request", 400);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const colsParam = c.req.query("cols");
+		const rowsParam = c.req.query("rows");
+		const shell = c.req.query("shell");
+		const sessionId = c.req.header("Session-Id") || c.req.query("session");
+		const cols = colsParam ? Number(colsParam) : 80;
+		const rows = rowsParam ? Number(rowsParam) : 24;
+		if (Number.isNaN(cols) || Number.isNaN(rows)) return errorJson("cols and rows must be valid numbers", "invalid_request", 400);
+		const opts = {
+			cols,
+			rows
+		};
+		if (shell) opts.shell = shell;
+		try {
+			if (sessionId) {
+				const validatedId = validateSessionId(sessionId);
+				if (!validatedId) return errorJson("Invalid session ID format", "invalid_request", 400);
+				return await (await sandbox.getSession(validatedId)).terminal(c.req.raw, opts);
+			}
+			return await sandbox.terminal(c.req.raw, opts);
+		} catch (err) {
+			return errorJson(`terminal failed: ${err instanceof Error ? err.message : String(err)}`, "exec_transport_error", 502);
+		}
+	});
+	app.post(`${apiPrefix}/sandbox/:id/persist`, async (c) => {
+		const root = "/workspace";
+		const excludesParam = c.req.query("excludes") ?? "";
+		const excludes = excludesParam ? excludesParam.split(",").filter((s) => s.length > 0) : [];
+		for (const ex of excludes) if (ex.includes("..")) return errorJson("exclude paths must not contain \"..\"", "invalid_request", 400);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const tmpPath = `/tmp/sandbox-persist-${Date.now()}.tar`;
+		const excludeArgs = excludes.map((rel) => `--exclude ${shellQuote("./" + rel.replace(/^\.\//, ""))}`).join(" ");
+		const tarCmd = excludeArgs ? `tar cf ${shellQuote(tmpPath)} ${excludeArgs} -C ${shellQuote(root)} .` : `tar cf ${shellQuote(tmpPath)} -C ${shellQuote(root)} .`;
+		try {
+			const result = await sandbox.exec(tarCmd);
+			if (result.exitCode !== 0) return errorJson(`tar failed (exit ${result.exitCode}): ${result.stderr}`, "workspace_archive_read_error", 502);
+			const stream = await sandbox.readFileStream(tmpPath);
+			sandbox.exec(`rm -f ${shellQuote(tmpPath)}`).catch(() => {});
+			return new Response(sseToByteStream(stream), {
+				status: 200,
+				headers: { "Content-Type": "application/octet-stream" }
+			});
+		} catch (err) {
+			return errorJson(`persist failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_read_error", 502);
+		}
+	});
+	app.post(`${apiPrefix}/sandbox/:id/hydrate`, async (c) => {
+		const root = "/workspace";
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		let tarBytes;
+		try {
+			const buffer = await c.req.arrayBuffer();
+			tarBytes = new Uint8Array(buffer);
+		} catch {
+			return errorJson("Could not read request body", "invalid_request", 400);
+		}
+		if (tarBytes.byteLength === 0) return errorJson("Empty tar payload", "invalid_request", 400);
+		const MAX_HYDRATE_BYTES = 32 * 1024 * 1024;
+		if (tarBytes.byteLength > MAX_HYDRATE_BYTES) return errorJson(`tar payload too large: ${tarBytes.byteLength} bytes exceeds the ${MAX_HYDRATE_BYTES}-byte limit`, "invalid_request", 400);
+		try {
+			await sandbox.exec(`mkdir -p ${shellQuote(root)}`);
+			const tmpPath = `/tmp/sandbox-hydrate-${Date.now()}.tar`;
+			let b64 = "";
+			const CHUNK = 6144;
+			for (let i = 0; i < tarBytes.length; i += CHUNK) b64 += btoa(String.fromCharCode(...tarBytes.subarray(i, i + CHUNK)));
+			await sandbox.writeFile(tmpPath, b64, { encoding: "base64" });
+			const extractResult = await sandbox.exec(`tar xf ${shellQuote(tmpPath)} -C ${shellQuote(root)} && rm -f ${shellQuote(tmpPath)}`);
+			if (extractResult.exitCode !== 0) return errorJson(`tar extract failed (exit ${extractResult.exitCode}): ${extractResult.stderr}`, "workspace_archive_write_error", 502);
+			return c.json({ ok: true });
+		} catch (err) {
+			return errorJson(`hydrate failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_write_error", 502);
+		}
+	});
+	app.post(`${apiPrefix}/sandbox/:id/mount`, async (c) => {
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return errorJson("Invalid JSON body", "invalid_request", 400);
+		}
+		if (!body.bucket || typeof body.bucket !== "string") return errorJson("bucket must be a non-empty string", "invalid_request", 400);
+		if (!body.mountPath || typeof body.mountPath !== "string") return errorJson("mountPath must be a non-empty string", "invalid_request", 400);
+		if (!body.mountPath.startsWith("/")) return errorJson("mountPath must be an absolute path (start with /)", "invalid_request", 400);
+		if (!body.options || typeof body.options !== "object") return errorJson("options must be an object", "invalid_request", 400);
+		if (!body.options.endpoint || typeof body.options.endpoint !== "string") return errorJson("options.endpoint must be a non-empty string", "invalid_request", 400);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const sdkOptions = { endpoint: body.options.endpoint };
+		if (body.options.readOnly !== void 0) sdkOptions.readOnly = body.options.readOnly;
+		if (body.options.prefix !== void 0) sdkOptions.prefix = body.options.prefix;
+		if (body.options.credentials) sdkOptions.credentials = {
+			accessKeyId: body.options.credentials.accessKeyId,
+			secretAccessKey: body.options.credentials.secretAccessKey
+		};
+		try {
+			await sandbox.mountBucket(body.bucket, body.mountPath, sdkOptions);
+			return c.json({ ok: true });
+		} catch (err) {
+			return errorJson(`mount failed: ${err instanceof Error ? err.message : String(err)}`, "mount_error", 502);
+		}
+	});
+	app.post(`${apiPrefix}/sandbox/:id/unmount`, async (c) => {
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return errorJson("Invalid JSON body", "invalid_request", 400);
+		}
+		if (!body.mountPath || typeof body.mountPath !== "string") return errorJson("mountPath must be a non-empty string", "invalid_request", 400);
+		if (!body.mountPath.startsWith("/")) return errorJson("mountPath must be an absolute path (start with /)", "invalid_request", 400);
+		const normalizedPath = new URL(body.mountPath, "file:///").pathname;
+		if (normalizedPath === "/") return errorJson("mountPath must not resolve to / (filesystem root)", "invalid_request", 400);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		try {
+			await sandbox.unmountBucket(normalizedPath);
+			const quoted = shellQuote(normalizedPath);
+			try {
+				await sandbox.exec(`mountpoint -q ${quoted} || rmdir ${quoted}`);
+			} catch {}
+			return c.json({ ok: true });
+		} catch (err) {
+			return errorJson(`unmount failed: ${err instanceof Error ? err.message : String(err)}`, "unmount_error", 502);
+		}
+	});
+	app.post(`${apiPrefix}/sandbox/:id/session`, async (c) => {
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		let body = {};
+		try {
+			body = await c.req.json();
+		} catch {}
+		try {
+			const session = await sandbox.createSession(body);
+			return c.json({ id: session.id });
+		} catch (err) {
+			return errorJson(`session create failed: ${err instanceof Error ? err.message : String(err)}`, "session_error", 502);
+		}
+	});
+	app.delete(`${apiPrefix}/sandbox/:id/session/:sid`, async (c) => {
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		const sid = c.req.param("sid");
+		try {
+			const result = await sandbox.deleteSession(sid);
+			return c.json(result);
+		} catch (err) {
+			return errorJson(`session delete failed: ${err instanceof Error ? err.message : String(err)}`, "session_error", 502);
+		}
+	});
+	app.delete(`${apiPrefix}/sandbox/:id`, async (c) => {
+		const containerUUID = c.get("containerUUID");
+		const sandbox = getSandbox$1(getSandboxNs(c.env), containerUUID);
+		try {
+			await sandbox.destroy();
+		} catch {}
+		try {
+			const poolNs = getWarmPoolNs(c.env);
+			const poolId = poolNs.idFromName("global-pool");
+			await poolNs.get(poolId).reportStopped(containerUUID);
+		} catch {}
+		return new Response(null, { status: 204 });
+	});
+	app.get(config.healthPath, (c) => {
+		const errors = [];
+		if (!c.env[sandboxBinding]) errors.push(`Missing required Durable Object binding "${sandboxBinding}". Ensure your wrangler.jsonc has a binding named "${sandboxBinding}".`);
+		if (!c.env[warmPoolBinding]) errors.push(`Missing required Durable Object binding "${warmPoolBinding}". Ensure your wrangler.jsonc has a binding named "${warmPoolBinding}".`);
+		if (errors.length > 0) return c.json({
+			ok: false,
+			errors
+		}, 503);
+		return c.json({ ok: true });
+	});
+	app.use(`${apiPrefix}/pool/*`, async (c, next) => {
+		const token = c.env.SANDBOX_API_KEY;
+		if (token) {
+			const authHeader = c.req.header("Authorization") ?? "";
+			if ((authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "") !== token) return errorJson("Unauthorized", "unauthorized", 401);
+		}
+		return next();
+	});
+	app.get(`${apiPrefix}/pool/stats`, async (c) => {
+		const warmTarget = Number.parseInt(c.env.WARM_POOL_TARGET || "0", 10) || 0;
+		const refreshInterval = Number.parseInt(c.env.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
+		const poolNs = getWarmPoolNs(c.env);
+		const poolId = poolNs.idFromName("global-pool");
+		const poolStub = poolNs.get(poolId);
+		try {
+			await poolStub.configure({
+				warmTarget,
+				refreshInterval
+			});
+		} catch {}
+		const stats = await poolStub.getStats();
+		return c.json(stats);
+	});
+	app.post(`${apiPrefix}/pool/shutdown-prewarmed`, async (c) => {
+		const warmTarget = Number.parseInt(c.env.WARM_POOL_TARGET || "0", 10) || 0;
+		const refreshInterval = Number.parseInt(c.env.WARM_POOL_REFRESH_INTERVAL || "10000", 10) || 1e4;
+		const poolNs = getWarmPoolNs(c.env);
+		const poolId = poolNs.idFromName("global-pool");
+		const poolStub = poolNs.get(poolId);
+		try {
+			await poolStub.configure({
+				warmTarget,
+				refreshInterval
+			});
+		} catch {}
+		await poolStub.shutdownPrewarmed();
+		return c.json({ ok: true });
+	});
+	app.post(`${apiPrefix}/pool/prime`, async (c) => {
+		await primePool(c.env, warmPoolBinding);
+		return c.json({ ok: true });
+	});
+	const openapiAuth = async (c, next) => {
+		const token = c.env.SANDBOX_API_KEY;
+		if (token) {
+			const authHeader = c.req.header("Authorization") ?? "";
+			const provided = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+			const queryToken = c.req.query("token") ?? "";
+			if (provided !== token && queryToken !== token) return errorJson("Unauthorized", "unauthorized", 401);
+		}
+		return next();
+	};
+	const openapiHtmlHandler = () => new Response(renderOpenApiHtml(OPENAPI_SCHEMA), { headers: { "Content-Type": "text/html; charset=utf-8" } });
+	app.get(`${apiPrefix}/openapi.json`, openapiAuth, (c) => c.json(OPENAPI_SCHEMA));
+	app.get(`${apiPrefix}/openapi.html`, openapiAuth, openapiHtmlHandler);
+	app.get(`${apiPrefix}/openapi`, openapiAuth, openapiHtmlHandler);
+	return app;
+}
+
+//#endregion
+//#region src/bridge/warm-pool.ts
+/**
+* WarmPool — Durable Object that maintains a pool of pre-started sandbox containers.
+*
+* Adapted from https://github.com/mikenomitch/cf-container-warm-pool
+* Inlined and tailored for the @cloudflare/sandbox SDK.
+*
+* The pool keeps N idle containers standing by so new sandbox sessions boot
+* instantly.  Once a container is assigned to a sandbox ID it is consumed and
+* never returned to the pool.
+*
+* Configuration is pushed in via `configure()` on every request (idempotent)
+* so changes to wrangler vars take effect without manual intervention.
+*/
+const DEFAULT_CONFIG = {
+	warmTarget: 0,
+	refreshInterval: 1e4
+};
+var WarmPool = class extends DurableObject {
+	config = { ...DEFAULT_CONFIG };
+	/** Container UUIDs that are warm and available for assignment */
+	warmContainers = /* @__PURE__ */ new Set();
+	/** Maps caller-provided sandbox IDs to container UUIDs (1:1, no sharing) */
+	assignments = /* @__PURE__ */ new Map();
+	/** Containers currently starting — excluded from health checks */
+	startingContainers = /* @__PURE__ */ new Set();
+	/** Inferred max_instances limit learned from Cloudflare errors, or null */
+	knownMaxInstances = null;
+	capacityExhausted = false;
+	initialized = false;
+	/**
+	* Get a container UUID for the given sandbox ID.
+	* - If this ID already has an assigned container that's still running, return it.
+	* - Otherwise assign a warm container (or start a new one).
+	*/
+	async getContainer(sandboxId) {
+		await this.init();
+		const existing = this.assignments.get(sandboxId);
+		if (existing) {
+			if (await this.isContainerRunning(existing)) return existing;
+			this.assignments.delete(sandboxId);
+			await this.persist();
+		}
+		if (this.warmContainers.size > 0) {
+			const containerUUID$1 = this.warmContainers.values().next().value;
+			this.warmContainers.delete(containerUUID$1);
+			this.assignments.set(sandboxId, containerUUID$1);
+			await this.persist();
+			return containerUUID$1;
+		}
+		if (this.remainingCapacity() <= 0) this.throwCapacityError();
+		const containerUUID = await this.startContainer();
+		if (containerUUID) {
+			this.assignments.set(sandboxId, containerUUID);
+			await this.persist();
+			return containerUUID;
+		}
+		if (this.capacityExhausted) this.throwCapacityError();
+		throw new Error("Failed to start container");
+	}
+	/**
+	* Look up an existing container assignment without allocating.
+	* Returns the container UUID if the sandbox ID has an active assignment, null otherwise.
+	* Used by DELETE to avoid starting a container just to destroy it.
+	*/
+	async lookupContainer(sandboxId) {
+		await this.init();
+		const existing = this.assignments.get(sandboxId);
+		if (existing) return existing;
+		return null;
+	}
+	/**
+	* Report that a container has stopped — removes it from tracking.
+	*/
+	async reportStopped(containerUUID) {
+		await this.init();
+		this.removeContainer(containerUUID);
+		await this.persist();
+	}
+	/**
+	* Get current pool statistics.
+	*/
+	async getStats() {
+		await this.init();
+		return {
+			warm: this.warmContainers.size,
+			assigned: this.assignments.size,
+			total: this.warmContainers.size + this.assignments.size,
+			config: this.config,
+			maxInstances: this.knownMaxInstances
+		};
+	}
+	/**
+	* Update pool configuration. Idempotent — called on every request to keep
+	* config in sync with wrangler vars across deploys.
+	*/
+	async configure(config) {
+		await this.init();
+		this.config = {
+			...DEFAULT_CONFIG,
+			...config
+		};
+		await this.ctx.storage.put("config", this.config);
+	}
+	/**
+	* Shutdown all pre-warmed (unassigned) containers.
+	* Does not affect containers that are assigned to sandbox IDs.
+	*/
+	async shutdownPrewarmed() {
+		await this.init();
+		for (const containerUUID of [...this.warmContainers]) try {
+			await this.getSandboxStub(containerUUID).stop();
+			this.warmContainers.delete(containerUUID);
+		} catch (error) {
+			console.error({
+				message: "Failed to stop container",
+				component: "warm-pool",
+				containerUUID,
+				error
+			});
+		}
+		await this.persist();
+	}
+	async alarm() {
+		await this.init();
+		this.capacityExhausted = false;
+		try {
+			await this.checkContainerHealth();
+			await this.adjustPool();
+			await this.keepWarmContainersAlive();
+		} catch (error) {
+			console.error({
+				message: "Alarm handler error",
+				component: "warm-pool",
+				error
+			});
+		}
+		await this.ctx.storage.setAlarm(Date.now() + this.config.refreshInterval);
+	}
+	async init() {
+		if (this.initialized) return;
+		const storedWarm = await this.ctx.storage.get("warmContainers");
+		if (storedWarm) this.warmContainers = new Set(storedWarm);
+		const storedAssignments = await this.ctx.storage.get("assignments");
+		if (storedAssignments) this.assignments = new Map(storedAssignments);
+		const storedConfig = await this.ctx.storage.get("config");
+		if (storedConfig) this.config = {
+			...DEFAULT_CONFIG,
+			...storedConfig
+		};
+		const storedMax = await this.ctx.storage.get("knownMaxInstances");
+		if (storedMax !== void 0) this.knownMaxInstances = storedMax;
+		this.initialized = true;
+		await this.scheduleRefresh();
+	}
+	async persist() {
+		await this.ctx.storage.put("warmContainers", this.warmContainers);
+		await this.ctx.storage.put("assignments", this.assignments);
+		if (this.knownMaxInstances !== null) await this.ctx.storage.put("knownMaxInstances", this.knownMaxInstances);
+		else await this.ctx.storage.delete("knownMaxInstances");
+	}
+	async scheduleRefresh() {
+		if (!await this.ctx.storage.getAlarm()) await this.ctx.storage.setAlarm(Date.now() + this.config.refreshInterval);
+	}
+	async startContainer() {
+		const containerUUID = crypto.randomUUID();
+		this.startingContainers.add(containerUUID);
+		try {
+			await this.getSandboxStub(containerUUID).startAndWaitForPorts();
+			console.info({
+				message: "Container started",
+				component: "warm-pool",
+				containerUUID
+			});
+			return containerUUID;
+		} catch (error) {
+			if (this.isMaxInstancesError(error)) await this.recordCapacityLimit();
+			else console.error({
+				message: "Failed to start container",
+				component: "warm-pool",
+				containerUUID,
+				error
+			});
+			return null;
+		} finally {
+			this.startingContainers.delete(containerUUID);
+		}
+	}
+	async isContainerRunning(containerUUID) {
+		if (this.startingContainers.has(containerUUID)) return true;
+		try {
+			const state = await this.getSandboxStub(containerUUID).getState();
+			return state.status === "running" || state.status === "healthy";
+		} catch (error) {
+			console.warn({
+				message: "Failed to check container status, assuming stopped",
+				component: "warm-pool",
+				containerUUID,
+				error
+			});
+			return false;
+		}
+	}
+	async checkContainerHealth() {
+		const allUUIDs = [...this.warmContainers, ...this.assignments.values()];
+		let anyRemoved = false;
+		for (const uuid of allUUIDs) if (!await this.isContainerRunning(uuid)) {
+			console.info({
+				message: "Container not running, removing from pool",
+				component: "warm-pool",
+				containerUUID: uuid
+			});
+			if (this.removeContainer(uuid)) anyRemoved = true;
+		}
+		if (anyRemoved) await this.persist();
+	}
+	/**
+	* Renew activity timeout on all warm containers to prevent them from sleeping.
+	*/
+	async keepWarmContainersAlive() {
+		for (const containerUUID of this.warmContainers) try {
+			this.getSandboxStub(containerUUID).renewActivityTimeout();
+		} catch (error) {
+			console.error({
+				message: "Failed to renew activity timeout",
+				component: "warm-pool",
+				containerUUID,
+				error
+			});
+		}
+	}
+	/**
+	* Scale the warm pool towards warmTarget, respecting inferred max_instances.
+	*/
+	async adjustPool() {
+		let diff = this.config.warmTarget - this.warmContainers.size;
+		if (diff > 0) {
+			if (this.remainingCapacity() === 0 && this.knownMaxInstances !== null) {
+				console.info({
+					message: "Pool at inferred limit, probing for capacity changes",
+					component: "warm-pool",
+					knownMaxInstances: this.knownMaxInstances
+				});
+				const probeUUID = await this.startContainer();
+				if (probeUUID) {
+					console.info({
+						message: "Probe succeeded, clearing cached limit",
+						component: "warm-pool"
+					});
+					this.knownMaxInstances = null;
+					this.warmContainers.add(probeUUID);
+					diff--;
+					await this.persist();
+				} else {
+					await this.persist();
+					return;
+				}
+			}
+			const toStart = Math.min(diff, this.remainingCapacity());
+			if (toStart <= 0) {
+				console.log({
+					message: "Cannot scale up pool",
+					component: "warm-pool",
+					needed: diff,
+					available: this.remainingCapacity(),
+					warm: this.warmContainers.size,
+					assigned: this.assignments.size,
+					knownMaxInstances: this.knownMaxInstances ?? "unknown"
+				});
+				return;
+			}
+			console.info({
+				message: "Scaling up pool",
+				component: "warm-pool",
+				starting: toStart,
+				needed: diff,
+				capacity: this.remainingCapacity()
+			});
+			for (let i = 0; i < toStart; i++) {
+				if (this.capacityExhausted) {
+					console.log({
+						message: "Capacity exhausted mid-loop, stopping further starts",
+						component: "warm-pool"
+					});
+					break;
+				}
+				const uuid = await this.startContainer();
+				if (uuid) this.warmContainers.add(uuid);
+			}
+			await this.persist();
+		} else if (diff < 0) {
+			const excess = -diff;
+			console.info({
+				message: "Scaling down pool",
+				component: "warm-pool",
+				stopping: excess
+			});
+			const toStop = [...this.warmContainers].slice(0, excess);
+			const stopped = [];
+			for (const uuid of toStop) try {
+				await this.getSandboxStub(uuid).stop();
+				stopped.push(uuid);
+			} catch (error) {
+				console.error({
+					message: "Failed to stop container",
+					component: "warm-pool",
+					containerUUID: uuid,
+					error
+				});
+			}
+			for (const uuid of stopped) this.warmContainers.delete(uuid);
+			await this.persist();
+		}
+	}
+	removeContainer(containerUUID) {
+		let removed = false;
+		if (this.warmContainers.delete(containerUUID)) removed = true;
+		for (const [sandboxId, uuid] of this.assignments) if (uuid === containerUUID) {
+			this.assignments.delete(sandboxId);
+			removed = true;
+			break;
+		}
+		return removed;
+	}
+	remainingCapacity() {
+		if (this.knownMaxInstances === null) return Infinity;
+		return Math.max(0, this.knownMaxInstances - (this.warmContainers.size + this.assignments.size));
+	}
+	isMaxInstancesError(error) {
+		return (error instanceof Error ? error.message : String(error)).includes("Maximum number of running container instances exceeded");
+	}
+	async recordCapacityLimit() {
+		const currentTotal = this.warmContainers.size + this.assignments.size;
+		this.knownMaxInstances = currentTotal;
+		this.capacityExhausted = true;
+		console.warn({
+			message: "Hit max_instances limit",
+			component: "warm-pool",
+			inferredCeiling: currentTotal,
+			warm: this.warmContainers.size,
+			assigned: this.assignments.size
+		});
+		await this.ctx.storage.put("knownMaxInstances", this.knownMaxInstances);
+	}
+	throwCapacityError() {
+		const total = this.warmContainers.size + this.assignments.size;
+		throw new Error(`Cannot start container: instance limit reached (${total}/${this.knownMaxInstances}). All container slots are in use. Wait for existing containers to stop.`);
+	}
+	getSandboxStub(containerUUID) {
+		const id = this.env.Sandbox.idFromName(containerUUID);
+		return this.env.Sandbox.get(id);
+	}
+};
+
+//#endregion
+//#region src/bridge/index.ts
+/**
+* @cloudflare/sandbox/bridge — Bridge factory for Cloudflare Sandbox Workers.
+*
+* Usage:
+* ```ts
+* import { bridge } from "@cloudflare/sandbox/bridge";
+* export { Sandbox } from "@cloudflare/sandbox";
+* export { WarmPool } from "@cloudflare/sandbox/bridge";
+*
+* export default bridge({
+*   async fetch(request, env, ctx) {
+*     return new Response("OK");
+*   },
+*   async scheduled(controller, env, ctx) {
+*     // custom scheduled logic
+*   }
+* });
+* ```
+*/
+/**
+* Log an error if the required Durable Object bindings are missing from the
+* module-level environment. The `cloudflare:workers` env exposes binding stubs
+* at module evaluation time, so a missing key means the wrangler.jsonc
+* configuration is wrong. The health endpoint performs the same validation at
+* request time and returns a 503.
+*/
+function checkBindings(env$1, options) {
+	const { sandboxBinding, warmPoolBinding } = options;
+	const missing = [];
+	if (!env$1[sandboxBinding]) missing.push(sandboxBinding);
+	if (!env$1[warmPoolBinding]) missing.push(warmPoolBinding);
+	if (missing.length > 0) for (const binding of missing) console.error({
+		message: `Missing required binding "${binding}"`,
+		component: "bridge",
+		binding,
+		hint: `Ensure your wrangler.jsonc has a Durable Object binding named "${binding}".`
+	});
+	if (!env$1.SANDBOX_API_KEY) console.warn({
+		message: "SANDBOX_API_KEY is not set — auth is disabled",
+		component: "bridge",
+		hint: "Set via `wrangler secret put SANDBOX_API_KEY`."
+	});
+}
+/**
+* Create a Worker export that wraps user handlers with bridge functionality.
+*
+* The bridge:
+* 1. Checks that required Durable Object bindings exist (logs errors if missing).
+* 2. Wraps `fetch()` to serve bridge API routes first, then falls through to the user handler.
+* 3. Wraps `scheduled()` to prime the warm pool, then calls the user handler.
+* 4. Passes through all other properties unchanged.
+*
+* @param worker - The user's worker handlers (fetch, scheduled, and any others).
+* @param config - Optional configuration for binding names and route paths.
+*/
+function bridge(worker, config) {
+	const sandboxBinding = config?.bindings?.sandbox ?? "Sandbox";
+	const warmPoolBinding = config?.bindings?.warmPool ?? "WarmPool";
+	const apiPrefix = config?.apiRoutePrefix ?? "/v1";
+	const healthPath = config?.healthRoute ?? "/health";
+	checkBindings(env, {
+		sandboxBinding,
+		warmPoolBinding
+	});
+	const app = createBridgeApp({
+		sandboxBinding,
+		warmPoolBinding,
+		apiPrefix,
+		healthPath
+	});
+	const passThrough = {};
+	for (const key of Object.keys(worker)) if (key !== "fetch" && key !== "scheduled") passThrough[key] = worker[key];
+	return {
+		...passThrough,
+		async fetch(request, env$1, ctx) {
+			const url = new URL(request.url);
+			if (url.pathname.startsWith(apiPrefix + "/") || url.pathname === apiPrefix || url.pathname === healthPath) return app.fetch(request, env$1, ctx);
+			if (worker.fetch) return worker.fetch(request, env$1, ctx);
+			return new Response("Not Found", { status: 404 });
+		},
+		async scheduled(controller, env$1, ctx) {
+			await primePool(env$1, warmPoolBinding);
+			if (worker.scheduled) await worker.scheduled(controller, env$1, ctx);
+		}
+	};
+}
+
+//#endregion
+export { WarmPool, bridge, resolveWorkspacePath, shellQuote };
+//# sourceMappingURL=index.js.map