Agents/Providers/ — Multi-Model Provider Adapters

Multi-Provider Auth Rotation Model Fallback Error Categorization

Contents

Architecture

flowchart TD
  subgraph Resolution["Model Resolution"]
    HOOK["resolveHookModelSelection()\nHook-based model override"]
    RUNTIME["resolveEffectiveRuntimeModel()\nContext window calculation"]
    REG["model.ts\nModel registry & lookup"]
  end
  subgraph Auth["Auth & Credential Layer"]
    PROF["auth-profiles.ts\nProfile ordering & cooldown"]
    HEALTH["auth-health.ts\nAuthProfileHealth status"]
    SYNC["external CLI sync\nTTL-based refresh"]
  end
  subgraph Selection["Provider Selection"]
    NORM["model.provider-normalization.ts\nProvider ID normalization"]
    EXTRA["extra-params.ts\nProvider-specific parameters"]
    CAPS["openrouter-model-capabilities.ts\nCapability flags"]
  end
  subgraph Adapters["Provider Adapters"]
    OAI["OpenAI Adapter"]
    ANT["Anthropic Adapter"]
    GEM["Google/Gemini Adapter"]
    BED["AWS Bedrock Adapter"]
    MOON["Moonshot Adapter"]
    MINI["Minimax Adapter"]
    OR["OpenRouter Adapter"]
    ZAI["Z AI Adapter"]
    PROXY["Proxy Adapter"]
  end
  subgraph Sanitize["Schema Sanitization"]
    CLEAN["cleanForGemini()\nJSON Schema cleanup"]
    KEYWORDS["GEMINI_UNSUPPORTED_SCHEMA_KEYWORDS"]
  end
  subgraph Fallback["Fallback & Recovery"]
    FB["model-fallback.ts\nCascading fallback chain"]
    ERR["FallbackSummaryError\nAll models exhausted"]
  end
  HOOK --> RUNTIME
  RUNTIME --> REG
  REG --> NORM
  NORM --> Auth
  Auth --> Selection
  Selection --> Adapters
  Adapters --> Sanitize
  Adapters --> Fallback
  Fallback -->|retry| Selection

Auth Profile State Machine

stateDiagram-v2
  [*] --> Valid
  Valid --> Cooldown : API error received
  Cooldown --> ValidProbe : soonestCooldownExpiry passes
  ValidProbe --> Valid : Probe succeeds
  ValidProbe --> Cooldown : Probe fails
  Valid --> Expired : Credential expires
  Expired --> Valid : Manual refresh / CLI sync
  Cooldown --> Expired : Credential expires during cooldown
  note right of Cooldown : Tracks (now, expiry) per profile
  note right of Valid : AuthProfileHealth = ok

Key Classes & Functions

Data Structures

Interactions

Configuration

Error Categorization

The fallback engine classifies provider errors into categories that determine retry behavior:

Provider Capability Matrix

Directory Map

pi-embedded-runner/
├── model.ts                                  ← Central model registry (~24KB)
├── model.provider-normalization.ts           ← Provider ID normalization
├── model-fallback.ts                         ← Cascading model fallback logic
├── auth-profiles.ts                          ← Auth profile ordering & cooldown
├── auth-health.ts                            ← AuthProfileHealth enum
├── extra-params.ts                           ← Provider-specific parameters
├── openrouter-model-capabilities.ts          ← OpenRouter capability flags
├── schema/
│   └── clean-for-gemini.ts                   ← Gemini JSON Schema sanitizer
├── openai-stream-wrappers.ts                 ← OpenAI adapter
├── anthropic-cache-retention.ts              ← Anthropic adapter
├── google-stream-wrappers.ts                 ← Google/Gemini adapter
├── bedrock-stream-wrappers.ts                ← AWS Bedrock adapter
├── moonshot-stream-wrappers.ts               ← Moonshot adapter
├── minimax-stream-wrappers.ts                ← Minimax adapter
├── proxy-stream-wrappers.ts                  ← Generic proxy adapter
├── zai-stream-wrappers.ts                    ← Z AI adapter
└── run/
    └── setup.ts                              ← Model resolution functions

Deep-Dive Highlights

Core provider mechanisms have been extracted into dedicated focus pages for in-depth exploration. Each page covers one aspect of the provider adapter layer with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: FallbackSummaryError Construction

// When all models in the fallback chain fail, FallbackSummaryError
// aggregates every per-model error into one structured report.
import { FallbackSummaryError } from './model-fallback';

const perModelErrors = [
  { model: 'openai/gpt-4o',       error: 'rate_limit',      status: 429 },
  { model: 'anthropic/claude-3.5', error: 'auth_expired',    status: 401 },
  { model: 'google/gemini-pro',    error: 'context_overflow', status: 400 },
];

throw new FallbackSummaryError(
  `All ${perModelErrors.length} fallback models exhausted`,
  perModelErrors,           // per-model error details
  'openai/gpt-4o',         // original requested model
  3,                        // total attempts
);
// FallbackSummaryError.perModelErrors gives structured access
// to each failure for logging and user-facing diagnostics.

Example: Auth Profile Ordering Logic

// resolveAuthProfileOrder() sorts credentials so the agent
// always tries the healthiest key first.
import { resolveAuthProfileOrder } from './auth-profiles';

const profiles = await resolveAuthProfileOrder('openai');
// Returns profiles sorted by:
//   1. AuthProfileHealth.ok        — fully healthy, preferred
//   2. AuthProfileHealth.expiring  — near expiry, usable
//   3. AuthProfileHealth.static    — static key, no refresh
//   4. (skipped) expired / missing — excluded from rotation
//
// Each profile tracks `soonestCooldownExpiry` so the system
// knows when to re-probe a previously failed credential.

for (const profile of profiles) {
  if (profile.cooldownExpiry && profile.cooldownExpiry > Date.now()) {
    continue; // still in cooldown, skip
  }
  return profile; // use first available
}
// If none available: trigger EXTERNAL_CLI_SYNC_TTL_MS refresh
// (900_000 ms = 15 min TTL) then retry.

Example: Gemini Schema Sanitization

import { cleanForGemini, GEMINI_UNSUPPORTED_SCHEMA_KEYWORDS } from './schema/clean-for-gemini';

// GEMINI_UNSUPPORTED_SCHEMA_KEYWORDS includes:
// '$ref', 'allOf', 'oneOf', 'anyOf', 'not', 'if', 'then', 'else', ...

const toolSchema = {
  type: 'object',
  properties: {
    query: { type: 'string', minLength: 1 },
    filter: { oneOf: [{ type: 'string' }, { type: 'number' }] },
  },
  $ref: '#/definitions/SearchParams',
};

const cleaned = cleanForGemini(toolSchema);
// Result: { type: 'object', properties: { query: { type: 'string' }, filter: {} } }
// '$ref', 'oneOf', and 'minLength' stripped — Gemini cannot process them.