@shanepadgett/tau-agent 0.26.0 → 0.28.0

package/extensions/explore/ast/registry.ts

@@ -0,0 +1,120 @@
+import { extname } from "node:path";
+import type { LanguageAdapter, LanguageCapabilities } from "./adapter.ts";
+import { csharpAdapter } from "./languages/csharp.ts";
+import { goAdapter } from "./languages/go.ts";
+import { javaAdapter } from "./languages/java.ts";
+import { kotlinAdapter } from "./languages/kotlin.ts";
+import { odinAdapter } from "./languages/odin.ts";
+import { rustAdapter } from "./languages/rust.ts";
+import { swiftAdapter } from "./languages/swift.ts";
+import { tsxAdapter, typescriptAdapter } from "./languages/typescript.ts";
+import { extractMarkdown } from "./markdown.ts";
+import type { PackageSurfaceResolver } from "./package-surface.ts";
+
+export type LanguageAdvertisement = {
+	id: string;
+	extensions: readonly string[];
+	capabilities: LanguageCapabilities;
+};
+
+export type AdapterRegistry = {
+	register(adapter: LanguageAdapter): void;
+	adapterForPath(path: string): LanguageAdapter | undefined;
+	adapterForId(languageId: string): LanguageAdapter | undefined;
+	registeredLanguages(): LanguageAdvertisement[];
+	/** Deduped package-surface resolvers from adapters that declare the capability. */
+	packageSurfaceResolvers(): readonly PackageSurfaceResolver[];
+};
+
+const MARKDOWN_EXTENSIONS = [".md", ".markdown", ".mdown"] as const;
+
+const MARKDOWN_CAPABILITIES: LanguageCapabilities = {
+	shape: true,
+	search: false,
+	fileDeps: false,
+	callEdges: false,
+	packageSurface: false,
+};
+
+function markdownAdapter(): LanguageAdapter {
+	return {
+		mode: "source",
+		id: "markdown",
+		extensions: MARKDOWN_EXTENSIONS,
+		capabilities: MARKDOWN_CAPABILITIES,
+		importNoiseIdentifiers: new Set(),
+		extract: extractMarkdown,
+	};
+}
+
+function createRegistry(seed: readonly LanguageAdapter[] = []): AdapterRegistry {
+	const byId = new Map<string, LanguageAdapter>();
+	const byExtension = new Map<string, LanguageAdapter>();
+
+	const register = (adapter: LanguageAdapter): void => {
+		if (byId.has(adapter.id)) {
+			throw new Error(`Language adapter already registered: ${adapter.id}`);
+		}
+		for (const ext of adapter.extensions) {
+			const key = ext.toLowerCase();
+			if (!key.startsWith(".")) {
+				throw new Error(`Language adapter ${adapter.id}: extension must start with '.': ${ext}`);
+			}
+			const existing = byExtension.get(key);
+			if (existing !== undefined) {
+				throw new Error(`Extension ${key} already registered by ${existing.id}; cannot register ${adapter.id}`);
+			}
+		}
+		byId.set(adapter.id, adapter);
+		for (const ext of adapter.extensions) {
+			byExtension.set(ext.toLowerCase(), adapter);
+		}
+	};
+
+	for (const adapter of seed) register(adapter);
+
+	return {
+		register,
+		adapterForPath(path: string): LanguageAdapter | undefined {
+			return byExtension.get(extname(path).toLowerCase());
+		},
+		adapterForId(languageId: string): LanguageAdapter | undefined {
+			return byId.get(languageId);
+		},
+		registeredLanguages(): LanguageAdvertisement[] {
+			return [...byId.values()].map((adapter) => ({
+				id: adapter.id,
+				extensions: adapter.extensions,
+				capabilities: adapter.capabilities,
+			}));
+		},
+		packageSurfaceResolvers(): readonly PackageSurfaceResolver[] {
+			const out: PackageSurfaceResolver[] = [];
+			const seen = new Set<PackageSurfaceResolver>();
+			for (const adapter of byId.values()) {
+				if (!adapter.capabilities.packageSurface) continue;
+				const resolver = adapter.resolvePackageSurface;
+				if (resolver === undefined || seen.has(resolver)) continue;
+				seen.add(resolver);
+				out.push(resolver);
+			}
+			return out;
+		},
+	};
+}
+
+/** Session registry: Markdown + grammar adapters. */
+export function createDefaultRegistry(): AdapterRegistry {
+	return createRegistry([
+		markdownAdapter(),
+		typescriptAdapter(),
+		tsxAdapter(),
+		goAdapter(),
+		rustAdapter(),
+		csharpAdapter(),
+		javaAdapter(),
+		kotlinAdapter(),
+		swiftAdapter(),
+		odinAdapter(),
+	]);
+}

package/extensions/explore/ast/scan.ts

@@ -0,0 +1,76 @@
+import type { ExploreEngine, FileSource } from "./engine.ts";
+import { DEFAULT_TRAVERSAL_BUDGETS, type TraversalBudgets, type TraversalLimit, walkPaths } from "../traverse.ts";
+
+export type ScanOptions = {
+	engine: ExploreEngine;
+	cwd: string;
+	root: string;
+	budgets?: Partial<TraversalBudgets>;
+	signal?: AbortSignal;
+	includeHidden?: boolean;
+	includeIgnored?: boolean;
+	includeNoise?: boolean;
+};
+
+/** Structured stop reason — not prose. */
+export type ScanOutcome = {
+	limit: TraversalLimit | undefined;
+	filesVisited: number;
+	sourceBytes: number;
+	elapsedMs: number;
+	/** Files that produced IR (registered language only). */
+	filesEmitted: number;
+};
+
+/**
+ * Budgeted ignore-aware multi-file IR+bytes production.
+ * Yields one FileSource per supported file; cooperative macrotask between files.
+ * Generator return value is the structured outcome (limit / counters).
+ */
+export async function* scanSources(options: ScanOptions): AsyncGenerator<FileSource, ScanOutcome> {
+	const started = Date.now();
+	const maxElapsedMs = options.budgets?.maxElapsedMs ?? DEFAULT_TRAVERSAL_BUDGETS.maxElapsedMs;
+	let filesEmitted = 0;
+
+	const walk = await walkPaths({
+		cwd: options.cwd,
+		root: options.root,
+		filesOnly: true,
+		includeHidden: options.includeHidden,
+		includeIgnored: options.includeIgnored,
+		includeNoise: options.includeNoise,
+		budgets: options.budgets,
+		signal: options.signal,
+		// Budgets count parseable files only — skip binaries/unregistered extensions.
+		matchFile: (hit) => options.engine.registry.adapterForPath(hit.absolutePath) !== undefined,
+	});
+
+	const elapsed = () => Date.now() - started;
+
+	const finish = (limit: TraversalLimit | undefined): ScanOutcome => ({
+		limit: limit ?? walk.limit,
+		filesVisited: walk.filesVisited,
+		sourceBytes: walk.sourceBytes,
+		elapsedMs: elapsed(),
+		filesEmitted,
+	});
+
+	for (const hit of walk.entries) {
+		if (options.signal?.aborted) return finish("cancelled");
+		if (elapsed() >= maxElapsedMs) return finish("maxElapsedMs");
+
+		const source = await options.engine.sourceForFile(hit.absolutePath);
+
+		// Do not emit work that finished after cancel/budget crossed during sourceForFile.
+		if (options.signal?.aborted) return finish("cancelled");
+		if (elapsed() >= maxElapsedMs) return finish("maxElapsedMs");
+
+		filesEmitted += 1;
+		yield source;
+		await new Promise<void>((resolve) => {
+			setImmediate(resolve);
+		});
+	}
+
+	return finish(walk.limit);
+}

package/extensions/explore/ast/slice.ts

@@ -0,0 +1,31 @@
+import type { Decl } from "./ir.ts";
+
+// All offsets are UTF-16 code units into the decoded source string (ir.ts).
+
+/** Decl signature: [startOffset, signatureEndOffset) — no docs, no body. */
+export function signatureText(decl: Decl, source: string): string {
+	return source.slice(decl.startOffset, decl.signatureEndOffset);
+}
+
+/** Attached doc comment text, or undefined when none. */
+export function docsText(decl: Decl, source: string): string | undefined {
+	if (decl.docStartOffset === undefined || decl.docEndOffset === undefined) return undefined;
+	const text = source.slice(decl.docStartOffset, decl.docEndOffset);
+	return text.length === 0 ? undefined : text;
+}
+
+/** Full declaration span [startOffset, endOffset) — no leading docs. */
+export function declarationText(decl: Decl, source: string): string {
+	return source.slice(decl.startOffset, decl.endOffset);
+}
+
+/**
+ * Docs (if any) + signature, joined as in source when docs sit immediately above.
+ * When docs exist, uses [docStartOffset, signatureEndOffset); else signature only.
+ */
+export function signatureWithDocsText(decl: Decl, source: string): string {
+	if (decl.docStartOffset === undefined || decl.docEndOffset === undefined) {
+		return signatureText(decl, source);
+	}
+	return source.slice(decl.docStartOffset, decl.signatureEndOffset);
+}

package/extensions/explore/ast/tools/ast-search.ts

@@ -0,0 +1,138 @@
+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 {
+	formatAstSearchEmpty,
+	formatAstSearchFile,
+	formatAstSearchFooters,
+	groupAstSearchByFile,
+} from "../format/ast-search.ts";
+import { astSearch } from "../queries/ast-search.ts";
+import { formatPathForDisplay, stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+
+const PATTERN_MAX_BYTES = 16 * 1024;
+
+const astSearchParams = Type.Object(
+	{
+		path: Type.String({ description: "File or directory to search" }),
+		pattern: Type.String({
+			minLength: 1,
+			maxLength: PATTERN_MAX_BYTES,
+			description:
+				"ast-grep pattern (e.g. 'console.log($ARG)', 'foo($$$ARGS)', 'if ($COND) { $$$BODY }'). $NAME binds one node; $$$NAME binds a sibling sequence.",
+		}),
+		language: Type.Optional(
+			Type.String({
+				description:
+					"Engine-registered language id (typescript, tsx, go, rust, c_sharp, java, kotlin, swift, odin). Required for directories; must match file extension when both given.",
+			}),
+		),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100 }),
+	},
+	{ additionalProperties: false },
+);
+
+type AstSearchParams = Static<typeof astSearchParams>;
+
+type AstSearchExecuteResult = {
+	content: Array<{ type: "text"; text: string }>;
+	details: ExploreToolDetails;
+};
+
+function optionVariants(params: AstSearchParams): string[] {
+	const lang = params.language !== undefined && params.language.length > 0 ? params.language : "lang?";
+	const limit = params.resultLimit === undefined ? "limit" : `limit=${params.resultLimit}`;
+	const pattern =
+		params.pattern === undefined
+			? "pattern"
+			: params.pattern.length > 24
+				? `${params.pattern.slice(0, 21)}...`
+				: params.pattern;
+	return [`[${lang} ${limit} ${pattern}]`];
+}
+
+export function createAstSearchTool(
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	engineFor: (cwd: string) => ExploreEngine,
+) {
+	return defineTool<typeof astSearchParams, ExploreToolDetails>({
+		name: "ast_search",
+		label: "ast_search",
+		description:
+			"Find code shapes with ast-grep patterns in one file or a tree. Use $NAME for one node and $$$NAME for sibling sequences (e.g. console.log($ARG), foo($$$ARGS)). Search only — no writes. Prefer over grep when structure matters.",
+		promptSnippet: "Structural pattern search with ast-grep metavariables",
+		promptGuidelines: [
+			"Use ast_search for code shapes; harness grep for literal text.",
+			"Pass language for directory targets (required). On a file, language is optional when the extension maps to a registered search language.",
+			"Patterns follow ast-grep rules: $NAME one node, $$$NAME sequence, $_ anonymous. Keep resultLimit tight.",
+			"No rewrite/write path — edits go through harness patch/edit/write.",
+		],
+		parameters: astSearchParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const abort = signal ?? new AbortController().signal;
+			const result = await astSearch(
+				engine,
+				params.path,
+				params.pattern,
+				params.language,
+				params.resultLimit,
+				abort,
+			);
+
+			const builder = new BoundedTextResultBuilder(temporaryOutput, "completeBlocks");
+			try {
+				const groups = groupAstSearchByFile(result.matches);
+				for (const group of groups) {
+					abort.throwIfAborted();
+					await builder.appendBlock(
+						group.path,
+						formatPathForDisplay(group.path, engine.cwd),
+						formatAstSearchFile(group.path, group.matches, engine.cwd),
+					);
+				}
+				if (groups.length === 0) {
+					await builder.appendBlock(undefined, "empty", formatAstSearchEmpty());
+				}
+				const footer = formatAstSearchFooters(result, engine.cwd);
+				if (footer !== undefined) {
+					abort.throwIfAborted();
+					await builder.appendRequiredBlock("ast_search limits", footer);
+				}
+				const bounded = await builder.finish();
+				return {
+					content: [{ type: "text", text: bounded.content }],
+					details: {
+						declarationCount: result.matches.length,
+						returnedBytes: Buffer.byteLength(bounded.content),
+						truncated: bounded.overflow.truncated,
+					},
+				} satisfies AstSearchExecuteResult;
+			} catch (error) {
+				await builder.abort();
+				throw error;
+			}
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const targets = [stripLeadingAt(args.path ?? "")];
+			const options = optionVariants(args);
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "ast_search", 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/context.ts

@@ -0,0 +1,126 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { BoundedTextResultBuilder } from "../../../../shared/bounded-text-result.ts";
+import { loadTauExtensionSettings } from "../../../../shared/settings/load.ts";
+import type { TemporaryOutputStore } from "../../../../shared/temporary-output-store.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import exploreSettings from "../../settings.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { contextSectionBlocks, formatContextResult } from "../format/context.ts";
+import type { ExploreFileGraph } from "../graph/file-graph.ts";
+import { queryContext } from "../queries/context.ts";
+import { stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+
+const contextParams = 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" })),
+		budget: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				description: "Token pack budget (default from explore.context.defaultBudgetTokens)",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export function createContextTool(
+	rowState: ToolRowStateStore,
+	temporaryOutput: TemporaryOutputStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return defineTool<typeof contextParams, ExploreToolDetails>({
+		name: "context",
+		label: "context",
+		description:
+			"Budgeted pack to understand one symbol in one call: target body, nearby callees/callers or type members/implementors. Raise budget if truncated. Use impact for full blast radius.",
+		promptSnippet: "Budgeted read pack for one symbol",
+		promptGuidelines: [
+			"Use when you need bodies/signatures around one symbol under a token budget.",
+			"Raise budget if entries are signature-only or truncated.",
+			"Use impact for full dependents list; context is a sample pack.",
+			"Callable and type targets only.",
+		],
+		parameters: contextParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const graph = graphFor(ctx.cwd);
+			const abort = signal ?? new AbortController().signal;
+			const settings = await loadTauExtensionSettings(ctx, exploreSettings);
+			const budget = params.budget ?? settings.context.defaultBudgetTokens;
+			const result = await queryContext({
+				engine,
+				graph,
+				scopePath: params.path,
+				targetPath: params.targetPath,
+				name: params.name,
+				line: params.line,
+				budget,
+				signal: abort,
+			});
+
+			if (result.kind !== "resolved") {
+				const text = formatContextResult(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 = contextSectionBlocks(result, engine.cwd);
+				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);
+					}
+				}
+				const bounded = await builder.finish();
+				const declarationCount = result.groups.reduce((sum, group) => sum + group.entries.length, 0);
+				return {
+					content: [{ type: "text", text: bounded.content }],
+					details: {
+						declarationCount,
+						returnedBytes: Buffer.byteLength(bounded.content),
+						truncated: bounded.overflow.truncated || result.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 budget = args.budget === undefined ? "budget=default" : `budget=${args.budget}`;
+			const options = [`[scope=${scope} ${budget}]`];
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "context", 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/deps.ts

@@ -0,0 +1,72 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { truncateBoundedHead } from "../../../../shared/bounded-text-result.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatDepsEmpty, formatDepsResult } from "../format/deps.ts";
+import type { ExploreFileGraph } from "../graph/file-graph.ts";
+import { stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+
+const depsParams = Type.Object(
+	{
+		path: Type.String({ description: "Source file" }),
+		depth: Type.Optional(Type.Integer({ minimum: 1, description: "Traversal depth (default 1)" })),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max dependent entries to return" }),
+	},
+	{ additionalProperties: false },
+);
+
+export function createDepsTool(
+	rowState: ToolRowStateStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return defineTool<typeof depsParams, ExploreToolDetails>({
+		name: "deps",
+		label: "deps",
+		description:
+			"File-level: what this file imports/depends on. Depth > 1 walks the internal import graph (BFS). External packages are listed last.",
+		promptSnippet: "List file imports and dependencies",
+		promptGuidelines: [
+			"Use for file-level dependency orientation, not symbol callees.",
+			"Increase depth only when transitive internal imports matter.",
+			"Tighten resultLimit when output is large.",
+		],
+		parameters: depsParams,
+		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 ?? 1;
+			const result = await graph.deps(params.path, depth, params.resultLimit, abort);
+			const text = formatDepsResult(result, engine.cwd, formatDepsEmpty());
+			const bounded = truncateBoundedHead(text);
+			return {
+				content: [{ type: "text", text: bounded.content }],
+				details: {
+					declarationCount: result.hits.length,
+					returnedBytes: Buffer.byteLength(bounded.content),
+					truncated: bounded.truncated,
+				},
+			};
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const targets = [stripLeadingAt(args.path ?? "")];
+			const depth = args.depth ?? 1;
+			const options = [`[depth=${depth} limit=${args.resultLimit ?? "?"}]`];
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "deps", 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);
+		},
+	});
+}