@sema-agent/core 1.452.0 → 2.0.1

package/dist/tools/fs/fs-pdf.d.ts

@@ -0,0 +1,22 @@
+import { errorResult } from "../../core/tools.js";
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import { type PdfModelCapabilities } from "./pdf.js";
+import { type ReadImageDownsamplerOption } from "./fs-shared.js";
+export { pdfModelCapabilitiesOf, type PdfModelCapabilities } from "./pdf.js";
+type ReadPdfReturn = string | {
+    content: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    } | {
+        type: "document";
+        data: string;
+        mimeType: string;
+    }>;
+    details: unknown;
+};
+export declare function readPdfFile(env: ExecutionEnv, path: string, key: string, pages: string | undefined, signal: AbortSignal | undefined, downsamplerOpt: ReadImageDownsamplerOption, cwd: string, preRead?: Uint8Array, caps?: PdfModelCapabilities): Promise<ReadPdfReturn>;
+export declare function pdfResultToToolReturn(r: ReadPdfReturn): ReturnType<typeof errorResult> | Exclude<ReadPdfReturn, string>;

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

@@ -0,0 +1,236 @@
+import { errorResult } from "../../core/tools.js";
+import { delimitUntrusted } from "../../core/untrusted-text.js";
+import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
+import { PDF_FALLBACK_RENDER_PAGES, PDF_INLINE_PAGE_THRESHOLD, PDF_MAX_EXTRACT_SIZE, PDF_MAX_PAGES_PER_READ, PDF_TARGET_RAW_SIZE, extractPdfPagesAsImages, extractPdfTextLayer, getPdfPageCount, parsePdfPageRange, pdfMagicMatches, } from "./pdf.js";
+import { resolveAutoDownsampler, enoentMessage, MAX_READ_BYTES } from "./fs-shared.js";
+export { pdfModelCapabilitiesOf } from "./pdf.js";
+async function pdfPagesToImageBlocks(pages, path, downsamplerOpt) {
+    const downsampler = downsamplerOpt === false ? undefined : (downsamplerOpt ?? (await resolveAutoDownsampler()));
+    const blocks = [];
+    for (const p of pages) {
+        let b64;
+        let mime = "image/jpeg";
+        if (downsampler) {
+            const out = await downsampler(Buffer.from(p.jpeg), "image/jpeg").catch(() => undefined);
+            if (out) {
+                b64 = out.base64;
+                mime = out.mimeType;
+            }
+        }
+        b64 ??= Buffer.from(p.jpeg).toString("base64");
+        if (b64.length > MCP_IMAGE_MAX_BASE64) {
+            return `Error (Read): rendered page ${p.pageNumber} of "${path}" is too large to send (base64 ${b64.length} chars exceeds the ${MCP_IMAGE_MAX_BASE64}-char / 5MB API image limit); narrow the range or extract text via Bash (e.g. \`pdftotext\`).`;
+        }
+        blocks.push({ type: "image", data: b64, mimeType: mime });
+    }
+    return blocks;
+}
+function boundPdfExtractedText(text) {
+    if (Buffer.byteLength(text, "utf8") <= MAX_READ_BYTES)
+        return { body: text, truncated: false };
+    return { body: text.slice(0, MAX_READ_BYTES), truncated: true };
+}
+export async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, preRead, caps) {
+    const cap = caps ?? { document: true, vision: true };
+    const meta = await env.fileInfo(key, signal);
+    if (!meta.ok) {
+        const ex = await env.exists(key, signal);
+        if (ex.ok && !ex.value)
+            return `Error (Read): ${await enoentMessage(env, key, cwd, signal)}`;
+        return `Error (Read): cannot stat PDF "${path}" to verify its size before reading: ${meta.error.message}`;
+    }
+    if (meta.value.kind === "directory") {
+        return `Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`;
+    }
+    const size = preRead ? preRead.byteLength : meta.value.size;
+    if (size > PDF_MAX_EXTRACT_SIZE) {
+        return `Error (Read): PDF "${path}" exceeds the maximum size for PDF reading (${size} bytes > ${PDF_MAX_EXTRACT_SIZE}-byte / 100 MB cap).`;
+    }
+    let bytes = preRead;
+    if (bytes === undefined && size <= PDF_TARGET_RAW_SIZE) {
+        const bin = await env.readBinaryFile(key, signal);
+        if (!bin.ok)
+            return `Error (Read): cannot read PDF "${path}": ${bin.error.message}`;
+        bytes = bin.value;
+    }
+    if (bytes !== undefined && !pdfMagicMatches(bytes)) {
+        return `Error (Read): "${path}" has a .pdf extension but its content is not a valid PDF (no %PDF- header; empty, truncated, or mis-named).`;
+    }
+    if (pages !== undefined) {
+        const range = parsePdfPageRange(pages);
+        if (range === undefined) {
+            return `Error (Read): Invalid pages parameter: "${pages}". Use formats like "1-5", "3", or "10-20". Pages are 1-indexed.`;
+        }
+        if (range.last !== Infinity && range.last - range.first + 1 > PDF_MAX_PAGES_PER_READ) {
+            return `Error (Read): Page range "${pages}" exceeds maximum of ${PDF_MAX_PAGES_PER_READ} pages per request. Please use a smaller range.`;
+        }
+        const pageCount = await getPdfPageCount(env, key, bytes, signal);
+        if (pageCount !== undefined && range.first > pageCount) {
+            return `Error (Read): page range "${pages}" starts past the end of the PDF (${pageCount} page${pageCount === 1 ? "" : "s"}).`;
+        }
+        let last = range.last === Infinity ? range.first + PDF_MAX_PAGES_PER_READ - 1 : range.last;
+        if (pageCount !== undefined)
+            last = Math.min(last, pageCount);
+        if (!cap.document && !cap.vision) {
+            const t = await extractPdfTextLayer(env, key, { first: range.first, last }, signal);
+            if (t.ok) {
+                const { body, truncated } = boundPdfExtractedText(t.text);
+                const timeoutNote = t.timedOutAfterSec !== undefined
+                    ? `; PARTIAL — pdftotext timed out after ${t.timedOutAfterSec}s, so the text below covers only what was extracted before the timeout; use a narrower pages range for the rest`
+                    : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""} extracted as text via pdftotext (the serving model does not support native PDF input)${timeoutNote}]` +
+                                `\n${delimitUntrusted("PDF text layer", body)}${truncated ? `\n[extracted text truncated at ${MAX_READ_BYTES} bytes; narrow the pages range]` : ""}`,
+                        },
+                    ],
+                    details: {
+                        type: "document",
+                        file: { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}), pages: `${range.first}-${last}`, ...(t.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
+                        fallback: { level: 1, reason: "model lacks document input; text layer extracted via pdftotext" },
+                    },
+                };
+            }
+            const why = t.toolMissing ? "the poppler utility `pdftotext` is not available in this environment" : `pdftotext failed: ${t.error}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `[PDF pages ${range.first}-${last} of ${path} omitted: the serving model supports neither native PDF (document) input nor image input, and engine-side text extraction did not run (${why}). ` +
+                            `Install poppler-utils, or extract the text via Bash (e.g. \`pdftotext -layout -f ${range.first} -l ${last} "${path}" -\`).]`,
+                    },
+                ],
+                details: {
+                    type: "document",
+                    file: { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}), pages: `${range.first}-${last}` },
+                    fallback: { level: 3, reason: why },
+                },
+            };
+        }
+        const extract = await extractPdfPagesAsImages(env, key, range.first, last, signal);
+        if (!extract.ok) {
+            if (extract.toolMissing) {
+                return (`Error (Read): reading a PDF page range requires the poppler utility \`pdftoppm\`, which is not available in this environment. ` +
+                    `Read the whole PDF without \`pages\` (works up to ${PDF_INLINE_PAGE_THRESHOLD} pages / 20 MB), or extract text via Bash (e.g. \`pdftotext\`).`);
+            }
+            return `Error (Read): PDF page extraction failed for "${path}": ${extract.error}`;
+        }
+        const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
+        if (typeof blocks === "string")
+            return blocks;
+        const requestedPages = last - range.first + 1;
+        const renderedAll = extract.pages.length >= requestedPages;
+        const header = extract.timedOutAfterSec !== undefined
+            ? renderedAll
+                ? `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm timed out after ${extract.timedOutAfterSec}s, but all ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} were rendered before the timeout hit at teardown (100 dpi); nothing is missing.]`
+                : `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm timed out after ${extract.timedOutAfterSec}s; rendered ${extract.pages.length} of ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} before the timeout (100 dpi). Read the remaining pages with a narrower range (e.g. pages: "${range.first + extract.pages.length}-${last}").]`
+            : `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""} rendered as ${extract.pages.length} image${extract.pages.length === 1 ? "" : "s"} (100 dpi)]`;
+        const content = [
+            { type: "text", text: header },
+            ...blocks,
+        ];
+        return {
+            content,
+            details: {
+                type: "document",
+                file: {
+                    type: "application/pdf",
+                    originalSize: size,
+                    ...(pageCount !== undefined ? { pageCount } : {}),
+                    pages: `${range.first}-${last}`,
+                    renderedPages: extract.pages.length,
+                    ...(extract.timedOutAfterSec !== undefined ? { requestedPages, timedOut: true } : {}),
+                },
+            },
+        };
+    }
+    const pageCount = await getPdfPageCount(env, key, bytes, signal);
+    if (pageCount !== undefined && pageCount > PDF_INLINE_PAGE_THRESHOLD) {
+        return `Error (Read): This PDF has ${pageCount} pages, which is too many to read at once. Use the pages parameter to read specific page ranges (e.g., pages: "1-5"). Maximum ${PDF_MAX_PAGES_PER_READ} pages per request.`;
+    }
+    if (size > PDF_TARGET_RAW_SIZE || bytes === undefined) {
+        return `Error (Read): PDF file exceeds maximum allowed size of 20.0 MB (${size} bytes). Use the pages parameter to read specific page ranges (e.g., pages: "1-5"), or extract text via Bash (e.g. \`pdftotext\`).`;
+    }
+    if (!cap.document) {
+        const fileCard = { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}) };
+        const t = await extractPdfTextLayer(env, key, undefined, signal);
+        if (t.ok) {
+            const { body, truncated } = boundPdfExtractedText(t.text);
+            const timeoutNote = t.timedOutAfterSec !== undefined
+                ? `; PARTIAL — pdftotext timed out after ${t.timedOutAfterSec}s, so the text below covers only what was extracted before the timeout; use the pages parameter for the rest`
+                : "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `[PDF: ${path} — extracted text layer via pdftotext${pageCount !== undefined ? `; ${pageCount} page${pageCount === 1 ? "" : "s"}` : ""} (the serving model does not support native PDF input)${timeoutNote}]` +
+                            `\n${delimitUntrusted("PDF text layer", body)}${truncated ? `\n[extracted text truncated at ${MAX_READ_BYTES} bytes; use the pages parameter to read specific ranges]` : ""}`,
+                    },
+                ],
+                details: {
+                    type: "document",
+                    file: { ...fileCard, ...(t.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
+                    fallback: { level: 1, reason: "model lacks document input; text layer extracted via pdftotext" },
+                },
+            };
+        }
+        const textWhy = t.toolMissing ? "`pdftotext` is not available in this environment" : `pdftotext failed: ${t.error}`;
+        let renderWhy;
+        if (cap.vision) {
+            const n = Math.min(PDF_FALLBACK_RENDER_PAGES, pageCount ?? PDF_FALLBACK_RENDER_PAGES);
+            const extract = await extractPdfPagesAsImages(env, key, 1, n, signal);
+            if (extract.ok) {
+                const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
+                if (typeof blocks !== "string") {
+                    const renderTimeoutNote = extract.timedOutAfterSec !== undefined ? ` pdftoppm timed out after ${extract.timedOutAfterSec}s — only the pages that finished rendering are included.` : "";
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `[PDF: ${path} — first ${extract.pages.length}${pageCount !== undefined ? ` of ${pageCount}` : ""} page${extract.pages.length === 1 ? "" : "s"} rendered as image${extract.pages.length === 1 ? "" : "s"} (100 dpi; ${textWhy}).${renderTimeoutNote} ` +
+                                    `Use the pages parameter (e.g., pages: "${extract.pages.length + 1}-${extract.pages.length + PDF_FALLBACK_RENDER_PAGES}") to read more pages.]`,
+                            },
+                            ...blocks,
+                        ],
+                        details: {
+                            type: "document",
+                            file: { ...fileCard, pages: `1-${extract.pages.length}`, renderedPages: extract.pages.length, ...(extract.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
+                            fallback: { level: 2, reason: `model lacks document input; ${textWhy}; rendered first ${extract.pages.length} page(s) via pdftoppm` },
+                        },
+                    };
+                }
+                renderWhy = "a rendered page image exceeded the per-image API size limit";
+            }
+            else {
+                renderWhy = extract.toolMissing ? "the poppler utility `pdftoppm` is not available in this environment" : `pdftoppm failed: ${extract.error}`;
+            }
+        }
+        else {
+            renderWhy = "the serving model does not support image input, so pages cannot be rendered";
+        }
+        const why = `text extraction did not run (${textWhy}); page rendering did not run (${renderWhy})`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `[PDF document omitted: the serving model does not support native PDF (document) input, and engine-side fallbacks were unavailable — ${why}. ` +
+                        `Install poppler-utils, or extract the text via Bash (e.g. \`pdftotext -layout "${path}" -\`).]`,
+                },
+            ],
+            details: { type: "document", file: fileCard, fallback: { level: 3, reason: why } },
+        };
+    }
+    const base64 = Buffer.from(bytes).toString("base64");
+    return {
+        content: [{ type: "document", data: base64, mimeType: "application/pdf" }],
+        details: {
+            type: "document",
+            file: { ...(base64.length <= 48_000 ? { base64 } : {}), type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}) },
+        },
+    };
+}
+export function pdfResultToToolReturn(r) {
+    return typeof r === "string" ? errorResult(r) : r;
+}

package/dist/tools/fs/fs-read.d.ts

@@ -0,0 +1,8 @@
+import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
+import { type ReadFileState } from "./safety.js";
+import { type PdfModelCapabilities } from "./pdf.js";
+import { type ReadImageDownsamplerOption, type CwdRef } from "./fs-shared.js";
+export declare function createReadFileTool(env: ExecutionEnv, state: ReadFileState, rootCanonical: string, cwdRef?: CwdRef, additionalRoots?: readonly string[], imageDownsampler?: ReadImageDownsamplerOption, pdfCapabilities?: PdfModelCapabilities, bgOutputReadExemption?: (canonicalKey: string, ctx: {
+    taskId?: string;
+    principal?: string;
+}) => boolean): AgentTool;

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

@@ -0,0 +1,286 @@
+import { Type } from "typebox";
+import { defineTool, errorResult } from "../../core/tools.js";
+import { sha256, resolveKey, violationText, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, } 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, resolveAutoDownsampler, MAX_READ_OUTPUT_CHARS, READ_CYBER_REMINDER, FILE_PATH_PARAMS, countLines, seededFileUnchangedReminder, enoentMessage, } from "./fs-shared.js";
+import { readPdfFile, pdfResultToToolReturn } from "./fs-pdf.js";
+export function createReadFileTool(env, state, rootCanonical, cwdRef, additionalRoots, imageDownsampler, pdfCapabilities, bgOutputReadExemption) {
+    return defineTool({
+        name: "Read",
+        contract: { contractId: "core.read@1", implementationRevision: "1" },
+        description: "Reads a file from the local filesystem.\n" +
+            "\n" +
+            "- `file_path` may be relative (resolved against the tracked working directory) or absolute (within the configured roots).\n" +
+            "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call.\n" +
+            "- When you already know which part of the file you need, only read that part. This can be important for larger files.\n" +
+            "- Results are returned using cat -n format, with line numbers starting at 1\n" +
+            "- Reads images (PNG, JPG, …) and presents them visually. Reads PDFs via the `pages` parameter (e.g. \"1-5\", max 20 pages/request; a PDF whose detected page count exceeds 10 requires `pages`). Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
+            "- Reading a directory, a missing file, or an empty file returns an error or warning rather than content.\n" +
+            "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
+            "- You must read a file before editing it.\n" +
+            "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
+        descriptionClassic: "Reads a file from the local filesystem.\n" +
+            "\n" +
+            "Usage:\n" +
+            "- By default, it reads the whole file (from `offset`, 1-based); a very large file is served as a partial view with an explicit marker and the next-page call\n" +
+            "- When you already know which part of the file you need, only read that part. This can be important for larger files.\n" +
+            "- Results are returned using cat -n format, with each line prefixed by its line number and a tab\n" +
+            "- This tool allows the model to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually.\n" +
+            "- This tool can only read files, not directories. To read a directory, use Glob/Grep or an ls command via the Bash tool.\n" +
+            "- You must read a file before editing it.\n" +
+            "- Reads PDFs (.pdf): the document is provided to the model directly (text layer included). Use the `pages` parameter (e.g., \"1-5\") to read a page range; a PDF whose detected page count exceeds 10 requires `pages`. Maximum 20 pages per request.\n" +
+            "- Reads Jupyter notebooks (.ipynb) as cells with outputs (offset/limit do not apply).\n" +
+            "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
+            "- If you read a file that exists but has empty contents you will receive a warning in place of file contents.\n" +
+            "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
+        parameters: Type.Object({
+            ...FILE_PATH_PARAMS,
+            offset: Type.Optional(Type.Number({ description: "The line number to start reading from. Only provide if the file is too large to read at once (1-based; default 1)." })),
+            limit: Type.Optional(Type.Number({ description: "The number of lines to read. Only provide if the file is too large to read at once. (Default: the whole file, bounded by the output-token cap.)" })),
+            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.` })),
+        }),
+        effect: "read",
+        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 r = await resolveKey(env, rootCanonical, path, ctx.signal, cwdRef?.current, additionalRoots, bgOutputReadExemption === undefined ? undefined : (key) => bgOutputReadExemption(key, ctx));
+            if (!r.ok)
+                return errorResult(violationText("Read", 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)}`);
+                    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;
+                if (meta.value.size > readCap) {
+                    return errorResult(`Error (Read): image "${path}" is too large to read (${meta.value.size} bytes > ${readCap}-byte cap).`);
+                }
+                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(`Error (Read): image "${path}" is too large to read (${bin.value.byteLength} bytes > ${readCap}-byte cap).`);
+                }
+                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));
+            }
+            if (hasBinaryExtension(r.key)) {
+                return 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) {
+                    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 && offset === undefined && limit === undefined) {
+                    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)}`);
+            }
+            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) {
+                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 && offset === undefined && limit === undefined) {
+                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));
+            }
+            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, 4096))) {
+                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 `<system-reminder>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.hash === hash) {
+                        return seededFileUnchangedReminder(r.key);
+                    }
+                    if (prevNb && prevNb.hash === hash && prevNb.view && prevNb.view.start === 1 && prevNb.view.end === total) {
+                        return `[${path}: unchanged since you last read it (lines 1-${total} of ${total}); content omitted to save context]`;
+                    }
+                    state.set(r.key, { hash, totalLines: countLines(content), truncated: false, view: { start: 1, end: total }, lastReadAt: Date.now() });
+                    const bodyBlocks = rendered.blocks.length > 0 ? rendered.blocks : [{ type: "text", text: "[notebook has 0 cells]" }];
+                    return {
+                        content: [...bodyBlocks, { type: "text", text: READ_CYBER_REMINDER }],
+                        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 && start === 1 && effLimit === undefined && prev.hash === hash) {
+                return seededFileUnchangedReminder(r.key);
+            }
+            if (total > 0 && prev && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
+                return `[${path}: unchanged since you last read it (lines ${start}-${end} of ${total}); content omitted to save context]`;
+            }
+            state.set(r.key, {
+                hash,
+                totalLines: countLines(content),
+                truncated,
+                ...(pageMarker !== undefined ? { isPartialView: true } : {}),
+                view: { start, end },
+                lastReadAt: Date.now(),
+            });
+            if (total === 0)
+                return `<system-reminder>Warning: the file exists but is shorter than the provided offset (${start}). The file has 1 lines.</system-reminder>`;
+            const header = pageMarker ?? (truncated ? `[${path}: lines ${start}-${end} of ${total}${end < total ? " — use offset to see more" : ""}]\n` : "");
+            return {
+                content: `${nbFallbackPrefix}${header}${body}${READ_CYBER_REMINDER}`,
+                details: {
+                    type: "text",
+                    file: {
+                        filePath: path,
+                        content: slice.join("\n"),
+                        numLines: slice.length,
+                        startLine: start,
+                        totalLines: total,
+                        ...(pageMarker !== undefined ? { truncatedByTokenCap: true } : {}),
+                    },
+                },
+            };
+        },
+    });
+}

package/dist/tools/fs/fs-search-tools.d.ts

@@ -0,0 +1,5 @@
+import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
+import type { ToolEffect } from "../../core/types.js";
+export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
+export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;
+export declare const HAND_TOOL_EFFECTS: Readonly<Record<string, ToolEffect>>;