Classify planner failures on the shapes providers actually emit

The recovery card's whole job is deciding whether a failure is fixed by
opening Providers or by retrying, and the first classifier got the two
most common browser cases backwards: Chrome's "Failed to fetch" and
Firefox's "NetworkError…" — what a stopped local provider looks like from
inside the extension — both fell through to `provider`, while a bare scan
for 5xx-shaped digits read "max_tokens 512" as a server error and led
with a Retry that could only fail the same way.

Status codes are now only trusted where they read as a status, textual
auth rejections ("Unauthorized", "invalid_api_key") are recognized
without a code, and a remaining 4xx stays `provider` because retrying an
argument the provider rejected is not the fix.

Also: carry `failureKind` through the planner gate wrapper, which was
dropping it before any caller could read it; name the failing provider in
the card, since "open Providers" is only actionable when the user knows
which one to look at; and end the detail sentence before appending "No
tools ran."

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: esokullu

src/chrome/src/agent/agent.js

@@ -127,16 +127,38 @@ function isBrowserNewTabUrl(url) {
   return BROWSER_NEW_TAB_URL_PREFIXES.some(prefix => value.startsWith(prefix));
 }
 
+// Only read a 3-digit number as a status code where it actually reads like
+// one — prefixed by a status word, leading the message, or parenthesized.
+// A bare scan would turn "max_tokens 512" into a 5xx and recommend a retry
+// that can only fail the same way.
+const PLANNER_FAILURE_STATUS_PATTERNS = [
+  /\b(?:error|http|status|code|returned|response)\s*[:#-]?\s*(\d{3})\b/i,
+  /^\s*\(?(\d{3})\)?\b/,
+  /\((\d{3})\)/,
+];
+const PLANNER_AUTH_FAILURE_RE = /\b(?:unauthori[sz]ed|unauthenticated|forbidden|permission denied|invalid credentials|(?:invalid|incorrect|missing|expired)[\s_-]*api[\s_-]*key|api[\s_-]*key[\s_-]*(?:is\s*)?(?:missing|invalid|incorrect|expired|not\s*set|required)|authentication|(?:expired|invalid)[\s_-]*token|token[\s_-]*expired)\b/i;
+// "Failed to fetch" (Chrome) and "NetworkError…" (Firefox) are the shapes a
+// dead local provider or an offline machine actually produces, so they have
+// to land in the bucket that offers Retry first.
+const PLANNER_TRANSIENT_FAILURE_RE = /\b(?:timed?\s*out|timeout|network\w*|failed to fetch|fetch failed|load failed|connection (?:closed|reset|refused|error)|econn\w+|socket hang up|temporar(?:y|ily)|unavailable|overloaded|rate[\s_-]?limit\w*|too many requests|bad gateway|gateway timeout)\b/i;
+
 function plannerRequestFailureKind(detail) {
   const text = String(detail || '');
-  const statusMatch = text.match(/\b(?:error|http|status)\s*[:#-]?\s*(\d{3})\b/i)
-    || text.match(/\b(401|403|408|425|429|5\d\d)\b/);
-  const status = Number(statusMatch?.[1] || 0);
-  if (status === 401 || status === 403) return 'auth';
-  if ([408, 425, 429].includes(status) || status >= 500) return 'transient';
-  if (/\b(?:timed?\s*out|timeout|network|fetch failed|connection (?:closed|reset|refused)|econn\w+|temporar(?:y|ily)|unavailable)\b/i.test(text)) {
-    return 'transient';
+  let status = 0;
+  for (const pattern of PLANNER_FAILURE_STATUS_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      status = Number(match[1]);
+      break;
+    }
   }
+  if (status === 401 || status === 403) return 'auth';
+  if ([408, 425, 429].includes(status) || (status >= 500 && status <= 599)) return 'transient';
+  if (PLANNER_AUTH_FAILURE_RE.test(text)) return 'auth';
+  // A remaining 4xx is a request the provider rejected on its merits; a retry
+  // of the same request is not the fix.
+  if (status >= 400 && status <= 499) return 'provider';
+  if (PLANNER_TRANSIENT_FAILURE_RE.test(text)) return 'transient';
   return 'provider';
 }
 
@@ -7233,6 +7255,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
         reason: gate.reason,
         requestKind: gate.requestKind,
         requiresStateChange: gate.requiresStateChange,
+        // Carried so a caller can tell an auth failure from a transient one
+        // without re-parsing the message text.
+        ...(gate.failureKind ? { failureKind: gate.failureKind } : {}),
       };
     }
 
@@ -7412,7 +7437,8 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
       500,
       { collapseWhitespace: true },
     );
-    const message = `Planner request failed before a valid response was available: ${detail} No tools ran.`;
+    const detailSentence = /[.!?]$/.test(detail) ? detail : `${detail}.`;
+    const message = `Planner request failed before a valid response was available: ${detailSentence} No tools ran.`;
     const failureKind = plannerRequestFailureKind(detail);
     onUpdate('warning', {
       code: 'planner_request_failed',

src/chrome/src/ui/sidepanel.js

@@ -5255,6 +5255,15 @@ function renderPlannerRequestFailure(assistantEl, data, retryPayload = null) {
   const message = document.createElement('div');
   message.className = 'planner-request-failure-message';
   message.textContent = data.message || 'Planner request failed before a valid response was available.';
+  // Name the provider that failed — with several configured, "open Providers"
+  // is only actionable if the user knows which one to look at. The label is a
+  // proper noun, so it needs no translation.
+  if (data.provider) {
+    const providerName = document.createElement('div');
+    providerName.className = 'planner-request-failure-provider';
+    providerName.textContent = data.provider;
+    message.appendChild(providerName);
+  }
 
   const actions = document.createElement('div');
   actions.className = 'planner-request-failure-actions';

src/chrome/styles/sidepanel.css

@@ -2877,6 +2877,13 @@ body {
   color: var(--error-soft);
 }
 
+.planner-request-failure-provider {
+  margin-top: 4px;
+  font-size: 11px;
+  font-weight: 600;
+  opacity: 0.85;
+}
+
 .planner-request-failure-actions {
   display: flex;
   flex-wrap: wrap;

src/firefox/src/agent/agent.js

@@ -122,16 +122,38 @@ function normalizeDoneOutcome(value) {
   return DONE_OUTCOMES.has(outcome) ? outcome : null;
 }
 
+// Only read a 3-digit number as a status code where it actually reads like
+// one — prefixed by a status word, leading the message, or parenthesized.
+// A bare scan would turn "max_tokens 512" into a 5xx and recommend a retry
+// that can only fail the same way.
+const PLANNER_FAILURE_STATUS_PATTERNS = [
+  /\b(?:error|http|status|code|returned|response)\s*[:#-]?\s*(\d{3})\b/i,
+  /^\s*\(?(\d{3})\)?\b/,
+  /\((\d{3})\)/,
+];
+const PLANNER_AUTH_FAILURE_RE = /\b(?:unauthori[sz]ed|unauthenticated|forbidden|permission denied|invalid credentials|(?:invalid|incorrect|missing|expired)[\s_-]*api[\s_-]*key|api[\s_-]*key[\s_-]*(?:is\s*)?(?:missing|invalid|incorrect|expired|not\s*set|required)|authentication|(?:expired|invalid)[\s_-]*token|token[\s_-]*expired)\b/i;
+// "Failed to fetch" (Chrome) and "NetworkError…" (Firefox) are the shapes a
+// dead local provider or an offline machine actually produces, so they have
+// to land in the bucket that offers Retry first.
+const PLANNER_TRANSIENT_FAILURE_RE = /\b(?:timed?\s*out|timeout|network\w*|failed to fetch|fetch failed|load failed|connection (?:closed|reset|refused|error)|econn\w+|socket hang up|temporar(?:y|ily)|unavailable|overloaded|rate[\s_-]?limit\w*|too many requests|bad gateway|gateway timeout)\b/i;
+
 function plannerRequestFailureKind(detail) {
   const text = String(detail || '');
-  const statusMatch = text.match(/\b(?:error|http|status)\s*[:#-]?\s*(\d{3})\b/i)
-    || text.match(/\b(401|403|408|425|429|5\d\d)\b/);
-  const status = Number(statusMatch?.[1] || 0);
-  if (status === 401 || status === 403) return 'auth';
-  if ([408, 425, 429].includes(status) || status >= 500) return 'transient';
-  if (/\b(?:timed?\s*out|timeout|network|fetch failed|connection (?:closed|reset|refused)|econn\w+|temporar(?:y|ily)|unavailable)\b/i.test(text)) {
-    return 'transient';
+  let status = 0;
+  for (const pattern of PLANNER_FAILURE_STATUS_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      status = Number(match[1]);
+      break;
+    }
   }
+  if (status === 401 || status === 403) return 'auth';
+  if ([408, 425, 429].includes(status) || (status >= 500 && status <= 599)) return 'transient';
+  if (PLANNER_AUTH_FAILURE_RE.test(text)) return 'auth';
+  // A remaining 4xx is a request the provider rejected on its merits; a retry
+  // of the same request is not the fix.
+  if (status >= 400 && status <= 499) return 'provider';
+  if (PLANNER_TRANSIENT_FAILURE_RE.test(text)) return 'transient';
   return 'provider';
 }
 
@@ -6172,6 +6194,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
         reason: gate.reason,
         requestKind: gate.requestKind,
         requiresStateChange: gate.requiresStateChange,
+        // Carried so a caller can tell an auth failure from a transient one
+        // without re-parsing the message text.
+        ...(gate.failureKind ? { failureKind: gate.failureKind } : {}),
       };
     }
 
@@ -6350,7 +6375,8 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
       500,
       { collapseWhitespace: true },
     );
-    const message = `Planner request failed before a valid response was available: ${detail} No tools ran.`;
+    const detailSentence = /[.!?]$/.test(detail) ? detail : `${detail}.`;
+    const message = `Planner request failed before a valid response was available: ${detailSentence} No tools ran.`;
     const failureKind = plannerRequestFailureKind(detail);
     onUpdate('warning', {
       code: 'planner_request_failed',

src/firefox/src/ui/sidepanel.js

@@ -5092,6 +5092,15 @@ function renderPlannerRequestFailure(assistantEl, data, retryPayload = null) {
   const message = document.createElement('div');
   message.className = 'planner-request-failure-message';
   message.textContent = data.message || 'Planner request failed before a valid response was available.';
+  // Name the provider that failed — with several configured, "open Providers"
+  // is only actionable if the user knows which one to look at. The label is a
+  // proper noun, so it needs no translation.
+  if (data.provider) {
+    const providerName = document.createElement('div');
+    providerName.className = 'planner-request-failure-provider';
+    providerName.textContent = data.provider;
+    message.appendChild(providerName);
+  }
 
   const actions = document.createElement('div');
   actions.className = 'planner-request-failure-actions';

src/firefox/styles/sidepanel.css

@@ -2761,6 +2761,13 @@ body {
   color: var(--error-soft);
 }
 
+.planner-request-failure-provider {
+  margin-top: 4px;
+  font-size: 11px;
+  font-weight: 600;
+  opacity: 0.85;
+}
+
 .planner-request-failure-actions {
   display: flex;
   flex-wrap: wrap;

test/run.js

@@ -49590,6 +49590,80 @@ test('planner request errors stop accurately instead of masquerading as JSON rep
       );
       assert.equal(transient.failureKind, 'transient', `${label}: 503 planner failure was not classified as transient`);
       assert.equal(warning?.failureKind, 'transient', `${label}: transient category was not exposed to the sidepanel`);
+
+      // The category only reorders two always-present buttons, but it is the
+      // whole point of the card: an auth failure must lead with Providers and
+      // a dropped connection must lead with Retry. Classification runs on raw
+      // provider prose, so pin the shapes real providers actually emit —
+      // including the browser's own fetch failures, which is what a stopped
+      // local server looks like from inside the extension.
+      const classifications = [
+        ['Incorrect API key provided: sk-***. (status 401)', 'auth', 'parenthesized 401'],
+        ['Unauthorized', 'auth', 'status-free auth rejection'],
+        ['invalid_api_key: authentication failed', 'auth', 'textual auth rejection'],
+        ['TypeError: Failed to fetch', 'transient', 'Chrome transport failure'],
+        ['NetworkError when attempting to fetch resource.', 'transient', 'Firefox transport failure'],
+        ['The request timed out after 60000 ms', 'transient', 'timeout'],
+        ['ECONNREFUSED 127.0.0.1:11434', 'transient', 'unreachable local provider'],
+        ['Rate limit reached. Please try again (429)', 'transient', 'rate limit'],
+        ['Provider returned 400: max_tokens 512 is invalid', 'provider', 'rejected request carrying a 5xx-shaped number'],
+        ['This model requires 8192 context, got 500 tokens', 'provider', 'prose carrying a 5xx-shaped number'],
+        ['insufficient_quota: You exceeded your current quota', 'provider', 'billing failure'],
+      ];
+      for (const [detail, expected, why] of classifications) {
+        agent._chatWithCostAllowance = async () => { throw new Error(detail); };
+        warning = null;
+        const classified = await agent._runPlannerGate(
+          tabId,
+          { role: 'user', content: 'Classify this failure.' },
+          onUpdate,
+          null,
+        );
+        assert.equal(
+          classified.failureKind,
+          expected,
+          `${label}: ${why} ("${detail}") should recover as ${expected}`,
+        );
+        assert.equal(
+          warning?.failureKind,
+          expected,
+          `${label}: ${why} lost its category on the way to the sidepanel`,
+        );
+        assert.match(
+          classified.message || '',
+          /[.!?] No tools ran\.$/,
+          `${label}: ${why} produced a run-on failure message`,
+        );
+      }
+    }
+  });
+});
+
+test('planner failure category survives the planner gate wrapper', async () => {
+  await withPlannerBrowserGlobals(async () => {
+    for (const [label, AgentClass] of [['chrome', AgentCh], ['firefox', AgentFx]]) {
+      const tabId = label === 'chrome' ? 9157 : 9158;
+      const provider = { name: 'broken-provider', model: 'broken-model', config: {} };
+      const agent = new AgentClass({ getActive: () => provider });
+      agent._chatWithCostAllowance = async () => { throw new Error('401 invalid API key'); };
+
+      const messages = [];
+      const outcome = await agent._maybeRunPlannerGate(
+        tabId,
+        messages,
+        { role: 'user', content: 'Perform this task.' },
+        () => {},
+        'act',
+        null,
+        null,
+      );
+      assert.equal(outcome.proceed, false, `${label}: planner failure unexpectedly continued into execution`);
+      assert.equal(outcome.reason, 'planner_error', `${label}: planner failure lost its planner status`);
+      assert.equal(
+        outcome.failureKind,
+        'auth',
+        `${label}: the gate wrapper dropped the failure category before any caller could read it`,
+      );
     }
   });
 });
@@ -49658,8 +49732,14 @@ test('planner request failures expose provider settings and retry actions in bot
       /function rebindPlannerRequestFailureControls\(\) \{[\s\S]*?planner-request-failure-provider-btn[\s\S]*?bindPlannerProviderSettingsButton/,
       `${label}: restored Providers buttons are not rebound`,
     );
+    assert.match(
+      panel,
+      /if \(data\.provider\) \{[\s\S]*?providerName\.className = 'planner-request-failure-provider';[\s\S]*?providerName\.textContent = data\.provider;/,
+      `${label}: the failing provider is never named, so "open Providers" does not say which one to fix`,
+    );
     assert.match(css, /\.planner-request-failure-actions \{/, `${label}: planner failure action row is not styled`);
     assert.match(css, /\.planner-request-failure-action\.primary \{/, `${label}: planner failure primary action is not styled`);
+    assert.match(css, /\.planner-request-failure-provider \{/, `${label}: planner failure provider label is not styled`);
   }
 });