pi-freeflow 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +173 -0
  2. package/extensions/index.ts +1529 -0
  3. package/package.json +26 -0
package/README.md ADDED
@@ -0,0 +1,173 @@
1
+ # pi-freeflow
2
+
3
+ > 🌊 **FreeFlow**: Free AI Model Provider for [Oh My Pi (OMP)](https://omp.sh) and [Pi](https://pi.dev) with **Multi-Cloud Rolling Relay** (Cloudflare Workers / Vercel), **Up to 1M Context Windows**, **Auto-Switch Failover**, and **Real-Time Streaming**.
4
+
5
+ ---
6
+
7
+ ## ✨ Features
8
+
9
+ - 🆓 **22 Free Models**: Curated access to OpenCode Zen and KiloCode free AI models.
10
+ - 🧠 **Full 1M Context Windows**: Pre-configured with up to 1,048,576 tokens context window and vision (image) support.
11
+ - ⚡ **Real-Time SSE Streaming**: Zero-buffering chunk streaming with instant token delivery.
12
+ - 🛡️ **Multi-Cloud Rolling Egress Relay**:
13
+ - Support for **Cloudflare Workers**, **Vercel Edge**, and **Deno Deploy**.
14
+ - **Sticky Active Proxy**: Stays on the healthy proxy without unnecessary round-robin churn.
15
+ - **Auto-Switch Failover**: Instantly rolls to the next proxy when encountering `HTTP 429` (Rate Limit), `502/503/504`, or Network Timeouts.
16
+ - **Direct Fallback**: Transparently falls back to direct upstream if all relays are exhausted.
17
+ - 🔇 **Full Quiet Mode**: Clean status bar indicators without intrusive console overlays in the TUI.
18
+ - 📝 **Persistent Background Logging**: Automatic diagnostic logs recorded to `~/.pi/agent/pi-freeflow.log` with 2MB auto-rotation.
19
+ - 🤖 **Sub-Agent Ready**: Seamlessly shared across concurrent parallel sub-agent tasks.
20
+
21
+ ---
22
+
23
+ ## 📦 Installation
24
+
25
+ ### Oh My Pi (OMP)
26
+ ```bash
27
+ omp plugin install pi-freeflow
28
+ ```
29
+
30
+ ### Pi Coding Agent
31
+ ```bash
32
+ pi install npm:pi-freeflow
33
+ ```
34
+
35
+ ### From Local / Git Repo
36
+ ```bash
37
+ omp plugin link /path/to/pi-freeflow
38
+ ```
39
+
40
+ ---
41
+
42
+ ## 🚀 Quick Start
43
+
44
+ 1. Start OMP or Pi:
45
+ ```bash
46
+ omp
47
+ ```
48
+ 2. Select a model via `/model` $\to$ **`freeflow`** $\to$ choose your model (e.g. `mimo-v2.5-free` or `x-preview-f-free`).
49
+ 3. Manage relays with the `/freeflow` command:
50
+ ```text
51
+ /freeflow status # Check relay status and active proxy
52
+ /freeflow list # View all saved relay proxies
53
+ /freeflow on # Enable relay proxying
54
+ /freeflow off # Disable relay (use direct upstream)
55
+ /freeflow use <URL> # Activate a specific relay proxy
56
+ /freeflow logs # Show recent 25 lines of debug logs
57
+ ```
58
+
59
+ ---
60
+
61
+ ## 📋 Model Catalog (22 Models)
62
+
63
+ ### OpenCode Zen Models (8 Models)
64
+
65
+ | Model ID | Name | Context Window | Max Output | Reasoning / Thinking | Vision (Images) |
66
+ | :--- | :--- | :---: | :---: | :---: | :---: |
67
+ | `x-preview-f-free` | Ox Alpha Free | **1M** (1,048,576) | 131K | `low, high, max` | ✅ Yes |
68
+ | `muse-spark-1.2-contributor-free` | Muse Spark 1.2 Free | **1M** (1,048,576) | 131K | `minimal..max` | ✅ Yes |
69
+ | `mimo-v2.5-free` | Xiaomi MiMo-V2.5 Free | **1M** (1,048,576) | 131K | `low, medium, high` | ✅ Yes |
70
+ | `laguna-s-2.1-free` | Poolside Laguna S 2.1 Free | **1M** (1,048,576) | 131K | `minimal..max` | ❌ No |
71
+ | `nemotron-3.5-lightning-free` | Nemotron 3.5 Lightning Free | **1M** (1,000,000) | 262K | `minimal..max` | ❌ No |
72
+ | `nemotron-3-ultra-free` | Nemotron 3 Ultra Free | **1M** (1,000,000) | 128K | `minimal..max` | ❌ No |
73
+ | `hy3-free` | Tencent Hunyuan 3 Free | **262K** (262,144) | 128K | `minimal..max` | ❌ No |
74
+ | `big-pickle` | Big Pickle | **200K** (200,000) | 32K | `high, max` | ❌ No |
75
+
76
+ ### KiloCode Gateway Models (14 Models)
77
+
78
+ | Model ID | Name | Context Window | Max Output | Reasoning / Thinking | Vision (Images) |
79
+ | :--- | :--- | :---: | :---: | :---: | :---: |
80
+ | `dots-studio/dots-3-note-preview:free` | Dots3-Note Preview Free | **512K** (512,000) | 512K | OpenRouter format | ✅ Yes |
81
+ | `stepfun/step-3.7-flash:free` | Step 3.7 Flash Free | **262K** (262,144) | 262K | OpenRouter format | ✅ Yes |
82
+ | `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free` | Nemotron 3 Nano Omni Free | **256K** (256,000) | 65K | OpenRouter format | ✅ Yes |
83
+ | `nvidia/nemotron-3-ultra-550b-a55b:free` | Nemotron 3 Ultra Free | **1M** (1,000,000) | 65K | OpenRouter format | ❌ No |
84
+ | `nvidia/nemotron-3.5-lightning:free` | Nemotron 3.5 Lightning Free | **1M** (1,000,000) | 65K | OpenRouter format | ❌ No |
85
+ | `nvidia/nemotron-3-super-120b-a12b:free` | Nemotron 3 Super Free | **262K** (262,144) | 262K | OpenRouter format | ❌ No |
86
+ | `tencent/hy3:free` | Tencent Hy3 Free | **262K** (262,144) | 128K | OpenRouter format | ❌ No |
87
+ | `cohere/north-mini-code:free` | North Mini Code Free | **256K** (256,000) | 64K | OpenRouter format | ❌ No |
88
+ | `poolside/laguna-s-2.1:free` | Laguna S 2.1 Free | **262K** (262,144) | 33K | OpenRouter format | ❌ No |
89
+ | `poolside/laguna-xs-2.1:free` | Laguna XS 2.1 Free | **262K** (262,144) | 33K | OpenRouter format | ❌ No |
90
+ | `liquid/lfm-2.5-2.6b:free` | Liquid LFM 2.5 2.6B Free | **66K** (65,536) | 8K | OpenRouter format | ❌ No |
91
+ | `kilo-auto/free` | Kilo Auto Free | **256K** (256,000) | 10K | Standard | ❌ No |
92
+ | `openrouter/free` | OpenRouter Free (auto) | **200K** (200,000) | 65K | Standard | ❌ No |
93
+ | `nvidia/nemotron-3.5-content-safety:free` | Nemotron 3.5 Content Safety | **128K** (128,000) | 8K | Standard | ❌ No |
94
+
95
+ ---
96
+
97
+ ## 🌐 Setting Up Your Own Egress Relays
98
+
99
+ ### 1. Cloudflare Worker Relay (Recommended)
100
+ Deploy this script to Cloudflare Workers (100,000 free requests/day):
101
+
102
+ ```javascript
103
+ const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];
104
+
105
+ export default {
106
+ async fetch(request) {
107
+ if (request.method === "OPTIONS") {
108
+ return new Response(null, {
109
+ headers: {
110
+ "Access-Control-Allow-Origin": "*",
111
+ "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
112
+ "Access-Control-Allow-Headers": "*",
113
+ },
114
+ });
115
+ }
116
+
117
+ const target = request.headers.get("x-relay-target");
118
+ const relayPath = request.headers.get("x-relay-path") || "/";
119
+
120
+ if (!target || !ALLOWED_TARGETS.includes(target)) {
121
+ return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
122
+ }
123
+
124
+ const targetUrl = target.replace(/\/$/, "") + relayPath;
125
+ const headers = new Headers(request.headers);
126
+ headers.delete("x-relay-target");
127
+ headers.delete("x-relay-path");
128
+ headers.delete("host");
129
+
130
+ const response = await fetch(targetUrl, {
131
+ method: request.method,
132
+ headers,
133
+ body: request.method !== "GET" && request.method !== "HEAD" ? request.body : undefined,
134
+ });
135
+
136
+ return new Response(response.body, {
137
+ status: response.status,
138
+ headers: response.headers,
139
+ });
140
+ }
141
+ };
142
+ ```
143
+
144
+ After deploying, register your Cloudflare Worker URL in OMP:
145
+ ```text
146
+ /freeflow use https://your-worker-name.your-subdomain.workers.dev
147
+ ```
148
+
149
+ ---
150
+
151
+ ### 2. Vercel Relay
152
+ Deploy using the built-in deploy command:
153
+ ```text
154
+ /freeflow deploy
155
+ ```
156
+ *(Prompts for your Vercel API token in-memory and automatically creates a private Edge Function relay).*
157
+
158
+ ---
159
+
160
+ ## 🛠️ Diagnostics & Troubleshooting
161
+
162
+ View live debug logs:
163
+ ```bash
164
+ cat ~/.pi/agent/pi-freeflow.log | tail -n 30
165
+ # or inside OMP:
166
+ /freeflow logs
167
+ ```
168
+
169
+ ---
170
+
171
+ ## 📄 License
172
+
173
+ MIT © trefeon & verokes