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

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

@@ -1,5 +1,5 @@
 // *****************************************************************************
-// Copyright (C) 2024 EclipseSource GmbH.
+// 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
@@ -43,6 +43,7 @@ import {
     LanguageModelResponse,
     LanguageModelSelector,
     LanguageModelStreamResponsePart,
+    ToolCallResult,
 } from '../common';
 
 @injectable()
@@ -58,7 +59,7 @@ export class LanguageModelDelegateClientImpl
         this.receiver.send(id, token);
     }
 
-    toolCall(requestId: string, toolId: string, args_string: string): Promise<unknown> {
+    toolCall(requestId: string, toolId: string, args_string: string): Promise<ToolCallResult> {
         return this.receiver.toolCall(requestId, toolId, args_string);
     }
 
@@ -236,8 +237,8 @@ export class FrontendLanguageModelRegistryImpl
         };
     }
 
-    private streams = new Map<string, StreamState>();
-    private requests = new Map<string, LanguageModelRequest>();
+    protected streams = new Map<string, StreamState>();
+    protected requests = new Map<string, LanguageModelRequest>();
 
     async *getIterable(
         state: StreamState
@@ -281,16 +282,21 @@ export class FrontendLanguageModelRegistryImpl
     }
 
     // called by backend once tool is invoked
-    toolCall(id: string, toolId: string, arg_string: string): Promise<unknown> {
+    async toolCall(id: string, toolId: string, arg_string: string): Promise<ToolCallResult> {
         if (!this.requests.has(id)) {
-            throw new Error('Somehow we got a callback for a non existing request!');
+            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) {
-            return tool.handler(arg_string);
+            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}` };
+            };
         }
-        throw new Error(`Could not find a tool for ${toolId}!`);
+        return { error: true, message: `Tool '${toolId}' not found in the available tools for this request.` };
     }
 
     // called by backend via the "delegate client" with the error to use for rejection

package/src/browser/index.ts

@@ -14,7 +14,11 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
+export * from './agent-completion-notification-service';
+export * from './os-notification-service';
+export * from './window-blink-service';
 export * from './ai-activation-service';
+export * from './ai-command-handler-factory';
 export * from './ai-core-frontend-application-contribution';
 export * from './ai-core-frontend-module';
 export * from './ai-core-preferences';

package/src/browser/os-notification-service.ts

@@ -0,0 +1,271 @@
+// *****************************************************************************
+// 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 } from '@theia/core/shared/inversify';
+import { nls } from '@theia/core/lib/common/nls';
+import { environment } from '@theia/core';
+
+/**
+ * Configuration options for OS notifications
+ */
+export interface OSNotificationOptions {
+    /** The notification body text */
+    body?: string;
+    /** Icon to display with the notification */
+    icon?: string;
+    /** Whether the notification should be silent */
+    silent?: boolean;
+    /** Tag to group notifications */
+    tag?: string;
+    /** Whether the notification requires user interaction to dismiss */
+    requireInteraction?: boolean;
+    /** Custom data to associate with the notification */
+    data?: unknown;
+}
+
+/**
+ * Result of an OS notification attempt
+ */
+export interface OSNotificationResult {
+    /** Whether the notification was successfully shown */
+    success: boolean;
+    /** Error message if the notification failed */
+    error?: string;
+    /** The created notification instance (if successful) */
+    notification?: Notification;
+}
+
+/**
+ * Service to handle OS-level notifications across different platforms
+ * Provides fallback mechanisms for environments where notifications are unavailable
+ */
+@injectable()
+export class OSNotificationService {
+
+    private isElectron: boolean;
+
+    constructor() {
+        this.isElectron = environment.electron.is();
+    }
+
+    /**
+     * Show an OS-level notification with the given title and options
+     *
+     * @param title The notification title
+     * @param options Optional notification configuration
+     * @returns Promise resolving to the notification result
+     */
+    async showNotification(title: string, options: OSNotificationOptions = {}): Promise<OSNotificationResult> {
+        try {
+            if (!this.isNotificationSupported()) {
+                return {
+                    success: false,
+                    error: 'Notifications are not supported in this environment'
+                };
+            }
+
+            const permission = await this.ensurePermission();
+            if (permission !== 'granted') {
+                return {
+                    success: false,
+                    error: `Notification permission ${permission}`
+                };
+            }
+
+            const notification = await this.createNotification(title, options);
+            return {
+                success: true,
+                notification
+            };
+
+        } catch (error) {
+            console.error('Failed to show OS notification:', error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error occurred'
+            };
+        }
+    }
+
+    /**
+     * Check if notification permission is granted
+     *
+     * @returns The current notification permission state
+     */
+    getPermissionStatus(): NotificationPermission {
+        if (!this.isNotificationSupported()) {
+            return 'denied';
+        }
+        return Notification.permission;
+    }
+
+    /**
+     * Request notification permission from the user
+     *
+     * @returns Promise resolving to the permission state
+     */
+    async requestPermission(): Promise<NotificationPermission> {
+        if (!this.isNotificationSupported()) {
+            return 'denied';
+        }
+
+        if (Notification.permission !== 'default') {
+            return Notification.permission;
+        }
+
+        try {
+            const permission = await Notification.requestPermission();
+            return permission;
+        } catch (error) {
+            console.error('Failed to request notification permission:', error);
+            return 'denied';
+        }
+    }
+
+    /**
+     * Check if OS notifications are supported in the current environment
+     *
+     * @returns true if notifications are supported, false otherwise
+     */
+    isNotificationSupported(): boolean {
+        return typeof window !== 'undefined' && 'Notification' in window;
+    }
+
+    /**
+     * Show a notification specifically for agent completion
+     * This is a convenience method with pre-configured options for agent notifications
+     *
+     * @param agentName The name of the agent that completed
+     * @param taskDescription Optional description of the completed task
+     * @returns Promise resolving to the notification result
+     */
+    async showAgentCompletionNotification(agentName: string, taskDescription?: string): Promise<OSNotificationResult> {
+        const title = nls.localize('theia/ai-core/agentCompletionTitle', 'Agent "{0}" Task Completed', agentName);
+        const body = 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);
+
+        return this.showNotification(title, {
+            body,
+            icon: this.getAgentCompletionIcon(),
+            tag: `agent-completion-${agentName}`,
+            requireInteraction: false,
+            data: {
+                type: 'agent-completion',
+                agentName,
+                taskDescription,
+                timestamp: Date.now()
+            }
+        });
+    }
+
+    /**
+     * Ensure notification permission is granted
+     *
+     * @returns Promise resolving to the permission state
+     */
+    private async ensurePermission(): Promise<NotificationPermission> {
+        const currentPermission = this.getPermissionStatus();
+
+        if (currentPermission === 'granted') {
+            return currentPermission;
+        }
+
+        if (currentPermission === 'denied') {
+            return currentPermission;
+        }
+
+        return this.requestPermission();
+    }
+
+    /**
+     * Create a native notification with the given title and options
+     *
+     * @param title The notification title
+     * @param options The notification options
+     * @returns Promise resolving to the created notification
+     */
+    private async createNotification(title: string, options: OSNotificationOptions): Promise<Notification> {
+        return new Promise<Notification>((resolve, reject): void => {
+            try {
+                const notificationOptions: NotificationOptions = {
+                    body: options.body,
+                    icon: options.icon,
+                    silent: options.silent,
+                    tag: options.tag,
+                    requireInteraction: options.requireInteraction,
+                    data: options.data
+                };
+
+                const notification = new Notification(title, notificationOptions);
+
+                notification.onshow = () => {
+                    console.debug('OS notification shown:', title);
+                };
+
+                notification.onerror = error => {
+                    console.error('OS notification error:', error);
+                    reject(new Error('Failed to show notification'));
+                };
+
+                notification.onclick = () => {
+                    console.debug('OS notification clicked:', title);
+                    this.focusApplicationWindow();
+                    notification.close();
+                };
+
+                notification.onclose = () => {
+                    console.debug('OS notification closed:', title);
+                };
+
+                resolve(notification);
+
+            } catch (error) {
+                reject(error);
+            }
+        });
+    }
+
+    /**
+     * Attempt to focus the application window when notification is clicked
+     */
+    private focusApplicationWindow(): void {
+        try {
+            if (typeof window !== 'undefined') {
+                window.focus();
+
+                if (this.isElectron && (window as unknown as { electronTheiaCore?: { focusWindow?: () => void } }).electronTheiaCore?.focusWindow) {
+                    (window as unknown as { electronTheiaCore: { focusWindow: () => void } }).electronTheiaCore.focusWindow();
+                }
+            }
+        } catch (error) {
+            console.debug('Could not focus application window:', error);
+        }
+    }
+
+    /**
+     * Get the icon URL for agent completion notifications
+     *
+     * @returns The icon URL or undefined if not available
+     */
+    private getAgentCompletionIcon(): string | undefined {
+        // This could return a path to an icon file
+        // For now, we'll return undefined to use the default system icon
+        return undefined;
+    }
+}

package/src/browser/window-blink-service.ts

@@ -0,0 +1,195 @@
+// *****************************************************************************
+// 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 } from '@theia/core/shared/inversify';
+import { environment } from '@theia/core';
+
+/**
+ * Result of a window blink attempt
+ */
+export interface WindowBlinkResult {
+    /** Whether the window blink was successful */
+    success: boolean;
+    /** Error message if the blink failed */
+    error?: string;
+}
+
+/**
+ * Service for blinking/flashing the application window to get user attention.
+ */
+@injectable()
+export class WindowBlinkService {
+
+    private isElectron: boolean;
+
+    constructor() {
+        this.isElectron = environment.electron.is();
+    }
+
+    /**
+     * Blink/flash the window to get user attention.
+     * The implementation varies depending on the platform and environment.
+     *
+     * @param agentName Optional name of the agent to include in the blink notification
+     */
+    async blinkWindow(agentName?: string): Promise<WindowBlinkResult> {
+        try {
+            if (this.isElectron) {
+                await this.blinkElectronWindow(agentName);
+            } else {
+                await this.blinkBrowserWindow(agentName);
+            }
+            return { success: true };
+        } catch (error) {
+            console.warn('Failed to blink window:', error);
+            try {
+                if (document.hidden) {
+                    this.focusWindow();
+                }
+                return { success: true };
+            } catch (fallbackError) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Failed to blink window'
+                };
+            }
+        }
+    }
+
+    private async blinkElectronWindow(agentName?: string): Promise<void> {
+        await this.blinkDocumentTitle(agentName);
+
+        if (document.hidden) {
+            try {
+                const theiaCoreAPI = (window as unknown as { electronTheiaCore?: { focusWindow?: () => void } }).electronTheiaCore;
+                if (theiaCoreAPI?.focusWindow) {
+                    theiaCoreAPI.focusWindow();
+                } else {
+                    window.focus();
+                }
+            } catch (error) {
+                console.debug('Could not focus hidden window:', error);
+            }
+        }
+    }
+
+    private async blinkBrowserWindow(agentName?: string): Promise<void> {
+        await this.blinkDocumentTitle(agentName);
+        this.blinkWithVisibilityAPI();
+        if (document.hidden) {
+            this.focusWindow();
+        }
+    }
+
+    private async blinkDocumentTitle(agentName?: string): Promise<void> {
+        const originalTitle = document.title;
+        const alertTitle = agentName
+            ? `🔔 Theia - Agent "${agentName}" Completed`
+            : '🔔 Theia - Agent Completed';
+
+        let blinkCount = 0;
+        const maxBlinks = 6;
+
+        const blinkInterval = setInterval(() => {
+            if (blinkCount >= maxBlinks) {
+                clearInterval(blinkInterval);
+                document.title = originalTitle;
+                return;
+            }
+
+            document.title = blinkCount % 2 === 0 ? alertTitle : originalTitle;
+            blinkCount++;
+        }, 500);
+    }
+
+    private blinkWithVisibilityAPI(): void {
+        // This method provides visual attention-getting behavior without creating notifications
+        // as notifications are handled by the OSNotificationService to avoid duplicates
+        if (!this.isElectron && typeof document.hidden !== 'undefined') {
+            // Focus the window if it's hidden to get user attention
+            if (document.hidden) {
+                this.focusWindow();
+            }
+        }
+    }
+
+    private focusWindow(): void {
+        try {
+            window.focus();
+
+            // Try to scroll to top to create some visual movement
+            if (document.body.scrollTop > 0 || document.documentElement.scrollTop > 0) {
+                const currentScroll = document.documentElement.scrollTop || document.body.scrollTop;
+                window.scrollTo(0, 0);
+                setTimeout(() => {
+                    window.scrollTo(0, currentScroll);
+                }, 100);
+            }
+        } catch (error) {
+            console.debug('Could not focus window:', error);
+        }
+    }
+
+    /**
+     * Check if window blinking is supported in the current environment.
+     */
+    isBlinkSupported(): boolean {
+        if (this.isElectron) {
+            const theiaCoreAPI = (window as unknown as { electronTheiaCore?: { focusWindow?: () => void } }).electronTheiaCore;
+            return !!(theiaCoreAPI?.focusWindow);
+        }
+
+        // In browser, we can always provide some form of attention-getting behavior
+        return true;
+    }
+
+    /**
+     * Get information about the blinking capabilities.
+     */
+    getBlinkCapabilities(): {
+        supported: boolean;
+        method: 'electron' | 'browser' | 'none';
+        features: string[];
+    } {
+        const features: string[] = [];
+        let method: 'electron' | 'browser' | 'none' = 'none';
+
+        if (this.isElectron) {
+            method = 'electron';
+            const theiaCoreAPI = (window as unknown as { electronTheiaCore?: { focusWindow?: () => void } }).electronTheiaCore;
+
+            if (theiaCoreAPI?.focusWindow) {
+                features.push('electronTheiaCore.focusWindow');
+                features.push('document.title blinking');
+                features.push('window.focus');
+            }
+        } else {
+            method = 'browser';
+            features.push('document.title');
+            features.push('window.focus');
+
+            if (typeof document.hidden !== 'undefined') {
+                features.push('Page Visibility API');
+            }
+        }
+
+        return {
+            supported: features.length > 0,
+            method,
+            features
+        };
+    }
+}

package/src/common/configurable-in-memory-resources.ts

@@ -89,6 +89,10 @@ export class ConfigurableMutableResource implements Resource {
         return !!this.options?.initiallyDirty;
     }
 
+    get contents(): string | Promise<string> {
+        return this.options?.contents ?? '';
+    }
+
     readContents(): Promise<string> {
         return Promise.resolve(this.options?.contents ?? '');
     }
@@ -153,4 +157,8 @@ export class ConfigurableMutableReferenceResource implements Resource {
     get autosaveable(): boolean {
         return this.reference.object.autosaveable;
     }
+
+    get contents(): string | Promise<string> {
+        return this.reference.object.contents;
+    }
 }

package/src/common/index.ts

@@ -31,3 +31,4 @@ export * from './language-model-service';
 export * from './token-usage-service';
 export * from './ai-variable-resource';
 export * from './configurable-in-memory-resources';
+export * from './notification-types';

package/src/common/language-model-delegate.ts

@@ -15,11 +15,14 @@
 // *****************************************************************************
 
 import { CancellationToken } from '@theia/core';
-import { LanguageModelMetaData, LanguageModelParsedResponse, LanguageModelRequest, LanguageModelStreamResponsePart, LanguageModelTextResponse } from './language-model';
+import {
+    LanguageModelMetaData, LanguageModelParsedResponse, LanguageModelRequest, LanguageModelStreamResponsePart,
+    LanguageModelTextResponse, ToolCallResult
+} from './language-model';
 
 export const LanguageModelDelegateClient = Symbol('LanguageModelDelegateClient');
 export interface LanguageModelDelegateClient {
-    toolCall(requestId: string, toolId: string, args_string: string): Promise<unknown>;
+    toolCall(requestId: string, toolId: string, args_string: string): Promise<ToolCallResult>;
     send(id: string, token: LanguageModelStreamResponsePart | undefined): void;
     error(id: string, error: Error): void;
 }

package/src/common/language-model.ts

@@ -55,7 +55,7 @@ export interface ToolResultMessage {
     tool_use_id: string;
     name: string;
     type: 'tool_result';
-    content?: string;
+    content?: ToolCallResult;
     is_error?: boolean;
 }
 
@@ -109,7 +109,7 @@ export interface ToolRequest {
     name: string;
     parameters: ToolRequestParameters
     description?: string;
-    handler: (arg_string: string, ctx?: unknown) => Promise<unknown>;
+    handler: (arg_string: string, ctx?: unknown) => Promise<ToolCallResult>;
     providerName?: string;
 }
 
@@ -245,6 +245,15 @@ export interface ThinkingResponsePart {
 export const isThinkingResponsePart = (part: unknown): part is ThinkingResponsePart =>
     !!(part && typeof part === 'object' && 'thought' in part && typeof part.thought === 'string');
 
+export interface ToolCallTextResult { type: 'text', text: string; };
+export interface ToolCallImageResult extends Base64ImageContent { type: 'image' };
+export interface ToolCallAudioResult { type: 'audio', data: string; mimeType: string };
+export interface ToolCallErrorResult { type: 'error', data: string; };
+export type ToolCallContentResult = ToolCallTextResult | ToolCallImageResult | ToolCallAudioResult | ToolCallErrorResult;
+export interface ToolCallContent {
+    content: ToolCallContentResult[];
+}
+export type ToolCallResult = undefined | object | string | ToolCallContent;
 export interface ToolCall {
     id?: string;
     function?: {
@@ -252,7 +261,7 @@ export interface ToolCall {
         name?: string;
     },
     finished?: boolean;
-    result?: string;
+    result?: ToolCallResult;
 }
 
 export interface LanguageModelStreamResponse {

package/src/common/notification-types.ts

@@ -0,0 +1,31 @@
+// *****************************************************************************
+// 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
+// *****************************************************************************
+
+export const NOTIFICATION_TYPE_OFF = 'off';
+export const NOTIFICATION_TYPE_OS_NOTIFICATION = 'os-notification';
+export const NOTIFICATION_TYPE_MESSAGE = 'message';
+export const NOTIFICATION_TYPE_BLINK = 'blink';
+export type NotificationType =
+    | typeof NOTIFICATION_TYPE_OFF
+    | typeof NOTIFICATION_TYPE_OS_NOTIFICATION
+    | typeof NOTIFICATION_TYPE_MESSAGE
+    | typeof NOTIFICATION_TYPE_BLINK;
+export const NOTIFICATION_TYPES: NotificationType[] = [
+    NOTIFICATION_TYPE_OFF,
+    NOTIFICATION_TYPE_OS_NOTIFICATION,
+    NOTIFICATION_TYPE_MESSAGE,
+    NOTIFICATION_TYPE_BLINK,
+];

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

@@ -22,7 +22,8 @@ import { PromptService, PromptServiceImpl } from './prompt-service';
 import { DefaultAIVariableService, AIVariableService } from './variable-service';
 import { ToolInvocationRegistry } from './tool-invocation-registry';
 import { ToolRequest } from './language-model';
-import { Logger } from '@theia/core';
+import { MockLogger } from '@theia/core/lib/common/test/mock-logger';
+import { ILogger, Logger } from '@theia/core';
 import * as sinon from 'sinon';
 
 describe('PromptService', () => {
@@ -40,6 +41,7 @@ describe('PromptService', () => {
             resolve: async () => ({ variable: nameVariable, value: 'Jane' })
         });
         container.bind<AIVariableService>(AIVariableService).toConstantValue(variableService);
+        container.bind<ILogger>(ILogger).toConstantValue(new MockLogger);
 
         promptService = container.get<PromptService>(PromptService);
         promptService.addBuiltInPromptFragment({ id: '1', template: 'Hello, {{name}}!' });
@@ -340,6 +342,7 @@ describe('PromptService', () => {
             })
         });
         container.bind<AIVariableService>(AIVariableService).toConstantValue(variableService);
+        container.bind<ILogger>(ILogger).toConstantValue(new MockLogger);
 
         const testPromptService = container.get<PromptService>(PromptService);
         testPromptService.addBuiltInPromptFragment({ id: 'testPrompt', template: 'Template with fragment: {{fragment}}' });