effect-cf 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # effect-cf
 
+## 0.50.0
+
+### Minor Changes
+
+- [#197](https://github.com/danieljvdm/effect-cf/pull/197) [`e174201`](https://github.com/danieljvdm/effect-cf/commit/e174201015b89202988c1bac5a3b25f1bfa6f5d0) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add `DurableObjectContainer` for direct Effect access to `ctx.container`, including runtime image and instance selection, native process execution with scoped cleanup and output streams, filesystem snapshots, HTTP readiness, TCP/HTTP ports with preview proxying, outbound interception, and idle timeouts. Timeout and polling options accept Effect duration inputs. Supply its layer to `DurableObject.make`, or wrap a native container with `fromContainer`.
+
+  Add `ContainerFiles.fromFiles` for Effect file operations and streams backed by Sandbox SDK 1.x `Files` and its matching `sandbox-shim`. File and native container failures retain their original causes.
+
+  Update the tested Cloudflare baseline to workerd `1.20260926.1`, Workers types `5.20260926.1`, Miniflare `5.20260926.1-alpha`, and Wrangler `4.144.0`, with compatibility date `2026-09-26`. Consumers using the optional Workers types package should update to the supported range or regenerate their Wrangler runtime types.
+
+  Retain the legacy Container and Sandbox adapters and document migration to the native API. Allow Sandbox SDK 1.x utilities alongside the native adapter; `effect-cf/sandbox` continues to require the legacy SDK 0.13 API.
+
 ## 0.49.0
 
 ### Minor Changes

package/README.md

@@ -6,12 +6,14 @@ Cloudflare entrypoints and bindings as Effect services.
 npm install effect-cf "effect@^4.0.0-rc.115"
 ```
 
-The repository tests against workerd `1.20260825.1` and `@cloudflare/workers-types@5.20260825.1`. Use `compatibility_date: "2026-08-25"` in Wrangler.
+The repository tests against workerd `1.20260926.1` and `@cloudflare/workers-types@5.20260926.1`. Use `compatibility_date: "2026-09-26"` in Wrangler.
 
 See the [runtime performance guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/runtime-performance.md) for measured alarm batching and telemetry configuration guidance.
 
 For typed WebSocket RPC clients whose connection lifetime is owned by an Effect layer, see the [WebSocket RPC guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/websocket-rpc.md).
 
+`DurableObjectContainer.layer` adds native `ctx.container` control to `DurableObject.make`: runtime image selection, command execution, filesystem snapshots, networking, and idle timeouts. See the [container guide](https://github.com/danieljvdm/effect-cf/blob/main/docs/containers.md) for setup and migration from the legacy Container and Sandbox classes.
+
 ## Worker
 
 ```ts
@@ -108,7 +110,7 @@ Enable tracing in `wrangler.jsonc`:
 
 ```jsonc
 {
-  "compatibility_date": "2026-08-25",
+  "compatibility_date": "2026-09-26",
   "observability": {
     "traces": { "enabled": true },
   },

package/dist/ContainerFiles.d.mts

@@ -0,0 +1,66 @@
+import { ContainerError } from "./DurableObjectContainer.mjs";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+declare namespace ContainerFiles_d_exports {
+  export { ContainerFiles, DirectoryEntry, FileContent, FileOperationOptions, FileStat, FileType, FilesResource, MkdirOptions, RemoveOptions, fromFiles };
+}
+type FileContent = string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array>;
+type FileType = "file" | "directory" | "symlink" | "blockDevice" | "characterDevice" | "fifo" | "socket";
+interface FileOperationOptions {
+  readonly cwd?: string;
+  readonly user?: string;
+}
+interface MkdirOptions extends FileOperationOptions {
+  readonly recursive?: boolean;
+}
+interface RemoveOptions extends FileOperationOptions {
+  readonly recursive?: boolean;
+  readonly force?: boolean;
+}
+interface FileStat {
+  readonly type: FileType;
+  readonly size: bigint;
+  readonly mode: number;
+  readonly uid: number;
+  readonly gid: number;
+  readonly accessedAt: Date;
+  readonly modifiedAt: Date;
+  readonly changedAt: Date;
+}
+interface DirectoryEntry {
+  readonly name: string;
+  readonly type: FileType;
+}
+type WithSignal<A> = A & {
+  readonly signal?: AbortSignal;
+};
+/** Structural contract of Sandbox SDK 1.x `Files`, without loading an SDK version. */
+interface FilesResource {
+  readFile(path: string, options?: WithSignal<FileOperationOptions>): Promise<Response>;
+  writeFile(path: string, content: FileContent, options?: WithSignal<FileOperationOptions>): Promise<void>;
+  stat(path: string, options?: WithSignal<FileOperationOptions>): Promise<FileStat>;
+  lstat(path: string, options?: WithSignal<FileOperationOptions>): Promise<FileStat>;
+  readDirectory(path: string, options?: WithSignal<FileOperationOptions>): Promise<ReadonlyArray<DirectoryEntry>>;
+  mkdir(path: string, options?: WithSignal<MkdirOptions>): Promise<void>;
+  rename(source: string, destination: string, options?: WithSignal<FileOperationOptions>): Promise<void>;
+  remove(path: string, options?: WithSignal<RemoveOptions>): Promise<void>;
+}
+interface ContainerFiles {
+  readonly raw: FilesResource;
+  /** The caller consumes or cancels the response body. Late failures retain native SDK errors. */
+  readonly readFile: (path: string, options?: FileOperationOptions) => Effect.Effect<Response, ContainerError>;
+  /** Includes failures that arrive while reading the response body. */
+  readonly readFileStream: (path: string, options?: FileOperationOptions) => Stream.Stream<Uint8Array, ContainerError>;
+  readonly readFileString: (path: string, options?: FileOperationOptions) => Effect.Effect<string, ContainerError>;
+  readonly writeFile: (path: string, content: FileContent, options?: FileOperationOptions) => Effect.Effect<void, ContainerError>;
+  readonly stat: (path: string, options?: FileOperationOptions) => Effect.Effect<FileStat, ContainerError>;
+  readonly lstat: (path: string, options?: FileOperationOptions) => Effect.Effect<FileStat, ContainerError>;
+  readonly readDirectory: (path: string, options?: FileOperationOptions) => Effect.Effect<ReadonlyArray<DirectoryEntry>, ContainerError>;
+  readonly mkdir: (path: string, options?: MkdirOptions) => Effect.Effect<void, ContainerError>;
+  readonly rename: (source: string, destination: string, options?: FileOperationOptions) => Effect.Effect<void, ContainerError>;
+  readonly remove: (path: string, options?: RemoveOptions) => Effect.Effect<void, ContainerError>;
+}
+/** Pass `new Files(container.raw)` from SDK 1.x. The image must supply its matching sandbox-shim. */
+declare const fromFiles: (files: FilesResource) => ContainerFiles;
+//#endregion
+export { ContainerFiles, ContainerFiles_d_exports, DirectoryEntry, FileContent, FileOperationOptions, FileStat, FileType, FilesResource, MkdirOptions, RemoveOptions, fromFiles };

package/dist/ContainerFiles.mjs

@@ -0,0 +1,66 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { ContainerError } from "./DurableObjectContainer.mjs";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+//#region src/ContainerFiles.ts
+var ContainerFiles_exports = /* @__PURE__ */ __exportAll({ fromFiles: () => fromFiles });
+const attempt = (operation, evaluate) => Effect.tryPromise({
+	try: evaluate,
+	catch: (cause) => new ContainerError({
+		operation: `files.${operation}`,
+		cause
+	})
+});
+/** Pass `new Files(container.raw)` from SDK 1.x. The image must supply its matching sandbox-shim. */
+const fromFiles = (files) => {
+	const readFile = (path, options) => attempt("readFile", (signal) => files.readFile(path, {
+		...options,
+		signal
+	}));
+	const readFileStream = (path, options) => Stream.unwrap(Effect.map(readFile(path, options), (response) => {
+		const body = response.body;
+		return body === null ? Stream.empty : Stream.fromReadableStream({
+			evaluate: () => body,
+			onError: (cause) => new ContainerError({
+				operation: "files.readFile",
+				cause
+			})
+		});
+	}));
+	return {
+		raw: files,
+		readFile,
+		readFileStream,
+		readFileString: (path, options) => readFileStream(path, options).pipe(Stream.decodeText(), Stream.mkString),
+		writeFile: (path, content, options) => attempt("writeFile", (signal) => files.writeFile(path, content, {
+			...options,
+			signal
+		})),
+		stat: (path, options) => attempt("stat", (signal) => files.stat(path, {
+			...options,
+			signal
+		})),
+		lstat: (path, options) => attempt("lstat", (signal) => files.lstat(path, {
+			...options,
+			signal
+		})),
+		readDirectory: (path, options) => attempt("readDirectory", (signal) => files.readDirectory(path, {
+			...options,
+			signal
+		})),
+		mkdir: (path, options) => attempt("mkdir", (signal) => files.mkdir(path, {
+			...options,
+			signal
+		})),
+		rename: (source, destination, options) => attempt("rename", (signal) => files.rename(source, destination, {
+			...options,
+			signal
+		})),
+		remove: (path, options) => attempt("remove", (signal) => files.remove(path, {
+			...options,
+			signal
+		}))
+	};
+};
+//#endregion
+export { ContainerFiles_exports, fromFiles };

package/dist/ContainerNamespace.d.mts

@@ -43,10 +43,12 @@ declare const ContainerState: S.Union<readonly [S.Struct<{
 }>]>;
 type ContainerState = typeof ContainerState.Type;
 /**
- * Native Container stub shape exposed by a Container namespace binding.
+ * RPC stub exposed by the legacy `@cloudflare/containers` Container class.
  *
  * This is structural so using Container bindings does not make
  * `@cloudflare/containers` a runtime dependency of effect-cf.
+ * Use `DurableObjectContainer` inside a Durable Object for the native
+ * `ctx.container` API and the `durable_object` scheduling policy.
  */
 interface ContainerStub {
   fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/DurableObjectContainer.d.mts

@@ -0,0 +1,133 @@
+import { DurableObjectState } from "./DurableObjectState.mjs";
+import * as Context$1 from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer$1 from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Duration from "effect/Duration";
+import * as Stream from "effect/Stream";
+import { Scope } from "effect";
+declare namespace DurableObjectContainer_d_exports {
+  export { ContainerError, ContainerExecOptions, ContainerExecOutput, ContainerExecOutputText, ContainerHttpReadinessOptions, ContainerInfo, ContainerNotConfiguredError, ContainerProcess, ContainerProcessLog, ContainerReadinessTimeoutError, ContainerSnapshot, ContainerSnapshotOptions, ContainerStartOptions, ContainerTcpPort, DurableObjectContainer, DurableObjectContainerService, fromContainer, layer };
+}
+type ContainerStartOptions = globalThis.ContainerStartupOptions;
+type ContainerExecOptions = Omit<globalThis.ContainerExecOptions, "signal">;
+type ContainerInfo = globalThis.ContainerInfo;
+type ContainerSnapshot = globalThis.ContainerSnapshot;
+type ContainerSnapshotOptions = globalThis.ContainerSnapshotOptions;
+type ContainerExecOutput = globalThis.ExecOutput;
+interface ContainerExecOutputText {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}
+interface ContainerProcessLog {
+  readonly stream: "stdout" | "stderr";
+  readonly data: Uint8Array;
+}
+interface ContainerHttpReadinessOptions {
+  /** Defaults to 30 seconds. All durations accept numbers in milliseconds. */
+  readonly timeout?: Duration.Input;
+  /** Delay between probes. Defaults to 100 milliseconds. */
+  readonly interval?: Duration.Input;
+  /** Bounds each connection or HTTP probe. Defaults to 1 second. */
+  readonly attemptTimeout?: Duration.Input;
+  readonly path?: string;
+  /** Accepts any HTTP response unless a status range is supplied. */
+  readonly status?: {
+    readonly min: number;
+    readonly max: number;
+  };
+}
+declare const ContainerNotConfiguredError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ContainerNotConfiguredError";
+} & Readonly<A>;
+declare class ContainerNotConfiguredError extends ContainerNotConfiguredError_base<{
+  readonly durableObjectId: string;
+}> {
+  get message(): string;
+}
+declare const ContainerError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ContainerError";
+} & Readonly<A>;
+declare class ContainerError extends ContainerError_base<{
+  readonly operation: string;
+  readonly cause: unknown;
+}> {
+  get message(): string;
+}
+declare const ContainerReadinessTimeoutError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ContainerReadinessTimeoutError";
+} & Readonly<A>;
+declare class ContainerReadinessTimeoutError extends ContainerReadinessTimeoutError_base<{
+  readonly port: number;
+  readonly timeout: Duration.Duration;
+  /** The last completed probe failure, when available. */
+  readonly cause: unknown;
+}> {
+  get message(): string;
+}
+/** A native process handle owned by its creating request. Choose one output consumer. */
+interface ContainerProcess {
+  readonly raw: globalThis.ExecProcess;
+  readonly pid: number;
+  readonly isPty: boolean;
+  readonly stdin: globalThis.ExecProcess["stdin"];
+  /** Empty when the corresponding native stream is absent. */
+  readonly stdout: Stream.Stream<Uint8Array, ContainerError>;
+  readonly stderr: Stream.Stream<Uint8Array, ContainerError>;
+  /** Drains both channels concurrently. Single-use, without buffering or replay. */
+  readonly logs: Stream.Stream<ContainerProcessLog, ContainerError>;
+  /** Nonzero exit codes are values, not Effect failures. */
+  readonly exitCode: Effect.Effect<number, ContainerError>;
+  readonly output: Effect.Effect<ContainerExecOutput, ContainerError>;
+  readonly outputText: Effect.Effect<ContainerExecOutputText, ContainerError>;
+  /** Signals the main process only; does nothing after its exit has been observed. */
+  readonly kill: (signal?: number) => Effect.Effect<void, ContainerError>;
+  readonly resize: (cols: number, rows: number) => Effect.Effect<void, ContainerError>;
+}
+interface ContainerTcpPort {
+  readonly raw: globalThis.Fetcher;
+  readonly fetch: (input: RequestInfo | URL, init?: RequestInit) => Effect.Effect<Response, ContainerError>;
+  /** Forwards an authorized preview request once, using the container's HTTP transport. */
+  readonly proxy: (request: Request) => Effect.Effect<Response, ContainerError>;
+  /** The caller owns the returned socket and must close it. */
+  readonly connect: (...args: Parameters<globalThis.Fetcher["connect"]>) => Effect.Effect<ReturnType<globalThis.Fetcher["connect"]>, ContainerError>;
+}
+/** Direct container control inside a Durable Object; lifecycle policy belongs to the application. */
+interface DurableObjectContainerService {
+  readonly raw: globalThis.Container;
+  readonly running: Effect.Effect<boolean, ContainerError>;
+  readonly images: Effect.Effect<Readonly<Record<string, string>>, ContainerError>;
+  readonly inspect: Effect.Effect<Option.Option<ContainerInfo>, ContainerError>;
+  /** Validates options and initiates startup. It does not wait for readiness. */
+  readonly start: (options?: ContainerStartOptions) => Effect.Effect<void, ContainerError>;
+  /** Waits for the container to stop; failures retain the native cause, including its exitCode. */
+  readonly monitor: Effect.Effect<void, ContainerError>;
+  readonly destroy: (reason?: Parameters<globalThis.Container["destroy"]>[0]) => Effect.Effect<void, ContainerError>;
+  readonly signal: (signal: number) => Effect.Effect<void, ContainerError>;
+  /** Effect duration input: numbers are milliseconds; bigints are nanoseconds. */
+  readonly setInactivityTimeout: (duration: Duration.Input) => Effect.Effect<void, ContainerError>;
+  readonly getTcpPort: (port: number) => Effect.Effect<ContainerTcpPort, ContainerError>;
+  /** Sends HTTP GET probes to an already-started container. Never retries a caller's request. */
+  readonly waitForHttp: (port: number, options?: ContainerHttpReadinessOptions) => Effect.Effect<void, ContainerError | ContainerReadinessTimeoutError>;
+  /**
+   * Runs an executable with arguments, without a shell or automatic container startup.
+   * Interruption cancels acquisition. After acquisition, the caller owns the process.
+   * To observe it from later requests, redirect output to files and ignore the native pipes.
+   */
+  readonly exec: (command: ReadonlyArray<string>, options?: ContainerExecOptions) => Effect.Effect<ContainerProcess, ContainerError>;
+  /** Sends SIGKILL to a still-running main process when the scope closes. */
+  readonly execScoped: (command: ReadonlyArray<string>, options?: ContainerExecOptions) => Effect.Effect<ContainerProcess, ContainerError, Scope.Scope>;
+  readonly snapshotContainer: (options?: ContainerSnapshotOptions) => Effect.Effect<ContainerSnapshot, ContainerError>;
+  readonly interceptOutboundHttp: (address: string, binding: globalThis.Fetcher) => Effect.Effect<void, ContainerError>;
+  readonly interceptAllOutboundHttp: (binding: globalThis.Fetcher) => Effect.Effect<void, ContainerError>;
+  readonly interceptOutboundHttps: (address: string, binding: globalThis.Fetcher) => Effect.Effect<void, ContainerError>;
+}
+declare const DurableObjectContainer_base: Context$1.ServiceClass<DurableObjectContainer, "effect-cf/DurableObjectContainer", DurableObjectContainerService>;
+declare class DurableObjectContainer extends DurableObjectContainer_base {}
+/** Wraps `ctx.container` without starting it or taking ownership of its lifecycle. */
+declare const fromContainer: (container: globalThis.Container) => DurableObjectContainerService;
+/** Supplies the container attached to the current Durable Object, without owning it. */
+declare const layer: Layer$1.Layer<DurableObjectContainer, ContainerNotConfiguredError, DurableObjectState>;
+//#endregion
+export { ContainerError, ContainerExecOptions, ContainerExecOutput, ContainerExecOutputText, ContainerHttpReadinessOptions, ContainerInfo, ContainerNotConfiguredError, ContainerProcess, ContainerProcessLog, ContainerReadinessTimeoutError, ContainerSnapshot, ContainerSnapshotOptions, ContainerStartOptions, ContainerTcpPort, DurableObjectContainer, DurableObjectContainerService, DurableObjectContainer_d_exports, fromContainer, layer };

package/dist/DurableObjectContainer.mjs

@@ -0,0 +1,179 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { causeMessage } from "./internal/ErrorMessage.mjs";
+import { DurableObjectState } from "./DurableObjectState.mjs";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Duration from "effect/Duration";
+import * as Stream from "effect/Stream";
+//#region src/DurableObjectContainer.ts
+var DurableObjectContainer_exports = /* @__PURE__ */ __exportAll({
+	ContainerError: () => ContainerError,
+	ContainerNotConfiguredError: () => ContainerNotConfiguredError,
+	ContainerReadinessTimeoutError: () => ContainerReadinessTimeoutError,
+	DurableObjectContainer: () => DurableObjectContainer,
+	fromContainer: () => fromContainer,
+	layer: () => layer
+});
+var ContainerNotConfiguredError = class extends Data.TaggedError("ContainerNotConfiguredError") {
+	get message() {
+		return `No container is configured for Durable Object "${this.durableObjectId}"`;
+	}
+};
+var ContainerError = class extends Data.TaggedError("ContainerError") {
+	get message() {
+		return `Durable Object container ${this.operation} failed: ${causeMessage(this.cause)}`;
+	}
+};
+var ContainerReadinessTimeoutError = class extends Data.TaggedError("ContainerReadinessTimeoutError") {
+	get message() {
+		return `Container port ${this.port} was not ready within ${Duration.toMillis(this.timeout)}ms`;
+	}
+};
+var DurableObjectContainer = class extends Context.Service()("effect-cf/DurableObjectContainer") {};
+const attempt = (operation, evaluate) => Effect.try({
+	try: evaluate,
+	catch: (cause) => new ContainerError({
+		operation,
+		cause
+	})
+});
+const attemptPromise = (operation, evaluate) => Effect.tryPromise({
+	try: evaluate,
+	catch: (cause) => new ContainerError({
+		operation,
+		cause
+	})
+});
+const processStream = (stream, operation) => stream === null || stream === void 0 ? Stream.empty : Stream.fromReadableStream({
+	evaluate: () => stream,
+	onError: (cause) => new ContainerError({
+		operation,
+		cause
+	})
+});
+const fromProcess = (process) => {
+	let exited = false;
+	const onExit = () => {
+		exited = true;
+	};
+	process.exitCode.then(onExit, onExit);
+	const stdout = processStream(process.stdout, "exec.stdout");
+	const stderr = processStream(process.stderr, "exec.stderr");
+	const output = attemptPromise("exec.output", () => process.output());
+	return {
+		raw: process,
+		pid: process.pid,
+		isPty: process.isPty,
+		stdin: process.stdin ?? null,
+		stdout,
+		stderr,
+		logs: Stream.merge(Stream.map(stdout, (data) => ({
+			stream: "stdout",
+			data
+		})), Stream.map(stderr, (data) => ({
+			stream: "stderr",
+			data
+		}))),
+		exitCode: attemptPromise("exec.exitCode", () => process.exitCode),
+		output,
+		outputText: Effect.map(output, (result) => ({
+			stdout: new TextDecoder().decode(result.stdout),
+			stderr: new TextDecoder().decode(result.stderr),
+			exitCode: result.exitCode
+		})),
+		kill: (signal) => attemptPromise("exec.kill", async () => {
+			await Promise.resolve();
+			if (!exited) process.kill(signal);
+		}),
+		resize: (cols, rows) => attempt("exec.resize", () => process.resize(cols, rows))
+	};
+};
+const fromTcpPort = (port) => {
+	const fetch = (input, init) => attemptPromise("getTcpPort.fetch", (signal) => {
+		const callerSignal = init?.signal !== void 0 ? init.signal : input instanceof Request ? input.signal : void 0;
+		return port.fetch(input, {
+			...init,
+			signal: callerSignal === null || callerSignal === void 0 ? signal : AbortSignal.any([callerSignal, signal])
+		});
+	});
+	return {
+		raw: port,
+		fetch,
+		proxy: (request) => attempt("getTcpPort.proxy", () => {
+			const url = new URL(request.url);
+			url.protocol = "http:";
+			return new Request(url, request);
+		}).pipe(Effect.flatMap((forwarded) => fetch(forwarded))),
+		connect: (...args) => attempt("getTcpPort.connect", () => port.connect(...args))
+	};
+};
+/** Wraps `ctx.container` without starting it or taking ownership of its lifecycle. */
+const fromContainer = (container) => {
+	const exec = (command, options) => attemptPromise("exec", (signal) => container.exec([...command], {
+		...options,
+		signal
+	})).pipe(Effect.map(fromProcess));
+	const waitForHttp = Effect.fnUntraced(function* (portNumber, options = {}) {
+		const timeout = yield* attempt("waitForHttp", () => Duration.fromInputUnsafe(options.timeout ?? "30 seconds"));
+		let lastFailure;
+		const probe = attemptPromise("waitForHttp", async (signal) => {
+			const response = await container.getTcpPort(portNumber).fetch(new URL(options.path ?? "/", "http://container"), { signal });
+			await response.body?.cancel();
+			if (options.status !== void 0 && (response.status < options.status.min || response.status > options.status.max)) throw new Error(`HTTP readiness probe returned status ${response.status}`);
+		});
+		return yield* Effect.gen(function* () {
+			while (true) {
+				if (!(yield* attempt("running", () => container.running))) return yield* new ContainerError({
+					operation: "waitForHttp",
+					cause: /* @__PURE__ */ new Error("Container stopped before the port became ready")
+				});
+				if (yield* probe.pipe(Effect.timeout(options.attemptTimeout ?? "1 second"), Effect.match({
+					onSuccess: () => true,
+					onFailure: (error) => {
+						lastFailure = error;
+						return false;
+					}
+				}))) return;
+				yield* Effect.sleep(options.interval ?? "100 millis");
+			}
+		}).pipe(Effect.timeoutOrElse({
+			duration: timeout,
+			orElse: () => Effect.fail(new ContainerReadinessTimeoutError({
+				port: portNumber,
+				timeout,
+				cause: lastFailure
+			}))
+		}));
+	});
+	return {
+		raw: container,
+		running: attempt("running", () => container.running),
+		images: attempt("images", () => container.images),
+		inspect: attemptPromise("inspect", () => container.inspect()).pipe(Effect.map(Option.fromNullishOr)),
+		start: (options) => attempt("start", () => container.start(options)),
+		monitor: attemptPromise("monitor", () => container.monitor()),
+		destroy: (reason) => attemptPromise("destroy", () => container.destroy(reason)),
+		signal: (signal) => attempt("signal", () => container.signal(signal)),
+		setInactivityTimeout: (duration) => attemptPromise("setInactivityTimeout", () => container.setInactivityTimeout(Duration.toMillis(duration))),
+		getTcpPort: (port) => attempt("getTcpPort", () => fromTcpPort(container.getTcpPort(port))),
+		waitForHttp,
+		exec,
+		execScoped: (command, options) => Effect.acquireRelease(exec(command, options), (process) => process.kill(9).pipe(Effect.orDie), { interruptible: true }),
+		snapshotContainer: (options = {}) => attemptPromise("snapshotContainer", () => container.snapshotContainer(options)),
+		interceptOutboundHttp: (address, binding) => attemptPromise("interceptOutboundHttp", () => container.interceptOutboundHttp(address, binding)),
+		interceptAllOutboundHttp: (binding) => attemptPromise("interceptAllOutboundHttp", () => container.interceptAllOutboundHttp(binding)),
+		interceptOutboundHttps: (address, binding) => attemptPromise("interceptOutboundHttps", () => container.interceptOutboundHttps(address, binding))
+	};
+};
+/** Supplies the container attached to the current Durable Object, without owning it. */
+const layer = Layer.effect(DurableObjectContainer, Effect.gen(function* () {
+	const state = yield* DurableObjectState;
+	const container = state.raw.container;
+	if (container === void 0) return yield* new ContainerNotConfiguredError({ durableObjectId: state.id.toString() });
+	return fromContainer(container);
+}));
+//#endregion
+export { ContainerError, ContainerNotConfiguredError, ContainerReadinessTimeoutError, DurableObjectContainer, DurableObjectContainer_exports, fromContainer, layer };

package/dist/index.d.mts

@@ -24,6 +24,8 @@ import { BrowserRendering_d_exports } from "./BrowserRendering.mjs";
 import { Cache_d_exports } from "./Cache.mjs";
 import { CloudflareOtlp_d_exports } from "./CloudflareOtlp.mjs";
 import { CloudflareTracer_d_exports } from "./CloudflareTracer.mjs";
+import { DurableObjectContainer_d_exports } from "./DurableObjectContainer.mjs";
+import { ContainerFiles_d_exports } from "./ContainerFiles.mjs";
 import { D1_d_exports } from "./D1.mjs";
 import { DurableObjectAlarm_d_exports } from "./DurableObjectAlarm.mjs";
 import { DurableObjectDefinition_d_exports } from "./DurableObjectDefinition.mjs";
@@ -40,4 +42,4 @@ import { Vectorize_d_exports } from "./Vectorize.mjs";
 import { WebTransport_d_exports } from "./WebTransport.mjs";
 import { WorkflowDefinition_d_exports } from "./WorkflowDefinition.mjs";
 import { Workflow_d_exports } from "./Workflow.mjs";
-export { AiGateway_d_exports as AiGateway, AnalyticsEngine_d_exports as AnalyticsEngine, Artifacts_d_exports as Artifacts, Binding_d_exports as Binding, BrowserRendering_d_exports as BrowserRendering, Cache_d_exports as Cache, CloudflareOtlp_d_exports as CloudflareOtlp, CloudflareTracer_d_exports as CloudflareTracer, ContainerNamespace_d_exports as ContainerNamespace, D1_d_exports as D1, DurableObject_d_exports as DurableObject, DurableObjectAlarm_d_exports as DurableObjectAlarm, DurableObjectDefinition_d_exports as DurableObjectDefinition, DurableObjectNamespace_d_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_d_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_d_exports as DurableObjectSqlite, DurableObjectState_d_exports as DurableObjectState, DurableObjectStorage_d_exports as DurableObjectStorage, DurableObjectWebSocket_d_exports as DurableObjectWebSocket, Email_d_exports as Email, Environment_d_exports as Environment, Hyperdrive_d_exports as Hyperdrive, Images_d_exports as Images, Kv_d_exports as Kv, Queue_d_exports as Queue, QueueBinding_d_exports as QueueBinding, QueueDefinition_d_exports as QueueDefinition, R2_d_exports as R2, Rpc_d_exports as Rpc, RpcDefinition_d_exports as RpcDefinition, RpcTargets_d_exports as RpcTargets, RpcTracing_d_exports as RpcTracing, RpcWebSocketClient_d_exports as RpcWebSocketClient, ServiceBinding_d_exports as ServiceBinding, Vectorize_d_exports as Vectorize, WebTransport_d_exports as WebTransport, Worker_d_exports as Worker, WorkerConfig, WorkerDefinition_d_exports as WorkerDefinition, type WorkerEnv, WorkerEnvironment, WorkersAi_d_exports as WorkersAi, Workflow_d_exports as Workflow, WorkflowBinding_d_exports as WorkflowBinding, WorkflowDefinition_d_exports as WorkflowDefinition };
+export { AiGateway_d_exports as AiGateway, AnalyticsEngine_d_exports as AnalyticsEngine, Artifacts_d_exports as Artifacts, Binding_d_exports as Binding, BrowserRendering_d_exports as BrowserRendering, Cache_d_exports as Cache, CloudflareOtlp_d_exports as CloudflareOtlp, CloudflareTracer_d_exports as CloudflareTracer, ContainerFiles_d_exports as ContainerFiles, ContainerNamespace_d_exports as ContainerNamespace, D1_d_exports as D1, DurableObject_d_exports as DurableObject, DurableObjectAlarm_d_exports as DurableObjectAlarm, DurableObjectContainer_d_exports as DurableObjectContainer, DurableObjectDefinition_d_exports as DurableObjectDefinition, DurableObjectNamespace_d_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_d_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_d_exports as DurableObjectSqlite, DurableObjectState_d_exports as DurableObjectState, DurableObjectStorage_d_exports as DurableObjectStorage, DurableObjectWebSocket_d_exports as DurableObjectWebSocket, Email_d_exports as Email, Environment_d_exports as Environment, Hyperdrive_d_exports as Hyperdrive, Images_d_exports as Images, Kv_d_exports as Kv, Queue_d_exports as Queue, QueueBinding_d_exports as QueueBinding, QueueDefinition_d_exports as QueueDefinition, R2_d_exports as R2, Rpc_d_exports as Rpc, RpcDefinition_d_exports as RpcDefinition, RpcTargets_d_exports as RpcTargets, RpcTracing_d_exports as RpcTracing, RpcWebSocketClient_d_exports as RpcWebSocketClient, ServiceBinding_d_exports as ServiceBinding, Vectorize_d_exports as Vectorize, WebTransport_d_exports as WebTransport, Worker_d_exports as Worker, WorkerConfig, WorkerDefinition_d_exports as WorkerDefinition, type WorkerEnv, WorkerEnvironment, WorkersAi_d_exports as WorkersAi, Workflow_d_exports as Workflow, WorkflowBinding_d_exports as WorkflowBinding, WorkflowDefinition_d_exports as WorkflowDefinition };

package/dist/index.mjs

@@ -11,6 +11,8 @@ import { DurableObjectWebSocket_exports } from "./DurableObjectWebSocket.mjs";
 import { DurableObjectState_exports } from "./DurableObjectState.mjs";
 import { CloudflareOtlp_exports } from "./CloudflareOtlp.mjs";
 import { CloudflareTracer_exports } from "./CloudflareTracer.mjs";
+import { DurableObjectContainer_exports } from "./DurableObjectContainer.mjs";
+import { ContainerFiles_exports } from "./ContainerFiles.mjs";
 import { RpcTargets_exports } from "./RpcTargets.mjs";
 import { ContainerNamespace_exports } from "./ContainerNamespace.mjs";
 import { D1_exports } from "./D1.mjs";
@@ -40,4 +42,4 @@ import { WebTransport_exports } from "./WebTransport.mjs";
 import { WorkflowBinding_exports } from "./WorkflowBinding.mjs";
 import { WorkflowDefinition_exports } from "./WorkflowDefinition.mjs";
 import { Workflow_exports } from "./Workflow.mjs";
-export { AiGateway_exports as AiGateway, AnalyticsEngine_exports as AnalyticsEngine, Artifacts_exports as Artifacts, Binding_exports as Binding, BrowserRendering_exports as BrowserRendering, Cache_exports as Cache, CloudflareOtlp_exports as CloudflareOtlp, CloudflareTracer_exports as CloudflareTracer, ContainerNamespace_exports as ContainerNamespace, D1_exports as D1, DurableObject_exports as DurableObject, DurableObjectAlarm_exports as DurableObjectAlarm, DurableObjectDefinition_exports as DurableObjectDefinition, DurableObjectNamespace_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_exports as DurableObjectSqlite, DurableObjectState_exports as DurableObjectState, DurableObjectStorage_exports as DurableObjectStorage, DurableObjectWebSocket_exports as DurableObjectWebSocket, Email_exports as Email, Environment_exports as Environment, Hyperdrive_exports as Hyperdrive, Images_exports as Images, Kv_exports as Kv, Queue_exports as Queue, QueueBinding_exports as QueueBinding, QueueDefinition_exports as QueueDefinition, R2_exports as R2, Rpc_exports as Rpc, RpcDefinition_exports as RpcDefinition, RpcTargets_exports as RpcTargets, RpcTracing_exports as RpcTracing, RpcWebSocketClient_exports as RpcWebSocketClient, ServiceBinding_exports as ServiceBinding, Vectorize_exports as Vectorize, WebTransport_exports as WebTransport, Worker_exports as Worker, WorkerConfig, WorkerDefinition_exports as WorkerDefinition, WorkerEnvironment, WorkersAi_exports as WorkersAi, Workflow_exports as Workflow, WorkflowBinding_exports as WorkflowBinding, WorkflowDefinition_exports as WorkflowDefinition };
+export { AiGateway_exports as AiGateway, AnalyticsEngine_exports as AnalyticsEngine, Artifacts_exports as Artifacts, Binding_exports as Binding, BrowserRendering_exports as BrowserRendering, Cache_exports as Cache, CloudflareOtlp_exports as CloudflareOtlp, CloudflareTracer_exports as CloudflareTracer, ContainerFiles_exports as ContainerFiles, ContainerNamespace_exports as ContainerNamespace, D1_exports as D1, DurableObject_exports as DurableObject, DurableObjectAlarm_exports as DurableObjectAlarm, DurableObjectContainer_exports as DurableObjectContainer, DurableObjectDefinition_exports as DurableObjectDefinition, DurableObjectNamespace_exports as DurableObjectNamespace, DurableObjectRpcWebSocket_exports as DurableObjectRpcWebSocket, DurableObjectSqlite_exports as DurableObjectSqlite, DurableObjectState_exports as DurableObjectState, DurableObjectStorage_exports as DurableObjectStorage, DurableObjectWebSocket_exports as DurableObjectWebSocket, Email_exports as Email, Environment_exports as Environment, Hyperdrive_exports as Hyperdrive, Images_exports as Images, Kv_exports as Kv, Queue_exports as Queue, QueueBinding_exports as QueueBinding, QueueDefinition_exports as QueueDefinition, R2_exports as R2, Rpc_exports as Rpc, RpcDefinition_exports as RpcDefinition, RpcTargets_exports as RpcTargets, RpcTracing_exports as RpcTracing, RpcWebSocketClient_exports as RpcWebSocketClient, ServiceBinding_exports as ServiceBinding, Vectorize_exports as Vectorize, WebTransport_exports as WebTransport, Worker_exports as Worker, WorkerConfig, WorkerDefinition_exports as WorkerDefinition, WorkerEnvironment, WorkersAi_exports as WorkersAi, Workflow_exports as Workflow, WorkflowBinding_exports as WorkflowBinding, WorkflowDefinition_exports as WorkflowDefinition };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-cf",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Effect-native primitives for Cloudflare Workers and bindings.",
   "license": "MIT",
   "repository": {
@@ -78,6 +78,7 @@
     "@cloudflare/computer": "0.2.0",
     "@cloudflare/containers": "catalog:",
     "@cloudflare/sandbox": "0.13.0-next.738.2",
+    "@cloudflare/sandbox-v1": "npm:@cloudflare/sandbox@1.0.0",
     "@cloudflare/vitest-plugin": "catalog:",
     "@cloudflare/workers-types": "catalog:",
     "@effect/platform-node": "catalog:",
@@ -96,9 +97,9 @@
   },
   "peerDependencies": {
     "@cloudflare/computer": "^0.2.0",
-    "@cloudflare/sandbox": "^0.13.0-next.738.2",
+    "@cloudflare/sandbox": "^0.13.0-next.738.2 || ^1.0.0",
     "@cloudflare/vitest-plugin": "^1.0.0",
-    "@cloudflare/workers-types": "^5.20260825.1",
+    "@cloudflare/workers-types": "^5.20260926.1",
     "@effect/sql-d1": "^4.0.0-rc.115",
     "@effect/sql-pg": "^4.0.0-rc.115",
     "@effect/sql-sqlite-do": "^4.0.0-rc.115",

package/src/ContainerFiles.ts

@@ -0,0 +1,162 @@
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+
+import { ContainerError } from "./DurableObjectContainer";
+
+export type FileContent =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | Blob
+  | ReadableStream<Uint8Array>;
+export type FileType =
+  | "file"
+  | "directory"
+  | "symlink"
+  | "blockDevice"
+  | "characterDevice"
+  | "fifo"
+  | "socket";
+
+export interface FileOperationOptions {
+  readonly cwd?: string;
+  readonly user?: string;
+}
+
+export interface MkdirOptions extends FileOperationOptions {
+  readonly recursive?: boolean;
+}
+
+export interface RemoveOptions extends FileOperationOptions {
+  readonly recursive?: boolean;
+  readonly force?: boolean;
+}
+
+export interface FileStat {
+  readonly type: FileType;
+  readonly size: bigint;
+  readonly mode: number;
+  readonly uid: number;
+  readonly gid: number;
+  readonly accessedAt: Date;
+  readonly modifiedAt: Date;
+  readonly changedAt: Date;
+}
+
+export interface DirectoryEntry {
+  readonly name: string;
+  readonly type: FileType;
+}
+
+type WithSignal<A> = A & { readonly signal?: AbortSignal };
+
+/** Structural contract of Sandbox SDK 1.x `Files`, without loading an SDK version. */
+export interface FilesResource {
+  readFile(path: string, options?: WithSignal<FileOperationOptions>): Promise<Response>;
+  writeFile(
+    path: string,
+    content: FileContent,
+    options?: WithSignal<FileOperationOptions>,
+  ): Promise<void>;
+  stat(path: string, options?: WithSignal<FileOperationOptions>): Promise<FileStat>;
+  lstat(path: string, options?: WithSignal<FileOperationOptions>): Promise<FileStat>;
+  readDirectory(
+    path: string,
+    options?: WithSignal<FileOperationOptions>,
+  ): Promise<ReadonlyArray<DirectoryEntry>>;
+  mkdir(path: string, options?: WithSignal<MkdirOptions>): Promise<void>;
+  rename(
+    source: string,
+    destination: string,
+    options?: WithSignal<FileOperationOptions>,
+  ): Promise<void>;
+  remove(path: string, options?: WithSignal<RemoveOptions>): Promise<void>;
+}
+
+export interface ContainerFiles {
+  readonly raw: FilesResource;
+  /** The caller consumes or cancels the response body. Late failures retain native SDK errors. */
+  readonly readFile: (
+    path: string,
+    options?: FileOperationOptions,
+  ) => Effect.Effect<Response, ContainerError>;
+  /** Includes failures that arrive while reading the response body. */
+  readonly readFileStream: (
+    path: string,
+    options?: FileOperationOptions,
+  ) => Stream.Stream<Uint8Array, ContainerError>;
+  readonly readFileString: (
+    path: string,
+    options?: FileOperationOptions,
+  ) => Effect.Effect<string, ContainerError>;
+  readonly writeFile: (
+    path: string,
+    content: FileContent,
+    options?: FileOperationOptions,
+  ) => Effect.Effect<void, ContainerError>;
+  readonly stat: (
+    path: string,
+    options?: FileOperationOptions,
+  ) => Effect.Effect<FileStat, ContainerError>;
+  readonly lstat: (
+    path: string,
+    options?: FileOperationOptions,
+  ) => Effect.Effect<FileStat, ContainerError>;
+  readonly readDirectory: (
+    path: string,
+    options?: FileOperationOptions,
+  ) => Effect.Effect<ReadonlyArray<DirectoryEntry>, ContainerError>;
+  readonly mkdir: (path: string, options?: MkdirOptions) => Effect.Effect<void, ContainerError>;
+  readonly rename: (
+    source: string,
+    destination: string,
+    options?: FileOperationOptions,
+  ) => Effect.Effect<void, ContainerError>;
+  readonly remove: (path: string, options?: RemoveOptions) => Effect.Effect<void, ContainerError>;
+}
+
+const attempt = <A>(operation: string, evaluate: (signal: AbortSignal) => Promise<A>) =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => new ContainerError({ operation: `files.${operation}`, cause }),
+  });
+
+/** Pass `new Files(container.raw)` from SDK 1.x. The image must supply its matching sandbox-shim. */
+export const fromFiles = (files: FilesResource): ContainerFiles => {
+  const readFile = (path: string, options?: FileOperationOptions) =>
+    attempt("readFile", (signal) => files.readFile(path, { ...options, signal }));
+  const readFileStream = (path: string, options?: FileOperationOptions) =>
+    Stream.unwrap(
+      Effect.map(readFile(path, options), (response) => {
+        const body = response.body;
+
+        return body === null
+          ? Stream.empty
+          : Stream.fromReadableStream({
+              evaluate: () => body,
+              onError: (cause) => new ContainerError({ operation: "files.readFile", cause }),
+            });
+      }),
+    );
+
+  return {
+    raw: files,
+    readFile,
+    readFileStream,
+    readFileString: (path, options) =>
+      readFileStream(path, options).pipe(Stream.decodeText(), Stream.mkString),
+    writeFile: (path, content, options) =>
+      attempt("writeFile", (signal) => files.writeFile(path, content, { ...options, signal })),
+    stat: (path, options) => attempt("stat", (signal) => files.stat(path, { ...options, signal })),
+    lstat: (path, options) =>
+      attempt("lstat", (signal) => files.lstat(path, { ...options, signal })),
+    readDirectory: (path, options) =>
+      attempt("readDirectory", (signal) => files.readDirectory(path, { ...options, signal })),
+    mkdir: (path, options) =>
+      attempt("mkdir", (signal) => files.mkdir(path, { ...options, signal })),
+    rename: (source, destination, options) =>
+      attempt("rename", (signal) => files.rename(source, destination, { ...options, signal })),
+    remove: (path, options) =>
+      attempt("remove", (signal) => files.remove(path, { ...options, signal })),
+  };
+};

package/src/ContainerNamespace.ts

@@ -60,10 +60,12 @@ export const ContainerState = S.Union([
 export type ContainerState = typeof ContainerState.Type;
 
 /**
- * Native Container stub shape exposed by a Container namespace binding.
+ * RPC stub exposed by the legacy `@cloudflare/containers` Container class.
  *
  * This is structural so using Container bindings does not make
  * `@cloudflare/containers` a runtime dependency of effect-cf.
+ * Use `DurableObjectContainer` inside a Durable Object for the native
+ * `ctx.container` API and the `durable_object` scheduling policy.
  */
 export interface ContainerStub {
   fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/src/DurableObjectContainer.ts

@@ -0,0 +1,388 @@
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import type { Scope } from "effect";
+
+import { DurableObjectState } from "./DurableObjectState";
+import * as ErrorMessage from "./internal/ErrorMessage";
+
+export type ContainerStartOptions = globalThis.ContainerStartupOptions;
+export type ContainerExecOptions = Omit<globalThis.ContainerExecOptions, "signal">;
+export type ContainerInfo = globalThis.ContainerInfo;
+export type ContainerSnapshot = globalThis.ContainerSnapshot;
+export type ContainerSnapshotOptions = globalThis.ContainerSnapshotOptions;
+export type ContainerExecOutput = globalThis.ExecOutput;
+
+export interface ContainerExecOutputText {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}
+
+export interface ContainerProcessLog {
+  readonly stream: "stdout" | "stderr";
+  readonly data: Uint8Array;
+}
+
+export interface ContainerHttpReadinessOptions {
+  /** Defaults to 30 seconds. All durations accept numbers in milliseconds. */
+  readonly timeout?: Duration.Input;
+  /** Delay between probes. Defaults to 100 milliseconds. */
+  readonly interval?: Duration.Input;
+  /** Bounds each connection or HTTP probe. Defaults to 1 second. */
+  readonly attemptTimeout?: Duration.Input;
+  readonly path?: string;
+  /** Accepts any HTTP response unless a status range is supplied. */
+  readonly status?: { readonly min: number; readonly max: number };
+}
+
+export class ContainerNotConfiguredError extends Data.TaggedError("ContainerNotConfiguredError")<{
+  readonly durableObjectId: string;
+}> {
+  override get message(): string {
+    return `No container is configured for Durable Object "${this.durableObjectId}"`;
+  }
+}
+
+export class ContainerError extends Data.TaggedError("ContainerError")<{
+  readonly operation: string;
+  readonly cause: unknown;
+}> {
+  override get message(): string {
+    return `Durable Object container ${this.operation} failed: ${ErrorMessage.causeMessage(this.cause)}`;
+  }
+}
+
+export class ContainerReadinessTimeoutError extends Data.TaggedError(
+  "ContainerReadinessTimeoutError",
+)<{
+  readonly port: number;
+  readonly timeout: Duration.Duration;
+  /** The last completed probe failure, when available. */
+  readonly cause: unknown;
+}> {
+  override get message(): string {
+    return `Container port ${this.port} was not ready within ${Duration.toMillis(this.timeout)}ms`;
+  }
+}
+
+/** A native process handle owned by its creating request. Choose one output consumer. */
+export interface ContainerProcess {
+  readonly raw: globalThis.ExecProcess;
+  readonly pid: number;
+  readonly isPty: boolean;
+  readonly stdin: globalThis.ExecProcess["stdin"];
+  /** Empty when the corresponding native stream is absent. */
+  readonly stdout: Stream.Stream<Uint8Array, ContainerError>;
+  readonly stderr: Stream.Stream<Uint8Array, ContainerError>;
+  /** Drains both channels concurrently. Single-use, without buffering or replay. */
+  readonly logs: Stream.Stream<ContainerProcessLog, ContainerError>;
+  /** Nonzero exit codes are values, not Effect failures. */
+  readonly exitCode: Effect.Effect<number, ContainerError>;
+  readonly output: Effect.Effect<ContainerExecOutput, ContainerError>;
+  readonly outputText: Effect.Effect<ContainerExecOutputText, ContainerError>;
+  /** Signals the main process only; does nothing after its exit has been observed. */
+  readonly kill: (signal?: number) => Effect.Effect<void, ContainerError>;
+  readonly resize: (cols: number, rows: number) => Effect.Effect<void, ContainerError>;
+}
+
+export interface ContainerTcpPort {
+  readonly raw: globalThis.Fetcher;
+  readonly fetch: (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ) => Effect.Effect<Response, ContainerError>;
+  /** Forwards an authorized preview request once, using the container's HTTP transport. */
+  readonly proxy: (request: Request) => Effect.Effect<Response, ContainerError>;
+  /** The caller owns the returned socket and must close it. */
+  readonly connect: (
+    ...args: Parameters<globalThis.Fetcher["connect"]>
+  ) => Effect.Effect<ReturnType<globalThis.Fetcher["connect"]>, ContainerError>;
+}
+
+/** Direct container control inside a Durable Object; lifecycle policy belongs to the application. */
+export interface DurableObjectContainerService {
+  readonly raw: globalThis.Container;
+  readonly running: Effect.Effect<boolean, ContainerError>;
+  readonly images: Effect.Effect<Readonly<Record<string, string>>, ContainerError>;
+  readonly inspect: Effect.Effect<Option.Option<ContainerInfo>, ContainerError>;
+  /** Validates options and initiates startup. It does not wait for readiness. */
+  readonly start: (options?: ContainerStartOptions) => Effect.Effect<void, ContainerError>;
+  /** Waits for the container to stop; failures retain the native cause, including its exitCode. */
+  readonly monitor: Effect.Effect<void, ContainerError>;
+  readonly destroy: (
+    reason?: Parameters<globalThis.Container["destroy"]>[0],
+  ) => Effect.Effect<void, ContainerError>;
+  readonly signal: (signal: number) => Effect.Effect<void, ContainerError>;
+  /** Effect duration input: numbers are milliseconds; bigints are nanoseconds. */
+  readonly setInactivityTimeout: (duration: Duration.Input) => Effect.Effect<void, ContainerError>;
+  readonly getTcpPort: (port: number) => Effect.Effect<ContainerTcpPort, ContainerError>;
+  /** Sends HTTP GET probes to an already-started container. Never retries a caller's request. */
+  readonly waitForHttp: (
+    port: number,
+    options?: ContainerHttpReadinessOptions,
+  ) => Effect.Effect<void, ContainerError | ContainerReadinessTimeoutError>;
+  /**
+   * Runs an executable with arguments, without a shell or automatic container startup.
+   * Interruption cancels acquisition. After acquisition, the caller owns the process.
+   * To observe it from later requests, redirect output to files and ignore the native pipes.
+   */
+  readonly exec: (
+    command: ReadonlyArray<string>,
+    options?: ContainerExecOptions,
+  ) => Effect.Effect<ContainerProcess, ContainerError>;
+  /** Sends SIGKILL to a still-running main process when the scope closes. */
+  readonly execScoped: (
+    command: ReadonlyArray<string>,
+    options?: ContainerExecOptions,
+  ) => Effect.Effect<ContainerProcess, ContainerError, Scope.Scope>;
+  readonly snapshotContainer: (
+    options?: ContainerSnapshotOptions,
+  ) => Effect.Effect<ContainerSnapshot, ContainerError>;
+  readonly interceptOutboundHttp: (
+    address: string,
+    binding: globalThis.Fetcher,
+  ) => Effect.Effect<void, ContainerError>;
+  readonly interceptAllOutboundHttp: (
+    binding: globalThis.Fetcher,
+  ) => Effect.Effect<void, ContainerError>;
+  readonly interceptOutboundHttps: (
+    address: string,
+    binding: globalThis.Fetcher,
+  ) => Effect.Effect<void, ContainerError>;
+}
+
+export class DurableObjectContainer extends Context.Service<
+  DurableObjectContainer,
+  DurableObjectContainerService
+>()("effect-cf/DurableObjectContainer") {}
+
+const attempt = <A>(operation: string, evaluate: () => A): Effect.Effect<A, ContainerError> =>
+  Effect.try({
+    try: evaluate,
+    catch: (cause) => new ContainerError({ operation, cause }),
+  });
+
+const attemptPromise = <A>(
+  operation: string,
+  evaluate: (signal: AbortSignal) => Promise<A>,
+): Effect.Effect<A, ContainerError> =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => new ContainerError({ operation, cause }),
+  });
+
+const processStream = (
+  stream: globalThis.ExecProcess["stdout"] | undefined,
+  operation: string,
+): Stream.Stream<Uint8Array, ContainerError> =>
+  stream === null || stream === undefined
+    ? Stream.empty
+    : Stream.fromReadableStream({
+        evaluate: () => stream,
+        onError: (cause) => new ContainerError({ operation, cause }),
+      });
+
+const fromProcess = (process: globalThis.ExecProcess): ContainerProcess => {
+  let exited = false;
+  const onExit = () => {
+    exited = true;
+  };
+
+  // Signaling an exited native process can raise an uncaught runtime error.
+  // Observe completion immediately, even if the caller never awaits exitCode.
+  process.exitCode.then(onExit, onExit);
+
+  const stdout = processStream(process.stdout, "exec.stdout");
+  const stderr = processStream(process.stderr, "exec.stderr");
+  const output = attemptPromise("exec.output", () => process.output());
+
+  return {
+    raw: process,
+    pid: process.pid,
+    isPty: process.isPty,
+    stdin: process.stdin ?? null,
+    stdout,
+    stderr,
+    logs: Stream.merge(
+      Stream.map(stdout, (data): ContainerProcessLog => ({ stream: "stdout", data })),
+      Stream.map(stderr, (data): ContainerProcessLog => ({ stream: "stderr", data })),
+    ),
+    exitCode: attemptPromise("exec.exitCode", () => process.exitCode),
+    output,
+    outputText: Effect.map(output, (result) => ({
+      stdout: new TextDecoder().decode(result.stdout),
+      stderr: new TextDecoder().decode(result.stderr),
+      exitCode: result.exitCode,
+    })),
+    kill: (signal) =>
+      attemptPromise("exec.kill", async () => {
+        // Let an already-settled exitCode notify us before attempting a signal.
+        await Promise.resolve();
+        if (!exited) process.kill(signal);
+      }),
+    resize: (cols, rows) => attempt("exec.resize", () => process.resize(cols, rows)),
+  };
+};
+
+const fromTcpPort = (port: globalThis.Fetcher): ContainerTcpPort => {
+  const fetch: ContainerTcpPort["fetch"] = (input, init) =>
+    attemptPromise("getTcpPort.fetch", (signal) => {
+      const callerSignal =
+        init?.signal !== undefined
+          ? init.signal
+          : input instanceof Request
+            ? input.signal
+            : undefined;
+
+      return port.fetch(input, {
+        ...init,
+        signal:
+          callerSignal === null || callerSignal === undefined
+            ? signal
+            : AbortSignal.any([callerSignal, signal]),
+      });
+    });
+
+  return {
+    raw: port,
+    fetch,
+    proxy: (request) =>
+      attempt("getTcpPort.proxy", () => {
+        const url = new URL(request.url);
+
+        url.protocol = "http:";
+
+        return new Request(url, request);
+      }).pipe(Effect.flatMap((forwarded) => fetch(forwarded))),
+    connect: (...args) => attempt("getTcpPort.connect", () => port.connect(...args)),
+  };
+};
+
+/** Wraps `ctx.container` without starting it or taking ownership of its lifecycle. */
+export const fromContainer = (container: globalThis.Container): DurableObjectContainerService => {
+  const exec = (command: ReadonlyArray<string>, options?: ContainerExecOptions) =>
+    attemptPromise("exec", (signal) => container.exec([...command], { ...options, signal })).pipe(
+      Effect.map(fromProcess),
+    );
+  const waitForHttp = Effect.fnUntraced(function* (
+    portNumber: number,
+    options: ContainerHttpReadinessOptions = {},
+  ) {
+    const timeout = yield* attempt("waitForHttp", () =>
+      Duration.fromInputUnsafe(options.timeout ?? "30 seconds"),
+    );
+    let lastFailure: unknown;
+    const probe = attemptPromise("waitForHttp", async (signal) => {
+      // Reacquire after a failed probe so workerd can discard a failed cached port capability.
+      const response = await container
+        .getTcpPort(portNumber)
+        .fetch(new URL(options.path ?? "/", "http://container"), { signal });
+
+      await response.body?.cancel();
+      if (
+        options.status !== undefined &&
+        (response.status < options.status.min || response.status > options.status.max)
+      ) {
+        throw new Error(`HTTP readiness probe returned status ${response.status}`);
+      }
+    });
+    const poll = Effect.gen(function* () {
+      while (true) {
+        if (!(yield* attempt("running", () => container.running))) {
+          return yield* new ContainerError({
+            operation: "waitForHttp",
+            cause: new Error("Container stopped before the port became ready"),
+          });
+        }
+        const ready = yield* probe.pipe(
+          Effect.timeout(options.attemptTimeout ?? "1 second"),
+          Effect.match({
+            onSuccess: () => true,
+            onFailure: (error) => {
+              lastFailure = error;
+
+              return false;
+            },
+          }),
+        );
+
+        if (ready) return;
+        yield* Effect.sleep(options.interval ?? "100 millis");
+      }
+    });
+
+    return yield* poll.pipe(
+      Effect.timeoutOrElse({
+        duration: timeout,
+        orElse: () =>
+          Effect.fail(
+            new ContainerReadinessTimeoutError({ port: portNumber, timeout, cause: lastFailure }),
+          ),
+      }),
+    );
+  });
+
+  return {
+    raw: container,
+    running: attempt("running", () => container.running),
+    images: attempt("images", () => container.images),
+    inspect: attemptPromise("inspect", () => container.inspect()).pipe(
+      Effect.map(Option.fromNullishOr),
+    ),
+    start: (options) => attempt("start", () => container.start(options)),
+    monitor: attemptPromise("monitor", () => container.monitor()),
+    destroy: (reason) => attemptPromise("destroy", () => container.destroy(reason)),
+    signal: (signal) => attempt("signal", () => container.signal(signal)),
+    setInactivityTimeout: (duration) =>
+      attemptPromise("setInactivityTimeout", () =>
+        container.setInactivityTimeout(Duration.toMillis(duration)),
+      ),
+    getTcpPort: (port) => attempt("getTcpPort", () => fromTcpPort(container.getTcpPort(port))),
+    waitForHttp,
+    exec,
+    execScoped: (command, options) =>
+      Effect.acquireRelease(
+        exec(command, options),
+        (process) => process.kill(9).pipe(Effect.orDie),
+        {
+          interruptible: true,
+        },
+      ),
+    snapshotContainer: (options = {}) =>
+      attemptPromise("snapshotContainer", () => container.snapshotContainer(options)),
+    interceptOutboundHttp: (address, binding) =>
+      attemptPromise("interceptOutboundHttp", () =>
+        container.interceptOutboundHttp(address, binding),
+      ),
+    interceptAllOutboundHttp: (binding) =>
+      attemptPromise("interceptAllOutboundHttp", () => container.interceptAllOutboundHttp(binding)),
+    interceptOutboundHttps: (address, binding) =>
+      attemptPromise("interceptOutboundHttps", () =>
+        container.interceptOutboundHttps(address, binding),
+      ),
+  };
+};
+
+/** Supplies the container attached to the current Durable Object, without owning it. */
+export const layer: Layer.Layer<
+  DurableObjectContainer,
+  ContainerNotConfiguredError,
+  DurableObjectState
+> = Layer.effect(
+  DurableObjectContainer,
+  Effect.gen(function* () {
+    const state = yield* DurableObjectState;
+    const container = state.raw.container;
+
+    if (container === undefined) {
+      return yield* new ContainerNotConfiguredError({ durableObjectId: state.id.toString() });
+    }
+
+    return fromContainer(container);
+  }),
+);

package/src/Sandbox.ts

@@ -1,3 +1,7 @@
+/**
+ * Adapter for the legacy `@cloudflare/sandbox` 0.13 namespace/client API.
+ * SDK 1.x utilities can instead use `DurableObjectContainer`'s native `raw` handle.
+ */
 import type {
   BackupOptions,
   CheckChangesOptions,

package/src/index.ts

@@ -6,10 +6,12 @@ export * as BrowserRendering from "./BrowserRendering";
 export * as Cache from "./Cache";
 export * as CloudflareOtlp from "./CloudflareOtlp";
 export * as CloudflareTracer from "./CloudflareTracer";
+export * as ContainerFiles from "./ContainerFiles";
 export * as ContainerNamespace from "./ContainerNamespace";
 export * as D1 from "./D1";
 export * as DurableObject from "./DurableObject";
 export * as DurableObjectAlarm from "./DurableObjectAlarm";
+export * as DurableObjectContainer from "./DurableObjectContainer";
 export * as DurableObjectDefinition from "./DurableObjectDefinition";
 export * as DurableObjectNamespace from "./DurableObjectNamespace";
 export * as DurableObjectRpcWebSocket from "./DurableObjectRpcWebSocket";