@robhowley/pi-openrouter 0.9.0 → 0.10.0

package/extensions/openrouter/local-usage.ts

@@ -2,11 +2,45 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import type { LocalUsageEvent, UsageAggregate } from './types.js';
-import { ZERO_AGGREGATE } from './types.js';
+import { createZeroAggregate } from './types.js';
 
 export type { LocalUsageEvent };
 
-const LOCAL_USAGE_DIR = path.join(os.homedir(), '.pi', 'openrouter', 'usage');
+const DEFAULT_LOCAL_USAGE_DIR = path.join(os.homedir(), '.pi', 'openrouter', 'usage');
+
+// Allow overriding usage directory for testing
+let localUsageDirOverride: string | null = null;
+
+/**
+ * Get the local usage directory.
+ * Uses override if set (for testing), otherwise uses default.
+ */
+function getLocalUsageDir(): string {
+  return localUsageDirOverride ?? DEFAULT_LOCAL_USAGE_DIR;
+}
+
+/**
+ * Set a custom local usage directory (for testing).
+ * Pass null to reset to default.
+ */
+export function setLocalUsageDir(dir: string | null): void {
+  localUsageDirOverride = dir;
+}
+
+/**
+ * Default retention period for local usage files (90 days).
+ * Files older than this will be deleted during opportunistic cleanup.
+ */
+const DEFAULT_RETENTION_DAYS = 90;
+
+/**
+ * Check if debug logging is enabled via environment variable.
+ * When PI_OPENROUTER_DEBUG_USAGE=1, verbose logging is enabled.
+ * Otherwise, logging is quiet to avoid noise.
+ */
+function isDebugEnabled(): boolean {
+  return process.env['PI_OPENROUTER_DEBUG_USAGE'] === '1';
+}
 
 /**
  * Get current UTC date as YYYY-MM-DD
@@ -49,19 +83,33 @@ export function* iterateDates(start: string, end: string): Generator<string> {
 /**
  * Append a single LocalUsageEvent to the appropriate daily JSONL file.
  * File is determined by UTC date from completedAt.
+ *
+ * Performs opportunistic cleanup of old files after successful write.
+ * All errors fail open - logged only when debug flag is enabled.
  */
 export async function writeLocalUsage(event: LocalUsageEvent): Promise<void> {
   try {
     const dateStr = getUtcDateFromTimestamp(event.completedAt);
-    const filePath = path.join(LOCAL_USAGE_DIR, `${dateStr}.jsonl`);
+    const usageDir = getLocalUsageDir();
+    const filePath = path.join(usageDir, `${dateStr}.jsonl`);
 
-    await fs.mkdir(LOCAL_USAGE_DIR, { recursive: true });
+    await fs.mkdir(usageDir, { recursive: true });
 
     const line = JSON.stringify(event) + '\n';
     await fs.appendFile(filePath, line, 'utf8');
+
+    // Opportunistically clean up old files after successful write
+    // This is fire-and-forget - errors are caught and logged only if debug is enabled
+    cleanupOldUsageFiles().catch((err) => {
+      if (isDebugEnabled()) {
+        console.error('[local-usage] Background cleanup failed:', err);
+      }
+    });
   } catch (err) {
     // Fail open - log but don't throw to avoid breaking the user experience
-    console.error('[local-usage] Failed to write usage event:', err);
+    if (isDebugEnabled()) {
+      console.error('[local-usage] Failed to write usage event:', err);
+    }
   }
 }
 
@@ -78,9 +126,10 @@ export interface ReadLocalUsageOptions {
  */
 export async function readLocalUsage(options: ReadLocalUsageOptions): Promise<LocalUsageEvent[]> {
   const events: LocalUsageEvent[] = [];
+  const usageDir = getLocalUsageDir();
 
   for (const dateStr of iterateDates(options.fromDateUtc, options.toDateUtc)) {
-    const filePath = path.join(LOCAL_USAGE_DIR, `${dateStr}.jsonl`);
+    const filePath = path.join(usageDir, `${dateStr}.jsonl`);
 
     try {
       const content = await fs.readFile(filePath, 'utf8');
@@ -95,7 +144,9 @@ export async function readLocalUsage(options: ReadLocalUsageOptions): Promise<Lo
           events.push(event);
         } catch (parseErr) {
           // Skip malformed lines but continue
-          console.warn(`[local-usage] Malformed line in ${dateStr}.jsonl:`, parseErr);
+          if (isDebugEnabled()) {
+            console.warn(`[local-usage] Malformed line in ${dateStr}.jsonl:`, parseErr);
+          }
         }
       }
     } catch (err) {
@@ -103,7 +154,9 @@ export async function readLocalUsage(options: ReadLocalUsageOptions): Promise<Lo
         // Missing file is OK - just no data for this date
         continue;
       }
-      console.error(`[local-usage] Failed to read ${dateStr}.jsonl:`, err);
+      if (isDebugEnabled()) {
+        console.error(`[local-usage] Failed to read ${dateStr}.jsonl:`, err);
+      }
       // Continue to next date despite error
     }
   }
@@ -112,15 +165,9 @@ export async function readLocalUsage(options: ReadLocalUsageOptions): Promise<Lo
 }
 
 /**
- * Aggregate local usage events into UsageAggregate.
- * Deduplicates by id (first occurrence wins).
+ * Deduplicate local usage events by id (first occurrence wins).
  */
-export function aggregateLocal(events: LocalUsageEvent[]): UsageAggregate {
-  if (events.length === 0) {
-    return ZERO_AGGREGATE;
-  }
-
-  // Deduplicate by id
+export function dedupeLocalUsageEvents(events: LocalUsageEvent[]): LocalUsageEvent[] {
   const seen = new Set<string>();
   const unique: LocalUsageEvent[] = [];
 
@@ -130,19 +177,100 @@ export function aggregateLocal(events: LocalUsageEvent[]): UsageAggregate {
     unique.push(event);
   }
 
-  // Aggregate
-  const result = unique.reduce(
-    (acc, event) => {
-      acc.requests += event.requests ?? 1;
-      acc.promptTokens += event.promptTokens || 0;
-      acc.completionTokens += event.completionTokens || 0;
-      acc.reasoningTokens += event.reasoningTokens || 0;
-      acc.cacheReadTokens += event.cacheReadTokens || 0;
-      acc.cacheWriteTokens += event.cacheWriteTokens || 0;
-      acc.cost += event.cost || 0;
-      return acc;
-    },
-    { ...ZERO_AGGREGATE },
-  );
+  return unique;
+}
+
+/**
+ * Aggregate local usage events into UsageAggregate.
+ * Deduplicates by id (first occurrence wins).
+ */
+export function aggregateLocal(events: LocalUsageEvent[]): UsageAggregate {
+  if (events.length === 0) {
+    return createZeroAggregate();
+  }
+
+  const result = dedupeLocalUsageEvents(events).reduce((acc, event) => {
+    acc.requests += event.requests ?? 1;
+    acc.promptTokens += event.promptTokens || 0;
+    acc.completionTokens += event.completionTokens || 0;
+    acc.reasoningTokens += event.reasoningTokens || 0;
+    acc.cacheReadTokens += event.cacheReadTokens || 0;
+    acc.cacheWriteTokens += event.cacheWriteTokens || 0;
+    acc.cost += event.cost || 0;
+    return acc;
+  }, createZeroAggregate());
   return result;
 }
+
+export interface CleanupOptions {
+  /** Number of days to retain (default: 90) */
+  retentionDays?: number;
+}
+
+/**
+ * Delete local usage files older than the retention window.
+ *
+ * This is called opportunistically after writes and fails open.
+ * Errors are logged only when debug flag is enabled.
+ *
+ * @param options - Cleanup configuration
+ * @param options.retentionDays - Days to retain (default: 90)
+ */
+export async function cleanupOldUsageFiles(options: CleanupOptions = {}): Promise<void> {
+  const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
+  const usageDir = getLocalUsageDir();
+
+  try {
+    // Calculate cutoff date
+    const today = getCurrentUtcDate();
+    const cutoffDate = addUtcDays(today, -retentionDays);
+
+    // List all files in usage directory
+    const files = await fs.readdir(usageDir);
+    const jsonlFiles = files.filter((f) => f.endsWith('.jsonl'));
+
+    let deletedCount = 0;
+
+    for (const filename of jsonlFiles) {
+      try {
+        // Extract date from filename (YYYY-MM-DD.jsonl)
+        const dateStr = filename.replace('.jsonl', '');
+
+        // Validate date format and value
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+          // Skip malformed filenames
+          continue;
+        }
+
+        const fileDate = new Date(dateStr + 'T00:00:00Z');
+        if (isNaN(fileDate.getTime())) {
+          // Skip invalid dates
+          continue;
+        }
+
+        // Delete if older than cutoff
+        if (dateStr < cutoffDate) {
+          const filePath = path.join(usageDir, filename);
+          await fs.unlink(filePath);
+          deletedCount++;
+        }
+      } catch (err) {
+        // Skip individual file errors
+        if (isDebugEnabled()) {
+          console.error(`[local-usage] Failed to delete ${filename}:`, err);
+        }
+      }
+    }
+
+    if (isDebugEnabled() && deletedCount > 0) {
+      console.log(
+        `[local-usage] Cleaned up ${deletedCount} old usage file${deletedCount === 1 ? '' : 's'}`,
+      );
+    }
+  } catch (err) {
+    // Fail open on directory read errors
+    if (isDebugEnabled()) {
+      console.error('[local-usage] Failed to cleanup old usage files:', err);
+    }
+  }
+}

package/extensions/openrouter/models/__tests__/cache.test.ts

@@ -1,9 +1,16 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { mkdir, rm, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
-import { loadCache, saveCache, getCacheAgeMs, formatCacheAge, setCacheDir } from '../cache.js';
+import {
+  loadCache,
+  saveCache,
+  getCacheAgeMs,
+  formatDuration,
+  formatCacheAge,
+  setCacheDir,
+} from '../cache.js';
 import { createMockCache } from '../../__tests__/fixtures.js';
 
 // Each test gets its own isolated temp directory
@@ -65,6 +72,18 @@ describe('loadCache', () => {
     const result = await loadCache();
     expect(result).toBeNull();
   });
+
+  it('should return null when cache timestamp is too far in the future', async () => {
+    await mkdir(testCacheDir, { recursive: true });
+    const cacheFile = join(testCacheDir, 'models-cache.json');
+    await writeFile(
+      cacheFile,
+      JSON.stringify(createMockCache({ timestamp: Date.now() + 6 * 60000 })),
+    );
+
+    const result = await loadCache();
+    expect(result).toBeNull();
+  });
 });
 
 describe('saveCache', () => {
@@ -93,6 +112,24 @@ describe('saveCache', () => {
     const loaded = await loadCache();
     expect(loaded!.timestamp).toBe(2000);
   });
+
+  it('should clamp future timestamps when saving', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-05-22T12:00:00.000Z'));
+
+    try {
+      const now = Date.now();
+      const mockCache = createMockCache({ timestamp: now + 60000 });
+
+      await saveCache(mockCache);
+
+      const loaded = await loadCache();
+      expect(loaded).not.toBeNull();
+      expect(loaded!.timestamp).toBe(now);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });
 
 describe('getCacheAgeMs', () => {
@@ -111,6 +148,25 @@ describe('getCacheAgeMs', () => {
     expect(age).toBeGreaterThanOrEqual(0);
     expect(age).toBeLessThan(100);
   });
+
+  it('should clamp small future skew to age 0', () => {
+    const cache = createMockCache({ timestamp: Date.now() + 60000 });
+    expect(getCacheAgeMs(cache)).toBe(0);
+  });
+});
+
+describe('formatDuration', () => {
+  it('should return unknown for null values', () => {
+    expect(formatDuration(null)).toBe('unknown');
+  });
+
+  it('should format zero as less than one minute', () => {
+    expect(formatDuration(0)).toBe('<1m');
+  });
+
+  it('should format negative values as less than one minute', () => {
+    expect(formatDuration(-1)).toBe('<1m');
+  });
 });
 
 describe('formatCacheAge', () => {
@@ -137,4 +193,9 @@ describe('formatCacheAge', () => {
     const cache = createMockCache({ timestamp: Date.now() - 60 * 60000 }); // exactly 1 hour
     expect(formatCacheAge(cache)).toBe('1h');
   });
+
+  it('should clamp future cache age display to less than one minute', () => {
+    const cache = createMockCache({ timestamp: Date.now() + 60000 });
+    expect(formatCacheAge(cache)).toBe('<1m');
+  });
 });

package/extensions/openrouter/models/__tests__/mapper.test.ts

@@ -33,6 +33,7 @@ describe('mapOpenRouterModel', () => {
     }> = [
       { name: 'empty id', overrides: { id: '' } },
       { name: 'undefined id (deleted property)', overrides: (m) => delete (m as any).id },
+      { name: 'missing pricing object', overrides: { pricing: undefined as any } },
       { name: 'missing pricing.prompt', overrides: { pricing: { completion: '0.000001' } as any } },
       { name: 'missing pricing.completion', overrides: { pricing: { prompt: '0.000001' } as any } },
       {
@@ -213,6 +214,7 @@ describe('mapOpenRouterModels', () => {
 
     expect(result.configs).toHaveLength(2);
     expect(result.skipped).toBe(1);
+    expect(result.skippedDetails).toEqual([{ id: 'unknown', reason: 'missing id' }]);
     expect(result.configs[0]!.id).toBe('model/valid-1');
     expect(result.configs[1]!.id).toBe('model/valid-2');
   });
@@ -237,4 +239,31 @@ describe('mapOpenRouterModels', () => {
     expect(result.configs).toHaveLength(0);
     expect(result.skipped).toBe(3);
   });
+
+  it('should add optional human-readable hints without changing reason codes', async () => {
+    const result = await mapOpenRouterModels([
+      createValidModel({
+        id: 'provider/no-context',
+        context_length: 0,
+        top_provider: { context_length: 0 },
+      }),
+      createValidModel({
+        id: 'provider/no-pricing',
+        pricing: { prompt: '0.000001' } as any,
+      }),
+    ]);
+
+    expect(result.skippedDetails).toEqual([
+      {
+        id: 'provider/no-context',
+        reason: 'missing context window',
+        hint: expect.stringContaining('contextWindow'),
+      },
+      {
+        id: 'provider/no-pricing',
+        reason: 'missing completion pricing',
+        hint: expect.stringContaining('cost safely'),
+      },
+    ]);
+  });
 });