@theia/ai-core 1.63.0-next.52 → 1.63.0

package/src/browser/agent-completion-notification-service.ts

@@ -0,0 +1,242 @@
+// *****************************************************************************
+// Copyright (C) 2025 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { injectable, inject } from '@theia/core/shared/inversify';
+import { PreferenceService } from '@theia/core/lib/browser/preferences';
+import { MessageService } from '@theia/core/lib/common/message-service';
+import { ApplicationShell } from '@theia/core/lib/browser/shell/application-shell';
+import { nls } from '@theia/core/lib/common/nls';
+import {
+    PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE,
+} from './ai-core-preferences';
+import { AgentService } from '../common/agent-service';
+import { AISettingsService } from '../common/settings-service';
+import { OSNotificationService } from './os-notification-service';
+import { WindowBlinkService } from './window-blink-service';
+import {
+    NotificationType,
+    NOTIFICATION_TYPE_OFF,
+    NOTIFICATION_TYPE_OS_NOTIFICATION,
+    NOTIFICATION_TYPE_MESSAGE,
+    NOTIFICATION_TYPE_BLINK,
+} from '../common/notification-types';
+
+@injectable()
+export class AgentCompletionNotificationService {
+    @inject(PreferenceService)
+    protected readonly preferenceService: PreferenceService;
+
+    @inject(AgentService)
+    protected readonly agentService: AgentService;
+
+    @inject(AISettingsService)
+    protected readonly settingsService: AISettingsService;
+
+    @inject(OSNotificationService)
+    protected readonly osNotificationService: OSNotificationService;
+
+    @inject(MessageService)
+    protected readonly messageService: MessageService;
+
+    @inject(WindowBlinkService)
+    protected readonly windowBlinkService: WindowBlinkService;
+
+    @inject(ApplicationShell)
+    protected readonly shell: ApplicationShell;
+
+    /**
+     * Show a completion notification for the specified agent if enabled in preferences.
+     *
+     * @param agentId The unique identifier of the agent
+     * @param taskDescription Optional description of the completed task
+     */
+    async showCompletionNotification(
+        agentId: string,
+        taskDescription?: string,
+    ): Promise<void> {
+        const notificationType =
+            await this.getNotificationTypeForAgent(agentId);
+
+        if (notificationType === NOTIFICATION_TYPE_OFF || this.isChatWidgetFocused()) {
+            return;
+        }
+
+        try {
+            const agentName = this.resolveAgentName(agentId);
+            await this.executeNotificationType(
+                agentName,
+                taskDescription,
+                notificationType,
+            );
+        } catch (error) {
+            console.error(
+                'Failed to show agent completion notification:',
+                error,
+            );
+        }
+    }
+
+    /**
+     * Resolve the display name for an agent by its ID.
+     *
+     * @param agentId The unique identifier of the agent
+     * @returns The agent's display name or the agent ID if not found
+     */
+    protected resolveAgentName(agentId: string): string {
+        try {
+            const agents = this.agentService.getAllAgents();
+            const agent = agents.find(a => a.id === agentId);
+            return agent?.name || agentId;
+        } catch (error) {
+            console.warn(
+                `Failed to resolve agent name for ID '${agentId}':`,
+                error,
+            );
+            return agentId;
+        }
+    }
+
+    /**
+     * Get the preferred notification type for a specific agent.
+     * If no agent-specific preference is set, returns the global default notification type.
+     */
+    protected async getNotificationTypeForAgent(
+        agentId: string,
+    ): Promise<NotificationType> {
+        const agentSettings =
+            await this.settingsService.getAgentSettings(agentId);
+        const agentNotificationType = agentSettings?.completionNotification as NotificationType;
+
+        // If agent has no specific setting, use the global default
+        if (!agentNotificationType) {
+            return this.preferenceService.get<NotificationType>(
+                PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE,
+                NOTIFICATION_TYPE_OFF,
+            );
+        }
+
+        return agentNotificationType;
+    }
+
+    /**
+     * Execute the specified notification type.
+     */
+    private async executeNotificationType(
+        agentName: string,
+        taskDescription: string | undefined,
+        type: NotificationType,
+    ): Promise<void> {
+        switch (type) {
+            case NOTIFICATION_TYPE_OS_NOTIFICATION:
+                await this.showOSNotification(agentName, taskDescription);
+                break;
+            case NOTIFICATION_TYPE_MESSAGE:
+                await this.showMessageServiceNotification(
+                    agentName,
+                    taskDescription,
+                );
+                break;
+            case NOTIFICATION_TYPE_BLINK:
+                await this.showBlinkNotification(agentName);
+                break;
+            default:
+                throw new Error(`Unknown notification type: ${type}`);
+        }
+    }
+
+    /**
+     * Show OS notification directly.
+     */
+    protected async showOSNotification(
+        agentName: string,
+        taskDescription?: string,
+    ): Promise<void> {
+        const result =
+            await this.osNotificationService.showAgentCompletionNotification(
+                agentName,
+                taskDescription,
+            );
+        if (!result.success) {
+            throw new Error(`OS notification failed: ${result.error}`);
+        }
+    }
+
+    /**
+     * Show MessageService notification.
+     */
+    protected async showMessageServiceNotification(
+        agentName: string,
+        taskDescription?: string,
+    ): Promise<void> {
+        const message = taskDescription
+            ? nls.localize(
+                'theia/ai-core/agentCompletionWithTask',
+                'Agent "{0}" has completed the task: {1}',
+                agentName,
+                taskDescription,
+            )
+            : nls.localize(
+                'theia/ai-core/agentCompletionMessage',
+                'Agent "{0}" has completed its task.',
+                agentName,
+            );
+        this.messageService.info(message);
+    }
+
+    /**
+     * Show window blink notification.
+     */
+    protected async showBlinkNotification(agentName: string): Promise<void> {
+        const result = await this.windowBlinkService.blinkWindow(agentName);
+        if (!result.success) {
+            throw new Error(
+                `Window blink notification failed: ${result.error}`,
+            );
+        }
+    }
+
+    /**
+     * Check if OS notifications are supported and enabled.
+     */
+    isOSNotificationSupported(): boolean {
+        return this.osNotificationService.isNotificationSupported();
+    }
+
+    /**
+     * Get the current OS notification permission status.
+     */
+    getOSNotificationPermission(): NotificationPermission {
+        return this.osNotificationService.getPermissionStatus();
+    }
+
+    /**
+     * Request OS notification permission from the user.
+     */
+    async requestOSNotificationPermission(): Promise<NotificationPermission> {
+        return this.osNotificationService.requestPermission();
+    }
+
+    /**
+     * Check if any chat widget currently has focus.
+     */
+    protected isChatWidgetFocused(): boolean {
+        const activeWidget = this.shell.activeWidget;
+        if (!activeWidget) {
+            return false;
+        }
+        return activeWidget.id === 'chat-view-widget';
+    }
+}

package/src/browser/agent-preferences.ts

@@ -16,6 +16,9 @@
 
 import { nls } from '@theia/core';
 import { PreferenceSchema } from '@theia/core/lib/browser/preferences/preference-contribution';
+import {
+  NOTIFICATION_TYPES
+} from '../common/notification-types';
 
 export const AGENT_SETTINGS_PREF = 'ai-features.agentSettings';
 
@@ -65,6 +68,17 @@ export const AgentSettingsPreferenceSchema: PreferenceSchema = {
             additionalProperties: {
               type: 'string'
             }
+          },
+          completionNotification: {
+            type: 'string',
+            enum: [...NOTIFICATION_TYPES],
+            title: nls.localize('theia/ai/agents/completionNotification/title', 'Completion Notification'),
+            markdownDescription: nls.localize('theia/ai/agents/completionNotification/mdDescription',
+              'Notification behavior when this agent completes a task. If not set, the global default notification setting will be used.\n\
+                - `os-notification`: Show OS/system notifications\n\
+                - `message`: Show notifications in the status bar/message area\n\
+                - `blink`: Blink or highlight the UI\n\
+                - `off`: Disable notifications for this agent')
           }
         },
         required: ['languageModelRequirements']

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

@@ -13,6 +13,7 @@
 //
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
+
 import { bindContributionProvider, CommandContribution, CommandHandler, ResourceResolver } from '@theia/core';
 import {
     RemoteConnectionProvider,
@@ -72,6 +73,9 @@ import { FrontendLanguageModelServiceImpl } from './frontend-language-model-serv
 import { TokenUsageFrontendService } from './token-usage-frontend-service';
 import { TokenUsageFrontendServiceImpl, TokenUsageServiceClientImpl } from './token-usage-frontend-service-impl';
 import { AIVariableUriLabelProvider } from './ai-variable-uri-label-provider';
+import { AgentCompletionNotificationService } from './agent-completion-notification-service';
+import { OSNotificationService } from './os-notification-service';
+import { WindowBlinkService } from './window-blink-service';
 
 export default new ContainerModule(bind => {
     bindContributionProvider(bind, LanguageModelProvider);
@@ -165,6 +169,10 @@ export default new ContainerModule(bind => {
     bind(ResourceResolver).toService(AIVariableResourceResolver);
     bind(AIVariableUriLabelProvider).toSelf().inSingletonScope();
     bind(LabelProviderContribution).toService(AIVariableUriLabelProvider);
+
+    bind(AgentCompletionNotificationService).toSelf().inSingletonScope();
+    bind(OSNotificationService).toSelf().inSingletonScope();
+    bind(WindowBlinkService).toSelf().inSingletonScope();
     bind(ConfigurableInMemoryResources).toSelf().inSingletonScope();
     bind(ResourceResolver).toService(ConfigurableInMemoryResources);
 });

package/src/browser/ai-core-preferences.ts

@@ -18,12 +18,18 @@ import { nls } from '@theia/core';
 import { PreferenceContribution, PreferenceProxy, PreferenceSchema } from '@theia/core/lib/browser';
 import { PreferenceProxyFactory } from '@theia/core/lib/browser/preferences/injectable-preference-proxy';
 import { interfaces } from '@theia/core/shared/inversify';
+import {
+    NOTIFICATION_TYPES,
+    NOTIFICATION_TYPE_OFF,
+    NotificationType
+} from '../common/notification-types';
 
 export const AI_CORE_PREFERENCES_TITLE = nls.localize('theia/ai/core/prefs/title', '✨ AI Features [Alpha]');
 export const PREFERENCE_NAME_ENABLE_AI = 'ai-features.AiEnable.enableAI';
 export const PREFERENCE_NAME_PROMPT_TEMPLATES = 'ai-features.promptTemplates.promptTemplatesFolder';
 export const PREFERENCE_NAME_REQUEST_SETTINGS = 'ai-features.modelSettings.requestSettings';
 export const PREFERENCE_NAME_MAX_RETRIES = 'ai-features.modelSettings.maxRetries';
+export const PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE = 'ai-features.notifications.default';
 
 export const aiCorePreferenceSchema: PreferenceSchema = {
     type: 'object',
@@ -130,14 +136,28 @@ export const aiCorePreferenceSchema: PreferenceSchema = {
             type: 'number',
             minimum: 0,
             default: 3
+        },
+        [PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE]: {
+            title: nls.localize('theia/ai/core/defaultNotification/title', 'Default Notification Type'),
+            markdownDescription: nls.localize('theia/ai/core/defaultNotification/mdDescription',
+                'The default notification method used when an AI agent completes a task. Individual agents can override this setting.\n\
+                - `os-notification`: Show OS/system notifications\n\
+                - `message`: Show notifications in the status bar/message area\n\
+                - `blink`: Blink or highlight the UI\n\
+                - `off`: Disable all notifications'),
+            type: 'string',
+            enum: [...NOTIFICATION_TYPES],
+            default: NOTIFICATION_TYPE_OFF
         }
     }
 };
+
 export interface AICoreConfiguration {
     [PREFERENCE_NAME_ENABLE_AI]: boolean | undefined;
     [PREFERENCE_NAME_PROMPT_TEMPLATES]: string | undefined;
     [PREFERENCE_NAME_REQUEST_SETTINGS]: Array<RequestSetting> | undefined;
     [PREFERENCE_NAME_MAX_RETRIES]: number | undefined;
+    [PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE]: NotificationType | undefined;
 }
 
 export interface RequestSetting {

package/src/browser/frontend-language-model-registry.spec.ts

@@ -0,0 +1,298 @@
+// *****************************************************************************
+// Copyright (C) 2025 EclipseSource.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+let disableJSDOM = enableJSDOM();
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+FrontendApplicationConfigProvider.set({});
+
+import { expect } from 'chai';
+import {
+    LanguageModelRequest,
+    ToolRequest
+} from '../common';
+
+disableJSDOM();
+
+interface ErrorObject {
+    error: boolean;
+    message: string;
+}
+
+function isErrorObject(obj: unknown): obj is ErrorObject {
+    return !!obj && typeof obj === 'object' && 'error' in obj && 'message' in obj;
+}
+
+// This class provides a minimal implementation focused solely on testing the toolCall method.
+// We cannot extend FrontendLanguageModelRegistryImpl directly due to issues in the test environment:
+//   - FrontendLanguageModelRegistryImpl imports dependencies that transitively depend on 'p-queue'
+//   - p-queue is an ESM-only module that cannot be loaded in the current test environment
+class TestableLanguageModelRegistry {
+    private requests = new Map<string, LanguageModelRequest>();
+
+    async toolCall(id: string, toolId: string, arg_string: string): Promise<unknown> {
+        if (!this.requests.has(id)) {
+            return { error: true, message: `No request found for ID '${id}'. The request may have been cancelled or completed.` };
+        }
+        const request = this.requests.get(id)!;
+        const tool = request.tools?.find(t => t.id === toolId);
+        if (tool) {
+            try {
+                return await tool.handler(arg_string);
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return { error: true, message: `Error executing tool '${toolId}': ${errorMessage}` };
+            };
+        }
+        return { error: true, message: `Tool '${toolId}' not found in the available tools for this request.` };
+    }
+
+    // Test helper method
+    setRequest(id: string, request: LanguageModelRequest): void {
+        this.requests.set(id, request);
+    }
+}
+
+describe('FrontendLanguageModelRegistryImpl toolCall functionality', () => {
+    let registry: TestableLanguageModelRegistry;
+
+    before(() => {
+        disableJSDOM = enableJSDOM();
+    });
+
+    after(() => {
+        disableJSDOM();
+    });
+
+    beforeEach(() => {
+        registry = new TestableLanguageModelRegistry();
+    });
+
+    describe('toolCall', () => {
+        it('should return error object when request ID does not exist', async () => {
+            const result = await registry.toolCall('nonexistent-id', 'test-tool', '{}');
+
+            expect(result).to.be.an('object');
+            expect(isErrorObject(result)).to.be.true;
+            if (isErrorObject(result)) {
+                expect(result.error).to.be.true;
+                expect(result.message).to.include('No request found for ID \'nonexistent-id\'');
+                expect(result.message).to.include('The request may have been cancelled or completed');
+            }
+        });
+
+        it('should return error object when tool is not found', async () => {
+            // Set up a request without the requested tool
+            const requestId = 'test-request-id';
+            const mockRequest: LanguageModelRequest = {
+                messages: [],
+                tools: [
+                    {
+                        id: 'different-tool',
+                        name: 'Different Tool',
+                        description: 'A different tool',
+                        parameters: {
+                            type: 'object',
+                            properties: {}
+                        },
+                        handler: () => Promise.resolve('success')
+                    }
+                ]
+            };
+
+            registry.setRequest(requestId, mockRequest);
+
+            const result = await registry.toolCall(requestId, 'nonexistent-tool', '{}');
+
+            expect(result).to.be.an('object');
+            expect(isErrorObject(result)).to.be.true;
+            if (isErrorObject(result)) {
+                expect(result.error).to.be.true;
+                expect(result.message).to.include('Tool \'nonexistent-tool\' not found in the available tools for this request');
+            }
+        });
+
+        it('should call tool handler successfully when tool exists', async () => {
+            const requestId = 'test-request-id';
+            const toolId = 'test-tool';
+            const expectedResult = 'tool execution result';
+
+            const mockTool: ToolRequest = {
+                id: toolId,
+                name: 'Test Tool',
+                description: 'A test tool',
+                parameters: {
+                    type: 'object',
+                    properties: {}
+                },
+                handler: (args: string) => Promise.resolve(expectedResult)
+            };
+
+            const mockRequest: LanguageModelRequest = {
+                messages: [],
+                tools: [mockTool]
+            };
+
+            registry.setRequest(requestId, mockRequest);
+
+            const result = await registry.toolCall(requestId, toolId, '{}');
+
+            expect(result).to.equal(expectedResult);
+        });
+
+        it('should handle synchronous tool handler errors gracefully', async () => {
+            const requestId = 'test-request-id';
+            const toolId = 'error-tool';
+            const errorMessage = 'Tool execution failed';
+
+            const mockTool: ToolRequest = {
+                id: toolId,
+                name: 'Error Tool',
+                description: 'A tool that throws an error',
+                parameters: {
+                    type: 'object',
+                    properties: {}
+                },
+                handler: () => {
+                    throw new Error(errorMessage);
+                }
+            };
+
+            const mockRequest: LanguageModelRequest = {
+                messages: [],
+                tools: [mockTool]
+            };
+
+            registry.setRequest(requestId, mockRequest);
+
+            const result = await registry.toolCall(requestId, toolId, '{}');
+
+            expect(result).to.be.an('object');
+            expect(isErrorObject(result)).to.be.true;
+            if (isErrorObject(result)) {
+                expect(result.error).to.be.true;
+                expect(result.message).to.include(`Error executing tool '${toolId}': ${errorMessage}`);
+            }
+        });
+
+        it('should handle non-Error exceptions gracefully', async () => {
+            const requestId = 'test-request-id';
+            const toolId = 'string-error-tool';
+            const errorMessage = 'String error';
+
+            const mockTool: ToolRequest = {
+                id: toolId,
+                name: 'String Error Tool',
+                description: 'A tool that throws a string',
+                parameters: {
+                    type: 'object',
+                    properties: {}
+                },
+                handler: () => {
+                    // eslint-disable-next-line no-throw-literal
+                    throw errorMessage;
+                }
+            };
+
+            const mockRequest: LanguageModelRequest = {
+                messages: [],
+                tools: [mockTool]
+            };
+
+            registry.setRequest(requestId, mockRequest);
+
+            const result = await registry.toolCall(requestId, toolId, '{}');
+
+            expect(result).to.be.an('object');
+            expect(isErrorObject(result)).to.be.true;
+            if (isErrorObject(result)) {
+                expect(result.error).to.be.true;
+                expect(result.message).to.include(`Error executing tool '${toolId}': ${errorMessage}`);
+            }
+        });
+
+        it('should handle asynchronous tool handler errors gracefully', async () => {
+            const requestId = 'test-request-id';
+            const toolId = 'async-error-tool';
+            const errorMessage = 'Async tool execution failed';
+
+            const mockTool: ToolRequest = {
+                id: toolId,
+                name: 'Async Error Tool',
+                description: 'A tool that returns a rejected promise',
+                parameters: {
+                    type: 'object',
+                    properties: {}
+                },
+                handler: () => Promise.reject(new Error(errorMessage))
+            };
+
+            const mockRequest: LanguageModelRequest = {
+                messages: [],
+                tools: [mockTool]
+            };
+
+            registry.setRequest(requestId, mockRequest);
+
+            const result = await registry.toolCall(requestId, toolId, '{}');
+
+            expect(result).to.be.an('object');
+            expect(isErrorObject(result)).to.be.true;
+            if (isErrorObject(result)) {
+                expect(result.error).to.be.true;
+                expect(result.message).to.include(`Error executing tool '${toolId}': ${errorMessage}`);
+            }
+        });
+
+        it('should handle tool handler with no tools array', async () => {
+            const requestId = 'test-request-id';
+            const mockRequest: LanguageModelRequest = {
+                messages: []
+                // No tools property
+            };
+
+            registry.setRequest(requestId, mockRequest);
+
+            const result = await registry.toolCall(requestId, 'any-tool', '{}');
+
+            expect(result).to.be.an('object');
+            expect(isErrorObject(result)).to.be.true;
+            if (isErrorObject(result)) {
+                expect(result.error).to.be.true;
+                expect(result.message).to.include('Tool \'any-tool\' not found in the available tools for this request');
+            }
+        });
+
+        it('should handle tool handler with empty tools array', async () => {
+            const requestId = 'test-request-id';
+            const mockRequest: LanguageModelRequest = {
+                messages: [],
+                tools: []
+            };
+
+            registry.setRequest(requestId, mockRequest);
+
+            const result = await registry.toolCall(requestId, 'any-tool', '{}');
+
+            expect(result).to.be.an('object');
+            expect(isErrorObject(result)).to.be.true;
+            if (isErrorObject(result)) {
+                expect(result.error).to.be.true;
+                expect(result.message).to.include('Tool \'any-tool\' not found in the available tools for this request');
+            }
+        });
+    });
+});