tensorlake 0.5.77 → 0.5.85

package/dist/index.d.cts

@@ -103,6 +103,36 @@ interface NativeSandboxClient {
     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;
 }
+interface NativeRepositoryClient {
+    gitRepoUrl(repo: string): 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): Promise<string>;
+    listFilesystems(): Promise<TracedJson>;
+    filesystemMeta(name: string): Promise<TracedJson>;
+    deleteFilesystem(name: string): Promise<string>;
+    filesystemRefStatus(name: string, refspec: string): Promise<TracedJson>;
+    readFilesystemFile(name: string, path: string, version: string): Promise<TracedBytes>;
+    listFilesystemTree(name: string, dirPath: string, version: string): Promise<TracedJson>;
+    pushFilesystemFiles(name: string, files: Array<{
+        path: string;
+        content: Buffer;
+    }>, deletes: string[], message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+}
 
 declare enum SandboxStatus {
     PENDING = "pending",
@@ -1440,6 +1470,231 @@ 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;
+    defaultBranch: string;
+    status: string;
+    kind: string;
+}
+/** Remote status of a filesystem: identity plus current head. */
+interface FilesystemStatus {
+    name: string;
+    status: string;
+    defaultBranch: string;
+    /**
+     * Commit hash the default branch currently points at; null for an empty
+     * filesystem that has never been written to.
+     */
+    headCommit: string | null;
+    /** Server-side movement counter for the default branch, 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;
+    /** Git blob/tree object id. */
+    oid: string;
+    /** Raw git mode (0o100644 file, 0o100755 executable, 0o120000 symlink, 0o40000 dir). */
+    mode: number;
+    /** Blob size in bytes when cheaply known server-side. */
+    size: number | null;
+    isDir: boolean;
+    isSymlink: boolean;
+}
+/** A durable version of the filesystem (a commit). */
+interface Snapshot {
+    /** Commit hash — pass as `version` to read the filesystem at this point. */
+    commit: string;
+    tree: string;
+    refName: string;
+    parent: string | null;
+    /** False when the write was a no-op (content identical to the parent). */
+    created: boolean;
+    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 CliNotFoundError extends MountError {
+    constructor(detail: string);
+}
+
+/**
+ * Client for Tensorlake filesystems.
+ *
+ * A filesystem is a durable, versioned file tree that lives in Tensorlake
+ * Cloud. Every write produces a {@link Snapshot} (a durable version), files
+ * can be read at any version, and a filesystem can be mounted to a local
+ * path through the `tl` CLI's FUSE/FSKit daemon.
+ *
+ * Reads and writes are served by the shared Rust cloud-sdk core (the same
+ * engine behind the `tl` CLI), so uploads get content-defined chunking,
+ * dedup, transient retries, and idempotent commit reattachment for free.
+ *
+ * @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;
+    organizationId?: string;
+    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 {
+    private binary;
+    private readonly envOverrides;
+    constructor(envOverrides: Record<string, string>);
+    private findCli;
+    private run;
+    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;
+    /**
+     * Any option left unset is resolved from the environment
+     * (`TENSORLAKE_API_KEY` / `TENSORLAKE_PAT`, `TENSORLAKE_API_URL`,
+     * `TENSORLAKE_ORGANIZATION_ID`, `TENSORLAKE_PROJECT_ID`).
+     */
+    constructor(options?: FilesystemClientOptions);
+    /** Create a new filesystem and return a handle to it. */
+    create(name: 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). */
+    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<Snapshot>;
+    /** Write several files (and/or delete paths) in one atomic snapshot. */
+    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<Snapshot>;
+    /** Delete one file. Returns the snapshot the deletion produced. */
+    deleteFile(path: string, message?: string): Promise<Snapshot>;
+    /**
+     * Return the filesystem's current version as a snapshot.
+     *
+     * Writes already create snapshots implicitly; this pins the current head
+     * without changing any content.
+     */
+    snapshot(message?: string): Promise<Snapshot>;
+    /**
+     * Read a file's bytes at `version` (branch, ref, or snapshot commit;
+     * defaults to the filesystem's default branch).
+     */
+    readFile(path: string, version?: string): Promise<Uint8Array>;
+    /** 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 head snapshot. */
+    status(): Promise<FilesystemStatus>;
+    /** Mount this filesystem to a local path (requires the `tl` CLI). */
+    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.
  *
@@ -1509,4 +1764,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, 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, FileSystem, type FileSystemMount, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, 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, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, 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, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };
+export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, 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 FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemStatus, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, 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, 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, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type Snapshot, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };

package/dist/index.d.ts

@@ -103,6 +103,36 @@ interface NativeSandboxClient {
     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;
 }
+interface NativeRepositoryClient {
+    gitRepoUrl(repo: string): 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): Promise<string>;
+    listFilesystems(): Promise<TracedJson>;
+    filesystemMeta(name: string): Promise<TracedJson>;
+    deleteFilesystem(name: string): Promise<string>;
+    filesystemRefStatus(name: string, refspec: string): Promise<TracedJson>;
+    readFilesystemFile(name: string, path: string, version: string): Promise<TracedBytes>;
+    listFilesystemTree(name: string, dirPath: string, version: string): Promise<TracedJson>;
+    pushFilesystemFiles(name: string, files: Array<{
+        path: string;
+        content: Buffer;
+    }>, deletes: string[], message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+}
 
 declare enum SandboxStatus {
     PENDING = "pending",
@@ -1440,6 +1470,231 @@ 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;
+    defaultBranch: string;
+    status: string;
+    kind: string;
+}
+/** Remote status of a filesystem: identity plus current head. */
+interface FilesystemStatus {
+    name: string;
+    status: string;
+    defaultBranch: string;
+    /**
+     * Commit hash the default branch currently points at; null for an empty
+     * filesystem that has never been written to.
+     */
+    headCommit: string | null;
+    /** Server-side movement counter for the default branch, 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;
+    /** Git blob/tree object id. */
+    oid: string;
+    /** Raw git mode (0o100644 file, 0o100755 executable, 0o120000 symlink, 0o40000 dir). */
+    mode: number;
+    /** Blob size in bytes when cheaply known server-side. */
+    size: number | null;
+    isDir: boolean;
+    isSymlink: boolean;
+}
+/** A durable version of the filesystem (a commit). */
+interface Snapshot {
+    /** Commit hash — pass as `version` to read the filesystem at this point. */
+    commit: string;
+    tree: string;
+    refName: string;
+    parent: string | null;
+    /** False when the write was a no-op (content identical to the parent). */
+    created: boolean;
+    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 CliNotFoundError extends MountError {
+    constructor(detail: string);
+}
+
+/**
+ * Client for Tensorlake filesystems.
+ *
+ * A filesystem is a durable, versioned file tree that lives in Tensorlake
+ * Cloud. Every write produces a {@link Snapshot} (a durable version), files
+ * can be read at any version, and a filesystem can be mounted to a local
+ * path through the `tl` CLI's FUSE/FSKit daemon.
+ *
+ * Reads and writes are served by the shared Rust cloud-sdk core (the same
+ * engine behind the `tl` CLI), so uploads get content-defined chunking,
+ * dedup, transient retries, and idempotent commit reattachment for free.
+ *
+ * @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;
+    organizationId?: string;
+    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 {
+    private binary;
+    private readonly envOverrides;
+    constructor(envOverrides: Record<string, string>);
+    private findCli;
+    private run;
+    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;
+    /**
+     * Any option left unset is resolved from the environment
+     * (`TENSORLAKE_API_KEY` / `TENSORLAKE_PAT`, `TENSORLAKE_API_URL`,
+     * `TENSORLAKE_ORGANIZATION_ID`, `TENSORLAKE_PROJECT_ID`).
+     */
+    constructor(options?: FilesystemClientOptions);
+    /** Create a new filesystem and return a handle to it. */
+    create(name: 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). */
+    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<Snapshot>;
+    /** Write several files (and/or delete paths) in one atomic snapshot. */
+    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<Snapshot>;
+    /** Delete one file. Returns the snapshot the deletion produced. */
+    deleteFile(path: string, message?: string): Promise<Snapshot>;
+    /**
+     * Return the filesystem's current version as a snapshot.
+     *
+     * Writes already create snapshots implicitly; this pins the current head
+     * without changing any content.
+     */
+    snapshot(message?: string): Promise<Snapshot>;
+    /**
+     * Read a file's bytes at `version` (branch, ref, or snapshot commit;
+     * defaults to the filesystem's default branch).
+     */
+    readFile(path: string, version?: string): Promise<Uint8Array>;
+    /** 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 head snapshot. */
+    status(): Promise<FilesystemStatus>;
+    /** Mount this filesystem to a local path (requires the `tl` CLI). */
+    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.
  *
@@ -1509,4 +1764,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, 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, FileSystem, type FileSystemMount, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, 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, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, 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, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };
+export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, 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 FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemStatus, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, 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, 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, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type Snapshot, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };