pi-freeflow 1.2.0 → 1.2.1

package/package.json

@@ -1,12 +1,20 @@
 {
 	"name": "pi-freeflow",
 	"type": "module",
-	"version": "1.2.0",
-	"description": "Personal multi-cloud rolling fallback relay for OpenCode Zen and KiloCode models in OMP/Pi",
+	"version": "1.2.1",
+	"description": "Multi-cloud rolling fallback relay for OpenCode Zen and KiloCode free models in Oh My Pi (OMP) and Pi",
+	"main": "extensions/index.ts",
+	"types": "src/index.ts",
 	"keywords": [
 		"pi-package",
 		"pi-extension",
-		"free-models"
+		"oh-my-pi",
+		"omp",
+		"free-models",
+		"opencode",
+		"kilocode",
+		"ai-models",
+		"relay"
 	],
 	"author": "trefeon",
 	"license": "MIT",
@@ -22,6 +30,18 @@
 	},
 	"files": [
 		"extensions",
-		"README.md"
-	]
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"test": "node --experimental-strip-types --test test/**/*.test.ts",
+		"typecheck": "tsc --noEmit",
+		"smoke": "node --experimental-strip-types -e \"import('./extensions/index.ts').then(() => console.log('✓ Smoke test passed: extensions/index.ts loaded successfully')).catch(err => { console.error(err); process.exit(1); })\""
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^0.84.3",
+		"@types/node": "^22.13.9",
+		"typescript": "^5.8.2"
+	}
 }

package/src/catalog.ts

@@ -0,0 +1,255 @@
+/**
+ * Dynamic catalog discovery, caching, and model enrichment for pi-freeflow
+ *
+ * Provides 1-hour atomic disk caching with safe offline fallback to verified static definitions.
+ */
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+	CATALOG_CACHE_FILE,
+	CATALOG_CACHE_TTL_MS,
+	KILO_CHAT_URL,
+	OPENCODE_API_URL,
+	opencodeHeaders,
+} from "./config.ts";
+import { log, logDebug, logWarn } from "./logger.ts";
+import {
+	KILO_MODELS,
+	KNOWN_MODELS,
+	MODEL_MAP,
+	OPENCODE_MODELS,
+} from "./models.ts";
+import type {
+	CatalogCacheData,
+	RawModelItem,
+	RegisteredModel,
+	Upstream,
+} from "./types.ts";
+
+/**
+ * In-memory cache of currently active/available free models.
+ * Initialized with all 23 verified models for 0ms instant availability.
+ */
+let aliveCatalog: RegisteredModel[] = [
+	...OPENCODE_MODELS.map((m) => ({ ...m, source: "opencode" as const })),
+	...KILO_MODELS.map((m) => ({ ...m, source: "kilo" as const })),
+];
+/**
+ * Get current in-memory alive catalog
+ */
+export function getAliveCatalog(): RegisteredModel[] {
+	return aliveCatalog;
+}
+
+/**
+ * Set in-memory alive catalog
+ */
+export function setAliveCatalog(catalog: RegisteredModel[]): void {
+	aliveCatalog = catalog;
+}
+
+/**
+ * Format a clean, human-readable display name for any upstream model ID.
+ */
+export function formatCleanDisplayName(id: string, customName?: string): string {
+	if (customName && customName.trim()) {
+		return customName.trim();
+	}
+	const known = MODEL_MAP.get(id);
+	if (known && known.name) {
+		return known.name;
+	}
+
+	// Strip provider prefix ("nvidia/", "stepfun/", "dots-studio/", etc.)
+	let clean = id.replace(/^[a-zA-Z0-9_.-]+\//, "");
+	// Strip variant suffixes
+	clean = clean.replace(/:(free|preview|exacto|default|batch)$/i, "");
+	clean = clean.replace(/-(free|contributor|preview)$/i, "");
+
+	// Capitalize words with acronym preservation
+	const parts = clean.split(/[-_]/).map((w) => {
+		const lower = w.toLowerCase();
+		if (lower === "gpt") return "GPT";
+		if (lower === "ai") return "AI";
+		if (lower === "lfm") return "LFM";
+		if (lower === "hy3") return "Hy3";
+		if (lower === "mimo") return "MiMo";
+		if (lower === "ocr") return "OCR";
+		return w.charAt(0).toUpperCase() + w.slice(1);
+	});
+
+	return parts.join(" ");
+}
+
+/**
+ * Enrich a raw upstream model item into a fully typed RegisteredModel.
+ */
+export function enrichModelDef(raw: RawModelItem, source: Upstream): RegisteredModel {
+	const known = MODEL_MAP.get(raw.id);
+	if (known) {
+		return { ...known, source };
+	}
+
+	const idLower = raw.id.toLowerCase();
+	const hasVision =
+		idLower.includes("vision") ||
+		idLower.includes("vl") ||
+		idLower.includes("omni") ||
+		idLower.includes("note") ||
+		idLower.includes("image");
+	const hasReasoning =
+		idLower.includes("reasoning") ||
+		idLower.includes("r1") ||
+		idLower.includes("o1") ||
+		idLower.includes("think") ||
+		idLower.includes("alpha") ||
+		idLower.includes("spark");
+
+	let contextWindow =
+		typeof raw.context_length === "number" ? raw.context_length : 262_144;
+	if (
+		idLower.includes("1m") ||
+		idLower.includes("ultra") ||
+		idLower.includes("lightning") ||
+		idLower.includes("mimo-v2.5") ||
+		idLower.includes("muse-spark")
+	) {
+		contextWindow = 1_048_576;
+	}
+
+	let maxTokens =
+		typeof raw.max_output_tokens === "number"
+			? raw.max_output_tokens
+			: 65_536;
+	if (idLower.includes("ultra") || idLower.includes("lightning")) {
+		maxTokens = 131_072;
+	}
+
+	const isResponses = raw.id === "muse-spark-1.2-contributor-free";
+
+	return {
+		id: raw.id,
+		name: formatCleanDisplayName(raw.id),
+		source,
+		reasoning: hasReasoning,
+		contextWindow,
+		maxTokens,
+		api: isResponses ? "openai-responses" : undefined,
+		input: hasVision ? ["text", "image"] : ["text"],
+		thinkingFormat: source === "kilo" && hasReasoning ? "openrouter" : undefined,
+	};
+}
+
+/**
+ * Read cached catalog data from disk if valid and unexpired.
+ */
+export function readCatalogCache(): CatalogCacheData | null {
+	try {
+		if (!fs.existsSync(CATALOG_CACHE_FILE)) {
+			return null;
+		}
+		const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
+		const data = JSON.parse(raw) as CatalogCacheData;
+		if (Date.now() - data.timestamp < CATALOG_CACHE_TTL_MS) {
+			return data;
+		}
+	} catch (err) {
+		logDebug("Failed reading catalog cache", { error: String(err) });
+	}
+	return null;
+}
+
+/**
+ * Atomically write catalog cache data to disk using temporary file + rename.
+ */
+export function writeCatalogCache(data: CatalogCacheData): void {
+	try {
+		const dir = path.dirname(CATALOG_CACHE_FILE);
+		if (!fs.existsSync(dir)) {
+			fs.mkdirSync(dir, { recursive: true });
+		}
+		const tmpPath = `${CATALOG_CACHE_FILE}.${randomUUID()}.tmp`;
+		fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf8");
+		fs.renameSync(tmpPath, CATALOG_CACHE_FILE);
+	} catch (err) {
+		logWarn("Could not persist catalog cache to disk", { error: String(err) });
+	}
+}
+
+/**
+ * Refresh free model catalog from OpenCode Zen and KiloCode Gateway endpoints.
+ * 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) {
+			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,
+			}));
+		}
+	} 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;
+}