@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/modal/capabilities.js

@@ -0,0 +1,159 @@
+/**
+ * SDK-free capability metadata for the Modal adapter.
+ *
+ * House rule: a behavioral claim stays `false` until a live probe against the
+ * pinned SDK establishes it. "The SDK has a method for it" is not evidence —
+ * a method can exist and degrade, and a capability means *reachable through
+ * this package's port*, not *present in the vendor surface*.
+ */
+export const modalSandboxCapabilities = {
+    /**
+     * Modal genuinely has server-side label search: `sandboxes.list({ tags })`
+     * returns only sandboxes carrying all the given tags, and the adapter routes
+     * every lookup through it. That is a real warm-lease implementation, unlike
+     * providers where `findAllByLabels` degrades to `[]`.
+     *
+     * It is nevertheless declared `false` until the live canary proves that a
+     * tagged sandbox is actually returned by a tag-filtered list. Promoting it
+     * on the strength of a type signature is exactly the inference this field
+     * exists to prevent, and `false` fails in the safe direction: the
+     * orchestrator declines to rely on warm leases rather than leaking them.
+     */
+    warmLease: false,
+    /**
+     * Permanently false, and not pending verification.
+     *
+     * Modal exposes no stop/start for a Sandbox. `terminate()` is the only
+     * lifecycle transition and it is terminal — there is no suspend, resume, or
+     * wake. The adapter therefore omits `start`/`stop` entirely rather than
+     * shipping no-ops, and this flag records the structural fact for the
+     * capability resolver, which cannot see an absent method.
+     */
+    lifecycle: false,
+};
+/**
+ * Bootstrap-plane capabilities. Note this is `RuntimeCapabilities` from
+ * `../types.js` — the live in-sandbox plane — and NOT the orchestration-plane
+ * `SandboxRuntimeCapabilities`. The two are deliberately distinct.
+ */
+export const modalWorkflowCapabilities = {
+    /**
+     * Modal supports PTY on both `create` and `exec` (`pty: true`, which
+     * multiplexes stderr into stdout). This package's port exposes no PTY
+     * operation, so it is not reachable here.
+     */
+    pty: false,
+    /**
+     * Modal exposes real filesystem snapshots — `snapshotFilesystem()` and
+     * `snapshotDirectory(path)`, both returning an `Image` reusable as a create
+     * source (30-day default TTL, `ttlMs: null` to retain indefinitely). This
+     * package's port exposes no snapshot operation, so the capability is not
+     * reachable through it. Documented here so the surface is not lost.
+     */
+    snapshots: false,
+    /** Modal Sandboxes are gVisor-isolated containers with their own filesystem. */
+    isolation: "strong",
+    /** A sandbox id survives the client: `sandboxes.fromId(id)` re-resolves it. */
+    persistentHandle: true,
+    /**
+     * `exec()` returns live `stdout`/`stderr` as `ReadableStream`s, so Modal can
+     * genuinely stream. The adapter drains them to completion to satisfy the
+     * port's buffered `RunScriptResult`, and the port exposes no streaming
+     * surface, so this is false *for this port* while true of the provider.
+     */
+    streamingLogs: false,
+};
+/** Nothing promoted yet: no live run has happened. Awaiting credentials. */
+export const modalObservedCapabilities = {
+    cleanupVerified: false,
+    snapshotCapture: false,
+    warmLease: false,
+    reattach: false,
+    lifecycle: false,
+    neverIdle: false,
+    lifetimeOverride: false,
+    concurrencyCeiling: false,
+};
+/**
+ * Cells that are **settled structural facts**, not pending observations.
+ *
+ * The distinction matters for review: everything else in
+ * {@link modalObservedCapabilities} is `false` only because no live run has
+ * happened yet and will flip when one does. These two are `false` because the
+ * provider cannot do the thing at all, so a future canary must not "promote"
+ * them and a future reader must not try to "fix" them.
+ */
+export const MODAL_STRUCTURALLY_FALSE = [
+    "lifecycle",
+    "neverIdle",
+];
+/**
+ * Structured capability modes for the Modal adapter.
+ *
+ * Every cell below restates, in the type system, something this file already
+ * documented in prose. That is the whole reason to fill them in: the booleans
+ * above cannot distinguish "Modal cannot do this" from "Modal can, but our port
+ * exposes no operation reaching it" from "nobody has checked yet", and this
+ * adapter is the one that had to work around that by hand — see
+ * {@link MODAL_STRUCTURALLY_FALSE}.
+ *
+ * Note what is deliberately *not* here: `warmLease` stays a `false` boolean
+ * pending the live canary. Modes describe the shape of a capability, not its
+ * verification state, so a mode is not a back door for promoting a cell that
+ * the house rule keeps unproven.
+ */
+export const modalCapabilityModes = {
+    /**
+     * `buffered`, not `separate-streams`.
+     *
+     * Modal's `exec()` does return live `stdout`/`stderr` as separate
+     * `ReadableStream`s, and `runScript` does hand back separated `stdout` and
+     * `stderr` fields. But both streaming members of the union require output to
+     * be *streamed live*, and the adapter drains both pipes to completion with
+     * `readText()` before it returns anything. Separated-after-the-fact is still
+     * buffered. Declaring `separate-streams` would promise callers an incremental
+     * channel this port does not have.
+     */
+    outputStreams: "buffered",
+    /**
+     * Anything written is lost when the sandbox goes away, and on Modal it always
+     * goes away: `terminate()` is the only lifecycle transition and it is
+     * terminal. There is no stop/start pair for state to survive across, so
+     * `persistent` cannot apply.
+     */
+    filesystem: "ephemeral",
+    /**
+     * The structural fact behind `neverIdle: false` in
+     * {@link MODAL_STRUCTURALLY_FALSE}, now stated in the type rather than in a
+     * hand-maintained list. *Every* Modal Sandbox carries a maximum lifetime —
+     * five minutes by default, 24 hours at the ceiling (`MODAL_MAX_LIFETIME_MS`),
+     * and the provider terminates it when that elapses. There is no "no deadline"
+     * setting, so no live run can ever move this.
+     *
+     * `deadline` says that on its own; per the union's own note, a provider that
+     * always terminates at a deadline cannot offer a never-idle tier, so this
+     * needs no separate `unsupported`.
+     */
+    lifetime: "deadline",
+    /**
+     * `not-exposed`, emphatically not `unsupported`: Modal supports PTY on both
+     * `create` and `exec` (`pty: true`). This package's port declares no PTY
+     * operation, so it is unreachable *here*. It moves if someone adds one — and
+     * `isPendingEvidence()` correctly reports false for it, because no canary
+     * against Modal can change a fact about our own port surface.
+     */
+    interactive: "not-exposed",
+    /**
+     * Also `not-exposed`. Modal has real filesystem snapshots —
+     * `snapshotFilesystem()` and `snapshotDirectory(path)`, both returning an
+     * `Image` reusable as a create source. The port exposes no snapshot
+     * operation, so the capability is not reachable through it.
+     *
+     * This is exactly the cell the absence vocabulary was added to protect:
+     * `modalObservedCapabilities.snapshotCapture` is a *pending* observation
+     * about the provider, while this is a *settled* fact about our port. A canary
+     * may promote that one; it must never promote this one.
+     */
+    snapshots: "not-exposed",
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/modal/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/modal/capabilities.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,KAAK;IAChB;;;;;;;;OAQG;IACH,SAAS,EAAE,KAAK;CACqC,CAAC;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC;;;;OAIG;IACH,GAAG,EAAE,KAAK;IACV;;;;;;OAMG;IACH,SAAS,EAAE,KAAK;IAChB,gFAAgF;IAChF,SAAS,EAAE,QAAQ;IACnB,+EAA+E;IAC/E,gBAAgB,EAAE,IAAI;IACtB;;;;;OAKG;IACH,aAAa,EAAE,KAAK;CACkB,CAAC;AAoCzC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,yBAAyB,GAA8B;IAClE,eAAe,EAAE,KAAK;IACtB,eAAe,EAAE,KAAK;IACtB,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;IAChB,gBAAgB,EAAE,KAAK;IACvB,kBAAkB,EAAE,KAAK;CAC1B,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,WAAW;IACX,WAAW;CACsD,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC;;;;;;;;;;OAUG;IACH,aAAa,EAAE,UAAU;IACzB;;;;;OAKG;IACH,UAAU,EAAE,WAAW;IACvB;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,UAAU;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,aAAa;IAC1B;;;;;;;;;;OAUG;IACH,SAAS,EAAE,aAAa;CACiB,CAAC"}

package/dist/modal/config.d.ts

@@ -0,0 +1,192 @@
+/**
+ * SDK-free configuration for the Modal adapter.
+ *
+ * Nothing in this module imports the vendor SDK, so config can be constructed,
+ * validated, and asserted on without pulling in a gRPC stack.
+ *
+ * Modal's object model is not the one this package's port assumes, and the
+ * difference is load-bearing rather than cosmetic:
+ *
+ *  - A Modal Sandbox is **a child of an App**, created from an **Image**.
+ *    `sandboxes.create(app, image, params)` takes both as required arguments.
+ *    There is no "just make me a sandbox" entry point, so `appName` and
+ *    `imageTag` are required here. No default is correct for every consumer,
+ *    and this package bakes none in.
+ *  - A Modal Sandbox has a **maximum lifetime**, after which the provider
+ *    terminates it. The SDK's default is five minutes. That default is a trap
+ *    for every caller who expects E2B/Daytona semantics, so `maxLifetimeMs` is
+ *    required and always sent explicitly — see {@link ModalRuntimeOptions.maxLifetimeMs}.
+ *  - A Modal Sandbox **cannot be stopped and restarted**. `terminate()` is the
+ *    only lifecycle transition and it is terminal.
+ */
+/**
+ * Modal credentials. Modal does not use a single bearer key: it authenticates
+ * with a token *pair*. Both halves are required, and neither is ever read from
+ * ambient process state — credential sourcing belongs to the caller.
+ */
+export interface ModalCredentials {
+    /** Modal token id, conventionally prefixed `ak-`. */
+    tokenId: string;
+    /** Modal token secret, conventionally prefixed `as-`. */
+    tokenSecret: string;
+}
+/** Compute shape requested for each sandbox. Drives both placement and billing. */
+export interface ModalResourceShape {
+    /**
+     * Reservation of **physical** CPU cores; may be fractional. Modal counts one
+     * physical core as two vCPU, so a "2 vCPU" reference shape is `cpu: 1`.
+     * Modal enforces a floor of 0.125 cores per container.
+     */
+    cpu?: number;
+    /** Hard CPU limit in physical cores. Omitted means no limit beyond the reservation. */
+    cpuLimit?: number;
+    /** Memory reservation in MiB. */
+    memoryMiB?: number;
+    /** Hard memory limit in MiB. */
+    memoryLimitMiB?: number;
+}
+export interface ModalRuntimeOptions {
+    /** Modal token pair. Required; never sourced from the environment here. */
+    credentials: ModalCredentials;
+    /**
+     * Name of the Modal App that owns every sandbox this runtime creates.
+     * Required: Modal has no appless sandbox, and no app name is universally
+     * correct. The adapter resolves it with `apps.fromName(name, {createIfMissing})`.
+     */
+    appName: string;
+    /**
+     * Whether the adapter may create `appName` if it does not exist. Defaults to
+     * `false`: creating provider-side objects as a side effect of a lookup is the
+     * kind of thing a caller should opt into, not discover.
+     */
+    createAppIfMissing?: boolean;
+    /**
+     * Registry tag for the sandbox image, e.g. `python:3.13` or a private
+     * registry reference. Required for the same reason as `appName`.
+     */
+    imageTag: string;
+    /**
+     * Modal environment name. Omitted means the credential's default environment.
+     * Set it to scope resources away from `main`.
+     */
+    environment?: string;
+    /** Optional control-plane endpoint override. Omitted uses the SDK's endpoint. */
+    endpoint?: string;
+    /**
+     * Home directory inside the image. Required because it is image-specific and
+     * no universal default exists.
+     */
+    defaultHomeDir: string;
+    /** Working directory for the sandbox and for exec'd commands. Defaults to `defaultHomeDir`. */
+    workdir?: string;
+    /**
+     * Prefix identifying resources this runtime is allowed to own. Used both as
+     * the sandbox name prefix and as the value of the ownership tag.
+     */
+    namePrefix: string;
+    /**
+     * Tag key carrying the ownership marker. Defaults to `agentRelayOwner`.
+     *
+     * Ownership is enforced through Modal's **server-side tag filter**, not
+     * through client-side name matching: `sandboxes.list({ tags })` returns only
+     * sandboxes carrying *all* the given tags, so injecting the ownership tag
+     * into every lookup makes cross-tenant collision structurally impossible
+     * rather than merely unlikely.
+     */
+    ownerTagKey?: string;
+    /**
+     * **Maximum sandbox lifetime.** Required, and deliberately so.
+     *
+     * Modal terminates a sandbox once this elapses, whether or not work is still
+     * running, and the SDK's own default is 5 minutes. Every other provider this
+     * package adapts treats a sandbox as living until told otherwise, so silently
+     * inheriting a 5-minute cap would strand callers' long-running work with no
+     * diagnosable cause. Making it required forces the decision into the open.
+     *
+     * This is NOT a request deadline. For that, see `createTimeoutMs`.
+     */
+    maxLifetimeMs: number;
+    /**
+     * Idle timeout in milliseconds — an independent knob from `maxLifetimeMs`.
+     * Omitted means Modal applies no idle termination.
+     */
+    idleTimeoutMs?: number;
+    /** Compute shape for each sandbox. Omitted fields fall back to Modal's defaults. */
+    resources?: ModalResourceShape;
+    /** Cloud provider to place sandboxes on. Omitted lets Modal choose. */
+    cloud?: string;
+    /** Region(s) to place sandboxes in. Omitted lets Modal choose. */
+    regions?: string[];
+    /** Block all outbound network access from the sandbox. */
+    blockNetwork?: boolean;
+    /** Per-request deadline handed to the SDK client. Default 30_000. */
+    requestTimeoutMs?: number;
+    /** Total deadline for a create call. Default 120_000. */
+    createTimeoutMs?: number;
+    /** Total deadline for list/get/count calls. Default 30_000. */
+    lookupTimeoutMs?: number;
+    /** Default deadline for a single exec when the caller does not supply one. Default 120_000. */
+    execTimeoutMs?: number;
+    /** Deadline for terminate plus its post-condition check. Default 60_000. */
+    destroyTimeoutMs?: number;
+    /** Deadline for a file upload. Default 60_000. */
+    uploadTimeoutMs?: number;
+    /** Polling interval for delete verification. Default 500. */
+    pollIntervalMs?: number;
+    /**
+     * Re-check each listed sandbox's tags in-process instead of trusting the
+     * server-side filter. Defaults to `true`.
+     *
+     * `sandboxes.list({ tags })` is documented to return only sandboxes carrying
+     * all the requested tags, and this adapter's whole ownership model rests on
+     * that. But a filter that is silently ignored, partially applied, or changed
+     * by a future release would hand a caller a **foreign sandbox as a warm
+     * lease** — strictly worse than returning no lease at all, because the caller
+     * would then exec into someone else's container. Until `warmLease` is
+     * promoted by a live probe, the filter is an unproven claim, and this adapter
+     * does not build ownership on unproven claims.
+     *
+     * The cost is real and worth stating: unlike providers that return tags
+     * inline with the listing, Modal's `Sandbox` object exposes `getTags()` as a
+     * separate call, so verification costs **one extra round trip per candidate**.
+     * Callers who have measured the filter and accept the risk can set this to
+     * `false`; the default errs toward correctness.
+     */
+    verifyTagsClientSide?: boolean;
+}
+/** Defaults applied by {@link resolveModalRuntimeOptions}. */
+export declare const MODAL_DEFAULTS: {
+    readonly ownerTagKey: "agentRelayOwner";
+    readonly createAppIfMissing: false;
+    readonly verifyTagsClientSide: true;
+    readonly requestTimeoutMs: 30000;
+    readonly createTimeoutMs: 120000;
+    readonly lookupTimeoutMs: 30000;
+    readonly execTimeoutMs: 120000;
+    readonly destroyTimeoutMs: 60000;
+    readonly uploadTimeoutMs: 60000;
+    readonly pollIntervalMs: 500;
+};
+/**
+ * Modal's documented floor for a CPU reservation. Requesting less is rejected
+ * here rather than at the provider, so the failure names the real cause.
+ */
+export declare const MODAL_MIN_CPU_CORES = 0.125;
+/**
+ * Modal's documented hard ceiling on a sandbox's maximum lifetime: 24 hours.
+ *
+ * Beyond this the provider offers no continuous-run option at all — its own
+ * guidance is to take a filesystem snapshot and restore it into a *new*
+ * sandbox. So a request for a longer-lived sandbox is not merely optimistic,
+ * it is unsatisfiable, and it fails here rather than at create time.
+ */
+export declare const MODAL_MAX_LIFETIME_MS: number;
+/** Config with every optional field resolved. */
+export type ResolvedModalRuntimeOptions = Omit<ModalRuntimeOptions, keyof typeof MODAL_DEFAULTS | "workdir"> & {
+    [K in keyof typeof MODAL_DEFAULTS]-?: NonNullable<ModalRuntimeOptions[K]>;
+} & {
+    workdir: string;
+};
+/** Validate and normalize caller config. Throws on anything unusable. */
+export declare function resolveModalRuntimeOptions(options: ModalRuntimeOptions): ResolvedModalRuntimeOptions;
+//# sourceMappingURL=config.d.ts.map

package/dist/modal/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/modal/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,WAAW,EAAE,gBAAgB,CAAC;IAE9B;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;OAUG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,oFAAoF;IACpF,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAE/B,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,+FAA+F;IAC/F,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;;;;;;;;;;OAkBG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,8DAA8D;AAC9D,eAAO,MAAM,cAAc;;;;;;;;;;;CAWjB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAsB,CAAC;AAEzD,iDAAiD;AACjD,MAAM,MAAM,2BAA2B,GACnC,IAAI,CAAC,mBAAmB,EAAE,MAAM,OAAO,cAAc,GAAG,SAAS,CAAC,GAClE;KAAG,CAAC,IAAI,MAAM,OAAO,cAAc,CAAC,CAAC,GAAG,WAAW,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;CAAE,GAC7E;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAyBxB,yEAAyE;AACzE,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,GAC3B,2BAA2B,CAgK7B"}

package/dist/modal/config.js

@@ -0,0 +1,169 @@
+/**
+ * SDK-free configuration for the Modal adapter.
+ *
+ * Nothing in this module imports the vendor SDK, so config can be constructed,
+ * validated, and asserted on without pulling in a gRPC stack.
+ *
+ * Modal's object model is not the one this package's port assumes, and the
+ * difference is load-bearing rather than cosmetic:
+ *
+ *  - A Modal Sandbox is **a child of an App**, created from an **Image**.
+ *    `sandboxes.create(app, image, params)` takes both as required arguments.
+ *    There is no "just make me a sandbox" entry point, so `appName` and
+ *    `imageTag` are required here. No default is correct for every consumer,
+ *    and this package bakes none in.
+ *  - A Modal Sandbox has a **maximum lifetime**, after which the provider
+ *    terminates it. The SDK's default is five minutes. That default is a trap
+ *    for every caller who expects E2B/Daytona semantics, so `maxLifetimeMs` is
+ *    required and always sent explicitly — see {@link ModalRuntimeOptions.maxLifetimeMs}.
+ *  - A Modal Sandbox **cannot be stopped and restarted**. `terminate()` is the
+ *    only lifecycle transition and it is terminal.
+ */
+/** Defaults applied by {@link resolveModalRuntimeOptions}. */
+export const MODAL_DEFAULTS = {
+    ownerTagKey: "agentRelayOwner",
+    createAppIfMissing: false,
+    verifyTagsClientSide: true,
+    requestTimeoutMs: 30_000,
+    createTimeoutMs: 120_000,
+    lookupTimeoutMs: 30_000,
+    execTimeoutMs: 120_000,
+    destroyTimeoutMs: 60_000,
+    uploadTimeoutMs: 60_000,
+    pollIntervalMs: 500,
+};
+/**
+ * Modal's documented floor for a CPU reservation. Requesting less is rejected
+ * here rather than at the provider, so the failure names the real cause.
+ */
+export const MODAL_MIN_CPU_CORES = 0.125;
+/**
+ * Modal's documented hard ceiling on a sandbox's maximum lifetime: 24 hours.
+ *
+ * Beyond this the provider offers no continuous-run option at all — its own
+ * guidance is to take a filesystem snapshot and restore it into a *new*
+ * sandbox. So a request for a longer-lived sandbox is not merely optimistic,
+ * it is unsatisfiable, and it fails here rather than at create time.
+ */
+export const MODAL_MAX_LIFETIME_MS = 24 * 60 * 60 * 1000;
+function requireNonEmpty(value, field) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        throw new Error(`ModalRuntime requires a non-empty ${field}`);
+    }
+    return trimmed;
+}
+/**
+ * A positive, finite duration. Non-finite values are rejected rather than
+ * coerced: `NaN` propagated into a deadline comparison silently disables the
+ * deadline instead of failing, which is the worst of both outcomes.
+ */
+function requirePositiveMs(value, fallback, field) {
+    const resolved = value ?? fallback;
+    if (!Number.isFinite(resolved) || resolved <= 0) {
+        throw new Error(`ModalRuntime ${field} must be a finite, positive number of milliseconds; got ${String(value)}`);
+    }
+    return resolved;
+}
+/** Validate and normalize caller config. Throws on anything unusable. */
+export function resolveModalRuntimeOptions(options) {
+    const tokenId = requireNonEmpty(options.credentials?.tokenId, "credentials.tokenId");
+    const tokenSecret = requireNonEmpty(options.credentials?.tokenSecret, "credentials.tokenSecret");
+    const appName = requireNonEmpty(options.appName, "appName");
+    const imageTag = requireNonEmpty(options.imageTag, "imageTag");
+    const defaultHomeDir = requireNonEmpty(options.defaultHomeDir, "defaultHomeDir");
+    const namePrefix = requireNonEmpty(options.namePrefix, "namePrefix");
+    const ownerTagKey = requireNonEmpty(options.ownerTagKey ?? MODAL_DEFAULTS.ownerTagKey, "ownerTagKey");
+    // Required and unforgiving: inheriting Modal's 5-minute default silently caps
+    // every caller's work.
+    if (options.maxLifetimeMs === undefined) {
+        throw new Error("ModalRuntime requires an explicit maxLifetimeMs: a Modal Sandbox is terminated by "
+            + "the provider once its maximum lifetime elapses, and the SDK default is 5 minutes. "
+            + "No default here would be correct for every caller.");
+    }
+    const maxLifetimeMs = requirePositiveMs(options.maxLifetimeMs, Number.NaN, "maxLifetimeMs");
+    if (maxLifetimeMs > MODAL_MAX_LIFETIME_MS) {
+        throw new Error(`ModalRuntime maxLifetimeMs (${maxLifetimeMs}) exceeds Modal's documented 24-hour ceiling `
+            + `(${MODAL_MAX_LIFETIME_MS}). Modal has no longer-lived sandbox: past 24 hours its own `
+            + "guidance is to snapshot the filesystem and restore into a new sandbox.");
+    }
+    const idleTimeoutMs = options.idleTimeoutMs === undefined
+        ? undefined
+        : requirePositiveMs(options.idleTimeoutMs, Number.NaN, "idleTimeoutMs");
+    if (idleTimeoutMs !== undefined && idleTimeoutMs > maxLifetimeMs) {
+        // Not fatal for Modal, but it always means the caller misread one of the
+        // two knobs: an idle timeout longer than the hard lifetime can never fire.
+        throw new Error(`ModalRuntime idleTimeoutMs (${idleTimeoutMs}) exceeds maxLifetimeMs (${maxLifetimeMs}); `
+            + "the idle timeout could never fire before the sandbox is terminated outright");
+    }
+    const resources = options.resources;
+    if (resources?.cpu !== undefined) {
+        if (!Number.isFinite(resources.cpu) || resources.cpu < MODAL_MIN_CPU_CORES) {
+            throw new Error(`ModalRuntime resources.cpu must be a finite number >= ${MODAL_MIN_CPU_CORES} `
+                + `physical cores; got ${String(resources.cpu)}`);
+        }
+    }
+    if (resources?.memoryMiB !== undefined) {
+        if (!Number.isFinite(resources.memoryMiB) || resources.memoryMiB <= 0) {
+            throw new Error(`ModalRuntime resources.memoryMiB must be a finite, positive number; got ${String(resources.memoryMiB)}`);
+        }
+    }
+    // Hard limits are validated on their own before any comparison with a
+    // reservation. Otherwise `cpuLimit: NaN` or `memoryLimitMiB: -1` slips
+    // through whenever the matching reservation is omitted, and the failure
+    // resurfaces at `sandboxes.create` with a message that no longer names the
+    // real cause.
+    if (resources?.cpuLimit !== undefined) {
+        if (!Number.isFinite(resources.cpuLimit) || resources.cpuLimit < MODAL_MIN_CPU_CORES) {
+            throw new Error(`ModalRuntime resources.cpuLimit must be a finite number >= ${MODAL_MIN_CPU_CORES} `
+                + `physical cores; got ${String(resources.cpuLimit)}`);
+        }
+    }
+    if (resources?.memoryLimitMiB !== undefined) {
+        if (!Number.isFinite(resources.memoryLimitMiB) || resources.memoryLimitMiB <= 0) {
+            throw new Error(`ModalRuntime resources.memoryLimitMiB must be a finite, positive number; `
+                + `got ${String(resources.memoryLimitMiB)}`);
+        }
+    }
+    if (resources?.cpu !== undefined && resources.cpuLimit !== undefined
+        && resources.cpuLimit < resources.cpu) {
+        throw new Error(`ModalRuntime resources.cpuLimit (${resources.cpuLimit}) is below resources.cpu (${resources.cpu})`);
+    }
+    if (resources?.memoryMiB !== undefined && resources.memoryLimitMiB !== undefined
+        && resources.memoryLimitMiB < resources.memoryMiB) {
+        throw new Error(`ModalRuntime resources.memoryLimitMiB (${resources.memoryLimitMiB}) is below `
+            + `resources.memoryMiB (${resources.memoryMiB})`);
+    }
+    // `blockNetwork` and `regions` are independent Modal parameters: a
+    // sandbox can legitimately need outbound-network isolation *and* placement
+    // in a specific region for data residency, latency, or capacity reasons.
+    // Blocking network access does not make physical placement meaningless.
+    return {
+        credentials: { tokenId, tokenSecret },
+        appName,
+        imageTag,
+        defaultHomeDir,
+        workdir: options.workdir?.trim() || defaultHomeDir,
+        namePrefix,
+        ownerTagKey,
+        createAppIfMissing: options.createAppIfMissing ?? MODAL_DEFAULTS.createAppIfMissing,
+        verifyTagsClientSide: options.verifyTagsClientSide
+            ?? MODAL_DEFAULTS.verifyTagsClientSide,
+        maxLifetimeMs,
+        ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+        ...(options.environment === undefined ? {} : { environment: options.environment }),
+        ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+        ...(resources === undefined ? {} : { resources }),
+        ...(options.cloud === undefined ? {} : { cloud: options.cloud }),
+        ...(options.regions === undefined ? {} : { regions: options.regions }),
+        ...(options.blockNetwork === undefined ? {} : { blockNetwork: options.blockNetwork }),
+        requestTimeoutMs: requirePositiveMs(options.requestTimeoutMs, MODAL_DEFAULTS.requestTimeoutMs, "requestTimeoutMs"),
+        createTimeoutMs: requirePositiveMs(options.createTimeoutMs, MODAL_DEFAULTS.createTimeoutMs, "createTimeoutMs"),
+        lookupTimeoutMs: requirePositiveMs(options.lookupTimeoutMs, MODAL_DEFAULTS.lookupTimeoutMs, "lookupTimeoutMs"),
+        execTimeoutMs: requirePositiveMs(options.execTimeoutMs, MODAL_DEFAULTS.execTimeoutMs, "execTimeoutMs"),
+        destroyTimeoutMs: requirePositiveMs(options.destroyTimeoutMs, MODAL_DEFAULTS.destroyTimeoutMs, "destroyTimeoutMs"),
+        uploadTimeoutMs: requirePositiveMs(options.uploadTimeoutMs, MODAL_DEFAULTS.uploadTimeoutMs, "uploadTimeoutMs"),
+        pollIntervalMs: requirePositiveMs(options.pollIntervalMs, MODAL_DEFAULTS.pollIntervalMs, "pollIntervalMs"),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/modal/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/modal/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAmKH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,WAAW,EAAE,iBAAiB;IAC9B,kBAAkB,EAAE,KAAK;IACzB,oBAAoB,EAAE,IAAI;IAC1B,gBAAgB,EAAE,MAAM;IACxB,eAAe,EAAE,OAAO;IACxB,eAAe,EAAE,MAAM;IACvB,aAAa,EAAE,OAAO;IACtB,gBAAgB,EAAE,MAAM;IACxB,eAAe,EAAE,MAAM;IACvB,cAAc,EAAE,GAAG;CACX,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAQzD,SAAS,eAAe,CAAC,KAAyB,EAAE,KAAa;IAC/D,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,qCAAqC,KAAK,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAyB,EAAE,QAAgB,EAAE,KAAa;IACnF,MAAM,QAAQ,GAAG,KAAK,IAAI,QAAQ,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,gBAAgB,KAAK,2DAA2D,MAAM,CAAC,KAAK,CAAC,EAAE,CAChG,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,0BAA0B,CACxC,OAA4B;IAE5B,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC;IACrF,MAAM,WAAW,GAAG,eAAe,CACjC,OAAO,CAAC,WAAW,EAAE,WAAW,EAChC,yBAAyB,CAC1B,CAAC;IACF,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC/D,MAAM,cAAc,GAAG,eAAe,CAAC,OAAO,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;IACjF,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACrE,MAAM,WAAW,GAAG,eAAe,CACjC,OAAO,CAAC,WAAW,IAAI,cAAc,CAAC,WAAW,EACjD,aAAa,CACd,CAAC;IAEF,8EAA8E;IAC9E,uBAAuB;IACvB,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,oFAAoF;cAChF,oFAAoF;cACpF,oDAAoD,CACzD,CAAC;IACJ,CAAC;IACD,MAAM,aAAa,GAAG,iBAAiB,CAAC,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAC5F,IAAI,aAAa,GAAG,qBAAqB,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,+BAA+B,aAAa,+CAA+C;cACvF,IAAI,qBAAqB,8DAA8D;cACvF,wEAAwE,CAC7E,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,KAAK,SAAS;QACvD,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAC1E,IAAI,aAAa,KAAK,SAAS,IAAI,aAAa,GAAG,aAAa,EAAE,CAAC;QACjE,yEAAyE;QACzE,2EAA2E;QAC3E,MAAM,IAAI,KAAK,CACb,+BAA+B,aAAa,4BAA4B,aAAa,KAAK;cACtF,6EAA6E,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,IAAI,SAAS,EAAE,GAAG,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,GAAG,mBAAmB,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CACb,yDAAyD,mBAAmB,GAAG;kBAC3E,uBAAuB,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CACnD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,SAAS,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,KAAK,CACb,2EAA2E,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CACzG,CAAC;QACJ,CAAC;IACH,CAAC;IACD,sEAAsE;IACtE,uEAAuE;IACvE,wEAAwE;IACxE,2EAA2E;IAC3E,cAAc;IACd,IAAI,SAAS,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,QAAQ,GAAG,mBAAmB,EAAE,CAAC;YACrF,MAAM,IAAI,KAAK,CACb,8DAA8D,mBAAmB,GAAG;kBAChF,uBAAuB,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CACxD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,SAAS,EAAE,cAAc,KAAK,SAAS,EAAE,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,SAAS,CAAC,cAAc,IAAI,CAAC,EAAE,CAAC;YAChF,MAAM,IAAI,KAAK,CACb,2EAA2E;kBACvE,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,EAAE,CAC9C,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IACE,SAAS,EAAE,GAAG,KAAK,SAAS,IAAI,SAAS,CAAC,QAAQ,KAAK,SAAS;WAC7D,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,GAAG,EACrC,CAAC;QACD,MAAM,IAAI,KAAK,CACb,oCAAoC,SAAS,CAAC,QAAQ,6BAA6B,SAAS,CAAC,GAAG,GAAG,CACpG,CAAC;IACJ,CAAC;IACD,IACE,SAAS,EAAE,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,cAAc,KAAK,SAAS;WACzE,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,SAAS,EACjD,CAAC;QACD,MAAM,IAAI,KAAK,CACb,0CAA0C,SAAS,CAAC,cAAc,aAAa;cAC3E,wBAAwB,SAAS,CAAC,SAAS,GAAG,CACnD,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,2EAA2E;IAC3E,yEAAyE;IACzE,wEAAwE;IAExE,OAAO;QACL,WAAW,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;QACrC,OAAO;QACP,QAAQ;QACR,cAAc;QACd,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,cAAc;QAClD,UAAU;QACV,WAAW;QACX,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,IAAI,cAAc,CAAC,kBAAkB;QACnF,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;eAC7C,cAAc,CAAC,oBAAoB;QACxC,aAAa;QACb,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC;QACzD,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAClF,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzE,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;QACjD,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QACtE,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;QACrF,gBAAgB,EAAE,iBAAiB,CACjC,OAAO,CAAC,gBAAgB,EACxB,cAAc,CAAC,gBAAgB,EAC/B,kBAAkB,CACnB;QACD,eAAe,EAAE,iBAAiB,CAChC,OAAO,CAAC,eAAe,EACvB,cAAc,CAAC,eAAe,EAC9B,iBAAiB,CAClB;QACD,eAAe,EAAE,iBAAiB,CAChC,OAAO,CAAC,eAAe,EACvB,cAAc,CAAC,eAAe,EAC9B,iBAAiB,CAClB;QACD,aAAa,EAAE,iBAAiB,CAC9B,OAAO,CAAC,aAAa,EACrB,cAAc,CAAC,aAAa,EAC5B,eAAe,CAChB;QACD,gBAAgB,EAAE,iBAAiB,CACjC,OAAO,CAAC,gBAAgB,EACxB,cAAc,CAAC,gBAAgB,EAC/B,kBAAkB,CACnB;QACD,eAAe,EAAE,iBAAiB,CAChC,OAAO,CAAC,eAAe,EACvB,cAAc,CAAC,eAAe,EAC9B,iBAAiB,CAClB;QACD,cAAc,EAAE,iBAAiB,CAC/B,OAAO,CAAC,cAAc,EACtB,cAAc,CAAC,cAAc,EAC7B,gBAAgB,CACjB;KACF,CAAC;AACJ,CAAC"}