@langchain/deno 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,576 @@
+import { Sandbox } from "@deno/sandbox";
+import { BackendFactory, BaseSandbox, EditResult, ExecuteResponse, FileDownloadResponse, FileUploadResponse, WriteResult } from "deepagents";
+
+//#region src/types.d.ts
+/**
+ * Type definitions for the Deno Sandbox backend.
+ *
+ * This module contains all type definitions for the @langchain/deno package,
+ * including options and error types.
+ */
+/**
+ * Supported regions for Deno Deploy sandboxes.
+ *
+ * Currently available regions:
+ * - `ams`: Amsterdam
+ * - `ord`: Chicago
+ */
+type DenoSandboxRegion = "ams" | "ord";
+/**
+ * Sandbox lifetime configuration.
+ *
+ * - `"session"`: Sandbox shuts down when you close/dispose the client (default)
+ * - Duration string: Keep sandbox alive for a specific time (e.g., "5m", "30s")
+ */
+type SandboxLifetime = "session" | `${number}s` | `${number}m`;
+/**
+ * Configuration options for creating a Deno Sandbox.
+ *
+ * @example
+ * ```typescript
+ * const options: DenoSandboxOptions = {
+ *   memoryMb: 1024, // 1GB memory
+ *   lifetime: "5m", // 5 minutes
+ *   region: "iad", // US East
+ * };
+ * ```
+ */
+interface DenoSandboxOptions {
+  /**
+   * Amount of memory allocated to the sandbox in megabytes.
+   *
+   * Memory limits:
+   * - Minimum: 768MB
+   * - Maximum: 4096MB
+   *
+   * @default 768
+   */
+  memoryMb?: number;
+  /**
+   * Sandbox lifetime configuration.
+   *
+   * - `"session"`: Sandbox shuts down when you close/dispose the client (default)
+   * - Duration string: Keep sandbox alive for a specific time (e.g., "5m", "30s")
+   *
+   * Supported duration suffixes: `s` (seconds), `m` (minutes).
+   *
+   * @default "session"
+   */
+  lifetime?: SandboxLifetime;
+  /**
+   * Region where the sandbox will be created.
+   *
+   * If not specified, the sandbox will be created in the default region.
+   *
+   * @see DenoSandboxRegion for available regions
+   */
+  region?: DenoSandboxRegion;
+  /**
+   * Initial files to create in the sandbox after initialization.
+   *
+   * A map of file paths to their contents. Files will be created
+   * in the sandbox filesystem before any commands are executed.
+   * Parent directories are created automatically.
+   *
+   * @example
+   * ```typescript
+   * const options: DenoSandboxOptions = {
+   *   memoryMb: 1024,
+   *   initialFiles: {
+   *     "/home/app/index.js": "console.log('Hello')",
+   *     "/home/app/package.json": '{"name": "test"}',
+   *   },
+   * };
+   * ```
+   */
+  initialFiles?: Record<string, string>;
+  /**
+   * Authentication configuration for Deno Deploy API.
+   *
+   * ### Environment Variable Setup
+   *
+   * ```bash
+   * # Go to https://app.deno.com -> Settings -> Organization Tokens
+   * # Create a new token and set it as environment variable
+   * export DENO_DEPLOY_TOKEN=your_token_here
+   * ```
+   *
+   * Or pass the token directly in this auth configuration.
+   */
+  auth?: {
+    /**
+     * Deno Deploy access token.
+     * If not provided, reads from `DENO_DEPLOY_TOKEN` environment variable.
+     */
+    token?: string;
+  };
+}
+/**
+ * Error codes for Deno Sandbox operations.
+ *
+ * Used to identify specific error conditions and handle them appropriately.
+ */
+type DenoSandboxErrorCode = /** 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";
+declare const DENO_SANDBOX_ERROR_SYMBOL: unique symbol;
+/**
+ * Custom error class for Deno 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 DenoSandboxError) {
+ *     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 DenoSandboxError extends Error {
+  readonly code: DenoSandboxErrorCode;
+  readonly cause?: Error | undefined;
+  [DENO_SANDBOX_ERROR_SYMBOL]: true;
+  /** Error name for instanceof checks and logging */
+  readonly name = "DenoSandboxError";
+  /**
+   * Creates a new DenoSandboxError.
+   *
+   * @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: DenoSandboxErrorCode, cause?: Error | undefined);
+  /**
+   * Checks if the error is an instance of DenoSandboxError.
+   *
+   * @param error - The error to check
+   * @returns True if the error is an instance of DenoSandboxError, false otherwise
+   */
+  static isInstance(error: unknown): error is DenoSandboxError;
+}
+//#endregion
+//#region src/sandbox.d.ts
+/**
+ * Deno Sandbox backend for deepagents.
+ *
+ * Extends `BaseSandbox` to provide command execution, file operations, and
+ * sandbox lifecycle management using Deno Deploy's Sandbox SDK.
+ *
+ * ## Basic Usage
+ *
+ * ```typescript
+ * import { DenoSandbox } from "@langchain/deno";
+ *
+ * // Create and initialize a sandbox
+ * const sandbox = await DenoSandbox.create({
+ *   memoryMb: 1024,
+ *   lifetime: "5m",
+ * });
+ *
+ * try {
+ *   // Execute commands
+ *   const result = await sandbox.execute("deno --version");
+ *   console.log(result.output);
+ * } finally {
+ *   // Always cleanup
+ *   await sandbox.close();
+ * }
+ * ```
+ *
+ * ## Using with DeepAgent
+ *
+ * ```typescript
+ * import { createDeepAgent } from "deepagents";
+ * import { DenoSandbox } from "@langchain/deno";
+ *
+ * const sandbox = await DenoSandbox.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 DenoSandbox extends BaseSandbox {
+  #private;
+  /**
+   * Get the unique identifier for this sandbox.
+   *
+   * Before initialization, returns a temporary ID.
+   * After initialization, returns the actual Deno sandbox ID.
+   */
+  get id(): string;
+  /**
+   * Get the underlying Deno Sandbox instance.
+   *
+   * @throws {DenoSandboxError} If the sandbox is not initialized
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await DenoSandbox.create();
+   * const denoSdk = sandbox.sandbox; // Access the raw SDK
+   * ```
+   */
+  get sandbox(): Sandbox;
+  /**
+   * Check if the sandbox is initialized and running.
+   */
+  get isRunning(): boolean;
+  /**
+   * Create a new DenoSandbox instance.
+   *
+   * Note: This only creates the instance. Call `initialize()` to actually
+   * create the Deno Sandbox, or use the static `DenoSandbox.create()` method.
+   *
+   * @param options - Configuration options for the sandbox
+   *
+   * @example
+   * ```typescript
+   * // Two-step initialization
+   * const sandbox = new DenoSandbox({ memoryMb: 1024 });
+   * await sandbox.initialize();
+   *
+   * // Or use the factory method
+   * const sandbox = await DenoSandbox.create({ memoryMb: 1024 });
+   * ```
+   */
+  constructor(options?: DenoSandboxOptions);
+  /**
+   * Initialize the sandbox by creating a new Deno Sandbox instance.
+   *
+   * This method authenticates with Deno Deploy and provisions a new microVM
+   * sandbox. After initialization, the `id` property will reflect the
+   * actual Deno sandbox ID.
+   *
+   * @throws {DenoSandboxError} If already initialized (`ALREADY_INITIALIZED`)
+   * @throws {DenoSandboxError} If authentication fails (`AUTHENTICATION_FAILED`)
+   * @throws {DenoSandboxError} If sandbox creation fails (`SANDBOX_CREATION_FAILED`)
+   *
+   * @example
+   * ```typescript
+   * const sandbox = new DenoSandbox();
+   * await sandbox.initialize();
+   * console.log(`Sandbox ID: ${sandbox.id}`);
+   * ```
+   */
+  initialize(): Promise<void>;
+  /**
+   * Execute a command in the sandbox.
+   *
+   * Commands are run using the sandbox's shell in the configured working directory.
+   *
+   * @param command - The shell command to execute
+   * @returns Execution result with output, exit code, and truncation flag
+   * @throws {DenoSandboxError} 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. 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, 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[]>;
+  /**
+   * Read a file's content with line numbers.
+   *
+   * Override of BaseSandbox.read() to use awk instead of Python,
+   * since Deno sandboxes don't have Python installed.
+   *
+   * @param filePath - Absolute path to the file
+   * @param offset - Line offset (0-indexed, default 0)
+   * @param limit - Maximum lines to return (default 500)
+   * @returns Formatted file content with line numbers, or error message
+   */
+  read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Create a new file with content.
+   *
+   * Override of BaseSandbox.write() to use shell commands instead of Python,
+   * since Deno sandboxes don't have Python installed.
+   *
+   * @param filePath - Absolute path for the new file
+   * @param content - File content to write
+   * @returns WriteResult with error populated on failure
+   */
+  write(filePath: string, content: string): Promise<WriteResult>;
+  /**
+   * Edit a file by replacing string occurrences.
+   *
+   * Override of BaseSandbox.edit() to use shell commands instead of Python,
+   * since Deno sandboxes don't have Python installed.
+   *
+   * Uses sed for in-place replacement with proper escaping.
+   *
+   * @param filePath - Absolute path to the file
+   * @param oldString - String to find and replace
+   * @param newString - Replacement string
+   * @param replaceAll - If true, replace all occurrences (default: false)
+   * @returns EditResult with error, path, and occurrences
+   */
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+  /**
+   * Close the sandbox and release all resources.
+   *
+   * After closing, the sandbox cannot be used again. Any unsaved data
+   * will be lost.
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   await sandbox.execute("deno run build.ts");
+   * } finally {
+   *   await sandbox.close();
+   * }
+   * ```
+   */
+  close(): Promise<void>;
+  /**
+   * Forcefully terminate the sandbox.
+   *
+   * Use this when you need to immediately stop the sandbox, even if
+   * operations are in progress.
+   *
+   * @example
+   * ```typescript
+   * await sandbox.kill();
+   * ```
+   */
+  kill(): Promise<void>;
+  /**
+   * Alias for close() to maintain compatibility with other sandbox implementations.
+   */
+  stop(): Promise<void>;
+  /**
+   * Create and initialize a new DenoSandbox 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 DenoSandbox.create({
+   *   memoryMb: 1024,
+   *   lifetime: "10m",
+   *   region: "iad",
+   * });
+   * ```
+   */
+  static create(options?: DenoSandboxOptions): Promise<DenoSandbox>;
+  /**
+   * Reconnect to an existing sandbox by ID.
+   *
+   * This allows you to resume working with a sandbox that was created
+   * earlier with a duration-based lifetime.
+   *
+   * @param sandboxId - The ID of the sandbox to reconnect to
+   * @param options - Optional auth configuration (for token)
+   * @returns A connected sandbox instance
+   *
+   * @example
+   * ```typescript
+   * // Resume a sandbox from a stored ID
+   * const sandbox = await DenoSandbox.connect("sandbox-abc123");
+   * const result = await sandbox.execute("ls -la");
+   * ```
+   */
+  static connect(sandboxId: string, options?: Pick<DenoSandboxOptions, "auth">): Promise<DenoSandbox>;
+}
+/**
+ * Async factory function type for creating Deno Sandbox instances.
+ *
+ * This is similar to BackendFactory but supports async creation,
+ * which is required for Deno Sandbox since initialization is async.
+ */
+type AsyncDenoSandboxFactory = () => Promise<DenoSandbox>;
+/**
+ * Create an async factory function that creates a new Deno 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 `createDenoSandboxFactoryFromSandbox()`
+ * 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 { DenoSandbox, createDenoSandboxFactory } from "@langchain/deno";
+ *
+ * // Create a factory for new sandboxes
+ * const factory = createDenoSandboxFactory({ memoryMb: 1024 });
+ *
+ * // Each call creates a new sandbox
+ * const sandbox1 = await factory();
+ * const sandbox2 = await factory();
+ *
+ * try {
+ *   // Use sandboxes...
+ * } finally {
+ *   await sandbox1.close();
+ *   await sandbox2.close();
+ * }
+ * ```
+ */
+declare function createDenoSandboxFactory(options?: DenoSandboxOptions): AsyncDenoSandboxFactory;
+/**
+ * Create a backend factory that reuses an existing Deno 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 DenoSandbox instance (must be initialized)
+ * @returns A BackendFactory that returns the provided sandbox
+ *
+ * @example
+ * ```typescript
+ * import { createDeepAgent, createFilesystemMiddleware } from "deepagents";
+ * import { DenoSandbox, createDenoSandboxFactoryFromSandbox } from "@langchain/deno";
+ *
+ * // Create and initialize a sandbox
+ * const sandbox = await DenoSandbox.create({ memoryMb: 1024 });
+ *
+ * try {
+ *   const agent = createDeepAgent({
+ *     model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
+ *     systemPrompt: "You are a coding assistant.",
+ *     middlewares: [
+ *       createFilesystemMiddleware({
+ *         backend: createDenoSandboxFactoryFromSandbox(sandbox),
+ *       }),
+ *     ],
+ *   });
+ *
+ *   await agent.invoke({ messages: [...] });
+ * } finally {
+ *   await sandbox.close();
+ * }
+ * ```
+ */
+declare function createDenoSandboxFactoryFromSandbox(sandbox: DenoSandbox): BackendFactory;
+//#endregion
+//#region src/auth.d.ts
+/**
+ * Authentication credentials for Deno Sandbox API.
+ */
+interface DenoCredentials {
+  /** Deno Deploy access token */
+  token: string;
+}
+/**
+ * Get the authentication token for Deno Sandbox API.
+ *
+ * Authentication is resolved in the following priority order:
+ *
+ * 1. **Explicit token**: If `options.token` is provided, it is used directly.
+ * 2. **DENO_DEPLOY_TOKEN**: Environment variable for Deno Deploy access token.
+ *
+ * If no token is found, an error is thrown with setup instructions.
+ *
+ * ## Environment Variable Setup
+ *
+ * ```bash
+ * # Go to https://app.deno.com -> Settings -> Organization Tokens
+ * # Create a new token and set it as environment variable
+ * export DENO_DEPLOY_TOKEN=your_token_here
+ * ```
+ *
+ * @param options - Optional authentication configuration from DenoSandboxOptions
+ * @returns The authentication token string
+ * @throws {Error} If no authentication token is available
+ *
+ * @example
+ * ```typescript
+ * // With explicit token
+ * const token = getAuthToken({ token: "my-token" });
+ *
+ * // Using environment variables (auto-detected)
+ * const token = getAuthToken();
+ *
+ * // From DenoSandboxOptions
+ * const options: DenoSandboxOptions = {
+ *   auth: { token: "my-token" }
+ * };
+ * const token = getAuthToken(options.auth);
+ * ```
+ */
+declare function getAuthToken(options?: DenoSandboxOptions["auth"]): string;
+/**
+ * Get authentication credentials for Deno Sandbox API.
+ *
+ * This function returns the credentials needed for the Deno SDK.
+ *
+ * @param options - Optional authentication configuration from DenoSandboxOptions
+ * @returns Complete authentication credentials
+ * @throws {Error} If no authentication token is available
+ */
+declare function getAuthCredentials(options?: DenoSandboxOptions["auth"]): DenoCredentials;
+//#endregion
+export { type AsyncDenoSandboxFactory, type DenoCredentials, DenoSandbox, DenoSandboxError, type DenoSandboxErrorCode, type DenoSandboxOptions, type DenoSandboxRegion, type SandboxLifetime, createDenoSandboxFactory, createDenoSandboxFactoryFromSandbox, getAuthCredentials, getAuthToken };
+//# sourceMappingURL=index.d.ts.map