pi-freeflow 1.4.11 → 1.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.4.11",
+  "version": "1.5.0",
   "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",
@@ -45,11 +45,19 @@
   "scripts": {
     "test": "node --experimental-strip-types --test --test-concurrency=1 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); })\""
+    "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); })\"",
+    "changeset": "changeset",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.27.0",
     "@earendil-works/pi-coding-agent": "^0.84.3",
     "@types/node": "^22.13.9",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.2",
+    "vitepress": "^1.6.4"
+  },
+  "dependencies": {
+    "undici": "^8.10.0"
   }
 }

package/src/catalog.ts

@@ -34,8 +34,7 @@ import type {
 /**
  * Pruned model IDs that must never re-enter the catalog via disk cache or upstream merge.
  */
-const DEAD_MODEL_IDS = new Set<string>(["deepseek-v4-flash-free", "x-preview-f-free"]);
-
+export const DEAD_MODEL_IDS = new Set<string>(["deepseek-v4-flash-free", "x-preview-f-free"]);
 /**
  * In-memory cache of currently active/available free models.
  * Initialized with all 21 verified models for 0ms instant availability.
@@ -170,6 +169,7 @@ export function enrichModelDef(raw: RawModelItem, source: Upstream): RegisteredM
 /**
  * Read cached catalog data from disk if valid and unexpired.
  * Filters out pruned dead IDs so stale disk entries never repopulate the catalog.
+ * Preserves etag for conditional If-None-Match requests.
  */
 export function readCatalogCache(): CatalogCacheData | null {
 	try {
@@ -192,6 +192,7 @@ export function readCatalogCache(): CatalogCacheData | null {
 
 /**
  * Atomically write catalog cache data to disk using temporary file + rename.
+ * Persists etag alongside models for subsequent If-None-Match conditional requests.
  */
 export function writeCatalogCache(data: CatalogCacheData): void {
 	try {
@@ -209,12 +210,13 @@ export function writeCatalogCache(data: CatalogCacheData): void {
 
 /**
  * Refresh free model catalog from OpenCode Zen and KiloCode Gateway endpoints.
- * Falls back gracefully to cached or static models if network requests fail.
+ * Uses ETag conditional requests (If-None-Match) to avoid re-merging unchanged
+ * catalogs; a 304 Not Modified response skips merge and returns the in-memory
+ * catalog unchanged. 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 21-model aliveCatalog.
+	// Thin provider: serve fresh disk cache instantly when valid
 	const disk = readCatalogCache();
 	if (disk && Array.isArray(disk.models) && disk.models.length > 0) {
 		const age = Date.now() - (disk.timestamp ?? 0);
@@ -222,7 +224,79 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 			aliveCatalog = disk.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
 			return aliveCatalog;
 		}
-		// Stale cache still better than empty — return it without network (filtered)
+	}
+
+	// Resolve etag from fresh or stale cache for conditional request
+	let cachedEtag: string | undefined = disk?.etag;
+	let staleForEtag: CatalogCacheData | null = disk;
+	if (!cachedEtag) {
+		try {
+			if (fs.existsSync(CATALOG_CACHE_FILE)) {
+				const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
+				const stale = JSON.parse(raw) as CatalogCacheData;
+				cachedEtag = stale.etag;
+				staleForEtag = stale;
+			}
+		} catch (err) {
+			logDebug("Failed reading stale catalog cache for etag", { error: String(err) });
+		}
+	}
+
+	// Attempt conditional fetch with If-None-Match when we have an etag
+	if (cachedEtag || force) {
+		try {
+			const headers: Record<string, string> = { ...opencodeHeaders() };
+			if (cachedEtag) {
+				headers["If-None-Match"] = cachedEtag;
+			}
+			const res = await fetch(`${OPENCODE_API_URL}/models`, { headers });
+			if (res.status === 304) {
+				// Not modified — skip merge, extend timestamp to avoid tight loop
+				if (staleForEtag && Array.isArray(staleForEtag.models)) {
+					try {
+						writeCatalogCache({ ...staleForEtag, timestamp: Date.now() });
+					} catch {}
+				}
+				return aliveCatalog;
+			}
+			if (res.ok) {
+				const newEtag = res.headers.get("etag") ?? res.headers.get("ETag") ?? cachedEtag;
+				const body: unknown = await res.json();
+				let rawList: RawModelItem[] = [];
+				if (Array.isArray(body)) {
+					rawList = body as RawModelItem[];
+				} else if (body !== null && typeof body === "object" && "data" in body) {
+					const dataVal = body.data as unknown;
+					if (Array.isArray(dataVal)) {
+						rawList = dataVal as RawModelItem[];
+					}
+				}
+				if (rawList.length > 0) {
+					const fresh = rawList.map((r) => enrichModelDef(r, "opencode"));
+					const merged = mergeCatalog(aliveCatalog, fresh);
+					aliveCatalog = merged;
+					writeCatalogCache({
+						timestamp: Date.now(),
+						opencode: fresh.map((m) => m.id),
+						kilo: staleForEtag?.kilo ?? [],
+						models: merged,
+						etag: newEtag ?? cachedEtag,
+					});
+					return aliveCatalog;
+				}
+				// Empty payload but 200 — treat as no-op, return current
+				if (newEtag && newEtag !== cachedEtag && staleForEtag) {
+					writeCatalogCache({ ...staleForEtag, timestamp: Date.now(), etag: newEtag });
+				}
+				return aliveCatalog;
+			}
+		} catch (err) {
+			logDebug("Conditional catalog fetch failed, falling back to cache", { error: String(err) });
+		}
+	}
+
+	// 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));
 		if (filtered.length >= 21) {
 			aliveCatalog = filtered;

package/src/commands.ts

@@ -4,17 +4,17 @@
  * log viewing, debug level configuration, and live catalog refreshing.
  */
 
-import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { refreshCatalog, setAliveCatalog } from "./catalog.ts";
-import { DEBUG_STATE_FILE, DEFAULT_RELAY_URL, LOG_FILE } from "./config.ts";
-import {
-	compareVersions,
-	fetchLatestVersion,
-	getCachedUpdate,
-	isLinkedInstall,
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { refreshCatalog, setAliveCatalog } from "./catalog.ts";
+import { DEBUG_STATE_FILE, DEFAULT_RELAY_URL, LOG_FILE } from "./config.ts";
+import {
+	compareVersions,
+	fetchLatestVersion,
+	getCachedUpdate,
+	isLinkedInstall,
 } from "./update-checker.ts";
 import {
 	deployCloudflareWorker,
@@ -60,6 +60,10 @@ import type {
 export function updateStatusBar(ui?: ExtensionUIContext): void {
 	if (!ui) return;
 	const relayState = getActiveRelayState();
+	if (relayState.hideWidget) {
+		ui.setStatus("freeflow", undefined);
+		return;
+	}
 	if (relayState.enabled && relayState.relays.length > 0) {
 		const label = shortRelayLabel(relayState.url);
 		const idx = Math.max(
@@ -76,64 +80,68 @@ export function updateStatusBar(ui?: ExtensionUIContext): void {
 	}
 }
 
-function getLocalVersion(): string {
-	try {
-		const thisDir = path.dirname(fileURLToPath(import.meta.url));
-		const pkgPath = path.join(thisDir, "..", "package.json");
-		const raw = readFileSync(pkgPath, "utf8");
-		const pkg = JSON.parse(raw) as { version?: string };
-		if (typeof pkg.version === "string" && pkg.version.trim().length > 0) {
-			return pkg.version.trim();
-		}
-		return "0.0.0";
-	} catch {
-		return "0.0.0";
-	}
-}
-
-function spawnWithProgress(
-	cmd: string,
-	args: string[],
-	ctx: ExtensionContext,
-): Promise<number> {
-	return new Promise((resolve) => {
-		try {
-			const child = spawn(cmd, args, {
-				shell: process.platform === "win32",
-				stdio: "pipe",
-			});
-			child.stdout?.on("data", (d: Buffer) => {
-				const s = String(d).trim();
-				if (s) ctx.ui.notify(s, "info");
-			});
-			child.stderr?.on("data", (d: Buffer) => {
-				const s = String(d).trim();
-				if (s) ctx.ui.notify(s, "info");
-			});
-			child.on("error", (err: Error) => {
-				ctx.ui.notify(`spawn ${cmd} failed: ${err.message}`, "warning");
-				resolve(1);
-			});
-			child.on("close", (code: number | null) => resolve(code ?? 0));
-		} catch (e) {
-			ctx.ui.notify(`spawn ${cmd} failed: ${(e as Error).message}`, "warning");
-			resolve(1);
-		}
-	});
-}
-
+function getLocalVersion(): string {
+	try {
+		const thisDir = path.dirname(fileURLToPath(import.meta.url));
+		const pkgPath = path.join(thisDir, "..", "package.json");
+		const raw = readFileSync(pkgPath, "utf8");
+		const pkg = JSON.parse(raw) as { version?: string };
+		if (typeof pkg.version === "string" && pkg.version.trim().length > 0) {
+			return pkg.version.trim();
+		}
+		return "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+
+function spawnWithProgress(
+	cmd: string,
+	args: string[],
+	ctx: ExtensionContext,
+): Promise<number> {
+	return new Promise((resolve) => {
+		try {
+			const child = spawn(cmd, args, {
+				shell: process.platform === "win32",
+				stdio: "pipe",
+			});
+			child.stdout?.on("data", (d: Buffer) => {
+				const s = String(d).trim();
+				if (s) ctx.ui.notify(s, "info");
+			});
+			child.stderr?.on("data", (d: Buffer) => {
+				const s = String(d).trim();
+				if (s) ctx.ui.notify(s, "info");
+			});
+			child.on("error", (err: Error) => {
+				ctx.ui.notify(`spawn ${cmd} failed: ${err.message}`, "warning");
+				resolve(1);
+			});
+			child.on("close", (code: number | null) => resolve(code ?? 0));
+		} catch (e) {
+			ctx.ui.notify(`spawn ${cmd} failed: ${(e as Error).message}`, "warning");
+			resolve(1);
+		}
+	});
+}
+
 export function createCommandSpec(
 	_pi: ExtensionAPI,
 	onCatalogRefreshed?: (models: RegisteredModel[]) => void,
 ): Omit<RegisteredCommand, "name"> {
 	return {
 		description:
-			"Relay egress: auto | on | off | status | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | logs [level] [n] | debug on|off | refresh | update | deploy vercel | deploy cloudflare | deploy deno",
+			"Relay egress: auto | on | off | hide | show | widget hide/show | status | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | logs [level] [n] | debug on|off | refresh | update | deploy vercel | deploy cloudflare | deploy deno",
 		getArgumentCompletions: (prefix: string) =>
 			[
 				"auto",
 				"on",
 				"off",
+				"hide",
+				"show",
+				"widget hide",
+				"widget show",
 				"status",
 				"add",
 				"list",
@@ -402,73 +410,83 @@ export function createCommandSpec(
 				setActiveRelayState(relayState);
 				persist();
 				flash();
-			} else if (sub === "status") {
-				flash();
-				try {
-					const local = getLocalVersion();
-					let latest: string | null = null;
-					const cached = getCachedUpdate();
-					if (cached && typeof cached.latest === "string") {
-						latest = cached.latest;
-					}
-					if (latest && compareVersions(latest, local) > 0) {
-						ctx.ui.notify(
-							`Update available: ${local} -> ${latest} - run /freeflow update`,
-							"info",
-						);
-					}
-				} catch {
-					// swallow — status banner is best-effort
-				}
-			} else if (sub === "update") {
-				if (isLinkedInstall()) {
-					ctx.ui.notify(
-						"LINK install (D:/github_repo/pi-freeflow) is live - just omp restart, no npm update needed.",
-						"info",
-					);
-				} else {
-					try {
-						ctx.ui.notify("Checking for updates…", "info");
-						let latest: string | null = null;
-						try {
-							latest = await fetchLatestVersion();
-						} catch {
-							latest = null;
-						}
-						if (!latest) {
-							const cached = getCachedUpdate();
-							if (cached && typeof cached.latest === "string") {
-								latest = cached.latest;
-							}
-						}
-						if (!latest) {
-							ctx.ui.notify("Could not check latest version (offline?)", "warning");
-						} else {
-							const local = getLocalVersion();
-							const cmp = compareVersions(latest, local);
-							if (cmp <= 0) {
-								ctx.ui.notify(`Already on latest (v${local})`, "info");
-							} else {
-								ctx.ui.notify(`Update available: v${local} → v${latest} — updating…`, "info");
-								let code = await spawnWithProgress("omp", ["plugin", "update", "pi-freeflow"], ctx);
-								if (code !== 0) {
-									ctx.ui.notify(`omp update exited ${code}, trying npm…`, "info");
-									code = await spawnWithProgress("npm", ["i", "-g", "pi-freeflow@latest"], ctx);
-								}
-								if (code === 0) {
-									ctx.ui.notify(`Updated to ${latest}, restart OMP`, "info");
-								} else {
-									ctx.ui.notify(
-										`Update failed (exit ${code}) — try manually: npm i -g pi-freeflow@latest`,
-										"warning",
-									);
-								}
-							}
-						}
-					} catch (e) {
-						ctx.ui.notify(`Update failed: ${(e as Error).message} — try manually: npm i -g pi-freeflow@latest`, "warning");
-					}
-				}
+			} else if (sub === "hide" || (sub === "widget" && rest === "hide")) {
+				relayState.hideWidget = true;
+				persist();
+				updateStatusBar(ctx.ui);
+				ctx.ui.notify("Widget hidden — use /freeflow show or /freeflow widget show to restore", "info");
+			} else if (sub === "show" || (sub === "widget" && rest === "show")) {
+				relayState.hideWidget = false;
+				persist();
+				flash();
+				ctx.ui.notify("Widget shown", "info");
+			} else if (sub === "status") {
+				flash();
+				try {
+					const local = getLocalVersion();
+					let latest: string | null = null;
+					const cached = getCachedUpdate();
+					if (cached && typeof cached.latest === "string") {
+						latest = cached.latest;
+					}
+					if (latest && compareVersions(latest, local) > 0) {
+						ctx.ui.notify(
+							`Update available: ${local} -> ${latest} - run /freeflow update`,
+							"info",
+						);
+					}
+				} catch {
+					// swallow — status banner is best-effort
+				}
+			} else if (sub === "update") {
+				if (isLinkedInstall()) {
+					ctx.ui.notify(
+						"LINK install (D:/github_repo/pi-freeflow) is live - just omp restart, no npm update needed.",
+						"info",
+					);
+				} else {
+					try {
+						ctx.ui.notify("Checking for updates…", "info");
+						let latest: string | null = null;
+						try {
+							latest = await fetchLatestVersion();
+						} catch {
+							latest = null;
+						}
+						if (!latest) {
+							const cached = getCachedUpdate();
+							if (cached && typeof cached.latest === "string") {
+								latest = cached.latest;
+							}
+						}
+						if (!latest) {
+							ctx.ui.notify("Could not check latest version (offline?)", "warning");
+						} else {
+							const local = getLocalVersion();
+							const cmp = compareVersions(latest, local);
+							if (cmp <= 0) {
+								ctx.ui.notify(`Already on latest (v${local})`, "info");
+							} else {
+								ctx.ui.notify(`Update available: v${local} → v${latest} — updating…`, "info");
+								let code = await spawnWithProgress("omp", ["plugin", "update", "pi-freeflow"], ctx);
+								if (code !== 0) {
+									ctx.ui.notify(`omp update exited ${code}, trying npm…`, "info");
+									code = await spawnWithProgress("npm", ["i", "-g", "pi-freeflow@latest"], ctx);
+								}
+								if (code === 0) {
+									ctx.ui.notify(`Updated to ${latest}, restart OMP`, "info");
+								} else {
+									ctx.ui.notify(
+										`Update failed (exit ${code}) — try manually: npm i -g pi-freeflow@latest`,
+										"warning",
+									);
+								}
+							}
+						}
+					} catch (e) {
+						ctx.ui.notify(`Update failed: ${(e as Error).message} — try manually: npm i -g pi-freeflow@latest`, "warning");
+					}
+				}
 			} else if (sub === "list") {
 				showList();
 			} else if (sub === "add") {
@@ -611,12 +629,14 @@ export function createCommandSpec(
 					let filterLevel: LogLevel | null = null;
 					let filterReqId: string | null = null;
 					let count = 25;
+					const rawTokens = rawRest ? rawRest.split(/\s+/) : [];
+					const isFollow = rawTokens.includes("--follow") || rawTokens.includes("-f");
 
 					if (sub === "trace" && rawRest) {
-						filterReqId = rawRest.split(/\s+/)[0];
+						filterReqId = rawTokens.filter((t) => t !== "--follow" && t !== "-f")[0] || null;
 					} else if (rawRest) {
-						const tokens = rawRest.split(/\s+/);
-						for (const t of tokens) {
+						for (const t of rawTokens) {
+							if (t === "--follow" || t === "-f") continue;
 							const lower = t.toLowerCase();
 							if (lower in LOG_LEVEL_ORDER) {
 								filterLevel = lower as LogLevel;
@@ -655,6 +675,18 @@ export function createCommandSpec(
 								"warning",
 							);
 						}
+						if (isFollow) {
+							const _t = setInterval(() => {
+								try {
+									const tail = readRecentLogs(filterLevel, filterReqId, count);
+									if (tail.lines.length > 0) {
+										ctx.ui.notify(tail.lines.join("\n"), "info");
+									}
+								} catch {}
+							}, 1000);
+							// @ts-ignore allow unref to not block process exit in CLI
+							_t.unref?.();
+						}
 						return;
 					}
 
@@ -663,6 +695,18 @@ export function createCommandSpec(
 						`${header}\n\n${result.lines.join("\n")}`,
 						"info",
 					);
+					if (isFollow) {
+						const _t2 = setInterval(() => {
+							try {
+								const tail = readRecentLogs(filterLevel, filterReqId, count);
+								if (tail.lines.length > 0) {
+									ctx.ui.notify(tail.lines.join("\n"), "info");
+								}
+							} catch {}
+						}, 1000);
+						// @ts-ignore allow unref to not block process exit in CLI
+						_t2.unref?.();
+					}
 				} catch (e) {
 					ctx.ui.notify(
 						`Could not read log file: ${(e as Error).message}`,

package/src/health.ts

@@ -0,0 +1,106 @@
+/**
+ * Health endpoint for pi-freeflow proxy
+ * Loopback-only GET /_health (and alias /health) returning relay health snapshot.
+ */
+
+import type * as http from "node:http";
+import { ALL_MODELS } from "./models.ts";
+import { getActiveRelayState, getRelayHealth, isRelayHealthy } from "./relay-state.ts";
+import { PORT } from "./config.ts";
+
+export interface HealthRelayInfo {
+	url: string;
+	label?: string;
+	healthy: boolean;
+	cooldownUntil: number;
+	consecutiveFailures: number;
+}
+
+export interface HealthData {
+	port: number;
+	active: string;
+	mode: string;
+	enabled: boolean;
+	relays: HealthRelayInfo[];
+	catalog: number;
+}
+
+/**
+ * Collect current health snapshot.
+ * @param portOverride - actual listening port (defaults to config PORT)
+ */
+export function getHealthData(portOverride?: number): HealthData {
+	const state = getActiveRelayState();
+	const relays: HealthRelayInfo[] = (state.relays || []).map((r) => {
+		const h = getRelayHealth(r.url);
+		const healthy = isRelayHealthy(r.url);
+		return {
+			url: r.url,
+			label: r.label,
+			healthy,
+			cooldownUntil: h?.cooldownUntil ?? 0,
+			consecutiveFailures: h?.consecutiveFailures ?? 0,
+		};
+	});
+	return {
+		port: portOverride ?? PORT,
+		active: state.url || "",
+		mode: (state.mode as string) ?? "auto",
+		enabled: Boolean(state.enabled),
+		relays,
+		catalog: ALL_MODELS.length,
+	};
+}
+
+function isLoopbackIP(ip: string): boolean {
+	if (!ip) return false;
+	const clean = ip.startsWith("::ffff:") ? ip.slice(7) : ip;
+	return clean === "127.0.0.1" || clean === "::1" || clean === "localhost";
+}
+
+function getClientIPFromReq(req: http.IncomingMessage): string {
+	const addr = (req.socket as unknown as { remoteAddress?: string })?.remoteAddress;
+	if (!addr) return "unknown";
+	return addr.startsWith("::ffff:") ? addr.slice(7) : addr;
+}
+
+/**
+ * Handle loopback health requests.
+ * Returns true if request was a health endpoint (handled, response already sent).
+ * Returns false if not a health path (caller should continue).
+ */
+export function handleHealthRequest(
+	req: http.IncomingMessage,
+	res: http.ServerResponse,
+	portOverride?: number,
+): boolean {
+	let pathname: string | null = null;
+	try {
+		pathname = new URL(req.url ?? "/", "http://127.0.0.1").pathname;
+	} catch {
+		return false;
+	}
+
+	const isHealthPath =
+		pathname === "/_health" || pathname === "/health" || pathname.endsWith("/health");
+	if (req.method !== "GET" || !isHealthPath) {
+		return false;
+	}
+
+	const clientIP = getClientIPFromReq(req);
+	if (!isLoopbackIP(clientIP)) {
+		const body = JSON.stringify({ error: "forbidden" });
+		res.writeHead(403, { "content-type": "application/json", "content-length": Buffer.byteLength(body) });
+		res.end(body);
+		return true;
+	}
+
+	const data = getHealthData(portOverride);
+	const body = JSON.stringify(data);
+	res.writeHead(200, {
+		"content-type": "application/json",
+		"content-length": Buffer.byteLength(body),
+	});
+	res.end(body);
+	return true;
+}