View Source Jido.Agent.Runtime.State (Jido v1.0.0-rc.4)

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

status()

Represents the possible states of a worker.

t()

Functions

default_topic(agent_id)

Generates the default PubSub topic name for an agent.

transition(state, desired)

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

default_topic(agent_id)

@spec default_topic(String.t()) :: String.t()

Generates the default PubSub topic name for an agent.

Parameters

agent_id - Unique identifier of the agent

Returns

String in the format "jido.agent.<agent_id>"

Examples

iex> Runtime.State.default_topic("robot_1")
"jido.agent.robot_1"

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