deepagents 1.7.1 → 1.7.3

package/dist/index.d.cts

@@ -1296,9 +1296,11 @@ declare class CompositeBackend implements BackendProtocol {
  *
  * This class provides default implementations for all SandboxBackendProtocol
  * methods using shell commands executed via execute(). Concrete implementations
- * only need to implement the execute() method.
+ * only need to implement execute(), uploadFiles(), and downloadFiles().
  *
- * Requires Node.js 20+ on the sandbox host.
+ * All shell commands use pure POSIX utilities (awk, grep, find, stat) that are
+ * available on any Linux including Alpine/busybox. No Python, Node.js, or
+ * other runtime is required on the sandbox host.
  */
 declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /** Unique identifier for the sandbox backend */
@@ -1321,6 +1323,9 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /**
    * List files and directories in the specified directory (non-recursive).
    *
+   * Uses pure POSIX shell (find + stat) via execute() — works on any Linux
+   * including Alpine. No Python or Node.js needed.
+   *
    * @param path - Absolute path to directory
    * @returns List of FileInfo objects for files and directories directly in the directory.
    */
@@ -1328,6 +1333,10 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /**
    * Read file content with line numbers.
    *
+   * Uses pure POSIX shell (awk) via execute() — only the requested slice
+   * is returned over the wire, making this efficient for large files.
+   * Works on any Linux including Alpine (no Python or Node.js needed).
+   *
    * @param filePath - Absolute file path
    * @param offset - Line offset to start reading from (0-indexed)
    * @param limit - Maximum number of lines to read
@@ -1337,12 +1346,14 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /**
    * Read file content as raw FileData.
    *
+   * Uses downloadFiles() directly — no runtime needed on the sandbox host.
+   *
    * @param filePath - Absolute file path
    * @returns Raw file content as FileData
    */
   readRaw(filePath: string): Promise<FileData>;
   /**
-   * Search for a literal text pattern in files.
+   * Search for a literal text pattern in files using grep.
    *
    * @param pattern - Literal string to search for (NOT regex).
    * @param path - Directory or file path to search in.
@@ -1352,14 +1363,30 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
   /**
    * Structured glob matching returning FileInfo objects.
+   *
+   * Uses pure POSIX shell (find + stat) via execute() to list all files,
+   * then applies glob-to-regex matching in TypeScript. No Python or Node.js
+   * needed on the sandbox host.
+   *
+   * Glob patterns are matched against paths relative to the search base:
+   * - `*`  matches any characters except `/`
+   * - `**` matches any characters including `/` (recursive)
+   * - `?`  matches a single character except `/`
+   * - `[...]` character classes
    */
   globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
   /**
    * Create a new file with content.
+   *
+   * Uses downloadFiles() to check existence and uploadFiles() to write.
+   * No runtime needed on the sandbox host.
    */
   write(filePath: string, content: string): Promise<WriteResult>;
   /**
    * Edit a file by replacing string occurrences.
+   *
+   * Uses downloadFiles() to read, performs string replacement in TypeScript,
+   * then uploadFiles() to write back. No runtime needed on the sandbox host.
    */
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
 }

package/dist/index.d.ts

@@ -1296,9 +1296,11 @@ declare class CompositeBackend implements BackendProtocol {
  *
  * This class provides default implementations for all SandboxBackendProtocol
  * methods using shell commands executed via execute(). Concrete implementations
- * only need to implement the execute() method.
+ * only need to implement execute(), uploadFiles(), and downloadFiles().
  *
- * Requires Node.js 20+ on the sandbox host.
+ * All shell commands use pure POSIX utilities (awk, grep, find, stat) that are
+ * available on any Linux including Alpine/busybox. No Python, Node.js, or
+ * other runtime is required on the sandbox host.
  */
 declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /** Unique identifier for the sandbox backend */
@@ -1321,6 +1323,9 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /**
    * List files and directories in the specified directory (non-recursive).
    *
+   * Uses pure POSIX shell (find + stat) via execute() — works on any Linux
+   * including Alpine. No Python or Node.js needed.
+   *
    * @param path - Absolute path to directory
    * @returns List of FileInfo objects for files and directories directly in the directory.
    */
@@ -1328,6 +1333,10 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /**
    * Read file content with line numbers.
    *
+   * Uses pure POSIX shell (awk) via execute() — only the requested slice
+   * is returned over the wire, making this efficient for large files.
+   * Works on any Linux including Alpine (no Python or Node.js needed).
+   *
    * @param filePath - Absolute file path
    * @param offset - Line offset to start reading from (0-indexed)
    * @param limit - Maximum number of lines to read
@@ -1337,12 +1346,14 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   /**
    * Read file content as raw FileData.
    *
+   * Uses downloadFiles() directly — no runtime needed on the sandbox host.
+   *
    * @param filePath - Absolute file path
    * @returns Raw file content as FileData
    */
   readRaw(filePath: string): Promise<FileData>;
   /**
-   * Search for a literal text pattern in files.
+   * Search for a literal text pattern in files using grep.
    *
    * @param pattern - Literal string to search for (NOT regex).
    * @param path - Directory or file path to search in.
@@ -1352,14 +1363,30 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
   /**
    * Structured glob matching returning FileInfo objects.
+   *
+   * Uses pure POSIX shell (find + stat) via execute() to list all files,
+   * then applies glob-to-regex matching in TypeScript. No Python or Node.js
+   * needed on the sandbox host.
+   *
+   * Glob patterns are matched against paths relative to the search base:
+   * - `*`  matches any characters except `/`
+   * - `**` matches any characters including `/` (recursive)
+   * - `?`  matches a single character except `/`
+   * - `[...]` character classes
    */
   globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
   /**
    * Create a new file with content.
+   *
+   * Uses downloadFiles() to check existence and uploadFiles() to write.
+   * No runtime needed on the sandbox host.
    */
   write(filePath: string, content: string): Promise<WriteResult>;
   /**
    * Edit a file by replacing string occurrences.
+   *
+   * Uses downloadFiles() to read, performs string replacement in TypeScript,
+   * then uploadFiles() to write back. No runtime needed on the sandbox host.
    */
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
 }