@cloudflare/sandbox 1.0.0 → 1.0.2

package/README.md

@@ -62,17 +62,17 @@ The image needs the helper that `Files` runs, and the Worker needs `nodejs_compa
 
 ## What you can build
 
-| Goal                                   | Guide                                                                                                                              | Example                                                                                                  |
-| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Run a script and read its output       | [Execute commands](https://developers.cloudflare.com/containers/guides/execute-commands/)                                          | [`workspace`](examples/workspace)                                                                        |
-| Keep a server or build running         | [Run background processes](https://developers.cloudflare.com/sandbox/commands/run-background-processes/)                           | [`process-workspace`](examples/process-workspace)                                                        |
-| Open a shell in the browser            | [Open a terminal in the browser](https://developers.cloudflare.com/sandbox/commands/open-a-terminal-in-the-browser/)               | [`terminal-workspace`](examples/terminal-workspace)                                                      |
-| Process files from a bucket            | [Mount an R2 bucket](https://developers.cloudflare.com/sandbox/files/mount-an-r2-bucket/)                                          | [`artifact-workspace`](examples/artifact-workspace)                                                      |
-| Save a workspace and resume it later   | [Save and restore a sandbox](https://developers.cloudflare.com/sandbox/files/save-and-restore-a-workspace/)                        | [`checkpoint-workspace`](examples/checkpoint-workspace), [`backup-workspace`](examples/backup-workspace) |
-| Preview a web app while you edit it    | [Preview a web application](https://developers.cloudflare.com/sandbox/previews/)                                                   | [`preview-workspace`](examples/preview-workspace)                                                        |
-| Share a port on its own URL            | [Serve previews on their own hostnames](https://developers.cloudflare.com/sandbox/previews/serve-previews-on-their-own-hostnames/) | [`share-workspace`](examples/share-workspace)                                                            |
-| Choose which hosts a sandbox can reach | [Control network access](https://developers.cloudflare.com/sandbox/network/)                                                       | [`outbound-workspace`](examples/outbound-workspace)                                                      |
-| Run a coding agent on a repository     | [Coding agents](https://developers.cloudflare.com/sandbox/coding-agents/)                                                          | [`coding-agents`](examples/coding-agents), [`devin`](devin), [`openai/agents-api`](openai/agents-api)    |
+| Goal                                   | Guide                                                                                                                              | Example                                                                                                                                       |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Run a script and read its output       | [Execute commands](https://developers.cloudflare.com/containers/guides/execute-commands/)                                          | [`workspace`](examples/workspace)                                                                                                             |
+| Keep a server or build running         | [Run background processes](https://developers.cloudflare.com/sandbox/commands/run-background-processes/)                           | [`process-workspace`](examples/process-workspace)                                                                                             |
+| Open a shell in the browser            | [Open a terminal in the browser](https://developers.cloudflare.com/sandbox/commands/open-a-terminal-in-the-browser/)               | [`terminal-workspace`](examples/terminal-workspace)                                                                                           |
+| Process files from a bucket            | [Mount an R2 bucket](https://developers.cloudflare.com/sandbox/files/mount-an-r2-bucket/)                                          | [`artifact-workspace`](examples/artifact-workspace)                                                                                           |
+| Save a workspace and resume it later   | [Save and restore a sandbox](https://developers.cloudflare.com/sandbox/files/save-and-restore-a-workspace/)                        | [`checkpoint-workspace`](examples/checkpoint-workspace), [`backup-workspace`](examples/backup-workspace)                                      |
+| Preview a web app while you edit it    | [Preview a web application](https://developers.cloudflare.com/sandbox/previews/)                                                   | [`preview-workspace`](examples/preview-workspace)                                                                                             |
+| Share a port on its own URL            | [Serve previews on their own hostnames](https://developers.cloudflare.com/sandbox/previews/serve-previews-on-their-own-hostnames/) | [`share-workspace`](examples/share-workspace)                                                                                                 |
+| Choose which hosts a sandbox can reach | [Control network access](https://developers.cloudflare.com/sandbox/network/)                                                       | [`outbound-workspace`](examples/outbound-workspace)                                                                                           |
+| Run a coding agent on a repository     | [Coding agents](https://developers.cloudflare.com/sandbox/coding-agents/)                                                          | [`coding-agents`](examples/coding-agents), [`templates/devin`](templates/devin), [`templates/openai-agents-api`](templates/openai-agents-api) |
 
 To run JavaScript or Python without a Linux environment, use [Dynamic Workers](https://developers.cloudflare.com/sandbox/concepts/) instead.
 
@@ -99,7 +99,7 @@ npm run check
 npm test
 ```
 
-[Testing](docs/testing.md) explains what these commands check, how to build behind a TLS-inspecting proxy, and how to test in production. [Releasing](docs/releasing.md) explains how maintainers publish the package and its image.
+[Testing](docs/testing.md) explains what these commands check, how to build behind a TLS-inspecting proxy, and how to test in production. [Releasing](docs/releasing.md) explains how to describe a change for the release notes, and how maintainers publish the package and its image.
 
 ## License
 

package/dist/index.d.mts

@@ -101,7 +101,7 @@ interface DirectoryBackupGatewayBinding {
  * The container reaches `fetch()` through the outbound intercept and can only use the grant
  * its current operation holds. The other methods are for the Durable Object alone.
  */
-declare class DirectoryBackupGateway extends WorkerEntrypoint<object, DirectoryBackupGatewayProps> {
+export declare class DirectoryBackupGateway extends WorkerEntrypoint<object, DirectoryBackupGatewayProps> {
   #private;
   fetch(request: Request): Promise<Response>;
   createUpload(name?: string): Promise<string>;
@@ -121,7 +121,7 @@ type DirectoryBackupContainer = Pick<Container, "exec" | "interceptOutboundHttp"
  * starts, retries, or times out anything. The application stores the returned records and
  * decides when to delete them.
  */
-declare class DirectoryBackup {
+export declare class DirectoryBackup {
   #private;
   constructor(container: DirectoryBackupContainer, gateway: DirectoryBackupGatewayBinding, storage: DirectoryBackupStorage);
   /**
@@ -214,7 +214,7 @@ type MkdirOptions = FileOperationOptions & {
  * Operations run against the current native container execution. Its image must provide the matching shim at
  * `/usr/local/bin/sandbox-shim`.
  */
-declare class Files {
+export declare class Files {
   #private;
   constructor(container: Pick<Container, "exec">);
   /**
@@ -452,7 +452,7 @@ interface S3GatewayBinding {
 }
 //#endregion
 //#region src/s3-mount/s3-gateway.d.ts
-declare class S3Gateway extends WorkerEntrypoint<object, S3GatewayProps> {
+export declare class S3Gateway extends WorkerEntrypoint<object, S3GatewayProps> {
   fetch(request: Request): Promise<Response>;
 }
 //#endregion
@@ -470,7 +470,7 @@ type S3MountContainer = Pick<Container, "exec" | "interceptOutboundHttp">;
  * monitors, or replaces it. The mounted path is not a POSIX filesystem. Do not
  * use it for locking or atomic rename.
  */
-declare class S3Mount {
+export declare class S3Mount {
   #private;
   constructor(container: S3MountContainer, gateway: S3GatewayBinding);
   /**
@@ -505,7 +505,7 @@ declare const FILE_OPERATIONS: readonly ["readFile", "writeFile", "stat", "lstat
 /** Filesystem operation that failed. */
 type SandboxFileOperation = (typeof FILE_OPERATIONS)[number];
 /** A native Linux filesystem failure reported by the sandbox container. */
-interface SandboxFileError extends Error {
+export interface SandboxFileError extends Error {
   readonly name: "SandboxFileError";
   readonly code: SandboxFileErrorCode;
   readonly operation: SandboxFileOperation;
@@ -513,38 +513,38 @@ interface SandboxFileError extends Error {
   readonly destination?: string;
   readonly detail: string;
 }
-declare const SandboxFileError: {
+export declare const SandboxFileError: {
   /** Recognizes local and JSRPC-crossed SandboxFileError values. */
   is(cause: unknown): cause is SandboxFileError;
 };
 /** An incompatible or malformed exchange with `sandbox-shim`. */
-interface SandboxProtocolError extends Error {
+export interface SandboxProtocolError extends Error {
   readonly name: "SandboxProtocolError";
   readonly code: "SANDBOX_PROTOCOL_ERROR";
   readonly detail: string;
 }
-declare const SandboxProtocolError: {
+export declare const SandboxProtocolError: {
   /** Recognizes local and JSRPC-crossed SandboxProtocolError values. */
   is(cause: unknown): cause is SandboxProtocolError;
 };
 type SandboxS3MountErrorCode = "S3_MOUNT_CONFLICT" | "S3_MOUNT_BUSY" | "S3_MOUNT_FAILED" | "S3_MOUNT_INCOMPATIBLE";
 type S3MountOperation = "mount" | "inspect" | "unmount";
 /** A classifiable failure while reconciling an S3-compatible filesystem mount. */
-interface SandboxS3MountError extends Error {
+export interface SandboxS3MountError extends Error {
   readonly name: "SandboxS3MountError";
   readonly code: SandboxS3MountErrorCode;
   readonly operation: S3MountOperation;
   readonly path: string;
   readonly detail: string;
 }
-declare const SandboxS3MountError: {
+export declare const SandboxS3MountError: {
   /** Recognizes local and JSRPC-crossed SandboxS3MountError values. */
   is(cause: unknown): cause is SandboxS3MountError;
 };
 type SandboxBackupErrorCode = "BACKUP_NOT_FOUND" | "BACKUP_INTEGRITY" | "BACKUP_TRANSFER";
 type DirectoryBackupOperation = "backup" | "restore" | "delete";
 /** A failure specific to a directory backup: a missing, altered, or unreachable object. */
-interface SandboxBackupError extends Error {
+export interface SandboxBackupError extends Error {
   readonly name: "SandboxBackupError";
   readonly code: SandboxBackupErrorCode;
   readonly operation: DirectoryBackupOperation;
@@ -552,9 +552,9 @@ interface SandboxBackupError extends Error {
   readonly path: string;
   readonly detail: string;
 }
-declare const SandboxBackupError: {
+export declare const SandboxBackupError: {
   /** Recognizes local and JSRPC-crossed SandboxBackupError values. */
   is(cause: unknown): cause is SandboxBackupError;
 };
 //#endregion
-export { DirectoryBackup, type DirectoryBackupDeleteOptions, DirectoryBackupGateway, type DirectoryBackupGatewayBinding, type DirectoryBackupOperation, type DirectoryBackupOptions, type DirectoryBackupRecord, type DirectoryBackupStorage, type DirectoryRestoreOptions, type FileContent, type FileOperationOptions, Files, type MkdirOptions, type RemoveOptions, S3Gateway, type S3GatewayBinding, S3Mount, type S3MountInspection, type S3MountOperation, type S3MountOperationOptions, type S3MountRequest, SandboxBackupError, type SandboxBackupErrorCode, type SandboxDirectoryEntry, SandboxFileError, type SandboxFileStat, type SandboxFileType, SandboxProtocolError, SandboxS3MountError, type SandboxS3MountErrorCode };
+export type { DirectoryBackupDeleteOptions, DirectoryBackupGatewayBinding, DirectoryBackupOperation, DirectoryBackupOptions, DirectoryBackupRecord, DirectoryBackupStorage, DirectoryRestoreOptions, FileContent, FileOperationOptions, MkdirOptions, RemoveOptions, S3GatewayBinding, S3MountInspection, S3MountOperation, S3MountOperationOptions, S3MountRequest, SandboxBackupErrorCode, SandboxDirectoryEntry, SandboxFileStat, SandboxFileType, SandboxS3MountErrorCode };

package/dist/index.mjs

@@ -985,11 +985,12 @@ async function readFile(container, path, options) {
 		stderr: "pipe"
 	});
 	let control;
-	let output;
+	let stdout;
 	try {
 		control = session.openStderrControl();
-		output = session.openStdoutReader();
+		stdout = new StdoutReader(session.openStdoutReader());
 		const opening = await control.readFrame();
+		stdout.stopReadingAhead();
 		if (opening.kind === "fileError") {
 			await control.expectEnd();
 			await session.settle();
@@ -1001,17 +1002,69 @@ async function readFile(container, path, options) {
 		if (opening.kind !== "success") throw protocolError("sandbox-shim returned data before file bytes");
 		const terminal = readTerminalControl(control);
 		terminal.catch(() => void 0);
-		return new Response(responseBody(session, control, output, terminal, path));
+		return new Response(responseBody(session, control, stdout, terminal, path));
 	} catch (error) {
-		terminateRead(session, control, output, error);
+		terminateRead(session, control, stdout, error);
 		throw error;
 	}
 }
-function responseBody(session, control, output, terminalFrame, path) {
+/**
+* Reads the shim's stdout, reading ahead until `readFile` has the opening frame from stderr.
+*
+* A container transport can carry stdout and stderr over one connection with shared backpressure,
+* and can deliver file bytes before the opening frame, or between its fragments. The rest of the
+* frame then arrives only after something reads stdout. The shim writes the whole opening frame
+* before any file byte, so the read-ahead stops once that frame is complete. After that, the
+* response body reads stdout on demand, so the caller's pace applies backpressure again.
+*
+* The read-ahead has no size limit, because stopping before the frame is complete would bring the
+* hang back. How much it holds depends on how far the transport lets stdout run ahead of stderr.
+*/
+var StdoutReader = class {
+	#reader;
+	#chunks = [];
+	#pending;
+	#readingAhead = true;
+	constructor(reader) {
+		this.#reader = reader;
+		this.#readNext();
+	}
+	/** Stops reading ahead. Chunks already read stay queued for `read()`. */
+	stopReadingAhead() {
+		this.#readingAhead = false;
+	}
+	read() {
+		const chunk = this.#chunks.shift();
+		if (chunk !== void 0) return Promise.resolve({
+			done: false,
+			value: chunk
+		});
+		const pending = this.#pending ?? this.#reader.read();
+		this.#pending = void 0;
+		return pending;
+	}
+	discard(reason) {
+		this.#reader.cancel(reason).then(() => this.#reader.releaseLock(), () => this.#reader.releaseLock());
+	}
+	releaseLock() {
+		this.#reader.releaseLock();
+	}
+	#readNext() {
+		const read = this.#reader.read();
+		this.#pending = read;
+		read.then((result) => {
+			if (this.#pending !== read || result.done) return;
+			this.#pending = void 0;
+			this.#chunks.push(result.value);
+			if (this.#readingAhead) this.#readNext();
+		}, () => void 0);
+	}
+};
+function responseBody(session, control, stdout, terminalFrame, path) {
 	return new ReadableStream({
 		pull: async (controller) => {
 			try {
-				const next = await session.waitFor(output.read());
+				const next = await session.waitFor(stdout.read());
 				if (!next.done) {
 					controller.enqueue(next.value);
 					return;
@@ -1025,16 +1078,16 @@ function responseBody(session, control, output, terminalFrame, path) {
 					}, terminal.errno, terminal.detail);
 				}
 				if (terminal.kind !== "success") throw protocolError("sandbox-shim returned data after file bytes");
-				output.releaseLock();
+				stdout.releaseLock();
 				control.releaseLock();
 				session.finish();
 				controller.close();
 			} catch (error) {
-				terminateRead(session, control, output, error);
+				terminateRead(session, control, stdout, error);
 				controller.error(error);
 			}
 		},
-		cancel: (reason) => terminateRead(session, control, output, reason)
+		cancel: (reason) => terminateRead(session, control, stdout, reason)
 	});
 }
 async function readTerminalControl(control) {
@@ -1042,10 +1095,10 @@ async function readTerminalControl(control) {
 	await control.expectEnd();
 	return frame;
 }
-function terminateRead(session, control, output, reason) {
+function terminateRead(session, control, stdout, reason) {
 	session.terminate();
 	control?.discard(reason);
-	if (output !== void 0) output.cancel(reason).then(() => output.releaseLock(), () => output.releaseLock());
+	stdout?.discard(reason);
 }
 //#endregion
 //#region src/files/stat-file.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Structured workspace file operations for Cloudflare sandboxes",
   "license": "Apache-2.0",
   "repository": {
@@ -23,6 +23,6 @@
   },
   "dependencies": {
     "aws4fetch": "1.0.20",
-    "zod": "4.5.4"
+    "zod": "4.6.7"
   }
 }