feat(ai-chat): add mode selection for Coder and Architect agents

planger · planger · commit 42e59863cccd · 2026-01-28T10:01:21.000+01:00
Introduce mode selection UI for AI chat agents, allowing users to switch
between different prompt variants (e.g., Edit Mode, Agent Mode) directly
from the chat input. Modes map to prompt variant IDs and override the
settings-configured default when selected.

Changes:
- Add `isDefault` property to `ChatMode` interface for bidirectional sync
- Create `AbstractModeAwareChatAgent` base class with shared mode logic
- Update `CoderAgent` with Edit, Agent, and Agent Next modes
- Update `ArchitectAgent` with Default, Simple, and Plan modes
- Initialize mode selector from agent's settings-configured default
- Export architect prompt ID constants for mode mapping
diff --git a/packages/ai-chat-ui/src/browser/chat-input-widget.tsx b/packages/ai-chat-ui/src/browser/chat-input-widget.tsx
@@ -364,9 +364,12 @@ export class AIChatInputWidget extends ReactWidget {
                 // Only update and re-render when the agent changes
                 if (agent && agentId !== previousAgentId) {
                     const modes = agent.modes ?? [];
+                    const defaultMode = modes.find(m => m.isDefault);
+                    const initialModeId = defaultMode?.id;
                     this.receivingAgent = {
                         agentId: agentId,
-                        modes
+                        modes,
+                        currentModeId: initialModeId
                     };
                     this.chatInputHasModesKey.set(modes.length > 1);
                     this.update();
@@ -494,6 +497,7 @@ export class AIChatInputWidget extends ReactWidget {
                     this.editorRef = editor;
                     this.setupEditorEventListeners();
                     this.editorReady.resolve();
+                    this.scheduleUpdateReceivingAgent();
                 }}
                 showContext={this.configuration?.showContext}
                 showPinnedAgent={this.configuration?.showPinnedAgent}
diff --git a/packages/ai-chat/src/common/chat-agents.ts b/packages/ai-chat/src/common/chat-agents.ts
@@ -143,6 +143,7 @@ export namespace ChatAgentLocation {
 export interface ChatMode {
     readonly id: string;
     readonly name: string;
+    readonly isDefault?: boolean;
 }
 
 export const ChatAgent = Symbol('ChatAgent');
diff --git a/packages/ai-ide/src/browser/architect-agent.ts b/packages/ai-ide/src/browser/architect-agent.ts
@@ -13,17 +13,21 @@
 //
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
-import { AbstractStreamParsingChatAgent, ChatRequestModel, ChatService, ChatSession, MutableChatModel, MutableChatRequestModel } from '@theia/ai-chat/lib/common';
+import {
+    ChatMode, ChatRequestModel, ChatService, ChatSession,
+    MutableChatModel, MutableChatRequestModel
+} from '@theia/ai-chat/lib/common';
 import { TaskContextStorageService } from '@theia/ai-chat/lib/browser/task-context-service';
 import { LanguageModelRequirement } from '@theia/ai-core';
 import { inject, injectable } from '@theia/core/shared/inversify';
-import { architectSystemVariants, ARCHITECT_PLANNING_PROMPT_ID } from '../common/architect-prompt-template';
+import { architectSystemVariants, ARCHITECT_DEFAULT_PROMPT_ID, ARCHITECT_PLANNING_PROMPT_ID, ARCHITECT_SIMPLE_PROMPT_ID } from '../common/architect-prompt-template';
 import { nls } from '@theia/core';
 import { MarkdownStringImpl } from '@theia/core/lib/common/markdown-rendering';
 import { AI_SUMMARIZE_SESSION_AS_TASK_FOR_CODER, AI_UPDATE_TASK_CONTEXT_COMMAND, AI_EXECUTE_PLAN_WITH_CODER } from '../common/summarize-session-commands';
+import { AbstractModeAwareChatAgent } from './mode-aware-chat-agent';
 
 @injectable()
-export class ArchitectAgent extends AbstractStreamParsingChatAgent {
+export class ArchitectAgent extends AbstractModeAwareChatAgent {
     @inject(ChatService) protected readonly chatService: ChatService;
     @inject(TaskContextStorageService) protected readonly taskContextStorageService: TaskContextStorageService;
 
@@ -39,6 +43,22 @@ export class ArchitectAgent extends AbstractStreamParsingChatAgent {
         'An AI assistant integrated into Theia IDE, designed to assist software developers. This agent can access the users workspace, it can get a list of all available files \
          and folders and retrieve their content. It cannot modify files. It can therefore answer questions about the current project, project files and source code in the \
          workspace, such as how to build the project, where to put source code, where to find specific code or configurations, etc.');
+
+    protected readonly modeDefinitions: Omit<ChatMode, 'isDefault'>[] = [
+        {
+            id: ARCHITECT_DEFAULT_PROMPT_ID,
+            name: nls.localize('theia/ai/ide/architectAgent/mode/default', 'Default Mode')
+        },
+        {
+            id: ARCHITECT_SIMPLE_PROMPT_ID,
+            name: nls.localize('theia/ai/ide/architectAgent/mode/simple', 'Simple Mode')
+        },
+        {
+            id: ARCHITECT_PLANNING_PROMPT_ID,
+            name: nls.localize('theia/ai/ide/architectAgent/mode/plan', 'Plan Mode')
+        },
+    ];
+
     override prompts = [architectSystemVariants];
     protected override systemPromptId: string | undefined = architectSystemVariants.id;
 
diff --git a/packages/ai-ide/src/browser/coder-agent.ts b/packages/ai-ide/src/browser/coder-agent.ts
@@ -13,10 +13,16 @@
 //
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
-import { AbstractStreamParsingChatAgent, ChatRequestModel, ChatService, ChatSession, MutableChatModel, MutableChatRequestModel } from '@theia/ai-chat/lib/common';
+import {
+    ChatMode, ChatRequestModel, ChatService, ChatSession,
+    MutableChatModel, MutableChatRequestModel
+} from '@theia/ai-chat/lib/common';
 import { inject, injectable } from '@theia/core/shared/inversify';
 import {
     CODER_SYSTEM_PROMPT_ID,
+    CODER_EDIT_TEMPLATE_ID,
+    CODER_AGENT_MODE_TEMPLATE_ID,
+    CODER_AGENT_MODE_NEXT_TEMPLATE_ID,
     getCoderAgentModePromptTemplate,
     getCoderAgentModeNextPromptTemplate,
     getCoderPromptTemplateEdit,
@@ -27,9 +33,10 @@ import { LanguageModelRequirement, PromptVariantSet } from '@theia/ai-core';
 import { nls } from '@theia/core';
 import { MarkdownStringImpl } from '@theia/core/lib/common/markdown-rendering';
 import { AI_CHAT_NEW_CHAT_WINDOW_COMMAND, ChatCommands } from '@theia/ai-chat-ui/lib/browser/chat-view-commands';
+import { AbstractModeAwareChatAgent } from './mode-aware-chat-agent';
 
 @injectable()
-export class CoderAgent extends AbstractStreamParsingChatAgent {
+export class CoderAgent extends AbstractModeAwareChatAgent {
     @inject(ChatService) protected readonly chatService: ChatService;
     id: string = 'Coder';
     name = 'Coder';
@@ -43,6 +50,22 @@ export class CoderAgent extends AbstractStreamParsingChatAgent {
         'An AI assistant integrated into Theia IDE, designed to assist software developers. This agent can access the users workspace, it can get a list of all available files \
         and folders and retrieve their content. Furthermore, it can suggest modifications of files to the user. It can therefore assist the user with coding tasks or other \
         tasks involving file changes.');
+
+    protected readonly modeDefinitions: Omit<ChatMode, 'isDefault'>[] = [
+        {
+            id: CODER_EDIT_TEMPLATE_ID,
+            name: nls.localize('theia/ai/ide/coderAgent/mode/edit', 'Edit Mode')
+        },
+        {
+            id: CODER_AGENT_MODE_TEMPLATE_ID,
+            name: nls.localizeByDefault('Agent Mode')
+        },
+        {
+            id: CODER_AGENT_MODE_NEXT_TEMPLATE_ID,
+            name: nls.localize('theia/ai/ide/coderAgent/mode/agentNext', 'Agent Mode (Next)')
+        },
+    ];
+
     override prompts: PromptVariantSet[] = [{
         id: CODER_SYSTEM_PROMPT_ID,
         defaultVariant: getCoderPromptTemplateEdit(),
diff --git a/packages/ai-ide/src/browser/mode-aware-chat-agent.ts b/packages/ai-ide/src/browser/mode-aware-chat-agent.ts
@@ -0,0 +1,98 @@
+// *****************************************************************************
+// 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 {
+    AbstractStreamParsingChatAgent, ChatMode, ChatSessionContext, SystemMessageDescription
+} from '@theia/ai-chat/lib/common';
+import { AIVariableContext } from '@theia/ai-core';
+import { injectable } from '@theia/core/shared/inversify';
+
+/**
+ * An abstract chat agent that supports mode selection for selecting prompt variants.
+ *
+ * Agents extending this class define their available modes via `modeDefinitions`.
+ * The `modes` getter dynamically computes which mode is the default based on the
+ * current prompt variant settings. When a request is made with a specific `modeId`,
+ * that mode's prompt variant is used instead of the settings-configured default.
+ */
+@injectable()
+export abstract class AbstractModeAwareChatAgent extends AbstractStreamParsingChatAgent {
+    /**
+     * Mode definitions without the `isDefault` property.
+     * Subclasses must provide their specific mode definitions.
+     * Each mode's `id` should correspond to a prompt variant ID.
+     */
+    protected abstract readonly modeDefinitions: Omit<ChatMode, 'isDefault'>[];
+
+    /**
+     * The ID of the prompt variant set used for mode selection.
+     * Defaults to `systemPromptId`. Override if a different variant set should be used.
+     */
+    protected get promptVariantSetId(): string | undefined {
+        return this.systemPromptId;
+    }
+
+    /**
+     * Returns the available modes with `isDefault` computed based on current settings.
+     */
+    get modes(): ChatMode[] {
+        const variantSetId = this.promptVariantSetId;
+        if (!variantSetId) {
+            return this.modeDefinitions.map(mode => ({ ...mode, isDefault: false }));
+        }
+        const effectiveVariantId = this.promptService.getEffectiveVariantId(variantSetId);
+        return this.modeDefinitions.map(mode => ({
+            ...mode,
+            isDefault: mode.id === effectiveVariantId
+        }));
+    }
+
+    protected override async getSystemMessageDescription(context: AIVariableContext): Promise<SystemMessageDescription | undefined> {
+        if (this.systemPromptId === undefined) {
+            return undefined;
+        }
+
+        // Check for mode-based override from request
+        const modeId = ChatSessionContext.is(context) ? context.request?.request.modeId : undefined;
+        const effectiveVariantId = this.getEffectiveVariantIdWithMode(modeId);
+
+        if (!effectiveVariantId) {
+            return undefined;
+        }
+
+        const isEdited = this.isPromptVariantCustomized(effectiveVariantId);
+        const resolvedPrompt = await this.promptService.getResolvedPromptFragment(effectiveVariantId, undefined, context);
+        return resolvedPrompt ? SystemMessageDescription.fromResolvedPromptFragment(resolvedPrompt, effectiveVariantId, isEdited) : undefined;
+    }
+
+    /**
+     * Determines the effective variant ID, considering mode override.
+     * If modeId is provided and is a valid variant for the prompt set, it takes precedence.
+     * Otherwise falls back to settings-based selection.
+     */
+    protected getEffectiveVariantIdWithMode(modeId?: string): string | undefined {
+        const variantSetId = this.promptVariantSetId;
+        if (!variantSetId) {
+            return undefined;
+        }
+        if (modeId) {
+            const variantIds = this.promptService.getVariantIds(variantSetId);
+            if (variantIds.includes(modeId)) {
+                return modeId;
+            }
+        }
+        return this.promptService.getEffectiveVariantId(variantSetId);
+    }
+}
diff --git a/packages/ai-ide/src/common/architect-prompt-template.ts b/packages/ai-ide/src/common/architect-prompt-template.ts
@@ -29,11 +29,13 @@ import {
 } from './task-context-function-ids';
 
 export const ARCHITECT_PLANNING_PROMPT_ID = 'architect-system-planning-next';
+export const ARCHITECT_SIMPLE_PROMPT_ID = 'architect-system-simple';
+export const ARCHITECT_DEFAULT_PROMPT_ID = 'architect-system-default';
 
 export const architectSystemVariants = <PromptVariantSet>{
     id: 'architect-system',
     defaultVariant: {
-        id: 'architect-system-default',
+        id: ARCHITECT_DEFAULT_PROMPT_ID,
         template: `{{!-- This prompt is licensed under the MIT License (https://opensource.org/license/mit).
 Made improvements or adaptations to this prompt template? We'd love for you to share it with the community! Contribute back here:
 https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-contribution --}}
@@ -72,7 +74,7 @@ Always look at the relevant files to understand your task using the function ~{$
     },
     variants: [
         {
-            id: 'architect-system-simple',
+            id: ARCHITECT_SIMPLE_PROMPT_ID,
             template: `{{!-- This prompt is licensed under the MIT License (https://opensource.org/license/mit).
 Made improvements or adaptations to this prompt template? We'd love for you to share it with the community! Contribute back here:
 https://github.com/eclipse-theia/theia/discussions/new?category=prompt-template-contribution --}}

Original file line number	Diff line number	Diff line change
`@@ -143,6 +143,7 @@ export namespace ChatAgentLocation {`
`143`	`143`	`export interface ChatMode {`
`144`	`144`	`readonly id: string;`
`145`	`145`	`readonly name: string;`
	`146`	`+ readonly isDefault?: boolean;`
`146`	`147`	`}`
`147`	`148`
`148`	`149`	`export const ChatAgent = Symbol('ChatAgent');`