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

Types

Represents the possible states of a worker.

t()

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

status()

@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

t()

@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

clear_queue(state)

@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()}}

dequeue(state)

@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}

enqueue(state, signal)

@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 state
  • signal - 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}

transition(state, desired)

@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 struct
  • desired - 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}}

validate_state(state)