fix(agents): reduce billing false positives on long text (#25680)

Land PR #25680 from @lairtonlelis.
Retain explicit status/code/http 402 detection for oversized structured payloads.

Co-authored-by: Ailton <lairton@telnyx.com>

src/agents/pi-embedded-helpers.isbillingerrormessage.test.ts

@@ -69,6 +69,40 @@ describe("isBillingErrorMessage", () => {
       expect(isBillingErrorMessage(sample)).toBe(false);
     }
   });
+  it("does not false-positive on long assistant responses mentioning billing keywords", () => {
+    // Simulate a multi-paragraph assistant response that mentions billing terms
+    const longResponse =
+      "Sure! Here's how to set up billing for your SaaS application.\n\n" +
+      "## Payment Integration\n\n" +
+      "First, you'll need to configure your payment gateway. Most providers offer " +
+      "a dashboard where you can manage credits, view invoices, and upgrade your plan. " +
+      "The billing page typically shows your current balance and payment history.\n\n" +
+      "## Managing Credits\n\n" +
+      "Users can purchase credits through the billing portal. When their credit balance " +
+      "runs low, send them a notification to upgrade their plan or add more credits. " +
+      "You should also handle insufficient balance cases gracefully.\n\n" +
+      "## Subscription Plans\n\n" +
+      "Offer multiple plan tiers with different features. Allow users to upgrade or " +
+      "downgrade their plan at any time. Make sure the billing cycle is clear.\n\n" +
+      "Let me know if you need more details on any of these topics!";
+    expect(longResponse.length).toBeGreaterThan(512);
+    expect(isBillingErrorMessage(longResponse)).toBe(false);
+  });
+  it("still matches explicit 402 markers in long payloads", () => {
+    const longStructuredError =
+      '{"error":{"code":402,"message":"payment required","details":"' + "x".repeat(700) + '"}}';
+    expect(longStructuredError.length).toBeGreaterThan(512);
+    expect(isBillingErrorMessage(longStructuredError)).toBe(true);
+  });
+  it("does not match long numeric text that is not a billing error", () => {
+    const longNonError =
+      "Quarterly report summary: subsystem A returned 402 records after retry. " +
+      "This is an analytics count, not an HTTP/API billing failure. " +
+      "Notes: " +
+      "x".repeat(700);
+    expect(longNonError.length).toBeGreaterThan(512);
+    expect(isBillingErrorMessage(longNonError)).toBe(false);
+  });
   it("still matches real HTTP 402 billing errors", () => {
     const realErrors = [
       "HTTP 402 Payment Required",

src/agents/pi-embedded-helpers/errors.ts

@@ -161,6 +161,8 @@ const CONTEXT_OVERFLOW_ERROR_HEAD_RE =
   /^(?:context overflow:|request_too_large\b|request size exceeds\b|request exceeds the maximum size\b|context length exceeded\b|maximum context length\b|prompt is too long\b|exceeds model context window\b)/i;
 const BILLING_ERROR_HEAD_RE =
   /^(?:error[:\s-]+)?billing(?:\s+error)?(?:[:\s-]+|$)|^(?:error[:\s-]+)?(?:credit balance|insufficient credits?|payment required|http\s*402\b)/i;
+const BILLING_ERROR_HARD_402_RE =
+  /["']?(?:status|code)["']?\s*[:=]\s*402\b|\bhttp\s*402\b|\berror(?:\s+code)?\s*[:=]?\s*402\b|^\s*402\s+payment/i;
 const HTTP_STATUS_PREFIX_RE = /^(?:http\s*)?(\d{3})\s+(.+)$/i;
 const HTTP_STATUS_CODE_PREFIX_RE = /^(?:http\s*)?(\d{3})(?:\s+([\s\S]+))?$/i;
 const HTML_ERROR_PREFIX_RE = /^\s*(?:<!doctype\s+html\b|<html\b)/i;
@@ -703,11 +705,26 @@ export function isTimeoutErrorMessage(raw: string): boolean {
   return matchesErrorPatterns(raw, ERROR_PATTERNS.timeout);
 }
 
+/**
+ * Maximum character length for a string to be considered a billing error message.
+ * Real API billing errors are short, structured messages (typically under 300 chars).
+ * Longer text is almost certainly assistant content that happens to mention billing keywords.
+ */
+const BILLING_ERROR_MAX_LENGTH = 512;
+
 export function isBillingErrorMessage(raw: string): boolean {
   const value = raw.toLowerCase();
   if (!value) {
     return false;
   }
+  // Real billing error messages from APIs are short structured payloads.
+  // Long text (e.g. multi-paragraph assistant responses) that happens to mention
+  // "billing", "payment", etc. should not be treated as a billing error.
+  if (raw.length > BILLING_ERROR_MAX_LENGTH) {
+    // Keep explicit status/code 402 detection for providers that wrap errors in
+    // larger payloads (for example nested JSON bodies or prefixed metadata).
+    return BILLING_ERROR_HARD_402_RE.test(value);
+  }
   if (matchesErrorPatterns(value, ERROR_PATTERNS.billing)) {
     return true;
   }