feat(api): read a thread back with its activities, not just its messages

[ciaransweet]

A restored thread showed what was said and nothing about what the agent did — no receipts, no publications, no views, no citations. Those are the things this runtime exists to make visible, so a reload lost the half that matters.

GET /threads/{id} now returns them.

It reads them back rather than rebuilding them

The old docstring said rebuilding would mean "re-deriving every historical turn's receipts". It would not: receipts are stored. _residue writes structured_content, captured_state and injected_state onto each tool message's artifact, and the checkpointer keeps all three — confirmed through JsonPlusSerializer and against a deployed thread.

So each activity comes from data already in the thread:

Activity	From
state.consumed	receipts_of(artifact), rendered by step_input against that turn's state
state.published	_published(artifact)
mcp.view	restore_structured(artifact, state) plus the tool's ui:// URI
answer.citations	answer_citations(ai_message)

An activity is a message in AG-UI, so they travel in messages and sit beside the call they belong to with no correlation work — the same property the live stream relies on.

The payload builders are shared now

consumed_content, published_content, view_content and citations_content are used by both the stream and the readback, so a receipt cannot read one way live and another after a reload. That also removed the _artifact smuggling _view/_filled needed: the deferral stays in the loop, the content builder is pure.

Verified against a live turn on a real model — every restored activity is byte-identical to the one the stream sent:

restored roles: [user, assistant, tool, activity, assistant, tool, activity, activity, activity, assistant]

  state.published    identical to live
  state.consumed     identical to live
  state.published    identical to live
  mcp.view           identical to live

live-only activity types: ['tools.withheld']

tools.withheld is correctly live-only: it announces what this build cannot do, which is not part of the conversation.

What degrades, rather than guessing

• A turn whose checkpoints have been pruned has no state to describe its receipts against, so its view is not rebuilt — better than drawing one from whatever state happens to be current.
• A ui:// bundle comes from the deployment as it stands, so a tool removed since has no view rather than a dangling URI.
• State is per turn, not per call, so two tools writing the same key within one turn describe each other's value. The checkpoints could tell them apart; the turn index cannot. Documented on thread_messages.

Cost

A second read per thread — turns_of walks the checkpoint history, proportional to the conversation. That is the documented price of deriving turns from a structure that does not record them, and it is what makes the difference between restoring a conversation and restoring what the agent was seen to do.

Example client

Restored activities mean the cross-highlighting works on a reloaded thread with no special case — origins folds state.published out of the messages exactly as it does live. Each turn is bounded by the next one's start; unbounded, turn 1 would claim every later turn's publications.

Also

stream_turn's _tool_result is now public as tool_finished, since the readback builds the same thing from the same message. And RunRequest's docstring said the client's message id "is discarded rather than stored" — stale since #86, which propagates it. Fixed here.

350 tests, lint clean, example client builds.

Activities are opt-in, and a run's closing snapshot opts out

Caught by trying it in the browser: the restored activities were duplicating at the bottom of every turn.

A client applying a MESSAGES_SNAPSHOT keeps every local activity whether the snapshot names it or not — defaultApplyEvents exempts the role. So a snapshot can never correct a client's activities, only append a second copy of ones the stream just sent. Readback ids are per-position (act_4_1) and the stream's are per-run (act_{runId}_4), so nothing matches and every one duplicates.

Omitting turns and tools was not enough to stop it: state.consumed and state.published need neither, so they came out anyway — and rendered against no state at all. There is now an explicit activities flag, off by default, and GET /threads/{id} is the one caller that asks for them.

Verified on a live turn: the closing snapshot carries six messages and no activities, while a reload of the same thread returns all four.