@mercury-fw/core 0.25.0

package/src/model/context-size.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 async function getLoadedContextLength(
+  host: string,
+  model: string,
+  fetchFn: typeof fetch = fetch,
+): Promise<number | null> {
+  const response = await fetchFn(`${host}/api/ps`);
+  const data = (await response.json()) as {
+    models?: Array<{ model: string; context_length?: number }>;
+  };
+  const entry = data.models?.find((m) => m.model === model);
+  return entry?.context_length ?? null;
+}

package/src/plugins/manifest.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 { PLUGIN_API_VERSION, 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 function buildPluginManifest(
+  plugins: Plugin[],
+  activatedPluginNames: string[],
+  fileCliBinaries: string[],
+  skills: Skill[],
+): PluginManifest {
+  const activated = new Set(activatedPluginNames);
+  return {
+    coreApiVersion: PLUGIN_API_VERSION,
+    plugins: plugins.map((p) => ({
+      name: p.name,
+      apiVersion: p.apiVersion,
+      active: activated.has(p.name),
+      skills: (p.skills ?? []).map((s) => s.name),
+      hasBuild: Boolean(p.build),
+    })),
+    activeClis: [...activatedPluginNames, ...fileCliBinaries].sort(),
+    skills: skills.map((s) => ({ name: s.name, description: s.description })),
+  };
+}

package/src/plugins/plugin-loader.ts

@@ -0,0 +1,205 @@
+/**
+ * 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 { PLUGIN_API_VERSION } from "@mercury-fw/plugin-types";
+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 function orderByDependencies(plugins: Plugin[]): { ordered: Plugin[]; cyclic: Plugin[] } {
+  const present = new Set(plugins.map((p) => p.name));
+  const remainingDeps = new Map<string, number>();
+  for (const p of plugins) {
+    // Distinct present dependencies only: the emit loop decrements once per
+    // dependency, so counting a name listed twice would wedge the plugin at a
+    // count that never reaches zero — misreported as a cycle (regression).
+    remainingDeps.set(p.name, new Set((p.dependsOn ?? []).filter((d) => present.has(d))).size);
+  }
+
+  const ordered: Plugin[] = [];
+  const emitted = new Set<string>();
+  // Repeatedly emit every plugin whose remaining dependencies are all already
+  // emitted, scanning in listing order so independent plugins keep it. Loop
+  // until a full pass emits nothing — whatever is left then is cyclic.
+  let progressed = true;
+  while (progressed) {
+    progressed = false;
+    for (const p of plugins) {
+      if (emitted.has(p.name)) continue;
+      if ((remainingDeps.get(p.name) ?? 0) !== 0) continue;
+      emitted.add(p.name);
+      ordered.push(p);
+      progressed = true;
+      for (const other of plugins) {
+        if (!emitted.has(other.name) && (other.dependsOn ?? []).includes(p.name)) {
+          remainingDeps.set(other.name, (remainingDeps.get(other.name) ?? 0) - 1);
+        }
+      }
+    }
+  }
+
+  const cyclic = plugins.filter((p) => !emitted.has(p.name));
+  return { ordered, cyclic };
+}
+
+/**
+ * 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 async function loadPlugins(plugins: Plugin[], ctx: PluginLoadContext): Promise<LoadedPlugins> {
+  const promptFragments: string[] = [];
+  const skills: Skill[] = [];
+  const sessionToolBundles: SessionToolBundle[] = [];
+  const toolStatusDescribers: Record<string, (input: unknown) => string> = {};
+  const postTurnGuards: PostTurnGuard[] = [];
+
+  const { ordered, cyclic } = orderByDependencies(plugins);
+  // A plugin caught in a cycle can't be ordered, so it can't load. Report it
+  // only when it's enabled — a disabled plugin contributes nothing regardless,
+  // same silence as any other disabled plugin.
+  for (const plugin of cyclic) {
+    if (ctx.enabledClis.includes(plugin.name)) {
+      ctx.log(`plugin "${plugin.name}" not activated: part of or depends on a dependency cycle`);
+    }
+  }
+
+  // Names that fully activated — a dependency must be in here for a dependent
+  // to load. Populated in dependency-first order, so a dependent is always
+  // processed after its dependencies have had their chance.
+  const activated = new Set<string>();
+
+  for (const plugin of ordered) {
+    // Not enabled on this instance: contribute nothing, and don't even
+    // validate the config — same as a CLI left out of MERCURY_CLIS.
+    if (!ctx.enabledClis.includes(plugin.name)) {
+      continue;
+    }
+    // Contract-version skew: core and plugin are versioned and installed
+    // separately, so a plugin built against a different contract than this core
+    // supports is possible. Refuse it fail-soft rather than run it against a
+    // shape it may not match.
+    if (plugin.apiVersion !== PLUGIN_API_VERSION) {
+      ctx.log(
+        `plugin "${plugin.name}" not activated: apiVersion ${plugin.apiVersion} ` +
+          `incompatible with this core (supports ${PLUGIN_API_VERSION})`,
+      );
+      continue;
+    }
+    // Every declared dependency must have fully activated first. Because we
+    // process in dependency-first order, a dependency that was going to load
+    // already has; anything still missing is disabled, failed, unknown, or
+    // itself skipped — so this dependent degrades fail-soft too. Checked before
+    // touching this plugin's own build, so a doomed plugin does no work.
+    const missingDeps = (plugin.dependsOn ?? []).filter((dep) => !activated.has(dep));
+    if (missingDeps.length > 0) {
+      ctx.log(
+        `plugin "${plugin.name}" not activated: dependency ${missingDeps.map((d) => `"${d}"`).join(", ")} absent or failed`,
+      );
+      continue;
+    }
+    try {
+      // Stage into locals first: build() can throw, and a plugin must degrade
+      // as a unit — nothing of it lands unless all of it succeeds.
+      const contributions = plugin.build ? plugin.build({ model: ctx.model, env: ctx.env, log: ctx.log }) : {};
+
+      if (plugin.systemPromptFragment !== undefined) {
+        promptFragments.push(plugin.systemPromptFragment);
+      }
+      if (plugin.skills !== undefined) {
+        skills.push(...plugin.skills);
+      }
+      if (contributions.sessionTools) {
+        sessionToolBundles.push({
+          build: contributions.sessionTools,
+          postProcess: contributions.postProcess,
+        });
+      }
+      if (contributions.toolStatusDescribers) {
+        Object.assign(toolStatusDescribers, contributions.toolStatusDescribers);
+      }
+      if (contributions.postTurnGuards) {
+        postTurnGuards.push(...contributions.postTurnGuards);
+      }
+      // Fully wired — only now does it count as a satisfied dependency for
+      // anything that declared `dependsOn` on it.
+      activated.add(plugin.name);
+    } catch (err) {
+      ctx.log(`plugin "${plugin.name}" failed to load, skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return { promptFragments, skills, sessionToolBundles, toolStatusDescribers, postTurnGuards, activated: [...activated] };
+}

package/src/router/channel-loader.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { CHANNEL_API_VERSION, 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 function loadChannels(channels: ChannelPlugin[], ctx: LoadChannelsContext): LoadedChannel[] {
+  const loaded: LoadedChannel[] = [];
+
+  for (const channel of channels) {
+    if (channel.apiVersion !== CHANNEL_API_VERSION) {
+      ctx.runtime.log(
+        `channel "${channel.name}" not activated: apiVersion ${channel.apiVersion} ` +
+          `incompatible with this core (supports ${CHANNEL_API_VERSION})`,
+      );
+      continue;
+    }
+    try {
+      const provider = channel.build(ctx.runtime);
+      // undefined = present but inert (this instance isn't configured for it).
+      if (provider === undefined) {
+        continue;
+      }
+      loaded.push({ name: channel.name, provider });
+    } catch (err) {
+      ctx.runtime.log(
+        `channel "${channel.name}" failed to load, skipped: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  return loaded;
+}

package/src/router/provider.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/src/router/terminal-provider.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { parseDumpCommand, defaultDumpPath, writeDump, formatContextUsage } from "./tool-log.ts";
+import { getLoadedContextLength } from "../model/context-size.ts";
+import { detectPendingConfirmation } from "../session/pending-confirmation.ts";
+import { PENDING_CONFIRMATION_NOTE } from "../session/agent-turn.ts";
+import type { Provider, HandleTurn, TurnSink } from "./provider.ts";
+import type { StepInfo } from "../session/step-info.ts";
+import type { writeConfirmationNote } from "../wiki/wiki-note.ts";
+
+const TERMINAL_SESSION_KEY = "terminal";
+
+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 function createTerminalProvider(deps: TerminalProviderDeps): Provider {
+  const stderrWrite = deps.stderrWrite ?? ((s: string) => console.error(s));
+  const getLoadedContextLengthFn = deps.getLoadedContextLengthFn ?? getLoadedContextLength;
+  const tryConfirmFn = deps.tryConfirmFn ?? tryConfirm;
+  const startTerminalReplFn = deps.startTerminalReplFn ?? startTerminalRepl;
+
+  let lastSteps: StepInfo[] = [];
+  let lastInputTokens: number | undefined;
+  let contextLength: number | null = null;
+
+  return {
+    async start(handleTurn: HandleTurn): Promise<void> {
+      await startTerminalReplFn(
+        async (input, onChunk) => {
+          const dumpCommand = parseDumpCommand(input);
+          if (dumpCommand) {
+            const path = dumpCommand.path ?? defaultDumpPath();
+            await writeDump(path, lastSteps);
+            return `wrote ${lastSteps.length} tool step(s) from the last turn to ${path}`;
+          }
+
+          // Same deterministic interception as every other channel — never
+          // let running a previously-approved mutation depend on the model.
+          const confirmReply = await tryConfirmFn(input, TERMINAL_SESSION_KEY, {
+            ...deps.confirmDeps,
+            userId: TERMINAL_SESSION_KEY,
+          });
+          if (confirmReply !== null) {
+            return confirmReply;
+          }
+
+          lastSteps = [];
+          let finalText = "";
+          // Keyed by the SDK's own reasoning-block id: a tool-calling turn
+          // can reason more than once (before a tool call, again after
+          // seeing its result), each burst getting its own header/close
+          // rather than being mistaken for a continuation of the first.
+          const reasoningIdsStarted = new Set<string>();
+          const dim = (label: string) => onChunk(`\x1b[2m\x1b[3m${label}\x1b[0m\n`);
+          const sink: TurnSink = {
+            onToolStart: dim,
+            // PENDING_CONFIRMATION_NOTE is dropped here: onStep (below)
+            // already printed the specific instruction (command + token)
+            // for the same step — the generic note would be a second,
+            // redundant line saying nothing new.
+            onTextChunk: (chunk) => {
+              if (chunk !== PENDING_CONFIRMATION_NOTE) onChunk(chunk);
+            },
+            // Only ever fires for a model that actually supports Ollama's
+            // extended thinking (see src/index.ts's OLLAMA_THINK) — a
+            // non-reasoning model means this is simply never called, so
+            // there's no header and no output at all for that turn.
+            onReasoningChunk: (chunk, id) => {
+              if (!reasoningIdsStarted.has(id)) {
+                reasoningIdsStarted.add(id);
+                dim("Sto pensando…");
+              }
+              onChunk(`\x1b[2m\x1b[3m${chunk}\x1b[0m`);
+            },
+            onReasoningEnd: (id) => {
+              if (reasoningIdsStarted.has(id)) onChunk("\n");
+            },
+            onStep: (step) => {
+              lastSteps.push(step);
+              // cli-tool.ts no longer tells the model to relay a token as
+              // text (that's channel-specific now) — the terminal has to
+              // say it itself, from the structured step data.
+              const pending = detectPendingConfirmation(step);
+              if (pending) {
+                onChunk(`Azione in sospeso: \`${pending.summary}\` — scrivi: ${pending.token}\n`);
+              }
+            },
+            onUsage: (tokens) => {
+              lastInputTokens = tokens;
+            },
+            finalize: async (text) => {
+              finalText = text;
+            },
+            dispose: () => {},
+          };
+
+          await handleTurn(
+            {
+              channel: "terminal",
+              multiUser: false,
+              text: input,
+              sessionKey: TERMINAL_SESSION_KEY,
+              wikiUserId: TERMINAL_SESSION_KEY,
+              logPrefix: "",
+            },
+            sink,
+          );
+
+          // Lazy, on-demand: /api/ps only reports models actually loaded,
+          // and the model isn't loaded until its first real call.
+          if (contextLength === null) {
+            contextLength = await getLoadedContextLengthFn(deps.ollamaHost, deps.ollamaModel);
+          }
+          return finalText;
+        },
+        undefined,
+        { promptSuffix: () => formatContextUsage(lastInputTokens, contextLength) },
+      );
+    },
+
+    async notify(userId: string, text: string): Promise<{ sessionKey: string }> {
+      stderrWrite(`[notify] to ${userId}: ${text}`);
+      return { sessionKey: TERMINAL_SESSION_KEY };
+    },
+  };
+}

package/src/router/terminal.ts

@@ -0,0 +1,151 @@
+/**
+ * The stdin/stdout REPL loop behind the dev console: it feeds whatever it reads
+ * into a generic `handleInput` callback and writes back whatever that callback
+ * returns.
+ *
+ * Why this exists: the dev REPL (`bun run repl`) is a debug/bootstrap console,
+ * not a production channel — a single operator, identity-less, no memory
+ * capture. This file is the *only* place that touches stdin/stdout;
+ * `handleInput` itself doesn't know it's talking to a terminal.
+ *
+ * `io.input`/`io.output` are injectable specifically so this file is
+ * unit-testable without spawning a real subprocess or touching real stdin —
+ * the real entrypoint calls it with no `io` argument and gets the real terminal.
+ *
+ * Used by: `terminal-provider.ts`, wired from the `repl.ts` entrypoint (never by
+ * the headless service). `handleInput` there is a closure over `handleTurn`;
+ * it also receives an `onChunk` callback (see `startTerminalRepl`'s doc comment)
+ * forwarded as the sink's text streaming, so a model response prints as it
+ * streams in rather than going silent for the whole answer.
+ */
+import * as readline from "node:readline";
+
+/**
+ * Writes to the real process stdout. Appends a newline by default — the
+ * prompt is the one caller that passes `{ newline: false }`, since it
+ * must stay on the same line as whatever the user types next.
+ */
+function realOutputWrite(s: string, opts?: { newline?: boolean }): void {
+  process.stdout.write(opts?.newline === false ? s : s + "\n");
+}
+
+/**
+ * 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 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 async 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> {
+  // Real stdin. Passing `output` (needed for readline to own prompt
+  // rendering — see below) only when stdin is an actual TTY: passing it
+  // against a non-TTY stdin (a Docker container with nothing attached at
+  // all — distinct from a *piped* stdin, e.g. `printf ... | docker
+  // compose exec -T ...`, which still has real lines to read and works
+  // fine either way) crashed the whole process on startup — observed
+  // live: `AbortError: Stream reader cancelled via releaseLock()`,
+  // thrown from inside readline's own stream handling, not something
+  // this file can catch around. Without `output`, the same
+  // already-closed stdin just ends the loop with zero lines, same as
+  // before today's arrow-key fix — confirmed safe by every previous
+  // detached `docker compose up -d` in this project's history.
+  const isTTY = !io?.input && process.stdin.isTTY;
+  const rl = io?.input
+    ? null
+    : isTTY
+      ? readline.createInterface({ input: process.stdin, output: process.stdout })
+      : readline.createInterface({ input: process.stdin });
+  // readline in TTY mode intercepts Ctrl+C and emits 'SIGINT' on the interface
+  // instead of letting it propagate as a process signal — without this handler
+  // Ctrl+C does nothing and the only way to stop Mercury is kill from outside.
+  // Not unit-tested: this path requires the real readline in TTY mode, which
+  // the io.input test seam bypasses entirely.
+  if (isTTY && rl) {
+    rl.on("SIGINT", () => process.exit(0));
+  }
+  const input = io?.input ?? rl!;
+  const output = io?.output ?? { write: realOutputWrite };
+
+  const writePrompt = () => {
+    const suffix = opts?.promptSuffix?.() ?? "";
+    if (isTTY && rl) {
+      rl.setPrompt(suffix + PROMPT);
+      rl.prompt();
+      return;
+    }
+    if (suffix) {
+      output.write(suffix, { newline: false });
+    }
+    output.write(PROMPT, { newline: false });
+  };
+
+  writePrompt();
+  for await (const line of input) {
+    let streamed = false;
+    let streamedText = "";
+    const onChunk = (chunk: string) => {
+      streamed = true;
+      streamedText += chunk;
+      output.write(chunk, { newline: false });
+    };
+    try {
+      const result = await handleInput(line, onChunk);
+      if (!streamed) {
+        output.write(result);
+      } else if (result.startsWith(streamedText)) {
+        // The common case: nothing was streamed beyond what handleInput
+        // returns, or turn-runner.ts only appended text after generation
+        // finished (e.g. a display the model surfaced via `present`) — the
+        // already-streamed prefix is still there, so only the new suffix
+        // needs writing.
+        output.write(result.slice(streamedText.length));
+      } else {
+        // The final result no longer extends what was already streamed —
+        // e.g. turn-runner.ts's issue-list correction replaced the text
+        // with a rewrite or the fixed fallback. What's already printed
+        // can't be un-printed, so show the real final answer in full
+        // instead of a slice computed against text that isn't there
+        // anymore.
+        output.write(`\n\n[risposta corretta rispetto a quanto già mostrato sopra]\n\n${result}`);
+      }
+    } catch (err) {
+      if (streamed) {
+        output.write("");
+      }
+      output.write(`error: ${String(err instanceof Error ? err.message : err)}`);
+    }
+    writePrompt();
+  }
+}