# `Jido.AgentServer.State`
[🔗](https://github.com/agentjido/jido/blob/v2.3.0/lib/jido/agent_server/state.ex#L1)

Internal state for AgentServer GenServer.

> #### Internal Module {: .warning}
> 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.

# `status`

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

# `t`

```elixir
@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(),
  current_runtime_context: 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()
}
```

# `add_child`

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

Adds a child to the children map.

# `attach_parent`

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

Attaches a parent reference to the runtime and agent state.

# `dequeue`

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

Dequeues the next directive for processing.

# `enqueue`

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

Enqueues a directive with its triggering signal for later execution.

# `enqueue`

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

Enqueues a directive with its triggering signal and runtime context.

# `enqueue_all`

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

Enqueues multiple directives from a single signal.

# `enqueue_all`

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

Enqueues multiple directives with runtime context from a single signal.

# `from_options`

```elixir
@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`

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

Gets a child by tag.

# `get_debug_events`

```elixir
@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`

```elixir
@spec increment_error_count(t()) :: t()
```

Increments the error count.

# `orphan_parent`

```elixir
@spec orphan_parent(t()) :: t()
```

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

# `queue_empty?`

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

Checks if the queue is empty.

# `queue_length`

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

Returns the current queue length.

# `record_debug_event`

```elixir
@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`

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

Removes a child by tag.

# `remove_child_by_pid`

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

Removes a child by PID.

# `set_debug`

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

Enables or disables debug mode at runtime.

# `set_status`

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

Sets the status.

# `update_agent`

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

Updates the agent in state.