@vellumai/assistant 0.5.1 → 0.5.2

package/src/oauth/seed-providers.ts

@@ -5,9 +5,11 @@ import { seedProviders } from "./oauth-store.js";
  *
  * These values are upserted into the `oauth_providers` SQLite table on
  * every startup. Only Vellum implementation fields (authUrl, tokenUrl,
- * tokenEndpointAuthMethod, extraParams, callbackTransport, pingUrl) are
- * overwritten on subsequent startups — user-customizable
- * fields (defaultScopes, scopePolicy, userinfoUrl, baseUrl) are only
+ * tokenEndpointAuthMethod, userinfoUrl, extraParams, callbackTransport,
+ * pingUrl, managedServiceConfigKey) and display metadata (displayName,
+ * description, dashboardUrl, clientIdPlaceholder, requiresClientSecret)
+ * are overwritten on subsequent startups — user-customizable
+ * fields (defaultScopes, scopePolicy, baseUrl) are only
  * written on initial insert and preserved across restarts.
  *
  * Code-side behavioral fields (identityVerifier, injectionTemplates,
@@ -32,6 +34,12 @@ const PROVIDER_SEED_DATA: Record<
     };
     extraParams?: Record<string, string>;
     callbackTransport?: string;
+    managedServiceConfigKey?: string;
+    displayName: string;
+    description: string;
+    dashboardUrl: string | null;
+    clientIdPlaceholder: string | null;
+    requiresClientSecret?: boolean;
   }
 > = {
   "integration:google": {
@@ -41,6 +49,10 @@ const PROVIDER_SEED_DATA: Record<
     userinfoUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
     pingUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
     baseUrl: "https://gmail.googleapis.com/gmail/v1/users/me",
+    displayName: "Google",
+    description: "Gmail, Calendar, and Contacts",
+    dashboardUrl: "https://console.cloud.google.com/apis/credentials",
+    clientIdPlaceholder: "123456789.apps.googleusercontent.com",
     defaultScopes: [
       "https://www.googleapis.com/auth/gmail.readonly",
       "https://www.googleapis.com/auth/gmail.modify",
@@ -60,6 +72,7 @@ const PROVIDER_SEED_DATA: Record<
     },
     extraParams: { access_type: "offline", prompt: "consent" },
     callbackTransport: "loopback",
+    managedServiceConfigKey: "google-oauth",
   },
 
   "integration:slack": {
@@ -68,6 +81,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://slack.com/api/oauth.v2.access",
     pingUrl: "https://slack.com/api/auth.test",
     baseUrl: "https://slack.com/api",
+    displayName: "Slack",
+    description: "Workspace messaging",
+    dashboardUrl: "https://api.slack.com/apps",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "channels:read",
       "channels:history",
@@ -101,6 +118,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.notion.com/v1/oauth/token",
     pingUrl: "https://api.notion.com/v1/users/me",
     baseUrl: "https://api.notion.com",
+    displayName: "Notion",
+    description: "Pages and databases",
+    dashboardUrl: "https://www.notion.so/my-integrations",
+    clientIdPlaceholder: null,
     defaultScopes: [],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -118,6 +139,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.x.com/2/oauth2/token",
     pingUrl: "https://api.x.com/2/users/me",
     baseUrl: "https://api.x.com",
+    displayName: "Twitter",
+    description: "Posts and direct messages",
+    dashboardUrl: "https://developer.twitter.com/en/portal/dashboard",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "tweet.read",
       "tweet.write",
@@ -139,6 +164,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://github.com/login/oauth/access_token",
     pingUrl: "https://api.github.com/user",
     baseUrl: "https://api.github.com",
+    displayName: "GitHub",
+    description: "Repositories and issues",
+    dashboardUrl: "https://github.com/settings/developers",
+    clientIdPlaceholder: null,
     defaultScopes: ["repo", "read:user", "notifications"],
     scopePolicy: {
       allowAdditionalScopes: true,
@@ -159,6 +188,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.linear.app/oauth/token",
     pingUrl: "https://api.linear.app/graphql",
     baseUrl: "https://api.linear.app",
+    displayName: "Linear",
+    description: "Issues and projects",
+    dashboardUrl: "https://linear.app/settings/api",
+    clientIdPlaceholder: null,
     defaultScopes: ["read", "write", "issues:create"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -175,6 +208,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://accounts.spotify.com/api/token",
     pingUrl: "https://api.spotify.com/v1/me",
     baseUrl: "https://api.spotify.com/v1",
+    displayName: "Spotify",
+    description: "Music and playlists",
+    dashboardUrl: "https://developer.spotify.com/dashboard",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "user-read-playback-state",
       "user-modify-playback-state",
@@ -201,6 +238,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://todoist.com/oauth/access_token",
     pingUrl: "https://api.todoist.com/rest/v2/projects",
     baseUrl: "https://api.todoist.com/rest/v2",
+    displayName: "Todoist",
+    description: "Tasks and projects",
+    dashboardUrl: "https://developer.todoist.com/appconsole.html",
+    clientIdPlaceholder: null,
     defaultScopes: ["data:read_write"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -216,6 +257,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://discord.com/api/v10/oauth2/token",
     pingUrl: "https://discord.com/api/v10/users/@me",
     baseUrl: "https://discord.com/api/v10",
+    displayName: "Discord",
+    description: "Servers and messages",
+    dashboardUrl: "https://discord.com/developers/applications",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "identify",
       "guilds",
@@ -236,6 +281,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.dropboxapi.com/oauth2/token",
     pingUrl: "https://api.dropboxapi.com/2/users/get_current_account",
     baseUrl: "https://api.dropboxapi.com/2",
+    displayName: "Dropbox",
+    description: "Files and folders",
+    dashboardUrl: "https://www.dropbox.com/developers/apps",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "files.metadata.read",
       "files.content.read",
@@ -257,6 +306,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://app.asana.com/-/oauth_token",
     pingUrl: "https://app.asana.com/api/1.0/users/me",
     baseUrl: "https://app.asana.com/api/1.0",
+    displayName: "Asana",
+    description: "Tasks and projects",
+    dashboardUrl: "https://app.asana.com/0/my-apps",
+    clientIdPlaceholder: null,
     defaultScopes: ["default"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -272,6 +325,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://airtable.com/oauth2/v1/token",
     pingUrl: "https://api.airtable.com/v0/meta/whoami",
     baseUrl: "https://api.airtable.com/v0",
+    displayName: "Airtable",
+    description: "Bases and records",
+    dashboardUrl: "https://airtable.com/create/tokens",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "data.records:read",
       "data.records:write",
@@ -292,6 +349,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.hubapi.com/oauth/v1/token",
     pingUrl: "https://api.hubapi.com/crm/v3/objects/contacts?limit=1",
     baseUrl: "https://api.hubapi.com",
+    displayName: "HubSpot",
+    description: "CRM contacts and deals",
+    dashboardUrl: "https://developers.hubspot.com/",
+    clientIdPlaceholder: null,
     defaultScopes: [
       "crm.objects.contacts.read",
       "crm.objects.contacts.write",
@@ -316,6 +377,10 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "https://api.figma.com/v1/oauth/token",
     pingUrl: "https://api.figma.com/v1/me",
     baseUrl: "https://api.figma.com/v1",
+    displayName: "Figma",
+    description: "Design files and comments",
+    dashboardUrl: "https://www.figma.com/developers/apps",
+    clientIdPlaceholder: null,
     defaultScopes: ["files:read", "file_comments:write"],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -335,6 +400,11 @@ const PROVIDER_SEED_DATA: Record<
     tokenUrl: "urn:manual-token",
     pingUrl: "https://slack.com/api/auth.test",
     baseUrl: "https://slack.com/api",
+    displayName: "Slack Channel",
+    description: "Channel bot token",
+    dashboardUrl: null,
+    clientIdPlaceholder: null,
+    requiresClientSecret: false,
     defaultScopes: [],
     scopePolicy: {
       allowAdditionalScopes: false,
@@ -348,6 +418,11 @@ const PROVIDER_SEED_DATA: Record<
     authUrl: "urn:manual-token",
     tokenUrl: "urn:manual-token",
     baseUrl: "https://api.telegram.org",
+    displayName: "Telegram",
+    description: "Bot messaging",
+    dashboardUrl: null,
+    clientIdPlaceholder: null,
+    requiresClientSecret: false,
     defaultScopes: [],
     scopePolicy: {
       allowAdditionalScopes: false,

package/src/oauth/token-persistence.ts

@@ -28,9 +28,8 @@ import {
 import { runPostConnectHook } from "../tools/credentials/post-connect-hooks.js";
 import {
   createConnection,
+  getActiveConnection,
   getApp,
-  getConnectionByProvider,
-  getConnectionByProviderAndAccount,
   listActiveConnectionsByProvider,
   updateConnection,
   upsertApp,
@@ -59,8 +58,12 @@ export interface StoreOAuth2TokensParams {
   clientId: string;
   clientSecret?: string;
   userinfoUrl?: string;
-  /** Fallback account info from an identity verifier (e.g. @username, email). */
-  identityAccountInfo?: string;
+  /**
+   * Best-effort account identifier parsed from the provider's identity
+   * endpoint (e.g. email, @username, display name). The format varies by
+   * provider and may be undefined if the API call fails.
+   */
+  parsedAccountIdentifier?: string;
   /** Pre-resolved oauth_app ID — skips the upsertApp() call if provided. */
   oauthAppId?: string;
 }
@@ -94,6 +97,10 @@ export async function storeOAuth2Tokens(
     ? Date.now() + tokens.expiresIn * 1000
     : null;
 
+  // Account identifier parsing is best-effort. The format varies by provider
+  // (email for Google, username for GitHub, display name for Spotify, etc.)
+  // and may be undefined if the userinfo/identity API call fails or the
+  // required scope wasn't granted.
   let accountInfo: string | undefined;
   if (userinfoUrl && grantedScopes.some((s) => s.includes("userinfo"))) {
     try {
@@ -109,7 +116,7 @@ export async function storeOAuth2Tokens(
     }
   }
 
-  const resolvedAccountInfo = accountInfo ?? params.identityAccountInfo;
+  const resolvedAccountInfo = accountInfo ?? params.parsedAccountIdentifier;
 
   // -------------------------------------------------------------------
   // SQLite oauth_app + oauth_connection + new-format secure keys
@@ -144,12 +151,11 @@ export async function storeOAuth2Tokens(
   //    lookup so that re-auth without userinfo still updates the right row.
   //    However, treat provider-only matches as ambiguous when multiple active
   //    connections exist to avoid overwriting the wrong account's tokens.
-  let existingConn: ReturnType<typeof getConnectionByProvider>;
+  let existingConn: ReturnType<typeof getActiveConnection>;
   if (resolvedAccountInfo) {
-    existingConn = getConnectionByProviderAndAccount(
-      service,
-      resolvedAccountInfo,
-    );
+    existingConn = getActiveConnection(service, {
+      account: resolvedAccountInfo,
+    });
   } else {
     const activeConns = listActiveConnectionsByProvider(service);
     // Only reuse the provider-only match when it's unambiguous (single connection).

package/src/permissions/checker.ts

@@ -144,6 +144,7 @@ const LOW_RISK_PROGRAMS = new Set([
   "du",
   "df",
   "assistant",
+  "vellum",
 ]);
 
 // High-risk shell programs / patterns
@@ -197,6 +198,32 @@ const LOW_RISK_GIT_SUBCOMMANDS = new Set([
   "reflog",
 ]);
 
+// Mutating assistant/vellum CLI subcommands that should be escalated to Medium
+// risk. Most assistant/vellum subcommands are read-only and stay Low risk.
+// This mirrors the git subcommand pattern — only known mutating operations
+// get escalated.
+const MEDIUM_RISK_CLI_SUBCOMMANDS = new Set([
+  "credentials",
+  "config",
+  "bash",
+  "trust",
+  "autonomy",
+  "contacts",
+  "mcp",
+  "keys",
+  "wake",
+  "sleep",
+  "hatch",
+  "retire",
+  "clean",
+  "setup",
+  "upgrade",
+  "recover",
+  "login",
+  "use",
+  "pair",
+]);
+
 // Commands that wrap another program — the real program appears as the first
 // non-flag argument.  When one of these is the segment program we look through
 // its args to find the effective program (e.g. `env curl …` → curl).
@@ -219,15 +246,40 @@ const WRAPPER_PROGRAMS = new Set([
 // value of -u) as the wrapped program instead of `echo`.
 const ENV_VALUE_FLAGS = new Set(["-u", "--unset", "-C", "--chdir"]);
 
+// `git` global flags that consume the next positional argument as their value.
+// Without this, `git -C status commit` would incorrectly identify `status`
+// (the directory path) as the subcommand instead of `commit`.
+const GIT_VALUE_FLAGS = new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--super-prefix",
+  "--config-env",
+]);
+
 /**
- * Return the first non-flag argument from an argument list.
- * Flags are arguments that start with `-`.  This is used to skip global
- * options (e.g. `--verbose`, `-h`) when extracting the subcommand from
- * CLIs like `git`, `vellum`, and `assistant`.
+ * Return the first non-flag argument from an argument list, optionally
+ * skipping value-taking flags.  Flags are arguments that start with `-`.
+ * This is used to skip global options (e.g. `--verbose`, `-h`, `-C <path>`)
+ * when extracting the subcommand from CLIs like `git`, `vellum`, and
+ * `assistant`.
+ *
+ * When `valueFlags` is provided, any flag in that set causes the next
+ * argument to be skipped as well (it is the flag's value, not a positional).
  */
-function firstPositionalArg(args: string[]): string | undefined {
-  for (const arg of args) {
-    if (!arg.startsWith("-")) return arg;
+function firstPositionalArg(
+  args: string[],
+  valueFlags?: Set<string>,
+): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("-")) {
+      if (valueFlags?.has(arg)) i++; // skip the next arg (the flag's value)
+      continue;
+    }
+    return arg;
   }
   return undefined;
 }
@@ -652,7 +704,7 @@ async function classifyRiskUncached(
       }
 
       if (prog === "git") {
-        const subcommand = firstPositionalArg(seg.args);
+        const subcommand = firstPositionalArg(seg.args, GIT_VALUE_FLAGS);
         if (subcommand && LOW_RISK_GIT_SUBCOMMANDS.has(subcommand)) {
           // Stay at current risk
           continue;
@@ -662,6 +714,17 @@ async function classifyRiskUncached(
         continue;
       }
 
+      if (prog === "vellum" || prog === "assistant") {
+        const subcommand = firstPositionalArg(seg.args);
+        if (subcommand && MEDIUM_RISK_CLI_SUBCOMMANDS.has(subcommand)) {
+          // Known mutating subcommands are medium
+          maxRisk = RiskLevel.Medium;
+          continue;
+        }
+        // Read-only / unknown subcommands stay at current risk
+        continue;
+      }
+
       if (!LOW_RISK_PROGRAMS.has(prog)) {
         // Unknown program → medium
         if (maxRisk === RiskLevel.Low) {

package/src/prompts/templates/BOOTSTRAP.md

@@ -208,6 +208,8 @@ Once you've completed Phase 1 and made reasonable progress through Phase 2, you'
 
 If you still haven't shown the two suggestions (Phase 2 step 4), do that before wrapping.
 
+When you're confident onboarding is complete, delete `BOOTSTRAP.md` so it doesn't re-trigger on the next conversation.
+
 ---
 
 _Good luck out there. Make it count._

package/src/providers/anthropic/client.ts

@@ -16,6 +16,9 @@ import type {
 
 const log = getLogger("anthropic-client");
 
+/** Validation-specific timeout (10s) so a stalled network doesn't block key submission. */
+const VALIDATION_TIMEOUT_MS = 10_000;
+
 /**
  * Validate an Anthropic API key by making a lightweight GET /v1/models call.
  * Returns `{ valid: true }` on success or `{ valid: false, reason: string }` on failure.
@@ -24,7 +27,11 @@ export async function validateAnthropicApiKey(
   apiKey: string,
 ): Promise<{ valid: true } | { valid: false; reason: string }> {
   try {
-    const client = new Anthropic({ apiKey });
+    const client = new Anthropic({
+      apiKey,
+      timeout: VALIDATION_TIMEOUT_MS,
+      maxRetries: 0,
+    });
     await client.models.list({ limit: 1 });
     return { valid: true };
   } catch (error) {

package/src/providers/failover.ts

@@ -133,7 +133,10 @@ export class FailoverProvider implements Provider {
           );
           health.unhealthySince = null;
         }
-        return response;
+        return {
+          ...response,
+          actualProvider: response.actualProvider ?? provider.name,
+        };
       } catch (error) {
         lastError = error;
 

package/src/providers/gemini/client.ts

@@ -3,6 +3,7 @@ import { ApiError, GoogleGenAI } from "@google/genai";
 
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "../../prompts/cache-boundary.js";
 import { ProviderError } from "../../util/errors.js";
+import { getLogger } from "../../util/logger.js";
 import { createStreamTimeout } from "../stream-timeout.js";
 import type {
   ContentBlock,
@@ -13,6 +14,55 @@ import type {
   ToolDefinition,
 } from "../types.js";
 
+const log = getLogger("gemini-client");
+
+/** Validation-specific timeout (10s) so a stalled network doesn't block key submission. */
+const VALIDATION_TIMEOUT_MS = 10_000;
+
+/**
+ * Validate a Gemini API key by making a lightweight models.list() call.
+ * Returns `{ valid: true }` on success or `{ valid: false, reason: string }` on failure.
+ */
+export async function validateGeminiApiKey(
+  apiKey: string,
+): Promise<{ valid: true } | { valid: false; reason: string }> {
+  try {
+    const client = new GoogleGenAI({ apiKey });
+    await client.models.list({
+      config: {
+        pageSize: 1,
+        httpOptions: { timeout: VALIDATION_TIMEOUT_MS },
+      },
+    });
+    return { valid: true };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      if (error.status === 401) {
+        return { valid: false, reason: "API key is invalid or expired." };
+      }
+      if (error.status === 403) {
+        return {
+          valid: false,
+          reason: `Gemini API error (${error.status}): ${error.message}`,
+        };
+      }
+      // Transient errors (429, 5xx, etc.) — validation is inconclusive,
+      // allow the key to be stored rather than blocking the user.
+      log.warn(
+        { status: error.status },
+        "Gemini API returned a transient error during key validation — allowing key storage",
+      );
+      return { valid: true };
+    }
+    // Network errors — validation is inconclusive, allow key storage.
+    log.warn(
+      { error: error instanceof Error ? error.message : String(error) },
+      "Network error during Gemini key validation — allowing key storage",
+    );
+    return { valid: true };
+  }
+}
+
 export interface GeminiProviderOptions {
   streamTimeoutMs?: number;
   /** When set, routes requests through the managed proxy at this base URL. */

package/src/providers/model-catalog.ts

@@ -0,0 +1,92 @@
+export interface CatalogModel {
+  id: string;
+  displayName: string;
+}
+
+export interface ProviderCatalogEntry {
+  id: string;
+  displayName: string;
+  models: CatalogModel[];
+  defaultModel: string;
+  apiKeyUrl?: string;
+  apiKeyPlaceholder?: string;
+}
+
+/** Single source of truth for all inference provider metadata and models. */
+export const PROVIDER_CATALOG: ProviderCatalogEntry[] = [
+  {
+    id: "anthropic",
+    displayName: "Anthropic",
+    models: [
+      { id: "claude-opus-4-6", displayName: "Claude Opus 4.6" },
+      { id: "claude-sonnet-4-6", displayName: "Claude Sonnet 4.6" },
+      { id: "claude-haiku-4-5-20251001", displayName: "Claude Haiku 4.5" },
+    ],
+    defaultModel: "claude-opus-4-6",
+    apiKeyUrl: "https://console.anthropic.com/settings/keys",
+    apiKeyPlaceholder: "sk-ant-api03-...",
+  },
+  {
+    id: "openai",
+    displayName: "OpenAI",
+    models: [
+      { id: "gpt-5.4", displayName: "GPT-5.4" },
+      { id: "gpt-5.2", displayName: "GPT-5.2" },
+      { id: "gpt-5.4-mini", displayName: "GPT-5.4 Mini" },
+      { id: "gpt-5.4-nano", displayName: "GPT-5.4 Nano" },
+    ],
+    defaultModel: "gpt-5.4",
+    apiKeyUrl: "https://platform.openai.com/api-keys",
+    apiKeyPlaceholder: "sk-proj-...",
+  },
+  {
+    id: "gemini",
+    displayName: "Google Gemini",
+    models: [
+      { id: "gemini-3-flash", displayName: "Gemini 3 Flash" },
+      { id: "gemini-3-pro", displayName: "Gemini 3 Pro" },
+    ],
+    defaultModel: "gemini-3-flash",
+    apiKeyUrl: "https://aistudio.google.com/apikey",
+    apiKeyPlaceholder: "AIza...",
+  },
+  {
+    id: "ollama",
+    displayName: "Ollama",
+    models: [
+      { id: "llama3.2", displayName: "Llama 3.2" },
+      { id: "mistral", displayName: "Mistral" },
+    ],
+    defaultModel: "llama3.2",
+  },
+  {
+    id: "fireworks",
+    displayName: "Fireworks",
+    models: [
+      {
+        id: "accounts/fireworks/models/kimi-k2p5",
+        displayName: "Kimi K2.5",
+      },
+    ],
+    defaultModel: "accounts/fireworks/models/kimi-k2p5",
+    apiKeyUrl: "https://fireworks.ai/account/api-keys",
+    apiKeyPlaceholder: "fw_...",
+  },
+  {
+    id: "openrouter",
+    displayName: "OpenRouter",
+    models: [
+      { id: "x-ai/grok-4", displayName: "Grok 4" },
+      { id: "x-ai/grok-4.20-beta", displayName: "Grok 4.20 Beta" },
+    ],
+    defaultModel: "x-ai/grok-4",
+    apiKeyUrl: "https://openrouter.ai/keys",
+    apiKeyPlaceholder: "sk-or-v1-...",
+  },
+];
+
+/** Check if a model ID is in the catalog for a given provider. */
+export function isModelInCatalog(provider: string, modelId: string): boolean {
+  const entry = PROVIDER_CATALOG.find((p) => p.id === provider);
+  return entry?.models.some((m) => m.id === modelId) ?? false;
+}

package/src/providers/model-intents.ts

@@ -1,20 +1,16 @@
+import { isModelInCatalog, PROVIDER_CATALOG } from "./model-catalog.js";
 import type { ModelIntent } from "./types.js";
 
-const PROVIDER_DEFAULT_MODELS = {
-  anthropic: "claude-opus-4-6",
-  openai: "gpt-5.2",
-  gemini: "gemini-3-flash",
-  ollama: "llama3.2",
-  fireworks: "accounts/fireworks/models/kimi-k2p5",
-  openrouter: "x-ai/grok-4",
-} as const;
-
-type KnownProviderName = keyof typeof PROVIDER_DEFAULT_MODELS;
+/**
+ * Derived from PROVIDER_CATALOG — single source of truth for default models.
+ * Each provider's `defaultModel` in the catalog populates this map.
+ */
+export const PROVIDER_DEFAULT_MODELS: Record<string, string> =
+  Object.fromEntries(
+    PROVIDER_CATALOG.map((entry) => [entry.id, entry.defaultModel]),
+  );
 
-const PROVIDER_MODEL_INTENTS: Record<
-  KnownProviderName,
-  Record<ModelIntent, string>
-> = {
+const PROVIDER_MODEL_INTENTS: Record<string, Record<ModelIntent, string>> = {
   anthropic: {
     "latency-optimized": "claude-haiku-4-5-20251001",
     "quality-optimized": "claude-opus-4-6",
@@ -47,29 +43,42 @@ const PROVIDER_MODEL_INTENTS: Record<
   },
 };
 
+const FALLBACK_DEFAULT_MODEL = "claude-opus-4-6";
+
 const MODEL_INTENTS = new Set<ModelIntent>([
   "latency-optimized",
   "quality-optimized",
   "vision-optimized",
 ]);
 
+// ── Consistency validation ───────────────────────────────────────────
+// Eagerly verify that every model ID referenced by PROVIDER_MODEL_INTENTS
+// exists in PROVIDER_CATALOG, catching drift at module-load time rather
+// than at runtime when a user picks a model.
+for (const [provider, intents] of Object.entries(PROVIDER_MODEL_INTENTS)) {
+  for (const [intent, modelId] of Object.entries(intents)) {
+    if (!isModelInCatalog(provider, modelId)) {
+      throw new Error(
+        `PROVIDER_MODEL_INTENTS[${provider}][${intent}] references model "${modelId}" ` +
+          `which is not in PROVIDER_CATALOG. Update model-catalog.ts or model-intents.ts.`,
+      );
+    }
+  }
+}
+
 export function isModelIntent(value: unknown): value is ModelIntent {
   return typeof value === "string" && MODEL_INTENTS.has(value as ModelIntent);
 }
 
 export function getProviderDefaultModel(providerName: string): string {
-  const knownProvider = providerName as KnownProviderName;
-  return (
-    PROVIDER_DEFAULT_MODELS[knownProvider] ?? PROVIDER_DEFAULT_MODELS.anthropic
-  );
+  return PROVIDER_DEFAULT_MODELS[providerName] ?? FALLBACK_DEFAULT_MODEL;
 }
 
 export function resolveModelIntent(
   providerName: string,
   intent: ModelIntent,
 ): string {
-  const knownProvider = providerName as KnownProviderName;
-  const providerIntentModels = PROVIDER_MODEL_INTENTS[knownProvider];
+  const providerIntentModels = PROVIDER_MODEL_INTENTS[providerName];
   if (providerIntentModels) {
     return providerIntentModels[intent];
   }