@shanepadgett/tau-agent 0.25.0 → 0.26.0

package/extensions/explore/README.md

@@ -6,7 +6,7 @@ It exists so agents can inspect paths, discover files, search text, inspect decl
 
 When the source baseline is no longer available, such as after compaction or a cold subagent resume, `read` safely returns the current full source.
 
-Agents invoke it with `ls`, `find`, `grep`, `outline`, `symbol`, and `read`. `outline` returns public declaration signatures and parenthesized numeric locators for TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, and Swift files. It also accepts a package directory, which inspects supported files directly inside it. Exact-name filters narrow the result, while `includePrivate` exposes internal declarations. `symbol` accepts those numbers to retrieve several exact declarations in one call, can add bounded surrounding lines, and rejects the whole batch when any locator is stale. Users run `/read-stats` to see estimated token and cost savings for the session.
+Agents invoke it with `ls`, `find`, `grep`, `outline`, `symbol`, and `read`. `outline` returns public declaration signatures and parenthesized numeric locators for TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown files. Markdown headings locate their complete sections. It also accepts a package directory, which inspects supported files directly inside it. Exact-name filters narrow the result, `includePrivate` exposes internal declarations, and `includeDocs` adds attached documentation comments when they are needed. Annotations and attributes remain in normal outlines. `symbol` accepts those numbers to retrieve several exact declarations in one call, can add bounded surrounding lines, and rejects the whole batch when any locator is stale. Users run `/read-stats` to see estimated token and cost savings for the session.
 
 Installed packages support `outline` and `symbol` on Apple Silicon Macs. They include the worker, so users do not need Rust or Cargo. On other platforms, the rest of Explore remains available and AST tools report the platform limit when invoked.
 
@@ -15,6 +15,7 @@ Use the cheapest useful step:
 1. Outline a package directory to discover its public API.
 2. Add exact names when likely declarations are known.
 3. Set `includePrivate` when implementation work needs internals.
-4. Send several locators to `symbol` for complete declarations.
-5. Add context lines when the edit needs nearby source.
-6. Use ranged or whole-file `read` for cross-cutting logic, exact formatting, or parser gaps.
+4. Set `includeDocs` when declaration documentation affects the task.
+5. Send several locators to `symbol` for complete declarations.
+6. Add context lines when the edit needs nearby source.
+7. Use ranged or whole-file `read` for cross-cutting logic, exact formatting, or parser gaps.

package/extensions/explore/ast-tools.ts

@@ -7,6 +7,7 @@ import {
 	truncateHead,
 	type Theme,
 } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { Text, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
 import { stat } from "node:fs/promises";
 import { basename, extname, resolve } from "node:path";
@@ -18,17 +19,22 @@ import type {
 	AstLanguage,
 	OutlineEntry,
 	OutlineFileResult,
+	SourceRange,
 	OutlineTarget,
 	OutlineTargetResult,
 	SymbolBatchResult,
+	SymbolView,
 } from "./ast-worker.ts";
 
 const outlineParams = Type.Object(
 	{
 		path: Type.String({
-			description: "TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, or Swift source file or directory",
+			description: "TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, or Markdown source file or directory",
 		}),
 		includePrivate: Type.Optional(Type.Boolean({ description: "Include private declarations and members" })),
+		includeDocs: Type.Optional(
+			Type.Boolean({ description: "Include attached documentation comments in declaration signatures" }),
+		),
 		names: Type.Optional(
 			Type.Array(Type.String(), {
 				minItems: 1,
@@ -44,6 +50,10 @@ const symbolParams = Type.Object(
 			minItems: 1,
 			description: "Numeric locators shown in parentheses by outline",
 		}),
+		view: StringEnum(["signature", "declaration", "declarationWithImports"] as const, {
+			description:
+				"Source view to retrieve; TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown support selective views",
+		}),
 		contextLines: Type.Optional(
 			Type.Integer({ minimum: 0, description: "Lines of source context before and after each declaration" }),
 		),
@@ -67,9 +77,11 @@ interface LocatorRecord {
 	path: string;
 	name: string;
 	stale: boolean;
+	declarationRetrieved: boolean;
+	generation: number;
 }
 
-type OutlineArgs = { path: string; includePrivate?: boolean; names?: string[] };
+type OutlineArgs = { path: string; includePrivate?: boolean; includeDocs?: boolean; names?: string[] };
 
 export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 	const locators = new Map<number, LocatorRecord>();
@@ -102,29 +114,204 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 	}
 
 	function locator(entry: OutlineEntry, path: string): number {
+		if (!entry.locator) throw new Error(`Structural outline row ${entry.name} has no symbol locator`);
 		const id = nextLocator++;
-		const record = { id, token: entry.locator, path: resolve(path), name: entry.name, stale: false };
+		const record = {
+			id,
+			token: entry.locator,
+			path: resolve(path),
+			name: entry.name,
+			stale: false,
+			declarationRetrieved: false,
+			generation: client.getGeneration(),
+		};
 		locators.set(id, record);
 		return id;
 	}
 
-	function renderEntry(entry: OutlineEntry, path: string, language: AstLanguage, indent: string): string {
-		const lines =
-			entry.range.start.line === entry.range.end.line
-				? `${entry.range.start.line + 1}`
-				: `${entry.range.start.line + 1}-${entry.range.end.line + 1}`;
-		let signature = entry.signature.replace(/\s+/g, " ").trim();
-		if (language === "odin") {
-			signature = signature
-				.replace(/\s*([(),:])\s*/g, "$1")
-				.replace(/\s*->\s*/g, "->")
-				.replace(/\s*:=\s*/g, ":=")
-				.replace(/\s*\{\s*$/, "");
+	function renderEntry(
+		entry: OutlineEntry,
+		path: string,
+		language: AstLanguage,
+		indent: string,
+		signatureOverride?: string,
+	): string {
+		const lines = displayLineRange(entry.range);
+		let signature = (signatureOverride ?? entry.signature).trim();
+		if (
+			language === "typeScript" ||
+			language === "tsx" ||
+			language === "odin" ||
+			language === "go" ||
+			language === "rust" ||
+			language === "cSharp" ||
+			language === "java" ||
+			language === "kotlin" ||
+			language === "swift" ||
+			language === "markdown"
+		) {
+			const signatureLines = signature.split("\n");
+			const relativeNameLine = entry.nameRange.start.line - entry.range.start.line;
+			const keywordNameLine =
+				language === "go"
+					? signatureLines.findIndex(
+							(line) => /\b(?:func|type|const|var)\b/.test(line) && line.includes(entry.name),
+						)
+					: -1;
+			let inBlockComment = false;
+			let annotationDepth = 0;
+			let attributeDepth = 0;
+			const metadataLines = signatureLines.map((line) => {
+				const trimmed = line.trimStart();
+				if (inBlockComment) {
+					if (trimmed.includes("*/")) inBlockComment = false;
+					return true;
+				}
+				if (trimmed.startsWith("/*")) {
+					inBlockComment = !trimmed.includes("*/");
+					return true;
+				}
+				if (annotationDepth > 0) {
+					annotationDepth += (line.match(/\(/g) ?? []).length - (line.match(/\)/g) ?? []).length;
+					return true;
+				}
+				if (attributeDepth > 0) {
+					attributeDepth += (line.match(/\[/g) ?? []).length - (line.match(/\]/g) ?? []).length;
+					return true;
+				}
+				if (trimmed.startsWith("@") && !trimmed.startsWith(`@interface ${entry.name}`)) {
+					annotationDepth = (line.match(/\(/g) ?? []).length - (line.match(/\)/g) ?? []).length;
+					return true;
+				}
+				if (trimmed.startsWith("#[")) {
+					attributeDepth = (line.match(/\[/g) ?? []).length - (line.match(/\]/g) ?? []).length;
+					return true;
+				}
+				return trimmed.startsWith("//");
+			});
+			const declarationNameLine = signatureLines.findIndex(
+				(line, index) => !metadataLines[index] && line.includes(entry.name),
+			);
+			const nameLine =
+				relativeNameLine >= 0 && relativeNameLine === declarationNameLine
+					? relativeNameLine
+					: keywordNameLine >= 0
+						? keywordNameLine
+						: declarationNameLine;
+			const declarationLine = language === "markdown" ? Math.max(0, relativeNameLine) : nameLine >= 0 ? nameLine : 0;
+			const sourceLine = signatureLines[declarationLine] ?? entry.name;
+			const first =
+				language === "markdown" || sourceLine.includes(entry.name) ? sourceLine : `${entry.name} ${sourceLine}`;
+			const warning =
+				entry.certainty === "certain"
+					? ""
+					: ` [${entry.certainty}${entry.certaintyReason ? `: ${entry.certaintyReason}` : ""}]`;
+			return [
+				...signatureLines.slice(0, declarationLine).map((line) => `${indent}${line}`),
+				`${indent}${lines}(${locator(entry, path)}): ${first}${warning}`,
+				...signatureLines.slice(declarationLine + 1).map((line) => `${indent}${line}`),
+			].join("\n");
 		}
+		signature = signature.replace(/\s+/g, " ");
 		const label = signature && signature.includes(entry.name) ? signature : `${entry.name} ${signature}`.trim();
 		return `${indent}${lines}(${locator(entry, path)}): ${label}`;
 	}
 
+	function renderStructuralEntry(entry: OutlineEntry, indent: string): string {
+		const lines = displayLineRange(entry.range);
+		return `${indent}${lines}: ${entry.signature.trim().replace(/\s+/g, " ")}`;
+	}
+
+	function containerFrame(
+		item: OutlineFileResult["items"][number],
+		language: AstLanguage,
+	): { header: string; footer: string } | undefined {
+		const firstMember = item.members[0];
+		if (!firstMember) return undefined;
+		if (
+			(language === "odin" ||
+				language === "cSharp" ||
+				language === "java" ||
+				language === "kotlin" ||
+				language === "swift") &&
+			item.bodyRange
+		) {
+			const bodyOffset = item.bodyRange.startByte - item.range.startByte;
+			const signature = Buffer.from(item.signature);
+			if (bodyOffset >= 0 && bodyOffset < signature.byteLength) {
+				const header = signature
+					.subarray(0, bodyOffset + 1)
+					.toString("utf8")
+					.trimEnd();
+				if (header.endsWith("{")) return { header, footer: "}" };
+			}
+		}
+		if (
+			item.symbolType === "class" ||
+			item.symbolType === "struct" ||
+			item.symbolType === "interface" ||
+			item.symbolType === "enum" ||
+			item.symbolType === "object" ||
+			item.symbolType === "namespace"
+		) {
+			const members = (
+				language === "typeScript" ||
+				language === "tsx" ||
+				language === "cSharp" ||
+				language === "java" ||
+				language === "kotlin" ||
+				language === "swift"
+					? item.members.filter(
+							(member) => member.qualifiedName.split(".").slice(0, -1).join(".") === item.qualifiedName,
+						)
+					: item.members
+			)
+				.map((member) =>
+					(language === "java" &&
+					(member.symbolType === "class" ||
+						member.symbolType === "struct" ||
+						member.symbolType === "interface" ||
+						member.symbolType === "enum") &&
+					member.signature.endsWith("{")
+						? `${member.signature} … }`
+						: member.signature
+					)
+						.split("\n")
+						.map((line) => `  ${line}`)
+						.join("\n"),
+				)
+				.join("\n");
+			const braceSuffix = `\n${members}\n}`;
+			if (item.signature.endsWith(braceSuffix))
+				return { header: item.signature.slice(0, -braceSuffix.length), footer: "}" };
+			const tupleMembers = item.members
+				.map((member) =>
+					`${member.signature},`
+						.split("\n")
+						.map((line) => `  ${line}`)
+						.join("\n"),
+				)
+				.join("\n");
+			const tupleSuffix = `\n${tupleMembers}\n);`;
+			if (item.signature.endsWith(tupleSuffix))
+				return { header: item.signature.slice(0, -tupleSuffix.length), footer: ");" };
+			const tupleMarker = `\n${tupleMembers}\n)`;
+			const tupleMarkerIndex = item.signature.lastIndexOf(tupleMarker);
+			if (tupleMarkerIndex >= 0)
+				return {
+					header: item.signature.slice(0, tupleMarkerIndex),
+					footer: item.signature.slice(tupleMarkerIndex + tupleMarker.length - 1),
+				};
+			if (item.symbolType === "class") return undefined;
+		}
+
+		const memberOffset = firstMember.range.startByte - item.range.startByte;
+		const signature = Buffer.from(item.signature);
+		if (memberOffset <= 0 || memberOffset > signature.byteLength) return undefined;
+		const header = signature.subarray(0, memberOffset).toString("utf8").trimEnd();
+		return header.endsWith("{") ? { header, footer: "}" } : undefined;
+	}
+
 	function renderOutlineFile(file: OutlineFileResult, cwd: string, includeHeader: boolean): string[] {
 		const lines = includeHeader
 			? [
@@ -136,7 +323,123 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 				`warning: parser recovered with ${file.diagnostics.errorNodes} ERROR and ${file.diagnostics.missingNodes} MISSING nodes`,
 			);
 		}
-		const declarations = file.items.filter((item) => !item.isImport);
+		const declarations = file.items.filter((item) => item.rowKind === "declaration");
+		if (
+			file.language === "typeScript" ||
+			file.language === "tsx" ||
+			file.language === "odin" ||
+			file.language === "go" ||
+			file.language === "rust" ||
+			file.language === "cSharp" ||
+			file.language === "java" ||
+			file.language === "kotlin" ||
+			file.language === "swift" ||
+			file.language === "markdown"
+		) {
+			let previousSection = "";
+			for (const item of file.items) {
+				const section =
+					item.rowKind === "package"
+						? "package"
+						: item.rowKind === "import"
+							? "imports"
+							: item.rowKind === "export"
+								? "exports"
+								: item.rowKind === "sideEffect"
+									? "side effects"
+									: "declarations";
+				if (section !== previousSection) {
+					if (lines.length > 0) lines.push("");
+					lines.push(section);
+					previousSection = section;
+				}
+				const frame = item.rowKind === "declaration" ? containerFrame(item, file.language) : undefined;
+				lines.push(
+					item.rowKind !== "declaration"
+						? renderStructuralEntry(item, "")
+						: renderEntry(item, file.path, file.language, "", frame?.header),
+				);
+				const nestedContainers = new Map(
+					file.language === "typeScript" ||
+						file.language === "tsx" ||
+						file.language === "odin" ||
+						file.language === "cSharp" ||
+						file.language === "java" ||
+						file.language === "kotlin" ||
+						file.language === "swift"
+						? [item, ...item.members]
+								.filter(
+									(entry) =>
+										entry.symbolType === "class" ||
+										entry.symbolType === "struct" ||
+										entry.symbolType === "interface" ||
+										entry.symbolType === "enum",
+								)
+								.map((entry) => [entry.qualifiedName, entry] as const)
+						: [],
+				);
+				const emittedEnumSeparators = new Set<string>();
+				const openNestedDepths: number[] = [];
+				for (const [memberIndex, member] of item.members.entries()) {
+					const depth =
+						file.language === "typeScript" ||
+						file.language === "tsx" ||
+						file.language === "odin" ||
+						file.language === "cSharp" ||
+						file.language === "java" ||
+						file.language === "kotlin" ||
+						file.language === "swift"
+							? Math.max(1, member.qualifiedName.split(".").length - item.qualifiedName.split(".").length)
+							: 1;
+					const parent = member.qualifiedName.split(".").slice(0, -1).join(".");
+					const siblings =
+						file.language === "typeScript" ||
+						file.language === "tsx" ||
+						file.language === "odin" ||
+						file.language === "cSharp" ||
+						file.language === "java" ||
+						file.language === "kotlin" ||
+						file.language === "swift"
+							? item.members.filter(
+									(candidate) => candidate.qualifiedName.split(".").slice(0, -1).join(".") === parent,
+								)
+							: [];
+					const parentIsEnum = file.language === "java" && nestedContainers.get(parent)?.symbolType === "enum";
+					while (openNestedDepths.length > 0 && (openNestedDepths.at(-1) ?? 0) >= depth) {
+						const closingDepth = openNestedDepths.pop();
+						if (closingDepth !== undefined) lines.push(`${"  ".repeat(closingDepth)}}`);
+					}
+					if (
+						parentIsEnum &&
+						!siblings.some((candidate) => candidate.symbolType === "enumMember") &&
+						!emittedEnumSeparators.has(parent)
+					) {
+						lines.push(`${"  ".repeat(depth)};`);
+						emittedEnumSeparators.add(parent);
+					}
+					let memberSignature = member.signature;
+					const nextMember = item.members[memberIndex + 1];
+					const hasDescendants = nextMember?.qualifiedName.startsWith(`${member.qualifiedName}.`) ?? false;
+					if (hasDescendants && memberSignature.endsWith(" { … }")) {
+						memberSignature = `${memberSignature.slice(0, -" { … }".length)} {`;
+						openNestedDepths.push(depth);
+					}
+					if (parentIsEnum && member.symbolType === "enumMember") {
+						const constants = siblings.filter((candidate) => candidate.symbolType === "enumMember");
+						const constantIndex = constants.indexOf(member);
+						if (constantIndex + 1 < constants.length) memberSignature += ",";
+						else if (siblings.some((candidate) => candidate.symbolType !== "enumMember")) memberSignature += ";";
+					}
+					lines.push(renderEntry(member, file.path, file.language, "  ".repeat(depth), memberSignature));
+				}
+				while (openNestedDepths.length > 0) {
+					const closingDepth = openNestedDepths.pop();
+					if (closingDepth !== undefined) lines.push(`${"  ".repeat(closingDepth)}}`);
+				}
+				if (frame) lines.push(frame.footer);
+			}
+			return lines;
+		}
 		const groups = new Map<string, typeof declarations>();
 		for (const item of declarations) {
 			const visibility = item.isExported ? "public" : "private";
@@ -167,6 +470,7 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 		promptGuidelines: [
 			"Use a public package outline first to discover reusable APIs; add exact names when likely symbols are known.",
 			"Set includePrivate when internal implementation discovery is needed.",
+			"Leave includeDocs off for routine exploration; enable it when documentation comments are needed.",
 			"Treat each parenthesized number after a line range as that declaration's symbol locator.",
 			"Use symbol with several locators when complete declaration source is needed.",
 		],
@@ -178,7 +482,13 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 				? { kind: "directory", path }
 				: { kind: "file", path, language: languageForPath(path) };
 			const names = params.names ?? [];
-			const result = await client.outline(target, params.includePrivate ?? false, names, signal);
+			const result = await client.outline(
+				target,
+				params.includePrivate ?? false,
+				params.includeDocs ?? false,
+				names,
+				signal,
+			);
 			const lines = result.files.flatMap((file, index) => [
 				...(index === 0 ? [] : [""]),
 				...renderOutlineFile(file, ctx.cwd, result.files.length > 1),
@@ -186,7 +496,10 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 			const declarationCount = result.files.reduce(
 				(count, file) =>
 					count +
-					file.items.reduce((fileCount, item) => fileCount + (item.isImport ? 0 : 1 + item.members.length), 0),
+					file.items.reduce(
+						(fileCount, item) => fileCount + (item.rowKind === "declaration" ? 1 + item.members.length : 0),
+						0,
+					),
 				0,
 			);
 			if (declarationCount === 0) lines.push(names.length > 0 ? "No matching declarations" : "No declarations");
@@ -222,14 +535,21 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 		promptSnippet: "Retrieve exact declaration source for several outline locators",
 		parameters: symbolParams,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			if (params.contextLines !== undefined && params.view !== "declaration") {
+				throw new Error("contextLines is supported only with view=declaration");
+			}
 			const records = [...new Set(params.locators)].map((id) => {
 				const record = locators.get(id);
 				if (!record) throw new Error(`Unknown symbol locator: ${id}. Run outline again.`);
 				if (record.stale) throw new Error(`Symbol locator ${id} is stale. Run outline again.`);
+				if (record.generation !== client.getGeneration()) {
+					throw new Error(`Symbol locator ${id} is stale because the AST worker restarted. Run outline again.`);
+				}
 				return record;
 			});
 			const result = await client.symbol(
 				[...new Set(records.map((record) => record.token))],
+				params.view,
 				params.contextLines ?? 0,
 				signal,
 			);
@@ -248,10 +568,7 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 					return declaration ? (requestedByToken.get(declaration.locator) ?? []) : [];
 				});
 				const range = block.returnedRange;
-				const lineRange =
-					range.start.line === range.end.line
-						? `${range.start.line + 1}`
-						: `${range.start.line + 1}-${range.end.line + 1}`;
+				const lineRange = displayLineRange(range);
 				lines.push(
 					...(includePaths ? [formatPathForDisplay(block.path, ctx.cwd)] : []),
 					`${lineRange}(${represented.map((record) => record.id).join(",")}): ${represented.map((record) => record.name).join(", ")}`,
@@ -260,6 +577,10 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 			}
 			const sourceBytes = result.blocks.reduce((count, block) => count + Buffer.byteLength(block.source), 0);
 			const output = compact(lines.join("\n"), sourceBytes, result.declarations.length, "symbol", result);
+			if (output.details.truncated) {
+				throw new Error("Symbol result exceeded the output limit. Request fewer locators.");
+			}
+			if (params.view === "declaration") for (const record of records) record.declarationRetrieved = true;
 			return { content: [{ type: "text", text: output.text }], details: output.details };
 		},
 		renderCall(args, theme, context) {
@@ -272,10 +593,10 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 					context.toolCallId,
 					"symbol",
 					targets,
-					[args.contextLines === undefined ? "" : `[context=${args.contextLines}]`],
+					[symbolOptions(args.view, args.contextLines)],
 					theme,
 				);
-			component.set(targets, [args.contextLines === undefined ? "" : `[context=${args.contextLines}]`], theme);
+			component.set(targets, [symbolOptions(args.view, args.contextLines)], theme);
 			return component;
 		},
 		renderResult(result, options, theme, context) {
@@ -300,6 +621,18 @@ export function createAstTools(client: AstClient, rowState: ToolRowStateStore) {
 	};
 }
 
+function displayLineRange(range: SourceRange): string {
+	const endLine =
+		range.endByte > range.startByte && range.end.column === 0
+			? Math.max(range.start.line, range.end.line - 1)
+			: range.end.line;
+	return range.start.line === endLine ? `${range.start.line + 1}` : `${range.start.line + 1}-${endLine + 1}`;
+}
+
+function symbolOptions(view: SymbolView, contextLines: number | undefined): string {
+	return `[${view}${contextLines === undefined ? "" : ` context=${contextLines}`}]`;
+}
+
 function renderAstResult(
 	result: { content: Array<{ type: string; text?: string }>; details?: AstToolDetails },
 	expanded: boolean,
@@ -407,7 +740,7 @@ function truncateLeft(text: string, width: number): string {
 }
 
 function outlineOptionVariants(args: OutlineArgs): string[] {
-	const fixed = args.includePrivate ? ["private"] : [];
+	const fixed = [...(args.includePrivate ? ["private"] : []), ...(args.includeDocs ? ["docs"] : [])];
 	const names = args.names ?? [];
 	if (names.length === 0) return [fixed.length > 0 ? `[${fixed.join(" ")}]` : ""];
 
@@ -485,6 +818,10 @@ function languageForPath(path: string): AstLanguage {
 			return "kotlin";
 		case ".swift":
 			return "swift";
+		case ".md":
+		case ".markdown":
+		case ".mdown":
+			return "markdown";
 		default:
 			throw new Error(`Unsupported outline file type: ${extname(path) || "no extension"}`);
 	}

package/extensions/explore/ast-worker.ts

@@ -3,7 +3,17 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-export type AstLanguage = "typeScript" | "tsx" | "odin" | "go" | "rust" | "cSharp" | "java" | "kotlin" | "swift";
+export type AstLanguage =
+	| "typeScript"
+	| "tsx"
+	| "odin"
+	| "go"
+	| "rust"
+	| "cSharp"
+	| "java"
+	| "kotlin"
+	| "swift"
+	| "markdown";
 
 export type OutlineTarget = { kind: "file"; path: string; language: AstLanguage } | { kind: "directory"; path: string };
 
@@ -23,13 +33,22 @@ export interface OutlineEntry {
 	role: "item" | "member";
 	symbolType: string;
 	name: string;
+	qualifiedName: string;
 	range: SourceRange;
+	nameRange: SourceRange;
+	receiverRange?: SourceRange;
+	bodyRange?: SourceRange;
 	signature: string;
 	astKind: string;
-	locator: string;
+	certainty: "certain" | "recovered" | "nearRecovery";
+	certaintyReason?: string;
+	locator?: string;
 }
 
+export type SymbolView = "signature" | "declaration" | "declarationWithImports";
+
 export interface OutlineItem extends OutlineEntry {
+	rowKind: "package" | "import" | "declaration" | "export" | "sideEffect";
 	isImport: boolean;
 	isExported: boolean;
 	members: Array<OutlineEntry & { isPublic: boolean }>;
@@ -73,20 +92,27 @@ export interface SymbolBatchResult {
 }
 
 export interface AstClient {
+	getGeneration(): number;
 	outline(
 		target: OutlineTarget,
 		includePrivate: boolean,
+		includeDocs: boolean,
 		names: string[],
 		signal: AbortSignal | undefined,
 	): Promise<OutlineTargetResult>;
-	symbol(locators: string[], contextLines: number, signal: AbortSignal | undefined): Promise<SymbolBatchResult>;
+	symbol(
+		locators: string[],
+		view: SymbolView,
+		contextLines: number,
+		signal: AbortSignal | undefined,
+	): Promise<SymbolBatchResult>;
 	shutdown(): Promise<void>;
 }
 
 type WorkerRequestPayload =
 	| { operation: "handshake" }
-	| { operation: "outline"; target: OutlineTarget; includePrivate: boolean; names: string[] }
-	| { operation: "symbol"; locators: string[]; contextLines: number };
+	| { operation: "outline"; target: OutlineTarget; includePrivate: boolean; includeDocs: boolean; names: string[] }
+	| { operation: "symbol"; locators: string[]; view: SymbolView; contextLines: number };
 
 interface WorkerResponse {
 	requestId: number;
@@ -102,7 +128,7 @@ interface PendingRequest {
 	removeAbortListener(): void;
 }
 
-const PROTOCOL_VERSION = 2;
+const PROTOCOL_VERSION = 5;
 const MAX_FRAME_BYTES = 8 * 1024 * 1024;
 const STDERR_BYTES = 16 * 1024;
 
@@ -142,25 +168,36 @@ export class AstWorkerClient implements AstClient {
 	private nextRequestId = 1;
 	private incoming = Buffer.alloc(0);
 	private stderr = "";
+	private generation = 0;
 
 	constructor(command: string | undefined = undefined, args: readonly string[] = []) {
 		this.command = command;
 		this.args = args;
 	}
 
+	getGeneration(): number {
+		return this.generation;
+	}
+
 	async outline(
 		target: OutlineTarget,
 		includePrivate: boolean,
+		includeDocs: boolean,
 		names: string[],
 		signal: AbortSignal | undefined,
 	): Promise<OutlineTargetResult> {
-		const result = await this.request({ operation: "outline", target, includePrivate, names }, signal);
+		const result = await this.request({ operation: "outline", target, includePrivate, includeDocs, names }, signal);
 		if (result.kind !== "outline") throw new Error("tau-ast returned the wrong result for outline");
 		return result as unknown as OutlineTargetResult;
 	}
 
-	async symbol(locators: string[], contextLines: number, signal: AbortSignal | undefined): Promise<SymbolBatchResult> {
-		const result = await this.request({ operation: "symbol", locators, contextLines }, signal);
+	async symbol(
+		locators: string[],
+		view: SymbolView,
+		contextLines: number,
+		signal: AbortSignal | undefined,
+	): Promise<SymbolBatchResult> {
+		const result = await this.request({ operation: "symbol", locators, view, contextLines }, signal);
 		if (result.kind !== "symbol") throw new Error("tau-ast returned the wrong result for symbol");
 		return result as unknown as SymbolBatchResult;
 	}
@@ -206,6 +243,7 @@ export class AstWorkerClient implements AstClient {
 			: resolveAstWorkerCommand(fileURLToPath(new URL("../../", import.meta.url)), process.platform, process.arch);
 		if ("error" in resolution) throw resolution.error;
 		const child = spawn(resolution.command, this.args, { stdio: ["pipe", "pipe", "pipe"] });
+		this.generation += 1;
 		this.child = child;
 		this.incoming = Buffer.alloc(0);
 		this.stderr = "";
@@ -302,6 +340,7 @@ export class AstWorkerClient implements AstClient {
 	private fail(child: ChildProcessWithoutNullStreams, error: Error, kill = true): void {
 		if (this.child !== child) return;
 		this.child = undefined;
+		this.generation += 1;
 		this.incoming = Buffer.alloc(0);
 		this.rejectPending(error);
 		if (kill && child.exitCode === null) child.kill();

package/extensions/subagent/session-resource.ts

@@ -118,7 +118,7 @@ export async function createSubagentSessionResource(
 		const modelRuntime = await ModelRuntime.create();
 		modelRuntime.registerNativeProvider(inputs.provider);
 		if (inputs.runtimeApiKey !== undefined)
-			await modelRuntime.setRuntimeApiKey(inputs.model.provider, inputs.runtimeApiKey);
+			await modelRuntime.setRuntimeApiKey(inputs.model.provider, inputs.runtimeApiKey, { allowNetwork: false });
 		if (signal.aborted) throw new Error(`Agent ${inputs.definition.name} startup aborted`);
 		const resourceLoader = new DefaultResourceLoader({
 			cwd: inputs.cwd,

package/extensions/tau-help/help.md

@@ -40,7 +40,7 @@ Gives the agent `context_prune` for creating a hard context checkpoint after bro
 
 ## explore
 
-Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. It also adds `outline` for public declarations in TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, and Swift files or package directories. Exact-name filters and `includePrivate` narrow or expand that surface. Parenthesized numbers identify declarations for `symbol`, which retrieves several complete declarations with optional surrounding lines and rejects stale batches. Installed packages support `outline` and `symbol` on Apple Silicon Macs without requiring Rust or Cargo; other platforms retain the rest of Explore and report the limit when an AST tool is invoked. These tools produce smaller model payloads and readable tool rows. Repeated `read` calls return unchanged markers or useful diffs when branch history proves the agent already saw the base content. A failed patch unlocks one normal reread of the affected path. `/read-stats` shows estimated token and cost savings for the current chat and whole session.
+Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. It also adds `outline` for public declarations in TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, Swift, and Markdown files or package directories. Markdown headings locate their complete sections. Exact-name filters and `includePrivate` narrow or expand that surface. Attached documentation comments are omitted by default; `includeDocs` adds them without hiding annotations or attributes. Parenthesized numbers identify declarations for `symbol`, which retrieves several complete declarations with optional surrounding lines and rejects stale batches. Installed packages support `outline` and `symbol` on Apple Silicon Macs without requiring Rust or Cargo; other platforms retain the rest of Explore and report the limit when an AST tool is invoked. These tools produce smaller model payloads and readable tool rows. Repeated `read` calls return unchanged markers or useful diffs when branch history proves the agent already saw the base content. A failed patch unlocks one normal reread of the affected path. `/read-stats` shows estimated token and cost savings for the current chat and whole session.
 
 ## footer
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.25.0",
+	"version": "0.26.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -35,7 +35,7 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.25.0",
+		"@shanepadgett/tau-tui": "0.26.0",
 		"@toon-format/toon": "2.3.0",
 		"image-size": "2.0.2",
 		"smol-toml": "1.7.0"