feat: add pagination support to read_file tool (EXT-617)

- Add offset, limit, format, and maxCharsPerLine params to FileEntry type
- Create pagination helper functions with cat_n formatting
- Implement bounded reads with stable line numbering
- Add pagination metadata to tool output (nextOffset, reachedEof, truncated)
- Update tool schema to support new pagination parameters
- Maintain backward compatibility with existing behavior
- Add comprehensive tests for pagination functionality

Implements spec requirements:
- Default limit of 2000 lines per request
- 0-based offset for pagination
- cat_n format with right-aligned line numbers
- Line truncation with configurable maxCharsPerLine (default 2000)
- Clear truncation signals and continuation hints
- Pagination message includes next offset for continuation

Author: roomote

packages/types/src/tool-params.ts

@@ -10,6 +10,14 @@ export interface LineRange {
 export interface FileEntry {
 	path: string
 	lineRanges?: LineRange[]
+	/** 0-based line offset for pagination (default: 0) */
+	offset?: number
+	/** Maximum number of lines to return (default: 2000) */
+	limit?: number
+	/** Output format (default: "cat_n") */
+	format?: "cat_n"
+	/** Maximum characters per line before truncation (default: 2000) */
+	maxCharsPerLine?: number
 }
 
 export interface Coordinate {

src/core/prompts/tools/native-tools/read_file.ts

@@ -45,26 +45,36 @@ export function createReadFileTool(options: ReadFileToolOptions = {}): OpenAI.Ch
 		descriptionIntro +
 		"Structure: { files: [{ path: 'relative/path.ts'" +
 		(partialReadsEnabled ? ", line_ranges: [[1, 50], [100, 150]]" : "") +
-		" }] }. " +
+		", offset: 0, limit: 2000 }] }. " +
 		"The 'path' is required and relative to workspace. "
 
 	const optionalRangesDescription = partialReadsEnabled
 		? "The 'line_ranges' is optional for reading specific sections. Each range is a [start, end] tuple (1-based inclusive). "
 		: ""
 
+	const paginationDescription =
+		"Pagination: Use 'offset' (0-based line offset, default: 0) and 'limit' (max lines to return, default: 2000) for bounded reads. When truncated, the response includes the next offset value for continuation. "
+
 	const examples = partialReadsEnabled
 		? "Example single file: { files: [{ path: 'src/app.ts' }] }. " +
+			"Example with pagination: { files: [{ path: 'src/app.ts', offset: 0, limit: 100 }] }. " +
 			"Example with line ranges: { files: [{ path: 'src/app.ts', line_ranges: [[1, 50], [100, 150]] }] }. " +
 			(isMultipleReadsEnabled
 				? `Example multiple files (within ${maxConcurrentFileReads}-file limit): { files: [{ path: 'file1.ts', line_ranges: [[1, 50]] }, { path: 'file2.ts' }] }`
 				: "")
 		: "Example single file: { files: [{ path: 'src/app.ts' }] }. " +
+			"Example with pagination: { files: [{ path: 'src/app.ts', offset: 0, limit: 100 }] }. " +
 			(isMultipleReadsEnabled
 				? `Example multiple files (within ${maxConcurrentFileReads}-file limit): { files: [{ path: 'file1.ts' }, { path: 'file2.ts' }] }`
 				: "")
 
 	const description =
-		baseDescription + optionalRangesDescription + getReadFileSupportsNote(supportsImages) + " " + examples
+		baseDescription +
+		optionalRangesDescription +
+		paginationDescription +
+		getReadFileSupportsNote(supportsImages) +
+		" " +
+		examples
 
 	// Build the properties object conditionally
 	const fileProperties: Record<string, any> = {
@@ -89,9 +99,35 @@ export function createReadFileTool(options: ReadFileToolOptions = {}): OpenAI.Ch
 		}
 	}
 
+	// Add pagination parameters
+	fileProperties.offset = {
+		type: ["integer", "null"],
+		description: "0-based line offset for pagination (default: 0). Use with limit for bounded reads.",
+	}
+
+	fileProperties.limit = {
+		type: ["integer", "null"],
+		description:
+			"Maximum number of lines to return (default: 2000). Response includes next offset for continuation.",
+	}
+
+	fileProperties.format = {
+		type: ["string", "null"],
+		description: "Output format (default: 'cat_n'). Currently only 'cat_n' (line-numbered) is supported.",
+		enum: ["cat_n", null],
+	}
+
+	fileProperties.maxCharsPerLine = {
+		type: ["integer", "null"],
+		description:
+			"Maximum characters per line before truncation (default: 2000). Truncated lines show '… [line truncated]' marker.",
+	}
+
 	// When using strict mode, ALL properties must be in the required array
 	// Optional properties are handled by having type: ["...", "null"]
-	const fileRequiredProperties = partialReadsEnabled ? ["path", "line_ranges"] : ["path"]
+	const fileRequiredProperties = partialReadsEnabled
+		? ["path", "line_ranges", "offset", "limit", "format", "maxCharsPerLine"]
+		: ["path", "offset", "limit", "format", "maxCharsPerLine"]
 
 	return {
 		type: "function",

src/core/tools/ReadFileTool.ts

@@ -29,6 +29,7 @@ import {
 import { FILE_READ_BUDGET_PERCENT, readFileWithTokenBudget } from "./helpers/fileTokenBudget"
 import { truncateDefinitionsToLineLimit } from "./helpers/truncateDefinitions"
 import { BaseTool, ToolCallbacks } from "./BaseTool"
+import { paginateLines, generatePaginationMessage } from "./helpers/paginationHelpers"
 
 interface FileResult {
 	path: string
@@ -41,6 +42,10 @@ interface FileResult {
 	imageDataUrl?: string
 	feedbackText?: string
 	feedbackImages?: any[]
+	offset?: number
+	limit?: number
+	format?: "cat_n"
+	maxCharsPerLine?: number
 }
 
 export class ReadFileTool extends BaseTool<"read_file"> {
@@ -79,6 +84,10 @@ export class ReadFileTool extends BaseTool<"read_file"> {
 			path: entry.path,
 			status: "pending",
 			lineRanges: entry.lineRanges,
+			offset: entry.offset,
+			limit: entry.limit,
+			format: entry.format,
+			maxCharsPerLine: entry.maxCharsPerLine,
 		}))
 
 		const updateFileResult = (filePath: string, updates: Partial<FileResult>) => {
@@ -449,57 +458,92 @@ export class ReadFileTool extends BaseTool<"read_file"> {
 						continue
 					}
 
-					const { id: modelId, info: modelInfo } = task.api.getModel()
-					const { contextTokens } = task.getTokenUsage()
-					const contextWindow = modelInfo.contextWindow
+					// Check if pagination parameters are specified
+					const usePagination = fileResult.offset !== undefined || fileResult.limit !== undefined
 
-					const maxOutputTokens =
-						getModelMaxOutputTokens({
-							modelId,
-							model: modelInfo,
-							settings: task.apiConfiguration,
-						}) ?? ANTHROPIC_DEFAULT_MAX_TOKENS
+					if (usePagination) {
+						// Use line-based pagination
+						const fileContent = await fs.readFile(fullPath, "utf-8")
+						const allLines = fileContent.split("\n")
 
-					// Calculate available token budget (60% of remaining context)
-					const remainingTokens = contextWindow - maxOutputTokens - (contextTokens || 0)
-					const safeReadBudget = Math.floor(remainingTokens * FILE_READ_BUDGET_PERCENT)
+						const paginationResult = paginateLines(allLines, {
+							offset: fileResult.offset,
+							limit: fileResult.limit,
+							maxCharsPerLine: fileResult.maxCharsPerLine,
+						})
 
-					let toolInfo = ""
+						const paginationMessage = generatePaginationMessage(paginationResult, allLines.length)
+						let toolInfo = ""
 
-					if (safeReadBudget <= 0) {
-						// No budget available
-						const notice = "No available context budget for file reading"
-						toolInfo = `Note: ${notice}`
-					} else {
-						// Read file with incremental token counting
-						const result = await readFileWithTokenBudget(fullPath, {
-							budgetTokens: safeReadBudget,
-						})
+						if (paginationResult.linesReturned === 0) {
+							toolInfo = `Note: ${paginationMessage}`
+						} else {
+							toolInfo = `${paginationResult.content}\n\nNote: ${paginationMessage}`
+						}
 
-						const content = addLineNumbers(result.content)
+						if (paginationResult.warnings.length > 0) {
+							toolInfo += `\nWarnings: ${paginationResult.warnings.join("; ")}`
+						}
+
+						await task.fileContextTracker.trackFileContext(relPath, "read_tool" as RecordSource)
 
-						if (!result.complete) {
-							// File was truncated
-							const notice = `File truncated: showing ${result.lineCount} lines (${result.tokenCount} tokens) due to context budget. Use line_range to read specific sections.`
-							toolInfo =
-								result.lineCount > 0
-									? `Lines 1-${result.lineCount}:\n${content}\n\nNote: ${notice}`
-									: `Note: ${notice}`
+						updateFileResult(relPath, {
+							nativeContent: `File: ${relPath}\n${toolInfo}`,
+						})
+					} else {
+						// Use existing token budget-based reading
+						const { id: modelId, info: modelInfo } = task.api.getModel()
+						const { contextTokens } = task.getTokenUsage()
+						const contextWindow = modelInfo.contextWindow
+
+						const maxOutputTokens =
+							getModelMaxOutputTokens({
+								modelId,
+								model: modelInfo,
+								settings: task.apiConfiguration,
+							}) ?? ANTHROPIC_DEFAULT_MAX_TOKENS
+
+						// Calculate available token budget (60% of remaining context)
+						const remainingTokens = contextWindow - maxOutputTokens - (contextTokens || 0)
+						const safeReadBudget = Math.floor(remainingTokens * FILE_READ_BUDGET_PERCENT)
+
+						let toolInfo = ""
+
+						if (safeReadBudget <= 0) {
+							// No budget available
+							const notice = "No available context budget for file reading"
+							toolInfo = `Note: ${notice}`
 						} else {
-							// Full file read
-							if (result.lineCount === 0) {
-								toolInfo = "Note: File is empty"
+							// Read file with incremental token counting
+							const result = await readFileWithTokenBudget(fullPath, {
+								budgetTokens: safeReadBudget,
+							})
+
+							const content = addLineNumbers(result.content)
+
+							if (!result.complete) {
+								// File was truncated
+								const notice = `File truncated: showing ${result.lineCount} lines (${result.tokenCount} tokens) due to context budget. Use line_range or offset/limit parameters to read specific sections.`
+								toolInfo =
+									result.lineCount > 0
+										? `Lines 1-${result.lineCount}:\n${content}\n\nNote: ${notice}`
+										: `Note: ${notice}`
 							} else {
-								toolInfo = `Lines 1-${result.lineCount}:\n${content}`
+								// Full file read
+								if (result.lineCount === 0) {
+									toolInfo = "Note: File is empty"
+								} else {
+									toolInfo = `Lines 1-${result.lineCount}:\n${content}`
+								}
 							}
 						}
-					}
 
-					await task.fileContextTracker.trackFileContext(relPath, "read_tool" as RecordSource)
+						await task.fileContextTracker.trackFileContext(relPath, "read_tool" as RecordSource)
 
-					updateFileResult(relPath, {
-						nativeContent: `File: ${relPath}\n${toolInfo}`,
-					})
+						updateFileResult(relPath, {
+							nativeContent: `File: ${relPath}\n${toolInfo}`,
+						})
+					}
 				} catch (error) {
 					const errorMsg = error instanceof Error ? error.message : String(error)
 					updateFileResult(relPath, {