@xpert-ai/plugin-sdk 3.8.1 → 3.8.3

package/index.cjs.js

@@ -956,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';
@@ -2635,34 +2637,100 @@ 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';
 }
 
-/**
- * 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.
- */ const MAX_LINE_LENGTH = 500;
+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";
+const WRITE_EXISTS_OUTPUT = 'Error: File already exists';
 /**
  * UTF-8 safe Base64 encoding function.
  * Replaces btoa() which only supports Latin1 characters.
@@ -2676,17 +2744,17 @@ const WRITE_EXISTS_OUTPUT = "Error: File already exists";
     const truncated = files.length > limit;
     const finalFiles = truncated ? files.slice(0, limit) : files;
     if (finalFiles.length === 0) {
-        return "No files found";
+        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.)");
+        lines.push('');
+        lines.push('(Results truncated. Consider using a more specific path or pattern.)');
     }
-    return lines.join("\n");
+    return lines.join('\n');
 }
 /**
  * Format grep matches into human-readable output grouped by file.
@@ -2695,28 +2763,28 @@ const WRITE_EXISTS_OUTPUT = "Error: File already exists";
     const truncated = matches.length > limit;
     const finalMatches = truncated ? matches.slice(0, limit) : matches;
     if (finalMatches.length === 0) {
-        return "No matches found";
+        return 'No matches found';
     }
     const lines = [
         `Found ${finalMatches.length} matches`
     ];
-    let currentFile = "";
+    let currentFile = '';
     for (const match of finalMatches){
         if (currentFile !== match.path) {
-            if (currentFile !== "") {
-                lines.push("");
+            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;
+        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.)");
+        lines.push('');
+        lines.push('(Results truncated. Consider using a more specific path or pattern.)');
     }
-    return lines.join("\n");
+    return lines.join('\n');
 }
 /**
  * Node.js command template for glob operations.
@@ -3197,14 +3265,14 @@ console.log(count);
  */ function buildGrepCommand(pattern, searchPath, globPattern) {
     const patternB64 = utf8ToBase64(pattern);
     const pathB64 = utf8ToBase64(searchPath);
-    const globB64 = globPattern ? utf8ToBase64(globPattern) : "";
+    const globB64 = globPattern ? utf8ToBase64(globPattern) : '';
     return `node -e "
 const fs = require('fs');
 const path = require('path');
 
 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"};
+const globPattern = ${globPattern ? `Buffer.from('${globB64}', 'base64').toString('utf-8')` : 'null'};
 
 let regex;
 try {
@@ -3273,8 +3341,8 @@ try {
  *
  * Requires Node.js 20+ on the sandbox host.
  */ class BaseSandbox {
-    async streamExecute(command, onLine) {
-        const result = await this.execute(command);
+    async streamExecute(command, onLine, options) {
+        const result = await this.execute(command, options);
         if (result.output) {
             onLine(result.output);
         }
@@ -3287,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);
@@ -3318,16 +3386,16 @@ try {
    * @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";
+            return 'Error: offset must be a 1-indexed entry number';
         }
         if (limit < 1) {
-            return "Error: limit must be greater than zero";
+            return 'Error: limit must be greater than zero';
         }
         if (depth < 1) {
-            return "Error: depth must be greater than zero";
+            return 'Error: depth must be greater than zero';
         }
         const command = buildListDirCommand(dirPath, offset, limit, depth);
-        const result = await this.execute(command);
+        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}'`;
         }
@@ -3344,7 +3412,7 @@ try {
    * @returns Formatted file content with line numbers, or error message
    */ 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);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return result.output || `Error: File '${filePath}' not found`;
         }
@@ -3352,17 +3420,17 @@ try {
     }
     /**
    * Structured search results or error string for invalid input.
-   */ async grepRaw(pattern, path = "/", include = null) {
+   */ async grepRaw(pattern, path = '/', include = null) {
         const command = buildGrepCommand(pattern, path, include);
-        const result = await this.execute(command);
+        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);
@@ -3379,23 +3447,23 @@ try {
     }
     /**
    * Search file contents for a regex pattern, returning human-readable output.
-   */ async grep(pattern, path = "/", include = null) {
+   */ async grep(pattern, path = '/', include = null) {
         const result = await this.grepRaw(pattern, path, include);
-        if (typeof result === "string") {
+        if (typeof result === 'string') {
             return result;
         }
         if (result.length === 0) {
-            return "No matches found";
+            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);
@@ -3413,10 +3481,10 @@ try {
     }
     /**
    * Find files matching a glob pattern, returning human-readable output.
-   */ async glob(pattern, path = "/") {
+   */ async glob(pattern, path = '/') {
         const files = await this.globInfo(pattern, path);
         if (files.length === 0) {
-            return "No files found";
+            return 'No files found';
         }
         return formatGlobOutput(files);
     }
@@ -3424,9 +3492,9 @@ try {
    * 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();
+            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.`
@@ -3446,7 +3514,7 @@ try {
         };
     }
     async writeViaUpload(filePath, content) {
-        const existsCheck = await this.execute(buildExistsCommand(filePath));
+        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.`
@@ -3455,7 +3523,7 @@ try {
         const uploads = await this.uploadFiles([
             [
                 filePath,
-                Buffer.from(content, "utf-8")
+                Buffer.from(content, 'utf-8')
             ]
         ]);
         const first = uploads[0];
@@ -3478,9 +3546,9 @@ try {
    * 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);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
-            const output = (result.output || "").trim();
+            const output = (result.output || '').trim();
             return {
                 error: output ? `Failed to append to file '${filePath}': ${output}` : `Failed to append to file '${filePath}'.`
             };
@@ -3494,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:
                 {
@@ -3530,7 +3598,7 @@ try {
    */ async multiEdit(filePath, edits) {
         if (!edits || edits.length === 0) {
             return {
-                error: "No edits provided"
+                error: 'No edits provided'
             };
         }
         const results = [];
@@ -3617,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;
@@ -3641,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;
@@ -3655,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;
@@ -3676,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;
@@ -3684,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;
@@ -3698,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;

package/index.esm.js

@@ -936,6 +936,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';
@@ -2615,34 +2617,100 @@ class CancelConversationCommand {
 }
 CancelConversationCommand.type = '[Chat Conversation] Cancel';
 
+const FILE_STORAGE_PROVIDER = 'FILE_STORAGE_PROVIDER';
+const FileStorageProvider = (provider)=>applyDecorators(SetMetadata(FILE_STORAGE_PROVIDER, provider), SetMetadata(STRATEGY_META_KEY, FILE_STORAGE_PROVIDER));
+
+let FileStorageProviderRegistry = class FileStorageProviderRegistry extends BaseStrategyRegistry {
+    constructor(discoveryService, reflector){
+        super(FILE_STORAGE_PROVIDER, discoveryService, reflector);
+    }
+};
+FileStorageProviderRegistry = __decorate([
+    Injectable(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [
+        typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+        typeof Reflector === "undefined" ? Object : Reflector
+    ])
+], FileStorageProviderRegistry);
+
+const FILE_UPLOAD_TARGET_STRATEGY = 'FILE_UPLOAD_TARGET_STRATEGY';
+const FileUploadTargetStrategy = (type)=>applyDecorators(SetMetadata(FILE_UPLOAD_TARGET_STRATEGY, type), SetMetadata(STRATEGY_META_KEY, FILE_UPLOAD_TARGET_STRATEGY));
+
+let FileUploadTargetRegistry = class FileUploadTargetRegistry extends BaseStrategyRegistry {
+    constructor(discoveryService, reflector){
+        super(FILE_UPLOAD_TARGET_STRATEGY, discoveryService, reflector);
+    }
+};
+FileUploadTargetRegistry = __decorate([
+    Injectable(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [
+        typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+        typeof Reflector === "undefined" ? Object : Reflector
+    ])
+], 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';
 }
 
-/**
- * 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.
- */ const MAX_LINE_LENGTH = 500;
+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";
+const WRITE_EXISTS_OUTPUT = 'Error: File already exists';
 /**
  * UTF-8 safe Base64 encoding function.
  * Replaces btoa() which only supports Latin1 characters.
@@ -2656,17 +2724,17 @@ const WRITE_EXISTS_OUTPUT = "Error: File already exists";
     const truncated = files.length > limit;
     const finalFiles = truncated ? files.slice(0, limit) : files;
     if (finalFiles.length === 0) {
-        return "No files found";
+        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.)");
+        lines.push('');
+        lines.push('(Results truncated. Consider using a more specific path or pattern.)');
     }
-    return lines.join("\n");
+    return lines.join('\n');
 }
 /**
  * Format grep matches into human-readable output grouped by file.
@@ -2675,28 +2743,28 @@ const WRITE_EXISTS_OUTPUT = "Error: File already exists";
     const truncated = matches.length > limit;
     const finalMatches = truncated ? matches.slice(0, limit) : matches;
     if (finalMatches.length === 0) {
-        return "No matches found";
+        return 'No matches found';
     }
     const lines = [
         `Found ${finalMatches.length} matches`
     ];
-    let currentFile = "";
+    let currentFile = '';
     for (const match of finalMatches){
         if (currentFile !== match.path) {
-            if (currentFile !== "") {
-                lines.push("");
+            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;
+        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.)");
+        lines.push('');
+        lines.push('(Results truncated. Consider using a more specific path or pattern.)');
     }
-    return lines.join("\n");
+    return lines.join('\n');
 }
 /**
  * Node.js command template for glob operations.
@@ -3177,14 +3245,14 @@ console.log(count);
  */ function buildGrepCommand(pattern, searchPath, globPattern) {
     const patternB64 = utf8ToBase64(pattern);
     const pathB64 = utf8ToBase64(searchPath);
-    const globB64 = globPattern ? utf8ToBase64(globPattern) : "";
+    const globB64 = globPattern ? utf8ToBase64(globPattern) : '';
     return `node -e "
 const fs = require('fs');
 const path = require('path');
 
 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"};
+const globPattern = ${globPattern ? `Buffer.from('${globB64}', 'base64').toString('utf-8')` : 'null'};
 
 let regex;
 try {
@@ -3253,8 +3321,8 @@ try {
  *
  * Requires Node.js 20+ on the sandbox host.
  */ class BaseSandbox {
-    async streamExecute(command, onLine) {
-        const result = await this.execute(command);
+    async streamExecute(command, onLine, options) {
+        const result = await this.execute(command, options);
         if (result.output) {
             onLine(result.output);
         }
@@ -3267,12 +3335,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);
@@ -3298,16 +3366,16 @@ try {
    * @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";
+            return 'Error: offset must be a 1-indexed entry number';
         }
         if (limit < 1) {
-            return "Error: limit must be greater than zero";
+            return 'Error: limit must be greater than zero';
         }
         if (depth < 1) {
-            return "Error: depth must be greater than zero";
+            return 'Error: depth must be greater than zero';
         }
         const command = buildListDirCommand(dirPath, offset, limit, depth);
-        const result = await this.execute(command);
+        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}'`;
         }
@@ -3324,7 +3392,7 @@ try {
    * @returns Formatted file content with line numbers, or error message
    */ 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);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return result.output || `Error: File '${filePath}' not found`;
         }
@@ -3332,17 +3400,17 @@ try {
     }
     /**
    * Structured search results or error string for invalid input.
-   */ async grepRaw(pattern, path = "/", include = null) {
+   */ async grepRaw(pattern, path = '/', include = null) {
         const command = buildGrepCommand(pattern, path, include);
-        const result = await this.execute(command);
+        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);
@@ -3359,23 +3427,23 @@ try {
     }
     /**
    * Search file contents for a regex pattern, returning human-readable output.
-   */ async grep(pattern, path = "/", include = null) {
+   */ async grep(pattern, path = '/', include = null) {
         const result = await this.grepRaw(pattern, path, include);
-        if (typeof result === "string") {
+        if (typeof result === 'string') {
             return result;
         }
         if (result.length === 0) {
-            return "No matches found";
+            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);
@@ -3393,10 +3461,10 @@ try {
     }
     /**
    * Find files matching a glob pattern, returning human-readable output.
-   */ async glob(pattern, path = "/") {
+   */ async glob(pattern, path = '/') {
         const files = await this.globInfo(pattern, path);
         if (files.length === 0) {
-            return "No files found";
+            return 'No files found';
         }
         return formatGlobOutput(files);
     }
@@ -3404,9 +3472,9 @@ try {
    * 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();
+            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.`
@@ -3426,7 +3494,7 @@ try {
         };
     }
     async writeViaUpload(filePath, content) {
-        const existsCheck = await this.execute(buildExistsCommand(filePath));
+        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.`
@@ -3435,7 +3503,7 @@ try {
         const uploads = await this.uploadFiles([
             [
                 filePath,
-                Buffer.from(content, "utf-8")
+                Buffer.from(content, 'utf-8')
             ]
         ]);
         const first = uploads[0];
@@ -3458,9 +3526,9 @@ try {
    * 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);
+        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
-            const output = (result.output || "").trim();
+            const output = (result.output || '').trim();
             return {
                 error: output ? `Failed to append to file '${filePath}': ${output}` : `Failed to append to file '${filePath}'.`
             };
@@ -3474,7 +3542,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:
                 {
@@ -3510,7 +3578,7 @@ try {
    */ async multiEdit(filePath, edits) {
         if (!edits || edits.length === 0) {
             return {
-                error: "No edits provided"
+                error: 'No edits provided'
             };
         }
         const results = [];
@@ -3554,4 +3622,4 @@ SandboxProviderRegistry = __decorate([
     ])
 ], SandboxProviderRegistry);
 
-export { AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CommonParameterRules, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, LLMUsage, LargeLanguageModel, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, STRATEGY_META_KEY, SandboxProviderRegistry, SandboxProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VectorStoreRegistry, VectorStoreStrategy, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WrapWorkflowNodeExecutionCommand, XpFileSystem, XpertServerPlugin, als, calcTokenUsage, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, defineAgentMessageType, defineChannelMessageType, downloadRemoteFile, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, isRemoteFile, isSandboxBackend, isStructuredMessageType, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, runWithRequestContext, sumTokenUsage };
+export { AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CommonParameterRules, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC, DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS, DEFAULT_SANDBOX_SHELL_TIMEOUT_MS, DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, FILE_STORAGE_PROVIDER, FILE_UPLOAD_TARGET_STRATEGY, FileStorageProvider, FileStorageProviderRegistry, FileUploadTargetRegistry, FileUploadTargetStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, LLMUsage, LargeLanguageModel, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, STRATEGY_META_KEY, SandboxProviderRegistry, SandboxProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VectorStoreRegistry, VectorStoreStrategy, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WrapWorkflowNodeExecutionCommand, XpFileSystem, XpertServerPlugin, als, appendSandboxMessage, buildSandboxTimeoutMessage, calcTokenUsage, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, defineAgentMessageType, defineChannelMessageType, downloadRemoteFile, formatSandboxTimeout, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, isRemoteFile, isSandboxBackend, isStructuredMessageType, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, resolveSandboxExecutionOptions, runWithRequestContext, secondsToMilliseconds, sumTokenUsage };

package/package.json

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

package/src/index.d.ts

@@ -13,5 +13,6 @@ export * from './lib/data/index';
 export * from './lib/ai-model/index';
 export * from './lib/agent/index';
 export * from './lib/channel/index';
+export * from './lib/file/index';
 export * from './lib/strategy';
 export * from './lib/sandbox/index';

package/src/lib/core/index.d.ts

@@ -1,4 +1,5 @@
 export * from './file-system';
+export * from './plugin-config';
 export * from './permissions';
 export * from './schema';
 export * from './i18n';

package/src/lib/core/plugin-config.d.ts

@@ -0,0 +1,9 @@
+export interface PluginConfigResolveOptions<TConfig extends object = Record<string, any>> {
+    organizationId?: string;
+    fallbackToGlobal?: boolean;
+    defaults?: Partial<TConfig>;
+}
+export interface IPluginConfigResolver {
+    resolve<TConfig extends object = Record<string, any>>(pluginName: string, options?: PluginConfigResolveOptions<TConfig>): TConfig;
+}
+export declare const PLUGIN_CONFIG_RESOLVER_TOKEN = "XPERT_PLUGIN_CONFIG_RESOLVER";

package/src/lib/file/file-storage/index.d.ts

@@ -0,0 +1,3 @@
+export * from './provider.decorator';
+export * from './provider.interface';
+export * from './provider.registry';

package/src/lib/file/file-storage/provider.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const FILE_STORAGE_PROVIDER = "FILE_STORAGE_PROVIDER";
+export declare const FileStorageProvider: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/file/file-storage/provider.interface.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { FileStorageOption, FileSystem, UploadedFile } from '@metad/contracts';
+export interface IFileStorageProvider {
+    readonly name: string;
+    readonly config?: FileSystem & Record<string, any>;
+    url(path: string): string;
+    path(path: string): string;
+    handler(options: FileStorageOption): any;
+    getFile(file: string): Promise<Buffer>;
+    putFile(fileContent: string | Buffer | URL, path?: string): Promise<UploadedFile>;
+    deleteFile(path: string): Promise<void>;
+    mapUploadedFile?(file: any): UploadedFile;
+}

package/src/lib/file/file-storage/provider.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IFileStorageProvider } from './provider.interface';
+export declare class FileStorageProviderRegistry extends BaseStrategyRegistry<IFileStorageProvider> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/file/file-upload/index.d.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator';
+export * from './strategy.interface';
+export * from './strategy.registry';

package/src/lib/file/file-upload/strategy.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const FILE_UPLOAD_TARGET_STRATEGY = "FILE_UPLOAD_TARGET_STRATEGY";
+export declare const FileUploadTargetStrategy: (type: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/file/file-upload/strategy.interface.d.ts

@@ -0,0 +1,25 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IFileAssetDestination, IFileAssetSource, IStorageFile, IUploadFileTarget } from '@metad/contracts';
+export type TFileUploadRequestContext = {
+    tenantId?: string;
+    organizationId?: string;
+    userId?: string;
+};
+export type TResolvedFileUploadSource = {
+    name: string;
+    originalName: string;
+    mimeType?: string;
+    size?: number;
+    buffer: Buffer;
+    source: IFileAssetSource;
+    storageFile?: IStorageFile;
+};
+export type TFileUploadContext = {
+    request: TFileUploadRequestContext;
+    metadata?: Record<string, any>;
+};
+export type TStorageProviderType = string;
+export interface IFileUploadTargetStrategy<TTarget extends IUploadFileTarget = IUploadFileTarget> {
+    upload(source: TResolvedFileUploadSource, target: TTarget, context: TFileUploadContext): Promise<IFileAssetDestination>;
+}

package/src/lib/file/file-upload/strategy.registry.d.ts

@@ -0,0 +1,6 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IFileUploadTargetStrategy } from './strategy.interface';
+export declare class FileUploadTargetRegistry extends BaseStrategyRegistry<IFileUploadTargetStrategy> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/file/index.d.ts

@@ -0,0 +1,2 @@
+export * from './file-storage';
+export * from './file-upload';

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

@@ -0,0 +1,27 @@
+export interface SandboxExecutionOptions {
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+export interface ResolvedSandboxExecutionOptions {
+    timeoutMs: number;
+    maxOutputBytes: number;
+}
+export declare const SANDBOX_SHELL_TIMEOUT_LIMITS_SEC: {
+    readonly min: 1;
+    readonly max: 3600;
+};
+export declare const DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC = 600;
+export declare const DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC = 120;
+export declare const DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC = 120;
+export declare const DEFAULT_SANDBOX_SHELL_TIMEOUT_MS: number;
+export declare const DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS: number;
+export declare const DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS: number;
+export declare const DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES: number;
+export declare const DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS: Readonly<SandboxExecutionOptions>;
+export declare const DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS: Readonly<SandboxExecutionOptions>;
+export declare const DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS: Readonly<SandboxExecutionOptions>;
+export declare function secondsToMilliseconds(seconds: number): number;
+export declare function formatSandboxTimeout(timeoutMs: number): string;
+export declare function buildSandboxTimeoutMessage(subject: string, timeoutMs: number): string;
+export declare function appendSandboxMessage(output: string, message: string): string;
+export declare function resolveSandboxExecutionOptions(options?: SandboxExecutionOptions, defaults?: SandboxExecutionOptions): ResolvedSandboxExecutionOptions;

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

@@ -1,3 +1,4 @@
+export * from './execution';
 export * from './protocol';
 export * from './sandbox';
 export * from './sandbox.decorator';

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

@@ -1,3 +1,4 @@
+import type { SandboxExecutionOptions } from './execution';
 /**
  * Protocol definition for pluggable memory backends.
  *
@@ -151,11 +152,13 @@ export interface ExecuteResponse {
     exitCode: number | null;
     /** Whether the output was truncated due to backend limitations */
     truncated: boolean;
+    /** Whether the command exceeded its timeout and was terminated */
+    timedOut?: boolean;
 }
 /**
  * Standardized error codes for file upload/download operations.
  */
-export type FileOperationError = "file_not_found" | "permission_denied" | "is_directory" | "invalid_path";
+export type FileOperationError = 'file_not_found' | 'permission_denied' | 'is_directory' | 'invalid_path';
 /**
  * Result of a single file download operation.
  */
@@ -318,7 +321,7 @@ export interface SandboxBackendProtocol extends BackendProtocol {
      * @param command - Full shell command string to execute
      * @returns ExecuteResponse with combined output, exit code, and truncation flag
      */
-    execute(command: string): MaybePromise<ExecuteResponse>;
+    execute(command: string, options?: SandboxExecutionOptions): MaybePromise<ExecuteResponse>;
     /**
      * Execute a command with line-by-line streaming output.
      *
@@ -337,7 +340,7 @@ export interface SandboxBackendProtocol extends BackendProtocol {
      * @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>;
+    streamExecute?(command: string, onLine: (line: string) => void, options?: SandboxExecutionOptions): MaybePromise<ExecuteResponse>;
     /** Unique identifier for the sandbox backend instance */
     readonly id: string;
 }

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

@@ -7,7 +7,8 @@
  *
  * Requires Node.js 20+ on the sandbox host.
  */
-import type { EditOperation, EditResult, ExecuteResponse, FileDownloadResponse, FileInfo, FileUploadResponse, GrepMatch, IndentationOptions, MaybePromise, MultiEditResult, ReadMode, SandboxBackendProtocol, WriteResult } from "./protocol";
+import type { EditOperation, EditResult, ExecuteResponse, FileDownloadResponse, FileInfo, FileUploadResponse, GrepMatch, IndentationOptions, MaybePromise, MultiEditResult, ReadMode, SandboxBackendProtocol, WriteResult } from './protocol';
+import { SandboxExecutionOptions } from './execution';
 /**
  * Base sandbox implementation with execute() as the only abstract method.
  *
@@ -25,8 +26,8 @@ export declare abstract class BaseSandbox implements SandboxBackendProtocol {
      * Execute a command in the sandbox.
      * This is the only method concrete implementations must provide.
      */
-    abstract execute(command: string): MaybePromise<ExecuteResponse>;
-    streamExecute(command: string, onLine: (line: string) => void): Promise<ExecuteResponse>;
+    abstract execute(command: string, options?: SandboxExecutionOptions): MaybePromise<ExecuteResponse>;
+    streamExecute(command: string, onLine: (line: string) => void, options?: SandboxExecutionOptions): Promise<ExecuteResponse>;
     /**
      * Upload multiple files to the sandbox.
      * Implementations must support partial success.

package/src/lib/types.d.ts

@@ -1,4 +1,4 @@
-import { PluginMeta } from '@metad/contracts';
+import { JsonSchemaObjectType, PluginMeta } from '@metad/contracts';
 import type { DynamicModule, INestApplicationContext } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import type { ZodSchema } from 'zod';
@@ -30,6 +30,8 @@ export interface PluginConfigSpec<T extends object = any> {
     schema?: ZodSchema<T>;
     /** Default configuration */
     defaults?: Partial<T>;
+    /** Optional JSON schema used by frontend configuration forms. */
+    formSchema?: JsonSchemaObjectType;
 }
 export interface XpertPlugin<TConfig extends object = any> extends PluginLifecycle, PluginHealth {
     meta: PluginMeta;