@robhowley/pi-openrouter 0.7.1 → 0.8.1

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,51 @@ 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';
+import { mapOpenRouterModels } from './models/mapper.js';
+
 // Store the current session state for use in command handlers
 let currentSessionState: OpenRouterSessionState | null = null;
 let sessionTrackingInstalled = false;
 
+// Store startup cache state for notifications
+let startupCacheInfo: { count: number; age: string } | undefined;
+
+// =============================================================================
+// 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
 // =============================================================================
@@ -49,7 +91,36 @@ function getCurrentSessionId(ctx: { sessionManager: { getSessionId(): string } }
   }
 }
 
-export default function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI) {
+  // Eager cache load on extension startup (before any sessions)
+  startupCacheInfo = undefined;
+  let startupCacheWarning: string | undefined;
+  if (isSyncEnabled()) {
+    const cache = await loadCache().catch(() => null);
+
+    if (cache?.models.length) {
+      try {
+        const { configs } = mapOpenRouterModels(cache.models);
+
+        // Register models directly with Pi's OpenRouter provider
+        pi.registerProvider('openrouter', {
+          baseUrl: 'https://openrouter.ai/api/v1',
+          apiKey: 'OPENROUTER_API_KEY',
+          api: 'openai-completions',
+          models: configs,
+          authHeader: true,
+        });
+
+        // Store for session_start notification
+        const age = formatDuration(getCacheAgeMs(cache));
+        startupCacheInfo = { count: configs.length, age };
+      } catch (error) {
+        startupCacheInfo = undefined;
+        startupCacheWarning = `OpenRouter: cached models found but failed to register: ${error instanceof Error ? error.message : String(error)}`;
+      }
+    }
+  }
+
   // Install before_provider_request hook once
   if (!sessionTrackingInstalled) {
     sessionTrackingInstalled = true;
@@ -160,6 +231,27 @@ export default function (pi: ExtensionAPI) {
     stopBackgroundRefresh();
   });
 
+  // Notify on first session start after extension load
+  pi.on('session_start', (event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    // Show a persistent status indicator
+    if (startupCacheInfo) {
+      const statusText = `OpenRouter ${startupCacheInfo.count} models`;
+      ctx.ui.setStatus('openrouter', ctx.ui.theme.fg('dim', statusText));
+    }
+
+    // Show a one-time notification on startup
+    if (event.reason === 'startup' && startupCacheInfo) {
+      const notice = `OpenRouter: ${startupCacheInfo.count} models loaded from cache (${startupCacheInfo.age} old). Run /openrouter models-sync to refresh.`;
+      ctx.ui.notify(notice, 'info');
+    }
+
+    if (event.reason === 'startup' && startupCacheWarning) {
+      ctx.ui.notify(startupCacheWarning, 'warning');
+    }
+  });
+
   pi.registerCommand('openrouter-usage', {
     description: 'Show OpenRouter usage: caps, spend, burn rate, and model breakdowns',
     getArgumentCompletions: () => null,
@@ -187,18 +279,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 +317,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 +526,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');
+  });
+});