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

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

@@ -0,0 +1,249 @@
+// *****************************************************************************
+// 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 { AI_CHAT_TOGGLE_COMMAND_ID } from '@theia/ai-chat-ui/lib/browser/ai-chat-ui-contribution';
+import { ChatAgentRecommendationService } from '@theia/ai-chat/lib/common';
+import { DEFAULT_CHAT_AGENT_PREF } from '@theia/ai-chat/lib/common/ai-chat-preferences';
+import { ENABLE_AI_CONTEXT_KEY } from '@theia/ai-core/lib/browser/ai-activation-service';
+import { AiConfigurationCategoryId } from '@theia/ai-core-ui/lib/browser/ai-configuration/ai-configuration-category';
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+import { PerspectiveServiceImpl } from '@theia/core/lib/browser/perspective-service';
+import { nls } from '@theia/core/lib/common/nls';
+import { WalkthroughProvider } from '@theia/getting-started/lib/common/walkthrough-provider';
+import { WalkthroughDefinition, WalkthroughStepDefinition } from '@theia/getting-started/lib/common/walkthrough-types';
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { WorkspaceCommands } from '@theia/workspace/lib/browser/workspace-commands';
+import { AI_SET_DEFAULT_CHAT_AGENT } from './ai-getting-started-commands';
+import { OPEN_AI_CONFIG_VIEW, OPEN_AI_CONFIG_VIEW_TOOLS } from './ai-configuration/ai-configuration-view-contribution';
+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';
+
+/**
+ * Id of the walkthrough that guides a new user through setting up and using the AI features.
+ * Also the argument of the `walkthrough.open` command.
+ */
+export const AI_GETTING_STARTED_WALKTHROUGH_ID = 'ai-features.getting-started';
+
+const AI_DOC_URL = 'https://theia-ide.org/docs/user_ai/';
+const THEIA_AI_DOC_URL = 'https://theia-ide.org/docs/theia_ai/';
+const FEEDBACK_URL = 'https://github.com/eclipse-theia/theia/issues/new/choose';
+
+/**
+ * Contributes the "Get started with AI" walkthrough to the welcome page: the single, progress-tracked path
+ * from disabled AI features to a first answer in the chat.
+ */
+@injectable()
+export class AiGettingStartedWalkthroughProvider implements WalkthroughProvider {
+
+    @inject(ChatAgentRecommendationService)
+    protected readonly recommendationService: ChatAgentRecommendationService;
+
+    protected walkthrough: WalkthroughDefinition | undefined;
+
+    getWalkthroughs(): WalkthroughDefinition[] {
+        // Built on demand rather than in the field initializer, so that the localization is in place.
+        this.walkthrough ??= this.createWalkthrough();
+        return [this.walkthrough];
+    }
+
+    protected get applicationName(): string {
+        return FrontendApplicationConfigProvider.get().applicationName;
+    }
+
+    /** Deep-links into the AI Configuration view, which takes a category id or an `ai-features.*` preference id. */
+    protected aiConfiguration(target?: string): string {
+        return `command:${OPEN_AI_CONFIG_VIEW.id}${target ? `?${target}` : ''}`;
+    }
+
+    protected createWalkthrough(): WalkthroughDefinition {
+        return {
+            id: AI_GETTING_STARTED_WALKTHROUGH_ID,
+            icon: 'sparkle',
+            title: nls.localize('theia/ai/ide/walkthrough/title', 'Get started with AI'),
+            description: nls.localize('theia/ai/ide/walkthrough/description', 'Set up the AI features of {0} and learn how to work with them.', this.applicationName),
+            steps: [
+                this.createAiSupportStep(),
+                this.createEnableStep(),
+                this.createModelStep(),
+                this.createAgentStep(),
+                this.createFirstQuestionStep(),
+                this.createToolConfirmationStep(),
+                this.createGoFurtherStep()
+            ]
+        };
+    }
+
+    /**
+     * The opening slide, carrying what the welcome page used to announce in its AI banner: what the features
+     * are, that they are opt-in and may incur costs, and the invitation to the community behind them.
+     */
+    protected createAiSupportStep(): WalkthroughStepDefinition {
+        return {
+            id: 'ai-support',
+            title: nls.localize('theia/ai/ide/walkthrough/aiSupport/title', 'AI support in {0}', this.applicationName),
+            description: nls.localize('theia/ai/ide/walkthrough/aiSupport/description', `
+{0} comes with AI support: chat with specialized agents about your project, let them change code and run tasks, complete code as you type and get help in the terminal.
+
+These features are disabled by default, so that you can opt in at your own discretion.
+
+Once enabled, they may generate continuous requests to the language models you provide access to. This might incur costs that you need to monitor closely.
+
+[Read the documentation]({1}).
+
+We welcome your feedback, contributions and sponsorship! Visit the [GitHub project]({2}) to support the ongoing development. Thank you for being part of our community!
+
+All of this is built on Theia AI, the framework for AI-powered tools and IDEs, published as a stable release. [Read the framework documentation]({3}).
+`, this.applicationName, AI_DOC_URL, FEEDBACK_URL, THEIA_AI_DOC_URL).trim(),
+            // Reading it is done once the user acts on it, either by following a link or by turning the features on.
+            completionEvents: [`onContext:${ENABLE_AI_CONTEXT_KEY}`, `onLink:${AI_DOC_URL}`]
+        };
+    }
+
+    protected createEnableStep(): WalkthroughStepDefinition {
+        return {
+            id: 'enable-ai',
+            title: nls.localize('theia/ai/ide/walkthrough/enableAi/title', 'Turn on the AI features'),
+            description: nls.localize('theia/ai/ide/walkthrough/enableAi/description', `
+Nothing is sent anywhere until you switch the AI features on, and you can switch them off again at any time.
+
+[Open the AI Configuration]({0}) and enable them there.
+`, this.aiConfiguration(ENABLE_AI_CONTEXT_KEY)).trim(),
+            completionEvents: [`onContext:${ENABLE_AI_CONTEXT_KEY}`]
+        };
+    }
+
+    protected createModelStep(): WalkthroughStepDefinition {
+        return {
+            id: 'connect-model',
+            title: nls.localize('theia/ai/ide/walkthrough/connectModel/title', 'Connect a language model'),
+            description: nls.localize('theia/ai/ide/walkthrough/connectModel/description', `
+Add an API key for a hosted provider:
+
+- [OpenAI]({0})
+- [Anthropic]({1})
+- [Google]({2})
+
+Prefer to stay local or use another service? Ollama, llamafile and any OpenAI-compatible endpoint can be set up in the [Models]({3}) page.
+
+Some agents bring their own model, for example Claude Code, and work without a provider.
+`, this.aiConfiguration('ai-features.openAiOfficial.openAiApiKey'),
+                this.aiConfiguration('ai-features.anthropic.AnthropicApiKey'),
+                this.aiConfiguration('ai-features.google.apiKey'),
+                this.aiConfiguration(AiConfigurationCategoryId.MODELS)).trim(),
+            completionEvents: [`onContext:${AI_MODEL_READY_CONTEXT_KEY}`]
+        };
+    }
+
+    protected createAgentStep(): WalkthroughStepDefinition {
+        const intro = nls.localize('theia/ai/ide/walkthrough/chooseAgent/intro', `
+Every chat request goes to an agent, and one of them answers whenever you do not name one yourself.
+
+**Set your default agent:**
+`).trim();
+        const outro = nls.localize('theia/ai/ide/walkthrough/chooseAgent/outro', `
+You can also [choose the default agent]({0}) in the settings, and address another one for a single message by starting it with *@AgentName*.
+The [Agents]({1}) page lists them all.
+`, this.aiConfiguration(DEFAULT_CHAT_AGENT_PREF), this.aiConfiguration(AiConfigurationCategoryId.AGENTS)).trim();
+        return {
+            id: 'choose-agent',
+            title: nls.localize('theia/ai/ide/walkthrough/chooseAgent/title', 'Choose your default agent'),
+            description: [intro, this.renderAgentChoices(), outro].filter(part => !!part).join('\n\n'),
+            completionEvents: [`onContext:${AI_DEFAULT_AGENT_CONTEXT_KEY}`]
+        };
+    }
+
+    /**
+     * One action per recommended agent, each setting it as the default right away.
+     *
+     * Every link stands alone in its paragraph, which is what the welcome page renders as a button, so this
+     * reads like the buttons the chat welcome used to offer. Products customize the list through
+     * {@link ChatAgentRecommendationService}.
+     */
+    protected renderAgentChoices(): string {
+        return this.recommendationService.getRecommendedAgents()
+            .map(agent => {
+                const command = `command:${AI_SET_DEFAULT_CHAT_AGENT.id}?${encodeURIComponent(JSON.stringify(agent.id))}`;
+                // Carried as the link title, so what the agent is good at stays available as a tooltip.
+                const title = agent.description ? ` "${agent.description.replace(/"/g, '')}"` : '';
+                return `[@${agent.label}](${command}${title})`;
+            })
+            .join('\n\n');
+    }
+
+    protected createFirstQuestionStep(): WalkthroughStepDefinition {
+        return {
+            id: 'first-question',
+            title: nls.localize('theia/ai/ide/walkthrough/firstQuestion/title', 'Ask your first question'),
+            description: nls.localize('theia/ai/ide/walkthrough/firstQuestion/description', `
+[Open the AI Chat]({0}) and ask something about your project.
+
+Two things make the answers a lot better:
+
+- *@AgentName* picks the agent for this message, for example *@Coder*.
+- *#* attaches context, for example *#file* or *#selectedText*. The paperclip button next to the input does the same.
+
+The chat remembers your sessions, so you can pick a conversation up later.
+`, `command:${AI_CHAT_TOGGLE_COMMAND_ID}`).trim(),
+            completionEvents: [`onContext:${AI_CHAT_USED_CONTEXT_KEY}`]
+        };
+    }
+
+    protected createToolConfirmationStep(): WalkthroughStepDefinition {
+        return {
+            id: 'tool-confirmation',
+            title: nls.localize('theia/ai/ide/walkthrough/toolConfirmation/title', 'Stay in control of what agents do'),
+            description: nls.localize('theia/ai/ide/walkthrough/toolConfirmation/description', `
+Agents act on your workspace through tools: they read files, run terminal commands or edit code.
+
+Every tool call asks for your confirmation first. In the [Tools]({0}) page you can change that default or pre-approve the tools you trust.
+
+AI features stay off entirely while a workspace is not trusted. [Manage workspace trust]({1}) to decide per project.
+`, `command:${OPEN_AI_CONFIG_VIEW_TOOLS.id}`, `command:${WorkspaceCommands.MANAGE_WORKSPACE_TRUST.id}`).trim(),
+            completionEvents: [
+                `onContext:${AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY}`,
+                `onLink:command:${OPEN_AI_CONFIG_VIEW_TOOLS.id}`
+            ]
+        };
+    }
+
+    protected createGoFurtherStep(): WalkthroughStepDefinition {
+        return {
+            id: 'go-further',
+            title: nls.localize('theia/ai/ide/walkthrough/goFurther/title', 'Go further'),
+            description: nls.localize('theia/ai/ide/walkthrough/goFurther/description', `
+The chat is only the beginning. AI also completes code as you type and assists in the terminal with *Ctrl+I*.
+
+- [Prompts and skills]({0}): read and adapt the instructions the agents work with.
+- [MCP servers]({1}): add tools beyond the ones {3} ships with.
+- [Token usage]({2}): see what your requests consume.
+- [Switch Perspective]({5}) (experimental): the *AI First* layout moves the chat into the main area, with the explorer and source control on the right.
+
+The AI History view, where available, shows what was actually sent to the model.
+
+There is more in [the documentation]({4}) - and your feedback is always welcome.
+`, this.aiConfiguration(AiConfigurationCategoryId.PROMPTS_AND_SKILLS),
+                this.aiConfiguration(AiConfigurationCategoryId.MCP_SERVERS),
+                this.aiConfiguration(AiConfigurationCategoryId.TOKEN_USAGE),
+                this.applicationName,
+                AI_DOC_URL,
+                `command:${PerspectiveServiceImpl.SWITCH_PERSPECTIVE_COMMAND.id}`).trim()
+        };
+    }
+}

package/src/browser/ai-walkthrough-context-keys.spec.ts

@@ -0,0 +1,209 @@
+// *****************************************************************************
+// 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
+// *****************************************************************************
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { expect } from 'chai';
+import { Emitter } from '@theia/core/lib/common/event';
+import { DEFAULT_CHAT_AGENT_PREF } from '@theia/ai-chat/lib/common/ai-chat-preferences';
+import { DEFAULT_TOOL_CONFIRMATION_PREFERENCE, TOOL_CONFIRMATION_PREFERENCE, ToolConfirmationMode } from '@theia/ai-chat/lib/common/chat-tool-preferences';
+import {
+    AI_CHAT_USED_CONTEXT_KEY,
+    AI_DEFAULT_AGENT_CONTEXT_KEY,
+    AI_MODEL_READY_CONTEXT_KEY,
+    AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY,
+    AiWalkthroughContextKeys
+} from './ai-walkthrough-context-keys';
+
+describe('AiWalkthroughContextKeys', () => {
+
+    let contextKeys: AiWalkthroughContextKeys;
+    let keyValues: Record<string, boolean>;
+    let models: { status: { status: string } }[];
+    let sessions: { title?: string }[];
+    let persistedSessions: boolean;
+    let preferences: Record<string, unknown>;
+    let productDefaults: Record<string, unknown>;
+    let onLanguageModelChangeEmitter: Emitter<void>;
+    let onSessionEventEmitter: Emitter<void>;
+    let onPreferenceChangedEmitter: Emitter<{ preferenceName: string }>;
+
+    beforeEach(() => {
+        keyValues = {};
+        models = [];
+        sessions = [];
+        persistedSessions = false;
+        preferences = {};
+        productDefaults = {};
+        onLanguageModelChangeEmitter = new Emitter();
+        onSessionEventEmitter = new Emitter();
+        onPreferenceChangedEmitter = new Emitter();
+
+        contextKeys = new AiWalkthroughContextKeys();
+        (contextKeys as any).contextKeyService = {
+            createKey: (key: string, defaultValue: boolean) => {
+                keyValues[key] = defaultValue;
+                return {
+                    get: () => keyValues[key],
+                    set: (value: boolean) => { keyValues[key] = value; }
+                };
+            }
+        };
+        (contextKeys as any).languageModelRegistry = {
+            onChange: onLanguageModelChangeEmitter.event,
+            getLanguageModels: () => Promise.resolve(models)
+        };
+        (contextKeys as any).chatService = {
+            onSessionEvent: onSessionEventEmitter.event,
+            getSessions: () => sessions,
+            hasPersistedSessions: () => Promise.resolve(persistedSessions)
+        };
+        (contextKeys as any).preferenceService = {
+            onPreferenceChanged: onPreferenceChangedEmitter.event,
+            ready: Promise.resolve(),
+            get: (key: string, defaultValue: unknown) => preferences[key] ?? defaultValue,
+            // Only the values the user set, which is what distinguishes a decision from a product default.
+            inspect: (key: string) => ({ preferenceName: key, defaultValue: productDefaults[key], globalValue: preferences[key] })
+        };
+        (contextKeys as any).init();
+    });
+
+    afterEach(() => {
+        contextKeys.onStop();
+        onLanguageModelChangeEmitter.dispose();
+        onSessionEventEmitter.dispose();
+        onPreferenceChangedEmitter.dispose();
+    });
+
+    describe(AI_MODEL_READY_CONTEXT_KEY, () => {
+        it('should be false without a usable model', async () => {
+            models = [{ status: { status: 'unavailable' } }];
+            await (contextKeys as any).updateModelState();
+
+            expect(keyValues[AI_MODEL_READY_CONTEXT_KEY]).to.be.false;
+        });
+
+        it('should become true once a model is ready', async () => {
+            models = [{ status: { status: 'unavailable' } }, { status: { status: 'ready' } }];
+            await (contextKeys as any).updateModelState();
+
+            expect(keyValues[AI_MODEL_READY_CONTEXT_KEY]).to.be.true;
+        });
+
+        it('should follow the registry when a model becomes unusable again', async () => {
+            models = [{ status: { status: 'ready' } }];
+            await (contextKeys as any).updateModelState();
+
+            models = [{ status: { status: 'unavailable' } }];
+            await (contextKeys as any).updateModelState();
+
+            expect(keyValues[AI_MODEL_READY_CONTEXT_KEY]).to.be.false;
+        });
+    });
+
+    describe(AI_CHAT_USED_CONTEXT_KEY, () => {
+        it('should be false while no chat was held', async () => {
+            sessions = [{}];
+            await (contextKeys as any).updateChatState();
+
+            expect(keyValues[AI_CHAT_USED_CONTEXT_KEY]).to.be.false;
+        });
+
+        it('should become true for a session that has a title', async () => {
+            sessions = [{ title: 'How do I build this?' }];
+            await (contextKeys as any).updateChatState();
+
+            expect(keyValues[AI_CHAT_USED_CONTEXT_KEY]).to.be.true;
+        });
+
+        it('should become true for a persisted session of an earlier run', async () => {
+            persistedSessions = true;
+            await (contextKeys as any).updateChatState();
+
+            expect(keyValues[AI_CHAT_USED_CONTEXT_KEY]).to.be.true;
+        });
+
+        it('should stay true once the chats are gone', async () => {
+            sessions = [{ title: 'How do I build this?' }];
+            await (contextKeys as any).updateChatState();
+
+            sessions = [];
+            await (contextKeys as any).updateChatState();
+
+            expect(keyValues[AI_CHAT_USED_CONTEXT_KEY]).to.be.true;
+        });
+
+        it('should not fail when the persisted sessions cannot be read', async () => {
+            (contextKeys as any).chatService.hasPersistedSessions = () => Promise.reject(new Error('no storage'));
+
+            await (contextKeys as any).updateChatState();
+
+            expect(keyValues[AI_CHAT_USED_CONTEXT_KEY]).to.be.false;
+        });
+    });
+
+    describe(AI_DEFAULT_AGENT_CONTEXT_KEY, () => {
+        it('should be false while no default agent is configured', () => {
+            (contextKeys as any).updateDefaultAgentState();
+
+            expect(keyValues[AI_DEFAULT_AGENT_CONTEXT_KEY]).to.be.false;
+        });
+
+        it('should be true for a configured default agent', () => {
+            preferences[DEFAULT_CHAT_AGENT_PREF] = 'Coder';
+            (contextKeys as any).updateDefaultAgentState();
+
+            expect(keyValues[AI_DEFAULT_AGENT_CONTEXT_KEY]).to.be.true;
+        });
+    });
+
+    describe(AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY, () => {
+        it('should be false while every tool call is confirmed and no tool was pre-approved', () => {
+            (contextKeys as any).updateToolConfirmationState();
+
+            expect(keyValues[AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY]).to.be.false;
+        });
+
+        it('should be true once the default mode was changed', () => {
+            preferences[DEFAULT_TOOL_CONFIRMATION_PREFERENCE] = ToolConfirmationMode.ALWAYS_ALLOW;
+            (contextKeys as any).updateToolConfirmationState();
+
+            expect(keyValues[AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY]).to.be.true;
+        });
+
+        it('should be true once single tools were pre-approved', () => {
+            preferences[TOOL_CONFIRMATION_PREFERENCE] = { 'some-tool': ToolConfirmationMode.ALWAYS_ALLOW };
+            (contextKeys as any).updateToolConfirmationState();
+
+            expect(keyValues[AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY]).to.be.true;
+        });
+
+        it('should stay false for defaults the product ships rather than the user setting them', () => {
+            productDefaults[DEFAULT_TOOL_CONFIRMATION_PREFERENCE] = ToolConfirmationMode.ALWAYS_ALLOW;
+            productDefaults[TOOL_CONFIRMATION_PREFERENCE] = { 'some-tool': ToolConfirmationMode.ALWAYS_ALLOW };
+            (contextKeys as any).updateToolConfirmationState();
+
+            expect(keyValues[AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY]).to.be.false;
+        });
+
+        it('should stay false after the per-tool settings were reset to an empty map', () => {
+            preferences[TOOL_CONFIRMATION_PREFERENCE] = {};
+            (contextKeys as any).updateToolConfirmationState();
+
+            expect(keyValues[AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY]).to.be.false;
+        });
+    });
+});

package/src/browser/ai-walkthrough-context-keys.ts

@@ -0,0 +1,147 @@
+// *****************************************************************************
+// 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 { ChatService } from '@theia/ai-chat/lib/common';
+import { DEFAULT_CHAT_AGENT_PREF } from '@theia/ai-chat/lib/common/ai-chat-preferences';
+import { DEFAULT_TOOL_CONFIRMATION_PREFERENCE, TOOL_CONFIRMATION_PREFERENCE } from '@theia/ai-chat/lib/common/chat-tool-preferences';
+import { FrontendLanguageModelRegistry } from '@theia/ai-core/lib/common';
+import { ContextKey, ContextKeyService } from '@theia/core/lib/browser/context-key-service';
+import { FrontendApplicationContribution } from '@theia/core/lib/browser/frontend-application-contribution';
+import { DisposableCollection } from '@theia/core/lib/common/disposable';
+import { PreferenceService } from '@theia/core/lib/common/preferences';
+import { inject, injectable, postConstruct } from '@theia/core/shared/inversify';
+
+/** True as soon as at least one language model is ready to be used. */
+export const AI_MODEL_READY_CONTEXT_KEY = 'ai.hasReadyLanguageModel';
+/** True as soon as the user has held at least one conversation with an agent. */
+export const AI_CHAT_USED_CONTEXT_KEY = 'ai.chat.hasRequest';
+/** True while a default chat agent is configured. */
+export const AI_DEFAULT_AGENT_CONTEXT_KEY = 'ai.chat.hasDefaultAgent';
+/** True once the user has decided how tool calls are confirmed, instead of staying on the default. */
+export const AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY = 'ai.chat.toolConfirmationConfigured';
+
+/**
+ * Publishes the state that the getting started walkthrough observes to tick off its steps.
+ *
+ * The keys describe what the user achieved rather than what they clicked. A step is therefore only completed
+ * once the setup actually works, and a user who configured everything before ever opening the walkthrough
+ * finds it completed rather than waiting for changes that already happened.
+ */
+@injectable()
+export class AiWalkthroughContextKeys implements FrontendApplicationContribution {
+
+    @inject(ContextKeyService)
+    protected readonly contextKeyService: ContextKeyService;
+
+    @inject(FrontendLanguageModelRegistry)
+    protected readonly languageModelRegistry: FrontendLanguageModelRegistry;
+
+    @inject(ChatService)
+    protected readonly chatService: ChatService;
+
+    @inject(PreferenceService)
+    protected readonly preferenceService: PreferenceService;
+
+    protected readonly toDispose = new DisposableCollection();
+
+    protected hasReadyLanguageModel: ContextKey<boolean>;
+    protected hasChatRequest: ContextKey<boolean>;
+    protected hasDefaultAgent: ContextKey<boolean>;
+    protected toolConfirmationConfigured: ContextKey<boolean>;
+
+    @postConstruct()
+    protected init(): void {
+        this.hasReadyLanguageModel = this.contextKeyService.createKey(AI_MODEL_READY_CONTEXT_KEY, false);
+        this.hasChatRequest = this.contextKeyService.createKey(AI_CHAT_USED_CONTEXT_KEY, false);
+        this.hasDefaultAgent = this.contextKeyService.createKey(AI_DEFAULT_AGENT_CONTEXT_KEY, false);
+        this.toolConfirmationConfigured = this.contextKeyService.createKey(AI_TOOL_CONFIRMATION_CONFIGURED_CONTEXT_KEY, false);
+
+        this.toDispose.push(this.languageModelRegistry.onChange(() => this.updateModelState()));
+        this.toDispose.push(this.chatService.onSessionEvent(() => this.updateChatState()));
+        this.toDispose.push(this.preferenceService.onPreferenceChanged(event => {
+            if (event.preferenceName === DEFAULT_CHAT_AGENT_PREF) {
+                this.updateDefaultAgentState();
+            } else if (event.preferenceName === DEFAULT_TOOL_CONFIRMATION_PREFERENCE || event.preferenceName === TOOL_CONFIRMATION_PREFERENCE) {
+                this.updateToolConfirmationState();
+            }
+        }));
+
+        this.updateModelState();
+        this.updateChatState();
+        this.preferenceService.ready.then(() => {
+            this.updateDefaultAgentState();
+            this.updateToolConfirmationState();
+        });
+    }
+
+    protected async updateModelState(): Promise<void> {
+        const models = await this.languageModelRegistry.getLanguageModels();
+        this.hasReadyLanguageModel.set(models.some(model => model.status.status === 'ready'));
+    }
+
+    /**
+     * A session gets its title from its first exchange, so a titled or persisted session means the user has
+     * asked something. Once true, the key stays true: the achievement does not go away when a chat is deleted.
+     */
+    protected async updateChatState(): Promise<void> {
+        if (this.hasChatRequest.get()) {
+            return;
+        }
+        if (this.chatService.getSessions().some(session => !!session.title)) {
+            this.hasChatRequest.set(true);
+            return;
+        }
+        try {
+            if (await this.chatService.hasPersistedSessions()) {
+                this.hasChatRequest.set(true);
+            }
+        } catch {
+            // The persisted sessions cannot be read; the key is updated again on the next session event.
+        }
+    }
+
+    protected updateDefaultAgentState(): void {
+        this.hasDefaultAgent.set(!!this.preferenceService.get<string>(DEFAULT_CHAT_AGENT_PREF, ''));
+    }
+
+    /**
+     * The user has taken a stance on tool confirmation as soon as they changed the default mode or
+     * pre-approved individual tools.
+     */
+    protected updateToolConfirmationState(): void {
+        this.toolConfirmationConfigured.set(
+            this.isSetByUser(DEFAULT_TOOL_CONFIRMATION_PREFERENCE) || this.isSetByUser(TOOL_CONFIRMATION_PREFERENCE)
+        );
+    }
+
+    /**
+     * Whether a preference carries a value the user set, rather than the one the product ships.
+     *
+     * The effective value cannot answer this: a product is free to ship its own confirmation defaults, and
+     * reading those back as a decision would tick the step for a user who never saw it. An empty object does
+     * not count either, since that is what resetting the per-tool settings leaves behind.
+     */
+    protected isSetByUser(preferenceName: string): boolean {
+        const inspection = this.preferenceService.inspect(preferenceName);
+        return [inspection?.globalValue, inspection?.workspaceValue, inspection?.workspaceFolderValue].some(
+            value => value !== undefined && !(typeof value === 'object' && Object.keys(value as object).length === 0)
+        );
+    }
+
+    onStop(): void {
+        this.toDispose.dispose();
+    }
+}

package/src/browser/chat-session-item.tsx

@@ -262,8 +262,8 @@ export function ChatSessionItem(props: ChatSessionItemComponentProps): React.Rea
                         tabIndex={0}
                         aria-expanded={isExpanded}
                         aria-label={isExpanded
-                            ? nls.localize('theia/ai/ide/collapseSession', 'Collapse {0}', title)
-                            : nls.localize('theia/ai/ide/expandSession', 'Expand {0}', title)}>
+                            ? nls.localizeByDefault('Collapse {0}', title)
+                            : nls.localizeByDefault('Expand {0}', title)}>
                         <span className={`codicon ${isExpanded ? 'codicon-chevron-down' : 'codicon-chevron-right'}`} />
                     </span>
                 ) : (