feat(read-file): page large read_file responses through to the end

Large-file pages used to dead-end: the scan ceiling fired while unread
content remained, overlong lines were grep-only, and the 10k re-cut
mangled footer-bearing pages. Resume now seeks to the stored point,
pages carry both offset and cursor continuations, and footer-bearing
pages pass the truncation layer untouched.

Author: TheGreatAxios

src/agent/posix-tool-plugins.test.ts

@@ -119,11 +119,13 @@ describe("buildCorePosixToolPlugins", () => {
         new AbortController().signal,
       );
       expect(allowed.isError).not.toBe(true);
-      // The read-file guard caps the read before result-truncation would run,
-      // so a 90KB single line comes back line-truncated and bounded.
-      expect(String(allowed.content)).toContain("line truncated at 2000 chars");
-      expect(Buffer.byteLength(String(allowed.content), "utf8")).toBeLessThan(
-        4096,
+      // The read-file guard windows the overlong line into a bounded page, so
+      // a 90KB single line comes back pageable: the tail stays reachable by
+      // path+offset continuation, not only by grep.
+      expect(String(allowed.content)).not.toContain("line truncated");
+      expect(String(allowed.content)).toContain("to continue");
+      expect(Buffer.byteLength(String(allowed.content), "utf8")).toBeLessThanOrEqual(
+        50 * 1024,
       );
     } finally {
       await rm(cwd, { recursive: true, force: true });

src/plugins/read-file-guard-plugin.ts

@@ -21,14 +21,19 @@ import { formatReadFileTimeoutMessage } from "./tool-time-budget.js";
 export const READ_FILE_MAX_BYTES = 50 * 1024;
 export const READ_FILE_DEFAULT_MAX_LINES = 2000;
 export const READ_FILE_MAX_LINE_LENGTH = 2000;
-// Absolute ceiling on bytes scanned from disk, so a deep offset into a huge file
-// stays time-bounded even though memory is already bounded by the streaming read.
+// Absolute ceiling on bytes scanned from disk past the requested offset, so an
+// emission window stays time-bounded even though memory is already bounded by
+// the streaming read. Bytes skipped to reach a nonzero offset do not count:
+// continuation past the ceiling must read through to the end, not dead-end
+// with a scan limit while unread content remains.
 export const READ_FILE_MAX_SCAN_BYTES = 8 * 1024 * 1024;
 /** Refuse tool-output blobs larger than this before bounded paging. */
 export const READ_FILE_MAX_TOOL_OUTPUT_BYTES = READ_FILE_MAX_SCAN_BYTES;
 // Headroom reserved out of the byte budget for the continuation notice, so the
-// returned payload including the notice stays under READ_FILE_MAX_BYTES.
-const NOTICE_RESERVE_BYTES = 256;
+// returned payload including the notice stays under READ_FILE_MAX_BYTES. Sized
+// for a dual footer: the plain `Use offset=` continuation plus the appended
+// single-use cursor alias on byte/scan-limit pages.
+const NOTICE_RESERVE_BYTES = 384;
 
 const LINE_TRUNC_SUFFIX = ` ... [line truncated at ${READ_FILE_MAX_LINE_LENGTH} chars; full line remains in the file — use grep to match within the line]`;
 const TOOL_OUTPUT_CHUNK_BYTES = 64 * 1024;
@@ -81,6 +86,13 @@ function mapFilesystemStreamError(
  * When `wrapLongLines` is set, overlong lines are split into successive numbered
  * windows instead of being truncated and dropped — so a giant JSON line can be
  * paged through with the same offset protocol as a multi-line file.
+ * When `windowHugeLines` is set instead, only single lines that on their own
+ * exceed the output budget are windowed; ordinary lines keep their numbers, so
+ * plain path+offset pagination stays line-aligned.
+ * The scan ceiling counts only bytes past the requested offset: bytes skipped
+ * to reach a nonzero offset never trip it, so continuation on a large file
+ * reads through to the end instead of dead-ending with a scan limit while
+ * unread content remains.
  */
 function readStreamBounded(
   stream: Readable,
@@ -91,10 +103,12 @@ function readStreamBounded(
   options: {
     mapStreamError?: (err: NodeJS.ErrnoException) => Error;
     wrapLongLines?: boolean;
+    windowHugeLines?: boolean;
   } = {},
 ): Promise<BoundedRead> {
   return new Promise<BoundedRead>((resolveP, rejectP) => {
-    const { mapStreamError, wrapLongLines = false } = options;
+    const { mapStreamError, wrapLongLines = false, windowHugeLines = false } =
+      options;
     const decoder = new StringDecoder("utf8");
     const contentBudget = READ_FILE_MAX_BYTES - NOTICE_RESERVE_BYTES;
 
@@ -103,12 +117,17 @@ function readStreamBounded(
     let firstChunk = true;
     let lineNo = 0;
     let scanned = 0;
+    let skipDone = offset <= 0;
     let outBytes = 0;
     let emitted = 0;
     let lastEmittedLine = 0;
     let truncReason: TruncReason | undefined;
     let endReached = false;
     let settled = false;
+    // Set when the scan ceiling trips: the trailing partial is reported
+    // truncated (never windowed), so a line longer than one scan pass keeps
+    // the scan-limit notice instead of a byte-limit page.
+    let scanCapped = false;
 
     const out: string[] = [];
 
@@ -136,6 +155,7 @@ function readStreamBounded(
     const handleLine = (raw: string, overflow: boolean): boolean => {
       lineNo++;
       if (lineNo <= offset) return true;
+      skipDone = true;
       if (emitted >= limit) {
         truncReason = "lines";
         return false;
@@ -174,7 +194,13 @@ function readStreamBounded(
         const nl = pending.indexOf("\n");
         if (nl === -1) {
           if (wrapLongLines) return emitWrapped(pending, false);
-          if (pending.length > READ_FILE_MAX_LINE_LENGTH) {
+          if (pending.length > READ_FILE_MAX_LINE_LENGTH && !windowHugeLines) {
+            pending = pending.slice(0, READ_FILE_MAX_LINE_LENGTH);
+            pendingOverflow = true;
+          } else if (
+            windowHugeLines &&
+            pending.length > READ_FILE_MAX_SCAN_BYTES
+          ) {
             pending = pending.slice(0, READ_FILE_MAX_LINE_LENGTH);
             pendingOverflow = true;
           }
@@ -187,7 +213,9 @@ function readStreamBounded(
         } else {
           const overflow = pendingOverflow;
           pendingOverflow = false;
-          if (!handleLine(line, overflow)) return false;
+          if (!overflow && windowHugeLines && line.length > contentBudget) {
+            if (!emitWrapped(line, true)) return false;
+          } else if (!handleLine(line, overflow)) return false;
         }
       }
     };
@@ -198,6 +226,10 @@ function readStreamBounded(
         emitWrapped(pending, true);
         return;
       }
+      if (!pendingOverflow && !scanCapped && windowHugeLines && pending.length > contentBudget) {
+        emitWrapped(pending, true);
+        return;
+      }
       handleLine(pending, pendingOverflow);
     };
 
@@ -207,6 +239,9 @@ function readStreamBounded(
           done({ content: "" });
           return;
         }
+        // Skip bytes are not scanned, so a dead offset on a file larger than
+        // the ceiling still reaches EOF. Report the true range, not a scan
+        // limit that would hide a reachable end of file.
         if (endReached) {
           done({
             content: `[offset ${offset} is beyond end of file ${displayPath} (${lineNo} lines); valid offsets 0-${lineNo - 1}]`,
@@ -242,13 +277,14 @@ function readStreamBounded(
           return;
         }
       }
-      scanned += chunk.length;
+      if (skipDone) scanned += chunk.length;
       pending += decoder.write(chunk);
       if (!drainPending()) {
         finishOk();
         return;
       }
       if (scanned >= READ_FILE_MAX_SCAN_BYTES) {
+        scanCapped = true;
         flushRemainder();
         if (truncReason === undefined) truncReason = "scan";
         finishOk();
@@ -292,6 +328,7 @@ export function readFileBounded(
     signal,
     {
       mapStreamError: (err) => mapFilesystemStreamError(absolutePath, err),
+      windowHugeLines: true,
     },
   );
 }

src/plugins/result-truncation-plugin.ts

@@ -293,10 +293,29 @@ export async function applyToolResultTruncation(
   return result;
 }
 
+// A read_file page already carries its own continuation contract (a plain
+// `Use offset=` footer, a single-use cursor alias, or both). Re-cutting it at
+// the 10k leisure cap would slice the footer off the page boundary and strand
+// the pagination chain, so footer-bearing read_file pages pass through intact.
+// Pages without a footer take the normal path.
+const READ_FILE_CONTINUATION_RE = /Use offset=\d+ to continue\.|Use path="tool-output:\/\/\//;
+
+function isPagedReadFilePage(
+  toolName: string | undefined,
+  result: ToolResult,
+): boolean {
+  return (
+    toolName === "read_file" &&
+    typeof result.content === "string" &&
+    READ_FILE_CONTINUATION_RE.test(result.content)
+  );
+}
+
 async function archiveThenTruncate(
   result: ToolResult,
   callId: string,
   options: ResultTruncationPluginOptions,
+  toolName?: string,
 ): Promise<ToolResult> {
   const archive = options.getEvidenceArchive?.();
   try {
@@ -320,6 +339,7 @@ async function archiveThenTruncate(
   }
 
   const before = result.content;
+  if (isPagedReadFilePage(toolName, result)) return result;
   const truncated = await applyToolResultTruncation(
     result,
     spillOptionsForCall(callId, options),
@@ -368,7 +388,12 @@ export function wrapAgentToolResultTruncation(
     return {
       ...tool,
       handler: async (call: ToolCall, signal: AbortSignal) =>
-        archiveThenTruncate(await inner(call, signal), call.id, options),
+        archiveThenTruncate(
+          await inner(call, signal),
+          call.id,
+          options,
+          tool.definition.name,
+        ),
     };
   }
   const inner = tool.handler;
@@ -380,6 +405,7 @@ export function wrapAgentToolResultTruncation(
         { callId: call.id, content: await inner(call.arguments, signal) },
         call.id,
         options,
+        tool.definition.name,
       ),
   };
 }
@@ -397,7 +423,7 @@ export function resultTruncationPlugin(
   return {
     middleware: (next) => async (call, signal) => {
       const result = await next(call, signal);
-      return archiveThenTruncate(result, call.id, options);
+      return archiveThenTruncate(result, call.id, options, call.name);
     },
   };
 }

vendor/intx-tools-posix/src/registry.ts

@@ -42,7 +42,7 @@ export const TOOL_DEFINITIONS: ToolDefinition[] = [
   {
     name: TOOL_NAMES.READ_FILE,
     description:
-      "Read a file and return its content with line numbers. The path argument accepts either a filesystem path or a tool-output URI of the form tool-output:///{callId} that references a prior tool result.",
+      "Read a file and return its content with line numbers. The path argument accepts either a filesystem path or a tool-output URI of the form tool-output:///{callId} that references a prior tool result. Large files are returned one page at a time: pass offset and limit to page through the file, then follow the `Use offset=N to continue.` footer to read the next page through to the end.",
     inputSchema: {
       type: "object",
       properties: {