@robhowley/pi-openrouter 0.9.0 → 0.10.0

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

@@ -4,7 +4,9 @@
 
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { ExtensionContext, ModelRegistry } from '@mariozechner/pi-coding-agent';
-import type { SyncResult } from '../types.js';
+import type { PiModelConfig, SyncResult } from '../types.js';
+import { ROUTER_ALIASES } from '../types.js';
+import { createPiModelConfig, createValidModel } from '../../__tests__/fixtures.js';
 
 // Import modules
 import {
@@ -13,9 +15,10 @@ import {
   getSyncState,
   getStatusText,
   areModelsAvailable,
+  includeBuiltinRouterModels,
 } from '../sync.js';
 import { fetchUserModels, AuthError } from '../../client.js';
-import { loadCache } from '../cache.js';
+import { loadCache, saveCache } from '../cache.js';
 
 // Mock the client module to control API behavior
 vi.mock('../../client.js', () => ({
@@ -133,8 +136,13 @@ describe('syncModels', () => {
   it('should return failure when API key is missing and no cache', async () => {
     // Ensure API key is not set
     delete process.env['OPENROUTER_API_KEY'];
+    delete process.env['OPENROUTER_MANAGEMENT_KEY'];
     // Mock fetchUserModels to throw AuthError
-    vi.mocked(fetchUserModels).mockRejectedValueOnce(new AuthError('OPENROUTER_API_KEY not set'));
+    vi.mocked(fetchUserModels).mockRejectedValueOnce(
+      new AuthError(
+        'OpenRouter API key not configured. Set OPENROUTER_API_KEY or OPENROUTER_MANAGEMENT_KEY.',
+      ),
+    );
     // Mock loadCache to return null (no cache available)
     vi.mocked(loadCache).mockResolvedValueOnce(null);
 
@@ -143,7 +151,7 @@ describe('syncModels', () => {
     expect(result.success).toBe(false);
     expect(result.registeredCount).toBe(0);
     expect(result.source).toBe('none');
-    expect(result.error).toContain('OPENROUTER_API_KEY not set');
+    expect(result.error).toContain('OpenRouter API key not configured');
   });
 
   it('should sync models from API and register with provider', async () => {
@@ -182,6 +190,150 @@ describe('syncModels', () => {
     expect(result.registeredCount).toBeGreaterThan(0);
     expect(mockRegisterProvider).toHaveBeenCalled();
   });
+
+  it('should register the API user catalog plus router aliases exactly once', async () => {
+    const mockModel = {
+      id: 'user/model-a',
+      name: 'User Model A',
+      architecture: {
+        inputModalities: ['text'],
+        outputModalities: ['text'],
+      },
+      contextLength: 128000,
+      pricing: {
+        prompt: 0.000001,
+        completion: 0.000002,
+      },
+      supportedParameters: [],
+      topProvider: {
+        contextLength: 128000,
+        maxCompletionTokens: 4096,
+      },
+    };
+
+    vi.mocked(fetchUserModels).mockResolvedValueOnce({
+      data: [mockModel],
+    } as any);
+
+    const result = await syncModels(mockCtx);
+    const providerConfig = mockRegisterProvider.mock.calls[0]![1] as { models: PiModelConfig[] };
+    const registeredIds = providerConfig.models.map((model) => model.id);
+
+    expect(result.registeredCount).toBe(1 + ROUTER_ALIASES.length);
+    expect(registeredIds).toEqual(['user/model-a', ...ROUTER_ALIASES]);
+    expect(registeredIds).not.toContain('anthropic/claude-3-opus');
+  });
+
+  it('should register cached user models plus router aliases on API failure', async () => {
+    vi.mocked(fetchUserModels).mockRejectedValueOnce(new Error('api down'));
+    vi.mocked(loadCache).mockResolvedValueOnce({
+      models: [createValidModel({ id: 'cached/model-a', name: 'Cached Model A' })],
+      skippedDetails: [
+        {
+          id: 'bad/model',
+          reason: 'missing context window',
+          hint: "Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.",
+        },
+      ],
+      timestamp: Date.now() - 60000,
+    });
+
+    const result = await syncModels(mockCtx);
+    const providerConfig = mockRegisterProvider.mock.calls[0]![1] as { models: PiModelConfig[] };
+    const registeredIds = providerConfig.models.map((model) => model.id);
+
+    expect(result.source).toBe('cache');
+    expect(result.registeredCount).toBe(1 + ROUTER_ALIASES.length);
+    expect(registeredIds).toEqual(['cached/model-a', ...ROUTER_ALIASES]);
+    expect(result.skippedDetails).toEqual([
+      {
+        id: 'bad/model',
+        reason: 'missing context window',
+        hint: "Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.",
+      },
+    ]);
+  });
+
+  it('should persist skipped reason hints in the saved cache', async () => {
+    vi.mocked(fetchUserModels).mockResolvedValueOnce({
+      data: [
+        {
+          id: 'user/model-a',
+          name: 'User Model A',
+          architecture: {
+            inputModalities: ['text'],
+            outputModalities: ['text'],
+          },
+          contextLength: 128000,
+          pricing: {
+            prompt: 0.000001,
+            completion: 0.000002,
+          },
+          supportedParameters: [],
+          topProvider: {
+            contextLength: 128000,
+            maxCompletionTokens: 4096,
+          },
+        },
+        {
+          id: 'bad/model',
+          name: 'Bad Model',
+          architecture: {
+            inputModalities: ['text'],
+            outputModalities: ['text'],
+          },
+          contextLength: 0,
+          pricing: {
+            prompt: 0.000001,
+            completion: 0.000002,
+          },
+          supportedParameters: [],
+          topProvider: {
+            contextLength: 0,
+            maxCompletionTokens: 4096,
+          },
+        },
+      ],
+    } as any);
+
+    const result = await syncModels(mockCtx);
+
+    expect(result.skippedDetails).toEqual([
+      {
+        id: 'bad/model',
+        reason: 'missing context window',
+        hint: expect.stringContaining(
+          '/openrouter model-override-set <model-id> contextWindow=<tokens>',
+        ),
+      },
+    ]);
+    expect(vi.mocked(saveCache)).toHaveBeenCalledWith(
+      expect.objectContaining({
+        skippedDetails: [
+          {
+            id: 'bad/model',
+            reason: 'missing context window',
+            hint: expect.stringContaining(
+              '/openrouter model-override-set <model-id> contextWindow=<tokens>',
+            ),
+          },
+        ],
+      }),
+    );
+  });
+
+  it('should include router aliases at most once', () => {
+    const configs = includeBuiltinRouterModels([
+      createPiModelConfig({ id: 'user/model-a' }),
+      createPiModelConfig({ id: ROUTER_ALIASES[0]! }),
+    ]);
+    const registeredIds = configs.map((model) => model.id);
+
+    expect(registeredIds).toEqual(['user/model-a', ...ROUTER_ALIASES]);
+    for (const routerId of ROUTER_ALIASES) {
+      expect(registeredIds.filter((id) => id === routerId)).toHaveLength(1);
+    }
+  });
 });
 
 describe('syncState management', () => {

package/extensions/openrouter/models/cache.ts

@@ -6,6 +6,7 @@ import { MS_PER_MINUTE } from './types.js';
 
 const CACHE_FILENAME = 'models-cache.json';
 const DEFAULT_CACHE_DIR = join(homedir(), '.pi', 'openrouter');
+const MAX_FUTURE_SKEW_MS = 5 * MS_PER_MINUTE;
 
 // Allow overriding cache directory for testing
 let cacheDirOverride: string | null = null;
@@ -40,6 +41,21 @@ async function ensureCacheDir(): Promise<void> {
   await mkdir(getCacheDir(), { recursive: true });
 }
 
+/**
+ * Returns true when a cache timestamp is structurally valid and not too far in the future.
+ */
+function isValidCacheTimestamp(timestamp: number, now = Date.now()): boolean {
+  return Number.isFinite(timestamp) && timestamp <= now + MAX_FUTURE_SKEW_MS;
+}
+
+/**
+ * Clamp future timestamps when saving so new cache writes never persist negative ages.
+ */
+function normalizeTimestampForSave(timestamp: number, now = Date.now()): number {
+  if (!isValidCacheTimestamp(timestamp, now)) return now;
+  return Math.min(timestamp, now);
+}
+
 /**
  * Load cached models from disk.
  * Returns null if cache doesn't exist or is corrupted.
@@ -55,6 +71,10 @@ export async function loadCache(): Promise<ModelsCache | null> {
       return null;
     }
 
+    if (!isValidCacheTimestamp(parsed.timestamp)) {
+      return null;
+    }
+
     return parsed;
   } catch {
     // File doesn't exist, permission error, or invalid JSON
@@ -68,14 +88,18 @@ export async function loadCache(): Promise<ModelsCache | null> {
 export async function saveCache(cache: ModelsCache): Promise<void> {
   await ensureCacheDir();
   const cachePath = getCachePath();
-  await writeFile(cachePath, JSON.stringify(cache, null, 2));
+  const normalizedCache: ModelsCache = {
+    ...cache,
+    timestamp: normalizeTimestampForSave(cache.timestamp),
+  };
+  await writeFile(cachePath, JSON.stringify(normalizedCache, null, 2));
 }
 
 /**
  * Get the age of the cache in milliseconds.
  */
 export function getCacheAgeMs(cache: ModelsCache): number {
-  return Date.now() - cache.timestamp;
+  return Math.max(0, Date.now() - cache.timestamp);
 }
 
 /**
@@ -84,6 +108,7 @@ export function getCacheAgeMs(cache: ModelsCache): number {
  */
 export function formatDuration(ms: number | null): string {
   if (ms === null) return 'unknown';
+  if (ms <= 0) return '<1m';
 
   const minutes = Math.floor(ms / MS_PER_MINUTE);
   if (minutes < 1) return '<1m';

package/extensions/openrouter/models/mapper.ts

@@ -1,7 +1,9 @@
 import type { OpenRouterModel, PiModelConfig, SkipReason, MapResult } from './types.js';
 import { ROUTER_ALIASES } from './types.js';
+import { getSkipReasonHint } from './skip-hints.js';
 import type { Model as SDKModel } from '@openrouter/sdk/models/index.js';
 import { loadModelOverrides, getModelOverride } from './overrides.js';
+import { normalizeOpenRouterModel } from '../normalizers.js';
 
 // Cache for built-in OpenRouter models from pi-ai
 // Populated lazily on first access
@@ -57,68 +59,24 @@ const COST_PER_MILLION = 1_000_000;
 const DEFAULT_MAX_TOKENS = 4096;
 
 /**
- * Convert SDK Model to our OpenRouterModel type for compatibility.
- * Handles SDK's camelCase naming convention.
+ * Validation result for a model check.
  */
-export function sdkModelToOpenRouterModel(model: SDKModel): OpenRouterModel {
-  const topProvider = model.topProvider
-    ? {
-        context_length: model.topProvider.contextLength ?? 0,
-        max_completion_tokens: model.topProvider.maxCompletionTokens ?? 0,
-      }
-    : undefined;
-
-  const perRequestLimits = model.perRequestLimits
-    ? {
-        completion_tokens: model.perRequestLimits.completionTokens ?? 0,
-      }
-    : undefined;
-
-  // Build the object conditionally to avoid undefined property issues
-  const result: OpenRouterModel = {
-    id: model.id,
-    name: model.name,
-    architecture: {
-      input_modalities: model.architecture.inputModalities ?? [],
-      output_modalities: model.architecture.outputModalities ?? [],
-    },
-    context_length: model.contextLength ?? 0,
-    pricing: {
-      prompt: String(model.pricing.prompt ?? 0),
-      completion: String(model.pricing.completion ?? 0),
-      input_cache_read: String(model.pricing.inputCacheRead ?? 0),
-      input_cache_write: String(model.pricing.inputCacheWrite ?? 0),
-    },
-    supported_parameters: model.supportedParameters,
-  };
+type PricedOpenRouterModel = OpenRouterModel & {
+  pricing: NonNullable<OpenRouterModel['pricing']>;
+};
 
-  // Conditionally add optional properties to avoid explicit undefined
-  if (topProvider) {
-    result.top_provider = topProvider;
-  }
-  if (perRequestLimits) {
-    result.per_request_limits = perRequestLimits;
-  }
-
-  return result;
-}
+type ValidationResult =
+  | { valid: true; model: PricedOpenRouterModel; contextWindow: number }
+  | { valid: false; reason: string; modelId: string; hint?: string };
 
 /**
- * Normalize input model to OpenRouterModel format.
+ * Build a failed validation result with a stable machine reason and optional hint.
  */
-function normalizeModel(model: OpenRouterModel | SDKModel): OpenRouterModel {
-  return 'contextLength' in model
-    ? sdkModelToOpenRouterModel(model as SDKModel)
-    : (model as OpenRouterModel);
+function invalidModel(reason: string, modelId: string): ValidationResult {
+  const hint = getSkipReasonHint(reason);
+  return hint ? { valid: false, reason, modelId, hint } : { valid: false, reason, modelId };
 }
 
-/**
- * Validation result for a model check.
- */
-type ValidationResult =
-  | { valid: true; model: OpenRouterModel; contextWindow: number }
-  | { valid: false; reason: string; modelId: string };
-
 /**
  * Validate a model and return either a valid result with extracted context window
  * or a failure reason.
@@ -126,30 +84,31 @@ type ValidationResult =
 function validateModel(model: OpenRouterModel): ValidationResult {
   // Check: missing required id
   if (!model.id) {
-    return { valid: false, reason: 'missing id', modelId: 'unknown' };
+    return invalidModel('missing id', 'unknown');
   }
 
   // Check: missing required pricing fields
-  if (!model.pricing?.prompt) {
-    return { valid: false, reason: 'missing prompt pricing', modelId: model.id };
+  const pricing = model.pricing;
+  if (!pricing?.prompt) {
+    return invalidModel('missing prompt pricing', model.id);
   }
-  if (!model.pricing?.completion) {
-    return { valid: false, reason: 'missing completion pricing', modelId: model.id };
+  if (!pricing.completion) {
+    return invalidModel('missing completion pricing', model.id);
   }
 
   // Check: missing context window (both primary and fallback)
   const contextWindow = model.top_provider?.context_length ?? model.context_length;
   if (!contextWindow) {
-    return { valid: false, reason: 'missing context window', modelId: model.id };
+    return invalidModel('missing context window', model.id);
   }
 
   // Check: explicitly non-text output (if specified)
   const outputModalities = model.architecture?.output_modalities;
   if (outputModalities && !outputModalities.includes('text')) {
-    return { valid: false, reason: 'non-text output modalities', modelId: model.id };
+    return invalidModel('non-text output modalities', model.id);
   }
 
-  return { valid: true, model, contextWindow };
+  return { valid: true, model: { ...model, pricing }, contextWindow };
 }
 
 /**
@@ -158,7 +117,7 @@ function validateModel(model: OpenRouterModel): ValidationResult {
  * Priority: user overrides > built-in registry > API data
  */
 async function buildPiConfig(
-  model: OpenRouterModel,
+  model: PricedOpenRouterModel,
   contextWindow: number,
   userOverrides?: Awaited<ReturnType<typeof loadModelOverrides>>,
 ): Promise<PiModelConfig> {
@@ -227,7 +186,7 @@ export async function mapOpenRouterModels(
   const skippedDetails: SkipReason[] = [];
 
   for (const rawModel of models) {
-    const model = normalizeModel(rawModel);
+    const model = normalizeOpenRouterModel(rawModel);
 
     // Skip router aliases - they're added manually after mapping
     if (ROUTER_ALIASES.includes(model.id)) {
@@ -238,11 +197,18 @@ export async function mapOpenRouterModels(
 
     if (!validation.valid) {
       skipped++;
-      skippedDetails.push({ id: validation.modelId, reason: validation.reason });
+      const skippedDetail: SkipReason = {
+        id: validation.modelId,
+        reason: validation.reason,
+      };
+      if (validation.hint) {
+        skippedDetail.hint = validation.hint;
+      }
+      skippedDetails.push(skippedDetail);
       continue;
     }
 
-    configs.push(await buildPiConfig(model, validation.contextWindow, userOverrides));
+    configs.push(await buildPiConfig(validation.model, validation.contextWindow, userOverrides));
   }
 
   return { configs, skipped, skippedDetails };
@@ -259,7 +225,7 @@ export async function mapOpenRouterModel(
   await loadBuiltInOpenRouterModels();
   const userOverrides = await loadModelOverrides();
 
-  const normalized = normalizeModel(model);
+  const normalized = normalizeOpenRouterModel(model);
 
   // Router aliases are handled separately, skip them here
   if (ROUTER_ALIASES.includes(normalized.id)) {
@@ -272,5 +238,5 @@ export async function mapOpenRouterModel(
     return null;
   }
 
-  return buildPiConfig(normalized, validation.contextWindow, userOverrides);
+  return buildPiConfig(validation.model, validation.contextWindow, userOverrides);
 }