pi-freeflow 1.5.0 → 1.6.0

package/README.md

@@ -26,7 +26,7 @@ Join devs bypassing rate limits with their own relay pools. BYO, add as many as
 | **Auto-Enabled on Session** | Relay stays enabled in `auto` mode on session start and model switch | Zero Friction | **$0** |
 | **Interactive CLI Management** | 10+ `/freeflow` subcommands (`status`, `list`, `use`, `add`, `label`, `remove`, `deploy`, `logs`, `debug`) | Full Control | **$0** |
 | **Dumb Proxy That Never Breaks** | `127.0.0.1:28180`, host-normalized, pathname-guarded `/v1/models` | 100% Uptime | **$0** |
-| **Observable Real Logs** | `~/.pi/agent/pi-freeflow.log`, 5MB auto-rotation, real-time debug toggle | Observable | **$0** |
+| **Observable Real Logs** | `~/.pi/agent/pi-freeflow.log`, 10MB auto-rotation, real-time debug toggle | Observable | **$0** |
 
 Philosophy: **Thin by design.** We only ship model list + relay proxy + log. Host owns thinking & normalization.
 
@@ -101,12 +101,17 @@ Manage your relay pool directly from the OMP / Pi terminal:
 /freeflow status                  # View active relay, pool status, and candidates
 /freeflow list                    # List all relays with real-time health badges (✓ / ⚠️ [cooling])
 /freeflow use <url|index|label>   # Switch active relay
+/freeflow url <url>               # Set the active relay URL directly
 /freeflow add <url> [label]       # Add new relay to the pool
 /freeflow label <index|url> <name># Assign a friendly label to a relay
 /freeflow remove <index|url|label># Remove a relay from the pool
+/freeflow test <index|url|label>  # Probe a relay for reachability (HTTP 200 + latency)
 /freeflow on | off | auto         # Toggle relay mode (auto = enabled for freeflow)
 /freeflow deploy <platform>       # Guided relay deploy: vercel|cloudflare|deno — token in-memory, auto-adds (Vercel 1M/mo recommended)
 /freeflow logs [lines]            # Inspect recent proxy logs
+/freeflow trace [req-id]          # Tail logs filtered by request correlation ID
+/freeflow refresh                 # Reload the model catalog from live upstreams
+/freeflow update                  # Check for and install a package update
 /freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
 ```
 
@@ -150,26 +155,7 @@ Default ships direct. Add relays via `/freeflow add <url> [label]`.
 ```bash
 /freeflow deploy cloudflare  # prompts token in-memory, auto-adds to pool
 ```
-*Manual fallback:* `dash.cloudflare.com` → Workers → Create → Deploy → Edit code → paste snippet below → Deploy → `/freeflow add https://your.workers.dev cf-worker-1`
-
-```js
-// Only the 2 upstreams pi-freeflow talks to. Anything else = open proxy abuse.
-const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
-
-export default {
-  async fetch(req) {
-    const target = req.headers.get("x-relay-target");
-    const relayPath = req.headers.get("x-relay-path") || "/";
-    if (!target) return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), { status: 400 });
-    const cleanTarget = target.replace(/\/$/, "");
-    if (!ALLOWED_TARGETS.includes(cleanTarget)) return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
-    if (!relayPath.startsWith("/")) return new Response(JSON.stringify({ error: "Bad path" }), { status: 400 });
-    const headers = new Headers(req.headers);
-    headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
-    return fetch(cleanTarget + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
-  },
-};
-```
+*Manual fallback:* `dash.cloudflare.com` → Workers → Create → Deploy → Edit code → paste the canonical worker source (see "Canonical worker source" below) → Deploy → `/freeflow add https://your.workers.dev cf-worker-1`
 
 **Option B: Vercel Edge Relay (1M req/mo) — Auto Deploy**
 ```bash
@@ -178,30 +164,9 @@ export default {
 ```
 *Manual fallback:* Push 2 files (`api/relay.js` + `vercel.json`) to GitHub $\to$ Import on `vercel.com` $\to$ `/freeflow add https://your.vercel.app vercel-relay-1`
 
-```js
-// api/relay.js
-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 target" }), { status: 403 });
-  }
-  const headers = new Headers(req.headers);
-  headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
-  const res = await fetch(target.replace(/\/$/, "") + relayPath, {
-    method: req.method,
-    headers,
-    body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined,
-    duplex: "half",
-  });
-  return new Response(res.body, { status: res.status, headers: res.headers });
-}
-```
+For `api/relay.js`, use the canonical worker source (see below); `vercel.json` stays:
 
 ```json
-// vercel.json
 { "rewrites": [{ "source": "/(.*)", "destination": "/api/relay" }] }
 ```
 
@@ -209,22 +174,29 @@ export default async function handler(req) {
 ```bash
 /freeflow deploy deno  # prompts token in-memory, auto-adds to pool
 ```
-*Manual fallback:* `dash.deno.com` → New Project → Playground → paste snippet below → Deploy → `/freeflow add https://your-project.deno.dev deno-relay-1`
+*Manual fallback:* `dash.deno.com` → New Project → Playground → paste the canonical worker source (see below) → Deploy → `/freeflow add https://your-project.deno.dev deno-relay-1`
 
-```ts
-const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+**Canonical worker source (all platforms)**
+
+The relay worker template is generated per deployment by `/freeflow deploy` and lives in [`src/deploy.ts`](src/deploy.ts): one hardened core plus thin Vercel / Cloudflare / Deno wrappers. Every deployment embeds its own shared secret and enforces the target allowlist (`https://opencode.ai`, `https://api.kilo.ai`), SSRF/private-host guard, relay-path validation, and a header denylist — `x-relay-auth` is checked by the worker and never forwarded upstream.
 
-Deno.serve(async (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 target" }), { status: 403 });
-  }
-  const headers = new Headers(req.headers);
-  headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
-  const res = await fetch(target.replace(/\/$/, "") + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
-  return new Response(res.body, { status: res.status, headers: res.headers });
-});
+```js
+// Minimal Cloudflare illustration. Prefer /freeflow deploy: the generated
+// worker (src/deploy.ts) is the signed/hardened source for all three
+// platforms. This example omits the SSRF guard, path validation, and auth.
+const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+export default {
+  async fetch(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 target" }), { status: 403 });
+    }
+    const headers = new Headers(req.headers);
+    headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
+    return fetch(target.replace(/\/$/, "") + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
+  },
+};
 ```
 
 **Verify your pool:**
@@ -247,15 +219,15 @@ cat ~/.pi/agent/pi-freeflow.log | tail -n 50
 /freeflow debug on
 ```
 
-Log rotation at 5MB. Clean, parseable, real-time HTTP lifecycle tracking.
+Log rotation at 10MB. Clean, parseable, real-time HTTP lifecycle tracking.
 
 ---
 
 ### Design
 
-This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step and there are no runtime dependencies. Thinking and prompt normalization stay with the host (`pi-ai`).
+This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step. The only runtime dependency is `undici`, which powers the upstream fetch agent. Thinking and prompt normalization stay with the host (`pi-ai`).
 
-Current size: about 4.6k lines including tests. 16 tests pass, typecheck clean.
+Current size: about 11.3k lines including tests. 226 tests pass, typecheck clean.
 
 ---
 
@@ -284,7 +256,7 @@ Contributions welcome — bug fixes, new relay platforms, model additions, docs
 
 #### Prerequisites
 
-- **Node.js ≥ 22.6.0** (uses `--experimental-strip-types`, no build step)
+- **Node.js ≥ 22.19.0** (uses `--experimental-strip-types`, no build step)
 - **pnpm** (package manager)
 
 #### Setup & Verify
@@ -295,7 +267,7 @@ cd pi-freeflow
 pnpm install
 
 # run all three before opening a PR
-pnpm test        # 16 tests across 2 test files
+pnpm test        # 226 tests across 30 test files
 pnpm typecheck   # tsc --noEmit, must pass clean
 pnpm smoke       # verifies extensions/index.ts loads without crashing
 ```
@@ -310,12 +282,12 @@ src/
 ├── proxy.ts          # local proxy server (127.0.0.1:28180)
 ├── relay.ts          # relay selection & round-robin
 ├── relay-state.ts    # relay pool state, health tracking
-├── rate-limiter.ts   # adaptive cooldown on 429/504/socket errors
+├── rate-limiter.ts   # in-memory sliding rate limiter (200/day, 200/hour)
 ├── stream-pipe.ts    # SSE stream piping & truncation resilience
 ├── commands.ts       # /freeflow CLI subcommands
 ├── deploy.ts         # guided relay deploy (vercel/cloudflare/deno)
-├── config.ts         # relay pool persistence
-├── logger.ts         # file logger with 5MB rotation
+├── config.ts         # constants, whitelists, paths, and runtime settings
+├── logger.ts         # file logger with 10MB rotation
 └── types.ts          # shared type definitions
 extensions/
 └── index.ts          # OMP/Pi extension manifest
@@ -325,7 +297,7 @@ test/
 
 #### Guidelines
 
-- **Stay thin.** No runtime dependencies. No build step. If it belongs in the host (`pi-ai`), don't add it here.
+- **Stay thin.** One runtime dependency (`undici`), no build step. If it belongs in the host (`pi-ai`), don't add it here.
 - **Test what you touch.** Every `src/*.ts` has a matching `test/*.test.ts`. Add or update tests for your change.
 - **Keep model IDs clean.** Slash-free, colon-free aliases for CLI compatibility. See existing patterns in `models.ts`.
 - **One concern per PR.** Bug fix? One PR. New relay platform? Separate PR. Easier to review, faster to merge.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.6.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",
@@ -24,7 +24,7 @@
   },
   "homepage": "https://github.com/trefeon/pi-freeflow#readme",
   "engines": {
-    "node": ">=22.6.0"
+    "node": ">=22.19.0"
   },
   "omp": {
     "extensions": [
@@ -52,7 +52,6 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.0",
-    "@earendil-works/pi-coding-agent": "^0.84.3",
     "@types/node": "^22.13.9",
     "typescript": "^5.8.2",
     "vitepress": "^1.6.4"

package/src/catalog.ts

@@ -10,6 +10,7 @@ import path from "node:path";
 import {
 	CATALOG_CACHE_FILE,
 	CATALOG_CACHE_TTL_MS,
+	CATALOG_REFRESH_TIMEOUT_MS,
 	KILO_CHAT_URL,
 	OPENCODE_API_URL,
 	opencodeHeaders,
@@ -17,12 +18,8 @@ import {
 import { log, logDebug, logWarn } from "./logger.ts";
 import {
 	ALL_MODELS,
-	KILO_MODELS,
 	KILO_MODEL_IDS,
-	KNOWN_MODELS,
 	MODEL_MAP,
-	OPENCODE_MODELS,
-	getAllRegisteredModels,
 } from "./models.ts";
 import type {
 	CatalogCacheData,
@@ -178,9 +175,10 @@ export function readCatalogCache(): CatalogCacheData | null {
 		}
 		const raw = fs.readFileSync(CATALOG_CACHE_FILE, "utf8");
 		const data = JSON.parse(raw) as CatalogCacheData;
-		if (Array.isArray(data.models)) {
-			data.models = data.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
+		if (!Array.isArray(data.models)) {
+			return null;
 		}
+		data.models = data.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
 		if (Date.now() - data.timestamp < CATALOG_CACHE_TTL_MS) {
 			return data;
 		}
@@ -249,7 +247,12 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 			if (cachedEtag) {
 				headers["If-None-Match"] = cachedEtag;
 			}
-			const res = await fetch(`${OPENCODE_API_URL}/models`, { headers });
+			const res = await fetch(`${OPENCODE_API_URL}/models`, {
+				headers,
+				// A hung upstream must not freeze /freeflow refresh: abort after
+				// CATALOG_REFRESH_TIMEOUT_MS and fall back to cache below.
+				signal: AbortSignal.timeout(CATALOG_REFRESH_TIMEOUT_MS),
+			});
 			if (res.status === 304) {
 				// Not modified — skip merge, extend timestamp to avoid tight loop
 				if (staleForEtag && Array.isArray(staleForEtag.models)) {
@@ -291,14 +294,20 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 				return aliveCatalog;
 			}
 		} catch (err) {
-			logDebug("Conditional catalog fetch failed, falling back to cache", { error: String(err) });
+			if ((err as Error)?.name === "AbortError") {
+				logWarn("Catalog refresh timed out — using cached/static fallback", {
+					timeoutMs: CATALOG_REFRESH_TIMEOUT_MS,
+				});
+			} else {
+				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) {
+		if (filtered.length >= ALL_MODELS.length) {
 			aliveCatalog = filtered;
 			return aliveCatalog;
 		}
@@ -310,7 +319,7 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 			const stale = JSON.parse(raw) as CatalogCacheData;
 			if (Array.isArray(stale.models) && stale.models.length > 0) {
 				const filtered = stale.models.filter((m) => !DEAD_MODEL_IDS.has(m.id));
-				if (filtered.length >= 21) {
+				if (filtered.length >= ALL_MODELS.length) {
 					aliveCatalog = filtered;
 					return aliveCatalog;
 				}