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

package/src/FunctionTarget.ts

@@ -0,0 +1,181 @@
+import {
+  serializeClassParameters,
+  type ClassParameterValue,
+} from "@distilled.cloud/modal/ClassParameters";
+import * as functions from "@distilled.cloud/modal/functions";
+import type { Input } from "alchemy/Input";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { environmentOf, type ErrorOf, type OpError, operations } from "./internal.ts";
+import type { OperationServices } from "./internal.ts";
+import type { FunctionRef, FunctionTarget } from "./InvokeFunction.ts";
+import * as ModalBindings from "./ModalBindings.ts";
+
+/*
+ * Shared scaffolding for bindings on a function (a `Modal.Function` or
+ * `Modal.Server` of the Stack, or a deployed function by name). NOT exported
+ * from `index.ts`.
+ */
+
+export const isFunctionRef = (target: unknown): target is FunctionRef =>
+  typeof target === "object" &&
+  target !== null &&
+  typeof (target as FunctionRef).app === "string" &&
+  typeof (target as FunctionRef).function === "string";
+
+/** A resolved target: its function id (looked up once) and the class method, if any. */
+export interface ResolvedFunction {
+  readonly functionId: Effect.Effect<string, FunctionLookupError>;
+  readonly method: string | undefined;
+}
+
+/** A parameter value missing from a parameterized class call. */
+export class FunctionParameterMissing extends Data.TaggedError("Modal.FunctionParameterMissing")<{
+  readonly message: string;
+}> {}
+
+const PARAM_TYPE = {
+  string: "PARAM_TYPE_STRING",
+  number: "PARAM_TYPE_INT",
+  boolean: "PARAM_TYPE_BOOL",
+  bytes: "PARAM_TYPE_BYTES",
+} as const;
+
+/**
+ * Serialize class parameters as Modal's `ClassParameterSet`, in the class's
+ * schema order with its defaults applied, as Modal's clients do: the bytes
+ * identify the bound function.
+ */
+const serializeParameters = Effect.fn(function* (
+  schema: ReadonlyArray<functions.ClassParameterSpec>,
+  values: Record<string, string | number | boolean | Uint8Array>,
+) {
+  const parameters: Array<ClassParameterValue> = [];
+  for (const spec of schema) {
+    const name = spec.name ?? "";
+    const value = values[name];
+    if (value === undefined) {
+      if (!spec.hasDefault) {
+        return yield* new FunctionParameterMissing({ message: `Missing class parameter ${name}` });
+      }
+      parameters.push({
+        name,
+        type: spec.type ?? "PARAM_TYPE_UNSPECIFIED",
+        stringValue: spec.stringDefault,
+        intValue: spec.intDefault,
+        bytesValue: spec.bytesDefault,
+        boolValue: spec.boolDefault,
+      });
+      continue;
+    }
+    parameters.push(
+      typeof value === "string"
+        ? { name, type: PARAM_TYPE.string, stringValue: value }
+        : typeof value === "number"
+          ? { name, type: PARAM_TYPE.number, intValue: String(Math.trunc(value)) }
+          : typeof value === "boolean"
+            ? { name, type: PARAM_TYPE.boolean, boolValue: value }
+            : {
+                name,
+                type: PARAM_TYPE.bytes,
+                bytesValue: Buffer.from(value).toString("base64"),
+              },
+    );
+  }
+  return yield* Effect.sync(() => serializeClassParameters(parameters));
+});
+
+/**
+ * Resolve a target in the construction phase. A resource of the Stack
+ * carries its id; a name is looked up on first use and cached (the id only
+ * changes when the App is redeployed).
+ */
+/** The operations that look a function up by name, resolved by `ModalBindings.withCredentials`. */
+export const FunctionLookupOps = operations({
+  get: functions.getFunction,
+  bindParams: functions.functionBindParams,
+});
+
+export type FunctionLookupOps = Effect.Success<typeof FunctionLookupOps>;
+
+/** Looking a function up by name (and binding a class's parameters). */
+export type FunctionLookupError =
+  | OpError<FunctionLookupOps, "get" | "bindParams">
+  | ErrorOf<typeof serializeParameters>;
+
+export const resolveFunction = Effect.fn(function* (
+  lookup: FunctionLookupOps,
+  target: FunctionTarget | { readonly functionId: unknown },
+) {
+  if (!isFunctionRef(target)) {
+    const functionId = yield* (
+      target as { readonly functionId: Effect.Effect<Effect.Effect<string>> }
+    ).functionId;
+    return { functionId, method: undefined } satisfies ResolvedFunction;
+  }
+  const [tag, method] = target.function.includes(".")
+    ? [`${target.function.split(".")[0]}.*`, target.function.split(".").slice(1).join(".")]
+    : [target.function, undefined];
+  let cached: string | undefined;
+  const functionId = Effect.suspend(() =>
+    cached !== undefined
+      ? Effect.succeed(cached)
+      : Effect.gen(function* () {
+          const environmentName = environmentOf(target.environment);
+          const found = yield* lookup.get({
+            appName: target.app,
+            objectTag: tag,
+            environmentName,
+          });
+          let id = found.functionId ?? "";
+          // A parameterized class runs a bound function per parameter set.
+          if (target.parameters !== undefined) {
+            const schema = found.handleMetadata?.classParameterInfo?.schema ?? [];
+            const serializedParams = yield* serializeParameters(schema, target.parameters);
+            const bound = yield* lookup.bindParams({
+              functionId: id,
+              serializedParams,
+              environmentName,
+            });
+            id = bound.boundFunctionId ?? id;
+          }
+          cached = id;
+          return id;
+        }),
+  );
+  return { functionId, method } satisfies ResolvedFunction;
+});
+
+/**
+ * A binding layer over a function target: grants the host's identity `role`
+ * on the function's environment (deploy only), resolves the target, and
+ * builds the client over `operations`.
+ */
+export const makeFunctionBinding = <Target, Ops, Client>(options: {
+  readonly tag: string;
+  readonly operations: Effect.Effect<Ops, never, OperationServices>;
+  readonly role: ModalBindings.EnvironmentGrant["role"];
+  readonly make: (resolved: ResolvedFunction, ops: Ops, target: Target) => Effect.Effect<Client>;
+}) =>
+  Effect.gen(function* () {
+    const lookup = yield* ModalBindings.withCredentials(FunctionLookupOps);
+    const ops = yield* ModalBindings.withCredentials(options.operations);
+    const bind = yield* ModalBindings.Bind;
+    return Effect.fn(options.tag)(function* (target: Target) {
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        if (isFunctionRef(target)) {
+          yield* bind`${options.tag}`({
+            roles: [{ environment: target.environment, role: options.role }],
+          });
+        } else {
+          const environment = (target as { readonly environment: Input<string | undefined> })
+            .environment;
+          yield* bind`${options.tag}(${target})`({
+            roles: [{ environment, role: options.role }],
+          });
+        }
+      }
+      const resolved = yield* resolveFunction(lookup, target as FunctionTarget);
+      return yield* options.make(resolved, ops, target);
+    });
+  });

package/src/Image.ts

@@ -0,0 +1,281 @@
+import * as BuildPlan from "@alchemy.run/docker/BuildPlan";
+import type { InlineDockerfile } from "@alchemy.run/docker/Dockerfile";
+import * as image from "@distilled.cloud/modal/image";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { sha256Object } from "alchemy/Util/sha256";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { buildImage, ImageBuildOps, type ImageBuildSpec } from "./ImageBuild.ts";
+import { checkCommands, lowerPlan, MODAL_CAPABILITIES } from "./ImagePlan.ts";
+import { declarable } from "./internal/Declared.ts";
+import type { Providers } from "./Providers.ts";
+import { createSandbox, SandboxOps } from "./SandboxClient.ts";
+
+/** A `run` command of a warm-base image exited non-zero. */
+export class ImageSetupFailed extends Data.TaggedError("Modal.ImageSetupFailed")<{
+  readonly command: string;
+  readonly exitCode: number;
+  readonly message: string;
+}> {}
+
+export interface ImageProps {
+  /** The App the image is built in (`Modal.App`). Images are cached per workspace. */
+  app: { readonly appId: string; readonly name?: string; readonly environment?: string };
+  /**
+   * Start from a registry image (`node:22-slim`, `ghcr.io/org/base:1`).
+   * Exclusive with {@link dockerfile} and {@link from}.
+   */
+  image?: string;
+  /**
+   * Build from a Dockerfile: a path, or inline content
+   * (`Dockerfile.inline\`…\``). Modal's builder runs it, not Docker: a
+   * multi-stage build, BuildKit mounts, heredocs, `EXPOSE`, `HEALTHCHECK`,
+   * `LABEL`, `ONBUILD`, `STOPSIGNAL` and `VOLUME` fail at plan; `USER` is
+   * ignored (containers run as root) with a warning.
+   */
+  dockerfile?: string | InlineDockerfile;
+  /** Build context for the Dockerfile's COPY/ADD sources. */
+  context?: string;
+  /** Start from another `Modal.Image` (a warm base built on a base). */
+  from?: { readonly imageId: string };
+  /** Dockerfile lines appended to the build (`"RUN pip install pandas"`). */
+  commands?: string[];
+  /**
+   * Shell commands run in a sandbox booted from the built image; its
+   * filesystem is then snapshotted into this image. Use it for setup that
+   * needs network or secrets at runtime (cloning a repo, installing
+   * dependencies), the deploy-time warm base sandboxes fork from.
+   */
+  run?: string[];
+  /** Secrets the build (and `run`) sees as environment variables. */
+  secrets?: Array<{ readonly secretId: string }>;
+  /** Pull a private base image with credentials stored in a `Modal.Secret`. */
+  registry?: {
+    readonly type: "aws" | "gcp" | "static";
+    readonly secret: { readonly secretId: string };
+  };
+  /** Run build steps on a GPU (`"A10G"`, `"H100"`). */
+  gpu?: string;
+  /** Pin Modal's image builder version (`"2025.06"`). */
+  builderVersion?: string;
+  /**
+   * Publish the image under this tag in its app's environment, so code
+   * outside the Stack finds it with `images.fromTag(tag)` or
+   * `modal.Image.from_tag`.
+   */
+  tag?: string;
+}
+
+export interface ImageAttributes {
+  /** Image ID (`im-…`): pass it as `image` when creating sandboxes. */
+  imageId: string;
+  /** The App the image was built in; `CreateSandbox(image)` creates sandboxes there. */
+  appId: string;
+  /** Name of that App (for finding its sandboxes by name). */
+  appName: string | undefined;
+  /** Environment of that App. */
+  environment: string | undefined;
+  /** Content hash of the build inputs; a change rebuilds. */
+  hash: string;
+}
+
+/**
+ * A Modal Image: a container image built by Modal's own builder (not
+ * Docker), from a registry image, a Dockerfile, or another Modal Image plus
+ * commands. Sandboxes boot from it.
+ *
+ * With `run`, the image becomes a warm base: Alchemy boots a sandbox from the
+ * built image, runs the commands, snapshots its filesystem, and terminates
+ * it. Sandboxes created from the result start with the repo cloned and
+ * dependencies installed. Runtime snapshots (`sandbox.snapshotFilesystem()`)
+ * are images too and work anywhere an image does.
+ *
+ * Modal builds remotely: deploying needs no local Docker.
+ *
+ * ### Building an Image
+ * **Example:** From a registry image with extra packages
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Coder = Modal.App("Coder", {});
+ * export const Node = Modal.Image("Node", {
+ *   app: Coder,
+ *   image: "node:22-bookworm",
+ *   commands: ["RUN apt-get update && apt-get install -y git ripgrep"],
+ * });
+ * ```
+ *
+ * **Example:** From an inline Dockerfile
+ * ```typescript
+ * import * as Dockerfile from "@alchemy.run/docker/Dockerfile";
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Coder = Modal.App("Coder", {});
+ * export const Python = Modal.Image("Python", {
+ *   app: Coder,
+ *   dockerfile: Dockerfile.inline`
+ *     FROM python:3.12-slim
+ *     RUN pip install pandas
+ *   `,
+ * });
+ * ```
+ *
+ * ### A warm base to fork from
+ * **Example:** Clone and install once, start every sandbox from it
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Coder = Modal.App("Coder", {});
+ * export const Node = Modal.Image("Node", { app: Coder, image: "node:22-bookworm" });
+ * export const Warm = Modal.Image("Warm", {
+ *   app: Coder,
+ *   from: Node,
+ *   run: [
+ *     "git clone https://github.com/alchemy-run/alchemy /work",
+ *     "cd /work && corepack enable && pnpm install",
+ *   ],
+ * });
+ * ```
+ *
+ * @resource
+ * @product Image
+ */
+export const Image = declarable<Image>()(Resource<Image>("Modal.Image"));
+
+export type Image = Resource<"Modal.Image", ImageProps, ImageAttributes, never, Providers>;
+
+const idOf = <K extends string>(value: unknown, key: K): string | undefined =>
+  typeof value === "object" && value !== null && key in value
+    ? ((value as Record<K, unknown>)[key] as string | undefined)
+    : undefined;
+
+/** The build spec for an Image's props (Dockerfile lowered, context collected). */
+/**
+ * Plan an Image's build with the shared {@link BuildPlan}: its environment
+ * (`image`, `dockerfile`/`context`, or a Modal base via `from`) checked
+ * against what Modal's builder runs, then the `commands` appended.
+ */
+const planOf = Effect.fn(function* (news: ImageProps) {
+  const fromId = idOf(news.from, "imageId");
+  const source =
+    fromId !== undefined
+      ? { dockerfile: { content: "FROM base\n" } }
+      : news.dockerfile !== undefined || news.context !== undefined
+        ? { dockerfile: news.dockerfile, context: news.context }
+        : { image: news.image ?? "debian:bookworm-slim" };
+  const plan = yield* BuildPlan.plan(source, { capabilities: MODAL_CAPABILITIES });
+  const extra = yield* checkCommands(news.commands ?? []);
+  const lowered = yield* lowerPlan(plan, extra);
+  const spec: ImageBuildSpec = {
+    ...lowered,
+    // `FROM base` names the Modal image passed as a base image.
+    ...(fromId !== undefined ? { baseImageId: fromId, commands: lowered.commands.slice(1) } : {}),
+    secretIds: (news.secrets ?? []).flatMap((s) => idOf(s, "secretId") ?? []),
+    registry: news.registry
+      ? { authType: news.registry.type, secretId: idOf(news.registry.secret, "secretId") ?? "" }
+      : undefined,
+    gpu: news.gpu,
+    builderVersion: news.builderVersion,
+  };
+  const hash = yield* sha256Object({
+    plan: plan.hash,
+    from: fromId,
+    extra,
+    secrets: spec.secretIds,
+    registry: spec.registry,
+    gpu: spec.gpu,
+    builder: spec.builderVersion,
+    // `tag` and `run` happen after the build; part of the hash so a change re-runs reconcile.
+    tag: news.tag,
+    run: news.run,
+  });
+  return { spec, hash, warnings: plan.warnings };
+});
+
+export const ImageProvider = () =>
+  Provider.effect(
+    Image,
+    Effect.gen(function* () {
+      return {
+        stables: [],
+        diff: Effect.fn(function* ({ news, output }) {
+          if (!isResolved(news) || output === undefined) return undefined;
+          // A changed build input (including files under `context`) is a new image.
+          const { hash } = yield* planOf(news);
+          return hash !== output.hash ? ({ action: "update" } as const) : undefined;
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (output === undefined) return undefined;
+          const found = yield* image
+            .imageFromId({ imageId: output.imageId })
+            .pipe(Effect.catchTag("ImageNotFound", () => Effect.undefined));
+          return found?.imageId ? output : undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, output, session }) {
+          const appId = idOf(news.app, "appId") ?? "";
+          const { spec, hash, warnings } = yield* planOf(news);
+          for (const warning of warnings) yield* session.note(warning);
+          // Observe: an image built from the same inputs still exists.
+          if (output !== undefined && output.hash === hash && output.appId === appId) {
+            const found = yield* image
+              .imageFromId({ imageId: output.imageId })
+              .pipe(Effect.catchTag("ImageNotFound", () => Effect.undefined));
+            if (found?.imageId) return output;
+          }
+          // Ensure: Modal content-addresses builds, so this is a no-op for
+          // inputs it has built before.
+          let imageId = yield* buildImage(yield* ImageBuildOps, appId, spec, {
+            note: session.note,
+          });
+          // Warm base: run setup in a sandbox and snapshot its filesystem.
+          if (news.run && news.run.length > 0) {
+            yield* session.note(`Running setup for image ${imageId}...`);
+            const box = yield* createSandbox(
+              yield* SandboxOps,
+              { appId },
+              {
+                image: { imageId },
+                secrets: spec.secretIds?.map((secretId) => ({ secretId })),
+                timeout: "1 hour",
+              },
+            );
+            const snapshot = yield* Effect.gen(function* () {
+              for (const command of news.run ?? []) {
+                const result = yield* box.exec(["sh", "-lc", command]);
+                if (result.exitCode !== 0) {
+                  return yield* new ImageSetupFailed({
+                    command,
+                    exitCode: result.exitCode,
+                    message: `\`${command}\` exited ${result.exitCode}: ${result.stderr.slice(-2000)}`,
+                  });
+                }
+              }
+              return yield* box.snapshotFilesystem("5 minutes");
+            }).pipe(Effect.ensuring(Effect.ignore(box.terminate())));
+            imageId = snapshot.imageId;
+          }
+          if (news.tag !== undefined) {
+            yield* image.publishImage({
+              imageId,
+              tag: news.tag,
+              environmentName: idOf(news.app, "environment") ?? "",
+            });
+          }
+          return {
+            imageId,
+            appId,
+            appName: idOf(news.app, "name"),
+            environment: idOf(news.app, "environment"),
+            hash,
+          };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* image
+            .deleteImage({ imageId: output.imageId })
+            .pipe(Effect.catchTag("ImageNotFound", () => Effect.void));
+        }),
+      };
+    }),
+  );

package/src/ImageBuild.ts

@@ -0,0 +1,228 @@
+import { createHash } from "node:crypto";
+import * as image from "@distilled.cloud/modal/image";
+import * as mount from "@distilled.cloud/modal/mount";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { BlobOps, MAX_INLINE_BYTES, uploadBlob } from "./Blob.ts";
+import { operations } from "./internal.ts";
+
+/** Modal's builder finished the image build with a failure. */
+export class ImageBuildFailed extends Data.TaggedError("Modal.ImageBuildFailed")<{
+  readonly imageId: string;
+  readonly status: string;
+  readonly message: string;
+  /** The last lines the build printed. */
+  readonly logs: string;
+}> {}
+
+/** The build didn't finish within its time budget. */
+export class ImageBuildTimeout extends Data.TaggedError("Modal.ImageBuildTimeout")<{
+  readonly imageId: string;
+  readonly message: string;
+}> {}
+
+/** What an image is built from, after Dockerfile lowering. */
+export interface ImageBuildSpec {
+  /** A registry image to start from (`FROM <ref>`). */
+  readonly dockerTag?: string;
+  /** A Modal image to start from. */
+  readonly baseImageId?: string;
+  /**
+   * Dockerfile commands. With `dockerTag`/`baseImageId` they follow the
+   * generated `FROM`; otherwise they are a whole Dockerfile.
+   */
+  readonly commands: ReadonlyArray<string>;
+  /**
+   * Files the commands `COPY`, by context-relative path. They are uploaded
+   * as a mount owned by the app, so their size isn't limited by Modal's
+   * 2 MB cap on an image definition.
+   */
+  readonly contextFiles?: ReadonlyArray<{
+    readonly filename: string;
+    readonly data: Uint8Array;
+    /** Permission bits. @default 0o644 */
+    readonly mode?: number;
+  }>;
+  /**
+   * A mount whose files the commands `COPY` (e.g. Modal's standalone
+   * Python). Not combined with {@link contextFiles}.
+   */
+  readonly contextMountId?: string;
+  /** Build arguments (`ARG` values). */
+  readonly buildArgs?: Readonly<Record<string, string>>;
+  /** Secrets (ids) the build steps see as environment variables. */
+  readonly secretIds?: ReadonlyArray<string>;
+  /** Credentials to pull a private base image. */
+  readonly registry?: {
+    readonly authType: "aws" | "gcp" | "static";
+    readonly secretId: string;
+  };
+  /** Run the build on a GPU (`"A10G"`, `"H100"`, ...). */
+  readonly gpu?: string;
+  readonly builderVersion?: string;
+  readonly forceBuild?: boolean;
+}
+
+const AUTH_TYPE = {
+  aws: "REGISTRY_AUTH_TYPE_AWS",
+  gcp: "REGISTRY_AUTH_TYPE_GCP",
+  static: "REGISTRY_AUTH_TYPE_STATIC_CREDS",
+} as const;
+
+/** A `"A100-80GB:2"`-style GPU spec as Modal's `GPUConfig`. */
+export const gpuConfig = (gpu: string | undefined): image.GPUConfig | undefined => {
+  if (gpu === undefined) return undefined;
+  const [type, count] = gpu.split(":");
+  return { gpuType: type!.toUpperCase(), count: count ? Number(count) : 1 };
+};
+
+/** The operations a build needs, resolved by `ModalBindings.withCredentials` (or at deploy). */
+export const ImageBuildOps = operations({
+  getOrCreate: image.imageGetOrCreate,
+  joinStreaming: image.imageJoinStreaming,
+  putFile: mount.mountPutFile,
+  getOrCreateMount: mount.mountGetOrCreate,
+  blobs: BlobOps,
+});
+
+export type ImageBuildOps = Effect.Success<typeof ImageBuildOps>;
+
+/** Modal returned a response without a field the build needs. */
+export class ImageBuildUnexpectedResponse extends Data.TaggedError(
+  "Modal.ImageBuildUnexpectedResponse",
+)<{
+  readonly message: string;
+}> {}
+
+/**
+ * Upload build context files as a mount owned by the app, the way Modal's
+ * clients send `COPY` sources. Modal stores files by content hash, so
+ * unchanged files are not sent again.
+ */
+const contextMount = Effect.fn(function* (
+  ops: ImageBuildOps,
+  appId: string,
+  files: NonNullable<ImageBuildSpec["contextFiles"]>,
+) {
+  const entries = [];
+  for (const file of files) {
+    const sha256Hex = yield* Effect.sync(() =>
+      createHash("sha256").update(file.data).digest("hex"),
+    );
+    const known = yield* ops.putFile({ sha256Hex });
+    if (!known.exists) {
+      const upload =
+        file.data.length > MAX_INLINE_BYTES
+          ? { dataBlobId: yield* uploadBlob(ops.blobs, file.data) }
+          : { data: yield* Effect.sync(() => Buffer.from(file.data).toString("base64")) };
+      const put = yield* ops.putFile({ sha256Hex, ...upload });
+      if (!put.exists) {
+        return yield* new ImageBuildUnexpectedResponse({
+          message: `Modal didn't store build context file ${file.filename}`,
+        });
+      }
+    }
+    entries.push({
+      filename: `/${file.filename.replace(/^\/+/, "")}`,
+      sha256Hex,
+      size: String(file.data.length),
+      mode: 0o100000 | ((file.mode ?? 0o644) & 0o7777),
+    });
+  }
+  const { mountId } = yield* ops.getOrCreateMount({
+    objectCreationType: "OBJECT_CREATION_TYPE_ANONYMOUS_OWNED_BY_APP",
+    appId,
+    files: entries,
+  });
+  if (!mountId) {
+    return yield* new ImageBuildUnexpectedResponse({
+      message: "Modal returned no id for the build context mount",
+    });
+  }
+  return mountId;
+});
+
+const FINISHED = (status: string | undefined) =>
+  status !== undefined && status !== "GENERIC_STATUS_UNSPECIFIED";
+
+/**
+ * Build (or reuse) an image with Modal's builder and wait until it is ready.
+ * Modal content-addresses images, so the same spec returns the same image
+ * without rebuilding. Fails with {@link ImageBuildFailed} on a failed build.
+ */
+export const buildImage = Effect.fn(function* (
+  ops: ImageBuildOps,
+  appId: string,
+  spec: ImageBuildSpec,
+  options: { readonly note?: (message: string) => Effect.Effect<void> } = {},
+) {
+  const from = spec.baseImageId
+    ? { baseImages: [{ imageId: spec.baseImageId, dockerTag: "base" }], first: ["FROM base"] }
+    : spec.dockerTag
+      ? { baseImages: [], first: [`FROM ${spec.dockerTag}`] }
+      : { baseImages: [], first: [] as string[] };
+  const contextMountId =
+    spec.contextFiles !== undefined && spec.contextFiles.length > 0
+      ? yield* contextMount(ops, appId, spec.contextFiles)
+      : spec.contextMountId;
+  const created = yield* ops.getOrCreate({
+    appId,
+    image: {
+      baseImages: from.baseImages,
+      dockerfileCommands: [...from.first, ...spec.commands],
+      contextMountId,
+      secretIds: spec.secretIds ? [...spec.secretIds] : undefined,
+      imageRegistryConfig: spec.registry
+        ? { registryAuthType: AUTH_TYPE[spec.registry.authType], secretId: spec.registry.secretId }
+        : undefined,
+      gpuConfig: gpuConfig(spec.gpu),
+      buildArgs: spec.buildArgs ? { ...spec.buildArgs } : undefined,
+    },
+    builderVersion: spec.builderVersion,
+    forceBuild: spec.forceBuild,
+  });
+  const imageId = created.imageId;
+  if (!imageId) {
+    return yield* new ImageBuildFailed({
+      imageId: "",
+      status: "GENERIC_STATUS_UNSPECIFIED",
+      message: "Modal returned no image id",
+      logs: "",
+    });
+  }
+  let result = created.result;
+  let lastEntryId: string | undefined;
+  const logs: string[] = [];
+  // Each join call streams build logs for up to ~55 s; a build may take many.
+  for (let attempt = 0; !FINISHED(result?.status) && attempt < 60; attempt++) {
+    if (attempt === 0 && options.note) yield* options.note(`Building image ${imageId}...`);
+    const { items } = yield* ops.joinStreaming({
+      imageId,
+      timeout: 55,
+      lastEntryId,
+      includeLogsForFinished: true,
+    });
+    for (const item of items) {
+      if (item.entryId) lastEntryId = item.entryId;
+      for (const log of item.taskLogs ?? []) {
+        if (log.data) logs.push(log.data);
+      }
+      if (FINISHED(item.result?.status)) result = item.result;
+    }
+  }
+  if (!FINISHED(result?.status)) {
+    return yield* new ImageBuildTimeout({
+      imageId,
+      message: `Modal image ${imageId} was still building after 55 minutes`,
+    });
+  }
+  if (result?.status !== "GENERIC_STATUS_SUCCESS") {
+    return yield* new ImageBuildFailed({
+      imageId,
+      status: result?.status ?? "GENERIC_STATUS_UNSPECIFIED",
+      message: result?.exception || `Modal image build ${imageId} ended with ${result?.status}`,
+      logs: logs.join("").split("\n").slice(-40).join("\n"),
+    });
+  }
+  return imageId;
+});