pi-freeflow 1.3.9 → 1.4.1

package/README.md

@@ -14,71 +14,64 @@ 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, 115KB.**
-
-### Features
-
-| What You Get | Value | Cost |
-| :--- | :--- | :--- |
-| **23 Curated Free Models** — 9 OpenCode Zen + 14 Kilo Gateway, 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) |
-| **Adaptive Health & Error Detection** — Auto-cooldown on 429/504/socket drops, instant roll to healthy relays | Self-healing | **$0** |
-| **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 & autonomous agentic tasks.
+#### 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 | 131K | `minimal → max` | ✅ |
-| `x-preview-f-free` | Ox Alpha | 1M | 131K | `low / high / max` | ✅ |
-| `mimo-v2.5-free` | Xiaomi MiMo | 1M | 131K | `low / medium / high` | ✅ |
-| `deepseek-v4-flash-free` | DeepSeek | 1M | 384K | `minimal → max` | ❌ |
-| `laguna-s-2.1-free` | Poolside | 1M | 131K | `minimal → max` | ❌ |
-| `nemotron-3.5-lightning-free` | NVIDIA | 1M | 262K | `minimal → max` | ❌ |
-| `nemotron-3-ultra-free` | NVIDIA | 1M | 128K | `minimal → max` | ❌ |
-| `hy3-free` | Tencent Hunyuan | 262K | 262K | `minimal → max` | ❌ |
-| `big-pickle` | Big Pickle | 200K | 32K | `high / max` | ❌ |
-
-#### Kilo Gateway (14) — OpenRouter Compatible
-Keyless access with `Bearer kilo-free`. Short slash-free & colon-free CLI aliases supported.
+| `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 | 512K | `openrouter` (auto) | ✅ |
-| `step-3.7-flash` (`stepfun/...:free`) | StepFun | 262K | 262K | `low / medium / high` | ✅ |
-| `nemotron-3-nano-omni` (`nvidia/...:free`) | NVIDIA | 256K | 65K | `openrouter` (auto) | ✅ |
-| `nemotron-3-ultra-550b` (`nvidia/...:free`) | NVIDIA | 1M | 65K | `openrouter` (auto) | ❌ |
-| `nemotron-3.5-lightning` (`nvidia/...:free`) | NVIDIA | 1M | 131K | `openrouter` (auto) | ❌ |
-| `nemotron-3-super` (`nvidia/...:free`) | NVIDIA | 262K | 262K | `openrouter` (auto) | ❌ |
-| `hy3` (`tencent/hy3:free`) | Tencent Hunyuan | 262K | 262K | `openrouter` (auto) | ❌ |
-| `north-mini-code` (`cohere/...:free`) | Cohere | 256K | 64K | `openrouter` (auto) | ❌ |
-| `laguna-s-2.1` (`poolside/...:free`) | Poolside | 1M | 131K | `openrouter` (auto) | ❌ |
-| `laguna-xs-2.1` (`poolside/...:free`) | Poolside | 262K | 32K | `openrouter` (auto) | ❌ |
-| `lfm-2.5` (`liquid/lfm-2.5-2.6b:free`) | Liquid AI | 128K | 32K | `openrouter` (auto) | ❌ |
-| `kilo-auto` (`kilo-auto/free`) | Kilo Gateway Auto | 256K | 10K | ❌ | ❌ |
-| `openrouter` (`openrouter/free`) | OpenRouter Free | 200K | 65K | ❌ | ✅ |
-| `content-safety` (`nvidia/...:free`) | NVIDIA | 128K | 8K | ❌ | ✅ |
+| `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)* | ✅ |
 
 ---
 
@@ -89,17 +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.
-- **Adaptive Health & Error Cooldown** — Relays hitting 429, 504, or network socket drops enter automatic cooldown (30-90s) and move behind healthy candidates.
-- **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`.
-- **Stream Truncation Resilience** — Detects SSE terminal events; handles premature stream closure with clean termination.
+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
@@ -124,25 +136,26 @@ omp
 
 # or CLI
 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:**
@@ -153,7 +166,7 @@ omp → /freeflow use https://your.workers.dev
 cat ~/.pi/agent/pi-freeflow.log | tail -n 20
 ```
 
-Done. Subagents now follow parent proxy — `Unable to connect` is history.
+---
 
 ### Logs & Debugging
 
@@ -165,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
 
@@ -178,6 +193,8 @@ Log rotation at 5MB. Clean, parseable, real-time.
 
 **Result: <500 LOC core, 39 tests PASS, typecheck PASS.**
 
+---
+
 ### FAQ
 
 **Do I need API keys?**
@@ -195,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."

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-freeflow",
 	"type": "module",
-	"version": "1.3.9",
+	"version": "1.4.1",
 	"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/index.ts

@@ -139,11 +139,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 
 	// 3. Instant 0ms Static Catalog Registration
 	// Register static models immediately on boot so Pi/OMP picker is populated with zero latency!
-	const registeredCatalog: RegisteredModel[] = getAllRegisteredModels().map((m) => ({
+	const registeredCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
 		...m,
 		source: KILO_MODEL_IDS.has(m.id) ? "kilo" : "opencode",
 	}));
-	setAliveCatalog(ALL_MODELS.map((m) => ({ ...m, source: KILO_MODEL_IDS.has(m.id) ? "kilo" : "opencode" })));
+	setAliveCatalog(registeredCatalog);
 	pi.registerProvider(
 		"freeflow",
 		buildProviderConfig(registeredCatalog, actualPort),

package/src/models.ts

@@ -357,36 +357,29 @@ export const KILO_MODEL_IDS = new Set<string>([
 ]);
 
 /**
- * Combined list of all 23 static free models
+ * Combined list of all 23 static free models (canonical)
  */
 export const ALL_MODELS: ModelDef[] = [...OPENCODE_MODELS, ...KILO_MODELS];
 
 /**
  * Map of model ID -> ModelDef
  */
-export const MODEL_MAP = new Map<string, ModelDef>([
-	...ALL_MODELS.map((m): [string, ModelDef] => [m.id, m]),
-	...Object.entries(MODEL_ALIASES).map(([aliasId, canonicalId]): [string, ModelDef] => {
-		const base = ALL_MODELS.find((m) => m.id === canonicalId);
-		return [
-			aliasId,
-			base
-				? { ...base, id: aliasId }
-				: { id: aliasId, name: aliasId, reasoning: false, contextWindow: 200_000, maxTokens: 32_000, input: ["text"] },
-		];
-	}),
-]);
+export const MODEL_MAP = new Map<string, ModelDef>(
+	ALL_MODELS.map((m): [string, ModelDef] => [m.id, m]),
+);
+
 /**
- * Lookup a model definition by ID
+ * Get full list of registered canonical models for Pi/OMP provider registration
  */
-export function getModelDef(id: string): ModelDef | undefined {
-	return MODEL_MAP.get(id) || MODEL_MAP.get(resolveCanonicalModelId(id));
+export function getAllRegisteredModels(): ModelDef[] {
+	return ALL_MODELS;
 }
+
 /**
- * Get full list of registered models including CLI aliases
+ * Lookup a model definition by ID (supporting alias fallback)
  */
-export function getAllRegisteredModels(): ModelDef[] {
-	return Array.from(MODEL_MAP.values());
+export function getModelDef(id: string): ModelDef | undefined {
+	return MODEL_MAP.get(id) || MODEL_MAP.get(resolveCanonicalModelId(id));
 }