@msm-core/mini 0.9.0 → 0.15.0

package/dist/core/loop.js

@@ -9,6 +9,9 @@
  */
 import { randomBytes } from "crypto";
 import { compactionAnchor, compactionBoundary, deriveMessages, } from "@msm-core/session";
+// The declaration thread of ص٣/٢, and the only values this file takes from
+// `types.js`: one predicate to read the hook's opt-in, one wrapper to pass it on.
+import { acceptResets, isResetAwareHook } from "./types.js";
 import { toWireMessage } from "../brain/tool-context.js";
 import { resolveGuards, checkGuards, hasHardBlock, hardAction, } from "./guards.js";
 import { runGates } from "./gates.js";
@@ -18,6 +21,7 @@ import { RedisMemory, connectRedis } from "../adapters/redis-memory.js";
 import { RedisControlBus } from "../adapters/redis-control.js";
 import { RedisDistributedLock } from "../adapters/redis-lock.js";
 import { executeTool, toToolDefinitions } from "../tools/executor.js";
+import { RedisToolDedup } from "../tools/dedup.js";
 import { parseDefinition } from "../definition/parser.js";
 function makeTaskId() {
     return randomBytes(8).toString("hex");
@@ -305,11 +309,62 @@ function assertRequestReconstructible(args) {
         throw invariantError("the tool results", turnId, stepId, expectedResults, sentResults);
     }
 }
+/**
+ * The four ports Redis can back, each paired with what a reader of the error
+ * will recognise it as. In the order a turn resolves them, so an error listing
+ * several reads in the order the run would have needed them.
+ */
+const REDIS_BACKED_PORTS = [
+    ["memory", "session memory — history, metadata, document state"],
+    ["controlBus", "the control bus — kill / pause / disable-tool"],
+    ["lock", "the session run-lock"],
+    ["dedup", "tool-call dedup"],
+];
+/**
+ * `redis` is optional (ص٤) under exactly one rule: **whatever it would have
+ * backed must be injected instead.** This is where that rule is enforced, and
+ * where it is enforced is half the point.
+ *
+ * A port is resolved lazily, deep inside a turn, on a path a given event may
+ * not even take. Left to itself, a composition that dropped `redis` while
+ * forgetting `dedup` would run fine until the first tool call — possibly in
+ * production, hours after the process started — and then fail with a message
+ * about a Redis config nobody wrote. A composition mistake belongs at
+ * composition time, named by the exact field that is missing, before a single
+ * event is handled and before a single token is paid for.
+ *
+ * Absence is read from the VALUE, not from the key: `exactOptionalPropertyTypes`
+ * stops a TypeScript caller writing `redis: undefined`, but a JavaScript host
+ * spreading an options bag can hand one over, and that caller deserves this
+ * error rather than a `TypeError` from inside `getRedis()`.
+ *
+ * With `redis` present this returns immediately and nothing about any existing
+ * composition changes.
+ */
+function assertRedisOrPorts(config) {
+    if (config.redis !== undefined)
+        return;
+    const missing = REDIS_BACKED_PORTS.filter(([field]) => config[field] === undefined);
+    if (missing.length === 0)
+        return;
+    const named = missing
+        .map(([field, what]) => `'${field}' (${what})`)
+        .join(", ");
+    const one = missing.length === 1;
+    throw new Error(`msm-mini: AgentConfig has no 'redis', so every port Redis would have ` +
+        `backed must be injected — missing ${one ? "port" : "ports"}: ${named}. ` +
+        `Inject ${one ? "it" : "them"} (InMemorySessionStore / InMemoryControlBus / ` +
+        `InMemoryLock / InMemoryToolDedup ship from '@msm-core/mini/adapters'), ` +
+        `or supply 'redis'.`);
+}
 /**
  * Create a stateful agent from config.
  * Returns an Agent object — call .handle() on every incoming event.
  */
 export function createAgent(config) {
+    // Before anything else: a redis-less config with an unbacked port is a
+    // composition error, and it is raised here rather than mid-turn (ص٤).
+    assertRedisOrPorts(config);
     const def = typeof config.definition === "string"
         ? parseDefinition(config.definition)
         : config.definition;
@@ -318,16 +373,24 @@ export function createAgent(config) {
     // never applied — the documented limits silently no-op'd (M1). resolveGuards
     // then rejects any NaN/garbage and clamps to sane bounds (H10).
     const guards = resolveGuards({ ...def.limits, ...config.guards });
-    const prefix = config.redis.prefix ?? "msm";
-    const ttl = config.redis.ttl ?? {};
-    // Lazy-initialized shared Redis connection
+    const prefix = config.redis?.prefix ?? "msm";
+    const ttl = config.redis?.ttl ?? {};
+    // Lazy-initialized shared Redis connection.
+    //
+    // Reachable only when `config.redis` is present: `assertRedisOrPorts` has
+    // already refused a redis-less config that left any of the four ports
+    // unbacked, and a redis-less config with all four injected never calls a
+    // resolver's fallback arm. The `?.`s below are therefore about a config
+    // object that EXISTS but is empty — `redis: {}` keeps throwing the same
+    // message it always has, which is what makes it a usable "explode if opened"
+    // test config (ports.test.ts leans on exactly that).
     let _redis = null;
     async function getRedis() {
         if (!_redis) {
-            if (config.redis.client) {
+            if (config.redis?.client) {
                 _redis = config.redis.client;
             }
-            else if (config.redis.url) {
+            else if (config.redis?.url) {
                 _redis = (await connectRedis(config.redis.url));
             }
             else {
@@ -395,6 +458,49 @@ export function createAgent(config) {
             ...(ttl.document !== undefined ? { documentTtl: ttl.document } : {}),
         });
     }
+    // ── The other three ports (س٦) ─────────────────────────────
+    //
+    // Same shape as `resolveStore`, three times: an injected port wins and no
+    // Redis object is built for it — and, critically, `getRedis()` is not called
+    // on its account, so a run with all four ports injected never opens a
+    // connection at all. Omit one and the loop builds the bundled Redis adapter
+    // exactly as it did before, with the tenant-scoped prefix it computed.
+    //
+    // They take the prefix rather than the event because `kill/pause/resume` have
+    // no event — they are handed a `companyId`/`agentType` pair instead. That is
+    // also why these are one function each and not four `new RedisControlBus`
+    // calls: the four sites that used to construct a bus by hand (handleCore plus
+    // the three public commands) had already begun to differ in how they built
+    // their prefix, and two sites that do the same thing separately are two sites
+    // that will one day do it differently (س١).
+    async function resolveControlBus(tenantPrefix) {
+        const injected = config.controlBus;
+        if (injected)
+            return injected;
+        return new RedisControlBus(await getRedis(), tenantPrefix);
+    }
+    async function resolveLock(tenantPrefix) {
+        const injected = config.lock;
+        if (injected)
+            return injected;
+        return new RedisDistributedLock(await getRedis(), tenantPrefix);
+    }
+    async function resolveDedup(tenantPrefix) {
+        const injected = config.dedup;
+        if (injected)
+            return injected;
+        return new RedisToolDedup(await getRedis(), tenantPrefix);
+    }
+    /**
+     * The prefix the three public commands scope their bus with — the one
+     * expression that used to be copy-pasted into `kill`, `pause` and `resume`.
+     * Note it is NOT `tenantPrefixFor`: those take the two ids separately and
+     * fall back to the base prefix when either is missing, which is the behaviour
+     * being preserved, not tidied.
+     */
+    function commandPrefix(companyId, agentType) {
+        return companyId && agentType ? `${prefix}:${companyId}:${agentType}` : prefix;
+    }
     /**
      * Public entry point — runs the loop, then persists final run metadata
      * (status / iterations / cost) for ops dashboards. Metadata is best-effort:
@@ -434,11 +540,13 @@ 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 controlBus = new RedisControlBus(redis, tenantPrefix);
-        const lock = new RedisDistributedLock(redis, tenantPrefix);
+        // The three run-control ports, resolved where the Redis trio used to be
+        // constructed — injected if the composition provided them, Redis-backed
+        // from `config.redis` if not. Session memory arrives resolved from
+        // handle(). With all four injected, nothing below touches Redis.
+        const controlBus = await resolveControlBus(tenantPrefix);
+        const lock = await resolveLock(tenantPrefix);
+        const dedup = await resolveDedup(tenantPrefix);
         // ── Gates (zero-LLM filters) ─────────────────────────────
         const gated = runGates(sessionId, taskId, event.message, config.gates);
         if (gated)
@@ -470,10 +578,24 @@ export function createAgent(config) {
          * `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.
+         *
+         * **And it declares for resets only when the hook did (ص٣/٢).** ص٢ built
+         * the cure in `brain/retry.ts` and could not deliver it here, because a
+         * declared sink whose `fireChunk` had no reset channel would take the flag
+         * and drop it — showing the hook consumer the retried answer glued onto
+         * the truncated one, which is ب١/٢ over again. `fireChunk` now carries the
+         * flag, so the loop can ask the one question worth asking: did the person
+         * on the far end of `onChunk` say they would act on it? Declared, the sink
+         * is wrapped and `withRetry` clears-and-restarts; undeclared, `isResetAware`
+         * is false in `retry.ts`, the ص١ mute path runs, and not a byte of this
+         * run differs from yesterday. The default did not move — it was extended.
          */
-        const chunkSink = config.hooks?.onChunk
-            ? (chunk) => fireChunk(config.hooks, sessionId, state.iteration, chunk.text)
+        const rawChunkSink = config.hooks?.onChunk
+            ? (chunk) => fireChunk(config.hooks, sessionId, state.iteration, chunk.text, chunk.reset)
             : undefined;
+        const chunkSink = rawChunkSink !== undefined && isResetAwareHook(config.hooks?.onChunk)
+            ? acceptResets(rawChunkSink)
+            : rawChunkSink;
         const toolDefs = toToolDefinitions(config.tools);
         const toolMap = new Map(config.tools.map((t) => [t.name, t]));
         const toolResults = [];
@@ -640,6 +762,15 @@ export function createAgent(config) {
              * 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.
+             *
+             * **And `model` is who answered, not who was asked** (س٦/٤). The request
+             * event carries `def.brain.model` — the configured name, which is the
+             * honest answer to "what did this agent ask for". It is NOT the honest
+             * answer to "what replied", and the two come apart the moment a host
+             * swaps the brain under a definition. So the responder travels on the
+             * payload, from the provider's own reply, and is written here beside the
+             * text it produced. A brain that does not report one writes no `model`
+             * key at all — an absent field, never an inferred one.
              */
             const logResponse = async (payload, stepId) => {
                 if (!turnLog)
@@ -649,6 +780,7 @@ export function createAgent(config) {
                 const text = payload.generation?.response_text ?? payload.final_output?.text;
                 const calls = orch?.action === "use_tool" ? stepToolCalls(orch) : [];
                 await writer.writeStep("model_response", stepId, {
+                    ...(payload.model !== undefined ? { model: payload.model } : {}),
                     ...(text !== undefined ? { text } : {}),
                     ...(calls.length > 0
                         ? {
@@ -760,6 +892,7 @@ export function createAgent(config) {
                                     terminatedBy: hardSignal.type,
                                     toolCalls: toolResults,
                                     ...(gated.validation ? { validation: gated.validation } : {}),
+                                    ...thoughtsOf(finalPayload, gated.validation),
                                 });
                             }
                         }
@@ -768,8 +901,15 @@ export function createAgent(config) {
                         }
                     }
                     // force_respond / escalate → emit last text if available
-                    const lastText = state.lastPayload?.generation?.response_text ??
-                        state.lastPayload?.final_output?.text ??
+                    //
+                    // Two sources, told apart on purpose (ت١/٢ item 4): text the model
+                    // wrote in its last payload, or the canned line below when it wrote
+                    // none. The last payload's `thoughts` rides out ONLY with the former
+                    // — thinking accompanies the answer it produced, never a sentence
+                    // the model did not write.
+                    const lastWritten = state.lastPayload?.generation?.response_text ??
+                        state.lastPayload?.final_output?.text;
+                    const lastText = lastWritten ??
                         "I was unable to complete this request within the allowed limits. Please try a more specific question.";
                     const gatedLast = await gateAndLog(lastText, stepId);
                     const outcomeType = gatedLast.validation?.action === "block"
@@ -786,6 +926,9 @@ export function createAgent(config) {
                         terminatedBy: hardSignal.type,
                         toolCalls: toolResults,
                         ...(gatedLast.validation ? { validation: gatedLast.validation } : {}),
+                        ...(lastWritten !== undefined
+                            ? thoughtsOf(state.lastPayload, gatedLast.validation)
+                            : {}),
                     });
                 }
                 // ── Context build ─────────────────────────────────────
@@ -889,8 +1032,7 @@ export function createAgent(config) {
                             agentName: def.name,
                             ...(event.tenantContext ? { tenantContext: event.tenantContext } : {}),
                         }, {
-                            redis,
-                            redisPrefix: tenantPrefix,
+                            dedup,
                             dedupTtlSeconds: ttl.toolDedup ?? 300,
                             ...(config.hooks?.onBeforeTool
                                 ? { hooks: { onBeforeTool: config.hooks.onBeforeTool } }
@@ -949,6 +1091,9 @@ export function createAgent(config) {
                     text: finalText,
                     toolCalls: toolResults,
                     ...(validation ? { validation } : {}),
+                    // The last step's thinking rides out with its answer (ت١) — and only
+                    // here, not into the log: the model never sees it again.
+                    ...thoughtsOf(payload, validation),
                 });
             }
         }
@@ -978,21 +1123,15 @@ export function createAgent(config) {
         }
     }
     async function kill(sessionId, companyId, agentType) {
-        const redis = await getRedis();
-        const p = companyId && agentType ? `${prefix}:${companyId}:${agentType}` : prefix;
-        const bus = new RedisControlBus(redis, p);
+        const bus = await resolveControlBus(commandPrefix(companyId, agentType));
         await bus.kill(sessionId);
     }
     async function pause(sessionId, companyId, agentType) {
-        const redis = await getRedis();
-        const p = companyId && agentType ? `${prefix}:${companyId}:${agentType}` : prefix;
-        const bus = new RedisControlBus(redis, p);
+        const bus = await resolveControlBus(commandPrefix(companyId, agentType));
         await bus.pause(sessionId);
     }
     async function resume(sessionId, companyId, agentType) {
-        const redis = await getRedis();
-        const p = companyId && agentType ? `${prefix}:${companyId}:${agentType}` : prefix;
-        const bus = new RedisControlBus(redis, p);
+        const bus = await resolveControlBus(commandPrefix(companyId, agentType));
         await bus.resume(sessionId);
     }
     return { handle, kill, pause, resume };
@@ -1086,6 +1225,31 @@ async function runWithTimeout(brainCall, budgetMs, controller) {
             clearTimeout(timer);
     }
 }
+/**
+ * `{ thoughts }` off the payload the outcome's text came from, or `{}` (ت١).
+ *
+ * Spread into the outcome at every site that takes its `text` from a payload,
+ * and nowhere else — the thinking travels with the answer it belongs to. A
+ * conditional spread so an outcome without thinking has no key, not an
+ * `undefined` one that `toEqual` would wave through (تعميم المجلس ٦).
+ *
+ * **A blocked answer takes its thinking with it** (ت١/٢ item 3). The output
+ * gate validates the TEXT; it never reads `thoughts`. So when the gate says
+ * `block` — the outcome is `suppressed` and the text is the canned line — the
+ * reasoning that produced the blocked answer is dropped too: what the gate
+ * would not let out as an answer does not leave as notes. On every other
+ * verdict (`release`, `review`, or no validator, including a gate that never
+ * ran because the text was empty) `thoughts` passes UNGATED — it is audit
+ * material for the host, declared as such on `LoopOutcome.thoughts`, and not
+ * a second answer for an end user.
+ */
+function thoughtsOf(payload, validation) {
+    if (validation?.action === "block")
+        return {};
+    return typeof payload?.thoughts === "string" && payload.thoughts !== ""
+        ? { thoughts: payload.thoughts }
+        : {};
+}
 function makeOutcome(type, sessionId, taskId, state, started, extra = {}) {
     return {
         type,