feat(state): read a state key as it stood at an earlier turn

[ciaransweet]

Closes #101.

A key holds one value, so a second call to the same tool replaces what the
first published. Ask the model how a result compares with the one it found
earlier and it reads the key, gets a well-formed value, and compares that value
with itself. Nothing fails, and the answer is confidently wrong.

The checkpointer already holds every past tool_state. This gives the model a
way to ask for one.

What changed

inspect_state(key, turn=N) reads the key as that turn ended, counting the
user's questions from 1. It answers three ways, and the third is the point:
the value; no_such_turn with how many the thread has had; or
turn_no_longer_retained, meaning the value existed and was pruned.

make_inspect_state(keys, history=None) takes an optional ThreadHistory
— one async snapshots(thread_id) returning {turn: state} plus a total.
with_session_state passes CheckpointHistory(checkpointer) whenever it is
given one, so hosts using it get this for free. Without a history the tool
behaves as before and turn= says the deployment keeps none.

StateEntry gains turn and turns_written, both stamped during capture
and merge. turns_written counts turns, not writes: two calls in one turn
add one, because a turn-scoped read resolves to what the turn ended with.

Three surfaces tell the model an earlier value exists, since a read of a
rewritten key is otherwise indistinguishable from a read of one written once:

• the [state updated: …] breadcrumb now names the turn this write displaced.
  This one matters most — passing @state:<key> resolves to the present and
  triggers no read at all, so the breadcrumb is the only warning that lands;
• a read of a key more than one turn wrote ends with a line saying so;
• the refusal listing marks it written in N turns.

The wire carries it too. state_metadata adds turnsWritten (omitted when
1, so its presence is the signal) and turn. The example panel renders
written in 2 turns on the row.

Turn derivation moved from mcp_agent_api.history to mcp_agent.history,
re-exported under the old names, so the tool and the HTTP routes share one
definition. It no longer assumes the saver walks newest-first — the base
contract does not promise an order, and the old rule would serve each turn's
starting state on an ascending walk.

Compatibility

• inspect_state is now async. A host invoking its graph synchronously has
  to switch. Nothing here or in dss does.
• A read appends its note after the JSON, so that output is no longer parseable
  as JSON. Same shape as the breadcrumb already on the result.

Testing it

examples/agui-events, four prompts in one thread:

sketch a rough boundary around the Severn catchment and call it Severn
now sketch one around the Thames and call it Thames
confirm from state what area each of the two sketches came out at
what did that key hold at turn 7?

Prompt 2's breadcrumb names turn 1, and the panel row gains written in 2 turns. Prompt 3 returns two reads, each labelled with its turn:

74352.9
[sketch-ops/sketch_area/area_km2 as it stood at the end of turn 1.]

Prompt 4 gets no_such_turn with turns_so_far, not an invented value.

Worth knowing: the model reaches for turn= when the answer needs it, not
reflexively. In this example the earlier value is still in the transcript as
tool-result text, so it often answers from that instead. The failure this
closes bites where the value is not recoverable from the transcript.

Verification

402 tests and lint green at each of the five commits. Exercised against a real
PostgreSQL 17 AsyncPostgresSaver: saver and graph walks derive identical
turns, each turn ends holding its own value, and a live inspect_state(turn=1)
returns turn 1's. That walk contains checkpoints with tied message counts, so
the id tiebreak runs in practice.

🤖 Generated with Claude Code

https://claude.ai/code/session_016K5NB5A3a8LWuxMAQQyUNJ