@prometheus-ai/agent 0.5.3 → 0.5.8

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

@@ -1,230 +1,22 @@
-import { type Api, type AssistantMessageEventStream, type Context, type Model, type ModelRefreshStrategy, type SimpleStreamOptions, type ThinkingConfig } from "@prometheus-ai/ai";
-import type { OAuthCredentials, OAuthLoginCallbacks } from "@prometheus-ai/ai/utils/oauth/types";
-import { type ThemeColor } from "../modes/theme/theme";
+import type { Api, Context, Model, ModelSpec, SimpleStreamOptions, ThinkingConfig } from "@prometheus-ai/ai/types";
+import type { AssistantMessageEventStream } from "@prometheus-ai/ai/utils/event-stream";
+import { type ModelRefreshStrategy } from "@prometheus-ai/catalog/model-manager";
+import type { ApiKeyResolver, FetchImpl } from "@prometheus-ai/ai";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@prometheus-ai/ai/oauth/types";
+import { type CanonicalModelIndex, type CanonicalModelRecord, type CanonicalModelVariant, type ModelEquivalenceConfig } from "@prometheus-ai/catalog/identity";
 import type { AuthStorage } from "../session/auth-storage";
-import { type ConfigError, ConfigFile } from "./config-file";
-import { type CanonicalModelIndex, type CanonicalModelRecord, type CanonicalModelVariant, type ModelEquivalenceConfig } from "./model-equivalence";
-import { type Settings } from "./settings";
+import { type ApiKeyResolverModel, type ApiKeyResolverOptions } from "./api-key-resolver";
+import type { ConfigError } from "./config-file";
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 export declare const kNoAuth = "N/A";
 export declare function isAuthenticated(apiKey: string | undefined | null): apiKey is string;
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "designer" | "commit" | "task";
-export interface ModelRoleInfo {
-    tag?: string;
-    name: string;
-    color?: ThemeColor;
-}
-export declare const MODEL_ROLES: Record<ModelRole, ModelRoleInfo>;
-export declare const MODEL_ROLE_IDS: ModelRole[];
-/** Alias for ModelRoleInfo - used for both built-in and custom roles */
-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;
-export declare const ModelsConfigFile: ConfigFile<{
-    providers?: Record<string, {
-        baseUrl?: string | undefined;
-        apiKey?: string | undefined;
-        api?: "anthropic-messages" | "azure-openai-responses" | "google-generative-ai" | "google-vertex" | "openai-codex-responses" | "openai-completions" | "openai-responses" | undefined;
-        headers?: Record<string, string> | undefined;
-        compat?: {
-            supportsStore?: boolean | undefined;
-            supportsDeveloperRole?: boolean | undefined;
-            supportsMultipleSystemMessages?: boolean | undefined;
-            supportsReasoningEffort?: boolean | undefined;
-            reasoningEffortMap?: {
-                minimal?: string | undefined;
-                low?: string | undefined;
-                medium?: string | undefined;
-                high?: string | undefined;
-                xhigh?: string | undefined;
-            } | undefined;
-            maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
-            supportsUsageInStreaming?: boolean | undefined;
-            requiresToolResultName?: boolean | undefined;
-            requiresMistralToolIds?: boolean | undefined;
-            requiresAssistantAfterToolResult?: boolean | undefined;
-            requiresThinkingAsText?: boolean | undefined;
-            reasoningContentField?: "reasoning" | "reasoning_content" | "reasoning_text" | undefined;
-            requiresReasoningContentForToolCalls?: boolean | undefined;
-            allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
-            requiresAssistantContentForToolCalls?: boolean | undefined;
-            supportsToolChoice?: boolean | undefined;
-            disableReasoningOnForcedToolChoice?: boolean | undefined;
-            disableReasoningOnToolChoice?: boolean | undefined;
-            thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;
-            openRouterRouting?: {
-                only?: string[] | undefined;
-                order?: string[] | undefined;
-            } | undefined;
-            vercelGatewayRouting?: {
-                only?: string[] | undefined;
-                order?: string[] | undefined;
-            } | undefined;
-            extraBody?: Record<string, unknown> | undefined;
-            cacheControlFormat?: "anthropic" | undefined;
-            supportsStrictMode?: boolean | undefined;
-            toolStrictMode?: "all_strict" | "none" | undefined;
-        } | undefined;
-        authHeader?: boolean | undefined;
-        auth?: "apiKey" | "none" | "oauth" | undefined;
-        discovery?: {
-            type: "llama.cpp" | "lm-studio" | "ollama" | "openai-models-list" | "proxy";
-        } | undefined;
-        models?: {
-            id: string;
-            name?: string | undefined;
-            api?: "anthropic-messages" | "azure-openai-responses" | "google-generative-ai" | "google-vertex" | "openai-codex-responses" | "openai-completions" | "openai-responses" | undefined;
-            baseUrl?: string | undefined;
-            reasoning?: boolean | undefined;
-            thinking?: {
-                minLevel: "high" | "low" | "medium" | "minimal" | "xhigh";
-                maxLevel: "high" | "low" | "medium" | "minimal" | "xhigh";
-                mode: "anthropic-adaptive" | "anthropic-budget-effort" | "budget" | "effort" | "google-level";
-                defaultLevel?: "high" | "low" | "medium" | "minimal" | "xhigh" | undefined;
-                levels?: ("high" | "low" | "medium" | "minimal" | "xhigh")[] | undefined;
-            } | undefined;
-            input?: ("image" | "text")[] | undefined;
-            cost?: {
-                input: number;
-                output: number;
-                cacheRead: number;
-                cacheWrite: number;
-            } | undefined;
-            premiumMultiplier?: number | undefined;
-            contextWindow?: number | undefined;
-            maxTokens?: number | undefined;
-            omitMaxOutputTokens?: boolean | undefined;
-            headers?: Record<string, string> | undefined;
-            compat?: {
-                supportsStore?: boolean | undefined;
-                supportsDeveloperRole?: boolean | undefined;
-                supportsMultipleSystemMessages?: boolean | undefined;
-                supportsReasoningEffort?: boolean | undefined;
-                reasoningEffortMap?: {
-                    minimal?: string | undefined;
-                    low?: string | undefined;
-                    medium?: string | undefined;
-                    high?: string | undefined;
-                    xhigh?: string | undefined;
-                } | undefined;
-                maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
-                supportsUsageInStreaming?: boolean | undefined;
-                requiresToolResultName?: boolean | undefined;
-                requiresMistralToolIds?: boolean | undefined;
-                requiresAssistantAfterToolResult?: boolean | undefined;
-                requiresThinkingAsText?: boolean | undefined;
-                reasoningContentField?: "reasoning" | "reasoning_content" | "reasoning_text" | undefined;
-                requiresReasoningContentForToolCalls?: boolean | undefined;
-                allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
-                requiresAssistantContentForToolCalls?: boolean | undefined;
-                supportsToolChoice?: boolean | undefined;
-                disableReasoningOnForcedToolChoice?: boolean | undefined;
-                disableReasoningOnToolChoice?: boolean | undefined;
-                thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;
-                openRouterRouting?: {
-                    only?: string[] | undefined;
-                    order?: string[] | undefined;
-                } | undefined;
-                vercelGatewayRouting?: {
-                    only?: string[] | undefined;
-                    order?: string[] | undefined;
-                } | undefined;
-                extraBody?: Record<string, unknown> | undefined;
-                cacheControlFormat?: "anthropic" | undefined;
-                supportsStrictMode?: boolean | undefined;
-                toolStrictMode?: "all_strict" | "none" | undefined;
-            } | undefined;
-            contextPromotionTarget?: string | undefined;
-        }[] | undefined;
-        modelOverrides?: Record<string, {
-            name?: string | undefined;
-            reasoning?: boolean | undefined;
-            thinking?: {
-                minLevel: "high" | "low" | "medium" | "minimal" | "xhigh";
-                maxLevel: "high" | "low" | "medium" | "minimal" | "xhigh";
-                mode: "anthropic-adaptive" | "anthropic-budget-effort" | "budget" | "effort" | "google-level";
-                defaultLevel?: "high" | "low" | "medium" | "minimal" | "xhigh" | undefined;
-                levels?: ("high" | "low" | "medium" | "minimal" | "xhigh")[] | undefined;
-            } | undefined;
-            input?: ("image" | "text")[] | undefined;
-            cost?: {
-                input?: number | undefined;
-                output?: number | undefined;
-                cacheRead?: number | undefined;
-                cacheWrite?: number | undefined;
-            } | undefined;
-            premiumMultiplier?: number | undefined;
-            contextWindow?: number | undefined;
-            maxTokens?: number | undefined;
-            omitMaxOutputTokens?: boolean | undefined;
-            headers?: Record<string, string> | undefined;
-            compat?: {
-                supportsStore?: boolean | undefined;
-                supportsDeveloperRole?: boolean | undefined;
-                supportsMultipleSystemMessages?: boolean | undefined;
-                supportsReasoningEffort?: boolean | undefined;
-                reasoningEffortMap?: {
-                    minimal?: string | undefined;
-                    low?: string | undefined;
-                    medium?: string | undefined;
-                    high?: string | undefined;
-                    xhigh?: string | undefined;
-                } | undefined;
-                maxTokensField?: "max_completion_tokens" | "max_tokens" | undefined;
-                supportsUsageInStreaming?: boolean | undefined;
-                requiresToolResultName?: boolean | undefined;
-                requiresMistralToolIds?: boolean | undefined;
-                requiresAssistantAfterToolResult?: boolean | undefined;
-                requiresThinkingAsText?: boolean | undefined;
-                reasoningContentField?: "reasoning" | "reasoning_content" | "reasoning_text" | undefined;
-                requiresReasoningContentForToolCalls?: boolean | undefined;
-                allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
-                requiresAssistantContentForToolCalls?: boolean | undefined;
-                supportsToolChoice?: boolean | undefined;
-                disableReasoningOnForcedToolChoice?: boolean | undefined;
-                disableReasoningOnToolChoice?: boolean | undefined;
-                thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;
-                openRouterRouting?: {
-                    only?: string[] | undefined;
-                    order?: string[] | undefined;
-                } | undefined;
-                vercelGatewayRouting?: {
-                    only?: string[] | undefined;
-                    order?: string[] | undefined;
-                } | undefined;
-                extraBody?: Record<string, unknown> | undefined;
-                cacheControlFormat?: "anthropic" | undefined;
-                supportsStrictMode?: boolean | undefined;
-                toolStrictMode?: "all_strict" | "none" | undefined;
-            } | undefined;
-            contextPromotionTarget?: string | undefined;
-        }> | undefined;
-        disableStrictTools?: boolean | undefined;
-        transport?: "prometheus-native" | undefined;
-    }> | undefined;
-    equivalence?: {
-        overrides?: Record<string, string> | undefined;
-        exclude?: string[] | undefined;
-    } | undefined;
-}>;
 /** Provider override config (baseUrl, headers, apiKey, compat, transport) without custom models */
 interface ProviderOverride {
     baseUrl?: string;
     headers?: Record<string, string>;
     apiKey?: string;
     authHeader?: boolean;
-    compat?: Model<Api>["compat"];
+    compat?: ModelSpec<Api>["compat"];
     transport?: Model<Api>["transport"];
 }
 /**
@@ -237,9 +29,19 @@ interface ProviderOverride {
  *      `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. `prometheus-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: prometheus-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`.
  */
@@ -258,6 +60,11 @@ export interface CanonicalModelQueryOptions {
     availableOnly?: boolean;
     candidates?: readonly Model<Api>[];
 }
+/** A canonical record (with query-filtered variants) plus the variant model selected for it. */
+export interface CanonicalModelSelection {
+    record: CanonicalModelRecord;
+    model: Model<Api>;
+}
 /**
  * Model registry - loads and manages models, resolves API keys via AuthStorage.
  */
@@ -273,13 +80,25 @@ export declare class ModelRegistry {
      * migration step lands off the event loop's hot path before the first
      * `tryLoad()` runs.
      */
-    constructor(authStorage: AuthStorage, modelsPath?: string);
+    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>;
+    /**
+     * 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).
      */
@@ -290,6 +109,14 @@ export declare class ModelRegistry {
      */
     getAll(): Model<Api>[];
     getCanonicalModels(options?: CanonicalModelQueryOptions): CanonicalModelRecord[];
+    /**
+     * One-pass equivalent of `getCanonicalModels` + `resolveCanonicalModel` per
+     * record. The per-query state (candidate-selector set, availability memo,
+     * provider rank, candidate order) is built once, so the whole catalog
+     * resolves in O(records + candidates) instead of O(records × candidates).
+     * This is the path the model selector hydrates from synchronously on open.
+     */
+    getCanonicalModelSelections(options?: CanonicalModelQueryOptions): CanonicalModelSelection[];
     getCanonicalVariants(canonicalId: string, options?: CanonicalModelQueryOptions): CanonicalModelVariant[];
     resolveCanonicalModel(canonicalId: string, options?: CanonicalModelQueryOptions): Model<Api> | undefined;
     getCanonicalId(model: Model<Api>): string | undefined;
@@ -301,11 +128,18 @@ export declare class ModelRegistry {
     /**
      * Check whether auth is configured for a model's provider.
      *
-     * Mirrors the upstream `@mariozechner/pi-coding-agent` API surface so that
+     * Mirrors the upstream `@mariozechner/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[];
@@ -324,8 +158,26 @@ export declare class ModelRegistry {
     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, baseUrl?: string): Promise<string | undefined>;
+    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).
      */
@@ -355,6 +207,11 @@ export declare class ModelRegistry {
      * 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).
@@ -365,7 +222,7 @@ export interface ProviderConfigInput {
     api?: Api;
     streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
     headers?: Record<string, string>;
-    compat?: Model<Api>["compat"];
+    compat?: ModelSpec<Api>["compat"];
     authHeader?: boolean;
     /** Streaming transport override — see {@link Model.transport}. */
     transport?: Model<Api>["transport"];
@@ -376,6 +233,13 @@ export interface ProviderConfigInput {
         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;
@@ -393,7 +257,7 @@ export interface ProviderConfigInput {
         contextWindow: number;
         maxTokens: number;
         headers?: Record<string, string>;
-        compat?: Model<Api>["compat"];
+        compat?: ModelSpec<Api>["compat"];
         contextPromotionTarget?: string;
         premiumMultiplier?: number;
     }>;

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

@@ -1,12 +1,24 @@
 /**
- * Model resolution, scoping, and initial selection
+ * 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 canonical id → 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 "@prometheus-ai/agent-core";
-import { type Api, type Effort, type KnownProvider, type Model } from "@prometheus-ai/ai";
-import { type ModelRegistry, type ModelRole } from "./model-registry";
+import type { Api, Effort, Model } from "@prometheus-ai/ai";
+import { type ModelRegistry } from "./model-registry";
+import { type ModelRole } from "./model-roles";
 import type { Settings } from "./settings";
-/** Default model IDs for each known provider */
-export declare const defaultModelPerProvider: Record<KnownProvider, string>;
 export interface ScopedModel {
     model: Model<Api>;
     thinkingLevel?: ThinkingLevel;
@@ -30,7 +42,9 @@ export declare function resolveProviderModelReference(provider: string, modelId:
 export interface ModelMatchPreferences {
     /** Most-recently-used model keys (provider/modelId) to prefer when ambiguous. */
     usageOrder?: string[];
-    /** Providers to deprioritize when no recent usage is available. */
+    /** 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 CanonicalModelRegistry = Partial<Pick<ModelRegistry, "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId">>;
@@ -38,15 +52,13 @@ export type ModelLookupRegistry = Pick<ModelRegistry, "getAvailable"> & Partial<
 type CliModelRegistry = Pick<ModelRegistry, "getAll"> & Partial<CanonicalModelRegistry>;
 type InitialModelRegistry = Pick<ModelRegistry, "getAvailable" | "find">;
 type RestorableModelRegistry = Pick<ModelRegistry, "getAvailable" | "find" | "getApiKey">;
-/**
- * Find an exact explicit provider/model match.
- * Bare model ids are handled separately so canonical ids can coalesce variants.
- */
-export declare function findExactModelReferenceMatch(modelReference: string, availableModels: Model<Api>[]): Model<Api> | undefined;
+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?: ThinkingLevel;
+    /** Upstream provider slug from an `@upstream` routing selector, if present. */
+    upstream?: string;
     warning: string | undefined;
     explicitThinkingLevel: boolean;
 }
@@ -55,7 +67,8 @@ export declare function parseModelPattern(pattern: string, availableModels: Mode
     modelRegistry?: CanonicalModelRegistry;
 }): ParsedModelResult;
 /**
- * Expand a role alias like "prometheus/smol" to the configured model string.
+ * Expand a role alias like "pi/smol" or "prometheus/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[];
@@ -163,6 +176,24 @@ export declare function resolveModelScope(patterns: string[], modelRegistry: Pic
  * rather than falling back to the global default (see issue #1022).
  */
 export declare function resolveAllowedModels(modelRegistry: Pick<ModelRegistry, "getAvailable" | "getCanonicalVariants">, 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 canonical ids expand to all available concrete variants
+ * - 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[], registry: Pick<ModelRegistry, "getCanonicalVariants">): Model<Api>[];
 export interface ResolveCliModelResult {
     model: Model<Api> | undefined;
     selector?: string;

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" | "title" | "task";
+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;