@xpert-ai/plugin-sdk 3.18.3 → 3.18.5

package/index.esm.js

@@ -4,7 +4,7 @@ import { pick } from 'lodash-es';
 import { _ as _extends } from './_extends.esm.js';
 import { DiscoveryService, Reflector } from '@nestjs/core';
 import { Subject, filter } from 'rxjs';
-import { LanguagesEnum, ParameterType, AiModelTypeEnum, PriceType, FetchFrom, ModelFeature, ModelPropertyKey, MCP_TOOL_RISKS, MCP_TOOL_SIDE_EFFECTS, MCP_TOOL_IDEMPOTENCY, MCP_REQUIRED_CONTEXTS, MCP_CAPABILITY_VISIBILITIES } from '@xpert-ai/contracts';
+import { LanguagesEnum, ParameterType, AiModelTypeEnum, PriceType, FetchFrom, ModelFeature, ModelPropertyKey, MCP_CAPABILITY_APPROVAL_MODES, MCP_TOOL_RISKS, MCP_TOOL_SIDE_EFFECTS, MCP_TOOL_IDEMPOTENCY, MCP_REQUIRED_CONTEXTS, MCP_CAPABILITY_VISIBILITIES } from '@xpert-ai/contracts';
 export { ASSISTANT_CHAT_SEND_MESSAGE_COMMAND, ASSISTANT_CONTEXT_SET_COMMAND } from '@xpert-ai/contracts';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { ExtractJwt } from 'passport-jwt';
@@ -16,7 +16,7 @@ import fs__default from 'fs';
 import http from 'http';
 import https from 'https';
 import { c as createRuntimeCapability, B as BuiltinToolset } from './model-provider.esm.js';
-export { A as ActorTokenRuntimeCapability, a as ArtifactsRuntimeCapability, b as BaseTool, d as BaseToolset, D as DefaultAgentMiddlewareRuntimeCapabilityRegistry, D as DefaultRuntimeCapabilityRegistry, K as KnowledgeDocumentVisualAssetsRuntimeCapability, e as KnowledgebaseDocumentsRuntimeCapability, f as KnowledgebaseProvisioningRuntimeCapability, g as KnowledgebaseRuntimeCapability, M as ModelProviderBuiltinToolset, P as ProjectAccessRuntimeCapability, h as ProjectProvisioningRuntimeCapability, S as SANDBOX_JOB_ERROR_CODES, i as SANDBOX_JOB_PROGRESS_PREFIX, j as SandboxJobRuntimeError, k as SandboxJobsRuntimeCapability, W as WORKSPACE_FILES_SOURCE, l as WorkspaceFilesRuntimeCapability, X as XPERT_RUNTIME_CAPABILITIES_TOKEN, m 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, K as KnowledgeDocumentVisualAssetsRuntimeCapability, f as KnowledgeDocumentVisualAssetsRuntimeFactoryCapability, g as KnowledgebaseDocumentsRuntimeCapability, h as KnowledgebaseProvisioningRuntimeCapability, i as KnowledgebaseRuntimeCapability, M as ModelProviderBuiltinToolset, P as ProjectAccessRuntimeCapability, j as ProjectProvisioningRuntimeCapability, S as SANDBOX_JOB_ERROR_CODES, k as SANDBOX_JOB_PROGRESS_PREFIX, l as SandboxJobRuntimeError, m as SandboxJobsRuntimeCapability, W as WORKSPACE_FILES_SOURCE, n as WorkspaceFilesRuntimeCapability, X as XPERT_RUNTIME_CAPABILITIES_TOKEN, o as isSandboxJobRuntimeError } from './model-provider.esm.js';
 import fsPromises from 'fs/promises';
 import * as path from 'path';
 import path__default, { join } from 'path';
@@ -41,7 +41,7 @@ import { assertConnectorDefinition } from './connector.esm.js';
 export { CONNECTOR_AUTHORIZATION_MODES, CONNECTOR_SCOPE_TYPES, getConnectorAuthMethods, getConnectorAuthorizationModes } from './connector.esm.js';
 export { base64ToBytes, bytesToBase64, createCollaborationClient, createCollaborationPresenceStore, createSocketIoTransportAdapter, createYjsDocumentAdapter } from './collaboration-client.esm.js';
 import { tool } from '@langchain/core/tools';
-import 'zod/v3';
+import { ZodError, z } from 'zod/v3';
 
 /**
  * Metadata keys used in plugins for defining various aspects like entities, subscribers, and configurations.
@@ -3579,17 +3579,11 @@ class OpenAICompatibleReranker {
             if (!Array.isArray(output)) {
                 throw new Error('Invalid response format: missing results array');
             }
-            // Collect raw scores and normalize them.
-            const scores = output.map((r)=>r.relevance_score);
-            const minScore = Math.min(...scores);
-            const maxScore = Math.max(...scores);
-            const scoreRange = maxScore !== minScore ? maxScore - minScore : 1.0;
             const reranked = output.map((r)=>{
                 const index = r.index;
-                const normalizedScore = (r.relevance_score - minScore) / scoreRange;
                 const result = {
                     index,
-                    relevanceScore: normalizedScore
+                    relevanceScore: r.relevance_score
                 };
                 if (options.returnDocuments) {
                     var _r_document, _docs_index, _docs_index1;
@@ -3639,6 +3633,44 @@ class Speech2TextChatModel extends BaseChatModel {
 }
 
 const encodingCache = new Map();
+/** Exact, model-independent text count for hard chunk limits. Treat special-token spellings as literal document text. */ function textEncoding() {
+    const cacheKey = 'encoding:cl100k_base';
+    let encoder = encodingCache.get(cacheKey);
+    if (!encoder) {
+        encoder = getEncoding('cl100k_base');
+        encodingCache.set(cacheKey, encoder);
+    }
+    return encoder;
+}
+function countTextTokens(text) {
+    if (!text) return 0;
+    // A hard limit must fail if tokenization fails, never fall back to an estimate.
+    return textEncoding().encode(text, [], []).length;
+}
+/** Token boundaries that also end on complete Unicode characters, in UTF-16 source offsets. */ function textTokenBoundaries(text) {
+    const encoder = textEncoding();
+    const tokens = encoder.encode(text, [], []);
+    const boundaries = [
+        {
+            offset: 0,
+            tokens: 0
+        }
+    ];
+    let offset = 0;
+    let start = 0;
+    for(let end = 1; end <= tokens.length; end++){
+        const decoded = encoder.decode(tokens.slice(start, end));
+        if (!decoded || !text.startsWith(decoded, offset)) continue;
+        offset += decoded.length;
+        boundaries.push({
+            offset,
+            tokens: end
+        });
+        start = end;
+    }
+    if (offset !== text.length) throw new Error('Tokenization could not preserve the source text.');
+    return boundaries;
+}
 /**
  * Fallback token estimation method.
  *
@@ -4103,6 +4135,9 @@ SSOProviderRegistry = __decorate([
 const ConnectorRuntimeCapability = createRuntimeCapability('platform.connector', {
     description: 'Resolve connector credentials for agent middleware.'
 });
+const ConnectorRuntimeFactoryCapability = createRuntimeCapability('platform.connector.factory', {
+    description: 'Create a connector API restricted to host-granted connectors and the authorized execution identity.'
+});
 
 const CONNECTOR_STRATEGY = 'CONNECTOR_STRATEGY';
 const ConnectorStrategyKey = (provider)=>applyDecorators(SetMetadata(CONNECTOR_STRATEGY, provider), SetMetadata(STRATEGY_META_KEY, CONNECTOR_STRATEGY));
@@ -5866,6 +5901,9 @@ const EVOLUTION_RUNTIME_SERVICE_TOKEN = 'XPERT_EVOLUTION_RUNTIME_SERVICE';
 const EvolutionRuntimeCapability = createRuntimeCapability('platform.agent-evolution', {
     description: 'Ingest learning signals and resolve immutable capability versions for domain runtimes.'
 });
+const EvolutionChangeRuntimeCapability = createRuntimeCapability('platform.agent-evolution.changes', {
+    description: 'Prepare, evaluate and publish versioned changes through target-owned validators and effect providers.'
+});
 
 function defineMcpApp(definition) {
     return Object.freeze(definition);
@@ -6029,6 +6067,12 @@ function validateProviderOptions(options) {
 }
 function validateToolOptions(options, methodName) {
     var _options_description;
+    if (options.resultFormat && options.resultFormat !== 'dto' && options.resultFormat !== 'tool_result') {
+        throw new Error(`Tool '${options.name}' declares an invalid resultFormat.`);
+    }
+    if (options.resultFormat === 'tool_result' && !options.outputSchema) {
+        throw new Error(`Tool '${options.name}' requires outputSchema for tool_result.`);
+    }
     if (!TOOL_NAME_PATTERN.test(options.name) || options.name.length > 191) {
         throw new Error(`Method '${methodName}' declares invalid Tool name '${options.name}'.`);
     }
@@ -6044,6 +6088,9 @@ function validateToolOptions(options, methodName) {
         throw new Error(`MCP Tool '${options.name}' requires at least one execution context.`);
     }
     if (options.mcp) {
+        if (options.mcp.defaultApprovalMode !== undefined && !includesValue(MCP_CAPABILITY_APPROVAL_MODES, options.mcp.defaultApprovalMode)) {
+            throw new Error(`MCP Tool '${options.name}' declares invalid defaultApprovalMode.`);
+        }
         const behavior = options.mcp.behavior;
         if (!includesValue(MCP_TOOL_RISKS, behavior == null ? void 0 : behavior.risk) || !includesValue(MCP_TOOL_SIDE_EFFECTS, behavior == null ? void 0 : behavior.sideEffect) || !includesValue(MCP_TOOL_IDEMPOTENCY, behavior == null ? void 0 : behavior.idempotency)) {
             throw new Error(`MCP Tool '${options.name}' requires valid behavior annotations.`);
@@ -6070,6 +6117,19 @@ function assertStrictObjectSchema(schema, toolName, role) {
     if (!schema || typeof Reflect.get(schema, 'parseAsync') !== 'function') {
         throw new Error(`Tool '${toolName}' requires a Zod ${role} schema.`);
     }
+    // Refinements preserve the strict object shape while enforcing cross-field invariants.
+    // Plugins can load a different physical copy of Zod; use its explicit type tag.
+    while(schema._def.typeName === 'ZodEffects'){
+        const refinement = schema;
+        if (refinement._def.effect.type !== 'refinement') break;
+        schema = refinement.innerType();
+    }
+    if (role === 'output' && schema._def.typeName === 'ZodUnion') {
+        // Recovery receipts may have a different shape, but every branch must reject extra fields.
+        const union = schema;
+        for (const option of union.options)assertStrictObjectSchema(option, toolName, role);
+        return;
+    }
     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.`);
@@ -6143,6 +6203,141 @@ XpertToolProviderRegistry = __decorate([
     ])
 ], XpertToolProviderRegistry);
 
+// Invariants: recovery starts only after the business method returns successfully.
+// Projection and recovery callbacks must be free of business side effects.
+// The adapter validates normal output once and validates any fallback separately;
+// neither path may rerun the operation or suppress input, authorization or commit failures.
+// Installed plugins may resolve a different physical SDK copy from the host.
+const PREPARED_RESULT = Symbol.for('xpert.tool.prepared-result.v1');
+/** Defer output projection until the adapter can validate and recover its result. */ function prepareToolResult(project, recover) {
+    return {
+        [PREPARED_RESULT]: true,
+        project,
+        recover
+    };
+}
+function isPrepared(value) {
+    return typeof value === 'object' && value !== null && PREPARED_RESULT in value && value[PREPARED_RESULT] === true && 'project' in value && typeof value.project === 'function' && 'recover' in value && typeof value.recover === 'function';
+}
+async function resolveToolResult(value, validate) {
+    if (!isPrepared(value)) return validate(value);
+    try {
+        return await validate(await value.project());
+    } catch (error) {
+        const diagnostic = {
+            code: 'tool_output_invalid',
+            issues: error instanceof ZodError ? error.issues.slice(0, 10).map((issue)=>({
+                    path: issue.path.join('.').slice(0, 240),
+                    code: issue.code
+                })) : []
+        };
+        // A malformed fallback is a programming error too; never send unchecked data.
+        return validate(await value.recover(diagnostic));
+    }
+}
+
+// Why this exists: MCP media blocks and business metadata have different contracts.
+// Validate metadata with the declared output schema, preserve bounded media blocks,
+// and include the same DTO in text for clients that hide structuredContent.
+const XPERT_TOOL_RESULT_FORMAT_VERSION = 1;
+const contentSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('text'),
+        text: z.string().max(2 * 1024 * 1024)
+    }).strict(),
+    z.object({
+        type: z.literal('image'),
+        data: z.string().min(1).max(8 * 1024 * 1024),
+        mimeType: z.enum([
+            'image/png',
+            'image/jpeg',
+            'image/webp',
+            'image/gif'
+        ])
+    }).strict(),
+    z.object({
+        type: z.literal('audio'),
+        data: z.string().min(1).max(8 * 1024 * 1024),
+        mimeType: z.string().min(1).max(100)
+    }).strict(),
+    z.object({
+        type: z.literal('resource_link'),
+        uri: z.string().min(1).max(4096),
+        name: z.string().max(240).optional()
+    }).strict()
+]);
+/** Validate the envelope separately so binary content never enters the business DTO. */ async function parseDecoratedToolResult(value, outputSchema) {
+    var _result_content;
+    const envelope = z.object({
+        content: z.array(contentSchema).max(32).optional(),
+        structuredContent: outputSchema,
+        isError: z.boolean().optional()
+    }).strict();
+    const result = await envelope.parseAsync(value);
+    var _result_content_map;
+    const content = (_result_content_map = (_result_content = result.content) == null ? void 0 : _result_content.map((item)=>{
+        switch(item.type){
+            case 'text':
+                return {
+                    type: 'text',
+                    text: item.text
+                };
+            case 'image':
+                return {
+                    type: 'image',
+                    data: item.data,
+                    mimeType: item.mimeType
+                };
+            case 'audio':
+                return {
+                    type: 'audio',
+                    data: item.data,
+                    mimeType: item.mimeType
+                };
+            case 'resource_link':
+                return _extends({
+                    type: 'resource_link',
+                    uri: item.uri
+                }, item.name ? {
+                    name: item.name
+                } : {});
+        }
+    })) != null ? _result_content_map : [];
+    // MCP clients may expose only content to the model. Keep the validated DTO
+    // readable there too, while retaining binary blocks and App structured data.
+    const text = JSON.stringify(result.structuredContent);
+    if (!content.some((item)=>item.type === 'text' && item.text === text)) content.push({
+        type: 'text',
+        text
+    });
+    return _extends({
+        structuredContent: result.structuredContent,
+        content
+    }, result.isError === undefined ? {} : {
+        isError: result.isError
+    });
+}
+function agentContent(content) {
+    return (content != null ? content : []).map((item)=>{
+        if (item.type === 'image') return {
+            type: 'image_url',
+            image_url: {
+                url: `data:${item.mimeType};base64,${item.data}`
+            }
+        };
+        if (item.type === 'text') return item;
+        var _item_name;
+        if (item.type === 'resource_link') return {
+            type: 'text',
+            text: `${(_item_name = item.name) != null ? _item_name : 'Resource'}: ${item.uri}`
+        };
+        return {
+            type: 'text',
+            text: `Audio content (${item.mimeType}) is available through MCP.`
+        };
+    });
+}
+
 class DecoratedToolsetStrategy {
     validateConfig() {
         return Promise.resolve();
@@ -6247,13 +6442,27 @@ function createAgentTool(instance, descriptor, middlewareContext, middlewareOpti
     return 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);
+        if (descriptor.options.resultFormat === 'tool_result' && descriptor.options.outputSchema) {
+            const result = await resolveToolResult(output, (value)=>parseDecoratedToolResult(value, descriptor.options.outputSchema));
+            var _result_isError;
+            return [
+                agentContent(result.content),
+                {
+                    structuredContent: result.structuredContent,
+                    isError: (_result_isError = result.isError) != null ? _result_isError : false
+                }
+            ];
+        }
+        return resolveToolResult(output, async (value)=>{
+            const parsedOutput = descriptor.options.outputSchema ? await descriptor.options.outputSchema.parseAsync(value) : value;
+            return stringifyDto(parsedOutput, descriptor.options.name);
+        });
     }, _extends({
         name: descriptor.options.name,
         description: descriptor.options.description,
         schema: descriptor.options.inputSchema,
-        verboseParsingErrors: true
+        verboseParsingErrors: true,
+        responseFormat: descriptor.options.resultFormat === 'tool_result' ? 'content_and_artifact' : 'content'
     }, descriptor.options.metadata ? {
         metadata: descriptor.options.metadata
     } : {}));
@@ -6277,7 +6486,10 @@ function createMcpTool(instance, descriptor) {
                 eligible: true
             }
         },
-        behavior: mcp.behavior,
+        behavior: mcp.behavior
+    }, mcp.defaultApprovalMode ? {
+        defaultApprovalMode: mcp.defaultApprovalMode
+    } : {}, {
         requiredContext: [
             ...mcp.requiredContext
         ],
@@ -6297,18 +6509,23 @@ function createMcpTool(instance, descriptor) {
         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
-            };
+            if (descriptor.options.resultFormat === 'tool_result') {
+                return resolveToolResult(output, (value)=>parseDecoratedToolResult(value, outputSchema));
+            }
+            return resolveToolResult(output, async (value)=>{
+                const parsedOutput = await outputSchema.parseAsync(value);
+                // Serialize once so text-only clients and MCP Apps receive the same JSON-safe DTO.
+                const text = stringifyDto(parsedOutput, descriptor.options.name);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text
+                        }
+                    ],
+                    structuredContent: JSON.parse(text)
+                };
+            });
         }
     });
 }
@@ -6373,9 +6590,6 @@ function stringifyDto(value, toolName) {
     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,
@@ -6455,4 +6669,4 @@ XpertToolProviderCoordinator = __decorate([
     ])
 ], XpertToolProviderCoordinator);
 
-export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_ERROR_STEER_TARGET_NOT_RUNNING, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModel, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, COLLABORATION_DOCUMENT_PROVIDER, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CollaborationDocumentProvider, CollaborationDocumentProviderRegistry, CollaborationRuntimeCapability, CommonParameterRules, ConnectorRuntimeCapability, 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, 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, KNOWLEDGE_STRATEGY, 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, 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, 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, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, 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, 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, WrapWorkflowNodeExecutionCommand, XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN, XPERT_TOOL_METHOD_METADATA, XPERT_TOOL_PROVIDER, XPERT_TOOL_PROVIDER_METADATA, XpFileSystem, XpertServerPlugin, XpertTool, XpertToolProvider, XpertToolProviderCoordinator, XpertToolProviderRegistry, als, appendSandboxMessage, assertConnectorDefinition, buildSandboxTimeoutMessage, calcTokenUsage, calculateLLMUsagePrice, calculateModelPrice, calculateModelUsageCharge, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, defineMcpApp, defineMcpCapabilities, defineMcpPrompt, defineMcpResource, defineMcpResourceTemplate, defineXpertTool, derivePluginArtifactNamespace, describeXpertToolProvider, downloadRemoteFile, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, getXpertToolMethod, isDevelopmentSandboxRuntimeEnvironment, isModelOutputValidationError, isModelUsagePricingConfig, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStrategyInstance, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, pluginArtifactTableName, processAsyncAIGCManagedJob, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, resolveModelUsagePricingSnapshot, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveStrategyMetadataTarget, resolveTenantGlobalScopeKey, resolveTokenUsage, runWithRequestContext, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage };
+export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_ERROR_STEER_TARGET_NOT_RUNNING, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModel, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, COLLABORATION_DOCUMENT_PROVIDER, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, 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, 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, KNOWLEDGE_STRATEGY, 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, 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, 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, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, 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, 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, WrapWorkflowNodeExecutionCommand, XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN, XPERT_TOOL_METHOD_METADATA, XPERT_TOOL_PROVIDER, XPERT_TOOL_PROVIDER_METADATA, XPERT_TOOL_RESULT_FORMAT_VERSION, XpFileSystem, XpertServerPlugin, XpertTool, XpertToolProvider, XpertToolProviderCoordinator, XpertToolProviderRegistry, 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, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, getXpertToolMethod, isDevelopmentSandboxRuntimeEnvironment, isModelOutputValidationError, isModelUsagePricingConfig, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStrategyInstance, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, pluginArtifactTableName, prepareToolResult, processAsyncAIGCManagedJob, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, resolveModelUsagePricingSnapshot, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveStrategyMetadataTarget, resolveTenantGlobalScopeKey, resolveTokenUsage, runWithRequestContext, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage, textTokenBoundaries };

package/model-provider.cjs.js

@@ -199,10 +199,16 @@ const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platfor
 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.'
 });
+/** Platform registry entry. The operation capability above is bound only inside a caller runtime. */ const ActorTokenRuntimeFactoryCapability = createRuntimeCapability('platform.actor-token.factory', {
+    description: 'Create an actor-token API with host-bound identity, delegation claims and an isolated token cache.'
+});
 
 const ArtifactsRuntimeCapability = createRuntimeCapability('platform.artifacts', {
     description: 'Create, version, preview, download, share, archive, and delete platform-managed plugin and Agent artifacts.'
@@ -375,12 +381,14 @@ function normalizeWorkspaceScope(scope) {
 }
 
 exports.ActorTokenRuntimeCapability = ActorTokenRuntimeCapability;
+exports.ActorTokenRuntimeFactoryCapability = ActorTokenRuntimeFactoryCapability;
 exports.ArtifactsRuntimeCapability = ArtifactsRuntimeCapability;
 exports.BaseTool = BaseTool;
 exports.BaseToolset = BaseToolset;
 exports.BuiltinToolset = BuiltinToolset;
 exports.DefaultRuntimeCapabilityRegistry = DefaultRuntimeCapabilityRegistry;
 exports.KnowledgeDocumentVisualAssetsRuntimeCapability = KnowledgeDocumentVisualAssetsRuntimeCapability;
+exports.KnowledgeDocumentVisualAssetsRuntimeFactoryCapability = KnowledgeDocumentVisualAssetsRuntimeFactoryCapability;
 exports.KnowledgebaseDocumentsRuntimeCapability = KnowledgebaseDocumentsRuntimeCapability;
 exports.KnowledgebaseProvisioningRuntimeCapability = KnowledgebaseProvisioningRuntimeCapability;
 exports.KnowledgebaseRuntimeCapability = KnowledgebaseRuntimeCapability;

package/model-provider.esm.js

@@ -197,10 +197,16 @@ const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platfor
 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.'
 });
+/** Platform registry entry. The operation capability above is bound only inside a caller runtime. */ const ActorTokenRuntimeFactoryCapability = createRuntimeCapability('platform.actor-token.factory', {
+    description: 'Create an actor-token API with host-bound identity, delegation claims and an isolated token cache.'
+});
 
 const ArtifactsRuntimeCapability = createRuntimeCapability('platform.artifacts', {
     description: 'Create, version, preview, download, share, archive, and delete platform-managed plugin and Agent artifacts.'
@@ -372,4 +378,4 @@ function normalizeWorkspaceScope(scope) {
     } : {});
 }
 
-export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, SANDBOX_JOB_ERROR_CODES as S, WORKSPACE_FILES_SOURCE as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ArtifactsRuntimeCapability as a, BaseTool as b, createRuntimeCapability as c, BaseToolset as d, KnowledgebaseDocumentsRuntimeCapability as e, KnowledgebaseProvisioningRuntimeCapability as f, KnowledgebaseRuntimeCapability as g, ProjectProvisioningRuntimeCapability as h, SANDBOX_JOB_PROGRESS_PREFIX as i, SandboxJobRuntimeError as j, SandboxJobsRuntimeCapability as k, WorkspaceFilesRuntimeCapability as l, isSandboxJobRuntimeError as m };
+export { ActorTokenRuntimeCapability as A, BuiltinToolset as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectAccessRuntimeCapability as P, SANDBOX_JOB_ERROR_CODES as S, WORKSPACE_FILES_SOURCE 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, KnowledgebaseDocumentsRuntimeCapability as g, KnowledgebaseProvisioningRuntimeCapability as h, KnowledgebaseRuntimeCapability as i, ProjectProvisioningRuntimeCapability as j, SANDBOX_JOB_PROGRESS_PREFIX as k, SandboxJobRuntimeError as l, SandboxJobsRuntimeCapability as m, WorkspaceFilesRuntimeCapability as n, isSandboxJobRuntimeError as o };

package/package.json

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

package/runtime-capabilities.md

@@ -0,0 +1,49 @@
+# Platform capabilities and scoped factories
+
+The platform registry is populated by `RuntimeCapabilityProvider` discovery after Nest has instantiated the application modules. Domain modules own their providers. HTTP handlers, View Actions, background jobs and Agent runtimes can consume this registry without constructing an Agent middleware runtime.
+
+## Choose the correct registry entry
+
+Stateless domain APIs such as ProjectProvisioning, Knowledgebase, Artifacts and File are registered directly. Their domain authorization checks still run for each operation. Agent runtimes may bind additional defaults to the same domain service, such as the conversation for File access.
+
+Three capabilities expose a **factory** in the platform registry. The operation API has a separate key and belongs only to a caller's scoped runtime:
+
+| Platform factory key                                    | Scoped operation key                             | State owned by one API                                     |
+| ------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------- |
+| `ConnectorRuntimeFactoryCapability`                     | `ConnectorRuntimeCapability`                     | Host-selected connector binding IDs and execution identity |
+| `ActorTokenRuntimeFactoryCapability`                    | `ActorTokenRuntimeCapability`                    | Caller identity, fixed delegation claims and token cache   |
+| `KnowledgeDocumentVisualAssetsRuntimeFactoryCapability` | `KnowledgeDocumentVisualAssetsRuntimeCapability` | Issued image paths and execution binding                   |
+
+The platform registry deliberately does not return a shared operation API for these three keys. Checking the scoped operation key on the platform registry is not a provider availability check; check the factory key there instead.
+
+## Bind once for a caller operation
+
+```ts
+import {
+  ActorTokenRuntimeFactoryCapability,
+  type ActorTokenRuntimeScope,
+  type RuntimeCapabilityRegistry
+} from '@xpert-ai/plugin-sdk'
+
+// authorizedScope comes from the host's authenticated, authorized request/job context.
+function bindJobTokenApi(capabilities: RuntimeCapabilityRegistry, authorizedScope: ActorTokenRuntimeScope) {
+  return capabilities.require(ActorTokenRuntimeFactoryCapability).createScopedApi({
+    ...authorizedScope,
+    act: { sub: 'background-task' }
+  })
+}
+```
+
+Reuse the returned API during that one operation. Create a new API for the next caller/execution. Never keep a scoped API in a singleton, or register it back into the platform registry. Factory resolution must happen after provider discovery, not in service constructors.
+
+`RuntimeIdentityScope` carries the authorized tenant, organization, user and optional project/Assistant/conversation/execution identity. It is an in-process host contract, not an HTTP DTO or model-visible tool input. A factory does not grant access: callers must first validate request/job ownership, and operations retain their domain checks.
+
+- Connector APIs copy the selected binding IDs. Empty selection denies access. Credential access retains identity, Assistant, project membership, personal/shared authorization and audit checks. Existing connector execution binding requirements remain in force.
+- ActorToken APIs capture identity and host-defined `act` claims. Per-call `act` adds metadata but cannot replace fixed host claims. Cached tokens are rejected if used under a different caller identity.
+- Visual-assets APIs require a complete authorized execution binding when used. They only read paths issued to the same API/execution and recheck document fingerprints. The caller supplies an already scoped WorkspaceFiles writer.
+
+## Agent integration
+
+The Agent facade resolves the platform factories when initializing a scoped runtime and registers the resulting operation APIs in that runtime's child registry. This does not change the model-visible tool list inside a tool-call loop.
+
+Some child Agent identities are assigned after graph construction. Visual-assets factories accept an optional host-owned `resolveExecutionScope` callback for this case. The Agent integration supplies the LangGraph resolver; the domain factory has no LangGraph dependency. Platform callers that omit the callback use the fixed scope captured at API creation. Every image issuance and consumption still verifies the execution binding.

package/src/lib/agent/middleware/capabilities/assistant-task.d.ts

@@ -95,6 +95,8 @@ export type AgentMiddlewareCorrelatedExecution = {
 };
 export type AgentMiddlewareAssistantTaskInput = {
     xpertId: string;
+    /** Selects the Assistant base and Primary models; child Agents retain authored models. */
+    modelId?: string;
     agentKey?: string;
     /** Resolve an organization-owned external Assistant from the requester's published graph. */
     target?: AgentMiddlewareAssistantTaskTarget;
@@ -137,6 +139,7 @@ export type AgentMiddlewareAssistantTaskCancelResult = {
     canceledExecutionIds: string[];
 };
 export interface AgentMiddlewareAssistantTaskApi {
+    getModels?(xpertId: string): Promise<import('@xpert-ai/contracts').TAssistantModelsResponse>;
     startTask(input: AgentMiddlewareAssistantTaskInput): Promise<AgentMiddlewareAssistantTaskResult>;
     /** Return only safe binding descriptors; internal Assistant instance IDs are intentionally omitted. */
     listExternalAssistantBindings?(input: AgentMiddlewareListExternalAssistantBindingsInput): Promise<AgentMiddlewareExternalAssistantBinding[]>;

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

@@ -7,6 +7,7 @@ import { ICopilotModel, IModelAccessResolution, IXpertAgentExecution, JSONValue,
 import { Subscriber } from 'rxjs';
 import { AIGCModelClient, AsyncAIGCModelClient, IRerank, TLLMUsage } from '../../ai-model/types';
 import type { RuntimeCapabilityRegistry } from '../../core';
+import type { ConnectorRuntimeScope } from '../../connector/runtime-capability';
 import type { WorkspaceFileCatalog } from '../../runtime/capabilities/workspace-files';
 export * from './runtime-capability';
 export * from './capabilities';
@@ -92,27 +93,14 @@ export type AgentMiddlewareModelProviderConnection = {
     /** Persist final authoritative usage and calculate its charge exactly once. */
     reportUsage(report: ModelUsageReport, modelAccess?: IModelAccessResolution): Promise<ModelUsageReportResult>;
 };
-export type AgentMiddlewareRuntimeScope = {
-    tenantId?: string | null;
-    organizationId?: string | null;
+export type AgentMiddlewareRuntimeScope = ConnectorRuntimeScope & {
     providerScopeId?: string | null;
-    userId?: string | null;
-    workspaceId?: string | null;
-    projectId?: string | null;
-    xpertId?: string | null;
     /** Authoritative Volume catalog for runtime workspace files. */
     catalog?: WorkspaceFileCatalog | null;
     /** Authoritative catalog identity for portable workspace references. */
     scopeId?: string | null;
     /** Legacy xperts catalog compatibility flag; new runtimes use user-xperts instead. */
     isolateByUser?: boolean | null;
-    xpertName?: string | null;
-    conversationId?: string | null;
-    threadId?: string | null;
-    agentKey?: string | null;
-    executionId?: string | null;
-    /** Connector bindings selected for this conversation. An empty list denies connector resolution. */
-    connectorBindingIds?: string[] | null;
     usageCallback?: (usage: TLLMUsage) => void | Promise<void>;
     workspaceRoot?: string | null;
     workspacePath?: string | null;

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

@@ -4,6 +4,7 @@ import { AIModel } from '../ai-model';
 import { TChatModelOptions } from './model';
 export type RerankResult = {
     index: number;
+    /** Relevance score reported by the rerank provider. Higher values are more relevant. */
     relevanceScore: number;
     document?: Document<Record<string, any>>;
 };
@@ -14,6 +15,7 @@ export declare abstract class RerankModel extends AIModel {
 export interface IRerank {
     rerank(docs: Document<Record<string, any>>[], query: string, options: {
         topN?: number;
+        /** Minimum relevanceScore, applied before the Top N limit. */
         scoreThreshold?: number;
         model?: string;
     }): Promise<RerankResult[]>;

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

@@ -1,4 +1,10 @@
 import type { TiktokenEncoding } from 'js-tiktoken';
+export declare function countTextTokens(text: string): number;
+/** Token boundaries that also end on complete Unicode characters, in UTF-16 source offsets. */
+export declare function textTokenBoundaries(text: string): {
+    offset: number;
+    tokens: number;
+}[];
 /**
  * Count tokens in text
  * 1) Preferred: js-tiktoken precise encoding