pi-freeflow 1.9.7 → 1.9.8

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to pi-freeflow. Public, user-visible behavior only.
 
+## 1.9.8 - 2026-09-06
+
+### Fixes
+- **Stale model list heals itself (follow-up to #6).** If your saved model list predates a newly added model, the background refresh now repairs the entry (correct endpoint and details) instead of sending requests to the wrong address — no manual `/freeflow refresh` or cache deletion needed.
+- **Paid models stay out of the picker even from old saved lists.** Every read of the saved model list now drops non-free entries, so models requiring an API key cannot linger after an upgrade.
+- **Old saved lists without a sync marker now re-sync once.** A saved list that could never trigger a network check now performs one plain revalidation (then syncs normally), so newly added free models appear without manual intervention. Missing or corrupt lists still fall back silently with no network call.
+- **Upstream errors are now visible in the proxy log.** Failed upstream responses log their status code and model, and a model routed to the wrong endpoint logs the mismatch with the fix (restart Pi/OMP after upgrade).
+
+### Validation
+- TypeScript typecheck passed cleanly (`tsc --noEmit`).
+- Full test suite passed on Windows (304 tests) and Ubuntu Linux (`acerblue`, 305/305 tests passed), including new regressions for the stale-cache shape from #6.
+- Live sweep of all 26 models through a fresh install on `acerblue`: 23/26 answered on first try (both Muse Spark models via the Responses endpoint); the 3 misses are upstream per-model daily quotas (429), zero server errors.
+
 ## 1.9.7 - 2026-09-06
 
 ### Fixes

package/README.md

@@ -50,6 +50,7 @@ Optimized for deep reasoning, long-horizon coding & autonomous agentic workflows
 | `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal … xhigh` | ❌ |
 | `big-pickle` | Big Pickle | **200K** (200.000) | **32K** (32.000) | `high / max` | ❌ |
 | `ling-3.0-flash-fin-free` | Inclusion AI | **262K** (262.144) | **131K** (131.072) | `minimal … xhigh` | ❌ |
+
 #### KiloCode Gateway (19 Models), OpenRouter Compatible
 Keyless access with `Bearer kilo-free`. Clean slash-free and colon-free CLI aliases supported.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.9.7",
+  "version": "1.9.8",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",

package/src/catalog.ts

@@ -20,7 +20,6 @@ import {
 	ALL_MODELS,
 	KILO_MODEL_IDS,
 	MODEL_MAP,
-	OPENCODE_MODELS,
 } from "./models.ts";
 import type {
 	CatalogCacheData,
@@ -40,6 +39,39 @@ export const DEAD_MODEL_IDS = new Set<string>([
 	"meituan/longcat-2.0-free",
 	"laguna-s-2.1-free",
 ]);
+/**
+ * Free-tier allowlist for anything entering the picker via network or stale disk.
+ * Upstream lists paid models alongside free ones (e.g. claude-fable-5-1,
+ * claude-opus-4-*, gemini-3-*) so a bare upstream merge leaks paid entries that
+ * fail with 401 Missing API key. Known static IDs without a free suffix
+ * (e.g. big-pickle) stay allowed via MODEL_MAP.
+ */
+export function isFreeCatalogId(id: string): boolean {
+	if (typeof id !== "string" || id.length === 0) return false;
+	if (DEAD_MODEL_IDS.has(id)) return false;
+	return id.includes("-free") || id.includes(":free") || id.includes("/free") || MODEL_MAP.has(id);
+}
+/**
+ * Purge paid/dead entries from a catalog list and repair known models against
+ * the static definitions. Stale disk caches predate the paid filter and the
+ * muse-spark-1.3 responses-api entry, so loading them verbatim replays a wrong
+ * api (chat/completions for a responses-only model -> upstream 500) until the
+ * 24h TTL expires. Repairing here self-heals on the next refresh without a
+ * reinstall.
+ */
+export function sanitizeCatalogModels(models: RegisteredModel[]): RegisteredModel[] {
+	const out: RegisteredModel[] = [];
+	for (const m of models) {
+		if (!m || typeof m.id !== "string" || !isFreeCatalogId(m.id)) continue;
+		const known = MODEL_MAP.get(m.id);
+		if (known) {
+			out.push({ ...known, source: m.source ?? (KILO_MODEL_IDS.has(m.id) ? "kilo" : "opencode") });
+		} else {
+			out.push(m);
+		}
+	}
+	return out;
+}
 /**
  * In-memory cache of currently active/available free models.
  * Initialized with all 26 verified models for 0ms instant availability.
@@ -73,11 +105,12 @@ export function mergeCatalog(
 	base: RegisteredModel[],
 	fresh: RegisteredModel[],
 ): RegisteredModel[] {
-	const filteredFresh = fresh.filter((m) => !DEAD_MODEL_IDS.has(m.id));
+	const filteredFresh = fresh.filter((m) => m && typeof m.id === "string" && isFreeCatalogId(m.id));
 	const byId = new Map(base.map((m) => [m.id, m]));
 	for (const m of filteredFresh) byId.set(m.id, m);
-	// Ensure no dead IDs survive even if base was stale
-	return [...byId.values()].filter((m) => !DEAD_MODEL_IDS.has(m.id));
+	// Sanitize the merged result so stale paid entries in a pre-fix base and
+	// stale api fields on known models never survive the merge.
+	return sanitizeCatalogModels([...byId.values()]);
 }
 
 /**
@@ -188,7 +221,7 @@ export function readCatalogCache(): CatalogCacheData | null {
 		if (!Array.isArray(data.models)) {
 			return null;
 		}
-		data.models = data.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
+		data.models = sanitizeCatalogModels(data.models);
 		if (Date.now() - data.timestamp < CATALOG_CACHE_TTL_MS) {
 			return data;
 		}
@@ -250,7 +283,7 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 	if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
 		const age = Date.now() - (disk.timestamp ?? 0);
 		if (!force && age < CATALOG_CACHE_TTL_MS) {
-			aliveCatalog = disk.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
+			aliveCatalog = sanitizeCatalogModels(disk.models);
 			return aliveCatalog;
 		}
 	}
@@ -271,8 +304,12 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 		}
 	}
 
-	// Attempt conditional fetch with If-None-Match when we have an etag
-	if (cachedEtag || force) {
+	// Attempt a fetch whenever there is cache material to revalidate: conditional
+	// with If-None-Match when we have an etag, plain otherwise. A pre-fix cache
+	// file with no etag must still go live (acquiring an etag and discovering
+	// new free models) instead of serving stale indefinitely. Corrupt/missing
+	// caches (staleForEtag null) skip the network and fall through to static.
+	if (cachedEtag || force || staleForEtag) {
 		try {
 			const headers: Record<string, string> = { ...opencodeHeaders() };
 			if (cachedEtag) {
@@ -306,14 +343,7 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 					}
 				}
 				if (rawList.length > 0) {
-					const freeRawList = rawList.filter((r) => {
-						if (!r || typeof r.id !== "string") return false;
-						if (DEAD_MODEL_IDS.has(r.id)) return false;
-						return (
-							r.id.includes("-free") ||
-							OPENCODE_MODELS.some((m) => m.id === r.id)
-						);
-					});
+					const freeRawList = rawList.filter((r) => r && typeof r.id === "string" && isFreeCatalogId(r.id));
 					const fresh = freeRawList.map((r) => enrichModelDef(r, "opencode"));
 					const merged = mergeCatalog(aliveCatalog, fresh);
 					aliveCatalog = merged;
@@ -345,7 +375,7 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 
 	// Stale cache still better than empty — return it without network (filtered)
 	if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
-		const filtered = disk.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
+		const filtered = sanitizeCatalogModels(disk.models);
 		if (filtered.length >= ALL_MODELS.length) {
 			aliveCatalog = filtered;
 			return aliveCatalog;
@@ -357,7 +387,7 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 			const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
 			const stale = JSON.parse(raw) as CatalogCacheData;
 			if (Array.isArray(stale.models) && stale.models.length > 0) {
-				const filtered = stale.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
+				const filtered = sanitizeCatalogModels(stale.models);
 				if (filtered.length >= ALL_MODELS.length) {
 					aliveCatalog = filtered;
 					return aliveCatalog;

package/src/proxy.ts

@@ -30,7 +30,7 @@ import {
 } from "./config.ts";
 
 import { isDebugEnabled, log } from "./logger.ts";
-import { KILO_MODEL_IDS, resolveCanonicalModelId } from "./models.ts";
+import { KILO_MODEL_IDS, MODEL_MAP, resolveCanonicalModelId } from "./models.ts";
 // normalize removed — host pi-ai already normalizes thinking/reasoning before proxy
 import { checkRateLimit } from "./rate-limiter.ts";
 import { relayFetch } from "./relay.ts";
@@ -524,6 +524,16 @@ export function startProxy(
 				return;
 			}
 
+			// Stale-registration guard: responses-only models (muse-spark-*) must
+			// reach upstream via /v1/responses. A chat/completions request for one
+			// means the host still holds a pre-fix provider registration (stale
+			// disk cache or no restart after upgrade) and upstream answers 500.
+			if (!isKilo && typeof parsedBody?.model === "string" && target.pathname.endsWith("/chat/completions")) {
+				const knownDef = MODEL_MAP.get(String(parsedBody.model));
+				if (knownDef?.api === "openai-responses") {
+					log("warn", `model ${String(parsedBody.model)} expects openai-responses but got ${target.pathname} — stale provider registration (restart Pi/OMP after upgrade)`, { model: String(parsedBody.model), path: target.pathname }, reqId);
+				}
+			}
 			try {
 				if (isKilo && parsedBody) {
 					// Header-wait timeout + client-disconnect abort: once headers
@@ -659,6 +669,9 @@ export function startProxy(
 										relayState.url,
 									);
 								} else {
+									if (!response.ok) {
+										log("warn", `upstream ${response.status} for model ${String((parsedBody as Record<string, unknown> | null)?.model ?? "?")} via relay`, { status: response.status, model: (parsedBody as Record<string, unknown> | null)?.model, path: req.url }, reqId);
+									}
 									const data = await response.text();
 									const ct =
 										response.headers.get("content-type") ||
@@ -716,6 +729,9 @@ export function startProxy(
 						clearTimeout(timeoutId);
 						res.off("close", onClientClose);
 						req.off("error", onReqError);
+						if (upstreamRes.status >= 400) {
+							log("warn", `direct upstream ${upstreamRes.status} for model ${String(parsedBody?.model ?? "?")} ${target.pathname}`, { status: upstreamRes.status, model: parsedBody?.model, path: target.pathname }, reqId);
+						}
 
 						const outHeaders: Record<string, string> = {};
 						for (const h of ["content-type", "cache-control", "x-request-id"] as const) {