@xpert-ai/plugin-sdk 3.8.0 → 3.8.1

package/index.cjs.js

@@ -531,6 +531,7 @@ exports.WorkflowNodeRegistry = __decorate([
     ])
 ], exports.WorkflowNodeRegistry);
 
+const COMMAND_METADATA$1 = '__command__';
 /**
  * Wrap Workflow Node Execution Command
  */ class WrapWorkflowNodeExecutionCommand extends cqrs.Command {
@@ -541,6 +542,9 @@ exports.WorkflowNodeRegistry = __decorate([
     }
 }
 WrapWorkflowNodeExecutionCommand.type = '[Workflow] Wrap Workflow Node Execution';
+Reflect.defineMetadata(COMMAND_METADATA$1, {
+    id: WrapWorkflowNodeExecutionCommand.type
+}, WrapWorkflowNodeExecutionCommand);
 
 const VECTOR_STORE_STRATEGY = 'VECTOR_STORE_STRATEGY';
 const VectorStoreStrategy = (provider)=>common.applyDecorators(common.SetMetadata(VECTOR_STORE_STRATEGY, provider), common.SetMetadata(STRATEGY_META_KEY, VECTOR_STORE_STRATEGY));
@@ -2384,6 +2388,7 @@ function normalizeContextSize(value) {
     return undefined;
 }
 
+const COMMAND_METADATA = '__command__';
 /**
  * Get a Chat Model of copilot model and check it's token limitation, record the token usage
  */ class CreateModelClientCommand extends cqrs.Command {
@@ -2394,6 +2399,9 @@ function normalizeContextSize(value) {
     }
 }
 CreateModelClientCommand.type = '[AI Model] Create Model Client';
+Reflect.defineMetadata(COMMAND_METADATA, {
+    id: CreateModelClientCommand.type
+}, CreateModelClientCommand);
 
 const AGENT_MIDDLEWARE_STRATEGY = 'AGENT_MIDDLEWARE_STRATEGY';
 const AgentMiddlewareStrategy = (provider)=>common.applyDecorators(common.SetMetadata(AGENT_MIDDLEWARE_STRATEGY, provider), common.SetMetadata(STRATEGY_META_KEY, AGENT_MIDDLEWARE_STRATEGY));
@@ -2650,18 +2658,78 @@ CancelConversationCommand.type = '[Chat Conversation] Cancel';
  * only need to implement the execute() method.
  *
  * Requires Node.js 20+ on the sandbox host.
- */ /**
+ */ const MAX_LINE_LENGTH = 500;
+const MAX_GREP_LINE_LENGTH = 2000;
+const GREP_RESULT_LIMIT = 100;
+const GLOB_RESULT_LIMIT = 100;
+const WRITE_EXISTS_OUTPUT = "Error: File already exists";
+/**
+ * UTF-8 safe Base64 encoding function.
+ * Replaces btoa() which only supports Latin1 characters.
+ */ function utf8ToBase64(str) {
+    return Buffer.from(str, 'utf-8').toString('base64');
+}
+/**
+ * Format glob results into human-readable output.
+ */ function formatGlobOutput(files, pattern) {
+    const limit = GLOB_RESULT_LIMIT;
+    const truncated = files.length > limit;
+    const finalFiles = truncated ? files.slice(0, limit) : files;
+    if (finalFiles.length === 0) {
+        return "No files found";
+    }
+    const lines = [];
+    for (const file of finalFiles){
+        lines.push(file.path);
+    }
+    if (truncated) {
+        lines.push("");
+        lines.push("(Results truncated. Consider using a more specific path or pattern.)");
+    }
+    return lines.join("\n");
+}
+/**
+ * Format grep matches into human-readable output grouped by file.
+ */ function formatGrepOutput(matches) {
+    const limit = GREP_RESULT_LIMIT;
+    const truncated = matches.length > limit;
+    const finalMatches = truncated ? matches.slice(0, limit) : matches;
+    if (finalMatches.length === 0) {
+        return "No matches found";
+    }
+    const lines = [
+        `Found ${finalMatches.length} matches`
+    ];
+    let currentFile = "";
+    for (const match of finalMatches){
+        if (currentFile !== match.path) {
+            if (currentFile !== "") {
+                lines.push("");
+            }
+            currentFile = match.path;
+            lines.push(`${match.path}:`);
+        }
+        const text = match.text.length > MAX_GREP_LINE_LENGTH ? match.text.substring(0, MAX_GREP_LINE_LENGTH) + "..." : match.text;
+        lines.push(`  Line ${match.line}: ${text}`);
+    }
+    if (truncated) {
+        lines.push("");
+        lines.push("(Results truncated. Consider using a more specific path or pattern.)");
+    }
+    return lines.join("\n");
+}
+/**
  * Node.js command template for glob operations.
  * Uses web-standard atob() for base64 decoding.
  */ function buildGlobCommand(searchPath, pattern) {
-    const pathB64 = btoa(searchPath);
-    const patternB64 = btoa(pattern);
+    const pathB64 = utf8ToBase64(searchPath);
+    const patternB64 = utf8ToBase64(pattern);
     return `node -e "
 const fs = require('fs');
 const path = require('path');
 
-const searchPath = atob('${pathB64}');
-const pattern = atob('${patternB64}');
+const searchPath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+const pattern = Buffer.from('${patternB64}', 'base64').toString('utf-8');
 
 function globMatch(relativePath, pattern) {
   const regexPattern = pattern
@@ -2706,12 +2774,12 @@ try {
 /**
  * Node.js command template for listing directory contents.
  */ function buildLsCommand(dirPath) {
-    const pathB64 = btoa(dirPath);
+    const pathB64 = utf8ToBase64(dirPath);
     return `node -e "
 const fs = require('fs');
 const path = require('path');
 
-const dirPath = atob('${pathB64}');
+const dirPath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
 
 try {
   const entries = fs.readdirSync(dirPath, { withFileTypes: true });
@@ -2731,17 +2799,129 @@ try {
 }
 "`;
 }
+const INDENTATION_SPACES = 2;
+const MAX_ENTRY_LENGTH = 500;
+/**
+ * Node.js command template for recursive directory listing with depth control.
+ */ function buildListDirCommand(dirPath, offset, limit, depth) {
+    const pathB64 = utf8ToBase64(dirPath);
+    const safeOffset = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 1;
+    const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 25;
+    const safeDepth = Number.isFinite(depth) && depth > 0 ? Math.floor(depth) : 2;
+    return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const dirPath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+const offset = ${safeOffset};
+const limit = ${safeLimit};
+const maxDepth = ${safeDepth};
+const INDENTATION_SPACES = ${INDENTATION_SPACES};
+const MAX_ENTRY_LENGTH = ${MAX_ENTRY_LENGTH};
+
+if (!path.isAbsolute(dirPath)) {
+  console.error('Error: dir_path must be an absolute path');
+  process.exit(1);
+}
+
+if (!fs.existsSync(dirPath)) {
+  console.error('Error: Directory not found');
+  process.exit(1);
+}
+
+if (!fs.statSync(dirPath).isDirectory()) {
+  console.error('Error: Path is not a directory');
+  process.exit(1);
+}
+
+function collectEntries(currentPath, relativePrefix, remainingDepth, entries) {
+  if (remainingDepth === 0) return;
+
+  try {
+    const dirEntries = fs.readdirSync(currentPath, { withFileTypes: true });
+    const sortedEntries = dirEntries
+      .map(entry => {
+        const fullPath = path.join(currentPath, entry.name);
+        const relativePath = path.join(relativePrefix, entry.name);
+        const displayName = entry.name.length > MAX_ENTRY_LENGTH
+          ? entry.name.substring(0, MAX_ENTRY_LENGTH)
+          : entry.name;
+
+        let kind = 'file';
+        if (entry.isSymbolicLink()) kind = 'symlink';
+        else if (entry.isDirectory()) kind = 'directory';
+
+        return {
+          fullPath,
+          relativePath,
+          displayName,
+          kind,
+          depth: relativePrefix.split(path.sep).filter(Boolean).length
+        };
+      })
+      .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+
+    for (const entry of sortedEntries) {
+      entries.push(entry);
+      if (entry.kind === 'directory' && remainingDepth > 1) {
+        collectEntries(entry.fullPath, entry.relativePath, remainingDepth - 1, entries);
+      }
+    }
+  } catch (e) {
+    // Skip unreadable directories
+  }
+}
+
+const allEntries = [];
+collectEntries(dirPath, '', maxDepth, allEntries);
+
+if (allEntries.length === 0) {
+  console.log('Absolute path: ' + dirPath);
+  console.log('(Empty directory)');
+  process.exit(0);
+}
+
+const startIndex = offset - 1;
+if (startIndex >= allEntries.length) {
+  console.error('Error: offset exceeds directory entry count');
+  process.exit(1);
+}
+
+const endIndex = Math.min(startIndex + limit, allEntries.length);
+const selectedEntries = allEntries.slice(startIndex, endIndex);
+
+console.log('Absolute path: ' + dirPath);
+
+for (const entry of selectedEntries) {
+  const indent = ' '.repeat(entry.depth * INDENTATION_SPACES);
+  let name = entry.displayName;
+  if (entry.kind === 'directory') name += '/';
+  else if (entry.kind === 'symlink') name += '@';
+  console.log(indent + name);
+}
+
+if (endIndex < allEntries.length) {
+  console.log('More than ' + limit + ' entries found');
+}
+"`;
+}
+const TAB_WIDTH = 4;
+const COMMENT_PREFIXES = [
+    '#',
+    '//',
+    '--'
+];
 /**
- * Node.js command template for reading files.
- */ function buildReadCommand(filePath, offset, limit) {
-    const pathB64 = btoa(filePath);
-    // Coerce offset and limit to safe non-negative integers before embedding in the shell command.
-    const safeOffset = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
-    const safeLimit = Number.isFinite(limit) && limit > 0 && limit < Number.MAX_SAFE_INTEGER ? Math.floor(limit) : 0;
+ * Node.js command template for slice mode reading.
+ */ function buildSliceReadCommand(filePath, offset, limit) {
+    const pathB64 = utf8ToBase64(filePath);
+    const safeOffset = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) - 1 : 0;
+    const safeLimit = Number.isFinite(limit) && limit > 0 && limit < Number.MAX_SAFE_INTEGER ? Math.floor(limit) : 2000;
     return `node -e "
 const fs = require('fs');
+const MAX_LINE_LENGTH = ${MAX_LINE_LENGTH};
 
-const filePath = atob('${pathB64}');
+const filePath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
 const offset = ${safeOffset};
 const limit = ${safeLimit};
 
@@ -2758,28 +2938,188 @@ if (stat.size === 0) {
 
 const content = fs.readFileSync(filePath, 'utf-8');
 const lines = content.split('\\n');
+
+if (offset >= lines.length) {
+  console.log('Error: offset exceeds file length');
+  process.exit(1);
+}
+
 const selected = lines.slice(offset, offset + limit);
 
 for (let i = 0; i < selected.length; i++) {
   const lineNum = offset + i + 1;
-  console.log(String(lineNum).padStart(6) + '\\t' + selected[i]);
+  let line = selected[i];
+  if (line.length > MAX_LINE_LENGTH) {
+    line = line.substring(0, MAX_LINE_LENGTH);
+  }
+  console.log('L' + lineNum + ': ' + line);
+}
+"`;
+}
+/**
+ * Node.js command template for indentation mode reading.
+ */ function buildIndentationReadCommand(filePath, offset, limit, options) {
+    const pathB64 = utf8ToBase64(filePath);
+    const safeOffset = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 1;
+    const safeLimit = Number.isFinite(limit) && limit > 0 && limit < Number.MAX_SAFE_INTEGER ? Math.floor(limit) : 2000;
+    var _options_anchor_line;
+    const anchorLine = (_options_anchor_line = options.anchor_line) != null ? _options_anchor_line : safeOffset;
+    var _options_max_levels;
+    const maxLevels = (_options_max_levels = options.max_levels) != null ? _options_max_levels : 0;
+    var _options_include_siblings;
+    const includeSiblings = (_options_include_siblings = options.include_siblings) != null ? _options_include_siblings : false;
+    var _options_include_header;
+    const includeHeader = (_options_include_header = options.include_header) != null ? _options_include_header : true;
+    var _options_max_lines;
+    const maxLines = (_options_max_lines = options.max_lines) != null ? _options_max_lines : safeLimit;
+    return `node -e "
+const fs = require('fs');
+const MAX_LINE_LENGTH = ${MAX_LINE_LENGTH};
+const TAB_WIDTH = ${TAB_WIDTH};
+const COMMENT_PREFIXES = ${JSON.stringify(COMMENT_PREFIXES)};
+
+const filePath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+const anchorLine = ${anchorLine};
+const limit = ${safeLimit};
+const maxLevels = ${maxLevels};
+const includeSiblings = ${includeSiblings};
+const includeHeader = ${includeHeader};
+const maxLines = ${maxLines};
+
+if (!fs.existsSync(filePath)) {
+  console.log('Error: File not found');
+  process.exit(1);
+}
+
+const content = fs.readFileSync(filePath, 'utf-8');
+const rawLines = content.split('\\n');
+
+if (rawLines.length === 0 || anchorLine > rawLines.length) {
+  console.log('Error: anchor_line exceeds file length');
+  process.exit(1);
+}
+
+function measureIndent(line) {
+  let indent = 0;
+  for (const c of line) {
+    if (c === ' ') indent++;
+    else if (c === '\\t') indent += TAB_WIDTH;
+    else break;
+  }
+  return indent;
+}
+
+function isBlank(line) { return line.trim() === ''; }
+function isComment(line) { return COMMENT_PREFIXES.some(p => line.trim().startsWith(p)); }
+function formatLine(line) { return line.length > MAX_LINE_LENGTH ? line.substring(0, MAX_LINE_LENGTH) : line; }
+
+const records = rawLines.map((raw, i) => ({
+  number: i + 1,
+  raw,
+  display: formatLine(raw),
+  indent: measureIndent(raw)
+}));
+
+const effectiveIndents = [];
+let prevIndent = 0;
+for (const r of records) {
+  if (isBlank(r.raw)) {
+    effectiveIndents.push(prevIndent);
+  } else {
+    prevIndent = r.indent;
+    effectiveIndents.push(prevIndent);
+  }
+}
+
+const anchorIndex = anchorLine - 1;
+const anchorIndent = effectiveIndents[anchorIndex];
+const minIndent = maxLevels === 0 ? 0 : Math.max(0, anchorIndent - maxLevels * TAB_WIDTH);
+const finalLimit = Math.min(limit, maxLines, records.length);
+
+if (finalLimit === 1) {
+  console.log('L' + records[anchorIndex].number + ': ' + records[anchorIndex].display);
+  process.exit(0);
+}
+
+const out = [records[anchorIndex]];
+let i = anchorIndex - 1;
+let j = anchorIndex + 1;
+let iCounterMinIndent = 0;
+let jCounterMinIndent = 0;
+
+while (out.length < finalLimit) {
+  let progressed = 0;
+
+  if (i >= 0) {
+    if (effectiveIndents[i] >= minIndent) {
+      out.unshift(records[i]);
+      progressed++;
+      const curI = i;
+      i--;
+
+      if (effectiveIndents[curI] === minIndent && !includeSiblings) {
+        const allowHeaderComment = includeHeader && isComment(records[curI].raw);
+        const canTakeLine = allowHeaderComment || iCounterMinIndent === 0;
+        if (canTakeLine) {
+          iCounterMinIndent++;
+        } else {
+          out.shift();
+          progressed--;
+          i = -1;
+        }
+      }
+
+      if (out.length >= finalLimit) break;
+    } else {
+      i = -1;
+    }
+  }
+
+  if (j < records.length) {
+    if (effectiveIndents[j] >= minIndent) {
+      out.push(records[j]);
+      progressed++;
+      const curJ = j;
+      j++;
+
+      if (effectiveIndents[curJ] === minIndent && !includeSiblings) {
+        if (jCounterMinIndent > 0) {
+          out.pop();
+          progressed--;
+          j = records.length;
+        }
+        jCounterMinIndent++;
+      }
+    } else {
+      j = records.length;
+    }
+  }
+
+  if (progressed === 0) break;
+}
+
+while (out.length > 0 && isBlank(out[0].raw)) out.shift();
+while (out.length > 0 && isBlank(out[out.length - 1].raw)) out.pop();
+
+for (const r of out) {
+  console.log('L' + r.number + ': ' + r.display);
 }
 "`;
 }
 /**
  * Node.js command template for writing files.
  */ function buildWriteCommand(filePath, content) {
-    const pathB64 = btoa(filePath);
-    const contentB64 = btoa(content);
+    const pathB64 = utf8ToBase64(filePath);
+    const contentB64 = utf8ToBase64(content);
     return `node -e "
 const fs = require('fs');
 const path = require('path');
 
-const filePath = atob('${pathB64}');
-const content = atob('${contentB64}');
+const filePath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+const content = Buffer.from('${contentB64}', 'base64').toString('utf-8');
 
 if (fs.existsSync(filePath)) {
-  console.error('Error: File already exists');
+  console.error('${WRITE_EXISTS_OUTPUT}');
   process.exit(1);
 }
 
@@ -2790,18 +3130,45 @@ fs.writeFileSync(filePath, content, 'utf-8');
 console.log('OK');
 "`;
 }
+function buildExistsCommand(filePath) {
+    const pathB64 = utf8ToBase64(filePath);
+    return `node -e "
+const fs = require('fs');
+const filePath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+process.exit(fs.existsSync(filePath) ? 0 : 1);
+"`;
+}
+/**
+ * Node.js command template for appending to files.
+ */ function buildAppendCommand(filePath, content) {
+    const pathB64 = utf8ToBase64(filePath);
+    const contentB64 = utf8ToBase64(content);
+    return `node -e "
+const fs = require('fs');
+const path = require('path');
+
+const filePath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+const content = Buffer.from('${contentB64}', 'base64').toString('utf-8');
+
+const parentDir = path.dirname(filePath) || '.';
+fs.mkdirSync(parentDir, { recursive: true });
+
+fs.appendFileSync(filePath, content, 'utf-8');
+console.log('OK');
+"`;
+}
 /**
  * Node.js command template for editing files.
  */ function buildEditCommand(filePath, oldStr, newStr, replaceAll) {
-    const pathB64 = btoa(filePath);
-    const oldB64 = btoa(oldStr);
-    const newB64 = btoa(newStr);
+    const pathB64 = utf8ToBase64(filePath);
+    const oldB64 = utf8ToBase64(oldStr);
+    const newB64 = utf8ToBase64(newStr);
     return `node -e "
 const fs = require('fs');
 
-const filePath = atob('${pathB64}');
-const oldStr = atob('${oldB64}');
-const newStr = atob('${newB64}');
+const filePath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+const oldStr = Buffer.from('${oldB64}', 'base64').toString('utf-8');
+const newStr = Buffer.from('${newB64}', 'base64').toString('utf-8');
 const replaceAll = ${Boolean(replaceAll)};
 
 let text;
@@ -2828,16 +3195,16 @@ console.log(count);
 /**
  * Node.js command template for grep operations.
  */ function buildGrepCommand(pattern, searchPath, globPattern) {
-    const patternB64 = btoa(pattern);
-    const pathB64 = btoa(searchPath);
-    const globB64 = globPattern ? btoa(globPattern) : "";
+    const patternB64 = utf8ToBase64(pattern);
+    const pathB64 = utf8ToBase64(searchPath);
+    const globB64 = globPattern ? utf8ToBase64(globPattern) : "";
     return `node -e "
 const fs = require('fs');
 const path = require('path');
 
-const pattern = atob('${patternB64}');
-const searchPath = atob('${pathB64}');
-const globPattern = ${globPattern ? `atob('${globB64}')` : "null"};
+const pattern = Buffer.from('${patternB64}', 'base64').toString('utf-8');
+const searchPath = Buffer.from('${pathB64}', 'base64').toString('utf-8');
+const globPattern = ${globPattern ? `Buffer.from('${globB64}', 'base64').toString('utf-8')` : "null"};
 
 let regex;
 try {
@@ -2906,6 +3273,13 @@ try {
  *
  * Requires Node.js 20+ on the sandbox host.
  */ class BaseSandbox {
+    async streamExecute(command, onLine) {
+        const result = await this.execute(command);
+        if (result.output) {
+            onLine(result.output);
+        }
+        return result;
+    }
     /**
    * List files and directories in the specified directory (non-recursive).
    *
@@ -2935,24 +3309,51 @@ try {
         return infos;
     }
     /**
+   * 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
+   */ async listDir(dirPath, offset = 1, limit = 25, depth = 2) {
+        if (offset < 1) {
+            return "Error: offset must be a 1-indexed entry number";
+        }
+        if (limit < 1) {
+            return "Error: limit must be greater than zero";
+        }
+        if (depth < 1) {
+            return "Error: depth must be greater than zero";
+        }
+        const command = buildListDirCommand(dirPath, offset, limit, depth);
+        const result = await this.execute(command);
+        if (result.exitCode !== 0) {
+            return result.output || `Error: Failed to list directory '${dirPath}'`;
+        }
+        return result.output;
+    }
+    /**
    * 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
-   */ async read(filePath, offset = 0, limit = 500) {
-        const command = buildReadCommand(filePath, offset, limit);
+   */ async read(filePath, offset = 1, limit = 2000, mode = 'slice', indentation) {
+        const command = mode === 'indentation' ? buildIndentationReadCommand(filePath, offset, limit, indentation != null ? indentation : {}) : buildSliceReadCommand(filePath, offset, limit);
         const result = await this.execute(command);
         if (result.exitCode !== 0) {
-            return `Error: File '${filePath}' not found`;
+            return result.output || `Error: File '${filePath}' not found`;
         }
         return result.output;
     }
     /**
    * Structured search results or error string for invalid input.
-   */ async grepRaw(pattern, path = "/", glob = null) {
-        const command = buildGrepCommand(pattern, path, glob);
+   */ async grepRaw(pattern, path = "/", include = null) {
+        const command = buildGrepCommand(pattern, path, include);
         const result = await this.execute(command);
         if (result.exitCode === 1) {
             // Check if it's a regex error
@@ -2977,6 +3378,18 @@ try {
         return matches;
     }
     /**
+   * Search file contents for a regex pattern, returning human-readable output.
+   */ async grep(pattern, path = "/", include = null) {
+        const result = await this.grepRaw(pattern, path, include);
+        if (typeof result === "string") {
+            return result;
+        }
+        if (result.length === 0) {
+            return "No matches found";
+        }
+        return formatGrepOutput(result);
+    }
+    /**
    * Structured glob matching returning FileInfo objects.
    */ async globInfo(pattern, path = "/") {
         const command = buildGlobCommand(path, pattern);
@@ -2999,15 +3412,79 @@ try {
         return infos;
     }
     /**
+   * Find files matching a glob pattern, returning human-readable output.
+   */ async glob(pattern, path = "/") {
+        const files = await this.globInfo(pattern, path);
+        if (files.length === 0) {
+            return "No files found";
+        }
+        return formatGlobOutput(files);
+    }
+    /**
    * Create a new file with content.
    */ async write(filePath, content) {
         const command = buildWriteCommand(filePath, content);
         const result = await this.execute(command);
         if (result.exitCode !== 0) {
+            const output = (result.output || "").trim();
+            if (output.includes(WRITE_EXISTS_OUTPUT)) {
+                return {
+                    error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.`
+                };
+            }
+            const fallback = await this.writeViaUpload(filePath, content);
+            if (!fallback.error) {
+                return fallback;
+            }
+            return {
+                error: output ? `Failed to write file '${filePath}': ${output}` : `Failed to write file '${filePath}'.`
+            };
+        }
+        return {
+            path: filePath,
+            filesUpdate: null
+        };
+    }
+    async writeViaUpload(filePath, content) {
+        const existsCheck = await this.execute(buildExistsCommand(filePath));
+        if (existsCheck.exitCode === 0) {
             return {
                 error: `Cannot write to ${filePath} because it already exists. Read and then make an edit, or write to a new path.`
             };
         }
+        const uploads = await this.uploadFiles([
+            [
+                filePath,
+                Buffer.from(content, "utf-8")
+            ]
+        ]);
+        const first = uploads[0];
+        if (!first) {
+            return {
+                error: `Failed to write file '${filePath}': upload returned no result.`
+            };
+        }
+        if (first.error) {
+            return {
+                error: `Failed to write file '${filePath}': ${first.error}`
+            };
+        }
+        return {
+            path: filePath,
+            filesUpdate: null
+        };
+    }
+    /**
+   * Append content to a file. Creates the file if it doesn't exist.
+   */ async append(filePath, content) {
+        const command = buildAppendCommand(filePath, content);
+        const result = await this.execute(command);
+        if (result.exitCode !== 0) {
+            const output = (result.output || "").trim();
+            return {
+                error: output ? `Failed to append to file '${filePath}': ${output}` : `Failed to append to file '${filePath}'.`
+            };
+        }
         return {
             path: filePath,
             filesUpdate: null
@@ -3046,6 +3523,38 @@ try {
                 };
         }
     }
+    /**
+   * 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).
+   */ async multiEdit(filePath, edits) {
+        if (!edits || edits.length === 0) {
+            return {
+                error: "No edits provided"
+            };
+        }
+        const results = [];
+        for (const edit of edits){
+            var _edit_replaceAll;
+            const result = await this.edit(filePath, edit.oldString, edit.newString, (_edit_replaceAll = edit.replaceAll) != null ? _edit_replaceAll : false);
+            results.push(result);
+            // If any edit fails, return immediately with error
+            if (result.error) {
+                return {
+                    error: `Multi-edit failed at edit ${results.length}: ${result.error}`,
+                    path: filePath,
+                    filesUpdate: null,
+                    results
+                };
+            }
+        }
+        // All edits succeeded
+        return {
+            path: filePath,
+            filesUpdate: null,
+            results
+        };
+    }
 }
 
 const SANDBOX_PROVIDER = 'SANDBOX_PROVIDER';