pi-free 1.0.0

package/config.ts

@@ -0,0 +1,224 @@
+/**
+ * Shared config for pi-free-providers.
+ *
+ * Keys and flags are resolved in this order (first wins):
+ *   1. Environment variable
+ *   2. ~/.pi/free.json
+ *
+ * Per-provider paid model flags:
+ *   OPENROUTER_SHOW_PAID=true or openrouter_show_paid: true
+ *   NVIDIA_SHOW_PAID=true or nvidia_show_paid: true
+ *   FIREWORKS_SHOW_PAID=true or fireworks_show_paid: true
+ *   CLINE_SHOW_PAID=true or cline_show_paid: true
+ *   OLLAMA_SHOW_PAID=true or ollama_show_paid: true
+ *
+ * PI_FREE_KILO_FREE_ONLY=true — restrict Kilo to free models even after login.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "./lib/logger.ts";
+
+const _logger = createLogger("config");
+
+interface PiFreeConfig {
+	openrouter_api_key?: string;
+	nvidia_api_key?: string;
+	opencode_api_key?: string;
+	fireworks_api_key?: string;
+	mistral_api_key?: string;
+	ollama_api_key?: string;
+	kilo_free_only?: boolean;
+	hidden_models?: string[];
+	// Per-provider paid model flags
+	openrouter_show_paid?: boolean;
+	nvidia_show_paid?: boolean;
+	fireworks_show_paid?: boolean;
+	cline_show_paid?: boolean;
+	zen_show_paid?: boolean;
+	mistral_show_paid?: boolean;
+	ollama_show_paid?: boolean;
+}
+
+const CONFIG_TEMPLATE: PiFreeConfig = {
+	openrouter_api_key: "",
+	nvidia_api_key: "",
+	opencode_api_key: "",
+	fireworks_api_key: "",
+	mistral_api_key: "",
+	ollama_api_key: "",
+	kilo_free_only: false,
+	hidden_models: [],
+	openrouter_show_paid: false,
+	nvidia_show_paid: false,
+	fireworks_show_paid: false,
+	cline_show_paid: false,
+	zen_show_paid: false,
+	mistral_show_paid: false,
+	ollama_show_paid: false,
+};
+
+const PI_DIR = join(process.env.HOME || process.env.USERPROFILE || "", ".pi");
+const CONFIG_PATH = join(PI_DIR, "free.json");
+
+function ensureConfigFile(): void {
+	try {
+		mkdirSync(PI_DIR, { recursive: true });
+		if (existsSync(CONFIG_PATH)) {
+			// Merge: add any new template keys without touching existing values
+			const existing = JSON.parse(
+				readFileSync(CONFIG_PATH, "utf8"),
+			) as PiFreeConfig;
+			const merged = { ...CONFIG_TEMPLATE, ...existing };
+			if (JSON.stringify(merged) !== JSON.stringify(existing)) {
+				writeFileSync(
+					CONFIG_PATH,
+					`${JSON.stringify(merged, null, 2)}\n`,
+					"utf8",
+				);
+			}
+		} else {
+			writeFileSync(
+				CONFIG_PATH,
+				`${JSON.stringify(CONFIG_TEMPLATE, null, 2)}\n`,
+				"utf8",
+			);
+		}
+	} catch (err) {
+		_logger.warn("Could not create config file", {
+			path: CONFIG_PATH,
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}
+
+function loadConfigFile(): PiFreeConfig {
+	try {
+		return JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as PiFreeConfig;
+	} catch {
+		return {};
+	}
+}
+
+ensureConfigFile();
+const file = loadConfigFile();
+
+// Resolve each value: env var takes priority over config file.
+// Treat empty strings in the config file as unset.
+function resolve(envKey: string, fileVal?: string): string | undefined {
+	return process.env[envKey] || (fileVal?.trim() ? fileVal : undefined);
+}
+
+// Resolve boolean flag: env var takes priority, then config file.
+// If neither is set, defaults to false (free-only mode).
+function resolveBool(envKey: string, fileVal?: boolean): boolean {
+	const envValue = process.env[envKey];
+	if (envValue === "true") return true;
+	if (envValue === "false") return false;
+	return fileVal === true;
+}
+
+// Global fallback (deprecated, use per-provider flags)
+// Returns true only if explicitly enabled via env var
+export const SHOW_PAID = process.env.PI_FREE_SHOW_PAID === "true";
+
+// Per-provider paid model flags - default to false (free-only) if not set
+export const OPENROUTER_SHOW_PAID = resolveBool(
+	"OPENROUTER_SHOW_PAID",
+	file.openrouter_show_paid,
+);
+
+export const NVIDIA_SHOW_PAID = resolveBool(
+	"NVIDIA_SHOW_PAID",
+	file.nvidia_show_paid,
+);
+
+export const FIREWORKS_SHOW_PAID = resolveBool(
+	"FIREWORKS_SHOW_PAID",
+	file.fireworks_show_paid,
+);
+
+export const CLINE_SHOW_PAID = resolveBool(
+	"CLINE_SHOW_PAID",
+	file.cline_show_paid,
+);
+
+export const ZEN_SHOW_PAID = resolveBool("ZEN_SHOW_PAID", file.zen_show_paid);
+
+export const MISTRAL_SHOW_PAID = resolveBool(
+	"MISTRAL_SHOW_PAID",
+	file.mistral_show_paid,
+);
+
+export const OLLAMA_SHOW_PAID = resolveBool(
+	"OLLAMA_SHOW_PAID",
+	file.ollama_show_paid,
+);
+
+export const KILO_FREE_ONLY = resolveBool(
+	"PI_FREE_KILO_FREE_ONLY",
+	file.kilo_free_only,
+);
+
+const HIDDEN: Set<string> = new Set(file.hidden_models ?? []);
+
+/** Removes any models whose id appears in hidden_models. */
+export function applyHidden<T extends { id: string }>(models: T[]): T[] {
+	if (HIDDEN.size === 0) return models;
+	return models.filter((m) => !HIDDEN.has(m.id));
+}
+
+export const OPENROUTER_API_KEY = resolve(
+	"OPENROUTER_API_KEY",
+	file.openrouter_api_key,
+);
+export const NVIDIA_API_KEY = resolve("NVIDIA_API_KEY", file.nvidia_api_key);
+export const OPENCODE_API_KEY = resolve(
+	"OPENCODE_API_KEY",
+	file.opencode_api_key,
+);
+export const FIREWORKS_API_KEY = resolve(
+	"FIREWORKS_API_KEY",
+	file.fireworks_api_key,
+);
+export const MISTRAL_API_KEY = resolve("MISTRAL_API_KEY", file.mistral_api_key);
+export const OLLAMA_API_KEY = resolve("OLLAMA_API_KEY", file.ollama_api_key);
+
+// Re-export provider names for consistency
+export {
+	PROVIDER_CLINE,
+	PROVIDER_FIREWORKS,
+	PROVIDER_KILO,
+	PROVIDER_MISTRAL,
+	PROVIDER_NVIDIA,
+	PROVIDER_OLLAMA,
+	PROVIDER_OPENROUTER,
+	PROVIDER_ZEN,
+} from "./constants.ts";
+
+// =============================================================================
+// Config Persistence
+// =============================================================================
+
+/** Save updated config values to ~/.pi/free.json */
+export function saveConfig(updates: Partial<PiFreeConfig>): void {
+	try {
+		const existing = loadConfigFile();
+		const merged = { ...existing, ...updates };
+		writeFileSync(CONFIG_PATH, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+		_logger.info("Config saved", {
+			path: CONFIG_PATH,
+			keys: Object.keys(updates),
+		});
+	} catch (err) {
+		_logger.error("Failed to save config", {
+			path: CONFIG_PATH,
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}
+
+/** Get current config values (for checking state) */
+export function getConfig(): PiFreeConfig {
+	return loadConfigFile();
+}

package/constants.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared constants for pi-free-providers.
+ * Centralizes provider names, URLs, and configuration values.
+ */
+
+// =============================================================================
+// Provider names (must match registerProvider calls)
+// =============================================================================
+
+export const PROVIDER_KILO = "kilo";
+export const PROVIDER_ZEN = "zen";
+export const PROVIDER_OPENROUTER = "openrouter";
+export const PROVIDER_NVIDIA = "nvidia";
+export const PROVIDER_CLINE = "cline";
+export const PROVIDER_FIREWORKS = "fireworks";
+export const PROVIDER_OLLAMA = "ollama";
+
+export const ALL_PROVIDERS = [
+	PROVIDER_KILO,
+	PROVIDER_ZEN,
+	PROVIDER_OPENROUTER,
+	PROVIDER_NVIDIA,
+	PROVIDER_CLINE,
+	PROVIDER_FIREWORKS,
+	PROVIDER_OLLAMA,
+] as const;
+
+// =============================================================================
+// Provider base URLs
+// =============================================================================
+
+export const BASE_URL_KILO = "https://api.kilo.ai/api/gateway";
+export const BASE_URL_ZEN = "https://opencode.ai/zen/v1";
+export const BASE_URL_OPENROUTER = "https://openrouter.ai/api/v1";
+export const BASE_URL_NVIDIA = "https://integrate.api.nvidia.com/v1";
+export const BASE_URL_CLINE = "https://api.cline.bot/api/v1";
+export const BASE_URL_FIREWORKS = "https://api.fireworks.ai/inference/v1";
+export const BASE_URL_OLLAMA = "https://ollama.com/v1";
+
+// =============================================================================
+// External URLs
+// =============================================================================
+
+export const URL_MODELS_DEV = "https://models.dev/api.json";
+export const URL_KILO_TOS = "https://kilo.ai/terms";
+export const URL_ZEN_TOS = "https://opencode.ai/terms";
+export const URL_CLINE_TOS = "https://cline.bot/tos";
+
+// =============================================================================
+// Cline auth
+// =============================================================================
+
+export const CLINE_AUTH_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+// =============================================================================
+// Configuration thresholds
+// =============================================================================
+
+export const NVIDIA_MIN_SIZE_B = 70; // Minimum model size for NVIDIA NIM
+export const DEFAULT_MIN_SIZE_B = 30; // Default minimum model size for filtering
+
+// =============================================================================
+// Timeouts (milliseconds)
+// =============================================================================
+
+// Timeout for fetch operations
+export const DEFAULT_FETCH_TIMEOUT_MS: number = 10_000;
+
+export interface TestConfig {
+	timeout: number;
+	retries: number;
+	label: string;
+}
+
+// LSP test - fixed - added missing property
+export const testConfig: TestConfig = {
+	timeout: 5000,
+	retries: 3,
+	label: "test",
+};
+
+// LSP test - fixed return type
+export function calculateTimeout(base: number): number {
+	return base * 2;
+}
+
+// LSP test - unused variable (should show hint/warning if configured)
+export function unusedParamTest(required: string, _unused: number): string {
+	return required.toUpperCase();
+}
+export const KILO_POLL_INTERVAL_MS = 3_000;
+export const KILO_TOKEN_EXPIRATION_MS = 365 * 24 * 60 * 60 * 1000; // 1 year
+
+// =============================================================================
+// Additional OpenAI-compatible providers
+// =============================================================================
+
+export const PROVIDER_GROQ = "groq";
+export const PROVIDER_TOGETHER = "together";
+export const PROVIDER_DEEPINFRA = "deepinfra";
+export const PROVIDER_MISTRAL = "mistral";
+export const PROVIDER_PERPLEXITY = "perplexity";
+export const PROVIDER_XAI = "xai";
+
+export const BASE_URL_GROQ = "https://api.groq.com/openai/v1";
+export const BASE_URL_TOGETHER = "https://api.together.xyz/v1";
+export const BASE_URL_DEEPINFRA = "https://api.deepinfra.com/v1/openai";
+export const BASE_URL_MISTRAL = "https://api.mistral.ai/v1";
+export const BASE_URL_PERPLEXITY = "https://api.perplexity.ai";
+export const BASE_URL_XAI = "https://api.x.ai/v1";

package/docs/free-tier-limits.md

@@ -0,0 +1,213 @@
+# Free Tier Rate Limits
+
+This document tracks the free tier usage limits for each provider in pi-free-providers.
+
+## Provider Limits
+
+| Provider | Free Tier Limit | Notes |
+|----------|-----------------|-------|
+| **Kilo** | 200 requests/hour | Per IP (anonymous) or per account (authenticated) |
+| **OpenRouter** | 1000 requests/day | For free tier (no API key) |
+| **Zen (OpenCode)** | Fair use | No hard limits, but abuse may be throttled |
+| **NVIDIA** | 1000 requests/month | NIM free tier |
+| **Fireworks** | 1000 requests/month | Free tier |
+| **Cline** | Undisclosed | Rate limited but limits not documented |
+
+## Usage Tracking
+
+The extension automatically tracks your usage against these limits:
+
+```typescript
+// Check current usage
+const usage = getFreeTierUsage("kilo");
+console.log(`Used ${usage.requestsThisHour}/${usage.limit.requestsPerHour} this hour`);
+
+// Get warning if approaching limit
+const warning = getLimitWarning("openrouter");
+if (warning) {
+  console.warn(warning); // "⚠️ openrouter: 85% of free tier used. ~150 requests remaining."
+}
+```
+
+## Status Indicators
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| 🟢 **OK** | < 70% used | No action needed |
+| 🟡 **Warning** | 70-90% used | Consider using other providers |
+| 🔴 **Critical** | > 90% used | Switch provider soon to avoid 429s |
+| ⚪ **Unknown** | Limits not documented | Monitor for errors |
+
+## What Happens When You Hit Limits
+
+When you approach or hit a rate limit:
+
+1. **Warning**: The system warns you before hitting the limit
+2. **429 Error**: Provider returns rate limit error
+3. **Auto-failover**: If `auto_model_hop` is enabled, automatically switches to another provider
+4. **Autocompact**: Suggests compacting conversation to reduce tokens
+
+## Understanding Exact Limits
+
+Per-model tracking helps discover exact limits empirically:
+
+### Example: Discovering Kilo's Per-Model Limits
+
+```typescript
+// After heavy usage, check the report
+logModelUsageReport("kilo");
+// [usage-report] kilo: 267 total requests
+//   - xiaomi/mimo-v2-pro:free: 201 requests  ← Hmm, stopped at ~200?
+//   - minimax/minimax-m2.5:free: 66 requests
+```
+
+This pattern suggests Kilo may have **per-model** limits (around 200/hour per model) in addition to IP-level limits.
+
+### Example: OpenRouter Daily Pattern
+
+```typescript
+logModelUsageReport("openrouter");
+// [usage-report] openrouter: 847 total requests
+//   - anthropic/claude-sonnet-4.6: 423 requests
+//   - google/gemini-3.1-pro-preview: 424 requests
+```
+
+Even distribution suggests OpenRouter's 1000/day limit is **provider-wide**, not per-model.
+
+### Example: Model-Specific Throttling
+
+```typescript
+// Compare two models at same provider
+const claudeUsage = getModelUsage("zen", "claude-opus-4-6");
+const geminiUsage = getModelUsage("zen", "gemini-3.1-pro");
+
+// If Claude hits 429s at 50 requests but Gemini works at 200,
+// Claude may have stricter rate limiting
+```
+
+## Avoiding Rate Limits
+
+### Strategy 1: Provider Rotation
+Use multiple providers to distribute load:
+
+```bash
+# Start with Kilo
+/model kilo/mimo-v2-pro:free
+
+# If rate limited, hop to OpenRouter
+/model openrouter/mimo-v2-pro:free
+```
+
+### Strategy 2: Session Management
+Start fresh sessions periodically to reset counters:
+
+```
+/session  # New session = fresh rate limit counters
+```
+
+### Strategy 3: Upgrade to Paid
+When free tier isn't enough:
+
+- **Kilo**: `/login kilo` for higher limits
+- **OpenRouter**: Set `OPENROUTER_API_KEY` for paid access
+- **NVIDIA**: Sign up for paid NIM access
+
+## Configuration
+
+Add to `~/.pi/free.json`:
+
+```json
+{
+  "auto_model_hop": true,
+  "max_model_hops": 3,
+  "allow_downgrades": "minor"
+}
+```
+
+This enables automatic failover when rate limits are hit.
+
+## Implementation Details
+
+Usage tracking is done via:
+- **In-memory counters**: Per session (resets when Pi restarts)
+- **Daily tracking**: Tracks requests per provider per day
+- **Hourly estimates**: Based on session activity
+- **Per-model tracking**: Granular tracking of which models you use most
+
+### Per-Model Tracking (NEW)
+
+We now track usage per model per provider:
+
+```typescript
+// Track a request for specific model
+incrementModelRequestCount("kilo", "xiaomi/mimo-v2-pro:free");
+
+// Get usage for specific model
+const usage = getModelUsage("kilo", "xiaomi/mimo-v2-pro:free");
+// { count: 45, lastUsed: 1711731234567 }
+
+// See which models you use most with a provider
+const kiloModels = getProviderModelUsage("kilo");
+// [
+//   { modelId: "xiaomi/mimo-v2-pro:free", count: 45, lastUsed: ... },
+//   { modelId: "minimax/minimax-m2.5:free", count: 32, lastUsed: ... }
+// ]
+
+// Get top models across all providers
+const top = getTopModels(5);
+// [
+//   { provider: "kilo", modelId: "xiaomi/mimo-v2-pro:free", count: 45 },
+//   { provider: "zen", modelId: "mimo-v2-pro-free", count: 38 },
+//   ...
+// ]
+```
+
+This helps identify:
+- Which models consume your quota fastest
+- If certain models have stricter limits
+- Optimal model rotation strategies
+
+Note: These are estimates. Provider-side counters are authoritative.
+
+## Known Limitations
+
+1. **No server-side sync**: We can't know the provider's exact count
+2. **Hourly estimates**: Hourly usage is estimated from daily total
+3. **IP-based limits**: Kilo's IP-based limits affect all users on same network
+4. **Undocumented limits**: Cline and Zen limits are not publicly documented
+
+## API Reference
+
+### Provider-Level Functions
+
+#### `getFreeTierUsage(provider: string)`
+Returns current usage against free tier limits.
+
+#### `isApproachingLimit(provider: string)`
+Returns `true` if usage is > 70% of limit.
+
+#### `getLimitWarning(provider: string)`
+Returns warning message if approaching limit, `null` otherwise.
+
+#### `formatFreeTierStatus(provider: string)`
+Returns formatted status string for display.
+
+### Per-Model Functions
+
+#### `incrementModelRequestCount(provider, modelId)`
+Track a request for a specific model. Call this on every request.
+
+#### `getModelUsage(provider, modelId)`
+Get usage stats for a specific model:
+```typescript
+{ count: 45, lastUsed: 1711731234567 }
+```
+
+#### `getProviderModelUsage(provider)`
+Get all model usage sorted by count (highest first) for a provider.
+
+#### `getTopModels(n)`
+Get top N most used models across all providers.
+
+#### `logModelUsageReport(provider?)`
+Print usage report to console. If provider omitted, shows top 10 across all providers.