@msm-core/mini 0.9.0 → 0.15.0

package/dist/core/types.d.ts

@@ -142,7 +142,108 @@ export interface BrainRunInput {
  */
 export interface BrainChunk {
     text: string;
+    /**
+     * "Discard everything I have sent you; this text starts over." (ص٢/٢)
+     *
+     * Set on the FIRST chunk a retried attempt delivers, and on no other. ص١
+     * bought the display invariant — what reaches the reader is always a prefix
+     * of the payload — by muting the retry outright, which is honest but costs
+     * the tail of the answer: the display stops where the dead attempt stopped.
+     * This flag is what buys the same invariant WITHOUT that cost, because a
+     * reader who can clear what it drew has no prefix to contradict.
+     *
+     * **It never reaches a consumer that did not ask for it.** The sink has to
+     * declare itself with `acceptResets` (see `ResetAwareChunkSink`); everything
+     * else takes the ص١ path unchanged, byte for byte. That is deliberate: a
+     * consumer that appends chunks and ignores this field would render "The
+     * contract staThe contract states…" — the exact defect ب١/٢ opened — so the
+     * flag is delivered only where someone has said, in the type system, that
+     * they will act on it.
+     *
+     * `true` and absent are the only two states. There is no `reset: false`: a
+     * chunk either says "start over" or says nothing, and an optional literal
+     * makes the compiler enforce that rather than a code review.
+     */
+    reset?: true;
+}
+/**
+ * A chunk sink that has DECLARED it understands `BrainChunk.reset` (ص٢/٢).
+ *
+ * The declaration lives on the sink rather than in `BrainRunInput` or
+ * `RetryOpts`, and the reason is measured, not stylistic: the gate that decides
+ * to reset lives in `brain/retry.ts`, and the ONLY thing that crosses from a
+ * brain's input into that gate is the sink itself (`emitOnce(input.onChunk!)`).
+ * `RetryOpts` carries `signal` alone, and widening either it or `BrainRunInput`
+ * would mean editing all four brains to forward the new field. Attaching the
+ * declaration to the sink also makes it unmisplaceable: a consumer cannot
+ * declare reset support and then hand over a different callback.
+ *
+ * It also costs the replay harness nothing. `keyof BrainRunInput` does not
+ * change, so `InputKeysArePartitioned` in `@msm-core/replay` is untouched and
+ * no fingerprint moves — the ب١ precedent of a declared breach is not needed
+ * here, because there is no breach.
+ */
+export interface ResetAwareChunkSink {
+    (chunk: BrainChunk): void;
+    /** The declaration itself. Read by `isResetAware`, never by a brain. */
+    readonly acceptsReset: true;
+}
+/**
+ * Declare that a chunk sink can handle `reset` — the opt-in, and the only way
+ * a `reset` chunk is ever produced.
+ *
+ * The contract you are signing: **when a chunk arrives with `reset: true`,
+ * throw away everything you have rendered for this call and start from that
+ * chunk.** Do that and the text you hold when the call returns is exactly the
+ * payload, with nothing missing and nothing shown twice.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export declare function acceptResets(sink: (chunk: BrainChunk) => void): ResetAwareChunkSink;
+/** True for a sink that went through `acceptResets`. */
+export declare function isResetAware(sink: unknown): sink is ResetAwareChunkSink;
+/**
+ * An `AgentHooks.onChunk` that has DECLARED it understands `ChunkInfo.reset`
+ * (ص٣/٢) — the same opt-in as `ResetAwareChunkSink`, one layer out.
+ *
+ * ص٢ carried `reset` as far as a brain's chunk sink and stopped, because the
+ * loop's own sink drops everything but `text` into `fireChunk` and a declared
+ * loop sink would therefore have taken the flag and thrown it away — handing
+ * the hook consumer the duplicated display ب١/٢ exists to prevent. This type
+ * is the missing half: with it the loop can tell whether the person on the far
+ * end of `onChunk` will act on a reset, and it declares to the brain only when
+ * they will.
+ *
+ * **It is the same shape and the same marker as `ResetAwareChunkSink` on
+ * purpose.** A consumer who has learned the opt-in once has learned it in both
+ * places, and the loop's job stays a single question — did they declare? —
+ * rather than a translation between two conventions.
+ *
+ * Note that `AgentHooks.onChunk` needs no widening to accept this: a function
+ * carrying an extra property is already assignable to `(info: ChunkInfo) =>
+ * void`. The published signature of `AgentHooks` does not move.
+ */
+export interface ResetAwareChunkHook {
+    (info: ChunkInfo): void;
+    /** The declaration itself. Read by `isResetAwareHook`, never by a brain. */
+    readonly acceptsReset: true;
 }
+/**
+ * Declare that an `onChunk` hook can handle `ChunkInfo.reset` — the opt-in,
+ * and the only way a `reset` ever reaches a hook consumer.
+ *
+ * The contract you are signing: **when a `ChunkInfo` arrives with
+ * `reset: true`, throw away every chunk you have rendered for this step and
+ * start again from that one.** Do that and the text you hold at the end of the
+ * step is exactly the answer, with nothing missing and nothing shown twice.
+ * Ignore it and you would render the retried answer glued onto the truncated
+ * one — which is why the flag is delivered nowhere else.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export declare function acceptChunkResets(hook: (info: ChunkInfo) => void): ResetAwareChunkHook;
+/** True for an `onChunk` hook that went through `acceptChunkResets`. */
+export declare function isResetAwareHook(hook: unknown): hook is ResetAwareChunkHook;
 /**
  * One tool invocation a model asked for, in the model's own order.
  *
@@ -237,8 +338,73 @@ export interface BrainPayload {
         inputTokens?: number;
         outputTokens?: number;
     };
+    /**
+     * **Who actually answered** — the model as the PROVIDER's own reply named it.
+     *
+     * Not the model that was asked for. The two differ more often than they look
+     * like they should: a host swaps the brain under an agent definition at
+     * composition time (an `llmOverride`), a gateway routes a request elsewhere,
+     * or a provider resolves an alias to a dated snapshot. In every one of those
+     * cases the configured name is what the request *intended* and this is what
+     * the request *got*, and only the second can answer "which model wrote this?"
+     * about a reply already sent.
+     *
+     * The loop copies it into `model_response.data.model` in the session log,
+     * beside `model_request.data.model`, which keeps its own meaning — the
+     * requested/configured name. Two fields, two questions, neither guessing.
+     *
+     * **Optional, and absent means absent.** A brain that cannot know (a scripted
+     * one, or a provider whose reply does not name a model) leaves it off, and
+     * the log carries no `model` on that response rather than a plausible
+     * fabrication. Anything derived from the configured name would be exactly the
+     * 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;
 }
+/**
+ * The responder's name lifted off a raw provider reply — `{}` when it named none.
+ *
+ * Spread into a `BrainPayload` by all four bundled brains, so the reading exists
+ * once. Four copies of the same check in four files is four chances to drift,
+ * and the one difference between them (Gemini spells the field `modelVersion`;
+ * OpenAI, Anthropic and Ollama spell it `model`) is a fact about wire formats
+ * that belongs written down, not re-derived per file.
+ *
+ * **Why the parameter is `unknown`, and why there is no cast anyway.** The
+ * declared shape of each provider response in `brain/streaming.ts` is exactly
+ * the set of fields its brain reads — by design, stated there — and that set
+ * does not include the model name. A parameter typed `{ model?: unknown }`
+ * would therefore be rejected for every real argument: TypeScript's weak-type
+ * check refuses an object that shares no property with an all-optional target,
+ * which is precisely the situation here. So this takes what it is really given
+ * — an object off a wire — and narrows it at runtime with `typeof` and `in`.
+ * Nothing is asserted about it that has not just been tested.
+ *
+ * A reply that carries no name, or a non-string one, yields `{}`: the payload
+ * gets no `model` key, and the log records the absence honestly instead of
+ * inventing a name from the request.
+ */
+export declare function respondingModel(reply: unknown): {
+    model?: string;
+};
 /** The Brain interface — any model that implements this works with msm-mini */
 export interface Brain {
     name: string;
@@ -331,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;
 }
 /**
@@ -365,7 +546,9 @@ export interface SessionMetadata {
  *
  * The loop talks to this interface and never to a concrete store. Inject an
  * implementation via `AgentConfig.memory`; when it is omitted the loop builds
- * the bundled `RedisMemory` from `AgentConfig.redis` exactly as it always has.
+ * the bundled `RedisMemory` from `AgentConfig.redis` exactly as it always has —
+ * and when `redis` is omitted too, `createAgent` refuses the composition by
+ * name rather than failing on the first history read (ص٤).
  *
  * Six functions — the surface `RedisMemory` already had, at its current
  * signatures. Nothing is added speculatively: an append-only event log is a
@@ -381,6 +564,103 @@ export interface SessionStore {
     getDocumentState(sessionId: string): Promise<DocumentState | null>;
     setDocumentState(sessionId: string, state: DocumentState): Promise<void>;
 }
+/**
+ * The control bus PORT — out-of-band commands for a running session.
+ *
+ * One string per session, read once at the top of every loop iteration, before
+ * the model is called. The **command vocabulary is part of this contract**,
+ * because the loop interprets it (`checkGuards`, `RedisControlBus.disabledTool`):
+ *
+ *   - `null`                — no command; the run proceeds.
+ *   - `"kill"` / `"kill:{reason}"` — hard abort, `terminatedBy: "task_killed"`.
+ *   - `"pause"`             — hard abort, `terminatedBy: "tenant_paused"`.
+ *   - `"disabled:{tool}"`   — that one tool is refused for the step; its
+ *                             siblings run.
+ *
+ * A verb is matched on the part before the first `:`, so an unknown verb is
+ * simply not a command anyone acts on — an implementation may carry its own
+ * without breaking the loop.
+ */
+export interface ControlBusPort {
+    /** The current command for this session, or `null` when there is none. */
+    getCommand(sessionId: string): Promise<string | null>;
+    /** Write a kill command. `reason` rides along in the guard's message. */
+    kill(sessionId: string, reason?: string): Promise<void>;
+    pause(sessionId: string): Promise<void>;
+    /** Clear a pause. A `kill` is deliberately NOT cleared by this. */
+    resume(sessionId: string): Promise<void>;
+}
+/**
+ * A held session lock. `release()` is called on every exit path of the loop —
+ * normal, guard-terminated and error — and `extend()` is for a holder that
+ * outlives its own TTL.
+ *
+ * Declared here rather than in the Redis adapter for the same reason
+ * `SessionMetadata` moved in س١: it is part of the contract every lock
+ * implements, not a detail of one of them. `adapters/redis-lock.ts` re-exports
+ * it, so every existing import keeps working unchanged.
+ */
+export interface LockHandle {
+    release(): Promise<void>;
+    extend(ttlMs: number): Promise<boolean>;
+}
+/**
+ * The session run-lock PORT — one turn per session at a time.
+ *
+ * **Named `RunLockPort`, not `LockPort`, deliberately.** `@msm-core/jobs` has
+ * exported a `LockPort` since long before this existed and it is a different
+ * contract entirely (`acquire(key, ttlMs): Promise<boolean>` — no handle, no
+ * release); nisus imports it today. Two packages of one SDK exporting one name
+ * for two contracts is a collision a consumer pays for in aliases forever, and
+ * it costs nothing to avoid before the first publish. The name is also the
+ * truer one: what this guards is a session's RUN, one turn at a time.
+ *
+ * The loop acquires before it does anything with the session and releases on
+ * every way out. This is the port whose in-RAM implementation has to be a real
+ * mutex and not a stub: a lock that always says yes turns "two workers cannot
+ * enter the same session" into a comment, and the failure it prevents (two
+ * turns interleaving their writes into one log) is silent when it happens.
+ *
+ * The loop calls only `acquireWithRetry` — waiting for a busy session is the
+ * behaviour it wants, so that is the surface extracted. Implementations are
+ * free to expose a non-blocking `acquire` beside it; the port does not require
+ * one because nothing in the loop asks for it.
+ */
+export interface RunLockPort {
+    /**
+     * Acquire, retrying until `waitMs` elapses. Throws when it cannot.
+     *
+     * @param ttlMs         lifetime of the lock — the loop passes the effective
+     *                      turn timeout plus a safety margin, so a lock never
+     *                      expires under a run that is still going.
+     * @param waitMs        how long to keep trying (adapter default: 5000).
+     * @param retryInterval base delay between attempts (adapter default: 100).
+     */
+    acquireWithRetry(sessionId: string, ttlMs: number, waitMs?: number, retryInterval?: number): Promise<LockHandle>;
+}
+/**
+ * The tool-dedup PORT — idempotency for repeated tool calls within a session.
+ *
+ * Keyed by `(sessionId, hash)`, where the hash is `hashToolCall(name, args)`:
+ * a deterministic SHA-256 of the tool name and its key-sorted arguments. The
+ * hashing stays a pure function in `tools/dedup.ts` — it is not I/O and there
+ * is nothing to swap about it — so an implementation of this port is only ever
+ * asked to store and fetch by a key it is handed.
+ *
+ * **Only `ok` results are ever stored** (the executor's rule, not the port's):
+ * a failure is worth retrying, and caching one would freeze a transient outage
+ * into the session for the whole TTL.
+ */
+export interface DedupPort {
+    /** A previously stored result for this exact call, or `null`. */
+    check(sessionId: string, hash: string): Promise<ToolResult | null>;
+    /**
+     * Remember a result for `ttlSeconds`. An implementation with no notion of
+     * expiry may ignore the TTL — it is a hint about staleness, and the loop
+     * passes `redis.ttl.toolDedup ?? 300` for it.
+     */
+    store(sessionId: string, hash: string, result: ToolResult, ttlSeconds: number): Promise<void>;
+}
 /**
  * What a compactor decides when it decides to compact.
  *
@@ -480,7 +760,34 @@ export interface AgentConfig {
     /** Path to .md definition file or pre-parsed AgentDefinition object */
     definition: string | AgentDefinition;
     brain: Brain;
-    redis: RedisConfig;
+    /**
+     * Redis connection for the four ports Redis can back: session `memory`, the
+     * `controlBus`, the run `lock` and tool `dedup`.
+     *
+     * **Optional (ص٤) — and only because س٦ earned it.** While the trio was
+     * `new`-ed inside the loop, `redis` was load-bearing for every run and being
+     * required was simply true. س٦ made all four injectable and proved a whole
+     * turn runs without opening a connection; the field stayed required after
+     * that for no reason but the calendar, so a fully-injected caller had to hand
+     * over an object it never used. The rule that replaces the requirement:
+     *
+     *   - **Present** — nothing changes, for anyone. Every port that is not
+     *     injected is built from this exactly as it always was: same
+     *     `{prefix}:{companyId}:{agentType}` scoping, same key shapes, same TTLs,
+     *     same moment of connection. `{}` is *present*, not absent: it has
+     *     neither `url` nor `client`, so the first port that reaches for it
+     *     throws as it always has — which is precisely what makes it useful as a
+     *     test config that fails loudly if anything opens Redis.
+     *   - **Absent** — every one of the four ports MUST be injected, because
+     *     there is nothing left to fall back to. A composition that omits one
+     *     is rejected by `createAgent` with an error naming the missing field;
+     *     see the check at the top of `createAgent`.
+     *
+     * Absence is read from the value (`undefined`), not from the key, so a host
+     * that spreads an options object with `redis: undefined` in it gets the same
+     * named composition error rather than a crash inside a turn.
+     */
+    redis?: RedisConfig;
     /**
      * Optional session-memory port. When injected, the loop routes ALL history /
      * metadata / document-state access through it and never constructs a
@@ -488,10 +795,61 @@ export interface AgentConfig {
      * `redis` exactly as before — same prefix, same TTLs, same tenant scoping —
      * so every existing consumer is unaffected.
      *
-     * `redis` stays required either way: the control bus, the session lock and
-     * tool dedup are separate ports and still ride on it.
+     * Isolation is the injector's (س١ ruling 3): this port takes a `sessionId`
+     * and knows nothing of tenants. Whoever injects a store injects its tenant
+     * scoping with it.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤) — not a run that fails on its first history read.
      */
     memory?: SessionStore;
+    /**
+     * Optional **control-bus port** — kill / pause / disable-tool commands.
+     *
+     * Injected, the loop reads its commands and `agent.kill/pause/resume()` write
+     * through it. Omitted, the loop builds `RedisControlBus` from `redis` exactly
+     * as before: same `{prefix}:{companyId}:{agentType}` tenant scoping, same
+     * `:agent:control:{sessionId}` key, same 7-day TTL on a kill.
+     *
+     * Isolation is the injector's, as with `memory`. Note in particular that
+     * `agent.kill(sessionId, companyId, agentType)` computes a tenant-scoped
+     * prefix for the FALLBACK bus only — an injected bus receives the session id
+     * and nothing else, and must scope its own keys.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤).
+     */
+    controlBus?: ControlBusPort;
+    /**
+     * Optional **session-lock port** — one turn per session at a time.
+     *
+     * Omitted, the loop builds `RedisDistributedLock` from `redis` exactly as
+     * before (`SET NX PX` on `{prefix}:session:{id}:lock`, released by token).
+     *
+     * An injected lock must actually exclude, or it is not a lock. In-process
+     * (`InMemoryLock`) that means one process; across replicas it means a shared
+     * one. Isolation is the injector's here too: two tenants that share one
+     * injected lock share its key space, and a session id colliding across them
+     * will serialise turns that have nothing to do with each other.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤).
+     */
+    lock?: RunLockPort;
+    /**
+     * Optional **tool-dedup port** — idempotency for repeated tool calls.
+     *
+     * Omitted, the loop builds the Redis-backed dedup from `redis` exactly as
+     * before: `{prefix}:session:{id}:tools:dedup` as a hash, the call hash as the
+     * field, `EXPIRE` refreshed on every store.
+     *
+     * Isolation is the injector's: a dedup shared unscoped between tenants can
+     * serve one tenant's cached tool result to another's identical call.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤).
+     */
+    dedup?: DedupPort;
     /**
      * Optional session **event log** (`@msm-core/session`). Injecting it inverts
      * where conversation context comes from:
@@ -590,6 +948,25 @@ export interface ChunkInfo {
     /** The delta — not the running total. Concatenating every chunk of a step
      *  yields the text that step's payload carries. */
     text: string;
+    /**
+     * "Discard everything I have sent you for this step; it starts over." (ص٣/٢)
+     *
+     * The hook-side face of `BrainChunk.reset`. Set on the FIRST chunk a retried
+     * attempt delivers, and on no other, so a consumer that clears and restarts
+     * on it ends the step holding exactly the answer — no truncation from the
+     * attempt that died, no duplication from the one that succeeded.
+     *
+     * **It never reaches a consumer that did not ask for it.** The hook must go
+     * through `acceptChunkResets` (see `ResetAwareChunkHook`); for every other
+     * hook the loop hands the brain an undeclared sink, `brain/retry.ts` takes
+     * the ص١ mute path, and the object delivered here carries the same three
+     * keys it carried before this field existed — the key is not merely
+     * `undefined`, it is absent. That is deliberate: a consumer that appends
+     * chunks and ignores this field would render the answer twice over.
+     *
+     * `true` and absent are the only two states, as on `BrainChunk`.
+     */
+    reset?: true;
 }
 /**
  * Return value from onBeforeTool hook:
@@ -657,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/core/types.js

@@ -4,6 +4,63 @@
  * All contracts for the lite agent runtime. Brain-agnostic, zero embedded
  * databases. Application layer owns persistence; agent owns the loop.
  */
+/**
+ * Declare that a chunk sink can handle `reset` — the opt-in, and the only way
+ * a `reset` chunk is ever produced.
+ *
+ * The contract you are signing: **when a chunk arrives with `reset: true`,
+ * throw away everything you have rendered for this call and start from that
+ * chunk.** Do that and the text you hold when the call returns is exactly the
+ * payload, with nothing missing and nothing shown twice.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export function acceptResets(sink) {
+    const declared = (chunk) => {
+        sink(chunk);
+    };
+    return Object.assign(declared, { acceptsReset: true });
+}
+/**
+ * The declaration marker, read in ONE place (ص٣/٢).
+ *
+ * There are two public predicates over this marker — one for a brain's chunk
+ * sink, one for the `AgentHooks.onChunk` a person writes — and س١'s rule is
+ * that two lookalikes drift apart in silence. They share this body so there is
+ * nothing to drift: the marker `acceptResets` and `acceptChunkResets` stamp is
+ * the same marker, and it is recognised the same way or not at all.
+ */
+function declaresResets(value) {
+    return (typeof value === "function" &&
+        value.acceptsReset === true);
+}
+/** True for a sink that went through `acceptResets`. */
+export function isResetAware(sink) {
+    return declaresResets(sink);
+}
+/**
+ * Declare that an `onChunk` hook can handle `ChunkInfo.reset` — the opt-in,
+ * and the only way a `reset` ever reaches a hook consumer.
+ *
+ * The contract you are signing: **when a `ChunkInfo` arrives with
+ * `reset: true`, throw away every chunk you have rendered for this step and
+ * start again from that one.** Do that and the text you hold at the end of the
+ * step is exactly the answer, with nothing missing and nothing shown twice.
+ * Ignore it and you would render the retried answer glued onto the truncated
+ * one — which is why the flag is delivered nowhere else.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export function acceptChunkResets(hook) {
+    const declared = (info) => {
+        hook(info);
+    };
+    return Object.assign(declared, { acceptsReset: true });
+}
+/** True for an `onChunk` hook that went through `acceptChunkResets`. */
+export function isResetAwareHook(hook) {
+    return declaresResets(hook);
+}
 /**
  * Every action the loop DISPATCHES ON — declared as data, and the only list.
  *
@@ -44,3 +101,36 @@ export const BRAIN_ACTIONS = [
     "clarify",
     "escalate",
 ];
+/**
+ * The responder's name lifted off a raw provider reply — `{}` when it named none.
+ *
+ * Spread into a `BrainPayload` by all four bundled brains, so the reading exists
+ * once. Four copies of the same check in four files is four chances to drift,
+ * and the one difference between them (Gemini spells the field `modelVersion`;
+ * OpenAI, Anthropic and Ollama spell it `model`) is a fact about wire formats
+ * that belongs written down, not re-derived per file.
+ *
+ * **Why the parameter is `unknown`, and why there is no cast anyway.** The
+ * declared shape of each provider response in `brain/streaming.ts` is exactly
+ * the set of fields its brain reads — by design, stated there — and that set
+ * does not include the model name. A parameter typed `{ model?: unknown }`
+ * would therefore be rejected for every real argument: TypeScript's weak-type
+ * check refuses an object that shares no property with an all-optional target,
+ * which is precisely the situation here. So this takes what it is really given
+ * — an object off a wire — and narrows it at runtime with `typeof` and `in`.
+ * Nothing is asserted about it that has not just been tested.
+ *
+ * A reply that carries no name, or a non-string one, yields `{}`: the payload
+ * gets no `model` key, and the log records the absence honestly instead of
+ * inventing a name from the request.
+ */
+export function respondingModel(reply) {
+    if (typeof reply !== "object" || reply === null)
+        return {};
+    const named = "model" in reply
+        ? reply.model
+        : "modelVersion" in reply
+            ? reply.modelVersion
+            : undefined;
+    return typeof named === "string" && named.length > 0 ? { model: named } : {};
+}

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)