pi-freeflow 1.9.7 → 1.9.9

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to pi-freeflow. Public, user-visible behavior only.
 
+## 1.9.9 - 2026-09-06
+
+### Fixes
+- **Removed our own request cap — sorry, that one was on us.** The proxy used to enforce a built-in request limit and could answer 429 before upstream quota was actually exhausted. That was a bug, not your quota. From this version the proxy never rejects on quota itself: a 429 only surfaces when the upstream — and every relay in your pool — genuinely is rate-limited, and that response now points you at `/freeflow deploy` to add relay egress.
+
+### Validation
+- TypeScript typecheck passed cleanly (`tsc --noEmit`) on Windows and Ubuntu Linux (`acerblue-local`).
+- Full test suite: Windows 302 tests (301 pass + 1 Linux-only skip), `acerblue-local` 302/302 pass, including new regressions locking the guidance hint onto genuine upstream 429s (direct path and exhausted relay pool).
+- Sandboxed stress harness 7/7 on `acerblue-local`; extension smoke load green on both machines.
+
+## 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.
 
@@ -346,7 +347,6 @@ src/
 ├── proxy.ts          # local proxy server (127.0.0.1:28180)
 ├── relay.ts          # relay selection & round-robin
 ├── relay-state.ts    # relay pool state, health tracking
-├── rate-limiter.ts   # in-memory sliding rate limiter (200/day, 200/hour)
 ├── stream-pipe.ts    # SSE stream piping & truncation resilience
 ├── commands.ts       # /freeflow CLI subcommands
 ├── deploy.ts         # guided relay deploy (vercel/cloudflare/deno)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.9.7",
+  "version": "1.9.9",
   "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/config.ts

@@ -7,7 +7,6 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFileSync } from "node:fs";
-import type { Upstream } from "./types.ts";
 
 // Package version — stale-daemon detection in the shared-port reuse path.
 let PKG_VERSION = "0.0.0";
@@ -68,12 +67,6 @@ export const CATALOG_CACHE_TTL_MS = 86_400_000; // 24 hours — delegate to host
 export const LOG_MAX_BYTES = 10 * 1024 * 1024; // 10MB per file
 export const LOG_MAX_FILES = 10; // 10 archived + current ≈ 110MB max (≈100MB per your request, rotated, not single 100MB blob)
 
-// ── Rate Limit Maxima ───────────────────────────────────────────────
-export const RATE_LIMIT_MAX: Record<Upstream, number> = {
-	opencode: 200, // public free quota: requests per UTC day per IP
-	kilo: 200, // documented gateway quota: requests per 1-hour window per IP
-};
-
 // ── Whitelists & Security ───────────────────────────────────────────
 export const ALLOWED_PATH_PATTERN = /^\/v1\/[a-zA-Z0-9/_.,\-?&= %]*$/;
 export const PATH_TRAVERSAL_PATTERN = /\.\./;

package/src/index.ts

@@ -43,7 +43,6 @@ import type {
 export * from "./types.ts";
 export * from "./config.ts";
 export * from "./logger.ts";
-export * from "./rate-limiter.ts";
 export * from "./models.ts";
 export * from "./catalog.ts";
 export * from "./relay-state.ts";

package/src/proxy.ts

@@ -30,13 +30,11 @@ 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";
 import { getActiveRelayState } from "./relay-state.ts";
 import { pipeUpstreamStream } from "./stream-pipe.ts";
-import type { Upstream } from "./types.ts";
 
 
 let shutdownShouldExit = false;
@@ -45,8 +43,9 @@ export function setShutdownShouldExit(v: boolean): void {
 }
 
 /**
- * Direct-mode 429 hint throttle: the guidance hint is emitted at most once per
- * 10 minutes per process so repeated rate-limit responses don't spam clients.
+ * Natural-429 hint throttle: the deploy guidance hint is attached to upstream
+ * 429 passthroughs at most once per 10 minutes per process so repeated
+ * rate-limit responses don't spam clients.
  */
 let last429HintAt = 0;
 function shouldShow429Hint(): boolean {
@@ -58,6 +57,26 @@ function shouldShow429Hint(): boolean {
 /** Test-only: reset 429 hint throttle */
 export function _reset429HintForTest(): void { last429HintAt = 0; }
 
+/** Deploy guidance attached to a natural upstream 429 once the throttle allows. */
+const RATE_LIMIT_HINT =
+	"Shared free-tier IP quota reached. Add your own relay egress: /freeflow deploy (Vercel 1M/mo recommended)";
+
+/**
+ * Attach the deploy hint to a natural upstream 429 JSON body. Anything else —
+ * non-429 statuses, non-JSON bodies — passes through untouched without
+ * consuming the throttle slot.
+ */
+function withRateLimitHint(status: number, data: string): string {
+	if (status !== 429) return data;
+	try {
+		const parsed: unknown = JSON.parse(data);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && shouldShow429Hint()) {
+			return JSON.stringify({ ...(parsed as Record<string, unknown>), hint: RATE_LIMIT_HINT });
+		}
+	} catch {}
+	return data;
+}
+
 /**
  * Extract client IP address from incoming HTTP request.
  */
@@ -504,26 +523,18 @@ export function startProxy(
 				}
 			} catch {}
 
-			const upstream: Upstream = isKilo ? "kilo" : "opencode";
 			const isStream = parsedBody?.stream === true;
 
-			// Seamless sub-agent rate-limit: when relay pool is active, bypass
-			// local per-IP quota (127.0.0.1 shared by all subagents) — upstream
-			// quota is per-egress-IP and relayFetch already rolls on 429 across
-			// 7 candidates until a response succeeds. Without this, parallel
-			// subagents sharing the daemon would hit local 429 before relay failover.
-			const relayPreview = getActiveRelayState();
-			const willUseRelay = relayPreview.enabled && Boolean(relayPreview.url || relayPreview.relays.length > 0);
-			if (!willUseRelay && !checkRateLimit(clientIP, upstream)) {
-				const body: Record<string, unknown> = { error: "rate limit exceeded" };
-				if (shouldShow429Hint()) {
-					body.hint = "Shared free-tier IP quota reached. Add your own relay egress: /freeflow deploy (Vercel 1M/mo recommended)";
+			// 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);
 				}
-				res.writeHead(429, { "content-type": "application/json" });
-				res.end(JSON.stringify(body));
-				return;
 			}
-
 			try {
 				if (isKilo && parsedBody) {
 					// Header-wait timeout + client-disconnect abort: once headers
@@ -583,7 +594,7 @@ export function startProxy(
 							undefined,
 						);
 					} else {
-						const data = await response.text();
+						const data = withRateLimitHint(response.status, await response.text());
 						const ct =
 							response.headers.get("content-type") || "application/json";
 						res.writeHead(response.status, { "content-type": ct });
@@ -659,7 +670,10 @@ export function startProxy(
 										relayState.url,
 									);
 								} else {
-									const data = await response.text();
+									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 = withRateLimitHint(response.status, await response.text());
 									const ct =
 										response.headers.get("content-type") ||
 										"application/json";
@@ -716,6 +730,20 @@ 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);
+						}
+
+						// Natural 429: every relay plus direct is rate-limited — buffer the
+						// JSON error and attach the deploy hint instead of piping it
+						// through as a stream body.
+						if (upstreamRes.status === 429) {
+							const data = withRateLimitHint(429, await upstreamRes.text());
+							const ct429 = upstreamRes.headers.get("content-type") || "application/json";
+							res.writeHead(429, { "content-type": ct429 });
+							res.end(data);
+							return;
+						}
 
 						const outHeaders: Record<string, string> = {};
 						for (const h of ["content-type", "cache-control", "x-request-id"] as const) {

package/src/types.ts

@@ -76,19 +76,6 @@ export interface CatalogCacheData {
 	etag?: string;
 }
 
-export interface RateLimitEntry {
-	count: number;
-	resetAt: number;
-}
-
-export interface RateLimitStatus {
-	allowed: boolean;
-	remaining: number;
-	resetAt: number;
-	limit: number;
-	count: number;
-}
-
 // ── Extension API & UI Types (compatible with @earendil-works/pi-coding-agent) ──
 
 export interface ExtensionUIContext {

package/src/rate-limiter.ts

@@ -1,148 +0,0 @@
-/**
- * Memory-safe sliding rate limiter for pi-freeflow
- * Enforces:
- *  - OpenCode Zen: 200 requests per UTC day per IP
- *  - KiloCode Gateway: 200 requests per 1-hour window per IP
- */
-
-import { RATE_LIMIT_MAX } from "./config.ts";
-import type { RateLimitEntry, RateLimitStatus, Upstream } from "./types.ts";
-
-const rateLimitMap = new Map<string, RateLimitEntry>();
-let lastCleanupAt = 0;
-const CLEANUP_INTERVAL_MS = 60_000; // 1 minute
-const MAX_MAP_SIZE_BEFORE_CLEANUP = 500;
-
-/**
- * Calculate the next reset timestamp in epoch milliseconds.
- */
-export function rateLimitResetAt(upstream: Upstream, now: number): number {
-	if (upstream === "kilo") {
-		return now + 60 * 60_000; // 1 hour sliding window
-	}
-	// OpenCode resets at 00:00:00.000 UTC of next day
-	const nextUtcDay = new Date(now);
-	nextUtcDay.setUTCHours(24, 0, 0, 0);
-	return nextUtcDay.getTime();
-}
-
-/**
- * Construct a cache key for an upstream + client IP.
- */
-export function rateLimitKey(
-	upstream: Upstream,
-	ip: string,
-	now: number = Date.now(),
-): string {
-	const safeIp = ip.trim() || "127.0.0.1";
-	if (upstream === "kilo") {
-		return `kilo:${safeIp}`;
-	}
-	const utcDate = new Date(now).toISOString().slice(0, 10);
-	return `opencode:${utcDate}:${safeIp}`;
-}
-
-/**
- * Purge expired rate limit buckets to guarantee bounded memory usage.
- * Returns the number of evicted entries.
- */
-export function cleanupRateLimits(now: number = Date.now()): number {
-	let evicted = 0;
-	for (const [key, entry] of rateLimitMap.entries()) {
-		if (entry.resetAt <= now) {
-			rateLimitMap.delete(key);
-			evicted++;
-		}
-	}
-	lastCleanupAt = now;
-	return evicted;
-}
-
-/**
- * Trigger cleanup if interval elapsed or map has grown past the high watermark.
- */
-function maybeCleanup(now: number): void {
-	if (
-		now - lastCleanupAt > CLEANUP_INTERVAL_MS ||
-		rateLimitMap.size > MAX_MAP_SIZE_BEFORE_CLEANUP
-	) {
-		cleanupRateLimits(now);
-	}
-}
-
-/**
- * Check and consume a quota token for the given IP and upstream.
- * Returns true if request is permitted, false if rate limit exceeded.
- */
-export function checkRateLimit(
-	ip: string,
-	upstream: Upstream,
-	now: number = Date.now(),
-): boolean {
-	maybeCleanup(now);
-
-	const key = rateLimitKey(upstream, ip, now);
-	const entry = rateLimitMap.get(key);
-	const maxLimit = RATE_LIMIT_MAX[upstream] ?? 200;
-
-	if (!entry || entry.resetAt <= now) {
-		rateLimitMap.set(key, {
-			count: 1,
-			resetAt: rateLimitResetAt(upstream, now),
-		});
-		return true;
-	}
-
-	if (entry.count >= maxLimit) {
-		return false;
-	}
-
-	entry.count++;
-	return true;
-}
-
-/**
- * Query current rate limit quota and remaining requests without mutating count.
- */
-export function getRateLimitStatus(
-	ip: string,
-	upstream: Upstream,
-	now: number = Date.now(),
-): RateLimitStatus {
-	const key = rateLimitKey(upstream, ip, now);
-	const entry = rateLimitMap.get(key);
-	const limit = RATE_LIMIT_MAX[upstream] ?? 200;
-
-	if (!entry || entry.resetAt <= now) {
-		return {
-			allowed: true,
-			remaining: limit,
-			resetAt: rateLimitResetAt(upstream, now),
-			limit,
-			count: 0,
-		};
-	}
-
-	const remaining = Math.max(0, limit - entry.count);
-	return {
-		allowed: remaining > 0,
-		remaining,
-		resetAt: entry.resetAt,
-		limit,
-		count: entry.count,
-	};
-}
-/**
- * Clear all rate limit records (primarily for testing and reset commands).
- */
-export function resetRateLimits(): void {
-	rateLimitMap.clear();
-	lastCleanupAt = Date.now();
-}
-
-/**
- * Get active count of entries in the rate limit table.
- */
-export function getRateLimitMapSize(): number {
-	return rateLimitMap.size;
-}