@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/config/schemas/llm.ts

@@ -11,8 +11,12 @@ import {
   parseVellumModel,
 } from "../../providers/vellum-model-routing.js";
 import {
+  BACKUP_PROFILE_KEYS,
   DEFAULT_PROFILE_KEYS,
   DEFAULT_PROFILE_PROVIDERS,
+  FALLBACK_PROFILE_BY_KEY,
+  isBackupProfileKey,
+  isDefaultProfileKey,
 } from "../default-profile-names.js";
 
 /**
@@ -51,12 +55,13 @@ export const KNOWN_LLM_PROVIDERS = [
   "atlascloud",
   "together",
   "litellm",
+  "opencode",
   "baseten",
   "poolside",
-  // Routing identities rather than adapters: "vellum" = the platform-managed
-  // route (upstream derived from the model at dispatch), "chatgpt" = the
-  // subscription route to OpenAI. Neither has a PROVIDER_CATALOG entry;
-  // dispatch substitutes the real upstream before any adapter lookup.
+  // Routing identities: "vellum" = the platform-managed route (upstream
+  // derived from the model at dispatch) and the catalog owner of
+  // Vellum-hosted GPU models; "chatgpt" = the subscription route to OpenAI.
+  // Dispatch substitutes a concrete upstream before adapter lookup.
   "vellum",
   "chatgpt",
 ] as const;
@@ -82,7 +87,8 @@ export function unknownLlmProviderIssue(provider: string): string | null {
  * connection can serve the shared BYOK templates (fixed base URL, and a
  * non-empty catalog `defaultModel` for the intent fallback in
  * `resolveModelIntent`). Deliberately narrower than `LLMProvider`: keyless
- * (ollama) and endpoint-supplied (openai-compatible, litellm) providers have
+ * (ollama) and endpoint-supplied (openai-compatible, litellm, opencode)
+ * providers have
  * no code-resolvable default profile implementation.
  */
 export const DEFAULT_PROVIDER_CHOICES: readonly LLMProvider[] = [
@@ -629,6 +635,13 @@ export const ProfileEntry = LLMConfigFragment.extend({
    * may accompany `mix`.
    */
   mix: MixSchema.optional(),
+  /**
+   * Code-owned backup profile for a Vellum-managed default profile. This is
+   * read-only metadata from the default-profile catalog. Config write paths
+   * reject user-authored values because custom and BYOK fallback routes are
+   * not supported.
+   */
+  fallbackProfile: z.string().min(1).optional().meta({ readOnly: true }),
 });
 export type ProfileEntry = z.infer<typeof ProfileEntry>;
 
@@ -674,10 +687,210 @@ export type DefaultProviderConfig = z.infer<typeof DefaultProviderSchema>;
  */
 const DefaultProviderField = DefaultProviderSchema.optional().catch(undefined);
 
+/**
+ * Whether the managed backup profiles (`BACKUP_PROFILE_KEYS`) resolve under a
+ * given `llm.defaultProvider`.
+ *
+ * Backups are companions of the managed (`vellum`) column only: on a BYOK or
+ * ChatGPT default provider `defaultProfileBodyForProvider` returns `undefined`
+ * for them, because the install may hold no credential for the backup's
+ * upstream. So a reference to one is a target that can never resolve there,
+ * and the schema must reject it rather than preserve a selection the picker
+ * cannot show.
+ *
+ * Accepts an unknown value so the raw write paths (which validate on-disk
+ * shapes without a full parse) can share the rule. A missing or malformed
+ * value resolves to the managed column: `DefaultProviderField` catches an
+ * invalid value to `undefined`, and an install predating
+ * `llm.defaultProvider` is managed by definition.
+ */
+export function backupProfilesResolveUnderDefaultProvider(
+  defaultProvider: unknown,
+): boolean {
+  const provider =
+    defaultProvider != null &&
+    typeof defaultProvider === "object" &&
+    !Array.isArray(defaultProvider)
+      ? (defaultProvider as Record<string, unknown>).provider
+      : undefined;
+  return typeof provider !== "string" || provider === "vellum";
+}
+
+/**
+ * Why a referenced profile name does not resolve, for the reference error
+ * messages. A backup key under a non-managed default provider gets its own
+ * reason: the name is real and code-defined, it just has no body outside the
+ * managed column, and "not defined in llm.profiles" would send the reader
+ * looking for a missing entry that was never supposed to exist.
+ */
+function unresolvableProfileReason(
+  name: string,
+  backupsResolve: boolean,
+): string {
+  return !backupsResolve &&
+    (BACKUP_PROFILE_KEYS as readonly string[]).includes(name)
+    ? "is a managed backup profile, which resolves only while llm.defaultProvider is the managed provider"
+    : "is not defined in llm.profiles";
+}
+
+/**
+ * The `llm.profiles` keys that are reference targets in their own right,
+ * given whether the managed backups resolve under the current
+ * `llm.defaultProvider`.
+ *
+ * Every on-disk key qualifies but one: a reserved backup name whose entry is
+ * a thin `source: "managed"` stub. The stub is not a profile, it is the
+ * workspace's slot for a code-owned one, and it can reach disk on a managed
+ * install through nothing more than a `config get` -> `config set` round-trip
+ * of the effective profile list (`normalizeManagedProfileWrites` reduces the
+ * echoed body to exactly that stub). Counting it as an ordinary raw key would
+ * let it launder a backup reference past the provider gate: after a switch to
+ * a BYOK or ChatGPT default provider the reference would keep validating
+ * while the code-owned body it stands for has resolved to nothing, leaving a
+ * selection that names a providerless stub.
+ *
+ * A genuinely user-owned entry under a backup name is the opposite case: it
+ * carries its own body, and with no code-owned body to lose on a non-managed
+ * column `resolveAgainstBody` resolves the workspace entry itself. So it
+ * stays a valid target on every column. The `source` test is the same one
+ * the resolver uses, which is what keeps the two in step.
+ */
+function referenceableProfileKeys(
+  profiles: Record<string, unknown> | undefined,
+  backupsResolve: boolean,
+): string[] {
+  return Object.entries(profiles ?? {})
+    .filter(([name, value]) => {
+      if (backupsResolve || !isBackupProfileKey(name)) {
+        return true;
+      }
+      const entry =
+        value != null && typeof value === "object" && !Array.isArray(value)
+          ? (value as Record<string, unknown>)
+          : null;
+      return entry != null && entry.source !== "managed";
+    })
+    .map(([name]) => name);
+}
+
 // ---------------------------------------------------------------------------
 // Top-level LLM schema
 // ---------------------------------------------------------------------------
 
+/**
+ * Cross-profile integrity checks for `fallbackProfile` metadata. Only the
+ * exact code-owned mapping on managed default profiles is accepted. The
+ * referenced profile must exist, must not be a mix, and must not declare a
+ * fallback of its own.
+ *
+ * Shared by `LLMSchema.superRefine` (full-config load) and the config write
+ * paths (`commitConfigWrite`), which persist raw config without a
+ * full-schema parse. Accepts a raw or parsed `llm.profiles` record; entries
+ * are read defensively so the raw on-disk shape is safe to pass.
+ *
+ * `defaultProvider` is the sibling `llm.defaultProvider` value (raw or
+ * parsed): it decides whether the managed backups are valid targets, since
+ * they resolve on the managed column alone.
+ */
+export function collectFallbackProfileIssues(
+  profiles: Record<string, unknown> | undefined,
+  defaultProvider?: unknown,
+): { profileName: string; message: string }[] {
+  const issues: { profileName: string; message: string }[] = [];
+  const entries = Object.entries(profiles ?? {});
+  const readEntry = (value: unknown): Record<string, unknown> | null =>
+    value != null && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : null;
+  // The always-available default profiles are code-defined
+  // (`default-profile-catalog.ts`) and resolve whether or not they are
+  // materialized in `llm.profiles`, so their names are always valid
+  // fallback targets (same rule as call-site `profile` references). The
+  // managed backups resolve the same way, but on the managed column only,
+  // so they are valid targets only under a managed `llm.defaultProvider`.
+  // A persisted managed stub for a backup name does not change that, see
+  // `referenceableProfileKeys`.
+  const backupsResolve =
+    backupProfilesResolveUnderDefaultProvider(defaultProvider);
+  const profileNames = new Set([
+    ...referenceableProfileKeys(profiles, backupsResolve),
+    ...DEFAULT_PROFILE_KEYS,
+    ...(backupsResolve ? BACKUP_PROFILE_KEYS : []),
+  ]);
+  const mixProfileNames = new Set(
+    entries
+      .filter(([, value]) => readEntry(value)?.mix != null)
+      .map(([name]) => name),
+  );
+  for (const [name, value] of entries) {
+    const entry = readEntry(value);
+    const fallback = entry?.fallbackProfile;
+    if (fallback == null) {
+      continue;
+    }
+    // Raw writes (e.g. `config set`) can carry a non-string value the field
+    // schema would reject on the next full parse; flag it here so it never
+    // reaches disk.
+    if (typeof fallback !== "string" || fallback.length === 0) {
+      issues.push({
+        profileName: name,
+        message: `Profile "${name}" declares a fallbackProfile that must be a non-empty string naming another profile.`,
+      });
+      continue;
+    }
+    const expectedFallback = isDefaultProfileKey(name)
+      ? FALLBACK_PROFILE_BY_KEY[name]
+      : undefined;
+    if (entry?.source !== "managed" || fallback !== expectedFallback) {
+      issues.push({
+        profileName: name,
+        message: `Profile "${name}" cannot configure fallbackProfile. Automatic fallbacks are code-owned for Vellum-managed default profiles.`,
+      });
+      continue;
+    }
+    // (e) A mix carries no route of its own to fall back from.
+    if (entry?.mix != null) {
+      issues.push({
+        profileName: name,
+        message: `Mix profile "${name}" cannot also set "fallbackProfile"; a mix only references other profiles plus metadata.`,
+      });
+      continue;
+    }
+    // (b) No self-reference.
+    if (fallback === name) {
+      issues.push({
+        profileName: name,
+        message: `Profile "${name}" cannot declare itself as its fallbackProfile.`,
+      });
+      continue;
+    }
+    // (a) Referenced profile must exist.
+    if (!profileNames.has(fallback)) {
+      issues.push({
+        profileName: name,
+        message: `Profile "${name}" declares fallbackProfile "${fallback}" which ${unresolvableProfileReason(fallback, backupsResolve)}.`,
+      });
+      continue;
+    }
+    // (c) A fallback target must be a standard (non-mix) profile.
+    if (mixProfileNames.has(fallback)) {
+      issues.push({
+        profileName: name,
+        message: `Profile "${name}" declares fallbackProfile "${fallback}" which is a mix profile; a fallback must be a standard profile.`,
+      });
+      continue;
+    }
+    // (d) Single hop only: the target must not declare its own fallback.
+    if (readEntry(profiles?.[fallback])?.fallbackProfile != null) {
+      issues.push({
+        profileName: name,
+        message: `Profile "${name}" declares fallbackProfile "${fallback}" which sets its own fallbackProfile; fallback is a single hop, chains are not allowed.`,
+      });
+    }
+  }
+  return issues;
+}
+
 export const LLMSchema = z
   .object({
     profiles: z.record(z.string().min(1), ProfileEntry).default({}),
@@ -740,12 +953,29 @@ export const LLMSchema = z
     // The always-available default profiles are code-defined
     // (`default-profile-catalog.ts`) and resolve whether or not they are
     // materialized in `llm.profiles`, so their names are always valid
-    // reference targets. The flag-gated `os-beta` is excluded: it resolves
-    // only while a workspace entry exists, so a reference to it is valid
-    // only when that entry is present in `config.profiles`.
+    // reference targets. The managed backups (`BACKUP_PROFILE_KEYS`) are
+    // code-defined on the same terms and are listed in the effective
+    // catalog, so a selection naming one (`activeProfile`, `advisorProfile`,
+    // a call-site pin) must survive the next load rather than being stripped
+    // back to a default. Backups are scoped to the managed column though, so
+    // they join the set only under a managed `llm.defaultProvider`: on a BYOK
+    // or ChatGPT default provider they have no body to resolve to, and
+    // keeping the reference would strand a selection the picker cannot show.
+    // The flag-gated `os-beta` is excluded: it resolves only while a
+    // workspace entry exists, so a reference to it is valid only when that
+    // entry is present in `config.profiles`. A backup name materialized as a
+    // thin managed stub does not re-enter the set on a non-managed column
+    // either, see `referenceableProfileKeys`.
+    const backupsResolve = backupProfilesResolveUnderDefaultProvider(
+      config.defaultProvider,
+    );
     const profileNames = new Set([
-      ...Object.keys(config.profiles ?? {}),
+      ...referenceableProfileKeys(
+        config.profiles as Record<string, unknown> | undefined,
+        backupsResolve,
+      ),
       ...DEFAULT_PROFILE_KEYS,
+      ...(backupsResolve ? BACKUP_PROFILE_KEYS : []),
     ]);
     for (const [siteId, siteConfig] of Object.entries(config.callSites ?? {})) {
       if (siteConfig?.profile == null) {
@@ -755,7 +985,7 @@ export const LLMSchema = z
         ctx.addIssue({
           code: "custom",
           path: ["callSites", siteId, "profile"],
-          message: `Profile "${siteConfig.profile}" referenced by call site "${siteId}" is not defined in llm.profiles`,
+          message: `Profile "${siteConfig.profile}" referenced by call site "${siteId}" ${unresolvableProfileReason(siteConfig.profile, backupsResolve)}`,
         });
       }
     }
@@ -766,7 +996,7 @@ export const LLMSchema = z
       ctx.addIssue({
         code: "custom",
         path: ["activeProfile"],
-        message: `Profile "${config.activeProfile}" referenced by llm.activeProfile is not defined in llm.profiles`,
+        message: `Profile "${config.activeProfile}" referenced by llm.activeProfile ${unresolvableProfileReason(config.activeProfile, backupsResolve)}`,
       });
     }
     if (
@@ -776,18 +1006,20 @@ export const LLMSchema = z
       ctx.addIssue({
         code: "custom",
         path: ["advisorProfile"],
-        message: `Profile "${config.advisorProfile}" referenced by llm.advisorProfile is not defined in llm.profiles`,
+        message: `Profile "${config.advisorProfile}" referenced by llm.advisorProfile ${unresolvableProfileReason(config.advisorProfile, backupsResolve)}`,
       });
     }
 
     // --- Mix profile validation --------------------------------------------
     // Config keys a mix profile must NOT also set (a mix only references other
     // profiles + metadata). Derived from the fragment shape plus the
-    // ProfileEntry-only `provider_connection` so it can't drift if a new config
-    // field is added to `LLMConfigFragment`.
+    // ProfileEntry-only `provider_connection` and `fallbackProfile` (a mix
+    // carries no config of its own, so it has no route to fall back from) so
+    // it can't drift if a new config field is added to `LLMConfigFragment`.
     const MIX_DISALLOWED_CONFIG_KEYS = [
       ...Object.keys(LLMConfigFragment.shape),
       "provider_connection",
+      "fallbackProfile",
     ];
     const mixProfileNames = new Set(
       Object.entries(config.profiles ?? {})
@@ -824,7 +1056,7 @@ export const LLMSchema = z
           ctx.addIssue({
             code: "custom",
             path: ["profiles", name, "mix", index, "profile"],
-            message: `Mix profile "${name}" references profile "${arm.profile}" which is not defined in llm.profiles.`,
+            message: `Mix profile "${name}" references profile "${arm.profile}" which ${unresolvableProfileReason(arm.profile, backupsResolve)}.`,
           });
           continue;
         }
@@ -838,6 +1070,22 @@ export const LLMSchema = z
         }
       }
     }
+
+    // --- fallbackProfile validation ----------------------------------------
+    // Cross-profile fallback rules live in `collectFallbackProfileIssues`
+    // (shared with the config write paths). A mix profile setting
+    // `fallbackProfile` is also rejected by the mix validation above
+    // (MIX_DISALLOWED_CONFIG_KEYS).
+    for (const issue of collectFallbackProfileIssues(
+      config.profiles,
+      config.defaultProvider,
+    )) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["profiles", issue.profileName, "fallbackProfile"],
+        message: issue.message,
+      });
+    }
   });
 
 export type LLMConfig = z.infer<typeof LLMSchema>;

package/src/config/schemas/mcp.ts

@@ -1,5 +1,13 @@
 import { z } from "zod";
 
+/**
+ * Risk level an MCP server's tools start at when its config entry does not
+ * name one. Callers that write or display a server entry must reference this
+ * rather than repeating a literal, so the level stays code-owned: an entry
+ * that omits the field picks up whatever this constant says on every load.
+ */
+export const DEFAULT_MCP_RISK_LEVEL = "medium";
+
 const McpStdioTransportSchema = z
   .object({
     type: z.literal("stdio"),
@@ -66,9 +74,9 @@ export const McpServerConfigSchema = z
       .enum(["low", "medium", "high"], {
         error: "mcp server defaultRiskLevel must be one of: low, medium, high",
       })
-      .default("high")
+      .default(DEFAULT_MCP_RISK_LEVEL)
       .describe(
-        "Default risk level assigned to tools from this server (affects approval requirements)",
+        "Risk level tools from this server start at (affects approval requirements). A tool's own MCP annotations move it one step from here: destructiveHint up, readOnlyHint down.",
       ),
     maxTools: z
       .number({ error: "mcp server maxTools must be a number" })

package/src/config/schemas/memory-retrospective.ts

@@ -2,11 +2,6 @@ import { z } from "zod";
 
 export const MemoryRetrospectiveConfigSchema = z
   .object({
-    // This kill switch exists only because conversation forking is expensive:
-    // a fork full-copies the source conversation (messages + attachments), so
-    // on a large conversation the retrospective's write burst can lock the
-    // SQLite table against other writers. Until forking is referential, an
-    // operator needs a way to stop retrospectives without turning off memory.
     enabled: z
       .boolean({ error: "memory.retrospective.enabled must be a boolean" })
       .default(true)
@@ -14,16 +9,6 @@ export const MemoryRetrospectiveConfigSchema = z
         "Whether the memory-retrospective background pass runs. When false, no retrospective is enqueued by any trigger (interval, message count, pre-compaction, scheduled sweep), the scheduled sweep job stops being queued, and any row already queued completes as a no-op. The rest of the memory system (extraction, retrieval, embeddings, `<memory>` injection) is unaffected. Use `memory.enabled` to disable memory as a whole.",
       ),
 
-    forkStrategy: z
-      .enum(["cloning", "reference"], {
-        error:
-          "memory.retrospective.forkStrategy must be 'cloning' or 'reference'",
-      })
-      .default("cloning")
-      .describe(
-        "How a retrospective's fork of the source conversation is materialized. `cloning` (default) full-copies the source conversation's messages and attachments into the fork. `reference` makes the fork referential: it holds only its own messages and reads the source's through `fork_parent_message_id`, so a fork costs a single row instead of a full copy of the conversation.",
-      ),
-
     timeThresholdMs: z
       .number({
         error: "memory.retrospective.timeThresholdMs must be a number",
@@ -102,7 +87,7 @@ export const MemoryRetrospectiveConfigSchema = z
       })
       .default(false)
       .describe(
-        "When false (default), superseded retrospective conversations are deleted once a newer run succeeds — the persisted remembered_log on memory_retrospective_state is the dedup baseline (the most recent run is scanned only as a fallback for state rows that predate the log column), so older runs are dead weight (fork-based runs each carry a full copy of the source conversation's messages). Operators who want to retain the full run history set this to true; retained runs also skip the startup orphan sweep so they survive restarts.",
+        "When false (default), superseded retrospective conversations are deleted once a newer run succeeds. The persisted remembered_log on memory_retrospective_state is the dedup baseline (the most recent run is scanned only as a fallback for state rows that predate the log column), so older runs are leftover review transcripts. Operators who want to retain the full run history set this to true; retained runs also skip the startup orphan sweep so they survive restarts.",
       ),
 
     matchConversationProfile: z
@@ -130,6 +115,3 @@ export const MemoryRetrospectiveConfigSchema = z
 export type MemoryRetrospectiveConfig = z.infer<
   typeof MemoryRetrospectiveConfigSchema
 >;
-
-/** How a retrospective materializes its fork of the source conversation. */
-export type MemoryForkStrategy = MemoryRetrospectiveConfig["forkStrategy"];

package/src/config/schemas/services.ts

@@ -136,6 +136,21 @@ const HubspotOAuthServiceSchema = BaseServiceSchema.extend({
   mode: ServiceModeSchema.default("your-own"),
 });
 
+const MondayOAuthServiceSchema = BaseServiceSchema.extend({
+  mode: ServiceModeSchema.default("your-own"),
+});
+
+export const EventbriteOAuthServiceSchema = BaseServiceSchema.extend({
+  mode: ServiceModeSchema.default("your-own"),
+});
+export type EventbriteOAuthService = z.infer<
+  typeof EventbriteOAuthServiceSchema
+>;
+
+const CalendlyOAuthServiceSchema = BaseServiceSchema.extend({
+  mode: ServiceModeSchema.default("your-own"),
+});
+
 export const ServicesSchema = z.object({
   inference: InferenceServiceSchema.default(InferenceServiceSchema.parse({})),
   "image-generation": ImageGenerationServiceSchema.default(
@@ -184,6 +199,15 @@ export const ServicesSchema = z.object({
   "hubspot-oauth": HubspotOAuthServiceSchema.default(
     HubspotOAuthServiceSchema.parse({}),
   ),
+  "monday-oauth": MondayOAuthServiceSchema.default(
+    MondayOAuthServiceSchema.parse({}),
+  ),
+  "eventbrite-oauth": EventbriteOAuthServiceSchema.default(
+    EventbriteOAuthServiceSchema.parse({}),
+  ),
+  "calendly-oauth": CalendlyOAuthServiceSchema.default(
+    CalendlyOAuthServiceSchema.parse({}),
+  ),
 });
 export type Services = z.infer<typeof ServicesSchema>;
 

package/src/config/schemas/stt.ts

@@ -1,12 +1,20 @@
 import { z } from "zod";
 
+import { listProviderModelFamilies } from "../../providers/speech-to-text/provider-catalog.js";
+import {
+  STT_ROLE_REQUIREMENTS,
+  STT_ROLES,
+  type SttRole,
+  sttRoleCapabilityGap,
+} from "../../stt/roles.js";
+import type { SttProviderId } from "../../stt/types.js";
+
 /**
  * Valid STT provider identifiers. New providers append here and register
  * an adapter.
  */
 export const VALID_STT_PROVIDERS = [
   "deepgram",
-  "deepgram-flux",
   "google-gemini",
   "openai-whisper",
   "xai",
@@ -38,12 +46,126 @@ const STT_PROVIDER_ALIASES: Record<
  * The map only holds entries the user has explicitly configured — it is
  * NOT required to enumerate every known provider.
  */
-export const SttProvidersSchema = z.record(
-  z.string(),
-  z.record(z.string(), z.unknown()).default({}),
-);
+export const SttProvidersSchema = z
+  .record(z.string(), z.record(z.string(), z.unknown()).default({}))
+  .check((ctx) => {
+    // `model` is only meaningful for providers the catalog knows, and the map
+    // is deliberately open to ids it does not: entries for future providers
+    // must keep round-tripping untouched. So validate the key where it means
+    // something and leave the rest alone.
+    for (const [providerId, settings] of Object.entries(ctx.value)) {
+      const model = settings?.model;
+      if (model === undefined) {
+        continue;
+      }
+      const families = listProviderModelFamilies(providerId as SttProviderId);
+      if (families.length === 0) {
+        continue;
+      }
+      if (typeof model !== "string" || !families.includes(model as never)) {
+        ctx.issues.push({
+          code: "custom",
+          path: [providerId, "model"],
+          message: `services.stt.providers.${providerId}.model must be one of: ${families.join(", ")}`,
+          input: model,
+        });
+      }
+    }
+  });
 export type SttProviders = z.infer<typeof SttProvidersSchema>;
 
+/**
+ * Per-consumer provider overrides: `services.stt.roles.<role>`.
+ *
+ * Sparse: an unset role falls back to `services.stt.provider`. Capability is
+ * per boundary while the base setting is global, so a provider that is right
+ * for live voice can be incapable of batch transcription. A role is how one
+ * consumer says which provider and model family it needs without moving the
+ * others onto it.
+ *
+ * Validation is fail-closed: a pair the provider cannot serve is rejected
+ * here rather than at dial time. Accepting it and falling back at resolve
+ * time is the silent substitution this config exists to make visible.
+ */
+export const SttRolesSchema = z
+  .partialRecord(
+    z.enum(STT_ROLES),
+    z.object({
+      provider: z
+        .preprocess(
+          (v) => {
+            if (typeof v !== "string") {
+              return v;
+            }
+            const k = v.trim().toLowerCase();
+            return STT_PROVIDER_ALIASES[k] ?? k;
+          },
+          z.enum(VALID_STT_PROVIDERS, {
+            error: `a services.stt.roles provider must be one of: ${VALID_STT_PROVIDERS.join(", ")}`,
+          }),
+        )
+        .describe("Provider this consumer uses"),
+      model: z
+        .string({ error: "a services.stt.roles model must be a string" })
+        .optional()
+        .describe(
+          "Model family this consumer uses. Omitted runs the provider's default family",
+        ),
+    }),
+  )
+  .check((ctx) => {
+    for (const [role, selection] of Object.entries(ctx.value)) {
+      if (selection === undefined) {
+        continue;
+      }
+      const families = listProviderModelFamilies(
+        selection.provider as SttProviderId,
+      );
+      if (
+        selection.model !== undefined &&
+        !families.includes(selection.model as never)
+      ) {
+        ctx.issues.push({
+          code: "custom",
+          path: [role, "model"],
+          message:
+            families.length === 0
+              ? `services.stt.roles.${role}: ${selection.provider} offers a single model, so model cannot be set`
+              : `services.stt.roles.${role}.model must be one of: ${families.join(", ")}`,
+          input: selection.model,
+        });
+        continue;
+      }
+      const gap = sttRoleCapabilityGap(role as SttRole, selection);
+      if (gap !== null) {
+        ctx.issues.push({
+          code: "custom",
+          path: [role],
+          message: `services.stt.roles.${role} cannot be ${describeSelection(selection)}: ${gap}`,
+          input: selection,
+        });
+      }
+    }
+  })
+  .describe(
+    `Per-consumer STT provider overrides (${STT_ROLES.join(", ")}). An unset role uses services.stt.provider`,
+  );
+
+export type SttRoles = z.infer<typeof SttRolesSchema>;
+
+/** How a role's selection reads in an error: "deepgram" or "deepgram/flux". */
+function describeSelection(selection: {
+  provider: string;
+  model?: string | undefined;
+}): string {
+  return selection.model === undefined
+    ? `"${selection.provider}"`
+    : `"${selection.provider}" running ${selection.model}`;
+}
+
+/** Re-exported so config consumers need not reach into the stt module. */
+export { STT_ROLE_REQUIREMENTS, STT_ROLES, type SttRole };
+
 /**
  * Canonical STT service configuration.
  *
@@ -98,6 +220,7 @@ export const SttServiceSchema = z
         "BCP-47 language code (e.g. 'en-US', 'hi') or 'multi' for code-switching across languages. Defaults to 'multi'; providers that detect natively ignore it",
       ),
     providers: SttProvidersSchema.default({}),
+    roles: SttRolesSchema.default({}),
   })
   .describe(
     "Speech-to-text service configuration -- provider selection, spoken language, and per-provider settings",