@msm-core/mini 0.9.0 → 0.15.0

package/dist/adapters/memory-lock.d.ts

@@ -0,0 +1,45 @@
+/**
+ * In-memory RunLockPort — a session mutex with no Redis.
+ *
+ * **This one has to actually lock.** A stub that always grants would make every
+ * test of the no-Redis loop pass while removing the guarantee the lock exists
+ * for: one turn per session at a time. Two turns running into one session
+ * interleave their history writes and their log appends, and the damage is
+ * silent — a log with two turns braided together still reads as a log. So the
+ * in-RAM lock is a real mutex, and it is guarded by a test that starts a second
+ * turn while the first is still inside the brain call and watches it wait.
+ *
+ * Fidelity to `RedisDistributedLock`, semantics first:
+ *   - **held is held**: `acquire` returns `null` for a session already locked,
+ *     rather than a second handle.
+ *   - **TTL is honoured**: a lock past its `ttlMs` is treated as gone, exactly
+ *     as `SET PX` lets Redis drop it. A RAM lock that never expired would
+ *     deadlock a session that Redis would have freed — the mirror would be
+ *     safer than the original, which is its own kind of lie.
+ *   - **release and extend are token-checked**: only the holder's own handle
+ *     can release or extend, which is what the `GET == token` Lua scripts buy
+ *     on the Redis side. A late release from a previous holder whose lock has
+ *     already expired must not unlock the current one.
+ *   - **the retry loop is the same shape**: attempt, jittered sleep, deadline —
+ *     and the same error message when the deadline passes, because that string
+ *     is what surfaces from the loop when a session is genuinely stuck.
+ *
+ * Scope: ONE process. Across replicas this excludes nothing at all, and that is
+ * not a limitation to work around — a mutex for a single-process deploy is the
+ * whole of what it claims to be. Multi-replica deploys use
+ * `RedisDistributedLock`.
+ */
+import type { LockHandle, RunLockPort } from "../core/types.js";
+export declare class InMemoryLock implements RunLockPort {
+    private readonly held;
+    /** The live holder of this session, or `undefined` if free or expired. */
+    private current;
+    /**
+     * Take the lock, or return `null` if someone else holds it.
+     * Not required by `RunLockPort` — the loop only ever waits — but it is the
+     * primitive `acquireWithRetry` is built from, and `RedisDistributedLock`
+     * exposes it too.
+     */
+    acquire(sessionId: string, ttlMs: number): Promise<LockHandle | null>;
+    acquireWithRetry(sessionId: string, ttlMs: number, waitMs?: number, retryInterval?: number): Promise<LockHandle>;
+}

package/dist/adapters/memory-lock.js

@@ -0,0 +1,89 @@
+/**
+ * In-memory RunLockPort — a session mutex with no Redis.
+ *
+ * **This one has to actually lock.** A stub that always grants would make every
+ * test of the no-Redis loop pass while removing the guarantee the lock exists
+ * for: one turn per session at a time. Two turns running into one session
+ * interleave their history writes and their log appends, and the damage is
+ * silent — a log with two turns braided together still reads as a log. So the
+ * in-RAM lock is a real mutex, and it is guarded by a test that starts a second
+ * turn while the first is still inside the brain call and watches it wait.
+ *
+ * Fidelity to `RedisDistributedLock`, semantics first:
+ *   - **held is held**: `acquire` returns `null` for a session already locked,
+ *     rather than a second handle.
+ *   - **TTL is honoured**: a lock past its `ttlMs` is treated as gone, exactly
+ *     as `SET PX` lets Redis drop it. A RAM lock that never expired would
+ *     deadlock a session that Redis would have freed — the mirror would be
+ *     safer than the original, which is its own kind of lie.
+ *   - **release and extend are token-checked**: only the holder's own handle
+ *     can release or extend, which is what the `GET == token` Lua scripts buy
+ *     on the Redis side. A late release from a previous holder whose lock has
+ *     already expired must not unlock the current one.
+ *   - **the retry loop is the same shape**: attempt, jittered sleep, deadline —
+ *     and the same error message when the deadline passes, because that string
+ *     is what surfaces from the loop when a session is genuinely stuck.
+ *
+ * Scope: ONE process. Across replicas this excludes nothing at all, and that is
+ * not a limitation to work around — a mutex for a single-process deploy is the
+ * whole of what it claims to be. Multi-replica deploys use
+ * `RedisDistributedLock`.
+ */
+import { randomBytes } from "crypto";
+export class InMemoryLock {
+    held = new Map();
+    /** The live holder of this session, or `undefined` if free or expired. */
+    current(sessionId) {
+        const entry = this.held.get(sessionId);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.held.delete(sessionId);
+            return undefined;
+        }
+        return entry;
+    }
+    /**
+     * Take the lock, or return `null` if someone else holds it.
+     * Not required by `RunLockPort` — the loop only ever waits — but it is the
+     * primitive `acquireWithRetry` is built from, and `RedisDistributedLock`
+     * exposes it too.
+     */
+    async acquire(sessionId, ttlMs) {
+        if (this.current(sessionId))
+            return null;
+        const token = randomBytes(16).toString("hex");
+        this.held.set(sessionId, { token, expiresAt: Date.now() + ttlMs });
+        const ownsIt = () => this.current(sessionId)?.token === token;
+        return {
+            release: async () => {
+                // Token-checked: a handle whose lock already expired and was retaken
+                // must not release the new holder's lock.
+                if (ownsIt())
+                    this.held.delete(sessionId);
+            },
+            extend: async (newTtlMs) => {
+                if (!ownsIt())
+                    return false;
+                this.held.set(sessionId, {
+                    token,
+                    expiresAt: Date.now() + newTtlMs,
+                });
+                return true;
+            },
+        };
+    }
+    async acquireWithRetry(sessionId, ttlMs, waitMs = 5000, retryInterval = 100) {
+        const deadline = Date.now() + waitMs;
+        while (Date.now() < deadline) {
+            const handle = await this.acquire(sessionId, ttlMs);
+            if (handle)
+                return handle;
+            await sleep(retryInterval + Math.random() * 50);
+        }
+        throw new Error(`msm-mini: could not acquire lock for session ${sessionId} within ${waitMs}ms`);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/adapters/redis-control.d.ts

@@ -7,7 +7,8 @@
  * Checked on every loop iteration before the brain call.
  */
 import type { RedisLike } from "./redis-types.js";
-export declare class RedisControlBus {
+import type { ControlBusPort } from "../core/types.js";
+export declare class RedisControlBus implements ControlBusPort {
     private readonly redis;
     private readonly prefix;
     constructor(redis: RedisLike, prefix?: string);

package/dist/adapters/redis-lock.d.ts

@@ -8,11 +8,15 @@
  * TTL: timeoutMs + 30s safety margin
  */
 import type { RedisLike } from "./redis-types.js";
-export interface LockHandle {
-    release(): Promise<void>;
-    extend(ttlMs: number): Promise<boolean>;
-}
-export declare class RedisDistributedLock {
+import type { LockHandle, RunLockPort } from "../core/types.js";
+/**
+ * Re-exported from its new home in `core/types.ts` (س٦), where it belongs with
+ * the port every lock implements rather than with one implementation of it.
+ * Every existing `import { LockHandle } from "@msm-core/mini/adapters"` keeps
+ * working, unchanged.
+ */
+export type { LockHandle };
+export declare class RedisDistributedLock implements RunLockPort {
     private readonly redis;
     private readonly prefix;
     constructor(redis: RedisLike, prefix?: string);

package/dist/brain/anthropic.js

@@ -2,6 +2,7 @@
  * Anthropic Brain — Claude via Messages API.
  * Peer dependency: @anthropic-ai/sdk >= 0.20.0
  */
+import { respondingModel } from "../core/types.js";
 import { computeCostUsd } from "./pricing.js";
 import { withRetry } from "./retry.js";
 import { foldToolResults, toolParamsToJsonSchema, toWireMessage, useToolOrchestration, } from "./tool-context.js";
@@ -63,7 +64,7 @@ export function createAnthropicBrain(opts) {
             // land in `AnthropicMessage` — the fields this brain reads — so the
             // payload is built once, from one shape.
             const response = input.onChunk
-                ? await withRetry(() => streamMessage(client, params, input.onChunk, input.signal), input.signal ? { signal: input.signal } : {})
+                ? await withRetry((emitOnce) => streamMessage(client, params, emitOnce(input.onChunk), input.signal), input.signal ? { signal: input.signal } : {})
                 : await withRetry(() => client.messages.create(params, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {});
             const content = response.content;
             const inputTokens = response.usage.input_tokens;
@@ -81,22 +82,46 @@ export function createAnthropicBrain(opts) {
                     params: (block.input ?? {}),
                 });
             }
+            // Text and thinking — the same rule as Gemini's (ت١/٨). EVERY `text`
+            // block, in the order Claude emitted them, joined with no separator;
+            // `thinking` blocks join separately into `thoughts` and never into the
+            // answer. Measured before this: `.find()` took the FIRST text block and
+            // dropped every later one, while thinking was already kept out by the
+            // type check. A `thinking` body only arrives unstreamed — the streamed
+            // fold carries no such field (see `AnthropicMessage`) — and this brain
+            // never asks for thinking, so `thoughts` is a contract, not a promise.
+            let text = "";
+            let thoughts = "";
+            for (const block of content) {
+                if (block.type === "text" && typeof block.text === "string") {
+                    text += block.text;
+                }
+                else if (block.type === "thinking" && typeof block.thinking === "string") {
+                    thoughts += block.thinking;
+                }
+            }
+            const thinking = thoughts ? { thoughts } : {};
             const orchestration = useToolOrchestration(calls, 0.9);
             if (orchestration) {
                 return {
                     orchestration,
                     usage: { inputTokens, outputTokens },
                     costUsd,
+                    ...thinking,
+                    ...respondingModel(response),
                 };
             }
-            // Text
-            const textBlock = content.find((b) => b.type === "text");
-            const text = textBlock?.text ?? "";
             return {
                 generation: { response_text: text },
                 orchestration: { action: "respond", confidence: 0.95 },
                 usage: { inputTokens, outputTokens },
                 costUsd,
+                ...thinking,
+                // Who answered, off the message itself — Claude names the model that
+                // served the request, which is not always the alias that was asked for.
+                // Streamed or not, `response` is the same shape: `message_start`
+                // carries the name and `accumulateAnthropic` keeps it.
+                ...respondingModel(response),
             };
         },
     };

package/dist/brain/factory.js

@@ -13,11 +13,64 @@ export function buildBrain(def) {
             return createOpenAIBrain({ ...(model ? { model } : {}), ...(endpoint ? { baseURL: endpoint } : {}), ...(apiKey ? { apiKey } : {}) });
         case "anthropic":
             return createAnthropicBrain({ ...(model ? { model } : {}), ...(apiKey ? { apiKey } : {}) });
-        case "gemini":
-            return createGeminiBrain({ ...(model ? { model } : {}), ...(apiKey ? { apiKey } : {}) });
+        case "gemini": {
+            // `## Brain` → `thinking` (ت١/٢): the definition's key reaches the brain
+            // here, and only after its shape is checked — a definition is data from
+            // a file or a host, and `[key: string]: unknown` lets anything through.
+            const thinking = brainThinkingOf(def.brain.thinking);
+            return createGeminiBrain({
+                ...(model ? { model } : {}),
+                ...(apiKey ? { apiKey } : {}),
+                ...(thinking ? { thinking } : {}),
+            });
+        }
         case "ollama":
             return createOllamaBrain({ ...(endpoint ? { endpoint } : {}), ...(model ? { model } : {}) });
         default:
             throw new Error(`msm-mini: unknown brain provider "${String(provider)}". Pass a Brain instance directly to createAgent().`);
     }
 }
+/**
+ * `def.brain.thinking` checked into the option `createGeminiBrain` takes, or
+ * `undefined` when the definition has none.
+ *
+ * A NAMED error for a wrong shape, not silence: `thinking` was added so a
+ * definition could switch the model's reasoning on, and a value that quietly
+ * did nothing would be the same leak with a config line under it. An object;
+ * `budget` a finite number ≥ 0 when given (`0` is thinking OFF); `includeThoughts`
+ * a boolean when given. Each field is copied only when set, so `{}` — and a
+ * host that spreads `{ budget: undefined }` — reaches the brain as an empty
+ * option, which the brain reads as absence.
+ */
+function brainThinkingOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`msm-mini: brain.thinking must be an object { budget?, includeThoughts? }, got ${describe(value)}`);
+    }
+    // `in` narrows `object` to the key it names — no cast over the definition.
+    const budget = "budget" in value ? value.budget : undefined;
+    const includeThoughts = "includeThoughts" in value ? value.includeThoughts : undefined;
+    if (budget !== undefined && !(typeof budget === "number" && Number.isFinite(budget) && budget >= 0)) {
+        throw new Error(`msm-mini: brain.thinking.budget must be a finite number >= 0, got ${describe(budget)}`);
+    }
+    if (includeThoughts !== undefined && typeof includeThoughts !== "boolean") {
+        throw new Error(`msm-mini: brain.thinking.includeThoughts must be a boolean, got ${describe(includeThoughts)}`);
+    }
+    return {
+        ...(budget !== undefined ? { budget } : {}),
+        ...(includeThoughts !== undefined ? { includeThoughts } : {}),
+    };
+}
+/** A value as an error message shows it: `"abc"`, `null`, `an array`. */
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "object")
+        return "an object";
+    return String(value);
+}

package/dist/brain/gemini.d.ts

@@ -3,7 +3,23 @@
  * Peer dependency: @google/generative-ai >= 0.14.0
  */
 import type { Brain } from "./types.js";
-export declare function createGeminiBrain(opts: {
+export interface GeminiBrainOptions {
     apiKey?: string;
     model?: string;
-}): Brain;
+    /**
+     * Thinking, opted into (ت١/٤). Translated to `generationConfig.thinkingConfig`
+     * — `budget` → `thinkingBudget`, `includeThoughts` → `includeThoughts`, each
+     * only when given — and ONLY when at least one field is given: absent,
+     * explicitly `undefined` from a JavaScript host, or an empty `{}`, the
+     * request carries no `generationConfig` at all and not one byte of it changes.
+     *
+     * `budget: 0` turns thinking off on models that allow it; `includeThoughts:
+     * true` asks for the reasoning back as parts tagged `thought: true`, which
+     * the brain routes to `BrainPayload.thoughts` and never into the answer.
+     */
+    thinking?: {
+        budget?: number;
+        includeThoughts?: boolean;
+    };
+}
+export declare function createGeminiBrain(opts: GeminiBrainOptions): Brain;

package/dist/brain/gemini.js

@@ -2,12 +2,16 @@
  * Gemini Brain — Google Gemini 2.5 Flash (primary brain for UTS).
  * Peer dependency: @google/generative-ai >= 0.14.0
  */
+import { respondingModel } from "../core/types.js";
 import { withRetry } from "./retry.js";
 import { foldToolResults, toWireMessage, useToolOrchestration, } from "./tool-context.js";
 import { accumulateGemini, consumeStream, geminiDelta, } from "./streaming.js";
 import { computeCostUsd } from "./pricing.js";
 export function createGeminiBrain(opts) {
     const model = opts.model ?? "gemini-2.5-flash";
+    // Resolved once, at composition: the request below spreads it, so a brain
+    // built without the option builds the request it always built.
+    const thinkingConfig = thinkingConfigOf(opts.thinking);
     return {
         name: "gemini",
         async run(input) {
@@ -54,13 +58,19 @@ export function createGeminiBrain(opts) {
                     },
                 ]
                 : undefined;
-            const request = tools
-                ? {
-                    systemInstruction: input.system_context,
-                    contents,
-                    tools: tools,
-                }
-                : { systemInstruction: input.system_context, contents };
+            const request = {
+                systemInstruction: input.system_context,
+                contents,
+                ...(tools
+                    ? {
+                        tools: tools,
+                    }
+                    : {}),
+                // The one key ت١ adds, and only for a brain that asked for it — a
+                // conditional spread, so "no option" leaves no `generationConfig` key
+                // (not even an `undefined` one) for the SDK to serialize.
+                ...(thinkingConfig ? { generationConfig: { thinkingConfig } } : {}),
+            };
             // ── The one branch streaming adds ──────────────────────────────────
             //
             // No `onChunk`, no stream: the call below is the call this brain has
@@ -68,7 +78,7 @@ export function createGeminiBrain(opts) {
             // land in `GeminiResponse` — the fields this brain reads — so the payload
             // is built once, from one shape.
             const response = input.onChunk
-                ? await withRetry(() => streamContent(() => geminiModel.generateContentStream(request, input.signal ? { signal: input.signal } : {}), input.onChunk, input.signal), input.signal ? { signal: input.signal } : {})
+                ? await withRetry((emitOnce) => streamContent(() => geminiModel.generateContentStream(request, input.signal ? { signal: input.signal } : {}), emitOnce(input.onChunk), input.signal), input.signal ? { signal: input.signal } : {})
                 : (await withRetry(() => geminiModel.generateContent(request, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {})).response;
             const parts = response?.candidates?.[0]?.content?.parts ?? [];
             // Token usage + cost — computed ONCE and returned on BOTH the tool-call and text
@@ -98,22 +108,84 @@ export function createGeminiBrain(opts) {
                     params: (fc.args ?? {}),
                 });
             }
+            // Text and thinking — EVERY text part, in emitted order, joined with no
+            // separator; the parts the model tagged `thought: true` join separately
+            // into `thoughts` and never into the answer (ت١). `.find()` took the
+            // first text part and dropped the rest, and with thinking on that first
+            // part was the reasoning, so the user read the model's notes instead of
+            // its reply. Untagged prose is kept as written: what the provider did not
+            // mark is answer text, and guessing is the prompt's job, not the loop's.
+            //
+            // One loop for both shapes — the raw candidate `generateContent` returns
+            // and the folded one `accumulateGemini` builds, which keeps its thinking
+            // in a part tagged the same way — so the streamed and unstreamed paths
+            // decide text-versus-thinking on the same lines.
+            let text = "";
+            let thoughts = "";
+            for (const part of parts) {
+                if (typeof part.text !== "string")
+                    continue;
+                if (part.thought === true)
+                    thoughts += part.text;
+                else
+                    text += part.text;
+            }
+            // Absent when there was no thinking — a key only when it says something.
+            const thinking = thoughts ? { thoughts } : {};
             const orchestration = useToolOrchestration(calls, 0.9);
             if (orchestration) {
-                return { orchestration, costUsd, ...(usage ? { usage } : {}) };
+                return {
+                    orchestration,
+                    costUsd,
+                    ...(usage ? { usage } : {}),
+                    ...thinking,
+                    ...respondingModel(response),
+                };
             }
-            // Text response
-            const textPart = parts.find((p) => "text" in p && typeof p.text === "string");
-            const text = textPart && "text" in textPart ? textPart.text : "";
             return {
                 generation: { response_text: text },
                 orchestration: { action: "respond", confidence: 0.95 },
                 costUsd,
                 ...(usage ? { usage } : {}),
+                ...thinking,
+                // Who answered — Gemini spells it `modelVersion`, and it is the field
+                // that tells `gemini-2.5-flash` from the dated build that served it.
+                // The SDK's non-streaming path hands back the parsed response body as
+                // it arrived, so the field survives even though its own `.d.ts` stops
+                // at three properties; on the streamed path every element repeats it
+                // and `accumulateGemini` carries it through. One line, both paths.
+                ...respondingModel(response),
             };
         },
     };
 }
+/**
+ * `createGeminiBrain({ thinking })` → the wire's `thinkingConfig`, or
+ * `undefined` when the option says nothing.
+ *
+ * Absence is read from the VALUE, not the key (تعميم المجلس ٦): a JavaScript
+ * host that spreads `thinking: undefined` gets the request it would get with
+ * no option at all. Each field is copied only when set, and `0` is a value —
+ * `budget: 0` is how thinking is switched OFF on a model that thinks by
+ * default, and a truthiness check would have thrown that away.
+ *
+ * **An empty object is absence too** (ت١/٢ item 5). `thinking: {}` — or
+ * `{ budget: undefined }` from a host that spreads what it does not have —
+ * names no field, so nothing goes on the wire: no `generationConfig`, and no
+ * `thinkingConfig: {}` that nobody asked for. The key is written only when
+ * it carries at least one value.
+ */
+function thinkingConfigOf(thinking) {
+    if (thinking === undefined)
+        return undefined;
+    const config = {
+        ...(thinking.budget !== undefined ? { thinkingBudget: thinking.budget } : {}),
+        ...(thinking.includeThoughts !== undefined
+            ? { includeThoughts: thinking.includeThoughts }
+            : {}),
+    };
+    return Object.keys(config).length > 0 ? config : undefined;
+}
 /**
  * `generateContentStream` read to the end, folded back into the response shape
  * the caller above expects.

package/dist/brain/ollama.js

@@ -2,6 +2,7 @@
  * Ollama Brain — local model via Ollama REST API.
  * No peer dependencies — plain HTTP fetch.
  */
+import { respondingModel } from "../core/types.js";
 import { withRetry } from "./retry.js";
 import { foldToolResults, toolParamsToJsonSchema, toWireMessage, useToolOrchestration, } from "./tool-context.js";
 import { accumulateOllama, consumeNdjson, } from "./streaming.js";
@@ -60,7 +61,7 @@ export function createOllamaBrain(opts) {
             });
             let data;
             if (input.onChunk) {
-                data = await withRetry(() => streamChat(post, input.onChunk, input.signal), input.signal ? { signal: input.signal } : {});
+                data = await withRetry((emitOnce) => streamChat(post, emitOnce(input.onChunk), input.signal), input.signal ? { signal: input.signal } : {});
             }
             else {
                 // Verbatim: the fetch is retried, the status check and the body read
@@ -88,13 +89,18 @@ export function createOllamaBrain(opts) {
             if (calls[0]?.name) {
                 const orchestration = useToolOrchestration(calls, 0.9);
                 if (orchestration)
-                    return { orchestration, ...usageBlock };
+                    return { orchestration, ...usageBlock, ...respondingModel(data) };
             }
             const text = data.message?.content ?? "";
             return {
                 generation: { response_text: text },
                 orchestration: { action: "respond", confidence: 0.85 },
                 ...usageBlock,
+                // Who answered — `/api/chat` echoes the served model at the top level,
+                // and on a local host that is the one place a swapped or re-tagged
+                // model shows itself. Streamed too: every NDJSON line repeats it and
+                // `accumulateOllama` keeps the last.
+                ...respondingModel(data),
             };
         },
     };

package/dist/brain/openai.js

@@ -2,6 +2,7 @@
  * OpenAI Brain — wraps the OpenAI Chat Completions API.
  * Peer dependency: openai >= 4.0.0
  */
+import { respondingModel } from "../core/types.js";
 import { computeCostUsd } from "./pricing.js";
 import { withRetry } from "./retry.js";
 import { foldToolResults, toolParamsToJsonSchema, toWireMessage, useToolOrchestration, } from "./tool-context.js";
@@ -56,7 +57,7 @@ export function createOpenAIBrain(opts) {
             // construction (`OpenAICompletion`), so there is one payload builder,
             // not two that must be kept in step.
             const response = input.onChunk
-                ? await withRetry(() => streamCompletion(client, body, input.onChunk, input.signal), input.signal ? { signal: input.signal } : {})
+                ? await withRetry((emitOnce) => streamCompletion(client, body, emitOnce(input.onChunk), input.signal), input.signal ? { signal: input.signal } : {})
                 : await withRetry(() => client.chat.completions.create(body, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {});
             const choice = response.choices[0];
             if (!choice)
@@ -93,13 +94,19 @@ export function createOpenAIBrain(opts) {
                 });
                 const orchestration = useToolOrchestration(calls, 0.9);
                 if (orchestration)
-                    return { orchestration, ...usageBlock };
+                    return { orchestration, ...usageBlock, ...respondingModel(response) };
             }
             const text = msg.content ?? "";
             return {
                 generation: { response_text: text },
                 orchestration: { action: "respond", confidence: 0.95 },
                 ...usageBlock,
+                // Who answered, off the completion itself — `gpt-4o-mini` asked for can
+                // come back as `gpt-4o-mini-2024-07-18`, and an override can make it
+                // something else entirely. `response` is the SAME shape either way, so
+                // this one line covers the streamed path too: the chunks carry `model`
+                // and `accumulateOpenAI` folds it in.
+                ...respondingModel(response),
             };
         },
     };

package/dist/brain/retry.d.ts

@@ -5,7 +5,96 @@
  * 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.
+ */
+/**
+ * Wrap a side-effecting sink so that only the attempt that first delivers
+ * through it may deliver at all — unless the sink declared `acceptResets`, in
+ * which case a later attempt may deliver after telling it to clear (ص٢/٢).
+ *
+ * Handed to the retried function; ignoring it is the pre-ب١/٢ behaviour, so no
+ * caller is broken by its existence. The signature stays generic on purpose:
+ * every call site today passes a chunk sink, but narrowing the parameter to
+ * `BrainChunk` would be a surface change for no gain — the reset branch reaches
+ * the chunk type through `isResetAware`, which is a runtime fact, not a guess.
  */
+export type SinkGate = <A extends unknown[]>(sink: (...args: A) => void) => (...args: A) => void;
 export interface RetryOpts {
     /** Total attempts including the first (default: 2 = one retry). */
     attempts?: number;
@@ -16,5 +105,12 @@ export interface RetryOpts {
 }
 /** True for errors worth one retry: 429, 5xx, or low-level network failures. */
 export declare function isTransientError(err: unknown): boolean;
-/** Run `fn`, retrying once (by default) on transient provider errors. */
-export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOpts): Promise<T>;
+/**
+ * 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 declare function withRetry<T>(fn: (emitOnce: SinkGate) => Promise<T>, opts?: RetryOpts): Promise<T>;