@msm-core/mini 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -12,6 +12,91 @@ Follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.15.0] — 2026-09-13
+
+Session ت١ (tadween chapter, item 1). Thinking is separated from the answer,
+and text parts are joined — on both paths, for Gemini and Anthropic alike.
+Everything here is additive; a composition that passes no new option gets
+yesterday's behavior, byte for byte.
+
+### Fixed
+
+- **Gemini: the first text part was the whole answer.** The brain read its
+  reply with `parts.find(text)`, so a candidate of several text parts returned
+  the first and dropped the rest — and with thinking enabled the first part
+  IS the reasoning, so the user read the model's notes instead of its reply.
+  Now every text part NOT tagged `thought: true` is joined in emitted order
+  with no separator; tagged parts are joined separately and never enter the
+  answer. Untagged prose is kept as written: the loop drops what the provider
+  tagged and keeps what it did not.
+- **Gemini streamed: thinking parts leaked into the merged answer.**
+  `accumulateGemini` folded every text part — tagged or not — into one slot.
+  It now keeps two (answer and thinking, each tagged as it arrived), and
+  `geminiDelta` skips tagged parts, so what an `onChunk` watcher hears stays a
+  prefix of the answer the payload finally carries (the ب١ covenant). The
+  brain decides text-versus-thinking on the folded shape with the same lines
+  it uses unstreamed.
+- **Anthropic: the first text block was the whole answer** (measured under
+  the same rule, item 8). Thinking blocks were already excluded by their
+  type; every `text` block is now joined in order, and a `thinking` block's
+  body goes to `thoughts` (unstreamed — the streamed fold does not carry it,
+  and this brain does not request thinking).
+
+### Added
+
+- `createGeminiBrain({ thinking?: { budget?, includeThoughts? } })` →
+  `generationConfig.thinkingConfig = { thinkingBudget, includeThoughts }`,
+  each field only when given, and the whole key only when the option is
+  present with a value (`thinking: undefined` from a JavaScript host is
+  absence). `budget: 0` is a value and switches thinking off. Without the
+  option the request carries no `generationConfig` key at all — guarded by a
+  before/after snapshot of the request. The option type is exported as
+  `GeminiBrainOptions`. Note: `@google/generative-ai` 0.24.1 (installed, and
+  the registry's newest as of 2026-09-13) does not declare `thinkingConfig`;
+  it serializes the request verbatim, so the field reaches the wire.
+- `BrainPayload.thoughts?: string` — the model's reasoning for that call,
+  joined, absent when there was none (no key, never `""`). Filled by the
+  Gemini and Anthropic brains; a custom brain may fill it the same way.
+- `LoopOutcome.thoughts?: string` — the LAST step's `thoughts`, at every exit
+  that takes its `text` from a payload (final answer, forced finalize,
+  force-respond/escalate). Absent otherwise. **Not written to the session
+  log**: the model never sees its own thinking again, so the invariant "what
+  the model sees is recorded" does not reach it — auditing it as an event is
+  raised to management, not decided here.
+  - **`thoughts` is ungated audit material — do not hand it to an end user
+    without the host's own filter.** The output gate validates `text` and
+    never reads `thoughts`. When the gate BLOCKS the answer (`type:
+    "suppressed"`) the outcome carries no `thoughts` either — what could not
+    go out as an answer does not go out as notes. On every other verdict
+    (`release`, `review`, no validator, or a gate that never ran because the
+    text was empty) `thoughts` passes exactly as the model wrote it.
+  - **Only with text the model wrote.** On a guard exit that falls back to
+    the canned "I was unable to complete…" line, `thoughts` is absent — the
+    thinking accompanies the answer it produced, never a sentence the model
+    did not write.
+  - **Reaches the `replay` tape.** `createRecordingBrain` records the whole
+    payload, `thoughts` included, like any other field; the `redact` option
+    of `createRecordingBrain` is where a host hides it (and replays with the
+    same redactor).
+- `## Brain` reads `thinking.budget` and `thinking.includeThoughts` (flat
+  dotted keys) into `AgentDefinition.brain.thinking?: { budget?, includeThoughts? }`
+  — now an explicit field — and `buildBrain` hands it to `createGeminiBrain`
+  **after checking its shape**: an object; `budget` a finite number ≥ 0 when
+  given; `includeThoughts` a boolean when given. A value that does not fit is
+  a **named error** (from the parser for text, from `buildBrain` for a
+  hand-built definition), never a silent default. Neither key written → no
+  `thinking` on the definition and no `generationConfig` on the wire. Only the
+  Gemini brain consumes the key in this release. (`## Brain` alone grew the
+  dotted grammar; other sections parse exactly as before.)
+- `thinking: {}` — and an object whose fields are all `undefined` — is
+  absence: no `generationConfig` on the wire, no `thinkingConfig: {}`.
+- Guards: `tests/gemini-thoughts.test.ts` (36 tests) and
+  `tests/brain-thinking-definition.test.ts` (14 tests) — each rule above, each
+  control named as such; the rule guards were shown red by deliberate breaks
+  (ten breaks over the two rounds, 21 of the 26 new tests reddened by name; the
+  rest are controls) and restored by fingerprint; the loop's three exit sites
+  guarded one by one.
+
 ## [0.14.0] — 2026-09-01
 
 Session ص٤. The Redis-mandatory era ends.

package/README.md

@@ -150,6 +150,60 @@ const outcome = await agent.handle({
 
 `buildBrain(definition)` reads the `## Brain` section of an `AgentDefinition` and returns the correct brain automatically.
 
+### Thinking (Gemini) — `thinking`
+
+Gemini 2.5+ models reason before they answer. Opt in per brain, and the
+reasoning comes back **separated** from the reply rather than inside it:
+
+```typescript
+const brain = createGeminiBrain({
+  model: "gemini-2.5-flash",
+  thinking: { budget: 1024, includeThoughts: false },
+});
+```
+
+Or from the definition file — the same two fields, written flat under
+`## Brain`, reach the brain through `buildBrain`:
+
+```markdown
+## Brain
+provider: gemini
+model: gemini-2.5-flash
+thinking.budget: 1024
+thinking.includeThoughts: false
+```
+
+- `budget` → `generationConfig.thinkingConfig.thinkingBudget`; `0` switches
+  thinking off on models that think by default.
+- `includeThoughts: true` asks for the reasoning back. Gemini tags those parts
+  `thought: true`; the brain joins them into `BrainPayload.thoughts` and the
+  loop copies the **last step's** value to `LoopOutcome.thoughts`. They never
+  enter `response_text`, are never streamed to `onChunk`, and are not written
+  to the session log.
+- **Without the option nothing changes**: the request carries no
+  `generationConfig` key at all, and the answer is built exactly as before.
+  An empty `thinking: {}` is the same as no option. A value that does not fit
+  (`thinking.budget: abc`, a negative budget, a non-boolean `includeThoughts`)
+  is a **named error** from the parser or from `buildBrain` — never a silent
+  default. Only the Gemini brain reads the key today.
+- **`thoughts` is ungated audit material — not for an end user without your
+  own filter.** The output gate (`validator`) checks `text` and never reads
+  `thoughts`. When it blocks the answer, `thoughts` is dropped with it; on
+  every other verdict — and when the gate never ran because the text was
+  empty — the reasoning passes exactly as the model wrote it. It rides only
+  with text the model wrote: a guard exit that falls back to the canned
+  "unable to complete" line carries no `thoughts`.
+- **It reaches the replay tape.** `@msm-core/replay`'s `createRecordingBrain`
+  records the whole payload, `thoughts` included; its `redact` option is where
+  to hide it (replay with the same redactor).
+
+Two rules hold regardless of the option, for Gemini and Anthropic alike
+(`0.15.0`): every text part/block is **joined in emitted order** (the first is
+no longer taken as the whole answer), and a part the provider **tagged** as
+thinking is kept out of the answer. Prose the provider did *not* tag is kept
+as written — the loop does not guess. A model that narrates its reasoning
+into the answer untagged is a prompt (or budget) matter, not a parsing one.
+
 ---
 
 ## HTTP Server

package/dist/brain/anthropic.js

@@ -82,23 +82,41 @@ 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`

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

@@ -9,6 +9,9 @@ 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) {
@@ -55,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
@@ -99,23 +108,46 @@ 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 } : {}),
+                    ...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
@@ -127,6 +159,33 @@ export function createGeminiBrain(opts) {
         },
     };
 }
+/**
+ * `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/streaming.d.ts

@@ -179,6 +179,16 @@ 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;
@@ -227,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 {
@@ -265,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;

package/dist/brain/streaming.js

@@ -266,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;
     }
@@ -275,24 +280,47 @@ 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;
@@ -302,13 +330,10 @@ export function accumulateGemini(items) {
             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 });

package/dist/core/loop.js

@@ -892,6 +892,7 @@ export function createAgent(config) {
                                     terminatedBy: hardSignal.type,
                                     toolCalls: toolResults,
                                     ...(gated.validation ? { validation: gated.validation } : {}),
+                                    ...thoughtsOf(finalPayload, gated.validation),
                                 });
                             }
                         }
@@ -900,8 +901,15 @@ export function createAgent(config) {
                         }
                     }
                     // force_respond / escalate → emit last text if available
-                    const lastText = state.lastPayload?.generation?.response_text ??
-                        state.lastPayload?.final_output?.text ??
+                    //
+                    // Two sources, told apart on purpose (ت١/٢ item 4): text the model
+                    // wrote in its last payload, or the canned line below when it wrote
+                    // none. The last payload's `thoughts` rides out ONLY with the former
+                    // — thinking accompanies the answer it produced, never a sentence
+                    // the model did not write.
+                    const lastWritten = state.lastPayload?.generation?.response_text ??
+                        state.lastPayload?.final_output?.text;
+                    const lastText = lastWritten ??
                         "I was unable to complete this request within the allowed limits. Please try a more specific question.";
                     const gatedLast = await gateAndLog(lastText, stepId);
                     const outcomeType = gatedLast.validation?.action === "block"
@@ -918,6 +926,9 @@ export function createAgent(config) {
                         terminatedBy: hardSignal.type,
                         toolCalls: toolResults,
                         ...(gatedLast.validation ? { validation: gatedLast.validation } : {}),
+                        ...(lastWritten !== undefined
+                            ? thoughtsOf(state.lastPayload, gatedLast.validation)
+                            : {}),
                     });
                 }
                 // ── Context build ─────────────────────────────────────
@@ -1080,6 +1091,9 @@ export function createAgent(config) {
                     text: finalText,
                     toolCalls: toolResults,
                     ...(validation ? { validation } : {}),
+                    // The last step's thinking rides out with its answer (ت١) — and only
+                    // here, not into the log: the model never sees it again.
+                    ...thoughtsOf(payload, validation),
                 });
             }
         }
@@ -1211,6 +1225,31 @@ async function runWithTimeout(brainCall, budgetMs, controller) {
             clearTimeout(timer);
     }
 }
+/**
+ * `{ thoughts }` off the payload the outcome's text came from, or `{}` (ت١).
+ *
+ * Spread into the outcome at every site that takes its `text` from a payload,
+ * and nowhere else — the thinking travels with the answer it belongs to. A
+ * conditional spread so an outcome without thinking has no key, not an
+ * `undefined` one that `toEqual` would wave through (تعميم المجلس ٦).
+ *
+ * **A blocked answer takes its thinking with it** (ت١/٢ item 3). The output
+ * gate validates the TEXT; it never reads `thoughts`. So when the gate says
+ * `block` — the outcome is `suppressed` and the text is the canned line — the
+ * reasoning that produced the blocked answer is dropped too: what the gate
+ * would not let out as an answer does not leave as notes. On every other
+ * verdict (`release`, `review`, or no validator, including a gate that never
+ * ran because the text was empty) `thoughts` passes UNGATED — it is audit
+ * material for the host, declared as such on `LoopOutcome.thoughts`, and not
+ * a second answer for an end user.
+ */
+function thoughtsOf(payload, validation) {
+    if (validation?.action === "block")
+        return {};
+    return typeof payload?.thoughts === "string" && payload.thoughts !== ""
+        ? { thoughts: payload.thoughts }
+        : {};
+}
 function makeOutcome(type, sessionId, taskId, state, started, extra = {}) {
     return {
         type,

package/dist/core/types.d.ts

@@ -360,6 +360,23 @@ export interface BrainPayload {
      * falsehood this field exists to stop telling.
      */
     model?: string;
+    /**
+     * The model's THINKING for this call, separated from its answer (ت١).
+     *
+     * Filled by a brain whose provider hands reasoning back tagged as such —
+     * Gemini's parts marked `thought: true`, Claude's `thinking` blocks — joined
+     * in emitted order and kept OUT of `generation.response_text`. Before this
+     * field the Gemini brain took the first text part as the answer, and with
+     * thinking on, the first text part was the reasoning: the user read the
+     * model's notes instead of its reply.
+     *
+     * **Optional, and absent means absent.** A call with no thinking carries no
+     * key at all — never `""` — so `"thoughts" in payload` is the honest test.
+     * The loop copies the LAST step's value to `LoopOutcome.thoughts` and does
+     * not write it to the session log: it is an output the model never sees
+     * again, so the rule "what the model sees is recorded" does not reach it.
+     */
+    thoughts?: string;
     [key: string]: unknown;
 }
 /**
@@ -480,6 +497,21 @@ export interface LoopOutcome {
     terminatedBy?: GuardSignalType;
     /** Output-gate result, when a validator is configured. */
     validation?: OutputValidation;
+    /**
+     * The thinking behind the answer, when the last model step reported any
+     * (`BrainPayload.thoughts`, ت١). Present only then — a run whose brain never
+     * separated thinking carries no key, exactly as before the field existed.
+     *
+     * **Ungated audit material — not for an end user without the host's
+     * filter** (ت١/٢ item 3). The output gate validates `text` and never reads
+     * this field. It is DROPPED when the gate blocks the answer (`type:
+     * "suppressed"`) — what could not go out as an answer does not go out as
+     * notes — and on every other verdict it passes as the model wrote it,
+     * including when the gate never ran because the text was empty. It also
+     * accompanies only text the model wrote: a guard exit that falls back to
+     * the canned "unable to complete" line carries no `thoughts`.
+     */
+    thoughts?: string;
     error?: string;
 }
 /**
@@ -1002,6 +1034,20 @@ export interface AgentDefinition {
         model: string;
         endpoint?: string;
         apiKey?: string;
+        /**
+         * Thinking, as `## Brain` spells it (ت١/٢): `thinking.budget` and
+         * `thinking.includeThoughts` — flat dotted keys, parsed into this object;
+         * neither key → no `thinking` at all. `buildBrain` hands it to
+         * `createGeminiBrain({ thinking })` after checking its shape (an object;
+         * `budget` a finite number ≥ 0 when given; `includeThoughts` a boolean
+         * when given — anything else is a named error at composition, not
+         * silence). Only the Gemini brain consumes it in this release; the other
+         * providers do not read the key. An empty object is absence.
+         */
+        thinking?: {
+            budget?: number;
+            includeThoughts?: boolean;
+        };
         [key: string]: unknown;
     };
     capabilities: string[];

package/dist/definition/parser.d.ts

@@ -3,6 +3,9 @@
  *
  * Supported sections: Persona, Brain, Capabilities, Limits, Sections
  * Stripped: Equipment, Skills, Hours, Memory rules (owned by the app layer)
+ *
+ * `## Brain` additionally reads `thinking.budget` and `thinking.includeThoughts`
+ * (flat dotted keys) into `brain.thinking` (ت١/٢).
  */
 import type { AgentDefinition } from "../core/types.js";
 /**

package/dist/definition/parser.js

@@ -3,6 +3,9 @@
  *
  * Supported sections: Persona, Brain, Capabilities, Limits, Sections
  * Stripped: Equipment, Skills, Hours, Memory rules (owned by the app layer)
+ *
+ * `## Brain` additionally reads `thinking.budget` and `thinking.includeThoughts`
+ * (flat dotted keys) into `brain.thinking` (ت١/٢).
  */
 import { readFileSync } from "fs";
 /**
@@ -34,6 +37,7 @@ function parseMd(md) {
     const personaName = extractKey(persona, "name") ?? extractKey(persona, "Name");
     const personaStyle = extractKey(persona, "style") ?? extractKey(persona, "Style");
     const brainEndpoint = brain["endpoint"] ?? brain["Endpoint"];
+    const brainThinking = parseBrainThinking(brain);
     const domain = meta["domain"] ?? meta["Domain"];
     const language = meta["language"] ?? meta["Language"];
     return {
@@ -50,6 +54,7 @@ function parseMd(md) {
                 "openai"),
             model: brain["model"] ?? brain["Model"] ?? "gpt-4o-mini",
             ...(brainEndpoint !== undefined ? { endpoint: brainEndpoint } : {}),
+            ...(brainThinking !== undefined ? { thinking: brainThinking } : {}),
         },
         capabilities,
         limits: {
@@ -107,8 +112,54 @@ function parseSection(lines, sectionName) {
     }
     return result;
 }
+/**
+ * `## Brain` accepts DOTTED keys (`thinking.budget: 1024`) on top of the plain
+ * ones every section accepts — that is how a nested option is written flat in
+ * a definition file (ت١/٢). The other sections keep the plain-key grammar; a
+ * dotted line there is ignored exactly as it was.
+ */
 function parseBrainSection(lines) {
-    return parseSection(lines, "Brain");
+    const result = {};
+    for (const line of getSectionLines(lines, "Brain")) {
+        const m = /^([A-Za-z]+(?:\.[A-Za-z]+)*)\s*:\s*(.+)$/.exec(line.trim());
+        if (m && m[1] && m[2])
+            result[m[1]] = m[2].trim();
+    }
+    return result;
+}
+/**
+ * `thinking.budget` / `thinking.includeThoughts` → `brain.thinking`, or
+ * `undefined` when neither key was written (then the definition has no
+ * `thinking` key at all, and `buildBrain` composes yesterday's brain).
+ *
+ * A value that does not parse is a NAMED error, not a fallback: `limits` may
+ * fall back to a default because a default exists, but there is no default
+ * thinking budget to fall back to, and a typo that silently switched the
+ * feature off is the silence this key was added to end. `budget` must be a
+ * finite number ≥ 0 (`0` is a value — thinking OFF); `includeThoughts` must
+ * be `true` or `false`.
+ */
+function parseBrainThinking(brain) {
+    const rawBudget = brain["thinking.budget"] ?? brain["Thinking.budget"];
+    const rawInclude = brain["thinking.includeThoughts"] ?? brain["Thinking.includeThoughts"];
+    if (rawBudget === undefined && rawInclude === undefined)
+        return undefined;
+    const thinking = {};
+    if (rawBudget !== undefined) {
+        const budget = Number(rawBudget);
+        if (!Number.isFinite(budget) || budget < 0) {
+            throw new Error(`msm-mini: ## Brain thinking.budget must be a finite number >= 0, got "${rawBudget}"`);
+        }
+        thinking.budget = budget;
+    }
+    if (rawInclude !== undefined) {
+        const lowered = rawInclude.toLowerCase();
+        if (lowered !== "true" && lowered !== "false") {
+            throw new Error(`msm-mini: ## Brain thinking.includeThoughts must be true or false, got "${rawInclude}"`);
+        }
+        thinking.includeThoughts = lowered === "true";
+    }
+    return thinking;
 }
 function parseListSection(lines, sectionName) {
     return getSectionLines(lines, sectionName)

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { createAgent } from "./core/loop.js";
 export { createBrainCompactor } from "./core/loop.js";
 export type { BrainCompactorOptions } from "./core/loop.js";
 export { createGeminiBrain } from "./brain/gemini.js";
+export type { GeminiBrainOptions } from "./brain/gemini.js";
 export { createOpenAIBrain } from "./brain/openai.js";
 export { createAnthropicBrain } from "./brain/anthropic.js";
 export { createOllamaBrain } from "./brain/ollama.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msm-core/mini",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Portable AI agent execution loop — brain-agnostic, zero embedded databases",
   "type": "module",
   "main": "./dist/index.js",