@xpert-ai/plugin-sdk 3.10.1 → 3.12.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @xpert-ai/plugin-sdk
 
+## 3.12.0
+
+### Minor Changes
+
+- d017897: plugin integration guard
+
+### Patch Changes
+
+- Updated dependencies [d017897]
+  - @xpert-ai/contracts@3.12.0
+
+## 3.11.2
+
+### Patch Changes
+
+- 7418eef: version
+
+## 4.0.0
+
+### Minor Changes
+
+- d92d0f2: upgrade zard ui
+
+### Patch Changes
+
+- Updated dependencies [d92d0f2]
+  - @xpert-ai/contracts@3.11.0
+
 ## 3.11.0
 
 ### Minor Changes

package/index.cjs.js

@@ -132,6 +132,11 @@ function __decorate(decorators, target, key, desc) {
     else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
+function __param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
 function __metadata(metadataKey, metadataValue) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
 }
@@ -524,7 +529,7 @@ class BaseStrategyRegistry {
         var _this_strategies_get_get;
         const strategy = (_this_strategies_get_get = (_this_strategies_get = this.strategies.get(orgKey)) == null ? void 0 : _this_strategies_get.get(type)) != null ? _this_strategies_get_get : orgKey === GLOBAL_ORGANIZATION_SCOPE ? undefined : (_this_strategies_get1 = this.strategies.get(GLOBAL_ORGANIZATION_SCOPE)) == null ? void 0 : _this_strategies_get1.get(type);
         if (!strategy) {
-            throw new Error(`No strategy found for type ${type}`);
+            throw new Error(`No strategy found for type '${type}' for strategy '${this.strategyKey}'`);
         }
         return strategy;
     }
@@ -1123,6 +1128,13 @@ function getRequiredPermissionOperation(method, permissionType) {
  * System token for resolving user permission service from plugin context.
  */ const USER_PERMISSION_SERVICE_TOKEN = 'XPERT_PLUGIN_USER_PERMISSION_SERVICE';
 
+/**
+ * System token for resolving speech-to-text service from plugin context.
+ */ const SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN = 'XPERT_PLUGIN_SPEECH_TO_TEXT_PERMISSION_SERVICE';
+/**
+ * Internal system token used by core to expose the speech-to-text bridge.
+ */ const SPEECH_TO_TEXT_SERVICE_TOKEN = 'XPERT_SPEECH_TO_TEXT_SERVICE';
+
 async function createI18nInstance(pluginDir, language) {
     const instance = i18next.createInstance();
     const i18nDir = path.join(pluginDir, 'i18n');
@@ -1225,6 +1237,69 @@ class JsonSchemaValidator {
     }
 }
 
+const PLUGIN_WEBHOOK_AUTH_METADATA_KEY = 'xpert:plugin:webhook-auth';
+const PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN = 'XPERT_PLUGIN_WEBHOOK_AUTH_SERVICE';
+function PluginWebhookAuth(metadata = {}) {
+    return common.SetMetadata(PLUGIN_WEBHOOK_AUTH_METADATA_KEY, _extends({
+        integrationParam: 'id',
+        secretQueryParam: 'secret'
+    }, metadata));
+}
+exports.PluginWebhookAuthGuard = class PluginWebhookAuthGuard {
+    async canActivate(context) {
+        var _request_params, _request_query;
+        const metadata = this.resolveMetadata(context);
+        if (!metadata) {
+            return true;
+        }
+        const request = context.switchToHttp().getRequest();
+        const integrationParam = metadata.integrationParam || 'id';
+        const secretQueryParam = metadata.secretQueryParam || 'secret';
+        const integrationId = this.getString((_request_params = request.params) == null ? void 0 : _request_params[integrationParam]);
+        const secret = this.getString((_request_query = request.query) == null ? void 0 : _request_query[secretQueryParam]);
+        if (!integrationId || !secret) {
+            throw new common.UnauthorizedException('Plugin webhook secret is required');
+        }
+        const authService = this.authService;
+        if (!authService) {
+            throw new common.UnauthorizedException('Plugin webhook auth service is not available');
+        }
+        const principalContext = await authService.validateWebhookSecret({
+            integrationId,
+            secret,
+            provider: metadata.provider
+        });
+        if (!(principalContext == null ? void 0 : principalContext.user) || !principalContext.headers) {
+            throw new common.UnauthorizedException('Plugin webhook secret is invalid');
+        }
+        request.user = principalContext.user;
+        var _request_headers;
+        request.headers = _extends({}, (_request_headers = request.headers) != null ? _request_headers : {}, principalContext.headers);
+        return true;
+    }
+    resolveMetadata(context) {
+        var _Reflect_getMetadata, _ref;
+        return (_ref = (_Reflect_getMetadata = Reflect.getMetadata(PLUGIN_WEBHOOK_AUTH_METADATA_KEY, context.getHandler())) != null ? _Reflect_getMetadata : Reflect.getMetadata(PLUGIN_WEBHOOK_AUTH_METADATA_KEY, context.getClass())) != null ? _ref : null;
+    }
+    getString(value) {
+        if (typeof value !== 'string') {
+            return '';
+        }
+        return value.trim();
+    }
+    constructor(authService){
+        this.authService = authService;
+    }
+};
+exports.PluginWebhookAuthGuard = __decorate([
+    common.Injectable(),
+    __param(0, common.Optional()),
+    __param(0, common.Inject(PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN)),
+    __metadata("design:paramtypes", [
+        Object
+    ])
+], exports.PluginWebhookAuthGuard);
+
 const DATASOURCE_STRATEGY = 'DATASOURCE_STRATEGY';
 const DataSourceStrategy = (provider)=>common.applyDecorators(common.SetMetadata(DATASOURCE_STRATEGY, provider), common.SetMetadata(STRATEGY_META_KEY, DATASOURCE_STRATEGY));
 
@@ -2678,6 +2753,10 @@ const KnowledgebaseRuntimeCapability = createRuntimeCapability('platform.knowled
     description: 'List, search, and write chunks in platform knowledgebases.'
 });
 
+const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
+    description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
+});
+
 const AssistantTaskRuntimeCapability = createRuntimeCapability('platform.assistant_task', {
     description: 'Start asynchronous tasks on the current platform assistant.'
 });
@@ -4502,6 +4581,7 @@ exports.JUMP_TO_TARGETS = JUMP_TO_TARGETS;
 exports.JsonSchemaValidator = JsonSchemaValidator;
 exports.KNOWLEDGE_STRATEGY = KNOWLEDGE_STRATEGY;
 exports.KnowledgeStrategyKey = KnowledgeStrategyKey;
+exports.KnowledgebaseDocumentsRuntimeCapability = KnowledgebaseDocumentsRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = KnowledgebaseRuntimeCapability;
 exports.LLMUsage = LLMUsage;
 exports.LargeLanguageModel = LargeLanguageModel;
@@ -4511,12 +4591,15 @@ exports.PERMISSION_OPERATION_METADATA_KEY = PERMISSION_OPERATION_METADATA_KEY;
 exports.PLUGIN_CONFIG_RESOLVER_TOKEN = PLUGIN_CONFIG_RESOLVER_TOKEN;
 exports.PLUGIN_METADATA = PLUGIN_METADATA;
 exports.PLUGIN_METADATA_KEY = PLUGIN_METADATA_KEY;
+exports.PLUGIN_WEBHOOK_AUTH_METADATA_KEY = PLUGIN_WEBHOOK_AUTH_METADATA_KEY;
+exports.PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN = PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN;
 exports.PROVIDE_AI_MODEL_LLM = PROVIDE_AI_MODEL_LLM;
 exports.PROVIDE_AI_MODEL_MODERATION = PROVIDE_AI_MODEL_MODERATION;
 exports.PROVIDE_AI_MODEL_RERANK = PROVIDE_AI_MODEL_RERANK;
 exports.PROVIDE_AI_MODEL_SPEECH2TEXT = PROVIDE_AI_MODEL_SPEECH2TEXT;
 exports.PROVIDE_AI_MODEL_TEXT_EMBEDDING = PROVIDE_AI_MODEL_TEXT_EMBEDDING;
 exports.PROVIDE_AI_MODEL_TTS = PROVIDE_AI_MODEL_TTS;
+exports.PluginWebhookAuth = PluginWebhookAuth;
 exports.RETRIEVER_STRATEGY = RETRIEVER_STRATEGY;
 exports.RequestContext = RequestContext;
 exports.RequirePermissionOperation = RequirePermissionOperation;
@@ -4525,6 +4608,8 @@ exports.RetrieverStrategy = RetrieverStrategy;
 exports.SANDBOX_PROVIDER = SANDBOX_PROVIDER;
 exports.SANDBOX_SHELL_TIMEOUT_LIMITS_SEC = SANDBOX_SHELL_TIMEOUT_LIMITS_SEC;
 exports.SKILL_SOURCE_PROVIDER = SKILL_SOURCE_PROVIDER;
+exports.SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN = SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN;
+exports.SPEECH_TO_TEXT_SERVICE_TOKEN = SPEECH_TO_TEXT_SERVICE_TOKEN;
 exports.SSOProviderStrategyKey = SSOProviderStrategyKey;
 exports.SSO_BINDING_PERMISSION_SERVICE_TOKEN = SSO_BINDING_PERMISSION_SERVICE_TOKEN;
 exports.SSO_PROVIDER = SSO_PROVIDER;

package/index.esm.js

@@ -1,4 +1,4 @@
-import { Module, Logger, applyDecorators, SetMetadata, HttpException, HttpStatus, BadRequestException, Injectable, Inject, NotFoundException, ForbiddenException } from '@nestjs/common';
+import { Module, Logger, applyDecorators, SetMetadata, HttpException, HttpStatus, BadRequestException, Injectable, Inject, Optional, UnauthorizedException, NotFoundException, ForbiddenException } from '@nestjs/common';
 import { MODULE_METADATA } from '@nestjs/common/constants';
 import { pick } from 'lodash-es';
 import { DiscoveryService, Reflector } from '@nestjs/core';
@@ -111,6 +111,11 @@ function __decorate(decorators, target, key, desc) {
     else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
+function __param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
 function __metadata(metadataKey, metadataValue) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
 }
@@ -503,7 +508,7 @@ class BaseStrategyRegistry {
         var _this_strategies_get_get;
         const strategy = (_this_strategies_get_get = (_this_strategies_get = this.strategies.get(orgKey)) == null ? void 0 : _this_strategies_get.get(type)) != null ? _this_strategies_get_get : orgKey === GLOBAL_ORGANIZATION_SCOPE ? undefined : (_this_strategies_get1 = this.strategies.get(GLOBAL_ORGANIZATION_SCOPE)) == null ? void 0 : _this_strategies_get1.get(type);
         if (!strategy) {
-            throw new Error(`No strategy found for type ${type}`);
+            throw new Error(`No strategy found for type '${type}' for strategy '${this.strategyKey}'`);
         }
         return strategy;
     }
@@ -1102,6 +1107,13 @@ function getRequiredPermissionOperation(method, permissionType) {
  * System token for resolving user permission service from plugin context.
  */ const USER_PERMISSION_SERVICE_TOKEN = 'XPERT_PLUGIN_USER_PERMISSION_SERVICE';
 
+/**
+ * System token for resolving speech-to-text service from plugin context.
+ */ const SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN = 'XPERT_PLUGIN_SPEECH_TO_TEXT_PERMISSION_SERVICE';
+/**
+ * Internal system token used by core to expose the speech-to-text bridge.
+ */ const SPEECH_TO_TEXT_SERVICE_TOKEN = 'XPERT_SPEECH_TO_TEXT_SERVICE';
+
 async function createI18nInstance(pluginDir, language) {
     const instance = createInstance();
     const i18nDir = path__default.join(pluginDir, 'i18n');
@@ -1204,6 +1216,69 @@ class JsonSchemaValidator {
     }
 }
 
+const PLUGIN_WEBHOOK_AUTH_METADATA_KEY = 'xpert:plugin:webhook-auth';
+const PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN = 'XPERT_PLUGIN_WEBHOOK_AUTH_SERVICE';
+function PluginWebhookAuth(metadata = {}) {
+    return SetMetadata(PLUGIN_WEBHOOK_AUTH_METADATA_KEY, _extends({
+        integrationParam: 'id',
+        secretQueryParam: 'secret'
+    }, metadata));
+}
+let PluginWebhookAuthGuard = class PluginWebhookAuthGuard {
+    async canActivate(context) {
+        var _request_params, _request_query;
+        const metadata = this.resolveMetadata(context);
+        if (!metadata) {
+            return true;
+        }
+        const request = context.switchToHttp().getRequest();
+        const integrationParam = metadata.integrationParam || 'id';
+        const secretQueryParam = metadata.secretQueryParam || 'secret';
+        const integrationId = this.getString((_request_params = request.params) == null ? void 0 : _request_params[integrationParam]);
+        const secret = this.getString((_request_query = request.query) == null ? void 0 : _request_query[secretQueryParam]);
+        if (!integrationId || !secret) {
+            throw new UnauthorizedException('Plugin webhook secret is required');
+        }
+        const authService = this.authService;
+        if (!authService) {
+            throw new UnauthorizedException('Plugin webhook auth service is not available');
+        }
+        const principalContext = await authService.validateWebhookSecret({
+            integrationId,
+            secret,
+            provider: metadata.provider
+        });
+        if (!(principalContext == null ? void 0 : principalContext.user) || !principalContext.headers) {
+            throw new UnauthorizedException('Plugin webhook secret is invalid');
+        }
+        request.user = principalContext.user;
+        var _request_headers;
+        request.headers = _extends({}, (_request_headers = request.headers) != null ? _request_headers : {}, principalContext.headers);
+        return true;
+    }
+    resolveMetadata(context) {
+        var _Reflect_getMetadata, _ref;
+        return (_ref = (_Reflect_getMetadata = Reflect.getMetadata(PLUGIN_WEBHOOK_AUTH_METADATA_KEY, context.getHandler())) != null ? _Reflect_getMetadata : Reflect.getMetadata(PLUGIN_WEBHOOK_AUTH_METADATA_KEY, context.getClass())) != null ? _ref : null;
+    }
+    getString(value) {
+        if (typeof value !== 'string') {
+            return '';
+        }
+        return value.trim();
+    }
+    constructor(authService){
+        this.authService = authService;
+    }
+};
+PluginWebhookAuthGuard = __decorate([
+    Injectable(),
+    __param(0, Optional()),
+    __param(0, Inject(PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN)),
+    __metadata("design:paramtypes", [
+        Object
+    ])
+], PluginWebhookAuthGuard);
+
 const DATASOURCE_STRATEGY = 'DATASOURCE_STRATEGY';
 const DataSourceStrategy = (provider)=>applyDecorators(SetMetadata(DATASOURCE_STRATEGY, provider), SetMetadata(STRATEGY_META_KEY, DATASOURCE_STRATEGY));
 
@@ -2657,6 +2732,10 @@ const KnowledgebaseRuntimeCapability = createRuntimeCapability('platform.knowled
     description: 'List, search, and write chunks in platform knowledgebases.'
 });
 
+const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
+    description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
+});
+
 const AssistantTaskRuntimeCapability = createRuntimeCapability('platform.assistant_task', {
     description: 'Start asynchronous tasks on the current platform assistant.'
 });
@@ -4416,4 +4495,4 @@ function escapeHtmlAttribute(value) {
 
 const VIEW_EXTENSION_CACHE_SERVICE_TOKEN = 'XPERT_PLUGIN_VIEW_EXTENSION_CACHE_SERVICE';
 
-export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CommonParameterRules, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC, DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS, DEFAULT_SANDBOX_SHELL_TIMEOUT_MS, DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DefaultAgentMiddlewareRuntimeCapabilityRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, FILE_STORAGE_PROVIDER, FILE_UPLOAD_TARGET_STRATEGY, FileRuntimeCapability, FileStorageProvider, FileStorageProviderRegistry, FileUploadTargetRegistry, FileUploadTargetStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, KnowledgebaseRuntimeCapability, LLMUsage, LargeLanguageModel, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SKILL_SOURCE_PROVIDER, SSOProviderRegistry, SSOProviderStrategyKey, SSO_BINDING_PERMISSION_SERVICE_TOKEN, SSO_PROVIDER, STRATEGY_META_KEY, SandboxProviderRegistry, SandboxProviderStrategy, SkillSourceProviderRegistry, SkillSourceProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WrapWorkflowNodeExecutionCommand, XPERT_RUNTIME_CAPABILITIES_TOKEN, XpFileSystem, XpertServerPlugin, als, appendSandboxMessage, buildSandboxTimeoutMessage, calcTokenUsage, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, downloadRemoteFile, formatSandboxTimeout, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStructuredMessageType, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, renderRemoteReactIframeHtml, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, runWithRequestContext, secondsToMilliseconds, sumTokenUsage };
+export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CommonParameterRules, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC, DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS, DEFAULT_SANDBOX_SHELL_TIMEOUT_MS, DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DefaultAgentMiddlewareRuntimeCapabilityRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, FILE_STORAGE_PROVIDER, FILE_UPLOAD_TARGET_STRATEGY, FileRuntimeCapability, FileStorageProvider, FileStorageProviderRegistry, FileUploadTargetRegistry, FileUploadTargetStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, KnowledgebaseDocumentsRuntimeCapability, KnowledgebaseRuntimeCapability, LLMUsage, LargeLanguageModel, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, PluginWebhookAuth, PluginWebhookAuthGuard, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SKILL_SOURCE_PROVIDER, SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN, SPEECH_TO_TEXT_SERVICE_TOKEN, SSOProviderRegistry, SSOProviderStrategyKey, SSO_BINDING_PERMISSION_SERVICE_TOKEN, SSO_PROVIDER, STRATEGY_META_KEY, SandboxProviderRegistry, SandboxProviderStrategy, SkillSourceProviderRegistry, SkillSourceProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WrapWorkflowNodeExecutionCommand, XPERT_RUNTIME_CAPABILITIES_TOKEN, XpFileSystem, XpertServerPlugin, als, appendSandboxMessage, buildSandboxTimeoutMessage, calcTokenUsage, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, downloadRemoteFile, formatSandboxTimeout, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStructuredMessageType, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, renderRemoteReactIframeHtml, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, runWithRequestContext, secondsToMilliseconds, sumTokenUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.10.1",
+  "version": "3.12.0",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -16,11 +16,11 @@
     "directory": "dist"
   },
   "dependencies": {
+    "@xpert-ai/contracts": "workspace:*",
     "js-tiktoken": "^1.0.21"
   },
   "peerDependencies": {
     "@langchain/core": "*",
-    "@xpert-ai/contracts": "workspace:*",
     "@xpert-ai/ocap-core": "workspace:*",
     "@nestjs/common": "*",
     "@nestjs/core": "*",

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

@@ -1,3 +1,4 @@
 export * from './knowledgebase';
+export * from './knowledgebase-documents';
 export * from './assistant-task';
 export * from './file';

package/src/lib/agent/middleware/capabilities/knowledgebase-documents.d.ts

@@ -0,0 +1,121 @@
+import { JSONValue } from '@xpert-ai/contracts';
+export type AgentMiddlewareKnowledgebaseDocumentFile = {
+    buffer: Buffer;
+    originalname?: string;
+    mimetype?: string;
+    size?: number;
+};
+export type AgentMiddlewareKnowledgebaseDocumentMetadata = Record<string, JSONValue>;
+export type AgentMiddlewareKnowledgebaseDocumentParserConfig = Record<string, JSONValue>;
+export type AgentMiddlewareKnowledgebaseDocumentDraft = {
+    id?: string;
+    name?: string;
+    type?: string;
+    category?: string;
+    sourceType?: string;
+    sourceConfig?: Record<string, JSONValue>;
+    filePath?: string;
+    fileUrl?: string;
+    mimeType?: string;
+    size?: string | number;
+    parentId?: string;
+    parserConfig?: AgentMiddlewareKnowledgebaseDocumentParserConfig;
+    metadata?: AgentMiddlewareKnowledgebaseDocumentMetadata;
+};
+export type AgentMiddlewareKnowledgebaseDocumentRecord = {
+    id: string;
+    name?: string;
+    type?: string;
+    category?: string | null;
+    sourceType?: string | null;
+    filePath?: string;
+    fileUrl?: string;
+    mimeType?: string;
+    size?: string | number;
+    status?: string | null;
+    progress?: number | null;
+    processMsg?: string | null;
+    knowledgebaseId?: string;
+    metadata?: AgentMiddlewareKnowledgebaseDocumentMetadata;
+};
+export type AgentMiddlewareKnowledgebaseUploadFileInput = {
+    knowledgebaseId: string;
+    file: AgentMiddlewareKnowledgebaseDocumentFile;
+    path?: string;
+    parentId?: string;
+};
+export type AgentMiddlewareKnowledgebaseUploadedFile = {
+    name: string;
+    filePath: string;
+    fileUrl: string;
+    mimeType?: string;
+    size?: number;
+    sourceHash?: string;
+};
+export type AgentMiddlewareKnowledgebaseCreateDocumentsInput = {
+    knowledgebaseId: string;
+    documents: AgentMiddlewareKnowledgebaseDocumentDraft[];
+    parserConfig?: AgentMiddlewareKnowledgebaseDocumentParserConfig;
+    metadata?: AgentMiddlewareKnowledgebaseDocumentMetadata;
+    process?: boolean;
+};
+export type AgentMiddlewareKnowledgebaseCreateDocumentsResult = {
+    documents: AgentMiddlewareKnowledgebaseDocumentRecord[];
+    processingStarted?: boolean;
+};
+export type AgentMiddlewareKnowledgebaseImportArchiveInput = {
+    knowledgebaseId: string;
+    file: AgentMiddlewareKnowledgebaseDocumentFile;
+    path?: string;
+    parentId?: string;
+    packageId?: string;
+    packageCode?: string;
+    parserConfig?: AgentMiddlewareKnowledgebaseDocumentParserConfig;
+    metadata?: AgentMiddlewareKnowledgebaseDocumentMetadata;
+    process?: boolean;
+    maxEntries?: number;
+    maxEntrySizeBytes?: number;
+    maxDepth?: number;
+    supportedExtensions?: string[];
+};
+export type AgentMiddlewareKnowledgebaseImportArchiveResult = {
+    archive: AgentMiddlewareKnowledgebaseUploadedFile;
+    documents: AgentMiddlewareKnowledgebaseDocumentRecord[];
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+    warnings: string[];
+    processingStarted?: boolean;
+    unsupported?: boolean;
+};
+export type AgentMiddlewareKnowledgebaseStartProcessingInput = {
+    knowledgebaseId?: string;
+    documentIds: string[];
+};
+export type AgentMiddlewareKnowledgebaseDocumentStatusInput = {
+    knowledgebaseId?: string;
+    documentIds: string[];
+};
+export type AgentMiddlewareKnowledgebaseDocumentStatusResult = {
+    documents: AgentMiddlewareKnowledgebaseDocumentRecord[];
+};
+export type AgentMiddlewareKnowledgebaseDeleteDocumentsInput = {
+    knowledgebaseId?: string;
+    documentIds: string[];
+};
+export type AgentMiddlewareKnowledgebaseDeleteDocumentsResult = {
+    knowledgebaseId?: string;
+    documentIds: string[];
+    deletedDocumentCount: number;
+    missingDocumentIds?: string[];
+};
+export interface AgentMiddlewareKnowledgebaseDocumentsApi {
+    uploadFile(input: AgentMiddlewareKnowledgebaseUploadFileInput): Promise<AgentMiddlewareKnowledgebaseUploadedFile>;
+    importArchive(input: AgentMiddlewareKnowledgebaseImportArchiveInput): Promise<AgentMiddlewareKnowledgebaseImportArchiveResult>;
+    createDocuments(input: AgentMiddlewareKnowledgebaseCreateDocumentsInput): Promise<AgentMiddlewareKnowledgebaseCreateDocumentsResult>;
+    startProcessing(input: AgentMiddlewareKnowledgebaseStartProcessingInput): Promise<AgentMiddlewareKnowledgebaseDocumentStatusResult>;
+    getDocumentStatus(input: AgentMiddlewareKnowledgebaseDocumentStatusInput): Promise<AgentMiddlewareKnowledgebaseDocumentStatusResult>;
+    deleteDocuments(input: AgentMiddlewareKnowledgebaseDeleteDocumentsInput): Promise<AgentMiddlewareKnowledgebaseDeleteDocumentsResult>;
+}
+export declare const KnowledgebaseDocumentsRuntimeCapability: import("../runtime-capability").RuntimeCapabilityKey<AgentMiddlewareKnowledgebaseDocumentsApi>;

package/src/lib/agent/middleware/capabilities/knowledgebase.d.ts

@@ -21,6 +21,7 @@ export type AgentMiddlewareKnowledgebaseSearchInput = {
     requestId?: string;
 };
 export type AgentMiddlewareKnowledgebaseDocument = {
+    id?: string;
     pageContent: string;
     metadata?: Record<string, unknown>;
 };

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

@@ -7,3 +7,4 @@ export * from './utils';
 export * from './context/index';
 export * from './types';
 export * from './strategy-bus';
+export * from './webhook';

package/src/lib/core/permissions/general.d.ts

@@ -1,4 +1,5 @@
 import type { IIntegration, IPagination } from '@xpert-ai/contracts';
+import type { PluginWebhookCredentialResult } from '../webhook';
 /**
  * Base Permission type
  */
@@ -69,4 +70,14 @@ export declare const INTEGRATION_PERMISSION_SERVICE_TOKEN = "XPERT_PLUGIN_INTEGR
 export interface IntegrationPermissionService {
     read<TIntegration = IIntegration>(id: string, options?: Record<string, any>): Promise<TIntegration | null>;
     findAll<TIntegration = IIntegration>(options?: Record<string, any>): Promise<IPagination<TIntegration>>;
+    ensureWebhookCredential?(id: string, options?: {
+        provider?: string | null;
+        rotateIfRevoked?: boolean;
+    }): Promise<PluginWebhookCredentialResult | null>;
+    rotateWebhookCredential?(id: string, options?: {
+        provider?: string | null;
+    }): Promise<PluginWebhookCredentialResult | null>;
+    revokeWebhookCredential?(id: string, options?: {
+        provider?: string | null;
+    }): Promise<boolean>;
 }

package/src/lib/core/permissions/index.d.ts

@@ -14,17 +14,19 @@ export * from './auth-login';
 export * from './bound-identity-login';
 export * from './sso-binding';
 export * from './user';
+export * from './speech-to-text';
 import type { FileSystemPermission, IntegrationPermission, KnowledgePermission, LLMPermission, VectorStorePermission } from './general';
 import type { AnalyticsPermission } from './analytics';
 import type { AccountBindingPermission } from './account-binding';
 import type { BoundIdentityLoginPermission } from './bound-identity-login';
 import type { HandoffPermission } from './handoff';
+import type { SpeechToTextPermission } from './speech-to-text';
 import type { SsoBindingPermission } from './sso-binding';
 import type { UserPermission } from './user';
 /**
  * Union type for all permissions
  */
-export type Permission = LLMPermission | VectorStorePermission | KnowledgePermission | FileSystemPermission | IntegrationPermission | AnalyticsPermission | AccountBindingPermission | BoundIdentityLoginPermission | SsoBindingPermission | UserPermission | HandoffPermission;
+export type Permission = LLMPermission | VectorStorePermission | KnowledgePermission | FileSystemPermission | IntegrationPermission | AnalyticsPermission | AccountBindingPermission | BoundIdentityLoginPermission | SsoBindingPermission | UserPermission | HandoffPermission | SpeechToTextPermission;
 /**
  * Permissions array type
  */

package/src/lib/core/permissions/speech-to-text.d.ts

@@ -0,0 +1,41 @@
+export type SpeechToTextPermissionOperation = 'transcribe';
+/**
+ * Speech-to-text Permission
+ * Example: { type: 'speech_to_text', operations: ['transcribe'] }
+ */
+export interface SpeechToTextPermission {
+    type: 'speech_to_text';
+    operations?: SpeechToTextPermissionOperation[];
+    scope?: string[];
+    description?: string;
+}
+/**
+ * System token for resolving speech-to-text service from plugin context.
+ */
+export declare const SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN = "XPERT_PLUGIN_SPEECH_TO_TEXT_PERMISSION_SERVICE";
+/**
+ * Internal system token used by core to expose the speech-to-text bridge.
+ */
+export declare const SPEECH_TO_TEXT_SERVICE_TOKEN = "XPERT_SPEECH_TO_TEXT_SERVICE";
+export interface SpeechToTextTranscribeFileInput {
+    data: Uint8Array;
+    originalName: string;
+    mimeType?: string;
+    size?: number;
+}
+export interface SpeechToTextTranscribeInput {
+    xpertId: string;
+    isDraft?: boolean;
+    tenantId?: string | null;
+    organizationId?: string | null;
+    file: SpeechToTextTranscribeFileInput;
+}
+export interface SpeechToTextTranscribeResult {
+    text: string;
+}
+/**
+ * Speech-to-text service exposed to plugins under permission control.
+ */
+export interface SpeechToTextPermissionService {
+    transcribe(input: SpeechToTextTranscribeInput): Promise<SpeechToTextTranscribeResult>;
+}

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

@@ -0,0 +1,41 @@
+import type { IApiPrincipal } from '@xpert-ai/contracts';
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+export declare const PLUGIN_WEBHOOK_AUTH_METADATA_KEY = "xpert:plugin:webhook-auth";
+export declare const PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN = "XPERT_PLUGIN_WEBHOOK_AUTH_SERVICE";
+export type PluginWebhookAuthMetadata = {
+    provider?: string;
+    integrationParam?: string;
+    secretQueryParam?: string;
+};
+export type PluginWebhookCredentialRecord = {
+    id: string;
+    tokenHash: string;
+    tokenPrefix?: string;
+    createdAt: string;
+    rotatedAt?: string | null;
+    revokedAt?: string | null;
+};
+export type PluginWebhookCredentialResult = {
+    token: string;
+    credential: PluginWebhookCredentialRecord;
+};
+export type PluginWebhookAuthRequest = {
+    integrationId: string;
+    secret: string;
+    provider?: string | null;
+};
+export type PluginWebhookAuthResult = {
+    user: IApiPrincipal;
+    headers: Record<string, string>;
+};
+export interface PluginWebhookAuthService {
+    validateWebhookSecret(input: PluginWebhookAuthRequest): Promise<PluginWebhookAuthResult | null>;
+}
+export declare function PluginWebhookAuth(metadata?: PluginWebhookAuthMetadata): import("@nestjs/common").CustomDecorator<string>;
+export declare class PluginWebhookAuthGuard implements CanActivate {
+    private readonly authService?;
+    constructor(authService?: PluginWebhookAuthService | null);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private resolveMetadata;
+    private getString;
+}

package/src/lib/types.d.ts

@@ -1,4 +1,4 @@
-import { IconDefinition, JsonSchemaObjectType, PluginMeta, PluginTargetApp, PluginTargetAppMeta, TAvatar, XpertTypeEnum } from '@xpert-ai/contracts';
+import { IconDefinition, JsonSchemaObjectType, PluginMeta, PluginTargetApp, PluginTargetAppMeta, TAvatar, XpertTemplatePluginDependencies, XpertTypeEnum } from '@xpert-ai/contracts';
 import type { DynamicModule, INestApplicationContext } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import type { ZodSchema } from 'zod';
@@ -68,6 +68,7 @@ export interface XpertTemplateContribution {
     startPrompts?: string[];
     releaseNotes?: string;
     xpertName?: string;
+    dependencies?: XpertTemplatePluginDependencies;
     [key: string]: unknown;
 }
 export interface XpertTemplateProvider {

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

@@ -1,6 +1,9 @@
-import { Runnable } from '@langchain/core/runnables';
+import { Runnable, RunnableToolLike } from '@langchain/core/runnables';
+import { DynamicStructuredTool, StructuredToolInterface } from '@langchain/core/tools';
+import { ToolInputSchemaBase } from '@langchain/core/dist/tools/types';
+import { InteropZodType } from '@langchain/core/utils/types';
 import { BaseChannel } from '@langchain/langgraph';
-import { IEnvironment, IWorkflowNode, TWorkflowNodeMeta, TXpertGraph, TWorkflowVarGroup, TXpertParameter, TXpertTeamNode } from '@xpert-ai/contracts';
+import { IEnvironment, IWorkflowNode, TWorkflowNodeMeta, TVariableAssigner, TXpertGraph, TWorkflowVarGroup, TXpertParameter, TXpertTeamNode } from '@xpert-ai/contracts';
 import { PromiseOrValue } from '../../types';
 export type TWorkflowNodeParams<TConfig = any> = {
     xpertId: string;
@@ -17,6 +20,14 @@ export type TWorkflowNodeResult = {
         annotation: BaseChannel;
     };
     navigator?: (state: any, config: any) => Promise<any>;
+    caller?: string;
+    toolset?: {
+        provider: string;
+        title: string;
+        id?: string;
+    };
+    tool?: DynamicStructuredTool<ToolInputSchemaBase, any, any> | StructuredToolInterface<ToolInputSchemaBase, any, any> | RunnableToolLike<InteropZodType, unknown>;
+    variables?: TVariableAssigner[];
 };
 /**
  * Workflow Node Strategy interface
@@ -37,6 +48,8 @@ export interface IWorkflowNodeStrategy<TConfig = any, TResult = any> {
         xpertId: string;
         environment: IEnvironment;
         isDraft: boolean;
+        leaderKey?: string;
+        conversationId?: string;
     }): PromiseOrValue<TWorkflowNodeResult>;
     inputVariables?(entity: IWorkflowNode, variables?: TWorkflowVarGroup[]): TXpertParameter[];
     outputVariables(entity: IWorkflowNode): TXpertParameter[];