@xpert-ai/plugin-sdk 3.18.0 → 3.18.2

package/index.cjs.js

@@ -36,7 +36,7 @@ var jsTiktoken = require('js-tiktoken');
 var base$1 = require('@langchain/core/language_models/base');
 var connector = require('./connector.cjs.js');
 var collaborationClient = require('./collaboration-client.cjs.js');
-require('@langchain/core/tools');
+var tools = require('@langchain/core/tools');
 require('zod/v3');
 
 function _interopNamespaceDefault(e) {
@@ -521,12 +521,14 @@ exports.StrategyBus = class StrategyBus {
             entry
         });
     }
-    remove(orgId, pluginName) {
-        this.subject.next({
+    remove(orgId, pluginName, cause) {
+        this.subject.next(_extends._extends({
             type: 'REMOVE',
             orgId,
             pluginName
-        });
+        }, cause ? {
+            cause
+        } : {}));
     }
     constructor(){
         this.subject = new rxjs.Subject();
@@ -561,22 +563,39 @@ class BaseStrategyRegistry {
         const type = this.reflector.get(this.strategyKey, target);
         if (type) {
             const source = this.getSource(instance);
-            const pluginName = source.kind === 'plugin' ? source.pluginName : undefined;
-            const organizationId = source.scopeKey;
-            var _this_strategies_get;
-            const orgMap = (_this_strategies_get = this.strategies.get(organizationId)) != null ? _this_strategies_get : new Map();
-            orgMap.set(type, instance);
-            this.strategies.set(organizationId, orgMap);
-            this.logger.debug(`Registered strategy of type ${type} for scope ${organizationId} from plugin ${pluginName}`);
-            if (pluginName) {
-                var _this_pluginStrategies_get;
-                const pluginStrategies = (_this_pluginStrategies_get = this.pluginStrategies.get(pluginName)) != null ? _this_pluginStrategies_get : new Set();
-                pluginStrategies.add(type);
-                this.pluginStrategies.set(pluginName, pluginStrategies);
-            }
+            this.store(type, instance, source, false);
         }
     }
+    /** Registers a host-generated adapter without mutating shared class metadata. */ register(type, instance, source) {
+        if ((typeof instance !== 'object' || instance === null) && typeof instance !== 'function') {
+            throw new Error(`Cannot register non-object strategy '${type}'.`);
+        }
+        this.assertCanRegister(type, instance, source);
+        this.explicitSources.set(instance, source);
+        return this.store(type, instance, source, false);
+    }
+    /** Preflights adapter batches so a provider is expanded atomically across registries. */ assertCanRegister(type, instance, source) {
+        var _this_strategies_get;
+        const existing = (_this_strategies_get = this.strategies.get(source.scopeKey)) == null ? void 0 : _this_strategies_get.get(type);
+        if (!existing || existing === instance) return;
+        const existingSource = this.getSource(existing);
+        const samePlugin = existingSource.kind === 'plugin' && source.kind === 'plugin' && existingSource.pluginName === source.pluginName;
+        if (!samePlugin) {
+            throw new Error(`Strategy '${type}' is already registered for scope '${source.scopeKey}'.`);
+        }
+    }
+    /** Removes one exact programmatic registration without affecting fallback scopes. */ unregister(type, source, expected) {
+        const orgMap = this.strategies.get(source.scopeKey);
+        const current = orgMap == null ? void 0 : orgMap.get(type);
+        if (expected !== undefined && current !== expected) return false;
+        var _orgMap_delete;
+        return (_orgMap_delete = orgMap == null ? void 0 : orgMap.delete(type)) != null ? _orgMap_delete : false;
+    }
     /** Returns the explicit registry provenance attached by the plugin loader. */ getSource(instance) {
+        if (typeof instance === 'object' && instance !== null || typeof instance === 'function') {
+            const explicit = this.explicitSources.get(instance);
+            if (explicit) return explicit;
+        }
         const target = resolveStrategyMetadataTarget(instance);
         if (!target) {
             return {
@@ -680,11 +699,68 @@ class BaseStrategyRegistry {
         }
         return Array.from(effective.values());
     }
+    listRegistrations(organizationId) {
+        organizationId != null ? organizationId : organizationId = RequestContext.getOrganizationId();
+        const effective = new Map();
+        for (const scopeKey of this.resolveStrategyScopeKeys(organizationId)){
+            var _this_strategies_get;
+            var _this_strategies_get_entries;
+            for (const [type, strategy] of (_this_strategies_get_entries = (_this_strategies_get = this.strategies.get(scopeKey)) == null ? void 0 : _this_strategies_get.entries()) != null ? _this_strategies_get_entries : []){
+                if (!effective.has(type)) effective.set(type, strategy);
+            }
+        }
+        return Array.from(effective, ([type, strategy])=>({
+                type,
+                strategy,
+                source: this.getSource(strategy)
+            }));
+    }
+    /** Returns every direct registration without applying request-scope fallback rules. */ listAllRegistrations() {
+        const registrations = [];
+        for (const [scopeKey, strategies] of this.strategies){
+            for (const [type, strategy] of strategies){
+                const source = this.getSource(strategy);
+                registrations.push({
+                    type,
+                    strategy,
+                    source: source.scopeKey === scopeKey ? source : _extends._extends({}, source, {
+                        scopeKey
+                    })
+                });
+            }
+        }
+        return registrations;
+    }
+    store(type, instance, source, rejectCrossPluginConflict) {
+        const pluginName = source.kind === 'plugin' ? source.pluginName : undefined;
+        const organizationId = source.scopeKey;
+        var _this_strategies_get;
+        const orgMap = (_this_strategies_get = this.strategies.get(organizationId)) != null ? _this_strategies_get : new Map();
+        const existing = orgMap.get(type);
+        if (rejectCrossPluginConflict && existing && existing !== instance) {
+            const existingSource = this.getSource(existing);
+            const samePlugin = existingSource.kind === 'plugin' && source.kind === 'plugin' && existingSource.pluginName === source.pluginName;
+            if (!samePlugin) {
+                throw new Error(`Strategy '${type}' is already registered for scope '${organizationId}'.`);
+            }
+        }
+        orgMap.set(type, instance);
+        this.strategies.set(organizationId, orgMap);
+        this.logger.debug(`Registered strategy of type ${type} for scope ${organizationId} from plugin ${pluginName}`);
+        if (pluginName) {
+            var _this_pluginStrategies_get;
+            const pluginStrategies = (_this_pluginStrategies_get = this.pluginStrategies.get(pluginName)) != null ? _this_pluginStrategies_get : new Set();
+            pluginStrategies.add(type);
+            this.pluginStrategies.set(pluginName, pluginStrategies);
+        }
+        return existing;
+    }
     constructor(strategyKey, discoveryService, reflector){
         this.logger = new common.Logger(BaseStrategyRegistry.name);
         // Map<scopeKey, Map<type, strategy>>
         this.strategies = new Map();
         this.pluginStrategies = new Map();
+        this.explicitSources = new WeakMap();
         this.strategyKey = strategyKey;
         this.discoveryService = discoveryService;
         this.reflector = reflector;
@@ -1700,13 +1776,13 @@ var DefaultParameterName;
 const PARAMETER_RULE_TEMPLATE = {
     [DefaultParameterName.TEMPERATURE]: {
         label: {
-            en_US: "Temperature",
-            zh_Hans: "温度"
+            en_US: 'Temperature',
+            zh_Hans: '温度'
         },
         type: contracts.ParameterType.FLOAT,
         help: {
-            en_US: "Controls randomness. Lower temperature results in less random completions." + " As the temperature approaches zero, the model will become deterministic and repetitive." + " Higher temperature results in more random completions.",
-            zh_Hans: "温度控制随机性。较低的温度会导致较少的随机完成。随着温度接近零，模型将变得确定性和重复性。" + "较高的温度会导致更多的随机完成。"
+            en_US: 'Controls randomness. Lower temperature results in less random completions.' + ' As the temperature approaches zero, the model will become deterministic and repetitive.' + ' Higher temperature results in more random completions.',
+            zh_Hans: '温度控制随机性。较低的温度会导致较少的随机完成。随着温度接近零，模型将变得确定性和重复性。' + '较高的温度会导致更多的随机完成。'
         },
         required: false,
         default: 0.0,
@@ -1716,13 +1792,13 @@ const PARAMETER_RULE_TEMPLATE = {
     },
     [DefaultParameterName.TOP_P]: {
         label: {
-            en_US: "Top P",
-            zh_Hans: "Top P"
+            en_US: 'Top P',
+            zh_Hans: 'Top P'
         },
         type: contracts.ParameterType.FLOAT,
         help: {
-            en_US: "Controls diversity via nucleus sampling: 0.5 means half of all likelihood-weighted options" + " are considered.",
-            zh_Hans: "通过核心采样控制多样性：0.5表示考虑了一半的所有可能性加权选项。"
+            en_US: 'Controls diversity via nucleus sampling: 0.5 means half of all likelihood-weighted options' + ' are considered.',
+            zh_Hans: '通过核心采样控制多样性：0.5表示考虑了一半的所有可能性加权选项。'
         },
         required: false,
         default: 1.0,
@@ -1732,13 +1808,13 @@ const PARAMETER_RULE_TEMPLATE = {
     },
     [DefaultParameterName.TOP_K]: {
         label: {
-            en_US: "Top K",
-            zh_Hans: "Top K"
+            en_US: 'Top K',
+            zh_Hans: 'Top K'
         },
         type: contracts.ParameterType.INT,
         help: {
-            en_US: "Limits the number of tokens to consider for each step by keeping only the k most likely tokens.",
-            zh_Hans: "通过只保留每一步中最可能的 k 个标记来限制要考虑的标记数量。"
+            en_US: 'Limits the number of tokens to consider for each step by keeping only the k most likely tokens.',
+            zh_Hans: '通过只保留每一步中最可能的 k 个标记来限制要考虑的标记数量。'
         },
         required: false,
         default: 50,
@@ -1748,13 +1824,13 @@ const PARAMETER_RULE_TEMPLATE = {
     },
     [DefaultParameterName.PRESENCE_PENALTY]: {
         label: {
-            en_US: "Presence Penalty",
-            zh_Hans: "存在惩罚"
+            en_US: 'Presence Penalty',
+            zh_Hans: '存在惩罚'
         },
         type: contracts.ParameterType.FLOAT,
         help: {
-            en_US: "Applies a penalty to the log-probability of tokens already in the text.",
-            zh_Hans: "对文本中已有的标记的对数概率施加惩罚。"
+            en_US: 'Applies a penalty to the log-probability of tokens already in the text.',
+            zh_Hans: '对文本中已有的标记的对数概率施加惩罚。'
         },
         required: false,
         default: 0.0,
@@ -1764,13 +1840,13 @@ const PARAMETER_RULE_TEMPLATE = {
     },
     [DefaultParameterName.FREQUENCY_PENALTY]: {
         label: {
-            en_US: "Frequency Penalty",
-            zh_Hans: "频率惩罚"
+            en_US: 'Frequency Penalty',
+            zh_Hans: '频率惩罚'
         },
         type: contracts.ParameterType.FLOAT,
         help: {
-            en_US: "Applies a penalty to the log-probability of tokens that appear in the text.",
-            zh_Hans: "对文本中出现的标记的对数概率施加惩罚。"
+            en_US: 'Applies a penalty to the log-probability of tokens that appear in the text.',
+            zh_Hans: '对文本中出现的标记的对数概率施加惩罚。'
         },
         required: false,
         default: 0.0,
@@ -1780,44 +1856,44 @@ const PARAMETER_RULE_TEMPLATE = {
     },
     [DefaultParameterName.MAX_TOKENS]: {
         label: {
-            en_US: "Max Tokens",
-            zh_Hans: "最大标记"
+            en_US: 'Max Tokens',
+            zh_Hans: '最大标记'
         },
         type: contracts.ParameterType.INT,
         help: {
-            en_US: "Specifies the upper limit on the length of generated results." + " If the generated results are truncated, you can increase this parameter.",
-            zh_Hans: "指定生成结果长度的上限。如果生成结果截断，可以调大该参数。"
+            en_US: 'Specifies the upper limit on the length of generated results.' + ' If the generated results are truncated, you can increase this parameter.',
+            zh_Hans: '指定生成结果长度的上限。如果生成结果截断，可以调大该参数。'
         },
         required: false,
-        default: 64,
+        default: 2048,
         min: 1,
         max: 2048,
         precision: 0
     },
     [DefaultParameterName.RESPONSE_FORMAT]: {
         label: {
-            en_US: "Response Format",
-            zh_Hans: "回复格式"
+            en_US: 'Response Format',
+            zh_Hans: '回复格式'
         },
         type: contracts.ParameterType.STRING,
         help: {
-            en_US: "Set a response format, ensure the output from llm is a valid code block as possible," + " such as JSON, XML, etc.",
-            zh_Hans: "设置一个返回格式，确保llm的输出尽可能是有效的代码块，如JSON、XML等"
+            en_US: 'Set a response format, ensure the output from llm is a valid code block as possible,' + ' such as JSON, XML, etc.',
+            zh_Hans: '设置一个返回格式，确保llm的输出尽可能是有效的代码块，如JSON、XML等'
         },
         required: false,
         options: [
-            "JSON",
-            "XML"
+            'JSON',
+            'XML'
         ]
     },
     [DefaultParameterName.JSON_SCHEMA]: {
         label: {
-            en_US: "JSON Schema"
+            en_US: 'JSON Schema'
         },
         type: contracts.ParameterType.TEXT,
         help: {
-            en_US: "Set a response json schema will ensure LLM to adhere it.",
-            zh_Hans: "设置返回的json schema，llm将按照它返回"
+            en_US: 'Set a response json schema will ensure LLM to adhere it.',
+            zh_Hans: '设置返回的json schema，llm将按照它返回'
         },
         required: false
     }
@@ -5849,6 +5925,551 @@ function freezeItems(items) {
     ]) : undefined;
 }
 
+const XPERT_TOOL_PROVIDER = 'XPERT_TOOL_PROVIDER';
+const XPERT_TOOL_PROVIDER_METADATA = 'XPERT_TOOL_PROVIDER_METADATA';
+const XPERT_TOOL_METHOD_METADATA = 'XPERT_TOOL_METHOD_METADATA';
+/** Marks one injectable business service as a reusable Tool provider and one native MCP service. */ const XpertToolProvider = (options)=>common.applyDecorators(common.Injectable(), common.SetMetadata(XPERT_TOOL_PROVIDER, options.provider), common.SetMetadata(XPERT_TOOL_PROVIDER_METADATA, Object.freeze(_extends._extends({}, options))), common.SetMetadata(STRATEGY_META_KEY, XPERT_TOOL_PROVIDER));
+/** Exposes one business method through an Agent Middleware, native MCP, or both. */ const XpertTool = (options)=>common.SetMetadata(XPERT_TOOL_METHOD_METADATA, Object.freeze(_extends._extends({}, options)));
+
+const PROVIDER_PATTERN = /^[a-z][a-z0-9_]*$/;
+const MIDDLEWARE_PROVIDER_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+const COMPONENT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_PATTERN = COMPONENT_KEY_PATTERN;
+const TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+function describeXpertToolProvider(instance) {
+    const target = instance.constructor;
+    const options = Reflect.getMetadata(XPERT_TOOL_PROVIDER_METADATA, target);
+    if (!options) {
+        throw new Error(`Provider '${target.name}' is missing @XpertToolProvider metadata.`);
+    }
+    validateProviderOptions(options);
+    const methods = collectDecoratedMethods(instance);
+    const names = new Set();
+    var _options_middlewares;
+    const middlewareProviders = new Set(((_options_middlewares = options.middlewares) != null ? _options_middlewares : []).map(({ provider })=>provider));
+    var _options_apps;
+    const appKeys = new Set(((_options_apps = options.apps) != null ? _options_apps : []).map(({ key })=>key));
+    const tools = methods.map(({ methodName, options: toolOptions })=>{
+        var _toolOptions_mcp_app;
+        validateToolOptions(toolOptions, methodName);
+        if (names.has(toolOptions.name)) {
+            throw new Error(`Tool '${toolOptions.name}' is declared more than once by provider '${options.provider}'.`);
+        }
+        names.add(toolOptions.name);
+        const middlewareProvider = resolveMiddlewareProvider(toolOptions, options);
+        if (!middlewareProvider && !toolOptions.mcp) {
+            throw new Error(`Tool '${toolOptions.name}' is not exposed through Middleware or MCP.`);
+        }
+        if (middlewareProvider && !middlewareProviders.has(middlewareProvider)) {
+            throw new Error(`Tool '${toolOptions.name}' references undeclared Middleware provider '${middlewareProvider}'.`);
+        }
+        const appKey = toolOptions.mcp && ((_toolOptions_mcp_app = toolOptions.mcp.app) == null ? void 0 : _toolOptions_mcp_app.resourceKey);
+        if (appKey && !appKeys.has(appKey)) {
+            throw new Error(`MCP Tool '${toolOptions.name}' references undeclared App '${appKey}'.`);
+        }
+        return Object.freeze({
+            methodName,
+            middlewareProvider,
+            options: toolOptions
+        });
+    });
+    if (!tools.length) {
+        throw new Error(`Provider '${options.provider}' does not declare any @XpertTool methods.`);
+    }
+    return Object.freeze({
+        options: Object.freeze(_extends._extends({}, options)),
+        tools: Object.freeze(tools)
+    });
+}
+function collectDecoratedMethods(instance) {
+    const result = [];
+    const seen = new Set();
+    let prototype = Object.getPrototypeOf(instance);
+    while(prototype && prototype !== Object.prototype){
+        for (const methodName of Object.getOwnPropertyNames(prototype)){
+            if (methodName === 'constructor' || seen.has(methodName)) continue;
+            seen.add(methodName);
+            const method = Reflect.get(prototype, methodName);
+            if (typeof method !== 'function') continue;
+            const options = Reflect.getMetadata(XPERT_TOOL_METHOD_METADATA, method);
+            if (options) result.push({
+                methodName,
+                options
+            });
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return result;
+}
+function validateProviderOptions(options) {
+    var _options_name;
+    if (!PROVIDER_PATTERN.test(options.provider)) {
+        throw new Error(`Xpert Tool provider '${options.provider}' must use lowercase snake_case.`);
+    }
+    if (!COMPONENT_KEY_PATTERN.test(options.componentKey)) {
+        throw new Error(`Xpert Tool component key '${options.componentKey}' must use lowercase kebab-case.`);
+    }
+    if (!((_options_name = options.name) == null ? void 0 : _options_name.trim())) throw new Error(`Xpert Tool provider '${options.provider}' requires a name.`);
+    if (options.slug && !SLUG_PATTERN.test(options.slug)) {
+        throw new Error(`Xpert Tool provider slug '${options.slug}' must use lowercase kebab-case.`);
+    }
+    const middlewareProviders = new Set();
+    var _options_middlewares;
+    for (const definition of (_options_middlewares = options.middlewares) != null ? _options_middlewares : []){
+        if (!MIDDLEWARE_PROVIDER_PATTERN.test(definition.provider)) {
+            throw new Error(`Middleware provider '${definition.provider}' must be a stable identifier.`);
+        }
+        if (middlewareProviders.has(definition.provider)) {
+            throw new Error(`Middleware provider '${definition.provider}' is declared more than once.`);
+        }
+        if (definition.meta.name !== definition.provider) {
+            throw new Error(`Middleware metadata name must match provider '${definition.provider}'.`);
+        }
+        middlewareProviders.add(definition.provider);
+    }
+    if (options.defaultMiddleware && !middlewareProviders.has(options.defaultMiddleware)) {
+        throw new Error(`Default Middleware provider '${options.defaultMiddleware}' is not declared.`);
+    }
+    const appKeys = new Set();
+    var _options_apps;
+    for (const app of (_options_apps = options.apps) != null ? _options_apps : []){
+        if (!TOOL_NAME_PATTERN.test(app.key) || app.key.length > 191) {
+            throw new Error(`MCP App key '${app.key}' is invalid.`);
+        }
+        if (appKeys.has(app.key)) {
+            throw new Error(`MCP App '${app.key}' is declared more than once.`);
+        }
+        if (!isRelativeHtmlEntry(app.entry)) {
+            throw new Error(`MCP App '${app.key}' entry must be a relative HTML path inside the plugin bundle.`);
+        }
+        appKeys.add(app.key);
+    }
+}
+function validateToolOptions(options, methodName) {
+    var _options_description;
+    if (!TOOL_NAME_PATTERN.test(options.name) || options.name.length > 191) {
+        throw new Error(`Method '${methodName}' declares invalid Tool name '${options.name}'.`);
+    }
+    if (!((_options_description = options.description) == null ? void 0 : _options_description.trim())) throw new Error(`Tool '${options.name}' requires a description.`);
+    assertStrictObjectSchema(options.inputSchema, options.name, 'input');
+    if (options.mcp && !options.outputSchema) {
+        throw new Error(`MCP Tool '${options.name}' requires an outputSchema.`);
+    }
+    if (options.mcp && options.outputSchema) {
+        assertStrictObjectSchema(options.outputSchema, options.name, 'output');
+    }
+    if (options.mcp && !options.mcp.requiredContext.length) {
+        throw new Error(`MCP Tool '${options.name}' requires at least one execution context.`);
+    }
+    if (options.mcp) {
+        const behavior = options.mcp.behavior;
+        if (!includesValue(contracts.MCP_TOOL_RISKS, behavior == null ? void 0 : behavior.risk) || !includesValue(contracts.MCP_TOOL_SIDE_EFFECTS, behavior == null ? void 0 : behavior.sideEffect) || !includesValue(contracts.MCP_TOOL_IDEMPOTENCY, behavior == null ? void 0 : behavior.idempotency)) {
+            throw new Error(`MCP Tool '${options.name}' requires valid behavior annotations.`);
+        }
+        const contexts = new Set(options.mcp.requiredContext);
+        if (contexts.size !== options.mcp.requiredContext.length || [
+            ...contexts
+        ].some((context)=>!includesValue(contracts.MCP_REQUIRED_CONTEXTS, context))) {
+            throw new Error(`MCP Tool '${options.name}' declares invalid or duplicate execution context requirements.`);
+        }
+        if (options.mcp.visibility && (!options.mcp.visibility.length || new Set(options.mcp.visibility).size !== options.mcp.visibility.length || options.mcp.visibility.some((visibility)=>!includesValue(contracts.MCP_CAPABILITY_VISIBILITIES, visibility)))) {
+            throw new Error(`MCP Tool '${options.name}' declares invalid visibility.`);
+        }
+        if (options.mcp.app && options.mcp.visibility && !options.mcp.visibility.includes('app')) {
+            throw new Error(`MCP Tool '${options.name}' with an App binding must include app visibility.`);
+        }
+    }
+}
+function isRelativeHtmlEntry(entry) {
+    if (!entry || !entry.endsWith('.html') || entry.startsWith('/') || entry.includes('\\')) return false;
+    return entry.split('/').every((segment)=>segment !== '.' && segment !== '..' && segment.length > 0);
+}
+function assertStrictObjectSchema(schema, toolName, role) {
+    if (!schema || typeof Reflect.get(schema, 'parseAsync') !== 'function') {
+        throw new Error(`Tool '${toolName}' requires a Zod ${role} schema.`);
+    }
+    const definition = Reflect.get(schema, '_def');
+    if (!definition || Reflect.get(definition, 'unknownKeys') !== 'strict') {
+        throw new Error(`Tool '${toolName}' ${role} schema must be a strict Zod object.`);
+    }
+}
+function resolveMiddlewareProvider(tool, provider) {
+    if (tool.middleware === false) return undefined;
+    if (typeof tool.middleware === 'string') return tool.middleware;
+    if (tool.middleware === true || tool.middleware === undefined) return provider.defaultMiddleware;
+    return undefined;
+}
+function getXpertToolMethod(instance, descriptor) {
+    const method = Reflect.get(instance, descriptor.methodName);
+    if (typeof method !== 'function') {
+        throw new Error(`Decorated Tool method '${descriptor.methodName}' is not callable.`);
+    }
+    return method.bind(instance);
+}
+function includesValue(values, value) {
+    return values.some((candidate)=>candidate === value);
+}
+
+exports.XpertToolProviderRegistry = class XpertToolProviderRegistry extends BaseStrategyRegistry {
+    upsert(candidate) {
+        const target = resolveStrategyMetadataTarget(candidate);
+        if (!target || !Reflect.getMetadata(XPERT_TOOL_PROVIDER_METADATA, target)) return;
+        const instance = candidate;
+        const descriptor = describeXpertToolProvider(instance);
+        const source = this.getSource(instance);
+        this.assertUniqueClaims(instance, descriptor, source.scopeKey);
+        const previous = this.register(descriptor.options.provider, instance, source);
+        this.replacements.set(instance, previous != null ? previous : null);
+    }
+    rollback(instance) {
+        const descriptor = describeXpertToolProvider(instance);
+        const source = this.getSource(instance);
+        const previous = this.replacements.get(instance);
+        if (previous) {
+            this.register(descriptor.options.provider, previous, this.getSource(previous));
+        } else {
+            this.unregister(descriptor.options.provider, source, instance);
+        }
+        this.replacements.delete(instance);
+    }
+    assertUniqueClaims(instance, descriptor, scopeKey) {
+        var _this_strategies_get;
+        const toolNames = new Set(descriptor.tools.map(({ options })=>options.name));
+        var _this_strategies_get_entries;
+        for (const [providerKey, existing] of (_this_strategies_get_entries = (_this_strategies_get = this.strategies.get(scopeKey)) == null ? void 0 : _this_strategies_get.entries()) != null ? _this_strategies_get_entries : []){
+            if (existing === instance || providerKey === descriptor.options.provider) continue;
+            const existingDescriptor = describeXpertToolProvider(existing);
+            if (existingDescriptor.options.componentKey === descriptor.options.componentKey) {
+                throw new Error(`Component key '${descriptor.options.componentKey}' is already registered for scope '${scopeKey}'.`);
+            }
+            const duplicateTool = existingDescriptor.tools.find(({ options })=>toolNames.has(options.name));
+            if (duplicateTool) {
+                throw new Error(`Tool '${duplicateTool.options.name}' is already registered for scope '${scopeKey}'.`);
+            }
+        }
+    }
+    constructor(discoveryService, reflector){
+        super(XPERT_TOOL_PROVIDER, discoveryService, reflector);
+        this.replacements = new WeakMap();
+    }
+};
+exports.XpertToolProviderRegistry = __decorate([
+    common.Injectable(),
+    __metadata("design:paramtypes", [
+        core.DiscoveryService,
+        core.Reflector
+    ])
+], exports.XpertToolProviderRegistry);
+
+class DecoratedToolsetStrategy {
+    validateConfig() {
+        return Promise.resolve();
+    }
+    async create(toolset, params) {
+        return new DecoratedBuiltinToolset(this.instance, this.descriptor, toolset, params, this.pluginName, this.pluginVersion);
+    }
+    createTools() {
+        return [];
+    }
+    constructor(instance, pluginName, pluginVersion){
+        this.instance = instance;
+        this.pluginName = pluginName;
+        this.pluginVersion = pluginVersion;
+        this.descriptor = describeXpertToolProvider(instance);
+        const options = this.descriptor.options;
+        var _options_author, _options_tags, _options_label, _options_configSchema;
+        this.meta = _extends._extends({
+            author: (_options_author = options.author) != null ? _options_author : 'Plugin',
+            tags: [
+                ...(_options_tags = options.tags) != null ? _options_tags : [
+                    'mcp'
+                ]
+            ],
+            name: options.provider,
+            label: (_options_label = options.label) != null ? _options_label : asI18n(options.name)
+        }, options.description ? {
+            description: asI18n(options.description)
+        } : {}, {
+            configSchema: (_options_configSchema = options.configSchema) != null ? _options_configSchema : {
+                type: 'object',
+                properties: {},
+                required: []
+            }
+        }, options.icon ? {
+            icon: options.icon
+        } : {});
+    }
+}
+class DecoratedAgentMiddlewareStrategy {
+    async createMiddleware(options, context) {
+        const tools = this.descriptor.tools.filter((item)=>item.middlewareProvider === this.provider).map((item)=>createAgentTool(this.instance, item, context, options));
+        const extensions = await (this.instance.getMiddlewareExtensions == null ? void 0 : this.instance.getMiddlewareExtensions.call(this.instance, this.provider, options, context));
+        return _extends._extends({}, extensions != null ? extensions : {}, {
+            name: this.provider,
+            tools
+        });
+    }
+    constructor(instance, descriptor, provider){
+        var _descriptor_options_middlewares;
+        this.instance = instance;
+        this.descriptor = descriptor;
+        this.provider = provider;
+        const definition = (_descriptor_options_middlewares = descriptor.options.middlewares) == null ? void 0 : _descriptor_options_middlewares.find((item)=>item.provider === provider);
+        if (!definition) throw new Error(`Middleware provider '${provider}' is not declared.`);
+        this.meta = definition.meta;
+    }
+}
+var _definitions = /*#__PURE__*/ _class_private_field_loose_key("_definitions");
+let DecoratedBuiltinToolset = class DecoratedBuiltinToolset extends modelProvider.BuiltinToolset {
+    _validateCredentials() {
+        return Promise.resolve();
+    }
+    async initTools() {
+        return this.tools;
+    }
+    getMcpCapabilityDefinitions() {
+        return _class_private_field_loose_base(this, _definitions)[_definitions];
+    }
+    getMcpCapabilitySource() {
+        return _extends._extends({}, this.pluginName ? {
+            pluginName: this.pluginName
+        } : {}, this.pluginVersion ? {
+            pluginVersion: this.pluginVersion
+        } : {});
+    }
+    constructor(instance, descriptor, toolset, params, pluginName, pluginVersion){
+        var _descriptor_options_apps;
+        super(descriptor.options.provider, toolset, params);
+        Object.defineProperty(this, _definitions, {
+            writable: true,
+            value: void 0
+        });
+        this.pluginName = pluginName;
+        this.pluginVersion = pluginVersion;
+        this.tools = [];
+        _class_private_field_loose_base(this, _definitions)[_definitions] = _extends._extends({
+            instructions: descriptor.options.instructions,
+            tools: descriptor.tools.filter((item)=>!!item.options.mcp).map((item)=>createMcpTool(instance, item))
+        }, ((_descriptor_options_apps = descriptor.options.apps) == null ? void 0 : _descriptor_options_apps.length) ? {
+            apps: [
+                ...descriptor.options.apps
+            ]
+        } : {});
+    }
+};
+function createAgentTool(instance, descriptor, middlewareContext, middlewareOptions) {
+    const invoke = getXpertToolMethod(instance, descriptor);
+    return tools.tool(async (input, config)=>{
+        const parsedInput = await descriptor.options.inputSchema.parseAsync(input);
+        const output = await invoke(parsedInput, agentExecutionContext(middlewareContext, middlewareOptions, config));
+        const parsedOutput = descriptor.options.outputSchema ? await descriptor.options.outputSchema.parseAsync(output) : output;
+        return stringifyDto(parsedOutput, descriptor.options.name);
+    }, _extends._extends({
+        name: descriptor.options.name,
+        description: descriptor.options.description,
+        schema: descriptor.options.inputSchema,
+        verboseParsingErrors: true
+    }, descriptor.options.metadata ? {
+        metadata: descriptor.options.metadata
+    } : {}));
+}
+function createMcpTool(instance, descriptor) {
+    const mcp = descriptor.options.mcp;
+    const outputSchema = descriptor.options.outputSchema;
+    if (!mcp || !outputSchema) throw new Error(`MCP Tool '${descriptor.options.name}' is incomplete.`);
+    const invoke = getXpertToolMethod(instance, descriptor);
+    var _mcp_visibility;
+    return _extends._extends({
+        name: descriptor.options.name
+    }, descriptor.options.title ? {
+        title: descriptor.options.title
+    } : {}, {
+        description: descriptor.options.description,
+        inputSchema: descriptor.options.inputSchema,
+        outputSchema,
+        exposure: {
+            mcp: {
+                eligible: true
+            }
+        },
+        behavior: mcp.behavior,
+        requiredContext: [
+            ...mcp.requiredContext
+        ],
+        visibility: [
+            ...(_mcp_visibility = mcp.visibility) != null ? _mcp_visibility : mcp.app ? [
+                'model',
+                'app'
+            ] : [
+                'model'
+            ]
+        ]
+    }, mcp.app ? {
+        app: {
+            resourceKey: mcp.app.resourceKey
+        }
+    } : {}, {
+        execute: async (input, context)=>{
+            const parsedInput = await descriptor.options.inputSchema.parseAsync(input);
+            const output = await invoke(parsedInput, mcpExecutionContext(context));
+            const parsedOutput = await outputSchema.parseAsync(output);
+            const dto = jsonDto(parsedOutput, descriptor.options.name);
+            var _descriptor_options_title;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `${(_descriptor_options_title = descriptor.options.title) != null ? _descriptor_options_title : descriptor.options.name} completed. See structuredContent for the result.`
+                    }
+                ],
+                structuredContent: dto
+            };
+        }
+    });
+}
+function agentExecutionContext(context, middlewareOptions, config) {
+    const configurable = config.configurable;
+    const requestId = readString(configurable, 'tool_call_id');
+    const executionId = readString(configurable, 'executionId');
+    const traceId = readString(configurable, 'traceId');
+    return _extends._extends({
+        surface: 'middleware',
+        tenantId: context.tenantId,
+        organizationId: context.organizationId,
+        principal: {
+            type: 'user',
+            id: context.userId,
+            userId: context.userId
+        },
+        workspaceId: context.workspaceId,
+        projectId: context.projectId,
+        conversationId: context.conversationId,
+        threadId: context.threadId,
+        xpertId: context.xpertId,
+        agentKey: context.agentKey
+    }, executionId ? {
+        executionId
+    } : {}, requestId ? {
+        requestId
+    } : {}, traceId ? {
+        traceId
+    } : {}, {
+        signal: config.signal,
+        host: {
+            models: {
+                createModelClient: context.runtime.createModelClient,
+                getModelProvider: context.runtime.getModelProvider
+            }
+        },
+        middlewareOptions
+    });
+}
+function mcpExecutionContext(context) {
+    return {
+        surface: 'mcp',
+        tenantId: context.tenantId,
+        organizationId: context.organizationId,
+        principal: context.principal,
+        workspaceId: context.workspaceId,
+        projectId: context.projectId,
+        conversationId: context.conversationId,
+        threadId: readString(context, 'threadId'),
+        xpertId: context.xpertId,
+        agentKey: context.agentKey,
+        executionId: context.executionId,
+        requestId: context.requestId,
+        traceId: context.traceId,
+        signal: context.signal,
+        host: context.host
+    };
+}
+function stringifyDto(value, toolName) {
+    const result = JSON.stringify(value);
+    if (result === undefined) throw new Error(`Tool '${toolName}' returned a non-JSON value.`);
+    return result;
+}
+function jsonDto(value, toolName) {
+    return JSON.parse(stringifyDto(value, toolName));
+}
+function asI18n(value) {
+    return {
+        en_US: value,
+        zh_Hans: value
+    };
+}
+function readString(value, key) {
+    if (!value || typeof value !== 'object') return undefined;
+    const field = Reflect.get(value, key);
+    return typeof field === 'string' && field ? field : undefined;
+}
+
+/** Expands one decorated business provider into the existing Toolset and Middleware registries. */ exports.XpertToolProviderCoordinator = class XpertToolProviderCoordinator {
+    onModuleInit() {
+        this.subscription = this.bus.events$.subscribe((event)=>{
+            if (event.type === 'UPSERT' && event.strategyType === XPERT_TOOL_PROVIDER) {
+                this.expand(event.entry.instance);
+            }
+        });
+        for (const wrapper of this.discovery.getProviders()){
+            if (wrapper.instance) this.expand(wrapper.instance);
+        }
+    }
+    onModuleDestroy() {
+        var _this_subscription;
+        (_this_subscription = this.subscription) == null ? void 0 : _this_subscription.unsubscribe();
+    }
+    expand(candidate) {
+        if (!candidate || typeof candidate !== 'object' && typeof candidate !== 'function') return;
+        const instance = candidate;
+        if (this.processed.has(instance)) return;
+        const target = resolveStrategyMetadataTarget(instance);
+        if (!target || !Reflect.getMetadata(XPERT_TOOL_PROVIDER_METADATA, target)) return;
+        const provider = instance;
+        const descriptor = describeXpertToolProvider(provider);
+        const source = this.providerRegistry.getSource(provider);
+        const pluginName = source.kind === 'plugin' ? source.pluginName : undefined;
+        const pluginVersion = source.kind === 'plugin' ? source.pluginVersion : undefined;
+        const toolsetAdapter = new DecoratedToolsetStrategy(provider, pluginName, pluginVersion);
+        var _descriptor_options_middlewares;
+        const middlewareAdapters = ((_descriptor_options_middlewares = descriptor.options.middlewares) != null ? _descriptor_options_middlewares : []).filter((definition)=>descriptor.tools.some((item)=>item.middlewareProvider === definition.provider)).map((definition)=>({
+                provider: definition.provider,
+                strategy: new DecoratedAgentMiddlewareStrategy(provider, descriptor, definition.provider)
+            }));
+        try {
+            this.toolsetRegistry.assertCanRegister(descriptor.options.provider, toolsetAdapter, source);
+            for (const adapter of middlewareAdapters){
+                this.middlewareRegistry.assertCanRegister(adapter.provider, adapter.strategy, source);
+            }
+        } catch (error) {
+            this.providerRegistry.rollback(provider);
+            throw error;
+        }
+        this.toolsetRegistry.register(descriptor.options.provider, toolsetAdapter, source);
+        for (const adapter of middlewareAdapters){
+            this.middlewareRegistry.register(adapter.provider, adapter.strategy, source);
+        }
+        this.processed.add(instance);
+    }
+    constructor(discovery, bus, providerRegistry, toolsetRegistry, middlewareRegistry){
+        this.processed = new WeakSet();
+        this.discovery = discovery;
+        this.bus = bus;
+        this.providerRegistry = providerRegistry;
+        this.toolsetRegistry = toolsetRegistry;
+        this.middlewareRegistry = middlewareRegistry;
+    }
+};
+exports.XpertToolProviderCoordinator = __decorate([
+    common.Injectable(),
+    __metadata("design:paramtypes", [
+        core.DiscoveryService,
+        exports.StrategyBus,
+        exports.XpertToolProviderRegistry,
+        exports.ToolsetRegistry,
+        exports.AgentMiddlewareRegistry
+    ])
+], exports.XpertToolProviderCoordinator);
+
 Object.defineProperty(exports, "ASSISTANT_CHAT_SEND_MESSAGE_COMMAND", {
     enumerable: true,
     get: function () { return contracts.ASSISTANT_CHAT_SEND_MESSAGE_COMMAND; }
@@ -5940,6 +6561,8 @@ exports.DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC = DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC;
 exports.DOCUMENT_SOURCE_STRATEGY = DOCUMENT_SOURCE_STRATEGY;
 exports.DOCUMENT_TRANSFORMER_STRATEGY = DOCUMENT_TRANSFORMER_STRATEGY;
 exports.DataSourceStrategy = DataSourceStrategy;
+exports.DecoratedAgentMiddlewareStrategy = DecoratedAgentMiddlewareStrategy;
+exports.DecoratedToolsetStrategy = DecoratedToolsetStrategy;
 exports.DocumentSourceStrategy = DocumentSourceStrategy;
 exports.DocumentTransformerStrategy = DocumentTransformerStrategy;
 exports.EVOLUTION_RUNTIME_SERVICE_TOKEN = EVOLUTION_RUNTIME_SERVICE_TOKEN;
@@ -6039,8 +6662,13 @@ exports.WorkflowNodeStrategy = WorkflowNodeStrategy;
 exports.WorkflowTriggerStrategy = WorkflowTriggerStrategy;
 exports.WrapWorkflowNodeExecutionCommand = WrapWorkflowNodeExecutionCommand;
 exports.XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN = XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN;
+exports.XPERT_TOOL_METHOD_METADATA = XPERT_TOOL_METHOD_METADATA;
+exports.XPERT_TOOL_PROVIDER = XPERT_TOOL_PROVIDER;
+exports.XPERT_TOOL_PROVIDER_METADATA = XPERT_TOOL_PROVIDER_METADATA;
 exports.XpFileSystem = XpFileSystem;
 exports.XpertServerPlugin = XpertServerPlugin;
+exports.XpertTool = XpertTool;
+exports.XpertToolProvider = XpertToolProvider;
 exports.als = als;
 exports.appendSandboxMessage = appendSandboxMessage;
 exports.buildSandboxTimeoutMessage = buildSandboxTimeoutMessage;
@@ -6061,6 +6689,7 @@ exports.defineMcpResource = defineMcpResource;
 exports.defineMcpResourceTemplate = defineMcpResourceTemplate;
 exports.defineXpertTool = defineXpertTool;
 exports.derivePluginArtifactNamespace = derivePluginArtifactNamespace;
+exports.describeXpertToolProvider = describeXpertToolProvider;
 exports.downloadRemoteFile = downloadRemoteFile;
 exports.formatSandboxTimeout = formatSandboxTimeout;
 exports.getDefaultTenantId = getDefaultTenantId;
@@ -6072,6 +6701,7 @@ exports.getPositionMap = getPositionMap;
 exports.getRequestContext = getRequestContext;
 exports.getRequiredPermissionOperation = getRequiredPermissionOperation;
 exports.getTenantGlobalScopeKey = getTenantGlobalScopeKey;
+exports.getXpertToolMethod = getXpertToolMethod;
 exports.isDevelopmentSandboxRuntimeEnvironment = isDevelopmentSandboxRuntimeEnvironment;
 exports.isModelOutputValidationError = isModelOutputValidationError;
 exports.isModelUsagePricingConfig = isModelUsagePricingConfig;