@shanepadgett/tau-agent 0.27.0 → 0.28.0

package/extensions/explore/index.ts

@@ -1,113 +1,103 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolve } from "node:path";
-import { emitTauEvent, onTauEvent } from "../../shared/events.js";
-import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
+import { onTauEvent } from "../../shared/events.ts";
 import { createTemporaryOutputStore } from "../../shared/temporary-output-store.ts";
-import { createToolRowStateStore } from "../../shared/tool-row-state.js";
-import { AST_DISCOVERY_BUDGET, effectiveAstGuidance } from "./ast-guidance.ts";
-import { createAstTools } from "./ast-tools.ts";
-import { AstWorkerClient } from "./ast-worker.ts";
-import { registerAutoread } from "./autoread.ts";
-import { createFindTool } from "./find.ts";
-import { createGrepTool } from "./grep.ts";
-import { createLsTool } from "./ls.ts";
-import { createOrientationState } from "./orientation-state.ts";
-import { createReadCacheStore } from "./read-cache.ts";
-import { createReadSnapshotStore } from "./read-snapshots.ts";
-import { showReadStats } from "./read-stats.ts";
-import { createExploreReadTool } from "./read.ts";
-import exploreSettings from "./settings.ts";
+import { createToolRowStateStore } from "../../shared/tool-row-state.ts";
+import { createExploreEngine, type ExploreEngine } from "./ast/engine.ts";
+import { createFileGraph, type ExploreFileGraph } from "./ast/graph/file-graph.ts";
+import { registerReadOutlineHook } from "./ast/read/hook.ts";
+import { createAstSearchTool } from "./ast/tools/ast-search.ts";
+import { createContextTool } from "./ast/tools/context.ts";
+import { createDepsTool } from "./ast/tools/deps.ts";
+import { createDiscoverTool } from "./ast/tools/discover.ts";
+import { createImpactTool } from "./ast/tools/impact.ts";
+import { createOutlineTool } from "./ast/tools/outline.ts";
+import {
+	createCalleesTool,
+	createCallersTool,
+	createImplementationsTool,
+	createReferencesTool,
+} from "./ast/tools/relationships.ts";
+import { createReverseDepsTool } from "./ast/tools/reverse-deps.ts";
+import { createShowTool } from "./ast/tools/show.ts";
+import { registerExploreGuidance } from "./guidance.ts";
+import { registerExploreAutoread } from "./read/autoread.ts";
 
 export default function exploreExtension(pi: ExtensionAPI): void {
-	let settings = exploreSettings.defaults;
 	const rowState = createToolRowStateStore(pi, "explore.tool-row-state");
-	const readCache = createReadCacheStore();
-	const readSnapshots = createReadSnapshotStore();
-	const astClient = new AstWorkerClient();
-	const orientation = createOrientationState(() => astClient.supportedLanguages());
 	const temporaryOutput = createTemporaryOutputStore();
-	const ast = createAstTools(astClient, rowState, temporaryOutput, orientation, (toolCallId, cwd, summary) => {
-		emitTauEvent(pi, "tau:file-mutation.applied", {
-			source: "locatorEdit",
-			toolCallId,
-			cwd,
-			status: summary.status,
-			changes: summary.changes.map((change) => ({
-				path: change.path,
-				kind: change.kind,
-				move: change.move,
-				linesAdded: change.linesAdded,
-				linesRemoved: change.linesRemoved,
-				resultingFingerprint: change.resultingFingerprint,
-				snapshotRanges: change.snapshotRanges,
-			})),
-		});
-	});
-	registerAutoread(pi, rowState);
-	pi.registerTool(ast.outline);
-	pi.registerTool(ast.symbol);
-	pi.registerTool(ast.replace_declaration);
-	pi.registerTool(ast.replace_body);
-	pi.registerTool(ast.insert_declaration);
-	pi.registerTool(ast.rename_declaration);
-	pi.registerTool(ast.api_discover);
-	pi.registerTool(ast.ast_search);
-	pi.registerTool(ast.references);
-	pi.registerTool(ast.callers);
-	pi.registerTool(ast.callees);
-	pi.registerTool(ast.implementations);
-	pi.registerTool(ast.tests);
-	pi.registerTool(createLsTool(rowState));
-	pi.registerTool(createFindTool(rowState));
-	pi.registerTool(createGrepTool(rowState));
-	pi.registerTool(createExploreReadTool(rowState, orientation, readCache, readSnapshots, () => settings.readGate));
-	pi.on("before_agent_start", async (event, ctx) => {
-		const guidance = await effectiveAstGuidance({
-			cwd: ctx.cwd,
-			workerLanguages: () => astClient.supportedLanguages(),
-			discoveryBudget: AST_DISCOVERY_BUDGET,
-		});
-		return guidance ? { systemPrompt: `${event.systemPrompt}\n\n${guidance}` } : undefined;
-	});
-	pi.registerCommand("read-stats", {
-		description: "Show estimated read token and cost savings for this session",
-		async handler(_args, ctx) {
-			if (ctx.mode !== "tui") {
-				ctx.ui.notify("Read stats require TUI mode", "error");
-				return;
-			}
-			await showReadStats(ctx, orientation);
-		},
-	});
+	let engine: ExploreEngine | undefined;
+	let graph: ExploreFileGraph | undefined;
+
+	const engineFor = (cwd: string): ExploreEngine => {
+		const absoluteCwd = resolve(cwd);
+		if (engine !== undefined && engine.cwd === absoluteCwd) return engine;
+		engine?.shutdown();
+		graph?.clear();
+		engine = createExploreEngine({ cwd: absoluteCwd });
+		graph = createFileGraph(engine);
+		return engine;
+	};
+
+	const graphFor = (cwd: string): ExploreFileGraph => {
+		engineFor(cwd);
+		if (graph === undefined) {
+			throw new Error("Explore file graph failed to initialize");
+		}
+		return graph;
+	};
+
+	pi.registerTool(createOutlineTool(rowState, temporaryOutput, engineFor));
+	pi.registerTool(createShowTool(rowState, engineFor));
+	pi.registerTool(createDiscoverTool(rowState, temporaryOutput, engineFor));
+	pi.registerTool(createAstSearchTool(rowState, temporaryOutput, engineFor));
+	pi.registerTool(createDepsTool(rowState, engineFor, graphFor));
+	pi.registerTool(createReverseDepsTool(rowState, engineFor, graphFor));
+	pi.registerTool(createCallersTool(rowState, engineFor, graphFor));
+	pi.registerTool(createCalleesTool(rowState, engineFor, graphFor));
+	pi.registerTool(createReferencesTool(rowState, engineFor, graphFor));
+	pi.registerTool(createImplementationsTool(rowState, engineFor, graphFor));
+	pi.registerTool(createImpactTool(rowState, temporaryOutput, engineFor, graphFor));
+	pi.registerTool(createContextTool(rowState, temporaryOutput, engineFor, graphFor));
+	registerReadOutlineHook(pi, engineFor);
+	registerExploreAutoread(pi, rowState, engineFor);
+	registerExploreGuidance(pi, engineFor);
+
 	pi.on("session_start", async (_event, ctx) => {
-		settings = await loadTauExtensionSettings(ctx, exploreSettings);
 		await temporaryOutput.shutdown();
 		await temporaryOutput.start();
 		rowState.clear();
-		readSnapshots.clear();
-		ast.clear();
+		engine?.shutdown();
+		graph?.clear();
+		engine = createExploreEngine({ cwd: ctx.cwd });
+		graph = createFileGraph(engine);
 	});
+
 	onTauEvent(pi, "explore.ast", "tau:file-mutation.applied", (event) => {
-		const paths = event.changes.flatMap((change) => [
-			resolve(event.cwd, change.path),
-			...(change.move ? [resolve(event.cwd, change.move.from), resolve(event.cwd, change.move.to)] : []),
-		]);
-		ast.invalidate(paths);
-		orientation.recordPatched(
-			event.changes.map((change) => ({
-				path: resolve(event.cwd, change.path),
-				resultingFingerprint: change.resultingFingerprint,
-			})),
+		if (engine === undefined) return;
+		const paths = event.changes.flatMap((change) => {
+			const main = resolve(event.cwd, change.path);
+			if (change.move === undefined) return [main];
+			return [main, resolve(event.cwd, change.move.from), resolve(event.cwd, change.move.to)];
+		});
+		engine.invalidate(paths);
+		const topologyChanged = event.changes.some(
+			(change) => change.kind === "add" || change.kind === "delete" || change.move !== undefined,
 		);
+		if (topologyChanged) graph?.clear();
+		else graph?.invalidate(paths);
 	});
-	pi.on("session_compact", () => readSnapshots.clear());
+
 	pi.on("session_tree", () => {
-		readSnapshots.clear();
-		ast.resetForTree();
+		engine?.clear();
+		graph?.clear();
 	});
+
 	pi.on("session_shutdown", async () => {
-		ast.clear();
-		await astClient.shutdown();
+		engine?.shutdown();
+		engine = undefined;
+		graph?.clear();
+		graph = undefined;
 		await temporaryOutput.shutdown();
 	});
 }

package/extensions/explore/read/autoread.ts

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { prepareAutoreadMessage, registerAutoread, type PreparedAutoreadMessage } from "../../../shared/autoread.ts";
+import { createCompleteFileMeta } from "../../../shared/full-file-knowledge.ts";
+import { loadTauExtensionSettings } from "../../../shared/settings/load.ts";
+import type { ToolRowStateStore } from "../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../ast/engine.ts";
+import { formatOutlineFile } from "../ast/format/outline.ts";
+import { formatLargeReadOutline, shouldOutlineFullRead, type ExploreReadSettings } from "../ast/read/policy.ts";
+import { outlinePath } from "../ast/queries/outline.ts";
+import exploreSettings from "../settings.ts";
+import { resolveExplorePath } from "../traverse.ts";
+
+const DEFAULT_OUTLINE_OPTIONS = {
+	includePrivate: false,
+	includeDocs: false,
+	names: [] as readonly string[],
+};
+
+export function registerExploreAutoread(
+	pi: ExtensionAPI,
+	rowState: ToolRowStateStore,
+	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;
+	});
+
+	registerAutoread(pi, rowState, async (options) => {
+		return prepareExploreAutoreadMessage({
+			...options,
+			engine: engineFor(options.cwd),
+			readSettings,
+		});
+	});
+}
+
+async function prepareExploreAutoreadMessage(options: {
+	rowId: string;
+	path: string;
+	cwd: string;
+	source: string;
+	batchId: string;
+	signal: AbortSignal | undefined;
+	isLifecycleCurrent: () => boolean;
+	maximumBytes?: number;
+	engine: ExploreEngine;
+	readSettings: ExploreReadSettings;
+}): Promise<PreparedAutoreadMessage> {
+	const { engine, readSettings, ...shared } = options;
+	if (!readSettings.enabled) return prepareAutoreadMessage(shared);
+
+	const absolutePath = resolveExplorePath(options.cwd, options.path);
+	if (engine.registry.adapterForPath(absolutePath) === undefined) {
+		return prepareAutoreadMessage(shared);
+	}
+
+	assertPreparationCurrent(options.signal, options.isLifecycleCurrent);
+
+	let lineCount: number;
+	try {
+		const source = await engine.sourceForFile(absolutePath);
+		lineCount = source.ir.lineCount;
+	} catch {
+		return prepareAutoreadMessage(shared);
+	}
+
+	if (!shouldOutlineFullRead(lineCount, readSettings.structureThresholdLines)) {
+		return prepareAutoreadMessage(shared);
+	}
+
+	const abort = options.signal ?? new AbortController().signal;
+	const result = await outlinePath(engine, options.path, DEFAULT_OUTLINE_OPTIONS, abort);
+	assertPreparationCurrent(options.signal, options.isLifecycleCurrent);
+	if (result.mode !== "file") {
+		return prepareAutoreadMessage(shared);
+	}
+
+	const outlineBody =
+		result.file.rows.length === 0 ? "No declarations" : formatOutlineFile(result.file, engine.cwd, false);
+	const outlineText = formatLargeReadOutline(outlineBody);
+	const messageContent = `${options.path}\n${outlineText}`;
+	const pathKey = resolve(options.cwd, options.path);
+	const readCache = createCompleteFileMeta({
+		pathKey,
+		presentation: "plain",
+		servedHash: createHash("sha256").update(outlineText, "utf8").digest("hex"),
+		mode: "baseline",
+		sourceText: outlineText,
+		returnedText: messageContent,
+		totalLines: lineCount,
+		summary: `outline (${lineCount} lines)`,
+	});
+
+	return {
+		customType: "tau.autoread",
+		content: messageContent,
+		display: true,
+		details: {
+			rowId: options.rowId,
+			path: options.path,
+			cwd: options.cwd,
+			source: options.source,
+			batchId: options.batchId,
+			status: "read",
+			readCache,
+		},
+	};
+}
+
+function assertPreparationCurrent(signal: AbortSignal | undefined, isLifecycleCurrent: () => boolean): void {
+	signal?.throwIfAborted();
+	if (!isLifecycleCurrent()) throw new Error("Autoread preparation crossed a session lifecycle boundary");
+}

package/extensions/explore/settings.ts

@@ -1,46 +1,64 @@
-import { relative, resolve } from "node:path";
 import { Type } from "typebox";
-import { matchGlob, posixPath } from "../../shared/glob.ts";
 import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
 
-export interface ExploreReadGateSettings {
-	includeGlobs: string[];
-	excludeGlobs: string[];
-}
-
 export default defineTauExtensionSettings({
 	key: "explore",
 	defaults: {
-		readGate: {
-			includeGlobs: ["**/*"] as string[],
-			excludeGlobs: ["**/*.md", "**/*.markdown", "**/*.mdown"] as string[],
+		context: {
+			defaultBudgetTokens: 8000 as number,
+		},
+		read: {
+			enabled: true as boolean,
+			structureThresholdLines: 200 as number,
+			maxRangeLines: 200 as number,
 		},
 	},
 	schema: Type.Object(
 		{
-			readGate: Type.Object(
-				{
-					includeGlobs: Type.Array(Type.String(), {
-						default: ["**/*"],
-						description:
-							"Working-directory-relative supported source paths that require a structural attempt before read.",
-					}),
-					excludeGlobs: Type.Array(Type.String(), {
-						default: ["**/*.md", "**/*.markdown", "**/*.mdown"],
-						description: "Working-directory-relative paths excluded from the Explore read gate. Exclusions win.",
-					}),
-				},
-				{ additionalProperties: false },
+			context: Type.Optional(
+				Type.Object(
+					{
+						defaultBudgetTokens: Type.Optional(
+							Type.Integer({
+								default: 8000,
+								minimum: 1,
+								description: "Default token budget for context when the caller omits budget.",
+							}),
+						),
+					},
+					{ additionalProperties: false },
+				),
+			),
+			read: Type.Optional(
+				Type.Object(
+					{
+						enabled: Type.Optional(
+							Type.Boolean({
+								default: true,
+								description:
+									"Master switch for Explore structural read overlay and large-source autoread outline path. When false, Pi read and autoread keep ordinary full bodies.",
+							}),
+						),
+						structureThresholdLines: Type.Optional(
+							Type.Integer({
+								default: 200,
+								minimum: 1,
+								description:
+									"Registered source at or under this line count may be full-read. Above it, full read model-visible result is outline only.",
+							}),
+						),
+						maxRangeLines: Type.Optional(
+							Type.Integer({
+								default: 200,
+								minimum: 1,
+								description: "Maximum lines returned by one ranged read on registered source.",
+							}),
+						),
+					},
+					{ additionalProperties: false },
+				),
 			),
 		},
 		{ additionalProperties: false },
 	),
 });
-
-export function matchesExploreReadGate(path: string, cwd: string, settings: ExploreReadGateSettings): boolean {
-	const projectPath = posixPath(relative(resolve(cwd), resolve(path)));
-	return (
-		settings.includeGlobs.some((pattern) => matchGlob(pattern, projectPath)) &&
-		!settings.excludeGlobs.some((pattern) => matchGlob(pattern, projectPath))
-	);
-}