@exulu/backend 2.2.0 → 3.0.0

package/dist/{chunk-Y7JPNBFM.js → chunk-KFL7HIID.js}

@@ -1,4 +1,7 @@
 import "dotenv/config";
+import {
+  findLiteLLMModel
+} from "./chunk-7CCMW3IW.js";
 
 // src/templates/tools/convert-exulu-tools-to-ai-sdk-tools.ts
 import { S3Client as S3Client2, PutObjectCommand as PutObjectCommand2, S3ServiceException } from "@aws-sdk/client-s3";
@@ -1715,7 +1718,7 @@ var ExuluTool = class _ExuluTool {
       });
       providerapikey = resolved.apiKey;
     }
-    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-M7I2TZQQ.js");
+    const { convertExuluToolsToAiSdkTools: convertExuluToolsToAiSdkTools2 } = await import("./convert-exulu-tools-to-ai-sdk-tools-YY2WIMMJ.js");
     const tools = await convertExuluToolsToAiSdkTools2(
       [this],
       [],
@@ -5381,6 +5384,15 @@ var REQUIRED_SYSTEM_DEPENDENCIES = [
       macos: "brew install poppler"
     }
   },
+  {
+    check: { kind: "binary", binary: "pdftotext" },
+    displayName: "Poppler (pdftotext)",
+    purpose: "parse_document tool: extracting page-marked text from PDFs",
+    installHints: {
+      debian: "apt-get install -y poppler-utils",
+      macos: "brew install poppler"
+    }
+  },
   {
     check: { kind: "npm-global", packageName: "docx" },
     displayName: "docx (npm global)",
@@ -6223,6 +6235,469 @@ var createSessionFileReadTool = ({
   });
 };
 
+// src/templates/tools/parse-document-tool.ts
+import { z as z11 } from "zod";
+import { extname } from "path";
+import { parseOfficeAsync } from "officeparser";
+
+// src/templates/tools/document-render-helpers.ts
+import { execFile } from "child_process";
+import { promisify as promisify3 } from "util";
+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;
+async function pdfToText(pdf) {
+  const dir = await mkdtemp(join3(tmpdir(), "exulu-parse-"));
+  try {
+    const inputPath = join3(dir, "input.pdf");
+    await writeFile2(inputPath, pdf);
+    const { stdout } = await execFileAsync("pdftotext", ["-layout", inputPath, "-"], {
+      timeout: 6e4,
+      maxBuffer: MAX_STDOUT_BYTES
+    });
+    return stdout;
+  } finally {
+    await rm2(dir, { recursive: true, force: true });
+  }
+}
+async function renderPdfPageToPng(pdf, page, scaleTo) {
+  const dir = await mkdtemp(join3(tmpdir(), "exulu-render-"));
+  try {
+    const inputPath = join3(dir, "input.pdf");
+    await writeFile2(inputPath, pdf);
+    try {
+      await execFileAsync(
+        "pdftoppm",
+        ["-png", "-f", String(page), "-l", String(page), "-scale-to", String(scaleTo), inputPath, join3(dir, "page")],
+        { timeout: 6e4, maxBuffer: MAX_STDOUT_BYTES }
+      );
+    } catch (err) {
+      if (err?.code === 99) return null;
+      throw err;
+    }
+    const produced = (await readdir2(dir)).find((f) => f.startsWith("page") && f.endsWith(".png"));
+    if (!produced) return null;
+    return await readFile(join3(dir, produced));
+  } finally {
+    await rm2(dir, { recursive: true, force: true });
+  }
+}
+
+// src/templates/tools/parse-document-tool.ts
+var DEFAULT_LIMIT2 = 250;
+var MAX_CONTENT_CHARS2 = 16e3;
+var MIN_CHARS_PER_PAGE = 20;
+var OFFICE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".docx",
+  ".doc",
+  ".xlsx",
+  ".xls",
+  ".pptx",
+  ".ppt",
+  ".odt",
+  ".ods",
+  ".odp",
+  ".rtf"
+]);
+var pagesPattern = /^(\d+)(?:-(\d+))?$/;
+var createParseDocumentTool = ({
+  sessionID,
+  user,
+  exuluConfig
+}) => {
+  if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
+  const parseDocumentExecute = async ({
+    filename,
+    pages,
+    offset,
+    limit
+  }) => {
+    const safeName = String(filename ?? "").trim();
+    if (!safeName || safeName.includes("..") || safeName.includes("/") || safeName.includes("\\")) {
+      return {
+        error: "Invalid filename \u2014 pass the bare file name exactly as listed in the session files (no paths)."
+      };
+    }
+    const ext = extname(safeName).toLowerCase();
+    if (ext !== ".pdf" && !OFFICE_EXTENSIONS.has(ext)) {
+      return {
+        error: `Unsupported extension "${ext}" \u2014 parse_document handles PDF and Office formats. For plain-text files use read_session_file.`
+      };
+    }
+    if (pages && ext !== ".pdf") {
+      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}`;
+    try {
+      const url = await getPresignedUrl(uploads.s3Bucket, key, exuluConfig);
+      const res = await fetch(url);
+      if (!res.ok) {
+        return { error: `Could not read session file "${safeName}" (status ${res.status}). Check the exact file name.` };
+      }
+      const bytes = Buffer.from(await res.arrayBuffer());
+      let fullText;
+      let totalPages;
+      if (ext === ".pdf") {
+        const raw = await pdfToText(bytes);
+        const pageTexts = raw.replace(/\f$/, "").split("\f");
+        totalPages = pageTexts.length;
+        const nonWhitespace = raw.replace(/\s/g, "").length;
+        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.`
+          };
+        }
+        let range = [1, totalPages];
+        if (pages) {
+          const m = pagesPattern.exec(pages.trim());
+          if (!m) return { error: `Invalid pages "${pages}" \u2014 use "3" or "2-5".` };
+          range = [Number(m[1]), Number(m[2] ?? m[1])];
+          if (range[0] < 1 || range[0] > range[1]) {
+            return { error: `Invalid pages "${pages}" \u2014 start must be at least 1 and not greater than the end.` };
+          }
+          if (range[0] > totalPages) {
+            return { error: `Page range starts at ${range[0]} but "${safeName}" has only ${totalPages} page${totalPages === 1 ? "" : "s"}.` };
+          }
+        }
+        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, {
+          outputErrorToConsole: false,
+          newlineDelimiter: "\n"
+        });
+        fullText = String(extracted);
+      }
+      const lines = fullText.split("\n");
+      const start = (offset ?? 1) - 1;
+      const requested = limit ?? DEFAULT_LIMIT2;
+      const sliced = lines.slice(start, start + requested);
+      let content = sliced.join("\n");
+      let linesReturned = sliced.length;
+      if (content.length > MAX_CONTENT_CHARS2) {
+        content = content.slice(0, MAX_CONTENT_CHARS2);
+        linesReturned = Math.max(1, content.split("\n").length - 1);
+        content = content + "\n[slice truncated \u2014 request fewer lines]";
+      }
+      return {
+        content,
+        ...totalPages !== void 0 ? { totalPages } : {},
+        totalLines: lines.length,
+        offset: start + 1,
+        linesReturned
+      };
+    } catch (err) {
+      return { error: `Failed to parse "${safeName}": ${err instanceof Error ? err.message : "unknown error"}` };
+    }
+  };
+  return ExuluTool.internal({
+    id: "parse_document",
+    name: "parse_document",
+    needsApproval: false,
+    description: `Extract the text of an uploaded PDF or Office document from this session's files, with "--- page N ---" markers for PDFs so you can locate content by page. Free and fast (no OCR): works only on documents with a real text layer. To SEE a page or an image inside a document, use view_document_page.`,
+    inputSchema: z11.object({
+      filename: z11.string().describe('Exact session file name, e.g. "report.pdf"'),
+      pages: z11.string().optional().describe('PDF page or range to extract, e.g. "2" or "1-5" (default: all pages) (PDF only)'),
+      offset: z11.number().int().min(1).optional().describe("1-based first output line to read (default 1)"),
+      limit: z11.number().int().min(1).max(1e3).optional().describe(`Number of lines to read (default ${DEFAULT_LIMIT2})`)
+    }),
+    type: "function",
+    category: "session",
+    config: [],
+    // Same shape mismatch as read_session_file / memory-tool: internal utility
+    // tools return richer objects than ExuluTool's retrieval-flavored execute
+    // type; the AI SDK passes the object through verbatim.
+    execute: parseDocumentExecute
+  });
+};
+
+// src/templates/tools/view-document-page-tool.ts
+import { z as z12 } from "zod";
+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 { 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";
+var execAsync3 = promisify4(exec3);
+var CACHE_ROOT = "/tmp/exulu-pdf-cache";
+var CACHE_IN = join4(CACHE_ROOT, "_in");
+var CACHE_OUT = join4(CACHE_ROOT, "_out");
+var inFlight = /* @__PURE__ */ new Map();
+var PreviewRenderError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PreviewRenderError";
+  }
+};
+function sanitizeEtag(raw) {
+  return raw.replace(/^"|"$/g, "").replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+async function getPdfPreviewBytes(opts) {
+  const { sourceKey, etag, config } = opts;
+  const safeEtag = sanitizeEtag(etag);
+  if (!safeEtag) {
+    throw new PreviewRenderError(`Invalid ETag for ${sourceKey}`);
+  }
+  const cachedPath = join4(CACHE_ROOT, `${safeEtag}.pdf`);
+  if (existsSync4(cachedPath)) {
+    return readFile2(cachedPath);
+  }
+  const existing = inFlight.get(safeEtag);
+  if (existing) return existing;
+  const promise = (async () => {
+    try {
+      await mkdir2(CACHE_IN, { recursive: true });
+      await mkdir2(CACHE_OUT, { recursive: true });
+      const ext = (extname2(sourceKey) || ".docx").toLowerCase();
+      const inputPath = join4(CACHE_IN, `${safeEtag}${ext}`);
+      const outputPath = join4(CACHE_OUT, `${safeEtag}.pdf`);
+      try {
+        const bytes = await getS3ObjectBytes(sourceKey, config);
+        await writeFile3(inputPath, bytes);
+        try {
+          await execAsync3(
+            `soffice --headless --convert-to pdf "${inputPath}" --outdir "${CACHE_OUT}"`,
+            { timeout: 6e4, maxBuffer: 16 * 1024 * 1024 }
+          );
+        } catch (err) {
+          throw new PreviewRenderError(
+            `LibreOffice conversion failed for ${sourceKey} (etag ${etag}): ${err?.stderr ?? err?.message ?? "unknown error"}`
+          );
+        }
+        if (!existsSync4(outputPath)) {
+          throw new PreviewRenderError(
+            `LibreOffice produced no output for ${sourceKey} (etag ${etag})`
+          );
+        }
+        await rename(outputPath, cachedPath);
+        return await readFile2(cachedPath);
+      } finally {
+        await rm3(inputPath, { force: true });
+      }
+    } finally {
+      inFlight.delete(safeEtag);
+    }
+  })();
+  inFlight.set(safeEtag, promise);
+  return promise;
+}
+
+// src/exulu/tool-image-attachments.ts
+var INJECTED_IMAGE_PREFIX = "[Image attached from tool call ";
+var stash = /* @__PURE__ */ new Map();
+var MAX_ENTRIES = 100;
+var TTL_MS = 30 * 60 * 1e3;
+var MAX_TOTAL_BYTES = 1e8;
+var STASH_TOOL_NAME = "view_document_page";
+function sweep() {
+  const cutoff = Date.now() - TTL_MS;
+  for (const [id, entry] of stash) {
+    if (entry.stashedAt < cutoff) stash.delete(id);
+  }
+  while (stash.size > MAX_ENTRIES) {
+    const oldest = stash.keys().next().value;
+    if (oldest === void 0) break;
+    stash.delete(oldest);
+  }
+  let totalBytes = 0;
+  for (const entry of stash.values()) totalBytes += entry.data.length;
+  while (totalBytes > MAX_TOTAL_BYTES) {
+    const oldest = stash.keys().next().value;
+    if (oldest === void 0) break;
+    totalBytes -= stash.get(oldest).data.length;
+    stash.delete(oldest);
+  }
+}
+function stashToolImage(toolCallId, image) {
+  stash.set(toolCallId, { ...image, stashedAt: Date.now() });
+  sweep();
+}
+function stashedIdsInMessage(message) {
+  if (message?.role !== "tool" || !Array.isArray(message.content)) return [];
+  return message.content.filter(
+    (p) => p?.type === "tool-result" && typeof p.toolCallId === "string" && p.toolName === STASH_TOOL_NAME && stash.has(p.toolCallId)
+  ).map((p) => p.toolCallId);
+}
+function injectedTextFor(id, label) {
+  return `${INJECTED_IMAGE_PREFIX}${id}: ${label}]`;
+}
+function firstTextPart(message) {
+  if (message?.role !== "user" || !Array.isArray(message.content)) return void 0;
+  const first = message.content[0];
+  return first?.type === "text" ? first.text : void 0;
+}
+function imageAttachmentGuard() {
+  return ({ messages }) => {
+    sweep();
+    if (!Array.isArray(messages) || messages.length === 0 || stash.size === 0) return void 0;
+    let changed = false;
+    const next = [];
+    for (let i = 0; i < messages.length; i++) {
+      const message = messages[i];
+      next.push(message);
+      const ids = stashedIdsInMessage(message);
+      if (ids.length === 0) continue;
+      const alreadyInjected = [];
+      for (let j = i + 1; j < messages.length; j++) {
+        const text = firstTextPart(messages[j]);
+        if (text === void 0 || !text.startsWith(INJECTED_IMAGE_PREFIX)) break;
+        alreadyInjected.push(text);
+      }
+      for (const id of ids) {
+        if (alreadyInjected.some((text) => text.startsWith(`${INJECTED_IMAGE_PREFIX}${id}:`))) continue;
+        const image = stash.get(id);
+        changed = true;
+        next.push({
+          role: "user",
+          content: [
+            { type: "text", text: injectedTextFor(id, image.label) },
+            { type: "image", image: image.data, mediaType: image.mediaType }
+          ]
+        });
+      }
+    }
+    return changed ? { messages: next } : void 0;
+  };
+}
+
+// src/templates/tools/view-document-page-tool.ts
+var MAX_IMAGE_BYTES = 375e4;
+var SCALE_PRIMARY = 1568;
+var SCALE_FALLBACK = 1024;
+var IMAGE_MEDIA_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp"
+};
+var OFFICE_EXTENSIONS2 = /* @__PURE__ */ new Set([
+  ".docx",
+  ".doc",
+  ".xlsx",
+  ".xls",
+  ".pptx",
+  ".ppt",
+  ".odt",
+  ".ods",
+  ".odp",
+  ".rtf"
+]);
+var createViewDocumentPageTool = ({
+  sessionID,
+  user,
+  exuluConfig
+}) => {
+  if (!sessionID || !exuluConfig?.fileUploads?.s3Bucket) return void 0;
+  const viewDocumentPageExecute = async ({ filename, page, model }, options) => {
+    const safeName = String(filename ?? "").trim();
+    if (!safeName || safeName.includes("..") || safeName.includes("/") || safeName.includes("\\")) {
+      return {
+        error: "Invalid filename \u2014 pass the bare file name exactly as listed in the session files (no paths)."
+      };
+    }
+    const ext = extname3(safeName).toLowerCase();
+    const isImage = ext in IMAGE_MEDIA_TYPES;
+    const isPdf = ext === ".pdf";
+    const isOffice = OFFICE_EXTENSIONS2.has(ext);
+    if (!isImage && !isPdf && !isOffice) {
+      return { error: `Unsupported extension "${ext}" \u2014 view_document_page handles PDF, Office, and image files.` };
+    }
+    const modelId = typeof model === "string" ? model : model?.modelId;
+    if (!modelId) {
+      console.warn("[EXULU] view_document_page: no model id available for vision gating \u2014 proceeding optimistically.");
+    }
+    if (modelId) {
+      try {
+        const entry = await findLiteLLMModel(modelId);
+        if (entry && entry.supports_vision === false) {
+          return {
+            error: `The current model "${modelId}" does not support images, so this page cannot be shown to you. Use parse_document for the text, or tell the user a vision-capable model is required.`
+          };
+        }
+      } catch {
+      }
+    }
+    const uploads = exuluConfig.fileUploads;
+    const generalPrefix = uploads.s3prefix ? `${uploads.s3prefix.replace(/\/$/, "")}/` : "";
+    const key = `${generalPrefix}user_${user?.id ?? "api"}/sessions/${sessionID}/${safeName}`;
+    const pageNumber = page ?? 1;
+    try {
+      let imageBytes;
+      let mediaType = "image/png";
+      if (isImage) {
+        imageBytes = await getS3ObjectBytes(key, exuluConfig);
+        mediaType = IMAGE_MEDIA_TYPES[ext];
+        if (imageBytes.length > MAX_IMAGE_BYTES) {
+          return {
+            error: `"${safeName}" is too large to attach (${imageBytes.length} bytes, max ${MAX_IMAGE_BYTES}). Ask the user for a smaller version of the image.`
+          };
+        }
+      } else {
+        let pdfBytes;
+        if (isPdf) {
+          pdfBytes = await getS3ObjectBytes(key, exuluConfig);
+        } else {
+          const etag = await getS3ObjectEtag(key, exuluConfig);
+          if (!etag) {
+            return { error: `Could not read session file "${safeName}". Check the exact file name.` };
+          }
+          pdfBytes = await getPdfPreviewBytes({ sourceKey: key, etag, config: exuluConfig });
+        }
+        let rendered = await renderPdfPageToPng(pdfBytes, pageNumber, SCALE_PRIMARY);
+        if (!rendered) {
+          return { error: `Could not render page ${pageNumber} of "${safeName}" \u2014 the document may have fewer pages.` };
+        }
+        if (rendered.length > MAX_IMAGE_BYTES) {
+          rendered = await renderPdfPageToPng(pdfBytes, pageNumber, SCALE_FALLBACK);
+        }
+        if (!rendered || rendered.length > MAX_IMAGE_BYTES) {
+          return { error: `Page ${pageNumber} of "${safeName}" is too complex to attach within the image size limit.` };
+        }
+        imageBytes = rendered;
+      }
+      if (!options?.toolCallId) {
+        return { error: "Internal error: missing toolCallId \u2014 the image cannot be attached." };
+      }
+      stashToolImage(options.toolCallId, {
+        data: imageBytes.toString("base64"),
+        mediaType,
+        label: isImage ? safeName : `${safeName} page ${pageNumber}`
+      });
+      return {
+        attached: true,
+        filename: safeName,
+        page: pageNumber,
+        note: "The rendered image follows this tool result as an attached user message \u2014 analyze it there. If no image message follows, the attachment has expired; call this tool again to re-render it."
+      };
+    } catch (err) {
+      return { error: `Failed to render "${safeName}": ${err instanceof Error ? err.message : "unknown error"}` };
+    }
+  };
+  return ExuluTool.internal({
+    id: "view_document_page",
+    name: "view_document_page",
+    needsApproval: false,
+    description: "LOOK at a page of an uploaded PDF/Office document, or at an uploaded image, from this session's files. The rendered image is attached as a user message directly after this tool result so you can visually analyze photos, charts, scans, and layouts. Use parse_document first to find which page you need. Requires a vision-capable model.",
+    inputSchema: z12.object({
+      filename: z12.string().describe('Exact session file name, e.g. "report.pdf" or "screenshot.png"'),
+      page: z12.number().int().min(1).optional().describe("Page number to render (default 1; ignored for image files)")
+    }),
+    type: "function",
+    category: "session",
+    config: [],
+    // Same execute-shape cast as read_session_file / parse_document.
+    execute: viewDocumentPageExecute
+  });
+};
+
 // src/templates/tools/convert-exulu-tools-to-ai-sdk-tools.ts
 var OUTPUT_OFFLOAD_EXEMPT_TOOL_IDS = /* @__PURE__ */ new Set(["agentic_context_search"]);
 var generateS3Key = (filename) => `${randomUUID4()}-${filename}`;
@@ -6404,6 +6879,14 @@ var convertExuluToolsToAiSdkTools = async (currentTools, currentSkills, approved
   if (sessionFileReadTool && !disabled.has(sessionFileReadTool.id)) {
     currentTools.push(sessionFileReadTool);
   }
+  const parseDocumentTool = createParseDocumentTool({ sessionID, user, exuluConfig });
+  if (parseDocumentTool && !disabled.has(parseDocumentTool.id)) {
+    currentTools.push(parseDocumentTool);
+  }
+  const viewDocumentPageTool = createViewDocumentPageTool({ sessionID, user, exuluConfig });
+  if (viewDocumentPageTool && !disabled.has(viewDocumentPageTool.id)) {
+    currentTools.push(viewDocumentPageTool);
+  }
   console.log("[EXULU] Creating agentic search tool", contexts?.length, model);
   if (contexts?.length && model && !disabled.has("agentic_context_search")) {
     const index = currentTools.findIndex((tool3) => tool3.id === "agentic_context_search");
@@ -6713,6 +7196,8 @@ export {
   resolveModel,
   exuluApp,
   oauthRegistry,
+  encrypt,
+  decrypt,
   oauthTokenStore,
   OAUTH_CALLBACK_PATH,
   decryptOauthState,
@@ -6731,6 +7216,9 @@ export {
   ContextCompactionRequiredError,
   mapStreamErrorMessage,
   guardExtractedFileText,
+  PreviewRenderError,
+  getPdfPreviewBytes,
+  imageAttachmentGuard,
   hydrateVariables,
   convertExuluToolsToAiSdkTools,
   ExuluTool,

package/dist/{convert-exulu-tools-to-ai-sdk-tools-M7I2TZQQ.js → convert-exulu-tools-to-ai-sdk-tools-YY2WIMMJ.js}

@@ -2,7 +2,8 @@ import "dotenv/config";
 import {
   convertExuluToolsToAiSdkTools,
   hydrateVariables
-} from "./chunk-Y7JPNBFM.js";
+} from "./chunk-KFL7HIID.js";
+import "./chunk-7CCMW3IW.js";
 export {
   convertExuluToolsToAiSdkTools,
   hydrateVariables