@shanepadgett/tau-agent 0.26.0 → 0.28.0

package/extensions/explore/ast/tools/discover.ts

@@ -0,0 +1,208 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import type { DeclKind } from "../ir.ts";
+import {
+	formatDiscoverEmpty,
+	formatDiscoverFile,
+	formatDiscoverFooters,
+	groupDiscoverByFile,
+} from "../format/discover.ts";
+import { discover, type DiscoverQuery, type DiscoverSurface } from "../queries/discover.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, shrinkingListVariants, type ExploreToolDetails } from "./render.ts";
+
+const declarationKinds = [
+	"module",
+	"namespace",
+	"package",
+	"class",
+	"method",
+	"property",
+	"field",
+	"constructor",
+	"enum",
+	"interface",
+	"type",
+	"typeAlias",
+	"function",
+	"variable",
+	"constant",
+	"object",
+	"enumMember",
+	"struct",
+	"event",
+	"operator",
+	"typeParameter",
+	"heading",
+] as const satisfies readonly DeclKind[];
+
+const discoverParams = Type.Object(
+	{
+		path: Type.String({ description: "Repository, package, or subtree directory" }),
+		query: Type.Union([
+			Type.Object(
+				{ kind: Type.Literal("exactName"), name: Type.String({ minLength: 1 }) },
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{ kind: Type.Literal("prefixName"), name: Type.String({ minLength: 1 }) },
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{ kind: Type.Literal("substringName"), name: Type.String({ minLength: 1 }) },
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{
+					kind: Type.Literal("fuzzyName"),
+					name: Type.String({ minLength: 1 }),
+					maxCandidates: Type.Integer({ minimum: 1, maximum: 10_000 }),
+					maxWork: Type.Integer({ minimum: 1, maximum: 1_000_000 }),
+				},
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{
+					kind: Type.Literal("declarationKind"),
+					declarationKind: StringEnum(declarationKinds),
+				},
+				{ additionalProperties: false },
+			),
+			Type.Object(
+				{
+					kind: Type.Literal("documentation"),
+					terms: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+					maxCandidates: Type.Integer({ minimum: 1, maximum: 10_000 }),
+					maxWork: Type.Integer({ minimum: 1, maximum: 1_000_000 }),
+				},
+				{ additionalProperties: false },
+			),
+		]),
+		surface: StringEnum(["all", "public", "private", "sourceExport", "packageSurface"] as const, {
+			description: "Declaration or export surface to search",
+		}),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100 }),
+	},
+	{ additionalProperties: false },
+);
+
+type DiscoverParams = Static<typeof discoverParams>;
+
+type DiscoverExecuteResult = {
+	content: Array<{ type: "text"; text: string }>;
+	details: ExploreToolDetails;
+};
+
+function formatQueryLabel(query: DiscoverParams["query"]): string {
+	switch (query.kind) {
+		case "exactName":
+		case "prefixName":
+		case "substringName":
+		case "fuzzyName":
+			return `${query.kind}=${query.name}`;
+		case "declarationKind":
+			return `kind=${query.declarationKind}`;
+		case "documentation":
+			return `docs=${query.terms.join(",")}`;
+	}
+}
+
+function discoverOptionVariants(params: DiscoverParams): string[] {
+	const query = params.query;
+	const queryLabels =
+		query === undefined
+			? ["query"]
+			: query.kind === "documentation"
+				? shrinkingListVariants(query.terms, `${query.terms.length} terms`).map((part) => `docs=${part}`)
+				: [formatQueryLabel(query)];
+	const surface = params.surface ?? "surface";
+	const limit = params.resultLimit === undefined ? "limit" : `limit=${params.resultLimit}`;
+	return queryLabels.map((label) => `[${label} ${surface} ${limit}]`);
+}
+
+export function createDiscoverTool(
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	engineFor: (cwd: string) => ExploreEngine,
+) {
+	return defineTool<typeof discoverParams, ExploreToolDetails>({
+		name: "discover",
+		label: "discover",
+		description:
+			"Find reusable declarations across a repository, package, or subtree by name, kind, or documentation. Signatures only — no bodies. Prefer package/public surfaces when looking for imports.",
+		promptSnippet: "Find reusable declarations across a repo/package/subtree when path is unknown",
+		promptGuidelines: [
+			"Use discover when reuse intent is known but the declaration path or exact name is not.",
+			"Choose exactly one query kind. Keep fuzzy or documentation work limits narrow.",
+			"Use packageSurface when the caller needs a supported public import path (languages with packageSurface capability).",
+			"Follow up with show using path+name(+line) when a candidate needs closer inspection.",
+		],
+		parameters: discoverParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const abort = signal ?? new AbortController().signal;
+			const result = await discover(
+				engine,
+				params.path,
+				params.query as DiscoverQuery,
+				params.surface as DiscoverSurface,
+				params.resultLimit,
+				abort,
+			);
+
+			const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+			try {
+				const groups = groupDiscoverByFile(result.candidates);
+				for (const group of groups) {
+					abort.throwIfAborted();
+					await builder.appendBlock(
+						group.path,
+						formatPathForDisplay(group.path, engine.cwd),
+						formatDiscoverFile(group.path, group.candidates, engine.cwd),
+					);
+				}
+				if (groups.length === 0) {
+					await builder.appendBlock(undefined, "empty", formatDiscoverEmpty());
+				}
+				const footer = formatDiscoverFooters(result);
+				if (footer !== undefined) {
+					abort.throwIfAborted();
+					await builder.appendRequiredBlock("discover limits", footer);
+				}
+				const bounded = await builder.finish();
+				return {
+					content: [{ type: "text", text: bounded.content }],
+					details: {
+						declarationCount: result.candidates.length,
+						returnedBytes: Buffer.byteLength(bounded.content),
+						truncated: bounded.overflow.truncated,
+					},
+				} satisfies DiscoverExecuteResult;
+			} catch (error) {
+				await builder.abort();
+				throw error;
+			}
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const targets = [stripLeadingAt(args.path ?? "")];
+			const options = discoverOptionVariants(args);
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "discover", targets, options, theme);
+			component.targetVariants = targets;
+			component.optionVariants = options;
+			component.theme = theme;
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderExploreResult(result, options.expanded, theme, context);
+		},
+	});
+}

package/extensions/explore/ast/tools/impact.ts

@@ -0,0 +1,135 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatImpactResult, impactSectionBlocks } from "../format/impact.ts";
+import type { ExploreFileGraph } from "../graph/file-graph.ts";
+import { IMPACT_DEPTH_DEFAULT, IMPACT_DEPTH_MAX, queryImpact, type ImpactMode } from "../queries/impact.ts";
+import { stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+
+const impactParams = Type.Object(
+	{
+		path: Type.String({ description: "Directory scope (repo/package/subtree)" }),
+		targetPath: Type.Optional(Type.String({ description: "Defining file when known" })),
+		name: Type.String({ minLength: 1, description: "Declaration name; may be dotted (Type.method)" }),
+		line: Type.Optional(Type.Integer({ minimum: 1, description: "1-indexed line to pin one candidate" })),
+		depth: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				maximum: IMPACT_DEPTH_MAX,
+				description: `File-transitive reverse depth (default ${IMPACT_DEPTH_DEFAULT}, max ${IMPACT_DEPTH_MAX}). Symbol hops are always 1.`,
+			}),
+		),
+		mode: Type.Optional(
+			StringEnum(["all", "deps", "dependents"] as const, {
+				description: "all = both sides; deps = callees+imports; dependents = callers+importers+transitive",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export function createImpactTool(
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return defineTool<typeof impactParams, ExploreToolDetails>({
+		name: "impact",
+		label: "impact",
+		description:
+			"One-call blast radius for a symbol: callees, callers, file imports, file importers, transitive file dependents. Narrow path scope. depth is file-transitive only.",
+		promptSnippet: "Blast radius before a non-trivial edit",
+		promptGuidelines: [
+			"Use before a non-trivial edit to see symbol and nearby file dependents.",
+			"Narrow path scope — whole-repo impact is not the goal.",
+			"depth applies only to reverse file dependents (not multi-hop symbol callers).",
+			"mode=deps for outbound only; mode=dependents for inbound only.",
+			"Callable and type targets only.",
+		],
+		parameters: impactParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const graph = graphFor(ctx.cwd);
+			const abort = signal ?? new AbortController().signal;
+			const depth = params.depth ?? IMPACT_DEPTH_DEFAULT;
+			const mode = (params.mode ?? "all") as ImpactMode;
+			const result = await queryImpact({
+				engine,
+				graph,
+				scopePath: params.path,
+				targetPath: params.targetPath,
+				name: params.name,
+				line: params.line,
+				depth,
+				mode,
+				signal: abort,
+			});
+
+			if (result.kind !== "resolved") {
+				const text = formatImpactResult(result, engine.cwd);
+				return {
+					content: [{ type: "text", text }],
+					details: {
+						declarationCount: 0,
+						returnedBytes: Buffer.byteLength(text),
+						truncated: false,
+					},
+				};
+			}
+
+			const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+			try {
+				const blocks = impactSectionBlocks(result, engine.cwd);
+				let count = 0;
+				for (const block of blocks) {
+					abort.throwIfAborted();
+					if (block.id === "footer") {
+						await builder.appendRequiredBlock(block.label, block.text);
+					} else {
+						await builder.appendBlock(block.id, block.label, block.text);
+					}
+					count += 1;
+				}
+				const bounded = await builder.finish();
+				return {
+					content: [{ type: "text", text: bounded.content }],
+					details: {
+						declarationCount: count,
+						returnedBytes: Buffer.byteLength(bounded.content),
+						truncated: bounded.overflow.truncated,
+					},
+				};
+			} catch (error) {
+				await builder.abort();
+				throw error;
+			}
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const name = args.name ?? "?";
+			const scope = stripLeadingAt(args.path ?? "");
+			const pin = args.targetPath !== undefined ? stripLeadingAt(args.targetPath) : "";
+			const targets = pin.length > 0 ? [`${name} @ ${pin}`] : [name];
+			const depth = args.depth ?? IMPACT_DEPTH_DEFAULT;
+			const mode = args.mode ?? "all";
+			const options = [`[scope=${scope} depth=${depth} mode=${mode}]`];
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "impact", targets, options, theme);
+			component.targetVariants = targets;
+			component.optionVariants = options;
+			component.theme = theme;
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderExploreResult(result, options.expanded, theme, context);
+		},
+	});
+}

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

@@ -0,0 +1,200 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
+import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatOutlineBudgetFooter, formatOutlineEmpty, formatOutlineFile } from "../format/outline.ts";
+import { outlinePath, outlineRecursive, type OutlineFileView, type OutlineOptions } from "../queries/outline.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, shrinkingListVariants, type ExploreToolDetails } from "./render.ts";
+
+const outlineParams = Type.Object(
+	{
+		path: Type.String({
+			description: "Supported source file, package directory, or subtree",
+		}),
+		includePrivate: Type.Optional(
+			Type.Boolean({ description: "Include private declarations and members (default false)" }),
+		),
+		includeDocs: Type.Optional(
+			Type.Boolean({ description: "Include attached documentation comments (default false)" }),
+		),
+		names: Type.Optional(
+			Type.Array(Type.String({ minLength: 1 }), {
+				minItems: 1,
+				description: "Exact declaration name or qualifiedName filters",
+			}),
+		),
+		recursive: Type.Optional(
+			Type.Boolean({ description: "Recursively outline every supported source file below a directory" }),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+type OutlineParams = Static<typeof outlineParams>;
+
+type OutlineExecuteResult = {
+	content: Array<{ type: "text"; text: string }>;
+	details: ExploreToolDetails;
+};
+
+function outlineOptions(params: OutlineParams): OutlineOptions {
+	return {
+		includePrivate: params.includePrivate === true,
+		includeDocs: params.includeDocs === true,
+		names: params.names ?? [],
+	};
+}
+
+function outlineOptionVariants(params: OutlineParams): string[] {
+	const fixed = [
+		...(params.recursive === true ? ["recursive"] : []),
+		...(params.includePrivate === true ? ["private"] : []),
+		...(params.includeDocs === true ? ["docs"] : []),
+	];
+	const names = params.names ?? [];
+	if (names.length === 0) return [fixed.length > 0 ? `[${fixed.join(" ")}]` : ""];
+	return shrinkingListVariants(names, String(names.length)).map(
+		(part) => `[${[...fixed, `names=${part}`].join(" ")}]`,
+	);
+}
+
+function emptyMessage(file: OutlineFileView, names: readonly string[]): string {
+	const base = formatOutlineEmpty(names);
+	if (!file.parseDegraded) return base;
+	return `warning: parser recovered with errors\n${base}`;
+}
+
+async function withBoundedOutline(
+	temporaryOutput: TemporaryOutputStore,
+	signal: AbortSignal,
+	run: (builder: BoundedTextResultBuilder) => Promise<number>,
+): Promise<OutlineExecuteResult> {
+	const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+	try {
+		const declarationCount = await run(builder);
+		signal.throwIfAborted();
+		const bounded = await builder.finish();
+		return {
+			content: [{ type: "text", text: bounded.content }],
+			details: {
+				declarationCount,
+				returnedBytes: Buffer.byteLength(bounded.content),
+				truncated: bounded.overflow.truncated,
+			},
+		};
+	} catch (error) {
+		await builder.abort();
+		throw error;
+	}
+}
+
+export function createOutlineTool(
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	engineFor: (cwd: string) => ExploreEngine,
+) {
+	return defineTool<typeof outlineParams, ExploreToolDetails>({
+		name: "outline",
+		label: "outline",
+		description:
+			"Inspect declarations in one supported source file, one non-recursive package directory, or a recursive mixed-language subtree without returning implementation bodies. Line ranges support follow-up show or ranged read.",
+		promptSnippet: "Inspect declarations and structure without reading implementation bodies",
+		promptGuidelines: [
+			"Set recursive=true to orient an unfamiliar repository or subtree across supported languages.",
+			"Leave includePrivate off for surface discovery; enable it only for targeted internal implementation work.",
+			"Leave includeDocs off when names and signatures answer the question; enable it only when documentation comments matter.",
+			"Use show with path+name (and optional line) when exact signature or declaration source is needed.",
+		],
+		parameters: outlineParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const options = outlineOptions(params);
+			const abort = signal ?? new AbortController().signal;
+
+			if (params.recursive === true) {
+				return withBoundedOutline(temporaryOutput, abort, async (builder) => {
+					let declarationCount = 0;
+					let emitted = 0;
+					const stream = outlineRecursive(engine, params.path, options, abort);
+					let step = await stream.next();
+					while (!step.done) {
+						abort.throwIfAborted();
+						const file = step.value;
+						declarationCount += file.rows.length;
+						emitted += 1;
+						await builder.appendBlock(
+							file.path,
+							formatPathForDisplay(file.path, engine.cwd),
+							formatOutlineFile(file, engine.cwd, true),
+						);
+						step = await stream.next();
+					}
+					if (emitted === 0) {
+						await builder.appendBlock(undefined, "empty", formatOutlineEmpty(options.names));
+					}
+					const footer = formatOutlineBudgetFooter(step.value);
+					if (footer !== undefined) {
+						abort.throwIfAborted();
+						await builder.appendRequiredBlock("outline limits", footer);
+					}
+					return declarationCount;
+				});
+			}
+
+			const result = await outlinePath(engine, params.path, options, abort);
+
+			if (result.mode === "file") {
+				const text =
+					result.file.rows.length === 0
+						? emptyMessage(result.file, options.names)
+						: formatOutlineFile(result.file, engine.cwd, false);
+				return withBoundedOutline(temporaryOutput, abort, async (builder) => {
+					abort.throwIfAborted();
+					await builder.appendBlock(result.file.path, formatPathForDisplay(result.file.path, engine.cwd), text);
+					return result.file.rows.length;
+				});
+			}
+
+			if (result.files.length === 0) {
+				return withBoundedOutline(temporaryOutput, abort, async (builder) => {
+					abort.throwIfAborted();
+					await builder.appendBlock(undefined, "empty", formatOutlineEmpty(options.names));
+					return 0;
+				});
+			}
+
+			return withBoundedOutline(temporaryOutput, abort, async (builder) => {
+				let declarationCount = 0;
+				for (const file of result.files) {
+					abort.throwIfAborted();
+					declarationCount += file.rows.length;
+					await builder.appendBlock(
+						file.path,
+						formatPathForDisplay(file.path, engine.cwd),
+						formatOutlineFile(file, engine.cwd, true),
+					);
+				}
+				return declarationCount;
+			});
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const targets = [stripLeadingAt(args.path ?? "")];
+			const options = outlineOptionVariants(args);
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "outline", targets, options, theme);
+			component.targetVariants = targets;
+			component.optionVariants = options;
+			component.theme = theme;
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderExploreResult(result, options.expanded, theme, context);
+		},
+	});
+}