@robhowley/pi-openrouter 0.7.0 → 0.8.0

package/extensions/openrouter/index.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
 import type { UsageSummary } from './types.js';
+import { MS_PER_MINUTE } from './models/types.js';
 import {
   usageCache,
   startBackgroundRefresh,
@@ -17,10 +18,47 @@ import type { KeyInfo } from './account-types.js';
 import type { RollupStatus } from './account-types.js';
 import crypto from 'node:crypto';
 
+// Import models sync
+import {
+  syncModels,
+  getSyncState,
+  isSyncEnabled,
+  getSkipReasonsAsync,
+  groupSkipReasons,
+} from './models/sync.js';
+import { loadCache, getCacheAgeMs, formatDuration } from './models/cache.js';
+
 // Store the current session state for use in command handlers
 let currentSessionState: OpenRouterSessionState | null = null;
 let sessionTrackingInstalled = false;
 
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Format skipped models details for --skipped flag output.
+ */
+function formatSkippedDetails(
+  skipCount: number,
+  groupedReasons: Record<string, number>,
+  skipReasons: Array<{ id: string; reason: string }>,
+): string {
+  if (skipCount === 0) {
+    return '\n\nNo skipped models';
+  }
+
+  let details = `\n\nOpenRouter skipped models: ${skipCount}\n`;
+  for (const [reason, count] of Object.entries(groupedReasons)) {
+    details += `\n${count} ${reason}\n`;
+    const modelsWithReason = skipReasons.filter((r) => r.reason === reason).map((r) => r.id);
+    for (const id of modelsWithReason) {
+      details += `- ${id}\n`;
+    }
+  }
+  return details;
+}
+
 // =============================================================================
 // Session State Management
 // =============================================================================
@@ -95,10 +133,14 @@ export default function (pi: ExtensionAPI) {
       if (!message) return;
 
       // Check if this is an OpenRouter request based on the message content/model
+      // Include url/endpoint from turnEvent so isOpenRouterRequest can check them
       const isOpenRouter = isOpenRouterRequest(
-        { type: 'before_provider_request', payload: message } as unknown as Parameters<
-          typeof isOpenRouterRequest
-        >[0],
+        {
+          type: 'before_provider_request',
+          payload: message,
+          url: turnEvent['url'],
+          endpoint: turnEvent['endpoint'],
+        } as unknown as Parameters<typeof isOpenRouterRequest>[0],
         ctx,
       );
       if (!isOpenRouter) return;
@@ -130,18 +172,20 @@ export default function (pi: ExtensionAPI) {
       // Calculate total cost from usage.cost.total
       const totalCost = usage.cost?.total;
 
-      const localEvent = {
+      const localEvent: LocalUsageEvent = {
         id: crypto.randomUUID(),
-        generationId: message['responseId'],
+        generationId: String(message['responseId'] ?? ''),
         sessionId: getCurrentSessionId(ctx),
         completedAt: new Date().toISOString(),
-        model: modelToLog,
-        promptTokens: usage.input,
-        completionTokens: usage.output,
-        cacheReadTokens: usage.cacheRead,
-        cacheWriteTokens: usage.cacheWrite,
-        cost: totalCost,
-      } as LocalUsageEvent;
+        model: modelToLog ?? 'unknown',
+        requests: 1,
+        promptTokens: usage.input ?? 0,
+        completionTokens: usage.output ?? 0,
+        reasoningTokens: 0,
+        cacheReadTokens: usage.cacheRead ?? 0,
+        cacheWriteTokens: usage.cacheWrite ?? 0,
+        cost: totalCost ?? 0,
+      };
 
       // Write to local JSONL - fail open (don't throw)
       writeLocalUsage(localEvent).catch(() => {});
@@ -181,18 +225,29 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  // Single entry point with subcommands: /openrouter [usage|account|session]
+  // ============== MODELS COMMANDS (subcommands of /openrouter) ==============
+
+  // Single entry point with subcommands: /openrouter [usage|account|session|models-sync|models-status]
   pi.registerCommand('openrouter', {
-    description: 'OpenRouter commands: usage, account, session',
+    description: 'OpenRouter commands: usage, account, session, models-sync, models-status',
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ['usage', 'account', 'session'];
+      const subcommands = ['usage', 'account', 'session', 'models-sync', 'models-status'];
       const items = subcommands
         .filter((s) => s.startsWith(prefix))
         .map((s) => ({ value: s, label: s }));
       return items.length > 0 ? items : null;
     },
     handler: async (args, ctx) => {
-      const subcommand = args.trim().split(/\s+/)[0] || '';
+      // Parse subcommand and flags
+      const parts = args.trim().split(/\s+/);
+      const subcommand = parts[0] || '';
+      const flags = parts.slice(1).reduce(
+        (acc, flag) => {
+          acc[flag] = true;
+          return acc;
+        },
+        {} as Record<string, boolean>,
+      );
 
       switch (subcommand) {
         case 'usage': {
@@ -208,8 +263,73 @@ export default function (pi: ExtensionAPI) {
           ctx.ui.notify(`OpenRouter session_id\n${getCurrentSessionId(ctx)}`, 'info');
           break;
         }
+        case 'models-sync': {
+          if (!isSyncEnabled()) {
+            ctx.ui.notify(
+              'OpenRouter model sync is disabled. Set openrouterModelSync: true in ~/.pi/agent/settings.json to enable.',
+              'error',
+            );
+            return;
+          }
+          const result = await syncModels(ctx);
+
+          // Display brief result using same color scheme as overlays
+          if (!result.success) {
+            let message = '';
+            if (result.source === 'cache') {
+              message = `OpenRouter models sync failed\n${result.registeredCount} registered from cache\nCache age: ${formatDuration(result.cacheAgeMs)}\nError: ${result.error}`;
+            } else {
+              message = `OpenRouter models unavailable\n0 registered\nError: ${result.error}`;
+            }
+            ctx.ui.notify(message, result.source === 'cache' ? 'warning' : 'error');
+          } else {
+            const message = `OpenRouter models synced\n${result.registeredCount} registered${result.skippedCount > 0 ? ` · ${result.skippedCount} skipped` : ''} · cache updated`;
+            ctx.ui.notify(message, 'info');
+          }
+          break;
+        }
+        case 'models-status': {
+          const state = getSyncState();
+          const skipReasons = await getSkipReasonsAsync();
+          const groupedReasons = groupSkipReasons(skipReasons);
+
+          // Get real-time cache age from disk
+          const cache = await loadCache();
+          const cacheAgeMs = cache ? getCacheAgeMs(cache) : null;
+
+          if (!state && !cache) {
+            ctx.ui.notify('OpenRouter models: not synced', 'error');
+          } else if (!state && cache) {
+            // Cache exists but no in-memory state (new Pi session)
+            const cachedCount = cache.models.length;
+            const message = `OpenRouter models cached\n${cachedCount} models in cache · age: ${formatDuration(cacheAgeMs)}\nRun '/openrouter models-sync' to register models`;
+            ctx.ui.notify(message, 'info');
+          } else if (state?.success) {
+            const skipCount = skipReasons.length;
+            let message = `OpenRouter models healthy\n${state.registeredCount} registered${skipCount > 0 ? ` · ${skipCount} skipped` : ''} · cache age: ${formatDuration(cacheAgeMs)}`;
+
+            if (flags['--skipped']) {
+              message += formatSkippedDetails(skipCount, groupedReasons, skipReasons);
+            }
+            ctx.ui.notify(message, 'info');
+          } else if (state?.source === 'cache') {
+            const skipCount = skipReasons.length;
+            let message = `OpenRouter models cached\n${state.registeredCount} registered${skipCount > 0 ? ` · ${skipCount} skipped` : ''}\nCache age: ${formatDuration(cacheAgeMs)}\nError: ${state.error}`;
+
+            if (flags['--skipped']) {
+              message += formatSkippedDetails(skipCount, groupedReasons, skipReasons);
+            }
+            ctx.ui.notify(message, 'warning');
+          } else {
+            ctx.ui.notify(
+              `OpenRouter models broken\n0 registered\nError: ${state?.error}`,
+              'error',
+            );
+          }
+          break;
+        }
         default: {
-          const available = ['usage', 'account', 'session'];
+          const available = ['usage', 'account', 'session', 'models-sync', 'models-status'];
           const message =
             available.length > 0
               ? `Available subcommands: ${available.join(', ')}${available.length > 1 ? '' : ''}`
@@ -352,7 +472,7 @@ async function showUsageOverlay(ctx: ExtensionContext, _subcommand?: string) {
   const cachedSummary = usageCache.get('usage');
   const lastFetchTimestamp = usageCache.getTimestamp('usage');
   const cachedMinutesAgo = lastFetchTimestamp
-    ? Math.round((Date.now() - lastFetchTimestamp) / 60000)
+    ? Math.round((Date.now() - lastFetchTimestamp) / MS_PER_MINUTE)
     : null;
 
   if (cachedSummary) {

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

@@ -0,0 +1,140 @@
+import { describe, it, expect, beforeEach, afterEach } 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 { createMockCache } from '../../__tests__/fixtures.js';
+
+// Each test gets its own isolated temp directory
+let testCacheDir: string;
+
+async function setupTestCache(): Promise<void> {
+  // Create isolated temp directory for this test
+  testCacheDir = join(tmpdir(), `pi-openrouter-test-${randomUUID()}`);
+  await mkdir(testCacheDir, { recursive: true });
+  // Tell the cache module to use our test directory
+  setCacheDir(testCacheDir);
+}
+
+async function cleanupTestCache(): Promise<void> {
+  // Reset cache dir to default (null means use default)
+  setCacheDir(null);
+  // Clean up temp directory
+  try {
+    await rm(testCacheDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+}
+
+describe('loadCache', () => {
+  beforeEach(setupTestCache);
+  afterEach(cleanupTestCache);
+
+  it('should return null when cache file does not exist', async () => {
+    const result = await loadCache();
+    expect(result).toBeNull();
+  });
+
+  it('should return parsed cache when file exists and is valid', async () => {
+    const mockCache = createMockCache({ timestamp: 1234567890 });
+    await saveCache(mockCache);
+
+    const result = await loadCache();
+    expect(result).not.toBeNull();
+    expect(result!.timestamp).toBe(1234567890);
+    expect(result!.models).toHaveLength(1);
+    expect(result!.models[0]!.id).toBe('test/model');
+  });
+
+  it('should return null when cache file contains invalid JSON', async () => {
+    await mkdir(testCacheDir, { recursive: true });
+    const cacheFile = join(testCacheDir, 'models-cache.json');
+    await writeFile(cacheFile, 'not valid json');
+
+    const result = await loadCache();
+    expect(result).toBeNull();
+  });
+
+  it('should return null when cache structure is invalid', async () => {
+    await mkdir(testCacheDir, { recursive: true });
+    const cacheFile = join(testCacheDir, 'models-cache.json');
+    await writeFile(cacheFile, JSON.stringify({ timestamp: 1234 })); // missing models
+
+    const result = await loadCache();
+    expect(result).toBeNull();
+  });
+});
+
+describe('saveCache', () => {
+  beforeEach(setupTestCache);
+  afterEach(cleanupTestCache);
+
+  it('should create cache file with valid JSON', async () => {
+    const mockCache = createMockCache();
+
+    await saveCache(mockCache);
+
+    // Verify it can be loaded back
+    const loaded = await loadCache();
+    expect(loaded).not.toBeNull();
+    expect(loaded!.timestamp).toBe(mockCache.timestamp);
+    expect(loaded!.models).toEqual(mockCache.models);
+  });
+
+  it('should overwrite existing cache file', async () => {
+    const firstCache = createMockCache({ timestamp: 1000 });
+    const secondCache = createMockCache({ timestamp: 2000 });
+
+    await saveCache(firstCache);
+    await saveCache(secondCache);
+
+    const loaded = await loadCache();
+    expect(loaded!.timestamp).toBe(2000);
+  });
+});
+
+describe('getCacheAgeMs', () => {
+  it('should calculate age correctly for recent cache', () => {
+    const cache = createMockCache({ timestamp: Date.now() - 60000 }); // 1 minute ago
+    const age = getCacheAgeMs(cache);
+
+    // Allow 100ms tolerance for test execution time
+    expect(age).toBeGreaterThanOrEqual(60000);
+    expect(age).toBeLessThan(61000);
+  });
+
+  it('should return 0 for cache with current timestamp', () => {
+    const cache = createMockCache({ timestamp: Date.now() });
+    const age = getCacheAgeMs(cache);
+    expect(age).toBeGreaterThanOrEqual(0);
+    expect(age).toBeLessThan(100);
+  });
+});
+
+describe('formatCacheAge', () => {
+  it('should return null for null cache', () => {
+    expect(formatCacheAge(null)).toBeNull();
+  });
+
+  it('should format minutes when less than 1 hour', () => {
+    const cache = createMockCache({ timestamp: Date.now() - 4 * 60000 }); // 4 minutes
+    expect(formatCacheAge(cache)).toBe('4m');
+  });
+
+  it('should format hours when between 1 hour and 1 day', () => {
+    const cache = createMockCache({ timestamp: Date.now() - 2 * 60 * 60000 }); // 2 hours
+    expect(formatCacheAge(cache)).toBe('2h');
+  });
+
+  it('should format days when over 1 day', () => {
+    const cache = createMockCache({ timestamp: Date.now() - 25 * 60 * 60000 }); // 25 hours
+    expect(formatCacheAge(cache)).toBe('1d');
+  });
+
+  it('should handle exact hour boundaries', () => {
+    const cache = createMockCache({ timestamp: Date.now() - 60 * 60000 }); // exactly 1 hour
+    expect(formatCacheAge(cache)).toBe('1h');
+  });
+});

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

@@ -0,0 +1,221 @@
+import { describe, it, expect } from 'vitest';
+import { mapOpenRouterModel, mapOpenRouterModels } from '../mapper.js';
+import { createValidModel } from '../../__tests__/fixtures.js';
+import type { OpenRouterModel, MapResult } from '../types.js';
+
+describe('mapOpenRouterModel', () => {
+  it('should map a valid model correctly', () => {
+    const model = createValidModel();
+    const result = mapOpenRouterModel(model);
+
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe('test/model');
+    expect(result!.name).toBe('Test Model');
+    expect(result!.contextWindow).toBe(128000);
+    expect(result!.maxTokens).toBe(4096); // default
+    expect(result!.cost.input).toBe(0.5); // 0.0000005 * 1M
+    expect(result!.cost.output).toBe(1.5); // 0.0000015 * 1M
+  });
+
+  it('should use name fallback to id when name missing', () => {
+    const model = createValidModel();
+    // @ts-expect-error: intentionally setting name to undefined for test
+    model.name = undefined;
+    const result = mapOpenRouterModel(model);
+
+    expect(result!.name).toBe('test/model');
+  });
+
+  describe('skip conditions', () => {
+    const skipCases: Array<{
+      name: string;
+      overrides: Partial<OpenRouterModel> | ((m: OpenRouterModel) => void);
+    }> = [
+      { name: 'empty id', overrides: { id: '' } },
+      { name: 'undefined id (deleted property)', overrides: (m) => delete (m as any).id },
+      { name: 'missing pricing.prompt', overrides: { pricing: { completion: '0.000001' } as any } },
+      { name: 'missing pricing.completion', overrides: { pricing: { prompt: '0.000001' } as any } },
+      {
+        name: 'missing context_length and top_provider',
+        overrides: { context_length: 0, top_provider: { context_length: 0 } },
+      },
+      {
+        name: 'non-text output modalities',
+        overrides: { architecture: { output_modalities: ['image', 'audio'] } as any },
+      },
+    ];
+
+    skipCases.forEach(({ name, overrides }) => {
+      it(`should skip model with ${name}`, () => {
+        const model = createValidModel();
+        if (typeof overrides === 'function') {
+          overrides(model);
+        } else {
+          Object.assign(model, overrides);
+        }
+        expect(mapOpenRouterModel(model)).toBeNull();
+      });
+    });
+  });
+
+  describe('reasoning detection', () => {
+    it("should detect reasoning from 'reasoning' parameter", () => {
+      const model = createValidModel({
+        supported_parameters: ['temperature', 'reasoning', 'max_tokens'],
+      });
+      expect(mapOpenRouterModel(model)!.reasoning).toBe(true);
+    });
+
+    it("should detect reasoning from 'include_reasoning' parameter", () => {
+      const model = createValidModel({
+        supported_parameters: ['include_reasoning'],
+      });
+      expect(mapOpenRouterModel(model)!.reasoning).toBe(true);
+    });
+
+    it('should not detect reasoning when neither parameter present', () => {
+      const model = createValidModel({
+        supported_parameters: ['temperature', 'max_tokens'],
+      });
+      expect(mapOpenRouterModel(model)!.reasoning).toBe(false);
+    });
+
+    it('should handle missing supported_parameters', () => {
+      const model = createValidModel({ supported_parameters: [] as any });
+      expect(mapOpenRouterModel(model)!.reasoning).toBe(false);
+    });
+  });
+
+  describe('input modality detection', () => {
+    it('should detect image support from input_modalities', () => {
+      const model = createValidModel({
+        architecture: { input_modalities: ['text', 'image'] } as any,
+      });
+      expect(mapOpenRouterModel(model)!.input).toEqual(['text', 'image']);
+    });
+
+    it('should default to text-only without image in modalities', () => {
+      const model = createValidModel({
+        architecture: { input_modalities: ['text'] } as any,
+      });
+      expect(mapOpenRouterModel(model)!.input).toEqual(['text']);
+    });
+
+    it('should default to text-only when architecture missing', () => {
+      const model = createValidModel({ architecture: null as any });
+      expect(mapOpenRouterModel(model)!.input).toEqual(['text']);
+    });
+  });
+
+  describe('cost calculation', () => {
+    it('should convert per-token to per-1M-tokens', () => {
+      const model = createValidModel({
+        pricing: { prompt: '0.000002', completion: '0.000006' },
+      });
+      const result = mapOpenRouterModel(model);
+      expect(result!.cost.input).toBe(2.0); // 0.000002 * 1,000,000
+      expect(result!.cost.output).toBe(6.0); // 0.000006 * 1,000,000
+    });
+
+    it('should handle cache pricing when present', () => {
+      const model = createValidModel({
+        pricing: {
+          prompt: '0.000001',
+          completion: '0.000003',
+          input_cache_read: '0.0000005',
+          input_cache_write: '0.000001',
+        },
+      });
+      const result = mapOpenRouterModel(model);
+      expect(result!.cost.cacheRead).toBe(0.5);
+      expect(result!.cost.cacheWrite).toBe(1.0);
+    });
+
+    it('should default cache pricing to 0 when missing', () => {
+      const model = createValidModel({
+        pricing: { prompt: '0.000001', completion: '0.000003' },
+      });
+      const result = mapOpenRouterModel(model);
+      expect(result!.cost.cacheRead).toBe(0);
+      expect(result!.cost.cacheWrite).toBe(0);
+    });
+  });
+
+  describe('contextWindow fallback', () => {
+    it('should prefer top_provider.context_length', () => {
+      const model = createValidModel({
+        context_length: 8000,
+        top_provider: { context_length: 128000 },
+      });
+      expect(mapOpenRouterModel(model)!.contextWindow).toBe(128000);
+    });
+
+    it('should fall back to context_length', () => {
+      const model = createValidModel({
+        context_length: 32000,
+        top_provider: null as any,
+      });
+      expect(mapOpenRouterModel(model)!.contextWindow).toBe(32000);
+    });
+  });
+
+  describe('maxTokens fallback', () => {
+    it('should prefer top_provider.max_completion_tokens', () => {
+      const model = createValidModel({
+        top_provider: { max_completion_tokens: 8192 },
+        per_request_limits: { completion_tokens: 4096 },
+      });
+      expect(mapOpenRouterModel(model)!.maxTokens).toBe(8192);
+    });
+
+    it('should fall back to per_request_limits.completion_tokens', () => {
+      const model = createValidModel({
+        per_request_limits: { completion_tokens: 8192 },
+      });
+      expect(mapOpenRouterModel(model)!.maxTokens).toBe(8192);
+    });
+
+    it('should use default when neither present', () => {
+      const model = createValidModel();
+      expect(mapOpenRouterModel(model)!.maxTokens).toBe(4096);
+    });
+  });
+});
+
+describe('mapOpenRouterModels', () => {
+  it('should map multiple models and track skips', () => {
+    const models: OpenRouterModel[] = [
+      createValidModel({ id: 'model/valid-1', name: 'Valid 1' }),
+      createValidModel({ id: '', name: 'Invalid (no id)' }), // will skip
+      createValidModel({ id: 'model/valid-2', name: 'Valid 2' }),
+    ];
+
+    const result: MapResult = mapOpenRouterModels(models);
+
+    expect(result.configs).toHaveLength(2);
+    expect(result.skipped).toBe(1);
+    expect(result.configs[0]!.id).toBe('model/valid-1');
+    expect(result.configs[1]!.id).toBe('model/valid-2');
+  });
+
+  it('should handle empty array', () => {
+    const result = mapOpenRouterModels([] as OpenRouterModel[]);
+    expect(result.configs).toHaveLength(0);
+    expect(result.skipped).toBe(0);
+  });
+
+  it('should skip all invalid models', () => {
+    const models: OpenRouterModel[] = [
+      createValidModel({ id: '' }),
+      createValidModel({ pricing: { prompt: '0.000001' } as any }),
+      createValidModel({
+        context_length: 0,
+        top_provider: { context_length: 0 },
+      }),
+    ];
+
+    const result = mapOpenRouterModels(models);
+    expect(result.configs).toHaveLength(0);
+    expect(result.skipped).toBe(3);
+  });
+});