Checkpoint preparation and restore for Composer strategy state.
Before persisting strategy state, closures must be stripped since they
cannot be serialized. On restore, they are reattached from the agent
module's DSL configuration (strategy_opts).
Status Transitions
hibernated → resuming → resumedStrategy Checkpoint Protocol
Strategies may implement the following optional callbacks to integrate with
the checkpoint lifecycle. These are discovered at runtime via
function_exported?/3 — no behaviour is required.
replay_directives_from_state/1— Given deserialized strategy state, returns a list of directives needed to resume in-flight operations (e.g. re-issue an LLM call or re-dispatch pending tool calls).prepare_for_checkpoint/1— Agent-level hook that prepares the agent for hibernation. Called before persisting.strip_for_checkpoint/1— Strategy-specific closure stripping callback. Receives the strategy state map and returns a cleaned version. Called byprepare_for_checkpoint/1when available; otherwise falls back to blanket top-level function stripping.reattach_runtime_config/2— Restores runtime closures and transient state fromstrategy_optsafter deserialization.
Schema Version
Current checkpoint schema is :composer_v1.
Summary
Functions
Wraps suspend directives with a CheckpointAndStop directive when the suspension
timeout exceeds the configured hibernate_after threshold.
Migrates checkpoint state from an older schema version to the current one.
Returns SpawnAgent directives for paused children that need re-spawning.
Prepares strategy state for checkpoint by stripping non-serializable values (closures/functions) and setting checkpoint status.
Reattaches runtime configuration (closures) from strategy_opts.
Returns directives needed to replay in-flight operations after checkpoint restore.
Returns the current checkpoint schema version.
Validates a checkpoint status transition.
Returns the list of valid checkpoint statuses.
Returns the list of valid transitions from a given status.
Functions
Wraps suspend directives with a CheckpointAndStop directive when the suspension
timeout exceeds the configured hibernate_after threshold.
Returns the original directives list, potentially with CheckpointAndStop appended.
@spec migrate(map(), non_neg_integer()) :: map()
Migrates checkpoint state from an older schema version to the current one.
@spec pending_child_respawns(map()) :: [Jido.Agent.Directive.SpawnAgent.t()]
Returns SpawnAgent directives for paused children that need re-spawning.
Prepares strategy state for checkpoint by stripping non-serializable values (closures/functions) and setting checkpoint status.
Delegates to the strategy module's prepare_for_checkpoint/1 callback
if available, otherwise falls back to blanket top-level function stripping.
Reattaches runtime configuration (closures) from strategy_opts.
Only restores values that are currently nil in the checkpoint state.
Returns directives needed to replay in-flight operations after checkpoint restore.
Replays workflow child spawning phases directly, and delegates strategy-specific
replay to the strategy module's replay_directives_from_state/1 callback.
@spec schema_version() :: atom()
Returns the current checkpoint schema version.
@spec transition_status(atom(), atom()) :: :ok | {:error, {:invalid_transition, atom(), atom(), [atom()]}}
Validates a checkpoint status transition.
@spec valid_statuses() :: [atom()]
Returns the list of valid checkpoint statuses.
Returns the list of valid transitions from a given status.