@msm-core/mini 0.9.0 → 0.15.0

package/dist/brain/retry.js

@@ -5,7 +5,105 @@
  * run with an error outcome. Every built-in brain now wraps its provider call
  * in withRetry(): a single bounded retry on transient failures, abort-aware
  * (never retries a cancelled call — that's the loop's time budget firing).
+ *
+ * ── Retrying a STREAM is not retrying a call (ب١/٢) ──────────────────────────
+ *
+ * A retried non-streaming call is invisible: the first attempt's response is
+ * thrown away and only the second one is ever seen. A retried STREAMING call is
+ * not, because the first attempt already spoke. It pushed "The contract sta"
+ * into the consumer's `onChunk` and then died on a 429; the second attempt
+ * opens a fresh stream and says the whole sentence again, and what the human
+ * watching reads is "The contract staThe contract states…". The payload was
+ * always right — only the display lied — which is exactly why it survived ب١.
+ *
+ * The cure has to live at the retry boundary, because that is the only place
+ * that knows an earlier attempt existed. `emitOnce` below is that boundary made
+ * available to the caller: wrap a sink in it and the run's chunks are delivered
+ * by AT MOST ONE attempt.
+ *
+ * **The invariant this buys.** What reaches the consumer is always a PREFIX of
+ * the payload the call finally returns. Never a different string, never a
+ * longer one. That is the whole property: a display may lag the truth, it may
+ * stop short of it, but it may never contradict it — and "The contract staThe
+ * contract states…" contradicts it, because no payload ever said that.
+ *
+ * **Gated on delivery, not on attempt number.** "Mute every attempt after the
+ * first" is the obvious rule and it is wrong: a first attempt that dies while
+ * opening the socket has shown the reader nothing, and muting the retry would
+ * turn a recoverable stumble into a run that streams not one character. So the
+ * gate closes only once a chunk has actually been DELIVERED, and a silent
+ * failure costs the reader nothing.
+ *
+ * **The decision is taken per attempt, before the call.** An attempt either
+ * speaks or it does not; a gate re-read mid-flight could fall silent halfway
+ * through a sentence, which is a worse artifact than the duplicate it replaced.
+ *
+ * **What this costs, stated plainly.** When the first attempt dies mid-sentence
+ * the reader's display stops there: the retry's text is suppressed, and the rest
+ * of the answer arrives with the payload rather than character by character. It
+ * is a truncated display, not a wrong one — and `onChunk` is display, not truth
+ * (ب١), so the returned payload is complete either way.
+ *
+ * **The alternative that was rejected.** Suppressing only the already-delivered
+ * PREFIX and streaming the remainder would keep the display live — but only if
+ * the retry repeats itself word for word, and a re-issued model call is under no
+ * obligation to. When it diverges, prefix-skipping splices the head of one
+ * answer onto the tail of another and hands the reader a sentence neither
+ * attempt produced. Stopping is honest; splicing is not. Delivering the retry
+ * losslessly needs a "discard what I showed you" signal on `BrainChunk`, which
+ * is a consumer-visible contract change and not this file's to make.
+ *
+ * ── The signal, and the covenant it must not break (ص٢/٢) ───────────────────
+ *
+ * That signal now exists: `BrainChunk.reset`. So the gate has TWO patterns, and
+ * which one a run gets is decided by the consumer, never by this file.
+ *
+ *   • **prefix** — the default, and the ص١ path unchanged. A retried attempt is
+ *     muted; the display stops where the dead attempt stopped; what reached the
+ *     reader is a prefix of the payload.
+ *
+ *   • **reset** — only for a sink that went through `acceptResets`. The retried
+ *     attempt is NOT muted. Its first delivered chunk carries `reset: true`,
+ *     meaning "throw away what I sent, start here", and the rest stream
+ *     normally. The reader ends up holding the whole payload: nothing lost,
+ *     nothing doubled.
+ *
+ * **A consumer that did not declare is not affected by any of this.** It is not
+ * a softer default — it is the same branch, the same `SILENT`, the same bytes,
+ * and the reset branch is unreachable without the declaration. That matters
+ * because delivering `reset` to a consumer that appends and ignores it would
+ * reproduce ب١/٢'s duplicate display exactly.
+ *
+ * **The reset rides on a real chunk rather than arriving as its own empty one.**
+ * Two reasons. It cannot be split — a reader that acts on one message and drops
+ * the next can never clear without also receiving the text that replaces it.
+ * And every chunk still corresponds to model text, so "concatenate, clearing at
+ * a reset" yields the payload with no zero-length special case. It is also LAZY:
+ * built when the retried attempt actually delivers, so an attempt that dies
+ * silently a second time clears nothing and leaves the display where ص١ would
+ * have left it.
+ */
+import { isResetAware } from "../core/types.js";
+/** What a muted attempt streams into. */
+const SILENT = () => { };
+/**
+ * The reset pattern's sink for one retried attempt: the first thing it delivers
+ * says "start over", everything after it is ordinary.
+ *
+ * `cleared` is per-attempt, which is what makes a third attempt clear again —
+ * each retry replaces the display, it does not append to the one before it.
  */
+function clearThenStream(sink) {
+    let cleared = false;
+    return (chunk) => {
+        if (cleared) {
+            sink(chunk);
+            return;
+        }
+        cleared = true;
+        sink({ ...chunk, reset: true });
+    };
+}
 const TRANSIENT_CODES = new Set([
     "ECONNRESET",
     "ECONNREFUSED",
@@ -38,14 +136,46 @@ export function isTransientError(err) {
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
-/** Run `fn`, retrying once (by default) on transient provider errors. */
+/**
+ * Run `fn`, retrying once (by default) on transient provider errors.
+ *
+ * `fn` receives an `emitOnce` gate (see the header): wrap the consumer's chunk
+ * sink in it and no text is delivered twice across attempts. A zero-argument
+ * thunk — every caller written before ب١/٢ — is assignable unchanged and behaves
+ * exactly as it did.
+ */
 export async function withRetry(fn, opts = {}) {
     const attempts = Math.max(1, opts.attempts ?? 2);
     const baseDelayMs = opts.baseDelayMs ?? 500;
+    /** Has any attempt so far actually pushed something through a gated sink? */
+    let delivered = false;
     let lastErr;
     for (let attempt = 1; attempt <= attempts; attempt++) {
+        // Read once, here, and not again inside the attempt — see the header.
+        const muted = delivered;
+        const emitOnce = muted
+            ? (sink) => {
+                // PREFIX pattern — the ص١ path, and the only one a sink that did not
+                // declare can reach.
+                if (!isResetAware(sink))
+                    return SILENT;
+                // RESET pattern. The predicate is the evidence: `acceptResets` is the
+                // only producer of the mark and it accepts nothing but a chunk sink,
+                // so this narrowed value really does take a `BrainChunk`. The gate's
+                // own signature stays `(...args: A) => void` for its caller; the args
+                // are ignored because the sink is called with the chunk it is given.
+                const declared = sink;
+                const stream = clearThenStream(declared);
+                return (...args) => {
+                    stream(args[0]);
+                };
+            }
+            : (sink) => (...args) => {
+                delivered = true;
+                sink(...args);
+            };
         try {
-            return await fn();
+            return await fn(emitOnce);
         }
         catch (err) {
             lastErr = err;

package/dist/brain/streaming.d.ts

@@ -23,6 +23,22 @@
  * a stream cannot reconstruct and no brain here consumes, so promising them
  * would be a lie the compiler would happily keep.
  *
+ * **The responder's name joined that set in س٦/٤**, by the same rule: the
+ * brains now read it (`respondingModel`) to record WHO answered in the session
+ * log, so it is a field this file has to carry or the answer is lost. And it is
+ * the one field here a stream CAN reconstruct — every provider stamps it on the
+ * wire, measured: OpenAI on each `ChatCompletionChunk`, Anthropic on the
+ * `message_start` message, Gemini as `modelVersion` on every stream element,
+ * Ollama on every NDJSON line. Leaving it out was not a design decision but the
+ * shape of the file before anyone needed it, and the cost was precise: nisus
+ * sets `hooks.onChunk` on every agent it builds, so EVERY turn it runs is a
+ * streamed turn, and every one of them would have logged no responder at all.
+ *
+ * **Absent stays absent.** Every carry below is a conditional spread: a stream
+ * that never names a model folds to the object it folded to yesterday, key for
+ * key, and the ب١ fixtures that assert `fold(chunks) === nonStreamed` keep
+ * passing untouched.
+ *
  * **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.
@@ -67,6 +83,8 @@ export interface OpenAIStreamChunk {
         prompt_tokens?: number;
         completion_tokens?: number;
     } | null;
+    /** The serving model — OpenAI stamps it on every chunk (`ChatCompletionChunk.model`). */
+    model?: string;
 }
 /**
  * What the OpenAI brain reads off a completion — streamed or not.
@@ -89,6 +107,8 @@ export interface OpenAICompletion {
         prompt_tokens?: number;
         completion_tokens?: number;
     } | null;
+    /** Who answered — `ChatCompletion.model`, and the streamed chunks' `model`. */
+    model?: string;
 }
 /**
  * The text this chunk carries, or "" for a tool-call or usage-only chunk.
@@ -139,6 +159,8 @@ export interface AnthropicStreamEvent {
             input_tokens?: number;
             output_tokens?: number;
         };
+        /** The serving model — carried on the `message_start` event's message. */
+        model?: string;
     };
     content_block?: {
         type?: string;
@@ -157,11 +179,23 @@ export interface AnthropicMessage {
         text?: string;
         name?: string;
         input?: unknown;
+        /**
+         * The body of a `thinking` block, as the unstreamed API spells it (ت١/٨).
+         * The brain joins these into `BrainPayload.thoughts` and never into the
+         * text. The streamed fold below does NOT carry it — `thinking_delta` is
+         * neither text nor JSON to `accumulateAnthropic`, so a streamed thinking
+         * block folds to `{ type: "thinking", text: "" }` as it always has, and
+         * `thoughts` is simply absent on that path. Said here so nobody reads the
+         * asymmetry as an accident: this brain does not request thinking at all.
+         */
+        thinking?: string;
     }>;
     usage: {
         input_tokens: number;
         output_tokens: number;
     };
+    /** Who answered — `Message.model`, and the `message_start` message's model. */
+    model?: string;
 }
 /**
  * The text this event carries, or "" for anything else (thinking included).
@@ -203,6 +237,18 @@ export interface GeminiPart {
         name: string;
         args?: unknown;
     };
+    /**
+     * `true` on a text part that is the model's THINKING, not its answer (ت١).
+     *
+     * Gemini 2.5+ marks the parts it emits under `thinkingConfig.includeThoughts`
+     * with exactly this flag, on the wire, and `@google/generative-ai` 0.24.1
+     * hands the parsed body through without declaring the field — so it is
+     * declared here, where the brain reads it, and nowhere else. A part without
+     * the flag (or with it `false`) is answer text; ONLY `=== true` is thinking.
+     * The brain drops what the provider tagged and keeps what it did not — prose
+     * that merely *reads* like reasoning is the prompt's business, not the loop's.
+     */
+    thought?: boolean;
 }
 /** What the Gemini brain reads off a response — streamed or not. */
 export interface GeminiResponse {
@@ -215,6 +261,16 @@ export interface GeminiResponse {
         promptTokenCount?: number;
         candidatesTokenCount?: number;
     };
+    /**
+     * Who answered. Google's spelling of the field, and the reason
+     * `respondingModel` knows two names for one thing.
+     *
+     * Undeclared by `@google/generative-ai`'s own `GenerateContentResponse` (it
+     * stops at three properties) — but the SDK hands back the parsed response
+     * body as it arrived, so the field is live on the wire and on the object.
+     * Declaring it here is what lets the brain read it without a cast.
+     */
+    modelVersion?: string;
 }
 /**
  * The text this stream item carries, across ALL of its text parts.
@@ -231,17 +287,28 @@ 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.
+ * not a flat concatenation of `parts` arrays: until ت١ the brain found its
+ * answer with `parts.find(p => "text" in p)`, so a response left as fifty
+ * little text parts returned the first syllable of the answer and dropped the
+ * rest. The brain now JOINS every text part, so the merge is no longer what
+ * saves the answer — but one part in, one part out is still the shape
+ * `generateContent` returns, and a fold that equals the unstreamed object is
+ * the claim the ب١ fixtures check.
  *
  * 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
+ * calls by filter and text by join — but a shape that reorders parts for no
  * reason is a shape that will eventually be believed.)
  *
+ * **Two slots, not one (ت١).** A part the model tagged `thought: true` merges
+ * into its OWN part, tagged the same way, and never into the answer's. The
+ * folded shape therefore still carries both kinds, tagged as they arrived, and
+ * the brain decides text-versus-thinking on that shape with the same lines it
+ * uses on an unstreamed candidate — one place for the decision, two paths
+ * through it. A stream with no thinking part folds to the object it folded to
+ * before the second slot existed, key for key.
+ *
  * Usage is cumulative in Gemini's stream: the last item that carries it wins.
  */
 export declare function accumulateGemini(items: readonly GeminiResponse[]): GeminiResponse;
@@ -258,6 +325,8 @@ export interface OllamaStreamLine {
     };
     prompt_eval_count?: number;
     eval_count?: number;
+    /** The served tag — Ollama repeats it on every line. */
+    model?: string;
 }
 /** What the Ollama brain reads off `/api/chat` — streamed or not. */
 export interface OllamaChatResponse {
@@ -272,6 +341,12 @@ export interface OllamaChatResponse {
     };
     prompt_eval_count?: number;
     eval_count?: number;
+    /**
+     * Who answered — the served tag, top level in the `/api/chat` body. On a
+     * local host this is the one place a re-pulled or re-tagged model shows
+     * itself, since nothing about the request would change.
+     */
+    model?: string;
 }
 /**
  * The text this line carries.

package/dist/brain/streaming.js

@@ -23,6 +23,22 @@
  * a stream cannot reconstruct and no brain here consumes, so promising them
  * would be a lie the compiler would happily keep.
  *
+ * **The responder's name joined that set in س٦/٤**, by the same rule: the
+ * brains now read it (`respondingModel`) to record WHO answered in the session
+ * log, so it is a field this file has to carry or the answer is lost. And it is
+ * the one field here a stream CAN reconstruct — every provider stamps it on the
+ * wire, measured: OpenAI on each `ChatCompletionChunk`, Anthropic on the
+ * `message_start` message, Gemini as `modelVersion` on every stream element,
+ * Ollama on every NDJSON line. Leaving it out was not a design decision but the
+ * shape of the file before anyone needed it, and the cost was precise: nisus
+ * sets `hooks.onChunk` on every agent it builds, so EVERY turn it runs is a
+ * streamed turn, and every one of them would have logged no responder at all.
+ *
+ * **Absent stays absent.** Every carry below is a conditional spread: a stream
+ * that never names a model folds to the object it folded to yesterday, key for
+ * key, and the ب١ fixtures that assert `fold(chunks) === nonStreamed` keep
+ * passing untouched.
+ *
  * **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.
@@ -94,10 +110,16 @@ export function accumulateOpenAI(chunks) {
     let content = "";
     let sawText = false;
     let usage;
+    let model;
     const fragments = new Map();
     for (const chunk of chunks) {
         if (chunk.usage)
             usage = chunk.usage;
+        // Every chunk repeats the serving model; the last one wins, exactly as
+        // `usage` does. They should all agree — and if a gateway ever re-routed
+        // mid-response, the name that answered LAST is the honest one to record.
+        if (chunk.model)
+            model = chunk.model;
         const delta = chunk.choices?.[0]?.delta;
         if (!delta)
             continue;
@@ -132,6 +154,7 @@ export function accumulateOpenAI(chunks) {
             },
         ],
         ...(usage ? { usage } : {}),
+        ...(model !== undefined ? { model } : {}),
     };
 }
 function blockDelta(delta) {
@@ -173,6 +196,7 @@ export function accumulateAnthropic(events) {
     const blocks = new Map();
     let inputTokens = 0;
     let outputTokens = 0;
+    let model;
     for (const event of events) {
         if (event.type === "message_start") {
             const usage = event.message?.usage;
@@ -180,6 +204,10 @@ export function accumulateAnthropic(events) {
                 inputTokens = usage.input_tokens;
             if (typeof usage?.output_tokens === "number")
                 outputTokens = usage.output_tokens;
+            // Claude names the serving model once, in the opening event's message —
+            // the same object the non-streamed call returns whole.
+            if (typeof event.message?.model === "string")
+                model = event.message.model;
             continue;
         }
         if (event.type === "message_delta") {
@@ -218,7 +246,11 @@ export function accumulateAnthropic(events) {
         .map(([, slot]) => slot.type === "tool_use"
         ? { type: "tool_use", name: slot.name, input: parseJsonObject(slot.json) }
         : { type: slot.type, text: slot.text });
-    return { content, usage: { input_tokens: inputTokens, output_tokens: outputTokens } };
+    return {
+        content,
+        usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+        ...(model !== undefined ? { model } : {}),
+    };
 }
 /**
  * The text this stream item carries, across ALL of its text parts.
@@ -234,6 +266,11 @@ export function geminiDelta(item) {
     const parts = item.candidates?.[0]?.content?.parts ?? [];
     let text = "";
     for (const part of parts) {
+        // A thinking part is not the answer, and what reaches the watcher must
+        // stay a prefix of the answer the payload finally carries (ب١) — so it is
+        // skipped here for the same reason the brain keeps it out of the text.
+        if (part.thought === true)
+            continue;
         if (typeof part.text === "string")
             text += part.text;
     }
@@ -243,35 +280,60 @@ export function geminiDelta(item) {
  * 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.
+ * not a flat concatenation of `parts` arrays: until ت١ the brain found its
+ * answer with `parts.find(p => "text" in p)`, so a response left as fifty
+ * little text parts returned the first syllable of the answer and dropped the
+ * rest. The brain now JOINS every text part, so the merge is no longer what
+ * saves the answer — but one part in, one part out is still the shape
+ * `generateContent` returns, and a fold that equals the unstreamed object is
+ * the claim the ب١ fixtures check.
  *
  * 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
+ * calls by filter and text by join — but a shape that reorders parts for no
  * reason is a shape that will eventually be believed.)
  *
+ * **Two slots, not one (ت١).** A part the model tagged `thought: true` merges
+ * into its OWN part, tagged the same way, and never into the answer's. The
+ * folded shape therefore still carries both kinds, tagged as they arrived, and
+ * the brain decides text-versus-thinking on that shape with the same lines it
+ * uses on an unstreamed candidate — one place for the decision, two paths
+ * through it. A stream with no thinking part folds to the object it folded to
+ * before the second slot existed, key for key.
+ *
  * Usage is cumulative in Gemini's stream: the last item that carries it wins.
  */
 export function accumulateGemini(items) {
     const parts = [];
     let textSlot = -1;
+    let thoughtSlot = -1;
     let usage;
+    let modelVersion;
+    // Append `text` to the part at `slot`, opening it at the end if there is none
+    // yet; returns the slot. `thought` rides along so the merged part stays tagged.
+    const merge = (slot, text, thought) => {
+        if (slot === -1) {
+            parts.push(thought ? { text, thought: true } : { text });
+            return parts.length - 1;
+        }
+        const joined = (parts[slot]?.text ?? "") + text;
+        parts[slot] = thought ? { text: joined, thought: true } : { text: joined };
+        return slot;
+    };
     for (const item of items) {
         if (item.usageMetadata)
             usage = item.usageMetadata;
+        // Every element repeats it (each is a whole `GenerateContentResponse`);
+        // last one wins, as with usage.
+        if (item.modelVersion)
+            modelVersion = item.modelVersion;
         for (const part of item.candidates?.[0]?.content?.parts ?? []) {
             if (typeof part.text === "string") {
-                if (textSlot === -1) {
-                    textSlot = parts.length;
-                    parts.push({ text: part.text });
-                }
-                else {
-                    parts[textSlot] = { text: (parts[textSlot]?.text ?? "") + part.text };
-                }
+                if (part.thought === true)
+                    thoughtSlot = merge(thoughtSlot, part.text, true);
+                else
+                    textSlot = merge(textSlot, part.text, false);
             }
             else if (part.functionCall) {
                 parts.push({ functionCall: part.functionCall });
@@ -281,6 +343,7 @@ export function accumulateGemini(items) {
     return {
         candidates: [{ content: { parts } }],
         ...(usage ? { usageMetadata: usage } : {}),
+        ...(modelVersion !== undefined ? { modelVersion } : {}),
     };
 }
 /**
@@ -323,6 +386,7 @@ export function accumulateOllama(lines) {
     const toolCalls = [];
     let promptEvalCount;
     let evalCount;
+    let model;
     for (const line of lines) {
         if (typeof line.message?.content === "string")
             content += line.message.content;
@@ -333,6 +397,9 @@ export function accumulateOllama(lines) {
         }
         if (typeof line.eval_count === "number")
             evalCount = line.eval_count;
+        // Repeated on every line; last one wins, as with the counts.
+        if (line.model)
+            model = line.model;
     }
     return {
         message: {
@@ -341,6 +408,7 @@ export function accumulateOllama(lines) {
         },
         ...(promptEvalCount !== undefined ? { prompt_eval_count: promptEvalCount } : {}),
         ...(evalCount !== undefined ? { eval_count: evalCount } : {}),
+        ...(model !== undefined ? { model } : {}),
     };
 }
 /**

package/dist/core/hooks.d.ts

@@ -10,13 +10,25 @@ export declare function fireSectionComplete(hooks: AgentHooks | undefined, sessi
 export declare function fireToolCall(hooks: AgentHooks | undefined, sessionId: string, result: ToolResult, iteration: number, cached: boolean, durationMs: number): void;
 export declare function fireGuard(hooks: AgentHooks | undefined, sessionId: string, signal: GuardSignal, iteration: number): void;
 /**
- * One streamed piece of model text (ب١).
+ * One streamed piece of model text (ب١), carrying `reset` when there is one
+ * and a consumer who asked for it (ص٣/٢).
  *
  * Same shape as its siblings, and the same contract: `safely` swallows a
  * throwing hook. That matters more here than anywhere else — this one fires
  * dozens of times per step, in the middle of reading a provider stream, and a
  * consumer whose SSE socket closed mid-answer must not take the run down with
  * it. A failed display is a failed display, not a failed run.
+ *
+ * **`reset` is spread, not assigned.** `{ sessionId, iteration, text }` is what
+ * an undeclared consumer received before this parameter existed and it is
+ * exactly what it receives now — the key is ABSENT, not present-and-undefined,
+ * so `Object.keys`, `toEqual`, `JSON.stringify` and a `for…in` all see what
+ * they saw yesterday. That equality is the mandatory control of ص٣/٢, and
+ * writing `reset` unconditionally would have broken it while every existing
+ * assertion stayed green.
+ *
+ * The parameter is optional and last, so the pre-ص٣ call shape still compiles
+ * and still means what it meant.
  */
-export declare function fireChunk(hooks: AgentHooks | undefined, sessionId: string, iteration: number, text: string): void;
+export declare function fireChunk(hooks: AgentHooks | undefined, sessionId: string, iteration: number, text: string, reset?: true): void;
 export declare function fireFatalError(hooks: AgentHooks | undefined, error: Error, sessionId: string): void;

package/dist/core/hooks.js

@@ -54,18 +54,35 @@ export function fireGuard(hooks, sessionId, signal, iteration) {
     safely(() => hooks.onGuard({ sessionId, signal, iteration }));
 }
 /**
- * One streamed piece of model text (ب١).
+ * One streamed piece of model text (ب١), carrying `reset` when there is one
+ * and a consumer who asked for it (ص٣/٢).
  *
  * Same shape as its siblings, and the same contract: `safely` swallows a
  * throwing hook. That matters more here than anywhere else — this one fires
  * dozens of times per step, in the middle of reading a provider stream, and a
  * consumer whose SSE socket closed mid-answer must not take the run down with
  * it. A failed display is a failed display, not a failed run.
+ *
+ * **`reset` is spread, not assigned.** `{ sessionId, iteration, text }` is what
+ * an undeclared consumer received before this parameter existed and it is
+ * exactly what it receives now — the key is ABSENT, not present-and-undefined,
+ * so `Object.keys`, `toEqual`, `JSON.stringify` and a `for…in` all see what
+ * they saw yesterday. That equality is the mandatory control of ص٣/٢, and
+ * writing `reset` unconditionally would have broken it while every existing
+ * assertion stayed green.
+ *
+ * The parameter is optional and last, so the pre-ص٣ call shape still compiles
+ * and still means what it meant.
  */
-export function fireChunk(hooks, sessionId, iteration, text) {
+export function fireChunk(hooks, sessionId, iteration, text, reset) {
     if (!hooks?.onChunk)
         return;
-    safely(() => hooks.onChunk({ sessionId, iteration, text }));
+    safely(() => hooks.onChunk({
+        sessionId,
+        iteration,
+        text,
+        ...(reset === true ? { reset } : {}),
+    }));
 }
 export function fireFatalError(hooks, error, sessionId) {
     if (!hooks?.onFatalError)