@langchain/daytona 0.0.1

package/dist/index.js

@@ -0,0 +1,689 @@
+import { Daytona } from "@daytonaio/sdk";
+import { BaseSandbox } from "deepagents";
+
+//#region src/auth.ts
+/** Default Daytona API URL */
+const DEFAULT_API_URL = "https://app.daytona.io/api";
+/**
+* Get the API key for Daytona API.
+*
+* Authentication is resolved in the following priority order:
+*
+* 1. **Explicit API key**: If `options.apiKey` is provided, it is used directly.
+* 2. **DAYTONA_API_KEY**: Environment variable for Daytona API key.
+*
+* If no API key is found, an error is thrown with setup instructions.
+*
+* ## Environment Variable Setup
+*
+* ```bash
+* # Get your API key from https://app.daytona.io
+* export DAYTONA_API_KEY=your_api_key_here
+* ```
+*
+* @param options - Optional authentication configuration from DaytonaSandboxOptions
+* @returns The API key string
+* @throws {Error} If no API key is available
+*
+* @example
+* ```typescript
+* // With explicit API key
+* const apiKey = getAuthApiKey({ apiKey: "my-api-key" });
+*
+* // Using environment variables (auto-detected)
+* const apiKey = getAuthApiKey();
+*
+* // From DaytonaSandboxOptions
+* const options: DaytonaSandboxOptions = {
+*   auth: { apiKey: "my-api-key" }
+* };
+* const apiKey = getAuthApiKey(options.auth);
+* ```
+*/
+function getAuthApiKey(options) {
+	if (options?.apiKey) return options.apiKey;
+	const apiKey = process.env.DAYTONA_API_KEY;
+	if (apiKey) return apiKey;
+	throw new Error("Daytona authentication required. Provide an API key using one of these methods:\n\n1. Set DAYTONA_API_KEY environment variable:\n   Get your API key from https://app.daytona.io\n   Run: export DAYTONA_API_KEY=your_api_key_here\n\n2. Pass API key directly in options:\n   new DaytonaSandbox({ auth: { apiKey: '...' } })");
+}
+/**
+* Get the API URL for Daytona API.
+*
+* URL is resolved in the following priority order:
+*
+* 1. **Explicit API URL**: If `options.apiUrl` is provided, it is used directly.
+* 2. **DAYTONA_API_URL**: Environment variable for Daytona API URL.
+* 3. **Default**: Uses the default Daytona API URL.
+*
+* @param options - Optional authentication configuration from DaytonaSandboxOptions
+* @returns The API URL string
+*/
+function getAuthApiUrl(options) {
+	if (options?.apiUrl) return options.apiUrl;
+	const apiUrl = process.env.DAYTONA_API_URL;
+	if (apiUrl) return apiUrl;
+	return DEFAULT_API_URL;
+}
+/**
+* Get authentication credentials for Daytona API.
+*
+* This function returns the credentials needed for the Daytona SDK.
+*
+* @param options - Optional authentication configuration from DaytonaSandboxOptions
+* @param target - Optional target region
+* @returns Complete authentication credentials
+* @throws {Error} If no API key is available
+*/
+function getAuthCredentials(options, target) {
+	return {
+		apiKey: getAuthApiKey(options),
+		apiUrl: getAuthApiUrl(options),
+		target: target ?? process.env.DAYTONA_TARGET
+	};
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* Custom error class for Daytona 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 DaytonaSandboxError) {
+*     switch (error.code) {
+*       case "NOT_INITIALIZED":
+*         await sandbox.initialize();
+*         break;
+*       case "COMMAND_TIMEOUT":
+*         console.error("Command took too long");
+*         break;
+*       default:
+*         throw error;
+*     }
+*   }
+* }
+* ```
+*/
+var DaytonaSandboxError = class DaytonaSandboxError extends Error {
+	/** Error name for instanceof checks and logging */
+	name = "DaytonaSandboxError";
+	/**
+	* Creates a new DaytonaSandboxError.
+	*
+	* @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, DaytonaSandboxError.prototype);
+	}
+};
+
+//#endregion
+//#region src/sandbox.ts
+/**
+* Daytona Sandbox implementation of the SandboxBackendProtocol.
+*
+* This module provides a Daytona Sandbox backend for deepagents, enabling agents
+* to execute commands, read/write files, and manage isolated sandbox environments
+* using Daytona's infrastructure.
+*
+* @packageDocumentation
+*/
+/**
+* Daytona Sandbox backend for deepagents.
+*
+* Extends `BaseSandbox` to provide command execution, file operations, and
+* sandbox lifecycle management using Daytona's SDK.
+*
+* ## Basic Usage
+*
+* ```typescript
+* import { DaytonaSandbox } from "@langchain/daytona";
+*
+* // Create and initialize a sandbox
+* const sandbox = await DaytonaSandbox.create({
+*   language: "typescript",
+*   timeout: 300,
+* });
+*
+* try {
+*   // Execute commands
+*   const result = await sandbox.execute("node --version");
+*   console.log(result.output);
+* } finally {
+*   // Always cleanup
+*   await sandbox.close();
+* }
+* ```
+*
+* ## Using with DeepAgent
+*
+* ```typescript
+* import { createDeepAgent } from "deepagents";
+* import { DaytonaSandbox } from "@langchain/daytona";
+*
+* const sandbox = await DaytonaSandbox.create();
+*
+* const agent = createDeepAgent({
+*   model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
+*   systemPrompt: "You are a coding assistant with sandbox access.",
+*   backend: sandbox,
+* });
+* ```
+*/
+var DaytonaSandbox = class DaytonaSandbox extends BaseSandbox {
+	/** Private reference to the Daytona client */
+	#daytona = null;
+	/** Private reference to the underlying Daytona Sandbox instance */
+	#sandbox = null;
+	/** Configuration options for this sandbox */
+	#options;
+	/** Unique identifier for this sandbox instance */
+	#id;
+	/** Default timeout for command execution in seconds */
+	#timeout;
+	/**
+	* Get the unique identifier for this sandbox.
+	*
+	* Before initialization, returns a temporary ID.
+	* After initialization, returns the actual Daytona sandbox ID.
+	*/
+	get id() {
+		return this.#id;
+	}
+	/**
+	* Get the underlying Daytona Sandbox instance.
+	*
+	* @throws {DaytonaSandboxError} If the sandbox is not initialized
+	*
+	* @example
+	* ```typescript
+	* const sandbox = await DaytonaSandbox.create();
+	* const daytonaSdk = sandbox.sandbox; // Access the raw SDK
+	* ```
+	*/
+	get sandbox() {
+		if (!this.#sandbox) throw new DaytonaSandboxError("Sandbox not initialized. Call initialize() or use DaytonaSandbox.create()", "NOT_INITIALIZED");
+		return this.#sandbox;
+	}
+	/**
+	* Check if the sandbox is initialized and running.
+	*/
+	get isRunning() {
+		return this.#sandbox !== null;
+	}
+	/**
+	* Create a new DaytonaSandbox instance.
+	*
+	* Note: This only creates the instance. Call `initialize()` to actually
+	* create the Daytona Sandbox, or use the static `DaytonaSandbox.create()` method.
+	*
+	* @param options - Configuration options for the sandbox
+	*
+	* @example
+	* ```typescript
+	* // Two-step initialization
+	* const sandbox = new DaytonaSandbox({ language: "typescript" });
+	* await sandbox.initialize();
+	*
+	* // Or use the factory method
+	* const sandbox = await DaytonaSandbox.create({ language: "typescript" });
+	* ```
+	*/
+	constructor(options = {}) {
+		super();
+		this.#options = {
+			language: "typescript",
+			timeout: 300,
+			...options
+		};
+		this.#timeout = this.#options.timeout ?? 300;
+		this.#id = `daytona-sandbox-${Date.now()}`;
+	}
+	/**
+	* Initialize the sandbox by creating a new Daytona Sandbox instance.
+	*
+	* This method authenticates with Daytona and provisions a new sandbox.
+	* After initialization, the `id` property will reflect the actual sandbox ID.
+	*
+	* @throws {DaytonaSandboxError} If already initialized (`ALREADY_INITIALIZED`)
+	* @throws {DaytonaSandboxError} If authentication fails (`AUTHENTICATION_FAILED`)
+	* @throws {DaytonaSandboxError} If sandbox creation fails (`SANDBOX_CREATION_FAILED`)
+	*
+	* @example
+	* ```typescript
+	* const sandbox = new DaytonaSandbox();
+	* await sandbox.initialize();
+	* console.log(`Sandbox ID: ${sandbox.id}`);
+	* ```
+	*/
+	async initialize() {
+		if (this.#sandbox) throw new DaytonaSandboxError("Sandbox is already initialized. Each DaytonaSandbox instance can only be initialized once.", "ALREADY_INITIALIZED");
+		let credentials;
+		try {
+			credentials = getAuthCredentials(this.#options.auth, this.#options.target);
+		} catch (error) {
+			throw new DaytonaSandboxError("Failed to authenticate with Daytona. Check your API key configuration.", "AUTHENTICATION_FAILED", error instanceof Error ? error : void 0);
+		}
+		try {
+			this.#daytona = new Daytona({
+				apiKey: credentials.apiKey,
+				apiUrl: credentials.apiUrl,
+				target: credentials.target
+			});
+			if (this.#options.image) {
+				const createOptions = {
+					image: this.#options.image,
+					language: this.#options.language ?? "typescript"
+				};
+				if (this.#options.envVars) createOptions.envVars = this.#options.envVars;
+				if (this.#options.autoStopInterval !== void 0) createOptions.autoStopInterval = this.#options.autoStopInterval;
+				if (this.#options.labels) createOptions.labels = this.#options.labels;
+				if (this.#options.resources) createOptions.resources = this.#options.resources;
+				this.#sandbox = await this.#daytona.create(createOptions);
+			} else {
+				const createOptions = { language: this.#options.language ?? "typescript" };
+				if (this.#options.snapshot) createOptions.snapshot = this.#options.snapshot;
+				if (this.#options.envVars) createOptions.envVars = this.#options.envVars;
+				if (this.#options.autoStopInterval !== void 0) createOptions.autoStopInterval = this.#options.autoStopInterval;
+				if (this.#options.labels) createOptions.labels = this.#options.labels;
+				this.#sandbox = await this.#daytona.create(createOptions);
+			}
+			this.#id = this.#sandbox.id;
+			if (this.#options.initialFiles) await this.#uploadInitialFiles(this.#options.initialFiles);
+		} catch (error) {
+			throw new DaytonaSandboxError(`Failed to create Daytona Sandbox: ${error instanceof Error ? error.message : String(error)}`, "SANDBOX_CREATION_FAILED", error instanceof Error ? error : void 0);
+		}
+	}
+	/**
+	* Upload initial files to the sandbox.
+	*
+	* @param files - A map of file paths to their string contents
+	*/
+	async #uploadInitialFiles(files) {
+		const encoder = new TextEncoder();
+		const fileEntries = Object.entries(files).map(([path, content]) => [path, encoder.encode(content)]);
+		const errors = (await this.uploadFiles(fileEntries)).filter((r) => r.error !== null);
+		if (errors.length > 0) throw new DaytonaSandboxError(`Failed to upload initial files: ${errors.map((e) => `${e.path}: ${e.error}`).join(", ")}`, "FILE_OPERATION_FAILED");
+	}
+	/**
+	* Execute a command in the sandbox.
+	*
+	* Commands are run using the sandbox's shell.
+	*
+	* @param command - The shell command to execute
+	* @returns Execution result with output, exit code, and truncation flag
+	* @throws {DaytonaSandboxError} 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.sandbox;
+		try {
+			const response = await sandbox.process.executeCommand(command, void 0, void 0, this.#timeout);
+			return {
+				output: response.result ?? "",
+				exitCode: response.exitCode ?? 0,
+				truncated: false
+			};
+		} catch (error) {
+			if (error instanceof Error && error.message.includes("timeout")) throw new DaytonaSandboxError(`Command timed out: ${command}`, "COMMAND_TIMEOUT", error);
+			throw new DaytonaSandboxError(`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. 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.sandbox;
+		const results = [];
+		for (const [path, content] of files) try {
+			const parentDir = path.substring(0, path.lastIndexOf("/"));
+			if (parentDir) await sandbox.fs.createFolder(parentDir, "755");
+			const buffer = Buffer.from(content);
+			await sandbox.fs.uploadFile(buffer, path);
+			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, 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.sandbox;
+		const results = [];
+		for (const path of paths) try {
+			const buffer = await sandbox.fs.downloadFile(path);
+			results.push({
+				path,
+				content: new Uint8Array(buffer),
+				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. The sandbox is deleted
+	* from Daytona's infrastructure.
+	*
+	* @example
+	* ```typescript
+	* try {
+	*   await sandbox.execute("npm run build");
+	* } finally {
+	*   await sandbox.close();
+	* }
+	* ```
+	*/
+	async close() {
+		if (this.#sandbox) try {
+			await this.#sandbox.delete();
+		} finally {
+			this.#sandbox = null;
+			this.#daytona = null;
+		}
+	}
+	/**
+	* Stop the sandbox without deleting it.
+	*
+	* The sandbox can be restarted later using `start()`.
+	*
+	* @example
+	* ```typescript
+	* await sandbox.stop();
+	* // Later...
+	* await sandbox.start();
+	* ```
+	*/
+	async stop() {
+		if (this.#sandbox) await this.#sandbox.stop();
+	}
+	/**
+	* Start a stopped sandbox.
+	*
+	* @param timeout - Maximum time to wait in seconds (default: 60)
+	*
+	* @example
+	* ```typescript
+	* await sandbox.start();
+	* console.log("Sandbox is now running");
+	* ```
+	*/
+	async start(timeout = 60) {
+		if (this.#sandbox) await this.#sandbox.start(timeout);
+	}
+	/**
+	* Forcefully terminate and delete the sandbox.
+	*
+	* Use this when you need to immediately stop the sandbox.
+	*
+	* @example
+	* ```typescript
+	* await sandbox.kill();
+	* ```
+	*/
+	async kill() {
+		await this.close();
+	}
+	/**
+	* Get the working directory path inside the sandbox.
+	*
+	* @returns The absolute path to the sandbox working directory
+	*
+	* @example
+	* ```typescript
+	* const workDir = await sandbox.getWorkDir();
+	* console.log(`Working directory: ${workDir}`);
+	* ```
+	*/
+	async getWorkDir() {
+		return await this.sandbox.getWorkDir() ?? "/home/daytona";
+	}
+	/**
+	* Get the user's home directory path inside the sandbox.
+	*
+	* @returns The absolute path to the user's home directory
+	*
+	* @example
+	* ```typescript
+	* const homeDir = await sandbox.getUserHomeDir();
+	* console.log(`Home directory: ${homeDir}`);
+	* ```
+	*/
+	async getUserHomeDir() {
+		return await this.sandbox.getUserHomeDir() ?? "/home/daytona";
+	}
+	/**
+	* Set the sandbox from an existing Daytona Sandbox instance.
+	* Used internally by the static `connect()` method.
+	*/
+	#setFromExisting(daytona, existingSandbox, sandboxId) {
+		this.#daytona = daytona;
+		this.#sandbox = existingSandbox;
+		this.#id = sandboxId;
+	}
+	/**
+	* Map Daytona SDK errors to standardized FileOperationError codes.
+	*
+	* @param error - The error from the Daytona 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 DaytonaSandbox 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 DaytonaSandbox.create({
+	*   language: "typescript",
+	*   cpu: 2,
+	*   memory: 4,
+	* });
+	* ```
+	*/
+	static async create(options) {
+		const sandbox = new DaytonaSandbox(options);
+		await sandbox.initialize();
+		return sandbox;
+	}
+	/**
+	* Connect to an existing sandbox by ID.
+	*
+	* This allows you to resume working with a sandbox that was created
+	* earlier or that is still running.
+	*
+	* @param sandboxId - The ID of the sandbox to connect to
+	* @param options - Optional auth configuration (for API key)
+	* @returns A connected sandbox instance
+	*
+	* @example
+	* ```typescript
+	* // Resume a sandbox from a stored ID
+	* const sandbox = await DaytonaSandbox.connect("sandbox-abc123");
+	* const result = await sandbox.execute("ls -la");
+	* ```
+	*/
+	static async connect(sandboxId, options) {
+		let credentials;
+		try {
+			credentials = getAuthCredentials(options?.auth, options?.target);
+		} catch (error) {
+			throw new DaytonaSandboxError("Failed to authenticate with Daytona. Check your API key configuration.", "AUTHENTICATION_FAILED", error instanceof Error ? error : void 0);
+		}
+		try {
+			const daytona = new Daytona({
+				apiKey: credentials.apiKey,
+				apiUrl: credentials.apiUrl,
+				target: credentials.target
+			});
+			const existingSandbox = await daytona.get(sandboxId);
+			const daytonaSandbox = new DaytonaSandbox(options);
+			daytonaSandbox.#setFromExisting(daytona, existingSandbox, sandboxId);
+			return daytonaSandbox;
+		} catch (error) {
+			throw new DaytonaSandboxError(`Sandbox not found: ${sandboxId}`, "SANDBOX_NOT_FOUND", error instanceof Error ? error : void 0);
+		}
+	}
+};
+/**
+* Create an async factory function that creates a new Daytona Sandbox per invocation.
+*
+* Each call to the factory will create and initialize a new sandbox.
+* This is useful when you want fresh, isolated environments for each
+* agent invocation.
+*
+* **Important**: This returns an async factory. For use with middleware that
+* requires synchronous BackendFactory, use `createDaytonaSandboxFactoryFromSandbox()`
+* with a pre-created sandbox instead.
+*
+* @param options - Optional configuration for sandbox creation
+* @returns An async factory function that creates new sandboxes
+*
+* @example
+* ```typescript
+* import { DaytonaSandbox, createDaytonaSandboxFactory } from "@langchain/daytona";
+*
+* // Create a factory for new sandboxes
+* const factory = createDaytonaSandboxFactory({ language: "typescript" });
+*
+* // Each call creates a new sandbox
+* const sandbox1 = await factory();
+* const sandbox2 = await factory();
+*
+* try {
+*   // Use sandboxes...
+* } finally {
+*   await sandbox1.close();
+*   await sandbox2.close();
+* }
+* ```
+*/
+function createDaytonaSandboxFactory(options) {
+	return async () => {
+		return await DaytonaSandbox.create(options);
+	};
+}
+/**
+* Create a backend factory that reuses an existing Daytona Sandbox.
+*
+* This allows multiple agent invocations to share the same sandbox,
+* avoiding the startup overhead of creating new sandboxes.
+*
+* Important: You are responsible for managing the sandbox lifecycle
+* (calling `close()` when done).
+*
+* @param sandbox - An existing DaytonaSandbox instance (must be initialized)
+* @returns A BackendFactory that returns the provided sandbox
+*
+* @example
+* ```typescript
+* import { createDeepAgent, createFilesystemMiddleware } from "deepagents";
+* import { DaytonaSandbox, createDaytonaSandboxFactoryFromSandbox } from "@langchain/daytona";
+*
+* // Create and initialize a sandbox
+* const sandbox = await DaytonaSandbox.create({ language: "typescript" });
+*
+* try {
+*   const agent = createDeepAgent({
+*     model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
+*     systemPrompt: "You are a coding assistant.",
+*     middlewares: [
+*       createFilesystemMiddleware({
+*         backend: createDaytonaSandboxFactoryFromSandbox(sandbox),
+*       }),
+*     ],
+*   });
+*
+*   await agent.invoke({ messages: [...] });
+* } finally {
+*   await sandbox.close();
+* }
+* ```
+*/
+function createDaytonaSandboxFactoryFromSandbox(sandbox) {
+	return () => sandbox;
+}
+
+//#endregion
+export { DaytonaSandbox, DaytonaSandboxError, createDaytonaSandboxFactory, createDaytonaSandboxFactoryFromSandbox, getAuthApiKey, getAuthApiUrl, getAuthCredentials };
+//# sourceMappingURL=index.js.map