pi-freeflow 1.7.0 → 1.8.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-freeflow 🌊
 
-> **25 free models. Up to 1M context. Zero API keys. Infinite scale via your own relay pool.**
+> **28 free models. Up to 1M context. Zero API keys. Infinite scale via your own relay pool.**
 
 Thin by design: model list + dumb relay + log. Host `pi-ai` owns thinking, normalization & provider magic. We just make it free, fast, and unbreakable.
 
@@ -18,7 +18,7 @@ Join devs bypassing rate limits with their own relay pools. BYO, add as many as
 
 | Feature | Description | Value | Cost |
 | :--- | :--- | :--- | :--- |
-| **25 Curated Free Models** | 7 OpenCode Zen + 18 KiloCode Gateway models, up to 1M context & 512K output | Ceiling Unlocked | **$0** |
+| **28 Curated Free Models** | 8 OpenCode Zen + 20 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** |
@@ -32,7 +32,7 @@ Philosophy: **Thin by design.** We only ship model list + relay proxy + log. Hos
 
 ---
 
-### 25 Curated Models, One Command
+### 28 Curated Models, One Command
 
 ```bash
 /model → freeflow → pick
@@ -123,33 +123,64 @@ Manage your relay pool directly from the OMP / Pi terminal:
 
 ### Quick Start in 30 Seconds
 
-#### 1. Install
-
-**Oh My Pi (Recommended):**
+**On Oh My Pi (OMP):**
 ```bash
 omp plugin install pi-freeflow
-# or local dev
+# or local dev (repo checkout)
 omp plugin link /path/to/pi-freeflow
 ```
 
-**Pi:**
+**On Pi:**
 ```bash
 pi install npm:pi-freeflow
 ```
 
+> Both commands fetch the **same npm package** from the registry — pi-freeflow
+> is an extension loaded by the host, not a standalone CLI. It works on **OMP
+> and Pi only** (they share the extension API).
+
 #### 2. Pick a Model
 
+**OMP — interactive:**
 ```bash
 omp
 /model → freeflow → muse-spark-1.2-contributor-free (1M) → max
+```
 
-# or CLI
+**OMP — one-shot CLI:**
+```bash
 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"
+omp -p --model freeflow/step-3.7-flash:high "solve this bug"   # alias + thinking level
+```
+
+**Pi — interactive:**
+```bash
+pi
+/model → freeflow → pick
+```
+
+**Pi — one-shot CLI:**
+```bash
+pi -p --model freeflow/step-3.7-flash:high "solve this bug"
+```
+
+> Model IDs accept a full canonical ID, a short alias (see the tables above),
+> and an optional `:effort` suffix (`:minimal` … `:xhigh`, `:max` where
+> supported). The host resolves the rest — you only type `freeflow/<name>`.
+
+#### 3. Manage Your Relay Pool (OMP & Pi both)
+
+```bash
+/freeflow status     # active relay, pool status, candidates
+/freeflow list       # relays with health badges
+/freeflow add <url> [label]
+/freeflow deploy     # guided deploy: vercel|cloudflare|deno
+/freeflow logs [n]   # tail proxy logs
 ```
 
-#### 3. Add Your Free Relays (Scale Infinitely)
+These slash commands work **identically in OMP and Pi** — the extension
+registers the same `/freeflow` command set in both hosts.
+#### 4. Add Your Free Relays (Scale Infinitely)
 
 Default ships direct. Add relays via `/freeflow add <url> [label]`.
 
@@ -231,7 +262,7 @@ Log rotation at 10MB. Clean, parseable, real-time HTTP lifecycle tracking.
 
 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 11.3k lines including tests. 228 tests pass, typecheck clean.
+Current size: about 11.3k lines including tests. 230 tests pass, typecheck clean.
 
 ---
 
@@ -251,6 +282,18 @@ 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.
+**Why is it installed via npm?**
+The npm package is the **distribution channel** only — both hosts resolve it internally:
+`omp plugin install pi-freeflow` and `pi install npm:pi-freeflow` install the same
+package from the npm registry. pi-freeflow is an **extension, not a standalone CLI** —
+the host (OMP or Pi) loads and runs it. A plain `npm install` just downloads the
+files; it is not a supported way to run the extension.
+
+**Which hosts can use it?**
+Oh My Pi (OMP) and Pi only. They share the same extension API
+(`extensions/index.ts` declares both `omp` and `pi` extension entries), so one
+package serves both. Other AI agents (OpenCode, KiloCode, Cursor, ...) have their
+own plugin systems and do not load this extension.
 
 ---
 
@@ -281,7 +324,7 @@ pnpm smoke       # verifies extensions/index.ts loads without crashing
 ```
 src/
 ├── index.ts          # extension entry, lifecycle hooks
-├── models.ts         # 25-model catalog definitions
+├── models.ts         # 28-model catalog definitions
 ├── catalog.ts        # model catalog cache (24h disk)
 ├── proxy.ts          # local proxy server (127.0.0.1:28180)
 ├── relay.ts          # relay selection & round-robin

package/package.json

@@ -1,62 +1,62 @@
-{
-  "name": "pi-freeflow",
-  "type": "module",
-  "version": "1.7.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",
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "oh-my-pi",
-    "omp",
-    "free-models",
-    "opencode",
-    "kilocode",
-    "ai-models",
-    "relay"
-  ],
-  "author": "trefeon",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/trefeon/pi-freeflow.git"
-  },
-  "homepage": "https://github.com/trefeon/pi-freeflow#readme",
-  "engines": {
-    "node": ">=22.19.0"
-  },
-  "omp": {
-    "extensions": [
-      "./extensions"
-    ]
-  },
-  "pi": {
-    "extensions": [
-      "./extensions"
-    ]
-  },
-  "files": [
-    "extensions",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --experimental-strip-types --test --test-concurrency=1 test/**/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "smoke": "node --experimental-strip-types -e \"import('./extensions/index.ts').then(() => console.log('✓ Smoke test passed: extensions/index.ts loaded successfully')).catch(err => { console.error(err); process.exit(1); })\"",
-    "changeset": "changeset",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.27.0",
-    "@types/node": "^22.13.9",
-    "typescript": "^5.8.2",
-    "vitepress": "^1.6.4"
-  },
-  "dependencies": {
-    "undici": "^8.10.0"
-  }
-}
+{
+  "name": "pi-freeflow",
+  "type": "module",
+  "version": "1.8.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",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "oh-my-pi",
+    "omp",
+    "free-models",
+    "opencode",
+    "kilocode",
+    "ai-models",
+    "relay"
+  ],
+  "author": "trefeon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trefeon/pi-freeflow.git"
+  },
+  "homepage": "https://github.com/trefeon/pi-freeflow#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "omp": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test --test-concurrency=1 test/**/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node --experimental-strip-types -e \"import('./extensions/index.ts').then(() => console.log('✓ Smoke test passed: extensions/index.ts loaded successfully')).catch(err => { console.error(err); process.exit(1); })\"",
+    "changeset": "changeset",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "@types/node": "^22.13.9",
+    "typescript": "^5.8.2",
+    "vitepress": "^1.6.4"
+  },
+  "dependencies": {
+    "undici": "^8.10.0"
+  }
+}

package/src/catalog.ts

@@ -34,7 +34,7 @@ import type {
 export const DEAD_MODEL_IDS = new Set<string>(["deepseek-v4-flash-free", "x-preview-f-free"]);
 /**
  * In-memory cache of currently active/available free models.
- * Initialized with all 25 verified models for 0ms instant availability.
+ * Initialized with all 28 verified models for 0ms instant availability.
  */
 let aliveCatalog: RegisteredModel[] = ALL_MODELS.map((m) => ({
 	...m,
@@ -328,6 +328,6 @@ export async function refreshCatalog(force = false): Promise<RegisteredModel[]>
 	} catch (err) {
 		logDebug("Failed reading stale catalog cache", { error: String(err) });
 	}
-	// No valid cache — return in-memory static 25 (host will refresh if needed)
+	// No valid cache — return in-memory static 28 (host will refresh if needed)
 	return aliveCatalog;
 }

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * pi-freeflow — Modular, high-resiliency LLM extension for Pi & Oh My Pi (OMP)
  *
- * Provides access to 25 free models (7 OpenCode Zen + 18 KiloCode Gateway) with:
+ * Provides access to 28 free models (8 OpenCode Zen + 20 KiloCode Gateway) with:
  * - Single-port daemon reuse on 28180 across concurrent subagents
  * - Multi-cloud rolling egress relays (Vercel Edge, Cloudflare, Deno)
  * - 0ms instant startup with verified static catalog and background live health checks
@@ -114,7 +114,7 @@ export function buildProviderConfig(
 ): ProviderConfig {
 	return {
 		baseUrl: `http://${HOST}:${port}/v1`,
-		apiKey: "placeholder",
+		apiKey: "public",
 		api: "openai-completions",
 		compat: { supportsDeveloperRole: false },
 		models: models.map((m) => {
@@ -310,7 +310,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 						? `Relay pool ready: ${freshRelayState.relays.length} relay(s). Run /freeflow for pool management.`
 						: "Relay pool empty — direct mode. Run /freeflow deploy to add your own egress.";
 				ctx.ui?.notify?.(
-					`freeflow ready: 25 free models via local proxy 127.0.0.1:28180. ${hint}`,
+					`freeflow ready: 28 free models via local proxy 127.0.0.1:28180. ${hint}`,
 					"info",
 				);
 			}

package/src/models.ts

@@ -1,9 +1,9 @@
 /**
  * Static model definitions and upstream routing catalogs for pi-freeflow
  *
- * Defines the 25 verified free models:
- * - 7 OpenCode Zen models (1 Responses API + 6 Chat Completions)
- * - 18 KiloCode Keyless Gateway models (17 OpenRouter format + 1 Standard format)
+ * Defines the 28 verified free models:
+ * - 8 OpenCode Zen models (1 Responses API + 7 Chat Completions)
+ * - 20 KiloCode Keyless Gateway models (19 OpenRouter format + 1 Standard format)
  */
 
 import type { ModelDef, ThinkingLevelMap, Upstream } from "./types.ts";
@@ -126,6 +126,22 @@ export const OPENCODE_MODELS: ModelDef[] = [
 			xhigh: "xhigh",
 			max: null,},
 	},
+	{
+		id: "ling-3.0-flash-fin-free",
+		name: "Ling 3.0 Flash Fin (256K)",
+		reasoning: true,
+		contextWindow: 262_144,
+		maxTokens: 131_072,
+		input: ["text"],
+		thinkingLevelMap: {
+			off: null,
+			minimal: "minimal",
+			low: "low",
+			medium: "medium",
+			high: "high",
+			xhigh: "xhigh",
+			max: null,},
+	},
 ];
 
 /**
@@ -328,6 +344,26 @@ export const KILO_MODELS: ModelDef[] = [
 	thinkingFormat: "openrouter",
 	thinkingLevelMap: KILO_REASONING_MAP,
 },
+{
+	id: "thinkingmachines/inkling:free",
+	name: "Inkling (1M)",
+	reasoning: true,
+	contextWindow: 1_048_576,
+	maxTokens: 262_144,
+	input: ["text", "image"],
+	thinkingFormat: "openrouter",
+	thinkingLevelMap: KILO_REASONING_MAP,
+},
+{
+	id: "thinkingmachines/inkling-small:free",
+	name: "Inkling Small (1M)",
+	reasoning: true,
+	contextWindow: 1_048_576,
+	maxTokens: 262_144,
+	input: ["text", "image"],
+	thinkingFormat: "openrouter",
+	thinkingLevelMap: KILO_REASONING_MAP,
+},
 ];
 
 /**
@@ -352,6 +388,8 @@ export const MODEL_ALIASES: Record<string, string> = {
 	"minimax-m2.7": "minimax/minimax-m2.7:free",
 	"minimax-m3": "minimax/minimax-m3:free",
 	"ling-3.0-flash-fin": "inclusionai/ling-3.0-flash-fin:free",
+	"inkling": "thinkingmachines/inkling:free",
+	"inkling-small": "thinkingmachines/inkling-small:free",
 	// provider-prefixed short aliases (slash-normalized)
 	"hy3:free": "tencent/hy3:free",
 	"laguna-s-2.1:free": "poolside/laguna-s-2.1:free",
@@ -379,7 +417,7 @@ export const KILO_MODEL_IDS = new Set<string>([
 ]);
 
 /**
- * Combined list of all 25 static free models (canonical)
+ * Combined list of all 28 static free models (canonical)
  */
 export const ALL_MODELS: ModelDef[] = [...OPENCODE_MODELS, ...KILO_MODELS];
 

package/src/proxy.ts

@@ -85,13 +85,12 @@ export function sanitizeHeaders(
 	incoming: http.IncomingHttpHeaders,
 	targetHost: string,
 ): Record<string, string> {
-	// Positive allowlist: only headers the proxy is meant to relay. Everything
-	// else (host, cookie, x-forwarded-*, client x-relay-*) is dropped so a
-	// browser/extension cannot smuggle headers into the upstream request.
+	// authorization is deliberately NOT forwarded: the host provider registers
+	// with a dummy key (placeholder), and zen free models are keyless — sending
+	// that fake key upstream gets 401 Invalid API key. Kilo injects its own key.
 	const allowed: Record<string, true> = {
 		"content-type": true,
 		accept: true,
-		authorization: true,
 		"x-request-id": true,
 	};
 	const sanitized: Record<string, string> = {};