View Source Jido.Agent.Runtime.State (Jido v1.0.0-rc.5)
Defines the state management structure and transition logic for Agent Runtimes.
The Runtime.State module implements a finite state machine (FSM) that governs the lifecycle of agent workers in the Jido system. It ensures type safety and enforces valid state transitions while providing telemetry and logging for observability.
State Machine
The worker can be in one of the following states:
:initializing
- Initial state when worker is starting up:idle
- Runtime is inactive and ready to accept new commands:planning
- Runtime is planning but not yet executing actions:running
- Runtime is actively executing commands:paused
- Runtime execution is temporarily suspended
State Transitions
Valid state transitions are:
initializing -> idle (initialization_complete)
idle -> planning (plan_initiated)
idle -> running (direct_execution)
planning -> running (plan_completed)
planning -> idle (plan_cancelled)
running -> paused (execution_paused)
running -> idle (execution_completed)
paused -> running (execution_resumed)
paused -> idle (execution_cancelled)
Fields
:agent
- The Agent struct being managed by this worker (required):pubsub
- PubSub module for event broadcasting (required):topic
- PubSub topic for worker events (required):status
- Current state of the worker (default: :idle):pending
- Queue of pending commands awaiting execution:max_queue_size
- Maximum number of commands that can be queued (default: 10000):child_supervisor
- Dynamic supervisor PID for managing child processes
Example
iex> state = %Runtime.State{
...> agent: my_agent,
...> pubsub: MyApp.PubSub,
...> topic: "agent.worker.1",
...> status: :idle
...> }
iex> {:ok, new_state} = Runtime.State.transition(state, :running)
iex> new_state.status
:running
Summary
Functions
Empties the pending queue in the runtime state.
Dequeues a signal from the state's pending queue.
Enqueues a signal into the state's pending queue.
Attempts to transition the worker to a new state.
Types
@type status() :: :initializing | :idle | :planning | :running | :paused
Represents the possible states of a worker.
:initializing
- Runtime is starting up:idle
- Runtime is inactive:planning
- Runtime is planning actions:running
- Runtime is executing actions:paused
- Runtime execution is suspended
@type t() :: %Jido.Agent.Runtime.State{ agent: Jido.Agent.t(), child_supervisor: pid() | nil, max_queue_size: non_neg_integer(), pending: :queue.queue(), pubsub: module(), status: status(), topic: String.t() }
Functions
@spec clear_queue(%Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: term(), topic: term() }) :: {:ok, %Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: term(), topic: term() }}
Empties the pending queue in the runtime state.
Returns a new state with an empty queue.
Parameters
state
- Current runtime state
Returns
{:ok, new_state}
- Queue was successfully emptied
Examples
iex> state = %Runtime.State{pending: queue_with_items}
iex> Runtime.State.clear_queue(state)
{:ok, %Runtime.State{pending: :queue.new()}}
@spec dequeue(%Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: term(), topic: term() }) :: {:ok, term(), %Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: term(), topic: term() }} | {:error, :empty_queue}
Dequeues a signal from the state's pending queue.
Returns the next signal and updated state with the signal removed from the queue. Returns error if queue is empty.
Parameters
state
- Current runtime state
Returns
{:ok, signal, new_state}
- Signal was successfully dequeued{:error, :empty_queue}
- Queue is empty
Examples
iex> state = %Runtime.State{pending: queue_with_items}
iex> Runtime.State.dequeue(state)
{:ok, %Signal{type: "test"}, %Runtime.State{pending: updated_queue}}
iex> state = %Runtime.State{pending: :queue.new()}
iex> Runtime.State.dequeue(state)
{:error, :empty_queue}
@spec enqueue( %Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: term(), topic: term() }, Jido.Signal.t() ) :: {:ok, %Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: term(), topic: term() }} | {:error, :queue_overflow}
Enqueues a signal into the state's pending queue.
Validates that the queue size is within the configured maximum before adding. Emits a queue_overflow event if the queue is full.
Parameters
state
- Current runtime statesignal
- Signal to enqueue
Returns
{:ok, new_state}
- Signal was successfully enqueued{:error, :queue_overflow}
- Queue is at max capacity
Examples
iex> state = %Runtime.State{pending: :queue.new(), max_queue_size: 2}
iex> Runtime.State.enqueue_signal(state, %Signal{type: "test"})
{:ok, %Runtime.State{pending: updated_queue}}
iex> state = %Runtime.State{pending: full_queue, max_queue_size: 1}
iex> Runtime.State.enqueue_signal(state, %Signal{type: "test"})
{:error, :queue_overflow}
@spec transition( %Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: status(), topic: term() }, status() ) :: {:ok, %Jido.Agent.Runtime.State{ agent: term(), child_supervisor: term(), max_queue_size: term(), pending: term(), pubsub: term(), status: term(), topic: term() }} | {:error, {:invalid_transition, status(), status()}}
Attempts to transition the worker to a new state.
This function enforces the state machine rules defined in @transitions. It logs state transitions for debugging and monitoring purposes.
Parameters
state
- Current Runtime.State structdesired
- Desired target state
Returns
{:ok, new_state}
- Transition was successful{:error, {:invalid_transition, current, desired}}
- Invalid state transition
Examples
iex> state = %Runtime.State{status: :idle}
iex> Runtime.State.transition(state, :running)
{:ok, %Runtime.State{status: :running}}
iex> state = %Runtime.State{status: :idle}
iex> Runtime.State.transition(state, :paused)
{:error, {:invalid_transition, :idle, :paused}}