Nanobot
Nanobot moves provider usage into a bounded trajectory store
Nanobot proposes a content-free SQLite trajectory record for every retry-managed provider attempt, backed by a typed usage contract and TUI telemetry that shows one measured request instead of mixing session estimates with cumulative turn totals.
HKUDS/nanobot PR #5481 is the inspected primary source: “feat(trajectory): add unified provider usage backend.” The related records below were inspected as supporting context rather than independent confirmation.
The facts
- HKUDS/nanobot PR #5481 was created 2026-08-21T18:40:26Z and was open at inspection; its title is “feat(trajectory): add unified provider usage backend.” - HKUDS/nanobot PR #5480 was created 2026-08-21T18:40:22Z and was open at inspection; its title is “refactor(providers): define typed LLM usage contract.” - HKUDS/nanobot PR #5469 was created 2026-08-21T09:58:59Z and was open at inspection; its title is “fix(tui): show measured request context.” - The repository reported 47265 stars, 718 open issues, default branch main, and last push 2026-08-21T18:40:02Z. - The latest tagged-release baseline checked was v0.3.0 published 2026-07-25T08:08:47Z.
What changed
HKUDS/nanobot PR #5481 reports: Part of native stack #5482, stacked on #5480. Review this after the provider usage-contract refactor; this PR now shows only the trajectory delta. Summary record one content-free trajectory row for every retry-managed provider attempt, including fallback leaves, errors, and cancellations persist normalized token/cache/timing metadata in a bounded SQLite WAL database and replace the legacy WebUI token JSON store expose daily/source/provider-model aggregates through the existing settings usage payload classify API, automation, Dream, system, and user calls without persisting session identifiers Design notes The schema deliberately excludes prompts, responses, reasoning, tool payloads, provider error text, and session keys. Free-form finish/error values are normalized before persistence; only coarse error kinds and valid HTTP status codes remain. Storage is capped at roughly 100k calls / 400 days. Cold aggregation uses a separate read-only WAL connection; cached refreshes avoid rescans and do not block provider writes. This intentionally starts a fresh trajectory.sqlite3; there is no migration from the legacy token-usage JSON file. Performance Windows local benchmark at 100k rows: writes: ~77 us/call storage: ~179 bytes/call including SQLite indexes/WAL cold Asia/Shanghai aggregate: ~0.62 s cached aggregate: ~0.07 ms concurrent record during cold aggregate: ~0.15 ms Verification ruff check nanobot... basedpyright (0 errors) provider tests: 977 passed WebUI Python tests: 280 passed, 2 skipped runner/loop tests: 410 passed Dream/gateway tests: 76 passed final focused trajectory/provider/subagent/settings tests:
HKUDS/nanobot PR #5480 reports: Summary replace dynamic provider usage dictionaries with an immutable typed LLMUsage contract and explicit provider identity normalize token and cache semantics at the OpenAI Chat, OpenAI Responses, Anthropic, and Bedrock wire boundaries preserve provider-reported totals, cache-write metrics, and the distinction between unreported cache metrics and explicit zero keep reported and estimated usage partitioned through runner aggregation, timing, SDK/API, session, and WebSocket boundaries update WebUI v2 aggregation with cache-observation denominators and compact, byte-bounded retention Contract input_tokens is logical input and includes cache reads and writes total_tokens is at least input_tokens plus output_tokens and preserves larger provider totals reported_tokens plus estimated_tokens equals total_tokens non-error zero usage is estimated in the runner; error responses remain unestimated Test plan uv run --no-sync pytest tests/providers -q (971 passed) uv run --no-sync pytest tests/agent/test_runner_core.py tests/agent/test_runner_hooks.py tests/agent/test_runner_errors.py tests/agent/test_runner_tool_execution.py -q (69 passed) uv run --no-sync pytest tests/webui -q (291 passed, 2 skipped) uv run --no-sync ruff check nanobot tests uv run --no-sync basedpyright bun run test (1084 passed) bun run build git diff origin/main...HEAD --check
HKUDS/nanobot PR #5469 reports: Summary keep cumulative per-turn token usage for backend accounting, but retain the latest provider-reported request separately for UI telemetry show only that measured request in the idle TUI footer: prompt context/window, matching cache ratio, output tokens, and generation rate remove the persistent estimated session-context label from the title so context appears only once hide context telemetry when a provider does not report real usage instead of presenting an estimate as measured data Before, a tool-heavy turn could mix two incompatible scopes: The title was a session-history estimate, while 1.4M was input accumulated across every model call in the turn. After: All footer values now describe the same latest provider-measured request. The explicit /context panel remains available for inspecting estimated replay/archive state. Follow-up to #5468. Testing cd tui && bun test (110 passed) cd tui && bun run check pytest tests/agent/test_runner_core.py -q (30 passed) ruff check nanobot/agent/runner.py tests/agent/test_runner_core.py git diff --check
Why it matters
Usage data becomes operational evidence only when provider semantics, retry attempts and UI scopes agree. Mixing estimated session context with cumulative input can look precise while describing no real request. The operator test is whether the system remains bounded and its receipts still describe the action after failure, retry or restart.
Current
The primary record was open when captured on 2026-08-22. The tagged-release baseline was v0.3.0 published 2026-07-25T08:08:47Z. Repository metadata, full source bodies, current pull requests and issues, releases, Google News, Hacker News, Lobsters, Metamesh and the rendered ClawCharts row were inspected. ClawCharts selected the subject; it did not prove the claim.
Evidence
The primary URL is https://github.com/HKUDS/nanobot/pull/5481. Supporting records are https://github.com/HKUDS/nanobot/pull/5480 and https://github.com/HKUDS/nanobot/pull/5469. Source bodies, timestamps and states are preserved in the daily evidence bundle. Test counts and reproductions remain attributed to their authors unless identified as independently rerun.
Source boundary
Open work is described as open, closed work as closed, and operator reports as reports. A pull request is evidence of proposed or reviewed direction, not proof of a shipped release. Search residue, package mirrors and historically published source spines were excluded.
Operator take
Preserve reported versus estimated usage, record retries without prompts or responses, cap retention, and label UI figures by the request scope they actually measure. Preserve a before-state receipt, make the smallest reversible change, and verify the original failure independently.
Caveat
Public project records are mutable. Status, scope and evidence can change after publication. This brief records the inspected state and does not authorize changes to a reader’s deployment.
Source inspected; source state, environment and release boundary remain explicit.