pi-freerouter 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# pi-freerouter
+
+Pi coding agent extension that routes every request through OpenRouter's free model tier — no paid API key needed beyond your OpenRouter account.
+
+## Quick start
+
+**1. Install**
+
+```bash
+pi install npm:pi-freerouter
+```
+
+**2. Set your OpenRouter API key**
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+```
+
+Free key at [openrouter.ai/keys](https://openrouter.ai/keys). No credit card required.
+
+**3. Start Pi**
+
+FreeRouter appears in the model picker and is set as the default automatically.
+
+---
+
+## How free model routing works
+
+OpenRouter exposes dozens of free models (models with a `:free` suffix). Each has its own rate limit — typically a few requests per minute per model. The trick is to spread load across all of them automatically.
+
+### Parallel racing
+
+Every time Pi sends a request, pi-freerouter doesn't pick one model and hope for the best. It picks the **next 3 available models** from its sorted list and fires all three requests simultaneously.
+
+```
+Request arrives
+    │
+    ├── model A ──────────────────── first token ──▶ WINNER → stream to Pi
+    ├── model B ───── (slower)                      → aborted
+    └── model C ─── (even slower)                   → aborted
+```
+
+Whichever model emits its first token wins. The other two are immediately cancelled. Pi sees a single clean stream — it has no idea a race happened.
+
+### Automatic fallback
+
+When a model hits its rate limit (HTTP 429) or fails (5xx), it's marked as exhausted and skipped for 90 seconds. The next batch of 3 models takes over. Timed-out models (no response in 30 seconds) recover faster — after 15 seconds.
+
+```
+Batch 1: [model A, model B, model C]  → all hit quota
+Batch 2: [model D, model E, model F]  → model D wins
+         ↑ model A–C recover after 90s and rejoin the pool
+```
+
+### Provider priority
+
+Free models are sorted so the lowest-latency inference providers are always tried first:
+
+1. Groq
+2. Cerebras  
+3. Fireworks
+4. Together
+5. Mistral
+6. Everything else (sorted by context window ascending)
+
+### Model list refresh
+
+The list of available free models is fetched at startup and refreshed every hour in the background, so long-running Pi sessions automatically pick up newly added models.
+
+---
+
+## Requirements
+
+- [Pi coding agent](https://pi.dev) v0.78+
+- OpenRouter API key (free tier is sufficient)
+
+## License
+
+MIT

package/dist/discovery.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderModelConfig } from "./types.js";
+export declare function fetchFreeModels(apiKey: string): Promise<ProviderModelConfig[]>;

package/dist/discovery.js

@@ -0,0 +1,47 @@
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+const DEFAULT_MAX_TOKENS = 4_096;
+// Providers known for low latency on free tier, ordered by preference
+const FAST_PROVIDER_PREFIXES = [
+    "groq/",
+    "cerebras/",
+    "fireworks/",
+    "together/",
+    "mistralai/",
+];
+function speedScore(modelId) {
+    const lower = modelId.toLowerCase();
+    const idx = FAST_PROVIDER_PREFIXES.findIndex((prefix) => lower.startsWith(prefix));
+    return idx === -1 ? FAST_PROVIDER_PREFIXES.length : idx;
+}
+export async function fetchFreeModels(apiKey) {
+    if (!apiKey) {
+        throw new Error("OPENROUTER_API_KEY is required");
+    }
+    const response = await fetch("https://openrouter.ai/api/v1/models", {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch OpenRouter models: ${response.status} ${response.statusText}`);
+    }
+    const payload = (await response.json());
+    const models = (payload.data ?? []).filter((m) => m.id.includes(":free"));
+    // Sort: fast providers first, then by context size ascending (smaller = faster inference)
+    models.sort((a, b) => {
+        const scoreDiff = speedScore(a.id) - speedScore(b.id);
+        if (scoreDiff !== 0)
+            return scoreDiff;
+        const aCtx = a.context_length ?? DEFAULT_CONTEXT_WINDOW;
+        const bCtx = b.context_length ?? DEFAULT_CONTEXT_WINDOW;
+        return aCtx - bCtx;
+    });
+    return models.map((m) => ({
+        id: m.id,
+        name: m.name,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: m.context_length ?? DEFAULT_CONTEXT_WINDOW,
+        maxTokens: m.top_provider?.max_completion_tokens ?? DEFAULT_MAX_TOKENS,
+    }));
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAEA,MAAM,sBAAsB,GAAG,OAAO,CAAC;AACvC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAEjC,sEAAsE;AACtE,MAAM,sBAAsB,GAAG;IAC7B,OAAO;IACP,WAAW;IACX,YAAY;IACZ,WAAW;IACX,YAAY;CACb,CAAC;AAEF,SAAS,UAAU,CAAC,OAAe;IACjC,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACnF,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;AAC1D,CAAC;AAaD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc;IAClD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,qCAAqC,EAAE;QAClE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;KAC/C,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IAClG,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA6B,CAAC;IAEpE,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IAE1E,0FAA0F;IAC1F,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACtD,IAAI,SAAS,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACtC,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,IAAI,sBAAsB,CAAC;QACxD,MAAM,IAAI,GAAG,CAAC,CAAC,cAAc,IAAI,sBAAsB,CAAC;QACxD,OAAO,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACxB,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,SAAS,EAAE,KAAK;QAChB,KAAK,EAAE,CAAC,MAAM,CAAyB;QACvC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;QAC1D,aAAa,EAAE,CAAC,CAAC,cAAc,IAAI,sBAAsB;QACzD,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE,qBAAqB,IAAI,kBAAkB;KACvE,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/discovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/discovery.test.js

@@ -0,0 +1,68 @@
+import { strict as assert } from "node:assert";
+import { describe, it, beforeEach, afterEach } from "node:test";
+describe("fetchFreeModels", () => {
+    let originalFetch;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it("filters only :free models and maps fields", async () => {
+        const mockPayload = {
+            data: [
+                {
+                    id: "meta-llama/llama-3.2-3b:free",
+                    name: "Llama 3.2 3B (free)",
+                    context_length: 131072,
+                    top_provider: { max_completion_tokens: 8192 },
+                    pricing: { prompt: "0", completion: "0" },
+                },
+                {
+                    id: "openai/gpt-4o",
+                    name: "GPT-4o",
+                    context_length: 128000,
+                    pricing: { prompt: "0.000005", completion: "0.000015" },
+                },
+            ],
+        };
+        globalThis.fetch = async () => ({
+            ok: true,
+            json: async () => mockPayload,
+        });
+        const { fetchFreeModels } = await import("./discovery.js");
+        const models = await fetchFreeModels("sk-or-test");
+        assert.equal(models.length, 1);
+        assert.equal(models[0].id, "meta-llama/llama-3.2-3b:free");
+        assert.equal(models[0].contextWindow, 131072);
+        assert.equal(models[0].maxTokens, 8192);
+        assert.deepEqual(models[0].cost, { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
+    });
+    it("throws if apiKey is empty", async () => {
+        const { fetchFreeModels } = await import("./discovery.js");
+        await assert.rejects(() => fetchFreeModels(""), /OPENROUTER_API_KEY/);
+    });
+    it("throws if fetch response is not ok", async () => {
+        globalThis.fetch = async () => ({ ok: false, status: 401, statusText: "Unauthorized" });
+        const { fetchFreeModels } = await import("./discovery.js");
+        await assert.rejects(() => fetchFreeModels("sk-or-bad"), /401/);
+    });
+    it("sorts fast providers before unknown providers", async () => {
+        const mockPayload = {
+            data: [
+                { id: "meta-llama/llama-3.1-8b:free", name: "Llama (unknown provider)", context_length: 32768 },
+                { id: "groq/llama-3.3-70b:free", name: "Groq Llama", context_length: 131072 },
+                { id: "cerebras/llama3.1-8b:free", name: "Cerebras Llama", context_length: 8192 },
+            ],
+        };
+        globalThis.fetch = async () => ({ ok: true, json: async () => mockPayload });
+        const { fetchFreeModels } = await import("./discovery.js");
+        const models = await fetchFreeModels("sk-or-test");
+        assert.equal(models.length, 3);
+        // Groq (score 0) before Cerebras (score 1) before unknown (score 5)
+        assert.ok(models[0].id.startsWith("groq/"), `expected groq first, got ${models[0].id}`);
+        assert.ok(models[1].id.startsWith("cerebras/"), `expected cerebras second, got ${models[1].id}`);
+        assert.ok(models[2].id.startsWith("meta-llama/"), `expected meta-llama last, got ${models[2].id}`);
+    });
+});
+//# sourceMappingURL=discovery.test.js.map

package/dist/discovery.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.test.js","sourceRoot":"","sources":["../src/discovery.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEhE,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,IAAI,aAAsC,CAAC;IAE3C,UAAU,CAAC,GAAG,EAAE;QACd,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,UAAU,CAAC,KAAK,GAAG,aAAa,CAAC;IACnC,CAAC,CAAC,CAAC;IACH,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,MAAM,WAAW,GAAG;YAClB,IAAI,EAAE;gBACJ;oBACE,EAAE,EAAE,8BAA8B;oBAClC,IAAI,EAAE,qBAAqB;oBAC3B,cAAc,EAAE,MAAM;oBACtB,YAAY,EAAE,EAAE,qBAAqB,EAAE,IAAI,EAAE;oBAC7C,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE;iBAC1C;gBACD;oBACE,EAAE,EAAE,eAAe;oBACnB,IAAI,EAAE,QAAQ;oBACd,cAAc,EAAE,MAAM;oBACtB,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE;iBACxD;aACF;SACF,CAAC;QAEF,UAAU,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE,CAC5B,CAAC;YACC,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,WAAW;SACtB,CAAA,CAAC;QAEZ,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,YAAY,CAAC,CAAC;QAEnD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC/B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,8BAA8B,CAAC,CAAC;QAC3D,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACxC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;QACzC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC3D,MAAM,MAAM,CAAC,OAAO,CAClB,GAAG,EAAE,CAAC,eAAe,CAAC,EAAE,CAAC,EACzB,oBAAoB,CACrB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,KAAK,IAAI,EAAE;QAClD,UAAU,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE,CAC5B,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,cAAc,EAAU,CAAA,CAAC;QAElE,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC3D,MAAM,MAAM,CAAC,OAAO,CAClB,GAAG,EAAE,CAAC,eAAe,CAAC,WAAW,CAAC,EAClC,KAAK,CACN,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;QAC7D,MAAM,WAAW,GAAG;YAClB,IAAI,EAAE;gBACJ,EAAE,EAAE,EAAE,8BAA8B,EAAE,IAAI,EAAE,0BAA0B,EAAE,cAAc,EAAE,KAAK,EAAE;gBAC/F,EAAE,EAAE,EAAE,yBAAyB,EAAE,IAAI,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE;gBAC7E,EAAE,EAAE,EAAE,2BAA2B,EAAE,IAAI,EAAE,gBAAgB,EAAE,cAAc,EAAE,IAAI,EAAE;aAClF;SACF,CAAC;QAEF,UAAU,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE,CAC5B,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,WAAW,EAAU,CAAA,CAAC;QAEvD,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,YAAY,CAAC,CAAC;QAEnD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC/B,oEAAoE;QACpE,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,4BAA4B,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACxF,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,iCAAiC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjG,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,iCAAiC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrG,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "./types.js";
+export default function (pi: ExtensionAPI): Promise<void>;

package/dist/index.js

@@ -0,0 +1,321 @@
+import { createAssistantMessageEventStream } from "./types.js";
+import { fetchFreeModels } from "./discovery.js";
+import { FreeRouter } from "./router.js";
+import { streamFreeModel, ModelExhaustedError, ModelFatalError } from "./stream.js";
+// Race this many free models simultaneously; first to stream wins.
+const RACE_WIDTH = 3;
+// If no candidate emits its first token within this window, abort and try the
+// next batch. Free models routinely take 10-30 s to first token; 30 s ensures
+// we don't thrash through the pool on legitimately slow (but live) models.
+const FIRST_TOKEN_TIMEOUT_MS = 30_000;
+// Re-fetch the free model list every hour so long-running Pi sessions pick up
+// newly available models (and stop wasting retries on removed ones).
+const REFRESH_INTERVAL_MS = 60 * 60 * 1_000;
+function mergeSignals(...signals) {
+    const controller = new AbortController();
+    for (const sig of signals) {
+        if (!sig)
+            continue;
+        if (sig.aborted) {
+            controller.abort();
+            return controller.signal;
+        }
+        sig.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    return controller.signal;
+}
+/**
+ * Start candidateIds concurrently and forward events from the first model that
+ * emits `text_start` (or a valid empty `done`) to outStream; abort the rest.
+ *
+ * Correctness notes:
+ * - Uses Map<candidateIdx, Promise> so delete(idx) is always by candidate index,
+ *   never by array position (which diverges after the first re-push).
+ * - Snapshots exhaustedIds at each return so late floating-.catch() pushes after
+ *   raceModels returns don't corrupt the caller's view.
+ * - Tracks fatalError (e.g. 402) separately from quota exhaustion.
+ */
+async function raceModels(candidateIds, context, apiKey, outStream, parentSignal, maxTokens) {
+    const controllers = candidateIds.map(() => new AbortController());
+    const proxyStreams = candidateIds.map(() => createAssistantMessageEventStream());
+    const exhaustedIds = [];
+    let fatalError;
+    // Start all candidates concurrently; each writes to its own isolated proxy stream.
+    candidateIds.forEach((modelId, i) => {
+        const sig = parentSignal
+            ? mergeSignals(parentSignal, controllers[i].signal)
+            : controllers[i].signal;
+        streamFreeModel(modelId, context, apiKey, proxyStreams[i], sig, maxTokens).catch((err) => {
+            if (err instanceof ModelExhaustedError) {
+                exhaustedIds.push(modelId);
+            }
+            else if (err instanceof ModelFatalError) {
+                fatalError = fatalError ?? err; // keep first fatal error
+            }
+            proxyStreams[i].end(); // ensure iterator terminates
+        });
+    });
+    const iterators = proxyStreams.map((s) => s[Symbol.asyncIterator]());
+    const buffers = candidateIds.map(() => []);
+    const nextFrom = (idx) => iterators[idx].next().then((result) => ({ idx, result }));
+    // Map<candidateIdx, Promise> so delete(idx) is always correct regardless of
+    // insertion order — the old array-based filter((_,j)=>j!==idx) was wrong after
+    // any re-push because j (array position) diverges from idx (candidate index).
+    const pending = new Map(candidateIds.map((_, i) => [i, nextFrom(i)]));
+    let timeoutHandle;
+    const deadline = new Promise((resolve) => {
+        timeoutHandle = setTimeout(() => resolve({ __timeout: true }), FIRST_TOKEN_TIMEOUT_MS);
+    });
+    try {
+        while (pending.size > 0) {
+            const resolved = await Promise.race([
+                ...pending.values(),
+                deadline,
+            ]);
+            if ("__timeout" in resolved) {
+                controllers.forEach((c) => c.abort());
+                return { winner: null, exhaustedIds: [...exhaustedIds], timedOut: true, fatalError };
+            }
+            const { idx, result } = resolved;
+            pending.delete(idx); // safe: keyed by candidate idx, not array position
+            if (result.done)
+                continue; // this candidate's stream ended; move on
+            const event = result.value;
+            buffers[idx].push(event);
+            // text_start      → normal text streaming win
+            // toolcall_start  → model is making a tool call; also a valid win
+            // done            → valid but empty response (no text/tool content); still a winner
+            if (event.type === "text_start" || event.type === "toolcall_start" || event.type === "done") {
+                controllers.forEach((c, j) => { if (j !== idx)
+                    c.abort(); });
+                for (const e of buffers[idx])
+                    outStream.push(e);
+                if (event.type === "done") {
+                    outStream.end();
+                    return { winner: candidateIds[idx], exhaustedIds: [...exhaustedIds], timedOut: false };
+                }
+                // text_start / toolcall_start: pipe remaining events from the winner to outStream.
+                for await (const e of { [Symbol.asyncIterator]: () => iterators[idx] }) {
+                    outStream.push(e);
+                    if (e.type === "done" || e.type === "error") {
+                        outStream.end();
+                        break;
+                    }
+                }
+                outStream.end(); // defensive: no-op if already ended via done/error above
+                return { winner: candidateIds[idx], exhaustedIds: [...exhaustedIds], timedOut: false };
+            }
+            if (event.type === "error") {
+                // Non-quota failure; stream ends next tick — don't re-add to pending.
+                continue;
+            }
+            // Any other event (e.g., thinking_start before text_start): keep consuming.
+            pending.set(idx, nextFrom(idx));
+        }
+        return { winner: null, exhaustedIds: [...exhaustedIds], timedOut: false, fatalError };
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+const BASE_ERROR_OUTPUT = {
+    role: "assistant",
+    api: "openrouter",
+    provider: "freerouter",
+    model: "free-router",
+    usage: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: "error",
+};
+export default async function (pi) {
+    const apiKeyRaw = process.env.OPENROUTER_API_KEY;
+    if (!apiKeyRaw) {
+        throw new Error("pi-freerouter: OPENROUTER_API_KEY is not set");
+    }
+    // Explicit string type so closures (streamSimple, refreshModels) see `string`,
+    // not `string | undefined` — TypeScript doesn't carry narrowing into inner fns.
+    const apiKey = apiKeyRaw;
+    const freeModels = await fetchFreeModels(apiKey);
+    if (freeModels.length === 0) {
+        throw new Error("pi-freerouter: No free models found on OpenRouter");
+    }
+    // `let` so the background refresh can replace it; each streamSimple call
+    // captures its own snapshot via `const localRouter = router`.
+    let router = new FreeRouter(freeModels.map((m) => m.id));
+    const maxContext = Math.max(...freeModels.map((m) => m.contextWindow));
+    const maxTokens = Math.max(...freeModels.map((m) => m.maxTokens));
+    // Hourly background refresh — picks up new free models without restarting Pi.
+    async function refreshModels() {
+        try {
+            const fresh = await fetchFreeModels(apiKey);
+            if (fresh.length > 0) {
+                router = new FreeRouter(fresh.map((m) => m.id));
+                console.log(`[pi-freerouter] Model list refreshed: ${fresh.length} free models`);
+            }
+        }
+        catch (err) {
+            console.warn("[pi-freerouter] Failed to refresh free model list:", err);
+        }
+    }
+    const refreshTimer = setInterval(() => { void refreshModels(); }, REFRESH_INTERVAL_MS);
+    // Don't keep the Node process alive solely for this timer.
+    if (typeof refreshTimer.unref === "function") {
+        refreshTimer.unref();
+    }
+    pi.registerProvider("freerouter", {
+        baseUrl: "https://openrouter.ai/api/v1",
+        apiKey,
+        api: "openai-completions",
+        models: [
+            {
+                id: "free-router",
+                name: "FreeRouter",
+                reasoning: false,
+                input: ["text"],
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                contextWindow: maxContext,
+                maxTokens,
+            },
+        ],
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        streamSimple: ((_model, context, options) => {
+            const stream = createAssistantMessageEventStream();
+            let streamClosed = false;
+            // Capture router at request start so mid-request refreshes don't affect
+            // this in-flight request's exhaustion tracking.
+            const localRouter = router;
+            (async () => {
+                while (true) {
+                    // Check abort before starting each batch.
+                    if (options?.signal?.aborted) {
+                        const abortMsg = "Request was cancelled.";
+                        streamClosed = true;
+                        stream.push({
+                            type: "error",
+                            reason: "aborted",
+                            error: {
+                                ...BASE_ERROR_OUTPUT,
+                                content: [],
+                                errorMessage: abortMsg,
+                                timestamp: Date.now(),
+                            },
+                        });
+                        stream.end();
+                        return;
+                    }
+                    const candidates = localRouter.nextModels(RACE_WIDTH);
+                    if (candidates.length === 0)
+                        break;
+                    console.log(`[pi-freerouter] Racing: ${candidates.join(", ")}`);
+                    const { winner, exhaustedIds, timedOut, fatalError } = await raceModels(candidates, context, apiKey, stream, options?.signal, options?.maxTokens);
+                    // Quota-exceeded models: long TTL (90s).
+                    exhaustedIds.forEach((id) => localRouter.markExhausted(id));
+                    if (winner !== null) {
+                        console.log(`[pi-freerouter] Winner: ${winner}`);
+                        streamClosed = true;
+                        return; // raceModels wrote all events and called stream.end()
+                    }
+                    // Fatal error (e.g., 402 Insufficient Credits) — surface immediately.
+                    if (fatalError) {
+                        const errMsg = fatalError.message;
+                        streamClosed = true;
+                        stream.push({
+                            type: "error",
+                            reason: "error",
+                            error: {
+                                ...BASE_ERROR_OUTPUT,
+                                content: [{ type: "text", text: errMsg }],
+                                errorMessage: errMsg,
+                                timestamp: Date.now(),
+                            },
+                        });
+                        stream.end();
+                        return;
+                    }
+                    // Check abort — race may have ended because parent signal fired.
+                    if (options?.signal?.aborted) {
+                        const abortMsg = "Request was cancelled.";
+                        streamClosed = true;
+                        stream.push({
+                            type: "error",
+                            reason: "aborted",
+                            error: {
+                                ...BASE_ERROR_OUTPUT,
+                                content: [],
+                                errorMessage: abortMsg,
+                                timestamp: Date.now(),
+                            },
+                        });
+                        stream.end();
+                        return;
+                    }
+                    // No winner — skip candidates we haven't already marked exhausted.
+                    // Timeout → short TTL (15s): model is alive but slow, recover quickly.
+                    // Other failure → long TTL (90s): treat as quota/error, avoid for longer.
+                    candidates.forEach((id) => {
+                        if (!exhaustedIds.includes(id)) {
+                            if (timedOut) {
+                                localRouter.markSlow(id);
+                            }
+                            else {
+                                localRouter.markExhausted(id);
+                            }
+                        }
+                    });
+                }
+                // All models currently in TTL cooldown.
+                const errMsg = "All free models exhausted. They will recover automatically — please try again in a moment.";
+                streamClosed = true;
+                stream.push({
+                    type: "error",
+                    reason: "error",
+                    error: {
+                        ...BASE_ERROR_OUTPUT,
+                        content: [{ type: "text", text: errMsg }],
+                        errorMessage: errMsg,
+                        timestamp: Date.now(),
+                    },
+                });
+                stream.end();
+            })().catch((err) => {
+                if (!streamClosed) {
+                    const errMsg = String(err);
+                    stream.push({
+                        type: "error",
+                        reason: "error",
+                        error: {
+                            ...BASE_ERROR_OUTPUT,
+                            content: [],
+                            errorMessage: errMsg,
+                            timestamp: Date.now(),
+                        },
+                    });
+                    stream.end();
+                }
+            });
+            // Cast: local stream satisfies the pi-ai class interface at runtime;
+            // private fields on the pi-ai class prevent structural assignability.
+            return stream;
+        }),
+    });
+    // Auto-activate FreeRouter as the default model on session start.
+    pi.on("session_start", async (_event, handlerCtx) => {
+        try {
+            const registry = handlerCtx?.modelRegistry;
+            const freeRouterModel = registry?.find?.("freerouter", "free-router");
+            if (freeRouterModel) {
+                await pi.setModel(freeRouterModel);
+            }
+        }
+        catch (err) {
+            console.warn("[pi-freerouter] Failed to set FreeRouter as active model:", err);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/router.d.ts

@@ -0,0 +1,12 @@
+export declare class FreeRouter {
+    private readonly models;
+    private readonly exhaustionTtlMs;
+    private readonly exhausted;
+    constructor(models: readonly string[], exhaustionTtlMs?: number);
+    nextModel(): string | null;
+    nextModels(count: number): string[];
+    /** Mark model as quota-exhausted (429/5xx). Long TTL — don't retry soon. */
+    markExhausted(id: string): void;
+    /** Mark model as slow (first-token timeout). Short TTL — try others first, recover fast. */
+    markSlow(id: string): void;
+}

package/dist/router.js

@@ -0,0 +1,53 @@
+// 90 s for quota exhaustion (429/5xx) — matches OpenRouter's per-minute reset window.
+const DEFAULT_EXHAUSTION_TTL_MS = 90_000;
+// 15 s for a first-token timeout — model is alive but slow; back-off briefly so
+// the next batch tries different candidates without burning the whole pool.
+const SLOW_TTL_MS = 15_000;
+export class FreeRouter {
+    models;
+    exhaustionTtlMs;
+    // modelId → { at: timestamp, ttl: ms }
+    exhausted = new Map();
+    constructor(models, exhaustionTtlMs = DEFAULT_EXHAUSTION_TTL_MS) {
+        this.models = models;
+        this.exhaustionTtlMs = exhaustionTtlMs;
+    }
+    nextModel() {
+        return this.nextModels(1)[0] ?? null;
+    }
+    nextModels(count) {
+        const now = Date.now();
+        const result = [];
+        for (const id of this.models) {
+            if (result.length >= count)
+                break;
+            const entry = this.exhausted.get(id);
+            if (entry !== undefined) {
+                if (now - entry.at < entry.ttl)
+                    continue;
+                this.exhausted.delete(id); // TTL expired — back in rotation
+            }
+            result.push(id);
+        }
+        return result;
+    }
+    /** Mark model as quota-exhausted (429/5xx). Long TTL — don't retry soon. */
+    markExhausted(id) {
+        if (!this.models.includes(id)) {
+            console.warn(`[pi-freerouter] markExhausted called with unknown model ID: ${id}`);
+            return;
+        }
+        this.exhausted.set(id, { at: Date.now(), ttl: this.exhaustionTtlMs });
+    }
+    /** Mark model as slow (first-token timeout). Short TTL — try others first, recover fast. */
+    markSlow(id) {
+        if (!this.models.includes(id))
+            return;
+        // Don't downgrade an already-exhausted model to the shorter slow TTL.
+        const existing = this.exhausted.get(id);
+        if (existing && existing.ttl >= this.exhaustionTtlMs)
+            return;
+        this.exhausted.set(id, { at: Date.now(), ttl: SLOW_TTL_MS });
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,MAAM,yBAAyB,GAAG,MAAM,CAAC;AACzC,gFAAgF;AAChF,4EAA4E;AAC5E,MAAM,WAAW,GAAG,MAAM,CAAC;AAE3B,MAAM,OAAO,UAAU;IAKF;IACA;IALnB,uCAAuC;IACtB,SAAS,GAAG,IAAI,GAAG,EAAuC,CAAC;IAE5E,YACmB,MAAyB,EACzB,kBAAkB,yBAAyB;QAD3C,WAAM,GAAN,MAAM,CAAmB;QACzB,oBAAe,GAAf,eAAe,CAA4B;IAC3D,CAAC;IAEJ,SAAS;QACP,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACvC,CAAC;IAED,UAAU,CAAC,KAAa;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK;gBAAE,MAAM;YAClC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,IAAI,GAAG,GAAG,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG;oBAAE,SAAS;gBACzC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,iCAAiC;YAC9D,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClB,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,4EAA4E;IAC5E,aAAa,CAAC,EAAU;QACtB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,+DAA+D,EAAE,EAAE,CAAC,CAAC;YAClF,OAAO;QACT,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,4FAA4F;IAC5F,QAAQ,CAAC,EAAU;QACjB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,OAAO;QACtC,sEAAsE;QACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACxC,IAAI,QAAQ,IAAI,QAAQ,CAAC,GAAG,IAAI,IAAI,CAAC,eAAe;YAAE,OAAO;QAC7D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/router.test.d.ts

@@ -0,0 +1 @@
+export {};