feat: add agent default variant handling in TUI and desktop

- Resolve configured variants through shared helpers used by app and TUI
- Respect agent-configured variants unless the user selects an override or Default
- Restore and hydrate TUI variant state without stale overrides or legacy default sentinels
- Add variant tests for shared helpers and agent config

Closes #22065

Author: CasualDeveloper

packages/app/src/components/prompt-input/submit.test.ts

@@ -12,13 +12,13 @@ const optimistic: Array<{
   sessionID?: string
   message: {
     agent: string
-    model: { providerID: string; modelID: string }
-    variant?: string
+    model: { providerID: string; modelID: string; variant?: string }
   }
 }> = []
 const optimisticSeeded: boolean[] = []
 const storedSessions: Record<string, Array<{ id: string; title?: string }>> = {}
 const promoted: Array<{ directory: string; sessionID: string }> = []
+const promotedVariants: Array<string | null | undefined> = []
 const sentShell: string[] = []
 const syncedDirectories: string[] = []
 const promotedDrafts: Array<{ draftID: string; server: string; sessionId: string }> = []
@@ -27,6 +27,7 @@ let params: { id?: string } = {}
 let search: { draftId?: string } = {}
 let selected = "/repo/worktree-a"
 let variant: string | undefined
+let selectedVariant: string | null | undefined
 let permissionServer = "server-a"
 let createSessionGate: Promise<void> | undefined
 
@@ -99,8 +100,7 @@ beforeAll(async () => {
     },
   }))
 
-  mock.module("@opencode-ai/ui/toast", () => ({
-    Toast: { Region: () => null },
+  mock.module("@/utils/toast", () => ({
     showToast: () => 0,
   }))
 
@@ -112,14 +112,15 @@ beforeAll(async () => {
     useLocal: () => ({
       model: {
         current: () => ({ id: "model", provider: { id: "provider" } }),
-        variant: { current: () => variant },
+        variant: { current: () => variant, selected: () => selectedVariant },
       },
       agent: {
         current: () => ({ name: "agent" }),
       },
       session: {
-        promote(directory: string, sessionID: string) {
+        promote(directory: string, sessionID: string, state?: { variant?: string | null }) {
           promoted.push({ directory, sessionID })
+          promotedVariants.push(state?.variant)
         },
       },
     }),
@@ -248,13 +249,15 @@ beforeEach(() => {
   optimistic.length = 0
   optimisticSeeded.length = 0
   promoted.length = 0
+  promotedVariants.length = 0
   promotedDrafts.length = 0
   params = {}
   search = {}
   sentShell.length = 0
   syncedDirectories.length = 0
   selected = "/repo/worktree-a"
   variant = undefined
+  selectedVariant = undefined
   permissionServer = "server-a"
   createSessionGate = undefined
   for (const key of Object.keys(storedSessions)) delete storedSessions[key]
@@ -426,7 +429,7 @@ describe("prompt submit worktree selection", () => {
     params = { id: "session-1" }
     const model = {
       current: () => ({ id: "draft-model", provider: { id: "draft-provider" } }),
-      variant: { current: () => "draft-variant" },
+      variant: { current: () => "draft-variant", selected: () => undefined },
     } as unknown as ModelSelection
     const submit = createPromptSubmit({
       prompt,
@@ -455,6 +458,68 @@ describe("prompt submit worktree selection", () => {
     })
   })
 
+  test("sends explicit default variant on optimistic prompts", async () => {
+    params = { id: "session-1" }
+    selectedVariant = null
+
+    const submit = createPromptSubmit({
+      prompt,
+      info: () => ({ id: "session-1" }),
+      imageAttachments: () => [],
+      commentCount: () => 0,
+      autoAccept: () => false,
+      mode: () => "normal",
+      working: () => false,
+      editor: () => undefined,
+      queueScroll: () => undefined,
+      promptLength: (value) => value.reduce((sum, part) => sum + ("content" in part ? part.content.length : 0), 0),
+      addToHistory: () => undefined,
+      resetHistoryNavigation: () => undefined,
+      setMode: () => undefined,
+      setPopover: () => undefined,
+      onSubmit: () => undefined,
+    })
+
+    const event = { preventDefault: () => undefined } as unknown as Event
+
+    await submit.handleSubmit(event)
+
+    expect(optimistic).toHaveLength(1)
+    expect(optimistic[0]).toMatchObject({
+      message: {
+        agent: "agent",
+        model: { providerID: "provider", modelID: "model", variant: "default" },
+      },
+    })
+  })
+
+  test("preserves explicit default when promoting a new session", async () => {
+    selectedVariant = null
+
+    const submit = createPromptSubmit({
+      prompt,
+      info: () => undefined,
+      imageAttachments: () => [],
+      commentCount: () => 0,
+      autoAccept: () => false,
+      mode: () => "normal",
+      working: () => false,
+      editor: () => undefined,
+      queueScroll: () => undefined,
+      promptLength: (value) => value.reduce((sum, part) => sum + ("content" in part ? part.content.length : 0), 0),
+      addToHistory: () => undefined,
+      resetHistoryNavigation: () => undefined,
+      setMode: () => undefined,
+      setPopover: () => undefined,
+      onSubmit: () => undefined,
+    })
+
+    await submit.handleSubmit({ preventDefault: () => undefined } as unknown as Event)
+
+    expect(promotedVariants).toEqual([null])
+    expect(optimistic[0]?.message.model.variant).toBe("default")
+  })
+
   test("seeds new sessions before optimistic prompts are added", async () => {
     const submit = createPromptSubmit({
       prompt,

packages/app/src/components/prompt-input/submit.ts

@@ -19,6 +19,7 @@ import { buildRequestParts } from "./build-request-parts"
 import { setCursorPosition } from "./editor-dom"
 import { formatServerError } from "@/utils/server-errors"
 import { ScopedKey } from "@/utils/server-scope"
+import { resolveModelVariantForRequest } from "@opencode-ai/core/util/model-variant"
 import { createPromptSubmissionState } from "./submission-state"
 
 type PendingPrompt = {
@@ -302,7 +303,11 @@ export function createPromptSubmit(input: PromptSubmitInput) {
     const modelSelection = input.model ?? local.model
     const currentModel = modelSelection.current()
     const currentAgent = local.agent.current()
-    const variant = modelSelection.variant.current()
+    const selectedVariant = modelSelection.variant.selected()
+    const variant = resolveModelVariantForRequest({
+      selected: selectedVariant,
+      current: modelSelection.variant.current(),
+    })
     if (!currentModel || !currentAgent) {
       showToast({
         title: language.t("prompt.toast.modelAgentRequired.title"),
@@ -383,7 +388,7 @@ export function createPromptSubmit(input: PromptSubmitInput) {
           local.session.promote(sessionDirectory, session.id, {
             agent: currentAgent.name,
             model: { providerID: currentModel.provider.id, modelID: currentModel.id },
-            variant: variant ?? null,
+            variant: selectedVariant,
           })
           layout.handoff.setTabs(base64Encode(sessionDirectory), session.id)
           const draftID = search.draftId

packages/app/src/context/local.tsx

@@ -8,7 +8,12 @@ import { useSettings } from "@/context/settings"
 import { useProviders } from "@/hooks/use-providers"
 import { Persist, persisted } from "@/utils/persist"
 import { hasCustomAgent, resolveAgent } from "./local-agent"
-import { cycleModelVariant, getConfiguredAgentVariant, resolveModelVariant } from "./model-variant"
+import {
+  cycleModelVariant,
+  getConfiguredAgentVariant,
+  resolveModelVariant,
+  resolveModelVariantFromMessage,
+} from "@opencode-ai/core/util/model-variant"
 import { useSDK } from "./sdk"
 import { useSync } from "./sync"
 import { useServerSDK } from "./server-sdk"
@@ -193,19 +198,19 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
           return
         }
 
+        const prev = scope()
         batch(() => {
           setStore("current", item.name)
           setStore("last", {
             type: "agent",
             agent: item.name,
             model: item.model,
-            variant: item.variant ?? null,
+            variant: prev?.variant,
           })
-          const prev = scope()
           const next = {
             agent: item.name,
             model: item.model ?? prev?.model,
-            variant: item.variant ?? prev?.variant,
+            variant: prev?.variant,
           } satisfies State
           const session = id()
           if (session) {
@@ -326,12 +331,14 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
         configured,
         selected,
         current() {
+          const selected = this.selected()
           const resolved = resolveModelVariant({
             variants: this.list(),
-            selected: this.selected(),
+            selected,
             configured: this.configured(),
           })
           if (resolved) return resolved
+          if (selected === null) return
           const model = current()
           if (!model) return
           const saved = models.variant.get({ providerID: model.provider.id, modelID: model.id })
@@ -405,7 +412,7 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
           setSaved("session", session, {
             agent: msg.agent,
             model: msg.model,
-            variant: msg.model?.variant ?? null,
+            variant: resolveModelVariantFromMessage(msg.model?.variant),
           })
         },
       },

packages/app/src/pages/session/composer/prompt-model-selection.ts

@@ -1,7 +1,7 @@
 import { batch, createMemo, startTransition } from "solid-js"
+import { cycleModelVariant, getConfiguredAgentVariant, resolveModelVariant } from "@opencode-ai/core/util/model-variant"
 import { useModels } from "@/context/models"
 import type { ModelKey, ModelSelection } from "@/context/local"
-import { cycleModelVariant, getConfiguredAgentVariant, resolveModelVariant } from "@/context/model-variant"
 import { usePrompt } from "@/context/prompt"
 import { useSDK } from "@/context/sdk"
 import { useSync } from "@/context/sync"
@@ -91,12 +91,14 @@ export function createPromptModelSelection(input: { agent: () => { model?: Model
         return prompt.model.current()?.variant
       },
       current() {
+        const selected = this.selected()
         const resolved = resolveModelVariant({
           variants: this.list(),
-          selected: this.selected(),
+          selected,
           configured: this.configured(),
         })
         if (resolved) return resolved
+        if (selected === null) return
         const model = current()
         if (!model) return
         const saved = models.variant.get({ providerID: model.provider.id, modelID: model.id })

packages/app/src/context/model-variant.ts packages/core/src/util/model-variant.tspackages/app/src/context/model-variant.ts renamed to packages/core/src/util/model-variant.ts

@@ -12,6 +12,9 @@ type Model = AgentModel & {
   variants?: Record<string, unknown>
 }
 
+// selected: string          = user-chosen variant name
+// selected: null            = user explicitly chose "default" (clears any agent-configured variant)
+// selected: undefined       = no user choice yet (fall back to agent-configured variant)
 type VariantInput = {
   variants: string[]
   selected: string | null | undefined
@@ -35,6 +38,19 @@ export function resolveModelVariant(input: VariantInput) {
   return undefined
 }
 
+export function resolveModelVariantForRequest(input: {
+  selected: string | null | undefined
+  current: string | undefined
+}) {
+  if (input.selected === null) return "default"
+  return input.current
+}
+
+export function resolveModelVariantFromMessage(variant: string | undefined) {
+  if (variant === "default") return null
+  return variant
+}
+
 export function cycleModelVariant(input: VariantInput) {
   if (input.variants.length === 0) return undefined
   if (input.selected === null) return input.variants[0]
@@ -43,6 +59,7 @@ export function cycleModelVariant(input: VariantInput) {
     if (index === input.variants.length - 1) return undefined
     return input.variants[index + 1]
   }
+  // No explicit selection: start cycling from the agent-configured variant.
   if (input.configured && input.variants.includes(input.configured)) {
     const index = input.variants.indexOf(input.configured)
     if (index === input.variants.length - 1) return input.variants[0]

…es/app/src/context/model-variant.test.ts …ges/core/test/util/model-variant.test.tspackages/app/src/context/model-variant.test.ts renamed to packages/core/test/util/model-variant.test.ts packages/app/src/context/model-variant.test.ts renamed to packages/core/test/util/model-variant.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, test } from "bun:test"
-import { cycleModelVariant, getConfiguredAgentVariant, resolveModelVariant } from "./model-variant"
+import {
+  cycleModelVariant,
+  getConfiguredAgentVariant,
+  resolveModelVariant,
+  resolveModelVariantForRequest,
+  resolveModelVariantFromMessage,
+} from "../../src/util/model-variant"
 
 describe("model variant", () => {
   test("resolves configured agent variant when model matches", () => {
@@ -83,4 +89,41 @@ describe("model variant", () => {
 
     expect(value).toBe("low")
   })
+
+  test("cycles through all variants from explicit selection", () => {
+    const variants = ["low", "high", "xhigh"]
+    const first = cycleModelVariant({ variants, selected: undefined, configured: undefined })
+    const second = cycleModelVariant({ variants, selected: first, configured: undefined })
+    const third = cycleModelVariant({ variants, selected: second, configured: undefined })
+    const fourth = cycleModelVariant({ variants, selected: third, configured: undefined })
+
+    expect(first).toBe("low")
+    expect(second).toBe("high")
+    expect(third).toBe("xhigh")
+    expect(fourth).toBeUndefined()
+  })
+
+  test("sends explicit default as request sentinel", () => {
+    const value = resolveModelVariantForRequest({ selected: null, current: undefined })
+
+    expect(value).toBe("default")
+  })
+
+  test("keeps current variant for requests without explicit default", () => {
+    const value = resolveModelVariantForRequest({ selected: undefined, current: "xhigh" })
+
+    expect(value).toBe("xhigh")
+  })
+
+  test("restores explicit default from message sentinel", () => {
+    const value = resolveModelVariantFromMessage("default")
+
+    expect(value).toBeNull()
+  })
+
+  test("keeps absent message variant as inherit", () => {
+    const value = resolveModelVariantFromMessage(undefined)
+
+    expect(value).toBeUndefined()
+  })
 })

packages/opencode/test/agent/agent.test.ts

@@ -753,3 +753,26 @@ it.instance(
     },
   },
 )
+
+it.instance(
+  "agent variant can be set from config",
+  () =>
+    Effect.gen(function* () {
+      const build = yield* load((svc) => svc.get("build"))
+      expect(build?.variant).toBe("high")
+    }),
+  {
+    config: {
+      agent: {
+        build: { variant: "high" },
+      },
+    },
+  },
+)
+
+it.instance("agent variant defaults to undefined when not set", () =>
+  Effect.gen(function* () {
+    const build = yield* load((svc) => svc.get("build"))
+    expect(build?.variant).toBeUndefined()
+  }),
+)

packages/tui/src/component/dialog-model.tsx

@@ -142,8 +142,13 @@ export function DialogModel(props: { providerID?: string }) {
   function onSelect(providerID: string, modelID: string) {
     local.model.set({ providerID, modelID }, { recent: true })
     const list = local.model.variant.list()
-    const cur = local.model.variant.selected()
-    if (cur === "default" || (cur && list.includes(cur))) {
+    const selected = local.model.variant.selected()
+    const current = local.model.variant.current()
+    if (
+      selected === null ||
+      (selected && list.includes(selected)) ||
+      (!selected && current && list.includes(current))
+    ) {
       dialog.clear()
       return
     }