fix(gateway): format usage dates in range timezone by NianJiuZst · Pull Request #100567 · openclaw/openclaw

NianJiuZst · 2026-07-06T02:50:02Z

What Problem This Solves

Fixes an issue where sessions.usage responses could report startDate / endDate labels using UTC calendar days even when the request interpreted the range in a specific UTC offset or gateway-local time.

AI-assisted.

Why This Change Was Made

The response date labels now use the same date interpretation as range resolution. When callers provide both explicit dates, the response preserves those calendar labels; otherwise it formats the computed range timestamps through the selected interpretation. This also updates explicit end-date resolution to use calendar day ends for the selected interpretation so gateway-local DST transition days do not query data outside the labelled range.

User Impact

Usage clients in non-UTC offsets can trust that sessions.usage.startDate and sessions.usage.endDate describe the requested local day instead of an adjacent UTC day. Gateway-local explicit ranges on DST-short days also avoid including data from the next local day.

Evidence

node scripts/run-vitest.mjs src/gateway/server-methods/usage.sessions-usage.test.ts src/gateway/server-methods/usage.test.ts passed: 4 files, 100 tests.
node_modules/.bin/oxfmt --check --threads=1 src/gateway/server-methods/usage.ts src/gateway/server-methods/usage.test.ts src/gateway/server-methods/usage.sessions-usage.test.ts passed.
git diff --check passed.
.agents/skills/autoreview/scripts/autoreview --mode local passed with no accepted/actionable findings after addressing the gateway DST boundary review finding.

clawsweeper · 2026-07-06T02:58:56Z

Codex review: needs maintainer review before merge. Reviewed July 6, 2026, 12:04 AM ET / 04:04 UTC.

Summary
The PR refactors gateway usage date-range helpers so sessions.usage date labels and gateway-local DST boundaries follow the request's UTC/gateway/specific timezone interpretation, with regression tests for offset and DST cases.

PR surface: Source +23, Tests +76. Total +99 across 4 files.

Reproducibility: yes. The maintainer proof gives a concrete current-main gateway repro for sessions.usage with startDate=endDate=2026-07-06, mode=specific, and utcOffset=UTC+8, and current main source explains why it returns a UTC-shifted start label.

Review metrics: none identified.

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 ClawSweeper repair is needed; the current PR head already contains the focused fix, tests, and sufficient real behavior proof with no review findings.

Security
Cleared: No concrete security or supply-chain concern found; the diff only changes gateway usage date math and tests, with no dependency, workflow, secret, packaging, or code-execution surface changes.

Review details

Best possible solution:

Land the focused gateway fix after normal exact-head required checks complete, keeping one canonical date-interpretation path for range boundaries, daily buckets, and response labels.

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

Yes. The maintainer proof gives a concrete current-main gateway repro for sessions.usage with startDate=endDate=2026-07-06, mode=specific, and utcOffset=UTC+8, and current main source explains why it returns a UTC-shifted start label.

Is this the best way to solve the issue?

Yes. The PR fixes the gateway owner boundary by sharing interpreted calendar-day math for range resolution and response labels; a UI-only relabel would leave the public gateway RPC inconsistent with its own request semantics.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The PR has live gateway proof from current main and repaired head, and the current head keeps the same changed usage files as the proven head while its Real behavior proof check passed.
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): The PR has live gateway proof from current main and repaired head, and the current head keeps the same changed usage files as the proven head while its Real behavior proof check passed.

Label justifications:

P2: This is a normal-priority gateway usage reporting bug with limited blast radius to date labels and range boundaries.
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): The PR has live gateway proof from current main and repaired head, and the current head keeps the same changed usage files as the proven head while its Real behavior proof check passed.
proof: sufficient: Contributor real behavior proof is sufficient. The PR has live gateway proof from current main and repaired head, and the current head keeps the same changed usage files as the proven head while its Real behavior proof check passed.

Evidence reviewed

PR surface:

Source +23, Tests +76. Total +99 across 4 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	1	76	53	+23
Tests	3	78	2	+76
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	4	154	55	+99

What I checked:

Repository policy read: Read the root AGENTS.md plus the gateway and gateway server-methods scoped AGENTS.md files; the review applied the gateway policy requiring caller/callee/sibling/test/proof inspection for PR verdicts. (AGENTS.md:1, bf04d049fa36)
Current-main behavior formats labels in UTC: Current main builds sessions.usage result labels from formatDateStr(startMs/endMs), whose UTC getters can produce a previous or next UTC calendar day for a range interpreted in a non-UTC offset. (src/gateway/server-methods/usage.ts:1474, bf04d049fa36)
PR implementation centralizes interpreted calendar math: The PR adds DateParts, datePartsToStartMs, datePartsToEndMs, and formatDateLabel, then uses the same interpretation for explicit ranges, trailing ranges, and sessions.usage response labels. (src/gateway/server-methods/usage.ts:180, 4a5b3fd4a4ac)
Gateway protocol and UI callers use interpreted dates: The protocol exposes mode and utcOffset for sessions.usage, and the web usage caller sends mode: specific plus the browser UTC offset for local-time requests, so fixing the gateway response labels is the right owner boundary. (packages/gateway-protocol/src/schema/sessions.ts:520, bf04d049fa36)
Sibling daily bucket contract checked: Session cost daily bucket formatting already accepts a fixed UTC offset or gateway-local timezone, which matches the PR's decision to align response labels with the same interpreted day keys rather than patching only the UI. (src/infra/session-cost-usage.ts:927, bf04d049fa36)
Regression tests cover offset labels and DST boundaries: The PR adds focused tests for UTC+8 response labels and gateway-local DST-short days, plus helper tests proving range end boundaries and trailing ranges stay on calendar days across DST. (src/gateway/server-methods/usage.sessions-usage.test.ts:344, 4a5b3fd4a4ac)

Likely related people:

vincentkoc: Authored the branch repair commit, supplied the real gateway repro/Testbox proof, and appears in recent sessions.usage history as reviewer/co-author on related usage fixes. (role: recent area contributor and reviewer; confidence: high; commits: 4a5b3fd4a4ac, eb03d0ee2ba1, aebf0bbd2da7; files: src/gateway/server-methods/usage.ts, src/gateway/server-methods/usage.test.ts, src/gateway/server-methods/usage.sessions-usage.test.ts)
NianJiuZst: Authored the initial PR commit and also authored the recently merged sessions.usage cache-read fix on the same gateway usage module, so they have direct recent history in this surface beyond opening this PR. (role: recent area contributor; confidence: medium; commits: b715b4c203cd, efe4a59ceb75; files: src/gateway/server-methods/usage.ts, src/gateway/server-methods/usage.sessions-usage.test.ts)
steipete: Recent main history shows comparative usage/cost work that explicitly aligned cost and session daily timezone buckets, and UI callers depend on this gateway date interpretation contract. (role: recent area contributor; confidence: medium; commits: ff32076f78b2, 99bd27535985, a8154f425c0c; files: src/gateway/server-methods/usage.ts, ui/src/lib/sessions/usage.ts, ui/src/pages/usage/route.ts)
Alix-007: Authored the recent merged inverted startDate/endDate range fix that introduced or maintained the central resolveDateRange behavior this PR refactors. (role: adjacent date-range contributor; confidence: medium; commits: 640258d7b31d; files: src/gateway/server-methods/usage.ts, src/gateway/server-methods/usage.test.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.

Review history (3 earlier review cycles)

reviewed 2026-07-06T03:02:12.172Z sha 7d43986 :: needs real behavior proof before merge. :: none
reviewed 2026-07-06T03:08:33.410Z sha 7d43986 :: needs real behavior proof before merge. :: none
reviewed 2026-07-06T03:51:46.058Z sha 8971ea2 :: needs maintainer review before merge. :: none

vincentkoc · 2026-07-06T03:41:15Z

Reviewed, repaired, and synchronized with current main on the contributor branch at 4a5b3fd4a4ac76302722e3bbeac2350ee6914c92.

The gateway now uses one calendar-day path for range boundaries and response labels, including gateway-local trailing ranges across DST.

Evidence:

Real current-main gateway repro for sessions.usage, 2026-07-06, mode=specific, utcOffset=UTC+8: returned 2026-07-05..2026-07-06.
Real repaired-head gateway on Blacksmith Testbox tbx_01kwtqkhk9x2h7nk0k926xb6sy: returned 2026-07-06..2026-07-06 for the same request.
Focused gateway usage tests: 106 passed.
Final-head Blacksmith Testbox tbx_01kwtqkhk9x2h7nk0k926xb6sy: 106 focused tests passed. The immediately preceding rebased head also passed pnpm check:changed and the real RPC proof; the final rebase changed no usage files.
Fresh autoreview: no accepted/actionable findings.
Exact-head CI: https://github.com/openclaw/openclaw/actions/runs/28766775222

No intervening commits on main changed the four reviewed usage files.

vincentkoc · 2026-07-06T04:11:27Z

Merged via squash.

Prepared head SHA: 4a5b3fd4a4ac76302722e3bbeac2350ee6914c92
Landed commit: 37f96bde4d90ada5808d4d44f8c141aa2d4520f9

* fix: format usage date labels by range timezone * fix(gateway): keep usage ranges on calendar days --------- Co-authored-by: NianJiuZst <[email protected]> Co-authored-by: Vincent Koc <[email protected]>

openclaw-barnacle Bot added gateway Gateway runtime size: S labels Jul 6, 2026

NianJiuZst marked this pull request as ready for review July 6, 2026 02:58

vincentkoc self-assigned this Jul 6, 2026

openclaw-barnacle Bot added size: M and removed size: S labels Jul 6, 2026

vincentkoc changed the title ~~fix: format usage date labels by range timezone~~ fix(gateway): format usage dates in range timezone Jul 6, 2026

vincentkoc requested a review from a team as a code owner July 6, 2026 03:42

openclaw-barnacle Bot added docs Improvements or additions to documentation app: android App: android app: ios App: ios app: web-ui App: web-ui cli CLI command changes scripts Repository scripts agents Agent runtime and tooling extensions: qa-lab size: XL and removed size: M labels Jul 6, 2026

vincentkoc force-pushed the codex/usage-specific-date-labels branch from 0aa9878 to 8971ea2 Compare July 6, 2026 03:46

openclaw-barnacle Bot removed docs Improvements or additions to documentation app: android App: android app: ios App: ios app: web-ui App: web-ui cli CLI command changes scripts Repository scripts labels Jul 6, 2026

openclaw-barnacle Bot added size: M and removed agents Agent runtime and tooling extensions: qa-lab size: XL labels Jul 6, 2026

NianJiuZst and others added 2 commits July 5, 2026 20:58

fix: format usage date labels by range timezone

b715b4c

fix(gateway): keep usage ranges on calendar days

4a5b3fd

vincentkoc force-pushed the codex/usage-specific-date-labels branch from 8971ea2 to 4a5b3fd Compare July 6, 2026 03:58

vincentkoc merged commit 37f96bd into openclaw:main Jul 6, 2026
123 of 130 checks passed

vincentkoc mentioned this pull request Jul 6, 2026

fix: honor open-ended usage date ranges #100564

Closed

This was referenced Jul 9, 2026

[Bug]: Usage history assigns events to wrong local day across DST transitions #103092

Closed

fix: keep usage day buckets correct across DST #103097

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(gateway): format usage dates in range timezone#100567

fix(gateway): format usage dates in range timezone#100567
vincentkoc merged 2 commits into
openclaw:mainfrom
NianJiuZst:codex/usage-specific-date-labels

NianJiuZst commented Jul 6, 2026

Uh oh!

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

vincentkoc commented Jul 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

vincentkoc commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

NianJiuZst commented Jul 6, 2026

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

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

Uh oh!

Uh oh!

vincentkoc commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

vincentkoc commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading

vincentkoc commented Jul 6, 2026 •

edited

Loading