@langchain/modal 0.0.1

package/dist/index.js

@@ -0,0 +1,633 @@
+import { ModalClient } from "modal";
+import { BaseSandbox } from "deepagents";
+
+//#region src/auth.ts
+/**
+* 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);
+* ```
+*/
+function getAuthCredentials(options) {
+	const tokenId = options?.tokenId || process.env.MODAL_TOKEN_ID;
+	const tokenSecret = options?.tokenSecret || process.env.MODAL_TOKEN_SECRET;
+	const missingTokenId = !tokenId;
+	const missingTokenSecret = !tokenSecret;
+	if (missingTokenId || missingTokenSecret) {
+		const missing = [];
+		if (missingTokenId) missing.push("MODAL_TOKEN_ID");
+		if (missingTokenSecret) missing.push("MODAL_TOKEN_SECRET");
+		throw new Error(`Modal authentication required. Missing: ${missing.join(", ")}.\n\nProvide credentials using one of these methods:
+
+1. Set environment variables:
+   Go to https://modal.com/settings/tokens
+   Create a new token and run:
+   export MODAL_TOKEN_ID=your_token_id
+   export MODAL_TOKEN_SECRET=your_token_secret
+
+2. Pass credentials directly in options:
+   new ModalSandbox({ auth: { tokenId: '...', tokenSecret: '...' } })`);
+	}
+	return {
+		tokenId,
+		tokenSecret
+	};
+}
+
+//#endregion
+//#region src/types.ts
+const MODAL_SANDBOX_ERROR_SYMBOL = Symbol.for("modal.sandbox.error");
+/**
+* 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;
+*     }
+*   }
+* }
+* ```
+*/
+var ModalSandboxError = class ModalSandboxError extends Error {
+	[MODAL_SANDBOX_ERROR_SYMBOL];
+	/** Error name for instanceof checks and logging */
+	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, code, cause) {
+		super(message);
+		this.code = code;
+		this.cause = cause;
+		Object.setPrototypeOf(this, ModalSandboxError.prototype);
+	}
+	/**
+	* 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) {
+		return typeof error === "object" && error !== null && error[MODAL_SANDBOX_ERROR_SYMBOL] === true;
+	}
+};
+
+//#endregion
+//#region src/sandbox.ts
+/**
+* Modal Sandbox implementation of the SandboxBackendProtocol.
+*
+* This module provides a Modal Sandbox backend for deepagents, enabling agents
+* to execute commands, read/write files, and manage isolated container
+* environments using Modal's serverless infrastructure.
+*
+* @packageDocumentation
+*/
+/**
+* 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,
+* });
+* ```
+*/
+var ModalSandbox = class ModalSandbox extends BaseSandbox {
+	/** Private reference to the Modal client */
+	#client = null;
+	/** Private reference to the Modal App */
+	#app = null;
+	/** Private reference to the underlying Modal Sandbox instance */
+	#sandbox = null;
+	/** Configuration options for this sandbox */
+	#options;
+	/** Unique identifier for this sandbox instance */
+	#id;
+	/**
+	* Get the unique identifier for this sandbox.
+	*
+	* Before initialization, returns a temporary ID.
+	* After initialization, returns the actual Modal sandbox ID.
+	*/
+	get id() {
+		return this.#id;
+	}
+	/**
+	* 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() {
+		if (!this.#sandbox) throw new ModalSandboxError("Sandbox not initialized. Call initialize() or use ModalSandbox.create()", "NOT_INITIALIZED");
+		return this.#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() {
+		if (!this.#client) throw new ModalSandboxError("Sandbox not initialized. Call initialize() or use ModalSandbox.create()", "NOT_INITIALIZED");
+		return this.#client;
+	}
+	/**
+	* Check if the sandbox is initialized and running.
+	*/
+	get isRunning() {
+		return this.#sandbox !== null;
+	}
+	/**
+	* 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 = {}) {
+		super();
+		this.#options = {
+			appName: "deepagents-sandbox",
+			imageName: "alpine:3.21",
+			...options
+		};
+		this.#id = `modal-sandbox-${Date.now()}`;
+	}
+	/**
+	* 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}`);
+	* ```
+	*/
+	async initialize() {
+		if (this.#sandbox) throw new ModalSandboxError("Sandbox is already initialized. Each ModalSandbox instance can only be initialized once.", "ALREADY_INITIALIZED");
+		try {
+			getAuthCredentials(this.#options.auth);
+		} catch (error) {
+			throw new ModalSandboxError("Failed to authenticate with Modal. Check your token configuration.", "AUTHENTICATION_FAILED", error instanceof Error ? error : void 0);
+		}
+		try {
+			this.#client = new ModalClient();
+			this.#app = await this.#client.apps.fromName(this.#options.appName ?? "deepagents-sandbox", { createIfMissing: true });
+			const image = this.#client.images.fromRegistry(this.#options.imageName ?? "alpine:3.21");
+			const { appName: _appName, imageName: _imageName, initialFiles: _initialFiles, auth: _auth, volumes: volumeNames, secrets: secretNames, ...sdkOptions } = this.#options;
+			const createOptions = { ...sdkOptions };
+			if (volumeNames !== void 0) {
+				const volumeObjects = {};
+				for (const [mountPath, volumeName] of Object.entries(volumeNames)) volumeObjects[mountPath] = await this.#client.volumes.fromName(volumeName, { createIfMissing: false });
+				createOptions.volumes = volumeObjects;
+			}
+			if (secretNames !== void 0 && secretNames.length > 0) {
+				const secretObjects = [];
+				for (const secretName of secretNames) {
+					const secret = await this.#client.secrets.fromName(secretName);
+					secretObjects.push(secret);
+				}
+				createOptions.secrets = secretObjects;
+			}
+			this.#sandbox = await this.#client.sandboxes.create(this.#app, image, createOptions);
+			this.#id = this.#sandbox.sandboxId;
+			if (this.#options.initialFiles) await this.#uploadInitialFiles(this.#options.initialFiles);
+		} catch (error) {
+			if (ModalSandboxError.isInstance(error)) throw error;
+			throw new ModalSandboxError(`Failed to create Modal Sandbox: ${error instanceof Error ? error.message : String(error)}`, "SANDBOX_CREATION_FAILED", error instanceof Error ? error : void 0);
+		}
+	}
+	/**
+	* Upload initial files to the sandbox during initialization.
+	* This is a private helper method used by initialize().
+	*
+	* @param files - Record of file paths to contents
+	*/
+	async #uploadInitialFiles(files) {
+		const encoder = new TextEncoder();
+		const filesToUpload = [];
+		for (const [filePath, content] of Object.entries(files)) {
+			const normalizedPath = filePath.startsWith("/") ? filePath.slice(1) : filePath;
+			const data = typeof content === "string" ? encoder.encode(content) : content;
+			filesToUpload.push([normalizedPath, data]);
+		}
+		const errors = (await this.uploadFiles(filesToUpload)).filter((r) => r.error !== null);
+		if (errors.length > 0) throw new ModalSandboxError(`Failed to upload initial files: ${errors.map((e) => e.path).join(", ")}`, "FILE_OPERATION_FAILED");
+	}
+	/**
+	* 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
+	* ```
+	*/
+	async execute(command) {
+		const sandbox = this.instance;
+		try {
+			const process = await sandbox.exec([
+				"bash",
+				"-c",
+				command
+			], {
+				stdout: "pipe",
+				stderr: "pipe"
+			});
+			const [stdout, stderr] = await Promise.all([process.stdout.readText(), process.stderr.readText()]);
+			const exitCode = await process.wait();
+			return {
+				output: stdout + stderr,
+				exitCode: exitCode ?? 0,
+				truncated: false
+			};
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("timeout")) throw new ModalSandboxError(`Command timed out: ${command}`, "COMMAND_TIMEOUT", error);
+			throw new ModalSandboxError(`Command execution failed: ${error instanceof Error ? error.message : String(error)}`, "COMMAND_FAILED", error instanceof Error ? error : void 0);
+		}
+	}
+	/**
+	* 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"}')],
+	* ]);
+	* ```
+	*/
+	async uploadFiles(files) {
+		const sandbox = this.instance;
+		const results = [];
+		for (const [path, content] of files) try {
+			const parentDir = path.substring(0, path.lastIndexOf("/"));
+			if (parentDir) await sandbox.exec([
+				"mkdir",
+				"-p",
+				parentDir
+			], {
+				stdout: "pipe",
+				stderr: "pipe"
+			}).then((p) => p.wait());
+			const writeHandle = await sandbox.open(path, "w");
+			await writeHandle.write(content);
+			await writeHandle.close();
+			results.push({
+				path,
+				error: null
+			});
+		} catch (error) {
+			results.push({
+				path,
+				error: this.#mapError(error)
+			});
+		}
+		return results;
+	}
+	/**
+	* 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}`);
+	*   }
+	* }
+	* ```
+	*/
+	async downloadFiles(paths) {
+		const sandbox = this.instance;
+		const results = [];
+		for (const path of paths) try {
+			const readHandle = await sandbox.open(path, "r");
+			const content = await readHandle.read();
+			await readHandle.close();
+			results.push({
+				path,
+				content: new Uint8Array(content),
+				error: null
+			});
+		} catch (error) {
+			results.push({
+				path,
+				content: null,
+				error: this.#mapError(error)
+			});
+		}
+		return results;
+	}
+	/**
+	* 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();
+	* }
+	* ```
+	*/
+	async close() {
+		if (this.#sandbox) try {
+			await this.#sandbox.terminate();
+		} finally {
+			this.#sandbox = null;
+			this.#app = null;
+			this.#client = null;
+		}
+	}
+	/**
+	* Terminate the sandbox.
+	*
+	* Alias for close() for Modal SDK compatibility.
+	*
+	* @example
+	* ```typescript
+	* await sandbox.terminate();
+	* ```
+	*/
+	async terminate() {
+		await this.close();
+	}
+	/**
+	* Alias for close() to maintain compatibility with other sandbox implementations.
+	*/
+	async stop() {
+		await this.close();
+	}
+	/**
+	* 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
+	*/
+	async poll() {
+		if (!this.#sandbox) return null;
+		return this.#sandbox.poll();
+	}
+	/**
+	* Wait for the sandbox to finish running.
+	*
+	* @returns The exit code of the sandbox
+	* @throws {ModalSandboxError} If the sandbox is not initialized
+	*/
+	async wait() {
+		return this.instance.wait();
+	}
+	/**
+	* Set the sandbox from an existing Modal Sandbox instance.
+	* Used internally by the static `fromId()` and `fromName()` methods.
+	*/
+	#setFromExisting(client, existingSandbox, sandboxId) {
+		this.#client = client;
+		this.#sandbox = existingSandbox;
+		this.#id = sandboxId;
+	}
+	/**
+	* Map Modal SDK errors to standardized FileOperationError codes.
+	*
+	* @param error - The error from the Modal SDK
+	* @returns A standardized error code
+	*/
+	#mapError(error) {
+		if (error instanceof Error) {
+			const msg = error.message.toLowerCase();
+			if (msg.includes("not found") || msg.includes("enoent")) return "file_not_found";
+			if (msg.includes("permission") || msg.includes("eacces")) return "permission_denied";
+			if (msg.includes("directory") || msg.includes("eisdir")) return "is_directory";
+		}
+		return "invalid_path";
+	}
+	/**
+	* 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 async create(options) {
+		const sandbox = new ModalSandbox(options);
+		await sandbox.initialize();
+		return sandbox;
+	}
+	/**
+	* 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 async fromId(sandboxId, options) {
+		try {
+			getAuthCredentials(options?.auth);
+		} catch (error) {
+			throw new ModalSandboxError("Failed to authenticate with Modal. Check your token configuration.", "AUTHENTICATION_FAILED", error instanceof Error ? error : void 0);
+		}
+		try {
+			const client = new ModalClient();
+			const existingSandbox = await client.sandboxes.fromId(sandboxId);
+			const modalSandbox = new ModalSandbox(options);
+			modalSandbox.#setFromExisting(client, existingSandbox, sandboxId);
+			return modalSandbox;
+		} catch (error) {
+			throw new ModalSandboxError(`Sandbox not found: ${sandboxId}`, "SANDBOX_NOT_FOUND", error instanceof Error ? error : void 0);
+		}
+	}
+	/**
+	* 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 async fromName(appName, sandboxName, options) {
+		try {
+			getAuthCredentials(options?.auth);
+		} catch (error) {
+			throw new ModalSandboxError("Failed to authenticate with Modal. Check your token configuration.", "AUTHENTICATION_FAILED", error instanceof Error ? error : void 0);
+		}
+		try {
+			const client = new ModalClient();
+			const existingSandbox = await client.sandboxes.fromName(appName, sandboxName);
+			const modalSandbox = new ModalSandbox(options);
+			modalSandbox.#setFromExisting(client, existingSandbox, existingSandbox.sandboxId);
+			return modalSandbox;
+		} catch (error) {
+			throw new ModalSandboxError(`Sandbox not found: ${appName}/${sandboxName}`, "SANDBOX_NOT_FOUND", error instanceof Error ? error : void 0);
+		}
+	}
+};
+
+//#endregion
+export { ModalSandbox, ModalSandboxError, getAuthCredentials };
+//# sourceMappingURL=index.js.map