@khanhicetea/pi-better-tool 0.2.2 → 0.2.4

package/src/read-code-imports.ts

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { basename, extname } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { boundCompleteOutput, fenceFor } from "./diagnostics.ts";
+import { resolveToolPath } from "./paths.ts";
+import { readSource, sourceReadError } from "./source-file.ts";
+
+export const readCodeImportsSchema = Type.Object({
+	path: Type.String({ minLength: 1, maxLength: 4096, description: "Local source file path (relative, absolute, @path, ~/path, or file URL)." }),
+});
+export type ReadCodeImportsInput = Static<typeof readCodeImportsSchema>;
+
+type ImportLanguage = "javascript" | "python" | "go" | "rust" | "c" | "csharp" | "java" | "kotlin" | "php" | "ruby" | "swift" | "shell";
+interface LineRange { start: number; end: number }
+export interface ReadCodeImportsResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: {
+		language: ImportLanguage;
+		snapshot: string;
+		found: boolean;
+		visible?: { startLine: number; endLine: number };
+	};
+}
+
+const MAX_OUTPUT_BYTES = 48 * 1024;
+const MAX_OUTPUT_LINES = 1950;
+const EXTENSIONS: Record<string, ImportLanguage> = {
+	".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript",
+	".ts": "javascript", ".tsx": "javascript", ".mts": "javascript", ".cts": "javascript",
+	".py": "python", ".pyi": "python", ".go": "go", ".rs": "rust",
+	".c": "c", ".h": "c", ".cc": "c", ".cpp": "c", ".cxx": "c", ".hpp": "c", ".m": "c", ".mm": "c",
+	".cs": "csharp", ".java": "java", ".kt": "kotlin", ".kts": "kotlin", ".php": "php",
+	".rb": "ruby", ".swift": "swift", ".sh": "shell", ".bash": "shell", ".zsh": "shell", ".fish": "shell",
+};
+
+function importLanguage(path: string): ImportLanguage | undefined {
+	const name = basename(path).toLowerCase();
+	if (name === "gemfile" || name === "rakefile") return "ruby";
+	return EXTENSIONS[extname(name)];
+}
+
+function isImportStart(line: string, language: ImportLanguage): boolean {
+	switch (language) {
+		case "javascript": return /^(?:import(?:\s|["'])|export\s+(?:type\s+)?(?:\*|\{)[\s\S]*\bfrom\b)/.test(line);
+		case "python": return /^(?:from\s+[\w.]+\s+import\b|import\s+[\w.])/.test(line);
+		case "go": return /^import(?:\s|\()/.test(line);
+		case "rust": return /^(?:(?:pub(?:\([^)]*\))?\s+)?use\b|extern\s+crate\b)/.test(line);
+		case "c": return /^\s*#\s*(?:include|import)\b/.test(line);
+		case "csharp": return /^(?:(?:global\s+)?using\b|extern\s+alias\b)/.test(line);
+		case "java": case "kotlin": return /^import\b/.test(line);
+		case "php": return /^(?:use\b|(?:require|include)(?:_once)?\b)/.test(line);
+		case "ruby": return /^(?:require|require_relative|load)\b/.test(line);
+		case "swift": return /^(?:@\w+(?:\([^)]*\))?\s+)?import\b/.test(line);
+		case "shell": return /^(?:source\b|\.\s+\S)/.test(line);
+	}
+}
+
+function statementEnd(lines: string[], start: number, language: ImportLanguage): number {
+	if (language === "go" && /^import\s*\(/.test(lines[start])) {
+		for (let index = start; index < lines.length; index++) if (/^\s*\)/.test(lines[index])) return index;
+		return start;
+	}
+	if (language === "python") {
+		let depth = 0;
+		for (let index = start; index < lines.length; index++) {
+			const code = lines[index].replace(/#.*$/, "");
+			depth += (code.match(/[([{]/g) ?? []).length - (code.match(/[)\]}]/g) ?? []).length;
+			if (depth <= 0 && !/\\\s*$/.test(code)) return index;
+		}
+		return start;
+	}
+	if (language === "javascript") {
+		for (let index = start; index < lines.length; index++) {
+			const code = lines[index].replace(/\/\/.*$/, "").trimEnd();
+			if (/;\s*$/.test(code) || /(?:from\s+)?["'][^"']+["']\s*(?:(?:with|assert)\s*\{.*\})?\s*$/.test(code)) return index;
+		}
+		return start;
+	}
+	if (language === "rust" || language === "csharp" || language === "java" || language === "kotlin" || language === "php") {
+		for (let index = start; index < lines.length; index++) if (/;\s*(?:\/\/.*)?$/.test(lines[index])) return index;
+		return start;
+	}
+	if (language === "c") {
+		let index = start;
+		while (index + 1 < lines.length && /\\\s*$/.test(lines[index])) index++;
+		return index;
+	}
+	return start;
+}
+
+function isTrivia(line: string): boolean {
+	return /^\s*(?:$|\/\/|\/\*|\*|#(?!\s*(?:include|import)\b)|<!--|-->|\{\/\*)/.test(line);
+}
+
+function findImportZone(lines: string[], language: ImportLanguage): LineRange | undefined {
+	const statements: LineRange[] = [];
+	for (let index = 0; index < lines.length; index++) {
+		if (!isImportStart(lines[index], language)) continue;
+		const end = statementEnd(lines, index, language);
+		statements.push({ start: index, end });
+		index = end;
+	}
+	if (!statements.length) return undefined;
+	const zone = { ...statements[0] };
+	for (const statement of statements.slice(1)) {
+		if (!lines.slice(zone.end + 1, statement.start).every(isTrivia)) break;
+		zone.end = statement.end;
+	}
+	return zone;
+}
+
+export function validateReadCodeImportsInput(input: ReadCodeImportsInput): void {
+	if (!input || typeof input.path !== "string" || !input.path.length || input.path.length > 4096) throw new Error("read_code_imports requires a non-empty path of at most 4096 characters.");
+}
+
+export function buildCodeImportsRead(input: ReadCodeImportsInput, content: string): ReadCodeImportsResult {
+	validateReadCodeImportsInput(input);
+	const language = importLanguage(resolveToolPath(input.path, "/"));
+	if (!language) throw new Error("Unsupported source type. read_code_imports supports JavaScript/TypeScript, Python, Go, Rust, C/C++, C#, Java, Kotlin, PHP, Ruby, Swift, and shell source files. Use read for this file.");
+	const lines = content.split("\n");
+	const zone = findImportZone(lines, language);
+	const snapshot = createHash("sha256").update(content).digest("hex");
+	const header = `Source ${JSON.stringify(input.path)} (${lines.length} lines). Snapshot sha256:${snapshot}`;
+	if (!zone) return { content: [{ type: "text", text: `${header}\nNo dependency import statements found.` }], details: { language, snapshot, found: false } };
+	const snippet = lines.slice(zone.start, zone.end + 1).join("\n");
+	const fence = fenceFor(snippet);
+	const text = `${header}\nImport zone: file lines ${zone.start + 1}-${zone.end + 1}. Raw source lines; regex-detected, not resolved.\n\n${fence}\n${snippet}\n${fence}`;
+	if (Buffer.byteLength(text, "utf8") > MAX_OUTPUT_BYTES || text.split("\n").length > MAX_OUTPUT_LINES) throw new Error(`The complete import zone exceeds the 48 KiB / 1,950-line output limit (lines ${zone.start + 1}-${zone.end + 1}). Use read with an explicit offset/limit.`);
+	return { content: [{ type: "text", text }], details: { language, snapshot, found: true, visible: { startLine: zone.start + 1, endLine: zone.end + 1 } } };
+}
+
+export async function executeReadCodeImports(input: ReadCodeImportsInput, signal: AbortSignal | undefined, ctx: Pick<ExtensionContext, "cwd">): Promise<ReadCodeImportsResult> {
+	validateReadCodeImportsInput(input);
+	const path = resolveToolPath(input.path, ctx.cwd);
+	let content: string;
+	try { content = await readSource(path, signal, "read_code_imports"); }
+	catch (error) { signal?.throwIfAborted(); throw new Error(boundCompleteOutput(await sourceReadError(path, error, "read_code_imports"))); }
+	try { return buildCodeImportsRead(input, content); }
+	catch (error) { throw new Error(boundCompleteOutput(error instanceof Error ? error.message : String(error))); }
+}
+
+export function registerReadCodeImportsTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "read_code_imports", label: "read_code_imports",
+		description: "Read the dependency import zone from a common-language source file as exact raw lines. Uses bounded regex-based detection for imports/includes/use/require statements, preserves comments and blank lines between adjacent imports, and reports the file range and snapshot. It does not resolve dependencies or replace read for arbitrary ranges.",
+		promptSnippet: "Read a source file's raw dependency import zone",
+		promptGuidelines: [
+			"When preparing an edit that adds code which uses a dependency, use read_code_imports if you are not sure whether the required import already exists.",
+			"When the target code also needs inspection, batch read_code_imports with that independent code read; inspect both results before making the dependent edit.",
+			"Treat read_code_imports output as regex-detected source text; inspect more context when conditional or generated imports can affect the edit.",
+			"Use the raw lines from read_code_imports to decide whether an import edit is needed, then include all required import and code changes in one edit call when possible.",
+		],
+		parameters: readCodeImportsSchema,
+		async execute(_id, input, signal, _onUpdate, ctx) { return executeReadCodeImports(input, signal, ctx); },
+	});
+}

package/src/read-evidence.ts

@@ -6,6 +6,7 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { normalizeToLF } from "./text.ts";
+import { buildSymbolRead, type ReadSymbolInput } from "./read-symbol.ts";
 
 export interface ReadEvidence {
 	/** 0-based, end-exclusive offsets in LF-normalized, BOM-stripped content. */
@@ -18,6 +19,8 @@ export interface ReadEvidence {
 
 interface ReadCall {
 	id: string;
+	name: "read" | "read_symbol";
+	arguments: Record<string, unknown>;
 	path: string;
 	offset?: number;
 	limit?: number;
@@ -69,11 +72,13 @@ export async function findLatestReadEvidence(
 	for (const message of messages) {
 		if (message.role === "assistant") {
 			for (const item of (message as StoredAssistant).content) {
-				if (item.type !== "toolCall" || item.name !== "read" || typeof item.id !== "string") continue;
+				if (item.type !== "toolCall" || (item.name !== "read" && item.name !== "read_symbol") || typeof item.id !== "string") continue;
 				const args = item.arguments as Record<string, unknown> | undefined;
 				if (!args || typeof args.path !== "string") continue;
 				calls.push({
 					id: item.id,
+					name: item.name,
+					arguments: args,
 					path: args.path,
 					offset: typeof args.offset === "number" ? args.offset : undefined,
 					limit: typeof args.limit === "number" ? args.limit : undefined,
@@ -81,7 +86,7 @@ export async function findLatestReadEvidence(
 			}
 		} else if (message.role === "toolResult") {
 			const result = message as StoredToolResult;
-			if (result.toolName === "read") results.set(result.toolCallId, result);
+			if (result.toolName === "read" || result.toolName === "read_symbol") results.set(result.toolCallId, result);
 		}
 	}
 
@@ -100,7 +105,17 @@ export async function findLatestReadEvidence(
 		// Never fall back to older intent when the newest same-file read is
 		// missing, failed, malformed, or stale.
 		const result = results.get(call.id);
-		if (!result || result.isError) return null;
+		if (!result || result.isError || result.toolName !== call.name) return null;
+		if (call.name === "read_symbol") {
+			if (result.content.length !== 1 || result.content[0].type !== "text") return null;
+			try {
+				// Regenerate from current source and original arguments, not untrusted
+				// details. Snapshot, selector, envelope, and visible bytes must agree.
+				const expected = await buildSymbolRead(call.arguments as ReadSymbolInput, normalizedContent);
+				if (result.content[0].text !== expected.content[0].text) return null;
+				return expected.details.visible ?? null;
+			} catch { return null; }
+		}
 		return evidenceFromBuiltinRead(normalizedContent, call, result.content);
 	}
 	return null;
@@ -155,7 +170,9 @@ export function evidenceFromBuiltinRead(
 	const startLine = startIndex + 1;
 	const endLine = startLine + visibleLines - 1;
 	const startOffset = offsetAtLine(content, startLine);
-	const endOffset = offsetAtLine(content, endLine + 1);
+	// A line-limited/truncated result omits the separator after its final
+	// displayed line. Do not authorize an edit anchor through unseen bytes.
+	const endOffset = startOffset + truncation.content.length;
 	return { startOffset, endOffset, startLine, endLine };
 }
 

package/src/read-symbol.ts

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { boundCompleteOutput, fenceFor } from "./diagnostics.ts";
+import { resolveToolPath } from "./paths.ts";
+import { readSource, sourceReadError } from "./source-file.ts";
+import { indexSymbols, languageForPath, SUPPORTED_LANGUAGES, type SourceSymbol } from "./symbols.ts";
+import { getLineSpans } from "./text.ts";
+
+export const readSymbolSchema = Type.Object({
+	path: Type.String({ minLength: 1, maxLength: 4096, description: "Local source file path (relative, absolute, @path, ~/path, or file URL)." }),
+	line: Type.Optional(Type.Integer({ minimum: 1, description: "Read the innermost symbol containing this 1-based line. Combine with symbol to disambiguate duplicate names." })),
+	column: Type.Optional(Type.Integer({ minimum: 1, description: "Optional 1-based UTF-16 column with line, to distinguish symbols on the same line." })),
+	symbol: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Exact symbol name or qualified name, for example Server.run. Omit both symbol and line to list a symbol outline." })),
+	parent: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, description: "Move outward this many enclosing symbols after selection (default 0)." })),
+	context: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, description: "Extra whole lines before and after the selected symbol (default 0)." })),
+	offset: Type.Optional(Type.Integer({ minimum: 1, description: "1-based position within the selected symbol/context or outline, not a file line. Use the exact continuation call from a partial result." })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 1800, description: "Maximum source lines (default 1000) or outline entries (default 50). Output also has a 48 KiB hard limit." })),
+});
+export type ReadSymbolInput = Static<typeof readSymbolSchema>;
+
+export interface VisibleSource {
+	startLine: number;
+	endLine: number;
+	startOffset: number;
+	endOffset: number;
+}
+export interface ReadSymbolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: {
+		mode: "symbol" | "outline";
+		snapshot: string;
+		symbol?: SourceSymbol;
+		visible?: VisibleSource;
+		complete: boolean;
+		nextCall?: ReadSymbolInput;
+	};
+}
+const MAX_OUTPUT_BYTES = 48 * 1024;
+const MAX_OUTPUT_LINES = 1950;
+const label = (text: string) => JSON.stringify(text.length > 300 ? `${text.slice(0, 297)}…` : text);
+const callText = (input: ReadSymbolInput) => `read_symbol ${JSON.stringify(input)}`;
+
+export function validateReadSymbolInput(input: ReadSymbolInput): void {
+	if (!input || typeof input.path !== "string" || !input.path.length || input.path.length > 4096) throw new Error("read_symbol requires a non-empty path of at most 4096 characters.");
+	if (input.symbol !== undefined && (typeof input.symbol !== "string" || !input.symbol.trim() || input.symbol.length > 256)) throw new Error("read_symbol symbol must be a non-empty name of at most 256 characters.");
+	for (const [key, min, max] of [["line", 1, Number.MAX_SAFE_INTEGER], ["column", 1, Number.MAX_SAFE_INTEGER], ["parent", 0, 20], ["context", 0, 20], ["offset", 1, Number.MAX_SAFE_INTEGER], ["limit", 1, 1800]] as const) {
+		const value = input[key];
+		if (value !== undefined && (!Number.isSafeInteger(value) || value < min || value > max)) throw new Error(`read_symbol ${key} must be an integer from ${min} to ${max}.`);
+	}
+	if (input.column !== undefined && input.line === undefined) throw new Error("read_symbol column requires line.");
+	if ((input.parent || input.context) && input.line === undefined && input.symbol === undefined) throw new Error("read_symbol parent/context requires a line or symbol selector; omit them to get an outline.");
+}
+
+function candidateLine(path: string, symbol: SourceSymbol): string {
+	return `- ${label(symbol.qualifiedName)} (${symbol.kind}), lines ${symbol.startLine}-${symbol.endLine}. ${callText({ path, line: symbol.startLine, column: symbol.startColumn, symbol: symbol.qualifiedName.length <= 256 ? symbol.qualifiedName : undefined })}`;
+}
+
+/** Non-copyable preview for failed selection; never presented as a complete symbol. */
+function fallbackContext(input: ReadSymbolInput, content: string, reason: string, atLine = input.line ?? 1): Error {
+	const lines = content.split("\n");
+	const center = Math.min(Math.max(atLine, 1), lines.length);
+	const start = Math.max(1, center - 5);
+	const end = Math.min(lines.length, center + 10);
+	const preview = lines.slice(start - 1, end).map((line, index) => `${start + index}: ${line.length > 240 ? `${line.slice(0, 240)}… [line clipped]` : line}`).join("\n");
+	return new Error(`${reason}\nFile has ${lines.length} lines. Preview only, not a complete symbol or retryable edit snippet:\n${preview}\nNext: read ${JSON.stringify({ path: input.path, offset: start, limit: end - start + 1 })}`);
+}
+
+function inside(symbol: SourceSymbol, line: number, column?: number): boolean {
+	if (line < symbol.startLine || line > symbol.endLine) return false;
+	if (column !== undefined && ((line === symbol.startLine && column < symbol.startColumn) || (line === symbol.endLine && column >= symbol.endColumn))) return false;
+	return true;
+}
+
+function selectSymbol(input: ReadSymbolInput, symbols: SourceSymbol[]): SourceSymbol {
+	let matches = symbols.filter((symbol) =>
+		(input.symbol === undefined || symbol.name === input.symbol || symbol.qualifiedName === input.symbol) &&
+		(input.line === undefined || inside(symbol, input.line, input.column)),
+	);
+	if (input.symbol === undefined) {
+		// Keep innermost declarations, but never choose arbitrarily between siblings.
+		const matched = new Set(matches);
+		const ancestors = new Set<SourceSymbol>();
+		// Parents precede children in the index. Propagate once in reverse,
+		// rather than walking every ancestor chain in deeply nested source.
+		for (let index = symbols.length - 1; index >= 0; index--) {
+			const symbol = symbols[index];
+			if (symbol.parent !== undefined && (matched.has(symbol) || ancestors.has(symbol))) ancestors.add(symbols[symbol.parent]);
+		}
+		matches = matches.filter((symbol) => !ancestors.has(symbol));
+	}
+	if (matches.length !== 1) {
+		const candidates = matches.length ? matches : [...symbols].sort((a, b) => {
+			if (input.line !== undefined) return Math.abs(a.startLine - input.line) - Math.abs(b.startLine - input.line);
+			const query = input.symbol?.toLowerCase() ?? "";
+			return Number(b.qualifiedName.toLowerCase().includes(query)) - Number(a.qualifiedName.toLowerCase().includes(query));
+		});
+		throw new Error([
+			matches.length ? `Ambiguous symbol selection: ${matches.length} candidates. No symbol was selected.` : "No matching symbol. Names are exact and case-sensitive; no nearby symbol was selected automatically.",
+			...candidates.slice(0, 8).map((symbol) => candidateLine(input.path, symbol)),
+			...(candidates.length > 8 ? [`${candidates.length - 8} more candidates omitted.`] : []),
+			`Next: choose a candidate call above, or list the outline with ${callText({ path: input.path })}.`,
+		].join("\n"));
+	}
+	let selected = matches[0];
+	for (let depth = 0; depth < (input.parent ?? 0); depth++) {
+		if (selected.parent === undefined) throw new Error(`No enclosing symbol at parent=${input.parent}. Outermost available: ${candidateLine(input.path, selected)}\nRetry with a smaller parent value.`);
+		selected = symbols[selected.parent];
+	}
+	return selected;
+}
+
+function fits(text: string): boolean {
+	return Buffer.byteLength(text, "utf8") <= MAX_OUTPUT_BYTES && text.split("\n").length <= MAX_OUTPUT_LINES;
+}
+
+/** Pure snapshot-to-result path, also used to verify stored read evidence. */
+export async function buildSymbolRead(input: ReadSymbolInput, content: string, signal?: AbortSignal): Promise<ReadSymbolResult> {
+	validateReadSymbolInput(input);
+	const lines = content.split("\n");
+	if (input.line !== undefined && input.line > lines.length) throw fallbackContext(input, content, `line=${input.line} is beyond EOF. Valid lines: 1-${lines.length}.`);
+	if (input.column !== undefined && input.column > lines[input.line! - 1].length + 1) throw fallbackContext(input, content, `column=${input.column} is outside line ${input.line}.`);
+	const parserPath = resolveToolPath(input.path, "/");
+	if (!languageForPath(parserPath)) throw fallbackContext(input, content, `Unsupported source type. read_symbol supports ${SUPPORTED_LANGUAGES}. Use read for this file.`);
+	let index: Awaited<ReturnType<typeof indexSymbols>>;
+	try { index = await indexSymbols(parserPath, content, signal); }
+	catch (error) {
+		signal?.throwIfAborted();
+		throw fallbackContext(input, content, `Symbol parser unavailable or analysis limit reached: ${error instanceof Error ? error.message.slice(0, 500) : "unknown parser error"}. Use read instead.`);
+	}
+	signal?.throwIfAborted();
+	if (index.errorLine !== undefined) throw fallbackContext(input, content, `Syntax error or incomplete syntax near line ${index.errorLine}; complete symbol boundaries are not reliable.`, input.line ?? index.errorLine);
+	const snapshot = createHash("sha256").update(content).digest("hex");
+	const header = `Source ${label(input.path)} (${lines.length} lines). Snapshot sha256:${snapshot}`;
+	const offset = input.offset ?? 1;
+	if (input.line === undefined && input.symbol === undefined) {
+		const total = index.symbols.length;
+		if (offset > Math.max(1, total)) throw new Error(`Outline offset=${offset} is beyond ${total} entries. Next: ${callText({ ...input, offset: Math.max(1, total - 49) })}`);
+		const entries: string[] = [];
+		let cursor = offset - 1;
+		for (; cursor < Math.min(total, offset - 1 + (input.limit ?? 50)); cursor++) {
+			const entry = candidateLine(input.path, index.symbols[cursor]);
+			if (!fits(`${header}\n${entries.join("\n")}\n${entry}\n${" ".repeat(6000)}`)) break;
+			entries.push(entry);
+		}
+		const nextCall = cursor < total ? { ...input, offset: cursor + 1 } : undefined;
+		const text = `${header}\nSymbol outline: ${total} declarations, ${entries.length} shown.${total === 0 ? " No symbols found; use read for source text." : ""}\n${entries.join("\n")}${nextCall ? `\nMore entries. Next: ${callText(nextCall)}` : ""}`;
+		return { content: [{ type: "text", text }], details: { mode: "outline", snapshot, complete: !nextCall, nextCall } };
+	}
+	if (!index.symbols.length) throw fallbackContext(input, content, "No symbol declarations found in this file.");
+	const selected = selectSymbol(input, index.symbols);
+	const start = Math.max(1, selected.startLine - (input.context ?? 0));
+	const end = Math.min(lines.length, selected.endLine + (input.context ?? 0));
+	const count = end - start + 1;
+	if (offset > count) throw new Error(`Symbol ${label(selected.qualifiedName)} spans lines ${selected.startLine}-${selected.endLine}; selected region has ${count} lines. offset=${offset} is outside it. Next: ${callText({ ...input, offset: 1 })}`);
+	const firstLine = start + offset - 1;
+	let lastLine = Math.min(end, firstLine + (input.limit ?? 1000) - 1);
+	const parents: string[] = [];
+	let parent = selected.parent;
+	while (parent !== undefined && parents.length < 20) { parents.unshift(label(index.symbols[parent].qualifiedName)); parent = index.symbols[parent].parent; }
+	const prefix = `${header}\nSymbol ${label(selected.qualifiedName)} (${selected.kind}), lines ${selected.startLine}-${selected.endLine}.${parents.length ? `\nEnclosing: ${parents.join(" > ")}` : ""}`;
+	let text = "";
+	let snippet = "";
+	let nextCall: ReadSymbolInput | undefined;
+	// Whole-line pages only. Account for fences, metadata, and continuation JSON.
+	while (lastLine >= firstLine) {
+		snippet = lines.slice(firstLine - 1, lastLine).join("\n");
+		const fence = fenceFor(snippet);
+		nextCall = lastLine < end ? { ...input, offset: lastLine - start + 2 } : undefined;
+		text = `${prefix}\nShowing file lines ${firstLine}-${lastLine} of selected lines ${start}-${end}. ${firstLine === start && lastLine === end ? "Complete selection." : "Partial selection; do not treat this page as the whole symbol."}\n\n${fence}\n${snippet}\n${fence}${nextCall ? `\n\nNext: ${callText(nextCall)}` : ""}`;
+		if (fits(text)) break;
+		// Remove a proportional chunk first; small pages shrink one line at a time.
+		lastLine -= Math.max(1, Math.floor((lastLine - firstLine + 1) / 4));
+	}
+	if (lastLine < firstLine) throw fallbackContext(input, content, `File line ${firstLine} cannot fit as a complete line in the 48 KiB output budget. No partial edit snippet was returned.`, firstLine);
+	const spans = getLineSpans(content);
+	const startOffset = spans[firstLine - 1]?.start ?? content.length;
+	return {
+		content: [{ type: "text", text }],
+		details: {
+			mode: "symbol", snapshot, symbol: selected,
+			visible: { startLine: firstLine, endLine: lastLine, startOffset, endOffset: startOffset + snippet.length },
+			complete: firstLine === start && lastLine === end, nextCall,
+		},
+	};
+}
+
+export async function executeReadSymbol(input: ReadSymbolInput, signal: AbortSignal | undefined, ctx: Pick<ExtensionContext, "cwd">): Promise<ReadSymbolResult> {
+	validateReadSymbolInput(input);
+	const path = resolveToolPath(input.path, ctx.cwd);
+	let content: string;
+	try { content = await readSource(path, signal); }
+	catch (error) { signal?.throwIfAborted(); throw new Error(boundCompleteOutput(await sourceReadError(path, error))); }
+	try { return await buildSymbolRead(input, content, signal); }
+	catch (error) {
+		signal?.throwIfAborted();
+		throw new Error(boundCompleteOutput(error instanceof Error ? error.message : String(error)));
+	}
+}
+
+export function registerReadSymbolTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "read_symbol", label: "read_symbol",
+		description: `Read a complete function, method, class, or type from a local source file by containing line or exact symbol name. Supports ${SUPPORTED_LANGUAGES}. With path only, lists a symbol outline. Includes enclosing names, exact source ranges, and actionable failure context. Output is bounded to 48 KiB/1950 lines; partial results include an exact continuation call. Does not replace read for ordinary text or images.`,
+		promptSnippet: "Read whole source symbols by line/name, or list a file's symbol outline",
+		promptGuidelines: [
+			"Use read_symbol with path and line after grep/edit identifies a code location, instead of guessing successive read offsets to find the function boundary.",
+			"Use read_symbol with symbol for an exact name or qualified name; use path alone for an outline. Use parent to include an enclosing function or class.",
+			"For read_symbol partial output, use the supplied continuation arguments. offset is relative to the selection, not a file line. Only displayed source is evidence for edit.",
+		],
+		parameters: readSymbolSchema,
+		async execute(_id, input, signal, _onUpdate, ctx) { return executeReadSymbol(input, signal, ctx); },
+	});
+}

package/src/source-file.ts

@@ -0,0 +1,62 @@
+import { constants } from "node:fs";
+import { open, opendir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { MAX_SOURCE_BYTES } from "./symbols.ts";
+import { normalizeToLF, splitBom } from "./text.ts";
+
+/** Bounded local source read; no silent decoding loss and no special files. */
+export async function readSource(path: string, signal?: AbortSignal, toolName = "read_symbol"): Promise<string> {
+	signal?.throwIfAborted();
+	const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	try {
+		const stat = await handle.stat();
+		if (!stat.isFile()) throw new Error("The path is not a regular source file.");
+		if (stat.size > MAX_SOURCE_BYTES) throw new Error("Source exceeds the 2 MiB symbol analysis limit; use read with offset/limit.");
+		const buffer = Buffer.alloc(Math.min(stat.size + 1, MAX_SOURCE_BYTES + 1));
+		let length = 0;
+		while (length < buffer.length) {
+			signal?.throwIfAborted();
+			const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+			if (!bytesRead) break;
+			length += bytesRead;
+		}
+		const after = await handle.stat();
+		if (length !== stat.size || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs || stat.ctimeMs !== after.ctimeMs) throw new Error(`The source changed during the read; retry ${toolName}.`);
+		const bytes = buffer.subarray(0, length);
+		let content: string;
+		try { content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+		catch { throw new Error("The source is not valid UTF-8; convert its encoding before symbol parsing."); }
+		if (bytes.includes(0)) throw new Error("The source contains NUL bytes; binary/UTF-16 input is not supported.");
+		signal?.throwIfAborted();
+		return splitBom(normalizeToLF(content)).text;
+	} finally {
+		await handle.close();
+	}
+}
+
+/** Only inspect a bounded number of siblings; never perform a hidden repo scan. */
+export async function sourceReadError(path: string, error: unknown, toolName = "read_symbol"): Promise<string> {
+	const code = (error as NodeJS.ErrnoException)?.code;
+	const message = error instanceof Error ? error.message.slice(0, 1000) : String(error).slice(0, 1000);
+	const lines = [`Could not read source ${JSON.stringify(path)}: ${message}`];
+	if (code === "ENOENT" || code === "ENOTDIR") {
+		const names: string[] = [];
+		try {
+			const directory = await opendir(dirname(path));
+			let inspected = 0;
+			for await (const entry of directory) {
+				if (entry.isFile()) names.push(entry.name);
+				if (++inspected >= 100) break;
+			}
+		} catch { /* Parent may also be missing or inaccessible. */ }
+		const stem = basename(path).split(".")[0].toLowerCase();
+		names.sort((a, b) => Number(b.toLowerCase().includes(stem)) - Number(a.toLowerCase().includes(stem)) || a.localeCompare(b));
+		if (names.length) lines.push("Nearby file candidates (bounded listing, not automatic path corrections):", ...names.slice(0, 8).map((name) => `  ${JSON.stringify(join(dirname(path), name))}`));
+		lines.push(`Verify the path and retry ${toolName}; use find/ls if the parent path is wrong.`);
+	} else if (code === "EACCES" || code === "EPERM") {
+		lines.push("Check file permissions. Do not retry the same call until access changes.");
+	} else lines.push(toolName === "read_symbol"
+		? "Use read for ordinary text, images, or bounded line ranges; no symbol boundaries were returned."
+		: "Use read for ordinary text, images, or bounded line ranges; no import lines were returned.");
+	return lines.join("\n");
+}