🤖 fix: validate /compact model format before persisting message (#1109)

Fixes janky `/compact` slash-command behavior where commands with
invalid model formats would show up in chat history even though the
request failed.

## Changes

- **Backend validation (agentSession.ts)**: Validate model format before
persisting user message to history. Invalid model strings (missing
provider prefix) are now rejected before the message is saved,
preventing orphaned compaction request messages.

- **Frontend validation (chatCommands.ts)**: Fail fast in `/compact`
handler when model format is invalid, showing a clear toast error with
example format.

- **Helper function**: Add `isValidModelFormat()` to check for
`provider:model-id` format (supports colons in model ID for ollama-style
names).

- **Preference poisoning fix**: Stop eagerly saving compaction model to
localStorage, preventing invalid model values from affecting future
`/compact` commands.

## Testing

- Added unit tests for `isValidModelFormat()`
- Updated integration test for invalid model format error handling

_Generated with `mux`_

Author: ammar-agent

src/browser/components/ChatInputToasts.tsx

@@ -1,10 +1,32 @@
 import React from "react";
 import type { Toast } from "./ChatInputToast";
 import { SolutionLabel } from "./ChatInputToast";
+import { DocsLink } from "./DocsLink";
 import type { ParsedCommand } from "@/browser/utils/slashCommands/types";
 import type { SendMessageError as SendMessageErrorType } from "@/common/types/errors";
 import { formatSendMessageError } from "@/common/utils/errors/formatSendError";
 
+export function createInvalidCompactModelToast(model: string): Toast {
+  return {
+    id: Date.now().toString(),
+    type: "error",
+    title: "Invalid Model",
+    message: `Invalid model format: "${model}". Use an alias or provider:model-id.`,
+    solution: (
+      <>
+        <SolutionLabel>Try an alias:</SolutionLabel>
+        /compact -m sonnet
+        <br />
+        /compact -m gpt
+        <br />
+        <br />
+        <SolutionLabel>Supported models:</SolutionLabel>
+        <DocsLink path="/models">mux.coder.com/models</DocsLink>
+      </>
+    ),
+  };
+}
+
 /**
  * Creates a toast message for command-related errors and help messages
  */

src/browser/utils/chatCommands.ts

@@ -22,7 +22,10 @@ import { WORKSPACE_ONLY_COMMANDS } from "@/constants/slashCommands";
 import type { Toast } from "@/browser/components/ChatInputToast";
 import type { ParsedCommand } from "@/browser/utils/slashCommands/types";
 import { applyCompactionOverrides } from "@/browser/utils/messages/compactionOptions";
-import { resolveCompactionModel } from "@/browser/utils/messages/compactionModelPreference";
+import {
+  resolveCompactionModel,
+  isValidModelFormat,
+} from "@/browser/utils/messages/compactionModelPreference";
 import type { ImageAttachment } from "../components/ImageAttachments";
 import { dispatchWorkspaceSwitch } from "./workspaceEvents";
 import { getRuntimeKey, copyWorkspaceStorage } from "@/common/constants/storage";
@@ -37,7 +40,10 @@ import { openInEditor } from "@/browser/utils/openInEditor";
 // Workspace Creation
 // ============================================================================
 
-import { createCommandToast } from "@/browser/components/ChatInputToasts";
+import {
+  createCommandToast,
+  createInvalidCompactModelToast,
+} from "@/browser/components/ChatInputToasts";
 import { trackCommandUsed, trackProviderConfigured } from "@/common/telemetry";
 import { addEphemeralMessage } from "@/browser/stores/WorkspaceStore";
 
@@ -851,6 +857,12 @@ export async function handleCompactCommand(
     onCancelEdit,
   } = context;
 
+  // Validate model format early - fail fast before sending to backend
+  if (parsed.model && !isValidModelFormat(parsed.model)) {
+    setToast(createInvalidCompactModelToast(parsed.model));
+    return { clearInput: false, toastShown: true };
+  }
+
   setInput("");
   setImageAttachments([]);
   setIsSending(true);

src/browser/utils/messages/compactionModelPreference.ts

@@ -6,16 +6,17 @@
 
 import { PREFERRED_COMPACTION_MODEL_KEY } from "@/common/constants/storage";
 
+// Re-export for convenience - validation used in /compact handler
+export { isValidModelFormat } from "@/common/utils/ai/models";
+
 /**
- * Resolve the effective compaction model, saving preference if a model is specified.
+ * Resolve the effective compaction model to use for compaction.
  *
  * @param requestedModel - Model specified in /compact -m flag (if any)
  * @returns The model to use for compaction, or undefined to use workspace default
  */
 export function resolveCompactionModel(requestedModel: string | undefined): string | undefined {
   if (requestedModel) {
-    // User specified a model with -m flag, save it as the new preference
-    localStorage.setItem(PREFERRED_COMPACTION_MODEL_KEY, requestedModel);
     return requestedModel;
   }
 

src/common/utils/ai/models.test.ts

@@ -1,5 +1,10 @@
 import { describe, it, expect } from "bun:test";
-import { normalizeGatewayModel, getModelName, supports1MContext } from "./models";
+import {
+  normalizeGatewayModel,
+  getModelName,
+  supports1MContext,
+  isValidModelFormat,
+} from "./models";
 
 describe("normalizeGatewayModel", () => {
   it("should convert mux-gateway:provider/model to provider:model", () => {
@@ -63,3 +68,28 @@ describe("supports1MContext", () => {
     expect(supports1MContext("mux-gateway:anthropic/claude-opus-4-5")).toBe(false);
   });
 });
+
+describe("isValidModelFormat", () => {
+  it("returns true for valid model formats", () => {
+    expect(isValidModelFormat("anthropic:claude-sonnet-4-5")).toBe(true);
+    expect(isValidModelFormat("openai:gpt-5.2")).toBe(true);
+    expect(isValidModelFormat("google:gemini-3-pro-preview")).toBe(true);
+    expect(isValidModelFormat("mux-gateway:anthropic/claude-opus-4-5")).toBe(true);
+    // Ollama-style model names with colons in the model ID
+    expect(isValidModelFormat("ollama:gpt-oss:20b")).toBe(true);
+  });
+
+  it("returns false for invalid model formats", () => {
+    // Missing colon
+    expect(isValidModelFormat("gpt")).toBe(false);
+    expect(isValidModelFormat("sonnet")).toBe(false);
+    expect(isValidModelFormat("badmodel")).toBe(false);
+
+    // Colon at start or end
+    expect(isValidModelFormat(":model")).toBe(false);
+    expect(isValidModelFormat("provider:")).toBe(false);
+
+    // Empty string
+    expect(isValidModelFormat("")).toBe(false);
+  });
+});

src/common/utils/ai/models.ts

@@ -6,6 +6,15 @@ import { DEFAULT_MODEL } from "@/common/constants/knownModels";
 
 export const defaultModel = DEFAULT_MODEL;
 
+/**
+ * Validate model string format (must be "provider:model-id").
+ * Supports colons in the model ID (e.g., "ollama:gpt-oss:20b").
+ */
+export function isValidModelFormat(model: string): boolean {
+  const colonIndex = model.indexOf(":");
+  return colonIndex > 0 && colonIndex < model.length - 1;
+}
+
 const MUX_GATEWAY_PREFIX = "mux-gateway:";
 
 /**

src/node/services/agentSession.ts

@@ -35,6 +35,7 @@ import { AttachmentService } from "./attachmentService";
 import type { PostCompactionAttachment, PostCompactionExclusions } from "@/common/types/attachment";
 import { TURNS_BETWEEN_ATTACHMENTS } from "@/common/constants/attachments";
 import { extractEditedFileDiffs } from "@/common/utils/messages/extractEditedFiles";
+import { isValidModelFormat } from "@/common/utils/ai/models";
 
 /**
  * Tracked file state for detecting external edits.
@@ -410,6 +411,21 @@ export class AgentSession {
     // muxMetadata is z.any() in schema - cast to proper type
     const typedMuxMetadata = options?.muxMetadata as MuxFrontendMetadata | undefined;
 
+    // Validate model BEFORE persisting message to prevent orphaned messages on invalid model
+    if (!options?.model || options.model.trim().length === 0) {
+      return Err(
+        createUnknownSendMessageError("No model specified. Please select a model using /model.")
+      );
+    }
+
+    // Validate model string format (must be "provider:model-id")
+    if (!isValidModelFormat(options.model)) {
+      return Err({
+        type: "invalid_model_string",
+        message: `Invalid model string format: "${options.model}". Expected "provider:model-id"`,
+      });
+    }
+
     const userMessage = createMuxMessage(
       messageId,
       "user",
@@ -475,12 +491,6 @@ export class AgentSession {
       this.emitQueuedMessageChanged();
     }
 
-    if (!options?.model || options.model.trim().length === 0) {
-      return Err(
-        createUnknownSendMessageError("No model specified. Please select a model using /model.")
-      );
-    }
-
     return this.streamWithHistory(options.model, options);
   }
 

tests/ipc/sendMessage.errors.test.ts

@@ -79,17 +79,21 @@ describeIntegration("sendMessage error handling tests", () => {
 
   describe("model errors", () => {
     test.concurrent(
-      "should fail with invalid model format",
+      "should fail with invalid model format (model validation happens before message is persisted)",
       async () => {
         await withSharedWorkspace("openai", async ({ env, workspaceId }) => {
           const result = await sendMessage(env, workspaceId, "Hello", {
             model: "invalid-model-without-provider",
           });
 
+          // Should fail synchronously with invalid_model_string error
+          // This happens BEFORE the message is persisted to history
           expect(result.success).toBe(false);
           if (!result.success) {
-            // Should indicate invalid model
-            expect(result.error.type).toBeDefined();
+            expect(result.error.type).toBe("invalid_model_string");
+            if (result.error.type === "invalid_model_string") {
+              expect(result.error.message).toContain("provider:model-id");
+            }
           }
         });
       },