@bubblebrain-ai/bubble 0.0.34 → 0.0.36

package/dist/prompt/task-reminders.js

@@ -1,3 +1,4 @@
+import { normalizeModelToken } from "../agent/routing-catalog.js";
 import { wrapInSystemReminder } from "./reminders.js";
 /**
  * Delegation nudge for exploration-shaped tasks: injected at the decision
@@ -6,7 +7,7 @@ import { wrapInSystemReminder } from "./reminders.js";
  * keeps it away from ordinary implementation/debugging turns, so it cannot
  * amplify over-delegation.
  */
-const DELEGATION_NUDGE = "- If answering needs scanning many files and only the conclusion matters, delegate to a background subagent (spawn_agent); when it is the same read-only question over several independent items, fan out with agent_team.";
+const DELEGATION_NUDGE = "- If answering needs scanning many files and only the conclusion matters, delegate to a background subagent (spawn_agent); when it is the same read-only question over several independent items, fan out with a run_workflow script.";
 export function reminderForTaskType(taskType, options = {}) {
     switch (taskType) {
         case "debugging":
@@ -62,3 +63,74 @@ Product discussion workflow:
             return undefined;
     }
 }
+/**
+ * Deterministic detector for an explicit user request for a coordinated
+ * multi-agent run. Three rounds of prompt wording lost to the model's
+ * "agent team = parallel spawns" prior in live tests (opus-4.8, 2026-07-06);
+ * per the task-reminder principle above, a reminder injected at the decision
+ * turn is the lever that actually works — the harness remembers so the model
+ * does not have to.
+ */
+/**
+ * User-named model resolution (model-routing design v3.6): when the user's
+ * message names a model that exists in the routable catalog, hand the main
+ * agent the EXACT provider:model id at the decision point. The catalog is a
+ * closed set, so matching is deterministic — the model must never retype an
+ * id from priors when the harness can resolve it ("gpt 5.6 sol" ->
+ * openai:gpt-5.6-sol; a Grok-4.5 parent invented "openai:gpt-5.6" without
+ * this, 2026-07-12 live case). Silent on no match: zero standing noise.
+ */
+export function userNamedModelReminder(input, routableModels, canSpawn) {
+    if (!canSpawn || !routableModels || routableModels.length === 0)
+        return undefined;
+    const text = typeof input === "string"
+        ? input
+        : input.map((part) => ("text" in part ? String(part.text ?? "") : "")).join(" ");
+    if (!text.trim())
+        return undefined;
+    const normalizedInput = normalizeModelToken(text);
+    // Group by model id so multi-provider models (glm-5.2 on four providers)
+    // produce one line listing the routable providers.
+    const hitsByModel = new Map();
+    for (const entry of routableModels) {
+        const keys = [normalizeModelToken(entry.id), normalizeModelToken(entry.name)];
+        // Short keys ("o1", "glm") would match prose; require some substance.
+        if (!keys.some((key) => key.length >= 5 && normalizedInput.includes(key)))
+            continue;
+        const hit = hitsByModel.get(entry.id);
+        if (hit) {
+            if (!hit.providerIds.includes(entry.providerId))
+                hit.providerIds.push(entry.providerId);
+        }
+        else {
+            hitsByModel.set(entry.id, { entry, providerIds: [entry.providerId] });
+        }
+    }
+    if (hitsByModel.size === 0)
+        return undefined;
+    const lines = [...hitsByModel.values()].slice(0, 6).map(({ entry, providerIds }) => {
+        const primary = `${providerIds[0]}:${entry.id}`;
+        const alternates = providerIds.length > 1 ? ` (also on: ${providerIds.slice(1).join(", ")})` : "";
+        return `- "${entry.name}" → ${primary}${alternates}`;
+    });
+    return [
+        "The user's message names these configured models. Exact routable ids:",
+        ...lines,
+        "Use these exact ids in spawn_agent / run_workflow `model` params; do not retype model ids from memory.",
+    ].join("\n");
+}
+const ORCHESTRATION_REQUEST = /\b(?:workflows?|orchestrat\w*|agent[ -]?teams?|fan[ -]?out)\b|工作流|编排|(?:智能体|代理|agent)\s*(?:团队|小队)/i;
+export function orchestrationRequestReminder(input, canRunWorkflow) {
+    if (!canRunWorkflow)
+        return undefined;
+    const text = typeof input === "string"
+        ? input
+        : input.map((part) => ("text" in part ? String(part.text ?? "") : "")).join(" ");
+    if (!ORCHESTRATION_REQUEST.test(text))
+        return undefined;
+    return [
+        "- This message explicitly asks for a coordinated multi-agent run (a workflow / orchestration / agent team).",
+        "Honor it with ONE run_workflow call whose script covers the whole fan-out.",
+        "Do not substitute parallel spawn_agent calls this turn — the user named the mechanism.",
+    ].join(" ");
+}

package/dist/provider-ai-sdk.js

@@ -138,14 +138,14 @@ function buildCallOptions(messages, chatOptions, providerOptions) {
 /**
  * Gemini 3 models take a graded thinking_level; 2.5-era models take a token
  * budget. "off" (budget 0) is only offered in the catalog for models that
- * accept it (2.5 Flash); xhigh/max clamp to high.
+ * accept it (2.5 Flash); xhigh/max/ultra clamp to high.
  */
 function buildGoogleThinkingOptions(modelId, level) {
     if (!level)
         return undefined;
     if (level === "off")
         return { thinkingConfig: { thinkingBudget: 0 } };
-    const clamped = level === "xhigh" || level === "max" ? "high" : level;
+    const clamped = level === "xhigh" || level === "max" || level === "ultra" ? "high" : level;
     if (modelId.includes("gemini-3")) {
         return { thinkingConfig: { thinkingLevel: clamped, includeThoughts: true } };
     }

package/dist/provider-grok.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Grok subscription provider support.
+ *
+ * The CLI chat proxy (cli-chat-proxy.grok.com) speaks the OpenAI
+ * chat-completions protocol, so the generic OpenAI provider does the heavy
+ * lifting. This module supplies the two Grok-specific pieces: the client
+ * identity headers the proxy gates on, and a fetch wrapper that keeps the
+ * OAuth bearer fresh across long sessions.
+ */
+import type { OAuthCredentials } from "./oauth/types.js";
+import { type ChatGptFetch } from "./network/chatgpt-transport.js";
+export declare const GROK_SUBSCRIPTION_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+export declare const GROK_CLIENT_VERSION = "0.2.93";
+export declare function isGrokSubscriptionBaseUrl(baseURL: string): boolean;
+export declare function buildGrokSubscriptionHeaders(): Record<string, string>;
+export interface GrokAuthAdapter {
+    getCredentials: () => OAuthCredentials | undefined | Promise<OAuthCredentials | undefined>;
+    refreshCredentials: (current?: OAuthCredentials) => Promise<OAuthCredentials>;
+    isExpired?: (credentials: OAuthCredentials, graceMs: number) => boolean;
+}
+/**
+ * Wrap a fetch so every request carries a fresh subscription bearer. The
+ * OpenAI client's static apiKey would go stale after ~6h; this reads (and
+ * proactively refreshes) the stored OAuth credentials per request instead.
+ */
+export declare function createGrokSubscriptionFetch(auth: GrokAuthAdapter, baseFetch?: ChatGptFetch): ChatGptFetch;

package/dist/provider-grok.js

@@ -0,0 +1,59 @@
+/**
+ * Grok subscription provider support.
+ *
+ * The CLI chat proxy (cli-chat-proxy.grok.com) speaks the OpenAI
+ * chat-completions protocol, so the generic OpenAI provider does the heavy
+ * lifting. This module supplies the two Grok-specific pieces: the client
+ * identity headers the proxy gates on, and a fetch wrapper that keeps the
+ * OAuth bearer fresh across long sessions.
+ */
+import { getChatGptFetch } from "./network/chatgpt-transport.js";
+export const GROK_SUBSCRIPTION_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+// The proxy rejects requests below a minimum client version; identify as the
+// same pinned CLI build Bubble verifies elsewhere.
+export const GROK_CLIENT_VERSION = "0.2.93";
+const TOKEN_REFRESH_GRACE_MS = 5 * 60 * 1000;
+export function isGrokSubscriptionBaseUrl(baseURL) {
+    const normalized = baseURL.trim().replace(/\/+$/, "");
+    return normalized === GROK_SUBSCRIPTION_BASE_URL || normalized.startsWith(`${GROK_SUBSCRIPTION_BASE_URL}/`);
+}
+export function buildGrokSubscriptionHeaders() {
+    return {
+        "User-Agent": "grok-cli",
+        "x-grok-client-version": GROK_CLIENT_VERSION,
+    };
+}
+/**
+ * Wrap a fetch so every request carries a fresh subscription bearer. The
+ * OpenAI client's static apiKey would go stale after ~6h; this reads (and
+ * proactively refreshes) the stored OAuth credentials per request instead.
+ */
+export function createGrokSubscriptionFetch(auth, baseFetch = getChatGptFetch()) {
+    let refreshPromise;
+    async function freshAccessToken() {
+        let credentials = await auth.getCredentials();
+        if (!credentials)
+            return undefined;
+        const expired = auth.isExpired
+            ? auth.isExpired(credentials, TOKEN_REFRESH_GRACE_MS)
+            : Date.now() >= credentials.expiresAt - TOKEN_REFRESH_GRACE_MS;
+        if ((expired || !credentials.accessToken) && credentials.refreshToken) {
+            if (!refreshPromise) {
+                refreshPromise = auth.refreshCredentials(credentials).finally(() => {
+                    refreshPromise = undefined;
+                });
+            }
+            credentials = await refreshPromise;
+        }
+        return credentials.accessToken || undefined;
+    }
+    return async (input, init) => {
+        const token = await freshAccessToken();
+        if (!token) {
+            return baseFetch(input, init);
+        }
+        const headers = new Headers(init?.headers);
+        headers.set("Authorization", `Bearer ${token}`);
+        return baseFetch(input, { ...(init ?? {}), headers });
+    };
+}

package/dist/provider-openai-codex.d.ts

@@ -1,11 +1,14 @@
-import type { Provider, ReasoningEffort, ThinkingLevel, TokenUsage } from "./types.js";
+import { type Provider, type ReasoningEffort, type ThinkingLevel, type TokenUsage } from "./types.js";
 import type { OAuthCredentials } from "./oauth/types.js";
 import { type ChatGptFetch } from "./network/chatgpt-transport.js";
 export interface CodexModelDescriptor {
     id: string;
     displayName?: string;
     contextWindow?: number;
+    useResponsesLite?: boolean;
     reasoningLevels?: ReasoningEffort[];
+    defaultReasoningLevel?: ReasoningEffort;
+    priority?: number;
     visibility?: string;
     minimalClientVersion?: string;
     /** Server-declared per-tool-output token cap (truncation_policy.limit when mode=tokens). */
@@ -39,4 +42,17 @@ export declare function fetchOpenAICodexModels(options: {
     accessToken: string;
     fetch?: ChatGptFetch;
 }): Promise<CodexModelDescriptor[]>;
+export interface OpenAICodexModelCatalogResult {
+    descriptors: CodexModelDescriptor[];
+    status: "success" | "unavailable";
+}
+/**
+ * Fetches the account-scoped Codex catalog while preserving the distinction
+ * between an authoritative empty catalog and discovery being unavailable.
+ */
+export declare function fetchOpenAICodexModelCatalog(options: {
+    baseURL: string;
+    accessToken: string;
+    fetch?: ChatGptFetch;
+}): Promise<OpenAICodexModelCatalogResult>;
 export declare function sortCodexModelDescriptors(descriptors: CodexModelDescriptor[]): CodexModelDescriptor[];

package/dist/provider-openai-codex.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { listBuiltinModels } from "./model-catalog.js";
+import { THINKING_LEVELS } from "./types.js";
+import { getBuiltinModel, listBuiltinModels } from "./model-catalog.js";
 import { resolveProviderRequestConfig } from "./provider-transform.js";
 import { chatGptFetch } from "./network/chatgpt-transport.js";
 import { computeRetryDelayMs, getProviderMaxRetries, isRetryableHttpStatus, ProviderStreamInterruptedError, sleepBeforeRetry, } from "./network/retry.js";
@@ -68,6 +69,7 @@ export function createOpenAICodexProvider(options) {
     }
     async function* streamChat(messages, chatOptions) {
         const requestConfig = resolveProviderRequestConfig("openai-codex", chatOptions.model, chatOptions.thinkingLevel ?? options.thinkingLevel ?? "off");
+        const useResponsesLite = getBuiltinModel("openai-codex", chatOptions.model)?.useResponsesLite === true;
         const body = JSON.stringify(buildRequestBody(messages, {
             model: chatOptions.model,
             tools: chatOptions.tools,
@@ -76,6 +78,7 @@ export function createOpenAICodexProvider(options) {
             sessionId,
             providerId: options.providerId,
             promptCacheKey: options.promptCacheKey,
+            useResponsesLite,
         }));
         const sendRequest = async (forceRefresh = false) => {
             const { accessToken, accountId } = await resolveRequestAuth(forceRefresh);
@@ -85,6 +88,7 @@ export function createOpenAICodexProvider(options) {
                 sessionId,
                 signal: chatOptions.abortSignal,
                 body,
+                useResponsesLite,
             }));
         };
         for (let attempt = 0;; attempt++) {
@@ -283,9 +287,17 @@ export function buildOpenAICodexPromptCacheKey(input) {
         .digest("hex");
 }
 export async function fetchOpenAICodexModels(options) {
+    const result = await fetchOpenAICodexModelCatalog(options);
+    return result.descriptors;
+}
+/**
+ * Fetches the account-scoped Codex catalog while preserving the distinction
+ * between an authoritative empty catalog and discovery being unavailable.
+ */
+export async function fetchOpenAICodexModelCatalog(options) {
     const accountId = extractChatGptAccountId(options.accessToken);
     if (!accountId) {
-        return [];
+        return { descriptors: [], status: "unavailable" };
     }
     const fetchImpl = options.fetch ?? chatGptFetch;
     for (const path of MODEL_DISCOVERY_PATHS) {
@@ -295,13 +307,17 @@ export async function fetchOpenAICodexModels(options) {
         }).catch(() => undefined);
         if (!response?.ok)
             continue;
-        const payload = await response.json().catch(() => undefined);
-        const descriptors = extractCodexModelDescriptors(payload);
-        if (descriptors.length > 0) {
-            return sortCodexModelDescriptors(descriptors);
-        }
+        const parsed = await response.json()
+            .then((payload) => ({ ok: true, payload }))
+            .catch(() => ({ ok: false }));
+        if (!parsed.ok)
+            continue;
+        return {
+            descriptors: sortCodexModelDescriptors(extractCodexModelDescriptors(parsed.payload)),
+            status: "success",
+        };
     }
-    return [];
+    return { descriptors: [], status: "unavailable" };
 }
 function buildRequestBody(messages, options) {
     const instructions = messages
@@ -309,11 +325,31 @@ function buildRequestBody(messages, options) {
         .map((message) => message.content)
         .join("\n\n");
     const input = messages.flatMap((message) => convertMessage(message));
+    const functionTools = (options.tools ?? []).map((tool) => ({
+        type: "function",
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+    }));
+    const liteFunctionTools = options.toolChoice === "none" ? [] : functionTools;
+    if (options.useResponsesLite) {
+        input.unshift({
+            type: "additional_tools",
+            role: "developer",
+            tools: liteFunctionTools,
+        });
+        if (instructions) {
+            input.splice(1, 0, {
+                role: "developer",
+                content: [{ type: "input_text", text: instructions }],
+            });
+        }
+    }
     const body = {
         model: options.model,
         store: false,
         stream: true,
-        instructions: instructions || undefined,
+        instructions: options.useResponsesLite ? "" : instructions || undefined,
         input,
         include: ["reasoning.encrypted_content"],
         prompt_cache_key: buildOpenAICodexPromptCacheKey({
@@ -321,17 +357,30 @@ function buildRequestBody(messages, options) {
             providerId: options.providerId,
             model: options.model,
         }),
-        tool_choice: options.tools && options.tools.length > 0 ? options.toolChoice ?? "auto" : undefined,
-        parallel_tool_calls: true,
+        tool_choice: options.useResponsesLite
+            ? "auto"
+            : options.tools && options.tools.length > 0 ? options.toolChoice ?? "auto" : undefined,
+        parallel_tool_calls: options.useResponsesLite ? false : true,
         text: { verbosity: "medium" },
+        client_metadata: options.useResponsesLite ? {
+            "x-codex-installation-id": options.sessionId,
+            session_id: options.sessionId,
+            thread_id: options.sessionId,
+            "x-codex-window-id": options.sessionId,
+        } : undefined,
     };
-    if (options.tools && options.tools.length > 0) {
-        body.tools = options.tools.map((tool) => ({
-            type: "function",
-            name: tool.name,
-            description: tool.description,
-            parameters: tool.parameters,
-        }));
+    if (!options.useResponsesLite && functionTools.length > 0) {
+        body.tools = functionTools;
+    }
+    if (options.reasoningEffort && options.reasoningEffort !== "off") {
+        // Codex exposes Ultra as a client-level preset: it keeps the session/UI
+        // state at Ultra (which enables proactive delegation) but sends Max over
+        // the Responses wire protocol. Match the official Codex client mapping.
+        const wireEffort = options.reasoningEffort === "ultra" ? "max" : options.reasoningEffort;
+        body.reasoning = {
+            effort: wireEffort,
+            ...(options.useResponsesLite ? { context: "all_turns" } : {}),
+        };
     }
     return body;
 }
@@ -430,7 +479,7 @@ async function* parseSse(response) {
 function buildCodexRequestInit(options) {
     const init = {
         method: "POST",
-        headers: buildSseHeaders(options.accessToken, options.accountId, options.sessionId),
+        headers: buildSseHeaders(options.accessToken, options.accountId, options.sessionId, options.useResponsesLite),
         signal: options.signal,
         body: options.body,
         keepalive: false,
@@ -505,17 +554,26 @@ function buildBaseHeaders(accessToken, accountId, sessionId, extraHeaders) {
     const headers = new Headers(extraHeaders);
     headers.set("Authorization", `Bearer ${accessToken}`);
     headers.set("ChatGPT-Account-Id", accountId);
-    headers.set("originator", "bubble");
-    headers.set("User-Agent", "bubble");
+    // The ChatGPT Codex backend gates newly listed models on the Codex client
+    // identity as well as client_version. Keep the official originator token and
+    // identify Bubble explicitly as a User-Agent suffix.
+    headers.set("originator", "codex_cli_rs");
+    headers.set("User-Agent", `codex_cli_rs/${CODEX_CLIENT_VERSION} (bubble)`);
     headers.set("session_id", sessionId);
     return headers;
 }
-function buildSseHeaders(accessToken, accountId, sessionId) {
+function buildSseHeaders(accessToken, accountId, sessionId, useResponsesLite = false) {
     const headers = buildBaseHeaders(accessToken, accountId, sessionId, {
         accept: "text/event-stream",
         "content-type": "application/json",
     });
     headers.set("OpenAI-Beta", OPENAI_BETA_RESPONSES);
+    if (useResponsesLite) {
+        headers.set("x-openai-internal-codex-responses-lite", "true");
+        headers.set("thread_id", sessionId);
+        headers.set("x-codex-window-id", sessionId);
+        headers.set("x-codex-installation-id", sessionId);
+    }
     return headers;
 }
 function resolveCodexUrl(baseURL) {
@@ -530,9 +588,6 @@ function resolveRelativeUrl(baseURL, path) {
     const normalized = (baseURL.trim() || DEFAULT_CODEX_BASE_URL).replace(/\/+$/, "");
     return `${normalized}${path}`;
 }
-const REASONING_EFFORTS = [
-    "off", "minimal", "low", "medium", "high", "xhigh", "max",
-];
 function extractCodexModelDescriptors(payload) {
     const out = [];
     const seen = new Set();
@@ -553,22 +608,35 @@ function extractCodexModelDescriptors(payload) {
         const ctx = record.context_window;
         if (typeof ctx === "number" && ctx > 0)
             desc.contextWindow = ctx;
+        const useResponsesLite = record.use_responses_lite;
+        if (typeof useResponsesLite === "boolean")
+            desc.useResponsesLite = useResponsesLite;
         const visibility = record.visibility;
         if (typeof visibility === "string")
             desc.visibility = visibility;
         const minVer = record.minimal_client_version;
         if (typeof minVer === "string")
             desc.minimalClientVersion = minVer;
+        const priority = record.priority;
+        if (typeof priority === "number" && Number.isFinite(priority))
+            desc.priority = priority;
         const levels = record.supported_reasoning_levels;
         if (Array.isArray(levels)) {
-            const efforts = new Set(["off"]);
+            const efforts = [];
             for (const level of levels) {
                 const effort = level?.effort;
-                if (typeof effort === "string" && REASONING_EFFORTS.includes(effort)) {
-                    efforts.add(effort);
+                if (typeof effort === "string"
+                    && THINKING_LEVELS.includes(effort)
+                    && !efforts.includes(effort)) {
+                    efforts.push(effort);
                 }
             }
-            desc.reasoningLevels = REASONING_EFFORTS.filter((e) => efforts.has(e));
+            desc.reasoningLevels = efforts;
+            const defaultLevel = record.default_reasoning_level;
+            if (typeof defaultLevel === "string"
+                && efforts.includes(defaultLevel)) {
+                desc.defaultReasoningLevel = defaultLevel;
+            }
         }
         const truncPolicy = record.truncation_policy;
         if (truncPolicy && truncPolicy.mode === "tokens") {
@@ -617,6 +685,10 @@ export function sortCodexModelDescriptors(descriptors) {
         const rightFamily = parseCodexFamilyRank(right.id);
         if (leftFamily !== rightFamily)
             return rightFamily - leftFamily;
+        const leftPriority = left.priority ?? Number.MAX_SAFE_INTEGER;
+        const rightPriority = right.priority ?? Number.MAX_SAFE_INTEGER;
+        if (leftPriority !== rightPriority)
+            return leftPriority - rightPriority;
         const leftRank = preferred.get(left.id) ?? Number.MAX_SAFE_INTEGER;
         const rightRank = preferred.get(right.id) ?? Number.MAX_SAFE_INTEGER;
         if (leftRank !== rightRank)

package/dist/provider-registry.d.ts

@@ -9,6 +9,8 @@ import { type ProviderProtocol } from "./model-catalog.js";
 import { ModelConfig } from "./model-config.js";
 import { AuthStorage } from "./oauth/index.js";
 import { type OpenAICodexAuthAdapter } from "./provider-openai-codex.js";
+import type { GrokAuthAdapter } from "./provider-grok.js";
+import type { ThinkingLevel } from "./types.js";
 export interface ProviderProfile {
     id: string;
     name: string;
@@ -22,6 +24,37 @@ export interface ModelInfo {
     id: string;
     name: string;
     providerId: string;
+    reasoningLevels?: ThinkingLevel[];
+    defaultReasoningLevel?: ThinkingLevel;
+    contextWindow?: number;
+    useResponsesLite?: boolean;
+    toolOutputTokenLimit?: number;
+    /** Within-provider capability/cost tier (models.json / catalog annotation). */
+    tier?: import("./model-catalog.js").ModelTier;
+    /** Deterministic within-tier routing order (models.json only). */
+    routingPriority?: number;
+}
+export type ModelDiscoverySource = "remote" | "cache" | "static" | "fallback";
+export interface ModelDiscoveryResult {
+    models: ModelInfo[];
+    source: ModelDiscoverySource;
+    /** True when `models` is the complete list for this provider/account. */
+    authoritative: boolean;
+    error?: string;
+}
+/**
+ * Read-only view of the discovery cache for routing consumers
+ * (docs/model-routing-design.md §1.4). `complete` is true only for a
+ * successful remote discovery that returned the provider's full catalog —
+ * static/fallback results are NEVER complete, regardless of the internal
+ * `authoritative` flag (which historically marks static fallbacks true).
+ */
+export interface CachedDiscoverySnapshot {
+    models: ModelInfo[];
+    source: Exclude<ModelDiscoverySource, "cache">;
+    complete: boolean;
+    expiresAt: number;
+    identityKey: string;
 }
 export declare const BUILTIN_PROVIDERS: import("./model-catalog.js").BuiltinProviderDefinition[];
 export declare const USER_VISIBLE_PROVIDER_IDS: string[];
@@ -30,12 +63,32 @@ export declare class ProviderRegistry {
     private config;
     private modelConfig;
     private authStorage;
+    private modelDiscoveryCache;
+    private modelDiscoveryInFlight;
+    private modelDiscoveryGeneration;
+    /** Last membership seen per discovery key — survives cache eviction/TTL so
+     *  a re-discovery with identical membership never bumps the revision. */
+    private lastDiscoveryMembership;
+    private routingRevision;
+    private identityFingerprints;
     constructor(config: UserConfig);
+    /**
+     * Monotonic counter of semantic routing-world changes: provider set,
+     * credential identity, provider key/config, discovery membership.
+     * Same-account OAuth token rotation deliberately does NOT bump it
+     * (docs/model-routing-design.md §1.6).
+     */
+    getRoutingRevision(): number;
+    private bumpRoutingRevision;
+    /** Stable identity for stored credentials: account id, else refresh-token hash. */
+    private credentialFingerprint;
+    private handleAuthMutation;
     getModelConfig(): ModelConfig;
     getAuthStorage(): AuthStorage;
     supportsOAuth(providerId: string): boolean;
     private resolveOAuthAuthKey;
     createOpenAICodexAuthAdapter(providerId: string): OpenAICodexAuthAdapter | undefined;
+    createGrokAuthAdapter(providerId: string): GrokAuthAdapter | undefined;
     getDefaultModel(providerId: string, authType?: ProviderProfile["authType"]): string | undefined;
     prepareProvider(providerId: string): Promise<void>;
     getConfigured(): ProviderProfile[];
@@ -46,6 +99,25 @@ export declare class ProviderRegistry {
     removeProvider(id: string): void;
     updateProviderKey(id: string, apiKey: string): void;
     listModels(provider: ProviderProfile): Promise<ModelInfo[]>;
+    discoverModels(provider: ProviderProfile, options?: {
+        forceRefresh?: boolean;
+    }): Promise<ModelDiscoveryResult>;
+    private performModelDiscovery;
+    private fallbackDiscovery;
+    private localModelsForProvider;
+    private discoveryIdentity;
+    private modelDiscoveryKey;
+    /**
+     * Read-only view of the cached discovery result for the provider's CURRENT
+     * configuration/identity (docs/model-routing-design.md §1.4). Returns
+     * undefined when nothing is cached or the cache has expired. `complete` is
+     * derived strictly: only a successful full remote catalog qualifies —
+     * never static or fallback results, whose internal `authoritative` flag
+     * this design does not trust.
+     */
+    getCachedDiscoverySnapshot(providerId: string): CachedDiscoverySnapshot | undefined;
+    private isCurrentModelDiscovery;
+    private applyDynamicDiscoveryMetadata;
 }
 /** Encode a model selection as "providerId:modelId". */
 export declare function encodeModel(providerId: string, modelId: string): string;