feat: redesign max-ai-credits exceeded failure template (#38164)

* chore: initial plan for max-ai-credits exceeded template redesign

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* feat: redesign max-ai-credits exceeded template — inline metrics, no table, no run URL, suggested limit snippet

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Peli de Halleux <pelikhan@users.noreply.github.com>

Author: 3 people

actions/setup/js/handle_agent_failure.cjs

@@ -1477,20 +1477,22 @@ function buildAICreditsRateLimitErrorContext(hasAICreditsRateLimitError, aiCredi
   const formattedMaxAICredits = Number.isFinite(numericMaxAICredits) && numericMaxAICredits > 0 ? formatAIC(numericMaxAICredits) : "";
   const overage = Number.isFinite(numericAICredits) && Number.isFinite(numericMaxAICredits) && numericAICredits > numericMaxAICredits ? numericAICredits - numericMaxAICredits : NaN;
   const formattedOverage = Number.isFinite(overage) && overage > 0 ? formatAIC(overage) : "";
-  const metricsRows = [];
-  if (formattedAICredits) {
-    metricsRows.push(`| AI credits used | \`${formattedAICredits}\` |`);
-  }
-  if (formattedMaxAICredits) {
-    metricsRows.push(`| Guardrail limit (\`max-ai-credits\`) | \`${formattedMaxAICredits}\` |`);
-  }
-  if (formattedOverage) {
-    metricsRows.push(`| Over the limit by | \`${formattedOverage}\` |`);
-  }
-  if (runUrl) {
-    metricsRows.push(`| Run | [View workflow run](${runUrl}) |`);
+
+  // Build inline metrics summary (no table, no run URL)
+  let metricsSummary = "";
+  if (formattedAICredits && formattedMaxAICredits) {
+    metricsSummary = ` Used \`${formattedAICredits}\` of \`${formattedMaxAICredits}\` max`;
+    if (formattedOverage) {
+      metricsSummary += ` (over by \`${formattedOverage}\`)`;
+    }
+    metricsSummary += ".";
+  } else if (formattedAICredits) {
+    metricsSummary = ` Used \`${formattedAICredits}\`.`;
   }
-  const metricsTable = metricsRows.length > 0 ? `\n\n| Metric | Value |\n| --- | --- |\n${metricsRows.join("\n")}` : "";
+
+  // Suggest a new limit: 2x current max, or 2x actual usage if max is unknown, or a reasonable default
+  const baseForSuggestion = Number.isFinite(numericMaxAICredits) && numericMaxAICredits > 0 ? numericMaxAICredits : Number.isFinite(numericAICredits) && numericAICredits > 0 ? numericAICredits : 0;
+  const suggestedCredits = baseForSuggestion > 0 ? Math.ceil(baseForSuggestion * 2) : 2000;
 
   const templateName = "ai_credits_rate_limit_error.md";
   let templatePath = "";
@@ -1504,11 +1506,12 @@ function buildAICreditsRateLimitErrorContext(hasAICreditsRateLimitError, aiCredi
     return (
       "\n" +
       renderTemplateFromFile(templatePath, {
-        metrics_table: metricsTable,
+        metrics_summary: metricsSummary,
+        suggested_credits: suggestedCredits,
       })
     );
   } catch (error) {
-    throw new Error(`failed to render template at ${templatePath}: ${getErrorMessage(error)}; verify template syntax and required placeholders: metrics_table`);
+    throw new Error(`failed to render template at ${templatePath}: ${getErrorMessage(error)}; verify template syntax and required placeholders: metrics_summary, suggested_credits`);
   }
 }
 

actions/setup/js/handle_agent_failure_ai_credits_rate_limit.test.cjs

@@ -19,15 +19,23 @@ describe("handle_agent_failure AI Credits rate-limit context", () => {
     delete process.env.GH_AW_PROMPTS_DIR;
   });
 
-  it("shows actual usage, guardrail details, and collapsible optimization guidance", () => {
+  it("shows inline usage and overage without table, no run URL, with suggested limit snippet", () => {
     const rendered = buildAICreditsRateLimitErrorContext(true, "17.329230000000003", "10.1", "https://github.com/octo/repo/actions/runs/123");
 
     expect(rendered).toContain("AI Credits Budget Exceeded");
-    expect(rendered).toContain("| AI credits used | `17.3` |");
-    expect(rendered).toContain("| Guardrail limit (`max-ai-credits`) | `10.1` |");
-    expect(rendered).toContain("| Over the limit by | `7.23` |");
-    expect(rendered).toContain("| Run | [View workflow run](https://github.com/octo/repo/actions/runs/123) |");
+    // inline metrics
+    expect(rendered).toContain("Used `17.3` of `10.1` max (over by `7.23`)");
+    // no table rows
+    expect(rendered).not.toContain("| AI credits used |");
+    expect(rendered).not.toContain("| Guardrail limit");
+    expect(rendered).not.toContain("| Over the limit by |");
+    // run URL not repeated
+    expect(rendered).not.toContain("https://github.com/octo/repo/actions/runs/123");
+    // suggested limit snippet (2x max = 20.2, ceiled to 21)
+    expect(rendered).toContain("max-ai-credits: 21");
+    // progressive disclosure
     expect(rendered).toContain("<details>");
+    expect(rendered).toContain("<summary>Increase the limit</summary>");
     expect(rendered).toContain("<summary>Tips for reducing AI credit usage</summary>");
     expect(rendered).toContain("https://github.github.com/gh-aw/reference/cost-management/");
     expect(rendered).not.toContain("Consult the billing dashboards for accurate usage and charges.");

actions/setup/js/handle_agent_failure_max_ai_credits_exceeded.test.cjs

@@ -20,36 +20,48 @@ describe("handle_agent_failure Max AI Credits exceeded context", () => {
     delete process.env.GH_AW_PROMPTS_DIR;
   });
 
-  it("shows budget exhaustion message with usage, limit, and overage details", () => {
+  it("shows budget exhaustion message with inline usage, limit, and overage — no table, no run URL", () => {
     const rendered = buildAICreditsRateLimitErrorContext(true, "105000", "100000", "https://github.com/octo/repo/actions/runs/456");
 
     expect(rendered).toContain("AI Credits Budget Exceeded");
     expect(rendered).toContain("hit the configured `max-ai-credits` guardrail");
-    expect(rendered).toContain("| AI credits used |");
-    expect(rendered).toContain("| Guardrail limit (`max-ai-credits`) |");
-    expect(rendered).toContain("| Over the limit by |");
-    expect(rendered).toContain("| Run | [View workflow run](https://github.com/octo/repo/actions/runs/456) |");
+    // inline metrics — no table
+    expect(rendered).toContain("Used `105K` of `100K` max (over by `5K`)");
+    expect(rendered).not.toContain("| AI credits used |");
+    expect(rendered).not.toContain("| Guardrail limit");
+    expect(rendered).not.toContain("| Over the limit by |");
+    // run URL not repeated
+    expect(rendered).not.toContain("https://github.com/octo/repo/actions/runs/456");
+    // suggested limit snippet
+    expect(rendered).toContain("max-ai-credits: 200000");
+    // progressive disclosure
     expect(rendered).toContain("<details>");
+    expect(rendered).toContain("<summary>Increase the limit</summary>");
     expect(rendered).toContain("<summary>Tips for reducing AI credit usage</summary>");
     expect(rendered).toContain("https://github.github.com/gh-aw/reference/cost-management/");
   });
 
-  it("shows message without metrics rows when no credit data is available", () => {
+  it("shows message without metrics when no credit data is available, still shows snippet with default limit", () => {
     const rendered = buildAICreditsRateLimitErrorContext(true, "", "", "");
 
     expect(rendered).toContain("AI Credits Budget Exceeded");
+    expect(rendered).not.toContain("Used `");
     expect(rendered).not.toContain("| AI credits used |");
     expect(rendered).not.toContain("| Guardrail limit");
     expect(rendered).not.toContain("| Run |");
+    expect(rendered).toContain("max-ai-credits: 2000");
   });
 
-  it("does not show overage row when usage does not exceed limit", () => {
+  it("does not show overage when usage does not exceed limit", () => {
     const rendered = buildAICreditsRateLimitErrorContext(true, "50000", "100000", "");
 
     expect(rendered).toContain("AI Credits Budget Exceeded");
-    expect(rendered).toContain("| AI credits used |");
-    expect(rendered).toContain("| Guardrail limit (`max-ai-credits`) |");
+    expect(rendered).toContain("Used `50K` of `100K` max");
+    expect(rendered).not.toContain("over by");
+    expect(rendered).not.toContain("| AI credits used |");
     expect(rendered).not.toContain("| Over the limit by |");
+    // suggested limit is 2x max
+    expect(rendered).toContain("max-ai-credits: 200000");
   });
 
   it("returns empty string when max_ai_credits_exceeded is false", () => {

actions/setup/md/ai_credits_rate_limit_error.md

@@ -1,13 +1,23 @@
 > [!WARNING]
 > **AI Credits Budget Exceeded**
 >
-> The workflow hit the configured `max-ai-credits` guardrail.{metrics_table}
+> The workflow hit the configured `max-ai-credits` guardrail.{metrics_summary}
+
+<details>
+<summary>Increase the limit</summary>
+
+Update `max-ai-credits` in your workflow frontmatter:
+
+```yaml
+max-ai-credits: {suggested_credits}
+```
+
+</details>
 
 <details>
 <summary>Tips for reducing AI credit usage</summary>
 
 - Review the [cost optimization guidance](https://github.github.com/gh-aw/reference/cost-management/).
-- Increase the `max-ai-credits` limit in the workflow frontmatter if the task legitimately requires more credits.
 - Reduce unnecessary model or tool calls in the prompt.
 - Trim large inputs or excess context that does not change the outcome.
 - Split large tasks across smaller runs when possible.