modal 0.7.4 → 0.7.6

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.ts CHANGED
@@ -126,6 +126,32 @@ declare enum DeploymentNamespace {
126
126
  DEPLOYMENT_NAMESPACE_GLOBAL = 3,
127
127
  UNRECOGNIZED = -1
128
128
  }
129
+ declare enum EndpointApiSurface {
130
+ ENDPOINT_API_SURFACE_UNSPECIFIED = 0,
131
+ ENDPOINT_API_SURFACE_OPENAI_CHAT_COMPLETIONS = 1,
132
+ ENDPOINT_API_SURFACE_OPENAI_RESPONSES = 2,
133
+ ENDPOINT_API_SURFACE_ANTHROPIC_MESSAGES = 3,
134
+ UNRECOGNIZED = -1
135
+ }
136
+ declare enum EndpointInputModality {
137
+ ENDPOINT_INPUT_MODALITY_UNSPECIFIED = 0,
138
+ ENDPOINT_INPUT_MODALITY_TEXT = 1,
139
+ ENDPOINT_INPUT_MODALITY_IMAGE = 2,
140
+ ENDPOINT_INPUT_MODALITY_AUDIO = 3,
141
+ UNRECOGNIZED = -1
142
+ }
143
+ declare enum EndpointStopSource {
144
+ ENDPOINT_STOP_SOURCE_UNSPECIFIED = 0,
145
+ ENDPOINT_STOP_SOURCE_CLI = 1,
146
+ ENDPOINT_STOP_SOURCE_WEB = 2,
147
+ UNRECOGNIZED = -1
148
+ }
149
+ declare enum EnvironmentRole {
150
+ ENVIRONMENT_ROLE_UNSPECIFIED = 0,
151
+ ENVIRONMENT_ROLE_VIEWER = 1,
152
+ ENVIRONMENT_ROLE_CONTRIBUTOR = 2,
153
+ UNRECOGNIZED = -1
154
+ }
129
155
  declare enum ExecOutputOption {
130
156
  EXEC_OUTPUT_OPTION_UNSPECIFIED = 0,
131
157
  EXEC_OUTPUT_OPTION_DEVNULL = 1,
@@ -171,6 +197,20 @@ declare enum GPUType {
171
197
  GPU_TYPE_H200 = 12,
172
198
  UNRECOGNIZED = -1
173
199
  }
200
+ declare enum IdentityProviderType {
201
+ IDENTITY_PROVIDER_TYPE_UNSPECIFIED = 0,
202
+ IDENTITY_PROVIDER_TYPE_GITHUB = 1,
203
+ IDENTITY_PROVIDER_TYPE_OKTA = 2,
204
+ IDENTITY_PROVIDER_TYPE_GOOGLE_OAUTH = 3,
205
+ UNRECOGNIZED = -1
206
+ }
207
+ declare enum MemberRole {
208
+ MEMBER_ROLE_UNSPECIFIED = 0,
209
+ MEMBER_ROLE_USER = 1,
210
+ MEMBER_ROLE_MANAGER = 2,
211
+ MEMBER_ROLE_OWNER = 3,
212
+ UNRECOGNIZED = -1
213
+ }
174
214
  declare enum ObjectCreationType {
175
215
  /** OBJECT_CREATION_TYPE_UNSPECIFIED - just lookup */
176
216
  OBJECT_CREATION_TYPE_UNSPECIFIED = 0,
@@ -513,7 +553,14 @@ interface AppGetByDeploymentNameRequest {
513
553
  }
514
554
  declare const AppGetByDeploymentNameRequest: MessageFns$1<AppGetByDeploymentNameRequest>;
515
555
  interface AppGetByDeploymentNameResponse {
556
+ /** Null when App with requested name is not deployed */
516
557
  appId: string;
558
+ /** Populated if App with requested name was recently stopped */
559
+ previousAppId: string;
560
+ /** Populated because server may resolve default environment */
561
+ environmentName: string;
562
+ /** Lifecycle of current App or recently stopped App */
563
+ lifecycle: AppLifecycle | undefined;
517
564
  }
518
565
  declare const AppGetByDeploymentNameResponse: MessageFns$1<AppGetByDeploymentNameResponse>;
519
566
  interface AppGetLayoutRequest {
@@ -769,7 +816,7 @@ interface AutoscalerSettings {
769
816
  maxContainers?: number | undefined;
770
817
  /** Additional container to spin up when Function is active */
771
818
  bufferContainers?: number | undefined;
772
- /** Currently unused; a placeholder in case we decide to expose scaleup control to users */
819
+ /** Stabilization window (in seconds) before scaling up; requires sustained demand over this period */
773
820
  scaleupWindow?: number | undefined;
774
821
  /** Maximum amount of time a container can be idle before being scaled down, in seconds; pka "container_idle_timeout" */
775
822
  scaledownWindow?: number | undefined;
@@ -1311,14 +1358,117 @@ interface DomainListResponse {
1311
1358
  domains: Domain[];
1312
1359
  }
1313
1360
  declare const DomainListResponse: MessageFns$1<DomainListResponse>;
1361
+ interface EndpointComputeRegionSpec {
1362
+ auto?: Empty | undefined;
1363
+ colocated?: Empty | undefined;
1364
+ explicit?: EndpointComputeRegionSpec_ExplicitRegions | undefined;
1365
+ }
1366
+ declare const EndpointComputeRegionSpec: MessageFns$1<EndpointComputeRegionSpec>;
1367
+ interface EndpointComputeRegionSpec_ExplicitRegions {
1368
+ regions: string[];
1369
+ }
1370
+ declare const EndpointComputeRegionSpec_ExplicitRegions: MessageFns$1<EndpointComputeRegionSpec_ExplicitRegions>;
1371
+ interface EndpointCreateRequest {
1372
+ name: string;
1373
+ description: string;
1374
+ proxyRegions: string[];
1375
+ computeRegion: EndpointComputeRegionSpec | undefined;
1376
+ model: EndpointModelSource | undefined;
1377
+ apiSurfaces: EndpointApiSurface[];
1378
+ inputModalities: EndpointInputModality[];
1379
+ environmentName: string;
1380
+ }
1381
+ declare const EndpointCreateRequest: MessageFns$1<EndpointCreateRequest>;
1382
+ interface EndpointCreateResponse {
1383
+ endpointId: string;
1384
+ }
1385
+ declare const EndpointCreateResponse: MessageFns$1<EndpointCreateResponse>;
1386
+ interface EndpointCustomModelSource {
1387
+ baseModelRepoId: string;
1388
+ huggingface?: EndpointHuggingFaceModelSource | undefined;
1389
+ modalVolume?: EndpointModalVolumeModelSource | undefined;
1390
+ }
1391
+ declare const EndpointCustomModelSource: MessageFns$1<EndpointCustomModelSource>;
1392
+ interface EndpointHuggingFaceModelSource {
1393
+ repoId: string;
1394
+ revision: string;
1395
+ huggingfaceToken: string;
1396
+ }
1397
+ declare const EndpointHuggingFaceModelSource: MessageFns$1<EndpointHuggingFaceModelSource>;
1398
+ interface EndpointListItem {
1399
+ endpointId: string;
1400
+ name: string;
1401
+ description: string;
1402
+ activeDeploymentId: string;
1403
+ updatedAt: number;
1404
+ metadata: EndpointMetadata | undefined;
1405
+ }
1406
+ declare const EndpointListItem: MessageFns$1<EndpointListItem>;
1407
+ interface EndpointListRequest {
1408
+ environmentName: string;
1409
+ pagination: ListPagination | undefined;
1410
+ }
1411
+ declare const EndpointListRequest: MessageFns$1<EndpointListRequest>;
1412
+ interface EndpointListResponse {
1413
+ items: EndpointListItem[];
1414
+ environmentName: string;
1415
+ }
1416
+ declare const EndpointListResponse: MessageFns$1<EndpointListResponse>;
1417
+ interface EndpointMetadata {
1418
+ name: string;
1419
+ creationInfo: CreationInfo | undefined;
1420
+ }
1421
+ declare const EndpointMetadata: MessageFns$1<EndpointMetadata>;
1422
+ interface EndpointModalVolumeModelSource {
1423
+ volumeId: string;
1424
+ modelPath: string;
1425
+ }
1426
+ declare const EndpointModalVolumeModelSource: MessageFns$1<EndpointModalVolumeModelSource>;
1427
+ interface EndpointModelSource {
1428
+ baseModelRepoId?: string | undefined;
1429
+ custom?: EndpointCustomModelSource | undefined;
1430
+ }
1431
+ declare const EndpointModelSource: MessageFns$1<EndpointModelSource>;
1432
+ interface EndpointStopRequest {
1433
+ endpointId: string;
1434
+ source: EndpointStopSource;
1435
+ }
1436
+ declare const EndpointStopRequest: MessageFns$1<EndpointStopRequest>;
1437
+ interface EndpointStopResponse {
1438
+ }
1439
+ declare const EndpointStopResponse: MessageFns$1<EndpointStopResponse>;
1314
1440
  interface EnvironmentCreateRequest {
1315
1441
  name: string;
1442
+ isManaged: boolean;
1316
1443
  }
1317
1444
  declare const EnvironmentCreateRequest: MessageFns$1<EnvironmentCreateRequest>;
1318
1445
  interface EnvironmentDeleteRequest {
1319
1446
  name: string;
1320
1447
  }
1321
1448
  declare const EnvironmentDeleteRequest: MessageFns$1<EnvironmentDeleteRequest>;
1449
+ interface EnvironmentGetManagedRequest {
1450
+ environmentId: string;
1451
+ }
1452
+ declare const EnvironmentGetManagedRequest: MessageFns$1<EnvironmentGetManagedRequest>;
1453
+ interface EnvironmentGetManagedResponse {
1454
+ environmentId: string;
1455
+ name: string;
1456
+ createdAt: number;
1457
+ principalRoles: EnvironmentGetManagedResponse_PrincipalEnvRole[];
1458
+ additionalRoles: EnvironmentGetManagedResponse_PrincipalEnvRole[];
1459
+ }
1460
+ declare const EnvironmentGetManagedResponse: MessageFns$1<EnvironmentGetManagedResponse>;
1461
+ interface EnvironmentGetManagedResponse_PrincipalEnvRole {
1462
+ userId: string;
1463
+ serviceUserId: string;
1464
+ email: string;
1465
+ avatarUrl: string;
1466
+ serviceUserName: string;
1467
+ role: EnvironmentRole;
1468
+ memberRole: MemberRole;
1469
+ userName: string;
1470
+ }
1471
+ declare const EnvironmentGetManagedResponse_PrincipalEnvRole: MessageFns$1<EnvironmentGetManagedResponse_PrincipalEnvRole>;
1322
1472
  interface EnvironmentGetOrCreateRequest {
1323
1473
  deploymentName: string;
1324
1474
  objectCreationType: ObjectCreationType;
@@ -1351,6 +1501,18 @@ interface EnvironmentMetadata {
1351
1501
  settings: EnvironmentSettings | undefined;
1352
1502
  }
1353
1503
  declare const EnvironmentMetadata: MessageFns$1<EnvironmentMetadata>;
1504
+ interface EnvironmentRoleSetRequest {
1505
+ environmentId: string;
1506
+ userId: string;
1507
+ serviceUserId: string;
1508
+ role: EnvironmentRole;
1509
+ }
1510
+ declare const EnvironmentRoleSetRequest: MessageFns$1<EnvironmentRoleSetRequest>;
1511
+ interface EnvironmentSetManagedRequest {
1512
+ environmentId: string;
1513
+ managed: boolean;
1514
+ }
1515
+ declare const EnvironmentSetManagedRequest: MessageFns$1<EnvironmentSetManagedRequest>;
1354
1516
  /**
1355
1517
  * Environment-scoped settings, with workspace-level defaults.
1356
1518
  * Note that we use MergeFrom to combine workspace / environment settings,
@@ -1473,7 +1635,7 @@ interface FunctionMessage {
1473
1635
  objectDependencies: ObjectDependency[];
1474
1636
  blockNetwork: boolean;
1475
1637
  /**
1476
- * In the SDK, we've deprecated `max_inputs` (which only every implemented `max_inputs=1`)
1638
+ * In the SDK, we've deprecated `max_inputs` (which only ever implemented `max_inputs=1`)
1477
1639
  * in favor of a boolean `single_use_containers` parameter.
1478
1640
  */
1479
1641
  maxInputs: number;
@@ -1510,6 +1672,8 @@ interface FunctionMessage {
1510
1672
  /**
1511
1673
  * _experimental_proxy_ip -> ProxyInfo
1512
1674
  * TODO: deprecate.
1675
+ *
1676
+ * @deprecated
1513
1677
  */
1514
1678
  ExperimentalProxyIp?: string | undefined;
1515
1679
  /** For internal debugging use only. */
@@ -1562,6 +1726,8 @@ interface FunctionMessage {
1562
1726
  singleUseContainers: boolean;
1563
1727
  /** When True, the function is a server function */
1564
1728
  isServer: boolean;
1729
+ /** Where inputs to a function should be routed through. */
1730
+ routingRegion: string;
1565
1731
  }
1566
1732
  declare const FunctionMessage: MessageFns$1<FunctionMessage>;
1567
1733
  interface FunctionAsyncInvokeRequest {
@@ -1712,6 +1878,8 @@ interface FunctionData {
1712
1878
  /**
1713
1879
  * _experimental_proxy_ip -> ProxyInfo
1714
1880
  * TODO: deprecate.
1881
+ *
1882
+ * @deprecated
1715
1883
  */
1716
1884
  ExperimentalProxyIp?: string | undefined;
1717
1885
  /** Mapping of method names to method definitions, only non-empty for class service functions */
@@ -1754,6 +1922,8 @@ interface FunctionData {
1754
1922
  implementationName: string;
1755
1923
  /** When True, the function is a server function */
1756
1924
  isServer: boolean;
1925
+ /** Where inputs to a function should be routed through. */
1926
+ routingRegion: string;
1757
1927
  }
1758
1928
  declare const FunctionData: MessageFns$1<FunctionData>;
1759
1929
  interface FunctionData_RankedFunction {
@@ -1768,7 +1938,6 @@ interface FunctionFinishInputsRequest {
1768
1938
  }
1769
1939
  declare const FunctionFinishInputsRequest: MessageFns$1<FunctionFinishInputsRequest>;
1770
1940
  interface FunctionGetCallGraphRequest {
1771
- /** TODO: use input_id once we switch client submit API to return those. */
1772
1941
  functionCallId: string;
1773
1942
  }
1774
1943
  declare const FunctionGetCallGraphRequest: MessageFns$1<FunctionGetCallGraphRequest>;
@@ -1801,6 +1970,7 @@ interface FunctionGetInputsItem {
1801
1970
  /** intercepted and only used by the worker. */
1802
1971
  functionMapIdx?: number | undefined;
1803
1972
  attemptToken: string;
1973
+ fromInputPlane: boolean;
1804
1974
  }
1805
1975
  declare const FunctionGetInputsItem: MessageFns$1<FunctionGetInputsItem>;
1806
1976
  interface FunctionGetInputsRequest {
@@ -2024,6 +2194,8 @@ interface FunctionPutOutputsItem {
2024
2194
  functionCallId: string;
2025
2195
  /** injected by the worker */
2026
2196
  functionMapIdx?: number | undefined;
2197
+ /** injected by the worker */
2198
+ fromInputPlane: boolean;
2027
2199
  }
2028
2200
  declare const FunctionPutOutputsItem: MessageFns$1<FunctionPutOutputsItem>;
2029
2201
  interface FunctionPutOutputsRequest {
@@ -2066,6 +2238,7 @@ interface FunctionStats$1 {
2066
2238
  backlog: number;
2067
2239
  numTotalTasks: number;
2068
2240
  numRunningInputs: number;
2241
+ inputHeadroom: number;
2069
2242
  }
2070
2243
  declare const FunctionStats$1: MessageFns$1<FunctionStats$1>;
2071
2244
  interface FunctionUpdateSchedulingParamsRequest {
@@ -2811,9 +2984,9 @@ interface Sandbox$1 {
2811
2984
  /** Optional idle timeout in seconds. If set, the sandbox will be terminated after being idle for this duration. */
2812
2985
  idleTimeoutSecs?: number | undefined;
2813
2986
  /**
2814
- * If set, the sandbox will be created with direct sandbox commands enabled.
2815
- * Exec commands for the sandbox will be issued directly to the sandbox
2816
- * command router running on the Modal worker.
2987
+ * Deprecated: direct sandbox commands are always enabled.
2988
+ *
2989
+ * @deprecated
2817
2990
  */
2818
2991
  directSandboxCommandsEnabled: boolean;
2819
2992
  /**
@@ -2832,6 +3005,12 @@ interface Sandbox$1 {
2832
3005
  includeOidcIdentityToken: boolean;
2833
3006
  /** Probe used to determine when the sandbox has become ready. */
2834
3007
  readinessProbe?: Probe$1 | undefined;
3008
+ /**
3009
+ * If set, only connections from these CIDRs will be allowed to connect to the sandbox
3010
+ * (tunnels and auth proxy).
3011
+ */
3012
+ inboundCidrAllowlist: string[];
3013
+ environmentVariables: StringMap | undefined;
2835
3014
  }
2836
3015
  declare const Sandbox$1: MessageFns$1<Sandbox$1>;
2837
3016
  interface SandboxCreateConnectTokenRequest {
@@ -2849,6 +3028,7 @@ interface SandboxCreateRequest {
2849
3028
  definition: Sandbox$1 | undefined;
2850
3029
  /** DEPRECATED* 7/16/2025 */
2851
3030
  environmentName: string;
3031
+ tags: SandboxTag[];
2852
3032
  }
2853
3033
  declare const SandboxCreateRequest: MessageFns$1<SandboxCreateRequest>;
2854
3034
  interface SandboxCreateResponse {
@@ -2877,6 +3057,12 @@ declare const SandboxGetCommandRouterAccessRequest: MessageFns$1<SandboxGetComma
2877
3057
  interface SandboxGetCommandRouterAccessResponse {
2878
3058
  jwt: string;
2879
3059
  url: string;
3060
+ /**
3061
+ * Worker's public IPv4 address. When set, clients should connect directly
3062
+ * to this IP while still using the URL's hostname for TLS SNI and the
3063
+ * HTTP/2 :authority header.
3064
+ */
3065
+ workerIpv4Address: string;
2880
3066
  }
2881
3067
  declare const SandboxGetCommandRouterAccessResponse: MessageFns$1<SandboxGetCommandRouterAccessResponse>;
2882
3068
  interface SandboxGetFromNameRequest {
@@ -2950,6 +3136,8 @@ interface SandboxInfo {
2950
3136
  timeoutSecs: number;
2951
3137
  idleTimeoutSecs?: number | undefined;
2952
3138
  readyAt?: number | undefined;
3139
+ readinessProbe?: Probe$1 | undefined;
3140
+ tunnels: TunnelData[];
2953
3141
  }
2954
3142
  declare const SandboxInfo: MessageFns$1<SandboxInfo>;
2955
3143
  interface SandboxListRequest {
@@ -3171,12 +3359,26 @@ interface SecretUpdateRequest_Update {
3171
3359
  value?: string | undefined;
3172
3360
  }
3173
3361
  declare const SecretUpdateRequest_Update: MessageFns$1<SecretUpdateRequest_Update>;
3362
+ interface ServiceUser {
3363
+ name: string;
3364
+ tokenId: string;
3365
+ createdBy: string;
3366
+ createdAt: number;
3367
+ lastUsedAt: number;
3368
+ createdByAvatarUrl: string;
3369
+ serviceUserId: string;
3370
+ }
3371
+ declare const ServiceUser: MessageFns$1<ServiceUser>;
3174
3372
  interface ServiceUserIdentity {
3175
3373
  serviceUserId: string;
3176
3374
  serviceUserName: string;
3177
3375
  createdBy: UserIdentity | undefined;
3178
3376
  }
3179
3377
  declare const ServiceUserIdentity: MessageFns$1<ServiceUserIdentity>;
3378
+ interface ServiceUserListResponse {
3379
+ serviceUsers: ServiceUser[];
3380
+ }
3381
+ declare const ServiceUserListResponse: MessageFns$1<ServiceUserListResponse>;
3180
3382
  interface SharedVolumeDeleteRequest {
3181
3383
  sharedVolumeId: string;
3182
3384
  }
@@ -3259,6 +3461,12 @@ interface SharedVolumeRemoveFileRequest {
3259
3461
  recursive: boolean;
3260
3462
  }
3261
3463
  declare const SharedVolumeRemoveFileRequest: MessageFns$1<SharedVolumeRemoveFileRequest>;
3464
+ interface StringMap {
3465
+ contents: {
3466
+ [key: string]: string;
3467
+ };
3468
+ }
3469
+ declare const StringMap: MessageFns$1<StringMap>;
3262
3470
  interface SystemErrorMessage {
3263
3471
  errorCode: SystemErrorCode;
3264
3472
  errorMessage: string;
@@ -3627,6 +3835,7 @@ interface VolumeMount {
3627
3835
  mountPath: string;
3628
3836
  allowBackgroundCommits: boolean;
3629
3837
  readOnly: boolean;
3838
+ subPath?: string | undefined;
3630
3839
  }
3631
3840
  declare const VolumeMount: MessageFns$1<VolumeMount>;
3632
3841
  interface VolumePutFiles2Request {
@@ -3792,6 +4001,23 @@ interface WorkspaceDashboardUrlResponse {
3792
4001
  url: string;
3793
4002
  }
3794
4003
  declare const WorkspaceDashboardUrlResponse: MessageFns$1<WorkspaceDashboardUrlResponse>;
4004
+ interface WorkspaceMembersListItem {
4005
+ memberId: string;
4006
+ memberDisplayname: string;
4007
+ memberRole: MemberRole;
4008
+ joinedAt: number;
4009
+ lastActiveAt: number;
4010
+ deletedAt: number;
4011
+ userId: string;
4012
+ identityProviderType: IdentityProviderType;
4013
+ email: string;
4014
+ avatarUrl: string;
4015
+ }
4016
+ declare const WorkspaceMembersListItem: MessageFns$1<WorkspaceMembersListItem>;
4017
+ interface WorkspaceMembersListResponse {
4018
+ members: WorkspaceMembersListItem[];
4019
+ }
4020
+ declare const WorkspaceMembersListResponse: MessageFns$1<WorkspaceMembersListResponse>;
3795
4021
  interface WorkspaceNameLookupResponse {
3796
4022
  /** @deprecated */
3797
4023
  workspaceName: string;
@@ -4293,6 +4519,31 @@ declare const ModalClientDefinition: {
4293
4519
  readonly responseStream: false;
4294
4520
  readonly options: {};
4295
4521
  };
4522
+ /** Endpoints */
4523
+ readonly endpointCreate: {
4524
+ readonly name: "EndpointCreate";
4525
+ readonly requestType: MessageFns$1<EndpointCreateRequest>;
4526
+ readonly requestStream: false;
4527
+ readonly responseType: MessageFns$1<EndpointCreateResponse>;
4528
+ readonly responseStream: false;
4529
+ readonly options: {};
4530
+ };
4531
+ readonly endpointList: {
4532
+ readonly name: "EndpointList";
4533
+ readonly requestType: MessageFns$1<EndpointListRequest>;
4534
+ readonly requestStream: false;
4535
+ readonly responseType: MessageFns$1<EndpointListResponse>;
4536
+ readonly responseStream: false;
4537
+ readonly options: {};
4538
+ };
4539
+ readonly endpointStop: {
4540
+ readonly name: "EndpointStop";
4541
+ readonly requestType: MessageFns$1<EndpointStopRequest>;
4542
+ readonly requestStream: false;
4543
+ readonly responseType: MessageFns$1<EndpointStopResponse>;
4544
+ readonly responseStream: false;
4545
+ readonly options: {};
4546
+ };
4296
4547
  /** Environments */
4297
4548
  readonly environmentCreate: {
4298
4549
  readonly name: "EnvironmentCreate";
@@ -4310,6 +4561,14 @@ declare const ModalClientDefinition: {
4310
4561
  readonly responseStream: false;
4311
4562
  readonly options: {};
4312
4563
  };
4564
+ readonly environmentGetManaged: {
4565
+ readonly name: "EnvironmentGetManaged";
4566
+ readonly requestType: MessageFns$1<EnvironmentGetManagedRequest>;
4567
+ readonly requestStream: false;
4568
+ readonly responseType: MessageFns$1<EnvironmentGetManagedResponse>;
4569
+ readonly responseStream: false;
4570
+ readonly options: {};
4571
+ };
4313
4572
  readonly environmentGetOrCreate: {
4314
4573
  readonly name: "EnvironmentGetOrCreate";
4315
4574
  readonly requestType: MessageFns$1<EnvironmentGetOrCreateRequest>;
@@ -4326,6 +4585,22 @@ declare const ModalClientDefinition: {
4326
4585
  readonly responseStream: false;
4327
4586
  readonly options: {};
4328
4587
  };
4588
+ readonly environmentRoleSet: {
4589
+ readonly name: "EnvironmentRoleSet";
4590
+ readonly requestType: MessageFns$1<EnvironmentRoleSetRequest>;
4591
+ readonly requestStream: false;
4592
+ readonly responseType: MessageFns$2<Empty>;
4593
+ readonly responseStream: false;
4594
+ readonly options: {};
4595
+ };
4596
+ readonly environmentSetManaged: {
4597
+ readonly name: "EnvironmentSetManaged";
4598
+ readonly requestType: MessageFns$1<EnvironmentSetManagedRequest>;
4599
+ readonly requestStream: false;
4600
+ readonly responseType: MessageFns$2<Empty>;
4601
+ readonly responseStream: false;
4602
+ readonly options: {};
4603
+ };
4329
4604
  readonly environmentUpdate: {
4330
4605
  readonly name: "EnvironmentUpdate";
4331
4606
  readonly requestType: MessageFns$1<EnvironmentUpdateRequest>;
@@ -5037,6 +5312,15 @@ declare const ModalClientDefinition: {
5037
5312
  readonly responseStream: false;
5038
5313
  readonly options: {};
5039
5314
  };
5315
+ /** Service users */
5316
+ readonly serviceUserList: {
5317
+ readonly name: "ServiceUserList";
5318
+ readonly requestType: MessageFns$2<Empty>;
5319
+ readonly requestStream: false;
5320
+ readonly responseType: MessageFns$1<ServiceUserListResponse>;
5321
+ readonly responseStream: false;
5322
+ readonly options: {};
5323
+ };
5040
5324
  /** SharedVolumes */
5041
5325
  readonly sharedVolumeDelete: {
5042
5326
  readonly name: "SharedVolumeDelete";
@@ -5372,6 +5656,14 @@ declare const ModalClientDefinition: {
5372
5656
  readonly responseStream: false;
5373
5657
  readonly options: {};
5374
5658
  };
5659
+ readonly workspaceMembersList: {
5660
+ readonly name: "WorkspaceMembersList";
5661
+ readonly requestType: MessageFns$2<Empty>;
5662
+ readonly requestStream: false;
5663
+ readonly responseType: MessageFns$1<WorkspaceMembersListResponse>;
5664
+ readonly responseStream: false;
5665
+ readonly options: {};
5666
+ };
5375
5667
  readonly workspaceNameLookup: {
5376
5668
  readonly name: "WorkspaceNameLookup";
5377
5669
  readonly requestType: MessageFns$2<Empty>;
@@ -5583,8 +5875,8 @@ declare class Function_ {
5583
5875
  getCurrentStats(): Promise<FunctionStats>;
5584
5876
  updateAutoscaler(params: FunctionUpdateAutoscalerParams): Promise<void>;
5585
5877
  /**
5586
- * URL of a Function running as a web endpoint.
5587
- * @returns The web URL if this Function is a web endpoint, otherwise undefined
5878
+ * URL for addressing the Web Function via HTTP.
5879
+ * @returns The web URL, or undefined if this is not a Web Function
5588
5880
  */
5589
5881
  getWebUrl(): Promise<string | undefined>;
5590
5882
  }
@@ -5654,20 +5946,45 @@ declare class VolumeService {
5654
5946
  */
5655
5947
  delete(name: string, params?: VolumeDeleteParams): Promise<void>;
5656
5948
  }
5949
+ /**
5950
+ * Resolved mount configuration stored on a Volume. `subPath: undefined` means "mount the
5951
+ * whole volume" (no sub-path set on the resulting VolumeMount proto).
5952
+ */
5953
+ type ResolvedMountOptions = {
5954
+ readOnly: boolean;
5955
+ subPath: string | undefined;
5956
+ };
5657
5957
  /** Volumes provide persistent storage that can be mounted in Modal {@link Function_ Function}s. */
5658
5958
  declare class Volume {
5659
5959
  #private;
5660
5960
  readonly volumeId: string;
5661
5961
  readonly name?: string;
5662
- private _readOnly;
5962
+ /**
5963
+ * @hidden
5964
+ * @internal
5965
+ */
5966
+ readonly _mountOptions: ResolvedMountOptions;
5663
5967
  /** @ignore */
5664
- constructor(volumeId: string, name?: string, readOnly?: boolean, ephemeralHbManager?: EphemeralHeartbeatManager);
5968
+ constructor(volumeId: string, name?: string, mountOptions?: ResolvedMountOptions, ephemeralHbManager?: EphemeralHeartbeatManager);
5665
5969
  /**
5666
5970
  * @deprecated Use {@link VolumeService#fromName client.volumes.fromName()} instead.
5667
5971
  */
5668
5972
  static fromName(name: string, options?: VolumeFromNameParams): Promise<Volume>;
5669
- /** Configure Volume to mount as read-only. */
5973
+ /**
5974
+ * Configure Volume to mount as read-only.
5975
+ *
5976
+ * @deprecated Use {@link withMountOptions} with `{ readOnly: true }` instead.
5977
+ */
5670
5978
  readOnly(): Volume;
5979
+ /**
5980
+ * Configure options used when mounting this Volume. Fields left undefined preserve their value
5981
+ * from any previous withMountOptions call on the same Volume (stacking).
5982
+ */
5983
+ withMountOptions(params?: VolumeMountOptions): Volume;
5984
+ /**
5985
+ * @deprecated Inspect mount configuration at the call site that configured it instead.
5986
+ * Future versions of this SDK may remove direct mount-option accessors on Volume.
5987
+ */
5671
5988
  get isReadOnly(): boolean;
5672
5989
  /**
5673
5990
  * @deprecated Use {@link VolumeService#ephemeral client.volumes.ephemeral()} instead.
@@ -5676,6 +5993,11 @@ declare class Volume {
5676
5993
  /** Delete the ephemeral Volume. Only usable with emphemeral Volumes. */
5677
5994
  closeEphemeral(): void;
5678
5995
  }
5996
+ /** Options for mounting a {@link Volume}. */
5997
+ type VolumeMountOptions = {
5998
+ readOnly?: boolean;
5999
+ subPath?: string;
6000
+ };
5679
6001
 
5680
6002
  /** Optional parameters for {@link ClsService#fromName client.cls.fromName()}. */
5681
6003
  type ClsFromNameParams = {
@@ -6147,12 +6469,53 @@ declare const TaskMountDirectoryRequest: MessageFns<TaskMountDirectoryRequest>;
6147
6469
  interface TaskSnapshotDirectoryRequest {
6148
6470
  taskId: string;
6149
6471
  path: Uint8Array;
6472
+ /** A unique ID to ensure idempotency of directory snapshot requests. */
6473
+ snapshotId: string;
6474
+ /**
6475
+ * Lifetime for the resulting image, in seconds. When set, the
6476
+ * image's expires_at is a hard cutoff: it is fixed at creation time
6477
+ * and is not extended on use.
6478
+ *
6479
+ * When unset, the resulting image gets the legacy retention policy:
6480
+ * a 30-day TTL that is bumped forward by 30 days on every use, so
6481
+ * active images effectively never expire.
6482
+ *
6483
+ * Sentinel: -1 means "no expiry" (the image never expires).
6484
+ * 0 and other negative values are invalid and rejected by the
6485
+ * server.
6486
+ */
6487
+ ttlSeconds?: number | undefined;
6150
6488
  }
6151
6489
  declare const TaskSnapshotDirectoryRequest: MessageFns<TaskSnapshotDirectoryRequest>;
6152
6490
  interface TaskSnapshotDirectoryResponse {
6153
6491
  imageId: string;
6154
6492
  }
6155
6493
  declare const TaskSnapshotDirectoryResponse: MessageFns<TaskSnapshotDirectoryResponse>;
6494
+ interface TaskSnapshotFilesystemRequest {
6495
+ taskId: string;
6496
+ /** A unique ID to ensure idempotency of filesystem snapshot requests. */
6497
+ snapshotId: string;
6498
+ /**
6499
+ * Lifetime for the resulting image, in seconds. Must be set. When positive,
6500
+ * the image expiry is a hard cutoff: it is fixed at creation time and is
6501
+ * not extended on use.
6502
+ *
6503
+ * Sentinel: -1 means "no expiry" (the image never expires).
6504
+ * 0 and other negative values are invalid and rejected by the
6505
+ * server.
6506
+ */
6507
+ ttlSeconds?: number | undefined;
6508
+ }
6509
+ declare const TaskSnapshotFilesystemRequest: MessageFns<TaskSnapshotFilesystemRequest>;
6510
+ interface TaskSnapshotFilesystemResponse {
6511
+ imageId: string;
6512
+ }
6513
+ declare const TaskSnapshotFilesystemResponse: MessageFns<TaskSnapshotFilesystemResponse>;
6514
+ interface TaskUnmountDirectoryRequest {
6515
+ taskId: string;
6516
+ path: Uint8Array;
6517
+ }
6518
+ declare const TaskUnmountDirectoryRequest: MessageFns<TaskUnmountDirectoryRequest>;
6156
6519
  type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
6157
6520
  type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
6158
6521
  [K in keyof T]?: DeepPartial<T[K]>;
@@ -6182,6 +6545,8 @@ interface Profile {
6182
6545
  environment?: string;
6183
6546
  imageBuilderVersion?: string;
6184
6547
  logLevel?: string;
6548
+ /** Parsed from MODAL_MAX_THROTTLE_WAIT. null means unlimited. */
6549
+ maxThrottleWaitSecs?: number;
6185
6550
  }
6186
6551
 
6187
6552
  /** @ignore */
@@ -6190,13 +6555,15 @@ declare class TaskCommandRouterClientImpl {
6190
6555
  private channel;
6191
6556
  private serverClient;
6192
6557
  private taskId;
6558
+ private sandboxId;
6559
+ private isV2;
6193
6560
  private serverUrl;
6194
6561
  private jwt;
6195
6562
  private jwtExp;
6196
6563
  private jwtRefreshLock;
6197
6564
  private logger;
6198
6565
  private closed;
6199
- static tryInit(serverClient: ModalGrpcClient, taskId: string, logger: Logger, profile: Profile): Promise<TaskCommandRouterClientImpl | null>;
6566
+ static tryInit(serverClient: ModalGrpcClient, taskId: string, sandboxId: string, isV2: boolean, logger: Logger, profile: Profile): Promise<TaskCommandRouterClientImpl | null>;
6200
6567
  private constructor();
6201
6568
  close(): void;
6202
6569
  execStart(request: TaskExecStartRequest): Promise<TaskExecStartResponse>;
@@ -6206,6 +6573,8 @@ declare class TaskCommandRouterClientImpl {
6206
6573
  execWait(taskId: string, execId: string, deadline?: number | null): Promise<TaskExecWaitResponse>;
6207
6574
  mountDirectory(request: TaskMountDirectoryRequest): Promise<void>;
6208
6575
  snapshotDirectory(request: TaskSnapshotDirectoryRequest): Promise<TaskSnapshotDirectoryResponse>;
6576
+ snapshotFilesystem(request: TaskSnapshotFilesystemRequest, options?: TimeoutOptions): Promise<TaskSnapshotFilesystemResponse>;
6577
+ unmountDirectory(request: TaskUnmountDirectoryRequest): Promise<void>;
6209
6578
  private refreshJwt;
6210
6579
  private callWithAuthRetry;
6211
6580
  private streamStdio;
@@ -6228,7 +6597,7 @@ declare class SandboxFile {
6228
6597
  read(): Promise<Uint8Array>;
6229
6598
  /**
6230
6599
  * Write data to the file.
6231
- * @param data - Data to write (string or Uint8Array)
6600
+ * @param data - Data to write
6232
6601
  */
6233
6602
  write(data: Uint8Array): Promise<void>;
6234
6603
  /**
@@ -6241,6 +6610,173 @@ declare class SandboxFile {
6241
6610
  close(): Promise<void>;
6242
6611
  }
6243
6612
 
6613
+ /** Type of a filesystem entry. */
6614
+ type FileType = "file" | "directory" | "symlink";
6615
+ /** Metadata for a file or directory entry in a Sandbox. */
6616
+ interface FileInfo {
6617
+ readonly name: string;
6618
+ readonly path: string;
6619
+ readonly type: FileType;
6620
+ readonly size: number;
6621
+ readonly mode: number;
6622
+ readonly permissions: string;
6623
+ readonly owner: string;
6624
+ readonly group: string;
6625
+ /** Unix epoch seconds. */
6626
+ readonly modifiedTime: number;
6627
+ readonly symlinkTarget: string | null;
6628
+ }
6629
+ /** Namespace for Sandbox filesystem APIs. */
6630
+ declare class SandboxFilesystem {
6631
+ private readonly sandbox;
6632
+ /** @ignore */
6633
+ constructor(sandbox: Sandbox);
6634
+ /**
6635
+ * Copy a local file into the Sandbox.
6636
+ *
6637
+ * `remotePath` must be an absolute path to a file in the Sandbox.
6638
+ * Parent directories are created if needed. The remote file is overwritten
6639
+ * if it already exists.
6640
+ *
6641
+ * @throws {SandboxFilesystemNotADirectoryError} a parent component of `remotePath` is not a directory.
6642
+ * @throws {SandboxFilesystemIsADirectoryError} `remotePath` points to a directory.
6643
+ * @throws {SandboxFilesystemPermissionError} write permission is denied in the Sandbox.
6644
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6645
+ * @throws {Error} `localPath` does not exist, is a directory, or cannot be read (`ENOENT`, `EISDIR`, `EACCES`).
6646
+ */
6647
+ copyFromLocal(localPath: string, remotePath: string): Promise<void>;
6648
+ /**
6649
+ * Copy a file from the Sandbox to a local path.
6650
+ *
6651
+ * `remotePath` must be an absolute path to a file in the Sandbox.
6652
+ * Parent directories for `localPath` are created if needed. The local file
6653
+ * is overwritten if it already exists.
6654
+ *
6655
+ * @throws {SandboxFilesystemNotFoundError} the remote path does not exist.
6656
+ * @throws {SandboxFilesystemIsADirectoryError} the remote path points to a directory.
6657
+ * @throws {SandboxFilesystemFileTooLargeError} the file exceeds the read size limit.
6658
+ * @throws {SandboxFilesystemPermissionError} read permission is denied in the Sandbox.
6659
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6660
+ * @throws {Error} `localPath` points to a directory, or writing it is not permitted.
6661
+ */
6662
+ copyToLocal(remotePath: string, localPath: string): Promise<void>;
6663
+ /**
6664
+ * List files and directories in a Sandbox directory.
6665
+ *
6666
+ * `remotePath` must be an absolute path to a directory in the Sandbox.
6667
+ * Returns an array of {@link FileInfo} objects sorted by name.
6668
+ *
6669
+ * @throws {SandboxFilesystemNotFoundError} the path does not exist.
6670
+ * @throws {SandboxFilesystemNotADirectoryError} the path is not a directory.
6671
+ * @throws {SandboxFilesystemPermissionError} read permission is denied.
6672
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6673
+ */
6674
+ listFiles(remotePath: string): Promise<FileInfo[]>;
6675
+ /**
6676
+ * Create a new directory in the Sandbox.
6677
+ *
6678
+ * `remotePath` must be an absolute path in the Sandbox.
6679
+ *
6680
+ * When `createParents` is `true` (the default), any missing parent
6681
+ * directories are created and the call is idempotent (succeeds if the
6682
+ * directory already exists). When `createParents` is `false`, the immediate
6683
+ * parent must already exist and the path must not already exist.
6684
+ *
6685
+ * @throws {SandboxFilesystemNotFoundError} the parent does not exist and `createParents` is `false`.
6686
+ * @throws {SandboxFilesystemPathAlreadyExistsError} the path already exists and `createParents` is `false`.
6687
+ * @throws {SandboxFilesystemNotADirectoryError} a path component is not a directory.
6688
+ * @throws {SandboxFilesystemPermissionError} creation is not permitted.
6689
+ * @throws {InvalidError} the operation is not supported by the mount.
6690
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6691
+ */
6692
+ makeDirectory(remotePath: string, options?: {
6693
+ createParents?: boolean;
6694
+ }): Promise<void>;
6695
+ /**
6696
+ * Read a file from the Sandbox and return its contents as bytes.
6697
+ *
6698
+ * `remotePath` must be an absolute path to a file in the Sandbox.
6699
+ *
6700
+ * @throws {SandboxFilesystemNotFoundError} the path does not exist.
6701
+ * @throws {SandboxFilesystemIsADirectoryError} the path points to a directory.
6702
+ * @throws {SandboxFilesystemFileTooLargeError} the file exceeds the read size limit.
6703
+ * @throws {SandboxFilesystemPermissionError} read permission is denied.
6704
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6705
+ */
6706
+ readBytes(remotePath: string): Promise<Uint8Array>;
6707
+ /**
6708
+ * Read a file from the Sandbox and return its contents as a UTF-8 string.
6709
+ *
6710
+ * `remotePath` must be an absolute path to a file in the Sandbox.
6711
+ *
6712
+ * @throws {SandboxFilesystemNotFoundError} the path does not exist.
6713
+ * @throws {SandboxFilesystemIsADirectoryError} the path points to a directory.
6714
+ * @throws {SandboxFilesystemFileTooLargeError} the file exceeds the read size limit.
6715
+ * @throws {SandboxFilesystemPermissionError} read permission is denied.
6716
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6717
+ */
6718
+ readText(remotePath: string): Promise<string>;
6719
+ /**
6720
+ * Remove a file or directory in the Sandbox.
6721
+ *
6722
+ * `remotePath` must be an absolute path in the Sandbox. When `remotePath`
6723
+ * is a directory and `recursive` is `false` (the default), it is removed
6724
+ * only if empty. When `recursive` is `true`, the directory and all its
6725
+ * contents are removed. Recursive removal is not supported on all mounts —
6726
+ * `CloudBucketMount` does not support it.
6727
+ *
6728
+ * @throws {SandboxFilesystemNotFoundError} the path does not exist.
6729
+ * @throws {SandboxFilesystemDirectoryNotEmptyError} `recursive` is `false` and the directory is not empty.
6730
+ * @throws {SandboxFilesystemPermissionError} removal is not permitted.
6731
+ * @throws {InvalidError} the operation is not supported by the mount.
6732
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6733
+ */
6734
+ remove(remotePath: string, options?: {
6735
+ recursive?: boolean;
6736
+ }): Promise<void>;
6737
+ /**
6738
+ * Return metadata for a single file, directory, or symlink in the Sandbox.
6739
+ *
6740
+ * `remotePath` must be an absolute path in the Sandbox. If `remotePath` is
6741
+ * a symlink, the returned {@link FileInfo} describes the symlink itself, not
6742
+ * the target it points to.
6743
+ *
6744
+ * @throws {SandboxFilesystemNotFoundError} the path does not exist.
6745
+ * @throws {SandboxFilesystemNotADirectoryError} a non-leaf component of the path is not a directory.
6746
+ * @throws {SandboxFilesystemPermissionError} a path component is not searchable.
6747
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6748
+ */
6749
+ stat(remotePath: string): Promise<FileInfo>;
6750
+ /**
6751
+ * Write binary content to a file in the Sandbox.
6752
+ *
6753
+ * `remotePath` must be an absolute path to a file in the Sandbox.
6754
+ * Parent directories are created if needed. The remote file is overwritten
6755
+ * if it already exists.
6756
+ *
6757
+ * @throws {TypeError} `data` is not a `Uint8Array`, `ArrayBuffer`, or `Buffer`.
6758
+ * @throws {SandboxFilesystemNotADirectoryError} a parent component of `remotePath` is not a directory.
6759
+ * @throws {SandboxFilesystemIsADirectoryError} `remotePath` points to a directory.
6760
+ * @throws {SandboxFilesystemPermissionError} write permission is denied.
6761
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6762
+ */
6763
+ writeBytes(data: Uint8Array | ArrayBuffer | Buffer, remotePath: string): Promise<void>;
6764
+ /**
6765
+ * Write UTF-8 text to a file in the Sandbox.
6766
+ *
6767
+ * `remotePath` must be an absolute path to a file in the Sandbox.
6768
+ * Parent directories are created if needed. The remote file is overwritten
6769
+ * if it already exists.
6770
+ *
6771
+ * @throws {TypeError} `data` is not a string.
6772
+ * @throws {SandboxFilesystemNotADirectoryError} a parent component of `remotePath` is not a directory.
6773
+ * @throws {SandboxFilesystemIsADirectoryError} `remotePath` points to a directory.
6774
+ * @throws {SandboxFilesystemPermissionError} write permission is denied.
6775
+ * @throws {SandboxFilesystemError} the command fails for any other reason.
6776
+ */
6777
+ writeText(data: string, remotePath: string): Promise<void>;
6778
+ }
6779
+
6244
6780
  /**
6245
6781
  * Wrapper around `ReadableStream` with convenience functions.
6246
6782
  *
@@ -6346,8 +6882,14 @@ type SandboxCreateParams = {
6346
6882
  unencryptedPorts?: number[];
6347
6883
  /** Whether to block all network access from the Sandbox. */
6348
6884
  blockNetwork?: boolean;
6349
- /** List of CIDRs the Sandbox is allowed to access. If None, all CIDRs are allowed. Cannot be used with blockNetwork. */
6885
+ /** List of CIDRs the Sandbox is allowed to access. If not set, all CIDRs are allowed. Cannot be used with blockNetwork. */
6886
+ outboundCidrAllowlist?: string[];
6887
+ /**
6888
+ * @deprecated Use {@link outboundCidrAllowlist} instead.
6889
+ */
6350
6890
  cidrAllowlist?: string[];
6891
+ /** List of CIDRs allowed to connect inbound to the Sandbox (tunnels and connection tokens). If not set, all IPs are allowed. Cannot be used with blockNetwork. */
6892
+ inboundCidrAllowlist?: string[];
6351
6893
  /** Cloud provider to run the Sandbox on. */
6352
6894
  cloud?: string;
6353
6895
  /** Region(s) to run the Sandbox on. */
@@ -6360,6 +6902,8 @@ type SandboxCreateParams = {
6360
6902
  readinessProbe?: Probe;
6361
6903
  /** Optional name for the Sandbox. Unique within an App. */
6362
6904
  name?: string;
6905
+ /** Tags to attach to the Sandbox. Filterable via {@link SandboxService#list Sandbox.list}. */
6906
+ tags?: Record<string, string>;
6363
6907
  /** Optional experimental options. */
6364
6908
  experimentalOptions?: Record<string, any>;
6365
6909
  /** If set, connections to this Sandbox will be subdomains of this domain rather than the default.
@@ -6385,6 +6929,24 @@ declare class SandboxService {
6385
6929
  * Create a new {@link Sandbox} in the {@link App} with the specified {@link Image} and options.
6386
6930
  */
6387
6931
  create(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
6932
+ /**
6933
+ * Create a new {@link Sandbox} using the experimental V2 backend.
6934
+ *
6935
+ * Supported features include exec, encrypted tunnels, wait/poll/terminate,
6936
+ * CPU and memory configuration, and region placement.
6937
+ *
6938
+ * Features like tags, filesystem snapshots, memory snapshots, volumes, cloud
6939
+ * bucket mounts, GPUs, custom domains, OIDC identity tokens, proxies, and
6940
+ * readiness probes are not supported.
6941
+ *
6942
+ * V2 sandboxes created with this method are not currently returned by
6943
+ * {@link SandboxService#list client.sandboxes.list()} and cannot be looked up
6944
+ * with {@link SandboxService#fromName client.sandboxes.fromName()}. Store
6945
+ * {@link Sandbox#sandboxId sandbox.sandboxId} if you need to retrieve the
6946
+ * sandbox later, and use {@link SandboxService#fromId client.sandboxes.fromId()}
6947
+ * to reattach.
6948
+ */
6949
+ experimentalCreate(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
6388
6950
  /** Returns a running {@link Sandbox} object from an ID.
6389
6951
  *
6390
6952
  * @returns Sandbox with ID
@@ -6474,10 +7036,15 @@ declare class Sandbox {
6474
7036
  #private;
6475
7037
  readonly sandboxId: string;
6476
7038
  /** @ignore */
6477
- constructor(client: ModalClient, sandboxId: string);
7039
+ constructor(client: ModalClient, sandboxId: string, params?: {
7040
+ isV2?: boolean;
7041
+ taskId?: string;
7042
+ tunnels?: Record<number, Tunnel>;
7043
+ });
6478
7044
  get stdin(): ModalWriteStream<string>;
6479
7045
  get stdout(): ModalReadStream<string>;
6480
7046
  get stderr(): ModalReadStream<string>;
7047
+ get filesystem(): SandboxFilesystem;
6481
7048
  /** Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in {@link SandboxService#list Sandbox.list}. */
6482
7049
  setTags(tags: Record<string, string>): Promise<void>;
6483
7050
  /** Get tags (key-value pairs) currently attached to this Sandbox from the server. */
@@ -6492,6 +7059,10 @@ declare class Sandbox {
6492
7059
  static fromName(appName: string, name: string, environment?: string): Promise<Sandbox>;
6493
7060
  /**
6494
7061
  * Open a file in the Sandbox filesystem.
7062
+ *
7063
+ * @deprecated Use {@link SandboxFilesystem} methods: `sandbox.filesystem.readBytes()`,
7064
+ * `writeBytes()`, or `copyToLocal()` instead for improved reliability.
7065
+ *
6495
7066
  * @param path - Path to the file to open
6496
7067
  * @param mode - File open mode (r, w, a, r+, w+, a+)
6497
7068
  * @returns Promise that resolves to a {@link SandboxFile}
@@ -6540,7 +7111,11 @@ declare class Sandbox {
6540
7111
  *
6541
7112
  * Returns an {@link Image} object which can be used to spawn a new Sandbox with the same filesystem.
6542
7113
  *
6543
- * @param timeoutMs - Timeout for the snapshot operation in milliseconds
7114
+ * `timeoutMs` is propagated as the gRPC deadline. If the snapshot does
7115
+ * not return within that window, the call is cancelled and an error is
7116
+ * thrown.
7117
+ *
7118
+ * @param timeoutMs - Timeout for the snapshot operation in milliseconds.
6544
7119
  * @returns Promise that resolves to an {@link Image}
6545
7120
  */
6546
7121
  snapshotFilesystem(timeoutMs?: number): Promise<Image>;
@@ -6551,9 +7126,18 @@ declare class Sandbox {
6551
7126
  * @param image - Optional {@link Image} to mount. If undefined, mounts an empty directory.
6552
7127
  */
6553
7128
  mountImage(path: string, image?: Image): Promise<void>;
7129
+ /**
7130
+ * Unmounts an {@link Image} previously mounted at a path in the Sandbox filesystem.
7131
+ *
7132
+ * @param path - The mount path to unmount
7133
+ */
7134
+ unmountImage(path: string): Promise<void>;
6554
7135
  /**
6555
7136
  * Snapshots and creates a new {@link Image} from a directory in the running sandbox.
6556
7137
  *
7138
+ * Directory snapshots are currently persisted for 30 days after they
7139
+ * were created.
7140
+ *
6557
7141
  * @param path - The path of the directory to snapshot
6558
7142
  * @returns Promise that resolves to an {@link Image}
6559
7143
  */
@@ -6576,6 +7160,13 @@ declare class ContainerProcess<R extends string | Uint8Array = any> {
6576
7160
  stderr: ModalReadStream<R>;
6577
7161
  /** @ignore */
6578
7162
  constructor(taskId: string, execId: string, commandRouterClient: TaskCommandRouterClientImpl, params?: SandboxExecParams, deadline?: number | null);
7163
+ /**
7164
+ * @ignore
7165
+ * Send stdin EOF directly, bypassing the WritableStream state machine.
7166
+ *
7167
+ * Useful for when an stdin write has failed.
7168
+ */
7169
+ closeStdin(): Promise<void>;
6579
7170
  /** Wait for process completion and return the exit code. */
6580
7171
  wait(): Promise<number>;
6581
7172
  }
@@ -6587,6 +7178,7 @@ interface ModalClientParams {
6587
7178
  endpoint?: string;
6588
7179
  timeoutMs?: number;
6589
7180
  maxRetries?: number;
7181
+ maxThrottleWaitSecs?: number;
6590
7182
  logger?: Logger;
6591
7183
  logLevel?: LogLevel;
6592
7184
  /**
@@ -6785,6 +7377,38 @@ declare class QueueEmptyError extends Error {
6785
7377
  declare class QueueFullError extends Error {
6786
7378
  constructor(message: string);
6787
7379
  }
7380
+ /** Errors from invalid Sandbox FileSystem operations. */
7381
+ declare class SandboxFilesystemError extends Error {
7382
+ constructor(message: string);
7383
+ }
7384
+ /** A directory was expected to be empty but is not. */
7385
+ declare class SandboxFilesystemDirectoryNotEmptyError extends SandboxFilesystemError {
7386
+ constructor(message: string);
7387
+ }
7388
+ /** A file exceeds the maximum allowed size for a read operation. */
7389
+ declare class SandboxFilesystemFileTooLargeError extends SandboxFilesystemError {
7390
+ constructor(message: string);
7391
+ }
7392
+ /** A file operation was attempted on a path that resolves to a directory. */
7393
+ declare class SandboxFilesystemIsADirectoryError extends SandboxFilesystemError {
7394
+ constructor(message: string);
7395
+ }
7396
+ /** A directory operation encountered a path component that is not a directory. */
7397
+ declare class SandboxFilesystemNotADirectoryError extends SandboxFilesystemError {
7398
+ constructor(message: string);
7399
+ }
7400
+ /** A file or directory is not found. */
7401
+ declare class SandboxFilesystemNotFoundError extends SandboxFilesystemError {
7402
+ constructor(message: string);
7403
+ }
7404
+ /** A path already exists and the operation requires it to be absent. */
7405
+ declare class SandboxFilesystemPathAlreadyExistsError extends SandboxFilesystemError {
7406
+ constructor(message: string);
7407
+ }
7408
+ /** Permission is denied for a file operation. */
7409
+ declare class SandboxFilesystemPermissionError extends SandboxFilesystemError {
7410
+ constructor(message: string);
7411
+ }
6788
7412
  /** Sandbox operations that exceed the allowed time limit. */
6789
7413
  declare class SandboxTimeoutError extends Error {
6790
7414
  constructor(message?: string);
@@ -6796,4 +7420,4 @@ declare class ClientClosedError extends Error {
6796
7420
 
6797
7421
  declare function checkForRenamedParams(params: any, renames: Record<string, string>): void;
6798
7422
 
6799
- export { AlreadyExistsError, App, type AppFromNameParams, AppService, ClientClosedError, type ClientOptions, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ContainerProcess, type DeleteOptions, type EphemeralOptions, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, FunctionCallService, type FunctionFromNameParams, FunctionService, type FunctionStats, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, ImageService, InternalFailure, InvalidError, type LogLevel, type Logger, type LookupOptions, 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, SandboxFile, type SandboxFileMode, type SandboxFromNameParams, type SandboxListParams, SandboxService, type SandboxTerminateParams, SandboxTimeoutError, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, VolumeService, checkForRenamedParams, close, initializeClient };
7423
+ export { AlreadyExistsError, App, type AppFromNameParams, AppService, ClientClosedError, type ClientOptions, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ContainerProcess, type DeleteOptions, type EphemeralOptions, type FileInfo, type FileType, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, FunctionCallService, type FunctionFromNameParams, FunctionService, type FunctionStats, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, ImageService, InternalFailure, InvalidError, type LogLevel, type Logger, type LookupOptions, 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, SandboxFile, type SandboxFileMode, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, SandboxService, type SandboxTerminateParams, SandboxTimeoutError, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptions, VolumeService, checkForRenamedParams, close, initializeClient };