@shanepadgett/tau-agent 0.26.0 → 0.28.0

package/extensions/explore/ast/queries/outline.ts

@@ -0,0 +1,203 @@
+import { lstat } from "node:fs/promises";
+import type { ExploreEngine } from "../engine.ts";
+import type { Decl, DeclKind, FileIr } from "../ir.ts";
+import { filterDeclForest, walkDecls } from "../query.ts";
+import { scanSources, type ScanOutcome } from "../scan.ts";
+import { docsText, signatureText } from "../slice.ts";
+import { formatPathForDisplay, pathResolutionError, resolveExplorePath, walkPaths } from "../../traverse.ts";
+
+export type OutlineOptions = {
+	includePrivate: boolean;
+	includeDocs: boolean;
+	/** Exact `name` / `qualifiedName` filter. Empty → no name filter. */
+	names: readonly string[];
+};
+
+export type OutlineRow = {
+	depth: number;
+	startLine: number;
+	endLine: number;
+	kind: DeclKind;
+	name: string;
+	qualifiedName: string;
+	/** Signature source slice (no body). */
+	signature: string;
+	/** Attached docs when `includeDocs` and a span exists. */
+	docs: string | undefined;
+};
+
+export type OutlineFileView = {
+	/** Absolute path. */
+	path: string;
+	languageId: string;
+	parseDegraded: boolean;
+	rows: OutlineRow[];
+};
+
+export type OutlineResult = { mode: "file"; file: OutlineFileView } | { mode: "directory"; files: OutlineFileView[] };
+
+function keepVisibility(includePrivate: boolean): (decl: Decl) => boolean {
+	if (includePrivate) return () => true;
+	return (decl) => decl.visibility === "public" || decl.visibility === "protected";
+}
+
+/** Keep decls that match a name, or ancestors of a match (structure preserved). */
+function filterByNames(decls: readonly Decl[], names: ReadonlySet<string>): Decl[] {
+	const out: Decl[] = [];
+	for (const decl of decls) {
+		const selfMatch = names.has(decl.name) || names.has(decl.qualifiedName);
+		if (selfMatch) {
+			out.push(decl);
+			continue;
+		}
+		const children = filterByNames(decl.children, names);
+		if (children.length > 0) out.push({ ...decl, children });
+	}
+	return out;
+}
+
+function prepareDecls(ir: FileIr, options: OutlineOptions): Decl[] {
+	let decls = filterDeclForest(ir.decls, keepVisibility(options.includePrivate));
+	if (options.names.length > 0) {
+		decls = filterByNames(decls, new Set(options.names));
+	}
+	return decls;
+}
+
+function outlineFromIr(ir: FileIr, source: string, options: OutlineOptions): OutlineFileView {
+	const decls = prepareDecls(ir, options);
+	const rows: OutlineRow[] = [];
+	walkDecls(decls, (decl, depth) => {
+		rows.push({
+			depth,
+			startLine: decl.startLine,
+			endLine: decl.endLine,
+			kind: decl.kind,
+			name: decl.name,
+			qualifiedName: decl.qualifiedName,
+			signature: signatureText(decl, source),
+			docs: options.includeDocs ? docsText(decl, source) : undefined,
+		});
+	});
+	return {
+		path: ir.path,
+		languageId: ir.languageId,
+		parseDegraded: ir.parseDegraded,
+		rows,
+	};
+}
+
+/** Multi-file: keep files with rows, or degraded parses (diagnostic only). */
+function keepMultiFileView(view: OutlineFileView): boolean {
+	return view.rows.length > 0 || view.parseDegraded;
+}
+
+async function outlineAbsoluteFile(
+	engine: ExploreEngine,
+	absolutePath: string,
+	options: OutlineOptions,
+): Promise<OutlineFileView> {
+	const source = await engine.sourceForFile(absolutePath);
+	return outlineFromIr(source.ir, source.source, options);
+}
+
+/** Ignore-aware one-level file list. Intentional shallow walk — maxDepth limit is not a failure. */
+async function listSupportedFilesOneLevel(
+	engine: ExploreEngine,
+	directory: string,
+	signal: AbortSignal,
+): Promise<string[]> {
+	const walk = await walkPaths({
+		cwd: engine.cwd,
+		root: directory,
+		filesOnly: true,
+		includeRoot: false,
+		budgets: { maxDepth: 1 },
+		signal,
+		matchFile: (hit) => engine.registry.adapterForPath(hit.absolutePath) !== undefined,
+	});
+	if (walk.limit === "cancelled" || signal.aborted) {
+		throw new Error("outline cancelled");
+	}
+	return walk.entries
+		.filter((hit) => hit.depth === 1 && hit.type === "file")
+		.map((hit) => hit.absolutePath)
+		.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * File or one-level directory outline (non-recursive).
+ * Recursive streaming lives in the tool (complete-block emission).
+ */
+export async function outlinePath(
+	engine: ExploreEngine,
+	pathInput: string,
+	options: OutlineOptions,
+	signal: AbortSignal,
+): Promise<OutlineResult> {
+	signal.throwIfAborted();
+	const absolutePath = resolveExplorePath(engine.cwd, pathInput);
+	let stats;
+	try {
+		stats = await lstat(absolutePath);
+	} catch (error) {
+		throw pathResolutionError(error, pathInput);
+	}
+
+	if (stats.isDirectory()) {
+		const paths = await listSupportedFilesOneLevel(engine, absolutePath, signal);
+		const files: OutlineFileView[] = [];
+		for (const filePath of paths) {
+			signal.throwIfAborted();
+			const view = await outlineAbsoluteFile(engine, filePath, options);
+			if (keepMultiFileView(view)) files.push(view);
+		}
+		return { mode: "directory", files };
+	}
+
+	if (!stats.isFile()) {
+		throw new Error(`Not a file or directory: ${formatPathForDisplay(absolutePath, engine.cwd)}`);
+	}
+	if (engine.registry.adapterForPath(absolutePath) === undefined) {
+		throw new Error(`Unsupported language for path: ${formatPathForDisplay(absolutePath, engine.cwd)}`);
+	}
+	const file = await outlineAbsoluteFile(engine, absolutePath, options);
+	return { mode: "file", file };
+}
+
+/**
+ * Stream recursive outline file units. Yields IR+bytes together (one source read per file).
+ * Return value is the scan outcome (limits / counters).
+ */
+export async function* outlineRecursive(
+	engine: ExploreEngine,
+	pathInput: string,
+	options: OutlineOptions,
+	signal: AbortSignal,
+): AsyncGenerator<OutlineFileView, ScanOutcome> {
+	signal.throwIfAborted();
+	const absolutePath = resolveExplorePath(engine.cwd, pathInput);
+	let stats;
+	try {
+		stats = await lstat(absolutePath);
+	} catch (error) {
+		throw pathResolutionError(error, pathInput);
+	}
+	if (!stats.isDirectory()) {
+		throw new Error("recursive outline requires a directory target");
+	}
+
+	const scan = scanSources({ engine, cwd: engine.cwd, root: absolutePath, signal });
+	let step = await scan.next();
+	while (!step.done) {
+		signal.throwIfAborted();
+		const view = outlineFromIr(step.value.ir, step.value.source, options);
+		if (keepMultiFileView(view)) yield view;
+		step = await scan.next();
+	}
+	const outcome = step.value;
+	if (outcome.limit === "cancelled" || signal.aborted) {
+		throw new Error("outline cancelled");
+	}
+	return outcome;
+}

package/extensions/explore/ast/queries/show.ts

@@ -0,0 +1,262 @@
+import type { ExploreEngine } from "../engine.ts";
+import type { Candidate, Target } from "../identity.ts";
+import { resolveTarget } from "../identity.ts";
+import type { Decl, FileIr, ImportRef } from "../ir.ts";
+import { declarationText, signatureText, signatureWithDocsText } from "../slice.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+
+export type ShowView = "signature" | "signatureWithDocs" | "declaration" | "declarationWithImports";
+
+export type ShowTargetInput = {
+	path: string;
+	name: string;
+	line?: number;
+};
+
+export type ShowBlock = {
+	path: string;
+	name: string;
+	qualifiedName: string;
+	startLine: number;
+	endLine: number;
+	text: string;
+	/** Real warnings only (e.g. no docs for signatureWithDocs). */
+	warnings: string[];
+};
+
+export type ShowBatch = {
+	blocks: ShowBlock[];
+};
+
+const IDENTIFIER = /[A-Za-z_$][\w$]*/gu;
+
+const NO_IMPORT_NOISE: ReadonlySet<string> = new Set();
+
+function targetKey(target: ShowTargetInput): string {
+	const line = target.line === undefined ? "" : String(target.line);
+	return `${stripLeadingAt(target.path)}\0${target.name}\0${line}`;
+}
+
+/** Dedupe identical path+name+line targets, preserving first-seen order. */
+function dedupeShowTargets(targets: readonly ShowTargetInput[]): ShowTargetInput[] {
+	const seen = new Set<string>();
+	const out: ShowTargetInput[] = [];
+	for (const target of targets) {
+		const key = targetKey(target);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push({
+			path: stripLeadingAt(target.path),
+			name: target.name,
+			...(target.line === undefined ? {} : { line: target.line }),
+		});
+	}
+	return out;
+}
+
+function identifiersIn(text: string, noise: ReadonlySet<string>): Set<string> {
+	const out = new Set<string>();
+	for (const match of text.matchAll(IDENTIFIER)) {
+		const id = match[0];
+		if (id !== undefined && !noise.has(id)) out.add(id);
+	}
+	return out;
+}
+
+/** Exact import statement text from adapter byte span. Noise set is language-owned. */
+function importStatementsFor(
+	declText: string,
+	imports: readonly ImportRef[],
+	source: string,
+	noise: ReadonlySet<string>,
+): string[] {
+	const declIds = identifiersIn(declText, noise);
+	const seenSpans = new Set<string>();
+	const out: string[] = [];
+	for (const importRef of imports) {
+		const spanKey = `${importRef.startOffset}:${importRef.endOffset}`;
+		if (seenSpans.has(spanKey)) continue;
+		const statement = source.slice(importRef.startOffset, importRef.endOffset).replace(/\s+$/u, "");
+		if (statement.length === 0) continue;
+		const hit = [...identifiersIn(statement, noise)].some((id) => declIds.has(id));
+		if (!hit) continue;
+		seenSpans.add(spanKey);
+		out.push(statement);
+	}
+	return out;
+}
+
+function lineRanges(source: string): { start: number; end: number }[] {
+	const ranges: { start: number; end: number }[] = [];
+	let start = 0;
+	for (let i = 0; i < source.length; i += 1) {
+		if (source.charCodeAt(i) === 10) {
+			ranges.push({ start, end: i });
+			start = i + 1;
+		}
+	}
+	if (start < source.length || source.length === 0) {
+		ranges.push({ start, end: source.length });
+	}
+	return ranges;
+}
+
+function sliceLines(source: string, startLine: number, endLine: number): string {
+	const ranges = lineRanges(source);
+	if (ranges.length === 0) return "";
+	const lo = Math.max(1, startLine);
+	const hi = Math.min(ranges.length, endLine);
+	if (hi < lo) return "";
+	const start = ranges[lo - 1];
+	const end = ranges[hi - 1];
+	if (start === undefined || end === undefined) return "";
+	return source.slice(start.start, end.end);
+}
+
+/** Exact source slice for one resolved decl. Shared by show and context. */
+export function extractShowView(
+	decl: Decl,
+	path: string,
+	ir: FileIr,
+	source: string,
+	view: ShowView,
+	importNoise: ReadonlySet<string> = NO_IMPORT_NOISE,
+	contextLines = 0,
+): ShowBlock {
+	return buildBlock(decl, path, ir, source, view, contextLines, importNoise);
+}
+
+function buildBlock(
+	decl: Decl,
+	path: string,
+	ir: FileIr,
+	source: string,
+	view: ShowView,
+	contextLines: number,
+	importNoise: ReadonlySet<string>,
+): ShowBlock {
+	const warnings: string[] = [];
+	let text: string;
+	let startLine = decl.startLine;
+	let endLine = decl.endLine;
+
+	switch (view) {
+		case "signature": {
+			text = signatureText(decl, source);
+			break;
+		}
+		case "signatureWithDocs": {
+			if (decl.docStartOffset === undefined || decl.docEndOffset === undefined) {
+				warnings.push("no attached documentation");
+				text = signatureText(decl, source);
+			} else {
+				text = signatureWithDocsText(decl, source);
+			}
+			break;
+		}
+		case "declaration": {
+			if (contextLines > 0) {
+				startLine = Math.max(1, decl.startLine - contextLines);
+				endLine = Math.min(Math.max(ir.lineCount, decl.endLine), decl.endLine + contextLines);
+				text = sliceLines(source, startLine, endLine);
+			} else {
+				text = declarationText(decl, source);
+			}
+			break;
+		}
+		case "declarationWithImports": {
+			const declText = declarationText(decl, source);
+			const importBlocks = importStatementsFor(declText, ir.imports, source, importNoise);
+			text = importBlocks.length > 0 ? `${importBlocks.join("\n")}\n\n${declText}` : declText;
+			break;
+		}
+	}
+
+	return {
+		path,
+		name: decl.name,
+		qualifiedName: decl.qualifiedName,
+		startLine,
+		endLine,
+		text,
+		warnings,
+	};
+}
+
+function formatCandidateError(label: string, candidates: readonly Candidate[], cwd: string): string {
+	const lines = [
+		`Ambiguous target ${label}:`,
+		...candidates.map((candidate) => {
+			const path = formatPathForDisplay(candidate.path, cwd);
+			const range =
+				candidate.startLine === candidate.endLine
+					? `L${candidate.startLine}`
+					: `L${candidate.startLine}-${candidate.endLine}`;
+			const sig = candidate.signature.replace(/\s+/gu, " ").trim();
+			return `${path}:${range} ${candidate.kind} ${candidate.qualifiedName} — ${sig}`;
+		}),
+	];
+	return lines.join("\n");
+}
+
+/**
+ * Resolve every target before emitting. Any missing/ambiguous target fails the whole batch.
+ * `contextLines` must be omitted (undefined) unless view is declaration.
+ */
+export async function showTargets(
+	engine: ExploreEngine,
+	targets: readonly ShowTargetInput[],
+	view: ShowView,
+	contextLines: number | undefined,
+	signal: AbortSignal,
+): Promise<ShowBatch> {
+	if (contextLines !== undefined && view !== "declaration") {
+		throw new Error("contextLines is supported only with view=declaration");
+	}
+	const context = contextLines ?? 0;
+
+	const unique = dedupeShowTargets(targets);
+	const blocks: ShowBlock[] = [];
+	let docsWarningEmitted = false;
+
+	for (const target of unique) {
+		signal.throwIfAborted();
+		const resolutionTarget: Target = {
+			path: target.path,
+			name: target.name,
+			...(target.line === undefined ? {} : { line: target.line }),
+		};
+		const resolution = await resolveTarget(engine, engine.cwd, resolutionTarget, signal);
+		const label =
+			target.line === undefined
+				? `${target.name} @ ${target.path}`
+				: `${target.name} @ ${target.path}:${target.line}`;
+
+		if (resolution.kind === "notFound") {
+			throw new Error(`No declaration matched ${label}`);
+		}
+		if (resolution.kind === "candidates") {
+			throw new Error(formatCandidateError(label, resolution.candidates, engine.cwd));
+		}
+
+		const adapter = engine.registry.adapterForPath(resolution.path);
+		const importNoise = adapter?.importNoiseIdentifiers ?? NO_IMPORT_NOISE;
+		const block = buildBlock(
+			resolution.decl,
+			resolution.path,
+			resolution.ir,
+			resolution.source,
+			view,
+			context,
+			importNoise,
+		);
+		if (docsWarningEmitted) {
+			block.warnings = block.warnings.filter((warning) => warning !== "no attached documentation");
+		} else if (block.warnings.includes("no attached documentation")) {
+			docsWarningEmitted = true;
+		}
+		blocks.push(block);
+	}
+
+	return { blocks };
+}

package/extensions/explore/ast/query.ts

@@ -0,0 +1,48 @@
+import type { Decl } from "./ir.ts";
+
+/** Depth-first visit of a decl forest. */
+export function walkDecls(decls: readonly Decl[], visit: (decl: Decl, depth: number) => void): void {
+	const go = (nodes: readonly Decl[], depth: number): void => {
+		for (const decl of nodes) {
+			visit(decl, depth);
+			if (decl.children.length > 0) go(decl.children, depth + 1);
+		}
+	};
+	go(decls, 0);
+}
+
+function nameMatches(decl: Decl, name: string): boolean {
+	return decl.name === name || decl.qualifiedName === name;
+}
+
+function coversLine(decl: Decl, line: number): boolean {
+	return line >= decl.startLine && line <= decl.endLine;
+}
+
+function findByName(decls: readonly Decl[], name: string): Decl[] {
+	const out: Decl[] = [];
+	walkDecls(decls, (decl) => {
+		if (nameMatches(decl, name)) out.push(decl);
+	});
+	return out;
+}
+
+/** Name matches, then optional line filter. */
+export function findTargets(decls: readonly Decl[], name: string, line?: number): Decl[] {
+	const named = findByName(decls, name);
+	if (line === undefined) return named;
+	return named.filter((decl) => coversLine(decl, line));
+}
+
+/** Drop private/internal decls from a forest; keep structure. */
+export function filterDeclForest(decls: readonly Decl[], keep: (decl: Decl) => boolean): Decl[] {
+	const out: Decl[] = [];
+	for (const decl of decls) {
+		if (!keep(decl)) continue;
+		out.push({
+			...decl,
+			children: filterDeclForest(decl.children, keep),
+		});
+	}
+	return out;
+}

package/extensions/explore/ast/read/hook.ts

@@ -0,0 +1,125 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadTauExtensionSettings } from "../../../../shared/settings/load.ts";
+import exploreSettings from "../../settings.ts";
+import { resolveExplorePath } from "../../traverse.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatOutlineFile } from "../format/outline.ts";
+import { outlinePath } from "../queries/outline.ts";
+import {
+	countLines,
+	formatLargeReadOutline,
+	rangedReadOverLimitMessage,
+	readCallKind,
+	shouldOutlineFullRead,
+	type ExploreReadSettings,
+} from "./policy.ts";
+
+type ReadOverlayResult = {
+	content: Array<{ type: "text"; text: string }>;
+	isError: boolean;
+};
+
+const DEFAULT_OUTLINE_OPTIONS = {
+	includePrivate: false,
+	includeDocs: false,
+	names: [] as readonly string[],
+};
+
+export function registerReadOutlineHook(pi: ExtensionAPI, engineFor: (cwd: string) => ExploreEngine): void {
+	let readSettings: ExploreReadSettings = exploreSettings.defaults.read;
+
+	pi.on("session_start", async (_event, ctx) => {
+		const settings = await loadTauExtensionSettings(ctx, exploreSettings);
+		readSettings = settings.read;
+	});
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.toolName !== "read") return;
+		if (event.isError) return;
+		if (!readSettings.enabled) return;
+		if (event.content.some((part) => part.type === "image")) return;
+
+		const path = readPathInput(event.input);
+		if (path === undefined) return;
+
+		const engine = engineFor(ctx.cwd);
+		const absolutePath = resolveExplorePath(engine.cwd, path);
+		if (engine.registry.adapterForPath(absolutePath) === undefined) return;
+
+		const kind = readCallKind(event.input);
+		if (kind === "ranged") {
+			return enforceRangedLimit(event.input, event.content, readSettings.maxRangeLines);
+		}
+
+		return substituteLargeFullRead({
+			engine,
+			path,
+			absolutePath,
+			structureThresholdLines: readSettings.structureThresholdLines,
+		});
+	});
+}
+
+async function substituteLargeFullRead(options: {
+	engine: ExploreEngine;
+	path: string;
+	absolutePath: string;
+	structureThresholdLines: number;
+}): Promise<ReadOverlayResult | undefined> {
+	let lineCount: number;
+	try {
+		const source = await options.engine.sourceForFile(options.absolutePath);
+		lineCount = source.ir.lineCount;
+	} catch {
+		// Unreadable / unsupported mid-flight — leave Pi result alone.
+		return undefined;
+	}
+
+	if (!shouldOutlineFullRead(lineCount, options.structureThresholdLines)) return undefined;
+
+	try {
+		const result = await outlinePath(
+			options.engine,
+			options.path,
+			DEFAULT_OUTLINE_OPTIONS,
+			new AbortController().signal,
+		);
+		if (result.mode !== "file") return undefined;
+		const outlineText =
+			result.file.rows.length === 0 ? "No declarations" : formatOutlineFile(result.file, options.engine.cwd, false);
+		return {
+			content: [{ type: "text", text: formatLargeReadOutline(outlineText) }],
+			isError: false,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+function enforceRangedLimit(
+	input: Record<string, unknown>,
+	content: ReadonlyArray<{ type: string; text?: string }>,
+	maxRangeLines: number,
+): ReadOverlayResult | undefined {
+	const limit = typeof input.limit === "number" && Number.isFinite(input.limit) ? input.limit : undefined;
+	const returnedLines = countLines(textFromContent(content));
+	const message = rangedReadOverLimitMessage({ limit, returnedLines, maxRangeLines });
+	if (message === undefined) return undefined;
+	return {
+		content: [{ type: "text", text: message }],
+		isError: true,
+	};
+}
+
+function readPathInput(input: Record<string, unknown>): string | undefined {
+	const path = input.path;
+	return typeof path === "string" && path.length > 0 ? path : undefined;
+}
+
+function textFromContent(content: ReadonlyArray<{ type: string; text?: string }>): string {
+	const parts: string[] = [];
+	for (const part of content) {
+		if (part.type === "text" && typeof part.text === "string") parts.push(part.text);
+	}
+	return parts.join("\n");
+}

package/extensions/explore/ast/read/policy.ts

@@ -0,0 +1,55 @@
+export type ExploreReadSettings = {
+	enabled: boolean;
+	structureThresholdLines: number;
+	maxRangeLines: number;
+};
+
+export type ReadCallKind = "full" | "ranged";
+
+const LARGE_READ_OUTLINE_INSTRUCTION = "large file: use ranged read or show for bodies";
+
+/** Newline-based line count (empty string → 0). */
+export function countLines(text: string): number {
+	if (text.length === 0) return 0;
+	let count = 1;
+	for (let i = 0; i < text.length; i += 1) {
+		const code = text.charCodeAt(i);
+		if (code === 10) count += 1;
+		else if (code === 13) {
+			count += 1;
+			if (text.charCodeAt(i + 1) === 10) i += 1;
+		}
+	}
+	return count;
+}
+
+export function readCallKind(input: { offset?: unknown; limit?: unknown }): ReadCallKind {
+	const hasOffset = typeof input.offset === "number" && Number.isFinite(input.offset);
+	const hasLimit = typeof input.limit === "number" && Number.isFinite(input.limit);
+	return hasOffset || hasLimit ? "ranged" : "full";
+}
+
+export function shouldOutlineFullRead(lineCount: number, structureThresholdLines: number): boolean {
+	return lineCount > structureThresholdLines;
+}
+
+/** Hard-error message when a ranged read exceeds maxRangeLines; undefined when allowed. */
+export function rangedReadOverLimitMessage(options: {
+	limit: number | undefined;
+	returnedLines: number;
+	maxRangeLines: number;
+}): string | undefined {
+	const { limit, returnedLines, maxRangeLines } = options;
+	if (typeof limit === "number" && limit > maxRangeLines) {
+		return `Range limit ${limit} exceeds explore.read.maxRangeLines (${maxRangeLines}). Shrink limit and retry.`;
+	}
+	if (returnedLines > maxRangeLines) {
+		return `Ranged read returned ${returnedLines} lines; max is explore.read.maxRangeLines (${maxRangeLines}). Set a smaller limit and retry.`;
+	}
+	return undefined;
+}
+
+export function formatLargeReadOutline(outlineText: string): string {
+	if (outlineText.length === 0) return LARGE_READ_OUTLINE_INSTRUCTION;
+	return `${outlineText}\n${LARGE_READ_OUTLINE_INSTRUCTION}`;
+}