@robhowley/pi-openrouter 0.7.1 → 0.8.0

package/extensions/openrouter/client.ts

@@ -1,6 +1,8 @@
 import type { ActivityResponse } from '@openrouter/sdk/models/index.js';
 import type { GetCreditsResponse } from '@openrouter/sdk/models/operations/index.js';
 import { OpenRouter } from '@openrouter/sdk/sdk/sdk.js';
+import type { ModelsListResponse } from '@openrouter/sdk/models/index.js';
+import { UnauthorizedResponseError } from '@openrouter/sdk/models/errors/index.js';
 
 let client: OpenRouter | null = null;
 
@@ -34,23 +36,76 @@ export async function getActivity(): Promise<ActivityResponse['data'] | null> {
   }
 }
 
-interface SDKError {
-  status?: number;
-  message?: string;
+/**
+ * Fetch the authenticated user's model catalog from OpenRouter.
+ * Uses the SDK for consistent error handling and retry behavior.
+ */
+export async function fetchUserModels(): Promise<ModelsListResponse> {
+  const key = getApiKey();
+  if (!key) {
+    throw new AuthError('OPENROUTER_API_KEY not set');
+  }
+
+  try {
+    const sdkClient = new OpenRouter({ apiKey: key });
+    const response = await sdkClient.models.listForUser({ bearer: key }, {});
+    return response as ModelsListResponse;
+  } catch (err: unknown) {
+    throw mapSdkError(err);
+  }
+}
+
+/**
+ * Check if the OpenRouter API key is configured.
+ */
+export function isConfigured(): boolean {
+  return !!getApiKey();
 }
 
-function isSDKError(err: unknown): err is SDKError {
-  return err !== null && typeof err === 'object' && 'status' in err;
+/**
+ * Get the OpenRouter API key from environment.
+ */
+export function getApiKey(): string | undefined {
+  return process.env['OPENROUTER_API_KEY'];
 }
 
+/**
+ * Map SDK errors to our error types with proper status codes.
+ */
 function mapSdkError(err: unknown): Error {
-  if (isSDKError(err)) {
-    const status = err.status;
-    const message = err.message ?? 'Unknown error';
-    if (status === 401) return new AuthError(message);
-    return new ApiError(`${status}: ${message}`);
+  // Handle UnauthorizedResponseError (401)
+  if (err instanceof UnauthorizedResponseError) {
+    return new ApiError('Unauthorized: Invalid or expired API key', 401);
   }
-  if (err instanceof Error) return err;
+
+  // Handle other SDK errors with statusCode
+  if (err instanceof Error && 'statusCode' in err) {
+    const statusCode = (err as { statusCode: number }).statusCode;
+    if (statusCode === 401) {
+      return new AuthError(err.message || 'Unauthorized');
+    }
+    return new ApiError(err.message || 'API error', statusCode);
+  }
+
+  // Map error messages to appropriate status codes
+  if (err instanceof Error) {
+    const message = err.message.toLowerCase();
+    if (message.includes('unauthorized')) {
+      return new ApiError('Unauthorized: Invalid or expired API key', 401);
+    }
+    if (message.includes('rate limit') || message.includes('rate limited')) {
+      return new ApiError('Rate limited: Too many requests', 429);
+    }
+    if (
+      message.includes('server error') ||
+      message.includes('internal') ||
+      message.includes('service unavailable')
+    ) {
+      return new ApiError(err.message || 'Server error', 500);
+    }
+    return new ApiError(err.message || 'API error', 500);
+  }
+
   return new Error(String(err));
 }
 
@@ -62,7 +117,10 @@ export class AuthError extends Error {
 }
 
 export class ApiError extends Error {
-  constructor(message: string) {
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+  ) {
     super(message);
     this.name = 'ApiError';
   }

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
 // =============================================================================
@@ -187,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': {
@@ -214,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 ? '' : ''}`
@@ -358,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);
+  });
+});