@aeonsparx/pi-unreal 0.0.0-stage → 1.0.0

package/extensions/unreal/lib/pi-tools.ts

@@ -0,0 +1,402 @@
+/**
+ * Pi tool wrappers for the compiler-free UE source index.
+ *
+ * Four tools, one idea: an agent asking "where is X" gets one line, not 176 files of grep output.
+ * Nothing here needs clangd, clang, Visual Studio, or Rider — the data is (a) a definition scan of
+ * `.h`/`.cpp` text and (b) `UnrealBuildTool -Mode=Query` output for compile facts.
+ *
+ * Cost discipline is the design constraint: project/plugin indexes build in seconds and are built on
+ * demand; an Engine/Source index scans tens of thousands of files, so `unreal_index` is the only tool
+ * that pays for it. A lookup that wants engine sources reports the cost and how to pay it — it never
+ * stalls the agent.
+ */
+
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+import { normalizePath, realFs, truncateLines, type JsonValue } from "./util.ts";
+import { buildContext, compileDbReport, fileContext, indexBuild, indexStatus, symbolList, symbolLookup, type Scope } from "./tools.ts";
+
+/* ──────────────────────────────────────────────────────────────────────────── schemas */
+
+const ScopeSchema = Type.Optional(
+	Type.Union([Type.Literal("project"), Type.Literal("engine"), Type.Literal("all")], {
+		description: "Which sources to search. 'project' (default) = the project's modules plus its enabled plugins. 'engine' = Engine/Source. 'all' = both.",
+	}),
+);
+const EngineAreasSchema = Type.Optional(
+	Type.Array(Type.String(), {
+			// Must match DEFAULT_ENGINE_AREAS in lib/store.ts — the schema description is what agents read.
+		description: 'Engine/Source sub-areas for engine-scope work, e.g. ["Runtime"] or ["Runtime/Core","Runtime/CoreUObject"]. Default: ["Runtime"] (DEFAULT_ENGINE_AREAS in lib/store.ts); "Editor" and "Developer" are opt-in and roughly triple the scan.',
+	}),
+);
+const LimitSchema = Type.Optional(Type.Number({ description: "Maximum rows to return. Default 25." }));
+const TargetSchema = Type.Optional(Type.String({ description: "UBT target whose compile environment to report, e.g. 'LpEditor', 'UnrealEditor'. Default: the project's editor target." }));
+const PlatformSchema = Type.Optional(Type.String({ description: "Target platform. Default: this machine's platform (Win64 on Windows)." }));
+const ConfigurationSchema = Type.Optional(Type.String({ description: "Target configuration: Development (default), DebugGame, Shipping." }));
+
+/** Every tool takes the workspace directory; the session cwd is the default so agents rarely pass it. */
+const CwdSchema = Type.Optional(Type.String({ description: "Workspace directory containing the .uproject. Default: the session cwd." }));
+
+const SymbolParams = Type.Object({
+	cwd: CwdSchema,
+	query: Type.String({ description: "Symbol name: 'AActor', 'UAnimInstance', 'AActor:Tick' (qualified), or a bare method name together with 'owner'." }),
+	owner: Type.Optional(Type.String({ description: "Owner type for a member lookup: query 'Tick' + owner 'AActor'. A bare method name is resolved through its owner." })),
+	scope: ScopeSchema,
+	engineAreas: EngineAreasSchema,
+	module: Type.Optional(Type.String({ description: "Restrict hits to one module, e.g. 'Engine'." })),
+	prefix: Type.Optional(Type.Boolean({ description: "Allow prefix matching (name families, typos). Default false: exact + qualified-member only." })),
+	limit: LimitSchema,
+});
+
+const ListParams = Type.Object({
+	cwd: CwdSchema,
+	prefix: Type.String({ description: "Symbol-name prefix, e.g. 'ULp' or 'ANiMy'." }),
+	scope: ScopeSchema,
+	engineAreas: EngineAreasSchema,
+	kind: Type.Optional(
+		Type.Union([Type.Literal("class"), Type.Literal("struct"), Type.Literal("enum"), Type.Literal("union"), Type.Literal("function"), Type.Literal("delegate"), Type.Literal("property"), Type.Literal("alias")], {
+			description: "Filter by definition kind.",
+		}),
+	),
+	module: Type.Optional(Type.String({ description: "Restrict hits to one module." })),
+	limit: Type.Optional(Type.Number({ description: "Maximum names to return. Default 40." })),
+});
+
+const ContextParams = Type.Object({
+	cwd: CwdSchema,
+	file: Type.Optional(Type.String({ description: "Source file to describe (.h/.cpp in the project, a plugin, or Engine/Source): its module, declarations, include paths, defines file." })),
+	module: Type.Optional(Type.String({ description: "Module to describe instead of a file, e.g. 'GameplayAbilities' — dependency lists, include paths, defines file, standard, SDK." })),
+	target: TargetSchema,
+	platform: PlatformSchema,
+	configuration: ConfigurationSchema,
+	includeDefines: Type.Optional(Type.Boolean({ description: "Also read the module's preprocessor define list. Needs the UBT Query cache (~7s the first time). Default false." })),
+	engineAreas: EngineAreasSchema,
+	refresh: Type.Optional(Type.Boolean({ description: "Re-run UnrealBuildTool Query instead of using the cached JSON." })),
+	limit: LimitSchema,
+});
+
+const IndexParams = Type.Object({
+	cwd: CwdSchema,
+	action: Type.Union([Type.Literal("build"), Type.Literal("status"), Type.Literal("compiledb")], { description: "'build' creates or refreshes an index. 'status' lists what is cached and what building will cost. 'compiledb' runs UnrealBuildTool -Mode=GenerateClangDatabase and normalizes it for clangd (minutes, ~1 GB for the engine scope)." }),
+	scope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("engine"), Type.Literal("project+engine")], { description: "Index scope for 'build': 'project' (default, seconds) or 'engine' (minutes the first time). For 'compiledb': 'project' (default) = project + enabled plugin sources, 'project+engine' adds all of Engine/Source." })),
+	mode: Type.Optional(Type.Union([Type.Literal("definitions"), Type.Literal("full")], { description: "'definitions' = symbol -> file:line only (default, fast). 'full' also records per-file include sets and needs UnrealBuildTool Query (~7s, no compiler)." })),
+	engineAreas: EngineAreasSchema,
+	target: TargetSchema,
+	platform: PlatformSchema,
+	configuration: ConfigurationSchema,
+	refresh: Type.Optional(Type.Boolean({ description: "Force a rebuild, and re-run UnrealBuildTool Query in 'full' mode. Default false." })),
+});
+
+/* ──────────────────────────────────────────────────────────────────────────── rendering */
+
+const jsonOf = (value: unknown): JsonValue => JSON.parse(JSON.stringify(value ?? null)) as JsonValue;
+
+const shortPath = (file: string | undefined, cwd: string) => {
+	if (!file) return "?";
+	const f = normalizePath(file);
+	const base = normalizePath(cwd);
+	return f.startsWith(`${base}/`) ? f.slice(base.length + 1) : f;
+};
+
+const rowLine = (row: { symbol: string; kind: string; file: string; line: number; module: string; scope?: string }, cwd: string) =>
+	`  ${row.kind} ${row.symbol}  ${shortPath(row.file, cwd)}:${row.line}  [${row.module}${row.scope ? ` · ${row.scope}` : ""}]`;
+
+function result(text: string, details: unknown, isError = false) {
+	return {
+		content: [{ type: "text" as const, text: truncateLines(text, 70).text }],
+		details: details as never,
+		structuredContent: jsonOf(details),
+		...(isError ? { isError: true } : {}),
+	};
+}
+
+const bullets = (label: string, items: string[]) => (items.length ? items.map((n) => `· ${label}: ${n}`) : []);
+
+/* ────────────────────────────────────────────────────────────────────────── output schemas */
+
+/**
+ * The structured payloads nest heterogeneously (`moduleRefs` is a module list for a file and a
+ * per-module map for a build), and the point of `structuredContent` is machine consumption —
+ * nested objects are declared permissively so a shape change in the library never makes a tool
+ * call fail validation.
+ */
+const Loose = Type.Object({}, { additionalProperties: true });
+const LooseList = Type.Array(Loose);
+const Strings = Type.Array(Type.String());
+const DefRowOut = Type.Object({
+	symbol: Type.String(),
+	kind: Type.String(),
+	file: Type.String(),
+	line: Type.Number(),
+	module: Type.String(),
+	scope: Type.String(),
+	marker: Type.String(),
+	rank: Type.Number(),
+	match: Type.String(),
+});
+const IndexRefOut = Type.Object({ key: Type.String(), scope: Type.String(), defs: Type.Number(), generatedAt: Type.Number() });
+
+const SymbolOut = Type.Object({ scope: Type.String(), total: Type.Number(), results: Type.Array(DefRowOut), ranks: LooseList, indexes: Type.Array(IndexRefOut), notes: Strings, warnings: Type.Optional(Strings) });
+const ListOut = Type.Object({ scope: Type.String(), total: Type.Number(), symbols: Type.Array(DefRowOut), indexes: Type.Array(IndexRefOut), notes: Strings, warnings: Type.Optional(Strings) });
+const ContextOut = Type.Object({ unit: Loose, counts: Loose, source: Type.String(), warnings: Type.Optional(Strings), notes: Type.Optional(Strings) });
+const IndexOut = Type.Object({
+	key: Type.Optional(Type.String()),
+	mode: Type.Optional(Type.String()),
+	scope: Type.Optional(Type.String()),
+	healthy: Type.Optional(Type.Boolean()),
+	issues: Type.Optional(Strings),
+	ageMs: Type.Optional(Type.Number()),
+	counts: Type.Optional(Loose),
+	roots: Type.Optional(Type.Union([Strings, LooseList, Type.Number()])),
+	source: Type.Optional(Type.String()),
+	target: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	platform: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	configuration: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	query: Type.Optional(Loose),
+	built: Type.Optional(Type.Boolean()),
+	durationMs: Type.Optional(Type.Number()),
+	actions: Type.Optional(Strings),
+	warnings: Type.Optional(Strings),
+	notes: Type.Optional(Strings),
+	status: Type.Optional(Loose),
+	indexes: Type.Optional(LooseList),
+});
+
+/* ──────────────────────────────────────────────────────────────────────────── tools */
+
+export const unrealSymbol = defineTool({
+	name: "unreal_symbol",
+	label: "UE symbol",
+	description: "Find where a C++ type, function, USTRUCT, UENUM or UPROPERTY is defined — project and enabled plugins by default, Engine/Source on request — one line per hit with its owning module.",
+	promptSnippet: "Locate a UE C++ symbol definition (project, plugins, engine) with module attribution",
+	promptGuidelines: [
+		"Use unreal_symbol instead of grepping Engine/Source for a class or function name: grep returns every file that mentions the name (a hot engine class is ~176 files / 150 KB of context); this returns definition lines only.",
+		"Default scope is 'project' (project modules + enabled plugins). Engine types (AActor, UAnimInstance, FWorldDelegates) need scope 'engine', which requires an engine index: unreal_index action build scope engine — minutes the first time, cached afterwards, and engineAreas [\"Runtime\"] makes it much cheaper.",
+		"Qualify member lookups: query 'Tick' with owner 'AActor', or query 'AActor:Tick'. Use prefix: true for name families ('ULp', 'ANiMy'), never to silently accept a typo.",
+		"A definition line is a starting point, not an answer: read that file at that line. For engine call graphs clangd (MCP) is more precise; for module/link facts use unreal_context.",
+	],
+	parameters: SymbolParams,
+	outputSchema: SymbolOut,
+	annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+	executionMode: "parallel",
+
+	async execute(_id, params, _signal, _update, ctx) {
+		const query = params.owner ? `${params.owner}:${params.query}` : params.query;
+		const out = await symbolLookup({ cwd: params.cwd ?? ctx.cwd, query, scope: params.scope as Scope | undefined, engineAreas: params.engineAreas, module: params.module, prefix: params.prefix, limit: params.limit, fs: realFs });
+		const rows = out.results.map((row) => rowLine(row, params.cwd ?? ctx.cwd));
+		const text = [`unreal_symbol '${query}' scope=${out.scope}: ${out.total} definition(s)`, ...rows, ...out.notes.map((n) => `· ${n}`), ...(out.warnings ?? []).map((w) => `! ${w}`)].join("\n");
+		return result(text, out, out.total === 0);
+	},
+});
+
+export const unrealSymbolList = defineTool({
+	name: "unreal_symbol_list",
+	label: "UE symbols by prefix",
+	description: "List symbol names starting with a prefix — what a project defines (ULp*, FP*) or an engine family (UAnim*, ANiMy*).",
+	promptSnippet: "List UE symbol names by prefix (project, plugins, engine)",
+	promptGuidelines: [
+		"Use unreal_symbol_list to discover names before a lookup: 'ULp' shows the project's own classes; engine scope shows prefix families.",
+		"Keep limit small (20-40): a one-letter prefix over an engine index matches thousands of names.",
+	],
+	parameters: ListParams,
+	outputSchema: ListOut,
+	annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+	executionMode: "parallel",
+
+	async execute(_id, params, _signal, _update, ctx) {
+		const out = await symbolList({ cwd: params.cwd ?? ctx.cwd, prefix: params.prefix, scope: params.scope as Scope | undefined, kind: params.kind, module: params.module, engineAreas: params.engineAreas, limit: params.limit ?? 40, fs: realFs });
+		const rows = out.symbols.map((row) => rowLine(row, params.cwd ?? ctx.cwd));
+		const text = [`unreal_symbol_list '${params.prefix}' scope=${out.scope}: ${out.total} symbol(s)`, ...rows, ...out.notes.map((n) => `· ${n}`)].join("\n");
+		return result(text, out);
+	},
+});
+
+export const unrealContext = defineTool({
+	name: "unreal_context",
+	label: "UE compile context",
+	description: "Answer 'what do I need to use X': the module directory, the real Definitions.h defines, C++ standard, SDK, include paths, module dependency lists (public/private/circular/dynamic), and what a header declares.",
+	promptSnippet: "Report a UE module's or file's real compile context (UBT Query + scan data)",
+	promptGuidelines: [
+		"Before adding a Build.cs dependency, ask unreal_context for the module: its public/private dependency lists are the authoritative 'use this type, link this module' answer.",
+		"Pass 'file' for a header to get its module, its declarations, and the include paths its target compiles with — cheaper than a repo-wide grep for the #include line.",
+		"The define list lives in Intermediate/Build/.../Definitions.<Module>.h (UBT generates it). UBT Query reports defines: [] — this tool reads that file, so 'defines' is real, not guessed.",
+	],
+	parameters: ContextParams,
+	outputSchema: ContextOut,
+	annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+	executionMode: "parallel",
+
+	async execute(_id, params, _signal, _update, ctx) {
+		if (!params.file && !params.module) {
+			return result("unreal_context needs 'file' (a .h/.cpp) or 'module' (a module name).", { error: "no file or module" }, true);
+		}
+
+		if (params.file) {
+			const fc = await fileContext({
+				cwd: params.cwd ?? ctx.cwd,
+				file: params.file,
+				mode: params.includeDefines ? "full" : "definitions",
+				includeDefines: params.includeDefines,
+				engineAreas: params.engineAreas,
+				refresh: params.refresh,
+				limit: params.limit,
+				fs: realFs,
+			});
+			const c = fc.compile;
+			const lines = [
+				`unreal_context ${shortPath(fc.file, params.cwd ?? ctx.cwd)}  mode=${fc.mode}  module=${fc.module ?? "?"}${fc.indexKey ? `  index=${fc.indexKey}` : ""}`,
+			];
+			if (c) {
+				lines.push(
+					`  file kind=${c.kind}${c.standard ? `  standard=${c.standard}` : ""}${c.compiler ? `  compiler=${c.compiler}` : ""}`,
+					`  include paths: ${c.includePaths.length} · forced includes: ${c.forcedIncludes.length} · declares: ${c.declares.length} · includes: ${c.includes.length}`,
+					`  deps: ${c.moduleRefs.public.length} public + ${c.moduleRefs.private.length} private`,
+				);
+				if (c.moduleRefs.publicInclude.length) lines.push(`  publicInclude: ${c.moduleRefs.publicInclude.join(", ")}`);
+				if (c.moduleRefs.circular.length) lines.push(`  circular: ${c.moduleRefs.circular.join(", ")}`);
+				if (c.moduleRefs.dynamicallyLoaded.length) lines.push(`  dynamicallyLoaded: ${c.moduleRefs.dynamicallyLoaded.join(", ")}`);
+				if (c.declares.length) lines.push(`  declares: ${c.declares.slice(0, 24).join(", ")}`);
+				if (c.definesFile) lines.push(`  defines file: ${shortPath(c.definesFile, params.cwd ?? ctx.cwd)}`);
+				if (c.forcedIncludes.length) lines.push(`  forced includes: ${c.forcedIncludes.slice(0, 3).map((f) => shortPath(f, params.cwd ?? ctx.cwd)).join(", ")}`);
+				lines.push(...c.notes.map((n) => `· ${n}`));
+			}
+			if (fc.defines?.length) lines.push(`  defines: ${fc.defines.slice(0, 40).join(" ")}`);
+			if (fc.symbols?.length) lines.push(`  symbols in file: ${fc.symbols.slice(0, 20).map((s) => `${s.kind} ${s.symbol}@${s.line}`).join(", ")}`);
+			const text = [...lines, ...fc.notes.map((n) => `· ${n}`), ...(fc.warnings ?? []).map((w) => `! ${w}`), ...(fc.error ? [`! ${fc.error}`] : [])].join("\n");
+			return result(text, fc, !!fc.error);
+		}
+
+		const out = await buildContext({
+			cwd: params.cwd ?? ctx.cwd,
+			module: params.module,
+			target: params.target,
+			platform: params.platform,
+			configuration: params.configuration,
+			includeDefines: params.includeDefines,
+			engineAreas: params.engineAreas,
+			refresh: params.refresh,
+			limit: params.limit,
+			fs: realFs,
+		});
+		const m = out.module;
+		const lines = [
+			`unreal_context module ${m?.name ?? params.module}  target=${out.target?.target} ${out.target?.platform} ${out.target?.configuration} (${out.target?.source ?? "?"})`,
+			`  dir: ${shortPath(m?.directory, params.cwd ?? ctx.cwd) ?? "?"}${m?.standard ? `  standard=${m.standard}` : ""}${m?.windowsSdkVersion ? `  sdk=${m.windowsSdkVersion}` : ""}`,
+			`  deps: ${m?.dependencies ?? 0} · public headers: ${m?.publicHeaders ?? 0} · private headers: ${m?.privateHeaders ?? 0} · include paths: ${m?.includePaths ?? 0} · total headers: ${out.headerCount}`,
+			`  query cache: ${out.queryCache?.source ?? "?"}${out.queryCache?.durationMs ? ` (${JSON.stringify(out.queryCache.durationMs)} ms)` : ""}`,
+		];
+		lines.push(...bullets("publicInclude", m?.publicInclude ?? []), ...bullets("privateInclude", m?.privateInclude ?? []), ...bullets("circular", m?.circular ?? []), ...bullets("dynamicallyLoaded", m?.dynamicallyLoaded ?? []));
+		if (m?.definesFile) lines.push(`  defines file: ${shortPath(m.definesFile, params.cwd ?? ctx.cwd)}`);
+		if (out.defines?.length) lines.push(`  defines: ${out.defines.slice(0, 40).join(" ")}`);
+		if (m?.compilerPath) lines.push(`  compiler: ${m.compilerPath}`);
+		if (out.projectModules?.length) lines.push(`  project modules: ${out.projectModules.map((entry) => entry.name).slice(0, 20).join(", ")}`);
+		const text = [...lines, ...out.notes.map((n) => `· ${n}`), ...(out.warnings ?? []).map((w) => `! ${w}`), ...(out.error ? [`! ${out.error}`] : [])].join("\n");
+		return result(text, out, !!out.error);
+	},
+});
+
+export const unrealIndex = defineTool({
+	name: "unreal_index",
+	label: "UE index",
+	description: "Build or report the source index: project/plugins (seconds), Engine/Source (minutes the first time), and the UnrealBuildTool Query cache behind the compile facts.",
+	promptSnippet: "Build/report the UE symbol index and UBT Query cache",
+	promptGuidelines: [
+		"Run unreal_index action 'status' first: it prints what is cached, how old it is, and what building will cost.",
+		"An engine-scope build is a minutes-long scan the first time. Ask the user before building it, and prefer engineAreas [\"Runtime\"] over the whole tree when the question is about gameplay base classes.",
+		"mode 'full' runs UnrealBuildTool -Mode=Query (~7s, needs no compiler, and runs in UBT's own Query environment so it cannot collide with a live build) and records include edges; 'definitions' is a text scan only.",
+		"After a rebase, a branch switch, adding a plugin, or an engine version change, rebuild with refresh: true — indexes are keyed by scan-root identity, not by the project name.",
+		"action 'compiledb' is the clangd enrichment path: minutes of UnrealBuildTool work, ~1 GB for the engine scope. Ask the user before running it, pass check: '<file>' to prove the result with clangd --check, and treat the database as machine-local (never committed).",
+	],
+	parameters: IndexParams,
+	outputSchema: IndexOut,
+	annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+	executionMode: "sequential",
+
+	async execute(_id, params, _signal, _update, ctx) {
+		if (params.action === "status") {
+			const out = indexStatus(params.cwd ?? ctx.cwd, realFs);
+			const lines = [
+				`cache: ${out.cacheDir}`,
+				`query cache: ${out.query.usable ? `${out.query.target.target} ${out.query.target.platform} ${out.query.target.configuration} (${out.query.target.source})` : "not built"}`,
+				`  TargetDetails: ${out.query.targetDetails ? `${Math.round(out.query.targetDetails.bytes / 1024)} KB, ${Math.round(out.query.targetDetails.ageMs / 1000)}s old` : "absent"}`,
+				`  TargetModuleReferences: ${out.query.moduleReferences ? `${Math.round(out.query.moduleReferences.bytes / 1024)} KB, ${Math.round(out.query.moduleReferences.ageMs / 1000)}s old` : "absent"}`,
+			];
+			for (const index of out.indexes) {
+				lines.push(`index ${index.key}  ${index.scope || "?"} ${index.mode}  ${index.defs} symbols / ${index.files} files  ${index.source}${index.target ? ` target=${index.target}` : ""}  ${Math.round(index.ageMs / 1000)}s old  ${index.sizeMb}MB${index.issues.length ? `  issues: ${index.issues.join("; ")}` : ""}`);
+			}
+			if (!out.indexes.length) lines.push("no symbol index yet — unreal_index action build scope project (seconds)");
+			const text = [...lines, ...(out.query.notes ?? []).map((n) => `· ${n}`)].join("\n");
+			return result(text, out);
+		}
+
+		if (params.action === "compiledb") {
+			const db = await compileDbReport({
+				cwd: params.cwd ?? ctx.cwd,
+				scope: (params.scope === "project+engine" ? "project+engine" : "project") as "project" | "project+engine",
+				target: params.target,
+				platform: params.platform,
+				configuration: params.configuration,
+				refresh: params.refresh,
+				fs: realFs,
+			});
+			const text = [
+				`unreal_index compiledb → ${db.ok ? "ok" : "FAILED"}`,
+				...(db.target ? [`  target ${db.target} ${db.platform ?? ""} ${db.configuration ?? ""}`] : []),
+				`  ${db.entries} clangd-ready entries${"path" in db ? ` at ${db.path}` : ""} ${db.reused ? "(reused)" : ""}`,
+				...(db.notes ?? []).map((n) => `· ${n}`),
+				...(db.warnings ?? []).map((w) => `! ${w}`),
+			].join("\n");
+			return result(text, db as unknown as Record<string, JsonValue>, !db.ok);
+		}
+
+		const out = await indexBuild({
+			cwd: params.cwd ?? ctx.cwd,
+			scope: (params.scope ?? "project") as "project" | "engine",
+			mode: (params.mode ?? "definitions") as "definitions" | "full",
+			engineAreas: params.engineAreas,
+			target: params.target,
+			platform: params.platform,
+			configuration: params.configuration,
+			refresh: params.refresh,
+			fs: realFs,
+		});
+		const seconds = out.durationMs != null ? (out.durationMs / 1000).toFixed(1) : "?";
+		const text = [
+			`unreal_index build scope=${out.scope} mode=${out.mode} → ${out.key}`,
+			`  ${out.symbols} symbols / ${out.files} files / ${out.modules} modules from ${out.roots} roots ${out.built ? `in ${seconds}s` : "(cached, reused as is)"}`,
+			`  areas: ${(out.engineAreas ?? []).join(", ")}`,
+			`  dir: ${out.indexDir ?? "not built"}`,
+			...out.notes.map((n) => `· ${n}`),
+			...(out.warnings ?? []).map((w) => `! ${w}`),
+		].join("\n");
+		return result(text, out, !out.built && out.symbols === 0);
+	},
+});
+
+export const indexTools = [unrealSymbol, unrealSymbolList, unrealContext, unrealIndex];
+
+/** `/unreal-symbol <name>` — prefix-tolerant lookup across project and engine indexes. */
+export function unrealSymbolCommand(query: string, cwd: string) {
+	return symbolLookup({ cwd, query, scope: "all", prefix: true, fs: realFs }).then((out) => {
+		const rows = out.results.map((row) => rowLine(row, cwd));
+		return [`unreal_symbol '${query}': ${out.total} definition(s)`, ...rows, ...out.notes.map((n) => `· ${n}`)].join("\n");
+	});
+}
+
+/** `/unreal-module <name>` — module identity + dependency lists; needs the Query cache, not a symbol index. */
+export function unrealModuleCommand(name: string, cwd: string) {
+	return buildContext({ cwd, module: name, includeDefines: true, fs: realFs }).then((out) => {
+		const m = out.module;
+		return [
+			`module ${m?.name ?? name}`,
+			`  dir: ${shortPath(m?.directory, cwd)}  target=${out.target?.target} ${out.target?.platform} ${out.target?.configuration}`,
+			`  standard=${m?.standard ?? "?"}  sdk=${m?.windowsSdkVersion ?? "?"}  deps=${m?.dependencies ?? 0}`,
+			`  publicInclude: ${(m?.publicInclude ?? []).join(", ") || "?"}`,
+			`  privateInclude: ${(m?.privateInclude ?? []).join(", ") || "?"}`,
+			`  defines file: ${shortPath(m?.definesFile, cwd)}`,
+			...out.notes.map((n) => `· ${n}`),
+			...(out.warnings ?? []).map((w) => `! ${w}`),
+		].join("\n");
+	});
+}