@theia/ai-core 1.77.0-next.7 → 1.77.0-next.77

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);
+        });
+    });
+});

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

@@ -0,0 +1,182 @@
+// *****************************************************************************
+// 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 } from '@theia/core/shared/inversify';
+import { MaybePromise, nls } from '@theia/core';
+import {
+    AIVariable, AIVariableContext, AIVariableContribution, AIVariableResolutionRequest,
+    AIVariableResolver, AIVariableService, ResolvedAIVariable
+} from '../common/variable-service';
+import { WorkspaceService } from '@theia/workspace/lib/browser';
+import { AGENTS_MD_FILE_NAME } from '../common/agents-md';
+import { AgentsMdFile, AgentsMdService } from './agents-md-service';
+
+export const AGENTS_MD_AUTO_LOADED_VARIABLE: AIVariable = {
+    id: 'agentsMdAutoLoaded',
+    name: 'agentsMdAutoLoaded',
+    description: nls.localize('theia/ai/core/agentsMdAutoLoadedVariable/description',
+        'Returns the content of the workspace root AGENTS.md when the workspace has a single root, so that it is always in context')
+};
+
+export const AGENTS_MD_VARIABLE: AIVariable = {
+    id: 'agentsMd',
+    name: 'agentsMd',
+    description: nls.localize('theia/ai/core/agentsMdVariable/description',
+        'Lists the AGENTS.md files an agent has to read on demand, i.e. the ones that are not already loaded')
+};
+
+export const AGENTS_MD_CONTENT_VARIABLE: AIVariable = {
+    id: 'agentsMdContent',
+    name: 'agentsMdContent',
+    description: nls.localize('theia/ai/core/agentsMdContentVariable/description',
+        'Returns the full content of the AGENTS.md files of the workspace')
+};
+
+/**
+ * Resolves the three ways of consuming `AGENTS.md`.
+ *
+ * A **single-root** workspace has an unambiguous project root, so its `AGENTS.md` is always in
+ * context, mirroring how other tools implementing the standard treat the root file. A workspace with
+ * several roots has no such file, so nothing is loaded and every discovered file is advertised
+ * instead, to be read on demand. {@link AGENTS_MD_AUTO_LOADED_VARIABLE} and
+ * {@link AGENTS_MD_VARIABLE} are therefore mutually exclusive by construction: at most one of them is
+ * ever non-empty.
+ *
+ * - {@link AGENTS_MD_AUTO_LOADED_VARIABLE} inlines the single root's file, or nothing.
+ * - {@link AGENTS_MD_VARIABLE} advertises files by path so a tool-calling agent can fetch them with
+ *   `getFileContent`, or nothing.
+ * - {@link AGENTS_MD_CONTENT_VARIABLE} always inlines everything discovered, regardless of root
+ *   count, for consumers such as code completion that have no tool-calling loop and therefore cannot
+ *   fetch anything on demand.
+ *
+ * All three resolve to the empty string when the workspace has no `AGENTS.md`.
+ */
+@injectable()
+export class AgentsMdVariableContribution implements AIVariableContribution, AIVariableResolver {
+
+    @inject(AgentsMdService)
+    protected readonly agentsMdService: AgentsMdService;
+
+    @inject(WorkspaceService)
+    protected readonly workspaceService: WorkspaceService;
+
+    registerVariables(service: AIVariableService): void {
+        service.registerResolver(AGENTS_MD_AUTO_LOADED_VARIABLE, this);
+        service.registerResolver(AGENTS_MD_VARIABLE, this);
+        service.registerResolver(AGENTS_MD_CONTENT_VARIABLE, this);
+    }
+
+    canResolve(request: AIVariableResolutionRequest, _context: AIVariableContext): MaybePromise<number> {
+        if (request.variable.name === AGENTS_MD_AUTO_LOADED_VARIABLE.name
+            || request.variable.name === AGENTS_MD_VARIABLE.name
+            || request.variable.name === AGENTS_MD_CONTENT_VARIABLE.name) {
+            return 1;
+        }
+        return -1;
+    }
+
+    async resolve(request: AIVariableResolutionRequest, _context: AIVariableContext): Promise<ResolvedAIVariable | undefined> {
+        // Without this a request issued before the initial scan completes would silently report that
+        // the workspace has no project context.
+        await this.agentsMdService.ready;
+        const files = this.agentsMdService.getAgentsMdFiles();
+
+        if (request.variable.name === AGENTS_MD_AUTO_LOADED_VARIABLE.name) {
+            return { variable: request.variable, value: this.generateAutoLoaded(files) };
+        }
+        if (request.variable.name === AGENTS_MD_VARIABLE.name) {
+            // Suppressed when the root file is already in context, so the model is never told to read
+            // a file it has just been handed.
+            return { variable: request.variable, value: this.isAutoLoading() ? '' : this.generateAgentsMdXML(files) };
+        }
+        if (request.variable.name === AGENTS_MD_CONTENT_VARIABLE.name) {
+            return { variable: request.variable, value: this.mergeContent(files) };
+        }
+        return undefined;
+    }
+
+    /**
+     * Whether the workspace root's `AGENTS.md` is put into context rather than advertised. Keyed on
+     * the number of workspace **roots**, not the number of discovered files: a workspace with several
+     * roots has no single project root whose file could stand for the whole session, even when only
+     * one of those roots happens to carry an `AGENTS.md`.
+     */
+    protected isAutoLoading(): boolean {
+        return this.workspaceService.tryGetRoots().length === 1;
+    }
+
+    /**
+     * Inlines the single root's file. The content is raw Markdown and not XML-escaped; only the path,
+     * which is an attribute, is.
+     */
+    protected generateAutoLoaded(files: AgentsMdFile[]): string {
+        if (!this.isAutoLoading() || files.length === 0) {
+            return '';
+        }
+        const file = files[0];
+        return `<project_instructions path="${this.escapeXml(this.toWorkspaceRelativePath(file))}">\n${this.escapeFunctionReferences(file.content)}\n</project_instructions>`;
+    }
+
+    /**
+     * Advertises the files by their `<rootName>/AGENTS.md` path, the path format the workspace tools
+     * accept and return, so the model can pass it to `getFileContent` verbatim.
+     */
+    protected generateAgentsMdXML(files: AgentsMdFile[]): string {
+        if (files.length === 0) {
+            return '';
+        }
+        const entries = files.map(file => `<file>${this.escapeXml(this.toWorkspaceRelativePath(file))}</file>`).join('\n');
+        return `<agents_md_files>\n${entries}\n</agents_md_files>`;
+    }
+
+    /**
+     * Inlines the content. A single root contributes its file verbatim; only a multi-root workspace
+     * gets provenance headings, mirroring how equal-priority prompt fragment sources are merged.
+     */
+    protected mergeContent(files: AgentsMdFile[]): string {
+        if (files.length === 0) {
+            return '';
+        }
+        if (files.length === 1) {
+            return this.escapeFunctionReferences(files[0].content);
+        }
+        return files.map(file => `### ${file.rootName}\n\n${this.escapeFunctionReferences(file.content)}`).join('\n\n');
+    }
+
+    /**
+     * Keeps `~{...}` in inlined content literal. Function references are matched on the resolved
+     * prompt text, so a `~{someTool}` in a file anyone in the repository can edit would otherwise
+     * attach that tool to every agent using the fragment. A zero-width space between `~` and `{`
+     * breaks the match without changing what the model reads. `{{...}}` needs no such treatment, as
+     * variables are not resolved recursively.
+     */
+    protected escapeFunctionReferences(content: string): string {
+        return content.replace(/~\{/g, '~\u200B{');
+    }
+
+    protected toWorkspaceRelativePath(file: AgentsMdFile): string {
+        return `${file.rootName}/${AGENTS_MD_FILE_NAME}`;
+    }
+
+    protected escapeXml(text: string): string {
+        return text
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+}

package/src/browser/ai-core-frontend-module.ts

@@ -67,6 +67,7 @@ import { DefaultPromptFragmentCustomizationService } from './frontend-prompt-cus
 import { DefaultFrontendVariableService, FrontendVariableService } from './frontend-variable-service';
 import { PromptTemplateContribution } from './prompttemplate-contribution';
 import { FileVariableContribution } from './file-variable-contribution';
+import { WorkspaceRelativePathResolver } from './workspace-relative-path-resolver';
 import { TheiaVariableContribution } from './theia-variable-contribution';
 import { TodayVariableContribution } from '../common/today-variable-contribution';
 import { AgentsVariableContribution } from '../common/agents-variable-contribution';
@@ -84,6 +85,11 @@ import { ProductNameVariableContribution } from './product-name-variable-contrib
 import { CapabilityVariableContribution } from '../common/capability-variable-contribution';
 import { GenericCapabilitiesVariableContribution } from './generic-capabilities-variable-contribution';
 import { GenericCapabilitiesPromptFragmentContribution } from './generic-capabilities-prompt-fragment-contribution';
+import { AgentsMdService, DefaultAgentsMdService } from './agents-md-service';
+import { AgentsMdVariableContribution } from './agents-md-variable-contribution';
+import { AgentsMdPromptFragmentContribution } from './agents-md-prompt-fragment-contribution';
+import { AgentsMdMigrationService } from './agents-md-migration-service';
+import { AgentsMdFrontendApplicationContribution } from './agents-md-frontend-application-contribution';
 import { LanguageModelService } from '../common/language-model-service';
 import { FrontendLanguageModelServiceImpl } from './frontend-language-model-service';
 import { TokenUsageFrontendService } from './token-usage-frontend-service';
@@ -142,6 +148,13 @@ export default new ContainerModule(bind => {
     bind(SkillPromptCoordinator).toSelf().inSingletonScope();
     bind(FrontendApplicationContribution).toService(SkillPromptCoordinator);
 
+    bind(DefaultAgentsMdService).toSelf().inSingletonScope();
+    bind(AgentsMdService).toService(DefaultAgentsMdService);
+    bind(AgentsMdMigrationService).toSelf().inSingletonScope();
+    bind(AgentsMdFrontendApplicationContribution).toSelf().inSingletonScope();
+    bind(FrontendApplicationContribution).toService(AgentsMdFrontendApplicationContribution);
+    bind(CommandContribution).toService(AgentsMdFrontendApplicationContribution);
+
     bindRootContributionProvider(bind, SkillDirectoryContribution);
 
     bindRootContributionProvider(bind, AIVariableContribution);
@@ -156,12 +169,15 @@ export default new ContainerModule(bind => {
     bind(PromptVariableContribution).toSelf().inSingletonScope();
     bind(AIVariableContribution).toService(PromptVariableContribution);
     bind(AIVariableContribution).to(TodayVariableContribution).inSingletonScope();
+    bind(WorkspaceRelativePathResolver).toSelf().inSingletonScope();
     bind(AIVariableContribution).to(FileVariableContribution).inSingletonScope();
     bind(AgentsVariableContribution).toSelf().inSingletonScope();
     bind(AIVariableContribution).toService(AgentsVariableContribution);
     bind(AIVariableContribution).to(OpenEditorsVariableContribution).inSingletonScope();
     bind(SkillsVariableContribution).toSelf().inSingletonScope();
     bind(AIVariableContribution).toService(SkillsVariableContribution);
+    bind(AgentsMdVariableContribution).toSelf().inSingletonScope();
+    bind(AIVariableContribution).toService(AgentsMdVariableContribution);
     bind(AIVariableContribution).to(CapabilityVariableContribution).inSingletonScope();
     bind(AIVariableContribution).to(ProductNameVariableContribution).inSingletonScope();
 
@@ -171,6 +187,9 @@ export default new ContainerModule(bind => {
     bind(GenericCapabilitiesPromptFragmentContribution).toSelf().inSingletonScope();
     bind(FrontendApplicationContribution).toService(GenericCapabilitiesPromptFragmentContribution);
 
+    bind(AgentsMdPromptFragmentContribution).toSelf().inSingletonScope();
+    bind(FrontendApplicationContribution).toService(AgentsMdPromptFragmentContribution);
+
     bind(FrontendApplicationContribution).to(AICoreFrontendApplicationContribution).inSingletonScope();
 
     bind(ToolInvocationRegistry).to(ToolInvocationRegistryImpl).inSingletonScope();