@xpert-ai/plugin-sdk 3.20.0 → 3.21.1

package/index.esm.js

@@ -16,7 +16,7 @@ import fs__default from 'fs';
 import http from 'http';
 import https from 'https';
 import { c as createRuntimeCapability, B as BuiltinToolset, W as WorkspaceFilesRuntimeCapability } from './model-provider.esm.js';
-export { A as ActorTokenRuntimeCapability, a as ActorTokenRuntimeFactoryCapability, b as ArtifactsRuntimeCapability, d as BaseTool, e as BaseToolset, D as DefaultAgentMiddlewareRuntimeCapabilityRegistry, D as DefaultRuntimeCapabilityRegistry, K as KnowledgeDocumentVisualAssetsRuntimeCapability, f as KnowledgeDocumentVisualAssetsRuntimeFactoryCapability, g as KnowledgeGraphRuntimeCapability, h as KnowledgebaseDocumentsRuntimeCapability, i as KnowledgebaseProvisioningRuntimeCapability, j as KnowledgebaseRuntimeCapability, M as ModelProviderBuiltinToolset, P as ProjectAccessRuntimeCapability, k as ProjectProvisioningRuntimeCapability, R as RUNTIME_CAPABILITY_PROVIDER, l as RuntimeCapabilityProvider, S as SANDBOX_JOB_ERROR_CODES, m as SANDBOX_JOB_PROGRESS_PREFIX, n as SandboxJobRuntimeError, o as SandboxJobsRuntimeCapability, T as ToolImagesRuntimeCapability, p as WORKSPACE_FILES_SOURCE, X as XPERT_RUNTIME_CAPABILITIES_TOKEN, q as isSandboxJobRuntimeError } from './model-provider.esm.js';
+export { A as ActorTokenRuntimeCapability, a as ActorTokenRuntimeFactoryCapability, b as ArtifactsRuntimeCapability, d as BaseTool, e as BaseToolset, D as DefaultAgentMiddlewareRuntimeCapabilityRegistry, D as DefaultRuntimeCapabilityRegistry, M as ModelProviderBuiltinToolset, P as ProjectAccessRuntimeCapability, f as ProjectProvisioningRuntimeCapability, R as RUNTIME_CAPABILITY_PROVIDER, g as RuntimeCapabilityProvider, S as SANDBOX_JOB_ERROR_CODES, h as SANDBOX_JOB_PROGRESS_PREFIX, i as SandboxJobRuntimeError, j as SandboxJobsRuntimeCapability, T as ToolImagesRuntimeCapability, k as WORKSPACE_FILES_SOURCE, X as XPERT_RUNTIME_CAPABILITIES_TOKEN, l as isSandboxJobRuntimeError } from './model-provider.esm.js';
 import fsPromises from 'fs/promises';
 import * as path from 'path';
 import path__default, { join } from 'path';
@@ -182,14 +182,15 @@ class RequestContext {
         const session = getRequestContext();
         return session;
     }
-    static currentApiKey() {
+    /** @deprecated For resource authorization use currentApiPrincipal()?.resourceScope; retained for credential metadata. */ static currentApiKey() {
         var _RequestContext_currentApiPrincipal;
         var _RequestContext_currentApiPrincipal_apiKey;
         return (_RequestContext_currentApiPrincipal_apiKey = (_RequestContext_currentApiPrincipal = RequestContext.currentApiPrincipal()) == null ? void 0 : _RequestContext_currentApiPrincipal.apiKey) != null ? _RequestContext_currentApiPrincipal_apiKey : null;
     }
     static currentApiPrincipal() {
         const user = RequestContext.currentUser();
-        return (user == null ? void 0 : user.apiKey) ? user : null;
+        // Conversation-scoped client secrets carry no synthetic API key.
+        return (user == null ? void 0 : user.apiKey) || (user == null ? void 0 : user.principalType) === 'client_secret' || (user == null ? void 0 : user.principalType) === 'api_key' ? user : null;
     }
     static currentRequest() {
         const requestContext = RequestContext.currentRequestContext();
@@ -1104,6 +1105,41 @@ KeywordAnalyzerRegistry = __decorate([
     ])
 ], KeywordAnalyzerRegistry);
 
+const KnowledgebaseRuntimeCapability = createRuntimeCapability('platform.knowledgebase', {
+    description: 'List, search, and write chunks in platform knowledgebases.'
+});
+const KnowledgebaseProvisioningRuntimeCapability = createRuntimeCapability('platform.knowledgebase.provisioning', {
+    description: 'Idempotently provision managed platform knowledgebases and connect them to an Agent.'
+});
+
+/** Knowledgebase discovery is scoped to the authenticated runtime, never caller-supplied identities. */ const knowledgebaseActions = [
+    'knowledgebase.read',
+    'knowledgebase.manage',
+    'content.search',
+    'documents.read',
+    'documents.create',
+    'documents.update',
+    'documents.delete',
+    'documents.process',
+    'chunks.write',
+    'chunks.delete'
+];
+
+const KnowledgeGraphRuntimeCapability = createRuntimeCapability('platform.knowledge-graph', {
+    description: 'Publish, inspect, and retract source-owned structured knowledge graphs without model extraction.'
+});
+
+const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
+    description: 'Upload, import, create, process, reprocess, inspect, and delete persistent knowledgebase documents.'
+});
+
+const KnowledgeDocumentVisualAssetsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.visual-assets', {
+    description: 'Issue execution-scoped logical KnowledgeDocument image paths and inject validated images without exposing host storage paths.'
+});
+const KnowledgeDocumentVisualAssetsRuntimeFactoryCapability = createRuntimeCapability('platform.knowledge-document.visual-assets.factory', {
+    description: 'Create a visual-assets API with an execution-local image allow-list and authorized workspace writer.'
+});
+
 const TOOLSET_STRATEGY = 'TOOLSET_STRATEGY';
 /**
  * Decorator to mark a provider as a Toolset Strategy
@@ -10102,4 +10138,11 @@ const ProjectTasksRuntimeCapability = createRuntimeCapability('platform.project.
     description: 'Read project task graphs, manage schedules, and resolve exact execution conversations.'
 });
 
-export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_ERROR_STEER_TARGET_NOT_RUNNING, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AGENT_RUNTIME_EVENT_MESSAGE_TYPE, AGENT_RUNTIME_STRATEGY, AIModel, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ASSISTANT_CAPABILITY_PROVIDER, AdapterDataSourceStrategy, AgentExecutionRunnerCapability, AgentExecutionRunnerFactoryCapability, AgentInvocationRuntimeCapability, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AgentRuntimeFactoryCapability, AgentRuntimeRegistry, AgentRuntimeStrategy, AiModelNotFoundException, AssistantCapabilityProvider, AssistantCapabilityProviderRegistry, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CLI_MODEL_TOKEN_REFERENCE, COLLABORATION_DOCUMENT_PROVIDER, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CliModelProfilesCapability, CollaborationDocumentProvider, CollaborationDocumentProviderRegistry, CollaborationRuntimeCapability, CommonParameterRules, ConnectorRuntimeCapability, ConnectorRuntimeFactoryCapability, ConnectorStrategyKey, ConnectorStrategyRegistry, 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, DecoratedAgentMiddlewareStrategy, DecoratedToolsetStrategy, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, EVOLUTION_RUNTIME_SERVICE_TOKEN, EVOLUTION_TARGET_PROVIDER, EvolutionBaselineRuntimeCapability, EvolutionChangeRuntimeCapability, EvolutionRuntimeCapability, EvolutionTargetProviderRegistry, EvolutionTargetProviderStrategy, 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, ImageGenerationModel, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KEYWORD_ANALYZER_STRATEGY, KNOWLEDGE_STRATEGY, KeywordAnalyzerRegistry, KeywordAnalyzerStrategy, KnowledgeStrategyKey, KnowledgeStrategyRegistry, LLMUsage, LargeLanguageModel, MANAGED_CONNECTION_REGISTRY_TOKEN, MANAGED_QUEUE_HANDLER_REGISTRY_TOKEN, MANAGED_QUEUE_SERVICE_TOKEN, MCP_CAPABILITY_CHANGE_EVENT_TYPES, MODEL_OUTPUT_VALIDATION_ERROR_CODE, ModelExecutionEnvironmentCapability, ModelOutputValidationError, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_JOB_PROCESSOR_METADATA, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PLUGIN_VERSION_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN, PROJECT_TASK_PROVIDER, PROJECT_TYPE_PROVIDER, 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, PluginJobProcessor, PluginWebhookAuth, PluginWebhookAuthGuard, ProjectTaskProvider, ProjectTaskProviderRegistry, ProjectTasksRuntimeCapability, ProjectTypeProvider, ProjectTypeProviderRegistry, RESOURCE_CARD_EVENT, RESOURCE_CARD_PROVIDER, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, ResourceCardProvider, ResourceCardProviderRegistry, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_RUNTIME_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SANDBOX_WORKSPACE_MAPPER, 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, SYSTEM_GLOBAL_SCOPE, SandboxProviderRegistry, SandboxProviderStrategy, SandboxRuntimeProviderRegistry, SandboxRuntimeProviderStrategy, SandboxWorkspaceMapperRegistry, SandboxWorkspaceMapperStrategy, ShellModelExecutionSourceCapability, SkillSourceProviderRegistry, SkillSourceProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TENANT_GLOBAL_SCOPE_PREFIX, TENANT_GLOBAL_SCOPE_SUFFIX, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VIDEO_GENERATION_PERMISSION_SERVICE_TOKEN, VIDEO_GENERATION_SERVICE_TOKEN, VIDEO_GENERATOR_FAMILIES, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, VideoGenerationModel, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WorkspaceFilesRuntimeCapability, WrapWorkflowNodeExecutionCommand, XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN, XPERT_TOOL_METHOD_METADATA, XPERT_TOOL_PROVIDER, XPERT_TOOL_PROVIDER_METADATA, XPERT_TOOL_RESULT_FORMAT_VERSION, XpFileSystem, XpertPrompt, XpertResource, XpertResourceTemplate, XpertServerPlugin, XpertTool, XpertToolProvider, XpertToolProviderCoordinator, XpertToolProviderRegistry, agentInvocationDispatchContextSchema, agentRuntimeConsumptionStateSchema, agentRuntimeDeliveryStateSchema, agentRuntimeEventMessageId, agentRuntimeEventSchema, agentRuntimeReplyTargetSchema, agentRuntimeResultClaimSchema, agentRuntimeResultConsumptionKey, als, appendSandboxMessage, assertConnectorDefinition, buildSandboxTimeoutMessage, calcTokenUsage, calculateLLMUsagePrice, calculateModelPrice, calculateModelUsageCharge, chunkText, countTextTokens, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, defineMcpApp, defineMcpCapabilities, defineMcpPrompt, defineMcpResource, defineMcpResourceTemplate, defineXpertTool, derivePluginArtifactNamespace, describeXpertToolProvider, downloadRemoteFile, emitResourceCard, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, getXpertToolMethod, isAgentInvocationTerminal, isDevelopmentSandboxRuntimeEnvironment, isModelOutputValidationError, isModelUsagePricingConfig, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStrategyInstance, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeModelRequirements, mergeParentChildChunks, nativeModelTransport, normalizeContextSize, normalizeTokenUsage, pluginArtifactTableName, prepareToolResult, processAsyncAIGCManagedJob, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, resolveModelUsagePricingSnapshot, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveStrategyMetadataTarget, resolveTenantGlobalScopeKey, resolveTokenUsage, resolveTokenUsageCandidates, resolveXpertMcpExtensions, runWithRequestContext, runtimeToolProviderComponent, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage, taskWaitReason, textTokenBoundaries };
+/** Import official resource packages for the authenticated organization administrator. Does not authorize workspaces. */ class ImportDefaultAgentPluginsCommand extends Command {
+}
+ImportDefaultAgentPluginsCommand.type = '[Agent Plugins] Import defaults';
+Reflect.defineMetadata('__command__', {
+    id: ImportDefaultAgentPluginsCommand.type
+}, ImportDefaultAgentPluginsCommand);
+
+export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_ERROR_STEER_TARGET_NOT_RUNNING, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AGENT_RUNTIME_EVENT_MESSAGE_TYPE, AGENT_RUNTIME_STRATEGY, AIModel, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ASSISTANT_CAPABILITY_PROVIDER, AdapterDataSourceStrategy, AgentExecutionRunnerCapability, AgentExecutionRunnerFactoryCapability, AgentInvocationRuntimeCapability, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AgentRuntimeFactoryCapability, AgentRuntimeRegistry, AgentRuntimeStrategy, AiModelNotFoundException, AssistantCapabilityProvider, AssistantCapabilityProviderRegistry, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CLI_MODEL_TOKEN_REFERENCE, COLLABORATION_DOCUMENT_PROVIDER, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CliModelProfilesCapability, CollaborationDocumentProvider, CollaborationDocumentProviderRegistry, CollaborationRuntimeCapability, CommonParameterRules, ConnectorRuntimeCapability, ConnectorRuntimeFactoryCapability, ConnectorStrategyKey, ConnectorStrategyRegistry, 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, DecoratedAgentMiddlewareStrategy, DecoratedToolsetStrategy, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, EVOLUTION_RUNTIME_SERVICE_TOKEN, EVOLUTION_TARGET_PROVIDER, EvolutionBaselineRuntimeCapability, EvolutionChangeRuntimeCapability, EvolutionRuntimeCapability, EvolutionTargetProviderRegistry, EvolutionTargetProviderStrategy, 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, ImageGenerationModel, ImageUnderstandingRegistry, ImageUnderstandingStrategy, ImportDefaultAgentPluginsCommand, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KEYWORD_ANALYZER_STRATEGY, KNOWLEDGE_STRATEGY, KeywordAnalyzerRegistry, KeywordAnalyzerStrategy, KnowledgeDocumentVisualAssetsRuntimeCapability, KnowledgeDocumentVisualAssetsRuntimeFactoryCapability, KnowledgeGraphRuntimeCapability, KnowledgeStrategyKey, KnowledgeStrategyRegistry, KnowledgebaseDocumentsRuntimeCapability, KnowledgebaseProvisioningRuntimeCapability, KnowledgebaseRuntimeCapability, LLMUsage, LargeLanguageModel, MANAGED_CONNECTION_REGISTRY_TOKEN, MANAGED_QUEUE_HANDLER_REGISTRY_TOKEN, MANAGED_QUEUE_SERVICE_TOKEN, MCP_CAPABILITY_CHANGE_EVENT_TYPES, MODEL_OUTPUT_VALIDATION_ERROR_CODE, ModelExecutionEnvironmentCapability, ModelOutputValidationError, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_JOB_PROCESSOR_METADATA, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PLUGIN_VERSION_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN, PROJECT_TASK_PROVIDER, PROJECT_TYPE_PROVIDER, 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, PluginJobProcessor, PluginWebhookAuth, PluginWebhookAuthGuard, ProjectTaskProvider, ProjectTaskProviderRegistry, ProjectTasksRuntimeCapability, ProjectTypeProvider, ProjectTypeProviderRegistry, RESOURCE_CARD_EVENT, RESOURCE_CARD_PROVIDER, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, ResourceCardProvider, ResourceCardProviderRegistry, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_RUNTIME_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SANDBOX_WORKSPACE_MAPPER, 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, SYSTEM_GLOBAL_SCOPE, SandboxProviderRegistry, SandboxProviderStrategy, SandboxRuntimeProviderRegistry, SandboxRuntimeProviderStrategy, SandboxWorkspaceMapperRegistry, SandboxWorkspaceMapperStrategy, ShellModelExecutionSourceCapability, SkillSourceProviderRegistry, SkillSourceProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TENANT_GLOBAL_SCOPE_PREFIX, TENANT_GLOBAL_SCOPE_SUFFIX, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VIDEO_GENERATION_PERMISSION_SERVICE_TOKEN, VIDEO_GENERATION_SERVICE_TOKEN, VIDEO_GENERATOR_FAMILIES, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, VideoGenerationModel, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WorkspaceFilesRuntimeCapability, WrapWorkflowNodeExecutionCommand, XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN, XPERT_TOOL_METHOD_METADATA, XPERT_TOOL_PROVIDER, XPERT_TOOL_PROVIDER_METADATA, XPERT_TOOL_RESULT_FORMAT_VERSION, XpFileSystem, XpertPrompt, XpertResource, XpertResourceTemplate, XpertServerPlugin, XpertTool, XpertToolProvider, XpertToolProviderCoordinator, XpertToolProviderRegistry, agentInvocationDispatchContextSchema, agentRuntimeConsumptionStateSchema, agentRuntimeDeliveryStateSchema, agentRuntimeEventMessageId, agentRuntimeEventSchema, agentRuntimeReplyTargetSchema, agentRuntimeResultClaimSchema, agentRuntimeResultConsumptionKey, als, appendSandboxMessage, assertConnectorDefinition, buildSandboxTimeoutMessage, calcTokenUsage, calculateLLMUsagePrice, calculateModelPrice, calculateModelUsageCharge, chunkText, countTextTokens, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, defineMcpApp, defineMcpCapabilities, defineMcpPrompt, defineMcpResource, defineMcpResourceTemplate, defineXpertTool, derivePluginArtifactNamespace, describeXpertToolProvider, downloadRemoteFile, emitResourceCard, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, getXpertToolMethod, isAgentInvocationTerminal, isDevelopmentSandboxRuntimeEnvironment, isModelOutputValidationError, isModelUsagePricingConfig, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStrategyInstance, isStructuredMessageType, isTenantGlobalScopeKey, knowledgebaseActions, loadYamlFile, mergeCredentials, mergeModelRequirements, mergeParentChildChunks, nativeModelTransport, normalizeContextSize, normalizeTokenUsage, pluginArtifactTableName, prepareToolResult, processAsyncAIGCManagedJob, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, resolveModelUsagePricingSnapshot, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveStrategyMetadataTarget, resolveTenantGlobalScopeKey, resolveTokenUsage, resolveTokenUsageCandidates, resolveXpertMcpExtensions, runWithRequestContext, runtimeToolProviderComponent, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage, taskWaitReason, textTokenBoundaries };

package/model-provider.cjs.js

@@ -6,6 +6,46 @@ var common = require('@nestjs/common');
 var tools = require('@langchain/core/tools');
 var v3 = require('zod/v3');
 
+function createRuntimeCapability(id, options = {}) {
+    return Object.freeze({
+        id,
+        description: options.description
+    });
+}
+const XPERT_RUNTIME_CAPABILITIES_TOKEN = 'XPERT_RUNTIME_CAPABILITIES';
+/** Metadata key under which RuntimeCapabilityProviderExplorer discovers capability providers. */ const RUNTIME_CAPABILITY_PROVIDER = 'XPERT_RUNTIME_CAPABILITY_PROVIDER';
+/** Tags a Nest provider as the platform implementation of a runtime capability. */ const RuntimeCapabilityProvider = (capability)=>common.SetMetadata(RUNTIME_CAPABILITY_PROVIDER, capability);
+class DefaultRuntimeCapabilityRegistry {
+    register(key, implementation) {
+        this.capabilities.set(runtimeCapabilityId(key), implementation);
+        return this;
+    }
+    has(key) {
+        var _this_parent;
+        return this.capabilities.has(runtimeCapabilityId(key)) || ((_this_parent = this.parent) == null ? void 0 : _this_parent.get(key)) !== undefined;
+    }
+    get(key) {
+        var _this_parent;
+        const id = runtimeCapabilityId(key);
+        return this.capabilities.has(id) ? this.capabilities.get(id) : (_this_parent = this.parent) == null ? void 0 : _this_parent.get(key);
+    }
+    require(key) {
+        const implementation = this.get(key);
+        if (!implementation) {
+            throw new Error(`Runtime capability '${runtimeCapabilityId(key)}' is not available`);
+        }
+        return implementation;
+    }
+    constructor(entries = [], parent){
+        this.capabilities = new Map();
+        this.parent = parent;
+        entries.forEach(([key, implementation])=>this.register(key, implementation));
+    }
+}
+function runtimeCapabilityId(key) {
+    return typeof key === 'string' ? key : key.id;
+}
+
 /**
  * Base ability for all toolsets
  */ class BaseToolset extends tools.BaseToolkit {
@@ -147,68 +187,6 @@ class BuiltinToolset extends BaseToolset {
 } 
 BuiltinToolset.provider = '';
 
-function createRuntimeCapability(id, options = {}) {
-    return Object.freeze({
-        id,
-        description: options.description
-    });
-}
-const XPERT_RUNTIME_CAPABILITIES_TOKEN = 'XPERT_RUNTIME_CAPABILITIES';
-/** Metadata key under which RuntimeCapabilityProviderExplorer discovers capability providers. */ const RUNTIME_CAPABILITY_PROVIDER = 'XPERT_RUNTIME_CAPABILITY_PROVIDER';
-/** Tags a Nest provider as the platform implementation of a runtime capability. */ const RuntimeCapabilityProvider = (capability)=>common.SetMetadata(RUNTIME_CAPABILITY_PROVIDER, capability);
-class DefaultRuntimeCapabilityRegistry {
-    register(key, implementation) {
-        this.capabilities.set(runtimeCapabilityId(key), implementation);
-        return this;
-    }
-    has(key) {
-        var _this_parent;
-        return this.capabilities.has(runtimeCapabilityId(key)) || ((_this_parent = this.parent) == null ? void 0 : _this_parent.get(key)) !== undefined;
-    }
-    get(key) {
-        var _this_parent;
-        const id = runtimeCapabilityId(key);
-        return this.capabilities.has(id) ? this.capabilities.get(id) : (_this_parent = this.parent) == null ? void 0 : _this_parent.get(key);
-    }
-    require(key) {
-        const implementation = this.get(key);
-        if (!implementation) {
-            throw new Error(`Runtime capability '${runtimeCapabilityId(key)}' is not available`);
-        }
-        return implementation;
-    }
-    constructor(entries = [], parent){
-        this.capabilities = new Map();
-        this.parent = parent;
-        entries.forEach(([key, implementation])=>this.register(key, implementation));
-    }
-}
-function runtimeCapabilityId(key) {
-    return typeof key === 'string' ? key : key.id;
-}
-
-const KnowledgebaseRuntimeCapability = createRuntimeCapability('platform.knowledgebase', {
-    description: 'List, search, and write chunks in platform knowledgebases.'
-});
-const KnowledgebaseProvisioningRuntimeCapability = createRuntimeCapability('platform.knowledgebase.provisioning', {
-    description: 'Idempotently provision managed platform knowledgebases and connect them to an Agent.'
-});
-
-const KnowledgeGraphRuntimeCapability = createRuntimeCapability('platform.knowledge-graph', {
-    description: 'Publish, inspect, and retract source-owned structured knowledge graphs without model extraction.'
-});
-
-const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
-    description: 'Upload, import, create, process, reprocess, inspect, and delete persistent knowledgebase documents.'
-});
-
-const KnowledgeDocumentVisualAssetsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.visual-assets', {
-    description: 'Issue execution-scoped logical KnowledgeDocument image paths and inject validated images without exposing host storage paths.'
-});
-const KnowledgeDocumentVisualAssetsRuntimeFactoryCapability = createRuntimeCapability('platform.knowledge-document.visual-assets.factory', {
-    description: 'Create a visual-assets API with an execution-local image allow-list and authorized workspace writer.'
-});
-
 const ActorTokenRuntimeCapability = createRuntimeCapability('platform.actor-token', {
     description: 'Mint a short-lived host-issued actor bearer token for outbound API calls.'
 });
@@ -397,12 +375,6 @@ exports.BaseTool = BaseTool;
 exports.BaseToolset = BaseToolset;
 exports.BuiltinToolset = BuiltinToolset;
 exports.DefaultRuntimeCapabilityRegistry = DefaultRuntimeCapabilityRegistry;
-exports.KnowledgeDocumentVisualAssetsRuntimeCapability = KnowledgeDocumentVisualAssetsRuntimeCapability;
-exports.KnowledgeDocumentVisualAssetsRuntimeFactoryCapability = KnowledgeDocumentVisualAssetsRuntimeFactoryCapability;
-exports.KnowledgeGraphRuntimeCapability = KnowledgeGraphRuntimeCapability;
-exports.KnowledgebaseDocumentsRuntimeCapability = KnowledgebaseDocumentsRuntimeCapability;
-exports.KnowledgebaseProvisioningRuntimeCapability = KnowledgebaseProvisioningRuntimeCapability;
-exports.KnowledgebaseRuntimeCapability = KnowledgebaseRuntimeCapability;
 exports.ModelProviderBuiltinToolset = ModelProviderBuiltinToolset;
 exports.ProjectAccessRuntimeCapability = ProjectAccessRuntimeCapability;
 exports.ProjectProvisioningRuntimeCapability = ProjectProvisioningRuntimeCapability;

package/model-provider.esm.js

@@ -1,9 +1,49 @@
 import { _ as _extends } from './_extends.esm.js';
 import { AiModelTypeEnum } from '@xpert-ai/contracts';
-import { Logger, SetMetadata } from '@nestjs/common';
+import { SetMetadata, Logger } from '@nestjs/common';
 import { BaseToolkit, StructuredTool } from '@langchain/core/tools';
 import { z } from 'zod/v3';
 
+function createRuntimeCapability(id, options = {}) {
+    return Object.freeze({
+        id,
+        description: options.description
+    });
+}
+const XPERT_RUNTIME_CAPABILITIES_TOKEN = 'XPERT_RUNTIME_CAPABILITIES';
+/** Metadata key under which RuntimeCapabilityProviderExplorer discovers capability providers. */ const RUNTIME_CAPABILITY_PROVIDER = 'XPERT_RUNTIME_CAPABILITY_PROVIDER';
+/** Tags a Nest provider as the platform implementation of a runtime capability. */ const RuntimeCapabilityProvider = (capability)=>SetMetadata(RUNTIME_CAPABILITY_PROVIDER, capability);
+class DefaultRuntimeCapabilityRegistry {
+    register(key, implementation) {
+        this.capabilities.set(runtimeCapabilityId(key), implementation);
+        return this;
+    }
+    has(key) {
+        var _this_parent;
+        return this.capabilities.has(runtimeCapabilityId(key)) || ((_this_parent = this.parent) == null ? void 0 : _this_parent.get(key)) !== undefined;
+    }
+    get(key) {
+        var _this_parent;
+        const id = runtimeCapabilityId(key);
+        return this.capabilities.has(id) ? this.capabilities.get(id) : (_this_parent = this.parent) == null ? void 0 : _this_parent.get(key);
+    }
+    require(key) {
+        const implementation = this.get(key);
+        if (!implementation) {
+            throw new Error(`Runtime capability '${runtimeCapabilityId(key)}' is not available`);
+        }
+        return implementation;
+    }
+    constructor(entries = [], parent){
+        this.capabilities = new Map();
+        this.parent = parent;
+        entries.forEach(([key, implementation])=>this.register(key, implementation));
+    }
+}
+function runtimeCapabilityId(key) {
+    return typeof key === 'string' ? key : key.id;
+}
+
 /**
  * Base ability for all toolsets
  */ class BaseToolset extends BaseToolkit {
@@ -145,68 +185,6 @@ class BuiltinToolset extends BaseToolset {
 } 
 BuiltinToolset.provider = '';
 
-function createRuntimeCapability(id, options = {}) {
-    return Object.freeze({
-        id,
-        description: options.description
-    });
-}
-const XPERT_RUNTIME_CAPABILITIES_TOKEN = 'XPERT_RUNTIME_CAPABILITIES';
-/** Metadata key under which RuntimeCapabilityProviderExplorer discovers capability providers. */ const RUNTIME_CAPABILITY_PROVIDER = 'XPERT_RUNTIME_CAPABILITY_PROVIDER';
-/** Tags a Nest provider as the platform implementation of a runtime capability. */ const RuntimeCapabilityProvider = (capability)=>SetMetadata(RUNTIME_CAPABILITY_PROVIDER, capability);
-class DefaultRuntimeCapabilityRegistry {
-    register(key, implementation) {
-        this.capabilities.set(runtimeCapabilityId(key), implementation);
-        return this;
-    }
-    has(key) {
-        var _this_parent;
-        return this.capabilities.has(runtimeCapabilityId(key)) || ((_this_parent = this.parent) == null ? void 0 : _this_parent.get(key)) !== undefined;
-    }
-    get(key) {
-        var _this_parent;
-        const id = runtimeCapabilityId(key);
-        return this.capabilities.has(id) ? this.capabilities.get(id) : (_this_parent = this.parent) == null ? void 0 : _this_parent.get(key);
-    }
-    require(key) {
-        const implementation = this.get(key);
-        if (!implementation) {
-            throw new Error(`Runtime capability '${runtimeCapabilityId(key)}' is not available`);
-        }
-        return implementation;
-    }
-    constructor(entries = [], parent){
-        this.capabilities = new Map();
-        this.parent = parent;
-        entries.forEach(([key, implementation])=>this.register(key, implementation));
-    }
-}
-function runtimeCapabilityId(key) {
-    return typeof key === 'string' ? key : key.id;
-}
-
-const KnowledgebaseRuntimeCapability = createRuntimeCapability('platform.knowledgebase', {
-    description: 'List, search, and write chunks in platform knowledgebases.'
-});
-const KnowledgebaseProvisioningRuntimeCapability = createRuntimeCapability('platform.knowledgebase.provisioning', {
-    description: 'Idempotently provision managed platform knowledgebases and connect them to an Agent.'
-});
-
-const KnowledgeGraphRuntimeCapability = createRuntimeCapability('platform.knowledge-graph', {
-    description: 'Publish, inspect, and retract source-owned structured knowledge graphs without model extraction.'
-});
-
-const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
-    description: 'Upload, import, create, process, reprocess, inspect, and delete persistent knowledgebase documents.'
-});
-
-const KnowledgeDocumentVisualAssetsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.visual-assets', {
-    description: 'Issue execution-scoped logical KnowledgeDocument image paths and inject validated images without exposing host storage paths.'
-});
-const KnowledgeDocumentVisualAssetsRuntimeFactoryCapability = createRuntimeCapability('platform.knowledge-document.visual-assets.factory', {
-    description: 'Create a visual-assets API with an execution-local image allow-list and authorized workspace writer.'
-});
-
 const ActorTokenRuntimeCapability = createRuntimeCapability('platform.actor-token', {
     description: 'Mint a short-lived host-issued actor bearer token for outbound API calls.'
 });
@@ -388,4 +366,4 @@ function normalizeWorkspaceScope(scope) {
     } : {});
 }
 
-export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, RUNTIME_CAPABILITY_PROVIDER as R, SANDBOX_JOB_ERROR_CODES as S, ToolImagesRuntimeCapability as T, WorkspaceFilesRuntimeCapability as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ActorTokenRuntimeFactoryCapability as a, ArtifactsRuntimeCapability as b, createRuntimeCapability as c, BaseTool as d, BaseToolset as e, KnowledgeDocumentVisualAssetsRuntimeFactoryCapability as f, KnowledgeGraphRuntimeCapability as g, KnowledgebaseDocumentsRuntimeCapability as h, KnowledgebaseProvisioningRuntimeCapability as i, KnowledgebaseRuntimeCapability as j, ProjectProvisioningRuntimeCapability as k, RuntimeCapabilityProvider as l, SANDBOX_JOB_PROGRESS_PREFIX as m, SandboxJobRuntimeError as n, SandboxJobsRuntimeCapability as o, WORKSPACE_FILES_SOURCE as p, isSandboxJobRuntimeError as q };
+export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, RUNTIME_CAPABILITY_PROVIDER as R, SANDBOX_JOB_ERROR_CODES as S, ToolImagesRuntimeCapability as T, WorkspaceFilesRuntimeCapability as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ActorTokenRuntimeFactoryCapability as a, ArtifactsRuntimeCapability as b, createRuntimeCapability as c, BaseTool as d, BaseToolset as e, ProjectProvisioningRuntimeCapability as f, RuntimeCapabilityProvider as g, SANDBOX_JOB_PROGRESS_PREFIX as h, SandboxJobRuntimeError as i, SandboxJobsRuntimeCapability as j, WORKSPACE_FILES_SOURCE as k, isSandboxJobRuntimeError as l };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.20.0",
+  "version": "3.21.1",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.20.0",
+    "@xpert-ai/contracts": "3.21.0",
     "express": "^4.22.1",
     "js-tiktoken": "^1.0.21"
   },

package/src/index.d.ts

@@ -32,3 +32,4 @@ export * from './lib/mcp/index';
 export * from './lib/tool-provider/index';
 export * from './lib/project-type/index';
 export * from './lib/project-task/index';
+export * from './lib/agent-plugin/import-default-agent-plugins.command';

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

@@ -3,6 +3,8 @@ export declare const AGENT_CHAT_DISPATCH_MESSAGE_TYPE: import("./message-type").
 export declare const AGENT_CHAT_DISPATCH_ERROR_STEER_TARGET_NOT_RUNNING = "steer_target_not_running";
 export interface AgentChatHandoffMessageCallbackTarget {
     transport?: 'handoff-message';
+    /** Defaults to all events; lifecycle emits only terminal callbacks, leaving tokens in the run stream. */
+    events?: 'all' | 'lifecycle';
     messageType: string;
     headers?: Record<string, string>;
     context?: Record<string, unknown>;
@@ -16,6 +18,8 @@ export type AgentChatRuntimePrincipal = TChatRuntimePrincipal;
 export interface AgentChatDispatchPayload extends Record<string, unknown> {
     request: TChatRequest;
     options: TChatOptions & TChatSourceAuditOptions & {
+        /** Host-created group recipient receipt; the runtime must reauthorize it before execution. */
+        groupDeliveryId?: string;
         /** Host-resolved runtime branch, independent of the conversation root. */
         threadId?: string;
         isDerivedThread?: boolean;

package/src/lib/agent-plugin/import-default-agent-plugins.command.d.ts

@@ -0,0 +1,6 @@
+import { Command } from '@nestjs/cqrs';
+import type { DefaultAgentPluginsImportResult } from '@xpert-ai/contracts';
+/** Import official resource packages for the authenticated organization administrator. Does not authorize workspaces. */
+export declare class ImportDefaultAgentPluginsCommand extends Command<DefaultAgentPluginsImportResult> {
+    static readonly type = "[Agent Plugins] Import defaults";
+}

package/src/lib/core/context/request-context.d.ts

@@ -10,6 +10,7 @@ export declare class RequestContext {
     readonly extras: Record<string, any>;
     constructor(request: IncomingMessage, response: ServerResponse, reqId: string, userId?: string, extras?: Record<string, any>);
     static currentRequestContext(): RequestContext;
+    /** @deprecated For resource authorization use currentApiPrincipal()?.resourceScope; retained for credential metadata. */
     static currentApiKey(): IApiKey | null;
     static currentApiPrincipal(): IApiPrincipal | null;
     static currentRequest(): IncomingMessage;

package/src/lib/rag/capability/index.d.ts

@@ -0,0 +1,6 @@
+export * from './knowledgebase';
+export * from './knowledgebase-catalog';
+export * from './knowledge-graph';
+export * from './knowledgebase-documents';
+export * from './knowledge-upload-sessions';
+export * from './knowledge-document-visual-assets';

package/src/lib/{runtime/capabilities → rag/capability}/knowledge-document-visual-assets.d.ts

@@ -1,5 +1,5 @@
-import type { RuntimeIdentityScope } from '../runtime-scope';
-import type { WorkspaceFilesApi, WorkspacePortableFileReference } from './workspace-files';
+import type { RuntimeIdentityScope } from '../../runtime/runtime-scope';
+import type { WorkspaceFilesApi, WorkspacePortableFileReference } from '../../runtime/capabilities/workspace-files';
 export type KnowledgeDocumentVisualCandidateReason = 'same_block' | 'same_chunk' | 'same_page' | 'adjacent_page' | 'visual_summary_match' | 'visual_only_fallback';
 export type KnowledgeDocumentVisualTextAnchor = {
     page?: number;

package/src/lib/rag/capability/knowledge-upload-sessions.d.ts

@@ -0,0 +1,71 @@
+/** Persisted upload progress within one knowledgebase; completion does not imply document import or processing. */
+export type KnowledgeUploadSession = {
+    /** Host-generated session UUID, used together with the owning knowledgebaseId. */
+    id: string;
+    /** Display file name; not a storage path. */
+    name: string;
+    /** Expected total file size in bytes. */
+    size: number;
+    /** Host-selected part size in bytes; only the final part may be shorter. */
+    chunkSize: number;
+    /** Persisted zero-based part indexes, sorted in ascending order; gaps identify missing parts. */
+    received: number[];
+    /** Lowercase hexadecimal SHA-256 of each received part, keyed by its decimal index. */
+    partHashes: Record<string, string>;
+    /** True after complete() verifies all expected parts and records the whole-file hash. */
+    complete: boolean;
+    /** Lowercase hexadecimal SHA-256 of the whole file, available after successful completion. */
+    sha256?: string;
+};
+/** Server-only staged uploads exposed through Documents.uploads. Every operation revalidates Knowledge write access. */
+export interface KnowledgeUploadSessionsApi {
+    /**
+     * Create a new upload session without creating or processing a document.
+     * size is the total byte count (positive, currently at most 2 GiB); use the returned chunkSize for part boundaries.
+     */
+    create(input: {
+        knowledgebaseId: string;
+        name: string;
+        size: number;
+    }): Promise<KnowledgeUploadSession>;
+    /** Read persisted progress and part hashes to resume an existing session, including after a server restart. */
+    status(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+    }): Promise<KnowledgeUploadSession>;
+    /**
+     * Persist one zero-based part; parts may arrive out of order.
+     * buffer must match the expected part length and sha256 must be its lowercase hexadecimal SHA-256.
+     * Retrying identical bytes is safe; conflicting bytes for an existing index are rejected.
+     */
+    append(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+        index: number;
+        buffer: Buffer;
+        sha256: string;
+    }): Promise<void>;
+    /**
+     * Verify all parts and their lengths, then record the whole-file SHA-256 and mark the session complete.
+     * Incomplete uploads fail; repeated completion is safe. Does not import documents or start processing.
+     */
+    complete(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+    }): Promise<KnowledgeUploadSession>;
+    /**
+     * Read bytes from a completed upload, including ranges that cross part boundaries, for streaming ZIP readers.
+     * offset is zero-based; length is nonnegative, at most chunkSize, and offset + length must not exceed size.
+     */
+    read(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+        offset: number;
+        length: number;
+    }): Promise<Buffer>;
+    /** Delete an existing session and its staged bytes; previously imported documents are unaffected. */
+    remove(input: {
+        knowledgebaseId: string;
+        sessionId: string;
+    }): Promise<void>;
+}

package/src/lib/rag/capability/knowledgebase-catalog.d.ts

@@ -0,0 +1,78 @@
+/** Knowledgebase discovery is scoped to the authenticated runtime, never caller-supplied identities. */
+export declare const knowledgebaseActions: readonly ["knowledgebase.read", "knowledgebase.manage", "content.search", "documents.read", "documents.create", "documents.update", "documents.delete", "documents.process", "chunks.write", "chunks.delete"];
+export type KnowledgebaseAction = (typeof knowledgebaseActions)[number];
+export type KnowledgebaseQuery = {
+    scope: {
+        kind: 'workspace';
+        workspaceId: string;
+        relation: 'owned' | 'available';
+    } | {
+        kind: 'organization';
+    } | {
+        kind: 'tenant';
+    };
+    filter?: {
+        /** Literal name/description substring, not content retrieval. */
+        text?: string;
+        visibility?: 'private' | 'organization' | 'public';
+        applicationTags?: {
+            allOf: string[];
+        };
+        publication?: 'published' | 'unpublished';
+    };
+    access?: {
+        requireAll: KnowledgebaseAction[];
+    };
+    page?: {
+        limit?: number;
+        cursor?: string;
+    };
+};
+export type KnowledgebaseSummary = {
+    id: string;
+    name: string;
+    description: string | null;
+    workspaceId: string | null;
+    visibility: 'private' | 'organization' | 'public';
+    applicationTags: string[];
+    type: string | null;
+    status: string | null;
+    published: boolean;
+    documentNum: number;
+    chunkNum: number;
+};
+export type KnowledgebasePage = {
+    items: KnowledgebaseSummary[];
+    /** Follow even when items is empty; authorization is re-evaluated on every page. */
+    nextCursor: string | null;
+};
+export type KnowledgebaseDetail = KnowledgebaseSummary & {
+    capabilities: {
+        documentIngestion: boolean;
+    };
+    configuration: {
+        embeddingConfigured: boolean;
+    };
+    processing: {
+        blocked: boolean;
+        reason: 'rebuilding' | 'embedding_not_configured' | 'unsupported_type' | null;
+    };
+};
+export type KnowledgebaseGetInput = {
+    knowledgebaseId: string;
+};
+export type KnowledgebaseAccessInput = {
+    knowledgebaseIds: string[];
+    actions: KnowledgebaseAction[];
+};
+export type KnowledgebaseAccessResult = {
+    items: Array<{
+        knowledgebaseId: string;
+        /** Missing and inaccessible resources have the same unavailable result. */
+        status: 'available' | 'unavailable';
+        actions: Array<{
+            action: KnowledgebaseAction;
+            allowed: boolean;
+        }>;
+    }>;
+};

package/src/lib/{runtime/capabilities → rag/capability}/knowledgebase-documents.d.ts

@@ -1,5 +1,6 @@
 import { type I18nObject, type DocumentTextParserConfig, type DocumentSheetParserConfig, JSONValue } from '@xpert-ai/contracts';
-import type { WorkspacePortableFileReference } from './workspace-files';
+import type { WorkspacePortableFileReference } from '../../runtime/capabilities/workspace-files';
+import type { KnowledgeUploadSessionsApi } from './knowledge-upload-sessions';
 export type KnowledgebaseDocumentFile = {
     buffer: Buffer;
     originalname?: string;
@@ -60,6 +61,9 @@ export type KnowledgebaseListDocumentsInput = {
     page?: number;
     pageSize?: number;
     search?: string;
+    /** Literal substring search; paths include the logical folder and imported originalRelativePath. */
+    searchFields?: Array<'name' | 'path'>;
+    mimeTypes?: string[];
     includeFolders?: boolean;
     /** List direct children of this folder. Use null for the knowledgebase root. */
     parentId?: string | null;
@@ -110,6 +114,8 @@ export type KnowledgebaseUploadedFile = {
 };
 export type KnowledgebaseCreateDocumentsInput = {
     knowledgebaseId: string;
+    /** Retry key, scoped to this Knowledge base. Repeated creation returns the original documents. */
+    idempotencyKey?: string;
     documents: KnowledgebaseDocumentDraft[];
     parserConfig?: KnowledgebaseDocumentParserConfig;
     metadata?: KnowledgebaseDocumentMetadata;
@@ -266,6 +272,8 @@ export type KnowledgebaseProcessingOptionsResult = {
     parserConfig: DocumentTextParserConfig & Partial<DocumentSheetParserConfig>;
 };
 export interface KnowledgebaseDocumentsApi {
+    /** Stage resumable uploads without starting document processing. */
+    readonly uploads: KnowledgeUploadSessionsApi;
     getProcessingOptions(input: KnowledgebaseProcessingOptionsInput): Promise<KnowledgebaseProcessingOptionsResult>;
     readText(input: KnowledgebaseReadTextInput): Promise<KnowledgebaseReadTextResult>;
     /** Missing/stale conversion snapshots fail explicitly; this never falls back to indexed chunks. */