@exulu/backend 3.7.3 → 4.0.0

package/ee/agentic-retrieval/pipeline/memory.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { microCall } from "./micro-call";
+import { withTiming } from "./timing";
 import { singleSearch } from "./multi-query";
 import { fuzzyPrefilter } from "./prefilter";
 import { deriveKeywordVariants, normalizeFileName, stripSeparators } from "./text-utils";
@@ -45,18 +46,20 @@ async function loadMemoryItems(context: {
 // Keyword recall (ported from newton-memory.ts:91-169)
 // ---------------------------------------------------------------------------
 
-async function recallMemoryByKeywords({
+export async function recallMemoryByKeywords({
   keywords,
   importantKeyword,
   user,
   role,
   memoryContext,
+  timings,
 }: {
   keywords: string[];
   importantKeyword: string;
   user: any;
   role: any;
   memoryContext: { id: string; getItems: (o: any) => Promise<MemoryItem[]> };
+  timings?: Record<string, number>;
 }): Promise<Chunk[]> {
   const allKeywords = [
     ...new Set(
@@ -77,7 +80,7 @@ async function recallMemoryByKeywords({
   ].filter((v) => v.length >= 4);
   if (!allVariants.length) return [];
 
-  const items = await loadMemoryItems(memoryContext);
+  const items = await withTiming(timings, "memory.keywordRecall.itemsMs", () => loadMemoryItems(memoryContext));
 
   type Scored = { id: string; hits: number; importantHit: boolean; name: string };
   const scored: Scored[] = [];
@@ -104,14 +107,17 @@ async function recallMemoryByKeywords({
     topMatches.map((s) => `${s.name} (hits=${s.hits}, important=${s.importantHit})`),
   );
 
-  const chunks = await singleSearch({
+  // Full-text only: the items were already selected by keyword above, so this
+  // call just ranks their chunks. The hybrid method would add an embedding
+  // round trip (0.5-1.2 s, up to 5 s cold) on the memory phase's critical path.
+  const chunks = await withTiming(timings, "memory.keywordRecall.searchMs", () => singleSearch({
     query: allKeywords.join(", "),
-    config: { method: "hybridSearch", cutoffs: undefined, limit: 50 },
+    config: { method: "tsvector", cutoffs: undefined, limit: 50 },
     user,
     role,
     pinnedItemIds: topMatches.map((s) => s.id),
     context: memoryContext,
-  });
+  }));
 
   return chunks;
 }
@@ -137,11 +143,152 @@ function neutralResult(
   };
 }
 
+// ---------------------------------------------------------------------------
+// engine v2: one structured call for the whole memory phase
+// ---------------------------------------------------------------------------
+
+type MergedMemoryOutput = {
+  relevantChunkIds: string[];
+  override: { overrides: boolean; confidence: "high" | "medium" | "low"; authoritativeChunkIds: string[]; reason: string };
+  filePrioritization: { shouldPrioritizeFiles: boolean; fileNameHints?: string[] };
+  augmentation: { updatedUserQuestion: string; updatedRelevantKeywords: string[]; updatedImportantKeyword: string };
+};
+
+/**
+ * The v1 flow spends two sequential LLM hops on memory (relevance, then override +
+ * file prioritization + augmentation in parallel), ~3 s on the phase-1 critical path.
+ * The merged call answers all four questions from the same chunk list at once. The
+ * instructions are the v1 prompts, so each judgement keeps its rules; disabled features
+ * are still asked for (a stable schema) but their answers are ignored by mergedFollowups.
+ */
+async function runMergedMemoryCall({
+  model,
+  retrievedMemory,
+  question,
+  keywords,
+  importantKeyword,
+  memoryConfig,
+  glossary,
+}: {
+  model: any;
+  retrievedMemory: Chunk[];
+  question: string;
+  keywords: string[];
+  importantKeyword: string;
+  memoryConfig: { override: boolean; filePrioritization: boolean; queryAugmentation: boolean };
+  glossary: { term: string; meaning: string }[];
+}): Promise<MergedMemoryOutput> {
+  const glossaryText =
+    glossary.length > 0
+      ? `\nThe organization's documents use the following abbreviations/terms:\n${glossary.map((g) => `${g.term} : ${g.meaning}`).join("\n")}`
+      : "";
+  const system = `
+    You review the shared company memory for the user's question and answer FOUR questions in one go.
+
+    1. RELEVANCE (relevantChunkIds): return the chunk_ids of chunks containing information relevant to the
+    question, or an empty array. Be generous: include chunks that are topically related, share key
+    terminology, describe the same symptom from a different angle, or could plausibly help diagnose the
+    issue — even if they don't answer the question directly. Memory entries are deliberately broad,
+    hand-curated hints written by domain experts; the user's wording will rarely match the memory verbatim.
+    When in doubt, include the chunk.
+
+    2. OVERRIDE (override): decide whether ONE of the relevant chunks should become the AUTHORITATIVE basis
+    of the answer, taking precedence over the official documentation even if the documents state something
+    different. This is a deliberately STRICT check. Set overrides=true ONLY if a single chunk, on its own,
+    contains a DIRECT and SUFFICIENT answer to exactly what the user asked. Being topically related, sharing
+    terminology, describing the same component, or only partially addressing the question is NOT sufficient:
+    then set overrides=false. When in doubt, set overrides=false. Memory entries may capture field experience
+    that the manuals get wrong, so a confident, direct match is meant to win over the documents.
+    ${memoryConfig.override ? "" : "(Override is disabled for this agent: return overrides=false.)"}
+
+    3. FILE PRIORITIZATION (filePrioritization): set shouldPrioritizeFiles=true only if a relevant memory
+    entry explicitly says to look in, prioritize, prefer, or always search a particular document, file, or
+    file family (for example "When asked about X, always search in Y-Dateien first"). General background
+    facts, glossaries, or synonyms are NOT a file prioritization instruction. When true, return
+    fileNameHints exactly as referenced in the memory, bare names without folder paths.
+    ${memoryConfig.filePrioritization ? "" : "(File prioritization is disabled for this agent: return false.)"}
+
+    4. QUERY AUGMENTATION (augmentation): if, and only if, the relevant memory (or the glossary below)
+    contains synonyms or similar terms for what the user asked, return the user question and keywords
+    updated to include those synonyms — always keeping the original wording as well. Otherwise return the
+    original question, keywords and important keyword unchanged.
+    ${memoryConfig.queryAugmentation ? "" : "(Query augmentation is disabled for this agent: return the originals.)"}
+
+    <memory_chunks>
+    ${retrievedMemory.map((chunk) => `- ${chunk.chunk_id}: ${chunk.item_name} - ${chunk.chunk_content}`).join("\n")}
+    </memory_chunks>
+    ${glossaryText}
+  `;
+  const { output } = await microCall({
+    model,
+    system,
+    messages: [
+      {
+        role: "user",
+        content: `
+        <user_question>${question}</user_question>
+        <relevant_keywords>${keywords.join(", ")}</relevant_keywords>
+        <important_keyword>${importantKeyword}</important_keyword>
+        `,
+      },
+    ],
+    schema: z.object({
+      relevantChunkIds: z
+        .array(z.string())
+        .describe("chunk_ids (UUIDs at the start of each bullet) of relevant chunks; empty array if none."),
+      override: z.object({
+        overrides: z.boolean().describe("True ONLY if a chunk directly and sufficiently answers the question."),
+        confidence: z.enum(["high", "medium", "low"]),
+        authoritativeChunkIds: z.array(z.string()).describe("chunk_ids that directly answer the question; empty if overrides is false."),
+        reason: z.string().describe("One short sentence."),
+      }),
+      filePrioritization: z.object({
+        shouldPrioritizeFiles: z.boolean(),
+        fileNameHints: z.array(z.string()).optional(),
+      }),
+      augmentation: z.object({
+        updatedUserQuestion: z.string(),
+        updatedRelevantKeywords: z.array(z.string()),
+        updatedImportantKeyword: z.string(),
+      }),
+    }),
+  });
+  return output;
+}
+
+/** Shape the merged answer like the three v1 follow-up results, honouring the feature toggles. */
+function mergedFollowups(
+  merged: MergedMemoryOutput,
+  memoryConfig: { override: boolean; filePrioritization: boolean; queryAugmentation: boolean },
+  hasAugmentationContent: boolean,
+  question: string,
+  importantKeyword: string,
+) {
+  const overrideResult = {
+    output: memoryConfig.override
+      ? merged.override
+      : { overrides: false, confidence: "low" as const, authoritativeChunkIds: [] as string[], reason: "" },
+  };
+  const fileResult = {
+    output: memoryConfig.filePrioritization
+      ? merged.filePrioritization
+      : { shouldPrioritizeFiles: false, fileNameHints: [] as string[] },
+  };
+  const queryResult = {
+    output:
+      memoryConfig.queryAugmentation && hasAugmentationContent
+        ? merged.augmentation
+        : { updatedUserQuestion: question, updatedRelevantKeywords: [] as string[], updatedImportantKeyword: importantKeyword },
+  };
+  return [overrideResult, fileResult, queryResult] as const;
+}
+
 // ---------------------------------------------------------------------------
 // Main export
 // ---------------------------------------------------------------------------
 
 export async function runMemoryPhase({
+  timings,
   memoryChunks,
   memoryContext,
   question,
@@ -153,6 +300,7 @@ export async function runMemoryPhase({
   memoryConfig,
   glossary,
   documentContexts,
+  mergedCall = false,
 }: {
   memoryChunks: Chunk[];
   memoryContext?: any;
@@ -170,6 +318,9 @@ export async function runMemoryPhase({
   };
   glossary: { term: string; meaning: string }[];
   documentContexts: any[];
+  timings?: Record<string, number>;
+  /** engine v2: answer relevance, override, file prioritization and augmentation in ONE call. */
+  mergedCall?: boolean;
 }): Promise<MemoryPhaseResult> {
   try {
     // Short-circuit: disabled, or nothing to work with
@@ -183,13 +334,14 @@ export async function runMemoryPhase({
     // Keyword recall: extend memory with items that match the user's keywords
     if (memoryContext) {
       try {
-        const keywordMatched = await recallMemoryByKeywords({
+        const keywordMatched = await withTiming(timings, "memory.keywordRecallMs", () => recallMemoryByKeywords({
           keywords,
           importantKeyword,
           user,
           role,
           memoryContext,
-        });
+          timings,
+        }));
         if (keywordMatched.length > 0) {
           const seen = new Set(retrieved_memory.map((c) => c.chunk_id));
           const additions = keywordMatched.filter((c) => !seen.has(c.chunk_id));
@@ -217,8 +369,24 @@ export async function runMemoryPhase({
     `;
 
     let relevantMemoryChunks: Chunk[] = [];
+    let mergedOutput: MergedMemoryOutput | undefined;
     try {
-      const { output: output_relevant_memory } = await microCall({
+      if (mergedCall) {
+        mergedOutput = await withTiming(timings, "memory.mergedMs", () =>
+          runMergedMemoryCall({
+            model,
+            retrievedMemory: retrieved_memory,
+            question,
+            keywords,
+            importantKeyword,
+            memoryConfig,
+            glossary,
+          }),
+        );
+      }
+      const { output: output_relevant_memory } = mergedOutput
+        ? { output: { relevantChunkIds: mergedOutput.relevantChunkIds } }
+        : await withTiming(timings, "memory.relevanceMs", () => microCall({
         model,
         system: CHECK_MEMORIES_FOR_RELEVANT_INFORMATION,
         messages: [
@@ -238,7 +406,7 @@ export async function runMemoryPhase({
               "The chunk_ids (UUIDs at the start of each bullet) of chunks containing information relevant to the user's question. Empty array if none are relevant.",
             ),
         }),
-      });
+      }));
 
       const ids = new Set(output_relevant_memory?.relevantChunkIds ?? []);
       relevantMemoryChunks =
@@ -348,7 +516,9 @@ export async function runMemoryPhase({
       Otherwise, return the original user question, relevant keywords and important keyword.
       `;
 
-      const [overrideResult, fileResult, queryResult] = await Promise.all([
+      const [overrideResult, fileResult, queryResult] = mergedOutput
+        ? mergedFollowups(mergedOutput, memoryConfig, hasAugmentationContent, question, importantKeyword)
+        : await withTiming(timings, "memory.followupsMs", () => Promise.all([
         // Override check: strict gate to decide if memory should be authoritative
         memoryConfig.override
           ? microCall({
@@ -447,7 +617,7 @@ export async function runMemoryPhase({
                 updatedImportantKeyword: importantKeyword,
               },
             }),
-      ]);
+      ]));
 
       // Override gate (STRICT: only active when overrides===true && confidence==="high" && authoritativeChunks.length > 0)
       const overrideIds = new Set(overrideResult.output?.authoritativeChunkIds ?? []);

package/ee/agentic-retrieval/pipeline/pin-rerun.test.ts

@@ -0,0 +1,17 @@
+import { needsPinRerun } from "./pin-rerun";
+
+describe("needsPinRerun — whether memory's rewrite of the question can change the identifier pins", () => {
+  it("is false when the question is unchanged", () => {
+    expect(needsPinRerun("Fehler 0x02 am CBM-2", "Fehler 0x02 am CBM-2")).toBe(false);
+  });
+  it("is false when the rewrite only adds plain words or synonyms: pins depend on designations, not prose", () => {
+    expect(needsPinRerun("Wie quittiere ich die ECO Steuerung?", "Wie quittiere ich die ECO Steuerung (Hydraulik, Quittierung, bestätigen)?")).toBe(false);
+  });
+  it("is true when the rewrite introduces a new designation such as a model or error code", () => {
+    expect(needsPinRerun("Wie quittiere ich die ECO Steuerung?", "Wie quittiere ich die ECO Steuerung (FST-2XT)?")).toBe(true);
+    expect(needsPinRerun("Fehler am Bremsmodul", "Fehler 0x02 am Bremsmodul")).toBe(true);
+  });
+  it("ignores case and punctuation around designations", () => {
+    expect(needsPinRerun("cbm-2 Fehler", "CBM-2, Fehler, Bremsmodul")).toBe(false);
+  });
+});

package/ee/agentic-retrieval/pipeline/pin-rerun.ts

@@ -0,0 +1,29 @@
+/**
+ * engine v2 runs identifier pins in parallel with the memory phase, on the original
+ * question. Memory augmentation then usually rewrites the question (synonyms from the
+ * glossary/memory), and re-running the pins for every rewrite put ~1 s back on the
+ * critical path in most turns (eval 2026-09-12: pinsMs median 1.0 s). Pins come from
+ * designations (model names, error codes, part numbers), so only a rewrite that adds a
+ * new designation-like token can change them.
+ */
+export function needsPinRerun(originalQuestion: string, updatedQuestion: string): boolean {
+  if (originalQuestion === updatedQuestion) return false;
+  const before = designations(originalQuestion);
+  for (const token of designations(updatedQuestion)) {
+    if (!before.has(token)) return true;
+  }
+  return false;
+}
+
+/** Tokens that look like designations: they carry a digit or at least two capitals (FST-2XT, 0x02, CBM). */
+function designations(text: string): Set<string> {
+  const out = new Set<string>();
+  for (const raw of text.split(/[\s,;:()\[\]"'?!]+/)) {
+    const token = raw.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+    if (!token) continue;
+    const hasDigit = /\p{N}/u.test(token);
+    const capitals = (token.match(/\p{Lu}/gu) ?? []).length;
+    if (hasDigit || capitals >= 2) out.add(token.toLowerCase());
+  }
+  return out;
+}

package/ee/agentic-retrieval/pipeline/routing.test.ts

@@ -185,3 +185,37 @@ describe("runRoutingPhase", () => {
     expect(r.mainContexts).toEqual(["docs", "tickets"]);
   });
 });
+
+describe("runRoutingPhase with mergedCall (engine v2)", () => {
+  const rules = [{ id: "t", label: "T", description: "d", main: ["docs"], fallback: ["tickets"] }];
+  const mergedOut = (over: Partial<any> = {}) => ({ output: {
+    docPage: { hasFilenameHint: false, filenameHints: [], hasPageHint: false, pageNumber: null },
+    explicitlyRequestedKnowledgeBases: [],
+    classification: { ruleId: "t", reason: "because" },
+    ...over,
+  } });
+
+  it("asks the model once and applies the classification", async () => {
+    (generateText as jest.Mock).mockResolvedValueOnce(mergedOut());
+    const r = await runRoutingPhase({ question: "how do I fix the door?", enabledContexts: enabled, documentContexts: [],
+      routingRules: rules, preselectedItems: new Map(), model: {}, mergedCall: true });
+    expect(generateText).toHaveBeenCalledTimes(1);
+    expect(r.mainContexts).toEqual(["docs"]);
+    expect(r.fallbackContexts).toEqual(["tickets"]);
+  });
+
+  it("lets an explicit knowledge-base request win over the classification, with no fallback", async () => {
+    (generateText as jest.Mock).mockResolvedValueOnce(mergedOut({ explicitlyRequestedKnowledgeBases: ["tickets"] }));
+    const r = await runRoutingPhase({ question: "search tickets for X", enabledContexts: enabled, documentContexts: [],
+      routingRules: rules, preselectedItems: new Map(), model: {}, mergedCall: true });
+    expect(r.mainContexts).toEqual(["tickets"]);
+    expect(r.fallbackContexts).toEqual([]);
+  });
+
+  it("still reports a requested page from the merged answer", async () => {
+    (generateText as jest.Mock).mockResolvedValueOnce(mergedOut({ docPage: { hasFilenameHint: false, filenameHints: [], hasPageHint: true, pageNumber: 38 } }));
+    const r = await runRoutingPhase({ question: "page 38", enabledContexts: enabled, documentContexts: [],
+      routingRules: rules, preselectedItems: new Map(), model: {}, mergedCall: true });
+    expect(r.userRequestedPage).toBe(38);
+  });
+});

package/ee/agentic-retrieval/pipeline/routing.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { microCall } from "./micro-call";
+import { withTiming } from "./timing";
 import { fuzzyPrefilter } from "./prefilter";
 import { normalizeFileName } from "./text-utils";
 import type { RoutingRule } from "./config";
@@ -39,6 +40,69 @@ Return hasFilenameHint/hasPageHint false (and omit the hint fields) when neither
 is present. When in doubt, return false.
 `;
 
+type MergedRoutingOutput = {
+  docPage: { hasFilenameHint: boolean; filenameHints?: string[]; hasPageHint: boolean; pageNumber?: number | null };
+  explicitlyRequestedKnowledgeBases: string[];
+  classification?: { ruleId: string; reason: string } | null;
+};
+
+/**
+ * engine v2: the three routing judgements (document/page reference, explicit knowledge-base
+ * request, rule classification) in one structured call instead of two sequential hops.
+ * The instructions are the v1 prompts joined together so each judgement keeps its rules.
+ */
+async function runMergedRoutingCall({
+  model,
+  question,
+  knownIdentifiers,
+  enabledContexts,
+  routingRules,
+  extraInstructions,
+}: {
+  model: any;
+  question: string;
+  knownIdentifiers: string[];
+  enabledContexts: Array<{ id: string; name: string; description?: string }>;
+  routingRules: RoutingRule[];
+  extraInstructions?: string;
+}): Promise<MergedRoutingOutput> {
+  const kbListing = enabledContexts
+    .map((c) => `- ${c.id}: ${c.name}${c.description ? " — " + c.description : ""}`)
+    .join("\n");
+  const rulesLines = routingRules.map((r) => `- ${r.id} (${r.label}): ${r.description}`).join("\n");
+  const system =
+    `You analyse the user's request and answer ${routingRules.length ? "three" : "two"} questions in one go.\n\n` +
+    `A. DOCUMENT / PAGE REFERENCE (docPage):\n${buildDocPagePrompt(knownIdentifiers)}\n\n` +
+    `B. EXPLICIT KNOWLEDGE BASE REQUEST (explicitlyRequestedKnowledgeBases): check if the user has EXPLICITLY asked you to search in one or multiple of the following knowledge bases:\n${kbListing}\n` +
+    `EXPLICIT means the user names a knowledge base or clearly commands searching a specific source (e.g. "search in the tickets", "look this up in the manuals KB"). ` +
+    `A question that merely CONCERNS a topic related to a knowledge base's name or contents (e.g. asking about software changes, norms, or a product) is NOT an explicit request. ` +
+    `When in doubt, return an empty array. If explicit, return the knowledge base ids.\n` +
+    (routingRules.length
+      ? `\nC. CLASSIFICATION (classification): classify the request into exactly one of these categories:\n${rulesLines}` +
+        (extraInstructions ? `\n<instructions>\n${extraInstructions}\n</instructions>` : "")
+      : "");
+  const ids = enabledContexts.map((c) => c.id) as [string, ...string[]];
+  const schema = z.object({
+    docPage: z.object({
+      hasFilenameHint: z.boolean(),
+      filenameHints: z.array(z.string()).optional(),
+      hasPageHint: z.boolean(),
+      pageNumber: z.number().int().nullable().optional(),
+    }),
+    explicitlyRequestedKnowledgeBases: z.array(z.enum(ids)),
+    ...(routingRules.length
+      ? {
+          classification: z.object({
+            ruleId: z.enum(routingRules.map((r) => r.id) as [string, ...string[]]),
+            reason: z.string(),
+          }),
+        }
+      : {}),
+  });
+  const { output } = await microCall({ model, system, messages: [{ role: "user", content: question }], schema });
+  return output as MergedRoutingOutput;
+}
+
 export async function runRoutingPhase(opts: {
   question: string;
   enabledContexts: Array<{ id: string; name: string; description?: string }>;
@@ -49,6 +113,9 @@ export async function runRoutingPhase(opts: {
   /** Example product/model designations from the configured identifier vocabularies —
    * injected into the doc-reference prompt so they are never mistaken for filenames. */
   knownIdentifiers?: string[];
+  timings?: Record<string, number>;
+  /** engine v2: doc/page detection, explicit-KB detection and classification in ONE call. */
+  mergedCall?: boolean;
   model: any;
 }): Promise<RoutingPhaseResult> {
   const {
@@ -59,6 +126,7 @@ export async function runRoutingPhase(opts: {
     preselectedItems,
     extraInstructions,
     knownIdentifiers = [],
+    mergedCall = false,
     model,
   } = opts;
 
@@ -97,9 +165,30 @@ export async function runRoutingPhase(opts: {
     ` an empty array.` +
     `\nIf explicit, return the knowledge base ids. If not, return an empty array.`;
 
-  // --- Phase 1: parallel doc/page detection + explicit-KB detection ---
+  // --- Phase 1: doc/page detection + explicit-KB detection (+ classification when merged) ---
 
-  const [docPageRaw, explicitKBRaw] = await Promise.all([
+  // Classification is only needed when rules decide the routing (no explicit KB, no preselection);
+  // the merged call asks for it in the same round trip and phase 3 uses it when applicable.
+  const wantsClassification = routingRules.length > 0 && preselectedItems.size === 0;
+  const merged = mergedCall
+    ? await withTiming(opts.timings, "routing.mergedMs", () =>
+        runMergedRoutingCall({
+          model,
+          question,
+          knownIdentifiers,
+          enabledContexts,
+          routingRules: wantsClassification ? routingRules : [],
+          extraInstructions,
+        }).catch((err) => {
+          console.warn("[EXULU pipeline] merged routing call failed — falling back to the v1 hops.", err);
+          return null;
+        }),
+      )
+    : null;
+
+  const [docPageRaw, explicitKBRaw] = merged
+    ? [{ output: merged.docPage }, { output: { explicitlyRequestedKnowledgeBases: merged.explicitlyRequestedKnowledgeBases } }]
+    : await withTiming(opts.timings, "routing.detectMs", () => Promise.all([
     (async () => {
       try {
         return await microCall({
@@ -141,7 +230,7 @@ export async function runRoutingPhase(opts: {
         return { output: { explicitlyRequestedKnowledgeBases: [] as string[] } };
       }
     })(),
-  ]);
+  ]));
 
   // --- Phase 2: resolve filename hints across all document contexts ---
 
@@ -250,7 +339,9 @@ export async function runRoutingPhase(opts: {
     }
 
     try {
-      const { output: classified } = await microCall({
+      const { output: classified } = merged?.classification
+        ? { output: merged.classification }
+        : await withTiming(opts.timings, "routing.classifyMs", () => microCall({
         model,
         system: classifyPrompt,
         messages: [{ role: "user", content: question }],
@@ -258,7 +349,7 @@ export async function runRoutingPhase(opts: {
           ruleId: z.enum(ruleIds as [string, ...string[]]),
           reason: z.string(),
         }),
-      });
+      }));
 
       const matchedRule = routingRules.find((r) => r.id === classified.ruleId);
       if (matchedRule) {

package/ee/agentic-retrieval/pipeline/search.ts

@@ -2,6 +2,7 @@ import { effectiveKbSettings, type KbProfile } from "./config";
 import { multiQuerySearch, singleSearch, type SearchCallConfig } from "./multi-query";
 import { generateHydePassage } from "./hyde";
 import { fuzzyPrefilter } from "./prefilter";
+import { withTiming } from "./timing";
 import { applyRewrites } from "./text-utils";
 import type { Chunk } from "./types";
 
@@ -30,6 +31,8 @@ export async function searchContexts(opts: {
   rewrites: { find: string; replace: string }[];
   styleHint: string;
   maxQueries: number;
+  timings?: Record<string, number>;                     // sub-phase sink (see timing.ts)
+  timingPrefix?: string;                                // e.g. "search.main" / "search.fallback"
   skipPrefilter: boolean;                               // true for the speculative fallback pass
 }): Promise<{ chunks: Chunk[] }> {
   const {
@@ -54,7 +57,7 @@ export async function searchContexts(opts: {
   } = opts;
 
   const chunkArrays = await Promise.all(
-    contextIds.map(async (ctxId): Promise<Chunk[]> => {
+    contextIds.map((ctxId): Promise<Chunk[]> => withTiming(opts.timings, `${opts.timingPrefix ?? "search"}.${ctxId}Ms`, async () => {
       try {
         // Rule 4: Missing context contributes []
         const ctx = contextsById.get(ctxId);
@@ -124,13 +127,13 @@ export async function searchContexts(opts: {
             // Generate HyDE passage when settings.hyde is true
             let hydePassage: string | null = null;
             if (hyde) {
-              hydePassage = await generateHydePassage({
+              hydePassage = await withTiming(opts.timings, `${opts.timingPrefix ?? "search"}.${ctxId}.hydeMs`, () => generateHydePassage({
                 originalQuestion: question,
                 relevantKeywords: keywords,
                 importantKeyword,
                 styleHint,
                 model,
-              });
+              }));
             }
 
             // HyDE placed right after the question so the cap never drops it
@@ -153,14 +156,14 @@ export async function searchContexts(opts: {
           // pass too), unlike the cross-context identifier/memory/user pins suppressed above.
           // keywordPrefilter and no pins yet → fuzzyPrefilter; results become the pins
           if (keywordPrefilter && pinnedItemIds.length === 0) {
-            const prefiltered = await fuzzyPrefilter({
+            const prefiltered = await withTiming(opts.timings, `${opts.timingPrefix ?? "search"}.${ctxId}.prefilterMs`, () => fuzzyPrefilter({
               cacheKey: `conversations:${ctxId}`,
               relevantKeywords: keywords,
               importantKeyword,
               context: ctx,
               fields: ["name", "id", "external_id", "description"],
               normalize: (i: any) => [i.name, i.description].filter(Boolean).join(": "),
-            });
+            }));
             pinnedItemIds = prefiltered.map((r) => r.id);
           }
 
@@ -184,7 +187,7 @@ export async function searchContexts(opts: {
         console.warn(`[EXULU pipeline] searchContexts failed for context "${ctxId}":`, err);
         return [];
       }
-    }),
+    })),
   );
 
   return { chunks: chunkArrays.flat() };

package/ee/agentic-retrieval/pipeline/timing.test.ts

@@ -0,0 +1,24 @@
+import { withTiming } from "./timing";
+
+describe("withTiming — records how long a pipeline sub-phase took", () => {
+  it("stores the elapsed milliseconds under the key and returns the awaited value", async () => {
+    const timings: Record<string, number> = {};
+    let now = 1000;
+    const clock = () => now;
+    const value = await withTiming(timings, "memory.relevanceMs", async () => { now += 250; return "ok"; }, clock);
+    expect(value).toBe("ok");
+    expect(timings["memory.relevanceMs"]).toBe(250);
+  });
+
+  it("still records the time when the sub-phase throws, then rethrows", async () => {
+    const timings: Record<string, number> = {};
+    let now = 0;
+    const clock = () => now;
+    await expect(withTiming(timings, "routing.classifyMs", async () => { now += 40; throw new Error("boom"); }, clock)).rejects.toThrow("boom");
+    expect(timings["routing.classifyMs"]).toBe(40);
+  });
+
+  it("is a no-op passthrough when no timings sink is given", async () => {
+    await expect(withTiming(undefined, "x", async () => 7)).resolves.toBe(7);
+  });
+});

package/ee/agentic-retrieval/pipeline/timing.ts

@@ -0,0 +1,26 @@
+/**
+ * Sub-phase timing for the agentic retrieval pipeline.
+ *
+ * The pipeline reports phase durations ("memoryRoutingMs", "searchMs", …) in
+ * its result so slow retrievals can be diagnosed from the chat transcript
+ * alone. withTiming adds the next level down (an LLM hop inside the memory
+ * phase, one knowledge base inside the search fan-out) without threading
+ * clocks through every function: pass the shared sink and a key, get the
+ * awaited value back. Elapsed time is recorded even when the work throws.
+ */
+export type TimingSink = Record<string, number>;
+
+export async function withTiming<T>(
+  sink: TimingSink | undefined,
+  key: string,
+  work: () => Promise<T>,
+  now: () => number = Date.now,
+): Promise<T> {
+  if (!sink) return work();
+  const started = now();
+  try {
+    return await work();
+  } finally {
+    sink[key] = Math.max(0, now() - started);
+  }
+}

package/ee/agentic-retrieval/pipeline/types.ts

@@ -51,6 +51,8 @@ export type RetrievalStep = {
   tokens: number;
 };
 export type AgenticRetrievalOutput = {
+  /** Phase durations in ms (memoryRoutingMs, pinsMs, searchMs, rerankMs, fallbackRerankMs, totalMs). */
+  timings?: Record<string, number>;
   steps: RetrievalStep[];
   reasoning: { text: string; tools: unknown[] }[];
   chunks: ChunkWithScore[];