pi-free 1.0.0

package/tests/zen.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Zen Provider Tests
+ */
+
+import type {
+	ExtensionAPI,
+	ProviderModelConfig,
+} from "@mariozechner/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock dependencies
+vi.mock("../config.ts", () => ({
+	OPENCODE_API_KEY: "test-key",
+	ZEN_SHOW_PAID: false,
+	PROVIDER_ZEN: "zen",
+	applyHidden: (models: ProviderModelConfig[]) => models,
+}));
+
+vi.mock("../constants.ts", () => ({
+	BASE_URL_ZEN: "https://opencode.ai/zen/v1",
+	DEFAULT_FETCH_TIMEOUT_MS: 10000,
+	URL_MODELS_DEV: "https://models.dev/api.json",
+	URL_ZEN_TOS: "https://opencode.ai/terms",
+}));
+
+vi.mock("../provider-helper.ts", () => ({
+	createReRegister: vi.fn(() => vi.fn()),
+	createCtxReRegister: vi.fn(() => vi.fn()),
+	setupProvider: vi.fn(),
+}));
+
+vi.mock("../util.ts", () => ({
+	fetchWithRetry: vi.fn(),
+	logWarning: vi.fn(),
+}));
+
+import { fetchWithRetry } from "../lib/util.ts";
+import { setupProvider } from "../provider-helper.ts";
+import zenProvider from "../providers/zen.ts";
+
+describe("Zen Provider", () => {
+	let mockPi: ExtensionAPI;
+	let mockOn: ReturnType<typeof vi.fn>;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockOn = vi.fn();
+
+		mockPi = {
+			on: mockOn,
+		} as unknown as ExtensionAPI;
+	});
+
+	describe("initialization", () => {
+		it("should register event handlers", async () => {
+			vi.mocked(fetchWithRetry).mockResolvedValue({
+				ok: true,
+				json: vi.fn().mockResolvedValue({ data: [{ id: "test-model" }] }),
+			} as unknown as Response);
+
+			await zenProvider(mockPi);
+
+			expect(mockOn).toHaveBeenCalledWith(
+				"session_start",
+				expect.any(Function),
+			);
+			expect(mockOn).toHaveBeenCalledWith(
+				"before_agent_start",
+				expect.any(Function),
+			);
+		});
+	});
+
+	describe("session_start handling", () => {
+		it("should fetch and register models", async () => {
+			const gatewayModels = {
+				data: [{ id: "big-pickle" }, { id: "mimo-v2-pro-free" }],
+			};
+			const modelsDevResponse = {
+				opencode: {
+					id: "opencode",
+					models: {
+						"big-pickle": {
+							id: "big-pickle",
+							name: "Big Pickle",
+							reasoning: true,
+							cost: { input: 0, output: 0 },
+							limit: { context: 200000, output: 128000 },
+							modalities: { input: ["text"] },
+						},
+					},
+				},
+			};
+
+			vi.mocked(fetchWithRetry)
+				.mockResolvedValueOnce({
+					ok: true,
+					json: vi.fn().mockResolvedValue(gatewayModels),
+				} as unknown as Response)
+				.mockResolvedValueOnce({
+					ok: true,
+					json: vi.fn().mockResolvedValue(modelsDevResponse),
+				} as unknown as Response);
+
+			await zenProvider(mockPi);
+
+			const sessionStartHandler = mockOn.mock.calls.find(
+				(call) => call[0] === "session_start",
+			)?.[1];
+
+			const mockRegisterProvider = vi.fn();
+			const mockCtx = {
+				modelRegistry: {
+					getAvailable: vi.fn().mockReturnValue([]),
+					registerProvider: mockRegisterProvider,
+				},
+			};
+
+			await sessionStartHandler({}, mockCtx);
+
+			expect(mockRegisterProvider).toHaveBeenCalledWith(
+				"zen",
+				expect.objectContaining({
+					baseUrl: "https://opencode.ai/zen/v1",
+					apiKey: "PI_FREE_ZEN_API_KEY",
+					headers: expect.objectContaining({
+						"X-Title": "Pi",
+						"x-opencode-session": expect.any(String),
+					}),
+				}),
+			);
+		});
+	});
+
+	describe("fallback behavior", () => {
+		it("should use static fallback when API fails", async () => {
+			vi.mocked(fetchWithRetry).mockRejectedValue(new Error("Network error"));
+
+			await zenProvider(mockPi);
+
+			const sessionStartHandler = mockOn.mock.calls.find(
+				(call) => call[0] === "session_start",
+			)?.[1];
+
+			const mockRegisterProvider = vi.fn();
+			const mockCtx = {
+				modelRegistry: {
+					getAvailable: vi.fn().mockReturnValue([]),
+					registerProvider: mockRegisterProvider,
+				},
+			};
+
+			await sessionStartHandler({}, mockCtx);
+
+			// When API fails, it should not register (let Pi use built-in)
+			expect(mockRegisterProvider).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("setupProvider integration", () => {
+		it("should call setupProvider with correct config", async () => {
+			vi.mocked(fetchWithRetry).mockResolvedValue({
+				ok: true,
+				json: vi.fn().mockResolvedValue({ data: [] }),
+			} as unknown as Response);
+
+			await zenProvider(mockPi);
+
+			expect(setupProvider).toHaveBeenCalledWith(
+				mockPi,
+				expect.objectContaining({
+					providerId: "zen",
+					tosUrl: "https://opencode.ai/terms",
+					hasKey: true,
+				}),
+				expect.any(Object),
+			);
+		});
+	});
+});

package/todo.md

@@ -0,0 +1,153 @@
+# TODO: Fix Usage Tracking & Rate Limit Attribution
+
+## Current State
+
+The usage tracking infrastructure exists but is **not fully functional**:
+
+1. **Usage commands are disabled** (`usage/commands.ts`)
+   - `/free-sessionusage` and `/free-totalusage` commands exist but are commented out
+   - Reason: "duplicate registration issues" across providers
+
+2. **Usage tracking works at runtime** (`usage/tracking.ts`)
+   - Per-model request counts tracked in `modelUsageCounts` Map
+   - Session stats tracked in `sessionStats` Map
+   - Called from `provider-helper.ts` on each `turn_end` event
+
+3. **Cumulative usage persists** (`usage/cumulative.ts`, `usage/store.ts`)
+   - Stored at `~/.pi/free-usage.json`
+   - Tracks all-time usage per provider/model
+
+4. **Free tier limits defined** (`free-tier-limits.ts`)
+   - Hardcoded limits per provider
+   - NOT correctly integrated with usage tracking
+
+## Problems to Fix
+
+### 1. Usage Commands Disabled
+**File:** `usage/commands.ts`
+
+The `registerUsageCommands()` function is empty. The slash commands need to:
+- Register once globally (not per-provider)
+- Show current session usage with rate limit status
+- Show cumulative all-time usage
+
+**Current:**
+```typescript
+export function registerUsageCommands(_pi: ExtensionAPI): void {
+    // Commands disabled - Pi shows duplicate registrations across providers
+    // TODO: Find reliable way to register global commands once
+}
+```
+
+**Needed:**
+- Register `/free-sessionusage` - shows current session breakdown
+- Register `/free-totalusage` - shows cumulative usage from disk
+- Include rate limit warnings (🟢🟡🔴) based on current usage vs limits
+
+### 2. Rate Limit Attribution Wrong
+**Files:** `usage/tracking.ts`, `free-tier-limits.ts`, `usage/formatters.ts`
+
+The `FREE_TIER_LIMITS` in `free-tier-limits.ts` defines limits, but:
+- Zen has no entry (has free tier but not in the list)
+- Ollama has no entry (has free tier but not in the list)
+- Fireworks has no entry (has free tier but not in the list)
+- Mistral has no entry (has free tier but not in the list)
+- Cline has no entry (has free tier but not in the list)
+
+**Current `FREE_TIER_LIMITS`:**
+```typescript
+export const FREE_TIER_LIMITS: Record<string, FreeTierLimit> = {
+    kilo: { provider: "kilo", requestsPerHour: 200, ... },
+    openrouter: { provider: "openrouter", requestsPerDay: 1000, ... },
+    nvidia: { provider: "nvidia", requestsPerMonth: 1000, ... },
+    // Missing: zen, ollama, fireworks, mistral, cline
+};
+```
+
+**Needed:**
+- Add all providers with free tiers
+- Research actual limits from provider docs
+- Track per-provider usage counts separately (currently aggregated in `metrics.ts`)
+
+### 3. Usage Formatters Not Integrated
+**File:** `usage/formatters.ts`
+
+The formatters exist but are not called anywhere:
+- `formatSessionUsage()` - formats session stats
+- `formatCumulativeUsage()` - formats cumulative stats  
+- `formatFreeTierStatus()` - formats rate limit status with 🟢🟡🔴
+
+**Needed:**
+- Call formatters from usage commands
+- Show rate limit warnings based on `FREE_TIER_LIMITS`
+- Calculate percentage used: `(currentUsage / limit) * 100`
+
+### 4. Provider-Level Usage Tracking Missing
+**File:** `usage/tracking.ts`
+
+Current tracking aggregates by model, but doesn't track per-provider totals correctly for rate limits.
+
+The `sessionStats.providers` Map exists but:
+- Doesn't reset per time window (hour/day/month)
+- Doesn't check against `FREE_TIER_LIMITS`
+
+**Needed:**
+- Track usage per time window (hourly for Kilo, daily for OpenRouter, monthly for NVIDIA)
+- Check limits before incrementing (warn at 80%, critical at 95%)
+- Show warning in UI when approaching limits
+
+## Implementation Plan
+
+### Phase 1: Fix Free Tier Limits
+- [ ] Add missing providers to `FREE_TIER_LIMITS`
+  - [ ] Zen: 1000/day (verify with opencode.ai docs)
+  - [ ] Ollama: 5 hours + 7 days reset (explain credit system)
+  - [ ] Fireworks: research free tier limits
+  - [ ] Mistral: research free tier limits  
+  - [ ] Cline: research free tier limits
+
+### Phase 2: Wire Up Usage Commands
+- [ ] Create single registration point for global commands
+- [ ] Register `/free-sessionusage` command
+- [ ] Register `/free-totalusage` command
+- [ ] Test commands don't duplicate across providers
+
+### Phase 3: Integrate Formatters
+- [ ] Call `formatSessionUsage()` in `/free-sessionusage`
+- [ ] Call `formatCumulativeUsage()` in `/free-totalusage`
+- [ ] Add rate limit status to both commands using `formatFreeTierStatus()`
+
+### Phase 4: Per-Provider Rate Limit Warnings
+- [ ] Track usage per time window (hour/day/month)
+- [ ] Add limit checking in `incrementRequestCount()`
+- [ ] Show UI notification when approaching limit (80% = 🟡, 95% = 🔴)
+- [ ] Reset counters when time window expires
+
+## Provider Free Tier Research
+
+| Provider | Free Tier | Rate Limit | Documentation |
+|----------|-----------|------------|---------------|
+| Kilo | 14 models | 200 req/hour | kilo.ai/terms |
+| Zen | 11 models | 1000 req/day | opencode.ai |
+| OpenRouter | 29 models | 1000 req/day | openrouter.ai/docs |
+| NVIDIA | Curated 70B+ | 1000 credits/mo | build.nvidia.com |
+| Ollama | Cloud models | 5hrs + 7 days reset | ollama.com |
+| Fireworks | ? | ? | app.fireworks.ai |
+| Mistral | ? | ? | mistral.ai |
+| Cline | ? | ? | cline.bot |
+
+## Files to Modify
+
+1. `free-tier-limits.ts` - Add missing providers, verify limits
+2. `usage/commands.ts` - Implement command registration
+3. `usage/formatters.ts` - Ensure formatters use correct limits
+4. `usage/tracking.ts` - Add per-time-window tracking
+5. `provider-helper.ts` - Call limit check on turn_end
+6. `README.md` - Document usage commands once working
+
+## Notes
+
+- The `metrics.ts` file has `getDailyRequestCount()` but it tracks ALL providers together
+- Need separate counters per provider per time window
+- Consider using `usage/sessions.ts` for session-level tracking
+- The cumulative storage in `usage/store.ts` works - don't break it

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"lib": ["ES2022"],
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"allowImportingTsExtensions": true,
+		"noEmit": true,
+		"baseUrl": ".",
+		"paths": {
+			"@mariozechner/pi-coding-agent": [
+				"node_modules/@mariozechner/pi-coding-agent"
+			]
+		}
+	},
+	"include": ["**/*.ts", "providers/**/*.ts"],
+	"exclude": ["node_modules", ".pi-lens"]
+}

package/usage/commands.ts

@@ -0,0 +1,17 @@
+/**
+ * Free tier usage commands
+ *
+ * Provides:
+ * - /free-sessionusage: Current session breakdown
+ * - /free-totalusage: Cumulative usage from disk
+ *
+ * NOTE: Commands temporarily disabled due to duplicate registration issues.
+ * Use /kilo-sessionusage or /zen-sessionusage instead.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export function registerUsageCommands(_pi: ExtensionAPI): void {
+	// Commands disabled - Pi shows duplicate registrations across providers
+	// TODO: Find reliable way to register global commands once
+}

package/usage/cumulative.ts

@@ -0,0 +1,193 @@
+/**
+ * Cumulative usage persistence - disk storage for all-time stats
+ */
+
+import { join } from "node:path";
+import { createJSONStore } from "../lib/json-persistence.ts";
+import { createLogger } from "../lib/logger.ts";
+
+const _logger = createLogger("usage:cumulative");
+
+const PI_DIR = join(process.env.HOME || process.env.USERPROFILE || "", ".pi");
+const USAGE_FILE = join(PI_DIR, "free-cumulative-usage.json");
+
+interface CumulativeProviderStats {
+	totalRequests: number;
+	totalTokensIn: number;
+	totalTokensOut: number;
+	totalCacheRead: number;
+	totalCacheWrite: number;
+	totalCost: number;
+	models: Record<
+		string,
+		{
+			count: number;
+			tokensIn: number;
+			tokensOut: number;
+			cacheRead: number;
+			cacheWrite: number;
+			cost: number;
+		}
+	>;
+	firstUsed: string;
+	lastUsed: string;
+}
+
+interface CumulativeUsage {
+	providers: Record<string, CumulativeProviderStats>;
+	grandTotalRequests: number;
+	grandTotalTokensIn: number;
+	grandTotalTokensOut: number;
+	grandTotalCacheRead: number;
+	grandTotalCacheWrite: number;
+	grandTotalCost: number;
+}
+
+const cumulativeStore = createJSONStore<CumulativeUsage>(USAGE_FILE, {
+	providers: {},
+	grandTotalRequests: 0,
+	grandTotalTokensIn: 0,
+	grandTotalTokensOut: 0,
+	grandTotalCacheRead: 0,
+	grandTotalCacheWrite: 0,
+	grandTotalCost: 0,
+});
+
+export function persistUsage(
+	provider: string,
+	modelId: string,
+	tokensIn: number,
+	tokensOut: number,
+	cacheRead: number,
+	cacheWrite: number,
+	cost: number,
+): void {
+	const data = cumulativeStore.load();
+	const now = new Date().toISOString();
+
+	let providerStats = data.providers[provider];
+	if (!providerStats) {
+		providerStats = {
+			totalRequests: 0,
+			totalTokensIn: 0,
+			totalTokensOut: 0,
+			totalCacheRead: 0,
+			totalCacheWrite: 0,
+			totalCost: 0,
+			models: {},
+			firstUsed: now,
+			lastUsed: now,
+		};
+		data.providers[provider] = providerStats;
+	}
+
+	providerStats.totalRequests++;
+	providerStats.totalTokensIn += tokensIn;
+	providerStats.totalTokensOut += tokensOut;
+	providerStats.totalCacheRead += cacheRead;
+	providerStats.totalCacheWrite += cacheWrite;
+	providerStats.totalCost += cost;
+	providerStats.lastUsed = now;
+
+	const modelStats = providerStats.models[modelId] ?? {
+		count: 0,
+		tokensIn: 0,
+		tokensOut: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		cost: 0,
+	};
+	modelStats.count++;
+	modelStats.tokensIn += tokensIn;
+	modelStats.tokensOut += tokensOut;
+	modelStats.cacheRead += cacheRead;
+	modelStats.cacheWrite += cacheWrite;
+	modelStats.cost += cost;
+	providerStats.models[modelId] = modelStats;
+
+	data.grandTotalRequests++;
+	data.grandTotalTokensIn += tokensIn;
+	data.grandTotalTokensOut += tokensOut;
+	data.grandTotalCacheRead += cacheRead;
+	data.grandTotalCacheWrite += cacheWrite;
+	data.grandTotalCost += cost;
+
+	cumulativeStore.save(data);
+}
+
+export interface CumulativeUsageReport {
+	providers: Array<{
+		name: string;
+		totalRequests: number;
+		totalTokensIn: number;
+		totalTokensOut: number;
+		totalCacheRead: number;
+		totalCacheWrite: number;
+		totalCost: number;
+		modelCount: number;
+		firstUsed: string;
+		lastUsed: string;
+		topModels: Array<{
+			modelId: string;
+			count: number;
+			tokensIn: number;
+			tokensOut: number;
+			cacheRead: number;
+			cacheWrite: number;
+			cost: number;
+		}>;
+	}>;
+	grandTotalRequests: number;
+	grandTotalTokensIn: number;
+	grandTotalTokensOut: number;
+	grandTotalCacheRead: number;
+	grandTotalCacheWrite: number;
+	grandTotalCost: number;
+}
+
+export function getCumulativeUsage(): CumulativeUsageReport {
+	const data = cumulativeStore.load();
+
+	const providers: CumulativeUsageReport["providers"] = [];
+
+	for (const [name, stats] of Object.entries(data.providers)) {
+		const topModels = Object.entries(stats.models)
+			.map(([modelId, m]) => ({
+				modelId,
+				count: m.count,
+				tokensIn: m.tokensIn,
+				tokensOut: m.tokensOut,
+				cacheRead: m.cacheRead,
+				cacheWrite: m.cacheWrite,
+				cost: m.cost,
+			}))
+			.sort((a, b) => b.count - a.count)
+			.slice(0, 5);
+
+		providers.push({
+			name,
+			totalRequests: stats.totalRequests,
+			totalTokensIn: stats.totalTokensIn,
+			totalTokensOut: stats.totalTokensOut,
+			totalCacheRead: stats.totalCacheRead,
+			totalCacheWrite: stats.totalCacheWrite,
+			totalCost: stats.totalCost,
+			modelCount: Object.keys(stats.models).length,
+			firstUsed: stats.firstUsed,
+			lastUsed: stats.lastUsed,
+			topModels,
+		});
+	}
+
+	providers.sort((a, b) => b.totalRequests - a.totalRequests);
+
+	return {
+		providers,
+		grandTotalRequests: data.grandTotalRequests,
+		grandTotalTokensIn: data.grandTotalTokensIn,
+		grandTotalTokensOut: data.grandTotalTokensOut,
+		grandTotalCacheRead: data.grandTotalCacheRead,
+		grandTotalCacheWrite: data.grandTotalCacheWrite,
+		grandTotalCost: data.grandTotalCost,
+	};
+}

package/usage/formatters.ts

@@ -0,0 +1,131 @@
+/**
+ * Usage report formatters - text formatting for display
+ */
+
+import type { CumulativeUsageReport } from "./cumulative.ts";
+import {
+	type FreeTierLimit,
+	getFreeTierUsage,
+	getLimitWarning,
+} from "./limits.ts";
+import type { SessionUsageReport } from "./tracking.ts";
+
+export interface FreeTierUsage {
+	provider: string;
+	requestsToday: number;
+	requestsThisHour: number;
+	requestsThisMonth?: number;
+	limit: FreeTierLimit;
+	remainingToday?: number;
+	remainingThisHour?: number;
+	remainingThisMonth?: number;
+	percentUsed: number;
+	status: "ok" | "warning" | "critical" | "unknown";
+}
+
+export function formatSessionUsage(report: SessionUsageReport): string {
+	if (report.providers.length === 0) {
+		return "No usage recorded in this session yet.";
+	}
+
+	const lines: string[] = [];
+	lines.push("━".repeat(50));
+	lines.push(`📊 Session Usage (${report.durationFormatted})`);
+	lines.push("━".repeat(50));
+	lines.push("");
+
+	for (const p of report.providers) {
+		const warning = getLimitWarning(p.name);
+		const statusEmoji = warning ? (warning.includes("⚠️") ? "🔴" : "🟡") : "🟢";
+		lines.push(`${statusEmoji} ${p.name}`);
+		lines.push(`   Requests: ${p.requests}`);
+		lines.push(
+			`   Tokens: ~${Math.round(p.tokensIn / 1000)}K in, ~${Math.round(p.tokensOut / 1000)}K out`,
+		);
+
+		if (p.topModels.length > 0) {
+			lines.push(`   Top models:`);
+			for (const m of p.topModels.slice(0, 3)) {
+				lines.push(`     • ${m.modelId.split("/").pop()}: ${m.count} req`);
+			}
+		}
+		lines.push("");
+	}
+
+	lines.push("━".repeat(50));
+	lines.push(
+		`📈 Totals: ${report.totalRequests} requests, ~${Math.round(report.totalTokensIn / 1000)}K tokens`,
+	);
+	lines.push("━".repeat(50));
+
+	return lines.join("\n");
+}
+
+export function formatCumulativeUsage(report: CumulativeUsageReport): string {
+	if (report.providers.length === 0) {
+		return "No cumulative usage data yet. Start using free models!";
+	}
+
+	const lines: string[] = [];
+	lines.push("━".repeat(50));
+	lines.push("📊 Total Usage (All Time)");
+	lines.push("━".repeat(50));
+	lines.push("");
+
+	for (const p of report.providers) {
+		lines.push(`🔹 ${p.name}`);
+		lines.push(`   Requests: ${p.totalRequests.toLocaleString()}`);
+		lines.push(
+			`   Tokens: ~${Math.round(p.totalTokensIn / 1000).toLocaleString()}K in, ~${Math.round(p.totalTokensOut / 1000).toLocaleString()}K out`,
+		);
+		lines.push(`   Models used: ${p.modelCount}`);
+
+		if (p.topModels.length > 0) {
+			lines.push(`   Top models:`);
+			for (const m of p.topModels.slice(0, 3)) {
+				lines.push(
+					`     • ${m.modelId.split("/").pop()}: ${m.count.toLocaleString()} req`,
+				);
+			}
+		}
+
+		lines.push(`   Active since: ${p.firstUsed.split("T")[0]}`);
+		lines.push("");
+	}
+
+	lines.push("━".repeat(50));
+	lines.push(`📈 Grand Totals:`);
+	lines.push(`   ${report.grandTotalRequests.toLocaleString()} requests`);
+	lines.push(
+		`   ~${Math.round(report.grandTotalTokensIn / 1000).toLocaleString()}K input tokens`,
+	);
+	lines.push(
+		`   ~${Math.round(report.grandTotalTokensOut / 1000).toLocaleString()}K output tokens`,
+	);
+	lines.push("━".repeat(50));
+
+	return lines.join("\n");
+}
+
+export function formatFreeTierStatus(provider: string): string {
+	const usage = getFreeTierUsage(provider);
+	const parts: string[] = [];
+
+	if (usage.limit.requestsPerHour) {
+		parts.push(`${usage.requestsThisHour}/${usage.limit.requestsPerHour}/h`);
+	}
+	if (usage.limit.requestsPerDay) {
+		parts.push(`${usage.requestsToday}/${usage.limit.requestsPerDay}/d`);
+	}
+	if (usage.limit.requestsPerMonth) {
+		parts.push(
+			`${usage.requestsThisMonth ?? 0}/${usage.limit.requestsPerMonth}/mo`,
+		);
+	}
+
+	if (parts.length === 0) {
+		return `${provider}: ${usage.limit.description}`;
+	}
+
+	return `${provider}: ${parts.join(" | ")}`;
+}