@xpert-ai/plugin-sdk 3.8.1 → 3.8.4

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

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

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/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,9 +340,11 @@ 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;
+    /** 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

@@ -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.
  *
@@ -21,12 +22,18 @@ 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.
      */
-    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/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;

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;