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

package/src/common/language-model.ts

@@ -41,6 +41,38 @@ export interface ReasoningSupport {
     readonly supportedLevels: ReadonlyArray<ReasoningLevel>;
     readonly defaultLevel?: ReasoningLevel;
 }
+export namespace ReasoningSupport {
+    /** Levels ordered by increasing effort; `'auto'` sits outside the scale. */
+    const EFFORT_SCALE: ReadonlyArray<ReasoningLevel> = ['off', 'minimal', 'low', 'medium', 'high'];
+
+    /**
+     * Returns `level` when `support` lists it, otherwise the nearest supported level on the effort scale,
+     * preferring the higher neighbour (an unsupported `minimal` becomes `low`, not `off`). An unsupported
+     * `'auto'` resolves to `defaultLevel`, then to the first supported level. Returns `level` unchanged
+     * when nothing suitable is supported.
+     */
+    export function clampLevel(support: ReasoningSupport, level: ReasoningLevel): ReasoningLevel {
+        const supported = support.supportedLevels;
+        if (supported.includes(level)) {
+            return level;
+        }
+        if (level === 'auto') {
+            return support.defaultLevel && supported.includes(support.defaultLevel) ? support.defaultLevel : supported[0] ?? level;
+        }
+        const index = EFFORT_SCALE.indexOf(level);
+        for (let distance = 1; distance < EFFORT_SCALE.length; distance++) {
+            const higher = EFFORT_SCALE[index + distance];
+            if (higher && supported.includes(higher)) {
+                return higher;
+            }
+            const lower = EFFORT_SCALE[index - distance];
+            if (lower && supported.includes(lower)) {
+                return lower;
+            }
+        }
+        return supported.includes('auto') ? 'auto' : level;
+    }
+}
 
 export type LanguageModelMessage =
     TextMessage | ThinkingMessage | ToolUseMessage | ToolResultMessage | ServerToolUseMessage | ImageMessage | CompactionMessage;
@@ -319,6 +351,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 +699,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;
+}

package/src/common/model-discovery-util.spec.ts

@@ -0,0 +1,105 @@
+// *****************************************************************************
+// 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 { DiscoveredModels } from './model-discovery-util';
+
+describe('DiscoveredModels.undatedId', () => {
+
+    it('strips a compact date suffix, as Anthropic uses', () => {
+        expect(DiscoveredModels.undatedId('claude-opus-5-20260401')).to.equal('claude-opus-5');
+    });
+
+    it('strips a dashed date suffix, as OpenAI uses', () => {
+        expect(DiscoveredModels.undatedId('gpt-4o-2024-11-20')).to.equal('gpt-4o');
+    });
+
+    it('strips the year-less snapshot suffix of OpenAI\'s older models', () => {
+        expect(DiscoveredModels.undatedId('gpt-4-0613')).to.equal('gpt-4');
+        expect(DiscoveredModels.undatedId('gpt-3.5-turbo-0125')).to.equal('gpt-3.5-turbo');
+    });
+
+    it('returns undefined for an id without a date suffix', () => {
+        expect(DiscoveredModels.undatedId('claude-opus-5')).to.equal(undefined);
+        expect(DiscoveredModels.undatedId('gemini-3.7-flash')).to.equal(undefined);
+        // A version suffix is not a date and must not be mistaken for one.
+        expect(DiscoveredModels.undatedId('gemini-1.5-pro-002')).to.equal(undefined);
+        // Nor is a context size, even though it is four digits like a month and day.
+        expect(DiscoveredModels.undatedId('some-model-4096')).to.equal(undefined);
+        expect(DiscoveredModels.undatedId('gpt-4-1340')).to.equal(undefined);
+    });
+});
+
+describe('DiscoveredModels.withUndatedAliases', () => {
+
+    it('adds the undated alias while keeping the release-pinned ids', () => {
+        const result = DiscoveredModels.withUndatedAliases([
+            { id: 'claude-opus-5-20260401' },
+            { id: 'claude-haiku-4-5-20251001' }
+        ]);
+        expect(result.map(model => model.id)).to.deep.equal([
+            'claude-opus-5',
+            'claude-haiku-4-5',
+            'claude-opus-5-20260401',
+            'claude-haiku-4-5-20251001'
+        ]);
+    });
+
+    it('adds one alias per family and gives it the metadata of the newest release', () => {
+        const result = DiscoveredModels.withUndatedAliases([
+            { id: 'claude-opus-5-20251120', label: 'Claude Opus 5 (November)', released: Date.parse('2025-11-20') },
+            { id: 'claude-opus-5-20260401', label: 'Claude Opus 5', released: Date.parse('2026-04-01') }
+        ]);
+        expect(result.map(model => model.id)).to.deep.equal([
+            'claude-opus-5',
+            'claude-opus-5-20251120',
+            'claude-opus-5-20260401'
+        ]);
+        expect(result[0].label).to.equal('Claude Opus 5');
+    });
+
+    it('orders the variants by the reported release date, which the year-less ids cannot express', () => {
+        const result = DiscoveredModels.withUndatedAliases([
+            // June 2023 sorts after January 2024 by id alone; the reported dates say otherwise.
+            { id: 'gpt-4-0613', label: 'older', released: Date.parse('2023-06-13') },
+            { id: 'gpt-4-0125', label: 'newer', released: Date.parse('2024-01-25') }
+        ]);
+        expect(result[0].id).to.equal('gpt-4');
+        expect(result[0].label).to.equal('newer');
+    });
+
+    it('falls back to the date in the id when the provider reports none', () => {
+        const result = DiscoveredModels.withUndatedAliases([
+            { id: 'claude-opus-5-20251120', label: 'older' },
+            { id: 'claude-opus-5-20260401', label: 'newer' }
+        ]);
+        expect(result[0].label).to.equal('newer');
+    });
+
+    it('leaves an alias the provider reported itself untouched', () => {
+        const result = DiscoveredModels.withUndatedAliases([
+            { id: 'gpt-4o', label: 'GPT-4o' },
+            { id: 'gpt-4o-2024-11-20', label: 'GPT-4o (2024-11-20)' }
+        ]);
+        expect(result.map(model => model.id)).to.deep.equal(['gpt-4o', 'gpt-4o-2024-11-20']);
+        expect(result[0].label).to.equal('GPT-4o');
+    });
+
+    it('passes undated models through unchanged', () => {
+        const models = [{ id: 'gemini-3.7-flash' }, { id: 'gemini-3.1-pro-preview' }];
+        expect(DiscoveredModels.withUndatedAliases(models)).to.deep.equal(models);
+    });
+});

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

@@ -0,0 +1,129 @@
+// *****************************************************************************
+// 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 { DiscoveredModel } from './model-discovery-status';
+
+/**
+ * Helpers for the dated model ids that provider list endpoints report. Providers call these from
+ * an overridable method of their language-models manager, so a provider (or an adopter) can opt
+ * out or refine the behaviour without reimplementing it.
+ */
+export namespace DiscoveredModels {
+
+    /**
+     * The date suffix providers append to a release-pinned id: `-20260401` and `-2026-04-01`, plus the
+     * `-0613` (month and day only) form OpenAI used for its older snapshots. The month and day are
+     * range-checked so that an id merely ending in four digits — a context size, a version — is not
+     * mistaken for a release.
+     */
+    const DATE_SUFFIX = /-(?:(\d{4})-?(0[1-9]|1[0-2])-?(0[1-9]|[12]\d|3[01])|(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01]))$/;
+
+    /**
+     * The undated form of a release-pinned model id, e.g. `claude-opus-5-20260401` → `claude-opus-5`.
+     * Returns `undefined` when the id carries no date suffix.
+     */
+    export function undatedId(id: string): string | undefined {
+        const match = DATE_SUFFIX.exec(id);
+        return match ? id.substring(0, match.index) : undefined;
+    }
+
+    /**
+     * Adds the undated alias for every release-pinned model, keeping the pinned releases themselves.
+     *
+     * Providers such as Anthropic and OpenAI list one entry per release (`claude-opus-5-20260401`,
+     * `claude-opus-5-20251120`, …) while accepting the undated form (`claude-opus-5`) as a
+     * request-time alias for the newest of them. The undated id is what the built-in model aliases
+     * reference and what does not change from under a configuration when a new release ships, so it
+     * is registered even when the provider does not list it. The pinned releases stay registered too,
+     * so a specific release can be selected; what keeps them out of the way of the model pickers is
+     * that only undated ids are featured (see the favorite models service), not that they are hidden.
+     *
+     * The alias takes the metadata of the most recent variant. Aliases come first; the reported models
+     * keep their relative order after them. An alias the provider reported itself is left untouched.
+     */
+    export function withUndatedAliases(models: DiscoveredModel[]): DiscoveredModel[] {
+        const reported = new Set(models.map(model => model.id));
+        const aliases = new Map<string, DiscoveredModel>();
+        for (const model of models) {
+            const id = undatedId(model.id);
+            if (!id || reported.has(id)) {
+                continue;
+            }
+            const previous = aliases.get(id);
+            if (!previous || isNewer(model, previous)) {
+                aliases.set(id, { ...model, id });
+            }
+        }
+        return [...aliases.values(), ...models];
+    }
+
+    /**
+     * Whether the id is a pointer a provider maintains at the current model of a family, e.g.
+     * `gemini-flash-latest`. Such an id carries no version to compare, and does not need one: it
+     * resolves to whatever is newest by definition.
+     */
+    export function isLatestPointer(id: string): boolean {
+        return id.endsWith('-latest');
+    }
+
+    /**
+     * The version numbers in a model id, e.g. `gemini-3.7-flash` → `[3, 7]` and `claude-sonnet-4-5`
+     * → `[4, 5]`. A heuristic, and only meaningful between the models of one provider — and one
+     * vendor at that: it says nothing about `gpt-5` against `claude-sonnet-4.5`.
+     */
+    export function versionOf(id: string): number[] {
+        return (id.match(/\d+/g) ?? []).map(Number);
+    }
+
+    /**
+     * Compares two model ids by the version numbers in them, most recent first. A longer sequence wins
+     * a shared prefix, so `gemini-3.7` sorts before `gemini-3`.
+     */
+    export function compareByVersion(left: string, right: string): number {
+        const leftVersion = versionOf(left);
+        const rightVersion = versionOf(right);
+        for (let index = 0; index < Math.max(leftVersion.length, rightVersion.length); index++) {
+            const difference = (rightVersion[index] ?? -1) - (leftVersion[index] ?? -1);
+            if (difference !== 0) {
+                return difference;
+            }
+        }
+        return 0;
+    }
+
+    /**
+     * Whether `candidate` is a more recent variant than `current`. The release date the provider
+     * reported is authoritative and always comparable, so it decides whenever both carry one; the date
+     * in the id is the fallback, and it only orders ids of the same shape — a year-less `-0613` says
+     * nothing about which year it belongs to.
+     */
+    function isNewer(candidate: DiscoveredModel, current: DiscoveredModel): boolean {
+        if (candidate.released !== undefined && current.released !== undefined) {
+            return candidate.released > current.released;
+        }
+        return idDate(candidate.id) > idDate(current.id);
+    }
+
+    /** The date in a release-pinned id as a comparable number, or `0` when there is none. */
+    function idDate(id: string): number {
+        const match = DATE_SUFFIX.exec(id);
+        if (!match) {
+            return 0;
+        }
+        // Either the full `YYYYMMDD` (groups 1-3) or the year-less `MMDD` (groups 4-5).
+        return match[1] ? Number(`${match[1]}${match[2]}${match[3]}`) : Number(`${match[4]}${match[5]}`);
+    }
+}

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

@@ -90,6 +90,12 @@ describe('PromptService', () => {
         expect(prompt?.text).to.equal('Ciao, {{invalid}}!');
     });
 
+    it('should insert argument values literally without expanding replacement patterns', async () => {
+        const value = "echo $$ $' $& $`";
+        const prompt = await promptService.getResolvedPromptFragment('1', { name: value });
+        expect(prompt?.text).to.equal(`Hello, ${value}!`);
+    });
+
     it('should return undefined if the prompt fragment id is not found', async () => {
         const prompt = await promptService.getResolvedPromptFragment('4');
         expect(prompt).to.be.undefined;

package/src/common/prompt-service.ts

@@ -897,7 +897,7 @@ export class PromptServiceImpl implements PromptService {
         let resolvedTemplate = promptFragment.template;
         const variableAndArgResolutions = await this.resolveVariablesAndArgs(promptFragment.template, args, context);
         variableAndArgResolutions.replacements.forEach(replacement =>
-            resolvedTemplate = resolvedTemplate.replace(replacement.placeholder, replacement.value));
+            resolvedTemplate = resolvedTemplate.replace(replacement.placeholder, () => replacement.value));
 
         // Then resolve function references with already resolved variables and arguments
         // This allows to resolve function references contained in resolved variables (e.g. prompt fragments)
@@ -920,7 +920,7 @@ export class PromptServiceImpl implements PromptService {
             };
         });
         functionReplacements.forEach(replacement =>
-            resolvedTemplate = resolvedTemplate.replace(replacement.placeholder, replacement.value));
+            resolvedTemplate = resolvedTemplate.replace(replacement.placeholder, () => replacement.value));
 
         return {
             id: systemOrFragmentId,
@@ -945,7 +945,7 @@ export class PromptServiceImpl implements PromptService {
         const resolutions = await this.resolveVariablesAndArgs(promptFragment.template, args, context, resolveVariable);
         let resolvedTemplate = promptFragment.template;
         resolutions.replacements.forEach(replacement =>
-            resolvedTemplate = resolvedTemplate.replace(replacement.placeholder, replacement.value));
+            resolvedTemplate = resolvedTemplate.replace(replacement.placeholder, () => replacement.value));
 
         return {
             id: systemOrFragmentId,

package/src/node/ai-core-backend-module.ts

@@ -44,6 +44,8 @@ import {
 } from '../common';
 import { BackendLanguageModelRegistryImpl } from './backend-language-model-registry';
 import { TokenUsageServiceImpl } from './token-usage-service-impl';
+import { ModelSnapshotStore, ModelSnapshotStoreImpl } from './model-snapshot-store';
+import { ModelDiscoveryFetcher, ModelDiscoveryFetcherImpl } from './model-discovery-fetcher';
 import { AgentSettingsPreferenceSchema } from '../common/agent-preferences';
 import { bindAICorePreferences } from '../common/ai-core-preferences';
 
@@ -112,5 +114,11 @@ const aiCoreConnectionModule = ConnectionContainerModule.create(({ bind, bindBac
 export default new ContainerModule(bind => {
     bind(PreferenceContribution).toConstantValue({ schema: AgentSettingsPreferenceSchema });
     bindAICorePreferences(bind);
+    // Bound in the root container: the snapshots are per provider, not per frontend connection,
+    // and the provider managers resolving them live in connection-scoped child containers.
+    bind(ModelSnapshotStoreImpl).toSelf().inSingletonScope();
+    bind(ModelSnapshotStore).toService(ModelSnapshotStoreImpl);
+    bind(ModelDiscoveryFetcherImpl).toSelf().inSingletonScope();
+    bind(ModelDiscoveryFetcher).toService(ModelDiscoveryFetcherImpl);
     bind(ConnectionContainerModule).toConstantValue(aiCoreConnectionModule);
 });

package/src/node/backend-language-model-registry.ts

@@ -62,6 +62,7 @@ export class BackendLanguageModelRegistryImpl extends DefaultLanguageModelRegist
             family: model.family,
             maxInputTokens: model.maxInputTokens,
             maxOutputTokens: model.maxOutputTokens,
+            released: model.released,
             reasoningSupport: model.reasoningSupport,
             serverTools: model.serverTools,
             serverSideCompactionSupport: model.serverSideCompactionSupport,

package/src/node/index.ts

@@ -15,3 +15,5 @@
 // *****************************************************************************
 
 export * from './proxy-util';
+export * from './model-snapshot-store';
+export * from './model-discovery-fetcher';

package/src/node/model-discovery-fetcher.ts

@@ -0,0 +1,105 @@
+// *****************************************************************************
+// 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 { ILogger } from '@theia/core';
+import { timeout } from '@theia/core/lib/common/promise-util';
+import { inject, injectable, named } from '@theia/core/shared/inversify';
+import { DiscoveredModel, ModelDiscoveryResult } from '../common/model-discovery-status';
+import { ModelSnapshotStore } from './model-snapshot-store';
+
+export const ModelDiscoveryFetcher = Symbol('ModelDiscoveryFetcher');
+
+/** What a provider contributes to a discovery run; everything around it is the same for all of them. */
+export interface ModelDiscoveryRequest {
+    /** Name the provider's snapshot is kept under, e.g. `anthropic-models.json`. */
+    readonly snapshotFile: string;
+    /** The provider, for the log entry a failed fetch leaves, e.g. `Anthropic`. */
+    readonly providerLabel: string;
+    /** Asks the provider what it offers. Called again while {@link isRetryable} accepts the failure. */
+    listModels(): Promise<DiscoveredModel[]>;
+    /**
+     * Whether a failure is transient enough to try again. Nothing is retried by default: a provider
+     * knows which of its SDK's errors are a connection giving out and which are an answer.
+     */
+    isRetryable?(error: unknown): boolean;
+}
+
+/**
+ * Runs a provider's model discovery: asks it what it offers, retries a transient failure, and keeps
+ * the answer as a snapshot so the models survive a later failure or an offline start.
+ */
+export interface ModelDiscoveryFetcher {
+    /**
+     * Discovers the models of one provider. Returns the snapshot with `fromCache` set when the fetch
+     * failed and there is one, and rejects with the fetch's own error when there is not.
+     */
+    fetch(request: ModelDiscoveryRequest): Promise<ModelDiscoveryResult>;
+}
+
+@injectable()
+export class ModelDiscoveryFetcherImpl implements ModelDiscoveryFetcher {
+
+    /** Number of attempts (including the first) for a discovery fetch on a retryable error. */
+    protected maxAttempts = 3;
+    /** Base linear backoff between attempts; multiplied by the number of the attempt that failed. */
+    protected retryDelayMs = 500;
+
+    @inject(ModelSnapshotStore)
+    protected readonly snapshotStore: ModelSnapshotStore;
+
+    @inject(ILogger) @named('ai-core:ModelDiscoveryFetcherImpl')
+    protected readonly logger: ILogger;
+
+    async fetch(request: ModelDiscoveryRequest): Promise<ModelDiscoveryResult> {
+        try {
+            const models = await this.listWithRetry(request);
+            await this.snapshotStore.write(request.snapshotFile, models);
+            return { models, fromCache: false };
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const cached = await this.snapshotStore.read(request.snapshotFile);
+            if (cached) {
+                this.logger.warn(`${request.providerLabel}: model discovery failed (${message}); using cached snapshot.`);
+                return { models: cached, fromCache: true, error: message };
+            }
+            // A run that never succeeded has no snapshot to fall back on, so record the failure here.
+            this.logger.error(`${request.providerLabel}: model discovery failed; no cached snapshot to fall back on.`, error);
+            throw error;
+        }
+    }
+
+    /** Lists the models, retrying a transient failure with a linear backoff. */
+    protected async listWithRetry(request: ModelDiscoveryRequest): Promise<DiscoveredModel[]> {
+        let lastError: unknown;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            try {
+                return await request.listModels();
+            } catch (error) {
+                lastError = error;
+                if (attempt === this.maxAttempts || !request.isRetryable?.(error)) {
+                    break;
+                }
+                await this.delay(this.retryDelayMs * attempt);
+            }
+        }
+        throw lastError;
+    }
+
+    /** Waits between two attempts. Overridable so a test does not have to. */
+    protected delay(ms: number): Promise<void> {
+        return timeout(ms);
+    }
+}