@danypops/pi-lector 0.1.7 → 0.1.9

package/README.md

@@ -8,6 +8,10 @@ daemon-backed, hash-guarded filesystem. Requires a running Lector daemon
 pi install npm:@danypops/pi-lector
 ```
 
+`package_source` resolves an installed npm package through its lockfile and registry metadata, verifies an exact Git commit, and registers the package source read-only for `search_code`, `find_symbols`, and the semantic tools.
+
+Symbol and semantic tool results identify their backend and fidelity. `typescript-language-server` results are semantic; compiler or parser fallback results are structural and list their limitations.
+
 `populate_symbol_graph` submits bounded background work and waits briefly. If the
 graph is still loading, it returns a job id immediately; `job_status` polls that id
 later without forcing the agent into a blocking or blind polling loop.

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

@@ -1,16 +1,4 @@
-import type {
-	CallHierarchyEntry,
-	Diagnostic,
-	DocumentSymbolEntry,
-	Hover,
-	IncomingCall,
-	JobSnapshot,
-	OutgoingCall,
-	PopulateSymbolGraphResult,
-	SymbolEdgeKind,
-	SymbolNode,
-	WorkspaceLocation,
-} from "@danypops/lector";
+import type { JobSnapshot, OperationOutputs, PopulateSymbolGraphResult, SymbolEdgeKind, SymbolNode } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from "./lector-client.ts";
 
 /**
@@ -27,15 +15,15 @@ import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath } from ".
  * unlike read/write/edit) -- never a value captured once at session start.
  */
 export interface CodeIntelligenceOperations {
-	goToDefinition(path: string, line: number, character: number): Promise<readonly WorkspaceLocation[]>;
-	goToImplementation(path: string, line: number, character: number): Promise<readonly WorkspaceLocation[]>;
-	findReferences(path: string, line: number, character: number, includeDeclaration: boolean): Promise<readonly WorkspaceLocation[]>;
-	hover(path: string, line: number, character: number): Promise<Hover | undefined>;
-	documentSymbols(path: string): Promise<readonly DocumentSymbolEntry[]>;
-	diagnostics(path: string): Promise<readonly Diagnostic[]>;
-	prepareCallHierarchy(path: string, line: number, character: number): Promise<readonly CallHierarchyEntry[]>;
-	incomingCalls(path: string, line: number, character: number): Promise<readonly IncomingCall[]>;
-	outgoingCalls(path: string, line: number, character: number): Promise<readonly OutgoingCall[]>;
+	goToDefinition(path: string, line: number, character: number): Promise<OperationOutputs["workspace.goToDefinition"]>;
+	goToImplementation(path: string, line: number, character: number): Promise<OperationOutputs["workspace.goToImplementation"]>;
+	findReferences(path: string, line: number, character: number, includeDeclaration: boolean): Promise<OperationOutputs["workspace.findReferences"]>;
+	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"]>;
+	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"]>;
 	populateSymbolGraph(path: string, maxFiles: number, maxSymbolsPerFile: number, waitMs?: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	reachableFrom(path: string, line: number, character: number, maxDepth: number, kind?: SymbolEdgeKind): Promise<readonly SymbolNode[]>;
@@ -50,8 +38,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { locations } = await client.call("workspace.goToDefinition", { workspaceId, path, line, character });
-					return locations;
+					return client.call("workspace.goToDefinition", { workspaceId, path, line, character });
 				},
 			);
 		},
@@ -60,8 +47,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { locations } = await client.call("workspace.goToImplementation", { workspaceId, path, line, character });
-					return locations;
+					return client.call("workspace.goToImplementation", { workspaceId, path, line, character });
 				},
 			);
 		},
@@ -70,8 +56,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { locations } = await client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
-					return locations;
+					return client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
 				},
 			);
 		},
@@ -80,8 +65,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { hover } = await client.call("workspace.hover", { workspaceId, path, line, character });
-					return hover;
+					return client.call("workspace.hover", { workspaceId, path, line, character });
 				},
 			);
 		},
@@ -90,8 +74,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { symbols } = await client.call("workspace.documentSymbols", { workspaceId, path });
-					return symbols;
+					return client.call("workspace.documentSymbols", { workspaceId, path });
 				},
 			);
 		},
@@ -100,8 +83,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { diagnostics } = await client.call("workspace.diagnostics", { workspaceId, path });
-					return diagnostics;
+					return client.call("workspace.diagnostics", { workspaceId, path });
 				},
 			);
 		},
@@ -110,8 +92,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { items } = await client.call("workspace.prepareCallHierarchy", { workspaceId, path, line, character });
-					return items;
+					return client.call("workspace.prepareCallHierarchy", { workspaceId, path, line, character });
 				},
 			);
 		},
@@ -120,8 +101,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { calls } = await client.call("workspace.incomingCalls", { workspaceId, path, line, character });
-					return calls;
+					return client.call("workspace.incomingCalls", { workspaceId, path, line, character });
 				},
 			);
 		},
@@ -130,8 +110,7 @@ export function createLectorCodeIntelligenceOperations(): CodeIntelligenceOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { calls } = await client.call("workspace.outgoingCalls", { workspaceId, path, line, character });
-					return calls;
+					return client.call("workspace.outgoingCalls", { workspaceId, path, line, character });
 				},
 			);
 		},

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

@@ -1,4 +1,4 @@
-import type { TextSearchResult, WorkspaceQueryOutcome, WorkspaceSymbol } from "@danypops/lector";
+import type { SymbolSearchResult, TextSearchResult, WorkspaceQueryOutcome } from "@danypops/lector";
 import { lectorClient, workspaceForDirectory } from "./lector-client.ts";
 
 /**
@@ -10,11 +10,7 @@ import { lectorClient, workspaceForDirectory } from "./lector-client.ts";
  * required, same "no implicit fallback" convention as find_symbols/search_code.
  */
 export interface CrossWorkspaceSearchOperations {
-	findSymbols(
-		query: string,
-		directories: readonly string[],
-		timeoutMs?: number,
-	): Promise<readonly WorkspaceQueryOutcome<{ symbols: readonly WorkspaceSymbol[] }>[]>;
+	findSymbols(query: string, directories: readonly string[], timeoutMs?: number): Promise<readonly WorkspaceQueryOutcome<SymbolSearchResult>[]>;
 	searchText(
 		query: string,
 		directories: readonly string[],

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

@@ -1,4 +1,4 @@
-import type { TextSearchResult, WorkspaceQueryOutcome, WorkspaceSymbol } from "@danypops/lector";
+import type { SymbolSearchResult, TextSearchResult, WorkspaceQueryOutcome } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import type { LectorTheme } from "./lector-tui-theme.ts";
 
@@ -17,7 +17,7 @@ function formatOutcomeHeader(outcome: WorkspaceQueryOutcome<unknown>, theme: Lec
 }
 
 export function formatFindSymbolsAcrossProjectsResult(
-	results: readonly WorkspaceQueryOutcome<{ symbols: readonly WorkspaceSymbol[] }>[] | undefined,
+	results: readonly WorkspaceQueryOutcome<SymbolSearchResult>[] | undefined,
 	expanded: boolean,
 	theme: LectorTheme,
 ): string {
@@ -26,6 +26,9 @@ export function formatFindSymbolsAcrossProjectsResult(
 	for (const outcome of results) {
 		lines.push(formatOutcomeHeader(outcome, theme));
 		if (outcome.status !== "ready") continue;
+		lines.push(
+			theme.fg("muted", `  ${outcome.result.provenance.fidelity} via ${outcome.result.provenance.backend}${outcome.result.truncated ? " (truncated)" : ""}`),
+		);
 		if (outcome.result.symbols.length === 0) {
 			lines.push(theme.fg("dim", "  no symbols matched"));
 			continue;

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

@@ -1,4 +1,4 @@
-import type { WorkspaceSymbol } from "@danypops/lector";
+import type { SymbolSearchResult } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-client.ts";
 
 /**
@@ -15,7 +15,7 @@ import { lectorClient, withWorkspace, workspaceForDirectory } from "./lector-cli
  * is no implicit fallback anywhere in this module.
  */
 export interface FindSymbolsOperations {
-	findSymbols(query: string, directory: string): Promise<readonly WorkspaceSymbol[]>;
+	findSymbols(query: string, directory: string): Promise<SymbolSearchResult>;
 }
 
 export function createLectorFindSymbolsOperations(): FindSymbolsOperations {
@@ -25,8 +25,7 @@ export function createLectorFindSymbolsOperations(): FindSymbolsOperations {
 				() => workspaceForDirectory(directory),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { symbols } = await client.call("workspace.findSymbols", { workspaceId, query });
-					return symbols;
+					return client.call("workspace.findSymbols", { workspaceId, query });
 				},
 			);
 		},

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

@@ -1,4 +1,4 @@
-import type { WorkspaceSymbol } from "@danypops/lector";
+import type { SymbolSearchResult, WorkspaceSymbol } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { colorForKind, formatLocation, type LectorTheme } from "./lector-tui-theme.ts";
 
@@ -32,14 +32,17 @@ function formatSymbolLine(symbol: WorkspaceSymbol, theme: FindSymbolsTheme, kind
 	return `${kind}  ${name}  ${location}`;
 }
 
-export function formatFindSymbolsResult(symbols: readonly WorkspaceSymbol[] | undefined, query: string, expanded: boolean, theme: FindSymbolsTheme): string {
-	if (!symbols || symbols.length === 0) {
-		return theme.fg("dim", `No symbols found matching "${query}".`);
+export function formatFindSymbolsResult(result: SymbolSearchResult | undefined, query: string, expanded: boolean, theme: FindSymbolsTheme): string {
+	if (!result) return theme.fg("dim", `No symbols found matching "${query}".`);
+	const { symbols, provenance, truncated } = result;
+	const source = `${provenance.fidelity} via ${provenance.backend}${truncated ? " (truncated)" : ""}`;
+	if (symbols.length === 0) {
+		return `${theme.fg("muted", source)}\n${theme.fg("dim", `No symbols found matching "${query}".`)}`;
 	}
 
 	const kindColumnWidth = Math.max(...symbols.map((symbol) => symbol.kind.length));
 	const displayCount = expanded ? symbols.length : Math.min(symbols.length, DEFAULT_VISIBLE_RESULTS);
-	const lines = [theme.fg("muted", `${symbols.length} symbol${symbols.length === 1 ? "" : "s"} matching "${query}":`)];
+	const lines = [theme.fg("muted", source), theme.fg("muted", `${symbols.length} symbol${symbols.length === 1 ? "" : "s"} matching "${query}":`)];
 
 	for (const symbol of symbols.slice(0, displayCount)) {
 		lines.push(formatSymbolLine(symbol, theme, kindColumnWidth));

package/extension/src/index.ts

@@ -8,15 +8,17 @@ import type {
 	GitStatusSummary,
 	Hover,
 	IncomingCall,
+	IntelligenceProvenance,
 	JobSnapshot,
 	OutgoingCall,
+	PackageSourceOperationResult,
 	PopulateSymbolGraphResult,
 	RepoFetchResult,
 	SymbolNode,
+	SymbolSearchResult,
 	TextSearchResult,
 	WorkspaceLocation,
 	WorkspaceQueryOutcome,
-	WorkspaceSymbol,
 } from "@danypops/lector";
 import { createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -55,14 +57,30 @@ import { formatFindSymbolsCall, formatFindSymbolsResult } from "./find-symbols-r
 import { createLectorGitOperations } from "./git-operations.ts";
 import { formatGitDiffCall, formatGitDiffResult, formatGitLogCall, formatGitLogResult, formatGitStatusCall, formatGitStatusResult } from "./git-rendering.ts";
 import { nearestGitRoot } from "./nearest-workspace-root.ts";
+import { createLectorPackageSourceOperations } from "./package-source-operations.ts";
+import { formatPackageSourceCall, formatPackageSourceResult } from "./package-source-rendering.ts";
 import { createLectorReadOperations } from "./read-operations.ts";
 import { createLectorRepoFetchOperations } from "./repo-fetch-operations.ts";
 import { formatRepoFetchCall, formatRepoFetchResult } from "./repo-fetch-rendering.ts";
 import { createLectorSearchOperations } from "./search-operations.ts";
 import { formatSearchCall, formatSearchResult } from "./search-rendering.ts";
-import { type CachePresentationState, createWorkspaceCacheOperations, monitorWorkspaceCache } from "./workspace-cache-operations.ts";
+import {
+	type CachePresentationState,
+	cacheContextMessage,
+	createWorkspaceCacheOperations,
+	describeCacheState,
+	monitorWorkspaceCache,
+} from "./workspace-cache-operations.ts";
 import { createLectorWriteOperations } from "./write-operations.ts";
 
+function describeIntelligenceSource(provenance: IntelligenceProvenance): string {
+	return `${provenance.fidelity} via ${provenance.backend}`;
+}
+
+function renderIntelligenceSource(body: string, provenance: IntelligenceProvenance | undefined, theme: { fg(color: "muted", text: string): string }): string {
+	return provenance ? `${theme.fg("muted", describeIntelligenceSource(provenance))}\n${body}` : body;
+}
+
 /**
  * pi-lector -- the thin Pi host adapter for Lector. Overrides the built-in
  * read/write/edit tools by name with Lector-backed Operations, so built-in
@@ -87,13 +105,6 @@ export default function (pi: ExtensionAPI) {
 	let cacheState: CachePresentationState | undefined;
 	let lastInjectedCacheState: string | undefined;
 
-	function describeCacheState(state: CachePresentationState): string {
-		if (state.status === "not-cached") return `not cached (${state.reason})`;
-		if (state.status === "caching") return `caching (job ${state.jobId})`;
-		if (state.status === "finished-caching") return `finished caching (job ${state.job.id})`;
-		return "cached";
-	}
-
 	pi.on("before_agent_start", () => {
 		if (!cacheState) return;
 		const description = describeCacheState(cacheState);
@@ -102,7 +113,7 @@ export default function (pi: ExtensionAPI) {
 		return {
 			message: {
 				customType: "lector-cache-status",
-				content: `Lector workspace cache: ${description}. A caching graph is still loading; use live code-intelligence operations until it becomes cached.`,
+				content: cacheContextMessage(cacheState),
 				display: false,
 			},
 		};
@@ -160,7 +171,7 @@ export default function (pi: ExtensionAPI) {
 				"Search a workspace for functions, classes, interfaces, types, enums, and methods by name " +
 				"(case-insensitive substring match). Returns each match's kind and file location. `directory` " +
 				"selects which project to search -- pass the current working directory to search it, or any " +
-				"other project's directory to get code intelligence there without needing to be in it.",
+				"other project's directory to get code intelligence there without needing to be in it. Results identify semantic language-server authority or structural compiler/parser fallback.",
 			promptSnippet: "Search a workspace for a symbol (function, class, etc.) by name",
 			promptGuidelines: [
 				"Use find_symbols to locate where a function, class, interface, type, enum, or method is declared by name, instead of grepping for it.",
@@ -172,14 +183,16 @@ export default function (pi: ExtensionAPI) {
 			}),
 			async execute(_toolCallId, params) {
 				const directory = resolve(cwd, params.directory);
-				const symbols = await findSymbolsOperations.findSymbols(params.query, directory);
+				const result = await findSymbolsOperations.findSymbols(params.query, directory);
+				const { symbols, provenance, truncated } = result;
+				const source = `${provenance.fidelity} via ${provenance.backend}${truncated ? " (truncated)" : ""}`;
 				const text =
 					symbols.length === 0
-						? `No symbols found matching "${params.query}".`
-						: symbols
+						? `${source}\nNo symbols found matching "${params.query}".`
+						: `${source}\n${symbols
 								.map((symbol) => `${symbol.kind} ${symbol.name} -- ${symbol.location.path}:${symbol.location.line}:${symbol.location.character}`)
-								.join("\n");
-				return { content: [{ type: "text", text }], details: { symbols } };
+								.join("\n")}`;
+				return { content: [{ type: "text", text }], details: result };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -197,10 +210,10 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "find_symbols failed"), 0, 0);
 				}
-				const details = result.details as { symbols?: readonly WorkspaceSymbol[] } | undefined;
+				const details = result.details as SymbolSearchResult | undefined;
 				const query = typeof context.args?.query === "string" ? context.args.query : "";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatFindSymbolsResult(details?.symbols, query, expanded, theme));
+				text.setText(formatFindSymbolsResult(details, query, expanded, theme));
 				return text;
 			},
 		});
@@ -221,9 +234,9 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object(positionParameters),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const locations = await codeIntelligenceOperations.goToDefinition(path, params.line, params.character);
-				const text = locations.length === 0 ? "No definition found." : locations.map((l) => `${l.path}:${l.line}:${l.character}`).join("\n");
-				return { content: [{ type: "text", text }], details: { locations } };
+				const details = await codeIntelligenceOperations.goToDefinition(path, params.line, params.character);
+				const text = details.locations.length === 0 ? "No definition found." : details.locations.map((l) => `${l.path}:${l.line}:${l.character}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -239,9 +252,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "go_to_definition failed"), 0, 0);
 				}
-				const details = result.details as { locations?: readonly WorkspaceLocation[] } | undefined;
+				const details = result.details as { locations?: readonly WorkspaceLocation[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGoToDefinitionResult(details?.locations, expanded, theme));
+				text.setText(renderIntelligenceSource(formatGoToDefinitionResult(details?.locations, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -258,9 +271,10 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object(positionParameters),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const locations = await codeIntelligenceOperations.goToImplementation(path, params.line, params.character);
-				const text = locations.length === 0 ? "No implementation found." : locations.map((l) => `${l.path}:${l.line}:${l.character}`).join("\n");
-				return { content: [{ type: "text", text }], details: { locations } };
+				const details = await codeIntelligenceOperations.goToImplementation(path, params.line, params.character);
+				const text =
+					details.locations.length === 0 ? "No implementation found." : details.locations.map((l) => `${l.path}:${l.line}:${l.character}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -276,9 +290,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "go_to_implementation failed"), 0, 0);
 				}
-				const details = result.details as { locations?: readonly WorkspaceLocation[] } | undefined;
+				const details = result.details as { locations?: readonly WorkspaceLocation[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGoToImplementationResult(details?.locations, expanded, theme));
+				text.setText(renderIntelligenceSource(formatGoToImplementationResult(details?.locations, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -298,9 +312,9 @@ export default function (pi: ExtensionAPI) {
 			}),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const locations = await codeIntelligenceOperations.findReferences(path, params.line, params.character, params.includeDeclaration);
-				const text = locations.length === 0 ? "No references found." : locations.map((l) => `${l.path}:${l.line}:${l.character}`).join("\n");
-				return { content: [{ type: "text", text }], details: { locations } };
+				const details = await codeIntelligenceOperations.findReferences(path, params.line, params.character, params.includeDeclaration);
+				const text = details.locations.length === 0 ? "No references found." : details.locations.map((l) => `${l.path}:${l.line}:${l.character}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -316,9 +330,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "find_references failed"), 0, 0);
 				}
-				const details = result.details as { locations?: readonly WorkspaceLocation[] } | undefined;
+				const details = result.details as { locations?: readonly WorkspaceLocation[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatFindReferencesResult(details?.locations, expanded, theme));
+				text.setText(renderIntelligenceSource(formatFindReferencesResult(details?.locations, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -334,8 +348,13 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object(positionParameters),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const hover = await codeIntelligenceOperations.hover(path, params.line, params.character);
-				return { content: [{ type: "text", text: hover?.contents ?? "No hover information available." }], details: { hover } };
+				const details = await codeIntelligenceOperations.hover(path, params.line, params.character);
+				return {
+					content: [
+						{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${details.hover?.contents ?? "No hover information available."}` },
+					],
+					details,
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -351,9 +370,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "hover failed"), 0, 0);
 				}
-				const details = result.details as { hover?: Hover } | undefined;
+				const details = result.details as { hover?: Hover; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatHoverResult(details?.hover, expanded, theme));
+				text.setText(renderIntelligenceSource(formatHoverResult(details?.hover, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -367,9 +386,9 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object({ path: Type.String({ description: "Absolute or cwd-relative path to the file" }) }),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const symbols = await codeIntelligenceOperations.documentSymbols(path);
-				const text = symbols.length === 0 ? "No symbols found." : symbols.map((s) => `${s.kind} ${s.name}`).join("\n");
-				return { content: [{ type: "text", text }], details: { symbols } };
+				const details = await codeIntelligenceOperations.documentSymbols(path);
+				const text = details.symbols.length === 0 ? "No symbols found." : details.symbols.map((s) => `${s.kind} ${s.name}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -385,9 +404,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "document_symbols failed"), 0, 0);
 				}
-				const details = result.details as { symbols?: readonly DocumentSymbolEntry[] } | undefined;
+				const details = result.details as { symbols?: readonly DocumentSymbolEntry[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatDocumentSymbolsResult(details?.symbols, expanded, theme));
+				text.setText(renderIntelligenceSource(formatDocumentSymbolsResult(details?.symbols, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -401,12 +420,12 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object({ path: Type.String({ description: "Absolute or cwd-relative path to the file" }) }),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const diagnostics = await codeIntelligenceOperations.diagnostics(path);
+				const details = await codeIntelligenceOperations.diagnostics(path);
 				const text =
-					diagnostics.length === 0
+					details.diagnostics.length === 0
 						? "No diagnostics."
-						: diagnostics.map((d) => `${d.severity} ${d.range.path}:${d.range.start.line}:${d.range.start.character} -- ${d.message}`).join("\n");
-				return { content: [{ type: "text", text }], details: { diagnostics } };
+						: details.diagnostics.map((d) => `${d.severity} ${d.range.path}:${d.range.start.line}:${d.range.start.character} -- ${d.message}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -422,9 +441,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "diagnostics failed"), 0, 0);
 				}
-				const details = result.details as { diagnostics?: readonly Diagnostic[] } | undefined;
+				const details = result.details as { diagnostics?: readonly Diagnostic[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatDiagnosticsResult(details?.diagnostics, expanded, theme));
+				text.setText(renderIntelligenceSource(formatDiagnosticsResult(details?.diagnostics, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -440,12 +459,12 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object(positionParameters),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const items = await codeIntelligenceOperations.prepareCallHierarchy(path, params.line, params.character);
+				const details = await codeIntelligenceOperations.prepareCallHierarchy(path, params.line, params.character);
 				const text =
-					items.length === 0
+					details.items.length === 0
 						? "No call-hierarchy root at this position."
-						: items.map((i) => `${i.kind} ${i.name} -- ${i.location.path}:${i.location.line}:${i.location.character}`).join("\n");
-				return { content: [{ type: "text", text }], details: { items } };
+						: details.items.map((i) => `${i.kind} ${i.name} -- ${i.location.path}:${i.location.line}:${i.location.character}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -461,9 +480,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "prepare_call_hierarchy failed"), 0, 0);
 				}
-				const details = result.details as { items?: readonly CallHierarchyEntry[] } | undefined;
+				const details = result.details as { items?: readonly CallHierarchyEntry[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatPrepareCallHierarchyResult(details?.items, theme));
+				text.setText(renderIntelligenceSource(formatPrepareCallHierarchyResult(details?.items, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -479,12 +498,14 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object(positionParameters),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const calls = await codeIntelligenceOperations.incomingCalls(path, params.line, params.character);
+				const details = await codeIntelligenceOperations.incomingCalls(path, params.line, params.character);
 				const text =
-					calls.length === 0
+					details.calls.length === 0
 						? "No incoming calls found."
-						: calls.map((c) => `${c.from.kind} ${c.from.name} -- ${c.from.location.path}:${c.from.location.line}:${c.from.location.character}`).join("\n");
-				return { content: [{ type: "text", text }], details: { calls } };
+						: details.calls
+								.map((c) => `${c.from.kind} ${c.from.name} -- ${c.from.location.path}:${c.from.location.line}:${c.from.location.character}`)
+								.join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -500,9 +521,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "incoming_calls failed"), 0, 0);
 				}
-				const details = result.details as { calls?: readonly IncomingCall[] } | undefined;
+				const details = result.details as { calls?: readonly IncomingCall[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatIncomingCallsResult(details?.calls, expanded, theme));
+				text.setText(renderIntelligenceSource(formatIncomingCallsResult(details?.calls, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -516,12 +537,12 @@ export default function (pi: ExtensionAPI) {
 			parameters: Type.Object(positionParameters),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
-				const calls = await codeIntelligenceOperations.outgoingCalls(path, params.line, params.character);
+				const details = await codeIntelligenceOperations.outgoingCalls(path, params.line, params.character);
 				const text =
-					calls.length === 0
+					details.calls.length === 0
 						? "No outgoing calls found."
-						: calls.map((c) => `${c.to.kind} ${c.to.name} -- ${c.to.location.path}:${c.to.location.line}:${c.to.location.character}`).join("\n");
-				return { content: [{ type: "text", text }], details: { calls } };
+						: details.calls.map((c) => `${c.to.kind} ${c.to.name} -- ${c.to.location.path}:${c.to.location.line}:${c.to.location.character}`).join("\n");
+				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -537,9 +558,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "outgoing_calls failed"), 0, 0);
 				}
-				const details = result.details as { calls?: readonly OutgoingCall[] } | undefined;
+				const details = result.details as { calls?: readonly OutgoingCall[]; provenance?: IntelligenceProvenance } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatOutgoingCallsResult(details?.calls, expanded, theme));
+				text.setText(renderIntelligenceSource(formatOutgoingCallsResult(details?.calls, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -825,6 +846,45 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		const packageSourceOperations = createLectorPackageSourceOperations();
+		pi.registerTool({
+			name: "package_source",
+			label: "Package Source",
+			description:
+				"Resolve an installed npm package to verified exact repository source. Uses the project's lockfile, bounded registry metadata, and an exact Git ref/commit; registers verified source as a read-only workspace for the other Lector tools.",
+			promptSnippet: "Resolve an installed npm package to exact read-only source",
+			parameters: Type.Object({
+				directory: Type.String({ description: "Project directory containing the npm-family lockfile" }),
+				name: Type.String({ description: "Installed package name, including scope when present" }),
+				version: Type.Optional(Type.String({ description: "Exact installed version; required when the lockfile contains several versions" })),
+				registry: Type.Optional(Type.String({ description: "npm registry URL; defaults to the public npm registry" })),
+			}),
+			async execute(_toolCallId, params) {
+				const directory = resolve(cwd, params.directory);
+				const result = await packageSourceOperations.resolve(directory, params.name, params.version ?? null, params.registry ?? null);
+				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { result } };
+			},
+			renderCall(args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatPackageSourceCall(args as { directory?: unknown; name?: unknown; version?: unknown }, theme));
+				return text;
+			},
+			renderResult(result, { expanded, isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Resolving package source..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "package_source failed"), 0, 0);
+				}
+				const details = result.details as { result?: PackageSourceOperationResult } | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(formatPackageSourceResult(details?.result, expanded, theme));
+				return text;
+			},
+		});
+
 		const repoFetchOperations = createLectorRepoFetchOperations();
 		pi.registerTool({
 			name: "repo_fetch",
@@ -894,7 +954,7 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "find_symbols_across_projects failed"), 0, 0);
 				}
-				const details = result.details as { results?: readonly WorkspaceQueryOutcome<{ symbols: readonly WorkspaceSymbol[] }>[] } | undefined;
+				const details = result.details as { results?: readonly WorkspaceQueryOutcome<SymbolSearchResult>[] } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(formatFindSymbolsAcrossProjectsResult(details?.results, expanded, theme));
 				return text;

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

@@ -0,0 +1,21 @@
+import { DEFAULT_PACKAGE_SOURCE_BOUNDS, type PackageSourceOperationResult } from "@danypops/lector";
+import { lectorClient } from "./lector-client.ts";
+
+export interface PackageSourceOperations {
+	resolve(directory: string, name: string, requestedVersion: string | null, registry: string | null): Promise<PackageSourceOperationResult>;
+}
+
+export function createLectorPackageSourceOperations(): PackageSourceOperations {
+	return {
+		async resolve(directory, name, requestedVersion, registry) {
+			const client = await lectorClient();
+			return client.call("package.resolveSource", {
+				request: {
+					projectRoot: directory,
+					coordinate: { ecosystem: "npm", registry, name, requestedVersion },
+				},
+				bounds: DEFAULT_PACKAGE_SOURCE_BOUNDS,
+			});
+		},
+	};
+}

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

@@ -0,0 +1,37 @@
+import type { PackageSourceOperationResult } from "@danypops/lector";
+import type { LectorTheme } from "./lector-tui-theme.ts";
+
+const DEFAULT_VISIBLE_CANDIDATES = 5;
+
+export function formatPackageSourceCall(args: { directory?: unknown; name?: unknown; version?: unknown }, theme: LectorTheme): string {
+	const name = typeof args.name === "string" ? args.name : "";
+	const version = typeof args.version === "string" ? `@${args.version}` : "";
+	const directory = typeof args.directory === "string" ? args.directory : "";
+	return `${theme.fg("toolTitle", theme.bold("package_source"))} ${theme.fg("accent", `${name}${version}`)} ${theme.fg("dim", directory)}`.trim();
+}
+
+export function formatPackageSourceResult(result: PackageSourceOperationResult | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No package-source result.");
+	const { outcome } = result;
+	if (outcome.status === "verified") {
+		return [
+			`${theme.fg("accent", result.workspaceId ?? "unregistered")} ${theme.fg("success", `${outcome.coordinate.name}@${outcome.coordinate.resolvedVersion}`)}`,
+			`${outcome.workspace.cachePath}`,
+			`${outcome.repository.url ?? "local source"}@${outcome.repository.resolvedRef ?? "local"} ${outcome.repository.commit ?? outcome.verification.integrity}`,
+		].join("\n");
+	}
+	if (outcome.status === "ambiguous") {
+		const visible = expanded ? outcome.candidates : outcome.candidates.slice(0, DEFAULT_VISIBLE_CANDIDATES);
+		const lines = [theme.fg("warning", `Ambiguous package source (${outcome.code})`)];
+		for (const candidate of visible) lines.push(`${candidate.version} -- ${candidate.source}`);
+		const hidden = outcome.candidates.length - visible.length;
+		if (hidden > 0 || outcome.truncated) lines.push(theme.fg("dim", outcome.truncated ? "More candidates were truncated by the daemon." : `… ${hidden} more`));
+		return lines.join("\n");
+	}
+	if (outcome.status === "unauthenticated") {
+		return theme.fg("warning", `Authentication required (${outcome.code}): configure ${outcome.requiredCredentialNames.join(", ")}`);
+	}
+	if (outcome.status === "oversized") return theme.fg("warning", `Source resolution exceeded ${outcome.resource} limit ${outcome.limit}.`);
+	if (outcome.status === "mismatched") return theme.fg("error", `Source mismatch (${outcome.code}): expected ${outcome.expected}, got ${outcome.actual}.`);
+	return theme.fg("warning", `Source unavailable (${outcome.code}).`);
+}

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

@@ -46,6 +46,20 @@ export type CachePresentationState =
 	| { readonly status: "finished-caching"; readonly job: JobSnapshot<PopulateSymbolGraphResult> & { readonly status: "succeeded" } }
 	| { readonly status: "cached" };
 
+export function describeCacheState(state: CachePresentationState): string {
+	if (state.status === "not-cached") return `not cached (${state.reason})`;
+	if (state.status === "caching") return `caching (job ${state.jobId})`;
+	if (state.status === "finished-caching") return `finished caching (job ${state.job.id})`;
+	return "cached";
+}
+
+export function cacheContextMessage(state: CachePresentationState): string {
+	const prefix = `Lector workspace cache: ${describeCacheState(state)}.`;
+	if (state.status === "not-cached") return `${prefix} Live code-intelligence operations remain available.`;
+	if (state.status === "caching") return `${prefix} The cached graph is still building; use live code-intelligence operations until it is ready.`;
+	return `${prefix} The cached graph is ready.`;
+}
+
 export interface MonitorWorkspaceCacheOptions {
 	readonly directory: string;
 	readonly maxFiles: number;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -18,7 +18,7 @@
 		"typebox": "*"
 	},
 	"dependencies": {
-		"@danypops/lector": "^0.1.7"
+		"@danypops/lector": "^0.1.8"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.81.1",