@shanepadgett/tau-agent 0.27.0 → 0.28.0

package/extensions/context/sync.ts

@@ -223,12 +223,4 @@ function changedCatalogPaths(before: Map<string, string>, after: Map<string, str
 }
 
 // Ensure evidence tool name stays aligned with agent definition tooling.
-export const CONTEXT_SYNC_REQUIRED_TOOLS = [
-	"read",
-	"ls",
-	"find",
-	"grep",
-	"bash",
-	"patch",
-	CONTEXT_SYNC_EVIDENCE_TOOL,
-] as const;
+export const CONTEXT_SYNC_REQUIRED_TOOLS = ["read", "bash", "patch", CONTEXT_SYNC_EVIDENCE_TOOL] as const;

package/extensions/context-pruning/prune.ts

@@ -2,8 +2,8 @@ import { resolve } from "node:path";
 import { type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import type { ContextPruneDeferredFileV2, ContextPruneDetailsV2 } from "../../shared/context-pruning-state.ts";
-import { prepareAutoreadMessage, type PreparedAutoreadMessage } from "../explore/autoread.ts";
-import { MAX_COMPLETE_FILE_SNAPSHOT_BYTES } from "../explore/full-file-knowledge.ts";
+import { prepareAutoreadMessage, type PreparedAutoreadMessage } from "../../shared/autoread.ts";
+import { MAX_COMPLETE_FILE_SNAPSHOT_BYTES } from "../../shared/full-file-knowledge.ts";
 
 export const contextPruneParameters = Type.Object(
 	{

package/extensions/explore/README.md

@@ -1,28 +1,20 @@
 # Explore
 
-Locator edit tools (`replace_declaration`, `replace_body`, `insert_declaration`, and `rename_declaration`) consume numeric declaration locators and reject stale or parser-recovered targets. They validate candidate syntax before writing, invalidate old locators, and return fresh locators after a clean reparse. For Markdown headings, `replace_declaration` replaces the complete section and `replace_body` preserves the heading while replacing its contents. Nested replacement headings must stay below the selected heading depth. Markdown insertion and rename remain unavailable. Code rename requires an explicit file or repository scope. Inferred references change only with approval; ambiguous references stay unchanged and are reported.
+Explore gives Tau 12 structural source tools: outlines, declaration slices, discovery, structural search, graph and relationship queries, impact, and context packs. Targets use path + declaration name, with an optional line to disambiguate.
 
-Explore is Tau's first-party filesystem exploration extension.
+Pi keeps ordinary filesystem tools (`ls`, `find`, `grep`, `read`). Explore adds structure on top of supported source languages via in-process tree-sitter (WASM) on every platform supported by the Node runtime. Registered languages share the same tools and exploration workflow.
 
-It exists so agents can inspect paths, discover files, search text, inspect declarations in supported source languages, and read exact source with compact model payloads and readable tool rows. For configured supported source, the official `read` tool requires a current structural attempt for that exact file fingerprint. Direct file outlines and searches qualify, along with files returned by `symbol`, `api_discover`, structural search, and relationship tools. Markdown is ungated by default. Unsupported files and unavailable workers keep the ordinary read path. Autoread establishes complete-file knowledge while that source remains in active context. Later reads can return an unchanged marker or a smaller diff instead of resending the file. A successful Tau patch can return a trusted cached complete-file diff without another structural attempt when the current branch still contains the prior complete-file baseline and the resulting fingerprint matches.
+## Large `read` / autoread
 
-When the source baseline is no longer available, such as after compaction or a cold subagent resume, `read` safely returns the current full source.
+When `explore.read.enabled` is on (default), a full Pi `read` or autoread of a registered source file (including Markdown) above `explore.read.structureThresholdLines` (default 200) returns an **outline** — declarations or headings — not the full body. Use ranged `read` (`offset`/`limit`, capped by `explore.read.maxRangeLines`) or `show` for bodies and sections. Small files and unregistered paths stay ordinary Pi full text. Set `explore.read.enabled` to `false` to turn the overlay off.
 
-Agents invoke it with `ls`, `find`, `grep`, `api_discover`, `ast_search`, `outline`, `symbol`, `references`, `callers`, `callees`, `implementations`, `tests`, and `read`. The five relationship tools expand a declaration locator across a repository or subtree. Every result reports exact source location, syntactic relationship, exact/inferred/ambiguous certainty, production/test/generated/re-export classification, declaration candidates, and a numeric locator for the nearest complete editable scope. Ambiguous results are marked non-actionable. Scans stay bounded, deterministic, ignore-aware, and cancellable. `ast_search` finds code shapes with ast-grep patterns across one supported source file, repository, package, or subtree. Directory searches require an explicit language; supported files can infer it. Results include exact previews, metavariable bindings, parser uncertainty, numeric locators for matches and enclosing scopes, complete scan counts, and explicit result or traversal limits. Output stays bounded and complete overflow is saved to the active session temporary store. `api_discover` searches declarations across a repository, package, or subtree by exact, prefix, substring, bounded fuzzy, declaration-kind, or documentation query. It filters public, private, source-exported, or package-surface declarations and reports defining files separately from caller access for TypeScript, TSX, Odin, Go, Rust, C#, Java, Kotlin, and Swift. Caller access includes the canonical module path, exact import statement, usable access expression, and resolution uncertainty; TypeScript results also include re-export chains. Candidates contain signatures without implementation bodies and numeric locators accepted by `symbol`. `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 accepts a package directory for one-level inspection, or `recursive: true` for ignore-aware mixed-language orientation of a repository or subtree. Recursive output stays bounded; when the complete outline is larger, Tau saves it to a temporary path for targeted `grep` and ranged `read` during the active session. 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 in four views: `signature` omits documentation and bodies, `signatureWithDocs` adds attached documentation without the body, `declaration` returns exact declaration source, and `declarationWithImports` adds required imports. It retrieves several locators in one call, can add bounded surrounding lines to exact declarations, and rejects the whole batch when any locator is stale. Users run `/read-stats` to see estimated token and cost savings for the session.
+## Tools
 
-Explore scans a bounded, ignore-aware slice of the working root before each agent run. When the repository contains supported source and the selected native worker is usable, Explore adds language-specific AST-first guidance to the agent prompt. Unsupported repositories and hosts get the ordinary filesystem workflow. `api_discover`, `outline`, and `symbol` stay registered either way.
-
-Installed packages support `api_discover`, `ast_search`, `outline`, `symbol`, and the relationship tools 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.
-
-For supported source, use the cheapest useful step:
-
-1. Identify the current job: locate, reuse, edit, explain, or debug. Avoid loading implementation, callers, tests, or documentation needed only later.
-2. Use a recursive `outline` to orient an unfamiliar repository or subtree. Outline a known package or file directly. Outline large Markdown files before retrieving a relevant heading section.
-3. Use `api_discover` when reuse intent is known but the declaration path or exact name is not. Prefer package surfaces and public exports before private declarations.
-4. Narrow paths, exact names, query work, and result limits once the likely target is known. Enable `includePrivate` only for targeted implementation work.
-5. Stop at a clear outline or API candidate signature. Use `symbol(signature)` for closer contract inspection, `signatureWithDocs` only when attached documentation matters, and declaration views only for exact source.
-6. Use `references`, `callers`, `callees`, `implementations`, or `tests` after selecting a change target and when the result can affect the plan. Inspect tests earlier only when the task begins with test behavior or a failure.
-7. Use `ast_search` for code shapes and `grep` for literal text. Use targeted `read` for exact formatting, comments, parser gaps, unsupported files, or source outside declaration boundaries.
-8. Prefer locator edits when a complete declaration or body is the natural edit boundary. Use textual patching when the change crosses those boundaries or depends on surrounding text.
-
-Stop when the current question is answered. Expand exploration only for a specific unresolved question.
+- `outline` — declarations and structure for a file, one-level directory, or recursive subtree (no bodies).
+- `show` — exact signature / docs / declaration / declaration+imports for path+name targets.
+- `discover` — find reusable declarations across a repo/package/subtree by name, kind, or docs (signatures only).
+- `deps` / `reverse_deps` — file import graph forward and reverse.
+- `callers` / `callees` / `references` / `implementations` — symbol relationship sites.
+- `impact` — blast radius: symbol callees/callers plus file imports/importers/transitive dependents.
+- `context` — budgeted pack of bodies/signatures around one symbol.
+- `ast_search` — structural pattern search (ast-grep) over supported source.

package/extensions/explore/ast/adapter.ts

@@ -0,0 +1,97 @@
+import type { Tree } from "web-tree-sitter";
+import type { Decl, ImportRef } from "./ir.ts";
+import type { PackageSurfaceResolver } from "./package-surface.ts";
+
+export type LanguageCapabilities = {
+	shape: boolean;
+	search: boolean;
+	fileDeps: boolean;
+	callEdges: boolean;
+	packageSurface: boolean;
+};
+
+/**
+ * Contextual pattern wrap for languages where a bare snippet parses as the wrong kind
+ * (e.g. Go `fmt.Println($A)` → type_conversion). Shared search substitutes the user
+ * pattern for `$PATTERN` and tries each wrap after the bare pattern.
+ */
+export type AstSearchPatternContext = {
+	/** Source template containing the literal placeholder `$PATTERN`. */
+	readonly context: string;
+	/** tree-sitter kind name selected from the parsed context. */
+	readonly selector: string;
+};
+
+export type ExtractResult = {
+	decls: Decl[];
+	imports: ImportRef[];
+};
+
+/** Result of adapter-owned import specifier → file resolution. */
+export type FileDepResolution =
+	| { kind: "internal"; paths: string[] }
+	| { kind: "external"; id: string }
+	| { kind: "unresolved" };
+
+/**
+ * Host services for file-dep resolution.
+ * Language-agnostic: resolvers never touch the engine type.
+ */
+export type FileDepHost = {
+	readonly cwd: string;
+	/** Scope root for this query. Resolvers must not walk above it for internal hits. */
+	readonly scopeRoot: string;
+	pathExists(path: string): Promise<boolean>;
+	isFile(path: string): Promise<boolean>;
+	/** Basenames; empty if missing or not a directory. */
+	readDir(path: string): Promise<string[]>;
+	/** True when path is a registered source file this graph should consider. */
+	ownsPath(path: string): boolean;
+	/** Session-scoped memo bag; cleared with graph invalidation. */
+	readonly memo: Map<string, unknown>;
+};
+
+export type FileDepResolver = (
+	fromPath: string,
+	specifier: string,
+	host: FileDepHost,
+	signal: AbortSignal,
+) => Promise<FileDepResolution>;
+
+/**
+ * Grammar-backed language. `id` must match a pin in `ast/grammars/manifest`.
+ * Engine owns wasm load/parse; adapter only walks the tree.
+ * Language-owned hooks (`importNoiseIdentifiers`, `resolveFileDep`, optional `resolvePackageSurface`, callEdges)
+ * stay on the adapter — tools/queries never branch on language id.
+ */
+export type GrammarAdapter = {
+	readonly mode: "grammar";
+	readonly id: string;
+	readonly extensions: readonly string[];
+	readonly capabilities: LanguageCapabilities;
+	/** Keywords/types ignored when intersecting import text with a declaration slice (`show`). */
+	readonly importNoiseIdentifiers: ReadonlySet<string>;
+	extract(tree: Tree, source: string): ExtractResult;
+	/** Required when `capabilities.fileDeps` is true. */
+	readonly resolveFileDep?: FileDepResolver;
+	readonly resolvePackageSurface?: PackageSurfaceResolver;
+	/** Optional ast_search contextual wraps; shared matcher stays language-blind. */
+	readonly patternContexts?: readonly AstSearchPatternContext[];
+};
+
+/**
+ * Source-only language (Markdown). No tree-sitter grammar.
+ * Discriminant keeps engine free of `language ===` branches.
+ */
+export type SourceAdapter = {
+	readonly mode: "source";
+	readonly id: string;
+	readonly extensions: readonly string[];
+	readonly capabilities: LanguageCapabilities;
+	readonly importNoiseIdentifiers: ReadonlySet<string>;
+	extract(source: string): ExtractResult;
+	readonly resolveFileDep?: FileDepResolver;
+	readonly resolvePackageSurface?: PackageSurfaceResolver;
+};
+
+export type LanguageAdapter = GrammarAdapter | SourceAdapter;

package/extensions/explore/ast/engine.ts

@@ -0,0 +1,470 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import {
+	initializeTreeSitter,
+	parse as astGrepParse,
+	registerDynamicLanguage,
+	type SgNode,
+	type SgRoot,
+} from "@ast-grep/wasm";
+import { Language, Parser } from "web-tree-sitter";
+import type { AdapterRegistry } from "./registry.ts";
+import { createDefaultRegistry } from "./registry.ts";
+import type { FileIr } from "./ir.ts";
+import { grammarWasmPath, loadGrammarManifest, runtimeWasmPath, type GrammarPin } from "./grammars/manifest.ts";
+import { formatPathForDisplay, pathResolutionError, resolveExplorePath } from "../traverse.ts";
+
+export type FileSource = {
+	ir: FileIr;
+	/** Decoded source text this IR's offsets index into (UTF-16 code units). */
+	source: string;
+};
+
+export type AstSearchBinding = {
+	name: string;
+	/** Exact matched text (single node or multi-node join of exact pieces). */
+	text: string;
+};
+
+export type AstSearchHit = {
+	/** 1-indexed inclusive. */
+	startLine: number;
+	endLine: number;
+	/** Exact match preview (edit-grade). */
+	text: string;
+	bindings: AstSearchBinding[];
+};
+
+export type ExploreEngine = {
+	/** Absolute session cwd — path resolution and directory scans use this. */
+	readonly cwd: string;
+	readonly registry: AdapterRegistry;
+	/** Resolve path, read bytes, return cached or freshly extracted FileIr. */
+	irForFile(path: string): Promise<FileIr>;
+	/** One read: IR (cached when hash matches) plus the decoded source for slicing. */
+	sourceForFile(path: string): Promise<FileSource>;
+	/**
+	 * Structural pattern search over one source string.
+	 * Engine owns @ast-grep/wasm init + grammar registration from pinned wasm paths.
+	 * Does not use the IR cache; does not cache match results.
+	 */
+	searchInSource(languageId: string, source: string, pattern: string): Promise<AstSearchHit[]>;
+	invalidate(paths: readonly string[]): void;
+	clear(): void;
+	/**
+	 * Drop IR cache and delete the retained Parser.
+	 * Loaded Language modules are dropped from JS maps; web-tree-sitter 0.26 has no Language.delete().
+	 */
+	shutdown(): void;
+};
+
+export type ExploreEngineOptions = {
+	cwd: string;
+	registry?: AdapterRegistry;
+};
+
+type CacheEntry = {
+	contentHash: string;
+	ir: FileIr;
+};
+
+function contentHashOf(bytes: Uint8Array): string {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+
+function lineCountOf(source: string): number {
+	if (source.length === 0) return 0;
+	let count = 1;
+	for (let i = 0; i < source.length; i += 1) {
+		const code = source.charCodeAt(i);
+		if (code === 10) count += 1;
+		else if (code === 13) {
+			count += 1;
+			if (source.charCodeAt(i + 1) === 10) i += 1;
+		}
+	}
+	return count;
+}
+
+function pinById(id: string): GrammarPin {
+	const pin = loadGrammarManifest().grammars.find((entry) => entry.id === id);
+	if (pin === undefined) {
+		throw new Error(`No grammar artifact for language: ${id}`);
+	}
+	return pin;
+}
+
+/** ast-grep metavars: `$NAME` one node, `$$$NAME` sibling sequence. Skip `$_`. */
+function metaVarNames(pattern: string): { singles: string[]; multis: string[] } {
+	const singles: string[] = [];
+	const multis: string[] = [];
+	let i = 0;
+	while (i < pattern.length) {
+		if (pattern[i] !== "$") {
+			i += 1;
+			continue;
+		}
+		let dollars = 0;
+		while (i < pattern.length && pattern[i] === "$") {
+			dollars += 1;
+			i += 1;
+		}
+		let name = "";
+		while (i < pattern.length) {
+			const c = pattern[i];
+			if (c === undefined) break;
+			const isAlpha = (c >= "A" && c <= "Z") || c === "_";
+			const isAlnum = isAlpha || (c >= "0" && c <= "9");
+			if ((name.length === 0 && isAlpha) || (name.length > 0 && isAlnum)) {
+				name += c;
+				i += 1;
+				continue;
+			}
+			break;
+		}
+		if (name.length === 0 || name === "_") continue;
+		if (dollars >= 3) {
+			if (!multis.includes(name)) multis.push(name);
+		} else if (dollars === 1) {
+			if (!singles.includes(name)) singles.push(name);
+		}
+	}
+	return { singles, multis };
+}
+
+function hitKey(hit: AstSearchHit): string {
+	return `${hit.startLine}:${hit.endLine}:${hit.text}`;
+}
+
+/** @ast-grep/wasm Pos.index is Unicode scalar offset, not UTF-16. */
+function sliceByCharOffset(source: string, startChar: number, endChar: number): string {
+	let start = 0;
+	let end = source.length;
+	let charIndex = 0;
+	for (let i = 0; i < source.length;) {
+		if (charIndex === startChar) start = i;
+		const code = source.charCodeAt(i);
+		const step = code >= 0xd800 && code <= 0xdbff ? 2 : 1;
+		i += step;
+		charIndex += 1;
+		if (charIndex === endChar) {
+			end = i;
+			break;
+		}
+	}
+	if (charIndex < endChar) end = source.length;
+	return source.slice(start, end);
+}
+
+function bindingsFromNode(node: SgNode, pattern: string, source: string): AstSearchBinding[] {
+	const { singles, multis } = metaVarNames(pattern);
+	const out: AstSearchBinding[] = [];
+	for (const name of singles) {
+		const match = node.getMatch(name);
+		if (match !== undefined) out.push({ name, text: match.text() });
+	}
+	for (const name of multis) {
+		const parts = node.getMultipleMatches(name);
+		if (parts.length === 0) continue;
+		const first = parts[0];
+		const last = parts[parts.length - 1];
+		if (first === undefined || last === undefined) continue;
+		const start = first.range().start.index;
+		const end = last.range().end.index;
+		out.push({ name, text: sliceByCharOffset(source, start, end) });
+	}
+	return out;
+}
+
+function nodeToHit(node: SgNode, pattern: string, source: string): AstSearchHit {
+	const range = node.range();
+	return {
+		startLine: range.start.line + 1,
+		endLine: range.end.line + 1,
+		text: node.text(),
+		bindings: bindingsFromNode(node, pattern, source),
+	};
+}
+
+function collectHits(
+	root: SgRoot,
+	matcher: unknown,
+	pattern: string,
+	source: string,
+	into: Map<string, AstSearchHit>,
+): void {
+	const nodes = root.root().findAll(matcher);
+	for (const node of nodes) {
+		const hit = nodeToHit(node, pattern, source);
+		const key = hitKey(hit);
+		if (!into.has(key)) into.set(key, hit);
+	}
+}
+
+/**
+ * In-process web-tree-sitter host.
+ * Parse → extract plain FileIr → tree.delete() immediately. Cache IR only.
+ * All IR offsets are UTF-16 code units into the decoded source string.
+ * Only this module resolves wasm paths via the grammar manifest.
+ * ast_search uses @ast-grep/wasm on the same pinned grammar paths (decision 11-A).
+ */
+export function createExploreEngine(options: ExploreEngineOptions): ExploreEngine {
+	const cwd = resolve(options.cwd);
+	const registry = options.registry ?? createDefaultRegistry();
+	const irCache = new Map<string, CacheEntry>();
+	const languages = new Map<string, Language>();
+	const languageLoads = new Map<string, Promise<Language>>();
+	const searchLangReady = new Set<string>();
+
+	let initPromise: Promise<void> | undefined;
+	let searchInitPromise: Promise<void> | undefined;
+	let parser: Parser | undefined;
+	let shutDown = false;
+
+	const assertLive = (): void => {
+		if (shutDown) {
+			throw new Error("Explore engine has been shut down");
+		}
+	};
+
+	const ensureReady = async (): Promise<Parser> => {
+		assertLive();
+		if (parser !== undefined) return parser;
+		if (initPromise === undefined) {
+			initPromise = Parser.init({ locateFile: () => runtimeWasmPath() }).then(() => {
+				if (shutDown) return;
+				parser = new Parser();
+			});
+		}
+		await initPromise;
+		assertLive();
+		if (parser === undefined) throw new Error("Explore engine failed to initialize parser");
+		return parser;
+	};
+
+	const ensureSearchReady = async (): Promise<void> => {
+		assertLive();
+		// IR path init first so locateFile pins web-tree-sitter.wasm for the process.
+		await ensureReady();
+		if (searchInitPromise === undefined) {
+			searchInitPromise = initializeTreeSitter();
+		}
+		await searchInitPromise;
+		assertLive();
+	};
+
+	const ensureSearchLanguage = async (languageId: string): Promise<void> => {
+		assertLive();
+		if (searchLangReady.has(languageId)) return;
+		const adapter = registry.adapterForId(languageId);
+		if (adapter === undefined) {
+			throw new Error(`Unregistered language: ${languageId}`);
+		}
+		if (adapter.mode !== "grammar" || !adapter.capabilities.search) {
+			throw new Error(`Language does not support structural search: ${languageId}`);
+		}
+		await ensureSearchReady();
+		assertLive();
+		await registerDynamicLanguage({
+			[languageId]: {
+				libraryPath: grammarWasmPath(pinById(languageId)),
+				expandoChar: "µ",
+			},
+		});
+		assertLive();
+		searchLangReady.add(languageId);
+	};
+
+	const loadLanguage = async (languageId: string): Promise<Language> => {
+		assertLive();
+		const cached = languages.get(languageId);
+		if (cached !== undefined) return cached;
+
+		let pending = languageLoads.get(languageId);
+		if (pending === undefined) {
+			pending = Language.load(grammarWasmPath(pinById(languageId))).then(
+				(language) => {
+					languageLoads.delete(languageId);
+					if (!shutDown) {
+						languages.set(languageId, language);
+					}
+					return language;
+				},
+				(error: unknown) => {
+					languageLoads.delete(languageId);
+					throw error;
+				},
+			);
+			languageLoads.set(languageId, pending);
+		}
+
+		const language = await pending;
+		assertLive();
+		return language;
+	};
+
+	const buildIr = async (absolutePath: string, source: string, hash: string): Promise<FileIr> => {
+		const adapter = registry.adapterForPath(absolutePath);
+		if (adapter === undefined) {
+			throw new Error(`Unsupported language for path: ${formatPathForDisplay(absolutePath, cwd)}`);
+		}
+		const lineCount = lineCountOf(source);
+
+		if (adapter.mode === "source") {
+			const extracted = adapter.extract(source);
+			return {
+				path: absolutePath,
+				contentHash: hash,
+				languageId: adapter.id,
+				lineCount,
+				decls: extracted.decls,
+				imports: extracted.imports,
+				parseDegraded: false,
+			};
+		}
+
+		const activeParser = await ensureReady();
+		const language = await loadLanguage(adapter.id);
+		assertLive();
+		activeParser.setLanguage(language);
+		activeParser.reset();
+		const tree = activeParser.parse(source);
+		if (tree === null) {
+			throw new Error(`Parse failed for ${formatPathForDisplay(absolutePath, cwd)}`);
+		}
+		try {
+			const extracted = adapter.extract(tree, source);
+			return {
+				path: absolutePath,
+				contentHash: hash,
+				languageId: adapter.id,
+				lineCount,
+				decls: extracted.decls,
+				imports: extracted.imports,
+				parseDegraded: tree.rootNode.hasError,
+			};
+		} finally {
+			tree.delete();
+		}
+	};
+
+	const loadSource = async (path: string): Promise<FileSource> => {
+		assertLive();
+		const absolutePath = resolveExplorePath(cwd, path);
+		let bytes: Buffer;
+		try {
+			bytes = await readFile(absolutePath);
+		} catch (error) {
+			throw pathResolutionError(error, path);
+		}
+		assertLive();
+		const hash = contentHashOf(bytes);
+		const source = bytes.toString("utf8");
+		const cached = irCache.get(absolutePath);
+		if (cached !== undefined && cached.contentHash === hash) {
+			return { ir: cached.ir, source };
+		}
+		const ir = await buildIr(absolutePath, source, hash);
+		assertLive();
+		irCache.set(absolutePath, { contentHash: hash, ir });
+		return { ir, source };
+	};
+
+	return {
+		cwd,
+		registry,
+
+		async irForFile(path: string): Promise<FileIr> {
+			const source = await loadSource(path);
+			return source.ir;
+		},
+
+		async sourceForFile(path: string): Promise<FileSource> {
+			return loadSource(path);
+		},
+
+		async searchInSource(languageId: string, source: string, pattern: string): Promise<AstSearchHit[]> {
+			assertLive();
+			const adapter = registry.adapterForId(languageId);
+			if (adapter === undefined) {
+				throw new Error(`Unregistered language: ${languageId}`);
+			}
+			if (adapter.mode !== "grammar" || !adapter.capabilities.search) {
+				throw new Error(`Language does not support structural search: ${languageId}`);
+			}
+			await ensureSearchLanguage(languageId);
+			assertLive();
+
+			let root: SgRoot;
+			try {
+				root = astGrepParse(languageId, source);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				throw new Error(`Parse failed for structural search (${languageId}): ${message}`);
+			}
+
+			try {
+				const byKey = new Map<string, AstSearchHit>();
+				const matchers: unknown[] = [pattern];
+				const contexts = adapter.patternContexts ?? [];
+				for (const wrap of contexts) {
+					if (!wrap.context.includes("$PATTERN")) continue;
+					matchers.push({
+						rule: {
+							pattern: {
+								context: wrap.context.split("$PATTERN").join(pattern),
+								selector: wrap.selector,
+							},
+						},
+					});
+				}
+
+				let anyMatcherOk = false;
+				let lastError: string | undefined;
+				for (const matcher of matchers) {
+					try {
+						collectHits(root, matcher, pattern, source, byKey);
+						anyMatcherOk = true;
+					} catch (error) {
+						lastError = error instanceof Error ? error.message : String(error);
+					}
+				}
+				if (!anyMatcherOk) {
+					throw new Error(`Invalid pattern: ${lastError ?? "unknown pattern error"}`);
+				}
+
+				return [...byKey.values()].sort((a, b) => {
+					if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+					if (a.endLine !== b.endLine) return a.endLine - b.endLine;
+					return a.text.localeCompare(b.text);
+				});
+			} finally {
+				root.free();
+			}
+		},
+
+		invalidate(paths: readonly string[]): void {
+			for (const path of paths) {
+				irCache.delete(resolveExplorePath(cwd, path));
+			}
+		},
+
+		clear(): void {
+			irCache.clear();
+		},
+
+		shutdown(): void {
+			if (shutDown) return;
+			shutDown = true;
+			irCache.clear();
+			languages.clear();
+			languageLoads.clear();
+			searchLangReady.clear();
+			parser?.delete();
+			parser = undefined;
+			initPromise = undefined;
+			searchInitPromise = undefined;
+		},
+	};
+}