@msm-core/mini 0.5.2 → 0.9.0

package/dist/brain/streaming.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Streaming — the four providers' wire formats reduced to pure functions (ب١).
+ *
+ * **Why this file exists at all.** A streamed answer and a non-streamed answer
+ * are the same answer delivered twice over. The only way to be sure of that is
+ * to be able to *prove* it, and you cannot prove anything about code that only
+ * runs with a socket open and a key in the environment. So every provider's
+ * stream is split in two here:
+ *
+ *   - `…Delta(event)` — what text just arrived. Pure.
+ *   - `accumulate…(events)` — the events folded back into the SAME object shape
+ *     the provider's NON-streaming call returns. Pure.
+ *
+ * Feed `accumulate…` a fixed array of chunks in a test and you get an object
+ * that the brain's own post-call code — not a copy of it, the same lines —
+ * turns into a payload. That is what makes "the stream aggregates to what the
+ * non-stream returns" a checkable claim rather than a hope, and it is why the
+ * brains route BOTH paths into one `response` variable and one payload builder.
+ *
+ * **The read set is the contract.** Each `…Response` interface below is exactly
+ * the fields its brain reads off a provider response — no more. It is small on
+ * purpose: `id`, `created`, `finish_reason`, block ids and the rest are things
+ * a stream cannot reconstruct and no brain here consumes, so promising them
+ * would be a lie the compiler would happily keep.
+ *
+ * **Display, not truth (the governing limit of ب١).** Nothing in this file
+ * writes a log event, touches a fingerprint, or decides anything. Chunks are
+ * emitted for a human to look at; the payload the brain returns is the record.
+ *
+ * **Text only in v1.** Tool-call fragments are accumulated but never emitted —
+ * a half-arrived tool call is not something a consumer can do anything with,
+ * and `BrainChunk` says `{ text }` precisely so that stays true.
+ */
+import type { BrainChunk } from "../core/types.js";
+/** Where chunks go. Exactly `BrainRunInput.onChunk`, named for readability. */
+export type ChunkSink = (chunk: BrainChunk) => void;
+/**
+ * Read a provider stream to the end, emitting text as it arrives, and return
+ * every raw event for the accumulator.
+ *
+ * **Abort stops the consumption, and no chunk follows it.** The check sits
+ * before the emit, not after, so an abort that lands between two events ends
+ * the stream silently — the loop's `runWithTimeout` has already rejected by
+ * then and whatever is returned here is discarded. What must never happen is a
+ * chunk arriving at a consumer that has been told the call is over.
+ *
+ * Buffering every event is deliberate: one model response is small, and the
+ * accumulator that has to see all of them is the same function the tests feed
+ * by hand. A fold that ran only live would be a second implementation.
+ */
+export declare function consumeStream<T>(source: AsyncIterable<T>, deltaOf: (event: T) => string, sink: ChunkSink, signal?: AbortSignal): Promise<T[]>;
+/** One `chat.completions` stream chunk, reduced to what we consume. */
+export interface OpenAIStreamChunk {
+    choices?: Array<{
+        delta?: {
+            content?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    } | null;
+}
+/**
+ * What the OpenAI brain reads off a completion — streamed or not.
+ *
+ * `tool_calls` is `unknown[]` on purpose. OpenAI's own union now holds a CUSTOM
+ * tool call that carries no `function` at all, so no structural type both
+ * accepts the real `ChatCompletion` and promises a `function` field. The brain
+ * has narrowed each entry with its own cast since long before streaming
+ * existed — this simply stops pretending otherwise, and the non-streaming path
+ * needs no cast to satisfy it.
+ */
+export interface OpenAICompletion {
+    choices: Array<{
+        message: {
+            content?: string | null;
+            tool_calls?: unknown[];
+        };
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    } | null;
+}
+/**
+ * The text this chunk carries, or "" for a tool-call or usage-only chunk.
+ *
+ * **Why no fold here.** Two multiplicities are worth ruling out by name, since
+ * an extractor that silently reads "the first of several" is the exact bug this
+ * file was written to make impossible:
+ *
+ *   - WITHIN a choice, `delta.content` is one string, never a list. Nothing to
+ *     concatenate.
+ *   - ACROSS choices, `choices` IS an array — but only when a request sets
+ *     `n > 1`, which this brain never does. And if one ever did, several
+ *     choices are ALTERNATIVE answers, not pieces of one: summing them would
+ *     splice two different replies together. So `[0]` is right, and the rule
+ *     that actually matters is that `accumulateOpenAI` reads `[0]` too — what
+ *     the user watched is what the payload ends up holding, always.
+ */
+export declare function openAIDelta(chunk: OpenAIStreamChunk): string;
+/**
+ * Fold OpenAI chunks into the completion they describe.
+ *
+ * Tool calls arrive as fragments keyed by `index`: the name once, the arguments
+ * in pieces to be concatenated into the JSON string the non-streamed API hands
+ * over whole. Keyed by index and re-sorted rather than pushed in arrival order,
+ * because the model interleaves parallel calls and the ORDER of calls is the
+ * one thing س٤ made load-bearing.
+ *
+ * `content` stays `null` when no text delta ever arrived — that is what the
+ * non-streaming API returns for a pure tool-call response, and the two spellings
+ * must not differ.
+ */
+export declare function accumulateOpenAI(chunks: readonly OpenAIStreamChunk[]): OpenAICompletion;
+/**
+ * One Messages-API stream event, reduced to what we consume.
+ *
+ * `delta` is `unknown` for the same reason OpenAI's `tool_calls` is: the event
+ * union puts two unrelated shapes through one field name — a `message_delta`
+ * carries stop reason and stop sequence, a `content_block_delta` carries text
+ * or JSON fragments — and they share no property. Narrowing happens at the one
+ * place it is read (`blockDelta` below), which keeps the cast next to the check
+ * that justifies it and lets `RawMessageStreamEvent` flow in untouched.
+ */
+export interface AnthropicStreamEvent {
+    type: string;
+    index?: number;
+    message?: {
+        usage?: {
+            input_tokens?: number;
+            output_tokens?: number;
+        };
+    };
+    content_block?: {
+        type?: string;
+        name?: string;
+        input?: unknown;
+    };
+    delta?: unknown;
+    usage?: {
+        output_tokens?: number | null;
+    };
+}
+/** What the Anthropic brain reads off a message — streamed or not. */
+export interface AnthropicMessage {
+    content: Array<{
+        type: string;
+        text?: string;
+        name?: string;
+        input?: unknown;
+    }>;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+/**
+ * The text this event carries, or "" for anything else (thinking included).
+ *
+ * **Why no fold here.** One `content_block_delta` carries exactly one `delta`
+ * for exactly one `index` — the event type is `{ delta, index, type }`, not a
+ * list — so there is never more than one piece of text in an event and nothing
+ * to concatenate. Multiplicity in Claude's stream lives BETWEEN events, and
+ * that is `accumulateAnthropic`'s job, keyed by `index`.
+ */
+export declare function anthropicDelta(event: AnthropicStreamEvent): string;
+/**
+ * Fold Messages-API events into the message they describe.
+ *
+ * Blocks are addressed by `index` and rebuilt in index order: `text_delta`
+ * pieces concatenate into the block's text, `input_json_delta` pieces
+ * concatenate into the JSON that non-streamed responses deliver already parsed
+ * as `input`.
+ *
+ * Usage arrives in two halves — `input_tokens` at `message_start`, the final
+ * `output_tokens` at `message_delta` — so both are taken where they appear,
+ * with the later `message_delta` count winning.
+ *
+ * A tool block that never receives a delta ends as `input: {}`, which is what
+ * a zero-argument tool call looks like unstreamed.
+ */
+export declare function accumulateAnthropic(events: readonly AnthropicStreamEvent[]): AnthropicMessage;
+/**
+ * One part of a Gemini candidate — text or a function call.
+ *
+ * `args` is `unknown` rather than a record because that is what the SDK's own
+ * `FunctionCall.args` widens to (`object`), and the brain has always narrowed
+ * it with a cast at the point of use. Declaring it narrower here would only
+ * move the cast, not remove it.
+ */
+export interface GeminiPart {
+    text?: string;
+    functionCall?: {
+        name: string;
+        args?: unknown;
+    };
+}
+/** What the Gemini brain reads off a response — streamed or not. */
+export interface GeminiResponse {
+    candidates?: Array<{
+        content?: {
+            parts?: GeminiPart[];
+        };
+    }>;
+    usageMetadata?: {
+        promptTokenCount?: number;
+        candidatesTokenCount?: number;
+    };
+}
+/**
+ * The text this stream item carries, across ALL of its text parts.
+ *
+ * **This is the one extractor of the four that must fold**, and the fold is not
+ * defensive: Gemini's stream element carries an ARRAY of parts, and it really
+ * does put several — a sentence, a function call, a trailing sentence — into
+ * one candidate. Return `parts[0].text` and the watcher sees the first fragment
+ * of a paragraph while the payload holds all of it, which is the precise shape
+ * of "the stream lied to the user's face".
+ */
+export declare function geminiDelta(item: GeminiResponse): string;
+/**
+ * Fold Gemini stream items into the response they describe.
+ *
+ * **The text parts MERGE into one.** This is the whole reason this function is
+ * not a flat concatenation of `parts` arrays: the brain finds its answer with
+ * `parts.find(p => "text" in p)`, so a response left as fifty little text parts
+ * would return the first syllable of the answer and drop the rest. One part in,
+ * one part out — the same shape `generateContent` returns.
+ *
+ * The merged text keeps the POSITION of the first text part it saw, so a
+ * response that opened with a function call still reads in emitted order.
+ * (Order between text and calls does not reach the payload — the brain collects
+ * calls by filter and text by find — but a shape that reorders parts for no
+ * reason is a shape that will eventually be believed.)
+ *
+ * Usage is cumulative in Gemini's stream: the last item that carries it wins.
+ */
+export declare function accumulateGemini(items: readonly GeminiResponse[]): GeminiResponse;
+/** One NDJSON line off `/api/chat` with `stream: true`. */
+export interface OllamaStreamLine {
+    message?: {
+        content?: string;
+        tool_calls?: Array<{
+            function?: {
+                name?: string;
+                arguments?: Record<string, unknown>;
+            };
+        }>;
+    };
+    prompt_eval_count?: number;
+    eval_count?: number;
+}
+/** What the Ollama brain reads off `/api/chat` — streamed or not. */
+export interface OllamaChatResponse {
+    message?: {
+        content?: string;
+        tool_calls?: Array<{
+            function?: {
+                name?: string;
+                arguments?: Record<string, unknown>;
+            };
+        }>;
+    };
+    prompt_eval_count?: number;
+    eval_count?: number;
+}
+/**
+ * The text this line carries.
+ *
+ * **Why no fold here.** One NDJSON line carries one `message`, and that message
+ * carries one `content` string — neither is a list, so there is nothing to
+ * concatenate within a line. Ollama's multiplicity is one token per LINE, which
+ * is `accumulateOllama`'s job.
+ */
+export declare function ollamaDelta(line: OllamaStreamLine): string;
+/**
+ * Split whatever has arrived into whole NDJSON lines plus the leftover.
+ *
+ * Pure, and separate from the reader, because the bug this prevents is invisible
+ * in a happy-path test: a chunk boundary can fall anywhere, including the middle
+ * of a JSON object, and a splitter that forgets `rest` silently drops the token
+ * that straddled the seam. Blank lines are dropped; the trailing fragment is
+ * always handed back to be prefixed onto the next read.
+ */
+export declare function splitNdjsonFrame(buffer: string): {
+    lines: string[];
+    rest: string;
+};
+/**
+ * Fold NDJSON lines into the single response `stream: false` would return.
+ *
+ * Ollama streams content token by token, but hands over tool calls whole (with
+ * `arguments` already an object, not a JSON string) — so calls are collected,
+ * never concatenated. Counts arrive on the final line; last one wins.
+ */
+export declare function accumulateOllama(lines: readonly OllamaStreamLine[]): OllamaChatResponse;
+/**
+ * Read an NDJSON body to the end, emitting text as it arrives.
+ *
+ * The Ollama brain owns no SDK, so this is the equivalent of `consumeStream`
+ * for a raw `fetch` body: decode, split on newlines, parse, emit, keep the
+ * remainder. A line that will not parse is skipped rather than thrown — a
+ * local server that emits a stray keep-alive should not fail a run — and the
+ * abort check sits before the emit for the same reason it does upstream.
+ */
+export declare function consumeNdjson(body: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>, sink: ChunkSink, signal?: AbortSignal): Promise<OllamaStreamLine[]>;