RunState is a serializable snapshot of an in-progress agent run stored in src/agents/run_state.py that enables pause (HITL), approval flows, resume, and replay across run boundaries. RunState enforces strict schema versioning: only versions in SUPPORTED_SCHEMA_VERSIONS load; every shipped version must have a summary in SCHEMA_VERSION_SUMMARIES, and minimum versions guard specific features like programmatic tool calling (1.13) and hosted MCP approvals (1.14). HITL (Human-in-the-Loop) is a pattern that pauses agent execution at a defined checkpoint so a human can review or approve state before the run continues.
src/agents/run_state.py implements RunState, a serializable snapshot of an in-progress agent run that supports interruption (HITL pause), approval flows, resume, and cross-run replay.[1]
SUPPORTED_SCHEMA_VERSIONS in run_state.py is a frozenset of all schema version strings that can be read back; attempting to load a snapshot with a version outside this set causes a fail-fast error.[1] Every schema version ever shipped in a release must have a non-empty entry in SCHEMA_VERSION_SUMMARIES; an assertion fires at import time if any version is missing a summary.[1] RunState schema policy mandates that unreleased intermediate schema versions may be renumbered or squashed before release when their snapshots are intentionally unsupported.[1] Schema version 1.13 (_PROGRAMMATIC_TOOL_CALLING_MIN_SCHEMA_VERSION) is the minimum version required to deserialize programmatic tool calling and nested handoff history ownership.[1] Schema version 1.14 (_HOSTED_MCP_APPROVALS_MIN_SCHEMA_VERSION) is the minimum version required to deserialize scoped hosted MCP approvals and restored requests by server label.[1]
_PendingSessionWrite is a TypedDict in run_state.py representing one canonical resumed-output append awaiting acknowledgement, containing fields session_id, items, before, and persisted_count.[1] RunStateValidationError is a type alias for UserError | ValueError; validation failures in RunState deserialization surface as one of these two exception types.[1]
Sources