@theia/ai-core 1.61.0 → 1.62.0

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

@@ -17,7 +17,7 @@
 import { DisposableCollection, URI, Event, Emitter } from '@theia/core';
 import { OpenerService } from '@theia/core/lib/browser';
 import { inject, injectable, postConstruct } from '@theia/core/shared/inversify';
-import { PromptCustomizationService, CustomAgentDescription } from '../common';
+import { PromptFragmentCustomizationService, CustomAgentDescription, CustomizedPromptFragment } from '../common';
 import { BinaryBuffer } from '@theia/core/lib/common/buffer';
 import { FileService } from '@theia/filesystem/lib/browser/file-service';
 import { FileChangesEvent } from '@theia/filesystem/lib/common/files';
@@ -26,49 +26,97 @@ import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
 import { load, dump } from 'js-yaml';
 import { PROMPT_TEMPLATE_EXTENSION } from './prompttemplate-contribution';
 
-const templateEntry = {
+/**
+ * Default template entry for creating custom agents
+ */
+const newCustomAgentEntry = {
     id: 'my_agent',
     name: 'My Agent',
     description: 'This is an example agent. Please adapt the properties to fit your needs.',
-    prompt: 'You are an example agent. Be nice and helpful to the user.',
+    prompt: `{{!-- Note: The context section below will resolve all context elements (e.g. files) to their full content
+in the system prompt. Context elements can be added by the user in the default chat view (e.g. via DnD or the "+" button).
+If you want a more fine-grained, on demand resolvement of context elements, you can also resolve files to their paths only
+and equip the agent with functions so that the LLM can retrieve files on demand. See the Coder Agent prompt for an example.--}}
+
+# Role
+You are an example agent. Be nice and helpful to the user.
+
+## Current Context
+Some files and other pieces of data may have been added by the user to the context of the chat. If any have, the details can be found below.
+{{contextDetails}}`,
     defaultLLM: 'openai/gpt-4o'
 };
 
-// Template source priorities (higher number = higher priority)
-// Higher priority will "override" lower priority templates
-const enum TemplatePriority {
-    GLOBAL_TEMPLATE_DIR = 1,
-    ADDITIONAL_TEMPLATE_DIR = 2,
-    TEMPLATE_FILE = 3
+export enum CustomizationSource {
+    CUSTOMIZED = 1,
+    FOLDER = 2,
+    FILE = 3,
+}
+
+export function getCustomizationSourceString(origin: CustomizationSource): string {
+    switch (origin) {
+        case CustomizationSource.FILE:
+            return 'Workspace Template Files';
+        case CustomizationSource.FOLDER:
+            return 'Workspace Template Directories';
+        default:
+            return 'Prompt Templates Folder';
+    }
 }
 
 /**
- * Interface defining properties that can be updated in the service
+ * Interface defining properties that can be updated in the customization service
  */
-export interface PromptCustomizationProperties {
+export interface PromptFragmentCustomizationProperties {
     /** Array of directory paths to load templates from */
     directoryPaths?: string[];
+
     /** Array of file paths to treat as templates */
     filePaths?: string[];
+
     /** Array of file extensions to consider as template files */
     extensions?: string[];
 }
 
-interface TemplateEntry {
-    content: string;
-    priority: number;
+/**
+ * Internal representation of a fragment entry in the customization service
+ */
+interface PromptFragmentCustomization {
+    /** The template content */
+    template: string;
+
+    /** Source URI where this template is stored */
     sourceUri: string;
+
+    /** Source type of the customization */
+    origin: CustomizationSource;
+
+    /** Priority level (higher values override lower ones) */
+    priority: number;
+
+    /** Fragment ID */
     id: string;
+
+    /** Unique customization ID */
+    customizationId: string;
 }
 
+/**
+ * Information about a template file being watched for changes
+ */
 interface WatchedFileInfo {
+    /** The URI of the watched file */
     uri: URI;
-    templateId: string;
+
+    /** The fragment ID associated with this file */
+    fragmentId: string;
+
+    /** The customization ID for this file */
+    customizationId: string;
 }
 
 @injectable()
-export class FrontendPromptCustomizationServiceImpl implements PromptCustomizationService {
-
+export class DefaultPromptFragmentCustomizationService implements PromptFragmentCustomizationService {
     @inject(EnvVariablesServer)
     protected readonly envVariablesServer: EnvVariablesServer;
 
@@ -83,32 +131,36 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
 
     /** Stores URI strings of template files from directories currently being monitored for changes. */
     protected trackedTemplateURIs = new Set<string>();
-    /** Contains the currently active templates, mapped by template ID. */
-    protected effectiveTemplates = new Map<string, TemplateEntry>();
-    /** Tracks all loaded templates, including overridden ones, mapped by source URI. */
-    protected allLoadedTemplates = new Map<string, TemplateEntry>();
+
+    /** Contains the currently active customization, mapped by prompt fragment ID. */
+    protected activeCustomizations = new Map<string, PromptFragmentCustomization>();
+
+    /** Tracks all loaded customizations, including overridden ones, mapped by source URI. */
+    protected allCustomizations = new Map<string, PromptFragmentCustomization>();
+
     /** Stores additional directory paths for loading template files. */
     protected additionalTemplateDirs = new Set<string>();
+
     /** Contains file extensions that identify prompt template files. */
     protected templateExtensions = new Set<string>([PROMPT_TEMPLATE_EXTENSION]);
-    /** Stores specific file paths that should be treated as templates. */
-    protected templateFiles = new Set<string>();
+
+    /** Stores specific file paths, provided by the settings, that should be treated as templates. */
+    protected workspaceTemplateFiles = new Set<string>();
+
     /** Maps URI strings to WatchedFileInfo objects for individually watched template files. */
     protected watchedFiles = new Map<string, WatchedFileInfo>();
+
     /** Collection of disposable resources for cleanup when the service updates or is disposed. */
     protected toDispose = new DisposableCollection();
 
-    private readonly onDidChangePromptEmitter = new Emitter<string>();
-    readonly onDidChangePrompt: Event<string> = this.onDidChangePromptEmitter.event;
+    protected readonly onDidChangePromptFragmentCustomizationEmitter = new Emitter<string[]>();
+    readonly onDidChangePromptFragmentCustomization: Event<string[]> = this.onDidChangePromptFragmentCustomizationEmitter.event;
 
-    private readonly onDidChangeCustomAgentsEmitter = new Emitter<void>();
-    readonly onDidChangeCustomAgents = this.onDidChangeCustomAgentsEmitter.event;
+    protected readonly onDidChangeCustomAgentsEmitter = new Emitter<void>();
+    readonly onDidChangeCustomAgents: Event<void> = this.onDidChangeCustomAgentsEmitter.event;
 
     @postConstruct()
     protected init(): void {
-        // Ensure PROMPT_TEMPLATE_EXTENSION is always included in templateExtensions as a default
-        this.templateExtensions.add(PROMPT_TEMPLATE_EXTENSION);
-
         this.preferences.onPreferenceChanged(event => {
             if (event.preferenceName === PREFERENCE_NAME_PROMPT_TEMPLATES) {
                 this.update();
@@ -117,147 +169,210 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
         this.update();
     }
 
+    /**
+     * Updates the service by reloading all template files and watching for changes
+     */
     protected async update(): Promise<void> {
         this.toDispose.dispose();
         // we need to assign local variables, so that updates running in parallel don't interfere with each other
-        const templatesMap = new Map<string, TemplateEntry>();
-        const trackedURIs = new Set<string>();
-        const loadedTemplates = new Map<string, TemplateEntry>();
-        const watchedFilesMap = new Map<string, WatchedFileInfo>();
+        const activeCustomizationsCopy = new Map<string, PromptFragmentCustomization>();
+        const trackedTemplateURIsCopy = new Set<string>();
+        const allCustomizationsCopy = new Map<string, PromptFragmentCustomization>();
+        const watchedFilesCopy = new Map<string, WatchedFileInfo>();
 
         // Process in order of priority (lowest to highest)
-        // First process the main template directory (lowest priority)
-        const templateURI = await this.getTemplatesDirectoryURI();
-        await this.processTemplateDirectory(templatesMap, trackedURIs, loadedTemplates, templateURI, TemplatePriority.GLOBAL_TEMPLATE_DIR);
+        // 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 = URI.fromFilePath(dirPath);
-            await this.processTemplateDirectory(templatesMap, trackedURIs, loadedTemplates, dirURI, TemplatePriority.ADDITIONAL_TEMPLATE_DIR);
+            await this.processTemplateDirectory(
+                activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, dirURI, 2, CustomizationSource.FOLDER); // Priority 2 for folder fragments
         }
 
         // Process specific template files (highest priority)
-        await this.processTemplateFiles(templatesMap, trackedURIs, loadedTemplates, watchedFilesMap);
+        await this.processTemplateFiles(activeCustomizationsCopy, trackedTemplateURIsCopy, allCustomizationsCopy, watchedFilesCopy);
 
-        this.effectiveTemplates = templatesMap;
-        this.trackedTemplateURIs = trackedURIs;
-        this.allLoadedTemplates = loadedTemplates;
-        this.watchedFiles = watchedFilesMap;
+        this.activeCustomizations = activeCustomizationsCopy;
+        this.trackedTemplateURIs = trackedTemplateURIsCopy;
+        this.allCustomizations = allCustomizationsCopy;
+        this.watchedFiles = watchedFilesCopy;
 
         this.onDidChangeCustomAgentsEmitter.fire();
     }
 
     /**
-     * Adds a template to the templates map, handling conflicts based on priority
-     * @param templatesMap The map to add the template to
-     * @param id The template ID
-     * @param content The template content
-     * @param priority The template priority
+     * Adds a template to the customizations map, handling conflicts based on priority
+     * @param activeCustomizationsCopy The map to add the customization to
+     * @param id The fragment ID
+     * @param template The template content
      * @param sourceUri The URI of the source file (used to distinguish updates from conflicts)
-     * @param loadedTemplates The map to track all loaded templates
+     * @param allCustomizationsCopy The map to track all loaded customizations
+     * @param priority The customization priority
+     * @param origin The source type of the customization
      */
     protected addTemplate(
-        templatesMap: Map<string, TemplateEntry>,
+        activeCustomizationsCopy: Map<string, PromptFragmentCustomization>,
         id: string,
-        content: string,
-        priority: number,
+        template: string,
         sourceUri: string,
-        loadedTemplates: Map<string, TemplateEntry>
+        allCustomizationsCopy: Map<string, PromptFragmentCustomization>,
+        priority: number,
+        origin: CustomizationSource
     ): void {
-        // Always add to loadedTemplates to keep track of all templates including overridden ones
+        // Generate a unique customization ID based on source URI and priority
+        const customizationId = this.generateCustomizationId(id, sourceUri);
+
+        // Always add to allCustomizationsCopy to keep track of all customizations including overridden ones
         if (sourceUri) {
-            loadedTemplates.set(sourceUri, { id, content, priority, sourceUri });
+            allCustomizationsCopy.set(sourceUri, { id, template, sourceUri, priority, customizationId, origin });
         }
 
-        const existingEntry = templatesMap.get(id);
+        const existingEntry = activeCustomizationsCopy.get(id);
 
         if (existingEntry) {
             // If this is an update to the same file (same source URI)
             if (sourceUri && existingEntry.sourceUri === sourceUri) {
                 // Update the content while keeping the same priority and source
-                templatesMap.set(id, { id, content, priority, sourceUri });
+                activeCustomizationsCopy.set(id, { id, template, sourceUri, priority, customizationId, origin });
                 return;
             }
 
-            // If the new template has higher priority, replace the existing one
+            // If the new customization has higher priority, replace the existing one
             if (priority > existingEntry.priority) {
-                templatesMap.set(id, { id, content, priority, sourceUri });
+                activeCustomizationsCopy.set(id, { id, template, sourceUri, priority, customizationId, origin });
                 return;
             } else if (priority === existingEntry.priority) {
-                // There is a conflict with the same priority, we ignore the new template
+                // There is a conflict with the same priority, we ignore the new customization
                 const conflictSourceUri = existingEntry.sourceUri ? ` (Existing source: ${existingEntry.sourceUri}, New source: ${sourceUri})` : '';
-                console.warn(`Template conflict detected for ID '${id}' with equal priority.${conflictSourceUri}`);
+                console.warn(`Fragment conflict detected for ID '${id}' with equal priority.${conflictSourceUri}`);
             }
             return;
         }
 
-        // No conflict at all, add the template
-        templatesMap.set(id, { id, content, priority, sourceUri });
+        // No conflict at all, add the customization
+        activeCustomizationsCopy.set(id, { id, template, sourceUri, priority, customizationId, origin });
     }
 
     /**
-     * Removes a template from the templates map based on the source URI and fires change event.
-     * Also checks for any lower-priority templates with the same ID that might need to be loaded.
+     * Generates a unique customization ID based on the fragment ID, source URI, and priority
+     * @param id The fragment ID
+     * @param sourceUri The source URI of the template
+     * @returns A unique customization ID
+     */
+    protected generateCustomizationId(id: string, sourceUri: string): string {
+        // Create a customization ID that contains information about the source and priority
+        // This ensures uniqueness across different customization sources
+        const sourceHash = this.hashString(sourceUri);
+        return `${id}_${sourceHash}`;
+    }
+
+    /**
+     * Simple hash function to generate a short identifier from a string
+     * @param str The string to hash
+     * @returns A string hash
+     */
+    protected hashString(str: string): string {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return Math.abs(hash).toString(36).substring(0, 8);
+    }
+
+    /**
+     * Removes a customization from customizations maps based on the source URI.
+     * Also checks for any lower-priority customizations with the same ID that might need to be loaded.
      * @param sourceUri The URI of the source file being removed
-     * @param loadedTemplates The map of all loaded templates
+     * @param allCustomizationsCopy The map of all loaded customizations
+     * @param activeCustomizationsCopy The map of active customizations
+     * @param trackedTemplateURIsCopy Optional set of tracked URIs to update
+     * @returns The fragment ID that was removed, or undefined if no customization was found
      */
-    protected removeTemplateBySourceUri(
+    protected removeCustomizationFromMaps(
         sourceUri: string,
-        loadedTemplates: Map<string, TemplateEntry>
-    ): void {
-        // Get the template entry from loadedTemplates
-        const removedTemplate = loadedTemplates.get(sourceUri);
-        if (!removedTemplate) {
-            return;
+        allCustomizationsCopy: Map<string, PromptFragmentCustomization>,
+        activeCustomizationsCopy: Map<string, PromptFragmentCustomization>,
+        trackedTemplateURIsCopy: Set<string>
+    ): string | undefined {
+        // Get the customization entry from allCustomizationsCopy
+        const removedCustomization = allCustomizationsCopy.get(sourceUri);
+        if (!removedCustomization) {
+            return undefined;
         }
-        const templateId = removedTemplate.id;
-        loadedTemplates.delete(sourceUri);
-
-        // If the template is in the active templates map, we check if there is another template previously conflicting with it
-        const activeTemplate = this.effectiveTemplates.get(templateId);
-        if (activeTemplate && activeTemplate.sourceUri === sourceUri) {
-            this.effectiveTemplates.delete(templateId);
-            // Find any lower-priority templates with the same ID that were previously ignored
-            const lowerPriorityTemplates = Array.from(loadedTemplates.values())
-                .filter(t => t.id === templateId)
+        const fragmentId = removedCustomization.id;
+        allCustomizationsCopy.delete(sourceUri);
+        trackedTemplateURIsCopy.delete(sourceUri);
+
+        // If the customization is in the active customizations map, we check if there is another customization previously conflicting with it
+        const activeCustomization = activeCustomizationsCopy.get(fragmentId);
+        if (activeCustomization && activeCustomization.sourceUri === sourceUri) {
+            activeCustomizationsCopy.delete(fragmentId);
+            // Find any lower-priority customizations with the same ID that were previously ignored
+            const lowerPriorityCustomizations = Array.from(allCustomizationsCopy.values())
+                .filter(t => t.id === fragmentId)
                 .sort((a, b) => b.priority - a.priority); // Sort by priority (highest first)
 
-            // If there are any lower-priority templates, add the highest priority one
-            if (lowerPriorityTemplates.length > 0) {
-                const highestRemainingTemplate = lowerPriorityTemplates[0];
-                this.effectiveTemplates.set(templateId, highestRemainingTemplate);
+            // If there are any lower-priority customizations, add the highest priority one
+            if (lowerPriorityCustomizations.length > 0) {
+                const highestRemainingCustomization = lowerPriorityCustomizations[0];
+                activeCustomizationsCopy.set(fragmentId, highestRemainingCustomization);
             }
-            this.onDidChangePromptEmitter.fire(templateId);
+
         }
+
+        return fragmentId;
     }
 
     /**
      * Process the template files specified by path, watching for changes
-     * and loading their content into the templates map
+     * and loading their content into the customizations map
+     * @param activeCustomizationsCopy Map to store active customizations
+     * @param trackedTemplateURIsCopy Set to track URIs being monitored
+     * @param allCustomizationsCopy Map to store all loaded customizations
+     * @param watchedFilesCopy Map to store file watch information
      */
     protected async processTemplateFiles(
-        templatesMap: Map<string, TemplateEntry>,
-        trackedURIs: Set<string>,
-        loadedTemplates: Map<string, TemplateEntry>,
-        watchedFilesMap: Map<string, WatchedFileInfo>
+        activeCustomizationsCopy: Map<string, PromptFragmentCustomization>,
+        trackedTemplateURIsCopy: Set<string>,
+        allCustomizationsCopy: Map<string, PromptFragmentCustomization>,
+        watchedFilesCopy: Map<string, WatchedFileInfo>
     ): Promise<void> {
+        const priority = 3; // Highest priority for specific files
 
-        for (const filePath of this.templateFiles) {
+        const parsedPromptFragments = new Set<string>();
+
+        for (const filePath of this.workspaceTemplateFiles) {
             const fileURI = URI.fromFilePath(filePath);
-            const templateId = this.getTemplateIdFromFilePath(filePath);
+            const fragmentId = this.getFragmentIdFromFilePath(filePath);
             const uriString = fileURI.toString();
+            const customizationId = this.generateCustomizationId(fragmentId, uriString);
 
-            watchedFilesMap.set(uriString, { uri: fileURI, templateId });
+            watchedFilesCopy.set(uriString, { uri: fileURI, fragmentId, customizationId });
             this.toDispose.push(this.fileService.watch(fileURI, { recursive: false, excludes: [] }));
 
             if (await this.fileService.exists(fileURI)) {
-                trackedURIs.add(uriString);
+                trackedTemplateURIsCopy.add(uriString);
                 const fileContent = await this.fileService.read(fileURI);
-                this.addTemplate(templatesMap, templateId, fileContent.value, TemplatePriority.TEMPLATE_FILE, uriString, loadedTemplates);
+                this.addTemplate(activeCustomizationsCopy, fragmentId, fileContent.value, uriString, allCustomizationsCopy, priority, CustomizationSource.FILE);
+                parsedPromptFragments.add(fragmentId);
             }
         }
 
+        this.onDidChangePromptFragmentCustomizationEmitter.fire(Array.from(parsedPromptFragments));
+
         this.toDispose.push(this.fileService.onDidFilesChange(async (event: FileChangesEvent) => {
+            // Only watch for changes that are in the watchedFiles map
+            if (!event.changes.some(change => this.watchedFiles.get(change.resource.toString()))) {
+                return;
+            }
+            // Track changes for batched notification
+            const changedFragmentIds = new Set<string>();
 
             // Handle deleted files
             for (const deletedFile of event.getDeleted()) {
@@ -265,9 +380,10 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
                 const fileInfo = this.watchedFiles.get(fileUriString);
 
                 if (fileInfo) {
-                    this.removeTemplateBySourceUri(fileUriString, loadedTemplates);
-                    this.trackedTemplateURIs.delete(fileUriString);
-                    this.onDidChangePromptEmitter.fire(fileInfo.templateId);
+                    const removedFragmentId = this.removeCustomizationFromMaps(fileUriString, allCustomizationsCopy, activeCustomizationsCopy, trackedTemplateURIsCopy);
+                    if (removedFragmentId) {
+                        changedFragmentIds.add(removedFragmentId);
+                    }
                 }
             }
 
@@ -279,14 +395,15 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
                 if (fileInfo) {
                     const fileContent = await this.fileService.read(fileInfo.uri);
                     this.addTemplate(
-                        this.effectiveTemplates,
-                        fileInfo.templateId,
+                        this.activeCustomizations,
+                        fileInfo.fragmentId,
                         fileContent.value,
-                        TemplatePriority.TEMPLATE_FILE,
                         fileUriString,
-                        loadedTemplates
+                        this.allCustomizations,
+                        priority,
+                        CustomizationSource.FILE
                     );
-                    this.onDidChangePromptEmitter.fire(fileInfo.templateId);
+                    changedFragmentIds.add(fileInfo.fragmentId);
                 }
             }
 
@@ -298,60 +415,110 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
                 if (fileInfo) {
                     const fileContent = await this.fileService.read(fileInfo.uri);
                     this.addTemplate(
-                        this.effectiveTemplates,
-                        fileInfo.templateId,
+                        this.activeCustomizations,
+                        fileInfo.fragmentId,
                         fileContent.value,
-                        TemplatePriority.TEMPLATE_FILE,
                         fileUriString,
-                        loadedTemplates
+                        this.allCustomizations,
+                        priority,
+                        CustomizationSource.FILE
                     );
                     this.trackedTemplateURIs.add(fileUriString);
-                    this.onDidChangePromptEmitter.fire(fileInfo.templateId);
+                    changedFragmentIds.add(fileInfo.fragmentId);
                 }
             }
+
+            const changedFragmentIdsArray = Array.from(changedFragmentIds);
+            if (changedFragmentIdsArray.length > 0) {
+                this.onDidChangePromptFragmentCustomizationEmitter.fire(changedFragmentIdsArray);
+            };
         }));
     }
 
     /**
-     * Extract a template ID from a file path
+     * Extract a fragment ID from a file path
      * @param filePath The path to the template file
-     * @returns A template ID derived from the file name
+     * @returns A fragment ID derived from the file name
      */
-    protected getTemplateIdFromFilePath(filePath: string): string {
+    protected getFragmentIdFromFilePath(filePath: string): string {
         const uri = URI.fromFilePath(filePath);
         return this.removePromptTemplateSuffix(uri.path.name);
     }
 
+    /**
+     * Processes a directory for template files, adding them to the customizations map
+     * and setting up file watching
+     * @param activeCustomizationsCopy Map to store active customizations
+     * @param trackedTemplateURIsCopy Set to track URIs being monitored
+     * @param allCustomizationsCopy Map to store all loaded customizations
+     * @param dirURI URI of the directory to process
+     * @param priority Priority level for customizations in this directory
+     * @param customizationSource Source type of the customization
+     */
     protected async processTemplateDirectory(
-        templatesMap: Map<string, TemplateEntry>,
-        trackedURIs: Set<string>,
-        loadedTemplates: Map<string, TemplateEntry>,
+        activeCustomizationsCopy: Map<string, PromptFragmentCustomization>,
+        trackedTemplateURIsCopy: Set<string>,
+        allCustomizationsCopy: Map<string, PromptFragmentCustomization>,
         dirURI: URI,
-        priority: TemplatePriority
+        priority: number,
+        customizationSource: CustomizationSource
     ): Promise<void> {
+        if (!(await this.fileService.exists(dirURI))) {
+            return;
+        }
+        const stat = await this.fileService.resolve(dirURI);
+        if (stat.children === undefined) {
+            return;
+        }
+        const parsedPromptFragments = new Set<string>();
+        for (const file of stat.children) {
+            if (!file.isFile) {
+                continue;
+            }
+            const fileURI = file.resource;
+            if (this.isPromptTemplateExtension(fileURI.path.ext)) {
+                trackedTemplateURIsCopy.add(fileURI.toString());
+                const fileContent = await this.fileService.read(fileURI);
+                const fragmentId = this.removePromptTemplateSuffix(file.name);
+                this.addTemplate(activeCustomizationsCopy, fragmentId, fileContent.value, fileURI.toString(), allCustomizationsCopy, priority, customizationSource);
+                parsedPromptFragments.add(fragmentId);
+            }
+        }
+        this.onDidChangePromptFragmentCustomizationEmitter.fire(Array.from(parsedPromptFragments));
+        this.onDidChangeCustomAgentsEmitter.fire();
+
         this.toDispose.push(this.fileService.watch(dirURI, { recursive: true, excludes: [] }));
         this.toDispose.push(this.fileService.onDidFilesChange(async (event: FileChangesEvent) => {
+            // Only watch for changes within provided dir
+            if (!event.changes.some(change => change.resource.toString().startsWith(dirURI.toString()))) {
+                return;
+            }
             if (event.changes.some(change => change.resource.toString().endsWith('customAgents.yml'))) {
                 this.onDidChangeCustomAgentsEmitter.fire();
             }
 
+            // Track changes for batched notification
+            const changedFragmentIds = new Set<string>();
+
             // check deleted templates
             for (const deletedFile of event.getDeleted()) {
-                if (this.trackedTemplateURIs.has(deletedFile.resource.toString())) {
-                    this.trackedTemplateURIs.delete(deletedFile.resource.toString());
-                    const templateId = this.removePromptTemplateSuffix(deletedFile.resource.path.name);
-                    this.removeTemplateBySourceUri(deletedFile.resource.toString(), loadedTemplates);
-                    this.onDidChangePromptEmitter.fire(templateId);
+                const uriString = deletedFile.resource.toString();
+                if (this.trackedTemplateURIs.has(uriString)) {
+                    const removedFragmentId = this.removeCustomizationFromMaps(uriString, this.allCustomizations, this.activeCustomizations, this.trackedTemplateURIs);
+                    if (removedFragmentId) {
+                        changedFragmentIds.add(removedFragmentId);
+                    }
                 }
             }
 
             // check updated templates
             for (const updatedFile of event.getUpdated()) {
-                if (this.trackedTemplateURIs.has(updatedFile.resource.toString())) {
+                const uriString = updatedFile.resource.toString();
+                if (this.trackedTemplateURIs.has(uriString)) {
                     const fileContent = await this.fileService.read(updatedFile.resource);
-                    const templateId = this.removePromptTemplateSuffix(updatedFile.resource.path.name);
-                    this.addTemplate(this.effectiveTemplates, templateId, fileContent.value, priority, updatedFile.resource.toString(), loadedTemplates);
-                    this.onDidChangePromptEmitter.fire(templateId);
+                    const fragmentId = this.removePromptTemplateSuffix(updatedFile.resource.path.name);
+                    this.addTemplate(this.activeCustomizations, fragmentId, fileContent.value, uriString, this.allCustomizations, priority, customizationSource);
+                    changedFragmentIds.add(fragmentId);
                 }
             }
 
@@ -359,37 +526,20 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
             for (const addedFile of event.getAdded()) {
                 if (addedFile.resource.parent.toString() === dirURI.toString() &&
                     this.isPromptTemplateExtension(addedFile.resource.path.ext)) {
-                    this.trackedTemplateURIs.add(addedFile.resource.toString());
+                    const uriString = addedFile.resource.toString();
+                    this.trackedTemplateURIs.add(uriString);
                     const fileContent = await this.fileService.read(addedFile.resource);
-                    const templateId = this.removePromptTemplateSuffix(addedFile.resource.path.name);
-                    this.addTemplate(this.effectiveTemplates, templateId, fileContent.value, priority, addedFile.resource.toString(), loadedTemplates);
-                    this.onDidChangePromptEmitter.fire(templateId);
+                    const fragmentId = this.removePromptTemplateSuffix(addedFile.resource.path.name);
+                    this.addTemplate(this.activeCustomizations, fragmentId, fileContent.value, uriString, this.allCustomizations, priority, customizationSource);
+                    changedFragmentIds.add(fragmentId);
                 }
             }
-        }));
 
-        if (!(await this.fileService.exists(dirURI))) {
-            return;
-        }
-        const stat = await this.fileService.resolve(dirURI);
-        if (stat.children === undefined) {
-            return;
-        }
-
-        for (const file of stat.children) {
-            if (!file.isFile) {
-                continue;
-            }
-            const fileURI = file.resource;
-            if (this.isPromptTemplateExtension(fileURI.path.ext)) {
-                trackedURIs.add(fileURI.toString());
-                const fileContent = await this.fileService.read(fileURI);
-                const templateId = this.removePromptTemplateSuffix(file.name);
-                this.addTemplate(templatesMap, templateId, fileContent.value, priority, fileURI.toString(), loadedTemplates);
-                this.onDidChangePromptEmitter.fire(templateId);
-            }
-        }
-        this.onDidChangeCustomAgentsEmitter.fire();
+            const changedFragmentIdsArray = Array.from(changedFragmentIds);
+            if (changedFragmentIdsArray.length > 0) {
+                this.onDidChangePromptFragmentCustomizationEmitter.fire(changedFragmentIdsArray);
+            };
+        }));
     }
 
     /**
@@ -422,16 +572,15 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
      * @returns Array of file paths
      */
     getTemplateFiles(): string[] {
-        return Array.from(this.templateFiles);
+        return Array.from(this.workspaceTemplateFiles);
     }
 
     /**
      * Updates multiple configuration properties at once, triggering only a single update process.
-     *
      * @param properties An object containing the properties to update
      * @returns Promise that resolves when the update is complete
      */
-    async updateConfiguration(properties: PromptCustomizationProperties): Promise<void> {
+    async updateConfiguration(properties: PromptFragmentCustomizationProperties): Promise<void> {
         if (properties.directoryPaths !== undefined) {
             this.additionalTemplateDirs.clear();
             for (const path of properties.directoryPaths) {
@@ -449,9 +598,9 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
         }
 
         if (properties.filePaths !== undefined) {
-            this.templateFiles.clear();
+            this.workspaceTemplateFiles.clear();
             for (const path of properties.filePaths) {
-                this.templateFiles.add(path);
+                this.workspaceTemplateFiles.add(path);
             }
         }
 
@@ -459,6 +608,10 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
         await this.update();
     }
 
+    /**
+     * Gets the URI of the templates directory
+     * @returns URI of the templates directory
+     */
     protected async getTemplatesDirectoryURI(): Promise<URI> {
         const templatesFolder = this.preferences[PREFERENCE_NAME_PROMPT_TEMPLATES];
         if (templatesFolder && templatesFolder.trim().length > 0) {
@@ -468,10 +621,20 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
         return new URI(theiaConfigDir).resolve('prompt-templates');
     }
 
-    protected async getTemplateURI(templateId: string): Promise<URI> {
-        return (await this.getTemplatesDirectoryURI()).resolve(`${templateId}${PROMPT_TEMPLATE_EXTENSION}`);
+    /**
+     * Gets the URI for a specific template file
+     * @param fragmentId The fragment ID
+     * @returns URI for the template file
+     */
+    protected async getTemplateURI(fragmentId: string): Promise<URI> {
+        return (await this.getTemplatesDirectoryURI()).resolve(`${fragmentId}${PROMPT_TEMPLATE_EXTENSION}`);
     }
 
+    /**
+     * Removes the prompt template extension from a filename
+     * @param filename The filename with extension
+     * @returns The filename without the extension
+     */
     protected removePromptTemplateSuffix(filename: string): string {
         for (const ext of this.templateExtensions) {
             if (filename.endsWith(ext)) {
@@ -481,43 +644,271 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
         return filename;
     }
 
-    isPromptTemplateCustomized(id: string): boolean {
-        return this.effectiveTemplates.has(id);
+    // PromptFragmentCustomizationService interface implementation
+
+    isPromptFragmentCustomized(id: string): boolean {
+        return this.activeCustomizations.has(id);
+    }
+
+    getActivePromptFragmentCustomization(id: string): CustomizedPromptFragment | undefined {
+        const entry = this.activeCustomizations.get(id);
+        if (!entry) {
+            return undefined;
+        }
+
+        return {
+            id: entry.id,
+            template: entry.template,
+            customizationId: entry.customizationId,
+            priority: entry.priority
+        };
+    }
+
+    getAllCustomizations(id: string): CustomizedPromptFragment[] {
+        const fragments: CustomizedPromptFragment[] = [];
+
+        // Collect all customizations with matching ID
+        this.allCustomizations.forEach(value => {
+            if (value.id === id) {
+                fragments.push({
+                    id: value.id,
+                    template: value.template,
+                    customizationId: value.customizationId,
+                    priority: value.priority
+                });
+            }
+        });
+
+        // Sort by priority (highest first)
+        return fragments.sort((a, b) => b.priority - a.priority);
+    }
+
+    getCustomizedPromptFragmentIds(): string[] {
+        return Array.from(this.activeCustomizations.keys());
+    }
+
+    async createPromptFragmentCustomization(id: string, defaultContent?: string): Promise<void> {
+        await this.editTemplate(id, defaultContent);
     }
 
-    getCustomizedPromptTemplate(id: string): string | undefined {
-        const entry = this.effectiveTemplates.get(id);
-        return entry ? entry.content : undefined;
+    async createBuiltInPromptFragmentCustomization(id: string, defaultContent?: string): Promise<void> {
+        await this.createPromptFragmentCustomization(id, defaultContent);
     }
 
-    getCustomPromptTemplateIDs(): string[] {
-        return Array.from(this.effectiveTemplates.keys());
+    async editPromptFragmentCustomization(id: string, customizationId: string): Promise<void> {
+        // Find the customization with the given customization ID
+        const customization = Array.from(this.allCustomizations.values()).find(t =>
+            t.id === id && t.customizationId === customizationId
+        );
+
+        if (customization) {
+            const uri = new URI(customization.sourceUri);
+            const openHandler = await this.openerService.getOpener(uri);
+            openHandler.open(uri);
+        } else {
+            // Fall back to editing by fragment ID if customization ID not found
+            await this.editTemplate(id);
+        }
     }
 
-    async editTemplate(id: string, defaultContent?: string): Promise<void> {
+    /**
+     * Edits a template by opening it in the editor, creating it if it doesn't exist
+     * @param id The fragment ID
+     * @param defaultContent Optional default content for new templates
+     */
+    protected async editTemplate(id: string, defaultContent?: string): Promise<void> {
         const editorUri = await this.getTemplateURI(id);
-        if (! await this.fileService.exists(editorUri)) {
+        if (!(await this.fileService.exists(editorUri))) {
             await this.fileService.createFile(editorUri, BinaryBuffer.fromString(defaultContent ?? ''));
         }
         const openHandler = await this.openerService.getOpener(editorUri);
         openHandler.open(editorUri);
     }
 
-    async resetTemplate(id: string): Promise<void> {
-        const editorUri = await this.getTemplateURI(id);
-        if (await this.fileService.exists(editorUri)) {
-            await this.fileService.delete(editorUri);
+    async removePromptFragmentCustomization(id: string, customizationId: string): Promise<void> {
+        // Find the customization with the given customization ID
+        const customization = Array.from(this.allCustomizations.values()).find(t =>
+            t.id === id && t.customizationId === customizationId
+        );
+
+        if (customization) {
+            const sourceUri = customization.sourceUri;
+
+            // Delete the file if it exists
+            const uri = new URI(sourceUri);
+            if (await this.fileService.exists(uri)) {
+                await this.fileService.delete(uri);
+            }
+        }
+    }
+
+    async removeAllPromptFragmentCustomizations(id: string): Promise<void> {
+        // Get all customizations for this fragment ID
+        const customizations = this.getAllCustomizations(id);
+
+        if (customizations.length === 0) {
+            return; // Nothing to reset
+        }
+
+        // Find and delete all customization files
+        for (const customization of customizations) {
+            const fragment = Array.from(this.allCustomizations.values()).find(t =>
+                t.id === id && t.customizationId === customization.customizationId
+            );
+
+            if (fragment) {
+                const sourceUri = fragment.sourceUri;
+                // Delete the file if it exists
+                const uri = new URI(sourceUri);
+                if (await this.fileService.exists(uri)) {
+                    await this.fileService.delete(uri);
+                }
+            }
+        }
+    }
+
+    async resetToCustomization(id: string, customizationId: string): Promise<void> {
+        const customization = Array.from(this.allCustomizations.values()).find(t =>
+            t.id === id && t.customizationId === customizationId
+        );
+
+        if (customization) {
+            // Get all customizations for this fragment ID
+            const customizations = this.getAllCustomizations(id);
+
+            if (customizations.length === 0) {
+                return; // Nothing to reset
+            }
+
+            // Find the target customization
+            const targetCustomization = customizations.find(c => c.customizationId === customizationId);
+            if (!targetCustomization) {
+                return; // Target customization not found
+            }
+
+            // Find and delete all higher-priority customization files
+            for (const cust of customizations) {
+                if (cust.priority > targetCustomization.priority) {
+                    const fragmentToDelete = Array.from(this.allCustomizations.values()).find(t =>
+                        t.id === cust.id && t.customizationId === cust.customizationId
+                    );
+                    if (fragmentToDelete) {
+                        const sourceUri = fragmentToDelete.sourceUri;
+
+                        // Delete the file if it exists
+                        const uri = new URI(sourceUri);
+                        if (await this.fileService.exists(uri)) {
+                            await this.fileService.delete(uri);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    async getPromptFragmentCustomizationDescription(id: string, customizationId: string): Promise<string | undefined> {
+        // Find the customization with the given customization ID
+        const customization = Array.from(this.allCustomizations.values()).find(t =>
+            t.id === id && t.customizationId === customizationId
+        );
+
+        if (customization) {
+            return customization.sourceUri;
+        }
+
+        return undefined;
+    }
+
+    async getPromptFragmentCustomizationType(id: string, customizationId: string): Promise<string | undefined> {
+        // Find the customization with the given customization ID
+        const customization = Array.from(this.allCustomizations.values()).find(t =>
+            t.id === id && t.customizationId === customizationId
+        );
+
+        if (customization) {
+            return getCustomizationSourceString(customization.origin);
+        }
+
+        return undefined;
+    }
+
+    async editBuiltIn(id: string, defaultContent = ''): Promise<void> {
+        // Find an existing built-in customization (those with priority 1)
+        const builtInCustomization = Array.from(this.allCustomizations.values()).find(t =>
+            t.id === id && t.priority === 1
+        );
+
+        if (builtInCustomization) {
+            // Edit the existing built-in customization
+            const uri = new URI(builtInCustomization.sourceUri);
+            const openHandler = await this.openerService.getOpener(uri);
+            openHandler.open(uri);
+        } else {
+            // Create a new built-in customization
+            // Get the template URI in the main templates directory (priority 1)
+            const templateUri = await this.getTemplateURI(id);
+
+            // If template doesn't exist, create it with default content
+            if (!(await this.fileService.exists(templateUri))) {
+                await this.fileService.createFile(templateUri, BinaryBuffer.fromString(defaultContent));
+            }
+
+            // Open the template in the editor
+            const openHandler = await this.openerService.getOpener(templateUri);
+            openHandler.open(templateUri);
         }
     }
 
-    getTemplateIDFromURI(uri: URI): string | undefined {
+    async resetBuiltInCustomization(id: string): Promise<void> {
+        // Find a built-in customization (those with priority 1)
+        const builtInCustomization = Array.from(this.allCustomizations.values()).find(t =>
+            t.id === id && t.priority === 1
+        );
+
+        if (!builtInCustomization) {
+            return; // No built-in customization found
+        }
+
+        const sourceUri = builtInCustomization.sourceUri;
+
+        // Delete the file if it exists
+        const uri = new URI(sourceUri);
+        if (await this.fileService.exists(uri)) {
+            await this.fileService.delete(uri);
+        }
+    }
+
+    async editBuiltInPromptFragmentCustomization(id: string, defaultContent?: string): Promise<void> {
+        return this.editBuiltIn(id, defaultContent);
+    }
+
+    /**
+     * Gets the fragment ID from a URI
+     * @param uri URI to check
+     * @returns Fragment ID or undefined if not found
+     */
+    protected getFragmentIDFromURI(uri: URI): string | undefined {
         const id = this.removePromptTemplateSuffix(uri.path.name);
-        if (this.effectiveTemplates.has(id)) {
+        if (this.activeCustomizations.has(id)) {
             return id;
         }
         return undefined;
     }
 
+    /**
+     * Implementation of the generic getPromptFragmentIDFromResource method in the interface
+     * Accepts any resource identifier but only processes URIs
+     * @param resourceId Resource to check
+     * @returns Fragment ID or undefined if not found
+     */
+    getPromptFragmentIDFromResource(resourceId: unknown): string | undefined {
+        // Check if the resource is a URI
+        if (resourceId instanceof URI) {
+            return this.getFragmentIDFromURI(resourceId);
+        }
+        return undefined;
+    }
+
     async getCustomAgents(): Promise<CustomAgentDescription[]> {
         const agentsById = new Map<string, CustomAgentDescription>();
         // First, process additional (workspace) template directories to give them precedence
@@ -525,9 +916,9 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
             const dirURI = URI.fromFilePath(dirPath);
             await this.loadCustomAgentsFromDirectory(dirURI, agentsById);
         }
-        // Then process global template directory (only adding agents that don't conflict)
-        const globalTemplateDir = await this.getTemplatesDirectoryURI();
-        await this.loadCustomAgentsFromDirectory(globalTemplateDir, 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
         return Array.from(agentsById.values());
     }
@@ -577,9 +968,9 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
      */
     async getCustomAgentsLocations(): Promise<{ uri: URI, exists: boolean }[]> {
         const locations: { uri: URI, exists: boolean }[] = [];
-        // Check global template directory
-        const globalTemplateDir = await this.getTemplatesDirectoryURI();
-        const globalAgentsUri = globalTemplateDir.resolve('customAgents.yml');
+        // 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
@@ -598,7 +989,7 @@ export class FrontendPromptCustomizationServiceImpl implements PromptCustomizati
      * @param uri The URI of the customAgents.yml file to open or create
      */
     async openCustomAgentYaml(uri: URI): Promise<void> {
-        const content = dump([templateEntry]);
+        const content = dump([newCustomAgentEntry]);
         if (! await this.fileService.exists(uri)) {
             await this.fileService.createFile(uri, BinaryBuffer.fromString(content));
         } else {