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

package/dist/{sandbox-Be9WAqSg.js → sandbox-KiKLRbR_.js}

@@ -1,5 +1,5 @@
-import { n as normalizeSessionInfo, r as normalizeRuntimeBackendConfig, t as SandboxRuntimeApi } from "./runtime-api-CYA2DUQw.js";
-import { c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, p as parseErrorResponse, s as QuotaError, t as AuthError, u as StateError } from "./errors-DSz87Rkk.js";
+import { i as normalizeRuntimeBackendConfig, n as normalizeSessionInfo, r as uploadChunked, t as SandboxRuntimeApi } from "./runtime-api-BWq4XSrb.js";
+import { c as SandboxError, d as TimeoutError, f as ValidationError, i as NetworkError, l as ServerError, n as CapabilityError, p as parseErrorResponse, s as QuotaError, t as AuthError, u as StateError } from "./errors-wd266B9Q.js";
 import { addTokenUsage, readTokenCostUsd, readTokenUsage } from "@tangle-network/agent-core";
 //#region src/lib/sse-parser.ts
 /**
@@ -920,6 +920,22 @@ const WRITE_MANY_DEFAULT_PACE_MS = 150;
 const WRITE_MANY_DEFAULT_MAX_RETRIES = 4;
 const WRITE_MANY_RETRY_BASE_MS = 250;
 const WRITE_MANY_RETRY_MAX_MS = 2e3;
+function parseTextFileReadResponse(body) {
+	let payload;
+	try {
+		payload = JSON.parse(body);
+	} catch {
+		throw new ServerError("Runtime returned invalid JSON for file read", 502, {
+			origin: "runtime",
+			endpoint: "/files/read"
+		});
+	}
+	if (typeof payload !== "object" || payload === null || !("success" in payload) || payload.success !== true || !("data" in payload) || typeof payload.data !== "object" || payload.data === null || !("content" in payload.data) || typeof payload.data.content !== "string" || !("encoding" in payload.data) || payload.data.encoding !== "utf8") throw new ServerError("Runtime returned a malformed text file response", 502, {
+		origin: "runtime",
+		endpoint: "/files/read"
+	});
+	return payload.data.content;
+}
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Transient file-write failures worth retrying: rate-limit (quota), 5xx,
 *  transport (network), and request timeouts. A non-transient error (bad path,
@@ -1331,18 +1347,20 @@ var SandboxInstance = class SandboxInstance {
 	*/
 	async read(path, options) {
 		await this.ensureRunning();
-		const headers = {};
-		if (options?.sessionId) headers["X-Session-Id"] = options.sessionId;
+		const headers = options?.sessionId ? { "X-Session-Id": options.sessionId } : void 0;
 		const response = await this.runtimeFetch("/files/read", {
 			method: "POST",
 			headers,
-			body: JSON.stringify({ path })
+			body: JSON.stringify({
+				path,
+				encoding: "utf8"
+			})
 		});
 		if (!response.ok) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		return (await response.json()).data?.content ?? "";
+		return parseTextFileReadResponse(await response.text());
 	}
 	/**
 	* Write content to a file in the sandbox.
@@ -1393,7 +1411,10 @@ var SandboxInstance = class SandboxInstance {
 			if (started && paceMs > 0) await delay(paceMs);
 			started = true;
 			try {
-				await this.write(file.path, file.content, { mode: file.mode });
+				await this.write(file.path, file.content, {
+					mode: file.mode,
+					encoding: file.encoding
+				});
 				break;
 			} catch (err) {
 				if (isTransientWriteError(err) && attempt < maxRetries) {
@@ -1544,8 +1565,8 @@ var SandboxInstance = class SandboxInstance {
 	* `error` + `done` so callers never see a thrown generator.
 	*/
 	async *streamPromptInner(message, options) {
+		if (options?.lastEventId && !options.executionId) throw new ValidationError("lastEventId requires executionId so the SDK can replay the correct execution", { executionId: "Required when lastEventId is set" });
 		await this.ensureRunning();
-		const parts = encodePromptForWire(message);
 		const timeoutMs = typeof options?.timeoutMs === "number" && options.timeoutMs > 0 ? options.timeoutMs : void 0;
 		const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : void 0;
 		const streamSignal = timeoutSignal ? options?.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal : options?.signal;
@@ -1563,26 +1584,47 @@ var SandboxInstance = class SandboxInstance {
 				...data
 			});
 		};
+		const explicitReplay = Boolean(options?.executionId && options.lastEventId);
+		const requestEndpoint = explicitReplay ? `/agents/run/${encodeURIComponent(options?.executionId ?? "")}/events?lastEventId=${encodeURIComponent(options?.lastEventId ?? "")}&format=sse` : "/agents/run/stream";
+		let lastEventId = options?.lastEventId;
+		let executionId = options?.executionId;
+		let sessionId = options?.sessionId;
+		let receivedTerminal = false;
+		const RECONNECT_BACKOFF_MS = [
+			2e3,
+			4e3,
+			8e3,
+			16e3,
+			3e4,
+			3e4
+		];
+		const MAX_RECONNECT_ATTEMPTS = RECONNECT_BACKOFF_MS.length;
+		let lastReplayStatus;
+		let lastExecutionStatus;
+		let firstSseEventSeen = false;
 		let response;
 		try {
 			logStreamCheckpoint("runtime_post_start", {
-				endpoint: "/agents/run/stream",
+				endpoint: requestEndpoint,
 				sessionId: options?.sessionId,
 				executionId: options?.executionId,
 				hasLastEventId: Boolean(options?.lastEventId),
-				detach: options?.detach === true
+				detach: options?.detach === true,
+				replayOnly: explicitReplay
 			});
-			response = await this.runtimeFetch("/agents/run/stream", {
+			const request = explicitReplay ? {
+				method: "GET",
+				signal: streamSignal
+			} : {
 				method: "POST",
 				signal: streamSignal,
 				headers: {
 					...options?.executionId ? { "X-Execution-ID": options.executionId } : {},
-					...options?.lastEventId ? { "Last-Event-ID": options.lastEventId } : {},
 					...options?.detach ? { "x-agent-detach": "true" } : {}
 				},
 				body: JSON.stringify({
 					identifier: "default",
-					parts,
+					parts: encodePromptForWire(message),
 					sessionId: options?.sessionId,
 					turnId: options?.turnId,
 					metadata: options?.context,
@@ -1591,7 +1633,8 @@ var SandboxInstance = class SandboxInstance {
 					...options?.detach ? { detach: true } : {},
 					backend: normalizeRuntimeBackendConfig(options?.backend ?? this.defaultRuntimeBackend, { model: options?.model })
 				})
-			});
+			};
+			response = await this.runtimeFetch(requestEndpoint, request);
 			logStreamCheckpoint("runtime_response_headers", {
 				status: response.status,
 				ok: response.ok
@@ -1601,27 +1644,20 @@ var SandboxInstance = class SandboxInstance {
 			throwIfTimedOut();
 			throw err;
 		}
-		if (!response.ok) {
+		if (!response.ok && !explicitReplay) {
 			const body = await response.text();
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
-		let lastEventId = options?.lastEventId;
-		let executionId = options?.executionId;
-		let sessionId = options?.sessionId;
-		let receivedTerminal = false;
-		const RECONNECT_BACKOFF_MS = [
-			2e3,
-			4e3,
-			8e3,
-			16e3,
-			3e4,
-			3e4
-		];
-		const MAX_RECONNECT_ATTEMPTS = RECONNECT_BACKOFF_MS.length;
-		let lastReplayStatus;
-		let lastExecutionStatus;
-		let firstSseEventSeen = false;
-		for await (const event of this.parseSSEStream(response, streamSignal)) {
+		if (!response.ok) {
+			lastReplayStatus = response.status;
+			await response.text();
+			logStreamCheckpoint("replay_response_status", {
+				attempt: 0,
+				status: response.status,
+				ok: false
+			});
+		} else for await (const event of this.parseSSEStream(response, streamSignal)) {
+			if (event.type === "history.replay.start" || event.type === "history.replay.end") continue;
 			if (!firstSseEventSeen) {
 				firstSseEventSeen = true;
 				logStreamCheckpoint("first_sse_event", {
@@ -2099,11 +2135,19 @@ var SandboxInstance = class SandboxInstance {
 	async resourceUsage() {
 		await this.ensureRunning();
 		const response = await this.runtimeFetch("/health/detailed", { method: "GET" });
-		if (!response.ok) {
-			const body = await response.text();
-			throw parseErrorResponse(response.status, body, void 0, response.headers);
+		const body = await response.text();
+		let data;
+		try {
+			data = JSON.parse(body);
+		} catch (error) {
+			if (response.ok) throw new NetworkError("Detailed health returned a non-JSON response", error instanceof Error ? error : void 0, {
+				endpoint: "/health/detailed",
+				origin: "runtime"
+			});
 		}
-		return (await response.json()).resources ?? null;
+		if (data?.resources) return data.resources;
+		if (!response.ok) throw parseErrorResponse(response.status, body, void 0, response.headers);
+		return null;
 	}
 	/**
 	* Git capability object for repository operations.
@@ -2322,12 +2366,14 @@ var SandboxInstance = class SandboxInstance {
 			writeMany: (files, options) => this.writeMany(files, options),
 			search: (query, options) => this.search(query, options),
 			upload: (localPath, remotePath, options) => this.fsUpload(localPath, remotePath, options),
+			uploadData: (remotePath, data, options) => this.fsUploadData(remotePath, data, 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),
+			rename: (sourcePath, destinationPath, options) => this.fsRename(sourcePath, destinationPath, options),
 			mkdir: (path, options) => this.fsMkdir(path, options),
 			exists: (path) => this.fsExists(path)
 		};
@@ -2368,6 +2414,14 @@ var SandboxInstance = class SandboxInstance {
 			percentage: 100
 		});
 	}
+	/** See {@link FileSystem.uploadData}. Delegates to the shared, browser-safe
+	*  chunked-upload flow in `lib/chunked-upload.ts`, wired to this sandbox's
+	*  runtime endpoint (works over the gateway proxy or a direct connection —
+	*  both are transparent through `runtimeFetch`). */
+	async fsUploadData(remotePath, data, options) {
+		await this.ensureRunning();
+		return uploadChunked({ fetch: (path, init) => this.runtimeFetch(path, init) }, remotePath, data, options);
+	}
 	async fsDownload(remotePath, localPath, options) {
 		await this.ensureRunning();
 		const fs = await import("node:fs/promises");
@@ -2515,6 +2569,9 @@ var SandboxInstance = class SandboxInstance {
 			throw parseErrorResponse(response.status, body, void 0, response.headers);
 		}
 	}
+	async fsRename(sourcePath, destinationPath, options) {
+		return this.runtime.renameFile(sourcePath, destinationPath, options);
+	}
 	async fsMkdir(path, options) {
 		await this.ensureRunning();
 		const params = new URLSearchParams();
@@ -4443,15 +4500,10 @@ var SandboxInstance = class SandboxInstance {
 		return { state: "running" };
 	}
 	/**
-	* Mint a scoped, time-bounded JWT for direct browser access to this
-	* sandbox (Issue #913 Gap 1). Authority is the caller's
-	* `TANGLE_API_KEY` (sk-tan-*) — the Sandbox API mints the token;
-	* signing secrets stay server-side.
-	*
-	* Use this to give a browser direct read access to the sandbox without
-	* leaking the full bearer (`box.connection.authToken`). The returned
-	* token verifies against the same sidecar middleware that already
-	* gates ProductTokenIssuer-issued JWTs — no new sidecar surface.
+	* Mint a scoped, time-bounded JWT for browser access (Issue #913 Gap 1).
+	* Authority is the caller's `TANGLE_API_KEY` (sk-tan-*); signing secrets
+	* stay server-side. Session/project scopes work with SessionGatewayClient,
+	* while session-runtime/read-only scopes work with SandboxRuntimeClient.
 	*/
 	async mintScopedToken(opts) {
 		if ((opts.scope === "session" || opts.scope === "session-runtime") && !opts.sessionId) throw new ValidationError(`${opts.scope} scope requires a sessionId`);

package/dist/tangle/index.d.ts

@@ -1,2 +1,2 @@
-import { a as TANGLE_JOBS_CONTRACT, c as AgentSandboxBlueprintAbi, d as SandboxCreateParamTypes, f as SandboxCreateResponseParamTypes, i as TANGLE_CHAIN_ID, l as ITangleJobsAbi, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, p as SandboxIdParamTypes, r as JOB_SANDBOX_DELETE, s as TangleSandboxClientConfig, t as TangleSandboxClient, u as JsonResponseParamTypes } from "../index-BFnMEze6.js";
+import { a as TANGLE_JOBS_CONTRACT, c as AgentSandboxBlueprintAbi, d as SandboxCreateParamTypes, f as SandboxCreateResponseParamTypes, i as TANGLE_CHAIN_ID, l as ITangleJobsAbi, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, p as SandboxIdParamTypes, r as JOB_SANDBOX_DELETE, s as TangleSandboxClientConfig, t as TangleSandboxClient, u as JsonResponseParamTypes } from "../index-CEZaPvfX.js";
 export { AgentSandboxBlueprintAbi, ITangleJobsAbi, JOB_SANDBOX_CREATE, JOB_SANDBOX_DELETE, JsonResponseParamTypes, SandboxCreateParamTypes, SandboxCreateResponseParamTypes, SandboxIdParamTypes, TANGLE_CHAIN_ID, TANGLE_JOBS_CONTRACT, TANGLE_MAINNET_RPC, TangleSandboxClient, TangleSandboxClientConfig };

package/dist/tangle/index.js

@@ -1,2 +1,2 @@
-import { a as TANGLE_JOBS_CONTRACT, c as ITangleJobsAbi, d as SandboxCreateResponseParamTypes, f as SandboxIdParamTypes, i as TANGLE_CHAIN_ID, l as JsonResponseParamTypes, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, r as JOB_SANDBOX_DELETE, s as AgentSandboxBlueprintAbi, t as TangleSandboxClient, u as SandboxCreateParamTypes } from "../tangle-D6UfK_B0.js";
+import { a as TANGLE_JOBS_CONTRACT, c as ITangleJobsAbi, d as SandboxCreateResponseParamTypes, f as SandboxIdParamTypes, i as TANGLE_CHAIN_ID, l as JsonResponseParamTypes, n as JOB_SANDBOX_CREATE, o as TANGLE_MAINNET_RPC, r as JOB_SANDBOX_DELETE, s as AgentSandboxBlueprintAbi, t as TangleSandboxClient, u as SandboxCreateParamTypes } from "../tangle-Os9sH-ms.js";
 export { AgentSandboxBlueprintAbi, ITangleJobsAbi, JOB_SANDBOX_CREATE, JOB_SANDBOX_DELETE, JsonResponseParamTypes, SandboxCreateParamTypes, SandboxCreateResponseParamTypes, SandboxIdParamTypes, TANGLE_CHAIN_ID, TANGLE_JOBS_CONTRACT, TANGLE_MAINNET_RPC, TangleSandboxClient };

package/dist/{tangle-D6UfK_B0.js → tangle-Os9sH-ms.js}

@@ -1,5 +1,5 @@
-import { p as parseErrorResponse } from "./errors-DSz87Rkk.js";
-import { t as SandboxInstance } from "./sandbox-Be9WAqSg.js";
+import { p as parseErrorResponse } from "./errors-wd266B9Q.js";
+import { t as SandboxInstance } from "./sandbox-KiKLRbR_.js";
 //#region src/tangle/abi.ts
 /**
 * Tangle Contract ABI Definitions

package/dist/{types-BvSoEHz8.d.ts → types-LNLeU9Ub.d.ts}

@@ -662,6 +662,25 @@ interface CreateSandboxOptions {
    * timeout-driven retries.
    */
   idempotencyKey?: string;
+  /**
+   * Auto-split inline file mounts out of an inline `backend.profile` object
+   * at create time, send the lean profile (mount refs stripped) in the
+   * create request, then write the deferred files back once the sandbox is
+   * running.
+   *
+   * When `true` (the default), a profile with sizeable inline mounts (e.g.
+   * skills, tool scripts) does not bloat the create POST; the SDK
+   * materializes those files via {@link FileSystem.writeMany} /
+   * {@link FileSystem.uploadData} after the sandbox reaches `running`. Only
+   * applies to an inline `AgentProfile` object on `backend.profile` — a
+   * named-profile string is never split, and the deprecated untyped
+   * `backend.inlineProfile` passthrough is not split either. Set `false`
+   * to send the full profile inline in the create request (no post-create
+   * materialization step).
+   *
+   * @default true
+   */
+  autoMaterializeProfileFiles?: boolean;
 }
 /**
  * Per-call overrides for {@link SandboxClient.create}.
@@ -1254,18 +1273,19 @@ interface PromptOptions {
   /** AbortSignal for cancellation */
   signal?: AbortSignal;
   /**
-   * Stable execution id for cross-process reconnect. When passed, the same
-   * id on a retry lands on the same substrate execution — the platform
-   * replays its buffered event stream instead of spawning a duplicate run.
-   * Forwarded as the `X-Execution-ID` header. Omit to let the SDK extract
-   * one from the response stream's `execution.started` event (in-call
-   * reconnect only).
+   * Stable execution id for tracing a first dispatch or selecting an existing
+   * execution for replay. Forwarded as `X-Execution-ID` on a first dispatch.
+   * When combined with `lastEventId`, the SDK replays the existing execution
+   * without sending the prompt again. An execution ID alone does not make a
+   * repeated POST idempotent; use `turnId` for application-level retries.
+   * Omit to let the SDK read the id from `execution.started` for in-call
+   * reconnects.
    */
   executionId?: string;
   /**
-   * Last event id the caller has already acknowledged. The substrate
-   * replays strictly after this id on reconnect. Forwarded as the
-   * `Last-Event-ID` header. Omit on first attempt.
+   * Last event id the caller has already acknowledged. Requires `executionId`;
+   * the SDK replays strictly after this id without dispatching a new prompt.
+   * Omit on the first attempt.
    */
   lastEventId?: string;
   /**
@@ -1724,6 +1744,10 @@ interface SessionListOptions {
 }
 /** Options for creating a runtime agent session. */
 interface CreateSessionOptions {
+  /** Stable caller-supplied idempotency key. Repeating create with the same
+   * id returns the existing session without creating another workspace or
+   * backend session. Omit to let the runtime mint a random id. */
+  sessionId?: string;
   title?: string;
   parentId?: string;
   backend: BackendConfig;
@@ -2018,18 +2042,18 @@ type TurnDriveResult = {
   error: string;
 };
 /**
- * Scope of a `box.mintScopedToken()` request. Each value narrows the token's
- * authority compared to the full sandbox bearer. `session-runtime` permits
- * only typed message, workspace-file, and terminal operations for one session.
+ * Scope of a `box.mintScopedToken()` request. `session` and `project` mint
+ * SessionGateway read tokens. `session-runtime` and `read-only` mint sidecar
+ * capability tokens for browser-safe runtime access.
  */
 type ScopedTokenScope = "session" | "session-runtime" | "project" | "read-only";
 /**
  * Options for `box.mintScopedToken()`.
  */
 interface MintScopedTokenOptions {
-  /** Scope to mint. `session` narrows to a single session id; `project`
-   * grants read access to the whole sandbox; `read-only` is a project
-   * scope without prompt-dispatch capabilities. */
+  /** Scope to mint. `session` and `project` are for SessionGateway streams;
+   * `session-runtime` permits typed files, messages, and terminals for one
+   * session; `read-only` permits read-only runtime requests. */
   scope: ScopedTokenScope;
   /** Required when `scope` is `session` or `session-runtime`. */
   sessionId?: string;
@@ -2039,18 +2063,17 @@ interface MintScopedTokenOptions {
   ttlMinutes?: number;
 }
 /**
- * Returned by `box.mintScopedToken()`. The token verifies against the
- * same sidecar middleware that already gates ProductTokenIssuer-issued
- * JWTs — no new sidecar surface.
+ * Returned by `box.mintScopedToken()`. Use session/project tokens with
+ * `SessionGatewayClient`; use session-runtime/read-only tokens with
+ * `SandboxRuntimeClient`.
  */
 interface ScopedToken {
-  /** Bearer token (JWT). Send as `Authorization: Bearer <token>` or
-   * via the `EventSource` URL with token query param. */
+  /** Bearer token (JWT) for the consumer selected by `scope`. */
   token: string;
   /** When the token expires. */
   expiresAt: Date;
-  /** The runtime's direct edge URL. Matches `SandboxConnection.runtimeUrl`
-   *  (the SDK's canonical public name for this URL). */
+  /** The runtime's direct edge URL. Use with runtime scopes; session/project
+   * tokens instead connect to the Sandbox API's `/session` WebSocket. */
   runtimeUrl: string;
   /** Browser-safe Sandbox API proxy base for terminal and runtime requests. */
   sidecarProxyUrl: string;
@@ -2582,7 +2605,7 @@ interface SandboxFleetArtifactSpec {
    */
   path: string;
   label?: string;
-  /** Maximum allowed artifact content size in bytes. Defaults to 5 MiB. */
+  /** Maximum allowed artifact content size in bytes. Defaults to 10 MiB. */
   maxBytes?: number;
 }
 interface SandboxFleetArtifact extends SandboxFleetArtifactSpec {
@@ -4419,6 +4442,13 @@ interface FileWriteResult {
   /** Encoding echoed by runtimes that include it in write responses. */
   encoding?: "utf8" | "base64";
 }
+/** Metadata returned after a successful file or directory rename. */
+interface FileRenameResult {
+  /** Previous path, relative to the workspace when applicable. */
+  sourcePath: string;
+  /** New path, relative to the workspace when applicable. */
+  destinationPath: string;
+}
 /**
  * Options for uploading files.
  */
@@ -4441,6 +4471,36 @@ interface UploadProgress {
   /** Percentage complete (0-100) */
   percentage: number;
 }
+/**
+ * Options for {@link FileSystem.uploadData}.
+ */
+interface ChunkedUploadOptions {
+  /** Unix mode bits applied to the file after upload, e.g. 0o644. */
+  mode?: number;
+  /** Progress callback fired after each part completes. On the rare
+   *  checksum-mismatch recovery (one automatic full re-upload),
+   *  `bytesUploaded` restarts from 0 for the second pass. */
+  onProgress?: (progress: UploadProgress) => void;
+  /** Cancel the upload. A pending upload session is best-effort deleted
+   *  server-side when the signal fires mid-flow. */
+  signal?: AbortSignal;
+  /** Delay between part PUTs (ms) to pace bursts. 0 disables pacing (default). */
+  paceMs?: number;
+  /** Max retries per part on a transient error before failing loud. Default 4. */
+  maxRetries?: number;
+}
+/**
+ * Result of a successful {@link FileSystem.uploadData} call — the
+ * upload-session commit response.
+ */
+interface ChunkedUploadResult {
+  /** The path the runtime wrote the assembled payload to. */
+  path: string;
+  /** Total assembled size in bytes. */
+  size: number;
+  /** Server-computed content hash of the assembled payload. */
+  hash: string;
+}
 /**
  * Options for downloading files.
  */
@@ -4490,6 +4550,11 @@ interface DeleteOptions {
   /** Agent session whose workspace and change history receive the deletion. */
   sessionId?: string;
 }
+/** Options for {@link FileSystem.rename}. */
+interface RenameOptions {
+  /** Agent session whose workspace and change history receive the rename. */
+  sessionId?: string;
+}
 /**
  * File system operations for sandboxes. Access via `sandbox.fs`.
  *
@@ -4544,10 +4609,12 @@ interface DeleteOptions {
 interface WriteManyFile {
   /** Destination path. Relative paths resolve from the workspace root. */
   path: string;
-  /** File content (UTF-8). */
+  /** File content: UTF-8 by default, or base64 when `encoding: "base64"` (for binary payloads). */
   content: string;
   /** Unix mode bits applied after write, e.g. 0o755. */
   mode?: number;
+  /** Encoding of `content` on the wire. */
+  encoding?: "utf8" | "base64";
 }
 /** Options for {@link FileSystem.write}. */
 interface WriteFileOptions {
@@ -4638,6 +4705,35 @@ interface FileSystem {
    * ```
    */
   upload(localPath: string, remotePath: string, options?: UploadOptions): Promise<void>;
+  /**
+   * Upload in-memory binary or text data to the sandbox over the chunked
+   * upload-session protocol, without touching the local filesystem.
+   *
+   * Browser/Worker-safe (no `node:` APIs) — this is the sanctioned path for
+   * delivering payloads over ~1 MiB from a browser tab, a Worker, or any
+   * runtime without `node:fs`, where {@link FileSystem.upload}'s local-file
+   * read isn't available. Binary-safe: accepts a `Blob`, `ArrayBuffer`,
+   * `ArrayBufferView`, or UTF-8 `string`. The upload is chunked into
+   * server-sized parts transparently — callers see one call and one
+   * awaited result — and verified end-to-end with a whole-payload SHA-256
+   * at commit. Works identically whether the sandbox is reached through
+   * the gateway proxy or a direct sidecar connection.
+   *
+   * @param remotePath - Destination path in the sandbox.
+   * @param data - Payload to upload. Strings encode as UTF-8.
+   * @param options - Chunking, retry, progress, and cancellation options.
+   * @throws {SandboxError} `PAYLOAD_TOO_LARGE` immediately, before any
+   *   request, if the payload exceeds the chunked-upload session cap.
+   *
+   * @example
+   * ```typescript
+   * 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)}%`),
+   * });
+   * ```
+   */
+  uploadData(remotePath: string, data: Blob | ArrayBuffer | ArrayBufferView | string, options?: ChunkedUploadOptions): Promise<ChunkedUploadResult>;
   /**
    * Download a file from the sandbox.
    * Handles binary files correctly.
@@ -4734,6 +4830,27 @@ interface FileSystem {
    * ```
    */
   delete(path: string, options?: DeleteOptions): Promise<void>;
+  /**
+   * Rename a file or directory inside the sandbox without transferring its contents.
+   * An existing regular file or symbolic link at the destination is replaced atomically.
+   * Replacing a non-empty directory fails, as does moving across filesystems.
+   *
+   * @param sourcePath - Current path
+   * @param destinationPath - New path
+   * @param options - Session workspace options
+   * @returns The resolved source and destination paths
+   * @throws NotFoundError if the source or destination parent does not exist
+   * @throws Error if the destination is a non-empty directory or the paths span filesystems
+   *
+   * @example
+   * ```typescript
+   * await box.fs.rename(
+   *   "/workspace/assets/logo.tmp",
+   *   "/workspace/assets/logo.png",
+   * );
+   * ```
+   */
+  rename(sourcePath: string, destinationPath: string, options?: RenameOptions): Promise<FileRenameResult>;
   /**
    * Create a directory.
    *
@@ -4843,4 +4960,4 @@ interface CodeExecutionOptions {
   idempotencyKey?: string;
 }
 //#endregion
-export { EventStreamOptions as $, SandboxFleetMachine as $n, SessionMessageInputPart as $r, NetworkConfig as $t, CommitTaskSessionOptions as A, WriteFileOptions as Ai, Rollout as An, SandboxTerminalInfo as Ar, GpuLeaseCommandResult as At, CreateTaskSessionOptions as B, AgentProfilePermissionValue as Bi, SandboxClientConfig as Bn, SearchMatch as Br, IntelligenceReport as Bt, BatchTaskUsage as C, TurnDriveResult as Ci, PublishPublicTemplateVersionOptions as Cn, SandboxResourceUsage as Cr, GitBranch as Ct, CodeLanguage as D, UsageInfo as Di, ReconcileSandboxFleetsResult as Dn, SandboxRuntimeProfileList as Dr, GitStatus as Dt, CodeExecutionResult as E, UploadProgress as Ei, ReconcileSandboxFleetsOptions as En, SandboxRuntimeProfile as Er, GitDiff as Et, CreateSandboxFleetOptions as F, AgentProfileConfidential as Fi, RolloutStatus as Fn, SandboxTraceExport as Fr, GpuLeaseStatus as Ft, DownloadOptions as G, AgentProfileValidationResult as Gi, SandboxFleetArtifactSpec as Gn, SendSessionMessageRequest as Gr, JsonValue as Gt, DirectoryPermission as H, AgentProfileResourceRef as Hi, SandboxEnvironment as Hn, SecretInfo as Hr, IntelligenceReportCompareTo as Ht, CreateSandboxFleetTokenOptions as I, AgentProfileConnection as Ii, RolloutTurnPart as In, SandboxTraceOptions as Ir, GpuType as It, DriverConfig as J, defineGitHubResource as Ji, SandboxFleetDispatchResponse as Jn, SessionEventStreamOptions as Jr, ListSandboxFleetOptions as Jt, DownloadProgress as K, AgentSubagentProfile as Ki, SandboxFleetCostEstimate as Kn, SentSessionMessage as Kr, ListMessagesOptions as Kt, CreateSandboxFleetWithCoordinatorOptions as L, AgentProfileFileMount as Li, RunCodeOptions as Ln, SandboxUser as Lr, HostAgentDriverConfig as Lt, CreateGpuLeaseOptions as M, WriteManyOptions as Mi, RolloutOptions as Mn, SandboxTerminalRequestOptions as Mr, GpuLeaseExecResult as Mt, CreateIntelligenceReportOptions as N, AgentProfile as Ni, RolloutScorer as Nn, SandboxTraceBundle as Nr, GpuLeaseManager as Nt, CodeResult as O, WaitForOptions as Oi, RestoreSnapshotOptions as On, SandboxStatus as Or, GpuLease as Ot, CreateRequestOptions as P, AgentProfileCapabilities as Pi, RolloutStartResult as Pn, SandboxTraceEvent as Pr, GpuLeaseProviderName as Pt, EgressPolicy as Q, SandboxFleetIntelligenceEnvelope as Qn, SessionMessage as Qr, MkdirOptions as Qt, CreateSandboxOptions as R, AgentProfileMcpServer as Ri, SSHCommandDescriptor as Rn, ScopedToken as Rr, HostAgentRuntimeBackend as Rt, BatchTaskResult as S, ToolsConfig as Si, PublishPublicTemplateOptions as Sn, SandboxProfileSummary as Sr, GitAuth as St, CodeExecutionOptions as T, UploadOptions as Ti, ReapExpiredSandboxFleetsResult as Tn, SandboxRuntimeHealth as Tr, GitConfig as Tt, DispatchPromptOptions as U, AgentProfileResources as Ui, SandboxEvent as Un, SecretsManager as Ur, IntelligenceReportSubjectType as Ut, DeleteOptions as V, AgentProfilePrompt as Vi, SandboxConnection as Vn, SearchOptions as Vr, IntelligenceReportBudget as Vt, DispatchedSession as W, AgentProfileValidationIssue as Wi, SandboxFleetArtifact as Wn, SendSessionMessageOptions as Wr, IntelligenceReportWindow as Wt, DriverType as X, mergeAgentProfiles as Xi, SandboxFleetDriverTimings as Xn, SessionInfo as Xr, McpServerConfig as Xt, DriverInfo as Y, defineInlineResource as Yi, SandboxFleetDriverCapability as Yn, SessionForkOptions as Yr, ListSandboxOptions as Yt, EgressManager as Z, SandboxFleetInfo as Zn, SessionListOptions as Zr, MintScopedTokenOptions as Zt, BatchResult as _, TeeAttestationReport as _i, ProvisionResult as _n, SandboxInfo as _r, FleetExecDispatchResult as _t, AttachSandboxFleetMachineOptions as a, StartupDiagnostics as ai, PreviewLinkManager as an, SandboxFleetOperationsSummary as ar, FileReadError as at, BatchSidecarGroup as b, TeePublicKeyResponse as bi, PublicTemplateInfo as bn, SandboxPortBinding as br, FleetPromptDispatchResult as bt, BackendInfo as c, SubscriptionInfo as ci, ProcessLogEntry as cn, SandboxFleetTraceBundle as cr, FileTreeFile as ct, BackendType as d, TaskSessionChanges as di, ProcessSpawnOptions as dn, SandboxFleetTraceOptions as dr, FileWriteResult as dt, SessionStatus as ei, NetworkManager as en, SandboxFleetMachineMeteredUsage as er, ExecOptions as et, BatchBackend as f, TaskSessionCommitResult as fi, ProcessStatus as fn, SandboxFleetUsage as fr, FleetDispatchCancelResult as ft, BatchOptions as g, TeeAttestationOptions as gi, ProvisionEvent as gn, SandboxFleetWorkspaceSnapshotResult as gr, FleetExecDispatchOptions as gt, BatchEventDataMap as h, TaskSessionProfile as hi, PromptResult as hn, SandboxFleetWorkspaceRestoreResult as hr, FleetDispatchStreamOptions as ht, AttachGpuLeaseOptions as i, SshKeysManager as ii, PreviewLinkInfo as in, SandboxFleetManifestMachine as ir, FileReadBatchResult as it, CompletedTurnResult as j, WriteManyFile as ji, RolloutChildResult as jn, SandboxTerminalManager as jr, GpuLeaseExecOptions as jt, CodeResultPart as k, WaitForRolloutOptions as ki, ResumeOptions as kn, SandboxTerminalCreateOptions as kr, GpuLeaseBilling as kt, BackendManager as l, TaskOptions as li, ProcessManager as ln, SandboxFleetTraceEvent as lr, FileTreeOptions as lt, BatchEvent as m, TaskSessionInfo as mi, PromptOptions as mn, SandboxFleetWorkspaceReconcileResult as mr, FleetDispatchResultBufferOptions as mt, AccessPolicyRule as n, SnapshotOptions as ni, PermissionLevel as nn, SandboxFleetMachineSpec as nr, FileInfo as nt, BackendCapabilities as o, StartupOperation as oi, Process as on, SandboxFleetPolicy as or, FileReadResult as ot, BatchBackendStats as p, TaskSessionFileChange as pi, PromptInputPart as pn, SandboxFleetWorkspace as pr, FleetDispatchResultBuffer as pt, DriveTurnOptions as q, defineAgentProfile as qi, SandboxFleetDispatchFailureClass as qn, SessionBackendCredentials as qr, ListOptions as qt, AddUserOptions as r, SnapshotResult as ri, PermissionsManager as rn, SandboxFleetManifest as rr, FileReadBatchOptions as rt, BackendConfig as s, StorageConfig as si, ProcessInfo as sn, SandboxFleetToken as sr, FileSystem as st, AcceleratorKind as t, SnapshotInfo as ti, NonHostAgentDriverConfig as tn, SandboxFleetMachineRecord as tr, ExecResult as tt, BackendStatus as u, TaskResult as ui, ProcessSignal as un, SandboxFleetTraceExport as ur, FileTreeResult as ut, BatchRunOptions as v, TeeAttestationResponse as vi, ProvisionStatus as vn, SandboxIntelligenceEnvelope as vr, FleetMachineId as vt, BranchOptions as w, UpdateUserOptions as wi, ReapExpiredSandboxFleetsOptions as wn, SandboxResources as wr, GitCommit as wt, BatchTask as x, TokenRefreshHandler as xi, PublicTemplateVersionInfo as xn, SandboxPortPreviewLink as xr, GPU_LEASE_PROVIDER_NAMES as xt, BatchRunRequest as y, TeePublicKey as yi, ProvisionStep as yn, SandboxPermissionsConfig as yr, FleetPromptDispatchOptions as yt, CreateSessionOptions as z, AgentProfileModelHints as zi, SSHCredentials as zn, ScopedTokenScope as zr, InstalledTool as zt };
+export { EgressManager as $, defineInlineResource as $i, SandboxFleetDriverCapability as $n, SessionForkOptions as $r, McpServerConfig as $t, CodeResult as A, UploadProgress as Ai, ReconcileSandboxFleetsResult as An, SandboxRuntimeProfile as Ar, GitStatus as At, CreateSandboxOptions as B, AgentProfileConnection as Bi, RolloutTurnPart as Bn, SandboxTraceOptions as Br, HostAgentDriverConfig as Bt, BatchTaskUsage as C, TeePublicKey as Ci, PublicTemplateInfo as Cn, SandboxPermissionsConfig as Cr, FleetPromptDispatchResult as Ct, CodeExecutionOptions as D, TurnDriveResult as Di, ReapExpiredSandboxFleetsOptions as Dn, SandboxResourceUsage as Dr, GitCommit as Dt, ChunkedUploadResult as E, ToolsConfig as Ei, PublishPublicTemplateVersionOptions as En, SandboxProfileSummary as Er, GitBranch as Et, CreateIntelligenceReportOptions as F, WriteManyFile as Fi, RolloutChildResult as Fn, SandboxTerminalManager as Fr, GpuLeaseExecResult as Ft, DispatchPromptOptions as G, AgentProfilePrompt as Gi, SandboxConnection as Gn, SearchOptions as Gr, IntelligenceReportCompareTo as Gt, CreateTaskSessionOptions as H, AgentProfileMcpServer as Hi, SSHCommandDescriptor as Hn, ScopedToken as Hr, InstalledTool as Ht, CreateRequestOptions as I, WriteManyOptions as Ii, RolloutOptions as In, SandboxTerminalRequestOptions as Ir, GpuLeaseManager as It, DownloadProgress as J, AgentProfileValidationIssue as Ji, SandboxFleetArtifact as Jn, SendSessionMessageOptions as Jr, JsonValue as Jt, DispatchedSession as K, AgentProfileResourceRef as Ki, SandboxEnvironment as Kn, SecretInfo as Kr, IntelligenceReportSubjectType as Kt, CreateSandboxFleetOptions as L, AgentProfile as Li, RolloutScorer as Ln, SandboxTraceBundle as Lr, GpuLeaseProviderName as Lt, CommitTaskSessionOptions as M, WaitForOptions as Mi, RestoreSnapshotOptions as Mn, SandboxStatus as Mr, GpuLeaseBilling as Mt, CompletedTurnResult as N, WaitForRolloutOptions as Ni, ResumeOptions as Nn, SandboxTerminalCreateOptions as Nr, GpuLeaseCommandResult as Nt, CodeExecutionResult as O, UpdateUserOptions as Oi, ReapExpiredSandboxFleetsResult as On, SandboxResources as Or, GitConfig as Ot, CreateGpuLeaseOptions as P, WriteFileOptions as Pi, Rollout as Pn, SandboxTerminalInfo as Pr, GpuLeaseExecOptions as Pt, DriverType as Q, defineGitHubResource as Qi, SandboxFleetDispatchResponse as Qn, SessionEventStreamOptions as Qr, ListSandboxOptions as Qt, CreateSandboxFleetTokenOptions as R, AgentProfileCapabilities as Ri, RolloutStartResult as Rn, SandboxTraceEvent as Rr, GpuLeaseStatus as Rt, BatchTaskResult as S, TeeAttestationResponse as Si, ProvisionStep as Sn, SandboxIntelligenceEnvelope as Sr, FleetPromptDispatchOptions as St, ChunkedUploadOptions as T, TokenRefreshHandler as Ti, PublishPublicTemplateOptions as Tn, SandboxPortPreviewLink as Tr, GitAuth as Tt, DeleteOptions as U, AgentProfileModelHints as Ui, SSHCredentials as Un, ScopedTokenScope as Ur, IntelligenceReport as Ut, CreateSessionOptions as V, AgentProfileFileMount as Vi, RunCodeOptions as Vn, SandboxUser as Vr, HostAgentRuntimeBackend as Vt, DirectoryPermission as W, AgentProfilePermissionValue as Wi, SandboxClientConfig as Wn, SearchMatch as Wr, IntelligenceReportBudget as Wt, DriverConfig as X, AgentSubagentProfile as Xi, SandboxFleetCostEstimate as Xn, SentSessionMessage as Xr, ListOptions as Xt, DriveTurnOptions as Y, AgentProfileValidationResult as Yi, SandboxFleetArtifactSpec as Yn, SendSessionMessageRequest as Yr, ListMessagesOptions as Yt, DriverInfo as Z, defineAgentProfile as Zi, SandboxFleetDispatchFailureClass as Zn, SessionBackendCredentials as Zr, ListSandboxFleetOptions as Zt, BatchResult as _, TaskSessionFileChange as _i, PromptOptions as _n, SandboxFleetWorkspace as _r, FleetDispatchResultBufferOptions as _t, AttachSandboxFleetMachineOptions as a, SnapshotInfo as ai, PermissionLevel as an, SandboxFleetMachineRecord as ar, FileReadBatchOptions as at, BatchSidecarGroup as b, TeeAttestationOptions as bi, ProvisionResult as bn, SandboxFleetWorkspaceSnapshotResult as br, FleetExecDispatchResult as bt, BackendInfo as c, SshKeysManager as ci, PreviewLinkManager as cn, SandboxFleetManifestMachine as cr, FileReadResult as ct, BackendType as d, StorageConfig as di, ProcessLogEntry as dn, SandboxFleetToken as dr, FileTreeFile as dt, mergeAgentProfiles as ea, SessionInfo as ei, MintScopedTokenOptions as en, SandboxFleetDriverTimings as er, EgressPolicy as et, BatchBackend as f, SubscriptionInfo as fi, ProcessManager as fn, SandboxFleetTraceBundle as fr, FileTreeOptions as ft, BatchOptions as g, TaskSessionCommitResult as gi, PromptInputPart as gn, SandboxFleetUsage as gr, FleetDispatchResultBuffer as gt, BatchEventDataMap as h, TaskSessionChanges as hi, ProcessStatus as hn, SandboxFleetTraceOptions as hr, FleetDispatchCancelResult as ht, AttachGpuLeaseOptions as i, SessionStatus as ii, NonHostAgentDriverConfig as in, SandboxFleetMachineMeteredUsage as ir, FileInfo as it, CodeResultPart as j, UsageInfo as ji, RenameOptions as jn, SandboxRuntimeProfileList as jr, GpuLease as jt, CodeLanguage as k, UploadOptions as ki, ReconcileSandboxFleetsOptions as kn, SandboxRuntimeHealth as kr, GitDiff as kt, BackendManager as l, StartupDiagnostics as li, Process as ln, SandboxFleetOperationsSummary as lr, FileRenameResult as lt, BatchEvent as m, TaskResult as mi, ProcessSpawnOptions as mn, SandboxFleetTraceExport as mr, FileWriteResult as mt, AccessPolicyRule as n, SessionMessage as ni, NetworkConfig as nn, SandboxFleetIntelligenceEnvelope as nr, ExecOptions as nt, BackendCapabilities as o, SnapshotOptions as oi, PermissionsManager as on, SandboxFleetMachineSpec as or, FileReadBatchResult as ot, BatchBackendStats as p, TaskOptions as pi, ProcessSignal as pn, SandboxFleetTraceEvent as pr, FileTreeResult as pt, DownloadOptions as q, AgentProfileResources as qi, SandboxEvent as qn, SecretsManager as qr, IntelligenceReportWindow as qt, AddUserOptions as r, SessionMessageInputPart as ri, NetworkManager as rn, SandboxFleetMachine as rr, ExecResult as rt, BackendConfig as s, SnapshotResult as si, PreviewLinkInfo as sn, SandboxFleetManifest as sr, FileReadError as st, AcceleratorKind as t, SessionListOptions as ti, MkdirOptions as tn, SandboxFleetInfo as tr, EventStreamOptions as tt, BackendStatus as u, StartupOperation as ui, ProcessInfo as un, SandboxFleetPolicy as ur, FileSystem as ut, BatchRunOptions as v, TaskSessionInfo as vi, PromptResult as vn, SandboxFleetWorkspaceReconcileResult as vr, FleetDispatchStreamOptions as vt, BranchOptions as w, TeePublicKeyResponse as wi, PublicTemplateVersionInfo as wn, SandboxPortBinding as wr, GPU_LEASE_PROVIDER_NAMES as wt, BatchTask as x, TeeAttestationReport as xi, ProvisionStatus as xn, SandboxInfo as xr, FleetMachineId as xt, BatchRunRequest as y, TaskSessionProfile as yi, ProvisionEvent as yn, SandboxFleetWorkspaceRestoreResult as yr, FleetExecDispatchOptions as yt, CreateSandboxFleetWithCoordinatorOptions as z, AgentProfileConfidential as zi, RolloutStatus as zn, SandboxTraceExport as zr, GpuType as zt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox",
-  "version": "0.10.4",
+  "version": "0.10.5-develop.20260715115519.fee3d86",
   "description": "Client SDK for the Tangle Sandbox platform - build AI agent applications with dev containers",
   "type": "module",
   "main": "./dist/index.js",
@@ -88,7 +88,8 @@
   },
   "dependencies": {
     "@tangle-network/agent-core": "^0.4.0",
-    "@tangle-network/agent-interface": "^0.21.0"
+    "@tangle-network/agent-interface": "^0.21.0",
+    "@tangle-network/runtime-contracts": "0.1.0"
   },
   "peerDependencies": {
     "@mastra/core": "^1.36.0",