@msm-core/mini 0.9.0 → 0.14.0

package/CHANGELOG.md

@@ -3,6 +3,285 @@
 All notable changes are documented here.
 Follows [Semantic Versioning](https://semver.org/).
 
+> **Note on the gap (recorded 2026-09-01, session م١).** This ledger stopped at
+> `0.5.2` while six versions shipped — and `0.8.0` and `0.9.0` reached npm with
+> no entry to read. The entries from `0.6.0` down were written afterwards from
+> the session rulings in `docs/SESSIONS.md` and the commits that carried each
+> bump, not from memory; each is dated by that commit. The rule going forward:
+> whoever publishes keeps the ledger complete.
+
+---
+
+## [0.14.0] — 2026-09-01
+
+Session ص٤. The Redis-mandatory era ends.
+
+### Changed
+
+- `AgentConfig.redis` is **optional**. Present: byte-for-byte today's
+  behavior. Absent with all four ports injected (memory, controlBus, lock,
+  dedup): the loop runs with no Redis at all. Absent with any port missing:
+  `createAgent` fails immediately with an error that names the missing
+  port — and only it — and points at the `/adapters` in-memory
+  implementations. Absence is read from the VALUE (`=== undefined`), so a
+  host spreading `redis: undefined` gets the named error, not a TypeError
+  from the internals.
+
+## [0.13.0] — 2026-09-01
+
+Session س٦ (both rounds). The loop can now run with no Redis at all — and
+the audit log names the model that actually answered.
+
+### Added
+
+- Three injected ports on the س١ pattern: `ControlBusPort`, `RunLockPort`
+  (named to avoid `@msm-core/jobs`'s `LockPort` — the reason lives in the
+  port's own comment), `DedupPort` — `AgentConfig` accepts them optionally;
+  absent means the bundled Redis trio exactly as before. In-memory adapters
+  for all three; with all four ports injected the loop measurably issues
+  ZERO Redis calls.
+- Model truth: the four brains fill `BrainPayload.model` from the
+  provider's own reply — streamed and non-streamed both — and the loop
+  writes it to `model_response.data.model` (see `@msm-core/session` 0.3.0
+  for the event contract). `respondingModel` exported.
+
+### Notes
+
+- "Who injects a port injects its isolation" extends to the three new
+  ports, guarded behaviorally with two tenants.
+
+## [0.12.0] — 2026-09-01
+
+Session ص٣, entry with the bump (the new ledger guard enforces what
+Circular 2 asked by hand).
+
+### Added
+
+- The reset channel reaches `AgentHooks.onChunk`: `ChunkInfo.reset?: true`,
+  `fireChunk` spreads it, and a hooks consumer opts in with
+  `acceptChunkResets(hook)` (`isResetAwareHook`, `ResetAwareChunkHook`
+  exported). ص٢'s covenant one layer up: an undeclared consumer's chunks
+  are key-for-key what they always were — reset never reaches anyone who
+  did not ask for it.
+- Ledger guards in mini/session/replay/mcp: `package.json.version` must
+  equal the CHANGELOG head — no seventh unrecorded release.
+
+### Changed
+
+- mcp's spawned-process tests comply with Council Circular 1 (stderr in
+  every failure text, named waits, declared readiness) — diagnostics only;
+  the 98 tests and their assertions are unchanged.
+
+## [0.11.0] — 2026-09-01
+
+Session م١, entry by management at acceptance (Circular 2: the ledger rides
+with the bump, not behind it).
+
+### Added
+
+- `loadSkills(dir, log?)` in the definition layer — Claude-style skill packs
+  (`skills/<pack>/SKILL.md` folders and single `.md` files) read into one
+  `## Skills` markdown block for the host to append to an agent definition.
+  Lifted from nisus's `runtime/skills/loader.ts` and hardened: deterministic
+  code-unit ordering (platform-independent definitions — replay-stable
+  fingerprints), an injected `SkillsLogPort` instead of console, and empty
+  skill files contribute nothing rather than a bare separator (a declared,
+  parity-tested divergence from the original). Composition stays with the
+  host: the code moved, the wiring did not — zero loop changes.
+
+## [0.10.0] — 2026-09-01
+
+Session ص٢. A retried stream can finally repair the display it interrupted.
+
+### Added
+
+- **`BrainChunk.reset` — a retried call can tell you to clear what you drew.**
+  Since 0.9.1 a retried brain call stops re-emitting text you already saw, which
+  never truncates the payload but does leave the display frozen at the cut. A
+  consumer that *can* clear what it has drawn now opts in **on its sink**:
+  `acceptResets(sink)` marks it, `isResetAware(sink)` reports it, and
+  `ResetAwareChunkSink` is the type. A marked sink gets `reset: true` on the
+  first chunk after a retry and redraws the answer whole. **An unmarked sink is
+  on 0.9.1's path byte for byte** — the opt-in is the sink's, so a consumer that
+  does nothing sees nothing new.
+- New exports: `acceptResets`, `isResetAware`, type `ResetAwareChunkSink`.
+
+### Changed
+
+- Internal, no surface: every package's test tree is now type-checked by `tsc`
+  inside `npm test` (17 of 53 test files were under a compiler before; 54 of 54
+  now). This is why a type error can no longer sit green for months.
+
+---
+
+## [0.9.1] — 2026-09-01
+
+Session ص١ — three internal debts, two of them visible from outside.
+
+### Fixed
+
+- **A stamped tool's `destructive` / `category` now reach the model.**
+  `toToolDefinitions` declared both fields and dropped them on the way out, so a
+  tool marked destructive by the MCP adapter or by `createDelegateTool` was
+  described to the provider like any other tool. They are forwarded now.
+- **A retried brain call no longer streams the same words twice.** `withRetry`
+  restarted the provider call and the new attempt re-emitted text the consumer
+  had already rendered. The gate is keyed on **what was delivered**, not on the
+  attempt number: what reaches your `onChunk` is always a prefix of the final
+  payload — never longer than it, never contradicting it — and the worst case is
+  a display that stops where the cut happened rather than one that repeats or
+  truncates mid-sentence. Display only; `LoopOutcome` was always correct.
+
+### Changed
+
+- Internal: `mini`'s test tree is type-checked on every `npm test`. Nine
+  long-standing type errors in old tests were fixed **types only** — no test's
+  behavior and no test count changed.
+
+---
+
+## [0.9.0] — 2026-09-01
+
+Session ر٢. Delegation stops being a dead union member and becomes a tool.
+
+### Removed — ⚠️ a type breaks; no runtime does
+
+- **`"delegate"` is gone from the `BrainOrchestration.action` union.** It had
+  been declared since 0.1.0 and **the loop never executed it** — a brain
+  returning it fell through to the unknown-action path. Measured before the
+  removal: zero occurrences in `mini/src`, zero in nisus, and none of the four
+  brains ever emitted it. If you have a third-party brain that returns
+  `action: "delegate"`, it no longer type-checks, and at runtime it behaves
+  exactly as it always did: a terminal `respond` that delivers text and cannot
+  smuggle a tool call past the dispatcher (now pinned by a guard).
+
+### Added
+
+- **`createDelegateTool(delegates, opts?)` — one agent asks another, as an
+  ordinary `Tool`.** It returns a plain `call_agent` tool over
+  `Record<string, Agent>`, with the delegate names as an `enum` parameter so the
+  model cannot invent one. The child's session id is **derived**, not minted:
+  `${sessionId}.d.${name}` — deterministic, readable in a log, identical across
+  runs. The parent's `tenantContext` is inherited by the child.
+  `opts.maxDepth` (default 1) **fails closed** with a named `failed` result
+  rather than an exception. The child's cost comes back inside the tool result,
+  visible and not swallowed — it is deliberately *not* folded into the parent's
+  total, because counting it twice is worse than not counting it.
+  `opts.requiresApproval` / `destructive` / `category` stamp the definition, so
+  fail-closed approval covers a delegation with no new code.
+- New exports: `createDelegateTool`, `DELEGATE_TOOL_NAME`, types `DelegateTool`,
+  `DelegateToolOptions`.
+- **Zero loop changes.** A delegation passes guards, approval, dedup and the
+  session log exactly like any other tool — which is the whole argument for a
+  tool over an action.
+
+---
+
+## [0.8.0] — 2026-09-01
+
+Sessions ض١ and ب١. Two optional seats: one for compaction, one for streaming.
+
+### Added
+
+- **Streaming — `BrainRunInput.onChunk` and `AgentHooks.onChunk` (ب١).** All
+  four brains stream natively, each behind one branch; `BrainChunk` is
+  `{ text }`, and `ChunkInfo` adds `{ sessionId, iteration }` at the hook. Token
+  usage still arrives on the streamed path (`stream_options.include_usage`), so
+  `costCapPerTask` keeps working while streaming. **Streaming is display, not
+  truth**: no stream event is written to the session log, and
+  `@msm-core/replay`'s fingerprint is blind to `onChunk` — a run someone watched
+  and a run nobody watched are the same run. Without a handler the path is
+  literally the previous one, a single `if` apart.
+- **Compaction as an injected seat — `AgentConfig.compaction?: CompactionPort`
+  (ض١).** The port decides when a long conversation is summarised;
+  `createBrainCompactor(brain, opts?)` is one reference occupant that summarises
+  with a model you provide. The summary is written to the session log as a
+  `compaction` event, so it is auditable and re-derivable rather than a silent
+  trim, and a boundary never severs a tool call from its result
+  (`CompactionRangeError` names the attempt). **Without a `compaction` port
+  nothing changes**; without a `sessionLog` the seat is inert, declared.
+- New exports: `createBrainCompactor`; types `BrainCompactorOptions`,
+  `CompactionPort`, `CompactionDecision`, `ContextBudget`, `BrainChunk`,
+  `ChunkInfo`, `BrainToolCall`, `BrainOrchestration`.
+
+### Changed
+
+- Requires `@msm-core/session` `^0.2.0` — the `compaction` event is the tenth
+  member of that package's closed event union.
+
+---
+
+## [0.7.0] — 2026-09-01
+
+Sessions س٣ and س٤. Context starts being *derived*, and a step stops meaning one
+tool.
+
+### Added
+
+- **`AgentConfig.sessionLog?: SessionLogPort` — the loop writes an event log and
+  reads its context back out of it (س٣).** Injected, it inverts where
+  conversation context comes from: `deriveMessages(read())` instead of the
+  stored history array, with the same history budget applied. Events are written
+  **where they happen** — the user's message, each step, the raw pre-gate model
+  response, tool call/result pairs on every tool path (including refused and
+  unknown tools), guards that fired, the post-gate assistant message, and the
+  step's end on every exit including the `catch`. An invariant checks that every
+  field of `BrainRunInput` has exactly one counterpart in the log, and it runs
+  **before** the request goes to the model — a request that cannot be rebuilt
+  from the log should not be paid for. A rejected append fails the turn: the log
+  is the truth. **Absent, behavior is the previous version's bit for bit**;
+  `appendHistory` still runs, and the double write is transitional.
+- **`BrainOrchestration.tool_calls?: BrainToolCall[]` — many tools in ONE model
+  round-trip (س٤).** Three tools now cost two round-trips instead of four.
+  **A pure addition**: a brain that fills only `tool_name` / `tool_params` is
+  normalised to a single-call step and takes exactly the path it always took,
+  and a brain that fills the array fills those two with `tool_calls[0]` as well.
+  The covenant is one-directional — new readers may read the array, old readers
+  never find a hole where the first call used to be. Approval fails closed **per
+  call**, `onBeforeTool` and dedup run per call, and a failing sibling does not
+  kill the others.
+- New type `BrainToolCall`. New dependency: `@msm-core/session`.
+
+### Changed
+
+- **Tool turns are role-tagged deterministically across all four providers**
+  (`[tool_call:<id>]` / `[tool_result:<id>]`) instead of being flattened into a
+  bare `user` message. ⚠️ This changes the prompt text your provider receives: a
+  model reading back its own tool history can now tell which side was which.
+
+---
+
+## [0.6.0] — 2026-09-01
+
+Session س١. Session memory becomes a port.
+
+### Added
+
+- **`AgentConfig.memory?: SessionStore` — inject your own session store.** The
+  loop used to build `new RedisMemory(...)` by hand in two places that had
+  already drifted apart from each other in silence. There is now one port (six
+  functions, taken at `RedisMemory`'s exact signatures) and one construction
+  site: an injected store wins, and absent one `RedisMemory` is built exactly as
+  before. `RedisMemory` implements `SessionStore`, so an existing configuration
+  needs no change.
+- `InMemorySessionStore` in `@msm-core/mini/adapters` — a faithful RAM adapter
+  (tail limit, 500-entry cap, deep copy on both sides, so a returned reference
+  cannot be mutated into the store).
+- New exported types: `SessionStore`; and `SessionMetadata`, moved to
+  `core/types` with a back-compatible re-export from its old home (zero measured
+  breaks).
+
+### Note — the covenant that arrives with the port
+
+**Whoever injects a store injects its tenant isolation with it.** The loop
+cannot enforce the `{prefix}:{companyId}:{agentType}` rule on a port it cannot
+see into, so a store you supply owns its own tenant separation. The built-in
+`RedisMemory` path is unchanged and still guarded.
+
+`redis` remains required either way: the control bus, the distributed lock and
+the dedup cache are still Redis-backed by direct construction, so "a loop with
+no Redis at all" is not yet possible.
+
 ---
 
 ## [0.5.2] — 2026-07-01

package/dist/adapters/index.d.ts

@@ -10,7 +10,17 @@ export type { LockHandle } from "./redis-lock.js";
 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 in-RAM trio (س٦) — with `InMemorySessionStore` above, these are the four
+ * ports a loop needs, so an agent can run start to finish with no Redis at all.
+ * `InMemoryLock` is a real mutex, not a stub; see its file.
+ */
+export { InMemoryControlBus } from "./memory-control.js";
+export { InMemoryLock } from "./memory-lock.js";
+export { InMemoryToolDedup } from "./memory-dedup.js";
+/** The Redis-backed dedup, behind the port — what the loop builds when `dedup` is omitted. */
+export { RedisToolDedup } from "../tools/dedup.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";
+/** The ports `AgentConfig` accepts — for writing custom implementations. */
+export type { ControlBusPort, DedupPort, RunLockPort, SessionStore, } from "../core/types.js";

package/dist/adapters/index.js

@@ -8,3 +8,13 @@ export { RedisDistributedLock } from "./redis-lock.js";
 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 in-RAM trio (س٦) — with `InMemorySessionStore` above, these are the four
+ * ports a loop needs, so an agent can run start to finish with no Redis at all.
+ * `InMemoryLock` is a real mutex, not a stub; see its file.
+ */
+export { InMemoryControlBus } from "./memory-control.js";
+export { InMemoryLock } from "./memory-lock.js";
+export { InMemoryToolDedup } from "./memory-dedup.js";
+/** The Redis-backed dedup, behind the port — what the loop builds when `dedup` is omitted. */
+export { RedisToolDedup } from "../tools/dedup.js";

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

@@ -0,0 +1,43 @@
+/**
+ * In-memory ControlBusPort — kill / pause / disable-tool with no Redis.
+ *
+ * The bundled counterpart to `RedisControlBus`, held in process memory. It is
+ * what makes a single-process deploy (a desktop app, an air-gapped install) or
+ * a test able to steer a running agent at all: before س٦ the only bus was a
+ * Redis key, so "kill this session" required infrastructure.
+ *
+ * Fidelity to `RedisControlBus` is the point, and it is fidelity to the
+ * *semantics*, not just to the method names — the loop reads a command string
+ * and acts on its verb, so a mirror that stored a different vocabulary would be
+ * a mirror of nothing:
+ *   - `kill(id, reason)` stores `kill:{reason}`, default reason `"killed"` —
+ *     the loop's guard reports the part after the colon.
+ *   - `pause` stores `"pause"`; `disableTool` stores `disabled:{name}`.
+ *   - `resume` clears ONLY a pause. A killed session stays killed — the Redis
+ *     adapter reads before it deletes for exactly this reason, and a mirror
+ *     that "resumed" a kill would quietly revive an aborted run.
+ *   - one command per session: a later write replaces an earlier one.
+ *
+ * Scope: ONE process, and no expiry. The Redis bus gives a kill a 7-day TTL so
+ * the record outlives the worker that wrote it; nothing here outlives the
+ * process, so there is nothing to expire. For multi-replica deploys — where the
+ * whole point is that the killer and the killed are different processes — use
+ * `RedisControlBus`.
+ */
+import type { ControlBusPort } from "../core/types.js";
+export declare class InMemoryControlBus implements ControlBusPort {
+    private readonly commands;
+    getCommand(sessionId: string): Promise<string | null>;
+    kill(sessionId: string, reason?: string): Promise<void>;
+    pause(sessionId: string): Promise<void>;
+    /** Clears a pause and nothing else — a kill survives a resume. */
+    resume(sessionId: string): Promise<void>;
+    /**
+     * Refuse one tool for this session. Not part of `ControlBusPort` — the loop
+     * never writes it, it only reads the command — but present because the Redis
+     * bus has it and an operator on a no-Redis deploy needs the same lever.
+     */
+    disableTool(sessionId: string, toolName: string): Promise<void>;
+    /** Drop any command, whatever it is. Mirrors `RedisControlBus.clear`. */
+    clear(sessionId: string): Promise<void>;
+}

package/dist/adapters/memory-control.js

@@ -0,0 +1,56 @@
+/**
+ * In-memory ControlBusPort — kill / pause / disable-tool with no Redis.
+ *
+ * The bundled counterpart to `RedisControlBus`, held in process memory. It is
+ * what makes a single-process deploy (a desktop app, an air-gapped install) or
+ * a test able to steer a running agent at all: before س٦ the only bus was a
+ * Redis key, so "kill this session" required infrastructure.
+ *
+ * Fidelity to `RedisControlBus` is the point, and it is fidelity to the
+ * *semantics*, not just to the method names — the loop reads a command string
+ * and acts on its verb, so a mirror that stored a different vocabulary would be
+ * a mirror of nothing:
+ *   - `kill(id, reason)` stores `kill:{reason}`, default reason `"killed"` —
+ *     the loop's guard reports the part after the colon.
+ *   - `pause` stores `"pause"`; `disableTool` stores `disabled:{name}`.
+ *   - `resume` clears ONLY a pause. A killed session stays killed — the Redis
+ *     adapter reads before it deletes for exactly this reason, and a mirror
+ *     that "resumed" a kill would quietly revive an aborted run.
+ *   - one command per session: a later write replaces an earlier one.
+ *
+ * Scope: ONE process, and no expiry. The Redis bus gives a kill a 7-day TTL so
+ * the record outlives the worker that wrote it; nothing here outlives the
+ * process, so there is nothing to expire. For multi-replica deploys — where the
+ * whole point is that the killer and the killed are different processes — use
+ * `RedisControlBus`.
+ */
+export class InMemoryControlBus {
+    commands = new Map();
+    async getCommand(sessionId) {
+        return this.commands.get(sessionId) ?? null;
+    }
+    async kill(sessionId, reason = "killed") {
+        this.commands.set(sessionId, `kill:${reason}`);
+    }
+    async pause(sessionId) {
+        this.commands.set(sessionId, "pause");
+    }
+    /** Clears a pause and nothing else — a kill survives a resume. */
+    async resume(sessionId) {
+        if (this.commands.get(sessionId) === "pause") {
+            this.commands.delete(sessionId);
+        }
+    }
+    /**
+     * Refuse one tool for this session. Not part of `ControlBusPort` — the loop
+     * never writes it, it only reads the command — but present because the Redis
+     * bus has it and an operator on a no-Redis deploy needs the same lever.
+     */
+    async disableTool(sessionId, toolName) {
+        this.commands.set(sessionId, `disabled:${toolName}`);
+    }
+    /** Drop any command, whatever it is. Mirrors `RedisControlBus.clear`. */
+    async clear(sessionId) {
+        this.commands.delete(sessionId);
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * In-memory DedupPort — tool-call idempotency with no Redis.
+ *
+ * The bundled counterpart to the Redis-backed dedup (`RedisToolDedup`), held in
+ * process memory. It serves cached results **by the caller's own hash**, which
+ * is the only thing that makes it a mirror rather than a different feature: the
+ * hash is `hashToolCall(name, sortedArgs)` in both cases, so a call that Redis
+ * would have served from cache is served from cache here, and one it would have
+ * executed is executed here.
+ *
+ * Fidelity to the Redis semantics, in the two places they are not obvious:
+ *
+ *   - **The TTL is per session, and it slides.** The Redis adapter keeps ONE
+ *     hash per session and calls `EXPIRE` on that whole key at every store, so
+ *     one busy tool keeps the entire session's cache alive and the whole thing
+ *     drops together. This does the same: one `expiresAt` per session,
+ *     refreshed on every store, and an expired session's cache reads as empty.
+ *     A per-entry TTL would be the tidier design and would answer differently
+ *     from production on exactly the runs that matter — long ones.
+ *   - **Stored and returned values are deep-copied.** Redis stores JSON text,
+ *     so a cached result handed back is always a fresh object. Holding the
+ *     caller's reference instead would let a consumer that mutates a returned
+ *     `ToolResult` rewrite the cache under itself, and the difference would only
+ *     ever show up in production.
+ *
+ * Scope: ONE process. Two replicas each keep their own cache and will each run
+ * a call the other has already run — for shared dedup, use the Redis adapter.
+ */
+import type { DedupPort, ToolResult } from "../core/types.js";
+export declare class InMemoryToolDedup implements DedupPort {
+    private readonly sessions;
+    /** The live cache for a session, dropping it whole if its TTL has passed. */
+    private live;
+    check(sessionId: string, hash: string): Promise<ToolResult | null>;
+    store(sessionId: string, hash: string, result: ToolResult, ttlSeconds: number): Promise<void>;
+}

package/dist/adapters/memory-dedup.js

@@ -0,0 +1,59 @@
+/**
+ * In-memory DedupPort — tool-call idempotency with no Redis.
+ *
+ * The bundled counterpart to the Redis-backed dedup (`RedisToolDedup`), held in
+ * process memory. It serves cached results **by the caller's own hash**, which
+ * is the only thing that makes it a mirror rather than a different feature: the
+ * hash is `hashToolCall(name, sortedArgs)` in both cases, so a call that Redis
+ * would have served from cache is served from cache here, and one it would have
+ * executed is executed here.
+ *
+ * Fidelity to the Redis semantics, in the two places they are not obvious:
+ *
+ *   - **The TTL is per session, and it slides.** The Redis adapter keeps ONE
+ *     hash per session and calls `EXPIRE` on that whole key at every store, so
+ *     one busy tool keeps the entire session's cache alive and the whole thing
+ *     drops together. This does the same: one `expiresAt` per session,
+ *     refreshed on every store, and an expired session's cache reads as empty.
+ *     A per-entry TTL would be the tidier design and would answer differently
+ *     from production on exactly the runs that matter — long ones.
+ *   - **Stored and returned values are deep-copied.** Redis stores JSON text,
+ *     so a cached result handed back is always a fresh object. Holding the
+ *     caller's reference instead would let a consumer that mutates a returned
+ *     `ToolResult` rewrite the cache under itself, and the difference would only
+ *     ever show up in production.
+ *
+ * Scope: ONE process. Two replicas each keep their own cache and will each run
+ * a call the other has already run — for shared dedup, use the Redis adapter.
+ */
+/** Deep copy through JSON — the same serialization boundary Redis imposes. */
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export class InMemoryToolDedup {
+    sessions = new Map();
+    /** The live cache for a session, dropping it whole if its TTL has passed. */
+    live(sessionId) {
+        const cache = this.sessions.get(sessionId);
+        if (!cache)
+            return undefined;
+        if (cache.expiresAt <= Date.now()) {
+            this.sessions.delete(sessionId);
+            return undefined;
+        }
+        return cache;
+    }
+    async check(sessionId, hash) {
+        const found = this.live(sessionId)?.entries.get(hash);
+        return found ? clone(found) : null;
+    }
+    async store(sessionId, hash, result, ttlSeconds) {
+        const cache = this.live(sessionId) ?? {
+            entries: new Map(),
+            expiresAt: 0,
+        };
+        cache.entries.set(hash, clone(result));
+        cache.expiresAt = Date.now() + ttlSeconds * 1000;
+        this.sessions.set(sessionId, cache);
+    }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * In-memory RunLockPort — a session mutex with no Redis.
+ *
+ * **This one has to actually lock.** A stub that always grants would make every
+ * test of the no-Redis loop pass while removing the guarantee the lock exists
+ * for: one turn per session at a time. Two turns running into one session
+ * interleave their history writes and their log appends, and the damage is
+ * silent — a log with two turns braided together still reads as a log. So the
+ * in-RAM lock is a real mutex, and it is guarded by a test that starts a second
+ * turn while the first is still inside the brain call and watches it wait.
+ *
+ * Fidelity to `RedisDistributedLock`, semantics first:
+ *   - **held is held**: `acquire` returns `null` for a session already locked,
+ *     rather than a second handle.
+ *   - **TTL is honoured**: a lock past its `ttlMs` is treated as gone, exactly
+ *     as `SET PX` lets Redis drop it. A RAM lock that never expired would
+ *     deadlock a session that Redis would have freed — the mirror would be
+ *     safer than the original, which is its own kind of lie.
+ *   - **release and extend are token-checked**: only the holder's own handle
+ *     can release or extend, which is what the `GET == token` Lua scripts buy
+ *     on the Redis side. A late release from a previous holder whose lock has
+ *     already expired must not unlock the current one.
+ *   - **the retry loop is the same shape**: attempt, jittered sleep, deadline —
+ *     and the same error message when the deadline passes, because that string
+ *     is what surfaces from the loop when a session is genuinely stuck.
+ *
+ * Scope: ONE process. Across replicas this excludes nothing at all, and that is
+ * not a limitation to work around — a mutex for a single-process deploy is the
+ * whole of what it claims to be. Multi-replica deploys use
+ * `RedisDistributedLock`.
+ */
+import type { LockHandle, RunLockPort } from "../core/types.js";
+export declare class InMemoryLock implements RunLockPort {
+    private readonly held;
+    /** The live holder of this session, or `undefined` if free or expired. */
+    private current;
+    /**
+     * Take the lock, or return `null` if someone else holds it.
+     * Not required by `RunLockPort` — the loop only ever waits — but it is the
+     * primitive `acquireWithRetry` is built from, and `RedisDistributedLock`
+     * exposes it too.
+     */
+    acquire(sessionId: string, ttlMs: number): Promise<LockHandle | null>;
+    acquireWithRetry(sessionId: string, ttlMs: number, waitMs?: number, retryInterval?: number): Promise<LockHandle>;
+}

package/dist/adapters/memory-lock.js

@@ -0,0 +1,89 @@
+/**
+ * In-memory RunLockPort — a session mutex with no Redis.
+ *
+ * **This one has to actually lock.** A stub that always grants would make every
+ * test of the no-Redis loop pass while removing the guarantee the lock exists
+ * for: one turn per session at a time. Two turns running into one session
+ * interleave their history writes and their log appends, and the damage is
+ * silent — a log with two turns braided together still reads as a log. So the
+ * in-RAM lock is a real mutex, and it is guarded by a test that starts a second
+ * turn while the first is still inside the brain call and watches it wait.
+ *
+ * Fidelity to `RedisDistributedLock`, semantics first:
+ *   - **held is held**: `acquire` returns `null` for a session already locked,
+ *     rather than a second handle.
+ *   - **TTL is honoured**: a lock past its `ttlMs` is treated as gone, exactly
+ *     as `SET PX` lets Redis drop it. A RAM lock that never expired would
+ *     deadlock a session that Redis would have freed — the mirror would be
+ *     safer than the original, which is its own kind of lie.
+ *   - **release and extend are token-checked**: only the holder's own handle
+ *     can release or extend, which is what the `GET == token` Lua scripts buy
+ *     on the Redis side. A late release from a previous holder whose lock has
+ *     already expired must not unlock the current one.
+ *   - **the retry loop is the same shape**: attempt, jittered sleep, deadline —
+ *     and the same error message when the deadline passes, because that string
+ *     is what surfaces from the loop when a session is genuinely stuck.
+ *
+ * Scope: ONE process. Across replicas this excludes nothing at all, and that is
+ * not a limitation to work around — a mutex for a single-process deploy is the
+ * whole of what it claims to be. Multi-replica deploys use
+ * `RedisDistributedLock`.
+ */
+import { randomBytes } from "crypto";
+export class InMemoryLock {
+    held = new Map();
+    /** The live holder of this session, or `undefined` if free or expired. */
+    current(sessionId) {
+        const entry = this.held.get(sessionId);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.held.delete(sessionId);
+            return undefined;
+        }
+        return entry;
+    }
+    /**
+     * Take the lock, or return `null` if someone else holds it.
+     * Not required by `RunLockPort` — the loop only ever waits — but it is the
+     * primitive `acquireWithRetry` is built from, and `RedisDistributedLock`
+     * exposes it too.
+     */
+    async acquire(sessionId, ttlMs) {
+        if (this.current(sessionId))
+            return null;
+        const token = randomBytes(16).toString("hex");
+        this.held.set(sessionId, { token, expiresAt: Date.now() + ttlMs });
+        const ownsIt = () => this.current(sessionId)?.token === token;
+        return {
+            release: async () => {
+                // Token-checked: a handle whose lock already expired and was retaken
+                // must not release the new holder's lock.
+                if (ownsIt())
+                    this.held.delete(sessionId);
+            },
+            extend: async (newTtlMs) => {
+                if (!ownsIt())
+                    return false;
+                this.held.set(sessionId, {
+                    token,
+                    expiresAt: Date.now() + newTtlMs,
+                });
+                return true;
+            },
+        };
+    }
+    async acquireWithRetry(sessionId, ttlMs, waitMs = 5000, retryInterval = 100) {
+        const deadline = Date.now() + waitMs;
+        while (Date.now() < deadline) {
+            const handle = await this.acquire(sessionId, ttlMs);
+            if (handle)
+                return handle;
+            await sleep(retryInterval + Math.random() * 50);
+        }
+        throw new Error(`msm-mini: could not acquire lock for session ${sessionId} within ${waitMs}ms`);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -7,7 +7,8 @@
  * Checked on every loop iteration before the brain call.
  */
 import type { RedisLike } from "./redis-types.js";
-export declare class RedisControlBus {
+import type { ControlBusPort } from "../core/types.js";
+export declare class RedisControlBus implements ControlBusPort {
     private readonly redis;
     private readonly prefix;
     constructor(redis: RedisLike, prefix?: string);