tensorlake 0.5.29 → 0.5.31

package/dist/index.d.cts

@@ -24,7 +24,8 @@ declare enum SandboxStatus {
     SNAPSHOTTING = "snapshotting",
     SUSPENDING = "suspending",
     SUSPENDED = "suspended",
-    TERMINATED = "terminated"
+    TERMINATED = "terminated",
+    TIMEOUT = "timeout"
 }
 declare enum SnapshotStatus {
     IN_PROGRESS = "in_progress",
@@ -109,6 +110,7 @@ interface CreateSandboxResponse {
     sandboxId: string;
     status: SandboxStatus;
     routingHint?: string;
+    ingressEndpoint?: string;
     name?: string | null;
     terminationReason?: string;
     errorDetails?: unknown;
@@ -133,12 +135,14 @@ interface SandboxInfo {
     name?: string;
     allowUnauthenticatedAccess?: boolean;
     exposedPorts?: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
     routingHint?: string;
 }
 interface SandboxPortAccess {
     allowUnauthenticatedAccess: boolean;
     exposedPorts: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
 }
 /** Sandbox information plus the archival timestamp. */
@@ -329,6 +333,10 @@ interface SandboxClientOptions {
     namespace?: string;
     maxRetries?: number;
     retryBackoffMs?: number;
+    /** Total HTTP request timeout in seconds. Default: 300. */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. Total HTTP request timeout in milliseconds. */
+    timeoutMs?: number;
 }
 interface SandboxOptions {
     sandboxId: string;
@@ -337,10 +345,20 @@ interface SandboxOptions {
     organizationId?: string;
     projectId?: string;
     routingHint?: string;
+    resolveProxyInfo?: (identifier: string) => Promise<SandboxInfo & {
+        readonly traceId: string;
+    }>;
+    /** Optional total HTTP request timeout in seconds for sandbox proxy operations. Omit for no total proxy timeout. */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. Optional total HTTP request timeout in milliseconds for sandbox proxy operations. */
+    timeoutMs?: number;
 }
 interface CreateAndConnectOptions extends CreateSandboxOptions {
     poolId?: string;
     proxyUrl?: string;
+    /** Total HTTP request timeout in seconds for sandbox startup. Default: client requestTimeout. */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. */
     startupTimeout?: number;
 }
 interface SuspendResumeOptions {
@@ -509,19 +527,22 @@ declare class Pty {
 declare class Sandbox {
     readonly sandboxId: string;
     traceId: string | null;
+    private readonly proxy;
     private readonly http;
-    private readonly baseUrl;
-    private readonly wsHeaders;
     private ownsSandbox;
     private lifecycleClient;
     private lifecycleIdentifier;
     private sandboxName;
     constructor(options: SandboxOptions);
+    private get baseUrl();
+    private get wsHeaders();
     get name(): string | null;
     /** @internal Used by client wiring to keep locally cached name in sync. */
     _setName(name: string | null): void;
     /** @internal Used by lifecycle operations to pin to canonical sandbox ID. */
     _setLifecycleIdentifier(identifier: string): void;
+    /** @internal Used by the lazy proxy resolver. */
+    _getLifecycleIdentifier(): string;
     /** @internal Used by SandboxClient.createAndConnect to set ownership. */
     _setOwner(client: SandboxClient): void;
     /**
@@ -534,9 +555,9 @@ declare class Sandbox {
     /**
      * Attach to an existing sandbox and return a connected handle.
      *
-     * Returns immediately without contacting the server. Call `sandbox.info()`
-     * to fetch the current state on demand. Does **not** auto-resume a suspended
-     * sandbox — call `sandbox.resume()` explicitly.
+     * When `proxyUrl` is omitted, resolves the sandbox first so the handle uses
+     * the correct cloud/region ingress endpoint. Does **not** auto-resume a
+     * suspended sandbox — call `sandbox.resume()` explicitly.
      */
     static connect(options: ConnectOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
     /** Get information about a snapshot by ID. No sandbox handle needed. */
@@ -685,6 +706,9 @@ declare class SandboxClient {
     private readonly projectId;
     private readonly namespace;
     private readonly local;
+    private readonly maxRetries;
+    private readonly retryBackoffMs;
+    private readonly requestTimeoutMs;
     /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
     constructor(options?: SandboxClientOptions, _internal?: boolean);
     /** Create a client for the TensorLake cloud platform. */
@@ -693,13 +717,18 @@ declare class SandboxClient {
         organizationId?: string;
         projectId?: string;
         apiUrl?: string;
+        requestTimeout?: number;
+        timeoutMs?: number;
     }): SandboxClient;
     /** Create a client for a local Indexify server. */
     static forLocalhost(options?: {
         apiUrl?: string;
         namespace?: string;
+        requestTimeout?: number;
+        timeoutMs?: number;
     }): SandboxClient;
     close(): void;
+    private withRequestTimeout;
     private path;
     /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
     create(options?: CreateSandboxOptions): Promise<Traced<CreateSandboxResponse>>;
@@ -804,14 +833,15 @@ declare class SandboxClient {
     /** Delete a sandbox pool. Fails if the pool has active containers. */
     deletePool(poolId: string): Promise<void>;
     /** Return a `Sandbox` handle for an existing running sandbox without verifying it exists. */
-    connect(identifier: string, proxyUrl?: string, routingHint?: string): Sandbox;
+    connect(identifier: string, proxyUrl?: string, routingHint?: string, requestTimeout?: number): Sandbox;
     /**
      * Create a sandbox, wait for it to reach `Running`, and return a connected handle.
      *
-     * Blocks until the sandbox is ready or `startupTimeout` elapses. The returned
+     * Blocks until the sandbox is ready or `requestTimeout` elapses. The returned
      * `Sandbox` auto-terminates when `terminate()` is called.
      *
-     * @param options.startupTimeout - Max seconds to wait for `Running` status (default 60).
+     * @param options.requestTimeout - Max seconds to wait for `Running` status (default: client requestTimeout).
+     * @param options.startupTimeout - Deprecated alias for `requestTimeout`.
      * @throws {SandboxError} If the sandbox terminates during startup or the timeout elapses.
      */
     createAndConnect(options?: CreateAndConnectOptions): Promise<Sandbox>;
@@ -1014,6 +1044,15 @@ declare class APIClient {
     requestOutput(applicationName: string, requestId: string): Promise<RequestOutput>;
 }
 
+/**
+ * Build a public sandbox URL from a server-provided ingress endpoint.
+ *
+ * `port` omitted or `9501` returns the management URL:
+ * `https://<sandbox-id>.<ingress-host>`. User ports use the public
+ * `<port>-<sandbox-id>.<ingress-host>` form.
+ */
+declare function sandboxUrlFromIngressEndpoint(ingressEndpoint: string, sandboxId: string, port?: number): string;
+
 /** Base exception for all sandbox-related errors. */
 declare class SandboxException extends Error {
     constructor(message: string);
@@ -1062,4 +1101,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-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 };
+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 };

package/dist/index.d.ts

@@ -24,7 +24,8 @@ declare enum SandboxStatus {
     SNAPSHOTTING = "snapshotting",
     SUSPENDING = "suspending",
     SUSPENDED = "suspended",
-    TERMINATED = "terminated"
+    TERMINATED = "terminated",
+    TIMEOUT = "timeout"
 }
 declare enum SnapshotStatus {
     IN_PROGRESS = "in_progress",
@@ -109,6 +110,7 @@ interface CreateSandboxResponse {
     sandboxId: string;
     status: SandboxStatus;
     routingHint?: string;
+    ingressEndpoint?: string;
     name?: string | null;
     terminationReason?: string;
     errorDetails?: unknown;
@@ -133,12 +135,14 @@ interface SandboxInfo {
     name?: string;
     allowUnauthenticatedAccess?: boolean;
     exposedPorts?: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
     routingHint?: string;
 }
 interface SandboxPortAccess {
     allowUnauthenticatedAccess: boolean;
     exposedPorts: number[];
+    ingressEndpoint?: string;
     sandboxUrl?: string;
 }
 /** Sandbox information plus the archival timestamp. */
@@ -329,6 +333,10 @@ interface SandboxClientOptions {
     namespace?: string;
     maxRetries?: number;
     retryBackoffMs?: number;
+    /** Total HTTP request timeout in seconds. Default: 300. */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. Total HTTP request timeout in milliseconds. */
+    timeoutMs?: number;
 }
 interface SandboxOptions {
     sandboxId: string;
@@ -337,10 +345,20 @@ interface SandboxOptions {
     organizationId?: string;
     projectId?: string;
     routingHint?: string;
+    resolveProxyInfo?: (identifier: string) => Promise<SandboxInfo & {
+        readonly traceId: string;
+    }>;
+    /** Optional total HTTP request timeout in seconds for sandbox proxy operations. Omit for no total proxy timeout. */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. Optional total HTTP request timeout in milliseconds for sandbox proxy operations. */
+    timeoutMs?: number;
 }
 interface CreateAndConnectOptions extends CreateSandboxOptions {
     poolId?: string;
     proxyUrl?: string;
+    /** Total HTTP request timeout in seconds for sandbox startup. Default: client requestTimeout. */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. */
     startupTimeout?: number;
 }
 interface SuspendResumeOptions {
@@ -509,19 +527,22 @@ declare class Pty {
 declare class Sandbox {
     readonly sandboxId: string;
     traceId: string | null;
+    private readonly proxy;
     private readonly http;
-    private readonly baseUrl;
-    private readonly wsHeaders;
     private ownsSandbox;
     private lifecycleClient;
     private lifecycleIdentifier;
     private sandboxName;
     constructor(options: SandboxOptions);
+    private get baseUrl();
+    private get wsHeaders();
     get name(): string | null;
     /** @internal Used by client wiring to keep locally cached name in sync. */
     _setName(name: string | null): void;
     /** @internal Used by lifecycle operations to pin to canonical sandbox ID. */
     _setLifecycleIdentifier(identifier: string): void;
+    /** @internal Used by the lazy proxy resolver. */
+    _getLifecycleIdentifier(): string;
     /** @internal Used by SandboxClient.createAndConnect to set ownership. */
     _setOwner(client: SandboxClient): void;
     /**
@@ -534,9 +555,9 @@ declare class Sandbox {
     /**
      * Attach to an existing sandbox and return a connected handle.
      *
-     * Returns immediately without contacting the server. Call `sandbox.info()`
-     * to fetch the current state on demand. Does **not** auto-resume a suspended
-     * sandbox — call `sandbox.resume()` explicitly.
+     * When `proxyUrl` is omitted, resolves the sandbox first so the handle uses
+     * the correct cloud/region ingress endpoint. Does **not** auto-resume a
+     * suspended sandbox — call `sandbox.resume()` explicitly.
      */
     static connect(options: ConnectOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
     /** Get information about a snapshot by ID. No sandbox handle needed. */
@@ -685,6 +706,9 @@ declare class SandboxClient {
     private readonly projectId;
     private readonly namespace;
     private readonly local;
+    private readonly maxRetries;
+    private readonly retryBackoffMs;
+    private readonly requestTimeoutMs;
     /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
     constructor(options?: SandboxClientOptions, _internal?: boolean);
     /** Create a client for the TensorLake cloud platform. */
@@ -693,13 +717,18 @@ declare class SandboxClient {
         organizationId?: string;
         projectId?: string;
         apiUrl?: string;
+        requestTimeout?: number;
+        timeoutMs?: number;
     }): SandboxClient;
     /** Create a client for a local Indexify server. */
     static forLocalhost(options?: {
         apiUrl?: string;
         namespace?: string;
+        requestTimeout?: number;
+        timeoutMs?: number;
     }): SandboxClient;
     close(): void;
+    private withRequestTimeout;
     private path;
     /** Create a new sandbox. Returns immediately; the sandbox may still be starting. Use `createAndConnect()` for a blocking, ready-to-use handle. */
     create(options?: CreateSandboxOptions): Promise<Traced<CreateSandboxResponse>>;
@@ -804,14 +833,15 @@ declare class SandboxClient {
     /** Delete a sandbox pool. Fails if the pool has active containers. */
     deletePool(poolId: string): Promise<void>;
     /** Return a `Sandbox` handle for an existing running sandbox without verifying it exists. */
-    connect(identifier: string, proxyUrl?: string, routingHint?: string): Sandbox;
+    connect(identifier: string, proxyUrl?: string, routingHint?: string, requestTimeout?: number): Sandbox;
     /**
      * Create a sandbox, wait for it to reach `Running`, and return a connected handle.
      *
-     * Blocks until the sandbox is ready or `startupTimeout` elapses. The returned
+     * Blocks until the sandbox is ready or `requestTimeout` elapses. The returned
      * `Sandbox` auto-terminates when `terminate()` is called.
      *
-     * @param options.startupTimeout - Max seconds to wait for `Running` status (default 60).
+     * @param options.requestTimeout - Max seconds to wait for `Running` status (default: client requestTimeout).
+     * @param options.startupTimeout - Deprecated alias for `requestTimeout`.
      * @throws {SandboxError} If the sandbox terminates during startup or the timeout elapses.
      */
     createAndConnect(options?: CreateAndConnectOptions): Promise<Sandbox>;
@@ -1014,6 +1044,15 @@ declare class APIClient {
     requestOutput(applicationName: string, requestId: string): Promise<RequestOutput>;
 }
 
+/**
+ * Build a public sandbox URL from a server-provided ingress endpoint.
+ *
+ * `port` omitted or `9501` returns the management URL:
+ * `https://<sandbox-id>.<ingress-host>`. User ports use the public
+ * `<port>-<sandbox-id>.<ingress-host>` form.
+ */
+declare function sandboxUrlFromIngressEndpoint(ingressEndpoint: string, sandboxId: string, port?: number): string;
+
 /** Base exception for all sandbox-related errors. */
 declare class SandboxException extends Error {
     constructor(message: string);
@@ -1062,4 +1101,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-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 };
+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 };