@robhowley/pi-openrouter 0.8.2 → 0.9.0

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

@@ -0,0 +1,237 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  loadModelOverrides,
+  ModelOverridesLoadError,
+  saveModelOverrides,
+  setModelOverride,
+  removeModelOverride,
+} from '../overrides.js';
+import type { ModelOverridesFile, UserModelOverride } from '../types.js';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+// Mock node:fs
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+}));
+
+// Mock node:fs/promises
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn(),
+  writeFile: vi.fn(),
+  mkdir: vi.fn(),
+  rm: vi.fn(),
+}));
+
+// Mock node:os
+vi.mock('node:os', () => ({
+  homedir: vi.fn(),
+}));
+
+const OVERRIDES_FILE = join('/mock/home', '.pi', 'openrouter', 'model-overrides.json');
+
+describe('overrides', () => {
+  beforeEach(() => {
+    vi.mocked(homedir).mockReturnValue('/mock/home');
+    vi.mocked(existsSync).mockReturnValue(false);
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(rm).mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('loadModelOverrides', () => {
+    it('should return empty overrides when file does not exist', async () => {
+      vi.mocked(existsSync).mockReturnValue(false);
+
+      const result = await loadModelOverrides();
+
+      expect(result).toEqual({ version: 1, overrides: {} });
+    });
+
+    it('should throw when file is invalid JSON', async () => {
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFile).mockResolvedValue('invalid json');
+
+      await expect(loadModelOverrides()).rejects.toThrow(ModelOverridesLoadError);
+      await expect(loadModelOverrides()).rejects.toThrow('Invalid JSON in model overrides file');
+    });
+
+    it('should throw when file has wrong structure', async () => {
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFile).mockResolvedValue(JSON.stringify({ foo: 'bar' }));
+
+      await expect(loadModelOverrides()).rejects.toThrow(ModelOverridesLoadError);
+      await expect(loadModelOverrides()).rejects.toThrow('Invalid model overrides file structure');
+    });
+
+    it('should throw when existing file cannot be read', async () => {
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFile).mockRejectedValue(new Error('permission denied'));
+
+      await expect(loadModelOverrides()).rejects.toThrow(ModelOverridesLoadError);
+      await expect(loadModelOverrides()).rejects.toThrow('Failed to read model overrides file');
+    });
+
+    it('should load valid overrides file', async () => {
+      const mockData: ModelOverridesFile = {
+        version: 1,
+        overrides: {
+          'test/model': {
+            thinkingLevelMap: { high: 'high', xhigh: 'max' },
+          },
+        },
+      };
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFile).mockResolvedValue(JSON.stringify(mockData));
+
+      const result = await loadModelOverrides();
+
+      expect(result).toEqual(mockData);
+    });
+  });
+
+  describe('saveModelOverrides', () => {
+    it('should create directory if it does not exist', async () => {
+      vi.mocked(existsSync).mockReturnValue(false);
+
+      const overrides: ModelOverridesFile = { version: 1, overrides: {} };
+      await saveModelOverrides(overrides);
+
+      expect(mkdir).toHaveBeenCalledWith(join('/mock/home', '.pi', 'openrouter'), {
+        recursive: true,
+      });
+    });
+
+    it('should write JSON to file', async () => {
+      const overrides: ModelOverridesFile = {
+        version: 1,
+        overrides: {
+          'test/model': {
+            thinkingLevelMap: { high: 'high' },
+          },
+        },
+      };
+
+      await saveModelOverrides(overrides);
+
+      expect(writeFile).toHaveBeenCalledWith(
+        OVERRIDES_FILE,
+        JSON.stringify(overrides, null, 2),
+        'utf-8',
+      );
+    });
+  });
+
+  describe('setModelOverride', () => {
+    it('should add new override', () => {
+      const overrides: ModelOverridesFile = { version: 1, overrides: {} };
+      const override: UserModelOverride = {
+        thinkingLevelMap: { high: 'high' },
+      };
+
+      const result = setModelOverride(overrides, 'test/model', override);
+
+      expect(result.overrides['test/model']).toEqual({
+        thinkingLevelMap: { high: 'high' },
+      });
+    });
+
+    it('should merge with existing override', () => {
+      const existing: UserModelOverride = {
+        thinkingLevelMap: { minimal: null, high: 'low' },
+        contextWindow: 128000,
+      };
+      const overrides: ModelOverridesFile = {
+        version: 1,
+        overrides: { 'test/model': existing },
+      };
+
+      const newOverride: UserModelOverride = {
+        thinkingLevelMap: { high: 'high' },
+        maxTokens: 8192,
+      };
+
+      const result = setModelOverride(overrides, 'test/model', newOverride);
+
+      expect(result.overrides['test/model']).toEqual({
+        thinkingLevelMap: { minimal: null, high: 'high' },
+        contextWindow: 128000,
+        maxTokens: 8192,
+      });
+    });
+
+    it('should clean up undefined thinkingLevelMap entries', () => {
+      const overrides: ModelOverridesFile = { version: 1, overrides: {} };
+      const override: UserModelOverride = {
+        thinkingLevelMap: { high: 'high', medium: undefined as unknown as null },
+      };
+
+      const result = setModelOverride(overrides, 'test/model', override);
+
+      expect(result.overrides['test/model']?.thinkingLevelMap).toEqual({
+        high: 'high',
+      });
+    });
+
+    it('should remove empty thinkingLevelMap', () => {
+      const overrides: ModelOverridesFile = { version: 1, overrides: {} };
+      const override: UserModelOverride = {
+        thinkingLevelMap: {},
+        contextWindow: 128000,
+      };
+
+      const result = setModelOverride(overrides, 'test/model', override);
+
+      expect(result.overrides['test/model']?.thinkingLevelMap).toBeUndefined();
+      expect(result.overrides['test/model']?.contextWindow).toBe(128000);
+    });
+
+    it('should not create thinkingLevelMap for non-thinking overrides', () => {
+      const overrides: ModelOverridesFile = { version: 1, overrides: {} };
+
+      const result = setModelOverride(overrides, 'test/model', {
+        contextWindow: 64000,
+      });
+
+      expect(result.overrides['test/model']).toEqual({
+        contextWindow: 64000,
+      });
+    });
+  });
+
+  describe('removeModelOverride', () => {
+    it('should remove existing override', () => {
+      const overrides: ModelOverridesFile = {
+        version: 1,
+        overrides: {
+          'test/model': { thinkingLevelMap: { high: 'high' } },
+        },
+      };
+
+      const result = removeModelOverride(overrides, 'test/model');
+
+      expect(result.overrides['test/model']).toBeUndefined();
+      expect(Object.keys(result.overrides)).toHaveLength(0);
+    });
+
+    it('should be idempotent for non-existent model', () => {
+      const overrides: ModelOverridesFile = {
+        version: 1,
+        overrides: {
+          'other/model': { thinkingLevelMap: { high: 'high' } },
+        },
+      };
+
+      const result = removeModelOverride(overrides, 'unknown/model');
+
+      expect(result).toEqual(overrides);
+    });
+  });
+});

package/extensions/openrouter/models/mapper.ts

@@ -1,6 +1,7 @@
 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';
+import { loadModelOverrides, getModelOverride } from './overrides.js';
 
 // Cache for built-in OpenRouter models from pi-ai
 // Populated lazily on first access
@@ -20,7 +21,6 @@ async function loadBuiltInOpenRouterModels(): Promise<Map<string, PiModelConfig>
 
   try {
     // Import from pi-ai to get built-in model registry
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const { getModels } = (await import('@earendil-works/pi-ai')) as {
       getModels: (provider: string) => unknown[];
     };
@@ -29,7 +29,6 @@ async function loadBuiltInOpenRouterModels(): Promise<Map<string, PiModelConfig>
     if (Array.isArray(openrouterModels)) {
       for (const model of openrouterModels) {
         // Extract thinkingLevelMap from built-in model if present
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const modelWithThinking = model as { id: string; thinkingLevelMap?: unknown };
         if (modelWithThinking.id) {
           models.set(modelWithThinking.id, model as PiModelConfig);
@@ -155,11 +154,13 @@ function validateModel(model: OpenRouterModel): ValidationResult {
 
 /**
  * Build PiModelConfig from a validated OpenRouterModel.
- * Merges thinkingLevelMap from Pi's built-in registry if available.
+ * Merges thinkingLevelMap from Pi's built-in registry and user overrides.
+ * Priority: user overrides > built-in registry > API data
  */
 async function buildPiConfig(
   model: OpenRouterModel,
   contextWindow: number,
+  userOverrides?: Awaited<ReturnType<typeof loadModelOverrides>>,
 ): Promise<PiModelConfig> {
   const supportedParams = model.supported_parameters ?? [];
   const hasReasoning =
@@ -168,12 +169,25 @@ async function buildPiConfig(
   const supportsImages = inputModalities?.includes('image') ?? false;
 
   // Fetch thinkingLevelMap from built-in registry if this is a reasoning model
-  const thinkingLevelMap = hasReasoning ? await getBuiltInThinkingLevelMap(model.id) : undefined;
+  const builtInThinkingLevelMap = hasReasoning
+    ? await getBuiltInThinkingLevelMap(model.id)
+    : undefined;
+
+  // Fetch user override for this model
+  const userOverride = userOverrides ? getModelOverride(userOverrides, model.id) : undefined;
+
+  const thinkingLevelMap =
+    builtInThinkingLevelMap !== undefined || userOverride?.thinkingLevelMap !== undefined
+      ? {
+          ...builtInThinkingLevelMap,
+          ...userOverride?.thinkingLevelMap,
+        }
+      : undefined;
 
   const config: PiModelConfig = {
     id: model.id,
     name: model.name ?? model.id,
-    reasoning: hasReasoning,
+    reasoning: userOverride?.reasoning ?? hasReasoning,
     input: supportsImages ? ['text', 'image'] : ['text'],
     cost: {
       input: Number(model.pricing.prompt) * COST_PER_MILLION,
@@ -181,8 +195,9 @@ async function buildPiConfig(
       cacheRead: Number(model.pricing.input_cache_read ?? 0) * COST_PER_MILLION,
       cacheWrite: Number(model.pricing.input_cache_write ?? 0) * COST_PER_MILLION,
     },
-    contextWindow,
+    contextWindow: userOverride?.contextWindow ?? contextWindow,
     maxTokens:
+      userOverride?.maxTokens ??
       model.top_provider?.max_completion_tokens ??
       model.per_request_limits?.completion_tokens ??
       DEFAULT_MAX_TOKENS,
@@ -198,13 +213,14 @@ async function buildPiConfig(
 
 /**
  * Maps multiple OpenRouter models, tracking skips.
- * Async to allow fetching thinkingLevelMap from built-in registry.
+ * Async to allow fetching thinkingLevelMap from built-in registry and user overrides.
  */
 export async function mapOpenRouterModels(
   models: OpenRouterModel[] | SDKModel[],
 ): Promise<MapResult> {
-  // Pre-load built-in models for efficient lookup during mapping
+  // Pre-load built-in models and user overrides for efficient lookup during mapping
   await loadBuiltInOpenRouterModels();
+  const userOverrides = await loadModelOverrides();
 
   const configs: PiModelConfig[] = [];
   let skipped = 0;
@@ -226,7 +242,7 @@ export async function mapOpenRouterModels(
       continue;
     }
 
-    configs.push(await buildPiConfig(model, validation.contextWindow));
+    configs.push(await buildPiConfig(model, validation.contextWindow, userOverrides));
   }
 
   return { configs, skipped, skippedDetails };
@@ -241,6 +257,7 @@ export async function mapOpenRouterModel(
   model: OpenRouterModel | SDKModel,
 ): Promise<PiModelConfig | null> {
   await loadBuiltInOpenRouterModels();
+  const userOverrides = await loadModelOverrides();
 
   const normalized = normalizeModel(model);
 
@@ -255,5 +272,5 @@ export async function mapOpenRouterModel(
     return null;
   }
 
-  return buildPiConfig(normalized, validation.contextWindow);
+  return buildPiConfig(normalized, validation.contextWindow, userOverrides);
 }

package/extensions/openrouter/models/overrides.ts

@@ -0,0 +1,174 @@
+/**
+ * User model overrides persistence
+ *
+ * Manages ~/.pi/openrouter/model-overrides.json for user-defined
+ * PiModelConfig field overrides.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { UserModelOverride, ModelOverridesFile, ThinkingLevelMap } from './types.js';
+
+export class ModelOverridesLoadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ModelOverridesLoadError';
+  }
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Get the path to the overrides file.
+ * Computed lazily to allow for test mocking.
+ */
+function getOverridesFile(): string {
+  return join(homedir(), '.pi', 'openrouter', 'model-overrides.json');
+}
+
+/**
+ * Load model overrides from disk.
+ * Returns empty structure only when the file doesn't exist.
+ * Throws when an existing file cannot be read, parsed, or validated.
+ */
+export async function loadModelOverrides(): Promise<ModelOverridesFile> {
+  const overridesFile = getOverridesFile();
+  if (!existsSync(overridesFile)) {
+    return { version: 1, overrides: {} };
+  }
+
+  let content: string;
+  try {
+    content = await readFile(overridesFile, 'utf-8');
+  } catch (error) {
+    throw new ModelOverridesLoadError(
+      `Failed to read model overrides file at ${overridesFile}: ${getErrorMessage(error)}`,
+    );
+  }
+
+  let data: unknown;
+  try {
+    data = JSON.parse(content) as unknown;
+  } catch (error) {
+    throw new ModelOverridesLoadError(
+      `Invalid JSON in model overrides file at ${overridesFile}: ${getErrorMessage(error)}`,
+    );
+  }
+
+  // Basic validation
+  if (
+    typeof data === 'object' &&
+    data !== null &&
+    'version' in data &&
+    typeof (data as { version: unknown }).version === 'number' &&
+    'overrides' in data &&
+    typeof (data as { overrides: unknown }).overrides === 'object' &&
+    (data as { overrides: unknown }).overrides !== null
+  ) {
+    return data as ModelOverridesFile;
+  }
+
+  throw new ModelOverridesLoadError(`Invalid model overrides file structure at ${overridesFile}`);
+}
+
+/**
+ * Save model overrides to disk.
+ */
+export async function saveModelOverrides(overrides: ModelOverridesFile): Promise<void> {
+  const overridesFile = getOverridesFile();
+  const overridesDir = join(homedir(), '.pi', 'openrouter');
+
+  // Ensure directory exists
+  if (!existsSync(overridesDir)) {
+    await mkdir(overridesDir, { recursive: true });
+  }
+
+  const content = JSON.stringify(overrides, null, 2);
+  await writeFile(overridesFile, content, 'utf-8');
+}
+
+/**
+ * Get existing override for a specific model.
+ */
+export function getModelOverride(
+  overrides: ModelOverridesFile,
+  modelId: string,
+): UserModelOverride | undefined {
+  return overrides.overrides[modelId];
+}
+
+/**
+ * Set override for a specific model.
+ * Merges with existing override.
+ */
+export function setModelOverride(
+  overrides: ModelOverridesFile,
+  modelId: string,
+  override: UserModelOverride,
+): ModelOverridesFile {
+  const existing = overrides.overrides[modelId] ?? {};
+  const mergedThinkingLevelMap =
+    existing.thinkingLevelMap !== undefined || override.thinkingLevelMap !== undefined
+      ? {
+          ...existing.thinkingLevelMap,
+          ...override.thinkingLevelMap,
+        }
+      : undefined;
+
+  const merged: UserModelOverride = {
+    ...existing,
+    ...override,
+  };
+
+  if (mergedThinkingLevelMap !== undefined) {
+    const cleaned = Object.fromEntries(
+      Object.entries(mergedThinkingLevelMap).filter(([, v]) => v !== undefined),
+    );
+    if (Object.keys(cleaned).length > 0) {
+      merged.thinkingLevelMap = cleaned as Partial<ThinkingLevelMap>;
+    } else {
+      delete merged.thinkingLevelMap;
+    }
+  }
+
+  return {
+    ...overrides,
+    overrides: {
+      ...overrides.overrides,
+      [modelId]: merged,
+    },
+  };
+}
+
+/**
+ * Remove override for a specific model.
+ */
+export function removeModelOverride(
+  overrides: ModelOverridesFile,
+  modelId: string,
+): ModelOverridesFile {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { [modelId]: _, ...rest } = overrides.overrides;
+  return {
+    ...overrides,
+    overrides: rest,
+  };
+}
+
+/**
+ * Get all model IDs that have overrides.
+ */
+export function getOverrideModelIds(overrides: ModelOverridesFile): string[] {
+  return Object.keys(overrides.overrides);
+}
+
+/**
+ * Check if any overrides exist.
+ */
+export function hasOverrides(overrides: ModelOverridesFile): boolean {
+  return Object.keys(overrides.overrides).length > 0;
+}

package/extensions/openrouter/models/types.ts

@@ -105,6 +105,35 @@ export interface MapResult {
   skippedDetails: SkipReason[];
 }
 
+// =============================================================================
+// User Override Types
+// =============================================================================
+
+/**
+ * User-defined override for any PiModelConfig field.
+ * Stored in ~/.pi/openrouter/model-overrides.json
+ *
+ * For type safety, fields must be validated before storage.
+ * Unknown fields are ignored during merge.
+ */
+export interface UserModelOverride {
+  // Nested thinking level map - mapped from 'thinking.X' scoped syntax
+  thinkingLevelMap?: Partial<ThinkingLevelMap>;
+
+  // Top-level PiModelConfig overrides
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+}
+
+/**
+ * The overrides file structure.
+ */
+export interface ModelOverridesFile {
+  version: number;
+  overrides: Record<string, UserModelOverride>;
+}
+
 // =============================================================================
 // Built-in Router Definitions (Single Source of Truth)
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robhowley/pi-openrouter",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "type": "module",
   "description": "Live OpenRouter spend/account TUI overlays, user-scoped model sync, and session tagging for Pi.",
   "license": "MIT",