@theia/ai-core 1.76.0-next.23 → 1.76.0-next.33

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

@@ -0,0 +1,95 @@
+// *****************************************************************************
+// 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';
+
+describe('ModelDiscoveryStatusService', () => {
+
+    it('registers a provider with an initial idle status', () => {
+        const service = new ModelDiscoveryStatusService();
+        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 = new ModelDiscoveryStatusService();
+        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 = new ModelDiscoveryStatusService();
+        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 = new ModelDiscoveryStatusService();
+        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 = new ModelDiscoveryStatusService();
+        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 = new ModelDiscoveryStatusService();
+        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,118 @@
+// *****************************************************************************
+// 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 } from '@theia/core';
+import { injectable } 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 {
+
+    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 {
+        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

@@ -27,6 +27,7 @@ import {
     resolveCompactionDefault,
     resolveCompactionTokenThreshold,
     resolveCompactionTokenThresholdDefault,
+    resolveCustomModelHeaders,
     resolveServerSideCompaction
 } from './language-model';
 
@@ -260,6 +261,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', () => {

package/src/common/language-model.ts

@@ -319,6 +319,23 @@ export namespace ToolRequest {
             (!('required' in obj) || (Array.isArray(obj.required) && obj.required.every(prop => typeof prop === 'string')));
     }
 }
+
+/**
+ * Resolves the `headers` attribute of a custom model preference entry. Since preferences are
+ * user-authored JSON, entries with a non-string value are dropped. Returns `undefined` when no
+ * usable header remains, so that the default request headers are left untouched. The keys are
+ * sorted, so equal header maps stringify identically regardless of their order in the preference.
+ */
+export function resolveCustomModelHeaders(headers: unknown): Record<string, string> | undefined {
+    if (typeof headers !== 'object' || !headers || Array.isArray(headers)) {
+        return undefined;
+    }
+    const resolved = Object.entries(headers)
+        .filter((entry): entry is [string, string] => typeof entry[1] === 'string')
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return resolved.length > 0 ? Object.fromEntries(resolved) : undefined;
+}
+
 // Anthropic requires at least 50,000 tokens, so use one conservative minimum for all compaction settings.
 export const SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD_MINIMUM = 50_000;
 
@@ -650,6 +667,11 @@ export interface LanguageModelMetaData {
     readonly family?: string;
     readonly maxInputTokens?: number;
     readonly maxOutputTokens?: number;
+    /**
+     * Release date (ms since epoch) as reported by the provider, where it reports one. Lets the model
+     * lists offer the newest models first instead of ordering them by name.
+     */
+    readonly released?: number;
     readonly status: LanguageModelStatus;
     readonly reasoningSupport?: ReasoningSupport;
     /**

package/src/common/model-discovery-status.ts

@@ -0,0 +1,132 @@
+// *****************************************************************************
+// 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
+// *****************************************************************************
+
+/**
+ * Provider-level state of dynamic model discovery.
+ *
+ * This is distinct from the per-model {@link LanguageModelStatus} (`ready`/`unavailable`):
+ * it describes whether a provider's list of models is currently being fetched, has failed,
+ * needs credentials or user consent, etc. It gives the UI a place to communicate fetching
+ * progress and error state for the whole provider.
+ */
+export type ModelDiscoveryState =
+    /** No credential (API key / host) is configured, so nothing can be fetched. */
+    | 'no-credentials'
+    /** A credential was found in the environment and awaits the user's one-time confirmation. */
+    | 'awaiting-consent'
+    /** Nothing in progress; no fetch has run yet. */
+    | 'idle'
+    /** A fetch is currently in flight. */
+    | 'fetching'
+    /** The last fetch (or cache load) succeeded and models are registered. */
+    | 'ready'
+    /** The last fetch failed. */
+    | 'error'
+    /** The model list is configured manually, so the provider is not asked what it offers. */
+    | 'overridden';
+
+/** Where a provider's effective API key comes from. Used to gate env-var keys behind a one-time consent. */
+export type ApiKeySource = 'preference' | 'environment' | 'none';
+
+/**
+ * A model a provider reported from its list endpoint.
+ *
+ * Only {@link id} is guaranteed: the endpoints differ widely in what they report about a model.
+ * Anthropic gives a display name and a release date, Google additionally a description, and
+ * OpenAI nothing but the id.
+ */
+export interface DiscoveredModel {
+    /** Provider-native model id, without the `<provider>/` prefix. */
+    readonly id: string;
+    /** Human-readable name reported by the provider, e.g. `Claude Opus 5`. */
+    readonly label?: string;
+    /** Longer description reported by the provider. */
+    readonly description?: string;
+    /** Release date (ms since epoch) reported by the provider, used to order dated variants. */
+    readonly released?: number;
+    /**
+     * Set by a provider that knows better than the generic ranking which of its models should be
+     * offered in the model pickers without the user asking. GitHub Copilot serves several vendors, so
+     * "the five newest" would offer five models of whichever vendor names its models with the highest
+     * numbers; it therefore nominates one per vendor itself. Left unset by the other providers.
+     */
+    readonly featured?: boolean;
+}
+
+/**
+ * Result of a provider model-discovery attempt.
+ *
+ * On a successful live fetch, `fromCache` is `false`. When the live fetch fails but a cached
+ * snapshot is available, the cached models are returned with `fromCache: true` and `error` set to
+ * the failure reason, so the UI can keep the models usable while indicating they may be stale.
+ */
+export interface ModelDiscoveryResult {
+    /** The discovered models, in the order they should be registered. */
+    readonly models: DiscoveredModel[];
+    /** Whether the models came from the cached snapshot because the live fetch failed. */
+    readonly fromCache: boolean;
+    /** Failure reason when the live fetch failed (even if a cached result was returned). */
+    readonly error?: string;
+}
+
+/**
+ * What to do about a discovery state, offered as a button next to the explanation.
+ *
+ * Most providers need none: what a missing credential wants is the API key setting, which sits on the
+ * same page right above. A provider whose credential is established by a command rather than a
+ * preference — GitHub Copilot signs in through its CLI — names that command here.
+ */
+export interface ModelDiscoveryAction {
+    /** Button label, already localized. */
+    readonly label: string;
+    readonly commandId: string;
+    readonly args?: unknown[];
+}
+
+/**
+ * Snapshot of a provider's model-discovery state, as observed on the frontend.
+ */
+export interface ModelDiscoveryStatus {
+    /** Provider id, e.g. `anthropic`. Matches the provider node in the Models configuration category. */
+    readonly providerId: string;
+    /** Human-readable provider label, e.g. `Anthropic`. */
+    readonly label: string;
+    /**
+     * Prefix used for this provider's registered model ids (e.g. `openai` while the provider id is
+     * `openAiOfficial`). Defaults to {@link providerId} when omitted.
+     */
+    readonly modelIdPrefix?: string;
+    readonly state: ModelDiscoveryState;
+    /**
+     * Overrides the badge label the state would otherwise carry, for a provider the generic wording
+     * does not fit: what GitHub Copilot lacks when it has no credential is a sign-in, not an API key.
+     */
+    readonly stateLabel?: string;
+    /** Optional human-readable detail (error message, hint). */
+    readonly message?: string;
+    /** Timestamp (ms since epoch) of the last successful fetch, if any. */
+    readonly lastFetch?: number;
+    /** Whether the currently registered models came from a cached snapshot rather than a live fetch. */
+    readonly fromCache?: boolean;
+    /**
+     * What the provider reported about the models it discovered, keyed by id in
+     * {@link DiscoveredModel.id}. The registry stays the source of truth for which models are
+     * registered; this only carries the extra metadata (label, description) for display.
+     */
+    readonly discovered?: readonly DiscoveredModel[];
+    /** What the user can do about the current state, where a command settles it. */
+    readonly action?: ModelDiscoveryAction;
+}