@xpert-ai/plugin-sdk 3.7.0 → 3.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.7.0",
+  "version": "3.7.2",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -23,13 +23,16 @@
     "@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,3 +12,4 @@ export * from './lib/core/index';
 export * from './lib/data/index';
 export * from './lib/ai-model/index';
 export * from './lib/agent/index';
+export * from './lib/strategy';

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

@@ -2,3 +2,4 @@ export * from './strategy.decorator';
 export * from './strategy.interface';
 export * from './strategy.registry';
 export * from './types';
+export * from './runtime';

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

@@ -0,0 +1,57 @@
+import type { Runtime as LangGraphRuntime } from "@langchain/langgraph";
+import type { BaseMessage } from "@langchain/core/messages";
+/**
+ * Type for the agent's built-in state properties.
+ */
+export type AgentBuiltInState = {
+    /**
+     * Array of messages representing the conversation history.
+     *
+     * This includes all messages exchanged during the agent's execution:
+     * - Human messages: Input from the user
+     * - AI messages: Responses from the language model
+     * - Tool messages: Results from tool executions
+     * - System messages: System-level instructions or information
+     *
+     * Messages are accumulated throughout the agent's lifecycle and can be
+     * accessed or modified by middleware hooks during execution.
+     */
+    messages: BaseMessage[];
+    /**
+     * Structured response data returned by the agent when a `responseFormat` is configured.
+     *
+     * This property is only populated when you provide a `responseFormat` schema
+     * (as Zod or JSON schema) to the agent configuration. The agent will format
+     * its final output to match the specified schema and store it in this property.
+     *
+     * Note: The type is specified as `Record<string, unknown>` because TypeScript cannot
+     * infer the actual response format type in contexts like middleware, where the agent's
+     * generic type parameters are not accessible. You may need to cast this to your specific
+     * response type when accessing it.
+     */
+    structuredResponse?: Record<string, unknown>;
+};
+/**
+ * Type helper to check if TContext is an optional Zod schema
+ */
+type IsOptionalZodObject<T> = T extends any ? true : false;
+type IsDefaultZodObject<T> = T extends any ? true : false;
+export type WithMaybeContext<TContext> = undefined extends TContext ? {
+    readonly context?: TContext;
+} : IsOptionalZodObject<TContext> extends true ? {
+    readonly context?: TContext;
+} : IsDefaultZodObject<TContext> extends true ? {
+    readonly context?: TContext;
+} : {
+    readonly context: TContext;
+};
+/**
+ * Runtime information available to middleware (readonly).
+ */
+export type Runtime<TContext = unknown> = Partial<Omit<LangGraphRuntime<TContext>, "context" | "configurable">> & WithMaybeContext<TContext> & {
+    configurable?: {
+        thread_id?: string;
+        [key: string]: unknown;
+    };
+};
+export {};

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

@@ -1,2 +1,2 @@
 export declare const AGENT_MIDDLEWARE_STRATEGY = "AGENT_MIDDLEWARE_STRATEGY";
-export declare const AgentMiddlewareStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const AgentMiddlewareStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

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

@@ -1,7 +1,15 @@
 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 { 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 { AgentBuiltInState, Runtime } from './runtime';
+import { Command } from '@langchain/langgraph';
+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)
  */
@@ -94,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.
      */
@@ -104,6 +112,32 @@ 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>;
 }
 /**
  * Handler function type for wrapping model calls.
@@ -112,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.
@@ -126,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.
@@ -244,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/agent/skill/skill-source-provider.decorator.d.ts

@@ -1,2 +1,2 @@
 export declare const SKILL_SOURCE_PROVIDER = "SKILL_SOURCE_PROVIDER";
-export declare const SkillSourceProviderStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const SkillSourceProviderStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

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/core/index.d.ts

@@ -4,3 +4,5 @@ export * from './schema';
 export * from './i18n';
 export * from './utils';
 export * from './context/index';
+export * from './types';
+export * from './strategy-bus';

package/src/lib/core/strategy-bus.d.ts

@@ -0,0 +1,17 @@
+import { StrategyEntry } from './types';
+export type StrategyBusEvent<S = any> = {
+    type: 'UPSERT';
+    strategyType: string;
+    entry: StrategyEntry<S>;
+} | {
+    type: 'REMOVE';
+    strategyType?: string;
+    pluginName: string;
+    orgId: string;
+};
+export declare class StrategyBus {
+    private readonly subject;
+    readonly events$: import("rxjs").Observable<StrategyBusEvent<any>>;
+    upsert<S>(strategyType: string, entry: StrategyEntry<S>): void;
+    remove(orgId: string, pluginName: string): void;
+}

package/src/lib/core/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Who provided this strategy instance:
+ * - "core": main app providers
+ * - "plugin": runtime loaded plugin providers
+ */
+export type StrategySourceKind = 'core' | 'plugin';
+export interface StrategyEntry<S> {
+    instance: S;
+    /**
+     * Unique id for conflict detection & removal.
+     * For core providers you can use wrapper.id or class name.
+     * For plugin providers use `${org}:${pluginId}@${version}:${className}`
+     */
+    sourceId: string;
+    sourceKind: StrategySourceKind;
+}

package/src/lib/core/utils.d.ts

@@ -1,4 +1,5 @@
 import { Logger } from '@nestjs/common';
+import { JSONSchema4 } from 'json-schema';
 export declare function loadYamlFile<T>(filePath: string, logger?: Logger, ignoreError?: boolean, defaultValue?: T): T;
 /**
  * Get the mapping from name to index from a YAML file
@@ -10,3 +11,8 @@ export declare function loadYamlFile<T>(filePath: string, logger?: Logger, ignor
 export declare function getPositionMap(folderPath: string, fileName?: string, logger?: Logger): Record<string, number>;
 export declare function getPositionList(folderPath: string, fileName?: string, logger?: Logger): string[];
 export declare function getErrorMessage(err: any): string;
+export declare class JsonSchemaValidator {
+    private ajv;
+    constructor();
+    parseAndValidate(schemaStr?: string): JSONSchema4 | undefined;
+}

package/src/lib/data/datasource/strategy.decorator.d.ts

@@ -1,2 +1,2 @@
 export declare const DATASOURCE_STRATEGY = "DATASOURCE_STRATEGY";
-export declare const DataSourceStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const DataSourceStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

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

@@ -1,2 +1,2 @@
 export declare const INTEGRATION_STRATEGY = "INTEGRATION_STRATEGY";
-export declare const IntegrationStrategyKey: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const IntegrationStrategyKey: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/rag/image/strategy.decorator.d.ts

@@ -2,4 +2,4 @@ export declare const IMAGE_UNDERSTANDING_STRATEGY = "IMAGE_UNDERSTANDING_STRATEG
 /**
  * Decorator to mark a provider as an Image Understanding Strategy
  */
-export declare const ImageUnderstandingStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const ImageUnderstandingStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/rag/knowledge/knowledge-strategy.decorator.d.ts

@@ -1,2 +1,2 @@
 export declare const KNOWLEDGE_STRATEGY = "KNOWLEDGE_STRATEGY";
-export declare const KnowledgeStrategyKey: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const KnowledgeStrategyKey: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/rag/retriever/strategy.decorator.d.ts

@@ -2,4 +2,4 @@ export declare const RETRIEVER_STRATEGY = "RETRIEVER_STRATEGY";
 /**
  * Decorator to mark a provider as a Retriever Strategy
  */
-export declare const RetrieverStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const RetrieverStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/rag/source/strategy.decorator.d.ts

@@ -2,4 +2,4 @@ export declare const DOCUMENT_SOURCE_STRATEGY = "DOCUMENT_SOURCE_STRATEGY";
 /**
  * Decorator to mark a provider as a Document Source Strategy
  */
-export declare const DocumentSourceStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const DocumentSourceStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/rag/textsplitter/strategy.decorator.d.ts

@@ -1,2 +1,2 @@
 export declare const TEXT_SPLITTER_STRATEGY = "TEXT_SPLITTER_STRATEGY";
-export declare const TextSplitterStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const TextSplitterStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/rag/transformer/strategy.decorator.d.ts

@@ -2,4 +2,4 @@ export declare const DOCUMENT_TRANSFORMER_STRATEGY = "DOCUMENT_TRANSFORMER_STRAT
 /**
  * Decorator to mark a provider as a Document Transformer Strategy
  */
-export declare const DocumentTransformerStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const DocumentTransformerStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/strategy.d.ts

@@ -1,12 +1,38 @@
 import { OnModuleInit } from "@nestjs/common";
 import { DiscoveryService, Reflector } from "@nestjs/core";
+import { StrategyBus } from "./core/strategy-bus";
 export declare class BaseStrategyRegistry<S> implements OnModuleInit {
     protected readonly strategyKey: string;
     protected discoveryService: DiscoveryService;
     protected reflector: Reflector;
-    protected strategies: Map<string, S>;
+    private readonly logger;
+    protected readonly bus: StrategyBus;
+    protected strategies: Map<string, Map<string, S>>;
+    protected pluginStrategies: Map<string, Set<string>>;
     constructor(strategyKey: string, discoveryService: DiscoveryService, reflector: Reflector);
     onModuleInit(): void;
-    get(type: string): S;
-    list(): S[];
+    upsert(instance: any): void;
+    /**
+     * Remove all strategies registered by the given plugin for the given organization.
+     */
+    remove(organizationId: string, pluginName: string): void;
+    /**
+     * Resolve organization id, falling back to request context org or global scope.
+     */
+    protected resolveOrganization(organizationId?: string): string;
+    /**
+     * Get strategy by type from the given organization including global strategies as fallback.
+     *
+     * @param type
+     * @param organizationId
+     * @returns
+     */
+    get(type: string, organizationId?: string): S;
+    /**
+     * List all strategies for the given organization including global strategies, or only global strategies if global org is specified.
+     *
+     * @param organizationId
+     * @returns
+     */
+    list(organizationId?: string): S[];
 }

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

@@ -2,4 +2,4 @@ export declare const TOOLSET_STRATEGY = "TOOLSET_STRATEGY";
 /**
  * Decorator to mark a provider as a Toolset Strategy
  */
-export declare const ToolsetStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const ToolsetStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/types.d.ts

@@ -1,6 +1,10 @@
 import { PluginMeta } from '@metad/contracts';
 import type { DynamicModule, INestApplicationContext } from '@nestjs/common';
 import type { ZodSchema } from 'zod';
+export declare const ORGANIZATION_METADATA_KEY = "xpert:organizationId";
+export declare const PLUGIN_METADATA_KEY = "xpert:pluginName";
+export declare const GLOBAL_ORGANIZATION_SCOPE = "global";
+export declare const STRATEGY_META_KEY = "XPERT_STRATEGY_META_KEY";
 export interface PluginLifecycle {
     /** Called after module registration but before application startup */
     onInit?(ctx: PluginContext): Promise<void> | void;

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

@@ -1,2 +1,2 @@
 export declare const VECTOR_STORE_STRATEGY = "VECTOR_STORE_STRATEGY";
-export declare const VectorStoreStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const VectorStoreStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

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

@@ -2,4 +2,4 @@ export declare const WORKFLOW_NODE_STRATEGY = "WORKFLOW_NODE_STRATEGY";
 /**
  * Decorator to mark a provider as a Workflow Node Strategy
  */
-export declare const WorkflowNodeStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const WorkflowNodeStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

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

@@ -1,2 +1,2 @@
 export declare const WORKFLOW_TRIGGER_STRATEGY = "WORKFLOW_TRIGGER_STRATEGY";
-export declare const WorkflowTriggerStrategy: (provider: string) => import("@nestjs/common").CustomDecorator<string>;
+export declare const WorkflowTriggerStrategy: (provider: string) => <TFunction extends Function, Y>(target: object | TFunction, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;