fix(usage): cap token estimates at the model context window

[kartikkabadi]

Summary

Port of codex-router PR #140: a request the provider answered cannot have exceeded its context window, so the token estimate must never claim it did.

• estimateTokens gains an optional contextWindow cap (new capEstimateAtContextWindow helper).
• The request log caps the ESTIMATE field itself — attempt.inputTokenEstimate (persisted) and the usage-fallback inputTokens — at the routed model's window.
• The combined inputTokens field keeps its existing max(reported, estimate) behavior; provider-reported positive counts are never reduced by the cap.
• Positive/missing reported counts are never rewritten; kiro auto and unknown adapters/models stay uncapped (a window is never invented).

Context window source (file:function):

• Kiro: KIRO_MODEL_CONTEXT_WINDOWS in src/providers/kiro-models.ts (lookup mirrors kiroUpstreamContextWindow in src/adapters/kiro.ts).
• Cursor: inferCursorContextWindow in src/adapters/cursor/discovery.ts.
• Family is chosen by route adapter in contextWindowForModel (src/server/request-log.ts).

Verification

• bun test tests/token-estimate.test.ts — green (extended: cap at window, below-window unchanged, invalid windows ignored, min-1 floor).
• bun test tests/request-log-estimate-cap.test.ts — green (new file: capped estimate, below-window passthrough, positive counts never reduced, ESTIMATE vs combined field distinction, cursor adapter, unknown adapter, kiro auto).
• bun test tests/request-log.test.ts — green (73 pass / 0 fail across the three files); one pre-existing test that asserted an above-window estimate now asserts the capped value.

Checklist

• All CI tests are green on my local testing.
• I pushed my PR to the latest dev commit.
• I resolved all correct Codex and CodeRabbit findings.
• My PR is ready for review.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• Bug Fixes

  • Token estimates are now capped at the applicable model context window.
  • Request logs and calculated usage totals now avoid overstating input tokens.
  • Provider-reported positive usage values remain preserved.
  • Added accurate context-window handling for Kiro and Cursor models.

• Tests

  • Added coverage for context limits, fallback behavior, validation, and minimum token counts.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7f7ff50b-2432-453f-8329-03e67da5e1a2

📥 Commits

Reviewing files that changed from the base of the PR and between 8b1c620 and 21d27b4.

📒 Files selected for processing (5)

• src/lib/token-estimate.ts
• src/server/request-log.ts
• tests/request-log-estimate-cap.test.ts
• tests/request-log.test.ts
• tests/token-estimate.test.ts

---

📝 Walkthrough

Walkthrough

Changes

The token estimator now accepts an optional context window and caps valid estimates. Request logging resolves Kiro and Cursor windows, caps estimated input tokens, and keeps provider-reported usage precedence. Tests cover adapter-specific and fallback behavior.

Context-window token estimation

Layer / File(s)	Summary
Token estimate cap contract src/lib/token-estimate.ts, tests/token-estimate.test.ts	Adds capEstimateAtContextWindow and an optional contextWindow parameter to estimateTokens. Tests cover valid, invalid, minimum, and below-limit values.
Request-log context-window integration src/server/request-log.ts	Resolves Kiro and Cursor context windows, leaves unknown adapters and Kiro auto uncapped, and caps estimates during attempt and final usage logging.
Context-window behavior validation tests/request-log-estimate-cap.test.ts, tests/request-log.test.ts	Tests estimated-versus-reported usage precedence, adapter-specific inference, uncapped fallbacks, and the updated Kiro total.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 21d27

The change caps token estimates at known model context windows while preserving valid reported usage; no actionable merge-blocking risk remains after normal checks and review.

Possibly related PRs

• lidge-jun/opencodex#376: Related token-estimation changes in src/lib/token-estimate.ts.
• lidge-jun/opencodex#439: Related Kiro context-token estimation and request-log accounting.
• lidge-jun/opencodex#1435: Related provider context-window cap enforcement.

Suggested reviewers: wibias, lidge-jun, ingwannu

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: capping usage token estimates at the model context window.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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.}

Warning

⚠️ This pull request shows signs of AI-generated slop (redundant_comments). It has been flagged by CodeRabbit slop detection and should be reviewed carefully.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[kartikkabadi]

Checklist complete:\n\n- [x] Local CI green: typecheck (tsc --noEmit) clean, privacy scan passed, full suite exit 0 on a combined branch of all three ports (#1652/#1653/#1655) — the only suite failures are 18 pre-existing dev-baseline failures in untouched files (server-management-auth, lab-*-regressions, codex-shim), identical on dev.\n- [x] On latest dev (rebased onto 8b1c620).\n- [x] Focused regression tests for this behavior: see test file(s) in the diff.\n- [x] Ready for review.

[lidge-jun]

[Repository bug audit · 2026-08-14]

The estimate-capping rule is reasonable and the implementation correctly leaves positive provider-reported usage untouched. The adapter-selected context-window lookup also avoids guessing across shared model IDs.

Keep this draft until three gaps are closed: link a concrete issue/reproduction, rebase onto current dev, and run exact-head CI (currently action_required). Add a small provider-matrix test for adapter aliases/normalized model IDs so future registry naming changes do not silently disable the cap. This can then merge independently of the calendar-window fix in #1638.