@tensorlakeai/tensorlake 0.0.0-bootstrap.0 → 0.5.145

package/dist/index.d.ts

@@ -0,0 +1,2431 @@
+import { C as CloudClientOptions, A as ApplicationManifest, B as BinaryPayload, S as SandboxTemplate, a as ApplicationSummary, R as RequestInput, c as RequestMetadata, b as RequestOutput, d as SecretsList, e as Secret, N as NewSecret, U as UpsertSecretResponse, f as StartImageBuildRequest, g as BuildInfo, h as CreateApplicationBuildRequest, i as ApplicationBuildContext, j as ApplicationBuildResponse, k as BuildLogEntry, F as FileSystem } from './sandbox-image-ChzWDeZy.js';
+export { l as ApplicationBuildImageResult, m as CreateApplicationBuildImageRequest, n as CreateSandboxImageOptions, I as Image, o as ImageBuildOperation, p as ImageBuildOperationType, p as ImageBuildOperationTypeValue, q as ImageOptions, r as ImportSandboxImageOptions, s as RequestErrorInfo, t as SandboxImageSource, u as SecretsPagination, v as createSandboxImage, w as deleteSandboxImage, x as dockerfileContent, y as findSandboxImageByName, z as importSandboxImage, D as listSandboxImages } from './sandbox-image-ChzWDeZy.js';
+export { v as APIClient, A as ApplicationCapability, a as ApplicationOptions, F as File, b as FunctionOptions, c as Future, H as Headers, d as HeadersInit, e as HttpBody, P as Parameter, g as RegisteredFunction, h as RemoteOptions, j as RequestContext, S as Schema, l as SimpleApplicationOptions, m as SimpleFunctionOptions, T as TailCall, r as registerApplication, o as registerFunction, p as remoteOptions, q as retries, s as runLocal, t as runRemote, u as schema } from './remote-dblFxKug.js';
+
+/** An SDK result paired with its server-side W3C trace ID. */
+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: Uint8Array;
+    contentId?: string;
+    fullSize?: number;
+}
+interface TracedEvents {
+    traceId: string;
+    events: string[];
+}
+/** Per-event callback used by the streaming proxy methods. */
+type NativeEmit = (eventJson: string) => void | Promise<void>;
+interface NativeSandboxProxyClient {
+    baseUrl(): string;
+    startProcess(payloadJson: string): Promise<TracedJson>;
+    listProcesses(): Promise<TracedJson>;
+    getProcess(process: string): Promise<TracedJson>;
+    killProcess(process: string): Promise<string>;
+    restartProcess(process: string): Promise<TracedJson>;
+    sendSignal(process: string, signal: number): Promise<TracedJson>;
+    writeStdin(process: string, data: Buffer): Promise<string>;
+    closeStdin(process: string): Promise<string>;
+    getStdout(process: string): Promise<TracedJson>;
+    getStderr(process: string): Promise<TracedJson>;
+    getOutput(process: string): Promise<TracedJson>;
+    followStdout(process: string, emit: NativeEmit): Promise<string>;
+    followStderr(process: string, emit: NativeEmit): Promise<string>;
+    followOutput(process: string, 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>;
+    /** Wait-free create (`wait: false`, ADR 0086). */
+    createSandboxNoWait(requestJson: string): Promise<TracedJson>;
+    /** Poll the sandbox until it leaves `pending` or the budget runs out; resolves with the last `SandboxInfo`. */
+    waitForSandbox(sandboxId: string, timeoutSec: number, pollIntervalSec?: number | null): Promise<TracedJson>;
+    claimSandbox(poolId: string, requestJson?: 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>;
+    getSandboxLogs(requestJson: string): Promise<TracedJson>;
+    listSandboxLogProcesses(sandboxId: string): Promise<TracedJson>;
+    updateSandbox(sandboxId: string, requestJson: string, wait?: boolean, timeoutSec?: number, pollIntervalSec?: number): Promise<TracedJson>;
+    waitForResourceResize(sandboxId: string, generation: number, timeoutSec?: number, pollIntervalSec?: number): Promise<TracedJson>;
+    deleteSandbox(sandboxId: string): Promise<string>;
+    suspendSandbox(sandboxId: string): Promise<string>;
+    resumeSandbox(sandboxId: string): Promise<string>;
+    attachFileSystem(sandboxId: string, fileSystemId: string, mountPath: string, readOnly?: boolean | null, prefetch?: boolean | null, snapshotId?: string | null, owner?: string | null): Promise<TracedJson>;
+    detachFileSystem(sandboxId: string, mountPath: string): Promise<TracedJson>;
+    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;
+    selectSandboxProxyUrl(sandboxId: string, sandboxUrl?: string | null, ingressEndpoint?: string | null, explicitProxyUrl?: string | null): string | Promise<string>;
+}
+interface NativeRepositoryClient {
+    gitRepoUrl(repo: string): Promise<string>;
+    createRepo(repo: string, defaultBranch?: string | null): Promise<TracedJson>;
+    listRepos(): Promise<TracedJson>;
+    deleteRepo(repo: string): Promise<string>;
+    forkRepo(repo: string, baseRepo: string): Promise<TracedJson>;
+    archiveRepo(repo: string): Promise<string>;
+    restoreRepo(repo: string): Promise<string>;
+    repoInfo(repo: string): Promise<TracedJson>;
+    listBranches(repo: string): Promise<TracedJson>;
+    listRefs(repo: string): Promise<TracedJson>;
+    deleteBranch(repo: string, branch: string): Promise<string>;
+    listOperations(repo: string): Promise<TracedJson>;
+    gitCredential(repo?: string | null): Promise<string>;
+    commitStatus(repo: string, jobId: string): Promise<TracedJson>;
+    pushWorktree(repo: string, root: string, branch: string, message: string, expectOid?: string | null): Promise<TracedJson>;
+    mergeRepo(repo: string, ours: string, theirs: string, preflight: boolean, deep: boolean, materialize: boolean, message?: string | null, base?: string | null): Promise<TracedJson>;
+    commitConflicts(repo: string, commit: string): Promise<TracedJson>;
+    createFilesystem(name: string, region?: string): Promise<string>;
+    forkFilesystem(name: string, base: string, snapshot?: string | null): Promise<TracedJson>;
+    listFilesystems(): Promise<TracedJson>;
+    filesystemMeta(name: string): Promise<TracedJson>;
+    deleteFilesystem(name: string): Promise<string>;
+    filesystemRefStatus(name: string, refspec: string): Promise<TracedJson>;
+    retainFilesystemSnapshot(name: string, message: string, requestId: string): Promise<TracedJson>;
+    listFilesystemSnapshots(name: string): Promise<TracedJson>;
+    deleteFilesystemSnapshot(name: string, snapshot: string): Promise<string>;
+    readFilesystemFile(name: string, path: string, version: string, offset?: number, length?: number): Promise<TracedBytes>;
+    listFilesystemTree(name: string, dirPath: string, version: string): Promise<TracedJson>;
+    pushFilesystemFiles(name: string, files: Array<{
+        path: string;
+        content: Buffer;
+    }>, deletes: string[], moves: Array<{
+        from: string;
+        to: string;
+    }>, copies: Array<{
+        from: string;
+        to: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+    pushFilesystemPaths(name: string, files: Array<{
+        path: string;
+        localPath: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+}
+
+declare enum SandboxStatus {
+    PENDING = "pending",
+    RUNNING = "running",
+    SNAPSHOTTING = "snapshotting",
+    SUSPENDING = "suspending",
+    SUSPENDED = "suspended",
+    TERMINATED = "terminated",
+    TIMEOUT = "timeout",
+    /** Terminal status used by blocking create/claim responses. */
+    FAILED = "failed"
+}
+/**
+ * Why a pending sandbox is waiting (`pendingReason`). The wire value is a
+ * snake_case string; unknown future reasons arrive as plain strings.
+ */
+declare enum SandboxPendingReason {
+    SCHEDULING = "scheduling",
+    WAITING_FOR_CONTAINER = "waiting_for_container",
+    NO_EXECUTORS_AVAILABLE = "no_executors_available",
+    NO_RESOURCES_AVAILABLE = "no_resources_available",
+    POOL_AT_CAPACITY = "pool_at_capacity",
+    MAX_CAPACITY_REACHED = "max_capacity_reached",
+    NO_EXECUTOR_FOR_SNAPSHOT_LOCATION = "no_executor_for_snapshot_location",
+    /** The autoscaler reported that no fleet can ever place this shape. */
+    UNPLACEABLE = "unplaceable"
+}
+/** `terminationReason` when a `maxPendingSecs` bound expired, or the shape is unplaceable. */
+declare const TERMINATION_REASON_NO_CAPACITY = "no_capacity";
+/** `terminationReason` when a pending sandbox was deleted before it ran. */
+declare const TERMINATION_REASON_CANCELLED = "cancelled";
+/** Whether a sandbox status is one a readiness wait keeps polling through. */
+declare function isSandboxPending(status: SandboxStatus | string): boolean;
+declare enum SnapshotStatus {
+    IN_PROGRESS = "in_progress",
+    LOCAL_READY = "local_ready",
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+/**
+ * Snapshot type for sandbox snapshot creation.
+ *
+ * - `"memory"`: Capture VM memory + filesystem state. Sandboxes restored
+ *   from this snapshot warm-restore VM memory.
+ * - `"filesystem"`: Capture filesystem state only. Sandboxes restored from
+ *   this snapshot cold-boot from the snapshot tarball instead of warm-
+ *   restoring VM state. Use this for sandbox image builds so that the
+ *   restored sandbox bypasses Firecracker's overlay-path constraints.
+ */
+type SnapshotType = "memory" | "filesystem";
+/**
+ * Checkpoint type for {@link Sandbox.checkpoint}.
+ *
+ * - `"memory"`: Capture VM memory + filesystem state. Sandboxes restored
+ *   from this checkpoint warm-restore VM memory and running processes.
+ * - `"filesystem"`: Capture filesystem state only. Sandboxes restored from
+ *   this checkpoint cold-boot from the snapshot tarball.
+ */
+type CheckpointType = "memory" | "filesystem";
+type SnapshotWaitCondition = "local_ready" | "completed";
+declare enum ProcessStatus {
+    RUNNING = "running",
+    EXITED = "exited",
+    SIGNALED = "signaled",
+    OOM_KILLED = "oom_killed"
+}
+declare enum StdinMode {
+    CLOSED = "closed",
+    PIPE = "pipe"
+}
+declare enum OutputMode {
+    CAPTURE = "capture",
+    DISCARD = "discard"
+}
+declare enum ContainerState {
+    IDLE = "Idle",
+    RUNNING = "Running"
+}
+interface ContainerResourcesInfo {
+    cpus: number;
+    memoryMb: number;
+    diskMb: number;
+}
+/** GPU models supported by the sandbox scheduler. */
+type GpuModel = "A100-40GB" | "A100-80GB" | "H100" | "T4" | "A6000" | "RTX-PRO-6000" | "L40" | "A10";
+/** A homogeneous GPU allocation for a sandbox. */
+interface GpuRequest {
+    count: number;
+    model: GpuModel;
+}
+interface GPUResources {
+    count: number;
+    model: string;
+}
+/**
+ * Egress network access control policy for a sandbox.
+ *
+ * `denyOut` takes precedence over `allowOut`: a destination matched by both is
+ * blocked. Entries may be IPv4 addresses, CIDR ranges, or DNS hostnames;
+ * hostname rules are followed across DNS changes. The policy can be changed on
+ * a running sandbox via `Sandbox.update({ network })` (pass `null` to clear).
+ */
+interface NetworkConfig {
+    allowInternetAccess: boolean;
+    allowOut: string[];
+    denyOut: string[];
+}
+/**
+ * One file system mounted into a sandbox at an absolute guest path.
+ *
+ * `fileSystemId` is the Artifact Storage file-system name created with
+ * `tl fs create <name>` and `mountPath` is an absolute, unique guest path
+ * (e.g. `/mnt/skills`).
+ *
+ * `readOnly` and `prefetch` are optional mount modes; they are sent on the
+ * wire only when `true` (older servers reject unknown mount fields, so
+ * `false` is expressed by omission).
+ *
+ * `snapshotId` pins the mount to a specific filesystem snapshot. A pinned
+ * mount must also set `readOnly: true` (the server rejects a writable pin
+ * with HTTP 400). It is sent only when set, for the same compatibility
+ * reason as the mount modes.
+ *
+ * `owner` presents the mounted files as owned by a guest user: `NAME`,
+ * `UID`, `NAME:GROUP`, or `UID:GID` (e.g. `"agent"` or `"1001:1001"`),
+ * resolved against the sandbox image's own user database when the mount
+ * attaches. Unset keeps the image default (the baked `tl-user` account when
+ * the image has one, otherwise root). It is sent only when set, for the
+ * same compatibility reason as the mount modes.
+ */
+interface FileSystemMount {
+    fileSystemId: string;
+    mountPath: string;
+    /** Mount the file system read-only. */
+    readOnly?: boolean;
+    /** Eagerly download the file system's contents. */
+    prefetch?: boolean;
+    /** Pin the mount to a specific filesystem snapshot (requires `readOnly`). */
+    snapshotId?: string;
+    /** Present the mounted files as owned by this guest user spec. */
+    owner?: string;
+}
+/** Optional mount modes for attaching a file system to a running sandbox. */
+interface AttachFileSystemOptions {
+    /** Mount the file system read-only. */
+    readOnly?: boolean;
+    /** Eagerly download the file system's contents. */
+    prefetch?: boolean;
+    /** Pin the mount to a specific filesystem snapshot (requires `readOnly`). */
+    snapshotId?: string;
+    /** Present the mounted files as owned by this guest user spec. */
+    owner?: string;
+}
+interface ClaimSandboxOptions {
+    /** File systems to mount before the claimed sandbox is reported as running. */
+    fileSystems?: FileSystemMount[];
+}
+interface CreateSandboxOptions {
+    /** Optional sandbox image name. GPU sandboxes require a CAS image; when omitted with a GPU request, Tensorlake uses the server's configured GPU default. */
+    image?: string;
+    /** CPU count. Defaults to 1 for fresh creates; snapshot restores inherit it when omitted. */
+    cpus?: number;
+    /** Memory in MiB. Defaults to 1024 for fresh creates; snapshot restores inherit it when omitted. */
+    memoryMb?: number;
+    /** Root disk size in MiB. When omitted, the server uses its default disk size. */
+    diskMb?: number;
+    /** Number of GPUs to allocate. Defaults to A10 unless gpuModel is set. GPU sandboxes require a CAS image. */
+    gpus?: number;
+    /** GPU model to allocate. The string arm preserves compatibility with existing callers; values are validated at runtime. */
+    gpuModel?: GpuModel | (string & {});
+    /** Typed GPU model and count request. Cannot be combined with gpus or gpuModel. */
+    gpu?: GpuRequest;
+    timeoutSecs?: number;
+    entrypoint?: string[];
+    allowInternetAccess?: boolean;
+    allowOut?: string[];
+    denyOut?: string[];
+    snapshotId?: string;
+    /** Optional name for the sandbox. Named sandboxes support suspend/resume. When absent the sandbox is ephemeral. */
+    name?: string;
+    /** File systems to mount on fresh creation or warm-pool claim, each at its own absolute, unique guest mount path. */
+    fileSystems?: FileSystemMount[];
+    /**
+     * `false` returns a `PendingSandbox` handle as soon as the sandbox is
+     * durable, without waiting for it to run: `pending.ready()` waits,
+     * `pending.status()` looks, and `Sandbox.connect(pending.sandboxId)`
+     * collects it from any other process. `true` / unset waits as before.
+     */
+    wait?: boolean;
+    /**
+     * Longest the sandbox may wait for capacity before the server fails it with
+     * reason `no_capacity`. `0` fails at once when it cannot be placed; unset
+     * (the default) waits indefinitely. Applies to capacity waits only, not to
+     * image pull or boot. A bound shorter than the fleet's boot time (up to 20
+     * minutes on metal hosts) expires the very demand that made the autoscaler
+     * launch a host; 30 minutes or more is recommended for capacity waits.
+     */
+    maxPendingSecs?: number;
+}
+/**
+ * Bounded generation wait. Timeout never cancels a resize. Times are seconds.
+ * A zero timeout checks once without polling again.
+ */
+interface ResourceResizeWaitOptions {
+    timeout?: number;
+    pollInterval?: number;
+}
+declare enum ResizeStatus {
+    PENDING = "pending",
+    SUCCEEDED = "succeeded",
+    FAILED = "failed"
+}
+declare enum ResizeErrorReason {
+    FAILED = "failed",
+    TIMEOUT = "timeout",
+    SUPERSEDED = "superseded",
+    INTERRUPTED = "interrupted",
+    INCOMPATIBLE_RESPONSE = "incompatible_response"
+}
+interface SandboxResourceResizeInfo {
+    generation: number;
+    requested: ContainerResourcesInfo;
+    status: ResizeStatus | (string & {});
+    errorMessage?: string | null;
+}
+/** Wait options apply only to resource updates and are ignored for other properties. */
+interface UpdateSandboxOptions extends ResourceResizeWaitOptions {
+    /** Whole live vCPU target; omitted retains the current allocation. */
+    cpus?: number;
+    /** Memory target in MiB, with the same units as create; never rounded by the SDK. */
+    memoryMb?: number;
+    /** Root disk target in MiB; can only grow. */
+    diskMb?: number;
+    /** Wait for resize completion (default true). False returns admission. */
+    wait?: boolean;
+    /** New name for the sandbox. Naming an ephemeral sandbox enables suspend/resume. */
+    name?: string;
+    /** Whether exposed user ports should be reachable without TensorLake auth. */
+    allowUnauthenticatedAccess?: boolean;
+    /** User ports that should be routable through the sandbox proxy. Port 9501 is reserved. */
+    exposedPorts?: number[];
+    /**
+     * Egress network policy for the running sandbox, applied to the live VM's
+     * firewall in one atomic swap. Omit to keep the current policy, set to
+     * replace it, or pass `null` to clear it to unrestricted egress.
+     */
+    network?: NetworkConfig | null;
+}
+/**
+ * Response from a blocking create or a pool claim.
+ *
+ * The server waits for readiness for at most the request timeout and can
+ * already report `running`; a `pending` answer carries a `pendingReason`.
+ * Use `connect(sandboxId)` to wait for a pending sandbox, or
+ * `create({ wait: false })` for a `PendingSandbox` handle.
+ */
+interface CreateSandboxResponse {
+    sandboxId: string;
+    status: SandboxStatus;
+    reason?: string;
+    routingHint?: string;
+    ingressEndpoint?: string;
+    sandboxUrl?: string;
+    name?: string | null;
+    terminationReason?: string;
+    errorDetails?: unknown;
+    pendingReason?: string;
+}
+/**
+ * The acknowledgement of a `create({ wait: false })`: the wire record of a
+ * sandbox that is durable and starts whenever capacity allows. The
+ * `PendingSandbox` class in `pending-sandbox.ts` wraps it with `ready()` /
+ * `status()`. A server that predates `wait: false` answers the blocking
+ * create's shape instead, so `state` may already be `running`.
+ */
+interface PendingSandboxRecord {
+    sandboxId: string;
+    name?: string;
+    state: SandboxStatus;
+    pendingReason?: string;
+    routingHint?: string;
+    ingressEndpoint?: string;
+    sandboxUrl?: string;
+    reason?: string;
+    terminationReason?: string;
+    errorDetails?: unknown;
+}
+interface ReadyOptions {
+    /** Seconds to wait; defaults to the client requestTimeout. `0` observes the current state once. */
+    timeout?: number;
+    /** Seconds between `GET /sandboxes/{id}` polls. Default: 2. */
+    pollInterval?: number;
+    /**
+     * Delete the sandbox when `timeout` runs out while it is still pending,
+     * then throw `SandboxError` (the pre-ADR-0086 behaviour). Default false:
+     * throw `SandboxPending` and leave the sandbox queued.
+     */
+    cancelOnTimeout?: boolean;
+}
+interface CopySandboxOptions {
+    /** Number of running copies to create. Defaults to 1. */
+    times?: number;
+    /** Per-request timeout in seconds for the blocking live-copy request. */
+    requestTimeout?: number;
+}
+interface CopiedSandboxResponse {
+    sandboxId: string;
+    /** Raw server status. Partial copy responses can include statuses such as `"failed"`. */
+    status: string;
+    reason?: string;
+    routingHint?: string;
+    ingressEndpoint?: string;
+    sandboxUrl?: string;
+    name?: string | null;
+    terminationReason?: string;
+    errorDetails?: unknown;
+}
+interface CopySandboxResponse {
+    sourceSandboxId: string;
+    sandboxes: CopiedSandboxResponse[];
+}
+interface SandboxInfo {
+    runtime?: string;
+    resourceResize?: SandboxResourceResizeInfo | null;
+    sandboxId: string;
+    namespace: string;
+    status: SandboxStatus;
+    /** Resolved sandbox image name. */
+    image?: string;
+    resources: ContainerResourcesInfo;
+    timeoutSecs?: number;
+    entrypoint?: string[];
+    /** Egress network policy currently applied to the sandbox. */
+    networkPolicy?: NetworkConfig;
+    poolId?: string;
+    outcome?: string;
+    terminationReason?: string;
+    errorDetails?: unknown;
+    /** Why a pending sandbox is waiting, in snake_case. */
+    pendingReason?: string;
+    createdAt?: Date;
+    terminatedAt?: Date;
+    name?: string;
+    allowUnauthenticatedAccess?: boolean;
+    exposedPorts?: number[];
+    ingressEndpoint?: string;
+    sandboxUrl?: string;
+    routingHint?: string;
+    /** File systems currently mounted into the sandbox, each at its own guest mount path. Empty when none are mounted. */
+    fileSystems?: FileSystemMount[];
+}
+interface SandboxPortAccess {
+    allowUnauthenticatedAccess: boolean;
+    exposedPorts: number[];
+    ingressEndpoint?: string;
+    sandboxUrl?: string;
+}
+/** Sandbox information plus the archival timestamp. */
+interface ArchivedSandboxInfo extends SandboxInfo {
+    archivedAt: Date;
+}
+/** Pagination params for `listArchivedSandboxes`. */
+interface ListArchivedSandboxesOptions {
+    limit?: number;
+    /** Base64-encoded pagination cursor returned by a prior call. */
+    cursor?: string;
+    /** Pagination direction. */
+    direction?: "forward" | "backward";
+}
+interface ListArchivedSandboxesResponse {
+    sandboxes: ArchivedSandboxInfo[];
+    prevCursor?: string;
+    nextCursor?: string;
+}
+interface CreateSnapshotResponse {
+    snapshotId: string;
+    status: SnapshotStatus;
+}
+interface SnapshotInfo {
+    snapshotId: string;
+    namespace: string;
+    sandboxId: string;
+    baseImage: string;
+    status: SnapshotStatus;
+    snapshotType?: SnapshotType;
+    error?: string;
+    snapshotUri?: string;
+    snapshotFormatVersion?: string;
+    sizeBytes?: number;
+    rootfsDiskBytes?: number;
+    createdAt?: Date;
+}
+interface SnapshotOptions {
+    /**
+     * Optional snapshot type. When omitted the server picks its default. Use
+     * `"filesystem"` for snapshots intended for sandbox image builds so that
+     * restored sandboxes cold-boot.
+     */
+    snapshotType?: SnapshotType;
+}
+interface SnapshotAndWaitOptions extends SnapshotOptions {
+    timeout?: number;
+    pollInterval?: number;
+    /** Defaults to `"local_ready"`, which is enough to resume from a snapshot. */
+    waitUntil?: SnapshotWaitCondition;
+}
+type SandboxLogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+interface GetSandboxLogsOptions {
+    levels?: SandboxLogLevel[];
+    processIds?: string[];
+    nextToken?: string;
+    head?: number;
+    tail?: number;
+    body?: string;
+}
+interface SandboxLogSignal {
+    timestamp: number;
+    uuid: string;
+    namespace: string;
+    application: string;
+    sandboxId?: string;
+    resourceAttributes: Array<[string, string]>;
+    body: string;
+    logAttributes: string;
+    allocations?: string[];
+    functionRuns?: string[];
+    level?: number;
+    retention?: number;
+}
+interface SandboxLogsResponse {
+    logs: SandboxLogSignal[];
+    nextToken?: string;
+}
+interface SandboxProcessLogFilter {
+    processId: string;
+    processPid: string;
+    processCommand: string;
+    processManagedId: string;
+    processManagedName: string;
+    firstSeen: number;
+    lastSeen: number;
+    logCount: number;
+}
+interface SandboxProcessLogFiltersResponse {
+    processes: SandboxProcessLogFilter[];
+}
+interface CreatePoolOptions {
+    /** Sandbox image name, such as `tensorlake/ubuntu-minimal` or a registered Sandbox Image. */
+    image: string;
+    cpus?: number;
+    memoryMb?: number;
+    /** Root disk size in MiB. Omit to use the registered image's size. */
+    diskMb?: number;
+    timeoutSecs?: number;
+    entrypoint?: string[];
+    maxContainers?: number;
+    warmContainers?: number;
+    /** Network policy for each container. Can be replaced later via updatePool. */
+    network?: NetworkConfig;
+}
+interface UpdatePoolOptions {
+    /**
+     * Network policy for each container. Omit to keep the pool's current policy,
+     * set to replace it, or pass `null` to remove it (unclaimed warm containers
+     * are recycled onto the new policy).
+     */
+    network?: NetworkConfig | null;
+    /** Sandbox image name, such as `tensorlake/ubuntu-minimal` or a registered Sandbox Image. */
+    image: string;
+    cpus?: number;
+    memoryMb?: number;
+    /** Root disk size in MiB. Omit to use the registered image's size. */
+    diskMb?: number;
+    timeoutSecs?: number;
+    entrypoint?: string[];
+    maxContainers?: number;
+    warmContainers?: number;
+}
+interface CreateSandboxPoolResponse {
+    poolId: string;
+    namespace: string;
+}
+interface PoolContainerInfo {
+    id: string;
+    state: string;
+    sandboxId?: string;
+    executorId: string;
+}
+interface SandboxPoolInfo {
+    poolId: string;
+    namespace: string;
+    /** Sandbox image name backing the pool. */
+    image: string;
+    resources: ContainerResourcesInfo;
+    timeoutSecs: number;
+    entrypoint?: string[];
+    maxContainers?: number;
+    warmContainers?: number;
+    /** The network policy that applies to each container in the pool. */
+    networkPolicy?: NetworkConfig;
+    containers?: PoolContainerInfo[];
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+interface ProcessUserSpec {
+    name?: string;
+    uid?: number;
+    gid?: number;
+}
+type ProcessUser = string | ProcessUserSpec;
+type RestartPolicy = "never" | "on_failure" | "always";
+interface RestartPolicyConfig {
+    policy?: RestartPolicy;
+    maxRestarts?: number;
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+}
+type ProcessHealthCheckType = "http" | "tcp";
+interface ProcessHealthCheck {
+    type: ProcessHealthCheckType;
+    port: number;
+    path?: string;
+    initialDelayMs?: number;
+    intervalMs?: number;
+    timeoutMs?: number;
+    failureThreshold?: number;
+}
+type ManagedProcessStatus = "starting" | "running" | "backing_off" | "stopped";
+type ManagedProcessHealthStatus = "disabled" | "starting" | "healthy" | "unhealthy";
+interface ManagedProcessExit {
+    exitCode?: number;
+    signal?: number;
+    oomKilled: boolean;
+    endedAt: Date;
+}
+/**
+ * Managed-process metadata embedded into {@link ProcessInfo}.
+ *
+ * A managed process is addressable by either its current PID or, if a `name` was given at
+ * creation, that name (process APIs accept a PID or process name). `id` is a stable
+ * daemon-local identifier: it equals `name` when one was set, otherwise a daemon-assigned
+ * opaque id (the process is then addressable only by PID, not by `id`).
+ */
+interface ManagedProcessInfo {
+    id: string;
+    name?: string;
+    status: ManagedProcessStatus;
+    restartCount: number;
+    restart: RestartPolicyConfig;
+    healthCheck?: ProcessHealthCheck;
+    healthStatus: ManagedProcessHealthStatus;
+    consecutiveHealthFailures: number;
+    lastExit?: ManagedProcessExit;
+    lastError?: string;
+    nextRestartAt?: Date;
+}
+interface StartProcessOptions {
+    args?: string[];
+    env?: Record<string, string>;
+    workingDir?: string;
+    stdinMode?: StdinMode;
+    stdoutMode?: OutputMode;
+    stderrMode?: OutputMode;
+    user?: ProcessUser;
+    /**
+     * Optional managed-process name. Supplying this opts into managed process behavior, and
+     * lets the process be addressed by this name (in addition to its PID) in
+     * `getProcess`/`killProcess`/`sendSignal`/etc. — useful because a managed process's PID
+     * changes when it restarts. May contain any characters except `/` and must not be all
+     * digits (numeric strings are reserved for PID addressing). If omitted, the daemon assigns
+     * an opaque id (`ManagedProcessInfo.id`) and the process is addressable only by its current PID.
+     */
+    name?: string;
+    /** Optional restart behavior. Supplying this opts into managed process behavior. */
+    restart?: RestartPolicyConfig;
+    /** Optional HTTP/TCP health check. Supplying this opts into managed process behavior. */
+    healthCheck?: ProcessHealthCheck;
+}
+interface ProcessInfo {
+    handle?: number;
+    pid: number;
+    status: ProcessStatus;
+    exitCode?: number;
+    signal?: number;
+    stdinWritable: boolean;
+    command: string;
+    args: string[];
+    startedAt: Date;
+    endedAt?: Date;
+    managed?: ManagedProcessInfo;
+}
+interface SendSignalResponse {
+    success: boolean;
+}
+interface OutputResponse {
+    pid: number;
+    lines: string[];
+    lineCount: number;
+}
+interface OutputEvent {
+    line: string;
+    timestamp: Date;
+    stream?: string;
+}
+interface RunOptions {
+    args?: string[];
+    env?: Record<string, string>;
+    workingDir?: string;
+    timeout?: number;
+    user?: ProcessUser;
+}
+interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface DirectoryEntry {
+    name: string;
+    isDir: boolean;
+    size?: number;
+    modifiedAt?: Date;
+}
+interface ListDirectoryResponse {
+    path: string;
+    entries: DirectoryEntry[];
+}
+interface CreatePtySessionOptions {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    workingDir?: string;
+    rows?: number;
+    cols?: number;
+}
+interface PtySessionInfo {
+    sessionId: string;
+    token: string;
+}
+interface HealthResponse {
+    healthy: boolean;
+}
+interface DaemonInfo {
+    version: string;
+    uptimeSecs: number;
+    runningProcesses: number;
+    totalProcesses: number;
+}
+interface SandboxClientOptions {
+    apiUrl?: string;
+    apiKey?: string;
+    organizationId?: string;
+    projectId?: string;
+    namespace?: string;
+    maxRetries?: number;
+    retryBackoffMs?: number;
+    /**
+     * HTTP request timeout in seconds. For a streamed response it bounds the
+     * wait for the stream to start and each wait for more data. Default: 300.
+     */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. HTTP request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+interface SandboxOptions {
+    sandboxId: string;
+    /**
+     * Explicit sandbox proxy base URL. Direct `new Sandbox(...)` construction
+     * requires this; `Sandbox.connect()` and `SandboxClient.connect()` normally
+     * resolve the server-returned `sandboxUrl`.
+     */
+    proxyUrl?: string;
+    /** @internal Real caller/env proxy override, distinct from an internally selected proxyUrl. */
+    explicitProxyUrl?: string;
+    apiKey?: string;
+    organizationId?: string;
+    projectId?: string;
+    routingHint?: string;
+    resolveProxyInfo?: (identifier: string) => Promise<SandboxInfo & {
+        readonly traceId: string;
+    }>;
+    /**
+     * Optional HTTP request timeout in seconds for sandbox proxy operations. For
+     * streamed responses, such as `run()` and output follows, it bounds the wait
+     * for the stream to start and each wait for more data. Omit for no proxy
+     * timeout.
+     */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. Optional 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;
+    proxyUrl?: string;
+    /** Total HTTP request timeout in seconds for sandbox startup. Default: client requestTimeout. */
+    requestTimeout?: number;
+    /** @deprecated Use requestTimeout. */
+    startupTimeout?: number;
+    /**
+     * Delete the sandbox when `requestTimeout` runs out while it is still
+     * pending, then throw `SandboxError` (the pre-ADR-0086 behaviour). Default
+     * false: throw `SandboxPending` and leave the sandbox queued.
+     */
+    cancelOnTimeout?: boolean;
+    /** Seconds between readiness polls. Default: 2. */
+    pollInterval?: number;
+}
+/**
+ * Options for `Sandbox.getOrCreate`: everything `create` accepts (used only
+ * when a new sandbox must be created; `name` comes from the first argument),
+ * plus `resume`. `poolId` is excluded: a pool claim cannot carry a name, so
+ * a claimed sandbox could never be found again by a later call.
+ */
+interface GetOrCreateOptions extends Omit<CreateAndConnectOptions, "name" | "poolId"> {
+    /** Resume a suspended sandbox before returning. Default: true. */
+    resume?: boolean;
+}
+/**
+ * What `Sandbox.getOrCreate` did to bind the name, exposed as
+ * `sandbox.bindOutcome`:
+ *
+ * - `"created"`: nothing held the name; the call created a new sandbox.
+ * - `"attached"`: a sandbox already held the name and needed no resume.
+ *   Includes a sandbox that was still starting (the call waited for it)
+ *   and a suspended sandbox when `resume: false`.
+ * - `"resumed"`: the sandbox was suspended when the call found it and is
+ *   running now.
+ */
+type GetOrCreateOutcome = "created" | "attached" | "resumed";
+interface SuspendResumeOptions {
+    /** If false, fire-and-return without waiting for completion. Default: true. */
+    wait?: boolean;
+    /** Max seconds to wait when wait=true. Default: 300. */
+    timeout?: number;
+    /** Seconds between status polls when wait=true. Default: 1. */
+    pollInterval?: number;
+}
+interface CheckpointOptions extends SuspendResumeOptions {
+    checkpointType?: CheckpointType;
+    /** Defaults to `"local_ready"`, which is enough to resume from a checkpoint. */
+    waitUntil?: SnapshotWaitCondition;
+}
+interface ConnectOptions {
+    sandboxId: string;
+    proxyUrl?: string;
+    routingHint?: string;
+}
+
+type MouseButton = "left" | "middle" | "right";
+interface ConnectDesktopOptions {
+    /** Remote VNC port. Defaults to `5901`. */
+    port?: number;
+    /** Optional VNC password for classic VNC authentication. */
+    password?: string;
+    /** Whether to request a shared VNC session. Defaults to `true`. */
+    shared?: boolean;
+    /** Seconds to wait while opening the desktop session. Defaults to `10`. */
+    connectTimeout?: number;
+}
+interface DesktopPointerOptions {
+    button?: MouseButton;
+    x?: number;
+    y?: number;
+}
+interface DesktopDoubleClickOptions extends DesktopPointerOptions {
+    delayMs?: number;
+}
+interface DesktopConnectRequest extends ConnectDesktopOptions {
+    baseUrl: string;
+    wsHeaders: Record<string, string>;
+}
+declare class Desktop {
+    private session;
+    private readonly connectRequest;
+    private operationChain;
+    private reconnectPromise;
+    private closed;
+    private constructor();
+    static connect(options: DesktopConnectRequest): Promise<Desktop>;
+    get width(): number;
+    get height(): number;
+    close(): Promise<void>;
+    screenshot(timeout?: number): Promise<Uint8Array>;
+    getFrameVersion(): number;
+    screenshotAfter(frameVersion: number, timeout?: number): Promise<Uint8Array>;
+    moveMouse(x: number, y: number): Promise<void>;
+    mousePress(options?: DesktopPointerOptions): Promise<void>;
+    mouseRelease(options?: DesktopPointerOptions): Promise<void>;
+    click(options?: DesktopPointerOptions): Promise<void>;
+    doubleClick(options?: DesktopDoubleClickOptions): Promise<void>;
+    leftClick(x?: number, y?: number): Promise<void>;
+    middleClick(x?: number, y?: number): Promise<void>;
+    rightClick(x?: number, y?: number): Promise<void>;
+    scroll(steps: number, x?: number, y?: number): Promise<void>;
+    scrollUp(steps?: number, x?: number, y?: number): Promise<void>;
+    scrollDown(steps?: number, x?: number, y?: number): Promise<void>;
+    keyDown(key: string): Promise<void>;
+    keyUp(key: string): Promise<void>;
+    press(keys: string | string[]): Promise<void>;
+    typeText(text: string): Promise<void>;
+    private enqueue;
+    private captureScreenshot;
+    private captureScreenshotAfter;
+    private reconnect;
+    private performReconnect;
+}
+
+interface CreateTunnelOptions {
+    /** Local host/interface to bind. Defaults to `127.0.0.1`. */
+    localHost?: string;
+    /** Local port to bind. Defaults to the remote port. Use `0` for an ephemeral port. */
+    localPort?: number;
+    /** Seconds to wait for each websocket tunnel connection. Defaults to `10`. */
+    connectTimeout?: number;
+}
+interface TunnelAddress {
+    host: string;
+    port: number;
+}
+declare class TcpTunnel {
+    readonly remotePort: number;
+    readonly localHost: string;
+    readonly localPort: number;
+    private readonly baseUrl;
+    private readonly wsHeaders;
+    private readonly server;
+    private readonly connectTimeoutMs;
+    private readonly activeRelays;
+    private closePromise;
+    private constructor();
+    static listen(options: {
+        baseUrl: string;
+        wsHeaders: Record<string, string>;
+        remotePort: number;
+        localHost?: string;
+        localPort?: number;
+        connectTimeout?: number;
+    }): Promise<TcpTunnel>;
+    address(): TunnelAddress;
+    close(): Promise<void>;
+    private handleConnection;
+}
+
+type PtyDataHandler = (data: Uint8Array) => void;
+type PtyExitHandler = (exitCode: number) => void;
+interface PtyConnectionOptions {
+    onData?: PtyDataHandler;
+    onExit?: PtyExitHandler;
+}
+interface CreatePtyOptions extends CreatePtySessionOptions, PtyConnectionOptions {
+}
+declare class Pty {
+    readonly sessionId: string;
+    readonly token: string;
+    private readonly wsUrl;
+    private readonly wsHeaders;
+    private readonly killSession;
+    private socket;
+    private connectPromise;
+    private intentionalDisconnect;
+    private exitCode;
+    private waitSettled;
+    private readonly dataHandlers;
+    private readonly exitHandlers;
+    private readonly waitPromise;
+    private resolveWait;
+    private rejectWait;
+    constructor(options: {
+        sessionId: string;
+        token: string;
+        wsUrl: string;
+        wsHeaders: Record<string, string>;
+        killSession: () => Promise<void>;
+    });
+    onData(handler: PtyDataHandler): () => void;
+    onExit(handler: PtyExitHandler): () => void;
+    connect(): Promise<this>;
+    sendInput(input: string | Uint8Array): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    disconnect(code?: number, reason?: string): void;
+    wait(): Promise<number>;
+    kill(): Promise<void>;
+    private requireOpenSocket;
+    private finishWait;
+    private failWait;
+}
+declare class Sandbox {
+    traceId: string | null;
+    /**
+     * What {@link Sandbox.getOrCreate} did to bind the name: `"created"`,
+     * `"attached"`, or `"resumed"`. `null` for handles from `create` or
+     * `connect`.
+     */
+    readonly bindOutcome: GetOrCreateOutcome | null;
+    private readonly proxy;
+    private ownsSandbox;
+    private lifecycleClient;
+    private lifecycleIdentifier;
+    private sandboxName;
+    constructor(options: SandboxOptions);
+    /**
+     * The server-assigned sandbox ID.
+     *
+     * A handle opened by name (`connect({ sandboxId: name })`) reports the
+     * name until its first server response, then the canonical ID. Handles
+     * from `create` and `getOrCreate` carry the canonical ID from the start.
+     */
+    get sandboxId(): string;
+    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;
+    /** @internal Used by PendingSandbox.ready for a non-owning handle. */
+    _setLifecycleClient(client: SandboxClient): void;
+    /**
+     * Create a new sandbox and return a connected, running handle.
+     *
+     * Covers both fresh sandbox creation and restore-from-snapshot (set
+     * `snapshotId`). With `wait` unset or `true` it blocks until the sandbox
+     * is `Running`: the create is sent with `wait: false` and the sandbox is
+     * polled every two seconds, with `requestTimeout` as the wait budget.
+     *
+     * With `wait: false` it returns a {@link PendingSandbox} at once:
+     * `pending.ready()` waits for it, `pending.status()` looks at it, and
+     * `Sandbox.connect({ sandboxId: pending.sandboxId })` collects it from any
+     * other process. This is the call for requesting many sandboxes ahead of
+     * capacity. `wait: false` cannot be combined with `poolId`.
+     *
+     * **When the wait runs out the sandbox is not deleted.** A
+     * `SandboxPending` is thrown carrying the sandbox id; the sandbox keeps
+     * its place in the queue and starts whenever capacity arrives. Collect it
+     * later with `Sandbox.connect` or delete it to give up. Pass
+     * `cancelOnTimeout: true` for the previous delete-then-throw behaviour,
+     * or `maxPendingSecs` to let the server fail it after a bound.
+     *
+     * When `name` is already claimed, the server rejects the create with
+     * HTTP 409 (`RemoteAPIError`). To attach to the existing sandbox
+     * instead, use {@link Sandbox.getOrCreate}.
+     */
+    static create<O extends CreateAndConnectOptions & Partial<SandboxClientOptions> = CreateAndConnectOptions & Partial<SandboxClientOptions>>(options?: O): Promise<O extends {
+        wait: false;
+    } ? PendingSandbox : Sandbox>;
+    /**
+     * Attach to an existing sandbox and return a connected handle.
+     *
+     * The handle is lazy: when `proxyUrl` is omitted, the sandbox is resolved
+     * on the first request so the handle uses the correct cloud/region ingress
+     * endpoint. Connecting does not verify that the sandbox exists. Does
+     * **not** auto-resume a suspended sandbox — call `sandbox.resume()`
+     * explicitly.
+     */
+    static connect(options: ConnectOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
+    /**
+     * Return the one sandbox bound to `name`. Create it on first use.
+     *
+     * This is the recommended call for an agent session that derives its
+     * sandbox name from its session ID. It declares the intent "this name is
+     * my session's sandbox": when a sandbox already holds the name, the call
+     * attaches to it instead of failing with HTTP 409 the way `create` does.
+     *
+     * The steps, all handled internally:
+     *
+     * 1. `connect` by name — finds the sandbox, running or suspended.
+     * 2. When nothing holds the name, `create` with the given configuration.
+     * 3. When that create loses a race against another caller (HTTP 409),
+     *    connect to the winner.
+     * 4. When the sandbox is still starting (another caller's create is in
+     *    flight), wait until it is `Running`, the same way `create` blocks
+     *    for its own caller.
+     * 5. When the sandbox is suspended, `resume()` it. Disable with
+     *    `resume: false`.
+     *
+     * Concurrent callers that use the same name all converge on the same
+     * sandbox. The configuration options (`image`, `cpus`, ...) apply only
+     * when the call creates a new sandbox; an existing sandbox is returned
+     * as-is, with whatever configuration it already has.
+     *
+     * The returned handle carries the canonical `sandboxId` (not the name)
+     * and records what the call did in `bindOutcome`: `"created"`,
+     * `"attached"`, or `"resumed"`. See {@link GetOrCreateOutcome}.
+     *
+     * For about a second after `terminate()`, the name still resolves and
+     * the sandbox still reports `running`. A `getOrCreate` in that window
+     * attaches to the dying sandbox. When you recreate right after a
+     * terminate, check `status()` after the call, or wait for the old
+     * sandbox to report `terminated` first.
+     *
+     * `poolId` is not accepted: a pool claim cannot carry a name, so a
+     * claimed sandbox could never be found again by a later call. To use a
+     * warm pool, `create` with `poolId` and name the sandbox afterwards
+     * with `client.update(sandboxId, { name })`.
+     *
+     * @param name Sandbox name; unique within the namespace. Derive it
+     *   deterministically from your session ID, for example
+     *   `agent-${sessionId}`.
+     * @param options Create options plus `resume` (default true: resume a
+     *   suspended sandbox before returning). Used only when a new sandbox
+     *   must be created, except connection-level options.
+     * @throws {SandboxError} If the name stays claimed but its sandbox cannot
+     *   be attached to after several attempts (for example, the previous
+     *   holder is stuck terminating), or if a sandbox that is still starting
+     *   does not reach `Running` within `requestTimeout`.
+     * @throws {RemoteAPIError} If the create step fails with a non-409 error.
+     */
+    static getOrCreate(name: string, options?: GetOrCreateOptions & Partial<SandboxClientOptions>): Promise<Sandbox>;
+    /** Get information about a snapshot by ID. No sandbox handle needed. */
+    static getSnapshot(snapshotId: string, options?: Partial<SandboxClientOptions>): Promise<SnapshotInfo>;
+    /** Delete a snapshot by ID. No sandbox handle needed. */
+    static deleteSnapshot(snapshotId: string, options?: Partial<SandboxClientOptions>): Promise<void>;
+    /** List all sandboxes. No sandbox handle needed. */
+    static list(options?: Partial<SandboxClientOptions>): Promise<SandboxInfo[]>;
+    /** List all snapshots in the project. No sandbox handle needed. */
+    static listSnapshots(options?: Partial<SandboxClientOptions>): Promise<SnapshotInfo[]>;
+    private requireLifecycleClient;
+    /** Fetch the current sandbox information from the server on demand. */
+    info(): Promise<Traced<SandboxInfo>>;
+    /**
+     * Fetch the current sandbox status from the server.
+     *
+     * Always hits the network — the value is not cached locally because the
+     * status changes over the sandbox's lifecycle.
+     */
+    status(): Promise<SandboxStatus>;
+    /**
+     * Update this sandbox's properties or resize its resources.
+     *
+     * Resource targets use create's cpus, memoryMb, and diskMb names. Resize
+     * waits by default; wait=false returns admission. Timeout does not cancel it.
+     * Wait, timeout, and pollInterval are ignored on non-resource updates.
+     * A no-op returns current resources with absent or earlier resize metadata.
+     *
+     * Naming an ephemeral sandbox makes it non-ephemeral and enables
+     * suspend/resume. For `network`, omit to keep the current policy, pass an
+     * object to replace it, or pass `null` to clear it to unrestricted egress.
+     */
+    update(options: UpdateSandboxOptions): Promise<Traced<SandboxInfo>>;
+    /** Wait for this exact resize generation without submitting another update. */
+    waitForResourceResize(generation: number, options?: ResourceResizeWaitOptions): Promise<Traced<SandboxInfo>>;
+    /**
+     * Suspend this sandbox.
+     *
+     * By default blocks until the sandbox is fully `Suspended`. Pass
+     * `{ wait: false }` for fire-and-return.
+     */
+    suspend(options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * Resume this sandbox.
+     *
+     * By default blocks until the sandbox is `Running` and refreshes this
+     * handle's cached proxy routing. Rare transient proxy errors may still occur
+     * immediately after resume.
+     *
+     * Pass `{ wait: false }` for fire-and-return. That mode does not refresh
+     * cached proxy routing on this handle; use the default wait behavior for
+     * immediate follow-up operations, or wait until the sandbox is running and
+     * reconnect before issuing process/file/PTY operations.
+     */
+    resume(options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * Poll until the sandbox leaves `Suspending`.
+     *
+     * The lifecycle API rejects resume while a suspend is still in progress,
+     * so `getOrCreate` must wait for the suspend to settle before it can
+     * resume the sandbox.
+     */
+    private waitOutSuspending;
+    /**
+     * Poll until the sandbox is `Running` with routing info, then rebind this
+     * handle's cached proxy routing. Shared by `resume()` and the
+     * `getOrCreate` path that attaches to a still-starting sandbox.
+     */
+    private refreshRoutingWhenRunning;
+    /** Live-copy this running sandbox. */
+    copy(options?: CopySandboxOptions): Promise<Traced<CopySandboxResponse>>;
+    /**
+     * Attach a registered file system to this running sandbox at `mountPath`.
+     *
+     * Returns the updated sandbox info; the new mount appears in
+     * `fileSystems`. `options.snapshotId` pins the mount to a specific
+     * filesystem snapshot and requires `options.readOnly: true`.
+     */
+    attachFileSystem(fileSystemId: string, mountPath: string, options?: AttachFileSystemOptions): Promise<Traced<SandboxInfo>>;
+    /**
+     * Detach the file system mounted at `mountPath` from this running
+     * sandbox.
+     *
+     * Returns the updated sandbox info with the mount removed from
+     * `fileSystems`.
+     */
+    detachFileSystem(mountPath: string): Promise<Traced<SandboxInfo>>;
+    /** List the file systems currently mounted into this sandbox. */
+    listFileSystems(): Promise<Traced<FileSystemMount[]>>;
+    /**
+     * Create a checkpoint of this sandbox and wait for it to be locally ready.
+     *
+     * By default blocks until the checkpoint is resumable and returns
+     * `SnapshotInfo`. Pass `{ wait: false }` to fire-and-return
+     * (returns `undefined`).
+     */
+    checkpoint(options?: CheckpointOptions): Promise<Traced<SnapshotInfo> | undefined>;
+    /**
+     * List snapshots taken from this sandbox.
+     */
+    listSnapshots(): Promise<Traced<SnapshotInfo[]>>;
+    /** Close the proxy connection. The sandbox keeps running. */
+    close(): void;
+    /** Terminate the sandbox and release all resources. */
+    terminate(): Promise<void>;
+    /**
+     * Run a command to completion and return its output.
+     *
+     * Uses a single streaming `POST /api/v1/processes/run` request that starts
+     * the process, streams output, and delivers the exit code over one connection.
+     */
+    run(command: string, options?: RunOptions): Promise<Traced<CommandResult>>;
+    /**
+     * Start a process in the sandbox without waiting for it to exit.
+     *
+     * Returns a `ProcessInfo` with the assigned `pid`. Use `getProcess()` to
+     * poll status, or `followStdout()` / `followOutput()` to stream output
+     * until the process exits. Use `run()` instead to block until completion
+     * and get combined output in one call.
+     */
+    startProcess(command: string, options?: StartProcessOptions): Promise<Traced<ProcessInfo>>;
+    /** List all processes (running and exited) tracked by the sandbox daemon. */
+    listProcesses(): Promise<Traced<ProcessInfo[]>>;
+    /** Read persisted logs for this sandbox from the log service. */
+    getLogs(options?: GetSandboxLogsOptions): Promise<Traced<SandboxLogsResponse>>;
+    /** List processes available as persisted-log filters for this sandbox. */
+    listLogProcesses(): Promise<Traced<SandboxProcessLogFiltersResponse>>;
+    /** Get current status and metadata for a process. `process` is a PID or process name given on creation. */
+    getProcess(process: number | string): Promise<Traced<ProcessInfo>>;
+    /** Send SIGKILL to a process (or stop a managed process). `process` is a PID or process name given on creation. */
+    killProcess(process: number | string): Promise<void>;
+    /** Restart a managed process. `process` is a PID or process name given on creation. */
+    restartProcess(process: number | string): Promise<Traced<ProcessInfo>>;
+    /** Send an arbitrary signal (e.g. `15` for SIGTERM, `9` for SIGKILL). `process` is a PID or process name given on creation. */
+    sendSignal(process: number | string, signal: number): Promise<Traced<SendSignalResponse>>;
+    /** Write bytes to a process's stdin (must be started with `stdinMode: StdinMode.PIPE`). `process` is a PID or process name given on creation. */
+    writeStdin(process: number | string, data: Uint8Array): Promise<void>;
+    /** Close a process's stdin pipe, signalling EOF. `process` is a PID or process name given on creation. */
+    closeStdin(process: number | string): Promise<void>;
+    /** Return all captured stdout lines produced so far. `process` is a PID or process name given on creation. */
+    getStdout(process: number | string): Promise<Traced<OutputResponse>>;
+    /** Return all captured stderr lines produced so far. `process` is a PID or process name given on creation. */
+    getStderr(process: number | string): Promise<Traced<OutputResponse>>;
+    /** Return all captured stdout+stderr lines produced so far. `process` is a PID or process name given on creation. */
+    getOutput(process: number | string): Promise<Traced<OutputResponse>>;
+    /** Stream stdout events until the process exits. `process` is a PID or process name given on creation. */
+    followStdout(process: number | string, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<OutputEvent>;
+    /** Stream stderr events until the process exits. `process` is a PID or process name given on creation. */
+    followStderr(process: number | string, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<OutputEvent>;
+    /** Stream combined stdout+stderr events until the process exits. `process` is a PID or process name given on creation. */
+    followOutput(process: number | string, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<OutputEvent>;
+    /** Read a file from the sandbox and return its raw bytes. */
+    readFile(path: string): Promise<Traced<Uint8Array>>;
+    /** Write raw bytes to a file in the sandbox, creating it if it does not exist. */
+    writeFile(path: string, content: Uint8Array): Promise<void>;
+    /** Delete a file from the sandbox. */
+    deleteFile(path: string): Promise<void>;
+    /** List the contents of a directory in the sandbox. */
+    listDirectory(path: string): Promise<Traced<ListDirectoryResponse>>;
+    /** Create an interactive PTY session. Returns a `sessionId` and `token` for WebSocket connection via `connectPty()`. */
+    createPtySession(options: CreatePtySessionOptions): Promise<Traced<PtySessionInfo>>;
+    /** Create a PTY session and connect to it immediately. Cleans up the session if the WebSocket connection fails. */
+    createPty(options: CreatePtyOptions): Promise<Pty>;
+    /** Attach to an existing PTY session by ID and token and return a connected `Pty` handle. */
+    connectPty(sessionId: string, token: string, options?: PtyConnectionOptions): Promise<Pty>;
+    /** Open a TCP tunnel to a port inside the sandbox and return the local listener. */
+    createTunnel(remotePort: number, options?: CreateTunnelOptions): Promise<TcpTunnel>;
+    /** Connect to a sandbox VNC session for programmatic desktop control. */
+    connectDesktop(options?: ConnectDesktopOptions): Promise<Desktop>;
+    /**
+     * Poll the in-sandbox daemon until `127.0.0.1:port` accepts a TCP connection.
+     * Uses `bash`'s `/dev/tcp` builtin via `processes/run` — no extra deps in
+     * the sandbox image. `bash` is present on every image we ship.
+     */
+    private waitForPortReady;
+    ptyWsUrl(sessionId: string, token: string): string;
+    /** Check the sandbox daemon health. */
+    health(): Promise<Traced<HealthResponse>>;
+    /** Get sandbox daemon info (version, uptime, process counts). */
+    daemonInfo(): Promise<Traced<DaemonInfo>>;
+}
+
+/** @internal How a client binds a handle it issued. */
+interface PendingSandboxBinding {
+    client: SandboxClient;
+    proxyUrl?: string;
+    requestTimeout?: number;
+    requestedName?: string | null;
+    ownsSandbox: boolean;
+    traceId: string;
+}
+/**
+ * A sandbox requested with `wait: false`: the handle returned by
+ * `Sandbox.create({ wait: false })` / `SandboxClient.create({ wait: false })`.
+ *
+ * The sandbox is durable and starts whenever capacity allows. Collect it
+ * with {@link PendingSandbox.ready}, look at it with
+ * {@link PendingSandbox.status}, or from any other process with
+ * `Sandbox.connect({ sandboxId })` (which waits while it is pending) or
+ * `client.list()`. `pendingReason` is `scheduling` at create time; the
+ * capacity reasons appear after the first scheduler pass.
+ */
+declare class PendingSandbox implements PendingSandboxRecord {
+    private readonly binding;
+    readonly sandboxId: string;
+    readonly name?: string;
+    readonly state: SandboxStatus;
+    readonly pendingReason?: string;
+    readonly routingHint?: string;
+    readonly ingressEndpoint?: string;
+    readonly sandboxUrl?: string;
+    readonly reason?: string;
+    readonly terminationReason?: string;
+    readonly errorDetails?: unknown;
+    /** W3C trace id of the create request. */
+    readonly traceId: string;
+    /** @internal */
+    constructor(record: PendingSandboxRecord, binding: PendingSandboxBinding);
+    /** Fetch the sandbox's current state with one `GET`. */
+    status(): Promise<Traced<SandboxInfo>>;
+    /**
+     * Wait for the sandbox to be running and return a connected `Sandbox`.
+     *
+     * Polls `GET /sandboxes/{id}` every `pollInterval` seconds (default 2).
+     * Call it again after a `SandboxPending` to keep waiting.
+     *
+     * @throws {SandboxPending} `timeout` elapsed while the sandbox was still
+     *   pending. It keeps its place in the queue; the error carries
+     *   `sandboxId` and `pendingReason`.
+     * @throws {SandboxError} The sandbox settled somewhere else: `terminated`
+     *   or `failed` (`reason` is the server's, such as `no_capacity` or
+     *   `cancelled`), or `suspended`.
+     */
+    ready(options?: ReadyOptions): Promise<Sandbox>;
+}
+
+/**
+ * Client for managing TensorLake sandboxes, pools, and snapshots.
+ *
+ * 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 native;
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly organizationId;
+    private readonly projectId;
+    private readonly namespace;
+    private readonly requestTimeoutMs;
+    /** @internal Pass `true` to suppress the deprecation warning when used by `Sandbox.create()` / `Sandbox.connect()`. */
+    constructor(options?: SandboxClientOptions, _internal?: boolean);
+    /**
+     * Create an API-key client for TensorLake Cloud. Ingress selects the authorized
+     * organization/project; explicit scope options are forwarded only as compatibility headers.
+     */
+    static forCloud(options?: {
+        apiKey?: string;
+        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;
+    /** 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.
+     *
+     * With `wait` unset or `true` the server waits for readiness for at most
+     * the request timeout and answers the blocking create's record (`status`
+     * may already be `running`); this is the wire behaviour unchanged. With
+     * `wait: false` the server answers as soon as the sandbox is durable and
+     * this returns a {@link PendingSandbox} at once: `pending.ready()` waits
+     * for it, `pending.status()` looks at it, and `connect(sandboxId)`
+     * collects it from any other process. Give the sandbox a `name` when a
+     * retry of this call must not create a second one: a repeated name is an
+     * HTTP 409, and `Sandbox.getOrCreate` resolves it. Use
+     * `createAndConnect()` for a blocking, ready-to-use handle.
+     */
+    create<O extends CreateSandboxOptions = CreateSandboxOptions>(options?: O): Promise<O extends {
+        wait: false;
+    } ? PendingSandbox : Traced<CreateSandboxResponse>>;
+    /**
+     * @internal Send the create with `wait: false` and return the pending
+     * handle, bound to this client so `ready()` / `status()` work.
+     */
+    requestPending(options: CreateSandboxOptions | undefined, binding: {
+        proxyUrl?: string;
+        requestTimeout?: number;
+        ownsSandbox: boolean;
+    }): Promise<PendingSandbox>;
+    /** @internal Implementation of `PendingSandbox.ready`. */
+    _ready(sandboxId: string, binding: PendingSandboxBinding, options?: ReadyOptions): Promise<Sandbox>;
+    /**
+     * Poll `get` every `pollInterval` seconds until the sandbox leaves
+     * `pending` or `timeout` elapses, resolving with the last observation.
+     * Never rejects for a timeout and never deletes.
+     */
+    private waitForSandbox;
+    /** Turn the last observed sandbox state into a handle or an error. */
+    private settleWait;
+    /**
+     * Routing for a lazy `connect` handle. A sandbox that is still pending is
+     * waited on here rather than failing: readiness is a property of the
+     * sandbox, not of the create call that requested it.
+     */
+    private resolveRoutingInfo;
+    /** @internal Build the create wire body; shared by `create` and `createAndConnect`. */
+    static buildCreateRequestBody(options?: CreateSandboxOptions): Record<string, unknown>;
+    /** Get current state and metadata for a sandbox by ID. */
+    get(sandboxId: string): Promise<Traced<SandboxInfo>>;
+    /** List all sandboxes in the namespace. */
+    list(): Promise<Traced<SandboxInfo[]>>;
+    /**
+     * List archived (terminated) sandboxes in the namespace.
+     *
+     * Archived sandboxes are terminated sandboxes parked in the server's
+     * archived sandboxes store until the server-configured TTL expires.
+     */
+    listArchived(options?: ListArchivedSandboxesOptions): Promise<Traced<ListArchivedSandboxesResponse>>;
+    /** Get a single archived sandbox by id. */
+    getArchived(sandboxId: string): Promise<Traced<ArchivedSandboxInfo>>;
+    /** Read persisted logs for a sandbox. */
+    getLogs(sandboxId: string, options?: GetSandboxLogsOptions): Promise<Traced<SandboxLogsResponse>>;
+    /** List sandbox processes available as persisted-log filters. */
+    listLogProcesses(sandboxId: string): Promise<Traced<SandboxProcessLogFiltersResponse>>;
+    /**
+     * Update properties or resize a Running Cloud Hypervisor sandbox.
+     * Resource names match create. Resize waits by default; wait=false returns
+     * admission. Timeout leaves the resize running and reports its generation.
+     * Wait, timeout, and pollInterval are ignored on non-resource updates.
+     * A no-op returns current resources with absent or earlier resize metadata.
+     */
+    update(sandboxId: string, options: UpdateSandboxOptions): Promise<Traced<SandboxInfo>>;
+    /** Wait for this exact generation. Timeout leaves the resize running. */
+    waitForResourceResize(sandboxId: string, generation: number, options?: ResourceResizeWaitOptions): Promise<Traced<SandboxInfo>>;
+    /** Get the current proxy port settings for a sandbox. */
+    getPortAccess(sandboxId: string): Promise<SandboxPortAccess>;
+    /** Add one or more user ports to the sandbox proxy allowlist. */
+    exposePorts(sandboxId: string, ports: number[], options?: {
+        allowUnauthenticatedAccess?: boolean;
+    }): Promise<SandboxInfo>;
+    /** Remove one or more user ports from the sandbox proxy allowlist. */
+    unexposePorts(sandboxId: string, ports: number[]): Promise<SandboxInfo>;
+    /** Terminate and delete a sandbox. */
+    delete(sandboxId: string): Promise<void>;
+    /**
+     * Suspend a named sandbox, preserving its state for later resume.
+     *
+     * Only sandboxes created with a `name` can be suspended; ephemeral sandboxes
+     * 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.
+     */
+    suspend(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * Resume a suspended sandbox and bring it back to `Running`.
+     *
+     * 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.
+     */
+    resume(sandboxId: string, options?: SuspendResumeOptions): Promise<void>;
+    /**
+     * Attach a registered file system to a running sandbox at `mountPath`.
+     *
+     * The mount completes asynchronously on the dataplane; the returned
+     * `SandboxInfo` already reflects the new entry in `fileSystems`.
+     *
+     * `options.snapshotId` pins the mount to a specific filesystem snapshot
+     * and requires `options.readOnly: true`.
+     */
+    attachFileSystem(sandboxId: string, fileSystemId: string, mountPath: string, options?: AttachFileSystemOptions): Promise<Traced<SandboxInfo>>;
+    /**
+     * Detach the file system mounted at `mountPath` from a running sandbox.
+     *
+     * The unmount completes asynchronously on the dataplane; the returned
+     * `SandboxInfo` already reflects the removed `fileSystems` entry.
+     */
+    detachFileSystem(sandboxId: string, mountPath: string): Promise<Traced<SandboxInfo>>;
+    /**
+     * Claim a warm sandbox from a pool, creating one if no warm containers are
+     * available. Claim-specific file systems are ready before the sandbox is
+     * reported as running.
+     */
+    claim(poolId: string, options?: ClaimSandboxOptions): Promise<Traced<CreateSandboxResponse>>;
+    /**
+     * Live-copy a running sandbox.
+     *
+     * The server creates `times` running copies from the source sandbox. Partial
+     * responses can include failed copies; inspect each returned sandbox's
+     * `status` and `reason`.
+     */
+    copy(sandboxId: string, options?: CopySandboxOptions): Promise<Traced<CopySandboxResponse>>;
+    /**
+     * Request a snapshot of a running sandbox's filesystem.
+     *
+     * This call **returns immediately** with a `snapshotId` and `in_progress`
+     * status — the snapshot is created asynchronously. Poll `getSnapshot()` until
+     * `local_ready`, `completed`, or `failed`, or use `snapshotAndWait()` to
+     * block automatically.
+     */
+    snapshot(sandboxId: string, options?: SnapshotOptions): Promise<CreateSnapshotResponse>;
+    /** Get current status and metadata for a snapshot by ID. */
+    getSnapshot(snapshotId: string): Promise<Traced<SnapshotInfo>>;
+    /** List all snapshots in the namespace. */
+    listSnapshots(): Promise<Traced<SnapshotInfo[]>>;
+    /** Delete a snapshot by ID. */
+    deleteSnapshot(snapshotId: string): Promise<void>;
+    /**
+     * Create a snapshot and block until it is locally ready.
+     *
+     * Combines `snapshot()` with polling `getSnapshot()` until `local_ready`
+     * or `completed`. Pass `{ waitUntil: "completed" }` when durable
+     * `snapshotUri` metadata is required.
+     */
+    snapshotAndWait(sandboxId: string, options?: SnapshotAndWaitOptions): Promise<Traced<SnapshotInfo>>;
+    /** Create a new sandbox pool with warm pre-booted containers. */
+    createPool(options: CreatePoolOptions): Promise<CreateSandboxPoolResponse>;
+    /** Get current state and metadata for a sandbox pool by ID. */
+    getPool(poolId: string): Promise<SandboxPoolInfo>;
+    /** List all sandbox pools in the namespace. */
+    listPools(): Promise<Traced<SandboxPoolInfo[]>>;
+    /**
+     * Replace a pool configuration. Omit `network` to keep the pool's current
+     * network policy, set it to replace the policy, or pass `null` to remove the
+     * policy entirely. On a change the service recycles the pool's unclaimed
+     * warm containers onto the new policy, while containers already claimed by
+     * sandboxes keep the policy they booted with. CPU, memory, disk, image, and
+     * entrypoint changes likewise recycle unclaimed warm containers
+     * asynchronously. If suitable capacity is unavailable, stale warm
+     * containers are not used as a fallback.
+     */
+    updatePool(poolId: string, options: UpdatePoolOptions): Promise<SandboxPoolInfo>;
+    /** 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, requestTimeout?: number, explicitProxyUrl?: string): Sandbox;
+    /**
+     * Create a sandbox, wait for it to reach `Running`, and return a connected handle.
+     *
+     * This is `create({ wait: false })` followed by `PendingSandbox.ready()`
+     * polling every `pollInterval` seconds, with `requestTimeout` as the wait
+     * budget, in one call. The returned `Sandbox` auto-terminates when
+     * `terminate()` is called.
+     *
+     * **When the wait runs out the sandbox is not deleted.** A `SandboxPending`
+     * is thrown with the sandbox id, and the sandbox keeps its place in the
+     * queue and starts whenever capacity arrives; `connect` with that id to
+     * collect it, or `delete` it to give up. Pass
+     * `cancelOnTimeout: true` for the previous behaviour (delete, then throw
+     * `SandboxError`), or set `maxPendingSecs` to let the server fail it after
+     * a bound. A pool claim (`poolId`) answers from the server-side wait; a
+     * claim that is still starting is then waited on the same way.
+     */
+    createAndConnect(options?: CreateAndConnectOptions): Promise<Sandbox>;
+}
+
+declare class CloudClient {
+    private readonly transport;
+    private readonly organizationId?;
+    private readonly projectId?;
+    private readonly namespace;
+    constructor(options?: CloudClientOptions);
+    static forCloud(options?: CloudClientOptions): CloudClient;
+    close(): void;
+    upsertApplication(manifest: ApplicationManifest, codeZip: BinaryPayload, upgradeRunningRequests?: boolean): Promise<void>;
+    deleteApplication(applicationName: string): Promise<void>;
+    deleteSandboxImage(imageName: string): Promise<void>;
+    /**
+     * Look up a registered sandbox image (template) by its registered name.
+     *
+     * Returns the template, or `null` when no image with that name exists.
+     * API-key clients may omit organization/project IDs and use the
+     * token-scoped Platform API route directly. Explicit scope remains
+     * available for PAT callers.
+     */
+    findSandboxImageByName(imageName: string, options?: {
+        organizationId?: string;
+        projectId?: string;
+    }): Promise<SandboxTemplate | null>;
+    /**
+     * List all registered sandbox images (templates), following pagination to
+     * the end. API-key clients may omit organization/project IDs and use the
+     * token-scoped Platform API route directly.
+     */
+    listSandboxImages(options?: {
+        organizationId?: string;
+        projectId?: string;
+    }): Promise<SandboxTemplate[]>;
+    applications(): Promise<ApplicationSummary[]>;
+    applicationManifest(applicationName: string): Promise<ApplicationManifest>;
+    runRequest(applicationName: string, inputs?: RequestInput[]): Promise<string>;
+    waitOnRequestCompletion(applicationName: string, requestId: string): Promise<void>;
+    requestMetadata(applicationName: string, requestId: string): Promise<RequestMetadata>;
+    requestOutput(applicationName: string, requestId: string): Promise<RequestOutput>;
+    listSecrets(options?: {
+        organizationId?: string;
+        projectId?: string;
+        pageSize?: number;
+    }): Promise<SecretsList>;
+    getSecret(secretId: string, options?: {
+        organizationId?: string;
+        projectId?: string;
+    }): Promise<Secret>;
+    upsertSecrets(secrets: NewSecret | NewSecret[], options?: {
+        organizationId?: string;
+        projectId?: string;
+    }): Promise<UpsertSecretResponse>;
+    deleteSecret(secretId: string, options?: {
+        organizationId?: string;
+        projectId?: string;
+    }): Promise<void>;
+    private upsertSecret;
+    startImageBuild(buildServicePath: string, request: StartImageBuildRequest): Promise<BuildInfo>;
+    createApplicationBuild(buildServicePath: string, request: CreateApplicationBuildRequest, imageContexts: ApplicationBuildContext[]): Promise<ApplicationBuildResponse>;
+    applicationBuildInfo(buildServicePath: string, applicationBuildId: string): Promise<ApplicationBuildResponse>;
+    cancelApplicationBuild(buildServicePath: string, applicationBuildId: string): Promise<ApplicationBuildResponse>;
+    buildInfo(buildServicePath: string, buildId: string): Promise<BuildInfo>;
+    cancelBuild(buildServicePath: string, buildId: string): Promise<void>;
+    streamBuildLogs(buildServicePath: string, buildId: string, signal?: AbortSignal): AsyncIterable<BuildLogEntry>;
+    private runMultipartRequest;
+    private namespacePath;
+    private existingApplicationPublicEndpointId;
+    private platformProjectPath;
+    private secretCollectionPath;
+}
+
+/** Shared command runner for the separately installed local mount daemon. */
+declare class MountCli {
+    private readonly command;
+    private readonly envOverrides;
+    private binary;
+    constructor(command: "fs" | "git", envOverrides: Record<string, string>);
+    private findCli;
+    protected run(args: string[], timeoutMs?: number): Promise<string>;
+}
+
+interface RepositoryMountOptions {
+    /** Stateless read-only view; cannot be combined with publish or workspace. */
+    readOnly?: boolean;
+    /** Publish each explicit snapshot onto the mounted branch. */
+    publish?: boolean;
+    /** Resume a private workspace; cannot be combined with publish or readOnly. */
+    workspace?: string;
+}
+interface RepositoryUnmountOptions {
+    /** Delete the private server workspace after detaching. Defaults to false. */
+    deleteWorkspace?: boolean;
+    /** Drop unpublished local state. Defaults to false. */
+    discard?: boolean;
+}
+/** Stable fields from `tl git status --json`, with the full payload in raw. */
+interface RepositoryMountStatus {
+    path: string;
+    repository: string | null;
+    reference: string | null;
+    workspaceId: string | null;
+    state: string | null;
+    localChanges: boolean | null;
+    raw: Record<string, unknown>;
+}
+/** @internal CLI implementation; obtain mounts through RepositoryClient. */
+declare class GitCli extends MountCli {
+    constructor(envOverrides: Record<string, string>);
+    mount(target: string, localPath: string, options?: RepositoryMountOptions): Promise<RepositoryMount>;
+    unmount(localPath: string, options?: RepositoryUnmountOptions): Promise<void>;
+    status(localPath?: string): Promise<RepositoryMountStatus>;
+    snapshot(path: string, message?: string): Promise<void>;
+    sync(path: string, target?: string): Promise<void>;
+    rebase(path: string, target: string, failOnConflict: boolean): Promise<void>;
+    promote(path: string, branch: string, merge: boolean): Promise<void>;
+    prefetch(path: string): Promise<void>;
+}
+/** A repository mounted on the machine running Node.js via the `tl` CLI daemon. */
+declare class RepositoryMount {
+    private readonly cli;
+    /** Initial source (`repo[:ref][//subtree]`); sync/rebase can change the base. */
+    readonly target: string;
+    readonly path: string;
+    readonly readOnly: boolean;
+    /** @internal Obtain instances via RepositoryClient.mount(). */
+    constructor(cli: GitCli, 
+    /** Initial source (`repo[:ref][//subtree]`); sync/rebase can change the base. */
+    target: string, path: string, readOnly: boolean);
+    /** Inspect workspace state, pending changes, and daemon diagnostics. */
+    status(): Promise<RepositoryMountStatus>;
+    /** Materialize autosaved edits as a commit; publish mounts also update their branch. */
+    snapshot(message?: string): Promise<void>;
+    /** Refresh the current source, or switch an unsnapshotted workspace to a new base. */
+    sync(target?: string): Promise<void>;
+    /** Replay snapshots and pending edits onto another base. Conflicts become diff3 markers by default. */
+    rebase(target: string, options?: {
+        failOnConflict?: boolean;
+    }): Promise<void>;
+    /** Publish the workspace to a branch; merge allows landing when the branch moved. */
+    promote(branch: string, options?: {
+        merge?: boolean;
+    }): Promise<void>;
+    /** Download and verify the mounted working set for network-free reads. */
+    prefetch(): Promise<void>;
+    /** Detach, retaining the private workspace and unpublished state unless explicitly requested. */
+    unmount(options?: RepositoryUnmountOptions): Promise<void>;
+}
+
+interface RepositoryClientOptions {
+    apiUrl?: string;
+    apiKey?: string;
+    /** @deprecated Scope is selected by ingress for SDK API keys; used only by local `tl` mounts. */
+    organizationId?: string;
+    /** @deprecated Scope is selected by ingress for SDK API keys; used only by local `tl` mounts. */
+    projectId?: string;
+    requestTimeout?: number;
+    timeoutMs?: number;
+}
+interface GitRepository {
+    name: string;
+    fullName: string;
+    defaultBranch: string;
+    status: string;
+}
+interface RepositoryHandle {
+    repo: string;
+    url: string;
+    baseRepo?: string;
+}
+interface GitRef {
+    name: string;
+    oid: string;
+}
+interface Branch {
+    name: string;
+    refName: string;
+    oid: string;
+}
+interface RepositoryInfo {
+    repo: string;
+    url: string;
+    branches: Branch[];
+    refs: GitRef[];
+}
+interface GitCredential {
+    token: string;
+    tokenType: string;
+    expiresAt: string;
+    gitUsername: string;
+    repoPattern: string;
+    scopes: string[];
+}
+interface CommitJobReadBack {
+    done: number;
+    total: number;
+}
+interface CommitJobError {
+    kind: string;
+    message: string;
+    retryable: boolean;
+}
+interface CommitJobStatus {
+    jobId: string;
+    state: string;
+    phase?: string;
+    readBack?: CommitJobReadBack;
+    commit?: string;
+    tree?: string;
+    refName?: string;
+    parent?: string;
+    created?: boolean;
+    error?: CommitJobError;
+}
+interface PushReport {
+    commit: string;
+    tree: string;
+    refName: string;
+    created: boolean;
+    files: number;
+    bytesTotal: number;
+    chunksTotal: number;
+    chunksUploaded: number;
+    bytesUploaded: number;
+    fileBlobOids: Array<[string, string]>;
+}
+interface PushWorktreeOptions {
+    path?: string;
+    branch?: string;
+    message?: string;
+    expectOid?: string;
+}
+interface MergeEntry {
+    mode: number;
+    oid: string;
+}
+interface MergeConflict {
+    path: string;
+    kind: string;
+    potential: boolean;
+    ours?: MergeEntry;
+    base?: MergeEntry;
+    theirs?: MergeEntry;
+}
+interface MergeStats {
+    treesRead: number;
+    entriesCompared: number;
+    blobsMerged: number;
+    wallMs: number;
+}
+interface MergeReport {
+    ours: string;
+    theirs: string;
+    mergeBase?: string;
+    clean: boolean;
+    fastForward: boolean;
+    alreadyMerged: boolean;
+    changedPaths: number;
+    conflicts: MergeConflict[];
+    stats: MergeStats;
+    commit?: string;
+    fastForwarded: boolean;
+}
+interface MergeOptions {
+    preflight?: boolean;
+    deep?: boolean;
+    materialize?: boolean;
+    message?: string;
+    base?: string;
+}
+interface ConflictTerm {
+    mode: number;
+    oid: string;
+}
+interface ConflictPath {
+    path: string;
+    kind: string;
+    terms: Array<ConflictTerm | null>;
+}
+interface MergeConflictRecord {
+    version: number;
+    oursCommit: string;
+    theirsCommit: string;
+    baseCommit?: string;
+    paths: ConflictPath[];
+    truncatedPaths: number;
+}
+interface OperationRef {
+    name: string;
+    old?: string;
+    new?: string;
+}
+interface Operation {
+    opId: string;
+    repo: string;
+    network?: string;
+    parentOpId?: string;
+    actor: string;
+    atSecs: number;
+    kind: string;
+    result: string;
+    refs: OperationRef[];
+    packIds: string[];
+    oldPackIds: string[];
+    relatedRepo?: string;
+    status?: string;
+    oldPackCount: number;
+    objectCount: number;
+    packBytes: number;
+}
+declare class RepositoryClient {
+    private readonly native;
+    private readonly requestTimeoutMs;
+    private readonly cli;
+    constructor(options?: RepositoryClientOptions);
+    static forCloud(options?: RepositoryClientOptions): RepositoryClient;
+    static fromEnv(): Promise<RepositoryClient>;
+    close(): void;
+    /**
+     * Mount `repo[:branch|tag|full-commit][//subtree]` to a local directory.
+     * Requires the separately installed `tl` CLI with mount support. Mounts
+     * live on the machine running Node.js and must be explicitly unmounted.
+     */
+    mount(target: string, localPath: string, options?: RepositoryMountOptions): Promise<RepositoryMount>;
+    /** Detach a local repository mount, optionally deleting its private workspace. */
+    unmount(localPath: string, options?: RepositoryUnmountOptions): Promise<void>;
+    /** Inspect a local mount; defaults to the mount containing the current directory. */
+    mountStatus(localPath?: string): Promise<RepositoryMountStatus>;
+    url(repo: string): Promise<string>;
+    create(repo: string, options?: {
+        defaultBranch?: string;
+    }): Promise<Traced<RepositoryHandle>>;
+    list(): Promise<Traced<GitRepository[]>>;
+    delete(repo: string): Promise<void>;
+    fork(repo: string, baseRepo: string): Promise<Traced<RepositoryHandle>>;
+    archive(repo: string): Promise<void>;
+    restore(repo: string): Promise<void>;
+    info(repo: string): Promise<Traced<RepositoryInfo>>;
+    branches(repo: string): Promise<Traced<Branch[]>>;
+    refs(repo: string): Promise<Traced<GitRef[]>>;
+    deleteBranch(repo: string, branch: string): Promise<void>;
+    operations(repo: string): Promise<Traced<Operation[]>>;
+    credential(repo?: string): Promise<GitCredential>;
+    commitStatus(repo: string, jobId: string): Promise<Traced<CommitJobStatus>>;
+    pushWorktree(repo: string, options?: PushWorktreeOptions): Promise<Traced<PushReport>>;
+    merge(repo: string, ours: string, theirs: string, options?: MergeOptions): Promise<Traced<MergeReport>>;
+    commitConflicts(repo: string, commit: string): Promise<Traced<MergeConflictRecord> | null>;
+    private tracedJson;
+}
+
+/**
+ * Compatibility helpers for Artifact Storage filesystems.
+ *
+ * New code should use {@link FilesystemClient} directly. These helpers retain
+ * the original create/list/delete API and authenticate with
+ * `TENSORLAKE_API_KEY`; ingress selects the project scope.
+ *
+ * To mount a registered file system into a sandbox, pass
+ * `fileSystems` to `Sandbox.create()` (including warm-pool claims) or call
+ * `sandbox.attachFileSystem()` / `sandbox.detachFileSystem()` on a
+ * running sandbox.
+ */
+/** Register a new file system for the current project. */
+declare function createFileSystem(name: string, description?: string, options?: {
+    region?: string;
+}): Promise<FileSystem>;
+/** List all registered file systems for the current project. */
+declare function listFileSystems(): Promise<FileSystem[]>;
+/** Delete a registered file system by its id (e.g. `file_system_...`). */
+declare function deleteFileSystem(fileSystemId: string): Promise<void>;
+
+/** One filesystem as returned by listing/point-read endpoints. */
+interface FilesystemInfo {
+    name: string;
+    fullName: string;
+    status: string;
+    kind: string;
+}
+/** Remote status of a filesystem: identity plus current head. */
+interface FilesystemStatus {
+    name: string;
+    status: string;
+    /**
+     * Current native version id; null for an empty filesystem that has never
+     * been written to.
+     */
+    versionId: string | null;
+    /** Server-side movement counter for the live version, when reported. */
+    generation: number | null;
+}
+/** One directory entry from a filesystem listing. */
+interface FileEntry {
+    name: string;
+    /** Path of the entry relative to the filesystem root. */
+    path: string;
+    /** Stable native content identity for the file or directory. */
+    contentId: string;
+    /** Native entry kind. */
+    kind: "file" | "directory" | "symlink";
+    /** Whether a regular file is executable. */
+    executable: boolean;
+    /** Blob size in bytes when cheaply known server-side. */
+    size: number | null;
+    isDir: boolean;
+    isSymlink: boolean;
+}
+/** Bytes plus immutable identity/size returned by one file request. */
+interface FilesystemFileRead {
+    data: Uint8Array;
+    /** Stable native identity for the complete file content. */
+    contentId: string;
+    /** Size of the complete file, even when `data` is a requested range. */
+    size: number;
+}
+interface FilesystemReadOptions {
+    /** Current `main` head when omitted; otherwise one retained snapshot id. */
+    version?: string;
+    /** Half-open byte selection expressed as offset + length. */
+    range?: {
+        offset: number;
+        length: number;
+    };
+}
+/** The durable live version produced by one atomic filesystem publication. */
+interface FilesystemVersion {
+    /** Native version id — pass as `version` to read the filesystem at this point. */
+    versionId: string;
+    /** Version replaced by this publication, or null for the first publication. */
+    previousVersionId: string | null;
+    /** False when the write was a no-op (content identical to the parent). */
+    created: boolean;
+    message: string;
+}
+/** One newly retained native filesystem snapshot. */
+interface FilesystemSnapshot {
+    id: string;
+    message: string;
+}
+/** One explicitly retained native filesystem snapshot. */
+interface FilesystemSnapshotInfo {
+    id: string;
+    createdAt: Date;
+    message: string;
+}
+/**
+ * Status of a local mount as reported by `tl fs status --json`.
+ *
+ * The mount daemon's JSON is versioned independently of this SDK, so only
+ * stable fields are typed; the full payload is preserved in `raw`.
+ */
+interface MountStatus {
+    /** Local mount path. */
+    path: string;
+    /** Filesystem name this mount serves, when reported. */
+    filesystem: string | null;
+    /** Whether the daemon reports the mount as healthy/active. */
+    mounted: boolean;
+    /** Complete parsed JSON payload from the CLI. */
+    raw: Record<string, unknown>;
+}
+declare class FilesystemError extends Error {
+    constructor(message: string);
+}
+declare class FilesystemNotFoundError extends FilesystemError {
+    readonly filesystemName: string;
+    constructor(name: string);
+}
+declare class FileNotFoundInFilesystemError extends FilesystemError {
+    readonly filesystem: string;
+    readonly path: string;
+    constructor(filesystem: string, path: string);
+}
+declare class FilesystemAPIError extends FilesystemError {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+declare class MountError extends FilesystemError {
+    constructor(message: string);
+}
+declare class ReadOnlyMountNotSupportedError extends MountError {
+    constructor();
+}
+declare class CliNotFoundError extends MountError {
+    constructor(detail: string, command?: "fs" | "git mount");
+}
+
+/**
+ * Client for Tensorlake filesystems.
+ *
+ * A filesystem is a durable, versioned file tree that lives in Tensorlake
+ * Cloud. Every write publishes a durable live version; {@link Filesystem.snapshot}
+ * retains the current version permanently. Files can be read at any retained
+ * version, and a filesystem can be mounted to a local path through the `tl`
+ * CLI's FUSE/FSKit daemon.
+ *
+ * Server-side SDK writes hash complete files locally, upload missing bytes
+ * directly to checksum-bound object-store targets, and atomically publish
+ * one durable snapshot. Payload bytes never transit the API service.
+ *
+ * @example
+ * const client = new FilesystemClient();   // env-based auth
+ * const fs = await client.create("my-data");
+ * await fs.writeFile("docs/hello.txt", "hi");
+ * console.log(await fs.readText("docs/hello.txt"));
+ * const snapshot = await fs.snapshot("after first write");
+ *
+ * const mount = await fs.mount("/mnt/my-data"); // requires the `tl` CLI
+ * // ... use it as a normal directory
+ * await mount.unmount();
+ */
+
+interface FilesystemClientOptions {
+    apiKey?: string;
+    apiUrl?: string;
+    /** @deprecated Scope is selected by ingress for SDK API keys; used only by local `tl` mounts. */
+    organizationId?: string;
+    /** @deprecated Scope is selected by ingress for SDK API keys; used only by local `tl` mounts. */
+    projectId?: string;
+    /** @internal Test seam: bypass the native binding loader. */
+    nativeClient?: NativeRepositoryClient;
+}
+/**
+ * Runs `tl fs ...` commands for local mount operations.
+ *
+ * Mounting a filesystem to a local path is served by a FUSE (Linux) / FSKit
+ * (macOS) daemon that ships only inside the Tensorlake CLI, so the SDK drives
+ * mounts by invoking `tl fs mount/unmount/snapshot/status`. Everything else
+ * goes through the Rust core and does not need the CLI.
+ */
+declare class FsCli extends MountCli {
+    constructor(envOverrides: Record<string, string>);
+    mount(filesystem: string, localPath: string, readonly: boolean): Promise<void>;
+    unmount(localPath: string, discard: boolean): Promise<void>;
+    snapshot(localPath: string, message?: string): Promise<void>;
+    status(localPath?: string): Promise<Record<string, unknown>>;
+}
+/** Manages the filesystems of one Tensorlake project. */
+declare class FilesystemClient {
+    private readonly native;
+    private readonly cli;
+    /**
+     * The SDK authenticates with `apiKey` or `TENSORLAKE_API_KEY`. Project scope is selected by
+     * ingress from the API key; no organization/project lookup is performed. Organization/project
+     * options are retained only for the separately installed `tl` CLI used by local mounts.
+     */
+    constructor(options?: FilesystemClientOptions);
+    /** Create a filesystem; region fixes its storage placement. Forks inherit placement. */
+    create(name: string, options?: {
+        region?: string;
+    }): Promise<Filesystem>;
+    /**
+     * Fork a filesystem at its live head or an explicit retained snapshot.
+     * The server shares immutable content and publishes only metadata.
+     */
+    fork(name: string, baseFilesystem: string, snapshot?: string): Promise<Filesystem>;
+    /** Return a handle to an existing filesystem (verifies it exists). */
+    get(name: string): Promise<Filesystem>;
+    /** List all filesystems in the project. */
+    list(): Promise<FilesystemInfo[]>;
+    /** Permanently delete a filesystem and all its snapshots. */
+    delete(name: string): Promise<void>;
+    /**
+     * Mount a filesystem to a local path (requires the `tl` CLI).
+     *
+     * `readonly: true` is not supported for local mounts and throws
+     * {@link ReadOnlyMountNotSupportedError}; use a sandbox read-only mount
+     * (`readOnly: true`) or `tl git mount --ro` instead.
+     */
+    mount(name: string, localPath: string, readonly?: boolean): Promise<FilesystemMount>;
+    /**
+     * Unmount a locally mounted filesystem.
+     *
+     * `discard: true` drops local changes that were not yet uploaded.
+     */
+    unmount(localPath: string, discard?: boolean): Promise<void>;
+    /** Status of a local mount (defaults to the mount containing CWD). */
+    mountStatus(localPath?: string): Promise<MountStatus>;
+}
+type FileData = Uint8Array | string;
+/** Handle to one filesystem; reads/writes go through the Rust core. */
+declare class Filesystem {
+    private readonly client;
+    private readonly native;
+    private readonly cli;
+    readonly name: string;
+    private defaultBranch;
+    /** @internal — obtain instances via `FilesystemClient.create()` / `.get()`. */
+    constructor(client: FilesystemClient, native: NativeRepositoryClient, cli: FsCli, name: string, defaultBranch?: string | null);
+    /**
+     * The filesystem's default branch — the target of every write and the
+     * default version of every read, so writes and `status()` can never
+     * silently disagree on a non-"main" filesystem.
+     */
+    private branch;
+    /** Write one file. Returns the snapshot (version) the write produced. */
+    writeFile(path: string, data: FileData, message?: string): Promise<FilesystemVersion>;
+    /** Write several files (and/or delete paths) in one atomic snapshot. */
+    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<FilesystemVersion>;
+    /**
+     * Stream one local file directly to object storage in bounded parts.
+     * This is the memory-bounded API for multi-GiB files.
+     */
+    writeFileFromPath(path: string, localPath: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Atomically publish local files without loading their complete payloads
+     * into JavaScript or Rust memory.
+     */
+    writeFilesFromPaths(files: Map<string, string> | Record<string, string>, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Move a file or directory without downloading or re-uploading its bytes.
+     * The source removal and destination creation publish as one atomic snapshot.
+     */
+    moveFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Copy a file or directory by reusing immutable content references. No
+     * payload bytes traverse the client, API server, or object store.
+     */
+    copyFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    private publishChanges;
+    /** Delete one file. Returns the durable version the deletion produced. */
+    deleteFile(path: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Return the filesystem's current version as a snapshot.
+     *
+     * Writes publish durable live versions. This retains the current head
+     * permanently in one metadata-only server operation without changing or
+     * copying any content.
+     */
+    snapshot(message?: string): Promise<FilesystemSnapshot>;
+    /** List explicitly retained snapshots without reading filesystem contents. */
+    listSnapshots(): Promise<FilesystemSnapshotInfo[]>;
+    /** Delete one permanent retention point; shared/head-reachable bytes remain. */
+    deleteSnapshot(snapshot: string): Promise<void>;
+    /**
+     * Read a file's bytes at `version` (the current `main` head or a retained
+     * snapshot id; defaults to the filesystem's current head).
+     */
+    readFile(path: string, version?: string): Promise<Uint8Array>;
+    /**
+     * Read bytes and immutable metadata in one request. A range is executed by
+     * Artifact Storage, so callers never download the unrequested remainder.
+     */
+    readFileWithMetadata(path: string, options?: FilesystemReadOptions): Promise<FilesystemFileRead>;
+    /** Read a file as UTF-8 text at `version`. Throws on non-UTF-8 content. */
+    readText(path: string, version?: string): Promise<string>;
+    /** List one directory (non-recursive) at `version`. */
+    listFiles(dirPath?: string, version?: string): Promise<FileEntry[]>;
+    /** Remote status: identity plus the current native version. */
+    status(): Promise<FilesystemStatus>;
+    /**
+     * Mount this filesystem to a local path (requires the `tl` CLI).
+     *
+     * `readonly: true` is not supported for local mounts and throws
+     * {@link ReadOnlyMountNotSupportedError}; use a sandbox read-only mount
+     * (`readOnly: true`) or `tl git mount --ro` instead.
+     */
+    mount(localPath: string, readonly?: boolean): Promise<FilesystemMount>;
+}
+/** A filesystem mounted to a local path via the `tl` CLI daemon. */
+declare class FilesystemMount {
+    private readonly client;
+    private readonly cli;
+    readonly filesystem: string;
+    readonly path: string;
+    readonly readonly: boolean;
+    /** @internal — obtain instances via `FilesystemClient.mount()`. */
+    constructor(client: FilesystemClient, cli: FsCli, filesystem: string, path: string, readonly: boolean);
+    /** Flush pending local changes into a durable snapshot. */
+    snapshot(message?: string): Promise<void>;
+    /** Local mount status as reported by the mount daemon. */
+    status(): Promise<MountStatus>;
+    /** Unmount; `discard: true` drops changes not yet uploaded. */
+    unmount(discard?: boolean): Promise<void>;
+}
+
+/**
+ * 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);
+}
+/**
+ * General sandbox operation error.
+ *
+ * `reason` carries the server's reason when the error describes a sandbox
+ * that failed or terminated: `no_capacity` when a `maxPendingSecs` bound
+ * expired, `cancelled` when a pending sandbox was deleted, or a startup
+ * reason such as `ConfigurationError`. It is undefined for errors that are
+ * not about a sandbox's fate.
+ */
+declare class SandboxError extends SandboxException {
+    readonly reason?: string;
+    readonly sandboxId?: string;
+    constructor(message: string, options?: {
+        reason?: string;
+        sandboxId?: string;
+    });
+}
+/** A failed, timed-out, interrupted, or superseded resize, with confirmed allocation. */
+declare class SandboxResizeError extends SandboxError {
+    readonly reason: ResizeErrorReason;
+    readonly generation: number;
+    readonly info?: SandboxInfo;
+    constructor(payload: {
+        sandboxId: string;
+        generation: number;
+        reason: ResizeErrorReason;
+        message: string;
+        info?: SandboxInfo | null;
+    });
+    /** Last confirmed allocation, if an observation was available. */
+    get confirmedResources(): ContainerResourcesInfo | undefined;
+}
+/**
+ * The wait budget ran out while the sandbox was still queued.
+ *
+ * Thrown by `Sandbox.create`, `createAndConnect`, `PendingSandbox.ready` and
+ * a lazy `connect` when their timeout elapses before the sandbox is running.
+ * **The sandbox is not deleted**: it keeps its place in the queue and starts
+ * whenever capacity arrives. Call `ready()` again to keep waiting,
+ * `Sandbox.connect` from any other process, or `delete` it to give up.
+ * `pendingReason` is the last reason the scheduler recorded (`scheduling`,
+ * `no_resources_available`, `pool_at_capacity`, ...).
+ */
+declare class SandboxPending extends SandboxError {
+    readonly sandboxId: string;
+    readonly pendingReason?: string;
+    readonly timeout?: number;
+    constructor(sandboxId: string, options?: {
+        pendingReason?: string;
+        timeout?: number;
+    });
+}
+/**
+ * Raised when the client cannot complete a request against the API server.
+ *
+ * The original transport error is preserved on this error's {@link cause} for programmatic
+ * inspection, and its full chain is folded into the message so it survives
+ * wrappers that only forward `error.message`. No interpretation of the failure
+ * (client vs server) is applied — the raw inner error is surfaced as-is so the
+ * reader can judge.
+ */
+declare class SandboxConnectionError extends SandboxError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Raised when a sandbox is not found. */
+declare class SandboxNotFoundError extends SandboxError {
+    readonly sandboxId: string;
+    constructor(sandboxId: string);
+}
+/** Raised when a sandbox pool is not found. */
+declare class PoolNotFoundError extends SandboxError {
+    readonly poolId: string;
+    constructor(poolId: string);
+}
+/** Raised when attempting to delete a pool that is in use. */
+declare class PoolInUseError extends SandboxError {
+    readonly poolId: string;
+    constructor(poolId: string, message?: string);
+}
+/** Raised when the remote API returns an error. */
+declare class RemoteAPIError extends SandboxError {
+    readonly statusCode: number;
+    /** Original response body, retained for compatibility and diagnostics. */
+    readonly responseMessage: string;
+    readonly sandboxId?: string;
+    /** Server reason, including unknown future reasons. */
+    readonly reason?: string;
+    readonly errorDetails?: unknown;
+    constructor(statusCode: number, message: string);
+}
+/** Raised when request output is fetched before the request has completed. */
+declare class RequestNotFinishedError extends Error {
+    constructor();
+}
+/** Raised when a request completed unsuccessfully. */
+declare class RequestFailedError extends Error {
+    readonly failure: string;
+    constructor(failure: string);
+}
+/** Raised when a request surfaced an application-level error. */
+declare class RequestExecutionError extends Error {
+    readonly functionName?: string;
+    constructor(message: string, functionName?: string);
+}
+
+export { ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, type AttachFileSystemOptions, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, type ClaimSandboxOptions, CliNotFoundError, CloudClient, CloudClientOptions, type CommandResult, type CommitJobError, type CommitJobReadBack, type CommitJobStatus, type ConflictPath, type ConflictTerm, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, 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 FileEntry, FileNotFoundInFilesystemError, FileSystem, type FileSystemMount, Filesystem, FilesystemAPIError, FilesystemClient, type FilesystemClientOptions, FilesystemError, type FilesystemFileRead, type FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemReadOptions, type FilesystemSnapshot, type FilesystemSnapshotInfo, type FilesystemStatus, type FilesystemVersion, type GPUResources, type GetOrCreateOptions, type GetOrCreateOutcome, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, type GpuModel, type GpuRequest, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type ManagedProcessExit, type ManagedProcessHealthStatus, type ManagedProcessInfo, type ManagedProcessStatus, type MergeConflict, type MergeConflictRecord, type MergeEntry, type MergeOptions, type MergeReport, type MergeStats, MountError, type MountStatus, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, PendingSandbox, type PendingSandboxRecord, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessHealthCheck, type ProcessHealthCheckType, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, type PushReport, type PushWorktreeOptions, ReadOnlyMountNotSupportedError, type ReadyOptions, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RepositoryMount, type RepositoryMountOptions, type RepositoryMountStatus, type RepositoryUnmountOptions, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, ResizeErrorReason, ResizeStatus, type ResourceResizeWaitOptions, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, SandboxPending, SandboxPendingReason, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxResizeError, type SandboxResourceResizeInfo, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TERMINATION_REASON_CANCELLED, TERMINATION_REASON_NO_CAPACITY, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, type UpdateSandboxOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, isSandboxPending, listFileSystems, sandboxUrlFromIngressEndpoint };