pi-freeflow 1.2.0 → 1.3.0

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.3.0",
+	"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",
@@ -15,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"
@@ -22,6 +35,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,204 @@
+/**
+ * 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[]> {
+	// 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;
+		}
+		// Stale cache still better than empty — return it without network
+		if (disk.models.length === 23) {
+			aliveCatalog = disk.models;
+			return aliveCatalog;
+		}
+	}
+	// No valid cache — return in-memory static 23 (host will refresh if needed)
+	return aliveCatalog;
+}

package/src/commands.ts

@@ -0,0 +1,448 @@
+/**
+ * Interactive CLI slash commands and status bar manager for pi-freeflow
+ *
+ * log viewing, debug level configuration, and live catalog refreshing.
+ */
+
+import { refreshCatalog, setAliveCatalog } from "./catalog.ts";
+import { DEBUG_STATE_FILE, DEFAULT_RELAY_URL, LOG_FILE } from "./config.ts";
+import { deployVercelRelay } from "./deploy.ts";
+import {
+	LOG_LEVEL_ORDER,
+	getMinLogLevel,
+	isDebugEnabled,
+	loadDebugState,
+	readRecentLogs,
+	saveDebugState,
+} from "./logger.ts";
+import {
+	ensureRelay,
+	getActiveRelayState,
+	removeRelay,
+	saveRelayState,
+	setActiveRelayState,
+	setStatusUi,
+	shortRelayLabel,
+} from "./relay-state.ts";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ExtensionUIContext,
+	KnownRelay,
+	LogLevel,
+	RegisteredCommand,
+	RegisteredModel,
+	RelayState,
+} from "./types.ts";
+
+/**
+ * Update the TUI status bar widget with active relay state.
+ */
+export function updateStatusBar(ui?: ExtensionUIContext): void {
+	if (!ui) return;
+	const relayState = getActiveRelayState();
+	if (relayState.enabled && relayState.relays.length > 0) {
+		const label = shortRelayLabel(relayState.url);
+		const idx = Math.max(
+			1,
+			relayState.relays.findIndex((r) => r.url === relayState.url) + 1,
+		);
+		const total = relayState.relays.length;
+		ui.setStatus("freeflow", `relay: ON | ${label} ${idx}/${total}`);
+	} else {
+		ui.setStatus("freeflow", undefined);
+	}
+}
+
+export function createCommandSpec(
+	_pi: ExtensionAPI,
+	onCatalogRefreshed?: (models: RegisteredModel[]) => void,
+): Omit<RegisteredCommand, "name"> {
+	return {
+		description:
+			"Relay egress: on | off | status | logs [level] [n] | debug on|off|status | url [URL] | deploy | list | use <URL> | remove <URL> | refresh",
+		getArgumentCompletions: (prefix: string) =>
+			[
+				"on",
+				"off",
+				"status",
+				"url",
+				"deploy",
+				"list",
+				"use",
+				"remove",
+				"refresh",
+				"models",
+				"logs",
+				"debug",
+				"trace",
+			]
+				.filter((s) => s.startsWith(prefix))
+				.map((s) => ({ value: s, label: s })),
+		handler: async (args: string, ctx: ExtensionContext) => {
+			const parts = String(args || "")
+				.trim()
+				.split(/\s+/);
+			const sub = parts[0] || "";
+			const rest = parts.slice(1).join(" ");
+			const relayState = getActiveRelayState();
+
+			const flash = () => {
+				const activeLabel = shortRelayLabel(relayState.url);
+				const activeIdx = Math.max(
+					1,
+					relayState.relays.findIndex((r) => r.url === relayState.url) + 1,
+				);
+				const total = relayState.relays.length || 1;
+				ctx.ui.notify(
+					`Relay ${relayState.enabled ? "ON" : "OFF"}${relayState.enabled ? ` → ${activeLabel} (${activeIdx}/${total})` : " (direct)"} | saved=${relayState.relays.length} (auto-fallback rolling)`,
+					"info",
+				);
+			};
+
+			const persist = () => {
+				saveRelayState(relayState);
+				setStatusUi(ctx.ui);
+				updateStatusBar(ctx.ui);
+			};
+
+			const setRelay = (
+				enabled: boolean,
+				url: string,
+				addLabel?: string,
+			) => {
+				relayState.enabled = enabled;
+				relayState.url = (url || "").trim() || DEFAULT_RELAY_URL;
+				if (relayState.url) {
+					ensureRelay(relayState, relayState.url, addLabel);
+				}
+				setActiveRelayState(relayState);
+			};
+
+			const doDeploy = async () => {
+				const defaultName = `relay-${Date.now().toString(36)}`;
+				const token = (
+					await ctx.ui.input("Vercel API token (vercel-…):", "")
+				)?.trim();
+				if (!token) {
+					ctx.ui.notify("Deploy cancelled — no token", "warning");
+					return;
+				}
+				const name =
+					(
+						await ctx.ui.input(
+							"Project name (empty = auto):",
+							defaultName,
+						)
+					)?.trim() || defaultName;
+
+				ctx.ui.setStatus("freeflow", "deploying relay…");
+				try {
+					const url = await deployVercelRelay(token, name, (m) =>
+						ctx.ui.notify(m, "info"),
+					);
+					setRelay(true, url, `deployed ${name}`);
+					persist();
+					ctx.ui.notify(`✓ Deployed & active: ${url}`, "info");
+				} catch (e) {
+					updateStatusBar(ctx.ui);
+					ctx.ui.notify(
+						`Deploy failed: ${(e as Error).message}`,
+						"error",
+					);
+				}
+			};
+
+			const switchRelay = async () => {
+				if (!relayState.relays.length) {
+					ctx.ui.notify("No saved relays yet", "warning");
+					return;
+				}
+				const fmt = (r: KnownRelay) =>
+					`${r.url === relayState.url ? "★ " : "  "}${r.url}${r.label ? `  (${r.label})` : ""}`;
+				const opts = relayState.relays.map(fmt);
+				const choice = await ctx.ui.select("Switch relay", opts);
+				if (!choice) return;
+				const match = relayState.relays.find((r) => fmt(r) === choice);
+				if (!match) return;
+				setRelay(true, match.url);
+				persist();
+				flash();
+			};
+
+			const showList = () => {
+				if (!relayState.relays.length) {
+					ctx.ui.notify("No saved relays", "info");
+					return;
+				}
+				const lines = relayState.relays.map(
+					(r) =>
+						`${r.url === relayState.url ? "★" : " "} ${r.url}${r.label ? `  [${r.label}]` : ""}`,
+				);
+				ctx.ui.notify(
+					`Saved relays (${relayState.relays.length}):\n${lines.join("\n")}`,
+					"info",
+				);
+			};
+
+			const removeRelayMenu = async () => {
+				const removable = relayState.relays.filter(
+					(r) => r.url !== relayState.url,
+				);
+				if (!removable.length) {
+					ctx.ui.notify(
+						"Nothing to remove — the active relay cannot be removed (switch first)",
+						"warning",
+					);
+					return;
+				}
+				const fmt = (r: KnownRelay) =>
+					`${r.url}${r.label ? `  (${r.label})` : ""}`;
+				const choice = await ctx.ui.select(
+					"Remove relay",
+					removable.map(fmt),
+				);
+				if (!choice) return;
+				const match = removable.find((r) => fmt(r) === choice);
+				if (!match) return;
+				removeRelay(relayState, match.url);
+				persist();
+				ctx.ui.notify(`Removed: ${match.url}`, "info");
+			};
+
+			if (sub === "on") {
+				setRelay(true, relayState.url || DEFAULT_RELAY_URL);
+				persist();
+				flash();
+			} else if (sub === "off") {
+				relayState.enabled = false;
+				setActiveRelayState(relayState);
+				persist();
+				flash();
+			} else if (sub === "status") {
+				flash();
+			} else if (sub === "list") {
+				showList();
+			} else if (sub === "use") {
+				const url = (
+					rest ||
+					(await ctx.ui.input("Relay URL to activate:", "")) ||
+					""
+				).trim();
+				if (!url) {
+					ctx.ui.notify("No URL given", "warning");
+					return;
+				}
+				setRelay(true, url, "manual");
+				persist();
+				flash();
+			} else if (sub === "debug") {
+				const arg = rest.trim().toLowerCase();
+				if (arg === "on" || arg === "enable" || arg === "true") {
+					saveDebugState({ debug: true });
+					ctx.ui.notify(
+						"🔍 Debug ON — verbose trace enabled (level=debug). Logs now include request IDs, thinking sniffing, and payload normalize details.",
+						"info",
+					);
+				} else if (
+					arg === "off" ||
+					arg === "disable" ||
+					arg === "false"
+				) {
+					saveDebugState({ debug: false });
+					ctx.ui.notify(
+						`🔇 Debug OFF — level restored to info. File: ${DEBUG_STATE_FILE}`,
+						"info",
+					);
+				} else if (arg.startsWith("level")) {
+					const lvl = arg.split(/\s+/)[1] as LogLevel | undefined;
+					if (lvl && lvl in LOG_LEVEL_ORDER) {
+						saveDebugState({ debug: false, level: lvl });
+						ctx.ui.notify(
+							`Log level set to ${lvl} (persisted to ${DEBUG_STATE_FILE})`,
+							"info",
+						);
+					} else {
+						ctx.ui.notify(
+							`Unknown level: ${lvl} (use debug/info/warn/error)`,
+							"warning",
+						);
+					}
+				} else {
+					const st = loadDebugState();
+					const cur = st?.debug
+						? "debug (ON)"
+						: st?.level ||
+							process.env.FREEFLOW_LOG_LEVEL ||
+							"info";
+					ctx.ui.notify(
+						`Debug status: ${cur}\nFile: ${DEBUG_STATE_FILE}\nMinLevel: ${getMinLogLevel()} | isDebug=${isDebugEnabled()}\nUsage: /freeflow debug on|off | /freeflow debug level debug`,
+						"info",
+					);
+				}
+			} else if (sub === "logs" || sub === "log" || sub === "trace") {
+				try {
+					const rawRest = rest.trim();
+					let filterLevel: LogLevel | null = null;
+					let filterReqId: string | null = null;
+					let count = 25;
+
+					if (sub === "trace" && rawRest) {
+						filterReqId = rawRest.split(/\s+/)[0];
+					} else if (rawRest) {
+						const tokens = rawRest.split(/\s+/);
+						for (const t of tokens) {
+							const lower = t.toLowerCase();
+							if (lower in LOG_LEVEL_ORDER) {
+								filterLevel = lower as LogLevel;
+							} else if (/^\d+$/.test(t)) {
+								count = Math.min(
+									200,
+									Math.max(5, Number.parseInt(t, 10)),
+								);
+							} else if (
+								/^[a-f0-9]{6,8}$/i.test(t) ||
+								t.startsWith("req=")
+							) {
+								filterReqId = t.replace(/^req=/, "");
+							} else if (lower === "trace" || lower === "req") {
+								continue;
+							} else {
+								filterReqId = t;
+							}
+						}
+					}
+
+					const result = readRecentLogs(
+						filterLevel,
+						filterReqId,
+						count,
+					);
+					if (result.lines.length === 0) {
+						if (result.totalLines === 0) {
+							ctx.ui.notify(
+								"Log file is empty (no logs yet)",
+								"info",
+							);
+						} else {
+							ctx.ui.notify(
+								`No logs matched (level=${filterLevel || "any"} reqId=${filterReqId || "any"} count=${count})`,
+								"warning",
+							);
+						}
+						return;
+					}
+
+					const header = `pi-freeflow logs (last ${result.lines.length}/${result.totalMatched} matched, total ${result.totalLines} lines, file: ${LOG_FILE}${filterLevel ? ` level=${filterLevel}` : ""}${filterReqId ? ` req=${filterReqId}` : ""}):`;
+					ctx.ui.notify(
+						`${header}\n\n${result.lines.join("\n")}`,
+						"info",
+					);
+				} catch (e) {
+					ctx.ui.notify(
+						`Could not read log file: ${(e as Error).message}`,
+						"error",
+					);
+				}
+			} else if (
+				sub === "refresh" ||
+				sub === "reload" ||
+				sub === "models"
+			) {
+				ctx.ui.notify(
+					"Refreshing model catalog from live upstreams…",
+					"info",
+				);
+				const updated = await refreshCatalog(true);
+				setAliveCatalog(updated);
+				persist();
+				onCatalogRefreshed?.(updated);
+				ctx.ui.notify(
+					`✓ Refreshed ${updated.length} models with full-spec metadata!`,
+					"info",
+				);
+			} else if (sub === "remove") {
+				const url = (
+					rest ||
+					(await ctx.ui.input("Relay URL to remove:", "")) ||
+					""
+				).trim();
+				if (!url) {
+					ctx.ui.notify("No URL given", "warning");
+					return;
+				}
+				if (url === relayState.url) {
+					ctx.ui.notify(
+						"Cannot remove the active relay — switch first",
+						"warning",
+					);
+					return;
+				}
+				if (!relayState.relays.some((r) => r.url === url)) {
+					ctx.ui.notify("Not in saved list", "warning");
+					return;
+				}
+				removeRelay(relayState, url);
+				persist();
+				ctx.ui.notify(`Removed: ${url}`, "info");
+			} else if (sub === "url") {
+				const input =
+					rest ||
+					(await ctx.ui.input(
+						"Relay URL (empty = default):",
+						relayState.url || DEFAULT_RELAY_URL,
+					));
+				setRelay(
+					relayState.enabled,
+					(input || "").trim() || DEFAULT_RELAY_URL,
+					"manual",
+				);
+				persist();
+				flash();
+			} else if (sub === "deploy") {
+				await doDeploy();
+			} else {
+				const choice = await ctx.ui.select("freeflow relay", [
+					`Relay: ${relayState.enabled ? "ON" : "OFF"} → ${relayState.url || "direct"}`,
+					"Turn ON",
+					"Turn OFF",
+					"Switch relay…",
+					"Remove relay…",
+					"Set URL",
+					"Deploy Vercel relay…",
+					"List saved relays",
+				]);
+				if (choice === "Turn ON") {
+					setRelay(true, relayState.url || DEFAULT_RELAY_URL);
+					persist();
+					flash();
+				} else if (choice === "Turn OFF") {
+					relayState.enabled = false;
+					setActiveRelayState(relayState);
+					persist();
+					flash();
+				} else if (choice === "Switch relay…") {
+					await switchRelay();
+				} else if (choice === "Remove relay…") {
+					await removeRelayMenu();
+				} else if (choice === "Set URL") {
+					const input = await ctx.ui.input(
+						"Relay URL (empty = default):",
+						relayState.url || DEFAULT_RELAY_URL,
+					);
+					setRelay(
+						relayState.enabled,
+						(input || "").trim() || DEFAULT_RELAY_URL,
+						"manual",
+					);
+					persist();
+					flash();
+				} else if (choice === "Deploy Vercel relay…") {
+					await doDeploy();
+				} else if (choice === "List saved relays") {
+					showList();
+				}
+			}
+		},
+	};
+}