feat: Add model fallbacks

Author: j3k0

packages/opencode/src/agent/agent.ts

@@ -42,6 +42,12 @@ export const Info = Schema.Struct({
     }),
   ),
   variant: Schema.optional(Schema.String),
+  fallbacks: Schema.optional(
+    Schema.Array(Schema.Struct({
+      providerID: ProviderID,
+      modelID: ModelID,
+    })),
+  ),
   prompt: Schema.optional(Schema.String),
   options: Schema.Record(Schema.String, Schema.Unknown),
   steps: Schema.optional(Schema.Finite),
@@ -292,6 +298,9 @@ export const layer = Layer.effect(
               native: false,
             }
           if (value.model) item.model = Provider.parseModel(value.model)
+          if (value.fallbacks) {
+            item.fallbacks = value.fallbacks.map((f) => Provider.parseModel(f))
+          }
           item.variant = value.variant ?? item.variant
           item.prompt = value.prompt ?? item.prompt
           item.description = value.description ?? item.description

packages/opencode/src/cli/cmd/tui/app.tsx

@@ -877,6 +877,20 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
     }
   })
 
+  event.on("llm.fallback.triggered", (evt) => {
+    toast.show({
+      message: `Falling back to ${evt.properties.modelID} (${evt.properties.reason})`,
+      variant: "warning",
+    })
+  })
+
+  event.on("llm.fallback.used", (evt) => {
+    toast.show({
+      message: `Switched to ${evt.properties.modelID}`,
+      variant: "info",
+    })
+  })
+
   event.on("session.error", (evt) => {
     const error = evt.properties.error
     if (error && typeof error === "object" && error.name === "MessageAbortedError") return

packages/opencode/src/cli/cmd/tui/feature-plugins/system/session-v2.tsx

@@ -360,18 +360,22 @@ function AssistantMessage(props: {
 }
 
 function AssistantText(props: { part: SessionMessageAssistantText; syntax: SyntaxStyle }) {
-  const { theme } = useTheme()
+  const { theme, subtleSyntax } = useTheme()
+  const fallbackNotice = props.part.fallbackNotice
+  const isFallback = fallbackNotice != null
+  const fg = fallbackNotice === "resume" ? theme.success : isFallback ? theme.error : props.part.ignored ? theme.textMuted : theme.text
+  const syntaxStyle = isFallback || props.part.ignored ? subtleSyntax() : props.syntax
   return (
     <Show when={props.part.text.trim()}>
       <box paddingLeft={3} marginTop={1} flexShrink={0} id="text">
         <code
           filetype="markdown"
           drawUnstyledText={false}
           streaming={true}
-          syntaxStyle={props.syntax}
+          syntaxStyle={syntaxStyle}
           content={props.part.text.trim()}
           conceal={true}
-          fg={theme.text}
+          fg={fg}
         />
       </box>
     </Show>

packages/opencode/src/cli/cmd/tui/routes/session/index.tsx

@@ -1399,6 +1399,10 @@ function AssistantMessage(props: { message: AssistantMessage; parts: Part[]; las
   const sync = useSync()
   const messages = createMemo(() => sync.data.message[props.message.sessionID] ?? [])
   const model = createMemo(() => Model.name(ctx.providers(), props.message.providerID, props.message.modelID))
+  const providerName = createMemo(() => {
+    const p = ctx.providers()?.get(props.message.providerID)
+    return p?.name ?? props.message.providerID
+  })
 
   const final = createMemo(() => {
     return props.message.finish && !["tool-calls", "unknown"].includes(props.message.finish)
@@ -1468,7 +1472,7 @@ function AssistantMessage(props: { message: AssistantMessage; parts: Part[]; las
                 ▣{" "}
               </span>{" "}
               <span style={{ fg: theme.text }}>{Locale.titlecase(props.message.mode)}</span>
-              <span style={{ fg: theme.textMuted }}> · {model()}</span>
+              <span style={{ fg: theme.textMuted }}> · {model()} ({providerName()})</span>
               <Show when={duration()}>
                 <span style={{ fg: theme.textMuted }}> · {Locale.duration(duration())}</span>
               </Show>
@@ -1524,17 +1528,21 @@ function ReasoningPart(props: { last: boolean; part: ReasoningPart; message: Ass
 
 function TextPart(props: { last: boolean; part: TextPart; message: AssistantMessage }) {
   const ctx = use()
-  const { theme, syntax } = useTheme()
+  const { theme, syntax, subtleSyntax } = useTheme()
+  const fallbackNotice = (props.part as any).fallbackNotice as "using" | "switch" | "resume" | undefined
+  const isFallback = fallbackNotice != null
+  const fg = fallbackNotice === "resume" ? theme.success : isFallback ? theme.error : (props.part as any).ignored ? theme.textMuted : theme.markdownText
+  const syntaxStyle = isFallback || (props.part as any).ignored ? subtleSyntax() : syntax()
   return (
     <Show when={props.part.text.trim()}>
       <box id={"text-" + props.part.id} paddingLeft={3} marginTop={1} flexShrink={0}>
         <markdown
-          syntaxStyle={syntax()}
+          syntaxStyle={syntaxStyle}
           streaming={true}
           internalBlockMode="top-level"
           content={props.part.text.trim()}
           conceal={ctx.conceal()}
-          fg={theme.markdownText}
+          fg={fg}
           bg={theme.background}
         />
       </box>

packages/opencode/src/config/agent.ts

@@ -46,6 +46,9 @@ const AgentSchema = Schema.StructWithRest(
     }),
     maxSteps: Schema.optional(PositiveInt).annotate({ description: "@deprecated Use 'steps' field instead." }),
     permission: Schema.optional(ConfigPermission.Info),
+    fallbacks: Schema.optional(Schema.mutable(Schema.Array(ConfigModelID))).annotate({
+      description: "Fallback models to try when the primary model fails, in provider/model format",
+    }),
   }),
   [Schema.Record(Schema.String, Schema.Any)],
 )
@@ -65,6 +68,7 @@ const KNOWN_KEYS = new Set([
   "maxSteps",
   "options",
   "permission",
+  "fallbacks",
   "disable",
   "tools",
 ])

packages/opencode/src/config/config.ts

@@ -166,6 +166,12 @@ export const Info = Schema.Struct({
   model: Schema.optional(ConfigModelID).annotate({
     description: "Model to use in the format of provider/model, eg anthropic/claude-2",
   }),
+  fallbacks: Schema.optional(Schema.mutable(Schema.Array(ConfigModelID))).annotate({
+    description: "Fallback models to try when the primary model fails, in provider/model format",
+  }),
+  cooldown_seconds: Schema.optional(Schema.Number.check(Schema.isGreaterThan(0))).annotate({
+    description: "Duration in seconds to put a provider/model in cooldown after a retryable error (default: 300)",
+  }),
   small_model: Schema.optional(ConfigModelID).annotate({
     description: "Small model to use for tasks like title generation in the format of provider/model",
   }),