@prometheus-ai/ai 0.5.0

package/dist/types/index.d.ts

@@ -0,0 +1,49 @@
+export { type ZodType, z } from "zod/v4";
+export * from "./api-registry";
+export * from "./auth-broker";
+export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
+export * from "./auth-gateway/types";
+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/anthropic-client";
+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/oauth";
+export type { OAuthCredentials, OAuthProvider, OAuthProviderId, OAuthProviderInfo, } from "./utils/oauth/types";
+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,17 @@
+import type { Api, Model } from "./types";
+interface CacheEntry<TApi extends Api = Api> {
+    models: Model<TApi>[];
+    fresh: boolean;
+    authoritative: boolean;
+    updatedAt: number;
+    /**
+     * Hash of the static catalog slice that was merged into `models` when this
+     * row was written. `resolveProviderModels` compares against the current
+     * static fingerprint and bypasses the static+cache re-merge when they
+     * match — the cache already incorporates the same static state.
+     */
+    staticFingerprint: string;
+}
+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, staticFingerprint: string, dbPath?: string): void;
+export {};

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

@@ -0,0 +1,64 @@
+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;
+    /** When true, a successful dynamic fetch is the complete provider catalog and prunes static-only models. */
+    dynamicModelsAuthoritative?: boolean;
+    /** 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,100 @@
+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;
+/**
+ * True when the model reasons natively but rejects the wire `reasoning.effort`
+ * param (compat.supportsReasoningEffort: false on openai-responses*). Callers
+ * are expected to omit the effort field; the wire-side omitReasoningEffort
+ * gate (providers/xai-responses.ts:78) is the actual strip, and this
+ * predicate is the upstream check that prevents a redundant
+ * requireSupportedEffort throw from defeating that gate.
+ *
+ * Scoped to openai-responses* because that's the only API surface where
+ * `compat.supportsReasoningEffort: false` is meaningful today. The
+ * `in`-narrowed access is necessary because Model.compat is
+ * `AnthropicCompat | OpenAICompat` and the api gate doesn't narrow the
+ * union for TS.
+ */
+export declare function modelOmitsReasoningEffort<TApi extends Api>(model: ApiModel<TApi>): boolean;
+/**
+ * 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;
+/**
+ * Mid-conversation `role: "system"` messages (system instructions appended at
+ * non-first positions in the `messages` array) are supported starting with
+ * Claude Opus 4.8. Earlier Claude models reject the role.
+ * @see https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
+ */
+export declare function supportsMidConversationSystemMessages(modelId: string): boolean;
+/**
+ * Claude Opus 4.8 must emit at most one tool call per turn: the Anthropic
+ * Messages provider sends `tool_choice.disable_parallel_tool_use = true` for
+ * this model. Scoped to exactly 4.8 — earlier and later Opus versions keep
+ * Anthropic's default parallel tool-calling.
+ */
+export declare function disablesParallelToolUse(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,24 @@
+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;
+    /**
+     * Human-readable description of the active credential, e.g.
+     * `"broker http://can.internal:8765 · oauth #5 (foo@bar.com)"`.
+     * Rendered as a `Source` field; omitted when undefined.
+     */
+    credentialSource?: 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,50 @@
+/**
+ * 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;
+    /** When true, successful runtime discovery replaces bundled provider models instead of merging fallback-only IDs. */
+    dynamicModelsAuthoritative?: 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,24 @@
+import type { ModelManagerOptions } from "../model-manager";
+import type { FetchImpl } from "../types";
+export interface GoogleModelManagerConfig {
+    apiKey?: string;
+}
+export interface GoogleVertexModelManagerConfig {
+    apiKey?: string;
+    project?: string;
+    location?: string;
+    signal?: AbortSignal;
+    fetch?: FetchImpl;
+}
+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;
+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";

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

@@ -0,0 +1,7 @@
+import type { ModelManagerOptions } from "../model-manager";
+export interface OllamaCloudModelManagerConfig {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export declare function normalizeOllamaCloudBaseUrl(baseUrl?: string): string;
+export declare function ollamaCloudModelManagerOptions(config?: OllamaCloudModelManagerConfig): ModelManagerOptions<"ollama-chat">;