fix: normalize nested usage details by kiranmagic7 · Pull Request #16 · steipete/tokentally

kiranmagic7 · 2026-06-12T11:21:16Z

Summary

Normalize nested provider usage details for cached input tokens and reasoning tokens.
Preserve cachedInputTokens through tallyCosts() aggregation when providers expose it.
Add regression coverage for Chat Completions-style and Responses API-style usage payloads.

Validation

pnpm test — 5 files / 21 tests passed
pnpm typecheck — passed
pnpm lint — passed
pnpm check — passed with coverage
git diff --check — passed

Notes

This keeps existing pricing behavior unchanged. cachedInputTokens is exposed as normalized usage metadata; discounted cached-input billing can stay a separate pricing feature if/when the library adds provider-specific cached-token pricing.

clawsweeper · 2026-06-12T11:22:11Z

Codex review: needs maintainer review before merge. Reviewed June 12, 2026, 11:07 AM ET / 15:07 UTC.

Summary
The PR adds normalization and aggregation of nested cached-input and reasoning-token metadata, with public API documentation and regression coverage.

Reproducibility: yes. from source inspection, though it was not executed locally during this read-only review. Current main has no nested-detail lookup, and the contributor’s exact-head built-package output demonstrates the observable gap and corrected result.

Review metrics: 2 noteworthy metrics.

Patch surface: 7 files, +122/-7. The patch consistently covers the public type, parser, aggregation, regression tests, README, and repository-required release note.
Regression coverage: 4 tests added. Three normalization cases and one aggregation case exercise both nested provider payload shapes and metadata preservation.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

No automated repair is needed; the remaining action is ordinary owner review and merge judgment.

Security
Cleared: The patch changes only TypeScript types, parsing, aggregation, tests, and documentation, with no dependency, workflow, secret, install, publishing, or external code-execution changes.

Review details

Best possible solution:

Land the additive provider-agnostic normalization and aggregation behavior while keeping cached-token pricing as a separate future concern.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection, though it was not executed locally during this read-only review. Current main has no nested-detail lookup, and the contributor’s exact-head built-package output demonstrates the observable gap and corrected result.

Is this the best way to solve the issue?

Yes. Extending the existing best-effort alias normalizer and established tally accumulator is narrower and more maintainable than introducing provider-specific parsing or coupling metadata collection to cached-token pricing.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d2a54bb78442.

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. Exact-head terminal output from the built package shows both representative nested payloads normalizing correctly and cached-input metadata surviving aggregation.
add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): Exact-head terminal output from the built package shows both representative nested payloads normalizing correctly and cached-input metadata surviving aggregation.
remove rating: 🧂 unranked krab: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.
remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

P2: This is a bounded public-library usage-normalization improvement with limited blast radius and no urgent runtime outage.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): Exact-head terminal output from the built package shows both representative nested payloads normalizing correctly and cached-input metadata surviving aggregation.
proof: sufficient: Contributor real behavior proof is sufficient. Exact-head terminal output from the built package shows both representative nested payloads normalizing correctly and cached-input metadata surviving aggregation.

Evidence reviewed

What I checked:

Current-main normalization gap: Current main recognizes only top-level token and reasoning aliases, so nested input/output detail objects are discarded. (src/usage.ts:41, d2a54bb78442)
Focused parser implementation: The branch reads cached-token fields from input details and reasoning-token fields from output details while retaining the established first-valid-alias normalization approach. (src/usage.ts:52, 1c6ea0537ae8)
Aggregation preservation: The branch accumulates optional cached-input metadata across calls without changing the existing input/output cost calculation. (src/tally.ts:41, 1c6ea0537ae8)
Regression coverage: The added tests cover Chat Completions details, Responses API details, a top-level cached-token alias, and multi-call tally aggregation. (tests/usage.test.ts:28, 1c6ea0537ae8)
Real behavior proof: The contributor posted exact-head built-package output showing both nested payload forms normalize correctly and cached-input tokens survive aggregation. (1c6ea0537ae8)
Feature provenance: Git history shows the repository owner introduced the central normalizer, tally accumulator, public usage type, and original tests in the initial tokentally implementation. (src/usage.ts:25, fb5cb3b71075)

Likely related people:

steipete: Peter Steinberger’s commits introduced and released the normalization, tally, public usage type, and associated tests across the affected code path. (role: feature introducer and recent area contributor; confidence: high; commits: fb5cb3b71075, fdedcf96c3da; files: src/usage.ts, src/tally.ts, src/types.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

kiranmagic7 · 2026-06-12T15:04:25Z

Added runtime proof for exact head 1c6ea0537ae8ea6493568c6f5644985606ffd343 using the built package output.

Validation:

pnpm install --frozen-lockfile -> completed from the lockfile
pnpm check -> passed: lint, type-aware lint, typecheck, and coverage (5 files / 21 tests passed)
git diff --check -> passed
pnpm build -> passed

Built-library invocation:

node --input-type=module <<'NODE'
import { normalizeTokenUsage, tallyCosts } from './dist/index.js';

const chatCompletions = normalizeTokenUsage({
  prompt_tokens: 100,
  completion_tokens: 20,
  total_tokens: 120,
  prompt_tokens_details: { cached_tokens: 40 },
  completion_tokens_details: { reasoning_tokens: 7 },
});
const responses = normalizeTokenUsage({
  input_tokens: 150,
  output_tokens: 30,
  total_tokens: 180,
  input_tokens_details: { cached_tokens: 25 },
  output_tokens_details: { reasoning_tokens: 12 },
});
const tally = await tallyCosts({
  calls: [
    { model: 'demo-model', usage: chatCompletions },
    { model: 'demo-model', usage: responses },
  ],
  resolvePricing: async () => ({ inputUsdPerToken: 0.000001, outputUsdPerToken: 0.000002 }),
});
console.log(JSON.stringify({ chatCompletions, responses, demoModelUsage: tally.byModel['demo-model'].usage }, null, 2));
NODE

Output:

{
  "chatCompletions": {
    "inputTokens": 100,
    "outputTokens": 20,
    "cachedInputTokens": 40,
    "reasoningTokens": 7,
    "totalTokens": 120
  },
  "responses": {
    "inputTokens": 150,
    "outputTokens": 30,
    "cachedInputTokens": 25,
    "reasoningTokens": 12,
    "totalTokens": 180
  },
  "demoModelUsage": {
    "inputTokens": 250,
    "outputTokens": 50,
    "cachedInputTokens": 65,
    "reasoningTokens": 19,
    "totalTokens": 300
  }
}

This shows the built dist entry normalizing both representative nested payload shapes and preserving cachedInputTokens through aggregation.

@clawsweeper re-review

clawsweeper · 2026-06-12T15:04:29Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/27424208958
Updated: 2026-06-12T15:08:42.408Z

fix: normalize nested usage details

1c6ea05

steipete added 2 commits June 13, 2026 03:50

docs: update nested usage release notes

24bb953

fix: avoid nested reasoning double count

c043c5c

steipete merged commit b422607 into steipete:main Jun 13, 2026
1 check passed

Navigation Menu

fix: normalize nested usage details - #16

fix: normalize nested usage details#16
steipete merged 3 commits into
steipete:mainfrom
kiranmagic7:fix/nested-usage-details

kiranmagic7 commented Jun 12, 2026

Uh oh!

clawsweeper Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

kiranmagic7 commented Jun 12, 2026

Uh oh!

clawsweeper Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kiranmagic7 commented Jun 12, 2026

Summary

Validation

Notes

Uh oh!

clawsweeper Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kiranmagic7 commented Jun 12, 2026

Uh oh!

clawsweeper Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented Jun 12, 2026 •

edited

Loading

clawsweeper Bot commented Jun 12, 2026 •

edited

Loading