@theia/ai-copilot 1.75.0 → 1.76.0-next.10

package/src/node/copilot-language-models-manager-impl.spec.ts

@@ -0,0 +1,137 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH 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 { expect } from 'chai';
+import { LanguageModel, LanguageModelStatus } from '@theia/ai-core';
+import { MockLogger } from '@theia/core/lib/common/test/mock-logger';
+import { CopilotAuthState } from '../common/copilot-auth-service';
+import { CopilotLanguageModelsManagerImpl } from './copilot-language-models-manager-impl';
+
+/** A registry that records the models and the patches it received. */
+class FakeRegistry {
+
+    readonly models: LanguageModel[] = [];
+    readonly patches: Array<{ id: string, patch: Partial<LanguageModel> }> = [];
+
+    async getLanguageModel(id: string): Promise<LanguageModel | undefined> {
+        return this.models.find(model => model.id === id);
+    }
+
+    async getLanguageModels(): Promise<LanguageModel[]> {
+        return this.models;
+    }
+
+    addLanguageModels(models: LanguageModel[]): void {
+        this.models.push(...models);
+    }
+
+    removeLanguageModels(ids: string[]): void {
+        for (const id of ids) {
+            const index = this.models.findIndex(model => model.id === id);
+            if (index >= 0) {
+                this.models.splice(index, 1);
+            }
+        }
+    }
+
+    async patchLanguageModel(id: string, patch: Partial<LanguageModel>): Promise<void> {
+        this.patches.push({ id, patch });
+        Object.assign(this.models.find(model => model.id === id) ?? {}, patch);
+    }
+}
+
+class TestableCopilotLanguageModelsManagerImpl extends CopilotLanguageModelsManagerImpl {
+
+    authState: CopilotAuthState = { isAuthenticated: true };
+    listFailure: Error | undefined;
+    modelIds: string[] = ['gpt-5'];
+
+    constructor(readonly registry: FakeRegistry) {
+        super();
+        Object.assign(this, {
+            logger: new MockLogger(),
+            languageModelRegistry: registry,
+            authService: {
+                getAuthState: async () => this.authState,
+                onAuthStateChanged: () => ({ dispose: () => { } })
+            },
+            sdkClientProvider: {
+                listModelIds: async () => {
+                    if (this.listFailure) {
+                        throw this.listFailure;
+                    }
+                    return this.modelIds;
+                }
+            }
+        });
+    }
+
+    callCalculateStatus(): Promise<LanguageModelStatus> {
+        return this.calculateStatus();
+    }
+}
+
+describe('CopilotLanguageModelsManagerImpl - status', () => {
+
+    let manager: TestableCopilotLanguageModelsManagerImpl;
+
+    beforeEach(() => {
+        manager = new TestableCopilotLanguageModelsManagerImpl(new FakeRegistry());
+    });
+
+    it('should report a model as ready for a user who is signed in', async () => {
+        await manager.createOrUpdateLanguageModels({ id: 'copilot/gpt-5', model: 'gpt-5', maxRetries: 3 });
+        expect(manager.registry.models[0].status).to.deep.equal({ status: 'ready' });
+    });
+
+    it('should report a model as unavailable while nobody is signed in', async () => {
+        manager.authState = { isAuthenticated: false };
+        expect(await manager.callCalculateStatus()).to.deep.include({ status: 'unavailable' });
+    });
+
+    it('should report models as unavailable when they cannot be listed, rather than as ready', async () => {
+        manager.listFailure = new Error('not authorized to use this Copilot feature');
+        expect(await manager.fetchAvailableModelIds()).to.be.empty;
+        const status = await manager.callCalculateStatus();
+        expect(status.status).to.equal('unavailable');
+        expect(status.message).to.contain('not authorized');
+    });
+
+    it('should reflect a failed listing in the models that are already registered', async () => {
+        await manager.createOrUpdateLanguageModels({ id: 'copilot/gpt-5', model: 'gpt-5', maxRetries: 3 });
+        manager.listFailure = new Error('socket hang up');
+        await manager.fetchAvailableModelIds();
+        expect(manager.registry.patches.map(patch => patch.id)).to.deep.equal(['copilot/gpt-5']);
+        expect(manager.registry.models[0].status).to.deep.include({ status: 'unavailable' });
+    });
+
+    it('should report ready again once the models can be listed', async () => {
+        await manager.createOrUpdateLanguageModels({ id: 'copilot/gpt-5', model: 'gpt-5', maxRetries: 3 });
+        manager.listFailure = new Error('socket hang up');
+        await manager.fetchAvailableModelIds();
+        manager.listFailure = undefined;
+        expect(await manager.fetchAvailableModelIds()).to.deep.equal(['gpt-5']);
+        expect(manager.registry.models[0].status).to.deep.equal({ status: 'ready' });
+    });
+
+    it('should update an existing model instead of registering it twice', async () => {
+        await manager.createOrUpdateLanguageModels({ id: 'copilot/gpt-5', model: 'gpt-5', maxRetries: 3 });
+        await manager.createOrUpdateLanguageModels({ id: 'copilot/gpt-5', model: 'gpt-5', maxRetries: 5 });
+        expect(manager.registry.models).to.have.lengthOf(1);
+        expect(manager.registry.patches).to.have.lengthOf(1);
+        expect(manager.registry.patches[0].patch).to.deep.include({ maxRetries: 5 });
+    });
+});

package/src/node/copilot-language-models-manager-impl.ts

@@ -15,11 +15,11 @@
 // *****************************************************************************
 
 import { LanguageModelRegistry, LanguageModelStatus } from '@theia/ai-core';
-import { Disposable, DisposableCollection, ILogger } from '@theia/core';
-import { inject, injectable, postConstruct, named } from '@theia/core/shared/inversify';
-import { CopilotLanguageModelsManager, CopilotModelDescription, COPILOT_PROVIDER_ID, getCopilotApiBaseUrl } from '../common';
-import { CopilotOAuthConfig } from '../common/copilot-oauth-config';
-import { CopilotLanguageModel } from './copilot-language-model';
+import { DisposableCollection, ILogger, nls } from '@theia/core';
+import { inject, injectable, named, postConstruct, preDestroy } from '@theia/core/shared/inversify';
+import { CopilotLanguageModelsManager, CopilotModelDescription, COPILOT_PROVIDER_ID } from '../common';
+import { CopilotSdkLanguageModel } from './copilot-sdk-language-model';
+import { CopilotSdkClientProvider } from './copilot-sdk-client-provider';
 import { CopilotAuthServiceImpl } from './copilot-auth-service-impl';
 
 /**
@@ -27,7 +27,7 @@ import { CopilotAuthServiceImpl } from './copilot-auth-service-impl';
  * Manages registration and lifecycle of Copilot language models in the AI language model registry.
  */
 @injectable()
-export class CopilotLanguageModelsManagerImpl implements CopilotLanguageModelsManager, Disposable {
+export class CopilotLanguageModelsManagerImpl implements CopilotLanguageModelsManager {
 
     @inject(LanguageModelRegistry)
     protected readonly languageModelRegistry: LanguageModelRegistry;
@@ -35,36 +35,51 @@ export class CopilotLanguageModelsManagerImpl implements CopilotLanguageModelsMa
     @inject(CopilotAuthServiceImpl)
     protected readonly authService: CopilotAuthServiceImpl;
 
-    @inject(CopilotOAuthConfig)
-    protected readonly oauthConfig: CopilotOAuthConfig;
+    @inject(CopilotSdkClientProvider)
+    protected readonly sdkClientProvider: CopilotSdkClientProvider;
 
     @inject(ILogger) @named('ai-copilot:CopilotLanguageModelsManagerImpl')
     protected readonly logger: ILogger;
 
-    protected enterpriseUrl: string | undefined;
     protected readonly toDispose = new DisposableCollection();
 
+    /**
+     * Why the last model discovery failed, if it did.
+     *
+     * Being signed in does not imply that requests are accepted: the credentials can lack the Copilot
+     * entitlement, be revoked, or belong to a subscription served by a different API host. Reporting
+     * the models as ready in those cases claims a working setup that is not there, so the failure is
+     * remembered and reflected in the status of the models.
+     */
+    protected discoveryFailure: string | undefined;
+
     @postConstruct()
     protected init(): void {
         this.toDispose.push(this.authService.onAuthStateChanged(() => {
-            this.refreshModelsStatus();
+            // The listener cannot be awaited, so the failure is reported here rather than escaping as
+            // an unhandled rejection.
+            this.refreshModelsStatus().catch(error => this.logger.warn('Copilot: failed to update the status of the models:', error));
         }));
     }
 
-    dispose(): void {
+    /**
+     * Detaches from the auth service when the container this manager lives in goes away.
+     * Unbinding a container runs `@preDestroy` rather than `dispose`, see the client provider.
+     */
+    @preDestroy()
+    protected stop(): void {
         this.toDispose.dispose();
     }
 
-    setEnterpriseUrl(url: string | undefined): void {
-        this.enterpriseUrl = url;
-    }
-
     protected async calculateStatus(): Promise<LanguageModelStatus> {
         const authState = await this.authService.getAuthState();
-        if (authState.isAuthenticated) {
-            return { status: 'ready' };
+        if (!authState.isAuthenticated) {
+            return { status: 'unavailable', message: nls.localize('theia/ai/copilot/notSignedIn', 'Not signed in to GitHub Copilot') };
+        }
+        if (this.discoveryFailure) {
+            return { status: 'unavailable', message: this.discoveryFailure };
         }
-        return { status: 'unavailable', message: 'Not signed in to GitHub Copilot' };
+        return { status: 'ready' };
     }
 
     async createOrUpdateLanguageModels(...modelDescriptions: CopilotModelDescription[]): Promise<void> {
@@ -74,29 +89,24 @@ export class CopilotLanguageModelsManagerImpl implements CopilotLanguageModelsMa
             const model = await this.languageModelRegistry.getLanguageModel(modelDescription.id);
 
             if (model) {
-                if (!(model instanceof CopilotLanguageModel)) {
+                if (!(model instanceof CopilotSdkLanguageModel)) {
                     this.logger.warn(`Copilot: model ${modelDescription.id} is not a Copilot model`);
                     continue;
                 }
-                await this.languageModelRegistry.patchLanguageModel<CopilotLanguageModel>(modelDescription.id, {
+                await this.languageModelRegistry.patchLanguageModel<CopilotSdkLanguageModel>(modelDescription.id, {
                     model: modelDescription.model,
-                    enableStreaming: modelDescription.enableStreaming,
-                    supportsStructuredOutput: modelDescription.supportsStructuredOutput,
                     status,
                     maxRetries: modelDescription.maxRetries
                 });
             } else {
                 this.languageModelRegistry.addLanguageModels([
-                    new CopilotLanguageModel(
+                    new CopilotSdkLanguageModel(
                         modelDescription.id,
                         modelDescription.model,
                         status,
-                        modelDescription.enableStreaming,
-                        modelDescription.supportsStructuredOutput,
                         modelDescription.maxRetries,
-                        () => this.authService.getAccessToken(),
-                        () => this.enterpriseUrl,
-                        () => this.oauthConfig.userAgent
+                        () => this.sdkClientProvider.getClient(),
+                        this.logger
                     )
                 ]);
             }
@@ -112,8 +122,8 @@ export class CopilotLanguageModelsManagerImpl implements CopilotLanguageModelsMa
         const allModels = await this.languageModelRegistry.getLanguageModels();
 
         for (const model of allModels) {
-            if (model instanceof CopilotLanguageModel && model.id.startsWith(`${COPILOT_PROVIDER_ID}/`)) {
-                await this.languageModelRegistry.patchLanguageModel<CopilotLanguageModel>(model.id, {
+            if (model instanceof CopilotSdkLanguageModel && model.id.startsWith(`${COPILOT_PROVIDER_ID}/`)) {
+                await this.languageModelRegistry.patchLanguageModel<CopilotSdkLanguageModel>(model.id, {
                     status
                 });
             }
@@ -121,70 +131,26 @@ export class CopilotLanguageModelsManagerImpl implements CopilotLanguageModelsMa
     }
 
     async fetchAvailableModelIds(): Promise<string[]> {
-        const accessToken = await this.authService.getAccessToken();
-        if (!accessToken) {
-            return [];
-        }
-
-        const baseURL = getCopilotApiBaseUrl(this.enterpriseUrl);
-
         try {
-            const response = await fetch(`${baseURL}/models`, {
-                headers: {
-                    'Authorization': `Bearer ${accessToken}`,
-                    'User-Agent': this.oauthConfig.userAgent,
-                    'Accept': 'application/json'
-                }
-            });
-
-            if (!response.ok) {
-                this.logger.warn(`Copilot: failed to fetch available models: ${response.status} ${response.statusText}`);
-                return [];
-            }
-
-            const data = await response.json() as {
-                data?: Array<{ id: string; capabilities?: { family?: string } }>
-            };
-            const models = data.data ?? [];
-            const modelIds = this.deduplicateModels(models);
-            this.logger.info(`Copilot: discovered ${modelIds.length} available models: ${modelIds.join(', ')}`);
+            const modelIds = await this.sdkClientProvider.listModelIds();
+            this.logger.info(`Copilot: discovered ${modelIds.length} models [${modelIds.join(', ')}]`);
+            await this.setDiscoveryFailure(undefined);
             return modelIds;
         } catch (error) {
-            this.logger.warn('Copilot: failed to fetch available models:', error);
+            this.logger.warn('Copilot: failed to fetch available models via the Copilot CLI:', error);
+            await this.setDiscoveryFailure(error instanceof Error ? error.message : String(error));
             return [];
         }
     }
 
     /**
-     * Deduplicates models returned by the Copilot API.
-     * The API returns both alias IDs (e.g., `gpt-4o`) and versioned IDs
-     * (e.g., `gpt-4o-2024-11-20`) for the same model family.
-     * We keep only the family alias when it exists, falling back to
-     * the versioned ID otherwise.
+     * Records the outcome of the last model discovery and reflects it in the status of the models.
      */
-    protected deduplicateModels(models: Array<{ id: string; capabilities?: { family?: string } }>): string[] {
-        const allIds = new Set(models.map(m => m.id));
-        const result: string[] = [];
-        const seenFamilies = new Set<string>();
-
-        for (const model of models) {
-            const family = model.capabilities?.family;
-            if (family && seenFamilies.has(family)) {
-                continue;
-            }
-            if (family) {
-                seenFamilies.add(family);
-                // Prefer the family alias if it exists as a model ID
-                if (allIds.has(family)) {
-                    result.push(family);
-                } else {
-                    result.push(model.id);
-                }
-            } else {
-                result.push(model.id);
-            }
+    protected async setDiscoveryFailure(failure: string | undefined): Promise<void> {
+        if (this.discoveryFailure === failure) {
+            return;
         }
-
-        return result;
+        this.discoveryFailure = failure;
+        await this.refreshModelsStatus();
     }
 }

package/src/node/copilot-runtime-env.ts

@@ -0,0 +1,46 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH 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
+// *****************************************************************************
+
+/**
+ * The environment of the processes this integration starts, which are the Copilot CLI of a sign-in
+ * and the one that serves the requests.
+ */
+export namespace CopilotRuntimeEnv {
+
+    /**
+     * The variables the Copilot CLI accepts a token from. None of them is a sign-in of this
+     * application, so a token this application does not own must not reach the CLI through them.
+     */
+    export const TOKEN_VARIABLES = ['COPILOT_GITHUB_TOKEN', 'GH_TOKEN', 'GITHUB_TOKEN'];
+
+    /**
+     * The given environment without the variables that carry a token.
+     *
+     * They are dropped by name and regardless of their case, rather than masked with `undefined`.
+     * Environment variables are case-insensitive on Windows, so a `Github_Token` of the backend would
+     * survive a `GITHUB_TOKEN: undefined` next to it and would still be read by the CLI.
+     */
+    export function withoutTokens(env: NodeJS.ProcessEnv): Record<string, string | undefined> {
+        const dropped = new Set(TOKEN_VARIABLES.map(name => name.toLowerCase()));
+        const result: Record<string, string | undefined> = {};
+        for (const [name, value] of Object.entries(env)) {
+            if (!dropped.has(name.toLowerCase())) {
+                result[name] = value;
+            }
+        }
+        return result;
+    }
+}

package/src/node/copilot-sdk-client-provider.spec.ts

@@ -0,0 +1,253 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH 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 { expect } from 'chai';
+import { promises as fs } from 'fs';
+import * as os from 'os';
+import { join } from 'path';
+import { MockLogger } from '@theia/core/lib/common/test/mock-logger';
+import { FileUri } from '@theia/core/lib/common/file-uri';
+import { CopilotCredentials } from './copilot-credential-store';
+import { CopilotSdkClientProvider } from './copilot-sdk-client-provider';
+import type { CopilotClient, CopilotClientOptions } from './copilot-sdk-types';
+
+interface SdkStub {
+    api: {
+        CopilotClient: new (options?: CopilotClientOptions) => CopilotClient,
+        RuntimeConnection: { forStdio: (options: { path: string }) => unknown }
+    };
+    started: string[];
+    stopped: string[];
+}
+
+/** The SDK as the provider uses it: a client constructor and the stdio connection factory. */
+function sdkStub(): SdkStub {
+    const started: string[] = [];
+    const stopped: string[] = [];
+    class StubClient {
+        constructor(readonly options?: CopilotClientOptions) { }
+        async start(): Promise<void> {
+            started.push(String(this.options?.gitHubToken));
+        }
+        async stop(): Promise<Error[]> {
+            stopped.push(String(this.options?.gitHubToken));
+            return [];
+        }
+        async listModels(): Promise<[]> {
+            return [];
+        }
+    }
+    return {
+        api: {
+            CopilotClient: StubClient as unknown as new (options?: CopilotClientOptions) => CopilotClient,
+            RuntimeConnection: { forStdio: (options: { path: string }) => ({ kind: 'stdio', ...options }) }
+        },
+        started,
+        stopped
+    };
+}
+
+class TestableCopilotSdkClientProvider extends CopilotSdkClientProvider {
+
+    credentials: CopilotCredentials | undefined = { token: 'gho_first' };
+
+    constructor(sdk: SdkStub['api'], configDirectory: string, cli = join('/opt', 'copilot', 'copilot')) {
+        super();
+        Object.assign(this, {
+            logger: new MockLogger(),
+            credentialStore: { get: async () => this.credentials },
+            cliLocator: { resolve: async () => cli },
+            sdkLoader: { load: async () => sdk },
+            envVariablesServer: { getConfigDirUri: async () => FileUri.create(configDirectory).toString() }
+        });
+    }
+
+    callCreateRuntimeEnv(credentials: CopilotCredentials): Record<string, string | undefined> {
+        return this.createRuntimeEnv(credentials);
+    }
+
+    callEnrichEntitlementError(error: unknown): unknown {
+        return this.enrichEntitlementError(error);
+    }
+
+    clientOptions(client: CopilotClient): CopilotClientOptions | undefined {
+        return (client as unknown as { options?: CopilotClientOptions }).options;
+    }
+}
+
+describe('CopilotSdkClientProvider - client options', () => {
+
+    let configDirectory: string;
+    let sdk: ReturnType<typeof sdkStub>;
+
+    beforeEach(async () => {
+        configDirectory = await fs.mkdtemp(join(os.tmpdir(), 'theia-copilot-config-'));
+        sdk = sdkStub();
+    });
+
+    afterEach(async () => {
+        await fs.rm(configDirectory, { recursive: true, force: true });
+    });
+
+    it('should hand the located CLI and the token of this application to the runtime', async () => {
+        const provider = new TestableCopilotSdkClientProvider(sdk.api, configDirectory);
+        const options = provider.clientOptions(await provider.getClient());
+        expect(options?.connection).to.deep.equal({ kind: 'stdio', path: join('/opt', 'copilot', 'copilot') });
+        expect(options?.gitHubToken).to.equal('gho_first');
+        // Nothing the runtime finds on the host may make it appear signed in.
+        expect(options?.useLoggedInUser).to.be.false;
+    });
+
+    it('should keep the runtime out of the ambient behaviour of the CLI', async () => {
+        const provider = new TestableCopilotSdkClientProvider(sdk.api, configDirectory);
+        const options = provider.clientOptions(await provider.getClient());
+        expect(options?.mode).to.equal('empty');
+    });
+
+    it('should point the runtime at a Copilot home of the application and create it', async () => {
+        const provider = new TestableCopilotSdkClientProvider(sdk.api, configDirectory);
+        const options = provider.clientOptions(await provider.getClient());
+        const home = join(configDirectory, 'copilot');
+        // Compared without case, because the URI of the configuration directory lowercases the drive
+        // letter on Windows, which addresses the same location.
+        expect(options?.baseDirectory?.toLowerCase()).to.equal(home.toLowerCase());
+        expect((await fs.stat(home)).isDirectory()).to.be.true;
+    });
+});
+
+describe('CopilotSdkClientProvider - runtime environment', () => {
+
+    const provider = new TestableCopilotSdkClientProvider(sdkStub().api, os.tmpdir());
+
+    it('should remove tokens of the environment, which are not a sign-in of this application', () => {
+        const previous = { ...process.env };
+        try {
+            process.env.GITHUB_TOKEN = 'gho_environment';
+            process.env.GH_TOKEN = 'gho_environment';
+            process.env.COPILOT_GITHUB_TOKEN = 'gho_environment';
+            const env = provider.callCreateRuntimeEnv({ token: 'gho_ours' });
+            expect(env.GITHUB_TOKEN).to.be.undefined;
+            expect(env.GH_TOKEN).to.be.undefined;
+            expect(env.COPILOT_GITHUB_TOKEN).to.be.undefined;
+        } finally {
+            process.env = previous;
+        }
+    });
+
+    it('should remove a token variable whatever its case, since Windows ignores it', () => {
+        const previous = { ...process.env };
+        try {
+            process.env.Gh_Token = 'gho_environment';
+            const env = provider.callCreateRuntimeEnv({ token: 'gho_ours' });
+            expect(Object.keys(env).some(name => name.toLowerCase() === 'gh_token')).to.be.false;
+        } finally {
+            process.env = previous;
+        }
+    });
+
+    it('should point the runtime at the deployment that was signed in to', () => {
+        const env = provider.callCreateRuntimeEnv({ token: 'gho_ours', enterpriseUrl: 'company.ghe.com' });
+        expect(env.COPILOT_GH_HOST).to.equal('company.ghe.com');
+    });
+
+    it('should leave the host alone for a sign-in against GitHub.com', () => {
+        expect(provider.callCreateRuntimeEnv({ token: 'gho_ours' })).to.not.have.property('COPILOT_GH_HOST');
+    });
+});
+
+describe('CopilotSdkClientProvider - lifecycle', () => {
+
+    let configDirectory: string;
+    let sdk: ReturnType<typeof sdkStub>;
+    let provider: TestableCopilotSdkClientProvider;
+
+    beforeEach(async () => {
+        configDirectory = await fs.mkdtemp(join(os.tmpdir(), 'theia-copilot-config-'));
+        sdk = sdkStub();
+        provider = new TestableCopilotSdkClientProvider(sdk.api, configDirectory);
+    });
+
+    afterEach(async () => {
+        await fs.rm(configDirectory, { recursive: true, force: true });
+    });
+
+    it('should reject when the application is not signed in', async () => {
+        provider.credentials = undefined;
+        try {
+            await provider.getClient();
+            expect.fail('should have rejected');
+        } catch (error) {
+            expect(String(error)).to.contain('sign in');
+        }
+    });
+
+    it('should start one CLI and share it, also for concurrent callers', async () => {
+        const [first, second] = await Promise.all([provider.getClient(), provider.getClient()]);
+        expect(first).to.equal(second);
+        expect(await provider.getClient()).to.equal(first);
+        expect(sdk.started).to.deep.equal(['gho_first']);
+    });
+
+    it('should replace the client when the credentials changed, stopping the previous one', async () => {
+        const first = await provider.getClient();
+        provider.credentials = { token: 'gho_second' };
+        const second = await provider.getClient();
+        expect(second).to.not.equal(first);
+        expect(sdk.started).to.deep.equal(['gho_first', 'gho_second']);
+        expect(sdk.stopped).to.deep.equal(['gho_first']);
+    });
+
+    it('should stop the CLI on reset and start a new one afterwards', async () => {
+        await provider.getClient();
+        await provider.reset();
+        expect(sdk.stopped).to.deep.equal(['gho_first']);
+        await provider.getClient();
+        expect(sdk.started).to.deep.equal(['gho_first', 'gho_first']);
+    });
+
+    it('should not cache a client whose runtime failed to start', async () => {
+        const failing = sdkStub();
+        failing.api.CopilotClient = class {
+            async start(): Promise<void> {
+                throw new Error('runtime did not come up');
+            }
+        } as unknown as new () => CopilotClient;
+        const other = new TestableCopilotSdkClientProvider(failing.api, configDirectory);
+        await other.getClient().catch(() => { /* expected */ });
+        // A cached rejection would keep replaying instead of trying again.
+        await other.getClient().catch(error => expect(String(error)).to.contain('did not come up'));
+    });
+});
+
+describe('CopilotSdkClientProvider - entitlement errors', () => {
+
+    const provider = new TestableCopilotSdkClientProvider(sdkStub().api, os.tmpdir());
+
+    it('should explain what an authorization failure of the runtime can mean', () => {
+        const enriched = provider.callEnrichEntitlementError(new Error('user is not authorized to use this Copilot feature'));
+        expect(String(enriched)).to.contain('subscription');
+        expect(String(enriched)).to.contain('not authorized to use this Copilot feature');
+    });
+
+    it('should explain a policy rejection the same way', () => {
+        expect(String(provider.callEnrichEntitlementError(new Error('Access denied by policy settings')))).to.contain('administrator');
+    });
+
+    it('should pass an unrelated failure through unchanged', () => {
+        const error = new Error('socket hang up');
+        expect(provider.callEnrichEntitlementError(error)).to.equal(error);
+    });
+});