@xpert-ai/plugin-sdk 3.7.1 → 3.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.7.1",
+  "version": "3.8.0",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -20,16 +20,20 @@
   "peerDependencies": {
     "@langchain/core": "*",
     "@metad/contracts": "*",
+    "@metad/ocap-core": "*",
     "@nestjs/common": "*",
     "@nestjs/core": "*",
     "@nestjs/cqrs": "*",
+    "ajv": "*",
     "lodash-es": "*",
     "i18next-fs-backend": "*",
     "i18next": "*",
+    "json-schema": "*",
     "jsonwebtoken": "*",
     "fs": "*",
     "path": "*",
     "passport-jwt": "*",
+    "rxjs": "*",
     "stream": "*",
     "yaml": "*",
     "zod": "*"

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

@@ -1,14 +1,21 @@
 import { LanguageModelLike } from '@langchain/core/language_models/base';
 import { AIMessage, BaseMessage, SystemMessage } from '@langchain/core/messages';
-import { DynamicStructuredTool } from '@langchain/core/tools';
-import { InteropZodObject } from '@langchain/core/utils/types';
-import { Runtime } from './runtime';
+import { DynamicStructuredTool, DynamicTool, StructuredToolInterface } from '@langchain/core/tools';
+import type { ToolCall, ToolMessage } from "@langchain/core/messages/tool";
+import { InferInteropZodOutput, InteropZodObject } from '@langchain/core/utils/types';
+import { RunnableToolLike } from '@langchain/core/runnables';
+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;
+type NormalizeContextSchema<TContextSchema extends InteropZodObject | undefined = undefined> = TContextSchema extends InteropZodObject ? InferInteropZodOutput<TContextSchema> : never;
 /**
  * jump targets (user facing)
  */
 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.
  */
@@ -95,7 +102,7 @@ export type AfterAgentHook<TSchema extends InteropZodObject | undefined = undefi
  * @template TState - The agent's state type, must extend Record<string, unknown>. Defaults to Record<string, unknown>.
  * @template TContext - The runtime context type for accessing metadata and control flow. Defaults to unknown.
  */
-export interface ModelRequest<TState = any, TContext = unknown> {
+export interface ModelRequest<TState extends Record<string, unknown> = Record<string, unknown>, TContext = unknown> {
     /**
      * The model to use for this step.
      */
@@ -105,6 +112,31 @@ export interface ModelRequest<TState = any, TContext = unknown> {
      */
     messages: BaseMessage[];
     systemMessage?: SystemMessage;
+    /**
+     * Tool choice configuration (model-specific format).
+     * Can be one of:
+     * - `"auto"`: means the model can pick between generating a message or calling one or more tools.
+     * - `"none"`: means the model will not call any tool and instead generates a message.
+     * - `"required"`: means the model must call one or more tools.
+     * - `{ type: "function", function: { name: string } }`: The model will use the specified function.
+     */
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    /**
+     * The tools to make available for this step.
+     */
+    tools: (ServerTool | ClientTool)[];
+    /**
+     * The current agent state (includes both middleware state and built-in state).
+     */
+    state: TState & AgentBuiltInState;
+    /**
+     * The runtime context containing metadata, signal, writer, interrupt, etc.
+     */
     runtime: Runtime<TContext>;
 }
 /**
@@ -114,7 +146,7 @@ export interface ModelRequest<TState = any, TContext = unknown> {
  * @param request - The model request containing model, messages, systemPrompt, tools, state, and runtime
  * @returns The AI message response from the model
  */
-export type WrapModelCallHandler<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<TSchema, TContext>) => PromiseOrValue<AIMessage>;
+export type WrapModelCallHandler<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema>, TContext>) => PromiseOrValue<AIMessage>;
 /**
  * Wrapper function type for the wrapModelCall hook.
  * Allows middleware to intercept and modify model execution.
@@ -128,7 +160,40 @@ export type WrapModelCallHandler<TSchema extends InteropZodObject | undefined =
  * @param handler - The function that invokes the model. Call this with a ModelRequest to get the response
  * @returns The AI message response from the model (or a modified version)
  */
-export type WrapModelCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<TSchema, TContext>, handler: WrapModelCallHandler<TSchema, TContext>) => PromiseOrValue<AIMessage>;
+export type WrapModelCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ModelRequest<NormalizedSchemaInput<TSchema>, TContext>, handler: WrapModelCallHandler<TSchema, TContext>) => PromiseOrValue<AIMessage>;
+/**
+ * Represents a tool call request for the wrapToolCall hook.
+ * Contains the tool call information along with the agent's current state and runtime.
+ */
+export interface ToolCallRequest<TState extends Record<string, unknown> = Record<string, unknown>, TContext = unknown> {
+    /**
+     * The tool call to be executed
+     */
+    toolCall: ToolCall;
+    /**
+     * The BaseTool instance being invoked.
+     * Provides access to tool metadata like name, description, schema, etc.
+     */
+    tool: ClientTool | ServerTool;
+    /**
+     * The current agent state (includes both middleware state and built-in state).
+     */
+    state: TState & AgentBuiltInState;
+    /**
+     * The runtime context containing metadata, signal, writer, interrupt, etc.
+     */
+    runtime: Runtime<TContext>;
+}
+/**
+ * Handler function type for wrapping tool calls.
+ * Takes a tool call request and returns the tool result or a command.
+ */
+export type ToolCallHandler<TSchema extends Record<string, unknown> = AgentBuiltInState, TContext = unknown> = (request: ToolCallRequest<TSchema, TContext>) => PromiseOrValue<ToolMessage | Command>;
+/**
+ * Wrapper function type for the wrapToolCall hook.
+ * Allows middleware to intercept and modify tool execution.
+ */
+export type WrapToolCallHook<TSchema extends InteropZodObject | undefined = undefined, TContext = unknown> = (request: ToolCallRequest<NormalizedSchemaInput<TSchema>, TContext>, handler: ToolCallHandler<NormalizedSchemaInput<TSchema>, TContext>) => PromiseOrValue<ToolMessage | Command>;
 export interface AgentMiddleware<TSchema extends InteropZodObject | undefined = any, TContextSchema extends InteropZodObject | undefined = any, TFullContext = any> {
     /**
      * The name of the middleware.
@@ -246,6 +311,6 @@ export interface AgentMiddleware<TSchema extends InteropZodObject | undefined =
      * }
      * ```
      */
-    wrapToolCall?: (request: ModelRequest<TSchema, TFullContext>, handler: WrapModelCallHandler<TSchema, TFullContext>) => PromiseOrValue<AIMessage>;
+    wrapToolCall?: WrapToolCallHook<TSchema, NormalizeContextSchema<TContextSchema>>;
 }
 export {};

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

@@ -1,8 +1,9 @@
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { AIModelEntity, AiModelTypeEnum, ICopilotModel, ParameterRule, PriceInfo, PriceType } from '@metad/contracts';
 import { Logger } from '@nestjs/common';
-import { IAIModel, TChatModelOptions } from './types/';
 import { ModelProvider } from './abstract-provider';
+import { IAIModel, TChatModelOptions } from './types/model';
+import { ModelProfile } from './types/profile';
 export declare abstract class AIModel implements IAIModel {
     protected readonly modelProvider: ModelProvider;
     modelType: AiModelTypeEnum;
@@ -30,4 +31,5 @@ export declare abstract class AIModel implements IAIModel {
     private sortModelSchemas;
     protected _commonParameterRules(model: string): ParameterRule[];
     getParameterRules(model: string, credentials: Record<string, string>): ParameterRule[];
+    getModelProfile(model: string, credentials: unknown): ModelProfile;
 }

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>;