@msm-core/mini 0.5.1 → 0.8.0

package/dist/core/loop.js

@@ -8,10 +8,12 @@
  *   budget exhausted → force_respond → done
  */
 import { randomBytes } from "crypto";
+import { compactionAnchor, compactionBoundary, deriveMessages, } from "@msm-core/session";
+import { toWireMessage } from "../brain/tool-context.js";
 import { resolveGuards, checkGuards, hasHardBlock, hardAction, } from "./guards.js";
 import { runGates } from "./gates.js";
-import { buildContext } from "./context-builder.js";
-import { fireIteration, fireToolCall, fireGuard, fireFatalError, fireSectionComplete, } from "./hooks.js";
+import { buildContext, DEFAULT_BUDGET } from "./context-builder.js";
+import { fireChunk, fireIteration, fireToolCall, fireGuard, fireFatalError, fireSectionComplete, } from "./hooks.js";
 import { RedisMemory, connectRedis } from "../adapters/redis-memory.js";
 import { RedisControlBus } from "../adapters/redis-control.js";
 import { RedisDistributedLock } from "../adapters/redis-lock.js";
@@ -20,6 +22,289 @@ import { parseDefinition } from "../definition/parser.js";
 function makeTaskId() {
     return randomBytes(8).toString("hex");
 }
+/**
+ * How many past tool results ride along on a brain call. One constant, because
+ * the loop applies it and the invariant has to reproduce it — two copies of `5`
+ * would drift and the invariant would then fail on a difference that is not a
+ * difference.
+ */
+const TOOL_RESULT_WINDOW = 5;
+/**
+ * The budget the derived history will ACTUALLY be trimmed to — the loop's own
+ * `historyLimit` (derived from `maxIterations`) reconciled with the context
+ * builder's `maxHistoryMessages`, because the request passes through both cuts.
+ *
+ * A compactor is told this number and not `DEFAULT_BUDGET`, because the number
+ * that matters to it is the one that decides what gets dropped. Being told 20
+ * while the real cap is 8 would have it compact eleven messages too late.
+ */
+function effectiveBudget(historyLimit) {
+    return {
+        maxTokens: DEFAULT_BUDGET.maxTokens,
+        maxHistoryMessages: Math.min(historyLimit, DEFAULT_BUDGET.maxHistoryMessages),
+    };
+}
+// ═══ One step, N tool calls (س٤) ══════════════════════════════════════════════
+/** `{}` for anything that is not an object — a call still runs and still fails validation. */
+function asParams(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * The calls of ONE step, normalized — the single reading of a model response
+ * that both the log and the dispatcher use.
+ *
+ * Two shapes arrive here and exactly one leaves:
+ *
+ *   - `tool_calls` present  → every call, in the model's order.
+ *   - only `tool_name`      → one call. Every brain written before س٤, and
+ *                             every scripted brain in the suite, lands here and
+ *                             takes the path it always took.
+ *
+ * It is pure and it is called TWICE per step — once to write
+ * `model_response.toolCalls`, once to dispatch — because the alternative is
+ * threading a list between two places that must agree on ordinals, and a
+ * `callId` that disagrees with the call it names is a log that cannot be
+ * replayed. One function, one answer, no drift.
+ *
+ * Entries with a non-string `name` are dropped rather than carried: they are
+ * not callable by any path, and keeping them would shift the ordinals of the
+ * calls that ARE callable. An EMPTY name survives — that is a call the model
+ * genuinely made to a tool that does not exist, and it is recorded and answered
+ * as such.
+ */
+function stepToolCalls(orch) {
+    const declared = orch.tool_calls;
+    if (Array.isArray(declared) && declared.length > 0) {
+        return declared
+            .filter((c) => c !== null && typeof c === "object" && typeof c.name === "string")
+            .map((c) => ({ name: c.name, params: asParams(c.params) }));
+    }
+    return orch.tool_name
+        ? [{ name: orch.tool_name, params: asParams(orch.tool_params) }]
+        : [];
+}
+/**
+ * The loop's writer for ONE turn: it mints the identifiers, keeps the sequence,
+ * and appends.
+ *
+ * Identifiers are minted here and not in `@msm-core/session` on purpose — that
+ * package is pure. They are *structured* rather than opaque: `t{seq}` for the
+ * turn, then `turn.sN` per step and `turn.sN.cM` per call. Unique within the
+ * session by construction, and readable in an audit trail, where `t41.s2.c1`
+ * says what it is and a random hex string would not.
+ *
+ * ── Why the turn id is DERIVED and no longer random (ض١ §6, س٥'s lesson) ────
+ *
+ * It used to be `t${randomBytes(8)}`. It is now `t${head + 1}` — the `seq` this
+ * turn's first event will occupy. A random id per turn kills every comparison
+ * that crosses a run: a tape fingerprint, a golden log, a diff of two sessions
+ * that should be identical. `@msm-core/replay` had to *normalise* `toolCallId`
+ * to its order of appearance precisely because the value underneath was
+ * arbitrary; deriving the id removes the arbitrariness at the source instead of
+ * papering over it downstream.
+ *
+ * It is still unique: `seq` rises by exactly one per session and never repeats,
+ * so no two turns that write anything can claim the same head. (A turn that
+ * writes NOTHING leaves the head where it was and the next turn takes the same
+ * id — harmless, because the first turn put no event in the log to collide
+ * with.) And it is still meaningful: `t41` says the turn opened at seq 41.
+ *
+ * `seq` is held in memory for the turn and starts at `head + 1`. Two writers on
+ * one session would collide — which is why this is created *after* the session
+ * lock is held, and why a collision raises `SeqGapError` instead of silently
+ * renumbering.
+ */
+class TurnWriter {
+    turnId;
+    #seq;
+    #log;
+    #sessionId;
+    constructor(log, sessionId, head) {
+        this.#log = log;
+        this.#sessionId = sessionId;
+        this.#seq = head;
+        this.turnId = `t${head + 1}`;
+    }
+    /** The id of step `index` (1-based) in this turn. */
+    stepId(index) {
+        return `${this.turnId}.s${index}`;
+    }
+    /** The id of the `ordinal`-th (1-based) tool call of a step. */
+    callId(stepId, ordinal) {
+        return `${stepId}.c${ordinal}`;
+    }
+    /** Append a turn-scoped event. Returns the `seq` it was written at. */
+    async writeTurn(type, data, time = Date.now()) {
+        return this.#append({ type, data, time });
+    }
+    /**
+     * Append a step-scoped event. `stepId` is required by the signature, not by a
+     * runtime check — the seven step types cannot be written without one.
+     */
+    async writeStep(type, stepId, data, time = Date.now()) {
+        return this.#append({ type, data, time, stepId });
+    }
+    async #append(parts) {
+        const seq = this.#seq + 1;
+        // The cast is the one place the type/data correlation is asserted rather
+        // than proved: `writeTurn` / `writeStep` above are what actually pair a
+        // type with its payload, and every caller goes through them.
+        const event = {
+            seq,
+            time: parts.time,
+            type: parts.type,
+            data: parts.data,
+            turnId: this.turnId,
+            ...(parts.stepId !== undefined ? { stepId: parts.stepId } : {}),
+        };
+        await this.#log.append(this.#sessionId, event);
+        // Advance only after the store accepted it — a rejected append must not
+        // leave a hole that the next write would silently skip over.
+        this.#seq = seq;
+        return seq;
+    }
+}
+/**
+ * Is the invariant armed?
+ *
+ * Silent by default in production, strict under the test runner. `MSM_SESSION_STRICT`
+ * overrides in both directions: set it to turn the check on in a live service
+ * (recommended in staging), set it to `0`/`false` to turn it off in a test run.
+ */
+function sessionStrict() {
+    const flag = process.env["MSM_SESSION_STRICT"];
+    if (flag !== undefined && flag !== "") {
+        return flag !== "0" && flag.toLowerCase() !== "false";
+    }
+    return (process.env["VITEST"] !== undefined || process.env["NODE_ENV"] === "test");
+}
+/** JSON with object keys sorted, so two equal values always compare equal. */
+function stable(value) {
+    return (JSON.stringify(value, (_key, val) => {
+        if (val === null || typeof val !== "object" || Array.isArray(val))
+            return val;
+        const source = val;
+        const sorted = {};
+        for (const key of Object.keys(source).sort())
+            sorted[key] = source[key];
+        return sorted;
+    }) ?? "undefined");
+}
+function invariantError(what, turnId, stepId, fromLog, sent) {
+    return new Error(`msm-mini session-log invariant: ${what} is not reconstructible from the ` +
+        `session log (turn=${turnId} step=${stepId}). ` +
+        `log=${stable(fromLog)} sent=${stable(sent)}`);
+}
+/** The four fields of a tool result that actually reach the model (see `foldToolResults`). */
+function deliveredToolResult(result) {
+    return {
+        tool: result.tool,
+        status: result.status,
+        ...(result.result !== undefined ? { result: result.result } : {}),
+        ...(result.error !== undefined ? { error: result.error } : {}),
+    };
+}
+/**
+ * **The rule this whole session exists to enforce**: everything handed to the
+ * model must be rebuildable from the log alone.
+ *
+ * `BrainRunInput` carries four things into a model call, and each has exactly
+ * one counterpart in the log:
+ *
+ *   | sent             | rebuilt from                                        |
+ *   |------------------|-----------------------------------------------------|
+ *   | `raw`            | this turn's `user_message`                           |
+ *   | `system_context` | this step's `model_request.data.system`               |
+ *   | `history`        | `deriveMessages(events before this turn)`, same trim  |
+ *   | `tool_results`   | this turn's PAIRED `tool_call`/`tool_result` events   |
+ *
+ * The system context needs its own comparison because no message event can
+ * produce it: the assembled persona + memories + tool catalogue never passes
+ * through the conversation, so it is recorded as audit data or it is lost. One
+ * comparison against `deriveMessages` alone would report a difference that is
+ * not a difference.
+ *
+ * Tool results are rebuilt through the **pairing** rule, not from
+ * `tool_result` events alone. That is what gives the check teeth: drop the
+ * `tool_call` and the pair vanishes from the reconstruction; drop the
+ * `tool_result` and it vanishes too. Either half missing is a log that cannot
+ * replay the conversation it claims to record.
+ *
+ * The events are re-read from the store rather than remembered, so a store that
+ * loses, reorders or mangles a write is caught here and not at replay time.
+ *
+ * Throws on any difference; the caller runs it only when `sessionStrict()`.
+ */
+function assertRequestReconstructible(args) {
+    const { events, turnId, stepId, historyLimit, sent } = args;
+    // The cut is this turn's USER MESSAGE, not this turn's first event.
+    //
+    // They were the same thing until ض١: the user message opened every turn. A
+    // turn that compacts now writes its `compaction` event first, and that event
+    // is precisely a statement ABOUT the past — it belongs on the `before` side of
+    // the cut, because the history handed to the model was derived with it
+    // applied. Cutting at the turn's first event would put the compaction on the
+    // `inTurn` side, reconstruct an UNcompacted conversation, and fire the
+    // invariant on a difference that is not one.
+    //
+    // On every path without compaction the two definitions pick the same index,
+    // so nothing else moves.
+    const turnStart = events.findIndex((e) => e.turnId === turnId && e.type === "user_message");
+    const before = turnStart < 0 ? events : events.slice(0, turnStart);
+    const inTurn = turnStart < 0 ? [] : events.slice(turnStart);
+    // 1 ── the user's message
+    const opening = inTurn.find((e) => e.type === "user_message");
+    if (!opening || opening.data.text !== sent.raw) {
+        throw invariantError("the user message", turnId, stepId, opening?.data.text, sent.raw);
+    }
+    // 2 ── the assembled system context, read back OUT of the log
+    //
+    // Its own comparison, because no message event can produce it: the assembled
+    // persona + memories + tool catalogue never travels through the conversation,
+    // so it is recorded as audit data or it is lost. Checking `deriveMessages`
+    // alone would report a difference that is not a difference (س٢ ruling 6).
+    let request;
+    for (const e of inTurn) {
+        if (e.type === "model_request" && e.stepId === stepId)
+            request = e;
+    }
+    if (!request) {
+        throw invariantError("the model request", turnId, stepId, null, "a model_request event for this step");
+    }
+    if (request.data.system !== sent.system_context) {
+        throw invariantError("the system context", turnId, stepId, request.data.system, sent.system_context);
+    }
+    // 3 ── the conversation, derived and trimmed exactly as the request was
+    const expectedHistory = deriveMessages(before)
+        .slice(-historyLimit)
+        .slice(-DEFAULT_BUDGET.maxHistoryMessages);
+    if (stable(expectedHistory) !== stable(sent.history)) {
+        throw invariantError("the conversation history", turnId, stepId, expectedHistory, sent.history);
+    }
+    // 4 ── the tool results, rebuilt through the pairing rule
+    const called = new Set();
+    const paired = [];
+    for (const e of inTurn) {
+        if (e.type === "tool_call") {
+            called.add(e.data.callId);
+        }
+        else if (e.type === "tool_result" && called.has(e.data.callId)) {
+            paired.push(deliveredToolResult({
+                tool: e.data.name,
+                status: e.data.status,
+                ...(e.data.result !== undefined ? { result: e.data.result } : {}),
+                ...(e.data.error !== undefined ? { error: e.data.error } : {}),
+            }));
+        }
+    }
+    const expectedResults = paired.slice(-TOOL_RESULT_WINDOW);
+    const sentResults = (sent.tool_results ?? []).map(deliveredToolResult);
+    if (stable(expectedResults) !== stable(sentResults)) {
+        throw invariantError("the tool results", turnId, stepId, expectedResults, sentResults);
+    }
+}
 /**
  * Create a stateful agent from config.
  * Returns an Agent object — call .handle() on every incoming event.
@@ -87,19 +372,43 @@ export function createAgent(config) {
             ? `${prefix}:${event.tenantContext.companyId}:${event.tenantContext.agentType}`
             : prefix;
     }
+    /**
+     * The session store for one event — the loop's ONLY door to session memory.
+     *
+     * An injected `config.memory` wins and no Redis store is built (nor is the
+     * connection opened on its account). Otherwise the bundled `RedisMemory` is
+     * built from `config.redis` exactly as before: same tenant prefix, same
+     * history/document TTLs. Both `handle()` and `handleCore()` go through here,
+     * so the two construction sites that used to drift apart are now one.
+     */
+    async function resolveStore(event) {
+        // Read `config.memory` ONCE — the guard for "resolved once per cycle"
+        // counts property reads through a getter, and a second read here would be
+        // indistinguishable from a second resolve.
+        const injected = config.memory;
+        if (injected)
+            return injected;
+        const redis = await getRedis();
+        return new RedisMemory(redis, {
+            prefix: tenantPrefixFor(event),
+            ...(ttl.history !== undefined ? { historyTtl: ttl.history } : {}),
+            ...(ttl.document !== undefined ? { documentTtl: ttl.document } : {}),
+        });
+    }
     /**
      * Public entry point — runs the loop, then persists final run metadata
      * (status / iterations / cost) for ops dashboards. Metadata is best-effort:
      * it never blocks or fails the response.
+     *
+     * The store is resolved ONCE here and threaded into the loop. It used to be
+     * resolved twice per cycle — once inside `handleCore` and once again for this
+     * metadata write — which built two `RedisMemory` instances on the fallback
+     * path and read an injected port twice (س١ ruling 6). One turn, one store.
      */
     async function handle(event) {
-        const outcome = await handleCore(event);
+        const memory = await resolveStore(event);
+        const outcome = await handleCore(event, memory);
         try {
-            const redis = await getRedis();
-            const memory = new RedisMemory(redis, {
-                prefix: tenantPrefixFor(event),
-                ...(ttl.history !== undefined ? { historyTtl: ttl.history } : {}),
-            });
             await memory.setMetadata(event.sessionId, {
                 iterationCount: outcome.metrics.iterations,
                 startedAt: Date.now() - outcome.metrics.durationMs,
@@ -116,7 +425,7 @@ export function createAgent(config) {
         }
         return outcome;
     }
-    async function handleCore(event) {
+    async function handleCore(event, memory) {
         const sessionId = event.sessionId;
         const taskId = makeTaskId();
         const started = Date.now();
@@ -125,12 +434,9 @@ export function createAgent(config) {
         const effectiveGuards = event.guardsOverride
             ? resolveGuards({ ...guards, ...event.guardsOverride })
             : guards;
+        // Redis still backs the control bus, the session lock and tool dedup —
+        // separate ports, untouched. Session memory arrives resolved from handle().
         const redis = await getRedis();
-        const memory = new RedisMemory(redis, {
-            prefix: tenantPrefix,
-            ...(ttl.history !== undefined ? { historyTtl: ttl.history } : {}),
-            ...(ttl.document !== undefined ? { documentTtl: ttl.document } : {}),
-        });
         const controlBus = new RedisControlBus(redis, tenantPrefix);
         const lock = new RedisDistributedLock(redis, tenantPrefix);
         // ── Gates (zero-LLM filters) ─────────────────────────────
@@ -151,15 +457,241 @@ export function createAgent(config) {
             totalToolCalls: 0,
             consecutiveToolFailures: 0,
         };
+        /**
+         * The streaming request, built once — or not built at all (ب١).
+         *
+         * **This `undefined` is the feature.** With no `onChunk` hook configured,
+         * `BrainRunInput` carries no `onChunk`, every brain sees the field missing
+         * and takes its ordinary non-streaming path, and nothing anywhere in this
+         * run differs from yesterday. Passing a no-op sink instead would have put
+         * every agent on earth onto the streaming code path to feed a function that
+         * throws its argument away.
+         *
+         * `state.iteration` is read when a chunk fires, not when this closure is
+         * made, so each chunk carries the step it actually belongs to — including
+         * the finalize call, which streams under the iteration it aborted on.
+         */
+        const chunkSink = config.hooks?.onChunk
+            ? (chunk) => fireChunk(config.hooks, sessionId, state.iteration, chunk.text)
+            : undefined;
         const toolDefs = toToolDefinitions(config.tools);
         const toolMap = new Map(config.tools.map((t) => [t.name, t]));
         const toolResults = [];
+        const sessionLog = config.sessionLog;
+        const strict = sessionLog ? sessionStrict() : false;
+        /** The open step, if any — the error path uses it to close the step it died in. */
+        let openStep;
+        let turnLog;
         try {
-            // Load history
-            const history = await memory.getHistory(sessionId, effectiveGuards.maxIterations * 4);
+            const historyLimit = effectiveGuards.maxIterations * 4;
+            let history;
+            if (sessionLog) {
+                // ── The log is the truth, and the conversation is derived from it ──
+                //
+                // Read BEFORE the turn's first write: these are the events of every
+                // PREVIOUS turn, and they are what the conversation is derived from.
+                // The current message is not part of it — it travels as `raw`, the way
+                // it always has, and appending it to the history too would deliver it
+                // twice.
+                //
+                // The derived conversation carries the `assistant`/`tool` pairs of past
+                // turns, which `getHistory` never held (there is not one `role: "tool"`
+                // write in this package). That difference is the whole point of the
+                // log — and it is guarded explicitly on both paths, not left to be
+                // noticed in production.
+                turnLog = new TurnWriter(sessionLog, sessionId, await sessionLog.head(sessionId));
+                let past = await sessionLog.read(sessionId);
+                // ── The compaction seat (ض١) ──────────────────────────────────────
+                //
+                // Consulted BEFORE the turn's user message is written, so the range it
+                // proposes covers only completed turns and the summary is in place for
+                // the very first model call of this turn.
+                //
+                // Everything below is skipped when no port is injected — which is the
+                // default, and which is why an agent that does not opt in cannot tell
+                // ض١ happened. The seat needs the log and says so at the type level via
+                // `sessionLog` being the branch it lives in: a compaction is an EVENT,
+                // and without a log there is nowhere to record it.
+                if (config.compaction) {
+                    const decision = await config.compaction.maybeCompact(deriveMessages(past), effectiveBudget(historyLimit));
+                    const summary = decision?.summary?.trim();
+                    if (summary) {
+                        // Two defences, and this is the first: the port asked to keep N
+                        // turns, `compactionBoundary` decides what that can safely mean.
+                        // It returns 0 when nothing can be compacted without severing a
+                        // tool call from its result or splitting a turn — and 0 means the
+                        // loop writes nothing at all rather than writing a range the
+                        // derivation would then refuse.
+                        const toSeq = compactionBoundary(past, decision?.keepTurns ?? 0);
+                        const fromSeq = compactionAnchor(past);
+                        if (toSeq >= fromSeq) {
+                            await turnLog.writeTurn("compaction", {
+                                fromSeq,
+                                toSeq,
+                                summary,
+                                // Who asked, not why — the loop does not know the port's
+                                // reasoning and will not invent one for an audit record.
+                                reason: "compaction_port",
+                            });
+                            // Re-read rather than patch what is in hand: the events come back
+                            // through the store, so a log that lost or mangled the write is
+                            // caught here, on this turn, and not at replay time.
+                            past = await sessionLog.read(sessionId);
+                        }
+                    }
+                }
+                // The same cap the store applied on the legacy path, so the budget of a
+                // long session is bounded identically even when nothing compacts.
+                history = deriveMessages(past).slice(-historyLimit);
+                await turnLog.writeTurn("user_message", { text: event.message }, 
+                // `started`, not "now": the user's message arrived when the turn
+                // opened. It also keeps the derived `timestamp` equal to the one
+                // `appendHistory` writes for the same message.
+                started);
+            }
+            else {
+                history = await memory.getHistory(sessionId, historyLimit);
+            }
+            /**
+             * Close the turn: the delivered reply goes to BOTH records — the event
+             * log (the truth) and the history array (transitional compatibility,
+             * §5) — and the step that produced it is closed.
+             *
+             * One helper for all three delivery paths, because three copies of the
+             * same two writes is exactly how two of them silently drift apart (س١'s
+             * lesson, paid for once already).
+             */
+            const closeTurn = async (finalText, stepId, reason) => {
+                const now = Date.now();
+                await turnLog?.writeTurn("assistant_message", { text: finalText }, now);
+                await turnLog?.writeStep("step_ended", stepId, {
+                    index: state.iteration,
+                    reason,
+                });
+                openStep = undefined;
+                await memory.appendHistory(sessionId, {
+                    role: "user",
+                    content: event.message,
+                    timestamp: started,
+                });
+                await memory.appendHistory(sessionId, {
+                    role: "assistant",
+                    content: finalText,
+                    timestamp: now,
+                });
+            };
+            /** Close a step that produced no reply (a tool round-trip, or an abort). */
+            const endStep = async (stepId, reason) => {
+                await turnLog?.writeStep("step_ended", stepId, {
+                    index: state.iteration,
+                    reason,
+                });
+                openStep = undefined;
+            };
+            /** Record a guard that fired, at the step it fired in. */
+            const logGuard = async (stepId, guard, action, reason) => {
+                await turnLog?.writeStep("guard_fired", stepId, {
+                    guard,
+                    ...(action !== undefined ? { action } : {}),
+                    ...(reason !== undefined ? { reason } : {}),
+                });
+            };
+            /** The output gate, plus the `guard_fired` record when it does something. */
+            const gateAndLog = async (text, stepId) => {
+                const gated = await applyOutputGate(text);
+                if (gated.validation && gated.validation.action !== "release") {
+                    await logGuard(stepId, "output_gate", gated.validation.action, gated.validation.violations.join(", ") || undefined);
+                }
+                return gated;
+            };
+            /**
+             * Record what is about to be sent — then prove it is reconstructible.
+             *
+             * The invariant runs BEFORE the call goes out, not after: a request that
+             * cannot be rebuilt from the log is a request that should not be paid
+             * for, and failing after the money is spent teaches nothing the receipt
+             * would not.
+             */
+            const logRequest = async (input, stepId) => {
+                if (!turnLog || !sessionLog)
+                    return;
+                await turnLog.writeStep("model_request", stepId, {
+                    model: def.brain.model,
+                    system: input.system_context,
+                    messageCount: input.history.length,
+                    toolNames: input.tools.map((t) => t.name),
+                });
+                if (!strict)
+                    return;
+                // Re-read from the store rather than reuse what was just written: a log
+                // that loses, reorders or mangles a write is caught here, not at replay.
+                assertRequestReconstructible({
+                    events: await sessionLog.read(sessionId),
+                    turnId: turnLog.turnId,
+                    stepId,
+                    historyLimit,
+                    sent: input,
+                });
+            };
+            /**
+             * Record what came back, verbatim — before any output gate touches it.
+             *
+             * `toolCalls` carries ALL the calls of the step, in the model's order,
+             * numbered `stepId.c1 … stepId.cN`. The log shape was built for this from
+             * the start (س٢ §4: "a step carries as many tool calls as the model asked
+             * for") — this is the writer finally filling it.
+             */
+            const logResponse = async (payload, stepId) => {
+                if (!turnLog)
+                    return;
+                const writer = turnLog;
+                const orch = payload.orchestration;
+                const text = payload.generation?.response_text ?? payload.final_output?.text;
+                const calls = orch?.action === "use_tool" ? stepToolCalls(orch) : [];
+                await writer.writeStep("model_response", stepId, {
+                    ...(text !== undefined ? { text } : {}),
+                    ...(calls.length > 0
+                        ? {
+                            toolCalls: calls.map((call, index) => ({
+                                callId: writer.callId(stepId, index + 1),
+                                name: call.name,
+                                args: call.params,
+                            })),
+                        }
+                        : {}),
+                    ...(orch?.action !== undefined ? { finishReason: orch.action } : {}),
+                    ...(payload.usage !== undefined ? { usage: payload.usage } : {}),
+                    ...(payload.costUsd !== undefined ? { costUsd: payload.costUsd } : {}),
+                });
+            };
+            /**
+             * One tool invocation, both halves. Written together because the pair is
+             * the unit: a call with no result replays as a question the model must
+             * answer and cannot, and a result with no call replays as an answer to
+             * nothing. Every provider rejects half a pair.
+             */
+            const logToolPair = async (stepId, ordinal, name, args, result) => {
+                if (!turnLog)
+                    return;
+                const callId = turnLog.callId(stepId, ordinal);
+                await turnLog.writeStep("tool_call", stepId, { callId, name, args });
+                await turnLog.writeStep("tool_result", stepId, {
+                    callId,
+                    name,
+                    status: result.status,
+                    ...(result.result !== undefined ? { result: result.result } : {}),
+                    ...(result.error !== undefined ? { error: result.error } : {}),
+                });
+            };
             // Loop
             while (true) {
                 state.iteration++;
+                // ── Step opens ────────────────────────────────────────
+                const stepId = turnLog ? turnLog.stepId(state.iteration) : "";
+                openStep = { id: stepId, index: state.iteration };
+                await turnLog?.writeStep("step_started", stepId, {
+                    index: state.iteration,
+                });
                 // ── Control bus check ─────────────────────────────────
                 const command = await controlBus.getCommand(sessionId);
                 // ── Guards ────────────────────────────────────────────
@@ -170,9 +702,13 @@ export function createAgent(config) {
                     const hardSignal = guardSignals.find((s) => s.hard);
                     fireGuard(config.hooks, sessionId, hardSignal, state.iteration);
                     const ha = hardAction(guardSignals);
+                    // Logged at the same moment the hook fires, and only for the signal
+                    // the loop acts on: a signal the loop ignores did not "fire".
+                    await logGuard(stepId, hardSignal.type, ha, hardSignal.message);
                     if (process.env["MINI_DEBUG"])
                         console.error(`[mini] hardBlock type=${hardSignal.type} action=${ha} toolResults=${toolResults.length}`);
                     if (ha === "abort") {
+                        await endStep(stepId, "guard");
                         await lockHandle.release();
                         return makeOutcome("error", sessionId, taskId, state, started, {
                             text: `Aborted: ${hardSignal.message}`,
@@ -193,14 +729,22 @@ export function createAgent(config) {
                             const finalRemainingMs = effectiveGuards.timeoutMs > 0
                                 ? Math.max(1, effectiveGuards.timeoutMs - (Date.now() - state.startedAt))
                                 : 0;
-                            const finalPayload = await runWithTimeout(config.brain.run({
+                            const finalInput = {
                                 raw: event.message,
                                 system_context,
                                 history: finalHistory,
                                 tools: [], // no tools → the model must produce a textual answer
-                                tool_results: toolResults.slice(-5),
+                                tool_results: toolResults.slice(-TOOL_RESULT_WINDOW),
+                            };
+                            await logRequest(finalInput, stepId);
+                            const finalPayload = await runWithTimeout(config.brain.run({
+                                ...finalInput,
                                 signal: finalController.signal,
+                                // The forced answer is the one the user actually reads —
+                                // if anything in a run deserves to stream, it is this.
+                                ...(chunkSink ? { onChunk: chunkSink } : {}),
                             }), finalRemainingMs, finalController);
+                            await logResponse(finalPayload, stepId);
                             state.totalCostUsd += finalPayload.costUsd ?? 0;
                             const forced = finalPayload.generation?.response_text ??
                                 finalPayload.final_output?.text ??
@@ -208,17 +752,8 @@ export function createAgent(config) {
                             if (process.env["MINI_DEBUG"])
                                 console.error(`[mini] finalize fired; forced.len=${forced.length} orch=${finalPayload.orchestration?.action}`);
                             if (forced) {
-                                const gated = await applyOutputGate(forced);
-                                await memory.appendHistory(sessionId, {
-                                    role: "user",
-                                    content: event.message,
-                                    timestamp: started,
-                                });
-                                await memory.appendHistory(sessionId, {
-                                    role: "assistant",
-                                    content: gated.finalText,
-                                    timestamp: Date.now(),
-                                });
+                                const gated = await gateAndLog(forced, stepId);
+                                await closeTurn(gated.finalText, stepId, hardSignal.type);
                                 await lockHandle.release();
                                 return makeOutcome(gated.validation?.action === "block" ? "suppressed" : "response", sessionId, taskId, state, started, {
                                     text: gated.finalText,
@@ -236,7 +771,7 @@ export function createAgent(config) {
                     const lastText = state.lastPayload?.generation?.response_text ??
                         state.lastPayload?.final_output?.text ??
                         "I was unable to complete this request within the allowed limits. Please try a more specific question.";
-                    const gatedLast = await applyOutputGate(lastText);
+                    const gatedLast = await gateAndLog(lastText, stepId);
                     const outcomeType = gatedLast.validation?.action === "block"
                         ? "suppressed"
                         : ha === "escalate"
@@ -244,16 +779,7 @@ export function createAgent(config) {
                             : "response";
                     // Record BOTH sides of the turn — assistant-only history leaves
                     // orphaned turns that misalign the conversation on the next call.
-                    await memory.appendHistory(sessionId, {
-                        role: "user",
-                        content: event.message,
-                        timestamp: started,
-                    });
-                    await memory.appendHistory(sessionId, {
-                        role: "assistant",
-                        content: gatedLast.finalText,
-                        timestamp: Date.now(),
-                    });
+                    await closeTurn(gatedLast.finalText, stepId, hardSignal.type);
                     await lockHandle.release();
                     return makeOutcome(outcomeType, sessionId, taskId, state, started, {
                         text: gatedLast.finalText,
@@ -274,9 +800,10 @@ export function createAgent(config) {
                     history: trimmedHistory,
                     tools: toolDefs,
                     ...(toolResults.length > 0
-                        ? { tool_results: toolResults.slice(-5) }
+                        ? { tool_results: toolResults.slice(-TOOL_RESULT_WINDOW) }
                         : {}),
                 };
+                await logRequest(brainInput, stepId);
                 // Bound the brain call by the remaining time budget. Without this a hung
                 // LLM call blocks forever — the wall-clock guard only runs *between*
                 // iterations, never during one.
@@ -285,58 +812,111 @@ export function createAgent(config) {
                 const remainingMs = effectiveGuards.timeoutMs > 0
                     ? Math.max(1, effectiveGuards.timeoutMs - elapsed)
                     : 0;
-                const payload = await runWithTimeout(config.brain.run({ ...brainInput, signal: controller.signal }), remainingMs, controller);
+                const payload = await runWithTimeout(config.brain.run({
+                    ...brainInput,
+                    signal: controller.signal,
+                    ...(chunkSink ? { onChunk: chunkSink } : {}),
+                }), remainingMs, controller);
+                await logResponse(payload, stepId);
                 state.lastPayload = payload;
                 state.totalCostUsd += payload.costUsd ?? 0;
                 const orch = payload.orchestration;
-                // ── Tool call ─────────────────────────────────────────
-                if (orch?.action === "use_tool" && orch.tool_name) {
-                    const toolName = orch.tool_name;
-                    // Check if tool is disabled
+                // ── Tool calls ────────────────────────────────────────
+                //
+                // A step is N calls, not one. They run SEQUENTIALLY, in the model's
+                // order, and the loop returns to the model ONCE when they are all
+                // done — that single round-trip instead of N is the whole point.
+                //
+                // Sequential and not `Promise.all` on purpose: domain tools here write
+                // to shared systems, and nothing in the `Tool` contract promises they
+                // are safe to run concurrently. Parallel *requesting* is what the models
+                // do; parallel *executing* is a separate decision with a separate
+                // blast radius, and it is not made here.
+                //
+                // The gate is unchanged (`action === "use_tool"` plus a first call that
+                // names something), so a brain that fills only `tool_name` walks the
+                // path it always walked.
+                const stepCalls = orch?.action === "use_tool" ? stepToolCalls(orch) : [];
+                if (stepCalls.length > 0) {
+                    // Read once for the whole step: one control-bus command governs the
+                    // step it was read in, and re-reading per call would let a mid-step
+                    // change split one step's siblings under two different policies.
                     const disabledTool = RedisControlBus.disabledTool(command);
-                    if (disabledTool === toolName) {
-                        toolResults.push({
-                            tool: toolName,
-                            status: "failed",
-                            error: `Tool "${toolName}" is currently disabled`,
-                        });
-                        state.consecutiveToolFailures++;
-                        continue;
-                    }
-                    const tool = toolMap.get(toolName);
-                    if (!tool) {
-                        toolResults.push({
-                            tool: toolName,
-                            status: "failed",
-                            error: `Unknown tool: "${toolName}"`,
+                    /** Did ANY call of this step come back ok? — §4's counter turns on it. */
+                    let anySucceeded = false;
+                    for (const [index, call] of stepCalls.entries()) {
+                        // 1-based within the step, and stable: `stepId.c1 … stepId.cN`,
+                        // matching the ids `model_response` already announced. A blocked or
+                        // unknown call keeps its ordinal — renumbering around it would make
+                        // the ids in the response and the ids on the pairs disagree.
+                        const ordinal = index + 1;
+                        const toolName = call.name;
+                        const params = call.params;
+                        // Disabled via the control bus — this call only. Its siblings are
+                        // not this tool and are not refused on its account.
+                        if (disabledTool === toolName) {
+                            const blocked = {
+                                tool: toolName,
+                                status: "failed",
+                                error: `Tool "${toolName}" is currently disabled`,
+                            };
+                            toolResults.push(blocked);
+                            // A refused call is still a call the model made and a result it
+                            // was shown. Logging only the calls that reached a tool would
+                            // leave the model reasoning about an answer the log cannot
+                            // account for.
+                            await logToolPair(stepId, ordinal, toolName, params, blocked);
+                            continue;
+                        }
+                        const tool = toolMap.get(toolName);
+                        if (!tool) {
+                            const unknown = {
+                                tool: toolName,
+                                status: "failed",
+                                error: `Unknown tool: "${toolName}"`,
+                            };
+                            toolResults.push(unknown);
+                            await logToolPair(stepId, ordinal, toolName, params, unknown);
+                            continue;
+                        }
+                        // Per CALL, not per step: the approval gate, the onBeforeTool hook
+                        // and the dedup key all live inside `executeTool`, so a
+                        // `requiresApproval` tool fails closed for ITS call alone while its
+                        // siblings run. A step is not an approval unit.
+                        const exec = await executeTool(tool, params, {
+                            sessionId,
+                            iteration: state.iteration,
+                            agentName: def.name,
+                            ...(event.tenantContext ? { tenantContext: event.tenantContext } : {}),
+                        }, {
+                            redis,
+                            redisPrefix: tenantPrefix,
+                            dedupTtlSeconds: ttl.toolDedup ?? 300,
+                            ...(config.hooks?.onBeforeTool
+                                ? { hooks: { onBeforeTool: config.hooks.onBeforeTool } }
+                                : {}),
                         });
-                        state.consecutiveToolFailures++;
-                        continue;
-                    }
-                    const params = (orch.tool_params ?? {});
-                    const exec = await executeTool(tool, params, {
-                        sessionId,
-                        iteration: state.iteration,
-                        agentName: def.name,
-                        ...(event.tenantContext ? { tenantContext: event.tenantContext } : {}),
-                    }, {
-                        redis,
-                        redisPrefix: tenantPrefix,
-                        dedupTtlSeconds: ttl.toolDedup ?? 300,
-                        ...(config.hooks?.onBeforeTool
-                            ? { hooks: { onBeforeTool: config.hooks.onBeforeTool } }
-                            : {}),
-                    });
-                    fireToolCall(config.hooks, sessionId, exec.result, state.iteration, exec.cached, exec.durationMs);
-                    toolResults.push(exec.result);
-                    state.totalToolCalls++;
-                    if (exec.result.status === "failed") {
-                        state.consecutiveToolFailures++;
+                        fireToolCall(config.hooks, sessionId, exec.result, state.iteration, exec.cached, exec.durationMs);
+                        toolResults.push(exec.result);
+                        state.totalToolCalls++;
+                        if (exec.result.status !== "failed")
+                            anySucceeded = true;
+                        await logToolPair(stepId, ordinal, toolName, params, exec.result);
+                        // …and on to the next sibling. One tool's failure is that tool's
+                        // failure: it does not abort the step, because the model asked for
+                        // several answers and a partial set is still worth more than none.
                     }
-                    else {
+                    // §4 — the counter counts STEPS, not calls. A step with at least one
+                    // success clears it; a step where everything failed adds exactly one.
+                    // Counting per call would let a single bad step of five calls burn a
+                    // three-failure budget outright, which turns a broken tool into a
+                    // terminated conversation.
+                    if (anySucceeded)
                         state.consecutiveToolFailures = 0;
-                    }
-                    continue; // next iteration
+                    else
+                        state.consecutiveToolFailures++;
+                    await endStep(stepId, "tool_calls");
+                    continue; // ONE model round-trip for the whole step
                 }
                 // ── Terminal outcome ──────────────────────────────────
                 const text = payload.generation?.response_text ?? payload.final_output?.text ?? "";
@@ -354,18 +934,10 @@ export function createAgent(config) {
                     }
                 }
                 // ── Optional output gate (shared with all guard exits) ─
-                const { finalText, validation } = await applyOutputGate(text);
-                // Record to history (the delivered text, post-gate)
-                await memory.appendHistory(sessionId, {
-                    role: "user",
-                    content: event.message,
-                    timestamp: started,
-                });
-                await memory.appendHistory(sessionId, {
-                    role: "assistant",
-                    content: finalText,
-                    timestamp: Date.now(),
-                });
+                const { finalText, validation } = await gateAndLog(text, stepId);
+                // Record the delivered text, post-gate — to the log and to the history
+                // array both, for as long as both exist.
+                await closeTurn(finalText, stepId, "final_response");
                 const baseType = orch?.action === "clarify"
                     ? "clarify"
                     : orch?.action === "escalate"
@@ -383,6 +955,21 @@ export function createAgent(config) {
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
             fireFatalError(config.hooks, error, sessionId);
+            // Close the step the run died inside — best effort, and ONLY here. The
+            // log may well be the thing that just failed, and a second failure must
+            // not replace the original error with a less informative one. A log that
+            // simply stops mid-step is itself an honest record of a run that did.
+            if (turnLog && openStep) {
+                try {
+                    await turnLog.writeStep("step_ended", openStep.id, {
+                        index: openStep.index,
+                        reason: "error",
+                    });
+                }
+                catch {
+                    // unreachable log — nothing more to record it with
+                }
+            }
             await lockHandle.release();
             return makeOutcome("error", sessionId, taskId, state, started, {
                 text: "An unexpected error occurred. Please try again.",
@@ -410,6 +997,70 @@ export function createAgent(config) {
     }
     return { handle, kill, pause, resume };
 }
+const DEFAULT_COMPACTOR_SYSTEM = "You compress conversation transcripts for an AI agent's working memory. " +
+    "You are not talking to the user and you never answer the user's question.";
+const DEFAULT_COMPACTOR_INSTRUCTION = "Summarise the transcript below so that an assistant can continue the " +
+    "conversation without it. Preserve: the user's goal, every decision and " +
+    "commitment made, every fact, figure, name and identifier established, and " +
+    "any question still open. Drop pleasantries and repetition. Write plain " +
+    "prose, no preamble, no headings.";
+/**
+ * A `CompactionPort` that summarises with an injected `Brain`.
+ *
+ * **A reference implementation, not a requirement.** The port is the contract;
+ * this is one way to satisfy it, and a consumer with a cheaper model, a local
+ * one, or a rule-based summariser wires up its own and the loop cannot tell.
+ *
+ * It opens no connection of its own. The summary is an ordinary `brain.run`
+ * call on a brain the caller built and injected — the same covenant as every
+ * other port in this package: nothing here knows the network.
+ *
+ * Two deliberate refusals:
+ *
+ *   - It does not use the agent's own tools, history or system context. A
+ *     summariser that could call tools is a second agent with no budget and no
+ *     guards.
+ *   - It does not swallow a provider failure. An empty answer is a decision
+ *     ("nothing to compact"); a thrown error is a broken compactor, and a
+ *     compactor that has been quietly failing is a session quietly losing its
+ *     head — the failure ض١ exists to end.
+ *
+ * The rendering is deterministic and reuses `toWireMessage`, so the summariser
+ * reads a tool round-trip exactly as the agent's own model reads it (س٤'s wire
+ * contract), and the same conversation always produces the same prompt.
+ */
+export function createBrainCompactor(brain, opts = {}) {
+    const keepTurns = opts.keepTurns ?? 2;
+    const systemContext = opts.systemContext ?? DEFAULT_COMPACTOR_SYSTEM;
+    const instruction = opts.instruction ?? DEFAULT_COMPACTOR_INSTRUCTION;
+    return {
+        async maybeCompact(messages, budget) {
+            const threshold = opts.threshold ?? budget.maxHistoryMessages;
+            if (messages.length <= threshold)
+                return null;
+            const transcript = messages
+                .map((message) => {
+                const wire = toWireMessage(message);
+                return `${wire.role}: ${wire.content}`;
+            })
+                .join("\n");
+            const payload = await brain.run({
+                raw: `${instruction}\n\n<transcript>\n${transcript}\n</transcript>`,
+                system_context: systemContext,
+                history: [],
+                tools: [],
+            });
+            const summary = (payload.generation?.response_text ??
+                payload.final_output?.text ??
+                "").trim();
+            // No text is not an error, it is "I have nothing to say about this" —
+            // and the loop then leaves the conversation exactly as it found it.
+            if (!summary)
+                return null;
+            return { summary, keepTurns };
+        },
+    };
+}
 // ─── Helpers ──────────────────────────────────────────────────
 /**
  * Race a brain call against a time budget. On timeout, abort the controller