@xpert-ai/plugin-sdk 3.7.1 → 3.8.0

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

@@ -0,0 +1,265 @@
+/**
+ * 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.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Structured file listing info.
+ *
+ * Minimal contract used across backends. Only "path" is required.
+ * Other fields are best-effort and may be absent depending on backend.
+ */
+export interface FileInfo {
+    /** File path */
+    path: string;
+    /** Whether this is a directory */
+    is_dir?: boolean;
+    /** File size in bytes (approximate) */
+    size?: number;
+    /** ISO 8601 timestamp of last modification */
+    modified_at?: string;
+}
+/**
+ * Structured grep match entry.
+ */
+export interface GrepMatch {
+    /** File path where match was found */
+    path: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** The matching line text */
+    text: string;
+}
+/**
+ * File data structure used by backends.
+ *
+ * All file data is represented as objects with this structure:
+ */
+export interface FileData {
+    /** Lines of text content */
+    content: string[];
+    /** ISO format timestamp of creation */
+    created_at: string;
+    /** ISO format timestamp of last modification */
+    modified_at: string;
+}
+/**
+ * Result from backend write 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 WriteResult {
+    /** Error message on failure, undefined on success */
+    error?: string;
+    /** File path of written 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;
+    /** Metadata for the write operation, attached to the ToolMessage */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from backend 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 EditResult {
+    /** 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;
+    /** Number of replacements made, undefined on failure */
+    occurrences?: number;
+    /** Metadata for the edit operation, attached to the ToolMessage */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of code execution.
+ * Simplified schema optimized for LLM consumption.
+ */
+export interface ExecuteResponse {
+    /** Combined stdout and stderr output of the executed command */
+    output: string;
+    /** The process exit code. 0 indicates success, non-zero indicates failure */
+    exitCode: number | null;
+    /** Whether the output was truncated due to backend limitations */
+    truncated: boolean;
+}
+/**
+ * Standardized error codes for file upload/download operations.
+ */
+export type FileOperationError = "file_not_found" | "permission_denied" | "is_directory" | "invalid_path";
+/**
+ * Result of a single file download operation.
+ */
+export interface FileDownloadResponse {
+    /** The file path that was requested */
+    path: string;
+    /** File contents as Uint8Array on success, null on failure */
+    content: Uint8Array | null;
+    /** Standardized error code on failure, null on success */
+    error: FileOperationError | null;
+}
+/**
+ * Result of a single file upload operation.
+ */
+export interface FileUploadResponse {
+    /** The file path that was requested */
+    path: string;
+    /** Standardized error code on failure, null on success */
+    error: FileOperationError | null;
+}
+/**
+ * Protocol for pluggable memory backends (single, unified).
+ *
+ * Backends can store files in different locations (state, filesystem, database, etc.)
+ * and provide a uniform interface for file operations.
+ *
+ * All file data is represented as objects with the FileData structure.
+ *
+ * Methods can return either direct values or Promises, allowing both
+ * synchronous and asynchronous implementations.
+ */
+export interface BackendProtocol {
+    /**
+     * Structured listing with file metadata.
+     *
+     * Lists files and directories in the specified directory (non-recursive).
+     * Directories have a trailing / in their path and is_dir=true.
+     *
+     * @param path - Absolute path to directory
+     * @returns List of FileInfo objects for files and directories directly in the directory
+     */
+    lsInfo(path: string): MaybePromise<FileInfo[]>;
+    /**
+     * 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
+     * @returns Formatted file content with line numbers, or error message
+     */
+    read(filePath: string, offset?: number, limit?: number): MaybePromise<string>;
+    /**
+     * Structured search results or error string for invalid input.
+     *
+     * Searches file contents for a regex pattern.
+     *
+     * @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")
+     * @returns List of GrepMatch objects or error string for invalid regex
+     */
+    grepRaw(pattern: string, path?: string | null, glob?: string | null): MaybePromise<GrepMatch[] | string>;
+    /**
+     * Structured glob matching returning FileInfo objects.
+     *
+     * @param pattern - Glob pattern (e.g., `*.py`, `**\/*.ts`)
+     * @param path - Base path to search from (default: "/")
+     * @returns List of FileInfo objects matching the pattern
+     */
+    globInfo(pattern: string, path?: string): MaybePromise<FileInfo[]>;
+    /**
+     * Create a new file.
+     *
+     * @param filePath - Absolute file path
+     * @param content - File content as string
+     * @returns WriteResult with error populated on failure
+     */
+    write(filePath: string, content: string): MaybePromise<WriteResult>;
+    /**
+     * Edit a file by replacing string occurrences.
+     *
+     * @param filePath - Absolute file path
+     * @param oldString - String to find and replace
+     * @param newString - Replacement string
+     * @param replaceAll - If true, replace all occurrences (default: false)
+     * @returns EditResult with error, path, filesUpdate, and occurrences
+     */
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): MaybePromise<EditResult>;
+    /**
+     * Upload multiple files.
+     *
+     * @param files - List of [path, content] tuples to upload
+     * @returns List of FileUploadResponse objects, one per input file
+     */
+    uploadFiles(files: Array<[string, Uint8Array]>): MaybePromise<FileUploadResponse[]>;
+    /**
+     * Download multiple files.
+     *
+     * @param paths - List of file paths to download
+     * @returns List of FileDownloadResponse objects, one per input path
+     */
+    downloadFiles(paths: string[]): MaybePromise<FileDownloadResponse[]>;
+}
+/**
+ * Protocol for sandboxed backends with isolated runtime.
+ * Sandboxed backends run in isolated environments (e.g., containers)
+ * and communicate via defined interfaces.
+ */
+export interface SandboxBackendProtocol extends BackendProtocol {
+    /**
+     * Execute a command in the sandbox.
+     *
+     * @param command - Full shell command string to execute
+     * @returns ExecuteResponse with combined output, exit code, and truncation flag
+     */
+    execute(command: string): MaybePromise<ExecuteResponse>;
+    /** Unique identifier for the sandbox backend instance */
+    readonly id: string;
+}
+/**
+ * Type guard to check if a backend supports execution.
+ *
+ * @param backend - Backend instance to check
+ * @returns True if the backend implements SandboxBackendProtocol
+ */
+export declare function isSandboxBackend(backend: BackendProtocol): backend is SandboxBackendProtocol;
+/**
+ * State and store container for backend initialization.
+ *
+ * This provides a clean interface for what backends need to access:
+ * - state: Current agent state (with files, messages, etc.)
+ * - store: Optional persistent store for cross-conversation data
+ *
+ * Different contexts build this differently:
+ * - Tools: Extract state via getCurrentTaskInput(config)
+ * - Middleware: Use request.state directly
+ */
+export interface StateAndStore {
+    /** Current agent state with files, messages, etc. */
+    state: unknown;
+    /** Optional BaseStore for persistent cross-conversation storage */
+    /** Optional assistant ID for per-assistant isolation in store */
+    assistantId?: string;
+}
+/**
+ * Factory function type for creating backend instances.
+ *
+ * Backends receive StateAndStore which contains the current state
+ * and optional store, extracted from the execution context.
+ *
+ * @example
+ * ```typescript
+ * // Using in middleware
+ * const middleware = createFilesystemMiddleware({
+ *   backend: (stateAndStore) => new StateBackend(stateAndStore)
+ * });
+ * ```
+ */
+export type BackendFactory = (stateAndStore: StateAndStore) => BackendProtocol;

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

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import type { EditResult, ExecuteResponse, FileDownloadResponse, FileInfo, FileUploadResponse, GrepMatch, MaybePromise, SandboxBackendProtocol, WriteResult } from "./protocol";
+/**
+ * Base sandbox implementation with execute() as the only abstract method.
+ *
+ * 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.
+ */
+export declare abstract class BaseSandbox implements SandboxBackendProtocol {
+    /** 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>;
+    /**
+     * Upload multiple files to the sandbox.
+     * Implementations must support partial success.
+     */
+    abstract uploadFiles(files: Array<[string, Uint8Array]>): MaybePromise<FileUploadResponse[]>;
+    /**
+     * Download multiple files from the sandbox.
+     * Implementations must support partial success.
+     */
+    abstract downloadFiles(paths: string[]): MaybePromise<FileDownloadResponse[]>;
+    /**
+     * List files and directories in the specified directory (non-recursive).
+     *
+     * @param path - Absolute path to directory
+     * @returns List of FileInfo objects for files and directories directly in the directory.
+     */
+    lsInfo(path: string): Promise<FileInfo[]>;
+    /**
+     * Read file content with line numbers.
+     *
+     * @param filePath - Absolute file path
+     * @param offset - Line offset to start reading from (0-indexed)
+     * @param limit - Maximum number of lines to read
+     * @returns Formatted file content with line numbers, or error message
+     */
+    read(filePath: string, offset?: number, limit?: number): Promise<string>;
+    /**
+     * Structured search results or error string for invalid input.
+     */
+    grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
+    /**
+     * Structured glob matching returning FileInfo objects.
+     */
+    globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
+    /**
+     * Create a new file with content.
+     */
+    write(filePath: string, content: string): Promise<WriteResult>;
+    /**
+     * Edit a file by replacing string occurrences.
+     */
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+}

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

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

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

@@ -0,0 +1,38 @@
+import { TSandboxProviderMeta } from "@metad/contracts";
+import { SandboxBackendProtocol } from "./protocol";
+export type SandboxProviderCreateOptions = {
+    /**
+     * Working space directory for the sandbox instance
+     */
+    workingDirectory?: string;
+    /**
+     * Sandbox container environment identifier
+     */
+    environmentId?: string;
+    /**
+     * Tenant identifier
+     */
+    tenantId?: string;
+    /**
+     * User identifier
+     */
+    userId?: string;
+    /**
+     * Project identifier
+     */
+    projectId?: string;
+};
+export interface ISandboxProvider<T extends SandboxBackendProtocol = SandboxBackendProtocol> {
+    type: string;
+    meta: TSandboxProviderMeta;
+    /**
+     * Create a new sandbox instance
+     *
+     * @param options
+     */
+    create(options?: SandboxProviderCreateOptions): Promise<T>;
+    /**
+     * Get default working directory for the sandbox instances
+     */
+    getDefaultWorkingDir(): string;
+}

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

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

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

@@ -1,5 +1,5 @@
 import { DynamicStructuredTool } from '@langchain/core/tools';
-import { I18nObject } from '@metad/contracts';
+import { I18nObject, IconDefinition } from '@metad/contracts';
 import { ZodSchema } from 'zod';
 import { BuiltinToolset } from './builtin';
 export interface IToolsetStrategy<TConfig = any> {
@@ -13,11 +13,7 @@ export interface IToolsetStrategy<TConfig = any> {
         label: I18nObject;
         description?: I18nObject;
         configSchema: any;
-        icon?: {
-            svg?: string;
-            png?: string;
-            color?: string;
-        };
+        icon?: IconDefinition;
     };
     /**
      * Validate the configuration

package/src/lib/types.d.ts

@@ -1,6 +1,8 @@
 import { PluginMeta } from '@metad/contracts';
 import type { DynamicModule, INestApplicationContext } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
 import type { ZodSchema } from 'zod';
+import type { Permissions } from './core/permissions';
 export declare const ORGANIZATION_METADATA_KEY = "xpert:organizationId";
 export declare const PLUGIN_METADATA_KEY = "xpert:pluginName";
 export declare const GLOBAL_ORGANIZATION_SCOPE = "global";
@@ -32,11 +34,14 @@ export interface PluginConfigSpec<T extends object = any> {
 export interface XpertPlugin<TConfig extends object = any> extends PluginLifecycle, PluginHealth {
     meta: PluginMeta;
     config?: PluginConfigSpec<TConfig>;
+    /** Declares the required system-level permissions for this plugin. */
+    permissions?: Permissions;
     /** Returns the DynamicModule to be mounted to the main application (can be set as global) */
     register(ctx: PluginContext<TConfig>): DynamicModule;
 }
 export interface PluginContext<TConfig extends object = any> {
-    app: INestApplicationContext;
+    module: ModuleRef;
+    app?: INestApplicationContext;
     logger: PluginLogger;
     config: TConfig;
     /** Helper method to access other Providers in the container */
@@ -49,3 +54,4 @@ export interface PluginLogger {
     warn(msg: string, meta?: any): void;
     error(msg: string, meta?: any): void;
 }
+export type PromiseOrValue<T> = T | Promise<T>;

package/src/lib/workflow/node/strategy.interface.d.ts

@@ -1,6 +1,7 @@
 import { Runnable } from '@langchain/core/runnables';
 import { BaseChannel } from '@langchain/langgraph';
-import { IEnvironment, IWorkflowNode, TWorkflowNodeMeta, TXpertGraph, TXpertParameter, TXpertTeamNode } from '@metad/contracts';
+import { IEnvironment, IWorkflowNode, TWorkflowNodeMeta, TXpertGraph, TWorkflowVarGroup, TXpertParameter, TXpertTeamNode } from '@metad/contracts';
+import { PromiseOrValue } from '../../types';
 export type TWorkflowNodeParams<TConfig = any> = {
     xpertId: string;
     agentKey?: string;
@@ -36,6 +37,7 @@ export interface IWorkflowNodeStrategy<TConfig = any, TResult = any> {
         xpertId: string;
         environment: IEnvironment;
         isDraft: boolean;
-    }): TWorkflowNodeResult;
+    }): PromiseOrValue<TWorkflowNodeResult>;
+    inputVariables?(entity: IWorkflowNode, variables?: TWorkflowVarGroup[]): TXpertParameter[];
     outputVariables(entity: IWorkflowNode): TXpertParameter[];
 }

package/src/lib/workflow/trigger/strategy.interface.d.ts

@@ -1,4 +1,9 @@
 import { TWorkflowTriggerMeta, TXpertTeamNode } from '@metad/contracts';
+export type TWorkflowTriggerBootstrapMode = 'replay_publish' | 'skip';
+export type TWorkflowTriggerBootstrapConfig = {
+    mode: TWorkflowTriggerBootstrapMode;
+    critical?: boolean;
+};
 export type TWorkflowTriggerParams<T> = {
     xpertId: string;
     agentKey?: string;
@@ -7,6 +12,14 @@ export type TWorkflowTriggerParams<T> = {
 };
 export interface IWorkflowTriggerStrategy<T> {
     meta: TWorkflowTriggerMeta;
+    /**
+     * Controls how this trigger should be recovered during system bootstrap.
+     *
+     * Default when omitted:
+     * - mode: "replay_publish"
+     * - critical: false
+     */
+    bootstrap?: TWorkflowTriggerBootstrapConfig;
     validate(payload: TWorkflowTriggerParams<T>): Promise<any[]>;
     /**
      * Initialize the trigger when publish xpert workflow