fix: cap balance preflight output estimate

[0xCheetah1]

Summary

Fixes balance preflight fallback for high-output-cap models.

OpenClaw can send the model default as max_tokens, e.g. 128000 for Opus-class models. ClawRouter was treating that as guaranteed spend during the local balance check, so calls to anthropic/claude-opus-5 could fall back to a free model even with $5+ in the wallet. In practice, short Opus 5 calls cost closer to cents, but the preflight assumed worst-case full output.

This adds a preflight-only output estimate cap. The actual request payload is unchanged, and x402/server payment still enforces the real quote.

Changes

• Add estimateBalancePreflightAmount() for low-balance preflight checks.
• Cap preflight assumed output tokens at 4096.
• Keep estimateAmount() exact for budget enforcement, max-cost checks, and cached balance accounting.
• Add regression coverage across high-output Anthropic and OpenAI models.

Verification

• Node v22.23.1
• npm run format:check
• npm run typecheck
• npm run lint
• npm test
• npm run build
• Testbed hotpatch verified through OpenClaw/ClawRouter:
  • anthropic/claude-opus-5
  • max_tokens: 128000
  • wallet around $5.83
  • response stayed on Opus 5 with no low-balance/free fallback

Summary by CodeRabbit

• Bug Fixes

  • Improved balance preflight estimates when requests specify very large output token limits.
  • Preflight checks now cap estimated output usage at 4,096 tokens, aligning “can pay” decisions with bounded preflight spend.

• Tests

  • Added a new test suite covering capped preflight estimates and standard amount estimates with varying output limits.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a 4096-token cap to balance preflight estimates, exposes the general estimator and capped preflight helper, updates balance checks and fallback accounting, and adds parameterized coverage for high-output models.

Changes

Balance preflight estimation

Layer / File(s)	Summary
Capped preflight estimation and validation src/proxy.ts, src/proxy.balance-estimate.test.ts	The general estimateAmount helper is exported, estimateBalancePreflightAmount caps maxTokens at 4096, and tests compare capped preflight estimates with uncapped estimates across high-output models.
Balance check and fallback accounting src/proxy.ts	Balance checks use the capped estimate with the existing buffer, and free-model fallback clears the tracked estimated cost.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: capping the balance preflight output estimate.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/proxy.ts`:
- Around line 4692-4694: In the preflight estimation flow around
estimateBalancePreflightAmount, store the capped result in a separate
preflightEstimatedCostMicros variable used only by checkSufficient. Keep
estimatedCostMicros tied to the uncapped estimate or actual settled payment so
maxCostPerRun enforcement and balance deduction use the full request cost.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c6363729-225a-49ef-ba50-6a529320e210

📥 Commits

Reviewing files that changed from the base of the PR and between 40c7a2a and 0af84fc.

⛔ Files ignored due to path filters (4)

• dist/cli.js is excluded by !**/dist/**
• dist/cli.js.map is excluded by !**/dist/**, !**/*.map
• dist/index.js is excluded by !**/dist/**
• dist/index.js.map is excluded by !**/dist/**, !**/*.map

📒 Files selected for processing (2)

• src/proxy.balance-estimate.test.ts
• src/proxy.ts

[VickyXAI]

Landed on main as 8d4e203 with your authorship preserved, released in v0.12.237 — thank you! The PR branch had rebuilt dist/ against a pre-v0.12.236 base (129k-line churn), so rather than merge the artifact conflict we cherry-picked the src changes (src/proxy.ts + src/proxy.balance-estimate.test.ts, applied clean — main's proxy.ts hadn't moved since your fork point) and rebuilt dist in the release commit. Credited in the CHANGELOG. Nice catch on the free-fallback path also deducting the stale paid estimate from the cached balance.