@juicesharp/rpiv-advisor 1.15.0 → 1.16.0

package/README.md

@@ -14,7 +14,7 @@ Let the model ask a stronger model for a second opinion before it acts. `rpiv-ad
 
 ## Features
 
-- **Reviewer model selector** - `/advisor` opens a picker over any model in Pi's registry, plus a reasoning-effort picker for reasoning-capable models.
+- **Reviewer model selector** - `/advisor` opens a picker over any model in Pi's registry, plus a reasoning-effort picker for reasoning-capable models. Start typing to fuzzy-filter the list by model name or `provider:id`.
 - **Persisted across sessions** - selection saved at `~/.config/rpiv-advisor/advisor.json` (chmod 0600).
 - **Off by default** - the `advisor` tool is excluded until you pick a model; choose "No advisor" to disable.
 - **Per-executor blocklist** - list executor models in `disabledForModels` (in `advisor.json`) to strip the `advisor` tool when those models drive the session. Entries can be plain strings (block at any effort) or `{ "model": "<provider:id>", "minEffort": "<level>" }` to block only when the executor's effort meets or exceeds the threshold. Available levels, lowest to highest: `minimal`, `low`, `medium`, `high`, `xhigh`.

package/advisor/command.ts

@@ -0,0 +1,146 @@
+/**
+ * command — the /advisor slash command. Reads top-down: interactive guard →
+ * model picker (buildModelItems) → no-advisor branch (applyDisable) → model
+ * lookup → effort picker (buildEffortItems) → enable (applyEnable). The apply
+ * helpers persist before mutating in-memory state (review I2).
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { getSupportedThinkingLevels, type ThinkingLevel } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SelectItem } from "@earendil-works/pi-tui";
+import { showAdvisorPicker, showEffortPicker } from "../advisor-ui.js";
+import { modelKey, saveAdvisorConfig } from "./config.js";
+import { reconcileAdvisorTool } from "./handlers.js";
+import {
+	ADVISOR_TOOL_NAME,
+	BASE_EFFORT_LEVELS,
+	CHECKMARK,
+	DEFAULT_EFFORT,
+	errSelectionNotFound,
+	MSG_ADVISOR_DISABLED,
+	MSG_PERSIST_FAILED,
+	MSG_REQUIRES_INTERACTIVE,
+	msgAdvisorEnabled,
+	msgAdvisorEnabledInactive,
+	NO_ADVISOR_VALUE,
+	OFF_VALUE,
+	RECOMMENDED_EFFORT_SUFFIX,
+	XHIGH_EFFORT_LEVEL,
+} from "./messages.js";
+import { isExecutorBlocked } from "./policy.js";
+import { getAdvisorEffort, getAdvisorModel, setAdvisorEffort, setAdvisorModel } from "./state.js";
+
+function buildModelItems(availableModels: Model<Api>[], currentKey: string | undefined): SelectItem[] {
+	const items: SelectItem[] = availableModels.map((m) => {
+		const key = modelKey(m);
+		const check = key === currentKey ? CHECKMARK : "";
+		return { value: key, label: `${m.name}  (${m.provider})${check}` };
+	});
+	items.push({
+		value: NO_ADVISOR_VALUE,
+		label: currentKey === undefined ? `No advisor${CHECKMARK}` : "No advisor",
+	});
+	return items;
+}
+
+function buildEffortItems(picked: Model<Api>): SelectItem[] {
+	const levels = getSupportedThinkingLevels(picked).includes("xhigh")
+		? [...BASE_EFFORT_LEVELS, XHIGH_EFFORT_LEVEL]
+		: BASE_EFFORT_LEVELS;
+	return [
+		{ value: OFF_VALUE, label: "off" },
+		...levels.map((level) => ({
+			value: level,
+			label: level === DEFAULT_EFFORT ? `${level}${RECOMMENDED_EFFORT_SUFFIX}` : level,
+		})),
+	];
+}
+
+// Disable path — persist BEFORE mutating in-memory state so a save failure
+// can't strand "model=undefined + tool still registered" (review I2). The strip
+// is unconditional-on-presence (no advisor at all), so it stays inline rather
+// than routing through reconcileAdvisorTool's blocked-conditional path.
+function applyDisable(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	if (!saveAdvisorConfig(undefined, undefined)) {
+		ctx.ui.notify(MSG_PERSIST_FAILED, "error");
+		return;
+	}
+	setAdvisorModel(undefined);
+	setAdvisorEffort(undefined);
+	const active = pi.getActiveTools();
+	if (active.includes(ADVISOR_TOOL_NAME)) {
+		pi.setActiveTools(active.filter((n) => n !== ADVISOR_TOOL_NAME));
+	}
+	ctx.ui.notify(MSG_ADVISOR_DISABLED, "info");
+}
+
+// Enable path — persist first (review I2), set in-memory state, activate via
+// reconcileAdvisorTool (which re-reads the active-tool list post-effort-picker-
+// await), and notify. Silent reconcile — the enable/inactive notify is the
+// single trailing notify call here.
+function applyEnable(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	picked: Model<Api>,
+	effort: ThinkingLevel | undefined,
+): void {
+	if (!saveAdvisorConfig(modelKey(picked), effort)) {
+		ctx.ui.notify(MSG_PERSIST_FAILED, "error");
+		return;
+	}
+	setAdvisorEffort(effort);
+	setAdvisorModel(picked);
+
+	const blocked = isExecutorBlocked(ctx, pi.getThinkingLevel());
+	reconcileAdvisorTool(pi, ctx, { blocked });
+	ctx.ui.notify(
+		blocked ? msgAdvisorEnabledInactive(modelKey(picked), effort) : msgAdvisorEnabled(modelKey(picked), effort),
+		"info",
+	);
+}
+
+export function registerAdvisorCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("advisor", {
+		description: "Configure the advisor model for the advisor-strategy pattern",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(MSG_REQUIRES_INTERACTIVE, "error");
+				return;
+			}
+
+			const availableModels = ctx.modelRegistry.getAvailable();
+			const current = getAdvisorModel();
+			const currentKey = current ? modelKey(current) : undefined;
+
+			const choice = await showAdvisorPicker(ctx, buildModelItems(availableModels, currentKey));
+			if (!choice) return;
+
+			if (choice === NO_ADVISOR_VALUE) {
+				applyDisable(pi, ctx);
+				return;
+			}
+
+			const picked = availableModels.find((m) => modelKey(m) === choice);
+			if (!picked) {
+				ctx.ui.notify(errSelectionNotFound(choice), "error");
+				return;
+			}
+
+			// Effort picker — only for reasoning-capable models
+			let effortChoice: ThinkingLevel | undefined;
+			if (picked.reasoning) {
+				const effortResult = await showEffortPicker(
+					ctx,
+					buildEffortItems(picked),
+					getAdvisorEffort(),
+					DEFAULT_EFFORT,
+				);
+				if (!effortResult) return;
+				effortChoice = effortResult === OFF_VALUE ? undefined : (effortResult as ThinkingLevel);
+			}
+
+			applyEnable(pi, ctx, picked, effortChoice);
+		},
+	});
+}

package/advisor/config.ts

@@ -0,0 +1,60 @@
+/**
+ * config — persisted advisor config (~/.config/rpiv-advisor/advisor.json) and
+ * the provider:id key codec. Owns the AdvisorConfig shape, load/validate/save,
+ * and the modelKey (join) / parseModelKey (split) inverse pair (L4-04).
+ */
+
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
+import type { GuidanceFields } from "@juicesharp/rpiv-config";
+import { configPath, loadJsonConfig, saveJsonConfig } from "@juicesharp/rpiv-config";
+import { EFFORT_ORDINAL } from "./messages.js";
+
+const ADVISOR_CONFIG_PATH = configPath("rpiv-advisor", "advisor.json");
+
+export type DisabledForModelsEntry = string | { model: string; minEffort?: ThinkingLevel };
+
+interface AdvisorConfig {
+	modelKey?: string;
+	effort?: ThinkingLevel;
+	guidance?: GuidanceFields;
+	disabledForModels?: DisabledForModelsEntry[];
+}
+
+export function loadAdvisorConfig(): AdvisorConfig {
+	return loadJsonConfig<AdvisorConfig>(ADVISOR_CONFIG_PATH);
+}
+
+export function validateDisabledForModels(value: unknown): DisabledForModelsEntry[] {
+	if (!Array.isArray(value)) return [];
+	return value.filter((entry): entry is DisabledForModelsEntry => {
+		if (typeof entry === "string") return entry.length > 0;
+		if (typeof entry !== "object" || entry === null) return false;
+		const obj = entry as Record<string, unknown>;
+		if (typeof obj.model !== "string" || obj.model.length === 0) return false;
+		if (obj.minEffort !== undefined && !EFFORT_ORDINAL.includes(obj.minEffort as ThinkingLevel)) return false;
+		return true;
+	});
+}
+
+export function saveAdvisorConfig(key: string | undefined, effort: ThinkingLevel | undefined): boolean {
+	const existing = loadAdvisorConfig();
+	const config: AdvisorConfig = { ...existing };
+	// Delete (rather than omit) to clear fields that may exist in the spread
+	// from a prior read. JSON.parse always produces configurable properties,
+	// so delete is safe in strict mode.
+	if (key) config.modelKey = key;
+	else delete config.modelKey;
+	if (effort) config.effort = effort;
+	else delete config.effort;
+	return saveJsonConfig(ADVISOR_CONFIG_PATH, config);
+}
+
+export function parseModelKey(key: string): { provider: string; modelId: string } | undefined {
+	const idx = key.indexOf(":");
+	if (idx < 1) return undefined;
+	return { provider: key.slice(0, idx), modelId: key.slice(idx + 1) };
+}
+
+export function modelKey(m: { provider: string; id: string }): string {
+	return `${m.provider}:${m.id}`;
+}

package/advisor/context.ts

@@ -0,0 +1,40 @@
+/**
+ * context — branch-message massaging for the advisor side-call. Strips the
+ * executor's in-flight advisor() toolCall from the tail (orphan toolCalls are
+ * rejected by providers) and guarantees a user-role tail (some providers reject
+ * an assistant-prefill tail).
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import { ADVISOR_TOOL_NAME, MSG_ADVISOR_NUDGE } from "./messages.js";
+
+// Strip the executor's in-flight advisor() toolCall from the tail assistant
+// message. That call is what invoked *us* — there is no matching toolResult
+// yet, and providers (Anthropic, GLM/zai, OpenAI) reject payloads with orphan
+// toolCalls. Name-targeted to leave any other trailing toolCalls visible.
+export function stripInflightAdvisorCall(messages: Message[]): Message[] {
+	if (messages.length === 0) return messages;
+	const last = messages[messages.length - 1];
+	if (last.role !== "assistant") return messages;
+	const filtered = last.content.filter((c) => !(c.type === "toolCall" && c.name === ADVISOR_TOOL_NAME));
+	if (filtered.length === last.content.length) return messages;
+	if (filtered.length === 0) return messages.slice(0, -1);
+	return [...messages.slice(0, -1), { ...last, content: filtered }];
+}
+
+// Some providers (recent Anthropic Claude models) reject payloads ending on an
+// assistant turn ("This model does not support assistant message prefill. The
+// conversation must end with a user message."). After stripInflightAdvisorCall
+// the tail can be assistant (e.g. the executor wrote thinking text before
+// calling advisor). Append a minimal user-role nudge to guarantee user-tail.
+export function ensureUserTailForAdvisor(messages: Message[]): Message[] {
+	if (messages.length === 0) return messages;
+	const last = messages[messages.length - 1];
+	if (last.role !== "assistant") return messages;
+	const nudge: Message = {
+		role: "user",
+		content: [{ type: "text", text: MSG_ADVISOR_NUDGE }],
+		timestamp: Date.now(),
+	};
+	return [...messages, nudge];
+}

package/advisor/execute.ts

@@ -0,0 +1,178 @@
+/**
+ * execute — the advisor side-call. Curates the executor's branch (inventory
+ * prefix + tail massaging), invokes the advisor model via completeSimple with
+ * no tools, and returns a structured tool result. Every result branch (success
+ * / abort / error / empty) and the pre-call error paths funnel through
+ * buildAdvisorResult so the envelope is built in exactly one place.
+ */
+
+import type { StopReason, Usage } from "@earendil-works/pi-ai";
+import { completeSimple, type Message, type ThinkingLevel } from "@earendil-works/pi-ai";
+import {
+	type AgentToolResult,
+	type AgentToolUpdateCallback,
+	buildSessionContext,
+	convertToLlm,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { ensureUserTailForAdvisor, stripInflightAdvisorCall } from "./context.js";
+import { getInventoryMessage } from "./inventory.js";
+import {
+	ERR_ABORTED_DETAIL,
+	ERR_CALL_ABORTED,
+	ERR_EMPTY_RESPONSE,
+	ERR_EMPTY_RESPONSE_DETAIL,
+	ERR_NO_MODEL,
+	ERR_NO_MODEL_SELECTED,
+	errCallFailed,
+	errCallThrew,
+	errMisconfigured,
+	errNoApiKey,
+	errNoApiKeyDetail,
+	msgConsulting,
+} from "./messages.js";
+import { ADVISOR_SYSTEM_PROMPT } from "./prompt.js";
+import { getAdvisorEffort, getAdvisorModel } from "./state.js";
+
+interface AdvisorDetails {
+	advisorModel?: string;
+	effort?: ThinkingLevel;
+	usage?: Usage;
+	stopReason?: StopReason;
+	errorMessage?: string;
+}
+
+// Single result-envelope builder — every executeAdvisor branch and the pre-call
+// error paths funnel through here. `effort` is snapshotted once at executeAdvisor
+// entry and threaded through every call so the returned details.effort always
+// matches the value sent as `reasoning` to completeSimple, even if module-level
+// state is mutated during the await window.
+function buildAdvisorResult(opts: {
+	text: string;
+	effort: ThinkingLevel | undefined;
+	advisorLabel?: string;
+	usage?: Usage;
+	stopReason?: StopReason;
+	errorMessage?: string;
+}): AgentToolResult<AdvisorDetails> {
+	const details: AdvisorDetails = { effort: opts.effort };
+	if (opts.advisorLabel !== undefined) details.advisorModel = opts.advisorLabel;
+	if (opts.usage !== undefined) details.usage = opts.usage;
+	if (opts.stopReason !== undefined) details.stopReason = opts.stopReason;
+	if (opts.errorMessage !== undefined) details.errorMessage = opts.errorMessage;
+	return { content: [{ type: "text", text: opts.text }], details };
+}
+
+function buildErrorResult(
+	advisorLabel: string | undefined,
+	effort: ThinkingLevel | undefined,
+	userText: string,
+	errorMessage: string,
+): AgentToolResult<AdvisorDetails> {
+	return buildAdvisorResult({ text: userText, effort, advisorLabel, errorMessage });
+}
+
+export async function executeAdvisor(
+	ctx: ExtensionContext,
+	pi: ExtensionAPI,
+	signal: AbortSignal | undefined,
+	onUpdate: AgentToolUpdateCallback<AdvisorDetails> | undefined,
+): Promise<AgentToolResult<AdvisorDetails>> {
+	// Snapshot effort once at entry — every result envelope and the API call
+	// itself use this same value so a concurrent setAdvisorEffort() during the
+	// await window cannot desync details.effort from the `reasoning` actually sent.
+	const effort = getAdvisorEffort();
+	const advisor = getAdvisorModel();
+	if (!advisor) {
+		return buildErrorResult(undefined, effort, ERR_NO_MODEL, ERR_NO_MODEL_SELECTED);
+	}
+	const advisorLabel = `${advisor.provider}:${advisor.id}`;
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(advisor);
+	if (!auth.ok) {
+		return buildErrorResult(advisorLabel, effort, errMisconfigured(advisorLabel, auth.error), auth.error);
+	}
+	if (!auth.apiKey) {
+		return buildErrorResult(advisorLabel, effort, errNoApiKey(advisorLabel), errNoApiKeyDetail(advisor.provider));
+	}
+
+	// Live-read every call — advisor runs mid-turn so any message_end snapshot
+	// is always one turn stale. buildSessionContext() preserves Pi's resolved
+	// LLM context, including compaction summaries and branch summaries, instead
+	// of replaying raw pre-compaction branch messages. convertToLlm is
+	// pass-through for user/assistant/toolResult (messages.js:111-114), so
+	// element refs are stable across calls via the session store.
+	const { messages: sessionMessages } = buildSessionContext(
+		ctx.sessionManager.getEntries(),
+		ctx.sessionManager.getLeafId(),
+	);
+	const branchMessages = ensureUserTailForAdvisor(stripInflightAdvisorCall(convertToLlm(sessionMessages)));
+	const inventoryMessage = getInventoryMessage(pi.getAllTools());
+	const messages: Message[] = inventoryMessage ? [inventoryMessage, ...branchMessages] : branchMessages;
+
+	onUpdate?.({
+		content: [{ type: "text", text: msgConsulting(advisorLabel, effort) }],
+		details: { advisorModel: advisorLabel, effort },
+	});
+
+	try {
+		const response = await completeSimple(
+			advisor,
+			// `tools: []` reaffirms the "never calls tools" contract even when
+			// `messages` contains prior toolCall/toolResult blocks (btw.ts:235).
+			{ systemPrompt: ADVISOR_SYSTEM_PROMPT, messages, tools: [] },
+			{ apiKey: auth.apiKey, headers: auth.headers, signal, reasoning: effort },
+		);
+
+		if (response.stopReason === "aborted") {
+			return buildAdvisorResult({
+				text: ERR_CALL_ABORTED,
+				effort,
+				advisorLabel,
+				usage: response.usage,
+				stopReason: response.stopReason,
+				errorMessage: response.errorMessage ?? ERR_ABORTED_DETAIL,
+			});
+		}
+
+		if (response.stopReason === "error") {
+			return buildAdvisorResult({
+				text: errCallFailed(response.errorMessage),
+				effort,
+				advisorLabel,
+				usage: response.usage,
+				stopReason: response.stopReason,
+				errorMessage: response.errorMessage,
+			});
+		}
+
+		const advisorText = response.content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map((c) => c.text)
+			.join("\n")
+			.trim();
+
+		if (!advisorText) {
+			return buildAdvisorResult({
+				text: ERR_EMPTY_RESPONSE,
+				effort,
+				advisorLabel,
+				usage: response.usage,
+				stopReason: response.stopReason,
+				errorMessage: ERR_EMPTY_RESPONSE_DETAIL,
+			});
+		}
+
+		return buildAdvisorResult({
+			text: advisorText,
+			effort,
+			advisorLabel,
+			usage: response.usage,
+			stopReason: response.stopReason,
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return buildErrorResult(advisorLabel, effort, errCallThrew(message), message);
+	}
+}

package/advisor/handlers.ts

@@ -0,0 +1,91 @@
+/**
+ * handlers — mid-session lifecycle handlers. A shared reconcileAdvisorTool
+ * strips or re-adds the advisor tool to match the blocked state (with an
+ * optional notify), and the three register*Handler functions wire it to
+ * before_agent_start, model_select, and thinking_level_select.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { modelKey } from "./config.js";
+import { ADVISOR_TOOL_NAME, MSG_ADVISOR_DISABLED, msgAdvisorRestored } from "./messages.js";
+import { isExecutorBlocked, isModelBlocked } from "./policy.js";
+import { getAdvisorEffort, getAdvisorModel } from "./state.js";
+
+interface ReconcileNotify {
+	/** Shown when the tool is stripped (executor became blocked). */
+	disabled: string;
+	/** Shown when the tool is re-added (executor became unblocked). */
+	restored: string;
+}
+
+// Strip-or-add the advisor tool to match the blocked state, with an optional
+// notify on each transition. Reads the active-tool list itself. Shared by the
+// three lifecycle handlers and the /advisor command's activate step.
+export function reconcileAdvisorTool(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	opts: { blocked: boolean; notify?: ReconcileNotify },
+): void {
+	const active = pi.getActiveTools();
+	const hasTool = active.includes(ADVISOR_TOOL_NAME);
+	if (opts.blocked && hasTool) {
+		pi.setActiveTools(active.filter((n) => n !== ADVISOR_TOOL_NAME));
+		if (opts.notify && ctx.hasUI) ctx.ui.notify(opts.notify.disabled, "info");
+	} else if (!opts.blocked && !hasTool) {
+		pi.setActiveTools([...active, ADVISOR_TOOL_NAME]);
+		if (opts.notify && ctx.hasUI) ctx.ui.notify(opts.notify.restored, "info");
+	}
+}
+
+export function registerAdvisorBeforeAgentStart(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const advisor = getAdvisorModel();
+		if (!advisor) {
+			const active = pi.getActiveTools();
+			if (active.includes(ADVISOR_TOOL_NAME)) {
+				pi.setActiveTools(active.filter((n) => n !== ADVISOR_TOOL_NAME));
+			}
+			return;
+		}
+		reconcileAdvisorTool(pi, ctx, { blocked: isExecutorBlocked(ctx, pi.getThinkingLevel()) });
+	});
+}
+
+export function registerModelSelectHandler(pi: ExtensionAPI): void {
+	pi.on("model_select", async (event, ctx) => {
+		// session_start restore path is owned by restoreAdvisorState — it already
+		// activates the tool and notifies. Skipping "restore" here prevents a
+		// duplicate notification on initial model load.
+		if (event.source === "restore") return;
+
+		const advisor = getAdvisorModel();
+		if (!advisor) return;
+
+		reconcileAdvisorTool(pi, ctx, {
+			blocked: isModelBlocked(event.model, pi.getThinkingLevel()),
+			notify: {
+				disabled: `Advisor disabled for ${modelKey(event.model)}`,
+				restored: msgAdvisorRestored(modelKey(advisor), getAdvisorEffort()),
+			},
+		});
+	});
+}
+
+export function registerThinkingLevelSelectHandler(pi: ExtensionAPI): void {
+	pi.on("thinking_level_select", async (event, ctx) => {
+		const advisor = getAdvisorModel();
+		if (!advisor) return;
+
+		// `blocked === true` implies a defined model (isModelBlocked returns false
+		// for undefined), so the MSG_ADVISOR_DISABLED fallback is unreachable — it
+		// only keeps the disabled string total without a non-null assertion on the model.
+		const model = ctx?.model;
+		reconcileAdvisorTool(pi, ctx, {
+			blocked: isModelBlocked(model, event.level),
+			notify: {
+				disabled: model ? `Advisor disabled for ${modelKey(model)}` : MSG_ADVISOR_DISABLED,
+				restored: msgAdvisorRestored(modelKey(advisor), getAdvisorEffort()),
+			},
+		});
+	});
+}

package/advisor/index.ts

@@ -0,0 +1,39 @@
+/**
+ * advisor — Advisor-strategy pattern: a zero-param `advisor` tool + `/advisor`
+ * command that forward the serialized conversation branch to a separately-
+ * configured reviewer model. Advisor has no tools, never emits user-facing
+ * output, and returns guidance the executor resumes with.
+ *
+ * The implementation is one concern per file under this directory; this barrel
+ * re-exports the package's public surface (consumed by ../index.ts, the repo-
+ * root test/setup.ts, and the advisor.*.test.ts suite via "./advisor/index.js").
+ *
+ * Module map:
+ *   messages   — tool identity, sentinels, effort vocabulary, all strings
+ *   config     — persisted config + provider:id key codec
+ *   state      — in-memory model/effort selection
+ *   policy     — disabledForModels blocklist + blocked predicates
+ *   inventory  — globalThis tool-inventory cache + serializer
+ *   context    — branch-message massaging
+ *   prompt     — system-prompt loader
+ *   execute    — the advisor side-call
+ *   register   — advisor tool registration
+ *   handlers   — mid-session lifecycle handlers
+ *   restore    — session_start restoration
+ *   command    — /advisor slash command
+ */
+
+export { registerAdvisorCommand } from "./command.js";
+export { loadAdvisorConfig, saveAdvisorConfig } from "./config.js";
+export { ensureUserTailForAdvisor, stripInflightAdvisorCall } from "./context.js";
+export {
+	registerAdvisorBeforeAgentStart,
+	registerModelSelectHandler,
+	registerThinkingLevelSelectHandler,
+} from "./handlers.js";
+export { getInventoryMessage, stableStringify } from "./inventory.js";
+export { ADVISOR_TOOL_NAME } from "./messages.js";
+export { setDisabledForModels } from "./policy.js";
+export { DEFAULT_PROMPT_GUIDELINES, DEFAULT_PROMPT_SNIPPET, registerAdvisorTool } from "./register.js";
+export { __resetAdvisorAnnounced, registerAdvisorSessionStart, restoreAdvisorState } from "./restore.js";
+export { getAdvisorEffort, getAdvisorModel, setAdvisorEffort, setAdvisorModel } from "./state.js";

package/advisor/inventory.ts

@@ -0,0 +1,80 @@
+/**
+ * inventory — stable tool-inventory Message for advisor prompt-cache parity.
+ *
+ * globalThis-keyed (Symbol.for("rpiv-advisor")) so the cache survives module
+ * re-import on /new, /fork, /resume (mirrors rpiv-btw/btw.ts). Single-slot — the
+ * Pi tool registry is process-scoped, so per-session keying would be redundant;
+ * the cache invalidates only when the set of registered tool names changes. Also
+ * exposes the key-sorted JSON serializer (stableStringify) the block is built from.
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+
+const ADVISOR_STATE_KEY = Symbol.for("rpiv-advisor");
+
+interface AdvisorState {
+	inventorySignature?: string;
+	inventoryMessage?: Message;
+}
+
+function getAdvisorRuntimeState(): AdvisorState {
+	const g = globalThis as unknown as { [k: symbol]: AdvisorState | undefined };
+	let state = g[ADVISOR_STATE_KEY];
+	if (!state) {
+		state = {};
+		g[ADVISOR_STATE_KEY] = state;
+	}
+	return state;
+}
+
+// Recursive key-sorted JSON serializer — matches JSON.stringify semantics
+// (drops `undefined` in objects, emits `null` for `undefined` in arrays) but
+// guarantees stable key ordering across V8 insertion-order variation. Required
+// because nested TypeBox schemas may be authored in any order, and prompt
+// caching is byte-sensitive.
+export function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== "object") {
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((v) => (v === undefined ? "null" : stableStringify(v))).join(",")}]`;
+	}
+	const obj = value as Record<string, unknown>;
+	const entries: string[] = [];
+	for (const k of Object.keys(obj).sort()) {
+		const v = obj[k];
+		if (v === undefined) continue;
+		entries.push(`${JSON.stringify(k)}:${stableStringify(v)}`);
+	}
+	return `{${entries.join(",")}}`;
+}
+
+function buildInventoryBlock(tools: ToolInfo[]): string {
+	// Omit `sourceInfo` — its `path` field is install-location-dependent and
+	// would bust cache parity across machines/reinstalls.
+	return tools
+		.map((t) => `### ${t.name}\n${t.description}\n\nParameters: ${stableStringify(t.parameters)}`)
+		.join("\n\n---\n\n");
+}
+
+// Returns `undefined` when the registry is empty (no extensions loaded) so
+// callers can skip prepending an empty block that would still cost a cache unit.
+export function getInventoryMessage(tools: ToolInfo[]): Message | undefined {
+	if (tools.length === 0) return undefined;
+	const sorted = [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+	const signature = sorted.map((t) => t.name).join("|");
+	const state = getAdvisorRuntimeState();
+	if (state.inventorySignature === signature && state.inventoryMessage) {
+		return state.inventoryMessage;
+	}
+	const text = `## Available Executor Tools\n\n${buildInventoryBlock(sorted)}`;
+	const message: Message = {
+		role: "user",
+		content: [{ type: "text", text }],
+		timestamp: Date.now(),
+	};
+	state.inventorySignature = signature;
+	state.inventoryMessage = message;
+	return message;
+}