@juicesharp/rpiv-advisor 2.5.2 → 2.6.1

package/README.md

@@ -78,7 +78,7 @@ write leaves your previous selection untouched and tells you so.
 | Key | What it does | Default |
 | --- | --- | --- |
 | `modelKey` | The reviewer model, as `"provider/modelId"`. Written by `/advisor`. | absent — advisor off |
-| `effort` | Reasoning effort for the reviewer: `minimal`, `low`, `medium`, `high`, `xhigh`. Written by `/advisor`. | absent — no reasoning sent |
+| `effort` | Reasoning effort for the reviewer: `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Written by `/advisor`; only levels supported by the selected model are offered. | absent — no reasoning sent |
 | `disabledForModels` | Executor models the advisor is stripped for. Plain strings block at any effort; `{ "model": "…", "minEffort": "…" }` blocks only at or above that effort. | `[]` |
 
 ```json

package/advisor/command.ts

@@ -2,11 +2,12 @@
  * 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).
+ * helpers persist before mutating in-memory state — a save failure must never
+ * leave memory ahead of disk.
  */
 
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { getSupportedThinkingLevels, type ThinkingLevel } from "@earendil-works/pi-ai";
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SelectItem } from "@earendil-works/pi-tui";
 import { modelKey } from "@juicesharp/rpiv-config";
@@ -15,11 +16,13 @@ import { saveAdvisorConfig } from "./config.js";
 import { reconcileAdvisorTool } from "./handlers.js";
 import {
 	ADVISOR_TOOL_NAME,
-	BASE_EFFORT_LEVELS,
 	CHECKMARK,
 	DEFAULT_EFFORT,
+	EFFORT_ORDINAL,
 	errSelectionNotFound,
+	type GradedEffort,
 	MSG_ADVISOR_DISABLED,
+	MSG_EFFORT_NOT_SET,
 	MSG_PERSIST_FAILED,
 	MSG_REQUIRES_INTERACTIVE,
 	msgAdvisorEnabled,
@@ -27,11 +30,13 @@ import {
 	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";
 
+// Mirror: packages/rpiv-pi/extensions/rpiv-core/rpiv-models/items.ts
+// buildModelItems — structural twin kept in a separate package by the
+// zero-cross-imports contract; evolve model-picker semantics together.
 function buildModelItems(availableModels: Model<Api>[], currentKey: string | undefined): SelectItem[] {
 	const items: SelectItem[] = availableModels.map((m) => {
 		const key = modelKey(m);
@@ -45,12 +50,20 @@ function buildModelItems(availableModels: Model<Api>[], currentKey: string | und
 	return items;
 }
 
+// Mirror: packages/rpiv-pi/extensions/rpiv-core/rpiv-models/items.ts
+// buildEffortItems — same filter-in/map-out shape, different sentinels and
+// persist target; evolve level-picker semantics together.
 function buildEffortItems(picked: Model<Api>): SelectItem[] {
-	const levels = getSupportedThinkingLevels(picked).includes("xhigh")
-		? [...BASE_EFFORT_LEVELS, XHIGH_EFFORT_LEVEL]
-		: BASE_EFFORT_LEVELS;
+	// Intersect with EFFORT_ORDINAL (which excludes "off") so the picker can
+	// never offer — hence saveAdvisorConfig can never persist — a level that
+	// minEffort blocklist comparisons don't rank.
+	const levels = getSupportedThinkingLevels(picked).filter((level): level is GradedEffort =>
+		EFFORT_ORDINAL.includes(level as GradedEffort),
+	);
 	return [
-		{ value: OFF_VALUE, label: "off" },
+		// "off (no reasoning sent)" ≠ /rpiv-models' "off (disable reasoning)":
+		// this row sends NO reasoning option; /rpiv-models persists thinking:"off".
+		{ value: OFF_VALUE, label: "off (no reasoning sent)" },
 		...levels.map((level) => ({
 			value: level,
 			label: level === DEFAULT_EFFORT ? `${level}${RECOMMENDED_EFFORT_SUFFIX}` : level,
@@ -59,7 +72,7 @@ function buildEffortItems(picked: Model<Api>): SelectItem[] {
 }
 
 // Disable path — persist BEFORE mutating in-memory state so a save failure
-// can't strand "model=undefined + tool still registered" (review I2). The strip
+// can't strand "model=undefined + tool still registered". 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 {
@@ -76,7 +89,7 @@ function applyDisable(pi: ExtensionAPI, ctx: ExtensionContext): void {
 	ctx.ui.notify(MSG_ADVISOR_DISABLED, "info");
 }
 
-// Enable path — persist first (review I2), set in-memory state, activate via
+// Enable path — persist first, 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.
@@ -84,7 +97,7 @@ function applyEnable(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
 	picked: Model<Api>,
-	effort: ThinkingLevel | undefined,
+	effort: GradedEffort | undefined,
 ): void {
 	if (!saveAdvisorConfig(modelKey(picked), effort)) {
 		ctx.ui.notify(MSG_PERSIST_FAILED, "error");
@@ -129,7 +142,7 @@ export function registerAdvisorCommand(pi: ExtensionAPI): void {
 			}
 
 			// Effort picker — only for reasoning-capable models
-			let effortChoice: ThinkingLevel | undefined;
+			let effortChoice: GradedEffort | undefined;
 			if (picked.reasoning) {
 				const effortResult = await showEffortPicker(
 					ctx,
@@ -137,8 +150,17 @@ export function registerAdvisorCommand(pi: ExtensionAPI): void {
 					getAdvisorEffort(),
 					DEFAULT_EFFORT,
 				);
-				if (!effortResult) return;
-				effortChoice = effortResult === OFF_VALUE ? undefined : (effortResult as ThinkingLevel);
+				if (!effortResult) {
+					// Esc at the effort step keeps the model selection — cancelling
+					// one step never discards prior choices (the invariant shared
+					// with the /rpiv-models stepper). The divergence is deliberate:
+					// that twin backs up without writing, while here the enable
+					// proceeds and PERSISTS with no explicit effort (model default),
+					// announced by this notify before the write.
+					ctx.ui.notify(MSG_EFFORT_NOT_SET, "info");
+				} else {
+					effortChoice = effortResult === OFF_VALUE ? undefined : (effortResult as GradedEffort);
+				}
 			}
 
 			applyEnable(pi, ctx, picked, effortChoice);

package/advisor/config.ts

@@ -1,21 +1,21 @@
 /**
  * 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).
+ * the provider:id key codec. Owns the AdvisorConfig shape and load/validate/save.
+ * The modelKey (join) / parseModelKey (split) inverse pair the codec relies on
+ * lives in @juicesharp/rpiv-config.
  */
 
-import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import type { GuidanceFields } from "@juicesharp/rpiv-config";
 import { configPath, loadJsonConfigWithLegacyFallback, saveJsonConfig } from "@juicesharp/rpiv-config";
-import { EFFORT_ORDINAL } from "./messages.js";
+import { EFFORT_ORDINAL, type GradedEffort } from "./messages.js";
 
 const ADVISOR_CONFIG_PATH = configPath("rpiv-advisor", "advisor.json");
 
-export type DisabledForModelsEntry = string | { model: string; minEffort?: ThinkingLevel };
+export type DisabledForModelsEntry = string | { model: string; minEffort?: GradedEffort };
 
 interface AdvisorConfig {
 	modelKey?: string;
-	effort?: ThinkingLevel;
+	effort?: GradedEffort;
 	guidance?: GuidanceFields;
 	disabledForModels?: DisabledForModelsEntry[];
 }
@@ -31,12 +31,19 @@ export function validateDisabledForModels(value: unknown): DisabledForModelsEntr
 		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;
+		if (obj.minEffort !== undefined && !EFFORT_ORDINAL.includes(obj.minEffort as GradedEffort)) {
+			// Warn before dropping — the entry's model identity is discarded along
+			// with the bad threshold (mirrors models-config's warn-on-miss posture).
+			console.warn(
+				`[rpiv-advisor] advisor.json: unknown minEffort "${String(obj.minEffort)}" — dropping disabledForModels entry for "${obj.model}"`,
+			);
+			return false;
+		}
 		return true;
 	});
 }
 
-export function saveAdvisorConfig(key: string | undefined, effort: ThinkingLevel | undefined): boolean {
+export function saveAdvisorConfig(key: string | undefined, effort: GradedEffort | undefined): boolean {
 	const existing = loadAdvisorConfig();
 	const config: AdvisorConfig = { ...existing };
 	// Delete (rather than omit) to clear fields that may exist in the spread

package/advisor/execute.ts

@@ -105,7 +105,12 @@ export async function executeAdvisor(
 	if (!auth.ok) {
 		return buildErrorResult(advisorLabel, effort, errMisconfigured(advisorLabel, auth.error), auth.error);
 	}
-	if (!auth.apiKey) {
+	// OAuth-backed providers resolve `{ ok: true }` with no literal apiKey — their
+	// credentials are applied inside Pi's runtime facade. A missing key is only
+	// fatal on legacy hosts without that facade, where the global completion
+	// fallback needs the key passed explicitly.
+	const runtimeCompleteSimple = getRuntimeCompleteSimple(ctx.modelRegistry);
+	if (!auth.apiKey && !runtimeCompleteSimple) {
 		return buildErrorResult(advisorLabel, effort, errNoApiKey(advisorLabel), errNoApiKeyDetail(advisor.provider));
 	}
 
@@ -129,12 +134,12 @@ export async function executeAdvisor(
 	});
 
 	try {
-		// Prefer Pi's auth-aware runtime facade. Unlike the global compatibility
-		// function, it runs request preparation and applies credential-derived
-		// fields such as GitHub Copilot's OAuth-specific baseUrl. Do not pass the
-		// preflight key/headers to this path: explicit overrides would bypass that
-		// resolution and reintroduce the endpoint mismatch.
-		const runtimeCompleteSimple = getRuntimeCompleteSimple(ctx.modelRegistry);
+		// Prefer Pi's auth-aware runtime facade (resolved once above, before the
+		// missing-key guard). Unlike the global compatibility function, it runs
+		// request preparation and applies credential-derived fields such as GitHub
+		// Copilot's OAuth-specific baseUrl. Do not pass the preflight key/headers
+		// to this path: explicit overrides would bypass that resolution and
+		// reintroduce the endpoint mismatch.
 		const completeSimple = runtimeCompleteSimple ?? (await loadCompleteSimple());
 		const requestOptions = runtimeCompleteSimple
 			? { signal, reasoning: effort }

package/advisor/messages.ts

@@ -14,11 +14,14 @@ export const TOOL_LABEL = "Advisor";
 export const NO_ADVISOR_VALUE = "__no_advisor__";
 export const OFF_VALUE = "__off__";
 
-// Effort levels
-export const BASE_EFFORT_LEVELS: ThinkingLevel[] = ["minimal", "low", "medium", "high"];
-export const XHIGH_EFFORT_LEVEL: ThinkingLevel = "xhigh";
-export const EFFORT_ORDINAL: readonly ThinkingLevel[] = ["minimal", "low", "medium", "high", "xhigh"];
-export const DEFAULT_EFFORT: ThinkingLevel = "high";
+// Effort levels. GradedEffort is the ordinal's domain: the graded levels only,
+// never "off" — an "off" element would corrupt the indexOf ranking that
+// minEffort thresholds compare against. Today pi-ai's ThinkingLevel already
+// excludes "off" (the Exclude is a defensive no-op); the alias keeps that
+// exclusion structural if the upstream universe ever re-widens.
+export type GradedEffort = Exclude<ThinkingLevel, "off">;
+export const EFFORT_ORDINAL: readonly GradedEffort[] = ["minimal", "low", "medium", "high", "xhigh", "max"];
+export const DEFAULT_EFFORT: GradedEffort = "high";
 export const RECOMMENDED_EFFORT_SUFFIX = "  (recommended)";
 
 // UI — labels used by command flow; panel prose/titles live in advisor-ui.ts
@@ -28,6 +31,7 @@ export const CHECKMARK = " ✓";
 export const MSG_ADVISOR_DISABLED = "Advisor disabled";
 export const MSG_REQUIRES_INTERACTIVE = "/advisor requires interactive mode";
 export const MSG_ADVISOR_NUDGE = "Please advise on the executor's situation above.";
+export const MSG_EFFORT_NOT_SET = "Effort not set — advisor uses the model default";
 export const MSG_PERSIST_FAILED = "Failed to save advisor selection — selection not persisted";
 
 // Errors (static)

package/advisor/policy.ts

@@ -3,11 +3,11 @@
  * that decide whether the advisor tool is blocked for a given model/effort.
  */
 
-import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { modelKey, parseModelKey } from "@juicesharp/rpiv-config";
 import type { DisabledForModelsEntry } from "./config.js";
-import { EFFORT_ORDINAL } from "./messages.js";
+import { EFFORT_ORDINAL, type GradedEffort } from "./messages.js";
 
 let disabledForModelsCache: DisabledForModelsEntry[] = [];
 
@@ -27,6 +27,12 @@ function canonicalKey(entry: string): string {
 	return parsed ? `${parsed.provider}/${parsed.modelId}` : entry;
 }
 
+/**
+ * True when `model` is on the disabledForModels blocklist at the executor's
+ * current thinking level. Fail-soft ranking contract: an executor level that
+ * is unset, "off", or unknown to EFFORT_ORDINAL yields indexOf −1, ranking
+ * below every minEffort threshold — such levels never block.
+ */
 export function isModelBlocked(model: Model<Api> | undefined, thinkingLevel?: string): boolean {
 	if (!model) return false;
 	const key = modelKey(model);
@@ -37,7 +43,11 @@ export function isModelBlocked(model: Model<Api> | undefined, thinkingLevel?: st
 			if (canonicalKey(entry.model) !== key) continue;
 			if (entry.minEffort === undefined) return true;
 			const thresholdOrdinal = EFFORT_ORDINAL.indexOf(entry.minEffort);
-			const executorOrdinal = EFFORT_ORDINAL.indexOf(thinkingLevel as ThinkingLevel);
+			// A threshold unknown to the ordinal cannot rank; skip the entry —
+			// otherwise its indexOf -1 would equal an unknown executor's -1 and
+			// block, breaking the "unknown never blocks" contract above.
+			if (thresholdOrdinal === -1) continue;
+			const executorOrdinal = EFFORT_ORDINAL.indexOf(thinkingLevel as GradedEffort);
 			if (executorOrdinal >= thresholdOrdinal) return true;
 		}
 	}

package/advisor/restore.ts

@@ -8,7 +8,13 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { modelKey, parseModelKey } from "@juicesharp/rpiv-config";
 import { loadAdvisorConfig, validateDisabledForModels } from "./config.js";
 import { reconcileAdvisorTool } from "./handlers.js";
-import { ADVISOR_TOOL_NAME, errModelUnavailable, msgAdvisorRestored, msgAdvisorRestoredInactive } from "./messages.js";
+import {
+	ADVISOR_TOOL_NAME,
+	EFFORT_ORDINAL,
+	errModelUnavailable,
+	msgAdvisorRestored,
+	msgAdvisorRestoredInactive,
+} from "./messages.js";
 import { isExecutorBlocked, setDisabledForModels } from "./policy.js";
 import { setAdvisorEffort, setAdvisorModel } from "./state.js";
 
@@ -74,14 +80,26 @@ export function restoreAdvisorState(ctx: ExtensionContext, pi: ExtensionAPI): vo
 	}
 
 	setAdvisorModel(model);
-	if (config.effort) {
-		setAdvisorEffort(config.effort);
+	// Overwrite — never merge — the in-memory effort with the persisted value.
+	// "Model present, effort absent" is a first-class persisted state (the
+	// /advisor Esc and off choices both save it), and another process can
+	// remove the field from the shared advisor.json mid-session; a guarded set
+	// here would leave a stale module-level effort feeding `reasoning` on every
+	// advisor call. A hand-edited value unknown to EFFORT_ORDINAL is dropped
+	// with a warning rather than restored and sent as `reasoning`.
+	let effort = config.effort;
+	if (effort !== undefined && !EFFORT_ORDINAL.includes(effort)) {
+		console.warn(
+			`[rpiv-advisor] advisor.json: unknown effort "${effort}" — ignoring (valid values: ${EFFORT_ORDINAL.join(", ")})`,
+		);
+		effort = undefined;
 	}
+	setAdvisorEffort(effort);
 
 	if (isExecutorBlocked(ctx, pi.getThinkingLevel())) {
 		reconcileAdvisorTool(pi, ctx, { blocked: true });
 		const advisorLabel = modelKey(model);
-		notifyOnce(msgAdvisorRestoredInactive(advisorLabel, config.effort), "info");
+		notifyOnce(msgAdvisorRestoredInactive(advisorLabel, effort), "info");
 		return;
 	}
 
@@ -90,7 +108,7 @@ export function restoreAdvisorState(ctx: ExtensionContext, pi: ExtensionAPI): vo
 		pi.setActiveTools([...active, ADVISOR_TOOL_NAME]);
 	}
 
-	notifyOnce(msgAdvisorRestored(modelKey(model), config.effort), "info");
+	notifyOnce(msgAdvisorRestored(modelKey(model), effort), "info");
 }
 
 export function registerAdvisorSessionStart(pi: ExtensionAPI): void {

package/advisor/state.ts

@@ -3,10 +3,11 @@
  * the persisted form lives in config.ts, the blocklist cache in policy.ts.
  */
 
-import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { GradedEffort } from "./messages.js";
 
 let selectedAdvisor: Model<Api> | undefined;
-let selectedAdvisorEffort: ThinkingLevel | undefined;
+let selectedAdvisorEffort: GradedEffort | undefined;
 
 export function getAdvisorModel(): Model<Api> | undefined {
 	return selectedAdvisor;
@@ -16,10 +17,10 @@ export function setAdvisorModel(model: Model<Api> | undefined): void {
 	selectedAdvisor = model;
 }
 
-export function getAdvisorEffort(): ThinkingLevel | undefined {
+export function getAdvisorEffort(): GradedEffort | undefined {
 	return selectedAdvisorEffort;
 }
 
-export function setAdvisorEffort(effort: ThinkingLevel | undefined): void {
+export function setAdvisorEffort(effort: GradedEffort | undefined): void {
 	selectedAdvisorEffort = effort;
 }

package/docs/configuration.md

@@ -41,7 +41,7 @@ previous selection and the active tool list are left untouched.
 | Key | Type | Default | Written by |
 | --- | --- | --- | --- |
 | `modelKey` | `string` — `"provider/modelId"` | absent (advisor off) | `/advisor` |
-| `effort` | `"minimal" \| "low" \| "medium" \| "high" \| "xhigh"` | absent (no `reasoning` sent) | `/advisor` effort picker |
+| `effort` | graded thinking level (`minimal` → `max`) | absent (no `reasoning` sent) | `/advisor` effort picker |
 | `disabledForModels` | `(string \| { model, minEffort? })[]` | `[]` | hand-edited |
 | `guidance.promptSnippet` | `string` | built-in snippet | hand-edited |
 | `guidance.promptGuidelines` | `string[]` | six built-in guidelines | hand-edited |
@@ -59,12 +59,18 @@ form the next time you save through `/advisor`.
 ### `effort`
 
 Offered only for models whose registry entry reports reasoning support. The
-picker lists `off`, `minimal`, `low`, `medium`, `high`, and adds `xhigh` when
-the picked model supports it. `high` is marked `(recommended)`. Choosing `off`
-deletes the key, and no `reasoning` parameter is sent with the advisor call.
-
-`EFFORT_ORDINAL`, lowest to highest, is `minimal`, `low`, `medium`, `high`,
-`xhigh`. This ordering is what `minEffort` compares against.
+picker lists `off (no reasoning sent)` plus the graded levels Pi reports for the
+selected model. `high` is marked `(recommended)`. Choosing `off` deletes the
+key, and no `reasoning` parameter is sent with the advisor call — distinct from
+`/rpiv-models`' `off (disable reasoning)`, which persists an explicit
+`thinking: "off"`.
+
+`EFFORT_ORDINAL` orders the graded levels lowest → highest; this ordering is what
+`minEffort` compares against.
+
+> **Naming note.** Advisor "effort", Pi's "thinking level", and pi-ai's `reasoning`
+> parameter are the same graded-level concept — the name differs per layer (fixed by
+> on-disk config keys and upstream APIs), but there is no semantic distinction.
 
 ### `disabledForModels`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-advisor",
-	"version": "2.5.2",
+	"version": "2.6.1",
 	"description": "Pi extension. A second opinion the model can request from a stronger reviewer model before it acts.",
 	"keywords": [
 		"pi-package",
@@ -40,12 +40,13 @@
 		"LICENSE"
 	],
 	"pi": {
+		"image": "https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-advisor/docs/cover.png",
 		"extensions": [
 			"./index.ts"
 		]
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^2.5.2",
+		"@juicesharp/rpiv-config": "^2.6.1",
 		"typebox": "^1.1.24"
 	},
 	"peerDependencies": {