@robhowley/pi-openrouter 0.8.2 → 0.9.0

package/extensions/openrouter/index.ts

@@ -28,6 +28,16 @@ import {
 } from './models/sync.js';
 import { loadCache, getCacheAgeMs, formatDuration } from './models/cache.js';
 import { mapOpenRouterModels } from './models/mapper.js';
+import {
+  loadModelOverrides,
+  saveModelOverrides,
+  setModelOverride,
+  removeModelOverride,
+  getModelOverride,
+  getOverrideModelIds,
+  hasOverrides,
+} from './models/overrides.js';
+import type { UserModelOverride, ThinkingLevelMap, ModelOverridesFile } from './models/types.js';
 
 // Store the current session state for use in command handlers
 let currentSessionState: OpenRouterSessionState | null = null;
@@ -43,6 +53,10 @@ let startupCacheInfo: { count: number; age: string } | undefined;
 /**
  * Format skipped models details for --skipped flag output.
  */
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function formatSkippedDetails(
   skipCount: number,
   groupedReasons: Record<string, number>,
@@ -285,16 +299,26 @@ export default async function (pi: ExtensionAPI) {
   pi.registerCommand('openrouter', {
     description: 'OpenRouter commands: usage, account, session, models-sync, models-status',
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ['usage', 'account', 'session', 'models-sync', 'models-status'];
+      const subcommands = [
+        'usage',
+        'account',
+        'session',
+        'models-sync',
+        'models-status',
+        'model-override-set',
+        'model-override-clear',
+        'model-override-list',
+      ];
       const items = subcommands
         .filter((s) => s.startsWith(prefix))
         .map((s) => ({ value: s, label: s }));
       return items.length > 0 ? items : null;
     },
     handler: async (args, ctx) => {
-      // Parse subcommand and flags
+      // Parse subcommand and args
       const parts = args.trim().split(/\s+/);
       const subcommand = parts[0] || '';
+      const subcommandArgs = parts.slice(1).join(' ').trim();
       const flags = parts.slice(1).reduce(
         (acc, flag) => {
           acc[flag] = true;
@@ -382,8 +406,74 @@ export default async function (pi: ExtensionAPI) {
           }
           break;
         }
+        case 'model-override-set': {
+          let userOverrides: ModelOverridesFile;
+          try {
+            userOverrides = await loadModelOverrides();
+          } catch (error) {
+            ctx.ui.notify(`Failed to load model overrides: ${getErrorMessage(error)}`, 'error');
+            break;
+          }
+
+          const result = await handleModelOverrideSet(subcommandArgs, userOverrides);
+          if (result.success) {
+            ctx.ui.notify(result.message, 'info');
+            // Notify if we just changed the currently active model
+            if (result.modelId && ctx.model && result.modelId === ctx.model.id) {
+              ctx.ui.notify(
+                'Model configuration updated. Run /openrouter models-sync to apply changes to the current conversation.',
+                'info',
+              );
+            }
+          } else {
+            ctx.ui.notify(result.message, 'error');
+          }
+          break;
+        }
+        case 'model-override-clear': {
+          let userOverrides: ModelOverridesFile;
+          try {
+            userOverrides = await loadModelOverrides();
+          } catch (error) {
+            ctx.ui.notify(`Failed to load model overrides: ${getErrorMessage(error)}`, 'error');
+            break;
+          }
+
+          const result = await handleModelOverrideClear(subcommandArgs, userOverrides);
+          if (result.success) {
+            ctx.ui.notify(result.message, 'info');
+            // Notify if we just cleared the currently active model
+            if (result.modelId && ctx.model && result.modelId === ctx.model.id) {
+              ctx.ui.notify(
+                'Model configuration updated. Run /openrouter models-sync to apply changes to the current conversation.',
+                'info',
+              );
+            }
+          } else {
+            ctx.ui.notify(result.message, 'error');
+          }
+          break;
+        }
+        case 'model-override-list': {
+          try {
+            const result = await handleModelOverrideList(subcommandArgs);
+            ctx.ui.notify(result, 'info');
+          } catch (error) {
+            ctx.ui.notify(`Failed to load model overrides: ${getErrorMessage(error)}`, 'error');
+          }
+          break;
+        }
         default: {
-          const available = ['usage', 'account', 'session', 'models-sync', 'models-status'];
+          const available = [
+            'usage',
+            'account',
+            'session',
+            'models-sync',
+            'models-status',
+            'model-override-set',
+            'model-override-clear',
+            'model-override-list',
+          ];
           const message =
             available.length > 0
               ? `Available subcommands: ${available.join(', ')}${available.length > 1 ? '' : ''}`
@@ -396,6 +486,317 @@ export default async function (pi: ExtensionAPI) {
   });
 }
 
+// =============================================================================
+// Generic Model Override Handlers (Scoped Syntax)
+// =============================================================================
+
+interface HandlerResult {
+  success: boolean;
+  message: string;
+  modelId?: string;
+}
+
+interface ScopedField {
+  targetField: string;
+  targetType: 'string' | 'number' | 'boolean';
+}
+
+/**
+ * Scoped field name mapping: converts user-facing 'thinking.X' to internal 'thinkingLevelMap.X'
+ * Also supports exact PiModelConfig field names for future extensibility.
+ */
+const SCOPED_FIELD_MAP: Record<string, ScopedField> = {
+  // thinking.* shorthand - maps to thinkingLevelMap
+  'thinking.off': { targetField: 'thinkingLevelMap.off', targetType: 'string' },
+  'thinking.minimal': { targetField: 'thinkingLevelMap.minimal', targetType: 'string' },
+  'thinking.low': { targetField: 'thinkingLevelMap.low', targetType: 'string' },
+  'thinking.medium': { targetField: 'thinkingLevelMap.medium', targetType: 'string' },
+  'thinking.high': { targetField: 'thinkingLevelMap.high', targetType: 'string' },
+  'thinking.xhigh': { targetField: 'thinkingLevelMap.xhigh', targetType: 'string' },
+
+  // exact field names (passthrough)
+  'thinkingLevelMap.off': { targetField: 'thinkingLevelMap.off', targetType: 'string' },
+  'thinkingLevelMap.minimal': { targetField: 'thinkingLevelMap.minimal', targetType: 'string' },
+  'thinkingLevelMap.low': { targetField: 'thinkingLevelMap.low', targetType: 'string' },
+  'thinkingLevelMap.medium': { targetField: 'thinkingLevelMap.medium', targetType: 'string' },
+  'thinkingLevelMap.high': { targetField: 'thinkingLevelMap.high', targetType: 'string' },
+  'thinkingLevelMap.xhigh': { targetField: 'thinkingLevelMap.xhigh', targetType: 'string' },
+
+  // top-level fields (future extensibility)
+  contextWindow: { targetField: 'contextWindow', targetType: 'number' },
+  maxTokens: { targetField: 'maxTokens', targetType: 'number' },
+  reasoning: { targetField: 'reasoning', targetType: 'boolean' },
+};
+
+/**
+ * Parse a scoped assignment like "thinking.high=high" or "contextWindow=128000".
+ */
+export function parseScopedAssignment(
+  assignment: string,
+): { fullPath: string; value: unknown } | null {
+  const eqIdx = assignment.indexOf('=');
+  if (eqIdx === -1) return null;
+
+  const scopedName = assignment.slice(0, eqIdx).trim();
+  const rawValue = assignment.slice(eqIdx + 1).trim();
+
+  const mapped = SCOPED_FIELD_MAP[scopedName];
+  if (!mapped) return null;
+
+  // Parse value by type
+  let parsedValue: unknown;
+  switch (mapped.targetType) {
+    case 'string':
+      // "null" -> null, otherwise string
+      parsedValue = rawValue === 'null' ? null : rawValue;
+      break;
+    case 'number': {
+      const num = parseInt(rawValue, 10);
+      if (isNaN(num)) return null;
+      parsedValue = num;
+      break;
+    }
+    case 'boolean':
+      if (rawValue !== 'true' && rawValue !== 'false') return null;
+      parsedValue = rawValue === 'true';
+      break;
+    default:
+      return null;
+  }
+
+  return { fullPath: mapped.targetField, value: parsedValue };
+}
+
+/**
+ * Apply a nested value to an object using dot notation path.
+ */
+export function applyNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split('.');
+  let current: unknown = obj;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const key = parts[i]!;
+    const currentRecord = current as Record<string, unknown>;
+    if (
+      !(key in currentRecord) ||
+      typeof currentRecord[key] !== 'object' ||
+      currentRecord[key] === null
+    ) {
+      currentRecord[key] = {};
+    }
+    current = currentRecord[key];
+  }
+
+  const finalKey = parts[parts.length - 1]!;
+  (current as Record<string, unknown>)[finalKey] = value;
+}
+
+/**
+ * Handle /openrouter model-override-set command.
+ * Format: model-override-set <model-id> <field=value>...
+ * Examples:
+ *   /openrouter model-override-set deepseek/deepseek-v4-pro thinking.high=high thinking.xhigh=max
+ *   /openrouter model-override-set deepseek/deepseek-v4-pro contextWindow=128000
+ */
+export async function handleModelOverrideSet(
+  args: string,
+  userOverrides: ModelOverridesFile,
+): Promise<HandlerResult> {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+
+  if (parts.length < 1) {
+    return {
+      success: false,
+      message:
+        'Usage: /openrouter model-override-set <model-id> <field=value>...\nExample: /openrouter model-override-set deepseek/deepseek-v4-pro thinking.high=high thinking.xhigh=max',
+    };
+  }
+
+  const modelId = parts[0];
+
+  if (!modelId) {
+    return {
+      success: false,
+      message:
+        'Usage: /openrouter model-override-set <model-id> <field=value>...\nExample: /openrouter model-override-set deepseek/deepseek-v4-pro thinking.high=high thinking.xhigh=max',
+    };
+  }
+
+  // Validate model ID format (should be provider/model)
+  if (!modelId.includes('/')) {
+    return {
+      success: false,
+      message: `Invalid model ID format: "${modelId}"\nExpected format: provider/model (e.g., "deepseek/deepseek-v4-pro")`,
+    };
+  }
+
+  // Build override incrementally from assignments
+  const override: UserModelOverride = {};
+  const assignments = parts.slice(1).filter((p) => !p.startsWith('--'));
+
+  for (const assignment of assignments) {
+    const parsed = parseScopedAssignment(assignment);
+    if (!parsed) {
+      return {
+        success: false,
+        message: `Invalid assignment: "${assignment}"\nExpected format: field=value (e.g., thinking.high=high or contextWindow=128000)\nSee available fields with /openrouter model-override-list --fields`,
+      };
+    }
+    applyNestedValue(override as Record<string, unknown>, parsed.fullPath, parsed.value);
+  }
+
+  // If no assignments provided, error out
+  if (Object.keys(override).length === 0) {
+    return {
+      success: false,
+      message:
+        'No field assignments provided.\nUsage: /openrouter model-override-set <model-id> field=value [field=value]...\nExample: /openrouter model-override-set deepseek/deepseek-v4-pro thinking.high=high thinking.xhigh=max',
+    };
+  }
+
+  // Update overrides file
+  const updatedOverrides = setModelOverride(userOverrides, modelId, override);
+  try {
+    await saveModelOverrides(updatedOverrides);
+  } catch (error) {
+    return {
+      success: false,
+      message: `Failed to save overrides for ${modelId}: ${getErrorMessage(error)}`,
+    };
+  }
+
+  const savedOverride = updatedOverrides.overrides[modelId] as UserModelOverride;
+
+  // Format success message
+  const lines: string[] = [`Saved overrides for ${modelId}:`];
+  for (const [key, val] of Object.entries(savedOverride)) {
+    if (key === 'thinkingLevelMap' && val) {
+      lines.push('  thinkingLevelMap:');
+      for (const [level, mapped] of Object.entries(val as ThinkingLevelMap)) {
+        lines.push(`    ${level}: ${mapped === null ? 'null' : mapped}`);
+      }
+    } else {
+      lines.push(`  ${key}: ${val}`);
+    }
+  }
+
+  return {
+    success: true,
+    message: lines.join('\n'),
+    modelId,
+  };
+}
+
+/**
+ * Handle /openrouter model-override-clear command.
+ */
+export async function handleModelOverrideClear(
+  args: string,
+  userOverrides: ModelOverridesFile,
+): Promise<HandlerResult> {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  const modelId = parts[0];
+
+  if (!modelId) {
+    return {
+      success: false,
+      message: 'Usage: /openrouter model-override-clear <model-id>',
+    };
+  }
+
+  if (!modelId.includes('/')) {
+    return {
+      success: false,
+      message: `Invalid model ID format: "${modelId}"\nExpected format: provider/model`,
+    };
+  }
+
+  const existing = getModelOverride(userOverrides, modelId);
+  if (!existing) {
+    return {
+      success: false,
+      message: `No overrides found for ${modelId}`,
+    };
+  }
+
+  const updatedOverrides = removeModelOverride(userOverrides, modelId);
+  try {
+    await saveModelOverrides(updatedOverrides);
+  } catch (error) {
+    return {
+      success: false,
+      message: `Failed to clear overrides for ${modelId}: ${getErrorMessage(error)}`,
+    };
+  }
+
+  return {
+    success: true,
+    message: `Cleared all overrides for ${modelId}`,
+    modelId,
+  };
+}
+
+/**
+ * Handle /openrouter model-override-list command.
+ */
+export async function handleModelOverrideList(args: string): Promise<string> {
+  const userOverrides = await loadModelOverrides();
+  const modelId = args.trim();
+
+  // List available fields if --fields flag
+  if (modelId === '--fields') {
+    const fields = Object.keys(SCOPED_FIELD_MAP)
+      .map(
+        (k) => `  ${k}: ${SCOPED_FIELD_MAP[k]!.targetField} (${SCOPED_FIELD_MAP[k]!.targetType})`,
+      )
+      .join('\n');
+    return `Available override fields:\n${fields}`;
+  }
+
+  if (!hasOverrides(userOverrides)) {
+    return 'No model overrides configured.\nUse /openrouter model-override-set to add overrides.';
+  }
+
+  if (modelId) {
+    // Show specific model
+    const override = getModelOverride(userOverrides, modelId);
+    if (!override) {
+      return `No overrides configured for ${modelId}`;
+    }
+
+    const lines: string[] = [`Overrides for ${modelId}:`];
+    for (const [key, val] of Object.entries(override)) {
+      if (key === 'thinkingLevelMap' && val) {
+        lines.push('  thinkingLevelMap:');
+        for (const [level, mapped] of Object.entries(val as ThinkingLevelMap)) {
+          lines.push(`    ${level}: ${mapped === null ? 'null' : mapped}`);
+        }
+      } else {
+        lines.push(`  ${key}: ${val}`);
+      }
+    }
+    return lines.join('\n');
+  }
+
+  // List all overrides
+  const modelIds = getOverrideModelIds(userOverrides);
+  const lines: string[] = [`${modelIds.length} model(s) with overrides:`];
+  for (const id of modelIds) {
+    const override = getModelOverride(userOverrides, id);
+    if (override?.thinkingLevelMap && Object.keys(override.thinkingLevelMap).length > 0) {
+      const tlm = Object.entries(override.thinkingLevelMap)
+        .filter(([, v]) => v !== null)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(',');
+      lines.push(`  ${id}${tlm ? ` [${tlm}]` : ''}`);
+    } else {
+      lines.push(`  ${id}`);
+    }
+  }
+  lines.push('\nUse /openrouter model-override-list <model-id> for details');
+  return lines.join('\n');
+}
+
 async function showAccountOverlay(ctx: ExtensionContext) {
   let error: string | null = null;
   let keyInfo: KeyInfo[] | null = null;

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

@@ -0,0 +1,102 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createValidModel } from '../../__tests__/fixtures.js';
+import type { ModelOverridesFile } from '../types.js';
+
+const { loadModelOverrides } = vi.hoisted(() => ({
+  loadModelOverrides: vi.fn<() => Promise<ModelOverridesFile>>(),
+}));
+
+vi.mock('../overrides.js', () => ({
+  loadModelOverrides,
+  getModelOverride: (overrides: ModelOverridesFile, modelId: string) =>
+    overrides.overrides[modelId],
+}));
+
+vi.mock('@earendil-works/pi-ai', () => ({
+  getModels: vi.fn(() => [
+    {
+      id: 'test/model',
+      thinkingLevelMap: {
+        minimal: 'builtin-minimal',
+        high: 'builtin-high',
+        xhigh: 'builtin-xhigh',
+      },
+    },
+  ]),
+}));
+
+import { mapOpenRouterModels } from '../mapper.js';
+
+describe('mapOpenRouterModels overrides', () => {
+  beforeEach(() => {
+    loadModelOverrides.mockResolvedValue({ version: 1, overrides: {} });
+  });
+
+  it('applies top-level overrides and merges sparse thinkingLevelMap with built-in values', async () => {
+    loadModelOverrides.mockResolvedValue({
+      version: 1,
+      overrides: {
+        'test/model': {
+          contextWindow: 64000,
+          maxTokens: 8192,
+          reasoning: false,
+          thinkingLevelMap: {
+            high: 'override-high',
+            xhigh: null,
+          },
+        },
+      },
+    });
+
+    const result = await mapOpenRouterModels([
+      createValidModel({
+        id: 'test/model',
+        supported_parameters: ['reasoning'],
+      }),
+    ]);
+
+    expect(result.configs).toHaveLength(1);
+    expect(result.configs[0]).toMatchObject({
+      id: 'test/model',
+      contextWindow: 64000,
+      maxTokens: 8192,
+      reasoning: false,
+      thinkingLevelMap: {
+        minimal: 'builtin-minimal',
+        high: 'override-high',
+        xhigh: null,
+      },
+    });
+  });
+
+  it('applies user thinkingLevelMap when the built-in registry has no map for the model', async () => {
+    loadModelOverrides.mockResolvedValue({
+      version: 1,
+      overrides: {
+        'new/model': {
+          thinkingLevelMap: {
+            high: 'high',
+            xhigh: 'max',
+          },
+        },
+      },
+    });
+
+    const result = await mapOpenRouterModels([
+      createValidModel({
+        id: 'new/model',
+        supported_parameters: ['reasoning'],
+      }),
+    ]);
+
+    expect(result.configs).toHaveLength(1);
+    expect(result.configs[0]).toMatchObject({
+      id: 'new/model',
+      reasoning: true,
+      thinkingLevelMap: {
+        high: 'high',
+        xhigh: 'max',
+      },
+    });
+  });
+});