@langchain/deno 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Sandbox } from "@deno/sandbox";
-import { BackendFactory, BaseSandbox, EditResult, ExecuteResponse, FileDownloadResponse, FileUploadResponse, SandboxError, SandboxErrorCode, WriteResult } from "deepagents";
+import { Memory, Region, Sandbox, SecretConfig, SnapshotId, SnapshotSlug, VolumeId, VolumeSlug } from "@deno/sandbox";
+import { BackendFactory, BaseSandbox, ExecuteResponse, FileDownloadResponse, FileUploadResponse, SandboxError, SandboxErrorCode } from "deepagents";
 
 //#region src/types.d.ts
 /**
@@ -9,23 +9,35 @@ import { BackendFactory, BaseSandbox, EditResult, ExecuteResponse, FileDownloadR
  * - `ams`: Amsterdam
  * - `ord`: Chicago
  */
-type DenoSandboxRegion = "ams" | "ord";
+type DenoSandboxRegion = Region;
 /**
  * Sandbox lifetime configuration.
  *
+ * @deprecated Use {@link SandboxTimeout} instead. This type will be removed in a future release.
+ *
  * - `"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`;
+/**
+ * Sandbox timeout configuration.
+ *
+ * - `"session"`: Sandbox shuts down when the primary client disconnects (default)
+ * - Duration string: Keep sandbox alive for a specific time (e.g., "600s", "20m")
+ *
+ * Note: when using a duration, the sandbox will be terminated after the specified
+ * time even if clients are still connected.
+ */
+type SandboxTimeout = "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
+ *   memory: "1GiB", // 1GB memory
+ *   timeout: "5m", // 5 minutes
+ *   region: "ord", // Chicago
  * };
  * ```
  */
@@ -33,6 +45,8 @@ interface DenoSandboxOptions {
   /**
    * Amount of memory allocated to the sandbox in megabytes.
    *
+   * @deprecated Use {@link DenoSandboxOptions.memory} instead. This option will be removed in a future release.
+   *
    * Memory limits:
    * - Minimum: 768MB
    * - Maximum: 4096MB
@@ -40,9 +54,24 @@ interface DenoSandboxOptions {
    * @default 768
    */
   memoryMb?: number;
+  /**
+   * The memory size of the sandbox. Supports plain numbers (interpreted as bytes)
+   * and human-readable strings with binary (GiB, MiB, KiB) or decimal (GB, MB, kB)
+   * units.
+   *
+   * Takes precedence over the deprecated `memoryMb` option.
+   *
+   * @example 1342177280
+   * @example "1GiB"
+   * @example "1280MiB"
+   * @default "1280MiB"
+   */
+  memory?: Memory;
   /**
    * Sandbox lifetime configuration.
    *
+   * @deprecated Use {@link DenoSandboxOptions.timeout} instead. This option will be removed in a future release.
+   *
    * - `"session"`: Sandbox shuts down when you close/dispose the client (default)
    * - Duration string: Keep sandbox alive for a specific time (e.g., "5m", "30s")
    *
@@ -51,6 +80,22 @@ interface DenoSandboxOptions {
    * @default "session"
    */
   lifetime?: SandboxLifetime;
+  /**
+   * The timeout of the sandbox. When not specified, it defaults to `"session"`.
+   *
+   * Takes precedence over the deprecated `lifetime` option.
+   *
+   * - `"session"`: Sandbox is destroyed when the primary client disconnects.
+   * - Duration string: Keep sandbox alive for a specific time (e.g., "600s", "20m").
+   *   Note that when this duration has passed, the sandbox will be terminated even
+   *   if there are still clients connected to it.
+   *
+   * @example "session"
+   * @example "600s"
+   * @example "20m"
+   * @default "session"
+   */
+  timeout?: SandboxTimeout;
   /**
    * Region where the sandbox will be created.
    *
@@ -69,7 +114,7 @@ interface DenoSandboxOptions {
    * @example
    * ```typescript
    * const options: DenoSandboxOptions = {
-   *   memoryMb: 1024,
+   *   memory: "1GiB",
    *   initialFiles: {
    *     "/home/app/index.js": "console.log('Hello')",
    *     "/home/app/package.json": '{"name": "test"}',
@@ -81,6 +126,9 @@ interface DenoSandboxOptions {
   /**
    * Authentication configuration for Deno Deploy API.
    *
+   * @deprecated Use the top-level {@link DenoSandboxOptions.token} and {@link DenoSandboxOptions.org} options instead.
+   * This option will be removed in a future release.
+   *
    * ### Environment Variable Setup
    *
    * ```bash
@@ -98,6 +146,148 @@ interface DenoSandboxOptions {
      */
     token?: string;
   };
+  /**
+   * The Deno Deploy access token that should be used to authenticate requests.
+   *
+   * - When passing an organization token (starts with `ddo_`), no further
+   *   organization information is required.
+   * - When passing a personal token (starts with `ddp_`), the `org` option
+   *   must also be provided.
+   *
+   * If not provided, the `DENO_DEPLOY_TOKEN` environment variable will be used.
+   *
+   * Takes precedence over the deprecated `auth.token` option.
+   */
+  token?: string;
+  /**
+   * The Deno Deploy organization slug to operate within.
+   *
+   * This is required when using a personal access token (starts with `ddp_`).
+   * If not provided, the `DENO_DEPLOY_ORG` environment variable will be used.
+   */
+  org?: string;
+  /**
+   * Environment variables to start the sandbox with, in addition to the default
+   * environment variables such as `DENO_DEPLOY_ORGANIZATION_ID`.
+   */
+  env?: Record<string, string>;
+  /**
+   * Whether to enable debug logging.
+   *
+   * @default false
+   */
+  debug?: boolean;
+  /**
+   * Labels to set on the sandbox. Up to 5 labels can be specified.
+   * Each label key must be at most 64 bytes, and each label value
+   * must be at most 128 bytes.
+   */
+  labels?: Record<string, string>;
+  /**
+   * A volume or snapshot to use as the root filesystem of the sandbox.
+   *
+   * If not specified, the default base image will be used. The volume or
+   * snapshot must be bootable.
+   *
+   * - Volumes will be mounted read-write (writes are persisted).
+   * - Snapshots will be mounted read-only (writes are not persisted).
+   *
+   * @example
+   * ```typescript
+   * const options: DenoSandboxOptions = {
+   *   root: "my-volume-slug",
+   * };
+   * ```
+   */
+  root?: VolumeId | VolumeSlug | SnapshotId | SnapshotSlug;
+  /**
+   * Volumes to mount on the sandbox.
+   *
+   * The key is the mount path inside the sandbox, and the value is the
+   * volume ID or slug.
+   *
+   * @example
+   * ```typescript
+   * const options: DenoSandboxOptions = {
+   *   volumes: {
+   *     "/data/volume1": "volume-slug-or-id-1",
+   *   },
+   * };
+   * ```
+   */
+  volumes?: Record<string, VolumeId | VolumeSlug>;
+  /**
+   * List of hostnames / IP addresses with optional port numbers that the
+   * sandbox can make outbound network requests to.
+   *
+   * If not specified, no network restrictions are applied.
+   *
+   * @example []
+   * @example ["example.com"]
+   * @example ["*.example.com"]
+   * @example ["example.com:443"]
+   */
+  allowNet?: string[];
+  /**
+   * Secret environment variables that are never exposed to sandbox code.
+   * The real secret values are injected on the wire when the sandbox makes
+   * HTTPS requests to the specified hosts.
+   *
+   * The key is the environment variable name.
+   *
+   * @example
+   * ```typescript
+   * const options: DenoSandboxOptions = {
+   *   secrets: {
+   *     OPENAI_API_KEY: {
+   *       hosts: ["api.openai.com"],
+   *       value: "sk-proj-your-real-key",
+   *     },
+   *   },
+   * };
+   * ```
+   */
+  secrets?: Record<string, SecretConfig>;
+  /**
+   * Whether to expose SSH access to the sandbox. If true, the sandbox's
+   * `ssh` property will be populated once the sandbox is ready.
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await DenoSandbox.create({ ssh: true });
+   * console.log(sandbox.instance.ssh);
+   * // => { username: "...", hostname: "..." }
+   * ```
+   */
+  ssh?: boolean;
+  /**
+   * The port number to expose for HTTP access. If specified, the sandbox's
+   * `url` property will be populated once the sandbox is ready, and can
+   * be used to access the sandbox over HTTP.
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await DenoSandbox.create({ port: 8080 });
+   * console.log(sandbox.instance.url);
+   * // => "http://..."
+   * ```
+   */
+  port?: number;
+  /**
+   * Override the Sandbox API endpoint URL to use to create and communicate
+   * with the sandboxes.
+   *
+   * The default can also be overridden by setting the `DENO_SANDBOX_ENDPOINT`
+   * or `DENO_SANDBOX_BASE_DOMAIN` environment variables.
+   */
+  sandboxEndpoint?: string | ((region: string) => string);
+  /**
+   * Override the API endpoint to use to connect to Deno Deploy.
+   *
+   * The default can also be overridden by setting the `DENO_DEPLOY_ENDPOINT`
+   * environment variable.
+   */
+  apiEndpoint?: string;
 }
 /**
  * Error codes for Deno Sandbox operations.
@@ -171,8 +361,8 @@ declare class DenoSandboxError extends SandboxError {
  *
  * // Create and initialize a sandbox
  * const sandbox = await DenoSandbox.create({
- *   memoryMb: 1024,
- *   lifetime: "5m",
+ *   memory: "1GiB",
+ *   timeout: "5m",
  * });
  *
  * try {
@@ -236,11 +426,11 @@ declare class DenoSandbox extends BaseSandbox {
    * @example
    * ```typescript
    * // Two-step initialization
-   * const sandbox = new DenoSandbox({ memoryMb: 1024 });
+   * const sandbox = new DenoSandbox({ memory: "1GiB" });
    * await sandbox.initialize();
    *
    * // Or use the factory method
-   * const sandbox = await DenoSandbox.create({ memoryMb: 1024 });
+   * const sandbox = await DenoSandbox.create({ memory: "1GiB" });
    * ```
    */
   constructor(options?: DenoSandboxOptions);
@@ -321,44 +511,6 @@ declare class DenoSandbox extends BaseSandbox {
    * ```
    */
   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.
    *
@@ -403,9 +555,9 @@ declare class DenoSandbox extends BaseSandbox {
    * @example
    * ```typescript
    * const sandbox = await DenoSandbox.create({
-   *   memoryMb: 1024,
-   *   lifetime: "10m",
-   *   region: "iad",
+   *   memory: "1GiB",
+   *   timeout: "10m",
+   *   region: "ord",
    * });
    * ```
    */
@@ -427,7 +579,7 @@ declare class DenoSandbox extends BaseSandbox {
    * const result = await sandbox.execute("ls -la");
    * ```
    */
-  static fromId(id: string, options?: Pick<DenoSandboxOptions, "auth">): Promise<DenoSandbox>;
+  static fromId(id: string, options?: Pick<DenoSandboxOptions, "auth" | "token" | "org" | "apiEndpoint">): Promise<DenoSandbox>;
 }
 /**
  * Async factory function type for creating Deno Sandbox instances.
@@ -455,7 +607,7 @@ type AsyncDenoSandboxFactory = () => Promise<DenoSandbox>;
  * import { DenoSandbox, createDenoSandboxFactory } from "@langchain/deno";
  *
  * // Create a factory for new sandboxes
- * const factory = createDenoSandboxFactory({ memoryMb: 1024 });
+ * const factory = createDenoSandboxFactory({ memory: "1GiB" });
  *
  * // Each call creates a new sandbox
  * const sandbox1 = await factory();
@@ -488,7 +640,7 @@ declare function createDenoSandboxFactory(options?: DenoSandboxOptions): AsyncDe
  * import { DenoSandbox, createDenoSandboxFactoryFromSandbox } from "@langchain/deno";
  *
  * // Create and initialize a sandbox
- * const sandbox = await DenoSandbox.create({ memoryMb: 1024 });
+ * const sandbox = await DenoSandbox.create({ memory: "1GiB" });
  *
  * try {
  *   const agent = createDeepAgent({
@@ -537,7 +689,7 @@ interface DenoCredentials {
  *
  * @param options - Optional authentication configuration from DenoSandboxOptions
  * @returns The authentication token string
- * @throws {Error} If no authentication token is available
+ * @throws {DenoSandboxError} If no authentication token is available
  *
  * @example
  * ```typescript
@@ -562,9 +714,9 @@ declare function getAuthToken(options?: DenoSandboxOptions["auth"]): string;
  *
  * @param options - Optional authentication configuration from DenoSandboxOptions
  * @returns Complete authentication credentials
- * @throws {Error} If no authentication token is available
+ * @throws {DenoSandboxError} 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 };
+export { type AsyncDenoSandboxFactory, type DenoCredentials, DenoSandbox, DenoSandboxError, type DenoSandboxErrorCode, type DenoSandboxOptions, type DenoSandboxRegion, type SandboxLifetime, type SandboxTimeout, createDenoSandboxFactory, createDenoSandboxFactoryFromSandbox, getAuthCredentials, getAuthToken };
 //# sourceMappingURL=index.d.cts.map