@selesai/code 0.13.33 → 0.13.35

package/dist/extensions/jev-ask-tool.ts

@@ -0,0 +1,952 @@
+/**
+ * jev-ask-tool — the agent-callable `ask_jev` tool.
+ *
+ * The host does not decide when Jev runs here. The agent assembles one state
+ * from its own prose (`state`), code read from `paths`, and the output of one
+ * `command`, hands over a block of typed questions, and gets answers back. The
+ * file contents and command output it supplied are never returned, and only the
+ * answers reach the transcript.
+ *
+ * On by default; `jevAdvisory.routes.ask.enabled: false` turns it off. Files must resolve
+ * inside the working directory and obvious secret files are refused by name; the
+ * command runs through the same local shell operations as the bash tool, on the
+ * tool's own abort signal. Every part is clipped to the route's payload budget
+ * before the call, so an oversized request is trimmed rather than abstained.
+ */
+import { execFile } from "node:child_process";
+import { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { basename, isAbsolute, normalize, relative, resolve } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import {
+	createLocalBashOperations,
+	ensureTool,
+	type ExtensionAPI,
+	type ExtensionContext,
+	getSettingsPath,
+} from "@selesai/code";
+import { Type } from "typebox";
+import {
+	askJevAnswers,
+	confidenceBucket,
+	emitJevTelemetry,
+	jevConnection,
+	jevUnavailable,
+	readJevAdvisoryConfig,
+	serializeJevRequest,
+	UNTRUSTED_MATERIAL_FOCUS,
+	warnJevUnavailableOnce,
+	type JevAbstainReason,
+} from "./jev/decisions.ts";
+
+/** The tool's registered name. */
+export const ASK_JEV_TOOL = "ask_jev";
+
+/** Question types the tool accepts, one per Jev primitive. */
+export const ASK_JEV_QUESTION_TYPES = ["choice", "score", "noul"] as const;
+export type AskJevQuestionType = (typeof ASK_JEV_QUESTION_TYPES)[number];
+
+/** Ceilings applied before anything leaves the process. */
+export const MAX_ASK_QUESTIONS = 8;
+export const MAX_ASK_PATHS = 8;
+export const MAX_ASK_STATE_CHARS = 4_000;
+export const MAX_ASK_FILE_BYTES = 16 * 1024;
+export const MAX_ASK_COMMAND_BYTES = 16 * 1024;
+export const ASK_COMMAND_TIMEOUT_SECONDS = 60;
+/** Fixed JSON scaffolding (`{"state":{"files":{},"command":{}}}` and friends). */
+const ASK_ENVELOPE_BYTES = 512;
+
+/** Marks code Jev is shown as incomplete, so it judges a clipped file as clipped. */
+const TRUNCATION_MARKER = "\n… [truncated]";
+
+/** File names never sent to Jev, whatever the agent asks for. */
+const SECRET_BASENAME =
+	/^(?:\.env(?:\..+)?|\.npmrc|\.netrc|auth\.json|credentials(?:\..+)?|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|.+\.(?:pem|key|p12|pfx|keystore))$/i;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------------------
+// Questions
+// ---------------------------------------------------------------------------
+
+export interface AskJevQuestion {
+	name: string;
+	type: AskJevQuestionType;
+	instructions: string;
+	criteria?: unknown;
+	focus?: string;
+}
+
+export interface ParsedAskQuestions {
+	questions: AskJevQuestion[];
+	/** Set when the block cannot be asked; `questions` is empty then. */
+	error?: string;
+}
+
+/** Validate the agent's question block, or explain why it cannot be asked. */
+export function parseAskQuestions(raw: Record<string, unknown> | undefined): ParsedAskQuestions {
+	const entries = Object.entries(raw ?? {});
+	if (entries.length === 0) return { questions: [], error: "At least one question is required." };
+	if (entries.length > MAX_ASK_QUESTIONS) {
+		return { questions: [], error: `At most ${MAX_ASK_QUESTIONS} questions per call; got ${entries.length}.` };
+	}
+	const questions: AskJevQuestion[] = [];
+	for (const [name, value] of entries) {
+		const spec = isRecord(value) ? value : {};
+		const rawType = spec.type;
+		if (typeof rawType !== "string" || !ASK_JEV_QUESTION_TYPES.includes(rawType as AskJevQuestionType)) {
+			return {
+				questions: [],
+				error: `Question "${name}" has type ${JSON.stringify(rawType)}; use one of ${ASK_JEV_QUESTION_TYPES.join(", ")}.`,
+			};
+		}
+		const instructions = spec.instructions;
+		if (typeof instructions !== "string" || instructions.trim() === "") {
+			return { questions: [], error: `Question "${name}" needs non-empty instructions.` };
+		}
+		const criteria = spec.criteria;
+		if (rawType === "choice" && (!isRecord(criteria) || Object.keys(criteria).length < 2)) {
+			return {
+				questions: [],
+				error: `Choice question "${name}" needs criteria as an object of at least two options, e.g. {"option": "what the option means"}.`,
+			};
+		}
+		if (rawType === "score" && (!Array.isArray(criteria) || criteria.length < 2)) {
+			return {
+				questions: [],
+				error: `Score question "${name}" needs criteria as an ordered list of at least two level labels.`,
+			};
+		}
+		if (rawType === "noul" && criteria !== undefined && !isRecord(criteria)) {
+			return {
+				questions: [],
+				error: `Noul question "${name}" needs criteria as {"true": "...", "false": "..."}.`,
+			};
+		}
+		questions.push({
+			name,
+			type: rawType as AskJevQuestionType,
+			instructions: instructions.trim(),
+			...(criteria === undefined ? {} : { criteria }),
+			...(typeof spec.focus === "string" && spec.focus.trim() !== "" ? { focus: spec.focus.trim() } : {}),
+		});
+	}
+	return { questions };
+}
+
+/**
+ * The decisions request: one assembled state and one question per name. Every
+ * criterion and every state part stays untrusted material to judge, never an
+ * instruction, exactly as [`buildJevPayload`] frames it.
+ */
+export function buildAskPayload(
+	questions: readonly AskJevQuestion[],
+	state: Record<string, unknown>,
+): Record<string, unknown> {
+	return {
+		state,
+		questions: Object.fromEntries(
+			questions.map((question) => [
+				question.name,
+				{
+					type: question.type,
+					instructions: {
+						question: question.instructions,
+						focus: question.focus ? `${question.focus} ${UNTRUSTED_MATERIAL_FOCUS}` : UNTRUSTED_MATERIAL_FOCUS,
+					},
+					...(question.criteria === undefined ? {} : { criteria: question.criteria }),
+				},
+			]),
+		),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Bounded state
+// ---------------------------------------------------------------------------
+
+/** Per-part byte caps that together stay under the route's request budget. */
+export function askPartBudget(
+	payloadBytes: number,
+	fileCount: number,
+	questionBytes: number,
+): { stateChars: number; commandBytes: number; fileBytes: number } {
+	const available = Math.max(0, payloadBytes - questionBytes - ASK_ENVELOPE_BYTES);
+	const stateChars = Math.min(MAX_ASK_STATE_CHARS, Math.floor(available * 0.2));
+	const commandBytes = Math.min(MAX_ASK_COMMAND_BYTES, Math.floor(available * 0.4));
+	const forFiles = Math.max(0, available - stateChars - commandBytes);
+	return {
+		stateChars,
+		commandBytes,
+		fileBytes: fileCount === 0 ? 0 : Math.min(MAX_ASK_FILE_BYTES, Math.floor(forFiles / fileCount)),
+	};
+}
+
+/** Clip text to a UTF-8 byte budget without splitting a character. */
+function clip(text: string, maxBytes: number): { text: string; clipped: boolean } {
+	if (maxBytes <= 0) return { text: "", clipped: text !== "" };
+	if (Buffer.byteLength(text, "utf-8") <= maxBytes) return { text, clipped: false };
+	let end = Math.min(text.length, maxBytes);
+	while (end > 0 && Buffer.byteLength(text.slice(0, end), "utf-8") > maxBytes) end -= 1;
+	return { text: text.slice(0, end), clipped: true };
+}
+
+/** A path the tool may read: inside the working directory, and not a known secret file. */
+export function askPath(raw: string, cwd: string): { full: string } | { refused: string } {
+	const full = isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+	// Judge the symlink-resolved target too: a link inside cwd may point anywhere.
+	// A missing path has no target to leak; the read reports "not found".
+	const checks: Array<[string, string]> = [[full, resolve(cwd)]];
+	try {
+		checks.push([realpathSync(full), realpathSync(cwd)]);
+	} catch {}
+	for (const [path, root] of checks) {
+		const inside = relative(root, path);
+		if (inside === "" || inside.startsWith("..") || isAbsolute(inside)) {
+			return { refused: "outside the working directory" };
+		}
+		if (SECRET_BASENAME.test(basename(path))) return { refused: "looks like a secret file" };
+	}
+	return { full };
+}
+
+/** Read at most `maxBytes` of a file without loading the rest of it, or say why it could not be read. */
+function readBounded(path: string, maxBytes: number): { text: string; clipped: boolean } | { error: string } {
+	let size: number;
+	try {
+		const stats = statSync(path);
+		if (!stats.isFile()) return { error: "not a file" };
+		size = stats.size;
+	} catch (error) {
+		return { error: isRecord(error) && error.code === "ENOENT" ? "not found" : "unreadable" };
+	}
+	const length = Math.max(0, Math.min(size, maxBytes));
+	const buffer = Buffer.alloc(length);
+	try {
+		const fd = openSync(path, "r");
+		try {
+			const read = readSync(fd, buffer, 0, length, 0);
+			return { text: buffer.subarray(0, read).toString("utf-8"), clipped: size > read };
+		} finally {
+			closeSync(fd);
+		}
+	} catch {
+		return { error: "unreadable" };
+	}
+}
+
+/** One shell command through the same local operations the bash tool uses. */
+export async function runAskCommand(
+	command: string,
+	cwd: string,
+	signal: AbortSignal | undefined,
+): Promise<{ output: string; exitCode: number | null; clipped: boolean; failed: boolean }> {
+	const chunks: string[] = [];
+	let bytes = 0;
+	let clipped = false;
+	let failed = false;
+	let exitCode: number | null = null;
+	try {
+		const code = await createLocalBashOperations().exec(command, cwd, {
+			onData: (data) => {
+				if (clipped) return;
+				const text = data.toString("utf-8");
+				chunks.push(text);
+				bytes += Buffer.byteLength(text, "utf-8");
+				if (bytes >= MAX_ASK_COMMAND_BYTES) clipped = true;
+			},
+			signal,
+			timeout: ASK_COMMAND_TIMEOUT_SECONDS,
+		});
+		exitCode = code.exitCode;
+	} catch {
+		// A failed, timed-out, or cancelled command still reports what it printed.
+		failed = true;
+	}
+	return { output: chunks.join(""), exitCode, clipped, failed };
+}
+
+// ---------------------------------------------------------------------------
+// Answers
+// ---------------------------------------------------------------------------
+
+function formatValue(value: unknown): string {
+	if (typeof value === "number") return Number.isInteger(value) ? String(value) : value.toFixed(2);
+	if (typeof value === "string") return value;
+	return JSON.stringify(value);
+}
+
+/** A score answer as the agent reads it: the nearest level label, then the raw position. */
+export function formatScore(answer: Record<string, unknown>, levels: unknown): string | undefined {
+	const score = answer.score;
+	if (typeof score !== "number") return undefined;
+	const legend = isRecord(answer.legend) ? answer.legend : undefined;
+	const nearest = Math.round(score);
+	const label = legend?.[String(nearest)] ?? (Array.isArray(levels) ? levels[nearest] : undefined);
+	return typeof label === "string" ? `${label} (${formatValue(score)})` : formatValue(score);
+}
+
+/**
+ * Render answers for the agent: each value and its confidence, never the raw
+ * probability distribution, the file contents, or the command output.
+ */
+export function renderAskAnswers(input: {
+	questions: readonly AskJevQuestion[];
+	answers: Record<string, unknown>;
+	rejected: Record<string, JevAbstainReason>;
+	failure?: JevAbstainReason;
+	model: string;
+	elapsedMs: number;
+	refused: readonly string[];
+	notes: readonly string[];
+	/** How many paths the agent passed, and the directory they resolve against. */
+	pathsRequested?: number;
+	cwd?: string;
+}): string {
+	const lines: string[] = [];
+	let answered = 0;
+	for (const question of input.questions) {
+		const answer = input.answers[question.name];
+		if (!isRecord(answer)) {
+			lines.push(`- ${question.name}: no answer (${input.rejected[question.name] ?? input.failure ?? "missing"})`);
+			continue;
+		}
+		answered += 1;
+		// The type is already in the label, the legend is folded into the score, and raw
+		// distributions stay out of the agent's context.
+		const fields = Object.entries(answer)
+			.filter(([key]) => !["probabilities", "type", "legend"].includes(key))
+			.map(([key, value]) =>
+				key === "score" ? `score=${formatScore(answer, question.criteria)}` : `${key}=${formatValue(value)}`,
+			);
+		lines.push(`- ${question.name} (${question.type}): ${fields.length > 0 ? fields.join(", ") : "answered"}`);
+	}
+	const header = [`ask_jev: ${answered}/${input.questions.length} answered via ${input.model} in ${input.elapsedMs}ms`];
+	if (answered === 0 && input.failure) header.push(`Jev was unavailable or abstained: ${input.failure}.`);
+	// Missing material changes what the answers mean, so it leads rather than trails them.
+	const requested = input.pathsRequested ?? 0;
+	if (requested > 0 && input.refused.length >= requested) {
+		header.push(
+			`WARNING: Jev answered without any of the ${requested} files you passed (${input.refused.join("; ")}). ` +
+				`Paths resolve inside ${input.cwd ?? "the working directory"}; treat these answers as judged from your prose alone.`,
+		);
+	} else if (input.refused.length > 0) {
+		header.push(`Not sent to Jev: ${input.refused.join("; ")}.`);
+	}
+	const footer = [
+		"Only these answers are returned: the file contents and command output you supplied were not sent back to you.",
+		...(input.notes.length > 0 ? [`Truncated to fit the request budget: ${input.notes.join("; ")}.`] : []),
+	];
+	return [...header, ...lines, ...footer].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// jev_find: ripgrep gathers candidates, Jev judges each one
+// ---------------------------------------------------------------------------
+
+/** The file finder's registered name. */
+export const JEV_FIND_TOOL = "jev_find";
+/** ponytail: 16 nouls per request (the JevPDF batch size); raise once Jev is measured on larger blocks. */
+export const FIND_BATCH = 16;
+/** Three batches, sent in parallel, so a find costs one Jev round trip. */
+export const MAX_FIND_CANDIDATES = 48;
+const FIND_MATCH_LINES = 6;
+const FIND_DEFAULT_LIMIT = 8;
+const FIND_MIN_RELEVANCE = 0.5;
+/** Room each batch keeps for the questions and JSON scaffolding. */
+const FIND_QUESTION_RESERVE = 6 * 1024;
+
+export interface FindCandidate {
+	path: string;
+	/** Matched line numbers (pattern mode only). */
+	lines: number[];
+	/** What Jev reads: the matched lines, or the head of the file. */
+	snippet: string;
+}
+
+/** Run ripgrep with an argument list (no shell). Exit 1 is "no matches"; an overfull buffer keeps what arrived. */
+function runRg(bin: string, args: string[], cwd: string, signal: AbortSignal | undefined): Promise<string> {
+	return new Promise((done, fail) => {
+		execFile(
+			bin,
+			args,
+			{ cwd, signal, maxBuffer: 8 * 1024 * 1024, timeout: ASK_COMMAND_TIMEOUT_SECONDS * 1000 },
+			(error, stdout) => {
+				const code = error ? (error as { code?: unknown }).code : 0;
+				if (!error || code === 1 || code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") done(String(stdout));
+				else fail(error);
+			},
+		);
+	});
+}
+
+/** Filler words that would match nearly every file. */
+const FIND_STOP_WORDS = new Set(
+	"the and for with where what which when who how does did this that from into its are was can should would there file files code find implement implemented implements".split(" "),
+);
+
+/** Question words worth searching for: 3+ letters, not filler, at most eight. */
+function questionWords(question: string): string[] {
+	const words = question.toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
+	return [...new Set(words)].filter((word) => !FIND_STOP_WORDS.has(word)).slice(0, 8);
+}
+
+/** How much of each listed file is scanned for question words. */
+const FIND_SCAN_BYTES = 256 * 1024;
+const FIND_EXCERPT_LINES = 12;
+
+/**
+ * What Jev reads of a listed file: the lines holding the most distinct question words, in file
+ * order and numbered, or the head of the file when none match. A file's head is usually its
+ * doc comment, which rarely shows where the asked-about behavior lives.
+ */
+export function excerpt(text: string, words: readonly string[], maxBytes: number): { lines: number[]; snippet: string } {
+	const rows = text.split("\n");
+	const best = rows
+		.map((row, index) => {
+			const lower = row.toLowerCase();
+			return { index, count: words.filter((word) => lower.includes(word)).length };
+		})
+		.filter((hit) => hit.count > 0)
+		.sort((a, b) => b.count - a.count || a.index - b.index)
+		.slice(0, FIND_EXCERPT_LINES);
+	if (best.length === 0) return { lines: [], snippet: clip(text, maxBytes).text };
+	const inOrder = [...best].sort((a, b) => a.index - b.index);
+	const snippet = inOrder.map((hit) => `L${hit.index + 1}: ${rows[hit.index].trim().slice(0, 240)}`).join("\n");
+	// Pointers lead with the best-matching lines.
+	return { lines: best.map((hit) => hit.index + 1), snippet: clip(snippet, maxBytes).text };
+}
+
+/** Path parts (3+ letters) sharing a stem with a question word; orders a file listing before it is capped. */
+function pathOverlap(path: string, words: readonly string[]): number {
+	const parts = path.toLowerCase().match(/[a-z0-9]{3,}/g) ?? [];
+	return parts.filter((part) => words.some((word) => word.includes(part) || part.includes(word))).length;
+}
+
+/**
+ * Candidate files under `root`, most promising first. With `pattern`, the files ripgrep matches
+ * (most matches first) with their matched lines as the snippet; without it, every file ripgrep
+ * lists (question words in the path first) with the head of the file as the snippet. Respects
+ * .gitignore, and never offers a file `askPath` would refuse.
+ */
+export async function findCandidates(
+	options: { rg: string; cwd: string; root: string; question: string; pattern?: string; glob?: string; ignoreCase?: boolean },
+	snippetBytes: number,
+	signal: AbortSignal | undefined,
+): Promise<{ candidates: FindCandidate[]; total: number }> {
+	// Always name the root: with no path and a piped stdin, rg searches stdin and hangs.
+	// Paths come back as `./src/x.ts`, so they are normalized below.
+	const root = ["--", options.root];
+	const filters = [...(options.glob ? ["--glob", options.glob] : []), ...(options.ignoreCase ? ["-i"] : [])];
+	const allowed = (path: string) => "full" in askPath(path, options.cwd);
+	if (options.pattern) {
+		const out = await runRg(
+			options.rg,
+			["--null", "--line-number", "--no-heading", "--color=never", "--max-count", String(FIND_MATCH_LINES), "--max-columns", "240", ...filters, "-e", options.pattern, ...root],
+			options.cwd,
+			signal,
+		);
+		const byFile = new Map<string, { lines: number[]; text: string[] }>();
+		for (const row of out.split("\n")) {
+			const nul = row.indexOf("\0");
+			if (nul < 0) continue;
+			const path = normalize(row.slice(0, nul));
+			const match = /^(\d+):(.*)$/.exec(row.slice(nul + 1));
+			if (!match) continue;
+			const entry = byFile.get(path) ?? { lines: [], text: [] };
+			entry.lines.push(Number(match[1]));
+			entry.text.push(`L${match[1]}: ${match[2].trim()}`);
+			byFile.set(path, entry);
+		}
+		const files = [...byFile].filter(([path]) => allowed(path)).sort((a, b) => b[1].lines.length - a[1].lines.length);
+		return {
+			total: files.length,
+			candidates: files.slice(0, MAX_FIND_CANDIDATES).map(([path, entry]) => ({
+				path,
+				lines: entry.lines,
+				snippet: clip(entry.text.join("\n"), snippetBytes).text,
+			})),
+		};
+	}
+	const words = questionWords(options.question);
+	const out = await runRg(options.rg, ["--files", "--color=never", ...filters, ...root], options.cwd, signal);
+	const listed = out
+		.split("\n")
+		.filter((path) => path !== "")
+		.map((path) => normalize(path))
+		.filter(allowed);
+	const score = new Map(listed.map((path) => [path, pathOverlap(path, words)]));
+	if (listed.length > MAX_FIND_CANDIDATES && words.length > 0) {
+		// More files than Jev judges: a file scores once per distinct question word its content holds,
+		// one fixed-string ripgrep per word, in parallel.
+		const hits = await Promise.all(
+			words.map((word) =>
+				runRg(options.rg, ["-l", "-i", "-F", "--color=never", ...filters, "-e", word, ...root], options.cwd, signal),
+			),
+		);
+		for (const listing of hits) {
+			for (const raw of listing.split("\n")) {
+				const path = raw === "" ? "" : normalize(raw);
+				const current = score.get(path);
+				if (current !== undefined) score.set(path, current + 1);
+			}
+		}
+	}
+	const files = listed.map((path) => ({ path })).sort((a, b) => (score.get(b.path) ?? 0) - (score.get(a.path) ?? 0));
+	const candidates: FindCandidate[] = [];
+	for (const { path } of files.slice(0, MAX_FIND_CANDIDATES)) {
+		const file = readBounded(resolve(options.cwd, path), FIND_SCAN_BYTES);
+		if ("error" in file) continue;
+		candidates.push({ path, ...excerpt(file.text, words, snippetBytes) });
+	}
+	return { candidates, total: files.length };
+}
+
+/** One batch as a decisions request: the shared snippets as state, one noul per file. */
+export function buildFindPayload(question: string, batch: readonly FindCandidate[]): Record<string, unknown> {
+	return buildAskPayload(
+		batch.map((candidate, index) => ({
+			name: `f${index}`,
+			type: "noul" as const,
+			instructions: `Is the file "${candidate.path}" relevant to the request, judged by its excerpt in state.files?`,
+			criteria: {
+				true: "The excerpt shows this file implements, defines, configures, or directly answers the request.",
+				false: "The file only mentions related words, or is about something else.",
+			},
+		})),
+		{ request: question, files: Object.fromEntries(batch.map((candidate) => [candidate.path, candidate.snippet])) },
+	);
+}
+
+/**
+ * The batch's request, its snippets shrunk until the serialized request fits `maxBytes`: code
+ * grows under JSON escaping, so a byte budget per snippet alone does not guarantee a fit.
+ */
+export function fitFindPayload(question: string, batch: readonly FindCandidate[], maxBytes: number): Record<string, unknown> {
+	let limit = Math.max(0, ...batch.map((candidate) => Buffer.byteLength(candidate.snippet, "utf-8")));
+	for (;;) {
+		const payload = buildFindPayload(
+			question,
+			batch.map((candidate) => ({ ...candidate, snippet: clip(candidate.snippet, limit).text })),
+		);
+		if (limit < 64 || serializeJevRequest(payload, maxBytes) !== undefined) return payload;
+		limit = Math.floor(limit * 0.75);
+	}
+}
+
+/** Pointers only: path, matched lines, relevance. File contents never reach the agent. */
+export function renderFindResults(input: {
+	ranked: ReadonlyArray<FindCandidate & { relevance?: number }>;
+	total: number;
+	judged: number;
+	limit: number;
+	model: string;
+	elapsedMs: number;
+	failure?: string;
+}): string {
+	const pointer = (candidate: FindCandidate) =>
+		candidate.lines.length > 0 ? `${candidate.path}:${candidate.lines.slice(0, 4).join(",")}` : candidate.path;
+	if (input.total === 0) return "jev_find: no candidate files. Loosen `pattern`, `glob`, or `path`.";
+	const lines: string[] = [];
+	if (input.judged === 0) {
+		lines.push(
+			`jev_find: Jev did not judge (${input.failure ?? "missing"}); ${input.total} candidate file(s), unranked by relevance:`,
+			...input.ranked.slice(0, input.limit).map((candidate) => `- ${pointer(candidate)}`),
+		);
+	} else {
+		const strong = input.ranked.filter((candidate) => (candidate.relevance ?? 0) >= FIND_MIN_RELEVANCE);
+		lines.push(`jev_find: judged ${input.judged} of ${input.total} candidate file(s) via ${input.model} in ${input.elapsedMs}ms`);
+		const shown = strong.length > 0 ? strong.slice(0, input.limit) : input.ranked.slice(0, 3);
+		if (strong.length === 0) lines.push("No file is a confident match; the closest were:");
+		for (const candidate of shown) {
+			lines.push(`- ${pointer(candidate)} (${candidate.relevance === undefined ? "not judged" : candidate.relevance.toFixed(2)})`);
+		}
+		if (strong.length > shown.length) lines.push(`${strong.length - shown.length} more relevant file(s) past the limit.`);
+	}
+	if (input.total > MAX_FIND_CANDIDATES) {
+		lines.push(`${input.total - MAX_FIND_CANDIDATES} candidate(s) were not judged; narrow with \`pattern\`, \`glob\`, or \`path\`.`);
+	}
+	lines.push("Only pointers are returned; read the files you need.");
+	return lines.join("\n");
+}
+
+const JevFindParams = Type.Object({
+	question: Type.String({ description: "What you are looking for, in plain words (e.g. 'where is the retry backoff configured')." }),
+	pattern: Type.Optional(
+		Type.String({ description: "ripgrep regex to narrow candidates to files that match; omit to judge every listed file." }),
+	),
+	glob: Type.Optional(Type.String({ description: "File glob filter, e.g. '*.ts' or 'src/**/*.md'." })),
+	path: Type.Optional(Type.String({ description: "Directory to search, inside the working directory (default: '.')." })),
+	ignoreCase: Type.Optional(Type.Boolean({ description: "Case-insensitive pattern." })),
+	limit: Type.Optional(Type.Number({ description: `Most results to return (default ${FIND_DEFAULT_LIMIT}).` })),
+});
+
+// ---------------------------------------------------------------------------
+// Tool
+// ---------------------------------------------------------------------------
+
+const QuestionSpec = Type.Object({
+	type: StringEnum(ASK_JEV_QUESTION_TYPES, {
+		description: "choice: pick one option. score: place the state on a rubric. noul: probability a statement holds.",
+	}),
+	instructions: Type.String({ description: "The question, stated in one sentence." }),
+	criteria: Type.Optional(
+		Type.Unknown({
+			description:
+				'choice: {"option": "what the option means"} (at least two). score: an ordered array of level labels. noul: {"true": "...", "false": "..."}.',
+		}),
+	),
+	focus: Type.Optional(Type.String({ description: "Extra judging guidance for this question." })),
+});
+
+const AskJevParams = Type.Object({
+	state: Type.Optional(Type.String({ description: "Your own prose: the situation and what you are deciding." })),
+	paths: Type.Optional(
+		Type.Array(Type.String(), {
+			description: `Code to include as state, read-only (max ${MAX_ASK_PATHS}). Relative paths resolve against the working directory; paths outside it are refused.`,
+		}),
+	),
+	command: Type.Optional(Type.String({ description: "One shell command whose output becomes state." })),
+	questions: Type.Record(Type.String(), QuestionSpec, { description: "Question name -> spec." }),
+});
+
+export default function jevAskToolExtension(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: ASK_JEV_TOOL,
+		label: "Ask Jev",
+		description: [
+			"Ask Jev (a typed decisions model, not a chat model) a block of questions about a state you assemble here:",
+			"your own prose in `state`, code read from `paths`, and the output of one shell `command`. Code makes one",
+			"bounded call and returns answers only — the file contents and command output are never sent back to you.",
+			"Anything you put in the state is sent to Jev, so pass only code you are willing to share.",
+			'`questions` is an object keyed by question name; each value is {"type": "choice" | "score" | "noul",',
+			'"instructions": <the question>, "criteria": <see below>, "focus"?: <extra guidance>}.',
+			'choice criteria: {"option": "what the option means"}; score criteria: an ordered array of level labels;',
+			'noul criteria: {"true": "...", "false": "..."} (optional for noul).',
+			"Each answer returns the chosen value, score, or probability plus a confidence; raw probability",
+			"distributions are omitted.",
+			"Use it to triage a failure before touching anything (run the failing command, ask what kind of failure it is),",
+			"judge a diff before shipping (a risk score and a needs-review flag), classify a request before planning, or",
+			"find which of several files matters without reading them into your own context.",
+			`Bounds: ${MAX_ASK_QUESTIONS} questions, ${MAX_ASK_PATHS} paths per call; each file is clipped to about ${MAX_ASK_FILE_BYTES / 1024} KB and marked when clipped.`,
+		].join(" "),
+		promptSnippet: "Ask Jev a typed question about state you assemble from prose, files, or one command",
+		promptGuidelines: [
+			"Use ask_jev whenever a judgment would otherwise be a guess — what kind of failure this is, how risky a diff is, what a request is really asking for. It returns typed answers with confidences for a fraction of a cent, so it validates assumptions before they cost a wrong edit.",
+			"Prefer ask_jev over reading files when you only need a verdict about them (which of these files handles X, does this code already do Y, is this test output a code bug or a flaky test): pass them as `paths` or the command as `command`, and only the answer enters your context. Read a file yourself when you need its exact text, such as before editing it.",
+		],
+		discovery: {
+			summary: "Ask Jev one block of typed choice/score/noul questions over prose, code, and one command's output",
+			aliases: ["jev", "triage", "classify", "judge", "score"],
+			category: "Decisions",
+		},
+		parameters: AskJevParams,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx: ExtensionContext) {
+			const text = (value: string) => ({ content: [{ type: "text" as const, text: value }], details: {} });
+
+			const config = readJevAdvisoryConfig(getSettingsPath());
+			const route = config.routes.ask;
+			if (!route.enabled) {
+				return text(
+					`ask_jev is disabled (jevAdvisory.routes.ask.enabled is false in ${getSettingsPath()}). Remove that setting or set it to true.`,
+				);
+			}
+
+			const parsed = parseAskQuestions(params.questions as Record<string, unknown> | undefined);
+			if (parsed.error !== undefined) {
+				return text(`ask_jev needs a usable question block: ${parsed.error}`);
+			}
+			const questions = parsed.questions;
+
+			// Reading files and running the command exist only to feed Jev: without a reachable
+			// Jev, do neither (an `npm test` would otherwise run in full and be thrown away).
+			const connection = jevConnection(config, route);
+			const unreachable = await jevUnavailable(ctx, connection);
+			if (unreachable) {
+				if (ctx.hasUI) warnJevUnavailableOnce(ctx.ui, config.provider);
+				emitJevTelemetry(pi.events, "decision", {
+					route: "ask",
+					outcome: "fallback",
+					candidates: questions.length,
+					confidence: confidenceBucket(undefined),
+					elapsedMs: 0,
+					reason: unreachable,
+				});
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `${renderAskAnswers({
+								questions,
+								answers: {},
+								rejected: {},
+								failure: unreachable,
+								model: config.model,
+								elapsedMs: 0,
+								refused: [],
+								notes: [],
+							})}\nNothing was read, run, or sent. Decide without Jev: read the files or run the command yourself.`,
+						},
+					],
+					details: { answered: 0, questions: questions.length, model: config.model, elapsedMs: 0, failure: unreachable },
+				};
+			}
+
+			const questionBytes = Buffer.byteLength(
+				JSON.stringify(buildAskPayload(questions, {}).questions),
+				"utf-8",
+			);
+			const requested = (params.paths ?? []).slice(0, MAX_ASK_PATHS);
+			const budget = askPartBudget(route.payloadBytes, requested.length, questionBytes);
+
+			const refused: string[] = [];
+			const notes: string[] = [];
+
+			const prose = clip((params.state ?? "").trim(), budget.stateChars);
+			if (prose.clipped) notes.push("state");
+
+			const files: Record<string, string> = {};
+			for (const raw of requested) {
+				const path = askPath(raw, ctx.cwd);
+				if ("refused" in path) {
+					refused.push(`${raw} (${path.refused})`);
+					continue;
+				}
+				const file = readBounded(path.full, Math.max(0, budget.fileBytes - Buffer.byteLength(TRUNCATION_MARKER, "utf-8")));
+				if ("error" in file) {
+					refused.push(`${raw} (${file.error})`);
+					continue;
+				}
+				if (file.clipped) notes.push(raw);
+				files[relative(ctx.cwd, path.full)] = file.clipped ? `${file.text}${TRUNCATION_MARKER}` : file.text;
+			}
+
+			let command: Record<string, unknown> | undefined;
+			if (params.command?.trim()) {
+				const result = await runAskCommand(params.command.trim(), ctx.cwd, signal);
+				const output = clip(result.output, budget.commandBytes);
+				if (output.clipped || result.clipped) notes.push("command output");
+				command = {
+					command: params.command.trim(),
+					output: output.text,
+					exitCode: result.exitCode,
+					...(result.failed ? { failed: true } : {}),
+				};
+			}
+
+			const payload = buildAskPayload(questions, {
+				...(prose.text ? { request: prose.text } : {}),
+				...(Object.keys(files).length > 0 ? { files } : {}),
+				...(command ? { command } : {}),
+			});
+			if (serializeJevRequest(payload, route.payloadBytes) === undefined) {
+				return text("ask_jev could not fit this request in its budget; pass fewer paths or a shorter command.");
+			}
+
+			const result = await askJevAnswers(ctx, connection, {
+				payload,
+				maxBytes: route.payloadBytes,
+			});
+			const answers = result.answers ?? {};
+			const rejected: Record<string, JevAbstainReason> = {};
+			let answered = 0;
+			let topConfidence: number | undefined;
+			for (const question of questions) {
+				const answer = answers[question.name];
+				if (!isRecord(answer)) {
+					rejected[question.name] = result.failure ?? "missing";
+					continue;
+				}
+				answered += 1;
+				if (typeof answer.confidence === "number") {
+					topConfidence = topConfidence === undefined ? answer.confidence : Math.max(topConfidence, answer.confidence);
+				}
+			}
+
+			// Content-free: no state, answers, or criteria travel, only shape and outcome.
+			emitJevTelemetry(pi.events, "decision", {
+				route: "ask",
+				outcome: answered > 0 ? "jev" : "fallback",
+				candidates: questions.length,
+				confidence: confidenceBucket(topConfidence),
+				elapsedMs: result.elapsedMs,
+				...(answered > 0 ? {} : { reason: result.failure ?? "missing" }),
+			});
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: renderAskAnswers({
+							questions,
+							answers,
+							rejected,
+							failure: result.failure,
+							model: config.model,
+							elapsedMs: result.elapsedMs,
+							refused,
+							notes,
+							pathsRequested: requested.length,
+							cwd: ctx.cwd,
+						}),
+					},
+				],
+				// Deliberately shape only: tool details are persisted in the session.
+				details: {
+					answered,
+					questions: questions.length,
+					model: config.model,
+					elapsedMs: result.elapsedMs,
+					...(result.failure ? { failure: result.failure } : {}),
+				},
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: JEV_FIND_TOOL,
+		label: "Jev Find",
+		description: [
+			"Find which files answer a question without reading them: ripgrep gathers candidate files (those matching",
+			"`pattern`, or every file under `path` filtered by `glob`), and Jev judges each file's excerpt against",
+			"`question` in one parallel round trip. Returns ranked `path:lines (relevance)` pointers, never contents.",
+			`Judges up to ${MAX_FIND_CANDIDATES} files per call; respects .gitignore; secret-named files are never sent.`,
+		].join(" "),
+		promptSnippet: "Find the files that answer a question: ripgrep candidates ranked by Jev, pointers only",
+		promptGuidelines: [
+			"When you look for code by what it does rather than by an exact identifier you already know, call jev_find first — before grep, find, ls, or reading candidate files. One call ranks up to 48 files in about a second and returns file:line pointers; then read only the top ones. Pass `question` in plain words; add `pattern` when you know a likely identifier, `glob`/`path` to scope it.",
+			"Use grep for an exact string or identifier you already know; use jev_find when you would otherwise grep several guesses or read files to see which one is relevant.",
+		],
+		discovery: {
+			summary: "Semantic file finder: ripgrep candidates ranked by Jev relevance",
+			aliases: ["jevgrep", "find", "search", "locate"],
+			category: "Decisions",
+		},
+		parameters: JevFindParams,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx: ExtensionContext) {
+			const text = (value: string, details: Record<string, unknown> = {}) => ({
+				content: [{ type: "text" as const, text: value }],
+				details,
+			});
+			const config = readJevAdvisoryConfig(getSettingsPath());
+			const route = config.routes.ask;
+			if (!route.enabled) {
+				return text(`jev_find is disabled (jevAdvisory.routes.ask.enabled is false in ${getSettingsPath()}).`);
+			}
+			const question = params.question?.trim() ?? "";
+			if (question === "") return text("jev_find needs a non-empty `question`.");
+
+			const rootArg = params.path?.trim() || ".";
+			const rootFull = resolve(ctx.cwd, rootArg);
+			const inside = relative(resolve(ctx.cwd), rootFull);
+			if (inside.startsWith("..") || isAbsolute(inside)) {
+				return text(`jev_find: ${rootArg} is outside the working directory.`);
+			}
+			const rg = await ensureTool("rg");
+			if (!rg) return text("jev_find needs ripgrep (rg), which is not available; use grep instead.");
+
+			const snippetBytes = Math.max(256, Math.floor((route.payloadBytes - FIND_QUESTION_RESERVE) / FIND_BATCH));
+			let found: { candidates: FindCandidate[]; total: number };
+			try {
+				found = await findCandidates(
+					{
+						rg,
+						cwd: ctx.cwd,
+						root: inside === "" ? "." : inside,
+						question,
+						pattern: params.pattern || undefined,
+						glob: params.glob || undefined,
+						ignoreCase: params.ignoreCase,
+					},
+					snippetBytes,
+					signal,
+				);
+			} catch (error) {
+				return text(`jev_find: ripgrep failed (${error instanceof Error ? error.message.split("\n")[0] : String(error)}).`);
+			}
+			const limit = Math.max(1, Math.floor(params.limit ?? FIND_DEFAULT_LIMIT));
+			const { candidates, total } = found;
+			if (candidates.length === 0) {
+				return text(renderFindResults({ ranked: [], total: 0, judged: 0, limit, model: config.model, elapsedMs: 0 }));
+			}
+
+			// Without Jev the candidates are still worth returning: the call is never wasted.
+			const connection = jevConnection(config, route);
+			const unreachable = await jevUnavailable(ctx, connection);
+			const batches: FindCandidate[][] = [];
+			for (let start = 0; start < candidates.length; start += FIND_BATCH) {
+				batches.push(candidates.slice(start, start + FIND_BATCH));
+			}
+			const started = Date.now();
+			const results = unreachable
+				? []
+				: await Promise.all(
+						batches.map((batch) =>
+							askJevAnswers(ctx, connection, {
+								payload: fitFindPayload(question, batch, route.payloadBytes),
+								maxBytes: route.payloadBytes,
+							}),
+						),
+					);
+			const elapsedMs = Date.now() - started;
+
+			const scored: Array<FindCandidate & { relevance?: number }> = [];
+			let judged = 0;
+			batches.forEach((batch, b) => {
+				const answers = results[b]?.answers ?? {};
+				batch.forEach((candidate, i) => {
+					const answer = answers[`f${i}`];
+					const relevance = isRecord(answer) && typeof answer.noul === "number" ? answer.noul : undefined;
+					if (relevance !== undefined) judged += 1;
+					scored.push({ ...candidate, ...(relevance === undefined ? {} : { relevance }) });
+				});
+			});
+			// Judged files by relevance; unjudged ones keep ripgrep's order behind them.
+			const ranked = judged > 0 ? [...scored].sort((a, b) => (b.relevance ?? -1) - (a.relevance ?? -1)) : scored;
+			const failure = unreachable ?? results.find((result) => result.failure)?.failure;
+
+			emitJevTelemetry(pi.events, "decision", {
+				route: "find",
+				outcome: judged > 0 ? "jev" : "fallback",
+				candidates: candidates.length,
+				confidence: confidenceBucket(ranked[0]?.relevance),
+				elapsedMs,
+				...(judged > 0 ? {} : { reason: failure ?? "missing" }),
+			});
+			return text(
+				renderFindResults({ ranked, total, judged, limit, model: config.model, elapsedMs, failure }),
+				// Shape only, like ask_jev: details persist in the session.
+				{ candidates: candidates.length, total, judged, elapsedMs, ...(failure ? { failure } : {}) },
+			);
+		},
+	});
+
+	// Offer the tools only while Jev can answer: a tool that always fails costs the agent a turn
+	// every time it reaches for it. Checked before every run, so `/tokenin add` brings them back
+	// without a reload. Silent on purpose: the one warning comes from whichever Jev path first
+	// needs the missing credential, not from every session of a user without a subscription.
+	// Only a removal made here is ever undone, so a loadout the user trimmed stays trimmed.
+	const jevTools = [ASK_JEV_TOOL, JEV_FIND_TOOL];
+	const hidden = new Set<string>();
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const config = readJevAdvisoryConfig(getSettingsPath());
+		const route = config.routes.ask;
+		const offline = !route.enabled || (await jevUnavailable(ctx, jevConnection(config, route))) !== undefined;
+		const active = pi.getActiveTools();
+		if (offline) {
+			const dropping = jevTools.filter((name) => active.includes(name));
+			if (dropping.length > 0) {
+				pi.setActiveTools(active.filter((name) => !dropping.includes(name)));
+				for (const name of dropping) hidden.add(name);
+			}
+		} else if (hidden.size > 0) {
+			const restoring = [...hidden].filter((name) => !active.includes(name));
+			if (restoring.length > 0) pi.setActiveTools([...active, ...restoring]);
+			hidden.clear();
+		}
+		return undefined;
+	});
+}