agent-nuvira 3.3.1 → 3.3.4

package/dist/tools/read-extract.js

@@ -1,34 +1,102 @@
 /**
  * read_extract — Document-to-text extraction.
  *
- * Extracts text from various document formats:
- * - PDF documents
- * - Microsoft Word (DOCX)
- * - Microsoft Excel (XLSX)
- * - Microsoft PowerPoint (PPTX)
- * - Plain text files
- * - Markdown files
- * - HTML files
+ * IMPLEMENTED:
+ *   - Text-ish: plain text, Markdown, HTML, CSV, JSON, XML, YAML (no dependency)
+ *   - PDF      — `pdfjs-dist/legacy` with geometry-based row reconstruction (extract/pdf.ts)
+ *   - DOCX     — `mammoth`, HTML output flattened structure-preservingly (extract/docx.ts)
+ *   - XLSX     — SheetJS with cell number formats applied (extract/xlsx.ts)
+ *   - PPTX     — `fflate` + direct `<a:t>` reading (extract/pptx.ts)
+ *
+ * NOT IMPLEMENTED — refused with a typed `unsupported_format` and alternatives:
+ *   legacy binary Office formats (.doc/.xls/.ppt), .rtf, .odt — see PENDING_FORMATS.
+ *
+ * History: this module used to read a PDF and a DOCX by `readFileSync(path, 'utf-8')`
+ * and stripping non-printable bytes, then report `success: true`. A PDF stores its
+ * text inside compressed content streams and a DOCX is a ZIP of XML parts, so that
+ * path could only ever return the container. On 2026-09-27 exactly that reached the
+ * model as a health report it then could not assess, with no signal that extraction
+ * had failed. Every extractor below either does the real work or refuses.
+ *
+ * The container readers are imported dynamically: pdf.js and SheetJS are megabytes
+ * that the CLI, the dashboard server and the tool registry should not pay for at
+ * startup, and a failure to load one is reported as `not_configured` rather than
+ * silently degrading.
+ *
+ * See TOOL_TRUTHFULNESS_TRACKER.md (P0.1, P0.2, P1.2–P1.5).
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { refusalFields } from './tool-refusal.js';
+import { htmlToText } from './extract/html-text.js';
+// ─── Budgets ────────────────────────────────────────────────────────────────
+/**
+ * Character budget for one extraction. Documents are unbounded input flowing into
+ * a bounded context window, so the output is capped and `metadata.truncated` says
+ * whether it was hit — a partial document is never presented as the whole one.
+ */
+const MAX_EXTRACT_CHARS = 40_000;
+// ─── Format model ───────────────────────────────────────────────────────────
+/** Formats with a working extractor. */
+const IMPLEMENTED_FORMATS = new Set([
+    '.txt', '.md', '.markdown', '.text', '.log',
+    '.html', '.htm', '.csv', '.tsv', '.json', '.xml', '.yaml', '.yml',
+    '.pdf', '.docx', '.xlsx', '.pptx',
+]);
+/**
+ * Formats the tool does not read, with the reason surfaced to the model. Kept as a
+ * map so the gap is explicit and greppable rather than implied by a missing `case`.
+ */
+const PENDING_FORMATS = new Map([
+    ['.doc', 'Legacy binary Word (.doc) is not supported — only the OOXML .docx container.'],
+    ['.xls', 'Legacy binary Excel (.xls) is not supported — only the OOXML .xlsx container.'],
+    ['.ppt', 'Legacy binary PowerPoint (.ppt) is not supported — only the OOXML .pptx container.'],
+    ['.rtf', 'RTF is not supported.'],
+    ['.odt', 'ODF (.odt) is not supported — only OOXML .docx.'],
+    ['.ods', 'ODF (.ods) is not supported — only OOXML .xlsx.'],
+]);
+/** What to do instead, per unsupported format. */
+const PENDING_ALTERNATIVES = {
+    '.doc': ['Save as .docx and read that', 'Convert with LibreOffice (`soffice --convert-to docx`)'],
+    '.xls': ['Save as .xlsx or CSV and read that'],
+    '.ppt': ['Save as .pptx and read that'],
+    '.rtf': ['Save as .docx or plain text and read that'],
+    '.odt': ['Save as .docx and read that'],
+    '.ods': ['Save as .xlsx or CSV and read that'],
+};
+/** Container formats whose reader is loaded on demand. */
+const CONTAINER_FORMATS = new Set(['.pdf', '.docx', '.xlsx', '.pptx']);
 // ─── Read Extract Manager ───────────────────────────────────────────────────
 class ReadExtractManager {
-    supportedFormats = new Set([
-        '.txt', '.md', '.markdown', '.html', '.htm', '.csv', '.json', '.xml', '.yaml', '.yml',
-        '.pdf', '.docx', '.xlsx', '.pptx',
-    ]);
     /**
-     * Extract text from a file.
+     * Extract text from a file. Never throws: an unreadable, unsupported or
+     * package-less format comes back as `success: false` with a typed `code`.
      */
-    async extract(filePath) {
+    async extract(filePath, opts = {}) {
         const ext = path.extname(filePath).toLowerCase();
-        if (!this.supportedFormats.has(ext)) {
+        if (PENDING_FORMATS.has(ext)) {
+            return this.refused(ext, PENDING_FORMATS.get(ext), PENDING_ALTERNATIVES[ext] ?? []);
+        }
+        if (!IMPLEMENTED_FORMATS.has(ext)) {
+            // An image is a common arrival here (usually from a chat attachment). The reader
+            // cannot transcribe it, but a vision backend can — so say that plainly rather
+            // than only listing the formats this module knows.
+            const isImage = /^\.(png|jpe?g|gif|webp|bmp|tiff?)$/i.test(ext);
+            return this.refused(ext || '(no extension)', `Unsupported format: ${ext || '(no extension)'}.`, isImage
+                ? [
+                    'Use describe_image — a vision backend can read this image directly',
+                    `Readable text formats: ${this.getSupportedFormats().join(', ')}`,
+                ]
+                : [`Readable formats: ${this.getSupportedFormats().join(', ')}`]);
+        }
+        if (!fs.existsSync(filePath)) {
             return {
                 text: '',
                 format: ext,
                 success: false,
-                error: `Unsupported format: ${ext}. Supported: ${Array.from(this.supportedFormats).join(', ')}`,
+                code: 'no_data',
+                error: `No such file: ${filePath}`,
+                alternatives: ['Check the path (it is resolved relative to the workspace)'],
             };
         }
         try {
@@ -36,12 +104,15 @@ class ReadExtractManager {
                 case '.txt':
                 case '.md':
                 case '.markdown':
+                case '.text':
+                case '.log':
                     return this.extractPlainText(filePath);
                 case '.html':
                 case '.htm':
                     return this.extractHTML(filePath);
                 case '.csv':
-                    return this.extractCSV(filePath);
+                case '.tsv':
+                    return this.extractDelimited(filePath, ext === '.tsv' ? '\t' : ',');
                 case '.json':
                     return this.extractJSON(filePath);
                 case '.xml':
@@ -50,15 +121,15 @@ class ReadExtractManager {
                 case '.yml':
                     return this.extractYAML(filePath);
                 case '.pdf':
-                    return this.extractPDF(filePath);
+                    return await this.extractPdf(filePath, opts);
                 case '.docx':
-                    return this.extractDOCX(filePath);
+                    return await this.extractDocx(filePath);
                 case '.xlsx':
-                    return this.extractXLSX(filePath);
+                    return await this.extractXlsx(filePath);
                 case '.pptx':
-                    return this.extractPPTX(filePath);
+                    return await this.extractPptx(filePath);
                 default:
-                    return { text: '', format: ext, success: false, error: 'Unknown format' };
+                    return this.refused(ext, `Unsupported format: ${ext}`, []);
             }
         }
         catch (err) {
@@ -66,200 +137,465 @@ class ReadExtractManager {
                 text: '',
                 format: ext,
                 success: false,
-                error: err.message,
+                code: 'unavailable',
+                error: err?.message ? String(err.message) : String(err),
             };
         }
     }
-    /**
-     * Extract plain text.
-     */
-    extractPlainText(filePath) {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        return {
-            text: content,
-            format: 'text',
-            success: true,
-            metadata: {
-                words: content.split(/\s+/).length,
-            },
-        };
-    }
-    /**
-     * Extract HTML to text.
-     */
-    extractHTML(filePath) {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        // Simple HTML to text conversion
-        const text = content
-            .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
-            .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
-            .replace(/<[^>]+>/g, ' ')
-            .replace(/\s+/g, ' ')
-            .trim();
-        return {
-            text,
-            format: 'html',
-            success: true,
-            metadata: {
-                words: text.split(/\s+/).length,
-            },
-        };
-    }
-    /**
-     * Extract CSV to text.
-     */
-    extractCSV(filePath) {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const lines = content.split('\n').filter((l) => l.trim());
-        // Simple CSV to text
-        const text = lines.map((line) => {
-            const cells = line.split(',').map((c) => c.trim());
-            return cells.join(' | ');
-        }).join('\n');
+    // ─── Container extractors ─────────────────────────────────────────────────
+    async extractPdf(filePath, opts = {}) {
+        let mod;
+        try {
+            mod = await import('./extract/pdf.js');
+        }
+        catch (err) {
+            return this.notConfigured('.pdf', 'the PDF reader (pdfjs-dist)', err);
+        }
+        let result;
+        try {
+            result = await mod.extractPdfText(new Uint8Array(fs.readFileSync(filePath)), {
+                maxChars: MAX_EXTRACT_CHARS,
+            });
+        }
+        catch (err) {
+            const encrypted = err instanceof mod.PdfExtractError && err.encrypted;
+            return {
+                text: '',
+                format: 'pdf',
+                success: false,
+                code: 'unavailable',
+                error: err instanceof Error ? err.message : String(err),
+                alternatives: encrypted
+                    ? ['Remove the password (print/export to a new PDF) and read that']
+                    : ['Re-export the PDF', 'Send the pages as screenshots so describe_image can read them'],
+            };
+        }
+        // No page yielded text: a scanned document, not an empty one. Reported as a
+        // typed refusal because "success with empty text" is the defect this workstream
+        // removed — a caller cannot act on it.
+        if (result.pagesWithText === 0) {
+            return this.scannedPdfResult(filePath, result, opts);
+        }
         return {
-            text,
-            format: 'csv',
+            text: result.text,
+            format: 'pdf',
             success: true,
             metadata: {
-                words: text.split(/\s+/).length,
+                pages: result.pages,
+                pagesWithText: result.pagesWithText,
+                words: countWords(result.text),
+                truncated: result.truncated,
+                ...(result.pagesWithoutText.length > 0
+                    ? { warnings: [`Page(s) ${result.pagesWithoutText.join(', ')} have no text layer (scanned images).`] }
+                    : {}),
             },
         };
     }
-    /**
-     * Extract JSON to text.
-     */
-    extractJSON(filePath) {
-        const content = fs.readFileSync(filePath, 'utf-8');
+    async extractDocx(filePath) {
+        let mod;
         try {
-            const data = JSON.parse(content);
-            const text = JSON.stringify(data, null, 2);
+            mod = await import('./extract/docx.js');
+        }
+        catch (err) {
+            return this.notConfigured('.docx', 'the DOCX reader (mammoth)', err);
+        }
+        try {
+            const result = await mod.extractDocxText(fs.readFileSync(filePath), { maxChars: MAX_EXTRACT_CHARS });
             return {
-                text,
-                format: 'json',
+                text: result.text,
+                format: 'docx',
                 success: true,
+                metadata: {
+                    words: countWords(result.text),
+                    truncated: result.truncated,
+                    ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+                },
             };
         }
-        catch {
+        catch (err) {
             return {
-                text: content,
-                format: 'json',
-                success: true,
+                text: '',
+                format: 'docx',
+                success: false,
+                code: 'unavailable',
+                error: err instanceof Error ? err.message : String(err),
+                alternatives: ['Re-export the document', 'Save it as .txt or .md and read that'],
             };
         }
     }
-    /**
-     * Extract XML to text.
-     */
-    extractXML(filePath) {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        // Simple XML to text
-        const text = content
-            .replace(/<[^>]+>/g, ' ')
-            .replace(/\s+/g, ' ')
-            .trim();
-        return {
-            text,
-            format: 'xml',
-            success: true,
-        };
-    }
-    /**
-     * Extract YAML to text.
-     */
-    extractYAML(filePath) {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        return {
-            text: content,
-            format: 'yaml',
-            success: true,
-        };
+    async extractXlsx(filePath) {
+        let mod;
+        try {
+            mod = await import('./extract/xlsx.js');
+        }
+        catch (err) {
+            return this.notConfigured('.xlsx', 'the spreadsheet reader (SheetJS)', err);
+        }
+        try {
+            const result = await mod.extractXlsxText(fs.readFileSync(filePath), { maxChars: MAX_EXTRACT_CHARS });
+            if (result.text.trim().length === 0) {
+                return {
+                    text: '',
+                    format: 'xlsx',
+                    success: false,
+                    code: 'no_data',
+                    error: `The workbook has ${result.sheets.length} sheet(s) but no non-empty cells.`,
+                    alternatives: ['Check the sheet is not empty, or export it as CSV'],
+                    metadata: { sheets: result.sheets },
+                };
+            }
+            return {
+                text: result.text,
+                format: 'xlsx',
+                success: true,
+                metadata: {
+                    sheets: result.sheets,
+                    rows: result.rows,
+                    words: countWords(result.text),
+                    truncated: result.truncated,
+                    ...(result.skippedSheets.length > 0
+                        ? { warnings: [`Sheet(s) not read (character budget): ${result.skippedSheets.join(', ')}`] }
+                        : {}),
+                },
+            };
+        }
+        catch (err) {
+            return {
+                text: '',
+                format: 'xlsx',
+                success: false,
+                code: 'unavailable',
+                error: err instanceof Error ? err.message : String(err),
+                alternatives: ['Re-export the workbook', 'Export the sheet as CSV and read that'],
+            };
+        }
     }
-    /**
-     * Extract PDF (simplified - actual PDF extraction requires pdf-parse library).
-     */
-    extractPDF(filePath) {
-        // Simplified PDF extraction
-        // In production, use pdf-parse library
+    async extractPptx(filePath) {
+        let mod;
         try {
-            const content = fs.readFileSync(filePath, 'utf-8');
-            // Attempt to extract readable text
-            const text = content
-                .replace(/[^\x20-\x7E\n]/g, ' ')
-                .replace(/\s+/g, ' ')
-                .trim();
+            mod = await import('./extract/pptx.js');
+        }
+        catch (err) {
+            return this.notConfigured('.pptx', 'the ZIP reader (fflate)', err);
+        }
+        try {
+            const result = await mod.extractPptxText(fs.readFileSync(filePath), { maxChars: MAX_EXTRACT_CHARS });
+            if (result.text.trim().length === 0) {
+                return {
+                    text: '',
+                    format: 'pptx',
+                    success: false,
+                    code: 'no_data',
+                    error: `All ${result.slides} slide(s) are text-free (images only).`,
+                    alternatives: ['Send the slides as screenshots so the vision model can read them'],
+                    metadata: { slides: result.slides },
+                };
+            }
             return {
-                text: text.slice(0, 10000), // Limit to 10K chars
-                format: 'pdf',
+                text: result.text,
+                format: 'pptx',
                 success: true,
                 metadata: {
-                    words: text.split(/\s+/).length,
+                    slides: result.slides,
+                    words: countWords(result.text),
+                    truncated: result.truncated,
+                    ...(result.emptySlides.length > 0
+                        ? { warnings: [`Slide(s) with no text: ${result.emptySlides.join(', ')}`] }
+                        : {}),
                 },
             };
         }
-        catch {
+        catch (err) {
             return {
                 text: '',
-                format: 'pdf',
+                format: 'pptx',
                 success: false,
-                error: 'PDF extraction requires pdf-parse library',
+                code: 'unavailable',
+                error: err instanceof Error ? err.message : String(err),
+                alternatives: ['Re-export the presentation', 'Export the slides as images'],
             };
         }
     }
     /**
-     * Extract DOCX (simplified - actual DOCX extraction requires docx library).
+     * A PDF with no text layer: either transcribe it (when the caller asked for OCR and
+     * the route is available) or refuse with the way to ask. Both outcomes are explicit.
      */
-    extractDOCX(filePath) {
-        // Simplified DOCX extraction
-        // In production, use docx or mammoth library
+    async scannedPdfResult(filePath, result, opts) {
+        const base = {
+            pages: result.pages,
+            pagesWithText: 0,
+            truncated: result.truncated,
+        };
+        const alternatives = [
+            opts.ocr
+                ? 'Install a PDF rasteriser (Poppler: pdftoppm/pdftocairo) and configure a vision backend'
+                : 'Call read_extract again with ocr:true to transcribe the pages with the vision model',
+            'Send the page as a screenshot so the vision model can read it (describe_image)',
+            'Paste the report text',
+        ];
+        if (!opts.ocr) {
+            return {
+                text: '',
+                format: 'pdf',
+                success: false,
+                code: 'no_data',
+                error: `The PDF has ${result.pages} page(s) but no text layer — it is a scan/image, so there is no text to extract.`,
+                alternatives,
+                metadata: base,
+            };
+        }
+        // OCR was requested — attempt it, and if a prerequisite is missing say WHICH.
         try {
-            const content = fs.readFileSync(filePath, 'utf-8');
-            const text = content
-                .replace(/<[^>]+>/g, ' ')
-                .replace(/\s+/g, ' ')
-                .trim();
+            const ocr = await import('./extract/pdf-ocr.js');
+            const transcribed = await ocr.ocrScannedPdf(filePath, result.pages, opts.ocrOptions ?? {});
             return {
-                text: text.slice(0, 10000),
-                format: 'docx',
+                text: transcribed.text,
+                format: 'pdf',
                 success: true,
+                metadata: {
+                    ...base,
+                    ocr: true,
+                    ocrRenderer: transcribed.renderer,
+                    words: countWords(transcribed.text),
+                    truncated: transcribed.truncated,
+                    warnings: [
+                        'Text recovered by OCR from rendered page images — a transcription, not a parsed '
+                            + 'text layer. Verify digits (lab values, dates, doses) against the original.',
+                    ],
+                },
             };
         }
-        catch {
+        catch (err) {
+            const ocr = await import('./extract/pdf-ocr.js');
+            const code = err instanceof ocr.PdfOcrError ? err.code : 'unavailable';
             return {
                 text: '',
-                format: 'docx',
+                format: 'pdf',
                 success: false,
-                error: 'DOCX extraction requires mammoth library',
+                code,
+                error: err instanceof Error ? err.message : String(err),
+                alternatives,
+                metadata: base,
             };
         }
     }
-    /**
-     * Extract XLSX (simplified).
-     */
-    extractXLSX(filePath) {
+    /** An optional reader that failed to load is a typed refusal, never a silent gap. */
+    notConfigured(format, what, err) {
         return {
             text: '',
-            format: 'xlsx',
+            format,
             success: false,
-            error: 'XLSX extraction requires xlsx library',
+            error: `${what} is not available in this install, so ${format} could not be read (${err instanceof Error ? err.message : String(err)}).`,
+            ...refusalFields('not_configured', [`Reinstall dependencies (npm install) to restore ${what}`]),
         };
     }
-    /**
-     * Extract PPTX (simplified).
-     */
-    extractPPTX(filePath) {
+    /** A refusal in the module's result shape (empty text, no fabricated metadata). */
+    refused(format, reason, alternatives) {
         return {
             text: '',
-            format: 'pptx',
+            format,
             success: false,
-            error: 'PPTX extraction requires pptx library',
+            error: reason,
+            ...refusalFields('unsupported_format', alternatives),
+        };
+    }
+    // ─── Text extractors ──────────────────────────────────────────────────────
+    /**
+     * A NUL byte in the first 8 KB means the file is not text, whatever extension it
+     * carries — the same probe `read_file` uses (`coding-tools.ts:looksBinary`). Without
+     * it a mislabelled binary reaches the model as mojibake, which is the very class
+     * of defect this module now refuses.
+     */
+    looksBinary(filePath) {
+        const fd = fs.openSync(filePath, 'r');
+        try {
+            const probe = Buffer.alloc(8192);
+            const read = fs.readSync(fd, probe, 0, probe.length, 0);
+            return probe.subarray(0, read).includes(0);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    extractPlainText(filePath) {
+        if (this.looksBinary(filePath)) {
+            return this.refused('text', `'${path.basename(filePath)}' looks binary (a text/Markdown file with NUL bytes) — its bytes are not text.`, ['Check the real file type and use the matching reader']);
+        }
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const truncated = content.length > MAX_EXTRACT_CHARS;
+        return {
+            text: truncated ? `${content.slice(0, MAX_EXTRACT_CHARS)}\n…[truncated]` : content,
+            format: 'text',
+            success: true,
+            metadata: {
+                words: countWords(content),
+                truncated,
+            },
+        };
+    }
+    /**
+     * HTML → text. Structure-preserving (`htmlToText`): cells stay on one line so a
+     * table's value/column pairing survives. Layout (CSS) is not reconstructed and is
+     * not claimed to be.
+     */
+    extractHTML(filePath) {
+        const text = htmlToText(fs.readFileSync(filePath, 'utf-8'));
+        const truncated = text.length > MAX_EXTRACT_CHARS;
+        return {
+            text: truncated ? `${text.slice(0, MAX_EXTRACT_CHARS)}\n…[truncated]` : text,
+            format: 'html',
+            success: true,
+            metadata: {
+                words: countWords(text),
+                truncated,
+            },
         };
     }
     /**
-     * Get supported formats.
+     * CSV/TSV → text, with RFC 4180 quoting rules rather than `split(',')`. The naive
+     * split silently corrupted any row containing a quoted separator — a lab row like
+     * `Glucose,112,"HIGH, range 70-99"` became four fields with the reference range torn
+     * apart, while the result still reported success.
      */
+    extractDelimited(filePath, delimiter) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split(/\r?\n/).filter((l) => l.trim());
+        const rows = lines.map((line) => parseDelimitedRow(line, delimiter));
+        // Rows stay themselves — separated by newlines, cells by ` | ` — so the table
+        // shape the file encoded is the shape the model reads.
+        const text = rows.map((cells) => cells.join(' | ')).join('\n');
+        const truncated = text.length > MAX_EXTRACT_CHARS;
+        return {
+            text: truncated ? `${text.slice(0, MAX_EXTRACT_CHARS)}\n…[truncated]` : text,
+            format: delimiter === '\t' ? 'tsv' : 'csv',
+            success: true,
+            metadata: {
+                words: countWords(text),
+                rows: rows.length,
+                truncated,
+            },
+        };
+    }
+    extractJSON(filePath) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        let text;
+        let valid = true;
+        try {
+            text = JSON.stringify(JSON.parse(content), null, 2);
+        }
+        catch {
+            // Not valid JSON — return the raw text, and say so rather than implying a parse.
+            text = content;
+            valid = false;
+        }
+        const truncated = text.length > MAX_EXTRACT_CHARS;
+        return {
+            text: truncated ? `${text.slice(0, MAX_EXTRACT_CHARS)}\n…[truncated]` : text,
+            format: 'json',
+            success: true,
+            metadata: {
+                truncated,
+                // A success result never carries an `error` string: the two together are
+                // exactly the ambiguity ("did it work?") this module removes.
+                ...(valid ? {} : { warnings: ['File is not valid JSON — raw text returned'] }),
+            },
+        };
+    }
+    extractXML(filePath) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const text = htmlToText(content);
+        const truncated = text.length > MAX_EXTRACT_CHARS;
+        return {
+            text: truncated ? `${text.slice(0, MAX_EXTRACT_CHARS)}\n…[truncated]` : text,
+            format: 'xml',
+            success: true,
+            metadata: { words: countWords(text), truncated },
+        };
+    }
+    extractYAML(filePath) {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const truncated = content.length > MAX_EXTRACT_CHARS;
+        return {
+            text: truncated ? `${content.slice(0, MAX_EXTRACT_CHARS)}\n…[truncated]` : content,
+            format: 'yaml',
+            success: true,
+            metadata: { words: countWords(content), truncated },
+        };
+    }
+    // ─── Capability surface ───────────────────────────────────────────────────
+    /** Formats with a working extractor. Feeds the tool description. */
     getSupportedFormats() {
-        return Array.from(this.supportedFormats);
+        return Array.from(IMPLEMENTED_FORMATS);
+    }
+    /** Formats the description does not advertise because nothing reads them. */
+    getPendingFormats() {
+        return Array.from(PENDING_FORMATS, ([format, reason]) => ({ format, reason }));
+    }
+    /** Whether a specific path's extension has a working extractor. */
+    isFormatAvailable(filePath) {
+        return IMPLEMENTED_FORMATS.has(path.extname(filePath).toLowerCase());
+    }
+    /** Whether a path's format needs a heavy on-demand reader. */
+    isContainerFormat(filePath) {
+        return CONTAINER_FORMATS.has(path.extname(filePath).toLowerCase());
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function countWords(text) {
+    return text.split(/\s+/).filter(Boolean).length;
+}
+/**
+ * Split one delimited line into fields, honouring `"…"` quoting and escaped `""`.
+ * Exported for tests. `parseCsvRow` is kept as the comma-specific alias.
+ */
+export function parseDelimitedRow(line, delimiter = ',') {
+    const cells = [];
+    let field = '';
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (line[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else
+                    inQuotes = false;
+            }
+            else {
+                field += ch;
+            }
+        }
+        else if (ch === '"') {
+            inQuotes = true;
+        }
+        else if (ch === delimiter) {
+            cells.push(field.trim());
+            field = '';
+        }
+        else {
+            field += ch;
+        }
     }
+    cells.push(field.trim());
+    return cells;
+}
+/** CSV-specific alias (kept for callers/tests that name the comma case). */
+export function parseCsvRow(line) {
+    return parseDelimitedRow(line, ',');
+}
+/**
+ * Probe mirrored into the `read_extract` tool description: true when the path's
+ * format can actually be extracted. Callers use it to choose a tool *before*
+ * spending a step on a refusal.
+ */
+export function isReadExtractAvailable(filePath) {
+    return getReadExtractManager().isFormatAvailable(filePath);
+}
+/** Formats with a working extractor (module-level convenience). */
+export function getReadExtractFormats() {
+    return getReadExtractManager().getSupportedFormats();
 }
 // ─── Singleton ──────────────────────────────────────────────────────────────
 let _instance = null;
@@ -268,5 +604,5 @@ export function getReadExtractManager() {
         _instance = new ReadExtractManager();
     return _instance;
 }
-export { ReadExtractManager };
+export { ReadExtractManager, MAX_EXTRACT_CHARS };
 //# sourceMappingURL=read-extract.js.map