@theia/ai-copilot 1.76.0-next.4 → 1.76.0-next.42

package/src/node/copilot-sdk-mappers.spec.ts

@@ -0,0 +1,190 @@
+// *****************************************************************************
+// 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 { LanguageModelMessage } from '@theia/ai-core';
+import type { ModelInfo } from './copilot-sdk-types';
+import { selectSdkModelIds, buildSdkPrompt, buildSdkSystemMessage } from './copilot-sdk-mappers';
+
+// Minimal ModelInfo factory: selectSdkModelIds only reads `id` and `policy.state`.
+function model(id: string, state?: 'enabled' | 'disabled' | 'unconfigured'): ModelInfo {
+    return { id, policy: state ? { state } : undefined } as unknown as ModelInfo;
+}
+
+describe('copilot-sdk-mappers - selectSdkModelIds', () => {
+    it('keeps enabled and unconfigured models and drops disabled ones', () => {
+        const result = selectSdkModelIds([
+            model('gpt-4o', 'enabled'),
+            model('o1', 'disabled'),
+            model('claude', 'unconfigured'),
+            model('gpt-5')
+        ]);
+        expect(result).to.deep.equal(['gpt-4o', 'claude', 'gpt-5']);
+    });
+
+    it('preserves order and removes duplicates', () => {
+        const result = selectSdkModelIds([
+            model('a', 'enabled'),
+            model('b', 'enabled'),
+            model('a', 'enabled')
+        ]);
+        expect(result).to.deep.equal(['a', 'b']);
+    });
+
+    it('keeps a dated release alongside its family, so a release can be pinned', () => {
+        const result = selectSdkModelIds([
+            model('gpt-5'),
+            model('gpt-5-2026-04-17'),
+            model('claude-sonnet-5'),
+            model('claude-sonnet-5-20260514')
+        ]);
+        // Which of them the model pickers offer is decided by the favorite models service, which
+        // features the families; the releases stay selectable for whoever wants one.
+        expect(result).to.deep.equal(['gpt-5', 'gpt-5-2026-04-17', 'claude-sonnet-5', 'claude-sonnet-5-20260514']);
+    });
+
+    it('keeps a dated release that is the only way to select that model', () => {
+        const result = selectSdkModelIds([model('gpt-5'), model('o5-preview-2026-03-01')]);
+        expect(result).to.deep.equal(['gpt-5', 'o5-preview-2026-03-01']);
+    });
+
+    it('keeps a dated release whose family is disabled by policy', () => {
+        const result = selectSdkModelIds([model('gpt-5', 'disabled'), model('gpt-5-2026-04-17')]);
+        expect(result).to.deep.equal(['gpt-5-2026-04-17']);
+    });
+
+    it('returns an empty list when given no models', () => {
+        expect(selectSdkModelIds([])).to.deep.equal([]);
+    });
+});
+
+describe('copilot-sdk-mappers - buildSdkPrompt', () => {
+    it('forwards a lone user turn verbatim with no system text', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'user', type: 'text', text: 'hello world' }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.systemText).to.equal('');
+        expect(result.prompt).to.equal('hello world');
+    });
+
+    it('extracts and concatenates system messages', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'system', type: 'text', text: 'You are helpful.' },
+            { actor: 'system', type: 'text', text: 'Be concise.' },
+            { actor: 'user', type: 'text', text: 'hi' }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.systemText).to.equal('You are helpful.\n\nBe concise.');
+        expect(result.prompt).to.equal('hi');
+    });
+
+    it('renders a multi-message history as a role-labelled transcript', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'user', type: 'text', text: 'first' },
+            { actor: 'ai', type: 'text', text: 'reply' },
+            { actor: 'user', type: 'text', text: 'second' }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.prompt).to.equal('User: first\n\nAssistant: reply\n\nUser: second');
+    });
+
+    it('drops thinking messages from the conversation body', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'ai', type: 'thinking', thinking: 'internal', signature: 's' },
+            { actor: 'user', type: 'text', text: 'only user' }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.prompt).to.equal('only user');
+    });
+
+    it('summarises tool use and tool result messages in the transcript', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'user', type: 'text', text: 'run it' },
+            { actor: 'ai', type: 'tool_use', id: 'call_1', name: 'foo', input: { x: 1 } },
+            { actor: 'user', type: 'tool_result', tool_use_id: 'call_1', name: 'foo', content: 'done' }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.prompt).to.equal(
+            'User: run it\n\nAssistant: [tool call: foo {"x":1}]\n\nUser: [tool result: done]'
+        );
+    });
+
+    it('turns a base64 user image into a blob attachment and drops it from the prompt text', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'user', type: 'text', text: 'what is this?' },
+            { actor: 'user', type: 'image', image: { base64data: 'aGk=', mimeType: 'image/png' } }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.prompt).to.equal('what is this?');
+        expect(result.attachments).to.deep.equal([{ type: 'blob', data: 'aGk=', mimeType: 'image/png' }]);
+    });
+
+    it('collects multiple base64 images in message order', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'user', type: 'image', image: { base64data: 'AAA=', mimeType: 'image/png' } },
+            { actor: 'user', type: 'image', image: { base64data: 'BBB=', mimeType: 'image/jpeg' } }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.attachments).to.deep.equal([
+            { type: 'blob', data: 'AAA=', mimeType: 'image/png' },
+            { type: 'blob', data: 'BBB=', mimeType: 'image/jpeg' }
+        ]);
+    });
+
+    it('leaves attachments undefined when there are no images', () => {
+        const result = buildSdkPrompt([{ actor: 'user', type: 'text', text: 'hi' }]);
+        expect(result.attachments).to.be.undefined;
+    });
+
+    it('does not attach a URL image and renders it as an omitted placeholder instead', () => {
+        const messages: LanguageModelMessage[] = [
+            { actor: 'user', type: 'text', text: 'look' },
+            { actor: 'user', type: 'image', image: { url: 'https://example.com/a.png' } }
+        ];
+        const result = buildSdkPrompt(messages);
+        expect(result.attachments).to.be.undefined;
+        expect(result.prompt).to.equal('User: look\n\nUser: [image omitted]');
+    });
+});
+
+describe('copilot-sdk-mappers - buildSdkSystemMessage', () => {
+    it('carries the system text as the content of the system message', () => {
+        const systemMessage = buildSdkSystemMessage('be helpful');
+        expect(systemMessage?.mode).to.equal('customize');
+        expect(systemMessage?.content).to.equal('be helpful');
+    });
+
+    it('removes the agent instructions of the CLI that the Theia prompt replaces', () => {
+        const systemMessage = buildSdkSystemMessage('be helpful');
+        const sections = systemMessage?.mode === 'customize' ? systemMessage.sections : undefined;
+        expect(Object.keys(sections ?? {})).to.have.members(['identity', 'tone', 'guidelines', 'code_change_rules']);
+        for (const section of Object.values(sections ?? {})) {
+            expect(section?.action).to.equal('remove');
+        }
+    });
+
+    it('keeps the tool instructions of the CLI, which tool calling relies on', () => {
+        const systemMessage = buildSdkSystemMessage('be helpful');
+        const sections = systemMessage?.mode === 'customize' ? systemMessage.sections : undefined;
+        expect(sections).to.not.have.property('tool_instructions');
+        expect(sections).to.not.have.property('safety');
+    });
+
+    it('configures nothing when the request has no system text', () => {
+        expect(buildSdkSystemMessage('')).to.be.undefined;
+    });
+});

package/src/node/copilot-sdk-mappers.ts

@@ -0,0 +1,172 @@
+// *****************************************************************************
+// 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 { Base64ImageContent, ImageContent, ImageMessage, LanguageModelMessage } from '@theia/ai-core';
+import type { BlobMessageAttachment, ModelInfo, SystemMessageConfig } from './copilot-sdk-types';
+
+/**
+ * Selects the model IDs that should be surfaced to Theia from the list returned
+ * by `CopilotClient.listModels()`.
+ *
+ * Models whose policy is explicitly `disabled` are filtered out; `enabled` and
+ * `unconfigured` models are kept. Order is preserved and duplicates are removed.
+ *
+ * The list can name the same model both by its family and by its dated releases, and both are kept:
+ * the family is what the model pickers offer, while a dated release stays selectable for anyone who
+ * wants to pin one. This mirrors the other providers, where discovery reports every release and only
+ * the undated ids are featured.
+ */
+export function selectSdkModelIds(models: ModelInfo[]): string[] {
+    const result: string[] = [];
+    const seen = new Set<string>();
+    for (const model of models) {
+        if (!model.id || seen.has(model.id)) {
+            continue;
+        }
+        if (model.policy && model.policy.state === 'disabled') {
+            continue;
+        }
+        seen.add(model.id);
+        result.push(model.id);
+    }
+    return result;
+}
+
+/**
+ * The result of flattening a Theia message history into a single prompt for the
+ * agentic Copilot SDK session.
+ */
+export interface SdkPrompt {
+    /** Concatenated content of all system messages (may be empty). */
+    systemText: string;
+    /** The user-facing prompt body derived from the non-system messages. */
+    prompt: string;
+    /** Base64-encoded images pulled out of the user's messages, sent alongside the prompt. */
+    attachments?: BlobMessageAttachment[];
+}
+
+function roleLabel(message: LanguageModelMessage): string {
+    switch (message.actor) {
+        case 'ai':
+            return 'Assistant';
+        case 'system':
+            return 'System';
+        default:
+            return 'User';
+    }
+}
+
+/**
+ * Whether a message is a user image the SDK can be sent as a blob attachment.
+ *
+ * URL images are not covered: the SDK's attachments carry inline data, not a remote reference,
+ * and fetching the URL on the backend to inline it would add a server-side-request-forgery
+ * surface for what is, today, not a use case Theia exercises.
+ */
+function isAttachableImageMessage(message: LanguageModelMessage): message is ImageMessage & { image: Base64ImageContent } {
+    return LanguageModelMessage.isImageMessage(message) && message.actor === 'user' && ImageContent.isBase64(message.image);
+}
+
+function messageToText(message: LanguageModelMessage): string {
+    if (LanguageModelMessage.isTextMessage(message)) {
+        return message.text;
+    }
+    if (LanguageModelMessage.isToolUseMessage(message)) {
+        return `[tool call: ${message.name} ${JSON.stringify(message.input)}]`;
+    }
+    if (LanguageModelMessage.isToolResultMessage(message)) {
+        const content = message.content === undefined
+            ? ''
+            : (typeof message.content === 'string' ? message.content : JSON.stringify(message.content));
+        return `[tool result: ${content}]`;
+    }
+    if (LanguageModelMessage.isImageMessage(message)) {
+        // Reached for URL images and non-user image messages; base64 user images are attachments instead, see buildSdkPrompt.
+        return '[image omitted]';
+    }
+    return '';
+}
+
+/**
+ * Flattens a Theia message history into an {@link SdkPrompt}.
+ *
+ * The Copilot SDK session is a stateful agent that accepts a single prompt
+ * string per `send()` call, so the full Theia history is collapsed here. System
+ * messages are extracted separately and become the system message of the session,
+ * see {@link buildSdkSystemMessage}. A lone user turn is forwarded verbatim;
+ * richer histories are rendered as a role-labelled transcript.
+ *
+ * Base64 user images are pulled out of the history and sent as blob attachments instead of
+ * being flattened into the prompt text, see {@link isAttachableImageMessage}. This is otherwise
+ * a lossy mapping by design, see the limitations documented in the package README, and is
+ * intended for single-turn requests.
+ */
+export function buildSdkPrompt(messages: LanguageModelMessage[]): SdkPrompt {
+    const systemParts: string[] = [];
+    const conversation: LanguageModelMessage[] = [];
+    const attachments: BlobMessageAttachment[] = [];
+    for (const message of messages) {
+        if (message.actor === 'system' && LanguageModelMessage.isTextMessage(message)) {
+            systemParts.push(message.text);
+        } else if (message.type === 'thinking') {
+            continue;
+        } else if (isAttachableImageMessage(message)) {
+            attachments.push({ type: 'blob', data: message.image.base64data, mimeType: message.image.mimeType });
+        } else {
+            conversation.push(message);
+        }
+    }
+
+    const systemText = systemParts.join('\n\n').trim();
+
+    let prompt: string;
+    if (conversation.length === 1 && LanguageModelMessage.isTextMessage(conversation[0]) && conversation[0].actor === 'user') {
+        prompt = conversation[0].text;
+    } else {
+        prompt = conversation
+            .map(message => `${roleLabel(message)}: ${messageToText(message)}`)
+            .join('\n\n')
+            .trim();
+    }
+
+    return { systemText, prompt, attachments: attachments.length > 0 ? attachments : undefined };
+}
+
+/**
+ * Builds the system message configuration of a session from the system text of a request.
+ *
+ * The CLI is an agent with a system prompt of its own, while a Theia agent brings a complete one.
+ * The sections that describe who the agent is and how it should work are therefore removed, so that
+ * they cannot contradict the prompt of the Theia agent, and the prompt is added in their place. The
+ * sections that make tool calling work and the ones that carry the safety rules of the CLI are kept:
+ * this integration declares Theia's tools to the CLI, so the model still has to be told how to call
+ * them. Replacing the message as a whole would drop those as well.
+ */
+export function buildSdkSystemMessage(systemText: string): SystemMessageConfig | undefined {
+    if (!systemText) {
+        return undefined;
+    }
+    return {
+        mode: 'customize',
+        sections: {
+            identity: { action: 'remove' },
+            tone: { action: 'remove' },
+            guidelines: { action: 'remove' },
+            code_change_rules: { action: 'remove' }
+        },
+        content: systemText
+    };
+}

package/src/node/copilot-sdk-types.ts

@@ -0,0 +1,290 @@
+// *****************************************************************************
+// 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 declarations in this file mirror the API of the GitHub Copilot SDK '@github/copilot-sdk' (1.0.9)
+// - https://github.com/github/copilot-sdk
+// '@github/copilot-sdk' copyright:
+/*---------------------------------------------------------------------------------------------
+ *  Copyright GitHub, Inc.
+ *  Licensed under the MIT License. See LICENSE in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+/**
+ * The part of the Copilot SDK API this integration uses, mirrored by hand.
+ *
+ * Mirrored from `@github/copilot-sdk` 1.0.9 (protocol version 3), which the Copilot CLI 1.0.79 ships.
+ * The package is deliberately not a dependency: it depends on the CLI, a large proprietary binary that
+ * would end up in the tree and the lockfile of every application. The CLI is a prerequisite on the
+ * backend host instead, see `CopilotCliLocator`, and the SDK is loaded from it at runtime, see
+ * `CopilotSdkLoader`.
+ *
+ * Only what this integration passes to the SDK or reads from it is declared, so a drift shows up as a
+ * compile error here rather than at runtime. `scripts/copilot-sdk-mirror` checks the mirror against a
+ * released SDK and runs in CI on a schedule; update the version above along with the declarations.
+ */
+
+// ============================================================================
+// Models, from `dist/types.d.ts`
+// ============================================================================
+
+export interface ModelPolicy {
+    state: 'enabled' | 'disabled' | 'unconfigured';
+}
+
+/** A model as reported by {@link CopilotClient.listModels}. */
+export interface ModelInfo {
+    /** Model identifier, for example `claude-sonnet-4.5`. */
+    id: string;
+    policy?: ModelPolicy;
+}
+
+// ============================================================================
+// System message, from `dist/types.d.ts`
+// ============================================================================
+
+/** The sections the runtime assembles its system prompt from. Unknown ids are a silent no-op there. */
+export type SystemMessageSection =
+    | 'preamble'
+    | 'identity'
+    | 'tone'
+    | 'tool_efficiency'
+    | 'environment_context'
+    | 'code_change_rules'
+    | 'guidelines'
+    | 'safety'
+    | 'tool_instructions'
+    | 'custom_instructions'
+    | 'runtime_instructions'
+    | 'last_instructions';
+
+export type SectionTransformFn = (currentContent: string) => string | Promise<string>;
+
+export type SectionOverrideAction = 'replace' | 'remove' | 'append' | 'prepend' | 'preserve' | SectionTransformFn;
+
+export interface SectionOverride {
+    action: SectionOverrideAction;
+    content?: string;
+}
+
+/** The SDK foundation plus the given content. */
+export interface SystemMessageAppendConfig {
+    mode?: 'append';
+    content?: string;
+}
+
+/** The given content as the entire system message. */
+export interface SystemMessageReplaceConfig {
+    mode: 'replace';
+    content: string;
+}
+
+/** The SDK structure with section-level overrides, which is what this integration uses. */
+export interface SystemMessageCustomizeConfig {
+    mode: 'customize';
+    sections?: Partial<Record<SystemMessageSection, SectionOverride>>;
+    content?: string;
+}
+
+export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
+
+// ============================================================================
+// Tools, from `dist/types.d.ts`
+// ============================================================================
+
+/** What the runtime tells a tool handler about its invocation. */
+export interface ToolInvocation {
+    sessionId: string;
+    toolCallId: string;
+    toolName: string;
+    arguments: unknown;
+}
+
+export type ToolHandler = (args: unknown, invocation: ToolInvocation) => Promise<unknown> | unknown;
+
+/** A tool declared to the runtime. `parameters` also accepts a Zod schema upstream. */
+export interface Tool {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    handler?: ToolHandler;
+    /** When true, the tool runs without a permission prompt of the runtime. */
+    skipPermission?: boolean;
+}
+
+// ============================================================================
+// Permissions, from `dist/types.d.ts` and `dist/generated/rpc.d.ts`
+// ============================================================================
+
+/**
+ * A permission request of the runtime, upstream a union over the kind of operation with its own fields.
+ * Only `managedApprovalRequired` is read, which managed policy sets for a request it reserves for the
+ * user.
+ */
+export interface PermissionRequest {
+    readonly kind: string;
+    readonly managedApprovalRequired?: boolean;
+}
+
+/** The decisions this integration can return. Upstream also has scopes that outlive a request. */
+export type PermissionRequestResult =
+    | { kind: 'approve-once' }
+    | { kind: 'reject', feedback?: string }
+    /** No user is available to confirm the request. */
+    | { kind: 'user-not-available' }
+    /** Leaves the request pending, so that another connected client can answer it. */
+    | { kind: 'no-result' };
+
+export type PermissionHandler = (
+    request: PermissionRequest,
+    invocation: { sessionId: string, managedSettingsEnabled?: boolean }
+) => Promise<PermissionRequestResult> | PermissionRequestResult;
+
+// ============================================================================
+// Session events, from `dist/generated/session-events.d.ts`
+// ============================================================================
+
+/** The envelope every session event comes in. */
+export interface SessionEvent<T extends string, D> {
+    readonly type: T;
+    readonly data: D;
+}
+
+/** The session events this integration listens to, keyed by their type discriminator. */
+export interface CopilotSessionEvents {
+    'assistant.message_delta': SessionEvent<'assistant.message_delta', {
+        readonly deltaContent: string
+    }>;
+    'assistant.reasoning_delta': SessionEvent<'assistant.reasoning_delta', {
+        readonly deltaContent: string
+    }>;
+    'assistant.message': SessionEvent<'assistant.message', {
+        readonly content: string,
+        readonly outputTokens?: number
+    }>;
+    'assistant.usage': SessionEvent<'assistant.usage', {
+        readonly inputTokens?: number,
+        readonly outputTokens?: number
+    }>;
+    /** Nothing of its payload is read, the event itself is the signal that the turn is over. */
+    'session.idle': SessionEvent<'session.idle', unknown>;
+    'session.error': SessionEvent<'session.error', {
+        readonly errorType: string,
+        readonly message: string,
+        readonly statusCode?: number,
+        readonly stack?: string
+    }>;
+}
+
+export type CopilotSessionEventType = keyof CopilotSessionEvents;
+
+// ============================================================================
+// Session, from `dist/session.d.ts` and `dist/types.d.ts`
+// ============================================================================
+
+/** The one attachment kind this integration produces: an inline image, from `MessageOptions['attachments']`. */
+export interface BlobMessageAttachment {
+    type: 'blob';
+    data: string;
+    mimeType: string;
+    displayName?: string;
+}
+
+/** The options this integration passes to {@link CopilotSession.send}. */
+export interface MessageOptions {
+    prompt: string;
+    attachments?: BlobMessageAttachment[];
+}
+
+/** A conversation with the runtime, upstream a class with resume, fork and sharing on top. */
+export interface CopilotSession {
+    readonly sessionId: string;
+    /**
+     * Registers a handler for one type of event and returns the function that removes it again.
+     */
+    on<K extends CopilotSessionEventType>(eventType: K, handler: (event: CopilotSessionEvents[K]) => void): () => void;
+    /** Sends a turn and resolves with the id of the message it created. */
+    send(options: MessageOptions): Promise<string>;
+    /** Stops the turn in flight. */
+    abort(): Promise<void>;
+    /** Releases the session in memory, leaving what it persisted in place. */
+    disconnect(): Promise<void>;
+}
+
+// ============================================================================
+// Client, from `dist/client.d.ts` and `dist/types.d.ts`
+// ============================================================================
+
+/** How the SDK reaches the runtime. This integration always spawns the CLI it located. */
+export interface StdioRuntimeConnection {
+    readonly kind: 'stdio';
+    readonly path?: string;
+    readonly args?: readonly string[];
+    readonly env?: Record<string, string>;
+}
+
+export type RuntimeConnection = StdioRuntimeConnection;
+
+/** The `RuntimeConnection` value of the SDK, of which only the stdio factory is used. */
+export interface RuntimeConnectionFactory {
+    readonly forStdio: (options?: { path?: string, args?: readonly string[], env?: Record<string, string> }) => StdioRuntimeConnection;
+}
+
+/**
+ * Selects the defaults of the runtime: `copilot-cli` brings the ambient behaviour of the CLI along,
+ * `empty` requires the application to opt into what it needs.
+ */
+export type CopilotClientMode = 'empty' | 'copilot-cli';
+
+/** The client options this integration sets. */
+export interface CopilotClientOptions {
+    connection?: RuntimeConnection;
+    mode?: CopilotClientMode;
+    /** Copilot home of the runtime, which becomes its `COPILOT_HOME`. Required in `empty` mode. */
+    baseDirectory?: string;
+    logLevel?: 'none' | 'error' | 'warning' | 'info' | 'debug' | 'all';
+    env?: Record<string, string | undefined>;
+    gitHubToken?: string;
+    /** When false, only an explicit token is used and no sign-in found on the host. */
+    useLoggedInUser?: boolean;
+}
+
+/** The session configuration this integration passes. */
+export interface SessionConfig {
+    model?: string;
+    streaming?: boolean;
+    tools?: Tool[];
+    systemMessage?: SystemMessageConfig;
+    /**
+     * The tools to enable, as source-qualified patterns such as `custom:*` or `builtin:<name>`.
+     * Required in `empty` mode.
+     */
+    availableTools?: string[];
+    onPermissionRequest?: PermissionHandler;
+}
+
+/** The runtime as seen by this integration, upstream a class with the full session and status API. */
+export interface CopilotClient {
+    /** Starts the runtime and connects to it. */
+    start(): Promise<void>;
+    /** Stops the runtime and resolves with the errors its cleanup ran into, if any. */
+    stop(): Promise<Error[]>;
+    listModels(): Promise<ModelInfo[]>;
+    createSession(config: SessionConfig): Promise<CopilotSession>;
+    /** Removes a session and what it persisted in the Copilot home. */
+    deleteSession(sessionId: string): Promise<void>;
+}
+
+export type CopilotClientConstructor = new (options?: CopilotClientOptions) => CopilotClient;

package/src/node/index.ts

@@ -15,5 +15,13 @@
 // *****************************************************************************
 
 export * from './copilot-auth-service-impl';
-export * from './copilot-language-model';
 export * from './copilot-language-models-manager-impl';
+export * from './copilot-cli-auth-provider';
+export * from './copilot-cli-locator';
+export * from './copilot-credential-store';
+export * from './copilot-runtime-env';
+export * from './copilot-sdk-client-provider';
+export * from './copilot-sdk-loader';
+export * from './copilot-sdk-mappers';
+export * from './copilot-sdk-language-model';
+export * from './copilot-sdk-types';