@evolvingmachines/modal 0.0.55 → 0.0.57

package/dist/index.d.ts

@@ -1,7 +1,20 @@
+import { Sandbox } from 'modal';
+
+/**
+ * GENERATED — DO NOT EDIT. `npm run generate:image-version` (repo root)
+ * rewrites this file from the evolve-all image build inputs under
+ * assets/docker/ (see assets/docker/image-digest.ts for the derivation).
+ * The value is content-addressed: same inputs → same tag, any input
+ * change → a new tag. The coherence test in
+ * packages/daytona/tests/unit/daytona-image-version.test.ts fails the
+ * suite whenever this checked-in copy is stale.
+ */
+declare const EVOLVE_IMAGE_VERSION = "c-880c264ce574";
+
 /**
  * Modal Sandbox Provider - Clean Architecture
  *
- * @requires modal >= 0.3.0
+ * @requires modal >= 0.9.0
  * @requires Node.js >= 18 (for ReadableStream support)
  *
  * Design principles:
@@ -13,9 +26,322 @@
  *
  * Modal-specific notes:
  * - No native file APIs - uses exec() with stdin/stdout
- * - pause() not supported - throws error
+ * - Named Volumes mount at create (`volumes`, keyed by in-box path, read-only
+ *   or read-write) — Modal's "upload once, read from many sandboxes" store.
+ *   modal@0.9.0 has no upload-to-Volume call, so a Volume is filled from
+ *   INSIDE a sandbox that mounts it read-write (background commits while it
+ *   runs, a final commit when it exits); this package adds none either
+ * - pause() not supported - throws error (use Evolve checkpoints for persistence)
  * - Requires app context for sandbox creation
+ * - Hard 24h sandbox lifetime cap (ModalSandboxLifetimeError when exceeded)
+ * - Everything executes as root inside the sandbox; the `user` option is
+ *   enforced through an `su <user> -c` wrapper (default user: "user")
+ * - Network policy maps to Modal's blockNetwork / outboundDomainAllowlist /
+ *   outboundCidrAllowlist (domain allowlist admits TLS on port 443 only —
+ *   plaintext destinations must be listed as IPs/CIDRs)
+ * - Modal exposes no metadata or public timestamps on sandboxes; both are
+ *   stamped into sandbox tags at create time and read back via getTags()
+ */
+
+/**
+ * Modal's hard cap on sandbox lifetime (24 hours).
+ * Requests beyond this throw ModalSandboxLifetimeError.
+ */
+declare const MODAL_MAX_LIFETIME_MS: number;
+/**
+ * Chunk size for stdin uploads, and the reason it is THIS big.
+ *
+ * Every writeBytes() call is one awaited unary TaskExecStdinWrite round trip
+ * to Modal, so upload time is set by how many messages a payload becomes, not
+ * by how many bytes it is. Measured on live sandboxes with a 180MiB file:
+ *
+ *     64KiB   311.6s   (2880 messages — Node's default read size)
+ *     4MiB     36.2s
+ *     8MiB     30.1s   <- this constant
+ *     16MiB    31.4s
+ *
+ * Below roughly 4MiB the upload is round-trip bound and shrinking the chunk
+ * makes it dramatically slower; above it the transport saturates near 6MiB/s
+ * and a bigger chunk buys nothing.
+ *
+ * Modal's 100MiB per-message cap (RESOURCE_EXHAUSTED at 104,857,600 bytes) is
+ * the CEILING this must stay under — it is not the reason for the value. Do
+ * not "play it safe" by trimming this toward the cap-satisfying end: 64KiB is
+ * equally cap-safe and ten times slower, which is exactly the state this
+ * constant was raised to fix.
+ *
+ * STANDING DECISION (chunk size stays 8MiB) and its trigger: a worker running
+ * 16 concurrent uploads buffers about 256MiB at this size, which is real
+ * pressure in a 1GB worker. The re-profile's saturation row runs exactly that
+ * 16-parallel case; the ruling is to move on ITS data, not on precaution. If
+ * that row shows memory pressure, dropping to 4MiB is a measured one-line
+ * change — 36.2s versus 30.1s, about 83% of the throughput for half the
+ * buffer — and everything above still holds.
+ */
+declare const MODAL_STDIN_CHUNK_BYTES: number;
+/**
+ * Typed error for Modal's hard 24h sandbox lifetime cap.
+ * Long-running sessions must persist progress with Evolve checkpoints and
+ * resume in a fresh sandbox instead of extending the timeout.
+ */
+declare class ModalSandboxLifetimeError extends Error {
+    readonly requestedTimeoutMs: number;
+    constructor(requestedTimeoutMs: number);
+}
+/** Throws ModalSandboxLifetimeError when the timeout exceeds Modal's 24h cap. */
+declare function validateTimeout(timeoutMs: number): void;
+/**
+ * Typed error for an idle timeout Modal could not act on. Both bounds are
+ * refusals rather than clamps: silently raising a zero, or lowering a value past
+ * the lifetime cap, would hand back a box that dies on a schedule the caller
+ * never asked for.
+ */
+declare class ModalIdleTimeoutError extends Error {
+    readonly requestedIdleTimeoutMs: number;
+    constructor(requestedIdleTimeoutMs: number, reason: string);
+}
+/**
+ * Evolve's idle bound -> Modal's create params, same shape as mapNetworkPolicy
+ * and mapResources: provider-neutral option in, Modal fragment out.
+ *
+ * ABSENT MEANS ABSENT. Modal's own default is no idle timer at all, so an unset
+ * option must spread to nothing — inventing a default here would start killing
+ * boxes that today live out their lifetime, for every caller who never asked.
+ *
+ * An idle timeout has to be a positive span, and one above the 24h lifetime cap
+ * can never fire because the sandbox is already gone. Both are caller mistakes,
+ * and both throw rather than clamp: silently raising a zero or lowering an
+ * over-cap value hands back a box that dies on a schedule nobody chose.
+ */
+declare function mapIdleTimeout(idleTimeoutMs?: number): {
+    idleTimeoutMs?: number;
+};
+/**
+ * Typed error for a boot command Modal could not act on as given. A refusal
+ * rather than a repair, same law as the idle bound above: the one shape
+ * rejected (an empty argv) is indistinguishable on the wire from "no args",
+ * which boots the image's own ENTRYPOINT/CMD — exactly what an explicit
+ * bootCommand exists to displace.
+ */
+declare class ModalBootCommandError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Evolve's boot command -> Modal's create params, same shape as
+ * mapIdleTimeout and mapResources: provider-neutral option in, Modal
+ * fragment out.
+ *
+ * ABSENT MEANS ABSENT: with no bootCommand the create carries no `command`,
+ * and the image's own ENTRYPOINT/CMD boots as the sandbox main process —
+ * Modal's documented default and this provider's behavior since its first
+ * release; inventing a keep-alive here would silently change what every
+ * existing caller's box runs.
+ *
+ * An EMPTY argv is refused, never forwarded: Modal reads empty args as "no
+ * args" (the wire shape is the same `entrypointArgs: []` an omitted command
+ * produces), so `bootCommand: []` would boot the entrypoint while looking
+ * like an override — omit the option to boot the image's command.
+ */
+declare function mapBootCommand(bootCommand?: readonly string[]): {
+    command?: string[];
+};
+/**
+ * One named Modal Volume to mount at sandbox creation — the value of the
+ * `volumes` create option, keyed by its absolute in-box mount path.
+ */
+interface ModalVolumeMount {
+    /** The Volume's name in the Modal workspace (client.volumes.fromName). */
+    name: string;
+    /**
+     * Mount read-only (default false). Enforced by Modal inside the box: a
+     * write on a read-only mount answers EROFS ("Read-only file system").
+     */
+    readOnly?: boolean;
+    /**
+     * Create the Volume when no Volume of that name exists (default false —
+     * a missing Volume is a typed refusal, ModalVolumeError "not-found").
+     */
+    createIfMissing?: boolean;
+}
+/** Why a Volume mount could not be honored. */
+type ModalVolumeErrorReason = 
+/** The mount path is not an absolute in-box path (or is "/"). Refused offline. */
+"invalid-mount-path"
+/** The Volume name is blank. Refused offline. */
+ | "invalid-name"
+/** No Volume of that name exists and createIfMissing was not set. */
+ | "not-found"
+/** Modal could not resolve the Volume for another reason (its words in the message). */
+ | "resolve-failed";
+/**
+ * Typed error for a `volumes` entry this provider cannot mount. Thrown by
+ * create() — the two offline reasons before any network call, the two
+ * resolve reasons before any sandbox exists, so a refused mount never leaves
+ * a box behind. `cause` carries Modal's own error on the resolve reasons.
+ */
+declare class ModalVolumeError extends Error {
+    readonly reason: ModalVolumeErrorReason;
+    readonly mountPath: string;
+    readonly volumeName: string;
+    constructor(reason: ModalVolumeErrorReason, mountPath: string, volumeName: string, message: string, cause?: unknown);
+}
+/** One validated Volume mount, ready to resolve. */
+interface ResolvedVolumeMount {
+    mountPath: string;
+    name: string;
+    readOnly: boolean;
+    createIfMissing: boolean;
+}
+/**
+ * Evolve's `volumes` option -> the list create() resolves, same shape as
+ * mapIdleTimeout and mapBootCommand: option in, validated fragment out, and
+ * ABSENT MEANS ABSENT — no option (or an empty record) yields no mounts and
+ * the create call carries no `volumes` key at all.
+ *
+ * Offline refusals, before any app/image/Volume round trip: a mount path
+ * that is not absolute (Modal mounts by absolute path; a relative one has
+ * no meaning) or is "/" (mounting over the root filesystem), and a blank
+ * Volume name (fromName would answer with a confusing not-found).
+ */
+declare function mapVolumeMounts(volumes?: Record<string, ModalVolumeMount>): ResolvedVolumeMount[];
+/**
+ * Wrap a command with cwd + env handling and (when not root) an
+ * `su <user> -c` wrapper.
+ *
+ * Modal sandboxes run as root by default (ignoring the Dockerfile USER
+ * directive), but Claude CLI and other tools refuse certain operations when
+ * running as root.
+ *
+ * Uses `su <user> -c` instead of `sudo -u <user>` because Claude CLI's
+ * --dangerously-skip-permissions flag refuses to run when it detects sudo.
+ *
+ * Uses base64 encoding to avoid shell escaping issues with complex commands
+ * that contain quotes, special characters, etc. Env vars are inlined because
+ * su does not preserve the environment the way `sudo -E` does.
+ */
+declare function wrapCommand(command: string, user: string, cwd?: string, envs?: Record<string, string>): string[];
+/**
+ * Typed error for sizing requests Modal's create() cannot enforce.
+ * The installed Modal JS SDK sizes cpu (cores) and memoryMiB at create time
+ * only — there is no disk-size parameter, so a requested disk size would be
+ * silently ignored. Per the provider law (reject what you cannot enforce,
+ * never silently ignore) it is refused loudly here.
+ */
+declare class ModalResourcesError extends Error {
+    constructor(message: string);
+}
+/**
+ * Map Evolve's provider-neutral resources (cpu cores, memory GiB, disk GiB)
+ * onto Modal's create() params (cpu cores, memoryMiB). Fractional GiB rounds
+ * UP so the sandbox never gets less memory than requested. `disk` throws
+ * ModalResourcesError — the SDK cannot express it.
+ */
+/**
+ * Structural twin of SandboxCreateOptions["resources"] — spelled locally
+ * (rather than indexed off the SDK type) so this package can build against
+ * an SDK whose published type predates the GPU fields; the provider-parity
+ * conformance file still pins the two to each other.
+ */
+type ModalCreateResources = {
+    cpu?: number;
+    memory?: number;
+    disk?: number;
+    gpu?: number;
+    gpuTypes?: string[];
+};
+declare function mapResources(resources?: ModalCreateResources): {
+    cpu: number;
+    memoryMiB: number;
+    gpu?: string;
+};
+/** Modal create() params derived from Evolve's provider-neutral network policy. */
+interface ModalNetworkCreateParams {
+    blockNetwork?: boolean;
+    outboundCidrAllowlist?: string[];
+    outboundDomainAllowlist?: string[];
+}
+/** Why a network destination cannot be mapped onto Modal's allowlist. */
+type ModalNetworkPolicyReason = "port-unsupported" | "invalid-ipv4";
+/**
+ * Typed error for destinations Modal's allowlist cannot express.
+ *
+ * Modal's allowlist filters hosts (domain allowlist) and IPs/CIDRs (CIDR
+ * allowlist) only — it has no notion of a port, and an invalid IPv4/CIDR
+ * would be silently forwarded to the API. Both are rejected loudly here
+ * instead of weakening or mangling the sandbox's egress policy.
  */
+declare class ModalNetworkPolicyError extends Error {
+    readonly reason: ModalNetworkPolicyReason;
+    /** The offending destination. */
+    readonly destination?: string;
+    constructor(reason: ModalNetworkPolicyReason, message: string, destination?: string);
+}
+/**
+ * Map Evolve's provider-neutral network policy onto Modal create() params.
+ *
+ * - outbound "open" (or no policy)     → no restrictions
+ * - outbound "blocked", no allowlist   → blockNetwork: true (drops all egress)
+ * - outbound "blocked" with allowlist  → outboundDomainAllowlist (hostnames,
+ *   wildcards like "*.example.com") + outboundCidrAllowlist (IPs/CIDRs; bare
+ *   IPs get /32 or /128 appended). Both lists are always set because Modal
+ *   treats an unset list as "allow all" — an empty array means "allow none"
+ *   for that class of destination. Note: Modal's domain allowlist only admits
+ *   TLS traffic on port 443; plaintext destinations must be listed as CIDRs.
+ */
+declare function mapNetworkPolicy(network?: SandboxCreateOptions["network"]): ModalNetworkCreateParams;
+/**
+ * The same policy expressed the way Modal's RUNTIME switch takes it: both
+ * allowlists, always.
+ *
+ * Two independent reasons, and the second outlives the first. Modal requires
+ * both today — "Both `outboundCidrAllowlist` and `outboundDomainAllowlist`
+ * must be provided" (modal@0.9.0 index.d.ts:8040) — but that is documented as
+ * temporary ("This requirement will be relaxed in a future release",
+ * index.d.ts:7917-7919). What does not change is the meaning of leaving one
+ * out: "`undefined` leaves that dimension unchanged, while a defined value
+ * replaces it" (index.d.ts:7913-7915). An omitted list therefore CARRIES OVER
+ * whatever the box already had — which for a switch whose whole contract is
+ * "replace the policy" is precisely the silent-widening bug: the dimension the
+ * new policy never mentions would keep the old policy's allowances. Stating
+ * both is what makes the switch a true replace, and it stays correct when
+ * partial updates become legal.
+ *
+ * `blockNetwork` has no runtime form at all, which is why a sealed policy
+ * becomes empty lists here: "an empty array blocks all egress for that
+ * dimension" (index.d.ts:7913-7915).
+ *
+ * Built on mapNetworkPolicy so the classification of a destination — what
+ * counts as a CIDR, what is rejected for carrying a port — is the SAME code
+ * the create path uses. A second copy of that logic is how an update ends up
+ * admitting what the create refused.
+ *
+ * Upstream: harbor modal.py:1236-1249 (`_dynamic_network_kwargs`).
+ */
+declare function dynamicNetworkPolicyParams(network?: SandboxCreateOptions["network"]): {
+    outboundCidrAllowlist: string[];
+    outboundDomainAllowlist: string[];
+};
+/**
+ * Whether this box must be created in the switchable shape: true when any
+ * declared phase policy differs from the boot policy. Order and duplicate
+ * destinations are not meaning (Modal applies a set), so they are normalized
+ * away before comparing — otherwise a caller listing the same hosts in a
+ * different order would arm dynamic mode for no reason.
+ *
+ * Upstream: harbor modal.py:1040-1047 (`_requires_dynamic_network`).
+ */
+declare function requiresDynamicNetwork(network: SandboxCreateOptions["network"], phases: SandboxCreateOptions["phaseNetworkPolicies"]): boolean;
+/** Container registry family for an image tag. */
+type ImageRegistry = "aws-ecr" | "gcp-artifact-registry" | "registry";
+/** Detect which Modal image constructor an image tag needs. */
+declare function resolveImageRegistry(tag: string): ImageRegistry;
+/**
+ * Build a SandboxInfo from a sandbox's tags. Modal exposes no metadata or
+ * public timestamps, so image and startedAt come from the tags stamped at
+ * create time; for sandboxes not created by this SDK they are empty strings
+ * (never fabricated). endAt is always undefined — Modal does not expose it.
+ */
+declare function buildSandboxInfo(sandboxId: string, tags: Record<string, string>, fallbackImage?: string): SandboxInfo;
 /** Result of a completed sandbox command */
 interface SandboxCommandResult {
     exitCode: number;
@@ -93,15 +419,159 @@ interface SandboxCreateOptions {
     image?: string;
     envs?: Record<string, string>;
     metadata?: Record<string, string>;
+    /** Sandbox lifetime in ms. Modal hard-caps lifetime at 24h (MODAL_MAX_LIFETIME_MS). */
     timeoutMs?: number;
+    /**
+     * Terminate the sandbox after this long with nothing running in it — the
+     * bound that reclaims a box whose client died, without waiting out the whole
+     * lifetime. Modal is the only provider with both clocks.
+     *
+     * OMITTED BY DEFAULT: Modal runs no idle timer unless asked. Modal counts a
+     * sandbox active while an exec is running, while its stdin is being written,
+     * or while a tunnel connection is open — file operations are not named in
+     * that list, and this adapter is safe only because it routes reads and writes
+     * through exec (`cat` / `cat >`). A future native filesystem path would need
+     * this re-checked.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * The argv the sandbox boots as its MAIN PROCESS, replacing the image's own
+     * ENTRYPOINT/CMD. Forwarded to Modal's Sandbox.create args — documented as
+     * "Set the CMD of the Sandbox, overriding any CMD of the container image"
+     * (modal.com/docs/reference/modal.Sandbox), and the override is TOTAL in
+     * operation, entrypoint included: Harbor's modal backend documents its
+     * forwarded args as overriding "the image's ENTRYPOINT/CMD" and must pass
+     * None "to inherit the image's command (e.g. dockerd-entrypoint.sh for the
+     * DinD image)" (harbor modal.py:1151-1155) — with args present that DinD
+     * entrypoint would not run at all.
+     *
+     * OMITTED, the image's own ENTRYPOINT/CMD boots as the main process, and a
+     * start program that exits takes the sandbox down with it (harbor
+     * modal.py:285-291). A caller that needs an INERT boot — the box held open
+     * while every process it runs arrives by exec, so whoever execs the image's
+     * start program is its ONLY launcher — passes a keep-alive here (Harbor's
+     * own is ["sh", "-c", "sleep infinity"]).
+     *
+     * An empty argv is REJECTED (ModalBootCommandError): on the wire it is the
+     * same "no args" an omitted option sends, so it would boot the entrypoint
+     * while reading like an override.
+     */
+    bootCommand?: string[];
     workingDirectory?: string;
+    /**
+     * Per-sandbox compute sizing: cpu in cores, memory in GiB — mapped to
+     * Modal's create-time cpu / memoryMiB requests (defaults when omitted:
+     * 4 cores / 4 GiB). `disk` is REJECTED with ModalResourcesError: the Modal
+     * JS SDK exposes no disk-size parameter, so a specific disk size cannot be
+     * enforced (containers get Modal's default disk quota).
+     *
+     * `gpu` + `gpuTypes` become Modal's "<TYPE>:<count>" GPU reservation
+     * ('any' when no types are named; the FIRST type when several — Modal
+     * reserves one type per sandbox; the type passes through verbatim and an
+     * unknown one gets Modal's own typed rejection at create).
+     */
+    resources?: ModalCreateResources;
+    /**
+     * Provider-neutral outbound network policy, enforced by Modal's network
+     * stack. "blocked" with no allowedDestinations drops all egress; with
+     * allowedDestinations, hostnames go to Modal's domain allowlist (TLS/443
+     * only) and IPs/CIDRs to the CIDR allowlist.
+     */
+    network?: {
+        outbound: "open" | "blocked";
+        allowedDestinations?: string[];
+    };
+    /**
+     * Every policy `updateNetwork()` may later be asked for on this box.
+     *
+     * LOAD-BEARING ON MODAL, unlike on the other providers. Modal's create call
+     * takes EITHER `blockNetwork: true` OR the two allowlists — each allowlist
+     * field is documented "Cannot be used with blockNetwork" (modal@0.9.0
+     * index.d.ts:7682-7686) — so the blunt `blockNetwork: true` box this adapter
+     * builds for a sealed policy has no allowlist to widen later. When a phase
+     * policy here differs from `network`, the adapter creates the box in the
+     * switchable shape instead: an empty `outboundCidrAllowlist` — "an empty
+     * array blocks all egress for that dimension" (index.d.ts:7913-7915) — plus
+     * a domain allowlist holding only the unresolvable sentinel, never an empty
+     * one (see withDomainFilteringEnabled: an empty domain list leaves Modal's
+     * domain filter switched OFF and unswitchable). Same zero egress, still
+     * switchable.
+     *
+     * Upstream: harbor modal.py:1040-1047 (`_requires_dynamic_network`) and
+     * :1169-1171 (`if self._dynamic_network: block_network = False`).
+     */
+    phaseNetworkPolicies?: Array<{
+        outbound: "open" | "blocked";
+        allowedDestinations?: string[];
+    }>;
+    /**
+     * Named Modal Volumes mounted into the sandbox at create time, keyed by
+     * the ABSOLUTE in-box mount path. Each entry is resolved through
+     * client.volumes.fromName(name, { createIfMissing }) (modal@0.9.0
+     * index.d.ts:6456) and mounted with its own mount options
+     * (Volume.withMountOptions, index.d.ts:6499-6512) as the create call's
+     * `volumes` record (index.d.ts:7668). A read-only mount is enforced by
+     * Modal in the box (a write answers EROFS).
+     *
+     * WHAT A VOLUME IS FOR: bytes many sandboxes need — Modal's own guidance
+     * for data shared across sandboxes is to load it into a Volume once and
+     * mount it everywhere (modal.com/docs/guide/volumes, /guide/sandbox-files)
+     * — instead of moving them through this provider's per-message stdin
+     * path once per box (MODAL_STDIN_CHUNK_BYTES states that bound). Measured
+     * live 2026-09-08 (160 MiB, python:3.11-slim): a read from a mounted
+     * Volume 0.2-1.1 s (148-773 MiB/s) against 24-37 s per stdin upload.
+     *
+     * FILLING ONE: modal@0.9.0 exposes no upload-to-Volume call, so a Volume
+     * is written from INSIDE a sandbox that mounts it read-write; Modal
+     * commits the writes in the background while that sandbox runs and once
+     * more when it exits (the create call always sets allowBackgroundCommits,
+     * index.js:55511-55521), and a sandbox created after that exit sees the
+     * committed files at boot.
+     *
+     * ABSENT MEANS ABSENT: no option, no `volumes` key on the create call.
+     * Invalid entries are refused with ModalVolumeError before any network
+     * call; a Volume Modal cannot resolve is refused before any sandbox exists.
+     */
+    volumes?: Record<string, ModalVolumeMount>;
+    /**
+     * Run all commands and file operations as this user (default "user"),
+     * enforced via an `su <user> -c` wrapper since Modal executes everything as
+     * root. Pass "root" to run directly as root with no wrapper.
+     */
+    user?: string;
+    /** Home directory used by the SDK for agent config paths; not consumed by the provider. */
+    homeDir?: string;
 }
 /** Options for listing sandboxes */
 interface SandboxListOptions {
+    /** Modal has no paused state; filters that exclude "running" match nothing. */
     state?: ("running" | "paused")[];
     metadata?: Record<string, string>;
     limit?: number;
 }
+/**
+ * A COMPLETE (or admittedly incomplete) enumeration of the app's fleet.
+ *
+ * `complete` is the load-bearing field. Callers that need a whole fleet —
+ * orphan sweeps, lifecycle reconciliation — read a sandbox's ABSENCE from the
+ * list as evidence it is gone, so a truncated walk and a small fleet must never
+ * be the same answer. That includes a walk stopped by the caller's own `limit`:
+ * "you asked for ten and there are more" is a truncated fleet.
+ */
+interface SandboxListPage {
+    sandboxes: SandboxInfo[];
+    complete: boolean;
+    pagesFetched: number;
+    error?: string;
+}
+/**
+ * Sandboxes a single enumeration will walk before it gives up and reports
+ * itself incomplete. Modal's list is an async generator with no page size we
+ * control, so the ceiling is counted in SANDBOXES rather than pages — same
+ * purpose as the other providers' page caps: never return a short list that
+ * reads like a whole one.
+ */
+declare const MODAL_MAX_LIST_SANDBOXES = 10000;
 /** Command execution capabilities */
 interface SandboxCommands {
     /** Run command and wait for completion */
@@ -132,6 +602,8 @@ interface SandboxFiles {
     readStream(path: string): Promise<ReadableStream<Uint8Array>>;
     /** Write from stream */
     writeStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /** Upload a local file by path, streamed off disk (never buffered whole) */
+    writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
     /** Get pre-signed upload URL for large files (expiration in seconds) */
     uploadUrl(path: string, expiresInSeconds?: number): Promise<string>;
     /** Get pre-signed download URL for large files (expiration in seconds) */
@@ -164,17 +636,50 @@ interface SandboxInstance {
     kill(): Promise<void>;
     /** Pause sandbox (preserves state) */
     pause(): Promise<void>;
+    /** Replace the outbound network policy of the running sandbox. */
+    updateNetwork(network: {
+        outbound: "open" | "blocked";
+        allowedDestinations?: string[];
+    }): Promise<void>;
 }
 /** Sandbox lifecycle management */
 interface SandboxProvider {
     /** Provider type identifier */
     readonly providerType: string;
+    /** Human-readable provider name for logging */
+    readonly name?: string;
+    /**
+     * TRUE on every build whose create() maps SandboxCreateOptions.bootCommand
+     * to Modal's create args. A consumer whose safety depends on an inert boot
+     * must CHECK this and refuse a provider without it: an older build would
+     * silently drop the unknown option and boot the image's own ENTRYPOINT/CMD
+     * as the sandbox main process.
+     */
+    readonly supportsBootCommand?: boolean;
+    /**
+     * TRUE on every build whose create() maps SandboxCreateOptions.volumes to
+     * Modal's create-time Volume mounts. Same law as supportsBootCommand: an
+     * older build would silently drop the unknown option and boot a box with
+     * nothing mounted, so a consumer that relies on the mount checks this
+     * before it fills or reads a Volume.
+     */
+    readonly supportsVolumes?: boolean;
     /** Create new sandbox */
     create(options: SandboxCreateOptions): Promise<SandboxInstance>;
     /** Connect to existing sandbox */
     connect(sandboxId: string, timeoutMs?: number): Promise<SandboxInstance>;
-    /** List sandboxes (first page only, up to limit) */
+    /** List sandboxes, walking the whole app. `limit` bounds items returned. */
     list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
+    /** The same enumeration for fleet bookkeeping: never throws, reports completeness. */
+    listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
+    /**
+     * Build or pull the sandbox image ahead of time so a later create() does not
+     * wait for it. Takes what `create({ image })` takes, resolved by the same
+     * path, and defaults to the provider's configured image. Optional on the
+     * same terms as the SDK contract: declared so every provider offering it
+     * offers the same signature.
+     */
+    prepareImage?(image?: string): Promise<void>;
 }
 interface ModalConfig {
     /** Modal app name. Default: "evolve-sandbox" */
@@ -187,8 +692,15 @@ interface ModalConfig {
     tokenSecret?: string;
     /** Modal API endpoint. Default: https://api.modal.com:443 */
     endpoint?: string;
-    /** Docker image name (default: 'evolve-all'). Resolved through IMAGE_MAP or used as-is for custom images. */
+    /** Docker image name (default: 'evolve-all-<EVOLVE_IMAGE_VERSION>'). Resolved through IMAGE_MAP or used as-is for custom images; explicit names pass through untouched. */
     imageName?: string;
+    /**
+     * Name of a Modal Secret holding registry credentials for private images.
+     * Required for AWS ECR (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
+     * AWS_REGION with read-only ECR IAM) and GCP Artifact Registry; optional
+     * for private Docker Hub images. Create one at https://modal.com/secrets
+     */
+    imageSecretName?: string;
 }
 /** Internal resolved config with required credentials */
 interface ResolvedModalConfig {
@@ -198,21 +710,344 @@ interface ResolvedModalConfig {
     defaultTimeoutMs?: number;
     endpoint?: string;
     imageName?: string;
+    imageSecretName?: string;
+}
+declare class ModalCommands implements SandboxCommands {
+    private sandbox;
+    private user;
+    constructor(sandbox: Sandbox, user: string);
+    run(command: string, options?: SandboxRunOptions): Promise<SandboxCommandResult>;
+    spawn(command: string, options?: SandboxSpawnOptions): Promise<SandboxCommandHandle>;
+    list(): Promise<ProcessInfo[]>;
+    connect(_processId: string, _options?: SandboxConnectOptions): Promise<SandboxCommandHandle>;
+    sendStdin(_processId: string, _data: string): Promise<void>;
+    kill(processId: string): Promise<boolean>;
+    /**
+     * Accumulate stdout/stderr using for-await pattern (more reliable with Modal streams).
+     * Based on vibekit's approach which works correctly with Modal SDK.
+     */
+    private accumulateStreams;
+}
+declare class ModalFiles implements SandboxFiles {
+    private sandbox;
+    private user;
+    constructor(sandbox: Sandbox, user: string);
+    /**
+     * Chown a path to the sandbox user so agent CLIs (running via the su
+     * wrapper) can access files created by root-level exec. No-op when the
+     * sandbox user is root.
+     */
+    private chownToUser;
+    /**
+     * Write a payload to a process's stdin in MODAL_STDIN_CHUNK_BYTES slices.
+     * Each writeBytes() call becomes one gRPC TaskExecStdinWrite message and
+     * Modal rejects messages over 100MiB, so large files must be chunked
+     * (multi-hundred-MB payloads are common).
+     */
+    private writeStdinChunked;
+    /**
+     * Stream a byte source into a process's stdin, buffering it into
+     * MODAL_STDIN_CHUNK_BYTES writes rather than forwarding the source's own
+     * chunk size.
+     *
+     * WHY this exists rather than the SDK's own file copy. Modal documents
+     * "convenience APIs for streaming file copies in both directions"
+     * (https://modal.com/docs/guide/sandbox-files), but the JS
+     * `filesystem.copyFromLocal()` in modal@0.9.0 streams the local file with
+     * a bare `createReadStream(localPath)` — Node's default 64KiB highWaterMark
+     * — and awaits one unary TaskExecStdinWrite per chunk. Modal's own Python
+     * SDK reads TASK_COMMAND_ROUTER_MAX_BUFFER_SIZE (16MiB) per chunk for the
+     * same operation, so the 64KiB default is a JS-side omission, not a
+     * transport limit. Since the size is not a parameter of copyFromLocal(),
+     * the native call cannot be made to send larger messages.
+     *
+     * Measured, 180MiB payload: 64KiB 311.6s (2880 messages), native
+     * copyFromLocal 308.7s, 4MiB 36.2s, 8MiB 30.1s, 16MiB 31.4s. The upload is
+     * round-trip bound until roughly 4MiB and throughput bound after it, so the
+     * fix is message SIZE rather than which sink receives the bytes — the
+     * exec-stdin sink stays and the chunking changes.
+     *
+     * Peak memory stays at one chunk plus the source's own, never the whole
+     * payload: bundles run to hundreds of MB while workers hold many trials in
+     * a small heap.
+     */
+    private writeStdinCoalesced;
+    read(path: string): Promise<string | Uint8Array>;
+    write(path: string, content: string | Buffer | ArrayBuffer | Uint8Array): Promise<void>;
+    writeBatch(files: Array<{
+        path: string;
+        data: string | Buffer | ArrayBuffer | Uint8Array;
+    }>): Promise<void>;
+    makeDir(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    list(path: string): Promise<FileInfo[]>;
+    remove(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    readStream(path: string): Promise<ReadableStream<Uint8Array>>;
+    writeStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * Upload a local file by PATH, chunk by chunk into the same `cat >` sink
+     * writeStream() uses — so peak memory is one chunk rather than the whole
+     * file, which is what makes a large artifact safe under concurrency.
+     *
+     * The read is sized to MODAL_STDIN_CHUNK_BYTES instead of Node's 64KiB
+     * default because every chunk costs one awaited round trip to Modal: the
+     * same 180MiB bundle took 311.6s at 64KiB and 30.1s at 8MiB (measured, one
+     * sandbox, same file). writeStdinCoalesced would batch a small-chunk stream
+     * anyway; asking the filesystem for whole chunks just avoids assembling
+     * them from 128 pieces.
+     */
+    writeFromPath(sandboxPath: string, localPath: string): Promise<void>;
+    uploadUrl(_path: string, _expiresInSeconds?: number): Promise<string>;
+    downloadUrl(_path: string, _expiresInSeconds?: number): Promise<string>;
+    watchDir(_path: string, _onEvent: (event: FilesystemEvent) => void | Promise<void>, _options?: WatchOptions): Promise<WatchHandle>;
+    private toBuffer;
+}
+declare class ModalSandboxImpl implements SandboxInstance {
+    private sandbox;
+    readonly commands: SandboxCommands;
+    readonly files: SandboxFiles;
+    private readonly image?;
+    constructor(sandbox: Sandbox, image: string | undefined, user: string);
+    get sandboxId(): string;
+    getHost(port: number): Promise<string>;
+    isRunning(): Promise<boolean>;
+    getInfo(): Promise<SandboxInfo>;
+    /**
+     * Replace the running sandbox's outbound policy — Modal's
+     * `Sandbox.updateNetworkPolicy`, "Updates the outbound network policy of a
+     * running Sandbox. Established connections that the new policy no longer
+     * permits are terminated." (modal@0.9.0 index.d.ts:8035-8042).
+     *
+     * The policy is mapped by dynamicNetworkPolicyParams — the create path's own
+     * classification — so an update can never admit a destination the create
+     * would have refused.
+     *
+     * WHAT THIS CANNOT FIX: a box created with `blockNetwork: true` has no
+     * allowlist for Modal to widen, because create refuses the two together
+     * (index.d.ts:7682-7686). Declare `phaseNetworkPolicies` at create and the
+     * adapter builds the box switchable instead. Modal's refusal in that case is
+     * its own error, surfaced verbatim rather than reinterpreted here — guessing
+     * at a remote refusal is how a real quota or auth failure gets mislabelled.
+     */
+    updateNetwork(network: {
+        outbound: "open" | "blocked";
+        allowedDestinations?: string[];
+    }): Promise<void>;
+    kill(): Promise<void>;
+    pause(): Promise<void>;
 }
 declare class ModalProvider implements SandboxProvider {
     readonly providerType: "modal";
     readonly name = "Modal";
+    /** create() maps bootCommand (see SandboxCreateOptions.bootCommand). */
+    readonly supportsBootCommand = true;
+    /** create() maps volumes (see SandboxCreateOptions.volumes). */
+    readonly supportsVolumes = true;
     private readonly client;
     private readonly appName;
     private readonly defaultTimeoutMs;
     private readonly imageName;
+    private readonly imageSecretName?;
     private _app;
+    /**
+     * Sandbox user configured at create time, reapplied on connect() so the su
+     * wrapper keeps targeting the same account. In-memory only: a connect()
+     * from a fresh process falls back to the default "user" account — callers
+     * reconnecting across processes must recreate the provider and sandbox with
+     * the same user, or operations on user-owned files fail loudly.
+     */
+    private readonly sandboxUsers;
     constructor(config: ResolvedModalConfig);
     private getApp;
+    /**
+     * Build a Modal Image for the resolved tag, routing private registries
+     * (AWS ECR, GCP Artifact Registry) through the configured Modal Secret.
+     *
+     * Digest-pinned ECR refs (`<repo>@sha256:<digest>`) are accepted by
+     * fromAwsEcr — verified LIVE against Modal 2026-08-21 (built and booted a
+     * sandbox from one). Modal's docs never say so (the modal.Image reference
+     * describes the parameter only as "Full ECR image URI", tag-form example),
+     * so treat the capability as observed behavior, not contract.
+     */
+    private resolveImage;
+    /**
+     * Resolve a requested image name to the Modal image identity, eagerly
+     * building it when it is a registry reference and resolving WITHOUT a build
+     * when it is a published Modal image name. The ONE place that resolution
+     * happens, because create(), prepareImage() and publishImageAs() drifting
+     * apart is a silent failure: the prewarm would populate one image while
+     * trials created against another, and nothing would report the mismatch —
+     * only the cold-start cost prewarm was meant to remove would quietly come
+     * back.
+     *
+     * "Eagerly builds an Image on Modal" — the SDK's own description of
+     * Image.build(app) (modal@0.9.0, dist/index.d.ts). The call is idempotent:
+     * the same reference returns the same cached imageId, so the first caller
+     * pays the registry pull and later ones resolve quickly.
+     */
+    private resolveAndBuildImage;
+    /**
+     * Build (or pull) an image on Modal ahead of time, so the sandbox that
+     * needs it later does not wait for it.
+     *
+     * Modal's own guidance: "To avoid blocking creation of new Sandboxes on
+     * rebuilding an invalidated Image, it's recommended to use Modal's named
+     * Images with sandboxes, rather than using inline Image definitions", and
+     * "Use `Image.build` to trigger Image builds as part of a deployment flow
+     * or at a regular interval (e.g., in a scheduled job or CI pipeline)"
+     * (https://modal.com/docs/guide/sandbox). This is that deployment-flow
+     * call: run it at publish time, and trial-time create() finds the image
+     * already built.
+     *
+     * `imageName` takes exactly what `create({ image })` takes and is resolved
+     * by the identical path, so callers prewarm the image they will actually
+     * run on rather than a reconstruction of it. Omitted, it prewarms the
+     * provider's configured default — again what create() would have chosen.
+     *
+     * There is deliberately no sizing parameter: on Modal, image identity is
+     * the registry reference alone, and CPU/memory/GPU are create-time sandbox
+     * options, so one eager build serves every sizing.
+     *
+     * OPERATIONAL TRAP, and prewarming at publish time is what makes it likely.
+     * From the same guide: "Modal treats external Image tags as immutable once
+     * pulled" and "Modal does not detect upstream changes to mutable tags like
+     * `:latest`". So prewarming a MUTABLE tag after re-pushing that tag warms
+     * the OLD image, and every later create() keeps launching the old image —
+     * quietly, because the reference still resolves. Modal's own remedy is to
+     * "update the tag in your deploy script (for example, `ubuntu:24.04` →
+     * `ubuntu:24.04-20240523`)".
+     *
+     * The versioned default (evolve-all-<c-hash>) is immune, because a content
+     * change moves the tag. The exposed legacy alias "evolve-all" is NOT: it
+     * maps to the mutable Docker Hub name, so prewarming it after a re-push
+     * warms the stale image. That alias is precisely why EVOLVE_IMAGE_VERSION
+     * exists — prewarm the versioned name unless you specifically want the
+     * account's already-pulled copy.
+     */
+    /**
+     * Give a built image OUR name on Modal, so it can be found — and deleted —
+     * later by a name this platform minted rather than an id Modal minted.
+     *
+     * WHY THIS EXISTS. Every other provider hands back a named artifact: an e2b
+     * template alias, a daytona snapshot name. Modal's image identity is the
+     * registry reference plus an opaque server-side id, and its delete verb
+     * (`client.images.delete`) takes the ID — which only exists after a build and
+     * is never returned by any lookup we could do later from a reference alone.
+     * So a Modal image built for a dataset could never be reclaimed when that
+     * dataset was deleted; the platform recorded the honest refusal
+     * `store_unsupported` and the images accumulated.
+     *
+     * `Image.publish(name)` closes that: it binds a stable name to the built
+     * image, and `images.fromName(name)` resolves that name back to the id
+     * WITHOUT rebuilding (it is a plain `imageGetByTag` lookup). Named, findable,
+     * deletable — the same shape the other two providers already have.
+     *
+     * IDEMPOTENT BY CONSTRUCTION for our use: the alias is a content address, so
+     * re-publishing the same alias re-binds it to the image that same content
+     * built. A caller that publishes twice names the same bytes twice.
+     *
+     * The build goes through resolveAndBuildImage, the ONE pair every other path
+     * uses, so a published image and the image a trial creates against cannot be
+     * different images — the same law prepareImage keeps.
+     *
+     * MODAL-ONLY, deliberately not on the shared provider interface: e2b and
+     * daytona name their artifacts at creation and have nothing to publish. The
+     * platform feature-detects this method rather than every provider carrying a
+     * verb only one of them can honor.
+     */
+    publishImageAs(alias: string, imageName?: string): Promise<string>;
+    prepareImage(imageName?: string): Promise<void>;
     create(options: SandboxCreateOptions): Promise<SandboxInstance>;
+    /**
+     * The validated mounts -> Modal's `volumes` create record: each Volume
+     * resolved by name (client.volumes.fromName, createIfMissing as declared)
+     * and carrying its mount options (withMountOptions — readOnly stated
+     * explicitly both ways, since the SDK keeps undefined fields from any
+     * earlier call on the same Volume object). Modal's NotFoundError becomes
+     * ModalVolumeError "not-found", anything else "resolve-failed", both with
+     * Modal's error as the cause. Undefined when there is nothing to mount.
+     */
+    private resolveVolumes;
     connect(sandboxId: string, _timeoutMs?: number): Promise<SandboxInstance>;
-    list(_options?: SandboxListOptions): Promise<SandboxInfo[]>;
+    /**
+     * List sandboxes, walking the whole app.
+     *
+     * This used to stop at a hardcoded default of 100 regardless of fleet size,
+     * which silently truncated any app with more — and said nothing about it
+     * while the shared SandboxProvider interface promised exhaustive listing.
+     * `limit` still bounds the sandboxes RETURNED, so a caller wanting one cheap
+     * sample asks for one; without it the answer is the whole app.
+     *
+     * The O(N)-round-trips warning below is unchanged and is the reason `limit`
+     * matters here more than on the other providers.
+     */
+    list(options?: SandboxListOptions): Promise<SandboxInfo[]>;
+    /**
+     * The fleet-bookkeeping enumeration: same walk, never throws.
+     *
+     * Modal has no lifecycle webhooks, so absence from a list is the ONLY
+     * termination signal either lane gets — which makes the difference between
+     * "the app is empty" and "the enumeration stopped early" the difference
+     * between a quiet fleet and one about to be reclaimed.
+     *
+     * NOTE the divergence from `listSandboxIds` below, which returns an EMPTY set
+     * on failure on the grounds that partial results are worse than none for a
+     * terminal-state decision. This one returns what it saw alongside
+     * `complete: false`. Both are safe because `complete` is what callers branch
+     * on, and the shared type documents the choice; do not align one to the other
+     * without deciding which rule you want.
+     */
+    listAll(options?: SandboxListOptions): Promise<SandboxListPage>;
+    private walk;
+    /**
+     * Live sandbox ids for the whole app, in ONE streamed call and O(1) round
+     * trips — the fleet-bookkeeping counterpart to `list()`.
+     *
+     * Exists because `list()` cannot be made cheap without dropping metadata from
+     * its contract: it owes callers a populated `SandboxInfo.metadata`, and Modal
+     * only serves tags per sandbox. Anything that just needs "which ids are
+     * alive" — lifecycle polling, orphan sweeps, reconciliation — uses this and
+     * pays one request no matter how large the fleet is.
+     *
+     * `complete` is the load-bearing field, not a nicety: absence from this list
+     * is what callers read as "terminated", so a truncated or errored enumeration
+     * MUST NOT be mistaken for an empty fleet. A caller that sees complete=false
+     * has to leave rows alone rather than mass-marking live sandboxes dead.
+     */
+    listSandboxIds(): Promise<{
+        ids: Set<string>;
+        complete: boolean;
+    }>;
+}
+/** The streamed sandbox surface this walk needs — Modal's list() satisfies it. */
+interface ModalSandboxStream {
+    sandboxId: string;
+    getTags(): Promise<Record<string, string>>;
 }
+/**
+ * Drain Modal's sandbox generator into one answer, with an honest completeness
+ * verdict.
+ *
+ * Separate from the provider because everything worth getting wrong lives here
+ * and none of it needs a gRPC connection: the difference between "the caller
+ * asked for ten" and "the app ran out", the ceiling that stops an unbounded
+ * walk, and the rule that a failure mid-walk yields what it saw marked
+ * INCOMPLETE rather than an exception or a short complete list.
+ *
+ * COST WARNING — this loop is O(N) ROUND TRIPS, not O(1). `list()` itself is one
+ * streamed call, but `getTags()` is a separate gRPC request per sandbox
+ * (`sandboxTagsGet`), so listing N sandboxes costs N+1 calls. That is fine for a
+ * user listing their handful of boxes with metadata, and NOT fine for fleet-wide
+ * bookkeeping: anything that only needs to know WHICH ids are alive must use
+ * `listSandboxIds`, never this. Please do not "optimize" by reintroducing tag
+ * reads into those paths.
+ *
+ * Exported for its test (`_testCollectSandboxes`).
+ */
+declare function collectSandboxes(iterate: () => AsyncIterable<ModalSandboxStream>, wanted?: number): Promise<SandboxListPage & {
+    stoppedAtLimit: boolean;
+}>;
 /**
  * Create Modal sandbox provider.
  *
@@ -222,5 +1057,26 @@ declare class ModalProvider implements SandboxProvider {
  * @see https://github.com/evolving-machines-lab/evolve/issues/8
  */
 declare function createModalProvider(config?: ModalConfig): SandboxProvider;
+declare const _testWrapCommand: typeof wrapCommand;
+declare const _testImageMap: Record<string, string>;
+declare const _testMapNetworkPolicy: typeof mapNetworkPolicy;
+declare const _testDynamicNetworkPolicyParams: typeof dynamicNetworkPolicyParams;
+declare const _testRequiresDynamicNetwork: typeof requiresDynamicNetwork;
+declare const _testMapResources: typeof mapResources;
+declare const _testResolveImageRegistry: typeof resolveImageRegistry;
+declare const _testBuildSandboxInfo: typeof buildSandboxInfo;
+declare const _testCollectSandboxes: typeof collectSandboxes;
+declare const _testValidateTimeout: typeof validateTimeout;
+declare const _testMapIdleTimeout: typeof mapIdleTimeout;
+declare const _testMapBootCommand: typeof mapBootCommand;
+declare const _testMapVolumeMounts: typeof mapVolumeMounts;
+/**
+ * TYPE-ONLY handle on the concrete sandbox class, for the contract-conformance
+ * seam. create() is declared to return the local SandboxInstance INTERFACE, so
+ * a seam reading create()'s return type checks the interface and never the
+ * class — which let a narrowed method on the class pass unnoticed. Exporting
+ * the type (never the constructor) gives the seam the real methods to pin.
+ */
+type _testModalSandboxImpl = ModalSandboxImpl;
 
-export { type FileInfo, type FilesystemEvent, type ModalConfig, ModalProvider, type ProcessInfo, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxConnectOptions, type SandboxCreateOptions, type SandboxFiles, type SandboxInfo, type SandboxInstance, type SandboxListOptions, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type WatchHandle, type WatchOptions, createModalProvider };
+export { EVOLVE_IMAGE_VERSION, type FileInfo, type FilesystemEvent, MODAL_MAX_LIFETIME_MS, MODAL_MAX_LIST_SANDBOXES, MODAL_STDIN_CHUNK_BYTES, ModalBootCommandError, ModalCommands, type ModalConfig, ModalFiles, ModalIdleTimeoutError, ModalNetworkPolicyError, type ModalNetworkPolicyReason, ModalProvider, ModalResourcesError, ModalSandboxLifetimeError, type ModalSandboxStream, ModalVolumeError, type ModalVolumeErrorReason, type ModalVolumeMount, type ProcessInfo, type SandboxCommandHandle, type SandboxCommandResult, type SandboxCommands, type SandboxConnectOptions, type SandboxCreateOptions, type SandboxFiles, type SandboxInfo, type SandboxInstance, type SandboxListOptions, type SandboxListPage, type SandboxProvider, type SandboxRunOptions, type SandboxSpawnOptions, type WatchHandle, type WatchOptions, _testBuildSandboxInfo, _testCollectSandboxes, _testDynamicNetworkPolicyParams, _testImageMap, _testMapBootCommand, _testMapIdleTimeout, _testMapNetworkPolicy, _testMapResources, _testMapVolumeMounts, type _testModalSandboxImpl, _testRequiresDynamicNetwork, _testResolveImageRegistry, _testValidateTimeout, _testWrapCommand, createModalProvider };