ultimate-pi 0.18.0 → 0.19.0

package/.pi/lib/harness-lens/clients/latency-logger.ts

@@ -0,0 +1,80 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const LATENCY_LOG_DIR = path.join(process.cwd(), ".pi", "harness", ".lens");
+const LATENCY_LOG_FILE = path.join(LATENCY_LOG_DIR, "latency.log");
+
+try {
+	if (!fs.existsSync(LATENCY_LOG_DIR)) {
+		fs.mkdirSync(LATENCY_LOG_DIR, { recursive: true });
+	}
+} catch {}
+
+export interface LatencyEntry {
+	type: "runner" | "tool_result" | "phase";
+	/** ISO timestamp when this entry was written (= finish time for runners) */
+	ts?: string;
+	/** ISO timestamp when the runner/phase started — diff with ts = durationMs */
+	startedAt?: string;
+	toolName?: string;
+	filePath: string;
+	fullPath?: string;
+	phase?: string;
+	durationMs: number;
+	totalDurationMs?: number;
+	result?: string;
+	runnerId?: string;
+	status?: string;
+	diagnosticCount?: number;
+	semantic?: string;
+	/** Per-diagnostic summary when a runner produces findings — aids root-cause analysis */
+	diagnostics?: Array<{
+		rule?: string;
+		message: string;
+		line?: number;
+		semantic?: string;
+	}>;
+	/** For dispatch_complete: actual wall-clock time (groups run in parallel) */
+	wallClockMs?: number;
+	/** For dispatch_complete: sum of all individual runner durationMs */
+	sumMs?: number;
+	/** wallClockMs - sumMs ≥ 0 means parallelism saved this many ms */
+	parallelGainMs?: number;
+	metadata?: Record<string, unknown>;
+}
+
+export function logLatency(entry: LatencyEntry): void {
+	if (
+		process.env.PI_LENS_TEST_MODE === "1" ||
+		(process.env.VITEST && process.env.PI_LENS_TEST_MODE !== "0")
+	) {
+		return;
+	}
+	const line = `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`;
+	try {
+		fs.appendFileSync(LATENCY_LOG_FILE, line);
+	} catch {}
+}
+
+export function getLatencyLogPath(): string {
+	return LATENCY_LOG_FILE;
+}
+
+export function readLatencyLog(limit = 100): LatencyEntry[] {
+	try {
+		const content = fs.readFileSync(LATENCY_LOG_FILE, "utf-8");
+		const lines = content.trim().split(/\r?\n/).filter(Boolean);
+		return lines
+			.slice(-limit)
+			.map((line) => JSON.parse(line))
+			.reverse();
+	} catch {
+		return [];
+	}
+}
+
+export function clearLatencyLog(): void {
+	try {
+		fs.writeFileSync(LATENCY_LOG_FILE, "");
+	} catch {}
+}

package/.pi/lib/harness-lens/clients/lens-config.ts

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+
+export interface PiLensGlobalConfig {
+	noLens?: boolean;
+	noLsp?: boolean;
+	noAutoformat?: boolean;
+	immediateFormat?: boolean;
+	lensGuard?: boolean;
+}
+
+export function loadPiLensGlobalConfig(): PiLensGlobalConfig {
+	const configPath = process.env.PI_LENS_CONFIG_PATH;
+	if (!configPath) return {};
+	try {
+		const raw = fs.readFileSync(configPath, "utf-8");
+		return JSON.parse(raw) as PiLensGlobalConfig;
+	} catch {
+		return {};
+	}
+}
+
+export function resolvePiLensFlag(
+	name: string,
+	getFlag: (name: string) => boolean | string | undefined,
+	global: PiLensGlobalConfig,
+): boolean | string | undefined {
+	const fromCli = getFlag(name);
+	if (fromCli !== undefined) return fromCli;
+	switch (name) {
+		case "no-lens":
+			return global.noLens;
+		case "no-lsp":
+			return global.noLsp;
+		case "no-autoformat":
+			return global.noAutoformat;
+		case "immediate-format":
+			return global.immediateFormat;
+		case "lens-guard":
+			return global.lensGuard;
+		default:
+			return undefined;
+	}
+}

package/.pi/lib/harness-lens/clients/lens-events.ts

@@ -0,0 +1,164 @@
+export interface LensDiagnostic {
+	id?: string;
+	message: string;
+	filePath?: string;
+	line?: number;
+	column?: number;
+	severity?: string;
+	semantic?: string;
+	tool?: string;
+	rule?: string;
+	defectClass?: string;
+	matchedText?: string;
+	fixSuggestion?: string;
+}
+
+export const LENS_EVENT_VERSION = 1;
+
+export const LENS_EVENT_NAMES = {
+	analysisComplete: "pi-lens/analysis-complete",
+	findings: "pi-lens/findings",
+	turnFindings: "pi-lens/turn-findings",
+} as const;
+
+type LensEventName = (typeof LENS_EVENT_NAMES)[keyof typeof LENS_EVENT_NAMES];
+
+type LensEventBus = {
+	emit?: (event: string, payload: unknown) => void;
+};
+
+export interface LensTelemetryPayload {
+	model: string;
+	sessionId: string;
+	turnIndex: number;
+	writeIndex: number;
+}
+
+export interface LensAnalysisPayload extends LensTelemetryPayload {
+	version: typeof LENS_EVENT_VERSION;
+	source: "pi-lens";
+	timestamp: string;
+	cwd: string;
+	filePath: string;
+	toolName: string;
+	diagnostics: LensDiagnostic[];
+	blockers: LensDiagnostic[];
+	warnings: LensDiagnostic[];
+	fixed: LensDiagnostic[];
+	resolvedCount: number;
+	hasBlockers: boolean;
+	fileModified: boolean;
+	changedFiles: string[];
+	durationMs: number;
+}
+
+export interface LensTurnFindingsPayload {
+	version: typeof LENS_EVENT_VERSION;
+	source: "pi-lens";
+	timestamp: string;
+	cwd: string;
+	filePaths: string[];
+	sessionId: string;
+	turnIndex: number;
+	blockerSections: number;
+	advisorySections: number;
+	content: string;
+}
+
+let lensEventBus: LensEventBus | undefined;
+
+export function initLensEvents(pi: { events?: LensEventBus }): void {
+	lensEventBus = pi.events;
+}
+
+function truncateText(
+	value: string | undefined,
+	maxChars: number,
+): string | undefined {
+	if (value === undefined) return undefined;
+	if (value.length <= maxChars) return value;
+	return `${value.slice(0, maxChars)}…`;
+}
+
+function normalizeDiagnostic(diagnostic: LensDiagnostic): LensDiagnostic {
+	return {
+		...diagnostic,
+		message: truncateText(diagnostic.message, 1_000) ?? "",
+		matchedText: truncateText(diagnostic.matchedText, 500),
+		fixSuggestion: truncateText(diagnostic.fixSuggestion, 500),
+	};
+}
+
+function normalizeDiagnostics(diagnostics: LensDiagnostic[]): LensDiagnostic[] {
+	return diagnostics.map(normalizeDiagnostic);
+}
+
+function emitLensEvent(eventName: LensEventName, payload: unknown): void {
+	const emit = lensEventBus?.emit;
+	if (!emit) return;
+
+	setImmediate(() => {
+		try {
+			emit.call(lensEventBus, eventName, payload);
+		} catch {
+			// Inter-extension events are observational. A listener must never break
+			// the pi-lens hook path or delay agent progress with error handling noise.
+		}
+	});
+}
+
+export function emitLensAnalysisComplete(
+	payload: Omit<
+		LensAnalysisPayload,
+		| "version"
+		| "source"
+		| "timestamp"
+		| "diagnostics"
+		| "blockers"
+		| "warnings"
+		| "fixed"
+	> & {
+		diagnostics: LensDiagnostic[];
+		blockers: LensDiagnostic[];
+		warnings: LensDiagnostic[];
+		fixed: LensDiagnostic[];
+	},
+): void {
+	const normalized: LensAnalysisPayload = {
+		version: LENS_EVENT_VERSION,
+		source: "pi-lens",
+		timestamp: new Date().toISOString(),
+		...payload,
+		diagnostics: normalizeDiagnostics(payload.diagnostics),
+		blockers: normalizeDiagnostics(payload.blockers),
+		warnings: normalizeDiagnostics(payload.warnings),
+		fixed: normalizeDiagnostics(payload.fixed),
+	};
+
+	emitLensEvent(LENS_EVENT_NAMES.analysisComplete, normalized);
+	if (
+		normalized.diagnostics.length > 0 ||
+		normalized.blockers.length > 0 ||
+		normalized.warnings.length > 0 ||
+		normalized.fixed.length > 0
+	) {
+		emitLensEvent(LENS_EVENT_NAMES.findings, normalized);
+	}
+}
+
+export function emitLensTurnFindings(
+	payload: Omit<
+		LensTurnFindingsPayload,
+		"version" | "source" | "timestamp" | "content"
+	> & {
+		content: string;
+	},
+): void {
+	emitLensEvent(LENS_EVENT_NAMES.turnFindings, {
+		version: LENS_EVENT_VERSION,
+		source: "pi-lens",
+		timestamp: new Date().toISOString(),
+		...payload,
+		content: truncateText(payload.content, 8_000) ?? "",
+	} satisfies LensTurnFindingsPayload);
+}

package/.pi/lib/harness-lens/clients/lsp/aggregation.ts

@@ -0,0 +1,91 @@
+/**
+ * Diagnostic Aggregation Utilities for pi-lens LSP
+ *
+ * Provides result-aware racing for multi-client diagnostic collection.
+ * Replaces the simple Promise.race + grace window pattern with one that
+ * only fires the grace window when a client actually returned diagnostics.
+ */
+
+/**
+ * Race a set of promises to completion, resolving as soon as the
+ * `shouldComplete` predicate is satisfied by the accumulated results.
+ *
+ * Key difference from Promise.race: Promise.race resolves when ANY promise
+ * settles (even with an empty/useless result). raceToCompletion only resolves
+ * early when results meet a quality threshold, optionally with a grace window
+ * to let more results accumulate.
+ *
+ * @param promises - Array of promises producing results
+ * @param shouldComplete - Called after each settled promise with all results
+ *   accumulated so far. Return true to trigger early completion.
+ * @param options.timeoutMs - Hard deadline; after this, resolve with whatever is ready
+ * @param options.graceMs - After shouldComplete returns true, wait this many ms
+ *   for additional results before finalizing. 0 = finalize immediately.
+ */
+export async function raceToCompletion<T>(
+	promises: Promise<T>[],
+	shouldComplete: (results: T[]) => boolean,
+	options: { timeoutMs: number; graceMs?: number } = { timeoutMs: 1500 },
+): Promise<T[]> {
+	const results: (T | undefined)[] = new Array(promises.length).fill(undefined);
+	let graceTimer: ReturnType<typeof setTimeout> | undefined;
+	let completed = false;
+	let remaining = promises.length;
+
+	return new Promise((resolve) => {
+		const timeout = setTimeout(() => {
+			completed = true;
+			if (graceTimer) clearTimeout(graceTimer);
+			resolve(results.filter((r): r is T => r !== undefined));
+		}, options.timeoutMs);
+
+		const finalize = () => {
+			if (completed) return;
+			completed = true;
+			clearTimeout(timeout);
+			if (graceTimer) clearTimeout(graceTimer);
+			resolve(results.filter((r): r is T => r !== undefined));
+		};
+
+		const check = () => {
+			if (completed) return;
+
+			if (remaining === 0) {
+				finalize();
+				return;
+			}
+
+			const collected = results.filter((r): r is T => r !== undefined);
+			if (shouldComplete(collected)) {
+				if (
+					options.graceMs !== undefined &&
+					options.graceMs > 0 &&
+					!graceTimer
+				) {
+					// Start grace window — more results may arrive
+					graceTimer = setTimeout(() => finalize(), options.graceMs);
+				} else {
+					finalize();
+				}
+			}
+		};
+
+		for (let i = 0; i < promises.length; i++) {
+			const index = i;
+			promises[i]
+				.then((result) => {
+					if (!completed) {
+						results[index] = result;
+						remaining--;
+						check();
+					}
+				})
+				.catch(() => {
+					if (!completed) {
+						remaining--;
+						check();
+					}
+				});
+		}
+	});
+}