@mercury-fw/core 0.25.0

package/dist/src/memory/episodic-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Layer 3 (Qdrant) episodic storage: one point per closed,
+ * summarized session — a raw, dated "what happened", not an
+ * interpretation. Consolidation into semantic memory (per-topic
+ * promotion into the wiki) is a separate, later concern that
+ * reads from this collection; this module only ever writes to it.
+ *
+ * `QdrantClientLike` describes only the subset of `@qdrant/js-client-rest`'s
+ * `QdrantClient` this file actually calls — real client instances satisfy
+ * it structurally, tests use a plain object instead of a real connection.
+ */
+export type QdrantClientLike = {
+    getCollections(): Promise<{
+        collections: Array<{
+            name: string;
+        }>;
+    }>;
+    createCollection(name: string, params: {
+        vectors: {
+            size: number;
+            distance: "Cosine" | "Euclid" | "Dot" | "Manhattan";
+        };
+    }): Promise<unknown>;
+    upsert(name: string, params: {
+        points: Array<{
+            id: string;
+            vector: number[];
+            payload: Record<string, unknown>;
+        }>;
+    }): Promise<unknown>;
+    /** @qdrant/js-client-rest 1.19 removed `search` in favour of the universal
+     * `query` endpoint: the vector moves to `query`, and results come back under
+     * `.points` instead of as a bare array. */
+    query(name: string, params: {
+        query: number[];
+        filter: Record<string, unknown>;
+        limit: number;
+        with_payload: boolean;
+    }): Promise<{
+        points: Array<{
+            id: string | number;
+            score: number;
+            payload?: Record<string, unknown> | null;
+        }>;
+    }>;
+    /**
+     * Optional — not part of the similarity-search surface every caller
+     * needs, only used by `getLastSessionEpisodicSummaries` below. Optional
+     * so `semantic-facts-store.ts`/`tool-corrections-store.ts` (which share
+     * this type but never call `scroll`) don't need a stub in every test
+     * fixture.
+     */
+    scroll?(name: string, params: {
+        filter: Record<string, unknown>;
+        order_by: {
+            key: string;
+            direction: "asc" | "desc";
+        };
+        limit: number;
+        /** Opaque pagination cursor (from a prior page's `next_page_offset`). */
+        offset?: string | number | Record<string, unknown> | null;
+        /** Whether to return point payloads (`listVerbatimBySession` needs them). */
+        with_payload?: boolean;
+    }): Promise<{
+        points: Array<{
+            id: string | number;
+            payload?: Record<string, unknown> | null;
+        }>;
+        next_page_offset?: string | number | Record<string, unknown> | null;
+    }>;
+    /** Optional — same reasoning as `scroll` above: only `ensureEpisodicCollection` needs it. */
+    createPayloadIndex?(name: string, params: {
+        field_name: string;
+        field_schema: "datetime" | "keyword";
+    }): Promise<unknown>;
+};
+/**
+ * Creates `collectionName` (cosine distance, `vectorSize`-dim) if it
+ * doesn't already exist, then ensures the `timestamp`/`userId` payload
+ * indexes exist regardless — `getLastSessionEpisodicSummaries`'s
+ * `order_by`/filter scroll queries fail with an HTTP 400 without them.
+ * Idempotent either way (Qdrant no-ops re-creating an existing index), so
+ * safe to call on every startup, including against a collection that
+ * predates this fix.
+ */
+export declare function ensureEpisodicCollection(client: QdrantClientLike, collectionName: string, vectorSize: number): Promise<void>;
+export type EpisodicSummary = {
+    userId: string;
+    sessionKey: string;
+    summary: string;
+    timestamp: string;
+};
+/** Embeds `entry.summary` and upserts it as a new point in `collectionName`, payload carrying the full entry. */
+export declare function storeEpisodicSummary(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, entry: EpisodicSummary): Promise<void>;
+/**
+ * Past episodic events for a specific user, most relevant to `queryText`
+ * (e.g. "notifications about KAN-123") — lets Mercury see how many times
+ * it already notified this user about a given item before composing a
+ * message. Not a general-purpose semantic consolidation/pattern-extraction
+ * engine (that doesn't exist here) — this only ever reads, never writes
+ * or promotes anything.
+ */
+export declare function searchEpisodicMemory(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, query: {
+    userId: string;
+    queryText: string;
+    limit?: number;
+}): Promise<EpisodicSummary[]>;
+/**
+ * The last closed session's episodic entries for `userId`, most recent
+ * first — up to `limit` entries, all sharing the same `sessionKey` as the
+ * single most recent entry. Used to seed a brand-new session's context
+ * primer with "what happened last time"; not similarity-scoped like
+ * `searchEpisodicMemory` (there's no query yet to compare against at
+ * session start). Returns an empty array (never throws) if the client
+ * doesn't support `scroll`, or if the user has no prior episodic entries —
+ * this is enrichment, the caller must work fine without it.
+ */
+export declare function getLastSessionEpisodicSummaries(client: QdrantClientLike, collectionName: string, query: {
+    userId: string;
+    limit?: number;
+}): Promise<EpisodicSummary[]>;

package/dist/src/memory/memory-provider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The memory-provider seam (issue #4, built ahead of the broader #30
+ * design): a memory mechanism that hooks the turn — capturing the
+ * exchange after it happens, and contributing its own recall tools — kept
+ * behind a small interface so the composition root wires it like any
+ * other provider rather than hardwiring it into the pipeline. Only the two
+ * hooks #4 exercises live here; the wider generalization (priming,
+ * summarizer, wiki strategy as swappable providers) is deferred to #30.
+ *
+ * The one implementation today is the verbatim archive
+ * (`./verbatim-archive-store.ts`).
+ */
+import { type Tool } from "ai";
+import type { QdrantClientLike } from "./episodic-store.ts";
+/** One side of an exchange to archive — the provider stamps its own durable timestamp. */
+export type VerbatimExchange = {
+    userId: string;
+    sessionKey: string;
+    role: "user" | "assistant";
+    content: string;
+};
+/** Per-turn identity a provider's recall tools are scoped to. `userId` is what makes recall cross-session. */
+export type MemoryProviderContext = {
+    sessionKey: string;
+    userId: string;
+};
+/**
+ * A memory mechanism the composition root can wire in. `captureExchange`
+ * runs after a turn resolves (post-message); `sessionTools` contributes
+ * model-invocable recall for the calling session. Both optional — a
+ * provider may only capture, or only recall.
+ */
+export type MemoryProvider = {
+    captureExchange?(exchange: VerbatimExchange): Promise<void>;
+    sessionTools?(ctx: MemoryProviderContext): Record<string, Tool>;
+};
+export type VerbatimArchiveProviderDeps = {
+    client: QdrantClientLike;
+    collectionName: string;
+    embed: (text: string) => Promise<number[]>;
+    /** Test seam; defaults to `() => new Date()`. The provider owns the durable ordering timestamp. */
+    now?: () => Date;
+};
+/**
+ * Builds the verbatim-archive provider: captures every user/assistant
+ * message verbatim to its Qdrant collection, and exposes a
+ * `recall_verbatim` tool that similarity-searches that archive scoped to
+ * the calling user — letting a later session resurface what was actually
+ * said before, beyond the live history window.
+ */
+export declare function createVerbatimArchiveProvider(deps: VerbatimArchiveProviderDeps): MemoryProvider;

package/dist/src/memory/semantic-facts-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Layer 3 (Qdrant) semantic facts storage — one collection, separate from
+ * `episodic-store.ts`. Episodic points are a raw dated account of a whole
+ * session; semantic facts are `{topic, value}` pairs extracted from a
+ * session, clustered per user+topic, and deterministically promoted to a
+ * standing wiki note. This module only owns the collection lifecycle;
+ * extraction, clustering, and promotion are separate concerns built on
+ * top of it.
+ */
+import type { QdrantClientLike } from "./episodic-store.ts";
+/** Creates `collectionName` (cosine distance, `vectorSize`-dim) if it doesn't already exist — safe to call on every startup. */
+export declare function ensureSemanticFactsCollection(client: QdrantClientLike, collectionName: string, vectorSize: number): Promise<void>;
+export type SemanticFactEntry = {
+    userId: string;
+    topic: string;
+    value: string;
+    timestamp: string;
+};
+/**
+ * Embeds `entry.topic` alone (never `topic + value`) and upserts it as a
+ * new point in `collectionName`, payload carrying the full entry. One
+ * point per extracted fact, never an update-in-place — consolidation
+ * reads the whole history back via `searchSemanticFactsByTopic` and
+ * decides what to promote.
+ */
+export declare function storeSemanticFact(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, entry: SemanticFactEntry): Promise<void>;
+/**
+ * Past facts for a specific user, clustered by topic similarity — the
+ * read side consolidation uses to gather "every occurrence of roughly
+ * this topic" before counting a dominant value. Filters by userId so
+ * one user's facts never leak into another's cluster.
+ */
+export declare function searchSemanticFactsByTopic(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, query: {
+    userId: string;
+    topic: string;
+    limit?: number;
+}): Promise<SemanticFactEntry[]>;

package/dist/src/memory/tool-corrections-store.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Layer 3 (Qdrant) procedural-correction staging — separate collection
+ * from `semantic-facts-store.ts`: that one is keyed by userId (a fact
+ * about a specific person), this one is keyed by tool (a fact about a
+ * CLI, true for whoever uses it next). Kept as its own collection rather
+ * than overloading `semantic-facts-store.ts`'s `userId` field with a tool
+ * name — a tool name in a field called `userId` would be a standing
+ * source of confusion for anyone reading this collection later.
+ */
+import type { QdrantClientLike } from "./episodic-store.ts";
+/** Creates `collectionName` (cosine distance, `vectorSize`-dim) if it doesn't already exist — safe to call on every startup. */
+export declare function ensureToolCorrectionsCollection(client: QdrantClientLike, collectionName: string, vectorSize: number): Promise<void>;
+export type ToolCorrectionEntry = {
+    tool: string;
+    topic: string;
+    value: string;
+    timestamp: string;
+};
+/** Embeds `entry.topic` alone (never `topic + value`), same reasoning as `storeSemanticFact` — upserts a new point, never an update-in-place. */
+export declare function storeToolCorrection(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, entry: ToolCorrectionEntry): Promise<void>;
+/** Past corrections for a specific tool, clustered by topic similarity — filters by `tool` so one tool's corrections never leak into another's cluster. */
+export declare function searchToolCorrectionsByTopic(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, query: {
+    tool: string;
+    topic: string;
+    limit?: number;
+}): Promise<ToolCorrectionEntry[]>;

package/dist/src/memory/verbatim-archive-store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The verbatim conversation archive (issue #4): a durable, lossless
+ * Qdrant collection holding the complete user↔model exchange, one point
+ * per message, distinct from every other memory layer.
+ *
+ * How it differs from the neighbours in this directory:
+ * - Layer-1 history (`../session/history.ts`) is a sliding window that
+ *   summarizes itself away — lossy by design.
+ * - The episodic store (`./episodic-store.ts`) captures a *summary* of a
+ *   closed session — derived, not raw.
+ * This archive instead keeps what was actually said, verbatim, so a later
+ * session can resurface it and re-read it in light of new facts. It only
+ * ever appends and reads; nothing here evicts (retention bounding is a
+ * separate, later concern).
+ *
+ * Reuses `episodic-store.ts`'s structural `QdrantClientLike` — the same
+ * subset of the real client every store in this directory shares.
+ */
+import type { QdrantClientLike } from "./episodic-store.ts";
+/**
+ * Creates `collectionName` (cosine distance, `vectorSize`-dim) if it
+ * doesn't already exist, then ensures the `userId` keyword payload index
+ * regardless — `searchVerbatim` filters by `userId` server-side, and the
+ * index keeps that filter usable as the archive grows. Idempotent
+ * (Qdrant no-ops re-creating an existing index), so safe to call on every
+ * startup, including against a collection created before this existed.
+ */
+export declare function ensureVerbatimCollection(client: QdrantClientLike, collectionName: string, vectorSize: number): Promise<void>;
+/** A single verbatim message as it was emitted in chat. `timestamp` (ISO 8601, ms precision) is the durable ordering key. */
+export type VerbatimMessage = {
+    userId: string;
+    sessionKey: string;
+    role: "user" | "assistant";
+    content: string;
+    timestamp: string;
+};
+/** Embeds `entry.content` and upserts it as a new point in `collectionName`, payload carrying the full verbatim message. */
+export declare function appendVerbatimMessage(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, entry: VerbatimMessage): Promise<void>;
+/**
+ * The verbatim messages for a specific user most relevant to `queryText`
+ * — e.g. "what did we say about KAN-1 last week". Filtered by `userId` so
+ * one user's transcript never leaks into another's. Only reads; returns
+ * the raw messages, ordering left to the caller (each carries its own
+ * `timestamp`).
+ */
+export declare function searchVerbatim(client: QdrantClientLike, collectionName: string, embed: (text: string) => Promise<number[]>, query: {
+    userId: string;
+    queryText: string;
+    limit?: number;
+}): Promise<VerbatimMessage[]>;
+/** One conversation in the list view: its key, the timestamp of its most recent message, and a short preview of it. */
+export type VerbatimSession = {
+    sessionKey: string;
+    lastTimestamp: string;
+    preview: string;
+};
+/**
+ * The known conversations, most-recently-active first — the sidebar a UI shows
+ * to switch between conversations. Scrolls the newest `SESSION_SCAN_LIMIT`
+ * messages (timestamp desc) and dedups by `sessionKey`, keeping each
+ * conversation's most recent message for its timestamp and preview, then caps
+ * the result at `limit`. Returns empty if the client can't scroll.
+ */
+export declare function listVerbatimSessions(client: QdrantClientLike, collectionName: string, query: {
+    limit: number;
+}): Promise<{
+    conversations: VerbatimSession[];
+}>;
+/** A page of a conversation's verbatim messages, plus the opaque cursor for the next page (null when exhausted). */
+export type VerbatimPage = {
+    messages: VerbatimMessage[];
+    nextOffset: string | number | Record<string, unknown> | null;
+};
+/**
+ * The verbatim messages of one conversation (`sessionKey`) in chronological
+ * order — the durable transcript a UI renders when it (re)loads a conversation.
+ * Unlike `searchVerbatim` this is a plain scroll (no similarity), filtered by
+ * `sessionKey` (the true per-conversation key; in the HTTP surface it equals
+ * the client's `conversationId`) and ordered by `timestamp` ascending, paged
+ * via the opaque `offset` cursor. Returns empty if the client can't scroll.
+ */
+export declare function listVerbatimBySession(client: QdrantClientLike, collectionName: string, query: {
+    sessionKey: string;
+    limit: number;
+    offset?: string | number | Record<string, unknown> | null;
+}): Promise<VerbatimPage>;

package/dist/src/model/client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Constructs the Ollama provider Mercury uses for every LLM call (main
+ * agent turns and Layer 1 summarization alike).
+ *
+ * Why it exists: the Ollama endpoint Mercury talks to varies by
+ * deployment (a local GPU box in development, a different host in
+ * production) and must always come from configuration, never be
+ * hardcoded or silently defaulted to `localhost` — this is the single
+ * place that reads that configuration, so the fail-fast behavior only
+ * has to be correct once.
+ *
+ * Used by: `src/index.ts` (wiring), which passes the resulting
+ * provider's model instance into `createSummarizer` (src/session/summarizer.ts)
+ * and `runTurn` (src/session/agent-turn.ts).
+ */
+import { type OllamaProvider } from "ai-sdk-ollama";
+/**
+ * Returns an Ollama provider bound to `OLLAMA_HOST`.
+ *
+ * Throws synchronously if `OLLAMA_HOST` is unset or empty — there is no
+ * fallback to `localhost`, since which Ollama endpoint to use is a
+ * deployment decision, not something Mercury's code should guess.
+ */
+export declare function getOllamaProvider(): OllamaProvider;

package/dist/src/model/context-size.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Queries Ollama directly (its native HTTP API, not the AI SDK — which
+ * has no concept of this) for the real context window size the running
+ * model is currently loaded with.
+ *
+ * Why this exists, instead of just reading the model's architectural max
+ * context length (available via `/api/show`'s `model_info`): Ollama can
+ * load a model with a smaller effective context window than what the
+ * model architecture supports (e.g. capped by `OLLAMA_CONTEXT_LENGTH` on
+ * the server, or a per-request `num_ctx`), so the architectural max can
+ * overstate what's actually usable. `/api/ps` reports what's actually
+ * loaded right now — verified live against a real Ollama server (GB10,
+ * qwen3.5:35b): it loaded with the full architectural context (262144),
+ * but that's specific to this deployment's configuration, not something
+ * to assume in general.
+ *
+ * Used by: `src/index.ts`, to show a real (not estimated) context-usage
+ * indicator next to the terminal prompt — see `src/router/tool-log.ts`'s
+ * `formatContextUsage`.
+ */
+/**
+ * Returns the context length Ollama has the given model loaded with
+ * right now, or `null` if that model isn't currently loaded (e.g. before
+ * its first use this process) — `/api/ps` only lists loaded models, so
+ * there's nothing to report yet. Querying again after the model has
+ * been used at least once will find it.
+ *
+ * @param fetchFn - Test seam; defaults to the real global `fetch`.
+ */
+export declare function getLoadedContextLength(host: string, model: string, fetchFn?: typeof fetch): Promise<number | null>;

package/dist/src/plugins/manifest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Builds the read-only installation manifest the HTTP surface exposes (4b):
+ * what this instance actually loaded — the core's plugin apiVersion, each
+ * plugin (name, declared apiVersion, whether it activated, the skills it
+ * contributes, whether it has a `build()`), the active CLI binaries, and the
+ * skill descriptors. Pure and side-effect-free so it's unit-tested directly.
+ *
+ * A plugin no longer exposes a central config, so activation is reported from
+ * the loader's `activated` set rather than inferred from a config map. The
+ * active CLI binaries are the activated plugins plus the file-based CLIs (the
+ * residual with no owning plugin).
+ */
+import { type Plugin, type Skill } from "@mercury-fw/plugin-types";
+export type PluginManifest = {
+    coreApiVersion: number;
+    plugins: Array<{
+        name: string;
+        apiVersion: number;
+        active: boolean;
+        skills: string[];
+        hasBuild: boolean;
+    }>;
+    activeClis: string[];
+    skills: Array<{
+        name: string;
+        description: string;
+    }>;
+};
+export declare function buildPluginManifest(plugins: Plugin[], activatedPluginNames: string[], fileCliBinaries: string[], skills: Skill[]): PluginManifest;

package/dist/src/plugins/plugin-loader.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The generic, fail-soft plugin loader. Turns a hand-listed set of plugin
+ * modules into what the composition root wires into a running Mercury: the
+ * per-plugin tool bundles the model-facing tools are built from, their status
+ * describers, the system-prompt fragments, and the post-turn guards. It knows
+ * nothing about any specific plugin — or about CLIs — the composition root
+ * names them, this loop processes them identically.
+ *
+ * Two properties it guarantees, both required by the plan's fail-soft step:
+ *  - a plugin contributes only when it is enabled on this instance (its name is
+ *    in MERCURY_CLIS);
+ *  - a plugin that fails — its `build()` throws — degrades as a single unit:
+ *    none of its contributions land, the failure is
+ *    logged with detail, and every other plugin and the process itself carry
+ *    on. This is the CLAUDE.md lesson made structural: one plugin's bad tick
+ *    never takes down the rest.
+ *
+ * The contract types (`Plugin`, `SessionToolContext`, `CliPostProcessor`,
+ * `PostTurnGuard`, and the `build()` context) live in `@mercury-fw/plugin-types`,
+ * the shared package both the core and the plugins import, so neither mirrors
+ * the other. This module keeps only the core-runtime pieces: how a hand-listed
+ * set of plugins is loaded and what the load produces.
+ */
+import type { LanguageModel } from "ai";
+import type { Plugin, CliPostProcessor, PostTurnGuard, Skill, SessionToolContext } from "@mercury-fw/plugin-types";
+import type { Tool } from "ai";
+/** One plugin's tool contribution, kept paired so the composition root can build
+ * its tools from its own post-processor: the plugin authored both, but a
+ * formatter decorator wraps the post-processor after `build()` returns, so the
+ * factory receives the final one at invocation rather than closing over it. */
+export interface SessionToolBundle {
+    build: (ctx: SessionToolContext, postProcess?: CliPostProcessor) => Record<string, Tool>;
+    postProcess?: CliPostProcessor;
+}
+/** What the loader hands back to the composition root, aggregated across every
+ * plugin that loaded. The core knows nothing about CLIs: a plugin's tool is an
+ * opaque `SessionToolBundle` it contributed, not a config the core assembles. */
+export interface LoadedPlugins {
+    promptFragments: string[];
+    skills: Skill[];
+    /** Per-plugin tool factories + their post-processors; the composition root
+     * invokes each per turn with the session context (see `SessionToolBundle`). */
+    sessionToolBundles: SessionToolBundle[];
+    /** Merged across plugins, keyed by the tool name each contributes, turning a
+     * tool call's input into its status label. */
+    toolStatusDescribers: Record<string, (input: unknown) => string>;
+    postTurnGuards: PostTurnGuard[];
+    /** Names of the plugins that fully activated — for read-only introspection
+     * (the manifest), since a plugin's tool is opaque and there's no central
+     * config map to infer activation from anymore. */
+    activated: string[];
+}
+/** Everything the loader needs from the composition root: which plugins are
+ * enabled on this instance, and the runtime context every `build()` gets. */
+export interface PluginLoadContext {
+    enabledClis: string[];
+    model: LanguageModel;
+    env: Record<string, string | undefined>;
+    log: (msg: string) => void;
+}
+/**
+ * Orders `plugins` so every plugin comes after each of its declared `dependsOn`
+ * (a stable topological sort: among plugins with no ordering constraint between
+ * them, listing order is preserved). Only edges to a plugin actually present in
+ * the set are honored — an unknown dependency name creates no edge and is
+ * caught later, at activation, as an absent dependency. Any plugin left over
+ * after the sort is part of, or downstream of, a dependency **cycle**: it comes
+ * back in `cyclic`, never in `ordered`, so a cycle degrades fail-soft (the
+ * caller skips those plugins) instead of dropping the whole load.
+ */
+export declare function orderByDependencies(plugins: Plugin[]): {
+    ordered: Plugin[];
+    cyclic: Plugin[];
+};
+/**
+ * Loads every plugin in `plugins`, returning their combined contributions.
+ * Plugins load in dependency-first order (see `orderByDependencies`), not
+ * listing order — though listing order is preserved among plugins with no
+ * dependency between them. Never throws — a plugin that fails is logged and
+ * skipped, its contributions staged and merged only once the whole plugin
+ * succeeds so a later failure can't leave it half-wired. A plugin whose
+ * declared `dependsOn` isn't fully activated (a dependency disabled, failed,
+ * unknown, or itself skipped) is skipped fail-soft too, transitively.
+ */
+export declare function loadPlugins(plugins: Plugin[], ctx: PluginLoadContext): Promise<LoadedPlugins>;

package/dist/src/router/channel-loader.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Loads the hand-listed channel plugins into the providers the composition root
+ * starts — the channel-side mirror of `plugins/plugin-loader.ts`. It knows
+ * nothing about any specific channel: the composition root names them, this
+ * loop builds them identically.
+ *
+ * A channel is active when it's declared in `mercury.config.ts`'s `channels`
+ * (there is no separate env gate): declared = active. Each channel self-gates on
+ * its real config via `build()` returning `undefined` (Google Chat with no
+ * subscription; HTTP always builds).
+ *
+ * Fail-soft, same guarantees as the tool-plugin loader:
+ *  - an `apiVersion` mismatch is refused before `build()` runs;
+ *  - a `build()` that throws degrades as a single unit (logged, skipped) while
+ *    every other channel and the process carry on;
+ *  - a `build()` that returns `undefined` means "present but inert" (the
+ *    instance isn't configured for it) — not started, not an error.
+ */
+import { type ChannelPlugin, type ChannelRuntimeContext, type Provider } from "@mercury-fw/channel-types";
+/** Everything the loader needs from the composition root: the runtime context every `build()` gets. */
+export type LoadChannelsContext = {
+    runtime: ChannelRuntimeContext;
+};
+/** One built channel, kept with its plugin name so the composition root can start it and look it up (e.g. the cron `Notifier`). */
+export type LoadedChannel = {
+    name: string;
+    provider: Provider;
+};
+/** Builds every declared channel in `channels`, returning the providers that actually constructed (skipping incompatible, inert, or failed ones). */
+export declare function loadChannels(channels: ChannelPlugin[], ctx: LoadChannelsContext): LoadedChannel[];

package/dist/src/router/provider.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Channel contract, re-exported from `@mercury-fw/channel-types`. A thin shim so
+ * the core modules importing from `router/provider.ts` don't change; the
+ * definitions moved to the shared package so channel plugins can import them
+ * without depending on the app.
+ */
+export type { Provider, InboundTurn, TurnSink, HandleTurn, Notifier } from "@mercury-fw/channel-types";

package/dist/src/router/terminal-provider.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The terminal channel's `Provider` implementation — wraps
+ * `startTerminalRepl` (`src/router/terminal.ts`, unmodified) and owns
+ * everything specific to running Mercury from a terminal: the `/dump`
+ * command, bare-token confirmation interception, the dim/italic
+ * tool-status rendering, and the live context-usage prompt suffix.
+ *
+ * A single operator, one conversation at a time — there is no real
+ * per-user identity here, so `notify` just writes to stderr rather than
+ * actually reaching anyone; implemented (not left optional) so a caller
+ * that expects a `Notifier` never silently loses a message.
+ */
+import { startTerminalRepl } from "./terminal.ts";
+import { tryConfirm, type ConfirmationStore } from "@mercury-fw/confirm-engine";
+import { getLoadedContextLength } from "../model/context-size.ts";
+import type { Provider } from "./provider.ts";
+import type { writeConfirmationNote } from "../wiki/wiki-note.ts";
+export type TerminalProviderDeps = {
+    confirmDeps: {
+        store: ConfirmationStore;
+        vaultPath: string;
+        writeConfirmationNoteFn: typeof writeConfirmationNote;
+        now?: () => Date;
+    };
+    ollamaHost: string;
+    ollamaModel: string;
+    /** Test seam; defaults to the real `getLoadedContextLength`. */
+    getLoadedContextLengthFn?: typeof getLoadedContextLength;
+    /** Test seam; defaults to the real `startTerminalRepl`. */
+    startTerminalReplFn?: typeof startTerminalRepl;
+    /** Test seam; defaults to the real `tryConfirm`. */
+    tryConfirmFn?: typeof tryConfirm;
+    /** Test seam; defaults to `console.error`. */
+    stderrWrite?: (s: string) => void;
+};
+/** Builds the terminal's `Provider`. */
+export declare function createTerminalProvider(deps: TerminalProviderDeps): Provider;

package/dist/src/router/terminal.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Written before the first input and again after every result, so a
+ * human at the terminal can tell an answer has finished and the next
+ * question can be typed — without this, a multi-line answer and the
+ * start of a new question were visually indistinguishable.
+ */
+export declare const PROMPT = "> ";
+/**
+ * Runs the REPL loop: read a line, pass it to `handleInput`, write the
+ * result, repeat until the input source is exhausted (EOF).
+ *
+ * If `handleInput` rejects, the error is written as a line (so a long-
+ * running debug session can see what went wrong) and the loop continues
+ * with the next line — one bad turn shouldn't kill the whole session.
+ *
+ * @param handleInput - Turns one line of input into one line of output.
+ *   Knows nothing about this being a terminal. Receives `onChunk`, which
+ *   it may call zero or more times with pieces of the answer as they
+ *   become available (e.g. while streaming a model response) — each
+ *   call is written immediately, without waiting for `handleInput` to
+ *   resolve. If `onChunk` is never called, the function's returned
+ *   string is written instead once `handleInput` resolves, exactly as
+ *   before streaming existed — this is what keeps the `/dump` command
+ *   and any other non-streaming reply working unchanged.
+ * @param io - Test seam. Defaults to real stdin/stdout when omitted.
+ * @param opts.promptSuffix - Optional, called fresh right before every
+ *   prompt (including the very first one) and written ahead of it — e.g.
+ *   a live context-usage indicator (see `src/router/tool-log.ts`'s
+ *   `formatContextUsage`), recomputed each time since the value changes
+ *   turn to turn.
+ */
+export declare function startTerminalRepl(handleInput: (input: string, onChunk: (chunk: string) => void) => Promise<string>, io?: {
+    input?: AsyncIterable<string>;
+    output?: {
+        write(s: string, opts?: {
+            newline?: boolean;
+        }): void;
+    };
+}, opts?: {
+    promptSuffix?: () => string;
+}): Promise<void>;