@mercury-fw/core 0.25.0

package/src/session/agent-turn.ts

@@ -0,0 +1,391 @@
+/**
+ * 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 { isStepCount, type LanguageModel, type StopCondition, type Tool } from "ai";
+import { generateText, streamText } from "ai-sdk-ollama";
+import type { Message, SessionHistory } from "./history.ts";
+import type { StepInfo } from "./step-info.ts";
+import { detectPendingConfirmation } from "./pending-confirmation.ts";
+// The sentinel is a channel-side contract value (see `@mercury-fw/channel-types`);
+// re-exported here for the core callers importing it from this module.
+import { PENDING_CONFIRMATION_NOTE } from "@mercury-fw/channel-types";
+export { PENDING_CONFIRMATION_NOTE };
+
+/** `""` unless `lastStep` staged a confirm-required command, in which case `PENDING_CONFIRMATION_NOTE`. */
+function resolveEmptyText(lastStep: StepInfo | undefined): string {
+  return lastStep && detectPendingConfirmation(lastStep) ? PENDING_CONFIRMATION_NOTE : "";
+}
+
+/**
+ * What actually gets recorded into `SessionHistory` for this turn — `displayText`
+ * unchanged, except when `lastStep` staged a confirm-required command: then
+ * it's the opaque `[REQ:<token>]` marker instead, regardless of `displayText`.
+ * The two diverge on purpose: `displayText` (what the channel shows/streams)
+ * stays the fixed `PENDING_CONFIRMATION_NOTE` sentence — both channels
+ * already suppress that exact string and show their own UI instead (a card,
+ * a printed instruction) — but that sentence must never reach persistent
+ * memory. A confirmation token is ephemeral by design (in-memory only, a
+ * few minutes' TTL — see `confirmation-store.ts`), so any summarized record
+ * claiming an action is "still pending" goes stale almost immediately;
+ * this is the stale-primer bug's actual fix. The marker forces a reader
+ * (the model, later, via `context-primer.ts`'s "Riferimenti aperti" +
+ * `resolve_reference` in `wiki-tools.ts`) to deliberately look up what it
+ * refers to instead of absorbing a claim that may no longer be true.
+ */
+function resolveHistoryText(lastStep: StepInfo | undefined, displayText: string): string {
+  const pending = lastStep ? detectPendingConfirmation(lastStep) : null;
+  return pending ? `[REQ:${pending.token}]` : displayText;
+}
+
+/**
+ * Stops the tool-calling loop immediately after a step that staged a
+ * confirm-required command — the model never gets a further step to
+ * write anything about it (see `PENDING_CONFIRMATION_NOTE` above for
+ * why). `stopWhen` conditions are OR'd together (confirmed against the
+ * AI SDK's own source: `isStopConditionMet` resolves every condition and
+ * stops if *any* is true), so combining this with `stepCountIs(100)`
+ * doesn't change when the step-budget cap itself kicks in.
+ */
+function pendingConfirmationStop(): StopCondition<any> {
+  return ({ steps }) => {
+    const last = steps[steps.length - 1];
+    return last !== undefined && detectPendingConfirmation(last) !== null;
+  };
+}
+
+/** 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 function buildGenerateTextParams(params: {
+  model: LanguageModel;
+  messages: Message[];
+  tools: Record<string, Tool>;
+  instructions: string;
+  onStepEnd?: (step: StepInfo) => void;
+  abortSignal?: AbortSignal;
+}) {
+  return { ...params, stopWhen: [isStepCount(100), pendingConfirmationStop()] };
+}
+
+/** Default production implementation: calls the real `generateText` from `ai`. */
+const defaultGenerateTextFn: GenerateTextFn = (params) =>
+  generateText(buildGenerateTextParams(params));
+
+/**
+ * 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 function buildStreamTextParams(params: {
+  model: LanguageModel;
+  messages: Message[];
+  tools: Record<string, Tool>;
+  instructions: string;
+  onStepEnd?: (step: StepInfo) => void;
+  abortSignal?: AbortSignal;
+}) {
+  return { ...params, stopWhen: [isStepCount(100), pendingConfirmationStop()] };
+}
+
+/** Default production implementation: calls the real `streamText` from `ai-sdk-ollama`. */
+const defaultStreamTextFn: StreamTextFn = (params) => streamText(buildStreamTextParams(params));
+
+/**
+ * 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 async 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> {
+  await history.addUserMessage(userInput);
+
+  if (deps.onTextChunk || deps.onReasoningChunk) {
+    const stream = deps.streamTextFn ?? defaultStreamTextFn;
+    let lastStep: StepInfo | undefined;
+    const result = await stream({
+      model: deps.model,
+      messages: history.getMessages(),
+      tools: deps.tools,
+      instructions: deps.system,
+      abortSignal: deps.abortSignal,
+      onStepEnd: (step) => {
+        lastStep = step;
+        deps.onStepFinish?.(step);
+      },
+    });
+
+    let fullText = "";
+    // The id of the reasoning block currently open, if any — a tool-
+    // calling turn can reason multiple times (before a tool call, again
+    // after seeing its result, ...), each burst carrying its own id from
+    // the SDK. Tracking only the *current* one (not a set of all-ever-seen
+    // ids) is enough: it's `undefined` whenever no block is open, which is
+    // exactly when the abrupt-failure guard below must stay silent.
+    let currentReasoningId: string | undefined;
+    try {
+      for await (const part of result.stream) {
+        if (part.type === "text-delta") {
+          const delta = part.text ?? part.delta ?? "";
+          fullText += delta;
+          deps.onTextChunk?.(delta);
+        } else if (part.type === "reasoning-delta") {
+          const id = part.id ?? "";
+          currentReasoningId = id;
+          deps.onReasoningChunk?.(part.text ?? part.delta ?? "", id);
+        } else if (part.type === "reasoning-end") {
+          const id = part.id ?? "";
+          currentReasoningId = undefined;
+          deps.onReasoningEnd?.(id, false);
+        }
+      }
+    } finally {
+      // Guarantees onReasoningEnd fires even if the stream throws
+      // mid-reasoning (no reasoning-end part arrives on an abrupt
+      // failure) — a caller building a live display (a status card, a
+      // printed block) can't be left stuck open forever. Only fires for
+      // whichever block was actually open when the failure happened
+      // (`currentReasoningId` is cleared by a normal reasoning-end, so
+      // this is a no-op outside an open block). `failed: true` here (vs.
+      // `false` on a normal reasoning-end above) is what lets a caller
+      // like Google Chat's status card show the right outcome — without
+      // it, every abrupt failure would look identical to a clean finish.
+      if (currentReasoningId !== undefined) {
+        deps.onReasoningEnd?.(currentReasoningId, true);
+      }
+    }
+    deps.onUsage?.((await result.usage)?.inputTokens);
+
+    if (fullText.trim().length === 0) {
+      fullText = resolveEmptyText(lastStep);
+      if (fullText.length > 0) deps.onTextChunk?.(fullText);
+    }
+
+    await history.addAssistantMessage(resolveHistoryText(lastStep, fullText));
+    return fullText;
+  }
+
+  const generate = deps.generateTextFn ?? defaultGenerateTextFn;
+  let lastStep: StepInfo | undefined;
+  const result = await generate({
+    model: deps.model,
+    messages: history.getMessages(),
+    tools: deps.tools,
+    instructions: deps.system,
+    abortSignal: deps.abortSignal,
+    onStepEnd: (step) => {
+      lastStep = step;
+      deps.onStepFinish?.(step);
+    },
+  });
+  deps.onUsage?.(result.usage?.inputTokens);
+
+  const text = result.text.trim().length === 0 ? resolveEmptyText(lastStep) : result.text;
+  await history.addAssistantMessage(resolveHistoryText(lastStep, text));
+  return text;
+}

package/src/session/context-primer.ts

@@ -0,0 +1,134 @@
+/**
+ * Builds the synthetic primer text seeded into a brand-new Google Chat
+ * session's history (see `history.ts`'s `primer` param): the wiki's own
+ * index (same for every user, not tied to any prior session), the wiki
+ * facts the user's last closed session actually reinforced, plus that same
+ * session's own episodic entries. Empty string when there's nothing —
+ * enrichment, a caller must work fine without it. Deliberately not
+ * similarity retrieval: there's no query yet to compare against at session
+ * start, only "what happened last time" (see `getLastSessionEpisodicSummaries`)
+ * plus "what's in the wiki right now".
+ */
+import { resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+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;
+};
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
+
+/** Same frontmatter shape `semantic-consolidation.ts` already parses (`derived_from: string[]`) — only `inferred` notes carry it, a `resolved`/`curated` note yields none. */
+function derivedFromTimestamps(text: string): string[] {
+  const match = FRONTMATTER_RE.exec(text);
+  if (!match) {
+    return [];
+  }
+  const frontmatter = parseYaml(match[1] as string) as { derived_from?: unknown };
+  return Array.isArray(frontmatter.derived_from) ? frontmatter.derived_from : [];
+}
+
+/** The note's content after its frontmatter block — matches `writeNoteFile`'s `---\n<yaml>---\n\n<body>\n` layout. */
+function noteBody(text: string): string {
+  const match = FRONTMATTER_RE.exec(text);
+  return (match ? text.slice(match[0].length) : text).trim();
+}
+
+/** Extracts a confirmation note's `status` field — `undefined` for anything not shaped like one (missing/unparseable frontmatter). */
+function noteStatus(text: string): string | undefined {
+  const match = FRONTMATTER_RE.exec(text);
+  if (!match) {
+    return undefined;
+  }
+  const frontmatter = parseYaml(match[1] as string) as { status?: unknown };
+  return typeof frontmatter.status === "string" ? frontmatter.status : undefined;
+}
+
+/**
+ * Tokens of this user's still-`"pending"` confirmation notes
+ * (`inferred/confirmations/<userId>/<token>.md` — see `writeConfirmationNote`
+ * in `wiki-note.ts`). Deliberately a separate lookup from the "Known facts"
+ * cross-reference below: this subtree isn't correlated to the last
+ * session's episodic timestamps, it's simply "whatever is still open right
+ * now" for this user, regardless of which session staged it.
+ */
+async function pendingConfirmationTokens(userId: string, deps: ContextPrimerDeps): Promise<string[]> {
+  const confirmationsRoot = resolve(deps.vaultPath, "inferred", "confirmations", encodeURIComponent(userId));
+  const files = await deps.listWikiFilesInRootsFn(deps.vaultPath, [confirmationsRoot]);
+  const tokens: string[] = [];
+  for (const file of files) {
+    const text = await deps.readWikiFileInRootsFn(deps.vaultPath, [confirmationsRoot], file);
+    if (noteStatus(text) === "pending") {
+      tokens.push(file.split("/").pop()!.replace(/\.md$/, ""));
+    }
+  }
+  return tokens;
+}
+
+/**
+ * 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 async function buildContextPrimer(userId: string, deps: ContextPrimerDeps): Promise<string> {
+  const entries = await deps.getLastSessionEntries(userId);
+  // Checked regardless of `entries` — a pending confirmation isn't tied to
+  // "was there a prior episodic session", it's simply still open right now.
+  const pendingTokens = await pendingConfirmationTokens(userId, deps);
+  // Same for every user (curated/ has no per-user scoping) — checked
+  // regardless of prior session too, so even a first-ever session gets
+  // pointed at what's in the wiki right now.
+  const indexContent = (await deps.readIndexFileFn(deps.vaultPath)).trim();
+
+  if (entries.length === 0 && pendingTokens.length === 0 && indexContent.length === 0) {
+    return "";
+  }
+
+  const sections: string[] = [];
+
+  if (indexContent.length > 0) {
+    sections.push(`Wiki index:\n${indexContent}`);
+  }
+
+  if (entries.length > 0) {
+    const entryTimestamps = new Set(entries.map((e) => e.timestamp));
+    const inferredRoot = resolve(deps.vaultPath, "inferred", "users", encodeURIComponent(userId));
+    const files = await deps.listWikiFilesInRootsFn(deps.vaultPath, [inferredRoot]);
+
+    const facts: string[] = [];
+    for (const file of files) {
+      const text = await deps.readWikiFileInRootsFn(deps.vaultPath, [inferredRoot], file);
+      const timestamps = derivedFromTimestamps(text);
+      if (!timestamps.some((ts) => entryTimestamps.has(ts))) {
+        continue;
+      }
+      const topic = file.split("/").pop()!.replace(/\.md$/, "");
+      const body = noteBody(text);
+      if (body) {
+        facts.push(`${topic}: ${body}`);
+      }
+    }
+
+    if (facts.length > 0) {
+      sections.push(`Known facts:\n${facts.map((f) => `- ${f}`).join("\n")}`);
+    }
+    sections.push(`Last session:\n${entries.map((e) => `- ${e.summary}`).join("\n")}`);
+  }
+
+  // Deliberately opaque: just the token, no command, no "still pending"
+  // narrative — see pendingConfirmationTokens's own doc comment for why.
+  // Resolving it into something meaningful requires the model to
+  // deliberately call resolve_reference (wiki-tools.ts) with the token.
+  if (pendingTokens.length > 0) {
+    sections.push(`Riferimenti aperti:\n${pendingTokens.map((t) => `- [REQ:${t}]`).join("\n")}`);
+  }
+
+  return sections.join("\n\n");
+}

package/src/session/episodic-summarizer.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { generateText, 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 function createEpisodicSummarizer(
+  model: LanguageModel,
+): (messages: Message[]) => Promise<string> {
+  return async (messages) => {
+    const { text } = await generateText({
+      model,
+      instructions:
+        "Summarize what happened in this conversation as a short, factual account for future recall — what was discussed, asked, or decided. Describe only what occurred in this session. Do not infer patterns, habits, or preferences about the user — that is a separate process, not this one. Never mention or guess a date — you don't reliably know the current date, and it's tracked separately from this text.",
+      prompt: messages.map((m) => `${m.role}: ${m.content}`).join("\n"),
+    });
+    return text;
+  };
+}