Export TokenUsage, page_iterator, and AsyncRemoteWorkspace as public SDK APIs

[enyst]

Summary

Promote a few symbols that OpenHands already relies on into package public APIs:

• TokenUsage
• page_iterator
• AsyncRemoteWorkspace

This updates package exports so consumers can import these from curated __init__.py APIs instead of deep implementation modules.

Docs PR: OpenHands/docs#394

Checklist

• If the PR is changing/adding functionality, are there tests to reflect this?
• If there is an example, have you run the example to make sure that it works?
• If there are instructions on how to run the code, have you followed the instructions and made sure that it works?
• If the feature is significant enough to require documentation, is there a PR open on the OpenHands/docs repository with the same branch name?
• Is the github CI passing?

Fixes #2444

---

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.13-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:1209c18-python

Run

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

All tags pushed for this build

ghcr.io/openhands/agent-server:1209c18-golang-amd64
ghcr.io/openhands/agent-server:1209c18-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:1209c18-golang-arm64
ghcr.io/openhands/agent-server:1209c18-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:1209c18-java-amd64
ghcr.io/openhands/agent-server:1209c18-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:1209c18-java-arm64
ghcr.io/openhands/agent-server:1209c18-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:1209c18-python-amd64
ghcr.io/openhands/agent-server:1209c18-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-amd64
ghcr.io/openhands/agent-server:1209c18-python-arm64
ghcr.io/openhands/agent-server:1209c18-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-arm64
ghcr.io/openhands/agent-server:1209c18-golang
ghcr.io/openhands/agent-server:1209c18-java
ghcr.io/openhands/agent-server:1209c18-python

About Multi-Architecture Support

• Each variant tag (e.g., 1209c18-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., 1209c18-python-amd64) are also available if needed

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ❌ FAILED

Result: ❌ FAILED

⚠️ Breaking REST API changes or policy violations detected.

Log excerpt (first 1000 characters)

Uninstalled 1 package in 1ms
Installed 1 package in 2ms
::error title=openhands-agent-server REST API::Breaking REST API change detected without MINOR version bump (1.14.0 -> 1.14.0).

Breaking REST API changes detected compared to baseline release:
- added '#/components/schemas/ACPAgent-Output, #/components/schemas/Agent-Output' to the '/items/anyOf[subschema #1: ConversationInfo]/agent' response property 'oneOf' list for the response status '200'
- the '/items/anyOf[subschema #1: ConversationInfo]/agent' response's property type/format changed from 'object'/'' to ''/'' for status '200'
- removed the required property '/items/anyOf[subschema #1: ConversationInfo]/agent/kind' from the response with the '200' status
- removed the required property '/items/anyOf[subschema #1: ConversationInfo]/agent/llm' from the response with the '200' status
- the 'agent' request property type/format changed from 'object'/'' to ''/''
- added '#/components/schemas/ACPAgent-Output, #/components/schemas/A

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-sdk/openhands/sdk
__init__.py	24	2	91%	79–80
TOTAL	20094	5840	70%

[all-hands-bot]

🟢 Good taste

Simple, pragmatic fix. Promoting already-used symbols to public API eliminates deep imports without adding complexity or breaking anything. This is exactly what API surface management should look like.

VERDICT: ✅ Worth merging - Clean additive change solving a real problem.

KEY INSIGHT: Best kind of API change - makes existing usage cleaner without touching any logic.