@danypops/pi-lector 0.13.9 → 0.14.0

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);
+}

package/extension/src/presentation/presentation-contract.ts

@@ -0,0 +1,148 @@
+import type { JsonValue } from "@danypops/vehicle-core";
+import type { AgentToolResult, AgentToolUpdateCallback, Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { TSchema } from "typebox";
+import { boundModelContentText, DEFAULT_MODEL_CONTENT_BYTES } from "./model-content.ts";
+import { type PresentationFamily, presentationFamily } from "./tool-presentation.ts";
+
+export const LECTOR_PRESENTATION_SCHEMA = "pi-lector.presentation/v1";
+export const DEFAULT_LECTOR_PRESENTATION_MAX_BYTES = 128 * 1024;
+
+interface LectorPresentationBase {
+	readonly schema: typeof LECTOR_PRESENTATION_SCHEMA;
+	readonly tool: string;
+	readonly action: string | null;
+	readonly payload: JsonValue;
+}
+
+/** Versioned presentation variants persisted independently from model-facing content. */
+export type LectorToolPresentation = {
+	readonly [Family in PresentationFamily]: LectorPresentationBase & { readonly family: Family };
+}[PresentationFamily];
+
+export type LectorPresentationEnvelope = LectorToolPresentation;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJsonValue);
+	if (isRecord(value)) return Object.values(value).every(isJsonValue);
+	return false;
+}
+
+function serializedJsonValue(value: unknown): JsonValue {
+	if (value === undefined) return null;
+	let serialized: string;
+	try {
+		serialized = JSON.stringify(value, (_key, candidate: unknown) => {
+			if (typeof candidate === "number" && !Number.isFinite(candidate)) throw new TypeError("non-finite number");
+			if (typeof candidate === "bigint" || typeof candidate === "function" || typeof candidate === "symbol") {
+				throw new TypeError(`unsupported ${typeof candidate}`);
+			}
+			return candidate;
+		});
+	} catch (error) {
+		throw new TypeError(`presentation details must be JSON serializable: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const parsed: unknown = JSON.parse(serialized);
+	if (!isJsonValue(parsed)) throw new TypeError("presentation details must contain only JSON values");
+	return parsed;
+}
+
+/** Projects one tool's renderer details into the versioned, serializable session boundary. */
+export function projectLectorPresentation(
+	tool: string,
+	details: unknown,
+	maxBytes = DEFAULT_LECTOR_PRESENTATION_MAX_BYTES,
+	actionOverride?: string,
+): LectorPresentationEnvelope {
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new TypeError("presentation maxBytes must be a positive integer");
+	const action = actionOverride ?? (isRecord(details) && typeof details.action === "string" ? details.action : null);
+	const envelope: LectorPresentationEnvelope = {
+		schema: LECTOR_PRESENTATION_SCHEMA,
+		tool,
+		action,
+		family: presentationFamily(tool, action ?? undefined),
+		payload: serializedJsonValue(details),
+	};
+	const bytes = Buffer.byteLength(JSON.stringify(envelope), "utf8");
+	if (bytes > maxBytes) throw new RangeError(`presentation details exceed ${maxBytes} bytes (${bytes} observed)`);
+	return envelope;
+}
+
+/** Validates the shared envelope. Domain renderers retain responsibility for validating their payload variant. */
+export function parseLectorPresentation(details: unknown, expectedTool: string): JsonValue | undefined {
+	if (!isRecord(details)) return undefined;
+	if (details.schema !== LECTOR_PRESENTATION_SCHEMA || details.tool !== expectedTool || !("payload" in details)) return undefined;
+	if (details.action !== null && typeof details.action !== "string") return undefined;
+	if (details.family !== presentationFamily(expectedTool, typeof details.action === "string" ? details.action : undefined)) return undefined;
+	try {
+		return serializedJsonValue(details.payload);
+	} catch {
+		return undefined;
+	}
+}
+
+function fallbackText(result: AgentToolResult<unknown>, theme: Theme): Text {
+	const content = result.content
+		.filter((block): block is Extract<(typeof result.content)[number], { type: "text" }> => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+	return new Text(theme.fg("toolOutput", content || "No result."), 0, 0);
+}
+
+export interface LectorPresentationOptions {
+	readonly maxBytes?: number;
+	readonly maxModelContentBytes?: number;
+}
+
+/** Wraps a production tool so persisted renderer details cross one validated, bounded envelope. */
+export function withLectorPresentation<TParams extends TSchema, TDetails, TState>(
+	tool: ToolDefinition<TParams, TDetails, TState>,
+	options: LectorPresentationOptions = {},
+): ToolDefinition<TParams, LectorPresentationEnvelope, TState> {
+	const maxBytes = options.maxBytes ?? DEFAULT_LECTOR_PRESENTATION_MAX_BYTES;
+	const maxModelContentBytes = options.maxModelContentBytes ?? DEFAULT_MODEL_CONTENT_BYTES;
+	return {
+		...tool,
+		async execute(toolCallId, params, signal, onUpdate, context) {
+			const parameterRecord = params as Record<string, unknown>;
+			const action =
+				typeof parameterRecord.action === "string"
+					? parameterRecord.action
+					: typeof parameterRecord.direction === "string"
+						? parameterRecord.direction
+						: undefined;
+			const boundedContent = (content: AgentToolResult<unknown>["content"]): AgentToolResult<unknown>["content"] =>
+				content.map((block) => (block.type === "text" ? { ...block, text: boundModelContentText(block.text, maxModelContentBytes) } : block));
+			const wrappedUpdate: AgentToolUpdateCallback<TDetails> | undefined = onUpdate
+				? (update) =>
+						onUpdate({
+							...update,
+							content: boundedContent(update.content),
+							details: projectLectorPresentation(tool.name, update.details, maxBytes, action),
+						})
+				: undefined;
+			const result = await tool.execute(toolCallId, params, signal, wrappedUpdate, context);
+			return {
+				...result,
+				content: boundedContent(result.content),
+				details: projectLectorPresentation(tool.name, result.details, maxBytes, action),
+			};
+		},
+		renderResult(result, renderOptions, theme, context) {
+			const payload = parseLectorPresentation(result.details, tool.name);
+			if (payload === undefined && !renderOptions.isPartial && !context.isError) return fallbackText(result, theme);
+			if (!tool.renderResult) return fallbackText(result, theme);
+			// The envelope is the runtime validation boundary. Each existing domain renderer narrows
+			// its own payload variant; this is the single shared assertion that reconnects its generic.
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+			const domainDetails = payload as TDetails;
+			return tool.renderResult({ ...result, details: domainDetails }, renderOptions, theme, context);
+		},
+	};
+}

package/extension/src/presentation/tool-presentation.ts

@@ -0,0 +1,170 @@
+export type PresentationFamily =
+	| "source"
+	| "markdown"
+	| "symbols"
+	| "locations"
+	| "diagnostics"
+	| "diff"
+	| "mutation"
+	| "status"
+	| "table"
+	| "tree"
+	| "candidates"
+	| "semantic-text";
+
+interface PresentationPathSpec {
+	readonly title: string;
+	readonly family: PresentationFamily;
+}
+
+interface ToolPresentationSpec extends PresentationPathSpec {
+	readonly actions?: Readonly<Record<string, PresentationPathSpec>>;
+}
+
+export const LECTOR_TOOL_PRESENTATION_SPECS: Readonly<Record<string, ToolPresentationSpec>> = {
+	read: { title: "Read File", family: "source" },
+	write: { title: "Write File", family: "mutation" },
+	edit: { title: "Edit File", family: "diff" },
+	find_symbols: { title: "Find Symbols", family: "symbols" },
+	localize_context: { title: "Localize Context", family: "candidates" },
+	go_to_definition: { title: "Go to Definition", family: "locations" },
+	go_to_implementation: { title: "Go to Implementation", family: "locations" },
+	find_references: { title: "Find References", family: "locations" },
+	hover: { title: "Hover", family: "markdown" },
+	document_symbols: { title: "Document Symbols", family: "tree" },
+	diagnostics: { title: "Diagnostics", family: "diagnostics" },
+	code_action_preview: { title: "Preview Code Actions", family: "candidates" },
+	code_action_apply: { title: "Apply Code Action", family: "mutation" },
+	diagnostic_delta: { title: "Diagnostic Delta", family: "diagnostics" },
+	call_hierarchy: {
+		title: "Call Hierarchy",
+		family: "tree",
+		actions: {
+			prepare: { title: "Prepare Call Hierarchy", family: "symbols" },
+			incoming: { title: "Incoming Calls", family: "tree" },
+			outgoing: { title: "Outgoing Calls", family: "tree" },
+		},
+	},
+	type_hierarchy: {
+		title: "Type Hierarchy",
+		family: "tree",
+		actions: {
+			prepare: { title: "Prepare Type Hierarchy", family: "symbols" },
+			supertypes: { title: "Supertypes", family: "tree" },
+			subtypes: { title: "Subtypes", family: "tree" },
+		},
+	},
+	impact_analysis: { title: "Impact Analysis", family: "tree" },
+	reference_based_rename: { title: "Rename File by References", family: "mutation" },
+	rename: {
+		title: "Rename Symbol",
+		family: "mutation",
+		actions: {
+			prepare: { title: "Prepare Rename", family: "semantic-text" },
+			apply: { title: "Rename Symbol", family: "mutation" },
+		},
+	},
+	symbol_annotations: {
+		title: "Symbol Annotations",
+		family: "semantic-text",
+		actions: {
+			create: { title: "Create Symbol Annotation", family: "mutation" },
+			get: { title: "Show Symbol Annotation", family: "markdown" },
+			list: { title: "List Symbol Annotations", family: "table" },
+			refresh: { title: "Refresh Symbol Annotation", family: "mutation" },
+			scrub: { title: "Scrub Symbol Annotation", family: "mutation" },
+			restore: { title: "Restore Symbol Annotation", family: "mutation" },
+			contain: { title: "Contain Symbol Annotation", family: "mutation" },
+			uncontain: { title: "Uncontain Symbol Annotation", family: "mutation" },
+			tree: { title: "Annotation Tree", family: "tree" },
+		},
+	},
+	reachable_from: { title: "Reachable Symbols", family: "tree" },
+	workspace_map: { title: "Workspace Map", family: "symbols" },
+	workspace_cache: {
+		title: "Workspace Cache",
+		family: "status",
+		actions: {
+			status: { title: "Workspace Cache Status", family: "status" },
+			populate: { title: "Populate Workspace Cache", family: "status" },
+			wait: { title: "Wait for Cache Job", family: "status" },
+			job_status: { title: "Cache Job Status", family: "status" },
+		},
+	},
+	git: {
+		title: "Git",
+		family: "semantic-text",
+		actions: {
+			status: { title: "Git Status", family: "status" },
+			log: { title: "Git Log", family: "table" },
+			diff: { title: "Git Diff", family: "diff" },
+			"compare-symbol": { title: "Compare Symbol", family: "diff" },
+			show: { title: "Show File at Git Ref", family: "source" },
+			"grep-ref": { title: "Search Git Ref", family: "locations" },
+			"grep-history": { title: "Search Git History", family: "locations" },
+			"ls-ref": { title: "List Files at Git Ref", family: "table" },
+			"is-ancestor": { title: "Check Git Ancestry", family: "semantic-text" },
+			"worktree-add": { title: "Create Git Worktree", family: "mutation" },
+			"worktree-remove": { title: "Remove Git Worktree", family: "mutation" },
+		},
+	},
+	search_code: { title: "Search Code", family: "locations" },
+	find_files: { title: "Find Files", family: "table" },
+	line_edit: { title: "Edit Lines", family: "diff" },
+	apply_patch: { title: "Apply Patch", family: "diff" },
+	mutation_history: {
+		title: "Mutation History",
+		family: "table",
+		actions: {
+			list: { title: "Mutation History", family: "table" },
+			revert: { title: "Revert Mutation", family: "mutation" },
+			"revert-transaction": { title: "Revert Transaction", family: "mutation" },
+		},
+	},
+	package_source: {
+		title: "Package Source",
+		family: "semantic-text",
+		actions: {
+			resolve: { title: "Resolve Package Source", family: "semantic-text" },
+			list: { title: "List Package Sources", family: "table" },
+			remove: { title: "Remove Package Source", family: "mutation" },
+			clean: { title: "Clean Package Sources", family: "mutation" },
+		},
+	},
+	repo_cache: {
+		title: "Repository Cache",
+		family: "semantic-text",
+		actions: {
+			fetch: { title: "Fetch Repository", family: "status" },
+			list: { title: "List Repository Cache", family: "table" },
+			evict: { title: "Evict Repository", family: "mutation" },
+		},
+	},
+	external_search: {
+		title: "External Search",
+		family: "candidates",
+		actions: {
+			github_repos: { title: "Search GitHub Repositories", family: "candidates" },
+			npm_packages: { title: "Search npm Packages", family: "candidates" },
+			sourcegraph_code: { title: "Search Public Code", family: "candidates" },
+		},
+	},
+	find_symbols_across_projects: { title: "Find Symbols Across Projects", family: "symbols" },
+	search_code_across_projects: { title: "Search Code Across Projects", family: "locations" },
+};
+
+export function presentationTitle(toolName: string, action?: string): string {
+	const spec = LECTOR_TOOL_PRESENTATION_SPECS[toolName];
+	if (!spec) throw new Error(`no presentation specification for ${toolName}`);
+	return (action ? spec.actions?.[action]?.title : undefined) ?? spec.title;
+}
+
+export function presentationFamily(toolName: string, action?: string): PresentationFamily {
+	const spec = LECTOR_TOOL_PRESENTATION_SPECS[toolName];
+	if (!spec) throw new Error(`no presentation specification for ${toolName}`);
+	return (action ? spec.actions?.[action]?.family : undefined) ?? spec.family;
+}
+
+export function presentationPathCount(): number {
+	return Object.values(LECTOR_TOOL_PRESENTATION_SPECS).reduce((count, spec) => count + (spec.actions ? Object.keys(spec.actions).length : 1), 0);
+}

package/extension/src/repo-cache/rendering.ts

@@ -2,6 +2,7 @@ import type { CachedRepositoryEntry, CachedRepositoryPage, RepoFetchResult } fro
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import type { TableColumn } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /** Table has no row-count bound of its own; a cache can grow arbitrarily large even though repo_cache's own `maxResults` bounds any one page, so the display itself still needs a cap independent of that. */
 export const REPO_CACHE_VISIBLE_ROWS = 20;
@@ -17,16 +18,16 @@ export function formatRepoCacheCall(
 	args: { owner?: unknown; repo?: unknown; ref?: unknown; host?: unknown; text?: unknown },
 	theme: LectorTheme,
 ): string {
-	const label = theme.fg("toolTitle", theme.bold("repo_cache"));
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("repo_cache", action)));
 	if (action === "list") {
 		const filter = typeof args.text === "string" && args.text.length > 0 ? args.text : typeof args.repo === "string" ? args.repo : "";
-		return `${label} ${theme.fg("accent", "list")}${filter ? ` ${theme.fg("dim", filter)}` : ""}`;
+		return `${label}${filter ? ` ${theme.fg("accent", filter)}` : ""}`;
 	}
 	const host = typeof args.host === "string" && args.host.length > 0 ? args.host : "github.com";
 	const owner = typeof args.owner === "string" ? args.owner : "";
 	const repo = typeof args.repo === "string" ? args.repo : "";
 	const ref = typeof args.ref === "string" ? `@${args.ref}` : "";
-	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", `${host}/${owner}/${repo}${ref}`)}`;
+	return `${label} ${theme.fg("accent", `${host}/${owner}/${repo}${ref}`)}`;
 }
 
 export function formatRepoFetchResult(result: (RepoFetchResult & { workspaceId: string }) | undefined, theme: LectorTheme): string {

package/extension/src/search/rendering.ts

@@ -2,17 +2,20 @@ import type { TextSearchResult } 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_MATCHES = 20;
 
 export function formatSearchCall(args: { directory?: unknown; query?: unknown }, theme: LectorTheme): string {
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	const query = typeof args.query === "string" ? args.query : "";
-	return `${theme.fg("toolTitle", theme.bold("search_code"))} ${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", directory)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("search_code")))} ${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", directory)}`;
 }
 
 export function formatSearchResult(result: TextSearchResult | undefined, expanded: boolean, theme: LectorTheme): string {
-	if (!result || result.matches.length === 0) return theme.fg("dim", "No matches found.");
+	if (!result) return theme.fg("dim", "No matches found.");
+	const provenance = result.provenance ? theme.fg("dim", `lexical via ${result.provenance.backend} (${result.provenance.indexState})`) : undefined;
+	if (result.matches.length === 0) return [provenance, theme.fg("dim", "No matches found.")].filter((line) => line !== undefined).join("\n");
 	const lines = renderTruncatedList({
 		items: result.matches,
 		expanded,
@@ -22,5 +25,5 @@ export function formatSearchResult(result: TextSearchResult | undefined, expande
 		moreLine: (hidden) => theme.fg("dim", `... ${hidden} more (${keyHint("app.tools.expand", "to expand")})`),
 		truncationWarning: result.truncated ? theme.fg("warning", "(search itself was truncated by maxMatches/maxBytes -- results are incomplete)") : undefined,
 	});
-	return lines.join("\n");
+	return [provenance, ...lines].filter((line) => line !== undefined).join("\n");
 }

package/extension/src/symbol-annotation/operations.ts

@@ -13,6 +13,8 @@ export interface AnnotationAnchorInput {
 	readonly character: number;
 }
 
+export type AnnotationAutoPopulationOptions = Pick<OperationInputs["workspace.createAnnotation"], "autoPopulate" | "maxFiles" | "maxSymbolsPerFile">;
+
 /**
  * Thin wrappers over Lector's annotation operations. Every operation resolves its workspace from
  * its own `path` parameter via workspaceForAnnotationPath -- a real project directory or an
@@ -29,6 +31,7 @@ export interface SymbolAnnotationOperations {
 		body: string,
 		anchors: readonly AnnotationAnchorInput[],
 		call: LectorVehicleCall,
+		autoPopulation?: AnnotationAutoPopulationOptions,
 	): Promise<OperationOutputs["workspace.createAnnotation"]>;
 	get(path: string, id: string, call: LectorVehicleCall): Promise<OperationOutputs["workspace.getAnnotation"]>;
 	list(
@@ -44,6 +47,7 @@ export interface SymbolAnnotationOperations {
 		body: string,
 		anchors: readonly AnnotationAnchorInput[],
 		call: LectorVehicleCall,
+		autoPopulation?: AnnotationAutoPopulationOptions,
 	): Promise<OperationOutputs["workspace.refreshAnnotation"]>;
 	scrub(path: string, id: string, call: LectorVehicleCall): Promise<OperationOutputs["workspace.scrubAnnotation"]>;
 	restore(path: string, id: string, call: LectorVehicleCall): Promise<OperationOutputs["workspace.restoreAnnotation"]>;
@@ -54,13 +58,13 @@ export interface SymbolAnnotationOperations {
 
 export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperations {
 	return {
-		async create(path, subtype, title, body, anchors, call) {
+		async create(path, subtype, title, body, anchors, call, autoPopulation) {
 			return withWorkspace(
 				() => workspaceForAnnotationPath(path),
 				({ workspaceId }) =>
 					invokeLectorVehicleOperation<OperationOutputs["workspace.createAnnotation"]>(
 						"workspace.createAnnotation",
-						{ workspaceId, subtype, title, body, anchors },
+						{ workspaceId, subtype, title, body, anchors, ...autoPopulation },
 						ANNOTATION_WRITE_PERMISSIONS,
 						call,
 					),
@@ -90,13 +94,13 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 					),
 			);
 		},
-		async refresh(path, id, subtype, title, body, anchors, call) {
+		async refresh(path, id, subtype, title, body, anchors, call, autoPopulation) {
 			return withWorkspace(
 				() => workspaceForAnnotationPath(path),
 				({ workspaceId }) =>
 					invokeLectorVehicleOperation<OperationOutputs["workspace.refreshAnnotation"]>(
 						"workspace.refreshAnnotation",
-						{ workspaceId, id, subtype, title, body, anchors },
+						{ workspaceId, id, subtype, title, body, anchors, ...autoPopulation },
 						ANNOTATION_WRITE_PERMISSIONS,
 						call,
 					),

package/extension/src/vehicle-client.ts

@@ -29,9 +29,11 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 type VehicleClientConnector = () => Promise<VehicleClient>;
 
-function connectLectorVehicleClient(): Promise<VehicleClient> {
+async function connectLectorVehicleClient(): Promise<VehicleClient> {
 	const { host, port, token } = resolveLectorDaemonConnection();
-	return Promise.resolve(new RemoteVehicleClient({ baseUrl: `http://${host}:${port}`, token }));
+	const client = new RemoteVehicleClient({ baseUrl: `http://${host}:${port}`, token });
+	await client.negotiate({ minimumVersion: 1, maximumVersion: 1, requiredCapabilities: [], optionalCapabilities: [] });
+	return client;
 }
 
 function resolveLectorVehicleIdentity() {

package/extension/src/workspace-cache/rendering.ts

@@ -1,5 +1,6 @@
 import type { CacheResultCounts, JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 type WorkspaceCacheAction = "status" | "populate" | "wait" | "job_status";
 
@@ -8,10 +9,10 @@ export function formatWorkspaceCacheCall(
 	args: { directory?: unknown; maxFiles?: unknown; maxSymbolsPerFile?: unknown; jobId?: unknown },
 	theme: LectorTheme,
 ): string {
-	const label = theme.fg("toolTitle", theme.bold("workspace_cache"));
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("workspace_cache", action)));
 	if (action === "job_status" || action === "wait") {
 		const jobId = typeof args.jobId === "string" ? args.jobId : "";
-		return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", jobId)}`;
+		return `${label} ${theme.fg("accent", jobId)}`;
 	}
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	const maxFiles = typeof args.maxFiles === "number" ? String(args.maxFiles) : "default";
@@ -20,7 +21,7 @@ export function formatWorkspaceCacheCall(
 		action === "populate" && (typeof args.maxFiles === "number" || typeof args.maxSymbolsPerFile === "number")
 			? theme.fg("dim", ` (maxFiles=${maxFiles}, maxSymbolsPerFile=${maxSymbolsPerFile})`)
 			: "";
-	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", directory)}${bounds}`;
+	return `${label} ${theme.fg("accent", directory)}${bounds}`;
 }
 
 function formatResultCounts(result: CacheResultCounts): string {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.13.9",
+	"version": "0.14.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -22,9 +22,9 @@
 		"@danypops/vehicle-client-pi": "^0.45.0"
 	},
 	"dependencies": {
-		"@danypops/lector": "^0.20.0",
-		"@danypops/vehicle-client": "^0.10.3",
-		"@danypops/vehicle-core": "^0.17.1",
+		"@danypops/lector": "^0.20.4",
+		"@danypops/vehicle-client": "^0.10.8",
+		"@danypops/vehicle-core": "^0.19.1",
 		"malevich-tui-components": "^0.32.1",
 		"picomatch": "^4.0.5"
 	},