@xpert-ai/plugin-sdk 3.8.0 → 3.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.8.0",
+  "version": "3.8.1",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",

package/src/lib/sandbox/protocol.d.ts

@@ -33,6 +33,25 @@ export interface GrepMatch {
     /** The matching line text */
     text: string;
 }
+/**
+ * Read mode for file reading operations.
+ */
+export type ReadMode = 'slice' | 'indentation';
+/**
+ * Configuration for indentation-aware file reading.
+ */
+export interface IndentationOptions {
+    /** Anchor line number (1-indexed), defaults to offset */
+    anchor_line?: number;
+    /** Maximum indentation depth to collect; 0 means unlimited */
+    max_levels?: number;
+    /** Whether to include sibling blocks at the same indentation level */
+    include_siblings?: boolean;
+    /** Whether to include header lines (comments) above the anchor block */
+    include_header?: boolean;
+    /** Hard cap on returned lines */
+    max_lines?: number;
+}
 /**
  * File data structure used by backends.
  *
@@ -88,6 +107,39 @@ export interface EditResult {
     /** Metadata for the edit operation, attached to the ToolMessage */
     metadata?: Record<string, unknown>;
 }
+/**
+ * Single edit operation for multi-edit.
+ */
+export interface EditOperation {
+    /** String to find and replace */
+    oldString: string;
+    /** Replacement string */
+    newString: string;
+    /** If true, replace all occurrences (default: false) */
+    replaceAll?: boolean;
+}
+/**
+ * Result from backend multi-edit operations.
+ *
+ * Checkpoint backends populate filesUpdate with {file_path: file_data} for LangGraph state.
+ * External backends set filesUpdate to null (already persisted to disk/S3/database/etc).
+ */
+export interface MultiEditResult {
+    /** Error message on failure, undefined on success */
+    error?: string;
+    /** File path of edited file, undefined on failure */
+    path?: string;
+    /**
+     * State update dict for checkpoint backends, null for external storage.
+     * Checkpoint backends populate this with {file_path: file_data} for LangGraph state.
+     * External backends set null (already persisted to disk/S3/database/etc).
+     */
+    filesUpdate?: Record<string, FileData> | null;
+    /** Results from each individual edit operation */
+    results?: EditResult[];
+    /** Metadata for the multi-edit operation, attached to the ToolMessage */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Result of code execution.
  * Simplified schema optimized for LLM consumption.
@@ -146,15 +198,27 @@ export interface BackendProtocol {
      * @returns List of FileInfo objects for files and directories directly in the directory
      */
     lsInfo(path: string): MaybePromise<FileInfo[]>;
+    /**
+     * List directory contents recursively with depth control and pagination.
+     *
+     * @param dirPath - Absolute path to directory
+     * @param offset - 1-indexed entry number to start from (default: 1)
+     * @param limit - Maximum number of entries to return (default: 25)
+     * @param depth - Maximum depth to traverse (default: 2)
+     * @returns Human-readable directory tree with indentation
+     */
+    listDir(dirPath: string, offset?: number, limit?: number, depth?: number): MaybePromise<string>;
     /**
      * Read file content with line numbers or an error string.
      *
      * @param filePath - Absolute file path
-     * @param offset - Line offset to start reading from (0-indexed), default 0
-     * @param limit - Maximum number of lines to read, default 500
+     * @param offset - Line offset to start reading from (1-indexed), default 1
+     * @param limit - Maximum number of lines to read, default 2000
+     * @param mode - Read mode: 'slice' (default) or 'indentation'
+     * @param indentation - Configuration for indentation mode
      * @returns Formatted file content with line numbers, or error message
      */
-    read(filePath: string, offset?: number, limit?: number): MaybePromise<string>;
+    read(filePath: string, offset?: number, limit?: number, mode?: ReadMode, indentation?: IndentationOptions): MaybePromise<string>;
     /**
      * Structured search results or error string for invalid input.
      *
@@ -162,10 +226,19 @@ export interface BackendProtocol {
      *
      * @param pattern - Regex pattern to search for
      * @param path - Base path to search from (default: null)
-     * @param glob - Optional glob pattern to filter files (e.g., "*.py")
+     * @param include - Optional glob pattern to filter files (e.g., "*.py")
      * @returns List of GrepMatch objects or error string for invalid regex
      */
-    grepRaw(pattern: string, path?: string | null, glob?: string | null): MaybePromise<GrepMatch[] | string>;
+    grepRaw(pattern: string, path?: string | null, include?: string | null): MaybePromise<GrepMatch[] | string>;
+    /**
+     * Search file contents for a regex pattern, returning human-readable output.
+     *
+     * @param pattern - Regex pattern to search for
+     * @param path - Base path to search from (default: workspace root)
+     * @param include - Optional glob pattern to filter files (e.g., "*.js", "*.{ts,tsx}")
+     * @returns Human-readable output with matches grouped by file
+     */
+    grep(pattern: string, path?: string | null, include?: string | null): MaybePromise<string>;
     /**
      * Structured glob matching returning FileInfo objects.
      *
@@ -174,6 +247,14 @@ export interface BackendProtocol {
      * @returns List of FileInfo objects matching the pattern
      */
     globInfo(pattern: string, path?: string): MaybePromise<FileInfo[]>;
+    /**
+     * Find files matching a glob pattern, returning human-readable output.
+     *
+     * @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
+     * @param path - Base path to search from (default: workspace root)
+     * @returns Human-readable output with matching file paths
+     */
+    glob(pattern: string, path?: string): MaybePromise<string>;
     /**
      * Create a new file.
      *
@@ -182,6 +263,14 @@ export interface BackendProtocol {
      * @returns WriteResult with error populated on failure
      */
     write(filePath: string, content: string): MaybePromise<WriteResult>;
+    /**
+     * Append content to a file. Creates the file if it doesn't exist.
+     *
+     * @param filePath - Absolute file path
+     * @param content - Content to append
+     * @returns WriteResult with error populated on failure
+     */
+    append(filePath: string, content: string): MaybePromise<WriteResult>;
     /**
      * Edit a file by replacing string occurrences.
      *
@@ -192,6 +281,16 @@ export interface BackendProtocol {
      * @returns EditResult with error, path, filesUpdate, and occurrences
      */
     edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
+    /**
+     * Perform multiple sequential edits on a single file.
+     * All edits are applied sequentially, with each edit operating on the result of the previous edit.
+     * All edits must succeed for the operation to succeed (atomic).
+     *
+     * @param filePath - Absolute file path
+     * @param edits - Array of edit operations to perform sequentially
+     * @returns MultiEditResult with error, path, filesUpdate, and individual results
+     */
+    multiEdit(filePath: string, edits: EditOperation[]): MaybePromise<MultiEditResult>;
     /**
      * Upload multiple files.
      *
@@ -220,6 +319,25 @@ export interface SandboxBackendProtocol extends BackendProtocol {
      * @returns ExecuteResponse with combined output, exit code, and truncation flag
      */
     execute(command: string): MaybePromise<ExecuteResponse>;
+    /**
+     * Execute a command with line-by-line streaming output.
+     *
+     * When implemented, the middleware layer can push incremental output
+     * to the frontend as each line arrives, rather than waiting for the
+     * command to finish.  Implementations MUST buffer partial lines and
+     * only invoke `onLine` with complete lines (LF-terminated).
+     *
+     * The returned `ExecuteResponse.output` contains the full collected
+     * output, identical to what `execute()` would return.
+     *
+     * Falls back to `execute()` + single `onLine` call in `BaseSandbox`
+     * when a concrete backend does not override this method.
+     *
+     * @param command - Full shell command string to execute
+     * @param onLine  - Callback invoked once per complete output line
+     * @returns ExecuteResponse with combined output, exit code, and truncation flag
+     */
+    streamExecute?(command: string, onLine: (line: string) => void): MaybePromise<ExecuteResponse>;
     /** Unique identifier for the sandbox backend instance */
     readonly id: string;
 }

package/src/lib/sandbox/sandbox.d.ts

@@ -7,7 +7,7 @@
  *
  * Requires Node.js 20+ on the sandbox host.
  */
-import type { EditResult, ExecuteResponse, FileDownloadResponse, FileInfo, FileUploadResponse, GrepMatch, MaybePromise, SandboxBackendProtocol, WriteResult } from "./protocol";
+import type { EditOperation, EditResult, ExecuteResponse, FileDownloadResponse, FileInfo, FileUploadResponse, GrepMatch, IndentationOptions, MaybePromise, MultiEditResult, ReadMode, SandboxBackendProtocol, WriteResult } from "./protocol";
 /**
  * Base sandbox implementation with execute() as the only abstract method.
  *
@@ -18,6 +18,7 @@ import type { EditResult, ExecuteResponse, FileDownloadResponse, FileInfo, FileU
  * Requires Node.js 20+ on the sandbox host.
  */
 export declare abstract class BaseSandbox implements SandboxBackendProtocol {
+    workingDirectory: string;
     /** Unique identifier for the sandbox backend */
     abstract readonly id: string;
     /**
@@ -25,6 +26,7 @@ export declare abstract class BaseSandbox implements SandboxBackendProtocol {
      * This is the only method concrete implementations must provide.
      */
     abstract execute(command: string): MaybePromise<ExecuteResponse>;
+    streamExecute(command: string, onLine: (line: string) => void): Promise<ExecuteResponse>;
     /**
      * Upload multiple files to the sandbox.
      * Implementations must support partial success.
@@ -42,29 +44,60 @@ export declare abstract class BaseSandbox implements SandboxBackendProtocol {
      * @returns List of FileInfo objects for files and directories directly in the directory.
      */
     lsInfo(path: string): Promise<FileInfo[]>;
+    /**
+     * List directory contents recursively with depth control and pagination.
+     *
+     * @param dirPath - Absolute path to directory
+     * @param offset - 1-indexed entry number to start from (default: 1)
+     * @param limit - Maximum number of entries to return (default: 25)
+     * @param depth - Maximum depth to traverse (default: 2)
+     * @returns Human-readable directory tree with indentation
+     */
+    listDir(dirPath: string, offset?: number, limit?: number, depth?: number): Promise<string>;
     /**
      * Read file content with line numbers.
      *
      * @param filePath - Absolute file path
-     * @param offset - Line offset to start reading from (0-indexed)
+     * @param offset - Line offset to start reading from (1-indexed)
      * @param limit - Maximum number of lines to read
+     * @param mode - Read mode: 'slice' (default) or 'indentation'
+     * @param indentation - Configuration for indentation mode
      * @returns Formatted file content with line numbers, or error message
      */
-    read(filePath: string, offset?: number, limit?: number): Promise<string>;
+    read(filePath: string, offset?: number, limit?: number, mode?: ReadMode, indentation?: IndentationOptions): Promise<string>;
     /**
      * Structured search results or error string for invalid input.
      */
-    grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
+    grepRaw(pattern: string, path?: string, include?: string | null): Promise<GrepMatch[] | string>;
+    /**
+     * Search file contents for a regex pattern, returning human-readable output.
+     */
+    grep(pattern: string, path?: string, include?: string | null): Promise<string>;
     /**
      * Structured glob matching returning FileInfo objects.
      */
     globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
+    /**
+     * Find files matching a glob pattern, returning human-readable output.
+     */
+    glob(pattern: string, path?: string): Promise<string>;
     /**
      * Create a new file with content.
      */
     write(filePath: string, content: string): Promise<WriteResult>;
+    private writeViaUpload;
+    /**
+     * Append content to a file. Creates the file if it doesn't exist.
+     */
+    append(filePath: string, content: string): Promise<WriteResult>;
     /**
      * Edit a file by replacing string occurrences.
      */
     edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+    /**
+     * Perform multiple sequential edits on a single file.
+     * All edits are applied sequentially, with each edit operating on the result of the previous edit.
+     * All edits must succeed for the operation to succeed (atomic).
+     */
+    multiEdit(filePath: string, edits: EditOperation[]): Promise<MultiEditResult>;
 }