pi-freeflow 1.4.1 → 1.4.2

package/README.md

@@ -46,11 +46,11 @@ Optimized for deep reasoning, long-horizon coding & autonomous agentic workflows
 | `muse-spark-1.2-contributor-free` | Meta Superintelligence Labs | **1M** (1.048.576) | **131K** (131.072) | `minimal → max` | ✅ |
 | `x-preview-f-free` | Ox Alpha | **1M** (1.048.576) | **131K** (131.072) | `low / high / max` | ✅ |
 | `mimo-v2.5-free` | Xiaomi MiMo | **1M** (1.048.576) | **131K** (131.072) | `low / medium / high` | ✅ |
-| `deepseek-v4-flash-free` | DeepSeek | **1M** (1.000.000) | **384K** (384.000) | `minimal → max` | ❌ |
-| `laguna-s-2.1-free` | Poolside | **1M** (1.048.576) | **131K** (131.072) | `minimal → max` | ❌ |
-| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `minimal → max` | ❌ |
-| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `minimal → max` | ❌ |
-| `hy3-free` | Tencent Hunyuan | **262K** (262.144) | **262K** (262.144) | `minimal → max` | ❌ |
+| `deepseek-v4-flash-free` | DeepSeek | **1M** (1.000.000) | **384K** (384.000) | `low → max` | ❌ |
+| `laguna-s-2.1-free` | Poolside | **1M** (1.048.576) | **131K** (131.072) | `low → max` | ❌ |
+| `nemotron-3.5-lightning-free` | NVIDIA | **1M** (1.000.000) | **262K** (262.144) | `low → max` | ❌ |
+| `nemotron-3-ultra-free` | NVIDIA | **1M** (1.000.000) | **128K** (128.000) | `low → max` | ❌ |
+| `hy3-free` | Tencent Hunyuan | **262K** (262.144) | **262K** (262.144) | `low → max` | ❌ |
 | `big-pickle` | Big Pickle | **200K** (200.000) | **32K** (32.000) | `high / max` | ❌ |
 
 #### KiloCode Gateway (14 Models) — OpenRouter Compatible
@@ -59,15 +59,15 @@ Keyless access with `Bearer kilo-free`. Clean slash-free and colon-free CLI alia
 | Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
 | :--- | :--- | :--- | :--- | :--- | :--- |
 | `dots-3-note-preview` (`dots-studio/...:free`) | Dots Studio | **512K** (512.000) | **512K** (512.000) | `openrouter` (auto) | ✅ |
-| `step-3.7-flash` (`stepfun/...:free`) | StepFun | **262K** (262.144) | **262K** (262.144) | `low / medium / high` | ✅ |
+| `step-3.7-flash` (`stepfun/...:free`) | StepFun | **262K** (262.144) | **262K** (262.144) | `openrouter` (auto) | ✅ |
 | `nemotron-3-nano-omni` (`nvidia/...:free`) | NVIDIA | **256K** (256.000) | **65K** (65.536) | `openrouter` (auto) | ✅ |
 | `nemotron-3-ultra-550b` (`nvidia/...:free`) | NVIDIA | **1M** (1.000.000) | **65K** (65.536) | `openrouter` (auto) | ❌ |
-| `nemotron-3.5-lightning` (`nvidia/...:free`) | NVIDIA | **1M** (1.000.000) | **131K** (131.072) | `openrouter` (auto) | ❌ |
+| `nvidia/nemotron-3.5-lightning:free` | NVIDIA | **1M** (1.000.000) | **131K** (131.072) | `openrouter` (auto) | ❌ |
 | `nemotron-3-super` (`nvidia/...:free`) | NVIDIA | **262K** (262.144) | **262K** (262.144) | `openrouter` (auto) | ❌ |
-| `hy3` (`tencent/hy3:free`) | Tencent Hunyuan | **262K** (262.144) | **262K** (262.144) | `openrouter` (auto) | ❌ |
+| `hy3:free` (`tencent/hy3:free`) | Tencent Hunyuan | **262K** (262.144) | **262K** (262.144) | `openrouter` (auto) | ❌ |
 | `north-mini-code` (`cohere/...:free`) | Cohere | **256K** (256.000) | **64K** (64.000) | `openrouter` (auto) | ❌ |
-| `laguna-s-2.1` (`poolside/...:free`) | Poolside | **1M** (1.048.576) | **131K** (131.072) | `openrouter` (auto) | ❌ |
-| `laguna-xs-2.1` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `openrouter` (auto) | ❌ |
+| `laguna-s-2.1:free` (`poolside/...:free`) | Poolside | **1M** (1.048.576) | **131K** (131.072) | `openrouter` (auto) | ❌ |
+| `laguna-xs-2.1:free` (`poolside/...:free`) | Poolside | **262K** (262.144) | **32K** (32.768) | `openrouter` (auto) | ❌ |
 | `lfm-2.5` (`liquid/lfm-2.5-2.6b:free`) | Liquid AI | **128K** (128.000) | **32K** (32.768) | `openrouter` (auto) | ❌ |
 | `kilo-auto` (`kilo-auto/free`) | Kilo Gateway Auto | **256K** (256.000) | **10K** (10.000) | ❌ *(non-thinking)* | ❌ |
 | `openrouter` (`openrouter/free`) | OpenRouter Free | **200K** (200.000) | **65K** (65.536) | ❌ *(non-thinking)* | ✅ |
@@ -84,7 +84,7 @@ You → 127.0.0.1:18080 (dumb proxy, host-normalized) → x-relay-target → N e
 
 1. **Per-Request Round-Robin**: 10 parallel subagents hit N different egress IPs (your pool size). No thundering herd.
 2. **Adaptive Health & Error Cooldown**: Relays hitting 429, 504, or socket disconnects enter temporary cooldown (30-90s) and automatically move behind healthy candidates. Healthy relays handle traffic with 0ms wasted delay.
-3. **Seamless 429 Roll**: `429 / 502 / 503 / 504` → instant roll to next relay, never 429 to agent.
+3. **Seamless 429 Roll**: `429 / 408 / 502 / 503 / 504 / 520-530` → instant roll to next relay, never 429 to agent.
 4. **Stream Truncation Resilience**: Stateful SSE terminal tracking prevents fatal unhandled stream closed errors when connections drop.
 5. **Direct Fallback Safety Net**: If all relays in the pool are exhausted, transparent direct fetch to upstream.
 6. **Zero Subagent Connect Errors**: 24h `DISK_CACHE_ONLY` model catalog avoids subagents hammering remote catalogs.
@@ -105,7 +105,7 @@ Manage your relay pool directly from the OMP / Pi terminal:
 /freeflow label <index|url> <name># Assign a friendly label to a relay
 /freeflow remove <index|url|label># Remove a relay from the pool
 /freeflow on | off | auto         # Toggle relay mode (auto = enabled for freeflow)
-/freeflow deploy                  # Guided auto-deploy 6 Vercel Edge relays (in-memory token)
+/freeflow deploy                  # Guided deploy of ONE Vercel Edge relay (in-memory token)
 /freeflow logs [lines]            # Inspect recent proxy logs
 /freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
 ```
@@ -146,18 +146,63 @@ Default ships direct. Add relays via `/freeflow add <url> [label]`.
 
 **Option A: Cloudflare Workers (100k req/day, no 25s timeout)**
 1. Go to `dash.cloudflare.com` → Workers → Create → Deploy → Edit code
-2. Paste the Worker relay snippet from `/reference/worker-relay.js`
+2. Paste this Worker relay snippet:
+
+```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 });
+  },
+};
+```
 3. Deploy and add it:
 
 ```bash
 omp → /freeflow add https://your.workers.dev cf-worker-1
 ```
 
-**Option B: Six Vercel Edges (1M req/mo) — Auto Deploy**
+**Option B: Vercel Edge Relay (1M req/mo) — Auto Deploy**
 ```bash
 /freeflow deploy  # prompts token in-memory, auto-adds to pool
 ```
 
+**Option C: Deno Deploy (100k req/day)**
+1. Go to `dash.deno.com` → New Project → Playground
+2. Paste this relay and click **Deploy**:
+
+```ts
+const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
+
+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 });
+});
+```
+
+3. Add it:
+
+```bash
+/freeflow add https://your-project.deno.dev deno-relay-1
+```
+
 **Verify your pool:**
 ```bash
 /freeflow status        # relay-A 1/N (ON) → candidates:N
@@ -186,12 +231,12 @@ Log rotation at 5MB. Clean, parseable, real-time HTTP lifecycle tracking.
 
 | Fat Plugin (Before) | Thin FreeFlow (Now) |
 | :--- | :--- |
-| `src/normalizer.ts` 200 LOC duplicates host | Deleted — host `pi-ai` owns 11 `thinkingFormat` |
+| `src/normalizer.ts` 200 LOC duplicates host | Deleted — host `pi-ai` owns 10 `thinkingFormat` |
 | Live fetch 10s in subagent → timeout | Disk-only 24h, proxy-only |
 | 400 loops N× relays | Narrow 429/5xx only, 400 surfaces instantly |
 | `GET /v1/models?foo` leaks paid | Pathname-guarded |
 
-**Result: <500 LOC core, 39 tests PASS, typecheck PASS.**
+**Result: ~3.6k LOC total, 53 tests PASS, typecheck PASS.**
 
 ---
 
@@ -216,8 +261,6 @@ We use OpenCode Zen & Kilo free tiers. You pay only with your own Cloudflare/Ver
 
 ### Contributing
 
-> "I shipped 10 parallel subagents on 1M context, zero keys, zero 429s. FreeFlow did the rolling, Pi did the thinking."
-
 ```bash
 git clone https://github.com/trefeon/pi-freeflow
 pnpm install

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-freeflow",
 	"type": "module",
-	"version": "1.4.1",
+	"version": "1.4.2",
 	"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",
@@ -23,6 +23,9 @@
 		"url": "git+https://github.com/trefeon/pi-freeflow.git"
 	},
 	"homepage": "https://github.com/trefeon/pi-freeflow#readme",
+	"engines": {
+		"node": ">=22.6.0"
+	},
 	"omp": {
 		"extensions": [
 			"./extensions"

package/src/commands.ts

@@ -410,7 +410,19 @@ export function createCommandSpec(
 					);
 				} else if (arg.startsWith("level")) {
 					const lvl = arg.split(/\s+/)[1] as LogLevel | undefined;
-					if (lvl && lvl in LOG_LEVEL_ORDER) {
+					// Allowlist only levels that actually have emitters. 'audit' exists in
+					// LOG_LEVEL_ORDER but nothing ever logs at it, so accepting it here
+					// silently suppressed ALL log output until manually reset.
+					const EMITTED_LEVELS: readonly LogLevel[] = [
+						"debug",
+						"info",
+						"warn",
+						"error",
+					];
+					if (
+						lvl &&
+						(EMITTED_LEVELS as readonly string[]).includes(lvl)
+					) {
 						saveDebugState({ debug: false, level: lvl });
 						ctx.ui.notify(
 							`Log level set to ${lvl} (persisted to ${DEBUG_STATE_FILE})`,

package/src/relay-state.ts

@@ -41,6 +41,32 @@ export function loadRelayState(): RelayState {
 	}
 }
 
+/** Block synchronously for ms without burning CPU. */
+function sleepSync(ms: number): void {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, Date.now() + ms);
+}
+
+/**
+ * Rename with bounded retry: Windows briefly locks the target when another
+ * process holds the state file open, surfacing as EPERM/EACCES/EBUSY.
+ * Three attempts with a fixed 50ms backoff; any other error fails immediately.
+ */
+function renameWithRetry(from: string, to: string): void {
+	const retryable: Record<string, true> = { EPERM: true, EACCES: true, EBUSY: true };
+	for (let attempt = 1; ; attempt++) {
+		try {
+			fs.renameSync(from, to);
+			return;
+		} catch (e) {
+			const code = (e as NodeJS.ErrnoException | null)?.code;
+			if (!code || !retryable[code] || attempt >= 3) {
+				throw e;
+			}
+			sleepSync(50);
+		}
+	}
+}
+
 /**
  * Atomically save relay state to disk using a temporary file and rename.
  */
@@ -52,7 +78,7 @@ export function saveRelayState(s: RelayState): void {
 		}
 		const tmpPath = `${RELAY_STATE_FILE}.${randomUUID()}.tmp`;
 		fs.writeFileSync(tmpPath, JSON.stringify(s, null, 2), "utf8");
-		fs.renameSync(tmpPath, RELAY_STATE_FILE);
+		renameWithRetry(tmpPath, RELAY_STATE_FILE);
 	} catch (e) {
 		logWarn("Could not persist relay state", { error: String(e) });
 	}
@@ -212,10 +238,13 @@ export function markRelayFailure(url: string, status?: number, error?: string):
 		cooldownMs = 45_000; // 45s for 5xx errors
 	}
 
+	// Escalate with consecutive failures so chronic offenders back off up to
+	// 4x their base cooldown instead of re-hammering at a fixed interval.
+	const multiplier = Math.min(4, consecutive);
 	relayHealthMap.set(clean, {
 		consecutiveFailures: consecutive,
 		lastFailureTime: now,
-		cooldownUntil: now + cooldownMs,
+		cooldownUntil: now + cooldownMs * multiplier,
 		lastStatus: status,
 		lastError: error,
 	});
@@ -370,9 +399,9 @@ export function getOrderedRelayUrls(): string[] {
 		const cooling = rawOrdered.filter((u) => !isRelayHealthy(u));
 		const ordered = [...healthy, ...cooling];
 
-		return ordered.length > 0 ? ordered : [DEFAULT_RELAY_URL];
+		return ordered;
 	}
-	return [DEFAULT_RELAY_URL];
+	return [];
 }
 
 /**

package/src/relay.ts

@@ -27,7 +27,6 @@ export function isRetriableStatus(status: number): boolean {
 	return (
 		status === 429 ||
 		status === 408 ||
-		status === 500 ||
 		status === 502 ||
 		status === 503 ||
 		status === 504 ||
@@ -56,6 +55,14 @@ export async function relayFetch(
 	}
 
 	const candidates = getOrderedRelayUrls();
+
+	if (candidates.length === 0) {
+		// Empty pool: skip straight to upstream instead of logging a misleading
+		// "relays bypassed/exhausted" WARN on every request.
+		log("debug", `relayFetch: direct (empty relay pool) -> ${url}`, undefined, rid);
+		return fetch(url, opts);
+	}
+
 	let lastResponse: Response | null = null;
 	let lastError: unknown = null;
 	const u = new URL(url);
@@ -109,6 +116,7 @@ export async function relayFetch(
 			// Fast fallback directly to upstream instead of cycling through multiple 25s timeouts.
 			if (res.status === 504) {
 				markRelayFailure(targetUrl, 504, "Gateway Timeout (25s exceeded)");
+				res.body?.cancel().catch(() => {});
 				log(
 					"warn",
 					`relay ${targetUrl} hit HTTP 504 Gateway Timeout in ${elapsed}s (prompt evaluation exceeded Vercel 25s limit) — fast fallback to direct upstream`,
@@ -120,6 +128,7 @@ export async function relayFetch(
 
 			if (isRetriableStatus(res.status)) {
 				markRelayFailure(targetUrl, res.status);
+				lastResponse?.body?.cancel().catch(() => {});
 				lastResponse = res;
 				log(
 					"warn",

package/src/stream-pipe.ts

@@ -34,6 +34,12 @@ export function pipeUpstreamStream(
 	const startAt = Date.now();
 	const isResponsesApi = req.url?.includes("/responses") ?? false;
 	let hasTerminalEvent = false;
+	// Abort-cause tracking: only genuine upstream-side truncation may penalize
+	// relay health. Client disconnects and clean upstream ends must not.
+	let upstreamEnded = false;
+	let clientAborted = false;
+	const TERMINAL_HEAD_SCAN_BYTES = 2000;
+	const TERMINAL_TAIL_SCAN_BYTES = 2000;
 
 	const sniffThinking = (chunk: Buffer | string): boolean => {
 		const s =
@@ -59,10 +65,15 @@ export function pipeUpstreamStream(
 			s.includes("[DONE]")
 		);
 	};
-
-	const ensureTerminalEvent = (isError = false, errorMsg?: string) => {
+	const ensureTerminalEvent = (
+		isError = false,
+		errorMsg?: string,
+		penalizeRelay = true,
+	) => {
 		if (hasTerminalEvent || res.writableEnded) return;
-		if (relayUrl && relayUrl !== "direct") {
+		// Only genuine upstream-side truncation penalizes relay health.
+		// Client disconnects and clean upstream ends leave it untouched.
+		if (penalizeRelay && relayUrl && relayUrl !== "direct") {
 			markRelayFailure(relayUrl, 0, errorMsg || "stream truncated prematurely");
 		}
 		if (isResponsesApi && totalChunks > 0) {
@@ -125,11 +136,19 @@ export function pipeUpstreamStream(
 					);
 				}
 			}
-
-			const strPreview =
-				typeof chunk === "string"
-					? chunk
-					: chunk.toString("utf8", 0, Math.min(chunk.length, 2000));
+			let strPreview: string;
+			if (typeof chunk === "string") {
+				strPreview = chunk;
+			} else if (chunk.length <= TERMINAL_HEAD_SCAN_BYTES) {
+				strPreview = chunk.toString("utf8");
+			} else {
+				// Coalesced final chunks can carry "[DONE]" well past the head —
+				// scan the tail too so healthy completions are not penalized.
+				strPreview = `${chunk.toString("utf8", 0, TERMINAL_HEAD_SCAN_BYTES)}\n${chunk.toString(
+					"utf8",
+					chunk.length - TERMINAL_TAIL_SCAN_BYTES,
+				)}`;
+			}
 			if (!hasTerminalEvent && checkTerminalEvent(strPreview)) {
 				hasTerminalEvent = true;
 			}
@@ -163,9 +182,16 @@ export function pipeUpstreamStream(
 	});
 
 	nodeStream.on("end", () => {
+		upstreamEnded = true;
 		const elapsed = ((Date.now() - startAt) / 1000).toFixed(1);
 		if (!hasTerminalEvent && totalChunks > 0) {
-			ensureTerminalEvent(false);
+			// Clean upstream end without a detectable marker: keep the host
+			// contract (synthetic terminal) but never blame the relay.
+			ensureTerminalEvent(
+				false,
+				"upstream ended without terminal marker",
+				false,
+			);
 		}
 		if (thinkingChunks > 0) {
 			log(
@@ -190,26 +216,48 @@ export function pipeUpstreamStream(
 	nodeStream.on("close", () => {
 		try {
 			if (!hasTerminalEvent && totalChunks > 0) {
-				ensureTerminalEvent(true, "stream closed prematurely");
+				if (clientAborted || upstreamEnded) {
+					// Client disconnect teardown or post-end cleanup — the relay
+					// is not at fault; still give the host a terminal event.
+					ensureTerminalEvent(false, "stream interrupted by client", false);
+				} else {
+					// Upstream socket died mid-stream with no error event:
+					// genuine upstream truncation — penalize the relay.
+					ensureTerminalEvent(true, "stream closed prematurely");
+				}
 			}
 			if (!res.writableEnded) res.end();
 		} catch {}
 	});
 
 	req.on("aborted", () => {
+		clientAborted = true;
 		log("warn", "client aborted — destroying upstream", { totalChunks }, rid);
 		if (!nodeStream.destroyed) nodeStream.destroy();
 	});
 
 	req.on("close", () => {
-		if (!nodeStream.destroyed) nodeStream.destroy();
+		if (!upstreamEnded && !nodeStream.destroyed) {
+			clientAborted = true;
+			nodeStream.destroy();
+		}
 	});
 
 	res.on("close", () => {
-		if (!nodeStream.destroyed) nodeStream.destroy();
+		if (
+			!upstreamEnded &&
+			!res.writableEnded &&
+			!nodeStream.destroyed
+		) {
+			clientAborted = true;
+			nodeStream.destroy();
+		}
 	});
 
 	res.on("error", () => {
-		if (!nodeStream.destroyed) nodeStream.destroy();
+		if (!upstreamEnded && !nodeStream.destroyed) {
+			clientAborted = true;
+			nodeStream.destroy();
+		}
 	});
 }