tensorlake 0.5.30 → 0.5.33

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
@@ -24,7 +24,8 @@ declare enum SandboxStatus {
24
24
  SNAPSHOTTING = "snapshotting",
25
25
  SUSPENDING = "suspending",
26
26
  SUSPENDED = "suspended",
27
- TERMINATED = "terminated"
27
+ TERMINATED = "terminated",
28
+ TIMEOUT = "timeout"
28
29
  }
29
30
  declare enum SnapshotStatus {
30
31
  IN_PROGRESS = "in_progress",
@@ -87,7 +88,6 @@ interface CreateSandboxOptions {
87
88
  memoryMb?: number;
88
89
  /** Root disk size in megabytes. When omitted, the server uses its default disk size. */
89
90
  diskMb?: number;
90
- secretNames?: string[];
91
91
  timeoutSecs?: number;
92
92
  entrypoint?: string[];
93
93
  allowInternetAccess?: boolean;
@@ -108,12 +108,34 @@ interface UpdateSandboxOptions {
108
108
  interface CreateSandboxResponse {
109
109
  sandboxId: string;
110
110
  status: SandboxStatus;
111
+ reason?: string;
111
112
  routingHint?: string;
112
113
  ingressEndpoint?: string;
113
114
  name?: string | null;
114
115
  terminationReason?: string;
115
116
  errorDetails?: unknown;
116
117
  }
118
+ interface CopySandboxOptions {
119
+ /** Number of running copies to create. Defaults to 1. */
120
+ times?: number;
121
+ /** Per-request timeout in seconds for the blocking live-copy request. */
122
+ requestTimeout?: number;
123
+ }
124
+ interface CopiedSandboxResponse {
125
+ sandboxId: string;
126
+ /** Raw server status. Partial copy responses can include statuses such as `"failed"`. */
127
+ status: string;
128
+ reason?: string;
129
+ routingHint?: string;
130
+ ingressEndpoint?: string;
131
+ name?: string | null;
132
+ terminationReason?: string;
133
+ errorDetails?: unknown;
134
+ }
135
+ interface CopySandboxResponse {
136
+ sourceSandboxId: string;
137
+ sandboxes: CopiedSandboxResponse[];
138
+ }
117
139
  interface SandboxInfo {
118
140
  sandboxId: string;
119
141
  namespace: string;
@@ -121,7 +143,6 @@ interface SandboxInfo {
121
143
  /** Resolved sandbox image name. */
122
144
  image?: string;
123
145
  resources: ContainerResourcesInfo;
124
- secretNames: string[];
125
146
  timeoutSecs?: number;
126
147
  entrypoint?: string[];
127
148
  network?: NetworkConfig;
@@ -199,7 +220,6 @@ interface CreatePoolOptions {
199
220
  cpus?: number;
200
221
  memoryMb?: number;
201
222
  ephemeralDiskMb?: number;
202
- secretNames?: string[];
203
223
  timeoutSecs?: number;
204
224
  entrypoint?: string[];
205
225
  maxContainers?: number;
@@ -211,7 +231,6 @@ interface UpdatePoolOptions {
211
231
  cpus?: number;
212
232
  memoryMb?: number;
213
233
  ephemeralDiskMb?: number;
214
- secretNames?: string[];
215
234
  timeoutSecs?: number;
216
235
  entrypoint?: string[];
217
236
  maxContainers?: number;
@@ -233,7 +252,6 @@ interface SandboxPoolInfo {
233
252
  /** Sandbox image name backing the pool. */
234
253
  image: string;
235
254
  resources: ContainerResourcesInfo;
236
- secretNames: string[];
237
255
  timeoutSecs: number;
238
256
  entrypoint?: string[];
239
257
  maxContainers?: number;
@@ -332,6 +350,10 @@ interface SandboxClientOptions {
332
350
  namespace?: string;
333
351
  maxRetries?: number;
334
352
  retryBackoffMs?: number;
353
+ /** Total HTTP request timeout in seconds. Default: 300. */
354
+ requestTimeout?: number;
355
+ /** @deprecated Use requestTimeout. Total HTTP request timeout in milliseconds. */
356
+ timeoutMs?: number;
335
357
  }
336
358
  interface SandboxOptions {
337
359
  sandboxId: string;
@@ -343,10 +365,17 @@ interface SandboxOptions {
343
365
  resolveProxyInfo?: (identifier: string) => Promise<SandboxInfo & {
344
366
  readonly traceId: string;
345
367
  }>;
368
+ /** Optional total HTTP request timeout in seconds for sandbox proxy operations. Omit for no total proxy timeout. */
369
+ requestTimeout?: number;
370
+ /** @deprecated Use requestTimeout. Optional total HTTP request timeout in milliseconds for sandbox proxy operations. */
371
+ timeoutMs?: number;
346
372
  }
347
373
  interface CreateAndConnectOptions extends CreateSandboxOptions {
348
374
  poolId?: string;
349
375
  proxyUrl?: string;
376
+ /** Total HTTP request timeout in seconds for sandbox startup. Default: client requestTimeout. */
377
+ requestTimeout?: number;
378
+ /** @deprecated Use requestTimeout. */
350
379
  startupTimeout?: number;
351
380
  }
352
381
  interface SuspendResumeOptions {
@@ -587,6 +616,8 @@ declare class Sandbox {
587
616
  * `{ wait: false }` for fire-and-return.
588
617
  */
589
618
  resume(options?: SuspendResumeOptions): Promise<void>;
619
+ /** Live-copy this running sandbox. */
620
+ copy(options?: CopySandboxOptions): Promise<Traced<CopySandboxResponse>>;
590
621
  /**
591
622
  * Create a checkpoint of this sandbox and wait for it to be locally ready.
592
623
  *
@@ -694,6 +725,9 @@ declare class SandboxClient {
694
725
  private readonly projectId;
695
726
  private readonly namespace;
696
727
  private readonly local;
728
+ private readonly maxRetries;
729
+ private readonly retryBackoffMs;
730
+ private readonly requestTimeoutMs;
697
731
  /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
698
732
  constructor(options?: SandboxClientOptions, _internal?: boolean);
699
733
  /** Create a client for the TensorLake cloud platform. */
@@ -702,13 +736,18 @@ declare class SandboxClient {
702
736
  organizationId?: string;
703
737
  projectId?: string;
704
738
  apiUrl?: string;
739
+ requestTimeout?: number;
740
+ timeoutMs?: number;
705
741
  }): SandboxClient;
706
742
  /** Create a client for a local Indexify server. */
707
743
  static forLocalhost(options?: {
708
744
  apiUrl?: string;
709
745
  namespace?: string;
746
+ requestTimeout?: number;
747
+ timeoutMs?: number;
710
748
  }): SandboxClient;
711
749
  close(): void;
750
+ private withRequestTimeout;
712
751
  private path;
713
752
  /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
714
753
  create(options?: CreateSandboxOptions): Promise<Traced<CreateSandboxResponse>>;
@@ -768,6 +807,14 @@ declare class SandboxClient {
768
807
  resume(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
769
808
  /** Claim a warm sandbox from a pool, creating one if no warm containers are available. */
770
809
  claim(poolId: string): Promise<Traced<CreateSandboxResponse>>;
810
+ /**
811
+ * Live-copy a running sandbox.
812
+ *
813
+ * The server creates `times` running copies from the source sandbox. Partial
814
+ * responses can include failed copies; inspect each returned sandbox's
815
+ * `status` and `reason`.
816
+ */
817
+ copy(sandboxId: string, options?: CopySandboxOptions): Promise<Traced<CopySandboxResponse>>;
771
818
  /**
772
819
  * Request a snapshot of a running sandbox's filesystem.
773
820
  *
@@ -813,14 +860,15 @@ declare class SandboxClient {
813
860
  /** Delete a sandbox pool. Fails if the pool has active containers. */
814
861
  deletePool(poolId: string): Promise<void>;
815
862
  /** Return a `Sandbox` handle for an existing running sandbox without verifying it exists. */
816
- connect(identifier: string, proxyUrl?: string, routingHint?: string): Sandbox;
863
+ connect(identifier: string, proxyUrl?: string, routingHint?: string, requestTimeout?: number): Sandbox;
817
864
  /**
818
865
  * Create a sandbox, wait for it to reach `Running`, and return a connected handle.
819
866
  *
820
- * Blocks until the sandbox is ready or `startupTimeout` elapses. The returned
867
+ * Blocks until the sandbox is ready or `requestTimeout` elapses. The returned
821
868
  * `Sandbox` auto-terminates when `terminate()` is called.
822
869
  *
823
- * @param options.startupTimeout - Max seconds to wait for `Running` status (default 60).
870
+ * @param options.requestTimeout - Max seconds to wait for `Running` status (default: client requestTimeout).
871
+ * @param options.startupTimeout - Deprecated alias for `requestTimeout`.
824
872
  * @throws {SandboxError} If the sandbox terminates during startup or the timeout elapses.
825
873
  */
826
874
  createAndConnect(options?: CreateAndConnectOptions): Promise<Sandbox>;
@@ -1040,9 +1088,21 @@ declare class SandboxException extends Error {
1040
1088
  declare class SandboxError extends SandboxException {
1041
1089
  constructor(message: string);
1042
1090
  }
1043
- /** Raised when the client cannot connect to the API server. */
1091
+ /**
1092
+ * Raised when the client cannot complete a request against the API server.
1093
+ *
1094
+ * The original transport error (typically undici's `TypeError: fetch failed`,
1095
+ * whose real reason — `ECONNREFUSED`, `UND_ERR_CONNECT_TIMEOUT`, `EMFILE`, … —
1096
+ * lives in `.cause`) is preserved on this error's {@link cause} for programmatic
1097
+ * inspection, and its full chain is folded into the message so it survives
1098
+ * wrappers that only forward `error.message`. No interpretation of the failure
1099
+ * (client vs server) is applied — the raw inner error is surfaced as-is so the
1100
+ * reader can judge.
1101
+ */
1044
1102
  declare class SandboxConnectionError extends SandboxError {
1045
- constructor(message: string);
1103
+ constructor(message: string, options?: {
1104
+ cause?: unknown;
1105
+ });
1046
1106
  }
1047
1107
  /** Raised when a sandbox is not found. */
1048
1108
  declare class SandboxNotFoundError extends SandboxError {
@@ -1080,4 +1140,4 @@ declare class RequestExecutionError extends Error {
1080
1140
  constructor(message: string, functionName?: string);
1081
1141
  }
1082
1142
 
1083
- export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse, sandboxUrlFromIngressEndpoint };
1143
+ export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse, sandboxUrlFromIngressEndpoint };
package/dist/index.d.ts CHANGED
@@ -24,7 +24,8 @@ declare enum SandboxStatus {
24
24
  SNAPSHOTTING = "snapshotting",
25
25
  SUSPENDING = "suspending",
26
26
  SUSPENDED = "suspended",
27
- TERMINATED = "terminated"
27
+ TERMINATED = "terminated",
28
+ TIMEOUT = "timeout"
28
29
  }
29
30
  declare enum SnapshotStatus {
30
31
  IN_PROGRESS = "in_progress",
@@ -87,7 +88,6 @@ interface CreateSandboxOptions {
87
88
  memoryMb?: number;
88
89
  /** Root disk size in megabytes. When omitted, the server uses its default disk size. */
89
90
  diskMb?: number;
90
- secretNames?: string[];
91
91
  timeoutSecs?: number;
92
92
  entrypoint?: string[];
93
93
  allowInternetAccess?: boolean;
@@ -108,12 +108,34 @@ interface UpdateSandboxOptions {
108
108
  interface CreateSandboxResponse {
109
109
  sandboxId: string;
110
110
  status: SandboxStatus;
111
+ reason?: string;
111
112
  routingHint?: string;
112
113
  ingressEndpoint?: string;
113
114
  name?: string | null;
114
115
  terminationReason?: string;
115
116
  errorDetails?: unknown;
116
117
  }
118
+ interface CopySandboxOptions {
119
+ /** Number of running copies to create. Defaults to 1. */
120
+ times?: number;
121
+ /** Per-request timeout in seconds for the blocking live-copy request. */
122
+ requestTimeout?: number;
123
+ }
124
+ interface CopiedSandboxResponse {
125
+ sandboxId: string;
126
+ /** Raw server status. Partial copy responses can include statuses such as `"failed"`. */
127
+ status: string;
128
+ reason?: string;
129
+ routingHint?: string;
130
+ ingressEndpoint?: string;
131
+ name?: string | null;
132
+ terminationReason?: string;
133
+ errorDetails?: unknown;
134
+ }
135
+ interface CopySandboxResponse {
136
+ sourceSandboxId: string;
137
+ sandboxes: CopiedSandboxResponse[];
138
+ }
117
139
  interface SandboxInfo {
118
140
  sandboxId: string;
119
141
  namespace: string;
@@ -121,7 +143,6 @@ interface SandboxInfo {
121
143
  /** Resolved sandbox image name. */
122
144
  image?: string;
123
145
  resources: ContainerResourcesInfo;
124
- secretNames: string[];
125
146
  timeoutSecs?: number;
126
147
  entrypoint?: string[];
127
148
  network?: NetworkConfig;
@@ -199,7 +220,6 @@ interface CreatePoolOptions {
199
220
  cpus?: number;
200
221
  memoryMb?: number;
201
222
  ephemeralDiskMb?: number;
202
- secretNames?: string[];
203
223
  timeoutSecs?: number;
204
224
  entrypoint?: string[];
205
225
  maxContainers?: number;
@@ -211,7 +231,6 @@ interface UpdatePoolOptions {
211
231
  cpus?: number;
212
232
  memoryMb?: number;
213
233
  ephemeralDiskMb?: number;
214
- secretNames?: string[];
215
234
  timeoutSecs?: number;
216
235
  entrypoint?: string[];
217
236
  maxContainers?: number;
@@ -233,7 +252,6 @@ interface SandboxPoolInfo {
233
252
  /** Sandbox image name backing the pool. */
234
253
  image: string;
235
254
  resources: ContainerResourcesInfo;
236
- secretNames: string[];
237
255
  timeoutSecs: number;
238
256
  entrypoint?: string[];
239
257
  maxContainers?: number;
@@ -332,6 +350,10 @@ interface SandboxClientOptions {
332
350
  namespace?: string;
333
351
  maxRetries?: number;
334
352
  retryBackoffMs?: number;
353
+ /** Total HTTP request timeout in seconds. Default: 300. */
354
+ requestTimeout?: number;
355
+ /** @deprecated Use requestTimeout. Total HTTP request timeout in milliseconds. */
356
+ timeoutMs?: number;
335
357
  }
336
358
  interface SandboxOptions {
337
359
  sandboxId: string;
@@ -343,10 +365,17 @@ interface SandboxOptions {
343
365
  resolveProxyInfo?: (identifier: string) => Promise<SandboxInfo & {
344
366
  readonly traceId: string;
345
367
  }>;
368
+ /** Optional total HTTP request timeout in seconds for sandbox proxy operations. Omit for no total proxy timeout. */
369
+ requestTimeout?: number;
370
+ /** @deprecated Use requestTimeout. Optional total HTTP request timeout in milliseconds for sandbox proxy operations. */
371
+ timeoutMs?: number;
346
372
  }
347
373
  interface CreateAndConnectOptions extends CreateSandboxOptions {
348
374
  poolId?: string;
349
375
  proxyUrl?: string;
376
+ /** Total HTTP request timeout in seconds for sandbox startup. Default: client requestTimeout. */
377
+ requestTimeout?: number;
378
+ /** @deprecated Use requestTimeout. */
350
379
  startupTimeout?: number;
351
380
  }
352
381
  interface SuspendResumeOptions {
@@ -587,6 +616,8 @@ declare class Sandbox {
587
616
  * `{ wait: false }` for fire-and-return.
588
617
  */
589
618
  resume(options?: SuspendResumeOptions): Promise<void>;
619
+ /** Live-copy this running sandbox. */
620
+ copy(options?: CopySandboxOptions): Promise<Traced<CopySandboxResponse>>;
590
621
  /**
591
622
  * Create a checkpoint of this sandbox and wait for it to be locally ready.
592
623
  *
@@ -694,6 +725,9 @@ declare class SandboxClient {
694
725
  private readonly projectId;
695
726
  private readonly namespace;
696
727
  private readonly local;
728
+ private readonly maxRetries;
729
+ private readonly retryBackoffMs;
730
+ private readonly requestTimeoutMs;
697
731
  /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
698
732
  constructor(options?: SandboxClientOptions, _internal?: boolean);
699
733
  /** Create a client for the TensorLake cloud platform. */
@@ -702,13 +736,18 @@ declare class SandboxClient {
702
736
  organizationId?: string;
703
737
  projectId?: string;
704
738
  apiUrl?: string;
739
+ requestTimeout?: number;
740
+ timeoutMs?: number;
705
741
  }): SandboxClient;
706
742
  /** Create a client for a local Indexify server. */
707
743
  static forLocalhost(options?: {
708
744
  apiUrl?: string;
709
745
  namespace?: string;
746
+ requestTimeout?: number;
747
+ timeoutMs?: number;
710
748
  }): SandboxClient;
711
749
  close(): void;
750
+ private withRequestTimeout;
712
751
  private path;
713
752
  /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
714
753
  create(options?: CreateSandboxOptions): Promise<Traced<CreateSandboxResponse>>;
@@ -768,6 +807,14 @@ declare class SandboxClient {
768
807
  resume(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
769
808
  /** Claim a warm sandbox from a pool, creating one if no warm containers are available. */
770
809
  claim(poolId: string): Promise<Traced<CreateSandboxResponse>>;
810
+ /**
811
+ * Live-copy a running sandbox.
812
+ *
813
+ * The server creates `times` running copies from the source sandbox. Partial
814
+ * responses can include failed copies; inspect each returned sandbox's
815
+ * `status` and `reason`.
816
+ */
817
+ copy(sandboxId: string, options?: CopySandboxOptions): Promise<Traced<CopySandboxResponse>>;
771
818
  /**
772
819
  * Request a snapshot of a running sandbox's filesystem.
773
820
  *
@@ -813,14 +860,15 @@ declare class SandboxClient {
813
860
  /** Delete a sandbox pool. Fails if the pool has active containers. */
814
861
  deletePool(poolId: string): Promise<void>;
815
862
  /** Return a `Sandbox` handle for an existing running sandbox without verifying it exists. */
816
- connect(identifier: string, proxyUrl?: string, routingHint?: string): Sandbox;
863
+ connect(identifier: string, proxyUrl?: string, routingHint?: string, requestTimeout?: number): Sandbox;
817
864
  /**
818
865
  * Create a sandbox, wait for it to reach `Running`, and return a connected handle.
819
866
  *
820
- * Blocks until the sandbox is ready or `startupTimeout` elapses. The returned
867
+ * Blocks until the sandbox is ready or `requestTimeout` elapses. The returned
821
868
  * `Sandbox` auto-terminates when `terminate()` is called.
822
869
  *
823
- * @param options.startupTimeout - Max seconds to wait for `Running` status (default 60).
870
+ * @param options.requestTimeout - Max seconds to wait for `Running` status (default: client requestTimeout).
871
+ * @param options.startupTimeout - Deprecated alias for `requestTimeout`.
824
872
  * @throws {SandboxError} If the sandbox terminates during startup or the timeout elapses.
825
873
  */
826
874
  createAndConnect(options?: CreateAndConnectOptions): Promise<Sandbox>;
@@ -1040,9 +1088,21 @@ declare class SandboxException extends Error {
1040
1088
  declare class SandboxError extends SandboxException {
1041
1089
  constructor(message: string);
1042
1090
  }
1043
- /** Raised when the client cannot connect to the API server. */
1091
+ /**
1092
+ * Raised when the client cannot complete a request against the API server.
1093
+ *
1094
+ * The original transport error (typically undici's `TypeError: fetch failed`,
1095
+ * whose real reason — `ECONNREFUSED`, `UND_ERR_CONNECT_TIMEOUT`, `EMFILE`, … —
1096
+ * lives in `.cause`) is preserved on this error's {@link cause} for programmatic
1097
+ * inspection, and its full chain is folded into the message so it survives
1098
+ * wrappers that only forward `error.message`. No interpretation of the failure
1099
+ * (client vs server) is applied — the raw inner error is surfaced as-is so the
1100
+ * reader can judge.
1101
+ */
1044
1102
  declare class SandboxConnectionError extends SandboxError {
1045
- constructor(message: string);
1103
+ constructor(message: string, options?: {
1104
+ cause?: unknown;
1105
+ });
1046
1106
  }
1047
1107
  /** Raised when a sandbox is not found. */
1048
1108
  declare class SandboxNotFoundError extends SandboxError {
@@ -1080,4 +1140,4 @@ declare class RequestExecutionError extends Error {
1080
1140
  constructor(message: string, functionName?: string);
1081
1141
  }
1082
1142
 
1083
- export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse, sandboxUrlFromIngressEndpoint };
1143
+ export { APIClient, type ApiKeyIntrospection, type ApplicationBuildContext, type ApplicationBuildImageResult, type ApplicationBuildResponse, type ApplicationManifest, type ApplicationSummary, type ArchivedSandboxInfo, type BinaryPayload, type BuildInfo, type BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, type CloudClientOptions, type CommandResult, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, type CreateApplicationBuildImageRequest, type CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type MouseButton, type NetworkConfig, type NewSecret, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, RemoteAPIError, type RequestErrorInfo, RequestExecutionError, RequestFailedError, type RequestInput, type RequestMetadata, RequestNotFinishedError, type RequestOutput, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, SandboxStatus, type Secret, type SecretsList, type SecretsPagination, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, type StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpsertSecretResponse, sandboxUrlFromIngressEndpoint };