modal 0.10.0 → 0.10.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Client, Status, ClientMiddleware } from 'nice-grpc';
+import { createChannel, Client, Status, ClientMiddleware } from 'nice-grpc';
 import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 
 /**
@@ -86,6 +86,13 @@ declare enum AppStopSource {
     APP_STOP_SOURCE_WEB = 3,
     UNRECOGNIZED = -1
 }
+/** CPU architecture an image is built for and must run on. */
+declare enum Arch {
+    ARCH_UNSPECIFIED = 0,
+    ARCH_X86_64 = 1,
+    ARCH_AARCH64 = 2,
+    UNRECOGNIZED = -1
+}
 declare enum CertificateStatus {
     CERTIFICATE_STATUS_PENDING = 0,
     CERTIFICATE_STATUS_ISSUED = 1,
@@ -184,6 +191,17 @@ declare enum EndpointStopSource {
     ENDPOINT_STOP_SOURCE_WEB = 2,
     UNRECOGNIZED = -1
 }
+/**
+ * Partial-update signal for EnvironmentUpdateRequest. Omitted means no-op.
+ * INHERIT clears the environment override so the workspace default applies.
+ */
+declare enum EnvironmentBlockUnauthenticatedResources {
+    ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_UNSPECIFIED = 0,
+    ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_INHERIT = 1,
+    ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_BLOCK = 2,
+    ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_ALLOW = 3,
+    UNRECOGNIZED = -1
+}
 declare enum EnvironmentRole {
     ENVIRONMENT_ROLE_UNSPECIFIED = 0,
     ENVIRONMENT_ROLE_VIEWER = 1,
@@ -625,6 +643,14 @@ interface AppGetByDeploymentNameResponse {
     lifecycle: AppLifecycle | undefined;
 }
 declare const AppGetByDeploymentNameResponse: MessageFns$1<AppGetByDeploymentNameResponse>;
+interface AppGetInfoRequest {
+    appId: string;
+}
+declare const AppGetInfoRequest: MessageFns$1<AppGetInfoRequest>;
+interface AppGetInfoResponse {
+    info: AppHandleMetadata | undefined;
+}
+declare const AppGetInfoResponse: MessageFns$1<AppGetInfoResponse>;
 interface AppGetLayoutRequest {
     appId: string;
 }
@@ -679,6 +705,7 @@ interface AppGetOrCreateRequest {
 declare const AppGetOrCreateRequest: MessageFns$1<AppGetOrCreateRequest>;
 interface AppGetOrCreateResponse {
     appId: string;
+    handleMetadata: AppHandleMetadata | undefined;
 }
 declare const AppGetOrCreateResponse: MessageFns$1<AppGetOrCreateResponse>;
 interface AppGetTagsRequest {
@@ -691,6 +718,21 @@ interface AppGetTagsResponse {
     };
 }
 declare const AppGetTagsResponse: MessageFns$1<AppGetTagsResponse>;
+interface AppHandleMetadata {
+    description: string;
+    appId: string;
+    environmentName: string;
+    lifecycle: AppLifecycle | undefined;
+    /** tag -> function id */
+    functions: {
+        [key: string]: string;
+    };
+    /** tag -> function id */
+    servers: {
+        [key: string]: string;
+    };
+}
+declare const AppHandleMetadata: MessageFns$1<AppHandleMetadata>;
 interface AppHeartbeatRequest {
     appId: string;
 }
@@ -1560,6 +1602,7 @@ interface EndpointListItem {
     provisioningStatus: EndpointProvisioningStatus;
     status: string;
     servingMode: EndpointServingMode;
+    unauthenticated: boolean;
 }
 declare const EndpointListItem: MessageFns$1<EndpointListItem>;
 interface EndpointListRequest {
@@ -1718,6 +1761,7 @@ interface EnvironmentListItem {
     spendLimitReached: boolean;
     environmentType: EnvironmentType;
     defaultMemberRole?: EnvironmentRole | undefined;
+    blockUnauthenticatedResources?: boolean | undefined;
 }
 declare const EnvironmentListItem: MessageFns$1<EnvironmentListItem>;
 interface EnvironmentListResponse {
@@ -1766,6 +1810,12 @@ interface EnvironmentSettings {
     webhookSuffix: string;
     maxConcurrentGpus?: number | undefined;
     maxConcurrentTasks?: number | undefined;
+    /**
+     * When true, new unauthenticated web functions, Servers, tunnels, and
+     * Endpoints in this environment are rejected. Unset inherits the workspace
+     * default.
+     */
+    blockUnauthenticatedResources?: boolean | undefined;
 }
 declare const EnvironmentSettings: MessageFns$1<EnvironmentSettings>;
 interface EnvironmentUpdateRequest {
@@ -1774,6 +1824,7 @@ interface EnvironmentUpdateRequest {
     webSuffix: string | undefined;
     maxConcurrentTasks?: number | undefined;
     maxConcurrentGpus?: number | undefined;
+    blockUnauthenticatedResources?: EnvironmentBlockUnauthenticatedResources | undefined;
 }
 declare const EnvironmentUpdateRequest: MessageFns$1<EnvironmentUpdateRequest>;
 /** A file entry when listing files in a volume or network file system. */
@@ -2208,6 +2259,15 @@ interface FunctionFinishInputsRequest {
     numInputs: number;
 }
 declare const FunctionFinishInputsRequest: MessageFns$1<FunctionFinishInputsRequest>;
+interface FunctionGetByIdRequest {
+    functionId: string;
+}
+declare const FunctionGetByIdRequest: MessageFns$1<FunctionGetByIdRequest>;
+interface FunctionGetByIdResponse {
+    function: FunctionData | undefined;
+    handleMetadata: FunctionHandleMetadata | undefined;
+}
+declare const FunctionGetByIdResponse: MessageFns$1<FunctionGetByIdResponse>;
 interface FunctionGetCallGraphRequest {
     functionCallId: string;
 }
@@ -2215,6 +2275,8 @@ declare const FunctionGetCallGraphRequest: MessageFns$1<FunctionGetCallGraphRequ
 interface FunctionGetCallGraphResponse {
     inputs: InputCallGraphInfo[];
     functionCalls: FunctionCallCallGraphInfo[];
+    /** Set by the server when the graph has more nodes than it will return, so `inputs` is a prefix of the graph. */
+    truncated: boolean;
 }
 declare const FunctionGetCallGraphResponse: MessageFns$1<FunctionGetCallGraphResponse>;
 interface FunctionGetCurrentStatsRequest {
@@ -2231,6 +2293,14 @@ interface FunctionGetDynamicConcurrencyResponse {
     concurrency: number;
 }
 declare const FunctionGetDynamicConcurrencyResponse: MessageFns$1<FunctionGetDynamicConcurrencyResponse>;
+interface FunctionGetFlashAuthTokenRequest {
+    functionId: string;
+}
+declare const FunctionGetFlashAuthTokenRequest: MessageFns$1<FunctionGetFlashAuthTokenRequest>;
+interface FunctionGetFlashAuthTokenResponse {
+    token: string;
+}
+declare const FunctionGetFlashAuthTokenResponse: MessageFns$1<FunctionGetFlashAuthTokenResponse>;
 interface FunctionGetInputsItem {
     inputId: string;
     input: FunctionInput | undefined;
@@ -2329,6 +2399,8 @@ interface FunctionGetTimeRangeStatsRequest {
     until: Date | undefined;
     /** Aggregate the root Function pool and its non-version-pinned variant pools. */
     rollup: boolean;
+    /** Filter stats for a specific container */
+    containerId?: string | undefined;
 }
 declare const FunctionGetTimeRangeStatsRequest: MessageFns$1<FunctionGetTimeRangeStatsRequest>;
 interface FunctionGetTimeRangeStatsResponse {
@@ -2336,32 +2408,34 @@ interface FunctionGetTimeRangeStatsResponse {
     since: Date | undefined;
     /** Exclusive. */
     until: Date | undefined;
-    /**
-     * Per-input latency distributions.
-     * Execution time derived from inputs that finish in the window
-     */
-    executionTimeSeconds: FunctionStatsPercentiles | undefined;
-    /**
-     * Purposely omitted for now since it can't be computed
-     * from the desired tables without caveats that are confusing
-     * to explain to users
-     */
-    queueTimeSeconds: FunctionStatsPercentiles | undefined;
-    endToEndLatencySeconds: FunctionStatsPercentiles | undefined;
-    /** Container startup is measured from enqueue to start. */
-    containerStartupTimeSeconds: FunctionStatsPercentiles | undefined;
     /** Counts of inputs that finish in the requested time range. */
     inputSuccessCount: number;
     inputFailureCount: number;
     inputTimeoutCount: number;
+    /** Number of inputs assigned but not finished at the exclusive end of the time range. */
+    inputRunningAtEndCount: number;
     /**
-     * Resource distributions are computed from normalized container heartbeat
-     * observations and expressed as fractions, where 1.0 represents 100% utilization.
-     * A missing message indicates that no observations were available.
+     * Metrics include execution_time, end_to_end_latency, subject to change
+     * as requirements evolve
      */
-    cpuUtilization: FunctionStatsPercentiles | undefined;
-    memoryUtilization: FunctionStatsPercentiles | undefined;
-    gpuUtilization: FunctionStatsPercentiles | undefined;
+    inputPercentileStats: {
+        [key: string]: StatsPercentileDistribution;
+    };
+    /**
+     * Container lifecycle counts. Started and errored containers are counted when
+     * the corresponding event occurs in the requested time range. Creating containers
+     * were enqueued but had not started or finished at the exclusive end of the range.
+     */
+    containerStartedCount: number;
+    containerErrorCount: number;
+    containerCreatingAtEndCount: number;
+    /**
+     * Metrics include cpu_usage, memory_usage, gpu_utilization subject to change
+     * as requirements evolve
+     */
+    containerPercentileStats: {
+        [key: string]: StatsPercentileDistribution;
+    };
     /**
      * Number of direct non-version-pinned variants included in the roll-up.
      * Zero when roll-up is disabled or the base Function has no variants.
@@ -2565,11 +2639,6 @@ interface FunctionStats$1 {
     inputHeadroom: number;
 }
 declare const FunctionStats$1: MessageFns$1<FunctionStats$1>;
-interface FunctionStatsPercentiles {
-    p50: number;
-    p90: number;
-}
-declare const FunctionStatsPercentiles: MessageFns$1<FunctionStatsPercentiles>;
 interface FunctionUpdateSchedulingParamsRequest {
     functionId: string;
     warmPoolSizeOverride: number;
@@ -2653,6 +2722,11 @@ interface Image$1 {
     };
     /** Volume mount for RUN commands */
     volumeMounts: VolumeMount[];
+    /**
+     * CPU architecture the image is built for. Images with an unspecified
+     * arch predate this field and are treated as x86_64.
+     */
+    arch: Arch;
 }
 declare const Image$1: MessageFns$1<Image$1>;
 interface ImageBuildChainGetRequest {
@@ -3096,6 +3170,35 @@ interface ObjectDependency {
     objectId: string;
 }
 declare const ObjectDependency: MessageFns$1<ObjectDependency>;
+/** Policy for outbound traffic from a sandbox. */
+interface OutboundPolicy {
+    /** Replace headers in outbound HTTPS requests, potentially with secret values. */
+    headerReplacements: OutboundPolicy_HeaderReplacement[];
+}
+declare const OutboundPolicy: MessageFns$1<OutboundPolicy>;
+interface OutboundPolicy_HeaderReplacement {
+    /**
+     * Domain that the header replacement is scoped to. Supports wildcards in
+     * subdomain positions.
+     */
+    domain: string;
+    /** Header name to replace. */
+    headerName: string;
+    /**
+     * Header value to replace.
+     *
+     * Supports templating with keys in a given secret_id: a $-prefixed key
+     * name in the secret will be replaced with the secret value. Literal $
+     * characters can be represented by two dollars: `$$`.
+     */
+    headerValue: string;
+    /**
+     * Reference to a secret to use in the header_value template. Can be empty
+     * if no secret value is used in header_value.
+     */
+    secretId: string;
+}
+declare const OutboundPolicy_HeaderReplacement: MessageFns$1<OutboundPolicy_HeaderReplacement>;
 interface PTYInfo {
     /** Soon deprecated */
     enabled: boolean;
@@ -3467,8 +3570,30 @@ interface Sandbox$1 {
      */
     inboundCidrAllowlist: string[];
     environmentVariables: StringMap | undefined;
+    outboundPolicy?: OutboundPolicy | undefined;
 }
 declare const Sandbox$1: MessageFns$1<Sandbox$1>;
+interface SandboxContainerCreateV2Request {
+    /** Sandbox the container joins; it runs inside that sandbox's task. */
+    sandboxId: string;
+    /** Logical container name, unique within the sandbox. */
+    containerName: string;
+    /**
+     * Same definition type as SandboxCreateV2. Fields a container cannot honor
+     * (resources, timeouts, scheduling constraints, ...) are rejected.
+     */
+    definition: Sandbox$1 | undefined;
+    ephemeralSecrets: StringMap | undefined;
+    cloudBucketMountCredentials: {
+        [key: string]: StringMap;
+    };
+}
+declare const SandboxContainerCreateV2Request: MessageFns$1<SandboxContainerCreateV2Request>;
+interface SandboxContainerCreateV2Response {
+    containerId: string;
+    containerName: string;
+}
+declare const SandboxContainerCreateV2Response: MessageFns$1<SandboxContainerCreateV2Response>;
 interface SandboxCreateConnectTokenRequest {
     sandboxId: string;
     userMetadata: string;
@@ -3988,6 +4113,18 @@ interface SharedVolumeRemoveFileRequest {
     recursive: boolean;
 }
 declare const SharedVolumeRemoveFileRequest: MessageFns$1<SharedVolumeRemoveFileRequest>;
+interface StatsPercentile {
+    /** The percentile expressed in basis points: 5000 is p50 and 9990 is p99.9. */
+    percentileBasisPoints: number;
+    value: number;
+}
+declare const StatsPercentile: MessageFns$1<StatsPercentile>;
+interface StatsPercentileDistribution {
+    /** Unit identifier such as "seconds", "cores", "gibibytes", or "fraction". */
+    unit: string;
+    percentiles: StatsPercentile[];
+}
+declare const StatsPercentileDistribution: MessageFns$1<StatsPercentileDistribution>;
 interface StringMap {
     contents: {
         [key: string]: string;
@@ -4295,6 +4432,11 @@ interface VolumeGetFile2Request {
     start: number;
     /** 0 is interpreted as 'read to end' */
     len: number;
+    /**
+     * The client extends each block body it downloads with zero bytes up to the
+     * block's expected length, so responses may omit trailing zero bytes.
+     */
+    clientPadsBlocks: boolean;
 }
 declare const VolumeGetFile2Request: MessageFns$1<VolumeGetFile2Request>;
 interface VolumeGetFile2Response {
@@ -4746,6 +4888,14 @@ declare const ModalClientDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly appGetInfo: {
+            readonly name: "AppGetInfo";
+            readonly requestType: MessageFns$1<AppGetInfoRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$1<AppGetInfoResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         readonly appGetLayout: {
             readonly name: "AppGetLayout";
             readonly requestType: MessageFns$1<AppGetLayoutRequest>;
@@ -5481,6 +5631,14 @@ declare const ModalClientDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly functionGetById: {
+            readonly name: "FunctionGetById";
+            readonly requestType: MessageFns$1<FunctionGetByIdRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$1<FunctionGetByIdResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         readonly functionGetCallGraph: {
             readonly name: "FunctionGetCallGraph";
             readonly requestType: MessageFns$1<FunctionGetCallGraphRequest>;
@@ -5505,6 +5663,14 @@ declare const ModalClientDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly functionGetFlashAuthToken: {
+            readonly name: "FunctionGetFlashAuthToken";
+            readonly requestType: MessageFns$1<FunctionGetFlashAuthTokenRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$1<FunctionGetFlashAuthTokenResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         /** For containers to request next call */
         readonly functionGetInputs: {
             readonly name: "FunctionGetInputs";
@@ -5867,6 +6033,14 @@ declare const ModalClientDefinition: {
             readonly options: {};
         };
         /** Sandboxes */
+        readonly sandboxContainerCreateV2: {
+            readonly name: "SandboxContainerCreateV2";
+            readonly requestType: MessageFns$1<SandboxContainerCreateV2Request>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$1<SandboxContainerCreateV2Response>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         readonly sandboxCreate: {
             readonly name: "SandboxCreate";
             readonly requestType: MessageFns$1<SandboxCreateRequest>;
@@ -7632,6 +7806,14 @@ declare enum TaskExecStdoutConfig {
     TASK_EXEC_STDOUT_CONFIG_PIPE = 1,
     UNRECOGNIZED = -1
 }
+interface SandboxStdinWriteV2Response {
+}
+declare const SandboxStdinWriteV2Response: MessageFns<SandboxStdinWriteV2Response>;
+interface SandboxStdioReadV2Response {
+    data: Uint8Array;
+    startingOffset: number;
+}
+declare const SandboxStdioReadV2Response: MessageFns<SandboxStdioReadV2Response>;
 interface SandboxWaitUntilReadyTcrResponse {
     readyAt: number;
 }
@@ -7918,11 +8100,26 @@ interface Profile {
     serverUrl: string;
     tokenId?: string;
     tokenSecret?: string;
+    oauthRefreshToken?: string;
+    oauthClientId?: string;
+    oauthClientSecret?: string;
+    oauthJwtKey?: string;
     environment?: string;
     imageBuilderVersion?: string;
     logLevel?: string;
     /** Parsed from MODAL_MAX_THROTTLE_WAIT. null means unlimited. */
     maxThrottleWaitSecs?: number;
+    /**
+     * How long a Sandbox connection may sit idle before the client gives it up.
+     * The Sandbox stays usable: the next operation reconnects. Zero keeps
+     * connections open until the client closes.
+     */
+    sandboxChannelIdleTimeoutMs: number;
+    /**
+     * Set by the MODAL_SANDBOX_V2 environment variable or the sandbox_v2
+     * profile key in .modal.toml.
+     */
+    sandboxV2: boolean;
 }
 
 /**
@@ -7949,7 +8146,37 @@ interface StdinSource {
 /** @ignore */
 declare class TaskCommandRouterClientImpl {
     private stub;
+    /**
+     * The connection, absent while it is released. It is dialled again by the
+     * next operation, so nothing may hold `stub` across one.
+     */
     private channel;
+    private dial;
+    private factory;
+    /**
+     * How many operations are using the connection. A count rather than a flag
+     * because operations overlap: only the last one out starts the idle clock.
+     */
+    private inFlight;
+    private idle;
+    /**
+     * Bumped every time a connection is dialled. A stream opened on an earlier
+     * one is stale: the connection under it has since been given up.
+     */
+    private generation;
+    /**
+     * Streams open right now, tracked so they can be ended on release.
+     *
+     * grpc-js does not cancel a call in flight when its channel is closed, and a
+     * subchannel with a live call on it is never collected - so closing alone
+     * leaves the socket up. Aborting the calls first is what actually frees it.
+     */
+    private liveStreams;
+    /**
+     * How long the client may go unused before its connection is given up. Zero
+     * keeps it up until the client is closed. Overridable in tests.
+     */
+    idleTimeoutMs: number;
     private serverClient;
     private taskId;
     private sandboxId;
@@ -7960,14 +8187,36 @@ declare class TaskCommandRouterClientImpl {
     private jwtRefreshLock;
     private logger;
     private closed;
+    private draining;
     /**
      * `access` is the router access returned by SandboxCreateV2, which lets a
      * freshly created sandbox connect without a round-trip. Pass undefined to look
      * it up — a re-attached sandbox, or the server could not mint a token.
      */
     static tryInit(serverClient: ModalGrpcClient, taskId: string, sandboxId: string, isV2: boolean, access: CommandRouterAccess | undefined, logger: Logger, profile: Profile): Promise<TaskCommandRouterClientImpl | null>;
-    private constructor();
+    /**
+     * Builds a client around an already-resolved connection. Public so a test can
+     * construct one without the control-plane round trip `tryInit` makes; the
+     * class is not exported from the package, so this is not API surface.
+     */
+    constructor(serverClient: ModalGrpcClient, taskId: string, sandboxId: string, isV2: boolean, serverUrl: string, jwt: string, dial: () => ReturnType<typeof createChannel>, logger: Logger, idleTimeoutMs: number);
+    /**
+     * Says the client is about to be used: holds off the idle timer, and dials
+     * again if the connection was already given up. Returns the generation being
+     * used; pair every call with endOp.
+     */
+    private beginOp;
+    /** Says the caller is done. The last one out starts the clock. */
+    private endOp;
+    /**
+     * Starts the countdown to giving the connection back. Call it with nothing
+     * in flight.
+     */
+    private armIdleTimer;
+    /** Refuse new operations and release resources after current operations finish. */
+    closeWhenIdle(): void;
     close(): void;
+    private callWithRetries;
     /** Run a unary RPC against the command router with the default retry policy. */
     private callUnary;
     execStart(request: TaskExecStartRequest): Promise<TaskExecStartResponse>;
@@ -7976,7 +8225,7 @@ declare class TaskCommandRouterClientImpl {
     containerList(request: TaskContainerListRequest): Promise<TaskContainerListResponse>;
     containerTerminate(request: TaskContainerTerminateRequest): Promise<void>;
     containerWait(request: TaskContainerWaitRequest): Promise<TaskContainerWaitResponse>;
-    execStdioRead(taskId: string, execId: string, fileDescriptor: FileDescriptor, deadline?: number | null): AsyncGenerator<TaskExecStdioReadResponse>;
+    execStdioRead(taskId: string, execId: string, fileDescriptor: FileDescriptor, deadline?: number | null, signal?: AbortSignal): AsyncGenerator<TaskExecStdioReadResponse>;
     execStdinWrite(taskId: string, execId: string, offset: number, data: Uint8Array, eof: boolean): Promise<TaskExecStdinWriteResponse>;
     /**
      * Read the current stdin write status for an exec'd command.
@@ -8010,10 +8259,20 @@ declare class TaskCommandRouterClientImpl {
      * within this window, the call is cancelled and a TimeoutError is thrown.
      */
     reloadVolumes(request: TaskReloadVolumesRequest, options?: TimeoutOptions): Promise<void>;
+    sandboxStdioReadV2(taskId: string, fileDescriptor: FileDescriptor, signal?: AbortSignal): AsyncGenerator<SandboxStdioReadV2Response>;
+    sandboxStdinWriteV2(taskId: string, offset: number, data: Uint8Array, eof: boolean): Promise<SandboxStdinWriteV2Response>;
     sandboxWaitUntilReady(taskId: string, timeoutMs: number): Promise<SandboxWaitUntilReadyTcrResponse>;
     private refreshJwt;
+    /** The caller holds an operation lease across authentication and all retries. */
     private callWithAuthRetry;
-    private streamStdio;
+    /**
+     * Yields the next chunk of stdio, opening or reopening the stream as it needs
+     * to, and determining whether or not to retry a failed open or read. It waits
+     * out the backoff itself.
+     */
+    private streamStdioWithRetries;
+    private streamExecStdio;
+    private streamSandboxStdio;
 }
 
 /** Type of a filesystem entry. */
@@ -8228,12 +8487,13 @@ declare class SandboxFilesystem {
     writeText(data: string, remotePath: string): Promise<void>;
 }
 
-type SandboxSidecarCommandRouter = Pick<TaskCommandRouterClientImpl, "containerCreate" | "containerGet" | "containerList" | "containerTerminate" | "containerWait">;
+type SandboxSidecarCommandRouter = Pick<TaskCommandRouterClientImpl, "containerCreate" | "containerGet" | "containerList" | "containerTerminate" | "containerWait" | "mountDirectory" | "snapshotDirectory" | "unmountDirectory">;
 type SandboxSidecarAccess = {
     client: ModalClient;
     exec(command: string[], params: SandboxExecParams | undefined, containerId: string): Promise<ContainerProcess>;
     commandRouter(): Promise<[string, SandboxSidecarCommandRouter]>;
     reloadVolumes(containerId: string, params: SidecarReloadVolumesParams | undefined): Promise<void>;
+    snapshotFilesystem(containerId: string, params: SidecarSnapshotFilesystemParams | undefined): Promise<Image>;
 };
 /** Options for {@link SidecarService#create SidecarService.create()}. */
 type SidecarCreateParams = {
@@ -8276,11 +8536,24 @@ type SidecarTerminateParams = {
     /** If true, wait for the sidecar container to terminate. */
     wait?: boolean;
 };
+/** Optional parameters for {@link SidecarContainer#snapshotFilesystem SidecarContainer.snapshotFilesystem()}. */
+type SidecarSnapshotFilesystemParams = {
+    /** Overall budget for the snapshot call, in milliseconds. Defaults to 55000. */
+    timeoutMs?: number;
+    /** Lifetime of the resulting image in milliseconds. Defaults to 30 days. Pass `null` for no expiry. */
+    ttlMs?: number | null;
+};
 /** Optional parameters for {@link SidecarContainer#reloadVolumes SidecarContainer.reloadVolumes()}. */
 type SidecarReloadVolumesParams = {
     /** Overall budget in milliseconds. Defaults to 55000. */
     timeoutMs?: number;
 };
+/** Optional parameters for {@link SidecarContainer#mountImage SidecarContainer.mountImage()}. */
+type SidecarMountImageParams = SandboxMountImageParams;
+/** Optional parameters for {@link SidecarContainer#unmountImage SidecarContainer.unmountImage()}. */
+type SidecarUnmountImageParams = Record<string, never>;
+/** Optional parameters for {@link SidecarContainer#snapshotDirectory SidecarContainer.snapshotDirectory()}. */
+type SidecarSnapshotDirectoryParams = SandboxSnapshotDirectoryParams;
 /**
  * Creates and manages sidecar containers inside a Sandbox.
  *
@@ -8334,6 +8607,8 @@ declare class SidecarContainer {
     terminate(params: {
         wait: true;
     }): Promise<number>;
+    /** Snapshot this Sidecar container's filesystem into an Image. */
+    snapshotFilesystem(params?: SidecarSnapshotFilesystemParams): Promise<Image>;
     /**
      * Reload all Volumes mounted in this sidecar container.
      *
@@ -8341,6 +8616,39 @@ declare class SidecarContainer {
      * (the reload may still complete in the background).
      */
     reloadVolumes(params?: SidecarReloadVolumesParams): Promise<void>;
+    /**
+     * Mount an {@link Image} at a path in this Sidecar container's filesystem.
+     *
+     * @param path - The path where the directory should be mounted
+     * @param image - Optional {@link Image} to mount. If undefined, mounts an empty directory.
+     * @param params - Optional parameters; see {@link SidecarMountImageParams}.
+     */
+    mountImage(path: string, image?: Image, params?: SidecarMountImageParams): Promise<void>;
+    /**
+     * Unmounts an {@link Image} previously mounted at a path in this Sidecar container's filesystem.
+     *
+     * @param path - The mount path to unmount
+     */
+    unmountImage(path: string, _params?: SidecarUnmountImageParams): Promise<void>;
+    /**
+     * Snapshots and creates a new {@link Image} from a directory in the running Sidecar container.
+     *
+     * The resulting Image is retained for `ttlMs` (default: 30 days),
+     * as a hard cutoff measured from creation — usage does not extend
+     * the lifetime. Pass `ttlMs: null` to retain indefinitely.
+     *
+     * The call has an overall `timeoutMs` budget (default: 55000). If it
+     * elapses before a snapshot completes, the call is cancelled and an
+     * error is thrown.
+     *
+     * The Image can be used anywhere an Image is accepted, including as a mount
+     * or as the base filesystem for another container.
+     *
+     * @param path - The path of the directory to snapshot
+     * @param params - Optional parameters; see {@link SidecarSnapshotDirectoryParams}.
+     * @returns Promise that resolves to an {@link Image}
+     */
+    snapshotDirectory(path: string, params?: SidecarSnapshotDirectoryParams): Promise<Image>;
 }
 
 /**
@@ -8514,7 +8822,9 @@ type SandboxCreateParams = {
     name?: string;
     /** Tags to attach to the Sandbox. Filterable via {@link SandboxService#list client.sandboxes.list}. */
     tags?: Record<string, string>;
-    /** Optional experimental options. */
+    /**
+     * Optional experimental options. Values must be booleans or strings.
+     */
     experimentalOptions?: Record<string, any>;
     /** If set, connections to this Sandbox will be subdomains of this domain rather than the default.
      * This requires prior manual setup by Modal and is only available for Enterprise customers.
@@ -8851,6 +9161,9 @@ declare class Sandbox {
      * Disconnect from the Sandbox, cleaning up local resources.
      * The Sandbox continues running on Modal's infrastructure.
      * After calling detach(), most operations on this Sandbox object will throw.
+     *
+     * This does not block on or interrupt ongoing reads or calls. Connection
+     * resources are closed promptly once those operations finish.
      */
     detach(): void;
     wait(): Promise<number>;
@@ -8887,13 +9200,39 @@ declare class Sandbox {
     /**
      * Get the exit filesystem snapshot image.
      *
+     * An exit snapshot captures the Sandbox filesystem when the Sandbox exits,
+     * whether its entrypoint finishes gracefully, abruptly, or it is stopped with
+     * {@link Sandbox#terminate}. The resulting {@link Image} can be passed to
+     * {@link SandboxService#create client.sandboxes.create()} to start a new
+     * Sandbox from the saved filesystem.
+     *
+     * Exit snapshots are opt-in: the Sandbox must have been created with
+     * `experimentalOptions: { enable_exit_snapshot: true }`. Calling this on a
+     * Sandbox created without that option throws an {@link InvalidError}.
+     *
+     * @example
+     * ```ts
+     * const sb = await modal.sandboxes.create(app, image, {
+     *   experimentalOptions: { enable_exit_snapshot: true },
+     * });
+     * // ... use the Sandbox ...
+     * await sb.terminate();
+     * const image = await sb.experimentalGetExitSnapshot();
+     * const sb2 = await modal.sandboxes.create(app, image);
+     * ```
+     *
      * EXPERIMENTAL: the API is subject to change.
      *
      * @param params - Optional parameters; see SandboxExperimentalGetExitSnapshotParams.
      * @returns The exit snapshot Image.
+     * @throws {InvalidError} If `timeoutMs` is negative, or if exit snapshots
+     *   were not enabled when the Sandbox was created.
      * @throws {TimeoutError} If `timeoutMs` elapses before the snapshot
      *   reaches a terminal state. This includes `timeoutMs = 0` when the
      *   snapshot is still pending.
+     * @throws {SnapshotCreationError} Snapshot operation is done and failed.
+     *   Polling again will not produce an Image; filesystem state is gone.
+     * @throws {NotFoundError} If the Sandbox does not exist.
      */
     experimentalGetExitSnapshot(params?: SandboxExperimentalGetExitSnapshotParams): Promise<Image>;
     /**
@@ -8999,6 +9338,14 @@ declare class ContainerProcess<R extends string | Uint8Array = any> {
 interface ModalClientParams {
     tokenId?: string;
     tokenSecret?: string;
+    /** OAuth refresh token returned by Modal's token endpoint. */
+    oauthRefreshToken?: string;
+    /** Modal-issued OAuth client ID, with an `oc-` prefix. */
+    oauthClientId?: string;
+    /** Modal-issued OAuth client secret, with an `ov-` prefix. */
+    oauthClientSecret?: string;
+    /** Unencrypted RSA private key encoded as PEM, with literal or escaped newlines. */
+    oauthJwtKey?: string;
     environment?: string;
     endpoint?: string;
     timeoutMs?: number;
@@ -9059,8 +9406,10 @@ declare class ModalClient {
     private authTokenManager;
     private customMiddleware;
     private environmentManager;
+    private oauthJwtKey?;
     constructor(params?: ModalClientParams);
     environmentName(environment?: string): string;
+    private validateProfileCredentials;
     /**
      * Returns the image builder version by querying the server where the local profile takes
      * precedence.
@@ -9207,7 +9556,7 @@ declare class SandboxFilesystemPermissionError extends SandboxFilesystemError {
 declare class SandboxTimeoutError extends Error {
     constructor(message?: string);
 }
-/** No snapshot image will be produced for a Sandbox. */
+/** Snapshot operation is done and failed. Polling again will not produce an Image; filesystem state is gone. */
 declare class SnapshotCreationError extends Error {
     constructor(message: string);
 }
@@ -9218,4 +9567,4 @@ declare class ClientClosedError extends Error {
 
 declare function checkForRenamedParams(params: any, renames: Record<string, string>): void;
 
-export { AlreadyExistsError, App, type AppFromNameParams, AppService, ClientClosedError, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ConflictError, ContainerProcess, ExecutionError, type FileInfo, type FileType, type FileWatchEvent, type FileWatchEventType, type FunctionAutoscalerSettings, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, type FunctionCallLogFetchParams, type FunctionCallLogStreamParams, type FunctionCallLogTailParams, FunctionCallLogsManager, FunctionCallService, type FunctionFromNameParams, type FunctionLogFetchParams, type FunctionLogStreamParams, type FunctionLogTailParams, FunctionLogsManager, FunctionService, type FunctionStats, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, type FunctionWithBatchingParams, type FunctionWithConcurrencyParams, type FunctionWithOptionsParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, type ImageFromNameParams, type ImagePublishParams, ImageService, InternalFailure, InvalidError, type LogEntry, type FunctionLogFetchParams as LogFetchParams, type LogLevel, type LogSource, type Logger, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, type SandboxExperimentalFromNameParams, type SandboxExperimentalFromSnapshotParams, type SandboxExperimentalGetExitSnapshotParams, type SandboxExperimentalListParams, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, type SandboxMountImageParams, type SandboxReloadVolumesParams, SandboxService, SandboxSnapshot, type SandboxSnapshotDirectoryParams, type SandboxSnapshotFilesystemParams, SandboxSnapshotService, type SandboxTerminateParams, SandboxTimeoutError, type SandboxUpdateNetworkPolicyParams, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, SidecarContainer, type SidecarCreateParams, type SidecarExecParams, type SidecarGetParams, type SidecarListParams, SidecarService, type SidecarTerminateParams, SnapshotCreationError, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptionsParams, VolumeService, checkForRenamedParams };
+export { AlreadyExistsError, App, type AppFromNameParams, AppService, ClientClosedError, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ConflictError, ContainerProcess, ExecutionError, type FileInfo, type FileType, type FileWatchEvent, type FileWatchEventType, type FunctionAutoscalerSettings, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, type FunctionCallLogFetchParams, type FunctionCallLogStreamParams, type FunctionCallLogTailParams, FunctionCallLogsManager, FunctionCallService, type FunctionFromNameParams, type FunctionLogFetchParams, type FunctionLogStreamParams, type FunctionLogTailParams, FunctionLogsManager, FunctionService, type FunctionStats, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, type FunctionWithBatchingParams, type FunctionWithConcurrencyParams, type FunctionWithOptionsParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, type ImageFromNameParams, type ImagePublishParams, ImageService, InternalFailure, InvalidError, type LogEntry, type FunctionLogFetchParams as LogFetchParams, type LogLevel, type LogSource, type Logger, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, type SandboxExperimentalFromNameParams, type SandboxExperimentalFromSnapshotParams, type SandboxExperimentalGetExitSnapshotParams, type SandboxExperimentalListParams, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, type SandboxMountImageParams, type SandboxReloadVolumesParams, SandboxService, SandboxSnapshot, type SandboxSnapshotDirectoryParams, type SandboxSnapshotFilesystemParams, SandboxSnapshotService, type SandboxTerminateParams, SandboxTimeoutError, type SandboxUpdateNetworkPolicyParams, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, SidecarContainer, type SidecarCreateParams, type SidecarExecParams, type SidecarGetParams, type SidecarListParams, type SidecarMountImageParams, SidecarService, type SidecarSnapshotDirectoryParams, type SidecarSnapshotFilesystemParams, type SidecarTerminateParams, type SidecarUnmountImageParams, SnapshotCreationError, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptionsParams, VolumeService, checkForRenamedParams };