tensorlake 0.5.37 → 0.5.40

package/dist/index.d.cts

@@ -18,6 +18,86 @@ type Traced<T> = T & {
     readonly traceId: string;
 };
 
+/**
+ * Bridge to the Rust core's sandbox lifecycle + proxy clients (`napi-rs`).
+ *
+ * The proxy data path (process/file/stream ops) is served by the Rust core so
+ * it shares `reqwest`'s connection pool — replacing the previous undici path,
+ * which multiplexed every parallel request onto a single, untuned HTTP/2
+ * connection. The native binding is required: there is no JS fallback.
+ *
+ * Convention (mirrors the Python binding): structured payloads cross as JSON
+ * strings, bytes as `Buffer`, and every call surfaces the W3C `traceId`.
+ * Errors arrive as a JSON `{category, status, message}` string in the native
+ * error message; {@link translateNativeError} rethrows them as the SDK's typed
+ * errors.
+ */
+interface TracedJson {
+    traceId: string;
+    json: string;
+}
+interface TracedBytes {
+    traceId: string;
+    data: Buffer;
+}
+interface TracedEvents {
+    traceId: string;
+    events: string[];
+}
+/** Per-event callback used by the streaming proxy methods. */
+type NativeEmit = (eventJson: string) => void;
+interface NativeSandboxProxyClient {
+    baseUrl(): string;
+    startProcess(payloadJson: string): Promise<TracedJson>;
+    listProcesses(): Promise<TracedJson>;
+    getProcess(pid: number): Promise<TracedJson>;
+    killProcess(pid: number): Promise<string>;
+    restartProcess(pid: number): Promise<TracedJson>;
+    sendSignal(pid: number, signal: number): Promise<TracedJson>;
+    writeStdin(pid: number, data: Buffer): Promise<string>;
+    closeStdin(pid: number): Promise<string>;
+    getStdout(pid: number): Promise<TracedJson>;
+    getStderr(pid: number): Promise<TracedJson>;
+    getOutput(pid: number): Promise<TracedJson>;
+    followStdout(pid: number, emit: NativeEmit): Promise<string>;
+    followStderr(pid: number, emit: NativeEmit): Promise<string>;
+    followOutput(pid: number, emit: NativeEmit): Promise<string>;
+    runProcess(payloadJson: string): Promise<TracedEvents>;
+    runProcessStreaming(payloadJson: string, emit: NativeEmit): Promise<string>;
+    readFile(path: string): Promise<TracedBytes>;
+    writeFile(path: string, content: Buffer): Promise<string>;
+    uploadFile(path: string, localPath: string): Promise<string>;
+    deleteFile(path: string): Promise<string>;
+    listDirectory(path: string): Promise<TracedJson>;
+    createPtySession(payloadJson: string): Promise<TracedJson>;
+    deletePtySession(sessionId: string): Promise<string>;
+    health(): Promise<TracedJson>;
+    info(): Promise<TracedJson>;
+}
+interface NativeSandboxClient {
+    createSandbox(requestJson: string): Promise<TracedJson>;
+    claimSandbox(poolId: string): Promise<TracedJson>;
+    copySandbox(sandboxId: string, times: number): Promise<TracedJson>;
+    getSandbox(sandboxId: string): Promise<TracedJson>;
+    listSandboxes(): Promise<TracedJson>;
+    listArchivedSandboxes(limit?: number | null, cursor?: string | null, direction?: string | null): Promise<TracedJson>;
+    getArchivedSandbox(sandboxId: string): Promise<TracedJson>;
+    updateSandbox(sandboxId: string, requestJson: string): Promise<TracedJson>;
+    deleteSandbox(sandboxId: string): Promise<string>;
+    suspendSandbox(sandboxId: string): Promise<string>;
+    resumeSandbox(sandboxId: string): Promise<string>;
+    createSnapshot(sandboxId: string, snapshotType?: string | null): Promise<TracedJson>;
+    getSnapshot(snapshotId: string): Promise<TracedJson>;
+    listSnapshots(): Promise<TracedJson>;
+    deleteSnapshot(snapshotId: string): Promise<string>;
+    createPool(requestJson: string): Promise<TracedJson>;
+    getPool(poolId: string): Promise<TracedJson>;
+    listPools(): Promise<TracedJson>;
+    updatePool(poolId: string, requestJson: string): Promise<TracedJson>;
+    deletePool(poolId: string): Promise<string>;
+    connectProxy(proxyUrl: string, sandboxId: string, routingHint?: string | null, requestTimeoutSec?: number | null): NativeSandboxProxyClient;
+}
+
 declare enum SandboxStatus {
     PENDING = "pending",
     RUNNING = "running",
@@ -421,6 +501,12 @@ interface SandboxOptions {
     requestTimeout?: number;
     /** @deprecated Use requestTimeout. Optional total HTTP request timeout in milliseconds for sandbox proxy operations. */
     timeoutMs?: number;
+    /**
+     * @internal Shared Rust-backed lifecycle client. When provided, the proxy
+     * client is minted via `connectProxy` so it reuses this client's connection
+     * pool (HTTP/2 coalescing across sandboxes).
+     */
+    nativeClient?: NativeSandboxClient;
 }
 interface CreateAndConnectOptions extends CreateSandboxOptions {
     poolId?: string;
@@ -597,7 +683,6 @@ declare class Sandbox {
     readonly sandboxId: string;
     traceId: string | null;
     private readonly proxy;
-    private readonly http;
     private ownsSandbox;
     private lifecycleClient;
     private lifecycleIdentifier;
@@ -682,7 +767,7 @@ declare class Sandbox {
      * List snapshots taken from this sandbox.
      */
     listSnapshots(): Promise<Traced<SnapshotInfo[]>>;
-    /** Close the HTTP client. The sandbox keeps running. */
+    /** Close the proxy connection. The sandbox keeps running. */
     close(): void;
     /** Terminate the sandbox and release all resources. */
     terminate(): Promise<void>;
@@ -768,19 +853,18 @@ declare class Sandbox {
 /**
  * Client for managing TensorLake sandboxes, pools, and snapshots.
  *
- * Use `SandboxClient.forCloud()` or `SandboxClient.forLocalhost()` for
- * clearer construction depending on your deployment target.
+ * This is a thin shim over the Rust core ({@link NativeSandboxClient}): every
+ * call marshals a request to JSON, delegates the RPC (URL resolution,
+ * namespacing, retries, connection pooling) to Rust, and reshapes the JSON
+ * response. There is no TypeScript-side HTTP transport.
  */
 declare class SandboxClient {
-    private readonly http;
+    private readonly native;
     private readonly apiUrl;
     private readonly apiKey;
     private readonly organizationId;
     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);
@@ -802,7 +886,10 @@ declare class SandboxClient {
     }): SandboxClient;
     close(): void;
     private withRequestTimeout;
-    private path;
+    /** Run a native JSON call and reshape it into a `Traced<T>`. */
+    private tracedJson;
+    /** Run a native JSON call and reshape it into a plain `T` (no trace id). */
+    private plainJson;
     /** 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>>;
     /** Get current state and metadata for a sandbox by ID. */
@@ -837,12 +924,6 @@ declare class SandboxClient {
      * cannot. By default blocks until the sandbox is fully `Suspended`. Pass
      * `{ wait: false }` to return immediately after the request is sent
      * (fire-and-return); the server processes the suspend asynchronously.
-     *
-     * @param sandboxId - ID or name of the sandbox.
-     * @param options.wait - If `true` (default), poll until `Suspended`. Pass `false` to fire-and-return.
-     * @param options.timeout - Max seconds to wait when `wait=true` (default 300).
-     * @param options.pollInterval - Seconds between status polls when `wait=true` (default 1).
-     * @throws {SandboxError} If `wait=true` and the sandbox does not reach `Suspended` within `timeout`.
      */
     suspend(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
     /**
@@ -851,12 +932,6 @@ declare class SandboxClient {
      * By default blocks until the sandbox is `Running` and routable. Pass
      * `{ wait: false }` to return immediately after the request is sent
      * (fire-and-return); the server processes the resume asynchronously.
-     *
-     * @param sandboxId - ID or name of the sandbox.
-     * @param options.wait - If `true` (default), poll until `Running`. Pass `false` to fire-and-return.
-     * @param options.timeout - Max seconds to wait when `wait=true` (default 300).
-     * @param options.pollInterval - Seconds between status polls when `wait=true` (default 1).
-     * @throws {SandboxError} If `wait=true` and the sandbox does not reach `Running` within `timeout`.
      */
     resume(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
     /** Claim a warm sandbox from a pool, creating one if no warm containers are available. */
@@ -876,9 +951,6 @@ declare class SandboxClient {
      * status — the snapshot is created asynchronously. Poll `getSnapshot()` until
      * `local_ready`, `completed`, or `failed`, or use `snapshotAndWait()` to
      * block automatically.
-     *
-     * @param options.snapshotType - `"filesystem"` for cold-boot snapshots (e.g. image builds).
-     *   Omit to use the server default (`filesystem`).
      */
     snapshot(sandboxId: string, options?: SnapshotOptions): Promise<CreateSnapshotResponse>;
     /** Get current status and metadata for a snapshot by ID. */
@@ -893,14 +965,6 @@ declare class SandboxClient {
      * Combines `snapshot()` with polling `getSnapshot()` until `local_ready`
      * or `completed`. Pass `{ waitUntil: "completed" }` when durable
      * `snapshotUri` metadata is required.
-     * Prefer `sandbox.checkpoint()` on a `Sandbox` handle for the same behavior
-     * without managing the client separately.
-     *
-     * @param sandboxId - ID of the running sandbox to snapshot.
-     * @param options.timeout - Max seconds to wait (default 300).
-     * @param options.pollInterval - Seconds between status polls (default 1).
-     * @param options.snapshotType - Snapshot type passed through to `snapshot()`.
-     * @throws {SandboxError} If the snapshot fails or `timeout` elapses.
      */
     snapshotAndWait(sandboxId: string, options?: SnapshotAndWaitOptions): Promise<Traced<SnapshotInfo>>;
     /** Create a new sandbox pool with warm pre-booted containers. */
@@ -920,10 +984,6 @@ declare class SandboxClient {
      *
      * Blocks until the sandbox is ready or `requestTimeout` elapses. The returned
      * `Sandbox` auto-terminates when `terminate()` is called.
-     *
-     * @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>;
 }

package/dist/index.d.ts

@@ -18,6 +18,86 @@ type Traced<T> = T & {
     readonly traceId: string;
 };
 
+/**
+ * Bridge to the Rust core's sandbox lifecycle + proxy clients (`napi-rs`).
+ *
+ * The proxy data path (process/file/stream ops) is served by the Rust core so
+ * it shares `reqwest`'s connection pool — replacing the previous undici path,
+ * which multiplexed every parallel request onto a single, untuned HTTP/2
+ * connection. The native binding is required: there is no JS fallback.
+ *
+ * Convention (mirrors the Python binding): structured payloads cross as JSON
+ * strings, bytes as `Buffer`, and every call surfaces the W3C `traceId`.
+ * Errors arrive as a JSON `{category, status, message}` string in the native
+ * error message; {@link translateNativeError} rethrows them as the SDK's typed
+ * errors.
+ */
+interface TracedJson {
+    traceId: string;
+    json: string;
+}
+interface TracedBytes {
+    traceId: string;
+    data: Buffer;
+}
+interface TracedEvents {
+    traceId: string;
+    events: string[];
+}
+/** Per-event callback used by the streaming proxy methods. */
+type NativeEmit = (eventJson: string) => void;
+interface NativeSandboxProxyClient {
+    baseUrl(): string;
+    startProcess(payloadJson: string): Promise<TracedJson>;
+    listProcesses(): Promise<TracedJson>;
+    getProcess(pid: number): Promise<TracedJson>;
+    killProcess(pid: number): Promise<string>;
+    restartProcess(pid: number): Promise<TracedJson>;
+    sendSignal(pid: number, signal: number): Promise<TracedJson>;
+    writeStdin(pid: number, data: Buffer): Promise<string>;
+    closeStdin(pid: number): Promise<string>;
+    getStdout(pid: number): Promise<TracedJson>;
+    getStderr(pid: number): Promise<TracedJson>;
+    getOutput(pid: number): Promise<TracedJson>;
+    followStdout(pid: number, emit: NativeEmit): Promise<string>;
+    followStderr(pid: number, emit: NativeEmit): Promise<string>;
+    followOutput(pid: number, emit: NativeEmit): Promise<string>;
+    runProcess(payloadJson: string): Promise<TracedEvents>;
+    runProcessStreaming(payloadJson: string, emit: NativeEmit): Promise<string>;
+    readFile(path: string): Promise<TracedBytes>;
+    writeFile(path: string, content: Buffer): Promise<string>;
+    uploadFile(path: string, localPath: string): Promise<string>;
+    deleteFile(path: string): Promise<string>;
+    listDirectory(path: string): Promise<TracedJson>;
+    createPtySession(payloadJson: string): Promise<TracedJson>;
+    deletePtySession(sessionId: string): Promise<string>;
+    health(): Promise<TracedJson>;
+    info(): Promise<TracedJson>;
+}
+interface NativeSandboxClient {
+    createSandbox(requestJson: string): Promise<TracedJson>;
+    claimSandbox(poolId: string): Promise<TracedJson>;
+    copySandbox(sandboxId: string, times: number): Promise<TracedJson>;
+    getSandbox(sandboxId: string): Promise<TracedJson>;
+    listSandboxes(): Promise<TracedJson>;
+    listArchivedSandboxes(limit?: number | null, cursor?: string | null, direction?: string | null): Promise<TracedJson>;
+    getArchivedSandbox(sandboxId: string): Promise<TracedJson>;
+    updateSandbox(sandboxId: string, requestJson: string): Promise<TracedJson>;
+    deleteSandbox(sandboxId: string): Promise<string>;
+    suspendSandbox(sandboxId: string): Promise<string>;
+    resumeSandbox(sandboxId: string): Promise<string>;
+    createSnapshot(sandboxId: string, snapshotType?: string | null): Promise<TracedJson>;
+    getSnapshot(snapshotId: string): Promise<TracedJson>;
+    listSnapshots(): Promise<TracedJson>;
+    deleteSnapshot(snapshotId: string): Promise<string>;
+    createPool(requestJson: string): Promise<TracedJson>;
+    getPool(poolId: string): Promise<TracedJson>;
+    listPools(): Promise<TracedJson>;
+    updatePool(poolId: string, requestJson: string): Promise<TracedJson>;
+    deletePool(poolId: string): Promise<string>;
+    connectProxy(proxyUrl: string, sandboxId: string, routingHint?: string | null, requestTimeoutSec?: number | null): NativeSandboxProxyClient;
+}
+
 declare enum SandboxStatus {
     PENDING = "pending",
     RUNNING = "running",
@@ -421,6 +501,12 @@ interface SandboxOptions {
     requestTimeout?: number;
     /** @deprecated Use requestTimeout. Optional total HTTP request timeout in milliseconds for sandbox proxy operations. */
     timeoutMs?: number;
+    /**
+     * @internal Shared Rust-backed lifecycle client. When provided, the proxy
+     * client is minted via `connectProxy` so it reuses this client's connection
+     * pool (HTTP/2 coalescing across sandboxes).
+     */
+    nativeClient?: NativeSandboxClient;
 }
 interface CreateAndConnectOptions extends CreateSandboxOptions {
     poolId?: string;
@@ -597,7 +683,6 @@ declare class Sandbox {
     readonly sandboxId: string;
     traceId: string | null;
     private readonly proxy;
-    private readonly http;
     private ownsSandbox;
     private lifecycleClient;
     private lifecycleIdentifier;
@@ -682,7 +767,7 @@ declare class Sandbox {
      * List snapshots taken from this sandbox.
      */
     listSnapshots(): Promise<Traced<SnapshotInfo[]>>;
-    /** Close the HTTP client. The sandbox keeps running. */
+    /** Close the proxy connection. The sandbox keeps running. */
     close(): void;
     /** Terminate the sandbox and release all resources. */
     terminate(): Promise<void>;
@@ -768,19 +853,18 @@ declare class Sandbox {
 /**
  * Client for managing TensorLake sandboxes, pools, and snapshots.
  *
- * Use `SandboxClient.forCloud()` or `SandboxClient.forLocalhost()` for
- * clearer construction depending on your deployment target.
+ * This is a thin shim over the Rust core ({@link NativeSandboxClient}): every
+ * call marshals a request to JSON, delegates the RPC (URL resolution,
+ * namespacing, retries, connection pooling) to Rust, and reshapes the JSON
+ * response. There is no TypeScript-side HTTP transport.
  */
 declare class SandboxClient {
-    private readonly http;
+    private readonly native;
     private readonly apiUrl;
     private readonly apiKey;
     private readonly organizationId;
     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);
@@ -802,7 +886,10 @@ declare class SandboxClient {
     }): SandboxClient;
     close(): void;
     private withRequestTimeout;
-    private path;
+    /** Run a native JSON call and reshape it into a `Traced<T>`. */
+    private tracedJson;
+    /** Run a native JSON call and reshape it into a plain `T` (no trace id). */
+    private plainJson;
     /** 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>>;
     /** Get current state and metadata for a sandbox by ID. */
@@ -837,12 +924,6 @@ declare class SandboxClient {
      * cannot. By default blocks until the sandbox is fully `Suspended`. Pass
      * `{ wait: false }` to return immediately after the request is sent
      * (fire-and-return); the server processes the suspend asynchronously.
-     *
-     * @param sandboxId - ID or name of the sandbox.
-     * @param options.wait - If `true` (default), poll until `Suspended`. Pass `false` to fire-and-return.
-     * @param options.timeout - Max seconds to wait when `wait=true` (default 300).
-     * @param options.pollInterval - Seconds between status polls when `wait=true` (default 1).
-     * @throws {SandboxError} If `wait=true` and the sandbox does not reach `Suspended` within `timeout`.
      */
     suspend(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
     /**
@@ -851,12 +932,6 @@ declare class SandboxClient {
      * By default blocks until the sandbox is `Running` and routable. Pass
      * `{ wait: false }` to return immediately after the request is sent
      * (fire-and-return); the server processes the resume asynchronously.
-     *
-     * @param sandboxId - ID or name of the sandbox.
-     * @param options.wait - If `true` (default), poll until `Running`. Pass `false` to fire-and-return.
-     * @param options.timeout - Max seconds to wait when `wait=true` (default 300).
-     * @param options.pollInterval - Seconds between status polls when `wait=true` (default 1).
-     * @throws {SandboxError} If `wait=true` and the sandbox does not reach `Running` within `timeout`.
      */
     resume(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
     /** Claim a warm sandbox from a pool, creating one if no warm containers are available. */
@@ -876,9 +951,6 @@ declare class SandboxClient {
      * status — the snapshot is created asynchronously. Poll `getSnapshot()` until
      * `local_ready`, `completed`, or `failed`, or use `snapshotAndWait()` to
      * block automatically.
-     *
-     * @param options.snapshotType - `"filesystem"` for cold-boot snapshots (e.g. image builds).
-     *   Omit to use the server default (`filesystem`).
      */
     snapshot(sandboxId: string, options?: SnapshotOptions): Promise<CreateSnapshotResponse>;
     /** Get current status and metadata for a snapshot by ID. */
@@ -893,14 +965,6 @@ declare class SandboxClient {
      * Combines `snapshot()` with polling `getSnapshot()` until `local_ready`
      * or `completed`. Pass `{ waitUntil: "completed" }` when durable
      * `snapshotUri` metadata is required.
-     * Prefer `sandbox.checkpoint()` on a `Sandbox` handle for the same behavior
-     * without managing the client separately.
-     *
-     * @param sandboxId - ID of the running sandbox to snapshot.
-     * @param options.timeout - Max seconds to wait (default 300).
-     * @param options.pollInterval - Seconds between status polls (default 1).
-     * @param options.snapshotType - Snapshot type passed through to `snapshot()`.
-     * @throws {SandboxError} If the snapshot fails or `timeout` elapses.
      */
     snapshotAndWait(sandboxId: string, options?: SnapshotAndWaitOptions): Promise<Traced<SnapshotInfo>>;
     /** Create a new sandbox pool with warm pre-booted containers. */
@@ -920,10 +984,6 @@ declare class SandboxClient {
      *
      * Blocks until the sandbox is ready or `requestTimeout` elapses. The returned
      * `Sandbox` auto-terminates when `terminate()` is called.
-     *
-     * @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>;
 }