@exulu/backend 1.54.0 → 1.55.0

package/ee/agentic-retrieval/v3/agent-loop.ts

@@ -6,6 +6,8 @@ import type { ExuluReranker } from "@SRC/exulu/reranker";
 import type { AgenticRetrievalOutput, ChunkResult, ClassificationResult } from "./types";
 import type { StrategyConfig } from "./strategies";
 import { createDynamicTools } from "./dynamic-tools";
+import { registerSessionTools } from "./session-tools-registry";
+import type { TrajectoryStepData } from "./trajectory";
 
 const FINISH_TOOL_NAME = "finish_retrieval";
 
@@ -71,9 +73,11 @@ export async function* runAgentLoop(params: {
   contextGuidance?: string;
   customInstructions?: string;
   classification: ClassificationResult;
+  sessionId?: string;
   onStepComplete?: (step: AgenticRetrievalOutput["steps"][0]) => void;
+  onTrajectoryStep?: (data: TrajectoryStepData) => void;
 }): AsyncGenerator<AgenticRetrievalOutput> {
-  const { query, strategy, tools, model, reranker, contextGuidance, customInstructions, onStepComplete } = params;
+  const { query, strategy, tools, model, reranker, contextGuidance, customInstructions, sessionId, onStepComplete, onTrajectoryStep } = params;
 
   const output: AgenticRetrievalOutput = {
     steps: [],
@@ -147,6 +151,16 @@ export async function* runAgentLoop(params: {
     // Extract chunks from tool results
     let stepChunks: any[] = extractChunksFromToolResults(result.toolResults as any[]);
 
+    // Deduplicate by chunk_id within this step (parallel tool calls can return the same chunk
+    // if the agent searches the same context twice, or the same chunk is indexed in two contexts).
+    const seenChunkIds = new Set<string>();
+    stepChunks = stepChunks.filter((c) => {
+      if (!c.chunk_id) return true;
+      if (seenChunkIds.has(c.chunk_id)) return false;
+      seenChunkIds.add(c.chunk_id);
+      return true;
+    });
+
     // Check if any search_content call excluded content (triggers page-load dynamic tools)
     // AI SDK v6 uses `input` (not `args`) for tool call arguments
     const hadExcludedContent = (result.toolCalls as any[])?.some(
@@ -164,6 +178,9 @@ export async function* runAgentLoop(params: {
     // Create dynamic tools (browse adjacent pages, load specific pages)
     const newDynamic = await createDynamicTools(stepChunks as ChunkResult[], hadExcludedContent);
     Object.assign(dynamicTools, newDynamic);
+    if (sessionId && Object.keys(newDynamic).length > 0) {
+      registerSessionTools(sessionId, newDynamic);
+    }
 
     // If relevant content was found but fewer than 5 chunks, withhold finish_retrieval
     // on the next step to force depth exploration via dynamic tools.
@@ -175,9 +192,14 @@ export async function* runAgentLoop(params: {
       Object.keys(newDynamic).length > 0 &&
       step < strategy.stepBudget - 2;
 
-    // Track which suggested contexts have been searched this step
+    // Track which suggested contexts have been searched this step.
+    // search_content and save_search_results now use knowledge_base_id (singular);
+    // count_items_or_chunks and search_items_by_name still use knowledge_base_ids (plural array).
     for (const tc of (result.toolCalls as any[]) ?? []) {
       if (SEARCH_TOOL_NAMES.has(tc.toolName)) {
+        if (tc.input?.knowledge_base_id) {
+          searchedContextIds.add(tc.input.knowledge_base_id);
+        }
         for (const id of (tc.input?.knowledge_base_ids ?? [])) {
           searchedContextIds.add(id);
         }
@@ -217,11 +239,35 @@ export async function* runAgentLoop(params: {
         output: stepChunks,
       })) ?? [],
     });
-    output.chunks.push(...stepChunks);
+    // Deduplicate against chunks already accumulated from prior steps
+    const existingChunkIds = new Set(output.chunks.map((c) => c.chunk_id).filter(Boolean));
+    output.chunks.push(...stepChunks.filter((c) => !c.chunk_id || !existingChunkIds.has(c.chunk_id)));
     output.usage.push(result.usage);
 
     onStepComplete?.(stepRecord);
 
+    if (onTrajectoryStep) {
+      const toolResultMap = new Map<string, any>();
+      for (const tr of (result.toolResults as any[]) ?? []) {
+        toolResultMap.set(tr.toolCallId, tr.output ?? tr.result);
+      }
+      onTrajectoryStep({
+        stepNumber: step + 1,
+        systemPrompt: stepSystemPrompt,
+        text: result.text ?? "",
+        toolCalls:
+          (result.toolCalls as any[])?.map((tc) => ({
+            name: tc.toolName,
+            id: tc.toolCallId,
+            input: tc.input,
+            output: toolResultMap.get(tc.toolCallId),
+          })) ?? [],
+        chunks: stepChunks,
+        dynamicToolsCreated: Object.keys(newDynamic),
+        tokens: result.usage?.totalTokens ?? 0,
+      });
+    }
+
     yield { ...output };
 
     // Stop if the model called finish_retrieval AND no forced continuation is needed

package/ee/agentic-retrieval/v3/classifier.ts

@@ -3,6 +3,7 @@ import type { LanguageModel } from "ai";
 import { z } from "zod";
 import type { ExuluContext } from "@SRC/exulu/context";
 import type { ClassificationResult, ContextSample } from "./types";
+import { withRetry } from "@SRC/utils/with-retry";
 
 /**
  * Classifies a query into one of four types and identifies which contexts are
@@ -27,47 +28,51 @@ export async function classifyQuery(
     })
     .join("\n\n");
 
-  const result = await generateText({
-    model,
-    temperature: 0,
-    output: Output.object({
-      schema: z.object({
-        queryType: z
-          .enum(["aggregate", "list", "targeted", "exploratory"])
-          .describe(
-            "aggregate: ONLY use when the user explicitly asks to COUNT how many documents/items/tickets exist in the knowledge base (e.g. 'how many documents about X?', 'total number of tickets'). NEVER use for: real-world statistics stored in a document, intent statements, how-to questions, error/fault descriptions, configuration questions, or any query that does not explicitly ask for a count of knowledge base entries. When in doubt, choose targeted. " +
+  const result: ClassificationResult = await withRetry(async () => {
+    const result = await generateText({
+      model,
+      temperature: 0,
+      output: Output.object({
+        schema: z.object({
+          queryType: z
+            .enum(["aggregate", "list", "targeted", "exploratory"])
+            .describe(
+              "aggregate: ONLY use when the user explicitly asks to COUNT how many documents/items/tickets exist in the knowledge base (e.g. 'how many documents about X?', 'total number of tickets'). NEVER use for: real-world statistics stored in a document, intent statements, how-to questions, error/fault descriptions, configuration questions, or any query that does not explicitly ask for a count of knowledge base entries. When in doubt, choose targeted. " +
               "list: user wants to enumerate matching items/documents (show me all, list documents about). " +
               "targeted: use for almost everything — specific fact, answer, configuration, how-to, error/fault, feature/behavior question. Also use for intent statements and short commands describing a desired state (phrases that state what the user wants to do or achieve, even without an explicit question word). Real-world statistics stored in documents also go here. When in doubt, choose targeted over aggregate or exploratory. " +
               "exploratory: only for broad conceptual questions needing multi-source synthesis (what is the process for Z, explain how X works, general overview of topic Y).",
-          ),
-        language: z
-          .string()
-          .describe("ISO 639-3 language code of the query (e.g. eng, deu, fra)"),
-        suggestedContextIds: z
-          .array(z.string())
-          .describe(
-            "IDs of knowledge bases most likely to contain the answer. Return empty array to search all contexts.",
-          ),
+            ),
+          language: z
+            .string()
+            .describe("ISO 639-3 language code of the query (e.g. eng, deu, fra)"),
+          suggestedContextIds: z
+            .array(z.enum(contexts.map((c) => c.id)))
+            .describe(
+              "IDs of knowledge bases most likely to contain the answer. Return empty array to search all contexts.",
+            ),
+        }),
       }),
-    }),
-    toolChoice: "none",
-    system: `You are a query classifier for a multi-knowledge-base retrieval system.
-Classify the query and identify which knowledge bases are most relevant.
+      toolChoice: "none",
+      system: `You are a query classifier for a multi-knowledge-base retrieval system.
+    Classify the query and identify which knowledge bases are most relevant.
+    
+    Available knowledge bases:
+    ${contextDescriptions}
+    
+    Guidelines for queryType:
+    - Use "aggregate" ONLY when the query contains explicit counting language (e.g., "how many", "count", "total number", "wie viele"). Short statements, commands, or phrases without a question word are NEVER aggregate — classify them as targeted.
+    - When in doubt between aggregate and targeted: always choose targeted.
+    
+    Guidelines for suggestedContextIds:
+    - Be conservative: only suggest contexts that are genuinely likely to contain the answer.
+      Aim for 2–3 focused suggestions rather than listing everything.
+    - Use each knowledge base's name and description (shown above) to judge relevance.
+    - Return an empty array only if you truly cannot determine which contexts are relevant.`,
+      prompt: `Query: ${query}`,
+    });
 
-Available knowledge bases:
-${contextDescriptions}
+    return result.output as ClassificationResult;
+  }, 3)
 
-Guidelines for queryType:
-- Use "aggregate" ONLY when the query contains explicit counting language (e.g., "how many", "count", "total number", "wie viele"). Short statements, commands, or phrases without a question word are NEVER aggregate — classify them as targeted.
-- When in doubt between aggregate and targeted: always choose targeted.
-
-Guidelines for suggestedContextIds:
-- Be conservative: only suggest contexts that are genuinely likely to contain the answer.
-  Aim for 2–3 focused suggestions rather than listing everything.
-- Use each knowledge base's name and description (shown above) to judge relevance.
-- Return an empty array only if you truly cannot determine which contexts are relevant.`,
-    prompt: `Query: ${query}`,
-  });
-
-  return result.output as ClassificationResult;
+  return result;
 }

package/ee/agentic-retrieval/v3/index.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { createBashTool } from "bash-tool";
-import type { LanguageModel } from "ai";
+import type { LanguageModel, Tool } from "ai";
 import type { ExuluContext } from "@SRC/exulu/context";
 import type { ExuluReranker } from "@SRC/exulu/reranker";
 import { ExuluTool } from "@SRC/exulu/tool";
@@ -8,7 +8,7 @@ import type { User } from "@EXULU_TYPES/models/user";
 import { checkLicense } from "@EE/entitlements";
 import { ContextSampler } from "./context-sampler";
 import { classifyQuery } from "./classifier";
-import { createRetrievalTools } from "./tools";
+import { createRetrievalTools, parseGlobalItemIds } from "./tools";
 import { STRATEGIES } from "./strategies";
 import { runAgentLoop } from "./agent-loop";
 import { TrajectoryLogger } from "./trajectory";
@@ -26,6 +26,9 @@ async function* executeV3({
   user,
   role,
   customInstructions,
+  logTrajectory,
+  sessionId,
+  preselectedItemIds,
 }: {
   query: string;
   contexts: ExuluContext[];
@@ -34,16 +37,29 @@ async function* executeV3({
   user?: User;
   role?: string;
   customInstructions?: string;
+  logTrajectory?: boolean;
+  sessionId?: string;
+  preselectedItemIds?: string[];
 }): AsyncGenerator<AgenticRetrievalOutput> {
-  // ── 1. Sample example records from each context (cached) ──────────────────
+  // ── 1. Parse preselected item IDs (global format: "<context_id>/<item_id>") ─
+  const preselectedByContext = preselectedItemIds?.length
+    ? parseGlobalItemIds(preselectedItemIds)
+    : undefined;
+
+  // When preselection is active, restrict to only contexts that have selected items
+  const activeContexts = preselectedByContext?.size
+    ? contexts.filter((c) => preselectedByContext.has(c.id))
+    : contexts;
+
+  // ── 2. Sample example records from each context (cached) ──────────────────
   console.log("[EXULU] v3 — sampling contexts");
-  const samples = await sampler.getSamples(contexts, user, role);
+  const samples = await sampler.getSamples(activeContexts, user, role);
 
-  // ── 2. Classify query (single fast LLM call) ──────────────────────────────
+  // ── 3. Classify query (single fast LLM call) ──────────────────────────────
   console.log("[EXULU] v3 — classifying query");
   let classification;
   try {
-    classification = await classifyQuery(query, contexts, samples, model);
+    classification = await classifyQuery(query, activeContexts, samples, model);
   } catch (err) {
     console.warn("[EXULU] v3 — classification failed, falling back to exploratory:", err);
     classification = {
@@ -54,32 +70,39 @@ async function* executeV3({
   }
   console.log("[EXULU] v3 — classified as:", classification);
 
-  // ── 3. Select strategy ────────────────────────────────────────────────────
+  // ── 4. Select strategy ────────────────────────────────────────────────────
   const strategy = STRATEGIES[classification.queryType];
 
   // Build context guidance: the classifier is a priority hint, not a hard filter.
   // All contexts remain available so the agent can fall back if suggested ones miss.
   const suggestedIds = classification.suggestedContextIds;
-  const fallbackIds = contexts
+  const fallbackIds = activeContexts
     .filter((c) => !suggestedIds.includes(c.id))
     .map((c) => c.id);
-  const contextGuidance =
+  const contextBase =
     suggestedIds.length > 0
       ? `Suggested priority contexts: [${suggestedIds.join(", ")}]. Also available: [${fallbackIds.join(", ")}]. Custom instructions may require searching additional or all contexts — follow them.`
-      : `All contexts available: [${contexts.map((c) => c.id).join(", ")}].`;
+      : `All contexts available: [${activeContexts.map((c) => c.id).join(", ")}].`;
+
+  const preselectedNote = preselectedByContext?.size
+    ? `\nSCOPE CONSTRAINT: Retrieval is scoped to preselected items/contexts. Per context: ${[...preselectedByContext.entries()].map(([ctx, ids]) => ids === null ? `${ctx} (full context)` : `${ctx} (${ids.length} item${ids.length === 1 ? "" : "s"})`).join(", ")}. All tools enforce this scope automatically. For full-context entries you may search freely; for item-restricted entries do NOT use search_items_by_name for discovery — go directly to search_content or save_search_results.`
+    : "";
 
-  // ── 4. Initialize tools ───────────────────────────────────────────────────
+  const contextGuidance = contextBase + preselectedNote;
+
+  // ── 5. Initialize tools ───────────────────────────────────────────────────
   const bashToolkit = await createBashTool({ files: {} });
 
   const retrievalTools = createRetrievalTools({
-    contexts, // ALL contexts — agent decides which to search based on context guidance
+    contexts: activeContexts,
     user,
     role,
     updateVirtualFiles: (files) => bashToolkit.sandbox.writeFiles(files),
+    preselectedItemsByContext: preselectedByContext,
   });
 
   // Build the tool set for this strategy
-  const activeTools: Record<string, any> = {};
+  const activeTools: Record<string, Tool> = {};
   for (const name of strategy.retrieval_tools) {
     if (name in retrievalTools) {
       activeTools[name] = retrievalTools[name as keyof typeof retrievalTools];
@@ -89,10 +112,10 @@ async function* executeV3({
     Object.assign(activeTools, bashToolkit.tools);
   }
 
-  // ── 5. Set up trajectory logging ──────────────────────────────────────────
-  const trajectory = new TrajectoryLogger(query, classification);
+  // ── 6. Set up trajectory logging ──────────────────────────────────────────
+  const trajectory = new TrajectoryLogger(query, classification, undefined, preselectedItemIds);
 
-  // ── 6. Run agent loop ─────────────────────────────────────────────────────
+  // ── 7. Run agent loop ─────────────────────────────────────────────────────
   let finalOutput: AgenticRetrievalOutput | undefined;
   let executionError: Error | undefined;
 
@@ -106,7 +129,9 @@ async function* executeV3({
       contextGuidance,
       customInstructions,
       classification,
+      sessionId,
       onStepComplete: (step) => trajectory.recordStep(step),
+      onTrajectoryStep: (data) => trajectory.recordRichStep(data),
     })) {
       finalOutput = output;
       yield output;
@@ -117,7 +142,7 @@ async function* executeV3({
     throw err;
   } finally {
     if (finalOutput) {
-      const trajectoryFile = await trajectory.finalize(finalOutput, !executionError, executionError);
+      const trajectoryFile = await trajectory.finalize(finalOutput, !executionError, executionError, logTrajectory);
       if (trajectoryFile) {
         finalOutput.trajectoryFile = trajectoryFile;
       }
@@ -141,6 +166,7 @@ export function createAgenticRetrievalToolV3({
   user,
   role,
   model,
+  preselectedItemIds,
 }: {
   contexts: ExuluContext[];
   rerankers: ExuluReranker[];
@@ -148,6 +174,7 @@ export function createAgenticRetrievalToolV3({
   role?: string;
   model?: LanguageModel;
   instructions?: string;
+  preselectedItemIds?: string[];
 }): ExuluTool | undefined {
   const license = checkLicense();
   if (!license["agentic-retrieval"]) {
@@ -177,6 +204,12 @@ export function createAgenticRetrievalToolV3({
         type: "string",
         default: "none",
       },
+      {
+        name: "managed_context",
+        description: "Makes sure the user defines which items from which contexts the agentic retrieval tool will search in",
+        type: "boolean",
+        default: false,
+      },
       {
         name: "reasoning_model",
         description: "By default the agentic retrieval tool uses the model from the agent calling the tool, but you can overwrite this here for the reasoning phase",
@@ -189,6 +222,18 @@ export function createAgenticRetrievalToolV3({
         type: "string",
         default: "",
       },
+      {
+        name: "require_preselected_contexts",
+        description: "Require the user to preselect contexts before executing the tool, meaning the user will be asked to select the contexts they want to search in",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "log_trajectories",
+        description: "Save a detailed markdown + JSON log of every retrieval execution to disk. Useful for debugging and evaluation.",
+        type: "boolean",
+        default: false,
+      },
       ...contexts.map((ctx) => ({
         name: ctx.id,
         description: `Enable search in "${ctx.name}". ${ctx.description}`,
@@ -202,15 +247,26 @@ export function createAgenticRetrievalToolV3({
         .string()
         .optional()
         .describe("Additional instructions from the user to guide retrieval"),
+      confirmedContextIds: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Knowledge base IDs explicitly confirmed by the user to be used in the retrieval. " +
+          "When presen only searches these contexts. "
+        )
     }),
     execute: async function* ({
       query,
       userInstructions,
+      confirmedContextIds,
       toolVariablesConfig,
+      sessionID,
     }: {
       query: string;
       userInstructions?: string;
+      confirmedContextIds?: string[];
       toolVariablesConfig?: Record<string, any>;
+      sessionID?: string;
     }) {
       
       /* ROADMAP:
@@ -234,14 +290,24 @@ export function createAgenticRetrievalToolV3({
       } */
 
       if (!model) {
-        throw new Error("Model is required for executing the agentic retrieval tool");
+        yield { result: "Model is required for executing the agentic retrieval tool" };
+        return;
       }
+
       let activeContexts = contexts;
       let configuredReranker: ExuluReranker | undefined;
       let configInstructions = "";
+      let logTrajectory = false;
+      let requiresPreselectedContexts = false;
+      let managedContextEnabled = false;
 
       if (toolVariablesConfig) {
         configInstructions = toolVariablesConfig["instructions"] ?? "";
+        logTrajectory =
+          toolVariablesConfig["log_trajectories"] === true ||
+          toolVariablesConfig["log_trajectories"] === "true";
+
+        managedContextEnabled = toolVariablesConfig["managed_context"] === true || toolVariablesConfig["managed_context"] === "true";
 
         activeContexts = contexts.filter(
           (ctx) =>
@@ -251,12 +317,36 @@ export function createAgenticRetrievalToolV3({
         );
         if (activeContexts.length === 0) activeContexts = contexts;
 
+        requiresPreselectedContexts = toolVariablesConfig["require_preselected_contexts"] === true || toolVariablesConfig["require_preselected_contexts"] === "true";
+
         const rerankerId = toolVariablesConfig["reranker"];
+        
         if (rerankerId && rerankerId !== "none") {
           configuredReranker = rerankers.find((r) => r.id === rerankerId);
         }
       }
 
+      console.log("[EXULU] Managed context enabled:", managedContextEnabled);
+      console.log("[EXULU] Preselected item IDs:", preselectedItemIds);
+
+      if (managedContextEnabled && !preselectedItemIds?.length) {
+        console.log("[EXULU] Managed context was enabled for the agentic retrieval tool. This means that the user must preselect items that the agentic retrieval tool will search in, please notify the user to preselect items before executing the tool.");
+        yield { result: "Managed context was enabled for the agentic retrieval tool. This means that the user must preselect items that the agentic retrieval tool will search in, please notify the user to preselect items before executing the tool." };
+        return;
+      }
+
+      if (requiresPreselectedContexts && !confirmedContextIds?.length && !preselectedItemIds?.length) {
+        console.log("[EXULU] The user must choose between the available contexts before executing the tool. The available contexts are: " + activeContexts.map((c) => c.id).join(", ") + ". If the question_ask tool is available use that to ask the user which contexts they want to search in, otherwise just ask them in plain text.");
+        yield { result: "The user must choose between the available contexts before executing the tool, the available contexts are: " + activeContexts.map((c) => c.id).join(", ") + ". If the question_ask tool is available use that to ask the user which contexts they want to search in, otherwise just ask them in plain text." };
+        return;
+      }
+
+      if (confirmedContextIds?.length) {
+        const confirmed = new Set(confirmedContextIds);
+        const filtered = activeContexts.filter((c) => confirmed.has(c.id));
+        if (filtered.length > 0) activeContexts = filtered;
+      }
+
       const combinedInstructions = [
         configInstructions ? `Configuration instructions: ${configInstructions}` : "",
         adminInstructions ? `Admin instructions: ${adminInstructions}` : "",
@@ -273,9 +363,13 @@ export function createAgenticRetrievalToolV3({
         user,
         role,
         customInstructions: combinedInstructions || undefined,
+        logTrajectory,
+        sessionId: sessionID,
+        preselectedItemIds,
       })) {
         yield { result: JSON.stringify(output) };
       }
+      return;
     },
   });
 }

package/ee/agentic-retrieval/v3/session-tools-registry.ts

@@ -0,0 +1,20 @@
+import type { Tool as AITool } from "ai";
+
+// Persists dynamic tools (get_more_content_from_X, get_X_page_N_content) created
+// during an agentic retrieval run, keyed by session ID. This lets the outer chat
+// agent call them directly on follow-up questions without re-running retrieval.
+const registry = new Map<string, Map<string, AITool>>();
+
+export function registerSessionTools(sessionId: string, tools: Record<string, AITool>): void {
+  const existing = registry.get(sessionId) ?? new Map();
+  for (const [name, toolDef] of Object.entries(tools)) {
+    existing.set(name, toolDef);
+  }
+  registry.set(sessionId, existing);
+}
+
+export function getSessionTools(sessionId: string): Record<string, AITool> {
+  const toolMap = registry.get(sessionId);
+  if (!toolMap || toolMap.size === 0) return {};
+  return Object.fromEntries(toolMap.entries());
+}

package/ee/agentic-retrieval/v3/strategies.ts

@@ -25,9 +25,10 @@ another component will do that based on what you retrieve.
 Always respond in the SAME LANGUAGE as the user's query.
 Always write search queries in the SAME LANGUAGE as the user's query — do NOT translate to English.
 
-SEARCH APPROACH — go wide first, then deep:
-1. First step: search broadly across all sources the system instructions indicate — do NOT
-   pre-filter to a single context on step 1.
+SEARCH APPROACH — one knowledge base at a time, then go deep:
+1. search_content and save_search_results accept ONE knowledge base per call. Make a separate
+   call for each knowledge base you need to cover — never skip one. Search all relevant
+   knowledge bases before concluding, even if the first one already returned good results.
 2. After finding a relevant document, use get_more_content_from_{item} dynamic tools to load
    additional pages/sections. The specific answer is often NOT in the first retrieved chunk —
    always explore adjacent content before concluding.
@@ -44,9 +45,8 @@ export const AGGREGATE_INSTRUCTIONS = `
 ${BASE_INSTRUCTIONS}
 
 STRATEGY: This is a COUNTING or AGGREGATION query.
-- Use count_items_or_chunks exclusively
+- Use count_items_or_chunks exclusively — it accepts multiple knowledge bases in one call for efficiency
 - Do NOT use search_content — it loads unnecessary data
-- Search ALL contexts in parallel in a single tool call
 - Return immediately after counting — one step is sufficient
 - If the count needs a content filter, use content_query parameter
 `.trim();
@@ -81,9 +81,23 @@ Search language:
 - Always write search queries in the SAME LANGUAGE as the user's query.
 - Do NOT translate the query to English — the documents are indexed in their original language.
 
-Step 1 — wide hybrid search (includeContent: true, limit 10):
-- Search broadly across all sources per the system instructions — do not limit to 1 context.
-- This gives you the best results from every relevant source at once.
+Step 1 — match the opening move to what the query actually needs:
+
+  Query references a SPECIFIC NAMED DOCUMENT (product manual, titled report, named file):
+  → ALWAYS start with search_items_by_name — searches document name/title directly
+  → Only proceed to load content if the document is found
+
+  Query asks WHETHER a topic EXISTS or WHAT documents cover a topic (no specific title given):
+  → search_content with includeContent: false
+  → Returns matching document names without loading chunk text — efficient and precise
+  → Load content with dynamic get_{item}_page_{n}_content tools only if needed in step 2
+
+  Query asks for CONTENT itself (procedures, parameters, explanations, how-to):
+  → search_content with includeContent: true, limit 20, searchMethod: "hybrid"
+  → Make one call per knowledge base — search each separately before concluding
+
+  Query provides an EXACT TERM (error code, product code, ID, parameter name):
+  → search_content with searchMethod: "keyword"
 
 Step 2+ — depth and follow-up:
 - For any relevant document found with fewer than 5 chunks, use get_more_content_from_{item}
@@ -93,19 +107,9 @@ Step 2+ — depth and follow-up:
 - Try alternative phrasings if the first query doesn't surface the right answer.
 
 Product-specific filtering:
-- When the query mentions a specific product (e.g., "FST-3", "ECO"), you MAY use
-  item_names: ["<product>"] on a follow-up search to narrow results — but only after an initial
+- When the query mentions a specific named entity (product, model, version), you MAY use
+  item_names: ["<entity>"] on a follow-up search to narrow results — but only after an initial
   wide search. Never start with item_names filtering alone.
-
-Two-step approach — use includeContent: false first:
-- Only when you expect many results (>20) and need to identify the right document first.
-- Step 1: search_content with includeContent: false → see which documents/chunks match.
-- Step 2: use dynamic get_{item}_page_{n}_content tools to load specific pages.
-
-Search method selection:
-- hybrid (default): best for most queries
-- keyword: exact product codes, document IDs, error codes
-- semantic: conceptual questions, synonyms, paraphrasing
 `.trim();
 
 export const EXPLORATORY_INSTRUCTIONS = `
@@ -114,13 +118,13 @@ ${BASE_INSTRUCTIONS}
 STRATEGY: This is an EXPLORATORY query — general question requiring broad search.
 
 Recommended approach:
-1. Start with a wide hybrid search across all relevant contexts (includeContent: true, limit: 10)
+1. Search each relevant knowledge base separately with hybrid search (includeContent: true, limit: 20) — one call per knowledge base
 2. If results are insufficient: try alternative search terms or different search method
 3. Use save_search_results + bash grep when you need to scan many results without context bloat
 4. Use dynamic get_more_content_from_{item} tools to read adjacent pages when a relevant item is found
 
 When to declare done:
-- You have retrieved chunks that cover the key aspects of the query
+- You have retrieved chunks that cover the key aspects of the query from all relevant knowledge bases
 - OR you have tried 3+ different search strategies and found nothing relevant
 
 Do NOT use count_items_or_chunks for exploratory queries — the user wants content, not statistics.
@@ -140,7 +144,7 @@ export const STRATEGIES: Record<QueryType, StrategyConfig> = {
   },
   list: {
     queryType: "list",
-    stepBudget: 2,
+    stepBudget: 3,
     retrieval_tools: ["count_items_or_chunks", "search_items_by_name", "search_content"],
     include_bash: false,
     instructions: LIST_INSTRUCTIONS,
@@ -154,7 +158,7 @@ export const STRATEGIES: Record<QueryType, StrategyConfig> = {
   },
   exploratory: {
     queryType: "exploratory",
-    stepBudget: 4,
+    stepBudget: 5,
     retrieval_tools: [
       "count_items_or_chunks",
       "search_items_by_name",