@mercury-fw/core 0.25.0

package/src/session/history.ts

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

package/src/session/pending-confirmation.ts

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

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

@@ -0,0 +1,38 @@
+/**
+ * Model-invocable loader for a plugin's Agent Skill body — the "load" half of
+ * the discover-then-load shape SKILL.md introduces. The system prompt carries
+ * only each skill's name and one-line description (see `buildSystemPrompt`);
+ * when a request matches one, the model calls this to pull the skill's full
+ * instructions into context, exactly as it calls a CLI's `--help` rather than
+ * carrying every flag in the prompt. Same `tool()`-wrapping split as
+ * `tool-log-recall-tool.ts` and `wiki-tools.ts`.
+ *
+ * Registered by the composition root only when at least one skill loaded, so an
+ * instance with no skills never exposes an empty tool.
+ */
+import { tool } from "ai";
+import { z } from "zod";
+import type { Skill, ExecutableTool } from "@mercury-fw/plugin-types";
+
+export function createReadSkillTool(skills: Skill[]): { read_skill: ExecutableTool } {
+  const byName = new Map(skills.map((s) => [s.name, s]));
+  const names = skills.map((s) => s.name).join(", ");
+  const read_skill = tool({
+    description:
+      "Load the full instructions for one of your skills by name. Each skill's name and one-line description " +
+      "is listed in your system prompt; call this to get its detailed how-to (conventions, flags, examples) " +
+      `BEFORE acting on a request it covers — the description alone is not enough. Available skills: ${names || "(none)"}.`,
+    inputSchema: z.object({
+      name: z.string().describe("The exact skill name from the 'Available skills' list in the system prompt."),
+    }),
+    execute: async ({ name }) => {
+      const skill = byName.get(name);
+      if (!skill) {
+        return { ok: false as const, error: `no skill named "${name}". Available skills: ${names || "(none)"}.` };
+      }
+      return { ok: true as const, data: skill.body };
+    },
+  });
+
+  return { read_skill };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Turns a closed session's messages into structured `{topic, value}`
+ * facts for the semantic consolidation engine (see
+ * `src/memory/semantic-facts-store.ts`) — distinct from
+ * `episodic-summarizer.ts`, which produces a prose account of the whole
+ * session. A single extracted fact here is a candidate, not yet a
+ * standing belief about the user: consolidation (a separate,
+ * deterministic step) decides whether repeated facts on the same topic
+ * are frequent enough to be promoted to a wiki note.
+ */
+import { generateObject, type LanguageModel } from "ai";
+import { z } from "zod";
+import type { Message } from "./history.ts";
+
+/**
+ * Closed vocabulary — the model can only ever return one of these exact
+ * values, never invent a new key for the same concept. Deliberately
+ * excludes identity/name: a registered Chat app's own `MESSAGE` event
+ * already carries the sender's `displayName` directly, so a semantic
+ * fact about "who the user is" would only duplicate or contradict that
+ * more authoritative source, never add anything — observed live as the
+ * `name`/`user-name` duplicate before this fix.
+ */
+export const SEMANTIC_FACT_TOPICS = ["team", "role", "preferred-language", "tools-used"] as const;
+export const SemanticFactSchema = z.object({ topic: z.enum(SEMANTIC_FACT_TOPICS), value: z.string() });
+export type SemanticFact = z.infer<typeof SemanticFactSchema>;
+
+type GenerateObjectFn = (params: {
+  model: LanguageModel;
+  output: "array";
+  schema: typeof SemanticFactSchema;
+  instructions: string;
+  prompt: string;
+}) => Promise<{ object: SemanticFact[] }>;
+
+const SYSTEM_PROMPT =
+  "Estrai fatti stabili e ricorrenti sull'utente da questa conversazione, scegliendo il topic " +
+  'esclusivamente tra questi quattro: "team", "role" (ruolo), "preferred-language" (lingua ' +
+  'preferita), "tools-used" (strumenti usati). Ogni fatto è una coppia {topic, value}: "value" è ' +
+  "quanto dichiarato o chiaramente implicato per quel topic. Non estrarre l'identità o il nome " +
+  "dell'utente — Mercury lo traccia già separatamente, non va incluso qui. Non estrarre dettagli " +
+  "specifici di un singolo task, validi solo per questa sessione — solo cose plausibilmente vere " +
+  "anche in futuro. Restituisci un array vuoto se non c'è nulla che qualifica tra i topic ammessi.";
+
+// index.ts prepends this to every user message before it reaches history,
+// so the model knows who it's talking to within a turn — bookkeeping
+// Mercury wrote itself, never something the user said. Left in, the
+// extractor mistakes the marker repeating in every turn for a "stable,
+// recurring fact" (this is exactly how the live name/user-name duplicate
+// happened): stripped here, only in this extractor, before the messages
+// are joined into the prompt.
+const SENDER_MARKER_RE = /^\[Da: [^\]]*\]\n/;
+
+/** Returns a function that extracts standing {topic, value} facts from a closed session's messages. */
+export function createSemanticFactExtractor(
+  model: LanguageModel,
+  generateObjectFn: GenerateObjectFn = generateObject as unknown as GenerateObjectFn,
+): (messages: Message[]) => Promise<SemanticFact[]> {
+  return async (messages) => {
+    const { object } = await generateObjectFn({
+      model,
+      output: "array",
+      schema: SemanticFactSchema,
+      instructions: SYSTEM_PROMPT,
+      prompt: messages.map((m) => `${m.role}: ${m.content.replace(SENDER_MARKER_RE, "")}`).join("\n"),
+    });
+    return object;
+  };
+}

package/src/session/step-info.ts

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

package/src/session/summarizer.ts

@@ -0,0 +1,36 @@
+/**
+ * Thin glue that turns `createSessionHistory`'s injected `summarize`
+ * dependency into a real LLM call.
+ *
+ * Kept separate from `history.ts` on purpose: `history.ts`'s threshold/
+ * merge/replace logic is the substantial part and is fully unit-tested
+ * with a fake summarizer; this file's only job is producing the prompt
+ * and calling `generateText`, which isn't worth mocking deeply for one
+ * line of glue.
+ *
+ * Used by: `src/index.ts` (wiring), which passes the result into
+ * `createSessionHistory` (see `src/session/history.ts`).
+ */
+import { generateText, type LanguageModel } from "ai";
+import type { Message } from "./history.ts";
+
+/**
+ * Returns a function matching `createSessionHistory`'s `summarize`
+ * signature, backed by `model`. The returned function asks the model to
+ * condense the given messages into a short summary that preserves
+ * names, ticket keys, and decisions — the things a future turn would
+ * otherwise lose once the raw messages are cleared.
+ */
+export function createSummarizer(
+  model: LanguageModel,
+): (messages: Message[]) => Promise<string> {
+  return async (messages) => {
+    const { text } = await generateText({
+      model,
+      instructions:
+        "Summarize this conversation concisely, preserving names, ticket keys, and decisions.",
+      prompt: messages.map((m) => `${m.role}: ${m.content}`).join("\n"),
+    });
+    return text;
+  };
+}

package/src/session/system-prompt.ts

@@ -0,0 +1,142 @@
+import { NO_REPLY } from "@mercury-fw/channel-types";
+import type { Skill } from "@mercury-fw/plugin-types";
+
+/** The assistant's persona, set by the instance: `identity` opens the system
+ * prompt, `tone` closes it. Either one left out falls back to its default. */
+export type Persona = { identity?: string; tone?: string };
+
+/** The identity an instance gets when its config sets none. */
+export const DEFAULT_PERSONA_IDENTITY = "You are Mercury, an internal assistant.";
+
+/** The tone an instance gets when its config sets none. */
+export const DEFAULT_PERSONA_TONE = [
+  "DO:",
+  "- Answer directly, in plain text only.",
+  "- Be dry but respectful, and complete.",
+  "- If you believe a point of view is useful, add it — but keep it brief and put it strictly at the end.",
+  "",
+  "DON'T:",
+  "- DON'T use Markdown formatting (no **, #, -, etc.), unless the user explicitly asks for it.",
+  "- DON'T introduce yourself as Mercury unless asked; the user already knows who you are.",
+  "- DON'T ask follow-up questions.",
+  "- DON'T add extra explanations or extra actions beyond what was requested.",
+].join("\n");
+
+/** A persona field's text, trimmed at the end (one kept in a Markdown file and
+ * imported as text always ends with a newline); empty or whitespace-only counts
+ * as left out and yields the default. */
+function personaSlot(text: string | undefined, fallback: string): string {
+  const trimmed = text?.trimEnd();
+  return trimmed ? trimmed : fallback;
+}
+
+/**
+ * Builds a system prompt that only describes tools actually present in
+ * `tools` (see `src/session/agent-turn.ts` for why a prompt mentioning
+ * an absent tool is a real bug, not a harmless no-op). The persona fills the
+ * first and last slots (see `personaSlot`).
+ */
+export function buildSystemPrompt(opts: {
+  pluginFragments: string[];
+  skills: Skill[];
+  multiUserChannel: boolean;
+  persona?: Persona;
+}): string {
+  const lines = [personaSlot(opts.persona?.identity, DEFAULT_PERSONA_IDENTITY)];
+  // Each loaded plugin's own always-on system-prompt fragment, inserted
+  // verbatim in the order the composition root supplies them. A plugin that
+  // failed to load contributes nothing — the fragment and the tool now come
+  // from the same place, which is what retires the "prompt describes a tool
+  // this instance doesn't have" bug class.
+  for (const fragment of opts.pluginFragments) {
+    lines.push(fragment);
+  }
+  // Skill descriptors (Agent Skills): only the name + one-line description stays
+  // in the prompt, always — enough to know a capability exists. The voluminous
+  // body loads on demand via the read_skill tool, the same discover-then-load
+  // shape the CLIs already use with --help, instead of paying for every skill's
+  // full instructions on every turn.
+  if (opts.skills.length > 0) {
+    lines.push(
+      [
+        "You have skills — capabilities whose detailed instructions you load on demand. Before acting on a request a skill covers, call read_skill with its name to load its full how-to first; the descriptions below say only which skill applies, never how to use it.",
+        "Available skills:",
+        ...opts.skills.map((s) => `- ${s.name}: ${s.description}`),
+      ].join("\n"),
+    );
+  }
+  // Always present (WIKI_VAULT_PATH is a required env var, the vault
+  // always exists once Mercury boots) — unlike jira, this
+  // block doesn't need its own opts flag.
+  lines.push(
+    [
+      "You have access to wiki tools: list_files, read_file, grep, write_file, resolve_reference — Mercury's own knowledge base. " +
+        "curated/ is team knowledge (conventions, docs, project status) — written by maintainers, and by you. " +
+        "inferred/ is private per-user notes managed automatically by a separate process, not by you directly.",
+      "DO:",
+      "- If your context contains an opaque `[REQ:<token>]` marker, that's a reference to a past confirm-required request — call resolve_reference with that token to see what it was, don't guess at what it means.",
+      "- For a CLI's own syntax/flags, rely on --help first. Only check the wiki if --help doesn't cover something specific to how this team uses that tool (a convention, a naming pattern, a policy).",
+      "- When a command's --select flag description is generic/shared across multiple subcommands, don't take its inline example at face value — check that command's own \"Examples\" section at the bottom of its --help output for the syntax that actually works with it.",
+      "- For anything else — documentation, project status, how some tool or process is used, team conventions — consult the wiki FIRST (grep/read_file/list_files), before trying a CLI or answering from general knowledge.",
+      "- If the wiki doesn't have the answer, try a live CLI query if one is relevant, before giving up.",
+      "- If you still don't know after checking both, say so plainly — don't guess or invent an answer.",
+      "- If you learn something worth remembering (a useful command pattern, a correction from the user, a new convention), write_file to add it to curated/ — prefer creating a new, clearly-named file over guessing at how to merge into an existing one.",
+      "",
+      "DON'T:",
+      "- DON'T claim something is documented in the wiki without actually reading it via read_file/grep first.",
+      "- DON'T write_file over an existing curated document without reading it first — write_file replaces the whole file, it doesn't merge, so an unread overwrite silently destroys whatever was already there.",
+    ].join("\n"),
+  );
+  lines.push(
+    [
+      "You have access to the recall_tool_calls tool.",
+      "DO:",
+      "- If asked what you actually ran/queried/did earlier in this same conversation, call recall_tool_calls and quote it verbatim — you have no memory of your own past tool calls otherwise, only your own prior reply text, so reconstructing from memory instead of calling this tool risks getting it wrong.",
+    ].join("\n"),
+  );
+  lines.push(
+    [
+      "You have access to the recall_verbatim tool.",
+      "DO:",
+      "- If asked about something said in an EARLIER conversation — beyond what you can see in this one — call recall_verbatim to retrieve the actual past messages and quote them, don't reconstruct from memory. This searches a durable archive of what you and this person really said before.",
+      "- Use recall_tool_calls, not this, for what you ran in the CURRENT conversation; use recall_verbatim for what was said in past ones.",
+    ].join("\n"),
+  );
+
+  if (opts.multiUserChannel) {
+    // Interim, explicitly non-deterministic mitigation for Mercury replying
+    // to every message in a shared space — not a replacement for real
+    // @-mention detection, which the registered app's own identity now
+    // makes possible but which isn't implemented yet. See NO_REPLY in
+    // google-chat-provider.ts for the code side of this check.
+    lines.push(
+      [
+        "This conversation may be a shared space with more than one person, not a private one-on-one chat.",
+        "DO:",
+        "- Only give a substantive answer if this message is clearly directed at you (e.g. it explicitly mentions/addresses you) or is a direct continuation of an exchange you were already having with this same sender.",
+        `- If the message doesn't seem directed at you or isn't relevant to you, respond with exactly \`${NO_REPLY}\` and nothing else — no punctuation, no explanation, nothing before or after it.`,
+      ].join("\n"),
+    );
+  }
+
+  lines.push(personaSlot(opts.persona?.tone, DEFAULT_PERSONA_TONE));
+  return lines.join("\n");
+}
+
+/**
+ * Builds the instance's two system prompts from the same plugins and persona:
+ * `system` for 1:1 channels (the terminal, the HTTP surface) and `chatSystem`
+ * for shared spaces, the only one that carries the multi-user clause — an
+ * operator typing normally must never get a NO_REPLY meant for a shared space.
+ */
+export function buildSystemPrompts(opts: {
+  pluginFragments: string[];
+  skills: Skill[];
+  /** Required even when undefined, so a caller can't silently drop the instance's persona. */
+  persona: Persona | undefined;
+}): { system: string; chatSystem: string } {
+  return {
+    system: buildSystemPrompt({ ...opts, multiUserChannel: false }),
+    chatSystem: buildSystemPrompt({ ...opts, multiUserChannel: true }),
+  };
+}

package/src/session/tool-correction-extractor.ts

@@ -0,0 +1,133 @@
+/**
+ * Detects, within a single turn's steps, a CLI command call that failed
+ * followed later by one for the same binary that succeeded — a candidate
+ * procedural correction, distinct from `semantic-fact-extractor.ts` (which
+ * is about the user, from `session.messages`) — this is about a *tool*,
+ * from the tool-call trace (`StepInfo`), true for whoever uses that
+ * command next, not just this user. Pairing is deterministic (pure
+ * string/status matching); describing *what* the correction actually was
+ * is delegated to the model, same `generateObject`-with-fixed-schema style
+ * as `semantic-fact-extractor.ts`.
+ *
+ * Wired per-turn (`onStepFinish`, see `index.ts`), not from
+ * `idle-session-cron.ts`'s idle sweep: the tool-call trace for a turn only
+ * exists in memory for the duration of that turn (`tool-log-buffer.ts` is a
+ * 200-entry ring buffer shared across every session — not a reliable place
+ * to reconstruct one turn's trace minutes or hours later).
+ */
+import { generateObject, type LanguageModel } from "ai";
+import { z } from "zod";
+import type { StepInfo } from "./step-info.ts";
+
+export const ProceduralCorrectionCandidateSchema = z.object({ topic: z.string(), value: z.string() });
+export type ProceduralCorrection = { tool: string; topic: string; value: string };
+
+type GenerateObjectFn = (params: {
+  model: LanguageModel;
+  output: "array";
+  schema: typeof ProceduralCorrectionCandidateSchema;
+  instructions: string;
+  prompt: string;
+}) => Promise<{ object: z.infer<typeof ProceduralCorrectionCandidateSchema>[] }>;
+
+const SYSTEM_PROMPT =
+  "Ti viene mostrato un tentativo di comando fallito e uno, per lo stesso strumento, andato a buon " +
+  "fine più tardi nello stesso turno di conversazione. Descrivi la correzione appresa come una coppia " +
+  '{topic, value}: "topic" è una chiave breve e stabile per questa specifica correzione (es. ' +
+  '"select-prefix", "assignee-operator"), "value" è la regola pratica da ricordare, in una frase, utile ' +
+  "per chiunque userà questo comando in futuro — non solo per chi l'ha scoperta ora. Se il secondo " +
+  "tentativo non è davvero una correzione dell'errore del primo (es. l'utente ha semplicemente cambiato " +
+  "richiesta), restituisci un array vuoto.";
+
+/** Same normalization `semantic-fact-extractor.ts` used to apply to identity/preference topics — still needed here since this topic is free text, not a closed enum (procedural corrections are open-ended by nature). */
+function normalizeTopic(topic: string): string {
+  return topic
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-");
+}
+
+type Attempt = { command: string; binary: string; ok: boolean; error?: string };
+
+function extractAttempts(steps: StepInfo[]): Attempt[] {
+  const attempts: Attempt[] = [];
+  for (const stepInfo of steps) {
+    for (const call of stepInfo.toolCalls) {
+      // A CLI attempt is any tool call carrying a `command` string — the
+      // generic shape every CLI tool takes, whatever its name (jiraCommand,
+      // bitbucketCommand, the residual runCommand). Keying on a fixed tool name
+      // would silently miss plugin-owned CLI tools; keying on the input shape
+      // stays correct as new CLI plugins are added.
+      const input = call.input as { command?: unknown };
+      if (typeof input.command !== "string") continue;
+      // Group attempts by the binary they invoked, which is just the command's
+      // first whitespace-delimited token — no need to fully tokenize the argv
+      // (that belongs to whoever executes the command, not to procedural
+      // learning). An empty/whitespace-only command has no binary to group by.
+      const binary = input.command.trim().split(/\s+/)[0] ?? "";
+      if (binary === "") continue;
+
+      const result = stepInfo.toolResults.find((r) => r.toolCallId === call.toolCallId);
+      const output = result?.output as { ok?: unknown; error?: unknown } | undefined;
+      if (!output) continue; // no result to learn from (e.g. malformed-args tool-error, not a CLI failure)
+
+      attempts.push({
+        command: input.command,
+        binary,
+        ok: output.ok === true,
+        error: typeof output.error === "string" ? output.error : undefined,
+      });
+    }
+  }
+  return attempts;
+}
+
+/** Each failed attempt paired with the first later attempt for the same binary that succeeded — never the reverse, and never across different binaries. */
+function findCorrectionPairs(attempts: Attempt[]): Array<{ failed: Attempt; corrected: Attempt }> {
+  const pairs: Array<{ failed: Attempt; corrected: Attempt }> = [];
+  for (let i = 0; i < attempts.length; i++) {
+    const failed = attempts[i];
+    if (!failed || failed.ok) continue;
+    const corrected = attempts.slice(i + 1).find((a) => a.binary === failed.binary && a.ok);
+    if (corrected) {
+      pairs.push({ failed, corrected });
+    }
+  }
+  return pairs;
+}
+
+/** Returns a function that extracts candidate procedural corrections from a single turn's steps. */
+export function createToolCorrectionExtractor(
+  model: LanguageModel,
+  generateObjectFn: GenerateObjectFn = generateObject as unknown as GenerateObjectFn,
+  deps?: { log?: (msg: string) => void },
+): (steps: StepInfo[]) => Promise<ProceduralCorrection[]> {
+  const log = deps?.log ?? ((msg: string) => console.error(msg));
+
+  return async (steps) => {
+    const pairs = findCorrectionPairs(extractAttempts(steps));
+    const corrections: ProceduralCorrection[] = [];
+
+    for (const { failed, corrected } of pairs) {
+      try {
+        const { object } = await generateObjectFn({
+          model,
+          output: "array",
+          schema: ProceduralCorrectionCandidateSchema,
+          instructions: SYSTEM_PROMPT,
+          prompt:
+            `Comando fallito: ${failed.command}\n` +
+            `Errore: ${failed.error ?? "(nessun messaggio)"}\n` +
+            `Comando corretto (riuscito): ${corrected.command}`,
+        });
+        for (const candidate of object) {
+          corrections.push({ tool: failed.binary, topic: normalizeTopic(candidate.topic), value: candidate.value });
+        }
+      } catch (err) {
+        log(`procedural correction extraction failed for ${failed.binary}: ${String(err)}`);
+      }
+    }
+
+    return corrections;
+  };
+}