@theia/ai-core 1.77.0-next.49 → 1.77.0-next.57

package/src/browser/agents-md-service.spec.ts

@@ -0,0 +1,258 @@
+// *****************************************************************************
+// Copyright (C) 2026 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 { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+const disableJSDOM = enableJSDOM();
+
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+// Guarded: another spec in the same mocha process may already have set it, and `set` throws on a
+// second call.
+try {
+    FrontendApplicationConfigProvider.get();
+} catch {
+    FrontendApplicationConfigProvider.set({});
+}
+
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { Disposable, Emitter, ILogger, Logger, URI } from '@theia/core';
+import { FileChangesEvent, FileChangeType, FileOperation, FileOperationEvent, FileStatWithMetadata } from '@theia/filesystem/lib/common/files';
+import { DefaultAgentsMdService } from './agents-md-service';
+
+disableJSDOM();
+
+/** Long enough to outlast the service's 50ms coalescing window. */
+const AFTER_DEBOUNCE_MS = 80;
+
+describe('AgentsMdService', () => {
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    let fileServiceMock: any;
+    let workspaceServiceMock: any;
+    let loggerErrorSpy: sinon.SinonStub;
+    let fileChangesEmitter: Emitter<FileChangesEvent>;
+    let operationsEmitter: Emitter<FileOperationEvent>;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+
+    function root(path: string): { resource: URI, name: string } {
+        const resource = new URI(`file://${path}`);
+        return { resource, name: resource.path.base };
+    }
+
+    /** Only `resource` is read by the service; the rest satisfies the event's signature. */
+    function stat(path: string): FileStatWithMetadata {
+        return { resource: new URI(`file://${path}`) } as FileStatWithMetadata;
+    }
+
+    function createService(): DefaultAgentsMdService {
+        const service = new DefaultAgentsMdService();
+        (service as unknown as { fileService: unknown }).fileService = fileServiceMock;
+        (service as unknown as { workspaceService: unknown }).workspaceService = workspaceServiceMock;
+        const loggerMock: ILogger = sinon.createStubInstance(Logger);
+        loggerMock.error = loggerErrorSpy;
+        (service as unknown as { logger: unknown }).logger = loggerMock;
+        return service;
+    }
+
+    /** Runs the `@postConstruct` initialization and waits for the initial scan. */
+    async function start(service: DefaultAgentsMdService): Promise<void> {
+        (service as unknown as { init(): void }).init();
+        await service.ready;
+    }
+
+    function existing(...paths: string[]): void {
+        fileServiceMock.exists.callsFake((uri: URI) => Promise.resolve(paths.includes(uri.path.toString())));
+    }
+
+    beforeEach(() => {
+        fileChangesEmitter = new Emitter<FileChangesEvent>();
+        operationsEmitter = new Emitter<FileOperationEvent>();
+        loggerErrorSpy = sinon.stub();
+        fileServiceMock = {
+            exists: sinon.stub().resolves(false),
+            read: sinon.stub().resolves({ value: '' }),
+            watch: sinon.stub().returns(Disposable.NULL),
+            onDidFilesChange: (listener: (e: FileChangesEvent) => void) => fileChangesEmitter.event(listener),
+            onDidRunOperation: (listener: (e: FileOperationEvent) => void) => operationsEmitter.event(listener)
+        };
+        workspaceServiceMock = {
+            ready: Promise.resolve(),
+            tryGetRoots: sinon.stub().returns([]),
+            onWorkspaceChanged: sinon.stub().returns(Disposable.NULL)
+        };
+    });
+
+    afterEach(() => {
+        sinon.restore();
+        fileChangesEmitter.dispose();
+        operationsEmitter.dispose();
+    });
+
+    it('finds nothing without a workspace root', async () => {
+        const service = createService();
+        await start(service);
+
+        expect(service.getAgentsMdFiles()).to.be.empty;
+    });
+
+    it('finds nothing when the root has no AGENTS.md', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        const service = createService();
+        await start(service);
+
+        expect(service.getAgentsMdFiles()).to.be.empty;
+    });
+
+    it('discovers AGENTS.md at the workspace root', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        existing('/ws/AGENTS.md');
+        fileServiceMock.read.resolves({ value: '# Project' });
+        const service = createService();
+        await start(service);
+
+        const files = service.getAgentsMdFiles();
+        expect(files).to.have.lengthOf(1);
+        expect(files[0].uri.path.toString()).to.equal('/ws/AGENTS.md');
+        expect(files[0].content).to.equal('# Project');
+        expect(files[0].rootName).to.equal('ws');
+    });
+
+    it('ignores a nested AGENTS.md, only the root is scanned', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        existing('/ws/packages/core/AGENTS.md');
+        const service = createService();
+        await start(service);
+
+        expect(service.getAgentsMdFiles()).to.be.empty;
+    });
+
+    it('reports one file per root, in workspace root order', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/a'), root('/b')]);
+        existing('/a/AGENTS.md', '/b/AGENTS.md');
+        fileServiceMock.read.callsFake((uri: URI) => Promise.resolve({ value: `content of ${uri.path.toString()}` }));
+        const service = createService();
+        await start(service);
+
+        expect(service.getAgentsMdFiles().map(file => file.rootName)).to.deep.equal(['a', 'b']);
+        expect(service.getAgentsMdFiles()[1].content).to.equal('content of /b/AGENTS.md');
+    });
+
+    it('keeps the other roots when one file cannot be read', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/broken'), root('/ok')]);
+        existing('/broken/AGENTS.md', '/ok/AGENTS.md');
+        fileServiceMock.read.callsFake((uri: URI) => uri.path.toString() === '/broken/AGENTS.md'
+            ? Promise.reject(new Error('boom'))
+            : Promise.resolve({ value: 'fine' }));
+        const service = createService();
+        await start(service);
+
+        expect(service.getAgentsMdFiles().map(file => file.rootName)).to.deep.equal(['ok']);
+        expect(loggerErrorSpy.called).to.be.true;
+    });
+
+    it('picks up an AGENTS.md created after the initial scan', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        const service = createService();
+        await start(service);
+        expect(service.getAgentsMdFiles()).to.be.empty;
+
+        existing('/ws/AGENTS.md');
+        fileServiceMock.read.resolves({ value: 'added later' });
+        const changed = new Promise<void>(resolve => service.onDidChange(() => resolve()));
+        fileChangesEmitter.fire(new FileChangesEvent([{ resource: new URI('file:///ws/AGENTS.md'), type: FileChangeType.ADDED }]));
+
+        await changed;
+        expect(service.getAgentsMdFiles().map(file => file.content)).to.deep.equal(['added later']);
+    });
+
+    it('picks up an AGENTS.md written through the FileService before the watcher is live', async () => {
+        // The migration writes AGENTS.md milliseconds after startup, while `FileService.watch` is
+        // still registering its backend watcher, so no file change event is emitted for it.
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        const service = createService();
+        await start(service);
+        expect(service.getAgentsMdFiles()).to.be.empty;
+
+        existing('/ws/AGENTS.md');
+        fileServiceMock.read.resolves({ value: 'migrated' });
+        const changed = new Promise<void>(resolve => service.onDidChange(() => resolve()));
+        operationsEmitter.fire(new FileOperationEvent(new URI('file:///ws/AGENTS.md'), FileOperation.CREATE, stat('/ws/AGENTS.md')));
+
+        await changed;
+        expect(service.getAgentsMdFiles().map(file => file.content)).to.deep.equal(['migrated']);
+    });
+
+    it('picks up a file moved onto the AGENTS.md path, where only the move target matches', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        const service = createService();
+        await start(service);
+
+        existing('/ws/AGENTS.md');
+        fileServiceMock.read.resolves({ value: 'renamed into place' });
+        const changed = new Promise<void>(resolve => service.onDidChange(() => resolve()));
+        operationsEmitter.fire(new FileOperationEvent(new URI('file:///ws/NOTES.md'), FileOperation.MOVE, stat('/ws/AGENTS.md')));
+
+        await changed;
+        expect(service.getAgentsMdFiles().map(file => file.content)).to.deep.equal(['renamed into place']);
+    });
+
+    it('rescans when an AGENTS.md is written while the initial scan is still running', async () => {
+        // Regression: `watchedFiles` used to be published only after a scan finished, so an
+        // operation arriving mid-scan was dropped and the empty result stuck for the session.
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        const service = createService();
+        let firstCheck = true;
+        fileServiceMock.exists.callsFake(() => {
+            if (firstCheck) {
+                firstCheck = false;
+                operationsEmitter.fire(new FileOperationEvent(new URI('file:///ws/AGENTS.md'), FileOperation.CREATE, stat('/ws/AGENTS.md')));
+                return Promise.resolve(false);
+            }
+            return Promise.resolve(true);
+        });
+        fileServiceMock.read.resolves({ value: 'written during the scan' });
+
+        await start(service);
+        await new Promise(resolve => setTimeout(resolve, AFTER_DEBOUNCE_MS));
+
+        expect(service.getAgentsMdFiles().map(file => file.content)).to.deep.equal(['written during the scan']);
+    });
+
+    it('ignores operations on other files in the root', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        const service = createService();
+        await start(service);
+        const onDidChange = sinon.spy();
+        service.onDidChange(onDidChange);
+
+        operationsEmitter.fire(new FileOperationEvent(new URI('file:///ws/README.md'), FileOperation.CREATE, stat('/ws/README.md')));
+        await new Promise(resolve => setTimeout(resolve, AFTER_DEBOUNCE_MS));
+
+        expect(onDidChange.called).to.be.false;
+    });
+
+    it('ignores changes to other files in the root', async () => {
+        workspaceServiceMock.tryGetRoots.returns([root('/ws')]);
+        const service = createService();
+        await start(service);
+        const onDidChange = sinon.spy();
+        service.onDidChange(onDidChange);
+
+        fileChangesEmitter.fire(new FileChangesEvent([{ resource: new URI('file:///ws/README.md'), type: FileChangeType.UPDATED }]));
+        await new Promise(resolve => setTimeout(resolve, AFTER_DEBOUNCE_MS));
+
+        expect(onDidChange.called).to.be.false;
+    });
+});

package/src/browser/agents-md-service.ts

@@ -0,0 +1,212 @@
+// *****************************************************************************
+// Copyright (C) 2026 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 { Deferred } from '@theia/core/lib/common/promise-util';
+import { Disposable, DisposableCollection, Emitter, Event, ILogger, URI } from '@theia/core';
+import { FileService } from '@theia/filesystem/lib/browser/file-service';
+import { FileChangesEvent, FileOperationEvent } from '@theia/filesystem/lib/common/files';
+import { WorkspaceService } from '@theia/workspace/lib/browser';
+import { AGENTS_MD_FILE_NAME } from '../common/agents-md';
+
+/** Debounce delay for coalescing rapid file system events. */
+const UPDATE_DEBOUNCE_MS = 50;
+
+export interface AgentsMdFile {
+    /** URI of the discovered `AGENTS.md`. */
+    uri: URI;
+    /** Content as of the last scan. */
+    content: string;
+    /** Name of the workspace root holding the file, used as provenance label when merging several roots. */
+    rootName: string;
+}
+
+export const AgentsMdService = Symbol('AgentsMdService');
+export interface AgentsMdService {
+    /** The `AGENTS.md` files discovered in the workspace roots, in workspace root order. */
+    getAgentsMdFiles(): AgentsMdFile[];
+
+    /** Fired after every scan, whether or not the result changed. */
+    readonly onDidChange: Event<void>;
+
+    /** Resolves once the initial scan is complete. Always resolves, even if the scan failed. */
+    readonly ready: Promise<void>;
+}
+
+/**
+ * Discovers `<root>/AGENTS.md` for every workspace root and keeps the content up to date.
+ *
+ * Only the workspace roots themselves are scanned. A nested `AGENTS.md` cascade with proximity
+ * precedence, `@path` imports and a global `~/.agents/AGENTS.md` are deliberately out of scope.
+ */
+@injectable()
+export class DefaultAgentsMdService implements AgentsMdService, Disposable {
+
+    @inject(FileService)
+    protected readonly fileService: FileService;
+
+    @inject(WorkspaceService)
+    protected readonly workspaceService: WorkspaceService;
+
+    @inject(ILogger) @named('ai-core:DefaultAgentsMdService')
+    protected readonly logger: ILogger;
+
+    protected files: AgentsMdFile[] = [];
+
+    /** Watchers of the current scan; disposed and rebuilt on every rescan. */
+    protected toDispose = new DisposableCollection();
+    /** Kept apart from {@link toDispose}, which does not survive a rescan. */
+    protected readonly toDisposeOnServiceDispose = new DisposableCollection();
+
+    /** URIs of the `AGENTS.md` files we react to: one per workspace root, whether or not it exists. */
+    protected watchedFiles = new Set<string>();
+
+    protected updateDebounceTimeout: ReturnType<typeof setTimeout> | undefined;
+
+    /** True while {@link update} is running, so concurrent callers do not duplicate the scan. */
+    protected updateInProgress = false;
+    /** Set when {@link update} is called while another run is in progress; triggers a follow-up scan. */
+    protected updateRescheduled = false;
+
+    protected readonly onDidChangeEmitter = new Emitter<void>();
+    readonly onDidChange: Event<void> = this.onDidChangeEmitter.event;
+
+    protected _ready = new Deferred<void>();
+    get ready(): Promise<void> {
+        return this._ready.promise;
+    }
+
+    @postConstruct()
+    protected init(): void {
+        this.toDisposeOnServiceDispose.push(this.onDidChangeEmitter);
+        this.toDisposeOnServiceDispose.push(this.fileService.onDidFilesChange((event: FileChangesEvent) => {
+            if (event.changes.some(change => this.isWatched(change.resource))) {
+                this.scheduleUpdate();
+            }
+        }));
+        // The watcher above only reports what the backend sees, and `FileService.watch` registers
+        // that watcher asynchronously. An `AGENTS.md` written through the application right after
+        // startup - most notably by the migration - therefore lands in the gap before the watcher is
+        // live and would be missed for the rest of the session. Operations performed through the
+        // FileService are reported here synchronously, independent of any watcher.
+        this.toDisposeOnServiceDispose.push(this.fileService.onDidRunOperation((event: FileOperationEvent) => {
+            if (this.isWatched(event.resource) || (event.target && this.isWatched(event.target.resource))) {
+                this.scheduleUpdate();
+            }
+        }));
+        this.initialize();
+    }
+
+    protected async initialize(): Promise<void> {
+        try {
+            await this.workspaceService.ready;
+        } catch (error) {
+            this.logger.error('Failed to resolve the workspace, scanning the already known roots for AGENTS.md', error);
+        }
+        // Listen before the initial scan, otherwise a change landing while it runs is recorded as
+        // already applied and dropped. update()'s in-progress guard coalesces the overlap.
+        this.toDisposeOnServiceDispose.push(this.workspaceService.onWorkspaceChanged(() => this.scheduleUpdate()));
+        try {
+            await this.update();
+        } catch (error) {
+            this.logger.error('Initial AGENTS.md scan failed', error);
+        }
+        this._ready.resolve();
+    }
+
+    getAgentsMdFiles(): AgentsMdFile[] {
+        return [...this.files];
+    }
+
+    /** Whether `resource` is one of the `AGENTS.md` locations this service tracks. */
+    protected isWatched(resource: URI): boolean {
+        return this.watchedFiles.has(resource.toString());
+    }
+
+    dispose(): void {
+        if (this.updateDebounceTimeout) {
+            clearTimeout(this.updateDebounceTimeout);
+            this.updateDebounceTimeout = undefined;
+        }
+        this.toDisposeOnServiceDispose.dispose();
+        this.toDispose.dispose();
+    }
+
+    protected scheduleUpdate(): void {
+        if (this.updateDebounceTimeout) {
+            clearTimeout(this.updateDebounceTimeout);
+        }
+        this.updateDebounceTimeout = setTimeout(() => {
+            this.updateDebounceTimeout = undefined;
+            this.update();
+        }, UPDATE_DEBOUNCE_MS);
+    }
+
+    protected async update(): Promise<void> {
+        if (this.updateDebounceTimeout) {
+            clearTimeout(this.updateDebounceTimeout);
+            this.updateDebounceTimeout = undefined;
+        }
+        // Serialise concurrent calls: a workspace-ready trigger and a file-change-driven
+        // scheduleUpdate() can fire within the same async tick. The second caller records a pending
+        // request and lets the first finish; the follow-up is re-scheduled through the debouncer.
+        if (this.updateInProgress) {
+            this.updateRescheduled = true;
+            return;
+        }
+        this.updateInProgress = true;
+        try {
+            await this.doUpdate();
+        } finally {
+            this.updateInProgress = false;
+            if (this.updateRescheduled) {
+                this.updateRescheduled = false;
+                this.scheduleUpdate();
+            }
+        }
+    }
+
+    protected async doUpdate(): Promise<void> {
+        const newDisposables = new DisposableCollection();
+        const newFiles: AgentsMdFile[] = [];
+        const roots = this.workspaceService.tryGetRoots();
+
+        // Publish the tracked locations before doing any I/O. A file operation landing while this
+        // scan is still running has to be recognized so that the in-progress guard can reschedule;
+        // assigning only at the end would drop it and leave this scan's stale result in place.
+        this.watchedFiles = new Set(roots.map(root => root.resource.resolve(AGENTS_MD_FILE_NAME).toString()));
+
+        for (const root of roots) {
+            const fileUri = root.resource.resolve(AGENTS_MD_FILE_NAME);
+            // Watch the root, not the file: a watcher on a missing file cannot report its creation.
+            newDisposables.push(this.fileService.watch(root.resource, { recursive: false, excludes: [] }));
+            try {
+                if (await this.fileService.exists(fileUri)) {
+                    const content = await this.fileService.read(fileUri);
+                    newFiles.push({ uri: fileUri, content: content.value, rootName: root.name });
+                }
+            } catch (error) {
+                this.logger.error(`Failed to read '${fileUri.toString()}': ${error}`);
+            }
+        }
+
+        this.toDispose.dispose();
+        this.toDispose = newDisposables;
+        this.files = newFiles;
+
+        this.onDidChangeEmitter.fire();
+    }
+}

package/src/browser/agents-md-variable-contribution.spec.ts

@@ -0,0 +1,180 @@
+// *****************************************************************************
+// Copyright (C) 2026 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 { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+const disableJSDOM = enableJSDOM();
+
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+// Guarded: another spec in the same mocha process may already have set it, and `set` throws on a
+// second call.
+try {
+    FrontendApplicationConfigProvider.get();
+} catch {
+    FrontendApplicationConfigProvider.set({});
+}
+
+import { expect } from 'chai';
+import { URI } from '@theia/core';
+import { AgentsMdFile, AgentsMdService } from './agents-md-service';
+import { AGENTS_MD_AUTO_LOADED_VARIABLE, AGENTS_MD_CONTENT_VARIABLE, AGENTS_MD_VARIABLE, AgentsMdVariableContribution } from './agents-md-variable-contribution';
+import { AIVariableContext } from '../common/variable-service';
+import { matchFunctionsRegEx } from '../common/prompt-service-util';
+
+disableJSDOM();
+
+describe('AgentsMdVariableContribution', () => {
+
+    function file(rootName: string, content: string): AgentsMdFile {
+        return { uri: new URI(`file:///${rootName}/AGENTS.md`), content, rootName };
+    }
+
+    /**
+     * @param rootCount how many workspace roots are open. Defaults to one per discovered file, which
+     * is the ordinary case; pass it explicitly to build a workspace whose root count and file count
+     * differ, since auto-loading keys on roots rather than files.
+     */
+    function createContribution(files: AgentsMdFile[], rootCount = files.length): AgentsMdVariableContribution {
+        const contribution = new AgentsMdVariableContribution();
+        const service: AgentsMdService = {
+            getAgentsMdFiles: () => files,
+            onDidChange: () => ({ dispose: () => { } }),
+            ready: Promise.resolve()
+        };
+        (contribution as unknown as { agentsMdService: AgentsMdService }).agentsMdService = service;
+        (contribution as unknown as { workspaceService: unknown }).workspaceService = {
+            tryGetRoots: () => new Array(rootCount).fill({})
+        };
+        return contribution;
+    }
+
+    async function resolve(files: AgentsMdFile[], variable: typeof AGENTS_MD_VARIABLE, rootCount?: number): Promise<string> {
+        const resolved = await createContribution(files, rootCount).resolve({ variable }, {} as AIVariableContext);
+        return resolved!.value;
+    }
+
+    describe('agentsMdAutoLoaded', () => {
+        it('resolves to nothing when the workspace has no AGENTS.md', async () => {
+            expect(await resolve([], AGENTS_MD_AUTO_LOADED_VARIABLE, 1)).to.equal('');
+        });
+
+        it('inlines the root file when the workspace has a single root', async () => {
+            expect(await resolve([file('theia', '# Project\n\nUse npm.')], AGENTS_MD_AUTO_LOADED_VARIABLE)).to.equal(
+                '<project_instructions path="theia/AGENTS.md">\n# Project\n\nUse npm.\n</project_instructions>'
+            );
+        });
+
+        it('loads nothing once the workspace has more than one root', async () => {
+            expect(await resolve([file('a', 'x'), file('b', 'y')], AGENTS_MD_AUTO_LOADED_VARIABLE)).to.equal('');
+        });
+
+        it('loads nothing in a multi-root workspace where only one root has a file', async () => {
+            // Keyed on root count, not file count: a workspace with several roots has no single
+            // project root, even when only one of them carries an AGENTS.md.
+            expect(await resolve([file('a', 'x')], AGENTS_MD_AUTO_LOADED_VARIABLE, 2)).to.equal('');
+        });
+
+        it('escapes the path but leaves the Markdown content untouched', async () => {
+            const resolved = await resolve([file('a&b', '# Heading <not xml> & "quoted"')], AGENTS_MD_AUTO_LOADED_VARIABLE, 1);
+            expect(resolved).to.contain('path="a&amp;b/AGENTS.md"');
+            expect(resolved).to.contain('# Heading <not xml> & "quoted"');
+        });
+
+        it('keeps function references in the content from attaching tools', async () => {
+            const resolved = await resolve([file('a', 'Use ~{getFileContent} and {{selectedText}}.')], AGENTS_MD_AUTO_LOADED_VARIABLE, 1);
+            expect(matchFunctionsRegEx(resolved)).to.be.empty;
+            expect(resolved).to.contain('{{selectedText}}');
+        });
+    });
+
+    describe('agentsMd', () => {
+        it('resolves to nothing when the workspace has no AGENTS.md', async () => {
+            expect(await resolve([], AGENTS_MD_VARIABLE)).to.equal('');
+        });
+
+        it('advertises nothing when the single root file is already loaded', async () => {
+            // Otherwise the model is told to read a file it has just been handed.
+            expect(await resolve([file('theia', 'x')], AGENTS_MD_VARIABLE)).to.equal('');
+        });
+
+        it('advertises one entry per root once there is more than one root', async () => {
+            expect(await resolve([file('a', 'x'), file('b', 'y')], AGENTS_MD_VARIABLE)).to.equal(
+                '<agents_md_files>\n<file>a/AGENTS.md</file>\n<file>b/AGENTS.md</file>\n</agents_md_files>'
+            );
+        });
+
+        it('advertises the single file of a multi-root workspace rather than loading it', async () => {
+            expect(await resolve([file('a', 'x')], AGENTS_MD_VARIABLE, 2)).to.equal(
+                '<agents_md_files>\n<file>a/AGENTS.md</file>\n</agents_md_files>'
+            );
+        });
+
+        it('escapes XML in the root name', async () => {
+            expect(await resolve([file('a&b', 'x')], AGENTS_MD_VARIABLE, 2)).to.contain('<file>a&amp;b/AGENTS.md</file>');
+        });
+
+        it('never inlines the content', async () => {
+            expect(await resolve([file('a', 'secret project conventions'), file('b', 'y')], AGENTS_MD_VARIABLE))
+                .to.not.contain('secret project conventions');
+        });
+    });
+
+    describe('the two are mutually exclusive', () => {
+        it('never emits both for the same workspace', async () => {
+            for (const [files, roots] of [
+                [[file('theia', 'x')], 1],
+                [[file('a', 'x'), file('b', 'y')], 2],
+                [[file('a', 'x')], 2],
+                [[], 1]
+            ] as [AgentsMdFile[], number][]) {
+                const loaded = await resolve(files, AGENTS_MD_AUTO_LOADED_VARIABLE, roots);
+                const listed = await resolve(files, AGENTS_MD_VARIABLE, roots);
+                expect(loaded === '' || listed === '', `both were non-empty for ${roots} root(s)`).to.be.true;
+            }
+        });
+    });
+
+    describe('agentsMdContent', () => {
+        it('resolves to nothing when the workspace has no AGENTS.md', async () => {
+            expect(await resolve([], AGENTS_MD_CONTENT_VARIABLE)).to.equal('');
+        });
+
+        it('inlines a single root verbatim, without provenance framing', async () => {
+            expect(await resolve([file('theia', '# Project\n\nUse npm.')], AGENTS_MD_CONTENT_VARIABLE)).to.equal('# Project\n\nUse npm.');
+        });
+
+        it('labels the sources when several roots contribute', async () => {
+            expect(await resolve([file('a', 'first'), file('b', 'second')], AGENTS_MD_CONTENT_VARIABLE)).to.equal(
+                '### a\n\nfirst\n\n### b\n\nsecond'
+            );
+        });
+
+        it('keeps function references in the content from attaching tools', async () => {
+            expect(matchFunctionsRegEx(await resolve([file('a', '~{getFileContent}')], AGENTS_MD_CONTENT_VARIABLE))).to.be.empty;
+            expect(matchFunctionsRegEx(await resolve([file('a', '~{x}'), file('b', '~{y}')], AGENTS_MD_CONTENT_VARIABLE))).to.be.empty;
+        });
+    });
+
+    describe('canResolve', () => {
+        it('claims all three variables and nothing else', () => {
+            const contribution = createContribution([]);
+            const context = {} as AIVariableContext;
+            expect(contribution.canResolve({ variable: AGENTS_MD_AUTO_LOADED_VARIABLE }, context)).to.equal(1);
+            expect(contribution.canResolve({ variable: AGENTS_MD_VARIABLE }, context)).to.equal(1);
+            expect(contribution.canResolve({ variable: AGENTS_MD_CONTENT_VARIABLE }, context)).to.equal(1);
+            expect(contribution.canResolve({ variable: { id: 'other', name: 'other', description: '' } }, context)).to.equal(-1);
+        });
+    });
+});