pi-jev-find 0.1.0

package/src/judge/jev-judge.ts

@@ -0,0 +1,169 @@
+/**
+ * Jev judge: native System One probability API (TypeSafe's `POST /v1/systemone`,
+ * the same wire jegrep uses). The cascade's `JudgeRequest` — `{state, questions}` —
+ * is forwarded verbatim with the model id; answers come back as absolute noul
+ * probabilities, no chat-JSON emulation.
+ *
+ * Ported from oh-my-pi `packages/ai/src/judgment/typesafe.ts` (MIT), reduced to
+ * the noul-only surface this cascade needs and driven entirely by environment
+ * variables so the extension carries no provider plumbing:
+ *
+ * - `JEV_API_KEY` (or `TYPESAFE_API_KEY`, jegrep-compatible)
+ * - `JEV_BASE_URL` (or `TYPESAFE_BASE_URL`; default `https://api.typesafe.ai`)
+ * - `JEV_MODEL` (or `TYPESAFE_DEFAULT_MODEL`; default `jev-latest`)
+ */
+import type { Judge, JudgeRequest, JudgeAnswer, JudgmentResult } from "./types";
+
+const DEFAULT_BASE_URL = "https://api.typesafe.ai";
+const DEFAULT_MODEL = "jev-latest";
+const JUDGMENT_ROUTE = "/v1/systemone";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_MAX_MS = 5_000;
+
+/** Resolved Jev configuration, for the /find status line. */
+export interface JevConfig {
+	apiKey: string;
+	baseUrl: string;
+	model: string;
+	/** Which environment variable supplied the key; never the key itself. */
+	keySource: string;
+}
+
+function readEnv(env: Record<string, string | undefined>, name: string, fallbackName?: string): { value: string | undefined; source: string } {
+	const primary = env[name]?.trim();
+	if (primary !== undefined && primary.length > 0) return { value: primary, source: name };
+	if (fallbackName === undefined) return { value: undefined, source: name };
+	const fallback = env[fallbackName]?.trim();
+	return { value: fallback !== undefined && fallback.length > 0 ? fallback : undefined, source: fallbackName };
+}
+
+/**
+ * Resolve the Jev endpoint from the environment. `JEV_*` names win;
+ * `TYPESAFE_*` names are honored as jegrep-compatible fallbacks. Throws a
+ * user-actionable message when no API key is configured.
+ */
+export function resolveJevConfig(env: Record<string, string | undefined> = process.env): JevConfig {
+	const key = readEnv(env, "JEV_API_KEY", "TYPESAFE_API_KEY");
+	if (key.value === undefined) {
+		throw new Error("pi-jev-find needs a Jev API key. Set JEV_API_KEY (or TYPESAFE_API_KEY) in your environment.");
+	}
+	const baseUrl = (readEnv(env, "JEV_BASE_URL", "TYPESAFE_BASE_URL").value ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+	const model = readEnv(env, "JEV_MODEL", "TYPESAFE_DEFAULT_MODEL").value ?? DEFAULT_MODEL;
+	return { apiKey: key.value, baseUrl, model, keySource: key.source };
+}
+
+/** Non-2xx response from the Jev API. */
+export class JevApiError extends Error {
+	constructor(
+		message: string,
+		readonly status: number,
+	) {
+		super(message);
+		this.name = "JevApiError";
+	}
+}
+
+interface SystemOneResponse {
+	model: string;
+	answers: Record<string, JudgeAnswer & { type?: string }>;
+	usage: { input_tokens: number; output_tokens: number; cost?: number };
+}
+
+function backoffMs(attempt: number, response: Response | undefined): number {
+	const retryAfter = response?.headers.get("retry-after");
+	if (retryAfter) {
+		const seconds = Number.parseFloat(retryAfter);
+		if (Number.isFinite(seconds)) return Math.min(seconds * 1000, BACKOFF_MAX_MS);
+	}
+	return Math.min(BACKOFF_BASE_MS * 2 ** attempt, BACKOFF_MAX_MS);
+}
+
+/** A {@link Judge} served by the native System One probability API. */
+export class JevJudge implements Judge {
+	readonly model: string;
+	readonly baseUrl: string;
+	readonly #apiKey: string;
+	readonly #fetch: typeof fetch;
+	readonly #timeoutMs: number;
+
+	constructor(
+		config: JevConfig,
+		options: { fetch?: typeof fetch; timeoutMs?: number } = {},
+	) {
+		this.model = config.model;
+		this.baseUrl = config.baseUrl;
+		this.#apiKey = config.apiKey;
+		this.#fetch = options.fetch ?? fetch;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	}
+
+	async judge(request: JudgeRequest, options: { signal?: AbortSignal } = {}): Promise<JudgmentResult> {
+		const signal = options.signal;
+		const body = JSON.stringify({ state: request.state, model: this.model, questions: request.questions });
+		let response: SystemOneResponse | undefined;
+		for (let attempt = 0; ; attempt++) {
+			signal?.throwIfAborted();
+			let http: Response;
+			try {
+				const timeout = AbortSignal.timeout(this.#timeoutMs);
+				http = await this.#fetch(`${this.baseUrl}${JUDGMENT_ROUTE}`, {
+					method: "POST",
+					headers: {
+						Authorization: `Bearer ${this.#apiKey}`,
+						Accept: "application/json",
+						"Content-Type": "application/json",
+					},
+					body,
+					signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+				});
+			} catch (error) {
+				// Transport failures (network, timeout) are transient: bounded retry.
+				if (signal?.aborted || attempt + 1 >= MAX_ATTEMPTS) throw error;
+				await sleep(backoffMs(attempt, undefined), signal);
+				continue;
+			}
+			if (http.ok) {
+				response = (await http.json()) as SystemOneResponse;
+				break;
+			}
+			const text = await http.text();
+			const error = new JevApiError(`jev API error (${http.status}): ${text}`, http.status);
+			const transient = http.status === 408 || http.status === 429 || http.status >= 500;
+			if (!transient || attempt + 1 >= MAX_ATTEMPTS) throw error;
+			await sleep(backoffMs(attempt, http), signal);
+		}
+		if (response === undefined) throw new JevApiError("jev API returned no response", 0);
+		// Every question must come back typed; a partial envelope is a hard error,
+		// not silently unjudged entries.
+		for (const id of Object.keys(request.questions)) {
+			const answer = response.answers[id];
+			if (answer === undefined || answer.type !== request.questions[id]?.type) {
+				throw new JevApiError(`jev response is missing a "${request.questions[id]?.type}" answer for question "${id}"`, 0);
+			}
+		}
+		return {
+			answers: response.answers,
+			usage: {
+				input: response.usage.input_tokens,
+				output: response.usage.output_tokens,
+				cost: response.usage.cost ?? 0,
+			},
+		};
+	}
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => resolve(), ms);
+		signal?.addEventListener(
+			"abort",
+			() => {
+				clearTimeout(timer);
+				reject(signal.reason ?? new Error("aborted"));
+			},
+			{ once: true },
+		);
+	});
+}

package/src/judge/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Judge wire contract: the three request shapes the cascade sends, and the
+ * answer shape every judge backend must produce. Mirrors the omp
+ * `@oh-my-pi/pi-ai` noul surface (MIT, oh-my-pi); pi has no native noul API,
+ * so {@link ../judge/pi-model-judge} emulates it with a chat completion.
+ */
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { readonly [key: string]: JsonValue };
+
+/** One probability question. `instructions` is self-contained per entry. */
+export interface NoulQuestion {
+	type: "noul";
+	instructions: string;
+}
+
+/** A judgment request: JSON state plus noul questions keyed by entry. */
+export interface JudgeRequest {
+	state: { readonly [key: string]: JsonValue };
+	questions: Record<string, NoulQuestion>;
+}
+
+/** A yes-probability in [0,1], or absent when the judge produced nothing usable. */
+export interface JudgeAnswer {
+	noul?: number;
+}
+
+export interface JudgeUsage {
+	input: number;
+	output: number;
+	cost: number;
+}
+
+export interface JudgmentResult {
+	answers: Record<string, JudgeAnswer>;
+	usage: JudgeUsage;
+}
+
+export interface Judge {
+	judge(request: JudgeRequest, options: { signal?: AbortSignal }): Promise<JudgmentResult>;
+}

package/src/prompts/find-name-question.ts

@@ -0,0 +1,2 @@
+export const nameQuestionTemplate = `Is the file tagged {{key}} ("{{name}}") likely to contain what this search is looking for: "{{query}}"? Judge by its name, size, and place in \`tree\`; apply \`criteria.file\`.
+`;

package/src/prompts/find-passage-question.ts

@@ -0,0 +1,2 @@
+export const passageQuestionTemplate = `Does \`passages.{{key}}\` substantively implement, define, or explain part of "{{query}}"? Apply \`criteria\`.
+`;

package/src/prompts/find-sketch-question.ts

@@ -0,0 +1,2 @@
+export const sketchQuestionTemplate = `Could passage {{key}} implement a requested step of search? Apply criteria.
+`;

package/src/render.ts

@@ -0,0 +1,97 @@
+/**
+ * TUI rendering for the find tool: a one-line call preview and a collapsed /
+ * expanded result view with judge-calibrated score gauges and range heat.
+ * Components are plain structural objects ({ render, invalidate }) so no
+ * runtime pi-tui import is required.
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import { rankedHeat } from "./cascade/passages.ts";
+import type { FindDetails, FindToolParams, FindHit } from "./types.ts";
+
+/** The theme surface this renderer uses; structurally satisfied by pi's Theme. */
+export interface ThemeLike {
+	fg(name: string, text: string): string;
+	bold(text: string): string;
+}
+
+/** Line ranges shown per hit in the expanded view. */
+const RANGES_SHOWN = 3;
+/** Heat gauge segments. */
+const GAUGE_SEGMENTS = 10;
+
+function component(render: (width: number) => string[]): Component {
+	return {
+		render,
+		invalidate() {},
+	};
+}
+
+/** Tabs to spaces; terminal-safe single line. */
+function sanitize(text: string): string {
+	return text.replace(/\t/g, "  ");
+}
+
+/** `0.94` → filled gauge `█████████░`. */
+function gauge(p: number): string {
+	const filled = Math.round(Math.min(1, Math.max(0, p)) * GAUGE_SEGMENTS);
+	return "█".repeat(filled) + "░".repeat(GAUGE_SEGMENTS - filled);
+}
+
+/** Heat color: strong hits green, mid amber, weak dim. */
+function heat(theme: ThemeLike, p: number, text: string): string {
+	if (p >= 0.6) return theme.fg("success", text);
+	if (p >= 0.4) return theme.fg("warning", text);
+	return theme.fg("dim", text);
+}
+
+/** The pending call preview: `find "query" [in path]`. */
+export function renderFindCall(args: Partial<FindToolParams>, theme: ThemeLike): Component {
+	let text = theme.fg("toolTitle", theme.bold("find ")) + theme.fg("accent", sanitize(`"${args.query ?? ""}"`));
+	if (args.path !== undefined) text += theme.fg("dim", ` in ${sanitize(args.path)}`);
+	const keywords = args.grep_keywords ?? [];
+	if (keywords.length > 0) text += theme.fg("dim", ` [${keywords.map(sanitize).join(", ")}]`);
+	return component(() => [text]);
+}
+
+export function renderFindResult(
+	details: FindDetails | undefined,
+	isError: boolean,
+	expanded: boolean,
+	theme: ThemeLike,
+): Component {
+	if (details === undefined) {
+		return component(() => [theme.fg(isError ? "error" : "dim", isError ? "find failed" : "find")]);
+	}
+	const { hits, stats, threshold, elapsedMs } = details;
+	const lines: string[] = [];
+	const head =
+		hits.length === 0
+			? theme.fg("warning", `no hits (τ ${threshold.toFixed(2)})`)
+			: theme.fg("success", `${hits.length} hit${hits.length === 1 ? "" : "s"}`) +
+				theme.fg("dim", ` (τ ${threshold.toFixed(2)}), strongest first`);
+	lines.push(head);
+	if (expanded) {
+		for (const hit of hits) lines.push(...hitLines(hit, theme));
+	}
+	lines.push(
+		theme.fg(
+			"dim",
+			`listed ${stats.filesListed} · judged ${stats.judged} · read ${stats.filesRead} files · ${stats.requests} requests · ${stats.inputTokens + stats.outputTokens} tokens · $${stats.cost.toFixed(4)} · ${(elapsedMs / 1000).toFixed(1)}s wall / ${(stats.apiMs / 1000).toFixed(1)}s api${stats.errors > 0 ? ` · ${stats.errors} errors` : ""}`,
+		),
+	);
+	return component(() => lines);
+}
+
+function hitLines(hit: FindHit, theme: ThemeLike): string[] {
+	const out: string[] = [];
+	const score = hit.contentScore.toFixed(2);
+	const coverage = hit.truncated ? `${hit.linesSeen} lines judged, partial` : `${hit.linesSeen} lines judged`;
+	out.push(`${theme.fg("accent", sanitize(hit.rel))}  ${heat(theme, hit.contentScore, score)}  ${theme.fg("dim", coverage)}`);
+	for (const range of rankedHeat(hit.ranges, RANGES_SHOWN)) {
+		const span = range.start === range.end ? String(range.start) : `${range.start}-${range.end}`;
+		out.push(
+			`  ${theme.fg("dim", sanitize(`${hit.rel}:${span}`))}  ${heat(theme, range.p, `${gauge(range.p)} ${range.p.toFixed(2)}`)}  ${sanitize(range.snippet)}`,
+		);
+	}
+	return out;
+}

package/src/rg.ts

@@ -0,0 +1,99 @@
+/**
+ * Thin ripgrep runner shared by the lexical scan and the file listing — the
+ * pi-jev-find replacement for omp's `@oh-my-pi/pi-natives` grep/glob (MIT,
+ * oh-my-pi). `rg` is the same engine both projects ultimately rely on.
+ *
+ * Hardening: `RIPGREP_CONFIG_PATH` is cleared so a user config cannot inject
+ * flags that break the `--json`/`--files` contracts; runs are killed on abort
+ * signal or timeout; stderr is capped.
+ */
+import { spawn } from "node:child_process";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export type RgFailure = "missing" | "failed" | "timeout" | "aborted";
+
+export class RgError extends Error {
+	constructor(
+		readonly kind: RgFailure,
+		message: string,
+	) {
+		super(message);
+		this.name = "RgError";
+	}
+}
+
+export interface RgRun {
+	/** 0 = matches, 1 = no matches (both success). */
+	exitCode: number;
+	/** Raw stdout bytes — callers decode (`--json` lines or `--files --null` paths). */
+	stdout: Buffer;
+}
+
+export interface RgOptions {
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}
+
+/**
+ * Run `rg` in `root` and collect stdout. Rejects with {@link RgError}:
+ * `missing` when rg is not on PATH, `failed` on exit code > 1 (rg: 2), and
+ * `timeout`/`aborted` when the run was killed.
+ */
+export async function runRg(root: string, args: readonly string[], options: RgOptions = {}): Promise<RgRun> {
+	if (options.signal?.aborted) throw new RgError("aborted", "aborted");
+	const child = spawn("rg", args, {
+		cwd: root,
+		stdio: ["ignore", "pipe", "pipe"],
+		env: { ...process.env, RIPGREP_CONFIG_PATH: "" },
+	});
+	const chunks: Buffer[] = [];
+	let stderr = "";
+	let killed: "timeout" | "aborted" | null = null;
+	const closed = Promise.withResolvers<number | null>();
+
+	child.stdout.on("data", (chunk: Buffer) => chunks.push(chunk));
+	child.stderr.on("data", (chunk: Buffer) => {
+		if (stderr.length < 4096) stderr += chunk.toString("utf8");
+	});
+	child.once("error", error => {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			closed.reject(new RgError("missing", "ripgrep (rg) is required but was not found on PATH"));
+		} else {
+			closed.reject(new RgError("failed", `rg failed to start: ${error.message}`));
+		}
+	});
+	child.once("close", code => closed.resolve(code));
+
+	const timer = setTimeout(() => {
+		killed = "timeout";
+		child.kill("SIGKILL");
+	}, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+	const onAbort = () => {
+		killed = "aborted";
+		child.kill("SIGKILL");
+	};
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+
+	try {
+		const code = await closed.promise;
+		if (killed === "aborted" || options.signal?.aborted) throw new RgError("aborted", "aborted");
+		if (killed === "timeout") throw new RgError("timeout", `rg timed out after ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`);
+		if (code === null) throw new RgError("failed", `rg terminated unexpectedly: ${stderr.trim()}`);
+		const stdout = Buffer.concat(chunks);
+		// Exit 2 with a completed search cycle (a `summary` event was emitted) means
+		// rg finished but found nothing searchable ("No files were searched") or hit
+		// per-file traversal errors; both are empty results, not tool failures.
+		if (code > 1 && !stdout.includes('"summary"')) {
+			throw new RgError("failed", `rg exited ${code}: ${stderr.trim()}`);
+		}
+		return { exitCode: code, stdout };
+	} catch (error) {
+		child.kill("SIGKILL");
+		throw error;
+	} finally {
+		clearTimeout(timer);
+		options.signal?.removeEventListener("abort", onAbort);
+	}
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared result shapes. These mirror the omp `@oh-my-pi/pi-tui/tools/find`
+ * types (MIT, oh-my-pi) so the cascade port stays shape-compatible.
+ */
+
+/** A judged line range: 1-based inclusive lines, yes-probability, one-line preview. */
+export interface FindRange {
+	start: number;
+	end: number;
+	p: number;
+	snippet: string;
+}
+
+/** One file hit returned by the cascade. */
+export interface FindHit {
+	/** Root-relative display path with `/` separators. */
+	rel: string;
+	/** Name-judge probability when the filename was judged; undefined for lexical champions. */
+	nameScore?: number;
+	/** Best passage score across judged windows. */
+	contentScore: number;
+	/** Judged ranges, strongest first. */
+	ranges: FindRange[];
+	/** Lines actually inspected. */
+	linesSeen: number;
+	/** Whether the read was cut at the byte cap. */
+	truncated: boolean;
+}
+
+/** Parameters of the find tool, matching the typebox schema in index.ts. */
+export interface FindToolParams {
+	query: string;
+	grep_keywords: string[];
+	path?: string;
+}
+
+/** Everything the renderer and the tool result need besides the raw digest. */
+export interface FindDetails {
+	query: string;
+	keywords: string[];
+	threshold: number;
+	hits: FindHit[];
+	stats: FindStats;
+	elapsedMs: number;
+	cwd: string;
+	/** Display form of the search scope when narrower than cwd, with trailing slash. */
+	scopePath?: string;
+}
+
+/** Cascade accounting surfaced to the renderer and stats footer. */
+export interface FindStats {
+	filesListed: number;
+	requests: number;
+	errors: number;
+	judged: number;
+	filesRead: number;
+	fileBytes: number;
+	inputTokens: number;
+	outputTokens: number;
+	cost: number;
+	apiMs: number;
+	windowsJudged: number;
+	windowsPruned: number;
+	mapCards: number;
+	failures: string[];
+}