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

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

@@ -1,5 +1,6 @@
-import { a as NotFoundError, d as TimeoutError, f as ValidationError, i as NetworkError, p as parseErrorResponse, t as AuthError } from "./errors-DSz87Rkk.js";
-import { d as exportTraceBundle, g as parseSSEStream, l as normalizeConnection, m as encodePromptForWire, n as normalizeStartupDiagnostics, t as SandboxInstance } from "./sandbox-Be9WAqSg.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
@@ -100,7 +101,7 @@ const DEFAULT_MACHINE_LIFETIME_SECONDS = 3600;
 const DEFAULT_MAX_CONCURRENT_CREATES = 4;
 const MAX_CONCURRENT_ARTIFACT_READS = 8;
 const DEFAULT_ARTIFACT_ROOT = "/workspace";
-const DEFAULT_MAX_ARTIFACT_BYTES = 25 * 1024 * 1024;
+const DEFAULT_MAX_ARTIFACT_BYTES = 10 * 1024 * 1024;
 const MAX_MACHINE_ID_LENGTH = 64;
 const machineIdPattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 function createFleetId() {
@@ -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
@@ -997,6 +1325,41 @@ const DEFAULT_TIMEOUT_MS = 3e4;
 */
 const DEFAULT_CREATE_TIMEOUT_MS = 12e4;
 const DEFAULT_GPU_CREATE_TIMEOUT_MS = 900 * 1e3;
+const CREATE_POST_MAX_ATTEMPTS = 5;
+const CREATE_RETRY_BASE_DELAY_MS = 250;
+const CREATE_RETRY_MAX_DELAY_MS = 4e3;
+const RETRYABLE_CREATE_STATUS_CODES = new Set([
+	408,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+function isRetryableCreateError(error) {
+	if (error instanceof NetworkError) return true;
+	return error instanceof SandboxError && error.status !== void 0 && RETRYABLE_CREATE_STATUS_CODES.has(error.status);
+}
+function createRetryDelayMs(error, failedAttempt) {
+	if (error instanceof SandboxError && error.retryAfterMs !== void 0) return error.retryAfterMs;
+	return Math.min(CREATE_RETRY_BASE_DELAY_MS * 2 ** Math.max(0, failedAttempt - 1), CREATE_RETRY_MAX_DELAY_MS);
+}
+async function waitForCreateRetry(delayMs, signal) {
+	if (signal.aborted) throw signal.reason ?? /* @__PURE__ */ new Error("Sandbox create aborted");
+	if (delayMs <= 0) return;
+	await new Promise((resolve, reject) => {
+		const timeoutId = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, delayMs);
+		const onAbort = () => {
+			clearTimeout(timeoutId);
+			reject(signal.reason ?? /* @__PURE__ */ new Error("Sandbox create aborted"));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
 /**
 * Extra grace the SDK's client-side batch deadline gets on top of
 * the server-side `timeoutMs`. The server's clock starts when the
@@ -1291,65 +1654,98 @@ 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;
+		const createRequestBody = JSON.stringify({
+			name: options?.name,
+			...resolvedEnvironment !== void 0 ? {
+				environment: resolvedEnvironment,
+				image: resolvedEnvironment
+			} : {},
+			git,
+			tools: options?.tools,
+			bare: options?.bare,
+			...options?.publicEdge === false ? { publicEdge: false } : {},
+			driver: options?.driver,
+			backend: requestBackend,
+			permissions: options?.permissions,
+			env: options?.env,
+			resources,
+			gpuLease: options?.gpuLease,
+			sshEnabled: options?.sshEnabled,
+			sshPublicKeys: options?.sshPublicKeys ?? (options?.sshPublicKey ? [options.sshPublicKey] : void 0),
+			sshKeyIds: options?.sshKeyIds,
+			webTerminalEnabled: options?.webTerminalEnabled,
+			maxLifetimeSeconds: options?.maxLifetimeSeconds,
+			idleTimeoutSeconds: options?.idleTimeoutSeconds,
+			storage: options?.storage,
+			ephemeral: options?.ephemeral,
+			fromSnapshot: options?.fromSnapshot,
+			fromSandboxId: options?.fromSandboxId,
+			templateId: options?.templateId,
+			publicTemplateId: options?.publicTemplateId,
+			publicTemplateVersionId: options?.publicTemplateVersionId,
+			secrets: options?.secrets,
+			confidential: options?.confidential,
+			metadata: options?.metadata,
+			teamId: options?.teamId,
+			capabilities: options?.capabilities,
+			privacy: options?.privacy,
+			egressPolicy: options?.egressPolicy,
+			idempotencyKey
+		});
+		const createTimeoutError = () => new TimeoutError(timeoutMs, `Sandbox create did not complete within ${timeoutMs}ms. The provision may still be running server-side; retry create() with idempotencyKey="${idempotencyKey}" to join it.`);
+		const waitBeforeRetry = async (error, failedAttempt) => {
+			try {
+				await waitForCreateRetry(createRetryDelayMs(error, failedAttempt), postSignal);
+			} catch (waitError) {
+				if (requestOptions?.signal?.aborted) throw waitError;
+				throw createTimeoutError();
+			}
+		};
 		let response;
-		try {
-			response = await this.fetch("/v1/sandboxes", {
-				method: "POST",
-				headers: { "Idempotency-Key": idempotencyKey },
-				signal: postSignal,
-				body: JSON.stringify({
-					name: options?.name,
-					...resolvedEnvironment !== void 0 ? {
-						environment: resolvedEnvironment,
-						image: resolvedEnvironment
-					} : {},
-					git,
-					tools: options?.tools,
-					bare: options?.bare,
-					...options?.publicEdge === false ? { publicEdge: false } : {},
-					driver: options?.driver,
-					backend: resolvedBackend,
-					permissions: options?.permissions,
-					env: options?.env,
-					resources,
-					gpuLease: options?.gpuLease,
-					sshEnabled: options?.sshEnabled,
-					sshPublicKeys: options?.sshPublicKeys ?? (options?.sshPublicKey ? [options.sshPublicKey] : void 0),
-					sshKeyIds: options?.sshKeyIds,
-					webTerminalEnabled: options?.webTerminalEnabled,
-					maxLifetimeSeconds: options?.maxLifetimeSeconds,
-					idleTimeoutSeconds: options?.idleTimeoutSeconds,
-					storage: options?.storage,
-					ephemeral: options?.ephemeral,
-					fromSnapshot: options?.fromSnapshot,
-					fromSandboxId: options?.fromSandboxId,
-					templateId: options?.templateId,
-					publicTemplateId: options?.publicTemplateId,
-					publicTemplateVersionId: options?.publicTemplateVersionId,
-					secrets: options?.secrets,
-					confidential: options?.confidential,
-					metadata: options?.metadata,
-					teamId: options?.teamId,
-					capabilities: options?.capabilities,
-					privacy: options?.privacy,
-					egressPolicy: options?.egressPolicy,
-					idempotencyKey
-				})
-			});
-		} catch (err) {
-			if (requestOptions?.signal?.aborted) throw err;
-			if (err instanceof TimeoutError || err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError")) throw new TimeoutError(timeoutMs, `Sandbox create did not complete within ${timeoutMs}ms. The provision may still be running server-side; retry create() with idempotencyKey="${idempotencyKey}" to join it.`);
-			throw err;
-		}
-		if (!response.ok) {
+		for (let attempt = 1; attempt <= CREATE_POST_MAX_ATTEMPTS; attempt++) {
+			try {
+				response = await this.fetch("/v1/sandboxes", {
+					method: "POST",
+					headers: { "Idempotency-Key": idempotencyKey },
+					signal: postSignal,
+					body: createRequestBody
+				});
+			} catch (error) {
+				if (requestOptions?.signal?.aborted) throw error;
+				if (postDeadline.aborted || Date.now() >= deadline || error instanceof TimeoutError || error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError")) throw createTimeoutError();
+				if (attempt >= CREATE_POST_MAX_ATTEMPTS || !isRetryableCreateError(error)) throw error;
+				await waitBeforeRetry(error, attempt);
+				continue;
+			}
+			if (response.ok) break;
 			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
+			const error = parseErrorResponse(response.status, body, void 0, response.headers);
+			if (attempt >= CREATE_POST_MAX_ATTEMPTS || !isRetryableCreateError(error)) throw error;
+			await waitBeforeRetry(error, attempt);
+			response = void 0;
 		}
+		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", {
@@ -1357,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;
 	}
 	/**
@@ -2246,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/collaboration/index.js

@@ -1,2 +1,2 @@
-import { a as CollaborationClient, i as parseCollaborationDocumentId, n as buildCollaborationDocumentId, r as normalizeCollaborationPath, t as CollaborationFileBridge } from "../collaboration-QZXrXdIb.js";
+import { a as CollaborationClient, i as parseCollaborationDocumentId, n as buildCollaborationDocumentId, r as normalizeCollaborationPath, t as CollaborationFileBridge } from "../collaboration-CcZE2xMl.js";
 export { CollaborationClient, CollaborationFileBridge, buildCollaborationDocumentId, normalizeCollaborationPath, parseCollaborationDocumentId };

package/dist/{collaboration-QZXrXdIb.js → collaboration-CcZE2xMl.js}

@@ -1,4 +1,4 @@
-import { d as TimeoutError, i as NetworkError, p as parseErrorResponse } from "./errors-DSz87Rkk.js";
+import { d as TimeoutError, i as NetworkError, p as parseErrorResponse } from "./errors-wd266B9Q.js";
 //#region src/collaboration/client.ts
 const DEFAULT_TIMEOUT_MS = 3e4;
 function normalizeBaseUrl(url) {

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { $t as NetworkConfig, Bn as SandboxClientConfig, Or as SandboxStatus, R as CreateSandboxOptions, _r as SandboxInfo, an as PreviewLinkManager, et as ExecOptions, in as PreviewLinkInfo, tt as ExecResult } from "./types-BvSoEHz8.js";
-import { n as SandboxInstance } from "./sandbox-BtNWbfd3.js";
-import { i as SandboxClient } from "./client-B8i6qrQr.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--P_nbLzM.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-DSz87Rkk.js";
-import { t as SandboxInstance } from "./sandbox-Be9WAqSg.js";
-import { n as SandboxClient } from "./client-DTpHjPjc.js";
+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-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/{errors--P_nbLzM.d.ts → errors-CNCz3Ms9.d.ts}

@@ -90,7 +90,7 @@ declare class PartialFailureError extends SandboxError {
 declare class ValidationError extends SandboxError {
   /** Field-level validation errors */
   readonly fields?: Record<string, string>;
-  constructor(message: string, fields?: Record<string, string>, metadata?: SandboxErrorMetadata);
+  constructor(message: string, fields?: Record<string, string>, metadata?: SandboxErrorMetadata, code?: string);
 }
 /**
  * The sandbox is not in a valid state for the requested operation.

package/dist/{errors-DSz87Rkk.js → errors-wd266B9Q.js}

@@ -109,8 +109,8 @@ var PartialFailureError = class extends SandboxError {
 var ValidationError = class extends SandboxError {
 	/** Field-level validation errors */
 	fields;
-	constructor(message, fields, metadata) {
-		super(message, "VALIDATION_ERROR", 400, metadata);
+	constructor(message, fields, metadata, code = "VALIDATION_ERROR") {
+		super(message, code, 400, metadata);
 		this.name = "ValidationError";
 		this.fields = fields;
 	}
@@ -255,7 +255,7 @@ function parseErrorResponse(status, body, context, headers) {
 	if (isPartialFailureCode(code)) return new PartialFailureError(message, code, status, metadata, readFailures(data, errorObj));
 	if (code === "EGRESS_PROXY_RECOVERY_REQUIRED") return new EgressProxyRecoveryError(message, metadata);
 	switch (status) {
-		case 400: return new ValidationError(message, data.fields, metadata);
+		case 400: return new ValidationError(message, data.fields, metadata, code);
 		case 401: return new AuthError(message, metadata);
 		case 404: return new NotFoundError(data.resourceType || "Resource", data.resourceId || "unknown", metadata);
 		case 408: return new TimeoutError(data.timeoutMs || 3e4, message, metadata);

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

@@ -1,5 +1,5 @@
-import { R as CreateSandboxOptions } from "./types-BvSoEHz8.js";
-import { n as SandboxInstance, t as HttpClient } from "./sandbox-BtNWbfd3.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
 /**