@xpert-ai/plugin-sdk 3.18.7 → 3.19.0

package/index.esm.js

@@ -8,7 +8,6 @@ import { LanguagesEnum, ParameterType, AiModelTypeEnum, PriceType, FetchFrom, Mo
 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';
-import { verify, JsonWebTokenError } from 'jsonwebtoken';
 import { randomUUID, createHash } from 'node:crypto';
 import { Command } from '@nestjs/cqrs';
 import * as fs from 'fs';
@@ -332,22 +331,15 @@ class RequestContext {
         }
         return scope.organizationId;
     }
-    static hasPermissions(findPermissions, throwError) {
-        const requestContext = RequestContext.currentRequestContext();
-        if (requestContext) {
-            // tslint:disable-next-line
-            const token = ExtractJwt.fromAuthHeaderAsBearerToken()(requestContext.request);
-            if (token) {
-                const { permissions } = verify(token, process.env['JWT_SECRET']);
-                if (permissions) {
-                    const found = permissions.filter((value)=>findPermissions.indexOf(value) >= 0);
-                    if (found.length === findPermissions.length) {
-                        return true;
-                    }
-                } else {
-                    return false;
-                }
-            }
+    /**
+     * Check the authenticated principal's enabled role permissions, matching the
+     * server RequestContext. Authentication guards resolve JWTs, API keys and
+     * ChatKit client secrets before this check; the bearer is not always a JWT.
+     */ static hasPermissions(findPermissions, throwError) {
+        const permissions = this.currentPermissions();
+        if (permissions.length > 0) {
+            const found = permissions.filter((value)=>findPermissions.indexOf(value) >= 0);
+            if (found.length === findPermissions.length) return true;
         }
         if (throwError) {
             throw new HttpException('Unauthorized', HttpStatus.UNAUTHORIZED);
@@ -355,17 +347,9 @@ class RequestContext {
         return false;
     }
     static hasAnyPermission(findPermissions, throwError) {
-        const requestContext = RequestContext.currentRequestContext();
-        if (requestContext) {
-            // tslint:disable-next-line
-            const token = ExtractJwt.fromAuthHeaderAsBearerToken()(requestContext.request);
-            if (token) {
-                const { permissions } = verify(token, process.env['JWT_SECRET']);
-                const found = permissions.filter((value)=>findPermissions.indexOf(value) >= 0);
-                if (found.length > 0) {
-                    return true;
-                }
-            }
+        const permissions = this.currentPermissions();
+        if (permissions.some((value)=>findPermissions.includes(value))) {
+            return true;
         }
         if (throwError) {
             throw new HttpException('Unauthorized', HttpStatus.UNAUTHORIZED);
@@ -403,20 +387,6 @@ class RequestContext {
         const context = RequestContext.currentRequestContext();
         if (context) {
             var _this_currentUser_role, _this_currentUser;
-            // tslint:disable-next-line
-            const token = this.currentToken();
-            if (token) {
-                try {
-                    const { role } = verify(token, process.env['JWT_SECRET']);
-                    if (role) {
-                        return roles.includes(role);
-                    }
-                } catch (error) {
-                    if (!(error instanceof JsonWebTokenError)) {
-                        throw error;
-                    }
-                }
-            }
             const role = (_this_currentUser = this.currentUser()) == null ? void 0 : (_this_currentUser_role = _this_currentUser.role) == null ? void 0 : _this_currentUser_role.name;
             if (role) {
                 return roles.includes(role);
@@ -427,6 +397,11 @@ class RequestContext {
         }
         return false;
     }
+    static currentPermissions() {
+        var _this_currentUser_role, _this_currentUser;
+        var _this_currentUser_role_rolePermissions;
+        return ((_this_currentUser_role_rolePermissions = (_this_currentUser = this.currentUser()) == null ? void 0 : (_this_currentUser_role = _this_currentUser.role) == null ? void 0 : _this_currentUser_role.rolePermissions) != null ? _this_currentUser_role_rolePermissions : []).filter((rolePermission)=>rolePermission == null ? void 0 : rolePermission.enabled).map((rolePermission)=>rolePermission == null ? void 0 : rolePermission.permission).filter((permission)=>!!permission);
+    }
     constructor(request, response, reqId, userId, extras = {}){
         this.request = request;
         this.response = response;
@@ -497,15 +472,6 @@ function runWithRequestContext(req, res, next) {
 }
 
 let StrategyBus = class StrategyBus {
-    registerRemovalGuard(guard) {
-        this.removalGuards.add(guard);
-        return ()=>{
-            this.removalGuards.delete(guard);
-        };
-    }
-    async assertCanRemove(scopeKey, pluginNames) {
-        for (const guard of this.removalGuards)await guard(scopeKey, pluginNames);
-    }
     upsert(strategyType, entry) {
         this.subject.next({
             type: 'UPSERT',
@@ -523,7 +489,6 @@ let StrategyBus = class StrategyBus {
         } : {}));
     }
     constructor(){
-        this.removalGuards = new Set();
         this.subject = new Subject();
         this.events$ = this.subject.asObservable();
     }
@@ -3864,7 +3829,7 @@ AgentMiddlewareRegistry = __decorate([
     'end'
 ];
 
-const AssistantTaskRuntimeCapability = createRuntimeCapability('platform.assistant_task', {
+/** Scoped runtime capability for platform Assistant tasks. */ const AssistantTaskRuntimeCapability = createRuntimeCapability('platform.assistant_task', {
     description: 'Start asynchronous tasks on the current platform assistant.'
 });
 
@@ -3987,6 +3952,52 @@ HandoffProcessorRegistry = __decorate([
     runTtlMs: 10 * 60 * 1000
 };
 
+/** Checks confirmed completion; unknown remains non-terminal. */ function isAgentInvocationTerminal(status) {
+    return status === 'succeeded' || status === 'failed' || status === 'cancelled';
+}
+
+/** Nest discovery metadata key for runtime strategies. */ const AGENT_RUNTIME_STRATEGY = 'AGENT_RUNTIME_STRATEGY';
+/** Associate a stable provider key with an adapter. Also declare @Injectable() and register the provider. */ const AgentRuntimeStrategy = (provider)=>applyDecorators(SetMetadata(AGENT_RUNTIME_STRATEGY, provider), SetMetadata(STRATEGY_META_KEY, AGENT_RUNTIME_STRATEGY));
+/** Scoped strategy registry with pinned provider/version lookup for continuation. */ let AgentRuntimeRegistry = class AgentRuntimeRegistry extends BaseStrategyRegistry {
+    /** Find the exact original scope/plugin/version, without fallback. Returns undefined if unavailable. */ getPinned(provider, source) {
+        var _this_strategies_get;
+        const strategy = (_this_strategies_get = this.strategies.get(source.scopeKey)) == null ? void 0 : _this_strategies_get.get(provider);
+        if (!strategy) return undefined;
+        const actual = this.getSource(strategy);
+        return actual.kind === source.kind && actual.scopeKey === source.scopeKey && (actual.kind !== 'plugin' || source.kind !== 'plugin' || actual.pluginName === source.pluginName && actual.pluginVersion === source.pluginVersion) ? strategy : undefined;
+    }
+    constructor(discoveryService, reflector){
+        super(AGENT_RUNTIME_STRATEGY, discoveryService, reflector);
+    }
+};
+AgentRuntimeRegistry = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [
+        DiscoveryService,
+        Reflector
+    ])
+], AgentRuntimeRegistry);
+
+/** Caller-scoped API obtained through runtime.capabilities.require(...). */ const AgentInvocationRuntimeCapability = createRuntimeCapability('platform.agent_invocation', {
+    description: 'Scoped, versioned Agent invocation and lifecycle control'
+});
+/** Platform factory capability. The wire key is stable across SDK naming changes. */ const AgentRuntimeFactoryCapability = createRuntimeCapability('platform.agent_invocation.factory');
+
+const ASSISTANT_CAPABILITY_PROVIDER = 'ASSISTANT_CAPABILITY_PROVIDER';
+const AssistantCapabilityProvider = (key)=>applyDecorators(SetMetadata(ASSISTANT_CAPABILITY_PROVIDER, key), SetMetadata(STRATEGY_META_KEY, ASSISTANT_CAPABILITY_PROVIDER));
+let AssistantCapabilityProviderRegistry = class AssistantCapabilityProviderRegistry extends BaseStrategyRegistry {
+    constructor(discovery, reflector){
+        super(ASSISTANT_CAPABILITY_PROVIDER, discovery, reflector);
+    }
+};
+AssistantCapabilityProviderRegistry = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [
+        DiscoveryService,
+        Reflector
+    ])
+], AssistantCapabilityProviderRegistry);
+
 /**
  * Common platform message length limits
  */ const CHAT_CHANNEL_TEXT_LIMITS = {
@@ -4281,10 +4292,12 @@ function appendSandboxMessage(output, message) {
 function resolveSandboxExecutionOptions(options, defaults = DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS) {
     const timeoutMs = typeof (options == null ? void 0 : options.timeoutMs) === 'number' && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? Math.trunc(options.timeoutMs) : typeof defaults.timeoutMs === 'number' && Number.isFinite(defaults.timeoutMs) && defaults.timeoutMs > 0 ? Math.trunc(defaults.timeoutMs) : DEFAULT_SANDBOX_SHELL_TIMEOUT_MS;
     const maxOutputBytes = typeof (options == null ? void 0 : options.maxOutputBytes) === 'number' && Number.isFinite(options.maxOutputBytes) && options.maxOutputBytes > 0 ? Math.trunc(options.maxOutputBytes) : typeof defaults.maxOutputBytes === 'number' && Number.isFinite(defaults.maxOutputBytes) && defaults.maxOutputBytes > 0 ? Math.trunc(defaults.maxOutputBytes) : DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES;
-    return {
+    return _extends({
         timeoutMs,
         maxOutputBytes
-    };
+    }, (options == null ? void 0 : options.signal) ? {
+        signal: options.signal
+    } : {});
 }
 
 function isObjectLike$2(value) {
@@ -5937,6 +5950,9 @@ EvolutionTargetProviderRegistry = __decorate([
 ], EvolutionTargetProviderRegistry);
 
 const EVOLUTION_RUNTIME_SERVICE_TOKEN = 'XPERT_EVOLUTION_RUNTIME_SERVICE';
+const EvolutionBaselineRuntimeCapability = createRuntimeCapability('platform.agent-evolution.baselines', {
+    description: 'Inspect and initialize organization rule baselines with administrator authorization and revision checks.'
+});
 const EvolutionRuntimeCapability = createRuntimeCapability('platform.agent-evolution', {
     description: 'Ingest learning signals and resolve immutable capability versions for domain runtimes.'
 });
@@ -6177,6 +6193,11 @@ function describeXpertToolProvider(instance) {
         if (middlewareProvider && !middlewareProviders.has(middlewareProvider)) {
             throw new Error(`Tool '${toolOptions.name}' references undeclared Middleware provider '${middlewareProvider}'.`);
         }
+        if (toolOptions.app) {
+            if (!middlewareProvider || !toolOptions.app.visibility.length || toolOptions.app.visibility.some((item)=>item !== 'model' && item !== 'app') || toolOptions.app.resourceKey && (!appKeys.has(toolOptions.app.resourceKey) || !toolOptions.app.visibility.includes('app'))) {
+                throw new Error(`Tool '${toolOptions.name}' has an invalid middleware App binding.`);
+            }
+        }
         const appKey = toolOptions.mcp && ((_toolOptions_mcp_app = toolOptions.mcp.app) == null ? void 0 : _toolOptions_mcp_app.resourceKey);
         if (appKey && !appKeys.has(appKey)) {
             throw new Error(`MCP Tool '${toolOptions.name}' references undeclared App '${appKey}'.`);
@@ -6574,12 +6595,21 @@ class DecoratedAgentMiddlewareStrategy {
         return this.descriptor.tools.filter((item)=>item.middlewareProvider === this.provider).map((item)=>item.options.name);
     }
     async createMiddleware(options, context) {
+        var _this_descriptor_options_apps;
         const tools = this.descriptor.tools.filter((item)=>item.middlewareProvider === this.provider).map((item)=>createAgentTool(this.instance, item, context, options));
         const extensions = await (this.instance.getMiddlewareExtensions == null ? void 0 : this.instance.getMiddlewareExtensions.call(this.instance, this.provider, options, context));
         return _extends({}, extensions != null ? extensions : {}, {
             name: this.provider,
             tools
-        });
+        }, ((_this_descriptor_options_apps = this.descriptor.options.apps) == null ? void 0 : _this_descriptor_options_apps.length) ? {
+            apps: {
+                definitions: this.descriptor.options.apps,
+                tools: Object.fromEntries(this.descriptor.tools.filter((item)=>item.middlewareProvider === this.provider && item.options.app).map((item)=>[
+                        item.options.name,
+                        item.options.app
+                    ]))
+            }
+        } : {});
     }
     constructor(instance, descriptor, provider){
         var _descriptor_options_middlewares;
@@ -9739,4 +9769,37 @@ function stableJson(value) {
     return `{${entries.map(([key, item])=>`${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
 }
 
-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, 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, 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, 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, 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, resolveXpertMcpExtensions, runWithRequestContext, runtimeToolProviderComponent, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage, textTokenBoundaries };
+const PROJECT_TYPE_PROVIDER = 'PROJECT_TYPE_PROVIDER';
+/** Register the stable provider key used by entity-backed App project type declarations. */ const ProjectTypeProvider = (key)=>applyDecorators(SetMetadata(PROJECT_TYPE_PROVIDER, key), SetMetadata(STRATEGY_META_KEY, PROJECT_TYPE_PROVIDER));
+let ProjectTypeProviderRegistry = class ProjectTypeProviderRegistry extends BaseStrategyRegistry {
+    constructor(discovery, reflector){
+        super(PROJECT_TYPE_PROVIDER, discovery, reflector);
+    }
+};
+ProjectTypeProviderRegistry = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [
+        DiscoveryService,
+        Reflector
+    ])
+], ProjectTypeProviderRegistry);
+
+const PROJECT_TASK_PROVIDER = 'PROJECT_TASK_PROVIDER';
+const ProjectTaskProvider = (key)=>applyDecorators(SetMetadata(PROJECT_TASK_PROVIDER, key), SetMetadata(STRATEGY_META_KEY, PROJECT_TASK_PROVIDER));
+let ProjectTaskProviderRegistry = class ProjectTaskProviderRegistry extends BaseStrategyRegistry {
+    constructor(discovery, reflector){
+        super(PROJECT_TASK_PROVIDER, discovery, reflector);
+    }
+};
+ProjectTaskProviderRegistry = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [
+        DiscoveryService,
+        Reflector
+    ])
+], ProjectTaskProviderRegistry);
+const ProjectTasksRuntimeCapability = createRuntimeCapability('platform.project.tasks', {
+    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_STRATEGY, AIModel, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ASSISTANT_CAPABILITY_PROVIDER, AdapterDataSourceStrategy, 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, 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, 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, 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, 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, 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, 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, isAgentInvocationTerminal, 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, resolveXpertMcpExtensions, runWithRequestContext, runtimeToolProviderComponent, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage, textTokenBoundaries };

package/package.json

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

package/runtime-capabilities.md

@@ -47,3 +47,38 @@ Reuse the returned API during that one operation. Create a new API for the next
 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.
+
+## Agent invocation
+
+Agent runtime extension contracts live under `src/lib/agent/runtime` and are
+exported from `@xpert-ai/plugin-sdk`. `AgentRuntimeFactory`, strategies and the
+registry describe the execution mechanism; `AgentInvocation*` types describe an
+individual call. Renaming the factory does not change capability identifiers.
+
+`AgentInvocationRuntimeCapability` is the scoped consumer API for invoking an
+approved Agent binding. Resolve the binding immediately before starting a call;
+provide the host tool-call/operation ID for idempotency. The API captures identity
+and rechecks workspace grants, target revision and provider provenance. Tools
+cannot supply user/organization identity or arbitrary runner configuration.
+
+```ts
+const api = context.runtime.capabilities.require(AgentInvocationRuntimeCapability)
+const target = await api.resolve(bindingId)
+const invocation = await api.start({ target, callId: toolCallId, input: { prompt } })
+// wait mode uses the host checkpoint adapter; background mode returns the ID.
+const completed = await api.awaitResult(invocation.id)
+```
+
+`inspect`, `cancel` and `respond` operate on the same invocation. A cancelling or
+unknown state is not proof of termination. Caller jobs may use
+`AgentRuntimeFactoryCapability` with a host-authorized identity;
+never accept that identity from model arguments.
+
+Providers implement `IAgentRuntimeStrategy` and use `@AgentRuntimeStrategy(key)`.
+Persist a receipt with `context.checkpoint` before waiting for external work.
+Declare checkpoint/session/no recovery accurately; reattachment must not send an
+ambiguous prompt again. The strategy contract contains no graph types. The host
+owns binding authorization, persistence, idempotency, waiting and audit history.
+The native Xpert graph and native background Task transports are separate
+strategies behind that same boundary. Providers must not call the Task facade
+back from their own executor.

package/src/index.d.ts

@@ -14,6 +14,7 @@ export * from './lib/data/index';
 export * from './lib/ai-model/index';
 export * from './lib/runtime/index';
 export * from './lib/agent/index';
+export * from './lib/assistant-capability/index';
 export * from './lib/channel/index';
 export * from './lib/file/index';
 export * from './lib/strategy';
@@ -27,3 +28,5 @@ export * from './lib/collaboration/index';
 export * from './lib/evolution/index';
 export * from './lib/mcp/index';
 export * from './lib/tool-provider/index';
+export * from './lib/project-type/index';
+export * from './lib/project-task/index';

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

@@ -1,3 +1,4 @@
 export * from './skill/index';
 export * from './middleware';
 export * from './handoff';
+export * from './runtime';

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

@@ -1,5 +1,7 @@
 import type { JSONValue, TAvatar } from '@xpert-ai/contracts';
+/** Task lifecycle snapshot. interrupted means paused; unknown does not confirm failure. */
 export type AgentMiddlewareAssistantTaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted' | 'unknown';
+/** Existing platform file reference; access remains subject to host authorization. */
 export type AgentMiddlewareAssistantTaskFile = {
     id?: string;
     fileId?: string;
@@ -13,33 +15,27 @@ export type AgentMiddlewareAssistantTaskFile = {
     role?: string;
 };
 /**
- * Stable plugin skill reference used by Assistant Tasks.
- *
- * Plugin-owned callers must not persist workspace-local SkillPackage UUIDs.
- * The host resolves this portable identity to the installed package and verifies
- * that the target Agent is directly connected to the owning Skills Middleware.
+ * Portable plugin skill identity, resolved through the target Agent's connected Skills Middleware.
+ * Do not persist workspace-local SkillPackage UUIDs in plugin configuration.
  */
 export type AgentMiddlewareAssistantTaskSkillRef = {
     pluginName: string;
     componentKey: string;
 };
-/**
- * Portable role identity used to resolve an organization-owned Assistant.
- * Instance UUIDs stay out of plugin contracts so the same workflow is deployable across organizations.
- */
+/** Portable plugin/template/Agent identity used to resolve a deployed Assistant. */
 export type AgentMiddlewareExternalAssistantExpectation = {
     pluginName: string;
     templateKey: string;
     agentKey: string;
 };
-/** Resolve the executor from the requester's required, direct external-Xpert connections. */
+/** Resolve the executor from the requester's required, direct published external-Assistant connections. */
 export type AgentMiddlewareAssistantTaskTarget = {
     kind: 'external_assistant';
     requesterXpertId: string;
     requesterAgentKey: string;
     expectation: AgentMiddlewareExternalAssistantExpectation;
 };
-/** Stable plugin-owned identity for reconciling platform executions with a domain operation. */
+/** Plugin-owned operation identity for reconciling executions with a domain subject. */
 export type AgentMiddlewareExecutionCorrelation = {
     namespace: string;
     operationId: string;
@@ -48,7 +44,7 @@ export type AgentMiddlewareExecutionCorrelation = {
 };
 /** Availability of a resolved external Assistant binding. */
 export type AgentMiddlewareExternalAssistantBindingStatus = 'available' | 'incompatible' | 'unpublished' | 'cross_organization';
-/** Safe external Assistant metadata that may cross plugin and View Host boundaries. */
+/** Binding display metadata; intentionally omits the deployed Assistant instance ID. */
 export type AgentMiddlewareExternalAssistantBinding = {
     title: string;
     name: string;
@@ -63,12 +59,12 @@ export type AgentMiddlewareExternalAssistantBinding = {
     publishedVersion?: string;
     status: AgentMiddlewareExternalAssistantBindingStatus;
 };
-/** Identifies the requester whose required direct bindings should be listed. */
+/** Requester whose required direct external-Assistant bindings should be listed. */
 export type AgentMiddlewareListExternalAssistantBindingsInput = {
     requesterXpertId: string;
     requesterAgentKey: string;
 };
-/** Selects correlated executions for one requester-owned domain subject. */
+/** Requester-scoped execution lookup for a plugin namespace and domain subject. */
 export type AgentMiddlewareListCorrelatedExecutionsInput = {
     requesterXpertId: string;
     requesterAgentKey: string;
@@ -76,7 +72,7 @@ export type AgentMiddlewareListCorrelatedExecutionsInput = {
     subjectId: string;
     limit?: number;
 };
-/** Safe execution summary returned to a plugin for domain reconciliation. */
+/** Execution receipt for domain reconciliation; executor fields identify the resolved published Assistant. */
 export type AgentMiddlewareCorrelatedExecution = {
     operationId: string;
     subjectId: string;
@@ -93,27 +89,32 @@ export type AgentMiddlewareCorrelatedExecution = {
     startedAt?: string;
     updatedAt?: string;
 };
+/** Start an asynchronous task on the current Assistant or a resolved external Assistant. */
 export type AgentMiddlewareAssistantTaskInput = {
+    /** Current/requesting Assistant ID; must match target.requesterXpertId when target is supplied. */
     xpertId: string;
-    /** Selects the Assistant base and Primary models; child Agents retain authored models. */
+    /** Selects the base/Primary model; child Agents retain authored models. */
     modelId?: string;
+    /** Entry Agent for the current Assistant; external targets use their resolved primary Agent. */
     agentKey?: string;
-    /** Resolve an organization-owned external Assistant from the requester's published graph. */
+    /** Optional external executor resolved from the requester's published graph. */
     target?: AgentMiddlewareAssistantTaskTarget;
     conversationId?: string | null;
     executionId?: string | null;
     projectId?: string | null;
     taskId?: string;
+    /** Per-run idempotency key. Otherwise correlation.operationId or executionId is used; taskId alone is insufficient. */
     clientMessageId?: string;
     prompt: string;
     files?: AgentMiddlewareAssistantTaskFile[];
-    /** Skills that this task is expected to load through its target Agent's Skills Middleware. */
+    /** Skills expected to load through the target Agent's connected Skills Middleware. */
     selectedSkillRefs?: AgentMiddlewareAssistantTaskSkillRef[];
-    /** Additional bounded human-input fields exposed to runtime-state fixed filters. */
+    /** Additional bounded runtime input; does not override the task prompt or files. */
     humanInput?: Record<string, JSONValue>;
     context?: Record<string, unknown>;
     correlation?: AgentMiddlewareExecutionCorrelation;
 };
+/** Task receipt, not necessarily a completed result. Use status and execution identifiers to follow progress. */
 export type AgentMiddlewareAssistantTaskResult = {
     status: AgentMiddlewareAssistantTaskStatus;
     taskId?: string;
@@ -127,6 +128,7 @@ export type AgentMiddlewareAssistantTaskResult = {
     executorAssistantTitle?: string;
     executorPublishedVersion?: string;
 };
+/** Host task/execution identifiers for lookup. Cancellation requires an execution, conversation or thread ID. */
 export type AgentMiddlewareAssistantTaskStatusInput = {
     taskId?: string;
     executionId?: string;
@@ -135,17 +137,50 @@ export type AgentMiddlewareAssistantTaskStatusInput = {
     clientMessageId?: string;
     xpertId?: string;
 };
+/** Platform executions affected by the cancellation request. */
 export type AgentMiddlewareAssistantTaskCancelResult = {
     canceledExecutionIds: string[];
 };
+/** Host Assistant Task API. Feature-detect optional methods before calling them. */
 export interface AgentMiddlewareAssistantTaskApi {
+    /**
+     * Verify that a running native delegate is the requester's bound external role.
+     *
+     * Re-resolves the requester's direct, required external-Assistant connections on
+     * every call. Exactly one candidate must match the plugin, template and primary
+     * Agent identity, be published and active in the same organization, and have
+     * the same instance ID as the actual executor. This only validates a binding;
+     * it does not create a task, invoke an Assistant or authorize domain artifacts.
+     *
+     * @param input - Requester identity, actual runtime executor and expected role.
+     * @param input.requesterXpertId - Assistant that owns the external connection.
+     * @param input.requesterAgentKey - The requesting Assistant's primary Agent key.
+     * @param input.executorXpertId - Actual executor ID from the trusted runtime context.
+     * @param input.expectation - Portable plugin, template and primary Agent identity.
+     * @returns Validated binding metadata with instance and workspace IDs omitted.
+     * @throws If the binding is missing, ambiguous, unpublished, incompatible, or
+     * the resolved instance differs from the runtime executor.
+     */
+    assertExternalAssistantBinding?(input: {
+        requesterXpertId: string;
+        requesterAgentKey: string;
+        executorXpertId: string;
+        expectation: {
+            pluginName: string;
+            templateKey: string;
+            agentKey: string;
+        };
+    }): Promise<AgentMiddlewareExternalAssistantBinding>;
     getModels?(xpertId: string): Promise<import('@xpert-ai/contracts').TAssistantModelsResponse>;
+    /** Submit once and retain the receipt; use getTaskStatus to follow asynchronous progress. */
     startTask(input: AgentMiddlewareAssistantTaskInput): Promise<AgentMiddlewareAssistantTaskResult>;
-    /** Return only safe binding descriptors; internal Assistant instance IDs are intentionally omitted. */
+    /** List safe binding descriptors without deployed Assistant instance IDs. */
     listExternalAssistantBindings?(input: AgentMiddlewareListExternalAssistantBindingsInput): Promise<AgentMiddlewareExternalAssistantBinding[]>;
     /** Read executions owned by the requester and its currently bound external Assistants. */
     listCorrelatedExecutions?(input: AgentMiddlewareListCorrelatedExecutionsInput): Promise<AgentMiddlewareCorrelatedExecution[]>;
+    /** Return the current receipt, or null if no matching task is found. */
     getTaskStatus?(input: AgentMiddlewareAssistantTaskStatusInput): Promise<AgentMiddlewareAssistantTaskResult | null>;
     cancelTask?(input: AgentMiddlewareAssistantTaskStatusInput): Promise<AgentMiddlewareAssistantTaskCancelResult>;
 }
+/** Scoped runtime capability for platform Assistant tasks. */
 export declare const AssistantTaskRuntimeCapability: import("../../../core/runtime-capability").RuntimeCapabilityKey<AgentMiddlewareAssistantTaskApi>;

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

@@ -107,7 +107,10 @@ export type AfterAgentHook<TSchema extends InteropZodObject | undefined = undefi
  */
 export interface ModelRequest<TState extends Record<string, unknown> = Record<string, unknown>, TContext = unknown> {
     /**
-     * The model to use for this step.
+     * The unbound model to use for this step. Middleware may replace it before
+     * the host binds the final tool selection or structured output schema.
+     * Replacements must expose bindTools/withStructuredOutput when those features
+     * are used. A plain Runnable is supported for calls without either feature.
      */
     model: LanguageModelLike;
     /**
@@ -116,7 +119,8 @@ export interface ModelRequest<TState extends Record<string, unknown> = Record<st
     messages: BaseMessage[];
     systemMessage?: SystemMessage;
     /**
-     * Tool choice configuration (model-specific format).
+     * Portable tool choice configuration, applied by the host after selection.
+     * A named tool must remain selected; "required" needs a non-empty selection.
      * Can be one of:
      * - `"auto"`: means the model can pick between generating a message or calling one or more tools.
      * - `"none"`: means the model will not call any tool and instead generates a message.
@@ -130,7 +134,11 @@ export interface ModelRequest<TState extends Record<string, unknown> = Record<st
         };
     };
     /**
-     * The tools to make available for this step.
+     * The registered tools to make available for this step. Return a subset of
+     * these instances (or an empty array) to change the model's available tools.
+     * New definitions, cloned tools and schema replacements require separate
+     * runtime registration so that every advertised tool has an execution route.
+     * Selection does not replace authorization at the tool execution boundary.
      */
     tools: (ServerTool | ClientTool)[];
     /**
@@ -225,6 +233,8 @@ export interface AgentMiddleware<TSchema extends InteropZodObject | undefined =
      */
     contextSchema?: TContextSchema;
     tools?: DynamicStructuredTool[];
+    /** Resource-backed MCP Apps and explicit model/App tool visibility. */
+    apps?: import('../../mcp/app').MiddlewareMcpApps;
     beforeAgent?: BeforeAgentHook<TSchema, TFullContext>;
     beforeModel?: BeforeModelHook<TSchema, TFullContext>;
     afterModel?: AfterModelHook<TSchema, TFullContext>;

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

@@ -0,0 +1,29 @@
+import type { AgentInvocation, AgentInvocationRequest, AgentJson, AgentTarget } from './types';
+import type { RuntimeIdentityScope } from '../../runtime/runtime-scope';
+/** Invocation API bound to one authorized caller/execution. Each operation revalidates access. */
+export interface AgentInvocationApi {
+    /** Resolve a binding to a pinned target. Optional on hosts with pre-resolved native targets. */
+    resolve?(bindingId: string): Promise<AgentTarget>;
+    /** Start or recover an idempotent request. The returned snapshot may still be running. */
+    start(request: AgentInvocationRequest): Promise<AgentInvocation>;
+    /** Refresh an existing invocation, possibly persisting provider observations. Never relaunches work. */
+    inspect(invocationId: string): Promise<AgentInvocation>;
+    /** Request supported cancellation; cancelling does not confirm termination. */
+    cancel(invocationId: string): Promise<AgentInvocation>;
+    /** Answer the current interaction using its exact ID and provider-defined response schema. */
+    respond(invocationId: string, interactionId: string, response: AgentJson): Promise<AgentInvocation>;
+    /**
+     * Optional checkpoint-aware wait; returns a terminal or unknown observation.
+     * Allow host suspension to propagate instead of treating it as a tool failure.
+     */
+    awaitResult?(invocationId: string): Promise<AgentInvocation>;
+}
+/** Caller-scoped API obtained through runtime.capabilities.require(...). */
+export declare const AgentInvocationRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<AgentInvocationApi>;
+/** Trusted host factory; scope must come from authenticated context, not model arguments. */
+export interface AgentRuntimeFactory {
+    /** Create an API per caller/execution. Do not cache it as a global singleton. */
+    createScopedApi(scope: RuntimeIdentityScope): AgentInvocationApi;
+}
+/** Platform factory capability. The wire key is stable across SDK naming changes. */
+export declare const AgentRuntimeFactoryCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<AgentRuntimeFactory>;

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

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './strategy';
+export * from './capability';