@xpert-ai/plugin-sdk 3.7.2 → 3.8.1

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

@@ -0,0 +1,103 @@
+/**
+ * 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 { EditOperation, EditResult, ExecuteResponse, FileDownloadResponse, FileInfo, FileUploadResponse, GrepMatch, IndentationOptions, MaybePromise, MultiEditResult, ReadMode, 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 {
+    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>;
+    streamExecute(command: string, onLine: (line: string) => void): Promise<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[]>;
+    /**
+     * 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 (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, mode?: ReadMode, indentation?: IndentationOptions): Promise<string>;
+    /**
+     * Structured search results or error string for invalid input.
+     */
+    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/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