@tangle-network/sandbox 0.10.5-develop.20260713235503.8f2cefc → 0.10.5-develop.20260715115519.fee3d86

package/README.md

@@ -222,6 +222,38 @@ A gateway crash before acknowledgement redelivers the same event IDs, which the
 See `examples/cf-worker-chat.ts`, `examples/browser-streaming-resume.ts`, and
 `examples/reconnect-from-last-event-id.ts` for end-to-end patterns.
 
+### Browser-safe scoped runtime client
+
+`@tangle-network/sandbox/runtime` is a browser- and Worker-safe entry point
+(no `node:` imports) for talking directly to one sandbox's runtime with a
+short-lived scoped token — never the account-level Sandbox API key — minted
+server-side via `box.mintScopedToken({ scope: "session-runtime", sessionId })`
+or `box.mintScopedToken({ scope: "read-only" })`.
+
+```typescript
+import { createSandboxRuntimeClient } from "@tangle-network/sandbox/runtime";
+
+const runtime = createSandboxRuntimeClient({
+  baseUrl: scopedToken.sidecarProxyUrl, // browser-safe proxy base from box.mintScopedToken()
+  token: scopedToken.token,
+});
+
+await runtime.writeFile("/workspace/notes.md", "# from the browser");
+
+// Binary-safe, chunked upload for payloads over ~1 MiB — same engine and
+// size contract as SandboxInstance.fs.uploadData, wired to the scoped token
+const blob = await fileInput.files[0].arrayBuffer();
+await runtime.uploadData("/workspace/uploads/file.bin", blob, {
+  onProgress: (p) => console.log(`${p.percentage.toFixed(1)}%`),
+});
+```
+
+Every method on the scoped client — `writeFile`, `readFiles`, `uploadData`,
+terminals, sessions — carries the same `Authorization: Bearer <token>` header
+and base URL prefix, so the request conventions match whether the token
+scope allows the call or not; a denied call fails with the typed
+`SandboxError`, not a silent no-op.
+
 ## Features
 
 - **Sandbox Management** - Create, list, stop, resume, and delete sandboxes
@@ -727,6 +759,70 @@ for await (const event of box.events({ signal: controller.signal })) {
 }
 ```
 
+### File I/O
+
+| Method | Environment | Payload | Notes |
+|---|---|---|---|
+| `fs.read(path)` / `fs.write(path, content, options?)` | Node + browser | UTF-8 string, or base64 via `options.encoding` | Single request — see the size contract below for the cap |
+| `fs.writeMany(files, options?)` | Node + browser | Same as `write`; per-file `encoding` | Paced, retry-aware batch through `fs.write`'s endpoint; fails loud on the first file that can't be written |
+| `fs.upload(localPath, remotePath, options?)` | Node only | Local file path | Reads the local file with `node:fs`; not available in a browser tab |
+| `fs.uploadData(remotePath, data, options?)` | Node + browser | `Blob \| ArrayBuffer \| ArrayBufferView \| string` | Browser/Worker-safe, binary-safe — the sanctioned path for payloads over ~1 MiB (see below) |
+| `fs.download(remotePath, localPath, options?)` | Node only | — | Writes to a local path with `node:fs` |
+| `fs.uploadDir` / `fs.downloadDir` | Node only | Local directory path | tar-based directory transfer |
+| `fs.list` / `fs.stat` / `fs.mkdir` / `fs.delete` / `fs.rename` / `fs.exists` | Node + browser | — | Directory listing and file metadata operations |
+
+```typescript
+// Text write/read (UTF-8 by default)
+await box.fs.write("/workspace/config.json", JSON.stringify(config));
+const raw = await box.fs.read("/workspace/config.json");
+
+// Base64 for binary content through the same single-shot endpoint
+await box.fs.write("/workspace/icon.png", base64Png, { encoding: "base64" });
+
+// Batch-write many small files (paced, retried)
+await box.fs.writeMany([
+  { path: "skills/review.md", content: reviewSkill },
+  { path: "assets/logo.png", content: base64Logo, encoding: "base64" },
+]);
+
+// Node-only: upload a local file
+await box.fs.upload("./model.bin", "/workspace/models/model.bin");
+
+// Browser/Worker-safe: upload in-memory data over ~1 MiB (e.g. an
+// <input type="file"> Blob) — chunked and verified end-to-end
+const blob = await fetch("https://example.com/model.bin").then((r) => r.blob());
+await box.fs.uploadData("/workspace/models/model.bin", blob, {
+  onProgress: (p) => console.log(`${p.percentage.toFixed(1)}%`),
+});
+
+await box.fs.download("/workspace/results.zip", "./results.zip");
+```
+
+`fs.uploadData` is the sanctioned path once a payload clears the single-shot
+write cap: it splits the payload into server-sized parts against a chunked
+upload-session and verifies the whole payload with a SHA-256 at commit, so
+it's safe for arbitrarily-shaped binary content (video, model weights,
+archives) up to the session cap. It works identically whether the sandbox is
+reached through the gateway proxy or a direct sidecar connection
+(`box.direct()`).
+
+#### File size contract
+
+| Surface | Cap | Constant | Failure |
+|---|---|---|---|
+| Single-shot decoded write (`fs.write`, `fs.writeMany`) | 5 MiB | `FILE_DECODED_WRITE_MAX_BYTES` | `FILE_TOO_LARGE` |
+| Gateway proxy request (wire, any route) | 1 MiB | `SANDBOX_PROXY_REQUEST_MAX_BYTES` | `PAYLOAD_TOO_LARGE` |
+| Direct-runtime write request (wire, `box.direct()` only) | 32 MiB | `SANDBOX_DIRECT_FILE_REQUEST_MAX_BYTES` | `PAYLOAD_TOO_LARGE` |
+| Multipart upload (`fs.upload`) | 5 MiB | `FILE_MULTIPART_UPLOAD_MAX_BYTES` | `FILE_TOO_LARGE` |
+| Chunked upload part (`fs.uploadData`, internal) | 768 KiB | `FILE_UPLOAD_PART_MAX_BYTES` | — (server-sized, transparent to callers) |
+| Chunked upload session (`fs.uploadData`) | 64 MiB | `FILE_UPLOAD_SESSION_MAX_BYTES` | `PAYLOAD_TOO_LARGE` |
+
+All constants are exported from `@tangle-network/runtime-contracts`. Use
+`fs.uploadData` for anything above the single-shot caps. `PAYLOAD_TOO_LARGE`
+means split the delivery (use `fs.uploadData` instead of one request);
+`FILE_TOO_LARGE` means the content itself exceeds what that surface accepts,
+no matter how it's delivered.
+
 ### Snapshots
 
 #### `box.snapshot(options?)`

package/dist/agent/index.d.ts

@@ -1,6 +1,6 @@
-import { D as CodeLanguage, E as CodeExecutionResult, T as CodeExecutionOptions, k as CodeResultPart } from "../types-yNRVRww-.js";
-import { n as SandboxInstance } from "../sandbox-BvNEOnIl.js";
-import { i as SandboxClient } from "../client-C-4NcZoa.js";
+import { D as CodeExecutionOptions, O as CodeExecutionResult, j as CodeResultPart, k as CodeLanguage } from "../types-LNLeU9Ub.js";
+import { n as SandboxInstance } from "../sandbox-B9P4tyt4.js";
+import { i as SandboxClient } from "../client-CSaBJ8wD.js";
 import * as _$_modelcontextprotocol_sdk_server_index_js0 from "@modelcontextprotocol/sdk/server/index.js";
 
 //#region src/agent/tools/_specs.d.ts

package/dist/{client-C-4NcZoa.d.ts → client-CSaBJ8wD.d.ts}

@@ -1,5 +1,5 @@
-import { $n as SandboxFleetInfo, Ci as TokenRefreshHandler, Cn as PublishPublicTemplateOptions, Dn as ReconcileSandboxFleetsOptions, En as ReapExpiredSandboxFleetsResult, F as CreateSandboxFleetOptions, Gr as SecretsManager, Gt as IntelligenceReportWindow, Hn as SandboxClientConfig, Ht as IntelligenceReportBudget, I as CreateSandboxFleetTokenOptions, Jn as SandboxFleetCostEstimate, Kn as SandboxFleetArtifact, L as CreateSandboxFleetWithCoordinatorOptions, N as CreateIntelligenceReportOptions, On as ReconcileSandboxFleetsResult, P as CreateRequestOptions, R as CreateSandboxOptions, Sn as PublicTemplateVersionInfo, Tn as ReapExpiredSandboxFleetsOptions, Ut as IntelligenceReportCompareTo, Vt as IntelligenceReport, Wn as SandboxEnvironment, Xn as SandboxFleetDispatchResponse, Xt as ListSandboxOptions, Yt as ListSandboxFleetOptions, Zn as SandboxFleetDriverCapability, _ as BatchResult, _r as SandboxFleetWorkspaceRestoreResult, _t as FleetExecDispatchOptions, a as AttachSandboxFleetMachineOptions, ar as SandboxFleetManifest, bt as FleetPromptDispatchOptions, et as ExecOptions, g as BatchOptions, gn as PromptResult, gr as SandboxFleetWorkspaceReconcileResult, gt as FleetDispatchStreamOptions, hn as PromptOptions, ht as FleetDispatchResultBufferOptions, ki as UsageInfo, lr as SandboxFleetToken, m as BatchEvent, mn as PromptInputPart, mr as SandboxFleetUsage, mt as FleetDispatchResultBuffer, oi as SshKeysManager, pr as SandboxFleetTraceOptions, pt as FleetDispatchCancelResult, qn as SandboxFleetArtifactSpec, rr as SandboxFleetMachineRecord, sr as SandboxFleetOperationsSummary, tt as ExecResult, ui as SubscriptionInfo, ur as SandboxFleetTraceBundle, v as BatchRunOptions, vr as SandboxFleetWorkspaceSnapshotResult, vt as FleetExecDispatchResult, wn as PublishPublicTemplateVersionOptions, wr as SandboxProfileSummary, x as BatchTask, xn as PublicTemplateInfo, xt as FleetPromptDispatchResult, y as BatchRunRequest, yr as SandboxInfo, yt as FleetMachineId } from "./types-yNRVRww-.js";
-import { a as TraceExportSink, i as TraceExportResult, n as SandboxInstance, t as HttpClient } from "./sandbox-BvNEOnIl.js";
+import { $n as SandboxFleetDriverCapability, An as ReconcileSandboxFleetsResult, B as CreateSandboxOptions, Cn as PublicTemplateInfo, Ct as FleetPromptDispatchResult, Dn as ReapExpiredSandboxFleetsOptions, En as PublishPublicTemplateVersionOptions, Er as SandboxProfileSummary, F as CreateIntelligenceReportOptions, Gt as IntelligenceReportCompareTo, I as CreateRequestOptions, Jn as SandboxFleetArtifact, Kn as SandboxEnvironment, L as CreateSandboxFleetOptions, On as ReapExpiredSandboxFleetsResult, Qn as SandboxFleetDispatchResponse, Qt as ListSandboxOptions, R as CreateSandboxFleetTokenOptions, St as FleetPromptDispatchOptions, Ti as TokenRefreshHandler, Tn as PublishPublicTemplateOptions, Ut as IntelligenceReport, Wn as SandboxClientConfig, Wt as IntelligenceReportBudget, Xn as SandboxFleetCostEstimate, Yn as SandboxFleetArtifactSpec, Zt as ListSandboxFleetOptions, _ as BatchResult, _n as PromptOptions, _t as FleetDispatchResultBufferOptions, a as AttachSandboxFleetMachineOptions, ar as SandboxFleetMachineRecord, br as SandboxFleetWorkspaceSnapshotResult, bt as FleetExecDispatchResult, ci as SshKeysManager, dr as SandboxFleetToken, fi as SubscriptionInfo, fr as SandboxFleetTraceBundle, g as BatchOptions, gn as PromptInputPart, gr as SandboxFleetUsage, gt as FleetDispatchResultBuffer, hr as SandboxFleetTraceOptions, ht as FleetDispatchCancelResult, ji as UsageInfo, kn as ReconcileSandboxFleetsOptions, lr as SandboxFleetOperationsSummary, m as BatchEvent, nt as ExecOptions, qr as SecretsManager, qt as IntelligenceReportWindow, rt as ExecResult, sr as SandboxFleetManifest, tr as SandboxFleetInfo, v as BatchRunOptions, vn as PromptResult, vr as SandboxFleetWorkspaceReconcileResult, vt as FleetDispatchStreamOptions, wn as PublicTemplateVersionInfo, x as BatchTask, xr as SandboxInfo, xt as FleetMachineId, y as BatchRunRequest, yr as SandboxFleetWorkspaceRestoreResult, yt as FleetExecDispatchOptions, z as CreateSandboxFleetWithCoordinatorOptions } from "./types-LNLeU9Ub.js";
+import { a as TraceExportSink, i as TraceExportResult, n as SandboxInstance, t as HttpClient } from "./sandbox-B9P4tyt4.js";
 
 //#region src/lib/sse-parser.d.ts
 /**

package/dist/{client-CL_cbjU4.js → client-_OBj4sNO.js}

@@ -1,5 +1,6 @@
-import { a as NotFoundError, c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, p as parseErrorResponse, t as AuthError } from "./errors-wd266B9Q.js";
-import { d as exportTraceBundle, g as parseSSEStream, l as normalizeConnection, m as encodePromptForWire, n as normalizeStartupDiagnostics, t as SandboxInstance } from "./sandbox-CIHssZCH.js";
+import { a as NotFoundError, c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, o as PartialFailureError, p as parseErrorResponse, t as AuthError } from "./errors-wd266B9Q.js";
+import { d as exportTraceBundle, g as parseSSEStream, h as encodeTextForWire, l as normalizeConnection, m as encodePromptForWire, n as normalizeStartupDiagnostics, t as SandboxInstance } from "./sandbox-KiKLRbR_.js";
+import { FILE_DECODED_WRITE_MAX_BYTES, SANDBOX_PROXY_REQUEST_MAX_BYTES } from "@tangle-network/runtime-contracts";
 //#region src/resources.ts
 /**
 * Compute tiers, ordered smallest → largest. Defined HERE (not imported from
@@ -946,6 +947,338 @@ function getMachineRole(info) {
 	return value === "coordinator" || value === "worker" ? value : void 0;
 }
 //#endregion
+//#region src/profile-file-mounts.ts
+const PROFILE_FILE_MOUNT_B64_CHUNK_CHARS = 3e3;
+const PROFILE_FILE_MOUNT_MAX_RETRIES = 4;
+const PROFILE_FILE_MOUNT_RETRY_BASE_MS = 250;
+const PROFILE_FILE_MOUNT_RETRY_MAX_MS = 2e3;
+const PROFILE_FILE_MOUNT_EXEC_TIMEOUT_MS = 3e4;
+const PROFILE_FILE_MOUNT_PACE_MS = 150;
+const PROFILE_BIN_DIR_RE = /(^|\/)(s?bin)\//;
+/**
+* Wire budget for a single-shot `POST /files/write` of a mount.
+* Materialization runs over whatever connection the box has — on the
+* default create() path that is the GATEWAY, whose wire cap
+* ({@link SANDBOX_PROXY_REQUEST_MAX_BYTES}, 1 MiB) binds long before the
+* sidecar's 5 MiB decoded cap. The routing decision measures the ACTUAL
+* serialized content (JSON escaping inflates unevenly — a NUL byte
+* becomes the six characters `\u0000`, a backslash doubles — so no fixed
+* inflation factor is safe), leaving headroom for the request envelope
+* (path up to 4 KiB, mode, encoding, braces). Anything that doesn't fit
+* rides chunked upload, whose parts are sized for the gateway.
+*/
+const PROFILE_FILE_WRITE_WIRE_BUDGET_BYTES = SANDBOX_PROXY_REQUEST_MAX_BYTES - 8 * 1024;
+function fitsSingleShotWrite(content, contentBytes) {
+	if (contentBytes > FILE_DECODED_WRITE_MAX_BYTES) return false;
+	if (contentBytes * 6 <= PROFILE_FILE_WRITE_WIRE_BUDGET_BYTES) return true;
+	return new TextEncoder().encode(JSON.stringify(content)).byteLength <= PROFILE_FILE_WRITE_WIRE_BUDGET_BYTES;
+}
+const DEFAULT_PROFILE_FILE_API_ABSOLUTE_PREFIXES = [
+	["/home", "agent"].join("/"),
+	["/home", "user"].join("/"),
+	"/tmp",
+	"/output"
+];
+function inlineContent(mount) {
+	const resource = mount.resource;
+	if (resource.kind !== "inline") throw new Error(`materializeProfileFileMounts: ${mount.path} requires an inline resource`);
+	if (typeof resource.content !== "string") throw new Error(`materializeProfileFileMounts: ${mount.path} inline resource requires string content`);
+	return resource.content;
+}
+/**
+* Synchronous pre-flight validation of deferred inline mounts: the same
+* content/path rules {@link materializeProfileFileMounts} enforces, runnable
+* BEFORE a sandbox is provisioned. create() calls this ahead of its POST so
+* client-detectable bad input (traversal paths, control characters,
+* non-string content) fails without paying for a sandbox that would only be
+* orphaned by the post-provision throw.
+*/
+function validateDeferredProfileFileMounts(files) {
+	for (const mount of files) {
+		inlineContent(mount);
+		validateProfileFilePath(mount.path);
+	}
+}
+function splitInlineProfileFileMounts(profile) {
+	const files = profile.resources?.files ?? [];
+	const deferredFiles = [];
+	const keptFiles = [];
+	for (const mount of files) if (mount.resource.kind === "inline") deferredFiles.push(mount);
+	else keptFiles.push(mount);
+	if (deferredFiles.length === 0) return {
+		leanProfile: profile,
+		deferredFiles
+	};
+	return {
+		leanProfile: {
+			...profile,
+			resources: {
+				...profile.resources ?? {},
+				files: keptFiles
+			}
+		},
+		deferredFiles
+	};
+}
+function shellSingleQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function shellPath(path) {
+	if (path === "~") return "\"$HOME\"";
+	if (path.startsWith("~/")) {
+		const rest = path.slice(2);
+		return rest ? `"$HOME"/${shellSingleQuote(rest)}` : "\"$HOME\"";
+	}
+	return shellSingleQuote(path);
+}
+function validateProfileFilePath(path) {
+	if (!path) throw new Error("materializeProfileFileMounts: file path is required");
+	if (path.endsWith("/")) throw new Error(`materializeProfileFileMounts: refusing directory-shaped file path ${path}`);
+	if (hasControlCharacter(path)) throw new Error(`materializeProfileFileMounts: refusing unsafe file path ${JSON.stringify(path)}`);
+	if (path === "~" || /^~[^/]/.test(path)) throw new Error(`materializeProfileFileMounts: refusing unsupported home path ${path}`);
+	if (hasUnsafeFileApiSegment(path)) throw new Error(`materializeProfileFileMounts: refusing unsafe file path ${path}`);
+}
+function hasUnsafeFileApiSegment(path) {
+	return path.split("/").some((segment) => segment === "." || segment === ".." || segment === ".sidecar");
+}
+function hasControlCharacter(value) {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code < 32 || code === 127) return true;
+	}
+	return false;
+}
+function normalizeAbsolutePrefixes(prefixes) {
+	return prefixes.map((prefix) => {
+		const normalized = prefix.trim().replace(/\/+$/, "");
+		if (!normalized.startsWith("/") || hasControlCharacter(normalized)) throw new Error(`materializeProfileFileMounts: fileApiAbsolutePrefixes must contain absolute paths; received ${JSON.stringify(prefix)}`);
+		if (hasUnsafeFileApiSegment(normalized)) throw new Error(`materializeProfileFileMounts: fileApiAbsolutePrefixes contains unsafe path ${JSON.stringify(prefix)}`);
+		return normalized;
+	});
+}
+function isAllowedAbsoluteFileApiPath(path, prefixes) {
+	for (const prefix of prefixes) if (path === prefix || path.startsWith(`${prefix}/`)) return true;
+	return false;
+}
+function fileApiTarget(mount, absolutePrefixes) {
+	if (mount.path.startsWith("~/")) return null;
+	if (mount.path.startsWith("/")) return isAllowedAbsoluteFileApiPath(mount.path, absolutePrefixes) ? mount.path : null;
+	if (mount.path.startsWith("~")) return null;
+	if (mount.path.length === 0) return null;
+	return mount.path;
+}
+function isExecutableProfileFile(mount) {
+	return mount.executable ?? PROFILE_BIN_DIR_RE.test(mount.path);
+}
+function profileFileMode(mount) {
+	return isExecutableProfileFile(mount) ? 493 : void 0;
+}
+function fileApiSupportsMode(box) {
+	return box.fs?.supportsWriteMode === true;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var ProfileFileMountExecTimeoutError = class extends Error {
+	constructor(timeoutMs) {
+		super(`exec exceeded ${timeoutMs}ms`);
+		this.name = "ProfileFileMountExecTimeoutError";
+	}
+};
+function execWithTimeout(box, cmd, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			reject(new ProfileFileMountExecTimeoutError(timeoutMs));
+		}, timeoutMs);
+		box.exec(cmd, { timeoutMs }).then((res) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(res);
+		}, (err) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+const TRANSIENT_EXEC_STATUS_CODES = new Set([
+	408,
+	409,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const TRANSIENT_EXEC_CODE_RE = /^(ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|ECONNABORTED)$/i;
+const TRANSIENT_EXEC_MESSAGE_RE = /\b(408|409|425|429|500|502|503|504)\b|rate.?limit|too many requests|\bfetch failed\b|network error|connection reset|socket hang up|timed? out|service unavailable|bad gateway|gateway timeout|internal server error|\b(?:sidecar|runtime|exec(?:ution)?|terminal|sandbox|service|command(?:s)?|proxy)\b.{0,80}\bnot ready\b|\bnot ready\b.{0,80}\b(?:sidecar|runtime|exec(?:ution)?|terminal|sandbox|service|command(?:s)?|proxy)\b/i;
+function errorStatus(err) {
+	const rawStatus = err.status ?? err.statusCode ?? (err.response && typeof err.response === "object" ? err.response.status : void 0);
+	if (typeof rawStatus === "number") return rawStatus;
+	if (typeof rawStatus === "string" && /^\d+$/.test(rawStatus)) return Number(rawStatus);
+}
+function retryAfterMs(err, seen = /* @__PURE__ */ new Set()) {
+	if (!err || typeof err !== "object") return void 0;
+	if (seen.has(err)) return void 0;
+	seen.add(err);
+	const e = err;
+	if (typeof e.retryAfterMs === "number") return e.retryAfterMs;
+	return retryAfterMs(e.cause, seen);
+}
+function isTransientExecError(err, seen = /* @__PURE__ */ new Set()) {
+	if (!err || typeof err !== "object") return false;
+	if (seen.has(err)) return false;
+	seen.add(err);
+	const e = err;
+	const status = errorStatus(e);
+	if (status !== void 0 && TRANSIENT_EXEC_STATUS_CODES.has(status)) return true;
+	if (typeof e.code === "string") {
+		if (TRANSIENT_EXEC_CODE_RE.test(e.code)) return true;
+		if (/rate.?limit|too.?many.?requests|429|server.?error|service.?unavailable/i.test(e.code)) return true;
+	}
+	if (typeof e.message === "string" && TRANSIENT_EXEC_MESSAGE_RE.test(e.message)) return true;
+	return isTransientExecError(e.cause, seen);
+}
+function transientExecError(err) {
+	if (err instanceof ProfileFileMountExecTimeoutError) return { retryable: false };
+	if (isTransientExecError(err)) return {
+		retryable: true,
+		retryAfterMs: retryAfterMs(err)
+	};
+	return { retryable: false };
+}
+async function sha256Hex(content) {
+	const bytes = new TextEncoder().encode(content);
+	const webSubtle = globalThis.crypto?.subtle;
+	if (webSubtle) {
+		const digest = await webSubtle.digest("SHA-256", bytes);
+		return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+	}
+	const { createHash } = await import("node:crypto");
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+async function execProfileFileMount(box, mount, content, options, execState) {
+	const maxRetries = options.maxRetries ?? PROFILE_FILE_MOUNT_MAX_RETRIES;
+	const path = mount.path;
+	const b64 = encodeTextForWire(content);
+	const b64Chunks = [];
+	for (let i = 0; i < b64.length; i += PROFILE_FILE_MOUNT_B64_CHUNK_CHARS) b64Chunks.push(b64.slice(i, i + PROFILE_FILE_MOUNT_B64_CHUNK_CHARS));
+	const expectedSha256 = await sha256Hex(content);
+	const dir = path.replace(/\/[^/]*$/, "");
+	const executable = isExecutableProfileFile(mount);
+	const q = shellPath(path);
+	const qb64 = shellPath(`${path}.b64`);
+	const qtmp = shellPath(`${path}.tmp`);
+	const qpartPrefix = shellPath(`${path}.b64.part.`);
+	const homeGuard = path.startsWith("~/") ? `[ -n "$HOME" ] || { echo ${shellSingleQuote(`materializeProfileFileMounts: HOME is unset for ${path}`)} >&2; exit 1; }; ` : "";
+	const run = async (cmd) => {
+		for (let attempt = 0;; attempt++) {
+			if (execState.started && options.paceMs > 0) await sleep(options.paceMs);
+			execState.started = true;
+			try {
+				return await execWithTimeout(box, cmd, options.execTimeoutMs);
+			} catch (err) {
+				const { retryable, retryAfterMs: retryAfter } = transientExecError(err);
+				if (retryable && attempt < maxRetries) {
+					const backoff = Math.min(PROFILE_FILE_MOUNT_RETRY_BASE_MS * 2 ** attempt, PROFILE_FILE_MOUNT_RETRY_MAX_MS);
+					await sleep(Math.min(retryAfter ?? backoff, PROFILE_FILE_MOUNT_RETRY_MAX_MS));
+					continue;
+				}
+				throw new Error(`materializeProfileFileMounts: exec failed for ${path}`, { cause: err });
+			}
+		}
+	};
+	const step = async (cmd) => {
+		const result = await run(`${homeGuard}${cmd}`);
+		if (result.exitCode !== 0) throw new Error(`materializeProfileFileMounts: failed to write ${path} (exit ${result.exitCode}): ${result.stderr.slice(0, 500)}`);
+	};
+	await step(dir ? `mkdir -p ${shellPath(dir)}` : ":");
+	for (let i = 0; i < b64Chunks.length; i++) {
+		const slice = b64Chunks[i];
+		if (slice === void 0) continue;
+		await step(`printf '%s' '${slice}' > ${shellPath(`${path}.b64.part.${i}`)}`);
+	}
+	const chmod = executable ? `chmod +x ${q} || exit 1; ` : "";
+	const checksumMismatch = shellSingleQuote(`materializeProfileFileMounts: checksum mismatch for ${path}`);
+	await step(`cleanup() { ${`rm -f ${qb64} ${qtmp}; i=0; while [ "$i" -lt ${b64Chunks.length} ]; do rm -f ${qpartPrefix}$i; i=$((i+1)); done`}; }; trap cleanup EXIT; expected='${expectedSha256}'; if [ -f ${q} ] && [ "$(sha256sum ${q} | awk '{print $1}')" = "$expected" ]; then ${chmod}exit 0; fi; : > ${qb64} && i=0; while [ "$i" -lt ${b64Chunks.length} ]; do cat ${qpartPrefix}$i >> ${qb64} || exit 1; i=$((i+1)); done && base64 -d ${qb64} > ${qtmp} && [ "$(sha256sum ${qtmp} | awk '{print $1}')" = "$expected" ] || { echo ${checksumMismatch} >&2; exit 1; }; mv ${qtmp} ${q} && ${executable ? `chmod +x ${q} && ` : ""}[ "$(sha256sum ${q} | awk '{print $1}')" = "$expected" ] || { echo ${checksumMismatch} >&2; exit 1; }`);
+}
+async function materializeProfileFileMounts(box, files, options = {}) {
+	const execTimeoutMs = options.execTimeoutMs ?? PROFILE_FILE_MOUNT_EXEC_TIMEOUT_MS;
+	const paceMs = options.paceMs ?? PROFILE_FILE_MOUNT_PACE_MS;
+	const maxRetries = options.maxRetries ?? PROFILE_FILE_MOUNT_MAX_RETRIES;
+	const absolutePrefixes = normalizeAbsolutePrefixes(options.fileApiAbsolutePrefixes ?? DEFAULT_PROFILE_FILE_API_ABSOLUTE_PREFIXES);
+	const fs = box.fs;
+	const fileApiAvailable = typeof fs?.writeMany === "function";
+	const modeAwareFileApi = fileApiSupportsMode(box);
+	const uploadDataFn = fs?.uploadData;
+	const viaFileApi = [];
+	const viaExec = [];
+	const viaUpload = [];
+	for (const mount of files) {
+		const content = inlineContent(mount);
+		validateProfileFilePath(mount.path);
+		const target = fileApiAvailable ? fileApiTarget(mount, absolutePrefixes) : null;
+		const executable = isExecutableProfileFile(mount);
+		if (target !== null && (!executable || modeAwareFileApi)) {
+			const mode = profileFileMode(mount);
+			const contentBytes = new TextEncoder().encode(content).byteLength;
+			if (!fitsSingleShotWrite(content, contentBytes)) {
+				if (typeof uploadDataFn !== "function") throw new Error(`materializeProfileFileMounts: ${mount.path} (${contentBytes} bytes decoded) does not fit a gateway-safe single-shot write once JSON-serialized, and the box does not expose fs.uploadData for chunked delivery`);
+				viaUpload.push({
+					path: target,
+					content,
+					...mode !== void 0 ? { mode } : {}
+				});
+				continue;
+			}
+			viaFileApi.push({
+				path: target,
+				content,
+				...mode !== void 0 ? { mode } : {}
+			});
+		} else viaExec.push({
+			mount,
+			content
+		});
+	}
+	if (viaFileApi.length > 0) try {
+		await fs?.writeMany(viaFileApi, {
+			paceMs,
+			maxRetries
+		});
+	} catch (err) {
+		throw new Error("materializeProfileFileMounts: file API batch write failed", { cause: err });
+	}
+	if (viaUpload.length > 0) {
+		if (typeof uploadDataFn !== "function") throw new Error("materializeProfileFileMounts: viaUpload entries exist but fs.uploadData is unavailable");
+		for (const item of viaUpload) try {
+			await uploadDataFn(item.path, item.content, {
+				...item.mode !== void 0 ? { mode: item.mode } : {},
+				paceMs,
+				maxRetries
+			});
+		} catch (err) {
+			throw new Error(`materializeProfileFileMounts: uploadData failed for ${item.path}`, { cause: err });
+		}
+	}
+	const execState = { started: false };
+	for (const item of viaExec) await execProfileFileMount(box, item.mount, item.content, {
+		execTimeoutMs,
+		paceMs,
+		maxRetries
+	}, execState);
+	return {
+		written: viaFileApi.length + viaExec.length + viaUpload.length,
+		viaFileApi: viaFileApi.length,
+		viaExec: viaExec.length,
+		viaUpload: viaUpload.length
+	};
+}
+//#endregion
 //#region src/session-events.ts
 async function broadcastSessionEvent(client, sessionId, event) {
 	if (!sessionId.trim()) throw new ValidationError("Session ID is required");
@@ -980,11 +1313,6 @@ async function broadcastSessionAgentEvent(client, sessionId, event) {
 }
 //#endregion
 //#region src/client.ts
-/**
-* Sandbox Client
-*
-* Main client class for interacting with the Sandbox API.
-*/
 const DEFAULT_TIMEOUT_MS = 3e4;
 /**
 * Default time budget for `create()` — the full create-and-reach-running
@@ -1326,6 +1654,22 @@ var SandboxClient = class {
 			...backend,
 			type: backend.type ?? "opencode"
 		} : void 0;
+		const autoMaterializeProfileFiles = options?.autoMaterializeProfileFiles ?? true;
+		let deferredProfileFiles = [];
+		let profileFilesFailOnError = true;
+		let requestBackend = resolvedBackend;
+		if (autoMaterializeProfileFiles && resolvedBackend?.profile && typeof resolvedBackend.profile === "object") {
+			const split = splitInlineProfileFileMounts(resolvedBackend.profile);
+			deferredProfileFiles = split.deferredFiles;
+			if (deferredProfileFiles.length > 0) {
+				requestBackend = {
+					...resolvedBackend,
+					profile: split.leanProfile
+				};
+				profileFilesFailOnError = resolvedBackend.profile.resources?.failOnError !== false;
+				if (profileFilesFailOnError) validateDeferredProfileFileMounts(deferredProfileFiles);
+			}
+		}
 		const resources = normalizeSandboxResources(options?.resources, options?.driver);
 		const postDeadline = AbortSignal.timeout(timeoutMs);
 		const postSignal = requestOptions?.signal ? AbortSignal.any([requestOptions.signal, postDeadline]) : postDeadline;
@@ -1340,7 +1684,7 @@ var SandboxClient = class {
 			bare: options?.bare,
 			...options?.publicEdge === false ? { publicEdge: false } : {},
 			driver: options?.driver,
-			backend: resolvedBackend,
+			backend: requestBackend,
 			permissions: options?.permissions,
 			env: options?.env,
 			resources,
@@ -1401,7 +1745,7 @@ var SandboxClient = class {
 		}
 		if (!response) throw createTimeoutError();
 		const data = await response.json();
-		const instance = new SandboxInstance(this, this.parseInfo(data), resolvedBackend);
+		const instance = new SandboxInstance(this, this.parseInfo(data), requestBackend);
 		if (instance.status === "provisioning" || instance.status === "pending") {
 			const remainingMs = Math.max(0, deadline - Date.now());
 			await instance.waitFor("running", {
@@ -1409,6 +1753,28 @@ var SandboxClient = class {
 				signal: requestOptions?.signal
 			});
 		}
+		if (deferredProfileFiles.length > 0) {
+			if (instance.status !== "running") {
+				const paths = deferredProfileFiles.map((file) => file.path);
+				const message = `Sandbox ${instance.id} reached status "${instance.status}" before its ${deferredProfileFiles.length} deferred inline profile file mount(s) [${paths.join(", ")}] could be materialized. The sandbox was NOT deleted — inspect it, or recreate with autoMaterializeProfileFiles: false.`;
+				if (!profileFilesFailOnError) {
+					console.warn(`[sandbox.create] ${message}`);
+					return instance;
+				}
+				throw new PartialFailureError(message, "PROFILE_FILES_MATERIALIZE_FAILED", 502, void 0, paths.map((path) => ({ path })));
+			}
+			try {
+				await materializeProfileFileMounts(instance, deferredProfileFiles);
+			} catch (err) {
+				const paths = deferredProfileFiles.map((file) => file.path);
+				const message = `Sandbox ${instance.id} is RUNNING but INCOMPLETELY PROVISIONED: materialization of its ${deferredProfileFiles.length} deferred inline profile file mount(s) failed partway; some or all of [${paths.join(", ")}] may be missing in the sandbox. The sandbox was NOT deleted — inspect it, retry writing the files yourself, or delete it once you've recovered what you need. Cause: ${err instanceof Error ? err.message : String(err)}`;
+				if (!profileFilesFailOnError) {
+					console.warn(`[sandbox.create] ${message}`);
+					return instance;
+				}
+				throw new PartialFailureError(message, "PROFILE_FILES_MATERIALIZE_FAILED", 502, void 0, paths.map((path) => ({ path })));
+			}
+		}
 		return instance;
 	}
 	/**
@@ -2298,4 +2664,4 @@ var TeamsClient = class {
 	}
 };
 //#endregion
-export { DEFAULT_SANDBOX_SIZE as a, resolveSandboxResources as c, SandboxFleetClient as i, sandboxResourcesForSize as l, SandboxClient as n, SANDBOX_SIZE_PRESETS as o, SandboxFleet as r, SANDBOX_SIZE_PRESET_NAMES as s, IntelligenceClient as t };
+export { validateDeferredProfileFileMounts as a, DEFAULT_SANDBOX_SIZE as c, resolveSandboxResources as d, sandboxResourcesForSize as f, splitInlineProfileFileMounts as i, SANDBOX_SIZE_PRESETS as l, SandboxClient as n, SandboxFleet as o, materializeProfileFileMounts as r, SandboxFleetClient as s, IntelligenceClient as t, SANDBOX_SIZE_PRESET_NAMES as u };

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { Ar as SandboxStatus, Hn as SandboxClientConfig, R as CreateSandboxOptions, an as PreviewLinkInfo, en as NetworkConfig, et as ExecOptions, on as PreviewLinkManager, tt as ExecResult, yr as SandboxInfo } from "./types-yNRVRww-.js";
-import { n as SandboxInstance } from "./sandbox-BvNEOnIl.js";
-import { i as SandboxClient } from "./client-C-4NcZoa.js";
+import { B as CreateSandboxOptions, Mr as SandboxStatus, Wn as SandboxClientConfig, cn as PreviewLinkManager, nn as NetworkConfig, nt as ExecOptions, rt as ExecResult, sn as PreviewLinkInfo, xr as SandboxInfo } from "./types-LNLeU9Ub.js";
+import { n as SandboxInstance } from "./sandbox-B9P4tyt4.js";
+import { i as SandboxClient } from "./client-CSaBJ8wD.js";
 import { a as NotFoundError, c as SandboxError, d as ServerError, f as StateError, i as NetworkError, l as SandboxErrorJson, m as ValidationError, n as CapabilityError, o as PartialFailureError, p as TimeoutError, s as QuotaError, t as AuthError, u as SandboxFailureDetail } from "./errors-CNCz3Ms9.js";
 export { AuthError, CapabilityError, type CreateSandboxOptions, type ExecOptions, type ExecResult, type NetworkConfig, NetworkError, NotFoundError, PartialFailureError, type PreviewLinkInfo, type PreviewLinkManager, QuotaError, SandboxClient as Sandbox, SandboxClient, type SandboxClientConfig, SandboxError, type SandboxErrorJson, type SandboxFailureDetail, type SandboxInfo, SandboxInstance, type SandboxStatus, ServerError, StateError, TimeoutError, ValidationError };

package/dist/core.js

@@ -1,4 +1,4 @@
 import { a as NotFoundError, c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, o as PartialFailureError, s as QuotaError, t as AuthError, u as StateError } from "./errors-wd266B9Q.js";
-import { t as SandboxInstance } from "./sandbox-CIHssZCH.js";
-import { n as SandboxClient } from "./client-CL_cbjU4.js";
+import { t as SandboxInstance } from "./sandbox-KiKLRbR_.js";
+import { n as SandboxClient } from "./client-_OBj4sNO.js";
 export { AuthError, CapabilityError, NetworkError, NotFoundError, PartialFailureError, QuotaError, SandboxClient as Sandbox, SandboxClient, SandboxError, SandboxInstance, ServerError, StateError, TimeoutError, ValidationError };

package/dist/{index-DFJiN98I.d.ts → index-CEZaPvfX.d.ts}

@@ -1,5 +1,5 @@
-import { R as CreateSandboxOptions } from "./types-yNRVRww-.js";
-import { n as SandboxInstance, t as HttpClient } from "./sandbox-BvNEOnIl.js";
+import { B as CreateSandboxOptions } from "./types-LNLeU9Ub.js";
+import { n as SandboxInstance, t as HttpClient } from "./sandbox-B9P4tyt4.js";
 
 //#region src/tangle/abi.d.ts
 /**