pi-freeflow 1.3.8 → 1.4.0

package/README.md

@@ -14,57 +14,66 @@ Thin by design: model list + dumb relay + log. Host `pi-ai` owns thinking, norma
 
 ---
 
-### Why FreeFlow?
-
-You love Pi. You love free models. You hate:
-
-- **429 Rate Limit** killing your 10-parallel subagent fleet
-- Paid models leaking into your picker
-- `reasoning_effort: max` rejected and thinking silently disabled
-- Paying for 1M context you should get for free
-
-**FreeFlow fixes all three — in 17 files, 102KB.**
-
-### Features
-
-| What You Get | Value | Cost |
-| :--- | :--- | :--- |
-| **23 Curated Free Models** — 9 OpenCode Zen + 14 Kilo, 66K-1M context, vision-ready | Unlimited | **$0** |
-| **BYO Relay Pool** — Cloudflare Workers + Vercel Edge, round-robin, seamless `429 → next` | Auto-scale | **$0** (your free tiers) |
-| **Dumb Proxy That Never Breaks** — `127.0.0.1:18080`, host-normalized, pathname-guarded `/v1/models` | 100% uptime | **$0** |
-| **Real Logs** — `~/.pi/agent/pi-freeflow.log`, 5MB rotate, debug toggle | Observable | **$0** |
+### Features at a Glance
+
+| Feature | Description | Value | Cost |
+| :--- | :--- | :--- | :--- |
+| **23 Curated Free Models** | 9 OpenCode Zen + 14 KiloCode Gateway models, up to 1M context & 512K output | Ceiling Unlocked | **$0** |
+| **BYO Relay Pool** | Round-robin load balancing across your Cloudflare Workers & Vercel Edges | Zero Rate Limits | **$0** (your free tiers) |
+| **Adaptive Health & Error Detection** | Auto-cooldown on 429 rate limits, 504 timeouts, and socket drops | 0ms Wasted Latency | **$0** |
+| **Stream Truncation Resilience** | Stateful SSE terminal tracking (`response.failed` / `response.incomplete` injection) | Zero Host Crashes | **$0** |
+| **Smart Model Aliasing** | Clean slash-free & colon-free CLI model names compatible with thinking selectors | DX Optimized | **$0** |
+| **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:18080`, 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** |
 
 Philosophy: **Thin by design.** We only ship model list + relay proxy + log. Host owns thinking & normalization.
 
 ---
 
-### 23 Models — One Command
+### 23 Curated Models — One Command
 
 ```bash
 /model → freeflow → pick
 ```
 
-#### OpenCode Zen (9) — Responses & Chat API
-Best for long-context reasoning. All vision-ready models marked.
-
-| Model | Context | Max Output | Thinking | Vision |
-| :--- | :--- | :--- | :--- | :--- |
-| `claude-sonnet-4.5-free` / `muse-spark-1.2-contributor-free` | 1M | 131K | `minimal → max` | ✅ |
-| `deepseek-v4-flash-free` | 1M | 384K | `minimal → max` | ❌ |
-| `grok-code-fast-1-preview-f-free` / `x-preview-f-free` | 1M | 131K | `low / high / max` | ✅ |
-| `mimo-v2.5-free` | 1M | 131K | `low / medium / high` | ✅ |
-| `minimax-m2.1-free` / `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` | ❌ |
-| `qwen3-coder-480b-free` / `hy3-free` | 262K | 128K | `minimal → max` | ❌ |
-| `big-pickle` | 200K | 32K | `high / max` | ❌ |
+#### OpenCode Zen (9 Models) — Responses & Chat API
+Optimized for deep reasoning, long-horizon coding & autonomous agentic workflows.
+
+| Model ID | Creator / Lab | Context | Max Output | Thinking | Vision |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `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` | ❌ |
+| `big-pickle` | Big Pickle | **200K** (200.000) | **32K** (32.000) | `high / max` | ❌ |
+
+#### KiloCode Gateway (14 Models) — OpenRouter Compatible
+Keyless access with `Bearer kilo-free`. Clean slash-free and colon-free CLI aliases supported.
+
+| 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` | ✅ |
+| `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) | ❌ |
+| `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) | ❌ |
+| `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) | ❌ |
+| `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)* | ✅ |
+| `content-safety` (`nvidia/...:free`) | NVIDIA | **128K** (128.000) | **8K** (8.192) | ❌ *(non-thinking)* | ✅ |
 
-#### Kilo Gateway (14) — OpenRouter Compatible
-Zero-config, `Bearer kilo-free`.
-
-`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), `minimax-m2.1/xs:free` (262K), `lfm-2.5:free` (66K), `kilo-auto/free`, `openrouter/free`, `content-safety:free` + 2 more.
-
-> All `off → null` (hidden). Host decides token budgets, not us.
+---
 
 ### How It Works — The Magic: BYO Relays, Zero Rate Limits
 
@@ -73,16 +82,36 @@ You → 127.0.0.1:18080 (dumb proxy, host-normalized) → x-relay-target → N e
                                      ↑ host already normalized thinking → proxy just forwards
 ```
 
-- **Round-robin per request** — 10 parallel subagents hit N different egress IPs (your pool size). No thundering herd.
-- **Seamless 429 roll** — `429 / 502 / 503 / 504` → instant roll to next relay, 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`.
-- **Real log (v1.3.1 thin):** `candidates:N → relay-A 429 rolling → relay-B 200 in 1.2s → 98 chunks 663KB done`
+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.
+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.
 
 You bring the relays (free tiers). We bring the rolling.
 
 ---
 
+### Interactive Commands Reference (`/freeflow`)
+
+Manage your relay pool directly from the OMP / Pi terminal:
+
+```bash
+/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 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 on | off | auto         # Toggle relay mode (auto = enabled for freeflow)
+/freeflow deploy                  # Guided auto-deploy 6 Vercel Edge relays (in-memory token)
+/freeflow logs [lines]            # Inspect recent proxy logs
+/freeflow debug on | off          # Toggle full HTTP lifecycle debug logging
+```
+
+---
+
 ### Quick Start — 30 Seconds
 
 #### 1. Install
@@ -103,39 +132,41 @@ pi install npm:pi-freeflow
 
 ```bash
 omp
-/model → freeflow → claude-sonnet-4.5 (1M) → max
+/model → freeflow → muse-spark-1.2-contributor-free (1M) → max
 
 # or CLI
-omp -p --model freeflow/claude-sonnet-4.5-contributor-free "build me a SaaS"
+omp -p --model freeflow/muse-spark-1.2-contributor-free "build me a SaaS"
+# or with short alias & thinking level
+omp -p --model freeflow/step-3.7-flash:high "solve this bug"
 ```
 
-#### 3. (Optional but 🔥) Add Your Free Relays
+#### 3. Add Your Free Relays (Scale Infinitely)
 
-Scale infinitely. Default ships direct, add relays via `/freeflow use <url>`.
+Default ships direct. Add relays via `/freeflow add <url> [label]`.
 
-**Option A: One Cloudflare Worker (100k req/day, no 25s timeout)**
+**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`
 3. Deploy and add it:
 
 ```bash
-omp → /freeflow use https://your.workers.dev
+omp → /freeflow add https://your.workers.dev cf-worker-1
 ```
 
 **Option B: Six Vercel Edges (1M req/mo) — Auto Deploy**
 ```bash
 /freeflow deploy  # prompts token in-memory, auto-adds to pool
-# or manual: vercel.json → api/relay.js
 ```
 
 **Verify your pool:**
 ```bash
 /freeflow status        # relay-A 1/N (ON) → candidates:N
+/freeflow list          # lists all relays with health status
 /freeflow logs          # tail -25
 cat ~/.pi/agent/pi-freeflow.log | tail -n 20
 ```
 
-Done. Subagents now follow parent proxy — `Unable to connect` is history.
+---
 
 ### Logs & Debugging
 
@@ -147,7 +178,9 @@ cat ~/.pi/agent/pi-freeflow.log | tail -n 50
 /freeflow debug on
 ```
 
-Log rotation at 5MB. Clean, parseable, real-time.
+Log rotation at 5MB. Clean, parseable, real-time HTTP lifecycle tracking.
+
+---
 
 ### Philosophy: Thin vs Fat
 
@@ -158,7 +191,9 @@ Log rotation at 5MB. Clean, parseable, real-time.
 | 400 loops N× relays | Narrow 429/5xx only, 400 surfaces instantly |
 | `GET /v1/models?foo` leaks paid | Pathname-guarded |
 
-**Result: <500 LOC core, 29 tests PASS, typecheck PASS.**
+**Result: <500 LOC core, 39 tests PASS, typecheck PASS.**
+
+---
 
 ### FAQ
 
@@ -177,6 +212,8 @@ Deleted in 1.3.0. If zai/qwen/deepseek thinking broke before, it's fixed now bec
 **Why is context free?**
 We use OpenCode Zen & Kilo free tiers. You pay only with your own Cloudflare/Vercel free tiers for egress.
 
+---
+
 ### Contributing
 
 > "I shipped 10 parallel subagents on 1M context, zero keys, zero 429s. FreeFlow did the rolling, Pi did the thinking."
@@ -195,5 +232,5 @@ MIT © trefeon
 
 Start now:
 ```bash
-omp plugin install pi-freeflow && omp --model freeflow/claude-sonnet-4.5-contributor-free --thinking max "make it sell"
+omp plugin install pi-freeflow && omp --model freeflow/muse-spark-1.2-contributor-free --thinking max "make it sell"
 ```

package/package.json

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

package/src/models.ts

@@ -87,7 +87,7 @@ export const OPENCODE_MODELS: ModelDef[] = [
 		name: "Hy3 (262K)",
 		reasoning: true,
 		contextWindow: 262_144,
-		maxTokens: 128_000,
+		maxTokens: 262_144,
 		input: ["text"],
 		thinkingLevelMap: {
 			off: null,
@@ -220,7 +220,7 @@ export const KILO_MODELS: ModelDef[] = [
 		name: "Nemotron 3.5 Lightning (Kilo)",
 		reasoning: true,
 		contextWindow: 1_000_000,
-		maxTokens: 65_536,
+		maxTokens: 131_072,
 		input: ["text"],
 		thinkingFormat: "openrouter",
 	},
@@ -238,9 +238,8 @@ export const KILO_MODELS: ModelDef[] = [
 		name: "Tencent Hy3 (Kilo)",
 		reasoning: true,
 		contextWindow: 262_144,
-		maxTokens: 128_000,
+		maxTokens: 262_144,
 		input: ["text"],
-		thinkingFormat: "openrouter",
 	},
 	{
 		id: "cohere/north-mini-code:free",
@@ -255,8 +254,8 @@ export const KILO_MODELS: ModelDef[] = [
 		id: "poolside/laguna-s-2.1:free",
 		name: "Laguna S 2.1 (Kilo)",
 		reasoning: true,
-		contextWindow: 262_144,
-		maxTokens: 32_768,
+		contextWindow: 1_048_576,
+		maxTokens: 131_072,
 		input: ["text"],
 		thinkingFormat: "openrouter",
 	},
@@ -273,8 +272,8 @@ export const KILO_MODELS: ModelDef[] = [
 		id: "liquid/lfm-2.5-2.6b:free",
 		name: "Liquid LFM 2.5",
 		reasoning: true,
-		contextWindow: 65_536,
-		maxTokens: 8_192,
+		contextWindow: 128_000,
+		maxTokens: 32_768,
 		input: ["text"],
 		thinkingFormat: "openrouter",
 	},
@@ -292,7 +291,7 @@ export const KILO_MODELS: ModelDef[] = [
 		reasoning: false,
 		contextWindow: 200_000,
 		maxTokens: 65_536,
-		input: ["text"],
+		input: ["text", "image"],
 	},
 	{
 		id: "nvidia/nemotron-3.5-content-safety:free",
@@ -300,7 +299,7 @@ export const KILO_MODELS: ModelDef[] = [
 		reasoning: false,
 		contextWindow: 128_000,
 		maxTokens: 8_192,
-		input: ["text"],
+		input: ["text", "image"],
 	},
 ];