@robhowley/pi-openrouter 0.11.1 → 0.12.0

package/extensions/openrouter/models/cache.ts

@@ -1,7 +1,7 @@
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { homedir } from 'os';
-import type { ModelsCache } from './types.js';
+import type { CatalogMode, ModelsCache } from './types.js';
 import { MS_PER_MINUTE } from './types.js';
 
 const CACHE_FILENAME = 'models-cache.json';
@@ -48,6 +48,16 @@ function isValidCacheTimestamp(timestamp: number, now = Date.now()): boolean {
   return Number.isFinite(timestamp) && timestamp <= now + MAX_FUTURE_SKEW_MS;
 }
 
+/**
+ * Normalize persisted catalog mode.
+ * Missing mode means an older cache file and defaults to full catalog mode.
+ */
+function normalizeCatalogMode(mode: unknown): CatalogMode | null {
+  if (mode === undefined) return 'full';
+  if (mode === 'full' || mode === 'free-only') return mode;
+  return null;
+}
+
 /**
  * Clamp future timestamps when saving so new cache writes never persist negative ages.
  */
@@ -64,18 +74,29 @@ export async function loadCache(): Promise<ModelsCache | null> {
   try {
     const cachePath = getCachePath();
     const data = await readFile(cachePath, 'utf-8');
-    const parsed = JSON.parse(data) as ModelsCache;
+    const parsed = JSON.parse(data) as Partial<ModelsCache> & { catalogMode?: unknown };
 
-    // Validate structure
+    // Validate required structure
     if (!parsed.models || !Array.isArray(parsed.models) || typeof parsed.timestamp !== 'number') {
       return null;
     }
 
-    if (!isValidCacheTimestamp(parsed.timestamp)) {
+    const catalogMode = normalizeCatalogMode(parsed.catalogMode);
+    if (!catalogMode || !isValidCacheTimestamp(parsed.timestamp)) {
       return null;
     }
 
-    return parsed;
+    const normalizedCache: ModelsCache = {
+      catalogMode,
+      models: parsed.models,
+      timestamp: parsed.timestamp,
+    };
+
+    if (Array.isArray(parsed.skippedDetails)) {
+      normalizedCache.skippedDetails = parsed.skippedDetails;
+    }
+
+    return normalizedCache;
   } catch {
     // File doesn't exist, permission error, or invalid JSON
     return null;
@@ -90,6 +111,7 @@ export async function saveCache(cache: ModelsCache): Promise<void> {
   const cachePath = getCachePath();
   const normalizedCache: ModelsCache = {
     ...cache,
+    catalogMode: normalizeCatalogMode(cache.catalogMode) ?? 'full',
     timestamp: normalizeTimestampForSave(cache.timestamp),
   };
   await writeFile(cachePath, JSON.stringify(normalizedCache, null, 2));

package/extensions/openrouter/models/sync.ts

@@ -4,25 +4,30 @@
  */
 
 import { fetchUserModels } from '../client.js';
-import { mapOpenRouterModels } from './mapper.js';
 import { sdkModelToOpenRouterModel } from '../normalizers.js';
-import { loadCache, saveCache } from './cache.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 import type { ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { loadCache, saveCache } from './cache.js';
+import { mapOpenRouterModels } from './mapper.js';
+import { ROUTER_DEFINITIONS } from './types.js';
 import type {
-  SyncResult,
-  PiModelConfig,
+  ActiveCatalogState,
+  CatalogMode,
   ModelsCache,
   OpenRouterModel,
+  PiModelConfig,
   SkipReason,
+  SyncResult,
 } from './types.js';
-import { existsSync, readFileSync } from 'node:fs';
-import { ROUTER_DEFINITIONS } from './types.js';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
 
 // Store the current sync state for status display.
 let currentSyncState: SyncResult | null = null;
 
+// Store the catalog currently registered with Pi.
+let currentActiveCatalogState: ActiveCatalogState | null = null;
+
 /**
  * Check if model sync is enabled via user config.
  * Default is true (sync enabled) if config is not set.
@@ -50,7 +55,7 @@ export function isSyncEnabled(): boolean {
  * Set the current sync state.
  * Called after each sync operation.
  */
-export function setSyncState(result: SyncResult): void {
+export function setSyncState(result: SyncResult | null): void {
   currentSyncState = result;
 }
 
@@ -61,6 +66,20 @@ export function getSyncState(): SyncResult | null {
   return currentSyncState;
 }
 
+/**
+ * Set the currently active catalog state.
+ */
+export function setActiveCatalogState(state: ActiveCatalogState | null): void {
+  currentActiveCatalogState = state;
+}
+
+/**
+ * Get the currently active catalog state.
+ */
+export function getActiveCatalogState(): ActiveCatalogState | null {
+  return currentActiveCatalogState;
+}
+
 /**
  * Register mapped models with Pi's OpenRouter provider.
  *
@@ -80,50 +99,109 @@ export async function registerModelsWithProvider(
   });
 }
 
+function getBuiltinRouterDefinitionsForCatalogMode(mode: CatalogMode) {
+  return ROUTER_DEFINITIONS.filter((router) => mode === 'full' || router.id === 'openrouter/free');
+}
+
+/**
+ * Returns true when an OpenRouter model ID is an explicit free variant.
+ */
+export function isExplicitFreeModelId(id: string): boolean {
+  return id.endsWith(':free');
+}
+
+/**
+ * Filter raw models for the requested catalog mode before mapping/validation.
+ */
+export function filterModelsForCatalogMode<T extends { id?: string }>(
+  models: T[],
+  mode: CatalogMode,
+): T[] {
+  if (mode === 'full') {
+    return [...models];
+  }
+
+  return models.filter((model) => typeof model.id === 'string' && isExplicitFreeModelId(model.id));
+}
+
 /**
  * Built-in router models derived from ROUTER_DEFINITIONS in types.ts.
  * This ensures sync with mapper.ts skip logic.
  */
-
-const BUILTIN_ROUTER_MODELS: PiModelConfig[] = ROUTER_DEFINITIONS.map((r) => ({
-  id: r.id,
-  name: r.name,
-  reasoning: r.reasoning,
-  input: [...r.input],
-  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-  contextWindow: r.contextLength,
-  maxTokens: r.maxTokens,
-}));
+export function getBuiltinRoutersForCatalogMode(mode: CatalogMode): PiModelConfig[] {
+  return getBuiltinRouterDefinitionsForCatalogMode(mode).map((router) => ({
+    id: router.id,
+    name: router.name,
+    reasoning: router.reasoning,
+    input: [...router.input],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: router.contextLength,
+    maxTokens: router.maxTokens,
+  }));
+}
 
 /**
  * Add built-in router aliases exactly once to a synced user catalog.
- *
- * The OpenRouter provider registration replaces the built-in list, so router aliases are the
- * only built-ins we intentionally preserve in this cleanup pass.
  */
-export function includeBuiltinRouterModels(configs: PiModelConfig[]): PiModelConfig[] {
+export function includeBuiltinRouterModels(
+  configs: PiModelConfig[],
+  mode: CatalogMode = 'full',
+): PiModelConfig[] {
   const seen = new Set(configs.map((config) => config.id));
-  const routersToAdd = BUILTIN_ROUTER_MODELS.filter((router) => !seen.has(router.id));
+  const routersToAdd = getBuiltinRoutersForCatalogMode(mode).filter(
+    (router) => !seen.has(router.id),
+  );
   return [...configs, ...routersToAdd];
 }
 
 /**
  * Convert router definitions to OpenRouterModel format for cache storage.
  */
-function getRouterCacheModels(): OpenRouterModel[] {
-  return ROUTER_DEFINITIONS.map((r) => ({
-    id: r.id,
-    name: r.name,
+function getRouterCacheModels(mode: CatalogMode): OpenRouterModel[] {
+  return getBuiltinRouterDefinitionsForCatalogMode(mode).map((router) => ({
+    id: router.id,
+    name: router.name,
     architecture: {
-      input_modalities: [...r.input],
-      output_modalities: [...r.output],
+      input_modalities: [...router.input],
+      output_modalities: [...router.output],
     },
-    context_length: r.contextLength,
+    context_length: router.contextLength,
     pricing: { prompt: '0', completion: '0' },
-    supported_parameters: r.reasoning ? ['reasoning'] : [],
+    supported_parameters: router.reasoning ? ['reasoning'] : [],
   }));
 }
 
+function getEffectiveSkippedCount(skipped: number, skippedDetails: SkipReason[]): number {
+  return skippedDetails.length > 0 ? skippedDetails.length : skipped;
+}
+
+function buildActiveCatalogState(args: {
+  mode: CatalogMode;
+  registeredModelIds: string[];
+  registeredCount: number;
+  skippedCount: number;
+  skippedDetails: SkipReason[];
+  source: ActiveCatalogState['source'];
+  cacheAgeMs: number;
+}): ActiveCatalogState {
+  return {
+    mode: args.mode,
+    registeredModelIds: args.registeredModelIds,
+    registeredCount: args.registeredCount,
+    skippedCount: args.skippedCount,
+    skippedDetails: args.skippedDetails,
+    source: args.source,
+    cacheAgeMs: args.cacheAgeMs,
+  };
+}
+
+function sliceSkipReasons(reasons: SkipReason[], maxResults?: number): SkipReason[] {
+  if (maxResults === undefined) {
+    return reasons;
+  }
+  return reasons.slice(0, maxResults);
+}
+
 /**
  * Execute a full sync operation:
  * 1. Fetch models from OpenRouter API
@@ -134,42 +212,87 @@ function getRouterCacheModels(): OpenRouterModel[] {
  * On API failure, falls back to cached models if available.
  *
  * @param ctx - Extension context for provider registration
+ * @param requestedMode - full catalog or free-only catalog filter
  * @returns SyncResult with details of the operation
  */
-export async function syncModels(_ctx: ExtensionContext): Promise<SyncResult> {
+export async function syncModels(
+  ctx: ExtensionContext,
+  requestedMode: CatalogMode = 'full',
+): Promise<SyncResult> {
   // Note: Config check (isSyncEnabled) is now handled at the command level
   // in index.ts. This allows tests to run without file system dependencies.
 
   // Attempt 1: Fetch from API
   try {
     const response = await fetchUserModels();
-    const { configs, skipped, skippedDetails } = await mapOpenRouterModels(response.data);
+    const filteredApiModels = filterModelsForCatalogMode(response.data, requestedMode);
+
+    if (requestedMode === 'free-only' && filteredApiModels.length === 0) {
+      const activeState = getActiveCatalogState();
+      const result: SyncResult = {
+        success: false,
+        outcome: 'no-change',
+        requestedMode,
+        catalogMode: activeState?.mode ?? null,
+        registeredCount: 0,
+        skippedCount: 0,
+        skippedDetails: [],
+        source: 'api',
+        cacheUpdated: false,
+        cacheAgeMs: activeState?.cacheAgeMs ?? null,
+        error: null,
+      };
+
+      setSyncState(result);
+      return result;
+    }
+
+    const { configs, skipped, skippedDetails } = await mapOpenRouterModels(filteredApiModels);
 
     // Add built-in router aliases that don't appear in /models/user endpoint.
-    const configsWithRouters = includeBuiltinRouterModels(configs);
+    const configsWithRouters = includeBuiltinRouterModels(configs, requestedMode);
 
     // Register with Pi's OpenRouter provider
-    await registerModelsWithProvider(_ctx, configsWithRouters);
+    await registerModelsWithProvider(ctx, configsWithRouters);
 
-    // Convert SDK Model[] to OpenRouterModel[] for cache storage
-    const cacheModels: OpenRouterModel[] = response.data.map(sdkModelToOpenRouterModel);
+    // Convert SDK Model[] to OpenRouterModel[] for cache storage.
+    // Store mode-shaped raw models so free-only cache cannot resurrect paid variants.
+    const cacheModels: OpenRouterModel[] = filteredApiModels.map((model) =>
+      sdkModelToOpenRouterModel(model),
+    );
 
-    // Update last-good cache (include routers and skip details)
+    // Update last-good cache (include mode-shaped routers and skip details)
     const cache: ModelsCache = {
-      models: [...cacheModels, ...getRouterCacheModels()],
-      skippedDetails: skippedDetails,
+      catalogMode: requestedMode,
+      models: [...cacheModels, ...getRouterCacheModels(requestedMode)],
+      skippedDetails,
       timestamp: Date.now(),
     };
     await saveCache(cache);
 
+    const skippedCount = getEffectiveSkippedCount(skipped, skippedDetails);
+    const activeState = buildActiveCatalogState({
+      mode: requestedMode,
+      registeredModelIds: configsWithRouters.map((config) => config.id),
+      registeredCount: configsWithRouters.length,
+      skippedCount,
+      skippedDetails,
+      source: 'api',
+      cacheAgeMs: 0,
+    });
+    setActiveCatalogState(activeState);
+
     const result: SyncResult = {
       success: true,
+      outcome: 'synced',
+      requestedMode,
+      catalogMode: requestedMode,
       registeredCount: configsWithRouters.length,
-      skippedCount: skipped,
-      skippedDetails: skippedDetails,
+      skippedCount,
+      skippedDetails,
       source: 'api',
       cacheUpdated: true,
-      cacheAgeMs: 0, // Cache was just updated
+      cacheAgeMs: 0,
       error: null,
     };
 
@@ -178,26 +301,40 @@ export async function syncModels(_ctx: ExtensionContext): Promise<SyncResult> {
   } catch (error) {
     // API failed - try cache fallback
     const errorMsg = error instanceof Error ? error.message : String(error);
-
     const cache = await loadCache();
 
     if (cache) {
-      // Attempt 2: Use cached models
-      const { configs, skipped } = await mapOpenRouterModels(cache.models);
-      const configsWithRouters = includeBuiltinRouterModels(configs);
-
-      await registerModelsWithProvider(_ctx, configsWithRouters);
-
-      // Use cached skip details if available
-      const cachedSkipDetails = cache.skippedDetails || [];
+      // Attempt 2: Use cached models with the cache's persisted catalog mode.
+      const filteredCacheModels = filterModelsForCatalogMode(cache.models, cache.catalogMode);
+      const { configs, skipped, skippedDetails } = await mapOpenRouterModels(filteredCacheModels);
+      const configsWithRouters = includeBuiltinRouterModels(configs, cache.catalogMode);
+
+      await registerModelsWithProvider(ctx, configsWithRouters);
+
+      const cachedSkipDetails = cache.skippedDetails ?? skippedDetails;
+      const skippedCount = getEffectiveSkippedCount(skipped, cachedSkipDetails);
+      const cacheAgeMs = Math.max(0, Date.now() - cache.timestamp);
+      const activeState = buildActiveCatalogState({
+        mode: cache.catalogMode,
+        registeredModelIds: configsWithRouters.map((config) => config.id),
+        registeredCount: configsWithRouters.length,
+        skippedCount,
+        skippedDetails: cachedSkipDetails,
+        source: 'cache',
+        cacheAgeMs,
+      });
+      setActiveCatalogState(activeState);
 
       const result: SyncResult = {
         success: false,
+        outcome: 'cache-fallback',
+        requestedMode,
+        catalogMode: cache.catalogMode,
         registeredCount: configsWithRouters.length,
-        skippedCount: skipped,
+        skippedCount,
         source: 'cache',
         cacheUpdated: false,
-        cacheAgeMs: Date.now() - cache.timestamp,
+        cacheAgeMs,
         error: errorMsg,
         skippedDetails: cachedSkipDetails,
       };
@@ -206,14 +343,20 @@ export async function syncModels(_ctx: ExtensionContext): Promise<SyncResult> {
       return result;
     }
 
-    // Attempt 3: No cache available - complete failure
+    // Attempt 3: No cache available - complete failure.
+    // Preserve any previously active in-memory catalog.
+    const activeState = getActiveCatalogState();
     const result: SyncResult = {
       success: false,
+      outcome: 'unavailable',
+      requestedMode,
+      catalogMode: activeState?.mode ?? null,
       registeredCount: 0,
       skippedCount: 0,
+      skippedDetails: [],
       source: 'none',
       cacheUpdated: false,
-      cacheAgeMs: null,
+      cacheAgeMs: activeState?.cacheAgeMs ?? null,
       error: errorMsg,
     };
 
@@ -226,8 +369,14 @@ export async function syncModels(_ctx: ExtensionContext): Promise<SyncResult> {
  * Get a human-readable status string for the current sync state.
  */
 export function getStatusText(): string {
-  const state = getSyncState();
+  const activeState = getActiveCatalogState();
 
+  if (activeState) {
+    const status = activeState.source === 'cache' ? 'cached' : 'healthy';
+    return `OpenRouter models: ${status} (${activeState.registeredCount} registered)`;
+  }
+
+  const state = getSyncState();
   if (!state) {
     return 'OpenRouter models: not synced';
   }
@@ -247,12 +396,12 @@ export function getStatusText(): string {
 
 /**
  * Check if models are currently available (synced or cached).
- * Checks in-memory state first, then falls back to cache file on disk.
+ * Checks in-memory active state first, then falls back to cache file on disk.
  */
 export async function areModelsAvailable(): Promise<boolean> {
-  const state = getSyncState();
-  if (state) {
-    return state.registeredCount > 0 || state.source === 'cache';
+  const activeState = getActiveCatalogState();
+  if (activeState) {
+    return activeState.registeredCount > 0;
   }
 
   // Check cache file on disk
@@ -261,17 +410,19 @@ export async function areModelsAvailable(): Promise<boolean> {
 }
 
 /**
- * Get skip reasons from the current sync state or cache.
+ * Get skip reasons from the active catalog, last sync state, or cache.
  * Note: For models-status (synchronous), we can't await here.
  * For async usage, use getSkipReasonsAsync instead.
  */
-export function getSkipReasons(maxResults: number = 10): SkipReason[] {
-  const state = getSyncState();
-  if (!state) return [];
+export function getSkipReasons(maxResults?: number): SkipReason[] {
+  const activeState = getActiveCatalogState();
+  if (activeState?.skippedDetails.length) {
+    return sliceSkipReasons(activeState.skippedDetails, maxResults);
+  }
 
-  // Prefer in-memory state
-  if (state.skippedDetails && state.skippedDetails.length > 0) {
-    return state.skippedDetails.slice(0, maxResults);
+  const state = getSyncState();
+  if (state?.skippedDetails?.length) {
+    return sliceSkipReasons(state.skippedDetails, maxResults);
   }
 
   return [];
@@ -280,18 +431,20 @@ export function getSkipReasons(maxResults: number = 10): SkipReason[] {
 /**
  * Async version of getSkipReasons that reads from cache if needed.
  */
-export async function getSkipReasonsAsync(maxResults: number = 10): Promise<SkipReason[]> {
-  const state = getSyncState();
+export async function getSkipReasonsAsync(maxResults?: number): Promise<SkipReason[]> {
+  const activeState = getActiveCatalogState();
+  if (activeState?.skippedDetails.length) {
+    return sliceSkipReasons(activeState.skippedDetails, maxResults);
+  }
 
-  // First check in-memory state
-  if (state?.skippedDetails && state.skippedDetails.length > 0) {
-    return state.skippedDetails.slice(0, maxResults);
+  const state = getSyncState();
+  if (state?.skippedDetails?.length) {
+    return sliceSkipReasons(state.skippedDetails, maxResults);
   }
 
-  // Fall back to cache if not available in state
   const cache = await loadCache();
-  if (cache?.skippedDetails && cache.skippedDetails.length > 0) {
-    return cache.skippedDetails.slice(0, maxResults);
+  if (cache?.skippedDetails?.length) {
+    return sliceSkipReasons(cache.skippedDetails, maxResults);
   }
 
   return [];

package/extensions/openrouter/models/types.ts

@@ -66,23 +66,56 @@ export interface PiModelConfig {
 }
 
 /**
- * Result of a sync operation
+ * Registered catalog mode.
+ */
+export type CatalogMode = 'full' | 'free-only';
+
+/**
+ * Source for the currently active OpenRouter catalog.
+ */
+export type CatalogSource = 'api' | 'cache';
+
+/**
+ * Rich classification for the last sync attempt.
+ */
+export type SyncOutcome = 'synced' | 'cache-fallback' | 'no-change' | 'unavailable';
+
+/**
+ * Result of a sync operation.
  */
 export interface SyncResult {
   success: boolean;
+  outcome: SyncOutcome;
+  requestedMode: CatalogMode;
+  catalogMode: CatalogMode | null;
   registeredCount: number;
   skippedCount: number;
   skippedDetails?: SkipReason[]; // Track why models were skipped
-  source: 'api' | 'cache' | 'none';
+  source: CatalogSource | 'none';
   cacheUpdated: boolean;
   cacheAgeMs: number | null;
   error: string | null;
 }
 
 /**
- * Cache file structure - using our OpenRouterModel type for consistency
+ * Snapshot of the catalog currently registered with Pi.
+ */
+export interface ActiveCatalogState {
+  mode: CatalogMode;
+  registeredModelIds?: string[];
+  registeredCount: number;
+  skippedCount: number;
+  skippedDetails: SkipReason[];
+  source: CatalogSource;
+  cacheAgeMs: number;
+}
+
+/**
+ * Cache file structure - using our OpenRouterModel type for consistency.
+ * Stores the raw models for the currently active catalog mode.
  */
 export interface ModelsCache {
+  catalogMode: CatalogMode;
   models: OpenRouterModel[];
   skippedDetails?: SkipReason[]; // New field for tracking skip reasons
   timestamp: number;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "type": "module",
-  "description": "Live OpenRouter spend/account TUI overlays, user-scoped model sync, api key management, and session tagging for Pi.",
+  "description": "Live OpenRouter spend/account TUI overlays, user-scoped or free-only model sync, api key management, and session tagging for Pi.",
   "license": "MIT",
   "files": [
     "extensions",