@theia/ai-core 1.76.0-next.6 → 1.76.0

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

@@ -0,0 +1,86 @@
+// *****************************************************************************
+// Copyright (C) 2026 Safi Seid-Ahmad, K2view 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 { 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 { LanguageModel, ReasoningSettings, ReasoningSupport, UserRequest } from '../common';
+import { PREFERENCE_NAME_REASONING, ReasoningPreferenceEntry } from '../common/ai-core-preferences';
+import { FrontendLanguageModelServiceImpl } from './frontend-language-model-service';
+
+disableJSDOM();
+
+const O_SERIES: ReasoningSupport = { supportedLevels: ['off', 'low', 'medium', 'high', 'auto'], defaultLevel: 'auto' };
+const GPT5: ReasoningSupport = { supportedLevels: ['off', 'minimal', 'low', 'medium', 'high', 'auto'], defaultLevel: 'auto' };
+
+/** Service with the trust check and the reasoning preference entries stubbed; nothing else in `sendRequest` needs a container. */
+function createService(reasoningEntries: ReasoningPreferenceEntry[] = []): FrontendLanguageModelServiceImpl {
+    const service = new FrontendLanguageModelServiceImpl();
+    Object.assign(service, {
+        workspaceTrustService: { getWorkspaceTrust: async () => true },
+        aiConfiguration: { get: <T>(key: string, defaultValue?: T): T | undefined => key === PREFERENCE_NAME_REASONING ? reasoningEntries as unknown as T : defaultValue }
+    });
+    return service;
+}
+
+function createModel(id: string, reasoningSupport: ReasoningSupport | undefined, captured: UserRequest[]): LanguageModel {
+    return {
+        id,
+        reasoningSupport,
+        status: { status: 'ready' },
+        request: async (request: UserRequest) => {
+            captured.push(request);
+            return { text: '' };
+        }
+    } as unknown as LanguageModel;
+}
+
+function createRequest(reasoning?: ReasoningSettings): UserRequest {
+    return { messages: [{ actor: 'user', type: 'text', text: 'hello' }], agentId: 'agent', sessionId: 'session', requestId: 'request', reasoning };
+}
+
+describe('FrontendLanguageModelServiceImpl reasoning level', () => {
+    before(() => disableJSDOM = enableJSDOM());
+    after(() => disableJSDOM());
+
+    it('clamps a session-selected level the model does not support to the nearest supported one', async () => {
+        const captured: UserRequest[] = [];
+        await createService().sendRequest(createModel('openai/o3', O_SERIES, captured), createRequest({ level: 'minimal' }));
+        expect(captured[0].reasoning).to.deep.equal({ level: 'low' });
+    });
+
+    it('clamps a preference-entry level the model does not support', async () => {
+        const captured: UserRequest[] = [];
+        const service = createService([{ scope: { providerId: 'openai' }, reasoning: { level: 'minimal' } }]);
+        await service.sendRequest(createModel('openai/o3', O_SERIES, captured), createRequest());
+        expect(captured[0].reasoning).to.deep.equal({ level: 'low' });
+    });
+
+    it('keeps a level the model supports', async () => {
+        const captured: UserRequest[] = [];
+        await createService().sendRequest(createModel('openai/gpt-5', GPT5, captured), createRequest({ level: 'minimal' }));
+        expect(captured[0].reasoning).to.deep.equal({ level: 'minimal' });
+    });
+
+    it('leaves the level untouched for models without reasoning support', async () => {
+        const captured: UserRequest[] = [];
+        await createService().sendRequest(createModel('openai/gpt-4o', undefined, captured), createRequest({ level: 'high' }));
+        expect(captured[0].reasoning).to.deep.equal({ level: 'high' });
+    });
+});

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

@@ -18,7 +18,7 @@ import { nls } from '@theia/core/lib/common/nls';
 import { inject, injectable } from '@theia/core/shared/inversify';
 import { Prioritizeable } from '@theia/core/lib/common/prioritizeable';
 import { WorkspaceTrustService } from '@theia/workspace/lib/browser/workspace-trust-service';
-import { AiConfigurationService, LanguageModel, LanguageModelResponse, ReasoningSettings, UserRequest } from '../common';
+import { AiConfigurationService, LanguageModel, LanguageModelResponse, ReasoningSettings, ReasoningSupport, UserRequest } from '../common';
 import { LanguageModelServiceImpl } from '../common/language-model-service';
 import {
     PREFERENCE_NAME_REQUEST_SETTINGS,
@@ -76,6 +76,14 @@ export class FrontendLanguageModelServiceImpl extends LanguageModelServiceImpl {
                 languageModelRequest.reasoning = { level: languageModel.reasoningSupport.defaultLevel };
             }
         }
+        // A persisted selection or preference entry can name a level the current model does not accept,
+        // which the provider would otherwise send as-is; clamp it to the model's declared levels.
+        if (languageModelRequest.reasoning && languageModel.reasoningSupport) {
+            const level = ReasoningSupport.clampLevel(languageModel.reasoningSupport, languageModelRequest.reasoning.level);
+            if (level !== languageModelRequest.reasoning.level) {
+                languageModelRequest.reasoning = { ...languageModelRequest.reasoning, level };
+            }
+        }
 
         return super.sendRequest(languageModel, languageModelRequest);
     }

package/src/browser/index.ts

@@ -28,6 +28,9 @@ export * from './ai-view-contribution';
 export * from './frontend-language-model-registry';
 export * from './frontend-language-model-alias-registry';
 export * from './hide-ai-preferences-contribution';
+export * from './model-discovery-status-service';
+export * from './favorite-models-service';
+export * from './discovering-provider-contribution';
 export * from './frontend-variable-service';
 export * from './prompttemplate-contribution';
 export * from './theia-variable-contribution';

package/src/browser/model-discovery-status-service.spec.ts

@@ -0,0 +1,101 @@
+// *****************************************************************************
+// Copyright (C) 2026 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 { expect } from 'chai';
+import { ModelDiscoveryStatus } from '../common/model-discovery-status';
+import { ModelDiscoveryStatusService } from './model-discovery-status-service';
+import { MockLogger } from '@theia/core/lib/common/test/mock-logger';
+
+/** The service logs a failed run, so a bare instance would have no logger to do it with. */
+function createService(): ModelDiscoveryStatusService {
+    return Object.assign(new ModelDiscoveryStatusService(), { logger: new MockLogger() });
+}
+
+describe('ModelDiscoveryStatusService', () => {
+
+    it('registers a provider with an initial idle status', () => {
+        const service = createService();
+        service.registerProvider({ providerId: 'anthropic', label: 'Anthropic', refresh: async () => { } });
+        const status = service.getStatus('anthropic');
+        expect(status?.state).to.equal('idle');
+        expect(status?.label).to.equal('Anthropic');
+    });
+
+    it('merges partial updates and fires onDidChange', () => {
+        const service = createService();
+        service.registerProvider({ providerId: 'anthropic', label: 'Anthropic', refresh: async () => { } });
+
+        const events: ModelDiscoveryStatus[] = [];
+        service.onDidChange(e => events.push(e));
+
+        service.updateStatus('anthropic', { state: 'fetching' });
+        service.updateStatus('anthropic', { state: 'ready', lastFetch: 123, fromCache: false });
+
+        const status = service.getStatus('anthropic');
+        expect(status?.state).to.equal('ready');
+        expect(status?.lastFetch).to.equal(123);
+        // label is carried over from registration.
+        expect(status?.label).to.equal('Anthropic');
+        expect(events.map(e => e.state)).to.deep.equal(['fetching', 'ready']);
+    });
+
+    it('does not reset an existing status when the provider is re-registered', () => {
+        const service = createService();
+        service.registerProvider({ providerId: 'anthropic', label: 'Anthropic', refresh: async () => { } });
+        service.updateStatus('anthropic', { state: 'ready' });
+
+        service.registerProvider({ providerId: 'anthropic', label: 'Anthropic', refresh: async () => { } });
+        expect(service.getStatus('anthropic')?.state).to.equal('ready');
+    });
+
+    it('reports a failure and clears what the previous state offered', () => {
+        const service = createService();
+        service.registerProvider({ providerId: 'copilot', label: 'GitHub Copilot', refresh: async () => { } });
+        service.updateStatus('copilot', {
+            state: 'no-credentials',
+            stateLabel: 'Not signed in',
+            action: { label: 'Sign in', commandId: 'copilot.signIn' }
+        });
+
+        service.reportError('copilot', new Error('the CLI is not talking'));
+
+        const status = service.getStatus('copilot');
+        expect(status?.state).to.equal('error');
+        expect(status?.message).to.equal('the CLI is not talking');
+        // A failure must not keep reading like the state before it.
+        expect(status?.stateLabel).to.equal(undefined);
+        expect(status?.action).to.equal(undefined);
+    });
+
+    it('reports a rejection that is not an error', () => {
+        const service = createService();
+        service.registerProvider({ providerId: 'anthropic', label: 'Anthropic', refresh: async () => { } });
+        service.reportError('anthropic', 'nope');
+        expect(service.getStatus('anthropic')?.message).to.equal('nope');
+    });
+
+    it('delegates refresh to the registered provider', async () => {
+        const service = createService();
+        let refreshed = false;
+        service.registerProvider({ providerId: 'anthropic', label: 'Anthropic', refresh: async () => { refreshed = true; } });
+
+        await service.refresh('anthropic');
+        expect(refreshed).to.be.true;
+
+        // Refreshing an unknown provider is a no-op and does not throw.
+        await service.refresh('unknown');
+    });
+});

package/src/browser/model-discovery-status-service.ts

@@ -0,0 +1,123 @@
+// *****************************************************************************
+// Copyright (C) 2026 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 { Emitter, Event, ILogger } from '@theia/core';
+import { inject, injectable, named } from '@theia/core/shared/inversify';
+import { ModelDiscoveryStatus } from '../common/model-discovery-status';
+
+/**
+ * A provider that participates in dynamic model discovery. Provider frontend contributions
+ * register a descriptor so the UI can display their {@link ModelDiscoveryStatus} and trigger
+ * a manual refresh.
+ */
+export interface ModelDiscoveryProviderDescriptor {
+    readonly providerId: string;
+    readonly label: string;
+    /** Prefix of this provider's registered model ids, if it differs from {@link providerId}. */
+    readonly modelIdPrefix?: string;
+    /** Triggers a manual re-fetch (used by the "Refresh"/"Retry" action). */
+    refresh(): Promise<void>;
+}
+
+/**
+ * Frontend registry of provider-level model-discovery status.
+ *
+ * Provider frontend contributions push their state here as they fetch models; the AI
+ * configuration UI observes {@link onDidChange} to render fetching/error/no-credentials state.
+ * This is the provider-level counterpart to the per-model `LanguageModelStatus`.
+ */
+@injectable()
+export class ModelDiscoveryStatusService {
+
+    @inject(ILogger) @named('ai-core:ModelDiscoveryStatusService')
+    protected readonly logger: ILogger;
+
+    protected readonly descriptors = new Map<string, ModelDiscoveryProviderDescriptor>();
+    protected readonly statuses = new Map<string, ModelDiscoveryStatus>();
+
+    protected readonly onDidChangeEmitter = new Emitter<ModelDiscoveryStatus>();
+    /** Fired whenever a provider's status changes; the argument is the new status. */
+    readonly onDidChange: Event<ModelDiscoveryStatus> = this.onDidChangeEmitter.event;
+
+    /**
+     * Register a provider. Idempotent: re-registering keeps any existing status and only
+     * updates the refresh callback and label.
+     */
+    registerProvider(descriptor: ModelDiscoveryProviderDescriptor): void {
+        this.descriptors.set(descriptor.providerId, descriptor);
+        if (!this.statuses.has(descriptor.providerId)) {
+            this.statuses.set(descriptor.providerId, {
+                providerId: descriptor.providerId,
+                label: descriptor.label,
+                modelIdPrefix: descriptor.modelIdPrefix,
+                state: 'idle'
+            });
+        }
+        this.onDidChangeEmitter.fire(this.statuses.get(descriptor.providerId)!);
+    }
+
+    /**
+     * Update a provider's status. Only the provided fields are changed; the rest are carried
+     * over from the previous status. Passing `undefined` for an optional field explicitly clears it.
+     */
+    updateStatus(providerId: string, update: Partial<Omit<ModelDiscoveryStatus, 'providerId'>>): void {
+        const previous = this.statuses.get(providerId);
+        const next: ModelDiscoveryStatus = {
+            providerId,
+            label: update.label ?? previous?.label ?? providerId,
+            modelIdPrefix: 'modelIdPrefix' in update ? update.modelIdPrefix : previous?.modelIdPrefix,
+            state: update.state ?? previous?.state ?? 'idle',
+            stateLabel: 'stateLabel' in update ? update.stateLabel : previous?.stateLabel,
+            message: 'message' in update ? update.message : previous?.message,
+            lastFetch: 'lastFetch' in update ? update.lastFetch : previous?.lastFetch,
+            fromCache: 'fromCache' in update ? update.fromCache : previous?.fromCache,
+            discovered: 'discovered' in update ? update.discovered : previous?.discovered,
+            action: 'action' in update ? update.action : previous?.action
+        };
+        this.statuses.set(providerId, next);
+        this.onDidChangeEmitter.fire(next);
+    }
+
+    /**
+     * Reports a failed discovery run. Any step of a run can fail, including the ones that only talk to
+     * the backend, and nothing awaits the promise a rejection would travel on: a provider's startup
+     * does not, and a refresh button cannot act on it. What the previous state offered is cleared, so
+     * a failure does not keep reading like the state before it (a badge, a sign-in button).
+     */
+    reportError(providerId: string, error: unknown): void {
+        // A run can also fail on this side of the RPC boundary, where nothing else would record it.
+        this.logger.error(`Model discovery failed for provider '${providerId}':`, error);
+        this.updateStatus(providerId, {
+            state: 'error',
+            stateLabel: undefined,
+            message: error instanceof Error ? error.message : String(error),
+            action: undefined
+        });
+    }
+
+    getStatus(providerId: string): ModelDiscoveryStatus | undefined {
+        return this.statuses.get(providerId);
+    }
+
+    getStatuses(): ModelDiscoveryStatus[] {
+        return [...this.statuses.values()];
+    }
+
+    /** Trigger a manual refresh for the given provider, if it is registered. */
+    async refresh(providerId: string): Promise<void> {
+        await this.descriptors.get(providerId)?.refresh();
+    }
+}

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

@@ -38,6 +38,15 @@ export const AI_CORE_PREFERENCES_TITLE = nls.localize('theia/ai-core/preferences
  */
 export const MODEL_PROVIDER_TYPE_DETAIL = 'aiModelProvider';
 
+/**
+ * Key under a preference's schema `typeDetails` marking a preference that the AI Configuration view
+ * edits through a dedicated control of its own, so it should not also appear as a raw settings row.
+ * The value stays a plain preference, editable in `settings.json` like any other; it is only the
+ * duplicate, less legible editor that is left out. Declare it as
+ * `typeDetails: { [DEDICATED_EDITOR_TYPE_DETAIL]: true }`.
+ */
+export const DEDICATED_EDITOR_TYPE_DETAIL = 'aiDedicatedEditor';
+
 /**
  * Shape a language-model provider stores under a preference's `typeDetails[MODEL_PROVIDER_TYPE_DETAIL]`
  * to describe its `ai-features.<provider>.*` block to the AI Configuration view's Models page. Declared
@@ -51,6 +60,8 @@ export const PREFERENCE_NAME_PROMPT_TEMPLATES = 'ai-features.promptTemplates.pro
 export const PREFERENCE_NAME_REQUEST_SETTINGS = 'ai-features.modelSettings.requestSettings';
 export const PREFERENCE_NAME_REASONING = 'ai-features.reasoning.defaults';
 export const PREFERENCE_NAME_MAX_RETRIES = 'ai-features.modelSettings.maxRetries';
+export const PREFERENCE_NAME_FAVORITE_MODELS = 'ai-features.modelSettings.favoriteModels';
+export const PREFERENCE_NAME_HIDDEN_MODELS = 'ai-features.modelSettings.hiddenModels';
 export const PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE = 'ai-features.notifications.default';
 export const PREFERENCE_NAME_SKILL_DIRECTORIES = 'ai-features.skills.skillDirectories';
 export const PREFERENCE_NAME_SERVER_SIDE_COMPACTION = 'ai-features.chat.serverSideCompaction';
@@ -169,6 +180,34 @@ export const aiCorePreferenceSchema: PreferenceSchema = {
             minimum: 0,
             default: 3
         },
+        [PREFERENCE_NAME_FAVORITE_MODELS]: {
+            title: nls.localize('theia/ai/core/favoriteModels/title', 'Favorite Models'),
+            markdownDescription: nls.localize('theia/ai/core/favoriteModels/mdDescription',
+                'Models the AI chat input\'s model picker shows in addition to the newest ones of each provider, as fully qualified ids '
+                + '(e.g. `anthropic/claude-opus-5`). This is for keeping an older or release-pinned model at hand. Check a model on its '
+                + 'provider\'s page in the AI Configuration view to add it.'),
+            type: 'array',
+            // The provider pages check models one by one; a second, raw editor for the same ids would
+            // invite typos and disagree with what the checks say.
+            typeDetails: { [DEDICATED_EDITOR_TYPE_DETAIL]: true },
+            items: {
+                type: 'string'
+            },
+            default: []
+        },
+        [PREFERENCE_NAME_HIDDEN_MODELS]: {
+            title: nls.localizeByDefault('Hidden Models'),
+            markdownDescription: nls.localize('theia/ai/core/hiddenModels/mdDescription',
+                'Models the AI chat input\'s model picker does not show even though it would by default, as fully qualified ids '
+                + '(e.g. `google/gemini-flash-lite-latest`). Only the models shown without being listed as a favorite end up here, '
+                + 'i.e. the newest ones of a provider. Uncheck a model on its provider\'s page in the AI Configuration view to add it.'),
+            type: 'array',
+            typeDetails: { [DEDICATED_EDITOR_TYPE_DETAIL]: true },
+            items: {
+                type: 'string'
+            },
+            default: []
+        },
         [PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE]: {
             title: nls.localize('theia/ai/core/defaultNotification/title', 'Default Notification Type'),
             markdownDescription: nls.localize('theia/ai/core/defaultNotification/mdDescription',
@@ -276,6 +315,7 @@ export interface AICoreConfiguration {
     [PREFERENCE_NAME_REQUEST_SETTINGS]: Array<RequestSetting> | undefined;
     [PREFERENCE_NAME_REASONING]: Array<ReasoningPreferenceEntry> | undefined;
     [PREFERENCE_NAME_MAX_RETRIES]: number | undefined;
+    [PREFERENCE_NAME_FAVORITE_MODELS]: string[] | undefined;
     [PREFERENCE_NAME_DEFAULT_NOTIFICATION_TYPE]: NotificationType | undefined;
     [PREFERENCE_NAME_SKILL_DIRECTORIES]: string[] | undefined;
     [PREFERENCE_NAME_SERVER_SIDE_COMPACTION]: boolean | undefined;

package/src/common/index.ts

@@ -22,6 +22,8 @@ export * from './language-model-delegate';
 export * from './language-model-util';
 export * from './language-model';
 export * from './language-model-alias';
+export * from './model-discovery-status';
+export * from './model-discovery-util';
 export * from './prompt-service';
 export * from './prompt-service-util';
 export * from './proxy-util';

package/src/common/language-model-ordering.spec.ts

@@ -0,0 +1,83 @@
+// *****************************************************************************
+// Copyright (C) 2026 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 { expect } from 'chai';
+import { LanguageModelMetaData } from './language-model';
+import { compareModelsByRecency, groupModelsByProvider, providerOf } from './language-model-util';
+
+function model(id: string, released?: number, vendor?: string): LanguageModelMetaData {
+    return { id, released, vendor, status: { status: 'ready' } };
+}
+
+describe('compareModelsByRecency', () => {
+
+    it('puts the most recently released model first', () => {
+        const sorted = [
+            model('anthropic/claude-haiku-4-5', Date.parse('2025-10-01')),
+            model('anthropic/claude-opus-5', Date.parse('2026-04-01'))
+        ].sort(compareModelsByRecency);
+        expect(sorted.map(entry => entry.id)).to.deep.equal(['anthropic/claude-opus-5', 'anthropic/claude-haiku-4-5']);
+    });
+
+    it('falls back to the id when no release date is reported, as for Gemini', () => {
+        const sorted = [model('google/gemini-3.7-flash'), model('google/gemini-3.1-pro')].sort(compareModelsByRecency);
+        expect(sorted.map(entry => entry.id)).to.deep.equal(['google/gemini-3.1-pro', 'google/gemini-3.7-flash']);
+    });
+
+    it('sorts a model without a reported date after the dated ones rather than to the top', () => {
+        const sorted = [
+            model('openai/undated'),
+            model('openai/dated', Date.parse('2020-01-01'))
+        ].sort(compareModelsByRecency);
+        expect(sorted.map(entry => entry.id)).to.deep.equal(['openai/dated', 'openai/undated']);
+    });
+});
+
+describe('providerOf', () => {
+
+    it('prefers the declared vendor', () => {
+        expect(providerOf(model('openai/gpt-5.5', undefined, 'openai'))).to.equal('openai');
+    });
+
+    it('falls back to the id prefix', () => {
+        expect(providerOf(model('anthropic/claude-opus-5'))).to.equal('anthropic');
+    });
+
+    it('yields an empty provider for an unprefixed id, e.g. a custom endpoint', () => {
+        expect(providerOf(model('my-local-model'))).to.equal('');
+    });
+});
+
+describe('groupModelsByProvider', () => {
+
+    it('groups by provider, ordering the groups by name and their models by recency', () => {
+        const groups = groupModelsByProvider([
+            model('openai/gpt-5.5', Date.parse('2025-08-01')),
+            model('anthropic/claude-haiku-4-5', Date.parse('2025-10-01')),
+            model('openai/gpt-5.6-sol', Date.parse('2026-02-01')),
+            model('anthropic/claude-opus-5', Date.parse('2026-04-01'))
+        ]);
+        expect(groups.map(group => group.provider)).to.deep.equal(['anthropic', 'openai']);
+        expect(groups[0].models.map(entry => entry.id)).to.deep.equal(['anthropic/claude-opus-5', 'anthropic/claude-haiku-4-5']);
+        expect(groups[1].models.map(entry => entry.id)).to.deep.equal(['openai/gpt-5.6-sol', 'openai/gpt-5.5']);
+    });
+
+    it('leaves the input untouched', () => {
+        const models = [model('b/second'), model('a/first')];
+        groupModelsByProvider(models);
+        expect(models.map(entry => entry.id)).to.deep.equal(['b/second', 'a/first']);
+    });
+});

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

@@ -19,6 +19,7 @@ import {
     isLanguageModelStreamResponse,
     isLanguageModelTextResponse,
     isTextResponsePart,
+    LanguageModelMetaData,
     LanguageModelResponse,
     ToolRequest
 } from './language-model';
@@ -80,3 +81,45 @@ export const getJsonOfText = (text: string): unknown => {
 };
 
 export const toolRequestToPromptText = (toolRequest: ToolRequest): string => `${toolRequest.id}`;
+
+/**
+ * Orders models for the lists a user picks from: newest first, since a provider's newest model is
+ * almost always the one being looked for, with the id as the tie-break so that models whose provider
+ * reports no release date (Gemini reports none) still come out in a stable, readable order.
+ */
+export const compareModelsByRecency = (left: LanguageModelMetaData, right: LanguageModelMetaData): number => {
+    if (left.released !== right.released) {
+        // A model without a reported date sorts after the dated ones rather than to the top.
+        return (right.released ?? 0) - (left.released ?? 0);
+    }
+    return left.id.localeCompare(right.id);
+};
+
+/**
+ * The provider a model belongs to: its declared vendor, falling back to the `<provider>/` prefix of
+ * its id. Used to group the model lists so that a provider's models stay together.
+ */
+export const providerOf = (model: LanguageModelMetaData): string => {
+    if (model.vendor) {
+        return model.vendor;
+    }
+    const separator = model.id.indexOf('/');
+    return separator > 0 ? model.id.substring(0, separator) : '';
+};
+
+/** Groups models by {@link providerOf}, each group ordered by {@link compareModelsByRecency}, groups by provider name. */
+export const groupModelsByProvider = <T extends LanguageModelMetaData>(models: T[]): Array<{ provider: string; models: T[] }> => {
+    const groups = new Map<string, T[]>();
+    for (const model of models) {
+        const provider = providerOf(model);
+        const group = groups.get(provider);
+        if (group) {
+            group.push(model);
+        } else {
+            groups.set(provider, [model]);
+        }
+    }
+    return [...groups.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([provider, grouped]) => ({ provider, models: grouped.slice().sort(compareModelsByRecency) }));
+};

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

@@ -24,9 +24,11 @@ import {
     isToolCallHtmlAppResult,
     LanguageModel,
     LanguageModelSelector,
+    ReasoningSupport,
     resolveCompactionDefault,
     resolveCompactionTokenThreshold,
     resolveCompactionTokenThresholdDefault,
+    resolveCustomModelHeaders,
     resolveServerSideCompaction
 } from './language-model';
 
@@ -260,6 +262,19 @@ describe('compaction contract', () => {
         expect(resolveServerSideCompaction(true, false, { enabled: true })).to.equal(true);
         expect(resolveServerSideCompaction(true, true, { enabled: false })).to.equal(false);
     });
+    it('resolves custom model headers, ignoring non-string and non-object values', () => {
+        expect(resolveCustomModelHeaders({ 'X-Audit-User': 'theia' })).to.deep.equal({ 'X-Audit-User': 'theia' });
+        // keys are sorted, so reordering the entries in the preference is not a change
+        expect(Object.keys(resolveCustomModelHeaders({ 'X-B': '2', 'X-A': '1' })!)).to.deep.equal(['X-A', 'X-B']);
+        // entries with a non-string value are dropped, the remaining ones are kept
+        expect(resolveCustomModelHeaders({ 'X-Audit-User': 'theia', 'X-Count': 5 })).to.deep.equal({ 'X-Audit-User': 'theia' });
+        // nothing usable -> undefined, so the default request headers stay untouched
+        expect(resolveCustomModelHeaders({ 'X-Count': 5 })).to.equal(undefined);
+        expect(resolveCustomModelHeaders({})).to.equal(undefined);
+        expect(resolveCustomModelHeaders(undefined)).to.equal(undefined);
+        expect(resolveCustomModelHeaders('X-Audit-User: theia')).to.equal(undefined);
+        expect(resolveCustomModelHeaders([['X-Audit-User', 'theia']])).to.equal(undefined);
+    });
 });
 
 describe('isToolCallHtmlAppResult', () => {
@@ -343,3 +358,33 @@ describe('isToolCallHtmlAppResult', () => {
         expect(isToolCallHtmlAppResult({ type: 'html', html, title: 'Animated Unit Test Sandbox' })).to.be.true;
     });
 });
+
+describe('ReasoningSupport.clampLevel', () => {
+    const oSeries: ReasoningSupport = { supportedLevels: ['off', 'low', 'medium', 'high', 'auto'], defaultLevel: 'auto' };
+
+    it('returns a supported level unchanged', () => {
+        expect(ReasoningSupport.clampLevel(oSeries, 'medium')).to.equal('medium');
+        expect(ReasoningSupport.clampLevel(oSeries, 'auto')).to.equal('auto');
+    });
+
+    it('raises an unsupported minimal to low rather than lowering it to off', () => {
+        expect(ReasoningSupport.clampLevel(oSeries, 'minimal')).to.equal('low');
+    });
+
+    it('lowers an unsupported level when nothing higher is supported', () => {
+        expect(ReasoningSupport.clampLevel({ supportedLevels: ['off', 'low', 'medium'] }, 'high')).to.equal('medium');
+    });
+
+    it('raises an unsupported off to the lowest supported effort', () => {
+        expect(ReasoningSupport.clampLevel({ supportedLevels: ['low', 'high'] }, 'off')).to.equal('low');
+    });
+
+    it('resolves an unsupported auto to the default level, then to the first supported level', () => {
+        expect(ReasoningSupport.clampLevel({ supportedLevels: ['low', 'high'], defaultLevel: 'high' }, 'auto')).to.equal('high');
+        expect(ReasoningSupport.clampLevel({ supportedLevels: ['low', 'high'] }, 'auto')).to.equal('low');
+    });
+
+    it('returns the level unchanged when the model declares no levels', () => {
+        expect(ReasoningSupport.clampLevel({ supportedLevels: [] }, 'minimal')).to.equal('minimal');
+    });
+});