@theia/ai-core 1.66.0-next.44 → 1.66.0-next.73

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

@@ -17,14 +17,15 @@
 import { DisposableCollection, URI, Event, Emitter, nls } from '@theia/core';
 import { OpenerService } from '@theia/core/lib/browser';
 import { inject, injectable, postConstruct } from '@theia/core/shared/inversify';
-import { PromptFragmentCustomizationService, CustomAgentDescription, CustomizedPromptFragment } from '../common';
+import { PromptFragmentCustomizationService, CustomAgentDescription, CustomizedPromptFragment, CommandPromptFragmentMetadata } 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';
 import { AICorePreferences, PREFERENCE_NAME_PROMPT_TEMPLATES } from '../common/ai-core-preferences';
 import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
-import { load, dump } from 'js-yaml';
+import { dump, load } from 'js-yaml';
 import { PROMPT_TEMPLATE_EXTENSION } from './prompttemplate-contribution';
+import { parseTemplateWithMetadata, ParsedTemplate } from './prompttemplate-parser';
 
 /**
  * Default template entry for creating custom agents
@@ -80,8 +81,9 @@ export interface PromptFragmentCustomizationProperties {
 
 /**
  * Internal representation of a fragment entry in the customization service
+ * Extends TemplateMetadata to include command-related properties
  */
-interface PromptFragmentCustomization {
+interface PromptFragmentCustomization extends CommandPromptFragmentMetadata {
     /** The template content */
     template: string;
 
@@ -213,6 +215,7 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
      * @param allCustomizationsCopy The map to track all loaded customizations
      * @param priority The customization priority
      * @param origin The source type of the customization
+     * @param metadata Optional command metadata
      */
     protected addTemplate(
         activeCustomizationsCopy: Map<string, PromptFragmentCustomization>,
@@ -221,14 +224,32 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
         sourceUri: string,
         allCustomizationsCopy: Map<string, PromptFragmentCustomization>,
         priority: number,
-        origin: CustomizationSource
+        origin: CustomizationSource,
+        metadata?: CommandPromptFragmentMetadata
     ): void {
         // Generate a unique customization ID based on source URI and priority
         const customizationId = this.generateCustomizationId(id, sourceUri);
 
+        // Create customization object with metadata
+        const customization: PromptFragmentCustomization = {
+            id,
+            template,
+            sourceUri,
+            priority,
+            customizationId,
+            origin,
+            ...(metadata && {
+                isCommand: metadata.isCommand,
+                commandName: metadata.commandName,
+                commandDescription: metadata.commandDescription,
+                commandArgumentHint: metadata.commandArgumentHint,
+                commandAgents: metadata.commandAgents,
+            })
+        };
+
         // Always add to allCustomizationsCopy to keep track of all customizations including overridden ones
         if (sourceUri) {
-            allCustomizationsCopy.set(sourceUri, { id, template, sourceUri, priority, customizationId, origin });
+            allCustomizationsCopy.set(sourceUri, customization);
         }
 
         const existingEntry = activeCustomizationsCopy.get(id);
@@ -237,13 +258,13 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
             // 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
-                activeCustomizationsCopy.set(id, { id, template, sourceUri, priority, customizationId, origin });
+                activeCustomizationsCopy.set(id, customization);
                 return;
             }
 
             // If the new customization has higher priority, replace the existing one
             if (priority > existingEntry.priority) {
-                activeCustomizationsCopy.set(id, { id, template, sourceUri, priority, customizationId, origin });
+                activeCustomizationsCopy.set(id, customization);
                 return;
             } else if (priority === existingEntry.priority) {
                 // There is a conflict with the same priority, we ignore the new customization
@@ -254,7 +275,7 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
         }
 
         // No conflict at all, add the customization
-        activeCustomizationsCopy.set(id, { id, template, sourceUri, priority, customizationId, origin });
+        activeCustomizationsCopy.set(id, customization);
     }
 
     /**
@@ -285,6 +306,15 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
         return Math.abs(hash).toString(36).substring(0, 8);
     }
 
+    /**
+     * Parses a template file that may contain YAML front matter
+     * @param fileContent The raw file content
+     * @returns Parsed metadata and template content
+     */
+    protected parseTemplateWithMetadata(fileContent: string): ParsedTemplate {
+        return parseTemplateWithMetadata(fileContent);
+    }
+
     /**
      * 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.
@@ -359,7 +389,8 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
             if (await this.fileService.exists(fileURI)) {
                 trackedTemplateURIsCopy.add(uriString);
                 const fileContent = await this.fileService.read(fileURI);
-                this.addTemplate(activeCustomizationsCopy, fragmentId, fileContent.value, uriString, allCustomizationsCopy, priority, CustomizationSource.FILE);
+                const parsed = this.parseTemplateWithMetadata(fileContent.value);
+                this.addTemplate(activeCustomizationsCopy, fragmentId, parsed.template, uriString, allCustomizationsCopy, priority, CustomizationSource.FILE, parsed.metadata);
                 parsedPromptFragments.add(fragmentId);
             }
         }
@@ -394,14 +425,16 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
 
                 if (fileInfo) {
                     const fileContent = await this.fileService.read(fileInfo.uri);
+                    const parsed = this.parseTemplateWithMetadata(fileContent.value);
                     this.addTemplate(
                         this.activeCustomizations,
                         fileInfo.fragmentId,
-                        fileContent.value,
+                        parsed.template,
                         fileUriString,
                         this.allCustomizations,
                         priority,
-                        CustomizationSource.FILE
+                        CustomizationSource.FILE,
+                        parsed.metadata
                     );
                     changedFragmentIds.add(fileInfo.fragmentId);
                 }
@@ -414,14 +447,16 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
 
                 if (fileInfo) {
                     const fileContent = await this.fileService.read(fileInfo.uri);
+                    const parsed = this.parseTemplateWithMetadata(fileContent.value);
                     this.addTemplate(
                         this.activeCustomizations,
                         fileInfo.fragmentId,
-                        fileContent.value,
+                        parsed.template,
                         fileUriString,
                         this.allCustomizations,
                         priority,
-                        CustomizationSource.FILE
+                        CustomizationSource.FILE,
+                        parsed.metadata
                     );
                     this.trackedTemplateURIs.add(fileUriString);
                     changedFragmentIds.add(fileInfo.fragmentId);
@@ -512,8 +547,9 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
             if (this.isPromptTemplateExtension(fileURI.path.ext)) {
                 trackedTemplateURIsCopy.add(fileURI.toString());
                 const fileContent = await this.fileService.read(fileURI);
+                const parsed = this.parseTemplateWithMetadata(fileContent.value);
                 const fragmentId = this.removePromptTemplateSuffix(file.name);
-                this.addTemplate(activeCustomizationsCopy, fragmentId, fileContent.value, fileURI.toString(), allCustomizationsCopy, priority, customizationSource);
+                this.addTemplate(activeCustomizationsCopy, fragmentId, parsed.template, fileURI.toString(), allCustomizationsCopy, priority, customizationSource, parsed.metadata);
                 parsedPromptFragments.add(fragmentId);
             }
         }
@@ -575,15 +611,17 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
                 const uriString = updatedFile.resource.toString();
                 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);
                     this.addTemplate(
                         this.activeCustomizations,
                         fragmentId,
-                        fileContent.value,
+                        parsed.template,
                         uriString,
                         this.allCustomizations,
                         priority,
-                        customizationSource
+                        customizationSource,
+                        parsed.metadata
                     );
                     changedFragmentIds.add(fragmentId);
                 }
@@ -596,15 +634,17 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
                     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,
-                        fileContent.value,
+                        parsed.template,
                         uriString,
                         this.allCustomizations,
                         priority,
-                        customizationSource
+                        customizationSource,
+                        parsed.metadata
                     );
                     changedFragmentIds.add(fragmentId);
                 }
@@ -735,7 +775,13 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
             id: entry.id,
             template: entry.template,
             customizationId: entry.customizationId,
-            priority: entry.priority
+            priority: entry.priority,
+            // Pass through command metadata
+            isCommand: entry.isCommand,
+            commandName: entry.commandName,
+            commandDescription: entry.commandDescription,
+            commandArgumentHint: entry.commandArgumentHint,
+            commandAgents: entry.commandAgents,
         };
     }
 
@@ -749,7 +795,13 @@ export class DefaultPromptFragmentCustomizationService implements PromptFragment
                     id: value.id,
                     template: value.template,
                     customizationId: value.customizationId,
-                    priority: value.priority
+                    priority: value.priority,
+                    // Pass through command metadata
+                    isCommand: value.isCommand,
+                    commandName: value.commandName,
+                    commandDescription: value.commandDescription,
+                    commandArgumentHint: value.commandArgumentHint,
+                    commandAgents: value.commandAgents,
                 });
             }
         });

package/src/browser/prompttemplate-parser.ts

@@ -0,0 +1,111 @@
+// *****************************************************************************
+// Copyright (C) 2025 EclipseSource and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { load } from 'js-yaml';
+import { CommandPromptFragmentMetadata } from '../common';
+
+/**
+ * Result of parsing a template file that may contain YAML front matter
+ */
+export interface ParsedTemplate {
+    /** The template content (without front matter) */
+    template: string;
+
+    /** Parsed metadata from YAML front matter, if present */
+    metadata?: CommandPromptFragmentMetadata;
+}
+
+/**
+ * Type guard to check if an object is valid TemplateMetadata
+ */
+export function isTemplateMetadata(obj: unknown): obj is CommandPromptFragmentMetadata {
+    if (!obj || typeof obj !== 'object') {
+        return false;
+    }
+    const metadata = obj as Record<string, unknown>;
+    return (
+        (metadata.isCommand === undefined || typeof metadata.isCommand === 'boolean') &&
+        (metadata.commandName === undefined || typeof metadata.commandName === 'string') &&
+        (metadata.commandDescription === undefined || typeof metadata.commandDescription === 'string') &&
+        (metadata.commandArgumentHint === undefined || typeof metadata.commandArgumentHint === 'string') &&
+        (metadata.commandAgents === undefined || (Array.isArray(metadata.commandAgents) &&
+            metadata.commandAgents.every(agent => typeof agent === 'string')))
+    );
+}
+
+/**
+ * Parses a template file that may contain YAML front matter.
+ *
+ * Front matter format:
+ * ```
+ * ---
+ * isCommand: true
+ * commandName: mycommand
+ * commandDescription: My command description
+ * commandArgumentHint: <arg1> <arg2>
+ * commandAgents:
+ *   - Agent1
+ *   - Agent2
+ * ---
+ * Template content here
+ * ```
+ *
+ * @param fileContent The raw file content to parse
+ * @returns ParsedTemplate containing the template content and optional metadata
+ */
+export function parseTemplateWithMetadata(fileContent: string): ParsedTemplate {
+    const frontMatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
+    const match = fileContent.match(frontMatterRegex);
+
+    if (!match) {
+        // No front matter, return content as-is
+        return { template: fileContent };
+    }
+
+    try {
+        const yamlContent = match[1];
+        const template = match[2];
+        const parsedYaml = load(yamlContent);
+
+        // Validate the parsed YAML is an object
+        if (!parsedYaml || typeof parsedYaml !== 'object') {
+            return { template: fileContent };
+        }
+
+        const metadata = parsedYaml as Record<string, unknown>;
+
+        // Extract and validate command metadata
+        const templateMetadata: CommandPromptFragmentMetadata = {
+            isCommand: typeof metadata.isCommand === 'boolean' ? metadata.isCommand : undefined,
+            commandName: typeof metadata.commandName === 'string' ? metadata.commandName : undefined,
+            commandDescription: typeof metadata.commandDescription === 'string' ? metadata.commandDescription : undefined,
+            commandArgumentHint: typeof metadata.commandArgumentHint === 'string' ? metadata.commandArgumentHint : undefined,
+            commandAgents: Array.isArray(metadata.commandAgents) ? metadata.commandAgents.filter(a => typeof a === 'string') : undefined,
+        };
+
+        // Only include metadata if it's valid
+        if (isTemplateMetadata(templateMetadata)) {
+            return { template, metadata: templateMetadata };
+        }
+
+        // Metadata validation failed, return just the template
+        return { template };
+    } catch (error) {
+        console.error('Failed to parse front matter:', error);
+        // Return entire content if YAML parsing fails
+        return { template: fileContent };
+    }
+}

package/src/common/prompt-service.spec.ts

@@ -362,4 +362,147 @@ describe('PromptService', () => {
         // Verify that the tool invocation registry was called
         expect(toolInvocationRegistry.getFunction.calledWith('testFunction')).to.be.true;
     });
+
+    // ===== Command Tests =====
+
+    describe('Command Management', () => {
+        it('getCommands() returns only fragments with isCommand=true', () => {
+            promptService.addBuiltInPromptFragment({
+                id: 'cmd1',
+                template: 'Command 1',
+                isCommand: true,
+                commandName: 'cmd1'
+            });
+            promptService.addBuiltInPromptFragment({
+                id: 'normal',
+                template: 'Normal prompt'
+            });
+            promptService.addBuiltInPromptFragment({
+                id: 'cmd2',
+                template: 'Command 2',
+                isCommand: true,
+                commandName: 'cmd2'
+            });
+
+            const commands = promptService.getCommands();
+            expect(commands.length).to.equal(2);
+            expect(commands.map(c => c.id)).to.include('cmd1');
+            expect(commands.map(c => c.id)).to.include('cmd2');
+            expect(commands.map(c => c.id)).to.not.include('normal');
+        });
+
+        it('getCommands(agentId) filters by commandAgents array', () => {
+            promptService.addBuiltInPromptFragment({
+                id: 'cmd-universal',
+                template: 'Universal command',
+                isCommand: true,
+                commandName: 'universal',
+                commandAgents: ['Universal']
+            });
+            promptService.addBuiltInPromptFragment({
+                id: 'cmd-specific',
+                template: 'Specific command',
+                isCommand: true,
+                commandName: 'specific',
+                commandAgents: ['SpecificAgent']
+            });
+
+            const universalCommands = promptService.getCommands('Universal');
+            expect(universalCommands.length).to.equal(1);
+            expect(universalCommands[0].id).to.equal('cmd-universal');
+
+            const specificCommands = promptService.getCommands('SpecificAgent');
+            expect(specificCommands.length).to.equal(1);
+            expect(specificCommands[0].id).to.equal('cmd-specific');
+        });
+
+        it('getCommands(agentId) includes commands without commandAgents', () => {
+            promptService.addBuiltInPromptFragment({
+                id: 'cmd-all',
+                template: 'Available for all',
+                isCommand: true,
+                commandName: 'all'
+                // No commandAgents means available for all
+            });
+            promptService.addBuiltInPromptFragment({
+                id: 'cmd-specific',
+                template: 'Specific command',
+                isCommand: true,
+                commandName: 'specific',
+                commandAgents: ['Universal']
+            });
+
+            const commands = promptService.getCommands('SomeOtherAgent');
+            expect(commands.length).to.equal(1);
+            expect(commands[0].id).to.equal('cmd-all');
+        });
+
+        it('getCommands() returns empty array when no commands registered', () => {
+            promptService.addBuiltInPromptFragment({
+                id: 'normal1',
+                template: 'Normal prompt 1'
+            });
+            promptService.addBuiltInPromptFragment({
+                id: 'normal2',
+                template: 'Normal prompt 2'
+            });
+
+            const commands = promptService.getCommands();
+            expect(commands.length).to.equal(0);
+        });
+
+        it('command metadata preserved through registration', () => {
+            promptService.addBuiltInPromptFragment({
+                id: 'test-cmd',
+                template: 'Test command',
+                isCommand: true,
+                commandName: 'test',
+                commandDescription: 'A test command',
+                commandArgumentHint: '<arg>',
+                commandAgents: ['Agent1', 'Agent2']
+            });
+
+            const commands = promptService.getCommands();
+            expect(commands.length).to.equal(1);
+            const cmd = commands[0];
+            expect(cmd.isCommand).to.be.true;
+            expect(cmd.commandName).to.equal('test');
+            expect(cmd.commandDescription).to.equal('A test command');
+            expect(cmd.commandArgumentHint).to.equal('<arg>');
+            expect(cmd.commandAgents).to.deep.equal(['Agent1', 'Agent2']);
+        });
+
+        it('getFragmentByCommandName finds fragment by command name', () => {
+            promptService.addBuiltInPromptFragment({
+                id: 'sample-debug',
+                template: 'Help debug: $ARGUMENTS',
+                isCommand: true,
+                commandName: 'debug',
+                commandDescription: 'Debug an issue',
+                commandArgumentHint: '<problem>'
+            });
+
+            // Should find by command name
+            const fragment = promptService.getPromptFragmentByCommandName('debug');
+            expect(fragment).to.not.be.undefined;
+            expect(fragment?.id).to.equal('sample-debug');
+            expect(fragment?.commandName).to.equal('debug');
+            expect(fragment?.template).to.equal('Help debug: $ARGUMENTS');
+        });
+
+        it('getFragmentByCommandName returns undefined for non-command fragments', () => {
+            promptService.addBuiltInPromptFragment({
+                id: 'normal-fragment',
+                template: 'Not a command'
+            });
+
+            const fragment = promptService.getPromptFragmentByCommandName('normal-fragment');
+            expect(fragment).to.be.undefined;
+        });
+
+        it('getFragmentByCommandName returns undefined for non-existent command', () => {
+            const fragment = promptService.getPromptFragmentByCommandName('non-existent');
+            expect(fragment).to.be.undefined;
+        });
+    });
 });

package/src/common/prompt-service.ts

@@ -23,10 +23,27 @@ import { ToolRequest } from './language-model';
 import { matchFunctionsRegEx, matchVariablesRegEx } from './prompt-service-util';
 import { AISettingsService } from './settings-service';
 
+export interface CommandPromptFragmentMetadata {
+    /** Mark this template as available as a slash command */
+    isCommand?: boolean;
+
+    /** Display name for the command (defaults to fragment id if not specified) */
+    commandName?: string;
+
+    /** Description shown in command autocomplete */
+    commandDescription?: string;
+
+    /** Hint for command arguments shown in autocomplete detail (e.g., "<topic>", "[options]") */
+    commandArgumentHint?: string;
+
+    /** List of agent IDs this command is available for (undefined means available for all agents) */
+    commandAgents?: string[];
+}
+
 /**
  * Represents a basic prompt fragment with an ID and template content.
  */
-export interface BasePromptFragment {
+export interface BasePromptFragment extends CommandPromptFragmentMetadata {
     /** Unique identifier for this prompt fragment */
     id: string;
 
@@ -306,6 +323,13 @@ export interface PromptService {
      */
     getBuiltInRawPrompt(fragmentId: string): PromptFragment | undefined;
 
+    /**
+     * Gets a prompt fragment by command name (for slash commands)
+     * @param commandName The command name to search for
+     * @returns The fragment with the matching command name or undefined if not found
+     */
+    getPromptFragmentByCommandName(commandName: string): PromptFragment | undefined;
+
     /**
      * Resolves a prompt fragment by replacing variables and function references
      * @param fragmentId The prompt fragment ID
@@ -399,6 +423,13 @@ export interface PromptService {
      */
     getPromptVariantSets(): Map<string, string[]>;
 
+    /**
+     * Gets all prompt fragments marked as commands, optionally filtered by agent
+     * @param agentId Optional agent ID to filter commands (undefined returns commands for all agents)
+     * @returns Array of command prompt fragments
+     */
+    getCommands(agentId?: string): PromptFragment[];
+
     /**
      * The following methods delegate to the PromptFragmentCustomizationService
      */
@@ -559,6 +590,24 @@ export class PromptServiceImpl implements PromptService {
         };
     }
 
+    getPromptFragmentByCommandName(commandName: string): PromptFragment | undefined {
+        // First check customized fragments
+        if (this.customizationService) {
+            const customizedIds = this.customizationService.getCustomizedPromptFragmentIds();
+            for (const fragmentId of customizedIds) {
+                const fragment = this.customizationService.getActivePromptFragmentCustomization(fragmentId);
+                if (fragment?.isCommand && fragment.commandName === commandName) {
+                    return fragment;
+                }
+            }
+        }
+
+        // Then check built-in fragments
+        return this._builtInFragments.find(fragment =>
+            fragment.isCommand && fragment.commandName === commandName
+        );
+    }
+
     /**
      * Strips comments from a template string
      * @param templateText The template text to process
@@ -888,6 +937,19 @@ export class PromptServiceImpl implements PromptService {
             this._builtInFragments.push(promptFragment);
         }
 
+        // Validate command name uniqueness if this is a command
+        if (promptFragment.isCommand && promptFragment.commandName) {
+            const commandName = promptFragment.commandName;
+            const duplicates = this._builtInFragments.filter(
+                f => f.isCommand && f.commandName === commandName && f.id !== promptFragment.id
+            );
+            if (duplicates.length > 0) {
+                this.logger.warn(
+                    `Command name '${commandName}' is used by multiple fragments: ${promptFragment.id} and ${duplicates.map(d => d.id).join(', ')}`
+                );
+            }
+        }
+
         // If this is a variant of a prompt variant set, record it in the variants map
         if (promptVariantSetId) {
             this.addFragmentVariant(promptVariantSetId, promptFragment.id, isDefault);
@@ -1042,4 +1104,14 @@ export class PromptServiceImpl implements PromptService {
             await this.customizationService.editBuiltInPromptFragmentCustomization(fragmentId, builtInTemplate?.template);
         }
     }
+
+    getCommands(agentId?: string): PromptFragment[] {
+        const allCommands = this.getActivePromptFragments().filter(fragment => fragment.isCommand === true);
+
+        if (!agentId) {
+            return allCommands;
+        }
+
+        return allCommands.filter(fragment => !fragment.commandAgents || fragment.commandAgents.includes(agentId));
+    }
 }

package/src/common/prompt-text.ts

@@ -19,4 +19,5 @@ export namespace PromptText {
     export const VARIABLE_CHAR = '#';
     export const FUNCTION_CHAR = '~';
     export const VARIABLE_SEPARATOR_CHAR = ':';
+    export const COMMAND_CHAR = '/';
 }