@msm-core/mini 0.5.1 → 0.8.0

package/dist/core/types.d.ts

@@ -4,6 +4,8 @@
  * All contracts for the lite agent runtime. Brain-agnostic, zero embedded
  * databases. Application layer owns persistence; agent owns the loop.
  */
+import type { SessionLogPort } from "@msm-core/session";
+import type { ContextBudget } from "./context-builder.js";
 /**
  * A single memory entry — assembled by msm-context or by the app directly.
  * The agent injects these into every brain call in priority order.
@@ -114,12 +116,67 @@ export interface BrainRunInput {
      * safe — the loop still stops waiting via its timeout race.
      */
     signal?: AbortSignal;
+    /**
+     * Present ONLY when a consumer asked to see the answer as it is produced
+     * (ب١). Its absence is the normal case and means "do not stream" — every
+     * built-in brain then walks the exact non-streaming path it always walked.
+     *
+     * **Display, not truth.** What the loop records, gates, returns and replays
+     * is still the completed `BrainPayload`. A chunk is never logged as an event,
+     * never enters a `replay` fingerprint, and never changes the session-log
+     * invariant. Drop every chunk on the floor and the run is bit-identical.
+     *
+     * A brain that ignores this field is CORRECT, not broken — it simply does not
+     * stream. Third-party brains written before ب١ keep working untouched.
+     */
+    onChunk?: (chunk: BrainChunk) => void;
+}
+/**
+ * One piece of a model answer as it arrives.
+ *
+ * **Text only in v1.** Streaming tool CALLS is deliberately out of scope: the
+ * brain still accumulates them and returns them in the payload exactly as it
+ * does today, so a half-arrived tool call is never observable and never
+ * executable. The type is an object rather than a bare `string` so that day —
+ * if it comes — adds a field instead of breaking every consumer's signature.
+ */
+export interface BrainChunk {
+    text: string;
+}
+/**
+ * One tool invocation a model asked for, in the model's own order.
+ *
+ * The unit is the CALL, not the step: modern models emit several in one
+ * response, and a step-shaped type would force the loop back into one
+ * round-trip per tool — the cost this exists to remove.
+ */
+export interface BrainToolCall {
+    name: string;
+    params: Record<string, unknown>;
 }
 export interface BrainOrchestration {
     action: "use_tool" | "respond" | "clarify" | "escalate" | "delegate";
     confidence: number;
+    /**
+     * The FIRST call of the step. Always filled whenever `tool_calls` is —
+     * never left behind as `tool_calls` grows. Every consumer written against
+     * one-tool-per-step keeps reading exactly what it always read.
+     */
     tool_name?: string;
+    /** The first call's arguments. Same covenant as `tool_name`. */
     tool_params?: Record<string, unknown>;
+    /**
+     * ALL the calls of this step, in the order the model emitted them.
+     *
+     * **A pure addition.** A brain that fills only `tool_name`/`tool_params`
+     * (every third-party brain written before this field existed, and every
+     * scripted brain in the suite) is normalized to a single-call step and takes
+     * the path it always took, character for character. A brain that fills this
+     * field fills the two above with `tool_calls[0]` as well — the covenant is
+     * one-directional: new readers may read the array, old readers never see a
+     * hole where the first call used to be.
+     */
+    tool_calls?: BrainToolCall[];
     reasoning?: string;
     [key: string]: unknown;
 }
@@ -253,6 +310,89 @@ export interface DocumentState {
     startedAt: number;
     updatedAt: number;
 }
+/**
+ * Final run metadata persisted after every handle() — for ops dashboards.
+ *
+ * Declared here, with the port it belongs to, rather than inside one adapter:
+ * it is part of the contract every store implements, not a Redis detail. The
+ * Redis adapter re-exports it, so existing imports keep working unchanged.
+ */
+export interface SessionMetadata {
+    iterationCount: number;
+    startedAt: number;
+    totalCostUsd: number;
+    status: "running" | "completed" | "failed" | "killed";
+}
+/**
+ * The session-memory PORT — conversation history, run metadata, document state.
+ *
+ * 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.
+ *
+ * Six functions — the surface `RedisMemory` already had, at its current
+ * signatures. Nothing is added speculatively: an append-only event log is a
+ * different contract and does not belong here.
+ */
+export interface SessionStore {
+    /** Append one message to this session's conversation history. */
+    appendHistory(sessionId: string, entry: Message): Promise<void>;
+    /** The last `limit` messages, oldest-first. Default limit: 50. */
+    getHistory(sessionId: string, limit?: number): Promise<Message[]>;
+    getMetadata(sessionId: string): Promise<SessionMetadata | null>;
+    setMetadata(sessionId: string, meta: SessionMetadata): Promise<void>;
+    getDocumentState(sessionId: string): Promise<DocumentState | null>;
+    setDocumentState(sessionId: string, state: DocumentState): Promise<void>;
+}
+/**
+ * What a compactor decides when it decides to compact.
+ *
+ * `keepTurns` is a REQUEST, not a command: the loop hands it to
+ * `compactionBoundary`, which cuts only at whole turns and refuses to sever a
+ * tool call from its result. A compactor asking to keep zero turns of a session
+ * whose last turn is still unpaired gets a smaller range than it asked for, or
+ * none at all. That is the point of having two defences.
+ */
+export interface CompactionDecision {
+    /** The text the compacted range will read as. Empty means "no compaction". */
+    summary: string;
+    /** How many trailing turns to leave verbatim. Clamped to what is safe. */
+    keepTurns: number;
+}
+/**
+ * The compaction seat: a port the loop consults before it derives the
+ * conversation, and never a trick it plays on the history array.
+ *
+ * Today a long session is trimmed by `history.slice(-maxHistoryMessages)`. That
+ * cut lands wherever it lands — through the middle of a tool call and its
+ * result, through the middle of a turn — and it is silent. A long legal case in
+ * nisus loses its own beginning and nothing anywhere says so. This port is the
+ * seat where that stops being true.
+ *
+ * Three properties are contractual:
+ *
+ *  1. **It only works with `sessionLog`.** Compaction records a `compaction`
+ *     event; without a log there is nowhere to record it, and a summary that is
+ *     not recorded is exactly the silent rewrite this replaces. With `memory`
+ *     alone the port is inert and the old `slice` path runs untouched — declared,
+ *     not an oversight.
+ *
+ *  2. **`null` means no compaction.** The overwhelmingly common answer. A port
+ *     that returns `null` costs one call and changes nothing.
+ *
+ *  3. **A throwing port fails the turn.** It is not swallowed. A compactor that
+ *     has quietly been failing for a month is a session that has quietly been
+ *     losing its head for a month — the failure this exists to end, wearing a
+ *     different hat.
+ *
+ * @param messages the conversation DERIVED from the log so far, in order.
+ * @param budget   the budget the derived history will actually be trimmed to —
+ *                 `maxHistoryMessages` is the effective cap, already reconciled
+ *                 with the agent's iteration-derived history limit.
+ */
+export interface CompactionPort {
+    maybeCompact(messages: readonly Message[], budget: ContextBudget): Promise<CompactionDecision | null>;
+}
 export interface RedisConfig {
     /**
      * Redis connection URL — mini creates its own connection.
@@ -304,6 +444,68 @@ export interface AgentConfig {
     definition: string | AgentDefinition;
     brain: Brain;
     redis: RedisConfig;
+    /**
+     * Optional session-memory port. When injected, the loop routes ALL history /
+     * metadata / document-state access through it and never constructs a
+     * Redis-backed store. When omitted, the loop builds `RedisMemory` from
+     * `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.
+     */
+    memory?: SessionStore;
+    /**
+     * Optional session **event log** (`@msm-core/session`). Injecting it inverts
+     * where conversation context comes from:
+     *
+     *   - **Omitted (default)** — nothing changes. Not one event is written, the
+     *     history handed to the brain is `memory.getHistory()` exactly as before,
+     *     and the invariant below never runs. Every existing consumer is
+     *     bit-for-bit unaffected.
+     *   - **Injected** — the loop writes every event as it happens (the user
+     *     message, each step, each model request/response, every tool call and
+     *     its result, guards, the delivered reply), and the conversation handed
+     *     to the model is DERIVED from the log (`deriveMessages`) instead of read
+     *     from the history array. `memory.appendHistory` keeps being written too:
+     *     one transitional phase of dual writing, log as truth, array as
+     *     compatibility.
+     *
+     * Two consequences worth knowing before you inject one:
+     *
+     *   1. **The derived conversation is richer.** It carries the
+     *      `assistant`/`tool` pairs of previous turns, which the history array
+     *      never held. That is the point of the log, not a side effect — but it
+     *      is a real change in what the model sees.
+     *   2. **It is the truth, so its failures are loud.** A rejected append
+     *      (e.g. `SeqGapError`) fails the turn rather than being swallowed: a log
+     *      with a hole in it cannot back an audit, a resume or a replay.
+     *
+     * Isolation is the injector's, exactly as with `memory`: this port takes a
+     * `sessionId` and knows nothing of tenants. Whoever injects a log injects its
+     * tenant scoping with it.
+     */
+    sessionLog?: SessionLogPort;
+    /**
+     * Optional **compaction port** (ض١). Consulted once per turn, right before
+     * the conversation is derived, and only when `sessionLog` is also injected.
+     *
+     *   - **Omitted (default)** — not one extra call, not one extra event. The
+     *     conversation is derived and trimmed exactly as it was before.
+     *   - **Omitted `sessionLog`** — the seat is inert even when this is set:
+     *     compaction records an event, and without a log there is nothing to
+     *     record it in. The legacy history path keeps its `slice`. Declared.
+     *   - **Both injected** — when the port returns a summary, the loop writes a
+     *     `compaction` event covering a safe range (`compactionBoundary`) and
+     *     re-derives. The model then reads one summary plus the recent turns
+     *     verbatim, and the invariant still proves that what it read came out of
+     *     the log — because the compaction is IN the log.
+     *
+     * `createBrainCompactor` is a reference implementation that summarises with an
+     * injected `Brain`. The port does not require it; anything with a
+     * `maybeCompact` will do, including one that never calls a model at all.
+     */
+    compaction?: CompactionPort;
     /** App-provided tools — agent can only call tools listed here */
     tools: Tool[];
     guards?: GuardConfig;
@@ -343,6 +545,15 @@ export interface GuardFiredInfo {
     signal: GuardSignal;
     iteration: number;
 }
+/** One streamed piece of the model's answer, with the step it belongs to (ب١). */
+export interface ChunkInfo {
+    sessionId: string;
+    /** The loop iteration whose brain call produced this text. */
+    iteration: number;
+    /** The delta — not the running total. Concatenating every chunk of a step
+     *  yields the text that step's payload carries. */
+    text: string;
+}
 /**
  * Return value from onBeforeTool hook:
  *   "proceed"            — execute the tool normally
@@ -365,6 +576,18 @@ export interface AgentHooks {
     onToolCall?: (info: ToolCallInfo) => void;
     onGuard?: (info: GuardFiredInfo) => void;
     onFatalError?: (error: Error, sessionId: string) => void;
+    /**
+     * Called for each piece of model text as it arrives (ب١). Wire it to an SSE
+     * channel and the user stops watching a silent screen.
+     *
+     * **Setting this is what turns streaming on.** The loop passes `onChunk` down
+     * to the brain only when this hook exists; with no hook, `BrainRunInput`
+     * carries no `onChunk` and every brain takes its ordinary non-streaming path.
+     *
+     * Fire-and-forget like its siblings: a throwing hook is swallowed and the
+     * stream continues — a broken display must not break the run.
+     */
+    onChunk?: (info: ChunkInfo) => void;
     /**
      * Called before every tool execution (BEFORE the dedup check, so cached
      * results can never bypass the gate). Return "proceed" to execute normally,

package/dist/index.d.ts

@@ -7,13 +7,16 @@
  * import { RedisMemory, RedisControlBus } from 'msm-mini/adapters'
  */
 export { createAgent } from "./core/loop.js";
+export { createBrainCompactor } from "./core/loop.js";
+export type { BrainCompactorOptions } from "./core/loop.js";
 export { createGeminiBrain } from "./brain/gemini.js";
 export { createOpenAIBrain } from "./brain/openai.js";
 export { createAnthropicBrain } from "./brain/anthropic.js";
 export { createOllamaBrain } from "./brain/ollama.js";
 export { buildBrain } from "./brain/factory.js";
 export { parseDefinition } from "./definition/parser.js";
-export type { Agent, AgentConfig, AgentEvent, AgentContext, AgentDefinition, AgentHooks, BeforeToolHookResult, Brain, BrainPayload, BrainRunInput, DocumentState, GateConfig, GuardConfig, GuardSignal, GuardSignalType, IterationInfo, LoopOutcome, MemoryEntry, Message, OutcomeType, OutputValidation, OutputValidator, RedisConfig, RunState, SectionInfo, TenantContext, Tool, ToolCallInfo, ToolDefinition, ToolMeta, ToolParameter, ToolResult, } from "./core/types.js";
+export type { Agent, AgentConfig, AgentEvent, AgentContext, AgentDefinition, AgentHooks, BeforeToolHookResult, Brain, BrainChunk, BrainOrchestration, BrainPayload, BrainRunInput, BrainToolCall, ChunkInfo, CompactionDecision, CompactionPort, DocumentState, GateConfig, GuardConfig, GuardSignal, GuardSignalType, IterationInfo, LoopOutcome, MemoryEntry, Message, OutcomeType, OutputValidation, OutputValidator, RedisConfig, RunState, SectionInfo, SessionMetadata, SessionStore, TenantContext, Tool, ToolCallInfo, ToolDefinition, ToolMeta, ToolParameter, ToolResult, } from "./core/types.js";
+export type { ContextBudget } from "./core/context-builder.js";
 export { resolveGuards, DEFAULT_GUARDS } from "./core/guards.js";
 export { scoreOutcome } from "./quality/scorer.js";
 export type { QualityScore, QualityFlag } from "./quality/scorer.js";

package/dist/index.js

@@ -8,6 +8,8 @@
  */
 // ── Main factory ────────────────────────────────────────────────────────────
 export { createAgent } from "./core/loop.js";
+// ── Compaction (ض١) — the seat, and one reference occupant ──────────────────
+export { createBrainCompactor } from "./core/loop.js";
 // ── Brain factories ─────────────────────────────────────────────────────────
 export { createGeminiBrain } from "./brain/gemini.js";
 export { createOpenAIBrain } from "./brain/openai.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msm-core/mini",
-  "version": "0.5.1",
+  "version": "0.8.0",
   "description": "Portable AI agent execution loop — brain-agnostic, zero embedded databases",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,13 +31,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "npm run build && npm test"
-  },
   "peerDependencies": {
     "openai": ">=4.0.0",
     "@anthropic-ai/sdk": ">=0.20.0",
@@ -55,7 +48,8 @@
     }
   },
   "dependencies": {
-    "ioredis": "^5.3.2"
+    "ioredis": "^5.3.2",
+    "@msm-core/session": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -71,5 +65,11 @@
     "portable"
   ],
   "author": "Emad Jumaah",
-  "license": "UNLICENSED"
-}
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}