feat: persist conversation read state

[justavibedev]

HUMAN:

---

AGENT:

Why

Agent Canvas cannot distinguish a completed response that has not been read from one the user has already seen. The server also currently advances updated_at for title-only metadata changes, so that timestamp cannot safely represent agent activity.

This is the canonical Agent Server and TypeScript-client portion of OpenHands/OpenHands#17140. The Canvas UI must consume a released client version in a follow-up PR.

Summary

• Persist last_read_at and expose a derived unread value only for terminal runs with newer activity.
• Extend the metadata update contract and TypeScript client so callers can mark a conversation read or unread.
• Keep manual/automatic title updates and tag edits from changing the agent-activity timestamp.

Issue Number

Supports OpenHands/OpenHands#17140.

How to Test

All dependency setup happened in disposable containers without host secrets. Networking was disconnected before the test commands ran.

• uv run pytest -q tests/agent_server/test_conversation_info_model.py tests/agent_server/test_conversation_service.py tests/agent_server/test_conversation_router.py — 225 passed.
• uv run pytest -q tests/agent_server/test_openapi_contract.py tests/agent_server/test_openapi_discriminator.py — 12 passed.
• uv run ruff check ... and uv run ruff format --check ... — passed for all changed Python files.
• uv run pyright openhands-agent-server/openhands/agent_server/models.py openhands-agent-server/openhands/agent_server/conversation_service.py — 0 errors.
• npm test -- --runInBand src/__tests__/api-clients.test.ts — 86 passed.
• npm run lint, npm run build, and npm run format:check — passed (lint reported eight pre-existing warnings and no errors).

The live Canvas demonstration belongs in the dependent UI PR after this client contract is released; this PR remains draft until then.

Video/Screenshots

Not applicable to this backend/client contract PR. The dependent Canvas PR will include the issue-required visual evidence.

Design Doc

N/A.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

This is additive at the REST layer. Existing conversations load with last_read_at = null. Read state is reported only after a run reaches a terminal status, so in-flight output does not produce an unread marker.