@wenathlan/devthink 2.0.12 → 2.0.14

package/dist/streaming.d.ts

@@ -0,0 +1,1119 @@
+/**
+ * @file streaming.ts
+ * @module provider/streaming
+ * @description
+ *  Third-person observer view: the library watches Antigravity / CloudCode
+ *  traffic and reproduces its streaming behavior without running Antigravity
+ *  itself.
+ *
+ *  Responsibilities isolated here:
+ *   - Incremental SSE parser tolerant to network splits (parseSSEChunk)
+ *   - Heterogeneous payload normalization (unwrap response/candidates/parts)
+ *   - LRU cache for thinking signatures — 100 entries — Map-based
+ *   - Preservation of thinking blocks between chunks (delta tracking)
+ *   - OpenAI / Anthropic transformers compatible with opencode plugin SDK
+ *   - Auto-recovery exponential backoff + jitter 0-80ms
+ *   - Synthetic finish injection when cloudcode-pa closes abruptly
+ *
+ *  Architectural constraints:
+ *   - Library-first, root-first (no src/ folder)
+ *   - Direct cloudcode-pa.googleapis.com — no localhost v1 proxy
+ *   - Only node:* builtins + global fetch (Node >=18)
+ *     -> node:crypto for FNV-1a, signature hashing, jitter
+ *     -> global TextDecoder / ReadableStream (web standards in Node)
+ *   - Production-ready: never throws in parser, defensive JSON tolerant,
+ *     JSDoc everywhere, explicit error handling, no placeholder
+ *
+ *  Date governance: 25/08/2026 — Canto do Buriti, PI, BR
+ *  Version: 2.0.0 — the merged provider lineage
+ *
+ *  Related modules:
+ *   - constants.ts — endpoints, LRU_THINKING_CACHE_SIZE, models 2026
+ *   - fingerprint.ts — FNV-1a reused here for deterministic ids
+ *   - request.ts — builds Antigravity request body
+ *   - recovery.ts — higher level auto-recovery using this module
+ *
+ * @author devthink
+ * @license MIT
+ */
+import { BACKOFF_BASE_MS, BACKOFF_FACTOR, BACKOFF_MAX_MS, GEMINI_CLI_OAUTH_CLIENT_ID as GEMINI_CLI_CLIENT_ID, GEMINI_CLI_OAUTH_CLIENT_SECRET as GEMINI_CLI_CLIENT_SECRET, JITTER_MAX_MS, JITTER_MIN_MS, LRU_THINKING_CACHE_SIZE, MAX_RETRIES, PROJECT_FALLBACK } from "./constants.js";
+import { fnv1a32, getJitter, thinkingCache } from "./core.js";
+export { BACKOFF_BASE_MS, BACKOFF_FACTOR, BACKOFF_MAX_MS, GEMINI_CLI_CLIENT_ID, GEMINI_CLI_CLIENT_SECRET, JITTER_MAX_MS, JITTER_MIN_MS, LRU_THINKING_CACHE_SIZE, MAX_RETRIES, PROJECT_FALLBACK, fnv1a32, getJitter, thinkingCache, };
+/** Retryable HTTP status codes for cloudcode-pa */
+/** Sentinel that Gemini / Antigravity sends to close stream */
+export declare const SSE_DONE_SENTINEL: "[DONE]";
+/**
+ * SHA-256 hex truncated to 16 chars — stable key for thinking text
+ * when length > few hundred chars. Falls back to FNV-1a if crypto fails.
+ *
+ * @param text - thinking text to hash
+ */
+export declare function hashThinkingText(text: string): string;
+/**
+ * Promise-based sleep with jitter included for backoff
+ * @param ms - base delay
+ */
+export declare function sleepWithJitter(ms: number): Promise<void>;
+/**
+ * @description
+ *  The observer notes that Claude thinking blocks carry `thoughtSignature`
+ *  that must be preserved across turns, otherwise API returns
+ *  "invalid signature". Original plugin stored 100 entries in Map.
+ *  LRU eviction keeps most recent.
+ *
+ *  This implementation is library-first: no external LRU dep,
+ *  uses Map insertion order (ES2015 guarantees order).
+ */
+export declare class ReplaySignatureCache {
+    private readonly maxSize;
+    private readonly map;
+    /**
+     * @param maxSize - max entries, default 100 per spec
+     */
+    constructor(maxSize?: number);
+    /** Current size */
+    get size(): number;
+    /** Max configured */
+    get capacity(): number;
+    /**
+     * Retrieves signature for given thinking text.
+     * The cache key is hash of normalized text (trimmed).
+     *
+     * @param thinkingText - full thinking block text
+     * @returns signature or undefined
+     */
+    get(thinkingText: string): string | undefined;
+    /**
+     * Retrieves signature by direct hash key (when caller already hashed)
+     */
+    getByHash(hashKey: string): string | undefined;
+    /**
+     * Stores signature keyed by thinking text
+     * @param thinkingText - full text
+     * @param signature - opaque signature string from API
+     */
+    set(thinkingText: string, signature: string): void;
+    /**
+     * Direct hash->signature set (when text not available)
+     */
+    setByHash(hashKey: string, signature: string): void;
+    /** Checks presence without touching LRU order */
+    has(thinkingText: string): boolean;
+    /** Deletes entry by thinking text */
+    delete(thinkingText: string): boolean;
+    /** Clears all */
+    clear(): void;
+    /** Iterates entries LRU order (oldest first) */
+    entries(): IterableIterator<[string, string]>;
+    /** Keys in LRU order */
+    keys(): IterableIterator<string>;
+    /** Returns diagnostic snapshot oldest->newest */
+    snapshot(): Array<{
+        hash: string;
+        signaturePreview: string;
+    }>;
+    private evictIfNeeded;
+}
+/** Global singleton used by transformers — library-first convenience */
+export declare const globalThinkingSignatureCache: ReplaySignatureCache;
+/**
+ * Raw SSE event parsed from wire.
+ * Observer keeps it minimal — only what cloudcode-pa uses.
+ */
+export interface ParsedSSEEvent {
+    /** Event type if server sent `event: xxx` */
+    event?: string | undefined;
+    /** Optional id `id: xxx` */
+    id?: string | undefined;
+    /** Retry interval `retry: xxx` */
+    retry?: number | undefined;
+    /** Joined data payload (may be JSON string, may be [DONE]) */
+    data: string;
+    /** Raw block for debugging */
+    rawBlock: string;
+}
+/**
+ * Mutable buffer holding incomplete SSE tail between network chunks.
+ * Third-person: the observer accumulates until double newline terminator.
+ */
+export interface SSEParserState {
+    /** Leftover incomplete tail */
+    buffer: string;
+    /** How many events parsed so far — useful for diagnostics */
+    eventsSeen: number;
+}
+/**
+ * Creates fresh parser state.
+ */
+export declare function createSSEParserState(): SSEParserState;
+/**
+ * Parses one text chunk incrementally, tolerant to splits.
+ *
+ * The observer learned from production: fetch streaming may split in middle
+ * of `data: {` JSON, or split the `\n\n` delimiter across chunks.
+ * Strategy:
+ *  1. Append chunk to state.buffer
+ *  2. Normalize \r\n -> \n, \r -> \n
+ *  3. While buffer contains `\n\n` extract block
+ *  4. For each block, extract data: lines (join with \n per SSE spec)
+ *  5. Leave incomplete tail in buffer
+ *
+ * @param chunk - new text arrived from decoder (may be partial)
+ * @param state - mutable buffer object — will be updated in place
+ * @returns parsed events from this chunk only
+ *
+ * @example
+ *  const state = createSSEParserState();
+ *  let ev = parseSSEChunk("data: {\"cand", state); // [] — buffered
+ *  ev = parseSSEChunk("idates\":[]}\n\n", state); // 1 event
+ */
+export declare function parseSSEChunk(chunk: string, state: SSEParserState): ParsedSSEEvent[];
+/**
+ * Parses a Uint8Array / Buffer chunk using TextDecoder streaming.
+ * Convenience wrapper around parseSSEChunk for binary fetch streams.
+ *
+ * @param binaryChunk - Uint8Array from reader.read()
+ * @param decoder - TextDecoder with {stream:true}
+ * @param state - parser state
+ */
+export declare function parseSSEBinaryChunk(binaryChunk: Uint8Array, decoder: {
+    decode(input: Uint8Array, options?: {
+        stream?: boolean;
+    }): string;
+}, state: SSEParserState): ParsedSSEEvent[];
+/**
+ * Normalized tool call extracted from Antigravity part
+ */
+export interface NormalizedToolCall {
+    /** Deterministic id if not provided by model */
+    id: string;
+    /** Function / tool name sanitized */
+    name: string;
+    /** Parsed args object if JSON parsable, otherwise raw string */
+    args: unknown;
+    /** Raw JSON string of args — for OpenAI delta streaming */
+    argsJson: string;
+    /** Whether this is delta (partial args) or final */
+    isDelta?: boolean;
+}
+/**
+ * Single normalized chunk produced from one or more raw payloads
+ */
+export interface NormalizedChunk {
+    /** Text delta to emit (incremental already deduped) */
+    text?: string | undefined;
+    /** Full accumulated text for tracking */
+    fullText?: string | undefined;
+    /** Thinking delta */
+    thinking?: string | undefined;
+    /** Full accumulated thinking */
+    fullThinking?: string | undefined;
+    /** Signature for thinking block if present */
+    thinkingSignature?: string | undefined;
+    /** Tool calls extracted */
+    toolCalls?: NormalizedToolCall[] | undefined;
+    /** Finish reason from cloudcode-pa, normalized to lowercase (stop, max_tokens, safety) */
+    finishReason?: string | undefined;
+    /** Raw original payload for debugging / grounding */
+    raw: unknown;
+    /** Candidate index if payload contained multiple candidates */
+    candidateIndex?: number | undefined;
+    /** Whether this part was marked as thought */
+    isThought?: boolean | undefined;
+    /** Grounding metadata e.g. groundingMetadata, groundingChunks */
+    groundingMetadata?: unknown | undefined;
+    /** Safety ratings if present */
+    safetyRatings?: unknown | undefined;
+    /** Usage metadata if present */
+    usageMetadata?: unknown | undefined;
+    /** Indicates stream is done (from [DONE] or finishReason) */
+    isFinished?: boolean | undefined;
+}
+/**
+ * Safe JSON parse — never throws, returns null on failure
+ * @param text - raw data string
+ */
+export declare function safeJsonParse(text: string): unknown | null;
+/**
+ * Unwraps heterogeneous envelope into candidate array.
+ * Handles observed shapes:
+ *  - {response:{candidates:[...]}}
+ *  - {candidates:[...]}
+ *  - {candidate:{...}}
+ *  - [{...}, {...}] (already array)
+ *  - {content:{parts:[...]}} single candidate
+ *  - {parts:[...]} direct parts
+ *
+ * @param payload - parsed JSON object
+ * @returns array of candidate-like objects
+ */
+export declare function unwrapCandidates(payload: unknown): unknown[];
+/**
+ * Extracts parts array from candidate
+ */
+export declare function extractParts(candidate: unknown): unknown[];
+/**
+ * Normalizes single part object into text/thinking/toolCall
+ * @param part - raw part
+ */
+export declare function normalizePart(part: unknown): {
+    text?: string;
+    thinking?: string;
+    thinkingSignature?: string;
+    toolCall?: NormalizedToolCall;
+    isThought?: boolean;
+};
+/**
+ * Maps Gemini finishReason to normalized lowercase reason
+ */
+export declare function mapFinishReason(rawReason: unknown): string | undefined;
+/**
+ * Core normalizer — converts raw SSE data strings (JSON) into normalized chunks.
+ * Tolerant to heterogeneous shapes observed in prod, daily, sandbox.
+ *
+ * @param rawDataStrings - array of data: payloads (already stripped of `data:` prefix)
+ * @returns normalized chunks (may be more than input if multiple candidates)
+ */
+export declare function normalizePayloads(rawDataStrings: (string | unknown)[]): NormalizedChunk[];
+/**
+ * Extracts delta from full text given previously sent buffer.
+ * If new text starts with old, returns suffix, else returns full new.
+ * This handles both cumulative and incremental server behavior.
+ *
+ * @param full - current accumulated text from server (may be cumulative)
+ * @param alreadySent - buffer already emitted to client
+ * @returns delta to emit now
+ */
+export declare function extractDelta(full: string, alreadySent: string): string;
+/**
+ * Tracks streaming session to preserve thinking and text between chunks.
+ * The observer watches two buffers: sentThinkingBuffer and sentTextBuffer.
+ * Prevents duplicated thinking blocks in UI (bug #120 in original repo).
+ */
+export declare class StreamingSessionTracker {
+    readonly signatureCache: ReplaySignatureCache;
+    private fullThinking;
+    private sentThinking;
+    private fullText;
+    private sentText;
+    private thinkingSignature?;
+    private finished;
+    private lastFinishReason?;
+    private toolCallsSeen;
+    /**
+     * @param signatureCache - optional LRU cache for thinking signatures
+     */
+    constructor(signatureCache?: ReplaySignatureCache);
+    /** Whether stream already finished */
+    get isFinished(): boolean;
+    get currentThinking(): string;
+    get currentText(): string;
+    /**
+     * Pushes new normalized chunk, deduplicates thinking/text, updates signature cache,
+     * and returns delta-only chunk ready for transformer.
+     *
+     * @param chunk - normalized from normalizePayloads
+     * @returns delta chunk (with only new portions) + metadata
+     */
+    push(chunk: NormalizedChunk): NormalizedChunk;
+    /**
+     * Returns synthetic finish chunk if stream ended without explicit finish.
+     * Preserves last known signature.
+     */
+    createSyntheticFinish(reason?: string): NormalizedChunk | null;
+    /** Resets tracker for new stream */
+    reset(): void;
+    /** Diagnostic snapshot */
+    snapshot(): {
+        fullThinkingLen: number;
+        sentThinkingLen: number;
+        fullTextLen: number;
+        sentTextLen: number;
+        finished: boolean;
+        toolCalls: number;
+        hasSignature: boolean;
+    };
+}
+export interface OpenAIChunkOptions {
+    /** Model id to echo back — e.g. antigravity-gemini-3-flash */
+    model: string;
+    /** Optional fixed id for stream — if not provided random-ish */
+    id?: string;
+    /** Creation timestamp in seconds */
+    created?: number;
+}
+/**
+ * Transforms normalized chunks into OpenAI SSE lines.
+ * Library-first: stateless transform + session tracker for delta.
+ *
+ * The observer emits reasoning_content for thinking (opencode supports both
+ * reasoning and reasoning_content per 2026 spec).
+ *
+ * @param chunk - delta chunk from StreamingSessionTracker
+ * @param opts - model/id/created
+ * @returns array of SSE formatted strings `data: {...}\n\n`
+ */
+export declare function transformToOpenAI(chunk: NormalizedChunk, opts: OpenAIChunkOptions, tracker?: StreamingSessionTracker): string[];
+/**
+ * Factory that returns stateful OpenAI transformer with internal tracker
+ * and LRU signature cache. Suitable for opencode plugin hook.
+ *
+ * @param opts - model options
+ * @param cache - optional cache injection
+ */
+export declare function createOpenAIStreamingTransformer(opts: OpenAIChunkOptions, cache?: ReplaySignatureCache): {
+    tracker: StreamingSessionTracker;
+    transform: (chunk: NormalizedChunk) => string[];
+    final: () => string[];
+};
+export interface AnthropicChunkOptions {
+    /** Model to echo */
+    model: string;
+    /** Message id */
+    messageId?: string;
+}
+type AnthropicBlockType = "text" | "thinking" | "tool_use";
+/**
+ * Internal state for Anthropic streaming sequence.
+ * Observer maintains index counters per content block.
+ */
+declare class AnthropicStateMachine {
+    messageStarted: boolean;
+    nextBlockIndex: number;
+    activeBlocks: Map<number, AnthropicBlockType>;
+    blockThinkingSent: Map<number, string>;
+    blockTextSent: Map<number, string>;
+    toolJsonSent: Map<string, string>;
+    finished: boolean;
+    reset(): void;
+}
+/**
+ * Transforms normalized chunk into Anthropic SSE events.
+ * Emits event: / data: pairs as per Anthropic Messages streaming spec:
+ *   message_start, content_block_start, content_block_delta, content_block_stop,
+ *   message_delta, message_stop
+ *
+ * Library-first: each call returns array of formatted SSE lines.
+ *
+ * @param chunk - delta chunk from tracker
+ * @param opts - model/message options
+ * @param state - anthropic state machine (mutable)
+ * @returns array of SSE lines (`event: xxx\ndata: {...}\n\n`)
+ */
+export declare function transformToAnthropic(chunk: NormalizedChunk, opts: AnthropicChunkOptions, state: AnthropicStateMachine): string[];
+/**
+ * Factory for Anthropic streaming transformer compatible with opencode
+ *
+ * @param opts - model options
+ * @param cache - LRU signature cache
+ */
+export declare function createAnthropicStreamingTransformer(opts: AnthropicChunkOptions, cache?: ReplaySignatureCache): {
+    tracker: StreamingSessionTracker;
+    anthropicState: AnthropicStateMachine;
+    transform: (chunk: NormalizedChunk) => string[];
+    final: () => string[];
+};
+export interface RetryOptions {
+    /** Max attempts including first */
+    maxRetries?: number;
+    /** Base delay ms */
+    baseMs?: number;
+    /** Factor */
+    factor?: number;
+    /** Max delay ms */
+    maxMs?: number;
+    /** Which status codes trigger retry */
+    retryableStatus?: number[];
+}
+/**
+ * Determines if error/status is retryable.
+ * Observer pattern: checks 429, 5xx, and network failures.
+ *
+ * @param status - HTTP status or undefined for network error
+ */
+export declare function isRetryableNetworkStatus(status: number | undefined, opts?: RetryOptions): boolean;
+/**
+ * Fetches with exponential backoff + jitter.
+ * Uses only node builtins + global fetch.
+ * Third-person observer: it watches fetch, retries on transient errors.
+ *
+ * @param input - RequestInfo
+ * @param init - RequestInit
+ * @param retryOpts - backoff options
+ * @returns Response
+ * @throws last error after retries exhausted
+ */
+export declare function fetchWithExponentialRetry(input: Parameters<typeof fetch>[0], init?: RequestInit, retryOpts?: RetryOptions): Promise<Response>;
+/**
+ * Creates synthetic finish chunk when stream closes abruptly.
+ * Observer injects `stop` finish to keep opencode SDK happy.
+ *
+ * @param tracker - session tracker to know current state
+ * @param reason - finish reason, default stop
+ * @returns normalized finish chunk or null if already finished
+ */
+export declare function injectSyntheticFinish(tracker: StreamingSessionTracker, reason?: string): NormalizedChunk | null;
+/**
+ * Wraps streaming response reading with auto-recovery.
+ * If reader throws before finish, retries whole fetch (exponential).
+ * On final failure, injects synthetic finish so UI doesn't hang.
+ *
+ * @param fetchFn - function that returns Promise<Response> (fresh fetch each attempt)
+ * @param onChunk - callback for each normalized chunk (deduped)
+ * @param retryOpts - retry options for fetch phase
+ * @param tracker - optional tracker (if not provided new one created)
+ */
+export declare function withAutoRecoveryStreaming(fetchFn: () => Promise<Response>, onChunk: (chunk: NormalizedChunk) => void | Promise<void>, retryOpts?: RetryOptions, tracker?: StreamingSessionTracker): Promise<void>;
+/**
+ * Async generator that reads a fetch Response body (cloudcode-pa alt=sse)
+ * and yields normalized chunks with preserved thinking blocks.
+ *
+ * The observer directly consumes https://cloudcode-pa.googleapis.com
+ * (or daily-.../sandbox) without localhost v1 proxy.
+ *
+ * @param response - fetch Response with body ReadableStream
+ * @param tracker - optional tracker for delta preservation (new one if not provided)
+ * @yields NormalizedChunk (deduped delta already applied via tracker)
+ */
+export declare function readSSEStream(response: Response, tracker?: StreamingSessionTracker): AsyncGenerator<NormalizedChunk>;
+/**
+ * Convenience: stream cloudcode-pa response and transform to OpenAI SSE lines.
+ * Used by opencode plugin fetch interceptor.
+ *
+ * @param response - fetch Response from cloudcode-pa
+ * @param openAIOpts - model info
+ * @param cache - optional LRU cache
+ * @returns AsyncGenerator<string> of `data: {...}\n\n` lines
+ */
+export declare function streamToOpenAI(response: Response, openAIOpts: OpenAIChunkOptions, cache?: ReplaySignatureCache): AsyncGenerator<string>;
+/**
+ * Convenience: stream cloudcode-pa response and transform to Anthropic SSE lines.
+ *
+ * @param response - fetch Response
+ * @param anthropicOpts - model info
+ * @param cache - optional LRU cache
+ * @returns AsyncGenerator<string> of `event: ...\ndata: ...\n\n`
+ */
+export declare function streamToAnthropic(response: Response, anthropicOpts: AnthropicChunkOptions, cache?: ReplaySignatureCache): AsyncGenerator<string>;
+/** Production Cloud Code Assist base endpoint. */
+/** Exact User-Agent sent by Gemini CLI 0.57.0. */
+/** X-Goog-Api-Client value observed on real Gemini CLI traffic. */
+/** Client-Metadata header string used by Gemini CLI bypass requests. */
+import { MODELS_2026_LEGACY as MODELS_2026 } from "./models.js";
+import type { ModelId2026 } from "./models.js";
+export { MODELS_2026 };
+export type { ModelId2026 };
+/**
+ * Raw part shape emitted by cloudcode-pa (Gemini core with Claude interop).
+ */
+export interface RawPart {
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+    functionCall?: {
+        name: string;
+        args?: Record<string, unknown> | string;
+        id?: string;
+    };
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+    [k: string]: unknown;
+}
+/**
+ * Raw content container — either wrapped parts or bare text.
+ */
+export interface RawContent {
+    role?: string;
+    parts?: RawPart[];
+    text?: string;
+}
+/**
+ * Raw candidate inside a cloudcode-pa chunk.
+ */
+export interface RawCandidate {
+    content?: RawContent;
+    finishReason?: string;
+    finishMessage?: string;
+    index?: number;
+    tokenCount?: number;
+    safetyRatings?: unknown[];
+    parts?: RawPart[];
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+}
+/**
+ * Heterogeneous raw chunk from v1internal:streamGenerateContent.
+ */
+export interface CloudCodeRawChunk {
+    candidates?: RawCandidate[];
+    content?: RawContent;
+    parts?: RawPart[];
+    response?: CloudCodeRawChunk;
+    usageMetadata?: {
+        promptTokenCount?: number;
+        candidatesTokenCount?: number;
+        totalTokenCount?: number;
+        thoughtsTokenCount?: number;
+    };
+    model?: string;
+    modelVersion?: string;
+    thought?: string;
+    thoughtSignature?: string;
+    [k: string]: unknown;
+}
+/** Kind discriminator for {@link NormalizedPart}. */
+export type NormalizedPartKind = "text" | "thinking" | "thought_signature" | "function_call" | "inline_data";
+/**
+ * One normalized part with provenance indexes and optional signature.
+ */
+export interface NormalizedPart {
+    kind: NormalizedPartKind;
+    text: string;
+    thought: boolean;
+    thoughtSignature?: string | undefined;
+    functionCall?: {
+        name: string;
+        args: string;
+        id: string;
+    };
+    rawIndex: number;
+    candidateIndex: number;
+    finishReason?: string | undefined;
+}
+/**
+ * Fully normalized payload: parts plus finish/usage metadata.
+ */
+export interface NormalizedPayload {
+    parts: NormalizedPart[];
+    finishReason?: string | undefined;
+    usage?: CloudCodeRawChunk["usageMetadata"] | undefined;
+    model?: string | undefined;
+    isThinkingChunk: boolean;
+    hasFinish: boolean;
+    raw: CloudCodeRawChunk;
+}
+/**
+ * Mutable state shared by the stateful OpenAI / Anthropic transformers.
+ */
+export interface StreamingState {
+    completionId: string;
+    model: string;
+    created: number;
+    sentRole: boolean;
+    accumulatedText: string;
+    accumulatedThinking: string;
+    lastFinishReason?: string | undefined;
+    insideThinking: boolean;
+    anthropicBlockIndex: number;
+    anthropicBlockKinds: Map<number, NormalizedPartKind>;
+    toolCallIdCounter: number;
+    pendingSignatures: string[];
+}
+/**
+ * OpenAI chat.completion.chunk wire type emitted by the transformer.
+ */
+export interface OpenAIChatChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: "assistant";
+            content?: string;
+            reasoning_content?: string;
+            reasoning?: string;
+            tool_calls?: Array<{
+                index: number;
+                id: string;
+                type: "function";
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }>;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        completion_tokens_details?: {
+            reasoning_tokens?: number;
+        };
+    };
+}
+/**
+ * Anthropic-style SSE event descriptor.
+ */
+export interface AnthropicSSEEvent {
+    type: string;
+    data?: unknown;
+    sse?: string;
+}
+/**
+ * Diagnostic result shape for remainder-based SSE parsing.
+ */
+export interface ParseSSEChunkResult {
+    payloads: CloudCodeRawChunk[];
+    remainder: string;
+    consumedBytes: number;
+    errors: string[];
+}
+/**
+ * Cached signature entry with turn/model provenance.
+ */
+export interface ReplaySignatureEntry {
+    signature: string;
+    thinkingText: string;
+    model: string;
+    timestamp: number;
+    turnId: string;
+    tokenCount?: number | undefined;
+}
+/**
+ * Entry-based LRU cache for thinking signatures across turns.
+ * Preserves thoughtSignature values that must be replayed on multi-turn
+ * requests for gemini-3-pro / claude thinking models.
+ *
+ * Kept alongside {@link ReplaySignatureCache}, which maps plain text hashes
+ * to signature strings.
+ */
+export declare class ThinkingSignatureLRUCache {
+    private readonly maxEntries;
+    private readonly map;
+    constructor(maxEntries?: number);
+    private touch;
+    get(key: string): ReplaySignatureEntry | undefined;
+    set(key: string, entry: ReplaySignatureEntry): void;
+    /**
+     * Short FNV-1a hex hash of thinking text, used as key when no turnId exists.
+     */
+    static hashThinking(text: string): string;
+    /**
+     * Adds an entry derived from a payload fragment and returns the cache key.
+     */
+    addFromPayload(payload: {
+        signature: string;
+        thinkingText?: string;
+        model?: string;
+        turnId?: string;
+        tokenCount?: number;
+    }): string;
+    findByModel(model: string): ReplaySignatureEntry[];
+    clear(): void;
+    get size(): number;
+    entries(): IterableIterator<[string, ReplaySignatureEntry]>;
+    toJSON(): Record<string, ReplaySignatureEntry>;
+}
+/**
+ * Global singleton of the entry-based LRU cache. Kept alongside the text-hash
+ * singleton {@link globalThinkingSignatureCache}.
+ */
+export declare const globalThinkingSignatureLRUCache: ThinkingSignatureLRUCache;
+/**
+ * Minimal SSE event shape used by the lightweight parser utilities.
+ */
+export type sseEvent = {
+    data: string;
+};
+/**
+ * Linear-time strip of SDK-injected `[cache_control...]` markers (regex-free;
+ * the former /\[cache_control.*?\]/g replace was polynomial on uncontrolled input).
+ */
+export declare const stripCacheControlMarkers: (text: string) => string;
+/**
+ * Strips SDK-injected cache_control markers from a thinking block payload.
+ *
+ * @param p - payload possibly containing `thinking`
+ * @param keepThinking - kept for API compatibility; both branches preserve thinking
+ * @returns payload with cleaned thinking text
+ */
+export declare const handleThinkingBlock: (p: any, keepThinking?: boolean) => any;
+/**
+ * Remainder-based SSE parser for cloudcode-pa streams. Pure function: feed each
+ * network chunk together with the previous remainder; it returns fully parsed
+ * payloads plus the new remainder. Tolerates UTF-8 splits, concatenated JSON,
+ * ndjson without SSE framing and `[DONE]` sentinels.
+ *
+ * Named `parseSSEPayloads` because {@link parseSSEChunk} already owns the
+ * event-block parser name in this module.
+ *
+ * @param chunk - new raw text or binary chunk
+ * @param previousRemainder - leftover text from the previous call
+ * @returns parsed payloads, new remainder, error notes and consumed length
+ *
+ * @example
+ * let remainder = "";
+ * for await (const raw of stream) {
+ *   const { payloads, remainder: next } = parseSSEPayloads(raw, remainder);
+ *   remainder = next;
+ *   for (const p of payloads) handle(p);
+ * }
+ */
+export declare function parseSSEPayloads(chunk: string | Uint8Array, previousRemainder?: string): {
+    payloads: CloudCodeRawChunk[];
+    remainder: string;
+    errors: string[];
+    consumed: number;
+};
+/**
+ * Normalizes heterogeneous raw chunks into {@link NormalizedPayload} arrays:
+ * unwraps `{response:{...}}`, builds virtual candidates for content/parts/text
+ * shapes, classifies parts into text/thinking/function_call/inline_data/
+ * thought_signature kinds and carries finish reasons and usage metadata.
+ *
+ * Named `normalizeRawPayloads` because the string-based {@link normalizePayloads}
+ * keeps its historical name in this module.
+ *
+ * @param rawChunks - typed raw chunks (output of parseSSEPayloads)
+ * @param opts - model fallback and candidate index fallback
+ * @returns normalized payloads
+ */
+export declare function normalizeRawPayloads(rawChunks: CloudCodeRawChunk[], opts?: {
+    model?: string;
+    candidateIndexFallback?: number;
+}): NormalizedPayload[];
+/**
+ * Creates the mutable state shared by the merged transformers.
+ *
+ * @param model - model id echoed back to clients
+ * @param completionId - optional fixed completion id
+ */
+export declare function createInitialStreamingState(model: string, completionId?: string): StreamingState;
+/**
+ * Transforms normalized payloads into OpenAI chat.completion.chunk objects.
+ * Emits a leading role chunk, routes thinking into reasoning_content/reasoning,
+ * caches thought signatures in the global entry-based LRU and streams tool calls.
+ *
+ * @param payloads - normalized payloads
+ * @param state - mutable streaming state updated in place
+ * @returns OpenAI chunk objects (serialize with serializeOpenAIChunksToSSE)
+ */
+export declare function transformToOpenAIChunks(payloads: NormalizedPayload[], state: StreamingState): OpenAIChatChunk[];
+/**
+ * Builds the final OpenAI finish chunk (with optional usage mapping) once the
+ * stream ends. The caller serializes it and appends the `[DONE]` marker.
+ *
+ * @param state - streaming state carrying the last observed finish reason
+ * @param reason - fallback finish reason
+ * @param usage - usage metadata captured from the stream
+ */
+export declare function createSyntheticFinishChunks(state: StreamingState, reason?: string, usage?: NormalizedPayload["usage"]): OpenAIChatChunk[];
+/**
+ * Serializes OpenAI chunks into SSE data lines ready for the wire.
+ *
+ * @param chunks - OpenAI chunk objects
+ * @returns array of `data: {...}\n\n` strings
+ */
+export declare function serializeOpenAIChunksToSSE(chunks: OpenAIChatChunk[]): string[];
+/**
+ * Transforms normalized payloads into Anthropic Messages SSE lines:
+ * message_start, content_block_start/delta/stop and message_delta/stop.
+ * Opens separate blocks when thinking interleaves with text so block ordering
+ * satisfies Claude validation.
+ *
+ * @param payloads - normalized payloads
+ * @param state - mutable streaming state updated in place
+ * @returns formatted SSE strings (`event: ...\ndata: {...}\n\n`)
+ */
+export declare function transformToAnthropicEvents(payloads: NormalizedPayload[], state: StreamingState): string[];
+/**
+ * Emits the final Anthropic events (block stop, message_delta with stop_reason,
+ * message_stop) once the stream ends.
+ *
+ * @param state - streaming state
+ * @param reason - fallback stop reason
+ * @param usage - usage metadata captured from the stream
+ * @returns formatted SSE strings
+ */
+export declare function createAnthropicSyntheticFinish(state: StreamingState, reason?: string, usage?: NormalizedPayload["usage"]): string[];
+/**
+ * Stateful incremental SSE parser wrapping parseSSEPayloads with streaming
+ * UTF-8 decoding and byte accounting.
+ */
+export declare class IncrementalSSEParser {
+    private buffer;
+    private readonly decoder;
+    private totalBytes;
+    constructor();
+    /**
+     * Pushes an incremental chunk (string, Uint8Array or Buffer), tolerating
+     * splits anywhere, and returns payloads parsed so far.
+     */
+    push(chunk: string | Uint8Array | Buffer): CloudCodeRawChunk[];
+    /**
+     * Final flush: decodes any pending bytes and attempts to parse the remainder.
+     */
+    flush(): CloudCodeRawChunk[];
+    get remainder(): string;
+    get bytesReceived(): number;
+    reset(): void;
+}
+/** Output format selector for {@link CloudCodeStreamingTransformer}. */
+export type OutputFormat = "openai" | "anthropic" | "raw";
+/**
+ * Options for the high-level streaming transformer.
+ */
+export interface StreamingTransformerOptions {
+    /** Target model id. */
+    model: string;
+    /** Wire format, openai by default. */
+    format?: OutputFormat;
+    /** Optional fixed completion id. */
+    completionId?: string;
+    /** External entry-based LRU cache (defaults to the global singleton). */
+    thinkingCache?: ThinkingSignatureLRUCache;
+    /** Inject a synthetic finish when the stream ends without one? Default true. */
+    injectSyntheticFinish?: boolean;
+    /** Append `[DONE]` after OpenAI SSE? Default true. */
+    includeDoneMarker?: boolean;
+    /** Callback invoked for every transformed SSE line. */
+    onChunk?: (sseLine: string, state: StreamingState) => void;
+}
+/**
+ * High-level cloudcode-pa SSE transformer: push raw network chunks in, receive
+ * serialized SSE lines out in the configured format, with synthetic finish
+ * injection and `[DONE]` handling on flush.
+ */
+export declare class CloudCodeStreamingTransformer {
+    private readonly parser;
+    private readonly state;
+    private readonly options;
+    private sentFinished;
+    private lastUsage?;
+    constructor(opts: StreamingTransformerOptions);
+    get streamingState(): StreamingState;
+    /**
+     * Transforms one raw chunk into output SSE lines.
+     */
+    transformChunk(rawChunk: string | Uint8Array): string[];
+    /**
+     * Flushes buffered input and injects the synthetic finish plus `[DONE]`.
+     */
+    flush(): string[];
+    private createFinish;
+    reset(model?: string): void;
+}
+/**
+ * Options for {@link resilientFetch}.
+ */
+export interface ResilientFetchOptions {
+    /** Max attempts including the first. */
+    maxRetries?: number;
+    /** Base delay in ms. */
+    baseDelayMs?: number;
+    /** Max delay in ms. */
+    maxDelayMs?: number;
+    /** Apply jitter? Default true. */
+    jitter?: boolean;
+    /** Status codes that trigger a retry. */
+    retryOn?: number[];
+    /** External abort signal. */
+    signal?: AbortSignal;
+    /** Per-attempt timeout in ms. */
+    timeoutMs?: number;
+}
+/**
+ * Computes exponential delay with optional multiplicative jitter (0.7x-1.3x).
+ *
+ * @param attempt - zero-based attempt index
+ * @param base - base delay ms
+ * @param max - maximum delay ms
+ * @param jitter - apply jitter
+ */
+export declare function computeExponentialDelay(attempt: number, base: number, max: number, jitter: boolean): number;
+/**
+ * Fetches streamGenerateContent with exponential backoff, per-attempt timeout
+ * and external-signal support, keeping Gemini CLI bypass headers intact.
+ *
+ * Equivalent sibling of {@link fetchWithExponentialRetry}; both are kept.
+ *
+ * @param url - endpoint URL
+ * @param init - RequestInit for fetch
+ * @param opts - retry options
+ * @returns Response with body stream
+ */
+export declare function resilientFetch(url: string, init: RequestInit, opts?: ResilientFetchOptions): Promise<Response>;
+/**
+ * High-level wrapper consuming streamGenerateContent with auto-recovery and
+ * yielding SSE strings in the configured format. Tolerant to mid-stream breaks
+ * (synthetic finish), missing finish reasons and UTF-8/JSON splits.
+ *
+ * @example
+ * for await (const sseLine of createResilientTransformedStream(url, init, { model, format: "openai" })) {
+ *   res.write(sseLine);
+ * }
+ */
+export declare function createResilientTransformedStream(url: string, init: RequestInit, transformerOpts: StreamingTransformerOptions, fetchOpts?: ResilientFetchOptions): AsyncGenerator<string, void, unknown>;
+/**
+ * Options for {@link buildGeminiCliBypassHeaders}.
+ */
+export interface BypassHeadersOptions {
+    model?: string;
+    accessToken?: string;
+    projectId?: string;
+    includeAuth?: boolean;
+}
+/**
+ * Builds headers fully compatible with official Gemini CLI traffic against
+ * cloudcode-pa, including the X-Goog-Request-Params project binding.
+ *
+ * @param opts - auth/project options
+ * @returns headers record ready for fetch
+ */
+export declare function buildGeminiCliBypassHeaders(opts?: BypassHeadersOptions): Record<string, string>;
+/**
+ * Deterministic session id (FNV-1a hex) derived from directory, hostname, cwd
+ * and pid. Streaming-module variant kept alongside the request-module version.
+ *
+ * @param directory - optional directory seed
+ * @returns 8-char hex digest
+ */
+export declare function buildHostSessionId(directory?: string): string;
+/**
+ * Detects whether any payload carries thinking content.
+ *
+ * @param payloads - normalized payloads
+ */
+export declare function hasThinkingContent(payloads: NormalizedPayload[]): boolean;
+/**
+ * Collects all distinct thinking signatures for multi-turn replay.
+ *
+ * @param payloads - normalized payloads
+ * @returns unique signature strings
+ */
+export declare function extractThinkingSignatures(payloads: NormalizedPayload[]): string[];
+/**
+ * Exposes accumulated state metrics for observability in the opencode UI.
+ *
+ * @param state - streaming state
+ */
+export declare function getStreamingSummary(state: StreamingState): {
+    completionId: string;
+    model: string;
+    textChars: number;
+    thinkingChars: number;
+    finishReason?: string | undefined;
+    toolCalls: number;
+    pendingSignatures: number;
+};
+/**
+ * Passes through the raw candidate payload when present, otherwise rebuilds a
+ * minimal Gemini-shaped response from the normalized view.
+ *
+ * @param p - normalized payload-like object
+ * @returns raw payload or reconstructed Gemini candidates envelope
+ */
+export declare const transformToGemini: (p: any) => any;
+/**
+ * Named bundle mirroring the legacy ONDA 4 module surface. Renamed members are
+ * wired to their merged equivalents: `parseSSEPayloads`, `normalizeRawPayloads`
+ * and the module-level `isRetryableNetworkStatus`.
+ */
+export declare const Streaming: {
+    readonly IncrementalSSEParser: typeof IncrementalSSEParser;
+    readonly CloudCodeStreamingTransformer: typeof CloudCodeStreamingTransformer;
+    readonly ThinkingSignatureLRUCache: typeof ThinkingSignatureLRUCache;
+    readonly globalThinkingSignatureCache: ReplaySignatureCache;
+    readonly globalThinkingSignatureLRUCache: ThinkingSignatureLRUCache;
+    readonly parseSSEPayloads: typeof parseSSEPayloads;
+    readonly normalizeRawPayloads: typeof normalizeRawPayloads;
+    readonly transformToOpenAIChunks: typeof transformToOpenAIChunks;
+    readonly transformToAnthropicEvents: typeof transformToAnthropicEvents;
+    readonly serializeOpenAIChunksToSSE: typeof serializeOpenAIChunksToSSE;
+    readonly createSyntheticFinishChunks: typeof createSyntheticFinishChunks;
+    readonly createAnthropicSyntheticFinish: typeof createAnthropicSyntheticFinish;
+    readonly createInitialStreamingState: typeof createInitialStreamingState;
+    readonly resilientFetch: typeof resilientFetch;
+    readonly createResilientTransformedStream: typeof createResilientTransformedStream;
+    readonly computeExponentialDelay: typeof computeExponentialDelay;
+    readonly isRetryableNetworkStatus: typeof isRetryableNetworkStatus;
+    readonly buildGeminiCliBypassHeaders: typeof buildGeminiCliBypassHeaders;
+    readonly buildHostSessionId: typeof buildHostSessionId;
+    readonly hasThinkingContent: typeof hasThinkingContent;
+    readonly extractThinkingSignatures: typeof extractThinkingSignatures;
+    readonly getStreamingSummary: typeof getStreamingSummary;
+    readonly transformToGemini: typeof transformToGemini;
+    readonly handleThinkingBlock: typeof handleThinkingBlock;
+    readonly GEMINI_CLI_CLIENT_ID: string;
+    readonly GEMINI_CLI_CLIENT_SECRET: string;
+    readonly GEMINI_CLI_USER_AGENT: "GeminiCLI/0.57.0/gemini-3-pro-preview (linux; x64; GitHub) google-api-nodejs-client/9.15.1";
+    readonly X_GOOG_API_CLIENT: "gl-node/22.19.0";
+    readonly CLIENT_METADATA_RAW: "ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI";
+    readonly PROJECT_FALLBACK: "rising-fact-p41fc";
+    readonly MODELS_2026: readonly ["antigravity-gemini-3-pro", "antigravity-gemini-3.1-pro", "antigravity-gemini-3-flash", "antigravity-claude-sonnet-4-6", "antigravity-claude-opus-4-6-thinking", "gemini-2.5-flash", "gemini-2.5-pro", "gemini-3-flash-preview", "gemini-3-pro-preview", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview-customtools"];
+};
+/**
+ * Default export for barrel compatibility: contains all primary helpers
+ */
+declare const streamingModule: {
+    LRU_THINKING_CACHE_SIZE: 100;
+    ReplaySignatureCache: typeof ReplaySignatureCache;
+    globalThinkingSignatureCache: ReplaySignatureCache;
+    createSSEParserState: typeof createSSEParserState;
+    parseSSEChunk: typeof parseSSEChunk;
+    parseSSEBinaryChunk: typeof parseSSEBinaryChunk;
+    safeJsonParse: typeof safeJsonParse;
+    unwrapCandidates: typeof unwrapCandidates;
+    extractParts: typeof extractParts;
+    normalizePart: typeof normalizePart;
+    normalizePayloads: typeof normalizePayloads;
+    mapFinishReason: typeof mapFinishReason;
+    extractDelta: typeof extractDelta;
+    StreamingSessionTracker: typeof StreamingSessionTracker;
+    transformToOpenAI: typeof transformToOpenAI;
+    createOpenAIStreamingTransformer: typeof createOpenAIStreamingTransformer;
+    transformToAnthropic: typeof transformToAnthropic;
+    createAnthropicStreamingTransformer: typeof createAnthropicStreamingTransformer;
+    fetchWithExponentialRetry: typeof fetchWithExponentialRetry;
+    injectSyntheticFinish: typeof injectSyntheticFinish;
+    withAutoRecoveryStreaming: typeof withAutoRecoveryStreaming;
+    readSSEStream: typeof readSSEStream;
+    streamToOpenAI: typeof streamToOpenAI;
+    streamToAnthropic: typeof streamToAnthropic;
+    fnv1a32: typeof fnv1a32;
+    hashThinkingText: typeof hashThinkingText;
+    getJitter: typeof getJitter;
+    sleepWithJitter: typeof sleepWithJitter;
+    SSE_DONE_SENTINEL: "[DONE]";
+};
+export default streamingModule;
+export type ChatEvent = {
+    type: "start";
+    provider: string;
+    model: string;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "reasoning";
+    text: string;
+} | {
+    type: "tool";
+    name: string;
+    input: unknown;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "finish";
+    reason?: string;
+};
+export type StreamOptions = {
+    provider: string;
+    model: string;
+    signal?: AbortSignal | undefined;
+};
+export declare function normalizeFrame(provider: string, frame: Record<string, unknown>): ChatEvent[];
+export declare function parseEventStream(response: Response, options: StreamOptions): AsyncGenerator<ChatEvent>;
+export declare function collectEvents(events: AsyncIterable<ChatEvent>): Promise<{
+    text: string;
+    reasoning: string;
+}>;
+//# sourceMappingURL=streaming.d.ts.map