@tangle-network/sandbox 0.1.2 → 0.2.1

package/dist/sandbox-ksXTNlo-.js

@@ -0,0 +1,3394 @@
+import { c as ServerError, f as parseErrorResponse, l as StateError, r as NetworkError, t as AuthError, u as TimeoutError } from "./errors-CljiGR__.js";
+//#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) {
+		hashes[lane] ^= byte + lane;
+		hashes[lane] = Math.imul(hashes[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;
+	if (!runtimeUrl) return void 0;
+	return {
+		runtimeUrl,
+		authToken: c.authToken,
+		authTokenExpiresAt: c.authTokenExpiresAt,
+		ssh: normalizeSshCredentials(c.ssh),
+		webTerminalUrl: c.webTerminalUrl
+	};
+}
+/**
+* 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/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 } : {},
+		...backend?.profile !== void 0 ? { profile: backend.profile } : {},
+		...inlineProfile ? { inlineProfile } : callerInlineProfile ? { inlineProfile: callerInlineProfile } : {},
+		...backend?.model ? { model: backend.model } : options.model ? { model: parseModelString(options.model) } : {},
+		...backend?.server ? { server: backend.server } : {}
+	};
+}
+function toBackendProfile(profile) {
+	return {
+		name: profile.name,
+		model: profile.model?.default,
+		...profile.prompt?.systemPrompt ? { systemPrompt: profile.prompt.systemPrompt } : {},
+		...profile.tools && Object.keys(profile.tools).length > 0 ? { tools: profile.tools } : {},
+		...profile.prompt?.instructions?.length ? { instructions: profile.prompt.instructions } : {},
+		...profile.permissions && Object.keys(profile.permissions).length > 0 ? { permission: Object.fromEntries(Object.entries(profile.permissions).map(([key, value]) => [key === "network" ? "webfetch" : key, value])) } : {},
+		...profile.mcp ? { mcp: Object.fromEntries(Object.entries(profile.mcp).map(([name, config]) => [name, {
+			...config.transport || config.url ? { type: config.transport === "stdio" ? "local" : config.transport === "sse" ? "remote" : config.transport } : {},
+			command: config.command ?? "",
+			...config.args ? { args: config.args } : {},
+			...config.env ? { env: config.env } : {},
+			...config.cwd ? { cwd: config.cwd } : {},
+			...config.url ? { url: config.url } : {},
+			...config.headers ? { headers: config.headers } : {}
+		}])) } : {},
+		...profile.subagents ? { subagents: profile.subagents } : {},
+		...profile.resources ? { resources: profile.resources } : {},
+		...profile.hooks ? { hooks: profile.hooks } : {},
+		...profile.modes ? { modes: profile.modes } : {},
+		...profile.extensions ? { extensions: profile.extensions } : {}
+	};
+}
+//#endregion
+//#region src/session.ts
+/**
+* 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
+		});
+	}
+	/**
+	* Cancel the session. Best-effort: an in-flight LLM call may still
+	* complete one more token before the abort takes effect. Idempotent —
+	* cancelling a completed session is a no-op.
+	*/
+	async cancel() {
+		return this.box._sessionCancel(this.id);
+	}
+};
+//#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;
+}
+/**
+* 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;
+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)");
+}
+function getSandboxEventText(event) {
+	if (event.type === "result") return event.data.finalText ?? void 0;
+	if (event.type !== "message.part.updated") return;
+	const part = event.data.part;
+	if (part?.type !== "text") return;
+	return part.text ?? part.content ?? void 0;
+}
+/**
+* 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;
+	}
+	/**
+	* 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 ?? ""
+		};
+	}
+	/**
+	* 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);
+		}
+	}
+	/**
+	* 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 error;
+		let traceId;
+		let usage;
+		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
+			})) {
+				const eventText = getSandboxEventText(event);
+				if (eventText !== void 0) responseText = eventText;
+				if (event.type === "result") {
+					const tokenUsage = event.data.tokenUsage;
+					if (tokenUsage) usage = {
+						inputTokens: tokenUsage.inputTokens ?? 0,
+						outputTokens: tokenUsage.outputTokens ?? 0
+					};
+				}
+				if (event.type === "trace.id") traceId = event.data.traceId;
+				if (event.type === "error") error = event.data.message;
+			}
+			return {
+				success: !error,
+				response: responseText,
+				error,
+				traceId,
+				durationMs: Date.now() - startTime,
+				usage
+			};
+		} catch (err) {
+			return {
+				success: false,
+				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.
+	*
+	* 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) {
+		await this.ensureRunning();
+		const parts = encodePromptForWire(message);
+		const response = await this.runtimeFetch("/agents/run/stream", {
+			method: "POST",
+			signal: options?.signal,
+			headers: {
+				...options?.executionId ? { "X-Execution-ID": options.executionId } : {},
+				...options?.lastEventId ? { "Last-Event-ID": options.lastEventId } : {}
+			},
+			body: JSON.stringify({
+				identifier: "default",
+				parts,
+				sessionId: options?.sessionId,
+				metadata: options?.context,
+				backend: normalizeRuntimeBackendConfig(options?.backend ?? this.defaultRuntimeBackend, { model: options?.model })
+			})
+		});
+		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 receivedTerminal = false;
+		const MAX_RECONNECT_ATTEMPTS = 3;
+		const RECONNECT_DELAY_MS = 2e3;
+		for await (const event of this.parseSSEStream(response, options?.signal)) {
+			if (event.id) lastEventId = event.id;
+			if (event.type === "execution.started" && event.data?.executionId) executionId = event.data.executionId;
+			if (event.type === "result" || event.type === "done") receivedTerminal = true;
+			yield event;
+		}
+		if (receivedTerminal || options?.signal?.aborted) return;
+		if (!executionId) {
+			console.warn("[sandbox-sdk] Stream dropped before execution.started, cannot reconnect");
+			return;
+		}
+		for (let attempt = 1; attempt <= MAX_RECONNECT_ATTEMPTS; attempt++) {
+			if (options?.signal?.aborted) return;
+			console.warn(`[sandbox-sdk] Stream dropped without terminal event, reconnecting (attempt ${attempt}/${MAX_RECONNECT_ATTEMPTS})`);
+			await new Promise((resolve) => setTimeout(resolve, RECONNECT_DELAY_MS));
+			if (options?.signal?.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: options?.signal
+				});
+				if (!replayResponse.ok) {
+					console.warn(`[sandbox-sdk] Replay endpoint returned ${replayResponse.status}, attempt ${attempt}`);
+					continue;
+				}
+				for await (const event of this.parseSSEStream(replayResponse, options?.signal)) {
+					if (event.type === "history.replay.start" || event.type === "history.replay.end") continue;
+					if (event.id) lastEventId = event.id;
+					if (event.type === "result" || event.type === "done") receivedTerminal = true;
+					yield event;
+				}
+				if (receivedTerminal || options?.signal?.aborted) return;
+			} catch (err) {
+				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`);
+	}
+	/**
+	* 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 error;
+		let traceId;
+		let usage;
+		try {
+			for await (const event of this.streamPrompt(prompt, {
+				...options,
+				sessionId
+			})) {
+				const eventText = getSandboxEventText(event);
+				if (eventText !== void 0) responseText = eventText;
+				if (event.type === "result") {
+					const tokenUsage = event.data.tokenUsage;
+					if (tokenUsage) usage = usage ? {
+						inputTokens: usage.inputTokens + (tokenUsage.inputTokens ?? 0),
+						outputTokens: usage.outputTokens + (tokenUsage.outputTokens ?? 0)
+					} : {
+						inputTokens: tokenUsage.inputTokens ?? 0,
+						outputTokens: tokenUsage.outputTokens ?? 0
+					};
+				}
+				if (event.type === "trace.id") traceId = event.data.traceId;
+				if (event.type === "error") error = event.data.message;
+			}
+			return {
+				success: !error,
+				response: responseText,
+				error,
+				traceId,
+				durationMs: Date.now() - startTime,
+				usage,
+				turnsUsed: 1,
+				sessionId
+			};
+		} catch (err) {
+			return {
+				success: false,
+				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
+			}
+		};
+		for await (const event of this.streamPrompt(prompt, {
+			...options,
+			sessionId
+		})) yield event;
+		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
+		};
+	}
+	/**
+	* 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),
+			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") {
+				const response = await self.runtimeFetch(`/process/${pid}`, {
+					method: "DELETE",
+					body: JSON.stringify({ signal })
+				});
+				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()
+		};
+	}
+	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();
+	}
+	/**
+	* 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 prefix = Number.parseInt(ipv6Match[2], 10);
+			if (prefix >= 0 && prefix <= 128) {
+				const ipPart = ipv6Match[1];
+				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
+			})
+		});
+		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() {
+		const response = await this.client.fetch(`/v1/sandboxes/${this.id}/resume`, { method: "POST" });
+		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=node_modules",
+				"--exclude=.git",
+				"-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
+		};
+	}
+	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,
+			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
+		};
+	}
+	/**
+	* 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();
+		return {
+			token: data.token,
+			expiresAt: /* @__PURE__ */ new Date(data.expiresAt * 1e3),
+			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 error;
+		let traceId;
+		let usage;
+		for await (const event of this._sessionEvents(id)) {
+			const text = getSandboxEventText(event);
+			if (text !== void 0) response = text;
+			if (event.type === "result") {
+				const tu = event.data.tokenUsage;
+				if (tu) usage = {
+					inputTokens: tu.inputTokens ?? 0,
+					outputTokens: tu.outputTokens ?? 0
+				};
+			}
+			if (event.type === "trace.id") traceId = event.data.traceId;
+			if (event.type === "error") error = event.data.message;
+			if (event.type === "done" || event.type === "result") break;
+		}
+		return {
+			success: !error,
+			response,
+			error,
+			traceId,
+			durationMs: Date.now() - startTime,
+			usage
+		};
+	}
+	/** @internal — invoked by SandboxSession.cancel(). */
+	async _sessionCancel(id) {
+		await this.ensureRunning();
+		const response = await this.runtimeFetch(`/agents/sessions/${encodeURIComponent(id)}/abort`, { method: "POST" });
+		if (!response.ok && response.status !== 404) {
+			const body = await response.text();
+			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		}
+	}
+};
+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.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) {
+		const runtimePrefix = `/v1/sandboxes/${encodeURIComponent(this.sandboxId)}/runtime`;
+		if (!path.startsWith(runtimePrefix)) return this.baseClient.fetch(path, options);
+		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);
+		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";
+		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 { exportTraceBundle as a, encodePromptForWire as c, buildTraceExportPayload as i, parseSSEStream as l, SandboxSession as n, otelTraceIdForTangleTrace as o, normalizeConnection as r, toOtelJson as s, SandboxInstance as t };