@diegopetrucci/pi-extensions 0.1.52 → 0.1.53

package/extensions/contrarian/index.ts

@@ -619,6 +619,19 @@ function isTransientErrorMessage(message: string): boolean {
 	return TRANSIENT_ERROR_PATTERN.test(message);
 }
 
+// A model the catalog advertises but the active provider/subscription cannot
+// serve surfaces as a not-found/404-style error (legacy snapshots or
+// access-gated tiers). These are NOT transient: the same model keeps failing,
+// so callers should fall back to a different model instead of retrying it.
+const MODEL_AVAILABILITY_ERROR_PATTERN =
+	/\b(?:404|403|not[_ ]?found(?:[_ ]?error)?|model[_ ]?not[_ ]?found(?:[_ ]?error)?|no such model|unknown model|does not exist|is not available|not available|model[_ ]?not[_ ]?available|unsupported model|invalid model|forbidden|access[ _-]?denied|permission[ _-]?denied|not[ _-]?entitled|do(?:es)? not have access)\b/i;
+
+function isModelAvailabilityError(message: string | undefined): boolean {
+	if (!message) return false;
+	if (isTransientErrorMessage(message)) return false;
+	return MODEL_AVAILABILITY_ERROR_PATTERN.test(message);
+}
+
 function formatContrarianModelError(stopReason: "error" | "aborted", errorMessage: string | undefined): string {
 	const trimmed = errorMessage?.trim();
 	if (stopReason === "aborted") {
@@ -810,10 +823,48 @@ async function findAvailableModel(
 	return undefined;
 }
 
+function toContrarianSelection(
+	model: PiModel,
+	thinkingLevelOverride: ThinkingLevel | undefined,
+	reason: string,
+): ContrarianSelection {
+	const thinking = resolveThinkingLevel(model, thinkingLevelOverride);
+	return {
+		modelRef: `${model.provider}/${model.id}`,
+		provider: model.provider,
+		modelId: model.id,
+		modelName: model.name,
+		thinkingLevel: thinking.effective,
+		...(thinking.clamped ? { requestedThinkingLevel: thinking.requested, thinkingLevelClamped: true } : {}),
+		autoSelected: true,
+		selectionReason: appendThinkingLevelClampReason(reason, thinking),
+	};
+}
+
+function buildSessionFallbackSelection(
+	ctx: { model?: PiModel },
+	thinkingLevelOverride: ThinkingLevel | undefined,
+): ContrarianSelection | undefined {
+	const model = ctx.model;
+	if (!model) return undefined;
+	return toContrarianSelection(
+		model,
+		thinkingLevelOverride,
+		`Used the current session model ${model.provider}/${model.id} as a final fallback.`,
+	);
+}
+
+function withFallbackReason(selection: ContrarianSelection, previous: ContrarianSelection): ContrarianSelection {
+	return {
+		...selection,
+		selectionReason: `${selection.selectionReason} (Fell back from ${previous.modelRef} after a model-availability error.)`,
+	};
+}
+
 async function selectContrarianModel(
 	ctx: { model?: PiModel; modelRegistry: { getAvailable(): PiModel[] | Promise<PiModel[]> } },
 	thinkingLevelOverride?: ThinkingLevel,
-): Promise<{ ok: true; selection: ContrarianSelection } | { ok: false; error: string }> {
+): Promise<{ ok: true; selection: ContrarianSelection; ordered: ContrarianSelection[] } | { ok: false; error: string }> {
 	const available = await ctx.modelRegistry.getAvailable();
 	if (available.length === 0) {
 		return {
@@ -884,29 +935,25 @@ async function selectContrarianModel(
 		reason = "No reasoning models were available, so the top-ranked model across all available providers was used.";
 	}
 
+	const sorted = [...candidates].sort((a, b) => rankModel(b) - rankModel(a));
 	const preferred = providerForPreferences
 		? selectPreferredModel(candidates, providerForPreferences)
 		: selectPreferredAcrossProviders(candidates);
-	const winner = preferred ?? [...candidates].sort((a, b) => rankModel(b) - rankModel(a))[0];
-	const thinking = resolveThinkingLevel(winner, thinkingLevelOverride);
-	const selectionReason = appendThinkingLevelClampReason(
-		preferred ? `Selected ${winner.id} via the hardcoded preference lists while preferring an opposite provider/model family.` : reason,
-		thinking,
+	const orderedModels = preferred ? [preferred, ...sorted.filter((model) => model !== preferred)] : sorted;
+
+	const ordered = orderedModels.map((model, index) =>
+		toContrarianSelection(
+			model,
+			thinkingLevelOverride,
+			index === 0
+				? preferred
+					? `Selected ${model.id} via the hardcoded preference lists while preferring an opposite provider/model family.`
+					: reason
+				: `Auto-selected ${model.provider}/${model.id} as a lower-ranked fallback.`,
+		),
 	);
 
-	return {
-		ok: true,
-		selection: {
-			modelRef: `${winner.provider}/${winner.id}`,
-			provider: winner.provider,
-			modelId: winner.id,
-			modelName: winner.name,
-			thinkingLevel: thinking.effective,
-			...(thinking.clamped ? { requestedThinkingLevel: thinking.requested, thinkingLevelClamped: true } : {}),
-			autoSelected: true,
-			selectionReason,
-		},
-	};
+	return { ok: true, selection: ordered[0], ordered };
 }
 
 function updateContrarianUi(ctx: ExtensionContext, activeRuns: Map<string, ContrarianUiRun>): void {
@@ -1314,7 +1361,16 @@ export default function contrarianExtension(pi: ExtensionAPI) {
 			updateContrarianUi(ctx, activeRuns);
 
 			try {
-				let selection: ContrarianSelection;
+				const attempts: ContrarianSelection[] = [];
+				const seen = new Set<string>();
+				const pushAttempt = (candidate: ContrarianSelection | undefined) => {
+					if (!candidate) return;
+					const key = `${candidate.provider}/${candidate.modelId}`.toLowerCase();
+					if (seen.has(key)) return;
+					seen.add(key);
+					attempts.push(candidate);
+				};
+
 				if (configuredModel) {
 					const modelRef = configuredModel;
 					const matched = await findAvailableModel(ctx, modelRef);
@@ -1333,7 +1389,7 @@ export default function contrarianExtension(pi: ExtensionAPI) {
 						: usedToolOverride
 							? "Used the explicit model override provided in the tool call. The model was not matched against the authenticated model list, so the reasoning level fallback was applied."
 							: "Used the configured default contrarian model. The model was not matched against the authenticated model list, so the reasoning level fallback was applied.";
-					selection = {
+					pushAttempt({
 						modelRef: matched ? `${matched.provider}/${matched.id}` : modelRef,
 						provider,
 						modelId,
@@ -1344,7 +1400,7 @@ export default function contrarianExtension(pi: ExtensionAPI) {
 							: {}),
 						autoSelected: false,
 						selectionReason,
-					};
+					});
 				} else {
 					const selectionResult = await selectContrarianModel(ctx, configuredThinkingLevel);
 					if (!selectionResult.ok) {
@@ -1367,11 +1423,14 @@ export default function contrarianExtension(pi: ExtensionAPI) {
 							},
 						};
 					}
-					selection = selectionResult.selection;
+					for (const candidate of selectionResult.ordered) pushAttempt(candidate);
 				}
 
-				uiRun.selection = selection;
-				updateContrarianUi(ctx, activeRuns);
+				// Keep the known-good session model as a final fallback: the catalog can
+				// advertise models the active provider/subscription cannot actually serve
+				// (legacy snapshots, access-gated tiers), which fail with a not-found/404
+				// error. Falling back lets the run degrade gracefully instead of hard-failing.
+				pushAttempt(buildSessionFallbackSelection(ctx, configuredThinkingLevel));
 
 				const handleUpdate = (partial: { content: Array<{ type: "text"; text: string }>; details: ContrarianDetails }) => {
 					uiRun.preview = partial.content[0]?.text ?? uiRun.preview;
@@ -1379,17 +1438,51 @@ export default function contrarianExtension(pi: ExtensionAPI) {
 					onUpdate?.(partial);
 				};
 
-				const result = await runContrarian(selection, params, signal, handleUpdate, ctx.cwd);
-				if (!result.ok) {
-					return {
-						content: [{ type: "text", text: result.error }],
-						details: result.details,
-					};
+				let lastErrorResult: { ok: false; error: string; details: ContrarianDetails } | undefined;
+				for (let index = 0; index < attempts.length; index++) {
+					const previous = index > 0 ? attempts[index - 1] : undefined;
+					const attempt = previous ? withFallbackReason(attempts[index], previous) : attempts[index];
+					uiRun.selection = attempt;
+					updateContrarianUi(ctx, activeRuns);
+
+					const result = await runContrarian(attempt, params, signal, handleUpdate, ctx.cwd);
+					if (result.ok) {
+						return {
+							content: [{ type: "text", text: result.output }],
+							details: result.details,
+						};
+					}
+
+					lastErrorResult = result;
+					const canFallBack = index < attempts.length - 1 && isModelAvailabilityError(result.error);
+					if (!canFallBack) {
+						return {
+							content: [{ type: "text", text: result.error }],
+							details: result.details,
+						};
+					}
 				}
 
 				return {
-					content: [{ type: "text", text: result.output }],
-					details: result.details,
+					content: [
+						{ type: "text", text: lastErrorResult?.error ?? "Contrarian could not select an available model." },
+					],
+					details:
+						lastErrorResult?.details ?? {
+							modelRef: "",
+							provider: ctx.model?.provider ?? "unknown",
+							modelId: "",
+							modelName: undefined,
+							thinkingLevel: configuredThinkingLevel ?? DEFAULT_THINKING_LEVEL,
+							autoSelected: true,
+							selectionReason: "No authenticated models were available to run the contrarian.",
+							includeBash: params.includeBash ?? false,
+							usage: createEmptyUsage(),
+							stderr: "",
+							exitCode: 1,
+							durationMs: 0,
+							cwd: params.cwd ?? ctx.cwd,
+						},
 				};
 			} finally {
 				activeRuns.delete(toolCallId);

package/extensions/contrarian/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-contrarian",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A read-only contrarian subagent extension for pi that stress-tests plans, designs, assumptions, and conclusions.",
   "keywords": [
     "pi-package",

package/extensions/librarian/index.ts

@@ -477,53 +477,104 @@ async function findAvailableModel(
 	return undefined;
 }
 
-async function selectLibrarianModel(
+// A model the catalog advertises but the active provider/subscription cannot
+// serve surfaces as a not-found/404-style error (legacy snapshots or
+// access-gated tiers). These are NOT transient: the same model keeps failing,
+// so we fall back to the next candidate instead of retrying it.
+const MODEL_AVAILABILITY_ERROR_PATTERN =
+	/\b(?:404|403|not[_ ]?found(?:[_ ]?error)?|model[_ ]?not[_ ]?found(?:[_ ]?error)?|no such model|unknown model|does not exist|is not available|not available|model[_ ]?not[_ ]?available|unsupported model|invalid model|forbidden|access[ _-]?denied|permission[ _-]?denied|not[ _-]?entitled|do(?:es)? not have access)\b/i;
+
+function isModelAvailabilityError(message: string | undefined): boolean {
+	if (!message) return false;
+	return MODEL_AVAILABILITY_ERROR_PATTERN.test(message);
+}
+
+type LibrarianCandidate = { model: any; details: LibrarianModelDetails };
+
+function withLibrarianFallbackReason(candidate: LibrarianCandidate, previous: LibrarianCandidate): LibrarianCandidate {
+	return {
+		model: candidate.model,
+		details: {
+			...candidate.details,
+			selectionReason: `${candidate.details.selectionReason} (Fell back from ${previous.details.modelRef} after a model-availability error.)`,
+		},
+	};
+}
+
+// Build an ordered list of model candidates to try. The catalog can advertise
+// models the active provider/subscription cannot actually serve, so callers run
+// these in order and skip ones that fail with a model-availability error,
+// ultimately falling back to the known-good current session model.
+async function buildLibrarianCandidates(
 	ctx: { model?: any; modelRegistry: { getAvailable(): any[] | Promise<any[]> } },
 	modelPreference: string | undefined,
 	thinkingLevel: ThinkingLevel,
-): Promise<{ model: any; details: LibrarianModelDetails }> {
+): Promise<LibrarianCandidate[]> {
+	const candidates: LibrarianCandidate[] = [];
+	const seen = new Set<string>();
+	const push = (model: any, details: LibrarianModelDetails) => {
+		if (!model) return;
+		const key = `${model.provider}/${model.id}`.toLowerCase();
+		if (seen.has(key)) return;
+		seen.add(key);
+		candidates.push({ model, details });
+	};
+
 	const normalized = modelPreference?.trim();
+	let configuredMatched: any | undefined;
 	if (normalized) {
-		const matched = await findAvailableModel(ctx, normalized);
-		if (matched) {
-			return {
-				model: matched,
-				details: {
-					modelRef: modelRef(matched),
-					provider: matched.provider,
-					modelId: matched.id,
-					thinkingLevel,
-					autoSelected: false,
-					selectionReason: "Using the configured librarian model.",
-				},
-			};
+		configuredMatched = await findAvailableModel(ctx, normalized);
+		if (configuredMatched) {
+			push(configuredMatched, {
+				modelRef: modelRef(configuredMatched),
+				provider: configuredMatched.provider,
+				modelId: configuredMatched.id,
+				thinkingLevel,
+				autoSelected: false,
+				selectionReason: "Using the configured librarian model.",
+			});
 		}
 	}
 
 	const available = await ctx.modelRegistry.getAvailable();
 	const preferred = available.filter(isPreferredFastLibrarianModel);
-	const winner = preferred.length > 0
-		? [...preferred].sort((a, b) => rankPreferredFastLibrarianModel(a) - rankPreferredFastLibrarianModel(b))[0]
-		: [...available].sort((a, b) => rankLibrarianModel(a) - rankLibrarianModel(b))[0];
-	if (!winner) {
-		throw new Error("No authenticated models are available for Librarian. Log in or configure an API key first.");
-	}
+	const ranked = preferred.length > 0
+		? [...preferred].sort((a, b) => rankPreferredFastLibrarianModel(a) - rankPreferredFastLibrarianModel(b))
+		: [...available].sort((a, b) => rankLibrarianModel(a) - rankLibrarianModel(b));
+	const fallbackText = normalized && !configuredMatched
+		? ` Configured model ${normalized} was unavailable, so Librarian fell back to auto-selection.`
+		: "";
+	ranked.forEach((model, index) => {
+		const topReason = preferred.length > 0
+			? `Selected a preferred fast Librarian model.${fallbackText}`
+			: `Selected the cheapest available model because no preferred fast Librarian model was available.${fallbackText}`;
+		push(model, {
+			modelRef: modelRef(model),
+			provider: model.provider,
+			modelId: model.id,
+			thinkingLevel,
+			autoSelected: true,
+			selectionReason: index === 0 ? topReason : `Auto-selected ${modelRef(model)} as a lower-ranked fallback.`,
+		});
+	});
 
-	const fallbackText = normalized ? ` Configured model ${normalized} was unavailable, so Librarian fell back to auto-selection.` : "";
-	const selectionReason = preferred.length > 0
-		? `Selected a preferred fast Librarian model.${fallbackText}`
-		: `Selected the cheapest available model because no preferred fast Librarian model was available.${fallbackText}`;
-	return {
-		model: winner,
-		details: {
-			modelRef: modelRef(winner),
-			provider: winner.provider,
-			modelId: winner.id,
+	// Final fallback: the active session model is known to be servable.
+	if (ctx.model) {
+		push(ctx.model, {
+			modelRef: modelRef(ctx.model),
+			provider: ctx.model.provider,
+			modelId: ctx.model.id,
 			thinkingLevel,
 			autoSelected: true,
-			selectionReason,
-		},
-	};
+			selectionReason: `Used the current session model ${modelRef(ctx.model)} as a final fallback.`,
+		});
+	}
+
+	if (candidates.length === 0) {
+		throw new Error("No authenticated models are available for Librarian. Log in or configure an API key first.");
+	}
+
+	return candidates;
 }
 
 function resolveToolPath(cwd: string, rawPath: string): string {
@@ -944,7 +995,8 @@ export default function librarianExtension(pi: ExtensionAPI) {
 				parseThinkingLevel((params as { thinkingLevel?: unknown }).thinkingLevel) ??
 				explicitModel.thinkingLevel ??
 				thinkingPreference;
-			const selectedModel = await selectLibrarianModel(ctx, explicitModel.model ?? modelPreference, thinkingLevel);
+			const candidates = await buildLibrarianCandidates(ctx, explicitModel.model ?? modelPreference, thinkingLevel);
+			const selectedModel = candidates[0];
 
 			const workspaceBase = path.join(os.tmpdir(), "pi-librarian");
 			await fs.mkdir(workspaceBase, { recursive: true });
@@ -1045,62 +1097,124 @@ export default function librarianExtension(pi: ExtensionAPI) {
 
 				await resourceLoader.reload();
 
-				const created = await createAgentSession({
-					cwd: workspace,
-					modelRegistry: ctx.modelRegistry,
-					resourceLoader,
-					sessionManager: SessionManager.inMemory(workspace),
-					model: selectedModel.model,
-					thinkingLevel,
-					tools: ["read", "bash"],
-				});
+				const runAttempt = async (
+					candidate: LibrarianCandidate,
+				): Promise<{ answer: string; lastAssistant: AssistantLikeMessage | undefined }> => {
+					details.model = candidate.details;
+					details.turns = 0;
+					details.toolCalls = [];
+					emit(true);
+
+					const created = await createAgentSession({
+						cwd: workspace,
+						modelRegistry: ctx.modelRegistry,
+						resourceLoader,
+						sessionManager: SessionManager.inMemory(workspace),
+						model: candidate.model,
+						thinkingLevel,
+						tools: ["read", "bash"],
+					});
 
-				session = created.session as typeof session;
-				unsubscribe = (created.session as any).subscribe((event: any) => {
-					switch (event.type) {
-						case "turn_end":
-							details.turns += 1;
-							emit();
-							break;
-						case "tool_execution_start":
-							details.toolCalls.push({
-								id: event.toolCallId,
-								name: event.toolName,
-								args: event.args,
-								startedAt: Date.now(),
-							});
-							if (details.toolCalls.length > MAX_TOOL_CALLS_TO_KEEP) {
-								details.toolCalls.splice(0, details.toolCalls.length - MAX_TOOL_CALLS_TO_KEEP);
+					session = created.session as typeof session;
+					unsubscribe = (created.session as any).subscribe((event: any) => {
+						switch (event.type) {
+							case "turn_end":
+								details.turns += 1;
+								emit();
+								break;
+							case "tool_execution_start":
+								details.toolCalls.push({
+									id: event.toolCallId,
+									name: event.toolName,
+									args: event.args,
+									startedAt: Date.now(),
+								});
+								if (details.toolCalls.length > MAX_TOOL_CALLS_TO_KEEP) {
+									details.toolCalls.splice(0, details.toolCalls.length - MAX_TOOL_CALLS_TO_KEEP);
+								}
+								emit(true);
+								break;
+							case "tool_execution_end": {
+								const call = details.toolCalls.find((item) => item.id === event.toolCallId);
+								if (call) {
+									call.endedAt = Date.now();
+									call.isError = event.isError;
+								}
+								emit(true);
+								break;
 							}
-							emit(true);
-							break;
-						case "tool_execution_end": {
-							const call = details.toolCalls.find((item) => item.id === event.toolCallId);
-							if (call) {
-								call.endedAt = Date.now();
-								call.isError = event.isError;
-							}
-							emit(true);
-							break;
 						}
+					});
+
+					try {
+						if (!aborted) {
+							const promptPromise = created.session.prompt(buildUserPrompt(query, repos, owners, maxSearchResults, details.cache), {
+								expandPromptTemplates: false,
+							});
+							const timeoutPromise = new Promise<never>((_resolve, reject) => {
+								runTimeout = setTimeout(() => {
+									abort();
+									reject(new Error(`Librarian timed out after ${Math.round(MAX_RUN_MS / 1000)} seconds.`));
+								}, MAX_RUN_MS);
+							});
+							await Promise.race([promptPromise, timeoutPromise]);
+						}
+
+						const lastAssistant = session ? getLastAssistantMessage(session.state.messages) : undefined;
+						const answer = session ? extractLastAssistantText(session.state.messages) : "";
+						return { answer, lastAssistant };
+					} finally {
+						if (runTimeout) {
+							clearTimeout(runTimeout);
+							runTimeout = undefined;
+						}
+						unsubscribe?.();
+						unsubscribe = undefined;
+						session?.dispose();
+						session = undefined;
 					}
-				});
+				};
 
-				if (!aborted) {
-					const promptPromise = created.session.prompt(buildUserPrompt(query, repos, owners, maxSearchResults, details.cache), {
-						expandPromptTemplates: false,
-					});
-					const timeoutPromise = new Promise<never>((_resolve, reject) => {
-						runTimeout = setTimeout(() => {
-							abort();
-							reject(new Error(`Librarian timed out after ${Math.round(MAX_RUN_MS / 1000)} seconds.`));
-						}, MAX_RUN_MS);
-					});
-					await Promise.race([promptPromise, timeoutPromise]);
+				let answer = "";
+				let lastAssistant: AssistantLikeMessage | undefined;
+				let attemptErrorReason: string | undefined;
+				for (let index = 0; index < candidates.length; index++) {
+					if (aborted) break;
+					const candidate =
+						index === 0 ? candidates[index] : withLibrarianFallbackReason(candidates[index], candidates[index - 1]);
+
+					let attempt: { answer: string; lastAssistant: AssistantLikeMessage | undefined };
+					try {
+						attempt = await runAttempt(candidate);
+					} catch (error) {
+						// Let aborts/timeouts propagate to the outer handler.
+						if (aborted || isAbortLikeError(error)) throw error;
+						// Some providers throw (rather than carry the error on the assistant
+						// message) when a model is unavailable; treat that like a
+						// message-carried availability error and fall back to the next model.
+						const message = error instanceof Error ? error.message : String(error);
+						if (index < candidates.length - 1 && isModelAvailabilityError(message)) {
+							answer = "";
+							lastAssistant = undefined;
+							attemptErrorReason = `the internal subagent stopped with an error: ${message}`;
+							continue;
+						}
+						throw error;
+					}
+
+					answer = attempt.answer;
+					lastAssistant = attempt.lastAssistant;
+					if (answer || aborted) break;
+
+					attemptErrorReason = describeNoAnswerReason(lastAssistant, details.turns);
+					const errorMessage =
+						lastAssistant && lastAssistant.stopReason === "error" && typeof lastAssistant.errorMessage === "string"
+							? lastAssistant.errorMessage
+							: undefined;
+					const canFallBack = index < candidates.length - 1 && isModelAvailabilityError(errorMessage);
+					if (!canFallBack) break;
 				}
 
-				const lastAssistant = session ? getLastAssistantMessage(session.state.messages) : undefined;
-				const answer = session ? extractLastAssistantText(session.state.messages) : "";
 				if (answer) {
 					lastContent = answer;
 					details.status = "done";
@@ -1109,7 +1223,7 @@ export default function librarianExtension(pi: ExtensionAPI) {
 					details.status = "aborted";
 				} else {
 					details.status = "error";
-					const reason = describeNoAnswerReason(lastAssistant, details.turns);
+					const reason = attemptErrorReason ?? describeNoAnswerReason(lastAssistant, details.turns);
 					lastContent = formatInternalFailure(details, reason);
 					details.error = reason;
 				}

package/extensions/librarian/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-librarian",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "A pi GitHub research scout with a toggleable local repo checkout cache under the user's OS cache directory.",
   "keywords": [
     "pi-package",

package/extensions/oracle/index.ts

@@ -612,6 +612,19 @@ function isTransientErrorMessage(message: string): boolean {
 	return TRANSIENT_ERROR_PATTERN.test(message);
 }
 
+// A model the catalog advertises but the active provider/subscription cannot
+// serve surfaces as a not-found/404-style error (legacy snapshots or
+// access-gated tiers). These are NOT transient: the same model keeps failing,
+// so callers should fall back to a different model instead of retrying it.
+const MODEL_AVAILABILITY_ERROR_PATTERN =
+	/\b(?:404|403|not[_ ]?found(?:[_ ]?error)?|model[_ ]?not[_ ]?found(?:[_ ]?error)?|no such model|unknown model|does not exist|is not available|not available|model[_ ]?not[_ ]?available|unsupported model|invalid model|forbidden|access[ _-]?denied|permission[ _-]?denied|not[ _-]?entitled|do(?:es)? not have access)\b/i;
+
+function isModelAvailabilityError(message: string | undefined): boolean {
+	if (!message) return false;
+	if (isTransientErrorMessage(message)) return false;
+	return MODEL_AVAILABILITY_ERROR_PATTERN.test(message);
+}
+
 function formatOracleModelError(stopReason: "error" | "aborted", errorMessage: string | undefined): string {
 	const trimmed = errorMessage?.trim();
 	if (stopReason === "aborted") {
@@ -776,10 +789,48 @@ async function findAvailableModel(
 	return undefined;
 }
 
+function toOracleSelection(
+	model: PiModel,
+	thinkingLevelOverride: ThinkingLevel | undefined,
+	reason: string,
+): OracleSelection {
+	const thinking = resolveThinkingLevel(model, thinkingLevelOverride);
+	return {
+		modelRef: `${model.provider}/${model.id}`,
+		provider: model.provider,
+		modelId: model.id,
+		modelName: model.name,
+		thinkingLevel: thinking.effective,
+		...(thinking.clamped ? { requestedThinkingLevel: thinking.requested, thinkingLevelClamped: true } : {}),
+		autoSelected: true,
+		selectionReason: appendThinkingLevelClampReason(reason, thinking),
+	};
+}
+
+function buildSessionFallbackSelection(
+	ctx: { model?: PiModel },
+	thinkingLevelOverride: ThinkingLevel | undefined,
+): OracleSelection | undefined {
+	const model = ctx.model;
+	if (!model) return undefined;
+	return toOracleSelection(
+		model,
+		thinkingLevelOverride,
+		`Used the current session model ${model.provider}/${model.id} as a final fallback.`,
+	);
+}
+
+function withFallbackReason(selection: OracleSelection, previous: OracleSelection): OracleSelection {
+	return {
+		...selection,
+		selectionReason: `${selection.selectionReason} (Fell back from ${previous.modelRef} after a model-availability error.)`,
+	};
+}
+
 async function selectOracleModel(
 	ctx: { model?: PiModel; modelRegistry: { getAvailable(): PiModel[] | Promise<PiModel[]> } },
 	thinkingLevelOverride?: ThinkingLevel,
-): Promise<{ ok: true; selection: OracleSelection } | { ok: false; error: string }> {
+): Promise<{ ok: true; selection: OracleSelection; ordered: OracleSelection[] } | { ok: false; error: string }> {
 	const available = await ctx.modelRegistry.getAvailable();
 	if (available.length === 0) {
 		return {
@@ -810,27 +861,23 @@ async function selectOracleModel(
 		reason = "No reasoning models were available, so the top-ranked model across all available providers was used.";
 	}
 
+	const sorted = [...candidates].sort((a, b) => rankModel(b) - rankModel(a));
 	const preferred = selectPreferredModel(candidates, providerForPreferences);
-	const winner = preferred ?? [...candidates].sort((a, b) => rankModel(b) - rankModel(a))[0];
-	const thinking = resolveThinkingLevel(winner, thinkingLevelOverride);
-	const selectionReason = appendThinkingLevelClampReason(
-		preferred ? `Selected ${winner.id} via the hardcoded preference list for ${winner.provider}.` : reason,
-		thinking,
+	const orderedModels = preferred ? [preferred, ...sorted.filter((model) => model !== preferred)] : sorted;
+
+	const ordered = orderedModels.map((model, index) =>
+		toOracleSelection(
+			model,
+			thinkingLevelOverride,
+			index === 0
+				? preferred
+					? `Selected ${model.id} via the hardcoded preference list for ${model.provider}.`
+					: reason
+				: `Auto-selected ${model.provider}/${model.id} as a lower-ranked fallback.`,
+		),
 	);
 
-	return {
-		ok: true,
-		selection: {
-			modelRef: `${winner.provider}/${winner.id}`,
-			provider: winner.provider,
-			modelId: winner.id,
-			modelName: winner.name,
-			thinkingLevel: thinking.effective,
-			...(thinking.clamped ? { requestedThinkingLevel: thinking.requested, thinkingLevelClamped: true } : {}),
-			autoSelected: true,
-			selectionReason,
-		},
-	};
+	return { ok: true, selection: ordered[0], ordered };
 }
 
 function updateOracleUi(ctx: ExtensionContext, activeRuns: Map<string, OracleUiRun>): void {
@@ -1237,7 +1284,16 @@ export default function oracleExtension(pi: ExtensionAPI) {
 			updateOracleUi(ctx, activeRuns);
 
 			try {
-				let selection: OracleSelection;
+				const attempts: OracleSelection[] = [];
+				const seen = new Set<string>();
+				const pushAttempt = (candidate: OracleSelection | undefined) => {
+					if (!candidate) return;
+					const key = `${candidate.provider}/${candidate.modelId}`.toLowerCase();
+					if (seen.has(key)) return;
+					seen.add(key);
+					attempts.push(candidate);
+				};
+
 				if (configuredModel) {
 					const modelRef = configuredModel;
 					const matched = await findAvailableModel(ctx, modelRef);
@@ -1256,7 +1312,7 @@ export default function oracleExtension(pi: ExtensionAPI) {
 						: usedToolOverride
 							? "Used the explicit model override provided in the tool call. The model was not matched against the authenticated model list, so the reasoning level fallback was applied."
 							: "Used the configured default oracle model. The model was not matched against the authenticated model list, so the reasoning level fallback was applied.";
-					selection = {
+					pushAttempt({
 						modelRef: matched ? `${matched.provider}/${matched.id}` : modelRef,
 						provider,
 						modelId,
@@ -1267,7 +1323,7 @@ export default function oracleExtension(pi: ExtensionAPI) {
 							: {}),
 						autoSelected: false,
 						selectionReason,
-					};
+					});
 				} else {
 					const selectionResult = await selectOracleModel(ctx, configuredThinkingLevel);
 					if (!selectionResult.ok) {
@@ -1290,11 +1346,14 @@ export default function oracleExtension(pi: ExtensionAPI) {
 							},
 						};
 					}
-					selection = selectionResult.selection;
+					for (const candidate of selectionResult.ordered) pushAttempt(candidate);
 				}
 
-				uiRun.selection = selection;
-				updateOracleUi(ctx, activeRuns);
+				// Keep the known-good session model as a final fallback: the catalog can
+				// advertise models the active provider/subscription cannot actually serve
+				// (legacy snapshots, access-gated tiers), which fail with a not-found/404
+				// error. Falling back lets the run degrade gracefully instead of hard-failing.
+				pushAttempt(buildSessionFallbackSelection(ctx, configuredThinkingLevel));
 
 				const handleUpdate = (partial: { content: Array<{ type: "text"; text: string }>; details: OracleDetails }) => {
 					uiRun.preview = partial.content[0]?.text ?? uiRun.preview;
@@ -1302,17 +1361,51 @@ export default function oracleExtension(pi: ExtensionAPI) {
 					onUpdate?.(partial);
 				};
 
-				const result = await runOracle(selection, params, signal, handleUpdate, ctx.cwd);
-				if (!result.ok) {
-					return {
-						content: [{ type: "text", text: result.error }],
-						details: result.details,
-					};
+				let lastErrorResult: { ok: false; error: string; details: OracleDetails } | undefined;
+				for (let index = 0; index < attempts.length; index++) {
+					const previous = index > 0 ? attempts[index - 1] : undefined;
+					const attempt = previous ? withFallbackReason(attempts[index], previous) : attempts[index];
+					uiRun.selection = attempt;
+					updateOracleUi(ctx, activeRuns);
+
+					const result = await runOracle(attempt, params, signal, handleUpdate, ctx.cwd);
+					if (result.ok) {
+						return {
+							content: [{ type: "text", text: result.output }],
+							details: result.details,
+						};
+					}
+
+					lastErrorResult = result;
+					const canFallBack = index < attempts.length - 1 && isModelAvailabilityError(result.error);
+					if (!canFallBack) {
+						return {
+							content: [{ type: "text", text: result.error }],
+							details: result.details,
+						};
+					}
 				}
 
 				return {
-					content: [{ type: "text", text: result.output }],
-					details: result.details,
+					content: [
+						{ type: "text", text: lastErrorResult?.error ?? "Oracle could not select an available model." },
+					],
+					details:
+						lastErrorResult?.details ?? {
+							modelRef: "",
+							provider: ctx.model?.provider ?? "unknown",
+							modelId: "",
+							modelName: undefined,
+							thinkingLevel: configuredThinkingLevel ?? DEFAULT_THINKING_LEVEL,
+							autoSelected: true,
+							selectionReason: "No authenticated models were available to run the oracle.",
+							includeBash: params.includeBash ?? false,
+							usage: createEmptyUsage(),
+							stderr: "",
+							exitCode: 1,
+							durationMs: 0,
+							cwd: params.cwd ?? ctx.cwd,
+						},
 				};
 			} finally {
 				activeRuns.delete(toolCallId);

package/extensions/oracle/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-oracle",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "An Amp-style oracle extension for pi that consults the strongest reasoning model on your current provider.",
   "keywords": [
     "pi-package",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-extensions",
-  "version": "0.1.52",
+  "version": "0.1.53",
   "description": "A collection of pi extensions and skills for annotation UIs, context management, workflow audits, contrarian review, review-comment triage, notifications, brrr push alerts, safety guards, GitHub research, repo-local knowledge, todos, tool rendering, model/provider helpers, and Xiaohei-style article illustrations.",
   "keywords": [
     "pi-package",