@tangle-network/sandbox 0.9.2 → 0.9.3-develop.20260627012805.bf68a85

package/dist/sandbox-FcVsLeUJ.js

@@ -0,0 +1,4500 @@
+import { c as ServerError, d as ValidationError, f as parseErrorResponse, l as StateError, o as QuotaError, r as NetworkError, s as SandboxError, t as AuthError, u as TimeoutError } from "./errors-DZsfJUuc.js";
+import { addTokenUsage, readTokenCostUsd, readTokenUsage } from "@tangle-network/agent-core";
+//#region src/backend-config.ts
+function parseModelString(model) {
+	const parts = model.split("/");
+	if (parts.length >= 2) return {
+		provider: parts[0],
+		model: parts.slice(1).join("/")
+	};
+	return { model };
+}
+/**
+* Normalize runtime backend config for the wire format.
+*
+* Callers set `backend.profile` (named string or portable AgentProfile).
+* This function generates the native `inlineProfile` shim automatically.
+*/
+function normalizeRuntimeBackendConfig(backend, options = {}) {
+	if (!backend && !options.model) return void 0;
+	const portableProfile = backend?.profile && typeof backend.profile !== "string" ? backend.profile : void 0;
+	const inlineProfile = portableProfile ? toBackendProfile(portableProfile) : void 0;
+	const callerInlineProfile = backend?.inlineProfile;
+	if (callerInlineProfile && !inlineProfile) console.warn("[sandbox-sdk] backend.inlineProfile is deprecated. Use backend.profile (AgentPortableProfile) instead.");
+	return {
+		...backend?.type ? { type: backend.type } : {},
+		...typeof backend?.profile === "string" ? { profile: backend.profile } : {},
+		...inlineProfile ? { inlineProfile } : callerInlineProfile ? { inlineProfile: callerInlineProfile } : {},
+		...backend?.model ? { model: backend.model } : options.model ? { model: parseModelString(options.model) } : {},
+		...backend?.server ? { server: backend.server } : {}
+	};
+}
+/**
+* Permission keys the sidecar's strict `permission` schema accepts
+* (apps/sidecar/src/schemas/agent-profile-schema.ts → permissionConfigSchema).
+* Any other portable-permission key is a per-tool gate, not a permission, and
+* is routed into `tools` instead of passed through — the sidecar's `.strict()`
+* schema rejects unknown permission keys with `unrecognized_keys`.
+*
+* Name must not carry an UPPERCASE `SIDECAR_`/`ORCHESTRATOR_`-style prefix:
+* obfuscate.sh runs `--rename-globals false`, so a module-global identifier
+* ships verbatim in dist/, and verify-dist.sh bans those prefixes as
+* closed-source leaks.
+*/
+const CANONICAL_PERMISSION_KEYS = new Set([
+	"edit",
+	"bash",
+	"webfetch",
+	"mcp",
+	"doom_loop",
+	"external_directory"
+]);
+function hasAnyProfileResource(resources) {
+	return !!(resources.files?.length || resources.tools?.length || resources.skills?.length || resources.agents?.length || resources.commands?.length || resources.instructions);
+}
+function validateProfileResources(profile) {
+	if (profile.resources !== void 0 && (profile.resources === null || typeof profile.resources !== "object" || Array.isArray(profile.resources))) throw new Error("backend.profile.resources must be an object when provided");
+	if (profile.resources?.plugins?.length) throw new Error("backend.profile.resources.plugins is not supported by the sandbox SDK profile contract; use backend-specific provider profiles for OpenCode plugin resources");
+}
+function toBackendProfile(profile) {
+	validateProfileResources(profile);
+	const permission = {};
+	const derivedTools = {};
+	for (const [rawKey, value] of Object.entries(profile.permissions ?? {})) {
+		const key = rawKey === "network" ? "webfetch" : rawKey;
+		if (CANONICAL_PERMISSION_KEYS.has(key)) permission[key] = value;
+		else if (typeof value === "string") derivedTools[key] = value !== "deny";
+		else console.warn(`[sandbox-sdk] dropping unsupported permission key "${rawKey}": not a canonical sidecar permission and not a string tool gate`);
+	}
+	const tools = {
+		...derivedTools,
+		...profile.tools ?? {}
+	};
+	const mcp = profile.mcp ? Object.fromEntries(Object.entries(profile.mcp).map(([name, config]) => {
+		const c = config;
+		const transport = c.transport;
+		const command = c.command;
+		const hasCommand = Array.isArray(command) ? command.length > 0 : typeof command === "string" && command.trim().length > 0;
+		const isRemote = transport === "http" || transport === "sse" || typeof c.url === "string" && !hasCommand;
+		const enabled = c.enabled;
+		const timeout = c.timeout;
+		if (isRemote) return [name, {
+			type: "remote",
+			url: c.url,
+			...c.headers ? { headers: c.headers } : {},
+			...enabled !== void 0 ? { enabled } : {},
+			...timeout !== void 0 ? { timeout } : {}
+		}];
+		return [name, {
+			type: "local",
+			command: [...Array.isArray(command) ? command : typeof command === "string" ? command.trim().split(/\s+/).filter(Boolean) : [], ...c.args ?? []],
+			...c.env ? { environment: c.env } : {},
+			...enabled !== void 0 ? { enabled } : {},
+			...timeout !== void 0 ? { timeout } : {}
+		}];
+	})) : void 0;
+	return {
+		name: profile.name,
+		model: profile.model?.default,
+		...profile.prompt?.systemPrompt ? { systemPrompt: profile.prompt.systemPrompt } : {},
+		...Object.keys(tools).length > 0 ? { tools } : {},
+		...profile.prompt?.instructions?.length ? { instructions: profile.prompt.instructions } : {},
+		...Object.keys(permission).length > 0 ? { permission } : {},
+		...mcp ? { mcp } : {},
+		...profile.connections?.length ? { connections: profile.connections } : {},
+		...profile.subagents ? { subagents: profile.subagents } : {},
+		...profile.resources && hasAnyProfileResource(profile.resources) ? { resources: profile.resources } : {},
+		...profile.hooks ? { hooks: profile.hooks } : {},
+		...profile.modes ? { modes: profile.modes } : {},
+		...profile.extensions ? { extensions: profile.extensions } : {}
+	};
+}
+/**
+* Serialize a portable AgentProfile into the sidecar's canonical inline-profile
+* wire shape (validated by inlineProfileSchema in
+* apps/sidecar/src/schemas/agent-profile-schema.ts).
+*
+* Single choke point every product shares: streamPrompt →
+* normalizeRuntimeBackendConfig → toBackendProfile. Exported so callers and the
+* drift-guard test target one contract — the test parses this output with the
+* sidecar's own schema, so any future schema tightening fails here first.
+*/
+function serializeForSidecar(profile) {
+	return toBackendProfile(profile);
+}
+//#endregion
+//#region src/lib/sse-parser.ts
+/**
+* Parse a streaming SSE response body into an async iterable of
+* structured events.
+*
+* @throws `TypeError` when the response has no body.
+* @throws `DOMException` with `name === "AbortError"` on cancellation.
+*/
+async function* parseSSEStream(body, options) {
+	if (!body) throw new TypeError("SSE stream has no response body");
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const { signal } = options ?? {};
+	let buffer = "";
+	let currentEvent = "";
+	let dataLines = [];
+	let currentId = "";
+	const flush = function* () {
+		if (dataLines.length === 0) {
+			currentEvent = "";
+			currentId = "";
+			return;
+		}
+		const effectiveEvent = currentEvent || "message";
+		const joined = dataLines.join("\n");
+		try {
+			yield {
+				type: effectiveEvent,
+				data: JSON.parse(joined),
+				id: currentId || void 0
+			};
+		} catch {
+			console.warn(`[sandbox-sdk] Malformed SSE JSON for event "${effectiveEvent}": ${joined.slice(0, 200)}`);
+		}
+		currentEvent = "";
+		dataLines = [];
+		currentId = "";
+	};
+	const processLine = (line) => {
+		if (line.startsWith("event:")) currentEvent = line.slice(6).trim();
+		else if (line.startsWith("data:")) dataLines.push(line.slice(5).trim());
+		else if (line.startsWith("id:")) currentId = line.slice(3).trim();
+	};
+	try {
+		while (true) {
+			if (signal?.aborted) throw new DOMException("SSE stream aborted", "AbortError");
+			const { done, value } = await reader.read();
+			if (done) {
+				if (signal?.aborted) throw new DOMException("SSE stream aborted", "AbortError");
+				break;
+			}
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split(/\r?\n/);
+			buffer = lines.pop() ?? "";
+			for (const line of lines) if (line === "") yield* flush();
+			else processLine(line);
+		}
+		buffer += decoder.decode();
+		if (buffer.length > 0) processLine(buffer);
+		yield* flush();
+	} finally {
+		reader.releaseLock();
+	}
+}
+//#endregion
+//#region src/lib/wire-encoding.ts
+/**
+* Encode a prompt text part for the wire. Server decodes at the route
+* boundary; the LLM only ever sees the original UTF-8. Done
+* unconditionally because readable bodies false-positive on ingress WAF
+* rules that pattern-match shell-injection-shaped substrings (which
+* legitimate prompts routinely contain — e.g. Step-0 dev-server
+* bootstrap).
+*/
+function encodeTextForWire(text) {
+	if (typeof Buffer !== "undefined") return Buffer.from(text, "utf8").toString("base64");
+	if (typeof btoa === "function") return btoa(encodeURIComponent(text).replace(/%([0-9A-F]{2})/g, (_, h) => String.fromCharCode(Number.parseInt(h, 16))));
+	throw new Error("encodeTextForWire: no base64 encoder available (Buffer and btoa both undefined)");
+}
+/**
+* Convert a caller-supplied prompt (string or parts array) into the
+* wire-format parts array. Every text part is base64-encoded; non-text
+* parts pass through. A bare string is wrapped in a single text part.
+*/
+function encodePromptForWire(message) {
+	return (typeof message === "string" ? [{
+		type: "text",
+		text: message
+	}] : message).map((part) => part.type === "text" ? {
+		type: "text",
+		text: encodeTextForWire(part.text)
+	} : part);
+}
+//#endregion
+//#region src/trace-exporter.ts
+function buildTraceExportPayload(bundle, format = "tangle", serviceName = "tangle-sandbox") {
+	if (format === "tangle") return bundle;
+	if (format === "otel-json") return toOtelJson(bundle, serviceName);
+	throw new Error(`Unsupported trace export format: ${String(format)}`);
+}
+async function exportTraceBundle(bundle, sink) {
+	if (!sink.url) throw new Error("Trace export requires sink.url");
+	const fetchImpl = sink.fetch ?? globalThis.fetch;
+	if (!fetchImpl) throw new Error("Trace export requires fetch");
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), sink.timeoutMs ?? 3e4);
+	try {
+		const response = await fetchImpl(sink.url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				...sink.headers
+			},
+			body: JSON.stringify(buildTraceExportPayload(bundle, sink.format ?? "tangle", sink.serviceName)),
+			signal: controller.signal
+		});
+		const body = await response.text();
+		if (!response.ok) throw new Error(`Trace export failed with ${response.status}: ${body.slice(0, 500)}`);
+		return {
+			status: response.status,
+			ok: true,
+			body
+		};
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+function toOtelJson(bundle, serviceName = "tangle-sandbox") {
+	const traceId = hexId(bundle.trace.traceId, 32);
+	const rootSpanId = hexId(`${bundle.trace.traceId}:root`, 16);
+	const rootStart = unixNano(rootTimestamp(bundle));
+	const rootEnd = rootStart + BigInt(Math.round(traceDurationMs(bundle.trace) * 1e6));
+	const rootSpan = {
+		traceId,
+		spanId: rootSpanId,
+		name: traceRootName(bundle),
+		kind: 1,
+		startTimeUnixNano: rootStart.toString(),
+		endTimeUnixNano: rootEnd.toString(),
+		attributes: [
+			attr("tangle.subject.id", traceSubjectId(bundle)),
+			attr("tangle.trace.id", bundle.trace.traceId),
+			attr("tangle.trace.schema_version", bundle.trace.schemaVersion),
+			...Object.entries(bundle.trace.timings ?? {}).map(([key, value]) => attr(`tangle.timing.${snakeCase(key)}`, value)),
+			...Object.entries(bundle.trace.criticalPath ?? {}).map(([key, value]) => attr(`tangle.critical_path.${snakeCase(key)}`, value))
+		],
+		...traceHasError(bundle) ? otelErrorStatus("Trace contains failure evidence") : {}
+	};
+	return { resourceSpans: [{
+		resource: { attributes: [
+			attr("service.name", serviceName),
+			attr("tangle.subject.id", traceSubjectId(bundle)),
+			attr("tangle.trace.schema_version", bundle.trace.schemaVersion),
+			...bundle.intelligence ? [
+				attr("tangle.intelligence.schema_version", bundle.intelligence.schemaVersion),
+				attr("tangle.intelligence.billable", false),
+				attr("tangle.intelligence.cost_usd", 0)
+			] : []
+		] },
+		scopeSpans: [{
+			scope: {
+				name: "@tangle-network/sandbox",
+				version: "trace.v1"
+			},
+			spans: [rootSpan, ...bundle.trace.events.map((event, index) => {
+				const start = unixNano(event.timestamp);
+				const durationMs = Math.max(0, event.durationMs ?? 0);
+				const end = start + BigInt(Math.round(durationMs * 1e6));
+				return {
+					traceId,
+					spanId: hexId(`${bundle.trace.traceId}:${index}`, 16),
+					parentSpanId: rootSpanId,
+					name: event.type,
+					kind: 1,
+					startTimeUnixNano: start.toString(),
+					endTimeUnixNano: end.toString(),
+					attributes: [
+						attr("tangle.subject.id", eventSubjectId(event)),
+						..."machineId" in event && event.machineId ? [attr("tangle.fleet.machine_id", event.machineId)] : [],
+						...Object.entries(event.attributes).map(([key, value]) => attr(key, value))
+					],
+					...eventHasError(event) ? otelErrorStatus("Event contains failure evidence") : {}
+				};
+			})]
+		}]
+	}] };
+}
+function otelTraceIdForTangleTrace(traceId) {
+	return hexId(traceId, 32);
+}
+function traceSubjectId(bundle) {
+	return "fleetId" in bundle.trace ? bundle.trace.fleetId : bundle.trace.sandboxId;
+}
+function eventSubjectId(event) {
+	return "fleetId" in event ? event.fleetId : event.sandboxId;
+}
+function attr(key, value) {
+	if (typeof value === "boolean") return {
+		key,
+		value: { boolValue: value }
+	};
+	if (typeof value === "number" && Number.isFinite(value)) return Number.isInteger(value) ? {
+		key,
+		value: { intValue: String(value) }
+	} : {
+		key,
+		value: { doubleValue: value }
+	};
+	if (typeof value === "string") return {
+		key,
+		value: { stringValue: value }
+	};
+	if (Array.isArray(value)) return {
+		key,
+		value: { arrayValue: { values: value.map((item) => attrValue(item)) } }
+	};
+	if (value && typeof value === "object") return {
+		key,
+		value: { kvlistValue: { values: Object.entries(value).map(([entryKey, entryValue]) => ({
+			key: entryKey,
+			value: attrValue(entryValue)
+		})) } }
+	};
+	return {
+		key,
+		value: { stringValue: JSON.stringify(value ?? null) }
+	};
+}
+function attrValue(value) {
+	if (typeof value === "boolean") return { boolValue: value };
+	if (typeof value === "number" && Number.isFinite(value)) return Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+	if (typeof value === "string") return { stringValue: value };
+	if (Array.isArray(value)) return { arrayValue: { values: value.map(attrValue) } };
+	if (value && typeof value === "object") return { kvlistValue: { values: Object.entries(value).map(([key, item]) => ({
+		key,
+		value: attrValue(item)
+	})) } };
+	return { stringValue: JSON.stringify(value ?? null) };
+}
+function unixNano(timestamp) {
+	const millis = Date.parse(timestamp);
+	return BigInt(Number.isFinite(millis) ? millis : 0) * 1000000n;
+}
+function hexId(input, length) {
+	const bytes = new TextEncoder().encode(input);
+	const hashes = [
+		2166136261,
+		2654435769,
+		2246822507,
+		3266489909
+	];
+	for (const byte of bytes) for (let lane = 0; lane < hashes.length; lane += 1) {
+		const hash = hashes[lane];
+		if (hash === void 0) throw new Error(`Missing trace hash lane ${lane}`);
+		hashes[lane] = Math.imul(hash ^ byte + lane, 16777619);
+	}
+	let out = hashes.map((hash) => (hash >>> 0).toString(16).padStart(8, "0")).join("");
+	while (out.length < length) {
+		const next = hexId(`${input}:${out.length}`, 32);
+		out += next;
+	}
+	return out.slice(0, length);
+}
+function traceRootName(bundle) {
+	return "fleetId" in bundle.trace ? "tangle.fleet.trace" : "tangle.sandbox.trace";
+}
+function rootTimestamp(bundle) {
+	return bundle.trace.events[0]?.timestamp ?? bundle.trace.exportedAt;
+}
+function traceDurationMs(trace) {
+	return Math.max(0, trace.criticalPath?.durationMs ?? 0);
+}
+function traceHasError(bundle) {
+	return bundle.trace.events.some(eventHasError);
+}
+function eventHasError(event) {
+	const status = event.attributes.status;
+	const error = event.attributes.error;
+	return event.type.includes("fail") || status === "failed" || status === "error" || Boolean(error);
+}
+function otelErrorStatus(message) {
+	return { status: {
+		code: 2,
+		message
+	} };
+}
+function snakeCase(value) {
+	return value.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+//#endregion
+//#region src/normalize.ts
+/**
+* Normalize a raw `connection` payload from the Sandbox API into the SDK's
+* canonical `SandboxConnection` shape.
+*
+* The current server returns the runtime URL as `connection.sidecarUrl`;
+* the SDK exposes it as `connection.runtimeUrl`. This helper reads either
+* field name so a future server-side rename needs no client change.
+*
+* Returns `undefined` when the raw payload has no usable runtime URL, so
+* callers using `normalizeConnection(data.connection) ?? fallback` can
+* preserve a previously-known connection during transient server states
+* (e.g. a partial payload that only carries an auth token). Without this
+* guard, a partial `{ authToken: "..." }` response would overwrite a
+* previously-valid connection with an object missing its URL.
+*/
+function normalizeConnection(raw) {
+	if (!raw || typeof raw !== "object") return void 0;
+	const c = raw;
+	const runtimeUrl = c.runtimeUrl ?? c.sidecarUrl;
+	const edgeStatus = normalizeEdgeStatus(c.edgeStatus);
+	const ssh = normalizeSshCredentials(c.ssh);
+	const webTerminalUrl = c.webTerminalUrl;
+	if (!runtimeUrl && !edgeStatus && !ssh && !webTerminalUrl) return void 0;
+	return {
+		runtimeUrl,
+		authToken: c.authToken,
+		authTokenExpiresAt: c.authTokenExpiresAt,
+		edgeStatus,
+		edgeReadyAt: c.edgeReadyAt,
+		edgeError: c.edgeError,
+		ssh,
+		webTerminalUrl
+	};
+}
+function normalizeEdgeStatus(raw) {
+	return raw === "pending" || raw === "ready" || raw === "failed" || raw === "skipped" ? raw : void 0;
+}
+/**
+* Narrow a raw `ssh` payload into a `SSHCredentials` object. Returns
+* `undefined` if the payload is missing required fields so callers that
+* dereference `connection.ssh.proxyCommand` don't surprise-crash on partial
+* server responses.
+*/
+function normalizeSshCredentials(raw) {
+	if (!raw || typeof raw !== "object") return void 0;
+	const s = raw;
+	if (typeof s.port !== "number" || typeof s.username !== "string" || typeof s.proxyCommand !== "string" || s.proxyCommand.length === 0) return;
+	return {
+		username: s.username,
+		port: s.port,
+		proxyCommand: s.proxyCommand
+	};
+}
+//#endregion
+//#region src/lib/agent-response-text.ts
+/**
+* Canonical extraction of an agent's response text from its sandbox event
+* stream. This is the single source of truth used by both `SandboxInstance.prompt`
+* (streaming accumulation) and any consumer that collects the raw event array
+* first (loop kernels, workflow runners) and needs the final text.
+*
+* The runtime emits agent text across several event shapes — a terminal
+* `result` event, incremental `token` events, and cumulative
+* `message.part.updated` text parts — each carrying the text under a different
+* key. Reading a single hard-coded field (e.g. `data.text`) misses the real
+* payload entirely, so the helpers below understand every shape the runtime
+* actually produces.
+*/
+/**
+* The text carried by a single event, or `undefined` when the event carries no
+* text payload. Mirrors the event shapes the sidecar/OpenCode runtime emits:
+*  - `result`     — the terminal event; final text under `finalText`/`response`/
+*                   `output`/`content`/`text`.
+*  - `token`      — an incremental token; text under `value`/`delta`/`text`/
+*                   `content`.
+*  - `message.part.updated` — a streamed assistant message part; the text part
+*                   lives at `data.part.text` (or `.content`) when
+*                   `part.type === "text"`.
+*/
+function isRecord(v) {
+	return typeof v === "object" && v !== null;
+}
+/** The first candidate that is actually a string. Using `typeof` rather than a
+*  `??` chain means a non-string in an earlier field (a malformed `finalText: 0`)
+*  never shadows a valid string in a later fallback, and the `string | undefined`
+*  return contract stays honest for callers. */
+function firstString(...candidates) {
+	for (const candidate of candidates) if (typeof candidate === "string") return candidate;
+}
+function getSandboxEventText(event) {
+	const data = isRecord(event.data) ? event.data : {};
+	if (event.type === "result") return firstString(data.finalText, data.response, data.output, data.content, data.text);
+	if (event.type === "token") return firstString(data.value, data.delta, data.text, data.content);
+	if (event.type !== "message.part.updated") return;
+	const part = isRecord(data.part) ? data.part : void 0;
+	if (part?.type !== "text") return;
+	return firstString(part.text, part.content);
+}
+/** As {@link getSandboxEventText}, but treats a whitespace-only payload as no
+*  text — so blank parts never overwrite real accumulated text. */
+function getMeaningfulSandboxEventText(event) {
+	const text = getSandboxEventText(event);
+	if (typeof text !== "string" || text.trim().length === 0) return;
+	return text;
+}
+/**
+* Fold one event into the running response text. `token` events APPEND their
+* incremental delta/value; every other text-bearing event (`result`,
+* `message.part.updated`) carries the cumulative text, so it REPLACES — unless
+* it is a strict continuation of what we already have, in which case it is
+* appended once. An event with no meaningful text leaves `current` untouched.
+*
+* Whitespace handling differs by kind: an incremental `token` keeps its RAW text
+* (a lone space delta is a word separator — dropping it concatenates words), but
+* a cumulative event uses the meaningful text so a blank payload never overwrites
+* real accumulated text.
+*/
+function applySandboxEventText(current, event) {
+	const text = event.type === "token" ? getSandboxEventText(event) : getMeaningfulSandboxEventText(event);
+	if (text === void 0) return current;
+	if (event.type !== "token") return text;
+	const delta = event.data.delta;
+	if (typeof delta === "string") return `${current ?? ""}${delta}`;
+	const value = event.data.value;
+	if (typeof value === "string") {
+		if (!current || value.startsWith(current)) return value;
+		return `${current}${value}`;
+	}
+	if (!current) return text;
+	if (text.startsWith(current)) return text;
+	return `${current}${text}`;
+}
+/**
+* Collect an agent's complete response text from an already-buffered event
+* array. Equivalent to the streaming accumulation in `SandboxInstance.prompt`,
+* exposed as a pure function so consumers that collect the raw stream first
+* (e.g. the agent-runtime loop kernel) decode the SAME way the SDK does.
+*
+* Returns `undefined` when the stream carried no meaningful text — the honest
+* "agent produced nothing extractable" signal, distinct from an empty string.
+* Whitespace is preserved DURING accumulation (a lone space token separates
+* words), but a result that is entirely whitespace is "no meaningful text", so
+* the final value is collapsed to `undefined` — a whitespace-only token stream
+* must not read as a truthy response.
+*/
+function collectAgentResponseText(events) {
+	let responseText;
+	for (const event of events) {
+		responseText = applySandboxEventText(responseText, event);
+		if (event.type === "result" || event.type === "done") break;
+	}
+	return responseText && responseText.trim().length > 0 ? responseText : void 0;
+}
+//#endregion
+//#region src/interactive.ts
+/**
+* Handle for one session's interactive harness. Obtained via
+* `box.session(id).interactive()`; does not hit the network until a method is
+* called.
+*/
+var InteractiveSessionHandle = class {
+	constructor(host, sessionId) {
+		this.host = host;
+		this.sessionId = sessionId;
+	}
+	/**
+	* Spawn the harness's interactive TUI for this session. Returns the
+	* `streamUrl` to attach a terminal client to. Throws if the harness has no
+	* interactive entrypoint (e.g. opencode), the binary is not installed, or a
+	* session is already running for this id.
+	*/
+	start(options) {
+		return this.host._startInteractive(this.sessionId, options);
+	}
+	/** Inject a prompt as keystrokes into the live harness (submitted on send). */
+	sendPrompt(prompt) {
+		return this.host._sendInteractivePrompt(this.sessionId, prompt);
+	}
+	/** Stop the interactive harness and reap its PTY. */
+	stop() {
+		return this.host._stopInteractive(this.sessionId);
+	}
+};
+//#endregion
+//#region src/session.ts
+/**
+* SandboxSession — first-class noun for an agent session inside a sandbox.
+*
+* Closes Issue #913 Gap 3: today `sessionId` is a string passed into
+* `prompt()` for resume; there is no way to inspect a session, list
+* active sessions, or query state without re-running the prompt. Apps
+* that fan out parallel research workers (the agent-builder Forge use
+* case) end up shadowing all session state in their own database. This
+* class makes the sandbox the source of truth — apps reduce their own
+* tables to thin denormalizations for cross-sandbox queries.
+*
+* The class is a thin façade over the sidecar's `/agents/sessions/{id}`
+* routes: `status` reads `GET /agents/sessions/{id}`, `events` opens an
+* SSE stream against `/agents/events?sessionId=...` (with `since` for
+* replay), `prompt` continues the session via `/agents/run/stream`,
+* `cancel` calls `/agents/sessions/{id}/abort`. No new sidecar surface
+* is required — every endpoint already exists.
+*
+* Construction is private to the SDK: get a Session from
+* `box.session(id)` (lazy reference, no network) or `box.sessions(...)`
+* (lister, single round-trip).
+*/
+/**
+* A single agent session inside a sandbox. Created via
+* `box.session(id)` — does not hit the network until a method is called.
+*/
+var SandboxSession = class {
+	/**
+	* @internal SDK-internal constructor — apps should call `box.session(id)`.
+	*/
+	constructor(box, id) {
+		this.box = box;
+		this.id = id;
+	}
+	/**
+	* Fetch the current session state from the sandbox. Includes status,
+	* model, prompt count, token usage if known, and timing metadata.
+	*
+	* Throws on transport error; returns `null` if the session id is not
+	* known to the sandbox (e.g. it ended and was reaped, or the id is
+	* invalid).
+	*/
+	async status() {
+		return this.box._sessionStatus(this.id);
+	}
+	/**
+	* Stream events from this session as they arrive. With no `since`,
+	* starts at the live tail; with `since`, replays from that event id
+	* forward — useful for reconnect-after-disconnect flows.
+	*
+	* The async iterator terminates when the session reaches a terminal
+	* state (`completed`, `failed`, `cancelled`) and the corresponding
+	* terminal event has been yielded, OR when the caller's signal aborts.
+	*/
+	events(opts) {
+		return this.box._sessionEvents(this.id, opts);
+	}
+	/**
+	* Await the session's terminal result. Polls status + drains events
+	* until the session reaches a terminal state, then returns the
+	* aggregated `PromptResult`.
+	*
+	* Use this to wait for a session that was started by another caller
+	* (e.g. `dispatchPrompt`).
+	*/
+	async result() {
+		return this.box._sessionResult(this.id);
+	}
+	/**
+	* Continue this session with an additional prompt. Equivalent to
+	* `box.prompt(message, { ...opts, sessionId: this.id })` but reads
+	* naturally on a Session reference.
+	*/
+	async prompt(message, opts) {
+		return this.box.prompt(message, {
+			...opts,
+			sessionId: this.id
+		});
+	}
+	/**
+	* Abort the session's in-flight execution; the session and its messages
+	* are preserved (this does not delete the session). Void-returning alias
+	* of `interrupt()` — use `interrupt()` when you need to know whether an
+	* execution was actually running. Best-effort: an in-flight LLM call may
+	* still complete one more token before the abort takes effect. Idempotent —
+	* aborting a session with nothing in flight is a no-op.
+	*/
+	async cancel() {
+		return this.box._sessionCancel(this.id);
+	}
+	/**
+	* Drive this session's harness in INTERACTIVE mode: spawn its native TUI,
+	* stream the live framebuffer, and inject prompts as keystrokes. Distinct
+	* from the headless `prompt()`/`events()` surface above. Lazy — does not hit
+	* the network until a handle method is called.
+	*/
+	interactive() {
+		return new InteractiveSessionHandle(this.box, this.id);
+	}
+	/**
+	* Resolve a pending permission interaction the agent raised mid-turn,
+	* forwarding `allow`/`deny` to the blocked agent through the unified
+	* interaction channel. Throws if no matching permission is outstanding.
+	*/
+	async respondToPermission(permissionID, options) {
+		return this.box._respondToPermission(this.id, permissionID, options);
+	}
+	/**
+	* Interrupt the session's current execution without deleting it. Returns
+	* `{ cancelled: false }` when nothing was running — the no-op is reported
+	* explicitly rather than masked as success.
+	*/
+	async interrupt() {
+		return this.box._interrupt(this.id);
+	}
+	/**
+	* Answer a question the agent asked via a question tool invocation. `answers`
+	* maps each question id to the selected option(s). OpenCode-only; other
+	* backends reject loudly.
+	*/
+	async answer(answers) {
+		return this.box._answerQuestion(this.id, answers);
+	}
+};
+//#endregion
+//#region src/sandbox.ts
+/**
+* Sandbox Instance
+*
+* Represents a single sandbox and provides methods to interact with it.
+*/
+function normalizeProvisionStep(raw) {
+	if (raw === "sidecar-ready") return "runtime-ready";
+	return raw;
+}
+/**
+* Normalize the raw `startupDiagnostics` field from a sandbox API
+* response into a {@link StartupDiagnostics}, deriving the
+* operation-name → duration `phases` map. Returns `null` when the
+* payload is absent or carries no operations — diagnostics are emitted
+* only once, on the create response, so most reads have no payload to
+* normalize.
+*/
+function normalizeStartupDiagnostics(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const rawOperations = raw.operations;
+	if (!Array.isArray(rawOperations) || rawOperations.length === 0) return null;
+	const operations = [];
+	const phases = {};
+	for (const entry of rawOperations) {
+		if (!entry || typeof entry !== "object") continue;
+		const record = entry;
+		const operation = record.operation;
+		if (typeof operation !== "string") continue;
+		const durationMs = typeof record.durationMs === "number" ? record.durationMs : void 0;
+		operations.push({
+			operation,
+			service: typeof record.service === "string" ? record.service : void 0,
+			status: typeof record.status === "string" ? record.status : void 0,
+			durationMs,
+			metadata: record.metadata && typeof record.metadata === "object" ? record.metadata : void 0
+		});
+		if (durationMs !== void 0) phases[operation] = durationMs;
+	}
+	if (operations.length === 0) return null;
+	return {
+		operations,
+		phases
+	};
+}
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function assertValidSessionId(value) {
+	if (!SESSION_ID_PATTERN.test(value)) throw new ValidationError(`Invalid sessionId ${JSON.stringify(value)}: must match ${SESSION_ID_PATTERN.source}`);
+}
+/**
+* Replace bearer-secret fields on a `SandboxConnection` with a sentinel
+* before serialization. The serialized shape is preserved (so external
+* tooling that switches on `connection.authToken !== undefined` keeps
+* working), but the actual token value never leaves the process.
+*/
+function redactConnectionSecrets(connection) {
+	if (!connection) return connection;
+	if (connection.authToken === void 0) return connection;
+	return {
+		...connection,
+		authToken: "[REDACTED]"
+	};
+}
+function normalizePreviewLink(raw) {
+	const sandboxId = raw.sandboxId ?? raw.sidecarId ?? "";
+	return {
+		previewId: raw.previewId,
+		sandboxId,
+		port: raw.port,
+		protocol: raw.protocol,
+		hostname: raw.hostname,
+		url: raw.url,
+		status: raw.status,
+		lastSyncAt: raw.lastSyncAt,
+		createdAt: raw.createdAt,
+		updatedAt: raw.updatedAt,
+		metadata: raw.metadata
+	};
+}
+const SNAPSHOT_RESTORE_POLL_INTERVAL_MS = 1e3;
+const SNAPSHOT_RESTORE_TIMEOUT_MS = 600 * 1e3;
+const SNAPSHOT_VISIBILITY_POLL_INTERVAL_MS = 1e3;
+const SNAPSHOT_VISIBILITY_TIMEOUT_MS = 120 * 1e3;
+const SNAPSHOT_CREATE_REQUEST_TIMEOUT_MS = 600 * 1e3;
+function toSnapshotResult(data) {
+	return {
+		snapshotId: data.snapshotId ?? data.id,
+		createdAt: new Date(data.createdAt),
+		sizeBytes: data.sizeBytes,
+		tags: data.tags ?? []
+	};
+}
+function isTransientSnapshotVisibilityError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes("SNAPSHOT_NOT_FOUND") || message.includes("Failed to list snapshot") || message.includes("Storage agent error (404)");
+}
+/**
+* Single source of truth for a run's outcome, shared by
+* `prompt`/`task`/`_sessionResult`/turn settling. A run succeeds only when it
+* reached a terminal event, raised no run-level error, hit no approval gate,
+* left no unanswered question, and recorded no failed (`isError`) tool. A
+* tool-only turn with no text succeeds; a turn whose tool failed (even if
+* narrated around) fails.
+*/
+function deriveOutcome(inputs) {
+	if (inputs.question) return {
+		status: "awaiting_question",
+		success: false,
+		error: inputs.runError ?? "Agent is awaiting an answer to a question"
+	};
+	if (inputs.approval) return {
+		status: "blocked_on_approval",
+		success: false,
+		error: inputs.runError ?? inputs.approval.message ?? "Agent is blocked on a hub approval"
+	};
+	if (inputs.runError) return {
+		status: "failed",
+		success: false,
+		error: inputs.runError
+	};
+	const failedTool = inputs.toolInvocations?.find((t) => t.isError === true);
+	if (failedTool) return {
+		status: "failed",
+		success: false,
+		error: `Tool "${failedTool.toolName}" failed`
+	};
+	if (!inputs.terminalReached) return {
+		status: "failed",
+		success: false,
+		error: "Agent stream ended without a terminal event"
+	};
+	return {
+		status: "success",
+		success: true
+	};
+}
+/** Read tool invocations off a `result` event payload. */
+function readToolInvocations(data) {
+	const raw = data.toolInvocations;
+	return Array.isArray(raw) ? raw : void 0;
+}
+/** Hub error code surfaced when a write tool hits an approval gate. */
+const HUB_APPROVAL_CODE = "HUB_APPROVAL_REQUIRED";
+/** Best-effort string view of an arbitrary tool result for signal matching. */
+function stringifyToolResult(result) {
+	if (typeof result === "string") return result;
+	try {
+		return JSON.stringify(result) ?? "";
+	} catch {
+		return String(result);
+	}
+}
+/**
+* Walk a tool result for an `approval` object and return its `id`/`connectionId`.
+* The in-sandbox hub bridge carries these in `structuredContent.details.approval`,
+* but the exact nesting depends on how the backend serialized the MCP result, so
+* search defensively. Returns `undefined` when not present — the id is then
+* surfaced honestly as `undefined`, never invented.
+*/
+function findApprovalDetails(value, depth = 0) {
+	if (depth > 6 || value === null || typeof value !== "object") return void 0;
+	const obj = value;
+	const approval = obj.approval;
+	if (approval && typeof approval === "object") {
+		const a = approval;
+		return {
+			...typeof a.id === "string" ? { id: a.id } : {},
+			...typeof a.connectionId === "string" ? { connectionId: a.connectionId } : {}
+		};
+	}
+	for (const v of Object.values(obj)) {
+		const found = findApprovalDetails(v, depth + 1);
+		if (found) return found;
+	}
+}
+/** Find a human-readable `message` string anywhere in a tool result. */
+function findResultMessage(value, depth = 0) {
+	if (depth > 6 || value === null || typeof value !== "object") return void 0;
+	const obj = value;
+	if (typeof obj.message === "string" && obj.message.length > 0) return obj.message;
+	for (const v of Object.values(obj)) {
+		const found = findResultMessage(v, depth + 1);
+		if (found) return found;
+	}
+}
+/**
+* Detect a hub approval gate among a run's tool invocations: a failed tool whose
+* result carries `HUB_APPROVAL_REQUIRED`. Returns the approval id/connectionId
+* when the structured signal survived serialization, else just the message — so
+* the run can settle as `blocked_on_approval` even when the id is unrecoverable.
+*/
+function detectHubApproval(toolInvocations) {
+	if (!toolInvocations) return void 0;
+	for (const tool of toolInvocations) {
+		if (tool.isError !== true) continue;
+		if (!stringifyToolResult(tool.result).includes(HUB_APPROVAL_CODE)) continue;
+		const approval = findApprovalDetails(tool.result);
+		const message = findResultMessage(tool.result) ?? "Hub action requires approval";
+		return {
+			...approval?.id ? { approvalId: approval.id } : {},
+			...approval?.connectionId ? { connectionId: approval.connectionId } : {},
+			message
+		};
+	}
+}
+/** Read an `interaction` event (kind `question`) into an awaiting-question requirement. */
+function readQuestionEvent(data) {
+	const request = data.request;
+	if (!request || request.kind !== "question" || typeof request.id !== "string") return;
+	return {
+		questionId: request.id,
+		questions: questionsFromAnswerSpec(request)
+	};
+}
+/** Reconstruct the prompt/options shape from a question interaction's answerSpec. */
+function questionsFromAnswerSpec(request) {
+	return request.answerSpec.fields.map((field) => field.type === "select" ? {
+		question: field.label,
+		options: field.options.map((o) => ({
+			label: o.label,
+			description: o.description
+		})),
+		multiSelect: field.multi === true
+	} : { question: field.label });
+}
+/**
+* Convert a thrown error into an in-band `error` SandboxEvent so a streaming
+* generator can surface a failure as an event followed by a terminal `done`
+* instead of throwing mid-iteration (which blanks the stream). Structured
+* `SandboxError` fields (code/status/origin/endpoint/retryAfterMs) are carried
+* through so consumers can inspect the failure without re-parsing the message.
+*/
+function toStreamErrorEvent(err) {
+	if (err instanceof SandboxError) return {
+		type: "error",
+		data: {
+			message: err.message,
+			code: err.code,
+			name: err.name,
+			...err.status !== void 0 ? { status: err.status } : {},
+			...err.origin ? { origin: err.origin } : {},
+			...err.endpoint ? { endpoint: err.endpoint } : {},
+			...err.retryAfterMs !== void 0 ? { retryAfterMs: err.retryAfterMs } : {}
+		}
+	};
+	return {
+		type: "error",
+		data: {
+			message: err instanceof Error ? err.message : String(err),
+			name: err instanceof Error ? err.name : "Error"
+		}
+	};
+}
+const WRITE_MANY_DEFAULT_PACE_MS = 150;
+const WRITE_MANY_DEFAULT_MAX_RETRIES = 4;
+const WRITE_MANY_RETRY_BASE_MS = 250;
+const WRITE_MANY_RETRY_MAX_MS = 2e3;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Transient file-write failures worth retrying: rate-limit (quota), 5xx,
+*  transport (network), and request timeouts. A non-transient error (bad path,
+*  auth, validation) fails loud immediately. */
+function isTransientWriteError(err) {
+	return err instanceof QuotaError || err instanceof ServerError || err instanceof NetworkError || err instanceof TimeoutError;
+}
+/**
+* A sandbox instance with methods for interaction.
+*/
+var SandboxInstance = class SandboxInstance {
+	client;
+	info;
+	defaultRuntimeBackend;
+	constructor(client, info, defaultRuntimeBackend) {
+		this.client = client;
+		this.info = info;
+		this.defaultRuntimeBackend = defaultRuntimeBackend;
+	}
+	/** Unique sandbox identifier */
+	get id() {
+		return this.info.id;
+	}
+	/** Human-readable name */
+	get name() {
+		return this.info.name;
+	}
+	/** Current status */
+	get status() {
+		return this.info.status;
+	}
+	/** Connection information */
+	get connection() {
+		return this.info.connection;
+	}
+	/** Custom metadata */
+	get metadata() {
+		return this.info.metadata;
+	}
+	/** When the sandbox was created */
+	get createdAt() {
+		return this.info.createdAt;
+	}
+	/** When the sandbox started running */
+	get startedAt() {
+		return this.info.startedAt;
+	}
+	/** Last activity timestamp */
+	get lastActivityAt() {
+		return this.info.lastActivityAt;
+	}
+	/** When the sandbox will expire */
+	get expiresAt() {
+		return this.info.expiresAt;
+	}
+	/** Error message if status is 'failed' */
+	get error() {
+		return this.info.error;
+	}
+	/** Web terminal URL for browser-based access */
+	get url() {
+		return this.info.connection?.webTerminalUrl;
+	}
+	/**
+	* The 12-phase startup breakdown (storage_provision, host_select, edge_bind,
+	* edge_ready, egress_proxy, docker_pull/create/start, sidecar_boot,
+	* health_check, …) the platform emitted when this sandbox was provisioned.
+	*
+	* Present only on a freshly-created box; `null` for a box resolved by id or
+	* when the runtime did not report diagnostics. Use `.phases` for the
+	* operation-name → durationMs map.
+	*
+	* @example
+	* ```typescript
+	* const d = box.startupDiagnostics();
+	* if (d) console.log(`provision phases: ${JSON.stringify(d.phases)}`);
+	* ```
+	*/
+	startupDiagnostics() {
+		return this.info.startupDiagnostics ?? null;
+	}
+	/**
+	* Serialize to the public sandbox shape for logs and structured
+	* output. Secrets in `connection` (currently `authToken`) are
+	* redacted so that `JSON.stringify(box)` is safe to ship to log
+	* sinks. Use {@link toDebugJSON} when the bearer is required (e.g.
+	* one-off CLI commands that print credentials to the user).
+	*/
+	toJSON() {
+		return {
+			id: this.id,
+			name: this.name,
+			status: this.status,
+			connection: redactConnectionSecrets(this.connection),
+			metadata: this.metadata,
+			createdAt: this.createdAt,
+			startedAt: this.startedAt,
+			lastActivityAt: this.lastActivityAt,
+			expiresAt: this.expiresAt,
+			error: this.error
+		};
+	}
+	/**
+	* Serialize the sandbox **including secrets** when `includeSecrets`
+	* is true. The default behavior matches {@link toJSON} and redacts
+	* `connection.authToken`.
+	*
+	* Use only when the caller has an explicit need for the bearer
+	* (e.g. presenting it once to the human operator). Never wire the
+	* result of `toDebugJSON({ includeSecrets: true })` into a structured
+	* logger — the bearer will land in any log sink consuming that output.
+	*/
+	toDebugJSON(options = {}) {
+		if (options.includeSecrets !== true) return this.toJSON();
+		return {
+			...this.toJSON(),
+			connection: this.connection
+		};
+	}
+	/**
+	* Create an advanced direct-runtime view of this sandbox.
+	*
+	* Runtime methods on the returned instance talk to the sandbox runtime
+	* directly using `connection.runtimeUrl` and `connection.authToken`.
+	* Lifecycle methods still go through the parent SDK client.
+	*/
+	direct() {
+		if (!this.connection?.runtimeUrl) throw new StateError("Sandbox has no direct runtime URL", this.status, "running");
+		let directInstance;
+		directInstance = new SandboxInstance(new DirectRuntimeHttpClient(this.client, this.id, () => directInstance.connection, async () => {
+			await directInstance.refresh();
+			const next = directInstance.connection?.authToken;
+			const client = this.client;
+			if (next && typeof client._emitTokenRefresh === "function") client._emitTokenRefresh(this.id, next);
+		}), { ...this.info }, this.defaultRuntimeBackend);
+		return directInstance;
+	}
+	/**
+	* Get an MCP endpoint for this sandbox. Returns a paste-able config
+	* for any MCP-capable host (Claude Desktop, Cursor, claude-code,
+	* codex, opencode, …) plus a freshly-minted, capability-scoped JWT.
+	*
+	* The token is short-lived and limited to the requested capabilities
+	* — it cannot be used against admin endpoints (`/exec`, `/files`,
+	* etc.) on the sandbox. Call `getMcpEndpoint()` again to rotate.
+	*
+	* Requires the sandbox to have been created with `capabilities`
+	* including the requested capability (default: `computer_use`).
+	*
+	* @example
+	* ```typescript
+	* const ep = await box.getMcpEndpoint();
+	* // Save ep.config to your IDE's mcp.json — that's it.
+	* fs.writeFileSync("mcp.json", JSON.stringify(ep.config, null, 2));
+	* ```
+	*/
+	async getMcpEndpoint(options) {
+		const params = new URLSearchParams();
+		if (options?.capabilities && options.capabilities.length > 0) params.set("capabilities", options.capabilities.join(","));
+		if (options?.serverName) params.set("serverName", options.serverName);
+		if (options?.ttlMinutes) params.set("ttlMinutes", String(options.ttlMinutes));
+		const qs = params.toString();
+		const path = `/v1/sandboxes/${this.id}/mcp${qs ? `?${qs}` : ""}`;
+		const response = await this.client.fetch(path);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	/**
+	* Refresh sandbox information from the server.
+	*/
+	async refresh() {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}`);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		this.info = this.parseInfo(data);
+	}
+	/**
+	* Fetch fresh TEE attestation evidence for this sandbox.
+	*
+	* When `attestationNonce` is supplied, the runtime must return evidence bound
+	* to that challenge or fail closed if the selected TEE backend cannot support
+	* nonce-bound report data.
+	*/
+	async getTeeAttestation(options) {
+		await this.ensureRunning();
+		const hasNonce = Boolean(options?.attestationNonce);
+		const response = await this.client.fetch(`/v1/sandboxes/${encodeURIComponent(this.id)}/tee/attestation`, {
+			method: hasNonce ? "POST" : "GET",
+			body: hasNonce ? JSON.stringify({ attestation_nonce: options?.attestationNonce }) : void 0
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		if (hasNonce) data.attestationNonce = options?.attestationNonce;
+		this.info = {
+			...this.info,
+			metadata: {
+				...this.info.metadata ?? {},
+				teeAttestationJson: JSON.stringify(data.attestation),
+				...data.attestationNonce ? { attestationNonce: data.attestationNonce } : {}
+			}
+		};
+		return data;
+	}
+	/**
+	* Fetch the TEE-bound public key used for sealed-secret encryption.
+	*
+	* The returned key includes an attestation report. Verify that report before
+	* encrypting secrets to the key.
+	*/
+	async getTeePublicKey() {
+		await this.ensureRunning();
+		const response = await this.client.fetch(`/v1/sandboxes/${encodeURIComponent(this.id)}/tee/public-key`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		this.info = {
+			...this.info,
+			metadata: {
+				...this.info.metadata ?? {},
+				teePublicKeyJson: JSON.stringify(data.public_key)
+			}
+		};
+		return data;
+	}
+	/**
+	* Bootstrap a real-time collaboration session for a file.
+	* Returns the WebSocket URL and auth token needed to connect a
+	* Hocuspocus/Yjs provider for live multi-user editing.
+	*
+	* @example
+	* ```typescript
+	* const collab = await box.collaborate("src/index.ts")
+	* // Use collab.transport.websocketUrl + collab.transport.token
+	* // with @hocuspocus/provider to connect
+	* ```
+	*/
+	async collaborate(path, options) {
+		const response = await this.client.fetch("/v1/collaboration/bootstrap", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				sandboxId: this.id,
+				path,
+				access: options?.access ?? "write"
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	/**
+	* Refresh a collaboration token for an existing document session.
+	*/
+	/**
+	* Refresh a collaboration token. Access level is preserved from the original
+	* token — cannot be escalated (read stays read, write stays write).
+	*/
+	async refreshCollaborationToken(documentId, currentToken) {
+		const response = await this.client.fetch("/v1/collaboration/token", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				sandboxId: this.id,
+				documentId,
+				currentToken
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	/**
+	* Get SSH credentials for connecting to the sandbox.
+	* Throws if SSH is not enabled or sandbox is not running.
+	*/
+	async ssh() {
+		await this.ensureRunning();
+		if (!this.connection?.ssh) throw new StateError("SSH is not enabled for this sandbox", this.status, "running");
+		return this.connection.ssh;
+	}
+	async sshCommand() {
+		const ssh = await this.ssh();
+		const authToken = this.client.getApiKey?.();
+		if (!authToken) throw new AuthError("SSH command requires client API key access to populate proxy auth");
+		const nullKnownHostsFile = process.platform === "win32" ? "NUL" : "/dev/null";
+		return {
+			command: `ssh -o ProxyCommand="${ssh.proxyCommand}" -o StrictHostKeyChecking=no -o UserKnownHostsFile=${nullKnownHostsFile} -o GlobalKnownHostsFile=${nullKnownHostsFile} -o LogLevel=ERROR -o ServerAliveInterval=15 -o ServerAliveCountMax=4 -o TCPKeepAlive=yes ${ssh.username}@localhost -p ${ssh.port}`,
+			env: { TANGLE_SSH_PROXY_AUTH_TOKEN: authToken }
+		};
+	}
+	/**
+	* Execute a command in the sandbox.
+	*/
+	async exec(command, options) {
+		await this.ensureRunning();
+		const headers = {};
+		if (options?.sessionId) headers["X-Session-Id"] = options.sessionId;
+		const response = await this.runtimeFetch("/terminals/commands", {
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				command,
+				cwd: options?.cwd,
+				env: options?.env,
+				timeout: options?.timeoutMs
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		const result = data.result ?? data;
+		return {
+			exitCode: result.exitCode ?? 0,
+			stdout: result.stdout ?? "",
+			stderr: result.stderr ?? ""
+		};
+	}
+	/**
+	* Run code in a persistent language kernel.
+	*
+	* Each `(sessionId, language)` pair gets its own long-lived kernel that
+	* keeps variable state across calls — like Jupyter cells. Without a
+	* `sessionId`, calls share a process-wide kernel per language.
+	*
+	* Returns typed results: stdout/stderr text plus a `results` array of
+	* structured outputs (matplotlib images as base64 PNG, pandas DataFrames,
+	* explicit `display(value)` calls as JSON/HTML, errors with traceback).
+	*
+	* @example Persistent Python session
+	* ```ts
+	* await box.runCode("python", "import pandas as pd; df = pd.DataFrame({'x': range(5)})", { sessionId: "s1" });
+	* const r = await box.runCode("python", "df.describe()", { sessionId: "s1" });
+	* // r.results[0] is a `dataframe` part with columns + rows from the describe()
+	* ```
+	*
+	* @example Matplotlib chart
+	* ```ts
+	* const r = await box.runCode("python",
+	*   "import matplotlib.pyplot as plt; plt.plot([1,2,3,4]); plt.show()",
+	*   { sessionId: "s1" });
+	* const png = r.results.find(p => p.type === "image");
+	* // png.data is a base64 PNG ready to render or hand back to an LLM
+	* ```
+	*/
+	async runCode(language, source, options) {
+		if (options?.sessionId !== void 0) assertValidSessionId(options.sessionId);
+		await this.ensureRunning();
+		const headers = {};
+		if (options?.sessionId) headers["X-Session-Id"] = options.sessionId;
+		if (options?.idempotencyKey) headers["X-Idempotency-Key"] = options.idempotencyKey;
+		const response = await this.runtimeFetch("/code/exec", {
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				language,
+				source,
+				timeoutMs: options?.timeoutMs,
+				env: options?.env,
+				cwd: options?.cwd
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const payload = await response.json();
+		if (!payload.success || !payload.data) throw new Error(payload.error?.message ?? "runCode failed without a typed error");
+		return payload.data;
+	}
+	/**
+	* Read a file from the sandbox.
+	*
+	* @param path - Path to the file. Relative paths resolve from the workspace root.
+	*   Absolute paths (e.g., `/tmp/output.json`) access the container filesystem directly.
+	* @returns File content as string
+	*
+	* @example
+	* ```typescript
+	* const content = await box.read("src/index.ts");
+	* const report = await box.read("/output/report.json");
+	* ```
+	*/
+	async read(path, options) {
+		await this.ensureRunning();
+		const headers = {};
+		if (options?.sessionId) headers["X-Session-Id"] = options.sessionId;
+		const response = await this.runtimeFetch("/files/read", {
+			method: "POST",
+			headers,
+			body: JSON.stringify({ path })
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).data?.content ?? "";
+	}
+	/**
+	* Write content to a file in the sandbox.
+	*
+	* @param path - Path to the file. Relative paths resolve from the workspace root.
+	*   Absolute paths (e.g., `/tmp/cases.json`) write to the container filesystem directly.
+	* @param content - Content to write
+	*
+	* @example
+	* ```typescript
+	* await box.write("src/fix.ts", "export const fix = () => {}");
+	* await box.write("/tmp/config.json", JSON.stringify(config));
+	* ```
+	*/
+	async write(path, content) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/files/write", {
+			method: "POST",
+			body: JSON.stringify({
+				path,
+				content
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/**
+	* Write many files in one paced, retry-aware batch — see
+	* {@link FileSystem.writeMany}. Each file goes through {@link write}; a small
+	* pace between writes keeps a large corpus under the file-write rate limit,
+	* and transient failures (quota / server / network / timeout) retry with
+	* exponential backoff (honoring a server `retryAfterMs`). Fail-loud on the
+	* first file that cannot be written after its retries.
+	*/
+	async writeMany(files, options = {}) {
+		const paceMs = options.paceMs ?? WRITE_MANY_DEFAULT_PACE_MS;
+		const maxRetries = options.maxRetries ?? WRITE_MANY_DEFAULT_MAX_RETRIES;
+		let started = false;
+		for (const file of files) for (let attempt = 0;; attempt++) {
+			if (started && paceMs > 0) await delay(paceMs);
+			started = true;
+			try {
+				await this.write(file.path, file.content);
+				break;
+			} catch (err) {
+				if (isTransientWriteError(err) && attempt < maxRetries) {
+					const backoff = Math.min(WRITE_MANY_RETRY_BASE_MS * 2 ** attempt, WRITE_MANY_RETRY_MAX_MS);
+					await delay((err instanceof SandboxError ? err.retryAfterMs : void 0) ?? backoff);
+					continue;
+				}
+				throw err;
+			}
+		}
+	}
+	/**
+	* Send a prompt to the agent running in the sandbox.
+	* Returns the complete response after the agent finishes.
+	*/
+	async prompt(message, options) {
+		await this.ensureRunning();
+		const startTime = Date.now();
+		let responseText;
+		let runError;
+		let traceId;
+		let usage;
+		let costUsd;
+		let toolInvocations;
+		let question;
+		let terminalReached = false;
+		const controller = new AbortController();
+		try {
+			const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+			for await (const event of this.streamPrompt(message, {
+				...options,
+				signal
+			})) {
+				responseText = applySandboxEventText(responseText, event);
+				if (event.type === "result" || event.type === "done") {
+					usage = readTokenUsage(event.data) ?? usage;
+					costUsd = readTokenCostUsd(event.data) ?? costUsd;
+				}
+				if (event.type === "result") toolInvocations = readToolInvocations(event.data) ?? toolInvocations;
+				if (event.type === "result" || event.type === "done") terminalReached = true;
+				if (event.type === "interaction") question = readQuestionEvent(event.data) ?? question;
+				if (event.type === "trace.id") traceId = event.data.traceId;
+				if (event.type === "error") runError = event.data.message;
+			}
+			const approval = detectHubApproval(toolInvocations);
+			const outcome = deriveOutcome({
+				terminalReached,
+				runError,
+				toolInvocations,
+				approval,
+				question
+			});
+			return {
+				success: outcome.success,
+				status: outcome.status,
+				response: responseText,
+				error: outcome.error,
+				toolInvocations,
+				approval,
+				question,
+				traceId,
+				durationMs: Date.now() - startTime,
+				usage,
+				costUsd
+			};
+		} catch (err) {
+			return {
+				success: false,
+				status: "failed",
+				error: err instanceof Error ? err.message : String(err),
+				durationMs: Date.now() - startTime
+			};
+		} finally {
+			controller.abort();
+		}
+	}
+	/**
+	* Stream events from an agent prompt.
+	* Use this for real-time updates during agent execution.
+	*
+	* Guarantees a terminal event on every non-cancelled path: a clean run
+	* ends with the runtime's `result`/`done`; a failure (pre-stream HTTP
+	* error, mid-stream network drop, timeout, or reconnect exhaustion) is
+	* surfaced as an in-band `error` event followed by a synthetic `done`,
+	* never a thrown generator. Caller-initiated cancellation (aborting
+	* `options.signal`) ends the stream silently with no synthetic terminal.
+	*
+	* Automatically reconnects via the runtime event replay endpoint if the
+	* SSE stream drops before a terminal event (`result` or `done`) is
+	* received. Reconnection is transparent — replayed events that were
+	* already yielded (based on event ID tracking) are deduplicated.
+	*/
+	async *streamPrompt(message, options) {
+		const isCallerAbort = () => options?.signal?.aborted === true;
+		let receivedTerminal = false;
+		let sessionId = options?.sessionId;
+		let executionId = options?.executionId;
+		try {
+			for await (const event of this.streamPromptInner(message, options)) {
+				if (event.type === "result" || event.type === "done") receivedTerminal = true;
+				if (event.type === "execution.started" && event.data.executionId) executionId = event.data.executionId;
+				const sid = event.data.sessionId;
+				if (typeof sid === "string" && sid.length > 0) sessionId = sid;
+				yield event;
+			}
+		} catch (err) {
+			if (isCallerAbort()) return;
+			yield toStreamErrorEvent(err);
+		} finally {
+			if (!receivedTerminal && !isCallerAbort()) yield {
+				type: "done",
+				data: {
+					status: "failed",
+					...sessionId ? { sessionId } : {},
+					...executionId ? { executionId } : {}
+				}
+			};
+		}
+	}
+	/**
+	* Inner prompt stream: opens the SSE connection and reconnects on silent
+	* drops. May throw (pre-stream HTTP error, timeout, reconnect exhausted);
+	* the public `streamPrompt` wrapper converts those throws into a terminal
+	* `error` + `done` so callers never see a thrown generator.
+	*/
+	async *streamPromptInner(message, options) {
+		await this.ensureRunning();
+		const parts = encodePromptForWire(message);
+		const timeoutMs = typeof options?.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : void 0;
+		const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : void 0;
+		const streamSignal = timeoutSignal ? options?.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal : options?.signal;
+		const throwIfTimedOut = () => {
+			if (!timeoutSignal?.aborted || !timeoutMs) return;
+			throw new TimeoutError(timeoutMs, `Prompt stream timed out after ${timeoutMs}ms`, {
+				endpoint: "/agents/run/stream",
+				origin: "runtime"
+			});
+		};
+		let response;
+		try {
+			response = await this.runtimeFetch("/agents/run/stream", {
+				method: "POST",
+				signal: streamSignal,
+				headers: {
+					...options?.executionId ? { "X-Execution-ID": options.executionId } : {},
+					...options?.lastEventId ? { "Last-Event-ID": options.lastEventId } : {},
+					...options?.detach ? { "x-agent-detach": "true" } : {}
+				},
+				body: JSON.stringify({
+					identifier: "default",
+					parts,
+					sessionId: options?.sessionId,
+					turnId: options?.turnId,
+					metadata: options?.context,
+					...options?.detach ? { detach: true } : {},
+					backend: normalizeRuntimeBackendConfig(options?.backend ?? this.defaultRuntimeBackend, { model: options?.model })
+				})
+			});
+		} catch (err) {
+			throwIfTimedOut();
+			throw err;
+		}
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		let lastEventId = options?.lastEventId;
+		let executionId = options?.executionId;
+		let sessionId = options?.sessionId;
+		let receivedTerminal = false;
+		const RECONNECT_BACKOFF_MS = [
+			2e3,
+			4e3,
+			8e3,
+			16e3,
+			3e4,
+			3e4
+		];
+		const MAX_RECONNECT_ATTEMPTS = RECONNECT_BACKOFF_MS.length;
+		let lastReplayStatus;
+		let lastExecutionStatus;
+		for await (const event of this.parseSSEStream(response, streamSignal)) {
+			if (event.id) lastEventId = event.id;
+			if (event.type === "execution.started" && event.data?.executionId) executionId = event.data.executionId;
+			const eventSessionId = event.data?.sessionId;
+			if (typeof eventSessionId === "string" && eventSessionId.length > 0) sessionId = eventSessionId;
+			if (event.type === "result" || event.type === "done") receivedTerminal = true;
+			yield event;
+		}
+		if (receivedTerminal) return;
+		throwIfTimedOut();
+		if (options?.signal?.aborted || streamSignal?.aborted) return;
+		if (!executionId) throw new NetworkError("Prompt stream dropped before execution.started; cannot reconnect", {
+			endpoint: "/agents/run/stream",
+			origin: "runtime"
+		});
+		for (let attempt = 1; attempt <= MAX_RECONNECT_ATTEMPTS; attempt++) {
+			throwIfTimedOut();
+			if (options?.signal?.aborted || streamSignal?.aborted) return;
+			console.warn(`[sandbox-sdk] Stream dropped without terminal event, reconnecting (attempt ${attempt}/${MAX_RECONNECT_ATTEMPTS})`);
+			await new Promise((resolve) => setTimeout(resolve, RECONNECT_BACKOFF_MS[attempt - 1]));
+			throwIfTimedOut();
+			if (options?.signal?.aborted || streamSignal?.aborted) return;
+			try {
+				const queryParams = lastEventId ? `?lastEventId=${encodeURIComponent(lastEventId)}&format=sse` : "?format=sse";
+				const replayResponse = await this.runtimeFetch(`/agents/run/${encodeURIComponent(executionId)}/events${queryParams}`, {
+					method: "GET",
+					signal: streamSignal
+				});
+				if (!replayResponse.ok) {
+					lastReplayStatus = replayResponse.status;
+					console.warn(`[sandbox-sdk] Replay endpoint returned ${replayResponse.status}, attempt ${attempt}`);
+					if (replayResponse.status === 404 && sessionId) try {
+						const info = await this._sessionStatus(sessionId);
+						if (info) {
+							lastExecutionStatus = info.status;
+							if (info.status === "completed" || info.status === "failed" || info.status === "cancelled") {
+								console.warn(`[sandbox-sdk] Replay 404 but session ${sessionId} is terminal (${info.status}); ending stream gracefully`);
+								yield {
+									type: "done",
+									data: {
+										sessionId,
+										executionId,
+										status: info.status,
+										replayUnavailable: true
+									}
+								};
+								return;
+							}
+						}
+					} catch (statusErr) {
+						console.warn(`[sandbox-sdk] Session status poll failed during replay 404: ${statusErr instanceof Error ? statusErr.message : String(statusErr)}`);
+					}
+					continue;
+				}
+				for await (const event of this.parseSSEStream(replayResponse, streamSignal)) {
+					if (event.type === "history.replay.start" || event.type === "history.replay.end") continue;
+					if (event.id) lastEventId = event.id;
+					const eventSessionId = event.data?.sessionId;
+					if (typeof eventSessionId === "string" && eventSessionId.length > 0) sessionId = eventSessionId;
+					if (event.type === "result" || event.type === "done") receivedTerminal = true;
+					yield event;
+				}
+				if (receivedTerminal) return;
+				throwIfTimedOut();
+				if (options?.signal?.aborted || streamSignal?.aborted) return;
+			} catch (err) {
+				throwIfTimedOut();
+				console.warn(`[sandbox-sdk] Reconnection attempt ${attempt} failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+		if (!receivedTerminal) {
+			console.warn(`[sandbox-sdk] Exhausted ${MAX_RECONNECT_ATTEMPTS} reconnection attempts without receiving terminal event`);
+			const replayStatusText = lastReplayStatus !== void 0 ? `; last replay status ${lastReplayStatus}` : "";
+			const execStatusText = lastExecutionStatus ? `; last known execution status ${lastExecutionStatus}` : "";
+			throw new NetworkError(`Prompt stream ended before a terminal event for execution ${executionId}${replayStatusText}${execStatusText}`, {
+				endpoint: `/agents/run/${executionId}/events`,
+				origin: "runtime"
+			});
+		}
+	}
+	/**
+	* Stream sandbox lifecycle and activity events.
+	*/
+	async *events(options) {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/events`, { signal: options?.signal });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		for await (const event of this.parseSSEStream(response, options?.signal)) {
+			if (options?.eventTypes && !options.eventTypes.includes(event.type)) continue;
+			yield event;
+		}
+	}
+	async trace(options = {}) {
+		const query = new URLSearchParams();
+		if (options.includeIntelligence === true) query.set("includeIntelligence", "true");
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/trace${query.size ? `?${query}` : ""}`);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	async intelligence() {
+		const intelligence = (await this.trace({ includeIntelligence: true })).intelligence;
+		if (!intelligence) throw new Error("Sandbox intelligence was not returned");
+		return intelligence;
+	}
+	async createIntelligenceReport(options = {}) {
+		const { window, compareTo, ...rest } = options;
+		const response = await this.client.fetch("/v1/intelligence/reports", {
+			method: "POST",
+			body: JSON.stringify({
+				subject: {
+					type: "sandbox",
+					id: this.id,
+					window,
+					compareTo
+				},
+				...rest
+			})
+		});
+		const body = await response.text();
+		if (!response.ok) throw parseErrorResponse(response.status, body, void 0, response.headers);
+		return JSON.parse(body).report;
+	}
+	async createAgenticIntelligenceReport(options) {
+		return this.createIntelligenceReport({
+			mode: "agentic",
+			budget: {
+				billTo: "customer",
+				maxUsd: options.maxUsd
+			},
+			metadata: options.metadata
+		});
+	}
+	async exportTrace(sink) {
+		return exportTraceBundle(await this.trace(), sink);
+	}
+	/**
+	* Stream real-time provisioning progress events.
+	*
+	* Connects to the SSE events stream and yields typed `ProvisionEvent` objects
+	* for each provisioning step. The generator completes when provisioning
+	* finishes (success or failure) and returns the terminal result.
+	*
+	* @returns AsyncGenerator of ProvisionEvent, with a ProvisionResult return value
+	*
+	* @example
+	* ```typescript
+	* const box = await client.create({ image: "ethereum" });
+	*
+	* const stream = box.watchProvisioning();
+	* for await (const event of stream) {
+	*   console.log(`[${event.step}] ${event.status} — ${event.message}`);
+	* }
+	* // stream.return value contains the terminal result
+	* ```
+	*/
+	async *watchProvisioning(options) {
+		const abortController = new AbortController();
+		const signal = options?.signal;
+		if (signal) if (signal.aborted) abortController.abort();
+		else signal.addEventListener("abort", () => abortController.abort(), { once: true });
+		let result;
+		try {
+			for await (const event of this.events({
+				signal: abortController.signal,
+				eventTypes: [
+					"provision_progress",
+					"provision_complete",
+					"provision_failed"
+				]
+			})) if (event.type === "provision_progress") {
+				const d = event.data;
+				yield {
+					step: normalizeProvisionStep(d.step),
+					status: d.status,
+					message: d.message,
+					percent: d.progress,
+					detail: d.detail,
+					timestamp: d.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+				};
+			} else if (event.type === "provision_complete") {
+				result = {
+					type: "complete",
+					containerId: event.data.containerId,
+					timestamp: event.data.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+				};
+				break;
+			} else if (event.type === "provision_failed") {
+				result = {
+					type: "failed",
+					error: event.data.error ?? "Provisioning failed",
+					timestamp: event.data.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+				};
+				break;
+			}
+		} finally {
+			abortController.abort();
+		}
+		try {
+			await this.refresh();
+		} catch {}
+		return result;
+	}
+	/**
+	* Run an agentic task until completion.
+	*
+	* Unlike prompt(), task() is designed for autonomous agent work:
+	* - The agent works until it completes the task or hits an error
+	* - Session state is maintained for context continuity
+	* - Token usage is aggregated across the execution
+	*
+	* Note: The agent (OpenCode/Claude) handles multi-turn execution internally.
+	* Most tasks complete in a single call. The maxTurns option is for edge cases
+	* where the agent explicitly signals it needs additional input.
+	*
+	* @param prompt - Task description for the agent
+	* @param options - Task options
+	* @returns Task result with response and execution metadata
+	*/
+	async task(prompt, options) {
+		const startTime = Date.now();
+		const sessionId = options?.sessionId ?? `task-${crypto.randomUUID()}`;
+		let responseText;
+		let runError;
+		let traceId;
+		let usage;
+		let costUsd;
+		let toolInvocations;
+		let question;
+		let terminalReached = false;
+		try {
+			for await (const event of this.streamPrompt(prompt, {
+				...options,
+				sessionId
+			})) {
+				responseText = applySandboxEventText(responseText, event);
+				if (event.type === "result") {
+					const eventUsage = readTokenUsage(event.data);
+					if (eventUsage) usage = addTokenUsage(usage, eventUsage);
+					const eventCostUsd = readTokenCostUsd(event.data);
+					if (eventCostUsd !== void 0) costUsd = (costUsd ?? 0) + eventCostUsd;
+					toolInvocations = readToolInvocations(event.data) ?? toolInvocations;
+				}
+				if (event.type === "done" && costUsd === void 0) costUsd = readTokenCostUsd(event.data);
+				if (event.type === "result" || event.type === "done") terminalReached = true;
+				if (event.type === "interaction") question = readQuestionEvent(event.data) ?? question;
+				if (event.type === "trace.id") traceId = event.data.traceId;
+				if (event.type === "error") runError = event.data.message;
+			}
+			const approval = detectHubApproval(toolInvocations);
+			const outcome = deriveOutcome({
+				terminalReached,
+				runError,
+				toolInvocations,
+				approval,
+				question
+			});
+			return {
+				success: outcome.success,
+				status: outcome.status,
+				response: responseText,
+				error: outcome.error,
+				toolInvocations,
+				approval,
+				question,
+				traceId,
+				durationMs: Date.now() - startTime,
+				usage,
+				costUsd,
+				turnsUsed: 1,
+				sessionId
+			};
+		} catch (err) {
+			return {
+				success: false,
+				status: "failed",
+				error: err instanceof Error ? err.message : String(err),
+				durationMs: Date.now() - startTime,
+				turnsUsed: 1,
+				sessionId
+			};
+		}
+	}
+	/**
+	* Stream events from a task execution.
+	*
+	* Use this for real-time updates as the agent works:
+	* - Tool calls and results
+	* - Thinking/reasoning steps
+	* - File operations
+	* - Final response
+	*
+	* @param prompt - Task description for the agent
+	* @param options - Task options
+	*/
+	async *streamTask(prompt, options) {
+		const sessionId = options?.sessionId ?? `task-${crypto.randomUUID()}`;
+		yield {
+			type: "task.start",
+			data: {
+				sessionId,
+				prompt
+			}
+		};
+		try {
+			for await (const event of this.streamPrompt(prompt, {
+				...options,
+				sessionId
+			})) yield event;
+		} finally {
+			yield {
+				type: "task.complete",
+				data: { sessionId }
+			};
+		}
+	}
+	/**
+	* Search for text patterns in files using ripgrep.
+	*
+	* This is a first-class code search capability, not a shell wrapper.
+	* Ripgrep is pre-installed in all managed sandboxes.
+	*
+	* @param pattern - Regular expression pattern to search for
+	* @param options - Search options
+	* @returns Async iterator of search matches
+	*
+	* @example Search for task-marker comments
+	* ```typescript
+	* for await (const match of box.search("TASK:", { glob: "**\/*.ts" })) {
+	*   console.log(`${match.path}:${match.line}: ${match.text}`);
+	* }
+	* ```
+	*
+	* @example Collect all matches
+	* ```typescript
+	* const matches = [];
+	* for await (const match of box.search("function.*async")) {
+	*   matches.push(match);
+	* }
+	* ```
+	*/
+	async *search(pattern, options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/search", {
+			method: "POST",
+			body: JSON.stringify({
+				pattern,
+				glob: options?.glob,
+				cwd: options?.cwd,
+				maxResults: options?.maxResults,
+				ignoreCase: options?.ignoreCase,
+				context: options?.context
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const matches = (await response.json()).matches ?? [];
+		for (const match of matches) yield {
+			path: match.path,
+			line: match.line,
+			column: match.column ?? 1,
+			text: match.text,
+			before: match.before,
+			after: match.after
+		};
+	}
+	/**
+	* Live whole-sandbox resource usage (memory + CPU) from the container cgroup.
+	*
+	* Returns `null` when cgroup stats are unavailable (non-Linux host). Memory is
+	* in MB; `memoryPeakMb` is the high-water mark since the sandbox started. CPU
+	* is a cumulative microsecond counter — sample twice and compute
+	* `cpu% = ΔcpuUsageUsec / (ΔsampledAtMs * 10)` for utilization.
+	*
+	* @example
+	* ```typescript
+	* const r = await box.resourceUsage();
+	* if (r) console.log(`peak ${r.memoryPeakMb} MB`);
+	* ```
+	*/
+	async resourceUsage() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/health/detailed", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).resources ?? null;
+	}
+	/**
+	* Git capability object for repository operations.
+	*
+	* All git operations are executed in the sandbox workspace.
+	*
+	* @example Check status and commit
+	* ```typescript
+	* const status = await box.git.status();
+	* if (status.isDirty) {
+	*   await box.git.add(["."]);
+	*   await box.git.commit("Update files");
+	*   await box.git.push();
+	* }
+	* ```
+	*/
+	get git() {
+		return {
+			status: () => this.gitStatus(),
+			log: (limit) => this.gitLog(limit),
+			diff: (ref) => this.gitDiff(ref),
+			add: (paths) => this.gitAdd(paths),
+			commit: (message, options) => this.gitCommit(message, options),
+			push: (options) => this.gitPush(options),
+			pull: (options) => this.gitPull(options),
+			branches: () => this.gitBranches(),
+			checkout: (ref, options) => this.gitCheckout(ref, options)
+		};
+	}
+	async gitStatus() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/git/status", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return {
+			branch: data.branch ?? "main",
+			head: data.head ?? "",
+			isDirty: data.isDirty ?? false,
+			ahead: data.ahead ?? 0,
+			behind: data.behind ?? 0,
+			staged: data.staged ?? [],
+			modified: data.modified ?? [],
+			untracked: data.untracked ?? []
+		};
+	}
+	async gitLog(limit = 10) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/git/log?limit=${limit}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return ((await response.json()).commits ?? []).map((c) => ({
+			sha: c.sha,
+			shortSha: c.sha.slice(0, 7),
+			message: c.message,
+			author: c.author,
+			email: c.email,
+			date: new Date(c.date)
+		}));
+	}
+	async gitDiff(ref) {
+		await this.ensureRunning();
+		const url = ref ? `/git/diff?ref=${encodeURIComponent(ref)}` : "/git/diff";
+		const response = await this.runtimeFetch(url, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return {
+			files: data.files ?? [],
+			additions: data.additions ?? 0,
+			deletions: data.deletions ?? 0,
+			raw: data.raw ?? ""
+		};
+	}
+	async gitAdd(paths) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/git/add", {
+			method: "POST",
+			body: JSON.stringify({ paths })
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async gitCommit(message, options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/git/commit", {
+			method: "POST",
+			body: JSON.stringify({
+				message,
+				amend: options?.amend
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return {
+			sha: data.sha,
+			shortSha: data.sha.slice(0, 7),
+			message: data.message,
+			author: data.author,
+			email: data.email,
+			date: new Date(data.date)
+		};
+	}
+	async gitPush(options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/git/push", {
+			method: "POST",
+			body: JSON.stringify({ force: options?.force })
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async gitPull(options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/git/pull", {
+			method: "POST",
+			body: JSON.stringify({ rebase: options?.rebase })
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async gitBranches() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/git/branches", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).branches ?? [];
+	}
+	async gitCheckout(ref, options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/git/checkout", {
+			method: "POST",
+			body: JSON.stringify({
+				ref,
+				create: options?.create
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/**
+	* Tools capability object for managing language runtimes.
+	*
+	* Uses mise (polyglot version manager) to install and manage tools.
+	*
+	* @example Install and use Node.js
+	* ```typescript
+	* await box.tools.install("node", "22");
+	* await box.tools.use("node", "22");
+	* const list = await box.tools.list();
+	* ```
+	*/
+	get tools() {
+		return {
+			install: (tool, version) => this.toolsInstall(tool, version),
+			use: (tool, version) => this.toolsUse(tool, version),
+			list: () => this.toolsList(),
+			run: (tool, args) => this.toolsRun(tool, args)
+		};
+	}
+	/**
+	* File system operations beyond basic read/write:
+	* - Binary upload/download
+	* - Directory ops (uploadDir, downloadDir, list, mkdir)
+	* - Metadata (stat, exists)
+	* - Progress reporting for large files
+	*
+	* @example Upload and download
+	* ```typescript
+	* await box.fs.upload("./model.bin", "/workspace/models/model.bin");
+	* await box.fs.download("/workspace/results.zip", "./results.zip");
+	* ```
+	*
+	* @example Directory operations
+	* ```typescript
+	* await box.fs.uploadDir("./project", "/workspace/project");
+	* const files = await box.fs.list("/workspace");
+	* ```
+	*
+	* @example File management
+	* ```typescript
+	* if (await box.fs.exists("/workspace/config.json")) {
+	*   const info = await box.fs.stat("/workspace/config.json");
+	*   console.log(`Size: ${info.size}`);
+	* }
+	* await box.fs.mkdir("/workspace/output", { recursive: true });
+	* await box.fs.delete("/workspace/temp", { recursive: true });
+	* ```
+	*/
+	get fs() {
+		return {
+			read: (path) => this.read(path),
+			write: (path, content) => this.write(path, content),
+			writeMany: (files, options) => this.writeMany(files, options),
+			search: (query, options) => this.search(query, options),
+			upload: (localPath, remotePath, options) => this.fsUpload(localPath, remotePath, options),
+			download: (remotePath, localPath, options) => this.fsDownload(remotePath, localPath, options),
+			uploadDir: (localDir, remoteDir) => this.fsUploadDir(localDir, remoteDir),
+			downloadDir: (remoteDir, localDir) => this.fsDownloadDir(remoteDir, localDir),
+			list: (path, options) => this.fsList(path, options),
+			stat: (path) => this.fsStat(path),
+			delete: (path, options) => this.fsDelete(path, options),
+			mkdir: (path, options) => this.fsMkdir(path, options),
+			exists: (path) => this.fsExists(path)
+		};
+	}
+	async fsUpload(localPath, remotePath, options) {
+		await this.ensureRunning();
+		const fs = await import("node:fs/promises");
+		const path = await import("node:path");
+		const fileBuffer = await fs.readFile(localPath);
+		const fileName = path.basename(localPath);
+		if (options?.onProgress) options.onProgress({
+			bytesUploaded: 0,
+			totalBytes: fileBuffer.length,
+			percentage: 0
+		});
+		const formData = new FormData();
+		formData.append("file", new Blob([new Uint8Array(fileBuffer)]), fileName);
+		formData.append("path", remotePath);
+		const response = await this.runtimeFetch("/fs/upload", {
+			method: "POST",
+			body: formData,
+			headers: {}
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		if (options?.onProgress) options.onProgress({
+			bytesUploaded: fileBuffer.length,
+			totalBytes: fileBuffer.length,
+			percentage: 100
+		});
+	}
+	async fsDownload(remotePath, localPath, options) {
+		await this.ensureRunning();
+		const fs = await import("node:fs/promises");
+		const path = await import("node:path");
+		await fs.mkdir(path.dirname(localPath), { recursive: true });
+		const response = await this.runtimeFetch(`/fs/download${remotePath}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const contentLength = response.headers.get("content-length");
+		const totalBytes = contentLength ? Number.parseInt(contentLength, 10) : 0;
+		if (options?.onProgress && totalBytes > 0) options.onProgress({
+			bytesDownloaded: 0,
+			totalBytes,
+			percentage: 0
+		});
+		const buffer = await response.arrayBuffer();
+		await fs.writeFile(localPath, Buffer.from(buffer));
+		if (options?.onProgress) options.onProgress({
+			bytesDownloaded: buffer.byteLength,
+			totalBytes: buffer.byteLength,
+			percentage: 100
+		});
+	}
+	async fsUploadDir(localDir, remoteDir) {
+		await this.ensureRunning();
+		const fs = await import("node:fs/promises");
+		const path = await import("node:path");
+		const { execSync } = await import("node:child_process");
+		const tempTarPath = path.join(await fs.mkdtemp(path.join((await import("node:os")).tmpdir(), "upload-")), "archive.tar.gz");
+		try {
+			execSync(`tar -czf "${tempTarPath}" -C "${localDir}" .`, { stdio: "pipe" });
+			const tarBuffer = await fs.readFile(tempTarPath);
+			const formData = new FormData();
+			formData.append("archive", new Blob([new Uint8Array(tarBuffer)]), "archive.tar.gz");
+			formData.append("path", remoteDir);
+			const response = await this.runtimeFetch("/fs/upload-dir", {
+				method: "POST",
+				body: formData,
+				headers: {}
+			});
+			if (!response.ok) {
+				const body = await response.text();
+				throw parseErrorResponse(response.status, body, void 0, response.headers);
+			}
+		} finally {
+			await fs.unlink(tempTarPath).catch(() => {});
+		}
+	}
+	async fsDownloadDir(remoteDir, localDir) {
+		await this.ensureRunning();
+		const fs = await import("node:fs/promises");
+		const path = await import("node:path");
+		const { execSync } = await import("node:child_process");
+		const response = await this.runtimeFetch(`/fs/download-dir${remoteDir}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const tempDir = await fs.mkdtemp(path.join((await import("node:os")).tmpdir(), "download-"));
+		const tempTarPath = path.join(tempDir, "archive.tar.gz");
+		try {
+			const buffer = await response.arrayBuffer();
+			await fs.writeFile(tempTarPath, Buffer.from(buffer));
+			await fs.mkdir(localDir, { recursive: true });
+			execSync(`tar -xzf "${tempTarPath}" -C "${localDir}"`, { stdio: "pipe" });
+		} finally {
+			await fs.rm(tempDir, { recursive: true }).catch(() => {});
+		}
+	}
+	async fsList(path, options) {
+		await this.ensureRunning();
+		const params = new URLSearchParams();
+		if (options?.all) params.set("all", "true");
+		if (options?.long) params.set("long", "true");
+		const query = params.toString();
+		const url = query ? `/fs/list${path}?${query}` : `/fs/list${path}`;
+		const response = await this.runtimeFetch(url, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return ((await response.json()).data?.entries ?? []).map((e) => ({
+			name: e.name,
+			path: e.path,
+			size: e.size,
+			isDir: e.isDir,
+			isFile: e.isFile,
+			isSymlink: e.isSymlink,
+			permissions: e.permissions,
+			owner: e.owner,
+			group: e.group,
+			modTime: new Date(e.modTime),
+			accessTime: new Date(e.accessTime)
+		}));
+	}
+	async fsStat(path) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/fs/stat${path}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const e = (await response.json()).data;
+		return {
+			name: e.name,
+			path: e.path,
+			size: e.size,
+			isDir: e.isDir,
+			isFile: e.isFile,
+			isSymlink: e.isSymlink,
+			permissions: e.permissions,
+			owner: e.owner,
+			group: e.group,
+			modTime: new Date(e.modTime),
+			accessTime: new Date(e.accessTime)
+		};
+	}
+	async fsDelete(path, options) {
+		await this.ensureRunning();
+		const params = new URLSearchParams();
+		if (options?.recursive) params.set("recursive", "true");
+		const query = params.toString();
+		const url = query ? `/fs${path}?${query}` : `/fs${path}`;
+		const response = await this.runtimeFetch(url, { method: "DELETE" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async fsMkdir(path, options) {
+		await this.ensureRunning();
+		const params = new URLSearchParams();
+		if (options?.recursive) params.set("recursive", "true");
+		const query = params.toString();
+		const url = query ? `/fs/mkdir${path}?${query}` : `/fs/mkdir${path}`;
+		const response = await this.runtimeFetch(url, { method: "POST" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async fsExists(path) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/fs/exists${path}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).data?.exists === true;
+	}
+	/**
+	* Permissions manager for multi-user access control.
+	*
+	* @example List users
+	* ```typescript
+	* const users = await box.permissions.list();
+	* for (const user of users) {
+	*   console.log(`${user.username}: ${user.role}`);
+	* }
+	* ```
+	*
+	* @example Add a developer
+	* ```typescript
+	* await box.permissions.add({
+	*   userId: "user_abc",
+	*   role: "developer",
+	*   sshKeys: ["ssh-ed25519 AAAA..."],
+	* });
+	* ```
+	*/
+	get permissions() {
+		return {
+			list: () => this.permissionsList(),
+			get: (userId) => this.permissionsGet(userId),
+			add: (options) => this.permissionsAdd(options),
+			update: (userId, options) => this.permissionsUpdate(userId, options),
+			remove: (userId, options) => this.permissionsRemove(userId, options),
+			setAccessPolicies: (userId, rules) => this.permissionsSetAccessPolicies(userId, rules),
+			getAccessPolicies: (userId) => this.permissionsGetAccessPolicies(userId),
+			checkAccess: (userId, path, action) => this.permissionsCheckAccess(userId, path, action)
+		};
+	}
+	async permissionsList() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/permissions/users", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return ((await response.json()).users ?? []).map((u) => ({
+			userId: u.userId,
+			username: u.username,
+			homeDir: u.homeDir,
+			role: u.role,
+			sshKeys: u.sshKeys ?? [],
+			directoryPermissions: u.directoryPermissions,
+			accessPolicies: u.accessPolicies,
+			createdAt: new Date(u.createdAt)
+		}));
+	}
+	async permissionsGet(userId) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/permissions/users/${encodeURIComponent(userId)}`, { method: "GET" });
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const u = await response.json();
+		return {
+			userId: u.userId,
+			username: u.username,
+			homeDir: u.homeDir,
+			role: u.role,
+			sshKeys: u.sshKeys ?? [],
+			directoryPermissions: u.directoryPermissions,
+			accessPolicies: u.accessPolicies,
+			createdAt: new Date(u.createdAt)
+		};
+	}
+	async permissionsAdd(options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/permissions/users", {
+			method: "POST",
+			body: JSON.stringify(options)
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const u = await response.json();
+		return {
+			userId: u.userId,
+			username: u.username,
+			homeDir: u.homeDir,
+			role: u.role,
+			sshKeys: u.sshKeys ?? [],
+			directoryPermissions: u.directoryPermissions,
+			accessPolicies: u.accessPolicies,
+			createdAt: new Date(u.createdAt)
+		};
+	}
+	async permissionsUpdate(userId, options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/permissions/users/${encodeURIComponent(userId)}`, {
+			method: "PATCH",
+			body: JSON.stringify(options)
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const u = await response.json();
+		return {
+			userId: u.userId,
+			username: u.username,
+			homeDir: u.homeDir,
+			role: u.role,
+			sshKeys: u.sshKeys ?? [],
+			directoryPermissions: u.directoryPermissions,
+			accessPolicies: u.accessPolicies,
+			createdAt: new Date(u.createdAt)
+		};
+	}
+	async permissionsRemove(userId, options) {
+		await this.ensureRunning();
+		const params = new URLSearchParams();
+		if (options?.preserveHomeDir) params.set("preserveHomeDir", "true");
+		const query = params.toString();
+		const path = query ? `/permissions/users/${encodeURIComponent(userId)}?${query}` : `/permissions/users/${encodeURIComponent(userId)}`;
+		const response = await this.runtimeFetch(path, { method: "DELETE" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async permissionsSetAccessPolicies(userId, rules) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/permissions/users/${encodeURIComponent(userId)}/policies`, {
+			method: "PUT",
+			body: JSON.stringify({ rules })
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async permissionsGetAccessPolicies(userId) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/permissions/users/${encodeURIComponent(userId)}/policies`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).rules ?? [];
+	}
+	async permissionsCheckAccess(userId, path, action) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/permissions/users/${encodeURIComponent(userId)}/check`, {
+			method: "POST",
+			body: JSON.stringify({
+				path,
+				action
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).allowed === true;
+	}
+	/**
+	* Backend manager for runtime agent configuration.
+	*
+	* @example Check backend status
+	* ```typescript
+	* const status = await box.backend.status();
+	* console.log(`Backend: ${status.type}, Status: ${status.status}`);
+	* ```
+	*
+	* @example Add MCP server at runtime
+	* ```typescript
+	* await box.backend.addMcp("web-search", {
+	*   command: "npx",
+	*   args: ["-y", "@anthropic/web-search"],
+	* });
+	* ```
+	*
+	* @example Read provider-native Cursor metadata
+	* ```typescript
+	* const models = await box.backend.models();
+	* const agents = await box.backend.agents({ limit: 20 });
+	* const runs = await box.backend.runs(agents.items[0].agentId);
+	* ```
+	*/
+	get backend() {
+		return {
+			status: () => this.backendStatus(),
+			capabilities: () => this.backendCapabilities(),
+			addMcp: (name, config) => this.backendAddMcp(name, config),
+			getMcpStatus: () => this.backendGetMcpStatus(),
+			updateConfig: (config) => this.backendUpdateConfig(config),
+			account: () => this.backendAccount(),
+			models: () => this.backendModels(),
+			repositories: () => this.backendRepositories(),
+			agents: (options) => this.backendAgents(options),
+			agent: (agentId) => this.backendAgent(agentId),
+			archiveAgent: (agentId) => this.backendArchiveAgent(agentId),
+			unarchiveAgent: (agentId) => this.backendUnarchiveAgent(agentId),
+			deleteAgent: (agentId) => this.backendDeleteAgent(agentId),
+			runs: (agentId, options) => this.backendRuns(agentId, options),
+			run: (runId, options) => this.backendRun(runId, options),
+			agentMessages: (agentId, options) => this.backendAgentMessages(agentId, options),
+			artifacts: (sessionId) => this.backendArtifacts(sessionId),
+			downloadArtifact: (sessionId, path) => this.backendDownloadArtifact(sessionId, path),
+			restart: () => this.backendRestart()
+		};
+	}
+	async backendStatus() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/backend/status", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	async backendCapabilities() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/backend/capabilities", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	async backendAddMcp(name, config) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/backend/mcp", {
+			method: "POST",
+			body: JSON.stringify({
+				name,
+				config
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async backendGetMcpStatus() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/backend/mcp", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).servers ?? {};
+	}
+	async backendUpdateConfig(config) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/backend/config", {
+			method: "PATCH",
+			body: JSON.stringify(config)
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async backendControlData(path) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(path, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const payload = await response.json();
+		if (!payload || typeof payload !== "object" || !("data" in payload)) throw new ServerError("Backend control response missing data", 502, {
+			endpoint: path,
+			origin: "runtime"
+		});
+		return payload.data;
+	}
+	async backendControlAction(path, method) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(path, { method });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	backendListSearch(options) {
+		const search = new URLSearchParams();
+		if (options?.limit !== void 0) search.set("limit", String(options.limit));
+		if (options?.cursor) search.set("cursor", options.cursor);
+		const query = search.toString();
+		return query ? `?${query}` : "";
+	}
+	async backendAccount() {
+		return this.backendControlData("/config/account");
+	}
+	async backendModels() {
+		return this.backendControlData("/config/models");
+	}
+	async backendRepositories() {
+		return this.backendControlData("/config/repositories");
+	}
+	async backendAgents(options) {
+		return this.backendControlData(`/config/backend-agents${this.backendListSearch(options)}`);
+	}
+	async backendAgent(agentId) {
+		return this.backendControlData(`/config/backend-agents/${encodeURIComponent(agentId)}`);
+	}
+	async backendArchiveAgent(agentId) {
+		await this.backendControlAction(`/config/backend-agents/${encodeURIComponent(agentId)}/archive`, "POST");
+	}
+	async backendUnarchiveAgent(agentId) {
+		await this.backendControlAction(`/config/backend-agents/${encodeURIComponent(agentId)}/unarchive`, "POST");
+	}
+	async backendDeleteAgent(agentId) {
+		await this.backendControlAction(`/config/backend-agents/${encodeURIComponent(agentId)}`, "DELETE");
+	}
+	async backendRuns(agentId, options) {
+		return this.backendControlData(`/config/backend-agents/${encodeURIComponent(agentId)}/runs${this.backendListSearch(options)}`);
+	}
+	async backendRun(runId, options) {
+		const search = new URLSearchParams();
+		if (options?.agentId) search.set("agentId", options.agentId);
+		const query = search.toString();
+		return this.backendControlData(`/config/backend-runs/${encodeURIComponent(runId)}${query ? `?${query}` : ""}`);
+	}
+	async backendAgentMessages(agentId, options) {
+		return this.backendControlData(`/config/backend-agents/${encodeURIComponent(agentId)}/messages${this.backendListSearch(options)}`);
+	}
+	async backendArtifacts(sessionId) {
+		return this.backendControlData(`/config/artifacts/${encodeURIComponent(sessionId)}`);
+	}
+	async backendDownloadArtifact(sessionId, path) {
+		await this.ensureRunning();
+		const search = new URLSearchParams({ path });
+		const response = await this.runtimeFetch(`/config/artifacts/${encodeURIComponent(sessionId)}/download?${search.toString()}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const payload = await response.json();
+		if (!payload || typeof payload.base64 !== "string") throw new ServerError("Backend artifact download response missing base64", 502, {
+			endpoint: `/config/artifacts/${encodeURIComponent(sessionId)}/download`,
+			origin: "runtime"
+		});
+		return Uint8Array.from(Buffer.from(payload.base64, "base64"));
+	}
+	async backendRestart() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/backend/restart", { method: "POST" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/**
+	* Process manager for spawning and controlling processes.
+	*
+	* Provides non-blocking process execution with real-time log streaming,
+	* ideal for long-running tasks like ML training or dev servers.
+	*
+	* @example Non-blocking process
+	* ```typescript
+	* const proc = await box.process.spawn("python train.py", {
+	*   cwd: "/workspace",
+	*   env: { "CUDA_VISIBLE_DEVICES": "0" }
+	* });
+	*
+	* // Stream logs
+	* for await (const entry of proc.logs()) {
+	*   console.log(`[${entry.type}] ${entry.data}`);
+	* }
+	*
+	* // Check status
+	* const status = await proc.status();
+	* console.log(`Running: ${status.running}`);
+	*
+	* // Kill if needed
+	* await proc.kill();
+	* ```
+	*
+	* @example Run Python code directly
+	* ```typescript
+	* const result = await box.process.runCode(`
+	*   import numpy as np
+	*   print(np.random.rand(10).mean())
+	* `);
+	* console.log(result.stdout);
+	* ```
+	*/
+	get process() {
+		return {
+			spawn: (command, options) => this.processSpawn(command, options),
+			runCode: (code, options) => this.processRunCode(code, options),
+			list: () => this.processList(),
+			get: (pid) => this.processGet(pid)
+		};
+	}
+	async processSpawn(command, options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/process/spawn", {
+			method: "POST",
+			body: JSON.stringify({
+				command,
+				cwd: options?.cwd,
+				env: options?.env,
+				timeoutMs: options?.timeoutMs,
+				blocking: false
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return this.createProcessHandle(data.data.pid, command);
+	}
+	async processRunCode(code, options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/process/run-code", {
+			method: "POST",
+			body: JSON.stringify({
+				code,
+				cwd: options?.cwd,
+				env: options?.env,
+				timeoutMs: options?.timeoutMs,
+				blocking: true
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).data;
+	}
+	async processList() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/process", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return ((await response.json()).data ?? []).map((p) => ({
+			pid: p.pid,
+			command: p.command,
+			cwd: p.cwd,
+			running: p.running,
+			exitCode: p.exitCode,
+			exitSignal: p.exitSignal,
+			startedAt: new Date(p.startedAt),
+			exitedAt: p.exitedAt ? new Date(p.exitedAt) : void 0
+		}));
+	}
+	async processGet(pid) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/process/${pid}`, { method: "GET" });
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return this.createProcessHandle(pid, data.data.command);
+	}
+	createProcessHandle(pid, command) {
+		const self = this;
+		return {
+			pid,
+			command,
+			async status() {
+				const response = await self.runtimeFetch(`/process/${pid}`, { method: "GET" });
+				if (!response.ok) {
+					const body = await response.text();
+					throw parseErrorResponse(response.status, body, void 0, response.headers);
+				}
+				const p = (await response.json()).data;
+				return {
+					pid: p.pid,
+					command: p.command,
+					cwd: p.cwd,
+					running: p.running,
+					exitCode: p.exitCode,
+					exitSignal: p.exitSignal,
+					startedAt: new Date(p.startedAt),
+					exitedAt: p.exitedAt ? new Date(p.exitedAt) : void 0
+				};
+			},
+			async wait() {
+				while (true) {
+					const s = await this.status();
+					if (!s.running) return s.exitCode;
+					await new Promise((resolve) => setTimeout(resolve, 500));
+				}
+			},
+			async kill(signal = "SIGTERM", options) {
+				const response = await self.runtimeFetch(`/process/${pid}`, {
+					method: "DELETE",
+					body: JSON.stringify({
+						signal,
+						...options?.tree === true ? { tree: true } : {}
+					})
+				});
+				if (!response.ok && response.status !== 404) {
+					const body = await response.text();
+					throw parseErrorResponse(response.status, body, void 0, response.headers);
+				}
+			},
+			async *logs() {
+				const response = await self.runtimeFetch(`/process/${pid}/logs`, { method: "GET" });
+				if (!response.ok) {
+					const body = await response.text();
+					throw parseErrorResponse(response.status, body, void 0, response.headers);
+				}
+				yield* self.parseProcessLogStream(response);
+			},
+			async *stdout() {
+				for await (const entry of this.logs()) if (entry.type === "stdout") yield entry.data;
+			},
+			async *stderr() {
+				for await (const entry of this.logs()) if (entry.type === "stderr") yield entry.data;
+			}
+		};
+	}
+	async *parseProcessLogStream(response) {
+		const reader = response.body?.getReader();
+		if (!reader) throw new NetworkError("No response body");
+		const decoder = new TextDecoder();
+		let buffer = "";
+		let currentEvent = "";
+		let currentData = "";
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				buffer += decoder.decode(value, { stream: true });
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) if (line.startsWith("event:")) currentEvent = line.slice(6).trim();
+				else if (line.startsWith("data:")) currentData = line.slice(5).trim();
+				else if (line === "" && currentEvent && currentData) {
+					if (currentEvent === "stdout" || currentEvent === "stderr") try {
+						const parsed = JSON.parse(currentData);
+						yield {
+							type: currentEvent,
+							data: parsed.data,
+							timestamp: parsed.timestamp
+						};
+					} catch {}
+					else if (currentEvent === "exit") return;
+					currentEvent = "";
+					currentData = "";
+				}
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	/**
+	* Network manager for runtime network configuration.
+	*
+	* @example Update network restrictions
+	* ```typescript
+	* // Block all outbound traffic
+	* await box.network.update({ blockOutbound: true });
+	*
+	* // Or switch to allowlist mode
+	* await box.network.update({
+	*   allowList: ["192.168.1.0/24", "8.8.8.8/32"]
+	* });
+	* ```
+	*
+	* @example Expose ports dynamically
+	* ```typescript
+	* const url = await box.network.exposePort(8000);
+	* console.log(`Service available at: ${url}`);
+	* ```
+	*/
+	get network() {
+		return {
+			update: (config) => this.networkUpdate(config),
+			exposePort: (port) => this.networkExposePort(port),
+			listUrls: () => this.networkListUrls(),
+			getConfig: () => this.networkGetConfig()
+		};
+	}
+	/**
+	* Egress policy manager for controlling outbound internet access.
+	*
+	* @example Read current egress policy
+	* ```typescript
+	* const { policy, source } = await box.egress.get();
+	* console.log(policy.mode, source);
+	* ```
+	*
+	* @example Update egress policy at runtime
+	* ```typescript
+	* await box.egress.update({ mode: "strict", allowDomains: ["api.github.com"] });
+	* ```
+	*/
+	get egress() {
+		return {
+			get: () => this.egressGet(),
+			update: (policy) => this.egressUpdate(policy)
+		};
+	}
+	async networkUpdate(config) {
+		if (config.blockOutbound !== void 0 && config.allowList !== void 0) {
+			if (config.blockOutbound && config.allowList.length > 0) throw new Error("blockOutbound and allowList are mutually exclusive");
+		}
+		if (config.allowList) {
+			if (config.allowList.length > 10) throw new Error("allowList cannot exceed 10 entries");
+			for (const cidr of config.allowList) if (!this.isValidCidr(cidr)) throw new Error(`Invalid CIDR format: ${cidr}`);
+		}
+		const response = await this.runtimeFetch("/network", {
+			method: "PATCH",
+			body: JSON.stringify(config)
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async networkExposePort(port) {
+		if (port < 1 || port > 65535) throw new Error("Port must be between 1 and 65535");
+		const response = await this.runtimeFetch("/network/expose", {
+			method: "POST",
+			body: JSON.stringify({ port })
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).url;
+	}
+	async networkListUrls() {
+		const response = await this.runtimeFetch("/network/urls");
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).urls ?? {};
+	}
+	async networkGetConfig() {
+		const response = await this.runtimeFetch("/network");
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	async egressGet() {
+		const response = await this.client.fetch(`/v1/sandboxes/${encodeURIComponent(this.id)}`);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return {
+			policy: data.egressPolicy ?? { mode: "open" },
+			source: data.egressPolicySource ?? "platform"
+		};
+	}
+	async egressUpdate(policy) {
+		const response = await this.client.fetch(`/v1/sandboxes/${encodeURIComponent(this.id)}/egress`, {
+			method: "PATCH",
+			body: JSON.stringify(policy)
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		this.info = {
+			...this.info,
+			egressPolicy: data.egressPolicy,
+			egressPolicySource: data.source
+		};
+		return {
+			policy: data.egressPolicy,
+			source: data.source
+		};
+	}
+	/**
+	* Validate CIDR notation (IPv4 and IPv6)
+	*/
+	isValidCidr(cidr) {
+		const ipv4Pattern = /^(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\/(?:[0-9]|[12]\d|3[0-2])$/;
+		const ipv6Pattern = /^([a-fA-F0-9:]+)\/(\d{1,3})$/;
+		if (ipv4Pattern.test(cidr)) return true;
+		const ipv6Match = cidr.match(ipv6Pattern);
+		if (ipv6Match) {
+			const ipPart = ipv6Match[1];
+			const prefixPart = ipv6Match[2];
+			if (ipPart === void 0 || prefixPart === void 0) return false;
+			const prefix = Number.parseInt(prefixPart, 10);
+			if (prefix >= 0 && prefix <= 128) {
+				const groups = ipPart.split(":");
+				if (groups.length <= 8 && ipPart.includes(":")) return groups.every((g) => g === "" || /^[a-fA-F0-9]{1,4}$/.test(g));
+			}
+		}
+		return false;
+	}
+	/**
+	* Preview link management.
+	*
+	* Create publicly accessible HTTPS URLs for TCP ports inside the sandbox.
+	*
+	* @example
+	* ```typescript
+	* const link = await box.previewLinks.create(3000);
+	* console.log(link.url);
+	*
+	* const links = await box.previewLinks.list();
+	* await box.previewLinks.remove(link.previewId);
+	* ```
+	*/
+	get previewLinks() {
+		return {
+			create: (port, options) => this.previewLinkCreate(port, options),
+			list: () => this.previewLinkList(),
+			remove: (previewId) => this.previewLinkRemove(previewId)
+		};
+	}
+	async previewLinkCreate(port, options) {
+		if (port < 1 || port > 65535) throw new Error("Port must be between 1 and 65535");
+		const response = await this.runtimeFetch("/preview-links", {
+			method: "POST",
+			body: JSON.stringify({
+				port,
+				protocol: options?.protocol ?? "tcp",
+				metadata: options?.metadata
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return normalizePreviewLink((await response.json()).previewLink);
+	}
+	async previewLinkList() {
+		const response = await this.runtimeFetch("/preview-links");
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return ((await response.json()).previewLinks ?? []).map(normalizePreviewLink);
+	}
+	async previewLinkRemove(previewId) {
+		const response = await this.runtimeFetch(`/preview-links/${encodeURIComponent(previewId)}`, { method: "DELETE" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/**
+	* Get information about the infrastructure driver for this sandbox.
+	*
+	* @example
+	* ```typescript
+	* const info = await box.getDriverInfo();
+	* console.log(`Driver: ${info.type}, CRIU: ${info.capabilities.criu}`);
+	* ```
+	*/
+	async getDriverInfo() {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/driver`);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	async toolsInstall(tool, version) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/tools/install", {
+			method: "POST",
+			body: JSON.stringify({
+				tool,
+				version
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async toolsUse(tool, version) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/tools/use", {
+			method: "POST",
+			body: JSON.stringify({
+				tool,
+				version
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	async toolsList() {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/tools", { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).tools ?? [];
+	}
+	async toolsRun(tool, args) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/tools/run", {
+			method: "POST",
+			body: JSON.stringify({
+				tool,
+				args
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return {
+			exitCode: data.exitCode ?? 0,
+			stdout: data.stdout ?? "",
+			stderr: data.stderr ?? ""
+		};
+	}
+	/**
+	* Create a snapshot of the sandbox state.
+	* Snapshots can be used to save workspace state for later restoration.
+	*
+	* If `storage` is provided (BYOS3), the snapshot is created directly
+	* directly on the sandbox and uploaded to customer-provided S3 storage.
+	*
+	* @param options - Snapshot options (tags, paths, storage)
+	* @returns Snapshot result with ID and metadata
+	*
+	* @example Standard snapshot (our storage)
+	* ```typescript
+	* const snap = await box.snapshot({
+	*   tags: ["v1.0", "stable"],
+	* });
+	* console.log(`Snapshot: ${snap.snapshotId}`);
+	* ```
+	*
+	* @example BYOS3 snapshot (customer storage)
+	* ```typescript
+	* const snap = await box.snapshot({
+	*   tags: ["production"],
+	*   storage: {
+	*     type: "s3",
+	*     bucket: "my-snapshots",
+	*     credentials: { accessKeyId: "...", secretAccessKey: "..." },
+	*   },
+	* });
+	* ```
+	*/
+	async snapshot(options) {
+		await this.ensureRunning();
+		if (options?.storage) {
+			const response = await this.runtimeFetch("/snapshots", {
+				method: "POST",
+				body: JSON.stringify({
+					projectId: this.id,
+					storage: options.storage,
+					tags: options.tags,
+					paths: options.paths
+				})
+			});
+			if (!response.ok) {
+				const body = await response.text();
+				throw parseErrorResponse(response.status, body, void 0, response.headers);
+			}
+			const data = await response.json();
+			return {
+				snapshotId: data.snapshot?.id ?? data.snapshotId,
+				createdAt: new Date(data.snapshot?.createdAt ?? data.createdAt ?? Date.now()),
+				sizeBytes: data.snapshot?.sizeBytes ?? data.sizeBytes,
+				tags: data.snapshot?.tags ?? data.tags ?? []
+			};
+		}
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/snapshots`, {
+			method: "POST",
+			body: JSON.stringify({
+				tags: options?.tags,
+				paths: options?.paths
+			})
+		}, { timeoutMs: SNAPSHOT_CREATE_REQUEST_TIMEOUT_MS });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		const snapshotId = data.snapshotId ?? data.id;
+		if (typeof snapshotId !== "string" || snapshotId.length === 0) throw new ServerError(`Snapshot create returned 200 but body had no snapshot ID: ${JSON.stringify(data).slice(0, 200)}`, response.status);
+		const snapshot = {
+			snapshotId,
+			createdAt: new Date(data.createdAt ?? Date.now()),
+			sizeBytes: data.sizeBytes,
+			tags: data.tags ?? []
+		};
+		await this.waitForSnapshotVisible(snapshot.snapshotId, {
+			createdAt: snapshot.createdAt,
+			sizeBytes: snapshot.sizeBytes,
+			tags: snapshot.tags
+		});
+		return snapshot;
+	}
+	/**
+	* List all snapshots for this sandbox.
+	*
+	* If `storage` is provided (BYOS3), lists snapshots from customer-provided
+	* S3 storage.
+	*
+	* @param storage - Optional customer storage config for BYOS3
+	* @returns Array of snapshot metadata
+	*
+	* @example List from our storage
+	* ```typescript
+	* const snapshots = await box.listSnapshots();
+	* for (const snap of snapshots) {
+	*   console.log(`${snap.snapshotId}: ${snap.createdAt}`);
+	* }
+	* ```
+	*
+	* @example List from customer S3 (BYOS3)
+	* ```typescript
+	* const snapshots = await box.listSnapshots({
+	*   type: "s3",
+	*   bucket: "my-snapshots",
+	*   credentials: { accessKeyId: "...", secretAccessKey: "..." },
+	* });
+	* ```
+	*/
+	async listSnapshots(storage) {
+		if (storage) {
+			await this.ensureRunning();
+			const response = await this.runtimeFetch("/snapshots/list", {
+				method: "POST",
+				body: JSON.stringify({
+					projectId: this.id,
+					storage
+				})
+			});
+			if (!response.ok) {
+				const body = await response.text();
+				throw parseErrorResponse(response.status, body, void 0, response.headers);
+			}
+			return ((await response.json()).snapshots ?? []).map((s) => ({
+				snapshotId: s.id ?? s.snapshotId,
+				sandboxId: this.id,
+				createdAt: new Date(s.createdAt),
+				tags: s.tags ?? [],
+				paths: [],
+				sizeBytes: s.sizeBytes
+			}));
+		}
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/snapshots`);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return (Array.isArray(data) ? data : data.snapshots ?? []).map((s) => ({
+			snapshotId: s.snapshotId ?? s.id,
+			sandboxId: s.sandboxId ?? s.projectRef ?? this.id,
+			createdAt: new Date(s.createdAt),
+			tags: s.tags ?? [],
+			paths: s.paths ?? [],
+			sizeBytes: s.sizeBytes
+		}));
+	}
+	async revertToSnapshot(snapshotId) {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/snapshots/${encodeURIComponent(snapshotId)}/restore`, { method: "POST" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		if (response.status === 202) return this.waitForSnapshotRestore(snapshotId, data);
+		return toSnapshotResult(data);
+	}
+	async waitForSnapshotRestore(snapshotId, accepted) {
+		const deadline = Date.now() + SNAPSHOT_RESTORE_TIMEOUT_MS;
+		while (Date.now() < deadline) {
+			const response = await this.client.fetch(`/v1/sandboxes/${this.id}/snapshots/jobs/${encodeURIComponent(accepted.jobId)}`);
+			if (!response.ok) {
+				const body = await response.text();
+				throw parseErrorResponse(response.status, body, void 0, response.headers);
+			}
+			const status = await response.json();
+			if (status.status === "failed" || status.result?.success === false) throw new ServerError(status.result?.error ?? `Snapshot restore job ${accepted.jobId} failed`);
+			if (status.status === "completed") return await this.waitForSnapshotVisible(snapshotId, status.completedAt ? { createdAt: new Date(status.completedAt) } : void 0);
+			await this.sleep(SNAPSHOT_RESTORE_POLL_INTERVAL_MS);
+		}
+		throw new TimeoutError(SNAPSHOT_RESTORE_TIMEOUT_MS);
+	}
+	async waitForSnapshotVisible(snapshotId, fallback) {
+		const deadline = Date.now() + SNAPSHOT_VISIBILITY_TIMEOUT_MS;
+		let lastError;
+		while (Date.now() < deadline) {
+			try {
+				const snapshot = (await this.listSnapshots()).find((item) => item.snapshotId === snapshotId);
+				if (snapshot) return {
+					snapshotId: snapshot.snapshotId,
+					createdAt: snapshot.createdAt,
+					sizeBytes: snapshot.sizeBytes,
+					tags: snapshot.tags
+				};
+				lastError = /* @__PURE__ */ new Error(`Snapshot ${snapshotId} not yet visible in list`);
+			} catch (error) {
+				if (!isTransientSnapshotVisibilityError(error)) throw error;
+				lastError = error;
+			}
+			await this.sleep(SNAPSHOT_VISIBILITY_POLL_INTERVAL_MS);
+		}
+		if (fallback) return {
+			snapshotId,
+			createdAt: fallback.createdAt ?? /* @__PURE__ */ new Date(),
+			sizeBytes: fallback.sizeBytes,
+			tags: fallback.tags ?? []
+		};
+		throw lastError instanceof Error ? lastError : new TimeoutError(SNAPSHOT_VISIBILITY_TIMEOUT_MS);
+	}
+	async deleteSnapshot(snapshotId) {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/snapshots/${encodeURIComponent(snapshotId)}`, { method: "DELETE" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/**
+	* Restore from the latest snapshot in customer-provided storage.
+	* Only available when using BYOS3 (calls the runtime directly).
+	*
+	* @param storage - Customer storage config (required)
+	* @param destinationPath - Optional path to restore to
+	* @returns Snapshot info if restored, null if no snapshot found
+	*
+	* @example Restore from customer S3
+	* ```typescript
+	* const result = await box.restoreFromStorage({
+	*   type: "s3",
+	*   bucket: "my-snapshots",
+	*   credentials: { accessKeyId: "...", secretAccessKey: "..." },
+	* });
+	*
+	* if (result) {
+	*   console.log(`Restored from ${result.snapshotId}`);
+	* } else {
+	*   console.log("No snapshot found");
+	* }
+	* ```
+	*/
+	async restoreFromStorage(storage, options) {
+		if (!storage) throw new Error("Storage config is required for restoreFromStorage");
+		await this.ensureRunning();
+		const response = await this.runtimeFetch("/snapshots/restore", {
+			method: "POST",
+			body: JSON.stringify({
+				projectId: this.id,
+				storage,
+				destinationPath: options?.destinationPath,
+				snapshotId: options?.snapshotId
+			})
+		});
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		if (!data.snapshot) return null;
+		return {
+			snapshotId: data.snapshot.id,
+			createdAt: new Date(data.snapshot.createdAt),
+			sizeBytes: data.snapshot.sizeBytes,
+			tags: data.snapshot.tags ?? []
+		};
+	}
+	/**
+	* Create a CRIU checkpoint of the sandbox's memory state.
+	*
+	* Checkpoints capture the complete memory state of the running sandbox,
+	* enabling true pause/resume and fork operations. Unlike snapshots which
+	* only preserve filesystem state, checkpoints preserve process memory,
+	* open file descriptors, and execution state.
+	*
+	* **Requirements:** CRIU must be available on the host. Check availability
+	* with `client.criuStatus()` before calling.
+	*
+	* **Note:** By default, checkpoint stops the sandbox. Use `leaveRunning: true`
+	* to keep it running (creates a copy-on-write checkpoint).
+	*
+	* @param options - Checkpoint options
+	* @returns Checkpoint result with ID and metadata
+	*
+	* @example Basic checkpoint (stops sandbox)
+	* ```typescript
+	* const checkpoint = await box.checkpoint();
+	* console.log(`Checkpoint: ${checkpoint.checkpointId}`);
+	* // Sandbox is now stopped, resume with box.resume()
+	* ```
+	*
+	* @example Checkpoint without stopping
+	* ```typescript
+	* const checkpoint = await box.checkpoint({
+	*   tags: ["before-deploy"],
+	*   leaveRunning: true,
+	* });
+	* // Sandbox continues running
+	* ```
+	*/
+	async checkpoint(options) {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/checkpoints`, {
+			method: "POST",
+			body: JSON.stringify({
+				tags: options?.tags,
+				leaveRunning: options?.leaveRunning,
+				includeSnapshot: options?.includeSnapshot
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return {
+			checkpointId: data.checkpointId ?? data.id,
+			createdAt: new Date(data.createdAt ?? ""),
+			sizeBytes: data.sizeBytes,
+			tags: data.tags ?? []
+		};
+	}
+	/**
+	* List all checkpoints for this sandbox.
+	*
+	* @returns Array of checkpoint metadata
+	*
+	* @example
+	* ```typescript
+	* const checkpoints = await box.listCheckpoints();
+	* for (const cp of checkpoints) {
+	*   console.log(`${cp.checkpointId}: ${cp.createdAt}`);
+	* }
+	* ```
+	*/
+	async listCheckpoints() {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/checkpoints`);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return (Array.isArray(data) ? data : data.checkpoints ?? []).map((cp) => this.parseCheckpointInfo(cp));
+	}
+	/**
+	* Delete a checkpoint.
+	*
+	* @param checkpointId - ID of the checkpoint to delete
+	*/
+	async deleteCheckpoint(checkpointId) {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/checkpoints/${encodeURIComponent(checkpointId)}`, { method: "DELETE" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/**
+	* Fork a new sandbox from a checkpoint.
+	*
+	* Creates a new sandbox with the same memory state as this sandbox
+	* at the time of the checkpoint. The fork has a new identity but
+	* preserves the execution state.
+	*
+	* **Use cases:**
+	* - Branch workflows: Create parallel execution paths
+	* - A/B testing: Run same state with different configurations
+	* - Debugging: Fork at a specific point to investigate
+	*
+	* @param checkpointId - ID of the checkpoint to fork from
+	* @param options - Fork configuration
+	* @returns The new sandbox instance
+	*
+	* @example Basic fork
+	* ```typescript
+	* const checkpoint = await box.checkpoint({ leaveRunning: true });
+	* const forked = await box.fork(checkpoint.checkpointId);
+	* // forked has same memory state as box at checkpoint time
+	* ```
+	*
+	* @example Fork with custom config
+	* ```typescript
+	* const forked = await box.fork(checkpointId, {
+	*   name: "experiment-branch",
+	*   env: { EXPERIMENT: "true" },
+	* });
+	* ```
+	*/
+	async fork(checkpointId, options) {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/fork`, {
+			method: "POST",
+			body: JSON.stringify({
+				checkpointId,
+				name: options?.name,
+				env: options?.env,
+				resources: options?.resources,
+				metadata: options?.metadata
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		return new SandboxInstance(this.client, this.parseInfo(data.sandbox ?? data), this.defaultRuntimeBackend);
+	}
+	/**
+	* Stop the sandbox (keeps state for resume).
+	*/
+	async stop() {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/stop`, { method: "POST" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		await this.refresh();
+	}
+	/**
+	* Resume a stopped sandbox.
+	*/
+	async resume(options = {}) {
+		if (options.timeoutMs !== void 0 && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) throw new ValidationError("resume timeoutMs must be a positive number");
+		const timeoutSignal = options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : void 0;
+		const signal = timeoutSignal ? options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal : options.signal;
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/resume`, {
+			method: "POST",
+			...signal ? { signal } : {}
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		await this.refresh();
+	}
+	/**
+	* Delete the sandbox permanently.
+	*/
+	async delete() {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}`, { method: "DELETE" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/**
+	* keepAlive is intentionally unavailable until the API exposes timeout updates.
+	* @param seconds - Reserved for future support
+	*/
+	async keepAlive(_seconds = 3600) {
+		throw new Error("Sandbox keepAlive() is not supported by the current API. Set idleTimeoutSeconds when creating the sandbox instead.");
+	}
+	/**
+	* Upload a local directory to the sandbox via tar.
+	* @param localPath - Local directory path to upload
+	* @param remotePath - Destination path in the sandbox (default: /home/user)
+	*/
+	async uploadDirectory(localPath, remotePath = "/home/user") {
+		const { stat } = await import("node:fs/promises");
+		const { resolve } = await import("node:path");
+		const { spawn } = await import("node:child_process");
+		const absPath = resolve(localPath);
+		if (!(await stat(absPath).catch(() => null))?.isDirectory()) throw new Error(`Local path is not a directory: ${localPath}`);
+		if (!remotePath || remotePath.trim() === "") throw new Error("Remote path cannot be empty");
+		const tarBase64 = (await new Promise((resolveTar, rejectTar) => {
+			const tar = spawn("tar", [
+				"-cf",
+				"-",
+				"--exclude=.git",
+				"--exclude=.hg",
+				"--exclude=.svn",
+				"--exclude=node_modules",
+				"--exclude=.next",
+				"--exclude=.nuxt",
+				"--exclude=.svelte-kit",
+				"--exclude=.turbo",
+				"--exclude=.parcel-cache",
+				"--exclude=.cache",
+				"--exclude=dist",
+				"--exclude=build",
+				"--exclude=out",
+				"--exclude=coverage",
+				"--exclude=target",
+				"--exclude=__pycache__",
+				"--exclude=.venv",
+				"--exclude=venv",
+				"--exclude=.tox",
+				"--exclude=.pytest_cache",
+				"--exclude=.mypy_cache",
+				"--exclude=.ruff_cache",
+				"--exclude=*.pyc",
+				"--exclude=*.egg-info",
+				"--exclude=CMakeFiles",
+				"--exclude=cmake-build-debug",
+				"--exclude=cmake-build-release",
+				"--exclude=*.o",
+				"--exclude=*.obj",
+				"--exclude=.gradle",
+				"--exclude=*.class",
+				"--exclude=.DS_Store",
+				"-C",
+				absPath,
+				"."
+			], { stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			] });
+			const chunks = [];
+			const stderrChunks = [];
+			let totalSize = 0;
+			let settled = false;
+			const maxTarBytes = 100 * 1024 * 1024;
+			const rejectOnce = (error) => {
+				if (settled) return;
+				settled = true;
+				rejectTar(error);
+			};
+			tar.stdout.on("data", (chunk) => {
+				totalSize += chunk.length;
+				if (totalSize > maxTarBytes) {
+					tar.kill("SIGKILL");
+					rejectOnce(/* @__PURE__ */ new Error("uploadDirectory archive exceeds 100MB limit"));
+					return;
+				}
+				chunks.push(chunk);
+			});
+			tar.stderr.on("data", (chunk) => {
+				stderrChunks.push(chunk);
+			});
+			tar.on("error", (error) => {
+				rejectOnce(/* @__PURE__ */ new Error(`Failed to create tar archive: ${error.message}`));
+			});
+			tar.on("close", (code) => {
+				if (settled) return;
+				if (code !== 0) {
+					const stderr = Buffer.concat(stderrChunks).toString().trim();
+					rejectOnce(/* @__PURE__ */ new Error(`tar failed with exit code ${code}${stderr ? `: ${stderr}` : ""}`));
+					return;
+				}
+				settled = true;
+				resolveTar(Buffer.concat(chunks));
+			});
+		})).toString("base64");
+		const quotedRemotePath = quoteForShell(remotePath);
+		await this.exec(`mkdir -p ${quotedRemotePath}`);
+		await this.exec(`printf %s ${quoteForShell(tarBase64)} | base64 -d | tar -xf - -C ${quotedRemotePath}`);
+	}
+	/**
+	* Wait for the sandbox to reach a specific status.
+	*
+	* When `onProgress` is provided and the sandbox is still provisioning,
+	* uses SSE events for real-time progress instead of polling. Falls back
+	* to polling if the SSE connection fails or is unavailable.
+	*
+	* @example Basic wait
+	* ```typescript
+	* await box.waitFor("running");
+	* ```
+	*
+	* @example Wait with progress tracking
+	* ```typescript
+	* await box.waitFor("running", {
+	*   onProgress: (event) => {
+	*     console.log(`[${event.step}] ${event.status} — ${event.message}`);
+	*     if (event.percent !== undefined) {
+	*       updateProgressBar(event.percent);
+	*     }
+	*   },
+	* });
+	* ```
+	*/
+	async waitFor(status, options) {
+		const statuses = Array.isArray(status) ? status : [status];
+		const timeoutMs = options?.timeoutMs ?? 12e4;
+		const pollIntervalMs = options?.pollIntervalMs ?? 2e3;
+		if (options?.onProgress && (this.status === "provisioning" || this.status === "pending")) try {
+			await this.waitForWithSSE(statuses, timeoutMs, options.onProgress, options.signal);
+			return;
+		} catch (err) {
+			if (err instanceof StateError || err instanceof TimeoutError) throw err;
+		}
+		const startTime = Date.now();
+		while (true) {
+			if (options?.signal?.aborted) throw new TimeoutError(0, "Aborted");
+			await this.refresh();
+			if (statuses.includes(this.status)) return;
+			if (this.status === "failed") throw new StateError(this.error ?? "Sandbox failed", this.status);
+			if (Date.now() - startTime > timeoutMs) throw new TimeoutError(timeoutMs, `Timed out waiting for sandbox to reach ${statuses.join(" or ")}`);
+			await this.sleep(pollIntervalMs);
+		}
+	}
+	/**
+	* SSE-based wait implementation. Subscribes to provisioning events and
+	* delivers progress callbacks while waiting for a target status.
+	*/
+	async waitForWithSSE(statuses, timeoutMs, onProgress, signal) {
+		const abortController = new AbortController();
+		const timeout = setTimeout(() => abortController.abort(), timeoutMs);
+		if (signal) {
+			if (signal.aborted) {
+				clearTimeout(timeout);
+				throw new TimeoutError(0, "Aborted");
+			}
+			signal.addEventListener("abort", () => abortController.abort(), { once: true });
+		}
+		try {
+			for await (const event of this.events({
+				signal: abortController.signal,
+				eventTypes: [
+					"provision_progress",
+					"provision_complete",
+					"provision_failed",
+					"status_change"
+				]
+			})) if (event.type === "provision_progress") {
+				const d = event.data;
+				onProgress({
+					step: normalizeProvisionStep(d.step),
+					status: d.status,
+					message: d.message,
+					percent: d.progress,
+					detail: d.detail,
+					timestamp: d.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+				});
+			} else if (event.type === "provision_failed") {
+				await this.refresh();
+				throw new StateError(event.data.error ?? "Provisioning failed", this.status);
+			} else if (event.type === "provision_complete" || event.type === "status_change") {
+				await this.refresh();
+				if (statuses.includes(this.status)) return;
+				if (this.status === "failed") throw new StateError(this.error ?? "Sandbox failed", this.status);
+			}
+			await this.refresh();
+			if (statuses.includes(this.status)) return;
+			if (this.status === "failed") throw new StateError(this.error ?? "Sandbox failed", this.status);
+			throw new TimeoutError(timeoutMs, `SSE stream ended before sandbox reached ${statuses.join(" or ")}`);
+		} finally {
+			clearTimeout(timeout);
+			abortController.abort();
+		}
+	}
+	parseCheckpointInfo(cp) {
+		return {
+			checkpointId: cp.checkpointId ?? cp.id,
+			sandboxId: cp.sandboxId ?? cp.projectRef ?? this.id,
+			createdAt: new Date(cp.createdAt),
+			tags: cp.tags ?? [],
+			sizeBytes: cp.sizeBytes,
+			hasMemoryState: cp.hasMemoryState ?? true,
+			hasFilesystemSnapshot: cp.hasFilesystemSnapshot ?? false
+		};
+	}
+	async ensureRunning() {
+		await this.refresh();
+		if (this.status !== "running") throw new StateError(`Sandbox is not running (status: ${this.status})`, this.status, "running");
+	}
+	async runtimeFetch(path, options) {
+		const url = `/v1/sandboxes/${encodeURIComponent(this.id)}/runtime${path}`;
+		try {
+			return options ? await this.client.fetch(url, options) : await this.client.fetch(url);
+		} catch (err) {
+			throw new NetworkError(`Failed to connect to sandbox: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : void 0, {
+				endpoint: path,
+				origin: "runtime"
+			});
+		}
+	}
+	/**
+	* Delegates to the shared `parseSSEStream` in `lib/sse-parser.ts`
+	* — one canonical SSE implementation for the whole SDK. The
+	* shared parser throws `AbortError` on cancellation (so consumers
+	* can distinguish cancel from clean EOF), but agent/task streaming
+	* callers of this method historically relied on a silent-return
+	* abort: they check `options?.signal?.aborted` AFTER the loop and
+	* decide whether to reconnect. The try/catch below preserves that
+	* legacy contract by swallowing AbortError at the delegate layer.
+	*/
+	async *parseSSEStream(response, signal) {
+		if (!response.body) throw new NetworkError("No response body");
+		try {
+			for await (const event of parseSSEStream(response.body, { signal })) yield event;
+		} catch (err) {
+			if (err instanceof Error && err.name === "AbortError") return;
+			throw err;
+		}
+	}
+	/**
+	* Associate a session ID with a user ID so the Sandbox API can route
+	* subsequent WebSocket connections to this sandbox.
+	*
+	* @param opts - Session and user identifiers
+	*
+	* @example
+	* ```typescript
+	* await box.registerSessionMapping({
+	*   sessionId: "sess_abc",
+	*   userId: "user_123",
+	* });
+	* ```
+	*/
+	async registerSessionMapping(opts) {
+		const response = await this.client.fetch(`/v1/session/${encodeURIComponent(opts.sessionId)}/mapping`, {
+			method: "PUT",
+			body: JSON.stringify({
+				userId: opts.userId,
+				sandboxId: this.id
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	parseInfo(data) {
+		return {
+			id: data.id ?? this.id,
+			name: data.name,
+			status: data.status ?? "pending",
+			connection: normalizeConnection(data.connection) ?? this.info.connection,
+			metadata: data.metadata,
+			createdAt: data.createdAt ? new Date(data.createdAt) : this.info.createdAt,
+			startedAt: data.startedAt ? new Date(data.startedAt) : void 0,
+			lastActivityAt: data.lastActivityAt ? new Date(data.lastActivityAt) : void 0,
+			expiresAt: data.expiresAt ? new Date(data.expiresAt) : void 0,
+			error: data.error,
+			startupDiagnostics: normalizeStartupDiagnostics(data.startupDiagnostics) ?? this.info?.startupDiagnostics
+		};
+	}
+	sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+	/**
+	* Get a session reference bound to this sandbox. Lazy: does not hit the
+	* network until you call a method on the returned `SandboxSession`.
+	* Use {@link sessions} to discover existing session ids.
+	*/
+	session(id) {
+		return new SandboxSession(this, id);
+	}
+	/**
+	* List sessions on this sandbox, optionally filtering by status. Returns
+	* `SandboxSession` instances paired with their last-known
+	* {@link SessionInfo} so callers can avoid an extra round-trip per
+	* session for status.
+	*/
+	async sessions(opts) {
+		await this.ensureRunning();
+		const search = new URLSearchParams();
+		if (opts?.backend) search.set("backend", opts.backend);
+		const qs = search.toString();
+		const response = await this.runtimeFetch(`/agents/sessions${qs ? `?${qs}` : ""}`);
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const list = await response.json();
+		const out = [];
+		for (const raw of list) {
+			const info = normalizeSessionInfo(raw);
+			if (!info) continue;
+			if (opts?.status && info.status !== opts.status) continue;
+			out.push({
+				session: this.session(info.id),
+				info
+			});
+		}
+		return out;
+	}
+	/**
+	* Dispatch a prompt and return immediately with the session id (Issue
+	* #913 Gap 2). The sandbox keeps running the prompt after this call
+	* returns; reconnect via `box.session(id).events()` or wait for
+	* completion with `box.session(id).result()`.
+	*
+	* Idempotent on `opts.sessionId`: re-dispatching with the same id when
+	* the session is already running is a lookup, not a re-create. This
+	* lets queue retries and reconnect-after-Worker-restart be safe by
+	* construction.
+	*/
+	async dispatchPrompt(message, opts) {
+		await this.ensureRunning();
+		if (opts?.sessionId) {
+			const existing = await this._sessionStatus(opts.sessionId);
+			if (existing) return {
+				sessionId: existing.id,
+				status: existing.status,
+				alreadyExisted: true
+			};
+		}
+		const ctrl = new AbortController();
+		const stream = this.streamPrompt(message, {
+			...opts,
+			detach: true,
+			signal: ctrl.signal
+		});
+		let resolvedSessionId = opts?.sessionId;
+		try {
+			for await (const event of stream) {
+				const id = event.data?.sessionId;
+				if (typeof id === "string" && id.length > 0) {
+					resolvedSessionId = id;
+					break;
+				}
+			}
+		} finally {
+			ctrl.abort();
+		}
+		if (!resolvedSessionId) throw new ServerError("dispatchPrompt did not receive a session id from the sandbox");
+		return {
+			sessionId: resolvedSessionId,
+			status: "running",
+			alreadyExisted: false
+		};
+	}
+	/**
+	* List messages for a session, including in-flight assistant content
+	* the agent is still streaming. Each entry's `metadata` carries the
+	* durability marker — `status: "streaming" | "completed" | "interrupted"`,
+	* `completed/interrupted` booleans, and the caller-supplied `turnId`
+	* when one was set. See `SessionMessage` for the full contract.
+	*
+	* Polling this is the right way to detect "did the sidecar die mid-
+	* turn?" — a SIGKILL leaves the assistant message with `status:
+	* "streaming"` and no `completed`/`interrupted` marker; a graceful
+	* abort stamps `interrupted: true` explicitly.
+	*/
+	async messages(opts) {
+		await this.ensureRunning();
+		const params = new URLSearchParams();
+		if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+		if (opts.offset !== void 0) params.set("offset", String(opts.offset));
+		if (opts.since !== void 0) params.set("since", String(opts.since));
+		const query = params.toString() ? `?${params.toString()}` : "";
+		const response = await this.client.fetch(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages${query}`, { method: "GET" });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return (await response.json()).map((m) => ({
+			id: m.info.id,
+			role: m.info.role,
+			timestamp: m.info.timestamp,
+			parts: m.parts,
+			metadata: m.info.metadata
+		}));
+	}
+	/**
+	* Look up a cached turn result by idempotency key. Returns the cached
+	* payload if a turn with this `turnId` previously completed on the
+	* given session; returns `null` if no such turn has finished yet
+	* (either it never started, or it interrupted before completion).
+	*
+	* Call this before re-issuing a `streamPrompt` / `prompt` / `task`
+	* that you might be retrying — a non-null result means the original
+	* attempt finished and you can return that to your caller instead of
+	* running the agent a second time. Only turns that reach the
+	* `completed` terminal state are cached; interrupted turns are not.
+	*/
+	async findCompletedTurn(turnId, opts) {
+		await this.ensureRunning();
+		const response = await this.client.fetch(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/turns/${encodeURIComponent(turnId)}`, { method: "GET" });
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return await response.json();
+	}
+	/**
+	* Drive a detached turn forward by exactly one settle → poll → dispatch
+	* pass and report where it stands. Built for tick-based callers —
+	* Cloudflare Workflows steps, queue consumers, crons — that re-invoke
+	* on their own schedule instead of holding a stream open. One
+	* invocation never loops, never sleeps, and never keeps a connection
+	* alive past the pass.
+	*
+	* The pass resolves to the first of:
+	*   1. The completed-turn cache has `turnId` → `completed`, or `failed`
+	*      when the cached payload carries no text — that result is final,
+	*      so a retry cannot improve it.
+	*   2. The session is queued/running → `running`, after enforcing
+	*      `wallCapMs`: a session past the cap is cancelled and reported
+	*      `failed`.
+	*   3. The session is terminal without a cached turn → settle from the
+	*      session result; an unsuccessful result is `failed`.
+	*   4. No session exists → dispatch fire-and-detach (idempotent on
+	*      `sessionId`, exactly like `dispatchPrompt`) → `running`.
+	*
+	* `failed` is always deterministic: re-invoking with the same ids
+	* returns the same outcome rather than starting a second agent run, so
+	* callers can treat it as terminal without their own retry bookkeeping.
+	*/
+	async driveTurn(message, opts) {
+		const turnId = opts.turnId ?? opts.sessionId;
+		const turn = await this.findCompletedTurn(turnId, { sessionId: opts.sessionId });
+		if (turn) return settleTurnDrive(turn.result);
+		const info = await this._sessionStatus(opts.sessionId);
+		if (info && (info.status === "running" || info.status === "queued")) {
+			const startedAt = info.startedAt ?? info.createdAt;
+			const elapsedMs = startedAt ? Date.now() - startedAt.getTime() : void 0;
+			if (opts.wallCapMs !== void 0 && elapsedMs !== void 0 && elapsedMs > opts.wallCapMs) {
+				await this._sessionCancel(opts.sessionId);
+				return {
+					state: "failed",
+					error: `session ${opts.sessionId} exceeded the ${opts.wallCapMs}ms wall-clock cap and was cancelled`
+				};
+			}
+			return {
+				state: "running",
+				...startedAt ? { startedAt } : {},
+				...elapsedMs !== void 0 ? { elapsedMs } : {}
+			};
+		}
+		if (info) {
+			const result = await this._sessionResult(opts.sessionId);
+			if (!result.success) return {
+				state: "failed",
+				error: `session ${opts.sessionId} ${info.status}: ${result.error ?? "no error detail"}`
+			};
+			return settleTurnDrive({ ...result });
+		}
+		await this.dispatchPrompt(message, {
+			...opts,
+			turnId
+		});
+		return { state: "running" };
+	}
+	/**
+	* Mint a scoped, time-bounded JWT for direct browser access to this
+	* sandbox (Issue #913 Gap 1). Authority is the caller's
+	* `TANGLE_API_KEY` (sk-tan-*) — the Sandbox API mints the token;
+	* signing secrets stay server-side.
+	*
+	* Use this to give a browser direct read access to the sandbox without
+	* leaking the full bearer (`box.connection.authToken`). The returned
+	* token verifies against the same sidecar middleware that already
+	* gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
+	*/
+	async mintScopedToken(opts) {
+		const response = await this.client.fetch(`/v1/sandboxes/${encodeURIComponent(this.id)}/scoped-token`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				scope: opts.scope,
+				...opts.sessionId ? { sessionId: opts.sessionId } : {},
+				...opts.ttlMinutes ? { ttlMinutes: opts.ttlMinutes } : {}
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = await response.json();
+		if (typeof data.sidecarUrl !== "string" || typeof data.sidecarProxyUrl !== "string") throw new Error("Scoped token response missing runtime URLs.");
+		return {
+			token: data.token,
+			expiresAt: /* @__PURE__ */ new Date(data.expiresAt * 1e3),
+			runtimeUrl: data.sidecarUrl,
+			sidecarProxyUrl: data.sidecarProxyUrl,
+			scope: data.scope
+		};
+	}
+	/** @internal — invoked by SandboxSession.status(). */
+	async _sessionStatus(id) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}`);
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return normalizeSessionInfo(await response.json());
+	}
+	/** @internal — invoked by SandboxSession.events(). */
+	async *_sessionEvents(id, opts) {
+		await this.ensureRunning();
+		const search = new URLSearchParams();
+		search.set("sessionId", id);
+		if (opts?.since) search.set("since", opts.since);
+		const response = await this.runtimeFetch(`/agents/events/?${search.toString()}`, { signal: opts?.signal });
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		yield* this.parseSSEStream(response, opts?.signal);
+	}
+	/** @internal — invoked by SandboxSession.result(). */
+	async _sessionResult(id) {
+		const startTime = Date.now();
+		let response;
+		let runError;
+		let traceId;
+		let usage;
+		let costUsd;
+		let toolInvocations;
+		let question;
+		let terminalReached = false;
+		for await (const event of this._sessionEvents(id)) {
+			response = applySandboxEventText(response, event);
+			if (event.type === "result" || event.type === "done") {
+				const data = event.data;
+				usage = readTokenUsage(data) ?? usage;
+				costUsd = readTokenCostUsd(data) ?? costUsd;
+			}
+			if (event.type === "result") {
+				const data = event.data;
+				toolInvocations = readToolInvocations(data) ?? toolInvocations;
+			}
+			if (event.type === "interaction") question = readQuestionEvent(event.data) ?? question;
+			if (event.type === "trace.id") traceId = event.data.traceId;
+			if (event.type === "error") runError = event.data.message;
+			if (event.type === "done" || event.type === "result") {
+				terminalReached = true;
+				break;
+			}
+		}
+		const approval = detectHubApproval(toolInvocations);
+		const outcome = deriveOutcome({
+			terminalReached,
+			runError,
+			toolInvocations,
+			approval,
+			question
+		});
+		return {
+			success: outcome.success,
+			status: outcome.status,
+			response,
+			error: outcome.error,
+			toolInvocations,
+			approval,
+			question,
+			traceId,
+			durationMs: Date.now() - startTime,
+			usage,
+			costUsd
+		};
+	}
+	/**
+	* @internal — invoked by SandboxSession.cancel(). Void-returning alias of
+	* `_interrupt`: both abort the in-flight execution via `POST /{id}/abort`
+	* (the session and its messages are preserved). `cancel()` discards the
+	* `cancelled` flag; callers that need to distinguish a real interruption
+	* from a no-op should use `interrupt()`.
+	*/
+	async _sessionCancel(id) {
+		await this._interrupt(id);
+	}
+	/** @internal — invoked by InteractiveSessionHandle.start(). */
+	async _startInteractive(id, options) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive`, {
+			method: "POST",
+			body: JSON.stringify(options)
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		const data = (await response.json())?.data;
+		if (!data || typeof data.sessionId !== "string" || typeof data.streamUrl !== "string") throw new ServerError("Interactive session response missing data", 502, {
+			endpoint: `/agents/sessions/${encodeURIComponent(id)}/interactive`,
+			origin: "runtime"
+		});
+		return data;
+	}
+	/** @internal — invoked by InteractiveSessionHandle.sendPrompt(). */
+	async _sendInteractivePrompt(id, prompt) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive/prompt`, {
+			method: "POST",
+			body: JSON.stringify({ prompt })
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/** @internal — invoked by InteractiveSessionHandle.stop(). */
+	async _stopInteractive(id) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactive`, { method: "DELETE" });
+		if (!response.ok && response.status !== 404) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+	/** @internal — invoked by SandboxSession.respondToPermission(). */
+	async _respondToPermission(id, permissionID, options) {
+		await this.ensureRunning();
+		const body = options.response === "allow" ? {
+			id: permissionID,
+			outcome: "accepted",
+			data: { grant: "allow_once" }
+		} : {
+			id: permissionID,
+			outcome: "declined"
+		};
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactions`, {
+			method: "POST",
+			body: JSON.stringify(body)
+		});
+		if (!response.ok) {
+			const errBody = await response.text();
+			throw parseErrorResponse(response.status, errBody, void 0, response.headers);
+		}
+	}
+	/** @internal — invoked by SandboxSession.interrupt(). */
+	async _interrupt(id) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/abort`, { method: "POST" });
+		if (response.status === 404) return { cancelled: false };
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+		return { cancelled: (await response.json()).data?.cancelled === true };
+	}
+	/**
+	* @internal — invoked by SandboxSession.answer(). Resolves the session's
+	* outstanding question interaction and posts the answer through the
+	* interaction response route. The positional answer arrays map onto the
+	* question's `answerSpec` fields in order.
+	*/
+	async _answerQuestion(id, answers) {
+		await this.ensureRunning();
+		const listResp = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactions`, { method: "GET" });
+		if (!listResp.ok) {
+			const body = await listResp.text();
+			throw parseErrorResponse(listResp.status, body, void 0, listResp.headers);
+		}
+		const outstanding = ((await listResp.json()).data?.interactions ?? []).find((r) => r.kind === "question");
+		if (!outstanding) throw new Error("No outstanding question to answer for this session");
+		const positional = Object.values(answers);
+		const data = {};
+		outstanding.answerSpec.fields.forEach((field, index) => {
+			const raw = answers[field.name] ?? answers[String(index)] ?? positional[index] ?? [];
+			switch (field.type) {
+				case "select":
+					data[field.name] = raw;
+					break;
+				case "number":
+					data[field.name] = Number(raw[0] ?? 0);
+					break;
+				case "boolean":
+					data[field.name] = raw[0] === "true";
+					break;
+				default: data[field.name] = raw[0] ?? "";
+			}
+		});
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/interactions`, {
+			method: "POST",
+			body: JSON.stringify({
+				id: outstanding.id,
+				outcome: "accepted",
+				data
+			})
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+};
+function settleTurnDrive(result) {
+	const text = typeof result.text === "string" ? result.text : typeof result.response === "string" ? result.response : void 0;
+	const status = typeof result.status === "string" ? result.status : deriveOutcome({
+		terminalReached: true,
+		runError: typeof result.error === "string" ? result.error : void 0,
+		toolInvocations: Array.isArray(result.toolInvocations) ? result.toolInvocations : void 0
+	}).status;
+	if (status !== "success") return {
+		state: "failed",
+		error: typeof result.error === "string" && result.error.length > 0 ? result.error : `turn ${status}`
+	};
+	return {
+		state: "completed",
+		text: text ?? "",
+		result
+	};
+}
+function normalizeSessionInfo(raw) {
+	const id = raw.id;
+	if (typeof id !== "string") return null;
+	const status = raw.status || "running";
+	return {
+		id,
+		status: [
+			"queued",
+			"running",
+			"completed",
+			"failed",
+			"cancelled"
+		].includes(status) ? status : "running",
+		backend: typeof raw.backendType === "string" ? raw.backendType : typeof raw.backend === "string" ? raw.backend : void 0,
+		model: typeof raw.model === "string" ? raw.model : void 0,
+		promptCount: typeof raw.promptCount === "number" ? raw.promptCount : void 0,
+		createdAt: raw.createdAt ? new Date(raw.createdAt) : void 0,
+		startedAt: raw.startedAt ? new Date(raw.startedAt) : void 0,
+		endedAt: raw.endedAt ? new Date(raw.endedAt) : void 0,
+		raw
+	};
+}
+var DirectRuntimeHttpClient = class {
+	baseClient;
+	sandboxId;
+	getConnection;
+	onUnauthorized;
+	constructor(baseClient, sandboxId, getConnection, onUnauthorized) {
+		this.baseClient = baseClient;
+		this.sandboxId = sandboxId;
+		this.getConnection = getConnection;
+		this.onUnauthorized = onUnauthorized;
+	}
+	async fetch(path, options, fetchOptions) {
+		const runtimePrefix = `/v1/sandboxes/${encodeURIComponent(this.sandboxId)}/runtime`;
+		if (!path.startsWith(runtimePrefix)) return this.baseClient.fetch(path, options, fetchOptions);
+		const runtimePath = path.slice(runtimePrefix.length);
+		if (runtimePath === "/network" || runtimePath.startsWith("/network/") || runtimePath === "/preview-links" || runtimePath.startsWith("/preview-links/")) return this.baseClient.fetch(path, options, fetchOptions);
+		const connection = this.getConnection();
+		const runtimeUrl = connection?.runtimeUrl;
+		if (!runtimeUrl) throw new NetworkError("Sandbox has no direct runtime URL");
+		const targetUrl = `${runtimeUrl.replace(/\/$/, "")}${runtimePath}`;
+		const headers = new Headers(options?.headers);
+		if (connection?.authToken) headers.set("Authorization", `Bearer ${connection.authToken}`);
+		const isFormDataBody = typeof FormData !== "undefined" && options?.body instanceof FormData;
+		if (!headers.has("Content-Type") && !isFormDataBody) headers.set("Content-Type", "application/json");
+		const init = {
+			...options,
+			headers
+		};
+		if (options?.body && typeof options.body === "object" && !isFormDataBody) init.duplex = "half";
+		const directTimeoutMs = fetchOptions?.timeoutMs;
+		if (!init.signal && typeof directTimeoutMs === "number" && directTimeoutMs > 0) init.signal = AbortSignal.timeout(directTimeoutMs);
+		let response = await fetch(targetUrl, init);
+		if (response.status === 401 && this.onUnauthorized && !headers.has("x-no-retry")) {
+			await response.arrayBuffer().catch(() => void 0);
+			try {
+				await this.onUnauthorized();
+			} catch {
+				return new Response("", {
+					status: 401,
+					statusText: response.statusText
+				});
+			}
+			const refreshedConnection = this.getConnection();
+			if (refreshedConnection?.authToken) {
+				headers.set("Authorization", `Bearer ${refreshedConnection.authToken}`);
+				response = await fetch(targetUrl, {
+					...init,
+					headers
+				});
+			}
+		}
+		const responseHeaders = new Headers(response.headers);
+		responseHeaders.set("x-tangle-request-path", path);
+		if (options?.method) responseHeaders.set("x-tangle-request-method", options.method);
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: responseHeaders
+		});
+	}
+};
+function quoteForShell(value) {
+	if (value.includes("\0")) throw new Error("Shell argument contains NUL byte");
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+//#endregion
+export { collectAgentResponseText as a, buildTraceExportPayload as c, toOtelJson as d, encodePromptForWire as f, serializeForSidecar as h, applySandboxEventText as i, exportTraceBundle as l, normalizeRuntimeBackendConfig as m, SandboxSession as n, getSandboxEventText as o, parseSSEStream as p, InteractiveSessionHandle as r, normalizeConnection as s, SandboxInstance as t, otelTraceIdForTangleTrace as u };