@exulu/backend 4.1.0 → 4.2.0

package/bin/setup-python.cjs

@@ -98,20 +98,24 @@ async function main() {
   console.log(`${colors.blue}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}`);
   console.log('');
 
-  // Check if already exists (and not forcing)
-  if (pythonEnvironmentExists() && !force) {
-    console.log(`${colors.green}✓${colors.reset} Python environment already set up`);
-    console.log('');
-    console.log('To rebuild the environment, run:');
-    console.log(`  ${colors.green}npx @exulu/backend setup-python --force${colors.reset}`);
-    console.log('');
-    console.log(`${colors.blue}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}`);
-    console.log('');
-    return;
-  }
-
-  if (force && pythonEnvironmentExists()) {
-    console.log(`${colors.yellow}⚠${colors.reset} Rebuilding Python environment (--force flag detected)`);
+  // We deliberately do NOT skip running setup.sh just because the venv
+  // directory and a `python` binary already exist (pythonEnvironmentExists()
+  // only checks that much, not that requirements.txt is fully installed).
+  // ee/python/setup.sh is itself idempotent — it only skips *recreating* the
+  // venv, never skips `pip install -r requirements.txt` — so always invoking
+  // it is cheap when nothing is missing (a few seconds) and is the only way
+  // to guarantee a venv created before a new requirement was added (e.g.
+  // python-docx, 2026-09-11) actually gets it installed. This used to return
+  // early here whenever the venv folder was merely present, which silently
+  // left newly-added dependencies uninstalled across any deploy that reused
+  // an older venv — see the docx-manipulation skill incident on dx-algi,
+  // 2026-09-21.
+  if (pythonEnvironmentExists()) {
+    console.log(
+      force
+        ? `${colors.yellow}⚠${colors.reset} Rebuilding Python environment (--force flag detected)`
+        : `${colors.blue}ℹ${colors.reset} Python environment directory already exists — verifying and installing any missing dependencies...`,
+    );
     console.log('');
   }
 

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

@@ -1716,7 +1716,7 @@ var ExuluTool = class _ExuluTool {
     if (!agent) {
       throw new Error("Agent not found.");
     }
-    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-6RU4IZMI.js");
+    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-AHRL4TN4.js");
     const tools = await convertExuluToolsToAiSdkTools2(
       [this],
       [],
@@ -6308,7 +6308,7 @@ async function downloadKeyIntoSandbox(opts) {
 }
 async function resolvePythonVenvPath() {
   try {
-    const { getPythonVenvPath } = await import("./python-setup-DRJ3QX5F.js");
+    const { getPythonVenvPath } = await import("./python-setup-UYSNAW5V.js");
     return getPythonVenvPath();
   } catch (err) {
     console.warn("[SKILLS] Could not resolve the Python venv for the session sandbox; skill scripts fall back to the system python.", err);
@@ -6961,11 +6961,50 @@ import { parseOfficeAsync } from "officeparser";
 // src/templates/tools/document-render-helpers.ts
 import { execFile } from "child_process";
 import { promisify as promisify3 } from "util";
+import { existsSync as existsSync4 } from "fs";
 import { mkdtemp, readdir as readdir2, readFile, rm as rm2, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir } from "os";
 import { join as join3 } from "path";
 var execFileAsync = promisify3(execFile);
 var MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+var LEGACY_OFFICE_CONVERSION_TARGETS = {
+  ".doc": "docx",
+  ".xls": "xlsx",
+  ".ppt": "pptx",
+  ".rtf": "docx"
+};
+function isLegacyOfficeFormat(ext) {
+  return ext in LEGACY_OFFICE_CONVERSION_TARGETS;
+}
+async function convertLegacyOfficeToModern(bytes, ext) {
+  const target = LEGACY_OFFICE_CONVERSION_TARGETS[ext];
+  if (!target) {
+    throw new Error(`No modern-format conversion target registered for "${ext}"`);
+  }
+  const dir = await mkdtemp(join3(tmpdir(), "exulu-officeconv-"));
+  try {
+    const inputPath = join3(dir, `input${ext}`);
+    await writeFile2(inputPath, bytes);
+    try {
+      await execFileAsync(
+        "soffice",
+        ["--headless", "--convert-to", target, inputPath, "--outdir", dir],
+        { timeout: 6e4, maxBuffer: MAX_STDOUT_BYTES }
+      );
+    } catch (err) {
+      throw new Error(
+        `LibreOffice could not convert the legacy "${ext}" file to ${target}: ` + (err instanceof Error ? err.message : String(err))
+      );
+    }
+    const outputPath = join3(dir, `input.${target}`);
+    if (!existsSync4(outputPath)) {
+      throw new Error(`LibreOffice produced no output converting "${ext}" to ${target}`);
+    }
+    return await readFile(outputPath);
+  } finally {
+    await rm2(dir, { recursive: true, force: true });
+  }
+}
 async function pdfToText(pdf) {
   const dir = await mkdtemp(join3(tmpdir(), "exulu-parse-"));
   try {
@@ -7032,6 +7071,18 @@ var OFFICE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".rtf"
 ]);
 var pagesPattern = /^(\d+)(?:-(\d+))?$/;
+var BINARY_DOCUMENT_EXTENSION_PATTERN = new RegExp(
+  `([^\\s"'\`]+\\.(?:pdf|${[...OFFICE_EXTENSIONS].map((ext) => ext.slice(1)).join("|")}))\\b`,
+  "i"
+);
+function binaryDocumentBashHint(command, stdout, stderr) {
+  const match = command.match(BINARY_DOCUMENT_EXTENSION_PATTERN);
+  if (!match) return void 0;
+  const silent = !stdout.trim() && !stderr.trim();
+  if (!silent && !looksLikeGarbledTextLayer(stdout)) return void 0;
+  const [, file] = match;
+  return `Note: "${file}" is a binary document \u2014 grep/cat/text tools cannot read the text inside it, so a silent or garbled result does not mean the content isn't there. Use parse_document to extract its text first, then search or read within that extracted text instead of the original file.`;
+}
 var createParseDocumentTool = ({
   sessionID,
   user,
@@ -7101,7 +7152,8 @@ var createParseDocumentTool = ({
         fullText = pageTexts.map((text, i) => ({ page: i + 1, text })).filter(({ page }) => page >= range[0] && page <= range[1]).map(({ page, text }) => `--- page ${page} ---
 ${text.trim()}`).join("\n");
       } else {
-        const extracted = await parseOfficeAsync(bytes, {
+        const officeBytes = isLegacyOfficeFormat(ext) ? await convertLegacyOfficeToModern(bytes, ext) : bytes;
+        const extracted = await parseOfficeAsync(officeBytes, {
           outputErrorToConsole: false,
           newlineDelimiter: "\n"
         });
@@ -7156,7 +7208,7 @@ import { extname as extname3 } from "path";
 
 // src/sessions/pdf-preview-cache.ts
 import { exec as exec3 } from "child_process";
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { mkdir as mkdir2, readFile as readFile2, rename, rm as rm3, writeFile as writeFile3 } from "fs/promises";
 import { extname as extname2, join as join4 } from "path";
 import { promisify as promisify4 } from "util";
@@ -7181,7 +7233,7 @@ async function getPdfPreviewBytes(opts) {
     throw new PreviewRenderError(`Invalid ETag for ${sourceKey}`);
   }
   const cachedPath = join4(CACHE_ROOT, `${safeEtag}.pdf`);
-  if (existsSync4(cachedPath)) {
+  if (existsSync5(cachedPath)) {
     return readFile2(cachedPath);
   }
   const existing = inFlight.get(safeEtag);
@@ -7206,7 +7258,7 @@ async function getPdfPreviewBytes(opts) {
             `LibreOffice conversion failed for ${sourceKey} (etag ${etag}): ${err?.stderr ?? err?.message ?? "unknown error"}`
           );
         }
-        if (!existsSync4(outputPath)) {
+        if (!existsSync5(outputPath)) {
           throw new PreviewRenderError(
             `LibreOffice produced no output for ${sourceKey} (etag ${etag})`
           );
@@ -8230,13 +8282,17 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
         const origExecute = sharedSessionSandbox.tools.bash.execute;
         if (!origExecute) throw new Error("bash execute is undefined");
         const result = await origExecute(args, opts);
+        const rawStdout = typeof result?.stdout === "string" ? result.stdout : "";
+        const rawStderr = typeof result?.stderr === "string" ? result.stderr : "";
+        const hint = binaryDocumentBashHint(String(args?.command ?? ""), rawStdout, rawStderr);
+        const stderrWithHint = hint ? [rawStderr, hint].filter(Boolean).join("\n\n") : rawStderr;
         return {
           ...result,
           ...typeof result?.stdout === "string" && {
-            stdout: truncateToolOutput(result.stdout, budget.contextWindow, "bash", 0.1, toolOutputCharLimit)
+            stdout: truncateToolOutput(rawStdout, budget.contextWindow, "bash", 0.1, toolOutputCharLimit)
           },
-          ...typeof result?.stderr === "string" && {
-            stderr: truncateToolOutput(result.stderr, budget.contextWindow, "bash stderr", 0.4, toolOutputCharLimit)
+          ...(typeof result?.stderr === "string" || hint) && {
+            stderr: truncateToolOutput(stderrWithHint, budget.contextWindow, "bash stderr", 0.4, toolOutputCharLimit)
           }
         };
       }

package/dist/{chunk-QMN6MVHQ.js → chunk-JIZCKSJO.js}

@@ -57,15 +57,11 @@ async function setupPythonEnvironment(options = {}) {
     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 alreadyExisted = isPythonEnvironmentSetup(packageRoot);
+  if (verbose) {
+    console.log(
+      alreadyExisted ? "Python environment already exists \u2014 verifying and installing any missing dependencies..." : "Setting up Python environment..."
+    );
   }
   const setupScriptPath = getSetupScriptPath(packageRoot);
   if (!existsSync(setupScriptPath)) {
@@ -76,9 +72,6 @@ async function setupPythonEnvironment(options = {}) {
     };
   }
   try {
-    if (verbose) {
-      console.log("Setting up Python environment...");
-    }
     const { stdout, stderr } = await execAsync(`bash "${setupScriptPath}"`, {
       cwd: packageRoot,
       timeout,
@@ -98,8 +91,8 @@ async function setupPythonEnvironment(options = {}) {
     }
     return {
       success: true,
-      message: "Python environment set up successfully",
-      alreadyExists: false,
+      message: alreadyExisted ? "Python environment verified (dependencies were already installed or have been updated)" : "Python environment set up successfully",
+      alreadyExists: alreadyExisted,
       pythonVersion,
       output
     };
@@ -108,7 +101,7 @@ async function setupPythonEnvironment(options = {}) {
     return {
       success: false,
       message: `Setup failed: ${error.message}`,
-      alreadyExists: false,
+      alreadyExists: alreadyExisted,
       output: errorOutput
     };
   }
@@ -171,7 +164,7 @@ async function validatePythonEnvironment(packageRoot, checkPackages = true) {
     };
   }
   if (checkPackages) {
-    const criticalPackages = ["pypdf", "transformers"];
+    const criticalPackages = ["pypdf", "transformers", "docx"];
     const missingPackages = [];
     for (const pkg of criticalPackages) {
       try {

package/dist/cli/start-whisper.js

@@ -2,7 +2,7 @@
 import "dotenv/config";
 import {
   getPackageRoot
-} from "../chunk-QMN6MVHQ.js";
+} from "../chunk-JIZCKSJO.js";
 
 // src/cli/start-whisper.ts
 import "dotenv/config";

package/dist/{convert-exulu-tools-to-ai-sdk-tools-6RU4IZMI.js → convert-exulu-tools-to-ai-sdk-tools-AHRL4TN4.js}

@@ -2,7 +2,7 @@ import "dotenv/config";
 import {
   convertExuluToolsToAiSdkTools,
   hydrateVariables
-} from "./chunk-RBEWHG7I.js";
+} from "./chunk-D4PCOOL5.js";
 import "./chunk-4PDWNVNT.js";
 export {
   convertExuluToolsToAiSdkTools,

package/dist/index.cjs

@@ -3950,15 +3950,11 @@ async function setupPythonEnvironment(options = {}) {
     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 alreadyExisted = isPythonEnvironmentSetup(packageRoot);
+  if (verbose) {
+    console.log(
+      alreadyExisted ? "Python environment already exists \u2014 verifying and installing any missing dependencies..." : "Setting up Python environment..."
+    );
   }
   const setupScriptPath = getSetupScriptPath(packageRoot);
   if (!(0, import_fs.existsSync)(setupScriptPath)) {
@@ -3969,9 +3965,6 @@ async function setupPythonEnvironment(options = {}) {
     };
   }
   try {
-    if (verbose) {
-      console.log("Setting up Python environment...");
-    }
     const { stdout, stderr } = await execAsync2(`bash "${setupScriptPath}"`, {
       cwd: packageRoot,
       timeout,
@@ -3991,8 +3984,8 @@ async function setupPythonEnvironment(options = {}) {
     }
     return {
       success: true,
-      message: "Python environment set up successfully",
-      alreadyExists: false,
+      message: alreadyExisted ? "Python environment verified (dependencies were already installed or have been updated)" : "Python environment set up successfully",
+      alreadyExists: alreadyExisted,
       pythonVersion,
       output
     };
@@ -4001,7 +3994,7 @@ async function setupPythonEnvironment(options = {}) {
     return {
       success: false,
       message: `Setup failed: ${error.message}`,
-      alreadyExists: false,
+      alreadyExists: alreadyExisted,
       output: errorOutput
     };
   }
@@ -4064,7 +4057,7 @@ async function validatePythonEnvironment(packageRoot, checkPackages = true) {
     };
   }
   if (checkPackages) {
-    const criticalPackages = ["pypdf", "transformers"];
+    const criticalPackages = ["pypdf", "transformers", "docx"];
     const missingPackages = [];
     for (const pkg of criticalPackages) {
       try {
@@ -5013,6 +5006,38 @@ var init_session_file_read_tool = __esm({
 });
 
 // src/templates/tools/document-render-helpers.ts
+function isLegacyOfficeFormat(ext) {
+  return ext in LEGACY_OFFICE_CONVERSION_TARGETS;
+}
+async function convertLegacyOfficeToModern(bytes, ext) {
+  const target = LEGACY_OFFICE_CONVERSION_TARGETS[ext];
+  if (!target) {
+    throw new Error(`No modern-format conversion target registered for "${ext}"`);
+  }
+  const dir = await (0, import_promises2.mkdtemp)((0, import_node_path5.join)((0, import_node_os.tmpdir)(), "exulu-officeconv-"));
+  try {
+    const inputPath = (0, import_node_path5.join)(dir, `input${ext}`);
+    await (0, import_promises2.writeFile)(inputPath, bytes);
+    try {
+      await execFileAsync(
+        "soffice",
+        ["--headless", "--convert-to", target, inputPath, "--outdir", dir],
+        { timeout: 6e4, maxBuffer: MAX_STDOUT_BYTES }
+      );
+    } catch (err) {
+      throw new Error(
+        `LibreOffice could not convert the legacy "${ext}" file to ${target}: ` + (err instanceof Error ? err.message : String(err))
+      );
+    }
+    const outputPath = (0, import_node_path5.join)(dir, `input.${target}`);
+    if (!(0, import_node_fs6.existsSync)(outputPath)) {
+      throw new Error(`LibreOffice produced no output converting "${ext}" to ${target}`);
+    }
+    return await (0, import_promises2.readFile)(outputPath);
+  } finally {
+    await (0, import_promises2.rm)(dir, { recursive: true, force: true });
+  }
+}
 async function pdfToText(pdf) {
   const dir = await (0, import_promises2.mkdtemp)((0, import_node_path5.join)((0, import_node_os.tmpdir)(), "exulu-parse-"));
   try {
@@ -5049,18 +5074,25 @@ async function renderPdfPageToPng(pdf, page, scaleTo) {
     await (0, import_promises2.rm)(dir, { recursive: true, force: true });
   }
 }
-var import_node_child_process4, import_node_util3, import_promises2, import_node_os, import_node_path5, execFileAsync, MAX_STDOUT_BYTES;
+var import_node_child_process4, import_node_util3, import_node_fs6, import_promises2, import_node_os, import_node_path5, execFileAsync, MAX_STDOUT_BYTES, LEGACY_OFFICE_CONVERSION_TARGETS;
 var init_document_render_helpers = __esm({
   "src/templates/tools/document-render-helpers.ts"() {
     "use strict";
     init_cjs_shims();
     import_node_child_process4 = require("child_process");
     import_node_util3 = require("util");
+    import_node_fs6 = require("fs");
     import_promises2 = require("fs/promises");
     import_node_os = require("os");
     import_node_path5 = require("path");
     execFileAsync = (0, import_node_util3.promisify)(import_node_child_process4.execFile);
     MAX_STDOUT_BYTES = 64 * 1024 * 1024;
+    LEGACY_OFFICE_CONVERSION_TARGETS = {
+      ".doc": "docx",
+      ".xls": "xlsx",
+      ".ppt": "pptx",
+      ".rtf": "docx"
+    };
   }
 });
 
@@ -5077,7 +5109,15 @@ function looksLikeGarbledTextLayer(text) {
   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;
+function binaryDocumentBashHint(command, stdout, stderr) {
+  const match = command.match(BINARY_DOCUMENT_EXTENSION_PATTERN);
+  if (!match) return void 0;
+  const silent = !stdout.trim() && !stderr.trim();
+  if (!silent && !looksLikeGarbledTextLayer(stdout)) return void 0;
+  const [, file] = match;
+  return `Note: "${file}" is a binary document \u2014 grep/cat/text tools cannot read the text inside it, so a silent or garbled result does not mean the content isn't there. Use parse_document to extract its text first, then search or read within that extracted text instead of the original file.`;
+}
+var import_zod8, import_node_path6, import_officeparser, DEFAULT_LIMIT2, MAX_CONTENT_CHARS2, MIN_CHARS_PER_PAGE, OFFICE_EXTENSIONS, pagesPattern, BINARY_DOCUMENT_EXTENSION_PATTERN, createParseDocumentTool;
 var init_parse_document_tool = __esm({
   "src/templates/tools/parse-document-tool.ts"() {
     "use strict";
@@ -5105,6 +5145,10 @@ var init_parse_document_tool = __esm({
       ".rtf"
     ]);
     pagesPattern = /^(\d+)(?:-(\d+))?$/;
+    BINARY_DOCUMENT_EXTENSION_PATTERN = new RegExp(
+      `([^\\s"'\`]+\\.(?:pdf|${[...OFFICE_EXTENSIONS].map((ext) => ext.slice(1)).join("|")}))\\b`,
+      "i"
+    );
     createParseDocumentTool = ({
       sessionID,
       user,
@@ -5174,7 +5218,8 @@ var init_parse_document_tool = __esm({
             fullText = pageTexts.map((text, i) => ({ page: i + 1, text })).filter(({ page }) => page >= range[0] && page <= range[1]).map(({ page, text }) => `--- page ${page} ---
 ${text.trim()}`).join("\n");
           } else {
-            const extracted = await (0, import_officeparser.parseOfficeAsync)(bytes, {
+            const officeBytes = isLegacyOfficeFormat(ext) ? await convertLegacyOfficeToModern(bytes, ext) : bytes;
+            const extracted = await (0, import_officeparser.parseOfficeAsync)(officeBytes, {
               outputErrorToConsole: false,
               newlineDelimiter: "\n"
             });
@@ -5236,7 +5281,7 @@ async function getPdfPreviewBytes(opts) {
     throw new PreviewRenderError(`Invalid ETag for ${sourceKey}`);
   }
   const cachedPath = (0, import_node_path7.join)(CACHE_ROOT, `${safeEtag}.pdf`);
-  if ((0, import_node_fs6.existsSync)(cachedPath)) {
+  if ((0, import_node_fs7.existsSync)(cachedPath)) {
     return (0, import_promises3.readFile)(cachedPath);
   }
   const existing = inFlight.get(safeEtag);
@@ -5261,7 +5306,7 @@ async function getPdfPreviewBytes(opts) {
             `LibreOffice conversion failed for ${sourceKey} (etag ${etag}): ${err?.stderr ?? err?.message ?? "unknown error"}`
           );
         }
-        if (!(0, import_node_fs6.existsSync)(outputPath)) {
+        if (!(0, import_node_fs7.existsSync)(outputPath)) {
           throw new PreviewRenderError(
             `LibreOffice produced no output for ${sourceKey} (etag ${etag})`
           );
@@ -5278,13 +5323,13 @@ 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, execAsync4, CACHE_ROOT, CACHE_IN, CACHE_OUT, inFlight, PreviewRenderError;
+var import_node_child_process5, import_node_fs7, 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";
     init_cjs_shims();
     import_node_child_process5 = require("child_process");
-    import_node_fs6 = require("fs");
+    import_node_fs7 = require("fs");
     import_promises3 = require("fs/promises");
     import_node_path7 = require("path");
     import_node_util4 = require("util");
@@ -6540,13 +6585,17 @@ var init_convert_exulu_tools_to_ai_sdk_tools = __esm({
             const origExecute = sharedSessionSandbox.tools.bash.execute;
             if (!origExecute) throw new Error("bash execute is undefined");
             const result = await origExecute(args, opts);
+            const rawStdout = typeof result?.stdout === "string" ? result.stdout : "";
+            const rawStderr = typeof result?.stderr === "string" ? result.stderr : "";
+            const hint = binaryDocumentBashHint(String(args?.command ?? ""), rawStdout, rawStderr);
+            const stderrWithHint = hint ? [rawStderr, hint].filter(Boolean).join("\n\n") : rawStderr;
             return {
               ...result,
               ...typeof result?.stdout === "string" && {
-                stdout: truncateToolOutput(result.stdout, budget.contextWindow, "bash", 0.1, toolOutputCharLimit)
+                stdout: truncateToolOutput(rawStdout, budget.contextWindow, "bash", 0.1, toolOutputCharLimit)
               },
-              ...typeof result?.stderr === "string" && {
-                stderr: truncateToolOutput(result.stderr, budget.contextWindow, "bash stderr", 0.4, toolOutputCharLimit)
+              ...(typeof result?.stderr === "string" || hint) && {
+                stderr: truncateToolOutput(stderrWithHint, budget.contextWindow, "bash stderr", 0.4, toolOutputCharLimit)
               }
             };
           }
@@ -12365,7 +12414,12 @@ var transcriptionJobsSchema = {
     // Selected per-meeting post-processing: [{ prompt_id, agent_id }].
     { name: "post_processing_prompts", type: "json" },
     // Results: [{ prompt_id, agent_id, prompt_name, status, output, error, ran_at }].
-    { name: "post_processing_outputs", type: "json" }
+    { name: "post_processing_outputs", type: "json" },
+    // Permanent local copy of the meeting's mixed MP4, downloaded from Recall
+    // when RECALL_STORE_VIDEO_LOCALLY=true. Null when that flag is off (the
+    // video then stays reachable only via ExuluRecall.getRecordingVideoUrl,
+    // for as long as Recall itself retains it) or for Whisper upload jobs.
+    { name: "video", type: "file" }
   ]
 };
 var imageGenerationsSchema = {
@@ -20847,6 +20901,9 @@ var buildTranscriptItemInput = ({
   post_processing: row.post_processing_outputs ?? void 0,
   // Handle for the meeting video; null for Whisper uploads.
   recall_recording_id: row.recall_recording_id ?? void 0,
+  // Permanent local copy of the video, only present when
+  // RECALL_STORE_VIDEO_LOCALLY was on at recording time.
+  video_s3key: row.video_s3key ?? void 0,
   rights_mode: rightsMode,
   created_by: row.created_by
 });
@@ -21182,6 +21239,12 @@ var recordingMonthlyLimitSeconds = () => {
   const minutes = Number(raw);
   return Number.isFinite(minutes) && minutes > 0 ? minutes * 60 : null;
 };
+var RECALL_RECORDING_RETENTION_DEFAULT_HOURS = 2160;
+var recallRecordingRetentionHours = () => {
+  const raw = Number(process.env.RECALL_RECORDING_RETENTION_HOURS);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : RECALL_RECORDING_RETENTION_DEFAULT_HOURS;
+};
+var recallStoreVideoLocally = () => process.env.RECALL_STORE_VIDEO_LOCALLY === "true";
 var recallWebhookUrl = () => {
   const base = recallPublicBaseUrl();
   return base ? `${base}/recall/webhooks` : null;
@@ -21296,7 +21359,6 @@ var recordingDurationSeconds = (rec) => {
   }
   return null;
 };
-var RECORDING_RETENTION_HOURS = 2160;
 var buildCreateBotPayload = (input) => ({
   meeting_url: input.meeting_url,
   join_at: input.join_at,
@@ -21306,7 +21368,7 @@ var buildCreateBotPayload = (input) => ({
     video_mixed_layout: "speaker_view",
     participant_events: {},
     meeting_metadata: {},
-    retention: { type: "timed", hours: RECORDING_RETENTION_HOURS }
+    retention: { type: "timed", hours: recallRecordingRetentionHours() }
   },
   ...input.notifyChat ? {
     chat: {
@@ -21368,6 +21430,31 @@ var recallClient = {
   }
 };
 
+// src/exulu/recall/video-storage.ts
+init_cjs_shims();
+init_uppy();
+async function downloadAndStoreRecordingVideo(recording, jobId, config) {
+  const video = recording.media_shortcuts?.video_mixed;
+  const url = video?.data?.download_url;
+  if (!url) return null;
+  if (video.status?.code && video.status.code !== "done") return null;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`video download failed for job ${jobId}: HTTP ${res.status}`);
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  return uploadFile(
+    bytes,
+    `recall-videos/${jobId}.mp4`,
+    config,
+    { contentType: "video/mp4" },
+    void 0,
+    void 0,
+    true
+    // global: this is a system-stored artifact, not scoped to an uploading user.
+  );
+}
+
 // src/exulu/recall/transcript-map.ts
 init_cjs_shims();
 var speakerLabel = (participant) => {
@@ -21605,12 +21692,24 @@ var recallService = {
       const raw = await recallClient.downloadTranscript(url);
       const segments = mapRecallTranscript(raw);
       let duration = durationFromSegments(segments);
+      let videoS3Key = null;
       const recId = recordingId ?? job.recall_recording_id;
       if (recId) {
         try {
           const rec = await recallClient.retrieveRecording(recId);
           const recDuration = recordingDurationSeconds(rec);
           if (recDuration != null) duration = recDuration;
+          if (recallStoreVideoLocally()) {
+            try {
+              videoS3Key = await downloadAndStoreRecordingVideo(
+                rec,
+                jobId,
+                exuluApp.get().config
+              );
+            } catch (err) {
+              log4(`could not store video locally for job ${jobId}: ${err.message}`);
+            }
+          }
         } catch (err) {
           log4(`could not fetch recording duration for job ${jobId}: ${err.message}`);
         }
@@ -21619,6 +21718,7 @@ var recallService = {
         recall_transcript_id: transcriptId ?? job.recall_transcript_id ?? null,
         raw_segments: JSON.stringify(segments),
         duration_seconds: duration,
+        ...videoS3Key ? { video_s3key: videoS3Key } : {},
         status: "awaiting_review"
       });
     } catch (err) {
@@ -22948,6 +23048,9 @@ type PageInfo {
   typeDefs += `
    meetingRecordingUsage: MeetingRecordingUsage
     `;
+  typeDefs += `
+   recordingVideoUrl(job_id: ID!): String
+    `;
   typeDefs += `
    workflowTriggers(workflow: ID!): [WorkflowTrigger!]!
     `;
@@ -23894,6 +23997,13 @@ type LiteLLMModel {
     if (!context.user) throw new Error("Authentication required");
     return recallService.getUsage();
   };
+  resolvers.Query["recordingVideoUrl"] = async (_, args, context) => {
+    await assertOwnsTranscriptionJob(args.job_id, context);
+    const { db: db2 } = context;
+    const row = await db2.from("transcription_jobs").select(["recall_recording_id"]).where({ id: args.job_id }).first();
+    if (!row?.recall_recording_id) return null;
+    return recallService.getRecordingVideoUrl(row.recall_recording_id);
+  };
   resolvers.Query["evals"] = async (_, args, context, info) => {
     const requestedFields = getRequestedFields(info);
     return {
@@ -25254,7 +25364,7 @@ async function editImage(args) {
 
 // src/exulu/litellm/parse-image-models.ts
 init_cjs_shims();
-var import_node_fs7 = require("fs");
+var import_node_fs8 = require("fs");
 var stripComment3 = (line) => {
   const idx = line.indexOf("#");
   return idx >= 0 ? line.slice(0, idx) : line;
@@ -25277,8 +25387,8 @@ var parseInt103 = (raw) => {
   return Number.isInteger(n) ? n : void 0;
 };
 var parseImageGenerationModels = (configPath) => {
-  if (!(0, import_node_fs7.existsSync)(configPath)) return [];
-  const text = (0, import_node_fs7.readFileSync)(configPath, "utf8");
+  if (!(0, import_node_fs8.existsSync)(configPath)) return [];
+  const text = (0, import_node_fs8.readFileSync)(configPath, "utf8");
   const lines = text.split("\n");
   const entries = [];
   let current;
@@ -31094,7 +31204,10 @@ var transcriptionsContext = new ExuluContext2({
     // Link back to the Recall recording so the mixed video stays reachable
     // (resolve a fresh URL via ExuluRecall.getRecordingVideoUrl — it expires
     // after six hours). Null for Whisper uploads.
-    { name: "recall_recording_id", type: "text" }
+    { name: "recall_recording_id", type: "text" },
+    // Permanent local copy of the mixed video, present only when
+    // RECALL_STORE_VIDEO_LOCALLY=true was set at recording time.
+    { name: "video", type: "file" }
   ],
   sources: [],
   active: true,
@@ -31527,6 +31640,11 @@ var ExuluApp = class {
   get audit() {
     return this._audit ?? getAuditLogger(this._config ?? {});
   }
+  /** The deployment's ExuluConfig, for background/webhook code paths that
+   *  have no request to read it off (e.g. the Recall webhook handler). */
+  get config() {
+    return this._config ?? {};
+  }
   embeddings = {
     generate: {
       one: async ({ context: contextId, item: itemId }) => {
@@ -32782,17 +32900,17 @@ init_cjs_shims();
 
 // src/exulu/litellm/db-init.ts
 init_cjs_shims();
-var import_node_fs9 = require("fs");
+var import_node_fs10 = require("fs");
 var import_node_path11 = require("path");
 var import_node_child_process6 = require("child_process");
 var import_pg = require("pg");
 
 // src/exulu/litellm/db-setup-check.ts
 init_cjs_shims();
-var import_node_fs8 = require("fs");
+var import_node_fs9 = require("fs");
 var readLiteLLMDatabaseUrl = (configPath) => {
-  if (!(0, import_node_fs8.existsSync)(configPath)) return void 0;
-  const text = (0, import_node_fs8.readFileSync)(configPath, "utf8");
+  if (!(0, import_node_fs9.existsSync)(configPath)) return void 0;
+  const text = (0, import_node_fs9.readFileSync)(configPath, "utf8");
   const match = text.match(
     /^\s*database_url:\s*["']?([^"'\n#]+?)["']?\s*(#.*)?$/m
   );
@@ -32994,7 +33112,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
   const venvBin = (0, import_node_path11.resolve)(packageRoot, "ee/python/.venv/bin");
   const prismaCli = (0, import_node_path11.resolve)(venvBin, "prisma");
   const venvLibDir = (0, import_node_path11.resolve)(packageRoot, "ee/python/.venv/lib");
-  const pythonVersionDir = (0, import_node_fs9.existsSync)(venvLibDir) ? (0, import_node_fs9.readdirSync)(venvLibDir).find((entry) => /^python3\.\d+$/.test(entry)) : void 0;
+  const pythonVersionDir = (0, import_node_fs10.existsSync)(venvLibDir) ? (0, import_node_fs10.readdirSync)(venvLibDir).find((entry) => /^python3\.\d+$/.test(entry)) : void 0;
   if (!pythonVersionDir) {
     warn2([
       `Could not find a python3.* directory under ${venvLibDir}.`,
@@ -33009,7 +33127,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     "site-packages/litellm/proxy"
   );
   const schemaPath = (0, import_node_path11.resolve)(litellmProxyDir, "schema.prisma");
-  if (!(0, import_node_fs9.existsSync)(prismaCli)) {
+  if (!(0, import_node_fs10.existsSync)(prismaCli)) {
     warn2([
       `Prisma CLI not found at ${prismaCli}.`,
       `Run \`npm run python:setup\` to create the venv and install prisma.`,
@@ -33017,7 +33135,7 @@ var initLiteLLMDatabase = async (packageRoot) => {
     ]);
     return;
   }
-  if (!(0, import_node_fs9.existsSync)(schemaPath)) {
+  if (!(0, import_node_fs10.existsSync)(schemaPath)) {
     warn2([
       `LiteLLM Prisma schema not found at ${schemaPath}.`,
       `Re-run \`npm run python:setup\`. Skipping LiteLLM database setup.`

package/dist/index.d.cts

@@ -1167,6 +1167,9 @@ declare class ExuluApp {
     context(id: string): ExuluContext | undefined;
     get contexts(): ExuluContext[];
     get audit(): AuditLogger;
+    /** The deployment's ExuluConfig, for background/webhook code paths that
+     *  have no request to read it off (e.g. the Recall webhook handler). */
+    get config(): ExuluConfig;
     embeddings: {
         generate: {
             one: ({ context: contextId, item: itemId }: {

package/dist/index.d.ts

@@ -1167,6 +1167,9 @@ declare class ExuluApp {
     context(id: string): ExuluContext | undefined;
     get contexts(): ExuluContext[];
     get audit(): AuditLogger;
+    /** The deployment's ExuluConfig, for background/webhook code paths that
+     *  have no request to read it off (e.g. the Recall webhook handler). */
+    get config(): ExuluConfig;
     embeddings: {
         generate: {
             one: ({ context: contextId, item: itemId }: {

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   isPythonEnvironmentSetup,
   setupPythonEnvironment,
   validatePythonEnvironment
-} from "./chunk-QMN6MVHQ.js";
+} from "./chunk-JIZCKSJO.js";
 import {
   COMPACTION_INSUFFICIENT,
   ContextCompactionRequiredError,
@@ -90,7 +90,7 @@ import {
   verifyCredentialNonce,
   waitForLiteLLMReady,
   withRetry
-} from "./chunk-RBEWHG7I.js";
+} from "./chunk-D4PCOOL5.js";
 import {
   LiteLLMAdminError,
   findLiteLLMModel,
@@ -2880,7 +2880,12 @@ var transcriptionJobsSchema = {
     // Selected per-meeting post-processing: [{ prompt_id, agent_id }].
     { name: "post_processing_prompts", type: "json" },
     // Results: [{ prompt_id, agent_id, prompt_name, status, output, error, ran_at }].
-    { name: "post_processing_outputs", type: "json" }
+    { name: "post_processing_outputs", type: "json" },
+    // Permanent local copy of the meeting's mixed MP4, downloaded from Recall
+    // when RECALL_STORE_VIDEO_LOCALLY=true. Null when that flag is off (the
+    // video then stays reachable only via ExuluRecall.getRecordingVideoUrl,
+    // for as long as Recall itself retains it) or for Whisper upload jobs.
+    { name: "video", type: "file" }
   ]
 };
 var imageGenerationsSchema = {
@@ -11202,6 +11207,9 @@ var buildTranscriptItemInput = ({
   post_processing: row.post_processing_outputs ?? void 0,
   // Handle for the meeting video; null for Whisper uploads.
   recall_recording_id: row.recall_recording_id ?? void 0,
+  // Permanent local copy of the video, only present when
+  // RECALL_STORE_VIDEO_LOCALLY was on at recording time.
+  video_s3key: row.video_s3key ?? void 0,
   rights_mode: rightsMode,
   created_by: row.created_by
 });
@@ -11529,6 +11537,12 @@ var recordingMonthlyLimitSeconds = () => {
   const minutes = Number(raw);
   return Number.isFinite(minutes) && minutes > 0 ? minutes * 60 : null;
 };
+var RECALL_RECORDING_RETENTION_DEFAULT_HOURS = 2160;
+var recallRecordingRetentionHours = () => {
+  const raw = Number(process.env.RECALL_RECORDING_RETENTION_HOURS);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : RECALL_RECORDING_RETENTION_DEFAULT_HOURS;
+};
+var recallStoreVideoLocally = () => process.env.RECALL_STORE_VIDEO_LOCALLY === "true";
 var recallWebhookUrl = () => {
   const base = recallPublicBaseUrl();
   return base ? `${base}/recall/webhooks` : null;
@@ -11643,7 +11657,6 @@ var recordingDurationSeconds = (rec) => {
   }
   return null;
 };
-var RECORDING_RETENTION_HOURS = 2160;
 var buildCreateBotPayload = (input) => ({
   meeting_url: input.meeting_url,
   join_at: input.join_at,
@@ -11653,7 +11666,7 @@ var buildCreateBotPayload = (input) => ({
     video_mixed_layout: "speaker_view",
     participant_events: {},
     meeting_metadata: {},
-    retention: { type: "timed", hours: RECORDING_RETENTION_HOURS }
+    retention: { type: "timed", hours: recallRecordingRetentionHours() }
   },
   ...input.notifyChat ? {
     chat: {
@@ -11715,6 +11728,29 @@ var recallClient = {
   }
 };
 
+// src/exulu/recall/video-storage.ts
+async function downloadAndStoreRecordingVideo(recording, jobId, config) {
+  const video = recording.media_shortcuts?.video_mixed;
+  const url = video?.data?.download_url;
+  if (!url) return null;
+  if (video.status?.code && video.status.code !== "done") return null;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`video download failed for job ${jobId}: HTTP ${res.status}`);
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  return uploadFile(
+    bytes,
+    `recall-videos/${jobId}.mp4`,
+    config,
+    { contentType: "video/mp4" },
+    void 0,
+    void 0,
+    true
+    // global: this is a system-stored artifact, not scoped to an uploading user.
+  );
+}
+
 // src/exulu/recall/transcript-map.ts
 var speakerLabel = (participant) => {
   if (!participant) return "unknown";
@@ -11951,12 +11987,24 @@ var recallService = {
       const raw = await recallClient.downloadTranscript(url);
       const segments = mapRecallTranscript(raw);
       let duration = durationFromSegments(segments);
+      let videoS3Key = null;
       const recId = recordingId ?? job.recall_recording_id;
       if (recId) {
         try {
           const rec = await recallClient.retrieveRecording(recId);
           const recDuration = recordingDurationSeconds(rec);
           if (recDuration != null) duration = recDuration;
+          if (recallStoreVideoLocally()) {
+            try {
+              videoS3Key = await downloadAndStoreRecordingVideo(
+                rec,
+                jobId,
+                exuluApp.get().config
+              );
+            } catch (err) {
+              log3(`could not store video locally for job ${jobId}: ${err.message}`);
+            }
+          }
         } catch (err) {
           log3(`could not fetch recording duration for job ${jobId}: ${err.message}`);
         }
@@ -11965,6 +12013,7 @@ var recallService = {
         recall_transcript_id: transcriptId ?? job.recall_transcript_id ?? null,
         raw_segments: JSON.stringify(segments),
         duration_seconds: duration,
+        ...videoS3Key ? { video_s3key: videoS3Key } : {},
         status: "awaiting_review"
       });
     } catch (err) {
@@ -13286,6 +13335,9 @@ type PageInfo {
   typeDefs += `
    meetingRecordingUsage: MeetingRecordingUsage
     `;
+  typeDefs += `
+   recordingVideoUrl(job_id: ID!): String
+    `;
   typeDefs += `
    workflowTriggers(workflow: ID!): [WorkflowTrigger!]!
     `;
@@ -14232,6 +14284,13 @@ type LiteLLMModel {
     if (!context.user) throw new Error("Authentication required");
     return recallService.getUsage();
   };
+  resolvers.Query["recordingVideoUrl"] = async (_, args, context) => {
+    await assertOwnsTranscriptionJob(args.job_id, context);
+    const { db } = context;
+    const row = await db.from("transcription_jobs").select(["recall_recording_id"]).where({ id: args.job_id }).first();
+    if (!row?.recall_recording_id) return null;
+    return recallService.getRecordingVideoUrl(row.recall_recording_id);
+  };
   resolvers.Query["evals"] = async (_, args, context, info) => {
     const requestedFields = getRequestedFields(info);
     return {
@@ -21314,7 +21373,10 @@ var transcriptionsContext = new ExuluContext2({
     // Link back to the Recall recording so the mixed video stays reachable
     // (resolve a fresh URL via ExuluRecall.getRecordingVideoUrl — it expires
     // after six hours). Null for Whisper uploads.
-    { name: "recall_recording_id", type: "text" }
+    { name: "recall_recording_id", type: "text" },
+    // Permanent local copy of the mixed video, present only when
+    // RECALL_STORE_VIDEO_LOCALLY=true was set at recording time.
+    { name: "video", type: "file" }
   ],
   sources: [],
   active: true,
@@ -21741,6 +21803,11 @@ var ExuluApp = class {
   get audit() {
     return this._audit ?? getAuditLogger(this._config ?? {});
   }
+  /** The deployment's ExuluConfig, for background/webhook code paths that
+   *  have no request to read it off (e.g. the Recall webhook handler). */
+  get config() {
+    return this._config ?? {};
+  }
   embeddings = {
     generate: {
       one: async ({ context: contextId, item: itemId }) => {

package/dist/{python-setup-DRJ3QX5F.js → python-setup-UYSNAW5V.js}

@@ -6,7 +6,7 @@ import {
   isPythonEnvironmentSetup,
   setupPythonEnvironment,
   validatePythonEnvironment
-} from "./chunk-QMN6MVHQ.js";
+} from "./chunk-JIZCKSJO.js";
 export {
   getPackageRoot,
   getPythonSetupInstructions,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exulu/backend",
   "author": "Qventu B.V.",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "main": "./dist/index.js",
   "private": false,
   "publishConfig": {

package/scripts/postinstall.cjs

@@ -156,15 +156,21 @@ async function main() {
     return;
   }
 
-  // Check if already exists
+  // We deliberately do NOT skip running setup.sh just because the venv
+  // directory and a `python` binary already exist (pythonEnvironmentExists()
+  // only checks that much, not that requirements.txt is fully installed).
+  // ee/python/setup.sh is itself idempotent — it only skips *recreating* the
+  // venv, never skips `pip install -r requirements.txt` — so always invoking
+  // it is cheap when nothing is missing (a few seconds) and is the only way
+  // to guarantee a venv created before a new requirement was added (e.g.
+  // python-docx, 2026-09-11) actually gets it installed. This used to return
+  // early here whenever the venv folder was merely present, which silently
+  // left newly-added dependencies uninstalled across any install that reused
+  // an older venv — see the docx-manipulation skill incident on dx-algi,
+  // 2026-09-21.
   if (pythonEnvironmentExists()) {
-    console.log(`${colors.green}✓${colors.reset} Python environment already set up`);
+    console.log(`${colors.blue}ℹ${colors.reset} Python environment directory already exists — verifying and installing any missing dependencies...`);
     console.log('');
-    console.log('To rebuild, run:');
-    console.log(`  ${colors.green}import { setupPythonEnvironment } from '@exulu/backend';${colors.reset}`);
-    console.log(`  ${colors.green}await setupPythonEnvironment({ force: true });${colors.reset}`);
-    console.log('');
-    return;
   }
 
   // Run setup