@selesai/code 0.13.33 → 0.13.34

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

@@ -0,0 +1,587 @@
+/**
+ * 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 { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { basename, isAbsolute, relative, resolve } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import {
+	createLocalBashOperations,
+	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");
+}
+
+// ---------------------------------------------------------------------------
+// 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 } : {}),
+				},
+			};
+		},
+	});
+
+	// Offer the tool 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 it 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.
+	let hidden = false;
+	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) {
+			if (active.includes(ASK_JEV_TOOL)) {
+				pi.setActiveTools(active.filter((name) => name !== ASK_JEV_TOOL));
+				hidden = true;
+			}
+		} else if (hidden) {
+			if (!active.includes(ASK_JEV_TOOL)) pi.setActiveTools([...active, ASK_JEV_TOOL]);
+			hidden = false;
+		}
+		return undefined;
+	});
+}

package/dist/extensions/package.json

@@ -19,6 +19,7 @@
 			"./herdr-agent-state.ts",
 			"./inline-skills.ts",
 			"./jev-advisory-routing.ts",
+			"./jev-ask-tool.ts",
 			"./rtk.ts",
 			"./tokenin-onboarding.ts",
 			"./pi-graft",

package/dist/extensions/pi-hermes-memory/README.md

@@ -483,45 +483,19 @@ Move behavior:
 
 ## Configuration
 
-Create `~/.selesai/agent/hermes-memory-config.json`:
+Set extension options under `hermesMemory` in `~/.selesai/agent/settings.json`:
 
 ```json
 {
-  "memoryMode": "policy-only",
-  "memoryPolicyStyle": "full",
-  "memoryCharLimit": 5000,
-  "userCharLimit": 5000,
-  "projectCharLimit": 5000,
-  "memoryDir": "~/.selesai/agent/pi-hermes-memory",
-  "projectsMemoryDir": "projects-memory",
-  "sessionSearch": { "variant": "legacy" },
-  "sessionRetentionDays": 0,
-  "quickCheckOnOpen": true,
-  "llmModelOverride": "openrouter/deepseek/deepseek-v4-flash",
-  "llmThinkingOverride": "off",
-  "childExtensionPaths": ["~/.selesai/agent/git/github.com/example/custom-provider-extension/index.ts"],
-  "nudgeInterval": 10,
-  "nudgeToolCalls": 15,
-  "reviewRecentMessages": 0,
-  "reviewEnabled": true,
-  "reviewTransport": "direct",
-  "memoryOverflowStrategy": "auto-consolidate",
-  "autoConsolidate": true,
-  "correctionDetection": true,
-  "failureInjectionEnabled": true,
-  "failureInjectionMaxAgeDays": 7,
-  "failureInjectionMaxEntries": 5,
-  "consolidationTimeoutMs": 180000,
-  "overflowGraceMs": 180000,
-  "autoConsolidationWarnOnFailure": true,
-  "flushOnCompact": true,
-  "flushOnShutdown": true,
-  "flushMinTurns": 6,
-  "flushRecentMessages": 0,
-  "standingInstructionsEnabled": true
+  "hermesMemory": {
+    "llmThinkingOverride": "off",
+    "consolidationTimeoutMs": 300000
+  }
 }
 ```
 
+The extension reads these options at startup. Values in `settings.json` override the legacy `hermes-memory-config.json`, which remains a fallback for existing installations. All settings below are keys inside `hermesMemory`. `llmModelOverride` is optional and uses `provider/model` format (for example, `tokenin/deepseek-v4.1-flash` if your account has access); leave it unset to use the active model.
+
 | Setting | Default | Description |
 |---|---|---|
 | `memoryMode` | `policy-only` | Prompt behavior: `policy-only` injects only memory policy; `legacy-inject` restores full memory prompt injection |
@@ -536,7 +510,7 @@ Create `~/.selesai/agent/hermes-memory-config.json`:
 | `sessionSearch` | `{ "variant": "legacy" }` | Session search implementation: `legacy` keeps the existing SQLite/FTS snippet search; `anchors` uses the opt-in Markdown request surface and returns compact JSONL line-range anchors from `~/.selesai/agent/sessions/` |
 | `sessionRetentionDays` | `0` | Opt-in SQLite session retention, in days. `0` (default) disables pruning entirely and keeps the legacy count-only backfill preflight. When positive, sessions whose JSONL source file was last modified longer ago than the window are pruned from SQLite at startup — **rows only; the JSONL files in `~/.selesai/agent/sessions/` are never deleted** — and both the deferred backfill and `/memory-index-sessions` skip files outside the window, so pruned sessions stay pruned instead of being re-indexed |
 | `quickCheckOnOpen` | `true` | Run a full SQLite integrity check asynchronously after opening the database; set to `false` to skip the startup scan (operation-time recovery remains enabled) |
-| `llmModelOverride` | unset | Optional model override for background review (direct and subprocess), correction save, session flush, and consolidation |
+| `llmModelOverride` | unset | Optional `provider/model` override for background review (direct and subprocess), correction save, session flush, and consolidation; unset uses the active model |
 | `llmThinkingOverride` | unset | Optional thinking override for those LLM calls; valid values are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If `llmModelOverride` is set and this is omitted, review/child calls default to `off` |
 | `childExtensionPaths` | unset | Trusted provider/auth extension sources explicitly allowed in isolated child Pi processes. Values are passed to Pi's standard `-e` resolver, so absolute paths, `~/...`, paths relative to the child working directory, and `git:`/`npm:` package sources are supported. Sibling packages matching the `*-oauth-adapter`/`*-auth-adapter` naming convention (including scoped packages, via their `package.json` `pi.extensions` manifest) are detected automatically. This setting is only needed for custom providers or adapters that are not detected. In-process direct transport (the default for review/flush/correction/consolidation) doesn't need it, since it reads whatever provider auth is already registered. |
 | `nudgeInterval` | `10` | Turns between auto-reviews |
@@ -546,7 +520,7 @@ Create `~/.selesai/agent/hermes-memory-config.json`:
 | `reviewTransport` | `direct` | LLM transport for background review, session flush, correction save, and manual consolidation: `direct` uses in-process `completeSimple()` with subprocess fallback; `subprocess` forces legacy `pi -p` only |
 | `memoryOverflowStrategy` | `auto-consolidate` | Legacy-inject behavior when a Markdown memory file reaches its character limit: `auto-consolidate` runs the existing consolidation flow; `reject` returns an error; `fifo-evict` rotates older entries in file order until the new entry fits |
 | `autoConsolidate` | `true` | Legacy alias for `memoryOverflowStrategy` when `memoryOverflowStrategy` is not set (`true` = `auto-consolidate`, `false` = `reject`) |
-| `consolidationTimeoutMs` | `180000` | Maximum time in milliseconds for a consolidation run (auto and `/memory-consolidate` alike). Configured values are used verbatim; a consolidation pays child-process boot plus a full LLM turn, so values below the default are frequently killed mid-run and log a warning at startup |
+| `consolidationTimeoutMs` | `300000` | Maximum time in milliseconds for a consolidation run (auto and `/memory-consolidate` alike). Configured values are used verbatim; a consolidation pays child-process boot plus a full LLM turn, so values below the default are frequently killed mid-run and log a warning at startup |
 | `overflowGraceMs` | `180000` | Wall-clock grace period after a memory overflow before automatic consolidation is retried; this gives the active agent time to consolidate manually. Set to `0` to disable the grace period |
 | `autoConsolidationWarnOnFailure` | `true` | Log failed automatic consolidation attempts to the session console. Set to `false` to suppress only this warning; the memory tool result still reports the failure reason |
 | `correctionDetection` | `true` | Detect user corrections and save immediately |
@@ -602,7 +576,8 @@ The deferred backfill, live-index, and integrity-check spans may appear after st
 │   │           └── SKILL.md
 │   └── another-project/
 │       └── MEMORY.md
-├── hermes-memory-config.json
+├── settings.json          ← Global settings; extension options are under hermesMemory
+├── hermes-memory-config.json ← Legacy fallback for older extension builds
 └── ...
 ```