dsh-plugin-subscriptions 0.4.2 → 0.5.1

package/lib/providers/grok.d.ts

@@ -101,13 +101,17 @@ export declare function fetchGrokCliCatalog(session: GrokSession, fetchFn?: Fetc
  * metadata (display name, context window, reasoning efforts). The api.x.ai
  * list stays authoritative for which models exist; the CLI catalog is
  * enrichment only, so its failure degrades to a plain list instead of taking
- * discovery down — models it does not cover simply expose no efforts.
+ * discovery down. When enrichment is missing, last-known capability metadata
+ * is carried forward so a transient CLI outage cannot strip efforts a
+ * session already selected.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param onWarn - warning sink for a failed CLI catalog fetch.
+ * @param previous - last-known catalog used to keep enrichment when the CLI
+ *   catalog is down or omits a model.
  * @returns discovered chat models in endpoint order.
  */
-export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void): Promise<DiscoveredModel[]>;
+export declare function fetchGrokModels(session: GrokSession, fetchFn?: FetchFn, onWarn?: (message: string) => void, previous?: readonly DiscoveredModel[]): Promise<DiscoveredModel[]>;
 /** Constructor dependencies for {@link GrokAdapter}. */
 export interface GrokAdapterOptions {
     models: readonly ModelEntry[];
@@ -131,6 +135,7 @@ export declare class GrokAdapter extends LlmAdapter {
     constructor(options: GrokAdapterOptions);
     /** Discovery fetcher: resolves the session through the refresh-aware path. */
     private fetchCatalog;
+    private listed;
     providerInfo(provider: string): LlmProviderInfo;
     private staticModels;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;

package/lib/providers/grok.js

@@ -7,7 +7,7 @@ import { attributionHeaders, EMPTY_RESPONSE_CODE, errorChain, LlmAdapter, LlmErr
 import { decodeJwtPayload } from '../auth/jwt.js';
 import { resolveImages } from '../translate/resolved.js';
 import { streamResponses, toResponsesInput, toResponsesTools } from '../translate/responses.js';
-import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
+import { httpLlmError, idleWatchdog, mapFetchFailure, ModelCatalogCache, discoverOrRetryAuth, isMissingOrInvalidCredential, oauthEndpointError, OAuthEndpointError, TokenManager, } from './common.js';
 export const GROK_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828';
 export const GROK_DISCOVERY_URL = 'https://auth.x.ai/.well-known/openid-configuration';
 export const GROK_API_URL = 'https://api.x.ai/v1/responses';
@@ -355,18 +355,40 @@ export async function fetchGrokCliCatalog(session, fetchFn = fetch) {
 function isChatModel(id) {
     return !/imagine|image-|video|embed/i.test(id);
 }
+/**
+ * CLI-contributed fields carried forward from a previously discovered model.
+ * @param prior - the last-known entry for this id, if any.
+ * @returns enrichment to apply when the live CLI catalog cannot contribute.
+ */
+function grokPriorMeta(prior) {
+    if (prior === undefined)
+        return {};
+    return {
+        ...(prior.name.length > 0 ? { name: prior.name } : {}),
+        ...(prior.description === undefined ? {} : { description: prior.description }),
+        ...(prior.contextWindow === undefined ? {} : { contextWindow: prior.contextWindow }),
+        ...(prior.reasoning === undefined ? {} : { reasoning: prior.reasoning }),
+    };
+}
 /**
  * Fetch the live grok model list, enriched with the CLI catalog's per-model
  * metadata (display name, context window, reasoning efforts). The api.x.ai
  * list stays authoritative for which models exist; the CLI catalog is
  * enrichment only, so its failure degrades to a plain list instead of taking
- * discovery down — models it does not cover simply expose no efforts.
+ * discovery down. When enrichment is missing, last-known capability metadata
+ * is carried forward so a transient CLI outage cannot strip efforts a
+ * session already selected.
  * @param session - the stored session (used as-is; never refreshed here).
  * @param fetchFn - fetch implementation (injectable for tests).
  * @param onWarn - warning sink for a failed CLI catalog fetch.
+ * @param previous - last-known catalog used to keep enrichment when the CLI
+ *   catalog is down or omits a model.
  * @returns discovered chat models in endpoint order.
  */
-export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
+export async function fetchGrokModels(session, fetchFn = fetch, onWarn, previous) {
+    const previousById = previous === undefined || previous.length === 0
+        ? undefined
+        : new Map(previous.map(model => [model.id, model]));
     const [response, cliCatalog] = await Promise.all([
         fetchFn(GROK_MODELS_URL, {
             headers: {
@@ -376,7 +398,9 @@ export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
             },
         }),
         fetchGrokCliCatalog(session, fetchFn).catch((error) => {
-            onWarn?.(`grok CLI catalog fetch failed; reasoning efforts are unavailable (${errorChain(error)})`);
+            onWarn?.(previousById === undefined
+                ? `grok CLI catalog fetch failed; reasoning efforts are unavailable (${errorChain(error)})`
+                : `grok CLI catalog fetch failed; keeping last-known reasoning efforts (${errorChain(error)})`);
             return undefined;
         }),
     ]);
@@ -393,7 +417,12 @@ export async function fetchGrokModels(session, fetchFn = fetch, onWarn) {
         if (!isChatModel(entry.id))
             continue;
         seen.add(entry.id);
-        discovered.push({ id: entry.id, name: entry.id, ...cliCatalog?.get(entry.id) });
+        const cli = cliCatalog?.get(entry.id);
+        discovered.push({
+            id: entry.id,
+            name: entry.id,
+            ...(cli ?? grokPriorMeta(previousById?.get(entry.id))),
+        });
     }
     // An empty catalog from a 200 response is treated as a discovery failure so
     // the adapter falls back to the static catalog instead of vanishing from
@@ -413,7 +442,16 @@ export class GrokAdapter extends LlmAdapter {
     }
     /** Discovery fetcher: resolves the session through the refresh-aware path. */
     async fetchCatalog() {
-        return fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn);
+        return fetchGrokModels(await this.options.tokens.session(), this.options.fetchFn, this.options.onWarn, this.catalog.lastKnown());
+    }
+    listed(provider, discovered) {
+        return discovered.map(model => ({
+            provider,
+            id: model.id,
+            name: model.name,
+            ...model.description === undefined ? {} : { description: model.description },
+            inputModalities: grokModalities(model.id),
+        }));
     }
     providerInfo(provider) {
         return { id: provider, name: 'Grok (Subscription)' };
@@ -437,23 +475,13 @@ export class GrokAdapter extends LlmAdapter {
             // The fetcher runs only on a cache miss, and resolves the session
             // through the refresh-aware path so an expired access token renews here
             // instead of failing discovery into the static fallback.
-            const discovered = await this.catalog.get(() => this.fetchCatalog());
-            return discovered.map(model => ({
-                provider,
-                id: model.id,
-                name: model.name,
-                ...model.description === undefined ? {} : { description: model.description },
-                inputModalities: grokModalities(model.id),
-            }));
+            return this.listed(provider, await discoverOrRetryAuth(force => this.options.tokens.session(force), this.catalog, () => this.catalog.get(() => this.fetchCatalog())));
         }
         catch (error) {
             // A permanent refresh failure deletes the stored session: the provider
             // is logged out, so hide it instead of showing a stale static catalog.
-            if (error instanceof LlmError
-                && (error.code === 'MISSING_CREDENTIAL' || error.code === 'INVALID_CREDENTIAL'))
+            if (isMissingOrInvalidCredential(error))
                 return [];
-            if (error instanceof OAuthEndpointError && error.status === 401)
-                this.catalog.invalidate();
             this.options.onWarn?.(`grok model discovery failed; using the built-in catalog (${errorChain(error)})`);
             return this.staticModels(provider);
         }

package/lib/tools/image-generate.js

@@ -16,7 +16,6 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
 import { AttachmentId } from '@deepseek-ai/dsh-attachment';
-import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { httpLlmError, TokenManager } from '../providers/common.js';
 /** Endpoint the codex generation request is posted to. */
@@ -334,15 +333,9 @@ export function createImageGenerateTool(options) {
                 ...refs.length > 0 ? { images: refs } : {},
                 ...revisedPrompt === undefined ? {} : { revisedPrompt },
             };
-            // Nested (Code Mode) dispatches have no card: defer the image content as
-            // a user message so the next model request still sees it (read_image's
-            // pattern).
-            if (exec.parent !== undefined && refs.length > 0) {
-                exec.deferContext(createUserMessage({
-                    content: imageGenerateContent(value),
-                    source: { kind: 'plugin', plugin: 'dsh-plugin-subscriptions' },
-                }));
-            }
+            // Nested (Code Mode) dispatches need no defer here: the harness's code
+            // mode already defers any image-bearing sub-result as a user message, so
+            // deferring again would inject the same attachment twice.
             return value;
         },
     });

package/lib/translate/anthropic.d.ts

@@ -13,6 +13,25 @@ import type { TranslatableMessage } from './resolved.js';
  * system entry on every request.
  */
 export declare const CLAUDE_CODE_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude.";
+/** Tags wrapping a mid-conversation system message where it sits in the history. */
+export declare const SYSTEM_REMINDER_OPEN = "<system-reminder>";
+export declare const SYSTEM_REMINDER_CLOSE = "</system-reminder>";
+/**
+ * How far apart consecutive message breakpoints sit, in content blocks.
+ *
+ * A breakpoint looks back at most 20 blocks for an entry an earlier request
+ * wrote, so marks must stay closer than that: one agentic turn can append a
+ * dozen tool_use/tool_result blocks at once, and a single trailing mark would
+ * silently fall out of range and rebuild the whole prefix.
+ */
+export declare const CACHE_BLOCK_STRIDE = 15;
+/**
+ * Message breakpoints per request. Anthropic allows four in total and the
+ * last `system` block takes the fourth, so three are left for the history —
+ * enough to tolerate a turn appending roughly {@link CACHE_BLOCK_STRIDE} × 3
+ * blocks before a read is lost.
+ */
+export declare const MESSAGE_CACHE_BREAKPOINTS = 3;
 /** One Anthropic request message. */
 export interface AnthropicMessage {
     role: 'user' | 'assistant';
@@ -21,27 +40,49 @@ export interface AnthropicMessage {
 /**
  * Convert harness messages into Anthropic messages. Consecutive same-role
  * messages merge into one message with multiple content blocks; tool results
- * arrive as user messages with `tool_result` blocks; system-role messages are
- * handled by {@link toAnthropicSystem} and skipped here. Reasoning blocks are
- * not replayed (v1). Images must arrive pre-resolved
+ * arrive as user messages with `tool_result` blocks, which a merged user
+ * message keeps in one leading run ({@link leadWithToolResults}); system-role
+ * messages before the conversation starts are handled by
+ * {@link toAnthropicSystem} and skipped here, while a later one rides in
+ * place as a user-role `<system-reminder>` block.
+ * Reasoning blocks are not replayed (v1). Images must arrive pre-resolved
  * ({@link TranslatableMessage}); an unresolved ImageBlock is skipped because
  * its bytes are unreachable here.
  * @param messages - ordered conversation messages with resolved images.
  * @returns Anthropic messages in conversation order.
  */
 export declare function toAnthropicMessages(messages: readonly TranslatableMessage[]): AnthropicMessage[];
+/**
+ * Mark the conversation's cache breakpoints in place: the last content block,
+ * then one every {@link CACHE_BLOCK_STRIDE} blocks backwards, {@link
+ * MESSAGE_CACHE_BREAKPOINTS} in total.
+ *
+ * The history is append-only, so the block one request marks last is
+ * byte-identical in the next — that entry is what the next request reads.
+ * Marks are counted across the flattened block sequence, not per message,
+ * because the lookback window Anthropic walks counts blocks the same way.
+ * @param messages - assembled Anthropic messages, marked in place.
+ */
+export declare function markMessageCache(messages: readonly AnthropicMessage[]): void;
 /**
  * Build the Anthropic `system` array: the mandatory Claude Code identity
  * block, then the explicit system prompt, then any system-role messages.
  * @param system - explicit system prompt, when set.
- * @param messages - conversation messages; their system-role text is appended.
+ * @param messages - conversation messages; the system-role text preceding the
+ * conversation is appended, and a later one is left to {@link toAnthropicMessages}.
  * @returns the system content blocks.
  */
 export declare function toAnthropicSystem(system?: string, messages?: readonly TranslatableMessage[]): Record<string, unknown>[];
 /**
- * Map harness tool schemas to Anthropic tools.
+ * Map harness tool schemas to Anthropic tools, in name order.
+ *
+ * `tools` renders at position 0 of the cached prefix, so any reordering
+ * invalidates every cache entry behind it — `system` and the whole
+ * conversation included. Registration order belongs to the caller and plugin
+ * load order can differ between processes, so the wire order is fixed here
+ * instead. Anthropic selects a tool by name; the array order carries nothing.
  * @param tools - tool schemas from the request.
- * @returns Anthropic `tools` array entries.
+ * @returns Anthropic `tools` array entries, ordered by tool name.
  */
 export declare function toAnthropicTools(tools: readonly ToolSchema[]): Record<string, unknown>[];
 /** The subset of Anthropic SSE event shapes this translator reads. */

package/lib/translate/anthropic.js

@@ -12,6 +12,25 @@ import { parseSse } from './sse.js';
  * system entry on every request.
  */
 export const CLAUDE_CODE_IDENTITY = 'You are Claude Code, Anthropic\'s official CLI for Claude.';
+/** Tags wrapping a mid-conversation system message where it sits in the history. */
+export const SYSTEM_REMINDER_OPEN = '<system-reminder>';
+export const SYSTEM_REMINDER_CLOSE = '</system-reminder>';
+/**
+ * How far apart consecutive message breakpoints sit, in content blocks.
+ *
+ * A breakpoint looks back at most 20 blocks for an entry an earlier request
+ * wrote, so marks must stay closer than that: one agentic turn can append a
+ * dozen tool_use/tool_result blocks at once, and a single trailing mark would
+ * silently fall out of range and rebuild the whole prefix.
+ */
+export const CACHE_BLOCK_STRIDE = 15;
+/**
+ * Message breakpoints per request. Anthropic allows four in total and the
+ * last `system` block takes the fourth, so three are left for the history —
+ * enough to tolerate a turn appending roughly {@link CACHE_BLOCK_STRIDE} × 3
+ * blocks before a read is lost.
+ */
+export const MESSAGE_CACHE_BREAKPOINTS = 3;
 /** Flatten a tool result's content to plain text for `tool_result`. */
 function toolResultText(block) {
     return block.content.map(part => (part.type === 'text' ? part.text : '')).join('');
@@ -30,12 +49,55 @@ function parseToolInput(raw) {
         return {};
     }
 }
+/**
+ * Move a user message's `tool_result` blocks into one contiguous run at the
+ * front, preserving the relative order of both groups.
+ *
+ * Anthropic answers every `tool_use` against the blocks that *lead* the next
+ * message, so a block of any other kind before or between the results reads
+ * as a call left unanswered and the request is rejected. The harness merges
+ * everything queued for one user turn into a single message, and a parallel
+ * tool batch arrives as one result message per call, so any context spliced
+ * mid-batch lands between two results. Restoring the run here keeps that
+ * independent of delivery order. Order *among* the results does not matter.
+ * @param message - one assembled user message, reordered in place.
+ */
+function leadWithToolResults(message) {
+    const firstOther = message.content.findIndex(block => block.type !== 'tool_result');
+    if (firstOther === -1)
+        return;
+    if (!message.content.slice(firstOther).some(block => block.type === 'tool_result'))
+        return;
+    message.content = [
+        ...message.content.filter(block => block.type === 'tool_result'),
+        ...message.content.filter(block => block.type !== 'tool_result'),
+    ];
+}
+/**
+ * Index of the first non-system message; `messages.length` when every message
+ * is a system one.
+ *
+ * A system message before the conversation starts is the operator's opening
+ * instruction and belongs in the `system` slot. One that arrives later is
+ * mid-conversation context, and hoisting it into `system` would move bytes in
+ * front of the whole history — invalidating every cached turn behind it — so
+ * it stays where it is, as a reminder block in `messages`.
+ * @param messages - ordered conversation messages.
+ * @returns the boundary index separating the two.
+ */
+function conversationStart(messages) {
+    const index = messages.findIndex(message => message.role !== 'system');
+    return index === -1 ? messages.length : index;
+}
 /**
  * Convert harness messages into Anthropic messages. Consecutive same-role
  * messages merge into one message with multiple content blocks; tool results
- * arrive as user messages with `tool_result` blocks; system-role messages are
- * handled by {@link toAnthropicSystem} and skipped here. Reasoning blocks are
- * not replayed (v1). Images must arrive pre-resolved
+ * arrive as user messages with `tool_result` blocks, which a merged user
+ * message keeps in one leading run ({@link leadWithToolResults}); system-role
+ * messages before the conversation starts are handled by
+ * {@link toAnthropicSystem} and skipped here, while a later one rides in
+ * place as a user-role `<system-reminder>` block.
+ * Reasoning blocks are not replayed (v1). Images must arrive pre-resolved
  * ({@link TranslatableMessage}); an unresolved ImageBlock is skipped because
  * its bytes are unreachable here.
  * @param messages - ordered conversation messages with resolved images.
@@ -43,24 +105,41 @@ function parseToolInput(raw) {
  */
 export function toAnthropicMessages(messages) {
     const out = [];
-    for (const message of messages) {
-        if (message.role === 'system')
+    const start = conversationStart(messages);
+    for (const [index, message] of messages.entries()) {
+        // A leading system message is an opening instruction; toAnthropicSystem
+        // owns those. A later one rides here so the cached prefix ahead of it
+        // stays byte-identical.
+        if (message.role === 'system' && index < start)
             continue;
-        const role = message.role;
+        const role = message.role === 'system' ? 'user' : message.role;
         const blocks = [];
         for (const block of message.content) {
             switch (block.type) {
                 case 'text':
-                    blocks.push({ type: 'text', text: block.text });
-                    break;
-                case 'tool-call':
                     blocks.push({
-                        type: 'tool_use',
-                        id: String(block.id),
-                        name: block.name,
-                        input: parseToolInput(block.arguments),
+                        type: 'text',
+                        text: message.role === 'system'
+                            ? `${SYSTEM_REMINDER_OPEN}${block.text}${SYSTEM_REMINDER_CLOSE}`
+                            : block.text,
                     });
                     break;
+                case 'tool-call':
+                    // Anthropic accepts `tool_use` only in assistant messages, and only
+                    // when a matching `tool_result` follows. A tool call in any other
+                    // role is replayed narrative — a settled subagent's closing message
+                    // spliced into the parent as a user-role notice carries the calls it
+                    // died holding, which no result will ever answer — so it rides as
+                    // descriptive text instead of a call the API would reject.
+                    blocks.push(role === 'assistant'
+                        ? {
+                            type: 'tool_use',
+                            id: String(block.id),
+                            name: block.name,
+                            input: parseToolInput(block.arguments),
+                        }
+                        : { type: 'text', text: `[tool call ${block.name}: ${block.arguments}]` });
+                    break;
                 case 'tool-result':
                     blocks.push({
                         type: 'tool_result',
@@ -92,36 +171,72 @@ export function toAnthropicMessages(messages) {
         else
             out.push({ role, content: blocks });
     }
+    for (const message of out) {
+        if (message.role === 'user')
+            leadWithToolResults(message);
+    }
     return out;
 }
+/**
+ * Mark the conversation's cache breakpoints in place: the last content block,
+ * then one every {@link CACHE_BLOCK_STRIDE} blocks backwards, {@link
+ * MESSAGE_CACHE_BREAKPOINTS} in total.
+ *
+ * The history is append-only, so the block one request marks last is
+ * byte-identical in the next — that entry is what the next request reads.
+ * Marks are counted across the flattened block sequence, not per message,
+ * because the lookback window Anthropic walks counts blocks the same way.
+ * @param messages - assembled Anthropic messages, marked in place.
+ */
+export function markMessageCache(messages) {
+    const blocks = messages.flatMap(message => message.content);
+    for (let mark = 0; mark < MESSAGE_CACHE_BREAKPOINTS; mark++) {
+        const at = blocks.length - 1 - mark * CACHE_BLOCK_STRIDE;
+        if (at < 0)
+            return;
+        blocks[at].cache_control = { type: 'ephemeral' };
+    }
+}
 /**
  * Build the Anthropic `system` array: the mandatory Claude Code identity
  * block, then the explicit system prompt, then any system-role messages.
  * @param system - explicit system prompt, when set.
- * @param messages - conversation messages; their system-role text is appended.
+ * @param messages - conversation messages; the system-role text preceding the
+ * conversation is appended, and a later one is left to {@link toAnthropicMessages}.
  * @returns the system content blocks.
  */
 export function toAnthropicSystem(system, messages) {
     const blocks = [{ type: 'text', text: CLAUDE_CODE_IDENTITY }];
     if (system !== undefined && system.length > 0)
         blocks.push({ type: 'text', text: system });
-    for (const message of messages ?? []) {
-        if (message.role !== 'system')
-            continue;
+    const history = messages ?? [];
+    for (const message of history.slice(0, conversationStart(history))) {
         for (const block of message.content) {
             if (block.type === 'text')
                 blocks.push({ type: 'text', text: block.text });
         }
     }
+    // `tools` renders ahead of `system`, so this one marker caches both. It is
+    // deliberately separate from the message marks: a tool_choice or thinking
+    // change invalidates the messages tier only, and this entry survives it.
+    blocks[blocks.length - 1].cache_control = { type: 'ephemeral' };
     return blocks;
 }
 /**
- * Map harness tool schemas to Anthropic tools.
+ * Map harness tool schemas to Anthropic tools, in name order.
+ *
+ * `tools` renders at position 0 of the cached prefix, so any reordering
+ * invalidates every cache entry behind it — `system` and the whole
+ * conversation included. Registration order belongs to the caller and plugin
+ * load order can differ between processes, so the wire order is fixed here
+ * instead. Anthropic selects a tool by name; the array order carries nothing.
  * @param tools - tool schemas from the request.
- * @returns Anthropic `tools` array entries.
+ * @returns Anthropic `tools` array entries, ordered by tool name.
  */
 export function toAnthropicTools(tools) {
-    return tools.map(tool => ({
+    return [...tools]
+        .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+        .map(tool => ({
         name: tool.name,
         description: tool.description,
         input_schema: tool.parameters,

package/lib/translate/chat-completions.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Translate between the harness message vocabulary and the OpenAI chat
+ * completions wire format the Copilot provider speaks: request message/tool
+ * assembly and a push-model SSE-chunk → StreamChunk state machine
+ * ({@link ChatCompletionsStreamTranslator}) mirroring the Responses
+ * translator, so tests need no streams.
+ */
+import type { StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { TranslatableMessage } from './resolved.js';
+/**
+ * Convert harness messages into chat completions `messages`. System-role
+ * messages become one leading `system` message; an explicit `system` argument
+ * wins over them when both exist. Reasoning blocks are not replayed (matching
+ * the Responses translator). Images must arrive pre-resolved; an unresolved
+ * ImageBlock is skipped because its bytes are unreachable here. A user message
+ * carrying only text collapses to a plain string body (some endpoints still
+ * reject content-part arrays); tool results become separate `tool` messages.
+ * @param messages - ordered conversation messages with resolved images.
+ * @param system - explicit system prompt, which takes precedence.
+ * @returns the wire `messages` array.
+ */
+export declare function toChatMessages(messages: readonly TranslatableMessage[], system?: string): Record<string, unknown>[];
+/**
+ * Map harness tool schemas to chat completions function tools.
+ * @param tools - tool schemas from the request.
+ * @returns the wire `tools` array.
+ */
+export declare function toChatTools(tools: readonly ToolSchema[]): Record<string, unknown>[];
+/** The subset of chat-completion chunk shapes this translator reads. */
+export interface ChatCompletionsStreamEvent {
+    choices?: {
+        index?: number;
+        delta?: {
+            content?: string | null;
+            role?: string;
+            reasoning_content?: string | null;
+            /** Copilot's Gemini models stream thinking as `reasoning_text`. */
+            reasoning_text?: string | null;
+            tool_calls?: {
+                index?: number;
+                id?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }[];
+        };
+        finish_reason?: string | null;
+    }[];
+    usage?: ChatCompletionsUsage | null;
+}
+/** Chat completions `usage` object shape. */
+export interface ChatCompletionsUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+}
+/**
+ * Map chat completions usage to disjoint harness counts (cached input is
+ * subtracted out of `inputTokens` and reported as `cacheReadTokens`).
+ * @param usage - wire usage from the terminal chunk.
+ * @returns harness token usage.
+ */
+export declare function mapChatCompletionsUsage(usage: ChatCompletionsUsage): TokenUsage;
+/**
+ * Push-model chat completions SSE translator: feed each parsed chunk object
+ * to {@link push} and collect the emitted harness StreamChunks. The terminal
+ * `finish_reason` chunk closes every block but only ARMS the finish chunk —
+ * usage must precede the terminal finish, and where usage lives differs by
+ * upstream: OpenAI-style streams send a trailing usage-only chunk
+ * (stream_options.include_usage), while Copilot's Gemini models attach a
+ * (zero) usage object to EVERY chunk and fold the real usage into the
+ * finish chunk itself. A chunk therefore never early-returns on `usage`
+ * alone: its deltas are always processed, and the terminal pair is drained
+ * when the finish is armed and usage arrived (or when a usage-only chunk
+ * follows an armed finish). `flush()` emits whatever remains when the
+ * stream's `[DONE]` (or EOF) arrives.
+ */
+export declare class ChatCompletionsStreamTranslator {
+    /** Text/reasoning blocks keyed by kind; tool calls keyed by their wire index. */
+    private blocks;
+    private order;
+    private nextIndex;
+    private sawToolCall;
+    private pendingUsage;
+    private armedFinish;
+    /** Set once the terminal finish chunk was emitted. */
+    terminated: boolean;
+    private open;
+    private close;
+    private closeAll;
+    /** Build the terminal finish chunk for one wire finish reason. */
+    private finishChunk;
+    /** Usage, then the armed finish: the only order the harness accepts. */
+    private drainTerminal;
+    /**
+     * Process one parsed chat-completion chunk.
+     * @param event - the parsed chunk object.
+     * @returns the StreamChunks this event produced (possibly none).
+     */
+    push(event: ChatCompletionsStreamEvent): StreamChunk[];
+    /**
+     * Emit whatever the stream left pending (`[DONE]` or EOF without a final
+     * usage chunk). Safe to call repeatedly.
+     * @returns the remaining terminal chunks.
+     */
+    flush(): StreamChunk[];
+}
+/**
+ * Consume a chat completions SSE byte stream and yield harness StreamChunks.
+ * @param stream - raw response body.
+ * @param onActivity - transport-activity callback for the idle watchdog.
+ * @returns the chunk stream; throws when the stream ends before any finish chunk.
+ */
+export declare function streamChatCompletions(stream: ReadableStream<Uint8Array>, onActivity?: () => void): AsyncGenerator<StreamChunk>;