@exulu/backend 3.7.3 → 4.0.0

package/dist/{chunk-BNTL6LYY.js → chunk-RBEWHG7I.js}

@@ -1716,7 +1716,7 @@ var ExuluTool = class _ExuluTool {
     if (!agent) {
       throw new Error("Agent not found.");
     }
-    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-UQSLJDXE.js");
+    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-6RU4IZMI.js");
     const tools = await convertExuluToolsToAiSdkTools2(
       [this],
       [],
@@ -2068,7 +2068,19 @@ var tuningSchema = z3.object({
   pinBoost: z3.number().min(0).max(1).default(0.15),
   identifierBoost: z3.number().min(0).max(1).default(0.15),
   pageWindow: z3.number().int().min(0).default(1),
-  maxQueriesPerContext: z3.number().int().positive().default(5)
+  maxQueriesPerContext: z3.number().int().positive().default(5),
+  /**
+   * Orchestration engine. "v1" is the sequential flow every agent ran before 2026-09;
+   * "v2" merges the phase-1 LLM hops and runs identifier pins in parallel. Per agent,
+   * so a candidate agent can run v2 while the production agent stays on v1.
+   */
+  engine: z3.enum(["v1", "v2"]).default("v1"),
+  /** v2 sub-features; each can be switched off on its own to bisect a regression. */
+  v2: z3.object({
+    mergedMemoryCall: z3.boolean().default(true),
+    mergedRoutingCall: z3.boolean().default(true),
+    parallelPins: z3.boolean().default(true)
+  }).default({ mergedMemoryCall: true, mergedRoutingCall: true, parallelPins: true })
 });
 var boolVal = (v) => v === true || v === "true" || v === 1;
 var strVal = (v, fallback) => typeof v === "string" && v.length > 0 ? v : fallback;
@@ -2291,6 +2303,17 @@ async function microCall(args) {
   );
 }
 
+// ee/agentic-retrieval/pipeline/timing.ts
+async function withTiming(sink, key, work, now = Date.now) {
+  if (!sink) return work();
+  const started = now();
+  try {
+    return await work();
+  } finally {
+    sink[key] = Math.max(0, now() - started);
+  }
+}
+
 // ee/agentic-retrieval/pipeline/prefilter.ts
 import Fuse from "fuse.js";
 import { z as z4 } from "zod";
@@ -2606,6 +2629,49 @@ Only set pageNumber when the user names a specific page.
 Return hasFilenameHint/hasPageHint false (and omit the hint fields) when neither
 is present. When in doubt, return false.
 `;
+async function runMergedRoutingCall({
+  model,
+  question,
+  knownIdentifiers,
+  enabledContexts,
+  routingRules,
+  extraInstructions
+}) {
+  const kbListing = enabledContexts.map((c) => `- ${c.id}: ${c.name}${c.description ? " \u2014 " + 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.
+
+A. DOCUMENT / PAGE REFERENCE (docPage):
+${buildDocPagePrompt(knownIdentifiers)}
+
+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:
+${kbListing}
+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.
+` + (routingRules.length ? `
+C. CLASSIFICATION (classification): classify the request into exactly one of these categories:
+${rulesLines}` + (extraInstructions ? `
+<instructions>
+${extraInstructions}
+</instructions>` : "") : "");
+  const ids = enabledContexts.map((c) => c.id);
+  const schema = z5.object({
+    docPage: z5.object({
+      hasFilenameHint: z5.boolean(),
+      filenameHints: z5.array(z5.string()).optional(),
+      hasPageHint: z5.boolean(),
+      pageNumber: z5.number().int().nullable().optional()
+    }),
+    explicitlyRequestedKnowledgeBases: z5.array(z5.enum(ids)),
+    ...routingRules.length ? {
+      classification: z5.object({
+        ruleId: z5.enum(routingRules.map((r) => r.id)),
+        reason: z5.string()
+      })
+    } : {}
+  });
+  const { output } = await microCall({ model, system, messages: [{ role: "user", content: question }], schema });
+  return output;
+}
 async function runRoutingPhase(opts) {
   const {
     question,
@@ -2615,6 +2681,7 @@ async function runRoutingPhase(opts) {
     preselectedItems,
     extraInstructions,
     knownIdentifiers = [],
+    mergedCall = false,
     model
   } = opts;
   try {
@@ -2634,7 +2701,23 @@ async function runRoutingPhase(opts) {
 ` + enabledContexts.map((c) => `- ${c.id}: ${c.name}${c.description ? " \u2014 " + c.description : ""}`).join("\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 \u2014 classification routing handles those. When in doubt, return an empty array.
 If explicit, return the knowledge base ids. If not, return an empty array.`;
-    const [docPageRaw, explicitKBRaw] = await Promise.all([
+    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 \u2014 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({
@@ -2676,7 +2759,7 @@ If explicit, return the knowledge base ids. If not, return an empty array.`;
           return { output: { explicitlyRequestedKnowledgeBases: [] } };
         }
       })()
-    ]);
+    ]));
     const userPinnedItemIdsByContext = /* @__PURE__ */ new Map();
     let userRequestedPage = null;
     if (docPageRaw.output.hasFilenameHint && docPageRaw.output.filenameHints?.length) {
@@ -2754,7 +2837,7 @@ ${extraInstructions}
 </instructions>`;
       }
       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 }],
@@ -2762,7 +2845,7 @@ ${extraInstructions}
             ruleId: z5.enum(ruleIds),
             reason: z5.string()
           })
-        });
+        }));
         const matchedRule = routingRules.find((r) => r.id === classified.ruleId);
         if (matchedRule) {
           const main = matchedRule.main.filter((id) => enabledIds.has(id));
@@ -2929,7 +3012,8 @@ async function recallMemoryByKeywords({
   importantKeyword,
   user,
   role,
-  memoryContext
+  memoryContext,
+  timings
 }) {
   const allKeywords = [
     ...new Set(
@@ -2946,7 +3030,7 @@ async function recallMemoryByKeywords({
     ...new Set(allKeywords.flatMap(deriveKeywordVariants).map(stripSeparators))
   ].filter((v) => v.length >= 4);
   if (!allVariants.length) return [];
-  const items = await loadMemoryItems(memoryContext);
+  const items = await withTiming(timings, "memory.keywordRecall.itemsMs", () => loadMemoryItems(memoryContext));
   const scored = [];
   for (const item of items) {
     const haystack = stripSeparators(
@@ -2968,14 +3052,14 @@ async function recallMemoryByKeywords({
     "[EXULU pipeline] keyword-triggered memory matches:",
     topMatches.map((s) => `${s.name} (hits=${s.hits}, important=${s.importantHit})`)
   );
-  const chunks = await singleSearch({
+  const chunks = await withTiming(timings, "memory.keywordRecall.searchMs", () => singleSearch({
     query: allKeywords.join(", "),
-    config: { method: "hybridSearch", cutoffs: void 0, limit: 50 },
+    config: { method: "tsvector", cutoffs: void 0, limit: 50 },
     user,
     role,
     pinnedItemIds: topMatches.map((s) => s.id),
     context: memoryContext
-  });
+  }));
   return chunks;
 }
 function neutralResult(question, keywords, importantKeyword, steps = []) {
@@ -2989,7 +3073,103 @@ function neutralResult(question, keywords, importantKeyword, steps = []) {
     steps
   };
 }
+async function runMergedMemoryCall({
+  model,
+  retrievedMemory,
+  question,
+  keywords,
+  importantKeyword,
+  memoryConfig,
+  glossary
+}) {
+  const glossaryText = glossary.length > 0 ? `
+The organization's documents use the following abbreviations/terms:
+${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 \u2014 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 \u2014 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: z6.object({
+      relevantChunkIds: z6.array(z6.string()).describe("chunk_ids (UUIDs at the start of each bullet) of relevant chunks; empty array if none."),
+      override: z6.object({
+        overrides: z6.boolean().describe("True ONLY if a chunk directly and sufficiently answers the question."),
+        confidence: z6.enum(["high", "medium", "low"]),
+        authoritativeChunkIds: z6.array(z6.string()).describe("chunk_ids that directly answer the question; empty if overrides is false."),
+        reason: z6.string().describe("One short sentence.")
+      }),
+      filePrioritization: z6.object({
+        shouldPrioritizeFiles: z6.boolean(),
+        fileNameHints: z6.array(z6.string()).optional()
+      }),
+      augmentation: z6.object({
+        updatedUserQuestion: z6.string(),
+        updatedRelevantKeywords: z6.array(z6.string()),
+        updatedImportantKeyword: z6.string()
+      })
+    })
+  });
+  return output;
+}
+function mergedFollowups(merged, memoryConfig, hasAugmentationContent, question, importantKeyword) {
+  const overrideResult = {
+    output: memoryConfig.override ? merged.override : { overrides: false, confidence: "low", authoritativeChunkIds: [], reason: "" }
+  };
+  const fileResult = {
+    output: memoryConfig.filePrioritization ? merged.filePrioritization : { shouldPrioritizeFiles: false, fileNameHints: [] }
+  };
+  const queryResult = {
+    output: memoryConfig.queryAugmentation && hasAugmentationContent ? merged.augmentation : { updatedUserQuestion: question, updatedRelevantKeywords: [], updatedImportantKeyword: importantKeyword }
+  };
+  return [overrideResult, fileResult, queryResult];
+}
 async function runMemoryPhase({
+  timings,
   memoryChunks,
   memoryContext,
   question,
@@ -3000,7 +3180,8 @@ async function runMemoryPhase({
   model,
   memoryConfig,
   glossary,
-  documentContexts
+  documentContexts,
+  mergedCall = false
 }) {
   try {
     if (!memoryConfig.enabled || memoryChunks.length === 0 && !memoryContext) {
@@ -3010,13 +3191,14 @@ async function runMemoryPhase({
     let retrieved_memory = [...memoryChunks];
     if (memoryContext) {
       try {
-        const keywordMatched = await recallMemoryByKeywords({
+        const keywordMatched = await withTiming(timings, "memory.keywordRecallMs", () => recallMemoryByKeywords({
           keywords,
           importantKeyword,
           user,
           role,
-          memoryContext
-        });
+          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));
@@ -3041,8 +3223,24 @@ async function runMemoryPhase({
     </memory_chunks>
     `;
     let relevantMemoryChunks = [];
+    let mergedOutput;
     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: [
@@ -3060,7 +3258,7 @@ 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 = ids.size === 0 ? [] : retrieved_memory.filter((c) => ids.has(c.chunk_id));
     } catch (e) {
@@ -3150,7 +3348,7 @@ ${glossary.map((g) => `${g.term} : ${g.meaning}`).join("\n")}` : "";
 
       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({
           model,
@@ -3231,7 +3429,7 @@ ${glossary.map((g) => `${g.term} : ${g.meaning}`).join("\n")}` : "";
             updatedImportantKeyword: importantKeyword
           }
         })
-      ]);
+      ]));
       const overrideIds = new Set(overrideResult.output?.authoritativeChunkIds ?? []);
       const authoritativeChunks = memoryChunksForAnswer.filter(
         (c) => c.chunk_id && overrideIds.has(c.chunk_id)
@@ -3407,7 +3605,7 @@ async function searchContexts(opts) {
     skipPrefilter
   } = opts;
   const chunkArrays = await Promise.all(
-    contextIds.map(async (ctxId) => {
+    contextIds.map((ctxId) => withTiming(opts.timings, `${opts.timingPrefix ?? "search"}.${ctxId}Ms`, async () => {
       try {
         const ctx = contextsById.get(ctxId);
         if (!ctx) return [];
@@ -3445,13 +3643,13 @@ async function searchContexts(opts) {
           if (multiQuery) {
             let hydePassage = null;
             if (hyde) {
-              hydePassage = await generateHydePassage({
+              hydePassage = await withTiming(opts.timings, `${opts.timingPrefix ?? "search"}.${ctxId}.hydeMs`, () => generateHydePassage({
                 originalQuestion: question,
                 relevantKeywords: keywords,
                 importantKeyword,
                 styleHint,
                 model
-              });
+              }));
             }
             const candidates = [
               question,
@@ -3466,14 +3664,14 @@ async function searchContexts(opts) {
         }
         if (kind === "conversations") {
           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) => [i.name, i.description].filter(Boolean).join(": ")
-            });
+            }));
             pinnedItemIds = prefiltered.map((r) => r.id);
           }
           const keywordQuery = keywords.length ? keywords.join(" ") + " " + importantKeyword : question;
@@ -3488,7 +3686,7 @@ async function searchContexts(opts) {
         console.warn(`[EXULU pipeline] searchContexts failed for context "${ctxId}":`, err);
         return [];
       }
-    })
+    }))
   );
   return { chunks: chunkArrays.flat() };
 }
@@ -3633,6 +3831,27 @@ async function rerankResults(opts) {
   return { limited_results, sorted_reranked_results: sorted, rerank_score_max_genuine };
 }
 
+// ee/agentic-retrieval/pipeline/pin-rerun.ts
+function needsPinRerun(originalQuestion, updatedQuestion) {
+  if (originalQuestion === updatedQuestion) return false;
+  const before = designations(originalQuestion);
+  for (const token of designations(updatedQuestion)) {
+    if (!before.has(token)) return true;
+  }
+  return false;
+}
+function designations(text) {
+  const out = /* @__PURE__ */ new Set();
+  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;
+}
+
 // ee/agentic-retrieval/pipeline/index.ts
 function addChunks(result, chunks) {
   const seen = new Set(result.chunks.map((c) => c.chunk_id));
@@ -3798,6 +4017,14 @@ function createAgenticRetrievalTool(opts) {
         usage: [],
         totalTokens: 0
       };
+      const t0 = Date.now();
+      const timings = {};
+      let tPhase = t0;
+      const lap = (name) => {
+        const now = Date.now();
+        timings[name] = (timings[name] ?? 0) + (now - tPhase);
+        tPhase = now;
+      };
       try {
         let enabledContexts = contexts.filter(
           (ctx) => cfg.knowledgeBases[ctx.id]?.enabled !== false
@@ -3870,8 +4097,19 @@ function createAgenticRetrievalTool(opts) {
           resolvedProject && projectScope?.customInstructions ? `Instructions for the attached project "${projectScope.name}":
 ${projectScope.customInstructions}` : ""
         ].filter(Boolean).join("\n");
-        const [memResult, routResult] = await Promise.all([
-          runMemoryPhase({
+        const engineV2 = cfg.tuning.engine === "v2";
+        const v2 = cfg.tuning.v2;
+        const pinsFor = (question) => resolveIdentifierPins({
+          question,
+          identifierSets: cfg.vocabulary.identifiers,
+          contextsById,
+          kbKindById,
+          model: utilityModel
+        });
+        const [memResult, routResult, parallelPins] = await Promise.all([
+          withTiming(timings, "memoryMs", () => runMemoryPhase({
+            timings,
+            mergedCall: engineV2 && v2.mergedMemoryCall,
             memoryChunks: memoryItems ?? [],
             memoryContext,
             question: userQuery,
@@ -3883,8 +4121,10 @@ ${projectScope.customInstructions}` : ""
             memoryConfig: cfg.memory,
             glossary: cfg.vocabulary.glossary,
             documentContexts
-          }),
-          runRoutingPhase({
+          })),
+          withTiming(timings, "routingMs", () => runRoutingPhase({
+            timings,
+            mergedCall: engineV2 && v2.mergedRoutingCall,
             question: userQuery,
             enabledContexts,
             documentContexts,
@@ -3895,8 +4135,12 @@ ${projectScope.customInstructions}` : ""
             // detector must never treat these as filename hints.
             knownIdentifiers: cfg.vocabulary.identifiers.flatMap((i) => i.examples),
             model: utilityModel
-          })
+          })),
+          // engine v2: identifier pins depend only on the question, so they run alongside
+          // memory and routing instead of after them (re-run below if memory rewrote the question).
+          engineV2 && v2.parallelPins ? withTiming(timings, "pinsParallelMs", () => pinsFor(userQuery)) : Promise.resolve(null)
         ]);
+        lap("memoryRoutingMs");
         for (const step of [...memResult.steps, ...routResult.steps]) {
           result.steps.push({
             stepNumber: 1,
@@ -3946,13 +4190,8 @@ ${projectScope.customInstructions}` : ""
           memoryPinnedItemIdsByContext,
           memoryOverride
         } = memResult;
-        const { pinsByContext: identifierPinsByContext, exactPinsByContext, steps: pinSteps } = await resolveIdentifierPins({
-          question: updatedQuestion,
-          identifierSets: cfg.vocabulary.identifiers,
-          contextsById,
-          kbKindById,
-          model: utilityModel
-        });
+        const { pinsByContext: identifierPinsByContext, exactPinsByContext, steps: pinSteps } = parallelPins && !needsPinRerun(userQuery, updatedQuestion) ? parallelPins : await pinsFor(updatedQuestion);
+        lap("pinsMs");
         for (const step of pinSteps) {
           result.steps.push({
             stepNumber: 1,
@@ -3982,6 +4221,8 @@ ${projectScope.customInstructions}` : ""
             rewrites: cfg.vocabulary.rewrites,
             styleHint: cfg.vocabulary.styleHint,
             maxQueries: cfg.tuning.maxQueriesPerContext,
+            timings,
+            timingPrefix: "search.main",
             skipPrefilter: false
           }),
           fallbackContextsToSearch.length > 0 && !hasExplicitDocAndPage ? searchContexts({
@@ -4002,9 +4243,12 @@ ${projectScope.customInstructions}` : ""
             rewrites: cfg.vocabulary.rewrites,
             styleHint: cfg.vocabulary.styleHint,
             maxQueries: cfg.tuning.maxQueriesPerContext,
+            timings,
+            timingPrefix: "search.fallback",
             skipPrefilter: true
           }) : Promise.resolve({ chunks: [] })
         ]);
+        lap("searchMs");
         const pinnedItemIds = /* @__PURE__ */ new Set([
           ...(function* () {
             for (const s of memoryPinnedItemIdsByContext.values()) yield* s;
@@ -4067,6 +4311,7 @@ ${projectScope.customInstructions}` : ""
           chunks: [],
           tokens: 0
         });
+        lap("rerankMs");
         addChunks(result, mainRerank.limited_results);
         yield { result: serializeOutput(result) };
         const literalLookupSatisfied = hasExplicitDocAndPage && mainRerank.limited_results.length > 0 && mainRerank.limited_results.some((r) => {
@@ -4115,6 +4360,7 @@ ${projectScope.customInstructions}` : ""
           });
           result.reasoning.push({ text: "Fallback results reranked", tools: [] });
           addChunks(result, fallbackRerank.limited_results);
+          lap("fallbackRerankMs");
           yield { result: serializeOutput(result) };
         }
         if (memoryOverride.active) {
@@ -4137,9 +4383,19 @@ Verified answer:
           addChunks(result, memoryOverride.chunks);
           yield { result: serializeOutput(result) };
         }
+        timings.totalMs = Date.now() - t0;
+        result.timings = timings;
+        result.steps.push({
+          stepNumber: 1,
+          text: `Timing: memory+routing ${timings.memoryRoutingMs ?? 0}ms (memory ${timings.memoryMs ?? 0}ms, routing ${timings.routingMs ?? 0}ms), pins ${timings.pinsMs ?? 0}ms, search ${timings.searchMs ?? 0}ms, rerank ${timings.rerankMs ?? 0}ms` + (timings.fallbackRerankMs !== void 0 ? `, fallback rerank ${timings.fallbackRerankMs}ms` : "") + `, total ${timings.totalMs}ms`,
+          toolCalls: [],
+          chunks: [],
+          tokens: 0
+        });
         if (cfg.logging) {
-          console.log("[EXULU pipeline] final result:", JSON.stringify({ steps: result.steps.length, chunks: result.chunks.length }));
+          console.log("[EXULU pipeline] final result:", JSON.stringify({ steps: result.steps.length, chunks: result.chunks.length, timings }));
         }
+        yield { result: serializeOutput(result) };
         return { result: serializeOutput(result) };
       } catch (err) {
         console.warn("[EXULU pipeline] retrieval pipeline failed:", err);
@@ -5723,6 +5979,33 @@ var createUppyRoutes = async (app, config) => {
   return app;
 };
 
+// ee/invoke-skills/artifact-filter.ts
+var IGNORED_SEGMENTS = /* @__PURE__ */ new Set([
+  "venv",
+  ".venv",
+  "env",
+  "node_modules",
+  "__pycache__",
+  "site-packages",
+  "dist-packages",
+  ".cache",
+  ".git",
+  ".pytest_cache",
+  ".mypy_cache",
+  ".ipynb_checkpoints"
+]);
+function isIgnoredArtifactPath(relativePath) {
+  return relativePath.split(/[\\/]+/).some((segment) => IGNORED_SEGMENTS.has(segment));
+}
+var DEFAULT_ARTIFACT_CAP = 50;
+function capArtifacts(artifacts, max = DEFAULT_ARTIFACT_CAP) {
+  if (artifacts.length <= max) return { kept: artifacts, omitted: 0 };
+  return { kept: artifacts.slice(0, max), omitted: artifacts.length - max };
+}
+function needsDownload(localSize, remoteSize) {
+  return localSize === void 0 || localSize !== remoteSize;
+}
+
 // src/exulu/system-dependencies.ts
 import { exec } from "child_process";
 import { existsSync as existsSync2 } from "fs";
@@ -5959,7 +6242,7 @@ function resolveSessionPath(inputPath, sessionDir) {
   }
   return resolved;
 }
-async function restoreArtifactsFromS3(sessionDir, sessionId, userId, config) {
+async function restoreArtifactsFromS3(sessionDir, sessionId, userId, config, opts = {}) {
   const userPrefix = `user_${userId}/sessions/${sessionId}/`;
   let objects;
   try {
@@ -5979,7 +6262,17 @@ async function restoreArtifactsFromS3(sessionDir, sessionId, userId, config) {
     const idx = obj.key.indexOf(userPrefix);
     const relativePath = idx >= 0 ? obj.key.slice(idx + userPrefix.length) : "";
     if (!relativePath) continue;
+    if (isIgnoredArtifactPath(relativePath)) continue;
     const localPath = join2(sessionDir, relativePath);
+    if (opts.onlyMissing) {
+      let localSize;
+      try {
+        localSize = (await stat(localPath)).size;
+      } catch {
+        localSize = void 0;
+      }
+      if (!needsDownload(localSize, obj.size)) continue;
+    }
     try {
       const bytes = await getS3ObjectBytes(obj.key, config);
       await mkdir(dirname(localPath), { recursive: true });
@@ -6013,6 +6306,15 @@ async function downloadKeyIntoSandbox(opts) {
   await writeFile(localPath, bytes);
   return { written: true, localPath };
 }
+async function resolvePythonVenvPath() {
+  try {
+    const { getPythonVenvPath } = await import("./python-setup-DRJ3QX5F.js");
+    return getPythonVenvPath();
+  } catch (err) {
+    console.warn("[SKILLS] Could not resolve the Python venv for the session sandbox; skill scripts fall back to the system python.", err);
+    return void 0;
+  }
+}
 async function createSessionSandbox(sessionId, skills, config, userId) {
   const cached = sandboxCache.get(sessionId);
   if (cached) {
@@ -6026,6 +6328,13 @@ async function createSessionSandbox(sessionId, skills, config, userId) {
       await downloadSkill(skill, skillsDirectory2, config);
       cached.installedSkills.set(skill.id, skill.current_version);
     }
+    if (userId && config.fileUploads) {
+      try {
+        await restoreArtifactsFromS3(cached.handle.sessionDir, sessionId, userId, config, { onlyMissing: true });
+      } catch (err) {
+        console.error(`[SKILLS] Failed to re-sync S3 session files for session ${sessionId}; continuing.`, err);
+      }
+    }
     return cached.handle;
   }
   const sessionDir = join2("/tmp", "exulu-sessions", sessionId);
@@ -6043,8 +6352,8 @@ async function createSessionSandbox(sessionId, skills, config, userId) {
       `[SKILLS] S3 artifact persistence disabled for session ${sessionId} (userId=${userId ?? "missing"}, fileUploads=${config.fileUploads ? "configured" : "missing"})`
     );
   }
-  if (userId && config.fileUploads && !dirExisted) {
-    await restoreArtifactsFromS3(sessionDir, sessionId, userId, config);
+  if (userId && config.fileUploads) {
+    await restoreArtifactsFromS3(sessionDir, sessionId, userId, config, { onlyMissing: dirExisted });
   }
   const probe = await probeSandboxSupport();
   const useDirectExec = !probe.canSandbox;
@@ -6079,6 +6388,7 @@ Probe error: ${probe.reason ?? "(no detail)"}`
     await SandboxManager.initialize(baselineSandboxConfig);
   }
   const npmGlobalRoot = await getNpmGlobalRoot();
+  const pythonVenvPath = await resolvePythonVenvPath();
   const sessionSandboxConfig = {
     network: {
       allowedDomains: [],
@@ -6093,7 +6403,8 @@ Probe error: ${probe.reason ?? "(no detail)"}`
         // Allow Node to read globally-installed packages from inside
         // the sandbox. Without this, `require('docx')` fails with
         // EPERM even when NODE_PATH points the resolver here.
-        ...npmGlobalRoot ? [npmGlobalRoot] : []
+        ...npmGlobalRoot ? [npmGlobalRoot] : [],
+        ...pythonVenvPath ? [pythonVenvPath] : []
       ],
       allowWrite: [sessionDir],
       denyWrite: []
@@ -6111,7 +6422,8 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   const sandboxedExecEnv = {
     ...configuredVariables,
     ...process.env,
-    ...npmGlobalRoot ? { NODE_PATH: npmGlobalRoot } : {}
+    ...npmGlobalRoot ? { NODE_PATH: npmGlobalRoot } : {},
+    ...pythonVenvPath ? { PATH: `${join2(pythonVenvPath, "bin")}:${process.env.PATH ?? ""}`, VIRTUAL_ENV: pythonVenvPath } : {}
   };
   const wrapIfNeeded = async (command) => {
     if (useDirectExec) return command;
@@ -6236,6 +6548,7 @@ Probe error: ${probe.reason ?? "(no detail)"}`
       for (const entry of entries) {
         const full = join2(dir, entry.name);
         if (full === skillsDir) continue;
+        if (isIgnoredArtifactPath(relative(sessionDir, full))) continue;
         if (entry.isDirectory()) {
           await walk(full);
         } else if (entry.isFile()) {
@@ -6331,19 +6644,24 @@ Probe error: ${probe.reason ?? "(no detail)"}`
         }
       }
       let stdout = result?.stdout ?? "";
-      const withUrls = artifacts.filter((a) => a.url);
+      const { kept, omitted } = capArtifacts(artifacts);
+      const withUrls = kept.filter((a) => a.url);
       if (withUrls.length > 0) {
         const lines = ["", "[exulu-artifacts]"];
         for (const a of withUrls) {
           lines.push(`  ${a.relativePath}: ${a.url}`);
         }
+        if (omitted > 0) {
+          lines.push(`  \u2026 ${omitted} more file(s) were created and mirrored but are not listed here.`);
+        }
         stdout = `${stdout}
 ${lines.join("\n")}`;
       }
       return {
         ...result,
         stdout,
-        artifacts
+        artifacts: kept,
+        ...omitted > 0 ? { artifactsOmitted: omitted } : {}
       };
     }
   });
@@ -6561,12 +6879,21 @@ var buildAuthToolModelOutput = (tool3) => ({ output }) => {
 
 // src/templates/tools/session-file-read-tool.ts
 import { z as z12 } from "zod";
+
+// src/exulu/session-files.ts
+function sessionFilePrefix(ownerId, sessionId, s3prefix) {
+  const general = s3prefix ? `${s3prefix.replace(/\/+$/, "")}/` : "";
+  return `${general}user_${ownerId}/sessions/${sessionId}/`;
+}
+
+// src/templates/tools/session-file-read-tool.ts
 var DEFAULT_LIMIT = 250;
 var MAX_CONTENT_CHARS = 16e3;
 var createSessionFileReadTool = ({
   sessionID,
   user,
-  exuluConfig
+  exuluConfig,
+  ownerId
 }) => {
   if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
   const readSessionFileExecute = async ({ filename, offset, limit }) => {
@@ -6577,8 +6904,7 @@ var createSessionFileReadTool = ({
       };
     }
     const uploads = exuluConfig.fileUploads;
-    const generalPrefix = uploads.s3prefix ? `${uploads.s3prefix.replace(/\/$/, "")}/` : "";
-    const key = `${generalPrefix}user_${user?.id ?? "api"}/sessions/${sessionID}/${safeName}`;
+    const key = `${sessionFilePrefix(ownerId ?? user?.id ?? "api", sessionID, uploads.s3prefix)}${safeName}`;
     try {
       const url = await getPresignedUrl(uploads.s3Bucket, key, exuluConfig);
       const res = await fetch(url);
@@ -6681,6 +7007,18 @@ async function renderPdfPageToPng(pdf, page, scaleTo) {
 var DEFAULT_LIMIT2 = 250;
 var MAX_CONTENT_CHARS2 = 16e3;
 var MIN_CHARS_PER_PAGE = 20;
+function looksLikeGarbledTextLayer(text) {
+  let control = 0;
+  let visible = 0;
+  for (const ch of text) {
+    const code = ch.charCodeAt(0);
+    if (code === 9 || code === 10 || code === 12 || code === 13 || code === 32) continue;
+    visible++;
+    if (code < 32 || code === 127) control++;
+  }
+  if (visible < 40) return false;
+  return control / visible > 0.01;
+}
 var OFFICE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".docx",
   ".doc",
@@ -6697,7 +7035,8 @@ var pagesPattern = /^(\d+)(?:-(\d+))?$/;
 var createParseDocumentTool = ({
   sessionID,
   user,
-  exuluConfig
+  exuluConfig,
+  ownerId
 }) => {
   if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
   const parseDocumentExecute = async ({
@@ -6722,8 +7061,7 @@ var createParseDocumentTool = ({
       return { error: `The pages option is only supported for PDF files \u2014 "${ext}" documents are extracted whole.` };
     }
     const uploads = exuluConfig.fileUploads;
-    const generalPrefix = uploads.s3prefix ? `${uploads.s3prefix.replace(/\/$/, "")}/` : "";
-    const key = `${generalPrefix}user_${user?.id ?? "api"}/sessions/${sessionID}/${safeName}`;
+    const key = `${sessionFilePrefix(ownerId ?? user?.id ?? "api", sessionID, uploads.s3prefix)}${safeName}`;
     try {
       const url = await getPresignedUrl(uploads.s3Bucket, key, exuluConfig);
       const res = await fetch(url);
@@ -6738,6 +7076,11 @@ var createParseDocumentTool = ({
         const pageTexts = raw.replace(/\f$/, "").split("\f");
         totalPages = pageTexts.length;
         const nonWhitespace = raw.replace(/\s/g, "").length;
+        if (looksLikeGarbledTextLayer(raw)) {
+          return {
+            error: `"${safeName}" has a text layer that is unreadable (its font encoding maps glyphs to the wrong characters, so words and especially numbers come out wrong or vanish). Do not use extracted text from this file. Use view_document_page to read the pages visually, or suggest the user add the document to a knowledge base with a document processor for full OCR.`
+          };
+        }
         if (nonWhitespace < totalPages * MIN_CHARS_PER_PAGE) {
           return {
             error: `"${safeName}" has no extractable text layer (likely a scan or image-based PDF). Use view_document_page to look at pages visually, or suggest the user add the document to a knowledge base with a document processor for full OCR.`
@@ -6985,7 +7328,8 @@ var OFFICE_EXTENSIONS2 = /* @__PURE__ */ new Set([
 var createViewDocumentPageTool = ({
   sessionID,
   user,
-  exuluConfig
+  exuluConfig,
+  ownerId
 }) => {
   if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
   const viewDocumentPageExecute = async ({ filename, page, model }, options) => {
@@ -7018,8 +7362,7 @@ var createViewDocumentPageTool = ({
       }
     }
     const uploads = exuluConfig.fileUploads;
-    const generalPrefix = uploads.s3prefix ? `${uploads.s3prefix.replace(/\/$/, "")}/` : "";
-    const key = `${generalPrefix}user_${user?.id ?? "api"}/sessions/${sessionID}/${safeName}`;
+    const key = `${sessionFilePrefix(ownerId ?? user?.id ?? "api", sessionID, uploads.s3prefix)}${safeName}`;
     const pageNumber = page ?? 1;
     try {
       let imageBytes;
@@ -7704,7 +8047,7 @@ var hydrateVariables = async (tool3) => {
   await Promise.all(promises);
   return tool3;
 };
-var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, contexts, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems, contextWindow, disabledTools) => {
+var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, contexts, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems, contextWindow, disabledTools, sessionOwnerId) => {
   if (!currentTools) return {};
   if (!allExuluTools) {
     allExuluTools = [];
@@ -7721,7 +8064,7 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
         sessionID,
         currentSkills || [],
         exuluConfig,
-        user?.id
+        sessionOwnerId ?? user?.id
       );
     } catch (err) {
       console.error(
@@ -7786,15 +8129,15 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
       currentTools.push(sessionItemsRetrievalTool);
     }
   }
-  const sessionFileReadTool = createSessionFileReadTool({ sessionID, user, exuluConfig });
+  const sessionFileReadTool = createSessionFileReadTool({ sessionID, user, exuluConfig, ownerId: sessionOwnerId });
   if (sessionFileReadTool && !disabled.has(sessionFileReadTool.id)) {
     currentTools.push(sessionFileReadTool);
   }
-  const parseDocumentTool = createParseDocumentTool({ sessionID, user, exuluConfig });
+  const parseDocumentTool = createParseDocumentTool({ sessionID, user, exuluConfig, ownerId: sessionOwnerId });
   if (parseDocumentTool && !disabled.has(parseDocumentTool.id)) {
     currentTools.push(parseDocumentTool);
   }
-  const viewDocumentPageTool = createViewDocumentPageTool({ sessionID, user, exuluConfig });
+  const viewDocumentPageTool = createViewDocumentPageTool({ sessionID, user, exuluConfig, ownerId: sessionOwnerId });
   if (viewDocumentPageTool && !disabled.has(viewDocumentPageTool.id)) {
     currentTools.push(viewDocumentPageTool);
   }
@@ -8161,6 +8504,7 @@ export {
   sanitizeToolName,
   KB_EDITOR_TOOL_ID,
   createKbEditorPickerTool,
+  isIgnoredArtifactPath,
   reportSystemDependencies,
   downloadKeyIntoSandbox,
   truncateToolOutput,
@@ -8176,6 +8520,7 @@ export {
   guardExtractedFileText,
   SCRUBBED_CREDENTIAL_TEXT,
   SCRUBBED_OAUTH_TEXT,
+  sessionFilePrefix,
   PreviewRenderError,
   getPdfPreviewBytes,
   imageAttachmentGuard,