dsh-subscriptions 0.1.0

package/lib/translate/antigravity-thinking.js

@@ -0,0 +1,44 @@
+/** Cloud Code Assist thinking budgets, matched to the runtime model family. */
+import { LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+/** Efforts supported by the known Antigravity runtime families. Unknown models keep upstream defaults. */
+export function antigravityReasoning(model) {
+    const ids = model.startsWith('claude-') ? ['high']
+        : model.startsWith('gpt-oss-') ? ['medium']
+            : model.startsWith('gemini-3.1-pro') || model === 'gemini-pro-agent' ? ['low', 'high']
+                : /^gemini-(?:2\.5|3)/.test(model) ? ['low', 'medium', 'high'] : [];
+    const fixedEffort = /^gemini-.*-(low|medium|high)$/.exec(model)?.[1];
+    const efforts = fixedEffort !== undefined && ids.includes(fixedEffort) ? [fixedEffort] : ids;
+    return efforts.length === 0 ? undefined : {
+        efforts: efforts.map(id => ({ id: ReasoningEffortId(id), name: id[0].toUpperCase() + id.slice(1) })),
+    };
+}
+/** Build the v1internal thinking config; do not forward arbitrary DSH effort strings. */
+export function antigravityThinking(model, effort, maxTokens) {
+    if (effort === undefined)
+        return undefined;
+    const supported = antigravityReasoning(model);
+    if (supported === undefined || effort !== 'off' && !supported.efforts.some(entry => entry.id === effort)) {
+        throw new LlmError(`Antigravity model ${model} does not support reasoning effort ${effort}`, 'UNSUPPORTED_REASONING_EFFORT');
+    }
+    if (effort === 'off')
+        return { includeThoughts: false, thinkingBudget: 0 };
+    // Reference: pi-antigravity src/models/models.ts at 697858c (v1internal wire).
+    let budget;
+    if (model.startsWith('claude-'))
+        budget = 1024;
+    else if (model.startsWith('gpt-oss-'))
+        budget = 8192;
+    else if (model.startsWith('gemini-3.1-pro') || model === 'gemini-pro-agent') {
+        budget = effort === 'high' ? 10001 : 1001;
+    }
+    else if (model.startsWith('gemini-3.5-flash') || model === 'gemini-3-flash-agent') {
+        budget = effort === 'high' ? 10000 : effort === 'medium' ? 4000 : 1000;
+    }
+    else {
+        budget = effort === 'high' ? -1 : effort === 'medium' ? 4000 : 1000;
+    }
+    if (maxTokens !== undefined && budget > 0 && maxTokens <= budget) {
+        throw new LlmError(`Antigravity maxTokens must exceed the thinking budget (${budget}) for ${model}/${effort}`, 'INVALID_REQUEST');
+    }
+    return { includeThoughts: true, thinkingBudget: budget };
+}

package/lib/translate/antigravity.d.ts

@@ -0,0 +1,114 @@
+/**
+ * DeepSeek Harness message/tool vocabulary to Antigravity's Gemini-shaped
+ * v1internal request envelope, plus response/SSE translation back to the
+ * harness streaming contract.
+ */
+import type { GenerateOptions, StreamChunk, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { TranslatableMessage } from './resolved.js';
+/** Minimal Gemini part shape used by v1internal. */
+export interface AntigravityPart {
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+    functionCall?: {
+        id?: string;
+        name?: string;
+        args?: unknown;
+    };
+    functionResponse?: {
+        id: string;
+        name: string;
+        response: Record<string, unknown>;
+    };
+}
+/** Full Antigravity request envelope. */
+export interface AntigravityRequest {
+    project: string;
+    requestId: string;
+    model: string;
+    userAgent: 'antigravity';
+    requestType: 'agent';
+    request: {
+        contents: {
+            role: 'user' | 'model';
+            parts: AntigravityPart[];
+        }[];
+        sessionId: string;
+        systemInstruction?: {
+            parts: {
+                text: string;
+            }[];
+        };
+        tools?: {
+            functionDeclarations: Record<string, unknown>[];
+        }[];
+        toolConfig?: {
+            functionCallingConfig: {
+                mode: 'VALIDATED';
+            };
+        };
+        generationConfig?: Record<string, unknown>;
+    };
+}
+/** Map harness tool schemas to Gemini function declarations. */
+export declare function toAntigravityTools(tools: readonly ToolSchema[], model?: string): {
+    functionDeclarations: Record<string, unknown>[];
+}[];
+/**
+ * Convert resolved harness messages into Gemini contents. Function response
+ * names are recovered from prior tool calls because DSH correlates results by
+ * id while the Gemini wire requires both id and name.
+ */
+export declare function toAntigravityContents(messages: readonly TranslatableMessage[], model?: string): {
+    role: 'user' | 'model';
+    parts: AntigravityPart[];
+}[];
+/**
+ * Build one v1internal generateContent/streamGenerateContent request.
+ * When forStreaming is true and the model is Claude, caps maxOutputTokens at 64000
+ * to avoid INVALID_ARGUMENT errors.
+ */
+export declare function toAntigravityRequest(options: GenerateOptions, messages: readonly TranslatableMessage[], projectId: string, forStreaming?: boolean): AntigravityRequest;
+/** Antigravity SSE/non-stream response subset. */
+export interface AntigravityResponseEvent {
+    response?: {
+        candidates?: {
+            content?: {
+                parts?: AntigravityPart[];
+            };
+            finishReason?: string;
+        }[];
+        usageMetadata?: {
+            promptTokenCount?: number;
+            candidatesTokenCount?: number;
+            thoughtsTokenCount?: number;
+            totalTokenCount?: number;
+            cachedContentTokenCount?: number;
+        };
+    };
+}
+/** Map Gemini usage metadata to the harness's disjoint counters. */
+export declare function mapAntigravityUsage(metadata: NonNullable<NonNullable<AntigravityResponseEvent['response']>['usageMetadata']>): TokenUsage;
+/** Push translator for both parsed SSE events and one non-stream response. */
+export declare class AntigravityStreamTranslator {
+    private blocks;
+    private closed;
+    private nextIndex;
+    private sawContent;
+    private sawToolCall;
+    terminated: boolean;
+    private open;
+    private close;
+    private closeAll;
+    private finish;
+    /** Process one decoded Antigravity response frame. */
+    push(event: AntigravityResponseEvent): StreamChunk[];
+}
+/** Consume Antigravity's SSE response into the DSH streaming contract. */
+export declare function streamAntigravity(stream: ReadableStream<Uint8Array>, onActivity?: () => void): AsyncGenerator<StreamChunk>;
+/** Translate a non-stream generateContent response using the same state machine. */
+export declare function parseAntigravityResponse(event: AntigravityResponseEvent): StreamChunk[];

package/lib/translate/antigravity.js

@@ -0,0 +1,366 @@
+/**
+ * DeepSeek Harness message/tool vocabulary to Antigravity's Gemini-shaped
+ * v1internal request envelope, plus response/SSE translation back to the
+ * harness streaming contract.
+ */
+import { randomUUID } from 'node:crypto';
+import { ToolCallId } from '../compat.js';
+import { EMPTY_RESPONSE_CODE, LlmError } from '@deepseek-ai/dsh-llm';
+import { withToolResultImages } from './resolved.js';
+import { parseSse } from './sse.js';
+import { antigravityThinking } from './antigravity-thinking.js';
+import { antigravityToolParameters } from './antigravity-schema.js';
+/**
+ * Normalize a harness tool result to the JSON object Antigravity's
+ * `FunctionResponse.response` field requires. That field maps to a singular
+ * protobuf `Struct`, so a bare array, string, number or boolean is rejected
+ * by the endpoint with "Proto field is not repeating, cannot start list".
+ * Only a non-array JSON object survives verbatim; every other JSON value is
+ * wrapped in the same "output" envelope the non-JSON path already uses --
+ * the shape other Cloud Code Assist clients send for every tool result.
+ */
+function toolResultValue(block) {
+    const text = block.content.map(part => part.type === 'text' ? part.text : '').join('');
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { output: text, ...block.isError === true ? { isError: true } : {} };
+    }
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+        return parsed;
+    return { output: parsed };
+}
+/** Safely read per-block replay metadata emitted by this adapter. */
+function replayBlocks(message, model) {
+    const source = message.source;
+    if (model !== undefined && (message.source?.kind !== 'model'
+        || message.source.provider !== 'antigravity' || message.source.model !== model))
+        return [];
+    if (source?.kind !== 'model' || typeof source.replayState !== 'object' || source.replayState === null)
+        return [];
+    const envelope = source.replayState;
+    const response = envelope.response;
+    if (response === null || response?.kind !== 'antigravity' || response.version !== 1 || !Array.isArray(envelope.blocks))
+        return [];
+    return envelope.blocks.map((entry) => {
+        if (typeof entry !== 'object' || entry === null)
+            return {};
+        const signature = entry.thoughtSignature;
+        return typeof signature === 'string' && signature.length > 0 ? { thoughtSignature: signature } : {};
+    });
+}
+/** Map harness tool schemas to Gemini function declarations. */
+export function toAntigravityTools(tools, model = 'gemini') {
+    if (tools.length === 0)
+        return [];
+    const legacy = /^(claude-|gpt-oss-)/.test(model);
+    return [{
+            functionDeclarations: tools.map(tool => ({
+                name: tool.name,
+                description: tool.description,
+                [legacy ? 'parameters' : 'parametersJsonSchema']: antigravityToolParameters(tool.parameters, legacy),
+            })),
+        }];
+}
+const SKIP_THOUGHT_SIGNATURE_VALIDATOR = 'skip_thought_signature_validator';
+/** Gemini 3 validates the first function call in every model tool-call step. */
+function requiresThoughtSignatures(model) {
+    return model !== undefined && /^gemini-3(?:[.-]|$)/i.test(model);
+}
+/**
+ * Convert resolved harness messages into Gemini contents. Function response
+ * names are recovered from prior tool calls because DSH correlates results by
+ * id while the Gemini wire requires both id and name.
+ */
+export function toAntigravityContents(messages, model) {
+    const out = [];
+    const callNames = new Map();
+    for (const message of withToolResultImages(messages)) {
+        if (message.role === 'system')
+            continue;
+        if (message.role === 'tool') {
+            const id = message.toolCallId ?? message.tool_call_id
+                ?? (message.source?.kind === 'tool' ? String(message.source.callId) : undefined);
+            if (id === undefined)
+                throw new LlmError('tool result has no call id', 'INVALID_REQUEST');
+            const part = { functionResponse: {
+                    id,
+                    name: callNames.get(id) ?? '',
+                    response: toolResultValue({ type: 'tool-result', toolCallId: ToolCallId(id), content: message.content }),
+                } };
+            const previous = out.at(-1);
+            if (previous?.role === 'user')
+                previous.parts.push(part);
+            else
+                out.push({ role: 'user', parts: [part] });
+            continue;
+        }
+        const role = message.role === 'assistant' ? 'model' : 'user';
+        const metadata = replayBlocks(message, model);
+        const parts = [];
+        let sawFunctionCall = false;
+        for (let index = 0; index < message.content.length; index++) {
+            const block = message.content[index];
+            switch (block.type) {
+                case 'text':
+                    // Antigravity's Claude-backed models reject empty text parts.
+                    parts.push({
+                        text: block.text.trim().length > 0 ? block.text : '.',
+                        ...metadata[index]?.thoughtSignature === undefined ? {} : { thoughtSignature: metadata[index].thoughtSignature },
+                    });
+                    break;
+                case 'reasoning': {
+                    const thoughtSignature = metadata[index]?.thoughtSignature;
+                    if (thoughtSignature !== undefined)
+                        parts.push({ thought: true, text: block.text, thoughtSignature });
+                    break;
+                }
+                case 'image':
+                    if ('dataBase64' in block) {
+                        parts.push({ inlineData: { mimeType: block.mediaType, data: block.dataBase64 } });
+                    }
+                    break;
+                case 'tool-call': {
+                    callNames.set(String(block.id), block.name);
+                    let args;
+                    try {
+                        args = JSON.parse(block.arguments);
+                    }
+                    catch {
+                        args = {};
+                    }
+                    const replaySignature = metadata[index]?.thoughtSignature;
+                    const thoughtSignature = replaySignature ?? (!sawFunctionCall && requiresThoughtSignatures(model)
+                        ? SKIP_THOUGHT_SIGNATURE_VALIDATOR
+                        : undefined);
+                    parts.push({
+                        functionCall: { id: String(block.id), name: block.name, args },
+                        ...thoughtSignature === undefined ? {} : { thoughtSignature },
+                    });
+                    sawFunctionCall = true;
+                    break;
+                }
+                case 'tool-result': {
+                    const id = String(block.toolCallId);
+                    parts.push({
+                        functionResponse: {
+                            id,
+                            name: callNames.get(id) ?? '',
+                            response: toolResultValue(block),
+                        },
+                    });
+                    break;
+                }
+                default:
+                    // Reasoning is not replayed without its provider signature. The
+                    // signature-bearing metadata remains attached to tool-call blocks.
+                    break;
+            }
+        }
+        if (parts.length === 0)
+            continue;
+        const previous = out.at(-1);
+        if (previous?.role === role)
+            previous.parts.push(...parts);
+        else
+            out.push({ role, parts });
+    }
+    return out;
+}
+/**
+ * Build one v1internal generateContent/streamGenerateContent request.
+ * When forStreaming is true and the model is Claude, caps maxOutputTokens at 64000
+ * to avoid INVALID_ARGUMENT errors.
+ */
+export function toAntigravityRequest(options, messages, projectId, forStreaming = false) {
+    const tools = toAntigravityTools(options.tools ?? [], options.model);
+    const thinkingConfig = antigravityThinking(options.model, options.reasoningEffort, options.maxTokens);
+    let maxOutputTokens = options.maxTokens;
+    // Claude models on the streaming path reject maxOutputTokens >= 65535
+    if (forStreaming && maxOutputTokens !== undefined && /^claude-/.test(options.model) && maxOutputTokens >= 65535) {
+        maxOutputTokens = 64000;
+    }
+    const generationConfig = {
+        ...maxOutputTokens === undefined ? {} : { maxOutputTokens },
+        ...options.temperature === undefined ? {} : { temperature: options.temperature },
+        ...options.stop === undefined || options.stop.length === 0 ? {} : { stopSequences: options.stop },
+        ...thinkingConfig === undefined ? {} : { thinkingConfig },
+    };
+    const systemTexts = messages.flatMap(message => message.role === 'system'
+        ? message.content.filter((block) => block.type === 'text').map(block => block.text)
+        : []);
+    const system = options.system ?? (systemTexts.length > 0 ? systemTexts.join('\n\n') : undefined);
+    const sessionId = options.sessionId === undefined ? randomUUID() : String(options.sessionId);
+    return {
+        project: projectId,
+        requestId: `agent/${String(Date.now())}/${randomUUID()}/4`,
+        model: options.model,
+        userAgent: 'antigravity',
+        requestType: 'agent',
+        request: {
+            contents: toAntigravityContents(messages, options.model),
+            sessionId,
+            ...system === undefined || system.length === 0 ? {} : { systemInstruction: { parts: [{ text: system }] } },
+            ...tools.length === 0 ? {} : {
+                tools,
+                toolConfig: { functionCallingConfig: { mode: 'VALIDATED' } },
+            },
+            ...Object.keys(generationConfig).length === 0 ? {} : { generationConfig },
+        },
+    };
+}
+/** Map Gemini usage metadata to the harness's disjoint counters. */
+export function mapAntigravityUsage(metadata) {
+    const cached = metadata.cachedContentTokenCount ?? 0;
+    return {
+        inputTokens: Math.max(0, (metadata.promptTokenCount ?? 0) - cached),
+        outputTokens: metadata.candidatesTokenCount ?? 0,
+        ...cached > 0 ? { cacheReadTokens: cached } : {},
+        ...metadata.thoughtsTokenCount === undefined ? {} : { reasoningTokens: metadata.thoughtsTokenCount },
+    };
+}
+/** Push translator for both parsed SSE events and one non-stream response. */
+export class AntigravityStreamTranslator {
+    blocks = new Map();
+    closed = [];
+    nextIndex = 0;
+    sawContent = false;
+    sawToolCall = false;
+    terminated = false;
+    open(key, kind, chunks, values = {}) {
+        const block = { index: this.nextIndex++, kind, text: '', ...values };
+        this.blocks.set(key, block);
+        chunks.push({ type: 'block-start', index: block.index, blockType: kind });
+        return block;
+    }
+    close(key, chunks) {
+        const block = this.blocks.get(key);
+        if (block === undefined)
+            return;
+        this.blocks.delete(key);
+        let content;
+        if (block.kind === 'text')
+            content = { type: 'text', text: block.text };
+        else if (block.kind === 'reasoning')
+            content = { type: 'reasoning', text: block.text };
+        else
+            content = {
+                type: 'tool-call',
+                id: ToolCallId(block.id ?? `call_${randomUUID().replaceAll('-', '')}`),
+                name: block.name ?? '',
+                arguments: block.text,
+            };
+        this.closed[block.index] = block.thoughtSignature === undefined ? {} : { thoughtSignature: block.thoughtSignature };
+        chunks.push({ type: 'block-end', index: block.index, block: content });
+    }
+    closeAll(chunks) {
+        for (const key of [...this.blocks.keys()])
+            this.close(key, chunks);
+    }
+    finish(reason) {
+        const replayState = {
+            response: { kind: 'antigravity', version: 1 },
+            blocks: this.closed,
+        };
+        if (!this.sawContent) {
+            return {
+                type: 'finish',
+                reason: { kind: 'error', failure: { message: 'Antigravity returned no content', code: EMPTY_RESPONSE_CODE } },
+            };
+        }
+        if (reason === 'MAX_TOKENS')
+            return { type: 'finish', reason: { kind: 'max-tokens' }, replayState };
+        if (reason === 'SAFETY' || reason === 'RECITATION' || reason === 'BLOCKLIST') {
+            return {
+                type: 'finish',
+                reason: { kind: 'error', failure: { message: `Antigravity blocked the response (${reason})`, code: 'CONTENT_FILTER' } },
+            };
+        }
+        return { type: 'finish', reason: { kind: this.sawToolCall ? 'tool-calls' : 'stop' }, replayState };
+    }
+    /** Process one decoded Antigravity response frame. */
+    push(event) {
+        if (this.terminated)
+            return [];
+        const chunks = [];
+        const candidate = event.response?.candidates?.[0];
+        for (const [partIndex, part] of (candidate?.content?.parts ?? []).entries()) {
+            if (part.thought === true && typeof part.text === 'string' && part.text.length > 0) {
+                const block = this.blocks.get('reasoning') ?? this.open('reasoning', 'reasoning', chunks);
+                block.text += part.text;
+                if (part.thoughtSignature !== undefined)
+                    block.thoughtSignature = part.thoughtSignature;
+                this.sawContent = true;
+                chunks.push({ type: 'reasoning-delta', index: block.index, text: part.text });
+            }
+            else if (typeof part.text === 'string' && part.text.length > 0) {
+                const block = this.blocks.get('text') ?? this.open('text', 'text', chunks);
+                block.text += part.text;
+                if (part.thoughtSignature !== undefined)
+                    block.thoughtSignature = part.thoughtSignature;
+                this.sawContent = true;
+                chunks.push({ type: 'text-delta', index: block.index, text: part.text });
+            }
+            else if (part.functionCall !== undefined) {
+                const call = part.functionCall;
+                const id = typeof call.id === 'string' && call.id.length > 0
+                    ? call.id
+                    : `call_${randomUUID().replaceAll('-', '')}`;
+                const key = `call:${id}:${String(partIndex)}`;
+                const args = JSON.stringify(call.args ?? {});
+                const block = this.open(key, 'tool-call', chunks, {
+                    id,
+                    name: call.name ?? '',
+                    ...part.thoughtSignature === undefined ? {} : { thoughtSignature: part.thoughtSignature },
+                });
+                block.text = args;
+                this.sawContent = true;
+                this.sawToolCall = true;
+                chunks.push({
+                    type: 'tool-call-delta',
+                    index: block.index,
+                    id: ToolCallId(id),
+                    name: call.name ?? '',
+                    argumentsDelta: args,
+                });
+                this.close(key, chunks);
+            }
+        }
+        if (candidate?.finishReason !== undefined) {
+            this.closeAll(chunks);
+            const usage = event.response?.usageMetadata;
+            if (usage !== undefined)
+                chunks.push({ type: 'usage', usage: mapAntigravityUsage(usage) });
+            chunks.push(this.finish(candidate.finishReason));
+            this.terminated = true;
+        }
+        return chunks;
+    }
+}
+/** Consume Antigravity's SSE response into the DSH streaming contract. */
+export async function* streamAntigravity(stream, onActivity) {
+    const translator = new AntigravityStreamTranslator();
+    for await (const event of parseSse(stream, onActivity)) {
+        if (event.data === '[DONE]')
+            break;
+        let parsed;
+        try {
+            parsed = JSON.parse(event.data);
+        }
+        catch {
+            throw new LlmError(`malformed Antigravity SSE payload: ${event.data.slice(0, 120)}`, 'MALFORMED_RESPONSE');
+        }
+        yield* translator.push(parsed);
+        if (translator.terminated)
+            return;
+    }
+    if (!translator.terminated) {
+        throw new LlmError('Antigravity SSE stream ended before a finish chunk', 'STREAM_CLOSED');
+    }
+}
+/** Translate a non-stream generateContent response using the same state machine. */
+export function parseAntigravityResponse(event) {
+    return new AntigravityStreamTranslator().push(event);
+}

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>;