@mercury-fw/core 0.25.0

package/dist/src/router/tool-log.d.ts

@@ -0,0 +1,65 @@
+import type { StepInfo } from "../session/step-info.ts";
+/**
+ * Stringifies `value` as JSON, truncating to `maxChars` and appending a
+ * marker with the real total length and a pointer to `/dump` when it
+ * doesn't fit — so a human watching the terminal sees something bounded
+ * but still knows more is available and how to get it.
+ */
+export declare function truncateForDisplay(value: unknown, maxChars: number): string;
+/**
+ * Builds the file `/dump` writes to when the user doesn't give an
+ * explicit path. Lands in the OS temp dir, not the process's cwd — in
+ * the Docker image that's `/app`, owned by root, where the `mercury`
+ * user can read/execute existing files but not create new ones (every
+ * default-path `/dump` failed with EACCES until this). Includes a
+ * timestamp (colons/dots replaced since they aren't valid in filenames
+ * on every filesystem) so repeated `/dump` calls land in separate files
+ * instead of silently overwriting a fixed default each time.
+ */
+export declare function defaultDumpPath(now?: Date): string;
+/**
+ * Parses a `/dump [path]` command line. Returns null for anything that
+ * isn't exactly this command (including regular conversation input, and
+ * a slash-prefixed word that merely starts with "dump") — the caller
+ * uses this to tell a real command from a message meant for the model.
+ * `path` is undefined when none was given — the caller decides the
+ * default (see `defaultDumpPath`), since computing "now" here would make
+ * this function's output depend on when it happens to run.
+ */
+export declare function parseDumpCommand(line: string): {
+    path: string | undefined;
+} | null;
+/**
+ * Writes `steps` to `path` as indented JSON — human-readable, since this
+ * is the path a person opens by hand to inspect what a tool actually
+ * returned, not something machine-parsed downstream.
+ */
+export declare function writeDump(path: string, steps: StepInfo[]): Promise<void>;
+/**
+ * Describes what happened to the tool call identified by `toolCallId`
+ * within `step`: its result if it executed, the `tool-error` content
+ * part if it failed before executing (e.g. arguments that don't match
+ * the tool's schema — there's no `toolResults` entry for this case, it
+ * only shows up in `content`), or an explicit "(none)" if neither is
+ * present. Printing "(none)" for an actual failure was the bug this
+ * fixes — it read as "nothing happened" when something had, in fact,
+ * gone wrong and been silently dropped from view.
+ */
+export declare function describeToolOutcome(step: StepInfo, toolCallId: string, maxChars: number): string;
+/**
+ * Formats real token counts for display next to the terminal prompt:
+ * `usedTokens` is the real `inputTokens` the last turn's call reported
+ * (see `src/session/agent-turn.ts`'s `onUsage`), `maxTokens` is the
+ * context length Ollama actually has the model loaded with right now
+ * (see `src/model/context-size.ts`) — not an estimate, and not the
+ * model's architectural maximum, which can overstate what's really
+ * usable. A model degrading over a long conversation is hard to tell
+ * apart by eye from "the context is genuinely near full" — this gives a
+ * live number instead of having to guess.
+ *
+ * `maxTokens` is `null` before the model has been loaded at least once
+ * this process (nothing to report yet) — the denominator is omitted
+ * rather than showing a misleading `/~0k`. `usedTokens` is `undefined`
+ * before the first turn has completed, shown as `?` for the same reason.
+ */
+export declare function formatContextUsage(usedTokens: number | undefined, maxTokens: number | null): string;

package/dist/src/router/turn-runner.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Deduplicates what `src/index.ts` used to do twice: two near-identical
+ * ~50-line closures, one per channel, that (1) tracked the session for
+ * Layer-3 capture when the channel has a real per-user identity, (2) ran
+ * `runTurn` with a channel-specific tool set/system prompt/output sink,
+ * and (3) mirrored new messages to Qdrant and extracted procedural
+ * corrections once the turn resolved. `createTurnRunner` is that shared
+ * body, parameterized entirely by `Provider`/`InboundTurn`/`TurnSink`
+ * (`src/router/provider.ts`) so it doesn't know or care which provider a
+ * given turn came from — same channel-agnostic spirit as `runTurn` itself.
+ */
+import type { LanguageModel, Tool } from "ai";
+import { runTurn } from "../session/agent-turn.ts";
+import type { StepInfo } from "../session/step-info.ts";
+import type { PostTurnGuard } from "@mercury-fw/plugin-types";
+export type { PostTurnGuard };
+import type { SessionHistory } from "../session/history.ts";
+import { recordStep } from "../session/tool-log-buffer.ts";
+import type { HandleTurn, TurnSink } from "./provider.ts";
+export type TurnRunnerDeps = {
+    model: LanguageModel;
+    /** Both variants, precomposed by the composition root; selected per turn by `turn.multiUser`. */
+    systemPrompts: {
+        singleUser: string;
+        multiUser: string;
+    };
+    buildTools: (sessionKey: string, wikiUserId: string, onToolStart?: TurnSink["onToolStart"], onToolFinish?: TurnSink["onToolFinish"]) => Record<string, Tool>;
+    /**
+     * `userId` is forwarded (not interpreted here) so a provider's own
+     * closure can decide whether to seed a first-ever session with a
+     * context primer (see `src/session/context-primer.ts`) — building one
+     * needs a real per-user identity, which only some providers have.
+     */
+    getOrCreateHistory: (sessionKey: string, trackForCapture: boolean, userId: string | undefined) => Promise<SessionHistory> | SessionHistory;
+    /** Layer-3 session tracking (sessionUsers map + idle scanner touch). Only for turns that carry a userId. */
+    trackSession: (sessionKey: string, userId: string, at: number) => void;
+    /** Refreshes this turn's tool-status callbacks for out-of-band capture messages. */
+    registerCaptureCallback: (sessionKey: string, onToolStart: TurnSink["onToolStart"], onToolFinish: TurnSink["onToolFinish"]) => void;
+    /** Mid-conversation Layer-3 capture threshold check. Only for turns that carry a userId. */
+    maybeCapture: (sessionKey: string, history: SessionHistory) => Promise<void>;
+    /**
+     * Archives one message of the verbatim user↔model exchange (issue #4).
+     * Wired by the composition root to the verbatim-archive provider; absent
+     * on an instance with no such provider. Only called for turns that carry a
+     * `userId` (the archive is per-user, like Layer-3 capture), keyed on the
+     * space-independent `wikiUserId`, and only ever with the model's own answer
+     * text — never the appended `present` displays.
+     */
+    captureVerbatim?: (msg: {
+        sessionKey: string;
+        userId: string;
+        role: "user" | "assistant";
+        content: string;
+    }) => Promise<void>;
+    processToolCorrections: (steps: StepInfo[], onToolStart: TurnSink["onToolStart"], onToolFinish: TurnSink["onToolFinish"]) => Promise<void>;
+    logStep: (prefix: string, step: StepInfo) => void;
+    /** Test seam; defaults to the real `recordStep`. */
+    recordStepFn?: typeof recordStep;
+    /** Test seam; defaults to the real `runTurn`. */
+    runTurnFn?: typeof runTurn;
+    /**
+     * Post-turn guards contributed by loaded plugins, run in order over the
+     * model's finished text (see `PostTurnGuard`). Empty/absent on an instance
+     * with no plugin that registers one. The composition root builds these; the
+     * core knows nothing about what any of them does.
+     */
+    postTurnGuards?: PostTurnGuard[];
+    /**
+     * Test seam; defaults to `console.log`. Receives a guard's own `log` line,
+     * or the core's own note when a guard throws. Exists to measure real-world
+     * guard frequency before investing further.
+     */
+    logPostTurnGuardFn?: (message: string) => void;
+    /** Test seam; defaults to `Date.now`. */
+    now?: () => number;
+    /**
+     * Returns the display artifacts the model surfaced via `present` this turn
+     * (see `display-store.ts`), in stash order, to append after the model's
+     * text. Absent on an instance with no display store — nothing is appended.
+     * The old unconditional splicing of every tool-produced display is gone:
+     * an artifact is shown only when the model explicitly presented it.
+     */
+    takeSurfacedDisplays?: (sessionKey: string) => string[];
+};
+/** Builds the shared `HandleTurn` every provider's driver calls once it has a real message to run through the model. */
+export declare function createTurnRunner(deps: TurnRunnerDeps): HandleTurn;

package/dist/src/session/agent-turn.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Orchestrates a single conversational turn: append the user's input to
+ * history, ask the model for a response (with access to whichever tools
+ * this Mercury instance has wired in), append the response to history,
+ * return it.
+ *
+ * This is the one place that calls `generateText` for the main agent
+ * loop (as opposed to `src/session/summarizer.ts`, which calls it for
+ * summarization) — see `buildGenerateTextParams` below for why it's
+ * `ai-sdk-ollama`'s enhanced version, not the plain `ai` one. The real
+ * call is injected as
+ * `generateTextFn` so tests can exercise the sequencing/wiring logic
+ * here without needing a real model — see the test file for what that
+ * does and doesn't cover.
+ *
+ * Deliberately generic about *what* Mercury can do: `system` and
+ * `tools` are both passed in by the caller rather than hardcoded here.
+ * A fixed prompt baked into this file describing a specific tool (e.g.
+ * "use jiraCli") would be actively wrong on an instance where that tool
+ * isn't wired in — the model could still attempt a call to a tool name
+ * not present in the request's tool schema, which the AI SDK surfaces
+ * as a real error (`NoSuchToolError`), not a harmless no-op. Composing
+ * a `system` string that accurately reflects which tools are actually
+ * available is `src/index.ts`'s job, since that's where the set of
+ * enabled CLIs/tools is decided.
+ *
+ * Used by: `src/router/turn-runner.ts`'s `createTurnRunner`, the one
+ * shared driver every `Provider` (terminal, Google Chat) funnels its
+ * turns through (see `src/router/provider.ts`) — `runTurn` itself doesn't
+ * know or care which provider a given conversation came from.
+ *
+ * Streaming (see `buildStreamTextParams`/`runTurn`'s `onTextChunk`) is
+ * opt-in: providing `onTextChunk` *or* `onReasoningChunk` switches this
+ * call to `streamText`, reading its `fullStream` instead of waiting in
+ * silence for a full response — which can take several seconds on the
+ * local development model. The terminal provider supplies both (prints
+ * the answer and the model's live reasoning to stdout); Google Chat's
+ * `TurnSink` supplies only `onReasoningChunk` (a live-patched status card
+ * for the model's reasoning) and deliberately never `onTextChunk` — Chat
+ * only shows a message once it's fully sent, so incremental *answer*
+ * delivery never actually reaches a human faster there, unlike a
+ * terminal's live-updating stdout; the reasoning card is a different,
+ * already-patchable surface (see `google-chat-provider.ts`'s `createSink`).
+ * Either way this function still returns the full answer text and records
+ * it as one assistant history entry, same as the plain `generateText` path
+ * below — reasoning content is never part of `fullText` or the recorded
+ * history entry, it only ever reaches `onReasoningChunk`/`onReasoningEnd`,
+ * since it's a live UI-only surface, not something the model should ever
+ * see reflected back at it on a later turn.
+ */
+import { type LanguageModel, type StopCondition, type Tool } from "ai";
+import type { Message, SessionHistory } from "./history.ts";
+import type { StepInfo } from "./step-info.ts";
+import { PENDING_CONFIRMATION_NOTE } from "@mercury-fw/channel-types";
+export { PENDING_CONFIRMATION_NOTE };
+/** The shape of the AI SDK call this module needs, injectable for tests. */
+type GenerateTextFn = (params: {
+    model: LanguageModel;
+    messages: Message[];
+    tools: Record<string, Tool>;
+    instructions: string;
+    onStepEnd?: (step: StepInfo) => void;
+    /** Aborts the in-flight generation when the caller cancels the turn. */
+    abortSignal?: AbortSignal;
+}) => Promise<{
+    text: string;
+    usage?: {
+        inputTokens: number | undefined;
+    };
+}>;
+/**
+ * Minimal shape this file reads off a `fullStream` part — deliberately a
+ * loose supertype of the real (much larger) `TextStreamPart` union `ai`
+ * actually emits (`node_modules/ai/dist/index.d.ts:2484`: `start`,
+ * `text-start`, `tool-call`, `finish`, etc.), not a closed enumeration of
+ * it: a closed union here would reject every part type this file doesn't
+ * care about, which the real stream emits plenty of. `delta`/`text` are
+ * both optional for the same reason — only present on the part types this
+ * file actually reads (`text-delta`/`reasoning-delta`), and the *name* of
+ * that field is itself unstable: `ai`'s own `.d.ts` declares this part
+ * shape twice with different field names for the same `type` value
+ * (`node_modules/ai/dist/index.d.ts:2103-2107` uses `delta`, `2555-2558`
+ * uses `text`) — confirmed live against the real `ai-sdk-ollama` stream
+ * that the installed version actually emits `text`, not `delta`. Reading
+ * both defensively (see the loop below) survives either shape rather than
+ * silently reading `undefined` and going empty if a future upgrade flips
+ * it back.
+ */
+type StreamPart = {
+    type: string;
+    delta?: string;
+    text?: string;
+    id?: string;
+};
+/** The shape of the AI SDK streaming call this module needs, injectable for tests. */
+type StreamTextFn = (params: {
+    model: LanguageModel;
+    messages: Message[];
+    tools: Record<string, Tool>;
+    instructions: string;
+    onStepEnd?: (step: StepInfo) => void;
+    /** Aborts the in-flight generation when the caller cancels the turn. */
+    abortSignal?: AbortSignal;
+}) => Promise<{
+    stream: AsyncIterable<StreamPart>;
+    usage?: PromiseLike<{
+        inputTokens: number | undefined;
+    }>;
+}>;
+/**
+ * Builds the params object passed to the real `generateText`. Extracted
+ * as its own pure function so it's unit-testable without a real model —
+ * `defaultGenerateTextFn` below is otherwise a thin, untestable wrapper
+ * around a direct SDK call.
+ *
+ * `stopWhen: stepCountIs(100)` is the one non-obvious part: `generateText`
+ * defaults to stopping after a single step. If that step is a tool call
+ * with no accompanying text (the normal case — the model calls a tool,
+ * then needs the tool's result before it can answer), the call returns
+ * with `text: ""` and no error, having never given the model a chance to
+ * read the tool result and respond — some cap above 1 is needed for
+ * that. Raised from an original 5 (observed live: a conversation
+ * combining wiki lookups with a jira search — which always needs
+ * `--select`, so almost always costs 2 attempts — routinely burned all 5
+ * steps on tool calls alone, leaving the model zero steps to ever write
+ * an answer) to 20 (matching this SDK's own default for its
+ * higher-level agent construct, `ToolLoopAgentSettings`), then to 100 for
+ * extra headroom during this research phase — the model should be free
+ * to make as many tool calls as it actually needs, not be cut off by an
+ * arbitrary ceiling. `runTurn`'s empty-text fallback (below) is the
+ * remaining safety net regardless of the cap's value: if a turn still
+ * exhausts it with nothing to show, that's communicated explicitly
+ * rather than left silent — the real backstop against a runaway loop is
+ * that fallback plus the step count itself still being finite, not the
+ * specific number.
+ *
+ * `generateText` itself is imported from `ai-sdk-ollama`, not the plain
+ * `ai` package — confirmed by a real run: with the standard SDK's
+ * version, Ollama executed the tool call but `text` still came back
+ * empty even with multi-step enabled. `ai-sdk-ollama`'s enhanced
+ * `generateText` is a drop-in replacement (same params/return shape)
+ * that specifically synthesizes a real response when this happens —
+ * documented as a known Ollama-provider quirk, not something to patch
+ * around here by hand.
+ */
+export declare function buildGenerateTextParams(params: {
+    model: LanguageModel;
+    messages: Message[];
+    tools: Record<string, Tool>;
+    instructions: string;
+    onStepEnd?: (step: StepInfo) => void;
+    abortSignal?: AbortSignal;
+}): {
+    stopWhen: StopCondition<any>[];
+    model: LanguageModel;
+    messages: Message[];
+    tools: Record<string, Tool>;
+    instructions: string;
+    onStepEnd?: (step: StepInfo) => void;
+    abortSignal?: AbortSignal;
+};
+/**
+ * Builds the params object passed to the real `streamText`. Same
+ * `stopWhen` reasoning as `buildGenerateTextParams` — a tool-call-only
+ * first step must not be the stream's last step either. `ai-sdk-ollama`'s
+ * `streamText` carries its own equivalent of the empty-text-after-
+ * tool-call fix (`enableStreamingSynthesis`, on by default) — verified by
+ * reading its source before relying on it, not assumed from the
+ * non-streaming behavior.
+ */
+export declare function buildStreamTextParams(params: {
+    model: LanguageModel;
+    messages: Message[];
+    tools: Record<string, Tool>;
+    instructions: string;
+    onStepEnd?: (step: StepInfo) => void;
+    abortSignal?: AbortSignal;
+}): {
+    stopWhen: StopCondition<any>[];
+    model: LanguageModel;
+    messages: Message[];
+    tools: Record<string, Tool>;
+    instructions: string;
+    onStepEnd?: (step: StepInfo) => void;
+    abortSignal?: AbortSignal;
+};
+/**
+ * Runs one turn: records `userInput`, generates a response with the
+ * given model/tools/system prompt, records the response, and returns it.
+ *
+ * @param history - The conversation's `SessionHistory`; one per
+ *   channel/space, never shared (see `src/index.ts`).
+ * @param userInput - The user's message for this turn.
+ * @param deps.model - The language model to use.
+ * @param deps.tools - The tools available to the model on this call —
+ *   which tools end up here depends on which CLIs this Mercury instance
+ *   has enabled (see `src/index.ts`), not on anything in this file.
+ * @param deps.system - The system prompt for this call. Must accurately
+ *   describe only the tools actually present in `deps.tools` — this
+ *   function doesn't validate that, the caller is responsible for
+ *   keeping the two in sync.
+ * @param deps.onStepFinish - Optional, called once per generation step
+ *   (including intermediate ones with only a tool call, no text).
+ *   `src/router/turn-runner.ts`'s shared `createTurnRunner` wires this for
+ *   every provider (fans out to `logStep`/`recordStep`/the provider's own
+ *   `TurnSink.onStep`) — what each provider actually *does* with a step
+ *   still differs (the terminal prints it, Google Chat's `TurnSink`
+ *   doesn't define `onStep` at all, showing raw tool calls to a chat
+ *   audience isn't the same call as showing them to whoever's debugging at
+ *   a terminal), but the wiring itself is no longer channel-specific.
+ * @param deps.onTextChunk - Optional. When provided (alongside or instead
+ *   of `onReasoningChunk`), this turn uses `streamText` instead of
+ *   `generateText`, calling this once per answer-text chunk as it arrives
+ *   — see the file header for why Google Chat never sets this one. The
+ *   returned string and the recorded history entry are the same either
+ *   way: the full answer text, joined from every `text-delta` chunk only.
+ * @param deps.onReasoningChunk - Optional. Also switches this turn onto
+ *   `streamText` (see `onTextChunk`). Called once per reasoning-token
+ *   delta as it streams, tagged with the SDK's own id for that reasoning
+ *   block — only ever fires for a model that actually supports Ollama's
+ *   native extended thinking (see `src/index.ts`'s `OLLAMA_THINK`);
+ *   otherwise no reasoning parts ever arrive and this is simply never
+ *   called. This content is UI-only: it never touches the returned text
+ *   or `SessionHistory`. A single turn can reason more than once (e.g.
+ *   once before a tool call, again after seeing its result) — each burst
+ *   carries its own id, letting a caller (e.g. a status card per id)
+ *   treat them as independent rather than one continuous stream.
+ * @param deps.onReasoningEnd - Optional. Fires once per reasoning block
+ *   that actually started (i.e. once per distinct id `onReasoningChunk`
+ *   reported) — including if the stream aborts while a block is still
+ *   open, so a caller building a live display (a status card, a printed
+ *   block) can't be left stuck open forever. `failed` is `true` only for
+ *   that abrupt-abort case, `false` on a normal reasoning-end.
+ * @param deps.generateTextFn - Test seam for the non-streaming path;
+ *   defaults to the real AI SDK call. Injecting a fake here only tests
+ *   this function's own sequencing — it does not exercise the real model
+ *   or the real AI SDK integration, which can only be verified by an
+ *   actual end-to-end run.
+ * @param deps.streamTextFn - Test seam for the streaming path (used when
+ *   `onTextChunk`/`onReasoningChunk` is provided), same caveat as
+ *   `generateTextFn`.
+ * @param deps.onUsage - Optional, called once per turn with the real
+ *   `inputTokens` count the model actually consumed (summed across every
+ *   step, including tool calls) — not an estimate. The terminal channel
+ *   uses this for a real context-usage indicator (see
+ *   `src/router/tool-log.ts`'s `formatContextUsage`); Mercury's own char-
+ *   count heuristic in `src/session/history.ts` is for a different
+ *   purpose (deciding when to summarize) and intentionally untouched by
+ *   this.
+ */
+export declare function runTurn(history: SessionHistory, userInput: string, deps: {
+    model: LanguageModel;
+    tools: Record<string, Tool>;
+    system: string;
+    onStepFinish?: (step: StepInfo) => void;
+    onTextChunk?: (chunk: string) => void;
+    onReasoningChunk?: (chunk: string, id: string) => void;
+    onReasoningEnd?: (id: string, failed: boolean) => void;
+    onUsage?: (inputTokens: number | undefined) => void;
+    generateTextFn?: GenerateTextFn;
+    streamTextFn?: StreamTextFn;
+    /** When set, aborting it stops the in-flight generation — the turn ends
+     * promptly instead of running to completion (see the HTTP surface's
+     * client-disconnect cancellation). Optional; existing callers pass none. */
+    abortSignal?: AbortSignal;
+}): Promise<string>;

package/dist/src/session/context-primer.d.ts

@@ -0,0 +1,16 @@
+import type { EpisodicSummary } from "../memory/episodic-store.ts";
+import type { listWikiFilesInRoots, readWikiFileInRoots, readIndexFile } from "../wiki/wiki-read.ts";
+export type ContextPrimerDeps = {
+    vaultPath: string;
+    /** Already scoped to the last closed session's own sessionKey — see `getLastSessionEpisodicSummaries`. */
+    getLastSessionEntries: (userId: string) => Promise<EpisodicSummary[]>;
+    listWikiFilesInRootsFn: typeof listWikiFilesInRoots;
+    readWikiFileInRootsFn: typeof readWikiFileInRoots;
+    readIndexFileFn: typeof readIndexFile;
+};
+/**
+ * Text of the primer for `userId`, built from injected deps only — never
+ * touches Qdrant or the filesystem directly, so tests supply fakes and
+ * `index.ts` supplies the real Qdrant-backed episodic query and wiki reads.
+ */
+export declare function buildContextPrimer(userId: string, deps: ContextPrimerDeps): Promise<string>;

package/dist/src/session/episodic-summarizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Thin glue turning a closed session's messages into the episodic
+ * summary written to Qdrant (see `src/memory/episodic-store.ts`) — a
+ * factual account of what happened, not an interpretation. Distinct from
+ * `summarizer.ts` (Layer 1): that one condenses history to keep the
+ * *next* turn's prompt small, preserving whatever helps continue the
+ * same conversation; this one produces a standalone record of a
+ * *finished* conversation, and must not infer patterns or preferences
+ * (that inference is a separate, deterministic consolidation step,
+ * not this LLM call's job).
+ *
+ * Deliberately never asks the model for a date: it has no reliable notion
+ * of "today" and would invent one (observed live: dates from the wrong
+ * year, hedged with "replace with current date if applicable"). The
+ * entry's own `timestamp` field (computed by the caller,
+ * `idle-session-cron.ts`) is the one and only source of truth for "when" —
+ * never duplicated into this text, mechanically or otherwise.
+ *
+ * Same "not worth mocking deeply" reasoning as `summarizer.ts` — no
+ * dedicated test file, it's one line of glue around `generateText`.
+ */
+import { type LanguageModel } from "ai";
+import type { Message } from "./history.ts";
+/** Returns a function that summarizes a closed session's messages into a factual account. */
+export declare function createEpisodicSummarizer(model: LanguageModel): (messages: Message[]) => Promise<string>;

package/dist/src/session/history.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Layer 1 conversation memory: a sliding window of raw messages that
+ * summarizes itself once it grows too large, instead of growing
+ * unbounded across a long conversation.
+ *
+ * Why it exists: without a bound, a multi-turn conversation eventually
+ * overflows the model's context window. This is the only memory layer
+ * Mercury has in M1 — Layer 2 (wiki) and Layer 3 (episodic/Qdrant) are
+ * later milestones, pure enrichment that the system must work without.
+ *
+ * Used by: `src/session/agent-turn.ts` (`runTurn`), which appends each
+ * turn's user/assistant messages here and reads `getMessages()` to build
+ * the prompt for the next generation call. `src/session/summarizer.ts`
+ * supplies the `summarize` function injected into `createSessionHistory`.
+ */
+/** A single turn's worth of conversation content. */
+export type Message = {
+    role: "user" | "assistant";
+    content: string;
+};
+/**
+ * Character-count threshold (not a real tokenizer count — a `chars/4`
+ * estimate is close enough given the wide margin in the model's context
+ * budget) above which the raw message history gets summarized and
+ * replaced. Exported so tests can construct fixtures that land exactly
+ * at, or just past, the boundary.
+ */
+export declare const MAX_HISTORY_CHARS = 60000;
+/**
+ * Mutable conversation history for a single ongoing conversation
+ * (one per channel/space — see `src/index.ts`, never shared across
+ * conversations).
+ */
+export type SessionHistory = {
+    /** Appends a user turn, summarizing first if this push crosses the threshold. */
+    addUserMessage(content: string): Promise<void>;
+    /** Appends an assistant turn, summarizing first if this push crosses the threshold. */
+    addAssistantMessage(content: string): Promise<void>;
+    /**
+     * Overwrites the most recently added message with `content`, in place,
+     * if it exists and is an assistant message — used when a turn's
+     * assistant text is corrected after already being recorded (see
+     * turn-runner.ts's issue-list correction). No-ops if there is no last
+     * message, or if it isn't an assistant message (defensive; shouldn't
+     * happen given how this is called). Deliberately synchronous and skips
+     * the summarization threshold check entirely: this replaces content
+     * already counted by the original `addAssistantMessage` call, it isn't
+     * new content being added.
+     */
+    replaceLastAssistantMessage(content: string): void;
+    /**
+     * The messages to feed into the next model call: the current summary
+     * (if one exists, as a synthetic leading message) followed by the raw
+     * messages accumulated since the last summarization.
+     */
+    getMessages(): Message[];
+    /**
+     * Total character length of what `getMessages()` would currently
+     * return — a live read on how close this conversation is to
+     * `MAX_HISTORY_CHARS` (and so to triggering summarization). Exposed so
+     * a channel can show this to a human, e.g. to tell apart "the model
+     * lost track of something" from "the context is actually near full".
+     */
+    getCharCount(): number;
+};
+/**
+ * Creates an empty `SessionHistory`.
+ *
+ * @param summarize - Called with the messages that precede the current
+ *   user turn (any prior summary re-injected as a leading message) whenever
+ *   a single append pushes the total content length over
+ *   `MAX_HISTORY_CHARS`. Its return value becomes the new summary; the
+ *   trailing run from the last user message onward is retained as the raw
+ *   window rather than cleared, so the current turn is never summarized away
+ *   (a model call always follows `addUserMessage`, and the primer/summary
+ *   leading messages are both `role:"assistant"` — folding the user turn
+ *   into them would hand the model a user-less array). The threshold check
+ *   runs after every individual append (not once per turn), so the crossing
+ *   point is caught precisely regardless of whether it's the user or
+ *   assistant message that tips it over. A lone crossing user message with
+ *   nothing before it is left live and `summarize` is not called.
+ * @param onBeforeCompress - Optional, called synchronously with the exact
+ *   same batch `summarize` is about to receive, right before it's
+ *   compressed out of the live context — a second, independent signal a
+ *   caller can mirror to somewhere durable (see `idle-session-cron.ts`'s
+ *   shared capture function) before that content stops being directly
+ *   visible to the model. Fire-and-forget on purpose: this function must
+ *   never block or fail Layer 1's own compression on an external write.
+ * @param primer - Optional, set once at creation from the user's last closed
+ *   session (see `context-primer.ts`). Held as its own state, entirely
+ *   independent from `summary`: it's never included in the batch passed to
+ *   `summarize`, so a real compression event can't paraphrase or drop it.
+ *   Leads `getMessages()` for the whole life of this history.
+ */
+export declare function createSessionHistory(summarize: (messages: Message[]) => Promise<string>, onBeforeCompress?: (messages: Message[]) => void, primer?: string): SessionHistory;

package/dist/src/session/pending-confirmation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Confirm-required detection, re-exported from `@mercury-fw/channel-types`. The
+ * logic moved to the shared package so channel plugins can import it without
+ * depending on the app; kept re-exported here for the core callers
+ * (`agent-turn.ts` and the tests) that import it from this path.
+ */
+export { detectPendingConfirmation } from "@mercury-fw/channel-types";
+export type { PendingConfirmation } from "@mercury-fw/channel-types";

package/dist/src/session/read-skill-tool.d.ts

@@ -0,0 +1,4 @@
+import type { Skill, ExecutableTool } from "@mercury-fw/plugin-types";
+export declare function createReadSkillTool(skills: Skill[]): {
+    read_skill: ExecutableTool;
+};

package/dist/src/session/semantic-fact-extractor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Turns a closed session's messages into structured `{topic, value}`
+ * facts for the semantic consolidation engine (see
+ * `src/memory/semantic-facts-store.ts`) — distinct from
+ * `episodic-summarizer.ts`, which produces a prose account of the whole
+ * session. A single extracted fact here is a candidate, not yet a
+ * standing belief about the user: consolidation (a separate,
+ * deterministic step) decides whether repeated facts on the same topic
+ * are frequent enough to be promoted to a wiki note.
+ */
+import { type LanguageModel } from "ai";
+import { z } from "zod";
+import type { Message } from "./history.ts";
+/**
+ * Closed vocabulary — the model can only ever return one of these exact
+ * values, never invent a new key for the same concept. Deliberately
+ * excludes identity/name: a registered Chat app's own `MESSAGE` event
+ * already carries the sender's `displayName` directly, so a semantic
+ * fact about "who the user is" would only duplicate or contradict that
+ * more authoritative source, never add anything — observed live as the
+ * `name`/`user-name` duplicate before this fix.
+ */
+export declare const SEMANTIC_FACT_TOPICS: readonly ["team", "role", "preferred-language", "tools-used"];
+export declare const SemanticFactSchema: z.ZodObject<{
+    topic: z.ZodEnum<{
+        team: "team";
+        role: "role";
+        "preferred-language": "preferred-language";
+        "tools-used": "tools-used";
+    }>;
+    value: z.ZodString;
+}, z.core.$strip>;
+export type SemanticFact = z.infer<typeof SemanticFactSchema>;
+type GenerateObjectFn = (params: {
+    model: LanguageModel;
+    output: "array";
+    schema: typeof SemanticFactSchema;
+    instructions: string;
+    prompt: string;
+}) => Promise<{
+    object: SemanticFact[];
+}>;
+/** Returns a function that extracts standing {topic, value} facts from a closed session's messages. */
+export declare function createSemanticFactExtractor(model: LanguageModel, generateObjectFn?: GenerateObjectFn): (messages: Message[]) => Promise<SemanticFact[]>;
+export {};

package/dist/src/session/step-info.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal shape of a finished generation step that callers might care
+ * about — just enough to show what tool Mercury called, with what
+ * input, and what it got back. `toolCallId` is what links an entry in
+ * `toolCalls` to its entry in `toolResults` — a call with no matching
+ * result is a real case callers need to handle explicitly rather than
+ * assume a 1:1 pairing: it means the call failed before ever executing
+ * (e.g. malformed arguments that don't match the tool's schema), which
+ * shows up as a `tool-error` entry in `content`, not in `toolResults` —
+ * confirmed against the real AI SDK's `StepResult` type, which has no
+ * separate `toolErrors` array; `content` is the one place every part
+ * (text/tool-call/tool-result/tool-error) actually lives. The real AI
+ * SDK step object has many more fields; this is a subset, which is fine
+ * since function parameter types only need to be structurally
+ * compatible, not identical.
+ *
+ * Lives in its own file, not `agent-turn.ts`, specifically so
+ * `pending-confirmation.ts` (which needs this type) and `agent-turn.ts`
+ * (which needs `pending-confirmation.ts`'s `detectPendingConfirmation` to
+ * decide whether to stop the tool-calling loop early) don't form an
+ * import cycle.
+ */
+import type { StepInfo } from "@mercury-fw/plugin-types";
+export type { StepInfo };