@lunora/container 1.0.0-alpha.8 → 1.0.0-alpha.80

package/dist/index.d.mts

@@ -1,17 +1,131 @@
-import { C as ContainerConfig, a as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/types.d-BlNwNY44.mjs";
-export type { B as BuildImageSource, c as ContainerInstanceType, d as ContainerReadinessCheck, e as ContainerRollout, f as CustomContainerInstanceType, g as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/types.d-BlNwNY44.mjs";
-/** Options for explicitly starting an instance (mirrors `@cloudflare/containers`). */
+import { a as ContainerSpawnOptions, b as ContainerSnapshot, c as ContainerProcess, d as ContainerRuntimeInstanceType, e as ContainerSpawnRequest, S as SpawnResult, D as DurableObjectJurisdiction, f as DefaultScheduledContainerConfig, g as DurableObjectScheduledContainerConfig, C as ContainerDefinition, h as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-BwpauCoI.mjs";
+export type { B as BuildImageSource, i as ContainerBackupStorage, j as ContainerConfig, k as ContainerConfigBase, l as ContainerInstanceType, m as ContainerNamedImageSource, n as ContainerReadinessCheck, o as ContainerRollout, p as CustomContainerInstanceType, q as NamedContainerInstanceType, R as RegistryImageSource } from "./packem_shared/jurisdiction.d-BwpauCoI.mjs";
+import { b as ContainerBackupOptions, C as ContainerFileOptions, c as ContainerMountRequest, a as ContainerFileContent, d as ContainerSandboxControls } from "./packem_shared/sandbox-types.d-DXlHnsEg.mjs";
+export type { e as ContainerFiles, f as ContainerMountCredentials } from "./packem_shared/sandbox-types.d-DXlHnsEg.mjs";
+import { DirectoryBackupRecord, S3MountInspection, SandboxDirectoryEntry, SandboxFileStat } from '@cloudflare/sandbox';
+export type { DirectoryBackupRecord, S3MountInspection, SandboxDirectoryEntry, SandboxFileStat } from '@cloudflare/sandbox';
+/**
+ * Per-call options for `ContainerHandle.exec`.
+ */
+interface ContainerExecOptions {
+  /** Arguments passed to `command`, unshelled — the container must not concatenate them into a shell string. */
+  args?: ReadonlyArray<string>;
+  /** Working directory for the command, relative to the container's own root. */
+  cwd?: string;
+  /** Extra environment for this command only, merged over the container's env. */
+  env?: Readonly<Record<string, string>>;
+  /**
+   * Cap on the response body, in bytes. The whole `{code,stdout,stderr}`
+   * document has to be held in memory to be parsed, and a build box or job
+   * runner routinely writes tens of megabytes — a single unbounded `exec`
+   * that returns more than the isolate's memory limit kills the isolate and
+   * every other in-flight request sharing it, not just this call. So a
+   * runner that overruns the cap fails the call loudly rather than taking
+   * the shard down with it; raise this (or have the runner cap its own
+   * output) when a command legitimately produces more.
+   *
+   * Default {@link DEFAULT_EXEC_MAX_OUTPUT_BYTES} (1MB).
+   */
+  maxOutputBytes?: number;
+  /**
+   * Abort the call. Composed with {@link ContainerExecOptions.timeoutMs} when
+   * both are given — whichever fires first wins.
+   */
+  signal?: AbortSignal;
+  /**
+   * Give up after this many ms. Covers the whole call — the request *and*
+   * reading the response body, since `fetch` resolves on headers and a
+   * runner that answers `200` and then stalls mid-body would otherwise sit
+   * past the deadline. Sent to the container as well, so a well-behaved
+   * runner can kill the process rather than leak it when the caller walks
+   * away.
+   */
+  timeoutMs?: number;
+}
+/**
+ * The outcome of a `ContainerHandle.exec` call.
+ *
+ * A non-zero `code` is **not** an error: a command that ran and failed is a
+ * result, and the caller decides what to do with it. Only a failure to *run*
+ * the command — transport, a non-2xx from the runner, an unparseable body —
+ * throws.
+ */
+interface ContainerExecResult {
+  /** Process exit code. Non-zero means the command ran and failed. */
+  code: number;
+  /** Everything the command wrote to stderr. */
+  stderr: string;
+  /** Everything the command wrote to stdout. */
+  stdout: string;
+}
+/**
+ * The route `ContainerHandle.exec` POSTs to. Namespaced under
+ * `/__lunora/` so it cannot collide with an application route the container
+ * already serves — the previous ad-hoc convention was a bare `/exec`, which an
+ * app could plausibly own for its own purposes.
+ *
+ * Exported because it is a *contract*, not an implementation detail: a
+ * container image has to serve exactly this route, and `@lunora/agent`'s
+ * human-in-the-loop gate has to recognise it. Both had it hard-coded as a
+ * second literal, which drifts silently — and on the gate's side, drift
+ * un-gates model-chosen command execution.
+ */
+declare const CONTAINER_EXEC_PATH = "/__lunora/exec";
+/** Options for `handle.terminal()`. */
+interface ContainerTerminalOptions extends Omit<ContainerSpawnOptions, "pty" | "signal" | "stdin"> {
+  /** Initial size. Defaults to the request's `?cols=&rows=` search params, else `80×24`. */
+  cols?: number;
+  /** The program to run. Defaults to `"sh"`. */
+  command?: string;
+  /** Initial size. Defaults to the request's `?cols=&rows=` search params, else `80×24`. */
+  rows?: number;
+}
+/**
+ * Options for explicitly starting an instance (mirrors `@cloudflare/containers`).
+ */
 interface ContainerStartOptions {
   /** Override outbound internet access for this start. */
   enableInternet?: boolean;
   /** Override the container entrypoint. */
   entrypoint?: string[];
-  /** Per-instance environment, merged over the definition's `env`/secrets. */
+  /**
+   * Per-instance environment. REPLACES the definition's `env`, `secrets` and
+   * `secretsStore` (the Secrets Store is not read), so pass every variable the
+   * container needs. It is persisted for the instance: every later start —
+   * including the implicit restart a `fetch`/`exec` triggers after the
+   * container slept, crashed or hit `hardTimeout` — uses it, until
+   * `destroy()`. The override cannot change while the container is running
+   * or still starting: a start whose `envVars` differ is rejected with
+   * `CONFLICT` in either case, so `stop()` it (and let any start in flight
+   * finish) first. So
+   * `start({ envVars: {} })` is a sandbox without the declared credentials,
+   * for as long as the instance exists.
+   */
   envVars?: Record<string, string>;
+  /**
+   * The image to start (`schedulingPolicy: "durable_object"` only): a key of
+   * the definition's `images`, or a Cloudflare-managed `"cloudflare/…"` image.
+   * Persisted like `envVars`, so the implicit restart after a sleep boots the
+   * same image. Mutually exclusive with `snapshot`.
+   */
+  image?: string;
+  /**
+   * The instance size (`schedulingPolicy: "durable_object"` only). Persisted
+   * with `image`; defaults to the definition's `instanceType`, else `"lite"`.
+   */
+  instanceType?: ContainerRuntimeInstanceType;
   /** Metadata labels attached for metrics/observability. */
   labels?: Record<string, string>;
+  /**
+   * Restore a filesystem saved by `snapshot()` instead of starting from an
+   * image (`schedulingPolicy: "durable_object"` only). Applies to this start
+   * only — a later restart after a sleep boots the image again.
+   */
+  snapshot?: ContainerSnapshot;
 }
-/** A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time. */
+/**
+ * A container instance's runtime state, as returned by `getState()`. Structural — the platform adds fields over time.
+ */
 interface ContainerInstanceState {
   [key: string]: unknown;
   /** Process exit code, present once the instance has `stopped_with_code`. */
@@ -28,6 +142,34 @@ interface ContainerStubLike {
   destroy?: () => Promise<void>;
   fetch: (input: Request) => Promise<Response>;
   getState?: () => Promise<ContainerInstanceState>;
+  lunoraBackup?: (directory: string, options?: ContainerBackupOptions) => Promise<DirectoryBackupRecord>;
+  lunoraDeleteBackup?: (backup: DirectoryBackupRecord) => Promise<void>;
+  /** The container DO's exec entry (`LunoraContainer.lunoraExec`), the only way a request reaches `/__lunora/exec`. */
+  lunoraExec?: (request: Request) => Promise<Response>;
+  lunoraInspectMount?: (path: string) => Promise<S3MountInspection>;
+  lunoraMkdir?: (path: string, options?: ContainerFileOptions & {
+    recursive?: boolean;
+  }) => Promise<void>;
+  lunoraMount?: (request: ContainerMountRequest) => Promise<void>;
+  lunoraReadDirectory?: (path: string, options?: ContainerFileOptions) => Promise<SandboxDirectoryEntry[]>;
+  lunoraReadFile?: (path: string, options?: ContainerFileOptions) => Promise<Response>;
+  lunoraRemove?: (path: string, options?: ContainerFileOptions & {
+    force?: boolean;
+    recursive?: boolean;
+  }) => Promise<void>;
+  lunoraRename?: (source: string, destination: string, options?: ContainerFileOptions) => Promise<void>;
+  lunoraRestore?: (backup: DirectoryBackupRecord, options?: {
+    directory?: string;
+  }) => Promise<void>;
+  /** The container DO's snapshot entry (`LunoraContainer.lunoraSnapshot`). */
+  lunoraSnapshot?: (options?: {
+    name?: string;
+  }) => Promise<ContainerSnapshot>;
+  /** The container DO's streaming-exec entry (`LunoraContainer.lunoraSpawn`). */
+  lunoraSpawn?: (request: ContainerSpawnRequest) => Promise<SpawnResult>;
+  lunoraStat?: (path: string, options?: ContainerFileOptions) => Promise<SandboxFileStat>;
+  lunoraUnmount?: (path: string) => Promise<void>;
+  lunoraWriteFile?: (path: string, content: ContainerFileContent, options?: ContainerFileOptions) => Promise<void>;
   removeAllowedHost?: (hostname: string) => Promise<void>;
   removeDeniedHost?: (hostname: string) => Promise<void>;
   renewActivityTimeout?: () => Promise<void>;
@@ -37,80 +179,126 @@ interface ContainerStubLike {
   stop?: (signal?: number | string) => Promise<void>;
 }
 /**
-* Cloudflare Durable Object data-residency jurisdiction. Widening union —
-* Cloudflare adds values over time.
-* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
-*/
-type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
-/** What the client needs from a Durable Object namespace binding. */
+ * What the client needs from a Durable Object namespace binding.
+ */
 interface ContainerNamespaceLike {
   get: (id: unknown) => ContainerStubLike;
   idFromName: (name: string) => unknown;
   /**
-  * Derive a jurisdiction-restricted subnamespace. Optional because older
-  * workers-types releases (and test doubles) may not expose it.
-  */
+   * Derive a jurisdiction-restricted subnamespace. Optional because older
+   * workers-types releases (and test doubles) may not expose it.
+   */
   jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => ContainerNamespaceLike;
 }
-/** A handle on one container instance (one Durable Object). */
+/**
+ * A handle on one container instance (one Durable Object).
+ */
 interface ContainerHandle {
   /**
-  * Send an HTTP (or WebSocket-upgrade) request to the container. A path
-  * string (`"/transcode"`) is resolved against a synthetic origin; a full
-  * `Request`/URL passes through unchanged.
-  */
+   * Run a command inside the container and return its exit code and output.
+   *
+   * A container is an HTTP server, so there is no platform-level exec to call:
+   * the command is POSTed to `/__lunora/exec` and the container app
+   * serves that route. What this method adds over hand-rolling that fetch is
+   * the **contract** — a pinned path, a typed request and response, and the
+   * distinction between "the command failed" (a `code`) and "the command could
+   * not be run" (a throw). Before it existed every caller invented its own
+   * `/exec` convention and read the raw body back as if it were output, which
+   * silently turned a runner's 500 into a successful-looking result.
+   *
+   * The container side must accept `{ args, command, cwd, env, timeoutMs }`
+   * and answer `{ code, stdout, stderr }` as JSON.
+   */
+  exec: (command: string, options?: ContainerExecOptions) => Promise<ContainerExecResult>;
+  /**
+   * Send an HTTP (or WebSocket-upgrade) request to the container. A path
+   * string (`"/transcode"`) is resolved against a synthetic origin; a full
+   * `Request`/URL passes through unchanged.
+   */
   fetch: (input: Request | string, init?: RequestInit) => Promise<Response>;
   /**
-  * Return a handle that routes every request to `targetPort` on the
-  * container instead of the definition's `defaultPort` — for multi-port
-  * containers (declare the ports in `requiredPorts`). Sets the
-  * `cf-container-target-port` header the way `@cloudflare/containers`'
-  * `switchPort` does, so it composes with `.get()`, `.any()`, and `.pool()`:
-  * `ctx.containers.app.get("u1").port(9090).fetch("/admin")`.
-  */
+   * Return a handle that routes every request to `targetPort` on the
+   * container instead of the definition's `defaultPort` — for multi-port
+   * containers (declare the ports in `requiredPorts`). Sets the
+   * `cf-container-target-port` header the way `@cloudflare/containers`'
+   * `switchPort` does, so it composes with `.get()`, `.any()`, and `.pool()`:
+   * `ctx.containers.app.get("u1").port(9090).fetch("/admin")`.
+   */
   port: (targetPort: number) => ContainerHandle;
 }
 /**
-* A handle on a *named* instance (from `.get(name)`) — `fetch` plus explicit
-* lifecycle control. The per-entity pattern (a sandbox per user, a room per
-* game, a job runner per id) often needs to tear down or inspect the instance
-* rather than wait for `sleepAfter`, so these wrap the container DO's
-* `start`/`stop`/`destroy`/`getState`.
-*/
+ * A handle on a *named* instance (from `.get(name)`) — `fetch` plus explicit
+ * lifecycle control. The per-entity pattern (a sandbox per user, a room per
+ * game, a job runner per id) often needs to tear down or inspect the instance
+ * rather than wait for `sleepAfter`, so these wrap the container DO's
+ * `start`/`stop`/`destroy`/`getState`.
+ */
 interface ContainerInstanceHandle extends ContainerHandle {
   /** Stop and discard the instance (its ephemeral disk is lost). */
   destroy: () => Promise<void>;
   /**
-  * Adjust this instance's egress allow/deny lists at runtime — the dynamic
-  * counterpart to the static `allowedHosts`/`deniedHosts` config. Useful for
-  * per-tenant egress policy. Requires the worker to export `ContainerProxy`
-  * (codegen re-exports it from the generated container file whenever any
-  * container is defined, so the runtime controls always work).
-  */
+   * Adjust this instance's egress allow/deny lists at runtime — the dynamic
+   * counterpart to the static `allowedHosts`/`deniedHosts` config. Useful for
+   * per-tenant egress policy. Requires the worker to export `ContainerProxy`
+   * (codegen re-exports it from the generated container file whenever any
+   * container is defined, so the runtime controls always work).
+   */
   egress: ContainerEgressControls;
   /** Read the instance's current runtime state. */
   getState: () => Promise<ContainerInstanceState>;
   /**
-  * Reset the instance's `sleepAfter` idle timer. The platform renews it on
-  * each proxied request, and because `@lunora/container` proxies WebSocket
-  * frames through the Durable Object, message traffic on an open socket
-  * renews it too (the WebSocket-keepalive gap of cloudflare/containers#147 is
-  * closed in the bundled base). This manual control is the escape hatch for
-  * keeping a container awake during activity that is neither an HTTP request
-  * nor a WS message — e.g. a long out-of-band job running inside it.
-  */
+   * Reset the instance's `sleepAfter` idle timer. The platform renews it on
+   * each proxied request, and because `@lunora/container` proxies WebSocket
+   * frames through the Durable Object, message traffic on an open socket
+   * renews it too (the WebSocket-keepalive gap of cloudflare/containers#147 is
+   * closed in the bundled base). This manual control is the escape hatch for
+   * keeping a container awake during activity that is neither an HTTP request
+   * nor a WS message — e.g. a long out-of-band job running inside it.
+   */
   renewActivityTimeout: () => Promise<void>;
+  /**
+   * Save the running container's filesystem and return a handle to restore it
+   * with `start({ snapshot })` — here or in another instance of the same
+   * container (`schedulingPolicy: "durable_object"` only; Cloudflare beta).
+   * Memory and processes are not captured.
+   */
+  snapshot: (options?: {
+    name?: string;
+  }) => Promise<ContainerSnapshot>;
+  /**
+   * Start a process and stream it, rather than buffer it the way `exec`
+   * does: its stdout/stderr arrive as streams, `stdin` can be piped, and the
+   * process can be killed or (under `pty`) resized while it runs. Needs the
+   * runtime's native exec; the container is started first when it is not
+   * running, and kept awake until the process exits.
+   */
+  spawn: (command: string, options?: ContainerSpawnOptions) => Promise<ContainerProcess>;
   /** Explicitly start the instance, optionally with per-instance env/entrypoint. */
   start: (options?: ContainerStartOptions) => Promise<void>;
   /** Stop the instance (optionally with a signal); it can start again on the next request. */
   stop: (signal?: number | string) => Promise<void>;
+  /**
+   * Answer a WebSocket upgrade `request` with a browser terminal: a shell
+   * (default `sh`) on a PTY, bridged to the socket. Binary frames are
+   * keystrokes, a text frame `{"cols":n,"rows":n}` resizes, and the socket
+   * closes when the shell exits. Authenticate the request first — whoever
+   * holds the socket has a shell in the container. Call it from a Worker
+   * route (see {@link getContainer}) and return the response as-is.
+   */
+  terminal: (request: Request, options?: ContainerTerminalOptions) => Promise<Response>;
 }
 /**
-* Runtime egress-firewall controls for a named instance (`handle.egress.*`).
-* Each maps to the corresponding `@cloudflare/containers` `Container` RPC, so
-* an app can tighten or relax a single instance's allowed/denied hosts after
-* start without redeploying.
-*/
+ * A named instance of a `defineContainer({ sandbox: true })` container: the
+ * {@link ContainerInstanceHandle} plus the Sandbox SDK helpers — structured
+ * file operations, directory backups to R2 and S3-compatible bucket mounts.
+ */
+interface SandboxContainerInstanceHandle extends ContainerInstanceHandle, ContainerSandboxControls {}
+/**
+ * Runtime egress-firewall controls for a named instance (`handle.egress.*`).
+ * Each maps to the corresponding `@cloudflare/containers` `Container` RPC, so
+ * an app can tighten or relax a single instance's allowed/denied hosts after
+ * start without redeploying.
+ */
 interface ContainerEgressControls {
   /** Add one hostname (or glob) to the allow-list. */
   allow: (hostname: string) => Promise<void>;
@@ -125,86 +313,100 @@ interface ContainerEgressControls {
   /** Replace the entire deny-list. */
   setDenied: (hosts: ReadonlyArray<string>) => Promise<void>;
 }
-/** The per-definition accessor exposed as `ctx.containers.&lt;exportName>`. */
+/**
+ * The per-definition accessor exposed as `ctx.containers.<exportName>`.
+ */
 interface ContainerAccessor {
   /**
-  * A random instance from a fixed pool of `count` (defaults to the
-  * definition's `maxInstances`, else 3 — mirroring `getRandom` from
-  * `@cloudflare/containers`). For stateless, interchangeable workloads.
-  *
-  * Like `.get()`, a path/URL-string fetch transparently retries the
-  * cold-start "instance is provisioning" transients (cloudflare/containers#45,
-  * #139); pass {@link InstanceRetryOptions} to tune or disable it.
-  */
+   * A random instance from a fixed pool of `count` (defaults to the
+   * definition's `maxInstances`, else 3 — mirroring `getRandom` from
+   * `@cloudflare/containers`). For stateless, interchangeable workloads.
+   *
+   * Like `.get()`, a path/URL-string fetch transparently retries the
+   * cold-start "instance is provisioning" transients (cloudflare/containers#45,
+   * #139); pass {@link InstanceRetryOptions} to tune or disable it.
+   */
   any: (count?: number, options?: InstanceRetryOptions) => ContainerHandle;
   /**
-  * The instance for `name` — one container per entity (user, room, job…),
-  * with lifecycle control.
-  *
-  * A path/URL-string fetch transparently retries the platform's cold-start
-  * transients — "there is no Container instance available" / "container is
-  * not listening" while an instance is still provisioning
-  * (cloudflare/containers#45, #139) — on the *same* instance with backoff,
-  * since the request never reached the app. Pass {@link InstanceRetryOptions}
-  * to tune attempts/backoff or disable it (`{ attempts: 1 }`). A pre-built
-  * `Request` (possibly a one-shot stream body) is sent once, never retried.
-  */
+   * The instance for `name` — one container per entity (user, room, job…),
+   * with lifecycle control.
+   *
+   * A path/URL-string fetch transparently retries the platform's cold-start
+   * transients — "there is no Container instance available" / "container is
+   * not listening" while an instance is still provisioning
+   * (cloudflare/containers#45, #139) — on the *same* instance with backoff,
+   * since the request never reached the app. Pass {@link InstanceRetryOptions}
+   * to tune attempts/backoff or disable it (`{ attempts: 1 }`). A pre-built
+   * `Request` (possibly a one-shot stream body) is sent once, never retried.
+   */
   get: (name: string, options?: InstanceRetryOptions) => ContainerInstanceHandle;
   /**
-  * A resilient handle over the pool: each `fetch` picks a random instance and,
-  * on a thrown error or a retryable response (5xx by default), retries on a
-  * freshly-picked instance with exponential backoff. Until Cloudflare ships
-  * native autoscaling + health-aware routing this is the recommended way to
-  * call a stateless container pool — it rides over a single cold/unhealthy
-  * instance instead of failing the whole request.
-  *
-  * Because a retry re-issues the request, pass a **replayable** body — a path
-  * string plus an `init.body` string/`ArrayBuffer` (re-created each attempt).
-  * A pre-built `Request` carrying a stream body can only be sent once, so it
-  * is not retry-safe here; use `.get()`/`.any()` for those.
-  */
+   * A resilient handle over the pool: each `fetch` picks a random instance and,
+   * on a thrown error or a retryable response (5xx by default), retries on a
+   * freshly-picked instance with exponential backoff. Until Cloudflare ships
+   * native autoscaling + health-aware routing this is the recommended way to
+   * call a stateless container pool — it rides over a single cold/unhealthy
+   * instance instead of failing the whole request.
+   *
+   * Because a retry re-issues the request, pass a **replayable** body — a path
+   * string plus an `init.body` string/`ArrayBuffer` (re-created each attempt).
+   * A pre-built `Request` carrying a stream body can only be sent once, so it
+   * is not retry-safe here; use `.get()`/`.any()` for those.
+   */
   pool: (options?: PoolOptions) => ContainerHandle;
 }
-/** Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}. */
+/** `ctx.containers.<name>` for a `defineContainer({ sandbox: true })` container: `.get()` adds the sandbox helpers. */
+interface SandboxContainerAccessor extends ContainerAccessor {
+  get: (name: string, options?: InstanceRetryOptions) => SandboxContainerInstanceHandle;
+}
+/**
+ * Tuning for a pooled, retrying container handle. See {@link ContainerAccessor.pool}.
+ */
 interface PoolOptions {
   /** Total attempts before giving up (each on a freshly-picked instance). Default 3. */
   attempts?: number;
   /** Base backoff in ms between attempts; doubles each retry (0 disables the wait). Default 100. */
   backoffMs?: number;
   /**
-  * Upper bound on a single backoff sleep, in ms. The doubling delay is clamped
-  * to this ceiling so a large `attempts` count can't produce an unboundedly
-  * long wait. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s).
-  */
+   * Upper bound on a single backoff sleep, in ms. The doubling delay is clamped
+   * to this ceiling so a large `attempts` count can't produce an unboundedly
+   * long wait. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s).
+   */
   maxBackoffMs?: number;
   /**
-  * Whether a *returned* response should be retried on another instance.
-  * Defaults to retrying any `5xx`. A thrown error (network/start failure) is
-  * always retried regardless of this predicate.
-  */
+   * Whether a *returned* response should be retried on another instance.
+   * Defaults to retrying any `5xx`. A thrown error (network/start failure) is
+   * always retried regardless of this predicate.
+   *
+   * Applies to `fetch` only. `exec` retries on the cold-start transients
+   * alone, because its caller never chose the request and a command that
+   * already ran must not be re-run just because the runner failed afterwards.
+   */
   retryOn?: (response: Response) => boolean;
   /** Pool size to spread picks across. Defaults to the definition's `maxInstances`, else 3. */
   size?: number;
 }
 /**
-* Tuning for the cold-start retry on a `.get()`/`.any()` handle. The retry fires
-* only on the platform's provisioning transients (no-instance / not-listening /
-* rate-limited — see {@link isColdStartTransient}), which is why it's safe by
-* default: those responses mean the request never reached the container.
-*/
+ * Tuning for the cold-start retry on a `.get()`/`.any()` handle. The retry fires
+ * only on the platform's provisioning transients (no-instance / not-listening /
+ * rate-limited — see {@link isColdStartTransient}), which is why it's safe by
+ * default: those responses mean the request never reached the container.
+ */
 interface InstanceRetryOptions {
   /**
-  * Total attempts on a cold-start transient before the last outcome is
-  * surfaced as-is. `1` disables the retry. Default
-  * {@link DEFAULT_COLD_START_ATTEMPTS}.
-  */
+   * Total attempts on a cold-start transient before the last outcome is
+   * surfaced as-is. `1` disables the retry. Default
+   * {@link DEFAULT_COLD_START_ATTEMPTS}.
+   */
   attempts?: number;
   /** Base backoff in ms between attempts; doubles each retry (0 disables the wait). Default {@link DEFAULT_COLD_START_BACKOFF_MS}. */
   backoffMs?: number;
   /** Upper bound on a single backoff sleep, in ms. Default {@link DEFAULT_MAX_BACKOFF_MS} (30s). */
   maxBackoffMs?: number;
 }
-/** Wiring info for one definition, emitted by codegen into the generated DO. */
+/**
+ * Wiring info for one definition, emitted by codegen into the generated DO.
+ */
 interface ContainerBindingSpec {
   /** Durable Object binding name, e.g. `CONTAINER_TRANSCODER`. */
   binding: string;
@@ -214,70 +416,299 @@ interface ContainerBindingSpec {
   maxInstances?: number;
 }
 /**
-* Build the `ctx.containers` record from the Worker `env`. Called by the
-* generated ShardDO with the specs codegen derived from
-* `lunora/containers.ts`. A missing binding doesn't throw here — only when the
-* handle is actually used — so one unprovisioned container never breaks
-* unrelated functions.
-*/
-declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction) => Record<string, ContainerAccessor>;
-/** A test handler: receives the request plus the targeted instance name. */
+ * Build the `ctx.containers` record from the Worker `env`. Called by the
+ * generated ShardDO with the specs codegen derived from `lunora/containers.ts`.
+ * A missing binding doesn't throw here — only when the handle is actually used —
+ * so one unprovisioned container never breaks unrelated functions.
+ *
+ * The last two arguments carry the dispatch's telemetry verdict onto every
+ * outbound container `fetch`, both read off the inbound request by the DO:
+ *
+ * - `traceparent` — the W3C trace context, so the container's own spans stitch
+ * under the Worker's trace rather than starting a disconnected one.
+ * - `sampleErrors` — the tail-bias toggle, so the container exports what THIS
+ * dispatch decided instead of falling back to its own environment and agreeing
+ * with the other tiers only by coincidence. `undefined` (an alarm, a
+ * subscription re-run, a non-Lunora caller propagated no verdict) omits the
+ * header and leaves the container on its own configuration.
+ */
+declare const createContainerContext: (env: Record<string, unknown>, specs: ReadonlyArray<ContainerBindingSpec>, jurisdiction?: DurableObjectJurisdiction, traceparent?: string, sampleErrors?: boolean) => Record<string, ContainerAccessor>;
+/**
+ * A named container instance straight off the Worker `env`, for code that has
+ * no `ctx.containers` — typically an `httpRouter` route that opens a
+ * {@link ContainerInstanceHandle.terminal} or proxies a preview port, both of
+ * which must hand a WebSocket upgrade response back to the browser. The
+ * binding is derived from `exportName` exactly as codegen derives it. Pass
+ * {@link SandboxContainerInstanceHandle} as the type argument for a
+ * `sandbox: true` container.
+ *
+ * ```ts
+ * app.get("/terminal", async (c) => getContainer(c.env, "box", userId).terminal(c.req.raw));
+ * ```
+ */
+declare const getContainer: <Handle extends ContainerInstanceHandle = ContainerInstanceHandle>(env: Record<string, unknown>, exportName: string, name: string, options?: InstanceRetryOptions & {
+  jurisdiction?: DurableObjectJurisdiction;
+}) => Handle;
+/**
+ * A test handler: receives the request plus the targeted instance name.
+ */
 type ContainerTestHandler = (request: Request, instance: {
   name: string;
 }) => Promise<Response> | Response;
 /**
-* Docker-free test double for `ctx.containers`: each export name maps to a
-* fetch handler that plays the container. Mirrors the real shape exactly, so
-* action handlers under test can't tell the difference.
-*
-* ```ts
-* const containers = createContainerTestContext({
-*     transcoder: (request) => new Response("ok"),
-* });
-* ```
-*/
+ * Docker-free test double for `ctx.containers`: each export name maps to a
+ * fetch handler that plays the container. Mirrors the real shape exactly, so
+ * action handlers under test can't tell the difference.
+ *
+ * ```ts
+ * const containers = createContainerTestContext({
+ *     transcoder: (request) => new Response("ok"),
+ * });
+ * ```
+ */
 declare const createContainerTestContext: (handlers: Record<string, ContainerTestHandler>) => Record<string, ContainerAccessor>;
+/** Whether an image name is a Cloudflare-managed image (`cloudflare/debian-trixie`), which needs no `images` entry. */
+declare const isManagedImage: (name: string) => boolean;
+/**
+ * The default-policy keys the `durable_object` policy refuses — wrangler rejects
+ * `max_instances` under it, and a rollout has nothing to roll. One table, read by
+ * `defineContainer` and by codegen's static discovery.
+ */
+declare const DURABLE_OBJECT_POLICY_FORBIDDEN_KEYS: readonly ["maxInstances", "rollout"];
 /**
-* Normalize a `ContainerImageSource` into the shape wrangler wants: a
-* Dockerfile path + build context for local builds, or a fully-qualified
-* reference for pre-built images.
-*
-* A local-path string whose basename starts with `Dockerfile` (so
-* `Dockerfile.dev` also counts) is used as-is with its directory as the build
-* context; any other path is treated as the build-context directory and the
-* Dockerfile is expected at `&lt;dir>/Dockerfile`.
-*/
+ * Normalize a `ContainerImageSource` into the shape wrangler wants: a
+ * Dockerfile path + build context for local builds, or a fully-qualified
+ * reference for pre-built images.
+ *
+ * A local-path string whose basename starts with `Dockerfile` (so
+ * `Dockerfile.dev` also counts) is used as-is with its directory as the build
+ * context; any other path is treated as the build-context directory and the
+ * Dockerfile is expected at `<dir>/Dockerfile`.
+ */
 declare const normalizeContainerImage: (image: ContainerImageSource) => NormalizedContainerImage;
 /**
-* The generated Container DO class name for a `lunora/containers.ts` export:
-* `transcoder` → `TranscoderContainer`. wrangler's `containers[].class_name`
-* and the Durable Object binding's `class_name` both reference it, so codegen
-* and the config layer MUST derive it identically — always via this helper.
-*/
+ * The generated Container DO class name for a `lunora/containers.ts` export:
+ * `transcoder` → `TranscoderContainer`. wrangler's `containers[].class_name`
+ * and the Durable Object binding's `class_name` both reference it, so codegen
+ * and the config layer MUST derive it identically — always via this helper.
+ */
 declare const containerClassName: (exportName: string) => string;
 /**
-* The Durable Object binding name for a container export: `transcoder` →
-* `CONTAINER_TRANSCODER`, `imageResizer` → `CONTAINER_IMAGE_RESIZER`. The
-* `CONTAINER_` prefix namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`
-* so a container export can never collide with the built-in bindings.
-*/
+ * The Durable Object binding name for a container export: `transcoder` →
+ * `CONTAINER_TRANSCODER`, `imageResizer` → `CONTAINER_IMAGE_RESIZER`. The
+ * `CONTAINER_` prefix namespaces these away from `SHARD`/`SESSION`/`SCHEDULER`
+ * so a container export can never collide with the built-in bindings.
+ */
 declare const containerBindingName: (exportName: string) => string;
 /**
-* The local image tag a Railpack `{ build }` container is built and pushed
-* under: `transcoder` → `lunora-transcoder:build`. The config reconciler writes
-* it as the wrangler `containers[].image`, and `lunora deploy` builds that tag
-* with Railpack and `wrangler containers push`es it before deploying — so all
-* three derive the tag from this one helper and can never disagree.
-*/
+ * The local image tag a Railpack `{ build }` container is built and pushed
+ * under: `transcoder` → `lunora-transcoder:build`. The config reconciler writes
+ * it as the wrangler `containers[].image`, and `lunora deploy` builds that tag
+ * with Railpack and `wrangler containers push`es it before deploying — so all
+ * three derive the tag from this one helper and can never disagree.
+ */
 declare const containerBuildTag: (exportName: string) => string;
-declare const defineContainer: (config: ContainerConfig) => ContainerDefinition;
-/** True when a value is a `defineContainer` result (the runtime brand check). */
+/** Whether a registry reference is digest-pinned in the Cloudflare registry — the only kind a named image accepts. */
+declare const isCloudflareRegistryDigest: (reference: unknown) => boolean;
+/**
+ * `defineContainer` is part of the experimental `@lunora/container` API and may change without a major version bump.
+ */
+declare const defineContainer: {
+  (config: DefaultScheduledContainerConfig): DefaultScheduledContainerConfig & {
+    readonly isLunoraContainer: true;
+  };
+  (config: DurableObjectScheduledContainerConfig): DurableObjectScheduledContainerConfig & {
+    readonly isLunoraContainer: true;
+  };
+};
+/**
+ * True when a value is a `defineContainer` result (the runtime brand check).
+ */
 declare const isContainerDefinition: (value: unknown) => value is ContainerDefinition;
 /**
-* The container's full environment at instance start: the static `env` block
-* plus every declared secret resolved from the Worker `env`. A declared secret
-* missing from the Worker env fails fast — starting the container without a
-* credential it was promised yields far worse errors downstream.
-*/
+ * The container's full environment at instance start: the static `env` block
+ * plus every declared secret resolved from the Worker `env`. A declared secret
+ * missing from the Worker env fails fast — starting the container without a
+ * credential it was promised yields far worse errors downstream.
+ */
 declare const resolveContainerEnvVariables: (definition: ContainerDefinition, workerEnv: Record<string, unknown>, exportName?: string) => Record<string, string>;
-export { type ContainerAccessor, type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition, type ContainerEgressControls, type ContainerHandle, type ContainerImageSource, type ContainerInstanceHandle, type ContainerInstanceState, type ContainerNamespaceLike, type ContainerStartOptions, type ContainerTestHandler, type DurableObjectJurisdiction, type InstanceRetryOptions, type NormalizedContainerImage, type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };
+/**
+ * Cloudflare's documented bounds for a custom container instance type
+ * (https://developers.cloudflare.com/containers/platform-details/limits/):
+ * 1–4 vCPU, up to 12 GiB memory, up to 20 GB disk at any memory size, and at
+ * least 3 GiB memory per vCPU. Below 1 vCPU, Cloudflare points at the named
+ * `lite` / `basic` instance types instead.
+ *
+ * The one copy of these numbers. `defineContainer` checks a `durable_object`
+ * container's runtime size against it, and `@lunora/config`'s wrangler validator
+ * checks `containers[].instance_type` against it (config already depends on this
+ * package, so the import runs one way). Pure data, Node-safe.
+ */
+/** Inclusive bounds for one dimension of a custom instance type. */
+interface InstanceDimensionLimits {
+  readonly max: number;
+  readonly min: number;
+}
+/** Per-dimension bounds, keyed by the `CustomContainerInstanceType` field names. */
+declare const CUSTOM_INSTANCE_TYPE_LIMITS: Readonly<{
+  diskMb: InstanceDimensionLimits;
+  memoryMib: InstanceDimensionLimits;
+  vcpu: InstanceDimensionLimits;
+}>;
+/** The memory floor per vCPU: 3 GiB. */
+declare const CUSTOM_INSTANCE_MIN_MEMORY_MIB_PER_VCPU = 3072;
+export { CONTAINER_EXEC_PATH, CUSTOM_INSTANCE_MIN_MEMORY_MIB_PER_VCPU, CUSTOM_INSTANCE_TYPE_LIMITS,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerAccessor, type ContainerBackupOptions,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerBindingSpec, type ContainerDefinition,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerEgressControls, type ContainerExecOptions, type ContainerExecResult, type ContainerFileContent, type ContainerFileOptions,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerHandle, type ContainerImageSource,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerInstanceHandle,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerInstanceState, type ContainerMountRequest,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerNamespaceLike, type ContainerProcess, type ContainerRuntimeInstanceType, type ContainerSandboxControls, type ContainerSnapshot, type ContainerSpawnOptions,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerStartOptions, type ContainerTerminalOptions,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type ContainerTestHandler, DURABLE_OBJECT_POLICY_FORBIDDEN_KEYS, type DefaultScheduledContainerConfig,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type DurableObjectJurisdiction, type DurableObjectScheduledContainerConfig, type InstanceDimensionLimits,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type InstanceRetryOptions, type NormalizedContainerImage,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type PoolOptions,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type SandboxContainerAccessor,
+/**
+ * `@lunora/container` — Cloudflare Containers for Lunora.
+ *
+ * This root export is Node-safe (no Cloudflare runtime imports): the
+ * `defineContainer` authoring surface, the naming/normalization helpers
+ * codegen and `@lunora/config` share, the `ctx.containers` client wiring, and
+ * a Docker-free test double. The workerd-only `LunoraContainer` base class
+ * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
+ * behind the `@lunora/container/do` subpath.
+ */
+type SandboxContainerInstanceHandle, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, getContainer, isCloudflareRegistryDigest, isContainerDefinition, isManagedImage, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };