modal 0.7.5 → 0.7.6

package/dist/index.d.cts

@@ -140,6 +140,12 @@ declare enum EndpointInputModality {
     ENDPOINT_INPUT_MODALITY_AUDIO = 3,
     UNRECOGNIZED = -1
 }
+declare enum EndpointStopSource {
+    ENDPOINT_STOP_SOURCE_UNSPECIFIED = 0,
+    ENDPOINT_STOP_SOURCE_CLI = 1,
+    ENDPOINT_STOP_SOURCE_WEB = 2,
+    UNRECOGNIZED = -1
+}
 declare enum EnvironmentRole {
     ENVIRONMENT_ROLE_UNSPECIFIED = 0,
     ENVIRONMENT_ROLE_VIEWER = 1,
@@ -1389,6 +1395,30 @@ interface EndpointHuggingFaceModelSource {
     huggingfaceToken: string;
 }
 declare const EndpointHuggingFaceModelSource: MessageFns$1<EndpointHuggingFaceModelSource>;
+interface EndpointListItem {
+    endpointId: string;
+    name: string;
+    description: string;
+    activeDeploymentId: string;
+    updatedAt: number;
+    metadata: EndpointMetadata | undefined;
+}
+declare const EndpointListItem: MessageFns$1<EndpointListItem>;
+interface EndpointListRequest {
+    environmentName: string;
+    pagination: ListPagination | undefined;
+}
+declare const EndpointListRequest: MessageFns$1<EndpointListRequest>;
+interface EndpointListResponse {
+    items: EndpointListItem[];
+    environmentName: string;
+}
+declare const EndpointListResponse: MessageFns$1<EndpointListResponse>;
+interface EndpointMetadata {
+    name: string;
+    creationInfo: CreationInfo | undefined;
+}
+declare const EndpointMetadata: MessageFns$1<EndpointMetadata>;
 interface EndpointModalVolumeModelSource {
     volumeId: string;
     modelPath: string;
@@ -1399,6 +1429,14 @@ interface EndpointModelSource {
     custom?: EndpointCustomModelSource | undefined;
 }
 declare const EndpointModelSource: MessageFns$1<EndpointModelSource>;
+interface EndpointStopRequest {
+    endpointId: string;
+    source: EndpointStopSource;
+}
+declare const EndpointStopRequest: MessageFns$1<EndpointStopRequest>;
+interface EndpointStopResponse {
+}
+declare const EndpointStopResponse: MessageFns$1<EndpointStopResponse>;
 interface EnvironmentCreateRequest {
     name: string;
     isManaged: boolean;
@@ -2972,6 +3010,7 @@ interface Sandbox$1 {
      * (tunnels and auth proxy).
      */
     inboundCidrAllowlist: string[];
+    environmentVariables: StringMap | undefined;
 }
 declare const Sandbox$1: MessageFns$1<Sandbox$1>;
 interface SandboxCreateConnectTokenRequest {
@@ -3422,6 +3461,12 @@ interface SharedVolumeRemoveFileRequest {
     recursive: boolean;
 }
 declare const SharedVolumeRemoveFileRequest: MessageFns$1<SharedVolumeRemoveFileRequest>;
+interface StringMap {
+    contents: {
+        [key: string]: string;
+    };
+}
+declare const StringMap: MessageFns$1<StringMap>;
 interface SystemErrorMessage {
     errorCode: SystemErrorCode;
     errorMessage: string;
@@ -4483,6 +4528,22 @@ declare const ModalClientDefinition: {
             readonly responseStream: false;
             readonly options: {};
         };
+        readonly endpointList: {
+            readonly name: "EndpointList";
+            readonly requestType: MessageFns$1<EndpointListRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$1<EndpointListResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
+        readonly endpointStop: {
+            readonly name: "EndpointStop";
+            readonly requestType: MessageFns$1<EndpointStopRequest>;
+            readonly requestStream: false;
+            readonly responseType: MessageFns$1<EndpointStopResponse>;
+            readonly responseStream: false;
+            readonly options: {};
+        };
         /** Environments */
         readonly environmentCreate: {
             readonly name: "EnvironmentCreate";
@@ -5885,20 +5946,45 @@ declare class VolumeService {
      */
     delete(name: string, params?: VolumeDeleteParams): Promise<void>;
 }
+/**
+ * Resolved mount configuration stored on a Volume. `subPath: undefined` means "mount the
+ * whole volume" (no sub-path set on the resulting VolumeMount proto).
+ */
+type ResolvedMountOptions = {
+    readOnly: boolean;
+    subPath: string | undefined;
+};
 /** Volumes provide persistent storage that can be mounted in Modal {@link Function_ Function}s. */
 declare class Volume {
     #private;
     readonly volumeId: string;
     readonly name?: string;
-    private _readOnly;
+    /**
+     * @hidden
+     * @internal
+     */
+    readonly _mountOptions: ResolvedMountOptions;
     /** @ignore */
-    constructor(volumeId: string, name?: string, readOnly?: boolean, ephemeralHbManager?: EphemeralHeartbeatManager);
+    constructor(volumeId: string, name?: string, mountOptions?: ResolvedMountOptions, ephemeralHbManager?: EphemeralHeartbeatManager);
     /**
      * @deprecated Use {@link VolumeService#fromName client.volumes.fromName()} instead.
      */
     static fromName(name: string, options?: VolumeFromNameParams): Promise<Volume>;
-    /** Configure Volume to mount as read-only. */
+    /**
+     * Configure Volume to mount as read-only.
+     *
+     * @deprecated Use {@link withMountOptions} with `{ readOnly: true }` instead.
+     */
     readOnly(): Volume;
+    /**
+     * Configure options used when mounting this Volume. Fields left undefined preserve their value
+     * from any previous withMountOptions call on the same Volume (stacking).
+     */
+    withMountOptions(params?: VolumeMountOptions): Volume;
+    /**
+     * @deprecated Inspect mount configuration at the call site that configured it instead.
+     * Future versions of this SDK may remove direct mount-option accessors on Volume.
+     */
     get isReadOnly(): boolean;
     /**
      * @deprecated Use {@link VolumeService#ephemeral client.volumes.ephemeral()} instead.
@@ -5907,6 +5993,11 @@ declare class Volume {
     /** Delete the ephemeral Volume. Only usable with emphemeral Volumes. */
     closeEphemeral(): void;
 }
+/** Options for mounting a {@link Volume}. */
+type VolumeMountOptions = {
+    readOnly?: boolean;
+    subPath?: string;
+};
 
 /** Optional parameters for {@link ClsService#fromName client.cls.fromName()}. */
 type ClsFromNameParams = {
@@ -6519,6 +6610,173 @@ declare class SandboxFile {
     close(): Promise<void>;
 }
 
+/** Type of a filesystem entry. */
+type FileType = "file" | "directory" | "symlink";
+/** Metadata for a file or directory entry in a Sandbox. */
+interface FileInfo {
+    readonly name: string;
+    readonly path: string;
+    readonly type: FileType;
+    readonly size: number;
+    readonly mode: number;
+    readonly permissions: string;
+    readonly owner: string;
+    readonly group: string;
+    /** Unix epoch seconds. */
+    readonly modifiedTime: number;
+    readonly symlinkTarget: string | null;
+}
+/** Namespace for Sandbox filesystem APIs. */
+declare class SandboxFilesystem {
+    private readonly sandbox;
+    /** @ignore */
+    constructor(sandbox: Sandbox);
+    /**
+     * Copy a local file into the Sandbox.
+     *
+     * `remotePath` must be an absolute path to a file in the Sandbox.
+     * Parent directories are created if needed. The remote file is overwritten
+     * if it already exists.
+     *
+     * @throws {SandboxFilesystemNotADirectoryError} a parent component of `remotePath` is not a directory.
+     * @throws {SandboxFilesystemIsADirectoryError} `remotePath` points to a directory.
+     * @throws {SandboxFilesystemPermissionError} write permission is denied in the Sandbox.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     * @throws {Error} `localPath` does not exist, is a directory, or cannot be read (`ENOENT`, `EISDIR`, `EACCES`).
+     */
+    copyFromLocal(localPath: string, remotePath: string): Promise<void>;
+    /**
+     * Copy a file from the Sandbox to a local path.
+     *
+     * `remotePath` must be an absolute path to a file in the Sandbox.
+     * Parent directories for `localPath` are created if needed. The local file
+     * is overwritten if it already exists.
+     *
+     * @throws {SandboxFilesystemNotFoundError} the remote path does not exist.
+     * @throws {SandboxFilesystemIsADirectoryError} the remote path points to a directory.
+     * @throws {SandboxFilesystemFileTooLargeError} the file exceeds the read size limit.
+     * @throws {SandboxFilesystemPermissionError} read permission is denied in the Sandbox.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     * @throws {Error} `localPath` points to a directory, or writing it is not permitted.
+     */
+    copyToLocal(remotePath: string, localPath: string): Promise<void>;
+    /**
+     * List files and directories in a Sandbox directory.
+     *
+     * `remotePath` must be an absolute path to a directory in the Sandbox.
+     * Returns an array of {@link FileInfo} objects sorted by name.
+     *
+     * @throws {SandboxFilesystemNotFoundError} the path does not exist.
+     * @throws {SandboxFilesystemNotADirectoryError} the path is not a directory.
+     * @throws {SandboxFilesystemPermissionError} read permission is denied.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    listFiles(remotePath: string): Promise<FileInfo[]>;
+    /**
+     * Create a new directory in the Sandbox.
+     *
+     * `remotePath` must be an absolute path in the Sandbox.
+     *
+     * When `createParents` is `true` (the default), any missing parent
+     * directories are created and the call is idempotent (succeeds if the
+     * directory already exists). When `createParents` is `false`, the immediate
+     * parent must already exist and the path must not already exist.
+     *
+     * @throws {SandboxFilesystemNotFoundError} the parent does not exist and `createParents` is `false`.
+     * @throws {SandboxFilesystemPathAlreadyExistsError} the path already exists and `createParents` is `false`.
+     * @throws {SandboxFilesystemNotADirectoryError} a path component is not a directory.
+     * @throws {SandboxFilesystemPermissionError} creation is not permitted.
+     * @throws {InvalidError} the operation is not supported by the mount.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    makeDirectory(remotePath: string, options?: {
+        createParents?: boolean;
+    }): Promise<void>;
+    /**
+     * Read a file from the Sandbox and return its contents as bytes.
+     *
+     * `remotePath` must be an absolute path to a file in the Sandbox.
+     *
+     * @throws {SandboxFilesystemNotFoundError} the path does not exist.
+     * @throws {SandboxFilesystemIsADirectoryError} the path points to a directory.
+     * @throws {SandboxFilesystemFileTooLargeError} the file exceeds the read size limit.
+     * @throws {SandboxFilesystemPermissionError} read permission is denied.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    readBytes(remotePath: string): Promise<Uint8Array>;
+    /**
+     * Read a file from the Sandbox and return its contents as a UTF-8 string.
+     *
+     * `remotePath` must be an absolute path to a file in the Sandbox.
+     *
+     * @throws {SandboxFilesystemNotFoundError} the path does not exist.
+     * @throws {SandboxFilesystemIsADirectoryError} the path points to a directory.
+     * @throws {SandboxFilesystemFileTooLargeError} the file exceeds the read size limit.
+     * @throws {SandboxFilesystemPermissionError} read permission is denied.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    readText(remotePath: string): Promise<string>;
+    /**
+     * Remove a file or directory in the Sandbox.
+     *
+     * `remotePath` must be an absolute path in the Sandbox. When `remotePath`
+     * is a directory and `recursive` is `false` (the default), it is removed
+     * only if empty. When `recursive` is `true`, the directory and all its
+     * contents are removed. Recursive removal is not supported on all mounts —
+     * `CloudBucketMount` does not support it.
+     *
+     * @throws {SandboxFilesystemNotFoundError} the path does not exist.
+     * @throws {SandboxFilesystemDirectoryNotEmptyError} `recursive` is `false` and the directory is not empty.
+     * @throws {SandboxFilesystemPermissionError} removal is not permitted.
+     * @throws {InvalidError} the operation is not supported by the mount.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    remove(remotePath: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Return metadata for a single file, directory, or symlink in the Sandbox.
+     *
+     * `remotePath` must be an absolute path in the Sandbox. If `remotePath` is
+     * a symlink, the returned {@link FileInfo} describes the symlink itself, not
+     * the target it points to.
+     *
+     * @throws {SandboxFilesystemNotFoundError} the path does not exist.
+     * @throws {SandboxFilesystemNotADirectoryError} a non-leaf component of the path is not a directory.
+     * @throws {SandboxFilesystemPermissionError} a path component is not searchable.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    stat(remotePath: string): Promise<FileInfo>;
+    /**
+     * Write binary content to a file in the Sandbox.
+     *
+     * `remotePath` must be an absolute path to a file in the Sandbox.
+     * Parent directories are created if needed. The remote file is overwritten
+     * if it already exists.
+     *
+     * @throws {TypeError} `data` is not a `Uint8Array`, `ArrayBuffer`, or `Buffer`.
+     * @throws {SandboxFilesystemNotADirectoryError} a parent component of `remotePath` is not a directory.
+     * @throws {SandboxFilesystemIsADirectoryError} `remotePath` points to a directory.
+     * @throws {SandboxFilesystemPermissionError} write permission is denied.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    writeBytes(data: Uint8Array | ArrayBuffer | Buffer, remotePath: string): Promise<void>;
+    /**
+     * Write UTF-8 text to a file in the Sandbox.
+     *
+     * `remotePath` must be an absolute path to a file in the Sandbox.
+     * Parent directories are created if needed. The remote file is overwritten
+     * if it already exists.
+     *
+     * @throws {TypeError} `data` is not a string.
+     * @throws {SandboxFilesystemNotADirectoryError} a parent component of `remotePath` is not a directory.
+     * @throws {SandboxFilesystemIsADirectoryError} `remotePath` points to a directory.
+     * @throws {SandboxFilesystemPermissionError} write permission is denied.
+     * @throws {SandboxFilesystemError} the command fails for any other reason.
+     */
+    writeText(data: string, remotePath: string): Promise<void>;
+}
+
 /**
  * Wrapper around `ReadableStream` with convenience functions.
  *
@@ -6673,6 +6931,20 @@ declare class SandboxService {
     create(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
     /**
      * Create a new {@link Sandbox} using the experimental V2 backend.
+     *
+     * Supported features include exec, encrypted tunnels, wait/poll/terminate,
+     * CPU and memory configuration, and region placement.
+     *
+     * Features like tags, filesystem snapshots, memory snapshots, volumes, cloud
+     * bucket mounts, GPUs, custom domains, OIDC identity tokens, proxies, and
+     * readiness probes are not supported.
+     *
+     * V2 sandboxes created with this method are not currently returned by
+     * {@link SandboxService#list client.sandboxes.list()} and cannot be looked up
+     * with {@link SandboxService#fromName client.sandboxes.fromName()}. Store
+     * {@link Sandbox#sandboxId sandbox.sandboxId} if you need to retrieve the
+     * sandbox later, and use {@link SandboxService#fromId client.sandboxes.fromId()}
+     * to reattach.
      */
     experimentalCreate(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
     /** Returns a running {@link Sandbox} object from an ID.
@@ -6772,6 +7044,7 @@ declare class Sandbox {
     get stdin(): ModalWriteStream<string>;
     get stdout(): ModalReadStream<string>;
     get stderr(): ModalReadStream<string>;
+    get filesystem(): SandboxFilesystem;
     /** Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in {@link SandboxService#list Sandbox.list}. */
     setTags(tags: Record<string, string>): Promise<void>;
     /** Get tags (key-value pairs) currently attached to this Sandbox from the server. */
@@ -6786,6 +7059,10 @@ declare class Sandbox {
     static fromName(appName: string, name: string, environment?: string): Promise<Sandbox>;
     /**
      * Open a file in the Sandbox filesystem.
+     *
+     * @deprecated Use {@link SandboxFilesystem} methods: `sandbox.filesystem.readBytes()`,
+     * `writeBytes()`, or `copyToLocal()` instead for improved reliability.
+     *
      * @param path - Path to the file to open
      * @param mode - File open mode (r, w, a, r+, w+, a+)
      * @returns Promise that resolves to a {@link SandboxFile}
@@ -6883,6 +7160,13 @@ declare class ContainerProcess<R extends string | Uint8Array = any> {
     stderr: ModalReadStream<R>;
     /** @ignore */
     constructor(taskId: string, execId: string, commandRouterClient: TaskCommandRouterClientImpl, params?: SandboxExecParams, deadline?: number | null);
+    /**
+     * @ignore
+     * Send stdin EOF directly, bypassing the WritableStream state machine.
+     *
+     * Useful for when an stdin write has failed.
+     */
+    closeStdin(): Promise<void>;
     /** Wait for process completion and return the exit code. */
     wait(): Promise<number>;
 }
@@ -7093,6 +7377,38 @@ declare class QueueEmptyError extends Error {
 declare class QueueFullError extends Error {
     constructor(message: string);
 }
+/** Errors from invalid Sandbox FileSystem operations. */
+declare class SandboxFilesystemError extends Error {
+    constructor(message: string);
+}
+/** A directory was expected to be empty but is not. */
+declare class SandboxFilesystemDirectoryNotEmptyError extends SandboxFilesystemError {
+    constructor(message: string);
+}
+/** A file exceeds the maximum allowed size for a read operation. */
+declare class SandboxFilesystemFileTooLargeError extends SandboxFilesystemError {
+    constructor(message: string);
+}
+/** A file operation was attempted on a path that resolves to a directory. */
+declare class SandboxFilesystemIsADirectoryError extends SandboxFilesystemError {
+    constructor(message: string);
+}
+/** A directory operation encountered a path component that is not a directory. */
+declare class SandboxFilesystemNotADirectoryError extends SandboxFilesystemError {
+    constructor(message: string);
+}
+/** A file or directory is not found. */
+declare class SandboxFilesystemNotFoundError extends SandboxFilesystemError {
+    constructor(message: string);
+}
+/** A path already exists and the operation requires it to be absent. */
+declare class SandboxFilesystemPathAlreadyExistsError extends SandboxFilesystemError {
+    constructor(message: string);
+}
+/** Permission is denied for a file operation. */
+declare class SandboxFilesystemPermissionError extends SandboxFilesystemError {
+    constructor(message: string);
+}
 /** Sandbox operations that exceed the allowed time limit. */
 declare class SandboxTimeoutError extends Error {
     constructor(message?: string);
@@ -7104,4 +7420,4 @@ declare class ClientClosedError extends Error {
 
 declare function checkForRenamedParams(params: any, renames: Record<string, string>): void;
 
-export { AlreadyExistsError, App, type AppFromNameParams, AppService, ClientClosedError, type ClientOptions, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ContainerProcess, type DeleteOptions, type EphemeralOptions, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, FunctionCallService, type FunctionFromNameParams, FunctionService, type FunctionStats, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, ImageService, InternalFailure, InvalidError, type LogLevel, type Logger, type LookupOptions, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, SandboxFile, type SandboxFileMode, type SandboxFromNameParams, type SandboxListParams, SandboxService, type SandboxTerminateParams, SandboxTimeoutError, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, VolumeService, checkForRenamedParams, close, initializeClient };
+export { AlreadyExistsError, App, type AppFromNameParams, AppService, ClientClosedError, type ClientOptions, CloudBucketMount, CloudBucketMountService, Cls, type ClsFromNameParams, ClsInstance, ClsService, type ClsWithBatchingParams, type ClsWithConcurrencyParams, type ClsWithOptionsParams, ContainerProcess, type DeleteOptions, type EphemeralOptions, type FileInfo, type FileType, FunctionCall, type FunctionCallCancelParams, type FunctionCallGetParams, FunctionCallService, type FunctionFromNameParams, FunctionService, type FunctionStats, FunctionTimeoutError, type FunctionUpdateAutoscalerParams, Function_, Image, type ImageDeleteParams, type ImageDockerfileCommandsParams, ImageService, InternalFailure, InvalidError, type LogLevel, type Logger, type LookupOptions, ModalClient, type ModalClientParams, type ModalReadStream, type ModalWriteStream, NotFoundError, Probe, type ProbeParams, type Profile, Proxy, type ProxyFromNameParams, ProxyService, Queue, type QueueClearParams, type QueueDeleteParams, QueueEmptyError, type QueueEphemeralParams, type QueueFromNameParams, QueueFullError, type QueueGetParams, type QueueIterateParams, type QueueLenParams, type QueuePutParams, QueueService, RemoteError, Retries, Sandbox, type SandboxCreateConnectCredentials, type SandboxCreateConnectTokenParams, type SandboxCreateParams, type SandboxExecParams, SandboxFile, type SandboxFileMode, SandboxFilesystem, SandboxFilesystemDirectoryNotEmptyError, SandboxFilesystemError, SandboxFilesystemFileTooLargeError, SandboxFilesystemIsADirectoryError, SandboxFilesystemNotADirectoryError, SandboxFilesystemNotFoundError, SandboxFilesystemPathAlreadyExistsError, SandboxFilesystemPermissionError, type SandboxFromNameParams, type SandboxListParams, SandboxService, type SandboxTerminateParams, SandboxTimeoutError, Secret, type SecretDeleteParams, type SecretFromNameParams, type SecretFromObjectParams, SecretService, type StdioBehavior, type StreamMode, TimeoutError, Tunnel, Volume, type VolumeDeleteParams, type VolumeEphemeralParams, type VolumeFromNameParams, type VolumeMountOptions, VolumeService, checkForRenamedParams, close, initializeClient };