@danypops/pi-lector 0.11.2 → 0.12.0

package/README.md

@@ -20,9 +20,10 @@ it's still building, instead of requiring an explicit "start indexing" call.
 When a session starts inside a Git repository, pi-lector checks a durable, bounded
 source-content manifest without blocking startup. The footer reports not cached,
 caching, or cached across every workspace touched so far this session; completion
-also emits a one-shot notification. Session shutdown stops polling, and the agent
-receives each state transition once in its context.
+also emits a one-shot notification. The adapter subscribes to daemon job completion,
+keeps bounded status polling as the disconnect fallback, and closes both on session shutdown.
+The agent receives each state transition once in its context.
 
 For an explicit, custom-bound population outside of Pi (a larger scan than the
 default 500 files / 100 symbols per file), use `lector workspace populate-symbol-graph`
-and `lector job status` directly.
+and `lector job wait` directly.

package/extension/src/index.ts

@@ -132,6 +132,7 @@ import {
 	createWorkspaceCacheOperations,
 	describeCacheState,
 	monitorWorkspaceCache,
+	waitForJobCompletion,
 } from "./workspace-cache/operations.ts";
 import { formatJobSnapshotResult, formatWorkspaceCacheCall, formatWorkspaceCacheStatusResult } from "./workspace-cache/rendering.ts";
 import { createLectorWriteOperations } from "./write/operations.ts";
@@ -1108,7 +1109,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		interface WorkspaceCacheToolDetails {
-			readonly action: "status" | "populate" | "job_status";
+			readonly action: "status" | "populate" | "wait" | "job_status";
 			readonly status?: WorkspaceCacheStatus;
 			readonly job?: JobSnapshot<PopulateSymbolGraphResult>;
 		}
@@ -1117,14 +1118,14 @@ export default function (pi: ExtensionAPI) {
 			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 any work. action=populate explicitly requests a scan (optionally larger than the default 500-file/100-symbol auto-scan every workspace gets on first touch) and waits up to waitMs for it to finish, returning a job snapshot either way. action=job_status polls a job returned by populate that didn't finish within its own wait.",
+				"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. 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.",
 			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.",
-				"action=populate returns immediately once its own waitMs elapses even if the job is still running -- check the returned job's status and poll with action=job_status (the same jobId) rather than assuming a non-succeeded result means failure.",
+				"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.",
 			],
 			parameters: Type.Object({
-				action: Type.Union([Type.Literal("status"), Type.Literal("populate"), Type.Literal("job_status")]),
+				action: Type.Union([Type.Literal("status"), Type.Literal("populate"), Type.Literal("wait"), Type.Literal("job_status")]),
 				directory: Type.Optional(
 					Type.String({ description: "Required for action=status/populate -- absolute or cwd-relative path used to resolve the workspace" }),
 				),
@@ -1137,17 +1138,33 @@ export default function (pi: ExtensionAPI) {
 				waitMs: Type.Optional(
 					Type.Number({
 						description:
-							"action=populate only -- how long to wait for the job to finish before returning its current snapshot; defaults to 3000, capped by the daemon at 30000",
+							"action=populate: initial daemon wait, defaults to 3000 and capped at 30000. action=wait: total subscription/fallback bound, defaults to 300000 and capped at 300000",
 					}),
 				),
-				jobId: Type.Optional(Type.String({ description: "Required for action=job_status -- a jobId returned by a prior action=populate call" })),
+				jobId: Type.Optional(Type.String({ description: "Required for action=wait/job_status -- a jobId returned by action=populate" })),
 			}),
-			async execute(_toolCallId, params): Promise<AgentToolResult<WorkspaceCacheToolDetails>> {
+			async execute(_toolCallId, params, signal): Promise<AgentToolResult<WorkspaceCacheToolDetails>> {
 				if (params.action === "job_status") {
 					if (!params.jobId) throw new Error("workspace_cache action=job_status requires jobId");
-					const job = await codeIntelligenceOperations.jobStatus(params.jobId);
+					const job = await cacheOperations.jobStatus(params.jobId);
 					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "job_status", job } };
 				}
+				if (params.action === "wait") {
+					if (!params.jobId) throw new Error("workspace_cache action=wait requires jobId");
+					const waitMs = params.waitMs ?? 300_000;
+					if (!Number.isSafeInteger(waitMs) || waitMs < 1 || waitMs > 300_000)
+						throw new Error("workspace_cache action=wait waitMs must be an integer from 1 to 300000");
+					const pollIntervalMs = 5_000;
+					const completed = await waitForJobCompletion(cacheOperations, params.jobId, {
+						pollIntervalMs,
+						maxPolls: Math.ceil(waitMs / pollIntervalMs),
+						shouldContinue: () => !signal?.aborted,
+						signal,
+					});
+					if (signal?.aborted) throw new DOMException("workspace cache wait canceled", "AbortError");
+					const job = completed ?? (await cacheOperations.jobStatus(params.jobId));
+					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "wait", job } };
+				}
 				if (!params.directory) throw new Error(`workspace_cache action=${params.action} requires directory`);
 				const directory = resolve(cwd, params.directory);
 				const maxFiles = params.maxFiles ?? 500;
@@ -1156,11 +1173,11 @@ export default function (pi: ExtensionAPI) {
 					const status = await cacheOperations.status(directory, maxFiles, maxSymbolsPerFile);
 					return { content: [{ type: "text", text: JSON.stringify(status) }], details: { action: "status", status } };
 				}
-				const job = await codeIntelligenceOperations.populateSymbolGraph(directory, maxFiles, maxSymbolsPerFile, params.waitMs ?? 3_000);
+				const job = await cacheOperations.submit(directory, maxFiles, maxSymbolsPerFile, params.waitMs ?? 3_000);
 				return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "populate", job } };
 			},
 			renderCall(args, theme, context) {
-				const action = args.action === "populate" || args.action === "job_status" ? args.action : "status";
+				const action = args.action === "populate" || args.action === "wait" || args.action === "job_status" ? args.action : "status";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(formatWorkspaceCacheCall(action, args, theme));
 				return text;

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

@@ -1,10 +1,18 @@
-import type { JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
+import { type JobSnapshot, type PopulateSymbolGraphResult, resolveLectorDaemonConnection, type WorkspaceCacheStatus } from "@danypops/lector";
+import { connectPushChannel } from "@danypops/vehicle-client/daemon-client";
 import { lectorClient, withWorkspace, workspaceForProjectDirectory } from "../lector-client.ts";
 
+export interface JobWatchHandle {
+	close(): void;
+}
+
+export type JobWatchOutcome = { readonly status: "subscribed"; readonly handle: JobWatchHandle } | { readonly status: "unavailable" };
+
 export interface WorkspaceCacheOperations {
 	status(directory: string, maxFiles: number, maxSymbolsPerFile: number): Promise<WorkspaceCacheStatus>;
-	submit(directory: string, maxFiles: number, maxSymbolsPerFile: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
+	submit(directory: string, maxFiles: number, maxSymbolsPerFile: number, waitMs?: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
+	watchJob?(jobId: string, onJob: (job: JobSnapshot<PopulateSymbolGraphResult>) => void): Promise<JobWatchOutcome>;
 }
 
 export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
@@ -18,7 +26,7 @@ export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
 				},
 			);
 		},
-		submit(directory, maxFiles, maxSymbolsPerFile) {
+		submit(directory, maxFiles, maxSymbolsPerFile, waitMs = 0) {
 			return withWorkspace(
 				() => workspaceForProjectDirectory(directory),
 				async ({ workspaceId }) => {
@@ -26,7 +34,7 @@ export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
 					const { job } = await client.callOnce("job.submit", {
 						operation: "workspace.populateSymbolGraph",
 						input: { workspaceId, maxFiles, maxSymbolsPerFile },
-						waitMs: 0,
+						waitMs,
 					});
 					return job;
 				},
@@ -37,6 +45,33 @@ export function createWorkspaceCacheOperations(): WorkspaceCacheOperations {
 			const { job } = await client.call("job.status", { jobId });
 			return job;
 		},
+		async watchJob(jobId, onJob) {
+			try {
+				const client = await lectorClient();
+				const { topic } = await client.call("job.watch", { jobId });
+				const initialTarget = resolveLectorDaemonConnection();
+				const channel = connectPushChannel({
+					url: () => {
+						const target = resolveLectorDaemonConnection();
+						return `ws://${target.host}:${target.port}/push`;
+					},
+					token: initialTarget.token,
+					topics: [topic],
+					onMessage(receivedTopic) {
+						if (receivedTopic !== topic) return;
+						void client
+							.call("job.status", { jobId })
+							.then(({ job }) => onJob(job))
+							.catch(() => {
+								// The bounded status cadence remains authoritative when push refresh fails.
+							});
+					},
+				});
+				return { status: "subscribed", handle: { close: () => channel.close() } };
+			} catch {
+				return { status: "unavailable" };
+			}
+		},
 	};
 }
 
@@ -74,6 +109,49 @@ export interface MonitorWorkspaceCacheOptions {
 	readonly sleep?: (ms: number) => Promise<void>;
 }
 
+export interface WaitForJobCompletionOptions {
+	readonly pollIntervalMs: number;
+	readonly maxPolls: number;
+	readonly shouldContinue: () => boolean;
+	readonly signal?: AbortSignal;
+	readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/** Waits on Vehicle push delivery and checks status on a bounded cadence when push is unavailable or disconnected. */
+export async function waitForJobCompletion(
+	operations: WorkspaceCacheOperations,
+	jobId: string,
+	options: WaitForJobCompletionOptions,
+): Promise<JobSnapshot<PopulateSymbolGraphResult> | undefined> {
+	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+	let pushedResolve: ((job: JobSnapshot<PopulateSymbolGraphResult>) => void) | undefined;
+	const pushed = new Promise<JobSnapshot<PopulateSymbolGraphResult>>((resolve) => {
+		pushedResolve = resolve;
+	});
+	let watch: JobWatchHandle | undefined;
+	let resolveAbort!: () => void;
+	const aborted = new Promise<void>((resolve) => {
+		resolveAbort = resolve;
+	});
+	const onAbort = () => resolveAbort();
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		const outcome = await operations.watchJob?.(jobId, (job) => pushedResolve?.(job));
+		if (outcome?.status === "subscribed") watch = outcome.handle;
+		for (let poll = 0; poll < options.maxPolls && options.shouldContinue() && !options.signal?.aborted; poll++) {
+			const current = await operations.jobStatus(jobId);
+			if (current.status === "succeeded" || current.status === "failed") return current;
+			const next = await Promise.race([pushed, sleep(options.pollIntervalMs).then(() => undefined), aborted.then(() => undefined)]);
+			if (next?.status === "succeeded" || next?.status === "failed") return next;
+		}
+		if (options.shouldContinue() && !options.signal?.aborted) return operations.jobStatus(jobId);
+		return undefined;
+	} finally {
+		options.signal?.removeEventListener("abort", onAbort);
+		watch?.close();
+	}
+}
+
 /** Drives one bounded session cache lifecycle; Pi event handlers only render its states. */
 export async function monitorWorkspaceCache(operations: WorkspaceCacheOperations, options: MonitorWorkspaceCacheOptions): Promise<void> {
 	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
@@ -108,14 +186,12 @@ export async function monitorWorkspaceCache(operations: WorkspaceCacheOperations
 	}
 	options.onState({ status: "caching", jobId });
 
-	for (let poll = 0; poll < options.maxPolls && options.shouldContinue(); poll++) {
-		await sleep(options.pollIntervalMs);
-		if (!options.shouldContinue()) return;
-		const job = await operations.jobStatus(jobId);
-		if (job.status === "failed") throw new Error(`${job.error.code}: ${job.error.message}`);
-		if (job.status === "succeeded") {
-			reportCompleted(job);
-			return;
-		}
-	}
+	const job = await waitForJobCompletion(operations, jobId, {
+		pollIntervalMs: options.pollIntervalMs,
+		maxPolls: options.maxPolls,
+		shouldContinue: options.shouldContinue,
+		sleep,
+	});
+	if (job?.status === "failed") throw new Error(`${job.error.code}: ${job.error.message}`);
+	if (job?.status === "succeeded") reportCompleted(job);
 }

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

@@ -1,7 +1,7 @@
 import type { JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
 
-type WorkspaceCacheAction = "status" | "populate" | "job_status";
+type WorkspaceCacheAction = "status" | "populate" | "wait" | "job_status";
 
 export function formatWorkspaceCacheCall(
 	action: WorkspaceCacheAction,
@@ -9,9 +9,9 @@ export function formatWorkspaceCacheCall(
 	theme: LectorTheme,
 ): string {
 	const label = theme.fg("toolTitle", theme.bold("workspace_cache"));
-	if (action === "job_status") {
+	if (action === "job_status" || action === "wait") {
 		const jobId = typeof args.jobId === "string" ? args.jobId : "";
-		return `${label} ${theme.fg("accent", "job_status")} ${theme.fg("dim", jobId)}`;
+		return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", jobId)}`;
 	}
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	const maxFiles = typeof args.maxFiles === "number" ? String(args.maxFiles) : "default";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.11.2",
+	"version": "0.12.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -19,7 +19,7 @@
 	},
 	"dependencies": {
 		"@danypops/vehicle-client": "^0.2.0",
-		"@danypops/lector": "^0.15.0",
+		"@danypops/lector": "^0.16.0",
 		"malevich-tui-components": "^0.19.0"
 	},
 	"devDependencies": {