@robhowley/pi-openrouter 0.7.1 → 0.8.1

package/extensions/openrouter/models/mapper.ts

@@ -0,0 +1,182 @@
+import type { OpenRouterModel, PiModelConfig, SkipReason, MapResult } from './types.js';
+import { ROUTER_ALIASES } from './types.js';
+import type { Model as SDKModel } from '@openrouter/sdk/models/index.js';
+
+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.
+ */
+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,
+  };
+
+  // Conditionally add optional properties to avoid explicit undefined
+  if (topProvider) {
+    result.top_provider = topProvider;
+  }
+  if (perRequestLimits) {
+    result.per_request_limits = perRequestLimits;
+  }
+
+  return result;
+}
+
+/**
+ * Normalize input model to OpenRouterModel format.
+ */
+function normalizeModel(model: OpenRouterModel | SDKModel): OpenRouterModel {
+  return 'contextLength' in model
+    ? sdkModelToOpenRouterModel(model as SDKModel)
+    : (model as OpenRouterModel);
+}
+
+/**
+ * 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.
+ */
+function validateModel(model: OpenRouterModel): ValidationResult {
+  // Check: missing required id
+  if (!model.id) {
+    return { valid: false, reason: 'missing id', modelId: 'unknown' };
+  }
+
+  // Check: missing required pricing fields
+  if (!model.pricing?.prompt) {
+    return { valid: false, reason: 'missing prompt pricing', modelId: model.id };
+  }
+  if (!model.pricing?.completion) {
+    return { valid: false, reason: 'missing completion pricing', modelId: 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 };
+  }
+
+  // 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 { valid: true, model, contextWindow };
+}
+
+/**
+ * Build PiModelConfig from a validated OpenRouterModel.
+ */
+function buildPiConfig(model: OpenRouterModel, contextWindow: number): PiModelConfig {
+  const supportedParams = model.supported_parameters ?? [];
+  const hasReasoning =
+    supportedParams.includes('reasoning') || supportedParams.includes('include_reasoning');
+  const inputModalities = model.architecture?.input_modalities;
+  const supportsImages = inputModalities?.includes('image') ?? false;
+
+  return {
+    id: model.id,
+    name: model.name ?? model.id,
+    reasoning: hasReasoning,
+    input: supportsImages ? ['text', 'image'] : ['text'],
+    cost: {
+      input: Number(model.pricing.prompt) * COST_PER_MILLION,
+      output: Number(model.pricing.completion) * COST_PER_MILLION,
+      cacheRead: Number(model.pricing.input_cache_read ?? 0) * COST_PER_MILLION,
+      cacheWrite: Number(model.pricing.input_cache_write ?? 0) * COST_PER_MILLION,
+    },
+    contextWindow,
+    maxTokens:
+      model.top_provider?.max_completion_tokens ??
+      model.per_request_limits?.completion_tokens ??
+      DEFAULT_MAX_TOKENS,
+  };
+}
+
+/**
+ * Maps multiple OpenRouter models, tracking skips.
+ */
+export function mapOpenRouterModels(models: OpenRouterModel[] | SDKModel[]): MapResult {
+  const configs: PiModelConfig[] = [];
+  let skipped = 0;
+  const skippedDetails: SkipReason[] = [];
+
+  for (const rawModel of models) {
+    const model = normalizeModel(rawModel);
+
+    // Skip router aliases - they're added manually after mapping
+    if (ROUTER_ALIASES.includes(model.id)) {
+      continue;
+    }
+
+    const validation = validateModel(model);
+
+    if (!validation.valid) {
+      skipped++;
+      skippedDetails.push({ id: validation.modelId, reason: validation.reason });
+      continue;
+    }
+
+    configs.push(buildPiConfig(model, validation.contextWindow));
+  }
+
+  return { configs, skipped, skippedDetails };
+}
+
+/**
+ * Maps a single OpenRouter model to Pi model config.
+ * Returns null if the model should be skipped.
+ */
+export function mapOpenRouterModel(model: OpenRouterModel | SDKModel): PiModelConfig | null {
+  const normalized = normalizeModel(model);
+
+  // Router aliases are handled separately, skip them here
+  if (ROUTER_ALIASES.includes(normalized.id)) {
+    return null;
+  }
+
+  const validation = validateModel(normalized);
+
+  if (!validation.valid) {
+    return null;
+  }
+
+  return buildPiConfig(normalized, validation.contextWindow);
+}

package/extensions/openrouter/models/sync.ts

@@ -0,0 +1,310 @@
+/**
+ * Sync engine for OpenRouter models.
+ * Orchestrates model fetch, mapping, registration, and cache management.
+ */
+
+import { fetchUserModels } from '../client.js';
+import { mapOpenRouterModels, sdkModelToOpenRouterModel } from './mapper.js';
+import { loadCache, saveCache } from './cache.js';
+import type { ExtensionContext } from '@mariozechner/pi-coding-agent';
+import type {
+  SyncResult,
+  PiModelConfig,
+  ModelsCache,
+  OpenRouterModel,
+  SkipReason,
+} 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;
+
+/**
+ * Check if model sync is enabled via user config.
+ * Default is true (sync enabled) if config is not set.
+ *
+ * Reads from ~/.pi/agent/settings.json (global settings).
+ */
+export function isSyncEnabled(): boolean {
+  // Get global settings path
+  const globalSettingsPath = join(homedir(), '.pi', 'agent', 'settings.json');
+
+  if (!existsSync(globalSettingsPath)) {
+    return true; // Default to enabled if no settings file
+  }
+
+  try {
+    const settings = JSON.parse(readFileSync(globalSettingsPath, 'utf-8'));
+    // Default is true (enabled) - only disabled if explicitly set to false
+    return settings['openrouterModelSync'] !== false;
+  } catch {
+    return true; // Default to enabled if settings file can't be read
+  }
+}
+
+/**
+ * Set the current sync state.
+ * Called after each sync operation.
+ */
+export function setSyncState(result: SyncResult): void {
+  currentSyncState = result;
+}
+
+/**
+ * Get the current sync state for status display.
+ */
+export function getSyncState(): SyncResult | null {
+  return currentSyncState;
+}
+
+/**
+ * Register mapped models with Pi's OpenRouter provider.
+ *
+ * Uses modelRegistry.registerProvider() to add models to the built-in openrouter provider.
+ * The models array replaces all existing models for the provider.
+ */
+export async function registerModelsWithProvider(
+  ctx: ExtensionContext,
+  configs: PiModelConfig[],
+): Promise<void> {
+  // Register models with Pi's OpenRouter provider
+  // This replaces all existing models for the provider with our synced ones
+  ctx.modelRegistry.registerProvider('openrouter', {
+    baseUrl: 'https://openrouter.ai/api/v1',
+    apiKey: 'OPENROUTER_API_KEY',
+    api: 'openai-completions',
+    models: configs,
+    authHeader: true,
+  });
+}
+
+/**
+ * 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,
+}));
+
+/**
+ * Convert router definitions to OpenRouterModel format for cache storage.
+ */
+function getRouterCacheModels(): OpenRouterModel[] {
+  return ROUTER_DEFINITIONS.map((r) => ({
+    id: r.id,
+    name: r.name,
+    architecture: {
+      input_modalities: [...r.input],
+      output_modalities: [...r.output],
+    },
+    context_length: r.contextLength,
+    pricing: { prompt: '0', completion: '0' },
+    supported_parameters: r.reasoning ? ['reasoning'] : [],
+  }));
+}
+
+/**
+ * Execute a full sync operation:
+ * 1. Fetch models from OpenRouter API
+ * 2. Map to Pi model config
+ * 3. Register with provider
+ * 4. Update cache
+ *
+ * On API failure, falls back to cached models if available.
+ *
+ * @param ctx - Extension context for provider registration
+ * @returns SyncResult with details of the operation
+ */
+export async function syncModels(_ctx: ExtensionContext): 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 } = mapOpenRouterModels(response.data);
+
+    // Add built-in router aliases that don't appear in /models/user endpoint
+    const configsWithRouters = [...configs, ...BUILTIN_ROUTER_MODELS];
+
+    // Register with Pi's OpenRouter provider
+    await registerModelsWithProvider(_ctx, configsWithRouters);
+
+    // Convert SDK Model[] to OpenRouterModel[] for cache storage
+    const cacheModels: OpenRouterModel[] = response.data.map(sdkModelToOpenRouterModel);
+
+    // Update last-good cache (include routers and skip details)
+    const cache: ModelsCache = {
+      models: [...cacheModels, ...getRouterCacheModels()],
+      skippedDetails: skippedDetails,
+      timestamp: Date.now(),
+    };
+    await saveCache(cache);
+
+    const result: SyncResult = {
+      success: true,
+      registeredCount: configsWithRouters.length,
+      skippedCount: skipped,
+      skippedDetails: skippedDetails,
+      source: 'api',
+      cacheUpdated: true,
+      cacheAgeMs: 0, // Cache was just updated
+      error: null,
+    };
+
+    setSyncState(result);
+    return result;
+  } 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 } = mapOpenRouterModels(cache.models);
+
+      await registerModelsWithProvider(_ctx, configs);
+
+      // Use cached skip details if available
+      const cachedSkipDetails = cache.skippedDetails || [];
+
+      const result: SyncResult = {
+        success: false,
+        registeredCount: configs.length,
+        skippedCount: skipped,
+        source: 'cache',
+        cacheUpdated: false,
+        cacheAgeMs: Date.now() - cache.timestamp,
+        error: errorMsg,
+        skippedDetails: cachedSkipDetails,
+      };
+
+      setSyncState(result);
+      return result;
+    }
+
+    // Attempt 3: No cache available - complete failure
+    const result: SyncResult = {
+      success: false,
+      registeredCount: 0,
+      skippedCount: 0,
+      source: 'none',
+      cacheUpdated: false,
+      cacheAgeMs: null,
+      error: errorMsg,
+    };
+
+    setSyncState(result);
+    return result;
+  }
+}
+
+/**
+ * Get a human-readable status string for the current sync state.
+ */
+export function getStatusText(): string {
+  const state = getSyncState();
+
+  if (!state) {
+    return 'OpenRouter models: not synced';
+  }
+
+  // Derive status from result
+  let status: string;
+  if (state.success) {
+    status = 'healthy';
+  } else if (state.source === 'cache') {
+    status = 'cached';
+  } else {
+    status = 'broken';
+  }
+
+  return `OpenRouter models: ${status} (${state.registeredCount} registered)`;
+}
+
+/**
+ * Check if models are currently available (synced or cached).
+ * Checks in-memory 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';
+  }
+
+  // Check cache file on disk
+  const cache = await loadCache();
+  return cache !== null && cache.models.length > 0;
+}
+
+/**
+ * Get skip reasons from the current 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 [];
+
+  // Prefer in-memory state
+  if (state.skippedDetails && state.skippedDetails.length > 0) {
+    return state.skippedDetails.slice(0, maxResults);
+  }
+
+  return [];
+}
+
+/**
+ * Async version of getSkipReasons that reads from cache if needed.
+ */
+export async function getSkipReasonsAsync(maxResults: number = 10): Promise<SkipReason[]> {
+  const state = getSyncState();
+
+  // First check in-memory state
+  if (state?.skippedDetails && state.skippedDetails.length > 0) {
+    return state.skippedDetails.slice(0, 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);
+  }
+
+  return [];
+}
+
+/**
+ * Format skip reasons for display.
+ */
+export function formatSkipReasons(reasons: SkipReason[]): string {
+  if (reasons.length === 0) return '';
+
+  const lines: string[] = [];
+  for (const reason of reasons) {
+    lines.push(`  - ${reason.id}: ${reason.reason}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Group skip reasons by reason type and return counts.
+ */
+export function groupSkipReasons(reasons: SkipReason[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const reason of reasons) {
+    counts[reason.reason] = (counts[reason.reason] || 0) + 1;
+  }
+  return counts;
+}

package/extensions/openrouter/models/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Raw OpenRouter model from /api/v1/models/user
+ */
+export interface OpenRouterModel {
+  id: string;
+  name?: string;
+  architecture?: {
+    input_modalities?: string[];
+    output_modalities?: string[];
+  };
+  context_length: number;
+  pricing: {
+    prompt: string; // per-token price as string
+    completion: string;
+    input_cache_read?: string;
+    input_cache_write?: string;
+  };
+  supported_parameters?: string[];
+  top_provider?: {
+    context_length?: number;
+    max_completion_tokens?: number;
+  };
+  per_request_limits?: {
+    completion_tokens?: number;
+  };
+}
+
+/**
+ * Response wrapper from /models/user endpoint
+ */
+export interface OpenRouterModelsResponse {
+  data: OpenRouterModel[];
+}
+
+/**
+ * Mapped Pi model configuration for provider registration
+ */
+export interface PiModelConfig {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: ('text' | 'image')[];
+  cost: {
+    input: number; // $ per 1M tokens
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+  contextWindow: number;
+  maxTokens: number;
+}
+
+/**
+ * Result of a sync operation
+ */
+export interface SyncResult {
+  success: boolean;
+  registeredCount: number;
+  skippedCount: number;
+  skippedDetails?: SkipReason[]; // Track why models were skipped
+  source: 'api' | 'cache' | 'none';
+  cacheUpdated: boolean;
+  cacheAgeMs: number | null;
+  error: string | null;
+}
+
+/**
+ * Cache file structure - using our OpenRouterModel type for consistency
+ */
+export interface ModelsCache {
+  models: OpenRouterModel[];
+  skippedDetails?: SkipReason[]; // New field for tracking skip reasons
+  timestamp: number;
+}
+
+/**
+ * Reason a model was skipped during mapping.
+ */
+export interface SkipReason {
+  id: string;
+  reason: string;
+}
+
+/**
+ * Result of batch mapping operation
+ */
+export interface MapResult {
+  configs: PiModelConfig[];
+  skipped: number;
+  skippedDetails: SkipReason[];
+}
+
+// =============================================================================
+// Built-in Router Definitions (Single Source of Truth)
+// =============================================================================
+
+/**
+ * Canonical router definitions for OpenRouter's special routing models.
+ * These don't appear in /models/user API but should always be available.
+ */
+export const ROUTER_DEFINITIONS = [
+  {
+    id: 'openrouter/auto',
+    name: 'Auto Router',
+    reasoning: true,
+    input: ['text', 'image'] as const,
+    output: ['text'] as const,
+    contextLength: 2000000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'openrouter/free',
+    name: 'Free Models Router',
+    reasoning: true,
+    input: ['text', 'image'] as const,
+    output: ['text'] as const,
+    contextLength: 200000,
+    maxTokens: 4096,
+  },
+  {
+    id: 'openrouter/owl-alpha',
+    name: 'Owl Alpha',
+    reasoning: false,
+    input: ['text'] as const,
+    output: ['text'] as const,
+    contextLength: 1048756,
+    maxTokens: 262144,
+  },
+] as const;
+
+/**
+ * Router IDs extracted from ROUTER_DEFINITIONS for quick lookup.
+ * Use this for skip checks and filtering.
+ */
+export const ROUTER_ALIASES: readonly string[] = ROUTER_DEFINITIONS.map((r) => r.id);
+
+// =============================================================================
+// Time Constants
+// =============================================================================
+
+/** Milliseconds per minute */
+export const MS_PER_MINUTE = 60000;
+
+/** Milliseconds per hour */
+export const MS_PER_HOUR = 3600000;
+
+/** Milliseconds per day */
+export const MS_PER_DAY = 86400000;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "type": "module",
-  "description": "Live OpenRouter TUI overlays for spend, credits, key limits, burn rate, model usage, and session tagging.",
+  "description": "Live OpenRouter spend/account TUI overlays, user-scoped model sync, and session tagging for Pi.",
   "license": "MIT",
   "files": [
     "extensions",