@animus-labs/cortex 0.2.2 → 0.2.3

package/src/cortex-agent.ts

@@ -26,7 +26,9 @@ import type { PiEventSource } from './event-bridge.js';
 import { BudgetGuard } from './budget-guard.js';
 import { classifyError } from './error-classifier.js';
 import { parseWorkingTags } from './working-tags.js';
-import { UTILITY_MODEL_DEFAULTS } from './provider-registry.js';
+import { getModel as getPiModel, getModels as getPiModels } from '@earendil-works/pi-ai';
+import { UTILITY_MODEL_OVERRIDES } from './provider-registry.js';
+import { inferUtilityModel } from './utility-model-inference.js';
 import { McpClientManager } from './mcp-client.js';
 import { CompactionManager, buildCompactionConfig } from './compaction/index.js';
 import { isContextOverflow } from './compaction/failsafe.js';
@@ -2863,6 +2865,25 @@ export class CortexAgent {
    * If 'default' or undefined, look up the provider default and preserve
    * the raw provider-specific fields from the primary pi-ai model.
    */
+  private inferDefaultUtilityModel(provider: string): PiModel | null {
+    const overrideModelId = UTILITY_MODEL_OVERRIDES[provider];
+    if (overrideModelId) {
+      try {
+        const overrideModel = (getPiModel as unknown as (provider: string, modelId: string) => unknown)(provider, overrideModelId);
+        if (overrideModel) return overrideModel as PiModel;
+      } catch {
+        return null;
+      }
+    }
+
+    try {
+      const models = (getPiModels as unknown as (provider: string) => PiModel[])(provider);
+      return inferUtilityModel(models as unknown as Array<Record<string, unknown>>) as PiModel | null;
+    } catch {
+      return null;
+    }
+  }
+
   private resolveUtilityModels(
     primaryModel: CortexModel,
     primaryPiModel: PiModel,
@@ -2874,26 +2895,24 @@ export class CortexAgent {
     const primaryProvider = primaryModel.provider;
 
     if (!utilityModelConfig || utilityModelConfig === 'default') {
-      const defaultModelId = UTILITY_MODEL_DEFAULTS[primaryProvider];
-      if (!defaultModelId) {
+      const utilityPiModel = this.inferDefaultUtilityModel(primaryProvider);
+      if (!utilityPiModel) {
         return {
           utilityModel: primaryModel,
           utilityPiModel: primaryPiModel,
         };
       }
 
-      const utilityPiModel = {
-        ...primaryPiModel,
-        name: defaultModelId,
-        id: defaultModelId,
-      };
+      const rawUtilityId = utilityPiModel['id'];
+      const rawUtilityName = utilityPiModel['name'];
+      const utilityModelId = typeof rawUtilityId === 'string' ? rawUtilityId : String(rawUtilityId ?? rawUtilityName);
 
       return {
         utilityPiModel,
         utilityModel: wrapModel(
           utilityPiModel,
           primaryProvider,
-          defaultModelId,
+          utilityModelId,
           utilityPiModel.contextWindow ?? primaryModel.contextWindow,
         ),
       };

package/src/index.ts

@@ -260,11 +260,13 @@ export type {
 // Model Wrapper (Phase 1D)
 export { wrapModel, unwrapModel, isCortexModel } from './model-wrapper.js';
 export type { CortexModel } from './model-wrapper.js';
+export { inferUtilityModel, inferUtilityModelId } from './utility-model-inference.js';
 
 // Provider Registry (Phase 1D)
 export {
   PROVIDER_REGISTRY,
   OAUTH_PROVIDER_IDS,
+  UTILITY_MODEL_OVERRIDES,
   UTILITY_MODEL_DEFAULTS,
   PRIMARY_MODEL_DEFAULTS,
   PROVIDER_CACHE_CONFIG,

package/src/provider-manager.ts

@@ -17,13 +17,14 @@
 import {
   PROVIDER_REGISTRY,
   OAUTH_PROVIDER_IDS,
-  UTILITY_MODEL_DEFAULTS,
+  UTILITY_MODEL_OVERRIDES,
 } from './provider-registry.js';
 import { createRequire } from 'node:module';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { ThinkingLevel } from './types.js';
 import type { ProviderInfo, ModelInfo } from './provider-registry.js';
 import { wrapModel } from './model-wrapper.js';
+import { inferUtilityModelId } from './utility-model-inference.js';
 import type { CortexModel } from './model-wrapper.js';
 
 const nodeRequire = createRequire(import.meta.url);
@@ -639,10 +640,12 @@ function mapRawToModelInfo(
     supportsThinking: supportedThinkingLevels.some(level => level !== 'off')
       || !!(raw['supportsThinking'] || raw['reasoning']),
     supportedThinkingLevels,
-    supportsImages: !!raw['supportsImages'],
+    supportsImages: Array.isArray(raw['input'])
+      ? raw['input'].includes('image')
+      : !!raw['supportsImages'],
   };
 
-  const rawPricing = raw['pricing'];
+  const rawPricing = raw['pricing'] ?? raw['cost'];
   if (rawPricing && typeof rawPricing === 'object') {
     const pricing = rawPricing as Record<string, unknown>;
     const inputPrice = pricing['input'];
@@ -830,32 +833,31 @@ export class ProviderManager implements IProviderManager {
   async validateApiKey(provider: string, apiKey: string): Promise<ApiKeyValidationResult> {
     const piAi = await loadPiAi();
 
-    // Find the cheapest model for this provider to minimize validation cost
-    const cheapestModelId = this.getSmallestModelId(provider);
-    if (!cheapestModelId) {
-      // No known model, try a generic test with the provider's first model
-      const models = piAi.getModels(provider);
-      if (models.length === 0) {
-        return {
-          provider,
-          modelId: null,
-          valid: false,
-          retryable: false,
-          status: 'resolution_error',
-          message: `No models found for provider "${provider}"`,
-        };
-      }
-      const firstRawId = models[0]!['id'];
-      const firstRawName = models[0]!['name'];
-      const firstModelId = typeof firstRawId === 'string'
-        ? firstRawId
-        : typeof firstRawName === 'string'
-          ? firstRawName
-          : String(firstRawId ?? firstRawName);
-      return this.tryValidation(piAi, provider, firstModelId, apiKey);
+    const models = piAi.getModels(provider) ?? [];
+    if (models.length === 0) {
+      return {
+        provider,
+        modelId: null,
+        valid: false,
+        retryable: false,
+        status: 'resolution_error',
+        message: `No models found for provider "${provider}"`,
+      };
+    }
+
+    const modelId = this.getSmallestModelId(provider, models);
+    if (!modelId) {
+      return {
+        provider,
+        modelId: null,
+        valid: false,
+        retryable: false,
+        status: 'resolution_error',
+        message: `No usable models found for provider "${provider}"`,
+      };
     }
 
-    return this.tryValidation(piAi, provider, cheapestModelId, apiKey);
+    return this.tryValidation(piAi, provider, modelId, apiKey);
   }
 
   /**
@@ -948,11 +950,10 @@ export class ProviderManager implements IProviderManager {
   // -----------------------------------------------------------------------
 
   /**
-   * Get the cheapest known model ID for a provider.
-   * Uses the UTILITY_MODEL_DEFAULTS as a proxy for "smallest model."
+   * Get the cheapest likely utility model ID for a provider.
    */
-  private getSmallestModelId(provider: string): string | null {
-    return UTILITY_MODEL_DEFAULTS[provider] ?? null;
+  private getSmallestModelId(provider: string, models: Array<Record<string, unknown>>): string | null {
+    return UTILITY_MODEL_OVERRIDES[provider] ?? inferUtilityModelId(models);
   }
 
   /**

package/src/provider-registry.ts

@@ -4,7 +4,7 @@
  * This module contains:
  * 1. PROVIDER_REGISTRY: metadata for all known providers (auth methods, env vars, key prefixes)
  * 2. OAUTH_PROVIDER_IDS: the subset of providers that support OAuth
- * 3. UTILITY_MODEL_DEFAULTS: per-provider cheapest-capable model for utility operations
+ * 3. UTILITY_MODEL_OVERRIDES: per-provider utility model overrides for inference exceptions
  *
  * OAuth flows are resolved through pi-ai's OAuth provider registry at runtime.
  *
@@ -270,17 +270,9 @@ export const OAUTH_PROVIDER_IDS: string[] = [
 ];
 
 // ---------------------------------------------------------------------------
-// Utility Model Defaults
+// Model Defaults
 // ---------------------------------------------------------------------------
 
-/**
- * Default utility model IDs per provider.
- * Used when utilityModel is 'default' or undefined.
- *
- * These are the cheapest capable models for each provider,
- * suitable for internal operations like WebFetch summarization
- * and safety classification.
- */
 /**
  * Default primary model IDs per provider.
  * Used when a user first connects a provider and no model is explicitly selected.
@@ -289,21 +281,22 @@ export const OAUTH_PROVIDER_IDS: string[] = [
 export const PRIMARY_MODEL_DEFAULTS: Record<string, string> = {
   anthropic: 'claude-sonnet-4-6',
   openai: 'gpt-5.4',
+  'openai-codex': 'gpt-5.5',
   google: 'gemini-3.1-pro-preview',
+  xai: 'grok-4',
   groq: 'openai/gpt-oss-120b',
   cerebras: 'gpt-oss-120b',
   mistral: 'mistral-large-2512',
 };
 
-export const UTILITY_MODEL_DEFAULTS: Record<string, string> = {
-  anthropic: 'claude-haiku-4-5-20251001',     // $1.00/$5.00 per 1M tokens
-  openai: 'gpt-4.1-nano',                     // $0.10/$0.40 per 1M tokens
-  'openai-codex': 'gpt-5.4-mini',            // Current small Codex-capable model
-  google: 'gemini-2.5-flash-lite',            // $0.10/$0.40 per 1M tokens
-  groq: 'llama-3.1-8b-instant',              // ~$0.05/$0.08 per 1M tokens
-  cerebras: 'llama3.1-8b',                    // ~$0.10/$0.10 per 1M tokens
-  mistral: 'mistral-small-2506',             // $0.06/$0.18 per 1M tokens
-};
+/**
+ * Per-provider utility model overrides for inference exceptions.
+ * Leave empty unless dynamic inference picks a bad utility model for a provider.
+ */
+export const UTILITY_MODEL_OVERRIDES: Record<string, string> = {};
+
+/** Backwards-compatible alias. Prefer UTILITY_MODEL_OVERRIDES for new code. */
+export const UTILITY_MODEL_DEFAULTS = UTILITY_MODEL_OVERRIDES;
 
 // ---------------------------------------------------------------------------
 // Cache Retention

package/src/utility-model-inference.ts

@@ -0,0 +1,203 @@
+type RawModel = Record<string, unknown>;
+
+const MIN_UTILITY_CONTEXT_WINDOW = 32_000;
+
+const SPECIAL_PURPOSE_MODEL_PATTERN = /(?:embedding|embed|rerank|moderation|whisper|tts|audio|speech|image-generation|vision|live|deep-research|safety|safeguard|guard|search|transcrib)/i;
+
+const UTILITY_TERMS: Array<{ pattern: RegExp; score: number }> = [
+  { pattern: /(?:^|[\s._/-])flash[\s._/-]?lite(?:$|[\s._/-])/, score: 110 },
+  { pattern: /(?:^|[\s._/-])nano(?:$|[\s._/-])/, score: 100 },
+  { pattern: /(?:^|[\s._/-])mini(?:$|[\s._/-])/, score: 95 },
+  { pattern: /(?:^|[\s._/-])haiku(?:$|[\s._/-])/, score: 95 },
+  { pattern: /(?:^|[\s._/-])small(?:$|[\s._/-])/, score: 85 },
+  { pattern: /(?:^|[\s._/-])fast(?:$|[\s._/-])/, score: 80 },
+  { pattern: /(?:^|[\s._/-])spark(?:$|[\s._/-])/, score: 80 },
+  { pattern: /(?:^|[\s._/-])instant(?:$|[\s._/-])/, score: 75 },
+  { pattern: /(?:^|[\s._/-])lite(?:$|[\s._/-])/, score: 70 },
+  { pattern: /(?:^|[\s._/-])flash(?:$|[\s._/-])/, score: 65 },
+  { pattern: /(?:^|[\s._/-])(?:7|8)b(?:$|[\s._/-])/, score: 65 },
+  { pattern: /(?:^|[\s._/-])(?:12|20)b(?:$|[\s._/-])/, score: 45 },
+  { pattern: /(?:^|[\s._/-])32b(?:$|[\s._/-])/, score: 25 },
+];
+
+interface UtilityCandidate {
+  model: RawModel;
+  id: string;
+  name: string;
+  utilityScore: number;
+  recencyScore: number;
+  costScore: number;
+}
+
+export function inferUtilityModel(models: readonly RawModel[] | null | undefined): RawModel | null {
+  if (!Array.isArray(models)) return null;
+
+  const capable = models
+    .map(toUtilityCandidate)
+    .filter((candidate): candidate is UtilityCandidate => candidate !== null);
+
+  const utilityCandidates = capable.filter(candidate => candidate.utilityScore > 0);
+  if (utilityCandidates.length > 0) {
+    return [...utilityCandidates].sort(compareUtilityCandidates)[0]!.model;
+  }
+  if (capable.length === 0) return null;
+
+  return [...capable].sort(compareFallbackCandidates)[0]!.model;
+}
+
+export function inferUtilityModelId(models: readonly RawModel[] | null | undefined): string | null {
+  const model = inferUtilityModel(models);
+  const id = model?.['id'];
+  if (typeof id === 'string') return id;
+  const name = model?.['name'];
+  return typeof name === 'string' ? name : null;
+}
+
+function toUtilityCandidate(model: RawModel): UtilityCandidate | null {
+  const id = getString(model['id']) ?? getString(model['name']);
+  if (!id) return null;
+
+  const name = getString(model['name']) ?? id;
+  const searchable = `${id} ${name}`.toLowerCase();
+  if (SPECIAL_PURPOSE_MODEL_PATTERN.test(searchable)) return null;
+
+  if (!supportsText(model)) return null;
+
+  const contextWindow = getNumber(model['contextWindow']) ?? 0;
+  if (contextWindow > 0 && contextWindow < MIN_UTILITY_CONTEXT_WINDOW) return null;
+
+  return {
+    model,
+    id,
+    name,
+    utilityScore: inferUtilityScore(searchable),
+    recencyScore: inferRecencyScore(searchable),
+    costScore: inferCostScore(model),
+  };
+}
+
+function compareUtilityCandidates(a: UtilityCandidate, b: UtilityCandidate): number {
+  if (b.recencyScore !== a.recencyScore) return b.recencyScore - a.recencyScore;
+  if (a.costScore !== b.costScore) return a.costScore - b.costScore;
+  if (b.utilityScore !== a.utilityScore) return b.utilityScore - a.utilityScore;
+  return a.id.localeCompare(b.id);
+}
+
+function compareFallbackCandidates(a: UtilityCandidate, b: UtilityCandidate): number {
+  if (a.costScore !== b.costScore) return a.costScore - b.costScore;
+  if (b.recencyScore !== a.recencyScore) return b.recencyScore - a.recencyScore;
+  return a.id.localeCompare(b.id);
+}
+
+function supportsText(model: RawModel): boolean {
+  const input = model['input'];
+  if (!Array.isArray(input)) return true;
+  return input.includes('text');
+}
+
+function inferUtilityScore(searchable: string): number {
+  let score = 0;
+  for (const term of UTILITY_TERMS) {
+    if (term.pattern.test(searchable)) {
+      score = Math.max(score, term.score);
+    }
+  }
+  return score;
+}
+
+function inferRecencyScore(searchable: string): number {
+  const dateScore = inferDateScore(searchable);
+  const versionScore = inferVersionScore(searchable);
+  return Math.max(dateScore, versionScore);
+}
+
+function inferDateScore(searchable: string): number {
+  let score = 0;
+
+  for (const match of searchable.matchAll(/20\d{6}/g)) {
+    const value = Number(match[0]);
+    if (isValidDateScore(value)) {
+      score = Math.max(score, value);
+    }
+  }
+
+  for (const match of searchable.matchAll(/(20\d{2})[-_/](0[1-9]|1[0-2])/g)) {
+    score = Math.max(score, Number(match[1]) * 10_000 + Number(match[2]) * 100);
+  }
+
+  for (const match of searchable.matchAll(/(0[1-9]|1[0-2])[-_/](20\d{2})/g)) {
+    score = Math.max(score, Number(match[2]) * 10_000 + Number(match[1]) * 100);
+  }
+
+  for (const match of searchable.matchAll(/(?:^|[^\d])(\d{4})(?:$|[^\da-z])/g)) {
+    const raw = match[1]!;
+    const year = Number(raw.slice(0, 2));
+    const month = Number(raw.slice(2, 4));
+    if (year >= 20 && year <= 40 && month >= 1 && month <= 12) {
+      score = Math.max(score, 20_000_000 + year * 10_000 + month * 100);
+    }
+  }
+
+  return score;
+}
+
+function inferVersionScore(searchable: string): number {
+  const scrubbed = searchable
+    .replace(/20\d{6}/g, ' ')
+    .replace(/(20\d{2})[-_/](0[1-9]|1[0-2])/g, ' ')
+    .replace(/(0[1-9]|1[0-2])[-_/](20\d{2})/g, ' ')
+    .replace(/(?:^|[^\d])(\d{4})(?:$|[^\da-z])/g, ' ')
+    .replace(/\b\d+(?:\.\d+)?b\b/g, ' ');
+
+  let score = 0;
+  for (const match of scrubbed.matchAll(/\d+(?:\.\d+)+/g)) {
+    score = Math.max(score, scoreVersionParts(match[0]!.split('.').map(Number)));
+  }
+
+  const tokens = scrubbed.split(/[^a-z0-9]+/).filter(Boolean);
+  for (let i = 0; i < tokens.length; i++) {
+    if (!/^\d+$/.test(tokens[i]!)) continue;
+    const parts: number[] = [];
+    for (let j = i; j < tokens.length && /^\d+$/.test(tokens[j]!) && parts.length < 4; j++) {
+      parts.push(Number(tokens[j]));
+    }
+    if (parts.length >= 2) {
+      score = Math.max(score, scoreVersionParts(parts));
+    }
+  }
+
+  return score;
+}
+
+function scoreVersionParts(parts: number[]): number {
+  const weights = [1_000_000, 10_000, 100, 1];
+  return parts.slice(0, weights.length).reduce((score, part, index) => (
+    Number.isFinite(part) ? score + part * weights[index]! : score
+  ), 0);
+}
+
+function inferCostScore(model: RawModel): number {
+  const cost = model['cost'] ?? model['pricing'];
+  if (!cost || typeof cost !== 'object') return Number.MAX_SAFE_INTEGER;
+
+  const rawCost = cost as RawModel;
+  const input = getNumber(rawCost['input']) ?? 0;
+  const output = getNumber(rawCost['output']) ?? 0;
+  if (input === 0 && output === 0) return Number.MAX_SAFE_INTEGER - 1;
+  return input + output * 3;
+}
+
+function isValidDateScore(value: number): boolean {
+  const year = Math.floor(value / 10_000);
+  const month = Math.floor((value % 10_000) / 100);
+  const day = value % 100;
+  return year >= 2020 && year <= 2040 && month >= 1 && month <= 12 && day >= 1 && day <= 31;
+}
+
+function getString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function getNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}