@namzu/sdk 51.1.0 → 52.0.0

package/src/tools/builtins/grep.ts

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { readFile, stat } from 'node:fs/promises'
 import { isAbsolute, join, relative, sep } from 'node:path'
 import { z } from 'zod'
 import { walkFilesLocally } from '../../sandbox/file-walk.js'
@@ -51,6 +51,12 @@ function relativeInclude(include: string, root: string, sandboxed: boolean): str
 	return pattern.includes('/') ? pattern : `**/${pattern}`
 }
 
+/** Entries returned when `head_limit` is not given. */
+export const DEFAULT_HEAD_LIMIT = 250
+
+/** A matching or context line longer than this is replaced by a notice, not printed. */
+export const MAX_LINE_COLUMNS = 500
+
 const inputSchema = z.object({
 	pattern: z.string().describe('Regular expression pattern to search for in file contents'),
 	path: z
@@ -68,12 +74,32 @@ const inputSchema = z.object({
 		.min(0)
 		.default(0)
 		.describe('Number of lines to show before and after each match'),
+	output_mode: z
+		.enum(['files_with_matches', 'content', 'count'])
+		.default('files_with_matches')
+		.describe(
+			'What to return. "files_with_matches" (default): the paths of files that match, newest first. "content": matching lines with file and line number (supports context_lines). "count": the number of matching lines per file.',
+		),
+	head_limit: z.coerce
+		.number()
+		.int()
+		.min(0)
+		.optional()
+		.describe(
+			`Return at most this many entries (file paths, output lines, or count rows depending on output_mode). Defaults to ${DEFAULT_HEAD_LIMIT}. Pass 0 for no limit; use that sparingly, a large result wastes context.`,
+		),
+	offset: z.coerce
+		.number()
+		.int()
+		.min(0)
+		.default(0)
+		.describe('Skip this many entries before applying head_limit, to page through results.'),
 	max_results: z.coerce
 		.number()
 		.int()
 		.min(1)
-		.default(100)
-		.describe('Maximum number of matching lines to return'),
+		.optional()
+		.describe('Deprecated: use head_limit. Used as head_limit when head_limit is not given.'),
 })
 
 const MAX_FILE_SIZE = 5 * 1024 * 1024 // 5 MB — skip binaries/large files
@@ -91,7 +117,7 @@ function isBinaryContent(buffer: Buffer): boolean {
 export const GrepTool = defineTool({
 	name: 'grep',
 	description:
-		'Searches file contents using a regular expression. Returns matching lines with file paths, line numbers, and optional context lines. Searches incrementally with a bounded traversal; identifies incomplete searches. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory.',
+		'Searches file contents using a regular expression. By default returns the paths of matching files, newest first; output_mode "content" returns matching lines with file paths, line numbers and optional context lines, and "count" returns the number of matching lines per file. Results are paged: head_limit (default 250, 0 for none) and offset. A line over 500 characters is replaced by a notice. Searches with a bounded traversal and identifies incomplete searches. Skips binary files, files over 5 MB, and symlinks. Choose the narrowest relevant directory.',
 	inputSchema,
 	category: 'analysis',
 	// Declared so a path outside the turn's roots can be reviewed before the
@@ -158,12 +184,21 @@ export const GrepTool = defineTool({
 		}
 		const entries = walkSandbox ? walkSandbox(root, options) : walkFilesLocally(root, options)
 
+		// `execute` is reachable without the schema's defaults.
+		const mode = input.output_mode ?? 'files_with_matches'
+		// `max_results` predates `head_limit`; it keeps meaning "at most this many".
+		const headLimit = input.head_limit ?? input.max_results ?? DEFAULT_HEAD_LIMIT
+		const offset = input.offset ?? 0
+		// Content lines in output order. Only content mode uses them as the
+		// result; the other modes build from `matchedFiles`.
 		const results: string[] = []
+		const matchedFiles: { relPath: string; host?: string; count: number }[] = []
 		let totalMatches = 0
 		let filesSearched = 0
 		let filesMatched = 0
 
 		let truncated = false
+		let pageHasMore = false
 		let failure: string | undefined
 		let unreadableFiles = 0
 		try {
@@ -181,14 +216,16 @@ export const GrepTool = defineTool({
 				if (entry.size > MAX_FILE_SIZE) continue
 
 				let content: string
+				let contained: string | undefined
 				try {
 					const buffer = await readWithSignal(
 						() =>
 							sandbox
 								? sandbox.readFile(filePath)
-								: resolveWithinReal(root, filePath).then((contained) =>
-										readFile(contained, { signal: context.abortSignal }),
-									),
+								: resolveWithinReal(root, filePath).then((path) => {
+										contained = path
+										return readFile(path, { signal: context.abortSignal })
+									}),
 						context.abortSignal,
 					)
 					context.abortSignal?.throwIfAborted()
@@ -201,7 +238,12 @@ export const GrepTool = defineTool({
 				}
 
 				const lines = content.split('\n')
-				let fileHasMatch = false
+				let fileMatches = 0
+				const relPath = sandbox
+					? `./${relativePosix(sandbox.rootDir, filePath)}`
+					: `./${relative(context.workingDirectory, join(lexicalRoot, relative(root, filePath)))
+							.split(sep)
+							.join('/')}`
 
 				for (let i = 0; i < lines.length; i++) {
 					context.abortSignal?.throwIfAborted()
@@ -209,16 +251,12 @@ export const GrepTool = defineTool({
 					regex.lastIndex = 0
 					if (!regex.test(line)) continue
 
-					if (!fileHasMatch) {
-						fileHasMatch = true
-						filesMatched++
-					}
-
-					const relPath = sandbox
-						? `./${relativePosix(sandbox.rootDir, filePath)}`
-						: `./${relative(context.workingDirectory, join(lexicalRoot, relative(root, filePath)))
-								.split(sep)
-								.join('/')}`
+					if (fileMatches === 0) filesMatched++
+					fileMatches++
+					totalMatches++
+					// A file list only needs to know that the file matches.
+					if (mode === 'files_with_matches') break
+					if (mode === 'count') continue
 
 					if (input.context_lines > 0) {
 						const start = Math.max(0, i - input.context_lines)
@@ -230,22 +268,32 @@ export const GrepTool = defineTool({
 
 						for (let j = start; j <= end; j++) {
 							const prefix = j === i ? ':' : '-'
-							results.push(`${relPath}${prefix}${j + 1}${prefix}${lines[j]}`)
+							const text = lines[j] ?? ''
+							results.push(
+								`${relPath}${prefix}${j + 1}${prefix}${clipLine(text, j === i ? 'matching' : 'context')}`,
+							)
 						}
 					} else {
-						results.push(`${relPath}:${i + 1}:${line}`)
+						results.push(`${relPath}:${i + 1}:${clipLine(line, 'matching')}`)
 					}
 
-					totalMatches++
-					if (totalMatches >= input.max_results) break
+					// A full page ends the search: another file is not read just to
+					// prove there is more, so a page that is exactly full is reported
+					// as possibly continuing.
+					if (headLimit > 0 && results.length >= offset + headLimit) {
+						pageHasMore = true
+						break
+					}
 				}
 
-				if (totalMatches >= input.max_results) {
-					// Do not read another file just to prove there are more hits. Reaching
-					// the requested cap means completeness was not established.
-					truncated = true
-					break
+				if (fileMatches > 0 && mode !== 'content') {
+					matchedFiles.push({
+						relPath,
+						...(contained !== undefined ? { host: contained } : {}),
+						count: fileMatches,
+					})
 				}
+				if (pageHasMore) break
 			}
 		} catch (error) {
 			truncated = true
@@ -255,21 +303,66 @@ export const GrepTool = defineTool({
 			truncated = true
 			failure ??= `${unreadableFiles} file(s) could not be read.`
 		}
-		const summary =
-			totalMatches > 0
-				? `Found ${totalMatches} match(es) in ${filesMatched} file(s) (${filesSearched} files searched)`
-				: truncated
-					? `No matches found in the files searched for pattern "${input.pattern}"`
-					: `No matches found for pattern "${input.pattern}"`
+		if (pageHasMore) truncated = true
+
+		// Entries as the model will page through them.
+		let entriesOut: string[]
+		if (mode === 'content') {
+			entriesOut = results
+		} else if (mode === 'count') {
+			entriesOut = matchedFiles.map((f) => `${f.relPath}:${f.count}`)
+		} else {
+			entriesOut = (await sortByNewest(matchedFiles)).map((f) => f.relPath)
+		}
+		const total = entriesOut.length
+		const page =
+			headLimit === 0 ? entriesOut.slice(offset) : entriesOut.slice(offset, offset + headLimit)
+		// Reported only when it did something, like a `| head`: a limit that cut
+		// nothing off is not news.
+		const moreRemain = headLimit > 0 && (pageHasMore || total - offset > headLimit)
+		const paging = [
+			...(moreRemain ? [`limit: ${headLimit}`] : []),
+			...(offset > 0 ? [`offset: ${offset}`] : []),
+		].join(', ')
+
+		let body: string
+		let summary: string | undefined
+		if (page.length === 0) {
+			body = ''
+			summary =
+				offset > 0 && total > 0
+					? 'No entries at this offset.'
+					: truncated
+						? `No matches found in the files searched for pattern "${input.pattern}"`
+						: `No matches found for pattern "${input.pattern}"`
+		} else if (mode === 'files_with_matches') {
+			body = `Found ${page.length} ${page.length === 1 ? 'file' : 'files'}${paging ? ` (${paging})` : ''}\n${page.join('\n')}`
+		} else if (mode === 'count') {
+			body = page.join('\n')
+			summary = `Found ${totalMatches} total ${totalMatches === 1 ? 'match' : 'matches'} across ${filesMatched} ${filesMatched === 1 ? 'file' : 'files'}${paging ? ` (${paging})` : ''}. ${filesSearched} files searched.`
+		} else {
+			body = page.join('\n')
+			summary = `Found ${totalMatches} match(es) in ${filesMatched} file(s) (${filesSearched} files searched)${offset > 0 ? ` from offset ${offset}` : ''}`
+		}
 		const notice = failure
 			? `[Search incomplete: ${failure}]`
-			: truncated
-				? `[Search incomplete: reached max_results (${input.max_results}). Narrow the directory or include pattern for a complete search.]`
-				: undefined
+			: pageHasMore
+				? `[Search incomplete: the page of ${headLimit} is full, so more may follow. Pass offset to continue, or narrow the directory or include pattern.]`
+				: truncated
+					? '[Search incomplete: the search did not reach every file. Narrow the directory or include pattern for a complete search.]'
+					: undefined
 		return {
 			success: failure === undefined,
-			output: [results.join('\n'), summary, notice].filter(Boolean).join('\n\n'),
-			data: { totalMatches, filesSearched, filesMatched, truncated },
+			output: [body, summary, notice].filter(Boolean).join('\n\n'),
+			data: {
+				totalMatches,
+				filesSearched,
+				filesMatched,
+				truncated,
+				mode,
+				...(moreRemain ? { appliedLimit: headLimit } : {}),
+				...(offset > 0 ? { appliedOffset: offset } : {}),
+			},
 			facts: {
 				kind: 'search',
 				pattern: input.pattern,
@@ -283,3 +376,31 @@ export const GrepTool = defineTool({
 		}
 	},
 })
+
+/** A line past the column cap is not printed: one minified bundle would be the whole result. */
+function clipLine(line: string, kind: 'matching' | 'context'): string {
+	return line.length > MAX_LINE_COLUMNS ? `[Omitted long ${kind} line]` : line
+}
+
+/**
+ * Newest modification first; ties by path. A file that cannot be stat'ed, and
+ * every file in a sandbox (which reports no modification time), sorts as
+ * oldest, so a sandbox listing is in path order.
+ */
+async function sortByNewest<T extends { relPath: string; host?: string }>(
+	files: readonly T[],
+): Promise<T[]> {
+	const stamped = await Promise.all(
+		files.map(async (file) => {
+			if (file.host === undefined) return { file, mtime: 0 }
+			try {
+				return { file, mtime: (await stat(file.host)).mtimeMs }
+			} catch {
+				return { file, mtime: 0 }
+			}
+		}),
+	)
+	return stamped
+		.sort((a, b) => b.mtime - a.mtime || a.file.relPath.localeCompare(b.file.relPath))
+		.map((entry) => entry.file)
+}

package/src/tools/builtins/read-file.ts

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { readFile, stat } from 'node:fs/promises'
 import { extname } from 'node:path'
 import { z } from 'zod'
 import type { ToolContext } from '../../types/tool/index.js'
@@ -7,7 +7,7 @@ import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { looksBinary } from '../text-window.js'
 import { fingerprintContent } from './content-fingerprint.js'
-import { type RenderedRead, renderNumberedRead } from './read-render.js'
+import { type RenderedRead, renderCappedRead } from './read-render.js'
 
 const inputSchema = z.object({
 	path: z.string().describe('Path to the file to read (absolute or relative)'),
@@ -34,12 +34,18 @@ const inputSchema = z.object({
 		.optional()
 		.describe('Starting line number (0-indexed). Defaults to 0 (beginning of file).'),
 	limit: z.coerce.number().optional().describe('Maximum number of lines to read'),
+	allow_large: z
+		.boolean()
+		.optional()
+		.describe(
+			'Raise the size and token caps for this one read. Set it only after a read was refused as too large and you genuinely need all of the file.',
+		),
 })
 
 export const ReadFileTool = defineTool({
 	name: 'read',
 	description:
-		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files. Without a window it returns the first 2000 lines and says so — pass offset/limit to continue.',
+		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files. Without a window it returns the first 2000 lines and says so — pass offset/limit to continue. A file over 256 KiB is refused unless a window is named, and a result over about 25,000 tokens is cut to a first page that names the next call; pass allow_large only when you need all of it.',
 	inputSchema,
 	category: 'filesystem',
 	// Declared so a path outside the turn's roots can be reviewed before the
@@ -49,6 +55,9 @@ export const ReadFileTool = defineTool({
 	readOnly: true,
 	destructive: false,
 	concurrencySafe: true,
+	// Bounded by the size and token caps in `renderCappedRead`, so the turn's
+	// default per-result cap and the per-message budget leave it alone.
+	selfLimitingOutput: true,
 
 	presentCall(input) {
 		if (typeof input.path !== 'string') return undefined
@@ -84,7 +93,9 @@ export const ReadFileTool = defineTool({
 				}
 			}
 			const content = buffer.toString('utf-8')
-			const rendered = renderNumberedRead(content, input)
+			const capped = renderCappedRead(content, buffer.length, input, capOptions(input, context))
+			if (!capped.ok) return refusedRead(input.path, buffer.length, capped.message, true)
+			const rendered = capped.rendered
 			recordObservedRead(context, input.path, content, rendered)
 
 			return {
@@ -102,6 +113,13 @@ export const ReadFileTool = defineTool({
 		}
 
 		const filePath = await resolveWithinAnyReal(toolRoots(context), input.path)
+		// Refused on the size alone, before the file is in memory, when no window
+		// was named: the cap exists so a huge file is never loaded to be refused.
+		if (input.readRange === undefined && input.limit === undefined) {
+			const { size } = await stat(filePath)
+			const early = renderCappedRead('', size, input, capOptions(input, context))
+			if (!early.ok) return refusedRead(filePath, size, early.message, false)
+		}
 		const buffer = await readFile(filePath)
 		const binaryGuidance = describeStructuredBinaryRead(filePath, buffer)
 		if (binaryGuidance) {
@@ -121,7 +139,9 @@ export const ReadFileTool = defineTool({
 			}
 		}
 		const content = buffer.toString('utf-8')
-		const rendered = renderNumberedRead(content, input)
+		const capped = renderCappedRead(content, buffer.length, input, capOptions(input, context))
+		if (!capped.ok) return refusedRead(filePath, buffer.length, capped.message, false)
+		const rendered = capped.rendered
 		recordObservedRead(context, filePath, content, rendered)
 
 		return {
@@ -138,6 +158,29 @@ export const ReadFileTool = defineTool({
 	},
 })
 
+function capOptions(
+	input: { path: string; allow_large?: boolean | undefined },
+	context: ToolContext,
+): Parameters<typeof renderCappedRead>[3] {
+	const tokens = Number(context.env?.NAMZU_FILE_READ_MAX_OUTPUT_TOKENS)
+	return {
+		path: input.path,
+		ext: extname(input.path).toLowerCase(),
+		...(input.allow_large === true ? { allowLarge: true } : {}),
+		...(Number.isFinite(tokens) && tokens > 0 ? { caps: { maxTokens: tokens } } : {}),
+	}
+}
+
+function refusedRead(path: string, bytes: number, message: string, sandboxed: boolean) {
+	return {
+		success: false as const,
+		output: '',
+		error: message,
+		data: { path, tooLarge: true, ...(sandboxed ? { sandboxed: true } : {}) },
+		facts: { kind: 'read' as const, path, bytes },
+	}
+}
+
 /**
  * What a read returned, as fields. A file that is not text is named as such,
  * so a host says "Binary file, 4 KB" instead of drawing the bytes the model's

package/src/tools/builtins/read-render.ts

@@ -102,3 +102,196 @@ export function resolveReadWindow(
 	const end = input.limit ? start + input.limit : Math.min(totalLines, start + DEFAULT_READ_LINES)
 	return { start, end }
 }
+
+/**
+ * Largest file `read` returns whole when the caller named no window.
+ * A file over it is refused with the way to read part of it.
+ */
+export const MAX_READ_BYTES = 262_144
+
+/** Largest read result, in estimated tokens. */
+export const MAX_READ_TOKENS = 25_000
+
+/**
+ * Bytes of text one token is allowed to stand for when bounding a SELECTED
+ * window by its bytes: a window may hold at most `tokens * 128` bytes before
+ * it is refused outright, without estimating anything.
+ */
+const SELECTED_BYTES_PER_TOKEN = 128
+
+/**
+ * What `allow_large` multiplies both caps by.
+ *
+ * The caps it lifts are "what still fits in the context left this turn",
+ * which this kernel does not track, so it lifts them by a fixed factor.
+ */
+export const ALLOW_LARGE_FACTOR = 4
+
+/** Share of the page a trimmed first page is aimed at, so the estimate lands under the cap. */
+const TRIM_TARGET = 0.85
+
+/** The ways a read can be refused before it returns anything. */
+export type ReadRefusal = string
+
+export interface ReadCaps {
+	readonly maxBytes: number
+	readonly maxTokens: number
+}
+
+export interface ReadCapOptions {
+	readonly path: string
+	/** File extension with the dot, lower case; JSON text is denser per token. */
+	readonly ext: string
+	readonly allowLarge?: boolean
+	/** Overrides for the defaults, from the host's environment. */
+	readonly caps?: Partial<ReadCaps>
+}
+
+/** Estimated tokens: characters over four, over two for JSON text. */
+export function estimateReadTokens(text: string, ext: string): number {
+	const perToken = ext === '.json' || ext === '.jsonl' || ext === '.jsonc' ? 2 : 4
+	return Math.round(text.length / perToken)
+}
+
+function humanBytes(n: number): string {
+	if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MiB`
+	if (n >= 1024) return `${Math.round(n / 1024)} KiB`
+	return `${n} B`
+}
+
+function allowLargeHint(allowedAlready: boolean): string {
+	return allowedAlready
+		? ' Even with allow_large this is more than a read may return.'
+		: ' To read it anyway, call read again with allow_large: true, but only if you need all of it or were asked for the whole file.'
+}
+
+/**
+ * Render a read, or refuse it, under the size and token caps.
+ *
+ * Three rules, in the order they are checked:
+ *
+ * 1. No window named and the file over {@link MAX_READ_BYTES}: refuse. A caller
+ *    that asked for a window (`readRange`, `limit`) has chosen its size.
+ * 2. A selected window over `maxTokens * 128` bytes: refuse.
+ * 3. The selected text over `maxTokens` by estimate: for the first page of an
+ *    unwindowed read, return the lines that fit with a notice naming the next
+ *    call; for any other read, refuse and report the count.
+ *
+ * Pure, like {@link renderNumberedRead}; a read that none of this touches
+ * renders byte for byte as `renderNumberedRead` does.
+ */
+export function renderCappedRead(
+	content: string,
+	byteLength: number,
+	input: ReadWindowRequest,
+	options: ReadCapOptions,
+): { ok: true; rendered: RenderedRead } | { ok: false; message: ReadRefusal } {
+	const factor = options.allowLarge ? ALLOW_LARGE_FACTOR : 1
+	const maxBytes = (options.caps?.maxBytes ?? MAX_READ_BYTES) * factor
+	const maxTokens = (options.caps?.maxTokens ?? MAX_READ_TOKENS) * factor
+	const hint = allowLargeHint(options.allowLarge === true)
+
+	const windowed = input.readRange !== undefined || input.limit !== undefined
+	if (!windowed && byteLength > maxBytes) {
+		return {
+			ok: false,
+			message: `File content (${humanBytes(byteLength)}) exceeds the maximum allowed size (${humanBytes(maxBytes)}). Use offset and limit to read part of it, or search for what you need instead of reading all of it.${hint}`,
+		}
+	}
+
+	const lines = content.split('\n')
+	const { start, end } = resolveReadWindow(input, lines.length)
+	const selected = lines.slice(start, end)
+	const selectedText = selected.join('\n')
+
+	const selectedBytes = Buffer.byteLength(selectedText, 'utf8')
+	if (selectedBytes > maxTokens * SELECTED_BYTES_PER_TOKEN) {
+		return {
+			ok: false,
+			message: `The requested lines hold over ${humanBytes(maxTokens * SELECTED_BYTES_PER_TOKEN)} of text, more than a read can return. Use a smaller limit; if a single line is this large, no limit will fit it, so search for what you need instead.${hint}`,
+		}
+	}
+
+	const tokens = estimateReadTokens(selectedText, options.ext)
+	if (tokens <= maxTokens) {
+		return { ok: true, rendered: renderNumberedRead(content, input) }
+	}
+
+	const firstPage = input.readRange === undefined && input.limit === undefined && start === 0
+	if (!firstPage) {
+		return {
+			ok: false,
+			message: `File content (${tokens} tokens) exceeds the maximum allowed tokens (${maxTokens}). Use offset and limit to read part of it, or search for what you need instead of reading all of it.${hint}`,
+		}
+	}
+	return {
+		ok: true,
+		rendered: trimFirstPage(selected, lines.length, selectedText, tokens, maxTokens, options.path),
+	}
+}
+
+/**
+ * The first page of a file whose first window is over the token cap: the
+ * leading lines that fit, numbered, and a notice that says it is a page and
+ * names the next call.
+ *
+ * Sized from the measured ratio of characters to tokens, aimed at
+ * {@link TRIM_TARGET} of the cap, and shrunk by 30% up to six times if the
+ * estimate still lands over. A page whose first lines are themselves too long
+ * falls back to a character excerpt, which cannot be paged by line.
+ */
+function trimFirstPage(
+	selected: readonly string[],
+	totalLines: number,
+	selectedText: string,
+	tokens: number,
+	maxTokens: number,
+	path: string,
+): RenderedRead {
+	const charsPerToken = Math.max(0.5, selectedText.length / Math.max(1, tokens))
+	const fits = (text: string) => text.length / charsPerToken <= maxTokens
+
+	let keep = Math.max(
+		1,
+		Math.min(
+			selected.length,
+			Math.floor(((selected.length * maxTokens) / Math.max(1, tokens)) * TRIM_TARGET),
+		),
+	)
+	let page = selected.slice(0, keep).join('\n')
+	for (let i = 0; i < 6; i++) {
+		if (fits(page) || keep <= 1) break
+		keep = Math.max(1, Math.floor(keep * 0.7))
+		page = selected.slice(0, keep).join('\n')
+	}
+
+	const tail = 'Do NOT answer from this page alone if the answer may be further in the file.]'
+	if (!fits(page) || page.trim() === '') {
+		let chars = Math.max(1, Math.floor(maxTokens * charsPerToken * TRIM_TARGET))
+		let excerpt = selectedText.slice(0, chars)
+		for (let i = 0; i < 6 && !fits(excerpt); i++) {
+			chars = Math.max(1, Math.floor(chars * 0.7))
+			excerpt = selectedText.slice(0, chars)
+		}
+		const last = excerpt.charCodeAt(excerpt.length - 1)
+		if (last >= 0xd800 && last <= 0xdbff) excerpt = excerpt.slice(0, -1)
+		const shown = excerpt.split('\n').length
+		return {
+			output: `${numbered(excerpt.split('\n'))}\n\n[Truncated: PARTIAL view — ${path}: showing the first ${excerpt.length} of ${selectedText.length} characters (${tokens} tokens, cap ${maxTokens}); this file has very long lines and cannot be paged by line. Use grep to find a specific section, or read with offset and limit. ${tail}`,
+			totalLines,
+			returnedLines: shown,
+			partial: true,
+		}
+	}
+
+	return {
+		output: `${numbered(selected.slice(0, keep))}\n\n[Truncated: PARTIAL view — ${path}: showing lines 1-${keep} of ${totalLines} total (${tokens} tokens, cap ${maxTokens}). Call read with offset=${keep} limit=${keep} for the next page, or grep to find a specific section. ${tail}`,
+		totalLines,
+		returnedLines: keep,
+		partial: true,
+	}
+}
+
+function numbered(lines: readonly string[]): string {
+	return lines.map((line, i) => `${i + 1}\t${line}`).join('\n')
+}