pi-freeflow 1.1.3 → 1.1.5

package/README.md

@@ -94,10 +94,18 @@ omp plugin link /path/to/pi-freeflow
 
 ---
 
-## 🌐 Setting Up Your Own Egress Relays
+## 🌐 Setting Up Your Own Egress Relays (Multi-Cloud)
 
-### 1. Cloudflare Worker Relay (Recommended)
-Deploy this script to Cloudflare Workers (100,000 free requests/day):
+By default, FreeFlow works out of the box with direct upstream calls. To expand concurrency, bypass IP rate limits, and enable rolling failover, you can connect your own free cloud relays across **Cloudflare Workers**, **Vercel Edge**, **Deno Deploy**, or a **Linux VPS**.
+
+---
+
+### 1. Cloudflare Worker Relay (Recommended ⭐)
+> **Free Tier**: 100,000 requests/day · Low latency · No 25-second execution timeout.
+
+1. Go to [dash.cloudflare.com](https://dash.cloudflare.com) $\to$ **Workers & Pages** $\to$ **Create application** $\to$ **Create Worker**.
+2. Name your worker (e.g. `my-freeflow-relay`) $\to$ click **Deploy**.
+3. Click **Edit code**, paste this JavaScript, and click **Save and Deploy**:
 
 ```javascript
 const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
@@ -108,8 +116,9 @@ export default {
       return new Response(null, {
         headers: {
           "Access-Control-Allow-Origin": "*",
-          "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+          "Access-Control-Allow-Methods": "GET, POST, OPTIONS, HEAD",
           "Access-Control-Allow-Headers": "*",
+          "Access-Control-Max-Age": "86400",
         },
       });
     }
@@ -117,8 +126,8 @@ export default {
     const target = request.headers.get("x-relay-target");
     const relayPath = request.headers.get("x-relay-path") || "/";
 
-    if (!target || !ALLOWED_TARGETS.includes(target)) {
-      return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
+    if (!target || !ALLOWED_TARGETS.includes(target.replace(/\/$/, ""))) {
+      return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403, headers: { "content-type": "application/json" } });
     }
 
     const targetUrl = target.replace(/\/$/, "") + relayPath;
@@ -126,42 +135,147 @@ export default {
     headers.delete("x-relay-target");
     headers.delete("x-relay-path");
     headers.delete("host");
+    headers.delete("cf-connecting-ip");
+    headers.delete("cf-ray");
+
+    try {
+      const response = await fetch(targetUrl, {
+        method: request.method,
+        headers,
+        body: request.method !== "GET" && request.method !== "HEAD" ? request.body : undefined,
+      });
 
-    const response = await fetch(targetUrl, {
-      method: request.method,
-      headers,
-      body: request.method !== "GET" && request.method !== "HEAD" ? request.body : undefined,
-    });
+      const outHeaders = new Headers(response.headers);
+      outHeaders.set("Access-Control-Allow-Origin", "*");
+      return new Response(response.body, { status: response.status, headers: outHeaders });
+    } catch (err) {
+      return new Response(JSON.stringify({ error: "Upstream failed", details: String(err) }), { status: 502, headers: { "content-type": "application/json" } });
+    }
+  },
+};
+```
 
-    return new Response(response.body, {
-      status: response.status,
-      headers: response.headers,
-    });
-### 2. Vercel Relay
-Deploy using the built-in deploy command:
+4. Copy your Worker URL and register it inside OMP:
+```text
+/freeflow use https://my-freeflow-relay.your-subdomain.workers.dev
+```
+
+---
+
+### 2. Vercel Edge Relay
+> **Free Tier**: 1,000,000 requests/month.
+
+#### Method A: Automated In-Memory CLI Deploy
+1. Generate a Vercel token at [vercel.com/account/tokens](https://vercel.com/account/tokens).
+2. In OMP TUI, run:
 ```text
 /freeflow deploy
 ```
-*(Prompts for your Vercel API token in-memory and automatically creates a private Edge Function relay).*
+*(Prompts for your token in-memory, provisions a private Edge Function, and adds it to your relay pool automatically).*
+
+#### Method B: Manual Git Deploy
+Deploy a Git repository with these 3 files:
+* **`api/relay.js`**:
+  ```javascript
+  const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+  export const config = { runtime: "edge" };
+  export default async function handler(req) {
+    const target = req.headers.get("x-relay-target");
+    const relayPath = req.headers.get("x-relay-path") || "/";
+    if (!target || !ALLOWED_TARGETS.includes(target.replace(/\/$/, ""))) return new Response(JSON.stringify({ error: "Forbidden" }), { status: 403 });
+    const targetUrl = target.replace(/\/$/, "") + relayPath;
+    const headers = new Headers(req.headers);
+    headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
+    const response = await fetch(targetUrl, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined, duplex: "half" });
+    return new Response(response.body, { status: response.status, headers: response.headers });
+  }
+  ```
+* **`package.json`**: `{ "name": "freeflow-relay", "version": "1.0.0" }`
+* **`vercel.json`**: `{ "rewrites": [{ "source": "/(.*)", "destination": "/api/relay" }] }`
+
+---
+
+### 3. Deno Deploy Relay
+> **Free Tier**: 100,000 requests/day.
+
+1. Open [dash.deno.com](https://dash.deno.com) $\to$ **New Project** $\to$ **Playground**.
+2. Paste the following TypeScript code:
+
+```typescript
+const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+
+Deno.serve(async (req) => {
+  if (req.method === "OPTIONS") {
+    return new Response(null, {
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+        "Access-Control-Allow-Headers": "*",
+      },
+    });
+  }
+
+  const target = req.headers.get("x-relay-target");
+  const relayPath = req.headers.get("x-relay-path") || "/";
+  if (!target || !ALLOWED_TARGETS.includes(target.replace(/\/$/, ""))) {
+    return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
+  }
+
+  const targetUrl = target.replace(/\/$/, "") + relayPath;
+  const headers = new Headers(req.headers);
+  headers.delete("x-relay-target");
+  headers.delete("x-relay-path");
+  headers.delete("host");
+
+  const response = await fetch(targetUrl, {
+    method: req.method,
+    headers,
+    body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined,
+  });
+  return new Response(response.body, { status: response.status, headers: response.headers });
+});
+```
+3. Click **Deploy** and copy your Deno project URL (`https://project-name.deno.dev`).
+
+---
+
+## 🎮 Managing Relays in FreeFlow
+
+Inside the OMP / Pi TUI:
+```text
+/freeflow use <URL>     # Set active relay and add to saved pool
+/freeflow list          # View all saved relays with status indicators (★ = active)
+/freeflow status        # Check current relay health and egress mode
+/freeflow refresh       # Trigger live on-demand model catalog sync from upstream APIs
+/freeflow on            # Force enable relay egress mode
+/freeflow off           # Switch to direct upstream mode
+/freeflow remove <URL>  # Remove an inactive relay from pool
+/freeflow logs          # Show last 25 lines of debug logs
+```
 
 ---
 
 ## 🛠️ Diagnostics & Troubleshooting
 
 ### Custom Port Configuration
-By default, `pi-freeflow` uses a **Single Shared Port** (`18080`). All concurrent sub-agents automatically share the same master proxy port without spawning redundant servers.
+By default, `pi-freeflow` uses a **Single Shared Master Port** (`18080`). All concurrent sub-agents automatically reuse this master proxy without spawning redundant servers or extra sockets.
 
 To change the base port:
 ```env
 FREEFLOW_PORT=19000
 ```
 
-View live debug logs:
+### Subagent Credentials
+If subagents report missing provider keys, verify `~/.omp/agent/.env`:
+```env
+FREEFLOW_API_KEY=freeflow
+```
+
+### Live Logs
 ```bash
-cat ~/.pi/agent/pi-freeflow.log | tail -n 30
-# or inside OMP:
-/freeflow logs
+cat ~/.pi/agent/pi-freeflow.log | tail -n 40
 ```
+
 ---
 
 ## 📄 License

package/extensions/index.ts

@@ -746,10 +746,7 @@ function checkRateLimit(ip: string, upstream: Upstream): boolean {
 	return true;
 }
 
-// ── Health Check (OpenCode/Kilo catalogs; no per-model inference) ──
-// Each upstream publishes a model list; fetch it ONCE (cached) and check
-// membership. A 1-token chat probe per model was too slow (large models need
-// 10s+ for the first token). Real usability is validated at chat time (300s).
+// ── Health Check & Dynamic Catalog Auto-Update ────────────────────
 const CATALOG_CACHE_FILE = path.join(
 	homedir(),
 	".pi",
@@ -758,10 +755,98 @@ const CATALOG_CACHE_FILE = path.join(
 );
 const CATALOG_CACHE_TTL_MS = 3600_000; // 1 hour
 
+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 nicely
+	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(" ");
+}
+
+interface RawModelItem {
+	id: string;
+	context_length?: number;
+	max_output_tokens?: number;
+	[key: string]: unknown;
+}
+
+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,
+	};
+}
+
 interface CatalogCacheData {
 	timestamp: number;
 	opencode: string[];
 	kilo: string[];
+	models?: RegisteredModel[];
 }
 
 function readCatalogCache(): CatalogCacheData | null {
@@ -776,99 +861,81 @@ function readCatalogCache(): CatalogCacheData | null {
 	return null;
 }
 
-function writeCatalogCache(opencode: string[], kilo: string[]): void {
+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(`${API}/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 {}
+	if (!opencodeList.length) {
+		opencodeList = KNOWN_MODELS.map((m) => ({ ...m, source: "opencode" as const }));
+	}
+
+	// 2. Fetch KiloCode Gateway models
+	let kiloList: RegisteredModel[] = [];
+	try {
+		const r = await fetch(
+			KILO_CHAT_URL.replace("/chat/completions", "/models"),
+			{
+				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 {}
+	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
 	try {
 		const dir = path.dirname(CATALOG_CACHE_FILE);
 		if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 		const data: CatalogCacheData = {
 			timestamp: Date.now(),
-			opencode,
-			kilo,
+			opencode: opencodeList.map((m) => m.id),
+			kilo: kiloList.map((m) => m.id),
+			models: all,
 		};
 		const tmpPath = `${CATALOG_CACHE_FILE}.${randomUUID()}.tmp`;
-		fs.writeFileSync(tmpPath, JSON.stringify(data), "utf8");
+		fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf8");
 		fs.renameSync(tmpPath, CATALOG_CACHE_FILE);
 	} catch {}
-}
-
-let opencodeCatalogP: Promise<Set<string> | null> | null = null;
-function opencodeCatalog(): Promise<Set<string> | null> {
-	if (!opencodeCatalogP)
-		opencodeCatalogP = (async () => {
-			const disk = readCatalogCache();
-			if (disk && Array.isArray(disk.opencode) && disk.opencode.length > 0) {
-				return new Set<string>(disk.opencode);
-			}
-			try {
-				const r = await fetch(`${API}/models`, {
-					headers: opencodeHeaders(),
-					signal: AbortSignal.timeout(10_000),
-				});
-				if (!r.ok) {
-					// Fallback to static known models if network fails
-					return new Set<string>(KNOWN_MODELS.map((m) => m.id));
-				}
-				const d = await r.json();
-				const arr = (d?.data ?? []).map((m: { id: string }) => m.id);
-				const s = new Set<string>(arr);
-				const kDisk = disk?.kilo ?? KILO_MODELS.map((m) => m.id);
-				writeCatalogCache(arr, kDisk);
-				return s;
-			} catch {
-				return new Set<string>(KNOWN_MODELS.map((m) => m.id));
-			}
-		})();
-	return opencodeCatalogP;
-}
-let kiloCatalogP: Promise<Set<string> | null> | null = null;
-function kiloCatalog(): Promise<Set<string> | null> {
-	if (!kiloCatalogP)
-		kiloCatalogP = (async () => {
-			const disk = readCatalogCache();
-			if (disk && Array.isArray(disk.kilo) && disk.kilo.length > 0) {
-				return new Set<string>(disk.kilo);
-			}
-			try {
-				const r = await fetch(
-					KILO_CHAT_URL.replace("/chat/completions", "/models"),
-					{
-						headers: { Authorization: "Bearer kilo-free" },
-						signal: AbortSignal.timeout(10_000),
-					},
-				);
-				if (!r.ok) {
-					return new Set<string>(KILO_MODELS.map((m) => m.id));
-				}
-				const d = await r.json();
-				const arr = (d?.data ?? []).map((m: { id: string }) => m.id);
-				const s = new Set<string>(arr);
-				const ocDisk = disk?.opencode ?? KNOWN_MODELS.map((m) => m.id);
-				writeCatalogCache(ocDisk, arr);
-				return s;
-			} catch {
-				return new Set<string>(KILO_MODELS.map((m) => m.id));
-			}
-		})();
-	return kiloCatalogP;
-}
 
-async function checkModelAlive(id: string): Promise<boolean> {
-	try {
-		const cat = await opencodeCatalog();
-		return cat ? cat.has(id) : false;
-	} catch {
-		return false;
-	}
+	return all;
 }
 
-async function checkKiloAlive(id: string): Promise<boolean> {
-	try {
-		const cat = await kiloCatalog();
-		return cat ? cat.has(id) : false;
-	} catch {
-		return false;
-	}
-}
 
 // ── Helpers ────────────────────────────────────────────────────────
 function getClientIP(req: http.IncomingMessage): string {
@@ -1371,31 +1438,8 @@ export default async function (pi: ExtensionAPI) {
 			return;
 		}
 	}
-	// Health check opencode models
-	log("info", `checking ${KNOWN_MODELS.length} opencode model(s)...`);
-	const opencodeChecks = await Promise.all(
-		KNOWN_MODELS.map(async (model) => {
-			const alive = await checkModelAlive(model.id);
-			if (alive) log("info", `✓ ${model.id} is alive`);
-			else log("warn", `✗ ${model.id} is dead — skipping`);
-			return { ...model, alive, source: "opencode" as const };
-		}),
-	);
-
-	// Health check kilo models
-	log("info", `checking ${KILO_MODELS.length} kilo model(s)...`);
-	const kiloChecks = await Promise.all(
-		KILO_MODELS.map(async (model) => {
-			const alive = await checkKiloAlive(model.id);
-			if (alive) log("info", `✓ ${model.id} (kilo) is alive`);
-			else log("warn", `✗ ${model.id} (kilo) is dead — skipping`);
-			return { ...model, alive, source: "kilo" as const };
-		}),
-	);
-
-	const aliveModels = [...opencodeChecks, ...kiloChecks].filter((m) => m.alive);
+	const aliveModels = await refreshCatalog();
 	aliveCatalog = aliveModels;
-
 	if (aliveModels.length === 0) {
 		// Don't bail: still register /bansos below so the user can recover
 		// (e.g. switch the relay off) instead of being stranded with no command.
@@ -1439,9 +1483,9 @@ export default async function (pi: ExtensionAPI) {
 	// ── /bansos command: toggle relay egress live (on|off|status|url [URL]) ───
 	const commandSpec = {
 		description:
-			"Relay egress: on | off | status | logs | url [URL] | deploy | list | use <URL> | remove <URL>",
+			"Relay egress: on | off | status | logs | url [URL] | deploy | list | use <URL> | remove <URL> | refresh",
 		getArgumentCompletions: (prefix: string) =>
-			["on", "off", "status", "url", "deploy", "list", "use", "remove"]
+			["on", "off", "status", "url", "deploy", "list", "use", "remove", "refresh", "models"]
 				.filter((s) => s.startsWith(prefix))
 				.map((s) => ({ value: s, label: s })),
 		handler: async (args: string, ctx) => {
@@ -1582,7 +1626,7 @@ export default async function (pi: ExtensionAPI) {
 			} else if (sub === "logs" || sub === "log") {
 				try {
 					if (!fs.existsSync(LOG_FILE)) {
-						ctx.ui.notify(`No logs recorded yet in ${LOG_FILE}`, "info");
+						ctx.ui.notify("Log file is empty", "info");
 						return;
 					}
 					const content = fs.readFileSync(LOG_FILE, "utf8");
@@ -1591,6 +1635,14 @@ export default async function (pi: ExtensionAPI) {
 				} 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);
+				persist();
+				ctx.ui.notify(
+					`✓ Refreshed ${updated.length} models with full-spec metadata!`,
+					"info",
+				);
 			} else if (sub === "remove") {
 				const url = (
 					rest ||

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-freeflow",
 	"type": "module",
-	"version": "1.1.3",
+	"version": "1.1.5",
 	"description": "Personal multi-cloud rolling fallback relay for OpenCode Zen and KiloCode models in OMP/Pi",
 	"keywords": [
 		"pi-package",