@theia/ai-ide 1.76.0-next.7 → 1.76.0

package/src/browser/ai-configuration/categories/provider-model-discovery-section.tsx

@@ -0,0 +1,341 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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 { nls } from '@theia/core';
+import { codicon } from '@theia/core/lib/browser';
+import * as React from '@theia/core/shared/react';
+import { formatDistanceToNow } from 'date-fns';
+import { compareModelsByRecency, LanguageModel } from '@theia/ai-core/lib/common';
+import { FavoriteModelsService } from '@theia/ai-core/lib/browser';
+import { DiscoveredModel, ModelDiscoveryAction, ModelDiscoveryStatus } from '@theia/ai-core/lib/common/model-discovery-status';
+import { AiConfigurationItemStatus } from '@theia/ai-core-ui/lib/browser/ai-configuration/ai-configuration-category';
+import {
+    AiConfigurationCallout, AiConfigurationEmptyState, AiConfigurationFilterInput, AiConfigurationFilterToggle, AiConfigurationIconButton, AiConfigurationSection,
+    AiConfigurationStatusBadge
+} from '@theia/ai-core-ui/lib/browser/ai-configuration/components/ai-configuration-primitives';
+import { AiConfigurationItemRow } from '@theia/ai-core-ui/lib/browser/ai-configuration/components/ai-configuration-item-row';
+
+/**
+ * Number of models from which the list gets a filter. Below it, scanning the list is faster than
+ * typing; above it — OpenAI reports dozens — it is not.
+ */
+const FILTER_THRESHOLD = 8;
+
+export interface ProviderModelDiscoverySectionProps {
+    readonly status: ModelDiscoveryStatus;
+    /** The provider's currently registered models. */
+    readonly models: LanguageModel[];
+    /** Decides which models the pickers offer, and takes the user's checks. */
+    readonly favorites: FavoriteModelsService;
+    readonly onRefresh: () => void;
+    /** Runs what the provider offers to do about the current state, e.g. signing in to GitHub Copilot. */
+    readonly onAction: (action: ModelDiscoveryAction) => void;
+}
+
+/**
+ * Renders a provider's model-discovery state (fetching / ready / cached / error / no credentials /
+ * awaiting consent / manual), a manual refresh, and the discovered models, below the provider's
+ * settings in the Models category. This is the provider-level surface that per-model status cannot
+ * give: fetching progress and failure of the list call itself.
+ *
+ * The list holds everything the provider offers, one entry per release included, which is more than
+ * a model picker can carry. Which of them the pickers offer is shown and controlled here, by the
+ * star on each row.
+ */
+export const ProviderModelDiscoverySection: React.FC<ProviderModelDiscoverySectionProps> = ({ status, models, favorites, onRefresh, onAction }) => {
+    const [filter, setFilter] = React.useState('');
+    const [favoritesOnly, setFavoritesOnly] = React.useState(false);
+    // Re-render when a star is set anywhere, and when a discovery changes what is featured.
+    const [favoritesRevision, setFavoritesRevision] = React.useState(0);
+    React.useEffect(() => {
+        const listener = favorites.onDidChange(() => setFavoritesRevision(revision => revision + 1));
+        return () => listener.dispose();
+    }, [favorites]);
+    const fetching = status.state === 'fetching';
+    const modelIdPrefix = status.modelIdPrefix ?? status.providerId;
+    const overridden = favorites.hasOverrides(modelIdPrefix);
+    // Without a credential there is nothing to ask the provider; refreshing would only report the same
+    // state back. The setting or the sign-in above the list is what moves this on.
+    const refreshable = status.state !== 'no-credentials' && status.state !== 'awaiting-consent';
+    // Newest first: a provider's recent models are what a list this long is scrolled for. Models whose
+    // provider reports no release date (Gemini reports none) fall back to alphabetical order.
+    const rows = React.useMemo(() => models
+        .slice()
+        .sort(compareModelsByRecency)
+        // `favoritesRevision` is not read here: it is what re-runs this when a star or the featured set changes.
+        .map(model => describeModel(model, status.discovered, favorites))
+        // The provider's current line-up first, newest first within each part. A list this long is read
+        // from the top, and the models the picker starts with are what it is usually opened for. The sort
+        // is stable, so it only lifts them past the older ones without disturbing the order.
+        .sort((left, right) => Number(right.featured) - Number(left.featured)),
+    [models, status.discovered, favorites, favoritesRevision]);
+    const matches = React.useMemo(
+        () => rows.filter(row => (!favoritesOnly || row.favorite) && matchesFilter(row, filter)),
+        [rows, filter, favoritesOnly]
+    );
+    const favoritesOnlyLabel = favoritesOnly
+        ? nls.localize('theia/ai/ide/modelsConfiguration/showAllModels', 'Show all discovered models')
+        : nls.localize('theia/ai/ide/modelsConfiguration/showCheckedModels', 'Show only the models the AI chat input\'s model picker shows');
+    const filterToggles: AiConfigurationFilterToggle[] = [{
+        iconClass: codicon('pass'),
+        title: favoritesOnlyLabel,
+        active: favoritesOnly,
+        onToggle: () => setFavoritesOnly(!favoritesOnly)
+    }];
+    return <AiConfigurationSection
+        title={nls.localize('theia/ai/ide/modelsConfiguration/discovery', 'Model Discovery')}
+        count={rows.length > 0 ? rows.length : undefined}
+        subtitle={sectionSubtitle(status, rows.length, rows.filter(row => row.favorite).length)}
+        actions={<>
+            <AiConfigurationStatusBadge status={discoveryStatusBadge(status)} />
+            <AiConfigurationIconButton
+                iconClass={codicon(fetching ? 'sync' : 'refresh')}
+                title={refreshable
+                    ? nls.localize('theia/ai/ide/modelsConfiguration/refresh', 'Refresh the model list')
+                    : status.message ?? nls.localize('theia/ai/ide/modelsConfiguration/refreshUnavailable', 'Nothing to refresh until the provider has a credential')}
+                busy={fetching}
+                disabled={fetching || !refreshable}
+                onClick={onRefresh}
+            />
+            <AiConfigurationIconButton
+                iconClass={codicon('discard')}
+                title={overridden
+                    ? nls.localize('theia/ai/ide/modelsConfiguration/resetShown', 'Reset to defaults')
+                    : nls.localize('theia/ai/ide/modelsConfiguration/resetShownUnavailable', 'Already at the defaults')}
+                disabled={!overridden}
+                onClick={() => favorites.resetToDefaults(modelIdPrefix)}
+            />
+        </>}
+    >
+        <DiscoveryBody
+            status={status}
+            rows={rows}
+            matches={matches}
+            filter={filter}
+            onFilterChange={setFilter}
+            filterToggles={filterToggles}
+            favorites={favorites}
+            onRefresh={onRefresh}
+            onAction={onAction}
+        />
+    </AiConfigurationSection>;
+};
+
+/**
+ * The line under the section title. A manually configured list says so, since that is why no discovery
+ * ran; otherwise it states once — rather than leaving it to the tooltip of each of forty rows — that
+ * the checks are about the chat input alone. An agent's model and a model alias are picked from every
+ * discovered model, on their own pages.
+ */
+function sectionSubtitle(status: ModelDiscoveryStatus, rowCount: number, shownCount: number): string | undefined {
+    if (status.state === 'overridden') {
+        return status.message;
+    }
+    // The ratio is the overview a list this long cannot give by itself, and it says what the checks mean.
+    return rowCount > 0
+        ? nls.localize('theia/ai/ide/modelsConfiguration/shownExplanation',
+            '{0} of {1} shown in the AI chat input\'s model picker', shownCount, rowCount)
+        : undefined;
+}
+
+/** A registered model paired with whatever the provider reported about it. */
+interface ModelRow {
+    readonly id: string;
+    /** Fully qualified id, i.e. with the `<provider>/` prefix, as the favorites are keyed. */
+    readonly qualifiedId: string;
+    readonly label?: string;
+    readonly description?: string;
+    readonly released?: number;
+    readonly ready: boolean;
+    readonly statusMessage?: string;
+    /** Whether the model pickers offer this model. */
+    readonly favorite: boolean;
+    /** Whether it is offered automatically, in which case the star cannot be removed. */
+    readonly featured: boolean;
+}
+
+function describeModel(model: LanguageModel, discovered: readonly DiscoveredModel[] | undefined, favorites: FavoriteModelsService): ModelRow {
+    // Registered ids carry the `<provider>/` prefix; what the provider reported does not.
+    const id = model.id.substring(model.id.indexOf('/') + 1);
+    const reported = discovered?.find(candidate => candidate.id === id);
+    return {
+        id,
+        qualifiedId: model.id,
+        label: reported?.label ?? model.name,
+        description: reported?.description,
+        released: model.released ?? reported?.released,
+        ready: model.status.status === 'ready',
+        statusMessage: model.status.message,
+        favorite: favorites.isFavorite(model.id),
+        featured: favorites.isFeatured(model.id)
+    };
+}
+
+function matchesFilter(row: ModelRow, filter: string): boolean {
+    const query = filter.trim().toLowerCase();
+    return query.length === 0
+        || row.id.toLowerCase().includes(query)
+        || (row.label?.toLowerCase().includes(query) ?? false);
+}
+
+interface DiscoveryBodyProps {
+    readonly status: ModelDiscoveryStatus;
+    readonly rows: ModelRow[];
+    readonly matches: ModelRow[];
+    readonly filter: string;
+    readonly onFilterChange: (value: string) => void;
+    /** Narrowings offered inside the filter box, on top of the typed text. */
+    readonly filterToggles: AiConfigurationFilterToggle[];
+    readonly favorites: FavoriteModelsService;
+    readonly onRefresh: () => void;
+    readonly onAction: (action: ModelDiscoveryAction) => void;
+}
+
+const DiscoveryBody: React.FC<DiscoveryBodyProps> = ({ status, rows, matches, filter, onFilterChange, filterToggles, favorites, onRefresh, onAction }) => {
+    // The provider's API-key and consent settings sit on the same page, right above this section — but
+    // a provider whose credential is a sign-in rather than a setting names the command that gets one.
+    if (status.state === 'no-credentials' || status.state === 'awaiting-consent') {
+        return <AiConfigurationEmptyState
+            message={status.message ?? ''}
+            iconClass={codicon('key')}
+            action={status.action && <button className='theia-button main' onClick={() => onAction(status.action!)}>{status.action.label}</button>}
+        />;
+    }
+    const retry = <button className='theia-button main' onClick={onRefresh}>{nls.localizeByDefault('Retry')}</button>;
+    const refresh = <button className='theia-button main' onClick={onRefresh}>{nls.localizeByDefault('Refresh')}</button>;
+    return <>
+        {/* A failed refresh does not unregister what an earlier one found, so the models stay listed
+            below the failure rather than being replaced by it. */}
+        {status.state === 'error' && <AiConfigurationCallout message={status.message ?? ''} action={retry} />}
+        {status.state === 'ready' && status.fromCache && status.message && <AiConfigurationCallout message={status.message} action={refresh} />}
+        {rows.length === 0
+            ? <AiConfigurationEmptyState
+                message={nls.localize('theia/ai/ide/modelsConfiguration/noModels', 'No models discovered yet.')}
+                iconClass={codicon('cloud')}
+            />
+            : <>
+                {rows.length > FILTER_THRESHOLD && <AiConfigurationFilterInput
+                    value={filter}
+                    onChange={onFilterChange}
+                    placeholder={nls.localize('theia/ai/ide/modelsConfiguration/filterModels', 'Filter models')}
+                    toggles={filterToggles}
+                />}
+                {matches.length === 0
+                    ? <AiConfigurationEmptyState message={nls.localizeByDefault('No results found')} />
+                    : <ModelRows rows={matches} favorites={favorites} />}
+            </>}
+    </>;
+};
+
+const ModelRows: React.FC<{ rows: ModelRow[]; favorites: FavoriteModelsService }> = ({ rows, favorites }) => <>
+    {rows.map(row => <AiConfigurationItemRow
+        key={row.id}
+        // The id is the heading on every row, whatever the provider reports: it is what agents, aliases
+        // and settings reference, and OpenAI reports nothing else, so heading it with the name where
+        // there is one would give each provider a differently shaped list.
+        label={row.id}
+        // Kept on the row whether the model is checked or not: it says that this is one of the
+        // provider's current models, which is why the picker starts with it and stays true after
+        // someone unchecks it.
+        tags={row.featured
+            ? [{
+                label: nls.localizeByDefault('Default'),
+                title: nls.localize('theia/ai/ide/modelsConfiguration/defaultModel',
+                    'One of the newest models of this provider, which the AI chat input\'s model picker shows unless it is hidden here')
+            }]
+            : undefined}
+        description={modelRowDescription(row)}
+        // Every model in this list is ready as long as the provider has a key, which it has whenever the
+        // list is shown at all. Only the exception is worth a badge.
+        status={row.ready ? undefined : notReadyBadge(row)}
+        trailing={<>
+            {/* Names the order the list is in, which is otherwise a claim the user cannot check. */}
+            {row.released !== undefined && <span className='ai-configuration-item-row-detail'>
+                {nls.localize('theia/ai/ide/modelsConfiguration/released', 'released {0}',
+                    formatDistanceToNow(row.released, { addSuffix: true }))}
+            </span>}
+            <ShowInChatButton row={row} favorites={favorites} />
+        </>}
+    />)}
+</>;
+
+/**
+ * Whether the AI chat input's model picker shows this model: a checked circle when it does, an empty
+ * one when it does not. Nothing else is affected — an agent's model and a model alias are picked from
+ * every discovered model, on their own pages.
+ *
+ * What a model released tomorrow is shown by is the `Default` badge on its row, not a check made
+ * here; unchecking one of those is what says otherwise, and that is all that is stored.
+ */
+const ShowInChatButton: React.FC<{ row: ModelRow; favorites: FavoriteModelsService }> = ({ row, favorites }) => {
+    const title = row.favorite
+        ? nls.localize('theia/ai/ide/modelsConfiguration/hideModel', 'Hide this model from the AI chat input\'s model picker')
+        : nls.localize('theia/ai/ide/modelsConfiguration/showModel', 'Show this model in the AI chat input\'s model picker');
+    return <AiConfigurationIconButton
+        iconClass={codicon(row.favorite ? 'pass' : 'circle-large')}
+        title={title}
+        onClick={() => favorites.toggleFavorite(row.qualifiedId)}
+    />;
+};
+
+/** What the provider reports about the model, if anything: its name, its description, or both. */
+function modelRowDescription(row: ModelRow): string | undefined {
+    const parts = [row.label, row.description].filter(part => part !== undefined);
+    return parts.length > 0 ? parts.join(' · ') : undefined;
+}
+
+function notReadyBadge(row: ModelRow): AiConfigurationItemStatus {
+    return {
+        kind: 'warn',
+        label: nls.localize('theia/ai/ide/modelsConfiguration/modelNotReady', 'Not ready'),
+        tooltip: row.statusMessage
+    };
+}
+
+/** Maps the discovery state onto the shared status badge, so it reads like every other badge in the view. */
+function discoveryStatusBadge(status: ModelDiscoveryStatus): AiConfigurationItemStatus {
+    const badge = genericStatusBadge(status);
+    // A provider whose credential is not an API key says so itself; the state alone cannot know.
+    return status.stateLabel ? { ...badge, label: status.stateLabel } : badge;
+}
+
+function genericStatusBadge(status: ModelDiscoveryStatus): AiConfigurationItemStatus {
+    switch (status.state) {
+        case 'no-credentials':
+            return { kind: 'warn', label: nls.localize('theia/ai/ide/modelsConfiguration/noKey', 'No API key'), tooltip: status.message };
+        case 'awaiting-consent':
+            return { kind: 'warn', label: nls.localize('theia/ai/ide/modelsConfiguration/awaitingConsent', 'Awaiting consent'), tooltip: status.message };
+        case 'fetching':
+            return { kind: 'off', label: nls.localize('theia/ai/ide/modelsConfiguration/fetching', 'Fetching…'), tooltip: status.message };
+        case 'error':
+            return { kind: 'error', label: nls.localizeByDefault('Error'), tooltip: status.message };
+        case 'overridden':
+            return { kind: 'off', label: nls.localizeByDefault('Manual'), tooltip: status.message };
+        case 'ready':
+            if (status.fromCache) {
+                return { kind: 'warn', label: nls.localizeByDefault('Cached'), tooltip: status.message };
+            }
+            return {
+                kind: 'on',
+                label: status.lastFetch
+                    ? nls.localize('theia/ai/ide/modelsConfiguration/updated', 'Updated {0}', formatDistanceToNow(status.lastFetch, { addSuffix: true }))
+                    : nls.localize('theia/ai/ide/modelsConfiguration/ready', 'Ready'),
+                tooltip: status.message
+            };
+        default:
+            return { kind: 'off', label: nls.localizeByDefault('Idle'), tooltip: status.message };
+    }
+}

package/src/browser/ai-configuration/language-model-renderer.tsx

@@ -18,6 +18,7 @@ import {
     Agent,
     AISettingsService,
     FrontendLanguageModelRegistry,
+    groupModelsByProvider,
     LanguageModel,
     LanguageModelRequirement,
     PREFERENCE_NAME_REASONING,
@@ -248,13 +249,20 @@ export const LanguageModelRenderer: React.FC<LanguageModelSettingsProps> = (
                 label: nls.localize('theia/ai/core/languageModelRenderer/alias', '[alias] {0}', alias.id)
             });
         });
-        languageModels?.slice().sort((a, b) => (a.name ?? a.id).localeCompare(b.name ?? b.id)).forEach(model => {
+        const modelOption = (model: LanguageModel): SelectOption => {
             const isNotReady = model.status.status !== 'ready';
-            options.push({
+            return {
                 value: model.id,
                 label: `${model.name ?? model.id} ${isNotReady ? '✗' : '✓'}`,
                 description: isNotReady && model.status.message ? model.status.message : undefined
-            });
+            };
+        };
+        // Divided per provider, newest first inside each group. Every model is offered here, not just
+        // the ones the chat picker carries: this is the page where a specific older or release-pinned
+        // model is deliberately assigned to an agent.
+        groupModelsByProvider(languageModels ?? []).forEach(({ models }) => {
+            options.push({ separator: true });
+            options.push(...models.map(modelOption));
         });
         return options;
     }, [aliases, languageModels]);

package/src/browser/ai-getting-started-commands.ts

@@ -0,0 +1,33 @@
+// *****************************************************************************
+// 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 { Command } from '@theia/core/lib/common/command';
+
+/** Opens the AI getting started walkthrough, from the chat view, a menu or the command palette. */
+export const AI_OPEN_GETTING_STARTED_WALKTHROUGH = Command.toLocalizedCommand({
+    id: 'ai.openGettingStartedWalkthrough',
+    label: 'Get Started with AI'
+}, 'theia/ai/ide/openGettingStartedWalkthrough');
+
+/**
+ * Sets the default chat agent to the agent id passed as the first argument.
+ * Lets the walkthrough offer the recommended agents as one click each, rather than sending the user to the
+ * preference row to pick one there.
+ */
+export const AI_SET_DEFAULT_CHAT_AGENT = Command.toLocalizedCommand({
+    id: 'ai.setDefaultChatAgent',
+    label: 'Set Default Chat Agent'
+}, 'theia/ai/ide/setDefaultChatAgent');

package/src/browser/ai-getting-started-contribution.ts

@@ -0,0 +1,64 @@
+// *****************************************************************************
+// 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 { CommandContribution, CommandRegistry } from '@theia/core/lib/common/command';
+import { PreferenceScope, PreferenceService } from '@theia/core/lib/common/preferences';
+import { MessageService } from '@theia/core/lib/common/message-service';
+import { nls } from '@theia/core/lib/common/nls';
+import { ChatAgentService } from '@theia/ai-chat/lib/common';
+import { DEFAULT_CHAT_AGENT_PREF } from '@theia/ai-chat/lib/common/ai-chat-preferences';
+import { WalkthroughCommands } from '@theia/getting-started/lib/common/walkthrough-commands';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { AI_GETTING_STARTED_WALKTHROUGH_ID } from './ai-getting-started-walkthrough';
+import { AI_OPEN_GETTING_STARTED_WALKTHROUGH, AI_SET_DEFAULT_CHAT_AGENT } from './ai-getting-started-commands';
+
+/**
+ * Opens the AI getting started walkthrough from anywhere - the chat view, the command palette or a menu -
+ * without every caller having to know the walkthrough id.
+ */
+@injectable()
+export class AiGettingStartedContribution implements CommandContribution {
+
+    @inject(PreferenceService)
+    protected readonly preferenceService: PreferenceService;
+
+    @inject(MessageService)
+    protected readonly messageService: MessageService;
+
+    @inject(ChatAgentService)
+    protected readonly chatAgentService: ChatAgentService;
+
+    registerCommands(commands: CommandRegistry): void {
+        // Deliberately not gated on the AI features being enabled: this is where they get enabled.
+        commands.registerCommand(AI_OPEN_GETTING_STARTED_WALKTHROUGH, {
+            execute: () => commands.executeCommand(WalkthroughCommands.OPEN_WALKTHROUGH.id, AI_GETTING_STARTED_WALKTHROUGH_ID)
+        });
+        commands.registerCommand(AI_SET_DEFAULT_CHAT_AGENT, {
+            execute: (agentId: string) => this.setDefaultChatAgent(agentId),
+            isEnabled: (agentId: unknown) => typeof agentId === 'string' && !!agentId
+        });
+    }
+
+    /**
+     * Writes the default chat agent preference and says so: the walkthrough offers this as a button, and
+     * without the message the only feedback would be the step ticking itself off further up the page.
+     */
+    protected async setDefaultChatAgent(agentId: string): Promise<void> {
+        await this.preferenceService.set(DEFAULT_CHAT_AGENT_PREF, agentId, PreferenceScope.User);
+        const label = this.chatAgentService.getAgent(agentId)?.name ?? agentId;
+        this.messageService.info(nls.localize('theia/ai/ide/defaultChatAgentSet', 'The default chat agent is now {0}.', label));
+    }
+}

package/src/browser/ai-getting-started-walkthrough.spec.ts

@@ -0,0 +1,146 @@
+// *****************************************************************************
+// 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 { 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 { ENABLE_AI_CONTEXT_KEY } from '@theia/ai-core/lib/browser/ai-activation-service';
+import { WalkthroughDefinition } from '@theia/getting-started/lib/common/walkthrough-types';
+import { AI_GETTING_STARTED_WALKTHROUGH_ID, AiGettingStartedWalkthroughProvider } from './ai-getting-started-walkthrough';
+import {
+    AI_CHAT_USED_CONTEXT_KEY,
+    AI_DEFAULT_AGENT_CONTEXT_KEY,
+    AI_MODEL_READY_CONTEXT_KEY,
+    AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY
+} from './ai-walkthrough-context-keys';
+disableJSDOM();
+
+/** The commands the walkthrough is allowed to link to; each one is registered by one of the AI packages. */
+const KNOWN_COMMANDS = new Set([
+    'aiConfiguration:open',
+    'aiConfiguration:openTools',
+    'aiChat:toggle',
+    'workspace:manageTrust',
+    'perspective.switch',
+    'ai.setDefaultChatAgent'
+]);
+
+const KNOWN_CONTEXT_KEYS = new Set([
+    ENABLE_AI_CONTEXT_KEY,
+    AI_MODEL_READY_CONTEXT_KEY,
+    AI_CHAT_USED_CONTEXT_KEY,
+    AI_DEFAULT_AGENT_CONTEXT_KEY,
+    AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY
+]);
+
+describe('AiGettingStartedWalkthroughProvider', () => {
+
+    let walkthrough: WalkthroughDefinition;
+
+    /** The recommended agents a product contributes, which the agent step turns into one link each. */
+    const recommendedAgents = [
+        { id: 'Coder', label: 'Coder', description: 'Code generation and modification' },
+        { id: 'Architect', label: 'Architect', description: 'High-level design and architecture' }
+    ];
+
+    function createProvider(): AiGettingStartedWalkthroughProvider {
+        const provider = new AiGettingStartedWalkthroughProvider();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (provider as any).recommendationService = { getRecommendedAgents: () => recommendedAgents };
+        return provider;
+    }
+
+    function agentStepOf(provider: AiGettingStartedWalkthroughProvider): string {
+        return provider.getWalkthroughs()[0].steps.find(step => step.id === 'choose-agent')!.description;
+    }
+
+    before(() => {
+        disableJSDOM = enableJSDOM();
+        FrontendApplicationConfigProvider.set({});
+        walkthrough = createProvider().getWalkthroughs()[0];
+    });
+    after(() => disableJSDOM());
+
+    it('should contribute the getting started walkthrough', () => {
+        const walkthroughs = createProvider().getWalkthroughs();
+
+        expect(walkthroughs).to.have.lengthOf(1);
+        expect(walkthroughs[0].id).to.equal(AI_GETTING_STARTED_WALKTHROUGH_ID);
+        expect(walkthroughs[0].steps.map(step => step.id)).to.deep.equal(
+            ['ai-support', 'enable-ai', 'connect-model', 'choose-agent', 'first-question', 'tool-confirmation', 'go-further']);
+    });
+
+    it('should offer every recommended agent as an action that sets it as the default', () => {
+        const description = agentStepOf(createProvider());
+        for (const agent of recommendedAgents) {
+            // Alone in its paragraph, which is what the welcome page renders as a button, and carrying the
+            // agent's description as the link title so it stays available as a tooltip.
+            expect(description, `action for ${agent.id}`).to.include(
+                `\n\n[@${agent.label}](command:ai.setDefaultChatAgent?${encodeURIComponent(JSON.stringify(agent.id))} "${agent.description}")`);
+        }
+    });
+
+    it('should keep the preference row reachable', () => {
+        expect(agentStepOf(createProvider())).to.include('command:aiConfiguration:open?ai-features.chat.defaultChatAgent');
+    });
+
+    it('should give every step an id, a title and a description', () => {
+        const ids = walkthrough.steps.map(step => step.id);
+        expect(new Set(ids).size).to.equal(ids.length);
+        for (const step of walkthrough.steps) {
+            expect(step.title, `title of ${step.id}`).to.not.be.empty;
+            expect(step.description, `description of ${step.id}`).to.not.be.empty;
+        }
+    });
+
+    it('should substitute every placeholder', () => {
+        for (const step of walkthrough.steps) {
+            expect(step.title, `title of ${step.id}`).to.not.match(/\{\d+\}/);
+            expect(step.description, `description of ${step.id}`).to.not.match(/\{\d+\}/);
+        }
+        expect(walkthrough.description).to.not.match(/\{\d+\}/);
+    });
+
+    it('should only link to commands that exist', () => {
+        for (const step of walkthrough.steps) {
+            for (const match of step.description.matchAll(/\(command:([^?)]+)/g)) {
+                expect(KNOWN_COMMANDS, `command of ${step.id}`).to.include(match[1]);
+            }
+        }
+    });
+
+    it('should only complete on context keys that are published, so that steps also tick for an already configured user', () => {
+        for (const step of walkthrough.steps) {
+            for (const event of step.completionEvents ?? []) {
+                if (event.startsWith('onContext:')) {
+                    expect(KNOWN_CONTEXT_KEYS, `context key of ${step.id}`).to.include(event.substring('onContext:'.length));
+                } else {
+                    // An `onLink:` event only ever fires for a link the step actually offers.
+                    expect(event, `completion event of ${step.id}`).to.match(/^onLink:/);
+                    expect(step.description, `link of ${step.id}`).to.include(`(${event.substring('onLink:'.length)})`);
+                }
+            }
+        }
+    });
+
+    it('should have a completion event for every step that can be verified', () => {
+        const withoutCompletion = walkthrough.steps.filter(step => !step.completionEvents?.length).map(step => step.id);
+        // The closing step only points at further reading, so there is nothing to observe; it is marked done by hand.
+        expect(withoutCompletion).to.deep.equal(['go-further']);
+    });
+});