modal 0.10.0 → 0.10.2-dev.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { Client, Status, ClientMiddleware } from 'nice-grpc';
1
+ import { createChannel, Client, Status, ClientMiddleware } from 'nice-grpc';
2
2
  import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
3
3
 
4
4
  /**
@@ -86,6 +86,13 @@ declare enum AppStopSource {
86
86
  APP_STOP_SOURCE_WEB = 3,
87
87
  UNRECOGNIZED = -1
88
88
  }
89
+ /** CPU architecture an image is built for and must run on. */
90
+ declare enum Arch {
91
+ ARCH_UNSPECIFIED = 0,
92
+ ARCH_X86_64 = 1,
93
+ ARCH_AARCH64 = 2,
94
+ UNRECOGNIZED = -1
95
+ }
89
96
  declare enum CertificateStatus {
90
97
  CERTIFICATE_STATUS_PENDING = 0,
91
98
  CERTIFICATE_STATUS_ISSUED = 1,
@@ -184,6 +191,17 @@ declare enum EndpointStopSource {
184
191
  ENDPOINT_STOP_SOURCE_WEB = 2,
185
192
  UNRECOGNIZED = -1
186
193
  }
194
+ /**
195
+ * Partial-update signal for EnvironmentUpdateRequest. Omitted means no-op.
196
+ * INHERIT clears the environment override so the workspace default applies.
197
+ */
198
+ declare enum EnvironmentBlockUnauthenticatedResources {
199
+ ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_UNSPECIFIED = 0,
200
+ ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_INHERIT = 1,
201
+ ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_BLOCK = 2,
202
+ ENVIRONMENT_BLOCK_UNAUTHENTICATED_RESOURCES_ALLOW = 3,
203
+ UNRECOGNIZED = -1
204
+ }
187
205
  declare enum EnvironmentRole {
188
206
  ENVIRONMENT_ROLE_UNSPECIFIED = 0,
189
207
  ENVIRONMENT_ROLE_VIEWER = 1,
@@ -249,10 +267,16 @@ declare enum GPUType {
249
267
  declare enum IdentityProviderType {
250
268
  IDENTITY_PROVIDER_TYPE_UNSPECIFIED = 0,
251
269
  IDENTITY_PROVIDER_TYPE_GITHUB = 1,
252
- IDENTITY_PROVIDER_TYPE_OKTA = 2,
270
+ IDENTITY_PROVIDER_TYPE_SAML = 2,
253
271
  IDENTITY_PROVIDER_TYPE_GOOGLE_OAUTH = 3,
254
272
  UNRECOGNIZED = -1
255
273
  }
274
+ declare enum LLMEngine {
275
+ LLM_ENGINE_UNSPECIFIED = 0,
276
+ LLM_ENGINE_SGLANG = 1,
277
+ LLM_ENGINE_VLLM = 2,
278
+ UNRECOGNIZED = -1
279
+ }
256
280
  declare enum MemberRole {
257
281
  MEMBER_ROLE_UNSPECIFIED = 0,
258
282
  MEMBER_ROLE_USER = 1,
@@ -322,6 +346,13 @@ declare enum SeekWhence {
322
346
  SEEK_END = 2,
323
347
  UNRECOGNIZED = -1
324
348
  }
349
+ declare enum ServerInferenceStatsStatus {
350
+ SERVER_INFERENCE_STATS_STATUS_UNSPECIFIED = 0,
351
+ SERVER_INFERENCE_STATS_STATUS_AVAILABLE = 1,
352
+ SERVER_INFERENCE_STATS_STATUS_NO_DATA = 2,
353
+ SERVER_INFERENCE_STATS_STATUS_UNAVAILABLE = 3,
354
+ UNRECOGNIZED = -1
355
+ }
325
356
  declare enum SystemErrorCode {
326
357
  SYSTEM_ERROR_CODE_UNSPECIFIED = 0,
327
358
  /** SYSTEM_ERROR_CODE_PERM - EPERM: Operation not permitted */
@@ -404,6 +435,12 @@ declare enum WebhookType {
404
435
  WEBHOOK_TYPE_WEB_SERVER = 4,
405
436
  UNRECOGNIZED = -1
406
437
  }
438
+ declare enum BlobUploadResult_Outcome {
439
+ OUTCOME_UNSPECIFIED = 0,
440
+ OUTCOME_SUCCESS = 1,
441
+ OUTCOME_FAILURE = 2,
442
+ UNRECOGNIZED = -1
443
+ }
407
444
  declare enum ClassParameterInfo_ParameterSerializationFormat {
408
445
  PARAM_SERIALIZATION_FORMAT_UNSPECIFIED = 0,
409
446
  /** PARAM_SERIALIZATION_FORMAT_PICKLE - legacy format - pickle of (args, kwargs) tuple */
@@ -525,6 +562,8 @@ interface AppCountLogsRequest {
525
562
  until: Date | undefined;
526
563
  bucketSecs: number;
527
564
  source: FileDescriptor;
565
+ /** Restrict logs to this exact Function ID, including when it is the base Function. */
566
+ parametrizedFunctionId: string;
528
567
  }
529
568
  declare const AppCountLogsRequest: MessageFns$1<AppCountLogsRequest>;
530
569
  interface AppCountLogsResponse {
@@ -603,6 +642,8 @@ interface AppFetchLogsRequest {
603
642
  taskId: string;
604
643
  sandboxId: string;
605
644
  searchText: string;
645
+ /** Restrict logs to this exact Function ID, including when it is the base Function. */
646
+ parametrizedFunctionId: string;
606
647
  }
607
648
  declare const AppFetchLogsRequest: MessageFns$1<AppFetchLogsRequest>;
608
649
  interface AppFetchLogsResponse {
@@ -625,6 +666,25 @@ interface AppGetByDeploymentNameResponse {
625
666
  lifecycle: AppLifecycle | undefined;
626
667
  }
627
668
  declare const AppGetByDeploymentNameResponse: MessageFns$1<AppGetByDeploymentNameResponse>;
669
+ interface AppGetInfoRequest {
670
+ appId: string;
671
+ }
672
+ declare const AppGetInfoRequest: MessageFns$1<AppGetInfoRequest>;
673
+ interface AppGetInfoResponse {
674
+ info: AppHandleMetadata | undefined;
675
+ functionInfoSummaries: {
676
+ [key: string]: AppGetInfoResponse_FunctionInfoSummary;
677
+ };
678
+ }
679
+ declare const AppGetInfoResponse: MessageFns$1<AppGetInfoResponse>;
680
+ interface AppGetInfoResponse_FunctionInfoSummary {
681
+ gpuConfig: GPUConfig[];
682
+ schedule: Schedule | undefined;
683
+ /** True for Web Functions and classes with web methods; false for Servers. */
684
+ webFunction: boolean;
685
+ requiresProxyAuth?: boolean | undefined;
686
+ }
687
+ declare const AppGetInfoResponse_FunctionInfoSummary: MessageFns$1<AppGetInfoResponse_FunctionInfoSummary>;
628
688
  interface AppGetLayoutRequest {
629
689
  appId: string;
630
690
  }
@@ -679,6 +739,7 @@ interface AppGetOrCreateRequest {
679
739
  declare const AppGetOrCreateRequest: MessageFns$1<AppGetOrCreateRequest>;
680
740
  interface AppGetOrCreateResponse {
681
741
  appId: string;
742
+ handleMetadata: AppHandleMetadata | undefined;
682
743
  }
683
744
  declare const AppGetOrCreateResponse: MessageFns$1<AppGetOrCreateResponse>;
684
745
  interface AppGetTagsRequest {
@@ -691,6 +752,21 @@ interface AppGetTagsResponse {
691
752
  };
692
753
  }
693
754
  declare const AppGetTagsResponse: MessageFns$1<AppGetTagsResponse>;
755
+ interface AppHandleMetadata {
756
+ description: string;
757
+ appId: string;
758
+ environmentName: string;
759
+ lifecycle: AppLifecycle | undefined;
760
+ /** tag -> function id */
761
+ functions: {
762
+ [key: string]: string;
763
+ };
764
+ /** tag -> function id */
765
+ servers: {
766
+ [key: string]: string;
767
+ };
768
+ }
769
+ declare const AppHandleMetadata: MessageFns$1<AppHandleMetadata>;
694
770
  interface AppHeartbeatRequest {
695
771
  appId: string;
696
772
  }
@@ -891,6 +967,25 @@ interface AuthTokenGetResponse {
891
967
  token: string;
892
968
  }
893
969
  declare const AuthTokenGetResponse: MessageFns$1<AuthTokenGetResponse>;
970
+ /**
971
+ * Message representing the current (coalesced) state of the autoscaler configuration
972
+ * As well as the different sources that were used to create it.
973
+ */
974
+ interface AutoscalerConfiguration {
975
+ /** The settings that are currently in effect. */
976
+ settings: AutoscalerSettings | undefined;
977
+ /** For tracking the source of the overridden value; keys correspond to fields in `settings`. */
978
+ overrideEvents: {
979
+ [key: string]: UserActionInfo;
980
+ };
981
+ /** The default settings that are used when no static settings are provided and no overrides are in effect. */
982
+ defaultSettings: AutoscalerSettings | undefined;
983
+ /** The static settings that were used to initialize the configuration. */
984
+ staticSettings: AutoscalerSettings | undefined;
985
+ /** The merge of all overrides that were used to create the current configuration. */
986
+ overrideSettings: AutoscalerSettings | undefined;
987
+ }
988
+ declare const AutoscalerConfiguration: MessageFns$1<AutoscalerConfiguration>;
894
989
  /**
895
990
  * A collection of user-configurable settings for Function autoscaling
896
991
  * These are used for static configuration and for dynamic autoscaler updates
@@ -949,6 +1044,13 @@ interface BlobGetResponse {
949
1044
  downloadUrl: string;
950
1045
  }
951
1046
  declare const BlobGetResponse: MessageFns$1<BlobGetResponse>;
1047
+ interface BlobUploadResult {
1048
+ /** The blob id (from BlobCreateResponse) that this upload attempt targeted. */
1049
+ blobId: string;
1050
+ outcome: BlobUploadResult_Outcome;
1051
+ throughputBytesS: number;
1052
+ }
1053
+ declare const BlobUploadResult: MessageFns$1<BlobUploadResult>;
952
1054
  interface BuildFunction {
953
1055
  definition: string;
954
1056
  globals: Uint8Array;
@@ -1560,6 +1662,7 @@ interface EndpointListItem {
1560
1662
  provisioningStatus: EndpointProvisioningStatus;
1561
1663
  status: string;
1562
1664
  servingMode: EndpointServingMode;
1665
+ unauthenticated: boolean;
1563
1666
  }
1564
1667
  declare const EndpointListItem: MessageFns$1<EndpointListItem>;
1565
1668
  interface EndpointListRequest {
@@ -1718,6 +1821,7 @@ interface EnvironmentListItem {
1718
1821
  spendLimitReached: boolean;
1719
1822
  environmentType: EnvironmentType;
1720
1823
  defaultMemberRole?: EnvironmentRole | undefined;
1824
+ blockUnauthenticatedResources?: boolean | undefined;
1721
1825
  }
1722
1826
  declare const EnvironmentListItem: MessageFns$1<EnvironmentListItem>;
1723
1827
  interface EnvironmentListResponse {
@@ -1766,6 +1870,12 @@ interface EnvironmentSettings {
1766
1870
  webhookSuffix: string;
1767
1871
  maxConcurrentGpus?: number | undefined;
1768
1872
  maxConcurrentTasks?: number | undefined;
1873
+ /**
1874
+ * When true, new unauthenticated web functions, Servers, tunnels, and
1875
+ * Endpoints in this environment are rejected. Unset inherits the workspace
1876
+ * default.
1877
+ */
1878
+ blockUnauthenticatedResources?: boolean | undefined;
1769
1879
  }
1770
1880
  declare const EnvironmentSettings: MessageFns$1<EnvironmentSettings>;
1771
1881
  interface EnvironmentUpdateRequest {
@@ -1774,6 +1884,7 @@ interface EnvironmentUpdateRequest {
1774
1884
  webSuffix: string | undefined;
1775
1885
  maxConcurrentTasks?: number | undefined;
1776
1886
  maxConcurrentGpus?: number | undefined;
1887
+ blockUnauthenticatedResources?: EnvironmentBlockUnauthenticatedResources | undefined;
1777
1888
  }
1778
1889
  declare const EnvironmentUpdateRequest: MessageFns$1<EnvironmentUpdateRequest>;
1779
1890
  /** A file entry when listing files in a volume or network file system. */
@@ -2208,6 +2319,15 @@ interface FunctionFinishInputsRequest {
2208
2319
  numInputs: number;
2209
2320
  }
2210
2321
  declare const FunctionFinishInputsRequest: MessageFns$1<FunctionFinishInputsRequest>;
2322
+ interface FunctionGetByIdRequest {
2323
+ functionId: string;
2324
+ }
2325
+ declare const FunctionGetByIdRequest: MessageFns$1<FunctionGetByIdRequest>;
2326
+ interface FunctionGetByIdResponse {
2327
+ function: FunctionData | undefined;
2328
+ handleMetadata: FunctionHandleMetadata | undefined;
2329
+ }
2330
+ declare const FunctionGetByIdResponse: MessageFns$1<FunctionGetByIdResponse>;
2211
2331
  interface FunctionGetCallGraphRequest {
2212
2332
  functionCallId: string;
2213
2333
  }
@@ -2215,6 +2335,8 @@ declare const FunctionGetCallGraphRequest: MessageFns$1<FunctionGetCallGraphRequ
2215
2335
  interface FunctionGetCallGraphResponse {
2216
2336
  inputs: InputCallGraphInfo[];
2217
2337
  functionCalls: FunctionCallCallGraphInfo[];
2338
+ /** Set by the server when the graph has more nodes than it will return, so `inputs` is a prefix of the graph. */
2339
+ truncated: boolean;
2218
2340
  }
2219
2341
  declare const FunctionGetCallGraphResponse: MessageFns$1<FunctionGetCallGraphResponse>;
2220
2342
  interface FunctionGetCurrentStatsRequest {
@@ -2231,6 +2353,14 @@ interface FunctionGetDynamicConcurrencyResponse {
2231
2353
  concurrency: number;
2232
2354
  }
2233
2355
  declare const FunctionGetDynamicConcurrencyResponse: MessageFns$1<FunctionGetDynamicConcurrencyResponse>;
2356
+ interface FunctionGetFlashAuthTokenRequest {
2357
+ functionId: string;
2358
+ }
2359
+ declare const FunctionGetFlashAuthTokenRequest: MessageFns$1<FunctionGetFlashAuthTokenRequest>;
2360
+ interface FunctionGetFlashAuthTokenResponse {
2361
+ token: string;
2362
+ }
2363
+ declare const FunctionGetFlashAuthTokenResponse: MessageFns$1<FunctionGetFlashAuthTokenResponse>;
2234
2364
  interface FunctionGetInputsItem {
2235
2365
  inputId: string;
2236
2366
  input: FunctionInput | undefined;
@@ -2312,6 +2442,14 @@ interface FunctionGetResponse {
2312
2442
  function: FunctionData | undefined;
2313
2443
  }
2314
2444
  declare const FunctionGetResponse: MessageFns$1<FunctionGetResponse>;
2445
+ interface FunctionGetSchedulingParamsRequest {
2446
+ functionId: string;
2447
+ }
2448
+ declare const FunctionGetSchedulingParamsRequest: MessageFns$1<FunctionGetSchedulingParamsRequest>;
2449
+ interface FunctionGetSchedulingParamsResponse {
2450
+ autoscalerConfiguration: AutoscalerConfiguration | undefined;
2451
+ }
2452
+ declare const FunctionGetSchedulingParamsResponse: MessageFns$1<FunctionGetSchedulingParamsResponse>;
2315
2453
  interface FunctionGetSerializedRequest {
2316
2454
  functionId: string;
2317
2455
  }
@@ -2329,6 +2467,8 @@ interface FunctionGetTimeRangeStatsRequest {
2329
2467
  until: Date | undefined;
2330
2468
  /** Aggregate the root Function pool and its non-version-pinned variant pools. */
2331
2469
  rollup: boolean;
2470
+ /** Filter stats for a specific container */
2471
+ containerId?: string | undefined;
2332
2472
  }
2333
2473
  declare const FunctionGetTimeRangeStatsRequest: MessageFns$1<FunctionGetTimeRangeStatsRequest>;
2334
2474
  interface FunctionGetTimeRangeStatsResponse {
@@ -2336,32 +2476,34 @@ interface FunctionGetTimeRangeStatsResponse {
2336
2476
  since: Date | undefined;
2337
2477
  /** Exclusive. */
2338
2478
  until: Date | undefined;
2339
- /**
2340
- * Per-input latency distributions.
2341
- * Execution time derived from inputs that finish in the window
2342
- */
2343
- executionTimeSeconds: FunctionStatsPercentiles | undefined;
2344
- /**
2345
- * Purposely omitted for now since it can't be computed
2346
- * from the desired tables without caveats that are confusing
2347
- * to explain to users
2348
- */
2349
- queueTimeSeconds: FunctionStatsPercentiles | undefined;
2350
- endToEndLatencySeconds: FunctionStatsPercentiles | undefined;
2351
- /** Container startup is measured from enqueue to start. */
2352
- containerStartupTimeSeconds: FunctionStatsPercentiles | undefined;
2353
2479
  /** Counts of inputs that finish in the requested time range. */
2354
2480
  inputSuccessCount: number;
2355
2481
  inputFailureCount: number;
2356
2482
  inputTimeoutCount: number;
2483
+ /** Number of inputs assigned but not finished at the exclusive end of the time range. */
2484
+ inputRunningAtEndCount: number;
2485
+ /**
2486
+ * Metrics include execution_time, end_to_end_latency, subject to change
2487
+ * as requirements evolve
2488
+ */
2489
+ inputPercentileStats: {
2490
+ [key: string]: StatsPercentileDistribution;
2491
+ };
2357
2492
  /**
2358
- * Resource distributions are computed from normalized container heartbeat
2359
- * observations and expressed as fractions, where 1.0 represents 100% utilization.
2360
- * A missing message indicates that no observations were available.
2493
+ * Container lifecycle counts. Started and errored containers are counted when
2494
+ * the corresponding event occurs in the requested time range. Creating containers
2495
+ * were enqueued but had not started or finished at the exclusive end of the range.
2361
2496
  */
2362
- cpuUtilization: FunctionStatsPercentiles | undefined;
2363
- memoryUtilization: FunctionStatsPercentiles | undefined;
2364
- gpuUtilization: FunctionStatsPercentiles | undefined;
2497
+ containerStartedCount: number;
2498
+ containerErrorCount: number;
2499
+ containerCreatingAtEndCount: number;
2500
+ /**
2501
+ * Metrics include cpu_usage, memory_usage, gpu_utilization subject to change
2502
+ * as requirements evolve
2503
+ */
2504
+ containerPercentileStats: {
2505
+ [key: string]: StatsPercentileDistribution;
2506
+ };
2365
2507
  /**
2366
2508
  * Number of direct non-version-pinned variants included in the roll-up.
2367
2509
  * Zero when roll-up is disabled or the base Function has no variants.
@@ -2401,6 +2543,8 @@ interface FunctionHandleMetadata {
2401
2543
  supportedInputFormats: DataFormat[];
2402
2544
  supportedOutputFormats: DataFormat[];
2403
2545
  appId: string;
2546
+ /** The base Function ID for a variant, or the Function's own ID otherwise. */
2547
+ baseFunctionId: string;
2404
2548
  }
2405
2549
  declare const FunctionHandleMetadata: MessageFns$1<FunctionHandleMetadata>;
2406
2550
  interface FunctionInput {
@@ -2488,6 +2632,7 @@ interface FunctionPutInputsItem {
2488
2632
  input: FunctionInput | undefined;
2489
2633
  r2Failed: boolean;
2490
2634
  r2ThroughputBytesS: number;
2635
+ blobUploadResults: BlobUploadResult[];
2491
2636
  }
2492
2637
  declare const FunctionPutInputsItem: MessageFns$1<FunctionPutInputsItem>;
2493
2638
  interface FunctionPutInputsRequest {
@@ -2565,11 +2710,6 @@ interface FunctionStats$1 {
2565
2710
  inputHeadroom: number;
2566
2711
  }
2567
2712
  declare const FunctionStats$1: MessageFns$1<FunctionStats$1>;
2568
- interface FunctionStatsPercentiles {
2569
- p50: number;
2570
- p90: number;
2571
- }
2572
- declare const FunctionStatsPercentiles: MessageFns$1<FunctionStatsPercentiles>;
2573
2713
  interface FunctionUpdateSchedulingParamsRequest {
2574
2714
  functionId: string;
2575
2715
  warmPoolSizeOverride: number;
@@ -2653,6 +2793,11 @@ interface Image$1 {
2653
2793
  };
2654
2794
  /** Volume mount for RUN commands */
2655
2795
  volumeMounts: VolumeMount[];
2796
+ /**
2797
+ * CPU architecture the image is built for. Images with an unspecified
2798
+ * arch predate this field and are treated as x86_64.
2799
+ */
2800
+ arch: Arch;
2656
2801
  }
2657
2802
  declare const Image$1: MessageFns$1<Image$1>;
2658
2803
  interface ImageBuildChainGetRequest {
@@ -3096,6 +3241,35 @@ interface ObjectDependency {
3096
3241
  objectId: string;
3097
3242
  }
3098
3243
  declare const ObjectDependency: MessageFns$1<ObjectDependency>;
3244
+ /** Policy for outbound traffic from a sandbox. */
3245
+ interface OutboundPolicy {
3246
+ /** Replace headers in outbound HTTPS requests, potentially with secret values. */
3247
+ headerReplacements: OutboundPolicy_HeaderReplacement[];
3248
+ }
3249
+ declare const OutboundPolicy: MessageFns$1<OutboundPolicy>;
3250
+ interface OutboundPolicy_HeaderReplacement {
3251
+ /**
3252
+ * Domain that the header replacements are scoped to. Supports wildcards in
3253
+ * subdomain positions.
3254
+ */
3255
+ domain: string;
3256
+ /**
3257
+ * Reference to a secret usable in the header value templates. Can be
3258
+ * empty if no secret value is used.
3259
+ */
3260
+ secretId: string;
3261
+ /**
3262
+ * Header name -> header value.
3263
+ *
3264
+ * Values support templating with keys in the stanza's secret_id: a
3265
+ * $-prefixed key name in the secret will be replaced with the secret
3266
+ * value. Literal $ characters can be represented by two dollars: `$$`.
3267
+ */
3268
+ headers: {
3269
+ [key: string]: string;
3270
+ };
3271
+ }
3272
+ declare const OutboundPolicy_HeaderReplacement: MessageFns$1<OutboundPolicy_HeaderReplacement>;
3099
3273
  interface PTYInfo {
3100
3274
  /** Soon deprecated */
3101
3275
  enabled: boolean;
@@ -3467,8 +3641,37 @@ interface Sandbox$1 {
3467
3641
  */
3468
3642
  inboundCidrAllowlist: string[];
3469
3643
  environmentVariables: StringMap | undefined;
3644
+ outboundPolicy?: OutboundPolicy | undefined;
3645
+ /**
3646
+ * If set, the sandbox's main container is served an X.509-SVID over a
3647
+ * SPIFFE Workload API socket, addressed by SPIFFE_ENDPOINT_SOCKET. The
3648
+ * certificate federates into a cloud account (AWS IAM Roles Anywhere).
3649
+ * Sidecars are not served one.
3650
+ */
3651
+ includeX509Svid: boolean;
3470
3652
  }
3471
3653
  declare const Sandbox$1: MessageFns$1<Sandbox$1>;
3654
+ interface SandboxContainerCreateV2Request {
3655
+ /** Sandbox the container joins; it runs inside that sandbox's task. */
3656
+ sandboxId: string;
3657
+ /** Logical container name, unique within the sandbox. */
3658
+ containerName: string;
3659
+ /**
3660
+ * Same definition type as SandboxCreateV2. Fields a container cannot honor
3661
+ * (resources, timeouts, scheduling constraints, ...) are rejected.
3662
+ */
3663
+ definition: Sandbox$1 | undefined;
3664
+ ephemeralSecrets: StringMap | undefined;
3665
+ cloudBucketMountCredentials: {
3666
+ [key: string]: StringMap;
3667
+ };
3668
+ }
3669
+ declare const SandboxContainerCreateV2Request: MessageFns$1<SandboxContainerCreateV2Request>;
3670
+ interface SandboxContainerCreateV2Response {
3671
+ containerId: string;
3672
+ containerName: string;
3673
+ }
3674
+ declare const SandboxContainerCreateV2Response: MessageFns$1<SandboxContainerCreateV2Response>;
3472
3675
  interface SandboxCreateConnectTokenRequest {
3473
3676
  sandboxId: string;
3474
3677
  userMetadata: string;
@@ -3886,6 +4089,71 @@ interface SecretUpdateRequest_Update {
3886
4089
  value?: string | undefined;
3887
4090
  }
3888
4091
  declare const SecretUpdateRequest_Update: MessageFns$1<SecretUpdateRequest_Update>;
4092
+ interface ServerGetTimeRangeStatsRequest {
4093
+ functionId: string;
4094
+ /** Inclusive. */
4095
+ since: Date | undefined;
4096
+ /** Exclusive. */
4097
+ until: Date | undefined;
4098
+ /** Filter stats for a specific container */
4099
+ containerId?: string | undefined;
4100
+ }
4101
+ declare const ServerGetTimeRangeStatsRequest: MessageFns$1<ServerGetTimeRangeStatsRequest>;
4102
+ interface ServerGetTimeRangeStatsResponse {
4103
+ /** Inclusive. */
4104
+ since: Date | undefined;
4105
+ /** Exclusive. */
4106
+ until: Date | undefined;
4107
+ requestCount: number;
4108
+ requestCountByStatusCode: ServerGetTimeRangeStatsResponse_ServerStatusCodeCount[];
4109
+ requestRatePerSecond: number;
4110
+ /** Metrics include request_latency, subject to change as requirements evolve. */
4111
+ requestPercentileStats: {
4112
+ [key: string]: StatsPercentileDistribution;
4113
+ };
4114
+ /**
4115
+ * Metrics include startup_time, cpu_usage, memory_usage, and
4116
+ * gpu_utilization, subject to change as requirements evolve.
4117
+ */
4118
+ containerPercentileStats: {
4119
+ [key: string]: StatsPercentileDistribution;
4120
+ };
4121
+ /** Absent when the image does not contain a supported inference engine. */
4122
+ inference: ServerGetTimeRangeStatsResponse_ServerInferenceStats | undefined;
4123
+ /**
4124
+ * Container lifecycle counts. Started and errored containers are counted when
4125
+ * the corresponding event occurs in the requested time range. Creating containers
4126
+ * were enqueued but had not started or finished at the exclusive end of the range.
4127
+ */
4128
+ containerStartedCount: number;
4129
+ containerErrorCount: number;
4130
+ containerCreatingAtEndCount: number;
4131
+ }
4132
+ declare const ServerGetTimeRangeStatsResponse: MessageFns$1<ServerGetTimeRangeStatsResponse>;
4133
+ interface ServerGetTimeRangeStatsResponse_ServerInferenceStats {
4134
+ engine: LLMEngine;
4135
+ status: ServerInferenceStatsStatus;
4136
+ /**
4137
+ * Metrics include time_to_first_token, inter_token_latency, and
4138
+ * end_to_end_latency, subject to change as requirements evolve.
4139
+ */
4140
+ percentileStats: {
4141
+ [key: string]: StatsPercentileDistribution;
4142
+ };
4143
+ /**
4144
+ * Metrics include input_tokens_per_second, cached_input_tokens_per_second,
4145
+ * and output_tokens_per_second, subject to change as requirements evolve.
4146
+ */
4147
+ scalarStats: {
4148
+ [key: string]: number;
4149
+ };
4150
+ }
4151
+ declare const ServerGetTimeRangeStatsResponse_ServerInferenceStats: MessageFns$1<ServerGetTimeRangeStatsResponse_ServerInferenceStats>;
4152
+ interface ServerGetTimeRangeStatsResponse_ServerStatusCodeCount {
4153
+ statusCode: number;
4154
+ count: number;
4155
+ }
4156
+ declare const ServerGetTimeRangeStatsResponse_ServerStatusCodeCount: MessageFns$1<ServerGetTimeRangeStatsResponse_ServerStatusCodeCount>;
3889
4157
  interface ServiceUser {
3890
4158
  name: string;
3891
4159
  tokenId: string;
@@ -3988,6 +4256,18 @@ interface SharedVolumeRemoveFileRequest {
3988
4256
  recursive: boolean;
3989
4257
  }
3990
4258
  declare const SharedVolumeRemoveFileRequest: MessageFns$1<SharedVolumeRemoveFileRequest>;
4259
+ interface StatsPercentile {
4260
+ /** The percentile expressed in basis points: 5000 is p50 and 9990 is p99.9. */
4261
+ percentileBasisPoints: number;
4262
+ value: number;
4263
+ }
4264
+ declare const StatsPercentile: MessageFns$1<StatsPercentile>;
4265
+ interface StatsPercentileDistribution {
4266
+ /** Unit identifier such as "seconds", "cores", "gibibytes", or "fraction". */
4267
+ unit: string;
4268
+ percentiles: StatsPercentile[];
4269
+ }
4270
+ declare const StatsPercentileDistribution: MessageFns$1<StatsPercentileDistribution>;
3991
4271
  interface StringMap {
3992
4272
  contents: {
3993
4273
  [key: string]: string;
@@ -4225,6 +4505,15 @@ interface UploadUrlList {
4225
4505
  items: string[];
4226
4506
  }
4227
4507
  declare const UploadUrlList: MessageFns$1<UploadUrlList>;
4508
+ /** Used for capturing context about an action performed by a user */
4509
+ interface UserActionInfo {
4510
+ userId: string;
4511
+ serviceUserId: string;
4512
+ timestamp: number;
4513
+ /** Resolved display name, could be a user or service user. */
4514
+ requestedBy: string;
4515
+ }
4516
+ declare const UserActionInfo: MessageFns$1<UserActionInfo>;
4228
4517
  interface UserGroupEnvironmentSetRequest {
4229
4518
  environmentId: string;
4230
4519
  userGroupId: string;
@@ -4295,6 +4584,11 @@ interface VolumeGetFile2Request {
4295
4584
  start: number;
4296
4585
  /** 0 is interpreted as 'read to end' */
4297
4586
  len: number;
4587
+ /**
4588
+ * The client extends each block body it downloads with zero bytes up to the
4589
+ * block's expected length, so responses may omit trailing zero bytes.
4590
+ */
4591
+ clientPadsBlocks: boolean;
4298
4592
  }
4299
4593
  declare const VolumeGetFile2Request: MessageFns$1<VolumeGetFile2Request>;
4300
4594
  interface VolumeGetFile2Response {
@@ -4541,10 +4835,13 @@ interface WebhookToken {
4541
4835
  tokenId: string;
4542
4836
  createdAt: number;
4543
4837
  scoped: boolean;
4838
+ name: string;
4839
+ createdBy: UserIdentity | undefined;
4544
4840
  }
4545
4841
  declare const WebhookToken: MessageFns$1<WebhookToken>;
4546
4842
  interface WebhookTokenCreateRequest {
4547
4843
  scoped: boolean;
4844
+ name: string;
4548
4845
  }
4549
4846
  declare const WebhookTokenCreateRequest: MessageFns$1<WebhookTokenCreateRequest>;
4550
4847
  interface WebhookTokenEnvironmentAddRequest {
@@ -4671,6 +4968,18 @@ interface WorkspaceSetDefaultEnvironmentRequest {
4671
4968
  environmentName: string;
4672
4969
  }
4673
4970
  declare const WorkspaceSetDefaultEnvironmentRequest: MessageFns$1<WorkspaceSetDefaultEnvironmentRequest>;
4971
+ interface WorkspaceSetDefaultEnvironmentSettingsRequest {
4972
+ /**
4973
+ * Omitted = no-op. INHERIT clears the workspace default so environments
4974
+ * with no override have no block. Rejects UNSPECIFIED.
4975
+ */
4976
+ blockUnauthenticatedResources?: EnvironmentBlockUnauthenticatedResources | undefined;
4977
+ }
4978
+ declare const WorkspaceSetDefaultEnvironmentSettingsRequest: MessageFns$1<WorkspaceSetDefaultEnvironmentSettingsRequest>;
4979
+ interface WorkspaceSetDefaultEnvironmentSettingsResponse {
4980
+ defaultEnvironmentSettings: EnvironmentSettings | undefined;
4981
+ }
4982
+ declare const WorkspaceSetDefaultEnvironmentSettingsResponse: MessageFns$1<WorkspaceSetDefaultEnvironmentSettingsResponse>;
4674
4983
  interface WorkspaceSetImageBuilderVersionRequest {
4675
4984
  newImageBuilderVersion: string;
4676
4985
  }
@@ -4746,6 +5055,14 @@ declare const ModalClientDefinition: {
4746
5055
  readonly responseStream: false;
4747
5056
  readonly options: {};
4748
5057
  };
5058
+ readonly appGetInfo: {
5059
+ readonly name: "AppGetInfo";
5060
+ readonly requestType: MessageFns$1<AppGetInfoRequest>;
5061
+ readonly requestStream: false;
5062
+ readonly responseType: MessageFns$1<AppGetInfoResponse>;
5063
+ readonly responseStream: false;
5064
+ readonly options: {};
5065
+ };
4749
5066
  readonly appGetLayout: {
4750
5067
  readonly name: "AppGetLayout";
4751
5068
  readonly requestType: MessageFns$1<AppGetLayoutRequest>;
@@ -5481,6 +5798,14 @@ declare const ModalClientDefinition: {
5481
5798
  readonly responseStream: false;
5482
5799
  readonly options: {};
5483
5800
  };
5801
+ readonly functionGetById: {
5802
+ readonly name: "FunctionGetById";
5803
+ readonly requestType: MessageFns$1<FunctionGetByIdRequest>;
5804
+ readonly requestStream: false;
5805
+ readonly responseType: MessageFns$1<FunctionGetByIdResponse>;
5806
+ readonly responseStream: false;
5807
+ readonly options: {};
5808
+ };
5484
5809
  readonly functionGetCallGraph: {
5485
5810
  readonly name: "FunctionGetCallGraph";
5486
5811
  readonly requestType: MessageFns$1<FunctionGetCallGraphRequest>;
@@ -5505,6 +5830,14 @@ declare const ModalClientDefinition: {
5505
5830
  readonly responseStream: false;
5506
5831
  readonly options: {};
5507
5832
  };
5833
+ readonly functionGetFlashAuthToken: {
5834
+ readonly name: "FunctionGetFlashAuthToken";
5835
+ readonly requestType: MessageFns$1<FunctionGetFlashAuthTokenRequest>;
5836
+ readonly requestStream: false;
5837
+ readonly responseType: MessageFns$1<FunctionGetFlashAuthTokenResponse>;
5838
+ readonly responseStream: false;
5839
+ readonly options: {};
5840
+ };
5508
5841
  /** For containers to request next call */
5509
5842
  readonly functionGetInputs: {
5510
5843
  readonly name: "FunctionGetInputs";
@@ -5523,6 +5856,14 @@ declare const ModalClientDefinition: {
5523
5856
  readonly responseStream: false;
5524
5857
  readonly options: {};
5525
5858
  };
5859
+ readonly functionGetSchedulingParams: {
5860
+ readonly name: "FunctionGetSchedulingParams";
5861
+ readonly requestType: MessageFns$1<FunctionGetSchedulingParamsRequest>;
5862
+ readonly requestStream: false;
5863
+ readonly responseType: MessageFns$1<FunctionGetSchedulingParamsResponse>;
5864
+ readonly responseStream: false;
5865
+ readonly options: {};
5866
+ };
5526
5867
  readonly functionGetSerialized: {
5527
5868
  readonly name: "FunctionGetSerialized";
5528
5869
  readonly requestType: MessageFns$1<FunctionGetSerializedRequest>;
@@ -5867,6 +6208,14 @@ declare const ModalClientDefinition: {
5867
6208
  readonly options: {};
5868
6209
  };
5869
6210
  /** Sandboxes */
6211
+ readonly sandboxContainerCreateV2: {
6212
+ readonly name: "SandboxContainerCreateV2";
6213
+ readonly requestType: MessageFns$1<SandboxContainerCreateV2Request>;
6214
+ readonly requestStream: false;
6215
+ readonly responseType: MessageFns$1<SandboxContainerCreateV2Response>;
6216
+ readonly responseStream: false;
6217
+ readonly options: {};
6218
+ };
5870
6219
  readonly sandboxCreate: {
5871
6220
  readonly name: "SandboxCreate";
5872
6221
  readonly requestType: MessageFns$1<SandboxCreateRequest>;
@@ -6189,6 +6538,15 @@ declare const ModalClientDefinition: {
6189
6538
  readonly responseStream: false;
6190
6539
  readonly options: {};
6191
6540
  };
6541
+ /** Servers */
6542
+ readonly serverGetTimeRangeStats: {
6543
+ readonly name: "ServerGetTimeRangeStats";
6544
+ readonly requestType: MessageFns$1<ServerGetTimeRangeStatsRequest>;
6545
+ readonly requestStream: false;
6546
+ readonly responseType: MessageFns$1<ServerGetTimeRangeStatsResponse>;
6547
+ readonly responseStream: false;
6548
+ readonly options: {};
6549
+ };
6192
6550
  /** Service users */
6193
6551
  readonly serviceUserList: {
6194
6552
  readonly name: "ServiceUserList";
@@ -6639,6 +6997,14 @@ declare const ModalClientDefinition: {
6639
6997
  readonly responseStream: false;
6640
6998
  readonly options: {};
6641
6999
  };
7000
+ readonly workspaceSetDefaultEnvironmentSettings: {
7001
+ readonly name: "WorkspaceSetDefaultEnvironmentSettings";
7002
+ readonly requestType: MessageFns$1<WorkspaceSetDefaultEnvironmentSettingsRequest>;
7003
+ readonly requestStream: false;
7004
+ readonly responseType: MessageFns$1<WorkspaceSetDefaultEnvironmentSettingsResponse>;
7005
+ readonly responseStream: false;
7006
+ readonly options: {};
7007
+ };
6642
7008
  readonly workspaceSetImageBuilderVersion: {
6643
7009
  readonly name: "WorkspaceSetImageBuilderVersion";
6644
7010
  readonly requestType: MessageFns$1<WorkspaceSetImageBuilderVersionRequest>;
@@ -7632,6 +7998,14 @@ declare enum TaskExecStdoutConfig {
7632
7998
  TASK_EXEC_STDOUT_CONFIG_PIPE = 1,
7633
7999
  UNRECOGNIZED = -1
7634
8000
  }
8001
+ interface SandboxStdinWriteV2Response {
8002
+ }
8003
+ declare const SandboxStdinWriteV2Response: MessageFns<SandboxStdinWriteV2Response>;
8004
+ interface SandboxStdioReadV2Response {
8005
+ data: Uint8Array;
8006
+ startingOffset: number;
8007
+ }
8008
+ declare const SandboxStdioReadV2Response: MessageFns<SandboxStdioReadV2Response>;
7635
8009
  interface SandboxWaitUntilReadyTcrResponse {
7636
8010
  readyAt: number;
7637
8011
  }
@@ -7918,11 +8292,26 @@ interface Profile {
7918
8292
  serverUrl: string;
7919
8293
  tokenId?: string;
7920
8294
  tokenSecret?: string;
8295
+ oauthRefreshToken?: string;
8296
+ oauthClientId?: string;
8297
+ oauthClientSecret?: string;
8298
+ oauthJwtKey?: string;
7921
8299
  environment?: string;
7922
8300
  imageBuilderVersion?: string;
7923
8301
  logLevel?: string;
7924
8302
  /** Parsed from MODAL_MAX_THROTTLE_WAIT. null means unlimited. */
7925
8303
  maxThrottleWaitSecs?: number;
8304
+ /**
8305
+ * How long a Sandbox connection may sit idle before the client gives it up.
8306
+ * The Sandbox stays usable: the next operation reconnects. Zero keeps
8307
+ * connections open until the client closes.
8308
+ */
8309
+ sandboxChannelIdleTimeoutMs: number;
8310
+ /**
8311
+ * Set by the MODAL_SANDBOX_V2 environment variable or the sandbox_v2
8312
+ * profile key in .modal.toml.
8313
+ */
8314
+ sandboxV2: boolean;
7926
8315
  }
7927
8316
 
7928
8317
  /**
@@ -7949,7 +8338,37 @@ interface StdinSource {
7949
8338
  /** @ignore */
7950
8339
  declare class TaskCommandRouterClientImpl {
7951
8340
  private stub;
8341
+ /**
8342
+ * The connection, absent while it is released. It is dialled again by the
8343
+ * next operation, so nothing may hold `stub` across one.
8344
+ */
7952
8345
  private channel;
8346
+ private dial;
8347
+ private factory;
8348
+ /**
8349
+ * How many operations are using the connection. A count rather than a flag
8350
+ * because operations overlap: only the last one out starts the idle clock.
8351
+ */
8352
+ private inFlight;
8353
+ private idle;
8354
+ /**
8355
+ * Bumped every time a connection is dialled. A stream opened on an earlier
8356
+ * one is stale: the connection under it has since been given up.
8357
+ */
8358
+ private generation;
8359
+ /**
8360
+ * Streams open right now, tracked so they can be ended on release.
8361
+ *
8362
+ * grpc-js does not cancel a call in flight when its channel is closed, and a
8363
+ * subchannel with a live call on it is never collected - so closing alone
8364
+ * leaves the socket up. Aborting the calls first is what actually frees it.
8365
+ */
8366
+ private liveStreams;
8367
+ /**
8368
+ * How long the client may go unused before its connection is given up. Zero
8369
+ * keeps it up until the client is closed. Overridable in tests.
8370
+ */
8371
+ idleTimeoutMs: number;
7953
8372
  private serverClient;
7954
8373
  private taskId;
7955
8374
  private sandboxId;
@@ -7960,14 +8379,36 @@ declare class TaskCommandRouterClientImpl {
7960
8379
  private jwtRefreshLock;
7961
8380
  private logger;
7962
8381
  private closed;
8382
+ private draining;
7963
8383
  /**
7964
8384
  * `access` is the router access returned by SandboxCreateV2, which lets a
7965
8385
  * freshly created sandbox connect without a round-trip. Pass undefined to look
7966
8386
  * it up — a re-attached sandbox, or the server could not mint a token.
7967
8387
  */
7968
8388
  static tryInit(serverClient: ModalGrpcClient, taskId: string, sandboxId: string, isV2: boolean, access: CommandRouterAccess | undefined, logger: Logger, profile: Profile): Promise<TaskCommandRouterClientImpl | null>;
7969
- private constructor();
8389
+ /**
8390
+ * Builds a client around an already-resolved connection. Public so a test can
8391
+ * construct one without the control-plane round trip `tryInit` makes; the
8392
+ * class is not exported from the package, so this is not API surface.
8393
+ */
8394
+ constructor(serverClient: ModalGrpcClient, taskId: string, sandboxId: string, isV2: boolean, serverUrl: string, jwt: string, dial: () => ReturnType<typeof createChannel>, logger: Logger, idleTimeoutMs: number);
8395
+ /**
8396
+ * Says the client is about to be used: holds off the idle timer, and dials
8397
+ * again if the connection was already given up. Returns the generation being
8398
+ * used; pair every call with endOp.
8399
+ */
8400
+ private beginOp;
8401
+ /** Says the caller is done. The last one out starts the clock. */
8402
+ private endOp;
8403
+ /**
8404
+ * Starts the countdown to giving the connection back. Call it with nothing
8405
+ * in flight.
8406
+ */
8407
+ private armIdleTimer;
8408
+ /** Refuse new operations and release resources after current operations finish. */
8409
+ closeWhenIdle(): void;
7970
8410
  close(): void;
8411
+ private callWithRetries;
7971
8412
  /** Run a unary RPC against the command router with the default retry policy. */
7972
8413
  private callUnary;
7973
8414
  execStart(request: TaskExecStartRequest): Promise<TaskExecStartResponse>;
@@ -7976,7 +8417,7 @@ declare class TaskCommandRouterClientImpl {
7976
8417
  containerList(request: TaskContainerListRequest): Promise<TaskContainerListResponse>;
7977
8418
  containerTerminate(request: TaskContainerTerminateRequest): Promise<void>;
7978
8419
  containerWait(request: TaskContainerWaitRequest): Promise<TaskContainerWaitResponse>;
7979
- execStdioRead(taskId: string, execId: string, fileDescriptor: FileDescriptor, deadline?: number | null): AsyncGenerator<TaskExecStdioReadResponse>;
8420
+ execStdioRead(taskId: string, execId: string, fileDescriptor: FileDescriptor, deadline?: number | null, signal?: AbortSignal): AsyncGenerator<TaskExecStdioReadResponse>;
7980
8421
  execStdinWrite(taskId: string, execId: string, offset: number, data: Uint8Array, eof: boolean): Promise<TaskExecStdinWriteResponse>;
7981
8422
  /**
7982
8423
  * Read the current stdin write status for an exec'd command.
@@ -8010,10 +8451,20 @@ declare class TaskCommandRouterClientImpl {
8010
8451
  * within this window, the call is cancelled and a TimeoutError is thrown.
8011
8452
  */
8012
8453
  reloadVolumes(request: TaskReloadVolumesRequest, options?: TimeoutOptions): Promise<void>;
8454
+ sandboxStdioReadV2(taskId: string, fileDescriptor: FileDescriptor, signal?: AbortSignal): AsyncGenerator<SandboxStdioReadV2Response>;
8455
+ sandboxStdinWriteV2(taskId: string, offset: number, data: Uint8Array, eof: boolean): Promise<SandboxStdinWriteV2Response>;
8013
8456
  sandboxWaitUntilReady(taskId: string, timeoutMs: number): Promise<SandboxWaitUntilReadyTcrResponse>;
8014
8457
  private refreshJwt;
8458
+ /** The caller holds an operation lease across authentication and all retries. */
8015
8459
  private callWithAuthRetry;
8016
- private streamStdio;
8460
+ /**
8461
+ * Yields the next chunk of stdio, opening or reopening the stream as it needs
8462
+ * to, and determining whether or not to retry a failed open or read. It waits
8463
+ * out the backoff itself.
8464
+ */
8465
+ private streamStdioWithRetries;
8466
+ private streamExecStdio;
8467
+ private streamSandboxStdio;
8017
8468
  }
8018
8469
 
8019
8470
  /** Type of a filesystem entry. */
@@ -8228,12 +8679,15 @@ declare class SandboxFilesystem {
8228
8679
  writeText(data: string, remotePath: string): Promise<void>;
8229
8680
  }
8230
8681
 
8231
- type SandboxSidecarCommandRouter = Pick<TaskCommandRouterClientImpl, "containerCreate" | "containerGet" | "containerList" | "containerTerminate" | "containerWait">;
8682
+ type SandboxSidecarCommandRouter = Pick<TaskCommandRouterClientImpl, "containerCreate" | "containerGet" | "containerList" | "containerTerminate" | "containerWait" | "mountDirectory" | "snapshotDirectory" | "unmountDirectory">;
8232
8683
  type SandboxSidecarAccess = {
8233
8684
  client: ModalClient;
8685
+ sandboxId: string;
8686
+ ensureAttached(): void;
8234
8687
  exec(command: string[], params: SandboxExecParams | undefined, containerId: string): Promise<ContainerProcess>;
8235
8688
  commandRouter(): Promise<[string, SandboxSidecarCommandRouter]>;
8236
8689
  reloadVolumes(containerId: string, params: SidecarReloadVolumesParams | undefined): Promise<void>;
8690
+ snapshotFilesystem(containerId: string, params: SidecarSnapshotFilesystemParams | undefined): Promise<Image>;
8237
8691
  };
8238
8692
  /** Options for {@link SidecarService#create SidecarService.create()}. */
8239
8693
  type SidecarCreateParams = {
@@ -8276,11 +8730,24 @@ type SidecarTerminateParams = {
8276
8730
  /** If true, wait for the sidecar container to terminate. */
8277
8731
  wait?: boolean;
8278
8732
  };
8733
+ /** Optional parameters for {@link SidecarContainer#snapshotFilesystem SidecarContainer.snapshotFilesystem()}. */
8734
+ type SidecarSnapshotFilesystemParams = {
8735
+ /** Overall budget for the snapshot call, in milliseconds. Defaults to 55000. */
8736
+ timeoutMs?: number;
8737
+ /** Lifetime of the resulting image in milliseconds. Defaults to 30 days. Pass `null` for no expiry. */
8738
+ ttlMs?: number | null;
8739
+ };
8279
8740
  /** Optional parameters for {@link SidecarContainer#reloadVolumes SidecarContainer.reloadVolumes()}. */
8280
8741
  type SidecarReloadVolumesParams = {
8281
8742
  /** Overall budget in milliseconds. Defaults to 55000. */
8282
8743
  timeoutMs?: number;
8283
8744
  };
8745
+ /** Optional parameters for {@link SidecarContainer#mountImage SidecarContainer.mountImage()}. */
8746
+ type SidecarMountImageParams = SandboxMountImageParams;
8747
+ /** Optional parameters for {@link SidecarContainer#unmountImage SidecarContainer.unmountImage()}. */
8748
+ type SidecarUnmountImageParams = Record<string, never>;
8749
+ /** Optional parameters for {@link SidecarContainer#snapshotDirectory SidecarContainer.snapshotDirectory()}. */
8750
+ type SidecarSnapshotDirectoryParams = SandboxSnapshotDirectoryParams;
8284
8751
  /**
8285
8752
  * Creates and manages sidecar containers inside a Sandbox.
8286
8753
  *
@@ -8334,6 +8801,8 @@ declare class SidecarContainer {
8334
8801
  terminate(params: {
8335
8802
  wait: true;
8336
8803
  }): Promise<number>;
8804
+ /** Snapshot this Sidecar container's filesystem into an Image. */
8805
+ snapshotFilesystem(params?: SidecarSnapshotFilesystemParams): Promise<Image>;
8337
8806
  /**
8338
8807
  * Reload all Volumes mounted in this sidecar container.
8339
8808
  *
@@ -8341,6 +8810,39 @@ declare class SidecarContainer {
8341
8810
  * (the reload may still complete in the background).
8342
8811
  */
8343
8812
  reloadVolumes(params?: SidecarReloadVolumesParams): Promise<void>;
8813
+ /**
8814
+ * Mount an {@link Image} at a path in this Sidecar container's filesystem.
8815
+ *
8816
+ * @param path - The path where the directory should be mounted
8817
+ * @param image - Optional {@link Image} to mount. If undefined, mounts an empty directory.
8818
+ * @param params - Optional parameters; see {@link SidecarMountImageParams}.
8819
+ */
8820
+ mountImage(path: string, image?: Image, params?: SidecarMountImageParams): Promise<void>;
8821
+ /**
8822
+ * Unmounts an {@link Image} previously mounted at a path in this Sidecar container's filesystem.
8823
+ *
8824
+ * @param path - The mount path to unmount
8825
+ */
8826
+ unmountImage(path: string, _params?: SidecarUnmountImageParams): Promise<void>;
8827
+ /**
8828
+ * Snapshots and creates a new {@link Image} from a directory in the running Sidecar container.
8829
+ *
8830
+ * The resulting Image is retained for `ttlMs` (default: 30 days),
8831
+ * as a hard cutoff measured from creation — usage does not extend
8832
+ * the lifetime. Pass `ttlMs: null` to retain indefinitely.
8833
+ *
8834
+ * The call has an overall `timeoutMs` budget (default: 55000). If it
8835
+ * elapses before a snapshot completes, the call is cancelled and an
8836
+ * error is thrown.
8837
+ *
8838
+ * The Image can be used anywhere an Image is accepted, including as a mount
8839
+ * or as the base filesystem for another container.
8840
+ *
8841
+ * @param path - The path of the directory to snapshot
8842
+ * @param params - Optional parameters; see {@link SidecarSnapshotDirectoryParams}.
8843
+ * @returns Promise that resolves to an {@link Image}
8844
+ */
8845
+ snapshotDirectory(path: string, params?: SidecarSnapshotDirectoryParams): Promise<Image>;
8344
8846
  }
8345
8847
 
8346
8848
  /**
@@ -8514,7 +9016,9 @@ type SandboxCreateParams = {
8514
9016
  name?: string;
8515
9017
  /** Tags to attach to the Sandbox. Filterable via {@link SandboxService#list client.sandboxes.list}. */
8516
9018
  tags?: Record<string, string>;
8517
- /** Optional experimental options. */
9019
+ /**
9020
+ * Optional experimental options. Values must be booleans or strings.
9021
+ */
8518
9022
  experimentalOptions?: Record<string, any>;
8519
9023
  /** If set, connections to this Sandbox will be subdomains of this domain rather than the default.
8520
9024
  * This requires prior manual setup by Modal and is only available for Enterprise customers.
@@ -8851,6 +9355,9 @@ declare class Sandbox {
8851
9355
  * Disconnect from the Sandbox, cleaning up local resources.
8852
9356
  * The Sandbox continues running on Modal's infrastructure.
8853
9357
  * After calling detach(), most operations on this Sandbox object will throw.
9358
+ *
9359
+ * This does not block on or interrupt ongoing reads or calls. Connection
9360
+ * resources are closed promptly once those operations finish.
8854
9361
  */
8855
9362
  detach(): void;
8856
9363
  wait(): Promise<number>;
@@ -8887,13 +9394,39 @@ declare class Sandbox {
8887
9394
  /**
8888
9395
  * Get the exit filesystem snapshot image.
8889
9396
  *
9397
+ * An exit snapshot captures the Sandbox filesystem when the Sandbox exits,
9398
+ * whether its entrypoint finishes gracefully, abruptly, or it is stopped with
9399
+ * {@link Sandbox#terminate}. The resulting {@link Image} can be passed to
9400
+ * {@link SandboxService#create client.sandboxes.create()} to start a new
9401
+ * Sandbox from the saved filesystem.
9402
+ *
9403
+ * Exit snapshots are opt-in: the Sandbox must have been created with
9404
+ * `experimentalOptions: { enable_exit_snapshot: true }`. Calling this on a
9405
+ * Sandbox created without that option throws an {@link InvalidError}.
9406
+ *
9407
+ * @example
9408
+ * ```ts
9409
+ * const sb = await modal.sandboxes.create(app, image, {
9410
+ * experimentalOptions: { enable_exit_snapshot: true },
9411
+ * });
9412
+ * // ... use the Sandbox ...
9413
+ * await sb.terminate();
9414
+ * const image = await sb.experimentalGetExitSnapshot();
9415
+ * const sb2 = await modal.sandboxes.create(app, image);
9416
+ * ```
9417
+ *
8890
9418
  * EXPERIMENTAL: the API is subject to change.
8891
9419
  *
8892
9420
  * @param params - Optional parameters; see SandboxExperimentalGetExitSnapshotParams.
8893
9421
  * @returns The exit snapshot Image.
9422
+ * @throws {InvalidError} If `timeoutMs` is negative, or if exit snapshots
9423
+ * were not enabled when the Sandbox was created.
8894
9424
  * @throws {TimeoutError} If `timeoutMs` elapses before the snapshot
8895
9425
  * reaches a terminal state. This includes `timeoutMs = 0` when the
8896
9426
  * snapshot is still pending.
9427
+ * @throws {SnapshotCreationError} Snapshot operation is done and failed.
9428
+ * Polling again will not produce an Image; filesystem state is gone.
9429
+ * @throws {NotFoundError} If the Sandbox does not exist.
8897
9430
  */
8898
9431
  experimentalGetExitSnapshot(params?: SandboxExperimentalGetExitSnapshotParams): Promise<Image>;
8899
9432
  /**
@@ -8999,6 +9532,14 @@ declare class ContainerProcess<R extends string | Uint8Array = any> {
8999
9532
  interface ModalClientParams {
9000
9533
  tokenId?: string;
9001
9534
  tokenSecret?: string;
9535
+ /** OAuth refresh token returned by Modal's token endpoint. */
9536
+ oauthRefreshToken?: string;
9537
+ /** Modal-issued OAuth client ID, with an `oc-` prefix. */
9538
+ oauthClientId?: string;
9539
+ /** Modal-issued OAuth client secret, with an `ov-` prefix. */
9540
+ oauthClientSecret?: string;
9541
+ /** Unencrypted RSA private key encoded as PEM, with literal or escaped newlines. */
9542
+ oauthJwtKey?: string;
9002
9543
  environment?: string;
9003
9544
  endpoint?: string;
9004
9545
  timeoutMs?: number;
@@ -9059,8 +9600,10 @@ declare class ModalClient {
9059
9600
  private authTokenManager;
9060
9601
  private customMiddleware;
9061
9602
  private environmentManager;
9603
+ private oauthJwtKey?;
9062
9604
  constructor(params?: ModalClientParams);
9063
9605
  environmentName(environment?: string): string;
9606
+ private validateProfileCredentials;
9064
9607
  /**
9065
9608
  * Returns the image builder version by querying the server where the local profile takes
9066
9609
  * precedence.
@@ -9207,7 +9750,7 @@ declare class SandboxFilesystemPermissionError extends SandboxFilesystemError {
9207
9750
  declare class SandboxTimeoutError extends Error {
9208
9751
  constructor(message?: string);
9209
9752
  }
9210
- /** No snapshot image will be produced for a Sandbox. */
9753
+ /** Snapshot operation is done and failed. Polling again will not produce an Image; filesystem state is gone. */
9211
9754
  declare class SnapshotCreationError extends Error {
9212
9755
  constructor(message: string);
9213
9756
  }
@@ -9218,4 +9761,4 @@ declare class ClientClosedError extends Error {
9218
9761
 
9219
9762
  declare function checkForRenamedParams(params: any, renames: Record<string, string>): void;
9220
9763
 
9221
- 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 };
9764
+ 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 };