University of Michigan - Ann Arbor

In StateM, a runbook is a human-readable and machine-operable YAML specification that defines the control profile for an agent workflow. It details phase-level states, permitted transitions, state-local instructions, lifecycle hooks (`in_hook` and `out_hook`), verification checks (`before_transfer`), and error-recovery rules. The runbook is hosted directly in the shared workspace, enabling the executing agent to inspect its current state, execute transitions, and record dynamic checks via standard CLI operations, while allowing human supervisors to inspect, audit, edit, and version the exact same control artifact.

StateM Runbook

Which set of lifecycle hooks and verification checks is detailed in a StateM runbook YAML specification?

In StateM, human supervisors must use a separate, proprietary GUI tool to audit runbooks because the control artifact cannot be inspected or edited directly by humans.

Formally, a StateM runbook is defined as a five-tuple:

$$\mathcal{B} = (\mathcal{S}, s_0, \mathcal{S}_T, \mathcal{E}, \Phi)$$

where:
- $\mathcal{S}$ is the finite set of phase-level states.
- $s_0 \in \mathcal{S}$ is the designated initial state.
- $\mathcal{S}_T \subseteq \mathcal{S}$ is the subset of terminal states denoting successful completion.
- $\mathcal{E} \subseteq \mathcal{S} \times \mathcal{S}$ is the set of permitted directed transitions between states.
- $\Phi(s)$ is the state specification mapping each state $s \in \mathcal{S}$ to its phase-local configuration, including the phase prompt, entry and exit hooks, transfer checks, and references to state-local artifacts.

Formal Runbook Specification in StateM

In a StateM runbook, each phase-level state node is organized into four distinct structural components:

1. `in_hook`: Executes setup operations upon entering the state, initializing state files and loading durable context or progress records.
2. `State body`: The primary open-ended execution space in which the agent retains discretion to reason, invoke tools, and edit files to solve phase-local tasks.
3. `out_hook`: Persists durable task progress, updates status receipts, and prepares workspace artifacts before state departure.
4. `before_transfer`: Evaluates blocking pre-commit checks; failing any check prevents transition commit and keeps the agent within the node for error repair.

Phase-Local Node Architecture in StateM

Through what operational interface does an executing StateM agent inspect its current state, execute transitions, and record dynamic checks in the shared workspace?

Learn Before

Related