agentxl 1.0.0 → 1.1.2

package/dist/server/document-converter.js

@@ -0,0 +1,353 @@
+/**
+ * Document pre-converter — converts binary documents to readable Markdown.
+ *
+ * Runs at scan time (or on demand). Cached converted files live alongside
+ * the source files in a `.agentxl-cache/` directory inside the linked folder.
+ *
+ * PDF conversion strategy:
+ * 1. Try pdf-parse (fast, local, free) — extracts embedded text
+ * 2. Check if extracted text is meaningful (chars-per-page heuristic)
+ * 3. If scanned/image PDF → fall back to Mistral OCR API
+ *
+ * XLSX and DOCX are NOT pre-converted — the agent writes extraction code
+ * at runtime via bash, which is more powerful for structured data.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "fs";
+import { join, dirname, basename, relative } from "path";
+/** Name of the cache directory inside the linked folder. */
+const CACHE_DIR = ".agentxl-cache";
+/**
+ * Minimum average characters per page to consider text extraction successful.
+ * Below this threshold, the PDF is likely scanned/image-based and needs OCR.
+ */
+const MIN_CHARS_PER_PAGE = 50;
+/**
+ * Extract text from a PDF using pdf-parse (local, no API call).
+ * Returns null if the PDF has no meaningful embedded text.
+ */
+async function extractPdfText(pdfPath) {
+    try {
+        const { PDFParse } = await import("pdf-parse");
+        const buffer = readFileSync(pdfPath);
+        const parser = new PDFParse({ data: new Uint8Array(buffer) });
+        const result = await parser.getText();
+        let title;
+        let author;
+        try {
+            const infoResult = await parser.getInfo();
+            const meta = infoResult?.info;
+            if (meta?.Title && typeof meta.Title === "string")
+                title = meta.Title;
+            if (meta?.Author && typeof meta.Author === "string")
+                author = meta.Author;
+        }
+        catch {
+            // Metadata is optional
+        }
+        await parser.destroy();
+        const cleanText = result.text.trim();
+        return {
+            text: cleanText,
+            pageCount: result.total,
+            title,
+            author,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if extracted text is meaningful (not just whitespace/control chars).
+ * Scanned PDFs often return empty or near-empty text.
+ */
+function isTextMeaningful(text, pageCount) {
+    if (!text || pageCount === 0)
+        return false;
+    // Strip whitespace and control characters
+    const meaningful = text.replace(/[\s\x00-\x1f]/g, "");
+    const charsPerPage = meaningful.length / pageCount;
+    return charsPerPage >= MIN_CHARS_PER_PAGE;
+}
+/**
+ * Detect which OCR provider is available.
+ * Priority: Azure Mistral (enterprise) → direct Mistral → null
+ */
+function getOcrConfig() {
+    // Azure Mistral (enterprise — Azure AI Services)
+    const azureEndpoint = process.env.AZURE_MISTRAL_ENDPOINT?.trim();
+    const azureKey = process.env.AZURE_MISTRAL_API_KEY?.trim();
+    if (azureEndpoint && azureKey) {
+        return { provider: "azure-mistral", endpoint: azureEndpoint, apiKey: azureKey };
+    }
+    // Direct Mistral API
+    const mistralKey = process.env.MISTRAL_API_KEY?.trim();
+    if (mistralKey) {
+        return { provider: "mistral", apiKey: mistralKey };
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Azure Mistral OCR
+// ---------------------------------------------------------------------------
+/**
+ * OCR a PDF using Azure-hosted Mistral OCR.
+ * Sends the PDF as a base64 data URL — no file upload step needed.
+ */
+async function ocrWithAzureMistral(pdfPath, endpoint, apiKey) {
+    const buffer = readFileSync(pdfPath);
+    const base64 = buffer.toString("base64");
+    const dataUrl = `data:application/pdf;base64,${base64}`;
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "api-key": apiKey,
+        },
+        body: JSON.stringify({
+            model: "mistral-ocr-latest",
+            document: {
+                type: "document_url",
+                document_url: dataUrl,
+            },
+            table_format: "markdown",
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Azure Mistral OCR failed (${response.status}): ${body.slice(0, 200)}`);
+    }
+    const result = (await response.json());
+    return result.pages.map((p) => p.markdown).join("\n\n---\n\n");
+}
+// ---------------------------------------------------------------------------
+// Direct Mistral OCR
+// ---------------------------------------------------------------------------
+/**
+ * OCR a PDF using Mistral's direct API.
+ * Uploads the file, runs OCR, returns markdown.
+ */
+async function ocrWithDirectMistral(pdfPath, apiKey) {
+    const { Mistral } = await import("@mistralai/mistralai");
+    const client = new Mistral({ apiKey });
+    // Upload the PDF file
+    const buffer = readFileSync(pdfPath);
+    const fileName = basename(pdfPath);
+    const blob = new Blob([buffer], { type: "application/pdf" });
+    const file = new File([blob], fileName, { type: "application/pdf" });
+    const uploaded = await client.files.upload({
+        file,
+        purpose: "ocr",
+    });
+    // Run OCR
+    const ocrResult = await client.ocr.process({
+        model: "mistral-ocr-latest",
+        document: {
+            type: "file",
+            fileId: uploaded.id,
+        },
+        tableFormat: "markdown",
+    });
+    // Combine all pages into markdown
+    const pages = ocrResult.pages.map((page) => page.markdown);
+    // Clean up the uploaded file (best effort)
+    try {
+        await client.files.delete({ fileId: uploaded.id });
+    }
+    catch {
+        // Non-fatal
+    }
+    return pages.join("\n\n---\n\n");
+}
+// ---------------------------------------------------------------------------
+// Unified OCR dispatcher
+// ---------------------------------------------------------------------------
+/**
+ * OCR a PDF using the best available provider.
+ */
+async function ocrPdf(pdfPath) {
+    const config = getOcrConfig();
+    if (!config) {
+        throw new Error("No OCR provider configured. Scanned PDFs need Mistral OCR.\n" +
+            "Set AZURE_MISTRAL_ENDPOINT + AZURE_MISTRAL_API_KEY (Azure)\n" +
+            "or MISTRAL_API_KEY (direct) in .env to enable OCR.");
+    }
+    if (config.provider === "azure-mistral") {
+        return ocrWithAzureMistral(pdfPath, config.endpoint, config.apiKey);
+    }
+    return ocrWithDirectMistral(pdfPath, config.apiKey);
+}
+// ---------------------------------------------------------------------------
+// PDF → Markdown (smart: text-first, OCR fallback)
+// ---------------------------------------------------------------------------
+/**
+ * Convert a single PDF to Markdown.
+ *
+ * Strategy:
+ * 1. Try local text extraction (pdf-parse) — fast, free
+ * 2. If text is empty/sparse → PDF is scanned → use Mistral OCR
+ * 3. If no Mistral key → return what we have with a warning
+ */
+async function pdfToMarkdown(pdfPath) {
+    const fileName = basename(pdfPath);
+    // Step 1: Try local text extraction
+    const extraction = await extractPdfText(pdfPath);
+    if (extraction && isTextMeaningful(extraction.text, extraction.pageCount)) {
+        // Good text extraction — use it directly
+        return formatPdfMarkdown(fileName, extraction.text, extraction.pageCount, {
+            title: extraction.title,
+            author: extraction.author,
+            method: "text-extraction",
+        });
+    }
+    // Step 2: Text is empty/sparse — try OCR (Azure Mistral or direct Mistral)
+    const pageCount = extraction?.pageCount ?? 0;
+    const sparseText = extraction?.text ?? "";
+    try {
+        const ocrText = await ocrPdf(pdfPath);
+        const config = getOcrConfig();
+        return formatPdfMarkdown(fileName, ocrText, pageCount, {
+            title: extraction?.title,
+            author: extraction?.author,
+            method: config?.provider === "azure-mistral" ? "azure-mistral-ocr" : "mistral-ocr",
+        });
+    }
+    catch (err) {
+        const ocrError = err instanceof Error ? err.message : String(err);
+        // No OCR available — return whatever we got (possibly empty)
+        if (sparseText) {
+            return formatPdfMarkdown(fileName, sparseText, pageCount, {
+                title: extraction?.title,
+                author: extraction?.author,
+                method: "text-extraction (partial)",
+                warning: `This PDF appears to be scanned/image-based. Text extraction may be incomplete. OCR failed: ${ocrError}`,
+            });
+        }
+        return `# ${fileName}\n\n> ⚠️ This PDF is scanned/image-based and could not be read.\n> Text extraction returned no content.\n> OCR failed: ${ocrError}\n\nSet AZURE_MISTRAL_ENDPOINT + AZURE_MISTRAL_API_KEY or MISTRAL_API_KEY to enable OCR.`;
+    }
+}
+/**
+ * Format extracted PDF content as clean Markdown.
+ */
+function formatPdfMarkdown(fileName, text, pageCount, opts) {
+    const lines = [
+        `# ${fileName}`,
+        "",
+        `> Extracted from PDF · ${pageCount} page${pageCount !== 1 ? "s" : ""} · ${opts.method}`,
+        "",
+    ];
+    if (opts.title)
+        lines.push(`**Title:** ${opts.title}  `);
+    if (opts.author)
+        lines.push(`**Author:** ${opts.author}  `);
+    if (opts.title || opts.author)
+        lines.push("");
+    if (opts.warning) {
+        lines.push(`> ⚠️ ${opts.warning}`, "");
+    }
+    lines.push("---", "", text.trim());
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Cache management
+// ---------------------------------------------------------------------------
+/**
+ * Get the cache path for a converted file.
+ * E.g., `subfolder/invoice.pdf` → `<folderRoot>/.agentxl-cache/subfolder/invoice.pdf.md`
+ */
+function getCachePath(folderRoot, relativePath) {
+    return join(folderRoot, CACHE_DIR, `${relativePath}.md`);
+}
+/**
+ * Check if a cached conversion exists and is newer than the source file.
+ */
+function isCacheValid(sourcePath, cachePath) {
+    if (!existsSync(cachePath))
+        return false;
+    try {
+        const sourceTime = statSync(sourcePath).mtimeMs;
+        const cacheTime = statSync(cachePath).mtimeMs;
+        return cacheTime >= sourceTime;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pre-convert all PDFs in an inventory to Markdown.
+ * Skips files where the cache is still valid (source not modified).
+ *
+ * @param inventory - Folder inventory from scanner
+ * @returns Summary of conversion results
+ */
+export async function convertDocuments(inventory) {
+    const result = {
+        converted: 0,
+        ocrConverted: 0,
+        cached: 0,
+        failed: 0,
+        errors: [],
+    };
+    const pdfs = inventory.files.filter((f) => f.extension === ".pdf" && f.supported);
+    if (pdfs.length === 0)
+        return result;
+    for (const file of pdfs) {
+        const cachePath = getCachePath(inventory.folderPath, file.relativePath);
+        // Skip if cache is still valid
+        if (isCacheValid(file.absolutePath, cachePath)) {
+            result.cached++;
+            continue;
+        }
+        try {
+            const markdown = await pdfToMarkdown(file.absolutePath);
+            // Detect which method was used
+            const usedOcr = markdown.includes("mistral-ocr");
+            // Ensure cache directory exists
+            const cacheDir = dirname(cachePath);
+            mkdirSync(cacheDir, { recursive: true });
+            writeFileSync(cachePath, markdown, "utf-8");
+            if (usedOcr) {
+                result.ocrConverted++;
+            }
+            else {
+                result.converted++;
+            }
+        }
+        catch (err) {
+            result.failed++;
+            result.errors.push(`${file.relativePath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
+}
+/**
+ * Get the markdown path for a source file, if it has been converted.
+ * Returns null if no cached conversion exists.
+ */
+export function getConvertedPath(folderRoot, relativePath) {
+    const cachePath = getCachePath(folderRoot, relativePath);
+    return existsSync(cachePath) ? cachePath : null;
+}
+/**
+ * Build a list of converted markdown files for agent context.
+ * Returns entries like: `invoice.pdf → .agentxl-cache/invoice.pdf.md`
+ */
+export function listConvertedFiles(inventory) {
+    const entries = [];
+    for (const file of inventory.files) {
+        if (file.extension === ".pdf") {
+            const cachePath = getCachePath(inventory.folderPath, file.relativePath);
+            if (existsSync(cachePath)) {
+                const convertedRelative = relative(inventory.folderPath, cachePath).replace(/\\/g, "/");
+                entries.push({
+                    source: file.relativePath,
+                    converted: convertedRelative,
+                });
+            }
+        }
+    }
+    return entries;
+}
+// Exports for testing
+export { isTextMeaningful, getOcrConfig, MIN_CHARS_PER_PAGE };
+//# sourceMappingURL=document-converter.js.map

package/dist/server/document-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-converter.js","sourceRoot":"","sources":["../../src/server/document-converter.ts"],"names":[],"mappings":"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"}

package/dist/server/excel-bridge.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Excel execution bridge — bidirectional communication between
+ * server-side tool execution and browser-side Office.js.
+ *
+ * Flow:
+ * 1. Agent calls `excel` custom tool with Office.js code
+ * 2. Tool execute() registers a pending execution and waits
+ * 3. Pi SDK emits tool_execution_start SSE → taskpane receives it
+ * 4. Taskpane runs the code inside Excel.run() via Office.js
+ * 5. Taskpane POSTs result to /api/excel/result
+ * 6. Bridge resolves the pending promise → tool returns result to agent
+ */
+/**
+ * Register a pending Excel execution and return a promise that resolves
+ * when the taskpane sends the result back.
+ *
+ * Called by the `excel` custom tool's execute function.
+ */
+export declare function registerPendingExecution(toolCallId: string, timeoutMs?: number): Promise<string>;
+/**
+ * Resolve a pending execution with a successful result.
+ * Called when the taskpane POSTs to /api/excel/result.
+ *
+ * @returns true if the execution was found and resolved.
+ */
+export declare function resolveExecution(toolCallId: string, result: string): boolean;
+/**
+ * Reject a pending execution with an error.
+ * Called when the taskpane reports an Office.js error.
+ *
+ * @returns true if the execution was found and rejected.
+ */
+export declare function rejectExecution(toolCallId: string, errorMessage: string): boolean;
+/** Get count of pending executions (for diagnostics). */
+export declare function getPendingCount(): number;
+/** Clear all pending executions (for cleanup/testing). */
+export declare function clearAllPending(): void;
+//# sourceMappingURL=excel-bridge.d.ts.map

package/dist/server/excel-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-bridge.d.ts","sourceRoot":"","sources":["../../src/server/excel-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAQT;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAQT;AAED,yDAAyD;AACzD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,0DAA0D;AAC1D,wBAAgB,eAAe,IAAI,IAAI,CAMtC"}

package/dist/server/excel-bridge.js

@@ -0,0 +1,75 @@
+/**
+ * Excel execution bridge — bidirectional communication between
+ * server-side tool execution and browser-side Office.js.
+ *
+ * Flow:
+ * 1. Agent calls `excel` custom tool with Office.js code
+ * 2. Tool execute() registers a pending execution and waits
+ * 3. Pi SDK emits tool_execution_start SSE → taskpane receives it
+ * 4. Taskpane runs the code inside Excel.run() via Office.js
+ * 5. Taskpane POSTs result to /api/excel/result
+ * 6. Bridge resolves the pending promise → tool returns result to agent
+ */
+/** Default timeout for Excel execution (ms). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** Map of toolCallId → pending execution promise. */
+const pending = new Map();
+/**
+ * Register a pending Excel execution and return a promise that resolves
+ * when the taskpane sends the result back.
+ *
+ * Called by the `excel` custom tool's execute function.
+ */
+export function registerPendingExecution(toolCallId, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            pending.delete(toolCallId);
+            reject(new Error(`Excel execution timed out after ${timeoutMs / 1000}s. ` +
+                `The taskpane may not be connected or Excel may be unresponsive.`));
+        }, timeoutMs);
+        pending.set(toolCallId, { resolve, reject, timeout });
+    });
+}
+/**
+ * Resolve a pending execution with a successful result.
+ * Called when the taskpane POSTs to /api/excel/result.
+ *
+ * @returns true if the execution was found and resolved.
+ */
+export function resolveExecution(toolCallId, result) {
+    const entry = pending.get(toolCallId);
+    if (!entry)
+        return false;
+    clearTimeout(entry.timeout);
+    pending.delete(toolCallId);
+    entry.resolve(result);
+    return true;
+}
+/**
+ * Reject a pending execution with an error.
+ * Called when the taskpane reports an Office.js error.
+ *
+ * @returns true if the execution was found and rejected.
+ */
+export function rejectExecution(toolCallId, errorMessage) {
+    const entry = pending.get(toolCallId);
+    if (!entry)
+        return false;
+    clearTimeout(entry.timeout);
+    pending.delete(toolCallId);
+    entry.reject(new Error(`Excel error: ${errorMessage}`));
+    return true;
+}
+/** Get count of pending executions (for diagnostics). */
+export function getPendingCount() {
+    return pending.size;
+}
+/** Clear all pending executions (for cleanup/testing). */
+export function clearAllPending() {
+    for (const [id, entry] of pending) {
+        clearTimeout(entry.timeout);
+        entry.reject(new Error("Cleared"));
+    }
+    pending.clear();
+}
+//# sourceMappingURL=excel-bridge.js.map

package/dist/server/excel-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-bridge.js","sourceRoot":"","sources":["../../src/server/excel-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gDAAgD;AAChD,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAQlC,qDAAqD;AACrD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA4B,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAkB,EAClB,YAAoB,kBAAkB;IAEtC,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC7C,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC3B,MAAM,CACJ,IAAI,KAAK,CACP,mCAAmC,SAAS,GAAG,IAAI,KAAK;gBACtD,iEAAiE,CACpE,CACF,CAAC;QACJ,CAAC,EAAE,SAAS,CAAC,CAAC;QAEd,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAAkB,EAClB,MAAc;IAEd,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC3B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAkB,EAClB,YAAoB;IAEpB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC3B,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gBAAgB,YAAY,EAAE,CAAC,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,eAAe;IAC7B,OAAO,OAAO,CAAC,IAAI,CAAC;AACtB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,eAAe;IAC7B,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QAClC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5B,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC"}

package/dist/server/folder-picker.d.ts

@@ -0,0 +1,9 @@
+export interface FolderPickerStrategy {
+    platform: string;
+    method: "native-helper" | "powershell" | "osascript" | "manual-only";
+    helperPath: string | null;
+}
+/** Detect which folder picker strategy will be used at runtime. */
+export declare function getFolderPickerStrategy(): FolderPickerStrategy;
+export declare function pickLocalFolder(initialPath?: string | null): Promise<string | null>;
+//# sourceMappingURL=folder-picker.d.ts.map

package/dist/server/folder-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-picker.d.ts","sourceRoot":"","sources":["../../src/server/folder-picker.ts"],"names":[],"mappings":"AAyOA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,CAAC;IACrE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,mEAAmE;AACnE,wBAAgB,uBAAuB,IAAI,oBAAoB,CAgB9D;AAED,wBAAsB,eAAe,CACnC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiExB"}