Schema and middleware for per-checkpoint state restored when resuming.
ResumeState declares several checkpointed, schema-private channels. They fall
into two groups with different write paths:
Written from inside the graph on successful model turns:
_context_tokens — total context tokens from the latest
AIMessage.usage_metadata, written by ResumeStateMiddleware.after_model.
Powers /tokens and the status bar._model_spec / _model_params — the model and invocation params effectively
in use for the turn, written by ConfigurableModelMiddleware after a
successful model call. Lets dcode -r restore the model the resumed thread
was actually using instead of falling back to the user's global default._last_model_request_at / _last_cache_model_spec — UTC request-start time
and requested model identity captured by ConfigurableModelMiddleware and
committed only after that call succeeds. Lets the TUI detect when the
provider's reusable prompt prefix may be cold.Written through the main graph or by the TUI client via aupdate_state (see
DeepAgentsApp._persist_goal_rubric_state) — these are user/agent-owned. Their
write sites are called out below:
_goal_objective / _goal_status / _goal_rubric / _goal_status_note —
the accepted goal and its lifecycle status. _goal_objective/_goal_rubric
are client-only, but _goal_status/_goal_status_note are also written
from inside the graph by the agent's update_goal tool._pending_goal_completion_note — optional agent-provided completion evidence
awaiting the post-turn rubric result._sticky_rubric — the TUI-owned persistent rubric. This is separate from
the public rubric graph input so one-shot rubric turns can be checkpointed
without being restored as sticky state._rubric_model_spec — the thread-scoped rubric-grader model selection,
written by the TUI client. It is a tri-state: absent means the thread has
recorded no selection, so the grader keeps its construction-time default;
INHERIT_RUBRIC_MODEL means the grader follows the active main model; any
other value is a dedicated model spec._pending_goal_objective / _pending_goal_rubric / _pending_goal_kind /
_pending_goal_request_id — a proposed goal or amendment and its originating
request, written by GoalCriteriaMiddleware inside the main graph, then
cleared by the TUI when the user accepts or rejects it.All of these are facts the CLI reads back from state_values on thread resume
so it can rehydrate the session without replaying or re-tokenizing history.
The model-turn channels are persisted from inside the graph (rather than via a
separate client-side aupdate_state call) so the write rides the same checkpoint
as the model response and avoids creating a standalone UpdateState run in
LangSmith. Because they are versioned channel state, resuming a specific
checkpoint yields the values as of that checkpoint — not a thread-level
aggregate. Accepted goal/rubric state is client-written because the user sets it
outside any model turn; pending criteria proposals and agent-driven status
updates are graph-written. Both paths work identically against local and remote
(HTTP) graphs.