@exulu/backend 3.7.3 → 4.0.0

package/dist/index.cjs

@@ -3727,6 +3727,40 @@ Current item: ${JSON.stringify(summary)}`
   }
 });
 
+// ee/invoke-skills/artifact-filter.ts
+function isIgnoredArtifactPath(relativePath) {
+  return relativePath.split(/[\\/]+/).some((segment) => IGNORED_SEGMENTS.has(segment));
+}
+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;
+}
+var IGNORED_SEGMENTS, DEFAULT_ARTIFACT_CAP;
+var init_artifact_filter = __esm({
+  "ee/invoke-skills/artifact-filter.ts"() {
+    "use strict";
+    init_cjs_shims();
+    IGNORED_SEGMENTS = /* @__PURE__ */ new Set([
+      "venv",
+      ".venv",
+      "env",
+      "node_modules",
+      "__pycache__",
+      "site-packages",
+      "dist-packages",
+      ".cache",
+      ".git",
+      ".pytest_cache",
+      ".mypy_cache",
+      ".ipynb_checkpoints"
+    ]);
+    DEFAULT_ARTIFACT_CAP = 50;
+  }
+});
+
 // src/exulu/system-dependencies.ts
 async function getNpmGlobalRoot() {
   if (cachedNpmGlobalRoot !== void 0) return cachedNpmGlobalRoot;
@@ -3856,6 +3890,229 @@ var init_variable = __esm({
   }
 });
 
+// src/utils/python-setup.ts
+var python_setup_exports = {};
+__export(python_setup_exports, {
+  getPackageRoot: () => getPackageRoot,
+  getPythonSetupInstructions: () => getPythonSetupInstructions,
+  getPythonVenvPath: () => getPythonVenvPath,
+  isPythonEnvironmentSetup: () => isPythonEnvironmentSetup,
+  setupPythonEnvironment: () => setupPythonEnvironment,
+  validatePythonEnvironment: () => validatePythonEnvironment
+});
+function getPackageRoot() {
+  const currentFile = (0, import_url.fileURLToPath)(importMetaUrl);
+  let currentDir = (0, import_path.dirname)(currentFile);
+  let attempts = 0;
+  const maxAttempts = 10;
+  while (attempts < maxAttempts) {
+    const packageJsonPath = (0, import_path.join)(currentDir, "package.json");
+    if ((0, import_fs.existsSync)(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse((0, import_fs.readFileSync)(packageJsonPath, "utf-8"));
+        if (packageJson.name === "@exulu/backend") {
+          return currentDir;
+        }
+      } catch {
+      }
+    }
+    const parentDir = (0, import_path.resolve)(currentDir, "..");
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+    attempts++;
+  }
+  const fallback = (0, import_path.resolve)((0, import_path.dirname)((0, import_url.fileURLToPath)(importMetaUrl)), "../..");
+  return fallback;
+}
+function getSetupScriptPath(packageRoot) {
+  return (0, import_path.resolve)(packageRoot, "ee/python/setup.sh");
+}
+function getVenvPath(packageRoot) {
+  return (0, import_path.resolve)(packageRoot, "ee/python/.venv");
+}
+function getPythonVenvPath(packageRoot) {
+  const root = packageRoot ?? getPackageRoot();
+  return isPythonEnvironmentSetup(root) ? getVenvPath(root) : void 0;
+}
+function isPythonEnvironmentSetup(packageRoot) {
+  const root = packageRoot ?? getPackageRoot();
+  const venvPath = getVenvPath(root);
+  const pythonPath = (0, import_path.join)(venvPath, "bin", "python");
+  return (0, import_fs.existsSync)(venvPath) && (0, import_fs.existsSync)(pythonPath);
+}
+async function setupPythonEnvironment(options = {}) {
+  const {
+    packageRoot = getPackageRoot(),
+    force = false,
+    verbose = false,
+    timeout = 6e5
+    // 10 minutes
+  } = options;
+  if (!force && isPythonEnvironmentSetup(packageRoot)) {
+    if (verbose) {
+      console.log("\u2713 Python environment already set up");
+    }
+    return {
+      success: true,
+      message: "Python environment already exists",
+      alreadyExists: true
+    };
+  }
+  const setupScriptPath = getSetupScriptPath(packageRoot);
+  if (!(0, import_fs.existsSync)(setupScriptPath)) {
+    return {
+      success: false,
+      message: `Setup script not found at: ${setupScriptPath}`,
+      alreadyExists: false
+    };
+  }
+  try {
+    if (verbose) {
+      console.log("Setting up Python environment...");
+    }
+    const { stdout, stderr } = await execAsync2(`bash "${setupScriptPath}"`, {
+      cwd: packageRoot,
+      timeout,
+      env: {
+        ...process.env,
+        // Ensure script can write to the directory
+        PYTHONDONTWRITEBYTECODE: "1"
+      },
+      maxBuffer: 10 * 1024 * 1024
+      // 10MB buffer
+    });
+    const output = stdout + stderr;
+    const versionMatch = output.match(/Python (\d+\.\d+\.\d+)/);
+    const pythonVersion = versionMatch ? versionMatch[1] : void 0;
+    if (verbose) {
+      console.log(output);
+    }
+    return {
+      success: true,
+      message: "Python environment set up successfully",
+      alreadyExists: false,
+      pythonVersion,
+      output
+    };
+  } catch (error) {
+    const errorOutput = error.stdout + error.stderr;
+    return {
+      success: false,
+      message: `Setup failed: ${error.message}`,
+      alreadyExists: false,
+      output: errorOutput
+    };
+  }
+}
+function getPythonSetupInstructions() {
+  return `
+Python environment not set up. Please run one of the following commands:
+
+Option 1 (Automatic):
+  import { setupPythonEnvironment } from '@exulu/backend';
+  await setupPythonEnvironment();
+
+Option 2 (Manual - for package consumers):
+  npx @exulu/backend setup-python
+
+Option 3 (Manual - for contributors):
+  npm run python:setup
+
+These commands will automatically create a Python virtual environment (.venv)
+in the @exulu/backend package and install all required dependencies.
+
+Requirements:
+  - Python 3.10 or higher must be installed
+  - pip must be available
+  - venv module must be available (for creating virtual environments)
+
+If Python dependencies are not installed, install them first, then run one of the commands above:
+  - macOS: brew install python@3.12
+  - Ubuntu/Debian: sudo apt-get install python3.12 python3-pip python3-venv
+  - Alpine Linux: apk add python3 py3-pip python3-dev
+  - Windows: Download from https://www.python.org/downloads/
+
+Note: In Docker containers, ensure you install all three components:
+  Ubuntu/Debian: apt-get install -y python3 python3-pip python3-venv
+  Alpine: apk add python3 py3-pip python3-dev
+`.trim();
+}
+async function validatePythonEnvironment(packageRoot, checkPackages = true) {
+  const root = packageRoot ?? getPackageRoot();
+  const venvPath = getVenvPath(root);
+  const pythonPath = (0, import_path.join)(venvPath, "bin", "python");
+  if (!(0, import_fs.existsSync)(venvPath)) {
+    return {
+      valid: false,
+      message: getPythonSetupInstructions()
+    };
+  }
+  if (!(0, import_fs.existsSync)(pythonPath)) {
+    return {
+      valid: false,
+      message: "Python virtual environment is corrupted. Please run:\n  await setupPythonEnvironment({ force: true })"
+    };
+  }
+  try {
+    await execAsync2(`"${pythonPath}" --version`, { cwd: root });
+  } catch {
+    return {
+      valid: false,
+      message: "Python executable is not working. Please run:\n  await setupPythonEnvironment({ force: true })"
+    };
+  }
+  if (checkPackages) {
+    const criticalPackages = ["pypdf", "transformers"];
+    const missingPackages = [];
+    for (const pkg of criticalPackages) {
+      try {
+        await execAsync2(`"${pythonPath}" -c "import ${pkg}"`, {
+          cwd: root,
+          timeout: 1e4
+          // 10 second timeout per import check
+        });
+      } catch {
+        missingPackages.push(pkg);
+      }
+    }
+    if (missingPackages.length > 0) {
+      return {
+        valid: false,
+        message: `Python environment exists but required packages are not installed: ${missingPackages.join(", ")}
+
+This usually happens when:
+1. The .venv folder was copied but dependencies were not installed
+2. The package was installed via npm but setup script was not run
+
+Please run:
+  await setupPythonEnvironment({ force: true })
+
+Or manually run the setup script:
+  bash ` + getSetupScriptPath(root)
+      };
+    }
+  }
+  return {
+    valid: true,
+    message: "Python environment is valid"
+  };
+}
+var import_child_process, import_util, import_path, import_fs, import_url, execAsync2;
+var init_python_setup = __esm({
+  "src/utils/python-setup.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_child_process = require("child_process");
+    import_util = require("util");
+    import_path = require("path");
+    import_fs = require("fs");
+    import_url = require("url");
+    execAsync2 = (0, import_util.promisify)(import_child_process.exec);
+  }
+});
+
 // ee/invoke-skills/create-sandbox.ts
 function probeSandboxSupport() {
   if (sandboxProbePromise) return sandboxProbePromise;
@@ -3941,7 +4198,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 {
@@ -3961,7 +4218,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 = (0, import_node_path4.join)(sessionDir, relativePath);
+    if (opts.onlyMissing) {
+      let localSize;
+      try {
+        localSize = (await (0, import_promises.stat)(localPath)).size;
+      } catch {
+        localSize = void 0;
+      }
+      if (!needsDownload(localSize, obj.size)) continue;
+    }
     try {
       const bytes = await getS3ObjectBytes(obj.key, config);
       await (0, import_promises.mkdir)((0, import_node_path4.dirname)(localPath), { recursive: true });
@@ -3995,6 +4262,15 @@ async function downloadKeyIntoSandbox(opts) {
   await (0, import_promises.writeFile)(localPath, bytes);
   return { written: true, localPath };
 }
+async function resolvePythonVenvPath() {
+  try {
+    const { getPythonVenvPath: getPythonVenvPath2 } = await Promise.resolve().then(() => (init_python_setup(), python_setup_exports));
+    return getPythonVenvPath2();
+  } 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) {
@@ -4008,6 +4284,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 = (0, import_node_path4.join)("/tmp", "exulu-sessions", sessionId);
@@ -4025,8 +4308,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;
@@ -4061,6 +4344,7 @@ Probe error: ${probe.reason ?? "(no detail)"}`
     await import_sandbox_runtime.SandboxManager.initialize(baselineSandboxConfig);
   }
   const npmGlobalRoot = await getNpmGlobalRoot();
+  const pythonVenvPath = await resolvePythonVenvPath();
   const sessionSandboxConfig = {
     network: {
       allowedDomains: [],
@@ -4075,7 +4359,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: []
@@ -4093,7 +4378,8 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   const sandboxedExecEnv = {
     ...configuredVariables,
     ...process.env,
-    ...npmGlobalRoot ? { NODE_PATH: npmGlobalRoot } : {}
+    ...npmGlobalRoot ? { NODE_PATH: npmGlobalRoot } : {},
+    ...pythonVenvPath ? { PATH: `${(0, import_node_path4.join)(pythonVenvPath, "bin")}:${process.env.PATH ?? ""}`, VIRTUAL_ENV: pythonVenvPath } : {}
   };
   const wrapIfNeeded = async (command) => {
     if (useDirectExec) return command;
@@ -4102,7 +4388,7 @@ Probe error: ${probe.reason ?? "(no detail)"}`
   const runWrapped = async (command) => {
     const wrapped = await wrapIfNeeded(command);
     try {
-      const { stdout, stderr } = await execAsync2(wrapped, {
+      const { stdout, stderr } = await execAsync3(wrapped, {
         maxBuffer: EXEC_MAX_BUFFER,
         shell: "/bin/bash",
         env: sandboxedExecEnv
@@ -4218,6 +4504,7 @@ Probe error: ${probe.reason ?? "(no detail)"}`
       for (const entry of entries) {
         const full = (0, import_node_path4.join)(dir, entry.name);
         if (full === skillsDir) continue;
+        if (isIgnoredArtifactPath((0, import_node_path4.relative)(sessionDir, full))) continue;
         if (entry.isDirectory()) {
           await walk(full);
         } else if (entry.isFile()) {
@@ -4313,19 +4600,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 } : {}
       };
     }
   });
@@ -4345,7 +4637,7 @@ ${lines.join("\n")}`;
   sandboxCache.set(sessionId, { handle, installedSkills });
   return handle;
 }
-var import_sandbox_runtime, import_promises, import_node_fs5, import_node_path4, import_node_child_process3, import_node_util2, import_bash_tool, import_ai2, import_zod6, import_crypto_js3, getAllExuluVariables, execAsync2, EXEC_MAX_BUFFER, sandboxProbePromise, SANDBOX_FALLBACK_INSTRUCTIONS, degradedModeLogged, sandboxCache;
+var import_sandbox_runtime, import_promises, import_node_fs5, import_node_path4, import_node_child_process3, import_node_util2, import_bash_tool, import_ai2, import_zod6, import_crypto_js3, getAllExuluVariables, execAsync3, EXEC_MAX_BUFFER, sandboxProbePromise, SANDBOX_FALLBACK_INSTRUCTIONS, degradedModeLogged, sandboxCache;
 var init_create_sandbox = __esm({
   "ee/invoke-skills/create-sandbox.ts"() {
     "use strict";
@@ -4357,6 +4649,7 @@ var init_create_sandbox = __esm({
     import_node_child_process3 = require("child_process");
     import_node_util2 = require("util");
     init_uppy();
+    init_artifact_filter();
     init_system_dependencies();
     import_bash_tool = require("bash-tool");
     import_ai2 = require("ai");
@@ -4390,7 +4683,7 @@ var init_create_sandbox = __esm({
       }
       return out;
     };
-    execAsync2 = (0, import_node_util2.promisify)(import_node_child_process3.exec);
+    execAsync3 = (0, import_node_util2.promisify)(import_node_child_process3.exec);
     EXEC_MAX_BUFFER = 32 * 1024 * 1024;
     SANDBOX_FALLBACK_INSTRUCTIONS = 'Skill sandboxing is running in DEGRADED mode: bwrap cannot create user namespaces on this host, so commands\nexecute directly. The container remains the isolation boundary and resolveSessionPath still scopes\nreadFile/writeFile to the session directory at the JS layer, but bash commands are NOT kernel-sandboxed.\n\nTo restore full sandboxing on Ubuntu 23.10+ / 24.04+ hosts (kernel 6.5+):\n  sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0\n  echo "kernel.apparmor_restrict_unprivileged_userns=0" | sudo tee /etc/sysctl.d/60-userns.conf\n  sudo sysctl --system\n\nOn Debian hosts where the same symptom appears:\n  sudo sysctl -w kernel.unprivileged_userns_clone=1\n\nSet EXULU_REQUIRE_SANDBOX=1 to fail startup instead of degrading.';
     degradedModeLogged = false;
@@ -4629,6 +4922,18 @@ var init_auth_tool_model_output = __esm({
   }
 });
 
+// src/exulu/session-files.ts
+function sessionFilePrefix(ownerId, sessionId, s3prefix) {
+  const general = s3prefix ? `${s3prefix.replace(/\/+$/, "")}/` : "";
+  return `${general}user_${ownerId}/sessions/${sessionId}/`;
+}
+var init_session_files = __esm({
+  "src/exulu/session-files.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
 // src/templates/tools/session-file-read-tool.ts
 var import_zod7, DEFAULT_LIMIT, MAX_CONTENT_CHARS, createSessionFileReadTool;
 var init_session_file_read_tool = __esm({
@@ -4636,6 +4941,7 @@ var init_session_file_read_tool = __esm({
     "use strict";
     init_cjs_shims();
     import_zod7 = require("zod");
+    init_session_files();
     init_tool();
     init_uppy();
     DEFAULT_LIMIT = 250;
@@ -4643,7 +4949,8 @@ var init_session_file_read_tool = __esm({
     createSessionFileReadTool = ({
       sessionID,
       user,
-      exuluConfig
+      exuluConfig,
+      ownerId
     }) => {
       if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
       const readSessionFileExecute = async ({ filename, offset, limit }) => {
@@ -4654,8 +4961,7 @@ var init_session_file_read_tool = __esm({
           };
         }
         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);
@@ -4759,6 +5065,18 @@ var init_document_render_helpers = __esm({
 });
 
 // src/templates/tools/parse-document-tool.ts
+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 import_zod8, import_node_path6, import_officeparser, DEFAULT_LIMIT2, MAX_CONTENT_CHARS2, MIN_CHARS_PER_PAGE, OFFICE_EXTENSIONS, pagesPattern, createParseDocumentTool;
 var init_parse_document_tool = __esm({
   "src/templates/tools/parse-document-tool.ts"() {
@@ -4770,6 +5088,7 @@ var init_parse_document_tool = __esm({
     init_tool();
     init_uppy();
     init_document_render_helpers();
+    init_session_files();
     DEFAULT_LIMIT2 = 250;
     MAX_CONTENT_CHARS2 = 16e3;
     MIN_CHARS_PER_PAGE = 20;
@@ -4789,7 +5108,8 @@ var init_parse_document_tool = __esm({
     createParseDocumentTool = ({
       sessionID,
       user,
-      exuluConfig
+      exuluConfig,
+      ownerId
     }) => {
       if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
       const parseDocumentExecute = async ({
@@ -4814,8 +5134,7 @@ var init_parse_document_tool = __esm({
           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);
@@ -4830,6 +5149,11 @@ var init_parse_document_tool = __esm({
             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.`
@@ -4928,7 +5252,7 @@ async function getPdfPreviewBytes(opts) {
         const bytes = await getS3ObjectBytes(sourceKey, config);
         await (0, import_promises3.writeFile)(inputPath, bytes);
         try {
-          await execAsync3(
+          await execAsync4(
             `soffice --headless --convert-to pdf "${inputPath}" --outdir "${CACHE_OUT}"`,
             { timeout: 6e4, maxBuffer: 16 * 1024 * 1024 }
           );
@@ -4954,7 +5278,7 @@ async function getPdfPreviewBytes(opts) {
   inFlight.set(safeEtag, promise);
   return promise;
 }
-var import_node_child_process5, import_node_fs6, import_promises3, import_node_path7, import_node_util4, execAsync3, CACHE_ROOT, CACHE_IN, CACHE_OUT, inFlight, PreviewRenderError;
+var import_node_child_process5, import_node_fs6, import_promises3, import_node_path7, import_node_util4, execAsync4, CACHE_ROOT, CACHE_IN, CACHE_OUT, inFlight, PreviewRenderError;
 var init_pdf_preview_cache = __esm({
   "src/sessions/pdf-preview-cache.ts"() {
     "use strict";
@@ -4965,7 +5289,7 @@ var init_pdf_preview_cache = __esm({
     import_node_path7 = require("path");
     import_node_util4 = require("util");
     init_uppy();
-    execAsync3 = (0, import_node_util4.promisify)(import_node_child_process5.exec);
+    execAsync4 = (0, import_node_util4.promisify)(import_node_child_process5.exec);
     CACHE_ROOT = "/tmp/exulu-pdf-cache";
     CACHE_IN = (0, import_node_path7.join)(CACHE_ROOT, "_in");
     CACHE_OUT = (0, import_node_path7.join)(CACHE_ROOT, "_out");
@@ -5165,6 +5489,7 @@ var init_view_document_page_tool = __esm({
     "use strict";
     init_cjs_shims();
     import_zod9 = require("zod");
+    init_session_files();
     import_node_path8 = require("path");
     init_tool();
     init_uppy();
@@ -5197,7 +5522,8 @@ var init_view_document_page_tool = __esm({
     createViewDocumentPageTool = ({
       sessionID,
       user,
-      exuluConfig
+      exuluConfig,
+      ownerId
     }) => {
       if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
       const viewDocumentPageExecute = async ({ filename, page, model }, options) => {
@@ -5230,8 +5556,7 @@ var init_view_document_page_tool = __esm({
           }
         }
         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;
@@ -5305,13 +5630,13 @@ var init_view_document_page_tool = __esm({
 });
 
 // src/exulu/audit/config.ts
-var import_os, import_path, normalizePrefix, hasAllS3Fields, resolveAuditConfig;
+var import_os, import_path2, normalizePrefix, hasAllS3Fields, resolveAuditConfig;
 var init_config = __esm({
   "src/exulu/audit/config.ts"() {
     "use strict";
     init_cjs_shims();
     import_os = __toESM(require("os"), 1);
-    import_path = __toESM(require("path"), 1);
+    import_path2 = __toESM(require("path"), 1);
     normalizePrefix = (p) => {
       const raw = (p ?? "audit").trim().replace(/^\/+|\/+$/g, "");
       return `${raw || "audit"}/`;
@@ -5343,7 +5668,7 @@ var init_config = __esm({
         retentionDays: a.retentionDays,
         manageLifecycle: a.manageLifecycle ?? !usingSharedFileUploadsBucket,
         usingSharedFileUploadsBucket,
-        spoolDir: a.spoolDir ?? import_path.default.join(import_os.default.tmpdir(), "exulu-audit-spool"),
+        spoolDir: a.spoolDir ?? import_path2.default.join(import_os.default.tmpdir(), "exulu-audit-spool"),
         flush: {
           maxRecords: a.flush?.maxRecords ?? 100,
           maxIntervalMs: a.flush?.maxIntervalMs ?? 5e3
@@ -5464,29 +5789,29 @@ ${JSON.stringify(config, null, 2)}`
 });
 
 // src/exulu/audit/sink.ts
-var import_crypto2, import_fs, import_path2, createFsSpoolStore, pad, AuditSink;
+var import_crypto2, import_fs2, import_path3, createFsSpoolStore, pad, AuditSink;
 var init_sink = __esm({
   "src/exulu/audit/sink.ts"() {
     "use strict";
     init_cjs_shims();
     import_crypto2 = require("crypto");
-    import_fs = require("fs");
-    import_path2 = __toESM(require("path"), 1);
+    import_fs2 = require("fs");
+    import_path3 = __toESM(require("path"), 1);
     createFsSpoolStore = (dir) => ({
       write: async (name, body) => {
-        await import_fs.promises.mkdir(dir, { recursive: true });
-        await import_fs.promises.writeFile(import_path2.default.join(dir, name), body, "utf8");
+        await import_fs2.promises.mkdir(dir, { recursive: true });
+        await import_fs2.promises.writeFile(import_path3.default.join(dir, name), body, "utf8");
       },
       list: async () => {
         try {
-          return (await import_fs.promises.readdir(dir)).filter((f) => f.endsWith(".ndjson"));
+          return (await import_fs2.promises.readdir(dir)).filter((f) => f.endsWith(".ndjson"));
         } catch {
           return [];
         }
       },
-      read: async (name) => import_fs.promises.readFile(import_path2.default.join(dir, name), "utf8"),
+      read: async (name) => import_fs2.promises.readFile(import_path3.default.join(dir, name), "utf8"),
       remove: async (name) => {
-        await import_fs.promises.rm(import_path2.default.join(dir, name), { force: true });
+        await import_fs2.promises.rm(import_path3.default.join(dir, name), { force: true });
       }
     });
     pad = (n) => String(n).padStart(2, "0");
@@ -6032,7 +6357,7 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
       await Promise.all(promises2);
       return tool4;
     };
-    convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approvedTools, allExuluTools, configs, contexts, user, exuluConfig, sessionID, req, project, sessionItems, model, agent, memoryItems, contextWindow, disabledTools) => {
+    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 = [];
@@ -6049,7 +6374,7 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
             sessionID,
             currentSkills || [],
             exuluConfig,
-            user?.id
+            sessionOwnerId ?? user?.id
           );
         } catch (err) {
           console.error(
@@ -6114,15 +6439,15 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
           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);
       }
@@ -6826,7 +7151,19 @@ var init_config2 = __esm({
       pinBoost: import_zod11.z.number().min(0).max(1).default(0.15),
       identifierBoost: import_zod11.z.number().min(0).max(1).default(0.15),
       pageWindow: import_zod11.z.number().int().min(0).default(1),
-      maxQueriesPerContext: import_zod11.z.number().int().positive().default(5)
+      maxQueriesPerContext: import_zod11.z.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: import_zod11.z.enum(["v1", "v2"]).default("v1"),
+      /** v2 sub-features; each can be switched off on its own to bisect a regression. */
+      v2: import_zod11.z.object({
+        mergedMemoryCall: import_zod11.z.boolean().default(true),
+        mergedRoutingCall: import_zod11.z.boolean().default(true),
+        parallelPins: import_zod11.z.boolean().default(true)
+      }).default({ mergedMemoryCall: true, mergedRoutingCall: true, parallelPins: true })
     });
     boolVal = (v) => v === true || v === "true" || v === 1;
     strVal = (v, fallback) => typeof v === "string" && v.length > 0 ? v : fallback;
@@ -6921,6 +7258,23 @@ var init_micro_call = __esm({
   }
 });
 
+// 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);
+  }
+}
+var init_timing = __esm({
+  "ee/agentic-retrieval/pipeline/timing.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
 // ee/agentic-retrieval/pipeline/text-utils.ts
 function extractIdentifierTokens(parts) {
   const tokens = /* @__PURE__ */ new Set();
@@ -7228,6 +7582,49 @@ If the question references none, return hasMatches false and an empty array.`;
 });
 
 // ee/agentic-retrieval/pipeline/routing.ts
+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 = import_zod13.z.object({
+    docPage: import_zod13.z.object({
+      hasFilenameHint: import_zod13.z.boolean(),
+      filenameHints: import_zod13.z.array(import_zod13.z.string()).optional(),
+      hasPageHint: import_zod13.z.boolean(),
+      pageNumber: import_zod13.z.number().int().nullable().optional()
+    }),
+    explicitlyRequestedKnowledgeBases: import_zod13.z.array(import_zod13.z.enum(ids)),
+    ...routingRules.length ? {
+      classification: import_zod13.z.object({
+        ruleId: import_zod13.z.enum(routingRules.map((r) => r.id)),
+        reason: import_zod13.z.string()
+      })
+    } : {}
+  });
+  const { output } = await microCall({ model, system, messages: [{ role: "user", content: question }], schema });
+  return output;
+}
 async function runRoutingPhase(opts) {
   const {
     question,
@@ -7237,6 +7634,7 @@ async function runRoutingPhase(opts) {
     preselectedItems,
     extraInstructions,
     knownIdentifiers = [],
+    mergedCall = false,
     model
   } = opts;
   try {
@@ -7256,7 +7654,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({
@@ -7298,7 +7712,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) {
@@ -7376,7 +7790,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 }],
@@ -7384,7 +7798,7 @@ ${extraInstructions}
             ruleId: import_zod13.z.enum(ruleIds),
             reason: import_zod13.z.string()
           })
-        });
+        }));
         const matchedRule = routingRules.find((r) => r.id === classified.ruleId);
         if (matchedRule) {
           const main = matchedRule.main.filter((id) => enabledIds.has(id));
@@ -7444,6 +7858,7 @@ var init_routing = __esm({
     init_cjs_shims();
     import_zod13 = require("zod");
     init_micro_call();
+    init_timing();
     init_prefilter();
     init_text_utils();
     MAX_USER_PIN_MATCHES = 8;
@@ -7585,7 +8000,8 @@ async function recallMemoryByKeywords({
   importantKeyword,
   user,
   role,
-  memoryContext
+  memoryContext,
+  timings
 }) {
   const allKeywords = [
     ...new Set(
@@ -7602,7 +8018,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(
@@ -7624,14 +8040,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 = []) {
@@ -7645,7 +8061,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: import_zod14.z.object({
+      relevantChunkIds: import_zod14.z.array(import_zod14.z.string()).describe("chunk_ids (UUIDs at the start of each bullet) of relevant chunks; empty array if none."),
+      override: import_zod14.z.object({
+        overrides: import_zod14.z.boolean().describe("True ONLY if a chunk directly and sufficiently answers the question."),
+        confidence: import_zod14.z.enum(["high", "medium", "low"]),
+        authoritativeChunkIds: import_zod14.z.array(import_zod14.z.string()).describe("chunk_ids that directly answer the question; empty if overrides is false."),
+        reason: import_zod14.z.string().describe("One short sentence.")
+      }),
+      filePrioritization: import_zod14.z.object({
+        shouldPrioritizeFiles: import_zod14.z.boolean(),
+        fileNameHints: import_zod14.z.array(import_zod14.z.string()).optional()
+      }),
+      augmentation: import_zod14.z.object({
+        updatedUserQuestion: import_zod14.z.string(),
+        updatedRelevantKeywords: import_zod14.z.array(import_zod14.z.string()),
+        updatedImportantKeyword: import_zod14.z.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,
@@ -7656,7 +8168,8 @@ async function runMemoryPhase({
   model,
   memoryConfig,
   glossary,
-  documentContexts
+  documentContexts,
+  mergedCall = false
 }) {
   try {
     if (!memoryConfig.enabled || memoryChunks.length === 0 && !memoryContext) {
@@ -7666,13 +8179,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));
@@ -7697,8 +8211,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: [
@@ -7716,7 +8246,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) {
@@ -7806,7 +8336,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,
@@ -7887,7 +8417,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)
@@ -7966,6 +8496,7 @@ var init_memory = __esm({
     init_cjs_shims();
     import_zod14 = require("zod");
     init_micro_call();
+    init_timing();
     init_multi_query();
     init_prefilter();
     init_text_utils();
@@ -8087,7 +8618,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 [];
@@ -8125,13 +8656,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,
@@ -8146,14 +8677,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;
@@ -8168,7 +8699,7 @@ async function searchContexts(opts) {
         console.warn(`[EXULU pipeline] searchContexts failed for context "${ctxId}":`, err);
         return [];
       }
-    })
+    }))
   );
   return { chunks: chunkArrays.flat() };
 }
@@ -8181,6 +8712,7 @@ var init_search = __esm({
     init_multi_query();
     init_hyde();
     init_prefilter();
+    init_timing();
     init_text_utils();
     tagContext = (chunks, ctx) => chunks.map((c) => ({ ...c, context: { id: ctx.id, name: ctx.name ?? ctx.id } }));
   }
@@ -8334,6 +8866,33 @@ var init_rerank = __esm({
   }
 });
 
+// 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;
+}
+var init_pin_rerun = __esm({
+  "ee/agentic-retrieval/pipeline/pin-rerun.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
 // ee/agentic-retrieval/pipeline/index.ts
 function addChunks(result, chunks) {
   const seen = new Set(result.chunks.map((c) => c.chunk_id));
@@ -8499,6 +9058,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
@@ -8571,8 +9138,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,
@@ -8584,8 +9162,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,
@@ -8596,8 +9176,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,
@@ -8647,13 +9231,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,
@@ -8683,6 +9262,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({
@@ -8703,9 +9284,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;
@@ -8768,6 +9352,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) => {
@@ -8816,6 +9401,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) {
@@ -8838,9 +9424,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);
@@ -8875,6 +9471,8 @@ var init_pipeline = __esm({
     init_prefilter();
     init_search();
     init_rerank();
+    init_timing();
+    init_pin_rerun();
     init_global_ids();
     init_global_ids();
   }
@@ -10283,6 +10881,68 @@ 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
+init_cjs_shims();
+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/apply-sorting.ts
 init_cjs_shims();
@@ -11273,6 +11933,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",
@@ -11990,6 +12658,15 @@ var convertContextToTableDefinition = (context) => {
 // src/graphql/resolvers/vector-search.ts
 init_statistics2();
 
+// src/graphql/resolvers/query-embedding-policy.ts
+init_cjs_shims();
+function needsQueryEmbedding(method) {
+  return method !== "tsvector";
+}
+function boostsWithQueryEntities(method) {
+  return method !== "tsvector";
+}
+
 // src/exulu/entities/index.ts
 init_cjs_shims();
 init_client();
@@ -12770,7 +13447,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 {
@@ -12803,8 +13482,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) {
@@ -12862,14 +13543,22 @@ var vectorSearch = async ({
       ]);
       resultChunks = await chunksQuery;
       break;
-    case "hybridSearch":
+    case "hybridSearch": {
+      let strictMatches = false;
+      if (query && hybridOrQuery) {
+        const probe = await db2(chunksTable + " as chunks").select(db2.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 = db2(chunksTable + " as chunks").select([
         "chunks.id",
@@ -12910,7 +13599,7 @@ var vectorSearch = async ({
         db2.raw('items."updatedAt" as item_updated_at'),
         db2.raw('items."createdAt" as item_created_at'),
         db2.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)
         ),
         db2.raw(`(1 - (chunks.embedding <=> ${vectorExpr})) AS cosine_distance`),
@@ -12936,12 +13625,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(
@@ -12993,7 +13684,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({
@@ -13012,117 +13703,31 @@ var vectorSearch = async ({
         const max = Math.max(...scores);
         const range = max - min;
         const boostWeight = context.entities?.boostWeight ?? 0.3;
-        results = results.map((r, i) => {
-          const base = range > 0 ? ((scores[i] ?? 0) - min) / range : 1;
-          const shared = sharedCounts.get(r.chunk_id) || 0;
-          const boost = boostWeight * (shared / (shared + 1));
-          return { r, score: base + boost };
-        }).sort((a, b) => b.score - a.score).map((x) => x.r);
-      }
-    } catch (err) {
-      console.error("[EXULU] Entity boost step failed (continuing):", err.message);
-    }
-  }
-  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 db2(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 || ""
-                  }
-                });
-              }
-            }
-          })
-        );
-      }
-    }
-    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 db2(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 = results.map((r, i) => {
+          const base = range > 0 ? ((scores[i] ?? 0) - min) / range : 1;
+          const shared = sharedCounts.get(r.chunk_id) || 0;
+          const boost = boostWeight * (shared / (shared + 1));
+          return { r, score: base + boost };
+        }).sort((a, b) => b.score - a.score).map((x) => x.r);
       }
+    } catch (err) {
+      console.error("[EXULU] Entity boost step failed (continuing):", err.message);
+    }
+  }
+  results = results.slice(0, limit);
+  if (expand?.before || expand?.after) {
+    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 db2(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 || "" });
     }
-    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) {
@@ -16713,6 +17318,20 @@ function serializeError(err, depth = 0) {
   return { message: String(err) };
 }
 
+// src/exulu/turn-metadata.ts
+init_cjs_shims();
+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/utils/enabled-tools.ts
 init_cjs_shims();
 init_pipeline();
@@ -16837,6 +17456,58 @@ async function resolveFreshFileUrl(url, opts) {
   }
 }
 
+// src/exulu/session-file-listing.ts
+init_cjs_shims();
+init_uppy();
+init_artifact_filter();
+init_session_files();
+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
 init_uppy();
 var import_ai6 = require("ai");
@@ -17088,11 +17759,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;
@@ -17114,7 +17786,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",
@@ -17139,6 +17811,37 @@ function retrievalBudgetGuard(limit, agenticToolKey, allToolKeys) {
   };
 }
 
+// src/exulu/resolve-reasoning-effort.ts
+init_cjs_shims();
+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
+init_cjs_shims();
+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
 init_sanitize_tool_name();
 init_tool_image_attachments();
@@ -17236,6 +17939,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,
@@ -17292,10 +18004,13 @@ var generateSync = async ({
   }
   let project;
   let sessionItems;
+  let sessionOwnerId;
+  let lastTurnAt;
   if (session) {
     const sessionData = await getSession({ sessionID: session });
     sessionItems = sessionData.session_items;
     project = sessionData.project;
+    sessionOwnerId = sessionData.user ?? void 0;
   }
   const model = languageModel;
   console.log("[EXULU] Model created for generating sync.");
@@ -17305,6 +18020,7 @@ var generateSync = async ({
       session,
       user: user.id
     });
+    lastTurnAt = lastMessageTime(previousMessages);
     const previousMessagesContent = previousMessages.map(
       (message) => JSON.parse(message.content)
     );
@@ -17399,7 +18115,8 @@ var generateSync = async ({
     agent,
     memoryItems,
     contextWindow,
-    disabledTools
+    disabledTools,
+    sessionOwnerId
   );
   const agenticEntry = currentTools?.find((t) => t.id === "agentic_context_search");
   const agenticToolKey = agenticEntry ? sanitizeToolName(agenticEntry.name) : void 0;
@@ -17466,6 +18183,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. ' +
@@ -17634,10 +18360,13 @@ var generateStream = async ({
   let previousMessagesContent = previousMessages || [];
   let project;
   let sessionItems;
+  let sessionOwnerId;
+  let lastTurnAt;
   if (session) {
     const sessionData = await getSession({ sessionID: session });
     project = sessionData.project;
     sessionItems = sessionData.session_items;
+    sessionOwnerId = sessionData.user ?? void 0;
     console.log("[EXULU] loading previous messages from session: " + session);
     const previousMessages2 = await getAgentMessages({
       session,
@@ -17648,6 +18377,7 @@ var generateStream = async ({
       includeAllUsers: isRunSessionMetadata(sessionData.metadata)
     });
     previousMessagesContent = previousMessages2.map((message2) => JSON.parse(message2.content));
+    lastTurnAt = lastMessageTime(previousMessages2);
   }
   const model = languageModel;
   messages = await (0, import_ai6.validateUIMessages)({
@@ -17790,6 +18520,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. ' +
@@ -17817,7 +18556,8 @@ When a tool execution is not approved by the user, do not retry it unless explic
     agent,
     memoryItems,
     contextWindow,
-    disabledTools
+    disabledTools,
+    sessionOwnerId
   );
   console.log("[EXULU] Converted tools", Object.keys(tools));
   const includesContextSearchTool = currentTools?.some(
@@ -17891,18 +18631,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: [(0, import_ai6.stepCountIs)(turnBudget), (0, import_ai6.hasToolCall)("image_generation")]
@@ -19766,13 +20500,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;
               },
@@ -19977,7 +20705,7 @@ var mapRoutineRunRow = (row, routineById) => {
 
 // src/graphql/schemas/index.ts
 init_entitlements();
-var import_fs2 = require("fs");
+var import_fs3 = require("fs");
 
 // src/exulu/transcription/service.ts
 init_cjs_shims();
@@ -23983,7 +24711,7 @@ var import_utils5 = require("@apollo/utils.keyvaluecache");
 var import_body_parser = __toESM(require("body-parser"), 1);
 var import_crypto_js7 = require("crypto-js");
 var import_openai = require("openai");
-var import_fs3 = __toESM(require("fs"), 1);
+var import_fs4 = __toESM(require("fs"), 1);
 var import_node_crypto15 = require("crypto");
 var import_api2 = require("@opentelemetry/api");
 var import_jszip3 = __toESM(require("jszip"), 1);
@@ -25320,7 +26048,7 @@ var REQUEST_SIZE_LIMIT = "50mb";
 var getExuluVersionNumber = async () => {
   try {
     const path4 = process.cwd();
-    const packageJson = import_fs3.default.readFileSync(path4 + "/package.json", "utf8");
+    const packageJson = import_fs4.default.readFileSync(path4 + "/package.json", "utf8");
     const packageData = JSON.parse(packageJson);
     const exuluVersion = packageData.dependencies["@exulu/backend"];
     console.log(`[EXULU] Installed exulu-backend version: ${exuluVersion}`);
@@ -25803,6 +26531,7 @@ var createExpressRoutes = async (app, tools, contexts, config, evals, tracer) =>
 
 ${customInstructions}` : agent.instructions;
         if (headers.session) markStreamActive(headers.session);
+        const turnStartedAt = Date.now();
         let result;
         try {
           result = await generateStream({
@@ -25844,13 +26573,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;
           },
@@ -30301,210 +31024,7 @@ init_singleton();
 init_entitlements();
 init_system_dependencies();
 init_supervisor();
-
-// src/utils/python-setup.ts
-init_cjs_shims();
-var import_child_process = require("child_process");
-var import_util = require("util");
-var import_path3 = require("path");
-var import_fs4 = require("fs");
-var import_url = require("url");
-var execAsync4 = (0, import_util.promisify)(import_child_process.exec);
-function getPackageRoot() {
-  const currentFile = (0, import_url.fileURLToPath)(importMetaUrl);
-  let currentDir = (0, import_path3.dirname)(currentFile);
-  let attempts = 0;
-  const maxAttempts = 10;
-  while (attempts < maxAttempts) {
-    const packageJsonPath = (0, import_path3.join)(currentDir, "package.json");
-    if ((0, import_fs4.existsSync)(packageJsonPath)) {
-      try {
-        const packageJson = JSON.parse((0, import_fs4.readFileSync)(packageJsonPath, "utf-8"));
-        if (packageJson.name === "@exulu/backend") {
-          return currentDir;
-        }
-      } catch {
-      }
-    }
-    const parentDir = (0, import_path3.resolve)(currentDir, "..");
-    if (parentDir === currentDir) {
-      break;
-    }
-    currentDir = parentDir;
-    attempts++;
-  }
-  const fallback = (0, import_path3.resolve)((0, import_path3.dirname)((0, import_url.fileURLToPath)(importMetaUrl)), "../..");
-  return fallback;
-}
-function getSetupScriptPath(packageRoot) {
-  return (0, import_path3.resolve)(packageRoot, "ee/python/setup.sh");
-}
-function getVenvPath(packageRoot) {
-  return (0, import_path3.resolve)(packageRoot, "ee/python/.venv");
-}
-function isPythonEnvironmentSetup(packageRoot) {
-  const root = packageRoot ?? getPackageRoot();
-  const venvPath = getVenvPath(root);
-  const pythonPath = (0, import_path3.join)(venvPath, "bin", "python");
-  return (0, import_fs4.existsSync)(venvPath) && (0, import_fs4.existsSync)(pythonPath);
-}
-async function setupPythonEnvironment(options = {}) {
-  const {
-    packageRoot = getPackageRoot(),
-    force = false,
-    verbose = false,
-    timeout = 6e5
-    // 10 minutes
-  } = options;
-  if (!force && isPythonEnvironmentSetup(packageRoot)) {
-    if (verbose) {
-      console.log("\u2713 Python environment already set up");
-    }
-    return {
-      success: true,
-      message: "Python environment already exists",
-      alreadyExists: true
-    };
-  }
-  const setupScriptPath = getSetupScriptPath(packageRoot);
-  if (!(0, import_fs4.existsSync)(setupScriptPath)) {
-    return {
-      success: false,
-      message: `Setup script not found at: ${setupScriptPath}`,
-      alreadyExists: false
-    };
-  }
-  try {
-    if (verbose) {
-      console.log("Setting up Python environment...");
-    }
-    const { stdout, stderr } = await execAsync4(`bash "${setupScriptPath}"`, {
-      cwd: packageRoot,
-      timeout,
-      env: {
-        ...process.env,
-        // Ensure script can write to the directory
-        PYTHONDONTWRITEBYTECODE: "1"
-      },
-      maxBuffer: 10 * 1024 * 1024
-      // 10MB buffer
-    });
-    const output = stdout + stderr;
-    const versionMatch = output.match(/Python (\d+\.\d+\.\d+)/);
-    const pythonVersion = versionMatch ? versionMatch[1] : void 0;
-    if (verbose) {
-      console.log(output);
-    }
-    return {
-      success: true,
-      message: "Python environment set up successfully",
-      alreadyExists: false,
-      pythonVersion,
-      output
-    };
-  } catch (error) {
-    const errorOutput = error.stdout + error.stderr;
-    return {
-      success: false,
-      message: `Setup failed: ${error.message}`,
-      alreadyExists: false,
-      output: errorOutput
-    };
-  }
-}
-function getPythonSetupInstructions() {
-  return `
-Python environment not set up. Please run one of the following commands:
-
-Option 1 (Automatic):
-  import { setupPythonEnvironment } from '@exulu/backend';
-  await setupPythonEnvironment();
-
-Option 2 (Manual - for package consumers):
-  npx @exulu/backend setup-python
-
-Option 3 (Manual - for contributors):
-  npm run python:setup
-
-These commands will automatically create a Python virtual environment (.venv)
-in the @exulu/backend package and install all required dependencies.
-
-Requirements:
-  - Python 3.10 or higher must be installed
-  - pip must be available
-  - venv module must be available (for creating virtual environments)
-
-If Python dependencies are not installed, install them first, then run one of the commands above:
-  - macOS: brew install python@3.12
-  - Ubuntu/Debian: sudo apt-get install python3.12 python3-pip python3-venv
-  - Alpine Linux: apk add python3 py3-pip python3-dev
-  - Windows: Download from https://www.python.org/downloads/
-
-Note: In Docker containers, ensure you install all three components:
-  Ubuntu/Debian: apt-get install -y python3 python3-pip python3-venv
-  Alpine: apk add python3 py3-pip python3-dev
-`.trim();
-}
-async function validatePythonEnvironment(packageRoot, checkPackages = true) {
-  const root = packageRoot ?? getPackageRoot();
-  const venvPath = getVenvPath(root);
-  const pythonPath = (0, import_path3.join)(venvPath, "bin", "python");
-  if (!(0, import_fs4.existsSync)(venvPath)) {
-    return {
-      valid: false,
-      message: getPythonSetupInstructions()
-    };
-  }
-  if (!(0, import_fs4.existsSync)(pythonPath)) {
-    return {
-      valid: false,
-      message: "Python virtual environment is corrupted. Please run:\n  await setupPythonEnvironment({ force: true })"
-    };
-  }
-  try {
-    await execAsync4(`"${pythonPath}" --version`, { cwd: root });
-  } catch {
-    return {
-      valid: false,
-      message: "Python executable is not working. Please run:\n  await setupPythonEnvironment({ force: true })"
-    };
-  }
-  if (checkPackages) {
-    const criticalPackages = ["docling", "transformers"];
-    const missingPackages = [];
-    for (const pkg of criticalPackages) {
-      try {
-        await execAsync4(`"${pythonPath}" -c "import ${pkg}"`, {
-          cwd: root,
-          timeout: 1e4
-          // 10 second timeout per import check
-        });
-      } catch {
-        missingPackages.push(pkg);
-      }
-    }
-    if (missingPackages.length > 0) {
-      return {
-        valid: false,
-        message: `Python environment exists but required packages are not installed: ${missingPackages.join(", ")}
-
-This usually happens when:
-1. The .venv folder was copied but dependencies were not installed
-2. The package was installed via npm but setup script was not run
-
-Please run:
-  await setupPythonEnvironment({ force: true })
-
-Or manually run the setup script:
-  bash ` + getSetupScriptPath(root)
-      };
-    }
-  }
-  return {
-    valid: true,
-    message: "Python environment is valid"
-  };
-}
+init_python_setup();
 
 // src/templates/contexts/index.ts
 init_cjs_shims();
@@ -32493,6 +33013,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
 };
 
 // src/postgres/init-litellm-db.ts
+init_python_setup();
 var initLitellmDb = async () => {
   await initLiteLLMDatabase(getPackageRoot());
   console.log("[EXULU] LiteLLM database initialized.");
@@ -33027,6 +33548,9 @@ var MarkdownChunker = class {
   }
 };
 
+// src/index.ts
+init_python_setup();
+
 // ee/python/documents/processing/doc_processor.ts
 init_cjs_shims();
 var fs4 = __toESM(require("fs"), 1);
@@ -33049,6 +33573,7 @@ var import_util3 = require("util");
 var import_path4 = require("path");
 var import_fs5 = require("fs");
 var import_url2 = require("url");
+init_python_setup();
 var execAsync5 = (0, import_util3.promisify)(import_child_process2.exec);
 function getPackageRoot2() {
   const currentFile = (0, import_url2.fileURLToPath)(importMetaUrl);
@@ -33570,7 +34095,7 @@ function reconstructTableHeaders(document2, validationResults, verbose = false)
   }
 }
 async function validateWithVLM(document2, model, verbose = false, concurrency = 10) {
-  console.log(`[EXULU] Starting VLM validation for docling output, ${document2.length} pages...`);
+  console.log(`[EXULU] Starting VLM validation for processor output, ${document2.length} pages...`);
   console.log(`[EXULU] Concurrency limit: ${concurrency}`);
   const limit = (0, import_p_limit.default)(concurrency);
   const validationResults = /* @__PURE__ */ new Map();
@@ -33705,48 +34230,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 fs4.promises.readFile(paths.json, "utf-8");
-      json = JSON.parse(jsonContent);
-    } else if (config?.processor.name === "officeparser") {
+    if (config?.processor.name === "officeparser") {
       const text = await (0, import_officeparser3.parseOfficeAsync)(buffer, {
         outputErrorToConsole: false,
         newlineDelimiter: "\n"
@@ -33837,14 +34321,16 @@ stderr: ${splitResult.stderr.slice(-1e3)}`
         image: screenshots.find((s) => s.pageNum === page.pageNum)?.imagePath
       }));
       fs4.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(
@@ -33962,9 +34448,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;