@robhowley/pi-openrouter 0.7.0 → 0.8.0

package/extensions/openrouter/models/sync.ts

@@ -0,0 +1,312 @@
+/**
+ * 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.
+ */
+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,
+  });
+
+  console.log(`[pi-openrouter] Registered ${configs.length} models with OpenRouter provider`);
+}
+
+/**
+ * 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/extensions/openrouter/session.ts

@@ -25,15 +25,30 @@ export function formatSessionId(sessionId: string): string {
 
 export function isOpenRouterRequest(event: BeforeProviderRequestEvent, _ctx: unknown): boolean {
   const ev = event as unknown as Record<string, unknown>;
-
-  // Method 1: Check model string (e.g., "openrouter/anthropic/claude-3.5-sonnet")
   const payload = ev['payload'] as Record<string, unknown> | undefined;
+
+  // Method 1: Check if provider is explicitly "openrouter" (Pi coding agent first-class)
+  // Provider could be in event.provider, event.payload.provider, as string or object with name
+  const eventProvider = ev['provider'];
+  const payloadProvider = payload?.['provider'];
+  const providerName =
+    typeof eventProvider === 'string'
+      ? eventProvider
+      : typeof payloadProvider === 'string'
+        ? payloadProvider
+        : ((eventProvider as Record<string, unknown> | undefined)?.['name'] ??
+          (payloadProvider as Record<string, unknown> | undefined)?.['name']);
+  if (providerName === 'openrouter') {
+    return true;
+  }
+
+  // Method 2: Check model string (e.g., "openrouter/anthropic/claude-3.5-sonnet")
   const model = String(payload?.['model'] ?? '');
   if (model.includes('openrouter/')) {
     return true;
   }
 
-  // Method 2: Check baseUrl from context.model
+  // Method 3: Check baseUrl from context.model
   // OpenRouter models have baseUrl starting with https://openrouter.ai/api/v1
   const context = _ctx as Record<string, unknown>;
   const ctxModel = context['model'] as Record<string, unknown> | undefined;
@@ -42,13 +57,13 @@ export function isOpenRouterRequest(event: BeforeProviderRequestEvent, _ctx: unk
     return true;
   }
 
-  // Method 3: Check for ZDR provider (Shopify routes to OpenRouter via ZDR)
+  // Method 4: Check for ZDR provider (Shopify routes to OpenRouter via ZDR)
   const provider = ev['provider'] as Record<string, unknown> | undefined;
   if (provider?.['zdr'] === true) {
     return true;
   }
 
-  // Method 4: Check URL
+  // Method 5: Check URL (fallback for events where provider info is missing)
   const url = String(
     (ev['url'] as string | undefined) ?? (ev['endpoint'] as string | undefined) ?? '',
   );

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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",