🤖 fix: emit chat-error for pre-stream API failures

When a chat message fails before streaming starts (e.g., invalid model,
missing API key), emit a 'chat-error' event so the error is visible in
the chat UI, not just as an easily-missed toast.

- Add ChatErrorMessage schema, type, and type guard
- Add emitChatError method in agentSession for pre-stream failures
- Handle chat-error in WorkspaceStore and StreamingMessageAggregator
- Add ChatErrorMessage UI component (displays 'Error' vs 'Stream Error')
- chat-error is never auto-retryable (requires user action to fix)
- Update retry eligibility to show retry UI for chat-error

Distinguishes from stream-error which occurs during AI SDK streaming and
may be transient/auto-retryable.

_Generated with `mux`_

Author: ibetitsmike

src/browser/components/AIView.tsx

@@ -133,7 +133,7 @@ const AIViewInner: React.FC<AIViewProps> = ({
     }
 
     for (const message of workspaceState.messages) {
-      if (message.type !== "stream-error") {
+      if (message.type !== "stream-error" && message.type !== "chat-error") {
         continue;
       }
       if (message.errorType !== "model_not_found") {
@@ -143,7 +143,7 @@ const AIViewInner: React.FC<AIViewProps> = ({
         continue;
       }
       handledModelErrorsRef.current.add(message.id);
-      if (message.model) {
+      if (message.type === "stream-error" && message.model) {
         evictModelFromLRU(message.model);
       }
     }

src/browser/components/Messages/MessageRenderer.tsx

@@ -5,7 +5,7 @@ import { UserMessage } from "./UserMessage";
 import { AssistantMessage } from "./AssistantMessage";
 import { ToolMessage } from "./ToolMessage";
 import { ReasoningMessage } from "./ReasoningMessage";
-import { StreamErrorMessage } from "./StreamErrorMessage";
+import { StreamErrorMessage, ChatErrorMessage } from "./StreamErrorMessage";
 import { HistoryHiddenMessage } from "./HistoryHiddenMessage";
 import { InitMessage } from "./InitMessage";
 
@@ -56,6 +56,8 @@ export const MessageRenderer = React.memo<MessageRendererProps>(
         return <ReasoningMessage message={message} className={className} />;
       case "stream-error":
         return <StreamErrorMessage message={message} className={className} />;
+      case "chat-error":
+        return <ChatErrorMessage message={message} className={className} />;
       case "history-hidden":
         return <HistoryHiddenMessage message={message} className={className} />;
       case "workspace-init":

src/browser/components/Messages/StreamErrorMessage.tsx

@@ -31,3 +31,29 @@ export const StreamErrorMessage: React.FC<StreamErrorMessageProps> = ({ message,
     </div>
   );
 };
+
+/**
+ * ChatErrorMessage - displays pre-stream errors (before AI SDK streaming starts).
+ * These are errors like invalid model, missing API key, unsupported provider, etc.
+ */
+interface ChatErrorMessageProps {
+  message: DisplayedMessage & { type: "chat-error" };
+  className?: string;
+}
+
+export const ChatErrorMessage: React.FC<ChatErrorMessageProps> = ({ message, className }) => {
+  return (
+    <div className={cn("bg-error-bg border border-error rounded px-5 py-4 my-3", className)}>
+      <div className="font-primary text-error mb-3 flex items-center gap-2.5 text-[13px] font-semibold tracking-wide">
+        <span className="text-base leading-none">●</span>
+        <span>Error</span>
+        <span className="text-secondary rounded-sm bg-black/40 px-2 py-0.5 font-mono text-[10px] tracking-wider uppercase">
+          {message.errorType}
+        </span>
+      </div>
+      <div className="text-foreground font-mono text-[13px] leading-relaxed break-words">
+        {message.error}
+      </div>
+    </div>
+  );
+};

src/browser/stores/WorkspaceStore.ts

@@ -13,6 +13,7 @@ import { useSyncExternalStore } from "react";
 import {
   isCaughtUpMessage,
   isStreamError,
+  isChatError,
   isDeleteMessage,
   isMuxMessage,
   isQueuedMessageChanged,
@@ -998,6 +999,16 @@ export class WorkspaceStore {
       return;
     }
 
+    // chat-error: pre-stream failures (invalid model, missing API key, etc.)
+    // These are NOT auto-retryable - they require user action
+    // Don't increment retry counter, but still show in UI and allow manual retry
+    if (isChatError(data)) {
+      aggregator.handleChatError(data);
+      this.states.bump(workspaceId);
+      this.dispatchResumeCheck(workspaceId);
+      return;
+    }
+
     if (isDeleteMessage(data)) {
       aggregator.handleDeleteMessage(data);
       this.states.bump(workspaceId);

src/browser/utils/messages/StreamingMessageAggregator.ts

@@ -21,7 +21,12 @@ import type {
 import type { LanguageModelV2Usage } from "@ai-sdk/provider";
 import type { TodoItem, StatusSetToolResult } from "@/common/types/tools";
 
-import type { WorkspaceChatMessage, StreamErrorMessage, DeleteMessage } from "@/common/orpc/types";
+import type {
+  WorkspaceChatMessage,
+  StreamErrorMessage,
+  ChatErrorMessage,
+  DeleteMessage,
+} from "@/common/orpc/types";
 import { isInitStart, isInitOutput, isInitEnd, isMuxMessage } from "@/common/orpc/types";
 import type {
   DynamicToolPart,
@@ -589,6 +594,40 @@ export class StreamingMessageAggregator {
     }
   }
 
+  /**
+   * Handle pre-stream chat errors (before stream-start).
+   * These are distinct from stream-error (AI SDK errors during streaming).
+   *
+   * chat-error occurs when:
+   * - Model validation fails (invalid format, non-existent model)
+   * - API key is missing
+   * - Provider is not supported
+   * - etc.
+   *
+   * Creates a synthetic error message since there's no active stream.
+   */
+  handleChatError(data: ChatErrorMessage): void {
+    // Get the highest historySequence from existing messages so this appears at the end
+    const maxSequence = Math.max(
+      0,
+      ...Array.from(this.messages.values()).map((m) => m.metadata?.historySequence ?? 0)
+    );
+    const errorMessage: MuxMessage = {
+      id: data.messageId,
+      role: "assistant",
+      parts: [],
+      metadata: {
+        partial: true,
+        error: data.error,
+        errorType: data.errorType,
+        timestamp: Date.now(),
+        historySequence: maxSequence + 1,
+      },
+    };
+    this.messages.set(data.messageId, errorMessage);
+    this.invalidateCache();
+  }
+
   handleToolCallStart(data: ToolCallStartEvent): void {
     const message = this.messages.get(data.messageId);
     if (!message) return;

src/browser/utils/messages/messageUtils.ts

@@ -11,6 +11,7 @@ export function shouldShowInterruptedBarrier(msg: DisplayedMessage): boolean {
   if (
     msg.type === "user" ||
     msg.type === "stream-error" ||
+    msg.type === "chat-error" ||
     msg.type === "history-hidden" ||
     msg.type === "workspace-init"
   )

src/browser/utils/messages/retryEligibility.ts

@@ -92,6 +92,7 @@ export function hasInterruptedStream(
 
   return (
     lastMessage.type === "stream-error" || // Stream errored out (show UI for ALL error types)
+    lastMessage.type === "chat-error" || // Pre-stream error (show UI so user can retry after fixing)
     lastMessage.type === "user" || // No response received yet (app restart during slow model)
     (lastMessage.type === "assistant" && lastMessage.isPartial === true) ||
     (lastMessage.type === "tool" && lastMessage.isPartial === true) ||
@@ -122,6 +123,13 @@ export function isEligibleForAutoRetry(
   // If the last message is a non-retryable error, don't auto-retry
   // (but manual retry is still available via hasInterruptedStream)
   const lastMessage = messages[messages.length - 1];
+
+  // chat-error is NEVER auto-retryable - always requires user action
+  // (fixing model selection, adding API key, etc.)
+  if (lastMessage.type === "chat-error") {
+    return false;
+  }
+
   if (lastMessage.type === "stream-error") {
     // Debug flag: force all errors to be retryable
     if (isForceAllRetryableEnabled()) {

src/common/orpc/schemas.ts

@@ -82,6 +82,7 @@ export {
   ReasoningEndEventSchema,
   RestoreToInputEventSchema,
   SendMessageOptionsSchema,
+  ChatErrorMessageSchema,
   StreamAbortEventSchema,
   StreamDeltaEventSchema,
   StreamEndEventSchema,

src/common/orpc/schemas/stream.ts

@@ -22,6 +22,23 @@ export const StreamErrorMessageSchema = z.object({
   errorType: StreamErrorTypeSchema,
 });
 
+/**
+ * Chat error message - for errors that occur BEFORE streaming starts.
+ * Distinct from StreamErrorMessage (AI SDK stream errors that happen during streaming).
+ *
+ * These errors are NOT auto-retryable - they require user action:
+ * - Invalid model format
+ * - Missing API key
+ * - Unsupported provider
+ * - etc.
+ */
+export const ChatErrorMessageSchema = z.object({
+  type: z.literal("chat-error"),
+  messageId: z.string(),
+  error: z.string(),
+  errorType: StreamErrorTypeSchema,
+});
+
 export const DeleteMessageSchema = z.object({
   type: z.literal("delete"),
   historySequences: z.array(z.number()),
@@ -260,6 +277,7 @@ export const WorkspaceChatMessageSchema = z.discriminatedUnion("type", [
   // Stream lifecycle events
   CaughtUpMessageSchema,
   StreamErrorMessageSchema,
+  ChatErrorMessageSchema,
   DeleteMessageSchema,
   StreamStartEventSchema,
   StreamDeltaEventSchema,

src/common/orpc/types.ts

@@ -25,6 +25,7 @@ export type ImagePart = z.infer<typeof schemas.ImagePartSchema>;
 export type WorkspaceChatMessage = z.infer<typeof schemas.WorkspaceChatMessageSchema>;
 export type CaughtUpMessage = z.infer<typeof schemas.CaughtUpMessageSchema>;
 export type StreamErrorMessage = z.infer<typeof schemas.StreamErrorMessageSchema>;
+export type ChatErrorMessage = z.infer<typeof schemas.ChatErrorMessageSchema>;
 export type DeleteMessage = z.infer<typeof schemas.DeleteMessageSchema>;
 export type WorkspaceInitEvent = z.infer<typeof schemas.WorkspaceInitEventSchema>;
 export type UpdateStatus = z.infer<typeof schemas.UpdateStatusSchema>;
@@ -43,6 +44,10 @@ export function isStreamError(msg: WorkspaceChatMessage): msg is StreamErrorMess
   return (msg as { type?: string }).type === "stream-error";
 }
 
+export function isChatError(msg: WorkspaceChatMessage): msg is ChatErrorMessage {
+  return (msg as { type?: string }).type === "chat-error";
+}
+
 export function isDeleteMessage(msg: WorkspaceChatMessage): msg is DeleteMessage {
   return (msg as { type?: string }).type === "delete";
 }