@danypops/pi-lector 0.13.9 → 0.14.0

package/extension/src/apply-patch/rendering.ts

@@ -1,6 +1,7 @@
 import type { EditOutcome } from "@danypops/lector";
 import { renderDiffLines, renderTruncatedList, type TextMeasure } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /**
  * The applied result (EditOutcome) only carries a hash transition, not the
@@ -15,7 +16,7 @@ const DEFAULT_VISIBLE_PATCH_LINES = 12;
 
 export function formatApplyPatchCall(args: { path?: unknown; patchText?: unknown }, theme: LectorTheme, measure?: TextMeasure): string {
 	const path = typeof args.path === "string" ? args.path : "";
-	const header = `${theme.fg("toolTitle", theme.bold("apply_patch"))} ${theme.fg("accent", path)}`;
+	const header = `${theme.fg("toolTitle", theme.bold(presentationTitle("apply_patch")))} ${theme.fg("accent", path)}`;
 	if (typeof args.patchText !== "string" || args.patchText.length === 0) return header;
 
 	const styledLines = renderDiffLines(

package/extension/src/code-intelligence/operations.ts

@@ -1,5 +1,9 @@
 import type { JobSnapshot, OperationInputs, OperationOutputs, PopulateSymbolGraphResult, SymbolEdgeKind, SymbolNode } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath, workspaceForPathOrDirectory } from "../lector-client.ts";
+import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
+
+const CODE_ACTION_PREVIEW_PERMISSIONS = ["workspace:read"];
+const CODE_ACTION_APPLY_PERMISSIONS = ["workspace:write"];
 
 /**
  * Thin wrappers over Lector's code-intelligence operations: goToDefinition,
@@ -34,9 +38,50 @@ export interface CodeIntelligenceOperations {
 	hover(path: string, line: number, character: number): Promise<OperationOutputs["workspace.hover"]>;
 	documentSymbols(path: string): Promise<OperationOutputs["workspace.documentSymbols"]>;
 	diagnostics(path: string): Promise<OperationOutputs["workspace.diagnostics"]>;
+	previewCodeActions(
+		path: string,
+		input: Omit<OperationInputs["workspace.previewCodeActions"], "workspaceId" | "path">,
+		call: LectorVehicleCall,
+	): Promise<OperationOutputs["workspace.previewCodeActions"]>;
+	applyCodeAction(
+		path: string,
+		previewId: OperationInputs["workspace.applyCodeAction"]["previewId"],
+		call: LectorVehicleCall,
+	): Promise<OperationOutputs["workspace.applyCodeAction"]>;
+	diagnosticDelta(
+		path: string,
+		source: OperationInputs["workspace.diagnosticDelta"]["source"],
+		bounds?: Omit<OperationInputs["workspace.diagnosticDelta"], "workspaceId" | "source">,
+	): Promise<OperationOutputs["workspace.diagnosticDelta"]>;
 	prepareCallHierarchy(path: string, line: number, character: number): Promise<OperationOutputs["workspace.prepareCallHierarchy"]>;
 	incomingCalls(path: string, line: number, character: number): Promise<OperationOutputs["workspace.incomingCalls"]>;
 	outgoingCalls(path: string, line: number, character: number): Promise<OperationOutputs["workspace.outgoingCalls"]>;
+	prepareTypeHierarchy(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.prepareTypeHierarchy"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.prepareTypeHierarchy"]>;
+	supertypes(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.supertypes"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.supertypes"]>;
+	subtypes(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.subtypes"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.subtypes"]>;
+	impactAnalysis(
+		path: string,
+		source: OperationInputs["workspace.impactAnalysis"]["source"],
+		bounds: Pick<
+			OperationInputs["workspace.impactAnalysis"],
+			"maxDepth" | "maxNodes" | "maxEdges" | "maxBytes" | "deadlineMs" | "coverage" | "autoPopulate" | "maxFiles" | "maxSymbolsPerFile"
+		>,
+	): Promise<OperationOutputs["workspace.impactAnalysis"]>;
 	/**
 	 * Not exposed as a standalone Pi tool -- every workspace auto-populates on first touch via
 	 * monitorWorkspaceCache (workspace-cache/operations.ts). Kept here as an internal capability
@@ -46,7 +91,14 @@ export interface CodeIntelligenceOperations {
 	populateSymbolGraph(path: string, maxFiles: number, maxSymbolsPerFile: number, waitMs?: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	/** Not exposed as a standalone Pi tool -- see populateSymbolGraph. */
 	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
-	reachableFrom(path: string, line: number, character: number, maxDepth: number, kind?: SymbolEdgeKind): Promise<readonly SymbolNode[]>;
+	reachableFrom(
+		path: string,
+		line: number,
+		character: number,
+		maxDepth: number,
+		kind?: SymbolEdgeKind,
+		autoPopulation?: Pick<OperationInputs["workspace.reachableFrom"], "autoPopulate" | "maxFiles" | "maxSymbolsPerFile">,
+	): Promise<readonly SymbolNode[]>;
 	/** Never spawns a symbol index -- safe to call opportunistically (e.g. before deciding whether to enrich a result). */
 	hasWarmIndex(path: string): Promise<boolean>;
 	workspaceMap(path: string, maxNodes: number, maxEdges: number, maxEntries: number, maxBytes: number): Promise<OperationOutputs["workspace.map"]>;
@@ -120,6 +172,36 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 				},
 			);
 		},
+		async previewCodeActions(path, input, call) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<OperationOutputs["workspace.previewCodeActions"]>(
+						"workspace.previewCodeActions",
+						{ workspaceId, path, ...input },
+						CODE_ACTION_PREVIEW_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async applyCodeAction(path, previewId, call) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<OperationOutputs["workspace.applyCodeAction"]>(
+						"workspace.applyCodeAction",
+						{ workspaceId, previewId },
+						CODE_ACTION_APPLY_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async diagnosticDelta(path, source, bounds) {
+			return withWorkspace(
+				() => workspaceForPathOrDirectory(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.diagnosticDelta", { workspaceId, source, ...bounds }),
+			);
+		},
 		async prepareCallHierarchy(path, line, character) {
 			return withWorkspace(
 				() => workspaceForCodeIntelligencePath(path),
@@ -147,6 +229,30 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 				},
 			);
 		},
+		async prepareTypeHierarchy(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.prepareTypeHierarchy", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async supertypes(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.supertypes", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async subtypes(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.subtypes", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async impactAnalysis(path, source, bounds) {
+			return withWorkspace(
+				() => workspaceForPathOrDirectory(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.impactAnalysis", { workspaceId, source, ...bounds }),
+			);
+		},
 		async populateSymbolGraph(path, maxFiles, maxSymbolsPerFile, waitMs = 500) {
 			return withWorkspace(
 				() => workspaceForPathOrDirectory(path),
@@ -167,12 +273,12 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 			const { job } = await client.call("job.status", { jobId });
 			return job;
 		},
-		async reachableFrom(path, line, character, maxDepth, kind) {
+		async reachableFrom(path, line, character, maxDepth, kind, autoPopulation) {
 			return withWorkspace(
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { symbols } = await client.call("workspace.reachableFrom", { workspaceId, path, line, character, maxDepth, kind });
+					const { symbols } = await client.call("workspace.reachableFrom", { workspaceId, path, line, character, maxDepth, kind, ...autoPopulation });
 					return symbols;
 				},
 			);

package/extension/src/code-intelligence/rendering.ts

@@ -5,6 +5,7 @@ import type {
 	Hover,
 	IncomingCall,
 	IntelligenceProvenance,
+	OperationOutputs,
 	OutgoingCall,
 	SymbolNode,
 	WorkspaceLocation,
@@ -13,6 +14,7 @@ import type {
 import { keyHint, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import { colorForKind, formatLocation, type LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /**
  * Custom TUI rendering for the code-intelligence tools: go_to_definition,
@@ -27,6 +29,7 @@ const DEFAULT_VISIBLE_LOCATIONS = 8;
 const DEFAULT_VISIBLE_SYMBOLS = 12;
 const DEFAULT_VISIBLE_DIAGNOSTICS = 12;
 const DEFAULT_VISIBLE_CALLS = 12;
+const DEFAULT_VISIBLE_CHANGES = 12;
 
 const DIAGNOSTIC_SEVERITY_COLOR: Record<Diagnostic["severity"], ThemeColor> = {
 	error: "error",
@@ -39,7 +42,7 @@ function formatPositionalCall(toolName: string, args: { path?: unknown; line?: u
 	const path = typeof args.path === "string" ? args.path : "";
 	const line = typeof args.line === "number" ? args.line : "?";
 	const character = typeof args.character === "number" ? args.character : "?";
-	return `${theme.fg("toolTitle", theme.bold(toolName))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle(toolName)))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
 }
 
 function moreLine(theme: LectorTheme): (hidden: number) => string {
@@ -108,7 +111,7 @@ export function formatHoverResult(hover: Hover | undefined, expanded: boolean, t
 
 export function formatDocumentSymbolsCall(args: { path?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
-	return `${theme.fg("toolTitle", theme.bold("document_symbols"))} ${theme.fg("accent", path)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("document_symbols")))} ${theme.fg("accent", path)}`;
 }
 
 /** Flattens a hierarchical DocumentSymbolEntry[] into (depth, entry) pairs, depth-first, for bounded rendering. */
@@ -147,7 +150,7 @@ export function formatDocumentSymbolsResult(symbols: readonly DocumentSymbolEntr
 
 export function formatDiagnosticsCall(args: { path?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
-	return `${theme.fg("toolTitle", theme.bold("diagnostics"))} ${theme.fg("accent", path)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("diagnostics")))} ${theme.fg("accent", path)}`;
 }
 
 export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | undefined, expanded: boolean, theme: LectorTheme): string {
@@ -171,6 +174,127 @@ export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | und
 	return lines.join("\n");
 }
 
+function formatPathCall(toolName: string, args: { path?: unknown }, theme: LectorTheme, qualifier = ""): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle(toolName)))}${qualifier ? ` ${theme.fg("muted", qualifier)}` : ""} ${theme.fg("accent", path)}`;
+}
+
+export function formatCodeActionPreviewCall(
+	args: { path?: unknown; startLine?: unknown; startCharacter?: unknown; endLine?: unknown; endCharacter?: unknown },
+	theme: LectorTheme,
+): string {
+	const range = `${typeof args.startLine === "number" ? args.startLine : "?"}:${typeof args.startCharacter === "number" ? args.startCharacter : "?"}-${typeof args.endLine === "number" ? args.endLine : "?"}:${typeof args.endCharacter === "number" ? args.endCharacter : "?"}`;
+	return formatPathCall("code_action_preview", args, theme, range);
+}
+
+export function formatCodeActionPreviewResult(
+	result: OperationOutputs["workspace.previewCodeActions"] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.actions.length === 0) return theme.fg("dim", "No code actions.");
+	return [
+		theme.fg("muted", `${result.actions.length} code action${result.actions.length === 1 ? "" : "s"}:`),
+		...renderTruncatedList({
+			items: result.actions,
+			expanded,
+			visibleCount: DEFAULT_VISIBLE_CHANGES,
+			formatItem: (action) => {
+				const state = action.disabledReason
+					? theme.fg("warning", `disabled: ${action.disabledReason}`)
+					: action.preferred
+						? theme.fg("success", "preferred")
+						: "";
+				const paths = action.affectedPaths.length > 0 ? action.affectedPaths.join(", ") : "command only";
+				return `  ${theme.bold(action.title)}${action.kind ? ` (${action.kind})` : ""} -- ${paths}${state ? ` -- ${state}` : ""}`;
+			},
+			moreLine: moreLine(theme),
+			truncationWarning: result.truncated || result.deadlineReached ? theme.fg("warning", "results truncated by the requested bounds") : undefined,
+		}),
+	].join("\n");
+}
+
+export function formatCodeActionApplyCall(args: { path?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("code_action_apply", args, theme);
+}
+
+export function formatCodeActionApplyResult(result: OperationOutputs["workspace.applyCodeAction"] | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No code-action result.");
+	const lines = result.touchedPaths.map((path) => `  ${path}`);
+	if (result.transactionId) lines.push(theme.fg("muted", `transaction ${result.transactionId}`));
+	if (result.pendingCommand) lines.push(theme.fg("warning", `pending command ${result.pendingCommand.command}`));
+	return lines.length > 0 ? lines.join("\n") : theme.fg("dim", "Code action made no file changes.");
+}
+
+export function formatDiagnosticDeltaCall(args: { path?: unknown; source?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("diagnostic_delta", args, theme, typeof args.source === "string" ? args.source : "");
+}
+
+export function formatDiagnosticDeltaResult(result: OperationOutputs["workspace.diagnosticDelta"] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No diagnostic delta.");
+	const changes = [
+		...result.introduced.map((diagnostic) => ({ label: "introduced", diagnostic })),
+		...result.resolved.map((diagnostic) => ({ label: "resolved", diagnostic })),
+		...result.changed.map(({ after }) => ({ label: "changed", diagnostic: after })),
+	];
+	if (changes.length === 0) return theme.fg("success", "No diagnostic changes.");
+	return renderTruncatedList({
+		items: changes,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CHANGES,
+		formatItem: ({ label, diagnostic }) =>
+			`${theme.fg(label === "introduced" ? "error" : label === "resolved" ? "success" : "warning", label)} ${formatLocation(theme, diagnostic.range.path, diagnostic.range.start.line, diagnostic.range.start.character)} -- ${diagnostic.message}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "results truncated by maxResults/maxBytes") : undefined,
+	}).join("\n");
+}
+
+export function formatTypeHierarchyCall(args: { direction?: unknown; path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	const direction = typeof args.direction === "string" ? args.direction : undefined;
+	const path = typeof args.path === "string" ? args.path : "";
+	const line = typeof args.line === "number" ? args.line : "?";
+	const character = typeof args.character === "number" ? args.character : "?";
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("type_hierarchy", direction)))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
+}
+
+export function formatTypeHierarchyResult(
+	result: OperationOutputs["workspace.prepareTypeHierarchy"] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.items.length === 0) return theme.fg("dim", "No type-hierarchy items found.");
+	return renderTruncatedList({
+		items: result.items,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CALLS,
+		formatItem: (item) => `  ${formatCallHierarchyEntry(item, theme)}${item.detail ? theme.fg("dim", ` -- ${item.detail}`) : ""}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "results truncated by the requested bounds") : undefined,
+	}).join("\n");
+}
+
+export function formatImpactAnalysisCall(args: { path?: unknown; source?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("impact_analysis", args, theme, typeof args.source === "string" ? args.source : "");
+}
+
+export function formatImpactAnalysisResult(result: OperationOutputs["workspace.impactAnalysis"] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No impact-analysis result.");
+	const impacts = [
+		...result.changedSymbols.map(({ symbol, side }) => ({ label: `changed ${side}`, symbol })),
+		...result.impactedSymbols.map(({ symbol, depth }) => ({ label: `impact depth=${depth}`, symbol })),
+		...result.relatedTests.map(({ symbol, evidence }) => ({ label: `test ${evidence.kind}`, symbol })),
+	];
+	if (impacts.length === 0) return theme.fg("dim", "No changed symbols resolved.");
+	return renderTruncatedList({
+		items: impacts,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CHANGES,
+		formatItem: ({ label, symbol }) => `${theme.fg("muted", label)} ${formatCallHierarchyEntry(symbol, theme)}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated || result.deadlineReached ? theme.fg("warning", "analysis truncated by the requested bounds") : undefined,
+	}).join("\n");
+}
+
 function formatCallHierarchyEntry(entry: { kind: string; name: string; location: WorkspaceLocation }, theme: LectorTheme): string {
 	const kind = theme.fg(colorForKind(entry.kind), entry.kind);
 	const name = theme.fg("text", theme.bold(entry.name));
@@ -192,7 +316,7 @@ export function formatCallHierarchyCall(args: { direction?: unknown; path?: unkn
 	const path = typeof args.path === "string" ? args.path : "";
 	const line = typeof args.line === "number" ? args.line : "?";
 	const character = typeof args.character === "number" ? args.character : "?";
-	return `${theme.fg("toolTitle", theme.bold("call_hierarchy"))} ${theme.fg("muted", direction)} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("call_hierarchy", direction)))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
 }
 
 function formatPrepareCallHierarchyResult(items: readonly CallHierarchyEntry[] | undefined, theme: LectorTheme): string {
@@ -265,7 +389,7 @@ export function formatReachableFromResult(symbols: readonly SymbolNode[] | undef
 export function formatWorkspaceMapCall(args: { path?: unknown; maxEntries?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
 	const maxEntries = typeof args.maxEntries === "number" ? ` (top ${args.maxEntries})` : "";
-	return `${theme.fg("toolTitle", theme.bold("workspace_map"))} ${theme.fg("dim", path)}${theme.fg("muted", maxEntries)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("workspace_map")))} ${theme.fg("dim", path)}${theme.fg("muted", maxEntries)}`;
 }
 
 export function formatWorkspaceMapResult(result: WorkspaceMapResult | undefined, expanded: boolean, theme: LectorTheme): string {

package/extension/src/cross-workspace-search/rendering.ts

@@ -3,14 +3,19 @@ import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import { describeFindSymbolSources } from "../find-symbols/rendering.ts";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 import type { CrossWorkspaceOutcome } from "./operations.ts";
 
 const DEFAULT_VISIBLE_PER_WORKSPACE = 10;
 
-export function formatCrossWorkspaceCall(args: { directories?: unknown; query?: unknown }, theme: LectorTheme): string {
+export function formatCrossWorkspaceCall(
+	toolName: "find_symbols_across_projects" | "search_code_across_projects",
+	args: { directories?: unknown; query?: unknown },
+	theme: LectorTheme,
+): string {
 	const directories = Array.isArray(args.directories) ? args.directories.filter((d): d is string => typeof d === "string") : [];
 	const query = typeof args.query === "string" ? args.query : "";
-	return `${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", `across ${directories.length} project(s)`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle(toolName)))} ${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", `across ${directories.length} project(s)`)}`;
 }
 
 function formatOutcomeHeader(entry: CrossWorkspaceOutcome<unknown>, theme: LectorTheme): string {
@@ -83,6 +88,9 @@ export function formatSearchTextAcrossProjectsResult(
 		lines.push(formatOutcomeHeader(entry, theme));
 		const { outcome } = entry;
 		if (outcome.status !== "ready") continue;
+		if (outcome.result.provenance) {
+			lines.push(theme.fg("dim", `  lexical via ${outcome.result.provenance.backend} (${outcome.result.provenance.indexState})`));
+		}
 		if (outcome.result.matches.length === 0) {
 			lines.push(theme.fg("dim", "  no matches"));
 			continue;

package/extension/src/editor/editor-state.ts

@@ -4,6 +4,26 @@ export type EditorMode = "normal" | "insert" | "command";
 
 export type EditorAction = { kind: "save" } | { kind: "save-and-quit" } | { kind: "quit" } | { kind: "hover" };
 
+export interface EditorSourcePosition {
+	/** One-based line number. */
+	readonly line: number;
+	/** One-based UTF-16 code-unit position within the line. */
+	readonly character: number;
+}
+
+export type EditorPositionErrorCode = "line-out-of-range" | "character-out-of-range";
+
+/** Reports why a requested source position cannot identify a cursor location in the current buffer. */
+export class EditorPositionError extends Error {
+	constructor(
+		readonly code: EditorPositionErrorCode,
+		message: string,
+	) {
+		super(`${code}: ${message}`);
+		this.name = "EditorPositionError";
+	}
+}
+
 const BACKSPACE_KEYS = new Set(["\x7f", "\b"]);
 
 /**
@@ -27,8 +47,25 @@ export class EditorState {
 	private insertPendingJ = false;
 	private yankedLine: string | undefined;
 
-	constructor(content: string) {
+	constructor(content: string, initialPosition?: EditorSourcePosition) {
 		this.buffer = new LiveBuffer(content);
+		if (initialPosition) this.moveToInitialPosition(initialPosition);
+	}
+
+	private moveToInitialPosition(position: EditorSourcePosition): void {
+		if (!Number.isSafeInteger(position.line) || position.line < 1 || position.line > this.buffer.lineCount) {
+			throw new EditorPositionError("line-out-of-range", `Line ${position.line} is outside this ${this.buffer.lineCount}-line buffer`);
+		}
+		const lineLength = this.buffer.lineText(position.line).length;
+		const maxCharacter = Math.max(lineLength, 1);
+		if (!Number.isSafeInteger(position.character) || position.character < 1 || position.character > maxCharacter) {
+			throw new EditorPositionError(
+				"character-out-of-range",
+				`Character ${position.character} is outside line ${position.line}'s ${lineLength} UTF-16 code units`,
+			);
+		}
+		this.cursorLine = position.line;
+		this.cursorCharacter = position.character;
 	}
 
 	get currentLineText(): string {

package/extension/src/editor/index.ts

@@ -29,7 +29,14 @@
  */
 
 export type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
-export { type EditorAction, type EditorMode, EditorState } from "./editor-state.ts";
+export {
+	type EditorAction,
+	type EditorMode,
+	EditorPositionError,
+	type EditorPositionErrorCode,
+	type EditorSourcePosition,
+	EditorState,
+} from "./editor-state.ts";
 export type { EditorTheme } from "./editor-theme.ts";
 export { ExplorerComponent, type ExplorerResult, type ExplorerViewState, joinExplorerPath } from "./explorer-component.ts";
 // runExplorerFlow is pure orchestration over the two interfaces above (browse, open a file into
@@ -44,4 +51,5 @@ export {
 	type EditorHoverRequest,
 	ModalEditorComponent,
 	type ModalEditorHost,
+	type ModalEditorOptions,
 } from "./modal-editor-component.ts";

package/extension/src/editor/modal-editor-component.ts

@@ -4,7 +4,7 @@ import { contentHashOf, highlightSpans } from "@danypops/lector";
 import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import type { EditorAction } from "./editor-state.ts";
+import type { EditorAction, EditorSourcePosition } from "./editor-state.ts";
 import { EditorState } from "./editor-state.ts";
 import type { EditorTheme } from "./editor-theme.ts";
 
@@ -26,6 +26,11 @@ export type EditorHoverOutcome =
 	| { readonly kind: "ready"; readonly hover?: { readonly contents: string } }
 	| { readonly kind: "stale-active-buffer"; readonly bufferHash: ContentHash };
 
+export interface ModalEditorOptions {
+	/** Positions the cursor using one-based UTF-16 coordinates and scrolls it into the first viewport. */
+	readonly initialPosition?: EditorSourcePosition;
+}
+
 export interface ModalEditorHost {
 	filePath: string;
 	/** Saves the buffer's current text through Lector's hash-guarded write. Throws (surfaced as a status message, not a crash) on a genuinely concurrent external change. */
@@ -65,13 +70,14 @@ export class ModalEditorComponent implements Component {
 	private statusMessage = "";
 	private highlightCache: { text: string; spans: readonly HighlightSpan[] } | undefined;
 
-	constructor(tui: TUI, theme: EditorTheme, host: ModalEditorHost, content: string, done: () => void) {
+	constructor(tui: TUI, theme: EditorTheme, host: ModalEditorHost, content: string, done: () => void, options: ModalEditorOptions = {}) {
 		this.tui = tui;
 		this.theme = theme;
 		this.host = host;
 		this.done = done;
 		this.extension = extname(host.filePath);
-		this.state = new EditorState(content);
+		this.state = new EditorState(content, options.initialPosition);
+		this.scrollToKeepCursorVisible();
 		this.refreshHighlightsSafely();
 	}
 

package/extension/src/external-search/rendering.ts

@@ -1,27 +1,61 @@
 import type { GithubRepoSearchResult, NpmPackageCandidate, SourcegraphCodeCandidate } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 type ExternalSearchAction = "github_repos" | "npm_packages" | "sourcegraph_code";
 
 export function formatExternalSearchCall(action: ExternalSearchAction, args: { query?: unknown }, theme: LectorTheme): string {
-	const label = theme.fg("toolTitle", theme.bold("external_search"));
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("external_search", action)));
 	const query = typeof args.query === "string" ? args.query : "";
-	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", query)}`;
+	return `${label} ${theme.fg("accent", `"${query}"`)}`;
 }
 
-export function formatGithubRepoSearchResult(result: GithubRepoSearchResult | undefined, theme: LectorTheme): string {
+const VISIBLE_CANDIDATES = 8;
+
+function boundedCandidates<T>(candidates: readonly T[], expanded: boolean): { visible: readonly T[]; more: number } {
+	const visible = expanded ? candidates : candidates.slice(0, VISIBLE_CANDIDATES);
+	return { visible, more: candidates.length - visible.length };
+}
+
+export function formatGithubRepoSearchResult(result: GithubRepoSearchResult | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!result) return theme.fg("dim", "No result.");
-	const count = result.candidates.length;
-	const summary = count === 0 ? theme.fg("dim", "no repositories matched") : theme.fg("success", `${count} repositor${count === 1 ? "y" : "ies"}`);
-	return result.authenticated ? summary : `${summary} ${theme.fg("warning", "(unauthenticated -- lower rate limit)")}`;
+	if (result.candidates.length === 0) return theme.fg("dim", "no repositories matched");
+	const { visible, more } = boundedCandidates(result.candidates, expanded);
+	const lines = visible.map(
+		(candidate) =>
+			`${theme.fg("accent", `${candidate.host}/${candidate.owner}/${candidate.repo}`)} · ${candidate.stars} stars${candidate.language ? ` · ${candidate.language}` : ""}${candidate.description ? `\n  ${candidate.description}` : ""}`,
+	);
+	if (more > 0) lines.push(theme.fg("muted", `… ${more} more (expand to show)`));
+	if (!result.authenticated) lines.push(theme.fg("warning", "unauthenticated -- lower rate limit"));
+	return lines.join("\n");
 }
 
-export function formatNpmPackageSearchResult(result: { candidates: readonly NpmPackageCandidate[] } | undefined, theme: LectorTheme): string {
-	const count = result?.candidates.length ?? 0;
-	return count === 0 ? theme.fg("dim", "no packages matched") : theme.fg("success", `${count} package${count === 1 ? "" : "s"}`);
+export function formatNpmPackageSearchResult(
+	result: { candidates: readonly NpmPackageCandidate[] } | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.candidates.length === 0) return theme.fg("dim", "no packages matched");
+	const { visible, more } = boundedCandidates(result.candidates, expanded);
+	const lines = visible.map(
+		(candidate) =>
+			`${theme.fg("accent", `${candidate.name}@${candidate.version}`)} · score ${candidate.score.toFixed(3)}${candidate.description ? `\n  ${candidate.description}` : ""}`,
+	);
+	if (more > 0) lines.push(theme.fg("muted", `… ${more} more (expand to show)`));
+	return lines.join("\n");
 }
 
-export function formatSourcegraphCodeSearchResult(result: { candidates: readonly SourcegraphCodeCandidate[] } | undefined, theme: LectorTheme): string {
-	const count = result?.candidates.length ?? 0;
-	return count === 0 ? theme.fg("dim", "no code matches") : theme.fg("success", `${count} match${count === 1 ? "" : "es"}`);
+export function formatSourcegraphCodeSearchResult(
+	result: { candidates: readonly SourcegraphCodeCandidate[] } | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.candidates.length === 0) return theme.fg("dim", "no code matches");
+	const { visible, more } = boundedCandidates(result.candidates, expanded);
+	const lines = visible.map((candidate) => {
+		const matches = candidate.lineMatches.slice(0, expanded ? candidate.lineMatches.length : 3);
+		return `${theme.fg("accent", `${candidate.repository}/${candidate.path}`)}\n${matches.map((match) => `  ${match.line}: ${match.preview}`).join("\n")}`;
+	});
+	if (more > 0) lines.push(theme.fg("muted", `… ${more} more (expand to show)`));
+	return lines.join("\n");
 }

package/extension/src/find-files/rendering.ts

@@ -2,13 +2,14 @@ import type { FindFilesResult } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 const DEFAULT_VISIBLE_PATHS = 40;
 
 export function formatFindFilesCall(args: { directory?: unknown; patterns?: unknown }, theme: LectorTheme): string {
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	const patterns = Array.isArray(args.patterns) ? args.patterns.filter((p): p is string => typeof p === "string") : [];
-	return `${theme.fg("toolTitle", theme.bold("find_files"))} ${theme.fg("accent", patterns.map((p) => `"${p}"`).join(", "))} ${theme.fg("dim", directory)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("find_files")))} ${theme.fg("accent", patterns.map((p) => `"${p}"`).join(", "))} ${theme.fg("dim", directory)}`;
 }
 
 export function formatFindFilesResult(result: FindFilesResult | undefined, expanded: boolean, theme: LectorTheme): string {

package/extension/src/find-symbols/rendering.ts

@@ -2,6 +2,7 @@ import type { SymbolSearchResult, WorkspaceSymbol } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import { colorForKind, formatLocation, type LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /**
  * Custom TUI rendering for find_symbols -- the one Lector-backed tool with
@@ -18,7 +19,7 @@ const DEFAULT_VISIBLE_RESULTS = 8;
 
 export function formatFindSymbolsCall(args: { query?: unknown; directory?: unknown }, theme: FindSymbolsTheme): string {
 	const query = typeof args.query === "string" ? args.query : "";
-	let content = `${theme.fg("toolTitle", theme.bold("find_symbols"))} ${theme.fg("accent", `"${query}"`)}`;
+	let content = `${theme.fg("toolTitle", theme.bold(presentationTitle("find_symbols")))} ${theme.fg("accent", `"${query}"`)}`;
 	if (typeof args.directory === "string" && args.directory.length > 0) {
 		content += ` ${theme.fg("muted", `in ${args.directory}`)}`;
 	}