@xpert-ai/plugin-sdk 3.8.0 → 3.8.3

package/package.json

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

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;