@langchain/modal 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,514 @@
+import { ModalClient, Sandbox, SandboxCreateParams } from "modal";
+import { BaseSandbox, ExecuteResponse, FileDownloadResponse, FileUploadResponse } from "deepagents";
+
+//#region src/types.d.ts
+/**
+ * Fields from SandboxCreateParams that we wrap with a different API:
+ * - `volumes` -> we accept volume names (strings), SDK needs Volume objects
+ * - `secrets` -> we accept secret names (strings), SDK needs Secret objects
+ *
+ * Fields not exposed yet:
+ * - `cloudBucketMounts`, `proxy`, `experimentalOptions`, `customDomain`
+ * - `command`, `pty`, `encryptedPorts`, `h2Ports`, `unencryptedPorts`, `cloud`
+ */
+type WrappedSdkFields = "secrets" | "volumes" | "cloudBucketMounts" | "proxy" | "experimentalOptions" | "customDomain" | "command" | "pty" | "encryptedPorts" | "h2Ports" | "unencryptedPorts" | "cloud";
+/**
+ * SDK options that pass through directly.
+ */
+type BaseSdkOptions = Omit<SandboxCreateParams, WrappedSdkFields>;
+/**
+ * Configuration options for creating a Modal Sandbox.
+ *
+ * Extends the Modal SDK's SandboxCreateParams with additional options
+ * for app/image configuration and a simplified volumes/secrets API.
+ *
+ * @example
+ * ```typescript
+ * const options: ModalSandboxOptions = {
+ *   appName: "my-sandbox-app",
+ *   imageName: "python:3.12-slim",
+ *   timeoutMs: 600_000, // 10 minutes
+ *   memoryMiB: 2048, // 2GB
+ *   initialFiles: {
+ *     "/app/index.js": "console.log('Hello')",
+ *   },
+ * };
+ * ```
+ */
+interface ModalSandboxOptions extends BaseSdkOptions {
+  /**
+   * Name of the Modal App to associate the sandbox with.
+   * If not provided, a default app name will be used.
+   * The app will be created if it doesn't exist.
+   *
+   * @default "deepagents-sandbox"
+   */
+  appName?: string;
+  /**
+   * Docker image to use for the sandbox container.
+   * Can be any public Docker image or a Modal Image reference.
+   *
+   * @default "alpine:3.21"
+   *
+   * @example
+   * ```typescript
+   * // Use Python image
+   * imageName: "python:3.12-slim"
+   *
+   * // Use Node.js image
+   * imageName: "node:20-slim"
+   * ```
+   */
+  imageName?: string;
+  /**
+   * Modal Volume names to mount, mapped to their mount paths.
+   * Volumes must be created beforehand in Modal.
+   *
+   * Unlike the SDK which requires Volume objects, we accept volume names
+   * and look them up automatically.
+   *
+   * @example
+   * ```typescript
+   * volumes: {
+   *   "/data": "my-data-volume",
+   *   "/cache": "my-cache-volume"
+   * }
+   * ```
+   */
+  volumes?: Record<string, string>;
+  /**
+   * Modal Secret names to inject into the sandbox environment.
+   * Secrets must be created beforehand in Modal.
+   *
+   * Unlike the SDK which requires Secret objects, we accept secret names
+   * and look them up automatically.
+   *
+   * @example
+   * ```typescript
+   * secrets: ["my-api-keys", "database-credentials"]
+   * ```
+   */
+  secrets?: string[];
+  /**
+   * Initial files to populate the sandbox with.
+   *
+   * Keys are file paths (relative to the working directory), values are file contents.
+   * Parent directories will be created automatically if they don't exist.
+   *
+   * @example
+   * ```typescript
+   * initialFiles: {
+   *   "/src/index.js": "console.log('Hello')",
+   *   "/package.json": '{"name": "my-app"}',
+   * }
+   * ```
+   */
+  initialFiles?: Record<string, string | Uint8Array>;
+  /**
+   * Authentication configuration for Modal API.
+   *
+   * ### Environment Variable Setup
+   *
+   * ```bash
+   * # Create a token at https://modal.com/settings/tokens
+   * export MODAL_TOKEN_ID=your_token_id
+   * export MODAL_TOKEN_SECRET=your_token_secret
+   * ```
+   *
+   * Or pass the credentials directly in this auth configuration.
+   */
+  auth?: {
+    /**
+     * Modal token ID.
+     * If not provided, reads from `MODAL_TOKEN_ID` environment variable.
+     */
+    tokenId?: string;
+    /**
+     * Modal token secret.
+     * If not provided, reads from `MODAL_TOKEN_SECRET` environment variable.
+     */
+    tokenSecret?: string;
+  };
+}
+/**
+ * Error codes for Modal Sandbox operations.
+ *
+ * Used to identify specific error conditions and handle them appropriately.
+ */
+type ModalSandboxErrorCode = /** Sandbox has not been initialized - call initialize() first */"NOT_INITIALIZED" /** Sandbox is already initialized - cannot initialize twice */ | "ALREADY_INITIALIZED" /** Authentication failed - check token configuration */ | "AUTHENTICATION_FAILED" /** Failed to create sandbox - check options and quotas */ | "SANDBOX_CREATION_FAILED" /** Sandbox not found - may have been stopped or expired */ | "SANDBOX_NOT_FOUND" /** Command execution timed out */ | "COMMAND_TIMEOUT" /** Command execution failed */ | "COMMAND_FAILED" /** File operation (read/write) failed */ | "FILE_OPERATION_FAILED" /** Resource limits exceeded (CPU, memory, storage) */ | "RESOURCE_LIMIT_EXCEEDED" /** Volume operation failed */ | "VOLUME_ERROR";
+declare const MODAL_SANDBOX_ERROR_SYMBOL: unique symbol;
+/**
+ * Custom error class for Modal Sandbox operations.
+ *
+ * Provides structured error information including:
+ * - Human-readable message
+ * - Error code for programmatic handling
+ * - Original cause for debugging
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandbox.execute("some command");
+ * } catch (error) {
+ *   if (error instanceof ModalSandboxError) {
+ *     switch (error.code) {
+ *       case "NOT_INITIALIZED":
+ *         await sandbox.initialize();
+ *         break;
+ *       case "COMMAND_TIMEOUT":
+ *         console.error("Command took too long");
+ *         break;
+ *       default:
+ *         throw error;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class ModalSandboxError extends Error {
+  readonly code: ModalSandboxErrorCode;
+  readonly cause?: Error | undefined;
+  [MODAL_SANDBOX_ERROR_SYMBOL]: true;
+  /** Error name for instanceof checks and logging */
+  readonly name = "ModalSandboxError";
+  /**
+   * Creates a new ModalSandboxError.
+   *
+   * @param message - Human-readable error description
+   * @param code - Structured error code for programmatic handling
+   * @param cause - Original error that caused this error (for debugging)
+   */
+  constructor(message: string, code: ModalSandboxErrorCode, cause?: Error | undefined);
+  /**
+   * Checks if the error is an instance of ModalSandboxError.
+   *
+   * @param error - The error to check
+   * @returns True if the error is an instance of ModalSandboxError, false otherwise
+   */
+  static isInstance(error: unknown): error is ModalSandboxError;
+}
+//#endregion
+//#region src/sandbox.d.ts
+/**
+ * Modal Sandbox backend for deepagents.
+ *
+ * Extends `BaseSandbox` to provide command execution, file operations, and
+ * sandbox lifecycle management using Modal's serverless infrastructure.
+ *
+ * ## Basic Usage
+ *
+ * ```typescript
+ * import { ModalSandbox } from "@langchain/modal";
+ *
+ * // Create and initialize a sandbox
+ * const sandbox = await ModalSandbox.create({
+ *   imageName: "python:3.12-slim",
+ *   timeout: 600,
+ * });
+ *
+ * try {
+ *   // Execute commands
+ *   const result = await sandbox.execute("python --version");
+ *   console.log(result.output);
+ * } finally {
+ *   // Always cleanup
+ *   await sandbox.close();
+ * }
+ * ```
+ *
+ * ## Using with DeepAgent
+ *
+ * ```typescript
+ * import { createDeepAgent } from "deepagents";
+ * import { ModalSandbox } from "@langchain/modal";
+ *
+ * const sandbox = await ModalSandbox.create();
+ *
+ * const agent = createDeepAgent({
+ *   model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
+ *   systemPrompt: "You are a coding assistant with sandbox access.",
+ *   backend: sandbox,
+ * });
+ * ```
+ */
+declare class ModalSandbox extends BaseSandbox {
+  #private;
+  /**
+   * Get the unique identifier for this sandbox.
+   *
+   * Before initialization, returns a temporary ID.
+   * After initialization, returns the actual Modal sandbox ID.
+   */
+  get id(): string;
+  /**
+   * Get the underlying Modal Sandbox instance.
+   *
+   * @throws {ModalSandboxError} If the sandbox is not initialized
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await ModalSandbox.create();
+   * const modalInstance = sandbox.instance; // Access the raw Modal Sandbox
+   * ```
+   */
+  get instance(): Sandbox;
+  /**
+   * Get the underlying Modal client instance.
+   *
+   * @throws {ModalSandboxError} If the sandbox is not initialized
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await ModalSandbox.create();
+   * const modalClient = sandbox.client; // Access the raw Modal client
+   * ```
+   */
+  get client(): ModalClient;
+  /**
+   * Check if the sandbox is initialized and running.
+   */
+  get isRunning(): boolean;
+  /**
+   * Create a new ModalSandbox instance.
+   *
+   * Note: This only creates the instance. Call `initialize()` to actually
+   * create the Modal Sandbox, or use the static `ModalSandbox.create()` method.
+   *
+   * @param options - Configuration options for the sandbox
+   *
+   * @example
+   * ```typescript
+   * // Two-step initialization
+   * const sandbox = new ModalSandbox({ imageName: "python:3.12-slim" });
+   * await sandbox.initialize();
+   *
+   * // Or use the factory method
+   * const sandbox = await ModalSandbox.create({ imageName: "python:3.12-slim" });
+   * ```
+   */
+  constructor(options?: ModalSandboxOptions);
+  /**
+   * Initialize the sandbox by creating a new Modal Sandbox instance.
+   *
+   * This method authenticates with Modal and provisions a new sandbox container.
+   * After initialization, the `id` property will reflect the actual Modal sandbox ID.
+   *
+   * @throws {ModalSandboxError} If already initialized (`ALREADY_INITIALIZED`)
+   * @throws {ModalSandboxError} If authentication fails (`AUTHENTICATION_FAILED`)
+   * @throws {ModalSandboxError} If sandbox creation fails (`SANDBOX_CREATION_FAILED`)
+   *
+   * @example
+   * ```typescript
+   * const sandbox = new ModalSandbox();
+   * await sandbox.initialize();
+   * console.log(`Sandbox ID: ${sandbox.id}`);
+   * ```
+   */
+  initialize(): Promise<void>;
+  /**
+   * Execute a command in the sandbox.
+   *
+   * Commands are run using bash -c to execute the command string.
+   *
+   * @param command - The shell command to execute
+   * @returns Execution result with output, exit code, and truncation flag
+   * @throws {ModalSandboxError} If the sandbox is not initialized
+   *
+   * @example
+   * ```typescript
+   * const result = await sandbox.execute("echo 'Hello World'");
+   * console.log(result.output); // "Hello World\n"
+   * console.log(result.exitCode); // 0
+   * ```
+   */
+  execute(command: string): Promise<ExecuteResponse>;
+  /**
+   * Upload files to the sandbox.
+   *
+   * Files are written to the sandbox filesystem using Modal's file API.
+   * Parent directories are created automatically if they don't exist.
+   *
+   * @param files - Array of [path, content] tuples to upload
+   * @returns Upload result for each file, with success or error status
+   *
+   * @example
+   * ```typescript
+   * const encoder = new TextEncoder();
+   * const results = await sandbox.uploadFiles([
+   *   ["src/index.js", encoder.encode("console.log('Hello')")],
+   *   ["package.json", encoder.encode('{"name": "test"}')],
+   * ]);
+   * ```
+   */
+  uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]>;
+  /**
+   * Download files from the sandbox.
+   *
+   * Each file is read individually using Modal's file API, allowing
+   * partial success when some files exist and others don't.
+   *
+   * @param paths - Array of file paths to download
+   * @returns Download result for each file, with content or error
+   *
+   * @example
+   * ```typescript
+   * const results = await sandbox.downloadFiles(["src/index.js", "missing.txt"]);
+   * for (const result of results) {
+   *   if (result.content) {
+   *     console.log(new TextDecoder().decode(result.content));
+   *   } else {
+   *     console.error(`Error: ${result.error}`);
+   *   }
+   * }
+   * ```
+   */
+  downloadFiles(paths: string[]): Promise<FileDownloadResponse[]>;
+  /**
+   * Close the sandbox and release all resources.
+   *
+   * After closing, the sandbox cannot be used again. This terminates
+   * the sandbox container on Modal.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await sandbox.execute("npm run build");
+   * } finally {
+   *   await sandbox.close();
+   * }
+   * ```
+   */
+  close(): Promise<void>;
+  /**
+   * Terminate the sandbox.
+   *
+   * Alias for close() for Modal SDK compatibility.
+   *
+   * @example
+   * ```typescript
+   * await sandbox.terminate();
+   * ```
+   */
+  terminate(): Promise<void>;
+  /**
+   * Alias for close() to maintain compatibility with other sandbox implementations.
+   */
+  stop(): Promise<void>;
+  /**
+   * Poll the sandbox status to check if it has finished running.
+   *
+   * @returns The exit code if the sandbox has finished, or null if still running
+   */
+  poll(): Promise<number | null>;
+  /**
+   * Wait for the sandbox to finish running.
+   *
+   * @returns The exit code of the sandbox
+   * @throws {ModalSandboxError} If the sandbox is not initialized
+   */
+  wait(): Promise<number>;
+  /**
+   * Create and initialize a new ModalSandbox in one step.
+   *
+   * This is the recommended way to create a sandbox. It combines
+   * construction and initialization into a single async operation.
+   *
+   * @param options - Configuration options for the sandbox
+   * @returns An initialized and ready-to-use sandbox
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await ModalSandbox.create({
+   *   imageName: "python:3.12-slim",
+   *   timeout: 600,
+   *   memory: 2048,
+   * });
+   * ```
+   */
+  static create(options?: ModalSandboxOptions): Promise<ModalSandbox>;
+  /**
+   * Reconnect to an existing sandbox by ID.
+   *
+   * This allows you to resume working with a sandbox that was created
+   * earlier and is still running.
+   *
+   * @param sandboxId - The ID of the sandbox to reconnect to
+   * @param options - Optional auth configuration
+   * @returns A connected sandbox instance
+   *
+   * @example
+   * ```typescript
+   * // Resume a sandbox from a stored ID
+   * const sandbox = await ModalSandbox.fromId("sb-abc123");
+   * const result = await sandbox.execute("ls -la");
+   * ```
+   */
+  static fromId(sandboxId: string, options?: Pick<ModalSandboxOptions, "auth">): Promise<ModalSandbox>;
+  /**
+   * Get a running sandbox by name from a deployed app.
+   *
+   * @param appName - The name of the Modal app
+   * @param sandboxName - The name of the sandbox
+   * @param options - Optional auth configuration
+   * @returns A connected sandbox instance
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await ModalSandbox.fromName("my-app", "my-sandbox");
+   * const result = await sandbox.execute("ls -la");
+   * ```
+   */
+  static fromName(appName: string, sandboxName: string, options?: Pick<ModalSandboxOptions, "auth">): Promise<ModalSandbox>;
+}
+//#endregion
+//#region src/auth.d.ts
+/**
+ * Authentication credentials for Modal API.
+ */
+interface ModalCredentials {
+  /** Modal token ID */
+  tokenId: string;
+  /** Modal token secret */
+  tokenSecret: string;
+}
+/**
+ * Get authentication credentials for Modal API.
+ *
+ * Credentials are resolved in the following priority order:
+ *
+ * 1. **Explicit options**: If `options.tokenId` and/or `options.tokenSecret` are provided,
+ *    they are used directly.
+ * 2. **Environment variables**: `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` are used as fallbacks.
+ *
+ * ## Environment Variable Setup
+ *
+ * ```bash
+ * # Go to https://modal.com/settings/tokens
+ * # Create a new token and set the environment variables
+ * export MODAL_TOKEN_ID=your_token_id
+ * export MODAL_TOKEN_SECRET=your_token_secret
+ * ```
+ *
+ * @param options - Optional authentication configuration from ModalSandboxOptions
+ * @returns Complete authentication credentials
+ * @throws {Error} If any credentials are missing
+ *
+ * @example
+ * ```typescript
+ * // With explicit credentials
+ * const creds = getAuthCredentials({ tokenId: "...", tokenSecret: "..." });
+ *
+ * // Using environment variables (auto-detected)
+ * const creds = getAuthCredentials();
+ *
+ * // From ModalSandboxOptions
+ * const options: ModalSandboxOptions = {
+ *   auth: { tokenId: "...", tokenSecret: "..." }
+ * };
+ * const creds = getAuthCredentials(options.auth);
+ * ```
+ */
+declare function getAuthCredentials(options?: ModalSandboxOptions["auth"]): ModalCredentials;
+//#endregion
+export { type ModalCredentials, ModalSandbox, ModalSandboxError, type ModalSandboxErrorCode, type ModalSandboxOptions, getAuthCredentials };
+//# sourceMappingURL=index.d.ts.map