@oh-my-pi/pi-ai 15.1.1 → 15.1.2

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [15.1.2] - 2026-05-15
+### Breaking Changes
+
+- Rejected draft-07 tuple and dependency keywords (`items` arrays, `dependencies`, `additionalItems`) in JSON Schema validation
+
+### Added
+
+- Added `responseHeaders`, `responseStatus`, and `responseRequestId` fields to `MockResponse` so mock providers can provide synthetic `ProviderResponseMetadata`
+- Added `onResponse` metadata emission for mocks that sends lowercased headers and a default status of 200 before streaming when response headers are configured
+- Added recursive strict-mode sanitization for array `prefixItems` entries so tuple schemas now enforce object constraints per item
+
+### Changed
+
+- Normalized legacy draft-07 JSON Schema constructs used in tool parameters (`items` arrays, `additionalItems`, `definitions`, `dependencies`) to draft 2020-12 before OpenAI/Google/CCA sanitization, wire conversion, and argument validation
+- Reworked OpenAI response schema adaptation to rewrite `oneOf` into `anyOf` while preserving existing `anyOf` branches
+- Changed tuple array validation to validate per-index schemas from `prefixItems` and apply `items` only to remaining elements
+
+### Fixed
+
+- Fixed validation of plain JSON Schema tool arguments that omitted a `$schema` URI so draft-07-shaped schemas now pass validation instead of being rejected
+- Fixed tuple-array validation for legacy JSON Schema tool schemas to enforce `additionalItems: false` and per-position constraints after automatic draft upgrade
+- Fixed Anthropic tool schema normalization to recurse into `prefixItems` so unsupported constraints inside tuple items are stripped in the generated input schema
+- Fixed Anthropic tool-schema normalization stripping the body of explicit open `additionalProperties` (e.g. Zod's `z.record(z.string(), z.unknown())` compiling to `additionalProperties: {}`) by unconditionally overwriting it with `false`, which closed record-style fields and prevented models from supplying any key. The coding-agent's `resolve` tool exposes plan-approval titles via such a field, so Kimi K2 (and any other Anthropic-shaped provider) could not pass `extra: { title }`, blocking plan mode entirely ([#1104](https://github.com/can1357/oh-my-pi/issues/1104))
+- Fixed Anthropic strict tool planning to leave tools with open `additionalProperties` maps non-strict instead of sending schemas Anthropic rejects.
+
 ## [15.1.0] - 2026-05-15
 
 ### Breaking Changes

package/dist/types/api-registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Custom API provider registry.
+ *
+ * Allows extensions to register streaming functions for custom API types
+ * (e.g., "vertex-claude-api") that are not built into stream.ts.
+ */
+import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions, StreamOptions } from "./types";
+export type CustomStreamFn = (model: Model<Api>, context: Context, options?: StreamOptions) => AssistantMessageEventStream;
+export type CustomStreamSimpleFn = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+export interface RegisteredCustomApi {
+    stream: CustomStreamFn;
+    streamSimple: CustomStreamSimpleFn;
+    sourceId?: string;
+}
+/**
+ * Register a custom API streaming function.
+ */
+export declare function registerCustomApi(api: string, streamSimple: CustomStreamSimpleFn, sourceId?: string, stream?: CustomStreamFn): void;
+/**
+ * Get a custom API provider by API identifier.
+ */
+export declare function getCustomApi(api: string): RegisteredCustomApi | undefined;
+/**
+ * Remove all custom APIs registered by a specific source (e.g., extension path).
+ */
+export declare function unregisterCustomApis(sourceId: string): void;
+/**
+ * Clear all custom API registrations.
+ */
+export declare function clearCustomApis(): void;

package/dist/types/auth-storage.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Credential storage for API keys and OAuth tokens.
+ * Handles loading, saving, refreshing credentials, and usage tracking.
+ *
+ * This module defines:
+ * - `AuthCredentialStore` interface: abstracting persistence (SQLite, memory, etc.)
+ * - `AuthStorage` class: credential management with round-robin, usage limits, OAuth refresh
+ * - `AuthCredentialStore`: concrete SQLite-backed implementation
+ */
+import { Database } from "bun:sqlite";
+import type { Provider } from "./types";
+import type { CredentialRankingStrategy, UsageLogger, UsageProvider, UsageReport } from "./usage";
+import type { OAuthController, OAuthCredentials, OAuthProviderId } from "./utils/oauth/types";
+export type ApiKeyCredential = {
+    type: "api_key";
+    key: string;
+};
+export type OAuthCredential = {
+    type: "oauth";
+} & OAuthCredentials;
+export type AuthCredential = ApiKeyCredential | OAuthCredential;
+export type AuthCredentialEntry = AuthCredential | AuthCredential[];
+export type AuthStorageData = Record<string, AuthCredentialEntry>;
+/**
+ * Serialized representation of AuthStorage for passing to subagent workers.
+ * Contains only the essential credential data, not runtime state.
+ */
+export interface SerializedAuthStorage {
+    credentials: Record<string, Array<{
+        id: number;
+        type: "api_key" | "oauth";
+        data: Record<string, unknown>;
+    }>>;
+    runtimeOverrides?: Record<string, string>;
+    dbPath?: string;
+}
+/**
+ * Auth credential with database row ID for updates/deletes.
+ * Wraps AuthCredential with storage metadata.
+ */
+export interface StoredAuthCredential {
+    id: number;
+    provider: string;
+    credential: AuthCredential;
+    disabledCause: string | null;
+}
+/**
+ * Event payload describing a credential that was just soft-disabled.
+ *
+ * Today the only call site is OAuth refresh failures with a definitive cause
+ * (`invalid_grant`, `401/403` not from a network blip, etc.) — the
+ * disabled_cause string is the verbatim error captured for forensics.
+ *
+ * Subscribers can use this to surface a notification, banner, or auto-launch
+ * a re-login flow instead of letting the credential silently disappear.
+ */
+export interface CredentialDisabledEvent {
+    provider: string;
+    disabledCause: string;
+}
+export type AuthStorageOptions = {
+    usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
+    rankingStrategyResolver?: (provider: Provider) => CredentialRankingStrategy | undefined;
+    usageFetch?: typeof fetch;
+    usageRequestTimeoutMs?: number;
+    usageLogger?: UsageLogger;
+    /**
+     * Resolve a config value (API key, header value, etc.) to an actual value.
+     * - coding-agent injects its resolveConfigValue (supports "!command" syntax via pi-natives)
+     * - Default: checks environment variable first, then treats as literal
+     */
+    configValueResolver?: (config: string) => Promise<string | undefined>;
+    /**
+     * Optional callback fired when AuthStorage automatically disables a
+     * credential because something detected it as no longer usable — today
+     * that's the OAuth refresh-failure path in `getApiKey`. NOT fired for
+     * user-initiated `remove()` (the user already knows) or dedup of
+     * duplicate credentials (uninteresting hygiene).
+     */
+    onCredentialDisabled?: (event: CredentialDisabledEvent) => void | Promise<void>;
+};
+type AuthApiKeyOptions = {
+    baseUrl?: string;
+    modelId?: string;
+};
+/**
+ * Credential storage backed by an AuthCredentialStore.
+ * Reads from storage on reload(), manages round-robin credential selection,
+ * usage limit tracking, and OAuth token refresh.
+ */
+export declare class AuthStorage {
+    #private;
+    constructor(store: AuthCredentialStore, options?: AuthStorageOptions);
+    /**
+     * Create an AuthStorage instance backed by a AuthCredentialStore.
+     * Convenience factory for standalone use (e.g., pi-ai CLI).
+     * @param dbPath - Path to SQLite database
+     */
+    static create(dbPath: string, options?: AuthStorageOptions): Promise<AuthStorage>;
+    /**
+     * Close the underlying credential store.
+     *
+     * After calling this, the instance must not be reused.
+     */
+    close(): void;
+    /**
+     * Subscribe to {@link CredentialDisabledEvent}s. Multiple subscribers are supported and
+     * each fires for every disable event; subscribers are invoked in registration order with
+     * exceptions and async rejections isolated per-listener so a misbehaving subscriber
+     * cannot break the disable path or starve the rest of the chain.
+     *
+     * If `credential_disabled` events were emitted while no listener was subscribed, they are
+     * replayed (in insertion order) to the listener that triggers the empty→non-empty
+     * transition. The drain is one-shot — listeners that subscribe after that no longer see
+     * past events.
+     *
+     * Returns an unsubscribe function. The function is idempotent: calling it more than once
+     * is a no-op. After every subscriber has unsubscribed, subsequent disable events buffer
+     * again until the next subscribe.
+     *
+     * @param listener Callback invoked with each disable event. May be sync or async.
+     * @returns A function that removes this listener from the subscriber set.
+     */
+    onCredentialDisabled(listener: (event: CredentialDisabledEvent) => void | Promise<void>): () => void;
+    /**
+     * Set a runtime API key override (not persisted to disk).
+     * Used for CLI --api-key flag.
+     */
+    setRuntimeApiKey(provider: string, apiKey: string): void;
+    /**
+     * Remove a runtime API key override.
+     */
+    removeRuntimeApiKey(provider: string): void;
+    /**
+     * Set a fallback resolver for API keys not found in storage or env vars.
+     * Used for custom provider keys from models.json.
+     */
+    setFallbackResolver(resolver: (provider: string) => string | undefined): void;
+    /**
+     * Reload credentials from storage.
+     */
+    reload(): Promise<void>;
+    /**
+     * Get credential for a provider (first entry if multiple).
+     */
+    get(provider: string): AuthCredential | undefined;
+    /**
+     * Set credential for a provider.
+     */
+    set(provider: string, credential: AuthCredentialEntry): Promise<void>;
+    /**
+     * Remove credential for a provider.
+     */
+    remove(provider: string): Promise<void>;
+    /**
+     * List all providers with credentials.
+     */
+    list(): string[];
+    /**
+     * Check if credentials exist for a provider in storage.
+     */
+    has(provider: string): boolean;
+    /**
+     * Check if any form of auth is configured for a provider.
+     * Unlike getApiKey(), this doesn't refresh OAuth tokens.
+     */
+    hasAuth(provider: string): boolean;
+    /**
+     * Check if OAuth credentials are configured for a provider.
+     */
+    hasOAuth(provider: string): boolean;
+    /**
+     * Get OAuth credentials for a provider.
+     */
+    getOAuthCredential(provider: string): OAuthCredential | undefined;
+    /**
+     * Get the OAuth `accountId` for a provider, preferring the credential that is
+     * session-sticky for `sessionId` when multiple OAuth credentials are configured.
+     * Falls back to the first OAuth credential when no session preference exists (e.g.
+     * first call before any `getApiKey` has been issued, or single-credential setups).
+     * Returns `undefined` when no OAuth credential carries an `accountId`.
+     */
+    getOAuthAccountId(provider: string, sessionId?: string): string | undefined;
+    /**
+     * Get all credentials.
+     */
+    getAll(): AuthStorageData;
+    /**
+     * Login to an OAuth provider.
+     */
+    login(provider: OAuthProviderId, ctrl: OAuthController & {
+        /** onAuth is required by auth-storage but optional in OAuthController */
+        onAuth: (info: {
+            url: string;
+            instructions?: string;
+        }) => void;
+        /** onPrompt is required for some providers (github-copilot, openai-codex) */
+        onPrompt: (prompt: {
+            message: string;
+            placeholder?: string;
+        }) => Promise<string>;
+    }): Promise<void>;
+    /**
+     * Logout from a provider.
+     */
+    logout(provider: string): Promise<void>;
+    fetchUsageReports(options?: {
+        baseUrlResolver?: (provider: Provider) => string | undefined;
+    }): Promise<UsageReport[] | null>;
+    /**
+     * Marks the current session's credential as temporarily blocked due to usage limits.
+     * Uses usage reports to determine accurate reset time when available.
+     * Returns true if a credential was blocked, enabling automatic fallback to the next credential.
+     */
+    markUsageLimitReached(provider: string, sessionId: string | undefined, options?: {
+        retryAfterMs?: number;
+        baseUrl?: string;
+    }): Promise<boolean>;
+    /**
+     * Peek at API key for a provider without refreshing OAuth tokens.
+     * Used for model discovery where we only need to know if credentials exist
+     * and get a best-effort token. For GitHub Copilot we preserve enterprise
+     * routing metadata so discovery can hit the correct host.
+     */
+    peekApiKey(provider: string): Promise<string | undefined>;
+    /**
+     * Get API key for a provider.
+     * Priority:
+     * 1. Runtime override (CLI --api-key)
+     * 2. API key from storage
+     * 3. OAuth token from storage (auto-refreshed)
+     * 4. Environment variable
+     * 5. Fallback resolver (models.json custom providers)
+     */
+    getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
+}
+/**
+ * Standalone SQLite-backed implementation of AuthCredentialStore interface.
+ * Used by the pi-ai CLI and as the default store for AuthStorage.create().
+ * Also has convenience methods for simple CRUD (saveOAuth, getOAuth, etc.).
+ */
+export declare class AuthCredentialStore {
+    #private;
+    constructor(db: Database);
+    static open(dbPath?: string): Promise<AuthCredentialStore>;
+    listAuthCredentials(provider?: string): StoredAuthCredential[];
+    replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
+    upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
+    updateAuthCredential(id: number, credential: AuthCredential): void;
+    deleteAuthCredential(id: number, disabledCause: string): void;
+    /**
+     * CAS-style disable: only soft-deletes the row when its `data` column still
+     * matches `expectedData` and the row has not already been disabled. Used by
+     * the OAuth refresh-failure path to avoid clobbering a peer that rotated the
+     * row between our pre-check and the disable.
+     */
+    tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string): boolean;
+    deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
+    getCache(key: string): string | null;
+    setCache(key: string, value: string, expiresAtSec: number): void;
+    cleanExpiredCache(): void;
+    /**
+     * Save OAuth credentials for a provider.
+     * Preserves unrelated identities and replaces only the matching credential.
+     */
+    saveOAuth(provider: string, credentials: OAuthCredentials): void;
+    /**
+     * Get OAuth credentials for a provider.
+     */
+    getOAuth(provider: string): OAuthCredentials | null;
+    /**
+     * Save API key for a provider (replaces existing).
+     */
+    saveApiKey(provider: string, apiKey: string): void;
+    /**
+     * Get API key for a provider.
+     */
+    getApiKey(provider: string): string | null;
+    /**
+     * List all providers with credentials.
+     */
+    listProviders(): string[];
+    /**
+     * Delete all credentials for a provider.
+     */
+    deleteProvider(provider: string): void;
+    close(): void;
+}
+export {};

package/dist/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,44 @@
+export { type ZodType, z } from "zod/v4";
+export * from "./api-registry";
+export * from "./auth-storage";
+export * from "./model-cache";
+export * from "./model-manager";
+export * from "./model-thinking";
+export * from "./models";
+export * from "./provider-details";
+export * from "./provider-models";
+export * from "./providers/anthropic";
+export * from "./providers/azure-openai-responses";
+export type * from "./providers/cursor";
+export * from "./providers/gitlab-duo";
+export type * from "./providers/google";
+export type * from "./providers/google-gemini-cli";
+export * from "./providers/google-gemini-headers";
+export type * from "./providers/google-vertex";
+export * from "./providers/kimi";
+export * from "./providers/mock";
+export * from "./providers/ollama";
+export * from "./providers/openai-codex-responses";
+export * from "./providers/openai-completions";
+export * from "./providers/openai-responses";
+export * from "./providers/synthetic";
+export * from "./rate-limit-utils";
+export * from "./stream";
+export * from "./types";
+export * from "./usage";
+export * from "./usage/claude";
+export * from "./usage/gemini";
+export * from "./usage/github-copilot";
+export * from "./usage/google-antigravity";
+export * from "./usage/kimi";
+export * from "./usage/minimax-code";
+export * from "./usage/openai-codex";
+export * from "./usage/zai";
+export * from "./utils/anthropic-auth";
+export * from "./utils/discovery";
+export * from "./utils/event-stream";
+export * from "./utils/h2-fetch";
+export * from "./utils/overflow";
+export * from "./utils/retry";
+export * from "./utils/schema";
+export * from "./utils/validation";

package/dist/types/model-cache.d.ts

@@ -0,0 +1,10 @@
+import type { Api, Model } from "./types";
+interface CacheEntry<TApi extends Api = Api> {
+    models: Model<TApi>[];
+    fresh: boolean;
+    authoritative: boolean;
+    updatedAt: number;
+}
+export declare function readModelCache<TApi extends Api>(providerId: string, ttlMs: number, now: () => number, dbPath?: string): CacheEntry<TApi> | null;
+export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, dbPath?: string): void;
+export {};

package/dist/types/model-manager.d.ts

@@ -0,0 +1,62 @@
+import type { Api, Model, Provider } from "./types";
+/**
+ * Controls when dynamic endpoint models should be fetched.
+ */
+export type ModelRefreshStrategy = "online" | "offline" | "online-if-uncached";
+/**
+ * Hook for loading and mapping models.dev fallback data into canonical model objects.
+ */
+export interface ModelsDevFallback<TApi extends Api = Api, TPayload = unknown> {
+    /** Fetches raw fallback payload (for example from models.dev). */
+    fetch(): Promise<TPayload>;
+    /** Maps payload into provider models. */
+    map(payload: TPayload, providerId: Provider): readonly Model<TApi>[];
+}
+/**
+ * Configuration for provider model resolution.
+ */
+export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload = unknown> {
+    /** Provider id used for static lookup and cache namespacing. */
+    providerId: Provider;
+    /** Optional static list override. When omitted, bundled models.json is used. */
+    staticModels?: readonly Model<TApi>[];
+    /** Optional override for the cache database path. Default: <agent-dir>/models.db. */
+    cacheDbPath?: string;
+    /** Maximum cache age in milliseconds before considered stale. Default: 24h. */
+    cacheTtlMs?: number;
+    /** Optional dynamic endpoint fetcher. */
+    fetchDynamicModels?: () => Promise<readonly Model<TApi>[] | null>;
+    /** Optional models.dev fallback hook. */
+    modelsDev?: ModelsDevFallback<TApi, TModelsDevPayload>;
+    /** Clock override for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Resolution result.
+ *
+ * `stale` is false when the resolved catalog is authoritative for the selected provider:
+ * - dynamic endpoint data was fetched in this call,
+ * - a still-fresh authoritative cache was reused in `online-if-uncached` mode, or
+ * - the provider has no dynamic fetcher configured.
+ */
+export interface ModelResolutionResult<TApi extends Api = Api> {
+    models: Model<TApi>[];
+    stale: boolean;
+}
+/**
+ * Stateful facade over provider model resolution.
+ */
+export interface ModelManager<TApi extends Api = Api> {
+    refresh(strategy?: ModelRefreshStrategy): Promise<ModelResolutionResult<TApi>>;
+}
+/**
+ * Creates a reusable provider model manager.
+ */
+export declare function createModelManager<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>): ModelManager<TApi>;
+/**
+ * Resolves provider models with source precedence:
+ * static -> models.dev -> cache -> dynamic.
+ *
+ * Later sources override earlier ones by model id.
+ */
+export declare function resolveProviderModels<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>, strategy?: ModelRefreshStrategy): Promise<ModelResolutionResult<TApi>>;

package/dist/types/model-thinking.d.ts

@@ -0,0 +1,71 @@
+import type { Api, Model as ApiModel } from "./types";
+/** User-facing thinking levels, ordered least to most intensive. */
+export declare const enum Effort {
+    Minimal = "minimal",
+    Low = "low",
+    Medium = "medium",
+    High = "high",
+    XHigh = "xhigh"
+}
+export declare const THINKING_EFFORTS: readonly Effort[];
+/**
+ * Static fallback model injected when Cloudflare AI Gateway discovery
+ * returns no results. Ensures the provider always has at least one usable
+ * model entry in the catalog.
+ */
+export declare const CLOUDFLARE_FALLBACK_MODEL: ApiModel<"anthropic-messages">;
+/**
+ * Returns a copy of the model with canonical thinking metadata attached.
+ *
+ * This helper belongs to catalog enrichment only. Runtime consumers should
+ * trust `model.thinking` and avoid inferring capabilities on demand.
+ */
+export declare function enrichModelThinking<TApi extends Api>(model: ApiModel<TApi>): ApiModel<TApi>;
+/**
+ * Returns a copy of the model with thinking metadata recomputed from the
+ * canonical rules, replacing any existing `thinking`.
+ */
+export declare function refreshModelThinking<TApi extends Api>(model: ApiModel<TApi>): ApiModel<TApi>;
+/**
+ * Apply upstream metadata corrections to a mutable array of models.
+ *
+ * Each model is first normalized through `refreshModelThinking()` so generated
+ * catalogs keep canonical thinking metadata and policy fixes in one pass.
+ */
+export declare function applyGeneratedModelPolicies(models: ApiModel<Api>[]): void;
+/**
+ * Link OpenAI model variants to their context promotion targets.
+ *
+ * When a model's context is exhausted, the agent can promote to a sibling
+ * model with a larger context window on the same provider:
+ * - `codex-spark` variants promote to `gpt-5.5`.
+ * - `gpt-5.5` (270K input) promotes to `gpt-5.4` (1M input).
+ */
+export declare function linkOpenAIPromotionTargets(models: ApiModel<Api>[]): void;
+/**
+ * Returns the supported thinking efforts declared on the model metadata.
+ *
+ * Catalog enrichment is responsible for normalizing bundled model metadata up front.
+ * Runtime callers must treat explicit `model.thinking` on custom models as authoritative
+ * so proxy-specific overrides from `models.yml` survive request construction.
+ *
+ * @throws Error when a reasoning-capable model is missing thinking metadata
+ */
+export declare function getSupportedEfforts<TApi extends Api>(model: ApiModel<TApi>): readonly Effort[];
+/**
+ * Clamps a requested thinking level against explicit model metadata.
+ *
+ * Non-reasoning models always resolve to `undefined`.
+ */
+export declare function clampThinkingLevelForModel<TApi extends Api>(model: ApiModel<TApi> | undefined, requested: Effort | undefined): Effort | undefined;
+export declare function requireSupportedEffort<TApi extends Api>(model: ApiModel<TApi>, effort: Effort): Effort;
+/** Maps a normalized thinking effort to Google's `thinkingLevel` enum values. */
+export declare function mapEffortToGoogleThinkingLevel<TApi extends Api>(model: ApiModel<TApi>, effort: Effort): "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+/** Maps a normalized thinking effort to Anthropic adaptive effort values. */
+export declare function mapEffortToAnthropicAdaptiveEffort<TApi extends Api>(model: ApiModel<TApi>, effort: Effort): "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Returns true for Anthropic models with Opus 4.7 API restrictions:
+ * - Sampling parameters (temperature/top_p/top_k) return 400 error
+ * - Thinking content is omitted by default (needs display: "summarized")
+ */
+export declare function hasOpus47ApiRestrictions(modelId: string): boolean;

package/dist/types/models.d.ts

@@ -0,0 +1,12 @@
+import MODELS from "./models.json";
+import type { Api, KnownProvider, Model, Usage } from "./types";
+export type GeneratedProvider = keyof typeof MODELS;
+export declare function getBundledModel<TApi extends Api = Api>(provider: GeneratedProvider, modelId: string): Model<TApi>;
+export declare function getBundledProviders(): KnownProvider[];
+export declare function getBundledModels(provider: GeneratedProvider): Model<Api>[];
+export declare function calculateCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"];
+/**
+ * Check if two models are equal by comparing both their id and provider.
+ * Returns false if either model is null or undefined.
+ */
+export declare function modelsAreEqual<TApi extends Api>(a: Model<TApi> | null | undefined, b: Model<TApi> | null | undefined): boolean;

package/dist/types/provider-details.d.ts

@@ -0,0 +1,18 @@
+import type { Api, Model, Provider, ProviderSessionState } from "./types";
+export interface ProviderDetailField {
+    label: string;
+    value: string;
+}
+export interface ProviderDetails {
+    provider: Provider;
+    api: Api;
+    fields: ProviderDetailField[];
+}
+export interface ProviderDetailsContext {
+    model: Model<Api>;
+    sessionId?: string;
+    authMode?: string;
+    preferWebsockets?: boolean;
+    providerSessionState?: Map<string, ProviderSessionState>;
+}
+export declare function getProviderDetails(context: ProviderDetailsContext): ProviderDetails;

package/dist/types/provider-models/bundled-references.d.ts

@@ -0,0 +1,4 @@
+import { getBundledModels } from "../models";
+import type { Api, Model } from "../types";
+export declare function createBundledReferenceMap<TApi extends Api>(provider: Parameters<typeof getBundledModels>[0]): Map<string, Model<TApi>>;
+export declare function createReferenceResolver<TApi extends Api>(providerRefs: Map<string, Model<TApi>>): (modelId: string) => Model<TApi> | undefined;

package/dist/types/provider-models/descriptors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Unified provider descriptors — single source of truth for provider metadata
+ * used by both runtime model discovery (model-registry.ts) and catalog
+ * generation (generate-models.ts).
+ */
+import type { ModelManagerOptions } from "../model-manager";
+import type { Api, KnownProvider } from "../types";
+import type { OAuthProvider } from "../utils/oauth/types";
+/** Catalog discovery configuration for providers that support endpoint-based model listing. */
+export interface CatalogDiscoveryConfig {
+    /** Human-readable name for log messages. */
+    label: string;
+    /** Environment variables to check for API keys during catalog generation. */
+    envVars: string[];
+    /** OAuth provider for credential refresh during catalog generation. */
+    oauthProvider?: OAuthProvider;
+    /** When true, catalog discovery proceeds even without credentials. */
+    allowUnauthenticated?: boolean;
+}
+/** Unified provider descriptor used by both runtime discovery and catalog generation. */
+export interface ProviderDescriptor {
+    providerId: KnownProvider;
+    createModelManagerOptions(config: {
+        apiKey?: string;
+        baseUrl?: string;
+    }): ModelManagerOptions<Api>;
+    /** Preferred model ID when no explicit selection is made. */
+    defaultModel: string;
+    /** When true, the runtime creates a model manager even without a valid API key (e.g. ollama). */
+    allowUnauthenticated?: boolean;
+    /** Catalog discovery configuration. Only providers with this field participate in generate-models.ts. */
+    catalogDiscovery?: CatalogDiscoveryConfig;
+}
+/** A provider descriptor that has catalog discovery configured. */
+export type CatalogProviderDescriptor = ProviderDescriptor & {
+    catalogDiscovery: CatalogDiscoveryConfig;
+};
+/** Type guard for descriptors with catalog discovery. */
+export declare function isCatalogDescriptor(d: ProviderDescriptor): d is CatalogProviderDescriptor;
+/** Whether catalog discovery may run without provider credentials. */
+export declare function allowsUnauthenticatedCatalogDiscovery(descriptor: CatalogProviderDescriptor): boolean;
+/**
+ * All standard providers. Special providers (google-antigravity, google-gemini-cli,
+ * openai-codex) are handled separately because they require different config shapes.
+ */
+export declare const PROVIDER_DESCRIPTORS: readonly ProviderDescriptor[];
+/** Default model IDs for all known providers, built from descriptors + special providers. */
+export declare const DEFAULT_MODEL_PER_PROVIDER: Record<KnownProvider, string>;

package/dist/types/provider-models/google.d.ts

@@ -0,0 +1,19 @@
+import type { ModelManagerOptions } from "../model-manager";
+export interface GoogleModelManagerConfig {
+    apiKey?: string;
+}
+export interface GoogleVertexModelManagerConfig {
+    apiKey?: string;
+}
+export interface GoogleAntigravityModelManagerConfig {
+    oauthToken?: string;
+    endpoint?: string;
+}
+export interface GoogleGeminiCliModelManagerConfig {
+    oauthToken?: string;
+    endpoint?: string;
+}
+export declare function googleModelManagerOptions(config?: GoogleModelManagerConfig): ModelManagerOptions<"google-generative-ai">;
+export declare function googleVertexModelManagerOptions(_config?: GoogleVertexModelManagerConfig): ModelManagerOptions<"google-vertex">;
+export declare function googleAntigravityModelManagerOptions(config?: GoogleAntigravityModelManagerConfig): ModelManagerOptions<"google-gemini-cli">;
+export declare function googleGeminiCliModelManagerOptions(config?: GoogleGeminiCliModelManagerConfig): ModelManagerOptions<"google-gemini-cli">;

package/dist/types/provider-models/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./descriptors";
+export * from "./google";
+export * from "./ollama";
+export * from "./openai-compat";
+export * from "./special";