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

package/src/browser/file-read-tracker-impl.spec.ts

@@ -0,0 +1,318 @@
+// *****************************************************************************
+// 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 { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+const disableJSDOM = enableJSDOM();
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+FrontendApplicationConfigProvider.set({});
+
+import { Emitter, Event, URI } from '@theia/core';
+import { BinaryBuffer } from '@theia/core/lib/common/buffer';
+import { FileService } from '@theia/filesystem/lib/browser/file-service';
+import { FileChangesEvent, FileChangeType, FileOperationError, FileOperationResult, FileStat } from '@theia/filesystem/lib/common/files';
+import { MonacoWorkspace } from '@theia/monaco/lib/browser/monaco-workspace';
+import { WorkspaceService } from '@theia/workspace/lib/browser/workspace-service';
+import { expect } from 'chai';
+import { FileReadTrackerImpl } from './file-read-tracker-impl';
+
+disableJSDOM();
+
+const SESSION = 'session-1';
+const OTHER_SESSION = 'session-2';
+const ROOT = new URI('file:///workspace');
+const FILE = ROOT.resolve('a.ts');
+/** As `resolveRelativePath` expects it back: root name plus path within that root. */
+const FILE_LABEL = 'workspace/a.ts';
+
+/** Drives the tracker against in-memory content: `contents` stands in for the files on disk. */
+class TestFileReadTracker extends FileReadTrackerImpl {
+    readonly contents = new Map<string, string>([[FILE.toString(), 'original']]);
+    /** Makes reading fail as a file too large to compare would, rather than as a missing one. */
+    readFails = false;
+    /** Runs once inside a read, to change the file while the tracker is still reading it. */
+    duringNextRead?: () => void;
+    /** The encoding the files are stored in: `read` decodes with it, `readFile` hands back their bytes. */
+    encoding: BufferEncoding = 'utf8';
+    protected override readonly maxFilesPerSession = 2;
+    /** The workspace roots labels are built against. */
+    readonly roots = [ROOT];
+    protected override readonly workspaceService = {
+        tryGetRoots: () => this.roots.map(resource => ({ resource } as FileStat))
+    } as WorkspaceService;
+    protected override readonly monacoWorkspace = { getTextDocument: () => undefined } as unknown as MonacoWorkspace;
+    /** Both decoders, so that a test can tell which one the tracker reads through. */
+    protected override readonly fileService = {
+        read: async (uri: URI) => ({ value: this.contentOf(uri) }),
+        readFile: async (uri: URI) => ({ value: BinaryBuffer.wrap(Buffer.from(this.contentOf(uri), this.encoding)) })
+    } as unknown as FileService;
+    protected readonly fileChangeEmitter = new Emitter<FileChangesEvent>();
+    protected readonly documentChangeEmitter = new Emitter<string>();
+
+    constructor() {
+        super();
+        // `@postConstruct` only runs on container resolution, so wire the listeners here.
+        this.init();
+    }
+
+    protected override get fileChanges(): Event<FileChangesEvent> {
+        return this.fileChangeEmitter.event;
+    }
+
+    protected override get documentChanges(): Event<string> {
+        return this.documentChangeEmitter.event;
+    }
+
+    /** Stands in for the file on disk, failing the way the file service would. */
+    protected contentOf(uri: URI): string {
+        if (this.readFails) {
+            throw new FileOperationError(`${uri} is too large`, FileOperationResult.FILE_TOO_LARGE);
+        }
+        const content = this.contents.get(uri.toString());
+        if (content === undefined) {
+            throw new FileOperationError(`${uri} does not exist`, FileOperationResult.FILE_NOT_FOUND);
+        }
+        const during = this.duringNextRead;
+        this.duringNextRead = undefined;
+        during?.();
+        return content;
+    }
+
+    /** Records what the agent saw, as `getFileContent` does. */
+    agentRead(uri = FILE, sessionId = SESSION): Promise<void> {
+        return this.recordRead(sessionId, uri, this.contents.get(uri.toString()));
+    }
+
+    /** Changes content behind the agent's back and notifies the tracker, as the workspace would. */
+    somebodyElseChanges(content: string, uri = FILE): void {
+        this.contents.set(uri.toString(), content);
+        this.fileChanged(uri);
+    }
+
+    somebodyElseDeletes(uri = FILE): void {
+        this.contents.delete(uri.toString());
+        this.fileChanged(uri);
+    }
+
+    fileChanged(...uris: URI[]): void {
+        this.fileChangeEmitter.fire(new FileChangesEvent(uris.map(resource => ({ resource, type: FileChangeType.UPDATED }))));
+    }
+
+    documentChanged(uri = FILE): void {
+        this.documentChangeEmitter.fire(uri.toString());
+    }
+}
+
+describe('FileReadTrackerImpl', () => {
+
+    it('reports a file that changed after it was read', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+
+        tracker.somebodyElseChanges('changed');
+
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal([FILE_LABEL]);
+        expect(await tracker.isStale(SESSION, FILE)).to.be.true;
+    });
+
+    it('reports a file whose unsaved document changed', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+
+        tracker.contents.set(FILE.toString(), 'the user typed something');
+        tracker.documentChanged();
+
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal([FILE_LABEL]);
+    });
+
+    it('keeps reporting a change until the file is read again', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+        tracker.somebodyElseChanges('changed');
+        expect(await tracker.getChangedFiles(SESSION)).to.have.lengthOf(1);
+        expect(await tracker.getChangedFiles(SESSION)).to.have.lengthOf(1);
+
+        await tracker.agentRead();
+
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+        expect(await tracker.isStale(SESSION, FILE)).to.be.false;
+    });
+
+    it('ignores files that were never read', async () => {
+        const tracker = new TestFileReadTracker();
+
+        tracker.somebodyElseChanges('changed');
+
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+        expect(await tracker.isStale(SESSION, FILE)).to.be.false;
+    });
+
+    it('ignores a change that left the content untouched', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+
+        // e.g. saving an unmodified document, or a formatter that had nothing to do
+        tracker.fileChanged(FILE);
+
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+        expect(await tracker.isStale(SESSION, FILE)).to.be.false;
+    });
+
+    it('stops reporting once an edit is undone', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+        tracker.somebodyElseChanges('changed');
+        expect(await tracker.getChangedFiles(SESSION)).to.have.lengthOf(1);
+
+        tracker.somebodyElseChanges('original');
+
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+    });
+
+    it('reports a deleted file once, then forgets it and allows writing it', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+
+        tracker.somebodyElseDeletes();
+
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal([FILE_LABEL]);
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+        expect(await tracker.isStale(SESSION, FILE)).to.be.false;
+    });
+
+    it('forgets a file that no longer exists when it is recorded', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+        tracker.somebodyElseDeletes();
+
+        // as the change set element does after applying a deletion
+        await tracker.recordRead(SESSION, FILE);
+
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+    });
+
+    it('keeps reporting a file it cannot read, and does not allow overwriting it', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+        tracker.fileChanged(FILE);
+        tracker.readFails = true;
+
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal([FILE_LABEL]);
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal([FILE_LABEL]);
+        expect(await tracker.isStale(SESSION, FILE)).to.be.true;
+    });
+
+    it('reports a change made while the read recording it was still in flight', async () => {
+        const tracker = new TestFileReadTracker();
+        tracker.duringNextRead = () => {
+            tracker.contents.set(FILE.toString(), 'the user typed something');
+            tracker.documentChanged();
+        };
+
+        // no content handed in, so the tracker reads it itself
+        await tracker.recordRead(SESSION, FILE);
+
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal([FILE_LABEL]);
+        expect(await tracker.isStale(SESSION, FILE)).to.be.true;
+    });
+
+    it('records nothing when the content cannot be read', async () => {
+        const tracker = new TestFileReadTracker();
+        tracker.readFails = true;
+
+        await tracker.recordRead(SESSION, FILE);
+
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+    });
+
+    it('treats a write by another session as an external change', async () => {
+        const tracker = new TestFileReadTracker();
+        await tracker.agentRead();
+        await tracker.agentRead(FILE, OTHER_SESSION);
+
+        tracker.somebodyElseChanges('written by the other session');
+        await tracker.recordRead(OTHER_SESSION, FILE);
+
+        expect(await tracker.getChangedFiles(OTHER_SESSION)).to.be.empty;
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal([FILE_LABEL]);
+    });
+
+    it('compares a file the read tools decode as UTF-16, not as UTF-8', async () => {
+        const tracker = new TestFileReadTracker();
+        tracker.encoding = 'utf16le'; // as a Windows-written `.ps1` is stored
+        await tracker.agentRead();
+
+        tracker.fileChanged(FILE);
+
+        expect(await tracker.getChangedFiles(SESSION)).to.be.empty;
+    });
+
+    describe('naming changed files', () => {
+
+        /** How the notice names `file` after it changed, in a workspace with the given extra roots. */
+        async function nameOf(file: URI, ...extraRoots: URI[]): Promise<string[]> {
+            const tracker = new TestFileReadTracker();
+            tracker.roots.push(...extraRoots);
+            tracker.contents.set(file.toString(), 'original');
+            await tracker.agentRead(file);
+            tracker.somebodyElseChanges('changed', file);
+            return tracker.getChangedFiles(SESSION);
+        }
+
+        it('names a file by the root it is in', async () => {
+            expect(await nameOf(new URI('file:///elsewhere/lib/b.ts'), new URI('file:///elsewhere/lib'))).to.deep.equal(['lib/b.ts']);
+        });
+
+        it('names a file by its root when that root is listed twice', async () => {
+            expect(await nameOf(FILE, ROOT)).to.deep.equal([FILE_LABEL]);
+        });
+
+        it('names a file by uri when two roots share the name it would use', async () => {
+            expect(await nameOf(FILE, new URI('file:///elsewhere/workspace'))).to.deep.equal([FILE.toString()]);
+        });
+
+        it('names a file by uri when it is outside every root', async () => {
+            expect(await nameOf(new URI('file:///etc/hosts'))).to.deep.equal(['file:///etc/hosts']);
+        });
+    });
+
+    it('evicts the least recently recorded file beyond the per-session limit', async () => {
+        const tracker = new TestFileReadTracker();
+        const files = ['a', 'b', 'c'].map(name => new URI(`file:///workspace/${name}.ts`));
+        for (const uri of files) {
+            tracker.contents.set(uri.toString(), 'original');
+            await tracker.agentRead(uri);
+        }
+
+        files.forEach(uri => tracker.somebodyElseChanges('changed', uri));
+
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal(['workspace/b.ts', 'workspace/c.ts']);
+    });
+
+    it('keeps a re-read file tracked, evicting the one untouched for longest', async () => {
+        const tracker = new TestFileReadTracker();
+        const [a, b, c] = ['a', 'b', 'c'].map(name => new URI(`file:///workspace/${name}.ts`));
+        [a, b, c].forEach(uri => tracker.contents.set(uri.toString(), 'original'));
+        await tracker.agentRead(a);
+        await tracker.agentRead(b);
+        await tracker.agentRead(a);
+        await tracker.agentRead(c);
+
+        tracker.somebodyElseChanges('changed', a);
+        tracker.somebodyElseChanges('changed', b);
+
+        expect(await tracker.getChangedFiles(SESSION)).to.deep.equal(['workspace/a.ts']);
+    });
+});

package/src/browser/file-read-tracker-impl.ts

@@ -0,0 +1,208 @@
+// *****************************************************************************
+// 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 { Event, URI } from '@theia/core';
+import { hash } from '@theia/core/lib/common/hash';
+import { inject, injectable, postConstruct } from '@theia/core/shared/inversify';
+import { FileService } from '@theia/filesystem/lib/browser/file-service';
+import { FileChangesEvent, FileOperationError, FileOperationResult } from '@theia/filesystem/lib/common/files';
+import { MonacoWorkspace } from '@theia/monaco/lib/browser/monaco-workspace';
+import { WorkspaceService } from '@theia/workspace/lib/browser/workspace-service';
+import { FileReadTracker } from '../common/file-read-tracker';
+
+/** The content an agent saw, and whether anything has since signalled a possible change. */
+interface TrackedFile {
+    /** `undefined` until the read determining it returns, so that it matches no content. */
+    seenHash?: number;
+    maybeStale: boolean;
+}
+
+@injectable()
+export class FileReadTrackerImpl implements FileReadTracker {
+
+    @inject(FileService)
+    protected readonly fileService: FileService;
+
+    @inject(MonacoWorkspace)
+    protected readonly monacoWorkspace: MonacoWorkspace;
+
+    @inject(WorkspaceService)
+    protected readonly workspaceService: WorkspaceService;
+
+    /** Session id -> tracked file uri -> state. Both levels are insertion ordered and bounded. */
+    protected readonly sessions = new Map<string, Map<string, TrackedFile>>();
+
+    /**
+     * Arbitrary bounds. Sessions are never disposed here, as that would mean depending on the `ChatService`
+     * that owns the agents using this service, so the least recently used are evicted; that only loses a notice.
+     */
+    protected readonly maxSessions: number = 32;
+    protected readonly maxFilesPerSession: number = 200;
+
+    /** A file grown past this is not read to compare, so a flagged one stays reported as changed. The read tools hand an agent far less. */
+    protected readonly maxComparedFileSize: number = 4 * 1024 * 1024;
+
+    /** Only flags entries; reading and hashing happens in {@link isStale} and {@link getChangedFiles}. */
+    @postConstruct()
+    protected init(): void {
+        this.fileChanges(event => this.handleFileChanges(event));
+        this.documentChanges(uri => this.invalidate(uri));
+    }
+
+    protected get fileChanges(): Event<FileChangesEvent> {
+        return this.fileService.onDidFilesChange;
+    }
+
+    /** Uris of documents whose unsaved content changed, which never reaches the file system. */
+    protected get documentChanges(): Event<string> {
+        return Event.map(this.monacoWorkspace.onDidChangeTextDocument, event => event.model.uri);
+    }
+
+    async recordRead(sessionId: string, uri: URI, content?: string): Promise<void> {
+        const key = uri.toString();
+        const files = this.touchSession(sessionId);
+        // Re-insert to move the key last, so eviction drops the least recently used.
+        files.delete(key);
+        // Tracked before the read, so a change arriving during it flags this entry instead of being overwritten.
+        const tracked: TrackedFile = { maybeStale: false };
+        files.set(key, tracked);
+        this.evictOverflow(files, this.maxFilesPerSession);
+        const current = content ?? await this.resolveContent(uri);
+        if (current === undefined) {
+            if (files.get(key) === tracked) { // a later read may own the entry by now
+                files.delete(key);
+            }
+            return;
+        }
+        tracked.seenHash = hash(current);
+    }
+
+    async isStale(sessionId: string, uri: URI): Promise<boolean> {
+        const files = this.sessions.get(sessionId);
+        if (!files) {
+            return false;
+        }
+        const key = uri.toString();
+        const tracked = files.get(key);
+        if (!tracked?.maybeStale) {
+            return false;
+        }
+        return await this.recheck(files, key, tracked) === 'changed';
+    }
+
+    async getChangedFiles(sessionId: string): Promise<string[]> {
+        const files = this.sessions.get(sessionId);
+        if (!files) {
+            return [];
+        }
+        const labels = await Promise.all([...files]
+            .filter(([, tracked]) => tracked.maybeStale)
+            .map(async ([key, tracked]) => await this.recheck(files, key, tracked) === 'unchanged' ? undefined : this.getLabel(new URI(key))));
+        return labels.filter((label): label is string => label !== undefined);
+    }
+
+    /**
+     * Flags the tracked files the event touched, by uri lookup rather than {@link FileChangesEvent.contains},
+     * which scans the whole change list. A deleted parent folder is therefore only noticed on the next read.
+     */
+    protected handleFileChanges(event: FileChangesEvent): void {
+        for (const change of event.changes) {
+            this.invalidate(change.resource.toString());
+        }
+    }
+
+    /** Compares a flagged file against what the agent saw, clearing the flag when the contents match again. */
+    protected async recheck(files: Map<string, TrackedFile>, key: string, tracked: TrackedFile): Promise<'unchanged' | 'changed' | 'gone'> {
+        let current: string;
+        try {
+            current = await this.readCurrentContent(new URI(key));
+        } catch (error) {
+            if (this.isFileNotFound(error)) {
+                files.delete(key);
+                return 'gone';
+            }
+            return 'changed';
+        }
+        if (hash(current) === tracked.seenHash) {
+            tracked.maybeStale = false;
+            return 'unchanged';
+        }
+        return 'changed';
+    }
+
+    protected isFileNotFound(error: unknown): boolean {
+        return error instanceof FileOperationError && error.fileOperationResult === FileOperationResult.FILE_NOT_FOUND;
+    }
+
+    /** `undefined` when the content cannot be read at all. */
+    protected async resolveContent(uri: URI): Promise<string | undefined> {
+        try {
+            return await this.readCurrentContent(uri);
+        } catch {
+            return undefined;
+        }
+    }
+
+    /** The content the agent would be handed now, preferring the open editor document as `getFileContent` does. */
+    protected async readCurrentContent(uri: URI): Promise<string> {
+        const document = this.monacoWorkspace.getTextDocument(uri.toString());
+        if (document) {
+            return document.getText();
+        }
+        return (await this.fileService.read(uri, { limits: { size: this.maxComparedFileSize } })).value;
+    }
+
+    /** A path the agent can pass back to `getFileContent`, which takes `<rootName>/<relativePath>` as well as a uri. */
+    protected getLabel(uri: URI): string {
+        const roots = this.workspaceService.tryGetRoots().map(root => root.resource);
+        for (const root of roots) {
+            const relativePath = root.relative(uri)?.toString();
+            // A basename shared with another root would resolve to that other root.
+            if (relativePath && !roots.some(other => other.path.base === root.path.base && !other.isEqual(root))) {
+                return `${root.path.base}/${relativePath}`;
+            }
+        }
+        return uri.toString();
+    }
+
+    protected invalidate(uriString: string): void {
+        for (const files of this.sessions.values()) {
+            const tracked = files.get(uriString);
+            if (tracked) {
+                tracked.maybeStale = true;
+            }
+        }
+    }
+
+    protected touchSession(sessionId: string): Map<string, TrackedFile> {
+        const files = this.sessions.get(sessionId) ?? new Map<string, TrackedFile>();
+        // Re-insert to move the key last, so eviction drops the least recently used.
+        this.sessions.delete(sessionId);
+        this.sessions.set(sessionId, files);
+        this.evictOverflow(this.sessions, this.maxSessions);
+        return files;
+    }
+
+    /** Drops entries from the front, which insertion order makes the least recently used ones. */
+    protected evictOverflow(entries: Map<string, unknown>, limit: number): void {
+        for (const key of entries.keys()) {
+            if (entries.size <= limit) {
+                return;
+            }
+            entries.delete(key);
+        }
+    }
+}

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

@@ -72,6 +72,10 @@ export const aiChatPreferences: PreferenceSchema = {
         [SESSION_STORAGE_PREF]: {
             type: 'string',
             enum: ['workspace', 'global'] satisfies SessionStorageScope[],
+            enumItemLabels: [
+                nls.localizeByDefault('Workspace'),
+                nls.localizeByDefault('Global')
+            ],
             enumDescriptions: [
                 nls.localize('theia/ai/chat/sessionStorageScope/workspace',
                     'Store chat sessions in workspace-specific metadata storage. Sessions are associated with the workspace but stored outside the workspace directory.'),

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

@@ -130,7 +130,7 @@ export class ChatAgentServiceImpl implements ChatAgentService {
     @inject(ContributionProvider) @named(ChatAgent)
     protected readonly agentContributions: ContributionProvider<ChatAgent>;
 
-    @inject(ILogger)
+    @inject(ILogger) @named('ai-chat:ChatAgentServiceImpl')
     protected readonly logger: ILogger;
 
     @inject(AgentService)

package/src/common/chat-agents.spec.ts

@@ -33,12 +33,16 @@ import {
     ThinkingChatResponseContentImpl,
 } from './chat-model';
 import { ParsedChatRequest, ParsedChatRequestTextPart } from './parsed-chat-request';
+import { FileReadTracker } from './file-read-tracker';
+import { ILogger } from '@theia/core';
+import { MockLogger } from '@theia/core/lib/common/test/mock-logger';
 
 class TestChatAgent extends AbstractChatAgent {
     readonly id = 'test-agent';
     readonly name = 'Test Agent';
     readonly languageModelRequirements: LanguageModelRequirement[] = [];
     protected readonly defaultLanguageModelPurpose = 'chat';
+    protected override logger: ILogger = new MockLogger();
 
     protected addContentsToResponse(): Promise<void> {
         return Promise.resolve();
@@ -59,6 +63,15 @@ class TestChatAgent extends AbstractChatAgent {
     public setLanguageModelRegistry(registry: LanguageModelRegistry): void {
         this.languageModelRegistry = registry;
     }
+
+    public exposeAppendExternalFileChangeNotice(request: MutableChatRequestModel, messages: LanguageModelMessage[]): Promise<void> {
+        return this.appendExternalFileChangeNotice(request, messages);
+    }
+
+    public setFileReadTracker(tracker: FileReadTracker): void {
+        this.fileReadTracker = tracker;
+    }
+
 }
 
 function createParsedRequest(text: string, request?: Partial<ChatRequest>): ParsedChatRequest {
@@ -201,6 +214,7 @@ class StreamParsingTestChatAgent extends AbstractStreamParsingChatAgent {
     readonly name = 'Stream Test Agent';
     readonly languageModelRequirements: LanguageModelRequirement[] = [];
     protected readonly defaultLanguageModelPurpose = 'chat';
+    protected override logger: ILogger = new MockLogger();
 
     exposeParse(token: LanguageModelStreamResponsePart): ChatResponseContent | ChatResponseContent[] {
         return this.parse(token, undefined as never);
@@ -292,3 +306,61 @@ describe('AbstractChatAgent.getLanguageModelForRequest', () => {
         expect(error).to.be.an('error');
     });
 });
+
+describe('AbstractChatAgent.appendExternalFileChangeNotice', () => {
+
+    function createAgent(getChangedFiles: () => Promise<string[]>): TestChatAgent {
+        const agent = new TestChatAgent();
+        agent.setFileReadTracker({
+            recordRead: async () => { },
+            isStale: async () => false,
+            getChangedFiles
+        });
+        return agent;
+    }
+
+    function createRequest(): MutableChatRequestModel {
+        return new MutableChatModel(ChatAgentLocation.Panel).addRequest(createParsedRequest('Hello'));
+    }
+
+    function textsOf(messages: LanguageModelMessage[]): string[] {
+        return messages.flatMap(message => message.type === 'text' ? [message.text] : []);
+    }
+
+    it('appends a trailing user message listing the changed files', async () => {
+        const agent = createAgent(async () => ['/workspace/a.ts', '/workspace/b.ts']);
+        const messages: LanguageModelMessage[] = [];
+
+        await agent.exposeAppendExternalFileChangeNotice(createRequest(), messages);
+
+        expect(messages).to.have.lengthOf(1);
+        expect(messages[0].actor).to.equal('user');
+        expect(textsOf(messages)[0]).to.contain('/workspace/a.ts').and.to.contain('/workspace/b.ts');
+    });
+
+    it('appends nothing when no file changed', async () => {
+        const agent = createAgent(async () => []);
+        const messages: LanguageModelMessage[] = [];
+
+        await agent.exposeAppendExternalFileChangeNotice(createRequest(), messages);
+
+        expect(messages).to.be.empty;
+    });
+
+    it('appends nothing when no tracker is bound', async () => {
+        const messages: LanguageModelMessage[] = [];
+
+        await new TestChatAgent().exposeAppendExternalFileChangeNotice(createRequest(), messages);
+
+        expect(messages).to.be.empty;
+    });
+
+    it('does not fail the request when the changed files cannot be determined', async () => {
+        const agent = createAgent(async () => { throw new Error('tracker unavailable'); });
+        const messages: LanguageModelMessage[] = [];
+
+        await agent.exposeAppendExternalFileChangeNotice(createRequest(), messages);
+
+        expect(messages).to.be.empty;
+    });
+});