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

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

@@ -84,6 +84,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 +147,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);
@@ -162,6 +174,8 @@ export default new ContainerModule(bind => {
     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 +185,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();

package/src/browser/frontend-prompt-customization-service.spec.ts

@@ -266,6 +266,10 @@ Template`;
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 return (this as any).provenanceLabel(sourceUri);
             }
+
+            public useSourceMaps(active: Map<string, FragmentEntry>, all: Map<string, FragmentEntry>): void {
+                Object.assign(this, { activeCustomizations: active, allCustomizations: all });
+            }
         }
 
         let service: TestableCustomizationService;
@@ -362,6 +366,26 @@ Template`;
             expect(idxB).to.be.lessThan(idxC);
         });
 
+        it('reports every source and marks all equal-priority merged sources active', () => {
+            service.testAddTemplate(activeMap, 'project-info', 'Shared instructions',
+                'file:///config/project-info.prompttemplate', allMap, 1, CustomizationSource.CUSTOMIZED);
+            service.testAddTemplate(activeMap, 'project-info', 'Root A instructions',
+                'file:///rootA/.prompts/project-info.prompttemplate', allMap, 2, CustomizationSource.FOLDER);
+            service.testAddTemplate(activeMap, 'project-info', 'Root B instructions',
+                'file:///rootB/.prompts/project-info.prompttemplate', allMap, 2, CustomizationSource.FOLDER);
+            service.testAddTemplate(activeMap, 'other-fragment', 'Unrelated',
+                'file:///config/other.prompttemplate', allMap, 1, CustomizationSource.CUSTOMIZED);
+            service.useSourceMaps(activeMap, allMap);
+
+            expect(service.getPromptFragmentCustomizationSources('project-info').map(source => ({
+                path: source.uri.path.toString(), template: source.template, active: source.active
+            }))).to.deep.equal([
+                { path: '/config/project-info.prompttemplate', template: 'Shared instructions', active: false },
+                { path: '/rootA/.prompts/project-info.prompttemplate', template: 'Root A instructions', active: true },
+                { path: '/rootB/.prompts/project-info.prompttemplate', template: 'Root B instructions', active: true }
+            ]);
+        });
+
         it('provenanceLabel extracts grandparent directory name from URI', () => {
             // For "file:///home/user/my-project/.prompts/foo.prompttemplate"
             // parent is ".prompts", grandparent is "my-project"

package/src/browser/frontend-prompt-customization-service.ts

@@ -18,7 +18,8 @@ import { DisposableCollection, URI, Event, Emitter, nls, ILogger } from '@theia/
 import { OpenerService } from '@theia/core/lib/browser';
 import { inject, injectable, postConstruct, named } from '@theia/core/shared/inversify';
 import {
-    PromptFragmentCustomizationService, CustomAgentDescription, CustomAgentPromptVariant, CustomizedPromptFragment, CommandPromptFragmentMetadata, CustomAgentsLocation
+    PromptFragmentCustomizationService, CustomAgentDescription, CustomAgentPromptVariant, CustomizedPromptFragment, CommandPromptFragmentMetadata, CustomAgentsLocation,
+    PromptFragmentCustomizationSource
 } from '../common';
 import { ConfigurableInMemoryResources } from '../common/configurable-in-memory-resources';
 import { parseFrontmatter, serializeFrontmatter } from '../common/frontmatter';
@@ -1166,6 +1167,17 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
         return this.activeCustomizations.has(id);
     }
 
+    getPromptFragmentCustomizationSources(id: string): PromptFragmentCustomizationSource[] {
+        const activeSources = this.activeCustomizations.get(id)?.sourceUris ?? [];
+        return Array.from(this.allCustomizations.values())
+            .filter(entry => entry.id === id)
+            .map(entry => ({
+                uri: new URI(entry.sourceUri),
+                template: entry.template,
+                active: activeSources.includes(entry.sourceUri)
+            }));
+    }
+
     getActivePromptFragmentCustomization(id: string): CustomizedPromptFragment | undefined {
         const entry = this.activeCustomizations.get(id);
         if (!entry) {

package/src/browser/index.ts

@@ -37,6 +37,11 @@ export * from './theia-variable-contribution';
 export * from './open-editors-variable-contribution';
 export * from './skills-variable-contribution';
 export * from './skill-service';
+export * from './agents-md-service';
+export * from './agents-md-variable-contribution';
+export * from './agents-md-prompt-fragment-contribution';
+export * from './agents-md-migration-service';
+export * from './agents-md-frontend-application-contribution';
 export * from './skill-prompt-coordinator';
 export * from './agent-plugin-ui-bridge';
 export * from './skill-registry-ui-bridge';

package/src/common/agents-md.ts

@@ -0,0 +1,37 @@
+// *****************************************************************************
+// 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
+// *****************************************************************************
+
+/**
+ * File name of the [AGENTS.md standard](https://agents.md/), the source of project-specific context
+ * for AI agents. Only this exact name is recognized: `AGENT.md`, `CLAUDE.md` and the various
+ * vendor-specific instruction files are deliberately not treated as fallbacks.
+ */
+export const AGENTS_MD_FILE_NAME = 'AGENTS.md';
+
+/**
+ * Advertises the workspace's `AGENTS.md` files by path so that a tool-calling agent can read them on
+ * demand. Reference it from a system prompt with `{{prompt:agents-md}}`.
+ */
+export const AGENTS_MD_PROMPT_FRAGMENT_ID = 'agents-md';
+
+/**
+ * Inlines the full `AGENTS.md` content.
+ *
+ * @deprecated Kept so that prompts still referencing `{{prompt:project-info}}` keep working, and for
+ * consumers without a tool-calling loop, which cannot fetch anything on demand. Prefer
+ * {@link AGENTS_MD_PROMPT_FRAGMENT_ID}, which lets the model load the content only when relevant.
+ */
+export const PROJECT_INFO_PROMPT_FRAGMENT_ID = 'project-info';

package/src/common/ai-variable-resource.ts

@@ -14,7 +14,7 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import * as deepEqual from 'fast-deep-equal';
+import deepEqual from 'fast-deep-equal';
 import { inject, injectable, postConstruct, named } from '@theia/core/shared/inversify';
 import { Resource, URI, generateUuid, ILogger } from '@theia/core';
 import { AIVariableContext, AIVariableResolutionRequest } from './variable-service';

package/src/common/index.ts

@@ -41,6 +41,7 @@ export * from './ai-variable-resource';
 export * from './configurable-in-memory-resources';
 export * from './notification-types';
 export * from './skill';
+export * from './agents-md';
 export * from './frontmatter';
 export * from './capability-utils';
 export * from './tool-constants';

package/src/common/prompt-service.ts

@@ -247,6 +247,13 @@ export interface CustomAgentsLocation {
     kind: 'agents-dir' | 'legacy-yaml';
 }
 
+/** A loaded customization file, including files hidden by a higher-priority override. */
+export interface PromptFragmentCustomizationSource {
+    uri: URI;
+    template: string;
+    active: boolean;
+}
+
 /**
  * Service responsible for customizing prompt fragments
  */
@@ -269,6 +276,13 @@ export interface PromptFragmentCustomizationService {
      */
     isPromptFragmentCustomized(fragmentId: string): boolean;
 
+    /**
+     * Gets every loaded customization file of a prompt fragment, including the ones hidden by a
+     * higher-priority customization, regardless of whether they are active.
+     * @param fragmentId The prompt fragment ID
+     */
+    getPromptFragmentCustomizationSources?(fragmentId: string): PromptFragmentCustomizationSource[];
+
     /**
      * Gets the active customized prompt fragment for a given ID
      * @param fragmentId The prompt fragment ID