Add env-configurable token view to visualizer (per-context vs accumulated)

[enyst]

Summary

• Introduce a small token display utility API (TokenDisplay, TokenDisplayMode, compute_token_display, get_default_mode_from_env)
• Refactor DefaultConversationVisualizer to use this utility
• Default behavior shows per-context (latest request) token counts while keeping cumulative cost labeled as (total)
• Add env toggles:
  • OH_TOKENS_VIEW_MODE: per_context (default) or accumulated (aliases supported: per_request/latest/current and total/sum)
  • OH_TOKENS_VIEW_DELTA: optional since-last delta for input tokens in per_context mode
• Add focused tests covering token_display and visualizer subtitle formatting/toggles

Rationale
This follows reviewer feedback to keep both views available and make the SDK configurable, while simplifying the visualizer by extracting token computation into a reusable utility.

Testing

• make build
• uv run pytest tests/sdk/conversation/test_token_display.py -q
• uv run pytest tests/sdk/conversation/test_visualizer.py -q
• uv run pre-commit run --files openhands-sdk/openhands/sdk/conversation/token_display.py openhands-sdk/openhands/sdk/conversation/visualizer/default.py tests/sdk/conversation/test_token_display.py

Notes

• Backward compatible: default display remains concise and adds configurability via env
• Minimal surface change; no breaking API changes

Co-authored-by: openhands openhands@all-hands.dev

@enyst can click here to continue refining the PR

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.12-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:5aba694-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-5aba694-python \
  ghcr.io/openhands/agent-server:5aba694-python

All tags pushed for this build

ghcr.io/openhands/agent-server:5aba694-golang-amd64
ghcr.io/openhands/agent-server:5aba694-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:5aba694-golang-arm64
ghcr.io/openhands/agent-server:5aba694-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:5aba694-java-amd64
ghcr.io/openhands/agent-server:5aba694-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:5aba694-java-arm64
ghcr.io/openhands/agent-server:5aba694-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:5aba694-python-amd64
ghcr.io/openhands/agent-server:5aba694-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-amd64
ghcr.io/openhands/agent-server:5aba694-python-arm64
ghcr.io/openhands/agent-server:5aba694-nikolaik_s_python-nodejs_tag_python3.12-nodejs22-arm64
ghcr.io/openhands/agent-server:5aba694-golang
ghcr.io/openhands/agent-server:5aba694-java
ghcr.io/openhands/agent-server:5aba694-python

About Multi-Architecture Support

• Each variant tag (e.g., 5aba694-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 5aba694-python-amd64) are also available if needed

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk/conversation
token_display.py	69	22	68%	19–23, 25, 46, 49–50, 71, 80–89, 100–101
openhands-sdk/openhands/sdk/conversation/visualizer
default.py	146	24	83%	84–85, 87–92, 94, 123, 143, 154, 165, 265, 284, 289, 302, 343, 356, 358, 360, 363, 375, 381
TOTAL	12992	5826	55%

[blacksmith-sh]

[Automatic Post]: I have assigned @xingyaoww as a reviewer based on git blame information. Thanks in advance for the help!

[blacksmith-sh]

[Automatic Post]: This PR seems to be currently waiting for review. @xingyaoww, could you please take a look when you have a chance?

[all-hands-bot]

[Automatic Post]: This PR seems to be currently waiting for review. @xingyaoww, could you please take a look when you have a chance?