@vib-rato/ai 0.16.0

package/dist/types/cli.d.ts

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

package/dist/types/codex-tools.d.ts

@@ -0,0 +1,4 @@
+/** Maps a canonical tool name to the name Codex accepts on the wire. */
+export declare function codexToolWireName(name: string): string;
+/** Maps a Codex wire tool name back to the canonical harness tool name. */
+export declare function codexToolCanonicalName(wireName: string): string;

package/dist/types/context-cap-policy.d.ts

@@ -0,0 +1,68 @@
+import type { Api, Model } from "./types";
+/**
+ * Codex GPT-5.6 OAuth context-window policy.
+ *
+ * Authoritative source and ownership path
+ * ---------------------------------------
+ * The authenticated Codex backend discovery endpoint (`GET {base}/codex/models`
+ * with an OAuth bearer token) is the authoritative runtime source of Codex OAuth
+ * model context-window metadata (`models[].context_window`). OpenAI owns that
+ * value; Vibrato consumes it read-only via `fetchCodexModels` and must not silently
+ * invent a larger limit without upstream evidence.
+ *
+ * This bundled policy is a client-side conservative guard, not a primary source.
+ * It exists because OpenAI temporarily reverted the GPT-5.6 Sol product context
+ * limit from 372K to 272K on 2026-07-13 (staff announcement quoted in
+ * vib-rato issues #2240 / #2260), while planning to restore 372K later.
+ * `ceiling` must only be raised with an upstream evidence citation; an
+ * unverified report that "372K is live again" is not sufficient.
+ *
+ * Precedence (highest -> lowest)
+ * ------------------------------
+ * 1. Explicit user per-model override (`contextWindow` in `modelOverrides`).
+ *    The model registry merges it into `model.contextWindow` before this cap and
+ *    passes it here; it is honored when a positive finite number, with
+ *    diagnostics emitted at the registry. Never silently discarded.
+ * 2. Live OAuth discovery metadata (`context_window`), forced to the enforced
+ *    product window for the GPT-5.6 tier.
+ * 3. Bundled conservative generic window (`CODEX_GENERIC_CONTEXT_WINDOW`),
+ *    used when discovery metadata is absent or invalid.
+ */
+export interface CodexGpt56ContextCapPolicy {
+    /**
+     * Usable prompt budget forced for the GPT-5.6 tier on the Codex product
+     * transport. The live OpenAI code backend metadata still reports the old
+     * 272K budget (or the total-window figure), so this is an explicit product
+     * override: the tier is forced to the enforced window regardless of what
+     * discovery reports.
+     */
+    enforced: number;
+}
+export declare const CODEX_GPT_5_6_CONTEXT_CAP: CodexGpt56ContextCapPolicy;
+/**
+ * Generic usable prompt budget for OpenAI code backend models outside the
+ * GPT-5.6 tier (e.g. gpt-5.5, gpt-5.4-codex, gpt-5.6-codex). Kept separate from
+ * {@link CODEX_GPT_5_6_CONTEXT_CAP} so the forced 5.6-tier window never leaks
+ * into unrelated Codex discovery rows.
+ */
+export declare const CODEX_GENERIC_CONTEXT_WINDOW = 272000;
+export declare function isCodexProductTransport(model: Pick<Model<Api>, "api" | "provider">): boolean;
+export declare function isCodexGpt56Tier(model: Pick<Model<Api>, "id">): boolean;
+export declare function codexContextOverrideKey(provider: string, modelId: string): string;
+export declare function resolveCodexGpt56DiscoveryContext(model: Pick<Model<Api>, "api" | "id" | "provider">, rawContextWindow: unknown, policy?: CodexGpt56ContextCapPolicy): number;
+/**
+ * Applies the final Codex GPT-5.6 context ceiling, honoring explicit user
+ * overrides.
+ *
+ * `userContextWindowOverrides` maps provider-qualified composite keys
+ * (`provider:modelId`, both lowercased, built by
+ * {@link codexContextOverrideKey}) to the user's explicit `contextWindow` value
+ * (already merged into `model.contextWindow` by the model registry). A tier
+ * model present with a positive finite value keeps its value even above
+ * `enforced` — the user's explicit, diagnosed choice. Every other tier
+ * model is forced to `enforced`, so a stale larger live/cached observation
+ * (e.g. a pre-rollback 373K cache) cannot resurface without an override.
+ * Because the key is provider-qualified, an override only exempts the exact
+ * provider+model pair it was configured for.
+ */
+export declare function applyFinalCodexGpt56ContextCap<TApi extends Api>(models: readonly Model<TApi>[], policy?: CodexGpt56ContextCapPolicy, userContextWindowOverrides?: ReadonlyMap<string, number>): Model<TApi>[];

package/dist/types/core.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Lightweight public AI runtime surface.
+ *
+ * This entrypoint intentionally exports core types, schemas, model metadata,
+ * stream dispatch, and lazy provider descriptors only. Concrete provider
+ * implementations stay behind `register-builtins` loaders and are not
+ * re-exported here.
+ */
+export { type ZodType, z } from "zod/v4";
+export * from "./api-registry";
+export * from "./auth-broker";
+export * from "./auth-gateway/types";
+export * from "./auth-storage";
+export * from "./codex-tools";
+export * from "./context-cap-policy";
+export * from "./model-cache";
+export * from "./model-manager";
+export * from "./model-thinking";
+export * from "./models";
+export * from "./provider-models";
+export { getProviderRuntimeDescriptor, PROVIDER_RUNTIME_DESCRIPTORS, type ProviderRuntimeDescriptor, } from "./providers/register-builtins";
+export { hasAdjacentPrivateThinkingBlocks } from "./providers/transform-messages";
+export * from "./rate-limit-utils";
+export * from "./stream";
+export * from "./types";
+export * from "./usage";
+export * from "./utils/event-stream";
+export * from "./utils/fallback-transport";
+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/tool-choice-capability";
+export * from "./utils/validation";

package/dist/types/index.d.ts

@@ -0,0 +1,55 @@
+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 "./context-cap-policy";
+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-opencodex-responses";
+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/grok-cli";
+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/fallback-transport";
+export * from "./utils/h2-fetch";
+export * from "./utils/oauth";
+export type { OAuthCredentials, OAuthLoginOptions, OAuthProvider, OAuthProviderId, OAuthProviderInfo, } from "./utils/oauth/types";
+export * from "./utils/overflow";
+export * from "./utils/provider-safety-stop";
+export * from "./utils/retry";
+export * from "./utils/schema";
+export * from "./utils/tool-choice-capability";
+export * from "./utils/validation";

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

@@ -0,0 +1,24 @@
+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;
+    /** IDs returned by the authoritative dynamic provider catalog, when retained. */
+    dynamicModelIds: string[] | undefined;
+    dynamicModelProvenance: string | undefined;
+}
+/** Close the shared cache only when it owns the exact requested database path. */
+export declare function closeModelCache(dbPath?: string): boolean;
+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, dynamicModelIds?: readonly string[], dynamicModelProvenance?: string): void;
+export declare function insertModelCacheIfAbsent<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string, dynamicModelIds?: readonly string[], dynamicModelProvenance?: string): boolean;
+export declare function updateModelCacheIfUnchanged<TApi extends Api>(providerId: string, expectedUpdatedAt: number, expectedDynamicModelIds: readonly string[] | undefined, expectedDynamicModelProvenance: string | undefined, expectedModels: readonly Model<TApi>[], updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string, dynamicModelIds?: readonly string[], dynamicModelProvenance?: string): boolean;
+export {};

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

@@ -0,0 +1,77 @@
+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;
+    /** Optional guard that must permit cache publication. Default: writes are permitted. */
+    canPublishCache?: () => boolean;
+    /** Credential-and-endpoint identity required to reuse dynamic catalog IDs. */
+    cacheDynamicModelProvenance?: string;
+}
+/**
+ * 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;
+    /** Whether the cache row consulted for this resolution was still within its TTL. */
+    cacheFresh: boolean;
+    /** Whether the consulted cache row was authoritative. */
+    cacheAuthoritative: boolean;
+    /** Whether this resolution successfully fetched dynamic models. */
+    fetched: boolean;
+    /**
+     * IDs returned by a current authoritative dynamic provider catalog. This is
+     * deliberately distinct from `models`, which merges static and cached data.
+     */
+    dynamicModelIds?: readonly string[];
+}
+/**
+ * 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-pricing.d.ts

@@ -0,0 +1,3 @@
+import type { Api, Model, ModelCost } from "./types";
+export declare function getOpenAIModelCost<TApi extends Api>(model: Model<TApi>, inputTokens: number): ModelCost | undefined;
+export declare function applyOpenAIModelPricing<TApi extends Api>(model: Model<TApi>): void;

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

@@ -0,0 +1,6 @@
+export declare const RETIRED_MODEL_KEYS: readonly ["google-antigravity/gemini-3.1-pro-high", "google-antigravity/gemini-3.7-flash-high", "google-antigravity/gemini-3.7-flash-low", "google-antigravity/gemini-3.7-flash-medium"];
+export declare function isRetiredModelKey(provider: string, modelId: string): boolean;
+export declare function isRetiredModel(model: {
+    provider: string;
+    id: string;
+}): boolean;

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",
+    Max = "max"
+}
+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">;
+export declare function isGroqCompoundReasoningUnsupported(model: Pick<ApiModel<Api>, "provider" | "id">): boolean;
+/**
+ * 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>;
+/**
+ * Returns whether the configured transport has an audited user-facing reasoning control.
+ *
+ * Custom OpenAI-compatible endpoints fail closed: declaring a model as reasoning-capable
+ * is not enough to prove that the proxy accepts OpenAI reasoning parameters. Unknown
+ * endpoints must opt in with `compat.supportsReasoningEffort: true`; providers using a
+ * non-OpenAI request shape must also declare `compat.thinkingFormat`. Bundled providers
+ * remain governed by their catalog and compatibility metadata.
+ */
+export declare function modelSupportsReasoningControl<TApi extends Api>(model: ApiModel<TApi>, resolvedBaseUrl?: string): boolean;
+/**
+ * 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:
+ * - `OpenAI code backend-spark` variants promote to `gpt-5.5`.
+ *
+ * `gpt-5.5` itself is a 1M-context model and is not demoted to `gpt-5.4`
+ * (which has a smaller window), so it has no promotion target.
+ */
+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;
+/**
+ * Adaptive thinking `display` is supported starting with Anthropic Opus 4.7.
+ * Older adaptive-thinking models (Opus 4.6, Sonnet 4.6+) reject the field.
+ * Fable (5+) postdates Opus 4.7, accepts `display`, and defaults it to
+ * "omitted" — thinking tokens are billed but no content streams back — so it
+ * must opt in like Opus 4.7+ (issue #2791).
+ *
+ * Shares `hasOpus47ApiRestrictions` version parsing on purpose: the two
+ * predicates describe the same API generation, and a private `claude-opus-(\d+)-(\d+)`
+ * regex silently disagreed with it for single-component aliases (`claude-opus-5`
+ * matched nothing while `claude-opus-5-20260101` matched), so the same model sent
+ * a different thinking shape and beta set depending on which id string was used.
+ * Bedrock region/inference-profile prefixes are handled by the canonical parser.
+ */
+export declare function supportsAnthropicAdaptiveThinkingDisplay(modelId: string): boolean;

package/dist/types/models.d.ts

@@ -0,0 +1,21 @@
+import type { Api, KnownProvider, Model, Usage } from "./types";
+/**
+ * Static bundled model registry loaded lazily from `models.json`.
+ *
+ * This module intentionally exposes compile-time defaults only.
+ * It does not include runtime discovery, models.dev overlays, or on-disk cache state.
+ *
+ * For runtime-aware resolution, use `createModelManager()` / `resolveProviderModels()`.
+ */
+type BundledCatalog = typeof import("./models.json");
+export type GeneratedProvider = keyof BundledCatalog;
+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;
+export {};

package/dist/types/openai-completions-compat.d.ts

@@ -0,0 +1,34 @@
+import type { Model, OpenAICompat } from "./types";
+type ResolvedToolStrictMode = NonNullable<OpenAICompat["toolStrictMode"]> | "mixed";
+/** Returns whether the request endpoint is an audited reasoning-control transport. */
+export declare function isAuditedOpenAIReasoningTransport(model: {
+    provider: string;
+    baseUrl?: string;
+}, resolvedBaseUrl?: string): boolean;
+export type ResolvedOpenAICompat = Required<Omit<OpenAICompat, "openRouterRouting" | "vercelGatewayRouting" | "extraBody" | "toolStrictMode" | "toolChoiceSupport" | "supportsResponsesSessionAffinity" | "supportsServiceTier" | "reservedToolNames">> & {
+    openRouterRouting?: OpenAICompat["openRouterRouting"];
+    vercelGatewayRouting?: OpenAICompat["vercelGatewayRouting"];
+    extraBody?: OpenAICompat["extraBody"];
+    toolStrictMode: ResolvedToolStrictMode;
+    supportsResponsesSessionAffinity?: OpenAICompat["supportsResponsesSessionAffinity"];
+    supportsServiceTier?: OpenAICompat["supportsServiceTier"];
+    /** Optional explicit capability override; resolved via deriveToolChoiceSupport. */
+    toolChoiceSupport?: OpenAICompat["toolChoiceSupport"];
+};
+/**
+ * Detect compatibility settings from provider and baseUrl for known providers.
+ * Provider takes precedence over URL-based detection since it's explicitly configured.
+ * @param model - The model configuration
+ * @param resolvedBaseUrl - Optional resolved base URL (e.g., after GitHub Copilot proxy-ep resolution).
+ *                           If provided, this takes precedence over model.baseUrl for URL-based checks.
+ */
+export declare function detectOpenAICompat(model: Model<"openai-completions">, resolvedBaseUrl?: string): ResolvedOpenAICompat;
+/**
+ * Resolve compatibility settings by layering explicit model.compat overrides onto
+ * the detected defaults. This is the canonical compat view for both metadata and transport.
+ * @param model - The model configuration
+ * @param resolvedBaseUrl - Optional resolved base URL (e.g., after GitHub Copilot proxy-ep resolution).
+ *                           If provided, this takes precedence over model.baseUrl for URL-based checks.
+ */
+export declare function resolveOpenAICompat(model: Model<"openai-completions">, resolvedBaseUrl?: string): ResolvedOpenAICompat;
+export {};

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,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 code provider) 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,20 @@
+import type { ModelManagerOptions } from "../model-manager";
+export interface GoogleModelManagerConfig {
+    apiKey?: string;
+    baseUrl?: 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";

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">;