@sandbox-kit/modal 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sandbox-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# Modal provider for Sandbox Kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Independent package over `modal@0.11.1`, published separately from the core
+`@sandbox-kit/sandbox` client. Use it through that shared API.
+
+```sh
+npm install @sandbox-kit/sandbox @sandbox-kit/modal
+```
+
+## Usage
+
+```ts
+import { modal } from "@sandbox-kit/modal";
+import { Client } from "@sandbox-kit/sandbox";
+
+await using client = new Client({
+  provider: modal(),
+  auth: {
+    tokenPair: { id: "...", secret: "..." },
+  },
+  scope: { appName: "my-app", environment: "main" },
+});
+
+const sandbox = await client.create({
+  source: { image: { reference: "alpine:3.21" } },
+  provisioning: { timeout: 120_000 },
+});
+console.log(sandbox.id);
+```
+
+Closing the client releases local SDK resources only. The Modal app must already
+exist.
+
+## Examples
+
+| Example    | Project                                                                                                    |
+| ---------- | ---------------------------------------------------------------------------------------------------------- |
+| Creation   | [create-modal-sandbox](../../../../examples/typescript/modal/create-modal-sandbox/README.md)               |
+| Resources  | [create-modal-with-resources](../../../../examples/typescript/modal/create-modal-with-resources/README.md) |
+| Attach     | [attach-modal-sandbox](../../../../examples/typescript/modal/attach-modal-sandbox/README.md)               |
+| Full index | [TypeScript examples](../../../../examples/typescript/README.md)                                           |
+
+## Capabilities
+
+Modal supports image creation, attach, terminate, and local handle detachment.
+The creation adapter covers runtime command/workdir/PTY, gVisor or VM isolation,
+CPU and memory reservations and limits, placement, network policy and ports,
+secrets, OIDC workload identity, readiness, timeouts, labels, and verbose mode.
+Unsupported shared intent is rejected before contacting Modal.
+
+## Implementation notes
+
+Checks and portable field mappings are handwritten in `checks/provider_checks.ts`,
+`mappings/provider_mappings.ts`, and `config/provider_config.ts`, kept in sync with
+`specs/providers/modal.yaml`. `src/modal.ts` owns SDK call ordering;
+`src/mappings.ts` owns remaining composition those helpers do not cover.

package/dist/checks/provider_checks.d.ts

@@ -0,0 +1,2 @@
+import type { CreateOptions } from "@sandbox-kit/sandbox";
+export declare function validateProviderCreate(request: CreateOptions): void;

package/dist/checks/provider_checks.js

@@ -0,0 +1,106 @@
+import { ErrorKind, sandboxError, CreateFieldEnvironment, CreateFieldNetworkInboundCidrsEntries, CreateFieldNetworkOutboundCidrsEntries, CreateFieldNetworkOutboundDomainsEntries, CreateFieldPlacementCloud, CreateFieldResourcesCpuCores, CreateFieldResourcesMemoryMib, CreateFieldRuntimeWorkingDirectory } from "@sandbox-kit/sandbox";
+// validateProviderCreate rejects creation settings this provider cannot honor.
+// Rules are inventoried in specs/providers/modal.yaml checks.
+export function validateProviderCreate(request) {
+    const cpuCores = request.resources?.cpuCores;
+    if (cpuCores !== undefined && cpuCores < 0.125) {
+        fail(ErrorKind.InvalidArgument, CreateFieldResourcesCpuCores, "resources.cpu_cores is outside supported values");
+    }
+    const memoryMib = request.resources?.memoryMib;
+    if (memoryMib !== undefined && memoryMib < BigInt("128")) {
+        fail(ErrorKind.InvalidArgument, CreateFieldResourcesMemoryMib, "resources.memory_mib is outside supported values");
+    }
+    const workingDirectory = request.runtime?.workingDirectory;
+    if (workingDirectory !== undefined && !workingDirectory.startsWith("/")) {
+        fail(ErrorKind.InvalidArgument, CreateFieldRuntimeWorkingDirectory, "runtime.working_directory is outside supported values");
+    }
+    const cloud = request.placement?.cloud;
+    if (cloud !== undefined &&
+        cloud !== "aws" &&
+        cloud !== "gcp" &&
+        cloud !== "oci" &&
+        cloud !== "auto") {
+        fail(ErrorKind.Unsupported, CreateFieldPlacementCloud, "placement.cloud is outside supported values");
+    }
+    for (const value of request.network?.outboundCidrs ?? []) {
+        if (value !== "" && !validCidr(value)) {
+            fail(ErrorKind.InvalidArgument, CreateFieldNetworkOutboundCidrsEntries, "network.outbound_cidrs.entries is outside supported values");
+        }
+    }
+    for (const value of request.network?.inboundCidrs ?? []) {
+        if (!validCidr(value)) {
+            fail(ErrorKind.InvalidArgument, CreateFieldNetworkInboundCidrsEntries, "network.inbound_cidrs.entries is outside supported values");
+        }
+    }
+    for (const value of request.network?.outboundDomains ?? []) {
+        if (value !== "" && !validDomain(value)) {
+            fail(ErrorKind.InvalidArgument, CreateFieldNetworkOutboundDomainsEntries, "network.outbound_domains.entries is outside supported values");
+        }
+    }
+    for (const value of Object.keys(request.environment ?? {})) {
+        if (!validEnvName(value)) {
+            fail(ErrorKind.InvalidArgument, CreateFieldEnvironment, "environment is outside supported values");
+        }
+    }
+}
+function validEnvName(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function validDomain(value) {
+    const domain = value.startsWith("*.") ? value.slice(2) : value;
+    return (domain.length <= 253 &&
+        /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.?$/i.test(domain));
+}
+function validCidr(value) {
+    const separator = value.lastIndexOf("/");
+    if (separator <= 0)
+        return false;
+    const address = value.slice(0, separator);
+    const prefix = Number(value.slice(separator + 1));
+    if (!Number.isInteger(prefix))
+        return false;
+    return address.includes(":")
+        ? prefix >= 0 && prefix <= 128 && validIpv6(address)
+        : prefix >= 0 && prefix <= 32 && validIpv4(address);
+}
+function validIpv4(value) {
+    const parts = value.split(".");
+    return (parts.length === 4 &&
+        parts.every((part) => /^(0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+}
+function validIpv6(value) {
+    if ((value.match(/::/g)?.length ?? 0) > 1)
+        return false;
+    const halves = value.split("::");
+    if (halves.length > 2)
+        return false;
+    const count = (part) => {
+        if (part === "")
+            return 0;
+        const groups = part.split(":");
+        let total = 0;
+        for (const group of groups) {
+            if (/^[0-9a-f]{1,4}$/i.test(group))
+                total++;
+            else if (validIpv4(group))
+                total += 2;
+            else
+                return undefined;
+        }
+        return total;
+    };
+    const left = count(halves[0] ?? "");
+    const right = count(halves[1] ?? "");
+    return (left !== undefined &&
+        right !== undefined &&
+        (halves.length === 2 ? left + right < 8 : left === 8));
+}
+function fail(kind, field, message) {
+    throw sandboxError({
+        kind,
+        provider: "modal",
+        operation: "create",
+        field,
+        message: "sandbox-kit modal: " + message,
+    });
+}

package/dist/config/provider_config.d.ts

@@ -0,0 +1,8 @@
+import type { ModalClientParams as NativeClientConfig } from "modal";
+import { type Config, type Scope } from "@sandbox-kit/sandbox";
+export declare function mapGeneratedClientConfig(config: Config): NativeClientConfig;
+export interface ProviderState {
+    readonly scope?: Scope;
+    readonly region?: string;
+}
+export declare function captureProviderState(config: Config): ProviderState;

package/dist/config/provider_config.js

@@ -0,0 +1,46 @@
+// Client configuration composition for the native SDK constructor.
+// Kept in sync with specs/providers/modal.yaml client: rules (not emitted).
+import { ErrorKind, sandboxError, validateConfig, ConfigFieldAuth, ConfigFieldEndpoint, ConfigFieldScopeProjectId } from "@sandbox-kit/sandbox";
+import { mapClientScope, mapOAuthAuth, mapTokenPairCredentials, } from "#mappings/provider_mappings.js";
+export function mapGeneratedClientConfig(config) {
+    const source = config;
+    validateConfig(source, "modal", "initialize");
+    const target = {};
+    if (source.endpoint !== undefined)
+        unsupported(ConfigFieldEndpoint, "Endpoint cannot be configured through this SDK's public client constructor");
+    if (source.scope !== undefined) {
+        const mapped = mapClientScope(source.scope, "initialize");
+        Object.assign(target, mapped);
+        if (source.scope.organizationId !== undefined)
+            unsupported("scope.organizationId", "unsupported client configuration field");
+        if (source.scope.projectId !== undefined)
+            unsupported(ConfigFieldScopeProjectId, "unsupported client configuration field");
+    }
+    if (source.auth?.tokenPair !== undefined) {
+        Object.assign(target, mapTokenPairCredentials(source.auth.tokenPair, "initialize"));
+    }
+    else if (source.auth?.oauthRefresh !== undefined) {
+        Object.assign(target, mapOAuthAuth(source.auth.oauthRefresh, "initialize"));
+    }
+    else if (source.auth !== undefined) {
+        unsupported(ConfigFieldAuth, "unsupported authentication mode");
+    }
+    return target;
+}
+export function captureProviderState(config) {
+    return {
+        ...(config.scope === undefined
+            ? {}
+            : { scope: structuredClone(config.scope) }),
+        ...(config.region === undefined ? {} : { region: config.region }),
+    };
+}
+function unsupported(field, message) {
+    throw sandboxError({
+        kind: ErrorKind.Unsupported,
+        provider: "modal",
+        operation: "initialize",
+        field,
+        message: "sandbox-kit modal: " + message,
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+import { SandboxError } from "@sandbox-kit/sandbox";
+export declare function mapModalError(error: unknown, operation: string): SandboxError;

package/dist/errors.js

@@ -0,0 +1,34 @@
+// Native Modal error translation is handwritten.
+// Classification order: existing SandboxError, abort/timeout DOMException,
+// then native Modal types, then unknown. Cause stays on SandboxError.cause.
+import { AlreadyExistsError, ClientClosedError, ConflictError, InvalidError, NotFoundError, ResourceExhaustedError, SandboxTimeoutError, TimeoutError } from "modal";
+import { ErrorKind, SandboxError, sandboxError } from "@sandbox-kit/sandbox";
+export function mapModalError(error, operation) {
+    if (error instanceof SandboxError)
+        return error;
+    if (error instanceof DOMException && error.name === "AbortError")
+        return create(ErrorKind.Canceled, error, operation);
+    if (error instanceof DOMException && error.name === "TimeoutError")
+        return create(ErrorKind.Timeout, error, operation);
+    let kind = ErrorKind.Unknown;
+    if (kind === ErrorKind.Unknown && error instanceof InvalidError)
+        kind = ErrorKind.InvalidArgument;
+    if (kind === ErrorKind.Unknown && error instanceof NotFoundError)
+        kind = ErrorKind.NotFound;
+    if (kind === ErrorKind.Unknown && error instanceof AlreadyExistsError)
+        kind = ErrorKind.AlreadyExists;
+    if (kind === ErrorKind.Unknown && error instanceof ConflictError)
+        kind = ErrorKind.Conflict;
+    if (kind === ErrorKind.Unknown && error instanceof ResourceExhaustedError)
+        kind = ErrorKind.ResourceExhausted;
+    if (kind === ErrorKind.Unknown && error instanceof TimeoutError)
+        kind = ErrorKind.Timeout;
+    if (kind === ErrorKind.Unknown && error instanceof SandboxTimeoutError)
+        kind = ErrorKind.Timeout;
+    if (kind === ErrorKind.Unknown && error instanceof ClientClosedError)
+        kind = ErrorKind.FailedPrecondition;
+    return create(kind, error, operation);
+}
+function create(kind, error, operation, statusCode, providerCode, providerSource) {
+    return sandboxError({ kind, provider: "modal", operation, field: "", message: error instanceof Error ? error.message : "sandbox-kit modal: provider operation failed", ...(statusCode === undefined ? {} : { statusCode }), ...(providerCode === undefined ? {} : { providerCode }), ...(providerSource === undefined ? {} : { providerSource }) }, error);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { providerName } from "./provider.js";
+export { modal } from "./modal.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { providerName } from "./provider.js";
+export { modal } from "./modal.js";

package/dist/mappings/mappings.d.ts

@@ -0,0 +1,16 @@
+import { type ModalClientParams, type Sandbox, type SandboxCreateParams } from "modal";
+import { type Config, type CreateOptions, type SandboxInfo } from "@sandbox-kit/sandbox";
+import type { ProviderState } from "#config/provider_config.js";
+export interface ModalCreatePlan {
+    readonly app: string;
+    readonly environment?: string;
+    readonly image: string;
+    readonly params: SandboxCreateParams;
+    readonly secretNames: readonly string[];
+    readonly proxyName?: string;
+    readonly waitUntilReady: boolean;
+    readonly readyTimeoutMs?: number;
+}
+export declare function mapClientConfig(config: Config): ModalClientParams;
+export declare function mapCreateRequest(request: CreateOptions, config: ProviderState): ModalCreatePlan;
+export declare function mapSandboxInfo(value: Sandbox, request?: CreateOptions): SandboxInfo;

package/dist/mappings/mappings.js

@@ -0,0 +1,317 @@
+// Provider-specific orchestration around generated portable field mappings.
+import { Probe, } from "modal";
+import { EgressMode, ErrorKind, IsolationKind, PolicyMode, PortTransport, SecretInjection, SandboxState, ValueOrigin, WaitCondition, sandboxError, CreateFieldIsolation, CreateFieldIsolationKind, CreateFieldLifetime, CreateFieldLifetimeIdleTerminateAfter, CreateFieldLifetimeIdleTerminateMode, CreateFieldNetwork, CreateFieldNetworkEgress, CreateFieldNetworkPortsPort, CreateFieldNetworkPortsTransport, CreateFieldPlacementTarget, CreateFieldProvisioningTimeout, CreateFieldProvisioningWaitFor, CreateFieldReadiness, CreateFieldRuntime, CreateFieldSecuritySecretsEnvironmentVariable, CreateFieldSecuritySecretsInjection, CreateFieldSource, ConfigFieldScopeAppName, CreateFieldName, CreateFieldNetworkInboundCidrs, CreateFieldNetworkProxyReference, CreateFieldProvisioningQueueTimeout, CreateFieldResourcesCpuLimitCores, CreateFieldResourcesDiskMib, CreateFieldResourcesMemoryLimitMib, CreateFieldResourcesMemoryMib, CreateFieldSecurityPublicAccess, CreateFieldSecuritySecretsReference, CreateFieldSourceImageReference } from "@sandbox-kit/sandbox";
+import { mapCommonCreateFields as generatedMapCommonCreateFields, mapIdleDuration as generatedMapIdleDuration, mapLifetimeDuration as generatedMapLifetimeDuration, mapResources as generatedMapResources, mapSandboxIdentity as generatedMapSandboxIdentity, } from "./provider_mappings.js";
+import { validateProviderCreate } from "#checks/provider_checks.js";
+import { mapGeneratedClientConfig } from "#config/provider_config.js";
+export function mapClientConfig(config) {
+    const result = mapGeneratedClientConfig(config);
+    if (config.timeout !== undefined)
+        result.timeoutMs = finiteDurationMs(config.timeout, "timeout", true);
+    return result;
+}
+export function mapCreateRequest(request, config) {
+    validateProviderCreate(request);
+    const app = config.scope?.appName === undefined
+        ? invalid(ConfigFieldScopeAppName, "Modal app name is required")
+        : nonblank(config.scope.appName, ConfigFieldScopeAppName);
+    if (request.source?.image === undefined)
+        unsupported(CreateFieldSource, "Modal requires an explicit image source");
+    const params = generatedMapCommonCreateFields(request);
+    if (request.name !== undefined)
+        params.name = nonblank(request.name, CreateFieldName);
+    if (config.region !== undefined)
+        params.regions = [nonblankConfig(config.region, "region")];
+    mapRuntime(request, params);
+    mapIsolation(request, params);
+    mapResources(request, params);
+    mapPlacement(request, params);
+    mapNetwork(request, params);
+    const secretNames = mapSecurity(request, params);
+    mapLifetime(request, params);
+    mapReadiness(request, params);
+    const wait = mapProvisioning(request, params);
+    mapObservability(request, params);
+    if (request.providerOptions !== undefined)
+        unsupported("providerOptions", "Modal provider options are not mapped");
+    return {
+        app,
+        ...(config.scope?.environment === undefined
+            ? {}
+            : { environment: config.scope.environment }),
+        image: nonblank(request.source.image.reference, CreateFieldSourceImageReference),
+        params,
+        secretNames,
+        ...(request.network?.proxyReference === undefined
+            ? {}
+            : {
+                proxyName: nonblank(request.network.proxyReference, CreateFieldNetworkProxyReference),
+            }),
+        ...wait,
+    };
+}
+function mapRuntime(r, p) {
+    const v = r.runtime;
+    if (!v)
+        return;
+    if (v.workingDirectory !== undefined)
+        p.workdir = v.workingDirectory;
+    if (v.entrypoint !== undefined)
+        p.command = [...v.entrypoint];
+    if (v.pty !== undefined)
+        p.pty = v.pty;
+    if (v.language !== undefined ||
+        v.version !== undefined ||
+        v.user !== undefined)
+        unsupported(CreateFieldRuntime, "language, version, and user must come from the Modal image");
+}
+function mapIsolation(r, p) {
+    const v = r.isolation;
+    if (!v)
+        return;
+    const kind = v.kind ?? IsolationKind.Default;
+    if (kind === IsolationKind.LinuxVm)
+        p.runtime = "vm";
+    else if (kind === IsolationKind.Container)
+        p.runtime = "gvisor";
+    else if (kind !== IsolationKind.Default)
+        unsupported(CreateFieldIsolationKind, "requested Modal isolation is unsupported");
+    if (v.providerKind !== undefined || v.nestedVirtualization !== undefined)
+        unsupported(CreateFieldIsolation, "provider kind and nested virtualization are unsupported");
+}
+function mapResources(r, p) {
+    const v = r.resources;
+    if (!v)
+        return;
+    if (v.cpuLimitCores !== undefined)
+        positive(v.cpuLimitCores, CreateFieldResourcesCpuLimitCores);
+    if (v.memoryMib !== undefined)
+        integer(v.memoryMib, CreateFieldResourcesMemoryMib, 128);
+    if (v.memoryLimitMib !== undefined)
+        integer(v.memoryLimitMib, CreateFieldResourcesMemoryLimitMib, 1);
+    if (v.diskMib !== undefined)
+        unsupported(CreateFieldResourcesDiskMib, "Modal disk override is unsupported");
+    Object.assign(p, generatedMapResources(v));
+}
+function mapPlacement(r, p) {
+    const v = r.placement;
+    if (!v)
+        return;
+    if (v.cloud !== undefined)
+        p.cloud = v.cloud;
+    if (v.regions !== undefined)
+        p.regions = [...v.regions];
+    if (v.target !== undefined)
+        unsupported(CreateFieldPlacementTarget, "Modal placement target is unsupported");
+}
+function mapNetwork(r, p) {
+    const v = r.network;
+    if (!v)
+        return;
+    const egress = v.egress ?? EgressMode.Default;
+    if (egress === EgressMode.BlockAll)
+        p.blockNetwork = true;
+    else if (egress !== EgressMode.Default &&
+        egress !== EgressMode.AllowAll &&
+        egress !== EgressMode.Restricted)
+        invalid(CreateFieldNetworkEgress, "unknown egress mode");
+    if (v.outboundCidrs !== undefined)
+        p.outboundCidrAllowlist = [...v.outboundCidrs];
+    if (v.outboundDomains !== undefined)
+        p.outboundDomainAllowlist = [...v.outboundDomains];
+    if (v.inboundCidrs !== undefined) {
+        if (!v.inboundCidrs.length)
+            unsupported(CreateFieldNetworkInboundCidrs, "empty inbound deny-all is not representable");
+        p.inboundCidrAllowlist = [...v.inboundCidrs];
+    }
+    if (v.privateNetwork !== undefined)
+        p.i6pn = v.privateNetwork;
+    if (v.customDomain !== undefined)
+        p.customDomain = v.customDomain;
+    if (v.ports) {
+        p.encryptedPorts = [];
+        p.h2Ports = [];
+        p.unencryptedPorts = [];
+        for (const x of v.ports) {
+            const port = x.port;
+            if (port === undefined)
+                invalid(CreateFieldNetworkPortsPort, "port is required");
+            const transport = x.transport ?? PortTransport.Default;
+            if (transport === PortTransport.Tls)
+                p.encryptedPorts.push(port);
+            else if (transport === PortTransport.Http2Tls)
+                p.h2Ports.push(port);
+            else if (transport === PortTransport.Plain)
+                p.unencryptedPorts.push(port);
+            else
+                invalid(CreateFieldNetworkPortsTransport, "explicit transport is required");
+        }
+    }
+    if (v.linkedSandbox !== undefined || v.outboundProxyUrl !== undefined)
+        unsupported(CreateFieldNetwork, "linked sandbox and outbound proxy URL mappings are unsupported");
+}
+function mapSecurity(r, p) {
+    const v = r.security;
+    if (!v)
+        return [];
+    if (v.workloadIdentity !== undefined)
+        p.includeOidcIdentityToken = v.workloadIdentity;
+    if (v.publicAccess !== undefined)
+        unsupported(CreateFieldSecurityPublicAccess, "Modal public access is represented by ports");
+    const names = [];
+    for (const s of v.secrets ?? []) {
+        if (s.environmentVariable !== undefined)
+            unsupported(CreateFieldSecuritySecretsEnvironmentVariable, "per-variable secret renaming is unsupported");
+        const injection = s.injection ?? SecretInjection.Default;
+        if (injection !== SecretInjection.Default &&
+            injection !== SecretInjection.Environment)
+            unsupported(CreateFieldSecuritySecretsInjection, "egress-placeholder injection is unsupported");
+        names.push(nonblank(s.reference, CreateFieldSecuritySecretsReference));
+    }
+    return names;
+}
+function mapLifetime(r, p) {
+    const v = r.lifetime;
+    if (!v)
+        return;
+    if (v.maximumLifetime !== undefined)
+        finiteDurationMs(v.maximumLifetime, "lifetime.maximumLifetime", false);
+    Object.assign(p, generatedMapLifetimeDuration(v));
+    if (v.idleTerminate) {
+        const mode = v.idleTerminate.mode ?? PolicyMode.Default;
+        if (mode === PolicyMode.Disabled)
+            p.idleTimeoutMs = 0;
+        else if (mode === PolicyMode.After) {
+            if (v.idleTerminate.after === undefined)
+                invalid(CreateFieldLifetimeIdleTerminateAfter, "duration is required");
+            finiteDurationMs(v.idleTerminate.after, "lifetime.idleTerminate.after", false);
+            Object.assign(p, generatedMapIdleDuration(v.idleTerminate));
+        }
+        else if (mode !== PolicyMode.Default)
+            invalid(CreateFieldLifetimeIdleTerminateMode, "unknown policy mode");
+    }
+    if (v.ephemeral !== undefined ||
+        v.idleStop !== undefined ||
+        v.idlePause !== undefined ||
+        v.stoppedArchive !== undefined ||
+        v.stoppedDelete !== undefined)
+        unsupported(CreateFieldLifetime, "requested lifecycle policy is unsupported by Modal");
+}
+function mapReadiness(r, p) {
+    const v = r.readiness;
+    if (!v)
+        return;
+    if (v.tcpPort !== undefined) {
+        p.readinessProbe = Probe.withTcp(v.tcpPort);
+    }
+    else if (v.command !== undefined)
+        p.readinessProbe = Probe.withExec([...(v.command.argv ?? [])]);
+    else
+        invalid(CreateFieldReadiness, "probe is required");
+}
+function mapProvisioning(r, _p) {
+    const v = r.provisioning;
+    if (!v)
+        return { waitUntilReady: false };
+    if (v.queueTimeout !== undefined)
+        unsupported(CreateFieldProvisioningQueueTimeout, "Modal queue timeout is unsupported");
+    const waitFor = v.waitFor ?? WaitCondition.Default;
+    if (waitFor === WaitCondition.Default || waitFor === WaitCondition.Scheduled)
+        return { waitUntilReady: false };
+    if (waitFor === WaitCondition.Ready) {
+        if (v.timeout === undefined || v.timeout <= 0)
+            invalid(CreateFieldProvisioningTimeout, "ready wait requires a positive timeout");
+        if (!r.readiness)
+            invalid(CreateFieldReadiness, "ready wait requires a probe");
+        return { waitUntilReady: true, readyTimeoutMs: v.timeout };
+    }
+    unsupported(CreateFieldProvisioningWaitFor, "requested wait condition is unsupported");
+}
+function mapObservability(r, p) {
+    const v = r.observability;
+    if (!v)
+        return;
+    if (v.verbose !== undefined)
+        p.verbose = v.verbose;
+    if (v.telemetryEndpoint !== undefined)
+        unsupported("observability.telemetryEndpoint", "per-sandbox telemetry endpoint is unsupported");
+}
+export function mapSandboxInfo(value, request) {
+    const mapped = generatedMapSandboxIdentity(value);
+    const origins = { ...(mapped.origins ?? {}) };
+    const result = {
+        id: mapped.id ?? value.sandboxId,
+        provider: "modal",
+        state: SandboxState.Running,
+        labels: {},
+        origins,
+    };
+    if (request?.name !== undefined) {
+        mutable(result).name = request.name;
+        origins.name = ValueOrigin.Request;
+    }
+    if (request?.labels !== undefined) {
+        mutable(result).labels = { ...request.labels };
+        origins.labels = ValueOrigin.Request;
+    }
+    if (request?.isolation !== undefined) {
+        mutable(result).isolation = { ...request.isolation };
+        origins.isolation = ValueOrigin.Request;
+    }
+    return result;
+}
+function mutable(v) {
+    return v;
+}
+function nonblank(v, f) {
+    if (!v.trim())
+        invalid(f, "must not be blank");
+    return v;
+}
+function nonblankConfig(v, f) {
+    if (!v.trim())
+        configInvalid(f, "must not be blank");
+    return v;
+}
+function positive(v, f) {
+    if (!Number.isFinite(v) || v <= 0)
+        invalid(f, "must be positive");
+    return v;
+}
+function integer(v, f, min) {
+    if (v < BigInt(min) || v > 2147483647n)
+        invalid(f, "is outside the supported range");
+    return Number(v);
+}
+function finiteDurationMs(v, f, zero) {
+    if (!Number.isFinite(v) || v < 0 || (!zero && v === 0))
+        invalid(f, "must be a finite positive duration");
+    return v;
+}
+function invalid(field, message) {
+    throw sandboxError({
+        kind: ErrorKind.InvalidArgument,
+        provider: "modal",
+        operation: "create",
+        field,
+        message: "sandbox-kit modal: " + message,
+    });
+}
+function unsupported(field, message) {
+    throw sandboxError({
+        kind: ErrorKind.Unsupported,
+        provider: "modal",
+        operation: "create",
+        field,
+        message: "sandbox-kit modal: " + message,
+    });
+}
+function configInvalid(field, message) {
+    throw sandboxError({
+        kind: ErrorKind.InvalidArgument,
+        provider: "modal",
+        operation: "initialize",
+        field,
+        message: "sandbox-kit modal: " + message,
+    });
+}

package/dist/mappings/provider_mappings.d.ts

@@ -0,0 +1,14 @@
+import { type SandboxInfo, type Scope } from "@sandbox-kit/sandbox";
+import type { CreateOptions, OAuthCredentials, Resources, TokenPairCredentials } from "@sandbox-kit/sandbox";
+import type { ModalClientParams as NativeModalClientParams, Sandbox as NativeSandbox, SandboxCreateParams as NativeSandboxCreateParams } from "modal";
+type PublicLifetime = NonNullable<CreateOptions["lifetime"]>;
+type PublicIdleTerminate = NonNullable<PublicLifetime["idleTerminate"]>;
+export declare function mapSandboxIdentity(source: NativeSandbox | undefined, operation?: string): Partial<SandboxInfo>;
+export declare function mapClientScope(source: Scope | undefined, operation?: string): NativeModalClientParams;
+export declare function mapCommonCreateFields(source: CreateOptions | undefined, operation?: string): NativeSandboxCreateParams;
+export declare function mapResources(source: Resources | undefined, operation?: string): NativeSandboxCreateParams;
+export declare function mapLifetimeDuration(source: PublicLifetime | undefined, operation?: string): NativeSandboxCreateParams;
+export declare function mapIdleDuration(source: PublicIdleTerminate | undefined, operation?: string): NativeSandboxCreateParams;
+export declare function mapTokenPairCredentials(source: TokenPairCredentials | undefined, operation?: string): NativeModalClientParams;
+export declare function mapOAuthAuth(source: OAuthCredentials | undefined, operation?: string): NativeModalClientParams;
+export {};