@msm-core/mini 0.8.0 → 0.14.0

package/dist/core/types.d.ts

@@ -142,7 +142,108 @@ export interface BrainRunInput {
  */
 export interface BrainChunk {
     text: string;
+    /**
+     * "Discard everything I have sent you; this text starts over." (ص٢/٢)
+     *
+     * Set on the FIRST chunk a retried attempt delivers, and on no other. ص١
+     * bought the display invariant — what reaches the reader is always a prefix
+     * of the payload — by muting the retry outright, which is honest but costs
+     * the tail of the answer: the display stops where the dead attempt stopped.
+     * This flag is what buys the same invariant WITHOUT that cost, because a
+     * reader who can clear what it drew has no prefix to contradict.
+     *
+     * **It never reaches a consumer that did not ask for it.** The sink has to
+     * declare itself with `acceptResets` (see `ResetAwareChunkSink`); everything
+     * else takes the ص١ path unchanged, byte for byte. That is deliberate: a
+     * consumer that appends chunks and ignores this field would render "The
+     * contract staThe contract states…" — the exact defect ب١/٢ opened — so the
+     * flag is delivered only where someone has said, in the type system, that
+     * they will act on it.
+     *
+     * `true` and absent are the only two states. There is no `reset: false`: a
+     * chunk either says "start over" or says nothing, and an optional literal
+     * makes the compiler enforce that rather than a code review.
+     */
+    reset?: true;
+}
+/**
+ * A chunk sink that has DECLARED it understands `BrainChunk.reset` (ص٢/٢).
+ *
+ * The declaration lives on the sink rather than in `BrainRunInput` or
+ * `RetryOpts`, and the reason is measured, not stylistic: the gate that decides
+ * to reset lives in `brain/retry.ts`, and the ONLY thing that crosses from a
+ * brain's input into that gate is the sink itself (`emitOnce(input.onChunk!)`).
+ * `RetryOpts` carries `signal` alone, and widening either it or `BrainRunInput`
+ * would mean editing all four brains to forward the new field. Attaching the
+ * declaration to the sink also makes it unmisplaceable: a consumer cannot
+ * declare reset support and then hand over a different callback.
+ *
+ * It also costs the replay harness nothing. `keyof BrainRunInput` does not
+ * change, so `InputKeysArePartitioned` in `@msm-core/replay` is untouched and
+ * no fingerprint moves — the ب١ precedent of a declared breach is not needed
+ * here, because there is no breach.
+ */
+export interface ResetAwareChunkSink {
+    (chunk: BrainChunk): void;
+    /** The declaration itself. Read by `isResetAware`, never by a brain. */
+    readonly acceptsReset: true;
+}
+/**
+ * Declare that a chunk sink can handle `reset` — the opt-in, and the only way
+ * a `reset` chunk is ever produced.
+ *
+ * The contract you are signing: **when a chunk arrives with `reset: true`,
+ * throw away everything you have rendered for this call and start from that
+ * chunk.** Do that and the text you hold when the call returns is exactly the
+ * payload, with nothing missing and nothing shown twice.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export declare function acceptResets(sink: (chunk: BrainChunk) => void): ResetAwareChunkSink;
+/** True for a sink that went through `acceptResets`. */
+export declare function isResetAware(sink: unknown): sink is ResetAwareChunkSink;
+/**
+ * An `AgentHooks.onChunk` that has DECLARED it understands `ChunkInfo.reset`
+ * (ص٣/٢) — the same opt-in as `ResetAwareChunkSink`, one layer out.
+ *
+ * ص٢ carried `reset` as far as a brain's chunk sink and stopped, because the
+ * loop's own sink drops everything but `text` into `fireChunk` and a declared
+ * loop sink would therefore have taken the flag and thrown it away — handing
+ * the hook consumer the duplicated display ب١/٢ exists to prevent. This type
+ * is the missing half: with it the loop can tell whether the person on the far
+ * end of `onChunk` will act on a reset, and it declares to the brain only when
+ * they will.
+ *
+ * **It is the same shape and the same marker as `ResetAwareChunkSink` on
+ * purpose.** A consumer who has learned the opt-in once has learned it in both
+ * places, and the loop's job stays a single question — did they declare? —
+ * rather than a translation between two conventions.
+ *
+ * Note that `AgentHooks.onChunk` needs no widening to accept this: a function
+ * carrying an extra property is already assignable to `(info: ChunkInfo) =>
+ * void`. The published signature of `AgentHooks` does not move.
+ */
+export interface ResetAwareChunkHook {
+    (info: ChunkInfo): void;
+    /** The declaration itself. Read by `isResetAwareHook`, never by a brain. */
+    readonly acceptsReset: true;
 }
+/**
+ * Declare that an `onChunk` hook can handle `ChunkInfo.reset` — the opt-in,
+ * and the only way a `reset` ever reaches a hook consumer.
+ *
+ * The contract you are signing: **when a `ChunkInfo` arrives with
+ * `reset: true`, throw away every chunk you have rendered for this step and
+ * start again from that one.** Do that and the text you hold at the end of the
+ * step is exactly the answer, with nothing missing and nothing shown twice.
+ * Ignore it and you would render the retried answer glued onto the truncated
+ * one — which is why the flag is delivered nowhere else.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export declare function acceptChunkResets(hook: (info: ChunkInfo) => void): ResetAwareChunkHook;
+/** True for an `onChunk` hook that went through `acceptChunkResets`. */
+export declare function isResetAwareHook(hook: unknown): hook is ResetAwareChunkHook;
 /**
  * One tool invocation a model asked for, in the model's own order.
  *
@@ -154,8 +255,45 @@ export interface BrainToolCall {
     name: string;
     params: Record<string, unknown>;
 }
+/**
+ * Every action the loop DISPATCHES ON — declared as data, and the only list.
+ *
+ * ── Why this is a `const` array and not an inline union (ر٢) ────────────────
+ *
+ * There were two lists. This union, and a second copy in `bridge/pipeline.ts`
+ * that normalises whatever a duck-typed pipeline hands back. Both carried a
+ * fifth member the loop never dispatched on — a routing action that was
+ * declared at the beginning, implemented nowhere, and used by nobody (measured:
+ * zero occurrences in the live consumer). It survived precisely because
+ * deleting it meant finding and agreeing two places, and س١'s lesson is that
+ * two lists of the same thing drift apart silently and are only noticed by the
+ * damage.
+ *
+ * So there is now one list. The union below is derived from it and the bridge
+ * validates against it, which means a member cannot be added to one and
+ * forgotten in the other, and a member cannot be REMOVED from one and left
+ * standing in the other. `BrainActionsAreTheFourLiveOnes` then makes growing
+ * this array a decision someone has to write down rather than one that happens
+ * by omission.
+ *
+ * **What the loop actually does with each** (`core/loop.ts`):
+ *   - `use_tool`  → the step's tool calls run, then back to the model.
+ *   - `clarify` / `escalate` → terminal, and the outcome carries that type.
+ *   - `respond`   → terminal, the text is delivered.
+ *
+ * And an action that is NONE of these — a rogue model emitting a string at
+ * runtime, where no type can stop it — takes the `respond` path: terminal,
+ * one iteration, whatever text the payload carried. That is the existing
+ * behaviour, it is fail-safe (a nonsense action never loops and never runs a
+ * tool), and it is pinned by a guard in `tests/delegate.test.ts` rather than
+ * left as an accident. The bridge's `respond` fallback for an unrecognised
+ * string is the same rule stated one layer earlier.
+ */
+export declare const BRAIN_ACTIONS: readonly ["use_tool", "respond", "clarify", "escalate"];
+/** What a model may ask the loop to do. Derived from `BRAIN_ACTIONS`. */
+export type BrainAction = (typeof BRAIN_ACTIONS)[number];
 export interface BrainOrchestration {
-    action: "use_tool" | "respond" | "clarify" | "escalate" | "delegate";
+    action: BrainAction;
     confidence: number;
     /**
      * The FIRST call of the step. Always filled whenever `tool_calls` is —
@@ -200,8 +338,56 @@ export interface BrainPayload {
         inputTokens?: number;
         outputTokens?: number;
     };
+    /**
+     * **Who actually answered** — the model as the PROVIDER's own reply named it.
+     *
+     * Not the model that was asked for. The two differ more often than they look
+     * like they should: a host swaps the brain under an agent definition at
+     * composition time (an `llmOverride`), a gateway routes a request elsewhere,
+     * or a provider resolves an alias to a dated snapshot. In every one of those
+     * cases the configured name is what the request *intended* and this is what
+     * the request *got*, and only the second can answer "which model wrote this?"
+     * about a reply already sent.
+     *
+     * The loop copies it into `model_response.data.model` in the session log,
+     * beside `model_request.data.model`, which keeps its own meaning — the
+     * requested/configured name. Two fields, two questions, neither guessing.
+     *
+     * **Optional, and absent means absent.** A brain that cannot know (a scripted
+     * one, or a provider whose reply does not name a model) leaves it off, and
+     * the log carries no `model` on that response rather than a plausible
+     * fabrication. Anything derived from the configured name would be exactly the
+     * falsehood this field exists to stop telling.
+     */
+    model?: string;
     [key: string]: unknown;
 }
+/**
+ * The responder's name lifted off a raw provider reply — `{}` when it named none.
+ *
+ * Spread into a `BrainPayload` by all four bundled brains, so the reading exists
+ * once. Four copies of the same check in four files is four chances to drift,
+ * and the one difference between them (Gemini spells the field `modelVersion`;
+ * OpenAI, Anthropic and Ollama spell it `model`) is a fact about wire formats
+ * that belongs written down, not re-derived per file.
+ *
+ * **Why the parameter is `unknown`, and why there is no cast anyway.** The
+ * declared shape of each provider response in `brain/streaming.ts` is exactly
+ * the set of fields its brain reads — by design, stated there — and that set
+ * does not include the model name. A parameter typed `{ model?: unknown }`
+ * would therefore be rejected for every real argument: TypeScript's weak-type
+ * check refuses an object that shares no property with an all-optional target,
+ * which is precisely the situation here. So this takes what it is really given
+ * — an object off a wire — and narrows it at runtime with `typeof` and `in`.
+ * Nothing is asserted about it that has not just been tested.
+ *
+ * A reply that carries no name, or a non-string one, yields `{}`: the payload
+ * gets no `model` key, and the log records the absence honestly instead of
+ * inventing a name from the request.
+ */
+export declare function respondingModel(reply: unknown): {
+    model?: string;
+};
 /** The Brain interface — any model that implements this works with msm-mini */
 export interface Brain {
     name: string;
@@ -328,7 +514,9 @@ export interface SessionMetadata {
  *
  * The loop talks to this interface and never to a concrete store. Inject an
  * implementation via `AgentConfig.memory`; when it is omitted the loop builds
- * the bundled `RedisMemory` from `AgentConfig.redis` exactly as it always has.
+ * the bundled `RedisMemory` from `AgentConfig.redis` exactly as it always has —
+ * and when `redis` is omitted too, `createAgent` refuses the composition by
+ * name rather than failing on the first history read (ص٤).
  *
  * Six functions — the surface `RedisMemory` already had, at its current
  * signatures. Nothing is added speculatively: an append-only event log is a
@@ -344,6 +532,103 @@ export interface SessionStore {
     getDocumentState(sessionId: string): Promise<DocumentState | null>;
     setDocumentState(sessionId: string, state: DocumentState): Promise<void>;
 }
+/**
+ * The control bus PORT — out-of-band commands for a running session.
+ *
+ * One string per session, read once at the top of every loop iteration, before
+ * the model is called. The **command vocabulary is part of this contract**,
+ * because the loop interprets it (`checkGuards`, `RedisControlBus.disabledTool`):
+ *
+ *   - `null`                — no command; the run proceeds.
+ *   - `"kill"` / `"kill:{reason}"` — hard abort, `terminatedBy: "task_killed"`.
+ *   - `"pause"`             — hard abort, `terminatedBy: "tenant_paused"`.
+ *   - `"disabled:{tool}"`   — that one tool is refused for the step; its
+ *                             siblings run.
+ *
+ * A verb is matched on the part before the first `:`, so an unknown verb is
+ * simply not a command anyone acts on — an implementation may carry its own
+ * without breaking the loop.
+ */
+export interface ControlBusPort {
+    /** The current command for this session, or `null` when there is none. */
+    getCommand(sessionId: string): Promise<string | null>;
+    /** Write a kill command. `reason` rides along in the guard's message. */
+    kill(sessionId: string, reason?: string): Promise<void>;
+    pause(sessionId: string): Promise<void>;
+    /** Clear a pause. A `kill` is deliberately NOT cleared by this. */
+    resume(sessionId: string): Promise<void>;
+}
+/**
+ * A held session lock. `release()` is called on every exit path of the loop —
+ * normal, guard-terminated and error — and `extend()` is for a holder that
+ * outlives its own TTL.
+ *
+ * Declared here rather than in the Redis adapter for the same reason
+ * `SessionMetadata` moved in س١: it is part of the contract every lock
+ * implements, not a detail of one of them. `adapters/redis-lock.ts` re-exports
+ * it, so every existing import keeps working unchanged.
+ */
+export interface LockHandle {
+    release(): Promise<void>;
+    extend(ttlMs: number): Promise<boolean>;
+}
+/**
+ * The session run-lock PORT — one turn per session at a time.
+ *
+ * **Named `RunLockPort`, not `LockPort`, deliberately.** `@msm-core/jobs` has
+ * exported a `LockPort` since long before this existed and it is a different
+ * contract entirely (`acquire(key, ttlMs): Promise<boolean>` — no handle, no
+ * release); nisus imports it today. Two packages of one SDK exporting one name
+ * for two contracts is a collision a consumer pays for in aliases forever, and
+ * it costs nothing to avoid before the first publish. The name is also the
+ * truer one: what this guards is a session's RUN, one turn at a time.
+ *
+ * The loop acquires before it does anything with the session and releases on
+ * every way out. This is the port whose in-RAM implementation has to be a real
+ * mutex and not a stub: a lock that always says yes turns "two workers cannot
+ * enter the same session" into a comment, and the failure it prevents (two
+ * turns interleaving their writes into one log) is silent when it happens.
+ *
+ * The loop calls only `acquireWithRetry` — waiting for a busy session is the
+ * behaviour it wants, so that is the surface extracted. Implementations are
+ * free to expose a non-blocking `acquire` beside it; the port does not require
+ * one because nothing in the loop asks for it.
+ */
+export interface RunLockPort {
+    /**
+     * Acquire, retrying until `waitMs` elapses. Throws when it cannot.
+     *
+     * @param ttlMs         lifetime of the lock — the loop passes the effective
+     *                      turn timeout plus a safety margin, so a lock never
+     *                      expires under a run that is still going.
+     * @param waitMs        how long to keep trying (adapter default: 5000).
+     * @param retryInterval base delay between attempts (adapter default: 100).
+     */
+    acquireWithRetry(sessionId: string, ttlMs: number, waitMs?: number, retryInterval?: number): Promise<LockHandle>;
+}
+/**
+ * The tool-dedup PORT — idempotency for repeated tool calls within a session.
+ *
+ * Keyed by `(sessionId, hash)`, where the hash is `hashToolCall(name, args)`:
+ * a deterministic SHA-256 of the tool name and its key-sorted arguments. The
+ * hashing stays a pure function in `tools/dedup.ts` — it is not I/O and there
+ * is nothing to swap about it — so an implementation of this port is only ever
+ * asked to store and fetch by a key it is handed.
+ *
+ * **Only `ok` results are ever stored** (the executor's rule, not the port's):
+ * a failure is worth retrying, and caching one would freeze a transient outage
+ * into the session for the whole TTL.
+ */
+export interface DedupPort {
+    /** A previously stored result for this exact call, or `null`. */
+    check(sessionId: string, hash: string): Promise<ToolResult | null>;
+    /**
+     * Remember a result for `ttlSeconds`. An implementation with no notion of
+     * expiry may ignore the TTL — it is a hint about staleness, and the loop
+     * passes `redis.ttl.toolDedup ?? 300` for it.
+     */
+    store(sessionId: string, hash: string, result: ToolResult, ttlSeconds: number): Promise<void>;
+}
 /**
  * What a compactor decides when it decides to compact.
  *
@@ -443,7 +728,34 @@ export interface AgentConfig {
     /** Path to .md definition file or pre-parsed AgentDefinition object */
     definition: string | AgentDefinition;
     brain: Brain;
-    redis: RedisConfig;
+    /**
+     * Redis connection for the four ports Redis can back: session `memory`, the
+     * `controlBus`, the run `lock` and tool `dedup`.
+     *
+     * **Optional (ص٤) — and only because س٦ earned it.** While the trio was
+     * `new`-ed inside the loop, `redis` was load-bearing for every run and being
+     * required was simply true. س٦ made all four injectable and proved a whole
+     * turn runs without opening a connection; the field stayed required after
+     * that for no reason but the calendar, so a fully-injected caller had to hand
+     * over an object it never used. The rule that replaces the requirement:
+     *
+     *   - **Present** — nothing changes, for anyone. Every port that is not
+     *     injected is built from this exactly as it always was: same
+     *     `{prefix}:{companyId}:{agentType}` scoping, same key shapes, same TTLs,
+     *     same moment of connection. `{}` is *present*, not absent: it has
+     *     neither `url` nor `client`, so the first port that reaches for it
+     *     throws as it always has — which is precisely what makes it useful as a
+     *     test config that fails loudly if anything opens Redis.
+     *   - **Absent** — every one of the four ports MUST be injected, because
+     *     there is nothing left to fall back to. A composition that omits one
+     *     is rejected by `createAgent` with an error naming the missing field;
+     *     see the check at the top of `createAgent`.
+     *
+     * Absence is read from the value (`undefined`), not from the key, so a host
+     * that spreads an options object with `redis: undefined` in it gets the same
+     * named composition error rather than a crash inside a turn.
+     */
+    redis?: RedisConfig;
     /**
      * Optional session-memory port. When injected, the loop routes ALL history /
      * metadata / document-state access through it and never constructs a
@@ -451,10 +763,61 @@ export interface AgentConfig {
      * `redis` exactly as before — same prefix, same TTLs, same tenant scoping —
      * so every existing consumer is unaffected.
      *
-     * `redis` stays required either way: the control bus, the session lock and
-     * tool dedup are separate ports and still ride on it.
+     * Isolation is the injector's (س١ ruling 3): this port takes a `sessionId`
+     * and knows nothing of tenants. Whoever injects a store injects its tenant
+     * scoping with it.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤) — not a run that fails on its first history read.
      */
     memory?: SessionStore;
+    /**
+     * Optional **control-bus port** — kill / pause / disable-tool commands.
+     *
+     * Injected, the loop reads its commands and `agent.kill/pause/resume()` write
+     * through it. Omitted, the loop builds `RedisControlBus` from `redis` exactly
+     * as before: same `{prefix}:{companyId}:{agentType}` tenant scoping, same
+     * `:agent:control:{sessionId}` key, same 7-day TTL on a kill.
+     *
+     * Isolation is the injector's, as with `memory`. Note in particular that
+     * `agent.kill(sessionId, companyId, agentType)` computes a tenant-scoped
+     * prefix for the FALLBACK bus only — an injected bus receives the session id
+     * and nothing else, and must scope its own keys.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤).
+     */
+    controlBus?: ControlBusPort;
+    /**
+     * Optional **session-lock port** — one turn per session at a time.
+     *
+     * Omitted, the loop builds `RedisDistributedLock` from `redis` exactly as
+     * before (`SET NX PX` on `{prefix}:session:{id}:lock`, released by token).
+     *
+     * An injected lock must actually exclude, or it is not a lock. In-process
+     * (`InMemoryLock`) that means one process; across replicas it means a shared
+     * one. Isolation is the injector's here too: two tenants that share one
+     * injected lock share its key space, and a session id colliding across them
+     * will serialise turns that have nothing to do with each other.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤).
+     */
+    lock?: RunLockPort;
+    /**
+     * Optional **tool-dedup port** — idempotency for repeated tool calls.
+     *
+     * Omitted, the loop builds the Redis-backed dedup from `redis` exactly as
+     * before: `{prefix}:session:{id}:tools:dedup` as a hash, the call hash as the
+     * field, `EXPIRE` refreshed on every store.
+     *
+     * Isolation is the injector's: a dedup shared unscoped between tenants can
+     * serve one tenant's cached tool result to another's identical call.
+     *
+     * Omitting this **and** `redis` is a composition error, raised at
+     * `createAgent` (ص٤).
+     */
+    dedup?: DedupPort;
     /**
      * Optional session **event log** (`@msm-core/session`). Injecting it inverts
      * where conversation context comes from:
@@ -553,6 +916,25 @@ export interface ChunkInfo {
     /** The delta — not the running total. Concatenating every chunk of a step
      *  yields the text that step's payload carries. */
     text: string;
+    /**
+     * "Discard everything I have sent you for this step; it starts over." (ص٣/٢)
+     *
+     * The hook-side face of `BrainChunk.reset`. Set on the FIRST chunk a retried
+     * attempt delivers, and on no other, so a consumer that clears and restarts
+     * on it ends the step holding exactly the answer — no truncation from the
+     * attempt that died, no duplication from the one that succeeded.
+     *
+     * **It never reaches a consumer that did not ask for it.** The hook must go
+     * through `acceptChunkResets` (see `ResetAwareChunkHook`); for every other
+     * hook the loop hands the brain an undeclared sink, `brain/retry.ts` takes
+     * the ص١ mute path, and the object delivered here carries the same three
+     * keys it carried before this field existed — the key is not merely
+     * `undefined`, it is absent. That is deliberate: a consumer that appends
+     * chunks and ignores this field would render the answer twice over.
+     *
+     * `true` and absent are the only two states, as on `BrainChunk`.
+     */
+    reset?: true;
 }
 /**
  * Return value from onBeforeTool hook:

package/dist/core/types.js

@@ -4,4 +4,133 @@
  * All contracts for the lite agent runtime. Brain-agnostic, zero embedded
  * databases. Application layer owns persistence; agent owns the loop.
  */
-export {};
+/**
+ * Declare that a chunk sink can handle `reset` — the opt-in, and the only way
+ * a `reset` chunk is ever produced.
+ *
+ * The contract you are signing: **when a chunk arrives with `reset: true`,
+ * throw away everything you have rendered for this call and start from that
+ * chunk.** Do that and the text you hold when the call returns is exactly the
+ * payload, with nothing missing and nothing shown twice.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export function acceptResets(sink) {
+    const declared = (chunk) => {
+        sink(chunk);
+    };
+    return Object.assign(declared, { acceptsReset: true });
+}
+/**
+ * The declaration marker, read in ONE place (ص٣/٢).
+ *
+ * There are two public predicates over this marker — one for a brain's chunk
+ * sink, one for the `AgentHooks.onChunk` a person writes — and س١'s rule is
+ * that two lookalikes drift apart in silence. They share this body so there is
+ * nothing to drift: the marker `acceptResets` and `acceptChunkResets` stamp is
+ * the same marker, and it is recognised the same way or not at all.
+ */
+function declaresResets(value) {
+    return (typeof value === "function" &&
+        value.acceptsReset === true);
+}
+/** True for a sink that went through `acceptResets`. */
+export function isResetAware(sink) {
+    return declaresResets(sink);
+}
+/**
+ * Declare that an `onChunk` hook can handle `ChunkInfo.reset` — the opt-in,
+ * and the only way a `reset` ever reaches a hook consumer.
+ *
+ * The contract you are signing: **when a `ChunkInfo` arrives with
+ * `reset: true`, throw away every chunk you have rendered for this step and
+ * start again from that one.** Do that and the text you hold at the end of the
+ * step is exactly the answer, with nothing missing and nothing shown twice.
+ * Ignore it and you would render the retried answer glued onto the truncated
+ * one — which is why the flag is delivered nowhere else.
+ *
+ * Returns a NEW function; the one you pass is not mutated.
+ */
+export function acceptChunkResets(hook) {
+    const declared = (info) => {
+        hook(info);
+    };
+    return Object.assign(declared, { acceptsReset: true });
+}
+/** True for an `onChunk` hook that went through `acceptChunkResets`. */
+export function isResetAwareHook(hook) {
+    return declaresResets(hook);
+}
+/**
+ * Every action the loop DISPATCHES ON — declared as data, and the only list.
+ *
+ * ── Why this is a `const` array and not an inline union (ر٢) ────────────────
+ *
+ * There were two lists. This union, and a second copy in `bridge/pipeline.ts`
+ * that normalises whatever a duck-typed pipeline hands back. Both carried a
+ * fifth member the loop never dispatched on — a routing action that was
+ * declared at the beginning, implemented nowhere, and used by nobody (measured:
+ * zero occurrences in the live consumer). It survived precisely because
+ * deleting it meant finding and agreeing two places, and س١'s lesson is that
+ * two lists of the same thing drift apart silently and are only noticed by the
+ * damage.
+ *
+ * So there is now one list. The union below is derived from it and the bridge
+ * validates against it, which means a member cannot be added to one and
+ * forgotten in the other, and a member cannot be REMOVED from one and left
+ * standing in the other. `BrainActionsAreTheFourLiveOnes` then makes growing
+ * this array a decision someone has to write down rather than one that happens
+ * by omission.
+ *
+ * **What the loop actually does with each** (`core/loop.ts`):
+ *   - `use_tool`  → the step's tool calls run, then back to the model.
+ *   - `clarify` / `escalate` → terminal, and the outcome carries that type.
+ *   - `respond`   → terminal, the text is delivered.
+ *
+ * And an action that is NONE of these — a rogue model emitting a string at
+ * runtime, where no type can stop it — takes the `respond` path: terminal,
+ * one iteration, whatever text the payload carried. That is the existing
+ * behaviour, it is fail-safe (a nonsense action never loops and never runs a
+ * tool), and it is pinned by a guard in `tests/delegate.test.ts` rather than
+ * left as an accident. The bridge's `respond` fallback for an unrecognised
+ * string is the same rule stated one layer earlier.
+ */
+export const BRAIN_ACTIONS = [
+    "use_tool",
+    "respond",
+    "clarify",
+    "escalate",
+];
+/**
+ * The responder's name lifted off a raw provider reply — `{}` when it named none.
+ *
+ * Spread into a `BrainPayload` by all four bundled brains, so the reading exists
+ * once. Four copies of the same check in four files is four chances to drift,
+ * and the one difference between them (Gemini spells the field `modelVersion`;
+ * OpenAI, Anthropic and Ollama spell it `model`) is a fact about wire formats
+ * that belongs written down, not re-derived per file.
+ *
+ * **Why the parameter is `unknown`, and why there is no cast anyway.** The
+ * declared shape of each provider response in `brain/streaming.ts` is exactly
+ * the set of fields its brain reads — by design, stated there — and that set
+ * does not include the model name. A parameter typed `{ model?: unknown }`
+ * would therefore be rejected for every real argument: TypeScript's weak-type
+ * check refuses an object that shares no property with an all-optional target,
+ * which is precisely the situation here. So this takes what it is really given
+ * — an object off a wire — and narrows it at runtime with `typeof` and `in`.
+ * Nothing is asserted about it that has not just been tested.
+ *
+ * A reply that carries no name, or a non-string one, yields `{}`: the payload
+ * gets no `model` key, and the log records the absence honestly instead of
+ * inventing a name from the request.
+ */
+export function respondingModel(reply) {
+    if (typeof reply !== "object" || reply === null)
+        return {};
+    const named = "model" in reply
+        ? reply.model
+        : "modelVersion" in reply
+            ? reply.modelVersion
+            : undefined;
+    return typeof named === "string" && named.length > 0 ? { model: named } : {};
+}

package/dist/definition/skills.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Skills — reusable instruction packs an agent loads, "files all the way down."
+ *
+ * Drop markdown into a folder and each file becomes part of the agent's
+ * definition, so the model gains that know-how with no rebuild and no code
+ * change. Two shapes are read, and they are the shapes Claude-style skill packs
+ * already use:
+ *
+ *   skills/
+ *     summarizing/SKILL.md      ← a folder pack
+ *     tone-of-voice.md          ← a single-file skill
+ *
+ * `loadSkills(dir)` returns ONE markdown block (`## Skills`), or `""` when
+ * there is nothing to load. **Composition stays with the host**: this module
+ * reads files and concatenates them; appending the block to a definition is the
+ * caller's line of code. The loop is not involved and does not know skills
+ * exist — `parseDefinition` has always *stripped* a `## Skills` section as
+ * "owned by the app layer", and that stays true.
+ *
+ * ── Lifted from `nisus/runtime/skills/loader.ts`, hardened where it mattered ──
+ *
+ * The pattern was right, so it was carried over rather than reinvented. Three
+ * things changed, each for a failure mode, and each pinned by a guard in
+ * `tests/skills.test.ts` — including a differential test against a verbatim
+ * transcription of the original, so any divergence beyond these is a bug:
+ *
+ *   1. **The order is deterministic.** The original iterated `readdirSync`
+ *      directly, and that order is filesystem- and platform-dependent (APFS
+ *      hands back roughly hash order; ext4 differs again). Two machines with
+ *      the same two skills therefore built two different definitions — the same
+ *      agent with two fingerprints, which is the enemy of replay
+ *      (`@msm-core/replay` fingerprints `system_context`) and of any diff a
+ *      human tries to read. Entries are now sorted by code unit before they are
+ *      read. **Not** `localeCompare`: that depends on ICU data and the ambient
+ *      locale, which would reintroduce exactly the nondeterminism being
+ *      removed.
+ *
+ *   2. **Diagnostics go to an injected port, never to `console`.** Same reason
+ *      as `@msm-core/mcp`'s `McpLogPort`: a library that prints is a library you
+ *      cannot embed. Absent a port, the loader is silent.
+ *
+ *   3. **An empty skill file contributes nothing instead of a bare separator.**
+ *      The original pushed `readFileSync(...).trim()` unconditionally, so an
+ *      empty (or whitespace-only) `.md` injected `"\n\n---\n\n\n\n---\n\n"`
+ *      into the text the model reads — a horizontal rule with no section under
+ *      it, mid-definition. It is now skipped, with a warning naming the file,
+ *      because a file someone left empty is a mistake worth hearing about.
+ *
+ * What deliberately did NOT change: a folder without a `SKILL.md` is skipped in
+ * silence (it is a plain folder, not a failure); a non-`.md` file is ignored;
+ * an entry that throws is reported and its siblings still load; and a folder
+ * pack and a single-file skill sitting side by side are BOTH read — the folder
+ * from its `SKILL.md`, the file from itself. That last one is the precedence
+ * rule, and it is a rule rather than an accident because a guard says so.
+ */
+/**
+ * Where the loader's diagnostics go — a port, not a console.
+ *
+ * Shaped so a plain `console`-like object, or the `SimpleLog` the original
+ * loader took, satisfies it without a wrapper.
+ */
+export interface SkillsLogPort {
+    info?(message: string): void;
+    warn?(message: string): void;
+}
+/**
+ * Read every skill under `dir` and return them as one markdown block, or `""`
+ * when the directory is missing, is not a directory, or holds no skills.
+ *
+ * Never throws for a skill it cannot read: the failure is reported on `log` and
+ * the remaining skills still load. A definition missing one section is worth
+ * more than an agent that will not start.
+ */
+export declare function loadSkills(dir: string, log?: SkillsLogPort): string;