feat: add generic AI communication model

Adds a new AI communication model for tracking raw LLM requests and
responses. Tracking is automated via the language-model-service.

This model serves as the foundation for:
- Extracting communication history from Theia AI, allowing LLM testing
  without running the full Theia-based application
- Replaying LLM communication without using an actual LLM, enabling
  deterministic integration tests
- Removing the clunky communication recording service, making the
  ai-history package optional

Resolves #15221

Contributed on behalf of STMicroelectronics

Author: sdirix

packages/ai-core/src/browser/frontend-language-model-service.ts

@@ -54,7 +54,7 @@ export class FrontendLanguageModelServiceImpl extends LanguageModelServiceImpl {
     }
 }
 
-export const mergeRequestSettings = (requestSettings: RequestSetting[], modelId: string, providerId: string, agentId: string): RequestSetting => {
+export const mergeRequestSettings = (requestSettings: RequestSetting[], modelId: string, providerId: string, agentId?: string): RequestSetting => {
     const prioritizedSettings = Prioritizeable.prioritizeAllSync(requestSettings,
         setting => getRequestSettingSpecificity(setting, {
             modelId,

packages/ai-core/src/common/language-model-interaction-model.ts

@@ -0,0 +1,92 @@
+// *****************************************************************************
+// Copyright (C) 2025 STMicroelectronics and others.
+//
+// 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 {
+    LanguageModelParsedResponse,
+    LanguageModelRequest,
+    LanguageModelStreamResponsePart,
+    LanguageModelTextResponse
+} from './language-model';
+
+/**
+ * An AI session tracks raw LLM interaction data, grouped into semantical requests.
+ */
+export interface AiSession {
+    /**
+     * Identifer of this AI Session. Will correspond to Chat session ids
+     */
+    id: string;
+    /**
+     * All semantic requests part of this sessions
+     */
+    requests: AiSemanticRequest[];
+}
+/**
+ * One logical request can be split into multiple requests to different language models
+ */
+export interface AiSemanticRequest {
+    /**
+     * Identifier of the semantic request. Will correspond to Chat request ids
+     */
+    id: string;
+    /**
+     * All raw requests which constitute this semantic request. Will be a single one for a "default" Chat request.
+     */
+    requests: AiRequest[];
+    /**
+     * Arbitrary metadata for the request
+     */
+    metadata: {
+        agent?: string;
+        [key: string]: unknown;
+    }
+}
+
+/**
+ * Alternative to the LanguageModelStreamResponse, suited for inspection
+ */
+export interface LanguageModelMonitoredStreamResponse {
+    parts: LanguageModelStreamResponsePart[]
+}
+
+/**
+ * The AiRequest interface represents a request to an AI language model, tracking all raw data exchanged
+ */
+export interface AiRequest {
+    /**
+     * Identifier of the request. Might have the same id as the parent semantic request, in case there is only one request or there being a root/seed request.
+     */
+    id: string;
+    /**
+     * The actual request sent to the language model
+     */
+    request: LanguageModelRequest;
+    /**
+     * Arbitrary metadata for the request. Might contain the agent id
+     */
+    metadata: {
+        agent?: string;
+        timestamp?: number;
+        [key: string]: unknown;
+    }
+    /**
+     * The identifier of the language model the request was sent to
+     */
+    languageModel: string;
+    /**
+     * The recorded response
+     */
+    response: LanguageModelTextResponse | LanguageModelParsedResponse | LanguageModelMonitoredStreamResponse;
+}

packages/ai-core/src/common/language-model-service.ts

@@ -15,13 +15,29 @@
 // *****************************************************************************
 
 import { inject } from '@theia/core/shared/inversify';
-import { LanguageModel, LanguageModelRegistry, LanguageModelResponse, UserRequest } from './language-model';
-import { CommunicationRecordingService } from './communication-recording-service';
+import { isLanguageModelStreamResponse, LanguageModel, LanguageModelRegistry, LanguageModelResponse, LanguageModelStreamResponsePart, UserRequest } from './language-model';
+import { AiRequest, AiSession } from './language-model-interaction-model';
+import { Emitter } from '@theia/core';
+
+export interface RequestAddedEvent {
+    type: 'requestAdded',
+    id: string;
+}
+export interface ResponseCompletedEvent {
+    type: 'responseCompleted',
+    requestId: string;
+}
+export type SessionEvent = RequestAddedEvent | ResponseCompletedEvent;
 
 export const LanguageModelService = Symbol('LanguageModelService');
 export interface LanguageModelService {
+    onSessionChanged: Emitter<SessionEvent>['event'];
+    /**
+     * Collection of all recorded AiSessions.
+     */
+    sessions: AiSession[];
     /**
-     * Submit a language model request in the context of the given `chatRequest`.
+     * Submit a language model request, it will automatically be recorded within an AiSession.
      */
     sendRequest(
         languageModel: LanguageModel,
@@ -33,8 +49,10 @@ export class LanguageModelServiceImpl implements LanguageModelService {
     @inject(LanguageModelRegistry)
     protected languageModelRegistry: LanguageModelRegistry;
 
-    @inject(CommunicationRecordingService)
-    protected recordingService: CommunicationRecordingService;
+    sessions: AiSession[] = [];
+
+    protected sessionChangedEmitter = new Emitter<SessionEvent>();
+    onSessionChanged = this.sessionChangedEmitter.event;
 
     async sendRequest(
         languageModel: LanguageModel,
@@ -53,7 +71,84 @@ export class LanguageModelServiceImpl implements LanguageModelService {
             return true;
         });
 
-        return languageModel.request(languageModelRequest, languageModelRequest.cancellationToken);
+        let response = await languageModel.request(languageModelRequest, languageModelRequest.cancellationToken);
+        let storedResponse: AiRequest['response'];
+        if (isLanguageModelStreamResponse(response)) {
+            const parts: LanguageModelStreamResponsePart[] = [];
+            response = {
+                ...response,
+                stream: createLoggingAsyncIterable(response.stream,
+                    parts,
+                    () => this.sessionChangedEmitter.fire({ type: 'responseCompleted', requestId: languageModelRequest.subRequestId ?? languageModelRequest.requestId }))
+            };
+            storedResponse = { parts };
+        } else {
+            storedResponse = response;
+        }
+        this.storeRequest(languageModel, languageModelRequest, storedResponse);
+
+        return response;
     }
 
+    protected storeRequest(languageModel: LanguageModel, languageModelRequest: UserRequest, response: AiRequest['response']): void {
+        // Find or create the session for this request
+        let session = this.sessions.find(s => s.id === languageModelRequest.sessionId);
+        if (!session) {
+            session = {
+                id: languageModelRequest.sessionId,
+                requests: []
+            };
+            this.sessions.push(session);
+        }
+
+        // Find or create the semantic request for this request
+        let semanticRequest = session.requests.find(r => r.id === languageModelRequest.requestId);
+        if (!semanticRequest) {
+            semanticRequest = {
+                id: languageModelRequest.requestId,
+                requests: [],
+                metadata: { agentId: languageModelRequest.agentId }
+            };
+            session.requests.push(semanticRequest);
+        }
+
+        // Create and add the AI request to the semantic request
+        const aiRequest: AiRequest = {
+            id: languageModelRequest.subRequestId ?? languageModelRequest.requestId,
+            request: languageModelRequest,
+            languageModel: languageModel.id,
+            response: response,
+            metadata: {}
+        };
+
+        semanticRequest.requests.push(aiRequest);
+
+        aiRequest.metadata.agentId = languageModelRequest.agentId;
+        aiRequest.metadata.timestamp = Date.now();
+
+        this.sessionChangedEmitter.fire({ type: 'requestAdded', id: languageModelRequest.subRequestId ?? languageModelRequest.requestId });
+    }
+
+}
+
+/**
+ * Creates an AsyncIterable wrapper that stores each yielded item while preserving the
+ * original AsyncIterable behavior.
+ */
+async function* createLoggingAsyncIterable(
+    stream: AsyncIterable<LanguageModelStreamResponsePart>,
+    parts: LanguageModelStreamResponsePart[],
+    streamFinished: () => void
+): AsyncIterable<LanguageModelStreamResponsePart> {
+    try {
+        for await (const part of stream) {
+            parts.push(part);
+            yield part;
+        }
+    } catch (error) {
+        parts.push({ content: `[NOT FROM LLM] An error occured: ${error.message}` });
+        throw error;
+    } finally {
+        streamFinished();
+    }
 }

packages/ai-core/src/common/language-model.ts

@@ -159,10 +159,32 @@ export interface ResponseFormatJsonSchema {
     };
 }
 
+/**
+ * The UserRequest extends the "pure" LanguageModelRequest for cancelling support as well as
+ * logging metadata.
+ * The additional metadata might also be used for other use cases, for example to query default
+ * request settings based on the agent id, merging with the request settings handed over.
+ */
 export interface UserRequest extends LanguageModelRequest {
+    /**
+     * Identifier of the Ai/ChatSession
+     */
     sessionId: string;
+    /**
+     * Identifier of the semantic request. Corresponds to request id in Chat sessions
+     */
     requestId: string;
-    agentId: string;
+    /**
+     * Id of a sub request in case a semantic request consists of multiple sub requests
+     */
+    subRequestId?: string;
+    /**
+     * Optional agent identifier in case the request was sent by an agent
+     */
+    agentId?: string;
+    /**
+     * Cancellation support
+     */
     cancellationToken?: CancellationToken;
 }