@msm-core/mini 0.5.2 → 0.9.0

package/dist/adapters/index.d.ts

@@ -8,5 +8,9 @@ export { RedisDistributedLock } from "./redis-lock.js";
 export type { LockHandle } from "./redis-lock.js";
 /** Correct single-node RedisLike for local / no-Redis / sovereign deploys + tests. */
 export { InMemoryRedis, createInMemoryRedis } from "./memory-redis.js";
+/** In-RAM SessionStore — the memory port with no Redis and no network. */
+export { InMemorySessionStore } from "./memory-store.js";
 /** The client shape RedisConfig.client expects — for wiring a custom client. */
 export type { RedisLike } from "./redis-types.js";
+/** The port `AgentConfig.memory` accepts — for writing a custom session store. */
+export type { SessionStore } from "../core/types.js";

package/dist/adapters/index.js

@@ -6,3 +6,5 @@ export { RedisControlBus } from "./redis-control.js";
 export { RedisDistributedLock } from "./redis-lock.js";
 /** Correct single-node RedisLike for local / no-Redis / sovereign deploys + tests. */
 export { InMemoryRedis, createInMemoryRedis } from "./memory-redis.js";
+/** In-RAM SessionStore — the memory port with no Redis and no network. */
+export { InMemorySessionStore } from "./memory-store.js";

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

@@ -0,0 +1,38 @@
+/**
+ * In-memory SessionStore — the memory port with no Redis and no network.
+ *
+ * The bundled counterpart to `RedisMemory`: a complete implementation of the
+ * six `SessionStore` functions, held in process memory. It exists because until
+ * now the loop built its store by hand from a Redis config, so a test — or a
+ * local / air-gapped deploy — could not run the loop without a live Redis for
+ * session memory.
+ *
+ * Fidelity to `RedisMemory` is deliberate, so swapping one for the other does
+ * not change loop behaviour:
+ *   - `getHistory` returns the LAST `limit` entries, oldest-first (`lrange -limit -1`).
+ *   - history is capped at `maxHistoryEntries` (default 500), oldest dropped
+ *     first — the same silent head-loss the Redis adapter has via `ltrim`.
+ *   - reads and writes are deep-copied, mirroring the JSON round-trip a real
+ *     store performs, so a caller holding a returned object can never mutate
+ *     what is stored (the loop does mutate the DocumentState it reads back).
+ *
+ * Scope: ONE process, no expiry. TTLs are a persistence concern; nothing here
+ * outlives the process, so nothing needs evicting. For multi-replica deploys
+ * and for durability across restarts, use `RedisMemory`.
+ */
+import type { DocumentState, Message, SessionMetadata, SessionStore } from "../core/types.js";
+export declare class InMemorySessionStore implements SessionStore {
+    private readonly sessions;
+    private readonly maxHistoryEntries;
+    constructor(opts?: {
+        /** Hard cap on stored history entries per session (default: 500). */
+        maxHistoryEntries?: number;
+    });
+    private slot;
+    appendHistory(sessionId: string, entry: Message): Promise<void>;
+    getHistory(sessionId: string, limit?: number): Promise<Message[]>;
+    getMetadata(sessionId: string): Promise<SessionMetadata | null>;
+    setMetadata(sessionId: string, meta: SessionMetadata): Promise<void>;
+    getDocumentState(sessionId: string): Promise<DocumentState | null>;
+    setDocumentState(sessionId: string, state: DocumentState): Promise<void>;
+}

package/dist/adapters/memory-store.js

@@ -0,0 +1,73 @@
+/**
+ * In-memory SessionStore — the memory port with no Redis and no network.
+ *
+ * The bundled counterpart to `RedisMemory`: a complete implementation of the
+ * six `SessionStore` functions, held in process memory. It exists because until
+ * now the loop built its store by hand from a Redis config, so a test — or a
+ * local / air-gapped deploy — could not run the loop without a live Redis for
+ * session memory.
+ *
+ * Fidelity to `RedisMemory` is deliberate, so swapping one for the other does
+ * not change loop behaviour:
+ *   - `getHistory` returns the LAST `limit` entries, oldest-first (`lrange -limit -1`).
+ *   - history is capped at `maxHistoryEntries` (default 500), oldest dropped
+ *     first — the same silent head-loss the Redis adapter has via `ltrim`.
+ *   - reads and writes are deep-copied, mirroring the JSON round-trip a real
+ *     store performs, so a caller holding a returned object can never mutate
+ *     what is stored (the loop does mutate the DocumentState it reads back).
+ *
+ * Scope: ONE process, no expiry. TTLs are a persistence concern; nothing here
+ * outlives the process, so nothing needs evicting. For multi-replica deploys
+ * and for durability across restarts, use `RedisMemory`.
+ */
+/** Deep copy through JSON — the same serialization boundary a real store has. */
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export class InMemorySessionStore {
+    sessions = new Map();
+    maxHistoryEntries;
+    constructor(opts = {}) {
+        this.maxHistoryEntries = opts.maxHistoryEntries ?? 500;
+    }
+    slot(sessionId) {
+        let slot = this.sessions.get(sessionId);
+        if (!slot) {
+            slot = { history: [], metadata: null, document: null };
+            this.sessions.set(sessionId, slot);
+        }
+        return slot;
+    }
+    // ─── History ──────────────────────────────────────────────
+    async appendHistory(sessionId, entry) {
+        const slot = this.slot(sessionId);
+        slot.history.push(clone(entry));
+        // Cap storage growth for chatty sessions, exactly as RedisMemory's ltrim does.
+        if (slot.history.length > this.maxHistoryEntries) {
+            slot.history.splice(0, slot.history.length - this.maxHistoryEntries);
+        }
+    }
+    async getHistory(sessionId, limit = 50) {
+        const history = this.sessions.get(sessionId)?.history ?? [];
+        // `lrange(key, -limit, -1)`: the tail of `limit` entries. A limit of 0 (or
+        // below) means "no tail window" and returns everything, as Redis does.
+        const start = limit > 0 ? Math.max(history.length - limit, 0) : 0;
+        return history.slice(start).map(clone);
+    }
+    // ─── Metadata ─────────────────────────────────────────────
+    async getMetadata(sessionId) {
+        const meta = this.sessions.get(sessionId)?.metadata;
+        return meta ? clone(meta) : null;
+    }
+    async setMetadata(sessionId, meta) {
+        this.slot(sessionId).metadata = clone(meta);
+    }
+    // ─── Document State (section tracker) ────────────────────
+    async getDocumentState(sessionId) {
+        const doc = this.sessions.get(sessionId)?.document;
+        return doc ? clone(doc) : null;
+    }
+    async setDocumentState(sessionId, state) {
+        this.slot(sessionId).document = clone(state);
+    }
+}

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

@@ -9,15 +9,20 @@
  *   {prefix}:session:{id}:metadata   JSON object, TTL 24h
  *   {prefix}:session:{id}:document   JSON object, TTL 4h
  */
-import type { Message, DocumentState } from "../core/types.js";
+import type { Message, DocumentState, SessionMetadata, SessionStore } from "../core/types.js";
 import type { RedisLike } from "./redis-types.js";
-export interface SessionMetadata {
-    iterationCount: number;
-    startedAt: number;
-    totalCostUsd: number;
-    status: "running" | "completed" | "failed" | "killed";
-}
-export declare class RedisMemory {
+/**
+ * `SessionMetadata` now lives in core/types.ts with the `SessionStore` port it
+ * belongs to. Re-exported here so `import { SessionMetadata } from
+ * "@msm-core/mini/adapters"` — and every existing deep import — keeps working.
+ */
+export type { SessionMetadata };
+/**
+ * The Redis implementation of the `SessionStore` port. The `implements` clause
+ * is load-bearing: it makes the compiler break on any future drift between this
+ * adapter and the port the loop programs against.
+ */
+export declare class RedisMemory implements SessionStore {
     private readonly redis;
     private readonly prefix;
     private readonly historyTtl;

package/dist/adapters/redis-memory.js

@@ -9,6 +9,11 @@
  *   {prefix}:session:{id}:metadata   JSON object, TTL 24h
  *   {prefix}:session:{id}:document   JSON object, TTL 4h
  */
+/**
+ * The Redis implementation of the `SessionStore` port. The `implements` clause
+ * is load-bearing: it makes the compiler break on any future drift between this
+ * adapter and the port the loop programs against.
+ */
 export class RedisMemory {
     redis;
     prefix;

package/dist/brain/anthropic.js

@@ -4,7 +4,8 @@
  */
 import { computeCostUsd } from "./pricing.js";
 import { withRetry } from "./retry.js";
-import { foldToolResults, toolParamsToJsonSchema } from "./tool-context.js";
+import { foldToolResults, toolParamsToJsonSchema, toWireMessage, useToolOrchestration, } from "./tool-context.js";
+import { accumulateAnthropic, anthropicDelta, consumeStream, } from "./streaming.js";
 export function createAnthropicBrain(opts) {
     // claude-3-5-sonnet-20241022 was retired (2025-10-28); claude-sonnet-4-6 is
     // its current drop-in replacement.
@@ -24,10 +25,13 @@ export function createAnthropicBrain(opts) {
             if (!apiKey)
                 throw new Error("msm-mini: ANTHROPIC_API_KEY not set");
             const client = new Anthropic({ apiKey });
-            const messages = input.history.map((m) => ({
-                role: m.role === "assistant" ? "assistant" : "user",
-                content: m.content,
-            }));
+            // Derived tool calls / tool results arrive TAGGED rather than flattened
+            // into anonymous `user` turns — see the wire contract in tool-context.ts.
+            // Claude read its own tool round-trips as the user's words before this.
+            const messages = input.history.map((m) => {
+                const wire = toWireMessage(m);
+                return { role: wire.role, content: wire.content };
+            });
             // Fold prior tool results into the current turn so Claude sees what its
             // tool calls returned (and is nudged to finalize) — without this it
             // re-emits use_tool every iteration until the guard cap (H1).
@@ -46,25 +50,39 @@ export function createAnthropicBrain(opts) {
                 system: input.system_context,
                 messages: messages,
             };
-            const response = await withRetry(() => client.messages.create(tools
+            const params = tools
                 ? {
                     ...baseParams,
                     tools: tools,
                 }
-                : baseParams, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {});
+                : baseParams;
+            // ── The one branch streaming adds ──────────────────────────────────
+            //
+            // No `onChunk`, no stream: the call below is the call this brain has
+            // always made, and every line after this block is untouched. Both paths
+            // land in `AnthropicMessage` — the fields this brain reads — so the
+            // payload is built once, from one shape.
+            const response = input.onChunk
+                ? await withRetry(() => streamMessage(client, params, input.onChunk, input.signal), input.signal ? { signal: input.signal } : {})
+                : await withRetry(() => client.messages.create(params, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {});
             const content = response.content;
             const inputTokens = response.usage.input_tokens;
             const outputTokens = response.usage.output_tokens;
             const costUsd = computeCostUsd(model, inputTokens, outputTokens);
-            // Tool use
-            const toolUseBlock = content.find((b) => b.type === "tool_use");
-            if (toolUseBlock && toolUseBlock.type === "tool_use") {
-                const orchestration = {
-                    action: "use_tool",
-                    confidence: 0.9,
-                    tool_name: toolUseBlock.name,
-                    tool_params: toolUseBlock.input,
-                };
+            // Tool use — EVERY `tool_use` block, in the order Claude emitted them.
+            // `.find()` kept the first and dropped the rest, and Claude emits parallel
+            // blocks routinely: each dropped block cost a full extra round-trip.
+            const calls = [];
+            for (const block of content) {
+                if (block.type !== "tool_use")
+                    continue;
+                calls.push({
+                    name: block.name ?? "",
+                    params: (block.input ?? {}),
+                });
+            }
+            const orchestration = useToolOrchestration(calls, 0.9);
+            if (orchestration) {
                 return {
                     orchestration,
                     usage: { inputTokens, outputTokens },
@@ -73,7 +91,7 @@ export function createAnthropicBrain(opts) {
             }
             // Text
             const textBlock = content.find((b) => b.type === "text");
-            const text = textBlock && textBlock.type === "text" ? textBlock.text : "";
+            const text = textBlock?.text ?? "";
             return {
                 generation: { response_text: text },
                 orchestration: { action: "respond", confidence: 0.95 },
@@ -83,3 +101,18 @@ export function createAnthropicBrain(opts) {
         },
     };
 }
+/**
+ * The same request with `stream: true`, read to the end, folded back into the
+ * message shape the caller above expects.
+ *
+ * Claude's stream is block-addressed rather than linear — `content_block_start`
+ * opens a block, deltas name its index, `content_block_stop` closes it — so the
+ * accumulator rebuilds blocks by index rather than by arrival. Text deltas are
+ * emitted; `input_json_delta` fragments of a tool call are not (v1 is text
+ * only), and thinking deltas are not text and are emitted by nobody.
+ */
+async function streamMessage(client, params, sink, signal) {
+    const stream = await client.messages.create({ ...params, stream: true }, signal ? { signal } : {});
+    const events = await consumeStream(stream, anthropicDelta, sink, signal);
+    return accumulateAnthropic(events);
+}

package/dist/brain/gemini.js

@@ -3,7 +3,8 @@
  * Peer dependency: @google/generative-ai >= 0.14.0
  */
 import { withRetry } from "./retry.js";
-import { foldToolResults } from "./tool-context.js";
+import { foldToolResults, toWireMessage, useToolOrchestration, } from "./tool-context.js";
+import { accumulateGemini, consumeStream, geminiDelta, } from "./streaming.js";
 import { computeCostUsd } from "./pricing.js";
 export function createGeminiBrain(opts) {
     const model = opts.model ?? "gemini-2.5-flash";
@@ -60,8 +61,15 @@ export function createGeminiBrain(opts) {
                     tools: tools,
                 }
                 : { systemInstruction: input.system_context, contents };
-            const result = await withRetry(() => geminiModel.generateContent(request, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {});
-            const response = result.response;
+            // ── The one branch streaming adds ──────────────────────────────────
+            //
+            // No `onChunk`, no stream: the call below is the call this brain has
+            // always made, and every line after this block is untouched. Both paths
+            // land in `GeminiResponse` — the fields this brain reads — so the payload
+            // is built once, from one shape.
+            const response = input.onChunk
+                ? await withRetry(() => streamContent(() => geminiModel.generateContentStream(request, input.signal ? { signal: input.signal } : {}), input.onChunk, input.signal), input.signal ? { signal: input.signal } : {})
+                : (await withRetry(() => geminiModel.generateContent(request, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {})).response;
             const parts = response?.candidates?.[0]?.content?.parts ?? [];
             // Token usage + cost — computed ONCE and returned on BOTH the tool-call and text
             // paths. Most iterations of an agentic run are tool calls, so omitting usage/cost
@@ -77,18 +85,21 @@ export function createGeminiBrain(opts) {
                 }
                 : undefined;
             const costUsd = computeCostUsd(model, inputTokens, outputTokens);
-            // Check for function call
-            const fnCallPart = parts.find((p) => "functionCall" in p && p.functionCall);
-            if (fnCallPart &&
-                "functionCall" in fnCallPart &&
-                fnCallPart.functionCall) {
-                const fc = fnCallPart.functionCall;
-                const orchestration = {
-                    action: "use_tool",
-                    confidence: 0.9,
-                    tool_name: fc.name,
-                    tool_params: fc.args,
-                };
+            // Function calls — EVERY `functionCall` part, in emitted order. Gemini
+            // returns parallel calls as several parts of one candidate; `.find()`
+            // kept the first and paid for the rest with extra round-trips.
+            const calls = [];
+            for (const part of parts) {
+                if (!("functionCall" in part) || !part.functionCall)
+                    continue;
+                const fc = part.functionCall;
+                calls.push({
+                    name: fc.name,
+                    params: (fc.args ?? {}),
+                });
+            }
+            const orchestration = useToolOrchestration(calls, 0.9);
+            if (orchestration) {
                 return { orchestration, costUsd, ...(usage ? { usage } : {}) };
             }
             // Text response
@@ -103,11 +114,33 @@ export function createGeminiBrain(opts) {
         },
     };
 }
+/**
+ * `generateContentStream` read to the end, folded back into the response shape
+ * the caller above expects.
+ *
+ * The SDK hands back BOTH an iterable `stream` and an already-aggregated
+ * `response` promise — and this deliberately ignores the second. The fold that
+ * runs in production has to be the fold the tests exercise; taking the SDK's
+ * aggregate instead would leave `accumulateGemini` proven and unused, which is
+ * the same as unproven.
+ *
+ * It takes the call as a thunk rather than the model, so `withRetry` re-opens a
+ * fresh stream on a retry instead of re-reading a drained one.
+ */
+async function streamContent(open, sink, signal) {
+    const result = await open();
+    const items = await consumeStream(result.stream, geminiDelta, sink, signal);
+    return accumulateGemini(items);
+}
 function buildGeminiContents(input) {
     const contents = [];
+    // Derived tool calls / tool results arrive TAGGED rather than flattened into
+    // anonymous `user` turns — see the wire contract in tool-context.ts. Gemini is
+    // the one provider that renames the role: `assistant` is spelled `model`.
     for (const msg of input.history) {
-        const role = msg.role === "assistant" ? "model" : "user";
-        contents.push({ role, parts: [{ text: msg.content }] });
+        const wire = toWireMessage(msg);
+        const role = wire.role === "assistant" ? "model" : "user";
+        contents.push({ role, parts: [{ text: wire.content }] });
     }
     // Current user message — shared fold + finalize nudge (parity with all brains).
     const userText = foldToolResults(input.raw, input.tool_results);

package/dist/brain/ollama.js

@@ -3,16 +3,27 @@
  * No peer dependencies — plain HTTP fetch.
  */
 import { withRetry } from "./retry.js";
-import { foldToolResults, toolParamsToJsonSchema } from "./tool-context.js";
+import { foldToolResults, toolParamsToJsonSchema, toWireMessage, useToolOrchestration, } from "./tool-context.js";
+import { accumulateOllama, consumeNdjson, } from "./streaming.js";
 export function createOllamaBrain(opts) {
     const endpoint = opts.endpoint ?? process.env["OLLAMA_ENDPOINT"] ?? "http://localhost:11434";
     const model = opts.model ?? "llama3.2";
     return {
         name: "ollama",
         async run(input) {
+            // Ollama is the one adapter that passed roles through verbatim, so a
+            // derived `role: "tool"` message went out as a bare `tool` turn with no
+            // native pairing — which no /api/chat backend can honour. The two DERIVED
+            // tool roles are tagged (the same text the other three send); every other
+            // role still passes through untouched.
             const messages = [
                 { role: "system", content: input.system_context },
-                ...input.history.map((m) => ({ role: m.role, content: m.content })),
+                ...input.history.map((m) => {
+                    const wire = toWireMessage(m);
+                    return wire.tagged
+                        ? { role: wire.role, content: wire.content }
+                        : { role: m.role, content: m.content };
+                }),
                 // Fold prior tool results into the turn (parity with the cloud brains).
                 { role: "user", content: foldToolResults(input.raw, input.tool_results) },
             ];
@@ -30,37 +41,54 @@ export function createOllamaBrain(opts) {
                     },
                 }))
                 : undefined;
-            const response = await withRetry(() => fetch(`${endpoint}/api/chat`, {
+            // ── The one branch streaming adds ──────────────────────────────────
+            //
+            // No `onChunk`, no stream: `stream: false` and one `response.json()`, the
+            // way this brain has always spoken to Ollama. Both paths land in
+            // `OllamaChatResponse` — the fields this brain reads — so the payload is
+            // built once, from one shape.
+            const post = (stream) => fetch(`${endpoint}/api/chat`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({
                     model,
                     messages,
-                    stream: false,
+                    stream,
                     ...(tools ? { tools } : {}),
                 }),
                 ...(input.signal ? { signal: input.signal } : {}),
-            }), input.signal ? { signal: input.signal } : {});
-            if (!response.ok) {
-                throw new Error(`Ollama error: ${response.status} ${response.statusText}`);
+            });
+            let data;
+            if (input.onChunk) {
+                data = await withRetry(() => streamChat(post, input.onChunk, input.signal), input.signal ? { signal: input.signal } : {});
+            }
+            else {
+                // Verbatim: the fetch is retried, the status check and the body read
+                // are not — exactly where those three lines have always sat.
+                const response = await withRetry(() => post(false), input.signal ? { signal: input.signal } : {});
+                if (!response.ok) {
+                    throw new Error(`Ollama error: ${response.status} ${response.statusText}`);
+                }
+                data = (await response.json());
             }
-            const data = (await response.json());
             const inputTokens = data.prompt_eval_count;
             const outputTokens = data.eval_count;
             const usageBlock = inputTokens !== undefined || outputTokens !== undefined
                 ? { usage: { ...(inputTokens !== undefined ? { inputTokens } : {}), ...(outputTokens !== undefined ? { outputTokens } : {}) } }
                 : {};
-            // Tool call (Ollama returns arguments already parsed as an object, unlike
-            // OpenAI's JSON string).
-            const call = data.message?.tool_calls?.[0]?.function;
-            if (call?.name) {
-                const orchestration = {
-                    action: "use_tool",
-                    confidence: 0.9,
-                    tool_name: call.name,
-                    tool_params: call.arguments ?? {},
-                };
-                return { orchestration, ...usageBlock };
+            // Tool calls — ALL of them (Ollama returns arguments already parsed as an
+            // object, unlike OpenAI's JSON string). The gate stays what it was: the
+            // FIRST entry must name a tool, or this is a text response. A local model
+            // that emits a nameless first entry behaves exactly as it did yesterday.
+            const rawCalls = data.message?.tool_calls ?? [];
+            const calls = rawCalls.map((c) => ({
+                name: c.function?.name ?? "",
+                params: c.function?.arguments ?? {},
+            }));
+            if (calls[0]?.name) {
+                const orchestration = useToolOrchestration(calls, 0.9);
+                if (orchestration)
+                    return { orchestration, ...usageBlock };
             }
             const text = data.message?.content ?? "";
             return {
@@ -71,3 +99,24 @@ export function createOllamaBrain(opts) {
         },
     };
 }
+/**
+ * The same POST with `stream: true`, whose body is NDJSON rather than one JSON
+ * object, folded back into the response shape the caller above expects.
+ *
+ * The status check stays where it is on the other path — before a single byte
+ * of body is read — so a refusing Ollama fails the same way whether or not
+ * anyone asked to watch. A body that never materialises is the one case this
+ * has to add: `response.body` is nullable in the fetch spec, and reading a
+ * null stream is a `TypeError` with no useful message.
+ */
+async function streamChat(post, sink, signal) {
+    const response = await post(true);
+    if (!response.ok) {
+        throw new Error(`Ollama error: ${response.status} ${response.statusText}`);
+    }
+    if (!response.body) {
+        throw new Error("Ollama error: streaming response carried no body");
+    }
+    const lines = await consumeNdjson(response.body, sink, signal);
+    return accumulateOllama(lines);
+}

package/dist/brain/openai.js

@@ -4,7 +4,8 @@
  */
 import { computeCostUsd } from "./pricing.js";
 import { withRetry } from "./retry.js";
-import { foldToolResults, toolParamsToJsonSchema } from "./tool-context.js";
+import { foldToolResults, toolParamsToJsonSchema, toWireMessage, useToolOrchestration, } from "./tool-context.js";
+import { accumulateOpenAI, consumeStream, openAIDelta, } from "./streaming.js";
 export function createOpenAIBrain(opts) {
     const model = opts.model ?? "gpt-4o-mini";
     return {
@@ -19,12 +20,14 @@ export function createOpenAIBrain(opts) {
             // brains) so the model sees what its tool calls returned and is nudged to
             // finalize rather than re-calling forever.
             const userContent = foldToolResults(input.raw, input.tool_results);
+            // Derived tool calls / tool results arrive TAGGED rather than flattened
+            // into anonymous `user` turns — see the wire contract in tool-context.ts.
             const messages = [
                 { role: "system", content: input.system_context },
-                ...input.history.map((m) => ({
-                    role: (m.role === "assistant" ? "assistant" : "user"),
-                    content: m.content,
-                })),
+                ...input.history.map((m) => {
+                    const wire = toWireMessage(m);
+                    return { role: wire.role, content: wire.content };
+                }),
                 { role: "user", content: userContent },
             ];
             const tools = input.tools.length > 0
@@ -45,7 +48,16 @@ export function createOpenAIBrain(opts) {
                     tool_choice: "auto",
                 }
                 : { model, messages: messages };
-            const response = await withRetry(() => client.chat.completions.create(body, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {});
+            // ── The one branch streaming adds ──────────────────────────────────
+            //
+            // No `onChunk`, no stream: the call below is the call this brain has
+            // always made, and every line after this block is untouched — the
+            // streamed and non-streamed responses are the same shape by
+            // construction (`OpenAICompletion`), so there is one payload builder,
+            // not two that must be kept in step.
+            const response = input.onChunk
+                ? await withRetry(() => streamCompletion(client, body, input.onChunk, input.signal), input.signal ? { signal: input.signal } : {})
+                : await withRetry(() => client.chat.completions.create(body, input.signal ? { signal: input.signal } : {}), input.signal ? { signal: input.signal } : {});
             const choice = response.choices[0];
             if (!choice)
                 return {};
@@ -62,24 +74,26 @@ export function createOpenAIBrain(opts) {
                     costUsd,
                 }
                 : {};
-            // Tool call response
+            // Tool calls — ALL of them, in the order the model emitted them. Taking
+            // only `tool_calls[0]` threw away every sibling call and bought each one
+            // back at the price of a whole extra model round-trip.
             if (msg.tool_calls?.length) {
-                const call = msg.tool_calls[0];
-                if (!call)
-                    return {};
-                let params = {};
-                try {
-                    params = JSON.parse(call.function
-                        ?.arguments ?? "{}");
-                }
-                catch { }
-                const orchestration = {
-                    action: "use_tool",
-                    confidence: 0.9,
-                    tool_name: call.function?.name ?? "",
-                    tool_params: params,
-                };
-                return { orchestration, ...usageBlock };
+                const calls = msg.tool_calls.map((call) => {
+                    const fn = call.function;
+                    let params = {};
+                    try {
+                        params = JSON.parse(fn?.arguments ?? "{}");
+                    }
+                    catch {
+                        // A call whose arguments are unparseable is still a call the model
+                        // made: it goes through with `{}` and fails validation downstream,
+                        // rather than silently vanishing from the step.
+                    }
+                    return { name: fn?.name ?? "", params };
+                });
+                const orchestration = useToolOrchestration(calls, 0.9);
+                if (orchestration)
+                    return { orchestration, ...usageBlock };
             }
             const text = msg.content ?? "";
             return {
@@ -90,3 +104,23 @@ export function createOpenAIBrain(opts) {
         },
     };
 }
+/**
+ * The same request with `stream: true`, read to the end, folded back into the
+ * completion shape the caller above expects.
+ *
+ * `stream_options.include_usage` is not optional politeness: without it OpenAI
+ * sends no `usage` on a streamed call, `computeCostUsd` would see `undefined`,
+ * and the loop's cost cap would silently stop counting for exactly the runs a
+ * user is watching. Streaming must not cost less to the accountant than it
+ * costs in fact.
+ */
+async function streamCompletion(client, body, sink, signal) {
+    const streamBody = {
+        ...body,
+        stream: true,
+        stream_options: { include_usage: true },
+    };
+    const stream = await client.chat.completions.create(streamBody, signal ? { signal } : {});
+    const chunks = await consumeStream(stream, openAIDelta, sink, signal);
+    return accumulateOpenAI(chunks);
+}