@danypops/pi-lector 0.14.0 → 0.15.0

package/extension/src/cross-workspace-search/model-content.ts

@@ -0,0 +1,69 @@
+import type { SymbolSearchResult, TextSearchResult } from "@danypops/lector";
+import { boundModelContentText, DEFAULT_MODEL_CONTENT_BYTES } from "../presentation/model-content.ts";
+import type { CrossWorkspaceOutcome } from "./operations.ts";
+
+const MAX_RESULTS_PER_PROJECT = 10;
+
+function appendOutcomeHeader<T>(lines: string[], entry: CrossWorkspaceOutcome<T>): boolean {
+	const { outcome } = entry;
+	switch (outcome.status) {
+		case "ready":
+			lines.push(`${entry.directory} -- ready`);
+			break;
+		case "loading":
+			lines.push(`${entry.directory} -- loading: ${outcome.message}`);
+			return false;
+		case "error":
+			lines.push(`${entry.directory} -- error: ${outcome.message}`);
+			return false;
+		default: {
+			const exhaustive: never = outcome;
+			throw new Error(`unhandled workspace query outcome: ${JSON.stringify(exhaustive)}`);
+		}
+	}
+	if (entry.collapsedWith.length > 0) lines.push(`  same workspace as: ${entry.collapsedWith.join(", ")}`);
+	return true;
+}
+
+/** Formats cross-project symbol outcomes with concrete, independently bounded results for model consumption. */
+export function formatFindSymbolsAcrossProjectsModelContent(
+	results: readonly CrossWorkspaceOutcome<SymbolSearchResult>[],
+	maxBytes = DEFAULT_MODEL_CONTENT_BYTES,
+): string {
+	const lines = ["Find Symbols Across Projects", `projects: ${results.length}`];
+	for (const entry of results) {
+		if (!appendOutcomeHeader(lines, entry)) continue;
+		if (entry.outcome.status !== "ready") continue;
+		const { result } = entry.outcome;
+		lines.push(`  provenance: ${result.provenance.fidelity} via ${result.provenance.backend}`);
+		lines.push(`  upstream truncated: ${result.truncated}`);
+		for (const item of result.symbols.slice(0, MAX_RESULTS_PER_PROJECT)) {
+			lines.push(`  ${item.kind} ${item.name} -- ${item.location.path}:${item.location.line}:${item.location.character}`);
+		}
+		if (result.symbols.length > MAX_RESULTS_PER_PROJECT) lines.push(`  ${result.symbols.length - MAX_RESULTS_PER_PROJECT} more symbols omitted`);
+		if (result.symbols.length === 0) lines.push("  no symbols matched");
+	}
+	return boundModelContentText(lines.join("\n"), maxBytes);
+}
+
+/** Formats cross-project text outcomes with concrete, independently bounded matches for model consumption. */
+export function formatSearchTextAcrossProjectsModelContent(
+	results: readonly CrossWorkspaceOutcome<TextSearchResult>[],
+	maxBytes = DEFAULT_MODEL_CONTENT_BYTES,
+): string {
+	const lines = ["Search Code Across Projects", `projects: ${results.length}`];
+	for (const entry of results) {
+		if (!appendOutcomeHeader(lines, entry)) continue;
+		if (entry.outcome.status !== "ready") continue;
+		const { result } = entry.outcome;
+		if (result.provenance) lines.push(`  provenance: lexical via ${result.provenance.backend} (${result.provenance.indexState})`);
+		lines.push(`  upstream truncated: ${result.truncated}`);
+		for (const item of result.matches.slice(0, MAX_RESULTS_PER_PROJECT)) {
+			const line = item.line.replace(/\n$/, "");
+			lines.push(`  ${item.path}:${item.lineNumber}: ${line}${item.lineTruncated ? " (line truncated)" : ""}`);
+		}
+		if (result.matches.length > MAX_RESULTS_PER_PROJECT) lines.push(`  ${result.matches.length - MAX_RESULTS_PER_PROJECT} more matches omitted`);
+		if (result.matches.length === 0) lines.push("  no matches");
+	}
+	return boundModelContentText(lines.join("\n"), maxBytes);
+}

package/extension/src/index.ts

@@ -82,6 +82,7 @@ import {
 	formatWorkspaceMapCall,
 	formatWorkspaceMapResult,
 } from "./code-intelligence/rendering.ts";
+import { formatFindSymbolsAcrossProjectsModelContent, formatSearchTextAcrossProjectsModelContent } from "./cross-workspace-search/model-content.ts";
 import { type CrossWorkspaceOutcome, createLectorCrossWorkspaceSearchOperations } from "./cross-workspace-search/operations.ts";
 import { formatCrossWorkspaceCall, formatFindSymbolsAcrossProjectsResult, formatSearchTextAcrossProjectsResult } from "./cross-workspace-search/rendering.ts";
 import { createLectorEditOperations } from "./edit/operations.ts";
@@ -125,6 +126,11 @@ import { withLectorPresentation } from "./presentation/presentation-contract.ts"
 import { presentationTitle } from "./presentation/tool-presentation.ts";
 import { createLectorReadOperations } from "./read/operations.ts";
 import { createReferenceBasedRenameOperations } from "./reference-based-rename/operations.ts";
+import {
+	formatReferenceBasedRenameModelContent,
+	formatReferenceBasedRenameResult,
+	type ReferenceBasedRenameOutcome,
+} from "./reference-based-rename/rendering.ts";
 import { createRenameOperations } from "./rename/operations.ts";
 import { createRepoCacheEvictOperations } from "./repo-cache/evict-operations.ts";
 import { createRepoCacheListOperations } from "./repo-cache/list-operations.ts";
@@ -154,7 +160,13 @@ import {
 	monitorWorkspaceCache,
 	waitForJobCompletion,
 } from "./workspace-cache/operations.ts";
-import { formatJobSnapshotResult, formatWorkspaceCacheCall, formatWorkspaceCacheStatusResult } from "./workspace-cache/rendering.ts";
+import {
+	formatJobSnapshotResult,
+	formatWorkspaceCacheCall,
+	formatWorkspaceCacheStatusResult,
+	formatWorkspaceReleaseModelContent,
+	formatWorkspaceReleaseResult,
+} from "./workspace-cache/rendering.ts";
 import { createLectorWriteOperations } from "./write/operations.ts";
 
 function describeIntelligenceSource(provenance: IntelligenceProvenance): string {
@@ -1190,14 +1202,7 @@ export default function (pi: ExtensionAPI) {
 				const fromPath = resolve(cwd, params.fromPath);
 				const toPath = resolve(cwd, params.toPath);
 				const outcome = await referenceBasedRenameOperations.rename(fromPath, toPath, params.maxFiles, params.maxSymbolsPerFile);
-				const lines = [
-					`moved to ${outcome.movedTo}`,
-					outcome.filesUpdated.length === 0
-						? "no other files referenced it"
-						: `updated imports in ${outcome.filesUpdated.length} file(s): ${outcome.filesUpdated.join(", ")}`,
-					...outcome.caveats.map((caveat) => `caveat: ${caveat}`),
-				];
-				return { content: [{ type: "text", text: lines.join("\n") }], details: { outcome } };
+				return { content: [{ type: "text", text: formatReferenceBasedRenameModelContent(outcome) }], details: { outcome } };
 			},
 			renderCall(args, theme, context) {
 				const fromPath = typeof args.fromPath === "string" ? args.fromPath : "";
@@ -1217,13 +1222,9 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "reference_based_rename failed"), 0, 0);
 				}
-				const details = result.details as { outcome?: { movedTo: string; filesUpdated: readonly string[] } } | undefined;
+				const details = result.details as { outcome?: ReferenceBasedRenameOutcome } | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(
-					details?.outcome
-						? `${theme.fg("success", "moved")} ${theme.fg("accent", details.outcome.movedTo)} ${theme.fg("dim", `(${details.outcome.filesUpdated.length} import(s) updated)`)}`
-						: theme.fg("success", "rename complete"),
-				);
+				text.setText(details?.outcome ? formatReferenceBasedRenameResult(details.outcome, theme) : theme.fg("success", "rename complete"));
 				return text;
 			},
 		});
@@ -1604,25 +1605,27 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		interface WorkspaceCacheToolDetails {
-			readonly action: "status" | "populate" | "wait" | "job_status";
+			readonly action: "status" | "populate" | "wait" | "job_status" | "release";
 			readonly status?: WorkspaceCacheStatus;
 			readonly job?: JobSnapshot<PopulateSymbolGraphResult>;
+			readonly release?: OperationOutputs["workspace.release"];
 		}
 
 		registerLectorTool({
 			name: "workspace_cache",
 			label: "Workspace Cache",
 			description:
-				"Checks or drives population of the workspace's persisted symbol graph -- the store reachable_from, symbol_annotations (anchor resolution), reference_based_rename, and workspace_map all read from, separate from the live language-server index find_symbols/hover/go_to_definition use. action=status reports not-cached/caching/partial/cached for the given bounds, without starting work. action=populate requests a scan and briefly waits for fast completion; a source file changing mid-scan (e.g. a concurrent edit or rename) is retried automatically in the background for up to a minute before surfacing as a real failure, no manual re-run needed. action=wait subscribes to daemon job completion, with bounded status polling only when push delivery is unavailable. action=job_status is a point-in-time diagnostic read.",
+				"Checks or drives population of the workspace's persisted symbol graph -- the store reachable_from, symbol_annotations (anchor resolution), reference_based_rename, and workspace_map all read from, separate from the live language-server index find_symbols/hover/go_to_definition use. action=status reports not-cached/caching/partial/cached for the given bounds, without starting work. action=populate requests a scan and briefly waits for fast completion; a source file changing mid-scan (e.g. a concurrent edit or rename) is retried automatically in the background for up to a minute before surfacing as a real failure, no manual re-run needed. action=wait subscribes to daemon job completion, with bounded status polling only when push delivery is unavailable. action=job_status is a point-in-time diagnostic read. action=release safely closes idle workspace resources and unregisters it so fetched/package source cleanup can proceed.",
 			promptSnippet: "Check or force-populate the workspace's persisted symbol graph",
 			promptGuidelines: [
 				"Use action=populate with a larger maxFiles/maxSymbolsPerFile before relying on reachable_from/symbol_annotations/reference_based_rename against a workspace bigger than the default 500-file auto-scan -- their own errors (empty results, UnknownAnnotationAnchor, ReferenceBasedRenameRequiresFreshGraph) usually mean the graph never reached the files you need, not that population is simply still catching up.",
 				"When action=populate returns a queued/running job, call action=wait once with that jobId; do not run shell sleep or manually poll job_status.",
+				"Use action=release after finishing with a fetched or package-source workspace so package_source remove/clean and repo_cache evict can reclaim it; active leases, jobs, or watches fail closed.",
 			],
 			parameters: Type.Object({
-				action: Type.Union([Type.Literal("status"), Type.Literal("populate"), Type.Literal("wait"), Type.Literal("job_status")]),
+				action: Type.Union([Type.Literal("status"), Type.Literal("populate"), Type.Literal("wait"), Type.Literal("job_status"), Type.Literal("release")]),
 				directory: Type.Optional(
-					Type.String({ description: "Required for action=status/populate -- absolute or cwd-relative path used to resolve the workspace" }),
+					Type.String({ description: "Required for action=status/populate/release -- absolute or cwd-relative path used to resolve the workspace" }),
 				),
 				maxFiles: Type.Optional(
 					Type.Number({ description: "action=status/populate only -- defaults to 500, the same bound the automatic first-touch scan uses" }),
@@ -1638,7 +1641,7 @@ export default function (pi: ExtensionAPI) {
 				),
 				jobId: Type.Optional(Type.String({ description: "Required for action=wait/job_status -- a jobId returned by action=populate" })),
 			}),
-			async execute(_toolCallId, params, signal): Promise<AgentToolResult<WorkspaceCacheToolDetails>> {
+			async execute(toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult<WorkspaceCacheToolDetails>> {
 				if (params.action === "job_status") {
 					if (!params.jobId) throw new Error("workspace_cache action=job_status requires jobId");
 					const job = await cacheOperations.jobStatus(params.jobId);
@@ -1674,6 +1677,18 @@ export default function (pi: ExtensionAPI) {
 				}
 				if (!params.directory) throw new Error(`workspace_cache action=${params.action} requires directory`);
 				const directory = resolve(cwd, params.directory);
+				if (params.action === "release") {
+					const release = await cacheOperations.release(directory, {
+						toolName: "workspace_cache",
+						toolCallId,
+						signal,
+						context: ctx,
+					});
+					return {
+						content: [{ type: "text", text: formatWorkspaceReleaseModelContent(release) }],
+						details: { action: "release", release },
+					};
+				}
 				const maxFiles = params.maxFiles ?? 500;
 				const maxSymbolsPerFile = params.maxSymbolsPerFile ?? 100;
 				if (params.action === "status") {
@@ -1690,7 +1705,8 @@ export default function (pi: ExtensionAPI) {
 				};
 			},
 			renderCall(args, theme, context) {
-				const action = args.action === "populate" || args.action === "wait" || args.action === "job_status" ? args.action : "status";
+				const action =
+					args.action === "populate" || args.action === "wait" || args.action === "job_status" || args.action === "release" ? args.action : "status";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(formatWorkspaceCacheCall(action, args, theme));
 				return text;
@@ -1706,7 +1722,13 @@ export default function (pi: ExtensionAPI) {
 				}
 				const details = result.details as WorkspaceCacheToolDetails | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(details?.action === "status" ? formatWorkspaceCacheStatusResult(details.status, theme) : formatJobSnapshotResult(details?.job, theme));
+				text.setText(
+					details?.action === "status"
+						? formatWorkspaceCacheStatusResult(details.status, theme)
+						: details?.action === "release"
+							? formatWorkspaceReleaseResult(details.release, theme)
+							: formatJobSnapshotResult(details?.job, theme),
+				);
 				return text;
 			},
 		});
@@ -2522,7 +2544,7 @@ export default function (pi: ExtensionAPI) {
 				const directories = params.directories.map((directory) => resolve(cwd, directory));
 				const results = await crossWorkspaceSearchOperations.findSymbols(params.query, directories, params.timeoutMs, params.maxResults);
 				return {
-					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("find_symbols_across_projects"), results) }],
+					content: [{ type: "text", text: formatFindSymbolsAcrossProjectsModelContent(results) }],
 					details: { results },
 				};
 			},
@@ -2564,7 +2586,7 @@ export default function (pi: ExtensionAPI) {
 				const directories = params.directories.map((directory) => resolve(cwd, directory));
 				const results = await crossWorkspaceSearchOperations.searchText(params.query, directories, params.maxMatches, params.maxBytes, params.timeoutMs);
 				return {
-					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("search_code_across_projects"), results) }],
+					content: [{ type: "text", text: formatSearchTextAcrossProjectsModelContent(results) }],
 					details: { results },
 				};
 			},

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

@@ -89,6 +89,7 @@ export const LECTOR_TOOL_PRESENTATION_SPECS: Readonly<Record<string, ToolPresent
 			populate: { title: "Populate Workspace Cache", family: "status" },
 			wait: { title: "Wait for Cache Job", family: "status" },
 			job_status: { title: "Cache Job Status", family: "status" },
+			release: { title: "Release Workspace", family: "mutation" },
 		},
 	},
 	git: {

package/extension/src/reference-based-rename/rendering.ts

@@ -0,0 +1,21 @@
+import type { OperationOutputs } from "@danypops/lector";
+import type { LectorTheme } from "../lector-tui-theme.ts";
+
+export type ReferenceBasedRenameOutcome = OperationOutputs["workspace.referenceBasedRename"];
+
+/** Formats a successful reference-based rename with every fact required for guarded transaction revert. */
+export function formatReferenceBasedRenameModelContent(outcome: ReferenceBasedRenameOutcome): string {
+	return [
+		`moved to ${outcome.movedTo}`,
+		outcome.filesUpdated.length === 0
+			? "no other files referenced it"
+			: `updated imports in ${outcome.filesUpdated.length} file(s): ${outcome.filesUpdated.join(", ")}`,
+		`transaction ${outcome.transactionId}`,
+		...outcome.caveats.map((caveat) => `caveat: ${caveat}`),
+	].join("\n");
+}
+
+/** Formats the compact human mutation result while preserving its reusable transaction identity. */
+export function formatReferenceBasedRenameResult(outcome: ReferenceBasedRenameOutcome, theme: LectorTheme): string {
+	return `${theme.fg("success", "moved")} ${theme.fg("accent", outcome.movedTo)} ${theme.fg("dim", `(${outcome.filesUpdated.length} import(s) updated, transaction ${outcome.transactionId})`)}`;
+}

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

@@ -1,13 +1,15 @@
 import {
 	type CacheResultCounts,
 	type JobSnapshot,
+	type OperationOutputs,
 	type PopulateSymbolGraphResult,
 	remoteErrorIs,
 	resolveLectorDaemonConnection,
 	type WorkspaceCacheStatus,
 } from "@danypops/lector";
 import { connectPushChannel } from "@danypops/vehicle-client/daemon-client";
-import { lectorClient, withWorkspace, workspaceForProjectDirectory } from "../lector-client.ts";
+import { forgetWorkspaceId, lectorClient, withWorkspace, workspaceForProjectDirectory } from "../lector-client.ts";
+import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
 
 export interface JobWatchHandle {
 	close(): void;
@@ -25,9 +27,11 @@ export type JobWatchOutcome = { readonly status: "subscribed"; readonly handle:
  * want today's exact contract.
  */
 const DEFAULT_POPULATE_RETRY_TIME_BUDGET_MS = 60_000;
+const WORKSPACE_RELEASE_PERMISSIONS = ["workspace:write"];
 
 export interface WorkspaceCacheOperations {
 	status(directory: string, maxFiles: number, maxSymbolsPerFile: number): Promise<WorkspaceCacheStatus>;
+	release(directory: string, call: LectorVehicleCall): Promise<OperationOutputs["workspace.release"]>;
 	submit(
 		directory: string,
 		maxFiles: number,
@@ -39,6 +43,8 @@ export interface WorkspaceCacheOperations {
 	watchJob?(jobId: string, onJob: (job: JobSnapshot<PopulateSymbolGraphResult>) => void): Promise<JobWatchOutcome>;
 }
 
+export type WorkspaceCacheMonitorOperations = Omit<WorkspaceCacheOperations, "release">;
+
 export function createWorkspaceCacheOperations(ownerId?: string): WorkspaceCacheOperations {
 	return {
 		status(directory, maxFiles, maxSymbolsPerFile) {
@@ -50,6 +56,21 @@ export function createWorkspaceCacheOperations(ownerId?: string): WorkspaceCache
 				},
 			);
 		},
+		release(directory, call) {
+			return withWorkspace(
+				() => workspaceForProjectDirectory(directory),
+				async ({ workspaceId, root }) => {
+					const result = await invokeLectorVehicleOperation<OperationOutputs["workspace.release"]>(
+						"workspace.release",
+						{ workspaceId },
+						WORKSPACE_RELEASE_PERMISSIONS,
+						call,
+					);
+					forgetWorkspaceId(root);
+					return result;
+				},
+			);
+		},
 		submit(directory, maxFiles, maxSymbolsPerFile, waitMs = 0, retryTimeBudgetMs = DEFAULT_POPULATE_RETRY_TIME_BUDGET_MS) {
 			return withWorkspace(
 				() => workspaceForProjectDirectory(directory),
@@ -159,7 +180,7 @@ export type JobCompletionOutcome =
 
 /** Waits on Vehicle push delivery and checks status on a bounded cadence when push is unavailable or disconnected. */
 export async function waitForJobCompletion(
-	operations: WorkspaceCacheOperations,
+	operations: WorkspaceCacheMonitorOperations,
 	jobId: string,
 	options: WaitForJobCompletionOptions,
 ): Promise<JobCompletionOutcome> {
@@ -205,7 +226,7 @@ export async function waitForJobCompletion(
 }
 
 /** Drives one bounded session cache lifecycle; Pi event handlers only render its states. */
-export async function monitorWorkspaceCache(operations: WorkspaceCacheOperations, options: MonitorWorkspaceCacheOptions): Promise<void> {
+export async function monitorWorkspaceCache(operations: WorkspaceCacheMonitorOperations, options: MonitorWorkspaceCacheOptions): Promise<void> {
 	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
 	const initial = await operations.status(options.directory, options.maxFiles, options.maxSymbolsPerFile);
 	if (!options.shouldContinue()) return;

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

@@ -1,8 +1,8 @@
-import type { CacheResultCounts, JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
+import type { CacheResultCounts, JobSnapshot, OperationOutputs, 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";
+type WorkspaceCacheAction = "status" | "populate" | "wait" | "job_status" | "release";
 
 export function formatWorkspaceCacheCall(
 	action: WorkspaceCacheAction,
@@ -29,6 +29,23 @@ function formatResultCounts(result: CacheResultCounts): string {
 	return `${result.filesProcessed}/${result.filesAttempted} files${failed}, ${result.symbolsProcessed} symbols, ${result.nodesAdded} nodes, ${result.edgesAdded} edges`;
 }
 
+export function formatWorkspaceReleaseModelContent(outcome: OperationOutputs["workspace.release"]): string {
+	return [
+		`released workspace ${outcome.workspaceId}`,
+		`closed indexes: ${outcome.closedIndexes}`,
+		`closed graph: ${outcome.closedGraph}`,
+		`closed watch: ${outcome.closedWatch}`,
+	].join("\n");
+}
+
+export function formatWorkspaceReleaseResult(outcome: OperationOutputs["workspace.release"] | undefined, theme: LectorTheme): string {
+	if (!outcome) return theme.fg("dim", "No result.");
+	return theme.fg(
+		"success",
+		`released ${outcome.workspaceId} -- ${outcome.closedIndexes} index(es), graph ${outcome.closedGraph ? "closed" : "idle"}, watch ${outcome.closedWatch ? "closed" : "idle"}`,
+	);
+}
+
 export function formatWorkspaceCacheStatusResult(status: WorkspaceCacheStatus | undefined, theme: LectorTheme): string {
 	if (!status) return theme.fg("dim", "No result.");
 	if (status.status === "not-cached") return theme.fg("warning", `not cached (${status.reason})`);

package/package.json

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