@sema-agent/core 7.41.1 → 7.42.0

package/dist/tools/fs/fs-read.js

@@ -1,22 +1,408 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } from "./safety.js";
+import { sha256, resolveKey, violationText, violationDetails, binaryMagicFormat, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, } from "./safety.js";
 import { decodeTextBytes } from "./encoding.js";
 import { isNotebookPath, parseNotebookCells, renderNotebookCells, stripNotebookImageData, NOTEBOOK_IMAGE_BASE64_BUDGET } from "./notebook.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE } from "../../core/mcp.js";
 import { PDF_MAX_PAGES_PER_READ, pdfMagicMatches } from "./pdf.js";
-import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, MAX_IMAGE_READ_BYTES, MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES, NO_DOWNSAMPLER_IMAGE_CAP_HINT, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
-import { readPdfFile, pdfResultToToolReturn } from "./fs-pdf.js";
+import { MAX_READ_BYTES, SLICED_READ_MAX_BYTES, NO_DOWNSAMPLER_IMAGE_CAP_HINT, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
+import { readPdfFile } from "./fs-pdf.js";
 import { openSystemReminder } from "../../core/reminder-mint.js";
-import { discloseReminderShaped } from "../../core/reminder-disclosure.js";
+import { planReminderDisclosure, commitReminderDisclosureEffects, renderReminderDisclosureTrailer, } from "../../core/reminder-disclosure.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
+import { admitImageBytes, imageReadCap } from "./image-admission.js";
+export const READ_OUTCOMES = Object.freeze(["attached", "partial", "unchanged", "not_attached"]);
+const NO_EFFECTS = () => ({ disclosure: [] });
+export function createModelFileReader(opts) {
+    const { env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readDeny, readFace, reminderMark } = opts;
+    const windows = opts.disclosureWindows ?? new Map();
+    const refuse = (envelope, kind) => ({
+        outcome: "not_attached",
+        ...(kind !== undefined ? { kind } : {}),
+        data: [],
+        notes: [],
+        refusal: envelope,
+        effects: NO_EFFECTS(),
+    });
+    const disclosureOf = (segments, outlet, key) => {
+        const plan = planReminderDisclosure({ segments, mark: reminderMark, outlet, defuseExactMark: false, throttle: { key, windows } });
+        const verdict = plan.verdict;
+        return { ...(verdict.reminder !== undefined || verdict.envelopeTags !== undefined ? { note: { kind: "disclosure", verdict } } : {}), effects: plan.effects };
+    };
+    const readForModel = async (args, ctx) => {
+        const { offset, limit, pages } = (args ?? {});
+        const path = fileArgPath(args);
+        if (path === undefined)
+            return refuse(errorResult(`Error (Read): file_path is required.`));
+        const unchanged = (note, kind, reason, startLine, endLine, totalLines) => ({
+            outcome: "unchanged",
+            kind,
+            data: [],
+            notes: [note],
+            details: { type: "file_unchanged", reason, file: { filePath: path, startLine, endLine, totalLines } },
+            effects: NO_EFFECTS(),
+        });
+        const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx), readDeny, readFace);
+        if (!r.ok)
+            return refuse(errorResult(violationText("Read", r.violation), violationDetails(r.violation)));
+        const isNb = isNotebookPath(r.key);
+        const imageMime = imageMimeForRead(r.key);
+        if (imageMime !== undefined) {
+            const meta = await env.fileInfo(r.key, ctx.signal);
+            if (!meta.ok) {
+                const ex = await env.exists(r.key, ctx.signal);
+                if (ex.ok && !ex.value)
+                    return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), "image");
+                return refuse(errorResult(`Error (Read): cannot stat image "${path}" to verify its size before reading: ${meta.error.message}`), "image");
+            }
+            if (meta.value.kind === "directory") {
+                return refuse(errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`), "image");
+            }
+            const downsampler = imageDownsampler === false ? undefined : (imageDownsampler ?? (await resolveAutoDownsampler()));
+            const readCap = imageReadCap(downsampler);
+            const tooLargeToRead = (bytes) => `Error (Read): image "${path}" is too large to read (${bytes} bytes > ${readCap}-byte cap).` +
+                (downsampler ? "" : ` ${NO_DOWNSAMPLER_IMAGE_CAP_HINT}`);
+            if (meta.value.size > readCap)
+                return refuse(errorResult(tooLargeToRead(meta.value.size)), "image");
+            const bin = await env.readBinaryFile(r.key, ctx.signal);
+            if (!bin.ok)
+                return refuse(errorResult(`Error (Read): cannot read image "${path}": ${bin.error.message}`), "image");
+            const admitted = await admitImageBytes(bin.value, imageMime, downsampler);
+            if (!admitted.ok) {
+                switch (admitted.reason) {
+                    case "raw_too_large":
+                        return refuse(errorResult(tooLargeToRead(bin.value.byteLength)), "image");
+                    case "magic_mismatch":
+                    case "mime_unsupported":
+                        return refuse(errorResult(`Error (Read): "${path}" has an image extension but its content is not a valid ${imageMime} (empty, truncated, or mis-named).`), "image");
+                    case "base64_too_large":
+                        return refuse(errorResult(`Error (Read): image "${path}" is too large to send (${bin.value.byteLength} bytes; base64 ${admitted.base64.length} chars exceeds the ${MCP_IMAGE_MAX_BASE64}-char / 5MB API image limit` +
+                            (downsampler
+                                ? "; downsampling could not bring it under the limit)."
+                                : `; raw images over ${IMAGE_TARGET_RAW_SIZE} bytes always exceed it — shrink it first, e.g. with an image tool via bash).`)), "image");
+                }
+            }
+            const { block, dimensions, originalSize, resized } = admitted;
+            return {
+                outcome: "attached",
+                kind: "image",
+                data: [block],
+                notes: resized && dimensions !== undefined ? [{ kind: "image_resized", dimensions }] : [],
+                details: {
+                    type: "image",
+                    file: { ...(block.data.length <= 48_000 ? { base64: block.data } : {}), type: block.mimeType, originalSize, ...(dimensions ? { dimensions } : {}) },
+                },
+                effects: NO_EFFECTS(),
+            };
+        }
+        const pdfOf = async (preRead) => {
+            const effects = [];
+            const out = await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, preRead, pdfCapabilities, readDeny, {
+                mark: reminderMark,
+                windows,
+                key: r.key,
+                effects,
+            });
+            if (typeof out === "string")
+                return refuse(errorResult(out), "pdf");
+            const details = out.details;
+            const outcome = details?.fallback?.level === 3 ? "not_attached" : details?.file?.timedOut === true ? "partial" : "attached";
+            return { outcome, kind: "pdf", data: out.content, notes: [], details: out.details, effects: { disclosure: effects } };
+        };
+        if (r.key.toLowerCase().endsWith(".pdf"))
+            return pdfOf(undefined);
+        const binaryExt = hasBinaryExtension(r.key);
+        const binaryExtRefusal = () => refuse(errorResult(`Error (Read): "${path}" appears to be a binary file (by extension); this tool reads UTF-8 text only.`), "text");
+        const info = await env.fileInfo(r.key, ctx.signal);
+        if (info.ok) {
+            if (info.value.kind === "directory") {
+                return refuse(errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`), "text");
+            }
+            if (info.value.size > SLICED_READ_MAX_BYTES) {
+                if (binaryExt)
+                    return binaryExtRefusal();
+                return refuse(errorResult(`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
+                    `(${info.value.size} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
+                    `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`), "text");
+            }
+            if (!isNb && info.value.size > MAX_READ_BYTES && limit === undefined) {
+                if (binaryExt)
+                    return binaryExtRefusal();
+                return refuse(errorResult(`Error (Read): "${path}" is too large to read in full (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`), "text");
+            }
+        }
+        else {
+            const ex = await env.exists(r.key, ctx.signal);
+            if (ex.ok && !ex.value)
+                return refuse(errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`), "text");
+            return refuse(errorResult(`Error (Read): cannot determine the type of "${path.slice(0, 300)}" (stat failed: ${info.error.message.slice(0, 200)}); refusing to open it — if it is a FIFO/socket/device, reading it would hang. Retry if this was transient, or inspect it with Bash (e.g. \`file\`, \`ls -l\`).`), "text");
+        }
+        const readBin = await env.readBinaryFile(r.key, ctx.signal);
+        if (!readBin.ok)
+            return refuse(errorResult(`Error (Read): cannot read "${path}": ${readBin.error.message}`), "text");
+        const readSize = readBin.value.byteLength;
+        if (readSize > SLICED_READ_MAX_BYTES) {
+            if (binaryExt)
+                return binaryExtRefusal();
+            return refuse(errorResult(`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
+                `(${readSize} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
+                `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`), "text");
+        }
+        if (!isNb && readSize > MAX_READ_BYTES && limit === undefined) {
+            if (binaryExt)
+                return binaryExtRefusal();
+            return refuse(errorResult(`Error (Read): "${path}" is too large to read in full (${readSize} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`), "text");
+        }
+        if (pdfMagicMatches(readBin.value))
+            return pdfOf(readBin.value);
+        const magicFormat = binaryMagicFormat(readBin.value);
+        if (magicFormat !== undefined) {
+            return refuse(errorResult(`Error (Read): "${path}" appears to be a binary file (${magicFormat}, identified by its file signature — whatever its extension says); ` +
+                `this tool reads UTF-8 and BOM-marked UTF-16LE text only. Inspect or convert it with bash instead.`), "text");
+        }
+        const decoded = decodeTextBytes(readBin.value);
+        if (decoded.malformed) {
+            return refuse(errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`), "text");
+        }
+        const content = decoded.text;
+        if (isBinaryContent(content.slice(0, 8192))) {
+            return refuse(errorResult(`Error (Read): "${path}" appears to be a binary file (non-text content); this tool reads UTF-8 and BOM-marked UTF-16LE text only. ` +
+                `If it is UTF-16 without a BOM or a legacy encoding, convert it first (e.g. \`iconv -f UTF-16LE -t UTF-8\`) or inspect/transform it with bash.`), "text");
+        }
+        const nbParsed = isNb ? parseNotebookCells(content, path) : undefined;
+        const nbForced = nbParsed !== undefined && nbParsed.ok;
+        const effOffset = nbForced ? undefined : offset;
+        const effLimit = nbForced ? undefined : limit;
+        const lines = content.length === 0 ? [] : content.split("\n");
+        const total = lines.length;
+        const start = Math.max(1, Math.floor(effOffset ?? 1));
+        const max = effLimit !== undefined ? Math.max(1, Math.floor(effLimit)) : Number.MAX_SAFE_INTEGER;
+        if (total > 0 && start > total) {
+            return { outcome: "not_attached", kind: "text", data: [], notes: [{ kind: "past_eof", offset: start, totalLines: total }], effects: NO_EFFECTS() };
+        }
+        let slice = lines.slice(start - 1, start - 1 + max);
+        let end = start - 1 + slice.length;
+        if (end === total - 1 && lines[total - 1] === "") {
+            slice = lines.slice(start - 1, total);
+            end = total;
+        }
+        const hash = sha256(content);
+        const notes = [];
+        if (nbParsed !== undefined) {
+            if (nbParsed.ok) {
+                const parsed = nbParsed;
+                const rendered = renderNotebookCells(parsed.cells, NOTEBOOK_IMAGE_BASE64_BUDGET);
+                if (rendered.textChars > MAX_READ_OUTPUT_CHARS) {
+                    return refuse(errorResult(`Error (Read): notebook "${path}" projects to ~${Math.round(rendered.textChars / 4)} tokens of cell content, over the 25000-token limit ` +
+                        `(offset/limit do not apply to notebooks — the whole notebook is always projected). Inspect portions with Bash + jq instead, e.g.\n` +
+                        `  cat "${path}" | jq '.cells[:20]' # First 20 cells\n` +
+                        `  cat "${path}" | jq '.cells | length' # Count total cells\n` +
+                        `  cat "${path}" | jq '.cells[] | select(.cell_type=="code") | .source' # All code sources`), "notebook");
+                }
+                const prevNb = state.get(r.key);
+                if (prevNb?.seededFromContext && !prevNb.isPartialView && prevNb.hash === hash) {
+                    return unchanged({ kind: "already_in_context", key: r.key }, "notebook", "already-in-context", 1, total, total);
+                }
+                if (prevNb && !prevNb.isPartialView && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
+                    return unchanged({ kind: "unchanged", path, start: 1, end: total, total }, "notebook", "unchanged-since-last-read", 1, total, total);
+                }
+                const observation = { key: r.key, entry: { hash, totalLines: countLines(content), truncated: false, view: { start: 1, end: total } } };
+                if (rendered.blocks.length === 0)
+                    notes.push({ kind: "notebook_no_cells" });
+                const disclosure = disclosureOf(rendered.blocks.filter((b) => b.type === "text").map((b) => b.text), "notebook", r.key);
+                if (disclosure.note !== undefined)
+                    notes.push(disclosure.note);
+                return {
+                    outcome: "attached",
+                    kind: "notebook",
+                    data: rendered.blocks,
+                    notes,
+                    details: { type: "notebook", file: { filePath: path, cells: parsed.cells.map(stripNotebookImageData) } },
+                    observation,
+                    effects: { disclosure: [disclosure.effects] },
+                };
+            }
+            notes.push({ kind: "notebook_fallback" });
+        }
+        const renderBody = (sl) => sl.map((l, i) => `${start + i}\t${l}`).join("\n");
+        let body = renderBody(slice);
+        let partial;
+        if (body.length > MAX_READ_OUTPUT_CHARS) {
+            const defaultFullRead = start <= 1 && effLimit === undefined;
+            if (!defaultFullRead) {
+                return refuse(errorResult(`Error (Read): the requested range of "${path}" is ~${Math.round(body.length / 4)} tokens, over the 25000-token limit. Narrow it with offset/limit, or use grep to search the file.`), "text");
+            }
+            const approxTokens = Math.round(body.length / 4);
+            let n = Math.max(1, Math.min(slice.length, Math.floor(slice.length * (MAX_READ_OUTPUT_CHARS / body.length) * 0.95)));
+            let paged = slice.slice(0, n);
+            let pagedBody = renderBody(paged);
+            for (let attempt = 0; attempt < 8 && pagedBody.length > MAX_READ_OUTPUT_CHARS && n > 1; attempt++) {
+                n = Math.max(1, Math.floor(n * 0.7));
+                paged = slice.slice(0, n);
+                pagedBody = renderBody(paged);
+            }
+            if (pagedBody.length <= MAX_READ_OUTPUT_CHARS) {
+                slice = paged;
+                end = start - 1 + slice.length;
+                body = pagedBody;
+                partial = { kind: "partial_page", end, total, approxTokens };
+            }
+            else {
+                let cut = MAX_READ_OUTPUT_CHARS - 200;
+                const cc = slice[0].charCodeAt(cut - 1);
+                if (cc >= 0xd800 && cc <= 0xdbff)
+                    cut -= 1;
+                slice = [slice[0].slice(0, cut)];
+                end = start;
+                body = renderBody(slice);
+                partial = { kind: "partial_chars", cut, totalChars: content.length, approxTokens };
+            }
+        }
+        const truncated = start > 1 || end < total || partial !== undefined;
+        const prev = state.get(r.key);
+        if (total > 0 && prev?.seededFromContext && !prev.isPartialView && start === 1 && effLimit === undefined && prev.hash === hash) {
+            return unchanged({ kind: "already_in_context", key: r.key }, "text", "already-in-context", 1, total, total);
+        }
+        if (total > 0 && prev && !prev.isPartialView && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
+            return unchanged({ kind: "unchanged", path, start, end, total }, "text", "unchanged-since-last-read", start, end, total);
+        }
+        const observation = {
+            key: r.key,
+            entry: { hash, totalLines: countLines(content), truncated, ...(partial !== undefined ? { isPartialView: true } : {}), view: { start, end } },
+        };
+        if (total === 0)
+            return { outcome: "attached", kind: "text", data: [], notes: [...notes, { kind: "empty_file" }], observation, effects: NO_EFFECTS() };
+        if (partial !== undefined)
+            notes.push(partial);
+        else if (truncated)
+            notes.push({ kind: "range", path, start, end, total });
+        const disclosure = disclosureOf([body], "read", r.key);
+        if (disclosure.note !== undefined)
+            notes.push(disclosure.note);
+        return {
+            outcome: partial !== undefined ? "partial" : "attached",
+            kind: "text",
+            data: [{ type: "text", text: body }],
+            notes,
+            details: {
+                type: "text",
+                file: {
+                    filePath: path,
+                    content: slice.join("\n"),
+                    numLines: slice.length,
+                    startLine: start,
+                    totalLines: total,
+                    ...(partial !== undefined ? { truncatedByTokenCap: true } : {}),
+                },
+            },
+            observation,
+            effects: { disclosure: [disclosure.effects] },
+        };
+    };
+    const committed = new WeakSet();
+    return {
+        readForModel,
+        commit(result, at) {
+            if (committed.has(result))
+                throw new Error("ModelFileReader.commit: this read result was already committed — a delivery commits its read once");
+            committed.add(result);
+            if (result.observation !== undefined) {
+                state.set(result.observation.key, {
+                    ...result.observation.entry,
+                    lastReadAt: at?.now ?? Date.now(),
+                    transmittedByToolCallId: at?.transmittedByToolCallId,
+                });
+            }
+            for (const e of result.effects.disclosure)
+                commitReminderDisclosureEffects(e, { counts: opts.reminderDisclosureCounts, windows });
+        },
+    };
+}
+export function renderReadNoteForTool(note, mark) {
+    switch (note.kind) {
+        case "empty_file":
+            return `${openSystemReminder(mark)}Warning: the file exists but the contents are empty.</system-reminder>`;
+        case "past_eof":
+            return `${openSystemReminder(mark)}Warning: the file exists but is shorter than the provided offset (${note.offset}). The file has ${note.totalLines} lines.</system-reminder>`;
+        case "already_in_context":
+            return seededFileUnchangedReminder(note.key, mark);
+        case "unchanged":
+            return `[${note.path}: unchanged since you last read it (lines ${note.start}-${note.end} of ${note.total}); content omitted to save context]`;
+        case "range":
+            return `[${note.path}: lines ${note.start}-${note.end} of ${note.total}${note.end < note.total ? " — use offset to see more" : ""}]\n`;
+        case "partial_page":
+            return (`[Truncated: PARTIAL view — showing lines 1-${note.end} of ${note.total} total (~${note.approxTokens} tokens, cap 25000). ` +
+                `Call Read with offset=${note.end + 1} limit=${note.end} for the next page, or Grep to find a specific section. ` +
+                `Do NOT answer from this page alone if the answer may be further in the file.]\n`);
+        case "partial_chars":
+            return (`[Truncated: PARTIAL view — showing the first ${note.cut} of ${note.totalChars} characters (~${note.approxTokens} tokens, cap 25000); ` +
+                `this file has very long lines and cannot be paginated by line. Use Grep to find a specific section, or Read with offset/limit to page through it. ` +
+                `Do NOT answer from this excerpt alone if the answer may be elsewhere in the file.]\n`);
+        case "notebook_fallback":
+            return "[not a parseable notebook — showing raw file text]\n";
+        case "notebook_no_cells":
+            return "[notebook has 0 cells]";
+        case "image_resized": {
+            const d = note.dimensions;
+            return `[Image: original ${d.originalWidth}x${d.originalHeight}, displayed at ${d.displayWidth}x${d.displayHeight}. Multiply coordinates by ${(d.originalWidth / d.displayWidth).toFixed(2)} to map to original image.]`;
+        }
+        case "disclosure":
+            return renderReminderDisclosureTrailer(note.verdict, mark) ?? "";
+    }
+}
+export function renderReadToolResult(r, mark) {
+    if (r.refusal !== undefined)
+        return r.refusal;
+    const noteOf = (kind) => r.notes.find((n) => n.kind === kind);
+    const lead = r.notes.find((n) => n.kind === "past_eof" || n.kind === "empty_file");
+    if (lead !== undefined)
+        return renderReadNoteForTool(lead, mark);
+    if (r.outcome === "unchanged")
+        return { content: renderReadNoteForTool(r.notes[0], mark), ...(r.details !== undefined ? { details: r.details } : {}) };
+    const disclosure = noteOf("disclosure");
+    const trailer = disclosure !== undefined ? renderReadNoteForTool(disclosure, mark) : undefined;
+    switch (r.kind) {
+        case "pdf":
+            return { content: r.data, details: r.details };
+        case "image": {
+            const resized = noteOf("image_resized");
+            return { content: [...r.data, ...(resized !== undefined ? [{ type: "text", text: renderReadNoteForTool(resized, mark) }] : [])], details: r.details };
+        }
+        case "notebook": {
+            const noCells = noteOf("notebook_no_cells");
+            return {
+                content: [
+                    ...(noCells !== undefined ? [{ type: "text", text: renderReadNoteForTool(noCells, mark) }] : r.data),
+                    ...(trailer !== undefined ? [{ type: "text", text: trailer }] : []),
+                ],
+                details: r.details,
+            };
+        }
+        default: {
+            const fallback = noteOf("notebook_fallback");
+            const header = noteOf("partial_page") ?? noteOf("partial_chars") ?? noteOf("range");
+            const body = r.data[0]?.text ?? "";
+            return {
+                content: `${fallback !== undefined ? renderReadNoteForTool(fallback, mark) : ""}${header !== undefined ? renderReadNoteForTool(header, mark) : ""}${body}${trailer !== undefined ? `\n${trailer}` : ""}`,
+                details: r.details,
+            };
+        }
+    }
+}
 export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption, readDeny, readFace, reminderMark, reminderDisclosureCounts) {
-    const reminderDisclosureWindows = new Map();
-    const pdfReminderDisclosure = (key) => ({
-        mark: reminderMark,
-        windows: reminderDisclosureWindows,
-        key,
-        counts: reminderDisclosureCounts,
+    const reader = createModelFileReader({
+        env,
+        state,
+        rootCanonical,
+        ...(cwdRef !== undefined ? { cwdRef } : {}),
+        ...(additionalRoots !== undefined ? { additionalRoots } : {}),
+        imageDownsampler,
+        ...(pdfCapabilities !== undefined ? { pdfCapabilities } : {}),
+        ...(bgOutputReadExemption !== undefined ? { bgOutputReadExemption } : {}),
+        ...(readDeny !== undefined ? { readDeny } : {}),
+        ...(readFace !== undefined ? { readFace } : {}),
+        ...(reminderMark !== undefined ? { reminderMark } : {}),
+        ...(reminderDisclosureCounts !== undefined ? { reminderDisclosureCounts } : {}),
     });
     const pathBoundLine = readFace === "open"
         ? "- `file_path` may be relative (resolved against the tracked working directory) or absolute. Reads are not confined to the workspace roots; a small sensitive-path deny list applies.\n"
@@ -56,282 +442,9 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             pages: Type.Optional(Type.String({ description: `Page range for PDF files (e.g., "1-5", "3", "10-20"). Only applicable to PDF files. Maximum ${PDF_MAX_PAGES_PER_READ} pages per request.` })),
         }),
         execute: async (args, ctx) => {
-            const { offset, limit, pages } = args;
-            const path = fileArgPath(args);
-            if (path === undefined)
-                return errorResult(`Error (Read): file_path is required.`);
-            const fileUnchangedResult = (text, reason, startLine, endLine, totalLines) => ({
-                content: text,
-                details: { type: "file_unchanged", reason, file: { filePath: path, startLine, endLine, totalLines } },
-            });
-            const r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx), readDeny, readFace);
-            if (!r.ok)
-                return errorResult(violationText("Read", r.violation), violationDetails(r.violation));
-            const isNb = isNotebookPath(r.key);
-            const imageMime = imageMimeForRead(r.key);
-            if (imageMime !== undefined) {
-                const meta = await env.fileInfo(r.key, ctx.signal);
-                if (!meta.ok) {
-                    const ex = await env.exists(r.key, ctx.signal);
-                    if (ex.ok && !ex.value)
-                        return errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`);
-                    return errorResult(`Error (Read): cannot stat image "${path}" to verify its size before reading: ${meta.error.message}`);
-                }
-                if (meta.value.kind === "directory") {
-                    return errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`);
-                }
-                const downsampler = imageDownsampler === false ? undefined : (imageDownsampler ?? (await resolveAutoDownsampler()));
-                const readCap = downsampler ? MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES : MAX_IMAGE_READ_BYTES;
-                const tooLargeToRead = (bytes) => `Error (Read): image "${path}" is too large to read (${bytes} bytes > ${readCap}-byte cap).` +
-                    (downsampler ? "" : ` ${NO_DOWNSAMPLER_IMAGE_CAP_HINT}`);
-                if (meta.value.size > readCap) {
-                    return errorResult(tooLargeToRead(meta.value.size));
-                }
-                const bin = await env.readBinaryFile(r.key, ctx.signal);
-                if (!bin.ok)
-                    return errorResult(`Error (Read): cannot read image "${path}": ${bin.error.message}`);
-                if (bin.value.byteLength > readCap) {
-                    return errorResult(tooLargeToRead(bin.value.byteLength));
-                }
-                if (!imageMagicMatches(bin.value, imageMime)) {
-                    return errorResult(`Error (Read): "${path}" has an image extension but its content is not a valid ${imageMime} (empty, truncated, or mis-named).`);
-                }
-                let base64;
-                let mime = imageMime;
-                let dimensions;
-                if (downsampler) {
-                    const out = await downsampler(Buffer.from(bin.value), imageMime).catch(() => undefined);
-                    if (out) {
-                        base64 = out.base64;
-                        mime = out.mimeType;
-                        dimensions = out.dimensions;
-                    }
-                }
-                base64 ??= Buffer.from(bin.value).toString("base64");
-                if (base64.length > MCP_IMAGE_MAX_BASE64) {
-                    return errorResult(`Error (Read): image "${path}" is too large to send (${bin.value.byteLength} bytes; base64 ${base64.length} chars exceeds the ${MCP_IMAGE_MAX_BASE64}-char / 5MB API image limit` +
-                        (downsampler
-                            ? "; downsampling could not bring it under the limit)."
-                            : `; raw images over ${IMAGE_TARGET_RAW_SIZE} bytes always exceed it — shrink it first, e.g. with an image tool via bash).`));
-                }
-                const wasResized = dimensions !== undefined && dimensions.displayWidth > 0 && dimensions.displayHeight > 0 && (dimensions.originalWidth !== dimensions.displayWidth || dimensions.originalHeight !== dimensions.displayHeight);
-                const content = [{ type: "image", data: base64, mimeType: mime }];
-                if (wasResized && dimensions) {
-                    const scale = dimensions.originalWidth / dimensions.displayWidth;
-                    content.push({
-                        type: "text",
-                        text: `[Image: original ${dimensions.originalWidth}x${dimensions.originalHeight}, displayed at ${dimensions.displayWidth}x${dimensions.displayHeight}. Multiply coordinates by ${scale.toFixed(2)} to map to original image.]`,
-                    });
-                }
-                return {
-                    content,
-                    details: {
-                        type: "image",
-                        file: { ...(base64.length <= 48_000 ? { base64 } : {}), type: mime, originalSize: bin.value.byteLength, ...(dimensions ? { dimensions } : {}) },
-                    },
-                };
-            }
-            if (r.key.toLowerCase().endsWith(".pdf")) {
-                return pdfResultToToolReturn(await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, undefined, pdfCapabilities, readDeny, pdfReminderDisclosure(r.key)));
-            }
-            const binaryExt = hasBinaryExtension(r.key);
-            const binaryExtRefusal = () => errorResult(`Error (Read): "${path}" appears to be a binary file (by extension); this tool reads UTF-8 text only.`);
-            const info = await env.fileInfo(r.key, ctx.signal);
-            if (info.ok) {
-                if (info.value.kind === "directory") {
-                    return errorResult(`Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`);
-                }
-                if (info.value.size > SLICED_READ_MAX_BYTES) {
-                    if (binaryExt)
-                        return binaryExtRefusal();
-                    return errorResult(`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
-                        `(${info.value.size} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
-                        `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
-                }
-                if (!isNb && info.value.size > MAX_READ_BYTES && limit === undefined) {
-                    if (binaryExt)
-                        return binaryExtRefusal();
-                    return errorResult(`Error (Read): "${path}" is too large to read in full (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
-                }
-            }
-            else {
-                const ex = await env.exists(r.key, ctx.signal);
-                if (ex.ok && !ex.value)
-                    return errorResult(`Error (Read): ${await enoentMessage(env, r.key, cwdRef?.current ?? rootCanonical, ctx.signal, readDeny)}`);
-                return errorResult(`Error (Read): cannot determine the type of "${path.slice(0, 300)}" (stat failed: ${info.error.message.slice(0, 200)}); refusing to open it — if it is a FIFO/socket/device, reading it would hang. Retry if this was transient, or inspect it with Bash (e.g. \`file\`, \`ls -l\`).`);
-            }
-            const readBin = await env.readBinaryFile(r.key, ctx.signal);
-            if (!readBin.ok)
-                return errorResult(`Error (Read): cannot read "${path}": ${readBin.error.message}`);
-            const readSize = readBin.value.byteLength;
-            if (readSize > SLICED_READ_MAX_BYTES) {
-                if (binaryExt)
-                    return binaryExtRefusal();
-                return errorResult(`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
-                    `(${readSize} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
-                    `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
-            }
-            if (!isNb && readSize > MAX_READ_BYTES && limit === undefined) {
-                if (binaryExt)
-                    return binaryExtRefusal();
-                return errorResult(`Error (Read): "${path}" is too large to read in full (${readSize} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`);
-            }
-            if (pdfMagicMatches(readBin.value)) {
-                return pdfResultToToolReturn(await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, readBin.value, pdfCapabilities, readDeny, pdfReminderDisclosure(r.key)));
-            }
-            const magicFormat = binaryMagicFormat(readBin.value);
-            if (magicFormat !== undefined) {
-                return errorResult(`Error (Read): "${path}" appears to be a binary file (${magicFormat}, identified by its file signature — whatever its extension says); ` +
-                    `this tool reads UTF-8 and BOM-marked UTF-16LE text only. Inspect or convert it with bash instead.`);
-            }
-            const decoded = decodeTextBytes(readBin.value);
-            if (decoded.malformed) {
-                return errorResult(`Error (Read): "${path}" has a UTF-16 BOM but a truncated (odd-length) body — the file is corrupt or mis-labelled; repair/convert it with bash (e.g. \`iconv\`) first.`);
-            }
-            const content = decoded.text;
-            if (isBinaryContent(content.slice(0, 8192))) {
-                return errorResult(`Error (Read): "${path}" appears to be a binary file (non-text content); this tool reads UTF-8 and BOM-marked UTF-16LE text only. ` +
-                    `If it is UTF-16 without a BOM or a legacy encoding, convert it first (e.g. \`iconv -f UTF-16LE -t UTF-8\`) or inspect/transform it with bash.`);
-            }
-            const nbParsed = isNb ? parseNotebookCells(content, path) : undefined;
-            const nbForced = nbParsed !== undefined && nbParsed.ok;
-            const effOffset = nbForced ? undefined : offset;
-            const effLimit = nbForced ? undefined : limit;
-            const lines = content.length === 0 ? [] : content.split("\n");
-            const total = lines.length;
-            const start = Math.max(1, Math.floor(effOffset ?? 1));
-            const max = effLimit !== undefined ? Math.max(1, Math.floor(effLimit)) : Number.MAX_SAFE_INTEGER;
-            if (total > 0 && start > total) {
-                return `${openSystemReminder(reminderMark)}Warning: the file exists but is shorter than the provided offset (${start}). The file has ${total} lines.</system-reminder>`;
-            }
-            let slice = lines.slice(start - 1, start - 1 + max);
-            let end = start - 1 + slice.length;
-            if (end === total - 1 && lines[total - 1] === "") {
-                slice = lines.slice(start - 1, total);
-                end = total;
-            }
-            const hash = sha256(content);
-            let nbFallbackPrefix = "";
-            if (nbParsed !== undefined) {
-                if (nbParsed.ok) {
-                    const parsed = nbParsed;
-                    const rendered = renderNotebookCells(parsed.cells, NOTEBOOK_IMAGE_BASE64_BUDGET);
-                    if (rendered.textChars > MAX_READ_OUTPUT_CHARS) {
-                        return errorResult(`Error (Read): notebook "${path}" projects to ~${Math.round(rendered.textChars / 4)} tokens of cell content, over the 25000-token limit ` +
-                            `(offset/limit do not apply to notebooks — the whole notebook is always projected). Inspect portions with Bash + jq instead, e.g.\n` +
-                            `  cat "${path}" | jq '.cells[:20]' # First 20 cells\n` +
-                            `  cat "${path}" | jq '.cells | length' # Count total cells\n` +
-                            `  cat "${path}" | jq '.cells[] | select(.cell_type=="code") | .source' # All code sources`);
-                    }
-                    const prevNb = state.get(r.key);
-                    if (prevNb?.seededFromContext && !prevNb.isPartialView && prevNb.hash === hash) {
-                        return fileUnchangedResult(seededFileUnchangedReminder(r.key, reminderMark), "already-in-context", 1, total, total);
-                    }
-                    if (prevNb && !prevNb.isPartialView && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
-                        return fileUnchangedResult(`[${path}: unchanged since you last read it (lines 1-${total} of ${total}); content omitted to save context]`, "unchanged-since-last-read", 1, total, total);
-                    }
-                    state.set(r.key, { hash, totalLines: countLines(content), truncated: false, view: { start: 1, end: total }, lastReadAt: Date.now(), transmittedByToolCallId: ctx.toolCallId });
-                    const bodyBlocks = rendered.blocks.length > 0 ? rendered.blocks : [{ type: "text", text: "[notebook has 0 cells]" }];
-                    const nbDisclosure = discloseReminderShaped({
-                        segments: rendered.blocks.filter((b) => b.type === "text").map((b) => b.text),
-                        mark: reminderMark,
-                        outlet: "notebook",
-                        defuseExactMark: false,
-                        throttle: { key: r.key, windows: reminderDisclosureWindows },
-                        counts: reminderDisclosureCounts,
-                    });
-                    return {
-                        content: [
-                            ...bodyBlocks,
-                            ...(nbDisclosure.trailer !== undefined ? [{ type: "text", text: nbDisclosure.trailer }] : []),
-                        ],
-                        details: { type: "notebook", file: { filePath: path, cells: parsed.cells.map(stripNotebookImageData) } },
-                    };
-                }
-                nbFallbackPrefix = "[not a parseable notebook — showing raw file text]\n";
-            }
-            const renderBody = (sl) => sl.map((l, i) => `${start + i}\t${l}`).join("\n");
-            let body = renderBody(slice);
-            let pageMarker;
-            if (body.length > MAX_READ_OUTPUT_CHARS) {
-                const defaultFullRead = start <= 1 && effLimit === undefined;
-                if (!defaultFullRead) {
-                    return errorResult(`Error (Read): the requested range of "${path}" is ~${Math.round(body.length / 4)} tokens, over the 25000-token limit. Narrow it with offset/limit, or use grep to search the file.`);
-                }
-                const approxTokens = Math.round(body.length / 4);
-                let n = Math.max(1, Math.min(slice.length, Math.floor(slice.length * (MAX_READ_OUTPUT_CHARS / body.length) * 0.95)));
-                let paged = slice.slice(0, n);
-                let pagedBody = renderBody(paged);
-                for (let attempt = 0; attempt < 8 && pagedBody.length > MAX_READ_OUTPUT_CHARS && n > 1; attempt++) {
-                    n = Math.max(1, Math.floor(n * 0.7));
-                    paged = slice.slice(0, n);
-                    pagedBody = renderBody(paged);
-                }
-                if (pagedBody.length <= MAX_READ_OUTPUT_CHARS) {
-                    slice = paged;
-                    end = start - 1 + slice.length;
-                    body = pagedBody;
-                    pageMarker =
-                        `[Truncated: PARTIAL view — showing lines 1-${end} of ${total} total (~${approxTokens} tokens, cap 25000). ` +
-                            `Call Read with offset=${end + 1} limit=${end} for the next page, or Grep to find a specific section. ` +
-                            `Do NOT answer from this page alone if the answer may be further in the file.]\n`;
-                }
-                else {
-                    let cut = MAX_READ_OUTPUT_CHARS - 200;
-                    const cc = slice[0].charCodeAt(cut - 1);
-                    if (cc >= 0xd800 && cc <= 0xdbff)
-                        cut -= 1;
-                    slice = [slice[0].slice(0, cut)];
-                    end = start;
-                    body = renderBody(slice);
-                    pageMarker =
-                        `[Truncated: PARTIAL view — showing the first ${cut} of ${content.length} characters (~${approxTokens} tokens, cap 25000); ` +
-                            `this file has very long lines and cannot be paginated by line. Use Grep to find a specific section, or Read with offset/limit to page through it. ` +
-                            `Do NOT answer from this excerpt alone if the answer may be elsewhere in the file.]\n`;
-                }
-            }
-            const truncated = start > 1 || end < total || pageMarker !== undefined;
-            const prev = state.get(r.key);
-            if (total > 0 && prev?.seededFromContext && !prev.isPartialView && start === 1 && effLimit === undefined && prev.hash === hash) {
-                return fileUnchangedResult(seededFileUnchangedReminder(r.key, reminderMark), "already-in-context", 1, total, total);
-            }
-            if (total > 0 && prev && !prev.isPartialView && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
-                return fileUnchangedResult(`[${path}: unchanged since you last read it (lines ${start}-${end} of ${total}); content omitted to save context]`, "unchanged-since-last-read", start, end, total);
-            }
-            state.set(r.key, {
-                hash,
-                totalLines: countLines(content),
-                truncated,
-                ...(pageMarker !== undefined ? { isPartialView: true } : {}),
-                view: { start, end },
-                lastReadAt: Date.now(),
-                transmittedByToolCallId: ctx.toolCallId,
-            });
-            if (total === 0)
-                return `${openSystemReminder(reminderMark)}Warning: the file exists but the contents are empty.</system-reminder>`;
-            const header = pageMarker ?? (truncated ? `[${path}: lines ${start}-${end} of ${total}${end < total ? " — use offset to see more" : ""}]\n` : "");
-            const disclosure = discloseReminderShaped({
-                segments: [body],
-                mark: reminderMark,
-                outlet: "read",
-                defuseExactMark: false,
-                throttle: { key: r.key, windows: reminderDisclosureWindows },
-                counts: reminderDisclosureCounts,
-            });
-            return {
-                content: `${nbFallbackPrefix}${header}${body}${disclosure.trailer !== undefined ? `\n${disclosure.trailer}` : ""}`,
-                details: {
-                    type: "text",
-                    file: {
-                        filePath: path,
-                        content: slice.join("\n"),
-                        numLines: slice.length,
-                        startLine: start,
-                        totalLines: total,
-                        ...(pageMarker !== undefined ? { truncatedByTokenCap: true } : {}),
-                    },
-                },
-            };
+            const result = await reader.readForModel(args, ctx);
+            reader.commit(result, { transmittedByToolCallId: ctx.toolCallId });
+            return renderReadToolResult(result, reminderMark);
         },
     });
 }