@robhowley/pi-openrouter 0.8.3 → 0.9.1

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/skip-hints.ts

@@ -0,0 +1,19 @@
+const SKIP_REASON_HINTS: Record<string, string> = {
+  'missing context window':
+    "Add a local contextWindow override with '/openrouter model-override-set <model-id> contextWindow=<tokens>' if the model's limit is known.",
+  'missing max tokens':
+    "Add a local maxTokens override with '/openrouter model-override-set <model-id> maxTokens=<tokens>' if the model's completion limit is known.",
+  'missing prompt pricing':
+    'OpenRouter did not provide complete pricing metadata, so Pi cannot map model cost safely.',
+  'missing completion pricing':
+    'OpenRouter did not provide complete pricing metadata, so Pi cannot map model cost safely.',
+  'non-text output modalities':
+    'This sync only registers models that advertise text/chat output, so non-text-only models are skipped.',
+};
+
+/**
+ * Return an optional human-readable hint for a stable machine-readable skip reason.
+ */
+export function getSkipReasonHint(reason: string): string | undefined {
+  return SKIP_REASON_HINTS[reason];
+}

package/extensions/openrouter/models/sync.ts

@@ -4,7 +4,8 @@
  */
 
 import { fetchUserModels } from '../client.js';
-import { mapOpenRouterModels, sdkModelToOpenRouterModel } from './mapper.js';
+import { mapOpenRouterModels } from './mapper.js';
+import { sdkModelToOpenRouterModel } from '../normalizers.js';
 import { loadCache, saveCache } from './cache.js';
 import type { ExtensionContext } from '@mariozechner/pi-coding-agent';
 import type {
@@ -63,15 +64,13 @@ export function getSyncState(): SyncResult | null {
 /**
  * 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.
+ * Uses modelRegistry.registerProvider() to replace the provider's model list with the synced
+ * user-scoped catalog plus the built-in router aliases that do not appear in /models/user.
  */
 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',
@@ -96,6 +95,18 @@ const BUILTIN_ROUTER_MODELS: PiModelConfig[] = ROUTER_DEFINITIONS.map((r) => ({
   maxTokens: r.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[] {
+  const seen = new Set(configs.map((config) => config.id));
+  const routersToAdd = BUILTIN_ROUTER_MODELS.filter((router) => !seen.has(router.id));
+  return [...configs, ...routersToAdd];
+}
+
 /**
  * Convert router definitions to OpenRouterModel format for cache storage.
  */
@@ -134,8 +145,8 @@ export async function syncModels(_ctx: ExtensionContext): Promise<SyncResult> {
     const response = await fetchUserModels();
     const { configs, skipped, skippedDetails } = await mapOpenRouterModels(response.data);
 
-    // Add built-in router aliases that don't appear in /models/user endpoint
-    const configsWithRouters = [...configs, ...BUILTIN_ROUTER_MODELS];
+    // Add built-in router aliases that don't appear in /models/user endpoint.
+    const configsWithRouters = includeBuiltinRouterModels(configs);
 
     // Register with Pi's OpenRouter provider
     await registerModelsWithProvider(_ctx, configsWithRouters);
@@ -173,15 +184,16 @@ export async function syncModels(_ctx: ExtensionContext): Promise<SyncResult> {
     if (cache) {
       // Attempt 2: Use cached models
       const { configs, skipped } = await mapOpenRouterModels(cache.models);
+      const configsWithRouters = includeBuiltinRouterModels(configs);
 
-      await registerModelsWithProvider(_ctx, configs);
+      await registerModelsWithProvider(_ctx, configsWithRouters);
 
       // Use cached skip details if available
       const cachedSkipDetails = cache.skippedDetails || [];
 
       const result: SyncResult = {
         success: false,
-        registeredCount: configs.length,
+        registeredCount: configsWithRouters.length,
         skippedCount: skipped,
         source: 'cache',
         cacheUpdated: false,
@@ -245,7 +257,7 @@ export async function areModelsAvailable(): Promise<boolean> {
 
   // Check cache file on disk
   const cache = await loadCache();
-  return cache !== null && cache.models.length > 0;
+  return !!cache && cache.models.length > 0;
 }
 
 /**

package/extensions/openrouter/models/types.ts

@@ -9,7 +9,7 @@ export interface OpenRouterModel {
     output_modalities?: string[];
   };
   context_length: number;
-  pricing: {
+  pricing?: {
     prompt: string; // per-token price as string
     completion: string;
     input_cache_read?: string;
@@ -94,6 +94,7 @@ export interface ModelsCache {
 export interface SkipReason {
   id: string;
   reason: string;
+  hint?: string;
 }
 
 /**
@@ -105,6 +106,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/extensions/openrouter/normalizers.ts

@@ -0,0 +1,128 @@
+import type { Model as SDKModel } from '@openrouter/sdk/models/index.js';
+import type { GetCurrentKeyData, ListData } from '@openrouter/sdk/models/operations/index.js';
+import type { BYOKStatus, ResetCadence } from './account-types.js';
+import type { OpenRouterModel } from './models/types.js';
+
+export interface NormalizedKeyMetadata {
+  name: string;
+  label: string;
+  used: number;
+  resetCadence: ResetCadence;
+  byok: BYOKStatus;
+  hash: string;
+  disabled: boolean;
+  limit?: number;
+  remaining?: number;
+}
+
+/**
+ * Convert SDK Model to our canonical OpenRouterModel shape.
+ * This isolates SDK camelCase/null handling at the package boundary.
+ */
+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;
+
+  const architecture = model.architecture
+    ? {
+        input_modalities: model.architecture.inputModalities ?? [],
+        output_modalities: model.architecture.outputModalities ?? [],
+      }
+    : undefined;
+
+  const pricing = model.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),
+      }
+    : undefined;
+
+  const result: OpenRouterModel = {
+    id: model.id,
+    name: model.name,
+    context_length: model.contextLength ?? 0,
+    supported_parameters: model.supportedParameters,
+  };
+
+  if (architecture) {
+    result.architecture = architecture;
+  }
+  if (pricing) {
+    result.pricing = pricing;
+  }
+  if (topProvider) {
+    result.top_provider = topProvider;
+  }
+  if (perRequestLimits) {
+    result.per_request_limits = perRequestLimits;
+  }
+
+  return result;
+}
+
+/**
+ * Normalize mixed SDK/canonical model inputs into the package's canonical shape.
+ */
+export function normalizeOpenRouterModel(model: OpenRouterModel | SDKModel): OpenRouterModel {
+  return 'contextLength' in model ? sdkModelToOpenRouterModel(model as SDKModel) : model;
+}
+
+/**
+ * Normalize SDK key metadata into the package's canonical internal shape.
+ * Converts SDK null/variant fields once so account code can stay domain-focused.
+ */
+export function normalizeSdkKeyMetadata(raw: GetCurrentKeyData | ListData): NormalizedKeyMetadata {
+  const used = raw.usage ?? raw.usageMonthly ?? 0;
+  const limit = raw.limit ?? undefined;
+  const remaining = raw.limitRemaining ?? undefined;
+
+  let byok: BYOKStatus = '?';
+  if (raw.includeByokInLimit === true) {
+    byok = 'incl';
+  } else if (raw.includeByokInLimit === false) {
+    byok = 'excl';
+  }
+
+  let resetCadence: ResetCadence = 'partial';
+  if (raw.limitReset) {
+    const reset = raw.limitReset.toLowerCase();
+    if (reset === 'monthly') {
+      resetCadence = 'monthly';
+    } else if (reset === 'daily') {
+      resetCadence = 'daily';
+    } else if (reset === 'never') {
+      resetCadence = 'never';
+    }
+  }
+
+  const normalized: NormalizedKeyMetadata = {
+    name: 'name' in raw ? (raw as ListData).name : raw.label,
+    label: raw.label,
+    used,
+    resetCadence,
+    byok,
+    hash: 'hash' in raw ? (raw as ListData).hash : 'unknown',
+    disabled: 'disabled' in raw ? (raw as ListData).disabled : false,
+  };
+
+  if (limit !== undefined) {
+    normalized.limit = limit;
+  }
+  if (remaining !== undefined) {
+    normalized.remaining = remaining;
+  }
+
+  return normalized;
+}

package/extensions/openrouter/overlay.ts

@@ -134,11 +134,13 @@ export class UsageOverlayComponent {
     const th = this.theme;
     const lines: string[] = [];
 
-    if (error) {
+    if (error && !summary) {
       lines.push(boxTop(this.width));
       lines.push(this.getUsageHeaderRow());
       lines.push(emptyRow(this.width));
-      lines.push(row(th.fg('error', error), this.width));
+      for (const errorLine of error.split('\n')) {
+        lines.push(row(th.fg('error', errorLine), this.width));
+      }
       if (cachedMinutesAgo !== null) {
         lines.push(
           row(th.fg('dim', `(last successful fetch: ${cachedMinutesAgo}m ago)`), this.width),
@@ -164,6 +166,19 @@ export class UsageOverlayComponent {
     lines.push(this.getUsageHeaderRow());
     lines.push(emptyRow(this.width));
 
+    if (error) {
+      lines.push(row(th.fg('warning', ' Stale usage data - refresh failed'), this.width));
+      for (const errorLine of error.split('\n')) {
+        lines.push(row(th.fg('dim', ` ${errorLine}`), this.width));
+      }
+      if (cachedMinutesAgo !== null) {
+        lines.push(
+          row(th.fg('dim', ` Last successful fetch: ${cachedMinutesAgo}m ago`), this.width),
+        );
+      }
+      lines.push(emptyRow(this.width));
+    }
+
     // Month row: amount stays with label, cap percentage right-aligned
     const monthLeftBase = ` Month $${fmt(summary.month)} / $${fmt(summary.cap)}`;
     const monthPercent = summary.cap > 0 ? Math.round((summary.month / summary.cap) * 100) : 0;
@@ -190,12 +205,8 @@ export class UsageOverlayComponent {
     }
     lines.push(rowRightAligned(weekLeftBase, weekRight + '  ', this.width));
 
-    // Today row on its own line - shows tilde since from local logs
-    const todayReqStr =
-      summary.local.requests > 0 ? ` · ${fmtCount(summary.local.requests)} reqs` : '';
-    lines.push(
-      rowRightAligned(` Today ~$${fmt(summary.local.cost)}${todayReqStr}`, '  ', this.width),
-    );
+    // Today row on its own line - shows tilde since it may include local tracked usage
+    lines.push(rowRightAligned(` Today ~$${fmt(summary.today)}`, '  ', this.width));
     lines.push(emptyRow(this.width));
 
     // Top models (7d table)

package/extensions/openrouter/session-state.ts

@@ -0,0 +1,110 @@
+import crypto from 'node:crypto';
+import { formatSessionId } from './session.js';
+
+/**
+ * Session state manager for OpenRouter session IDs.
+ * Ensures stable session IDs within a Pi session and proper reset across sessions.
+ */
+export interface SessionState {
+  /**
+   * Get the current session ID, creating one if needed.
+   * The ID is cached and stable for the lifetime of this SessionState instance.
+   */
+  getCurrentSessionId(ctx: { sessionManager: { getSessionId(): string } }): string;
+
+  /**
+   * Handle session_start lifecycle event.
+   * Checks if the raw session ID has changed and updates state accordingly.
+   * - If raw ID differs from cached: reset and format new ID
+   * - If raw ID is same: preserve cached formatted ID
+   * - If raw ID is empty/throws: clear state for fresh fallback
+   */
+  startSession(ctx: { sessionManager: { getSessionId(): string } }): void;
+
+  /**
+   * Reset the cached session ID. Call this on session_shutdown
+   * to ensure fresh IDs for new sessions.
+   */
+  reset(): void;
+
+  /**
+   * Peek at the current cached session ID without initializing one.
+   * Returns null if no session ID has been cached yet.
+   */
+  peek(): string | null;
+}
+
+class SessionStateImpl implements SessionState {
+  private cachedSessionId: string | null = null;
+  private cachedRawSessionId: string | null = null;
+
+  getCurrentSessionId(ctx: { sessionManager: { getSessionId(): string } }): string {
+    if (this.cachedSessionId) {
+      return this.cachedSessionId;
+    }
+
+    try {
+      const sessionId = ctx.sessionManager.getSessionId();
+      let formattedSessionId: string;
+
+      if (sessionId && sessionId !== '') {
+        formattedSessionId = formatSessionId(sessionId);
+        this.cachedRawSessionId = sessionId;
+      } else {
+        // Empty session ID: generate fallback UUID
+        formattedSessionId = formatSessionId(crypto.randomUUID());
+        this.cachedRawSessionId = null;
+      }
+
+      this.cachedSessionId = formattedSessionId;
+      return formattedSessionId;
+    } catch {
+      // Session manager threw error: generate fallback UUID
+      const fallbackId = formatSessionId(crypto.randomUUID());
+      this.cachedSessionId = fallbackId;
+      this.cachedRawSessionId = null;
+      return fallbackId;
+    }
+  }
+
+  startSession(ctx: { sessionManager: { getSessionId(): string } }): void {
+    try {
+      const rawSessionId = ctx.sessionManager.getSessionId();
+
+      if (rawSessionId && rawSessionId !== '') {
+        // Non-empty session ID from manager
+        if (this.cachedRawSessionId !== rawSessionId) {
+          // Raw session ID changed - reset and format new ID
+          this.cachedRawSessionId = rawSessionId;
+          this.cachedSessionId = formatSessionId(rawSessionId);
+        }
+        // else: same raw ID, preserve cached formatted ID
+      } else {
+        // Empty session ID - clear state for fresh fallback
+        this.cachedSessionId = null;
+        this.cachedRawSessionId = null;
+      }
+    } catch {
+      // Session manager threw - clear state for fresh fallback
+      this.cachedSessionId = null;
+      this.cachedRawSessionId = null;
+    }
+  }
+
+  reset(): void {
+    this.cachedSessionId = null;
+    this.cachedRawSessionId = null;
+  }
+
+  peek(): string | null {
+    return this.cachedSessionId;
+  }
+}
+
+/**
+ * Create a new SessionState instance.
+ * Each Pi session should get its own instance.
+ */
+export function createSessionState(): SessionState {
+  return new SessionStateImpl();
+}

package/extensions/openrouter/session.ts

@@ -23,6 +23,22 @@ export function formatSessionId(sessionId: string): string {
 // Detection Logic
 // =============================================================================
 
+/**
+ * Detect whether a provider request should be treated as an OpenRouter request.
+ *
+ * We intentionally use several overlapping signals because Pi events do not always
+ * expose provider metadata in the same place or at the same lifecycle stage.
+ * Different integrations can identify OpenRouter by:
+ * - provider name (`event.provider` or `event.payload.provider`) when Pi resolves it directly
+ * - model prefix (`openrouter/...`) when the request payload keeps the routed model id
+ * - `context.model.baseUrl` when the active model config points at OpenRouter
+ * - `provider.zdr === true` for Shopify's ZDR path that still routes through OpenRouter
+ * - request URL / endpoint as a last fallback for events that only expose transport details
+ *
+ * The checks stay intentionally redundant so session tagging and usage tracking keep
+ * working across request-time and `turn_end`-style event shapes without depending on
+ * a single field being present.
+ */
 export function isOpenRouterRequest(event: BeforeProviderRequestEvent, _ctx: unknown): boolean {
   const ev = event as unknown as Record<string, unknown>;
   const payload = ev['payload'] as Record<string, unknown> | undefined;

package/extensions/openrouter/types.ts

@@ -89,15 +89,34 @@ export interface UsageAggregate {
   cost: number;
 }
 
-export const ZERO_AGGREGATE: UsageAggregate = {
-  requests: 0,
-  promptTokens: 0,
-  completionTokens: 0,
-  reasoningTokens: 0,
-  cacheReadTokens: 0,
-  cacheWriteTokens: 0,
-  cost: 0,
-};
+export function createZeroAggregate(): UsageAggregate {
+  return {
+    requests: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    reasoningTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    cost: 0,
+  };
+}
+
+export function combineUsageAggregates(
+  official: UsageAggregate,
+  local: UsageAggregate,
+): UsageAggregate {
+  return {
+    requests: official.requests + local.requests,
+    promptTokens: official.promptTokens + local.promptTokens,
+    completionTokens: official.completionTokens + local.completionTokens,
+    reasoningTokens: official.reasoningTokens + local.reasoningTokens,
+    cacheReadTokens: official.cacheReadTokens + local.cacheReadTokens,
+    cacheWriteTokens: official.cacheWriteTokens + local.cacheWriteTokens,
+    cost: official.cost + local.cost,
+  };
+}
+
+export const ZERO_AGGREGATE: Readonly<UsageAggregate> = Object.freeze(createZeroAggregate());
 
 export interface CacheEntry<T> {
   data: T;