@xpert-ai/plugin-sdk 3.15.9 → 3.15.10

package/index.esm.js

@@ -2775,6 +2775,10 @@ const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platfor
     description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
 });
 
+const ArtifactsRuntimeCapability = createRuntimeCapability('platform.artifacts', {
+    description: 'Create, version, preview, download, share, archive, and delete platform-managed plugin and Agent artifacts.'
+});
+
 /** Stable source identifier for portable workspace file references. */ const WORKSPACE_FILES_SOURCE = 'platform.workspace.files';
 const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.workspace.files', {
     description: 'Upload, understand, read, and delete raw files in Xpert workspace volumes.'
@@ -4666,4 +4670,410 @@ function escapeInlineScript(value) {
 
 const VIEW_EXTENSION_CACHE_SERVICE_TOKEN = 'XPERT_PLUGIN_VIEW_EXTENSION_CACHE_SERVICE';
 
-export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CommonParameterRules, ConnectorRuntimeCapability, ConnectorStrategyKey, ConnectorStrategyRegistry, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC, DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS, DEFAULT_SANDBOX_SHELL_TIMEOUT_MS, DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DefaultRuntimeCapabilityRegistry as DefaultAgentMiddlewareRuntimeCapabilityRegistry, DefaultRuntimeCapabilityRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, FILE_STORAGE_PROVIDER, FILE_UPLOAD_TARGET_STRATEGY, FileRuntimeCapability, FileStorageProvider, FileStorageProviderRegistry, FileUploadTargetRegistry, FileUploadTargetStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, KnowledgebaseDocumentsRuntimeCapability, KnowledgebaseRuntimeCapability, LLMUsage, LargeLanguageModel, MANAGED_CONNECTION_REGISTRY_TOKEN, MANAGED_QUEUE_HANDLER_REGISTRY_TOKEN, MANAGED_QUEUE_SERVICE_TOKEN, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_JOB_PROCESSOR_METADATA, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, PluginJobProcessor, PluginWebhookAuth, PluginWebhookAuthGuard, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SKILL_SOURCE_PROVIDER, SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN, SPEECH_TO_TEXT_SERVICE_TOKEN, SSOProviderRegistry, SSOProviderStrategyKey, SSO_BINDING_PERMISSION_SERVICE_TOKEN, SSO_PROVIDER, STRATEGY_META_KEY, SYSTEM_GLOBAL_SCOPE, SandboxProviderRegistry, SandboxProviderStrategy, 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, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WORKSPACE_FILES_SOURCE, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WorkspaceFilesRuntimeCapability, WrapWorkflowNodeExecutionCommand, XPERT_RUNTIME_CAPABILITIES_TOKEN, XpFileSystem, XpertServerPlugin, als, appendSandboxMessage, buildSandboxTimeoutMessage, calcTokenUsage, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, derivePluginArtifactNamespace, downloadRemoteFile, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, pluginArtifactTableName, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveTenantGlobalScopeKey, runWithRequestContext, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage };
+/** Platform-owned real-time collaboration capability available to scoped plugin runtimes. */ const CollaborationRuntimeCapability = createRuntimeCapability('platform.collaboration', {
+    description: 'Create, synchronize, persist, authorize, and observe platform-managed real-time collaboration documents.'
+});
+
+const COLLABORATION_DOCUMENT_PROVIDER = 'COLLABORATION_DOCUMENT_PROVIDER';
+/** Register a plugin adapter for one stable collaboration resource type. */ const CollaborationDocumentProvider = (providerKey)=>applyDecorators(SetMetadata(COLLABORATION_DOCUMENT_PROVIDER, providerKey), SetMetadata(STRATEGY_META_KEY, COLLABORATION_DOCUMENT_PROVIDER));
+
+/** Discovers system and organization-scoped collaboration providers from loaded plugins. */ let CollaborationDocumentProviderRegistry = class CollaborationDocumentProviderRegistry extends BaseStrategyRegistry {
+    constructor(discoveryService, reflector){
+        super(COLLABORATION_DOCUMENT_PROVIDER, discoveryService, reflector);
+    }
+};
+CollaborationDocumentProviderRegistry = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [
+        DiscoveryService,
+        Reflector
+    ])
+], CollaborationDocumentProviderRegistry);
+
+function createSocketIoTransportAdapter(socket) {
+    return {
+        get connected () {
+            return socket.connected;
+        },
+        get clientId () {
+            var _socket_id;
+            return (_socket_id = socket.id) != null ? _socket_id : null;
+        },
+        connect: ()=>{
+            socket.connect();
+        },
+        disconnect: ()=>{
+            socket.disconnect();
+        },
+        emit: (event, payload = {})=>{
+            socket.emit(event, payload);
+        },
+        on: (event, handler)=>{
+            socket.on(event, handler);
+            return ()=>{
+                socket.off(event, handler);
+            };
+        }
+    };
+}
+/** Wrap a caller-owned `Y.Doc` without passing it across the runtime capability boundary. */ function createYjsDocumentAdapter(document, yjs) {
+    return {
+        applyUpdate: (update, origin)=>yjs.applyUpdate(document, update, origin),
+        encodeStateVector: ()=>yjs.encodeStateVector(document),
+        mergeUpdates: (updates)=>yjs.mergeUpdates(updates),
+        onUpdate: (handler)=>{
+            document.on('update', handler);
+            return ()=>document.off('update', handler);
+        }
+    };
+}
+/**
+ * Keep per-client sessions for cursors while exposing one collaborator per stable actor identity.
+ * This prevents a second tab owned by the same user from either duplicating or hiding that user.
+ */ function createCollaborationPresenceStore(options = {}) {
+    let selfClientId = null;
+    let sessions = new Map();
+    const readSnapshot = ()=>{
+        const activeSessions = Array.from(sessions.values()).sort((left, right)=>right.updatedAt - left.updatedAt);
+        const remoteSessions = activeSessions.filter((item)=>item.clientId !== selfClientId);
+        const actors = new Map();
+        for (const item of activeSessions)if (!actors.has(item.presenceId)) actors.set(item.presenceId, item);
+        if (options.includeSelf !== false && options.selfActor) {
+            const existing = activeSessions.find((item)=>{
+                var _options_selfActor;
+                return item.clientId === selfClientId || item.presenceId === ((_options_selfActor = options.selfActor) == null ? void 0 : _options_selfActor.presenceId);
+            });
+            actors.set(options.selfActor.presenceId, existing != null ? existing : actorPresence(options.selfActor, selfClientId));
+        }
+        const collaborators = Array.from(actors.values()).sort((left, right)=>{
+            var _options_selfActor, _options_selfActor1;
+            const leftSelf = left.presenceId === ((_options_selfActor = options.selfActor) == null ? void 0 : _options_selfActor.presenceId) ? 1 : 0;
+            const rightSelf = right.presenceId === ((_options_selfActor1 = options.selfActor) == null ? void 0 : _options_selfActor1.presenceId) ? 1 : 0;
+            return rightSelf - leftSelf || right.updatedAt - left.updatedAt;
+        });
+        return {
+            selfClientId,
+            sessions: activeSessions,
+            remoteSessions,
+            collaborators
+        };
+    };
+    const publish = ()=>options.onChange == null ? void 0 : options.onChange.call(options, readSnapshot());
+    return {
+        setSelfClientId: (clientId)=>{
+            selfClientId = clientId;
+            publish();
+        },
+        replace: (items, clientId = selfClientId)=>{
+            selfClientId = clientId;
+            sessions = new Map(items.map((item)=>[
+                    item.clientId,
+                    item
+                ]));
+            publish();
+        },
+        upsert: (item)=>{
+            sessions.set(item.clientId, item);
+            publish();
+        },
+        remove: (clientId)=>{
+            if (sessions.delete(clientId)) publish();
+        },
+        clear: ()=>{
+            sessions.clear();
+            selfClientId = null;
+            publish();
+        },
+        snapshot: readSnapshot
+    };
+}
+/**
+ * Create a collaboration client with update batching, state-vector repair, presence heartbeat,
+ * and reconnect synchronization. The caller retains ownership of the document and transport.
+ */ function createCollaborationClient(options) {
+    const remoteOrigin = Object.freeze({
+        kind: 'platform.collaboration.remote'
+    });
+    const batchMs = positiveInteger(options.batchMs, 40);
+    const syncIntervalMs = positiveInteger(options.syncIntervalMs, 2000);
+    const presenceHeartbeatMs = positiveInteger(options.presenceHeartbeatMs, 5000);
+    const presenceStaleMs = positiveInteger(options.presenceStaleMs, 15000);
+    var _options_initialPresence;
+    let presence = _extends({}, (_options_initialPresence = options.initialPresence) != null ? _options_initialPresence : {});
+    let pending = [];
+    let flushTimer;
+    let syncTimer;
+    let presenceTimer;
+    let presenceCleanupTimer;
+    var _options_transport_clientId;
+    let selfClientId = (_options_transport_clientId = options.transport.clientId) != null ? _options_transport_clientId : null;
+    let started = false;
+    const cleanups = [];
+    const presenceSeenAt = new Map();
+    const reportError = (error)=>options.onError == null ? void 0 : options.onError.call(options, error instanceof Error ? error : new Error(String(error)));
+    const emitPresence = ()=>options.transport.emit('presence', _extends({}, presence));
+    // Merge the short burst of local Yjs transactions into one network update.
+    const flush = ()=>{
+        if (flushTimer) clearTimeout(flushTimer);
+        flushTimer = undefined;
+        if (!pending.length || !options.transport.connected) return;
+        const updates = pending;
+        pending = [];
+        options.transport.emit('update', {
+            updateBase64: bytesToBase64(options.document.mergeUpdates(updates)),
+            origin: 'plugin-client'
+        });
+    };
+    // A state vector lets the server return only bytes missing from this client.
+    const requestSync = ()=>{
+        if (!options.transport.connected) return;
+        options.transport.emit('sync-request', {
+            stateVectorBase64: bytesToBase64(options.document.encodeStateVector())
+        });
+    };
+    // Mark server updates with `remoteOrigin` so the document observer does not send them back.
+    const applyRemote = (payload)=>{
+        const encoded = stringValue(payload['updateBase64']);
+        if (!encoded) return;
+        try {
+            options.document.applyUpdate(base64ToBytes(encoded), remoteOrigin);
+        } catch (error) {
+            reportError(error);
+        }
+    };
+    // Register listeners once, then start repair and presence heartbeats before opening the socket.
+    const connect = ()=>{
+        if (started) return;
+        started = true;
+        options.onConnectionChange == null ? void 0 : options.onConnectionChange.call(options, 'connecting');
+        cleanups.push(options.document.onUpdate((update, origin)=>{
+            if (origin === remoteOrigin) return;
+            pending.push(update);
+            if (!flushTimer) flushTimer = setTimeout(flush, batchMs);
+        }));
+        cleanups.push(options.transport.on('connect', ()=>{
+            var _options_transport_clientId;
+            selfClientId = (_options_transport_clientId = options.transport.clientId) != null ? _options_transport_clientId : selfClientId;
+            options.onConnectionChange == null ? void 0 : options.onConnectionChange.call(options, 'connected');
+            requestSync();
+            emitPresence();
+        }));
+        cleanups.push(options.transport.on('disconnect', ()=>options.onConnectionChange == null ? void 0 : options.onConnectionChange.call(options, 'disconnected')));
+        cleanups.push(options.transport.on('sync', applyRemote));
+        cleanups.push(options.transport.on('update', applyRemote));
+        cleanups.push(options.transport.on('update-ack', (payload)=>{
+            const ack = parseAck(payload);
+            if (ack) options.onAck == null ? void 0 : options.onAck.call(options, ack);
+        }));
+        cleanups.push(options.transport.on('presence', (payload)=>{
+            const item = parsePresence(payload);
+            if (item) {
+                presenceSeenAt.set(item.clientId, Date.now());
+                options.onPresence == null ? void 0 : options.onPresence.call(options, item);
+            }
+        }));
+        cleanups.push(options.transport.on('presence-snapshot', (payload)=>{
+            const rawItems = payload['items'];
+            const items = Array.isArray(rawItems) ? rawItems.map(parsePresence).filter(isPresence) : [];
+            var _stringValue, _ref;
+            selfClientId = (_ref = (_stringValue = stringValue(payload['selfClientId'])) != null ? _stringValue : options.transport.clientId) != null ? _ref : selfClientId;
+            presenceSeenAt.clear();
+            for (const item of items)presenceSeenAt.set(item.clientId, Date.now());
+            options.onPresenceSnapshot == null ? void 0 : options.onPresenceSnapshot.call(options, items, {
+                selfClientId
+            });
+        }));
+        cleanups.push(options.transport.on('presence-remove', (payload)=>{
+            const clientId = stringValue(payload['clientId']);
+            if (clientId) {
+                presenceSeenAt.delete(clientId);
+                options.onPresenceRemove == null ? void 0 : options.onPresenceRemove.call(options, clientId);
+            }
+        }));
+        cleanups.push(options.transport.on('error', (payload)=>{
+            var _stringValue;
+            return reportError((_stringValue = stringValue(payload['message'])) != null ? _stringValue : 'Collaboration failed.');
+        }));
+        syncTimer = setInterval(requestSync, syncIntervalMs);
+        presenceTimer = setInterval(emitPresence, presenceHeartbeatMs);
+        presenceCleanupTimer = setInterval(()=>{
+            const cutoff = Date.now() - presenceStaleMs;
+            for (const [clientId, seenAt] of presenceSeenAt){
+                if (clientId === selfClientId || seenAt >= cutoff) continue;
+                presenceSeenAt.delete(clientId);
+                options.onPresenceRemove == null ? void 0 : options.onPresenceRemove.call(options, clientId);
+            }
+        }, Math.min(5000, Math.max(1000, Math.floor(presenceStaleMs / 3))));
+        options.transport.connect();
+    };
+    // Flush best-effort pending state and release all timers/listeners owned by this client.
+    const disconnect = ()=>{
+        var _cleanups_pop;
+        if (!started) return;
+        flush();
+        started = false;
+        if (flushTimer) clearTimeout(flushTimer);
+        if (syncTimer) clearInterval(syncTimer);
+        if (presenceTimer) clearInterval(presenceTimer);
+        if (presenceCleanupTimer) clearInterval(presenceCleanupTimer);
+        flushTimer = undefined;
+        syncTimer = undefined;
+        presenceTimer = undefined;
+        presenceCleanupTimer = undefined;
+        presenceSeenAt.clear();
+        while(cleanups.length)(_cleanups_pop = cleanups.pop()) == null ? void 0 : _cleanups_pop();
+        options.transport.disconnect();
+        options.onConnectionChange == null ? void 0 : options.onConnectionChange.call(options, 'disconnected');
+    };
+    return {
+        get selfClientId () {
+            return selfClientId;
+        },
+        remoteOrigin,
+        connect,
+        disconnect,
+        flush,
+        requestSync,
+        setPresence: (patch)=>{
+            presence = _extends({}, presence, patch);
+            if (options.transport.connected) emitPresence();
+        }
+    };
+}
+function actorPresence(actor, clientId) {
+    return _extends({}, actor, {
+        clientId: clientId != null ? clientId : `self:${actor.presenceId}`,
+        pageId: null,
+        pointer: null,
+        focus: null,
+        selection: null,
+        viewport: null,
+        mode: null,
+        status: null,
+        toolName: null,
+        operationLabel: null,
+        updatedAt: Date.now()
+    });
+}
+/** Encode bytes in browsers without Node.js `Buffer`; chunks avoid argument-size limits. */ function bytesToBase64(bytes) {
+    let binary = '';
+    const chunkSize = 0x8000;
+    for(let offset = 0; offset < bytes.length; offset += chunkSize){
+        binary += String.fromCharCode(...bytes.subarray(offset, Math.min(offset + chunkSize, bytes.length)));
+    }
+    return globalThis.btoa(binary);
+}
+/** Decode base64 in browsers without requiring Node.js polyfills. */ function base64ToBytes(value) {
+    const binary = globalThis.atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for(let index = 0; index < binary.length; index += 1)bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+function parseAck(payload) {
+    const documentId = stringValue(payload['documentId']);
+    const stateVectorBase64 = stringValue(payload['stateVectorBase64']);
+    const sequenceNumber = payload['sequenceNumber'];
+    if (!documentId || !stateVectorBase64 || typeof sequenceNumber !== 'number') return null;
+    const materializationStatus = payload['materializationStatus'];
+    if (materializationStatus !== 'ready' && materializationStatus !== 'pending' && materializationStatus !== 'failed') return null;
+    return {
+        documentId,
+        duplicate: payload['duplicate'] === true,
+        sequenceNumber,
+        updateId: stringValue(payload['updateId']),
+        stateVectorBase64,
+        materializationStatus
+    };
+}
+function parsePresence(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    const item = value;
+    const clientId = stringValue(item['clientId']);
+    const presenceId = stringValue(item['presenceId']);
+    const displayName = stringValue(item['displayName']);
+    const color = stringValue(item['color']);
+    const actorType = item['actorType'];
+    if (!clientId || !presenceId || !displayName || !color || actorType !== 'user' && actorType !== 'agent' && actorType !== 'system') return null;
+    return {
+        clientId,
+        presenceId,
+        displayName,
+        color,
+        actorType,
+        avatarUrl: nullableString(item['avatarUrl']),
+        pageId: nullableString(item['pageId']),
+        pointer: parsePointer(item['pointer']),
+        focus: parseFocus(item['focus']),
+        selection: parseSelection(item['selection']),
+        viewport: parseViewport(item['viewport']),
+        mode: nullableString(item['mode']),
+        status: actorStatus(item['status']),
+        toolName: nullableString(item['toolName']),
+        operationLabel: nullableString(item['operationLabel']),
+        updatedAt: typeof item['updatedAt'] === 'number' ? item['updatedAt'] : Date.now()
+    };
+}
+function parsePointer(value) {
+    const item = recordValue(value);
+    if (!item || typeof item['x'] !== 'number' || typeof item['y'] !== 'number') return null;
+    return {
+        pageId: nullableString(item['pageId']),
+        x: item['x'],
+        y: item['y'],
+        visible: item['visible'] !== false
+    };
+}
+function parseFocus(value) {
+    const item = recordValue(value);
+    const kind = item && stringValue(item['kind']);
+    if (!item || !kind) return null;
+    return {
+        kind,
+        key: nullableString(item['key']),
+        pageId: nullableString(item['pageId']),
+        elementId: nullableString(item['elementId']),
+        fieldKey: nullableString(item['fieldKey'])
+    };
+}
+function parseSelection(value) {
+    const item = recordValue(value);
+    const kind = item == null ? void 0 : item['kind'];
+    if (!item || kind !== 'text' && kind !== 'elements') return null;
+    return {
+        kind,
+        fieldKey: nullableString(item['fieldKey']),
+        elementIds: Array.isArray(item['elementIds']) ? item['elementIds'].filter((entry)=>typeof entry === 'string') : null,
+        anchorRelativeBase64: nullableString(item['anchorRelativeBase64']),
+        headRelativeBase64: nullableString(item['headRelativeBase64'])
+    };
+}
+function parseViewport(value) {
+    const item = recordValue(value);
+    if (!item || typeof item['zoom'] !== 'number' || typeof item['width'] !== 'number' || typeof item['height'] !== 'number') return null;
+    return {
+        zoom: item['zoom'],
+        width: item['width'],
+        height: item['height']
+    };
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function isPresence(value) {
+    return value !== null;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function nullableString(value) {
+    var _stringValue;
+    return (_stringValue = stringValue(value)) != null ? _stringValue : null;
+}
+function actorStatus(value) {
+    return value === 'thinking' || value === 'editing' || value === 'done' || value === 'failed' ? value : null;
+}
+function positiveInteger(value, fallback) {
+    return Number.isFinite(value) && Number(value) > 0 ? Math.trunc(Number(value)) : fallback;
+}
+
+export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, ArtifactsRuntimeCapability, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, COLLABORATION_DOCUMENT_PROVIDER, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CollaborationDocumentProvider, CollaborationDocumentProviderRegistry, CollaborationRuntimeCapability, CommonParameterRules, ConnectorRuntimeCapability, ConnectorStrategyKey, ConnectorStrategyRegistry, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC, DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS, DEFAULT_SANDBOX_SHELL_TIMEOUT_MS, DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DefaultRuntimeCapabilityRegistry as DefaultAgentMiddlewareRuntimeCapabilityRegistry, DefaultRuntimeCapabilityRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, FILE_STORAGE_PROVIDER, FILE_UPLOAD_TARGET_STRATEGY, FileRuntimeCapability, FileStorageProvider, FileStorageProviderRegistry, FileUploadTargetRegistry, FileUploadTargetStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, KnowledgebaseDocumentsRuntimeCapability, KnowledgebaseRuntimeCapability, LLMUsage, LargeLanguageModel, MANAGED_CONNECTION_REGISTRY_TOKEN, MANAGED_QUEUE_HANDLER_REGISTRY_TOKEN, MANAGED_QUEUE_SERVICE_TOKEN, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_JOB_PROCESSOR_METADATA, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, PluginJobProcessor, PluginWebhookAuth, PluginWebhookAuthGuard, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SKILL_SOURCE_PROVIDER, SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN, SPEECH_TO_TEXT_SERVICE_TOKEN, SSOProviderRegistry, SSOProviderStrategyKey, SSO_BINDING_PERMISSION_SERVICE_TOKEN, SSO_PROVIDER, STRATEGY_META_KEY, SYSTEM_GLOBAL_SCOPE, SandboxProviderRegistry, SandboxProviderStrategy, 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, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WORKSPACE_FILES_SOURCE, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WorkspaceFilesRuntimeCapability, WrapWorkflowNodeExecutionCommand, XPERT_RUNTIME_CAPABILITIES_TOKEN, XpFileSystem, XpertServerPlugin, als, appendSandboxMessage, base64ToBytes, buildSandboxTimeoutMessage, bytesToBase64, calcTokenUsage, chunkText, countTokensSafe, createCollaborationClient, createCollaborationPresenceStore, createI18nInstance, createPluginLogger, createRuntimeCapability, createSocketIoTransportAdapter, createYjsDocumentAdapter, defineAgentMessageType, defineChannelMessageType, derivePluginArtifactNamespace, downloadRemoteFile, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, pluginArtifactTableName, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveTenantGlobalScopeKey, runWithRequestContext, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage };

package/package.json

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

package/src/index.d.ts

@@ -23,3 +23,4 @@ export * from './lib/sandbox/index';
 export * from './lib/managed-connection/index';
 export * from './lib/managed-queue/index';
 export * from './lib/view-extension/index';
+export * from './lib/collaboration/index';

package/src/lib/collaboration/client.d.ts

@@ -0,0 +1,118 @@
+import type { ApplyCollaborationUpdateResult, CollaborationPresencePatch, CollaborationSessionDescriptor, ICollaborationActor, ICollaborationPresence } from './types';
+export type CollaborationTransportPayload = Record<string, unknown>;
+export type CollaborationTransportHandler = (payload: CollaborationTransportPayload) => void;
+/** Framework-neutral event transport used by the collaboration client. */
+export interface CollaborationTransport {
+    readonly connected: boolean;
+    /** Socket/session identifier for this exact browser client, when the transport exposes one. */
+    readonly clientId?: string | null;
+    connect(): void;
+    disconnect(): void;
+    emit(event: string, payload?: CollaborationTransportPayload): void;
+    on(event: string, handler: CollaborationTransportHandler): () => void;
+}
+/** Minimal Socket.IO-compatible shape; keeps socket.io-client out of the SDK bundle. */
+export interface CollaborationSocketLike {
+    readonly connected: boolean;
+    readonly id?: string;
+    connect(): unknown;
+    disconnect(): unknown;
+    emit(event: string, payload?: CollaborationTransportPayload): unknown;
+    on(event: string, handler: CollaborationTransportHandler): unknown;
+    off(event: string, handler: CollaborationTransportHandler): unknown;
+}
+/** Adapt a caller-owned Socket.IO client to the SDK's framework-neutral transport. */
+export declare function createSocketIoTransportAdapter(socket: CollaborationSocketLike): CollaborationTransport;
+export type CollaborationDocumentUpdateHandler = (update: Uint8Array, origin: unknown) => void;
+/** Binary CRDT operations required by the generic collaboration client. */
+export interface CollaborationBinaryDocumentAdapter {
+    applyUpdate(update: Uint8Array, origin: unknown): void;
+    encodeStateVector(): Uint8Array;
+    mergeUpdates(updates: Uint8Array[]): Uint8Array;
+    onUpdate(handler: CollaborationDocumentUpdateHandler): () => void;
+}
+/** Minimal observable Yjs document surface accepted by `createYjsDocumentAdapter`. */
+export interface YjsDocumentLike {
+    on(event: 'update', handler: CollaborationDocumentUpdateHandler): void;
+    off(event: 'update', handler: CollaborationDocumentUpdateHandler): void;
+}
+/** Caller-supplied Yjs functions, avoiding a second Yjs runtime in plugin bundles. */
+export interface YjsApiLike<TDocument extends YjsDocumentLike> {
+    applyUpdate(document: TDocument, update: Uint8Array, origin?: unknown): void;
+    encodeStateVector(document: TDocument): Uint8Array;
+    mergeUpdates(updates: Uint8Array[]): Uint8Array;
+}
+/** Wrap a caller-owned `Y.Doc` without passing it across the runtime capability boundary. */
+export declare function createYjsDocumentAdapter<TDocument extends YjsDocumentLike>(document: TDocument, yjs: YjsApiLike<TDocument>): CollaborationBinaryDocumentAdapter;
+/** Timings, callbacks, transport, and document adapter used by a browser client. */
+export type CollaborationClientOptions = {
+    session: CollaborationSessionDescriptor;
+    transport: CollaborationTransport;
+    document: CollaborationBinaryDocumentAdapter;
+    initialPresence?: CollaborationPresencePatch;
+    batchMs?: number;
+    syncIntervalMs?: number;
+    presenceHeartbeatMs?: number;
+    /** Remove a presence locally when no refresh has been received within this interval. */
+    presenceStaleMs?: number;
+    onAck?: (ack: ApplyCollaborationUpdateResult) => void;
+    onPresence?: (presence: ICollaborationPresence) => void;
+    onPresenceSnapshot?: (items: ICollaborationPresence[], metadata: CollaborationPresenceSnapshotMetadata) => void;
+    onPresenceRemove?: (clientId: string) => void;
+    onConnectionChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+    onError?: (error: Error) => void;
+};
+/** Lifecycle and presence controls returned by `createCollaborationClient`. */
+export interface CollaborationClient {
+    /** Stable origin applied to remote updates so local observers can prevent echo loops. */
+    readonly remoteOrigin: object;
+    /** Socket id for this exact tab/device; distinct from the stable actor `presenceId`. */
+    readonly selfClientId: string | null;
+    connect(): void;
+    disconnect(): void;
+    flush(): void;
+    requestSync(): void;
+    setPresence(patch: CollaborationPresencePatch): void;
+}
+/** Connection-specific metadata delivered with a presence snapshot. */
+export type CollaborationPresenceSnapshotMetadata = {
+    selfClientId: string | null;
+};
+/** Stable, framework-neutral view of active collaboration sessions and deduplicated actors. */
+export type CollaborationPresenceStoreSnapshot = {
+    selfClientId: string | null;
+    /** Every active browser/Agent session keyed by `clientId`. */
+    sessions: ICollaborationPresence[];
+    /** Sessions excluding only this exact browser client. */
+    remoteSessions: ICollaborationPresence[];
+    /** One entry per actor identity, including the local actor when supplied. */
+    collaborators: ICollaborationPresence[];
+};
+export type CollaborationPresenceStoreOptions = {
+    selfActor?: ICollaborationActor | null;
+    includeSelf?: boolean;
+    onChange?: (snapshot: CollaborationPresenceStoreSnapshot) => void;
+};
+/** Mutable presence projection used by plugin UIs without coupling them to a framework. */
+export interface CollaborationPresenceStore {
+    setSelfClientId(clientId: string | null): void;
+    replace(items: ICollaborationPresence[], selfClientId?: string | null): void;
+    upsert(item: ICollaborationPresence): void;
+    remove(clientId: string): void;
+    clear(): void;
+    snapshot(): CollaborationPresenceStoreSnapshot;
+}
+/**
+ * Keep per-client sessions for cursors while exposing one collaborator per stable actor identity.
+ * This prevents a second tab owned by the same user from either duplicating or hiding that user.
+ */
+export declare function createCollaborationPresenceStore(options?: CollaborationPresenceStoreOptions): CollaborationPresenceStore;
+/**
+ * Create a collaboration client with update batching, state-vector repair, presence heartbeat,
+ * and reconnect synchronization. The caller retains ownership of the document and transport.
+ */
+export declare function createCollaborationClient(options: CollaborationClientOptions): CollaborationClient;
+/** Encode bytes in browsers without Node.js `Buffer`; chunks avoid argument-size limits. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decode base64 in browsers without requiring Node.js polyfills. */
+export declare function base64ToBytes(value: string): Uint8Array;

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

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './runtime-capability';
+export * from './provider.decorator';
+export * from './provider.registry';
+export * from './client';

package/src/lib/collaboration/provider.decorator.d.ts

@@ -0,0 +1,3 @@
+export declare const COLLABORATION_DOCUMENT_PROVIDER = "COLLABORATION_DOCUMENT_PROVIDER";
+/** Register a plugin adapter for one stable collaboration resource type. */
+export declare const CollaborationDocumentProvider: (providerKey: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/collaboration/provider.registry.d.ts

@@ -0,0 +1,7 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { ICollaborationDocumentProvider } from './types';
+/** Discovers system and organization-scoped collaboration providers from loaded plugins. */
+export declare class CollaborationDocumentProviderRegistry extends BaseStrategyRegistry<ICollaborationDocumentProvider> {
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+}

package/src/lib/collaboration/runtime-capability.d.ts

@@ -0,0 +1,3 @@
+import type { CollaborationApi } from './types';
+/** Platform-owned real-time collaboration capability available to scoped plugin runtimes. */
+export declare const CollaborationRuntimeCapability: import("../core/runtime-capability").RuntimeCapabilityKey<CollaborationApi>;