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

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

@@ -0,0 +1,241 @@
+// *****************************************************************************
+// 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 { promises as fs } from 'fs';
+import { join } from 'path';
+import { inject, injectable, named, preDestroy } from '@theia/core/shared/inversify';
+import { ILogger, nls, URI } from '@theia/core';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
+import { FileUri } from '@theia/core/lib/common/file-uri';
+import type { CopilotClient, CopilotClientOptions } from './copilot-sdk-types';
+import { CopilotCredentials, CopilotCredentialStore } from './copilot-credential-store';
+import { CopilotCliLocator } from './copilot-cli-locator';
+import { CopilotRuntimeEnv } from './copilot-runtime-env';
+import { CopilotSdkApi, CopilotSdkLoader } from './copilot-sdk-loader';
+import { selectSdkModelIds } from './copilot-sdk-mappers';
+
+/**
+ * Manages the lifecycle of a {@link CopilotClient}, which spawns and talks to the
+ * official Copilot CLI over JSON-RPC.
+ *
+ * The runtime is given the token this application holds, and nothing else: credentials the CLI could
+ * otherwise pick up on its own, from the environment or from the sign-in of the GitHub CLI, are not a
+ * sign-in of this application and are deliberately kept out of reach. The token is established by
+ * {@link CopilotCliAuthProvider} and kept in {@link CopilotCredentialStore}.
+ *
+ * A single client is started lazily and shared for the lifetime of the (connection-scoped) backend
+ * container. It is recreated when the host configuration changes.
+ *
+ * Note: this provider is bound in the per-connection container, so each frontend connection runs
+ * its own CLI process, authenticated with the credentials of the backend host. This is not suitable
+ * for multi-user backend deployments, where every connected frontend would share a single identity.
+ */
+@injectable()
+export class CopilotSdkClientProvider {
+
+    @inject(CopilotCredentialStore)
+    protected readonly credentialStore: CopilotCredentialStore;
+
+    @inject(CopilotCliLocator)
+    protected readonly cliLocator: CopilotCliLocator;
+
+    @inject(CopilotSdkLoader)
+    protected readonly sdkLoader: CopilotSdkLoader;
+
+    @inject(EnvVariablesServer)
+    protected readonly envVariablesServer: EnvVariablesServer;
+
+    @inject(ILogger) @named('ai-copilot:CopilotSdkClientProvider')
+    protected readonly logger: ILogger;
+
+    protected clientPromise: Promise<CopilotClient> | undefined;
+    protected clientConfigKey: string | undefined;
+
+    /**
+     * Returns a started {@link CopilotClient}, creating (or recreating, if the
+     * configuration changed) one on demand.
+     */
+    async getClient(): Promise<CopilotClient> {
+        const credentials = await this.credentialStore.get();
+        if (!credentials) {
+            throw new Error(nls.localize('theia/ai/copilot/notSignedInSignInFirst', 'Not signed in to GitHub Copilot. Please sign in first.'));
+        }
+        const configKey = this.getConfigKey(credentials);
+        if (this.clientPromise && this.clientConfigKey === configKey) {
+            return this.clientPromise;
+        }
+        // First use or changed credentials: (re)create the client. Capture the
+        // previous client and assign synchronously so concurrent callers share
+        // the same promise instead of spawning multiple CLI processes.
+        const previous = this.clientPromise;
+        this.clientConfigKey = configKey;
+        this.clientPromise = this.recreate(configKey, credentials, previous);
+        return this.clientPromise;
+    }
+
+    /**
+     * Lists the model IDs available to the authenticated user via the Copilot CLI.
+     * Because the CLI runs under an entitled identity, this returns the full current model lineup
+     * rather than the baseline set that the direct REST API exposes to an unentitled OAuth app.
+     */
+    async listModelIds(): Promise<string[]> {
+        const client = await this.getClient();
+        try {
+            const models = await client.listModels();
+            return selectSdkModelIds(models);
+        } catch (error) {
+            throw this.enrichEntitlementError(error);
+        }
+    }
+
+    /**
+     * Replaces the bare authorization failure of the Copilot runtime with an explanation of the
+     * possible causes, because the runtime only reports that the feature is not authorized.
+     */
+    protected enrichEntitlementError(error: unknown): unknown {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes('not authorized to use this Copilot feature') && !message.includes('Access denied by policy settings')) {
+            return error;
+        }
+        return new Error(nls.localize('theia/ai/copilot/notAuthorized',
+            'GitHub Copilot rejected the request as not authorized for this account. Either the account has no Copilot subscription, or '
+            + 'access has to be enabled by an administrator through an organization or enterprise policy. Signing out and in again also '
+            + 'renews credentials that were revoked. GitHub reports requests sent to an API host that does not match the subscription the '
+            + 'same way, so as a last resort the host can be set explicitly with the `COPILOT_API_URL` environment variable of the backend. '
+            + 'Reported by the Copilot runtime: {0}', message));
+    }
+
+    protected getConfigKey(credentials: CopilotCredentials): string {
+        return `${credentials.enterpriseUrl ?? ''}|${credentials.token}`;
+    }
+
+    protected async recreate(configKey: string, credentials: CopilotCredentials, previous: Promise<CopilotClient> | undefined): Promise<CopilotClient> {
+        if (previous) {
+            try {
+                const previousClient = await previous;
+                await previousClient.stop();
+            } catch (error) {
+                this.logger.warn('Copilot SDK: failed to stop previous client:', error);
+            }
+        }
+        const sdk = await this.sdkLoader.load();
+        const client = new sdk.CopilotClient(this.createClientOptions(sdk, credentials, await this.cliLocator.resolve(), await this.getCopilotHome()));
+        try {
+            await client.start();
+        } catch (error) {
+            // Don't cache a failed start, otherwise every later call replays the rejection.
+            if (this.clientConfigKey === configKey) {
+                this.clientPromise = undefined;
+                this.clientConfigKey = undefined;
+            }
+            throw error;
+        }
+        return client;
+    }
+
+    /**
+     * Builds the options of the {@link CopilotClient}.
+     *
+     * The token of this application is passed explicitly and the resolution of a logged-in user is
+     * switched off, so that the runtime cannot fall back to credentials this application does not own.
+     *
+     * The CLI is passed explicitly as well, see {@link CopilotCliLocator}: the SDK would otherwise look
+     * for the JavaScript entry point of a platform package installed next to itself and spawn it with
+     * `process.execPath`, which is the Electron binary rather than Node.js in an Electron application.
+     *
+     * The runtime is configured in `empty` mode rather than in the `copilot-cli` mode the SDK defaults
+     * to. That mode brings the ambient behaviour of the CLI along, which the SDK documents as unsuitable
+     * for an application serving requests on a backend: instructions and skills found on the host,
+     * session and memory stores, host git operations and plugins. Theia drives the conversation itself
+     * and declares the tools of each request, so none of that applies, and `empty` mode additionally
+     * keeps the runtime away from the system keychain. Its two requirements are met here, a persistence
+     * location ({@link getCopilotHome}) and an explicit tool list per session.
+     */
+    protected createClientOptions(sdk: CopilotSdkApi, credentials: CopilotCredentials, cliPath: string, baseDirectory: string): CopilotClientOptions {
+        return {
+            connection: sdk.RuntimeConnection.forStdio({ path: cliPath }),
+            mode: 'empty',
+            baseDirectory,
+            gitHubToken: credentials.token,
+            useLoggedInUser: false,
+            logLevel: 'error',
+            env: this.createRuntimeEnv(credentials)
+        };
+    }
+
+    /**
+     * The Copilot home the runtime is pointed at, below the configuration directory of Theia.
+     *
+     * Requests are served in sessions that the runtime persists in its home, and the default home is
+     * the one the user's own Copilot CLI uses. Prompts sent from Theia would end up listed among the
+     * conversations the user started themselves, so this application keeps its own.
+     */
+    protected async getCopilotHome(): Promise<string> {
+        const configDirectory = FileUri.fsPath(new URI(await this.envVariablesServer.getConfigDirUri()));
+        const home = join(configDirectory, 'copilot');
+        await fs.mkdir(home, { recursive: true });
+        return home;
+    }
+
+    /**
+     * Returns the environment for the runtime process.
+     *
+     * Tokens from the environment are removed: the runtime accepts them even when a token is passed
+     * explicitly, and they are not a sign-in of this application. The GitHub host is taken from the
+     * credentials, so that the runtime always talks to the deployment that was signed in to.
+     *
+     * The Copilot API endpoint is deliberately not set: the runtime resolves the one belonging to the
+     * subscription from the token, including for Business and Enterprise seats. The environment of the
+     * backend is inherited as-is, so an operator can still override it with `COPILOT_API_URL` should
+     * that resolution ever fail for a deployment.
+     */
+    protected createRuntimeEnv(credentials: CopilotCredentials): Record<string, string | undefined> {
+        return {
+            ...CopilotRuntimeEnv.withoutTokens(process.env),
+            ...(credentials.enterpriseUrl ? { COPILOT_GH_HOST: credentials.enterpriseUrl } : {})
+        };
+    }
+
+    /**
+     * Stops and clears the current client. Safe to call when no client exists.
+     */
+    async reset(): Promise<void> {
+        const previous = this.clientPromise;
+        this.clientPromise = undefined;
+        this.clientConfigKey = undefined;
+        if (previous) {
+            try {
+                const client = await previous;
+                await client.stop();
+            } catch (error) {
+                this.logger.warn('Copilot SDK: failed to stop client during reset:', error);
+            }
+        }
+    }
+
+    /**
+     * Stops the CLI when the container this provider lives in goes away, which happens when the
+     * frontend connection it belongs to is closed.
+     *
+     * A closing connection unbinds its container, and unbinding runs `@preDestroy` rather than
+     * `dispose`. Without this hook the CLI of every closed connection would keep running for the rest
+     * of the lifetime of the backend.
+     */
+    @preDestroy()
+    protected async stop(): Promise<void> {
+        await this.reset();
+    }
+}

package/src/node/copilot-sdk-language-model.spec.ts

@@ -0,0 +1,363 @@
+// *****************************************************************************
+// 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 { LanguageModelStreamResponsePart, ToolCallResponsePart, ToolRequest, UserRequest } from '@theia/ai-core';
+import type { CopilotClient, PermissionRequest, Tool } from './copilot-sdk-types';
+import { MockLogger } from '@theia/core/lib/common/test/mock-logger';
+import { approveTheiaTools, CopilotSdkLanguageModel, CopilotStreamSink } from './copilot-sdk-language-model';
+
+class TestableCopilotSdkLanguageModel extends CopilotSdkLanguageModel {
+    constructor() {
+        super('copilot/test', 'test-model', { status: 'ready' }, 3, async () => ({} as CopilotClient), new MockLogger());
+    }
+
+    callCreateTools(tools: ToolRequest[], sink: CopilotStreamSink): Tool[] {
+        return this.createTools(tools, sink);
+    }
+
+    /** Captures the session configuration the model would create for a request. */
+    async captureSessionConfig(request: UserRequest): Promise<Record<string, unknown>> {
+        let captured: Record<string, unknown> = {};
+        const client = {
+            createSession: async (config: Record<string, unknown>) => {
+                captured = config;
+                return { on: () => () => { }, send: async () => { }, abort: async () => { }, disconnect: async () => { } };
+            }
+        } as unknown as CopilotClient;
+        const model = new TestableCopilotSdkLanguageModel();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (model as any).clientProvider = async () => client;
+        await model.request(request);
+        return captured;
+    }
+
+    /**
+     * Runs a request against a session that reports itself idle as soon as it was sent to, and
+     * reports what the session was configured with, what it was sent, and what was discarded.
+     */
+    async captureTurn(request: UserRequest): Promise<{ config: Record<string, unknown>, prompt?: string, deleted?: string }> {
+        let config: Record<string, unknown> = {};
+        let prompt: string | undefined;
+        let deleted: string | undefined;
+        const listeners = new Map<string, (event: unknown) => void>();
+        const session = {
+            sessionId: 'test-session',
+            on: (event: string, handler: (payload: unknown) => void) => {
+                listeners.set(event, handler);
+                return () => listeners.delete(event);
+            },
+            send: async (message: { prompt: string }) => {
+                prompt = message.prompt;
+                listeners.get('session.idle')?.({});
+            },
+            abort: async () => { },
+            disconnect: async () => { }
+        };
+        const client = {
+            createSession: async (sessionConfig: Record<string, unknown>) => {
+                config = sessionConfig;
+                return session;
+            },
+            deleteSession: async (sessionId: string) => { deleted = sessionId; }
+        } as unknown as CopilotClient;
+        const model = new TestableCopilotSdkLanguageModel();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (model as any).clientProvider = async () => client;
+        const response = await model.request(request) as { stream: AsyncIterable<LanguageModelStreamResponsePart> };
+        for await (const part of response.stream) {
+            expect(part).to.exist;
+        }
+        return { config, prompt, deleted };
+    }
+}
+
+function toolRequest(name: string, handler: (args: string, ctx?: { toolCallId?: string }) => Promise<string>): ToolRequest {
+    return {
+        id: name,
+        name,
+        description: `the ${name} tool`,
+        parameters: { type: 'object', properties: { path: { type: 'string' } } },
+        handler
+    };
+}
+
+/**
+ * Runs a tool invocation the way the caller does, with the stream being consumed concurrently.
+ * The handler waits for its reported call to be consumed, so nothing may invoke it in isolation.
+ */
+async function invokeWhileConsuming(
+    sink: CopilotStreamSink,
+    invoke: () => Promise<unknown> | unknown
+): Promise<{ result: unknown, parts: LanguageModelStreamResponsePart[] }> {
+    const parts: LanguageModelStreamResponsePart[] = [];
+    const consumer = (async () => {
+        for await (const part of sink.drain()) {
+            parts.push(part);
+        }
+    })();
+    const result = await invoke();
+    sink.finish();
+    await consumer;
+    return { result, parts };
+}
+
+async function collect(sink: CopilotStreamSink): Promise<LanguageModelStreamResponsePart[]> {
+    const parts: LanguageModelStreamResponsePart[] = [];
+    for await (const part of sink.drain()) {
+        parts.push(part);
+    }
+    return parts;
+}
+
+function toolCalls(part: LanguageModelStreamResponsePart): ToolCallResponsePart['tool_calls'] {
+    return (part as ToolCallResponsePart).tool_calls;
+}
+
+describe('CopilotSdkLanguageModel - createTools', () => {
+
+    const model = new TestableCopilotSdkLanguageModel();
+
+    it('should declare the tools of the request to the CLI', () => {
+        const tools = model.callCreateTools([toolRequest('readFile', async () => 'content')], new CopilotStreamSink());
+        expect(tools).to.have.lengthOf(1);
+        expect(tools[0].name).to.equal('readFile');
+        expect(tools[0].description).to.equal('the readFile tool');
+        expect(tools[0].parameters).to.deep.equal({ type: 'object', properties: { path: { type: 'string' } } });
+        // Theia confirms tool invocations itself, so the CLI must not prompt again.
+        expect(tools[0].skipPermission).to.be.true;
+    });
+
+    it('should pass the raw argument string to the handler of the request', async () => {
+        let received: string | undefined;
+        const sink = new CopilotStreamSink();
+        const tools = model.callCreateTools([toolRequest('readFile', async args => { received = args; return 'content'; })], sink);
+
+        const { result } = await invokeWhileConsuming(sink, () =>
+            tools[0].handler!({ path: 'a.ts' }, { sessionId: 's', toolCallId: 'call_1', toolName: 'readFile', arguments: {} }));
+
+        expect(received).to.equal(JSON.stringify({ path: 'a.ts' }));
+        expect(result).to.equal('content');
+    });
+
+    it('should report the invocation as an unfinished and then a finished tool call', async () => {
+        const sink = new CopilotStreamSink();
+        const tools = model.callCreateTools([toolRequest('readFile', async () => 'content')], sink);
+
+        const { parts } = await invokeWhileConsuming(sink, () =>
+            tools[0].handler!({ path: 'a.ts' }, { sessionId: 's', toolCallId: 'call_1', toolName: 'readFile', arguments: {} }));
+
+        expect(parts).to.have.lengthOf(2);
+        expect(toolCalls(parts[0])[0]).to.deep.include({ id: 'call_1', finished: false });
+        expect(toolCalls(parts[0])[0].function).to.deep.equal({ name: 'readFile', arguments: JSON.stringify({ path: 'a.ts' }) });
+        expect(toolCalls(parts[1])[0]).to.deep.include({ id: 'call_1', finished: true, result: 'content' });
+    });
+
+    it('should report a failing tool to the stream and to the agent instead of throwing', async () => {
+        const sink = new CopilotStreamSink();
+        const tools = model.callCreateTools([toolRequest('readFile', async () => { throw new Error('no such file'); })], sink);
+
+        const { result, parts } = await invokeWhileConsuming(sink, () =>
+            tools[0].handler!({ path: 'missing.ts' }, { sessionId: 's', toolCallId: 'call_1', toolName: 'readFile', arguments: {} }));
+
+        expect(result).to.deep.equal({ error: 'no such file' });
+        expect(toolCalls(parts[1])[0]).to.deep.include({ id: 'call_1', finished: true, result: 'Error: no such file' });
+    });
+
+    it('should return an empty tool list when the request has no tools', () => {
+        expect(model.callCreateTools([], new CopilotStreamSink())).to.be.empty;
+    });
+});
+
+describe('CopilotSdkLanguageModel - session configuration', () => {
+
+    const model = new TestableCopilotSdkLanguageModel();
+
+    function requestWith(tools: ToolRequest[]): UserRequest {
+        return { messages: [{ actor: 'user', type: 'text', text: 'hi' }], tools } as unknown as UserRequest;
+    }
+
+    it('should enable the declared tools and nothing else', async () => {
+        const config = await model.captureSessionConfig(requestWith([toolRequest('readFile', async () => 'content')]));
+        // An empty list would match nothing and would disable the declared tools as well.
+        expect(config.availableTools).to.deep.equal(['custom:*']);
+        expect((config.tools as Tool[]).map(tool => tool.name)).to.deep.equal(['readFile']);
+    });
+
+    it('should declare every tool of the request', async () => {
+        const config = await model.captureSessionConfig(requestWith([
+            toolRequest('readFile', async () => 'a'),
+            toolRequest('listFiles', async () => 'b')
+        ]));
+        expect((config.tools as Tool[]).map(tool => tool.name)).to.deep.equal(['readFile', 'listFiles']);
+    });
+
+    it('should still exclude the built-in tools when the request has none', async () => {
+        const config = await model.captureSessionConfig(requestWith([]));
+        expect(config.availableTools).to.deep.equal(['custom:*']);
+        expect(config.tools).to.be.empty;
+    });
+});
+
+describe('approveTheiaTools', () => {
+
+    const customToolRequest = { kind: 'custom-tool', toolName: 'readFile' } as unknown as PermissionRequest;
+
+    it('should approve a request for a tool Theia declared and confirmed itself', () => {
+        expect(approveTheiaTools(customToolRequest, { sessionId: 'test-session' })).to.deep.equal({ kind: 'approve-once' });
+    });
+
+    it('should report that nobody can confirm a request managed policy reserves for a decision', () => {
+        const request = { ...customToolRequest, managedApprovalRequired: true } as unknown as PermissionRequest;
+        // Not `no-result`: that leaves the request pending for another client, and there is none here.
+        expect(approveTheiaTools(request, { sessionId: 'test-session' })).to.deep.equal({ kind: 'user-not-available' });
+    });
+
+    it('should report the same when the machine has managed settings enabled at all', () => {
+        expect(approveTheiaTools(customToolRequest, { sessionId: 'test-session', managedSettingsEnabled: true }))
+            .to.deep.equal({ kind: 'user-not-available' });
+    });
+});
+
+describe('CopilotSdkLanguageModel - turn', () => {
+
+    const model = new TestableCopilotSdkLanguageModel();
+
+    const request = {
+        messages: [
+            { actor: 'system', type: 'text', text: 'You are a helpful assistant.' },
+            { actor: 'user', type: 'text', text: 'hi' }
+        ]
+    } as unknown as UserRequest;
+
+    it('should configure the system prompt as the system message of the session', async () => {
+        const { config } = await model.captureTurn(request);
+        expect(config.systemMessage).to.deep.include({ mode: 'customize', content: 'You are a helpful assistant.' });
+    });
+
+    it('should send the user turn without the system prompt in it', async () => {
+        const { prompt } = await model.captureTurn(request);
+        expect(prompt).to.equal('hi');
+    });
+
+    it('should delete the session it created, which the CLI would otherwise keep', async () => {
+        const { deleted } = await model.captureTurn(request);
+        expect(deleted).to.equal('test-session');
+    });
+});
+
+describe('CopilotStreamSink', () => {
+
+    it('should yield parts pushed before draining', async () => {
+        const sink = new CopilotStreamSink();
+        sink.push({ content: 'a' });
+        sink.push({ content: 'b' });
+        sink.finish();
+        expect(await collect(sink)).to.deep.equal([{ content: 'a' }, { content: 'b' }]);
+    });
+
+    it('should yield parts pushed while draining', async () => {
+        const sink = new CopilotStreamSink();
+        const collected = collect(sink);
+        sink.push({ content: 'a' });
+        await Promise.resolve();
+        sink.push({ content: 'b' });
+        sink.finish();
+        expect(await collected).to.deep.equal([{ content: 'a' }, { content: 'b' }]);
+    });
+
+    it('should raise the failure after the buffered parts have been drained', async () => {
+        const sink = new CopilotStreamSink();
+        sink.push({ content: 'partial' });
+        sink.finish(new Error('session failed'));
+
+        const parts: LanguageModelStreamResponsePart[] = [];
+        let error: unknown;
+        try {
+            for await (const part of sink.drain()) {
+                parts.push(part);
+            }
+        } catch (caught) {
+            error = caught;
+        }
+
+        expect(parts).to.deep.equal([{ content: 'partial' }]);
+        expect((error as Error).message).to.equal('session failed');
+    });
+
+    it('should end without parts when finished immediately', async () => {
+        const sink = new CopilotStreamSink();
+        sink.finish();
+        expect(await collect(sink)).to.be.empty;
+    });
+});
+
+describe('CopilotSdkLanguageModel - tool call ordering', () => {
+
+    const model = new TestableCopilotSdkLanguageModel();
+    const invocation = { sessionId: 's', toolCallId: 'call_1', toolName: 'readFile', arguments: {} };
+
+    it('should report the call before running the tool, so the caller can record it first', async () => {
+        const sink = new CopilotStreamSink();
+        const observed: string[] = [];
+        const tools = model.callCreateTools([toolRequest('readFile', async () => {
+            observed.push('tool ran');
+            return 'content';
+        })], sink);
+
+        const invoked = tools[0].handler!({ path: 'a.ts' }, invocation);
+
+        // The consumer has not taken the part yet, so the tool must not have run.
+        expect(observed).to.be.empty;
+
+        const parts: LanguageModelStreamResponsePart[] = [];
+        const consumer = (async () => {
+            for await (const part of sink.drain()) {
+                parts.push(part);
+                observed.push('part consumed');
+            }
+        })();
+
+        await invoked;
+        sink.finish();
+        await consumer;
+
+        expect(observed[0]).to.equal('part consumed');
+        expect(observed).to.contain('tool ran');
+        expect(toolCalls(parts[0])[0]).to.deep.include({ id: 'call_1', finished: false });
+    });
+
+    it('should pass the call id to the handler so the caller can correlate it', async () => {
+        const sink = new CopilotStreamSink();
+        let receivedId: string | undefined;
+        const tools = model.callCreateTools([toolRequest('readFile', async (_args, ctx) => {
+            receivedId = ctx?.toolCallId;
+            return 'content';
+        })], sink);
+
+        const invoked = tools[0].handler!({ path: 'a.ts' }, invocation);
+        const consumer = (async () => {
+            for await (const part of sink.drain()) {
+                expect(part).to.exist;
+            }
+        })();
+        await invoked;
+        sink.finish();
+        await consumer;
+
+        expect(receivedId).to.equal('call_1');
+    });
+});