@xpert-ai/plugin-sdk 3.15.8 → 3.15.10

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @xpert-ai/plugin-sdk
 
+## 3.15.10
+
+### Patch Changes
+
+- c9d8401: collaboration & artifacts
+- Updated dependencies [c9d8401]
+  - @xpert-ai/contracts@3.15.10
+
+## 3.15.9
+
+### Patch Changes
+
+- 601438f: fix org membership plan
+- Updated dependencies [601438f]
+  - @xpert-ai/contracts@3.15.9
+
 ## 3.15.8
 
 ### Patch Changes

package/index.cjs.js

@@ -2795,6 +2795,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.'
@@ -4686,6 +4690,412 @@ function escapeInlineScript(value) {
 
 const VIEW_EXTENSION_CACHE_SERVICE_TOKEN = 'XPERT_PLUGIN_VIEW_EXTENSION_CACHE_SERVICE';
 
+/** 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)=>common.applyDecorators(common.SetMetadata(COLLABORATION_DOCUMENT_PROVIDER, providerKey), common.SetMetadata(STRATEGY_META_KEY, COLLABORATION_DOCUMENT_PROVIDER));
+
+/** Discovers system and organization-scoped collaboration providers from loaded plugins. */ exports.CollaborationDocumentProviderRegistry = class CollaborationDocumentProviderRegistry extends BaseStrategyRegistry {
+    constructor(discoveryService, reflector){
+        super(COLLABORATION_DOCUMENT_PROVIDER, discoveryService, reflector);
+    }
+};
+exports.CollaborationDocumentProviderRegistry = __decorate([
+    common.Injectable(),
+    __metadata("design:paramtypes", [
+        core.DiscoveryService,
+        core.Reflector
+    ])
+], exports.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;
+}
+
 Object.defineProperty(exports, "ASSISTANT_CHAT_SEND_MESSAGE_COMMAND", {
     enumerable: true,
     get: function () { return contracts.ASSISTANT_CHAT_SEND_MESSAGE_COMMAND; }
@@ -4704,6 +5114,7 @@ exports.ANALYTICS_PERMISSION_SERVICE_TOKEN = ANALYTICS_PERMISSION_SERVICE_TOKEN;
 exports.AdapterDataSourceStrategy = AdapterDataSourceStrategy;
 exports.AgentMiddlewareStrategy = AgentMiddlewareStrategy;
 exports.AiModelNotFoundException = AiModelNotFoundException;
+exports.ArtifactsRuntimeCapability = ArtifactsRuntimeCapability;
 exports.AssistantTaskRuntimeCapability = AssistantTaskRuntimeCapability;
 exports.BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN = BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN;
 exports.BUILTIN_GLOBAL_SCOPE = BUILTIN_GLOBAL_SCOPE;
@@ -4717,11 +5128,14 @@ exports.BaseToolset = BaseToolset;
 exports.BuiltinToolset = BuiltinToolset;
 exports.CHAT_CHANNEL = CHAT_CHANNEL;
 exports.CHAT_CHANNEL_TEXT_LIMITS = CHAT_CHANNEL_TEXT_LIMITS;
+exports.COLLABORATION_DOCUMENT_PROVIDER = COLLABORATION_DOCUMENT_PROVIDER;
 exports.CONNECTION_COMMAND_ROUTER_TOKEN = CONNECTION_COMMAND_ROUTER_TOKEN;
 exports.CONNECTOR_STRATEGY = CONNECTOR_STRATEGY;
 exports.CancelConversationCommand = CancelConversationCommand;
 exports.ChatChannel = ChatChannel;
 exports.ChatOAICompatReasoningModel = ChatOAICompatReasoningModel;
+exports.CollaborationDocumentProvider = CollaborationDocumentProvider;
+exports.CollaborationRuntimeCapability = CollaborationRuntimeCapability;
 exports.CommonParameterRules = CommonParameterRules;
 exports.ConnectorRuntimeCapability = ConnectorRuntimeCapability;
 exports.ConnectorStrategyKey = ConnectorStrategyKey;
@@ -4834,13 +5248,19 @@ exports.XpFileSystem = XpFileSystem;
 exports.XpertServerPlugin = XpertServerPlugin;
 exports.als = als;
 exports.appendSandboxMessage = appendSandboxMessage;
+exports.base64ToBytes = base64ToBytes;
 exports.buildSandboxTimeoutMessage = buildSandboxTimeoutMessage;
+exports.bytesToBase64 = bytesToBase64;
 exports.calcTokenUsage = calcTokenUsage;
 exports.chunkText = chunkText;
 exports.countTokensSafe = countTokensSafe;
+exports.createCollaborationClient = createCollaborationClient;
+exports.createCollaborationPresenceStore = createCollaborationPresenceStore;
 exports.createI18nInstance = createI18nInstance;
 exports.createPluginLogger = createPluginLogger;
 exports.createRuntimeCapability = createRuntimeCapability;
+exports.createSocketIoTransportAdapter = createSocketIoTransportAdapter;
+exports.createYjsDocumentAdapter = createYjsDocumentAdapter;
 exports.defineAgentMessageType = defineAgentMessageType;
 exports.defineChannelMessageType = defineChannelMessageType;
 exports.derivePluginArtifactNamespace = derivePluginArtifactNamespace;