jeopi-cli 16.2.14 → 16.2.15

package/dist/types/config/model-registry.d.ts

@@ -0,0 +1,251 @@
+import type { Api, Context, Model, ModelSpec, RemoteCompactionConfig, SimpleStreamOptions, ThinkingConfig } from "jeopi-ai/types";
+import type { AssistantMessageEventStream } from "jeopi-ai/utils/event-stream";
+import { type ModelRefreshStrategy } from "jeopi-catalog/model-manager";
+import type { ApiKeyResolver, FetchImpl } from "jeopi-ai";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "jeopi-ai/oauth/types";
+import type { AuthStorage } from "../session/auth-storage";
+import { type ApiKeyResolverModel, type ApiKeyResolverOptions } from "./api-key-resolver";
+import type { ConfigError } from "./config-file";
+export declare const kNoAuth = "N/A";
+export declare function isAuthenticated(apiKey: string | undefined | null): apiKey is string;
+/** Provider override config (baseUrl, headers, apiKey, compat, transport) without custom models */
+interface ProviderOverride {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    apiKey?: string;
+    authHeader?: boolean;
+    compat?: ModelSpec<Api>["compat"];
+    remoteCompaction?: RemoteCompactionConfig<Api>;
+    transport?: Model<Api>["transport"];
+}
+/**
+ * Merge a freshly discovered model with the matching bundled/configured entry
+ * (or a runtime provider override when no bundled entry exists).
+ *
+ * `baseUrl` resolution priority:
+ *   1. User-set `providerOverride.baseUrl` (explicit override in models.json)
+ *   2. Discovered baseUrl (xiaomi `tp-` token-plan keys resolve to
+ *      `token-plan-sgp.xiaomimimo.com` at discovery time)
+ *   3. Existing bundled baseUrl (the host baked into `models.json`)
+ *
+ * `transport` resolution priority:
+ *   1. `providerOverride.transport` (e.g. `pi-native` for auth-gateway users)
+ *   2. `existing.transport` (carried over from boot-time override application)
+ *   3. `model.transport` (rarely set — discovery defaults omit it)
+ *
+ * Without (1), the user's override would lose to discovery; without (2)
+ * preferred over (3), the bundled `api.xiaomimimo.com` would shadow the
+ * tp- token-plan host and produce 401s on the first stream call.
+ * Without explicit transport propagation, an openrouter (or any) entry
+ * marked `transport: pi-native` in models.yml silently reverts to the
+ * default openai-completions transport after the background catalog
+ * refresh — so the first `/model` switch after boot hits the raw OpenAI
+ * chat-completions URL instead of the gateway's `/v1/pi/stream` (#2555).
+ * See `xiaomi-tp-discovery-merge.test.ts` and the `refresh()` baseUrl-override
+ * regression in `model-registry.test.ts`.
+ */
+export declare function mergeDiscoveredModel<TApi extends Api>(model: Model<TApi>, existing: Model<Api> | undefined, providerOverride?: Pick<ProviderOverride, "baseUrl" | "headers" | "remoteCompaction" | "transport">): Model<TApi>;
+export type ProviderDiscoveryStatus = "idle" | "ok" | "empty" | "cached" | "unavailable" | "unauthenticated";
+export interface ProviderDiscoveryState {
+    provider: string;
+    status: ProviderDiscoveryStatus;
+    optional: boolean;
+    stale: boolean;
+    fetchedAt?: number;
+    models: string[];
+    error?: string;
+}
+/**
+ * Model registry - loads and manages models, resolves API keys via AuthStorage.
+ */
+export declare class ModelRegistry {
+    #private;
+    readonly authStorage: AuthStorage;
+    /**
+     * @param authStorage - Auth storage for API key resolution
+     *
+     * Sync constructor — eagerly loads bundled + cached models so tests and
+     * synchronous callers see a fully-populated registry immediately. Production
+     * boot paths SHOULD prefer {@link ModelRegistry.create} so the YAML/JSONC
+     * migration step lands off the event loop's hot path before the first
+     * `tryLoad()` runs.
+     */
+    constructor(authStorage: AuthStorage, modelsPath?: string, options?: {
+        fetch?: FetchImpl;
+    });
+    /**
+     * Reload models from disk (built-in + custom from models.json).
+     */
+    refresh(strategy?: ModelRefreshStrategy): Promise<void>;
+    refreshInBackground(strategy?: ModelRefreshStrategy): void;
+    refreshProvider(providerId: string, strategy?: ModelRefreshStrategy): Promise<void>;
+    /**
+     * Refresh dynamic metadata that can appear only after a local model loads.
+     */
+    refreshSelectedModelMetadata(model: Model<Api>): Promise<Model<Api>>;
+    /**
+     * Discover models for providers registered at runtime via `fetchDynamicModels`
+     * (extension providers). Merges the discovered catalog into the existing model
+     * set without reloading static models, so dynamically-discovered models from
+     * other providers are preserved. No-op when no runtime providers are registered.
+     *
+     * Drives the same SQLite model cache as built-in providers, so the default
+     * `online-if-uncached` strategy fetches at most once per cache TTL (24 h).
+     */
+    refreshRuntimeProviders(strategy?: ModelRefreshStrategy): Promise<void>;
+    /**
+     * Get any error from loading models.json (undefined if no error).
+     */
+    getError(): ConfigError | undefined;
+    /**
+     * Get all models (built-in + custom).
+     * If models.json had errors, returns only built-in models.
+     */
+    getAll(): Model<Api>[];
+    /**
+     * Get only models that have auth configured.
+     * This is a fast check that doesn't refresh OAuth tokens.
+     */
+    getAvailable(): Model<Api>[];
+    /**
+     * Check whether auth is configured for a model's provider.
+     *
+     * Mirrors the upstream `@mariozechner/pi-coding-agent` API surface so that
+     * external plugins/extensions and downstream wrappers (e.g. subagent launch
+     * paths that pre-flight auth before model resolution) can probe a model
+     * without resolving an API key. Returns true for keyless providers as well
+     * as providers with stored credentials. See issue #993.
+     *
+     * Side-effect-free and synchronous: a command-backed key (`!cmd`) counts as
+     * configured by its presence alone — the program is NOT executed — and OAuth
+     * tokens are NOT refreshed (`authStorage.hasAuth`). This is what keeps the
+     * model-switch pre-flight off the event loop's hot path; the real key
+     * (command execution + OAuth refresh) is resolved lazily per request via
+     * {@link ModelRegistry.resolver}.
+     */
+    hasConfiguredAuth(model: Model<Api>): boolean;
+    getDiscoverableProviders(): string[];
+    getProviderDiscoveryState(provider: string): ProviderDiscoveryState | undefined;
+    /**
+     * Find a model by provider and ID.
+     */
+    find(provider: string, modelId: string): Model<Api> | undefined;
+    /**
+     * Get the base URL associated with a provider, if any model defines one.
+     */
+    getProviderBaseUrl(provider: string): string | undefined;
+    /**
+     * Get API key for a model.
+     */
+    getApiKey(model: Model<Api>, sessionId?: string): Promise<string | undefined>;
+    /**
+     * Get API key for a provider (e.g., "openai").
+     *
+     * `options.forceRefresh` powers step (b) of the auth-retry policy — it
+     * re-mints the session-sticky OAuth token even when the cached copy still
+     * looks valid. `options.signal` is threaded into any broker-bound refresh.
+     */
+    getApiKeyForProvider(provider: string, sessionId?: string, options?: {
+        baseUrl?: string;
+        modelId?: string;
+        forceRefresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | undefined>;
+    /**
+     * Build an {@link ApiKeyResolver} implementing the central a/b/c auth-retry
+     * policy. Accepts a provider id with options, or a model with an optional
+     * session id (`resolver(model, sessionId)`) which derives `baseUrl`/`modelId`
+     * from the model. Callers that need the initial key for a guard can call
+     * `resolveApiKeyOnce(resolver)`.
+     */
+    resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
+    resolver(model: ApiKeyResolverModel, sessionId?: string): ApiKeyResolver;
+    /**
+     * Check if a model is using OAuth credentials (subscription).
+     */
+    isUsingOAuth(model: Model<Api>): boolean;
+    /**
+     * Remove custom API/OAuth registrations for a specific extension source.
+     */
+    clearSourceRegistrations(sourceId: string): void;
+    /**
+     * Remove registrations for extension sources that are no longer active.
+     */
+    syncExtensionSources(activeSourceIds: string[]): void;
+    /**
+     * Register a provider dynamically (from extensions).
+     *
+     * If provider has models: replaces all existing models for this provider.
+     * If provider has only baseUrl/headers: overrides existing models' URLs.
+     * If provider has streamSimple: registers a custom API streaming function.
+     * If provider has oauth: registers OAuth provider for /login support.
+     */
+    registerProvider(providerName: string, config: ProviderConfigInput, sourceId?: string): void;
+    /**
+     * Suppress a specific model selector (e.g., "provider/id") until a specific timestamp.
+     */
+    suppressSelector(selector: string, untilMs: number): void;
+    /**
+     * Check if a model selector is currently suppressed due to rate limits.
+     */
+    isSelectorSuppressed(selector: string): boolean;
+    /**
+     * Clear all cooldown suppressions recorded via {@link suppressSelector}.
+     * Used to reset retry-fallback cooldown state without a full {@link refresh}.
+     */
+    clearSuppressedSelectors(): void;
+}
+/**
+ * Input type for registerProvider API (from extensions).
+ */
+export interface ProviderConfigInput {
+    baseUrl?: string;
+    apiKey?: string;
+    api?: Api;
+    streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+    headers?: Record<string, string>;
+    compat?: ModelSpec<Api>["compat"];
+    remoteCompaction?: RemoteCompactionConfig<Api>;
+    authHeader?: boolean;
+    /** Streaming transport override — see {@link Model.transport}. */
+    transport?: Model<Api>["transport"];
+    oauth?: {
+        name: string;
+        login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials | string>;
+        refreshToken?(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+        getApiKey?(credentials: OAuthCredentials): string;
+        modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
+    };
+    /**
+     * Async factory that fetches the live model list from the provider endpoint.
+     * When present, the result is run through the same SQLite model-cache as
+     * built-in providers (keyed by provider name, default 24 h TTL).
+     * The factory receives the resolved API key (undefined when unauthenticated).
+     */
+    fetchDynamicModels?: (apiKey: string | undefined) => Promise<readonly NonNullable<ProviderConfigInput["models"]>[number][]>;
+    models?: Array<{
+        id: string;
+        name: string;
+        api?: Api;
+        baseUrl?: string;
+        reasoning: boolean;
+        thinking?: ThinkingConfig;
+        input: ("text" | "image")[];
+        supportsTools?: boolean;
+        cost: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+        };
+        contextWindow: number;
+        maxTokens: number;
+        headers?: Record<string, string>;
+        compat?: ModelSpec<Api>["compat"];
+        contextPromotionTarget?: string;
+        compactionModel?: string;
+        remoteCompaction?: RemoteCompactionConfig<Api>;
+        premiumMultiplier?: number;
+    }>;
+}
+export {};

package/dist/types/config/model-resolver.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Model resolution, scoping, and initial selection.
+ *
+ * Layering:
+ * - `matchModel` is the single matching engine. Order: exact `provider/id`
+ *   reference (with variant-alias and OpenRouter routed/date fallbacks) →
+ *   exact bare id → retired variant alias → provider-scoped fuzzy → substring
+ *   with alias-vs-dated pick.
+ * - `parseModelPatternWithContext`/`parseModelPattern` layer the selector
+ *   grammar on top: trailing `:level` thinking suffixes (`splitThinkingSuffix`)
+ *   and `@upstream` provider routing (`splitUpstreamRouting`).
+ * - Everything else (`resolveModelFromString`, `resolveModelOverride*`,
+ *   `resolveRoleSelection`, `resolveModelScope`, `resolveCliModel`,
+ *   `findSmolModel`/`findSlowModel`) adapts inputs — roles, settings patterns,
+ *   CLI flags, scope globs — onto that pipeline.
+ */
+import { ThinkingLevel } from "jeopi-agent-core";
+import type { Api, Effort, Model } from "jeopi-ai";
+import { type ConfiguredThinkingLevel } from "../thinking";
+import { type ModelRegistry } from "./model-registry";
+import { type ModelRole } from "./model-roles";
+import type { Settings } from "./settings";
+/**
+ * Pick the first provider-default model in availability order.
+ *
+ * If multiple providers expose that same default id, rank only that shared-id
+ * group by canonical provider priority so native/OAuth transports beat mirrors
+ * without changing unrelated provider fallback precedence.
+ */
+export declare function pickDefaultAvailableModel(availableModels: Model<Api>[]): Model<Api> | undefined;
+export interface ScopedModel {
+    model: Model<Api>;
+    thinkingLevel?: ThinkingLevel;
+    explicitThinkingLevel: boolean;
+}
+interface ThinkingSuffixOptions {
+    allowMaxAlias?: boolean;
+    allowAutoAlias?: boolean;
+}
+interface ModelStringParseOptions extends ThinkingSuffixOptions {
+    isLiteralModelId?: (provider: string, id: string) => boolean;
+}
+/**
+ * Parse a model string in "provider/modelId" format.
+ * Returns undefined if the format is invalid.
+ */
+export declare function parseModelString(modelStr: string, options?: ModelStringParseOptions): {
+    provider: string;
+    id: string;
+    thinkingLevel?: ConfiguredThinkingLevel;
+} | undefined;
+/**
+ * Format a model as "provider/modelId" string.
+ */
+export declare function formatModelString(model: Model<Api>): string;
+export declare function formatModelStringWithRouting(model: Model<Api>): string;
+export declare function formatModelSelectorValue(selector: string, thinkingLevel: ConfiguredThinkingLevel | undefined): string;
+/**
+ * Split a trailing `@<upstream>` provider-routing selector off a model pattern.
+ *
+ * `openrouter/z-ai/glm-4.7@cerebras` -> base `openrouter/z-ai/glm-4.7`, upstream
+ * `cerebras`. A `:thinking` suffix after the slug is kept on the base
+ * (`...@cerebras:high` -> base `...:high`). Returns undefined when there is no
+ * `@` or the suffix is not a bare provider slug, so model ids that legitimately
+ * contain `@` (`claude-opus-4-8@default`, `workers-ai/@cf/...`) are never split.
+ */
+export declare function splitUpstreamRouting(pattern: string): {
+    base: string;
+    upstream: string;
+} | undefined;
+export declare function resolveProviderModelReference(provider: string, modelId: string, availableModels: readonly Model<Api>[]): Model<Api> | undefined;
+export interface ModelMatchPreferences {
+    /** Most-recently-used model keys (provider/modelId) to prefer when ambiguous. */
+    usageOrder?: string[];
+    /** Provider precedence used for ambiguous unqualified model patterns. */
+    providerOrder?: readonly string[];
+    /** Providers to deprioritize when no recent usage or provider priority is available. */
+    deprioritizeProviders?: string[];
+}
+export type ModelLookupRegistry = Pick<ModelRegistry, "getAvailable">;
+type CliModelRegistry = Pick<ModelRegistry, "getAll">;
+type InitialModelRegistry = Pick<ModelRegistry, "getAvailable" | "find">;
+type RestorableModelRegistry = Pick<ModelRegistry, "getAvailable" | "find" | "getApiKey">;
+export declare function getModelMatchPreferences(settings?: Partial<Pick<Settings, "get" | "getStorage">>): ModelMatchPreferences;
+export interface ParsedModelResult {
+    model: Model<Api> | undefined;
+    /** Thinking level if explicitly specified in pattern, undefined otherwise */
+    thinkingLevel?: ConfiguredThinkingLevel;
+    /** Upstream provider slug from an `@upstream` routing selector, if present. */
+    upstream?: string;
+    warning: string | undefined;
+    explicitThinkingLevel: boolean;
+}
+export declare function parseModelPattern(pattern: string, availableModels: Model<Api>[], preferences?: ModelMatchPreferences, options?: {
+    allowInvalidThinkingSelectorFallback?: boolean;
+}): ParsedModelResult;
+/**
+ * Expand a role alias like "pi/smol" to the configured model string.
+ */
+export declare function expandRoleAlias(value: string, settings?: Settings): string;
+export declare function resolveConfiguredModelPatterns(value: string | string[] | undefined, settings?: Settings): string[];
+export interface AgentModelPatternResolutionOptions {
+    settingsOverride?: string | string[];
+    agentModel?: string | string[];
+    settings?: Settings;
+    activeModelPattern?: string;
+    fallbackModelPattern?: string;
+}
+export declare function resolveAgentModelPatterns(options: AgentModelPatternResolutionOptions): string[];
+/**
+ * Resolve a model role value into a concrete model and thinking metadata.
+ */
+export interface ResolvedModelRoleValue {
+    model: Model<Api> | undefined;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    explicitThinkingLevel: boolean;
+    warning: string | undefined;
+}
+export declare function resolveModelRoleValue(roleValue: string | undefined, availableModels: Model<Api>[], options?: {
+    settings?: Settings;
+    matchPreferences?: ModelMatchPreferences;
+}): ResolvedModelRoleValue;
+interface ExplicitThinkingSelectorOptions {
+    isLiteralModelId?: (provider: string, id: string) => boolean;
+}
+export declare function extractExplicitThinkingSelector(value: string | undefined, settings?: Settings, options?: ExplicitThinkingSelectorOptions): ConfiguredThinkingLevel | undefined;
+/**
+ * Resolve a model identifier or pattern to a Model instance.
+ */
+export declare function resolveModelFromString(value: string, available: Model<Api>[], matchPreferences?: ModelMatchPreferences): Model<Api> | undefined;
+/**
+ * Resolve a model from configured roles, honoring order and overrides.
+ */
+export declare function resolveModelFromSettings(options: {
+    settings: Settings;
+    availableModels: Model<Api>[];
+    matchPreferences?: ModelMatchPreferences;
+    roleOrder?: readonly ModelRole[];
+}): Model<Api> | undefined;
+/**
+ * Resolve a list of override patterns to the first matching model.
+ */
+export declare function resolveModelOverride(modelPatterns: string[], modelRegistry: ModelLookupRegistry, settings?: Settings): {
+    model?: Model<Api>;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    explicitThinkingLevel: boolean;
+};
+/**
+ * Resolve a list of override patterns to the first matching model, with an
+ * auth-aware fallback to the parent session's active model.
+ *
+ * If the resolved subagent model has no working credentials (provider has no
+ * usable auth), and the parent's active model resolves with working auth,
+ * use the parent's model instead. This prevents subagent dispatch from
+ * silently routing to a provider the user can't actually call (e.g.
+ * `modelRoles.task` pointing at an unqualified id whose only available
+ * provider variant has no configured credentials — see #985).
+ *
+ * Keyless-by-design providers (llama.cpp, ollama, lm-studio) advertise the
+ * `kNoAuth` sentinel from `getApiKey` to signal that they do not require
+ * credentials. Those are treated as authenticated here so an explicitly
+ * configured local model is never silently rerouted to the parent's remote
+ * provider (see #1008).
+ *
+ * If neither the subagent nor the parent has working auth, returns the
+ * primary resolution unchanged so the existing error path still surfaces
+ * a meaningful failure downstream.
+ */
+export declare function resolveModelOverrideWithAuthFallback(modelPatterns: string[], parentActiveModelPattern: string | undefined, modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">, settings?: Settings): Promise<{
+    model?: Model<Api>;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    explicitThinkingLevel: boolean;
+    authFallbackUsed: boolean;
+}>;
+/**
+ * Resolve a list of role patterns to the first matching model.
+ */
+export declare function resolveRoleSelection(roles: readonly string[], settings: Settings, availableModels: Model<Api>[]): {
+    model: Model<Api>;
+    thinkingLevel?: ConfiguredThinkingLevel;
+} | undefined;
+/**
+ * Resolve the model for the `advisor` role. A configured `modelRoles.advisor`
+ * wins outright (a bad override surfaces as no model rather than silently
+ * running something else); when unset it falls back to the `slow` priority
+ * chain via {@link ROLE_PRIORITY_ALIAS} — a strong reasoning model that, unlike
+ * the `slow` role itself, never inherits the primary's model. Returns undefined
+ * only when no candidate in the resolved chain is available.
+ */
+export declare function resolveAdvisorRoleSelection(settings: Settings, availableModels: Model<Api>[]): {
+    model: Model<Api>;
+    thinkingLevel?: ConfiguredThinkingLevel;
+} | undefined;
+/**
+ * Resolve model patterns to actual Model objects with optional thinking levels
+ * Format: "pattern:level" where :level is optional
+ * For each pattern, finds all matching models and picks the best version:
+ * 1. Prefer alias (e.g., claude-sonnet-4-5) over dated versions (claude-sonnet-4-5-20250929)
+ * 2. If no alias, pick the latest dated version
+ *
+ * Supports models with colons in their IDs (e.g., OpenRouter's model:exacto).
+ * The algorithm tries to match the full pattern first, then progressively
+ * strips colon-suffixes to find a match.
+ */
+export declare function resolveModelScope(patterns: string[], modelRegistry: Pick<ModelRegistry, "getAvailable">, preferences?: ModelMatchPreferences): Promise<ScopedModel[]>;
+/**
+ * Resolve the set of models a session is allowed to use, given the active
+ * settings. Starts from `modelRegistry.getAvailable()` (so disabled providers
+ * and providers without credentials are already filtered out) and, when
+ * `enabledModels` is configured for the current path scope, further restricts
+ * the result to models matching those patterns.
+ *
+ * Returns the unfiltered available list when `enabledModels` is empty.
+ * Returns an empty list when `enabledModels` is configured but no model matches
+ * any pattern — callers MUST treat this as "no usable model" rather than
+ * falling back to the global default (see issue #1022).
+ */
+export declare function resolveAllowedModels(modelRegistry: Pick<ModelRegistry, "getAvailable">, settings: Settings | undefined, preferences?: ModelMatchPreferences): Promise<Model<Api>[]>;
+/**
+ * Synchronous subset of {@link resolveAllowedModels} for contexts where async is unavailable
+ * (e.g. `getAvailableModels()` which is called from the ACP model-list advertisement, RPC
+ * `get_available_models`, and the `/model` slash command). Uses the same effective
+ * `enabledModels` scope semantics as startup resolution:
+ *
+ * - Glob selectors match `provider/modelId` and bare model id
+ * - Exact `provider/modelId`, bare ids, provider-scoped fuzzy, and substring selectors
+ *   resolve through the shared model-pattern matcher
+ * - Optional `:thinkingLevel` suffixes are stripped only when valid
+ *
+ * When no pattern resolves to any model (misconfiguration / typo) an empty list is returned,
+ * consistent with the empty-list contract of {@link resolveAllowedModels}. Callers that render
+ * a UI picker should treat an empty list as "hide the picker entry", matching how the SDK
+ * surfaces the same misconfiguration during session initialization.
+ */
+export declare function filterAvailableModelsByEnabledPatterns(available: Model<Api>[], patterns: readonly string[]): Model<Api>[];
+export interface ResolveCliModelResult {
+    model: Model<Api> | undefined;
+    selector?: string;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    warning: string | undefined;
+    error: string | undefined;
+}
+/**
+ * Resolve a single model from CLI flags.
+ */
+export declare function resolveCliModel(options: {
+    cliProvider?: string;
+    cliModel?: string;
+    modelRegistry: CliModelRegistry;
+    preferences?: ModelMatchPreferences;
+}): ResolveCliModelResult;
+export interface InitialModelResult {
+    model: Model<Api> | undefined;
+    thinkingLevel?: ThinkingLevel;
+    fallbackMessage: string | undefined;
+}
+/**
+ * Find the initial model to use based on priority:
+ * 1. CLI args (provider + model)
+ * 2. First model from scoped models (if not continuing/resuming)
+ * 3. Restored from session (if continuing/resuming)
+ * 4. Saved default from settings
+ * 5. First available model with valid API key
+ */
+export declare function findInitialModel(options: {
+    cliProvider?: string;
+    cliModel?: string;
+    scopedModels: ScopedModel[];
+    isContinuing: boolean;
+    defaultProvider?: string;
+    defaultModelId?: string;
+    defaultThinkingSelector?: Effort;
+    modelRegistry: InitialModelRegistry;
+}): Promise<InitialModelResult>;
+/**
+ * Restore model from session, with fallback to available models
+ */
+export declare function restoreModelFromSession(savedProvider: string, savedModelId: string, currentModel: Model<Api> | undefined, shouldPrintMessages: boolean, modelRegistry: RestorableModelRegistry): Promise<{
+    model: Model<Api> | undefined;
+    fallbackMessage: string | undefined;
+}>;
+/**
+ * Find a smol/fast model using the priority chain.
+ * Tries exact matches first, then fuzzy matches.
+ *
+ * @param modelRegistry The model registry to search
+ * @param savedModel Optional saved model string from settings (provider/modelId)
+ * @returns The best available smol model, or undefined if none found
+ */
+export declare function findSmolModel(modelRegistry: ModelLookupRegistry, savedModel?: string): Promise<Model<Api> | undefined>;
+/**
+ * Find a slow/comprehensive model using the priority chain.
+ * Prioritizes reasoning and codex models for thorough analysis.
+ *
+ * @param modelRegistry The model registry to search
+ * @param savedModel Optional saved model string from settings (provider/modelId)
+ * @returns The best available slow model, or undefined if none found
+ */
+export declare function findSlowModel(modelRegistry: ModelLookupRegistry, savedModel?: string): Promise<Model<Api> | undefined>;
+export {};

package/dist/types/config/model-roles.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Built-in model roles and role metadata helpers.
+ */
+import { type ThemeColor } from "../modes/theme/theme";
+import type { Settings } from "./settings";
+export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "designer" | "commit" | "tiny" | "task" | "advisor";
+export interface ModelRoleInfo {
+    tag?: string;
+    name: string;
+    color?: ThemeColor;
+    /** If true, the role is functional but not shown in the model selector UI. */
+    hidden?: boolean;
+}
+export declare const MODEL_ROLES: Record<ModelRole, ModelRoleInfo>;
+export declare const MODEL_ROLE_IDS: ModelRole[];
+export type RoleInfo = ModelRoleInfo;
+/**
+ * Return the canonical set of known roles for selector/carousel UI.
+ *
+ * Built-ins always come first. Configured cycle order, model assignments, and
+ * tag metadata can introduce additional custom roles without requiring duplicate
+ * entries across settings.
+ */
+export declare function getKnownRoleIds(settings: Settings): string[];
+/**
+ * Get role info for a role name (built-in or custom).
+ * Configured metadata overrides built-in defaults when present.
+ */
+export declare function getRoleInfo(role: string, settings: Settings): RoleInfo;