@xpert-ai/plugin-sdk 3.17.5 → 3.18.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @xpert-ai/plugin-sdk
 
+## 3.18.0
+
+### Minor Changes
+
+- 8e63a8b: Release Xpert 3.18.0.
+
+### Patch Changes
+
+- 477b711: Allow connector plugins to declare an embedded QR authorization presentation while the host manages polling and cancellation.
+- dad112d: Add authoritative Project View runtime scopes, membership and scheduling contracts, read/edit/manage action access, immutable Xpert workspace data scopes, scoped Connector bindings with personal or shared authorization, eligible expert providers, Project-scoped workspace files, and collaboration support.
+- 1c71b75: Add Project-scoped Connector authorization and scheduled tasks that run as a confirmed Project member.
+- d45a0c8: Add governed Project instructions and skills with sandbox read-only enforcement.
+- Updated dependencies [dad112d]
+- Updated dependencies [8e63a8b]
+- Updated dependencies [1c71b75]
+- Updated dependencies [d45a0c8]
+  - @xpert-ai/contracts@3.18.0
+
+## 3.17.6
+
+### Patch Changes
+
+- afb69b7: Release Xpert 3.17.6 after publishing the complete Sandbox Runtime image suite.
+- Updated dependencies [afb69b7]
+  - @xpert-ai/contracts@3.17.6
+
 ## 3.17.5
 
 ### Patch Changes

package/connector.cjs.js

@@ -1,5 +1,13 @@
 'use strict';
 
+const CONNECTOR_SCOPE_TYPES = [
+    'workspace',
+    'project'
+];
+const CONNECTOR_AUTHORIZATION_MODES = [
+    'personal',
+    'shared'
+];
 function getConnectorAuthMethods(definition) {
     var _definition_legacyAuthMethodId;
     if ('authMethods' in definition) {
@@ -17,6 +25,14 @@ function getConnectorAuthMethods(definition) {
         }
     ];
 }
+function getConnectorAuthorizationModes(definition) {
+    var _definition_authorizationModes;
+    return ((_definition_authorizationModes = definition.authorizationModes) == null ? void 0 : _definition_authorizationModes.length) ? [
+        ...definition.authorizationModes
+    ] : [
+        'shared'
+    ];
+}
 function assertConnectorDefinition(definition) {
     if (!isObjectValue(definition)) {
         throw new Error('Connector strategy must expose a valid connector definition');
@@ -32,8 +48,24 @@ function assertConnectorDefinition(definition) {
     }
     const auth = Reflect.get(definition, 'auth');
     const authMethods = Reflect.get(definition, 'authMethods');
+    const authorizationModes = Reflect.get(definition, 'authorizationModes');
     const resolvedMethods = [];
     const ids = new Set();
+    if (authorizationModes !== undefined) {
+        if (!Array.isArray(authorizationModes) || !authorizationModes.length) {
+            throw new Error(`Connector '${provider}' must declare at least one authorization mode`);
+        }
+        const seenModes = new Set();
+        for (const mode of authorizationModes){
+            if (mode !== 'personal' && mode !== 'shared') {
+                throw new Error(`Connector '${provider}' has unsupported authorization mode '${String(mode)}'`);
+            }
+            if (seenModes.has(mode)) {
+                throw new Error(`Connector '${provider}' has duplicate authorization mode '${mode}'`);
+            }
+            seenModes.add(mode);
+        }
+    }
     if (authMethods !== undefined) {
         if (!Array.isArray(authMethods) || !authMethods.length) {
             throw new Error(`Connector '${provider}' must declare at least one authentication method`);
@@ -98,6 +130,31 @@ function assertConnectorAuthMethod(method, provider) {
     if (type === 'api_key' && !isObjectValue(Reflect.get(method, 'credentials'))) {
         throw new Error(`Connector '${provider}' API key method '${idValue.trim()}' must declare credentials`);
     }
+    const authorizationPresentation = Reflect.get(method, 'authorizationPresentation');
+    if (authorizationPresentation !== undefined) {
+        assertConnectorAuthorizationPresentation(authorizationPresentation, provider, idValue.trim(), type);
+    }
+}
+function assertConnectorAuthorizationPresentation(value, provider, authMethodId, authMethodType) {
+    if (!isObjectValue(value) || Reflect.get(value, 'mode') !== 'embedded_qr') {
+        throw new Error(`Connector '${provider}' authentication method '${authMethodId}' has an invalid authorization presentation`);
+    }
+    if (authMethodType !== 'oauth2') {
+        throw new Error(`Connector '${provider}' authentication method '${authMethodId}' can declare authorization presentation only for OAuth`);
+    }
+    for (const field of [
+        'title',
+        'description',
+        'ariaLabel',
+        'completionHint',
+        'cancelLabel',
+        'copyLinkLabel',
+        'copyLinkError'
+    ]){
+        if (!isRuntimeI18nText(Reflect.get(value, field))) {
+            throw new Error(`Connector '${provider}' authentication method '${authMethodId}' authorization presentation must declare '${field}'`);
+        }
+    }
 }
 function isConnectorOAuthConfig(value) {
     return isObjectValue(value) && Reflect.get(value, 'type') === 'oauth2';
@@ -112,5 +169,8 @@ function isObjectValue(value) {
     return typeof value === 'object' && value !== null;
 }
 
+exports.CONNECTOR_AUTHORIZATION_MODES = CONNECTOR_AUTHORIZATION_MODES;
+exports.CONNECTOR_SCOPE_TYPES = CONNECTOR_SCOPE_TYPES;
 exports.assertConnectorDefinition = assertConnectorDefinition;
 exports.getConnectorAuthMethods = getConnectorAuthMethods;
+exports.getConnectorAuthorizationModes = getConnectorAuthorizationModes;

package/connector.esm.js

@@ -1,3 +1,11 @@
+const CONNECTOR_SCOPE_TYPES = [
+    'workspace',
+    'project'
+];
+const CONNECTOR_AUTHORIZATION_MODES = [
+    'personal',
+    'shared'
+];
 function getConnectorAuthMethods(definition) {
     var _definition_legacyAuthMethodId;
     if ('authMethods' in definition) {
@@ -15,6 +23,14 @@ function getConnectorAuthMethods(definition) {
         }
     ];
 }
+function getConnectorAuthorizationModes(definition) {
+    var _definition_authorizationModes;
+    return ((_definition_authorizationModes = definition.authorizationModes) == null ? void 0 : _definition_authorizationModes.length) ? [
+        ...definition.authorizationModes
+    ] : [
+        'shared'
+    ];
+}
 function assertConnectorDefinition(definition) {
     if (!isObjectValue(definition)) {
         throw new Error('Connector strategy must expose a valid connector definition');
@@ -30,8 +46,24 @@ function assertConnectorDefinition(definition) {
     }
     const auth = Reflect.get(definition, 'auth');
     const authMethods = Reflect.get(definition, 'authMethods');
+    const authorizationModes = Reflect.get(definition, 'authorizationModes');
     const resolvedMethods = [];
     const ids = new Set();
+    if (authorizationModes !== undefined) {
+        if (!Array.isArray(authorizationModes) || !authorizationModes.length) {
+            throw new Error(`Connector '${provider}' must declare at least one authorization mode`);
+        }
+        const seenModes = new Set();
+        for (const mode of authorizationModes){
+            if (mode !== 'personal' && mode !== 'shared') {
+                throw new Error(`Connector '${provider}' has unsupported authorization mode '${String(mode)}'`);
+            }
+            if (seenModes.has(mode)) {
+                throw new Error(`Connector '${provider}' has duplicate authorization mode '${mode}'`);
+            }
+            seenModes.add(mode);
+        }
+    }
     if (authMethods !== undefined) {
         if (!Array.isArray(authMethods) || !authMethods.length) {
             throw new Error(`Connector '${provider}' must declare at least one authentication method`);
@@ -96,6 +128,31 @@ function assertConnectorAuthMethod(method, provider) {
     if (type === 'api_key' && !isObjectValue(Reflect.get(method, 'credentials'))) {
         throw new Error(`Connector '${provider}' API key method '${idValue.trim()}' must declare credentials`);
     }
+    const authorizationPresentation = Reflect.get(method, 'authorizationPresentation');
+    if (authorizationPresentation !== undefined) {
+        assertConnectorAuthorizationPresentation(authorizationPresentation, provider, idValue.trim(), type);
+    }
+}
+function assertConnectorAuthorizationPresentation(value, provider, authMethodId, authMethodType) {
+    if (!isObjectValue(value) || Reflect.get(value, 'mode') !== 'embedded_qr') {
+        throw new Error(`Connector '${provider}' authentication method '${authMethodId}' has an invalid authorization presentation`);
+    }
+    if (authMethodType !== 'oauth2') {
+        throw new Error(`Connector '${provider}' authentication method '${authMethodId}' can declare authorization presentation only for OAuth`);
+    }
+    for (const field of [
+        'title',
+        'description',
+        'ariaLabel',
+        'completionHint',
+        'cancelLabel',
+        'copyLinkLabel',
+        'copyLinkError'
+    ]){
+        if (!isRuntimeI18nText(Reflect.get(value, field))) {
+            throw new Error(`Connector '${provider}' authentication method '${authMethodId}' authorization presentation must declare '${field}'`);
+        }
+    }
 }
 function isConnectorOAuthConfig(value) {
     return isObjectValue(value) && Reflect.get(value, 'type') === 'oauth2';
@@ -110,4 +167,4 @@ function isObjectValue(value) {
     return typeof value === 'object' && value !== null;
 }
 
-export { assertConnectorDefinition, getConnectorAuthMethods };
+export { CONNECTOR_AUTHORIZATION_MODES, CONNECTOR_SCOPE_TYPES, assertConnectorDefinition, getConnectorAuthMethods, getConnectorAuthorizationModes };

package/index.cjs.js

@@ -32,7 +32,7 @@ var documents = require('@langchain/core/documents');
 var chat_models = require('@langchain/core/language_models/chat_models');
 var env = require('@langchain/core/utils/env');
 var modelProviderHttpClient = require('./model-provider-http-client.cjs.js');
-require('js-tiktoken');
+var jsTiktoken = require('js-tiktoken');
 var base$1 = require('@langchain/core/language_models/base');
 var connector = require('./connector.cjs.js');
 var collaborationClient = require('./collaboration-client.cjs.js');
@@ -3144,8 +3144,8 @@ function estimateFallbackUsage(prompts, completion) {
             totalTokens: 0
         };
     }
-    const promptTokens = estimateTokens(prompts.join('\n'));
-    const completionTokens = estimateTokens(completion != null ? completion : '');
+    const promptTokens = estimateTokens$1(prompts.join('\n'));
+    const completionTokens = estimateTokens$1(completion != null ? completion : '');
     return {
         promptTokens,
         completionTokens,
@@ -3156,7 +3156,7 @@ function readCompletionText(output) {
     var _output_generations;
     return (_output_generations = output.generations) == null ? void 0 : _output_generations.flat().map((generation)=>generation.text).filter(Boolean).join('\n');
 }
-function estimateTokens(text) {
+function estimateTokens$1(text) {
     const estimatedText = text.replace(/data:image\/[a-zA-Z0-9.+-]+;base64,[a-zA-Z0-9+/_=-]+/g, '[image]');
     let cjkCharacters = 0;
     let otherCharacters = 0;
@@ -3580,12 +3580,60 @@ class Speech2TextChatModel extends chat_models.BaseChatModel {
     }
 }
 
+const encodingCache = new Map();
+/**
+ * Fallback token estimation method.
+ *
+ * 思路:
+ * - 英文：约 4 chars / token
+ * - 中文：约 1.5 chars / token
+ * - Mixed：按字符区分
+ */ function estimateTokens(text) {
+    if (!text) return 0;
+    let cn = 0;
+    let en = 0;
+    for (const ch of text){
+        if (/[\u4e00-\u9fa5]/.test(ch)) {
+            cn++;
+        } else {
+            en++;
+        }
+    }
+    // 中文 1 token ≈ 1.5 chars
+    const cnTokens = cn / 1.5;
+    // 英文 1 token ≈ 4 chars
+    const enTokens = en / 4;
+    return Math.ceil(cnTokens + enTokens);
+}
 /**
  * Count tokens in text
  * 1) Preferred: js-tiktoken precise encoding
  * 2) Fallback: estimated token count
  */ function countTokensSafe(text, opts) {
-    return 0;
+    if (!text) return 0;
+    try {
+        let resolvedEncoding;
+        if (opts == null ? void 0 : opts.encodingName) {
+            resolvedEncoding = String(opts.encodingName);
+        } else if (opts == null ? void 0 : opts.model) {
+            var _getEncodingNameForModel;
+            resolvedEncoding = (_getEncodingNameForModel = jsTiktoken.getEncodingNameForModel(opts.model)) != null ? _getEncodingNameForModel : 'cl100k_base';
+        } else {
+            resolvedEncoding = 'cl100k_base';
+        }
+        // Prefer exact token count via js-tiktoken
+        const cacheKey = (opts == null ? void 0 : opts.model) ? `model:${opts.model}` : `encoding:${resolvedEncoding}`;
+        let enc = encodingCache.get(cacheKey);
+        if (!enc) {
+            enc = (opts == null ? void 0 : opts.model) ? jsTiktoken.encodingForModel(opts.model) : jsTiktoken.getEncoding(resolvedEncoding);
+            encodingCache.set(cacheKey, enc);
+        }
+        const tokens = enc.encode(text);
+        return tokens.length;
+    } catch (e) {
+        // Provider-specific model names are not always known by js-tiktoken.
+        return estimateTokens(text);
+    }
 }
 
 function getModelContextSize(input) {
@@ -5833,8 +5881,11 @@ exports.createRuntimeCapability = modelProvider.createRuntimeCapability;
 exports.isSandboxJobRuntimeError = modelProvider.isSandboxJobRuntimeError;
 exports.ModelProviderHttpClient = modelProviderHttpClient.ModelProviderHttpClient;
 exports.ModelProviderHttpError = modelProviderHttpClient.ModelProviderHttpError;
+exports.CONNECTOR_AUTHORIZATION_MODES = connector.CONNECTOR_AUTHORIZATION_MODES;
+exports.CONNECTOR_SCOPE_TYPES = connector.CONNECTOR_SCOPE_TYPES;
 exports.assertConnectorDefinition = connector.assertConnectorDefinition;
 exports.getConnectorAuthMethods = connector.getConnectorAuthMethods;
+exports.getConnectorAuthorizationModes = connector.getConnectorAuthorizationModes;
 exports.base64ToBytes = collaborationClient.base64ToBytes;
 exports.bytesToBase64 = collaborationClient.bytesToBase64;
 exports.createCollaborationClient = collaborationClient.createCollaborationClient;

package/index.esm.js

@@ -35,10 +35,10 @@ import { Document } from '@langchain/core/documents';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { getEnvironmentVariable } from '@langchain/core/utils/env';
 export { ModelProviderHttpClient, ModelProviderHttpError } from './model-provider-http-client.esm.js';
-import 'js-tiktoken';
+import { getEncodingNameForModel, encodingForModel, getEncoding } from 'js-tiktoken';
 import { getModelContextSize as getModelContextSize$1 } from '@langchain/core/language_models/base';
 import { assertConnectorDefinition } from './connector.esm.js';
-export { getConnectorAuthMethods } 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 '@langchain/core/tools';
 import 'zod/v3';
@@ -3126,8 +3126,8 @@ function estimateFallbackUsage(prompts, completion) {
             totalTokens: 0
         };
     }
-    const promptTokens = estimateTokens(prompts.join('\n'));
-    const completionTokens = estimateTokens(completion != null ? completion : '');
+    const promptTokens = estimateTokens$1(prompts.join('\n'));
+    const completionTokens = estimateTokens$1(completion != null ? completion : '');
     return {
         promptTokens,
         completionTokens,
@@ -3138,7 +3138,7 @@ function readCompletionText(output) {
     var _output_generations;
     return (_output_generations = output.generations) == null ? void 0 : _output_generations.flat().map((generation)=>generation.text).filter(Boolean).join('\n');
 }
-function estimateTokens(text) {
+function estimateTokens$1(text) {
     const estimatedText = text.replace(/data:image\/[a-zA-Z0-9.+-]+;base64,[a-zA-Z0-9+/_=-]+/g, '[image]');
     let cjkCharacters = 0;
     let otherCharacters = 0;
@@ -3562,12 +3562,60 @@ class Speech2TextChatModel extends BaseChatModel {
     }
 }
 
+const encodingCache = new Map();
+/**
+ * Fallback token estimation method.
+ *
+ * 思路:
+ * - 英文：约 4 chars / token
+ * - 中文：约 1.5 chars / token
+ * - Mixed：按字符区分
+ */ function estimateTokens(text) {
+    if (!text) return 0;
+    let cn = 0;
+    let en = 0;
+    for (const ch of text){
+        if (/[\u4e00-\u9fa5]/.test(ch)) {
+            cn++;
+        } else {
+            en++;
+        }
+    }
+    // 中文 1 token ≈ 1.5 chars
+    const cnTokens = cn / 1.5;
+    // 英文 1 token ≈ 4 chars
+    const enTokens = en / 4;
+    return Math.ceil(cnTokens + enTokens);
+}
 /**
  * Count tokens in text
  * 1) Preferred: js-tiktoken precise encoding
  * 2) Fallback: estimated token count
  */ function countTokensSafe(text, opts) {
-    return 0;
+    if (!text) return 0;
+    try {
+        let resolvedEncoding;
+        if (opts == null ? void 0 : opts.encodingName) {
+            resolvedEncoding = String(opts.encodingName);
+        } else if (opts == null ? void 0 : opts.model) {
+            var _getEncodingNameForModel;
+            resolvedEncoding = (_getEncodingNameForModel = getEncodingNameForModel(opts.model)) != null ? _getEncodingNameForModel : 'cl100k_base';
+        } else {
+            resolvedEncoding = 'cl100k_base';
+        }
+        // Prefer exact token count via js-tiktoken
+        const cacheKey = (opts == null ? void 0 : opts.model) ? `model:${opts.model}` : `encoding:${resolvedEncoding}`;
+        let enc = encodingCache.get(cacheKey);
+        if (!enc) {
+            enc = (opts == null ? void 0 : opts.model) ? encodingForModel(opts.model) : getEncoding(resolvedEncoding);
+            encodingCache.set(cacheKey, enc);
+        }
+        const tokens = enc.encode(text);
+        return tokens.length;
+    } catch (e) {
+        // Provider-specific model names are not always known by js-tiktoken.
+        return estimateTokens(text);
+    }
 }
 
 function getModelContextSize(input) {

package/model-provider-toolset.cjs.js

@@ -1,8 +1,8 @@
 'use strict';
 
 var modelProvider = require('./model-provider.cjs.js');
-require('@xpert-ai/contracts');
 require('./_extends.cjs.js');
+require('@xpert-ai/contracts');
 require('@nestjs/common');
 require('@langchain/core/tools');
 require('zod/v3');

package/model-provider-toolset.esm.js

@@ -1,6 +1,6 @@
 export { M as ModelProviderBuiltinToolset } from './model-provider.esm.js';
-import '@xpert-ai/contracts';
 import './_extends.esm.js';
+import '@xpert-ai/contracts';
 import '@nestjs/common';
 import '@langchain/core/tools';
 import 'zod/v3';

package/model-provider.cjs.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var contracts = require('@xpert-ai/contracts');
 var _extends = require('./_extends.cjs.js');
+var contracts = require('@xpert-ai/contracts');
 var common = require('@nestjs/common');
 var tools = require('@langchain/core/tools');
 var v3 = require('zod/v3');
@@ -189,7 +189,7 @@ const KnowledgebaseProvisioningRuntimeCapability = createRuntimeCapability('plat
 });
 
 const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
-    description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
+    description: 'Upload, import, create, process, reprocess, inspect, and delete persistent knowledgebase documents.'
 });
 
 const KnowledgeDocumentVisualAssetsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.visual-assets', {
@@ -277,36 +277,23 @@ const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.p
         return match[1];
     }
     getWorkspaceFiles() {
-        var _this_runtimeCapabilities;
-        const workspaceFiles = (_this_runtimeCapabilities = this.runtimeCapabilities) == null ? void 0 : _this_runtimeCapabilities.get(WorkspaceFilesRuntimeCapability);
+        var _this_params_runtimeCapabilities, _this_params;
+        const workspaceFiles = (_this_params = this.params) == null ? void 0 : (_this_params_runtimeCapabilities = _this_params.runtimeCapabilities) == null ? void 0 : _this_params_runtimeCapabilities.get(WorkspaceFilesRuntimeCapability);
         if (!workspaceFiles) {
             throw new Error(this.modelProviderOptions.missingWorkspaceMessage);
         }
         return workspaceFiles;
     }
     createWorkspaceScope() {
-        var _this_params, _this_params1, _this_params2;
-        const projectId = normalizeOptionalString((_this_params = this.params) == null ? void 0 : _this_params.projectId);
-        if (projectId) {
-            var _this_params3, _this_params4;
-            return {
-                tenantId: normalizeOptionalString((_this_params3 = this.params) == null ? void 0 : _this_params3.tenantId),
-                userId: normalizeOptionalString((_this_params4 = this.params) == null ? void 0 : _this_params4.userId),
-                catalog: 'projects',
-                scopeId: projectId,
-                projectId
-            };
+        var _this_params, _this_params1;
+        const runtimeScope = (_this_params = this.params) == null ? void 0 : _this_params.runtimeScope;
+        if (runtimeScope) {
+            return normalizeWorkspaceScope(runtimeScope);
         }
-        const xpertId = normalizeOptionalString(this.xpertId);
-        if (!xpertId) return undefined;
-        return {
-            tenantId: normalizeOptionalString((_this_params1 = this.params) == null ? void 0 : _this_params1.tenantId),
-            userId: normalizeOptionalString((_this_params2 = this.params) == null ? void 0 : _this_params2.userId),
-            catalog: 'xperts',
-            scopeId: xpertId,
-            xpertId,
-            isolateByUser: false
-        };
+        if (normalizeOptionalString((_this_params1 = this.params) == null ? void 0 : _this_params1.projectId) || normalizeOptionalString(this.xpertId)) {
+            throw new Error(this.modelProviderOptions.missingWorkspaceMessage);
+        }
+        return undefined;
     }
     async createAsyncModelClient(model, modality, purpose = 'invoke') {
         const modelProvider = await this.getModelProviderRuntime();
@@ -336,16 +323,48 @@ const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.p
             modelType
         }, {});
     }
-    constructor(modelProviderOptions, toolset, runtimeCapabilities, params){
+    constructor(modelProviderOptions, toolset, _runtimeCapabilities, params){
         super(modelProviderOptions.toolsetProviderName, toolset, params);
         this.modelProviderOptions = modelProviderOptions;
-        this.runtimeCapabilities = runtimeCapabilities;
     }
 }
 function normalizeOptionalString(value) {
     const normalized = value == null ? void 0 : value.trim();
     return normalized || undefined;
 }
+function normalizeWorkspaceScope(scope) {
+    const tenantId = normalizeOptionalString(scope.tenantId);
+    const organizationId = normalizeOptionalString(scope.organizationId);
+    const userId = normalizeOptionalString(scope.userId);
+    var _scope_catalog;
+    const catalog = (_scope_catalog = scope.catalog) != null ? _scope_catalog : undefined;
+    const scopeId = normalizeOptionalString(scope.scopeId);
+    const projectId = normalizeOptionalString(scope.projectId);
+    const knowledgeId = normalizeOptionalString(scope.knowledgeId);
+    const rootId = normalizeOptionalString(scope.rootId);
+    const xpertId = normalizeOptionalString(scope.xpertId);
+    return _extends._extends({}, tenantId ? {
+        tenantId
+    } : {}, organizationId ? {
+        organizationId
+    } : {}, userId ? {
+        userId
+    } : {}, catalog ? {
+        catalog
+    } : {}, scopeId ? {
+        scopeId
+    } : {}, projectId ? {
+        projectId
+    } : {}, knowledgeId ? {
+        knowledgeId
+    } : {}, rootId ? {
+        rootId
+    } : {}, xpertId ? {
+        xpertId
+    } : {}, typeof scope.isolateByUser === 'boolean' ? {
+        isolateByUser: scope.isolateByUser
+    } : {});
+}
 
 exports.ActorTokenRuntimeCapability = ActorTokenRuntimeCapability;
 exports.ArtifactsRuntimeCapability = ArtifactsRuntimeCapability;

package/model-provider.esm.js

@@ -1,5 +1,5 @@
-import { AiModelTypeEnum } from '@xpert-ai/contracts';
 import { _ as _extends } from './_extends.esm.js';
+import { AiModelTypeEnum } from '@xpert-ai/contracts';
 import { Logger } from '@nestjs/common';
 import { BaseToolkit, StructuredTool } from '@langchain/core/tools';
 import { z } from 'zod/v3';
@@ -187,7 +187,7 @@ const KnowledgebaseProvisioningRuntimeCapability = createRuntimeCapability('plat
 });
 
 const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.documents', {
-    description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
+    description: 'Upload, import, create, process, reprocess, inspect, and delete persistent knowledgebase documents.'
 });
 
 const KnowledgeDocumentVisualAssetsRuntimeCapability = createRuntimeCapability('platform.knowledgebase.visual-assets', {
@@ -275,36 +275,23 @@ const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.p
         return match[1];
     }
     getWorkspaceFiles() {
-        var _this_runtimeCapabilities;
-        const workspaceFiles = (_this_runtimeCapabilities = this.runtimeCapabilities) == null ? void 0 : _this_runtimeCapabilities.get(WorkspaceFilesRuntimeCapability);
+        var _this_params_runtimeCapabilities, _this_params;
+        const workspaceFiles = (_this_params = this.params) == null ? void 0 : (_this_params_runtimeCapabilities = _this_params.runtimeCapabilities) == null ? void 0 : _this_params_runtimeCapabilities.get(WorkspaceFilesRuntimeCapability);
         if (!workspaceFiles) {
             throw new Error(this.modelProviderOptions.missingWorkspaceMessage);
         }
         return workspaceFiles;
     }
     createWorkspaceScope() {
-        var _this_params, _this_params1, _this_params2;
-        const projectId = normalizeOptionalString((_this_params = this.params) == null ? void 0 : _this_params.projectId);
-        if (projectId) {
-            var _this_params3, _this_params4;
-            return {
-                tenantId: normalizeOptionalString((_this_params3 = this.params) == null ? void 0 : _this_params3.tenantId),
-                userId: normalizeOptionalString((_this_params4 = this.params) == null ? void 0 : _this_params4.userId),
-                catalog: 'projects',
-                scopeId: projectId,
-                projectId
-            };
+        var _this_params, _this_params1;
+        const runtimeScope = (_this_params = this.params) == null ? void 0 : _this_params.runtimeScope;
+        if (runtimeScope) {
+            return normalizeWorkspaceScope(runtimeScope);
         }
-        const xpertId = normalizeOptionalString(this.xpertId);
-        if (!xpertId) return undefined;
-        return {
-            tenantId: normalizeOptionalString((_this_params1 = this.params) == null ? void 0 : _this_params1.tenantId),
-            userId: normalizeOptionalString((_this_params2 = this.params) == null ? void 0 : _this_params2.userId),
-            catalog: 'xperts',
-            scopeId: xpertId,
-            xpertId,
-            isolateByUser: false
-        };
+        if (normalizeOptionalString((_this_params1 = this.params) == null ? void 0 : _this_params1.projectId) || normalizeOptionalString(this.xpertId)) {
+            throw new Error(this.modelProviderOptions.missingWorkspaceMessage);
+        }
+        return undefined;
     }
     async createAsyncModelClient(model, modality, purpose = 'invoke') {
         const modelProvider = await this.getModelProviderRuntime();
@@ -334,15 +321,47 @@ const ProjectProvisioningRuntimeCapability = createRuntimeCapability('platform.p
             modelType
         }, {});
     }
-    constructor(modelProviderOptions, toolset, runtimeCapabilities, params){
+    constructor(modelProviderOptions, toolset, _runtimeCapabilities, params){
         super(modelProviderOptions.toolsetProviderName, toolset, params);
         this.modelProviderOptions = modelProviderOptions;
-        this.runtimeCapabilities = runtimeCapabilities;
     }
 }
 function normalizeOptionalString(value) {
     const normalized = value == null ? void 0 : value.trim();
     return normalized || undefined;
 }
+function normalizeWorkspaceScope(scope) {
+    const tenantId = normalizeOptionalString(scope.tenantId);
+    const organizationId = normalizeOptionalString(scope.organizationId);
+    const userId = normalizeOptionalString(scope.userId);
+    var _scope_catalog;
+    const catalog = (_scope_catalog = scope.catalog) != null ? _scope_catalog : undefined;
+    const scopeId = normalizeOptionalString(scope.scopeId);
+    const projectId = normalizeOptionalString(scope.projectId);
+    const knowledgeId = normalizeOptionalString(scope.knowledgeId);
+    const rootId = normalizeOptionalString(scope.rootId);
+    const xpertId = normalizeOptionalString(scope.xpertId);
+    return _extends({}, tenantId ? {
+        tenantId
+    } : {}, organizationId ? {
+        organizationId
+    } : {}, userId ? {
+        userId
+    } : {}, catalog ? {
+        catalog
+    } : {}, scopeId ? {
+        scopeId
+    } : {}, projectId ? {
+        projectId
+    } : {}, knowledgeId ? {
+        knowledgeId
+    } : {}, rootId ? {
+        rootId
+    } : {}, xpertId ? {
+        xpertId
+    } : {}, typeof scope.isolateByUser === 'boolean' ? {
+        isolateByUser: scope.isolateByUser
+    } : {});
+}
 
 export { ActorTokenRuntimeCapability as A, BaseTool as B, DefaultRuntimeCapabilityRegistry as D, KnowledgeDocumentVisualAssetsRuntimeCapability as K, ModelProviderBuiltinToolset as M, ProjectProvisioningRuntimeCapability as P, SANDBOX_JOB_ERROR_CODES as S, WORKSPACE_FILES_SOURCE as W, XPERT_RUNTIME_CAPABILITIES_TOKEN as X, ArtifactsRuntimeCapability as a, BaseToolset as b, createRuntimeCapability as c, BuiltinToolset as d, KnowledgebaseDocumentsRuntimeCapability as e, KnowledgebaseProvisioningRuntimeCapability as f, KnowledgebaseRuntimeCapability as g, SANDBOX_JOB_PROGRESS_PREFIX as h, SandboxJobRuntimeError as i, SandboxJobsRuntimeCapability as j, WorkspaceFilesRuntimeCapability as k, isSandboxJobRuntimeError as l };

package/package.json

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

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

@@ -1,4 +1,4 @@
-import type { JSONValue } from '@xpert-ai/contracts';
+import type { JSONValue, TAvatar } from '@xpert-ai/contracts';
 export type AgentMiddlewareAssistantTaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'interrupted' | 'unknown';
 export type AgentMiddlewareAssistantTaskFile = {
     id?: string;
@@ -23,9 +23,81 @@ 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.
+ */
+export type AgentMiddlewareExternalAssistantExpectation = {
+    pluginName: string;
+    templateKey: string;
+    agentKey: string;
+};
+/** Resolve the executor from the requester's required, direct external-Xpert 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. */
+export type AgentMiddlewareExecutionCorrelation = {
+    namespace: string;
+    operationId: string;
+    subjectId: string;
+    attributes?: Record<string, JSONValue>;
+};
+/** 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. */
+export type AgentMiddlewareExternalAssistantBinding = {
+    title: string;
+    name: string;
+    avatar?: TAvatar;
+    templateSource: {
+        templateId: string;
+        templateKey: string;
+        pluginName?: string;
+        source?: string;
+    } | null;
+    primaryAgentKey?: string;
+    publishedVersion?: string;
+    status: AgentMiddlewareExternalAssistantBindingStatus;
+};
+/** Identifies the requester whose required direct bindings should be listed. */
+export type AgentMiddlewareListExternalAssistantBindingsInput = {
+    requesterXpertId: string;
+    requesterAgentKey: string;
+};
+/** Selects correlated executions for one requester-owned domain subject. */
+export type AgentMiddlewareListCorrelatedExecutionsInput = {
+    requesterXpertId: string;
+    requesterAgentKey: string;
+    namespace: string;
+    subjectId: string;
+    limit?: number;
+};
+/** Safe execution summary returned to a plugin for domain reconciliation. */
+export type AgentMiddlewareCorrelatedExecution = {
+    operationId: string;
+    subjectId: string;
+    attributes?: Record<string, JSONValue>;
+    status: AgentMiddlewareAssistantTaskStatus;
+    executionId: string;
+    parentExecutionId?: string;
+    threadId?: string;
+    executorXpertId: string;
+    executorAgentKey?: string;
+    executorAssistantTemplateKey?: string;
+    executorAssistantTitle?: string;
+    executorPublishedVersion?: string;
+    startedAt?: string;
+    updatedAt?: string;
+};
 export type AgentMiddlewareAssistantTaskInput = {
     xpertId: string;
     agentKey?: string;
+    /** Resolve an organization-owned external Assistant from the requester's published graph. */
+    target?: AgentMiddlewareAssistantTaskTarget;
     conversationId?: string | null;
     executionId?: string | null;
     projectId?: string | null;
@@ -38,6 +110,7 @@ export type AgentMiddlewareAssistantTaskInput = {
     /** Additional bounded human-input fields exposed to runtime-state fixed filters. */
     humanInput?: Record<string, JSONValue>;
     context?: Record<string, unknown>;
+    correlation?: AgentMiddlewareExecutionCorrelation;
 };
 export type AgentMiddlewareAssistantTaskResult = {
     status: AgentMiddlewareAssistantTaskStatus;
@@ -46,6 +119,11 @@ export type AgentMiddlewareAssistantTaskResult = {
     conversationId?: string;
     threadId?: string;
     errorMessage?: string;
+    executorXpertId?: string;
+    executorAgentKey?: string;
+    executorAssistantTemplateKey?: string;
+    executorAssistantTitle?: string;
+    executorPublishedVersion?: string;
 };
 export type AgentMiddlewareAssistantTaskStatusInput = {
     taskId?: string;
@@ -60,6 +138,10 @@ export type AgentMiddlewareAssistantTaskCancelResult = {
 };
 export interface AgentMiddlewareAssistantTaskApi {
     startTask(input: AgentMiddlewareAssistantTaskInput): Promise<AgentMiddlewareAssistantTaskResult>;
+    /** Return only safe binding descriptors; internal Assistant instance IDs are intentionally omitted. */
+    listExternalAssistantBindings?(input: AgentMiddlewareListExternalAssistantBindingsInput): Promise<AgentMiddlewareExternalAssistantBinding[]>;
+    /** Read executions owned by the requester and its currently bound external Assistants. */
+    listCorrelatedExecutions?(input: AgentMiddlewareListCorrelatedExecutionsInput): Promise<AgentMiddlewareCorrelatedExecution[]>;
     getTaskStatus?(input: AgentMiddlewareAssistantTaskStatusInput): Promise<AgentMiddlewareAssistantTaskResult | null>;
     cancelTask?(input: AgentMiddlewareAssistantTaskStatusInput): Promise<AgentMiddlewareAssistantTaskCancelResult>;
 }

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 { WorkspaceFileCatalog } from '../../runtime/capabilities/workspace-files';
 export * from './runtime-capability';
 export * from './capabilities';
 /**
@@ -99,10 +100,19 @@ export type AgentMiddlewareRuntimeScope = {
     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/agent/middleware/strategy.interface.d.ts

@@ -1,4 +1,4 @@
-import { IWFNMiddleware, TAgentMiddlewareMeta, TXpertFeatures } from '@xpert-ai/contracts';
+import { IWFNMiddleware, TAgentMiddlewareMeta, TXpertFeatures, XpertWorkspaceDataScope } from '@xpert-ai/contracts';
 import { StructuredToolInterface } from '@langchain/core/tools';
 import { RunnableToolLike } from '@langchain/core/runnables';
 import { BaseStore } from '@langchain/langgraph';
@@ -12,7 +12,9 @@ export interface IAgentMiddlewareContext {
     workspaceId?: string;
     projectId?: string;
     conversationId?: string;
+    threadId?: string;
     xpertId?: string;
+    workspaceDataScope?: XpertWorkspaceDataScope | null;
     xpertFeatures?: TXpertFeatures | null;
     agentKey?: string;
     knowledgebaseIds?: string[];

package/src/lib/connector/strategy.interface.d.ts

@@ -2,6 +2,17 @@ import type { I18nText, IconDefinition } from '@xpert-ai/contracts';
 export type RuntimeI18nText = I18nText;
 export type RuntimeCapabilityIcon = IconDefinition;
 export type ConnectorStatus = 'pending' | 'active' | 'expired' | 'error' | 'disconnected';
+export declare const CONNECTOR_SCOPE_TYPES: readonly ["workspace", "project"];
+export type ConnectorScopeType = (typeof CONNECTOR_SCOPE_TYPES)[number];
+export type ConnectorScope = {
+    type: 'workspace';
+    workspaceId: string;
+} | {
+    type: 'project';
+    projectId: string;
+};
+export declare const CONNECTOR_AUTHORIZATION_MODES: readonly ["personal", "shared"];
+export type ConnectorAuthorizationMode = (typeof CONNECTOR_AUTHORIZATION_MODES)[number];
 export type ConnectorOAuthConfig = {
     type: 'oauth2';
     authorizationUrl?: string;
@@ -28,17 +39,28 @@ export type ConnectorAppCredentialsConfig = {
     defaultValues?: Record<string, string | number | boolean | null>;
 };
 export type ConnectorCredentialFormDefinition = ConnectorAppCredentialsConfig;
-export type ConnectorAuthMethodDefinition = {
+export type ConnectorAuthorizationPresentation = {
+    mode: 'embedded_qr';
+    title: RuntimeI18nText;
+    description: RuntimeI18nText;
+    ariaLabel: RuntimeI18nText;
+    completionHint: RuntimeI18nText;
+    cancelLabel: RuntimeI18nText;
+    copyLinkLabel: RuntimeI18nText;
+    copyLinkError: RuntimeI18nText;
+};
+type ConnectorAuthMethodBase = {
     id: string;
-    type: 'oauth2';
     label: RuntimeI18nText;
+    authorizationPresentation?: ConnectorAuthorizationPresentation;
+};
+export type ConnectorAuthMethodDefinition = ConnectorAuthMethodBase & ({
+    type: 'oauth2';
     appCredentials?: ConnectorCredentialFormDefinition;
 } | {
-    id: string;
     type: 'api_key';
-    label: RuntimeI18nText;
     credentials: ConnectorCredentialFormDefinition;
-};
+});
 export type ConnectorPermissionDeclaration = {
     key: string;
     label?: RuntimeI18nText;
@@ -55,6 +77,8 @@ export type ConnectorDefinitionBase = {
     description?: RuntimeI18nText;
     icon?: RuntimeCapabilityIcon;
     permissions?: ConnectorPermissionDeclaration[];
+    /** Credential ownership modes supported by this provider. Legacy providers are shared-only. */
+    authorizationModes?: ConnectorAuthorizationMode[];
     /** Maps credentials stored before multi-auth support to a declared OAuth method. */
     legacyAuthMethodId?: string;
 };
@@ -70,6 +94,7 @@ export type ConnectorMultiAuthDefinition = ConnectorDefinitionBase & {
 };
 export type ConnectorStrategyDefinition = ConnectorDefinition | ConnectorMultiAuthDefinition;
 export declare function getConnectorAuthMethods(definition: ConnectorStrategyDefinition): ConnectorAuthMethodDefinition[];
+export declare function getConnectorAuthorizationModes(definition: ConnectorStrategyDefinition): ConnectorAuthorizationMode[];
 export declare function assertConnectorDefinition(definition: unknown): asserts definition is ConnectorStrategyDefinition;
 export type ConnectorProfile = {
     openId?: string;
@@ -82,7 +107,12 @@ export type ConnectorProfile = {
 };
 export type ConnectorInstance = {
     id: string;
-    workspaceId: string;
+    /** @deprecated Prefer scope. */
+    workspaceId?: string | null;
+    projectId?: string | null;
+    scopeType?: ConnectorScopeType;
+    scope?: ConnectorScope;
+    authorizationMode?: ConnectorAuthorizationMode;
     provider: string;
     authMethodId?: string | null;
     status: ConnectorStatus;
@@ -98,12 +128,53 @@ export type ConnectorInstance = {
     createdAt?: string;
     updatedAt?: string;
 };
+export type ConnectorBinding = ConnectorInstance & {
+    scopeType: ConnectorScopeType;
+    scope: ConnectorScope;
+    authorizationMode: ConnectorAuthorizationMode;
+};
+export type ConnectorBindingCreateRequest = {
+    scope: ConnectorScope;
+    provider: string;
+    authorizationMode: ConnectorAuthorizationMode;
+};
+export type ConnectorRuntimeOption = {
+    bindingId: string;
+    provider: string;
+    authorizationMode: ConnectorAuthorizationMode;
+    status: ConnectorStatus;
+    granted: boolean;
+    label: RuntimeI18nText;
+    description?: RuntimeI18nText;
+    icon?: RuntimeCapabilityIcon;
+    /** Sanitized authentication forms needed to connect the current user's account. */
+    authMethods?: ConnectorAuthMethodDefinition[];
+    profile?: ConnectorProfile | null;
+};
+export type ConnectorRuntimeOptions = {
+    scope: ConnectorScope;
+    items: ConnectorRuntimeOption[];
+};
+export type ConnectorPersonalAccountInstance = {
+    id: string;
+    provider: string;
+    status: ConnectorStatus;
+    authMethodId?: string | null;
+    profile?: ConnectorProfile | null;
+    scopes?: string[];
+    expiresAt?: string | null;
+    connectedAt?: string | null;
+    disconnectedAt?: string | null;
+    lastError?: string | null;
+};
 export type ConnectorOAuthStartRequest = {
     app?: ConnectorAppCredentialPayload;
 };
 export type ConnectorConnectRequest = {
     authMethodId?: string;
     values?: ConnectorAppCredentialPayload;
+    /** Assistant proving run access when a non-member authorizes a personal Workspace connector. */
+    xpertId?: string;
     /** @deprecated Use values instead. */
     app?: ConnectorAppCredentialPayload;
 };
@@ -122,6 +193,8 @@ export type ConnectorOAuthStartResponse = {
 };
 export type ConnectorOAuthStatusResponse = {
     connector: ConnectorInstance;
+    /** Whether this binding currently has a usable credential for the requesting user. */
+    granted?: boolean;
     authorizationUrl?: string | null;
     stateExpiresAt?: string | null;
     pollIntervalSeconds?: number | null;
@@ -129,7 +202,11 @@ export type ConnectorOAuthStatusResponse = {
 };
 export type ConnectorRuntimeCredential = {
     connectorId: string;
-    workspaceId: string;
+    bindingId: string;
+    scope: ConnectorScope;
+    authorizationMode: ConnectorAuthorizationMode;
+    workspaceId?: string | null;
+    projectId?: string | null;
     provider: string;
     appId: string;
     brand?: string;
@@ -140,7 +217,11 @@ export type ConnectorRuntimeCredential = {
 };
 export type ConnectorRuntimeCredentialV2 = {
     connectorId: string;
-    workspaceId: string;
+    bindingId: string;
+    scope: ConnectorScope;
+    authorizationMode: ConnectorAuthorizationMode;
+    workspaceId?: string | null;
+    projectId?: string | null;
     provider: string;
     authMethodId: string;
     credentials: Record<string, unknown>;
@@ -149,8 +230,12 @@ export type ConnectorRuntimeCredentialV2 = {
     profile?: ConnectorProfile | null;
 };
 export type ConnectorRuntimeGetInput = {
-    workspaceId: string;
-    provider: string;
+    bindingId?: string;
+    /** @deprecated Use bindingId. */
+    workspaceId?: string;
+    projectId?: string;
+    provider?: string;
+    /** @deprecated Use bindingId. */
     connectorId?: string;
 };
 export interface ConnectorRuntimeApi {
@@ -261,6 +346,12 @@ export type ConnectorCredentialRefreshInput = {
     authMethodId: string;
     credential: ConnectorCredential;
 };
+export type ConnectorCredentialRevokeReason = 'disconnect' | 'delete' | 'rotate';
+export type ConnectorCredentialRevokeInput = {
+    authMethodId: string;
+    credential: ConnectorCredential;
+    reason: ConnectorCredentialRevokeReason;
+};
 export type ConnectorRuntimeCredentialResolveInput = {
     authMethodId: string;
     credential: ConnectorCredential;
@@ -295,6 +386,11 @@ export interface ConnectorStrategyRuntime {
     exchangeAuthorizationCode?(input: ConnectorAuthorizationCodeInput): Promise<ConnectorCredential>;
     pollConnection?(input: ConnectorConnectionPollInput): Promise<ConnectorConnectionPollResult>;
     refreshConnectionCredential?(input: ConnectorCredentialRefreshInput): Promise<ConnectorCredential>;
+    /**
+     * Revokes a provider-side credential before the host destroys a shared credential locally.
+     * Implementations should be idempotent. Hosts remain compatible with providers that omit this hook.
+     */
+    revokeCredential?(input: ConnectorCredentialRevokeInput): Promise<void>;
     resolveRuntimeCredential?(input: ConnectorRuntimeCredentialResolveInput): Promise<Record<string, unknown>> | Record<string, unknown>;
     buildAuthorizationUrl?(input: ConnectorAuthorizationUrlInput): Promise<ConnectorAuthorizationUrlResult>;
     exchangeOAuthCode?(input: ConnectorOAuthCodeInput): Promise<ConnectorOAuthCredential>;
@@ -310,3 +406,4 @@ export interface ConnectorMultiAuthStrategy extends ConnectorStrategyRuntime {
     definition: ConnectorMultiAuthDefinition;
     connect(input: ConnectorConnectInput): Promise<ConnectorConnectResult>;
 }
+export {};

package/src/lib/rag/image/strategy.interface.d.ts

@@ -1,18 +1,37 @@
 import { DocumentInterface } from '@langchain/core/documents';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import { IDocumentUnderstandingProvider, IKnowledgeDocument } from '@xpert-ai/contracts';
+import type { JSONValue } from '@xpert-ai/contracts';
 import { Permissions, XpFileSystem } from '../../core/index';
 import { ChunkMetadata } from '../types';
 export type TImageUnderstandingConfig = {
     stage: 'test' | 'prod';
-    visionModel: BaseChatModel;
+    /**
+     * Host-resolved vision model. Strategies that declare that the current
+     * configuration does not need vision may receive no model.
+     */
+    visionModel?: BaseChatModel;
     permissions?: {
         fileSystem?: XpFileSystem;
     };
 };
+export type TImageUnderstandingMetadata = {
+    /**
+     * Optional, JSON-safe metadata merged into the owning Knowledge document.
+     *
+     * Strategies must not place raw file bytes, vectors, credentials, or
+     * unrestricted OCR transcripts here. The host persists this value only at
+     * the document boundary so downstream plugins can inspect processing
+     * outcomes without parsing retrieval chunks.
+     */
+    documentMetadata?: Record<string, JSONValue>;
+    /** Provider-specific, non-persistent warnings consumed by the host. */
+    warnings?: unknown;
+    [key: string]: unknown;
+};
 export type TImageUnderstandingResult = {
     chunks: DocumentInterface<Partial<ChunkMetadata>>[];
-    metadata: any;
+    metadata?: TImageUnderstandingMetadata;
 };
 export interface IImageUnderstandingStrategy<TConfig extends TImageUnderstandingConfig = TImageUnderstandingConfig> {
     readonly permissions: Permissions;
@@ -24,6 +43,15 @@ export interface IImageUnderstandingStrategy<TConfig extends TImageUnderstanding
      * Validate the configuration
      */
     validateConfig(config: TConfig): Promise<void>;
+    /**
+     * Declares whether this invocation needs the host to resolve a vision model.
+     *
+     * The default is `true` for backwards compatibility. This hook is evaluated
+     * before model resolution so strategies can support deterministic branches,
+     * such as rebuilding retrieval text from trusted user-provided metadata,
+     * without depending on model availability.
+     */
+    requiresVisionModel?(config: Readonly<Partial<TConfig>>): boolean | Promise<boolean>;
     /**
      * Understand image files (e.g., OCR, VLM, Chart Parsing)
      */

package/src/lib/runtime/capabilities/knowledgebase-documents.d.ts

@@ -1,4 +1,5 @@
 import { type I18nObject, JSONValue } from '@xpert-ai/contracts';
+import type { WorkspacePortableFileReference } from './workspace-files';
 export type KnowledgebaseDocumentFile = {
     buffer: Buffer;
     originalname?: string;
@@ -148,6 +149,16 @@ export type KnowledgebaseStartProcessingInput = {
     knowledgebaseId?: string;
     documentIds: string[];
 };
+/**
+ * Re-runs authorized Knowledge documents with a replacement parser contract.
+ * The host resolves tenant and organization scope from the current runtime;
+ * callers cannot move documents between Knowledge bases through this API.
+ */
+export type KnowledgebaseReprocessDocumentsInput = {
+    knowledgebaseId: string;
+    documentIds: string[];
+    parserConfig: KnowledgebaseDocumentParserConfig;
+};
 export type KnowledgebaseDocumentStatusInput = {
     knowledgebaseId?: string;
     documentIds: string[];
@@ -165,6 +176,29 @@ export type KnowledgebaseDeleteDocumentsResult = {
     deletedDocumentCount: number;
     missingDocumentIds?: string[];
 };
+/** Identifies one standalone image document inside an already authorized Knowledge base. */
+export type KnowledgebaseReadImageInput = {
+    knowledgebaseId: string;
+    documentId: string;
+};
+/**
+ * Server-only image payload for plugin middleware.
+ *
+ * The `reference` is suitable for governed file flows, while `buffer` exists
+ * only for server-side validation or copying. Never expose either value
+ * directly to a model or iframe.
+ */
+export type KnowledgebaseReadImageResult = {
+    knowledgebaseId: string;
+    documentId: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    sourceHash?: string | null;
+    /** Scoped browser/file resolver reference. Never expose it to a model. */
+    reference: WorkspacePortableFileReference;
+    buffer: Buffer;
+};
 export interface KnowledgebaseDocumentsApi {
     listDocuments(input: KnowledgebaseListDocumentsInput): Promise<KnowledgebaseListDocumentsResult>;
     createFolder(input: KnowledgebaseCreateFolderInput): Promise<KnowledgebaseCreateFolderResult>;
@@ -173,7 +207,10 @@ export interface KnowledgebaseDocumentsApi {
     importArchive(input: KnowledgebaseImportArchiveInput): Promise<KnowledgebaseImportArchiveResult>;
     createDocuments(input: KnowledgebaseCreateDocumentsInput): Promise<KnowledgebaseCreateDocumentsResult>;
     startProcessing(input: KnowledgebaseStartProcessingInput): Promise<KnowledgebaseDocumentStatusResult>;
+    reprocessDocuments(input: KnowledgebaseReprocessDocumentsInput): Promise<KnowledgebaseDocumentStatusResult>;
     getDocumentStatus(input: KnowledgebaseDocumentStatusInput): Promise<KnowledgebaseDocumentStatusResult>;
     deleteDocuments(input: KnowledgebaseDeleteDocumentsInput): Promise<KnowledgebaseDeleteDocumentsResult>;
+    /** Reads original bytes after the host revalidates Knowledge and document scope. */
+    readImage(input: KnowledgebaseReadImageInput): Promise<KnowledgebaseReadImageResult>;
 }
 export declare const KnowledgebaseDocumentsRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<KnowledgebaseDocumentsApi>;

package/src/lib/runtime/capabilities/knowledgebase.d.ts

@@ -38,6 +38,7 @@ export type KnowledgebaseListItem = {
     id: string;
     name?: string;
     description?: string | null;
+    applicationTags?: string[];
     type?: string | null;
     status?: string | null;
     permission?: string | null;

package/src/lib/runtime/capabilities/project-provisioning.d.ts

@@ -1,13 +1,23 @@
 /** Lifecycle states that plugin-managed Projects may synchronize to the platform. */
 export type ProjectProvisioningStatus = 'active' | 'archived';
+/** Portable identity of one required, direct External Assistant binding. */
+export type ProjectExternalAssistantExpectation = {
+    pluginName: string;
+    templateKey: string;
+    agentKey: string;
+};
 /** Stable identity and desired state for an idempotently provisioned Chat Project. */
 export type ProjectEnsureInput = {
     /** Caller-generated id reused across retries to prevent duplicate Projects. */
     projectId: string;
-    /** Workspace that owns both the Project and connected Assistant. */
-    workspaceId: string;
+    /** @deprecated Projects no longer belong to a Workspace. Accepted only for legacy callers. */
+    workspaceId?: string;
     /** Assistant that must be connected to the Project. */
     xpertId: string;
+    /** Primary requester Agent used as the trust anchor for direct External Assistants. */
+    requesterAgentKey?: string;
+    /** Portable External Assistant identities that must all validate before any Project mutation. */
+    externalAssistantExpectations?: ProjectExternalAssistantExpectation[];
     /** Current business-project display name. */
     name: string;
     /** Current business-project lifecycle state. */
@@ -16,7 +26,8 @@ export type ProjectEnsureInput = {
 /** Effective Project state after an idempotent ensure operation. */
 export type ProjectEnsureResult = {
     projectId: string;
-    workspaceId: string;
+    /** @deprecated Echoed only when supplied by a legacy caller. */
+    workspaceId?: string;
     /** Complete set of Assistants connected after synchronization. */
     xpertIds: string[];
     /** Whether this call inserted the Project or reconciled an existing one. */

package/src/lib/runtime/capabilities/workspace-files.d.ts

@@ -1,5 +1,5 @@
 /** Logical workspace volume catalog supported by plugin-facing file APIs. */
-export type WorkspaceFileCatalog = 'projects' | 'users' | 'knowledges' | 'skills' | 'xperts';
+export type WorkspaceFileCatalog = 'projects' | 'users' | 'knowledges' | 'skills' | 'xperts' | 'user-xperts';
 /** Stable source identifier for portable workspace file references. */
 export declare const WORKSPACE_FILES_SOURCE: "platform.workspace.files";
 /**

package/src/lib/sandbox/sandbox.interface.d.ts

@@ -31,6 +31,8 @@ export type SandboxProviderCreateOptions = {
      * Explicit mapping between the server-visible volume root and the sandbox-visible workspace root.
      */
     workspaceBinding?: SandboxWorkspaceBinding;
+    /** Trusted Project scope hint for providers that can enforce read-only Project Content. */
+    protectProjectContent?: true;
     /**
      * Canonical sandbox environment identifier that owns the container lifecycle.
      */
@@ -68,9 +70,15 @@ export type SandboxProviderCreateOptions = {
         id: string;
     };
 };
+export type SandboxProviderCapabilities = {
+    /** The provider enforces project.md and skills as read-only inside the runtime. */
+    projectContentReadOnly: boolean;
+};
 export interface ISandboxProvider<T extends SandboxBackendProtocol = SandboxBackendProtocol> {
     type: string;
     meta: TSandboxProviderMeta;
+    /** Optional for backward compatibility; protected requests treat absence as unsupported. */
+    readonly capabilities?: SandboxProviderCapabilities;
     /**
      * Whether this provider is currently available in this deployment.
      * Providers without an availability hook remain available for backward compatibility.

package/src/lib/toolset/builtin.d.ts

@@ -4,7 +4,8 @@ import { I18nObject, IXpertToolset, ToolProviderCredentials, TToolCredentials, T
 import { Logger } from '@nestjs/common';
 import { CommandBus, QueryBus } from '@nestjs/cqrs';
 import { BaseToolset } from './toolset';
-import type { AgentMiddlewareModelProviderConnection, AgentMiddlewareRuntimeApi } from '../agent/middleware/runtime';
+import type { AgentMiddlewareModelProviderConnection, AgentMiddlewareRuntimeApi, AgentMiddlewareRuntimeScope } from '../agent/middleware/runtime';
+import type { RuntimeCapabilityResolver } from '../core/runtime-capability';
 import type { ManagedQueueService } from '../managed-queue';
 import type { McpCapabilityDefinitions, McpCapabilityRuntimeProvider } from '../mcp';
 /**
@@ -34,6 +35,10 @@ export type TBuiltinToolsetParams = TToolsetParams & {
     queryBus: QueryBus;
     store?: BaseStore;
     modelRuntime?: TToolModelRuntime;
+    /** Host-bound capabilities for this execution; these override installation-level plugin capabilities. */
+    runtimeCapabilities?: RuntimeCapabilityResolver;
+    /** Authoritative execution scope used by scoped capabilities and delayed plugin jobs. */
+    runtimeScope?: AgentMiddlewareRuntimeScope;
     managedQueue?: ManagedQueueService;
     /** Installation scope used to route jobs back to this plugin instance. */
     pluginScopeKey?: string;

package/src/lib/toolset/model-provider.d.ts

@@ -18,9 +18,8 @@ export type ModelProviderBuiltinToolsetOptions = {
  */
 export declare abstract class ModelProviderBuiltinToolset<T extends StructuredToolInterface = StructuredToolInterface, C = TToolCredentials> extends BuiltinToolset<T, C> {
     private readonly modelProviderOptions;
-    private readonly runtimeCapabilities?;
     private modelProvider?;
-    constructor(modelProviderOptions: ModelProviderBuiltinToolsetOptions, toolset?: IXpertToolset, runtimeCapabilities?: RuntimeCapabilityResolver, params?: TBuiltinToolsetParams);
+    constructor(modelProviderOptions: ModelProviderBuiltinToolsetOptions, toolset?: IXpertToolset, _runtimeCapabilities?: RuntimeCapabilityResolver, params?: TBuiltinToolsetParams);
     _validateCredentials(_credentials: C): Promise<void>;
     protected getModelProviderRuntime(): Promise<TToolModelProviderRuntime>;
     protected getModelProviderCredential(modelProvider: TToolModelProviderRuntime): string;