feat: Add showInChat property to control agent visibility in chat (#16925)

Adds the ability to mark agents as non-chat agents, making them available
for programmatic use (e.g., delegation) while hiding them from the chat UI.

Changes:
- Add `showInChat` optional property to `CustomAgentDescription` interface
- Add `showInChat` to `AgentSettings` and preference schema (default: true)
- Update `ChatAgentService.getAgents()` to filter by `showInChat` preference
- Add "Show in Chat" toggle in AI Agent Configuration widget
- Pass `showInChat` from YAML through factory to initialize preference

The setting can be configured via:
1. YAML: `showInChat: false` in customAgents.yml
2. UI: Toggle in AI Configuration > Agents panel

Agents with showInChat=false are filtered from:
- Chat `@` autocomplete
- Agent selection dialogs
- Orchestrator delegation list

Tests:
- Type guard tests for CustomAgentDescription.showInChat
- ChatAgentServiceImpl filtering tests (getAgents, getAllAgents, settings updates)

Backward compatible: existing agents without the property default to visible.

Author: eneufeld

.prompts/project-info.prompttemplate

@@ -56,7 +56,8 @@ Tests are located in the same directory as the components under test.
 
 ### Compile and Test
 
-This projects uses npm.
+Use `npm` (not `yarn`) for all package management and script execution.
+
 If you want to compile something, run the linter or tests, prefer to execute them for changed packages first, as they will run faster. Only build the full project once you are
 done for a final validation. There are usually pre-defined tasks for all these operations, prefer to use these instead of npm directly.
 

packages/ai-chat/src/browser/ai-chat-frontend-module.ts

@@ -14,7 +14,7 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import { Agent, AgentService, AIVariableContribution, bindToolProvider } from '@theia/ai-core/lib/common';
+import { Agent, AgentService, AISettingsService, AIVariableContribution, bindToolProvider } from '@theia/ai-core/lib/common';
 import { bindContributionProvider, CommandContribution, PreferenceContribution } from '@theia/core';
 import { FrontendApplicationContribution, LabelProviderContribution } from '@theia/core/lib/browser';
 import { ContainerModule } from '@theia/core/shared/inversify';
@@ -129,8 +129,8 @@ export default new ContainerModule(bind => {
     bind(ToolConfirmationManager).toSelf().inSingletonScope();
 
     bind(CustomChatAgent).toSelf();
-    bind(CustomAgentFactory).toFactory<CustomChatAgent, [string, string, string, string, string]>(
-        ctx => (id: string, name: string, description: string, prompt: string, defaultLLM: string) => {
+    bind(CustomAgentFactory).toFactory<CustomChatAgent, [string, string, string, string, string, boolean | undefined]>(
+        ctx => (id: string, name: string, description: string, prompt: string, defaultLLM: string, showInChat?: boolean) => {
             const agent = ctx.container.get<CustomChatAgent>(CustomChatAgent);
             agent.id = id;
             agent.name = name;
@@ -142,6 +142,17 @@ export default new ContainerModule(bind => {
             }];
             ctx.container.get<ChatAgentService>(ChatAgentService).registerChatAgent(agent);
             ctx.container.get<AgentService>(AgentService).registerAgent(agent);
+
+            // Initialize showInChat preference from YAML if not already set
+            if (showInChat === false) {
+                const settingsService = ctx.container.get<AISettingsService>(AISettingsService);
+                settingsService.getAgentSettings(id).then(settings => {
+                    if (settings?.showInChat === undefined) {
+                        settingsService.updateAgentSettings(id, { showInChat: false });
+                    }
+                });
+            }
+
             return agent;
         });
     bind(FrontendApplicationContribution).to(AICustomAgentsFrontendApplicationContribution).inSingletonScope();

packages/ai-chat/src/browser/custom-agent-factory.ts

@@ -17,4 +17,4 @@
 import { CustomChatAgent } from '../common';
 
 export const CustomAgentFactory = Symbol('CustomAgentFactory');
-export type CustomAgentFactory = (id: string, name: string, description: string, prompt: string, defaultLLM: string) => CustomChatAgent;
+export type CustomAgentFactory = (id: string, name: string, description: string, prompt: string, defaultLLM: string, showInChat?: boolean) => CustomChatAgent;

packages/ai-chat/src/browser/custom-agent-frontend-application-contribution.ts

@@ -38,7 +38,7 @@ export class AICustomAgentsFrontendApplicationContribution implements FrontendAp
     onStart(): void {
         this.customizationService?.getCustomAgents().then(customAgents => {
             customAgents.forEach(agent => {
-                this.customAgentFactory(agent.id, agent.name, agent.description, agent.prompt, agent.defaultLLM);
+                this.customAgentFactory(agent.id, agent.name, agent.description, agent.prompt, agent.defaultLLM, agent.showInChat);
                 this.knownCustomAgents.set(agent.id, agent);
             });
         }).catch(e => {
@@ -59,7 +59,7 @@ export class AICustomAgentsFrontendApplicationContribution implements FrontendAp
                 });
                 customAgentsToAdd
                     .forEach(agent => {
-                        this.customAgentFactory(agent.id, agent.name, agent.description, agent.prompt, agent.defaultLLM);
+                        this.customAgentFactory(agent.id, agent.name, agent.description, agent.prompt, agent.defaultLLM, agent.showInChat);
                         this.knownCustomAgents.set(agent.id, agent);
                     });
             }).catch(e => {

packages/ai-chat/src/common/chat-agent-service.spec.ts

@@ -0,0 +1,225 @@
+// *****************************************************************************
+// 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 'reflect-metadata';
+
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { Container } from 'inversify';
+import { ContributionProvider, ILogger } from '@theia/core';
+import { Emitter } from '@theia/core/lib/common';
+import { AgentService, AISettings, AISettingsService } from '@theia/ai-core';
+import { ChatAgent } from './chat-agents';
+import { ChatAgentService, ChatAgentServiceImpl } from './chat-agent-service';
+
+describe('ChatAgentServiceImpl', () => {
+    let container: Container;
+    let chatAgentService: ChatAgentServiceImpl;
+    let sandbox: sinon.SinonSandbox;
+
+    let mockAgentService: AgentService;
+    let mockAISettingsService: AISettingsService;
+    let settingsStub: sinon.SinonStub;
+    let onDidChangeEmitter: Emitter<void>;
+    let mockContributionProvider: { getContributions: sinon.SinonStub };
+
+    // Test agents
+    const agent1: ChatAgent = {
+        id: 'agent1',
+        name: 'Agent 1',
+        description: 'Test agent 1',
+        variables: [],
+        functions: [],
+        agentSpecificVariables: [],
+        tags: [],
+        prompts: [],
+        languageModelRequirements: [],
+        locations: [],
+        invoke: sinon.stub()
+    };
+
+    const agent2: ChatAgent = {
+        id: 'agent2',
+        name: 'Agent 2',
+        description: 'Test agent 2',
+        variables: [],
+        functions: [],
+        agentSpecificVariables: [],
+        tags: [],
+        prompts: [],
+        languageModelRequirements: [],
+        locations: [],
+        invoke: sinon.stub()
+    };
+
+    const agent3: ChatAgent = {
+        id: 'agent3',
+        name: 'Agent 3',
+        description: 'Test agent 3',
+        variables: [],
+        functions: [],
+        agentSpecificVariables: [],
+        tags: [],
+        prompts: [],
+        languageModelRequirements: [],
+        locations: [],
+        invoke: sinon.stub()
+    };
+
+    function createContainer(settings: AISettings = {}): Container {
+        const testContainer = new Container();
+
+        // Mock AgentService
+        mockAgentService = {
+            isEnabled: () => true,
+            getAgents: () => [],
+            getAllAgents: () => [],
+            enableAgent: async () => { },
+            disableAgent: async () => { },
+            registerAgent: () => { },
+            unregisterAgent: () => { },
+            onDidChangeAgents: new Emitter<void>().event
+        };
+        testContainer.bind(AgentService).toConstantValue(mockAgentService);
+
+        // Mock AISettingsService with Event
+        onDidChangeEmitter = new Emitter<void>();
+        settingsStub = sandbox.stub().resolves(settings);
+        mockAISettingsService = {
+            getSettings: settingsStub,
+            getAgentSettings: async () => undefined,
+            updateAgentSettings: async () => { },
+            onDidChange: onDidChangeEmitter.event
+        };
+        testContainer.bind(AISettingsService).toConstantValue(mockAISettingsService);
+
+        // Mock ContributionProvider
+        mockContributionProvider = {
+            getContributions: sandbox.stub().returns([agent1, agent2, agent3])
+        };
+        testContainer.bind(ContributionProvider).toConstantValue(mockContributionProvider).whenTargetNamed(ChatAgent);
+
+        // Mock Logger
+        const mockLogger = {
+            debug: sandbox.stub(),
+            info: sandbox.stub(),
+            warn: sandbox.stub(),
+            error: sandbox.stub()
+        };
+        testContainer.bind(ILogger).toConstantValue(mockLogger as unknown as ILogger);
+
+        // Bind the service under test
+        testContainer.bind(ChatAgentService).to(ChatAgentServiceImpl).inSingletonScope();
+
+        return testContainer;
+    }
+
+    async function initializeService(settings: AISettings = {}): Promise<void> {
+        sandbox = sinon.createSandbox();
+        container = createContainer(settings);
+        chatAgentService = container.get<ChatAgentServiceImpl>(ChatAgentService);
+        // Wait for @postConstruct async initialization
+        await settingsStub();
+        // Allow promise chain to complete
+        await new Promise(resolve => setTimeout(resolve, 0));
+    }
+
+    afterEach(() => {
+        sandbox.restore();
+        onDidChangeEmitter?.dispose();
+    });
+
+    describe('getAgents() showInChat filtering', () => {
+        it('returns agents when showInChat preference is not set (default = visible)', async () => {
+            await initializeService({});
+
+            const agents = chatAgentService.getAgents();
+
+            expect(agents).to.have.lengthOf(3);
+            expect(agents.map(a => a.id)).to.include.members(['agent1', 'agent2', 'agent3']);
+        });
+
+        it('filters out agents where showInChat preference is false', async () => {
+            await initializeService({
+                agent1: { showInChat: false },
+                agent2: { showInChat: false }
+            });
+
+            const agents = chatAgentService.getAgents();
+
+            expect(agents).to.have.lengthOf(1);
+            expect(agents[0].id).to.equal('agent3');
+        });
+
+        it('includes agents where showInChat preference is true', async () => {
+            await initializeService({
+                agent1: { showInChat: true },
+                agent2: { showInChat: true },
+                agent3: { showInChat: true }
+            });
+
+            const agents = chatAgentService.getAgents();
+
+            expect(agents).to.have.lengthOf(3);
+            expect(agents.map(a => a.id)).to.include.members(['agent1', 'agent2', 'agent3']);
+        });
+    });
+
+    describe('getAllAgents()', () => {
+        it('returns all agents regardless of showInChat setting', async () => {
+            await initializeService({
+                agent1: { showInChat: false },
+                agent2: { showInChat: false },
+                agent3: { showInChat: false }
+            });
+
+            const allAgents = chatAgentService.getAllAgents();
+
+            expect(allAgents).to.have.lengthOf(3);
+            expect(allAgents.map(a => a.id)).to.include.members(['agent1', 'agent2', 'agent3']);
+        });
+    });
+
+    describe('onDidChange updates', () => {
+        it('updates filtered list when AISettingsService.onDidChange fires', async () => {
+            // Start with agent1 hidden
+            await initializeService({
+                agent1: { showInChat: false }
+            });
+
+            let agents = chatAgentService.getAgents();
+            expect(agents).to.have.lengthOf(2);
+            expect(agents.map(a => a.id)).to.not.include('agent1');
+
+            // Update settings to show agent1 and hide agent2
+            settingsStub.resolves({
+                agent2: { showInChat: false }
+            });
+
+            // Fire the change event
+            onDidChangeEmitter.fire();
+
+            // Wait for async update
+            await settingsStub();
+            await new Promise(resolve => setTimeout(resolve, 0));
+
+            agents = chatAgentService.getAgents();
+            expect(agents).to.have.lengthOf(2);
+            expect(agents.map(a => a.id)).to.include('agent1');
+            expect(agents.map(a => a.id)).to.not.include('agent2');
+        });
+    });
+});

packages/ai-chat/src/common/chat-agent-service.ts

@@ -20,9 +20,9 @@
 // Partially copied from https://github.com/microsoft/vscode/blob/a2cab7255c0df424027be05d58e1b7b941f4ea60/src/vs/workbench/contrib/chat/common/chatAgents.ts
 
 import { ContributionProvider, ILogger } from '@theia/core';
-import { inject, injectable, named } from '@theia/core/shared/inversify';
+import { inject, injectable, named, optional, postConstruct } from '@theia/core/shared/inversify';
 import { ChatAgent } from './chat-agents';
-import { AgentService } from '@theia/ai-core';
+import { AgentService, AISettingsService } from '@theia/ai-core';
 
 export const ChatAgentService = Symbol('ChatAgentService');
 export const ChatAgentServiceFactory = Symbol('ChatAgentServiceFactory');
@@ -67,8 +67,34 @@ export class ChatAgentServiceImpl implements ChatAgentService {
     @inject(AgentService)
     protected agentService: AgentService;
 
+    @inject(AISettingsService) @optional()
+    protected readonly aiSettingsService: AISettingsService | undefined;
+
     protected _agents: ChatAgent[] = [];
 
+    protected hiddenFromChatAgents = new Set<string>();
+
+    @postConstruct()
+    protected init(): void {
+        this.aiSettingsService?.getSettings().then(settings => {
+            Object.entries(settings).forEach(([agentId, agentSettings]) => {
+                if (agentSettings.showInChat === false) {
+                    this.hiddenFromChatAgents.add(agentId);
+                }
+            });
+        });
+        this.aiSettingsService?.onDidChange(() => {
+            this.aiSettingsService?.getSettings().then(settings => {
+                this.hiddenFromChatAgents.clear();
+                Object.entries(settings).forEach(([agentId, agentSettings]) => {
+                    if (agentSettings.showInChat === false) {
+                        this.hiddenFromChatAgents.add(agentId);
+                    }
+                });
+            });
+        });
+    }
+
     protected get agents(): ChatAgent[] {
         // We can't collect the contributions at @postConstruct because this will lead to a circular dependency
         // with chat agents reusing the chat agent service (e.g. orchestrator)
@@ -89,7 +115,7 @@ export class ChatAgentServiceImpl implements ChatAgentService {
         return this.getAgents().find(agent => agent.id === id);
     }
     getAgents(): ChatAgent[] {
-        return this.agents.filter(a => this._agentIsEnabled(a.id));
+        return this.agents.filter(a => this._agentIsEnabled(a.id) && this._agentShowsInChat(a.id));
     }
     getAllAgents(): ChatAgent[] {
         return this.agents;
@@ -98,4 +124,8 @@ export class ChatAgentServiceImpl implements ChatAgentService {
     private _agentIsEnabled(id: string): boolean {
         return this.agentService.isEnabled(id);
     }
+
+    private _agentShowsInChat(id: string): boolean {
+        return !this.hiddenFromChatAgents.has(id);
+    }
 }

packages/ai-core/src/browser/frontend-prompt-customization-service.ts

@@ -45,7 +45,8 @@ You are an example agent. Be nice and helpful to the user.
 ## Current Context
 Some files and other pieces of data may have been added by the user to the context of the chat. If any have, the details can be found below.
 {{contextDetails}}`,
-    defaultLLM: 'openai/gpt-4o'
+    defaultLLM: 'openai/gpt-4o',
+    showInChat: true
 };
 
 export enum CustomizationSource {

packages/ai-core/src/common/agent-preferences.ts

@@ -38,6 +38,13 @@ export const AgentSettingsPreferenceSchema: PreferenceSchema = {
                         markdownDescription: nls.localize('theia/ai/agents/enable/mdDescription', 'Specifies whether the agent should be enabled (true) or disabled (false).'),
                         default: true
                     },
+                    showInChat: {
+                        type: 'boolean',
+                        title: nls.localize('theia/ai/agents/showInChat/title', 'Show in Chat'),
+                        markdownDescription: nls.localize('theia/ai/agents/showInChat/mdDescription',
+                            'Specifies whether the agent should be shown in the chat UI (true) or hidden (false).'),
+                        default: true
+                    },
                     languageModelRequirements: {
                         type: 'array',
                         title: nls.localize('theia/ai/agents/languageModelRequirements/title', 'Language Model Requirements'),