feat(api)!: say history is the server's, and share the state object

[ciaransweet]

Closes the two AG-UI follow-ups that get more expensive with every client integrating against the current shape. Both are things a consumer could previously only learn from a README paragraph.

MESSAGES_SNAPSHOT closing every run. A client posts its whole messages array and this server reads only the trailing user message — so a client that edited its own copy was wrong, with nothing on the wire saying so. Each run now ends with the thread as the server holds it.

STATE_SNAPSHOT under toolState. AG-UI's state object is the client's as much as ours: the protocol has it hold what a client and agent share, and STATE_DELTA patches it by JSON Pointer. Writing our metadata map at the root left a client nowhere for its own keys, and would overwrite any it sent. Under a namespace both fit, and a future STATE_DELTA has a stable path to address.

The read routes are unchanged — their bodies are ours alone, so state_metadata is still served unwrapped there.

The snapshot closes the run rather than opening it

Worth stating because the obvious placement is wrong, and the first version of this PR had it wrong.

defaultApplyEvents applies a snapshot by dropping every local message the snapshot does not name. A client renders its question the moment it is typed, so a snapshot sent after RUN_STARTED — before the turn is checkpointed — takes that question off the screen and leaves the answer under nothing. At the end of the run, everything the turn produced is in the thread.

Ids line up, which is what makes it reconcile rather than rebuild

Placement alone was not enough: client ids were minted locally and thread ids by the checkpointer, so no id matched and the whole list was dropped and re-appended — stranding activities at the top of the turn. Three changes fix that:

• the question keeps the id its client gave it (stream_turn(message_id=...))
• the answer is labelled with the provider's own id, taken off the streamed chunk — verified to be exactly the id the checkpoint stores
• ToolStarted and ToolFinished carry the assistant and tool message ids from the thread, so TOOL_CALL_START gets a real parentMessageId and TOOL_CALL_RESULT a real messageId

One hazard this exposed and now guards: an id the thread already holds is ignored, because LangGraph's message reducer matches on id and reusing one replaces that message rather than adding this one. A client numbering messages per session, or retrying with the same id, would otherwise silently rewrite its own history. Caught by an existing test that posts id: "u" on two turns.

Verified against a live turn on a real model — every id in the closing snapshot was already one the client held:

user       client-q-1                                    HELD
assistant  lc_run--01a00f33-dc00-7700-801e-537c01ad396d  HELD
tool       3d05ac89-fc43-4e43-9f90-5be0c6bcf31f          HELD
assistant  lc_run--01a00f33-ddbf-7af0-8740-525c0c9efa71  HELD
tool       9fd1bd2c-25c7-41b3-910e-ec29cff147a3          HELD
assistant  lc_run--01a00f33-e04a-7c13-a02a-cf96a052d65a  HELD

A failed turn snapshots nothing: the thread is mid-write, and telling a client to adopt that would hand it a state the server may itself drop.

Breaking

Read STATE_SNAPSHOT metadata from snapshot.toolState rather than from snapshot. The example client is updated here and builds.

Under this repo's release-please settings this lands as 0.6.0 — bump-minor-pre-major makes a breaking change a minor while pre-1.0. Consumers pin <0.6.0, so nobody picks it up until they widen that deliberately, which is the point.

Tests

348 total, lint clean, example client builds. Two existing tests read the snapshot at the root and were updated — they are the regression check that this is a wire change and not an accident.