@alchemy.run/e2b 0.0.0 → 2.0.0-beta.87

package/src/internal/TemplateBuild.ts

@@ -0,0 +1,383 @@
+/**
+ * Plans and runs an E2B template build. Shared by the `E2B.Template`
+ * resource (which lowers its Dockerfile or `main` through
+ * `./TemplatePlan.ts` first) and the runtime `E2B.CreateTemplate` binding.
+ *
+ * E2B builds remotely only: there is no local Docker step. The flow is
+ *
+ *   1. `createTemplate` — the template (by name) and a new build id
+ *   2. `getTemplateFileUploadLink` per `COPY` hash, uploading what E2B lacks
+ *   3. `startTemplateBuild` — base image or template, steps, start/ready command
+ *   4. `getTemplateBuildStatus` until the build is `ready` or `error`
+ *
+ * This module runs where a Worker runs: it imports nothing from
+ * `@alchemy.run/docker`.
+ */
+import * as crypto from "node:crypto";
+import * as templates from "@distilled.cloud/e2b/templates";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import type * as PlatformError from "effect/PlatformError";
+import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
+import { E2BUnexpectedResponse, TemplateBuildFailed } from "../Errors.ts";
+import { tarGzip } from "./Tar.ts";
+
+/** Credentials for a private base image. Passed to E2B's builder for the pull only. */
+export type TemplateRegistry =
+  | {
+      /** Any registry with username/password auth (Docker Hub, GHCR, …). */
+      readonly username: string;
+      readonly password: Redacted.Redacted<string>;
+    }
+  | {
+      /** Amazon ECR. */
+      readonly awsAccessKeyId: string;
+      readonly awsSecretAccessKey: Redacted.Redacted<string>;
+      readonly awsRegion: string;
+    }
+  | {
+      /** Google Artifact Registry / GCR. */
+      readonly serviceAccountJson: Redacted.Redacted<string>;
+    };
+
+/** A file written into the template, from memory. */
+export interface TemplateFile {
+  /** Absolute path in the template, e.g. `/home/user/app/config.json`. */
+  readonly path: string;
+  readonly contents: Uint8Array | string;
+  /** @default 0o644 */
+  readonly mode?: number;
+}
+
+/** E2B's own build inputs: a base plus steps, with no Dockerfile. */
+export interface TemplateSteps {
+  /** A registry image to build on, e.g. `"python:3.12-slim"`. */
+  readonly image?: string;
+  /** Another E2B template (name or id) to build on, reusing its cached layers. */
+  readonly fromTemplate?: string;
+  /** Environment variables set in the template (`ENV`). */
+  readonly env?: Readonly<Record<string, string>>;
+  /** Files written into the template. */
+  readonly files?: ReadonlyArray<TemplateFile>;
+  /** Shell commands run as extra `RUN` steps, after `env` and `files`. */
+  readonly run?: ReadonlyArray<string>;
+  /** Credentials for a private base image. */
+  readonly registry?: TemplateRegistry;
+  /**
+   * Command started when the template is built and captured running in its
+   * snapshot, so every sandbox starts with it already up.
+   */
+  readonly startCmd?: string;
+  /** Command that exits 0 once `startCmd` is ready; the snapshot is taken then. */
+  readonly readyCmd?: string;
+}
+
+/** Where a build's template lives and how big its sandboxes are. */
+export interface TemplateOptions {
+  /** Template name (and alias). */
+  readonly name: string;
+  /**
+   * Tags assigned to this build (e.g. `"v1"`). Sandboxes created from the
+   * template id or name boot its `default` tag.
+   * @default ["default"]
+   */
+  readonly tags?: ReadonlyArray<string>;
+  readonly cpuCount?: number;
+  readonly memoryMB?: number;
+  readonly minFreeDiskMb?: number;
+  /** Rebuild every layer, ignoring E2B's cache. */
+  readonly force?: boolean;
+}
+
+export interface TemplateBuildSpec extends TemplateSteps, TemplateOptions {}
+
+/** One file a `COPY` step uploads. */
+export interface UploadFile {
+  /** Path inside the archive, `/`-separated. */
+  readonly path: string;
+  readonly mode: number;
+  readonly size: number;
+  /** Hex SHA-256 of the contents. */
+  readonly sha256: string;
+  readonly read: Effect.Effect<Uint8Array, PlatformError.PlatformError>;
+}
+
+export interface PlannedStep {
+  readonly type: "RUN" | "COPY" | "ENV" | "WORKDIR" | "USER";
+  readonly args: ReadonlyArray<string>;
+  readonly filesHash?: string;
+}
+
+/** A base and steps that came before `TemplateSteps`' own: a lowered Dockerfile or program. */
+export interface LoweredSource {
+  readonly fromImage: string;
+  readonly steps: ReadonlyArray<PlannedStep>;
+  readonly uploads: ReadonlyMap<string, ReadonlyArray<UploadFile>>;
+  /** The start command the source declares (`ENTRYPOINT` / `CMD`). */
+  readonly startCmd: string | undefined;
+}
+
+export interface TemplateBuildPlan {
+  readonly fromImage?: string;
+  readonly fromTemplate?: string;
+  readonly steps: ReadonlyArray<PlannedStep>;
+  readonly startCmd?: string;
+  readonly readyCmd?: string;
+  /** Files per `COPY` hash, uploaded when E2B does not have them. */
+  readonly uploads: ReadonlyMap<string, ReadonlyArray<UploadFile>>;
+  /** Content hash of everything that determines the build. A different hash means rebuild. */
+  readonly hash: string;
+}
+
+export interface TemplateBuildResult {
+  readonly templateId: string;
+  readonly buildId: string;
+  readonly names: ReadonlyArray<string>;
+  readonly aliases: ReadonlyArray<string>;
+  readonly tags: ReadonlyArray<string>;
+  readonly public: boolean;
+}
+
+/** E2B's default base image, for a template with no `image`, Dockerfile or `fromTemplate`. */
+export const DEFAULT_BASE_IMAGE = "e2bdev/base";
+
+const encoder = new TextEncoder();
+
+const sha256 = (bytes: Uint8Array | string) =>
+  crypto.createHash("sha256").update(bytes).digest("hex");
+
+/**
+ * The content hash E2B caches a `COPY` step's files under: sha256 over the
+ * step, then each file's path, mode, size and content hash. Stable across
+ * machines (no owners or timestamps).
+ */
+export const filesHash = (
+  src: string,
+  dest: string,
+  files: ReadonlyArray<Pick<UploadFile, "path" | "mode" | "size" | "sha256">>,
+): string => {
+  const hash = crypto.createHash("sha256");
+  hash.update(`COPY ${src} ${dest}`);
+  for (const file of files) {
+    hash.update(`${file.path}\0${file.mode}\0${file.size}\0${file.sha256}\0`);
+  }
+  return hash.digest("hex");
+};
+
+/** `files` as `COPY` steps: each file is its own upload, named by its content. */
+const fileSteps = (files: ReadonlyArray<TemplateFile>) =>
+  files.map((file) => {
+    const bytes = typeof file.contents === "string" ? encoder.encode(file.contents) : file.contents;
+    const upload: UploadFile = {
+      path: `files/${sha256(bytes).slice(0, 16)}`,
+      mode: file.mode ?? 0o644,
+      size: bytes.byteLength,
+      sha256: sha256(bytes),
+      read: Effect.succeed(bytes),
+    };
+    const hash = filesHash(upload.path, file.path, [upload]);
+    return {
+      step: {
+        type: "COPY",
+        args: [upload.path, file.path, "", ""],
+        filesHash: hash,
+      } as PlannedStep,
+      hash,
+      upload,
+    };
+  });
+
+/**
+ * Plans a build: the lowered source (if any), then `env`, `files` and `run`
+ * as E2B steps, hashed.
+ */
+export const planTemplateBuild = (spec: TemplateBuildSpec, lowered?: LoweredSource) =>
+  Effect.gen(function* () {
+    if (spec.image !== undefined && spec.fromTemplate !== undefined) {
+      return yield* new E2BUnexpectedResponse({
+        message: `template ${spec.name}: set one of image or fromTemplate`,
+      });
+    }
+    const uploads = new Map<string, ReadonlyArray<UploadFile>>(lowered?.uploads ?? []);
+    const files = fileSteps(spec.files ?? []);
+    for (const file of files) uploads.set(file.hash, [file.upload]);
+    const steps: PlannedStep[] = [
+      ...(lowered?.steps ?? []),
+      ...(spec.env && Object.keys(spec.env).length > 0
+        ? [{ type: "ENV" as const, args: Object.entries(spec.env).flat() }]
+        : []),
+      ...files.map((file) => file.step),
+      ...(spec.run ?? []).map((command) => ({ type: "RUN" as const, args: [command] })),
+    ];
+    const fromTemplate = spec.fromTemplate;
+    const fromImage =
+      fromTemplate !== undefined
+        ? undefined
+        : (lowered?.fromImage ?? spec.image ?? DEFAULT_BASE_IMAGE);
+    const startCmd = spec.startCmd ?? lowered?.startCmd;
+
+    const hash = sha256(
+      JSON.stringify({
+        fromImage,
+        fromTemplate,
+        steps,
+        startCmd,
+        readyCmd: spec.readyCmd,
+        cpuCount: spec.cpuCount,
+        memoryMB: spec.memoryMB,
+        minFreeDiskMb: spec.minFreeDiskMb,
+        registry: spec.registry === undefined ? undefined : Object.keys(spec.registry).sort(),
+      }),
+    );
+
+    return {
+      fromImage,
+      fromTemplate,
+      steps,
+      startCmd,
+      readyCmd: spec.readyCmd,
+      uploads,
+      hash,
+    } satisfies TemplateBuildPlan;
+  });
+
+const registryOf = (registry: TemplateRegistry): templates.FromImageRegistry =>
+  // The registry union is opaque on the wire: secrets are unwrapped here, at
+  // the point of use, and never logged.
+  "awsAccessKeyId" in registry
+    ? {
+        type: "aws",
+        awsAccessKeyId: registry.awsAccessKeyId,
+        awsSecretAccessKey: Redacted.value(registry.awsSecretAccessKey),
+        awsRegion: registry.awsRegion,
+      }
+    : "serviceAccountJson" in registry
+      ? { type: "gcp", serviceAccountJson: Redacted.value(registry.serviceAccountJson) }
+      : {
+          type: "registry",
+          username: registry.username,
+          password: Redacted.value(registry.password),
+        };
+
+/** Uploads one `COPY` context unless E2B already has it. */
+const uploadContext = Effect.fn(function* (
+  templateId: string,
+  hash: string,
+  files: ReadonlyArray<UploadFile>,
+) {
+  const link = yield* templates.getTemplateFileUploadLink({ templateID: templateId, hash });
+  if (link.present) return;
+  if (link.url === undefined) {
+    return yield* new E2BUnexpectedResponse({
+      message: `E2B returned no upload URL for context ${hash} of template ${templateId}`,
+    });
+  }
+  const archive = yield* tarGzip(
+    yield* Effect.forEach(files, (file) =>
+      Effect.map(file.read, (contents) => ({ path: file.path, mode: file.mode, contents })),
+    ),
+  );
+  const client = yield* HttpClient.HttpClient;
+  const headers = Object.fromEntries(
+    Object.entries(link.headers ?? {}).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  );
+  // Raw HTTP: a presigned upload URL the API handed back, used as-is. The
+  // body is sized (presigned PUTs reject chunked transfer encoding), and
+  // carries only the headers E2B returned: the URL is signed without a
+  // Content-Type, so sending one fails with SignatureDoesNotMatch.
+  const response = yield* client
+    .execute(
+      HttpClientRequest.put(link.url).pipe(
+        HttpClientRequest.bodyUint8Array(archive),
+        HttpClientRequest.removeHeader("content-type"),
+        HttpClientRequest.setHeaders(headers),
+      ),
+    )
+    .pipe(Effect.retry({ times: 4, schedule: Schedule.exponential("500 millis") }));
+  if (response.status < 200 || response.status >= 300) {
+    const body = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
+    return yield* new E2BUnexpectedResponse({
+      message: `uploading build context ${hash} for template ${templateId} failed with HTTP ${response.status}: ${body.slice(0, 500)}`,
+    });
+  }
+});
+
+/** Polls a build until it is ready; fails with its reason and the tail of its logs. */
+export const waitForBuild = Effect.fn(function* (templateId: string, buildId: string) {
+  const status = yield* templates
+    .getTemplateBuildStatus({ templateID: templateId, buildID: buildId })
+    .pipe(
+      Effect.repeat({
+        // Image pulls and dependency installs take minutes; bounded at ~20 min.
+        schedule: Schedule.spaced(Duration.seconds(3)),
+        until: (info) => info.status === "ready" || info.status === "error",
+        times: 400,
+      }),
+    );
+  if (status.status !== "ready") {
+    // `logs` is always empty on the current build path; `logEntries` has them.
+    const logs = (status.reason?.logEntries ?? status.logEntries)
+      .slice(-40)
+      .map((entry) => entry.message);
+    return yield* new TemplateBuildFailed({
+      message: [
+        `E2B template build ${buildId} failed: ${status.reason?.message ?? status.status}`,
+        ...logs.slice(-15).map((line) => `  ${line}`),
+      ].join("\n"),
+      templateId,
+      buildId,
+      reason: status.reason?.message,
+      logs,
+    });
+  }
+  return status;
+});
+
+/** Runs a planned build to completion. */
+export const runTemplateBuild = Effect.fn(function* (
+  spec: TemplateBuildSpec,
+  plan: TemplateBuildPlan,
+) {
+  const created = yield* templates.createTemplate({
+    name: spec.name,
+    tags: spec.tags === undefined ? undefined : [...spec.tags],
+    cpuCount: spec.cpuCount,
+    memoryMB: spec.memoryMB,
+    minFreeDiskMb: spec.minFreeDiskMb,
+  });
+  yield* Effect.forEach(
+    [...plan.uploads],
+    ([hash, files]) => uploadContext(created.templateID, hash, files),
+    { concurrency: 4, discard: true },
+  );
+  yield* templates.startTemplateBuild({
+    templateID: created.templateID,
+    buildID: created.buildID,
+    fromImage: plan.fromImage,
+    fromTemplate: plan.fromTemplate,
+    fromImageRegistry: spec.registry === undefined ? undefined : registryOf(spec.registry),
+    steps: plan.steps.map((step) => ({
+      type: step.type,
+      args: [...step.args],
+      filesHash: step.filesHash,
+      force: spec.force,
+    })),
+    startCmd: plan.startCmd,
+    readyCmd: plan.readyCmd,
+    force: spec.force,
+  });
+  yield* waitForBuild(created.templateID, created.buildID);
+  return {
+    templateId: created.templateID,
+    buildId: created.buildID,
+    names: created.names,
+    aliases: created.aliases,
+    tags: created.tags,
+    public: created.public,
+  } satisfies TemplateBuildResult;
+});

package/src/internal/TemplatePlan.ts

@@ -0,0 +1,230 @@
+/**
+ * Lowers an image source (`image`, `dockerfile` + `context`, `main`) to E2B
+ * build steps through `@alchemy.run/docker/BuildPlan`.
+ *
+ * E2B does not run `docker build`: its builder takes a base image plus a
+ * list of steps (`RUN`, `COPY`, `ENV`, `WORKDIR`, `USER`) and a start
+ * command. `BuildPlan.plan` parses the Dockerfile, bundles `main`, collects
+ * the context files every `COPY` reads, and rejects what E2B's builder
+ * cannot run ({@link E2BCapabilities}). This module maps the plan's final
+ * stage onto E2B's steps, one `COPY` step and upload per source.
+ *
+ * Like E2B's own SDK, the build starts as `root` in `/` and ends as `user`
+ * in `/home/user` unless the Dockerfile sets `USER` / `WORKDIR` itself.
+ *
+ * Deploy-time only: `BuildPlan` bundles and reads the filesystem.
+ */
+import * as BuildPlan from "@alchemy.run/docker/BuildPlan";
+import type { ImageSourceProps } from "@alchemy.run/docker/ImageSource";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import { UnsupportedDockerfileInstruction } from "../Errors.ts";
+import {
+  filesHash,
+  type LoweredSource,
+  type PlannedStep,
+  type UploadFile,
+} from "./TemplateBuild.ts";
+
+/** What E2B's template builder can build. */
+export const E2BCapabilities: BuildPlan.Capabilities = {
+  target: "E2B.Template",
+  multiStage: false,
+  heredocs: false,
+  runMounts: false,
+  remoteAdd: false,
+  platforms: ["linux/amd64"],
+  // E2B's builder takes no build args or build secrets: arg values are
+  // written into the steps, and secret mounts fail at plan.
+  buildArgs: false,
+  secrets: false,
+  instructions: {
+    SHELL: "unsupported",
+    EXPOSE: "ignored",
+    LABEL: "ignored",
+    VOLUME: "ignored",
+    HEALTHCHECK: "ignored",
+    STOPSIGNAL: "ignored",
+    ONBUILD: "ignored",
+    MAINTAINER: "ignored",
+  },
+};
+
+/** `$VAR`, `${VAR}`, `${VAR:-default}` and `${VAR:+alt}` from ARG/ENV values, as Docker expands them. */
+export const substitute = (text: string, vars: ReadonlyMap<string, string>): string =>
+  text.replace(
+    /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::([-+])([^}]*))?\}|\$([A-Za-z_][A-Za-z0-9_]*)/g,
+    (
+      _,
+      braced: string | undefined,
+      op: string | undefined,
+      word: string | undefined,
+      bare: string | undefined,
+    ) => {
+      const name = braced ?? bare!;
+      const value = vars.get(name);
+      if (op === "-") return value !== undefined && value !== "" ? value : (word ?? "");
+      if (op === "+") return value !== undefined && value !== "" ? (word ?? "") : "";
+      return value ?? "";
+    },
+  );
+
+const shellQuote = (word: string) =>
+  /^[A-Za-z0-9_\-./=:@%+,]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+
+/** An exec-form argv as one shell command, for E2B's string steps. */
+export const shellCommand = (argv: ReadonlyArray<string>) => argv.map(shellQuote).join(" ");
+
+/**
+ * Lowers a plan's final stage to E2B steps. `args` override `ARG` defaults,
+ * like `docker build --build-arg`. An `ARG` becomes an `ENV` step, as in
+ * E2B's SDK, so `RUN` steps read it.
+ */
+export const lowerPlan = (plan: BuildPlan.BuildPlan, args: Readonly<Record<string, string>> = {}) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const fail = (message: string, line: number) =>
+      Effect.fail(new UnsupportedDockerfileInstruction({ message, line }));
+    /** An ARG's value: the build arg, else its default, else (in a stage) the global value. */
+    const argValue = (
+      name: string,
+      defaultValue: string | undefined,
+      vars: ReadonlyMap<string, string>,
+      inherited?: string,
+    ) => args[name] ?? (defaultValue !== undefined ? substitute(defaultValue, vars) : inherited);
+
+    const global = new Map<string, string>();
+    for (const arg of plan.dockerfile.globalArgs) {
+      for (const [name, defaultValue] of arg.vars) {
+        const value = argValue(name, defaultValue, global);
+        if (value !== undefined) global.set(name, value);
+      }
+    }
+    const fromImage = substitute(plan.base, global);
+    // Global ARGs only parameterise FROM; the stage sees the ones it redeclares.
+    const vars = new Map<string, string>();
+
+    const steps: PlannedStep[] = [
+      { type: "USER", args: ["root"] },
+      { type: "WORKDIR", args: ["/"] },
+    ];
+    const uploads = new Map<string, ReadonlyArray<UploadFile>>();
+    let userChanged = false;
+    let workdirChanged = false;
+
+    for (const instruction of plan.instructions) {
+      switch (instruction._tag) {
+        case "ARG": {
+          const set: string[] = [];
+          for (const [name, defaultValue] of instruction.vars) {
+            const value = argValue(name, defaultValue, vars, global.get(name));
+            if (value === undefined) continue;
+            vars.set(name, value);
+            set.push(name, value);
+          }
+          if (set.length > 0) steps.push({ type: "ENV", args: set });
+          break;
+        }
+        case "ENV": {
+          const pairs = instruction.vars.map(
+            ([name, value]) => [name, substitute(value, vars)] as const,
+          );
+          for (const [name, value] of pairs) vars.set(name, value);
+          steps.push({ type: "ENV", args: pairs.flat() });
+          break;
+        }
+        case "RUN":
+          steps.push({
+            type: "RUN",
+            args: [
+              instruction.command.form === "exec"
+                ? shellCommand(instruction.command.argv)
+                : instruction.command.script,
+            ],
+          });
+          break;
+        case "COPY":
+        case "ADD": {
+          const flag = (name: string) =>
+            instruction.flags.find((candidate) => candidate.name === name)?.value ?? "";
+          const dest = substitute(instruction.destination, vars);
+          for (const raw of instruction.sources) {
+            const src = substitute(raw, vars);
+            const files = BuildPlan.filesFor(plan, { ...instruction, sources: [src] });
+            if (files.length === 0) {
+              return yield* fail(
+                `${instruction._tag} ${src} matches no files in the build context`,
+                instruction.line,
+              );
+            }
+            const upload = files.map((file): UploadFile => ({
+              path: file.path,
+              mode: file.mode,
+              size: file.size,
+              sha256: file.sha256,
+              read: BuildPlan.readContextFile(file).pipe(
+                Effect.provideService(FileSystem.FileSystem, fs),
+              ),
+            }));
+            const hash = filesHash(src, dest, upload);
+            uploads.set(hash, upload);
+            steps.push({
+              type: "COPY",
+              args: [src, dest, substitute(flag("chown"), vars), flag("chmod")],
+              filesHash: hash,
+            });
+          }
+          break;
+        }
+        case "WORKDIR":
+          steps.push({ type: "WORKDIR", args: [substitute(instruction.value, vars)] });
+          workdirChanged = true;
+          break;
+        case "USER":
+          steps.push({ type: "USER", args: [substitute(instruction.value, vars)] });
+          userChanged = true;
+          break;
+        // CMD / ENTRYPOINT are the start command; the rest are ignored
+        // (BuildPlan rejected what E2B does not support).
+        default:
+          break;
+      }
+    }
+
+    if (!userChanged) steps.push({ type: "USER", args: ["user"] });
+    if (!workdirChanged) steps.push({ type: "WORKDIR", args: ["/home/user"] });
+
+    const argv = BuildPlan.startCommand(plan);
+    return {
+      fromImage,
+      steps,
+      uploads,
+      startCmd: argv === undefined ? undefined : shellCommand(argv),
+    } satisfies LoweredSource;
+  });
+
+export interface PlanSourceOptions {
+  /** Port a `main` program listens on. */
+  readonly port?: number;
+  /** Bootstrap wrapped around an Effect-native `main`. */
+  readonly bootstrap?: (importPath: string) => string;
+  /** `ARG` values. */
+  readonly args?: Readonly<Record<string, string>>;
+  /** Install lines from the program's mount capabilities (`alchemy/Mount`). */
+  readonly install?: ReadonlyArray<string>;
+}
+
+/** Plans an image source with E2B's capabilities and lowers it to E2B steps. */
+export const planSource = (source: ImageSourceProps, options: PlanSourceOptions = {}) =>
+  Effect.gen(function* () {
+    const plan = yield* BuildPlan.plan(source, {
+      capabilities: E2BCapabilities,
+      ...(options.port !== undefined ? { port: options.port } : {}),
+      ...(options.bootstrap !== undefined ? { bootstrap: options.bootstrap } : {}),
+      ...(options.install !== undefined && options.install.length > 0
+        ? { install: options.install }
+        : {}),
+    });
+    for (const warning of plan.warnings) yield* Effect.logDebug(warning);
+    return yield* lowerPlan(plan, { ...plan.args, ...options.args });
+  });

package/src/internal/VolumeHttp.ts

@@ -0,0 +1,88 @@
+/**
+ * The volume-content client over E2B's HTTP API.
+ *
+ * Volume content is authenticated with the volume's own token, which the
+ * control plane returns from `getVolume` (team key). The token is fetched
+ * once per volume on first use and kept for the life of the runtime; a failed
+ * lookup is not cached, so the next call retries it.
+ */
+import { volumeConnectionFor } from "@distilled.cloud/e2b";
+import type { VolumeConnection } from "@distilled.cloud/e2b/Credentials";
+import * as volumeContent from "@distilled.cloud/e2b/volume_content";
+import * as volumes from "@distilled.cloud/e2b/volumes";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import type * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import type { E2BAuth } from "../E2BBindings.ts";
+import type { ReadWriteVolumeClient } from "../VolumeFiles.ts";
+
+const decoder = new TextDecoder();
+
+/** The volume-token connection plus an HTTP client: what volume-content calls need. */
+type VolumeLayer = Layer.Layer<VolumeConnection | HttpClient.HttpClient>;
+
+export const makeVolumeFiles = (
+  auth: E2BAuth,
+  volumeIdOf: Effect.Effect<string>,
+): ReadWriteVolumeClient => {
+  let cached: { readonly volumeId: string; readonly layer: VolumeLayer } | undefined;
+  /** The volume-token connection, looked up once. */
+  const connection = Effect.suspend(() =>
+    cached !== undefined
+      ? Effect.succeed(cached)
+      : Effect.flatMap(volumeIdOf, (volumeId) =>
+          auth.authorize(volumes.getVolume({ volumeID: volumeId })).pipe(
+            Effect.map((volume) => {
+              cached = {
+                volumeId,
+                layer: Layer.mergeAll(volumeConnectionFor(volume), FetchHttpClient.layer),
+              };
+              return cached;
+            }),
+          ),
+        ),
+  );
+  /** Runs a volume-content call, given the volume id, with the volume's token. */
+  const inVolume = <A, E>(
+    call: (volumeID: string) => Effect.Effect<A, E, Layer.Success<VolumeLayer>>,
+  ) =>
+    Effect.flatMap(connection, ({ volumeId, layer }) => call(volumeId).pipe(Effect.provide(layer)));
+
+  return {
+    read: (path) => inVolume((volumeID) => volumeContent.readVolumeFile({ volumeID, path })),
+    readText: (path) =>
+      inVolume((volumeID) => volumeContent.readVolumeFile({ volumeID, path })).pipe(
+        Effect.map((bytes) => decoder.decode(bytes)),
+      ),
+    list: (path, options) =>
+      inVolume((volumeID) =>
+        volumeContent.listVolumeDir({
+          volumeID,
+          path,
+          ...(options?.depth === undefined ? {} : { depth: options.depth }),
+        }),
+      ),
+    stat: (path) => inVolume((volumeID) => volumeContent.statVolumePath({ volumeID, path })),
+    exists: (path) =>
+      inVolume((volumeID) => volumeContent.statVolumePath({ volumeID, path })).pipe(
+        Effect.as(true),
+        Effect.catchTag("NotFound", () => Effect.succeed(false)),
+      ),
+    write: (path, data, options) =>
+      inVolume((volumeID) =>
+        volumeContent.writeVolumeFile({ volumeID, path, body: data, force: true, ...options }),
+      ),
+    makeDir: (path, options) =>
+      inVolume((volumeID) =>
+        volumeContent.makeVolumeDir({ volumeID, path, force: true, ...options }),
+      ),
+    chmod: (path, options) =>
+      inVolume((volumeID) => volumeContent.updateVolumePath({ volumeID, path, ...options })),
+    remove: (path) =>
+      inVolume((volumeID) => volumeContent.removeVolumePath({ volumeID, path })).pipe(
+        Effect.asVoid,
+        Effect.catchTag("NotFound", () => Effect.void),
+      ),
+  };
+};