pi-free 2.2.4 → 2.2.6

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.6] - 2026-07-09
+
+### Changed
+
+- **Faster startup (~30x)** — warm-cache load dropped from ~2.1s to ~70ms: providers now serve from a 1-hour disk cache and fetch live only on cold/stale cache. Extends the cache-first pattern (already used by Cline) to kilo, fastrouter, and all OpenAI-compatible fetchers (tokenrouter, zenmux, crofai, deepinfra, sambanova, together, novita, routeway, bai, openmodel); the dynamic built-in phase runs concurrently with the static providers.
+- **Coding-Index debug logging is now opt-in** — `~/.pi/modelmatch.log` previously received one synchronous `appendFileSync` per model per match attempt at startup. Now off by default; set `PI_FREE_BENCHMARK_DEBUG=1` to re-enable.
+- **Config reads are memoized** — `~/.pi/free.json` is parsed once and reused while its mtime is unchanged.
+
+### Fixed
+
+- **Cache-poisoning guard** — a transient partial API response (a 200 returning a near-empty list) can no longer overwrite a healthy cached model list; fetches returning < 50% of the cached count keep the existing cache.
+
+### Removed
+
+- **Codestral provider** — removed the Codestral provider (`codestral.mistral.ai`). Codestral's free tier is no longer available; use `MISTRAL_API_KEY` with pi's built-in dynamic Mistral provider instead.
+
+## [2.2.5] - 2026-06-28
+
+### Fixed
+
+- **Qoder api2-v2 migration** — Move Qoder to the OpenAI-compatible `https://api2-v2.qoder.sh/model/v1/chat/completions` endpoint, replacing the legacy proxy-style request path. Streaming and non-streaming responses are normalized through the shared stream wrapper, stale legacy model cache entries are ignored, and Qoder now uses the standard basic/all toggle state instead of bespoke toggle logic. The provider avoids logging request bodies or credentials, clamps `max_tokens` to a valid positive value, propagates SSE error payloads, and guards against unbounded SSE buffers. Live validation confirmed the `lite` model works with saved Qoder auth; other account-gated models returned provider quota errors rather than protocol failures ([#285](https://github.com/apmantza/pi-free/pull/285)).
+
+- **OpenCode built-in toggle before registry load** — `/toggle-opencode` and `/toggle-opencode-go` now fall back to direct `/models` discovery with saved OpenCode credentials when Pi's built-in model registry has not populated yet, instead of warning `models not loaded yet. Start a session first.` OpenCode-discovered models preserve the dynamic stream wrapper and are run through `isFreeModel` with the full model set so only `*-free` models are marked free; non-free models no longer appear as free in the picker just because OpenCode's model-list endpoint omits pricing ([#286](https://github.com/apmantza/pi-free/pull/286), [#287](https://github.com/apmantza/pi-free/pull/287)).
+
 ## [2.2.4] - 2026-06-27
 
 ### Added

package/README.md

@@ -74,7 +74,7 @@ First run creates `~/.pi/free.json` automatically. Add keys there or use environ
 | Category | Providers |
 |---|---|
 | ✅ **Free** | Kilo, Cline, OpenRouter, OpenCode, LLM7, OpenModel, TokenRouter (1 free) |
-| 🔄 **Freemium** | Ollama Cloud, SambaNova, Codestral, AgentRouter |
+| 🔄 **Freemium** | Ollama Cloud, SambaNova, AgentRouter |
 | 💳 **Paid** | ZenMux, CrofAI, DeepInfra, Together, Novita, Routeway, b.ai |
 | 🔧 **Dynamic** | Mistral, Groq, Cerebras, xAI, Hugging Face, FastRouter |
 

package/banner.svg

@@ -95,7 +95,7 @@
     <text x="20" y="46" font-family="system-ui, sans-serif" font-size="11" fill="#8b9aaa">Kilo · Cline · OpenCode</text>
     <text x="20" y="66" font-family="system-ui, sans-serif" font-size="11" fill="#a78bfa">OpenModel · AgentRouter</text>
     <text x="20" y="86" font-family="system-ui, sans-serif" font-size="11" fill="#8b9aaa">Ollama Cloud · SambaNova</text>
-    <text x="20" y="106" font-family="system-ui, sans-serif" font-size="11" fill="#8b9aaa">Codestral · LLM7 · Novita</text>
+    <text x="20" y="106" font-family="system-ui, sans-serif" font-size="11" fill="#8b9aaa">LLM7 · Novita</text>
     <text x="20" y="126" font-family="system-ui, sans-serif" font-size="11" fill="#8b9aaa">ZenMux · CrofAI · DeepInfra</text>
     <text x="20" y="146" font-family="system-ui, sans-serif" font-size="11" fill="#8b9aaa">Together · TokenRouter · FastRouter</text>
     <text x="20" y="166" font-family="system-ui, sans-serif" font-size="11" fill="#8b9aaa">+ dynamic (Mistral, Groq, …)</text>

package/config.ts

@@ -9,7 +9,13 @@
  * (e.g. after toggle-{provider}) are visible immediately.
  */
 
-import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+	chmodSync,
+	existsSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 import {
 	PROVIDER_BAI,
@@ -20,11 +26,11 @@ import {
 	PROVIDER_OPENCODE,
 	PROVIDER_OPENMODEL,
 	PROVIDER_OPENROUTER,
+	PROVIDER_QODER,
 	PROVIDER_ROUTEWAY,
 	PROVIDER_TOKENROUTER,
 	PROVIDER_ZENMUX,
 	PROVIDER_CROFAI,
-	PROVIDER_CODESTRAL,
 	PROVIDER_LLM7,
 	PROVIDER_DEEPINFRA,
 	PROVIDER_SAMBANOVA,
@@ -39,6 +45,7 @@ export {
 	PROVIDER_MODAL,
 	PROVIDER_OPENCODE,
 	PROVIDER_OPENROUTER,
+	PROVIDER_QODER,
 	PROVIDER_QWEN,
 	PROVIDER_ROUTEWAY,
 	PROVIDER_TOKENROUTER,
@@ -63,7 +70,6 @@ interface PiFreeConfig {
 	ollama_api_key?: string;
 	zenmux_api_key?: string;
 	crofai_api_key?: string;
-	codestral_api_key?: string;
 	llm7_api_key?: string;
 	deepinfra_api_key?: string;
 	sambanova_api_key?: string;
@@ -84,7 +90,6 @@ interface PiFreeConfig {
 	cline_show_paid?: boolean;
 	zenmux_show_paid?: boolean;
 	crofai_show_paid?: boolean;
-	codestral_show_paid?: boolean;
 	llm7_show_paid?: boolean;
 	deepinfra_show_paid?: boolean;
 	sambanova_show_paid?: boolean;
@@ -97,6 +102,7 @@ interface PiFreeConfig {
 	openmodel_show_paid?: boolean;
 	openrouter_show_paid?: boolean;
 	opencode_show_paid?: boolean;
+	qoder_show_paid?: boolean;
 }
 
 const CONFIG_TEMPLATE: PiFreeConfig = {
@@ -104,7 +110,6 @@ const CONFIG_TEMPLATE: PiFreeConfig = {
 	ollama_api_key: "",
 	zenmux_api_key: "",
 	crofai_api_key: "",
-	codestral_api_key: "",
 	llm7_api_key: "",
 	deepinfra_api_key: "",
 	sambanova_api_key: "",
@@ -126,7 +131,6 @@ const CONFIG_TEMPLATE: PiFreeConfig = {
 	cline_show_paid: false,
 	zenmux_show_paid: false,
 	crofai_show_paid: false,
-	codestral_show_paid: false,
 	llm7_show_paid: false,
 	deepinfra_show_paid: false,
 	sambanova_show_paid: false,
@@ -139,10 +143,19 @@ const CONFIG_TEMPLATE: PiFreeConfig = {
 	openmodel_show_paid: false,
 	openrouter_show_paid: false,
 	opencode_show_paid: false,
+	qoder_show_paid: false,
 };
 
 const CONFIG_PATH = join(PI_DATA_DIR, "free.json");
 
+// Memoize the parsed config: re-read+parse only when the file's mtime changes.
+// loadConfigFile() is called on every config getter (dozens of times at
+// startup); this avoids repeated readFileSync + JSON.parse of the same file.
+// Every write path uses writeFileSync (which bumps mtime), so the mtime check
+// auto-invalidates after saveConfig()/updateConfig()/ensureConfigFile().
+let cachedConfig: PiFreeConfig | null = null;
+let cachedConfigMtime = -1;
+
 function ensureConfigFile(): void {
 	try {
 		ensureDir(PI_DATA_DIR);
@@ -209,17 +222,44 @@ function restrictConfigFilePermissions(): void {
 }
 
 export function loadConfigFile(): PiFreeConfig {
+	// Return the memoized parse when the file hasn't changed on disk.
+	// Use a single stat result for both the hit check and the cached mtime to
+	// reduce the TOCTOU window between the check and the read.
+	let mtime: number | undefined;
+	try {
+		mtime = statSync(CONFIG_PATH).mtimeMs;
+		if (cachedConfig !== null && mtime === cachedConfigMtime) {
+			// Return a frozen copy so callers cannot mutate the shared cache.
+			return Object.freeze(cachedConfig) as PiFreeConfig;
+		}
+	} catch {
+		// stat failed (e.g. file removed) — fall through to read+parse below
+		cachedConfig = null;
+	}
+
 	try {
-		return JSON.parse(
+		const parsed = JSON.parse(
 			readFileSync(CONFIG_PATH, "utf8"),
 			safeJsonReviver,
 		) as PiFreeConfig;
+		cachedConfig = parsed;
+		cachedConfigMtime = mtime ?? -1;
+		return Object.freeze(parsed) as PiFreeConfig;
 	} catch (err) {
-		_logger.error("Could not parse config file — returning empty config", {
-			path: CONFIG_PATH,
-			error: err instanceof Error ? err.message : String(err),
-		});
-		return {};
+		cachedConfig = null;
+		cachedConfigMtime = -1;
+		if (err instanceof SyntaxError) {
+			_logger.error("Config file is corrupt (invalid JSON) — returning empty config", {
+				path: CONFIG_PATH,
+				error: err.message,
+			});
+		} else {
+			_logger.error("Could not read config file — returning empty config", {
+				path: CONFIG_PATH,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+		return Object.freeze({}) as PiFreeConfig;
 	}
 }
 
@@ -230,7 +270,11 @@ export function loadConfigFile(): PiFreeConfig {
 function readRawConfigFile(): string | undefined {
 	try {
 		return readFileSync(CONFIG_PATH, "utf8");
-	} catch {
+	} catch (err) {
+		_logger.warn("Could not read config file", {
+			path: CONFIG_PATH,
+			error: err instanceof Error ? err.message : String(err),
+		});
 		return undefined;
 	}
 }
@@ -271,11 +315,6 @@ const PROVIDER_META: readonly ProviderMeta[] = [
 	{ id: PROVIDER_CLINE, prefix: "CLINE", showPaidKey: "cline_show_paid" },
 	{ id: PROVIDER_ZENMUX, prefix: "ZENMUX", showPaidKey: "zenmux_show_paid" },
 	{ id: PROVIDER_CROFAI, prefix: "CROFAI", showPaidKey: "crofai_show_paid" },
-	{
-		id: PROVIDER_CODESTRAL,
-		prefix: "CODESTRAL",
-		showPaidKey: "codestral_show_paid",
-	},
 	{ id: PROVIDER_LLM7, prefix: "LLM7", showPaidKey: "llm7_show_paid" },
 	{
 		id: PROVIDER_DEEPINFRA,
@@ -325,6 +364,7 @@ const PROVIDER_META: readonly ProviderMeta[] = [
 		prefix: "OPENCODE",
 		showPaidKey: "opencode_show_paid",
 	},
+	{ id: PROVIDER_QODER, prefix: "QODER", showPaidKey: "qoder_show_paid" },
 ];
 
 const PROVIDER_META_BY_ID = new Map(PROVIDER_META.map((m) => [m.id, m]));
@@ -364,13 +404,6 @@ export function getCrofaiShowPaid(): boolean {
 	return resolveBool("CROFAI_SHOW_PAID", loadConfigFile().crofai_show_paid);
 }
 
-export function getCodestralShowPaid(): boolean {
-	return resolveBool(
-		"CODESTRAL_SHOW_PAID",
-		loadConfigFile().codestral_show_paid,
-	);
-}
-
 export function getLlm7ShowPaid(): boolean {
 	return resolveBool("LLM7_SHOW_PAID", loadConfigFile().llm7_show_paid);
 }
@@ -473,10 +506,6 @@ export function getCrofaiApiKey(): string | undefined {
 	return resolve("CROFAI_API_KEY", loadConfigFile().crofai_api_key);
 }
 
-export function getCodestralApiKey(): string | undefined {
-	return resolve("CODESTRAL_API_KEY", loadConfigFile().codestral_api_key);
-}
-
 export function getLlm7ApiKey(): string | undefined {
 	return resolve("LLM7_API_KEY", loadConfigFile().llm7_api_key);
 }

package/constants.ts

@@ -16,7 +16,6 @@ export const PROVIDER_QWEN = "qwen";
 export const PROVIDER_MODAL = "modal";
 export const PROVIDER_ZENMUX = "zenmux";
 export const PROVIDER_CROFAI = "crofai";
-export const PROVIDER_CODESTRAL = "codestral";
 export const PROVIDER_LLM7 = "llm7";
 export const PROVIDER_DEEPINFRA = "deepinfra";
 export const PROVIDER_SAMBANOVA = "sambanova";
@@ -42,7 +41,6 @@ export const ALL_UNIQUE_PROVIDERS = [
 	PROVIDER_OLLAMA,
 	PROVIDER_ZENMUX,
 	PROVIDER_CROFAI,
-	PROVIDER_CODESTRAL,
 	PROVIDER_LLM7,
 	PROVIDER_DEEPINFRA,
 	PROVIDER_SAMBANOVA,
@@ -68,7 +66,6 @@ export const BASE_URL_QWEN =
 	"https://dashscope.aliyuncs.com/compatible-mode/v1";
 export const BASE_URL_ZENMUX = "https://zenmux.ai/api/v1";
 export const BASE_URL_CROFAI = "https://crof.ai/v1";
-export const BASE_URL_CODESTRAL = "https://codestral.mistral.ai/v1";
 export const BASE_URL_LLM7 = "https://api.llm7.io/v1";
 export const BASE_URL_DEEPINFRA = "https://api.deepinfra.com/v1/openai";
 export const BASE_URL_SAMBANOVA = "https://api.sambanova.ai/v1";
@@ -83,7 +80,7 @@ export const BASE_URL_BAI = "https://api.b.ai/v1";
  * NOT include `/v1`. See {@link PROVIDER_OPENMODEL}.
  */
 export const BASE_URL_OPENMODEL = "https://api.openmodel.ai";
-export const BASE_URL_QODER = "https://api3.qoder.sh";
+export const BASE_URL_QODER = "https://api2-v2.qoder.sh";
 
 /** Cline fetches free models from OpenRouter */
 export const BASE_URL_OPENROUTER = "https://openrouter.ai/api/v1";

package/index.ts

@@ -31,7 +31,6 @@ import {
 } from "./lib/registry.ts";
 // Import unique provider extensions (only providers NOT built into pi)
 import cline from "./providers/cline/cline.ts";
-import codestral from "./providers/codestral/codestral.ts";
 import crofai from "./providers/crofai/crofai.ts";
 import kilo from "./providers/kilo/kilo.ts";
 import llm7 from "./providers/llm7/llm7.ts";
@@ -61,7 +60,6 @@ const UNIQUE_PROVIDERS: ReadonlyArray<(pi: ExtensionAPI) => Promise<void>> = [
 	cline,
 	zenmux,
 	crofai,
-	codestral,
 	llm7,
 	deepinfra,
 	sambanova,
@@ -386,28 +384,36 @@ export default async function piFreeEntry(pi: ExtensionAPI) {
 	// Setup model telemetry (tracks real-world performance)
 	setupTelemetry(pi);
 
-	// Load all unique providers
-	// Each provider will register itself with the global toggle system
-	await Promise.allSettled(UNIQUE_PROVIDERS.map((setup) => setup(pi)));
-
-	// Setup dynamic built-in providers (Mistral, Groq, Cerebras, xAI, Hugging Face,
-	// OpenRouter/OpenCode from Pi auth, and FastRouter public model discovery)
-	try {
-		const { setupDynamicBuiltInProviders } = await import(
-			"./providers/dynamic-built-in/index.ts"
-		);
-		await setupDynamicBuiltInProviders(pi);
-	} catch (err) {
-		// Dynamic providers are a best-effort enhancement — if the import
-		// or init fails (e.g. upstream API change), continue with the
-		// already-registered static providers rather than failing the whole
-		// extension load. Log full error (message + stack) to the structured
-		// log so the user can investigate, but never block startup.
-		_logger.error("[pi-free] Dynamic built-in providers failed to load", {
-			error: err instanceof Error ? err.message : String(err),
-			stack: err instanceof Error ? err.stack : undefined,
-		});
-	}
+	// Load all unique providers + dynamic built-in providers CONCURRENTLY.
+	// Running the dynamic phase (e.g. FastRouter) in parallel with the static
+	// providers avoids serializing two independent network windows at startup.
+	// Each provider registers itself with the global toggle system.
+	const dynamicSetup = (async () => {
+		try {
+			const { setupDynamicBuiltInProviders } = await import(
+				"./providers/dynamic-built-in/index.ts"
+			);
+			await setupDynamicBuiltInProviders(pi);
+		} catch (err) {
+			// Dynamic providers are a best-effort enhancement — if the import
+			// or init fails (e.g. upstream API change), continue with the
+			// already-registered static providers rather than failing the whole
+			// extension load. Log full error (message + stack) to the structured
+			// log so the user can investigate, but never block startup.
+			_logger.error(
+				"[pi-free] Dynamic built-in providers failed to load",
+				{
+					error: err instanceof Error ? err.message : String(err),
+					stack: err instanceof Error ? err.stack : undefined,
+				},
+			);
+		}
+	})();
+
+	await Promise.allSettled([
+		...UNIQUE_PROVIDERS.map((setup) => setup(pi)),
+		dynamicSetup,
+	]);
 
 	// Setup toggles for pi's built-in providers (e.g., OpenCode)
 	setupBuiltInProviderToggles(pi);

package/lib/built-in-toggle.ts

@@ -16,7 +16,12 @@ import type {
 	ExtensionAPI,
 	ProviderModelConfig,
 } from "@earendil-works/pi-coding-agent";
-import { getOpencodeShowPaid, getOpenrouterShowPaid } from "../config.ts";
+import {
+	getOpencodeApiKey,
+	getOpencodeShowPaid,
+	getOpenrouterApiKey,
+	getOpenrouterShowPaid,
+} from "../config.ts";
 import { createLogger } from "./logger.ts";
 import {
 	getProviderRegistry,
@@ -25,6 +30,7 @@ import {
 } from "./registry.ts";
 import { wrapSessionStartHandler } from "./session-start-metrics.ts";
 import { createToggleState } from "./toggle-state.ts";
+import { fetchWithTimeout } from "./util.ts";
 import {
 	OPENCODE_DYNAMIC_API,
 	createOpenCodeSessionTracker,
@@ -53,12 +59,33 @@ function getOpenCodeSession() {
 interface BuiltInToggleConfig {
 	id: string;
 	getShowPaid: () => boolean;
+	baseUrl: string;
+	api: Api;
+	getApiKey: () => string | undefined;
 }
 
 const BUILT_IN_TOGGLE_PROVIDERS: BuiltInToggleConfig[] = [
-	{ id: "opencode", getShowPaid: getOpencodeShowPaid },
-	{ id: "opencode-go", getShowPaid: getOpencodeShowPaid },
-	{ id: "openrouter", getShowPaid: getOpenrouterShowPaid },
+	{
+		id: "opencode",
+		getShowPaid: getOpencodeShowPaid,
+		baseUrl: "https://opencode.ai/zen/v1",
+		api: OPENCODE_DYNAMIC_API,
+		getApiKey: getOpencodeApiKey,
+	},
+	{
+		id: "opencode-go",
+		getShowPaid: getOpencodeShowPaid,
+		baseUrl: "https://opencode.ai/zen/go/v1",
+		api: OPENCODE_DYNAMIC_API,
+		getApiKey: getOpencodeApiKey,
+	},
+	{
+		id: "openrouter",
+		getShowPaid: getOpenrouterShowPaid,
+		baseUrl: "https://openrouter.ai/api/v1",
+		api: "openai-completions",
+		getApiKey: getOpenrouterApiKey,
+	},
 ];
 
 // =============================================================================
@@ -74,6 +101,24 @@ interface BuiltInProviderState {
 const providerStates = new Map<string, BuiltInProviderState>();
 let commandsRegistered = false;
 
+const ZERO_COST = Object.freeze({
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0,
+});
+
+// OpenCode's /models endpoint does not expose real pricing. Use a tiny
+// non-zero sentinel for known non-free models so the model picker does not
+// label every OpenCode model as free. Authoritative free detection still uses
+// _freeKnown/_isFree, not the sentinel amount.
+const UNKNOWN_PAID_COST = Object.freeze({
+	input: 0.000001,
+	output: 0.000001,
+	cacheRead: 0,
+	cacheWrite: 0,
+});
+
 // =============================================================================
 // Setup
 // =============================================================================
@@ -138,18 +183,87 @@ function tryCaptureProvider(
 	const allModels = providerModels.map((m: Model<Api>) =>
 		modelToProviderConfig(m, config.id),
 	);
+
+	return createProviderState(pi, config, {
+		allModels,
+		baseUrl: providerModels[0].baseUrl,
+		api: providerModels[0].api,
+		apiKey: getApiKeyEnvForProvider(config.id),
+		source: "captured",
+	});
+}
+
+async function tryDiscoverProvider(
+	pi: ExtensionAPI,
+	config: BuiltInToggleConfig,
+): Promise<BuiltInProviderState | undefined> {
+	const apiKey = config.getApiKey();
+	if (!apiKey) return undefined;
+
+	try {
+		const response = await fetchWithTimeout(
+			`${config.baseUrl}/models`,
+			{
+				headers: {
+					Accept: "application/json",
+					Authorization: `Bearer ${apiKey}`,
+				},
+			},
+			30_000,
+		);
+
+		if (!response.ok) {
+			throw new Error(`HTTP ${response.status} ${response.statusText}`);
+		}
+
+		const body = (await response.json()) as
+			| Array<Record<string, unknown>>
+			| { data?: Array<Record<string, unknown>> };
+		const rawModels = Array.isArray(body) ? body : (body.data ?? []);
+		const mappedModels = rawModels
+			.map((m) => rawModelToProviderConfig(m, config))
+			.filter((m): m is ProviderModelConfig & { _pricingKnown?: boolean } =>
+				m !== undefined,
+			);
+		const allModels = applyAuthoritativeFreeFlags(mappedModels, config.id);
+
+		if (allModels.length === 0) return undefined;
+
+		return createProviderState(pi, config, {
+			allModels,
+			baseUrl: config.baseUrl,
+			api: config.api,
+			apiKey,
+			source: "discovered",
+		});
+	} catch (err) {
+		_logger.warn(`[built-in-toggle] ${config.id}: on-demand discovery failed`, {
+			error: err instanceof Error ? err.message : String(err),
+		});
+		return undefined;
+	}
+}
+
+function createProviderState(
+	pi: ExtensionAPI,
+	config: BuiltInToggleConfig,
+	options: {
+		allModels: ProviderModelConfig[];
+		baseUrl: string;
+		api: Api;
+		apiKey: string;
+		source: "captured" | "discovered";
+	},
+): BuiltInProviderState {
+	const { allModels, baseUrl, api, apiKey, source } = options;
 	const freeModels = allModels.filter((m: ProviderModelConfig) =>
 		isFreeModel({ ...m, provider: config.id }, allModels),
 	);
 
-	const baseUrl = providerModels[0].baseUrl;
-	const api = providerModels[0].api;
-	const apiKeyEnv = getApiKeyEnvForProvider(config.id);
-
 	const reRegister = (models: ProviderModelConfig[]) => {
 		pi.registerProvider(config.id, {
 			baseUrl,
-			apiKey: apiKeyEnv,
+			apiKey,
 			api: isOpenCodeProvider(config.id) ? OPENCODE_DYNAMIC_API : api,
 			...(isOpenCodeProvider(config.id)
 				? { streamSimple: createOpenCodeStreamSimple(getOpenCodeSession()) }
@@ -171,7 +285,7 @@ function tryCaptureProvider(
 	registerWithGlobalToggle(config.id, stored, reRegister, true);
 
 	_logger.info(
-		`[built-in-toggle] ${config.id}: captured ${allModels.length} models (${freeModels.length} free)`,
+		`[built-in-toggle] ${config.id}: ${source} ${allModels.length} models (${freeModels.length} free)`,
 	);
 
 	return state;
@@ -191,15 +305,21 @@ function registerToggleCommand(
 		handler: async (_args, ctx) => {
 			let state = providerStates.get(config.id);
 			if (!state) {
-				// Models may have loaded after session_start — try on-demand capture
+				// Models may have loaded after session_start — try on-demand capture.
 				state = tryCaptureProvider(pi, config, ctx);
-				if (!state) {
-					ctx.ui.notify(
-						`${config.id}: models not loaded yet. Start a session first.`,
-						"warning",
-					);
-					return;
-				}
+			}
+			if (!state) {
+				// If Pi has not exposed built-in models yet, fetch the provider's
+				// /models endpoint directly so /toggle-opencode works before the
+				// first chat session has populated the model registry.
+				state = await tryDiscoverProvider(pi, config);
+			}
+			if (!state) {
+				ctx.ui.notify(
+					`${config.id}: models not loaded yet and on-demand discovery failed. Check your API key, then try again.`,
+					"warning",
+				);
+				return;
 			}
 
 			const applied = state.toggleState.toggle(state.reRegister);
@@ -249,6 +369,53 @@ function modelToProviderConfig(
 	return base;
 }
 
+function rawModelToProviderConfig(
+	m: Record<string, unknown>,
+	config: BuiltInToggleConfig,
+): (ProviderModelConfig & { _pricingKnown?: boolean }) | undefined {
+	const id = String(m.id ?? "").trim();
+	if (!id) return undefined;
+	const inputModalities = Array.isArray(m.input_modalities)
+		? m.input_modalities
+		: undefined;
+	const supportsImage = inputModalities?.includes("image") === true;
+	return {
+		id,
+		name: String(m.name ?? m.model ?? id),
+		api: isOpenCodeProvider(config.id) ? OPENCODE_DYNAMIC_API : config.api,
+		reasoning: Boolean(m.reasoning ?? false),
+		input: supportsImage ? ["text", "image"] : ["text"],
+		cost: ZERO_COST,
+		contextWindow:
+			((m.context_length ??
+				m.max_context_length ??
+				m.context_window) as number) ?? 128_000,
+		maxTokens: ((m.max_tokens ?? m.max_completion_tokens) as number) ?? 16_384,
+		_pricingKnown: false,
+	};
+}
+
+function applyAuthoritativeFreeFlags(
+	models: Array<ProviderModelConfig & { _pricingKnown?: boolean }>,
+	providerId: string,
+): Array<
+	ProviderModelConfig & {
+		_pricingKnown?: boolean;
+		_freeKnown?: boolean;
+		_isFree?: boolean;
+	}
+> {
+	return models.map((model) => {
+		const isFree = isFreeModel({ ...model, provider: providerId }, models);
+		return {
+			...model,
+			cost: isFree ? ZERO_COST : UNKNOWN_PAID_COST,
+			_freeKnown: true,
+			_isFree: isFree,
+		};
+	});
+}
+
 function getApiKeyEnvForProvider(providerId: string): string {
 	const envMap: Record<string, string> = {
 		opencode: "$OPENCODE_API_KEY",

package/lib/provider-cache.ts

@@ -128,6 +128,28 @@ export async function saveProviderCache(
 	_logger.debug(`Saved ${models.length} models to cache for ${providerId}`);
 }
 
+/**
+ * Persist models to the cache, but refuse to overwrite a healthy existing
+ * entry with a drastically smaller list (a transient partial/error response).
+ * Also never caches an empty list. Returns true when the cache was written.
+ */
+export async function saveProviderCacheGuarded(
+	providerId: string,
+	models: ProviderModelConfig[],
+): Promise<boolean> {
+	if (!models || models.length === 0) return false;
+	const existing = getProviderCacheEntry(providerId);
+	const existingCount = existing?.models.length ?? 0;
+	if (existingCount > 0 && models.length < existingCount * 0.5) {
+		_logger.debug(
+			`Not caching ${providerId}: ${models.length} models vs ${existingCount} cached (likely transient shrink)`,
+		);
+		return false;
+	}
+	await saveProviderCache(providerId, models);
+	return true;
+}
+
 /**
  * Clear cached models for a provider.
  */