@xpert-ai/plugin-sdk 3.7.2 → 3.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.7.2",
+  "version": "3.8.0",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
   "peerDependencies": {
     "@langchain/core": "*",
     "@metad/contracts": "*",
+    "@metad/ocap-core": "*",
     "@nestjs/common": "*",
     "@nestjs/core": "*",
     "@nestjs/cqrs": "*",

package/src/index.d.ts

@@ -12,4 +12,6 @@ export * from './lib/core/index';
 export * from './lib/data/index';
 export * from './lib/ai-model/index';
 export * from './lib/agent/index';
+export * from './lib/channel/index';
 export * from './lib/strategy';
+export * from './lib/sandbox/index';

package/src/lib/agent/handoff/agent-chat.contract.d.ts

@@ -0,0 +1,20 @@
+import { TChatOptions, TChatRequest } from '@metad/contracts';
+export declare const AGENT_CHAT_DISPATCH_MESSAGE_TYPE: import("./message-type").StructuredHandoffMessageType;
+export interface AgentChatCallbackTarget {
+    messageType: string;
+    headers?: Record<string, string>;
+    context?: Record<string, unknown>;
+}
+export interface AgentChatDispatchPayload extends Record<string, unknown> {
+    request: TChatRequest;
+    options: TChatOptions;
+    callback: AgentChatCallbackTarget;
+}
+export interface AgentChatCallbackEnvelopePayload extends Record<string, unknown> {
+    kind: 'stream' | 'complete' | 'error';
+    sourceMessageId: string;
+    sequence: number;
+    event?: unknown;
+    error?: string;
+    context?: Record<string, unknown>;
+}

package/src/lib/agent/handoff/handoff-processor.decorator.d.ts

@@ -0,0 +1,11 @@
+import { HandoffProcessorMetadata } from './handoff.interface';
+/**
+ * Handoff Processor meta key。
+ */
+export declare const HANDOFF_PROCESSOR_STRATEGY = "HANDOFF_PROCESSOR_STRATEGY";
+/**
+ * Declare on a provider:
+ * 1) Which message types it handles
+ * 2) Default execution policy (lane/timeout)
+ */
+export declare function HandoffProcessorStrategy(provider: string, metadata: HandoffProcessorMetadata): <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/agent/handoff/handoff-processor.registry.d.ts

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

package/src/lib/agent/handoff/handoff.interface.d.ts

@@ -0,0 +1,17 @@
+import { HandoffMessage, ProcessContext, ProcessorPolicy, ProcessResult } from './types';
+/**
+ * Handoff Processor interface.
+ * - Processor focus only on message processing logic; scheduling, retries, concurrency, and cancellation are handled uniformly by Dispatcher + Queue.
+ */
+export interface IHandoffProcessor<TPayload extends Record<string, unknown> = Record<string, unknown>> {
+    process(message: HandoffMessage<TPayload>, ctx: ProcessContext): Promise<ProcessResult>;
+}
+export interface HandoffProcessorMetadata {
+    types: string[];
+    policy: ProcessorPolicy;
+}
+export interface ResolvedHandoffProcessor {
+    type: string;
+    processor: IHandoffProcessor;
+    metadata: HandoffProcessorMetadata;
+}

package/src/lib/agent/handoff/index.d.ts

@@ -0,0 +1,6 @@
+export * from './message-type';
+export * from './agent-chat.contract';
+export * from './handoff.interface';
+export * from './handoff-processor.decorator';
+export * from './handoff-processor.registry';
+export * from './types';

package/src/lib/agent/handoff/message-type.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured message types (suggested format):
+ * - channel.{provider}.{action}.v{number}
+ * - agent.{action}.v{number}
+ * - system.{action}.v{number}
+ * - plugin.{domain}.{action}.v{number}
+ *
+ * Note: At runtime, any string type is still allowed, facilitating dynamic extension by plugins.
+ */
+export type StructuredHandoffMessageType = `channel.${string}.${string}.v${number}` | `agent.${string}.v${number}` | `system.${string}.v${number}` | `plugin.${string}.${string}.v${number}`;
+/**
+ * Unified construction of channel message types to avoid manual string errors.
+ * Example: channel.lark.inbound.v1
+ */
+export declare function defineChannelMessageType(provider: string, action: string, version: number): StructuredHandoffMessageType;
+/**
+ * Unified construction of agent message types.
+ * Example: agent.handoff.v1
+ */
+export declare function defineAgentMessageType(action: string, version: number): StructuredHandoffMessageType;
+/**
+ * Check if a type conforms to the structured naming convention (format only, no semantic validation).
+ */
+export declare function isStructuredMessageType(type: string): boolean;

package/src/lib/agent/handoff/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Handoff execution types.
+ *
+ * Note:
+ * - Two-gate lane/session permit logic has been removed.
+ * - Lane is now an execution tag for observability and soft policy only.
+ */
+export type LaneName = 'main' | 'subagent' | 'cron' | 'nested';
+export type RunSource = 'chat' | 'xpert' | 'lark' | 'analytics' | 'api';
+export interface RunMetadata {
+    runId: string;
+    sessionKey: string;
+    lane: LaneName;
+    source: RunSource;
+    startedAt: number;
+    expiresAt?: number;
+    controller: AbortController;
+    conversationId?: string;
+    executionId?: string;
+    integrationId?: string;
+    userId?: string;
+    tenantId?: string;
+}
+export interface LaneStats {
+    lane: string;
+    active: number;
+    queued: number;
+    maxConcurrent: number;
+    draining: boolean;
+}
+export interface RunOptions {
+    runId: string;
+    sessionKey?: string;
+    globalLane?: LaneName;
+    abortController: AbortController;
+    source?: RunSource;
+    conversationId?: string;
+    executionId?: string;
+    integrationId?: string;
+    userId?: string;
+    tenantId?: string;
+    timeoutMs?: number;
+}
+export interface ExecutionConfig {
+    lanes: Record<LaneName, number>;
+    runTtlMs: number;
+}
+export declare const DEFAULT_EXECUTION_CONFIG: ExecutionConfig;
+/**
+ * Handoff message envelope (v1).
+ * Using `type` with a string allows plugins to dynamically expand at runtime without needing to modify the core type definition.
+ */
+export interface HandoffMessage<TPayload extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    /**
+     * Message type, used for processor resolution.
+     */
+    type: string;
+    version: number;
+    tenantId: string;
+    sessionKey: string;
+    businessKey: string;
+    attempt: number;
+    maxAttempts: number;
+    enqueuedAt: number;
+    traceId: string;
+    parentMessageId?: string;
+    payload: TPayload;
+    headers?: HandoffMessageHeaders;
+}
+export interface HandoffMessageHeaders extends Record<string, string> {
+    organizationId?: string;
+    userId?: string;
+    language?: string;
+    threadId?: string;
+    conversationId?: string;
+    sourceAgent?: string;
+    targetAgent?: string;
+    source?: RunSource;
+    requestedLane?: LaneName;
+    integrationId?: string;
+}
+/**
+ * Processor execution policy: declared by the Processor, executed uniformly by the Dispatcher.
+ */
+export interface ProcessorPolicy {
+    lane: LaneName;
+    timeoutMs?: number;
+}
+export interface ProcessContext {
+    runId: string;
+    traceId: string;
+    abortSignal: AbortSignal;
+    /**
+     * Optional local-process event channel for queue waiters (e.g. SSE connection awaiting this message).
+     * This is intentionally process-local and best-effort.
+     */
+    emit?: (event: unknown) => void;
+}
+export type ProcessResult = {
+    status: 'ok';
+    outbound?: HandoffMessage[];
+} | {
+    status: 'retry';
+    delayMs: number;
+    reason?: string;
+} | {
+    status: 'dead';
+    reason: string;
+};

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

@@ -1 +1,2 @@
 export * from './middleware';
+export * from './handoff';

package/src/lib/agent/middleware/runtime.d.ts

@@ -1,5 +1,6 @@
 import type { Runtime as LangGraphRuntime } from "@langchain/langgraph";
 import type { BaseMessage } from "@langchain/core/messages";
+import { TSandboxConfigurable } from "@metad/contracts";
 /**
  * Type for the agent's built-in state properties.
  */
@@ -51,6 +52,7 @@ export type WithMaybeContext<TContext> = undefined extends TContext ? {
 export type Runtime<TContext = unknown> = Partial<Omit<LangGraphRuntime<TContext>, "context" | "configurable">> & WithMaybeContext<TContext> & {
     configurable?: {
         thread_id?: string;
+        sandbox?: TSandboxConfigurable | null;
         [key: string]: unknown;
     };
 };

package/src/lib/agent/middleware/strategy.interface.d.ts

@@ -1,5 +1,8 @@
 import { IWFNMiddleware, TAgentMiddlewareMeta } from '@metad/contracts';
-import { AgentMiddleware, PromiseOrValue } from './types';
+import { StructuredToolInterface } from "@langchain/core/tools";
+import { RunnableToolLike } from '@langchain/core/runnables';
+import { AgentMiddleware } from './types';
+import { PromiseOrValue } from '../../types';
 export interface IAgentMiddlewareContext {
     tenantId: string;
     userId: string;
@@ -9,6 +12,7 @@ export interface IAgentMiddlewareContext {
     xpertId?: string;
     agentKey?: string;
     node: IWFNMiddleware;
+    tools: Map<string, StructuredToolInterface | RunnableToolLike>;
 }
 export interface IAgentMiddlewareStrategy<T = unknown> {
     meta: TAgentMiddlewareMeta;

package/src/lib/agent/middleware/types.d.ts

@@ -4,8 +4,9 @@ import { DynamicStructuredTool, DynamicTool, StructuredToolInterface } from '@la
 import type { ToolCall, ToolMessage } from "@langchain/core/messages/tool";
 import { InferInteropZodOutput, InteropZodObject } from '@langchain/core/utils/types';
 import { RunnableToolLike } from '@langchain/core/runnables';
-import { AgentBuiltInState, Runtime } from './runtime';
 import { Command } from '@langchain/langgraph';
+import { AgentBuiltInState, Runtime } from './runtime';
+import { PromiseOrValue } from '../../types';
 export type ServerTool = Record<string, unknown>;
 export type ClientTool = StructuredToolInterface | DynamicTool | RunnableToolLike;
 export type NormalizedSchemaInput<TSchema extends InteropZodObject | undefined | never = any> = [TSchema] extends [never] ? AgentBuiltInState : TSchema extends InteropZodObject ? InferInteropZodOutput<TSchema> & AgentBuiltInState : TSchema extends Record<string, unknown> ? TSchema & AgentBuiltInState : AgentBuiltInState;
@@ -15,7 +16,6 @@ type NormalizeContextSchema<TContextSchema extends InteropZodObject | undefined
  */
 export declare const JUMP_TO_TARGETS: readonly ["model", "tools", "end"];
 export type JumpToTarget = (typeof JUMP_TO_TARGETS)[number];
-export type PromiseOrValue<T> = T | Promise<T>;
 /**
  * Result type for middleware functions.
  */

package/src/lib/ai-model/utils/index.d.ts

@@ -1 +1,2 @@
 export * from './tokenizer';
+export * from './limits';

package/src/lib/ai-model/utils/limits.d.ts

@@ -0,0 +1,4 @@
+import { BaseLanguageModel } from "@langchain/core/language_models/base";
+import { ICopilotModel } from "@metad/contracts";
+export declare function getModelContextSize(input: BaseLanguageModel | ICopilotModel): number | undefined;
+export declare function normalizeContextSize(value: unknown): number | undefined;

package/src/lib/channel/cancel-conversation.command.d.ts

@@ -0,0 +1,14 @@
+import { ICommand } from '@nestjs/cqrs';
+export declare class CancelConversationCommand implements ICommand {
+    readonly input: {
+        conversationId?: string;
+        threadId?: string;
+        executionId?: string;
+    };
+    static readonly type = "[Chat Conversation] Cancel";
+    constructor(input: {
+        conversationId?: string;
+        threadId?: string;
+        executionId?: string;
+    });
+}

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

@@ -0,0 +1,4 @@
+export * from './strategy.interface';
+export * from './strategy.registry';
+export * from './strategy.decorator';
+export * from './cancel-conversation.command';

package/src/lib/channel/strategy.decorator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Metadata key for chat channel
+ */
+export declare const CHAT_CHANNEL = "CHAT_CHANNEL";
+/**
+ * Decorator for chat channel implementations
+ *
+ * Use this decorator to register a chat channel implementation.
+ * The decorated class will be automatically discovered and registered
+ * to ChatChannelRegistry on module initialization.
+ *
+ * @param type - The channel type identifier (e.g., 'lark', 'wecom', 'dingtalk')
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * @ChatChannel('lark')
+ * export class LarkChatChannel implements IChatChannel {
+ *   // Implementation
+ * }
+ * ```
+ */
+export declare const ChatChannel: (type: string) => import("@nestjs/common").CustomDecorator<string>;

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

@@ -0,0 +1,345 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IIntegration } from '@metad/contracts';
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Channel metadata
+ */
+export type TChatChannelMeta = {
+    /**
+     * Channel type identifier
+     */
+    type: string;
+    /**
+     * Display name
+     */
+    label: string;
+    /**
+     * Description
+     */
+    description?: string;
+    /**
+     * Icon
+     */
+    icon?: string;
+    /**
+     * JSON Schema for integration configuration
+     */
+    configSchema?: Record<string, any>;
+};
+/**
+ * Channel capabilities declaration
+ */
+export type TChatChannelCapabilities = {
+    /** Supports Markdown messages */
+    markdown: boolean;
+    /** Supports interactive cards */
+    card: boolean;
+    /** Supports card button interactions */
+    cardAction: boolean;
+    /** Supports editing/updating messages */
+    updateMessage: boolean;
+    /** Supports @mentions */
+    mention: boolean;
+    /** Supports group chat */
+    group: boolean;
+    /** Supports message threads/replies */
+    thread?: boolean;
+    /** Supports media messages (images, files) */
+    media?: boolean;
+    /** Maximum characters per message (auto-chunked if exceeded), e.g., Telegram 4096, Discord 2000 */
+    textChunkLimit?: number;
+    /** Supports streaming message updates (typewriter effect) */
+    streamingUpdate?: boolean;
+};
+/**
+ * Inbound message - unified format from different platforms
+ */
+export type TChatInboundMessage = {
+    /** Platform message ID */
+    messageId: string;
+    /** Chat ID */
+    chatId: string;
+    /** Chat type: private, group, channel, thread */
+    chatType: 'private' | 'group' | 'channel' | 'thread';
+    /** Sender ID (platform user ID) */
+    senderId: string;
+    /** Sender name */
+    senderName?: string;
+    /** Message content (text) */
+    content: string;
+    /** Content type */
+    contentType: 'text' | 'image' | 'file' | 'card_action' | 'voice';
+    /** List of mentioned users */
+    mentions?: Array<{
+        id: string;
+        name?: string;
+    }>;
+    /** Reply-to message ID */
+    replyToMessageId?: string;
+    /** Thread ID (for threaded conversations) */
+    threadId?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Platform raw event data */
+    raw: any;
+};
+/**
+ * Card action event - triggered when user clicks card button
+ */
+export type TChatCardAction<V = unknown> = {
+    /** Action type/tag */
+    type: string;
+    /** Action value */
+    value: V;
+    /** Message ID the card belongs to */
+    messageId: string;
+    /** Chat ID */
+    chatId: string;
+    /** User ID who triggered the action */
+    userId: string;
+    /** Raw event data */
+    raw: any;
+};
+/**
+ * Chat context - used for sending messages
+ */
+export type TChatContext = {
+    /** Integration configuration */
+    integration: IIntegration;
+    /** Chat ID */
+    chatId: string;
+    /** Target user ID (for private chat) */
+    userId?: string;
+    /** Thread ID (for thread replies) */
+    threadId?: string;
+    /** Reply-to message ID */
+    replyToMessageId?: string;
+};
+/**
+ * Send result
+ */
+export type TChatSendResult = {
+    /** Success status */
+    success: boolean;
+    /** Message ID */
+    messageId?: string;
+    /** Error message */
+    error?: string;
+};
+/**
+ * Event handling context
+ */
+export type TChatEventContext<TConfig = any> = {
+    /** Integration configuration */
+    integration: IIntegration<TConfig>;
+    /** Tenant ID */
+    tenantId: string;
+    /** Organization ID */
+    organizationId: string;
+};
+/**
+ * Event handling callbacks
+ */
+export type TChatEventHandlers = {
+    /** Called when message is received */
+    onMessage?: (message: TChatInboundMessage, ctx: TChatEventContext) => Promise<void>;
+    /** Called on card interaction */
+    onCardAction?: (action: TChatCardAction, ctx: TChatEventContext) => Promise<void>;
+    /** Called when @mentioned in group chat */
+    onMention?: (message: TChatInboundMessage, ctx: TChatEventContext) => Promise<void>;
+};
+/**
+ * Chat channel interface
+ *
+ * For bidirectional messaging platforms (Lark, WeCom, DingTalk, Slack, etc.)
+ * Supports: receive message → invoke Xpert → reply message
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * @ChatChannel('lark')
+ * export class LarkChatChannel implements IChatChannel {
+ *   meta = { type: 'lark', label: 'Lark', ... }
+ *
+ *   createEventHandler(ctx, handlers) {
+ *     // Return Express middleware for handling Webhook
+ *   }
+ *
+ *   async sendText(ctx, content) {
+ *     // Send text message via Lark API
+ *   }
+ * }
+ * ```
+ */
+export interface IChatChannel<TConfig = any, TEvent = any> {
+    /**
+     * Channel metadata
+     */
+    meta: TChatChannelMeta;
+    /**
+     * Channel capabilities declaration
+     */
+    capabilities: TChatChannelCapabilities;
+    /**
+     * Create Webhook/event handler
+     *
+     * Returns Express middleware for handling inbound Webhooks.
+     * The middleware should:
+     * 1. Verify request (signature, token)
+     * 2. Parse event
+     * 3. Call appropriate handler callbacks (onMessage, onCardAction, etc.)
+     *
+     * @param ctx - Event context containing integration configuration
+     * @param handlers - Callback functions for different event types
+     * @returns Express middleware
+     */
+    createEventHandler(ctx: TChatEventContext<TConfig>, handlers: TChatEventHandlers): (req: Request, res: Response, next?: NextFunction) => Promise<void>;
+    /**
+     * Parse inbound event to unified message format
+     *
+     * @param event - Platform raw event
+     * @param ctx - Event context
+     * @returns Parsed message, or null if not a message event
+     */
+    parseInboundMessage?(event: TEvent, ctx: TChatEventContext<TConfig>): TChatInboundMessage | null;
+    /**
+     * Parse card action event
+     *
+     * @param event - Platform raw event
+     * @param ctx - Event context
+     * @returns Parsed card action, or null if not a card action event
+     */
+    parseCardAction?(event: TEvent, ctx: TChatEventContext<TConfig>): TChatCardAction | null;
+    /**
+     * Check if bot is @mentioned in message
+     *
+     * @param message - Inbound message
+     * @param botId - Bot's user ID on the platform
+     * @returns True if bot is mentioned
+     */
+    isBotMentioned?(message: TChatInboundMessage, botId: string): boolean;
+    /**
+     * Send text message
+     *
+     * @param ctx - Chat context
+     * @param content - Text content
+     * @returns Send result
+     */
+    sendText(ctx: TChatContext, content: string): Promise<TChatSendResult>;
+    /**
+     * Send Markdown message
+     *
+     * @param ctx - Chat context
+     * @param content - Markdown content
+     * @returns Send result
+     */
+    sendMarkdown?(ctx: TChatContext, content: string): Promise<TChatSendResult>;
+    /**
+     * Send interactive card
+     *
+     * @param ctx - Chat context
+     * @param card - Card content (platform-specific format)
+     * @returns Send result
+     */
+    sendCard?(ctx: TChatContext, card: any): Promise<TChatSendResult>;
+    /**
+     * Send media message (image, file)
+     *
+     * @param ctx - Chat context
+     * @param media - Media info
+     * @returns Send result
+     */
+    sendMedia?(ctx: TChatContext, media: {
+        /** Media type */
+        type: 'image' | 'file' | 'audio' | 'video';
+        /** Media URL */
+        url?: string;
+        /** Media content (Buffer) */
+        content?: Buffer;
+        /** Filename */
+        filename?: string;
+    }): Promise<TChatSendResult>;
+    /**
+     * Update/edit sent message
+     *
+     * @param ctx - Chat context
+     * @param messageId - Message ID to update
+     * @param content - New content
+     * @returns Send result
+     */
+    updateMessage?(ctx: TChatContext, messageId: string, content: string | any): Promise<TChatSendResult>;
+    /**
+     * Get bot information
+     *
+     * @param integration - Integration configuration
+     * @returns Bot info (ID, name, avatar, etc.)
+     */
+    getBotInfo?(integration: IIntegration<TConfig>): Promise<{
+        /** Bot ID */
+        id: string;
+        /** Bot name */
+        name?: string;
+        /** Bot avatar URL */
+        avatar?: string;
+    }>;
+    /**
+     * Validate integration configuration
+     *
+     * @param config - Configuration to validate
+     * @returns Validation result
+     */
+    validateConfig?(config: TConfig): Promise<{
+        /** Is valid */
+        valid: boolean;
+        /** Error list */
+        errors?: string[];
+    }>;
+    /**
+     * Test connection
+     *
+     * @param integration - Integration to test
+     * @returns Test result
+     */
+    testConnection?(integration: IIntegration<TConfig>): Promise<{
+        /** Success status */
+        success: boolean;
+        /** Message */
+        message?: string;
+    }>;
+    /**
+     * Get channel runtime status (for monitoring and operations)
+     *
+     * @param integration - Integration configuration
+     * @returns Channel status
+     */
+    getStatus?(integration: IIntegration<TConfig>): Promise<TChatChannelStatus>;
+}
+/**
+ * Channel runtime status (for monitoring)
+ */
+export type TChatChannelStatus = {
+    /** Is connected/running */
+    connected: boolean;
+    /** Last activity timestamp */
+    lastActivityAt?: number;
+    /** Last inbound message timestamp */
+    lastInboundAt?: number;
+    /** Last outbound message timestamp */
+    lastOutboundAt?: number;
+    /** Last error message */
+    error?: string;
+};
+/**
+ * Common platform message length limits
+ */
+export declare const CHAT_CHANNEL_TEXT_LIMITS: Record<string, number>;
+/**
+ * Chunk long text by specified length
+ *
+ * @param text - Text to chunk
+ * @param limit - Maximum characters per chunk
+ * @param mode - Chunking mode: 'text' splits by character, 'markdown' tries to preserve paragraphs
+ * @returns Array of chunked text
+ */
+export declare function chunkText(text: string, limit: number, mode?: 'text' | 'markdown'): string[];