@xpert-ai/plugin-sdk 3.8.3 → 3.8.4

package/index.cjs.js

@@ -2011,11 +2011,11 @@ class LLMUsage {
     }
     plus(other) {
         /**
-		 * Add two LLMUsage instances together.
-		 *
-		 * @param other: Another LLMUsage instance to add
-		 * @return: A new LLMUsage instance with summed values
-		 */ if (this.totalTokens === 0) {
+     * Add two LLMUsage instances together.
+     *
+     * @param other: Another LLMUsage instance to add
+     * @return: A new LLMUsage instance with summed values
+     */ if (this.totalTokens === 0) {
             return other;
         } else {
             return new LLMUsage(this.promptTokens + other.promptTokens, other.promptUnitPrice, other.promptPriceUnit, this.promptPrice + other.promptPrice, this.completionTokens + other.completionTokens, other.completionUnitPrice, other.completionPriceUnit, this.completionPrice + other.completionPrice, this.totalTokens + other.totalTokens, this.totalPrice + other.totalPrice, other.currency, this.latency + other.latency);
@@ -2023,11 +2023,11 @@ class LLMUsage {
     }
     add(other) {
         /**
-		 * Overload the + operator to add two LLMUsage instances.
-		 *
-		 * @param other: Another LLMUsage instance to add
-		 * @return: A new LLMUsage instance with summed values
-		 */ return this.plus(other);
+     * Overload the + operator to add two LLMUsage instances.
+     *
+     * @param other: Another LLMUsage instance to add
+     * @return: A new LLMUsage instance with summed values
+     */ return this.plus(other);
     }
     constructor(promptTokens, promptUnitPrice, promptPriceUnit, promptPrice, completionTokens, completionUnitPrice, completionPriceUnit, completionPrice, totalTokens, totalPrice, currency, latency){
         this.promptTokens = promptTokens;
@@ -2147,6 +2147,78 @@ class LargeLanguageModel extends AIModel {
             }
         };
     }
+    createHandleVerboseCallbacks(enabled, logger) {
+        if (!enabled) {
+            return [];
+        }
+        const targetLogger = logger != null ? logger : _class_private_field_loose_base(this, _logger)[_logger];
+        return [
+            {
+                handleChatModelStart: (llm, messages, runId, parentRunId, extraParams, tags, metadata, runName)=>{
+                    targetLogger.verbose(this.formatVerboseLog('chat_model/start', {
+                        runId,
+                        parentRunId,
+                        runName,
+                        model: llm,
+                        messages,
+                        extraParams,
+                        tags,
+                        metadata
+                    }));
+                },
+                handleLLMStart: (llm, prompts, runId, parentRunId, extraParams, tags, metadata, runName)=>{
+                    targetLogger.verbose(this.formatVerboseLog('llm/start', {
+                        runId,
+                        parentRunId,
+                        runName,
+                        model: llm,
+                        prompts,
+                        extraParams,
+                        tags,
+                        metadata
+                    }));
+                },
+                handleLLMEnd: (output, runId, parentRunId, tags, extraParams)=>{
+                    targetLogger.verbose(this.formatVerboseLog('llm/end', {
+                        runId,
+                        parentRunId,
+                        output,
+                        tags,
+                        extraParams
+                    }));
+                },
+                handleLLMError: (err, runId, parentRunId, tags, extraParams)=>{
+                    targetLogger.verbose(this.formatVerboseLog('llm/error', {
+                        runId,
+                        parentRunId,
+                        error: this.formatError(err),
+                        tags,
+                        extraParams
+                    }));
+                }
+            }
+        ];
+    }
+    formatVerboseLog(event, payload) {
+        return `[langchain][${event}] ${this.stringifyLogPayload(payload)}`;
+    }
+    stringifyLogPayload(payload) {
+        try {
+            return JSON.stringify(payload, null, 2);
+        } catch (error) {
+            return `[unserializable payload: ${this.formatError(error)}]`;
+        }
+    }
+    formatError(error) {
+        if (error instanceof Error) {
+            return {
+                name: error.name,
+                message: error.message,
+                stack: error.stack
+            };
+        }
+        return error;
+    }
     constructor(...args){
         super(...args);
         Object.defineProperty(this, _logger, {
@@ -3341,6 +3413,13 @@ try {
  *
  * Requires Node.js 20+ on the sandbox host.
  */ class BaseSandbox {
+    /**
+   * Internal hook for file/search operations. Concrete backends can override
+   * this to distinguish "background helper commands" from user-facing shell
+   * execute calls.
+   */ executeOperation(command, options) {
+        return this.execute(command, options);
+    }
     async streamExecute(command, onLine, options) {
         const result = await this.execute(command, options);
         if (result.output) {
@@ -3355,7 +3434,7 @@ 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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return [];
         }
@@ -3395,7 +3474,7 @@ try {
             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);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return result.output || `Error: Failed to list directory '${dirPath}'`;
         }
@@ -3412,7 +3491,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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return result.output || `Error: File '${filePath}' not found`;
         }
@@ -3422,7 +3501,7 @@ try {
    * Structured search results or error string for invalid input.
    */ async grepRaw(pattern, path = '/', include = null) {
         const command = buildGrepCommand(pattern, path, include);
-        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
         if (result.exitCode === 1) {
             // Check if it's a regex error
             if (result.output.includes('Invalid regex:')) {
@@ -3461,7 +3540,7 @@ try {
    * Structured glob matching returning FileInfo objects.
    */ async globInfo(pattern, path = '/') {
         const command = buildGlobCommand(path, pattern);
-        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
         const infos = [];
         const lines = result.output.trim().split('\n').filter(Boolean);
         for (const line of lines){
@@ -3492,7 +3571,7 @@ try {
    * Create a new file with content.
    */ async write(filePath, content) {
         const command = buildWriteCommand(filePath, content);
-        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             const output = (result.output || '').trim();
             if (output.includes(WRITE_EXISTS_OUTPUT)) {
@@ -3514,7 +3593,7 @@ try {
         };
     }
     async writeViaUpload(filePath, content) {
-        const existsCheck = await this.execute(buildExistsCommand(filePath), DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const existsCheck = await this.executeOperation(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.`
@@ -3546,7 +3625,7 @@ 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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             const output = (result.output || '').trim();
             return {
@@ -3562,7 +3641,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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         switch(result.exitCode){
             case 0:
                 {

package/index.esm.js

@@ -1991,11 +1991,11 @@ class LLMUsage {
     }
     plus(other) {
         /**
-		 * Add two LLMUsage instances together.
-		 *
-		 * @param other: Another LLMUsage instance to add
-		 * @return: A new LLMUsage instance with summed values
-		 */ if (this.totalTokens === 0) {
+     * Add two LLMUsage instances together.
+     *
+     * @param other: Another LLMUsage instance to add
+     * @return: A new LLMUsage instance with summed values
+     */ if (this.totalTokens === 0) {
             return other;
         } else {
             return new LLMUsage(this.promptTokens + other.promptTokens, other.promptUnitPrice, other.promptPriceUnit, this.promptPrice + other.promptPrice, this.completionTokens + other.completionTokens, other.completionUnitPrice, other.completionPriceUnit, this.completionPrice + other.completionPrice, this.totalTokens + other.totalTokens, this.totalPrice + other.totalPrice, other.currency, this.latency + other.latency);
@@ -2003,11 +2003,11 @@ class LLMUsage {
     }
     add(other) {
         /**
-		 * Overload the + operator to add two LLMUsage instances.
-		 *
-		 * @param other: Another LLMUsage instance to add
-		 * @return: A new LLMUsage instance with summed values
-		 */ return this.plus(other);
+     * Overload the + operator to add two LLMUsage instances.
+     *
+     * @param other: Another LLMUsage instance to add
+     * @return: A new LLMUsage instance with summed values
+     */ return this.plus(other);
     }
     constructor(promptTokens, promptUnitPrice, promptPriceUnit, promptPrice, completionTokens, completionUnitPrice, completionPriceUnit, completionPrice, totalTokens, totalPrice, currency, latency){
         this.promptTokens = promptTokens;
@@ -2127,6 +2127,78 @@ class LargeLanguageModel extends AIModel {
             }
         };
     }
+    createHandleVerboseCallbacks(enabled, logger) {
+        if (!enabled) {
+            return [];
+        }
+        const targetLogger = logger != null ? logger : _class_private_field_loose_base(this, _logger)[_logger];
+        return [
+            {
+                handleChatModelStart: (llm, messages, runId, parentRunId, extraParams, tags, metadata, runName)=>{
+                    targetLogger.verbose(this.formatVerboseLog('chat_model/start', {
+                        runId,
+                        parentRunId,
+                        runName,
+                        model: llm,
+                        messages,
+                        extraParams,
+                        tags,
+                        metadata
+                    }));
+                },
+                handleLLMStart: (llm, prompts, runId, parentRunId, extraParams, tags, metadata, runName)=>{
+                    targetLogger.verbose(this.formatVerboseLog('llm/start', {
+                        runId,
+                        parentRunId,
+                        runName,
+                        model: llm,
+                        prompts,
+                        extraParams,
+                        tags,
+                        metadata
+                    }));
+                },
+                handleLLMEnd: (output, runId, parentRunId, tags, extraParams)=>{
+                    targetLogger.verbose(this.formatVerboseLog('llm/end', {
+                        runId,
+                        parentRunId,
+                        output,
+                        tags,
+                        extraParams
+                    }));
+                },
+                handleLLMError: (err, runId, parentRunId, tags, extraParams)=>{
+                    targetLogger.verbose(this.formatVerboseLog('llm/error', {
+                        runId,
+                        parentRunId,
+                        error: this.formatError(err),
+                        tags,
+                        extraParams
+                    }));
+                }
+            }
+        ];
+    }
+    formatVerboseLog(event, payload) {
+        return `[langchain][${event}] ${this.stringifyLogPayload(payload)}`;
+    }
+    stringifyLogPayload(payload) {
+        try {
+            return JSON.stringify(payload, null, 2);
+        } catch (error) {
+            return `[unserializable payload: ${this.formatError(error)}]`;
+        }
+    }
+    formatError(error) {
+        if (error instanceof Error) {
+            return {
+                name: error.name,
+                message: error.message,
+                stack: error.stack
+            };
+        }
+        return error;
+    }
     constructor(...args){
         super(...args);
         Object.defineProperty(this, _logger, {
@@ -3321,6 +3393,13 @@ try {
  *
  * Requires Node.js 20+ on the sandbox host.
  */ class BaseSandbox {
+    /**
+   * Internal hook for file/search operations. Concrete backends can override
+   * this to distinguish "background helper commands" from user-facing shell
+   * execute calls.
+   */ executeOperation(command, options) {
+        return this.execute(command, options);
+    }
     async streamExecute(command, onLine, options) {
         const result = await this.execute(command, options);
         if (result.output) {
@@ -3335,7 +3414,7 @@ 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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return [];
         }
@@ -3375,7 +3454,7 @@ try {
             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);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return result.output || `Error: Failed to list directory '${dirPath}'`;
         }
@@ -3392,7 +3471,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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             return result.output || `Error: File '${filePath}' not found`;
         }
@@ -3402,7 +3481,7 @@ try {
    * Structured search results or error string for invalid input.
    */ async grepRaw(pattern, path = '/', include = null) {
         const command = buildGrepCommand(pattern, path, include);
-        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
         if (result.exitCode === 1) {
             // Check if it's a regex error
             if (result.output.includes('Invalid regex:')) {
@@ -3441,7 +3520,7 @@ try {
    * Structured glob matching returning FileInfo objects.
    */ async globInfo(pattern, path = '/') {
         const command = buildGlobCommand(path, pattern);
-        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS);
         const infos = [];
         const lines = result.output.trim().split('\n').filter(Boolean);
         for (const line of lines){
@@ -3472,7 +3551,7 @@ try {
    * Create a new file with content.
    */ async write(filePath, content) {
         const command = buildWriteCommand(filePath, content);
-        const result = await this.execute(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             const output = (result.output || '').trim();
             if (output.includes(WRITE_EXISTS_OUTPUT)) {
@@ -3494,7 +3573,7 @@ try {
         };
     }
     async writeViaUpload(filePath, content) {
-        const existsCheck = await this.execute(buildExistsCommand(filePath), DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const existsCheck = await this.executeOperation(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.`
@@ -3526,7 +3605,7 @@ 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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         if (result.exitCode !== 0) {
             const output = (result.output || '').trim();
             return {
@@ -3542,7 +3621,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, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
+        const result = await this.executeOperation(command, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS);
         switch(result.exitCode){
             case 0:
                 {

package/package.json

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

package/src/lib/ai-model/llm.d.ts

@@ -41,6 +41,15 @@ export declare abstract class LargeLanguageModel extends AIModel {
         handleLLMError: (err: any) => void;
     };
     protected getCustomizableModelSchemaFromCredentials(model: string, credentials: Record<string, any>): AIModelEntity | null;
+    protected createHandleVerboseCallbacks(enabled?: boolean, logger?: Logger): {
+        handleChatModelStart: (llm: any, messages: any, runId: any, parentRunId: any, extraParams: any, tags: any, metadata: any, runName: any) => void;
+        handleLLMStart: (llm: any, prompts: any, runId: any, parentRunId: any, extraParams: any, tags: any, metadata: any, runName: any) => void;
+        handleLLMEnd: (output: any, runId: any, parentRunId: any, tags: any, extraParams: any) => void;
+        handleLLMError: (err: any, runId: any, parentRunId: any, tags: any, extraParams: any) => void;
+    }[];
+    private formatVerboseLog;
+    private stringifyLogPayload;
+    private formatError;
 }
 export declare function calcTokenUsage(output: LLMResult): TTokenUsage;
 /**

package/src/lib/core/permissions/general.d.ts

@@ -1,4 +1,4 @@
-import type { IIntegration } from '@metad/contracts';
+import type { IIntegration, IPagination } from '@metad/contracts';
 /**
  * Base Permission type
  */
@@ -68,4 +68,5 @@ export declare const INTEGRATION_PERMISSION_SERVICE_TOKEN = "XPERT_PLUGIN_INTEGR
  */
 export interface IntegrationPermissionService {
     read<TIntegration = IIntegration>(id: string, options?: Record<string, any>): Promise<TIntegration | null>;
+    findAll<TIntegration = IIntegration>(options?: Record<string, any>): Promise<IPagination<TIntegration>>;
 }

package/src/lib/integration/strategy.interface.d.ts

@@ -2,10 +2,22 @@ import { IIntegration, TIntegrationProvider } from '@metad/contracts';
 export type TIntegrationStrategyParams = {
     query: string;
 };
+export type IntegrationTestProbe = {
+    connected?: boolean;
+    state?: string;
+    lastError?: string | null;
+    checkedAt?: number | null;
+};
+export type IntegrationTestResult = {
+    webhookUrl?: string;
+    mode?: string;
+    warnings?: string[];
+    probe?: IntegrationTestProbe;
+} & Record<string, unknown>;
 export interface IntegrationStrategy<T = unknown> {
     meta: TIntegrationProvider;
     execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
-    validateConfig?(config: T, integration?: IIntegration<T>): Promise<void | {
-        webhookUrl: string;
-    }>;
+    onUpdate?(previous: IIntegration<T>, current: IIntegration<any>): Promise<void> | void;
+    onDelete?(integration: IIntegration<T>): Promise<void> | void;
+    validateConfig?(config: T, integration?: IIntegration<T>): Promise<void | IntegrationTestResult>;
 }

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

@@ -343,6 +343,8 @@ export interface SandboxBackendProtocol extends BackendProtocol {
     streamExecute?(command: string, onLine: (line: string) => void, options?: SandboxExecutionOptions): MaybePromise<ExecuteResponse>;
     /** Unique identifier for the sandbox backend instance */
     readonly id: string;
+    /** Canonical sandbox environment identifier bound to this backend */
+    readonly environmentId?: string | null;
 }
 /**
  * Type guard to check if a backend supports execution.

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

@@ -22,6 +22,12 @@ export declare abstract class BaseSandbox implements SandboxBackendProtocol {
     workingDirectory: string;
     /** Unique identifier for the sandbox backend */
     abstract readonly id: string;
+    /**
+     * Internal hook for file/search operations. Concrete backends can override
+     * this to distinguish "background helper commands" from user-facing shell
+     * execute calls.
+     */
+    protected executeOperation(command: string, options?: SandboxExecutionOptions): MaybePromise<ExecuteResponse>;
     /**
      * Execute a command in the sandbox.
      * This is the only method concrete implementations must provide.

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

@@ -1,26 +1,22 @@
-import { TSandboxProviderMeta } from "@metad/contracts";
-import { SandboxBackendProtocol } from "./protocol";
+import { TSandboxProviderMeta, TSandboxWorkForType } from '@metad/contracts';
+import { SandboxBackendProtocol } from './protocol';
 export type SandboxProviderCreateOptions = {
     /**
      * Working space directory for the sandbox instance
      */
     workingDirectory?: string;
     /**
-     * Sandbox container environment identifier
+     * Canonical sandbox environment identifier that owns the container lifecycle.
      */
     environmentId?: string;
     /**
      * Tenant identifier
      */
     tenantId?: string;
-    /**
-     * User identifier
-     */
-    userId?: string;
-    /**
-     * Project identifier
-     */
-    projectId?: string;
+    workFor: {
+        type: TSandboxWorkForType;
+        id: string;
+    };
 };
 export interface ISandboxProvider<T extends SandboxBackendProtocol = SandboxBackendProtocol> {
     type: string;