feat: File based long tool return (#488)

src/tools/impl/Read.ts

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import * as path from "node:path";
+import { OVERFLOW_CONFIG, writeOverflowFile } from "./overflow.js";
 import { LIMITS } from "./truncation.js";
 import { validateRequiredParams } from "./validation.js";
 
@@ -52,6 +53,7 @@ function formatWithLineNumbers(
   content: string,
   offset?: number,
   limit?: number,
+  workingDirectory?: string,
 ): string {
   const lines = content.split("\n");
   const originalLineCount = lines.length;
@@ -88,6 +90,21 @@ function formatWithLineNumbers(
   const notices: string[] = [];
   const wasTruncatedByLineCount = actualEndLine < originalLineCount;
 
+  // Write to overflow file if content was truncated and overflow is enabled
+  let overflowPath: string | undefined;
+  if (
+    (wasTruncatedByLineCount || linesWereTruncatedInLength) &&
+    OVERFLOW_CONFIG.ENABLED &&
+    workingDirectory
+  ) {
+    try {
+      overflowPath = writeOverflowFile(content, workingDirectory, "Read");
+    } catch (error) {
+      // Silently fail if overflow file creation fails
+      console.error("Failed to write overflow file:", error);
+    }
+  }
+
   if (wasTruncatedByLineCount && !limit) {
     // Only show this notice if user didn't explicitly set a limit
     notices.push(
@@ -101,6 +118,10 @@ function formatWithLineNumbers(
     );
   }
 
+  if (overflowPath) {
+    notices.push(`\n\n[Full file content written to: ${overflowPath}]`);
+  }
+
   if (notices.length > 0) {
     result += notices.join("");
   }
@@ -132,7 +153,12 @@ export async function read(args: ReadArgs): Promise<ReadResult> {
         content: `<system-reminder>\nThe file ${resolvedPath} exists but has empty contents.\n</system-reminder>`,
       };
     }
-    const formattedContent = formatWithLineNumbers(content, offset, limit);
+    const formattedContent = formatWithLineNumbers(
+      content,
+      offset,
+      limit,
+      userCwd,
+    );
     return { content: formattedContent };
   } catch (error) {
     const err = error as NodeJS.ErrnoException;