@msm-core/mini 0.9.0 → 0.14.0

package/dist/core/hooks.d.ts

@@ -10,13 +10,25 @@ export declare function fireSectionComplete(hooks: AgentHooks | undefined, sessi
 export declare function fireToolCall(hooks: AgentHooks | undefined, sessionId: string, result: ToolResult, iteration: number, cached: boolean, durationMs: number): void;
 export declare function fireGuard(hooks: AgentHooks | undefined, sessionId: string, signal: GuardSignal, iteration: number): void;
 /**
- * One streamed piece of model text (ب١).
+ * One streamed piece of model text (ب١), carrying `reset` when there is one
+ * and a consumer who asked for it (ص٣/٢).
  *
  * Same shape as its siblings, and the same contract: `safely` swallows a
  * throwing hook. That matters more here than anywhere else — this one fires
  * dozens of times per step, in the middle of reading a provider stream, and a
  * consumer whose SSE socket closed mid-answer must not take the run down with
  * it. A failed display is a failed display, not a failed run.
+ *
+ * **`reset` is spread, not assigned.** `{ sessionId, iteration, text }` is what
+ * an undeclared consumer received before this parameter existed and it is
+ * exactly what it receives now — the key is ABSENT, not present-and-undefined,
+ * so `Object.keys`, `toEqual`, `JSON.stringify` and a `for…in` all see what
+ * they saw yesterday. That equality is the mandatory control of ص٣/٢, and
+ * writing `reset` unconditionally would have broken it while every existing
+ * assertion stayed green.
+ *
+ * The parameter is optional and last, so the pre-ص٣ call shape still compiles
+ * and still means what it meant.
  */
-export declare function fireChunk(hooks: AgentHooks | undefined, sessionId: string, iteration: number, text: string): void;
+export declare function fireChunk(hooks: AgentHooks | undefined, sessionId: string, iteration: number, text: string, reset?: true): void;
 export declare function fireFatalError(hooks: AgentHooks | undefined, error: Error, sessionId: string): void;

package/dist/core/hooks.js

@@ -54,18 +54,35 @@ export function fireGuard(hooks, sessionId, signal, iteration) {
     safely(() => hooks.onGuard({ sessionId, signal, iteration }));
 }
 /**
- * One streamed piece of model text (ب١).
+ * One streamed piece of model text (ب١), carrying `reset` when there is one
+ * and a consumer who asked for it (ص٣/٢).
  *
  * Same shape as its siblings, and the same contract: `safely` swallows a
  * throwing hook. That matters more here than anywhere else — this one fires
  * dozens of times per step, in the middle of reading a provider stream, and a
  * consumer whose SSE socket closed mid-answer must not take the run down with
  * it. A failed display is a failed display, not a failed run.
+ *
+ * **`reset` is spread, not assigned.** `{ sessionId, iteration, text }` is what
+ * an undeclared consumer received before this parameter existed and it is
+ * exactly what it receives now — the key is ABSENT, not present-and-undefined,
+ * so `Object.keys`, `toEqual`, `JSON.stringify` and a `for…in` all see what
+ * they saw yesterday. That equality is the mandatory control of ص٣/٢, and
+ * writing `reset` unconditionally would have broken it while every existing
+ * assertion stayed green.
+ *
+ * The parameter is optional and last, so the pre-ص٣ call shape still compiles
+ * and still means what it meant.
  */
-export function fireChunk(hooks, sessionId, iteration, text) {
+export function fireChunk(hooks, sessionId, iteration, text, reset) {
     if (!hooks?.onChunk)
         return;
-    safely(() => hooks.onChunk({ sessionId, iteration, text }));
+    safely(() => hooks.onChunk({
+        sessionId,
+        iteration,
+        text,
+        ...(reset === true ? { reset } : {}),
+    }));
 }
 export function fireFatalError(hooks, error, sessionId) {
     if (!hooks?.onFatalError)

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
                         ? {
@@ -889,8 +1021,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 } }
@@ -978,21 +1109,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 };