@theia/ai-chat 1.75.0-next.8 → 1.75.0

package/src/common/chat-agents.ts

@@ -62,6 +62,7 @@ import {
 import { ContributionProvider, ILogger, isArray, nls } from '@theia/core';
 import { inject, injectable, named, optional, postConstruct } from '@theia/core/shared/inversify';
 import { ChatAgentService } from './chat-agent-service';
+import { FileReadTracker } from './file-read-tracker';
 import {
     ChatModel,
     ChatRequestModel,
@@ -187,7 +188,10 @@ export function isChatAgent(agent: Agent): agent is ChatAgent {
 @injectable()
 export abstract class AbstractChatAgent implements ChatAgent {
     @inject(LanguageModelRegistry) protected languageModelRegistry: LanguageModelRegistry;
-    @inject(ILogger) protected logger: ILogger;
+
+    @inject(ILogger) @named('ai-chat:AbstractChatAgent')
+    protected readonly logger: ILogger;
+
     @inject(ChatToolRequestService) protected chatToolRequestService: ChatToolRequestService;
     @inject(LanguageModelService) protected languageModelService: LanguageModelService;
     @inject(PromptService) protected promptService: PromptService;
@@ -200,6 +204,8 @@ export abstract class AbstractChatAgent implements ChatAgent {
 
     @inject(TokenUsageService) @optional() protected tokenUsageService: TokenUsageService | undefined;
 
+    @inject(FileReadTracker) @optional() protected fileReadTracker: FileReadTracker | undefined;
+
     readonly abstract id: string;
     readonly abstract name: string;
     readonly abstract languageModelRequirements: LanguageModelRequirement[];
@@ -255,6 +261,7 @@ export abstract class AbstractChatAgent implements ChatAgent {
             }
 
             const messages = await this.getMessages(request.session);
+            await this.appendExternalFileChangeNotice(request, messages);
 
             if (systemMessageDescription) {
                 const systemMsg: LanguageModelMessage = {
@@ -295,6 +302,27 @@ export abstract class AbstractChatAgent implements ChatAgent {
         }
     }
 
+    /**
+     * Tells the agent which files it read were meanwhile changed by somebody else. A trailing user message
+     * rather than the cached system message; providers requiring alternating roles merge same-role runs.
+     */
+    protected async appendExternalFileChangeNotice(request: MutableChatRequestModel, messages: LanguageModelMessage[]): Promise<void> {
+        try {
+            const changedFiles = await this.fileReadTracker?.getChangedFiles(request.session.id);
+            if (changedFiles?.length) {
+                messages.push({
+                    actor: 'user',
+                    type: 'text',
+                    text: `The following files changed since you last read them: ${changedFiles.join(', ')}. ` +
+                        'Read them again before relying on their content or overwriting them.'
+                });
+            }
+        } catch (error) {
+            // Advisory, so failing to determine it must not fail the request.
+            this.logger.warn('Could not determine externally changed files.', error);
+        }
+    }
+
     protected parseContents(text: string, request: MutableChatRequestModel): ChatResponseContent[] {
         return parseContents(
             text,
@@ -305,7 +333,7 @@ export abstract class AbstractChatAgent implements ChatAgent {
     };
 
     protected handleError(request: MutableChatRequestModel, error: Error): void {
-        console.error('Error handling chat interaction:', error);
+        this.logger.error('Error handling chat interaction:', error);
         request.response.response.addContent(new ErrorChatResponseContentImpl(error));
         request.response.error(error);
     }
@@ -749,7 +777,7 @@ export abstract class AbstractStreamParsingChatAgent extends AbstractChatAgent {
         for await (const token of languageModelResponse.stream) {
             // Skip unknown tokens. For example OpenAI sends empty tokens around tool calls
             if (!isLanguageModelStreamResponsePart(token)) {
-                console.debug(`Unknown token: '${JSON.stringify(token)}'. Skipping`);
+                this.logger.debug(`Unknown token: '${JSON.stringify(token)}'. Skipping`);
                 continue;
             }
             const newContent = this.parse(token, request);

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

@@ -194,7 +194,7 @@ export class ChatContentDeserializerRegistryImpl implements ChatContentDeseriali
     @inject(ContributionProvider) @named(ChatContentDeserializerContribution)
     protected readonly deserializerContributions: ContributionProvider<ChatContentDeserializerContribution>;
 
-    @inject(ILogger) @named('ChatContentDeserializerRegistry')
+    @inject(ILogger) @named('ai-chat:ChatContentDeserializerRegistryImpl')
     protected readonly logger: ILogger;
 
     /**

package/src/common/chat-request-parser.spec.ts

@@ -27,7 +27,7 @@ import { AgentDelegationTool } from '../browser/agent-delegation-tool';
 
 describe('ChatRequestParserImpl', () => {
     /** Command names the stubbed `PromptService` knows about. Anything else is not a command. */
-    const KNOWN_COMMANDS = ['hello', 'explain', 'compare', 'cmd', 'summarize', 'skill-one', 'skill-two'];
+    const KNOWN_COMMANDS = ['hello', 'explain', 'compare', 'cmd', 'summarize', 'skill-one', 'skill-two', 'bigquery:query-builder', 'io.github.acme_tools:my-skill'];
     /** Prompt fragments that are not marked as commands, but can still be invoked by their id. */
     const KNOWN_FRAGMENT_IDS = ['coder-system'];
 
@@ -710,6 +710,44 @@ describe('ChatRequestParserImpl', () => {
                 expect((result.parts[0] as ParsedChatRequestVariablePart).variableArg).to.equal('coder-system');
             });
 
+            it('parses a qualified command name containing a colon as one command', async () => {
+                // A skill supplied by an installed artifact is addressed as `<qualifier>:<skill>`, so
+                // the colon has to be part of the command name rather than terminate it.
+                const text = '/bigquery:query-builder';
+                const result = await parse(text);
+
+                expect(result.parts.length).to.equal(1);
+                expect((result.parts[0] as ParsedChatRequestVariablePart).variableArg).to.equal('bigquery:query-builder');
+                expectFullCoverage(result.parts, text);
+            });
+
+            it('parses a qualified command name with arguments', async () => {
+                const text = '/bigquery:query-builder count the rows';
+                const result = await parse(text);
+
+                expect(result.parts.length).to.equal(1);
+                expect((result.parts[0] as ParsedChatRequestVariablePart).variableArg).to.equal('bigquery:query-builder|count the rows');
+                expectFullCoverage(result.parts, text);
+            });
+
+            it('parses a qualified command name whose qualifier contains periods', async () => {
+                // The qualifier is the plugin's directory name, which is derived from its identifier -
+                // `io.github.acme/tools` becomes `io.github.acme_tools`, periods and all. Without them
+                // in the charset the token falls through to the model as plain text, with no error.
+                const text = '/io.github.acme_tools:my-skill';
+                const result = await parse(text);
+
+                expect(result.parts.length).to.equal(1);
+                expect((result.parts[0] as ParsedChatRequestVariablePart).variableArg).to.equal('io.github.acme_tools:my-skill');
+                expectFullCoverage(result.parts, text);
+            });
+
+            it('leaves an unknown colon-separated slash token as plain text', async () => {
+                // Widening the command charset must not turn arbitrary text into a command.
+                await expectPlainText('/unknown:thing');
+                await expectPlainText('/io.github.other_tools:my-skill');
+            });
+
             it('keeps trailing whitespace out of the command part', async () => {
                 const text = '/summarize   ';
                 const result = await parse(text);

package/src/common/chat-request-parser.ts

@@ -19,7 +19,7 @@
  *--------------------------------------------------------------------------------------------*/
 // Partially copied from https://github.com/microsoft/vscode/blob/a2cab7255c0df424027be05d58e1b7b941f4ea60/src/vs/workbench/contrib/chat/common/chatRequestParser.ts
 
-import { inject, injectable } from '@theia/core/shared/inversify';
+import { inject, injectable, named } from '@theia/core/shared/inversify';
 import { ChatAgentService } from './chat-agent-service';
 import { ChatAgentLocation } from './chat-agents';
 import { ChatContext, ChatRequest } from './chat-model';
@@ -50,8 +50,10 @@ const variableReg = /^#([\w_\-]+)(?::([\w_\-_\/\\.:]+))?(?=(\s|$|\b))/i; // A #-
 // A /-command (/commandname) with optional arguments parsed separately. The command name must be
 // terminated by whitespace or the end of the input, so that path segments such as `/home/user` are
 // not mistaken for a command.
-const commandReg = /^\/([\w_\-]+)(?=\s|$)/;
-const nextCommandReg = /\s+\/([\w_\-]+)(?=\s|$)/g;
+// The colon and the period are in the charset so a qualified skill is invocable as
+// `/<qualifier>:<skill>`; the qualifier comes from a plugin identifier, so it usually has periods.
+const commandReg = /^\/([\w_\-.:]+)(?=\s|$)/;
+const nextCommandReg = /\s+\/([\w_\-.:]+)(?=\s|$)/g;
 
 export const ChatRequestParser = Symbol('ChatRequestParser');
 export interface ChatRequestParser {
@@ -74,7 +76,8 @@ export class ChatRequestParserImpl implements ChatRequestParser {
         @inject(ChatAgentService) private readonly agentService: ChatAgentService,
         @inject(AIVariableService) private readonly variableService: AIVariableService,
         @inject(ToolInvocationRegistry) private readonly toolInvocationRegistry: ToolInvocationRegistry,
-        @inject(ILogger) private readonly logger: ILogger,
+        @inject(ILogger) @named('ai-chat:ChatRequestParserImpl')
+        protected readonly logger: ILogger
     ) { }
 
     async parseChatRequest(request: ChatRequest, location: ChatAgentLocation, context: ChatContext): Promise<ParsedChatRequest> {

package/src/common/chat-service-session-restore.spec.ts

@@ -0,0 +1,190 @@
+// *****************************************************************************
+// Copyright (C) 2026 Safi Seid-Ahmad, K2view 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 { expect } from 'chai';
+import { Container } from '@theia/core/shared/inversify';
+import { ChatServiceImpl } from './chat-service';
+import { ChatSessionStore, ChatSessionIndex, ChatModelWithMetadata } from './chat-session-store';
+import { ChatAgentService } from './chat-agent-service';
+import { ChatRequestParser } from './chat-request-parser';
+import { AIVariableService, ToolInvocationRegistry } from '@theia/ai-core';
+import { ILogger } from '@theia/core';
+import { ChatContentDeserializerRegistry, ChatContentDeserializerRegistryImpl, DefaultChatContentDeserializerContribution } from './chat-content-deserializer';
+import { ChangeSetElementDeserializerRegistry, ChangeSetElementDeserializerRegistryImpl } from './change-set-element-deserializer';
+import { ChatAgentLocation } from './chat-agents';
+import { ChatModel } from './chat-model';
+import { SerializedChatData } from './chat-model-serialization';
+
+describe('ChatService Session Restore', () => {
+
+    class MockChatSessionStore implements ChatSessionStore {
+        public readCount = 0;
+        public readDelayMs = 50;
+        public serialized?: SerializedChatData;
+        public failReads = false;
+
+        async storeSessions(...sessions: Array<ChatModel | ChatModelWithMetadata>): Promise<void> { }
+
+        async readSession(sessionId: string): Promise<SerializedChatData | undefined> {
+            this.readCount++;
+            if (this.failReads) {
+                throw new Error('storage unavailable');
+            }
+            // Simulate the load time of a large persisted session: this is the window in
+            // which a second restore request for the same session can arrive.
+            await new Promise(resolve => setTimeout(resolve, this.readDelayMs));
+            return this.serialized;
+        }
+
+        async deleteSession(sessionId: string): Promise<void> { }
+
+        async clearAllSessions(): Promise<void> { }
+
+        async getSessionIndex(): Promise<ChatSessionIndex> {
+            return {};
+        }
+
+        async hasPersistedSessions(): Promise<boolean> {
+            return this.serialized !== undefined;
+        }
+
+        async setSessionTitle(sessionId: string, title: string): Promise<void> { }
+    }
+
+    class MockChatAgentService {
+        readonly onDidChangeAgents = { dispose: () => { } };
+        readonly onDefaultAgentChanged = { dispose: () => { } };
+
+        getAgent(): undefined {
+            return undefined;
+        }
+        getAgents(): never[] {
+            return [];
+        }
+        resolveAgent(): undefined {
+            return undefined;
+        }
+    }
+
+    class MockChatRequestParser {
+        parseChatRequest(): { parts: never[]; text: string } {
+            return { parts: [], text: '' };
+        }
+    }
+
+    class MockAIVariableService {
+        resolveVariables(): Promise<unknown[]> {
+            return Promise.resolve([]);
+        }
+    }
+
+    class MockLogger {
+        error(): void { }
+        warn(): void { }
+        info(): void { }
+        debug(): void { }
+    }
+
+    const mockToolInvocationRegistry: ToolInvocationRegistry = {
+        registerTool: () => { },
+        unregisterTool: () => { },
+        getFunction: () => undefined,
+        getFunctions: () => [],
+        getAllFunctions: () => [],
+        unregisterAllTools: () => { },
+        onDidChange: () => ({ dispose: () => { } })
+    };
+
+    function createChatService(sessionStore: ChatSessionStore): ChatServiceImpl {
+        const container = new Container();
+        container.bind(ChatSessionStore).toConstantValue(sessionStore);
+        container.bind(ChatAgentService).toConstantValue(new MockChatAgentService() as unknown as ChatAgentService);
+        container.bind(ChatRequestParser).toConstantValue(new MockChatRequestParser() as unknown as ChatRequestParser);
+        container.bind(AIVariableService).toConstantValue(new MockAIVariableService() as unknown as AIVariableService);
+        container.bind(ILogger).toConstantValue(new MockLogger() as unknown as ILogger);
+        container.bind(ToolInvocationRegistry).toConstantValue(mockToolInvocationRegistry);
+        const contentRegistry = new ChatContentDeserializerRegistryImpl();
+        new DefaultChatContentDeserializerContribution().registerDeserializers(contentRegistry);
+        container.bind(ChatContentDeserializerRegistry).toConstantValue(contentRegistry);
+        container.bind(ChangeSetElementDeserializerRegistry).toConstantValue(new ChangeSetElementDeserializerRegistryImpl());
+        container.bind(ChatServiceImpl).toSelf().inSingletonScope();
+        return container.get(ChatServiceImpl);
+    }
+
+    let store: MockChatSessionStore;
+    let chatService: ChatServiceImpl;
+    let restoredId: string;
+
+    beforeEach(async () => {
+        // Build valid serialized session data by serializing a real session.
+        const sourceStore = new MockChatSessionStore();
+        const sourceService = createChatService(sourceStore);
+        const sourceSession = sourceService.createSession(ChatAgentLocation.Panel);
+        await sourceService.sendRequest(sourceSession.id, { text: 'Test' });
+        const serialized: SerializedChatData = {
+            version: 1,
+            model: sourceSession.model.toSerializable(),
+            pinnedAgentId: undefined,
+            saveDate: Date.now()
+        };
+        restoredId = sourceSession.id;
+
+        store = new MockChatSessionStore();
+        store.serialized = serialized;
+        chatService = createChatService(store);
+    });
+
+    it('should register a session only once when restored concurrently', async () => {
+        const [first, second] = await Promise.all([
+            chatService.getOrRestoreSession(restoredId),
+            chatService.getOrRestoreSession(restoredId)
+        ]);
+
+        expect(first).to.not.be.undefined;
+        expect(second).to.equal(first);
+        expect(chatService.getSessions().filter(s => s.id === restoredId)).to.have.lengthOf(1);
+        expect(store.readCount).to.equal(1);
+    });
+
+    it('should keep getActiveSession working when concurrent restores are followed by activation', async () => {
+        // Opening a session from the session list runs restore + activate. A double-click on a
+        // large (slow to load) session runs it twice concurrently. Without a guard this
+        // registers the session twice, setActiveSession(id) marks both copies active, and every
+        // getActiveSession() call throws from then on — disabling the chat Home button and
+        // other session commands until the page is reloaded.
+        await Promise.all([
+            chatService.getOrRestoreSession(restoredId).then(() => chatService.setActiveSession(restoredId, { focus: true })),
+            chatService.getOrRestoreSession(restoredId).then(() => chatService.setActiveSession(restoredId, { focus: true }))
+        ]);
+
+        const active = chatService.getActiveSession();
+        expect(active).to.not.be.undefined;
+        expect(active!.id).to.equal(restoredId);
+    });
+
+    it('should allow restoring again after a failed attempt', async () => {
+        store.failReads = true;
+        await chatService.getOrRestoreSession(restoredId).then(
+            () => { throw new Error('expected the restore to fail'); },
+            () => undefined
+        );
+
+        store.failReads = false;
+        const session = await chatService.getOrRestoreSession(restoredId);
+        expect(session).to.not.be.undefined;
+        expect(session!.id).to.equal(restoredId);
+    });
+});

package/src/common/chat-service.ts

@@ -22,7 +22,7 @@
 import { AIVariableResolutionRequest, AIVariableService, ResolvedAIContextVariable, ToolInvocationRegistry, ToolRequest } from '@theia/ai-core';
 import { Emitter, Event, ILogger, URI, generateUuid } from '@theia/core';
 import { Deferred } from '@theia/core/lib/common/promise-util';
-import { inject, injectable, optional } from '@theia/core/shared/inversify';
+import { inject, injectable, optional, named } from '@theia/core/shared/inversify';
 import { ChatAgentService, DefaultChatAgentId, FallbackChatAgentId } from './chat-agent-service';
 import { ChatAgent, ChatAgentLocation, ChatSessionContext } from './chat-agents';
 import {
@@ -184,8 +184,8 @@ export class ChatServiceImpl implements ChatService {
     @inject(AIVariableService)
     protected variableService: AIVariableService;
 
-    @inject(ILogger)
-    protected logger: ILogger;
+    @inject(ILogger) @named('ai-chat:ChatServiceImpl')
+    protected readonly logger: ILogger;
 
     @inject(ChatSessionStore) @optional()
     protected sessionStore: ChatSessionStore | undefined;
@@ -201,6 +201,9 @@ export class ChatServiceImpl implements ChatService {
 
     protected _sessions: ChatSessionInternal[] = [];
 
+    /** In-flight session restores by id, so concurrent requests for the same session share one restore. */
+    protected readonly pendingSessionRestores = new Map<string, Promise<ChatSession | undefined>>();
+
     getSessions(): ChatSessionInternal[] {
         return [...this._sessions];
     }
@@ -532,7 +535,21 @@ export class ChatServiceImpl implements ChatService {
             this.logger.debug('Session already loaded', { sessionId });
             return existing;
         }
+        // Share one in-flight restore per session id: restoring a large session takes long
+        // enough that a second request (e.g. a double-click in the session list) can arrive
+        // mid-restore. Without this guard both restores register the session, and
+        // setActiveSession then marks both copies active, breaking getActiveSession()
+        // (and with it e.g. the chat Home button) until the page is reloaded.
+        let pending = this.pendingSessionRestores.get(sessionId);
+        if (!pending) {
+            pending = this.restoreSession(sessionId)
+                .finally(() => this.pendingSessionRestores.delete(sessionId));
+            this.pendingSessionRestores.set(sessionId, pending);
+        }
+        return pending;
+    }
 
+    protected async restoreSession(sessionId: string): Promise<ChatSession | undefined> {
         if (!this.sessionStore) {
             this.logger.debug('Session store not available, cannot restore', { sessionId });
             return undefined;

package/src/common/chat-session-summary-agent.ts

@@ -18,14 +18,18 @@ import {
     LanguageModelRequirement,
     PromptVariantSet
 } from '@theia/ai-core';
-import { injectable } from '@theia/core/shared/inversify';
+import { inject, injectable, named } from '@theia/core/shared/inversify';
 import { AbstractStreamParsingChatAgent, ChatAgent } from './chat-agents';
 import { CHAT_SESSION_SUMMARY_PROMPT } from './chat-session-summary-agent-prompt';
-import { nls } from '@theia/core';
+import { ILogger, nls } from '@theia/core';
 
 @injectable()
 export class ChatSessionSummaryAgent extends AbstractStreamParsingChatAgent implements ChatAgent {
     static ID = 'chat-session-summary-agent';
+
+    @inject(ILogger) @named('ai-chat:ChatSessionSummaryAgent')
+    protected override readonly logger: ILogger;
+
     id = ChatSessionSummaryAgent.ID;
     name = 'Chat Session Summary';
     override description = nls.localize('theia/ai/chat/chatSessionSummaryAgent/description', 'Agent for generating chat session summaries.');

package/src/common/chat-tool-preferences.ts

@@ -57,13 +57,13 @@ export const TOOL_CONFIRMATION_PREFERENCE = 'ai-features.chat.toolConfirmation';
 export const DEFAULT_TOOL_CONFIRMATION_PREFERENCE = 'ai-features.chat.defaultToolConfirmation';
 export const TOOL_CONFIRMATION_TIMEOUT_PREFERENCE = 'ai-features.chat.toolConfirmationTimeout';
 
-const TOOL_CONFIRMATION_MODE_VALUES = [
+export const TOOL_CONFIRMATION_MODE_VALUES = [
     ToolConfirmationMode.ALWAYS_ALLOW,
     ToolConfirmationMode.CONFIRM,
     ToolConfirmationMode.DISABLED
 ];
 
-const TOOL_CONFIRMATION_MODE_DESCRIPTIONS = [
+export const TOOL_CONFIRMATION_MODE_DESCRIPTIONS = [
     nls.localize('theia/ai/chat/toolConfirmation/alwaysAllow/description', 'Execute tools automatically without confirmation'),
     nls.localize('theia/ai/chat/toolConfirmation/confirm/description', 'Ask for confirmation before executing tools'),
     nls.localize('theia/ai/chat/toolConfirmation/disabled/description', 'Disable tool execution')

package/src/common/context-summary-variable.ts

@@ -22,7 +22,8 @@ import { ChatSessionContext } from './chat-agents';
 
 export const CONTEXT_SUMMARY_VARIABLE: AIVariable = {
     id: 'contextSummary',
-    description: nls.localize('theia/ai/core/contextSummaryVariable/description', 'Describes files in the context for a given session.'),
+    description: nls.localize('theia/ai/chat/contextSummaryVariable/description',
+        'A JSON summary of every element in the current chat session context, listing each element\'s type and identifiers.'),
     name: 'contextSummary',
 };
 

package/src/common/custom-chat-agent.ts

@@ -16,10 +16,14 @@
 
 import { CustomAgentPromptVariant, LanguageModelRequirement } from '@theia/ai-core';
 import { AbstractStreamParsingChatAgent } from './chat-agents';
-import { injectable } from '@theia/core/shared/inversify';
+import { ILogger } from '@theia/core';
+import { inject, injectable, named } from '@theia/core/shared/inversify';
 
 @injectable()
 export class CustomChatAgent extends AbstractStreamParsingChatAgent {
+    @inject(ILogger) @named('ai-chat:CustomChatAgent')
+    protected override readonly logger: ILogger;
+
     id: string = 'CustomChatAgent';
     name: string = 'CustomChatAgent';
     languageModelRequirements: LanguageModelRequirement[] = [{ purpose: 'chat' }];

package/src/common/file-read-tracker.ts

@@ -0,0 +1,29 @@
+// *****************************************************************************
+// Copyright (C) 2026 Ehab Younes.
+//
+// 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 { URI } from '@theia/core';
+
+export const FileReadTracker = Symbol('FileReadTracker');
+
+/** Tracks the content an agent has seen per chat session, so that changes by anyone else can be reported back to it. */
+export interface FileReadTracker {
+    /** Snapshots `uri` as the session's agent just saw it, or forgets it if it is gone. Pass `content` when at hand to save a read. */
+    recordRead(sessionId: string, uri: URI, content?: string): Promise<void>;
+    /** Whether `uri` differs from what the session's agent last saw. `false` if never read or gone: neither holds content a write could discard. */
+    isStale(sessionId: string, uri: URI): Promise<boolean>;
+    /** Files changed since the session's agent read them, reported again until it reads them anew so an ignored notice cannot get lost. */
+    getChangedFiles(sessionId: string): Promise<string[]>;
+}

package/src/common/index.ts

@@ -27,5 +27,6 @@ export * from './custom-chat-agent';
 export * from './parsed-chat-request';
 export * from './context-variables';
 export * from './chat-tool-request-service';
+export * from './file-read-tracker';
 export * from './chat-tool-confirmation-timeout';
 export * from './provider-error-formatter';