PR #61608: fix(agents): classify Anthropic extra-usage billing

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/61608

Description (problem / solution / changelog)

Summary

• Problem: Anthropic extra-usage exhaustion messages like You're out of extra usage... were not classified as billing/failover-worthy, so the assistant path could skip same-turn model fallback for that provider error.
• Why it matters: configured Anthropic -> fallback model setups could miss the intended handoff and leave users with only a generic invalid-request error path.
• What changed: classify Anthropic extra-usage exhaustion phrasings as billing and add regression coverage for raw-text and JSON-wrapped invalid_request_error variants.
• What did NOT change (scope boundary): this PR does not change unrelated error-formatting behavior outside this matcher path.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #61513
• Related #61513
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the Anthropic billing matcher recognized generic credit/quota/payment wording, but not the current out of extra usage / extra usage is required phrasings Anthropic returns for exhausted extra usage.
• Missing detection / guardrail: no regression test covered these specific Anthropic wording variants in either raw text or JSON-wrapped invalid_request_error payloads.
• Contributing context (if known): the current code already surfaced explicit error text for assistant-error turns, so the remaining bug was the missing failover classification rather than a silent-turn drop.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/pi-embedded-helpers.isbillingerrormessage.test.ts
• Scenario the test should lock in: Anthropic extra-usage exhaustion text, including JSON invalid_request_error payloads, classifies as billing.
• Why this is the smallest reliable guardrail: the regression is a matcher/classification gap, so helper-level assertions directly cover the affected branch without adding a larger harness.
• Existing test that already covers this (if any): none for these exact message variants.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Anthropic extra-usage exhaustion errors now enter the billing/failover path, allowing configured same-turn fallback to engage for these variants.

Diagram (if applicable)

Before:
[user turn] -> [Anthropic returns "out of extra usage"] -> [generic invalid-request classification] -> [no same-turn fallback]

After:
[user turn] -> [Anthropic returns "out of extra usage"] -> [billing classification] -> [configured fallback path can engage]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS 15 / darwin 25.3.0
• Runtime/container: local repo checkout
• Model/provider: Anthropic matcher path
• Integration/channel (if any): N/A
• Relevant config (redacted): fallback-enabled agent model setup

Steps

1. Evaluate or receive an Anthropic assistant error containing You're out of extra usage. Add more at claude.ai/settings/usage and keep going.
2. Route that error through classifyFailoverReason() in the assistant failover path.
3. Observe whether the message is classified as billing/failover-worthy.

Expected

• Anthropic extra-usage exhaustion variants classify as billing.
• Configured same-turn fallback can engage for those variants.

Actual

• Before this change, the exact issue wording classified as null, so it skipped the billing/failover path.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • Ran focused regression tests: pnpm test src/agents/pi-embedded-helpers.isbillingerrormessage.test.ts src/agents/pi-embedded-runner/run/payloads.errors.test.ts
  • Evaluated the exact issue payload against the live helper before the patch and confirmed classifyFailoverReason(...) === null
  • Re-ran the focused regression after the patch and confirmed the variant now classifies as billing
  • Ran pnpm build
• Edge cases checked:
  • Raw text variant
  • JSON-wrapped invalid_request_error variant
  • Existing long-context extra usage is required sibling wording
• What you did not verify:
  • Full-repo pnpm check is currently blocked by unrelated pre-existing type errors in untouched test files: extensions/diffs/src/language-hints.test.ts and src/auto-reply/reply/dispatch-from-config.reply-dispatch.test.ts
  • Full-repo pnpm test was started but not used as a gating signal for this narrow fix

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: broadening billing matching could accidentally catch unrelated prose if the matcher were too loose.
  • Mitigation: coverage locks this to the specific Anthropic extra-usage phrasings in both raw and JSON-wrapped provider-error forms.

AI-assisted: yes. I manually reviewed the touched code, validated the exact issue string against the live helper path, and ran the focused regression tests plus pnpm build.

Made with Cursor

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/pi-embedded-helpers.isbillingerrormessage.test.ts (modified, +16/-0)
• src/agents/pi-embedded-helpers/failover-matches.ts (modified, +2/-0)