@xpert-ai/plugin-sdk 3.8.0 → 3.8.3

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));
@@ -952,6 +956,8 @@ BuiltinToolset.provider = '';
     }
 }
 
+const PLUGIN_CONFIG_RESOLVER_TOKEN = 'XPERT_PLUGIN_CONFIG_RESOLVER';
+
 /**
  * System token for resolving integration read service from plugin context.
  */ const INTEGRATION_PERMISSION_SERVICE_TOKEN = 'XPERT_PLUGIN_INTEGRATION_PERMISSION_SERVICE';
@@ -2384,6 +2390,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 +2401,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));
@@ -2627,41 +2637,167 @@ class CancelConversationCommand {
 }
 CancelConversationCommand.type = '[Chat Conversation] Cancel';
 
+const FILE_STORAGE_PROVIDER = 'FILE_STORAGE_PROVIDER';
+const FileStorageProvider = (provider)=>common.applyDecorators(common.SetMetadata(FILE_STORAGE_PROVIDER, provider), common.SetMetadata(STRATEGY_META_KEY, FILE_STORAGE_PROVIDER));
+
+exports.FileStorageProviderRegistry = class FileStorageProviderRegistry extends BaseStrategyRegistry {
+    constructor(discoveryService, reflector){
+        super(FILE_STORAGE_PROVIDER, discoveryService, reflector);
+    }
+};
+exports.FileStorageProviderRegistry = __decorate([
+    common.Injectable(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [
+        typeof core.DiscoveryService === "undefined" ? Object : core.DiscoveryService,
+        typeof core.Reflector === "undefined" ? Object : core.Reflector
+    ])
+], exports.FileStorageProviderRegistry);
+
+const FILE_UPLOAD_TARGET_STRATEGY = 'FILE_UPLOAD_TARGET_STRATEGY';
+const FileUploadTargetStrategy = (type)=>common.applyDecorators(common.SetMetadata(FILE_UPLOAD_TARGET_STRATEGY, type), common.SetMetadata(STRATEGY_META_KEY, FILE_UPLOAD_TARGET_STRATEGY));
+
+exports.FileUploadTargetRegistry = class FileUploadTargetRegistry extends BaseStrategyRegistry {
+    constructor(discoveryService, reflector){
+        super(FILE_UPLOAD_TARGET_STRATEGY, discoveryService, reflector);
+    }
+};
+exports.FileUploadTargetRegistry = __decorate([
+    common.Injectable(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [
+        typeof core.DiscoveryService === "undefined" ? Object : core.DiscoveryService,
+        typeof core.Reflector === "undefined" ? Object : core.Reflector
+    ])
+], exports.FileUploadTargetRegistry);
+
+const SANDBOX_SHELL_TIMEOUT_LIMITS_SEC = {
+    min: 1,
+    max: 3600
+};
+const DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC = 600;
+const DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC = 120;
+const DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC = 120;
+const DEFAULT_SANDBOX_SHELL_TIMEOUT_MS = DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC * 1000;
+const DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS = DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC * 1000;
+const DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS = DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC * 1000;
+const DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES = 1024 * 1024;
+const DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS = {
+    timeoutMs: DEFAULT_SANDBOX_SHELL_TIMEOUT_MS,
+    maxOutputBytes: DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES
+};
+const DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS = {
+    timeoutMs: DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS,
+    maxOutputBytes: DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES
+};
+const DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS = {
+    timeoutMs: DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS,
+    maxOutputBytes: DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES
+};
+function secondsToMilliseconds(seconds) {
+    return Math.trunc(seconds * 1000);
+}
+function formatSandboxTimeout(timeoutMs) {
+    const timeoutSeconds = timeoutMs / 1000;
+    const secondsLabel = Number.isInteger(timeoutSeconds) ? String(timeoutSeconds) : Number(timeoutSeconds.toFixed(3)).toString();
+    return `${secondsLabel}s (${timeoutMs}ms)`;
+}
+function buildSandboxTimeoutMessage(subject, timeoutMs) {
+    return `${subject} timed out after ${formatSandboxTimeout(timeoutMs)}`;
+}
+function appendSandboxMessage(output, message) {
+    return output ? `${output}\n${message}` : message;
+}
+function resolveSandboxExecutionOptions(options, defaults = DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS) {
+    const timeoutMs = typeof (options == null ? void 0 : options.timeoutMs) === 'number' && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? Math.trunc(options.timeoutMs) : typeof defaults.timeoutMs === 'number' && Number.isFinite(defaults.timeoutMs) && defaults.timeoutMs > 0 ? Math.trunc(defaults.timeoutMs) : DEFAULT_SANDBOX_SHELL_TIMEOUT_MS;
+    const maxOutputBytes = typeof (options == null ? void 0 : options.maxOutputBytes) === 'number' && Number.isFinite(options.maxOutputBytes) && options.maxOutputBytes > 0 ? Math.trunc(options.maxOutputBytes) : typeof defaults.maxOutputBytes === 'number' && Number.isFinite(defaults.maxOutputBytes) && defaults.maxOutputBytes > 0 ? Math.trunc(defaults.maxOutputBytes) : DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES;
+    return {
+        timeoutMs,
+        maxOutputBytes
+    };
+}
+
 /**
- * Protocol definition for pluggable memory backends.
- *
- * This module defines the BackendProtocol that all backend implementations
- * must follow. Backends can store files in different locations (state, filesystem,
- * database, etc.) and provide a uniform interface for file operations.
- */ /**
  * Type guard to check if a backend supports execution.
  *
  * @param backend - Backend instance to check
  * @returns True if the backend implements SandboxBackendProtocol
  */ function isSandboxBackend(backend) {
-    return typeof backend.execute === "function" && typeof backend.id === "string";
+    return typeof backend.execute === 'function' && typeof backend.id === 'string';
 }
 
+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');
+}
 /**
- * BaseSandbox: Abstract base class for sandbox backends with command execution.
- *
- * This class provides default implementations for all SandboxBackendProtocol
- * methods using shell commands executed via execute(). Concrete implementations
- * only need to implement the execute() method.
- *
- * Requires Node.js 20+ on the sandbox host.
- */ /**
  * 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 +2842,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 +2867,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 +3006,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 +3198,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 +3263,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 +3341,13 @@ try {
  *
  * Requires Node.js 20+ on the sandbox host.
  */ class BaseSandbox {
+    async streamExecute(command, onLine, options) {
+        const result = await this.execute(command, options);
+        if (result.output) {
+            onLine(result.output);
+        }
+        return result;
+    }
     /**
    * List files and directories in the specified directory (non-recursive).
    *
@@ -2913,12 +3355,12 @@ try {
    * @returns List of FileInfo objects for files and directories directly in the directory.
    */ async lsInfo(path) {
         const command = buildLsCommand(path);
-        const result = await this.execute(command);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return [];
         }
         const infos = [];
-        const lines = result.output.trim().split("\n").filter(Boolean);
+        const lines = result.output.trim().split('\n').filter(Boolean);
         for (const line of lines){
             try {
                 const parsed = JSON.parse(line);
@@ -2935,33 +3377,60 @@ 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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        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);
-        const result = await this.execute(command);
+   */ 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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         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);
-        const result = await this.execute(command);
+   */ async grepRaw(pattern, path = '/', include = null) {
+        const command = buildGrepCommand(pattern, path, include);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
         if (result.exitCode === 1) {
             // Check if it's a regex error
-            if (result.output.includes("Invalid regex:")) {
+            if (result.output.includes('Invalid regex:')) {
                 return result.output.trim();
             }
         }
         const matches = [];
-        const lines = result.output.trim().split("\n").filter(Boolean);
+        const lines = result.output.trim().split('\n').filter(Boolean);
         for (const line of lines){
             try {
                 const parsed = JSON.parse(line);
@@ -2977,12 +3446,24 @@ 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 = "/") {
+   */ async globInfo(pattern, path = '/') {
         const command = buildGlobCommand(path, pattern);
-        const result = await this.execute(command);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
         const infos = [];
-        const lines = result.output.trim().split("\n").filter(Boolean);
+        const lines = result.output.trim().split('\n').filter(Boolean);
         for (const line of lines){
             try {
                 const parsed = JSON.parse(line);
@@ -2999,15 +3480,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);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         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), DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        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
@@ -3017,7 +3562,7 @@ try {
    * Edit a file by replacing string occurrences.
    */ async edit(filePath, oldString, newString, replaceAll = false) {
         const command = buildEditCommand(filePath, oldString, newString, replaceAll);
-        const result = await this.execute(command);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         switch(result.exitCode){
             case 0:
                 {
@@ -3046,6 +3591,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';
@@ -3108,11 +3685,25 @@ exports.CreateModelClientCommand = CreateModelClientCommand;
 exports.CredentialsValidateFailedError = CredentialsValidateFailedError;
 exports.DATASOURCE_STRATEGY = DATASOURCE_STRATEGY;
 exports.DEFAULT_EXECUTION_CONFIG = DEFAULT_EXECUTION_CONFIG;
+exports.DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES = DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES;
+exports.DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS = DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS;
+exports.DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS = DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS;
+exports.DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC = DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC;
+exports.DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS = DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS;
+exports.DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS = DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS;
+exports.DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC = DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC;
+exports.DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS = DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS;
+exports.DEFAULT_SANDBOX_SHELL_TIMEOUT_MS = DEFAULT_SANDBOX_SHELL_TIMEOUT_MS;
+exports.DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC = DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC;
 exports.DOCUMENT_SOURCE_STRATEGY = DOCUMENT_SOURCE_STRATEGY;
 exports.DOCUMENT_TRANSFORMER_STRATEGY = DOCUMENT_TRANSFORMER_STRATEGY;
 exports.DataSourceStrategy = DataSourceStrategy;
 exports.DocumentSourceStrategy = DocumentSourceStrategy;
 exports.DocumentTransformerStrategy = DocumentTransformerStrategy;
+exports.FILE_STORAGE_PROVIDER = FILE_STORAGE_PROVIDER;
+exports.FILE_UPLOAD_TARGET_STRATEGY = FILE_UPLOAD_TARGET_STRATEGY;
+exports.FileStorageProvider = FileStorageProvider;
+exports.FileUploadTargetStrategy = FileUploadTargetStrategy;
 exports.GLOBAL_ORGANIZATION_SCOPE = GLOBAL_ORGANIZATION_SCOPE;
 exports.HANDOFF_PERMISSION_SERVICE_TOKEN = HANDOFF_PERMISSION_SERVICE_TOKEN;
 exports.HANDOFF_PROCESSOR_STRATEGY = HANDOFF_PROCESSOR_STRATEGY;
@@ -3132,6 +3723,7 @@ exports.LargeLanguageModel = LargeLanguageModel;
 exports.ORGANIZATION_METADATA_KEY = ORGANIZATION_METADATA_KEY;
 exports.OpenAICompatibleReranker = OpenAICompatibleReranker;
 exports.PERMISSION_OPERATION_METADATA_KEY = PERMISSION_OPERATION_METADATA_KEY;
+exports.PLUGIN_CONFIG_RESOLVER_TOKEN = PLUGIN_CONFIG_RESOLVER_TOKEN;
 exports.PLUGIN_METADATA = PLUGIN_METADATA;
 exports.PLUGIN_METADATA_KEY = PLUGIN_METADATA_KEY;
 exports.PROVIDE_AI_MODEL_LLM = PROVIDE_AI_MODEL_LLM;
@@ -3146,6 +3738,7 @@ exports.RequirePermissionOperation = RequirePermissionOperation;
 exports.RerankModel = RerankModel;
 exports.RetrieverStrategy = RetrieverStrategy;
 exports.SANDBOX_PROVIDER = SANDBOX_PROVIDER;
+exports.SANDBOX_SHELL_TIMEOUT_LIMITS_SEC = SANDBOX_SHELL_TIMEOUT_LIMITS_SEC;
 exports.STRATEGY_META_KEY = STRATEGY_META_KEY;
 exports.SandboxProviderStrategy = SandboxProviderStrategy;
 exports.Speech2TextChatModel = Speech2TextChatModel;
@@ -3167,6 +3760,8 @@ exports.WrapWorkflowNodeExecutionCommand = WrapWorkflowNodeExecutionCommand;
 exports.XpFileSystem = XpFileSystem;
 exports.XpertServerPlugin = XpertServerPlugin;
 exports.als = als;
+exports.appendSandboxMessage = appendSandboxMessage;
+exports.buildSandboxTimeoutMessage = buildSandboxTimeoutMessage;
 exports.calcTokenUsage = calcTokenUsage;
 exports.chunkText = chunkText;
 exports.countTokensSafe = countTokensSafe;
@@ -3175,6 +3770,7 @@ exports.createPluginLogger = createPluginLogger;
 exports.defineAgentMessageType = defineAgentMessageType;
 exports.defineChannelMessageType = defineChannelMessageType;
 exports.downloadRemoteFile = downloadRemoteFile;
+exports.formatSandboxTimeout = formatSandboxTimeout;
 exports.getErrorMessage = getErrorMessage;
 exports.getModelContextSize = getModelContextSize;
 exports.getPermissionOperationMetadata = getPermissionOperationMetadata;
@@ -3189,5 +3785,7 @@ exports.loadYamlFile = loadYamlFile;
 exports.mergeCredentials = mergeCredentials;
 exports.mergeParentChildChunks = mergeParentChildChunks;
 exports.normalizeContextSize = normalizeContextSize;
+exports.resolveSandboxExecutionOptions = resolveSandboxExecutionOptions;
 exports.runWithRequestContext = runWithRequestContext;
+exports.secondsToMilliseconds = secondsToMilliseconds;
 exports.sumTokenUsage = sumTokenUsage;