fix(reply): show a clear "model unavailable" reply instead of generic failure

RomneyDa · claude · RomneyDa · commit a436ebf8af7f · 2026-06-28T18:52:54.000-07:00
When a configured model is retired/renamed by the provider, model resolution
fails (run.ts throws a typed FailoverError with reason "model_not_found") and
the agent runner falls back to the generic "Something went wrong … use /new"
reply. That copy is actively misleading for this failure: retrying or starting
a new session can never help, because the model id itself must be changed in
config. Users on a deprecated model (e.g. gpt-5.3-codex on a Codex ChatGPT
account) just see the generic message on every message and on /new.

Classify this failure into a dedicated user-facing reply that explains the
model is unavailable and points at the config. Detection is structural — it
keys off the typed FailoverError reason, not provider error text — so it stays
robust as provider wording changes; free-text rejections without a typed reason
remain the responsibility of the failover layer that owns error classification.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/auto-reply/reply/provider-request-error-classifier.test.ts b/src/auto-reply/reply/provider-request-error-classifier.test.ts
@@ -6,6 +6,7 @@ import {
   PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE,
   PROVIDER_CONVERSATION_STATE_ERROR_USER_MESSAGE,
   PROVIDER_INTERNAL_ERROR_USER_MESSAGE,
+  PROVIDER_MODEL_UNAVAILABLE_USER_MESSAGE,
   PROVIDER_RATE_LIMIT_OR_QUOTA_ERROR_USER_MESSAGE,
 } from "./provider-request-error-classifier.js";
 
@@ -55,6 +56,41 @@ describe("provider request error classifier", () => {
     ).toBeUndefined();
   });
 
+  it("classifies typed model_not_found failover errors as model unavailable", () => {
+    const error = new FailoverError(
+      'Unknown model: openai/gpt-5.3-codex. Found agents.defaults.models["openai/gpt-5.3-codex"] bound to the "codex" agent runtime.',
+      {
+        reason: "model_not_found",
+        provider: "openai",
+        model: "gpt-5.3-codex",
+      },
+    );
+
+    expect(classifyProviderRequestError(error)).toEqual({
+      code: "provider_model_unavailable",
+      userMessage: PROVIDER_MODEL_UNAVAILABLE_USER_MESSAGE,
+      technicalMessage: error.message,
+    });
+  });
+
+  it("does not classify model-not-found from raw provider text alone", () => {
+    // Detection is structural (typed failover reason), not text matching: a
+    // bare error string without the typed reason is left unclassified.
+    expect(
+      classifyProviderRequestError(new Error("Unknown model: openai/gpt-5.3-codex")),
+    ).toBeUndefined();
+  });
+
+  it("does not misclassify other typed failover reasons as model unavailable", () => {
+    const error = new FailoverError("Provider overloaded.", {
+      reason: "overloaded",
+      provider: "openai",
+      model: "gpt-5.5",
+    });
+
+    expect(classifyProviderRequestError(error)).toBeUndefined();
+  });
+
   it.each([
     [
       "OpenAI missing custom tool output",
diff --git a/src/auto-reply/reply/provider-request-error-classifier.ts b/src/auto-reply/reply/provider-request-error-classifier.ts
@@ -12,6 +12,7 @@ export type ProviderRequestErrorCode =
   | "provider_authentication_error"
   | "provider_conversation_state_error"
   | "provider_internal_error"
+  | "provider_model_unavailable"
   | "provider_rate_limit_or_quota_error";
 
 /** Structured provider error classification for reply failure handling. */
@@ -33,6 +34,14 @@ export const PROVIDER_INTERNAL_ERROR_USER_MESSAGE =
 
 export const PROVIDER_AUTHENTICATION_ERROR_USER_MESSAGE = `⚠️ ${AUTH_INVALID_TOKEN_USER_TEXT}`;
 
+/**
+ * User-facing copy for a configured model the provider no longer serves.
+ * Distinct from generic failures because retrying or starting a new session
+ * cannot help: the model id itself must be changed in config.
+ */
+export const PROVIDER_MODEL_UNAVAILABLE_USER_MESSAGE =
+  "⚠️ The configured model is unavailable from the provider — it may have been renamed, retired, or is not offered on this account. This needs a config update (agents.defaults.model); retrying or starting a new session won't fix it.";
+
 /** Classifies provider request failures that are actionable for users. */
 export function classifyProviderRequestError(
   err: unknown,
@@ -49,6 +58,17 @@ export function classifyProviderRequestError(
       technicalMessage,
     };
   }
+  // Detect retired/unavailable models structurally via the typed failover
+  // reason set at resolution time (run.ts), not by matching provider error
+  // text. Free-text provider rejections without a typed reason are left to the
+  // failover layer that owns error classification.
+  if (isFailoverError(err) && err.reason === "model_not_found") {
+    return {
+      code: "provider_model_unavailable",
+      userMessage: PROVIDER_MODEL_UNAVAILABLE_USER_MESSAGE,
+      technicalMessage,
+    };
+  }
   if (
     hasHttp429Evidence(err, technicalMessage) &&
     isGenericProviderRuntimeErrorMessage(technicalMessage)
