browser-use 0.2.0 → 0.3.0

package/dist/filesystem/file-system.js

@@ -1,11 +1,12 @@
 import fsSync from 'node:fs';
 import { promises as fsp } from 'node:fs';
 import path from 'node:path';
+import AdmZip from 'adm-zip';
 import PDFDocument from 'pdfkit';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 const require = createRequire(import.meta.url);
-async function extractPdfText(buffer) {
+export async function extractPdfText(buffer) {
     const pdfParseModule = (await import('pdf-parse'));
     if (typeof pdfParseModule.default === 'function') {
         const legacyParser = pdfParseModule.default;
@@ -33,10 +34,200 @@ async function extractPdfText(buffer) {
     }
     throw new FileSystemError("Error: Could not parse PDF file due to unsupported 'pdf-parse' module format.");
 }
+export async function extractPdfTextByPage(buffer) {
+    const pdfParseModule = (await import('pdf-parse'));
+    if (typeof pdfParseModule.PDFParse === 'function') {
+        const Parser = pdfParseModule.PDFParse;
+        const parser = new Parser({ data: buffer });
+        try {
+            let numPages = 0;
+            try {
+                const info = await parser.getInfo?.({ parsePageInfo: false });
+                numPages = Number(info?.total ?? 0);
+            }
+            catch {
+                numPages = 0;
+            }
+            if (!Number.isFinite(numPages) || numPages <= 0) {
+                const full = await parser.getText();
+                const text = typeof full?.text === 'string' ? full.text : '';
+                return {
+                    numPages: 1,
+                    pageTexts: [text],
+                    totalChars: text.length,
+                };
+            }
+            const pageTexts = [];
+            let totalChars = 0;
+            for (let pageNumber = 1; pageNumber <= numPages; pageNumber += 1) {
+                const pageResult = await parser.getText({ partial: [pageNumber] });
+                const text = typeof pageResult?.text === 'string' ? pageResult.text : '';
+                pageTexts.push(text);
+                totalChars += text.length;
+            }
+            return {
+                numPages,
+                pageTexts,
+                totalChars,
+            };
+        }
+        finally {
+            if (typeof parser.destroy === 'function') {
+                await parser.destroy();
+            }
+        }
+    }
+    const parsed = await extractPdfText(buffer);
+    const text = parsed.text ?? '';
+    return {
+        numPages: Math.max(parsed.totalPages, 1),
+        pageTexts: [text],
+        totalChars: text.length,
+    };
+}
 export const INVALID_FILENAME_ERROR_MESSAGE = 'Error: Invalid filename format. Must be alphanumeric with supported extension.';
 export const DEFAULT_FILE_SYSTEM_PATH = 'browseruse_agent_data';
-const DEFAULT_EXTENSIONS = ['md', 'txt', 'json', 'csv', 'pdf'];
-const filenameRegex = new RegExp(`^[a-zA-Z0-9_\\-]+\\.(${DEFAULT_EXTENSIONS.join('|')})$`);
+const UNSUPPORTED_BINARY_EXTENSIONS = new Set([
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'bmp',
+    'svg',
+    'webp',
+    'ico',
+    'mp3',
+    'mp4',
+    'wav',
+    'avi',
+    'mov',
+    'zip',
+    'tar',
+    'gz',
+    'rar',
+    'exe',
+    'bin',
+    'dll',
+    'so',
+]);
+const DEFAULT_EXTENSIONS = [
+    'md',
+    'txt',
+    'json',
+    'jsonl',
+    'csv',
+    'pdf',
+    'docx',
+    'html',
+    'xml',
+];
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const buildFilenameRegex = (extensions) => new RegExp(`^[a-zA-Z0-9_\\-.() \\u4e00-\\u9fff]+\\.(${extensions.map(escapeRegex).join('|')})$`);
+const buildFilenameErrorMessage = (fileName, supportedExtensions) => {
+    const base = path.basename(fileName);
+    const supported = supportedExtensions.map((ext) => `.${ext}`).join(', ');
+    if (base.includes('.')) {
+        const ext = base.slice(base.lastIndexOf('.') + 1).toLowerCase();
+        if (UNSUPPORTED_BINARY_EXTENSIONS.has(ext)) {
+            return (`Error: Cannot write binary/image file '${base}'. ` +
+                'The write_file tool only supports text-based files. ' +
+                `Supported extensions: ${supported}. ` +
+                'For screenshots, the browser automatically captures them - do not try to save screenshots as files.');
+        }
+        if (!supportedExtensions.includes(ext)) {
+            return (`Error: Unsupported file extension '.${ext}' in '${base}'. ` +
+                `Supported extensions: ${supported}. ` +
+                'Please rename the file to use a supported extension.');
+        }
+    }
+    else {
+        return (`Error: Filename '${base}' has no extension. ` +
+            `Please add a supported extension: ${supported}.`);
+    }
+    return (`Error: Invalid filename '${base}'. ` +
+        'Filenames must contain only letters, numbers, underscores, hyphens, dots, parentheses, and spaces. ' +
+        `Supported extensions: ${supported}.`);
+};
+const escapeXmlText = (value) => value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+const decodeXmlText = (value) => value
+    .replace(/&apos;/g, "'")
+    .replace(/&quot;/g, '"')
+    .replace(/&gt;/g, '>')
+    .replace(/&lt;/g, '<')
+    .replace(/&amp;/g, '&');
+const DOCX_CONTENT_TYPES_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+</Types>`;
+const DOCX_ROOT_RELS_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+</Relationships>`;
+const DOCX_DOCUMENT_RELS_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"></Relationships>`;
+const buildDocxDocumentXml = (content) => {
+    const lines = content.split(/\r?\n/);
+    const paragraphs = lines
+        .map((line) => {
+        if (!line) {
+            return '<w:p/>';
+        }
+        return `<w:p><w:r><w:t xml:space="preserve">${escapeXmlText(line)}</w:t></w:r></w:p>`;
+    })
+        .join('');
+    return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:document xmlns:wpc="http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas"
+  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+  xmlns:o="urn:schemas-microsoft-com:office:office"
+  xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+  xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"
+  xmlns:v="urn:schemas-microsoft-com:vml"
+  xmlns:wp14="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing"
+  xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
+  xmlns:w10="urn:schemas-microsoft-com:office:word"
+  xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+  xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"
+  xmlns:wpg="http://schemas.microsoft.com/office/word/2010/wordprocessingGroup"
+  xmlns:wpi="http://schemas.microsoft.com/office/word/2010/wordprocessingInk"
+  xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml"
+  xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape"
+  mc:Ignorable="w14 wp14">
+  <w:body>${paragraphs}<w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="708" w:footer="708" w:gutter="0"/></w:sectPr></w:body>
+</w:document>`;
+};
+const buildDocxBuffer = (content) => {
+    const zip = new AdmZip();
+    zip.addFile('[Content_Types].xml', Buffer.from(DOCX_CONTENT_TYPES_XML, 'utf-8'));
+    zip.addFile('_rels/.rels', Buffer.from(DOCX_ROOT_RELS_XML, 'utf-8'));
+    zip.addFile('word/_rels/document.xml.rels', Buffer.from(DOCX_DOCUMENT_RELS_XML, 'utf-8'));
+    zip.addFile('word/document.xml', Buffer.from(buildDocxDocumentXml(content), 'utf-8'));
+    return zip.toBuffer();
+};
+const readDocxText = (fileBuffer) => {
+    const zip = new AdmZip(fileBuffer);
+    const documentEntry = zip.getEntry('word/document.xml');
+    if (!documentEntry) {
+        throw new FileSystemError('Error: Could not parse DOCX file content.');
+    }
+    const xml = documentEntry.getData().toString('utf-8');
+    const normalizedXml = xml.replace(/<w:p\b([^>]*)\/>/g, '<w:p$1></w:p>');
+    const paragraphMatches = normalizedXml.match(/<w:p[\s\S]*?<\/w:p>/g) ?? [];
+    const lines = paragraphMatches.map((paragraph) => {
+        const textMatches = Array.from(paragraph.matchAll(/<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>/g));
+        if (!textMatches.length) {
+            return '';
+        }
+        return textMatches.map((match) => decodeXmlText(match[1] ?? '')).join('');
+    });
+    return lines.join('\n').trim();
+};
 export class FileSystemError extends Error {
 }
 class BaseFile {
@@ -105,6 +296,11 @@ class JsonFile extends BaseFile {
         return 'json';
     }
 }
+class JsonlFile extends BaseFile {
+    get extension() {
+        return 'jsonl';
+    }
+}
 class CsvFile extends BaseFile {
     get extension() {
         return 'csv';
@@ -154,19 +350,52 @@ stream.on('error', (err) => {
         }
     }
 }
+class DocxFile extends BaseFile {
+    get extension() {
+        return 'docx';
+    }
+    async syncToDisk(dir) {
+        const filePath = path.join(dir, this.fullName);
+        const docxBuffer = buildDocxBuffer(this.content || '');
+        await fsp.writeFile(filePath, docxBuffer);
+    }
+    syncToDiskSync(dir) {
+        const filePath = path.join(dir, this.fullName);
+        const docxBuffer = buildDocxBuffer(this.content || '');
+        fsSync.writeFileSync(filePath, docxBuffer);
+    }
+}
+class HtmlFile extends BaseFile {
+    get extension() {
+        return 'html';
+    }
+}
+class XmlFile extends BaseFile {
+    get extension() {
+        return 'xml';
+    }
+}
 const FILE_TYPES = {
     md: MarkdownFile,
     txt: TxtFile,
     json: JsonFile,
+    jsonl: JsonlFile,
     csv: CsvFile,
     pdf: PdfFile,
+    docx: DocxFile,
+    html: HtmlFile,
+    xml: XmlFile,
 };
 const TYPE_NAME_MAP = {
     MarkdownFile,
     TxtFile,
     JsonFile,
+    JsonlFile,
     CsvFile,
     PdfFile,
+    DocxFile,
+    HtmlFile,
+    XmlFile,
 };
 export class FileSystem {
     files = new Map();
@@ -194,7 +423,45 @@ export class FileSystem {
         }
     }
     isValidFilename(filename) {
-        return filenameRegex.test(filename);
+        const base = path.basename(filename);
+        const regex = buildFilenameRegex(this.get_allowed_extensions());
+        if (!regex.test(base)) {
+            return false;
+        }
+        const idx = base.lastIndexOf('.');
+        if (idx <= 0) {
+            return false;
+        }
+        return base.slice(0, idx).trim().length > 0;
+    }
+    static sanitize_filename(fileName) {
+        const base = path.basename(fileName);
+        const idx = base.lastIndexOf('.');
+        if (idx === -1) {
+            return base;
+        }
+        const ext = base.slice(idx + 1).toLowerCase();
+        let namePart = base.slice(0, idx);
+        namePart = namePart.replace(/ /g, '-');
+        namePart = namePart.replace(/[^a-zA-Z0-9_\-.()\u4e00-\u9fff]/g, '');
+        namePart = namePart.replace(/-{2,}/g, '-');
+        namePart = namePart.replace(/^[-.]+|[-.]+$/g, '');
+        if (!namePart) {
+            namePart = 'file';
+        }
+        return `${namePart}.${ext}`;
+    }
+    resolveFilename(filename) {
+        const base = path.basename(filename);
+        const wasChanged = base !== filename;
+        if (this.isValidFilename(base)) {
+            return [base, wasChanged];
+        }
+        const sanitized = FileSystem.sanitize_filename(base);
+        if (sanitized !== base && this.isValidFilename(sanitized)) {
+            return [sanitized, true];
+        }
+        return [base, wasChanged];
     }
     parseFilename(filename) {
         const idx = filename.lastIndexOf('.');
@@ -223,113 +490,307 @@ export class FileSystem {
         return this.dataDir;
     }
     get_file(filename) {
-        return this.files.get(filename) ?? null;
+        const [resolved] = this.resolveFilename(filename);
+        if (!this.isValidFilename(resolved)) {
+            return null;
+        }
+        return this.files.get(resolved) ?? null;
     }
     list_files() {
         return Array.from(this.files.values()).map((file) => file.fullName);
     }
     display_file(filename) {
-        if (!this.isValidFilename(filename)) {
+        const [resolved] = this.resolveFilename(filename);
+        if (!this.isValidFilename(resolved)) {
             return null;
         }
-        const file = this.get_file(filename);
+        const file = this.files.get(resolved) ?? null;
         return file ? file.read() : null;
     }
-    async read_file(filename, externalFile = false) {
+    async read_file_structured(filename, externalFile = false) {
+        const result = {
+            message: '',
+            images: null,
+        };
         if (externalFile) {
             try {
-                const [, extension] = this.parseFilename(filename);
-                if (['md', 'txt', 'json', 'csv'].includes(extension)) {
+                const base = path.basename(filename);
+                const idx = base.lastIndexOf('.');
+                if (idx === -1) {
+                    result.message =
+                        `Error: Invalid filename format ${filename}. ` +
+                            'Must be alphanumeric with a supported extension.';
+                    return result;
+                }
+                const extension = base.slice(idx + 1).toLowerCase();
+                const specialExtensions = new Set([
+                    'docx',
+                    'pdf',
+                    'jpg',
+                    'jpeg',
+                    'png',
+                ]);
+                const textExtensions = this.get_allowed_extensions().filter((ext) => !specialExtensions.has(ext));
+                if (textExtensions.includes(extension)) {
                     const content = await fsp.readFile(filename, 'utf-8');
-                    return `Read from file ${filename}.\n<content>\n${content}\n</content>`;
+                    result.message = `Read from file ${filename}.\n<content>\n${content}\n</content>`;
+                    return result;
                 }
                 if (extension === 'pdf') {
+                    const MAX_CHARS = 60000;
                     const buffer = await fsp.readFile(filename);
-                    const parsed = await extractPdfText(buffer);
-                    const totalPages = parsed.totalPages;
-                    const extraPages = Math.max(0, totalPages - 10);
-                    const snippet = parsed.text.trim();
-                    const preview = snippet
-                        .split(/\n{2,}/)
-                        .slice(0, 10)
+                    const pdf = await extractPdfTextByPage(buffer);
+                    const numPages = pdf.numPages;
+                    const pageTexts = pdf.pageTexts;
+                    const totalChars = pdf.totalChars;
+                    if (totalChars <= MAX_CHARS) {
+                        const contentParts = [];
+                        for (let pageNumber = 1; pageNumber <= pageTexts.length; pageNumber += 1) {
+                            const text = pageTexts[pageNumber - 1] ?? '';
+                            if (!text.trim()) {
+                                continue;
+                            }
+                            contentParts.push(`--- Page ${pageNumber} ---\n${text}`);
+                        }
+                        result.message =
+                            `Read from file ${filename} (${numPages} pages, ${totalChars.toLocaleString()} chars).\n` +
+                                `<content>\n${contentParts.join('\n\n')}\n</content>`;
+                        return result;
+                    }
+                    const wordToPages = new Map();
+                    const pageWords = new Map();
+                    for (let pageNumber = 1; pageNumber <= pageTexts.length; pageNumber += 1) {
+                        const text = pageTexts[pageNumber - 1] ?? '';
+                        const words = new Set((text.toLowerCase().match(/\b[a-zA-Z]{4,}\b/g) ?? []).map((word) => word));
+                        pageWords.set(pageNumber, words);
+                        for (const word of words) {
+                            if (!wordToPages.has(word)) {
+                                wordToPages.set(word, new Set());
+                            }
+                            wordToPages.get(word).add(pageNumber);
+                        }
+                    }
+                    const pageScores = new Map();
+                    for (const [pageNumber, words] of pageWords.entries()) {
+                        let score = 0;
+                        for (const word of words) {
+                            const pagesWithWord = wordToPages.get(word)?.size ?? 1;
+                            score += Math.log(Math.max(numPages, 1) / pagesWithWord);
+                        }
+                        pageScores.set(pageNumber, score);
+                    }
+                    const priorityPages = [1];
+                    const sortedPages = Array.from(pageScores.entries()).sort((a, b) => b[1] - a[1]);
+                    for (const [pageNumber] of sortedPages) {
+                        if (!priorityPages.includes(pageNumber)) {
+                            priorityPages.push(pageNumber);
+                        }
+                    }
+                    for (let pageNumber = 1; pageNumber <= numPages; pageNumber += 1) {
+                        if (!priorityPages.includes(pageNumber)) {
+                            priorityPages.push(pageNumber);
+                        }
+                    }
+                    const contentParts = [];
+                    let charsUsed = 0;
+                    const pagesIncluded = [];
+                    const pagesIncludedSet = new Set();
+                    for (const pageNumber of priorityPages) {
+                        const text = pageTexts[pageNumber - 1] ?? '';
+                        if (!text.trim()) {
+                            continue;
+                        }
+                        const pageHeader = `--- Page ${pageNumber} ---\n`;
+                        const truncationSuffix = '\n[...truncated]';
+                        const remaining = MAX_CHARS - charsUsed;
+                        const minUseful = pageHeader.length + truncationSuffix.length + 50;
+                        if (remaining < minUseful) {
+                            break;
+                        }
+                        let pageContent = `${pageHeader}${text}`;
+                        if (pageContent.length > remaining) {
+                            pageContent =
+                                pageContent.slice(0, Math.max(0, remaining - truncationSuffix.length)) + truncationSuffix;
+                        }
+                        contentParts.push({ pageNumber, content: pageContent });
+                        charsUsed += pageContent.length;
+                        pagesIncluded.push(pageNumber);
+                        pagesIncludedSet.add(pageNumber);
+                        if (charsUsed >= MAX_CHARS) {
+                            break;
+                        }
+                    }
+                    contentParts.sort((a, b) => a.pageNumber - b.pageNumber);
+                    const extractedText = contentParts
+                        .map((part) => part.content)
                         .join('\n\n');
-                    const suffix = extraPages > 0 ? `\n${extraPages} more pages...` : '';
-                    return `Read from file ${filename}.\n<content>\n${preview}${suffix}\n</content>`;
+                    let truncationNote = '';
+                    const pagesNotShown = numPages - pagesIncluded.length;
+                    if (pagesNotShown > 0) {
+                        const skipped = [];
+                        for (let pageNumber = 1; pageNumber <= numPages; pageNumber += 1) {
+                            if (!pagesIncludedSet.has(pageNumber)) {
+                                skipped.push(pageNumber);
+                            }
+                        }
+                        const skippedPreview = skipped.slice(0, 10).join(', ');
+                        const skippedSuffix = skipped.length > 10 ? ', ...' : '';
+                        truncationNote =
+                            `\n\n[Showing ${pagesIncluded.length} of ${numPages} pages. ` +
+                                `Skipped pages: [${skippedPreview}${skippedSuffix}]. ` +
+                                'Use read_long_content with a specific goal to find relevant sections.]';
+                    }
+                    result.message =
+                        `Read from file ${filename} (${numPages} pages, ${totalChars.toLocaleString()} chars total).\n` +
+                            `<content>\n${extractedText}${truncationNote}\n</content>`;
+                    return result;
+                }
+                if (extension === 'docx') {
+                    const fileBuffer = await fsp.readFile(filename);
+                    const content = readDocxText(fileBuffer);
+                    result.message = `Read from file ${filename}.\n<content>\n${content}\n</content>`;
+                    return result;
                 }
-                return `Error: Cannot read file ${filename} as ${extension} extension is not supported.`;
+                if (extension === 'jpg' ||
+                    extension === 'jpeg' ||
+                    extension === 'png') {
+                    const fileBuffer = await fsp.readFile(filename);
+                    result.message = `Read image file ${filename}.`;
+                    result.images = [
+                        {
+                            name: base,
+                            data: fileBuffer.toString('base64'),
+                        },
+                    ];
+                    return result;
+                }
+                result.message = `Error: Cannot read file ${filename} as ${extension} extension is not supported.`;
+                return result;
             }
             catch (error) {
                 if (error?.code === 'ENOENT') {
-                    return `Error: File '${filename}' not found.`;
+                    result.message = `Error: File '${filename}' not found.`;
+                    return result;
                 }
                 if (error?.code === 'EACCES') {
-                    return `Error: Permission denied to read file '${filename}'.`;
+                    result.message = `Error: Permission denied to read file '${filename}'.`;
+                    return result;
                 }
-                return `Error: Could not read file '${filename}'.`;
+                result.message =
+                    `Error: Could not read file '${filename}'. ${error instanceof Error ? error.message : ''}`.trim();
+                return result;
             }
         }
-        if (!this.isValidFilename(filename)) {
-            return INVALID_FILENAME_ERROR_MESSAGE;
+        const originalFilename = filename;
+        const [resolved, wasSanitized] = this.resolveFilename(filename);
+        if (!this.isValidFilename(resolved)) {
+            result.message = buildFilenameErrorMessage(filename, this.get_allowed_extensions());
+            return result;
         }
-        const file = this.get_file(filename);
+        const file = this.files.get(resolved) ?? null;
         if (!file) {
-            return `File '${filename}' not found.`;
+            if (wasSanitized) {
+                result.message =
+                    `File '${resolved}' not found. ` +
+                        `(Filename was auto-corrected from '${originalFilename}')`;
+            }
+            else {
+                result.message = `File '${originalFilename}' not found.`;
+            }
+            return result;
         }
         try {
             const content = file.read();
-            return `Read from file ${filename}.\n<content>\n${content}\n</content>`;
+            const sanitizeNote = wasSanitized
+                ? `Note: filename was auto-corrected from '${originalFilename}' to '${resolved}'. `
+                : '';
+            result.message = `${sanitizeNote}Read from file ${resolved}.\n<content>\n${content}\n</content>`;
+            return result;
         }
         catch (error) {
-            return error instanceof FileSystemError
-                ? error.message
-                : `Error: Could not read file '${filename}'.`;
+            result.message =
+                error instanceof FileSystemError
+                    ? error.message
+                    : `Error: Could not read file '${originalFilename}'.`;
+            return result;
         }
     }
+    async read_file(filename, externalFile = false) {
+        const result = await this.read_file_structured(filename, externalFile);
+        return result.message;
+    }
     async write_file(filename, content) {
-        if (!this.isValidFilename(filename)) {
-            return INVALID_FILENAME_ERROR_MESSAGE;
+        const originalFilename = filename;
+        const [resolved, wasSanitized] = this.resolveFilename(filename);
+        if (!this.isValidFilename(resolved)) {
+            return buildFilenameErrorMessage(filename, this.get_allowed_extensions());
         }
+        filename = resolved;
         const file = this.files.get(filename) ?? this.instantiateFile(filename);
         this.files.set(filename, file);
         try {
             await file.write(content, this.dataDir);
-            return `Data written to file ${filename} successfully.`;
+            const sanitizeNote = wasSanitized
+                ? ` (auto-corrected from '${originalFilename}')`
+                : '';
+            return `Data written to file ${filename} successfully.${sanitizeNote}`;
         }
         catch (error) {
             return `Error: Could not write to file '${filename}'. ${error.message}`;
         }
     }
     async append_file(filename, content) {
-        if (!this.isValidFilename(filename)) {
-            return INVALID_FILENAME_ERROR_MESSAGE;
+        const originalFilename = filename;
+        const [resolved, wasSanitized] = this.resolveFilename(filename);
+        if (!this.isValidFilename(resolved)) {
+            return buildFilenameErrorMessage(filename, this.get_allowed_extensions());
         }
+        filename = resolved;
         const file = this.get_file(filename);
         if (!file) {
+            if (wasSanitized) {
+                return (`File '${filename}' not found. ` +
+                    `(Filename was auto-corrected from '${originalFilename}')`);
+            }
             return `File '${filename}' not found.`;
         }
         try {
             await file.append(content, this.dataDir);
-            return `Data appended to file ${filename} successfully.`;
+            const sanitizeNote = wasSanitized
+                ? ` (auto-corrected from '${originalFilename}')`
+                : '';
+            return `Data appended to file ${filename} successfully.${sanitizeNote}`;
         }
         catch (error) {
             return `Error: Could not append to file '${filename}'. ${error.message}`;
         }
     }
     async replace_file_str(filename, oldStr, newStr) {
-        if (!this.isValidFilename(filename)) {
-            return INVALID_FILENAME_ERROR_MESSAGE;
+        const originalFilename = filename;
+        const [resolved, wasSanitized] = this.resolveFilename(filename);
+        if (!this.isValidFilename(resolved)) {
+            return buildFilenameErrorMessage(filename, this.get_allowed_extensions());
         }
+        filename = resolved;
         if (!oldStr) {
             return 'Error: Cannot replace empty string. Please provide a non-empty string to replace.';
         }
         const file = this.get_file(filename);
         if (!file) {
+            if (wasSanitized) {
+                return (`File '${filename}' not found. ` +
+                    `(Filename was auto-corrected from '${originalFilename}')`);
+            }
             return `File '${filename}' not found.`;
         }
         try {
             const content = file.read().replaceAll(oldStr, newStr);
             await file.write(content, this.dataDir);
-            return `Successfully replaced all occurrences of "${oldStr}" with "${newStr}" in file ${filename}`;
+            const sanitizeNote = wasSanitized
+                ? ` (auto-corrected from '${originalFilename}')`
+                : '';
+            return (`Successfully replaced all occurrences of "${oldStr}" with "${newStr}" in file ${filename}` +
+                sanitizeNote);
         }
         catch (error) {
             return `Error: Could not replace string in file '${filename}'. ${error.message}`;
@@ -341,7 +802,7 @@ export class FileSystem {
         await file.write(content, this.dataDir);
         this.files.set(filename, file);
         this.extractedContentCount += 1;
-        return `Extracted content saved to file ${filename} successfully.`;
+        return filename;
     }
     describe() {
         const DISPLAY_CHARS = 400;