@msm-core/mini 0.5.2 → 0.9.0

package/dist/brain/streaming.js

@@ -0,0 +1,439 @@
+/**
+ * Streaming — the four providers' wire formats reduced to pure functions (ب١).
+ *
+ * **Why this file exists at all.** A streamed answer and a non-streamed answer
+ * are the same answer delivered twice over. The only way to be sure of that is
+ * to be able to *prove* it, and you cannot prove anything about code that only
+ * runs with a socket open and a key in the environment. So every provider's
+ * stream is split in two here:
+ *
+ *   - `…Delta(event)` — what text just arrived. Pure.
+ *   - `accumulate…(events)` — the events folded back into the SAME object shape
+ *     the provider's NON-streaming call returns. Pure.
+ *
+ * Feed `accumulate…` a fixed array of chunks in a test and you get an object
+ * that the brain's own post-call code — not a copy of it, the same lines —
+ * turns into a payload. That is what makes "the stream aggregates to what the
+ * non-stream returns" a checkable claim rather than a hope, and it is why the
+ * brains route BOTH paths into one `response` variable and one payload builder.
+ *
+ * **The read set is the contract.** Each `…Response` interface below is exactly
+ * the fields its brain reads off a provider response — no more. It is small on
+ * purpose: `id`, `created`, `finish_reason`, block ids and the rest are things
+ * a stream cannot reconstruct and no brain here consumes, so promising them
+ * would be a lie the compiler would happily keep.
+ *
+ * **Display, not truth (the governing limit of ب١).** Nothing in this file
+ * writes a log event, touches a fingerprint, or decides anything. Chunks are
+ * emitted for a human to look at; the payload the brain returns is the record.
+ *
+ * **Text only in v1.** Tool-call fragments are accumulated but never emitted —
+ * a half-arrived tool call is not something a consumer can do anything with,
+ * and `BrainChunk` says `{ text }` precisely so that stays true.
+ */
+/**
+ * Read a provider stream to the end, emitting text as it arrives, and return
+ * every raw event for the accumulator.
+ *
+ * **Abort stops the consumption, and no chunk follows it.** The check sits
+ * before the emit, not after, so an abort that lands between two events ends
+ * the stream silently — the loop's `runWithTimeout` has already rejected by
+ * then and whatever is returned here is discarded. What must never happen is a
+ * chunk arriving at a consumer that has been told the call is over.
+ *
+ * Buffering every event is deliberate: one model response is small, and the
+ * accumulator that has to see all of them is the same function the tests feed
+ * by hand. A fold that ran only live would be a second implementation.
+ */
+export async function consumeStream(source, deltaOf, sink, signal) {
+    const events = [];
+    for await (const event of source) {
+        if (signal?.aborted)
+            break;
+        events.push(event);
+        const text = deltaOf(event);
+        if (text)
+            sink({ text });
+    }
+    return events;
+}
+/**
+ * The text this chunk carries, or "" for a tool-call or usage-only chunk.
+ *
+ * **Why no fold here.** Two multiplicities are worth ruling out by name, since
+ * an extractor that silently reads "the first of several" is the exact bug this
+ * file was written to make impossible:
+ *
+ *   - WITHIN a choice, `delta.content` is one string, never a list. Nothing to
+ *     concatenate.
+ *   - ACROSS choices, `choices` IS an array — but only when a request sets
+ *     `n > 1`, which this brain never does. And if one ever did, several
+ *     choices are ALTERNATIVE answers, not pieces of one: summing them would
+ *     splice two different replies together. So `[0]` is right, and the rule
+ *     that actually matters is that `accumulateOpenAI` reads `[0]` too — what
+ *     the user watched is what the payload ends up holding, always.
+ */
+export function openAIDelta(chunk) {
+    const content = chunk.choices?.[0]?.delta?.content;
+    return typeof content === "string" ? content : "";
+}
+/**
+ * Fold OpenAI chunks into the completion they describe.
+ *
+ * Tool calls arrive as fragments keyed by `index`: the name once, the arguments
+ * in pieces to be concatenated into the JSON string the non-streamed API hands
+ * over whole. Keyed by index and re-sorted rather than pushed in arrival order,
+ * because the model interleaves parallel calls and the ORDER of calls is the
+ * one thing س٤ made load-bearing.
+ *
+ * `content` stays `null` when no text delta ever arrived — that is what the
+ * non-streaming API returns for a pure tool-call response, and the two spellings
+ * must not differ.
+ */
+export function accumulateOpenAI(chunks) {
+    let content = "";
+    let sawText = false;
+    let usage;
+    const fragments = new Map();
+    for (const chunk of chunks) {
+        if (chunk.usage)
+            usage = chunk.usage;
+        const delta = chunk.choices?.[0]?.delta;
+        if (!delta)
+            continue;
+        if (typeof delta.content === "string") {
+            content += delta.content;
+            sawText = true;
+        }
+        for (const call of delta.tool_calls ?? []) {
+            let slot = fragments.get(call.index);
+            if (!slot) {
+                slot = { name: "", args: "" };
+                fragments.set(call.index, slot);
+            }
+            if (call.function?.name)
+                slot.name += call.function.name;
+            if (call.function?.arguments)
+                slot.args += call.function.arguments;
+        }
+    }
+    const toolCalls = [...fragments.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([, slot]) => ({
+        function: { name: slot.name, arguments: slot.args },
+    }));
+    return {
+        choices: [
+            {
+                message: {
+                    content: sawText ? content : null,
+                    ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+                },
+            },
+        ],
+        ...(usage ? { usage } : {}),
+    };
+}
+function blockDelta(delta) {
+    return delta && typeof delta === "object" ? delta : {};
+}
+/**
+ * The text this event carries, or "" for anything else (thinking included).
+ *
+ * **Why no fold here.** One `content_block_delta` carries exactly one `delta`
+ * for exactly one `index` — the event type is `{ delta, index, type }`, not a
+ * list — so there is never more than one piece of text in an event and nothing
+ * to concatenate. Multiplicity in Claude's stream lives BETWEEN events, and
+ * that is `accumulateAnthropic`'s job, keyed by `index`.
+ */
+export function anthropicDelta(event) {
+    if (event.type !== "content_block_delta")
+        return "";
+    const delta = blockDelta(event.delta);
+    if (delta.type !== "text_delta")
+        return "";
+    return typeof delta.text === "string" ? delta.text : "";
+}
+/**
+ * Fold Messages-API events into the message they describe.
+ *
+ * Blocks are addressed by `index` and rebuilt in index order: `text_delta`
+ * pieces concatenate into the block's text, `input_json_delta` pieces
+ * concatenate into the JSON that non-streamed responses deliver already parsed
+ * as `input`.
+ *
+ * Usage arrives in two halves — `input_tokens` at `message_start`, the final
+ * `output_tokens` at `message_delta` — so both are taken where they appear,
+ * with the later `message_delta` count winning.
+ *
+ * A tool block that never receives a delta ends as `input: {}`, which is what
+ * a zero-argument tool call looks like unstreamed.
+ */
+export function accumulateAnthropic(events) {
+    const blocks = new Map();
+    let inputTokens = 0;
+    let outputTokens = 0;
+    for (const event of events) {
+        if (event.type === "message_start") {
+            const usage = event.message?.usage;
+            if (typeof usage?.input_tokens === "number")
+                inputTokens = usage.input_tokens;
+            if (typeof usage?.output_tokens === "number")
+                outputTokens = usage.output_tokens;
+            continue;
+        }
+        if (event.type === "message_delta") {
+            if (typeof event.usage?.output_tokens === "number") {
+                outputTokens = event.usage.output_tokens;
+            }
+            continue;
+        }
+        if (event.index === undefined)
+            continue;
+        if (event.type === "content_block_start") {
+            blocks.set(event.index, {
+                type: event.content_block?.type ?? "text",
+                text: "",
+                name: event.content_block?.name ?? "",
+                json: "",
+            });
+            continue;
+        }
+        if (event.type === "content_block_delta") {
+            const slot = blocks.get(event.index);
+            if (!slot)
+                continue;
+            const delta = blockDelta(event.delta);
+            if (delta.type === "text_delta" && typeof delta.text === "string") {
+                slot.text += delta.text;
+            }
+            else if (delta.type === "input_json_delta" &&
+                typeof delta.partial_json === "string") {
+                slot.json += delta.partial_json;
+            }
+        }
+    }
+    const content = [...blocks.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([, slot]) => slot.type === "tool_use"
+        ? { type: "tool_use", name: slot.name, input: parseJsonObject(slot.json) }
+        : { type: slot.type, text: slot.text });
+    return { content, usage: { input_tokens: inputTokens, output_tokens: outputTokens } };
+}
+/**
+ * The text this stream item carries, across ALL of its text parts.
+ *
+ * **This is the one extractor of the four that must fold**, and the fold is not
+ * defensive: Gemini's stream element carries an ARRAY of parts, and it really
+ * does put several — a sentence, a function call, a trailing sentence — into
+ * one candidate. Return `parts[0].text` and the watcher sees the first fragment
+ * of a paragraph while the payload holds all of it, which is the precise shape
+ * of "the stream lied to the user's face".
+ */
+export function geminiDelta(item) {
+    const parts = item.candidates?.[0]?.content?.parts ?? [];
+    let text = "";
+    for (const part of parts) {
+        if (typeof part.text === "string")
+            text += part.text;
+    }
+    return text;
+}
+/**
+ * Fold Gemini stream items into the response they describe.
+ *
+ * **The text parts MERGE into one.** This is the whole reason this function is
+ * not a flat concatenation of `parts` arrays: the brain finds its answer with
+ * `parts.find(p => "text" in p)`, so a response left as fifty little text parts
+ * would return the first syllable of the answer and drop the rest. One part in,
+ * one part out — the same shape `generateContent` returns.
+ *
+ * The merged text keeps the POSITION of the first text part it saw, so a
+ * response that opened with a function call still reads in emitted order.
+ * (Order between text and calls does not reach the payload — the brain collects
+ * calls by filter and text by find — but a shape that reorders parts for no
+ * reason is a shape that will eventually be believed.)
+ *
+ * Usage is cumulative in Gemini's stream: the last item that carries it wins.
+ */
+export function accumulateGemini(items) {
+    const parts = [];
+    let textSlot = -1;
+    let usage;
+    for (const item of items) {
+        if (item.usageMetadata)
+            usage = item.usageMetadata;
+        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 };
+                }
+            }
+            else if (part.functionCall) {
+                parts.push({ functionCall: part.functionCall });
+            }
+        }
+    }
+    return {
+        candidates: [{ content: { parts } }],
+        ...(usage ? { usageMetadata: usage } : {}),
+    };
+}
+/**
+ * The text this line carries.
+ *
+ * **Why no fold here.** One NDJSON line carries one `message`, and that message
+ * carries one `content` string — neither is a list, so there is nothing to
+ * concatenate within a line. Ollama's multiplicity is one token per LINE, which
+ * is `accumulateOllama`'s job.
+ */
+export function ollamaDelta(line) {
+    return typeof line.message?.content === "string" ? line.message.content : "";
+}
+/**
+ * Split whatever has arrived into whole NDJSON lines plus the leftover.
+ *
+ * Pure, and separate from the reader, because the bug this prevents is invisible
+ * in a happy-path test: a chunk boundary can fall anywhere, including the middle
+ * of a JSON object, and a splitter that forgets `rest` silently drops the token
+ * that straddled the seam. Blank lines are dropped; the trailing fragment is
+ * always handed back to be prefixed onto the next read.
+ */
+export function splitNdjsonFrame(buffer) {
+    const parts = buffer.split("\n");
+    const rest = parts.pop() ?? "";
+    return {
+        lines: parts.map((line) => line.trim()).filter((line) => line.length > 0),
+        rest,
+    };
+}
+/**
+ * Fold NDJSON lines into the single response `stream: false` would return.
+ *
+ * Ollama streams content token by token, but hands over tool calls whole (with
+ * `arguments` already an object, not a JSON string) — so calls are collected,
+ * never concatenated. Counts arrive on the final line; last one wins.
+ */
+export function accumulateOllama(lines) {
+    let content = "";
+    const toolCalls = [];
+    let promptEvalCount;
+    let evalCount;
+    for (const line of lines) {
+        if (typeof line.message?.content === "string")
+            content += line.message.content;
+        for (const call of line.message?.tool_calls ?? [])
+            toolCalls.push(call);
+        if (typeof line.prompt_eval_count === "number") {
+            promptEvalCount = line.prompt_eval_count;
+        }
+        if (typeof line.eval_count === "number")
+            evalCount = line.eval_count;
+    }
+    return {
+        message: {
+            content,
+            ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+        },
+        ...(promptEvalCount !== undefined ? { prompt_eval_count: promptEvalCount } : {}),
+        ...(evalCount !== undefined ? { eval_count: evalCount } : {}),
+    };
+}
+/**
+ * Read an NDJSON body to the end, emitting text as it arrives.
+ *
+ * The Ollama brain owns no SDK, so this is the equivalent of `consumeStream`
+ * for a raw `fetch` body: decode, split on newlines, parse, emit, keep the
+ * remainder. A line that will not parse is skipped rather than thrown — a
+ * local server that emits a stray keep-alive should not fail a run — and the
+ * abort check sits before the emit for the same reason it does upstream.
+ */
+export async function consumeNdjson(body, sink, signal) {
+    const decoder = new TextDecoder();
+    const lines = [];
+    let buffer = "";
+    const take = (raw) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        lines.push(parsed);
+        const text = ollamaDelta(parsed);
+        if (text)
+            sink({ text });
+    };
+    for await (const bytes of toAsyncIterable(body)) {
+        if (signal?.aborted)
+            break;
+        buffer += decoder.decode(bytes, { stream: true });
+        const frame = splitNdjsonFrame(buffer);
+        buffer = frame.rest;
+        for (const line of frame.lines) {
+            if (signal?.aborted)
+                break;
+            take(line);
+        }
+    }
+    const tail = buffer.trim();
+    if (tail && !signal?.aborted)
+        take(tail);
+    return lines;
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * A `ReadableStream` is async-iterable in Node 18+ and in undici, but the type
+ * only says so on some lib targets. One narrowing here keeps the branch out of
+ * the reader above.
+ */
+function toAsyncIterable(body) {
+    if (Symbol.asyncIterator in body) {
+        return body;
+    }
+    const reader = body.getReader();
+    return {
+        async *[Symbol.asyncIterator]() {
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        return;
+                    if (value)
+                        yield value;
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        },
+    };
+}
+/**
+ * Concatenated `input_json_delta` fragments back into the object the
+ * non-streaming API returns.
+ *
+ * Empty means "no arguments" (`{}`), which is a real tool call. Unparseable
+ * means the model produced broken JSON — the same condition the OpenAI brain
+ * already meets with `{}` and a downstream validation failure, so it is met the
+ * same way here: the call survives to be rejected on its merits instead of
+ * vanishing from the step.
+ */
+function parseJsonObject(json) {
+    if (!json)
+        return {};
+    try {
+        const parsed = JSON.parse(json);
+        return parsed && typeof parsed === "object"
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/brain/tool-context.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared brain helpers — the two things EVERY provider must do identically so
+ * Shared brain helpers — the things EVERY provider must do identically so
  * tool-using agents behave the same across OpenAI / Anthropic / Gemini / Ollama.
  * Previously each brain hand-rolled these (or skipped them), which is why the
  * Anthropic and Ollama paths regressed (audit H1/H2):
@@ -13,8 +13,17 @@
  *  2. toolParamsToJsonSchema() — map a tool's ToolParameter record to a JSON
  *     Schema object INCLUDING `enum`. The Anthropic brain dropped `enum`, so an
  *     enum-constrained parameter was silently unconstrained there.
+ *
+ *  3. useToolOrchestration() — build the `use_tool` payload from the N calls a
+ *     model emitted. One function, not four, because the covenant it carries
+ *     ("`tool_name`/`tool_params` are ALWAYS the first call") is exactly the kind
+ *     of rule that survives in three copies and quietly dies in the fourth.
+ *
+ *  4. toWireMessage() — the declared representation of the two DERIVED tool
+ *     roles. See the block above it: this is a wire contract, not a formatting
+ *     preference.
  */
-import type { ToolParameter, ToolResult } from "../core/types.js";
+import type { BrainOrchestration, BrainToolCall, Message, ToolParameter, ToolResult } from "../core/types.js";
 /**
  * Fold prior-iteration tool results into the user turn. Returns `raw` unchanged
  * when there are none, so it is safe to call on the first iteration.
@@ -38,3 +47,42 @@ export interface JsonSchemaObject {
  * from this shape; the property/required/enum semantics stay identical.
  */
 export declare function toolParamsToJsonSchema(parameters: Record<string, ToolParameter>): JsonSchemaObject;
+/**
+ * Build the `use_tool` orchestration for the N calls a model emitted in ONE
+ * response.
+ *
+ * `tool_name` / `tool_params` are filled from `calls[0]` unconditionally. That
+ * is the whole backward-compatibility contract in one line, and it lives here —
+ * in one function the four brains call — rather than as four copies of the same
+ * two assignments, because four copies is how three stay right and one drifts
+ * (paid for once already: Anthropic dropped `enum`, Ollama dropped `tools`).
+ *
+ * Returns `undefined` for an empty list, so a provider response with no usable
+ * call falls through to its text path exactly as before.
+ */
+export declare function useToolOrchestration(calls: readonly BrainToolCall[], confidence: number): BrainOrchestration | undefined;
+/** Marks a derived tool CALL. Part of the wire contract — changing it is a change of format. */
+export declare const TOOL_CALL_TAG = "tool_call";
+/** Marks a derived tool RESULT. Part of the wire contract — changing it is a change of format. */
+export declare const TOOL_RESULT_TAG = "tool_result";
+export interface WireMessage {
+    /**
+     * The role handed to the provider. Only two, because only two are legal
+     * everywhere: Gemini renames `assistant` to `model`, and no provider accepts
+     * a bare `tool` turn without its native pairing.
+     */
+    role: "user" | "assistant";
+    content: string;
+    /**
+     * True when this message is a DERIVED tool role and its content carries a tag.
+     * Adapters that pass ordinary roles through untouched (Ollama) branch on this
+     * so nothing but the two tool roles changes shape.
+     */
+    tagged: boolean;
+}
+/**
+ * Render one history message for the wire. Ordinary `user`/`assistant` messages
+ * come back exactly as they went in (same role mapping every brain already
+ * applied); the two derived tool roles come back tagged.
+ */
+export declare function toWireMessage(m: Message): WireMessage;

package/dist/brain/tool-context.js

@@ -35,3 +35,91 @@ export function toolParamsToJsonSchema(parameters) {
             .map(([k]) => k),
     };
 }
+/**
+ * Build the `use_tool` orchestration for the N calls a model emitted in ONE
+ * response.
+ *
+ * `tool_name` / `tool_params` are filled from `calls[0]` unconditionally. That
+ * is the whole backward-compatibility contract in one line, and it lives here —
+ * in one function the four brains call — rather than as four copies of the same
+ * two assignments, because four copies is how three stay right and one drifts
+ * (paid for once already: Anthropic dropped `enum`, Ollama dropped `tools`).
+ *
+ * Returns `undefined` for an empty list, so a provider response with no usable
+ * call falls through to its text path exactly as before.
+ */
+export function useToolOrchestration(calls, confidence) {
+    const first = calls[0];
+    if (!first)
+        return undefined;
+    return {
+        action: "use_tool",
+        confidence,
+        tool_name: first.name,
+        tool_params: first.params,
+        tool_calls: calls.map((c) => ({ name: c.name, params: c.params })),
+    };
+}
+// ─── The derived tool roles on the wire (س٤ §7) ──────────────────────────────
+//
+// `deriveMessages` projects a session log into a conversation that contains two
+// roles the history array never held: an `assistant` message that IS a tool call
+// (it carries `toolName`/`toolCallId`), and a `tool` message that is its result.
+//
+// Every provider adapter used to flatten both into a bare `user` message. That
+// makes the model read its own tool call, and the tool's answer, as things the
+// USER said — a false transcript, and the falser the more tools a step uses.
+//
+// The minimum honest fix, and the one declared here, is a **deterministic
+// textual tag**: the two derived roles keep provider-legal roles but arrive
+// visibly marked, so the model can tell a tool round-trip from human speech.
+//
+//   a tool call    →  `[tool_call:<callId>] <name>({…})`      role: assistant
+//   a tool result  →  `[tool_result:<callId>] <name> <json>`  role: user
+//
+// Identical text across all four providers; only the role name is translated
+// (Gemini says `model` where the others say `assistant`). No clock, no
+// randomness, no provider branching in the content — the same message always
+// renders to the same bytes, which is what makes it replayable.
+//
+// `:<callId>` is omitted when the message carries none, so a legacy `role:
+// "tool"` entry from some other store still renders deterministically.
+//
+// **What this is NOT**: the provider-native representation (Anthropic's
+// `tool_use`/`tool_result` blocks, OpenAI's `role: "tool"` + `tool_call_id`,
+// Gemini's `functionCall`/`functionResponse` parts). That is a separate,
+// larger contract — it changes what the provider validates, not just what the
+// model reads — and it is deliberately NOT done here.
+/** Marks a derived tool CALL. Part of the wire contract — changing it is a change of format. */
+export const TOOL_CALL_TAG = "tool_call";
+/** Marks a derived tool RESULT. Part of the wire contract — changing it is a change of format. */
+export const TOOL_RESULT_TAG = "tool_result";
+/**
+ * Render one history message for the wire. Ordinary `user`/`assistant` messages
+ * come back exactly as they went in (same role mapping every brain already
+ * applied); the two derived tool roles come back tagged.
+ */
+export function toWireMessage(m) {
+    const id = m.toolCallId ? `:${m.toolCallId}` : "";
+    const name = m.toolName ?? "unknown";
+    if (m.role === "tool") {
+        return {
+            role: "user",
+            content: `[${TOOL_RESULT_TAG}${id}] ${name} ${m.content}`,
+            tagged: true,
+        };
+    }
+    if (m.role === "assistant" &&
+        (m.toolCallId !== undefined || m.toolName !== undefined)) {
+        return {
+            role: "assistant",
+            content: `[${TOOL_CALL_TAG}${id}] ${m.content}`,
+            tagged: true,
+        };
+    }
+    return {
+        role: m.role === "assistant" ? "assistant" : "user",
+        content: m.content,
+        tagged: false,
+    };
+}

package/dist/bridge/pipeline.js

@@ -14,6 +14,7 @@
  *
  * The pipeline is duck-typed — no direct import of @msm-core/pipeline.
  */
+import { BRAIN_ACTIONS } from "../core/types.js";
 // ─── Adapter ──────────────────────────────────────────────────
 /**
  * Wrap an @msm-core/pipeline as a Brain for @msm-core/mini.
@@ -57,14 +58,16 @@ export function wrapPipeline(pipeline, name = "pipeline") {
                     : {}),
             });
             const brain = result.payload.brain;
-            // Normalise action — pipeline may return arbitrary strings; mini only knows these
-            const VALID_ACTIONS = new Set([
-                "use_tool",
-                "respond",
-                "clarify",
-                "escalate",
-                "delegate",
-            ]);
+            // Normalise action — a duck-typed pipeline may return any string, and
+            // mini dispatches on four. The set is built FROM `BRAIN_ACTIONS` and is
+            // no longer a second hand-written copy of it (ر٢): a copy is how the
+            // union and this list came to disagree about a fifth action that the loop
+            // never dispatched on, and how that disagreement went unnoticed.
+            //
+            // The fallback is unchanged: an unrecognised string becomes `respond`,
+            // which is also what the loop itself does with one that arrives past this
+            // point. Two layers, one rule.
+            const VALID_ACTIONS = new Set(BRAIN_ACTIONS);
             const rawAction = brain?.action ?? "respond";
             const action = VALID_ACTIONS.has(rawAction)
                 ? rawAction

package/dist/core/context-builder.d.ts

@@ -17,6 +17,17 @@ export interface ContextBudget {
     /** Max history messages to include (default: 20) */
     maxHistoryMessages: number;
 }
+/**
+ * The budget `buildContext` applies when a caller does not pass one — which is
+ * every call the loop makes.
+ *
+ * Exported because the session-log invariant has to reproduce the *exact* trim
+ * chain the request went through in order to compare what was sent against what
+ * the log derives. A private copy of `20` in `loop.ts` would be a second source
+ * of truth that drifts the day this one is tuned, and the invariant would then
+ * fail on a difference that is not a difference.
+ */
+export declare const DEFAULT_BUDGET: ContextBudget;
 /**
  * Build the full system context string for the brain.
  * Enforces token budget by truncating memories from the bottom.

package/dist/core/context-builder.js

@@ -10,7 +10,17 @@
  * Token budget is enforced by dropping lowest-priority memories first.
  * The agent never queries external stores — context arrives pre-assembled.
  */
-const DEFAULT_BUDGET = {
+/**
+ * The budget `buildContext` applies when a caller does not pass one — which is
+ * every call the loop makes.
+ *
+ * Exported because the session-log invariant has to reproduce the *exact* trim
+ * chain the request went through in order to compare what was sent against what
+ * the log derives. A private copy of `20` in `loop.ts` would be a second source
+ * of truth that drifts the day this one is tuned, and the invariant would then
+ * fail on a difference that is not a difference.
+ */
+export const DEFAULT_BUDGET = {
     maxTokens: 32_000,
     maxHistoryMessages: 20,
 };

package/dist/core/hooks.d.ts

@@ -9,4 +9,14 @@ export declare function fireIteration(hooks: AgentHooks | undefined, state: RunS
 export declare function fireSectionComplete(hooks: AgentHooks | undefined, sessionId: string, sectionName: string, sectionIndex: number, totalSections: number): void;
 export declare function fireToolCall(hooks: AgentHooks | undefined, sessionId: string, result: ToolResult, iteration: number, cached: boolean, durationMs: number): void;
 export declare function fireGuard(hooks: AgentHooks | undefined, sessionId: string, signal: GuardSignal, iteration: number): void;
+/**
+ * One streamed piece of model text (ب١).
+ *
+ * Same shape as its siblings, and the same contract: `safely` swallows a
+ * throwing hook. That matters more here than anywhere else — this one fires
+ * dozens of times per step, in the middle of reading a provider stream, and a
+ * consumer whose SSE socket closed mid-answer must not take the run down with
+ * it. A failed display is a failed display, not a failed run.
+ */
+export declare function fireChunk(hooks: AgentHooks | undefined, sessionId: string, iteration: number, text: string): void;
 export declare function fireFatalError(hooks: AgentHooks | undefined, error: Error, sessionId: string): void;