@mercury-fw/core 0.25.0

package/src/router/tool-log.ts

@@ -0,0 +1,116 @@
+/**
+ * Helpers for the terminal channel's tool-call visibility (see
+ * `src/index.ts`'s `onStepFinish` wiring): tool results can be
+ * arbitrarily large — a single Jira issue search can return tens of KB
+ * of raw API JSON — so printing them in full on every turn isn't
+ * readable. `truncateForDisplay` bounds what gets printed live;
+ * `parseDumpCommand` + `writeDump` back the terminal-only `/dump`
+ * command, for when the full untruncated output is actually needed.
+ *
+ * This module is stateless and doesn't know about turns or sessions —
+ * `src/index.ts` owns the per-turn step history and decides when to call
+ * these.
+ */
+import { tmpdir } from "node:os";
+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 function truncateForDisplay(value: unknown, maxChars: number): string {
+  const json = JSON.stringify(value);
+  if (json.length <= maxChars) {
+    return json;
+  }
+  return `${json.slice(0, maxChars)}… (truncated, ${json.length} chars total — run /dump to write the full output to a file)`;
+}
+
+/**
+ * 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 function defaultDumpPath(now: Date = new Date()): string {
+  return `${tmpdir()}/mercury-last-tools-${now.toISOString().replace(/[:.]/g, "-")}.json`;
+}
+
+/**
+ * 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 function parseDumpCommand(line: string): { path: string | undefined } | null {
+  const match = line.trim().match(/^\/dump(?:\s+(\S+))?$/);
+  if (!match) {
+    return null;
+  }
+  return { path: match[1] };
+}
+
+/**
+ * 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 async function writeDump(path: string, steps: StepInfo[]): Promise<void> {
+  await Bun.write(path, JSON.stringify(steps, null, 2));
+}
+
+/**
+ * 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 function describeToolOutcome(step: StepInfo, toolCallId: string, maxChars: number): string {
+  const result = step.toolResults.find((r) => r.toolCallId === toolCallId);
+  if (result) {
+    return `[tool result] ${truncateForDisplay(result.output, maxChars)}`;
+  }
+  const errorPart = step.content.find((p) => p.type === "tool-error" && p.toolCallId === toolCallId);
+  if (errorPart) {
+    return `[tool error] ${truncateForDisplay(errorPart.error, maxChars)}`;
+  }
+  return "[tool result] (none)";
+}
+
+/**
+ * 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 function formatContextUsage(usedTokens: number | undefined, maxTokens: number | null): string {
+  const used = usedTokens === undefined ? "?" : Math.floor(usedTokens / 1000);
+  if (maxTokens === null) {
+    return `[~${used}k tokens] `;
+  }
+  const max = Math.floor(maxTokens / 1000);
+  return `[~${used}k/~${max}k tokens] `;
+}

package/src/router/turn-runner.ts

@@ -0,0 +1,205 @@
+/**
+ * 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";
+// `PostTurnGuard` is part of the plugin contract (a plugin's `build()` may
+// return these to inspect/rewrite the model's finished text), so it lives in
+// `@mercury-fw/plugin-types` and is re-exported here for the core callers that
+// import it from this module. No plugin ships one today; the mechanism stays
+// generic for future use. A guard that throws is caught by the core and never
+// blocks delivery — a guard failure is a quality miss, not a reason to
+// withhold an already-generated answer.
+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, InboundTurn, 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 function createTurnRunner(deps: TurnRunnerDeps): HandleTurn {
+  const postTurnGuards = deps.postTurnGuards ?? [];
+  const logPostTurnGuard = deps.logPostTurnGuardFn ?? ((message: string) => console.log(message));
+
+  return async (turn: InboundTurn, sink: TurnSink): Promise<void> => {
+    const tracked = turn.userId !== undefined;
+    if (tracked) {
+      deps.trackSession(turn.sessionKey, turn.userId as string, (deps.now ?? Date.now)());
+      deps.registerCaptureCallback(turn.sessionKey, sink.onToolStart, sink.onToolFinish);
+    }
+
+    const steps: StepInfo[] = [];
+    let history: SessionHistory;
+    // The model's own answer text (post-guards, before any surfaced `present`
+    // display is appended) — what the verbatim archive stores as the
+    // assistant's message. Assigned once the turn resolves successfully.
+    let assistantText = "";
+
+    try {
+      // Inside the try, not before it: a failure building the history
+      // (e.g. the context-primer's Qdrant query) must still release the
+      // sink (see TurnSink.dispose's doc comment) — a stuck-note timer
+      // already scheduled when the sink was constructed keeps running
+      // otherwise, firing on its own 60s schedule regardless of whether
+      // the turn itself already failed and was reported.
+      history = await deps.getOrCreateHistory(turn.sessionKey, tracked, turn.userId);
+      const text = await (deps.runTurnFn ?? runTurn)(history, turn.text, {
+        model: deps.model,
+        tools: deps.buildTools(turn.sessionKey, turn.wikiUserId, sink.onToolStart, sink.onToolFinish),
+        system: turn.multiUser ? deps.systemPrompts.multiUser : deps.systemPrompts.singleUser,
+        onTextChunk: sink.onTextChunk,
+        onReasoningChunk: sink.onReasoningChunk,
+        onReasoningEnd: sink.onReasoningEnd,
+        onStepFinish: (step) => {
+          steps.push(step);
+          deps.logStep(turn.logPrefix, step);
+          (deps.recordStepFn ?? recordStep)(turn.channel, turn.sessionKey, step);
+          sink.onStep?.(step);
+        },
+        onUsage: sink.onUsage,
+        abortSignal: turn.abortSignal,
+      });
+
+      let correctedText = text;
+      // Plugin-contributed post-turn guards, run in order. `shouldRun` gates
+      // both the rewrite and its status indicator (so a guard that doesn't
+      // engage shows nothing), and reuses the same onToolStart/onToolFinish
+      // machinery already shared with real tool calls and Layer-3 capture pings
+      // — terminal's dim-print and Google Chat's status-card patching both
+      // handle any (label, detail?, toolCallId?) triple generically. A guard
+      // that throws is caught here and never blocks delivery.
+      for (const guard of postTurnGuards) {
+        if (!guard.shouldRun(correctedText)) {
+          continue;
+        }
+        sink.onToolStart(guard.statusLabel, undefined, guard.statusId);
+        try {
+          const guarded = await guard.run(correctedText, steps);
+          sink.onToolFinish?.(guard.statusId, guarded.outcome);
+          if (guarded.log !== undefined) {
+            logPostTurnGuard(guarded.log);
+          }
+          correctedText = guarded.text;
+        } catch (err) {
+          sink.onToolFinish?.(guard.statusId, "failed");
+          logPostTurnGuard(
+            `[post-turn-guard] guard "${guard.statusId}" threw, kept text unchanged: ${String(err instanceof Error ? err.message : err)}`,
+          );
+        }
+      }
+
+      if (correctedText !== text) {
+        history.replaceLastAssistantMessage(correctedText);
+      }
+      assistantText = correctedText;
+
+      // Append only what the model chose to `present` this turn — never the
+      // whole set of tool-produced displays. Appending (not replacing) keeps
+      // the already-streamed prefix intact, so terminal.ts's safe-slice holds.
+      const surfaced = deps.takeSurfacedDisplays?.(turn.sessionKey) ?? [];
+      const finalText = [correctedText, ...surfaced].filter((part) => part !== "").join("\n\n");
+      await sink.finalize(finalText);
+    } finally {
+      sink.dispose();
+    }
+
+    if (tracked) {
+      await deps.maybeCapture(turn.sessionKey, history);
+      // Fail-soft: the verbatim archive is pure enrichment (principle #3).
+      // The answer is already delivered; a capture failure must never
+      // propagate out of this awaited handler and take the process down.
+      if (deps.captureVerbatim) {
+        // The archive is per-person and space-independent, so it keys on
+        // wikiUserId — Mercury's canonical per-user id, the same identity the
+        // wiki notes use — not the space-scoped session.
+        const userId = turn.wikiUserId;
+        try {
+          await deps.captureVerbatim({ sessionKey: turn.sessionKey, userId, role: "user", content: turn.text });
+          await deps.captureVerbatim({ sessionKey: turn.sessionKey, userId, role: "assistant", content: assistantText });
+        } catch (err) {
+          console.log(
+            `[verbatim-archive] capture failed, turn unaffected: ${String(err instanceof Error ? err.message : err)}`,
+          );
+        }
+      }
+    }
+    await deps.processToolCorrections(steps, sink.onToolStart, sink.onToolFinish);
+  };
+}