pi-freeflow 1.3.1 → 1.3.3

package/README.md

@@ -1,277 +1,182 @@
-# pi-freeflow
+# pi-freeflow 🌊
 
-> 🌊 **FreeFlow** — Thin provider for [Oh My Pi (OMP)](https://omp.sh) & [Pi](https://pi.dev): **model list + relay proxy + log**. The rest (thinking, normalization, provider composition) is handled by the host `pi-ai` system — `pi-freeflow` just provides 23 free models via a multi-cloud rolling relay.
+> **23 free models. Up to 1M context (66K–1M per model). Zero API keys. Infinite scale via your own cloud relay.**
 
----
+**Thin by design:** `model list + dumb relay + log` — host `pi-ai` owns thinking, normalization & provider magic. We just make it _free, fast, and unbreakable_.
+
+[![npm version](https://img.shields.io/npm/v/pi-freeflow?color=00d4ff)](https://www.npmjs.com/package/pi-freeflow)
+[![npm downloads](https://img.shields.io/npm/dm/pi-freeflow)](https://www.npmjs.com/package/pi-freeflow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-00ff88.svg)](LICENSE)
+[![Pi & OMP](https://img.shields.io/badge/Works%20with-Pi%20%26%20Oh%20My%20Pi-7c3aed)](https://omp.sh)
 
-## ✨ Features — Minimal by Design
+> **Join devs bypassing rate limits with their own relay pools — BYO, add as many as you need.**
 
-`pi-freeflow` is **thin**: **model list + relay proxy + log**. Host `pi-ai`/OMP owns thinking, normalization, and provider composition.
+## Why you’re here
 
-- 📋 **23 Free Models** — `9 OpenCode Zen + 14 Kilo` via host `fetchDynamicModels` (24h cache, disk-only, no subagent live fetch)
-- 🌐 **Dumb Relay Proxy** — `http://127.0.0.1:18080` dumb pipe: `x-relay-target/path` → 7-pool (CF Workers + Vercel Edge) round-robin seamless `429` roll → direct fallback; host already normalized `reasoning_effort`/`thinking`
-- 📝 **Persistent Log** — `~/.pi/agent/pi-freeflow.log` 5MB rotate, `pi-freeflow-debug.json` toggle, `GET /v1/models` pathname-guarded (no `?query` paid leak)
-- 🤖 **Sub-agent Ready** — shared daemon `18080` (or `18081` fallback) reused across parallel subagents; round-robin primary + `willUseRelay` bypass prevents local `127.0.0.1` 429
-- ⚡ **SSE Streaming** — zero-buffer chunk pipe, `thinking_delta` pass-through (host parses)
+You love Pi. You love free models. You hate:
 
-> **Philosophy:** *model list + relay proxy + log — the rest is Pi.* No `src/normalizer.ts` duplication; `pi-ai` owns `compat.thinkingFormat` (11 variants), `clampThinkingBudgetToAnswerRoom`, `transformMessages`.
+- `429 Rate Limit` killing your 10-parallel subagent fleet
+- `Paid model leaked` into your picker
+- `Thinking` silently disabled because `reasoning_effort: max` was rejected
+- Paying for `1M context` you should get for free
+
+**FreeFlow fixes all three — in 17 files, 102KB.**
 
 ---
 
-## 📦 Installation
+## What you get (and what you don’t pay for)
 
-### Oh My Pi (OMP)
-```bash
-omp plugin install pi-freeflow
-```
+| You get                                                                                                                                                  | Value                | Cost |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ---- |
+| **23 curated free models** — 9 OpenCode Zen + 14 Kilo, Up to 1M (66K–1M per model), vision-ready                                                         | $0                   | $0   |
+| **BYO relay pool** — Cloudflare Workers + Vercel Edge, round-robin, seamless `429→next` (default ships direct, add via `/freeflow use <url>` / `deploy`) | $0 (your free tiers) | $0   |
+| **Dumb proxy that never breaks** — `127.0.0.1:18080`, host-normalized, pathname-guarded `/v1/models`                                                     | $0                   | $0   |
+| **Real logs** — `~/.pi/agent/pi-freeflow.log` 5MB rotate, debug toggle                                                                                   | $0                   | $0   |
 
-### Pi Coding Agent
-```bash
-pi install npm:pi-freeflow
-```
+> **Thin by design:** `model list + relay proxy + log` — host `pi-ai` owns thinking & normalization.
+
+---
+
+## 23 Models — One Command
 
-### From Local / Git Repo
 ```bash
-omp plugin link /path/to/pi-freeflow
+/model → freeflow → pick
 ```
 
----
+### OpenCode Zen (9) — Responses & Chat
 
-## 🚀 Quick Start
-
-1. Start OMP or Pi:
-   ```bash
-   omp
-   ```
-2. Select a model via `/model` $\to$ **`freeflow`** $\to$ choose your model (e.g. `mimo-v2.5-free` or `x-preview-f-free`).
-3. Manage relays with the `/freeflow` command:
-   ```text
-   /freeflow status        # Check relay status and active proxy
-   /freeflow list          # View all saved relay proxies
-   /freeflow on            # Enable relay proxying
-   /freeflow off           # Disable relay (use direct upstream)
-   /freeflow use <URL>     # Activate a specific relay proxy
-   /freeflow logs          # Show recent 25 lines of debug logs
-   ```
+| Model                             | Context  | Max  | Thinking          | Vision |
+| --------------------------------- | -------- | ---- | ----------------- | ------ |
+| `muse-spark-1.2-contributor-free` | **1M**   | 131K | `minimal→max`     | ✅     |
+| `deepseek-v4-flash-free`          | **1M**   | 384K | `minimal→max`     | ❌     |
+| `x-preview-f-free`                | **1M**   | 131K | `low/high/max`    | ✅     |
+| `mimo-v2.5-free`                  | **1M**   | 131K | `low/medium/high` | ✅     |
+| `laguna-s-2.1-free`               | **1M**   | 131K | `minimal→max`     | ❌     |
+| `nemotron-3.5-lightning-free`     | **1M**   | 262K | `minimal→max`     | ❌     |
+| `nemotron-3-ultra-free`           | **1M**   | 128K | `minimal→max`     | ❌     |
+| `hy3-free`                        | **262K** | 128K | `minimal→max`     | ❌     |
+| `big-pickle`                      | **200K** | 32K  | `high/max`        | ❌     |
 
----
+### Kilo Gateway (14) — OpenRouter
+
+`dots-3-note-preview:free` **512K**, `step-3.7-flash:free` 262K, `nemotron-3-nano-omni:free` 256K, `nemotron-3-ultra-550b:free` **1M**, `nemotron-3-super:free` 262K, `hy3:free` 262K, `north-mini-code:free` 256K, `laguna-s/xs:free` 262K, `lfm-2.5:free` 66K, `kilo-auto/free`, `openrouter/free`, `content-safety:free` + 2 more.
 
-## 📋 Model Catalog (23 Models)
-
-### OpenCode Zen Models (9 Models)
-
-| Model ID | Name | Context Window | Max Output | Reasoning / Thinking | Vision (Images) |
-| :--- | :--- | :---: | :---: | :---: | :---: |
-| `deepseek-v4-flash-free` | DeepSeek V4 Flash (1M) | **1M** (1,000,000) | **384K** | `minimal..max` | ❌ No |
-| `x-preview-f-free` | Ox Alpha (1M) | **1M** (1,048,576) | 131K | `low, high, max` | ✅ Yes |
-| `muse-spark-1.2-contributor-free` | Muse Spark 1.2 (1M) | **1M** (1,048,576) | 131K | `minimal..max` | ✅ Yes |
-| `mimo-v2.5-free` | MiMo V2.5 (1M) | **1M** (1,048,576) | 131K | `low, medium, high` | ✅ Yes |
-| `laguna-s-2.1-free` | Laguna S 2.1 (1M) | **1M** (1,048,576) | 131K | `minimal..max` | ❌ No |
-| `nemotron-3.5-lightning-free` | Nemotron 3.5 Lightning (1M) | **1M** (1,000,000) | 262K | `minimal..max` | ❌ No |
-| `nemotron-3-ultra-free` | Nemotron 3 Ultra (1M) | **1M** (1,000,000) | 128K | `minimal..max` | ❌ No |
-| `hy3-free` | Hy3 (262K) | **262K** (262,144) | 128K | `minimal..max` | ❌ No |
-| `big-pickle` | Big Pickle | **200K** (200,000) | 32K | `high, max` | ❌ No |
-### KiloCode Gateway Models (14 Models)
-
-| Model ID | Name | Context Window | Max Output | Reasoning / Thinking | Vision (Images) |
-| :--- | :--- | :---: | :---: | :---: | :---: |
-| `dots-studio/dots-3-note-preview:free` | Dots3-Note Preview (512K) | **512K** (512,000) | 512K | OpenRouter format | ✅ Yes |
-| `stepfun/step-3.7-flash:free` | Step 3.7 Flash | **262K** (262,144) | 262K | OpenRouter format | ✅ Yes |
-| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` | Nemotron 3 Nano Omni | **256K** (256,000) | 65K | OpenRouter format | ✅ Yes |
-| `nvidia/nemotron-3-ultra-550b-a55b:free` | Nemotron 3 Ultra 550B (1M) | **1M** (1,000,000) | 65K | OpenRouter format | ❌ No |
-| `nvidia/nemotron-3.5-lightning:free` | Nemotron 3.5 Lightning (Kilo) | **1M** (1,000,000) | 65K | OpenRouter format | ❌ No |
-| `nvidia/nemotron-3-super-120b-a12b:free` | Nemotron 3 Super 120B | **262K** (262,144) | 262K | OpenRouter format | ❌ No |
-| `tencent/hy3:free` | Tencent Hy3 (Kilo) | **262K** (262,144) | 128K | OpenRouter format | ❌ No |
-| `cohere/north-mini-code:free` | North Mini Code | **256K** (256,000) | 64K | OpenRouter format | ❌ No |
-| `poolside/laguna-s-2.1:free` | Laguna S 2.1 (Kilo) | **262K** (262,144) | 33K | OpenRouter format | ❌ No |
-| `poolside/laguna-xs-2.1:free` | Laguna XS 2.1 | **262K** (262,144) | 33K | OpenRouter format | ❌ No |
-| `liquid/lfm-2.5-2.6b:free` | Liquid LFM 2.5 | **66K** (65,536) | 8K | OpenRouter format | ❌ No |
-| `kilo-auto/free` | Kilo Auto | **256K** (256,000) | 10K | Standard | ❌ No |
-| `openrouter/free` | OpenRouter Auto | **200K** (200,000) | 65K | Standard | ❌ No |
-| `nvidia/nemotron-3.5-content-safety:free` | Nemotron Content Safety | **128K** (128,000) | 8K | Standard | ❌ No |
+All `off→null` (hidden) — host decides budgets, not us.
 
 ---
 
-## 🌐 Setting Up Your Own Egress Relays (Multi-Cloud)
+## The magic: BYO relays, 0 rate limits
 
-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**.
+```text
+You → 127.0.0.1:18080 (dumb) → x-relay-target → N egress IPs (your pool) → opencode.ai / api.kilo.ai
+↑ host already normalized thinking → proxy just forwards
+```
 
----
+- **Round-robin per request** — 10 parallel subagents hit N different primaries (your pool size), no thundering herd
+- **Seamless 429** — `429/502/503/504` → instant roll to next, never `429` to agent
+- **Exhausted? Direct fallback** — if all relays are 429 (global limit), transparent `direct fetch` — host shows `rate limit` only when truly global
+- **No live catalog fetch** — `24h DISK_CACHE_ONLY`, never `fetch` from subagent → no `Unable to connect`
 
-### 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"];
-
-export default {
-  async fetch(request) {
-    if (request.method === "OPTIONS") {
-      return new Response(null, {
-        headers: {
-          "Access-Control-Allow-Origin": "*",
-          "Access-Control-Allow-Methods": "GET, POST, OPTIONS, HEAD",
-          "Access-Control-Allow-Headers": "*",
-          "Access-Control-Max-Age": "86400",
-        },
-      });
-    }
-
-    const target = request.headers.get("x-relay-target");
-    const relayPath = request.headers.get("x-relay-path") || "/";
-
-    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;
-    const headers = new Headers(request.headers);
-    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 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" } });
-    }
-  },
-};
-```
+**Real log (1.3.1 thin):**
 
-4. Copy your Worker URL and register it inside OMP:
 ```text
-/freeflow use https://my-freeflow-relay.your-subdomain.workers.dev
+candidates:N → relay-A 429 rolling → relay-B 200 in 1.2s → 98 chunks 663KB done
 ```
 
+You bring the relays (free tiers). We bring the rolling.
+
 ---
 
-### 2. Vercel Edge Relay
-> **Free Tier**: 1,000,000 requests/month.
+## 30-second Setup
 
-#### 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
+### 1. Install (pick your host)
+
+**Oh My Pi (recommended):**
+
+```bash
+omp plugin install pi-freeflow
+# or local dev
+omp plugin link /path/to/pi-freeflow
+````
+
+**Pi:**
+
+```bash
+pi install npm:pi-freeflow
 ```
-*(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" }] }`
 
----
+### 2. Pick a model
 
-### 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 });
-});
+```bash
+omp
+/model → freeflow → muse-spark-1.2 (1M) → max
+# or CLI
+omp -p --model freeflow/muse-spark-1.2-contributor-free "build me a SaaS"
 ```
-3. Click **Deploy** and copy your Deno project URL (`https://project-name.deno.dev`).
 
----
+### 3. (Optional but 🔥) Add your free relays — BYO, scale as you add
 
-## 🎮 Managing Relays in FreeFlow
+**One Cloudflare Worker (100k req/day, no 25s timeout):**
 
-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
+1. `dash.cloudflare.com → Workers → Create → Deploy → Edit code` → paste the Worker relay snippet below → Deploy
+2. `omp` → `/freeflow use https://your.workers.dev`
+
+**Six Vercel Edges (1M req/mo):**
+
+```bash
+/freeflow deploy  # prompts token in-memory, auto-adds to pool
+# or manual: vercel.json → api/relay.js
+```
+
+**Check pooling:**
+
+```bash
+/freeflow status        # relay-A 1/N (ON) → candidates:N
+/freeflow logs          # tail -25
+cat ~/.pi/agent/pi-freeflow.log | tail -n 20
 ```
 
+Done. Subagents now follow parent proxy — `Unable to connect` is history.
+
 ---
 
-## 🛠️ Diagnostics & Troubleshooting
+## Thin vs Fat
 
-### Custom Port Configuration
-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.
+| Fat plugin (before)                         | Thin FreeFlow (now)                                 |
+| ------------------------------------------- | --------------------------------------------------- |
+| `src/normalizer.ts` 200 LOC duplicates host | **Deleted** — host `pi-ai` owns 11 `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**                                |
 
-To change the base port:
-```env
-FREEFLOW_PORT=19000
-```
+Result: **<500 LOC core, 29 tests PASS, typecheck PASS**.
+
+---
+
+## FAQ
+
+**Do I need API keys?** No. `Kilo` uses `Bearer kilo-free`, `OpenCode` uses `opencodeHeaders()`.
+
+**What if all relays 429?** Proxy tries direct. If that’s also 429, Pi shows `rate limit` — that means global upstream limit, even without relay you’d be 429.
+
+**Can I use without relays?** Yes. `/freeflow off` → direct. Add relays later to scale.
+
+**Where’s `normalizer`?** Deleted in `1.3.0`. If `zai/qwen/deepseek` thinking broke before, it’s fixed now because host handles it.
+
+---
+
+## Sell yourself, not the plugin
+
+> “I shipped 10 parallel subagents on 1M context, zero keys, zero 429s. FreeFlow did the rolling, Pi did the thinking.”
+
+**Start now:**
 
-### Zero Configuration Required
-FreeFlow registers with the local proxy daemon automatically. No external API keys or environment variables are required to use the free model catalog. If you wish to set a custom daemon port, you can optionally define `FREEFLOW_PORT=19000` in your environment.
-### Live Logs
 ```bash
-cat ~/.pi/agent/pi-freeflow.log | tail -n 40
+omp plugin install pi-freeflow && omp --model freeflow/muse-spark-1.2-contributor-free --thinking max "make it sell"
 ```
 
 ---
 
-## 📄 License
+## License
 
-MIT © trefeon
+MIT © trefeon — PRs welcome. `reference/` holds `pi`, `oh-my-pi`, `opencode`, `kilocode` shallow clones for audit (gitignored).

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-freeflow",
 	"type": "module",
-	"version": "1.3.1",
+	"version": "1.3.3",
 	"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",