comisai 1.0.4

package/node_modules/@comis/skills/dist/builtin/file-tools/notebook-edit-tool.js

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Native notebook edit tool: cell-level Jupyter notebook editing with
+ * replace, insert, and delete operations.
+ *
+ * Follows the edit-tool.ts pattern: factory function returning AgentTool
+ * with inline validation pipeline (V1-V11).
+ *
+ * @module
+ */
+import { Type } from "@sinclair/typebox";
+import * as fs from "node:fs/promises";
+import { extname } from "node:path";
+import { fromPromise } from "@comis/shared";
+import { safePath, PathTraversalError } from "@comis/core";
+import { isDeviceFile } from "../file/file-state-tracker.js";
+import { readStringParam } from "../platform/tool-helpers.js";
+import { readFileWithMetadata, writeFilePreserving, } from "./shared/file-encoding.js";
+import { parseNotebook } from "./shared/notebook-utils.js";
+import { resolveCellIndex, replaceCell, insertCell, deleteCell, serializeNotebook, } from "./shared/notebook-edit-ops.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum file size in bytes (1 GiB). Files above this are rejected. */
+const MAX_FILE_SIZE = 1024 * 1024 * 1024;
+const VALID_EDIT_MODES = new Set(["replace", "insert", "delete"]);
+// ---------------------------------------------------------------------------
+// Parameter schema
+// ---------------------------------------------------------------------------
+const NotebookEditParams = Type.Object({
+    path: Type.String({
+        description: "Path to the Jupyter notebook (.ipynb) to edit (relative to workspace or absolute)",
+    }),
+    cell_id: Type.Optional(Type.String({
+        description: "Cell ID or index ('cell-N' format). For replace/delete: identifies the target cell. For insert: new cell goes after this cell. Omit to insert at beginning.",
+    })),
+    new_source: Type.Optional(Type.String({
+        description: "New source content for the cell. Required for replace and insert.",
+    })),
+    cell_type: Type.Optional(Type.Union([Type.Literal("code"), Type.Literal("markdown"), Type.Literal("raw")], {
+        description: "Cell type. Required for insert. For replace, defaults to existing cell type.",
+    })),
+    edit_mode: Type.Optional(Type.Union([
+        Type.Literal("replace"),
+        Type.Literal("insert"),
+        Type.Literal("delete"),
+    ], {
+        description: "Edit operation: replace (default), insert (new cell), or delete (remove cell).",
+        default: "replace",
+    })),
+}, { additionalProperties: false });
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a notebook edit tool for cell-level Jupyter notebook operations.
+ *
+ * @param workspacePath - Workspace root for path resolution
+ * @param logger - Optional structured logger
+ * @param tracker - Optional file state tracker for read-before-edit enforcement
+ * @returns AgentTool implementing notebook_edit
+ */
+export function createComisNotebookEditTool(workspacePath, logger, tracker) {
+    return {
+        name: "notebook_edit",
+        label: "Notebook Edit",
+        description: "Edit Jupyter notebook (.ipynb) cells. Supports replace (update cell source), " +
+            "insert (add new cell), and delete (remove cell) operations. Target cells by ID " +
+            "or index (cell-1, cell-2, ...). You must read the notebook in the current response " +
+            "before editing (reads from previous messages do not carry over). " +
+            "For insert mode, cell_type is required. Code cell outputs and execution counts " +
+            "are cleared on replace.",
+        parameters: NotebookEditParams,
+        async execute(_toolCallId, params) {
+            // V1 -- Extension check
+            const filePath = readStringParam(params, "path");
+            if (extname(filePath).toLowerCase() !== ".ipynb") {
+                throw new Error("[not_notebook] Only .ipynb files can be edited with notebook_edit. Use the edit tool for other file types.");
+            }
+            // V2 -- Edit mode validation
+            const editMode = params.edit_mode ?? "replace";
+            if (!VALID_EDIT_MODES.has(editMode)) {
+                throw new Error(`[invalid_edit_mode] Invalid edit_mode "${editMode}". Must be one of: replace, insert, delete.`);
+            }
+            // V3 -- Conditional parameter validation
+            const cellId = params.cell_id;
+            const newSource = params.new_source;
+            const cellType = params.cell_type;
+            if (editMode === "insert" && !cellType) {
+                throw new Error("[missing_cell_type] cell_type is required for insert mode. Specify 'code', 'markdown', or 'raw'.");
+            }
+            if ((editMode === "replace" || editMode === "delete") && !cellId) {
+                throw new Error(`[missing_cell_id] cell_id is required for ${editMode} mode. Specify the target cell ID or index (e.g., 'cell-1').`);
+            }
+            if ((editMode === "replace" || editMode === "insert") &&
+                newSource === undefined) {
+                throw new Error(`[missing_source] new_source is required for ${editMode} mode. Provide the new cell content.`);
+            }
+            // V4 -- Path resolution
+            let resolvedPath;
+            try {
+                resolvedPath = safePath(workspacePath, filePath);
+            }
+            catch (error) {
+                if (!(error instanceof PathTraversalError))
+                    throw error;
+                throw new Error(`[path_traversal] Path outside workspace bounds: ${filePath}`, { cause: error });
+            }
+            // V5 -- File existence + stat
+            const statResult = await fromPromise(fs.stat(resolvedPath));
+            if (!statResult.ok) {
+                throw new Error(`[file_not_found] File not found: ${filePath}`);
+            }
+            const stat = statResult.value;
+            // V6 -- File size limit
+            if (stat.size > MAX_FILE_SIZE) {
+                throw new Error("[file_too_large] File too large. Maximum: 1 GiB");
+            }
+            // V7 -- Device file check
+            if (isDeviceFile(resolvedPath)) {
+                throw new Error(`[device_file] Cannot edit device file: ${resolvedPath}`);
+            }
+            // V8 -- Read-before-edit
+            if (tracker && !tracker.hasBeenRead(resolvedPath)) {
+                throw new Error(`[not_read] You must read the notebook before editing. Use the read tool first: read ${filePath}`);
+            }
+            // V9 -- Staleness with content-hash fallback
+            if (tracker) {
+                const currentContent = await fs.readFile(resolvedPath);
+                const staleness = tracker.checkStaleness(resolvedPath, stat.mtimeMs, currentContent);
+                if (staleness.stale) {
+                    throw new Error("[stale_file] Notebook was modified since you last read it (mtime changed). Read the notebook again before editing.");
+                }
+            }
+            // V10 -- Read and parse notebook
+            const fileData = await readFileWithMetadata(resolvedPath);
+            const parseResult = parseNotebook(fileData.content);
+            if (!parseResult.ok) {
+                throw new Error(`[invalid_json] Failed to parse notebook: ${parseResult.error.message}`);
+            }
+            const notebook = parseResult.value;
+            // Also parse raw JSON for mutations (raw uses snake_case keys)
+            const raw = JSON.parse(fileData.content);
+            const rawCells = raw.cells;
+            // V11 -- Cell resolution (for replace and delete)
+            let cellIndex;
+            if (cellId) {
+                cellIndex = resolveCellIndex(notebook.cells, cellId);
+                if (cellIndex === undefined) {
+                    throw new Error(`[cell_not_found] Cell "${cellId}" not found. Available cells: ${notebook.cells.map((c) => c.id).join(", ")}`);
+                }
+            }
+            // -- Execute operation --
+            if (editMode === "replace") {
+                replaceCell(rawCells, cellIndex, newSource, cellType);
+            }
+            else if (editMode === "insert") {
+                const afterIdx = cellIndex !== undefined ? cellIndex : -1;
+                insertCell(rawCells, afterIdx, newSource, cellType, notebook.nbformat, notebook.nbformatMinor);
+            }
+            else if (editMode === "delete") {
+                deleteCell(rawCells, cellIndex);
+            }
+            // -- Write back and record mtime --
+            const serialized = serializeNotebook(raw);
+            await writeFilePreserving(resolvedPath, serialized, fileData.encoding, fileData.lineEnding);
+            // Post-write: record new mtime + content hash for immediate re-edit support
+            const newStat = await fs.stat(resolvedPath);
+            const newNotebookContent = await fs.readFile(resolvedPath);
+            tracker?.recordRead(resolvedPath, newStat.mtimeMs, undefined, undefined, newNotebookContent);
+            // -- Build result --
+            const opLabel = editMode === "replace"
+                ? "Replaced"
+                : editMode === "insert"
+                    ? "Inserted"
+                    : "Deleted";
+            const targetLabel = cellId ?? "beginning";
+            const resultText = `${opLabel} cell "${targetLabel}" in ${filePath}. Notebook now has ${rawCells.length} cell(s).`;
+            logger?.debug({
+                path: filePath,
+                operation: editMode,
+                cellId: cellId ?? null,
+                cellCount: rawCells.length,
+            }, "Notebook edit complete");
+            return {
+                content: [{ type: "text", text: resultText }],
+                details: {
+                    operation: editMode,
+                    cellId: cellId ?? null,
+                    cellCount: rawCells.length,
+                },
+            };
+        },
+    };
+}

package/node_modules/@comis/skills/dist/builtin/file-tools/read-tool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Native read tool: file reading with line numbers, pagination, encoding
+ * awareness, notebook rendering, dedup, and security guards.
+ *
+ * Replaces pi-mono createReadTool + 3-layer wrapper stack (safePath +
+ * pathSuggestion + fileStateGuards) with a single self-contained factory.
+ * Follows the exec-tool.ts pattern: factory function returning AgentTool.
+ *
+ * @module
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { FileStateTracker } from "../file/file-state-tracker.js";
+import { type LazyPaths } from "../file/safe-path-wrapper.js";
+/** Minimal pino-compatible logger interface (skills does not import @comis/infra). */
+interface ToolLogger {
+    warn(obj: Record<string, unknown>, msg: string): void;
+    debug(obj: Record<string, unknown>, msg: string): void;
+}
+declare const ReadParams: import("@sinclair/typebox").TObject<{
+    path: import("@sinclair/typebox").TString;
+    offset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    pages: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/**
+ * Parse a pages parameter string into start/end page numbers.
+ *
+ * Supports: single page ("5"), range ("3-7"), undefined (default to all up to maxPages).
+ * Clamps values within [1, totalPages] and caps span at maxPages.
+ *
+ * Exported with underscore prefix for test access (project convention).
+ */
+export declare function _parsePageRangeForTest(range: string | undefined, totalPages: number, maxPages: number): {
+    start: number;
+    end: number;
+};
+/**
+ * Create the native read tool.
+ *
+ * Returns an AgentTool that reads files with line numbers, pagination,
+ * encoding awareness, notebook rendering, dedup stubs, and security guards.
+ *
+ * @param workspacePath - Workspace root directory (all relative paths resolve against this)
+ * @param logger - Optional pino-compatible logger
+ * @param tracker - Optional FileStateTracker for dedup and state recording
+ * @param readOnlyPaths - Optional additional paths that the read tool may access
+ * @param sharedPaths - Optional shared paths (lazily resolved) accessible by all tools
+ */
+export declare function createComisReadTool(workspacePath: string, logger?: ToolLogger, tracker?: FileStateTracker, readOnlyPaths?: string[], sharedPaths?: LazyPaths): AgentTool<typeof ReadParams>;
+export {};

package/node_modules/@comis/skills/dist/builtin/file-tools/read-tool.js

@@ -0,0 +1,427 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Native read tool: file reading with line numbers, pagination, encoding
+ * awareness, notebook rendering, dedup, and security guards.
+ *
+ * Replaces pi-mono createReadTool + 3-layer wrapper stack (safePath +
+ * pathSuggestion + fileStateGuards) with a single self-contained factory.
+ * Follows the exec-tool.ts pattern: factory function returning AgentTool.
+ *
+ * @module
+ */
+import { ok, err } from "@comis/shared";
+import { Type } from "@sinclair/typebox";
+import * as fs from "node:fs/promises";
+import { extname } from "node:path";
+import { safePath, PathTraversalError } from "@comis/core";
+import { isDeviceFile } from "../file/file-state-tracker.js";
+import { suggestSimilarPaths } from "../file/path-suggest.js";
+import { resolvePaths } from "../file/safe-path-wrapper.js";
+import { readStringParam, readNumberParam } from "../platform/tool-helpers.js";
+import { readFileWithMetadata } from "./shared/file-encoding.js";
+import { parseNotebook, renderNotebookCells } from "./shared/notebook-utils.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_LIMIT = 2000;
+/** Maximum file size in bytes (1 GiB). Files above this are rejected. */
+const MAX_FILE_SIZE = 1024 * 1024 * 1024;
+// ---------------------------------------------------------------------------
+// Parameter schema
+// ---------------------------------------------------------------------------
+const ReadParams = Type.Object({
+    path: Type.String({
+        description: "Path to the file to read (relative to workspace or absolute)",
+    }),
+    offset: Type.Optional(Type.Integer({
+        description: "Line number to start reading from (0-based). Use with limit for pagination.",
+    })),
+    limit: Type.Optional(Type.Integer({
+        description: "Maximum number of lines to read. Defaults to 2000.",
+        default: 2000,
+    })),
+    pages: Type.Optional(Type.String({
+        description: "Page range for PDF files (e.g., '1-5', '3', '10-20'). " +
+            "Defaults to all pages up to 50. Maximum 50 pages per request.",
+    })),
+}, { additionalProperties: false });
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Try to stat a file with Unicode fallbacks for macOS path quirks.
+ * Returns the first successful stat result and the resolved path,
+ * or null if all attempts fail.
+ */
+async function statWithFallbacks(filePath) {
+    // Attempt 1: exact path
+    try {
+        return { stat: await fs.stat(filePath), resolvedPath: filePath };
+    }
+    catch {
+        // continue to fallbacks
+    }
+    // Attempt 2: thin space (U+202F) <-> regular space (U+0020)
+    const thinSpaceVariant = filePath.includes("\u202F")
+        ? filePath.replace(/\u202F/g, " ")
+        : filePath.replace(/ /g, "\u202F");
+    try {
+        return { stat: await fs.stat(thinSpaceVariant), resolvedPath: thinSpaceVariant };
+    }
+    catch {
+        // continue
+    }
+    // Attempt 3: NFD <-> NFC normalization
+    const nfdVariant = filePath.normalize("NFD");
+    if (nfdVariant !== filePath) {
+        try {
+            return { stat: await fs.stat(nfdVariant), resolvedPath: nfdVariant };
+        }
+        catch {
+            // continue
+        }
+    }
+    const nfcVariant = filePath.normalize("NFC");
+    if (nfcVariant !== filePath) {
+        try {
+            return { stat: await fs.stat(nfcVariant), resolvedPath: nfcVariant };
+        }
+        catch {
+            // continue
+        }
+    }
+    // Attempt 4: combined (thin space + NFD)
+    const combinedVariant = thinSpaceVariant.normalize("NFD");
+    if (combinedVariant !== filePath && combinedVariant !== thinSpaceVariant && combinedVariant !== nfdVariant) {
+        try {
+            return { stat: await fs.stat(combinedVariant), resolvedPath: combinedVariant };
+        }
+        catch {
+            // all fallbacks exhausted
+        }
+    }
+    return null;
+}
+/**
+ * Format byte size as human-readable string.
+ * Examples: "512B", "4.1KB", "1.3MB", "1.1GB"
+ */
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024) {
+        const kb = bytes / 1024;
+        return `${kb < 10 ? kb.toFixed(1) : Math.round(kb)}KB`;
+    }
+    if (bytes < 1024 * 1024 * 1024) {
+        const mb = bytes / (1024 * 1024);
+        return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)}MB`;
+    }
+    const gb = bytes / (1024 * 1024 * 1024);
+    return `${gb < 10 ? gb.toFixed(1) : Math.round(gb)}GB`;
+}
+// ---------------------------------------------------------------------------
+// PDF helpers
+// ---------------------------------------------------------------------------
+/** Maximum pages extractable in a single read call. */
+const MAX_PDF_PAGES = 50;
+/**
+ * Parse a pages parameter string into start/end page numbers.
+ *
+ * Supports: single page ("5"), range ("3-7"), undefined (default to all up to maxPages).
+ * Clamps values within [1, totalPages] and caps span at maxPages.
+ *
+ * Exported with underscore prefix for test access (project convention).
+ */
+export function _parsePageRangeForTest(range, totalPages, maxPages) {
+    return parsePageRange(range, totalPages, maxPages);
+}
+function parsePageRange(range, totalPages, maxPages) {
+    if (!range) {
+        return { start: 1, end: Math.min(totalPages, maxPages) };
+    }
+    if (/^\d+$/.test(range)) {
+        const page = Math.max(1, Math.min(parseInt(range, 10), totalPages));
+        return { start: page, end: page };
+    }
+    const match = range.match(/^(\d+)-(\d+)$/);
+    if (match) {
+        const start = Math.max(1, parseInt(match[1], 10));
+        const end = Math.min(totalPages, parseInt(match[2], 10));
+        if (end - start + 1 > maxPages) {
+            return { start, end: start + maxPages - 1 };
+        }
+        return { start, end };
+    }
+    // Invalid format: fall back to defaults
+    return { start: 1, end: Math.min(totalPages, maxPages) };
+}
+/**
+ * Extract text from a PDF file using pdfjs-dist (lazy dynamic import).
+ *
+ * Returns page-separated text with "--- Page N ---" markers.
+ * Follows the same pdfjs-dist patterns as pdf-extractor.ts.
+ */
+async function extractPdfText(filePath, options) {
+    try {
+        const buffer = await fs.readFile(filePath);
+        const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+        const loadingTask = pdfjs.getDocument({
+            data: new Uint8Array(buffer),
+            isEvalSupported: false,
+            verbosity: 0,
+        });
+        const pdf = await loadingTask.promise;
+        try {
+            const { start, end } = parsePageRange(options.pages, pdf.numPages, MAX_PDF_PAGES);
+            const texts = [];
+            for (let i = start; i <= end; i++) {
+                const page = await pdf.getPage(i);
+                const content = await page.getTextContent();
+                const pageText = content.items
+                    .filter((item) => typeof item === "object" && item !== null && "str" in item)
+                    .map((item) => item.str + (item.hasEOL ? "\n" : ""))
+                    .join("");
+                texts.push(`--- Page ${i} ---\n${pageText}`);
+            }
+            let text = texts.join("\n\n");
+            if (text.length > options.maxChars) {
+                text = text.slice(0, options.maxChars) + `\n[truncated at ${options.maxChars} characters]`;
+            }
+            return ok({
+                text,
+                pageCount: end - start + 1,
+                totalPages: pdf.numPages,
+                extractedChars: text.length,
+            });
+        }
+        finally {
+            await pdf.destroy();
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes("password") ||
+            msg.includes("encrypted") ||
+            (typeof e === "object" && e !== null && e.name === "PasswordException")) {
+            return err({ kind: "encrypted", message: "PDF is password-protected" });
+        }
+        return err({ kind: "parse", message: `Failed to extract PDF: ${msg}` });
+    }
+}
+/**
+ * Resolve a read path through the workspace -> readOnlyPaths -> sharedPaths
+ * fallback chain. Returns the resolved absolute path.
+ *
+ * Throws Error with [path_traversal] prefix when the path cannot be resolved
+ * through any allowed root.
+ */
+function resolveReadPath(workspacePath, filePath, readOnlyPaths, sharedPaths) {
+    // Try workspace first
+    try {
+        return safePath(workspacePath, filePath);
+    }
+    catch (error) {
+        if (!(error instanceof PathTraversalError))
+            throw error;
+    }
+    // Try readOnlyPaths
+    if (readOnlyPaths) {
+        for (const roPath of readOnlyPaths) {
+            try {
+                return safePath(roPath, filePath);
+            }
+            catch (error) {
+                if (!(error instanceof PathTraversalError))
+                    throw error;
+                // This readOnlyPath didn't match -- try next
+            }
+        }
+    }
+    // Try sharedPaths (lazily resolved)
+    const resolved = resolvePaths(sharedPaths);
+    for (const sp of resolved) {
+        try {
+            return safePath(sp, filePath);
+        }
+        catch (error) {
+            if (!(error instanceof PathTraversalError))
+                throw error;
+            // This sharedPath didn't match -- try next
+        }
+    }
+    throw new Error(`[path_traversal] Path outside workspace bounds: ${filePath}`);
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the native read tool.
+ *
+ * Returns an AgentTool that reads files with line numbers, pagination,
+ * encoding awareness, notebook rendering, dedup stubs, and security guards.
+ *
+ * @param workspacePath - Workspace root directory (all relative paths resolve against this)
+ * @param logger - Optional pino-compatible logger
+ * @param tracker - Optional FileStateTracker for dedup and state recording
+ * @param readOnlyPaths - Optional additional paths that the read tool may access
+ * @param sharedPaths - Optional shared paths (lazily resolved) accessible by all tools
+ */
+export function createComisReadTool(workspacePath, logger, tracker, readOnlyPaths, sharedPaths) {
+    // Comis extension: promptGuidelines (not part of AgentTool type, spread to bypass excess property check)
+    const ext = { promptGuidelines: [
+            "Use offset/limit for files larger than 2000 lines instead of reading the whole file.",
+            "For PDFs, use the `pages` parameter to read specific page ranges (max 50 pages).",
+            "If file not found, use `find` or `grep` to locate the correct path.",
+        ] };
+    return {
+        ...ext,
+        name: "read",
+        label: "Read",
+        description: "Read a file with line numbers and optional pagination (offset + limit). " +
+            "Returns content with line number prefixes for reference. Handles text files, " +
+            "images (returned as-is for multimodal), PDFs (text extraction with page range support), " +
+            "and common encodings (UTF-8, UTF-16LE). " +
+            "Use offset/limit for large files. Use pages param for PDFs. Error if file not found -- safe to try.",
+        parameters: ReadParams,
+        async execute(_toolCallId, params) {
+            // Extract params
+            const filePath = readStringParam(params, "path");
+            const offset = readNumberParam(params, "offset", false) ?? 0;
+            const limit = readNumberParam(params, "limit", false) ?? DEFAULT_LIMIT;
+            // V1+V2: Path resolution (workspace -> readOnlyPaths -> sharedPaths)
+            const resolvedPath = resolveReadPath(workspacePath, filePath, readOnlyPaths, sharedPaths);
+            // V3: Device file blocking
+            if (isDeviceFile(resolvedPath)) {
+                throw new Error("[device_file] Cannot read device file: " + resolvedPath);
+            }
+            // V4: File existence + stat with Unicode fallbacks (macOS screenshot paths)
+            const fallbackResult = await statWithFallbacks(resolvedPath);
+            if (!fallbackResult) {
+                const suggestions = suggestSimilarPaths(resolvedPath, workspacePath);
+                const hint = suggestions.length > 0
+                    ? ` Did you mean: ${suggestions.join(", ")}?`
+                    : " Use find or grep to locate the correct path.";
+                throw new Error(`[file_not_found] File not found: ${filePath}.${hint}`);
+            }
+            const { stat, resolvedPath: actualPath } = fallbackResult;
+            // V5: File size limit (1 GiB)
+            if (stat.size > MAX_FILE_SIZE) {
+                throw new Error(`[file_too_large] File too large (${formatSize(stat.size)}). Maximum: 1 GiB`);
+            }
+            // V6: PDF text extraction (inline, replacing old rejection)
+            if (extname(actualPath).toLowerCase() === ".pdf") {
+                const pagesParam = readStringParam(params, "pages", false);
+                const pdfResult = await extractPdfText(actualPath, {
+                    pages: pagesParam ?? undefined,
+                    maxChars: 200_000,
+                });
+                if (!pdfResult.ok) {
+                    if (pdfResult.error.kind === "encrypted") {
+                        throw new Error("[pdf_encrypted] PDF is password-protected. Cannot extract text.");
+                    }
+                    throw new Error(`[pdf_error] ${pdfResult.error.message}`);
+                }
+                const { text, pageCount, totalPages, extractedChars } = pdfResult.value;
+                const lines = text.split("\n");
+                const numbered = lines.map((line, i) => `${i + 1}\t${line}`).join("\n");
+                const header = pageCount < totalPages
+                    ? `[PDF: pages 1-${pageCount} of ${totalPages} (${formatSize(stat.size)}). Use pages param for specific range.]`
+                    : `[PDF: ${totalPages} page(s) (${formatSize(stat.size)})]`;
+                const pdfRawBuf = await fs.readFile(actualPath);
+                tracker?.recordRead(actualPath, stat.mtimeMs, undefined, undefined, pdfRawBuf);
+                return {
+                    content: [{ type: "text", text: `${header}\n${numbered}` }],
+                    details: {
+                        pdf: true,
+                        pageCount,
+                        totalPages,
+                        extractedChars,
+                        sizeBytes: stat.size,
+                        filePath: actualPath, // For microcompaction guard recovery detection
+                    },
+                };
+            }
+            // V7: Dedup check
+            if (tracker) {
+                const stub = tracker.shouldReturnStub(actualPath, stat.mtimeMs, stat.size, offset, limit);
+                if (stub) {
+                    return {
+                        content: [{ type: "text", text: stub }],
+                        details: { stub: true },
+                    };
+                }
+            }
+            // V8: Notebook rendering
+            if (extname(actualPath).toLowerCase() === ".ipynb") {
+                const raw = await fs.readFile(actualPath, "utf-8");
+                const parseResult = parseNotebook(raw);
+                if (!parseResult.ok) {
+                    throw new Error(`[read_error] Failed to parse notebook: ${parseResult.error.message}`);
+                }
+                // Pass the original filePath (not actualPath) for jq hints
+                const rendered = renderNotebookCells(parseResult.value, {
+                    filePath,
+                });
+                // Record read state (no offset/limit for notebooks, pass content for hash)
+                tracker?.recordRead(actualPath, stat.mtimeMs, undefined, undefined, Buffer.from(raw, "utf-8"));
+                logger?.debug({ path: filePath, cells: parseResult.value.cells.length }, "Notebook read complete");
+                return {
+                    content: [{ type: "text", text: rendered }],
+                    details: {
+                        notebook: true,
+                        cells: parseResult.value.cells.length,
+                        sizeBytes: stat.size,
+                        filePath: actualPath, // For microcompaction guard recovery detection
+                    },
+                };
+            }
+            // Normal file read via I/O bridge
+            const fileData = await readFileWithMetadata(actualPath);
+            // Line-number formatting + pagination
+            const lines = fileData.content.split("\n");
+            const totalLines = lines.length;
+            const sliced = lines.slice(offset, offset + limit);
+            const numbered = sliced
+                .map((line, i) => `${offset + i + 1}\t${line}`)
+                .join("\n");
+            // Build output with optional pagination header/footer
+            let output = "";
+            if (offset > 0 || offset + limit < totalLines) {
+                const endLine = Math.min(offset + limit, totalLines);
+                output += `[Reading lines ${offset + 1}-${endLine} of ${totalLines} (file: ${formatSize(stat.size)})]\n`;
+                output += numbered;
+                if (offset + limit < totalLines) {
+                    output += "\n[Use offset/limit to read more]";
+                }
+            }
+            else {
+                output = numbered;
+            }
+            // Record read state (pass content for full reads to enable content-hash staleness fallback)
+            const isFullRead = params.offset === undefined && params.limit === undefined;
+            const contentBuf = isFullRead ? Buffer.from(fileData.content, "utf-8") : undefined;
+            tracker?.recordRead(actualPath, stat.mtimeMs, offset, limit, contentBuf);
+            logger?.debug({
+                path: filePath,
+                lines: totalLines,
+                encoding: fileData.encoding,
+                lineEnding: fileData.lineEnding,
+                sizeBytes: fileData.sizeBytes,
+            }, "File read complete");
+            const readDetails = {
+                totalLines,
+                startLine: offset + 1,
+                endLine: Math.min(offset + limit, totalLines),
+                sizeBytes: stat.size,
+                encoding: fileData.encoding,
+                paginated: offset > 0 || offset + limit < totalLines,
+                filePath: actualPath, // For microcompaction guard recovery detection
+            };
+            return {
+                content: [{ type: "text", text: output }],
+                details: readDetails,
+            };
+        },
+    };
+}