@danypops/pi-lector 0.13.11 → 0.15.0

package/extension/src/index.ts

@@ -4,7 +4,6 @@ import { resolve } from "node:path";
 import type {
 	CachedRepositoryPage,
 	ContentHash,
-	ContextBundleResult,
 	Diagnostic,
 	DocumentSymbolEntry,
 	EditOutcome,
@@ -83,6 +82,7 @@ import {
 	formatWorkspaceMapCall,
 	formatWorkspaceMapResult,
 } from "./code-intelligence/rendering.ts";
+import { formatFindSymbolsAcrossProjectsModelContent, formatSearchTextAcrossProjectsModelContent } from "./cross-workspace-search/model-content.ts";
 import { type CrossWorkspaceOutcome, createLectorCrossWorkspaceSearchOperations } from "./cross-workspace-search/operations.ts";
 import { formatCrossWorkspaceCall, formatFindSymbolsAcrossProjectsResult, formatSearchTextAcrossProjectsResult } from "./cross-workspace-search/rendering.ts";
 import { createLectorEditOperations } from "./edit/operations.ts";
@@ -121,8 +121,16 @@ import {
 	PACKAGE_SOURCE_LIST_VISIBLE_ROWS,
 	packageSourceListMoreLine,
 } from "./package-source/rendering.ts";
+import { formatSemanticModelContent } from "./presentation/model-content.ts";
+import { withLectorPresentation } from "./presentation/presentation-contract.ts";
+import { presentationTitle } from "./presentation/tool-presentation.ts";
 import { createLectorReadOperations } from "./read/operations.ts";
 import { createReferenceBasedRenameOperations } from "./reference-based-rename/operations.ts";
+import {
+	formatReferenceBasedRenameModelContent,
+	formatReferenceBasedRenameResult,
+	type ReferenceBasedRenameOutcome,
+} from "./reference-based-rename/rendering.ts";
 import { createRenameOperations } from "./rename/operations.ts";
 import { createRepoCacheEvictOperations } from "./repo-cache/evict-operations.ts";
 import { createRepoCacheListOperations } from "./repo-cache/list-operations.ts";
@@ -152,7 +160,13 @@ import {
 	monitorWorkspaceCache,
 	waitForJobCompletion,
 } from "./workspace-cache/operations.ts";
-import { formatJobSnapshotResult, formatWorkspaceCacheCall, formatWorkspaceCacheStatusResult } from "./workspace-cache/rendering.ts";
+import {
+	formatJobSnapshotResult,
+	formatWorkspaceCacheCall,
+	formatWorkspaceCacheStatusResult,
+	formatWorkspaceReleaseModelContent,
+	formatWorkspaceReleaseResult,
+} from "./workspace-cache/rendering.ts";
 import { createLectorWriteOperations } from "./write/operations.ts";
 
 function describeIntelligenceSource(provenance: IntelligenceProvenance): string {
@@ -189,7 +203,7 @@ export default function (pi: ExtensionAPI) {
 	const customToolNames = new Set<string>();
 	function registerLectorTool<TParams extends TSchema, TDetails = unknown, TState = unknown>(tool: ToolDefinition<TParams, TDetails, TState>): void {
 		customToolNames.add(tool.name);
-		pi.registerTool(tool);
+		pi.registerTool(withLectorPresentation(tool));
 	}
 	pi.on("tool_result", (event) => {
 		if (!customToolNames.has(event.toolName)) return;
@@ -471,7 +485,11 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text", text }], details: result };
 			},
 			renderCall(args, theme) {
-				return new Text(theme.fg("toolTitle", `localize ${typeof args.query === "string" ? args.query : "context"}`), 0, 0);
+				return new Text(
+					`${theme.fg("toolTitle", theme.bold(presentationTitle("localize_context")))} ${theme.fg("accent", typeof args.query === "string" ? `"${args.query}"` : "")}`,
+					0,
+					0,
+				);
 			},
 			renderResult(result, { isPartial }, theme, context) {
 				if (isPartial) return new Text(theme.fg("warning", "Localizing..."), 0, 0);
@@ -482,8 +500,11 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "localize_context failed"), 0, 0);
 				}
-				const details = result.details as ContextBundleResult | undefined;
-				return new Text(details ? `${details.candidates.length} candidates · graph ${details.completeness.graph}` : "Localization complete", 0, 0);
+				const contentText = result.content
+					.filter((block) => block.type === "text")
+					.map((block) => block.text)
+					.join("\n");
+				return new Text(contentText || "Localization complete", 0, 0);
 			},
 		});
 
@@ -1181,21 +1202,14 @@ export default function (pi: ExtensionAPI) {
 				const fromPath = resolve(cwd, params.fromPath);
 				const toPath = resolve(cwd, params.toPath);
 				const outcome = await referenceBasedRenameOperations.rename(fromPath, toPath, params.maxFiles, params.maxSymbolsPerFile);
-				const lines = [
-					`moved to ${outcome.movedTo}`,
-					outcome.filesUpdated.length === 0
-						? "no other files referenced it"
-						: `updated imports in ${outcome.filesUpdated.length} file(s): ${outcome.filesUpdated.join(", ")}`,
-					...outcome.caveats.map((caveat) => `caveat: ${caveat}`),
-				];
-				return { content: [{ type: "text", text: lines.join("\n") }], details: { outcome } };
+				return { content: [{ type: "text", text: formatReferenceBasedRenameModelContent(outcome) }], details: { outcome } };
 			},
 			renderCall(args, theme, context) {
 				const fromPath = typeof args.fromPath === "string" ? args.fromPath : "";
 				const toPath = typeof args.toPath === "string" ? args.toPath : "";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(
-					`${theme.fg("toolTitle", theme.bold("reference_based_rename"))} ${theme.fg("accent", fromPath)} ${theme.fg("dim", "->")} ${theme.fg("accent", toPath)}`,
+					`${theme.fg("toolTitle", theme.bold(presentationTitle("reference_based_rename")))} ${theme.fg("accent", fromPath)} ${theme.fg("dim", "->")} ${theme.fg("accent", toPath)}`,
 				);
 				return text;
 			},
@@ -1208,13 +1222,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "reference_based_rename failed"), 0, 0);
 				}
-				const details = result.details as { outcome?: { movedTo: string; filesUpdated: readonly string[] } } | undefined;
+				const details = result.details as { outcome?: ReferenceBasedRenameOutcome } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(
-					details?.outcome
-						? `${theme.fg("success", "moved")} ${theme.fg("accent", details.outcome.movedTo)} ${theme.fg("dim", `(${details.outcome.filesUpdated.length} import(s) updated)`)}`
-						: theme.fg("success", "rename complete"),
-				);
+				text.setText(details?.outcome ? formatReferenceBasedRenameResult(details.outcome, theme) : theme.fg("success", "rename complete"));
 				return text;
 			},
 		});
@@ -1260,7 +1270,7 @@ export default function (pi: ExtensionAPI) {
 				const action = typeof args.action === "string" ? args.action : "";
 				const path = typeof args.path === "string" ? args.path : "";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(`${theme.fg("toolTitle", theme.bold("rename"))} ${theme.fg("dim", action)} ${theme.fg("accent", path)}`);
+				text.setText(`${theme.fg("toolTitle", theme.bold(presentationTitle("rename", action)))} ${theme.fg("accent", path)}`);
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -1441,10 +1451,10 @@ export default function (pi: ExtensionAPI) {
 								? ` ${args.rootId}`
 								: "";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(`${theme.fg("toolTitle", theme.bold("symbol_annotations"))} ${theme.fg("accent", action)}${theme.fg("dim", id)}`);
+				text.setText(`${theme.fg("toolTitle", theme.bold(presentationTitle("symbol_annotations", action)))}${theme.fg("accent", id)}`);
 				return text;
 			},
-			renderResult(result, { isPartial }, theme, context) {
+			renderResult(result, { expanded, isPartial }, theme, context) {
 				if (isPartial) return new Text(theme.fg("warning", "Working on annotation..."), 0, 0);
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				if (context.isError) {
@@ -1457,11 +1467,11 @@ export default function (pi: ExtensionAPI) {
 				}
 				const details = result.details as SymbolAnnotationToolDetails | undefined;
 				if (details?.annotations) {
-					text.setText(formatAnnotationListSummary(details.annotations, theme));
+					text.setText(expanded ? details.annotations.map(formatAnnotationDetail).join("\n\n") : formatAnnotationListSummary(details.annotations, theme));
 					return text;
 				}
 				if (details?.annotation) {
-					text.setText(formatAnnotationSummary(details.annotation, theme));
+					text.setText(expanded ? formatAnnotationDetail(details.annotation) : formatAnnotationSummary(details.annotation, theme));
 					return text;
 				}
 				if (details?.scrubbed !== undefined) {
@@ -1595,25 +1605,27 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		interface WorkspaceCacheToolDetails {
-			readonly action: "status" | "populate" | "wait" | "job_status";
+			readonly action: "status" | "populate" | "wait" | "job_status" | "release";
 			readonly status?: WorkspaceCacheStatus;
 			readonly job?: JobSnapshot<PopulateSymbolGraphResult>;
+			readonly release?: OperationOutputs["workspace.release"];
 		}
 
 		registerLectorTool({
 			name: "workspace_cache",
 			label: "Workspace Cache",
 			description:
-				"Checks or drives population of the workspace's persisted symbol graph -- the store reachable_from, symbol_annotations (anchor resolution), reference_based_rename, and workspace_map all read from, separate from the live language-server index find_symbols/hover/go_to_definition use. action=status reports not-cached/caching/partial/cached for the given bounds, without starting work. action=populate requests a scan and briefly waits for fast completion; a source file changing mid-scan (e.g. a concurrent edit or rename) is retried automatically in the background for up to a minute before surfacing as a real failure, no manual re-run needed. action=wait subscribes to daemon job completion, with bounded status polling only when push delivery is unavailable. action=job_status is a point-in-time diagnostic read.",
+				"Checks or drives population of the workspace's persisted symbol graph -- the store reachable_from, symbol_annotations (anchor resolution), reference_based_rename, and workspace_map all read from, separate from the live language-server index find_symbols/hover/go_to_definition use. action=status reports not-cached/caching/partial/cached for the given bounds, without starting work. action=populate requests a scan and briefly waits for fast completion; a source file changing mid-scan (e.g. a concurrent edit or rename) is retried automatically in the background for up to a minute before surfacing as a real failure, no manual re-run needed. action=wait subscribes to daemon job completion, with bounded status polling only when push delivery is unavailable. action=job_status is a point-in-time diagnostic read. action=release safely closes idle workspace resources and unregisters it so fetched/package source cleanup can proceed.",
 			promptSnippet: "Check or force-populate the workspace's persisted symbol graph",
 			promptGuidelines: [
 				"Use action=populate with a larger maxFiles/maxSymbolsPerFile before relying on reachable_from/symbol_annotations/reference_based_rename against a workspace bigger than the default 500-file auto-scan -- their own errors (empty results, UnknownAnnotationAnchor, ReferenceBasedRenameRequiresFreshGraph) usually mean the graph never reached the files you need, not that population is simply still catching up.",
 				"When action=populate returns a queued/running job, call action=wait once with that jobId; do not run shell sleep or manually poll job_status.",
+				"Use action=release after finishing with a fetched or package-source workspace so package_source remove/clean and repo_cache evict can reclaim it; active leases, jobs, or watches fail closed.",
 			],
 			parameters: Type.Object({
-				action: Type.Union([Type.Literal("status"), Type.Literal("populate"), Type.Literal("wait"), Type.Literal("job_status")]),
+				action: Type.Union([Type.Literal("status"), Type.Literal("populate"), Type.Literal("wait"), Type.Literal("job_status"), Type.Literal("release")]),
 				directory: Type.Optional(
-					Type.String({ description: "Required for action=status/populate -- absolute or cwd-relative path used to resolve the workspace" }),
+					Type.String({ description: "Required for action=status/populate/release -- absolute or cwd-relative path used to resolve the workspace" }),
 				),
 				maxFiles: Type.Optional(
 					Type.Number({ description: "action=status/populate only -- defaults to 500, the same bound the automatic first-touch scan uses" }),
@@ -1629,11 +1641,14 @@ export default function (pi: ExtensionAPI) {
 				),
 				jobId: Type.Optional(Type.String({ description: "Required for action=wait/job_status -- a jobId returned by action=populate" })),
 			}),
-			async execute(_toolCallId, params, signal): Promise<AgentToolResult<WorkspaceCacheToolDetails>> {
+			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<WorkspaceCacheToolDetails>> {
 				if (params.action === "job_status") {
 					if (!params.jobId) throw new Error("workspace_cache action=job_status requires jobId");
 					const job = await cacheOperations.jobStatus(params.jobId);
-					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "job_status", job } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "job_status"), job) }],
+						details: { action: "job_status", job },
+					};
 				}
 				if (params.action === "wait") {
 					if (!params.jobId) throw new Error("workspace_cache action=wait requires jobId");
@@ -1655,21 +1670,43 @@ export default function (pi: ExtensionAPI) {
 						);
 					}
 					const job = outcome.kind === "terminal" ? outcome.job : await cacheOperations.jobStatus(params.jobId);
-					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "wait", job } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "wait"), job) }],
+						details: { action: "wait", job },
+					};
 				}
 				if (!params.directory) throw new Error(`workspace_cache action=${params.action} requires directory`);
 				const directory = resolve(cwd, params.directory);
+				if (params.action === "release") {
+					const release = await cacheOperations.release(directory, {
+						toolName: "workspace_cache",
+						toolCallId,
+						signal,
+						context: ctx,
+					});
+					return {
+						content: [{ type: "text", text: formatWorkspaceReleaseModelContent(release) }],
+						details: { action: "release", release },
+					};
+				}
 				const maxFiles = params.maxFiles ?? 500;
 				const maxSymbolsPerFile = params.maxSymbolsPerFile ?? 100;
 				if (params.action === "status") {
 					const status = await cacheOperations.status(directory, maxFiles, maxSymbolsPerFile);
-					return { content: [{ type: "text", text: JSON.stringify(status) }], details: { action: "status", status } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "status"), status) }],
+						details: { action: "status", status },
+					};
 				}
 				const job = await cacheOperations.submit(directory, maxFiles, maxSymbolsPerFile, params.waitMs ?? 3_000);
-				return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "populate", job } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "populate"), job) }],
+					details: { action: "populate", job },
+				};
 			},
 			renderCall(args, theme, context) {
-				const action = args.action === "populate" || args.action === "wait" || args.action === "job_status" ? args.action : "status";
+				const action =
+					args.action === "populate" || args.action === "wait" || args.action === "job_status" || args.action === "release" ? args.action : "status";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(formatWorkspaceCacheCall(action, args, theme));
 				return text;
@@ -1685,7 +1722,13 @@ export default function (pi: ExtensionAPI) {
 				}
 				const details = result.details as WorkspaceCacheToolDetails | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(details?.action === "status" ? formatWorkspaceCacheStatusResult(details.status, theme) : formatJobSnapshotResult(details?.job, theme));
+				text.setText(
+					details?.action === "status"
+						? formatWorkspaceCacheStatusResult(details.status, theme)
+						: details?.action === "release"
+							? formatWorkspaceReleaseResult(details.release, theme)
+							: formatJobSnapshotResult(details?.job, theme),
+				);
 				return text;
 			},
 		});
@@ -1764,7 +1807,7 @@ export default function (pi: ExtensionAPI) {
 				if (params.action === "status") {
 					const summary = await gitOperations.status(directory, vehicleCall);
 					const details: GitToolDetails = { action: "status", summary };
-					return { content: [{ type: "text", text: JSON.stringify(summary) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "status"), summary) }], details };
 				}
 				if (params.action === "log") {
 					if (params.maxCount === undefined) throw new Error("git action=log requires maxCount");
@@ -1785,18 +1828,18 @@ export default function (pi: ExtensionAPI) {
 					if (params.maxBytes === undefined) throw new Error("git action=compare-symbol requires maxBytes");
 					const comparison = await gitOperations.compareSymbol(directory, params.path, params.symbol, params.fromRef, params.toRef, params.maxBytes);
 					const details: GitToolDetails = { action: "compare-symbol", comparison };
-					return { content: [{ type: "text", text: JSON.stringify(comparison) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "compare-symbol"), comparison) }], details };
 				}
 				if (params.action === "worktree-add") {
 					if (!params.ref) throw new Error("git action=worktree-add requires ref");
 					const worktreeAdd = await gitOperations.worktreeAdd(directory, params.ref, params.forceRefresh, vehicleCall);
 					const details: GitToolDetails = { action: "worktree-add", worktreeAdd };
-					return { content: [{ type: "text", text: JSON.stringify(worktreeAdd) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "worktree-add"), worktreeAdd) }], details };
 				}
 				if (params.action === "worktree-remove") {
 					const worktreeRemove = await gitOperations.worktreeRemove(directory, vehicleCall);
 					const details: GitToolDetails = { action: "worktree-remove", worktreeRemove };
-					return { content: [{ type: "text", text: JSON.stringify(worktreeRemove) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "worktree-remove"), worktreeRemove) }], details };
 				}
 				if (params.action === "show") {
 					if (!params.ref || !params.path) throw new Error("git action=show requires ref and path");
@@ -1809,7 +1852,7 @@ export default function (pi: ExtensionAPI) {
 					if (params.maxMatches === undefined || params.maxBytes === undefined) throw new Error("git action=grep-ref requires maxMatches and maxBytes");
 					const grep = await gitOperations.grep(directory, params.ref, params.pattern, params.pathspecs, params.maxMatches, params.maxBytes, vehicleCall);
 					const details: GitToolDetails = { action: "grep-ref", grep };
-					return { content: [{ type: "text", text: JSON.stringify(grep) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "grep-ref"), grep) }], details };
 				}
 				if (params.action === "grep-history") {
 					if (!params.pattern) throw new Error("git action=grep-history requires pattern");
@@ -1835,20 +1878,20 @@ export default function (pi: ExtensionAPI) {
 						vehicleCall,
 					);
 					const details: GitToolDetails = { action: "grep-history", historyGrep };
-					return { content: [{ type: "text", text: JSON.stringify(historyGrep) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "grep-history"), historyGrep) }], details };
 				}
 				if (params.action === "ls-ref") {
 					if (!params.ref) throw new Error("git action=ls-ref requires ref");
 					if (params.maxResults === undefined) throw new Error("git action=ls-ref requires maxResults");
 					const listFiles = await gitOperations.listFiles(directory, params.ref, params.pathspecs, params.maxResults, vehicleCall);
 					const details: GitToolDetails = { action: "ls-ref", listFiles };
-					return { content: [{ type: "text", text: JSON.stringify(listFiles) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "ls-ref"), listFiles) }], details };
 				}
 				if (params.action === "is-ancestor") {
 					if (!params.ancestorRef || !params.ref) throw new Error("git action=is-ancestor requires ancestorRef and ref");
 					const result = await gitOperations.isAncestor(directory, params.ancestorRef, params.ref, vehicleCall);
 					const details: GitToolDetails = { action: "is-ancestor", isAncestor: { ancestorRef: params.ancestorRef, ref: params.ref, result } };
-					return { content: [{ type: "text", text: JSON.stringify({ isAncestor: result }) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "is-ancestor"), { isAncestor: result }) }], details };
 				}
 				throw new Error(`unknown git action: ${String(params.action)}`);
 			},
@@ -2134,7 +2177,7 @@ export default function (pi: ExtensionAPI) {
 				const action = typeof args.action === "string" ? args.action : "";
 				const path = typeof args.path === "string" ? args.path : "";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(`${theme.fg("toolTitle", theme.bold("mutation_history"))} ${theme.fg("accent", action)} ${theme.fg("dim", path)}`);
+				text.setText(`${theme.fg("toolTitle", theme.bold(presentationTitle("mutation_history", action)))} ${theme.fg("accent", path)}`);
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -2210,7 +2253,10 @@ export default function (pi: ExtensionAPI) {
 						maxResults: params.maxResults,
 						cursor: params.cursor,
 					});
-					return { content: [{ type: "text", text: JSON.stringify(page) }], details: { action: "list", page } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "list"), page) }],
+						details: { action: "list", page },
+					};
 				}
 				if (params.action === "remove") {
 					if (!params.name || !params.resolvedVersion) throw new Error("package_source action=remove requires ecosystem, name, and resolvedVersion");
@@ -2220,11 +2266,17 @@ export default function (pi: ExtensionAPI) {
 						params.name,
 						params.resolvedVersion,
 					);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "remove", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "remove"), result) }],
+						details: { action: "remove", result },
+					};
 				}
 				if (params.action === "clean") {
 					const result = await packageSourceOperations.clean(optionalPackageEcosystem(params.ecosystem));
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "clean", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "clean"), result) }],
+						details: { action: "clean", result },
+					};
 				}
 				if (!params.directory || !params.name) throw new Error("package_source action=resolve requires directory and name");
 				const directory = resolve(cwd, params.directory);
@@ -2235,7 +2287,10 @@ export default function (pi: ExtensionAPI) {
 					params.registry ?? null,
 					optionalPackageEcosystem(params.ecosystem),
 				);
-				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "resolve", result } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "resolve"), result) }],
+					details: { action: "resolve", result },
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -2332,12 +2387,18 @@ export default function (pi: ExtensionAPI) {
 						params.forceRefresh,
 						vehicleCall,
 					);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "fetch", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("repo_cache", "fetch"), result) }],
+						details: { action: "fetch", result },
+					};
 				}
 				if (params.action === "evict") {
 					if (!params.owner || !params.repo) throw new Error("repo_cache action=evict requires owner and repo");
 					const result = await repoCacheEvictOperations.evict(params.host ?? "github.com", params.owner, params.repo, params.ref ?? null, vehicleCall);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "evict", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("repo_cache", "evict"), result) }],
+						details: { action: "evict", result },
+					};
 				}
 				if (params.maxResults === undefined) throw new Error("repo_cache action=list requires maxResults");
 				const page = await repoCacheListOperations.list(
@@ -2346,7 +2407,10 @@ export default function (pi: ExtensionAPI) {
 					params.cursor,
 					vehicleCall,
 				);
-				return { content: [{ type: "text", text: JSON.stringify(page) }], details: { action: "list", page } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("repo_cache", "list"), page) }],
+					details: { action: "list", page },
+				};
 			},
 			renderCall(args, theme, context) {
 				const action = args.action === "list" || args.action === "evict" ? args.action : "fetch";
@@ -2419,14 +2483,23 @@ export default function (pi: ExtensionAPI) {
 				};
 				if (params.action === "github_repos") {
 					const result = await externalSearchOperations.githubRepos(params.query, maxResults, vehicleCall);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "github_repos", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("external_search", "github_repos"), result) }],
+						details: { action: "github_repos", result },
+					};
 				}
 				if (params.action === "npm_packages") {
 					const result = await externalSearchOperations.npmPackages(params.query, maxResults, vehicleCall);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "npm_packages", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("external_search", "npm_packages"), result) }],
+						details: { action: "npm_packages", result },
+					};
 				}
 				const result = await externalSearchOperations.sourcegraphCode(params.query, maxResults, vehicleCall);
-				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "sourcegraph_code", result } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("external_search", "sourcegraph_code"), result) }],
+					details: { action: "sourcegraph_code", result },
+				};
 			},
 			renderCall(args, theme, context) {
 				const action = args.action === "npm_packages" || args.action === "sourcegraph_code" ? args.action : "github_repos";
@@ -2434,7 +2507,7 @@ export default function (pi: ExtensionAPI) {
 				text.setText(formatExternalSearchCall(action, args, theme));
 				return text;
 			},
-			renderResult(result, { isPartial }, theme, context) {
+			renderResult(result, { expanded, isPartial }, theme, context) {
 				if (isPartial) return new Text(theme.fg("warning", "Searching..."), 0, 0);
 				if (context.isError) {
 					const errorText = result.content
@@ -2445,9 +2518,9 @@ export default function (pi: ExtensionAPI) {
 				}
 				const details = result.details as ExternalSearchToolDetails | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				if (details?.action === "npm_packages") text.setText(formatNpmPackageSearchResult(details.result, theme));
-				else if (details?.action === "sourcegraph_code") text.setText(formatSourcegraphCodeSearchResult(details.result, theme));
-				else text.setText(formatGithubRepoSearchResult(details?.action === "github_repos" ? details.result : undefined, theme));
+				if (details?.action === "npm_packages") text.setText(formatNpmPackageSearchResult(details.result, expanded, theme));
+				else if (details?.action === "sourcegraph_code") text.setText(formatSourcegraphCodeSearchResult(details.result, expanded, theme));
+				else text.setText(formatGithubRepoSearchResult(details?.action === "github_repos" ? details.result : undefined, expanded, theme));
 				return text;
 			},
 		});
@@ -2470,11 +2543,14 @@ export default function (pi: ExtensionAPI) {
 			async execute(_toolCallId, params) {
 				const directories = params.directories.map((directory) => resolve(cwd, directory));
 				const results = await crossWorkspaceSearchOperations.findSymbols(params.query, directories, params.timeoutMs, params.maxResults);
-				return { content: [{ type: "text", text: JSON.stringify(results) }], details: { results } };
+				return {
+					content: [{ type: "text", text: formatFindSymbolsAcrossProjectsModelContent(results) }],
+					details: { results },
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatCrossWorkspaceCall(args, theme));
+				text.setText(formatCrossWorkspaceCall("find_symbols_across_projects", args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -2509,11 +2585,14 @@ export default function (pi: ExtensionAPI) {
 			async execute(_toolCallId, params) {
 				const directories = params.directories.map((directory) => resolve(cwd, directory));
 				const results = await crossWorkspaceSearchOperations.searchText(params.query, directories, params.maxMatches, params.maxBytes, params.timeoutMs);
-				return { content: [{ type: "text", text: JSON.stringify(results) }], details: { results } };
+				return {
+					content: [{ type: "text", text: formatSearchTextAcrossProjectsModelContent(results) }],
+					details: { results },
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatCrossWorkspaceCall(args, theme));
+				text.setText(formatCrossWorkspaceCall("search_code_across_projects", args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {

package/extension/src/line-edit/rendering.ts

@@ -1,10 +1,11 @@
 import type { LineEditOutcome } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 export function formatLineEditCall(args: { path?: unknown; edits?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
 	const count = Array.isArray(args.edits) ? args.edits.length : 0;
-	return `${theme.fg("toolTitle", theme.bold("line_edit"))} ${theme.fg("accent", path)} ${theme.fg("dim", `(${count} edit${count === 1 ? "" : "s"})`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("line_edit")))} ${theme.fg("accent", path)} ${theme.fg("dim", `(${count} edit${count === 1 ? "" : "s"})`)}`;
 }
 
 export function formatLineEditResult(result: LineEditOutcome | undefined, theme: LectorTheme): string {

package/extension/src/package-source/rendering.ts

@@ -2,6 +2,7 @@ import type { PackageSourceListEntry, PackageSourceOperationResult } from "@dany
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList, type TableColumn } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 const DEFAULT_VISIBLE_CANDIDATES = 5;
 
@@ -14,18 +15,18 @@ export function formatPackageSourceCall(
 	args: { action?: unknown; directory?: unknown; name?: unknown; version?: unknown; ecosystem?: unknown; resolvedVersion?: unknown; text?: unknown },
 	theme: LectorTheme,
 ): string {
-	const label = theme.fg("toolTitle", theme.bold("package_source"));
 	const action: PackageSourceAction = args.action === "list" || args.action === "remove" || args.action === "clean" ? args.action : "resolve";
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("package_source", action)));
 	if (action === "list") {
 		const text = typeof args.text === "string" && args.text.length > 0 ? ` ${theme.fg("dim", args.text)}` : "";
-		return `${label} ${theme.fg("accent", "list")}${text}`;
+		return `${label}${text}`;
 	}
 	if (action === "remove" || action === "clean") {
 		const name = typeof args.name === "string" ? args.name : "";
 		const version = typeof args.resolvedVersion === "string" ? `@${args.resolvedVersion}` : "";
 		const ecosystem = typeof args.ecosystem === "string" ? args.ecosystem : "";
 		const identity = name ? `${name}${version}` : ecosystem;
-		return `${label} ${theme.fg("accent", action)}${identity ? ` ${theme.fg("dim", identity)}` : ""}`;
+		return `${label}${identity ? ` ${theme.fg("accent", identity)}` : ""}`;
 	}
 	const name = typeof args.name === "string" ? args.name : "";
 	const version = typeof args.version === "string" ? `@${args.version}` : "";

package/extension/src/presentation/model-content.ts

@@ -0,0 +1,62 @@
+export const DEFAULT_MODEL_CONTENT_BYTES = 32_768;
+const MAX_COLLECTION_ENTRIES = 24;
+const MAX_DEPTH = 4;
+
+function scalarText(value: unknown): string | undefined {
+	if (value === null) return "none";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	return undefined;
+}
+
+function appendSemanticLines(lines: string[], value: unknown, path: string, depth: number): void {
+	const scalar = scalarText(value);
+	if (scalar !== undefined) {
+		lines.push(`${path}: ${scalar}`);
+		return;
+	}
+	if (depth >= MAX_DEPTH) {
+		lines.push(`${path}: [nested value omitted]`);
+		return;
+	}
+	if (Array.isArray(value)) {
+		lines.push(`${path} (${value.length})`);
+		for (const [index, entry] of value.slice(0, MAX_COLLECTION_ENTRIES).entries()) appendSemanticLines(lines, entry, `${path}[${index}]`, depth + 1);
+		if (value.length > MAX_COLLECTION_ENTRIES) lines.push(`${path}: ${value.length - MAX_COLLECTION_ENTRIES} more entries omitted`);
+		return;
+	}
+	if (typeof value === "object" && value !== null) {
+		const entries = Object.entries(value).slice(0, MAX_COLLECTION_ENTRIES);
+		if (entries.length === 0) lines.push(`${path}: none`);
+		for (const [key, entry] of entries) appendSemanticLines(lines, entry, path ? `${path}.${key}` : key, depth + 1);
+		if (Object.keys(value).length > MAX_COLLECTION_ENTRIES) lines.push(`${path || "result"}: additional fields omitted`);
+		return;
+	}
+	lines.push(`${path}: unavailable`);
+}
+
+/** Bounds UTF-8 model-facing text independently from presentation details. */
+export function boundModelContentText(full: string, maxBytes = DEFAULT_MODEL_CONTENT_BYTES): string {
+	if (!Number.isInteger(maxBytes) || maxBytes < 64) throw new Error("model content maxBytes must be an integer of at least 64");
+	if (Buffer.byteLength(full, "utf8") <= maxBytes) return full;
+	const suffix = "\n[model content truncated]";
+	const budget = maxBytes - Buffer.byteLength(suffix, "utf8");
+	let bytes = Buffer.from(full, "utf8").subarray(0, Math.max(0, budget));
+	let prefix = "";
+	while (bytes.length > 0) {
+		try {
+			prefix = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+			break;
+		} catch {
+			bytes = bytes.subarray(0, -1);
+		}
+	}
+	return `${prefix}${suffix}`;
+}
+
+/** Formats an operation outcome as bounded, semantic plain text for model consumption. */
+export function formatSemanticModelContent(title: string, value: unknown, maxBytes = DEFAULT_MODEL_CONTENT_BYTES): string {
+	const lines = [title];
+	appendSemanticLines(lines, value, "", 0);
+	return boundModelContentText(lines.join("\n"), maxBytes);
+}