@lunora/container 1.0.0-alpha.63 → 1.0.0-alpha.65

package/dist/index.d.mts

@@ -1,5 +1,9 @@
-import { D as DurableObjectJurisdiction, a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-DPvNG2h5.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/jurisdiction.d-DPvNG2h5.mjs";
+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-t4mtuqYW.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-t4mtuqYW.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`.
  */
@@ -67,6 +71,15 @@ interface ContainerExecResult {
  * 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`).
  */
@@ -89,8 +102,26 @@ interface ContainerStartOptions {
    * 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.
@@ -111,8 +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>;
@@ -199,11 +256,43 @@ interface ContainerInstanceHandle extends ContainerHandle {
    * 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>;
 }
+/**
+ * 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
@@ -266,6 +355,10 @@ interface ContainerAccessor {
    */
   pool: (options?: PoolOptions) => ContainerHandle;
 }
+/** `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}.
  */
@@ -340,6 +433,22 @@ interface ContainerBindingSpec {
  * 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.
  */
@@ -358,6 +467,14 @@ type ContainerTestHandler = (request: Request, instance: {
  * ```
  */
 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
@@ -391,10 +508,19 @@ declare const containerBindingName: (exportName: string) => string;
  * three derive the tag from this one helper and can never disagree.
  */
 declare const containerBuildTag: (exportName: string) => string;
+/** 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: ContainerConfig) => ContainerDefinition;
+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).
  */
@@ -417,7 +543,7 @@ export { CONTAINER_EXEC_PATH,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerAccessor,
+type ContainerAccessor, type ContainerBackupOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -428,7 +554,7 @@ type ContainerAccessor,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition,
+type ContainerBindingSpec, type ContainerDefinition,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -439,7 +565,7 @@ type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerEgressControls, type ContainerExecOptions, type ContainerExecResult,
+type ContainerEgressControls, type ContainerExecOptions, type ContainerExecResult, type ContainerFileContent, type ContainerFileOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -472,7 +598,7 @@ type ContainerInstanceHandle,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerInstanceState,
+type ContainerInstanceState, type ContainerMountRequest,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -483,7 +609,7 @@ type ContainerInstanceState,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerNamespaceLike,
+type ContainerNamespaceLike, type ContainerProcess, type ContainerRuntimeInstanceType, type ContainerSandboxControls, type ContainerSnapshot, type ContainerSpawnOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -494,7 +620,7 @@ type ContainerNamespaceLike,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerStartOptions,
+type ContainerStartOptions, type ContainerTerminalOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -505,7 +631,7 @@ type ContainerStartOptions,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerTestHandler,
+type ContainerTestHandler, DURABLE_OBJECT_POLICY_FORBIDDEN_KEYS, type DefaultScheduledContainerConfig,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -516,7 +642,7 @@ type ContainerTestHandler,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type DurableObjectJurisdiction,
+type DurableObjectJurisdiction, type DurableObjectScheduledContainerConfig,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -538,4 +664,26 @@ type InstanceRetryOptions, type NormalizedContainerImage,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-import { D as DurableObjectJurisdiction, a as ContainerConfig, C as ContainerDefinition, b as ContainerImageSource, N as NormalizedContainerImage } from "./packem_shared/jurisdiction.d-DPvNG2h5.js";
-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/jurisdiction.d-DPvNG2h5.js";
+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-t4mtuqYW.js";
+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-t4mtuqYW.js";
+import { b as ContainerBackupOptions, C as ContainerFileOptions, c as ContainerMountRequest, a as ContainerFileContent, d as ContainerSandboxControls } from "./packem_shared/sandbox-types.d-DXlHnsEg.js";
+export type { e as ContainerFiles, f as ContainerMountCredentials } from "./packem_shared/sandbox-types.d-DXlHnsEg.js";
+import { DirectoryBackupRecord, S3MountInspection, SandboxDirectoryEntry, SandboxFileStat } from '@cloudflare/sandbox';
+export type { DirectoryBackupRecord, S3MountInspection, SandboxDirectoryEntry, SandboxFileStat } from '@cloudflare/sandbox';
 /**
  * Per-call options for `ContainerHandle.exec`.
  */
@@ -67,6 +71,15 @@ interface ContainerExecResult {
  * 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`).
  */
@@ -89,8 +102,26 @@ interface ContainerStartOptions {
    * 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.
@@ -111,8 +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>;
@@ -199,11 +256,43 @@ interface ContainerInstanceHandle extends ContainerHandle {
    * 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>;
 }
+/**
+ * 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
@@ -266,6 +355,10 @@ interface ContainerAccessor {
    */
   pool: (options?: PoolOptions) => ContainerHandle;
 }
+/** `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}.
  */
@@ -340,6 +433,22 @@ interface ContainerBindingSpec {
  * 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.
  */
@@ -358,6 +467,14 @@ type ContainerTestHandler = (request: Request, instance: {
  * ```
  */
 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
@@ -391,10 +508,19 @@ declare const containerBindingName: (exportName: string) => string;
  * three derive the tag from this one helper and can never disagree.
  */
 declare const containerBuildTag: (exportName: string) => string;
+/** 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: ContainerConfig) => ContainerDefinition;
+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).
  */
@@ -417,7 +543,7 @@ export { CONTAINER_EXEC_PATH,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerAccessor,
+type ContainerAccessor, type ContainerBackupOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -428,7 +554,7 @@ type ContainerAccessor,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition,
+type ContainerBindingSpec, type ContainerDefinition,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -439,7 +565,7 @@ type ContainerBindingSpec, type ContainerConfig, type ContainerDefinition,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerEgressControls, type ContainerExecOptions, type ContainerExecResult,
+type ContainerEgressControls, type ContainerExecOptions, type ContainerExecResult, type ContainerFileContent, type ContainerFileOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -472,7 +598,7 @@ type ContainerInstanceHandle,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerInstanceState,
+type ContainerInstanceState, type ContainerMountRequest,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -483,7 +609,7 @@ type ContainerInstanceState,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerNamespaceLike,
+type ContainerNamespaceLike, type ContainerProcess, type ContainerRuntimeInstanceType, type ContainerSandboxControls, type ContainerSnapshot, type ContainerSpawnOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -494,7 +620,7 @@ type ContainerNamespaceLike,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerStartOptions,
+type ContainerStartOptions, type ContainerTerminalOptions,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -505,7 +631,7 @@ type ContainerStartOptions,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type ContainerTestHandler,
+type ContainerTestHandler, DURABLE_OBJECT_POLICY_FORBIDDEN_KEYS, type DefaultScheduledContainerConfig,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -516,7 +642,7 @@ type ContainerTestHandler,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type DurableObjectJurisdiction,
+type DurableObjectJurisdiction, type DurableObjectScheduledContainerConfig,
 /**
  * `@lunora/container` — Cloudflare Containers for Lunora.
  *
@@ -538,4 +664,26 @@ type InstanceRetryOptions, type NormalizedContainerImage,
  * (which pulls in `@cloudflare/containers` → `cloudflare:workers`) lives
  * behind the `@lunora/container/do` subpath.
  */
-type PoolOptions, containerBindingName, containerBuildTag, containerClassName, createContainerContext, createContainerTestContext, defineContainer, isContainerDefinition, normalizeContainerImage, resolveContainerEnvVariables as resolveContainerEnvVars };
+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 };

package/dist/index.mjs

@@ -1 +1 @@
-import{createContainerContext as o,createContainerTestContext as r}from"./packem_shared/createContainerContext-CLvjjJLs.mjs";import{containerBindingName as a,containerBuildTag as i,containerClassName as C,defineContainer as m,isContainerDefinition as s,normalizeContainerImage as c,resolveContainerEnvVars as f}from"./packem_shared/containerBindingName-C7SonAIK.mjs";import{C as l}from"./packem_shared/exec-WbCOLswq.mjs";export{l as CONTAINER_EXEC_PATH,a as containerBindingName,i as containerBuildTag,C as containerClassName,o as createContainerContext,r as createContainerTestContext,m as defineContainer,s as isContainerDefinition,c as normalizeContainerImage,f as resolveContainerEnvVars};
+import{createContainerContext as a,createContainerTestContext as t,getContainer as i}from"./packem_shared/createContainerContext-CcW1olml.mjs";import{DURABLE_OBJECT_POLICY_FORBIDDEN_KEYS as o,containerBindingName as C,containerBuildTag as s,containerClassName as g,defineContainer as m,isCloudflareRegistryDigest as E,isContainerDefinition as f,isManagedImage as l,normalizeContainerImage as _,resolveContainerEnvVars as c}from"./packem_shared/DURABLE_OBJECT_POLICY_FORBIDDEN_KEYS-B9DkqZkf.mjs";import{C as x}from"./packem_shared/exec-BYLW70sR.mjs";export{x as CONTAINER_EXEC_PATH,o as DURABLE_OBJECT_POLICY_FORBIDDEN_KEYS,C as containerBindingName,s as containerBuildTag,g as containerClassName,a as createContainerContext,t as createContainerTestContext,m as defineContainer,i as getContainer,E as isCloudflareRegistryDigest,f as isContainerDefinition,l as isManagedImage,_ as normalizeContainerImage,c as resolveContainerEnvVars};

package/dist/packem_shared/CONTAINER_EXEC_PATH-7Hcd6-zs.mjs

@@ -0,0 +1 @@
+import"./abort-deadline-jwbW9Ala.mjs";import{a as e,C as A,D as T,e as s,p as C}from"./exec-BYLW70sR.mjs";export{e as CONTAINER_EXEC_HEADER,A as CONTAINER_EXEC_PATH,T as DEFAULT_EXEC_MAX_OUTPUT_BYTES,s as execViaFetch,C as pathMatchesAnyDecoding};