Jido.AgentServer.State (Jido v2.2.0)

Internal state for AgentServer GenServer.

Internal Module

This module is internal to the AgentServer implementation. Its API may change without notice. Use Jido.AgentServer.state/1 to retrieve state.

This struct holds all runtime state for an agent instance including the agent itself, directive queue, hierarchy tracking, and configuration.

Summary

Types

status()

t()

Functions

add_child(state, tag, child)

Adds a child to the children map.

attach_parent(state, parent)

Attaches a parent reference to the runtime and agent state.

dequeue(state)

Dequeues the next directive for processing.

enqueue(state, signal, directive)

Enqueues a directive with its triggering signal for later execution.

enqueue_all(state, signal, list)

Enqueues multiple directives from a single signal.

from_options(opts, agent_module, agent)

Creates a new State from validated Options, agent module, and agent struct.

get_child(state, tag)

Gets a child by tag.

get_debug_events(state, opts \\ [])

Returns recent debug events, newest first.

increment_error_count(state)

Increments the error count.

orphan_parent(state)

Transitions the runtime into an orphaned state, preserving the former parent.

queue_empty?(state)

Checks if the queue is empty.

queue_length(state)

Returns the current queue length.

record_debug_event(state, type, data)

Records a debug event if debug mode is enabled.

remove_child(state, tag)

Removes a child by tag.

remove_child_by_pid(state, pid)

Removes a child by PID.

set_debug(state, enabled)

Enables or disables debug mode at runtime.

set_status(state, status)

Sets the status.

update_agent(state, agent)

Updates the agent in state.

Types

status()

@type status() :: :initializing | :idle | :processing | :stopping

t()

@type t() :: %Jido.AgentServer.State{
  agent: any(),
  agent_module: atom(),
  children: map(),
  completion_waiters: map(),
  cron_jobs: map(),
  cron_monitor_refs: map(),
  cron_monitors: map(),
  cron_restart_attempts: map(),
  cron_restart_timer_refs: map(),
  cron_restart_timers: map(),
  cron_runtime_specs: map(),
  cron_specs: map(),
  debug: boolean(),
  debug_events: [any()],
  debug_max_events: integer(),
  default_dispatch: nil | any(),
  deferred_async_signals: any(),
  error_count: integer(),
  error_policy: any(),
  id: binary(),
  jido: atom(),
  lifecycle: any(),
  max_queue_size: integer(),
  metrics: map(),
  on_parent_death: atom(),
  orphaned_from: nil | any(),
  parent: nil | any(),
  partition: nil | any(),
  processing: boolean(),
  queue: any(),
  registry: atom(),
  restored_from_storage: boolean(),
  signal_call_inflight: nil | any(),
  signal_call_queue: any(),
  signal_router: nil | any(),
  skip_schedules: boolean(),
  spawn_fun: nil | any(),
  status: atom()
}

Functions

add_child(state, tag, child)

@spec add_child(t(), term(), Jido.AgentServer.ChildInfo.t()) :: t()

Adds a child to the children map.

attach_parent(state, parent)

@spec attach_parent(t(), Jido.AgentServer.ParentRef.t()) :: t()

Attaches a parent reference to the runtime and agent state.

dequeue(state)

@spec dequeue(t()) :: {{:value, {Jido.Signal.t(), struct()}}, t()} | {:empty, t()}

Dequeues the next directive for processing.

enqueue(state, signal, directive)

@spec enqueue(t(), Jido.Signal.t(), struct()) ::
  {:ok, t()} | {:error, :queue_overflow}

Enqueues a directive with its triggering signal for later execution.

enqueue_all(state, signal, list)

@spec enqueue_all(t(), Jido.Signal.t(), [struct()]) ::
  {:ok, t()} | {:error, :queue_overflow}

Enqueues multiple directives from a single signal.

from_options(opts, agent_module, agent)

@spec from_options(Jido.AgentServer.Options.t(), module(), struct()) ::
  {:ok, t()} | {:error, term()}

Creates a new State from validated Options, agent module, and agent struct.

If a parent reference is provided, it's injected into the agent's state as agent.state.__parent__ so agents can use Directive.emit_to_parent/3.

get_child(state, tag)

@spec get_child(t(), term()) :: Jido.AgentServer.ChildInfo.t() | nil

Gets a child by tag.

get_debug_events(state, opts \\ [])

@spec get_debug_events(
  t(),
  keyword()
) :: [map()]

Returns recent debug events, newest first.

Options

:limit - Maximum number of events to return (default: all)

increment_error_count(state)

@spec increment_error_count(t()) :: t()

Increments the error count.

orphan_parent(state)

@spec orphan_parent(t()) :: t()

Transitions the runtime into an orphaned state, preserving the former parent.

queue_empty?(state)

@spec queue_empty?(t()) :: boolean()

Checks if the queue is empty.

queue_length(state)

@spec queue_length(t()) :: non_neg_integer()

Returns the current queue length.

record_debug_event(state, type, data)

@spec record_debug_event(t(), atom(), map()) :: t()

Records a debug event if debug mode is enabled.

Events are stored in a ring buffer (max 500 entries). Each event includes a monotonic timestamp for relative timing.

remove_child(state, tag)

@spec remove_child(t(), term()) :: t()

Removes a child by tag.

remove_child_by_pid(state, pid)

@spec remove_child_by_pid(t(), pid()) :: {term() | nil, t()}

Removes a child by PID.

set_debug(state, enabled)

@spec set_debug(t(), boolean()) :: t()

Enables or disables debug mode at runtime.

set_status(state, status)

@spec set_status(t(), status()) :: t()

Sets the status.

update_agent(state, agent)

@spec update_agent(
  t(),
  struct()
) :: t()

Updates the agent in state.