pi-freeflow 1.2.1 → 1.3.1

package/README.md

@@ -1,22 +1,20 @@
 # pi-freeflow
 
-> 🌊 **FreeFlow**: Free AI Model Provider for [Oh My Pi (OMP)](https://omp.sh) and [Pi](https://pi.dev) with **Multi-Cloud Rolling Relay** (Cloudflare Workers / Vercel), **Up to 1M Context Windows**, **Auto-Switch Failover**, and **Real-Time Streaming**.
+> 🌊 **FreeFlow** — Thin provider for [Oh My Pi (OMP)](https://omp.sh) & [Pi](https://pi.dev): **model list + relay proxy + log**. The rest (thinking, normalization, provider composition) is handled by the host `pi-ai` system — `pi-freeflow` just provides 23 free models via a multi-cloud rolling relay.
 
 ---
 
-## ✨ Features
-
-- 🆓 **23 Free Models**: Curated access to OpenCode Zen and KiloCode free AI models.
-- 🧠 **Full 1M Context Windows**: Pre-configured with up to 1,048,576 tokens context window and vision (image) support.
-- ⚡ **Real-Time SSE Streaming**: Zero-buffering chunk streaming with instant token delivery.
-- 🛡️ **Multi-Cloud Rolling Egress Relay**:
-  - Support for **Cloudflare Workers**, **Vercel Edge**, and **Deno Deploy**.
-  - **Sticky Active Proxy**: Stays on the healthy proxy without unnecessary round-robin churn.
-  - **Auto-Switch Failover**: Instantly rolls to the next proxy when encountering `HTTP 429` (Rate Limit), `502/503/504`, or Network Timeouts.
-  - **Direct Fallback**: Transparently falls back to direct upstream if all relays are exhausted.
-- 🔇 **Full Quiet Mode**: Clean status bar indicators without intrusive console overlays in the TUI.
-- 📝 **Persistent Background Logging**: Automatic diagnostic logs recorded to `~/.pi/agent/pi-freeflow.log` with 5MB auto-rotation.
-- 🤖 **Sub-Agent Ready**: Seamlessly shared across concurrent parallel sub-agent tasks.
+## ✨ Features — Minimal by Design
+
+`pi-freeflow` is **thin**: **model list + relay proxy + log**. Host `pi-ai`/OMP owns thinking, normalization, and provider composition.
+
+- 📋 **23 Free Models** — `9 OpenCode Zen + 14 Kilo` via host `fetchDynamicModels` (24h cache, disk-only, no subagent live fetch)
+- 🌐 **Dumb Relay Proxy** — `http://127.0.0.1:18080` dumb pipe: `x-relay-target/path` → 7-pool (CF Workers + Vercel Edge) round-robin seamless `429` roll → direct fallback; host already normalized `reasoning_effort`/`thinking`
+- 📝 **Persistent Log** — `~/.pi/agent/pi-freeflow.log` 5MB rotate, `pi-freeflow-debug.json` toggle, `GET /v1/models` pathname-guarded (no `?query` paid leak)
+- 🤖 **Sub-agent Ready** — shared daemon `18080` (or `18081` fallback) reused across parallel subagents; round-robin primary + `willUseRelay` bypass prevents local `127.0.0.1` 429
+- ⚡ **SSE Streaming** — zero-buffer chunk pipe, `thinking_delta` pass-through (host parses)
+
+> **Philosophy:** *model list + relay proxy + log — the rest is Pi.* No `src/normalizer.ts` duplication; `pi-ai` owns `compat.thinkingFormat` (11 variants), `clampThinkingBudgetToAnswerRoom`, `transformMessages`.
 
 ---
 

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "pi-freeflow",
 	"type": "module",
-	"version": "1.2.1",
-	"description": "Multi-cloud rolling fallback relay for OpenCode Zen and KiloCode free models in Oh My Pi (OMP) and Pi",
+	"version": "1.3.1",
+	"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",
 	"keywords": [
@@ -23,6 +23,11 @@
 		"url": "https://github.com/trefeon/pi-freeflow.git"
 	},
 	"homepage": "https://github.com/trefeon/pi-freeflow#readme",
+	"omp": {
+		"extensions": [
+			"./extensions"
+		]
+	},
 	"pi": {
 		"extensions": [
 			"./extensions"

package/src/catalog.ts

@@ -183,73 +183,22 @@ export function writeCatalogCache(data: CatalogCacheData): void {
  * Falls back gracefully to cached or static models if network requests fail.
  */
 export async function refreshCatalog(force = false): Promise<RegisteredModel[]> {
-	if (!force) {
-		const disk = readCatalogCache();
-		if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
+	// Thin provider: no live fetch — subagents must not hit upstream directly
+	// (proxy-only). Host Pi/OMP owns dynamic discovery via fetchDynamicModels (24h).
+	// We only serve disk cache if fresh, otherwise static 23-model aliveCatalog.
+	const disk = readCatalogCache();
+	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;
 			return aliveCatalog;
 		}
-	}
-
-	// 1. Fetch OpenCode Zen models
-	let opencodeList: RegisteredModel[] = [];
-	try {
-		const r = await fetch(`${OPENCODE_API_URL}/models`, {
-			headers: opencodeHeaders(),
-			signal: AbortSignal.timeout(10_000),
-		});
-		if (r.ok) {
-			const d = await r.json();
-			const items: RawModelItem[] = Array.isArray(d?.data) ? d.data : [];
-			const aliveIds = new Set(items.map((m) => m.id));
-			opencodeList = KNOWN_MODELS.filter((m) => aliveIds.has(m.id)).map((m) => ({
-				...m,
-				source: "opencode" as const,
-			}));
-		}
-	} catch (err) {
-		logDebug("OpenCode dynamic model fetch failed, using defaults", { error: String(err) });
-	}
-	if (!opencodeList.length) {
-		opencodeList = KNOWN_MODELS.map((m) => ({ ...m, source: "opencode" as const }));
-	}
-
-	// 2. Fetch KiloCode Gateway models
-	let kiloList: RegisteredModel[] = [];
-	try {
-		const kiloModelsUrl = KILO_CHAT_URL.replace("/chat/completions", "/models");
-		const r = await fetch(kiloModelsUrl, {
-			headers: { Authorization: "Bearer kilo-free" },
-			signal: AbortSignal.timeout(10_000),
-		});
-		if (r.ok) {
-			const d = await r.json();
-			const items: RawModelItem[] = Array.isArray(d?.data) ? d.data : [];
-			const aliveIds = new Set(items.map((m) => m.id));
-			kiloList = KILO_MODELS.filter((m) => aliveIds.has(m.id)).map((m) => ({
-				...m,
-				source: "kilo" as const,
-			}));
+		// Stale cache still better than empty — return it without network
+		if (disk.models.length === 23) {
+			aliveCatalog = disk.models;
+			return aliveCatalog;
 		}
-	} catch (err) {
-		logDebug("KiloCode dynamic model fetch failed, using defaults", { error: String(err) });
 	}
-	if (!kiloList.length) {
-		kiloList = KILO_MODELS.map((m) => ({ ...m, source: "kilo" as const }));
-	}
-
-	const all = [...opencodeList, ...kiloList];
-	aliveCatalog = all;
-
-	// Write rich models to cache atomically
-	const data: CatalogCacheData = {
-		timestamp: Date.now(),
-		opencode: opencodeList.map((m) => m.id),
-		kilo: kiloList.map((m) => m.id),
-		models: all,
-	};
-	writeCatalogCache(data);
-
-	log("info", `Catalog refreshed: ${opencodeList.length} OpenCode + ${kiloList.length} KiloCode free models available`);
-	return all;
+	// No valid cache — return in-memory static 23 (host will refresh if needed)
+	return aliveCatalog;
 }

package/src/config.ts

@@ -53,7 +53,7 @@ export const VERCEL_API = "https://api.vercel.com";
 export const RELAY_MAX_TOKENS = 131_072;
 
 // ── Catalog & Logging constants ─────────────────────────────────────
-export const CATALOG_CACHE_TTL_MS = 3_600_000; // 1 hour
+export const CATALOG_CACHE_TTL_MS = 86_400_000; // 24 hours — delegate to host fetchDynamicModels
 export const LOG_MAX_BYTES = 5 * 1024 * 1024; // 5MB
 export const LOG_MAX_FILES = 3;
 

package/src/index.ts

@@ -44,7 +44,6 @@ export * from "./catalog.ts";
 export * from "./relay-state.ts";
 export * from "./relay.ts";
 export * from "./deploy.ts";
-export * from "./normalizer.ts";
 export * from "./stream-pipe.ts";
 export * from "./proxy.ts";
 export * from "./commands.ts";
@@ -208,6 +207,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	});
 
 	pi.on?.("model_select", async (event, ctx: ExtensionContext) => {
+		const freshRelayState = resolveRelayState();
+		setActiveRelayState(freshRelayState, false);
 		setStatusUi(ctx.ui);
 		let provider: string | undefined;
 		let modelId: string | undefined;

package/src/models.ts

@@ -21,7 +21,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 384_000,
 		input: ["text"],
 		thinkingLevelMap: {
-			off: "low",
+			off: null,
 			minimal: "low",
 			low: "low",
 			medium: "high",
@@ -38,7 +38,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 131_072,
 		input: ["text", "image"],
 		thinkingLevelMap: {
-			off: "low",
+			off: null,
 			minimal: "low",
 			low: "low",
 			medium: "high",
@@ -73,7 +73,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 131_072,
 		input: ["text", "image"],
 		thinkingLevelMap: {
-			off: "low",
+			off: null,
 			minimal: "low",
 			low: "low",
 			medium: "medium",
@@ -90,7 +90,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 128_000,
 		input: ["text"],
 		thinkingLevelMap: {
-			off: "low",
+			off: null,
 			minimal: "low",
 			low: "low",
 			medium: "high",
@@ -107,7 +107,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 128_000,
 		input: ["text"],
 		thinkingLevelMap: {
-			off: "low",
+			off: null,
 			minimal: "low",
 			low: "low",
 			medium: "high",
@@ -124,7 +124,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 262_144,
 		input: ["text"],
 		thinkingLevelMap: {
-			off: "low",
+			off: null,
 			minimal: "low",
 			low: "low",
 			medium: "high",
@@ -141,7 +141,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 32_000,
 		input: ["text"],
 		thinkingLevelMap: {
-			off: "high",
+			off: null,
 			minimal: "high",
 			low: "high",
 			medium: "high",
@@ -158,7 +158,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		maxTokens: 131_072,
 		input: ["text"],
 		thinkingLevelMap: {
-			off: "low",
+			off: null,
 			minimal: "low",
 			low: "low",
 			medium: "high",

package/src/proxy.ts

@@ -24,7 +24,7 @@ import {
 } from "./config.ts";
 import { isDebugEnabled, log } from "./logger.ts";
 import { KILO_MODEL_IDS } from "./models.ts";
-import { normalizeRequestBody } from "./normalizer.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";
@@ -143,10 +143,12 @@ export function startProxy(
 
 		// Serve ONLY our registered free models. Never forward /v1/models to upstream
 		// to prevent paid/proprietary upstream models from leaking into the model picker.
-		if (
-			req.method === "GET" &&
-			(req.url === "/v1/models" || req.url === "/v1/models/")
-		) {
+		// Use pathname check so /v1/models?query variants are also guarded (no leak).
+		let reqPathname: string | null = null;
+		try {
+			reqPathname = new URL(req.url ?? "/", `http://${HOST}`).pathname;
+		} catch {}
+		if (req.method === "GET" && (reqPathname === "/v1/models" || reqPathname === "/v1/models/")) {
 			const alive = getAliveCatalog();
 			const body = JSON.stringify({
 				object: "list",
@@ -207,7 +209,14 @@ export function startProxy(
 			const upstream: Upstream = isKilo ? "kilo" : "opencode";
 			const isStream = parsedBody?.stream === true;
 
-			if (!checkRateLimit(clientIP, upstream)) {
+			// 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)) {
 				res.writeHead(429, { "content-type": "application/json" });
 				res.end(JSON.stringify({ error: "rate limit exceeded" }));
 				return;
@@ -216,7 +225,6 @@ export function startProxy(
 			try {
 				if (isKilo && parsedBody) {
 					const kiloBodyObj = structuredClone(parsedBody);
-					normalizeRequestBody(kiloBodyObj, true, isKilo, reqId);
 					const response = await relayFetch(
 						KILO_CHAT_URL,
 						{
@@ -271,7 +279,6 @@ export function startProxy(
 						try {
 							if (parsedBody) {
 								const relayBodyObj = structuredClone(parsedBody);
-								normalizeRequestBody(relayBodyObj, true, isKilo, reqId);
 								const relayBody = Buffer.from(JSON.stringify(relayBodyObj));
 								const response = await relayFetch(
 									fullUrl,
@@ -327,7 +334,6 @@ export function startProxy(
 					let directBody = Buffer.concat(bodyChunks);
 					if (parsedBody) {
 						const directBodyObj = structuredClone(parsedBody);
-						normalizeRequestBody(directBodyObj, false, isKilo, reqId);
 						directBody = Buffer.from(JSON.stringify(directBodyObj));
 					}
 

package/src/relay-state.ts

@@ -89,8 +89,9 @@ export function resolveRelayState(): RelayState {
 
 // In-memory global relay state
 let activeRelayState: RelayState = resolveRelayState();
+// Monotonic counter to distribute primary relay across concurrent subagents
+let roundRobinCounter = 0;
 let activeStatusUi: ExtensionUIContext | null = null;
-
 /**
  * Mtime of the on-disk state file at the moment we last read or wrote it.
  * Lets worker processes pick up relay-pool changes persisted by another
@@ -113,6 +114,11 @@ lastKnownStateMtimeMs = currentDiskStateMtimeMs();
  * Get active in-memory relay state
  */
 export function getActiveRelayState(): RelayState {
+	const currentMtime = currentDiskStateMtimeMs();
+	if (currentMtime > 0 && currentMtime > lastKnownStateMtimeMs) {
+		activeRelayState = resolveRelayState();
+		lastKnownStateMtimeMs = currentMtime;
+	}
 	return activeRelayState;
 }
 
@@ -174,9 +180,13 @@ export function getOrderedRelayUrls(): string[] {
 		if (activeIdx < 0) {
 			activeIdx = 0;
 		}
+		// Rotate starting point per-request to avoid thundering herd when many
+		// subagents hit the shared 127.0.0.1 daemon at once — each request
+		// tries a different primary relay, but still rolls seamlessly on 429.
+		const startIdx = (activeIdx + (roundRobinCounter++ % activeRelayState.relays.length)) % activeRelayState.relays.length;
 		const ordered: string[] = [];
 		for (let i = 0; i < activeRelayState.relays.length; i++) {
-			const r = activeRelayState.relays[(activeIdx + i) % activeRelayState.relays.length];
+			const r = activeRelayState.relays[(startIdx + i) % activeRelayState.relays.length];
 			if (r?.url?.trim()) {
 				ordered.push(r.url.trim());
 			}

package/src/relay.ts

@@ -24,16 +24,11 @@ import {
 export function isRetriableStatus(status: number): boolean {
 	return (
 		status === 429 ||
+		status === 408 ||
+		status === 500 ||
 		status === 502 ||
 		status === 503 ||
 		status === 504 ||
-		status === 408 ||
-		status === 404 ||
-		status === 410 ||
-		status === 402 ||
-		status === 403 ||
-		status === 500 ||
-		status === 400 ||
 		(status >= 520 && status <= 530)
 	);
 }

package/src/normalizer.ts

@@ -1,173 +0,0 @@
-/**
- * Request payload normalization for pi-freeflow
- *
- * Normalizes tool choice, translates Anthropic thinking to OpenAI reasoning_effort,
- * applies per-model thinkingLevelMap translation, and enforces token clamping.
- */
-
-import { RELAY_MAX_TOKENS } from "./config.ts";
-import { isDebugEnabled, log } from "./logger.ts";
-import { MODEL_MAP } from "./models.ts";
-import type { ModelDef } from "./types.ts";
-
-/**
- * Normalizes an OpenAI-compatible / Anthropic request payload before forwarding to upstream.
- *
- * 1. Strips empty tools and normalizes tool_choice (none -> stripped, other non-auto -> auto for OpenCode).
- * 2. Translates Anthropic thinking ({ type: "enabled", budget_tokens }) to OpenAI reasoning_effort.
- * 3. Applies per-model thinkingLevelMap and reasoning effort normalization.
- * 4. Clamps token limits (min 16 for OpenCode, maxTokens from modelDef, RELAY_MAX_TOKENS for relays).
- */
-export function normalizeRequestBody(
-	body: Record<string, unknown>,
-	isRelay = false,
-	isKilo = false,
-	reqId?: string,
-): Record<string, unknown> {
-	const DBG = isDebugEnabled();
-	const modelId = typeof body.model === "string" ? body.model : "";
-	const modelDef = MODEL_MAP.get(modelId);
-	const isResponsesApi = modelId === "muse-spark-1.2-contributor-free";
-
-	if (DBG) {
-		log(
-			"debug",
-			`normalize: incoming model=${modelId} kilo=${isKilo} relay=${isRelay}`,
-			{
-				reasoning_effort: body.reasoning_effort,
-				reasoning: body.reasoning,
-				thinking: (body as Record<string, unknown>).thinking,
-				tool_choice: body.tool_choice,
-				toolsLen: Array.isArray(body.tools) ? body.tools.length : undefined,
-			},
-			reqId,
-		);
-	}
-
-	// 1. Tool choice & empty tools normalization (pi-ai compat: opencode only supports auto)
-	if (Array.isArray(body.tools) && body.tools.length === 0) {
-		delete body.tools;
-		delete body.tool_choice;
-	}
-	if (body.tool_choice === "none") {
-		delete body.tool_choice;
-		delete body.tools;
-	} else if (!isKilo && body.tool_choice && body.tool_choice !== "auto") {
-		body.tool_choice = "auto";
-	}
-
-	// 1b. Anthropic thinking -> OpenAI reasoning_effort auto-translate
-	// Pi sends anthropic `thinking: {type:"enabled",budget_tokens}` when provider is anthropic.
-	// Our proxy is always openai-completions/responses upstream, so translate.
-	// Ref: pi-ai api/anthropic-messages.js (thinking.type adaptive/enabled/disabled) -> api/openai-completions.js (reasoning_effort)
-	const thinkingRaw = (body as Record<string, unknown>).thinking;
-	if (thinkingRaw && typeof thinkingRaw === "object") {
-		const th = thinkingRaw as Record<string, unknown>;
-		if (th.type === "disabled") {
-			delete (body as Record<string, unknown>).thinking;
-			// Mark as off so downstream reasoning mapping can clear effort
-			if (!body.reasoning_effort && !body.reasoning) {
-				body.reasoning_effort = "off";
-			}
-		} else if (th.type === "enabled" || th.type === "adaptive") {
-			delete (body as Record<string, unknown>).thinking;
-			// Preserve budget as hint if no explicit effort set
-			if (!body.reasoning_effort && typeof th.budget_tokens === "number") {
-				const budget = th.budget_tokens as number;
-				if (budget >= 8000) body.reasoning_effort = "xhigh";
-				else if (budget >= 4000) body.reasoning_effort = "high";
-				else if (budget >= 2000) body.reasoning_effort = "medium";
-				else body.reasoning_effort = "low";
-			}
-		}
-	}
-
-	// 2. Reasoning normalization — per-model thinkingLevelMap aware
-	// Ref: pi-ai api/openai-completions.js (compat.thinkingFormat branches) + api/openai-responses-shared.js
-	const mapEffort = (rawEffort: string): string | null | undefined => {
-		const key = rawEffort.toLowerCase() as keyof NonNullable<
-			ModelDef["thinkingLevelMap"]
-		>;
-		let mapped: string | null | undefined;
-		if (modelDef?.thinkingLevelMap && key in modelDef.thinkingLevelMap) {
-			mapped = modelDef.thinkingLevelMap[key] as string | null;
-		} else if (rawEffort === "xhigh" || rawEffort === "max") {
-			mapped = isResponsesApi
-				? "xhigh"
-				: modelId === "x-preview-f-free"
-					? "max"
-					: "xhigh";
-		} else if (rawEffort === "high" || rawEffort === "medium") {
-			mapped = "high";
-		} else if (rawEffort === "minimal") {
-			mapped = "minimal";
-		} else if (rawEffort === "none" || rawEffort === "off") {
-			mapped = null;
-		} else {
-			mapped = "low";
-		}
-
-		if (isResponsesApi && mapped === "max") {
-			mapped = "xhigh";
-		}
-		return mapped;
-	};
-	if (typeof body.reasoning_effort === "string") {
-		const mapped = mapEffort(body.reasoning_effort);
-		if (mapped === null || mapped === undefined) {
-			delete body.reasoning_effort;
-		} else {
-			body.reasoning_effort = mapped;
-		}
-	}
-	if (body.reasoning && typeof body.reasoning === "object") {
-		const r = body.reasoning as Record<string, unknown>;
-		if (r.effort === "none" || r.effort === "off") {
-			delete r.effort;
-		} else if (typeof r.effort === "string") {
-			const mapped = mapEffort(r.effort);
-			if (mapped === null || mapped === undefined) {
-				delete r.effort;
-			} else {
-				r.effort = mapped;
-			}
-		}
-		if (isResponsesApi && r.effort === "max") r.effort = "xhigh";
-	}
-
-	// 3. Max & Min tokens clamping (model-specific clamp + Vercel relay clamp)
-	const modelMax = modelDef?.maxTokens ?? RELAY_MAX_TOKENS;
-	const clampTokens = (val: number): number => {
-		let clamped = val;
-		if (!isKilo && clamped < 16) clamped = 16;
-		if (clamped > modelMax) clamped = modelMax;
-		if (isRelay && clamped > RELAY_MAX_TOKENS) clamped = RELAY_MAX_TOKENS;
-		return clamped;
-	};
-
-	if (typeof body.max_tokens === "number") {
-		body.max_tokens = clampTokens(body.max_tokens);
-	}
-	if (typeof body.maxTokens === "number") {
-		body.maxTokens = clampTokens(body.maxTokens);
-	}
-	if (typeof body.max_output_tokens === "number") {
-		body.max_output_tokens = clampTokens(body.max_output_tokens);
-	}
-
-	if (DBG) {
-		log(
-			"debug",
-			`normalize: outgoing model=${modelId}`,
-			{
-				reasoning_effort: body.reasoning_effort,
-				reasoning: body.reasoning,
-				max_tokens: body.max_tokens,
-				max_output_tokens: body.max_output_tokens,
-			},
-			reqId,
-		);
-	}
-
-	return body;
-}