@juicesharp/rpiv-advisor 0.1.3 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@ implementing the advisor-strategy pattern: the executor model can escalate
 decisions to a stronger reviewer model (e.g. Opus), receive guidance, and
 resume.
 
-![Advisor model selector](https://raw.githubusercontent.com/juicesharp/rpiv-advisor/main/docs/advisor.jpg)
+![Advisor model selector](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-advisor/docs/advisor.jpg)
 
 ## Installation
 

package/advisor-ui.ts

@@ -6,9 +6,9 @@
  * SelectList theme wiring.
  */
 
-import { DynamicBorder, type ExtensionContext, type Theme } from "@mariozechner/pi-coding-agent";
 import type { ThinkingLevel } from "@mariozechner/pi-ai";
-import { Container, SelectList, Spacer, Text, type SelectItem } from "@mariozechner/pi-tui";
+import { DynamicBorder, type ExtensionContext, type Theme } from "@mariozechner/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Spacer, Text } from "@mariozechner/pi-tui";
 
 const MAX_VISIBLE_ROWS = 10;
 const NAV_HINT = "↑↓ navigate • enter select • esc cancel";
@@ -39,12 +39,7 @@ function selectListTheme(theme: Theme) {
 	};
 }
 
-function buildSelectPanel(
-	theme: Theme,
-	title: string,
-	proseLines: string[],
-	selectList: SelectList,
-): Container {
+function buildSelectPanel(theme: Theme, title: string, proseLines: string[], selectList: SelectList): Container {
 	const container = new Container();
 	const border = () => new DynamicBorder((s: string) => theme.fg("accent", s));
 
@@ -64,16 +59,9 @@ function buildSelectPanel(
 	return container;
 }
 
-export async function showAdvisorPicker(
-	ctx: ExtensionContext,
-	items: SelectItem[],
-): Promise<string | null> {
+export async function showAdvisorPicker(ctx: ExtensionContext, items: SelectItem[]): Promise<string | null> {
 	return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-		const selectList = new SelectList(
-			items,
-			Math.min(items.length, MAX_VISIBLE_ROWS),
-			selectListTheme(theme),
-		);
+		const selectList = new SelectList(items, Math.min(items.length, MAX_VISIBLE_ROWS), selectListTheme(theme));
 		selectList.onSelect = (item) => done(item.value);
 		selectList.onCancel = () => done(null);
 
@@ -102,28 +90,15 @@ export async function showEffortPicker(
 	defaultEffort: ThinkingLevel,
 ): Promise<string | null> {
 	return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
-		const selectList = new SelectList(
-			items,
-			Math.min(items.length, MAX_VISIBLE_ROWS),
-			selectListTheme(theme),
-		);
-		const preferredIdx = currentEffort
-			? items.findIndex((item) => item.value === currentEffort)
-			: -1;
+		const selectList = new SelectList(items, Math.min(items.length, MAX_VISIBLE_ROWS), selectListTheme(theme));
+		const preferredIdx = currentEffort ? items.findIndex((item) => item.value === currentEffort) : -1;
 		selectList.setSelectedIndex(
-			preferredIdx >= 0
-				? preferredIdx
-				: items.findIndex((item) => item.value === defaultEffort),
+			preferredIdx >= 0 ? preferredIdx : items.findIndex((item) => item.value === defaultEffort),
 		);
 		selectList.onSelect = (item) => done(item.value);
 		selectList.onCancel = () => done(null);
 
-		const container = buildSelectPanel(
-			theme,
-			EFFORT_HEADER_TITLE,
-			[EFFORT_HEADER_PROSE],
-			selectList,
-		);
+		const container = buildSelectPanel(theme, EFFORT_HEADER_TITLE, [EFFORT_HEADER_PROSE], selectList);
 
 		return {
 			render: (w) => container.render(w),

package/advisor.ts

@@ -14,19 +14,19 @@
  */
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { completeSimple, supportsXhigh, type Message, type ThinkingLevel } from "@mariozechner/pi-ai";
 import type { Api, Model, StopReason, Usage } from "@mariozechner/pi-ai";
+import { completeSimple, type Message, supportsXhigh, type ThinkingLevel } from "@mariozechner/pi-ai";
 import {
-	convertToLlm,
-	serializeConversation,
 	type AgentToolResult,
 	type AgentToolUpdateCallback,
+	convertToLlm,
 	type ExtensionAPI,
 	type ExtensionContext,
 	type SessionEntry,
+	type ToolInfo,
 } from "@mariozechner/pi-coding-agent";
 import type { SelectItem } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -63,8 +63,7 @@ const MSG_ADVISOR_DISABLED = "Advisor disabled";
 const MSG_REQUIRES_INTERACTIVE = "/advisor requires interactive mode";
 
 // Errors (static)
-const ERR_NO_MODEL =
-	"No advisor model is configured. The user can enable one with the /advisor command.";
+const ERR_NO_MODEL = "No advisor model is configured. The user can enable one with the /advisor command.";
 const ERR_CALL_ABORTED = "Advisor call was cancelled before it completed.";
 const ERR_EMPTY_RESPONSE = "Advisor returned no text content.";
 const ERR_NO_MODEL_SELECTED = "no advisor model selected";
@@ -73,15 +72,13 @@ const ERR_ABORTED_DETAIL = "aborted";
 const ERR_UNKNOWN = "unknown error";
 
 // Errors/messages (parameterized)
-const errMisconfigured = (label: string, err: string) =>
-	`Advisor (${label}) is misconfigured: ${err}`;
+const errMisconfigured = (label: string, err: string) => `Advisor (${label}) is misconfigured: ${err}`;
 const errNoApiKey = (label: string) => `Advisor (${label}) has no API key available.`;
 const errNoApiKeyDetail = (provider: string) => `no API key for ${provider}`;
 const errCallFailed = (err: string | undefined) => `Advisor call failed: ${err ?? ERR_UNKNOWN}`;
 const errCallThrew = (msg: string) => `Advisor call threw: ${msg}`;
 const errSelectionNotFound = (choice: string) => `Advisor selection not found: ${choice}`;
-const errModelUnavailable = (key: string) =>
-	`Previously configured advisor model ${key} is no longer available`;
+const errModelUnavailable = (key: string) => `Previously configured advisor model ${key} is no longer available`;
 const msgAdvisorEnabled = (label: string, effort: ThinkingLevel | undefined) =>
 	`Advisor: ${label}${effort ? `, ${effort}` : ""}`;
 const msgAdvisorRestored = (label: string, effort: ThinkingLevel | undefined) =>
@@ -113,7 +110,7 @@ function saveAdvisorConfig(key: string | undefined, effort: ThinkingLevel | unde
 	if (effort) config.effort = effort;
 	try {
 		mkdirSync(dirname(ADVISOR_CONFIG_PATH), { recursive: true });
-		writeFileSync(ADVISOR_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf-8");
+		writeFileSync(ADVISOR_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
 	} catch {
 		// write may fail on disk-full or permission errors — best effort only
 	}
@@ -139,6 +136,97 @@ export const ADVISOR_SYSTEM_PROMPT = readFileSync(
 	"utf-8",
 ).trimEnd();
 
+// ---------------------------------------------------------------------------
+// Inventory state + serializer — stable tool-inventory Message for cache parity
+//
+// globalThis-keyed to survive module re-import on /new, /fork, /resume (mirrors
+// rpiv-btw/btw.ts:37, 87-98). Single-slot cache — the Pi tool registry is
+// process-scoped, so per-session keying would be redundant. Cache invalidates
+// only when the set of registered tool names changes.
+// ---------------------------------------------------------------------------
+
+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.
+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");
+}
+
+// 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.
+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 }];
+}
+
+// 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;
+}
+
 // ---------------------------------------------------------------------------
 // Module state — in-memory, resets each session
 // ---------------------------------------------------------------------------
@@ -216,14 +304,13 @@ function buildErrorResult(
 	const effort = getAdvisorEffort();
 	return {
 		content: [{ type: "text", text: userText }],
-		details: advisorLabel
-			? { advisorModel: advisorLabel, effort, errorMessage }
-			: { effort, errorMessage },
+		details: advisorLabel ? { advisorModel: advisorLabel, effort, errorMessage } : { effort, errorMessage },
 	};
 }
 
 async function executeAdvisor(
 	ctx: ExtensionContext,
+	pi: ExtensionAPI,
 	signal: AbortSignal | undefined,
 	onUpdate: AgentToolUpdateCallback<AdvisorDetails> | undefined,
 ): Promise<AgentToolResult<AdvisorDetails>> {
@@ -239,29 +326,20 @@ async function executeAdvisor(
 		return buildErrorResult(advisorLabel, errMisconfigured(advisorLabel, auth.error), auth.error);
 	}
 	if (!auth.apiKey) {
-		return buildErrorResult(
-			advisorLabel,
-			errNoApiKey(advisorLabel),
-			errNoApiKeyDetail(advisor.provider),
-		);
+		return buildErrorResult(advisorLabel, errNoApiKey(advisorLabel), errNoApiKeyDetail(advisor.provider));
 	}
 
+	// Live-read every call — advisor runs mid-turn so any message_end snapshot
+	// is always one turn stale. convertToLlm is pass-through for user/assistant/
+	// toolResult (messages.js:111-114), so element refs are stable across calls
+	// via the session store — content-stable output without a snapshot layer.
 	const branch = ctx.sessionManager.getBranch();
 	const agentMessages = branch
 		.filter((e): e is SessionEntry & { type: "message" } => e.type === "message")
 		.map((e) => e.message);
-	const conversationText = serializeConversation(convertToLlm(agentMessages));
-
-	const userMessage: Message = {
-		role: "user",
-		content: [
-			{
-				type: "text",
-				text: `## Conversation So Far\n\n${conversationText}`,
-			},
-		],
-		timestamp: Date.now(),
-	};
+	const branchMessages = stripInflightAdvisorCall(convertToLlm(agentMessages));
+	const inventoryMessage = getInventoryMessage(pi.getAllTools());
+	const messages: Message[] = inventoryMessage ? [inventoryMessage, ...branchMessages] : branchMessages;
 
 	onUpdate?.({
 		content: [{ type: "text", text: msgConsulting(advisorLabel, effort) }],
@@ -271,7 +349,9 @@ async function executeAdvisor(
 	try {
 		const response = await completeSimple(
 			advisor,
-			{ systemPrompt: ADVISOR_SYSTEM_PROMPT, messages: [userMessage] },
+			// `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 },
 		);
 
@@ -371,7 +451,7 @@ export function registerAdvisorTool(pi: ExtensionAPI): void {
 		parameters: AdvisorParams,
 
 		async execute(_toolCallId, _params, signal, onUpdate, ctx) {
-			return executeAdvisor(ctx, signal, onUpdate);
+			return executeAdvisor(ctx, pi, signal, onUpdate);
 		},
 	});
 }
@@ -435,9 +515,7 @@ export function registerAdvisorCommand(pi: ExtensionAPI): void {
 				setAdvisorEffort(undefined);
 				saveAdvisorConfig(undefined, undefined);
 				if (activeHas) {
-					pi.setActiveTools(
-						activeTools.filter((n) => n !== ADVISOR_TOOL_NAME),
-					);
+					pi.setActiveTools(activeTools.filter((n) => n !== ADVISOR_TOOL_NAME));
 				}
 				ctx.ui.notify(MSG_ADVISOR_DISABLED, "info");
 				return;
@@ -452,9 +530,7 @@ export function registerAdvisorCommand(pi: ExtensionAPI): void {
 			// Effort picker — only for reasoning-capable models
 			let effortChoice: ThinkingLevel | undefined;
 			if (picked.reasoning) {
-				const levels = supportsXhigh(picked)
-					? [...BASE_EFFORT_LEVELS, XHIGH_EFFORT_LEVEL]
-					: BASE_EFFORT_LEVELS;
+				const levels = supportsXhigh(picked) ? [...BASE_EFFORT_LEVELS, XHIGH_EFFORT_LEVEL] : BASE_EFFORT_LEVELS;
 
 				const effortItems: SelectItem[] = [
 					{ value: OFF_VALUE, label: "off" },
@@ -464,12 +540,7 @@ export function registerAdvisorCommand(pi: ExtensionAPI): void {
 					})),
 				];
 
-				const effortResult = await showEffortPicker(
-					ctx,
-					effortItems,
-					getAdvisorEffort(),
-					DEFAULT_EFFORT,
-				);
+				const effortResult = await showEffortPicker(ctx, effortItems, getAdvisorEffort(), DEFAULT_EFFORT);
 				if (!effortResult) {
 					return;
 				}

package/index.ts

@@ -11,18 +11,18 @@
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import {
-    registerAdvisorTool,
-    registerAdvisorCommand,
-    registerAdvisorBeforeAgentStart,
-    restoreAdvisorState,
+	registerAdvisorBeforeAgentStart,
+	registerAdvisorCommand,
+	registerAdvisorTool,
+	restoreAdvisorState,
 } from "./advisor.js";
 
 export default function (pi: ExtensionAPI) {
-    registerAdvisorTool(pi);
-    registerAdvisorCommand(pi);
-    registerAdvisorBeforeAgentStart(pi);
+	registerAdvisorTool(pi);
+	registerAdvisorCommand(pi);
+	registerAdvisorBeforeAgentStart(pi);
 
-    pi.on("session_start", async (_event, ctx) => {
-        restoreAdvisorState(ctx, pi);
-    });
+	pi.on("session_start", async (_event, ctx) => {
+		restoreAdvisorState(ctx, pi);
+	});
 }

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "@juicesharp/rpiv-advisor",
-  "version": "0.1.3",
+  "version": "0.7.0",
   "description": "Pi extension: advisor-strategy pattern — escalate to a stronger reviewer model",
-  "keywords": ["pi-package", "pi-extension", "rpiv", "advisor"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "rpiv",
+    "advisor"
+  ],
   "type": "module",
   "license": "MIT",
   "author": "juicesharp",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/juicesharp/rpiv-advisor.git"
+    "url": "git+https://github.com/juicesharp/rpiv-mono.git",
+    "directory": "packages/rpiv-advisor"
   },
-  "homepage": "https://github.com/juicesharp/rpiv-advisor#readme",
+  "homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-advisor#readme",
   "bugs": {
-    "url": "https://github.com/juicesharp/rpiv-advisor/issues"
+    "url": "https://github.com/juicesharp/rpiv-mono/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -22,10 +28,13 @@
     "advisor.ts",
     "advisor-ui.ts",
     "prompts/",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "peerDependencies": {
     "@mariozechner/pi-ai": "*",

package/prompts/advisor-system.txt

@@ -1,4 +1,4 @@
-You are an advisor model in an advisor-strategy pattern. An executor model is running a task end-to-end — calling tools, reading results, iterating toward a solution. When the executor hits a decision it cannot reasonably solve alone, it consults you for guidance.
+You are an advisor model in an advisor-strategy pattern. An executor model is running a task end-to-end — calling tools, reading results, iterating toward a solution. When the executor hits a decision it cannot reasonably solve alone, it consults you for guidance. The executor's full tool inventory is prepended before the conversation so you can judge tool-choice correctness.
 
 You read the shared conversation context and return ONE of:
 - a plan (concrete next steps the executor should take),