@exulu/backend 3.7.4 → 4.1.0

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   isPythonEnvironmentSetup,
   setupPythonEnvironment,
   validatePythonEnvironment
-} from "./chunk-27K2CO47.js";
+} from "./chunk-QMN6MVHQ.js";
 import {
   COMPACTION_INSUFFICIENT,
   ContextCompactionRequiredError,
@@ -62,6 +62,7 @@ import {
   imageAttachmentGuard,
   initAudit,
   invalidateBudgetCaches,
+  isIgnoredArtifactPath,
   isLiteLLMEnabled,
   listS3ObjectsByPrefix,
   listTagsByPrefix,
@@ -75,6 +76,7 @@ import {
   resolveReranker,
   sanitizeName,
   sanitizeToolName,
+  sessionFilePrefix,
   setBudgetSettings,
   setLiteLLMPackageRoot,
   sliceHistoryAtCheckpoint,
@@ -88,7 +90,7 @@ import {
   verifyCredentialNonce,
   waitForLiteLLMReady,
   withRetry
-} from "./chunk-AWMU6QXB.js";
+} from "./chunk-RBEWHG7I.js";
 import {
   LiteLLMAdminError,
   findLiteLLMModel,
@@ -1418,6 +1420,67 @@ function resolveSearchQueryTexts(query) {
     hybridOrQuery: buildFullTextOrQuery(query, ftsText)
   };
 }
+function chooseFullTextQuery(opts) {
+  if (opts.strictMatches || countOrTerms(opts.orText) > MAX_OR_TERMS) {
+    return { fn: "plainto_tsquery", text: opts.strictText };
+  }
+  return { fn: "websearch_to_tsquery", text: opts.orText };
+}
+var MAX_OR_TERMS = 12;
+function countOrTerms(orText) {
+  return orText.trim() ? orText.split(/\s+or\s+/i).length : 0;
+}
+
+// src/graphql/resolvers/expand-neighbours.ts
+function planNeighbourFetch(results, expand) {
+  const before = Math.max(0, expand.before ?? 0);
+  const after = Math.max(0, expand.after ?? 0);
+  const plan = /* @__PURE__ */ new Map();
+  if (before === 0 && after === 0) return plan;
+  const present = new Set(results.map((r) => `${r.item_id}-${r.chunk_index}`));
+  for (const r of results) {
+    for (let i = r.chunk_index - before; i <= r.chunk_index + after; i++) {
+      if (i < 0 || i === r.chunk_index || present.has(`${r.item_id}-${i}`)) continue;
+      if (!plan.has(r.item_id)) plan.set(r.item_id, /* @__PURE__ */ new Set());
+      plan.get(r.item_id).add(i);
+    }
+  }
+  return plan;
+}
+function mergeNeighbours(results, rows, plan, context) {
+  const byItem = /* @__PURE__ */ new Map();
+  for (const r of results) if (!byItem.has(r.item_id)) byItem.set(r.item_id, r);
+  const merged = /* @__PURE__ */ new Map();
+  for (const r of results) merged.set(`${r.item_id}-${r.chunk_index}`, r);
+  for (const row of rows) {
+    if (!plan.get(row.source)?.has(row.chunk_index)) continue;
+    const key = `${row.source}-${row.chunk_index}`;
+    if (merged.has(key)) continue;
+    const parent = byItem.get(row.source);
+    if (!parent) continue;
+    merged.set(key, {
+      chunk_content: row.content,
+      chunk_index: row.chunk_index,
+      chunk_id: row.id,
+      chunk_source: row.source,
+      chunk_metadata: row.metadata,
+      chunk_created_at: row.createdAt,
+      chunk_updated_at: row.updatedAt,
+      item_updated_at: parent.item_updated_at,
+      item_created_at: parent.item_created_at,
+      item_id: parent.item_id,
+      item_external_id: parent.item_external_id,
+      item_name: parent.item_name,
+      chunk_cosine_distance: 0,
+      chunk_fts_rank: 0,
+      chunk_hybrid_score: 0,
+      context
+    });
+  }
+  return Array.from(merged.values()).sort(
+    (a, b) => a.item_id === b.item_id ? a.chunk_index - b.chunk_index : 0
+  );
+}
 
 // src/graphql/resolvers/field-allow-list.ts
 var ALWAYS_ALLOWED = /* @__PURE__ */ new Set(["id", "createdAt", "updatedAt"]);
@@ -2385,6 +2448,14 @@ var agentsSchema = {
       name: "max_tool_steps",
       type: "number"
     },
+    {
+      // Thinking budget of the answer model, forwarded as LiteLLM's
+      // reasoning_effort ("none" | "disable" | "minimal" | "low" | "medium" |
+      // "high"). null = provider default. See resolve-reasoning-effort.ts.
+      // Auto-ALTERed on boot.
+      name: "reasoning_effort",
+      type: "text"
+    },
     {
       name: "guest_access",
       type: "boolean",
@@ -3099,6 +3170,14 @@ var convertContextToTableDefinition = (context) => {
   return addCoreFields(definition);
 };
 
+// src/graphql/resolvers/query-embedding-policy.ts
+function needsQueryEmbedding(method) {
+  return method !== "tsvector";
+}
+function boostsWithQueryEntities(method) {
+  return method !== "tsvector";
+}
+
 // src/exulu/entities/config.ts
 var hydrateEntityTypes = async (context) => {
   const byName = /* @__PURE__ */ new Map();
@@ -3863,7 +3942,9 @@ var vectorSearch = async ({
     const embedText = texts.embedText;
     hybridOrQuery = texts.hybridOrQuery;
     query = texts.ftsText;
-    if (queryEmbedding && queryEmbedding.length) {
+    if (!needsQueryEmbedding(method)) {
+      _embedSource = "none";
+    } else if (queryEmbedding && queryEmbedding.length) {
       vector = queryEmbedding;
       _embedSource = "reused";
     } else {
@@ -3896,8 +3977,10 @@ var vectorSearch = async ({
       vector = queryVector;
       _embedSource = "computed";
     }
-    vectorStr = `ARRAY[${vector.join(",")}]`;
-    vectorExpr = `${vectorStr}::vector`;
+    if (vector.length) {
+      vectorStr = `ARRAY[${vector.join(",")}]`;
+      vectorExpr = `${vectorStr}::vector`;
+    }
   }
   let keywordsQuery = [];
   if (keywords) {
@@ -3955,14 +4038,22 @@ var vectorSearch = async ({
       ]);
       resultChunks = await chunksQuery;
       break;
-    case "hybridSearch":
+    case "hybridSearch": {
+      let strictMatches = false;
+      if (query && hybridOrQuery) {
+        const probe = await db(chunksTable + " as chunks").select(db.raw("1")).whereRaw(`(${languages.map((lang) => `chunks.fts @@ plainto_tsquery('${lang}', ?)`).join(" OR ")})`, languages.map(() => query)).first();
+        strictMatches = Boolean(probe);
+      }
+      const fullText = chooseFullTextQuery({ strictMatches, strictText: query ?? "", orText: hybridOrQuery });
+      const ftsFn = fullText.fn;
+      hybridOrQuery = fullText.text;
       const matchCount = Math.min(limit * 2);
       const fullTextWeight = 2;
       const semanticWeight = 1;
       const rrfK = 50;
-      const ftRankExpression = languages.map((lang) => `ts_rank(chunks.fts, websearch_to_tsquery('${lang}', ?))`).join(", ");
+      const ftRankExpression = languages.map((lang) => `ts_rank(chunks.fts, ${ftsFn}('${lang}', ?))`).join(", ");
       const ftRankParams = languages.map(() => hybridOrQuery);
-      const ftMatchExpression = languages.map((lang) => `chunks.fts @@ websearch_to_tsquery('${lang}', ?)`).join(" OR ");
+      const ftMatchExpression = languages.map((lang) => `chunks.fts @@ ${ftsFn}('${lang}', ?)`).join(" OR ");
       const ftMatchParams = languages.map(() => hybridOrQuery);
       let fullTextQuery = db(chunksTable + " as chunks").select([
         "chunks.id",
@@ -4003,7 +4094,7 @@ var vectorSearch = async ({
         db.raw('items."updatedAt" as item_updated_at'),
         db.raw('items."createdAt" as item_created_at'),
         db.raw(
-          `GREATEST(${languages.map((lang) => `ts_rank(chunks.fts, websearch_to_tsquery('${lang}', ?))`).join(", ")}) AS fts_rank`,
+          `GREATEST(${languages.map((lang) => `ts_rank(chunks.fts, ${ftsFn}('${lang}', ?))`).join(", ")}) AS fts_rank`,
           languages.map(() => hybridOrQuery)
         ),
         db.raw(`(1 - (chunks.embedding <=> ${vectorExpr})) AS cosine_distance`),
@@ -4029,12 +4120,14 @@ var vectorSearch = async ({
                   `,
         [rrfK, fullTextWeight, rrfK, semanticWeight, cutoffs?.hybrid || 0]
       ).whereRaw(
-        `(chunks.fts IS NULL OR GREATEST(${languages.map((lang) => `ts_rank(chunks.fts, websearch_to_tsquery('${lang}', ?))`).join(", ")}) > ?)`,
+        `(chunks.fts IS NULL OR GREATEST(${languages.map((lang) => `ts_rank(chunks.fts, ${ftsFn}('${lang}', ?))`).join(", ")}) > ?)`,
         [...languages.map(() => hybridOrQuery), cutoffs?.tsvector || 0]
       ).whereRaw(`(chunks.embedding IS NULL OR (1 - (chunks.embedding <=> ${vectorExpr})) >= ?)`, [
         cutoffs?.cosineDistance || 0
       ]).orderByRaw("hybrid_score DESC").limit(Math.min(matchCount, 250));
       resultChunks = await hybridQuery;
+      break;
+    }
   }
   if (process.env.EXULU_VS_TIMING) {
     console.log(
@@ -4086,7 +4179,7 @@ var vectorSearch = async ({
   }
   let queryEntities = [];
   let entityInsights;
-  if (entitiesOn && rawQuery) {
+  if (entitiesOn && rawQuery && boostsWithQueryEntities(method)) {
     try {
       const types = await hydrateEntityTypes(context);
       const { mentions: queryMentions } = await extractEntitiesForItem({
@@ -4118,104 +4211,18 @@ var vectorSearch = async ({
   }
   results = results.slice(0, limit);
   if (expand?.before || expand?.after) {
-    const expandedMap = /* @__PURE__ */ new Map();
-    for (const chunk of results) {
-      expandedMap.set(`${chunk.item_id}-${chunk.chunk_index}`, chunk);
-    }
-    if (expand?.before) {
-      for (const chunk of results) {
-        const indicesToFetch = Array.from(
-          { length: expand.before },
-          (_, i) => chunk.chunk_index - expand.before + i
-        ).filter((index) => index >= 0);
-        await Promise.all(
-          indicesToFetch.map(async (index) => {
-            if (expandedMap.has(`${chunk.item_id}-${index}`)) {
-              return;
-            }
-            const expandedChunk = await db(chunksTable).where({
-              source: chunk.item_id,
-              chunk_index: index
-            }).first();
-            if (expandedChunk) {
-              if (expandedChunk) {
-                expandedMap.set(`${chunk.item_id}-${index}`, {
-                  chunk_content: expandedChunk.content,
-                  chunk_index: expandedChunk.chunk_index,
-                  chunk_id: expandedChunk.id,
-                  chunk_source: expandedChunk.source,
-                  chunk_metadata: expandedChunk.metadata,
-                  chunk_created_at: expandedChunk.createdAt,
-                  chunk_updated_at: expandedChunk.updatedAt,
-                  item_updated_at: chunk.item_updated_at,
-                  item_created_at: chunk.item_created_at,
-                  item_id: chunk.item_id,
-                  item_external_id: chunk.item_external_id,
-                  item_name: chunk.item_name,
-                  chunk_cosine_distance: 0,
-                  chunk_fts_rank: 0,
-                  chunk_hybrid_score: 0,
-                  context: {
-                    name: table.name.singular,
-                    id: table.id || ""
-                  }
-                });
-              }
-            }
-          })
-        );
-      }
+    const plan = planNeighbourFetch(results, expand);
+    if (plan.size > 0) {
+      const itemIds = Array.from(plan.keys());
+      const indices = Array.from(new Set(Array.from(plan.values()).flatMap((s) => Array.from(s))));
+      const rows = await db(chunksTable).select(["id", "source", "chunk_index", "content", "metadata", "createdAt", "updatedAt"]).whereIn("source", itemIds).whereIn("chunk_index", indices);
+      results = mergeNeighbours(results, rows, plan, { name: table.name.singular, id: table.id || "" });
     }
-    if (expand?.after) {
-      for (const chunk of results) {
-        const indicesToFetch = Array.from(
-          { length: expand.after },
-          (_, i) => chunk.chunk_index + i + 1
-        );
-        await Promise.all(
-          indicesToFetch.map(async (index) => {
-            if (expandedMap.has(`${chunk.item_id}-${index}`)) {
-              return;
-            }
-            const expandedChunk = await db(chunksTable).where({
-              source: chunk.item_id,
-              chunk_index: index
-            }).first();
-            if (expandedChunk) {
-              expandedMap.set(`${chunk.item_id}-${index}`, {
-                chunk_content: expandedChunk.content,
-                chunk_index: expandedChunk.chunk_index,
-                chunk_id: expandedChunk.id,
-                chunk_source: expandedChunk.source,
-                chunk_metadata: expandedChunk.metadata,
-                chunk_created_at: expandedChunk.createdAt,
-                chunk_updated_at: expandedChunk.updatedAt,
-                item_updated_at: chunk.item_updated_at,
-                item_created_at: chunk.item_created_at,
-                item_id: chunk.item_id,
-                item_external_id: chunk.item_external_id,
-                item_name: chunk.item_name,
-                chunk_cosine_distance: 0,
-                chunk_fts_rank: 0,
-                chunk_hybrid_score: 0,
-                context: {
-                  name: table.name.singular,
-                  id: table.id || ""
-                }
-              });
-            }
-          })
-        );
-      }
-    }
-    results = Array.from(expandedMap.values());
     results = results.sort((a, b) => {
       if (a.item_id !== b.item_id) {
         return a.item_id.localeCompare(b.item_id);
       }
-      const aIndex = Number(a.chunk_index);
-      const bIndex = Number(b.chunk_index);
-      return aIndex - bIndex;
+      return Number(a.chunk_index) - Number(b.chunk_index);
     });
   }
   if (entitiesOn) {
@@ -7741,6 +7748,19 @@ function serializeError(err, depth = 0) {
   return { message: String(err) };
 }
 
+// src/exulu/turn-metadata.ts
+function finishTurnMetadata(opts) {
+  const now = opts.now ?? Date.now();
+  return {
+    totalTokens: opts.totalUsage.totalTokens,
+    reasoningTokens: opts.totalUsage.reasoningTokens,
+    inputTokens: opts.totalUsage.inputTokens,
+    outputTokens: opts.totalUsage.outputTokens,
+    cachedInputTokens: opts.totalUsage.cachedInputTokens,
+    durationMs: Math.max(0, now - opts.startedAt)
+  };
+}
+
 // src/exulu/agent-as-tool.ts
 import { z as z2 } from "zod";
 
@@ -7846,6 +7866,54 @@ async function resolveFreshFileUrl(url, opts) {
   }
 }
 
+// src/exulu/session-file-listing.ts
+var DEFAULT_MAX = 25;
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatAge(then, now) {
+  const minutes = Math.max(0, Math.round((now.getTime() - then.getTime()) / 6e4));
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  const days = Math.round(hours / 24);
+  return `${days} day${days === 1 ? "" : "s"} ago`;
+}
+function describeSessionFiles(files, opts = {}) {
+  const now = opts.now ?? /* @__PURE__ */ new Date();
+  const max = opts.max ?? DEFAULT_MAX;
+  const usable = files.filter((f) => f.name && !f.name.endsWith("/") && !isIgnoredArtifactPath(f.name)).sort((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
+  if (usable.length === 0) return "";
+  const shown = usable.slice(0, max);
+  const lines = shown.map((f) => {
+    const isNew = opts.lastTurnAt ? f.lastModified.getTime() > opts.lastTurnAt.getTime() : false;
+    return `- ${f.name} (${formatSize(f.size)}, ${formatAge(f.lastModified, now)})${isNew ? " [NEW since your last answer]" : ""}`;
+  });
+  const omitted = usable.length - shown.length;
+  if (omitted > 0) lines.push(`\u2026 and ${omitted} more file${omitted === 1 ? "" : "s"} (list them with \`ls\`).`);
+  return "Files currently in this session (newest first):\n" + lines.join("\n") + '\nThese files are available to you. When the user refers to one of these files, to "the document" or "the attachment", or asks something only such a file can answer, read it with parse_document, view_document_page or read_session_file. Otherwise proceed as usual, e.g. with the knowledge bases.';
+}
+async function loadSessionFileListing(opts) {
+  const uploads = opts.exuluConfig?.fileUploads;
+  if (!uploads?.s3Bucket) return "";
+  const prefix = sessionFilePrefix(opts.ownerId, opts.sessionID, uploads.s3prefix);
+  try {
+    const objects = await listS3ObjectsByPrefix(prefix, opts.exuluConfig);
+    const files = objects.map((o) => ({
+      name: o.key.slice(o.key.indexOf(prefix) + prefix.length),
+      size: o.size,
+      lastModified: new Date(o.lastModified)
+    }));
+    return describeSessionFiles(files, { lastTurnAt: opts.lastTurnAt });
+  } catch (err) {
+    console.warn(`[EXULU] could not list session files for prompt (session ${opts.sessionID}):`, err);
+    return "";
+  }
+}
+
 // src/exulu/generate-stream.ts
 import {
   convertToModelMessages,
@@ -8085,11 +8153,12 @@ function resolveTurnStepBudget(maxStepCount, agent) {
   }
   return DEFAULT_MAX_STEPS;
 }
+var TOOL_INPUT_FLATTEN_CHARS = 6e3;
 function flattenPart(part) {
   const p = part;
   if (p?.type === "text") return p.text ?? "";
   if (p?.type === "tool-call") {
-    return `Earlier, the assistant ran the "${p.toolName}" tool with input: ${JSON.stringify(p.input ?? {}).slice(0, 300)}`;
+    return `Earlier, the assistant ran the "${p.toolName}" tool with input: ${JSON.stringify(p.input ?? {}).slice(0, TOOL_INPUT_FLATTEN_CHARS)}`;
   }
   if (p?.type === "tool-result") {
     const out = p.output?.value ?? p.output;
@@ -8111,7 +8180,7 @@ function flattenToolHistory(messages) {
     return m;
   });
 }
-var FINAL_ANSWER_INSTRUCTION = `This is your last step for this turn. Answer the user's original question now, in plain text, using only the information gathered above. If you could not finish the task, tell the user you reached the maximum number of tool steps, summarize what you found and did so far, and say what remains \u2014 they can ask you to continue. Do not attempt any further tool calls. Write your answer as normal prose for the user: do not output tool-call syntax, JSON commands, or bracketed lines such as "[called tool ...]" \u2014 describe anything you did or still plan to do in plain language.`;
+var FINAL_ANSWER_INSTRUCTION = `This is your last step for this turn. Answer the user's original question now, in plain text, using only the information gathered above. Do not invent, estimate or "fill in" values that were not actually gathered: report only what the tools returned or what you wrote down, and name explicitly what is missing. If you could not finish the task, tell the user you reached the maximum number of tool steps, summarize what you found and did so far, and say what remains \u2014 they can ask you to continue. Do not attempt any further tool calls. Write your answer as normal prose for the user: do not output tool-call syntax, JSON commands, or bracketed lines such as "[called tool ...]" \u2014 describe anything you did or still plan to do in plain language.`;
 function finalAnswerGuard(maxSteps) {
   return ({ stepNumber, messages }) => stepNumber >= maxSteps - 1 ? {
     toolChoice: "none",
@@ -8136,6 +8205,35 @@ function retrievalBudgetGuard(limit, agenticToolKey, allToolKeys) {
   };
 }
 
+// src/exulu/resolve-reasoning-effort.ts
+var REASONING_EFFORTS = ["none", "disable", "minimal", "low", "medium", "high"];
+function resolveReasoningEffort(agent) {
+  const raw = agent?.reasoning_effort;
+  if (typeof raw !== "string") return void 0;
+  const normalized = raw.trim().toLowerCase();
+  return REASONING_EFFORTS.includes(normalized) ? normalized : void 0;
+}
+function resolveProviderOptions(agent) {
+  const effort = resolveReasoningEffort(agent);
+  return {
+    openai: { reasoningSummary: "auto" },
+    ...effort ? { litellm: { reasoningEffort: effort } } : {}
+  };
+}
+
+// src/exulu/stream-error.ts
+function onChatStreamError({ error }) {
+  const detail = error instanceof Error ? error.message : error === void 0 ? "unknown error" : safeStringify(error);
+  console.error("[EXULU] chat stream error.", detail);
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
 // src/exulu/generate-stream.ts
 var processFilePartsInMessages = async (messages, offloadCtx) => {
   const processedMessages = await Promise.all(
@@ -8229,6 +8327,15 @@ var saveChat = async ({
     await mutation;
   }
 };
+var lastMessageTime = (rows) => {
+  let latest;
+  for (const row of rows) {
+    if (!row.createdAt) continue;
+    const d = new Date(row.createdAt);
+    if (!latest || d > latest) latest = d;
+  }
+  return latest;
+};
 var getAgentMessages = async ({
   session,
   user,
@@ -8286,6 +8393,7 @@ var generateSync = async ({
   let project;
   let sessionItems;
   let sessionOwnerId;
+  let lastTurnAt;
   if (session) {
     const sessionData = await getSession({ sessionID: session });
     sessionItems = sessionData.session_items;
@@ -8300,6 +8408,7 @@ var generateSync = async ({
       session,
       user: user.id
     });
+    lastTurnAt = lastMessageTime(previousMessages);
     const previousMessagesContent = previousMessages.map(
       (message) => JSON.parse(message.content)
     );
@@ -8462,6 +8571,15 @@ var generateSync = async ({
         commands like \`node create_doc.js\`) live in the same place. These files are scoped to
         this single session; they are NOT visible in other sessions, projects, or knowledge bases.
       `;
+  if (session) {
+    const listing = await loadSessionFileListing({
+      sessionID: session,
+      ownerId: sessionOwnerId ?? user?.id ?? "api",
+      exuluConfig,
+      lastTurnAt
+    });
+    if (listing) system += "\n\n" + listing;
+  }
   system += `
 
 When a tool execution is not approved by the user, do not retry it unless explicitly asked by the user. ' +
@@ -8631,6 +8749,7 @@ var generateStream = async ({
   let project;
   let sessionItems;
   let sessionOwnerId;
+  let lastTurnAt;
   if (session) {
     const sessionData = await getSession({ sessionID: session });
     project = sessionData.project;
@@ -8646,6 +8765,7 @@ var generateStream = async ({
       includeAllUsers: isRunSessionMetadata(sessionData.metadata)
     });
     previousMessagesContent = previousMessages2.map((message2) => JSON.parse(message2.content));
+    lastTurnAt = lastMessageTime(previousMessages2);
   }
   const model = languageModel;
   messages = await validateUIMessages({
@@ -8788,6 +8908,15 @@ ${skillsList}
         truncation notice, e.g. tool-output-*.txt). Use the read_session_file tool with offset/limit
         to page through it \u2014 do not ask the user to re-upload.
       `;
+  if (session) {
+    const listing = await loadSessionFileListing({
+      sessionID: session,
+      ownerId: sessionOwnerId ?? user?.id ?? "api",
+      exuluConfig,
+      lastTurnAt
+    });
+    if (listing) system += "\n\n" + listing;
+  }
   system += `
 
 When a tool execution is not approved by the user, do not retry it unless explicitly asked by the user. ' +
@@ -8890,18 +9019,12 @@ When a tool execution is not approved by the user, do not retry it unless explic
     // for the first step or change other parameters.
     system,
     maxRetries: 2,
-    providerOptions: {
-      openai: {
-        reasoningSummary: "auto"
-      }
-    },
+    // OpenAI reasoning summaries + the agent's optional thinking budget
+    // (agents.reasoning_effort → LiteLLM reasoning_effort).
+    providerOptions: resolveProviderOptions(agent),
     tools,
-    onError: (error) => {
-      console.error("[EXULU] chat stream error.", error);
-      throw new Error(
-        `Chat stream error: ${error instanceof Error ? error.message : JSON.stringify(error)}`
-      );
-    },
+    // Log only — throwing here crashed the process (see stream-error.ts).
+    onError: onChatStreamError,
     // todo allow configuring the step budget per skill
     prepareStep: composePrepareSteps(contextGuard(contextWindow), retrievalGuard, finalAnswerGuard(turnBudget), imageAttachmentGuard()),
     stopWhen: [stepCountIs(turnBudget), hasToolCall("image_generation")]
@@ -8913,6 +9036,44 @@ When a tool execution is not approved by the user, do not retry it unless explic
   };
 };
 
+// src/utils/agent-glossary.ts
+function extractGlossaryFromAgentTools(tools) {
+  if (!Array.isArray(tools)) return [];
+  const searchTool = tools.find((t) => t?.id === "agentic_context_search");
+  const entry = searchTool?.config?.find((c) => c?.name === "vocabulary");
+  if (entry === void 0 || entry.variable === void 0 || entry.variable === null || entry.variable === "") {
+    return [];
+  }
+  try {
+    const parsed = typeof entry.variable === "string" ? JSON.parse(entry.variable) : entry.variable;
+    const glossary = parsed?.glossary;
+    if (!Array.isArray(glossary)) return [];
+    return glossary.filter(
+      (g) => !!g && typeof g.term === "string" && typeof g.meaning === "string" && g.term.trim().length > 0
+    );
+  } catch (err) {
+    console.warn(
+      "[EXULU] Failed to parse the agentic_context_search vocabulary config while building agent instructions.",
+      err
+    );
+    return [];
+  }
+}
+function formatGlossaryBlock(glossary) {
+  if (!glossary.length) return "";
+  const lines = glossary.map((g) => `${g.term} : ${g.meaning}`).join("\n");
+  return `The organization's documents and internal terminology use the following abbreviations/terms:
+${lines}`;
+}
+function withGlossary(baseInstructions, tools) {
+  const instructions = baseInstructions ?? "";
+  const block = formatGlossaryBlock(extractGlossaryFromAgentTools(tools));
+  if (!block) return instructions;
+  return instructions ? `${block}
+
+${instructions}` : block;
+}
+
 // src/exulu/agent-as-tool.ts
 var createAgentTool = async (instance, contexts) => {
   const agent = await exuluApp.get().agent(instance);
@@ -8971,7 +9132,7 @@ var createAgentTool = async (instance, contexts) => {
       const response = await generateSync({
         agent,
         contexts,
-        instructions: agent.instructions,
+        instructions: withGlossary(agent.instructions, agent.tools),
         prompt: "The user has asked the following question: " + prompt + " and the following information is available: " + information,
         languageModel: resolved.languageModel,
         user,
@@ -10744,13 +10905,7 @@ var processUiMessagesFlow = async ({
               messageMetadata: ({ part }) => {
                 console.log("[EXULU] part", part.type);
                 if (part.type === "finish") {
-                  return {
-                    totalTokens: part.totalUsage.totalTokens,
-                    reasoningTokens: part.totalUsage.reasoningTokens,
-                    inputTokens: part.totalUsage.inputTokens,
-                    outputTokens: part.totalUsage.outputTokens,
-                    cachedInputTokens: part.totalUsage.cachedInputTokens
-                  };
+                  return finishTurnMetadata({ totalUsage: part.totalUsage, startedAt: startTime });
                 }
                 return void 0;
               },
@@ -11964,7 +12119,7 @@ var recallService = {
       );
       const { text } = await generateText4({
         model: resolved.languageModel,
-        system: agent.instructions || void 0,
+        system: withGlossary(agent.instructions, agent.tools) || void 0,
         prompt: `${prompt.content}
 
 ---
@@ -16681,10 +16836,14 @@ var createExpressRoutes = async (app, tools, contexts, config, evals, tracer) =>
         }
         const approvedTools = req.body.approvedTools ? typeof req.body.approvedTools === "string" ? JSON.parse(req.body.approvedTools) : req.body.approvedTools : [];
         const customInstructions = req.body.customInstructions ? typeof req.body.customInstructions === "string" ? req.body.customInstructions : JSON.stringify(req.body.customInstructions) : "";
-        const instructions = customInstructions ? `${agent.instructions}
+        const instructions = withGlossary(
+          customInstructions ? `${agent.instructions}
 
-${customInstructions}` : agent.instructions;
+${customInstructions}` : agent.instructions,
+          agent.tools
+        );
         if (headers.session) markStreamActive(headers.session);
+        const turnStartedAt = Date.now();
         let result;
         try {
           result = await generateStream({
@@ -16726,13 +16885,7 @@ ${customInstructions}` : agent.instructions;
               };
             }
             if (part.type === "finish") {
-              return {
-                totalTokens: part.totalUsage.totalTokens,
-                reasoningTokens: part.totalUsage.reasoningTokens,
-                inputTokens: part.totalUsage.inputTokens,
-                outputTokens: part.totalUsage.outputTokens,
-                cachedInputTokens: part.totalUsage.cachedInputTokens
-              };
+              return finishTurnMetadata({ totalUsage: part.totalUsage, startedAt: turnStartedAt });
             }
             return void 0;
           },
@@ -16824,9 +16977,12 @@ ${customInstructions}` : agent.instructions;
         return;
       } else {
         const customInstructions = req.body.customInstructions ? typeof req.body.customInstructions === "string" ? req.body.customInstructions : JSON.stringify(req.body.customInstructions) : "";
-        const instructions = customInstructions ? `${agent.instructions}
+        const instructions = withGlossary(
+          customInstructions ? `${agent.instructions}
 
-${customInstructions}` : agent.instructions;
+${customInstructions}` : agent.instructions,
+          agent.tools
+        );
         let response;
         try {
           response = await generateSync({
@@ -24151,7 +24307,7 @@ function reconstructTableHeaders(document, validationResults, verbose = false) {
   }
 }
 async function validateWithVLM(document, model, verbose = false, concurrency = 10) {
-  console.log(`[EXULU] Starting VLM validation for docling output, ${document.length} pages...`);
+  console.log(`[EXULU] Starting VLM validation for processor output, ${document.length} pages...`);
   console.log(`[EXULU] Concurrency limit: ${concurrency}`);
   const limit = pLimit(concurrency);
   const validationResults = /* @__PURE__ */ new Map();
@@ -24286,48 +24442,7 @@ async function processDocument(filePath, fileType, buffer, tempDir, config, verb
 async function processPdf(buffer, paths, config, verbose = false) {
   try {
     let json = [];
-    if (config?.processor.name === "docling") {
-      console.log(`[EXULU] Validating Python environment...`);
-      const validation = await validatePythonEnvironment(void 0, true);
-      if (!validation.valid) {
-        console.log(`[EXULU] Python environment not ready, setting up automatically...`);
-        console.log(`[EXULU] Reason: ${validation.message}`);
-        const setupResult = await setupPythonEnvironment({
-          verbose: true,
-          force: false
-          // Only setup if not already done
-        });
-        if (!setupResult.success) {
-          throw new Error(`Failed to setup Python environment: ${setupResult.message}
-
-${setupResult.output || ""}`);
-        }
-        console.log(`[EXULU] Python environment setup completed successfully`);
-      } else {
-        console.log(`[EXULU] Python environment is valid`);
-      }
-      console.log(`[EXULU] Processing document with document_to_markdown.py`);
-      const result = await executePythonScript({
-        scriptPath: "ee/python/documents/processing/document_to_markdown.py",
-        args: [
-          paths.source,
-          "-o",
-          paths.json,
-          "--images-dir",
-          paths.images
-        ],
-        timeout: 30 * 60 * 1e3
-        // 30 minutes for large documents
-      });
-      if (result.stderr) {
-        console.log("Processing info:", result.stderr.trim());
-      }
-      if (!result.success) {
-        throw new Error(`Document processing failed: ${result.stderr}`);
-      }
-      const jsonContent = await fs3.promises.readFile(paths.json, "utf-8");
-      json = JSON.parse(jsonContent);
-    } else if (config?.processor.name === "officeparser") {
+    if (config?.processor.name === "officeparser") {
       const text = await parseOfficeAsync2(buffer, {
         outputErrorToConsole: false,
         newlineDelimiter: "\n"
@@ -24418,14 +24533,16 @@ stderr: ${splitResult.stderr.slice(-1e3)}`
         image: screenshots.find((s) => s.pageNum === page.pageNum)?.imagePath
       }));
       fs3.writeFileSync(paths.json, JSON.stringify(json, null, 2));
+    } else {
+      const configured = String(config?.processor?.name ?? "");
+      throw new Error(
+        configured === "" ? "[EXULU] No document processor configured. Set processor.name to one of: mistral, liteparse, officeparser." : `[EXULU] Unknown document processor "${configured}". Supported processors are: mistral, liteparse, officeparser.` + (configured === "docling" ? ' The "docling" processor was removed: it depended on PyMuPDF, which is AGPL-licensed. Use "mistral" for PDF OCR.' : "")
+      );
     }
     console.log(`[EXULU] 
 \u2713 Document processing completed successfully`);
     console.log(`[EXULU] Total pages: ${json.length}`);
     console.log(`[EXULU] Output file: ${paths.json}`);
-    if (config?.vlm?.model) {
-      console.error("[EXULU] VLM validation is only supported when docling is enabled, skipping validation.");
-    }
     const vlmModel = config?.vlm?.model ? await resolveVlmModel(config) : void 0;
     if (vlmModel && json.length > 0) {
       json = await validateWithVLM(
@@ -24543,9 +24660,6 @@ async function documentProcessor({
     } = await loadFile(file, name, tempDir);
     let supportedTypes = [];
     switch (config?.processor.name) {
-      case "docling":
-        supportedTypes = ["pdf", "docx", "doc", "txt", "md", "jpg", "jpeg", "png", "gif", "webp"];
-        break;
       case "officeparser":
         supportedTypes = ["docx", "pptx", "xlsx", "odt", "odp", "ods", "pdf", "rtf", "csv", "md", "html"];
         break;