@theia/ai-core 1.73.0-next.7 → 1.73.0

package/lib/browser/frontend-prompt-customization-service.js

@@ -15,7 +15,7 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultPromptFragmentCustomizationService = exports.CustomizationSource = void 0;
+exports.DefaultPromptFragmentCustomizationService = exports.CustomizationSource = exports.CUSTOM_AGENT_WORKSPACE_DIRECTORIES = exports.CUSTOM_AGENT_DEFAULT_PROMPT_STEM = exports.CUSTOM_AGENT_FILE_NAME = exports.CUSTOM_AGENTS_DIRECTORY = void 0;
 exports.getCustomizationSourceString = getCustomizationSourceString;
 const tslib_1 = require("tslib");
 const core_1 = require("@theia/core");
@@ -23,6 +23,7 @@ const browser_1 = require("@theia/core/lib/browser");
 const inversify_1 = require("@theia/core/shared/inversify");
 const common_1 = require("../common");
 const configurable_in_memory_resources_1 = require("../common/configurable-in-memory-resources");
+const frontmatter_1 = require("../common/frontmatter");
 const buffer_1 = require("@theia/core/lib/common/buffer");
 const file_service_1 = require("@theia/filesystem/lib/browser/file-service");
 const ai_core_preferences_1 = require("../common/ai-core-preferences");
@@ -31,6 +32,51 @@ const js_yaml_1 = require("js-yaml");
 const prompttemplate_contribution_1 = require("./prompttemplate-contribution");
 const prompttemplate_parser_1 = require("./prompttemplate-parser");
 const browser_2 = require("@theia/workspace/lib/browser");
+/**
+ * Subdirectory (relative to a prompt-templates scope) holding one folder per custom agent.
+ */
+exports.CUSTOM_AGENTS_DIRECTORY = 'agents';
+/**
+ * Filename of the per-agent definition file (frontmatter + prompt body) inside `agents/<id>/`.
+ */
+exports.CUSTOM_AGENT_FILE_NAME = 'agent.md';
+/**
+ * Filename stem (without extension) reserved for the customization of a custom agent's
+ * default prompt. Lives at `<scope>/agents/<id>/prompt.prompttemplate` and maps to
+ * fragment id `<agent-name>_prompt`. Excluded from the variant loader so it doesn't double
+ * as an extra variant.
+ */
+exports.CUSTOM_AGENT_DEFAULT_PROMPT_STEM = 'prompt';
+/**
+ * Workspace-relative parent folders scanned for custom agents, independent of the configurable
+ * prompt-templates directories. Scanning both folders mirrors the skills convention introduced
+ * in #17553, but the duplicate-id precedence is intentionally inverted: here `.agents` is listed
+ * first, so it becomes the default location for newly created agents and wins over `.prompts`,
+ * whereas for skills `.prompts` wins over `.agents` (see `combineSkillDirectories` in
+ * `skill-service.ts`). `.prompts` is retained for backward compatibility with agents authored
+ * before the move to `.agents`.
+ */
+exports.CUSTOM_AGENT_WORKSPACE_DIRECTORIES = ['.agents', '.prompts'];
+var CustomAgentFrontmatter;
+(function (CustomAgentFrontmatter) {
+    function is(value) {
+        if (!value || typeof value !== 'object') {
+            return false;
+        }
+        const entry = value;
+        if (typeof entry.name !== 'string' || typeof entry.description !== 'string' || typeof entry.defaultLLM !== 'string') {
+            return false;
+        }
+        if ('showInChat' in entry && typeof entry.showInChat !== 'boolean') {
+            return false;
+        }
+        if ('id' in entry && typeof entry.id !== 'string') {
+            return false;
+        }
+        return true;
+    }
+    CustomAgentFrontmatter.is = is;
+})(CustomAgentFrontmatter || (CustomAgentFrontmatter = {}));
 /**
  * Default template entry for creating custom agents
  */
@@ -78,18 +124,31 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
         this.allCustomizations = new Map();
         /** Stores additional directory paths for loading template files. */
         this.additionalTemplateDirs = new Set();
+        /**
+         * Built-in parent directories scanned for custom agents (`.agents`, `.prompts`), independent of
+         * {@link additionalTemplateDirs}. Insertion order is preserved so the first entry (`.agents`)
+         * acts as the default location for newly created agents.
+         */
+        this.customAgentDirs = new Set();
         /** Contains file extensions that identify prompt template files. */
         this.templateExtensions = new Set([prompttemplate_contribution_1.PROMPT_TEMPLATE_EXTENSION]);
         /** Stores specific file paths, provided by the settings, that should be treated as templates. */
         this.workspaceTemplateFiles = new Set();
         /** Maps URI strings to WatchedFileInfo objects for individually watched template files. */
         this.watchedFiles = new Map();
+        /**
+         * For each known custom-agent prompt fragment id (i.e. `<name>_prompt`), the URI of the
+         * agent's folder (`<scope>/agents/<id>/`). Populated as agents are loaded and used to
+         * route customization writes/reads into the agent folder.
+         */
+        this.customAgentFolderByFragmentId = new Map();
         /** Collection of disposable resources for cleanup when the service updates or is disposed. */
         this.toDispose = new core_1.DisposableCollection();
         this.onDidChangePromptFragmentCustomizationEmitter = new core_1.Emitter();
         this.onDidChangePromptFragmentCustomization = this.onDidChangePromptFragmentCustomizationEmitter.event;
         this.onDidChangeCustomAgentsEmitter = new core_1.Emitter();
         this.onDidChangeCustomAgents = this.onDidChangeCustomAgentsEmitter.event;
+        this.warnedLegacyYamlUris = new Set();
     }
     init() {
         this.preferences.onPreferenceChanged(event => {
@@ -113,11 +172,28 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
         // First process the main templates directory (lowest priority)
         const templatesURI = await this.getTemplatesDirectoryURI();
         await this.processTemplateDirectory(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, templatesURI, 1, CustomizationSource.CUSTOMIZED); // Priority 1 for customized fragments
-        // Process additional template directories (medium priority)
-        for (const dirPath of this.additionalTemplateDirs) {
-            const dirURI = core_1.URI.fromFilePath(dirPath);
+        // Process additional template directories (medium priority). Skip any directory that
+        // resolves to the main templates directory — a user can set both prefs to the same
+        // path; re-processing the same dir overwrites the priority-1 entries with priority-2,
+        // which then hides them from `editBuiltIn`'s priority-1-only lookup.
+        const processedScopeKeys = new Set([templatesURI.toString()]);
+        for (const dirURI of this.getDedupedAdditionalScopes(templatesURI)) {
+            processedScopeKeys.add(dirURI.toString());
             await this.processTemplateDirectory(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, dirURI, 2, CustomizationSource.FOLDER); // Priority 2 for folder fragments
         }
+        // Process built-in custom-agent directories (`.agents`/`.prompts`) not already covered as
+        // template directories above: register the prompt fragments inside their `agents/<id>/`
+        // folders and watch them, so agents under these scopes get the same live refresh and
+        // prompt-fragment editing as those under template directories — without loading loose
+        // prompt templates from these built-in scopes themselves.
+        for (const dirPath of this.customAgentDirs) {
+            const scopeURI = core_1.URI.fromFilePath(dirPath);
+            if (processedScopeKeys.has(scopeURI.toString())) {
+                continue;
+            }
+            processedScopeKeys.add(scopeURI.toString());
+            await this.processCustomAgentScope(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, scopeURI, 2, CustomizationSource.FOLDER);
+        }
         // Process specific template files (highest priority)
         await this.processTemplateFiles(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, watchedFilesCopy);
         this.activeCustomizations = activeCustomizationsCopy;
@@ -388,10 +464,115 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
         // Process existing files if directory exists
         if (dirExists) {
             await this.processExistingTemplateDirectory(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, dirURI, priority, customizationSource);
+            await this.processCustomAgentFolders(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, dirURI, priority, customizationSource);
         }
         // Set up file watching for the directory (works for both existing and non-existing directories)
         this.setupDirectoryWatcher(dirURI, priority, customizationSource);
     }
+    /**
+     * Processes a built-in custom-agent scope (`.agents`/`.prompts`): registers the prompt fragments
+     * inside its `agents/<id>/` folders and watches the scope for changes. Unlike
+     * {@link processTemplateDirectory} it does not scan loose `*.prompttemplate` files in the scope
+     * root, so `.agents` does not become a general prompt-template directory.
+     * @param dirURI URI of the agent scope directory
+     * @param priority Priority level for customizations in this scope
+     * @param customizationSource Source type of the customization
+     */
+    async processCustomAgentScope(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, dirURI, priority, customizationSource) {
+        await this.processCustomAgentFolders(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, dirURI, priority, customizationSource);
+        // Watch for changes (works for both existing and non-existing directories), restricted to
+        // agent folders so newly created/edited agents under `.agents` are picked up live.
+        this.setupDirectoryWatcher(dirURI, priority, customizationSource, true);
+    }
+    /**
+     * Scan `<dirURI>/agents/<id>/*.prompttemplate` files and register each as a customized
+     * prompt fragment so they appear in the Prompt Fragments configuration view and so
+     * `editPromptFragmentCustomization` / `removePromptFragmentCustomization` can find their
+     * source URIs.
+     *
+     * The reserved filename `prompt.prompttemplate` maps to the agent's default-variant
+     * fragment id (`<agent-name>_prompt` read from the sibling `agent.md`'s frontmatter).
+     * Any other `.prompttemplate` file uses its filename stem as the fragment id (matching
+     * how variants are registered via {@link readCustomAgentPromptVariants}).
+     */
+    async processCustomAgentFolders(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, scopeDir, priority, customizationSource) {
+        const agentsDirURI = scopeDir.resolve(exports.CUSTOM_AGENTS_DIRECTORY);
+        let agentsStat;
+        try {
+            agentsStat = await this.fileService.resolve(agentsDirURI);
+        }
+        catch {
+            return;
+        }
+        if (!agentsStat.isDirectory || !agentsStat.children?.length) {
+            return;
+        }
+        for (const agentChild of agentsStat.children) {
+            if (!agentChild.isDirectory) {
+                continue;
+            }
+            const defaultFragmentId = await this.readCustomAgentDefaultFragmentId(agentChild.resource);
+            if (defaultFragmentId) {
+                this.customAgentFolderByFragmentId.set(defaultFragmentId, agentChild.resource);
+            }
+            const folderStat = await this.fileService.resolve(agentChild.resource).catch(() => undefined);
+            if (!folderStat?.children?.length) {
+                continue;
+            }
+            for (const file of folderStat.children) {
+                if (!file.isFile || !this.isPromptTemplateExtension(file.resource.path.ext)) {
+                    continue;
+                }
+                const stem = this.removePromptTemplateSuffix(file.resource.path.name);
+                const fragmentId = stem === exports.CUSTOM_AGENT_DEFAULT_PROMPT_STEM ? defaultFragmentId : stem;
+                if (!fragmentId) {
+                    continue;
+                }
+                trackedTemplateURIsCopy.add(file.resource.toString());
+                try {
+                    const fileContent = await this.fileService.read(file.resource);
+                    const parsed = this.parseTemplateWithMetadata(fileContent.value);
+                    this.addTemplate(activeCustomizationsCopy, fragmentId, parsed.template, file.resource.toString(), allCustomizationsCopy, priority, customizationSource, parsed.metadata);
+                }
+                catch (e) {
+                    this.logger.debug(`Failed to load custom-agent customization ${file.resource.toString()}: ${e?.message ?? e}`);
+                }
+            }
+        }
+    }
+    /**
+     * Return the parent URI when `resource` lives in `<scopeDirURI>/agents/<id>/`; otherwise
+     * undefined. Used to decide whether a newly-added file should be processed as a
+     * custom-agent prompt customization.
+     */
+    matchesCustomAgentFolder(resource, scopeDirURI) {
+        const parent = resource.parent;
+        const grandParent = parent.parent;
+        if (!grandParent) {
+            return undefined;
+        }
+        if (grandParent.path.base !== exports.CUSTOM_AGENTS_DIRECTORY) {
+            return undefined;
+        }
+        if (!grandParent.parent.isEqual(scopeDirURI)) {
+            return undefined;
+        }
+        return parent;
+    }
+    /**
+     * Read `<agentFolderURI>/agent.md`'s frontmatter and return the implied default
+     * fragment id (`<name>_prompt`). Returns undefined if the file is missing or invalid.
+     */
+    async readCustomAgentDefaultFragmentId(agentFolderURI) {
+        try {
+            const content = (await this.fileService.read(agentFolderURI.resolve(exports.CUSTOM_AGENT_FILE_NAME), { encoding: 'utf-8' })).value;
+            const { metadata } = (0, frontmatter_1.parseFrontmatter)(content, { isValid: CustomAgentFrontmatter.is });
+            return metadata ? `${metadata.name}_prompt` : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Processes an existing directory for template files
      * @param activeCustomizationsCopy Map to store active customizations
@@ -424,13 +605,27 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
         this.onDidChangePromptFragmentCustomizationEmitter.fire(Array.from(parsedPromptFragments));
         this.onDidChangeCustomAgentsEmitter.fire();
     }
+    /**
+     * Whether a changed resource path affects custom agents, i.e. it is (or is inside) an `agents/`
+     * directory, or a legacy `customAgents.yml`. Matches the `agents` directory itself (e.g. when the
+     * whole folder is deleted), not only files within it, so removing `agents/` triggers a reload.
+     * @param path The string form of the changed resource URI
+     */
+    isCustomAgentChange(path) {
+        return path.endsWith('customAgents.yml')
+            || path.includes(`/${exports.CUSTOM_AGENTS_DIRECTORY}/`)
+            || path.endsWith(`/${exports.CUSTOM_AGENTS_DIRECTORY}`);
+    }
     /**
      * Sets up file watching for a template directory (works for both existing and non-existing directories)
      * @param dirURI URI of the directory to watch
      * @param priority Priority level for customizations in this directory
      * @param customizationSource Source type of the customization
+     * @param agentsOnly When true, only `agents/<id>/` prompt files are registered on add; loose
+     * `*.prompttemplate` files in the scope root are ignored. Used for built-in agent scopes
+     * (`.agents`) that must not become general prompt-template directories.
      */
-    setupDirectoryWatcher(dirURI, priority, customizationSource) {
+    setupDirectoryWatcher(dirURI, priority, customizationSource, agentsOnly = false) {
         this.toDispose.push(this.fileService.watch(dirURI, { recursive: true, excludes: [] }));
         this.toDispose.push(this.fileService.onDidFilesChange(async (event) => {
             // Filter for changes within the watched directory
@@ -444,7 +639,7 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
                 await this.update();
                 return;
             }
-            if (event.changes.some(change => change.resource.toString().endsWith('customAgents.yml'))) {
+            if (event.changes.some(change => this.isCustomAgentChange(change.resource.toString()))) {
                 this.onDidChangeCustomAgentsEmitter.fire();
             }
             // Track changes for batched notification
@@ -465,23 +660,44 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
                 if (this.trackedTemplateURIs.has(uriString)) {
                     const fileContent = await this.fileService.read(updatedFile.resource);
                     const parsed = this.parseTemplateWithMetadata(fileContent.value);
-                    const fragmentId = this.removePromptTemplateSuffix(updatedFile.resource.path.name);
+                    // Prefer the already-tracked fragment id over the filename stem so that
+                    // `<scope>/agents/<id>/prompt.prompttemplate` keeps mapping to `<name>_prompt`
+                    // instead of becoming a fragment called `prompt`.
+                    const fragmentId = this.allCustomizations.get(uriString)?.id
+                        ?? this.removePromptTemplateSuffix(updatedFile.resource.path.name);
                     this.addTemplate(this.activeCustomizations, fragmentId, parsed.template, uriString, this.allCustomizations, priority, customizationSource, parsed.metadata);
                     changedFragmentIds.add(fragmentId);
                 }
             }
             // Handle new templates
             for (const addedFile of event.getAdded()) {
-                if (addedFile.resource.parent.toString() === dirURI.toString() &&
-                    this.isPromptTemplateExtension(addedFile.resource.path.ext)) {
-                    const uriString = addedFile.resource.toString();
-                    this.trackedTemplateURIs.add(uriString);
-                    const fileContent = await this.fileService.read(addedFile.resource);
-                    const parsed = this.parseTemplateWithMetadata(fileContent.value);
-                    const fragmentId = this.removePromptTemplateSuffix(addedFile.resource.path.name);
-                    this.addTemplate(this.activeCustomizations, fragmentId, parsed.template, uriString, this.allCustomizations, priority, customizationSource, parsed.metadata);
-                    changedFragmentIds.add(fragmentId);
+                if (!this.isPromptTemplateExtension(addedFile.resource.path.ext)) {
+                    continue;
+                }
+                const isScopeRoot = !agentsOnly && addedFile.resource.parent.toString() === dirURI.toString();
+                const agentFolderURI = this.matchesCustomAgentFolder(addedFile.resource, dirURI);
+                if (!isScopeRoot && !agentFolderURI) {
+                    continue;
+                }
+                const uriString = addedFile.resource.toString();
+                this.trackedTemplateURIs.add(uriString);
+                const fileContent = await this.fileService.read(addedFile.resource);
+                const parsed = this.parseTemplateWithMetadata(fileContent.value);
+                let fragmentId;
+                if (agentFolderURI) {
+                    const stem = this.removePromptTemplateSuffix(addedFile.resource.path.name);
+                    fragmentId = stem === exports.CUSTOM_AGENT_DEFAULT_PROMPT_STEM
+                        ? await this.readCustomAgentDefaultFragmentId(agentFolderURI)
+                        : stem;
+                }
+                else {
+                    fragmentId = this.removePromptTemplateSuffix(addedFile.resource.path.name);
+                }
+                if (!fragmentId) {
+                    continue;
                 }
+                this.addTemplate(this.activeCustomizations, fragmentId, parsed.template, uriString, this.allCustomizations, priority, customizationSource, parsed.metadata);
+                changedFragmentIds.add(fragmentId);
             }
             const changedFragmentIdsArray = Array.from(changedFragmentIds);
             if (changedFragmentIdsArray.length > 0) {
@@ -530,6 +746,12 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
                 this.additionalTemplateDirs.add(path);
             }
         }
+        if (properties.agentDirectoryPaths !== undefined) {
+            this.customAgentDirs.clear();
+            for (const path of properties.agentDirectoryPaths) {
+                this.customAgentDirs.add(path);
+            }
+        }
         if (properties.extensions !== undefined) {
             this.templateExtensions.clear();
             for (const ext of properties.extensions) {
@@ -559,12 +781,62 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
         const theiaConfigDir = await this.envVariablesServer.getConfigDirUri();
         return new core_1.URI(theiaConfigDir).resolve('prompt-templates');
     }
+    /**
+     * The additional (workspace) template directories as URIs, excluding any that resolves to the
+     * same location as `excluding` (typically the global templates directory). A user can point
+     * both the `promptTemplates` preference and a workspace template directory at the same path;
+     * processing that scope twice would hide priority-1 customizations behind priority-2 copies
+     * (see {@link update}) or list the same scope twice in the agent-location picker.
+     */
+    getDedupedAdditionalScopes(excluding) {
+        const result = [];
+        for (const dirPath of this.additionalTemplateDirs) {
+            const dirURI = core_1.URI.fromFilePath(dirPath);
+            if (!dirURI.isEqual(excluding)) {
+                result.push(dirURI);
+            }
+        }
+        return result;
+    }
+    /**
+     * The deduplicated parent directories scanned for custom agents, in precedence order:
+     * the built-in {@link customAgentDirs} (`.agents` then `.prompts`) first, so `.agents` is both
+     * the discovery winner and the default creation target; then any configured
+     * {@link additionalTemplateDirs} that may also hold agents; then the global templates directory.
+     * Independent of the prompt-templates preference, mirroring how skills resolve their folders.
+     */
+    async getCustomAgentScopes() {
+        const seen = new Set();
+        const scopes = [];
+        const add = (uri) => {
+            const key = uri.toString();
+            if (!seen.has(key)) {
+                seen.add(key);
+                scopes.push(uri);
+            }
+        };
+        for (const dirPath of this.customAgentDirs) {
+            add(core_1.URI.fromFilePath(dirPath));
+        }
+        for (const dirPath of this.additionalTemplateDirs) {
+            add(core_1.URI.fromFilePath(dirPath));
+        }
+        add(await this.getTemplatesDirectoryURI());
+        return scopes;
+    }
     /**
      * Gets the URI for a specific template file
      * @param fragmentId The fragment ID
      * @returns URI for the template file
      */
     async getTemplateURI(fragmentId) {
+        // Custom-agent default prompts live inside their own folder under the reserved filename
+        // `prompt.prompttemplate`. Variants and other fragments fall back to scope-root behavior
+        // (where filename = fragment id), matching how Theia tracks all other customizations.
+        const agentFolder = this.customAgentFolderByFragmentId.get(fragmentId);
+        if (agentFolder) {
+            return agentFolder.resolve(`${exports.CUSTOM_AGENT_DEFAULT_PROMPT_STEM}${prompttemplate_contribution_1.PROMPT_TEMPLATE_EXTENSION}`);
+        }
         return (await this.getTemplatesDirectoryURI()).resolve(`${fragmentId}${prompttemplate_contribution_1.PROMPT_TEMPLATE_EXTENSION}`);
     }
     /**
@@ -825,21 +1097,197 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
     }
     async getCustomAgents() {
         const agentsById = new Map();
-        // First, process additional (workspace) template directories to give them precedence
-        for (const dirPath of this.additionalTemplateDirs) {
-            const dirURI = core_1.URI.fromFilePath(dirPath);
-            await this.loadCustomAgentsFromDirectory(dirURI, agentsById);
+        // Process scopes in precedence order (`.agents`/`.prompts` first, global last). The map only
+        // keeps the first agent seen per id, so earlier scopes win on conflicts.
+        for (const scope of await this.getCustomAgentScopes()) {
+            await this.loadCustomAgentsFromAgentsDirectory(scope, agentsById);
+            await this.loadCustomAgentsFromDirectory(scope, agentsById);
         }
-        // Then process global templates directory (only adding agents that don't conflict)
-        const globalTemplatesDir = await this.getTemplatesDirectoryURI();
-        await this.loadCustomAgentsFromDirectory(globalTemplatesDir, agentsById);
-        // Return the merged list of agents
+        // Note: customAgentFolderByFragmentId is intentionally not cleared here. It grows
+        // monotonically — stale entries (renamed/removed agents) at worst point at a folder
+        // that no longer exists, which the file-create path mkdirps if needed. Clearing it
+        // up front would create a race where a concurrent `getTemplateURI` call sees an empty
+        // map and falls back to the scope root.
         return Array.from(agentsById.values());
     }
     /**
-     * Load custom agents from a specific directory
-     * @param directoryURI The URI of the directory to load from
-     * @param agentsById Map to store the loaded agents by ID
+     * Load custom agents from `<parentDirectory>/agents/<id>/agent.md`. Each immediate
+     * subdirectory under `agents/` defines one custom agent: the folder name is the
+     * agent id (single source of truth), the file's YAML frontmatter holds the metadata,
+     * and the body is the prompt text. Folders without a readable `agent.md` are skipped.
+     */
+    async loadCustomAgentsFromAgentsDirectory(parentDirectory, agentsById) {
+        const agentsDirURI = parentDirectory.resolve(exports.CUSTOM_AGENTS_DIRECTORY);
+        let directoryStat;
+        try {
+            directoryStat = await this.fileService.resolve(agentsDirURI);
+        }
+        catch {
+            return;
+        }
+        if (!directoryStat.isDirectory || !directoryStat.children?.length) {
+            return;
+        }
+        for (const child of directoryStat.children) {
+            if (!child.isDirectory) {
+                continue;
+            }
+            const agent = await this.readCustomAgentFile(child.resource);
+            if (!agent) {
+                continue;
+            }
+            if (!agentsById.has(agent.id)) {
+                agentsById.set(agent.id, agent);
+            }
+        }
+    }
+    async readCustomAgentFile(agentFolderURI) {
+        const id = agentFolderURI.path.base;
+        const fileURI = agentFolderURI.resolve(exports.CUSTOM_AGENT_FILE_NAME);
+        let content;
+        try {
+            content = (await this.fileService.read(fileURI, { encoding: 'utf-8' })).value;
+        }
+        catch {
+            return undefined;
+        }
+        const { metadata, body } = (0, frontmatter_1.parseFrontmatter)(content, { isValid: CustomAgentFrontmatter.is });
+        if (!metadata) {
+            this.logger.debug(`Invalid or missing frontmatter in ${fileURI.toString()}`);
+            return undefined;
+        }
+        if (metadata.id !== undefined && metadata.id !== id) {
+            this.logger.debug(`Frontmatter id '${metadata.id}' in ${fileURI.toString()} does not match folder name '${id}'. Skipping.`);
+            return undefined;
+        }
+        const promptVariants = await this.readCustomAgentPromptVariants(agentFolderURI);
+        const fragmentId = `${metadata.name}_prompt`;
+        this.customAgentFolderByFragmentId.set(fragmentId, agentFolderURI);
+        return {
+            id,
+            name: metadata.name,
+            description: metadata.description,
+            prompt: body,
+            defaultLLM: metadata.defaultLLM,
+            showInChat: metadata.showInChat,
+            ...(promptVariants.length > 0 ? { promptVariants } : {})
+        };
+    }
+    /**
+     * Remove `<scopeDir>/agents/<id>/` directories that contain no `agent.md`. They are usually
+     * the leftover side effect of a previous migration whose `agent.md` write failed after the
+     * parent directory had already been created. Removing them lets the next run re-attempt.
+     */
+    async cleanupEmptyAgentFolders(scopeDir) {
+        const agentsDirURI = scopeDir.resolve(exports.CUSTOM_AGENTS_DIRECTORY);
+        let stat;
+        try {
+            stat = await this.fileService.resolve(agentsDirURI);
+        }
+        catch {
+            return;
+        }
+        if (!stat.children?.length) {
+            return;
+        }
+        for (const child of stat.children) {
+            if (!child.isDirectory) {
+                continue;
+            }
+            const agentMdURI = child.resource.resolve(exports.CUSTOM_AGENT_FILE_NAME);
+            if (await this.fileService.exists(agentMdURI)) {
+                continue;
+            }
+            const childStat = await this.fileService.resolve(child.resource).catch(() => undefined);
+            if (childStat?.children?.length) {
+                continue;
+            }
+            try {
+                await this.fileService.delete(child.resource, { recursive: true });
+                this.logger.info(`Removed empty agent folder ${child.resource.toString()} left behind by a previous run.`);
+            }
+            catch (e) {
+                this.logger.warn(`Failed to remove empty agent folder ${child.resource.toString()}: ${e?.message ?? e}`);
+            }
+        }
+    }
+    /**
+     * List `.prompttemplate` files directly inside the given scope directory (one level only).
+     * Returns each file's URI along with its filename stem to enable cheap prefix matching
+     * during migration.
+     */
+    async listScopeRootPromptTemplates(scopeDir) {
+        let stat;
+        try {
+            stat = await this.fileService.resolve(scopeDir);
+        }
+        catch {
+            return [];
+        }
+        if (!stat.children?.length) {
+            return [];
+        }
+        const result = [];
+        for (const child of stat.children) {
+            if (!child.isFile) {
+                continue;
+            }
+            if (!this.isPromptTemplateExtension(child.resource.path.ext)) {
+                continue;
+            }
+            result.push({ uri: child.resource, stem: this.removePromptTemplateSuffix(child.resource.path.name) });
+        }
+        return result;
+    }
+    /**
+     * Scan an agent folder for sibling `.prompttemplate` files; each becomes a variant
+     * of the agent's prompt. Variant id = filename stem (e.g. `concise.prompttemplate`
+     * yields a variant with id `concise`). Files inside subdirectories are ignored.
+     *
+     * The reserved filename `prompt.prompttemplate` is excluded: it represents the
+     * default-variant customization (overrides `agent.md`'s body), not an extra variant,
+     * and is registered by the prompt-fragment customization scan instead.
+     */
+    async readCustomAgentPromptVariants(agentFolderURI) {
+        let folderStat;
+        try {
+            folderStat = await this.fileService.resolve(agentFolderURI);
+        }
+        catch {
+            return [];
+        }
+        if (!folderStat.children?.length) {
+            return [];
+        }
+        const variants = [];
+        for (const child of folderStat.children) {
+            if (!child.isFile) {
+                continue;
+            }
+            if (!this.isPromptTemplateExtension(child.resource.path.ext)) {
+                continue;
+            }
+            const variantId = this.removePromptTemplateSuffix(child.resource.path.name);
+            if (variantId === exports.CUSTOM_AGENT_DEFAULT_PROMPT_STEM) {
+                continue;
+            }
+            try {
+                const variantContent = (await this.fileService.read(child.resource, { encoding: 'utf-8' })).value;
+                const parsed = this.parseTemplateWithMetadata(variantContent);
+                variants.push({ id: variantId, template: parsed.template });
+            }
+            catch (e) {
+                this.logger.debug(`Failed to read prompt variant ${child.resource.toString()}: ${e?.message ?? e}`);
+            }
+        }
+        // Stable order to keep equality checks deterministic between loads.
+        variants.sort((a, b) => a.id.localeCompare(b.id));
+        return variants;
+    }
+    /**
+     * @deprecated Reads legacy `customAgents.yml` files. New agents should live under
+     * `<scope>/agents/<id>/agent.md`. Kept as a fallback until existing files have been
+     * auto-migrated; loader logs a one-time warning per scope when it finds one.
      */
     async loadCustomAgentsFromDirectory(directoryURI, agentsById) {
         const customAgentYamlUri = directoryURI.resolve('customAgents.yml');
@@ -847,11 +1295,12 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
         if (!yamlExists) {
             return;
         }
+        this.warnOnceLegacyYaml(customAgentYamlUri);
         try {
             const fileContent = await this.fileService.read(customAgentYamlUri, { encoding: 'utf-8' });
             const doc = (0, js_yaml_1.load)(fileContent.value);
             if (!Array.isArray(doc) || !doc.every(entry => common_1.CustomAgentDescription.is(entry))) {
-                console.debug(`Invalid customAgents.yml file content in ${directoryURI.toString()}`);
+                this.logger.debug(`Invalid customAgents.yml file content in ${directoryURI.toString()}`);
                 return;
             }
             const readAgents = doc;
@@ -863,35 +1312,195 @@ let DefaultPromptFragmentCustomizationService = class DefaultPromptFragmentCusto
             }
         }
         catch (e) {
-            console.debug(`Error loading customAgents.yml from ${directoryURI.toString()}: ${e.message}`, e);
+            this.logger.debug(`Error loading customAgents.yml from ${directoryURI.toString()}: ${e.message}`, e);
         }
     }
+    warnOnceLegacyYaml(uri) {
+        const key = uri.toString();
+        if (this.warnedLegacyYamlUris.has(key)) {
+            return;
+        }
+        this.warnedLegacyYamlUris.add(key);
+        this.logger.warn(`Loading custom agents from legacy '${key}'. ` +
+            `Files in this format are auto-migrated to the '${exports.CUSTOM_AGENTS_DIRECTORY}/' folder on startup. ` +
+            'If migration did not run, invoke the command \'AI: Re-run custom-agent migration\'.');
+    }
     /**
-     * Returns all locations of existing customAgents.yml files and potential locations where
-     * new customAgents.yml files could be created.
-     *
-     * @returns An array of objects containing the URI and whether the file exists
+     * Returns all locations of existing customAgents.yml files and `agents/` directories,
+     * plus the canonical locations where new agents would be created (one per scope). Scopes are
+     * returned in precedence order, so the first `agents-dir` entry is the default creation target.
      */
     async getCustomAgentsLocations() {
         const locations = [];
-        // Check global templates directory
-        const globalTemplatesDir = await this.getTemplatesDirectoryURI();
-        const globalAgentsUri = globalTemplatesDir.resolve('customAgents.yml');
-        const globalExists = await this.fileService.exists(globalAgentsUri);
-        locations.push({ uri: globalAgentsUri, exists: globalExists });
-        // Check additional (workspace) template directories
-        for (const dirPath of this.additionalTemplateDirs) {
-            const dirURI = core_1.URI.fromFilePath(dirPath);
-            const agentsUri = dirURI.resolve('customAgents.yml');
-            const exists = await this.fileService.exists(agentsUri);
-            locations.push({ uri: agentsUri, exists: exists });
+        for (const parentDir of await this.getCustomAgentScopes()) {
+            const agentsDirURI = parentDir.resolve(exports.CUSTOM_AGENTS_DIRECTORY);
+            locations.push({ uri: agentsDirURI, exists: await this.fileService.exists(agentsDirURI), kind: 'agents-dir' });
+            const yamlURI = parentDir.resolve('customAgents.yml');
+            locations.push({ uri: yamlURI, exists: await this.fileService.exists(yamlURI), kind: 'legacy-yaml' });
         }
         return locations;
     }
     /**
-     * Opens an existing customAgents.yml file at the given URI, or creates a new one if it doesn't exist.
+     * Creates `<parentDirectory>/agents/<id>/agent.md` from a `CustomAgentDescription` and opens it.
+     * The agent id determines the folder name; the prompt body is written verbatim under the YAML frontmatter.
+     */
+    async createCustomAgentFile(parentDirectory, agent) {
+        const fileURI = parentDirectory.resolve(exports.CUSTOM_AGENTS_DIRECTORY).resolve(agent.id).resolve(exports.CUSTOM_AGENT_FILE_NAME);
+        const content = serializeCustomAgentFile(agent);
+        if (!(await this.fileService.exists(fileURI))) {
+            await this.fileService.createFile(fileURI, buffer_1.BinaryBuffer.fromString(content));
+        }
+        else {
+            await this.fileService.writeFile(fileURI, buffer_1.BinaryBuffer.fromString(content));
+        }
+        const openHandler = await this.openerService.getOpener(fileURI);
+        openHandler.open(fileURI);
+        return fileURI;
+    }
+    /**
+     * Auto-migrate every legacy `customAgents.yml` reachable from the configured scopes to the new
+     * `agents/<id>/agent.md` layout. The original content is never deleted:
+     * - on full success the YAML is renamed to `customAgents.yml.bak`, replacing any previous backup;
+     * - on partial failure the YAML is renamed to `customAgents.yml.bak` only if no backup exists yet;
+     *   if one already exists the YAML is left in place, so the loader keeps serving it and the next
+     *   startup retries the migration.
      *
-     * @param uri The URI of the customAgents.yml file to open or create
+     * Idempotent: rerunning never overwrites an already-migrated agent file.
+     */
+    async migrateCustomAgentsYaml() {
+        // Coalesce concurrent calls. refreshCustomAgents() can re-fire during startup when
+        // additionalTemplateDirs is populated asynchronously; without this guard each call
+        // launches a parallel migration that races on the same `customAgents.yml` and on
+        // sibling `*_prompt*.prompttemplate` files.
+        if (this.migrationInFlight) {
+            return this.migrationInFlight;
+        }
+        this.migrationInFlight = this.doMigrateCustomAgentsYaml().finally(() => {
+            this.migrationInFlight = undefined;
+        });
+        return this.migrationInFlight;
+    }
+    async doMigrateCustomAgentsYaml() {
+        const scopes = await this.getCustomAgentScopes();
+        const reports = [];
+        for (const scope of scopes) {
+            const report = await this.migrateSingleScope(scope);
+            if (report) {
+                reports.push(report);
+            }
+        }
+        if (reports.some(r => r.migrated > 0)) {
+            this.onDidChangeCustomAgentsEmitter.fire();
+        }
+        return reports;
+    }
+    async migrateSingleScope(scopeDir) {
+        const yamlURI = scopeDir.resolve('customAgents.yml');
+        if (!(await this.fileService.exists(yamlURI))) {
+            return undefined;
+        }
+        this.logger.info(`Migrating custom agents from ${yamlURI.toString()}`);
+        let entries;
+        try {
+            const fileContent = await this.fileService.read(yamlURI, { encoding: 'utf-8' });
+            const doc = (0, js_yaml_1.load)(fileContent.value);
+            if (!Array.isArray(doc) || !doc.every(common_1.CustomAgentDescription.is)) {
+                this.logger.warn(`Skipping migration of ${yamlURI.toString()}: file content is not a valid CustomAgentDescription[]`);
+                return { scope: scopeDir, yamlURI, migrated: 0, alreadyPresent: 0, failed: 0, yamlBackedUp: false, promptOverridesMigrated: 0 };
+            }
+            entries = doc;
+        }
+        catch (e) {
+            this.logger.warn(`Skipping migration of ${yamlURI.toString()}: ${e.message}`);
+            return { scope: scopeDir, yamlURI, migrated: 0, alreadyPresent: 0, failed: 0, yamlBackedUp: false, promptOverridesMigrated: 0 };
+        }
+        let migrated = 0;
+        let alreadyPresent = 0;
+        let failed = 0;
+        let promptOverridesMigrated = 0;
+        // A previous failed migration may have created `agents/<id>/` directories without an
+        // `agent.md` inside. Remove those empty placeholders so this run can recreate them cleanly.
+        await this.cleanupEmptyAgentFolders(scopeDir);
+        // Snapshot scope-root template files once so we can match per agent without re-listing.
+        const scopeRootTemplateFiles = await this.listScopeRootPromptTemplates(scopeDir);
+        // Prompt-fragment files are matched by agent *name* (the fragment id is `<name>_prompt`)
+        // while folders are keyed by the unique *id*. When two entries share a name, only the first
+        // can own the name-based files, so track seen names and skip the move for the duplicates.
+        const seenNames = new Set();
+        for (const entry of entries) {
+            const agentFolderURI = scopeDir.resolve(exports.CUSTOM_AGENTS_DIRECTORY).resolve(entry.id);
+            const targetURI = agentFolderURI.resolve(exports.CUSTOM_AGENT_FILE_NAME);
+            if (await this.fileService.exists(targetURI)) {
+                alreadyPresent++;
+            }
+            else {
+                try {
+                    await this.fileService.createFile(targetURI, buffer_1.BinaryBuffer.fromString(serializeCustomAgentFile(entry)), { overwrite: true });
+                    migrated++;
+                }
+                catch (e) {
+                    this.logger.warn(`Failed to migrate agent '${entry.id}' from ${yamlURI.toString()}: ${e?.message ?? e}`, e);
+                    failed++;
+                    continue;
+                }
+            }
+            if (seenNames.has(entry.name)) {
+                this.logger.warn(`Multiple custom agents in ${yamlURI.toString()} share the name '${entry.name}'; ` +
+                    'prompt fragment files were migrated to the first matching agent only.');
+                continue;
+            }
+            seenNames.add(entry.name);
+            // Move any scope-root .prompttemplate files that look like they belong to this agent
+            // (filename stem starts with `<name>_prompt`, followed by EOF or a separator).
+            // They become variants under `<scope>/agents/<id>/`.
+            for (const file of scopeRootTemplateFiles) {
+                if (!matchesAgentPromptPrefix(file.stem, entry.name)) {
+                    continue;
+                }
+                const destURI = agentFolderURI.resolve(file.uri.path.base);
+                if (await this.fileService.exists(destURI)) {
+                    continue;
+                }
+                try {
+                    await this.fileService.move(file.uri, destURI);
+                    promptOverridesMigrated++;
+                }
+                catch (e) {
+                    this.logger.warn(`Failed to move prompt fragment ${file.uri.toString()} into ${destURI.toString()}: ${e?.message ?? e}`);
+                }
+            }
+        }
+        let yamlBackedUp = false;
+        const backupURI = scopeDir.resolve('customAgents.yml.bak');
+        if (failed === 0) {
+            try {
+                await this.fileService.move(yamlURI, backupURI, { overwrite: true });
+                yamlBackedUp = true;
+            }
+            catch (e) {
+                this.logger.warn(`Migrated ${migrated} agents but failed to back up ${yamlURI.toString()}: ${e.message}`);
+            }
+        }
+        else {
+            try {
+                if (!(await this.fileService.exists(backupURI))) {
+                    await this.fileService.move(yamlURI, backupURI);
+                    yamlBackedUp = true;
+                }
+            }
+            catch (e) {
+                this.logger.warn(`Failed to back up ${yamlURI.toString()} to ${backupURI.toString()}: ${e.message}`);
+            }
+        }
+        this.logger.info(`Migration done for ${yamlURI.toString()}: ` +
+            `migrated=${migrated}, alreadyPresent=${alreadyPresent}, failed=${failed}, ` +
+            `yamlBackedUp=${yamlBackedUp}, promptOverridesMigrated=${promptOverridesMigrated}`);
+        return { scope: scopeDir, yamlURI, migrated, alreadyPresent, failed, yamlBackedUp, promptOverridesMigrated };
+    }
+    /**
+     * @deprecated Use {@link createCustomAgentFile} to author agents in the new
+     * `<scope>/agents/<id>/agent.md` layout. Retained so existing UI affordances keep
+     * working until they are migrated.
      */
     async openCustomAgentYaml(uri) {
         const content = (0, js_yaml_1.dump)([newCustomAgentEntry]);
@@ -931,6 +1540,11 @@ tslib_1.__decorate([
     (0, inversify_1.inject)(browser_2.WorkspaceService),
     tslib_1.__metadata("design:type", browser_2.WorkspaceService)
 ], DefaultPromptFragmentCustomizationService.prototype, "workspaceService", void 0);
+tslib_1.__decorate([
+    (0, inversify_1.inject)(core_1.ILogger),
+    (0, inversify_1.named)('ai-core:DefaultPromptFragmentCustomizationService'),
+    tslib_1.__metadata("design:type", Object)
+], DefaultPromptFragmentCustomizationService.prototype, "logger", void 0);
 tslib_1.__decorate([
     (0, inversify_1.postConstruct)(),
     tslib_1.__metadata("design:type", Function),
@@ -940,4 +1554,30 @@ tslib_1.__decorate([
 exports.DefaultPromptFragmentCustomizationService = DefaultPromptFragmentCustomizationService = tslib_1.__decorate([
     (0, inversify_1.injectable)()
 ], DefaultPromptFragmentCustomizationService);
+/**
+ * Returns true when a filename stem looks like a prompt fragment owned by the named agent —
+ * i.e. it begins with `<name>_prompt` followed by end-of-string or a separator
+ * (`-`, `_`, ` `, `.`). Used to scoop variant files like `Foo_prompt_old.prompttemplate` into
+ * the agent's folder during migration without grabbing unrelated fragments such as
+ * `FooBar_prompt.prompttemplate` for a different agent.
+ */
+function matchesAgentPromptPrefix(stem, agentName) {
+    const prefix = `${agentName}_prompt`;
+    if (!stem.startsWith(prefix)) {
+        return false;
+    }
+    const next = stem.charAt(prefix.length);
+    return next === '' || next === '-' || next === '_' || next === ' ' || next === '.';
+}
+function serializeCustomAgentFile(agent) {
+    const metadata = {
+        name: agent.name,
+        description: agent.description,
+        defaultLLM: agent.defaultLLM,
+    };
+    if (agent.showInChat !== undefined) {
+        metadata.showInChat = agent.showInChat;
+    }
+    return (0, frontmatter_1.serializeFrontmatter)(metadata, agent.prompt);
+}
 //# sourceMappingURL=frontend-prompt-customization-service.js.map