@bubblebrain-ai/bubble 0.0.35 → 0.0.36

package/README.md

@@ -2,7 +2,7 @@
 
 Bubble is a terminal coding agent. It works inside a local project folder: it reads and edits files, runs commands behind configurable approval controls, searches and navigates code with language-server intelligence, browses the web, loads reusable skills, connects MCP tools, fans work out to subagents, and keeps persistent memory across sessions.
 
-It is provider-agnostic. Bring an API key for OpenAI, Anthropic, Google, DeepSeek, Moonshot/Kimi, Zhipu, Z.AI, MiniMax, Groq, Together, Fireworks, a local OpenAI-compatible endpoint, and more — or sign in to ChatGPT with OAuth and drive the Codex models directly.
+It is provider-agnostic. Bring an API key for OpenAI, Anthropic, Google, DeepSeek, Moonshot/Kimi, Zhipu, Z.AI, MiniMax, Groq, Together, Fireworks, a local OpenAI-compatible endpoint, and more; sign in to ChatGPT with OAuth; or sign in with OAuth to use a ChatGPT or Grok subscription directly.
 
 ---
 
@@ -39,10 +39,10 @@ Start Bubble in the current directory:
 bubble
 ```
 
-On first launch, connect a model:
+On first launch, connect a provider:
 
 - Run `/login` to sign in to ChatGPT (OAuth) and use the Codex models, or
-- Run `/provider` to add any other provider with an API key.
+- Run `/provider` to select Grok Subscription or add a provider with an API key.
 
 Then just type what you want done. Bubble plans, edits files, and runs commands, asking for approval where the current permission mode requires it.
 
@@ -64,10 +64,30 @@ Bubble ships with a catalog of built-in providers. Configure them inside the app
 
 | How | What it does |
 | --- | --- |
-| `/login` | OAuth sign-in for ChatGPT; unlocks the OpenAI Codex models without an API key. |
-| `/provider` | Open a picker to connect, switch, add, or remove a provider. |
+| `/login` | OAuth sign-in for ChatGPT or Grok Subscription; `/login grok` starts the Grok flow directly. |
+| `/provider` | Open a picker to connect, switch, add, or remove a provider, including Grok Subscription. |
 | `/model` | Pick the active model and reasoning effort. |
 
+### Grok Subscription Provider
+
+A Grok subscription works as a native model provider, exactly like ChatGPT
+OAuth: sign in once in the browser and the subscription models (`grok-4.5`,
+`grok-composer-2.5-fast`) drive Bubble's own agent loop — Bubble's tools,
+skills, MCP servers, subagents, memory, permission modes, and approval UI all
+apply as usual. `/model` selects the model and reasoning effort.
+
+```bash
+bubble
+# In the TUI: /login grok
+# or choose Grok Subscription from /provider
+```
+
+`/login grok` opens the xAI sign-in page in the default browser. If you have
+already signed in with the official Grok CLI, Bubble imports that login and
+skips the browser. Tokens are stored in `~/.bubble/auth.json` alongside other
+provider credentials and refresh automatically. Use `/logout grok` to remove
+this device's login.
+
 Built-in providers include OpenAI, Anthropic, Google, DeepSeek, Moonshot (CN and international), Kimi for Coding, Zhipu AI, Z.AI, Alibaba DashScope, Doubao (Volcengine Ark), MiniMax, StepFun, Groq, Together AI, Fireworks, and a `local` profile for any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio, etc.).
 
 For Doubao Seed models on Volcengine Ark, run `/provider --add doubao` and paste your Ark API key. The built-in endpoint is `https://ark.cn-beijing.volces.com/api/v3` and uses Ark's Responses API. The model picker exposes `minimal`, `low`, `medium`, and `high`, defaulting to `high`; `minimal` disables Ark thinking, while the other levels enable it.
@@ -95,7 +115,7 @@ For full control — custom base URLs, self-hosted gateways, extra models, or pi
 
 ### Reasoning effort
 
-Models that support it expose a reasoning-effort control: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Set it with `/model <id> --reasoning-effort <level>` in the app, or at launch with `--reasoning` (medium) or `--reasoning-effort <level>`.
+Models that support it expose a reasoning-effort control: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`. Set it with `/model <id> --reasoning-effort <level>` in the app, or at launch with `--reasoning` (medium) or `--reasoning-effort <level>`.
 
 ## Permission modes
 
@@ -191,7 +211,7 @@ Options (default):
   -r, --resume             Resume a previous session (latest by default)
   --session <name>         Session name to create or resume
   --reasoning              Enable reasoning mode at medium effort
-  --reasoning-effort <l>   Set reasoning effort: off|minimal|low|medium|high|xhigh|max
+  --reasoning-effort <l>   Set reasoning effort: off|minimal|low|medium|high|xhigh|max|ultra
   --plan                   Start in plan mode (read-only investigation; propose before executing)
   --dangerously-skip-permissions
                            Enable bypass mode (auto-approve EVERY tool; disables all safety prompts)

package/dist/agent/categories.d.ts

@@ -1,18 +1,50 @@
-import type { ThinkingLevel } from "../types.js";
+import type { ModelTier } from "../model-catalog.js";
+import { type ThinkingLevel } from "../types.js";
 export interface AgentCategoryConfig {
     model?: string;
+    /**
+     * Resolve the model by tier within the parent provider's catalog
+     * (docs/model-routing-design.md §3.1). Mutually exclusive with `model`;
+     * `model` wins if both are set.
+     */
+    tier?: ModelTier | "inherit";
     thinkingLevel?: ThinkingLevel;
     maxConcurrent?: number;
 }
 export type AgentCategoriesConfig = Record<string, AgentCategoryConfig>;
+/**
+ * Field-level provenance for the model-determining fields (§3.3): a value is
+ * "user" ONLY when the user's config object literally contained that key.
+ * thinkingLevel/maxConcurrent overrides carry no routing authority, so a
+ * partially-overridden builtin category keeps its builtin tier under the
+ * rank guard.
+ */
+export interface AgentCategoryProvenance {
+    tierSource?: "builtin" | "user";
+    modelSource?: "builtin" | "user";
+}
+export interface MergedAgentCategory {
+    config: AgentCategoryConfig;
+    provenance: AgentCategoryProvenance;
+}
 export interface ModelRoute {
     providerId: string;
     model: string;
     thinkingLevel: ThinkingLevel;
 }
+/** Which precedence layer decided the model at the category level. */
+export type CategoryModelSource = "builtin-tier" | "user-category";
+/** Which precedence layer decided the FINAL model (§3.4, chain-tracked). */
+export type RouteModelSource = "inherit" | CategoryModelSource | "profile" | "callsite";
 export interface ResolvedSubagentRoute extends ModelRoute {
     category?: string;
     inherited: boolean;
+    /** Set when the category layer decided the model (undefined = inherit). */
+    categoryModelSource?: CategoryModelSource;
+    /** True iff providerId+model equal the parent's — regardless of effort (§3.4). */
+    modelInherited?: boolean;
+    /** Assigned while applying the precedence chain, never inferred from final values. */
+    modelSource?: RouteModelSource;
 }
 export type CategoryResolution = {
     route: ResolvedSubagentRoute;
@@ -23,10 +55,42 @@ export interface ResolvedModelSelection {
     providerId: string;
     model: string | "inherit";
 }
+/** Catalog entry visible to tier resolution (built by routing-catalog.ts). */
+export interface TierCatalogEntry {
+    id: string;
+    tier?: ModelTier;
+    /** models.json user-authored ordering; wins over everything (§3.2). */
+    routingPriority?: number;
+    /** Index in the builtin catalog order, when the id is builtin. */
+    builtinIndex?: number;
+}
+/** Context for rank-guarded automatic tier routing (§3.2). */
+export interface TierRoutingContext {
+    /** Tier of the parent's own model, if annotated. */
+    parentTier?: ModelTier;
+    /** Same-provider catalog the tier is resolved against. */
+    models: TierCatalogEntry[];
+    /** agentRouting.autoTier kill switch (default true). */
+    autoTier: boolean;
+}
+export declare const TIER_RANK: Record<ModelTier, number>;
 export declare function builtinAgentCategories(): AgentCategoriesConfig;
 export declare function mergeAgentCategories(userCategories?: AgentCategoriesConfig): AgentCategoriesConfig;
+/**
+ * Field-level merge with provenance (§3.3). The merge itself is identical to
+ * mergeAgentCategories; provenance records whether the user literally wrote
+ * `tier` / `model`, so builtin tiers flowing through a partial override never
+ * masquerade as user intent.
+ */
+export declare function mergeAgentCategoriesWithProvenance(userCategories?: AgentCategoriesConfig): Record<string, MergedAgentCategory>;
 export declare function sanitizeAgentCategories(value: unknown): AgentCategoriesConfig;
-export declare function resolveSubagentRoute(category: string | undefined, parent: ModelRoute, categories?: AgentCategoriesConfig): CategoryResolution;
+export declare function resolveSubagentRoute(category: string | undefined, parent: ModelRoute, categories?: AgentCategoriesConfig, tierContext?: TierRoutingContext): CategoryResolution;
+/**
+ * Deterministic within-tier ordering (§3.2): user routingPriority, then
+ * builtin catalog order, then normalized id — never a remote response's
+ * array order.
+ */
+export declare function selectTierCandidates(models: TierCatalogEntry[], tier: ModelTier): TierCatalogEntry[];
 export declare function resolveModelRoute(model: string | undefined, parentProviderId: string): ResolvedModelSelection;
 export declare function resolveSameProviderModelRoute(model: string | undefined, parentProviderId: string): {
     model: string | "inherit";

package/dist/agent/categories.js

@@ -1,16 +1,9 @@
-const THINKING_LEVELS = new Set([
-    "off",
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max",
-]);
+import { THINKING_LEVELS } from "../types.js";
+export const TIER_RANK = { fast: 0, balanced: 1, strong: 2 };
 const BUILTIN_CATEGORIES = {
-    quick: { model: "inherit", thinkingLevel: "low", maxConcurrent: 3 },
+    quick: { model: "inherit", tier: "fast", thinkingLevel: "low", maxConcurrent: 3 },
+    explore: { model: "inherit", tier: "fast", thinkingLevel: "low", maxConcurrent: 3 },
     deep: { model: "inherit", thinkingLevel: "high", maxConcurrent: 2 },
-    explore: { model: "inherit", thinkingLevel: "low", maxConcurrent: 3 },
     review: { model: "inherit", thinkingLevel: "high", maxConcurrent: 2 },
     frontend: { model: "inherit", thinkingLevel: "high", maxConcurrent: 1 },
     writing: { model: "inherit", thinkingLevel: "medium", maxConcurrent: 2 },
@@ -28,6 +21,36 @@ export function mergeAgentCategories(userCategories) {
     }
     return merged;
 }
+/**
+ * Field-level merge with provenance (§3.3). The merge itself is identical to
+ * mergeAgentCategories; provenance records whether the user literally wrote
+ * `tier` / `model`, so builtin tiers flowing through a partial override never
+ * masquerade as user intent.
+ */
+export function mergeAgentCategoriesWithProvenance(userCategories) {
+    const sanitizedUser = sanitizeAgentCategories(userCategories);
+    const out = {};
+    for (const [name, config] of Object.entries(builtinAgentCategories())) {
+        out[name] = {
+            config: { ...config },
+            provenance: {
+                tierSource: config.tier !== undefined ? "builtin" : undefined,
+                modelSource: config.model !== undefined && config.model !== "inherit" ? "builtin" : undefined,
+            },
+        };
+    }
+    for (const [name, config] of Object.entries(sanitizedUser)) {
+        const existing = out[name] ?? { config: {}, provenance: {} };
+        out[name] = {
+            config: { ...existing.config, ...config },
+            provenance: {
+                tierSource: config.tier !== undefined ? "user" : existing.provenance.tierSource,
+                modelSource: config.model !== undefined ? "user" : existing.provenance.modelSource,
+            },
+        };
+    }
+    return out;
+}
 export function sanitizeAgentCategories(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return {};
@@ -41,6 +64,9 @@ export function sanitizeAgentCategories(value) {
         if (typeof record.model === "string" && record.model.trim()) {
             config.model = record.model.trim();
         }
+        if (isCategoryTier(record.tier)) {
+            config.tier = record.tier;
+        }
         if (isThinkingLevel(record.thinkingLevel)) {
             config.thinkingLevel = record.thinkingLevel;
         }
@@ -51,27 +77,99 @@ export function sanitizeAgentCategories(value) {
     }
     return out;
 }
-export function resolveSubagentRoute(category, parent, categories) {
+export function resolveSubagentRoute(category, parent, categories, tierContext) {
     const normalizedCategory = normalizeCategoryName(category);
     if (!normalizedCategory) {
         return { route: { ...parent, inherited: true } };
     }
-    const merged = mergeAgentCategories(categories);
-    const config = merged[normalizedCategory];
-    if (!config) {
+    const merged = mergeAgentCategoriesWithProvenance(categories);
+    const entry = merged[normalizedCategory];
+    if (!entry) {
         return { error: `Unknown subagent category "${normalizedCategory}".` };
     }
+    const { config, provenance } = entry;
+    // Explicit model binding wins over tier (config surface contract §3.1).
     const modelSelection = parseModelSelection(config.model, parent.providerId);
+    if (modelSelection.model !== "inherit") {
+        return {
+            route: {
+                category: normalizedCategory,
+                providerId: modelSelection.providerId,
+                model: modelSelection.model,
+                thinkingLevel: config.thinkingLevel ?? parent.thinkingLevel,
+                inherited: false,
+                categoryModelSource: provenance.modelSource === "user" ? "user-category" : "builtin-tier",
+            },
+        };
+    }
+    // Tier binding: rank-guarded for builtin-sourced tiers, free for
+    // user-authored ones (§3.2).
+    const tierModel = resolveTierModel(config.tier, provenance.tierSource, tierContext);
+    if (tierModel) {
+        return {
+            route: {
+                category: normalizedCategory,
+                providerId: parent.providerId,
+                model: tierModel,
+                thinkingLevel: config.thinkingLevel ?? parent.thinkingLevel,
+                inherited: false,
+                categoryModelSource: provenance.tierSource === "user" ? "user-category" : "builtin-tier",
+            },
+        };
+    }
     return {
         route: {
             category: normalizedCategory,
-            providerId: modelSelection.providerId,
-            model: modelSelection.model === "inherit" ? parent.model : modelSelection.model,
+            providerId: parent.providerId,
+            model: parent.model,
             thinkingLevel: config.thinkingLevel ?? parent.thinkingLevel,
-            inherited: modelSelection.model === "inherit" && config.thinkingLevel === undefined,
+            inherited: config.thinkingLevel === undefined,
         },
     };
 }
+/**
+ * Rank-guarded tier -> model resolution (§3.2). Returns undefined whenever
+ * the route must inherit: no tier context wired, kill switch off (builtin
+ * tiers only), unknown parent tier, missing target tier, or a target that is
+ * not strictly cheaper than the parent.
+ */
+function resolveTierModel(tier, tierSource, tierContext) {
+    if (!tier || tier === "inherit" || !tierContext)
+        return undefined;
+    const candidates = selectTierCandidates(tierContext.models, tier);
+    if (candidates.length === 0)
+        return undefined;
+    if (tierSource !== "user") {
+        // Builtin-sourced tier: downgrade-only, enforced by rank comparison.
+        if (!tierContext.autoTier)
+            return undefined;
+        if (!tierContext.parentTier)
+            return undefined;
+        if (TIER_RANK[tier] >= TIER_RANK[tierContext.parentTier])
+            return undefined;
+    }
+    return candidates[0].id;
+}
+/**
+ * Deterministic within-tier ordering (§3.2): user routingPriority, then
+ * builtin catalog order, then normalized id — never a remote response's
+ * array order.
+ */
+export function selectTierCandidates(models, tier) {
+    return models
+        .filter((entry) => entry.tier === tier)
+        .sort((a, b) => {
+        const priorityA = a.routingPriority ?? Number.POSITIVE_INFINITY;
+        const priorityB = b.routingPriority ?? Number.POSITIVE_INFINITY;
+        if (priorityA !== priorityB)
+            return priorityA - priorityB;
+        const builtinA = a.builtinIndex ?? Number.POSITIVE_INFINITY;
+        const builtinB = b.builtinIndex ?? Number.POSITIVE_INFINITY;
+        if (builtinA !== builtinB)
+            return builtinA - builtinB;
+        return a.id.localeCompare(b.id);
+    });
+}
 export function resolveModelRoute(model, parentProviderId) {
     return parseModelSelection(model, parentProviderId);
 }
@@ -95,7 +193,10 @@ function parseModelSelection(model, parentProviderId) {
     return { providerId: parentProviderId, model };
 }
 function isThinkingLevel(value) {
-    return typeof value === "string" && THINKING_LEVELS.has(value);
+    return typeof value === "string" && THINKING_LEVELS.includes(value);
+}
+function isCategoryTier(value) {
+    return value === "fast" || value === "balanced" || value === "strong" || value === "inherit";
 }
 function cloneCategories(categories) {
     return Object.fromEntries(Object.entries(categories).map(([name, config]) => [name, { ...config }]));

package/dist/agent/discovery-barrier.js

@@ -46,7 +46,7 @@ export class DiscoveryBarrier {
             return undefined;
         return {
             content: `Blocked speculative ${target.kind}. The path "${target.path}" has not been discovered in this repository context ` +
-                "and was not explicitly requested by the user. Run glob/grep/lsp discovery first, then read only returned paths. " +
+                "and was not explicitly requested by the user. Run glob/grep discovery first, then read only returned paths. " +
                 "Do not infer from this blocked call whether the path exists.",
             isError: true,
             status: "blocked",

package/dist/agent/profiles.d.ts

@@ -67,3 +67,4 @@ export declare function allowedToolEffectsForMode(mode: AgentProfileMode): Set<s
 export declare function selectToolsForAgentProfile(tools: ToolRegistryEntry[], profile: AgentProfile, approval?: AgentProfileApproval): ToolRegistryEntry[];
 export declare function validateAgentProfileTools(tools: ToolRegistryEntry[], profile: AgentProfile, approval?: AgentProfileApproval): AgentProfileDiagnostic[];
 export declare function mergeUsage(current: SubagentRunResult["usage"], usage: TokenUsage): SubagentRunResult["usage"];
+export declare function canonicalToolName(name: string): string;

package/dist/agent/profiles.js

@@ -10,14 +10,12 @@ const READONLY_PRESET = [
     "lsp",
     "web_search",
     "web_fetch",
-    "memory_search",
-    "memory_read_summary",
+    "memory",
     "skill",
     "todo_write",
 ];
 const SUBAGENT_DENY_TOOLS = new Set([
     "subagent",
-    "task",
     "spawn_agent",
     "wait_agent",
     "send_input",
@@ -126,12 +124,12 @@ export function builtinAgentProfiles() {
             "You are an explorer subagent for codebase reconnaissance.",
             "Answer the specific question by inspecting the repository directly. Prefer precise file paths and line-level evidence.",
             "Keep the answer compact and avoid broad refactors or implementation plans unless asked.",
-        ].join("\n"), ["read", "glob", "grep", "lsp", "memory_search", "memory_read_summary", "skill", "todo_write"]),
+        ].join("\n"), ["read", "glob", "grep", "lsp", "memory", "skill", "todo_write"]),
         roleProfile("worker", "Implementation-planning worker subagent", [
             "You are a worker subagent. In this Phase 1 runtime you are read-only, so you must not modify files.",
             "Analyze the assigned implementation slice, identify exact files to change, and return a concrete patch plan or findings.",
             "If write-capable worker mode is needed, say so explicitly.",
-        ].join("\n"), ["read", "glob", "grep", "lsp", "memory_search", "memory_read_summary", "skill", "todo_write"]),
+        ].join("\n"), ["read", "glob", "grep", "lsp", "memory", "skill", "todo_write"]),
         toProfile("search"),
         toProfile("security_investigation"),
         toProfile("evidence_correlation"),
@@ -167,7 +165,7 @@ export function allowedToolEffectsForMode(mode) {
         : new Set(["read"]);
 }
 export function selectToolsForAgentProfile(tools, profile, approval = profile.approval) {
-    const explicitInclude = new Set(profile.tools.include ?? []);
+    const explicitInclude = new Set((profile.tools.include ?? []).map(canonicalToolName));
     const selected = requestedToolNames(profile);
     for (const tool of SUBAGENT_DENY_TOOLS)
         selected.delete(tool);
@@ -183,13 +181,17 @@ export function selectToolsForAgentProfile(tools, profile, approval = profile.ap
             continue;
         if (approval === "disabled" && tool.requiresApproval)
             continue;
-        out.push(wrapApprovalFailTool(tool, approval));
+        // Explicit include is the profile author pre-unlocking the tool: the
+        // child is a fresh Agent with its own (empty) unlock set, so a deferred
+        // flag surviving here would re-lock the tool inside the child.
+        const entry = tool.deferred ? { ...tool, deferred: false } : tool;
+        out.push(wrapApprovalFailTool(entry, approval));
     }
     return out;
 }
 export function validateAgentProfileTools(tools, profile, approval = profile.approval) {
     const available = new Map(tools.map((tool) => [tool.name, tool]));
-    const explicitInclude = new Set(profile.tools.include ?? []);
+    const explicitInclude = new Set((profile.tools.include ?? []).map(canonicalToolName));
     const allowedEffects = allowedToolEffectsForMode(profile.mode);
     const diagnostics = [];
     for (const name of requestedToolNames(profile)) {
@@ -256,6 +258,18 @@ function wrapApprovalFailTool(tool, approval) {
         }),
     };
 }
+/**
+ * Renamed/merged tools keep working for user-defined profiles written
+ * against the old names (memory_search/memory_read_summary merged into
+ * "memory", 2026-07-13).
+ */
+const LEGACY_TOOL_ALIASES = {
+    memory_search: "memory",
+    memory_read_summary: "memory",
+};
+export function canonicalToolName(name) {
+    return LEGACY_TOOL_ALIASES[name] ?? name;
+}
 function requestedToolNames(profile) {
     const selected = new Set();
     if (profile.tools.preset === "readonly") {
@@ -264,12 +278,12 @@ function requestedToolNames(profile) {
     }
     else if (profile.tools.preset === "explicit") {
         for (const tool of profile.tools.include ?? [])
-            selected.add(tool);
+            selected.add(canonicalToolName(tool));
     }
     for (const tool of profile.tools.include ?? [])
-        selected.add(tool);
+        selected.add(canonicalToolName(tool));
     for (const tool of profile.tools.exclude ?? [])
-        selected.delete(tool);
+        selected.delete(canonicalToolName(tool));
     return selected;
 }
 function loadProfilesFromDir(dir, source, diagnostics) {

package/dist/agent/routing-catalog.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Routing catalog: the single source of catalog truth for subagent model
+ * routing (docs/model-routing-design.md §1).
+ *
+ * No routing consumer reads `listBuiltinModels` / `getConfigured` directly —
+ * neither reflects what is actually runnable. Consumers read a
+ * `RoutingSnapshot` through the live accessor created here; the accessor
+ * caches by the registry's routing revision and rebuilds lazily, so tier
+ * resolution, validation, the detector, and the menu are never stale (§1.5).
+ */
+import { type ModelTier } from "../model-catalog.js";
+import type { ProviderRegistry } from "../provider-registry.js";
+import { selectTierCandidates, type AgentCategoriesConfig, type TierRoutingContext } from "./categories.js";
+import type { ThinkingLevel } from "../types.js";
+export interface AgentRoutingConfig {
+    /** Automatic builtin-tier downgrade routing (§3.2). */
+    autoTier: boolean;
+    /** Call-site cross-provider routing; default open, set false to lock (§7.2). */
+    allowCrossProvider: boolean;
+}
+export declare const DEFAULT_AGENT_ROUTING: AgentRoutingConfig;
+export declare function sanitizeAgentRouting(value: unknown): AgentRoutingConfig;
+export interface RoutingModelEntry {
+    id: string;
+    name: string;
+    tier?: ModelTier;
+    routingPriority?: number;
+    /** Index in the builtin catalog order, when the id is builtin (§3.2 tiebreak). */
+    builtinIndex?: number;
+    source: "builtin" | "dynamic" | "custom";
+}
+export type RoutingMembershipSource = "custom-allowlist" | "complete-discovery" | "fallback-union";
+export interface RoutingSnapshot {
+    parent: {
+        providerId: string;
+        model: string;
+        tier?: ModelTier;
+    };
+    /** Catalog-effective provider id (openai OAuth -> "openai-codex" alias). */
+    effectiveProviderId: string;
+    membershipSource: RoutingMembershipSource;
+    /** Model list for the PARENT provider only (§1.2 scope note). */
+    models: RoutingModelEntry[];
+    /** True iff membershipSource === "custom-allowlist" — the only catalog
+     *  that hard-rejects unknown ids (§1.4). */
+    authoritative: boolean;
+    registryRevision: number;
+    /**
+     * Earliest expiry of the discovery data this snapshot consumed. TTL expiry
+     * is passive — it bumps no revision — so the accessor must rebuild past
+     * this instant or it serves a catalog the registry itself no longer would.
+     */
+    discoveryExpiresAt?: number;
+    /** Provider ids with active credentials (getEnabled, §1.1). */
+    runnableProviderIds: string[];
+    /** Post-merge, post-tier-resolution category bindings (§3). */
+    resolvedCategories: Array<{
+        name: string;
+        model: string | "inherit";
+        thinkingLevel?: ThinkingLevel;
+        tierSource?: "builtin" | "user";
+    }>;
+}
+export type RoutingSnapshotAccessor = (parent: {
+    providerId: string;
+    model: string;
+}) => RoutingSnapshot;
+/**
+ * Membership versus metadata (§1.3): an authoritative source alone decides
+ * which ids exist; lower-priority sources only enrich per-field metadata
+ * (tier: dynamic ?? custom ?? builtin).
+ */
+export declare function buildRoutingSnapshot(registry: ProviderRegistry, parent: {
+    providerId: string;
+    model: string;
+}, agentCategories: AgentCategoriesConfig, agentRouting: AgentRoutingConfig): RoutingSnapshot;
+/** Tier-resolution context derived from a snapshot (consumed by categories §3.2). */
+export declare function tierContextFromSnapshot(snapshot: RoutingSnapshot, agentRouting: AgentRoutingConfig): TierRoutingContext;
+/**
+ * Live accessor (§1.5): caches by (routing revision, parent route) and
+ * rebuilds lazily, so a discovery completion or provider mutation is
+ * reflected at the very next read. Building is synchronous over cached
+ * registry state — microseconds, never I/O.
+ */
+export declare function createRoutingSnapshotAccessor(registry: ProviderRegistry, getAgentCategories: () => AgentCategoriesConfig, getAgentRouting: () => AgentRoutingConfig): RoutingSnapshotAccessor;
+/** Tier of a model within a snapshot, when known. */
+export declare function snapshotModelTier(snapshot: RoutingSnapshot, modelId: string): ModelTier | undefined;
+export interface RoutableModelEntry {
+    /** Routable provider id — what goes before the colon in provider:model. */
+    providerId: string;
+    id: string;
+    name: string;
+}
+export type RoutableModelIndex = () => RoutableModelEntry[];
+/** Revision-cached index over all runnable providers' catalogs. */
+export declare function createRoutableModelIndex(registry: ProviderRegistry): RoutableModelIndex;
+/** Loose normalization for model-name matching: case/punctuation-insensitive. */
+export declare function normalizeModelToken(value: string): string;
+/**
+ * Near-match candidates for a (probably mistyped) model id within one
+ * provider's catalog. "suggest" matches normalized prefixes in either
+ * direction (soft "did you mean" notes). "truncation" matches only inputs
+ * the catalog EXTENDS ("gpt-5.6" -> gpt-5.6-sol/-terra/-luna) — the one
+ * direction that is typo evidence. An input extending a catalog id
+ * (gpt-5.6-sol-20260701 vs cataloged gpt-5.6-sol) is more likely a newly
+ * released variant the local catalog lags on, and must not be treated as a
+ * typo by hard-reject paths. Capped, deterministic order.
+ */
+export declare function nearModelMatches(input: string, candidates: RoutableModelEntry[], options?: {
+    limit?: number;
+    mode?: "suggest" | "truncation";
+}): string[];
+export { selectTierCandidates };