@theia/ai-chat 1.66.0-next.44 → 1.66.0-next.73

package/src/common/chat-content-deserializer.ts

@@ -0,0 +1,327 @@
+// *****************************************************************************
+// Copyright (C) 2025 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { inject, injectable, named, postConstruct } from '@theia/core/shared/inversify';
+import {
+    ChatResponseContent,
+    CodeChatResponseContentImpl,
+    CommandChatResponseContentImpl,
+    ErrorChatResponseContentImpl,
+    HorizontalLayoutChatResponseContentImpl,
+    InformationalChatResponseContentImpl,
+    MarkdownChatResponseContentImpl,
+    ProgressChatResponseContentImpl,
+    QuestionResponseContentImpl,
+    TextChatResponseContentImpl,
+    ThinkingChatResponseContentImpl,
+    ToolCallChatResponseContentImpl,
+    UnknownChatResponseContentImpl,
+    TextContentData,
+    ThinkingContentData,
+    MarkdownContentData,
+    InformationalContentData,
+    CodeContentData,
+    ToolCallContentData,
+    CommandContentData,
+    HorizontalLayoutContentData,
+    ProgressContentData,
+    ErrorContentData,
+    QuestionContentData
+} from './chat-model';
+import { SerializableChatResponseContentData } from './chat-model-serialization';
+import { ContributionProvider, ILogger, MaybePromise } from '@theia/core';
+
+export const ChatContentDeserializer = Symbol('ChatContentDeserializer');
+
+/**
+ * A deserializer for a specific kind of chat response content.
+ *
+ * Deserializers are responsible for reconstructing `ChatResponseContent` instances
+ * from their serialized data representations. Each deserializer handles a single
+ * content type identified by its `kind` property.
+ *
+ * @template T The type of the data object that this deserializer can process.
+ *
+ * @example
+ * ```typescript
+ * const textDeserializer: ChatContentDeserializer<TextContentData> = {
+ *     kind: 'text',
+ *     deserialize: (data) => new TextChatResponseContentImpl(data.content)
+ * };
+ * ```
+ */
+export interface ChatContentDeserializer<T = unknown> {
+    /**
+     * The unique identifier for the content type this deserializer handles.
+     * This must match the `kind` property of the serialized content data.
+     */
+    readonly kind: string;
+
+    /**
+     * Deserializes the given data into a `ChatResponseContent` instance.
+     *
+     * @param data The serialized data to deserialize. The structure depends on the content kind.
+     * @returns The deserialized content, or a Promise that resolves to the deserialized content.
+     */
+    deserialize(data: T): MaybePromise<ChatResponseContent>;
+}
+
+/**
+ * Contribution point for registering chat content deserializers.
+ *
+ * Implement this interface to contribute custom deserializers for application-specific
+ * or extension-specific chat response content types. Multiple contributions can be
+ * registered, and all will be collected via the contribution provider pattern.
+ *
+ * @example
+ * ```typescript
+ * @injectable()
+ * export class MyDeserializerContribution implements ChatContentDeserializerContribution {
+ *     registerDeserializers(registry: ChatContentDeserializerRegistry): void {
+ *         registry.register({
+ *             kind: 'customContent',
+ *             deserialize: (data: CustomContentData) =>
+ *                 new CustomContentImpl(data.title, data.items)
+ *         });
+ *     }
+ * }
+ *
+ * // In your module:
+ * bind(ChatContentDeserializerContribution).to(MyDeserializerContribution).inSingletonScope();
+ * ```
+ *
+ * @see {@link ChatContentDeserializerRegistry} for the registry that collects deserializers
+ * @see {@link DefaultChatContentDeserializerContribution} for built-in content type deserializers
+ */
+export interface ChatContentDeserializerContribution {
+    /**
+     * Registers one or more deserializers with the provided registry.
+     *
+     * This method is called during the registry's initialization phase (at `@postConstruct()` time).
+     *
+     * @param registry The registry to register deserializers with
+     */
+    registerDeserializers(registry: ChatContentDeserializerRegistry): void;
+}
+export const ChatContentDeserializerContribution = Symbol('ChatContentDeserializerContribution');
+
+/**
+ * Registry for chat content deserializers.
+ *
+ * This registry maintains a collection of deserializers for different content types
+ * and provides methods to register new deserializers and deserialize content data.
+ *
+ * @example
+ * ```typescript
+ * // Usage in a service:
+ * @inject(ChatContentDeserializerRegistry)
+ * protected deserializerRegistry: ChatContentDeserializerRegistry;
+ *
+ * async restoreContent(): Promise<void> {
+ *     const restoredContent = this.deserializerRegistry.deserialize(serializedData);
+ * }
+ * ```
+ *
+ * @see {@link ChatContentDeserializerContribution} for how to contribute deserializers
+ * @see {@link ChatContentDeserializerRegistryImpl} for the default implementation
+ */
+export interface ChatContentDeserializerRegistry {
+    /**
+     * Registers a deserializer for a specific content kind.
+     *
+     * If a deserializer for the same kind is already registered, it will be replaced.
+     *
+     * @param deserializer The deserializer to register
+     */
+    register(deserializer: ChatContentDeserializer<unknown>): void;
+
+    /**
+     * Deserializes the given serialized content data into a `ChatResponseContent` instance.
+     *
+     * The registry looks up the appropriate deserializer based on the `kind` property
+     * of the serialized data and delegates to that deserializer's `deserialize` method.
+     *
+     * If no deserializer is found for the content kind, an `UnknownChatResponseContentImpl`
+     * instance is returned with the original data and fallback message preserved.
+     * A warning is also logged with the missing kind and available kinds.
+     *
+     * @param serialized The serialized content data to deserialize
+     * @returns The deserialized content, or a Promise that resolves to the deserialized content
+     */
+    deserialize(serialized: SerializableChatResponseContentData): MaybePromise<ChatResponseContent>;
+}
+export const ChatContentDeserializerRegistry = Symbol('ChatContentDeserializerRegistry');
+
+/**
+ * Default implementation of the chat content deserializer registry.
+ *
+ * This registry collects deserializers from all bound `ChatContentDeserializerContribution`
+ * instances during its post-construction initialization phase. Deserializers are stored
+ * in a map keyed by their content kind.
+ *
+ * The registry handles unknown content types gracefully by returning an
+ * `UnknownChatResponseContentImpl` instance when no deserializer is found,
+ * ensuring that chat sessions can still be loaded even if some content types
+ * are no longer supported or available.
+ *
+ * @see {@link ChatContentDeserializerRegistry} for the interface definition
+ */
+@injectable()
+export class ChatContentDeserializerRegistryImpl implements ChatContentDeserializerRegistry {
+    /**
+     * Map of registered deserializers, keyed by content kind.
+     */
+    protected deserializers = new Map<string, ChatContentDeserializer>();
+
+    @inject(ContributionProvider) @named(ChatContentDeserializerContribution)
+    protected readonly deserializerContributions: ContributionProvider<ChatContentDeserializerContribution>;
+
+    @inject(ILogger) @named('ChatContentDeserializerRegistry')
+    protected readonly logger: ILogger;
+
+    /**
+     * Initializes the registry by collecting deserializers from all contributions.
+     * This method is automatically called after construction due to the `@postConstruct` decorator.
+     */
+    @postConstruct()
+    protected initDeserializers(): void {
+        for (const contribution of this.deserializerContributions.getContributions()) {
+            contribution.registerDeserializers(this);
+        }
+    }
+
+    register(deserializer: ChatContentDeserializer): void {
+        this.deserializers.set(deserializer.kind, deserializer);
+    }
+
+    deserialize(serialized: SerializableChatResponseContentData): MaybePromise<ChatResponseContent> {
+        const deserializer = this.deserializers.get(serialized.kind);
+        if (!deserializer) {
+            this.logger.warn('No deserializer found for kind:', serialized.kind, 'Available kinds:', Array.from(this.deserializers.keys()));
+            return new UnknownChatResponseContentImpl(
+                serialized.kind,
+                serialized.fallbackMessage,
+                serialized.data
+            );
+        }
+        return deserializer.deserialize(serialized.data);
+    }
+}
+
+/**
+ * Default implementation of the chat content deserializer contribution.
+ *
+ * This contribution registers deserializers for all built-in content types supported
+ * by Theia AI.
+ *
+ * Note that some content types have limitations when deserialized from persistence.
+ *
+ * @see {@link ChatContentDeserializerContribution} for the contribution interface
+ */
+@injectable()
+export class DefaultChatContentDeserializerContribution implements ChatContentDeserializerContribution {
+    registerDeserializers(registry: ChatContentDeserializerRegistry): void {
+        registry.register({
+            kind: 'text',
+            deserialize: (data: TextContentData) => new TextChatResponseContentImpl(data.content)
+        });
+
+        registry.register({
+            kind: 'thinking',
+            deserialize: (data: ThinkingContentData) => new ThinkingChatResponseContentImpl(
+                data.content,
+                data.signature
+            )
+        });
+
+        registry.register({
+            kind: 'markdownContent',
+            deserialize: (data: MarkdownContentData) => new MarkdownChatResponseContentImpl(data.content)
+        });
+
+        registry.register({
+            kind: 'informational',
+            deserialize: (data: InformationalContentData) => new InformationalChatResponseContentImpl(data.content)
+        });
+
+        registry.register({
+            kind: 'code',
+            deserialize: (data: CodeContentData) => new CodeChatResponseContentImpl(
+                data.code,
+                data.language,
+                data.location
+            )
+        });
+
+        registry.register({
+            kind: 'toolCall',
+            deserialize: (data: ToolCallContentData) => new ToolCallChatResponseContentImpl(
+                data.id,
+                data.name,
+                data.arguments,
+                data.finished,
+                data.result
+            )
+        });
+
+        registry.register({
+            kind: 'command',
+            deserialize: (data: CommandContentData) => {
+                const command = data.commandId ? { id: data.commandId } : undefined;
+                // Cannot restore customCallback since it contains a function
+                return new CommandChatResponseContentImpl(command, undefined, data.arguments);
+            }
+        });
+
+        registry.register({
+            kind: 'horizontal',
+            deserialize: async (data: HorizontalLayoutContentData) => {
+                const childContentPromises = data.content.map(child => registry.deserialize(child));
+                const childContent = Promise.all(childContentPromises);
+                return new HorizontalLayoutChatResponseContentImpl(await childContent);
+            }
+        });
+
+        registry.register({
+            kind: 'progress',
+            deserialize: (data: ProgressContentData) => new ProgressChatResponseContentImpl(data.message)
+        });
+
+        registry.register({
+            kind: 'error',
+            deserialize: (data: ErrorContentData) => {
+                const error = new Error(data.message);
+                if (data.stack) {
+                    error.stack = data.stack;
+                }
+                return new ErrorChatResponseContentImpl(error);
+            }
+        });
+
+        registry.register({
+            kind: 'question',
+            deserialize: (data: QuestionContentData) =>
+                // Restore in read-only mode (no handler/request)
+                new QuestionResponseContentImpl(
+                    data.question,
+                    data.options,
+                    undefined,
+                    undefined,
+                    data.selectedOption
+                )
+        });
+    }
+}

package/src/common/chat-model-serialization.spec.ts

@@ -0,0 +1,343 @@
+// *****************************************************************************
+// Copyright (C) 2025 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { ChatAgentLocation } from './chat-agents';
+import { MutableChatModel } from './chat-model';
+import { ParsedChatRequest } from './parsed-chat-request';
+
+describe('ChatModel Serialization and Restoration', () => {
+
+    function createParsedRequest(text: string): ParsedChatRequest {
+        return {
+            request: { text },
+            parts: [{
+                kind: 'text',
+                text,
+                promptText: text,
+                range: { start: 0, endExclusive: text.length }
+            }],
+            toolRequests: new Map(),
+            variables: []
+        };
+    }
+
+    describe('Simple tree serialization', () => {
+        it('should serialize a chat with a single request', () => {
+            const model = new MutableChatModel(ChatAgentLocation.Panel);
+            model.addRequest(createParsedRequest('Hello'));
+
+            const serialized = model.toSerializable();
+
+            expect(serialized.hierarchy).to.be.an('object');
+            expect(serialized.hierarchy!.rootBranchId).to.be.a('string');
+            expect(serialized.hierarchy!.branches).to.be.an('object');
+            expect(serialized.requests).to.have.lengthOf(1);
+            expect(serialized.requests[0].text).to.equal('Hello');
+        });
+
+        it('should serialize a chat with multiple sequential requests', () => {
+            const model = new MutableChatModel(ChatAgentLocation.Panel);
+            model.addRequest(createParsedRequest('First'));
+            model.addRequest(createParsedRequest('Second'));
+            model.addRequest(createParsedRequest('Third'));
+
+            const serialized = model.toSerializable();
+
+            expect(serialized.hierarchy).to.be.an('object');
+            expect(serialized.requests).to.have.lengthOf(3);
+
+            // Verify the hierarchy has 3 branches (one for each request)
+            const branches = Object.values(serialized.hierarchy!.branches);
+            expect(branches).to.have.lengthOf(3);
+
+            // Verify the active path through the tree
+            const rootBranch = serialized.hierarchy!.branches[serialized.hierarchy!.rootBranchId];
+            expect(rootBranch.items).to.have.lengthOf(1);
+            expect(rootBranch.items[0].requestId).to.equal(serialized.requests[0].id);
+            expect(rootBranch.items[0].nextBranchId).to.be.a('string');
+        });
+    });
+
+    describe('Tree serialization with alternatives (edited messages)', () => {
+        it('should serialize a chat with edited messages', () => {
+            const model = new MutableChatModel(ChatAgentLocation.Panel);
+
+            // Add first request
+            const req1 = model.addRequest(createParsedRequest('Original message'));
+            req1.response.complete();
+
+            // Add second request
+            model.addRequest(createParsedRequest('Follow-up'));
+
+            // Edit the first request (creating an alternative)
+            const branch1 = model.getBranch(req1.id);
+            expect(branch1).to.not.be.undefined;
+            branch1!.add(model.addRequest(createParsedRequest('Edited message'), 'agent-1'));
+
+            const serialized = model.toSerializable();
+
+            // Should have 3 requests: original, edited, and follow-up
+            expect(serialized.requests).to.have.lengthOf(3);
+
+            // The root branch should have 2 items (original and edited alternatives)
+            const rootBranch = serialized.hierarchy!.branches[serialized.hierarchy!.rootBranchId];
+            expect(rootBranch.items).to.have.lengthOf(2);
+            expect(rootBranch.items[0].requestId).to.equal(serialized.requests[0].id);
+            expect(rootBranch.items[1].requestId).to.equal(serialized.requests[2].id);
+
+            // The active branch index should point to the most recent alternative
+            expect(rootBranch.activeBranchIndex).to.be.at.least(0);
+        });
+
+        it('should serialize nested alternatives (edited multiple times)', () => {
+            const model = new MutableChatModel(ChatAgentLocation.Panel);
+
+            // Add first request
+            const req1 = model.addRequest(createParsedRequest('First'));
+            req1.response.complete();
+
+            // Add second request
+            const req2 = model.addRequest(createParsedRequest('Second'));
+            req2.response.complete();
+
+            // Edit the second request (creating an alternative)
+            const branch2 = model.getBranch(req2.id);
+            expect(branch2).to.not.be.undefined;
+            const req2edited = model.addRequest(createParsedRequest('Second (edited)'), 'agent-1');
+            branch2!.add(req2edited);
+
+            // Add third request after the edited version
+            model.addRequest(createParsedRequest('Third'));
+
+            const serialized = model.toSerializable();
+
+            // Should have 4 requests total
+            expect(serialized.requests).to.have.lengthOf(4);
+
+            // Find the second-level branch
+            const rootBranch = serialized.hierarchy!.branches[serialized.hierarchy!.rootBranchId];
+            const nextBranchId = rootBranch.items[rootBranch.activeBranchIndex].nextBranchId;
+            expect(nextBranchId).to.be.a('string');
+
+            const secondBranch = serialized.hierarchy!.branches[nextBranchId!];
+            expect(secondBranch.items).to.have.lengthOf(2); // Original and edited
+        });
+    });
+
+    describe('Tree restoration from serialized data', () => {
+        it('should restore a simple chat session', () => {
+            // Create and serialize
+            const model1 = new MutableChatModel(ChatAgentLocation.Panel);
+            model1.addRequest(createParsedRequest('Hello'));
+            const serialized = model1.toSerializable();
+
+            // Restore
+            const model2 = new MutableChatModel(serialized);
+
+            expect(model2.getRequests()).to.have.lengthOf(1);
+            expect(model2.getRequests()[0].request.text).to.equal('Hello');
+        });
+
+        it('should restore chat with multiple sequential requests', () => {
+            // Create and serialize
+            const model1 = new MutableChatModel(ChatAgentLocation.Panel);
+            model1.addRequest(createParsedRequest('First'));
+            model1.addRequest(createParsedRequest('Second'));
+            model1.addRequest(createParsedRequest('Third'));
+            const serialized = model1.toSerializable();
+
+            // Restore
+            const model2 = new MutableChatModel(serialized);
+
+            const requests = model2.getRequests();
+            expect(requests).to.have.lengthOf(3);
+            expect(requests[0].request.text).to.equal('First');
+            expect(requests[1].request.text).to.equal('Second');
+            expect(requests[2].request.text).to.equal('Third');
+        });
+
+        it('should restore chat with edited messages (alternatives)', () => {
+            // Create and serialize
+            const model1 = new MutableChatModel(ChatAgentLocation.Panel);
+            const req1 = model1.addRequest(createParsedRequest('Original'));
+            req1.response.complete();
+
+            const branch1 = model1.getBranch(req1.id);
+            const req1edited = model1.addRequest(createParsedRequest('Edited'), 'agent-1');
+            branch1!.add(req1edited);
+
+            const serialized = model1.toSerializable();
+
+            // Verify serialization includes both alternatives
+            expect(serialized.requests).to.have.lengthOf(2);
+
+            // Restore
+            const model2 = new MutableChatModel(serialized);
+
+            // Check that both alternatives are restored
+            const restoredBranch = model2.getBranch(serialized.requests[0].id);
+            expect(restoredBranch).to.not.be.undefined;
+            expect(restoredBranch!.items).to.have.lengthOf(2);
+            expect(restoredBranch!.items[0].element.request.text).to.equal('Original');
+            expect(restoredBranch!.items[1].element.request.text).to.equal('Edited');
+        });
+
+        it('should restore the correct active branch indices', () => {
+            // Create and serialize
+            const model1 = new MutableChatModel(ChatAgentLocation.Panel);
+            const req1 = model1.addRequest(createParsedRequest('Original'));
+            req1.response.complete();
+
+            const branch1 = model1.getBranch(req1.id);
+            const req1edited = model1.addRequest(createParsedRequest('Edited'), 'agent-1');
+            branch1!.add(req1edited);
+
+            // Switch to the edited version
+            branch1!.enable(req1edited);
+
+            const activeBranchIndex1 = branch1!.activeBranchIndex;
+            const serialized = model1.toSerializable();
+
+            // Restore
+            const model2 = new MutableChatModel(serialized);
+
+            const restoredBranch = model2.getBranch(serialized.requests[0].id);
+            expect(restoredBranch).to.not.be.undefined;
+            expect(restoredBranch!.activeBranchIndex).to.equal(activeBranchIndex1);
+        });
+
+        it('should restore a simple session with hierarchy', () => {
+            // Create serialized data with hierarchy
+            const serializedData = {
+                sessionId: 'simple-session',
+                location: ChatAgentLocation.Panel,
+                hierarchy: {
+                    rootBranchId: 'branch-root',
+                    branches: {
+                        'branch-root': {
+                            id: 'branch-root',
+                            items: [{ requestId: 'request-1' }],
+                            activeBranchIndex: 0
+                        }
+                    }
+                },
+                requests: [
+                    {
+                        id: 'request-1',
+                        text: 'Hello'
+                    }
+                ],
+                responses: [
+                    {
+                        id: 'response-1',
+                        requestId: 'request-1',
+                        isComplete: true,
+                        isError: false,
+                        content: []
+                    }
+                ]
+            };
+
+            // Should restore without errors
+            const model = new MutableChatModel(serializedData);
+            expect(model.getRequests()).to.have.lengthOf(1);
+            expect(model.getRequests()[0].request.text).to.equal('Hello');
+        });
+    });
+
+    describe('Complete round-trip with complex tree', () => {
+        it('should serialize and restore a complex tree structure', () => {
+            // Create a complex chat with multiple edits
+            const model1 = new MutableChatModel(ChatAgentLocation.Panel);
+
+            // Level 1
+            const req1 = model1.addRequest(createParsedRequest('Level 1 - Original'));
+            req1.response.complete();
+
+            // Level 2
+            const req2 = model1.addRequest(createParsedRequest('Level 2 - Original'));
+            req2.response.complete();
+
+            // Edit Level 1
+            const branch1 = model1.getBranch(req1.id);
+            const req1edited = model1.addRequest(createParsedRequest('Level 1 - Edited'), 'agent-1');
+            branch1!.add(req1edited);
+
+            // Add Level 2 alternative after edited Level 1
+            const req2alt = model1.addRequest(createParsedRequest('Level 2 - Alternative'));
+            req2alt.response.complete();
+
+            // Edit Level 2 alternative
+            const branch2alt = model1.getBranch(req2alt.id);
+            const req2altEdited = model1.addRequest(createParsedRequest('Level 2 - Alternative Edited'), 'agent-1');
+            branch2alt!.add(req2altEdited);
+
+            const serialized = model1.toSerializable();
+
+            // Verify serialization
+            expect(serialized.requests).to.have.lengthOf(5);
+            expect(serialized.hierarchy).to.be.an('object');
+
+            // Restore
+            const model2 = new MutableChatModel(serialized);
+
+            // Verify all requests are present
+            const allRequests = model2.getAllRequests();
+            expect(allRequests).to.have.lengthOf(5);
+
+            // Verify branch structure
+            const restoredBranch1 = model2.getBranches()[0];
+            expect(restoredBranch1.items).to.have.lengthOf(2); // Original + Edited
+
+            // Verify we can navigate the alternatives
+            expect(restoredBranch1.items[0].element.request.text).to.equal('Level 1 - Original');
+            expect(restoredBranch1.items[1].element.request.text).to.equal('Level 1 - Edited');
+        });
+
+        it('should preserve all requests across multiple serialization/restoration cycles', () => {
+            // Create initial model
+            let model = new MutableChatModel(ChatAgentLocation.Panel);
+            const req1 = model.addRequest(createParsedRequest('Request 1'));
+            req1.response.complete();
+
+            // Cycle 1
+            let serialized = model.toSerializable();
+            model = new MutableChatModel(serialized);
+
+            // Add more requests
+            model.addRequest(createParsedRequest('Request 2'));
+
+            // Cycle 2
+            serialized = model.toSerializable();
+            model = new MutableChatModel(serialized);
+
+            // Add an edit
+            const branch = model.getBranches()[0];
+            const reqEdited = model.addRequest(createParsedRequest('Request 1 - Edited'), 'agent-1');
+            branch.add(reqEdited);
+
+            // Final cycle
+            serialized = model.toSerializable();
+            const finalModel = new MutableChatModel(serialized);
+
+            // Verify all requests are preserved
+            expect(finalModel.getBranches()[0].items).to.have.lengthOf(2);
+            const allRequests = finalModel.getAllRequests();
+            expect(allRequests).to.have.lengthOf(3);
+        });
+    });
+});